# `MishkaPay.Ash`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/ash.ex#L6)

The Ash layer, for projects that use Ash: the `MishkaPay.Ash.Resource` extension a host adds
to resources of its own domain and data layer, and the listeners that keep them current.
Without Ash none of it compiles, and the rest of Mishka Pay works on plain structs.

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

      mishka_pay do
        kind :payment
      end
    end

A resource keeps one kind: the webhook `:inbox` (each checked event, worked by AshOban),
`:payment`, `:subscription`, `:customer` or `:dispute`, each synced from its provider. A host
owns the tables, the domain, the policies and the notifiers; the extension brings the
attributes, identities, calculations, actions, code interface and listener. `listeners/1`
lists the listeners of a domain for the application's children.

## Errors

`to_ash_error/1` turns a `MishkaPay.Errors` error into Ash's own classes, so a form shows it on
its field: an `:invalid` error becomes `Ash.Error.Changes.InvalidArgument`s at their fields
(for a nested input such as the customer of a checkout, at the inner field that failed, such
as `:email`), anything else an `Ash.Error.Unknown.UnknownError`. The actions here return them.
`message/1` gives their plain words; `provider_error/1` finds the provider's own error inside,
with its `:request_id` for the provider's support.

# `listeners`

```elixir
@spec listeners(Ash.Domain.t()) :: [module()]
```

The webhook listeners of a domain's resources (`listen? true` in `MishkaPay.Ash.Resource`), in
the domain's order, for the application's children:

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

# `message`

```elixir
@spec message(term()) :: String.t()
```

The plain words of an error, for a person or a log: the error's own message, without the
breadcrumbs and stack traces a Splode class adds; a class gives its errors' words, each its own
sentence.

# `provider_error`

```elixir
@spec provider_error(term()) :: Exception.t() | nil
```

The provider's own error inside `error`: a `MishkaPay.Errors.Rejected` or
`MishkaPay.Errors.Declined`, given as it is, inside a `MishkaPay.Errors` class, or inside the
Ash error an action returned (or `to_ash_error/1`'s list). Its `:request_id` and `:doc_url` are for the provider's support
and the log, never for the person's message. `nil` when the provider gave no error.

    {:error, error} = Ash.create(MyApp.Pay.Payment, attrs, action: :sync)

    case MishkaPay.Ash.provider_error(error) do
      %{request_id: id} when is_binary(id) -> Logger.warning("Stripe request #{id} failed")
      _none -> :ok
    end

# `stale?`

```elixir
@spec stale?(term()) :: boolean()
```

Whether a `:sync` was skipped because the row holds a newer read of the provider: the sync
succeeded in effect, since what it would write is already older than what is kept.

# `subscribed?`

```elixir
@spec subscribed?(Ash.Resource.t(), term(), keyword()) :: boolean()
```

Whether `user` has a subscription in `resource` that gives access now: see
`MishkaPay.Ash.Subscribed`, which is also the policy check.

    MishkaPay.Ash.subscribed?(MyApp.Pay.Subscription, current_user, tenant: site.id)

# `to_ash_error`

```elixir
@spec to_ash_error(Exception.t()) :: [Exception.t()]
```

A `MishkaPay.Errors` error (or any Splode error) as Ash errors, one per inner error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
