# `AshHooks.Catalog`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/catalog.ex#L1)

The event catalog read surface: the `outbound` DSL's declared metadata
(each event type's description, payload schema, and version), read back
for event pickers, doc generation, and payload-version negotiation.

<!-- not-run: This declaration fragment requires host schema and payload builder modules. -->

    webhooks do
      outbound :order_paid do
        description "An order reached the paid state."
        payload_schema MyApp.Schemas.OrderPaid
        version 2
        # endpoints pinning 1 receive this builder's bytes instead:
        payload_versions %{1 => {MyApp.Payloads, :order_paid_v1}}
      end
    end

`entries/1` lists a resource's declared catalog; `entry/2` reads one.
`payload/3` resolves the bytes a dispatch sends to one endpoint: the
dispatch payload when the endpoint has no pin or pinned the declaration's
current `version`, otherwise the matching `payload_versions` builder's
bytes.

A pin on a version the declaration does not carry fails that endpoint
closed (`{:error, :unknown_pinned_version}`) BEFORE any delivery row is
written, as does a variant builder that fails or returns a non-binary
(`{:error, :variant_failed}`; a crash is contained the same way).

# `entry`

```elixir
@type entry() :: %{
  name: atom(),
  description: String.t() | nil,
  payload_schema: term() | nil,
  example: String.t() | nil,
  version: pos_integer(),
  payload_versions: %{optional(pos_integer()) =&gt; {module(), atom()}} | nil
}
```

One catalog entry: the declared metadata for an outbound event type.

# `entries`

```elixir
@spec entries(module()) :: {:ok, [entry()]}
```

The resource's declared outbound catalog, in declaration order: the
event picker's source. Compose across your emitting resources yourself;
each entry carries everything a doc generator needs.

# `entry`

```elixir
@spec entry(module(), atom()) :: {:ok, entry()} | :error
```

One declared outbound entry, or `:error` when the resource declares no
such event type.

# `payload`

```elixir
@spec payload(AshHooks.Event.t(), AshHooks.Outbound.t(), struct()) ::
  {:ok, binary()} | {:error, :unknown_pinned_version | :variant_failed}
```

Returns `{:ok, bytes}` for the endpoint's declared pinned variant.
Endpoints with no pin, a pin to the current version, or no pinning column
receive the event's original bytes. An unknown pinned version returns
`{:error, :unknown_pinned_version}`; a failing or invalid variant builder
returns `{:error, :variant_failed}`.

---

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