feat: brew.send(key, payload) and fire by key (13.1.0)

[thedogwiththedataonit]

What

App email by trigger key, the SDK half of the DX push (brew.send). Rebased on main d804502 (10-16).

• brew.send(key, payload, options?) on every client, including withBrand(...) clients:
  brew.send('auth.password-reset', { email, confirmationUrl, appName }) fires
  POST /v1/automations/triggers/by-key/{triggerKey}/fire with { payload } and resolves to the accepted fire
  (triggerInstanceId, automationRunIds, triggerKey, ...). { idempotencyKey } is forwarded as the
  Idempotency-Key header; { raw: true } passes through.
• brew.automations.triggers.fireByKey({ triggerKey, payload }, options?): the object form, mirroring fire
  (TPayload generic, raw overload). An unknown key throws BrewApiError 404 TRIGGER_KEY_NOT_FOUND, a Brew-event
  trigger 409 TRIGGER_NOT_FIREABLE; an empty, . or .. key throws a TypeError before any request (dot segments
  would otherwise resolve to another route). FireTriggerByKeyResponse.triggerKey is required.
• BrewTriggerKeyRegistry (augment with declare module '@brew.new/sdk'): empty by default, so send takes any
  string key and { email: string } & { [k: string]: SendPayloadValue | undefined }. Once augmented, unknown keys and
  wrong payloads stop compiling; a key typed as a union must carry a payload that fits every key in it, and a key whose
  payload is itself a union is satisfied by any one of its alternatives (Greptile P2, fixed in d073ec7).
• Spec: brew-v2 main 8c7020e535 plus exactly the operations and schemas of GetBrew/brew-v2#2013 (d556eaf50d)
  and #2017 (63736f0f99). With #2017 now stacked on #2013 on current main, the vendored file is byte-identical to
  #2017's own spec. Trigger rows carry key + appEmail, create / patch take key, TriggerFireAccepted.triggerKey,
  codes TRIGGER_KEY_NOT_FOUND / TRIGGER_KEY_RESERVED / TRIGGER_KEY_TAKEN. Types regenerated with
  bun run generate:types.
• Docs: README "Send your first app email", docs/send.md, docs/automations.md trigger keys, the two-positional
  brew.send exception in docs/development.md#the-brewsend-exception (AGENTS.md pointer; AGENTS.md is 8,176 bytes).

Version: 13.1.0 (not released)

npm already has 12.2.0 and 12.3.0. Main's CHANGELOG "Unreleased" section (#71, canvas revoke response) changes a
public method signature and is planned as 13.0.0 under RELEASING.md's version policy (brew-cli's RELEASING waits
for it). This PR only adds, so it is the next minor after that: 13.1.0. The CHANGELOG heading is
13.1.0 (not released yet), above Unreleased. package.json stays at main's version: the release commit
(npm version 13.1.0) sets it, so merging this before 13.0.0 is cut cannot skip 13.0.0. Cut 13.0.0 first.
#64 (adapters + appEmails) is 13.2.0. Consumers that need brew.send pin ^13.1.0.

Rebase notes

• Conflicts: client.ts (main's canvas resource + send, both kept), package.json (main's 12.3.0 kept),
  AGENTS.md (main's text + the one-line brew.send pointer), CHANGELOG (main's history kept; this PR's entry rewritten as
  13.1.0; the 12.1.0 backfill kept), spec + generated types (rebuilt, not merged).
• The old branch's docs/development.md section lived in a merge commit and was dropped by the rebase; restored in
  1fe8154.

Publish gate

Do not tag or publish until GetBrew/brew-v2#2013 and #2017 are deployed and the live spec matches the vendored one
(the by-key operation and the trigger key / appEmail fields). Until then the by-key route answers 404 and trigger
rows carry no key. If either PR changes its spec before merge, re-vendor and run bun run generate:types.

Tests

• tests/resources/automations/triggers/fire-by-key.test.ts (MSW): dotted key in the path, body { payload }, auto and
  caller idempotency header, / and ? percent-encoded, ./../empty refused, { raw: true }, 404 mapping.
• tests/send.test.ts (MSW via createBrewClient): body, undefined field dropped, idempotency option, X-Brand-Id
  from withBrand, 404.
• tests/types/send-registry.test.ts + tests/types/augmented-registry/ (a separate TypeScript program; every
  @ts-expect-error must fire): unknown key, wrong payload, missing field, union key, union payload alternatives.

Local on head d073ec7: bun tsc, bun lint, bun run format:check, bun run test (124 files, 713 tests),
bun run build, generate:types freshness, bun install --frozen-lockfile (no changes), AGENTS.md budget: all pass.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no blocking issues remain.

Summary

Adds brew.send(key, payload, options?) and automations.triggers.fireByKey, with brand scoping, request options, and typed trigger keys.

• Triggers can be fired by a stable key instead of a minted id.
• brew.send sends app email by its trigger key.
• Trigger keys can be set, cleared, and read with trigger details.
• The changelog now includes the missing 12.1.0 release notes.
• Trigger API notes and shared types now describe key-based fires.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["brew.send(key, payload, options)"] --> B["triggers.fireByKey"]
  C["withBrand client"] --> A
  B --> D["Shared HTTP client"]
  D --> E["POST /v1/automations/triggers/by-key/{triggerKey}/fire"]
  E --> F["Accepted fire or raw response"]

Loading

_{Reviews (4) · Last reviewed commit: "fix(send): keep a union payload's altern..." · Reviewed by Greptile}