MishkaPay.Ash.Resource (Mishka Pay v0.0.1)

Copy Markdown View Source

Mishka Pay's Ash layer as a resource extension: a host's resource, in its own domain and data layer, says what it keeps, and gets the attributes, identities, calculations, actions, code interface and webhook listener of that kind.

defmodule MyApp.Pay.Subscription do
  use Ash.Resource,
    domain: MyApp.Pay,
    data_layer: AshPostgres.DataLayer,
    extensions: [MishkaPay.Ash.Resource]

  mishka_pay do
    kind :subscription
  end

  postgres do
    table "pay_subscriptions"
    repo MyApp.Repo
  end
end

The application supervises the listeners of the domain's resources:

children = [MishkaPay.Providers.Stripe, MyApp.Pay.Keys] ++ MishkaPay.Ash.listeners(MyApp.Pay)

A host owns the tables, the domain, the policies and the notifiers. Anything the host defines itself is kept: an attribute, identity, calculation, action, relationship or code interface of the same name is never added again, so a host can change one (such as the :tenant attribute's type). A resource without its own primary key gets uuid_v7_primary_key :id, and every kind gets the primary :read and :inserted_at/:updated_at timestamps.

Every action asks the provider before its transaction starts, writes what the provider answered and, with announce? true, fires mishka_pay:<kind>:changed with the provider's struct and the row after it. The host's Ash notifiers (such as Ash.Notifier.PubSub) see the actions as usual, so an open screen can show a change live. Errors come back as Ash errors (MishkaPay.Ash.to_ash_error/1).

A host that keeps tenants apart adds Ash multitenancy on its own attribute: each action then reads the provider keys of its Ash tenant, and each listener syncs a webhook's row in the webhook's own tenant (see MishkaPay.Ash.Tenant). The inbox stays global.

:inbox

Every checked provider event is stored once and worked by an AshOban job, with retries, so a slow or failing step never loses an event and the provider gets its answer at once. The extension adds AshOban to the resource; add the mishka_pay_inbox queue to Oban and the resource's domain to AshOban.config/2 like any AshOban resource.

It holds the event's provider, tenant, id, type, object, payment, subscription, dispute, mode and time (see MishkaPay.Event), its :status (:pending, :processed, :failed), the :last_error (kept from each failed try, while it is still tried again) and when it was processed. An identity on provider and event id keeps each event once, however often the provider sends it.

  1. :receive stores it (a second delivery finds the first) and starts the :process trigger.
  2. :process fires mishka_pay:event:process (MishkaPay.Events.event_process/0) with the event, outside the database transaction, in a task that cannot take the job down. A listener that sets :failed, raises, exits or runs past config :mishka_pay, event_process_timeout: (30 seconds) leaves the event pending, its reason noted by :note_error: AshOban tries again, ten times in all.
  3. After the last try, :fail marks it :failed with the reason, for a person to look at.

The trigger's worker and scheduler are <Resource>.MishkaPayWorker and <Resource>.MishkaPayScheduler. Its listener stores each event MishkaPay.Webhook checked.

:payment

Holds the provider and its payment id, the tenant, the :status (see MishkaPay.Payment), the :amount, :amount_refunded and :currency (the :money and :money_refunded calculations give them as Money), the caller's :reference from the checkout, the buyer (:customer_id, :customer_email, :customer_name), the card (:card_brand, :card_last4), why the last try failed (:failure_code, :failure_message), whether the buyer's bank asked for it back (:disputed), when the provider made it and when it was last synced. An identity on provider and payment id keeps one row per payment.

  • :sync takes :provider, :payment_id and :tenant, reads the payment (MishkaPay.fetch_payment/3) and writes it, creating the row the first time; the tenant is kept from that first time, so a later sync never moves a payment to another tenant. Events may come twice or in any order: every sync writes the payment as it is now.
  • :start_checkout (generic) opens a checkout (MishkaPay.checkout/1) from its :checkout map and answers the MishkaPay.Checkout with the page to send the buyer to. The row comes later, from the webhook of the payment the buyer makes.
  • :refund refunds the payment through its provider (MishkaPay.refund/1), in full or by :amount, with an optional :reason and :reference, then syncs the row and keeps the MishkaPay.Refund in the record's :refund metadata. How often a payment may be refunded is the tenant's runtime setting (MishkaPay.Credentials, :refunds). When the refund went through but the payment cannot be read again, the row counts the refund itself and the next sync brings the provider's word.

Its listener syncs the payment each inbox event concerns.

:subscription

Holds the provider and its subscription id, the tenant, the :status (see MishkaPay.Subscription), the :plan (its items' names), what each period costs (:amount, :currency, with the :money calculation) and how often (:interval, :interval_count), how many (:quantity), the end of the period paid for (:current_period_end), whether it ends then (:cancel_at_period_end), :canceled_at, :trial_end, a pause (:pause_behavior, :resumes_at), the buyer, the caller's :reference, when the provider made it and when it was last synced. A subscription starts with a checkout in mode: :subscription.

:customer

Holds the provider and its customer id, the tenant, :email, :name, :phone, the caller's :reference (the host's own user id), :metadata, the :default_payment_method, when the provider made it, when it was last synced, and :deleted_at once the provider deleted it.

  • :register makes the customer at its provider (MishkaPay.create_customer/1) from :provider, :tenant, :email, :name, :phone, :reference and :metadata, on :api (:v2 or :v1) when given, else the tenant's :customer_api (at Stripe an account with the customer configuration, acct_..., by default). The same :reference and fields registered twice within a day are one customer and one row.
  • :sync takes :provider, :customer_id and :tenant (MishkaPay.fetch_customer/3). A customer the provider deleted keeps its row, with :deleted_at set.
  • :edit changes :email, :name, :phone or :metadata at the provider (MishkaPay.update_customer/1).
  • :remove deletes the customer at the provider for good (MishkaPay.delete_customer/3), as a person's erase request asks, and keeps the row with :deleted_at set (at Stripe a customer made on Accounts v2 is closed). A host that must erase its own copy too destroys the row after. A customer.deleted webhook marks the row the same way.
  • :portal (generic) takes the row's :id and a :return_url (and the provider's :configuration) and answers a MishkaPay.PortalSession: redirect the buyer to its :url, where they manage their cards, invoices and subscriptions.

