# `MishkaPay.Events`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/events.ex#L5)

Every mishka_installer event Mishka Pay fires, in one place. Code and `use` macros call these
functions and never write an event name by hand.

| Event | Who listens | What it is for |
|---|---|---|
| `mishka_pay:providers` | each provider | says which providers are installed |
| `mishka_pay:credentials` | the host | gives the keys of a provider for one site |
| `mishka_pay:checkout:before` | the host | changes or refuses a checkout before the provider sees it |
| `mishka_pay:webhook:received` | the Ash inbox, or the host | a provider event whose signature was checked |
| `mishka_pay:event:process` | the host, or a payment resource | works one event the Ash inbox stored |
| `mishka_pay:payment:changed` | the host | a payment's state after it was synced from the provider |
| `mishka_pay:subscription:changed` | the host | a subscription's state after it was synced, cancelled or resumed |
| `mishka_pay:customer:changed` | the host | a customer after it was registered, synced or edited |
| `mishka_pay:dispute:changed` | the host | a dispute after it was synced, answered or accepted |

# `changed`

```elixir
@spec changed(atom()) :: String.t()
```

The event fired after a resource of `kind` wrote what its provider answered:
`"mishka_pay:<kind>:changed"`, with `%{<kind> => struct, record: record}`. For the payment,
subscription, customer and dispute kinds it is the event of their own function above; for the
catalog, coupons, promotion codes, payment links and bills (`MishkaPay.Ash.Object.Spec`) it is
the only one.

# `checkout_before`

```elixir
@spec checkout_before() :: String.t()
```

Hosts listen here to change or refuse a checkout before the provider sees it. A plugin gets
`%{checkout: %MishkaPay.Checkout{}, refused: nil}` and answers it with a changed `:checkout`, or
with `:refused` set to a reason. See `MishkaPay.checkout/1`.

# `credentials`

```elixir
@spec credentials() :: String.t()
```

The host listens here and answers a provider's keys for one site.

# `customer_changed`

```elixir
@spec customer_changed() :: String.t()
```

Fired after a customer resource (the `:customer` kind of `MishkaPay.Ash.Resource`) registered,
synced or edited a customer, with `%{customer: %MishkaPay.Customer{}, record: record}`. A host
listens here to link the customer to its user, or to push the change to the screens that show
it.

# `dispute_changed`

```elixir
@spec dispute_changed() :: String.t()
```

Fired after a dispute resource (the `:dispute` kind of `MishkaPay.Ash.Resource`) synced,
answered or accepted a dispute, with `%{dispute: %MishkaPay.Dispute{}, record: record}`. A host
listens here to take back what the payment gave while it is open, and give it again when it is
won.

# `event_process`

```elixir
@spec event_process() :: String.t()
```

The inbox (the `:inbox` kind of `MishkaPay.Ash.Resource`) fires this to work one stored event,
once per try. Listeners get `%{event: %MishkaPay.Event{}, failed: nil}` and answer it with
`:failed` set to a reason when the work did not finish, so the inbox tries again later.

# `payment_changed`

```elixir
@spec payment_changed() :: String.t()
```

Fired after a payment resource (the `:payment` kind of `MishkaPay.Ash.Resource`) synced a
payment from its provider, with `%{payment: %MishkaPay.Payment{}, record: record}`. A host
listens here to act on a paid or refunded payment, or to push the change to the screens that
show it.

# `providers`

```elixir
@spec providers() :: String.t()
```

Every provider listens here and adds itself to the `providers` list the event carries.

# `subscription_changed`

```elixir
@spec subscription_changed() :: String.t()
```

Fired after a subscription resource (the `:subscription` kind of `MishkaPay.Ash.Resource`)
synced, cancelled or resumed a subscription, with `%{subscription: %MishkaPay.Subscription{},
record: record}`. A host listens here to give or take access, or to push the change to the
screens that show it.

# `webhook_received`

```elixir
@spec webhook_received() :: String.t()
```

Listeners get every provider event whose signature was checked, as `%{event:
%MishkaPay.Event{}, failed: nil}`, and answer it with `:failed` set to a reason when they could
not take it, so the provider sends it again. See `MishkaPay.Webhook`.

---

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