ash_dispatch

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.6.9] - 2026-08-24

### Fixed

- **`:send_now` and `:reopen` accept nothing now.** Neither declared an
  `accept` list, so both inherited the resource default: **thirty attributes**,
  including `recipient`, `subject`, `body_html` and `content`.

  "Send this letter again" could therefore be called as "send a different
  letter to a different address" — and because the same call rewrites the
  receipt, nothing in the record would say otherwise afterwards. The receipt is
  the audit trail; an action that edits it while sending it destroys the only
  evidence of what was sent.

  A resend has no inputs. It re-sends what is already there.

  **Breaking if you were passing attributes to `:send_now`** — those calls will
  now fail with `NoSuchInput` instead of silently editing the outgoing mail.
  Change the receipt first with an ordinary update if that was deliberate, then
  send. `:reopen` shipped in 0.6.8 and cannot have dependents yet.

## [0.6.8] - 2026-08-23

### Added

- **`:reopen` — a way out of `:failed_permanent`.** The state was a dead end:
  no transition led out of it, `:send_now` refused it explicitly, and
  `SendEmail` treats it as terminal and completes any job for it as a success.
  A receipt that ended there could never be sent again — not even by a person
  who had just fixed the reason it failed. The only remaining move was to look
  at it.

  That is the wrong shape for the state that a permanent failure lands in. It
  is reached in ordinary operation (a provider outage, a rate limit, a
  mailbox that was full for a day), and every one of those reasons goes away
  on its own.

  `:reopen` moves the receipt back to `:scheduled` and enqueues a job, so the
  existing send path runs unchanged. Three deliberate choices:

  - It starts **only** from `:failed_permanent`. A receipt that actually
    reached its recipient can never be re-sent through it.
  - It is gated by the same `send_now_authorizer` as `:send_now`, because it
    sends real mail.
  - It **resets** `retry_count` rather than incrementing it. The counter
    exists to stop the automatic sweep from looping forever; a human deciding
    to try again is not that loop, and leaving the counter at its ceiling
    would let the sweep abandon the attempt the moment it failed once.

  Consumers that want the old behaviour need do nothing: the action has to be
  called to have an effect, and nothing in the library calls it.

## [0.6.7] - 2026-08-23

### Added

- **The resource bases accept `notifiers:`.** They already accepted
  `extensions:`, and the omission was arbitrary — a notifier is how you
  observe what a resource did without touching how it does it.

  Without it, a consumer wanting to react to receipt transitions has to reach
  for a change instead, and a non-atomic change forces `require_atomic? false`
  onto **every update action in the base** — actions the consumer cannot edit.
  That is a compile error with no way out from the consuming app.

  Two lines in each of `DeliveryReceipt.Base` and `Notification.Base`, both
  defaulting to `[]`, so nothing changes for anyone who does not pass the
  option.

## [0.6.6] - 2026-08-23

### Fixed

- **A receipt can no longer strand in `:scheduled` unnoticed.** That status
  promises a job is coming; nothing ever checked whether one was. A receipt
  whose job died, was pruned, or never enqueued sat there permanently — the
  retry sweep queries `status == :failed`, so it never looked, and no surface
  counted it.

  One production deployment carried **17 such receipts across six months**:
  four order confirmations (two to a customer, not staff), four reseller
  applications and nine product announcements. All showed a provider 429, all
  were moved to `:scheduled` by a retry, none were seen again. The underlying
  race was fixed in 0.5.6; what remained was that nothing recovers the
  receipts already stranded, or any stranded by a future crash or deploy.

  `RetryFailedDeliveries` now sweeps `:scheduled` before its ordinary pass,
  with three outcomes (see `AshDispatch.Workers.Stranded`):

  | age | outcome |
  |---|---|
  | under the grace period | left alone — `:scheduled` is a legitimate transient state |
  | past grace, under the ceiling | moved to `:failed`, so the existing retry machinery takes over |
  | past the ceiling | `:failed_permanent` with a reason — **never sent** |

  The ceiling exists because delivering a January order confirmation in
  August is worse than silence: the recipient has to work out whether
  something went wrong. The invisible debt is the defect, not the unsent
  mail.

  Configurable via `:stranded_stuck_after_minutes` (default 30) and
  `:stranded_stale_after_hours` (default 24). A contradictory configuration
  where the ceiling falls below the grace period resolves to leaving receipts
  alone — never touching one that may still be in flight is the stronger
  safety property, since a double-sent mail cannot be recalled.

  **This acts on existing data on first run.** A consumer holding stranded
  receipts it still wants delivered should raise
  `:stranded_stale_after_hours` before upgrading.

  The decision function is covered by unit tests; the sweep's database
  plumbing is not, for the harness reasons recorded under 0.6.5.

## [0.6.5] - 2026-08-21

### Added