:dispute

Holds the provider and its dispute id, the tenant, the payment and charge it takes back, the :amount and :currency (with the :money calculation), its :status (see MishkaPay.Dispute), the bank's :reason, when evidence is due (:evidence_due_by), whether evidence was sent (:has_evidence, :submission_count), whether the payment can still be refunded (:refundable), when the provider made it and when it was last synced.

Its listener syncs the dispute of each charge.dispute.* event.

Options

  • :kind - Required. What the resource keeps: :inbox (each checked webhook event), :payment, :subscription, :customer or :dispute; or what a site manages from its admin: :product, :price, :coupon, :promotion_code, :payment_link or :invoice (MishkaPay.Ash.Object.Spec). Valid values are :inbox, :payment, :subscription, :customer, :dispute, :product, :price, :coupon, :promotion_code, :payment_link, :invoice

  • :actions (list of atom/0) - Only these actions of the kind, besides the primary :read. Every action of the kind when left out. An :inbox needs all of its own.

  • :listen? (boolean/0) - Makes <Resource>.MishkaPayListener, the webhook listener that keeps the resource current. MishkaPay.Ash.listeners/1 lists them for the application's children. The default value is true.

  • :announce? (boolean/0) - Fires mishka_pay:<kind>:changed after each write the provider answered. The inbox announces nothing either way. The default value is true.

  • :code_interface? (boolean/0) - Defines a code interface function for each action it adds, such as MyApp.Pay.Subscription.cancel!(row, %{at: :now}). The inbox's :receive is receive_event. The default value is true.

  • :tenant_from (atom/0) - The host's own attribute that holds the tenant, such as :site_id (an attribute, or the source attribute of a belongs_to :site), for a host that keeps sites apart without Ash multitenancy. Each create action writes its tenant there too; the row's :tenant still picks the provider keys. With Ash multitenancy on that attribute, Ash fills it and this is not needed. Not for an :inbox, which stays global.

  • :belongs_to_user - A :user belongs_to relationship to the host's user resource, on :user_id, or on another attribute with {MyApp.Accounts.User, attribute: :owner_id}. A payment or a subscription gets its user from the checkout's owner, which :start_checkout takes from the actor and every sync writes again (MishkaPay.Ash.Owner); a customer's :register takes it as an input. It may be nil, for a sale with no owner.

  • :resync_after (pos_integer/0) - Hours after which a row still open at its provider is read again by an hourly AshOban trigger running :resync, in case a webhook never came: a pending or authorized payment, a subscription that has not ended, an open dispute, a draft or open bill. Runs on the inbox's queue, mishka_pay_inbox. Off unless given.

  • :keep_events_for - For an :inbox: how many days a processed event is kept before its daily :forget trigger deletes it, or :forever. Failed and pending events are always kept. The default value is 30.

MishkaPay.Ash.Resource.Info reads them back.

Summary

Functions

mishka_pay(body)

(macro)