@terreno/mcp 57.2.0 → 57.4.0

package/dist/docs/versioned/57.2.0/implementationPlans/comms-abstraction.md

@@ -0,0 +1,413 @@
+# Implementation Plan: Pluggable communications layer (@terreno/comms)
+
+**Status:** Approved — Phase 1 gap-fill implemented
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1018
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Approved:** 2026-08-20
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** none (inbound-webhooks is needed only by adapter delivery-callback phases)
+**RTK deprecation flag:** None — backend-only package
+**Shipped:** Phases 2–3 and most of Phase 1 in #1037; SendGrid adapter in #1050 (separate IP)
+**Remaining:** none — Phase 1 gap-fill landed on this branch
+**Research:** [comms-abstraction-research.md](comms-abstraction-research.md)
+
+## Goal
+
+Terreno backends cannot send email, SMS, or push notifications: there is no mail
+integration at all, `expo-server-sdk` sits unused in `@terreno/api`, and the RTK client's
+`resetPassword` call has no backend to talk to. This IP creates `@terreno/comms`, a new
+workspace package that defines **provider interfaces** for the four outbound channels
+(mail, SMS, push, OTP verification), a **`CommsApp`** TerrenoPlugin that registers
+configured providers and exposes send services to routes and other plugins, **push-token
+registration** routes and model, a **delivery log**, and **console adapters** so every
+channel works in development with zero external accounts.
+
+Concrete providers (Twilio, SendGrid, Expo push) are separate IPs — one per adapter — so
+consumer apps install only the SDKs they use.
+
+## Non-Goals
+
+- Any concrete provider SDK integration (see `comms-adapter-*` IPs). The SendGrid adapter
+  already lives at `@terreno/comms/adapters/sendgrid` under that IP; this IP does not own it.
+- In-app notification center, inbox UI, or user notification preferences
+  (`notification-center` item).
+- Password reset / email verification flows (`password-reset-and-email-verification` item
+  — a consumer of this layer).
+- Inbound webhook HTTP handling (`inbound-webhooks` item); this IP ships
+  `recordDeliveryEvent` / `recordOptOut` for adapters to call once those webhooks land.
+- Broadcast/bulk campaign tooling.
+- Admin retry UI and rich explorer filters ([comms-admin-dashboard](comms-admin-dashboard.md)).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| New package or `@terreno/api` module? | New package `@terreno/comms`, mirroring `@terreno/feature-flags` — keeps provider SDKs out of the core dependency tree |
+| How do provider SDKs stay optional? | Adapters live in subpath exports (`@terreno/comms/adapters/<name>`) with their SDKs as `peerDependencies` marked optional; core package has zero provider SDKs |
+| Precedent to follow | `secretProviders.ts` (env + GCP behind one interface) and the OpenFeature provider in `@terreno/feature-flags` |
+| Templates | Minimal: `{subject, text, html}` render helper with variable interpolation; no template builder |
+| Where do send calls log? | `CommsMessage` Mongoose model, mirroring the `AIRequest.logRequest` pattern — logging failures never break the send |
+| Dev experience | `ConsoleMailProvider` / `ConsoleSmsProvider` / `ConsolePushProvider` / `ConsoleVerificationProvider` print to logger and record to `CommsMessage`; default when no provider configured in non-production |
+| Consumer lifecycle hooks | `CommsApp` options expose `beforeSend` / `onSend` / `onError` / `onRetry` / `onOptOut` / `onDeliveryEvent`. Hooks are awaited but wrapped: a throwing hook is logged (`logger.error`) and never breaks the send. `beforeSend` may mutate or cancel |
+| Error taxonomy | Every `SendResult` failure carries `errorCode` (provider-native code as a string) and `errorClass` (`"permanent"` \| `"transient"` \| `"config"`). Adapters own the mapping; the facade uses `errorClass` to decide its single inline retry (transient only) and the admin dashboard uses it to gate manual retries |
+| Payload retention | `retainPayloadDays` option (default 30) keeps the rendered message on the `CommsMessage` row (post `redactPayload` hook) so the admin dashboard can retry; a TTL-style cleanup clears expired payloads |
+| `onRetry` signature (published) | Keep shipped `(context, result: SendResult)`. Put 1-based `attempt` on `CommsHookContext` (2 = the inline retry). Do not change the callback to `(context, attempt)` |
+| Provider throws | Facade never rethrows from `sendMail` / `sendSms` / `sendPushToUser` / `startVerification` / `checkVerification`. A throwing provider becomes `errorClass: "transient"`, `errorCode: "provider-throw"`, then follows the same retry rules |
+| Push retry | Retry **only tokens** whose first `SendResult` is `errorClass: "transient"` via a second `sendPush`; merge. Do not re-send accepted tokens |
+| Push prune | Deactivate when `errorClass === "permanent"` **or** `isPermanentFailure === true` (shipped alias; adapters may set both) |
+| Delivery / opt-out intake | `CommsService.recordDeliveryEvent` / `recordOptOut` update the matching log row (by `providerMessageId`) and invoke hooks. Missing rows: `logger.warn`, still fire the hook |
+| Payload expiry | `payloadExpiresAt` on the row. Mongo TTL indexes must **not** be used (they would delete the log). `CommsMessage.clearExpiredPayloads()` unsets `payload` only; `logSend` / `appendAttempt` call it best-effort (limit 50) |
+| `checkVerification` | Log a verification row; no inline retry; never persist the code |
+
+## Architecture
+
+```
+@terreno/comms
+  src/
+    types.ts            # Provider interfaces + message/result types
+    commsApp.ts         # CommsApp TerrenoPlugin
+    commsService.ts     # send* + recordDeliveryEvent/recordOptOut
+    models/
+      commsMessage.ts   # Delivery log
+      pushToken.ts      # Device push token registry
+    routes/
+      pushTokens.ts     # custom upsert/list/deactivate + owner read
+      commsExplorer.ts  # Admin-only delivery log explorer
+    adapters/
+      console.ts        # Dev adapters for all four channels
+    templates.ts        # renderTemplate({subject, text, html}, data)
+```
+
+### Provider interfaces (types.ts)
+
+```typescript
+export type CommsErrorClass = "config" | "permanent" | "transient";
+export type CommsChannel = "mail" | "push" | "sms" | "verification";
+export type CommsMessageStatus =
+  | "bounced"
+  | "cancelled"
+  | "delivered"
+  | "failed"
+  | "sent";
+
+export interface SendResult {
+  providerMessageId?: string;
+  accepted: boolean;
+  error?: string;
+  errorCode?: string;
+  errorClass?: CommsErrorClass;
+  isPermanentFailure?: boolean; // alias: treat as errorClass "permanent" when that is unset
+  metadata?: Record<string, unknown>;
+}
+
+export interface MailMessage {
+  to: string | string[];
+  from?: string;
+  subject: string;
+  text?: string;
+  html?: string;
+  replyTo?: string;
+  templateId?: string;
+  dynamicTemplateData?: Record<string, unknown>;
+  metadata?: Record<string, string>;
+}
+
+export interface MailProvider {
+  readonly id: string;
+  sendMail(message: MailMessage): Promise<SendResult>;
+}
+
+export interface SmsProvider {
+  readonly id: string;
+  sendSms(message: {to: string; body: string}): Promise<SendResult>;
+}
+
+export interface PushMessage {
+  tokens: string[];
+  title: string;
+  body: string;
+  data?: Record<string, unknown>;
+  badge?: number;
+  sound?: string | null;
+}
+
+export interface PushProvider {
+  readonly id: string;
+  sendPush(message: PushMessage): Promise<SendResult[]>; // one per token, same order
+}
+
+export interface VerificationProvider {
+  readonly id: string;
+  startVerification(options: {to: string; channel: "sms" | "email"}): Promise<SendResult>;
+  checkVerification(options: {to: string; code: string}): Promise<{
+    valid: boolean;
+    error?: string;
+  }>;
+}
+
+export interface DeliveryEvent {
+  channel: "mail" | "sms" | "push";
+  providerMessageId: string;
+  status: "delivered" | "bounced" | "failed" | "opened";
+  errorCode?: string;
+  errorClass?: CommsErrorClass;
+  raw?: unknown;
+}
+
+export interface CommsHookContext {
+  channel: CommsChannel;
+  provider: string;
+  message?: MailMessage | {to: string; body: string} | PushMessage | {
+    to: string;
+    channel: "sms" | "email";
+  };
+  userId?: string;
+  isRetry: boolean;
+  attempt: number;          // 1 = first provider call, 2 = inline retry
+  messageId?: string;       // CommsMessage._id once the log row exists
+}
+
+export interface OptOutEvent {
+  channel: "mail" | "sms";
+  to: string;
+  provider: string;
+  reason: string;           // e.g. "sms-stop", "unsubscribe", "spam-report"
+  raw?: unknown;
+}
+```
+
+Verification start attempts store `metadata.verificationChannel`. Recipients stay
+redacted. Verification codes are never persisted.
+
+### CommsApp (TerrenoPlugin)
+
+```typescript
+export interface CommsOptions {
+  mail?: MailProvider;
+  sms?: SmsProvider;
+  push?: PushProvider;
+  verification?: VerificationProvider;
+  defaultFrom?: string;
+  logMessages?: boolean;                      // default true
+  retainPayloadDays?: number;                 // default 30; 0 stores no payload
+  redactRecipients?: boolean;                 // default true — `to` at rest
+  redactPayload?: (context: CommsHookContext, payload: unknown) => unknown;
+
+  beforeSend?: (context: CommsHookContext) =>
+    Promise<{cancel?: boolean; message?: CommsHookContext["message"]} | void>;
+  onSend?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onError?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onRetry?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onOptOut?: (event: OptOutEvent) => Promise<void>;
+  onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
+}
+
+new TerrenoApp({userModel: User})
+  .register(new CommsApp({mail: new ConsoleMailProvider(), push: new ExpoPushProvider()}))
+  .start();
+```
+
+`CommsApp.register()` mounts the push-token routes and admin explorer;
+`getCommsService()` (module-level accessor) gives routes and other plugins `sendMail` /
+`sendSms` / `sendPushToUser` / `startVerification` / `checkVerification` /
+`recordDeliveryEvent` / `recordOptOut`. `sendPushToUser(userId, message)` resolves the
+user's active `PushToken`s and prunes tokens the provider reports permanently dead.
+
+Unconfigured channel behavior: in production, throw `APIError({status: 501, title:
+"Comms channel not configured"})`; in development, fall back to the console adapter with a
+`logger.warn`.
+
+### Hook order and semantics
+
+For every send (including the inline retry) the facade runs:
+
+1. `beforeSend` — once, **before the first** provider call. May replace the message
+   (`{message}`) or cancel (`{cancel: true}` → `CommsMessage` with `status: "cancelled"`,
+   no provider call). Quiet hours, preferences, and suppression lists use this hook.
+2. Provider `send*` → on `errorClass: "transient"` (or a wrapped provider throw),
+   `onRetry(context, failedResult)` fires with `context.attempt === 2` and `isRetry: true`,
+   then the facade retries once.
+3. `onSend` (accepted) or `onError` (final failure) — `onError` receives the full
+   `SendResult`.
+4. Later, adapters call `recordDeliveryEvent` / `recordOptOut`, which fire
+   `onDeliveryEvent` / `onOptOut`.
+
+`checkVerification` skips `beforeSend` and inline retry. It still logs and fires
+`onSend` / `onError`.
+
+Hooks are observation and shaping points, not error channels: exceptions thrown inside a
+hook are caught, logged with `logger.error`, and recorded in `CommsMessage.metadata.hookErrors`
+— they never change the send outcome. A throwing `beforeSend` is treated as “no mutation,
+do not cancel.”
+
+### Attempt logging
+
+One `CommsMessage` row per send invocation (not per retry):
+
+1. After attempt 1, `logSend` creates the row (`attempts[0]`, `attemptCount: 1`).
+2. After the inline retry, `appendAttempt` pushes `attempts[1]` and updates top-level
+   `status`, `error`, `errorCode`, `errorClass`, `providerMessageId`, `attemptCount`,
+   `lastAttemptAt`.
+3. Cancelled sends create a row with `status: "cancelled"`, empty `attempts`, no provider.
+
+`logSend` and `appendAttempt` never throw.
+
+### Payload stored per channel
+
+After `redactPayload` (identity if unset), when `retainPayloadDays > 0`:
+
+| Channel | `payload` |
+|---|---|
+| mail | `{to, from, subject, text, html, replyTo, templateId, dynamicTemplateData}` |
+| sms | `{to, body}` |
+| push | `{title, body, data, badge, sound}` (tokens omitted) |
+| verification start | `{channel}` only |
+| verification check | none |
+| cancelled | the mutated-or-original message, same shape as the channel |
+
+`payloadExpiresAt = now + retainPayloadDays`. Expired payload is treated as absent for
+retry even before cleanup runs.
+
+## Models
+
+All fields carry `description`; both models use `createdUpdatedPlugin` + `isDeletedPlugin`
+and live per the five-type pattern (`CommsMessageDocument`, etc.).
+
+**PushToken** — `userId` (ref User, required, indexed), `token` (string, required, unique),
+`platform` ("ios" | "android" | "web"), `deviceId` (string, optional), `active` (boolean,
+default true), `lastSeenAt` (date). Shipped.
+
+**CommsMessage** — `channel` ("mail" | "sms" | "push" | "verification"), `provider`
+(string), `to` (string, redacted-at-rest for sms/mail per option), `subject` (string,
+optional), `userId` (ref User, optional), `status` ("sent" | "failed" | "delivered" |
+"bounced" | "cancelled"), `providerMessageId` (string, indexed), `error` (string,
+optional), `errorCode` (string, indexed), `errorClass` ("permanent" | "transient" |
+"config"), `templateId` (string, optional), `attempts` (array of `{at, provider,
+providerMessageId, errorCode, errorClass, error}` — one entry per facade attempt including
+the inline retry), `attemptCount` (number), `lastAttemptAt` (date), `retriedFromId` /
+`retriedById` (ref CommsMessage — written later by admin-dashboard retries; schema exists
+now), `payload` (Mixed, retained per `retainPayloadDays` after `redactPayload`, cleared on
+expiry), `payloadExpiresAt` (date), `metadata` (Mixed). Statics: `logSend()`,
+`appendAttempt()`, `clearExpiredPayloads()`.
+
+These fields exist so the [comms-admin-dashboard](comms-admin-dashboard.md) IP can filter
+on error codes/classes, show per-attempt history, and re-send from the retained payload
+without any further schema changes.
+
+## APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| POST | `/comms/pushTokens` | IsAuthenticated | Upsert by `token`; sets `userId`, `platform`, `lastSeenAt` |
+| GET | `/comms/pushTokens` | IsOwner via queryFilter | List own device tokens |
+| DELETE | `/comms/pushTokens/:id` | IsOwner | Deactivate on logout/uninstall |
+| GET | `/comms/messages` | IsAdmin | Paginated delivery log explorer; filters: `channel`, `status`, `userId`, date range |
+
+Push token registration, owner-scoped list, and deactivation use dedicated handlers because
+`modelRouter` create cannot provide idempotent upsert semantics and `OwnerQueryFilter` targets a
+persisted `ownerId` while `PushToken` persists `userId`. Owner read remains on `modelRouter`.
+The explorer uses `createOpenApiBuilder`, modeled on `addAiRequestsExplorerRoutes`, and is
+deliberately minimal here — the [comms-admin-dashboard](comms-admin-dashboard.md) IP upgrades it
+with error-code/class filtering, free-text search, a detail route, stats, and retry endpoints.
+
+No HTTP routes for `recordDeliveryEvent` / `recordOptOut` in this IP.
+
+## Notifications
+
+None beyond the feature itself.
+
+## UI
+
+None in this IP. example-frontend gains a settings row that registers the Expo push token
+(client helper already exists in `store/utils.ts`) once the Expo adapter lands.
+
+## Phases
+
+1. **Package + contracts:** `@terreno/comms` package scaffold, `types.ts`, console
+   adapters, `CommsMessage` + logging, `commsService`, unit tests.
+   **Shipped** including dashboard-ready fields, hooks, payload retention, and
+   channel-wide transient retry.
+2. **CommsApp + routes:** plugin registration, `PushToken` model + routes, admin explorer,
+   OpenAPI, supertest coverage. **Shipped.**
+3. **Integration:** example-backend registers `CommsApp` (console adapters), seed docs,
+   `docs/reference/comms.md`, catalog entries, publish wiring in `publish-on-tag.yml`.
+   **Shipped.**
+
+## Feature Flags & Migrations
+
+None. New collections only; no existing data touched. Remaining schema fields are additive
+on `CommsMessage` (`cancelled` status value, `attempts`, payload fields, retry refs).
+
+## Activity Log & User Updates
+
+Every send attempt is a `CommsMessage` row (that is the audit surface). No user-facing
+updates.
+
+## Not Included / Future Work
+
+- Adapter IPs: `comms-adapter-expo-push`, `comms-adapter-twilio-sms`,
+  `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (Phase 1 of SendGrid already
+  shipped).
+- Admin operations dashboard (rich filtering, log digging, manual retries) —
+  [comms-admin-dashboard](comms-admin-dashboard.md); this IP only ships the fields and
+  hooks it needs.
+- Notification center, user notification preferences (`beforeSend` is the extension
+  point they will plug into).
+- Queue-backed sending with automatic scheduled retries — arrives with `job-queues`;
+  until then sends are inline with one transient-error retry plus manual admin retries.
+- Webhook HTTP for delivery callbacks — `inbound-webhooks` plus adapter Phase 2.
+
+## Files to Create / Modify
+
+Remaining roast (gap-fill):
+
+- `comms/src/types.ts`, `commsService.ts`, `models/commsMessage.ts`, `modelTypes.ts`
+- Tests for hooks, retry-per-channel, attempts, payload expiry
+- `docs/reference/comms.md`, `.rulesync/rules/comms/00-comms.md` (then `bun run rules`)
+
+Already shipped:
+
+- `comms/` package scaffold, console adapters, `CommsApp`, routes, CI/publish
+- Root `package.json` scripts, example-backend registration
+
+## Task List
+
+See [docs/tasks/comms-abstraction.md](../tasks/comms-abstraction.md).
+
+## Acceptance Criteria
+
+- [x] A Terreno app with only console adapters can call `sendMail`, `sendSms`,
+      `sendPushToUser`, and `startVerification`/`checkVerification` in development, each
+      producing a logger line and a `CommsMessage` row.
+- [x] `beforeSend` can cancel and mutate; `onSend`/`onError` fire with the final
+      `SendResult`; `onRetry` fires on the inline transient retry with
+      `context.attempt === 2` — and a hook that throws is logged without changing the send
+      outcome (test per hook, including `onOptOut` / `onDeliveryEvent` via the record
+      methods).
+- [x] Failed sends record `errorCode` and `errorClass` on both the `SendResult` and the
+      `CommsMessage` row; only `transient` failures trigger the inline retry; provider
+      throws become transient and do not propagate.
+- [x] `CommsMessage.attempts` holds one entry per attempt with per-attempt error data;
+      `payload` is retained post-redaction and cleared after `retainPayloadDays`.
+- [x] `POST /comms/pushTokens` registers a device token for the authenticated user;
+      re-posting the same token updates rather than duplicates; other users cannot list or
+      delete it.
+- [x] `GET /comms/messages` is admin-only, paginated, and filterable by channel and status.
+- [x] Production apps with an unconfigured channel get a 501 `APIError`, not a silent no-op.
+- [x] `@terreno/comms` core has zero provider SDKs in `dependencies`.
+- [x] All routes appear in `/openapi.json` and the generated SDK compiles.
+- [x] Push retries re-send only transient-failed tokens; permanent failures deactivate
+      tokens via `errorClass` or `isPermanentFailure`.
+- [x] `recordDeliveryEvent` updates status by `providerMessageId`; `recordOptOut` fires
+      `onOptOut` without sending.
+
+## Named assumptions (finish pass)
+
+1. Original Decisions table stands; remaining work implements the IP rather than shrinking
+   it to today’s partial code.
+2. Published `onRetry(context, result)` stays; `attempt` is added on context.
+3. Roadmap issue #1018 already exists; Blend does not open a second issue. Maintainer can
+   move Project status when roast of remaining tasks starts.

package/dist/docs/versioned/57.2.0/implementationPlans/comms-adapter-expo-push.md

@@ -0,0 +1,107 @@
+# Implementation Plan: Comms adapter — Expo push notifications
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1019
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md)
+**RTK deprecation flag:** None — backend adapter; client token registration already exists
+
+## Goal
+
+Implement `PushProvider` on Expo's push service so `sendPushToUser` delivers real
+notifications to iOS/Android devices. `expo-server-sdk` is already a dependency of
+`@terreno/api` (currently unused — it moves to this adapter's peer deps); the client-side
+token fetch (`getExpoPushTokenAsync`) already exists in `example-frontend/store/utils.ts`.
+
+## Non-Goals
+
+- Direct FCM/APNs integration (future adapter if demand appears).
+- Notification center / inbox UI.
+- Rich notification content (images, actions) beyond title/body/data/badge/sound.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| SDK | `expo-server-sdk` as optional peer of `@terreno/comms` (subpath `adapters/expoPush`); removed from `@terreno/api` deps |
+| Receipts | Poll receipts after send (Expo's required pattern); surface as `DeliveryEvent`s to `onDeliveryEvent` |
+| Dead tokens | `DeviceNotRegistered` receipt → `SendResult.accepted: false` with permanent-failure marker so core pruning deactivates the `PushToken` |
+| Chunking | Use the SDK's `chunkPushNotifications`; one `SendResult` per token preserved through chunks |
+
+## Architecture
+
+```typescript
+// @terreno/comms/adapters/expoPush
+export class ExpoPushProvider implements PushProvider {
+  readonly id = "expo";
+  constructor(options?: {accessToken?: string; receiptPollDelayMs?: number});
+  sendPush(message: PushMessage): Promise<SendResult[]>;
+}
+```
+
+Send flow: validate tokens with `Expo.isExpoPushToken` → chunk → send → collect tickets →
+schedule one receipt poll (default 15 min, configurable; inline timer until `job-queues`
+lands) → map receipt errors to `DeliveryEvent`s and permanent-failure results.
+
+## Models
+
+None new — uses `PushToken` and `CommsMessage` from the abstraction.
+
+## APIs
+
+None new.
+
+## Notifications
+
+This is the notification plumbing itself.
+
+## UI
+
+example-frontend: register the push token on login via `POST /comms/pushTokens` (guarded by
+`expo-device` physical-device check once the native baseline lands) and a profile-screen
+test-send row in dev builds.
+
+## Phases
+
+Single phase.
+
+## Feature Flags & Migrations
+
+None.
+
+## Activity Log & User Updates
+
+Sends and receipt failures logged to `CommsMessage`.
+
+## Not Included / Future Work
+
+- Queue-backed receipt polling (moves to `job-queues` when available).
+- Web push (Expo tokens cover native only; web is a future adapter).
+
+## Files to Create / Modify
+
+- `comms/src/adapters/expoPush.ts` + tests (mock `Expo` client)
+- `comms/package.json` — optional peer `expo-server-sdk`
+- `api/package.json` — remove unused `expo-server-sdk`
+- `example-frontend/app/(tabs)/profile.tsx`, `store/utils.ts` — token registration wiring
+- `docs/reference/comms.md` — adapter section
+
+## Task List
+
+See [docs/tasks/comms-adapter-expo-push.md](../tasks/comms-adapter-expo-push.md).
+
+## Acceptance Criteria
+
+- [ ] With a mocked Expo client, `sendPush` returns one `SendResult` per token across chunk
+      boundaries.
+- [ ] A `DeviceNotRegistered` receipt deactivates the corresponding `PushToken` via core
+      pruning.
+- [ ] Invalid tokens are rejected before hitting the SDK and logged as failed
+      `CommsMessage` rows.
+- [ ] `@terreno/api` no longer lists `expo-server-sdk`; apps not using the adapter install
+      nothing new.
+- [ ] example-frontend registers its token after login on a physical device build.

package/dist/docs/versioned/57.2.0/implementationPlans/comms-adapter-sendgrid.md

@@ -0,0 +1,157 @@
+# Implementation Plan: Comms adapter — transactional email (SendGrid)
+
+**Status:** In progress — Phase 1 send path implemented; Phase 2 gated on inbound-webhooks
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1022
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md); inbound-webhooks (Phase 2 only)
+**RTK deprecation flag:** None — backend only
+
+## Goal
+
+Implement `MailProvider` on Twilio SendGrid (decision D2 — first mail adapter, sharing the
+Twilio account story with the SMS and Verify adapters) so `sendMail` delivers real
+transactional email. This unblocks `password-reset-and-email-verification` and
+`invitations-and-seats`.
+
+## Non-Goals
+
+- Other mail providers (Resend/SES/SMTP — items when demand appears).
+- Marketing campaigns, contact lists, SendGrid dynamic template management.
+- Inbound email parsing.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| SDK | `@sendgrid/mail` as optional peer, subpath `@terreno/comms/adapters/sendgrid` |
+| Auth | `SENDGRID_API_KEY` env or constructor option; fail fast at registration when missing |
+| From address | Constructor `fromEmail`/`fromName` falling back to `CommsApp.defaultFrom`; sender verification is a documented SendGrid prerequisite, not automated |
+| Templates | Terreno-side rendering (`templates.ts` from the abstraction) sent as `text`/`html`; SendGrid dynamic templates supported pass-through via `templateId` + `dynamicTemplateData` but not required |
+| Sandbox | SendGrid `mail_settings.sandbox_mode` toggle for CI/e2e so tests never send |
+| Delivery events | Phase 2: SendGrid Event Webhook (delivered/deferred/bounce/dropped/spamreport/unsubscribe/open) with ECDSA signature verification via the inbound-webhooks framework, mapped to `DeliveryEvent`s / `OptOutEvent`s |
+| Error classification | Adapter owns the HTTP-status + event-type → `errorClass` map (table below); 429/5xx are `transient`, other 4xx `permanent`, 401/403 `config` |
+| Suppression / opt-outs | Bounces, spam reports, and unsubscribes emit `OptOutEvent` → consumer `onOptOut`. SendGrid maintains its own suppression lists; a send to a suppressed address comes back as a `dropped` event with the suppression reason, classified `permanent` |
+| Admin dashboard support | Every `CommsMessage` row stores `errorCode`/`errorClass`, the `x-message-id`, and a `metadata.consoleUrl` deep link to SendGrid Email Activity for log digging |
+
+## Architecture
+
+```typescript
+// @terreno/comms/adapters/sendgrid
+export class SendGridMailProvider implements MailProvider {
+  readonly id = "sendgrid";
+  constructor(options?: {
+    apiKey?: string;          // default env SENDGRID_API_KEY
+    fromEmail?: string;
+    fromName?: string;
+    sandboxMode?: boolean;    // default true when NODE_ENV === "test"
+  });
+  sendMail(message: MailMessage): Promise<SendResult>;
+}
+```
+
+Error mapping: SendGrid 4xx (bad address, unverified sender) → `accepted: false` with the
+response body's first error message in `SendResult.error` and full body in
+`CommsMessage.metadata`; 429/5xx classified `transient` and retried once by the core
+facade. The provider never throws through `sendMail`.
+
+### Error classification
+
+Send-time failures classify by HTTP status; post-acceptance failures arrive as events
+(Phase 2) and reclassify the `CommsMessage`.
+
+| Signal | Meaning | `errorCode` | `errorClass` |
+|---|---|---|---|
+| 400 (bad address, missing field), 413 | Request is wrong | `sendgrid-<status>` + first body error | `permanent` |
+| 401, 403 (bad key, unverified sender) | App misconfiguration | `sendgrid-<status>` | `config` (also `logger.error` at send time) |
+| 429 | Rate limited | `sendgrid-429` | `transient` |
+| 5xx / network errors | SendGrid-side or transport failure | `sendgrid-<status>` | `transient` |
+| Event: `bounce` (hard) | Mailbox permanently rejects | `bounce` + reason | `permanent` |
+| Event: `bounce` (soft) / `deferred` | Temporary mailbox/receiver issue | `deferred` | `transient` |
+| Event: `dropped` | SendGrid suppressed (prior bounce, spam report, unsubscribe, invalid) | `dropped` + reason | `permanent` |
+| Event: `spamreport`, `unsubscribe`, `group_unsubscribe` | Recipient opted out | event type | `permanent` (also emits `OptOutEvent`) |
+
+Permanent-class failures are never auto-retried and show as non-retryable in the admin
+dashboard with the reason (retrying a suppressed or unsubscribed address damages sender
+reputation); transient-class failures retry once inline and stay manually retryable.
+
+### Event webhook mapping (Phase 2)
+
+| SendGrid event | `DeliveryEvent.status` | `CommsMessage.status` |
+|---|---|---|
+| `processed` | — | `sent` (unchanged) |
+| `delivered` | `delivered` | `delivered` |
+| `deferred` | — (attempt noted in metadata) | `sent` (SendGrid keeps retrying) |
+| `bounce`, `dropped` | `bounced` / `failed` (+ reason as `errorCode`) | `bounced` / `failed` |
+| `open` | `opened` | unchanged (recorded in metadata) |
+| `spamreport`, `unsubscribe`, `group_unsubscribe` | — | unchanged; emits `OptOutEvent` → `onOptOut` |
+
+Events correlate to rows via the `x-message-id` response header captured at send time
+(SendGrid appends per-recipient suffixes; match on the prefix).
+
+## Models / APIs / Notifications / UI
+
+None new. Phase 2 adds one webhook route via the inbound-webhooks framework.
+
+## Phases
+
+1. **Send path:** provider, config resolution, sandbox mode, error classification,
+   `x-message-id` capture + Email Activity deep link, mocked-client tests;
+   example-backend env-gated registration; docs (including the sender-verification
+   prerequisite checklist).
+2. **Delivery events + opt-outs** *(gated on inbound-webhooks IP)*: Event Webhook route
+   with ECDSA signature verification; event mapping per the table →
+   `DeliveryEvent`/`OptOutEvent` → `CommsMessage.status` + consumer hooks.
+
+## Feature Flags & Migrations
+
+None.
+
+## Activity Log & User Updates
+
+All sends logged to `CommsMessage` with provider `sendgrid`.
+
+## Not Included / Future Work
+
+- Suppression-list *management* (viewing/clearing SendGrid suppressions from admin) — the
+  adapter only reports suppression outcomes; a management surface can extend the
+  [comms-admin-dashboard](comms-admin-dashboard.md) later.
+- Unsubscribe-group configuration.
+- Batch sending beyond the multiple-recipient `to` array.
+
+## Files to Create / Modify
+
+- `comms/src/adapters/sendgrid.ts` + tests
+- `comms/package.json` — optional peer `@sendgrid/mail`
+- `example-backend/src/server.ts` — env-gated registration
+- `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+
+## Task List
+
+See [docs/tasks/comms-adapter-sendgrid.md](../tasks/comms-adapter-sendgrid.md).
+
+## Acceptance Criteria
+
+- [x] `sendMail` delivers text/html mail with from-address fallback chain (provider option
+      → `CommsApp.defaultFrom`), and passes `templateId`/`dynamicTemplateData` through when
+      given.
+- [x] Sandbox mode is on by default under test and produces accepted results without real
+      sends.
+- [x] SendGrid errors surface as `accepted: false` with the SendGrid error message and a
+      correct `errorCode`/`errorClass` per the classification table; nothing throws
+      through the facade.
+- [x] 401/403 classify as `config` and `logger.error` at send time; 429/5xx classify as
+      `transient` and retry once; other 4xx are `permanent` and never retried.
+- [x] Each accepted send captures the `x-message-id` and stores a `metadata.consoleUrl`
+      Email Activity deep link.
+- [x] Consumer `onError` fires with the classified `SendResult` on every failed send
+      (mocked-client test).
+- [x] Missing API key fails fast at `CommsApp` registration with a clear error.
+- [x] Apps not using the adapter do not install `@sendgrid/mail`.
+- [ ] (Phase 2) Event webhook updates `CommsMessage.status` per the mapping table only
+      for signature-verified payloads; bounce/dropped reasons land as `errorCode`.
+- [ ] (Phase 2) `spamreport`/`unsubscribe` events fire `onOptOut`; later sends to the
+      suppressed address record `dropped` as `permanent`.