- **The recipient is in the context.** `do_build_receipt_content/4` runs once
  per recipient and has always had it in scope, but nothing downstream could
  see it: `prepare_template_assigns/2` receives `(context, channel)`, and
  template assigns were built from that return value plus
  `Context.template_assigns/1`. Greeting someone by name was impossible
  without reaching outside the render path.

  It now goes into `context.variables`, which is the one place that reaches
  **both** consumers — `Context.template_assigns/1` merges variables into the
  assigns a template sees, and the callback can read
  `context.variables[:recipient]` to PRECOMPUTE per-recipient values.

  That second half is the point. Exposing it only in the final assigns would
  have forced consumers to branch inside templates, which is exactly what a
  precomputed-assigns convention exists to prevent.

  `Map.put_new/3`, so an event that already resolves a richer recipient shape
  keeps its own. Purely additive: a context key nothing reads changes no
  output, and an event that never mentions the recipient renders
  byte-for-byte as before. `subject/2` still receives no recipient — a
  personalised subject line needs a callback signature change and is not part
  of this release.

  **Not covered by a test in this repo.** The suite has no harness for a full
  dispatch-to-receipt flow: no application-level `recipient_fields`, no
  configured `delivery_receipt_resource`, and further gaps behind those. An
  attempt to build one was abandoned as larger than the change it would
  guard. The behaviour is exercised end-to-end by magasin's mailing
  byte-identity test, which compares a preview rendered for a chosen
  recipient against what that recipient actually receives.

## [0.6.4] - 2026-08-18

Bug fixes in the delivery path, plus additive facades over machinery that
already existed. No behaviour changes for any existing consumer: every new
option defaults to exactly what the previous releases did.

### Fixed
- **User preferences are evaluated per receipt, not per context user.**
  The `:email` and `:in_app` transports asked
  `UserPreference.allows?(context, channel, event_config)` — a question
  about the user on the *context*, i.e. the event's subject. But a receipt
  is one recipient, so on any fan-out (one event, N receipts) that single
  verdict was applied to all N: one customer's opt-out silenced the whole
  send, and one customer's opt-in delivered to people who had opted out.
  Consumers implementing `user_allows?/4` never saw more than one user id
  per event and had no way to notice.

  Both transports now call the new `allows_receipt?/4`, which reads
  `receipt.user_id`. Receipts without a user id (external addresses,
  webhook targets) keep delivering unasked.

- **`{:at, %DateTime{}}` channel times are honored.** `normalize_time/1`
  accepted them, the `time` type documented them and
  `Channel.calculate_delay/1` knew how to compute them — but the email
  transport matched only `{:in, seconds}` and let everything else fall
  into a catch-all `0`, so an absolute-time channel sent IMMEDIATELY,
  silently (and `calculate_delay/1` had zero call sites). The delay is now
  computed from the datetime, clamped at 0 so a past time means "now".
  `{:in, seconds}` is unchanged.

### Added
- **`AshDispatch.preview/3`** — the preview engine behind ManualTrigger,
  exposed as a plain function. Renders subject/HTML/text for each channel
  of an event without delivering:

      AshDispatch.preview("orders.created", %{order_id: order.id},
        transport: :email, audience: :user)
      #=> {:ok, [%{subject: …, html_body: …, text_body: …, recipient: …}]}

  Options: `:audience`, `:transport`, `:actor`, `:recipient_email` (which
  only changes the displayed recipient — preview never sends).

- **`AshDispatch.UserPreference.allows_user?/4`** — the preference
  predicate, extracted from `allows?/3` and callable anywhere a user id is
  known: `allows_user?(user_id, event_id, transport, opts)`. This is how an
  admin screen's "342 recipients · 38 have opted out" stays in agreement
  with what the send path will do. A `nil` user id returns `true`.
  `allows?/3` keeps its behaviour and delegates to it.

- **`AshDispatch.UserPreference.allows_receipt?/4`** — the same question
  asked about a receipt's own recipient. This is the gate the transports run.

- **`config :ash_dispatch, preference_gated_audiences`** — which audiences
  have their recipients' preferences consulted. Defaults to `[:user]`,
  exactly the audience set every earlier release gated; every app-defined
  audience (`:customers`, `:watchers`, permission-scoped admin audiences)
  bypassed preferences entirely and still does until opted in:

      config :ash_dispatch, preference_gated_audiences: [:user, :customers]

  Keep admin/team/system audiences out of it — an operator must not be able
  to silence an operational alert by unticking a marketing box.

### Deprecated
- **Channel time `{:window, map}`.** Business-hours windows were never
  implemented; the spec has always delivered immediately. It still does —
  removing it would break consumers that declared one — but the first
  `{:window, …}` channel after boot now logs a deprecation warning. Use
  `{:in, seconds}` or `{:at, %DateTime{}}`. Removal is deliberately
  postponed.

### Docs
- **"Pattern 3: Frequency-Based Preferences" rewritten.** It instructed a
  side effect (`queue_for_digest/3`) inside `user_allows?/4` followed by
  `false` — i.e. a notification silently moved into a table nobody
  delivers from, behind a receipt claiming the user opted out. The
  predicate stays a predicate; digest mode is modelled as "no individual
  delivery" with the digest job owned by the app.

### Planned (names reserved, nothing shipped)
- **Per-recipient digests.** Reserved: channel time `{:digest, window}`,
  `AshDispatch.Resources.DigestEntry.Base`,
  `AshDispatch.Workers.FlushDigests`, and a `user_digest_mode/2` callback
  on the preference behaviour. Two properties are already fixed: the
  digest unit is per recipient (one body per user, not one body for
  everyone), and a digest still produces a `DeliveryReceipt` — a digest is
  a delivery, not a silence. See the User Preferences topic.

## [0.6.3] - 2026-08-17

### Added
- **`DeliveryReceipt.Base` `:list_all` takes an `audiences` list argument**
  alongside the existing single `audience` — apps with scoped audience
  families (e.g. permission-scoped admin audiences) can catch the whole
  family in one filter: `audiences: [:admin, :order_admins, …]`.

  (Written for 0.6.2, but the publish workflow triggers on every main push
  and the version bump sat in the first commit of a two-commit stack — so
  hex 0.6.2 was built mid-stack and never got this argument. Lesson: bump
  the version in the LAST commit of a stack, or push the stack atomically.)

## [0.6.2] - 2026-08-17

### Fixed
- **`ManualTrigger.Base` no longer hardcodes the audience/transport
  universe.** The `:preview` arguments and the `:trigger`-path attributes
  constrained `audience` to `one_of: [:user, :admin]` and `transport` to
  `one_of: [:email, :in_app]` — silently rejecting every app-defined
  audience (`:customers`, `:watchers`, permission-scoped admin audiences)
  and every transport added since. Both are now validated at runtime
  against the consuming app's `config :ash_dispatch, :audiences` and
  `Transport.Registry.receipted_atoms/0`, with the allowed universe listed
  in the error message. Same disease as the receipt-constraint drift fixed
  in 0.6.0; a structural test now pins that no hardcoded list returns.

## [0.6.1] - 2026-08-17

### Fixed
- **A registered transport no longer crashes the whole dispatch.**
  `Dispatcher.build_inline_content/4` had a `case channel.transport`
  with no catch-all, so the `:push` transport added in 0.6.0 raised
  `CaseClauseError` for every event carrying a `:push` channel — taking
  down the sibling channels on the same event with it. The case now has
  a catch-all (a transport without inline content gets `%{}` and still
  delivers), and `:push` has its own branch producing `title`,
  `message` and `action_url`.

  Same drift as the receipt constraint fixed in 0.6.0: the
  `AshDispatch.Transport` behaviour promises "one new file + one
  registry entry", and two places had not got the memo. A structural
  test now pins the catch-all.

## [0.6.0] - 2026-08-17

Adds a Web Push transport and removes the hardcoded transport lists that
made adding one a multi-file hunt.

### Added
- **`:push` transport** (`AshDispatch.Transports.Push`) — Web Push to the
  browser. Same shape as `:sms`: ash_dispatch owns routing and the
  delivery receipt, the consumer supplies a backend module implementing
  the new `AshDispatch.PushBackend` behaviour. Configure with
  `config :ash_dispatch, :push_backend, MyApp.Push`. With no backend
  configured the receipt is marked `:skipped` with
  `error_message: "transport_not_implemented"`, so an app can declare
  `:push` channels before the backend exists.

  VAPID keys, RFC 8291 encryption and the per-endpoint POST stay in the
  consuming app — they are deployment concerns (key material, egress,
  retry budget), not library concerns. `AshDispatch.PushBackend`'s docs
  spell out the contract, including pruning subscriptions on `404`/`410`
  and treating `429`/`5xx` as retryable.

  Declare push channels as `optional: true`: a user who never granted
  notification permission is a soft-skip, not a delivery failure.

- **`AshDispatch.Transport.Registry.receipted_atoms/0`** — the transport
  atoms that can appear on a `DeliveryReceipt` (registry minus the
  lightweight `:broadcast`/`:oban`).

### Fixed
- **The receipt `transport` constraint no longer drifts.** It was
  hardcoded in two places that had already gone out of sync:
  `AshDispatch.Setup` allowed `[:email, :in_app, :discord, :sms,
  :webhook]` while `DeliveryReceipt.Base` allowed those plus `:slack`.
  A `:slack` channel therefore produced a receipt the `Setup`-generated
  resource rejected. Both now derive from `receipted_atoms/0`, so
  registering a transport is once again "one new file + one registry
  entry" as `AshDispatch.Transport`'s docs promise.

### Compatibility
No migration required. The receipt constraint only widens, and consumers
that never declared a `:push` channel are unaffected.

## [0.5.6] - 2026-08-12

Security-focused release absorbing a consumer-proven patch set (policies and
retry semantics that one production app had carried as local vendor patches),
plus inline-image email support.

### Security
- **`Notification.Base` now ships `Ash.Policy.Authorizer` with per-user
  policies**: read and update only your own notifications,
  `mark_all_as_read`'s `user_id` argument must match the actor, and
  create/destroy are system-only. Without an authorizer, `authorize?: true`
  was a no-op — any signed-in user could read every other user's
  notification feed (proven in one production deployment) and mark other
  users' feeds as read. The in-app transport now creates notifications with
  `authorize?: false` at both call sites (initial delivery and retry).
- **`ManualTrigger.Base` is now fail-closed**: it declares the authorizer
  with no base policies, so everything is forbidden until the consuming app
  opens access with its own `policies` block (typically a `bypass` on its
  admin check). Previously any signed-in user could preview arbitrary
  records as email bodies and trigger real outbound email. Note for
  integrators: the base deliberately does NOT declare a
  `forbid_if always()` policy — base policies compile before the
  consumer's, and a later consumer `bypass` cannot re-open an earlier
  forbid.
- **`DeliveryReceipt.Base` write policies**: the blanket
  `bypass … authorize_if always()` on create/update/destroy let any
  authenticated actor mutate receipts — including `:retry`, which re-sends
  real email. External writes are now gated on the same configured
  permission as reads (`:manage_delivery_receipts` via the configured
  `permission_checker`). All library-internal writes already run with
  `authorize?: false` and are unaffected.
- **`EmailEvent` reads forbade everyone, super admins included** — its two
  non-bypass policies were AND-ed. The super-admin policy is now a `bypass`.

### Added
- **Inline (CID) email images**: `attachments/2` attachment maps accept
  optional `type: :inline | :attachment` and `cid: String.t()`. Inline
  attachments flow through the Oban job args and reach the Swoosh backend as
  `type: :inline` with `cid` defaulting to the filename — referenced from
  HTML as `<img src="cid:logo.png">`, they render without the recipient
  approving remote images. Plain attachments are byte-for-byte unaffected,
  and in-flight jobs enqueued by older versions decode unchanged.
- **App-wide default email attachments**: `config :ash_dispatch,
  default_email_attachments: {MyApp.EmailAssets, :defaults, []}` (MFA or
  zero-arity fun returning attachment maps) is merged ahead of each event's
  own `attachments/2` on every outgoing email. Built for the inline-logo
  case: one config line embeds a `type: :inline` logo referenced from a
  shared layout as `<img src="cid:logo.png">`. Resolution failures log and
  degrade to no attachments — branding must never block delivery.
- **`should_send?/2` is now actually invoked by the send path** (per
  channel, on both the direct-dispatch and notifier paths, including the
  deduplication path). The callback was declared on the behaviour — and
  implemented by consumer events as a last-moment guard — but never called,
  so those guards silently never ran. A guard that raises logs a warning and
  sends (dispatch is never aborted by a guard).

### Fixed
- **Retry race that silently dropped mail**: `RetryFailedDeliveries` now
  moves the receipt to `:scheduled` BEFORE enqueueing the worker, and puts
  it back to `:failed` (or `:failed_permanent` once retries are spent) if
  the enqueue fails; `mark_sending` additionally accepts `:failed` as a
  source state, which also makes Oban's own backoff retries effective.
  Previously the worker regularly ran while the receipt was still `:failed`,
  treated it as a duplicate job, returned `:ok`, and the receipt stranded on
  `:scheduled` where no retry path ever saw it again — in one production
  deployment this silently dropped 17 emails over eight months.
- `mark_failed` no longer increments `retry_count` (a failure is not a
  retry). With both `mark_failed` and `:retry` incrementing, every
  failed-and-retried cycle burned the retry budget twice as fast as
  `:max_retries` promised.
- Provider webhook events no longer overwrite each other:
  `record_webhook_event` merges into the existing `provider_response`, and
  the Resend handler namespaces each payload under its event type
  (`"email.delivered" => %{…}`), so the full delivery timeline — and the
  original send response with the provider id — survives.
- The email preference check now uses the category the event module actually
  declares (`category` in the dispatch DSL), falling back to the old
  event-id string munging. Munged ids only matched preference fields by
  coincidence, silently disabling opt-out toggles for events whose id
  didn't mirror a preference column.
- Retried emails no longer lose their attachments: retry/send-now jobs are
  built with `SendEmail.new_for_receipt/1`, which carries the original job's
  attachment args forward (attachments are resolved once, at first enqueue,
  and exist only in job args — a bare `%{receipt_id: _}` retry job resent
  the mail without them, breaking inline images).

### Fixed (0.2.x parity regressions)
- Restored the `authorize?: false` counter-scoping guard in
  `ResourceIntrospection.resolve_user_id_path_for_scoping/2` (present in
  0.2.x, lost in the notifier-era refactor): a counter with
  `authorize?: false` and no explicit `scope`/`user_id_path` is system-wide
  again, instead of silently auto-deriving a user scope and reading 0 for
  admin badges. Both callers already passed the option; it was ignored.
- `CounterLoader` audience matching now fails CLOSED for audiences
  configured as MFA/function resolvers: they cannot be evaluated against a
  single user, and the old fallthrough parsed them as an empty filter —
  "matches everyone" — broadcasting admin counters to every signed-in user.
  Counter audiences should use the declarative list form.
- All library-internal receipt/notification state writes now pass
  `authorize?: false` explicitly (receipt_status, every transport, the
  dispatcher's unknown-transport skip). They previously relied on
  `DeliveryReceipt.Base`'s blanket write bypass, which this release removed
  — without this, the tightened policies broke email/in-app delivery
  end-to-end for any consumer.

### Upgrade notes
- **`#{@var}` template interpolation is no longer converted.** The 0.2.x
  preprocessor rewrote `#{@var}` in mail templates to EEx; the current
  resolver deliberately skips `#{` (it can be legitimate Elixir
  interpolation inside a HEEx attribute expression). Body-position
  `#{@var}` now renders as literal text — migrate templates to `{@var}`
  (also auto-escaped since 0.4.6).
- Apps using `ManualTrigger.Base` MUST add a `policies` block to their
  trigger resource or the admin UI built on it will see empty lists:

      policies do
        bypass always() do
          authorize_if MyApp.PolicyHelpers.AdminCheck
        end
      end

- Apps exposing `DeliveryReceipt` actions (`:retry`, `:send_now`, reads)
  to their frontend need a `permission_checker` configured whose
  `:manage_delivery_receipts` permission matches their admin model.
- In-app retries now consume retry budget (`retry_count` increments on the
  synchronous in-app retry path as well).

## [0.5.5] - 2026-08-12

### Fixed
- `SendWebhook` pattern-matched on the `%Req.Response{}` struct although
  `req` is an optional dependency — any app without req failed to COMPILE
  the library in prod builds (dev builds often hid it via a transitive
  dev-only req). Now matches plain maps; the runtime `Req.post/2` call is
  unaffected and still requires req only when the webhook transport is
  actually used.

### Fixed
- The i18n catalog generator (`mix ash_dispatch.gen`) registered msgids
  under a hardcoded `"notifications"` domain while the Dispatcher looks
  them up via the configurable `:gettext_domain` — for any app setting
  that config, every dispatch translation silently missed. The generator
  now uses `Config.gettext_domain/0`.

## [0.5.4] - 2026-08-11

0.5.2 was never published — its changes ship here. (An earlier changelog
revision folded them into 0.5.3; in fact 0.5.3 had already been published
2026-07-14 with the attachment work alone, so they ship as 0.5.4.)

### Added
- **Resend webhook signature verification**:
  `AshDispatch.WebhookHandlers.Resend.verify/3` — Svix HMAC over
  `svix-id.svix-timestamp.raw_body` with constant-time comparison,
  multi-signature support (secret rotation) and a replay window. Ported
  from a client app, where it was the only verified endpoint in the
  fleet; siteflow/magasin expose unauthenticated receipt mutation today.
- **Sensitive-content scrubbing**:
  `AshDispatch.Workers.ScrubSensitiveContent` (cron) blanks `body_text`/
  `body_html` of receipts whose event declares
  `metadata: [sensitive_content: true]` once they are older than
  `config :ash_dispatch, :scrub_after_hours` (default 24). Receipts in
  `:failed` are left for the retry path first. Replaces app-level scrub
  workers .
- **`Dispatcher.dispatch_safely/3`** — rescue-and-log wrapper for
  fire-and-forget dispatch from code paths that must never be felled by a
  notification failure. mosis carries two hand-rolled copies of this
  (`Mosis.AshDispatch.dispatch_safely`, `AshDispatchAdapters.BestEffort`);
  they can be retired on upgrade.
- `BACKLOG.md`: design-level findings from the 2026-08-10 cross-app
  integration audit (retry semantics, ManualTrigger trigger no-op arguments,
  dead surface).
- CI: `ci.yml` runs format check + tests on every PR and push to main;
  `publish.yml` gained a version guard so re-pushing an already-published
  version no longer fails the pipeline.

### Changed
- Widened optional `hackney` constraint to `~> 1.9 or ~> 4.0` so the library
  coexists with dependencies that require hackney 4.x (e.g. stripity_stripe
  3.x). hackney is only used when Swoosh is configured with a hackney-based
  API client; projects using other adapters are unaffected.
- Downgraded the per-dispatch "No :user_module configured" log line from
  warning to debug. An app without a user resource is a valid configuration
  (custom recipient resolvers handle non-user recipients); the two
  recipient-resolution failure diagnostics keep their warning level.
- `SendEmail` with no `:email_backend` configured now marks the receipt
  `:skipped` ("no email_backend configured") with a warning, instead of
  logging `[MOCK]` and marking it `:sent` — a receipt claiming a delivery
  that never happened.
- `ValidateCanRetry` (the receipt `:retry` action) now reads
  `config :ash_dispatch, :max_retries` (default 5) instead of a hardcoded 5
  that silently overrode the same knob `RetryFailedDeliveries` honors.

### Deprecated
- `AshDispatch.Resources.ManualTrigger` (the legacy non-Base variant): its
  `:trigger` action fails `Dispatcher.dispatch/3`'s map guard with a
  `FunctionClauseError`. Use `AshDispatch.Resources.ManualTrigger.Base`.
  Removal planned for 0.6.

## [0.5.3] - 2026-07-14

### Added
- End-to-end email attachment support: events can implement
  `attachments/2`; attachments flow through the Oban job (base64) into the
  Swoosh backend (#5).

## [0.5.1] - 2026-06-29

Documentation-only release. Rebrands the project for its public launch.

### Changed

- **README rebranded for the `0.5` public launch.** Hex.pm + HexDocs
  badges, a prominent "experimental, API may change before 1.0" caveat,
  install instructions bumped to `~> 0.5`, and reworked Project Status /
  Contributing sections (dropping the pre-launch "being extracted / will
  be published" framing).
- Generic `MyApp.*` module names in the manual-dispatch tutorial
  (previously referenced an internal application name), and issue links
  point at the public repo.
- Corrected the dispatch-flow legend in *What is AshDispatch?* — email
  and webhook delivery run on real Oban workers; the mock is only the
  default email backend.

## [0.5.0] - 2026-06-29

First public release on hex.pm since `0.1.4` — brings the public package
up to current. Headline additions are two new transports and a formal
`Transport` behaviour.

### Added

- **`:oban` transport.** Dispatch an event straight to an Oban worker,
  eliminating the manual dispatch+enqueue dance. Wired via
  `use AshDispatch.Event, transports: [oban: [...]]`.
  - **Compile-time validation**: an `:oban` channel now requires
    `:oban_worker` metadata (previously a soft runtime warning + a
    `:skipped` receipt that left operators staring at an empty queue).
  - **Dispatch-layer enable-gate** via a pluggable
    `config :ash_dispatch, :gate_check_module`. A disabled gate skips
    the enqueue entirely (emitting `[:ash_dispatch, :oban, :gated_disabled]`
    telemetry) instead of burning queue capacity on a no-op worker.
    No gate configured → always enabled; a raising gate → defaults to
    enabled (over-fire is safer than a silent drop) and logs a warning.

- **`:custom_topic` transport.** A lightweight per-record PubSub
  broadcaster (`AshDispatch.Event.CustomTopic`) for fire-and-forget
  broadcasts that need no recipients, content, or `DeliveryReceipt`s.
  Topic accepts a string or a `{Module, :function}` MFA for per-record
  routing. Generates overridable `topic/0,1`, `event_name/0`,
  `safe_broadcast/1,2` helpers wrapping `Phoenix.PubSub.broadcast/3`
  with rescue + log + `[:ash_dispatch, :custom_topic, :broadcast_failure]`
  telemetry. The heavyweight Spark DSL path is unchanged when no
  `:transports` option is passed.

- **`AshDispatch.Transport` behaviour + Registry.** Dispatcher routing
  is now derived from a registry of transports rather than hardcoded,
  giving new transports a single integration point.

- **Module-typed `dispatch/3` overload** on `AshDispatch.Dispatcher`,
  resolving `event_id` via the `EventRegistry`.

- **`AshDispatch.Naming.wire_event_name/1`**, consolidating the
  dotted-split-and-take-last logic previously private to the Broadcast
  transport so other transports can reuse it.

### Fixed

- **`RecipientResolver` never aborts the parent operation.** Dispatch is
  a side-channel: recipient resolution now wraps its body in
  `try/rescue`, so a bad `user_resource` config or a raise from an
  auto-loaded calculation (e.g. an unstarted Cloak vault) degrades to
  `[]` recipients + a structured warning instead of bubbling an
  exception up and aborting the caller's transaction.

- **Cleared all Elixir 1.20 compiler warnings** (unused requires,
  unreachable `defp` clauses, bitstring `size(...)` pins, always-truthy
  guards). Behavior-preserving.

## [0.4.8] - 2026-05-14

### Fixed

- **Process-local Gettext locale leak after dispatch.** `Gettext.put_locale/2`
  is process-local. `apply_recipient_locale/3` mutates the running
  process's locale so per-recipient renders pick up the right language.
  Until now, after `build_receipt_content/4` returned, the process was
  left with **the last recipient's locale** — which meant a worker that
  dispatched event A to a `locale="en"` user and then ran any `t()`
  call for its own purposes (audit logging, custom emails, follow-up
  derivations) would see the leaked "en" locale instead of the locale
  the worker started with.

  Fix: `build_receipt_content/4` now captures `current_locale/0` before
  applying the recipient locale and restores it in an `after` block. Each
  receipt build is fully isolated; the caller's process locale is
  unchanged on return.

  Caught via crash-hunt regression: `t()` between two dispatches now
  renders correctly against the worker's surrounding locale.

## [0.4.7] - 2026-05-14

This release unlocks **DSL-only locale-aware events**. Combined with
0.4.6's HEEx auto-escape, an entire event can live in
`dispatch do … end` blocks with just `prepare_template_assigns/2`
left in the event module for derived assigns.

### Added

- **Configurable Gettext domain** for DSL content lookups
  (`AshDispatch.Config.gettext_domain/0`, default `"notifications"`).
  Apps with existing `default.po` setups can do
  `config :ash_dispatch, :gettext_domain, "default"` to share one
  translation bundle across the codebase.

- **Top-level `template_assigns` interpolation in `VariableInterpolator`.**
  When a variable doesn't match a field on the main resource, the
  interpolator now falls back to top-level keys in `data`. Lets
  `prepare_template_assigns/2`-returned values be addressed directly as
  `{{my_computed_var}}` instead of awkwardly stuffing them onto the
  resource struct.

### Fixed

- **`translate_content/2` no longer overwrites recipient locale.**
  Previously, when `context.locale` was nil the function unconditionally
  reset Gettext to `"en"` — silently undoing the per-recipient locale
  that `apply_recipient_locale/3` had just set. Now only overrides on
  explicit non-empty locale; trusts the process-level locale otherwise.

- **`action_label` now goes through `interpolate/2`** for `:in_app`
  channels — parity with `title`/`message`/`subject` so DSL-declared
  labels participate in both `{{var}}` substitution AND the gettext
  translation pipeline. Previously rendered raw.

## [0.4.6] - 2026-05-13

### Security

- **Auto-escape `{@var}` expansions in HTML email templates.**
  `TemplateResolver.render_template_content/4` previously rewrote
  HEEx-style `{@var}` markers to plain EEx `<%= @var %>` and evaluated
  the result via `EEx.eval_string/2`, which does NOT HTML-escape
  interpolated values. Any user-controlled string flowing through
  `prepare_template_assigns/2` (lead name, contract recipient, customer
  comment, etc.) landed raw in the rendered email — a real markup
  injection vector.

  The preprocessor now wraps every auto-converted `{@var}` expansion in
  `AshDispatch.SafeRender.escape/1` for `format: :html` so escape is the
  default, matching Phoenix HEEx semantics. Text formats are unaffected
  — `email.text.eex` and similar still emit `<%= @var %>` plain
  (text/plain has no HTML semantics).

  **Migration:** if your templates intentionally embed safe pre-rendered
  HTML, mark those expressions explicitly:

      <p>{raw(@trusted_block)}</p>
      <!-- or, fully qualified -->
      <p>{AshDispatch.SafeRender.raw(@trusted_block)}</p>

  `{:safe, iodata}` tuples (Phoenix.HTML's standard "already escaped"
  marker) also pass through `escape/1` unchanged, so existing
  Phoenix.HTML interop keeps working.

### Added

- `AshDispatch.SafeRender` module (`escape/1` + `raw/1`).

## [0.4.5] - 2026-05-13

### Added
- **Per-recipient locale resolution.** When a channel resolves to a
  multi-recipient audience (e.g. seller + admin), each recipient's
  rendered notification content now follows their own `recipient.locale`
  field. The resolution priority is:

      1. channel.locale       (static override)
      2. channel.locale_from  (channel-level dynamic on primary record)
      3. recipient.locale     (NEW — auto-detected when recipient struct has it)
      4. event/resource locale_from + auto-detected visitor_locale/locale
      5. context.locale + Config.default_locale()

  This makes multilingual sends — e.g. a customer-facing email to a
  Swedish lead, plus an internal email to an English admin — render in
  each recipient's preferred language from one event dispatch, with no
  per-recipient code in the calling worker. The recipient struct just
  needs a `:locale` field (typically a `User` record); audiences that
  expose user records via `RecipientResolver.to_recipient/1` get this
  for free.

### Changed
- `Dispatcher.build_receipt_content/4` now threads `recipient` into
  `build_module_content`, `build_inline_content`, and
  `render_inline_email_templates`. Subject + html/text bodies are now
  rendered per recipient with the correct locale, instead of once per
  channel. Pre-render side: the resolved locale is also stamped on the
  receipt for analytics/traceability.
- `Gettext.put_locale/2` is now invoked automatically inside
  `build_receipt_content` (via the new `apply_recipient_locale/3`
  helper) when `:gettext_backend` is configured. Consumer code that
  was previously calling `Gettext.put_locale` itself before
  `Dispatcher.dispatch/2` to influence content can drop that — the
  dispatcher handles it per-recipient.

## [0.4.4] - 2026-05-12

### Added
- **Pluggable SMS transport backend.** `AshDispatch.Transports.SMS` now
  delegates to a consumer-configured module implementing the new
  `AshDispatch.SMSBackend` behaviour. Configure with
  `config :ash_dispatch, :sms_backend, MyApp.SMS`. When no backend is
  configured the receipt is still marked `:skipped` with
  `error_message: "transport_not_implemented"`, preserving the prior
  stub behavior for consumers that haven't wired SMS yet.
- **`optional: true` channel option.** When a channel is marked optional
  and recipient identifier extraction fails (e.g. SMS channel for a
  user with no `phone_number`), the dispatcher logs and skips that
  channel rather than crashing the whole dispatch. Non-optional channels
  still re-raise as before.

## [0.4.3] - 2026-05-12

### Fixed
- **Catch the remaining 5 `channel.on`/`socket.on`/`channel.join().receive`
  callsites the v0.4.2 sweep missed.** 0.4.2 only widened 3 of the 8
  typed-payload callbacks in the SDK generator; consumers running TS
  strict mode still saw `TS2345` on the rest:
  - `hooks/use-channel.ts` — `channel.join().receive('ok', (response:
    ChannelJoinResponse) → unknown)` and `channel.on('counter_updated',
    (payload: CounterUpdatePayload) → unknown)`
  - `hooks/use-notifications.ts` (standalone mode) — `channel.on('initial_state',
    (payload: { counters?: ... }) → unknown)`,
    `channel.on('new_notification', (notification: Notification) → unknown)`,
    and `socket.on('new_notification', ...)`
  All 8 sites now use the same `(rawX: unknown) => { const x = rawX as
  T; ... }` pattern.

## [0.4.2] - 2026-05-12

### Fixed
- **TypeScript SDK generator emits strict-mode-clean channel handlers.**
  Previously, `channel.on('initial_state', (payload: {...}) => {...})` failed
  to type-check in consumers running `strict: true` (saleflow) because
  phoenix-js types the callback parameter as `(payload: unknown)` and TS
  function-parameter contravariance rejects narrower handler types.
  Generator now widens all `channel.on`/`socket.on` callbacks to
  `(rawPayload: unknown)` and narrows via an inline `as`-cast. Affects
  `socket-provider.tsx` (3 sites: `initial_state`, `counter_updated`,
  `entity_change`) and `hooks/use-notifications.ts` (2 sites:
  `channel.on('counter_updated')` + `socket.on('counter_updated')`).
- **`notification-bell.tsx` no longer imports unused `useState`.** Was
  emitting a `TS6133` violation under `noUnusedLocals`.

## [0.4.1] - 2026-05-12

### Added
- **`:table` option on `Notification.Base` and `DeliveryReceipt.Base`**. Lets
  consumer apps override the Postgres table name when their app already owns
  `notifications` / `delivery_receipts` for a legacy notification system and
  ash_dispatch needs to coexist rather than collide. Defaults preserve current
  behavior (`"notifications"` / `"delivery_receipts"`), so existing consumers
  upgrade transparently.

  Example:

      defmodule MyApp.Dispatch.Notification do
        use AshDispatch.Resources.Notification.Base,
          repo: MyApp.Repo,
          domain: MyApp.Dispatch,
          table: "dispatch_notifications"
      end

## [0.4.0] - 2026-05-12

### Changed (substrate retrofit — tx-semantics)
- **DispatchEvent and BroadcastCounterUpdate now route through `Ash.Notifier`**, not `Ash.Changeset.after_action/2`. Pre-retrofit, these changes fired synchronously inside the action's transaction BEFORE commit/rollback, allowing phantom dispatches and counter broadcasts when a wrapping `Ash.transaction/2` rolled back. Post-retrofit, work runs in `Ash.Notifier`'s commit-deferred firing path and is dropped on rollback (see Ash's `transaction/2` defer-and-fire-or-drop semantics). New shape: single `AshDispatch.Notifier` module + `AshDispatch.Notifier.Info` Spark Info reader; per-action config persisted into `dsl_state` by the `InjectDispatchChanges` and `InjectCounterBroadcasts` transformers and read at runtime by the notifier. Mirrors `Ash.Notifier.PubSub`'s canonical pattern.
- **Behaviour fix: receipt creation is now post-commit only**. `DeliveryReceipt` rows previously could land for events whose triggering action subsequently rolled back. Post-retrofit they only land for actually-committed actions. Orphan receipts on rollback were a bug, not a feature.
- **Removed `lib/changes/dispatch_event.ex` and `lib/changes/broadcast_counter_update.ex`** (845 LOC). Their orchestration logic moved to `lib/notifier/dispatch_handler.ex` and `lib/notifier/counter_handler.ex` respectively, exposed as public entry points the notifier calls.
- **Canary regression net** added at `test/notifier_tx_semantics_test.exs` — two tests (`refute_receive` after force-rollback via raise, `refute_receive` inside the txn before commit) that lock in the contract going forward.
- **DeliveryReceipt**: allow `:failed → :sent` transition for retry-after-failure paths. Previously the receipt was stuck in `:failed` even after a successful re-send.
- **Broadcast transport**: drop per-event log warning when `pubsub_module: nil` (documented passive-shell posture); consumers wanting a presence check should read `Config.pubsub_module()` once at app boot.

### Added
- Initial release of AshDispatch
- Event-driven notification system for Ash Framework
- Multiple transport types:
  - Email transport with Swoosh backend
  - In-app notifications
  - Discord webhooks
  - Slack webhooks
  - SMS transport (stub)
  - Generic webhook transport
- Delivery receipt tracking with state machine
- Automatic retry system for failed deliveries
- User preference checking for email notifications
- Recipient resolution behaviours
- Event DSL with template interpolation
- Comprehensive documentation and guides
- Testing utilities and helpers

### Fixed
- **Hybrid mode callback fallback**: Inline DSL now properly falls back to event module callbacks when fields are not provided. Previously, nil values from inline DSL would overwrite module callback results. Now, only non-nil inline DSL values are included in the content map, preserving module callbacks for dynamic content like `notification_message/2`, `subject/2`, and `action_url/2`

## [0.1.0] - 2025-01-17

### Added
- First alpha release
- Core dispatcher and event system
- Basic transport implementations
- Oban worker integration
- DeliveryReceipt and Notification resources
- Documentation structure with ex_doc

[Unreleased]: https://github.com/Vulcora/ash_dispatch/compare/v0.4.3...HEAD
[0.4.3]: https://github.com/Vulcora/ash_dispatch/compare/v0.4.2...v0.4.3
[0.4.2]: https://github.com/Vulcora/ash_dispatch/compare/v0.4.1...v0.4.2
[0.4.1]: https://github.com/Vulcora/ash_dispatch/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/Vulcora/ash_dispatch/compare/v0.1.0...v0.4.0
[0.1.0]: https://github.com/Vulcora/ash_dispatch/releases/tag/v0.1.0