@drawbridge/drawbridge-agents 0.1.36 → 0.1.38

package/conventions/cross-repo-contracts.md

@@ -9,6 +9,11 @@ skill) so it stops living only in tribal memory.
 
 - `OAUTH_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
   `assertEnv` it at boot. A mismatch silently breaks realtime token verification.
+- `UNSUBSCRIBE_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** —
+  both `assertEnv` it at boot. Sync signs the unsubscribe tokens it builds into notification
+  emails (`lib/suppression.js buildToken`); api verifies them on the public `/unsubscribe/:token`
+  routes (`lib/unsubscribe.js`). A mismatch makes every unsubscribe link 404 as "invalid or
+  expired" — one-click unsubscribes silently stop landing, which mail providers punish.
 - reCAPTCHA on auth is a key pair: `GOOGLE_RECAPTCHA_SECRET` (**drawbridge-api**) + `NEXT_PUBLIC_GOOGLE_RECAPTCHA_KEY`
   (**drawbridge-app-web**), both `assertEnv`'d at boot. The api verifies the v3 token app-web's
   `/auth` forms attach and enforces it **unconditionally** on `/oauth/{signup,signin}/request`
@@ -48,6 +53,28 @@ skill) so it stops living only in tribal memory.
   `ads-republishing.<connectionId>`). Never unique-index `coalesce` (superseding requires the
   second insert to land), and writes that set `key` need the writer-side E11000 handler or a
   replayed event logs a false error.
+- **The opt-out floor: `suppression` is the single consent gate** (api ↔ sync ↔ webhooks).
+  Writers: api's `/unsubscribe` routes and draw preflight, sync's twilio buffer drain
+  (`lib/buffer.js 'twilio.message.inbound'`). The ONLY reader on any send path is sync
+  `lib/suppression.js canSend()` — a new lead-facing send path must call it, or opted-out
+  recipients get contacted (TCPA/CAN-SPAM exposure). Lead-facing = the notification carries
+  `lead`/`workflow`/`connection`; those sends also REQUIRE an org connection (no system-sender
+  fallback), while org-less system mail (OTC codes, member invites, security notices) keeps the
+  system sender and is never suppressed. Inbound STOP flows webhooks
+  (`POST /connection/:id/twilio`, signature-verified against the URL built from
+  `APP_CLIENT_WEBHOOKS_URI`) → `buffer` doc → sync drain → platform-global suppression row;
+  api registers the number's SmsUrl at twilio connect (`lib/twilio.js`) and `scripts.js
+  registerTwilioWebhooks` backfills — a deployed webhooks route with unregistered numbers hears
+  nothing, silently.
+- **Adding an email/SMS vendor is a two-repo change** (api ↔ sync). A connection is deliverable
+  only if sync implements a sender for its slug — `lib/email.js` (`{ mailchimp, sendgrid }`) and
+  `lib/sms.js` (`{ twilio }`), which `queue/notification.js` reads **directly** as its guard and
+  org-scoped lookup; never re-list the slugs as literals, or the guard drifts from the senders
+  that exist. Adding a vendor to drawbridge-api `lib/connections.js` with `group : 'email'`/`'sms'`
+  makes it selectable throughout api and app-web, but with no sync sender every send is
+  cancelled, not delivered — merchant sees a workflow that ran and no message. The miss is
+  detectable, not silent: `notification.reason = 'connection-slug-mismatch'` plus an
+  Error-instance `logger.error` (a string never reaches Sentry Issues — see `sentry-sdk.md`).
 - Schema-gated fields ship **api-first, booted**: a sibling writer setting a field new to a
   drawbridge-api `$jsonSchema` (validators are strict + `additionalProperties: false`) must not
   go live until the api has **booted** with the schema change on that environment — creating the
@@ -208,6 +235,33 @@ skill) so it stops living only in tribal memory.
   drawbridge-utils (15 min). The prize-draw branch is a genuinely different 5 min
   (api `route/otc.js` CODE_TTL_MINUTES) — the two are not interchangeable.
 
+## Submission answers are immutable (api ↔ sync ↔ app-web ↔ share)
+
+- **Nothing rewrites `submission.fields[]` after the write.** Renaming a field or one of its
+  options, and deleting a field, all used to reach back into every stored submission (`$set` on
+  `fields.$[element].label` / `.value`, `$pull` by `reference`). An answer is the record of what a
+  person was asked and said; a definition change must not touch it. The link forward is
+  `fields[].reference` (the field id) and, for choice answers, `fields[].option` (the option id
+  captured at submission time) — text is display, ids are identity.
+- **Deleting a field is a tombstone**, `deleted : true`, never a `delete`. Every live read must
+  filter `deleted : { $ne : true }` — api's builder field list, create position count, delete
+  position decrement, and the share `campaign-fields` cache aggregate; sync's leads exporter and
+  the nightly `totals.fields` recount. The **lead-detail endpoint deliberately does not filter**:
+  app-web pivots `fieldsById[reference]`, so returning tombstoned definitions is the only thing
+  keeping a removed field's historical answers displayable (it labels them `(removed)`).
+- Because the doc survives, **`stream/field.js`'s `delete` handler never fires for a removal** —
+  its `update` handler watches `updateDescription.updatedFields.deleted === true` for the
+  `campaign.totals.fields` decrement and cache-chain invalidation. A new consumer of field
+  deletion must hook the transition, not the delete.
+- **Field validators live in `@drawbridge/drawbridge-utils/fields-validate`**, consumed by BOTH
+  drawbridge-share's form and drawbridge-api's submission POST — `yup` is injected so each keeps
+  its own copy. A rule added on one side only is client-side theater: the submission endpoint is
+  publicly reachable. `select` is checked in-list against the field's own options; `required()`
+  honours `attributes.required === false`.
+- **`scripts/backfill-submission-option-ids.js` must run before any further option rename lands.**
+  It matches legacy answers to options by text one last time; once a definition and its stored
+  text diverge, nothing can match them again.
+
 ## Growth attribution tags (growth ↔ api)
 
 - drawbridge-growth `lib/tags.js` MIRRORS drawbridge-api `lib/utm.js` — allow-listed keys, trim,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {