SDK 12.2.0: triggers.ensureBrewEvent for Brew-event triggers (brew-v2#2071) (#66)

* SDK 12.4.0: triggers.ensureBrewEvent for Brew-event triggers (brew-v2#2071)

GetBrew/brew-v2#2071 adds triggers Brew starts itself, the first being a
contact unsubscribing. This mirrors that API:

- `brew.automations.triggers.ensureBrewEvent({ event, scope, domainId? })`
  wraps `POST /v1/automations/triggers/brew-events`, the get-or-create
  for one scope, and returns the row plus `created`.
- Exports `EnsureBrewEventTriggerInput`, `EnsureBrewEventTriggerResponse`
  and `BrewEventTriggerConfig`.
- The bundled spec takes exactly brew-v2#2071's spec change; the
  consent-source sync stays with #62. Generated types are regenerated.
  Trigger `provider` and instance `source` gain `brew_event`, and the error
  codes gain `TRIGGER_NOT_FIREABLE`.
- `docs/automations.md` gets an "Unsubscribe triggers" section, and the
  `fire` JSDoc names the 409.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Release as 12.2.0; spec delta for Brew-event test runs

- 12.2.0, the next free version: this lands before the open 12.2.0 and
  12.3.0 branches, which renumber when they merge.
- Vendored spec delta from brew-v2#2071: the test operation says a
  Brew-event automation's test runs on Brew's sample with passed fields
  laid over it, and unsubscribe.reasons is required. Types regenerated.
- Docs and changelog: the sample overlay, and that mail from another
  marketing domain reaches the contact only while they are still on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: thedogwiththedataonit

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 12.2.0
+
+Needs the API from GetBrew/brew-v2#2071: triggers Brew starts itself.
+
+### Added
+
+- `brew.automations.triggers.ensureBrewEvent({ event, scope, domainId? })`
+  (`POST /v1/automations/triggers/brew-events`) gets or creates the brand's
+  trigger for one Brew-event scope and says which with `created`. The first
+  Brew event is `contact.unsubscribed`, a contact unsubscribing with an
+  email's link or their mail app's one-click button. Use `scope: 'domain'`
+  with a marketing `domainId` from `brew.domains.list()`, or `scope: 'all'`
+  for every email the brand sends. New types: `EnsureBrewEventTriggerInput`,
+  `EnsureBrewEventTriggerResponse` and `BrewEventTriggerConfig`.
+- Trigger rows can carry `provider: 'brew_event'` and a `brewEvent` config,
+  and trigger instances `source: 'brew_event'`. A `switch` over either union
+  that covers every value needs the new case.
+- The error code `TRIGGER_NOT_FIREABLE`. On a Brew-event trigger,
+  `triggers.fire` and `triggers.readiness` answer `409 TRIGGER_NOT_FIREABLE`,
+  and `triggers.patch` and `triggers.putContract` answer
+  `422 TRIGGER_IMMUTABLE`. Try its automation with `automations.test`: the
+  test runs on the trigger's sample, with any `payload` fields you pass laid
+  over it, and writes no contact.
+
 ## 12.0.0
 
 The API retired `POST /v1/data` (GetBrew/brew-v2#1825), so the SDK drops the

docs/automations.md

@@ -22,6 +22,7 @@ scope.
 | [`triggerInstances.list` / `get`](#fired-trigger-history)  | `/v1/automations/trigger-instances[/{triggerInstanceId}]` |
 | `triggers.list` / `create` / `patch` / `delete`            | `/v1/automations/triggers[/{triggerEventId}]`             |
 | `triggers.get`                                             | `GET /v1/automations/triggers/{triggerEventId}`           |
+| [`triggers.ensureBrewEvent`](#unsubscribe-triggers)        | `POST /v1/automations/triggers/brew-events`               |
 | [`triggers.fire`](#transactional-email--firing-triggers)   | `POST /v1/automations/triggers/{triggerEventId}/fire`     |
 | `triggers.readiness`                                       | `GET /v1/automations/triggers/{triggerEventId}/readiness` |
 | `triggers.getContract` / `putContract` / `validatePayload` | `/v1/automations/triggers/{triggerEventId}/contract[…]`   |
@@ -168,6 +169,54 @@ up.
 body. It replaced `triggers.ready`, which overloaded `GET …/fire` and wrapped
 its answer in the fire envelope.
 
+## Unsubscribe triggers
+
+Brew events are triggers Brew starts itself. The first one is
+`contact.unsubscribed`: a contact unsubscribed with an email's unsubscribe
+link or their mail app's one-click button (never a bounce, complaint, import
+or API edit). `triggers.ensureBrewEvent` returns the brand's trigger for one
+scope, creating it the first time:
+
+```ts
+// Unsubscribes from one marketing domain's list (ids from brew.domains.list())
+const news = await brew.automations.triggers.ensureBrewEvent({
+  event: 'contact.unsubscribed',
+  scope: 'domain',
+  domainId: 'jd7f0c2a8w1x9m4n6p3q5r8s2t',
+})
+
+// Unsubscribes from every email the brand sends
+const all = await brew.automations.triggers.ensureBrewEvent({
+  event: 'contact.unsubscribed',
+  scope: 'all',
+})
+
+all.created // true the first time, false on every later call
+all.brewEvent // { event: 'contact.unsubscribed', scope: 'all' }
+```
+
+An unsubscribe from all clicked in one of a domain's emails also starts that
+domain's trigger, if the contact was still on its list. The payload is
+`{ email, unsubscribe: { scope, domain?, method, reasons, reasonText?, emailId?, emailTitle?, sendId?, at } }`.
+
+Wire the `triggerEventId` into `automations.create`. Brew owns the row:
+`patch` and `putContract` answer `422 TRIGGER_IMMUTABLE`, and `fire` and
+`readiness` answer `409 TRIGGER_NOT_FIREABLE`. Try a flow with
+`automations.test({ automationId })`: the test runs on the trigger's sample,
+with any `payload` fields you pass laid over it, and writes no contact.
+
+The run emails only the contact who just opted out. Send what they need, such
+as a confirmation of the unsubscribe, from a transactional domain; never a
+promotion. Mail from another marketing domain reaches them only while they are
+still on its list, never after an unsubscribe from all. Publishing refuses a
+flow none of whose emails could reach them.
+
+Refusals: `400 INVALID_REQUEST` when `domainId` is missing for
+`scope: 'domain'` or sent for `scope: 'all'`; `404 DOMAIN_NOT_FOUND`;
+`422 DOMAIN_PURPOSE_NOT_ALLOWED` for a transactional domain, which keeps no
+list; `409 TRIGGER_LIMIT_REACHED` when the brand holds the most triggers it
+can.
+
 ## Fired-trigger history
 
 `triggerInstances` is the audit log of every inbound fire — one row per fire,
@@ -193,7 +242,8 @@ for await (const row of brew.automations.triggerInstances.listAll()) {
 ```
 
 An unknown id is `404 TRIGGER_INSTANCE_NOT_FOUND` — the code that replaced
-`EVENT_NOT_FOUND`.
+`EVENT_NOT_FOUND`. `source` says where the fire came from: `api`,
+`integration`, or `brew_event` (an unsubscribe Brew recorded itself).
 
 ## Manual-audience runs