@drawbridge/drawbridge-utils 0.0.124 → 0.0.126

package/dist/connections/index.cjs

@@ -251,7 +251,7 @@ var HOOKS = Object.freeze({
   ])
 });
 var HOOK_EFFECTS = Object.freeze(["enqueues", "events", "writes"]);
-var WRITE_OPERATIONS = Object.freeze(["create", "update"]);
+var WRITE_OPERATIONS = Object.freeze(["create", "delete", "update"]);
 var HOOK_PROPS = Object.freeze([
   "channel",
   "clientId",
@@ -311,9 +311,9 @@ var effectsOf = (answer) => {
     if (!WRITE_OPERATIONS.includes(write == null ? void 0 : write.operation)) {
       throw new Error("A described write on " + write.collection + " needs an operation \u2014 one of " + WRITE_OPERATIONS.join(", "));
     }
-    if (!(write == null ? void 0 : write.data)) throw new Error("A described write on " + write.collection + " carries no data");
-    if (write.operation === "update" && !write.query) {
-      throw new Error("A described update on " + write.collection + " has no query \u2014 that is every document in it");
+    if (write.operation !== "delete" && !(write == null ? void 0 : write.data)) throw new Error("A described write on " + write.collection + " carries no data");
+    if (["delete", "update"].includes(write.operation) && !write.query) {
+      throw new Error("A described " + write.operation + " on " + write.collection + " has no query \u2014 that is every document in it");
     }
     if (write.operation === "create" && write.query) {
       throw new Error("A described create on " + write.collection + " carries a query \u2014 create does not filter");
@@ -893,9 +893,13 @@ var attentive_default2 = {
     }
   },
   // WHY, in the merchant's words, and what to do about it.
+  // ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+  // is reconnecting — prompting "choose a segment" there asks the merchant to
+  // configure a grant that no longer exists. `pending` is exactly this task's
+  // moment: the grant is good and the segment is the missing half.
   tasks: (data2) => {
     var _a;
-    return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.segment) ? [] : [
+    return !["active", "pending"].includes(data2 == null ? void 0 : data2.status) || ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.segment) ? [] : [
       {
         message: "Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.",
         title: "Choose a segment"
@@ -905,6 +909,9 @@ var attentive_default2 = {
   title: "Attentive"
 };
 
+// lib/connections/providers/drawbridge.js
+var import_node_crypto2 = require("crypto");
+
 // lib/http.js
 var DEFAULT_TIMEOUT_MS = 15e3;
 var request = async ({
@@ -1731,6 +1738,8 @@ var channels = {
 };
 
 // lib/connections/providers/drawbridge.js
+var STOP_KEYWORDS = ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"];
+var START_KEYWORDS = ["START", "UNSTOP", "YES"];
 var interpolate = (template, data2) => {
   if (!template) return template;
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => (data2 == null ? void 0 : data2[key]) != null ? String(data2[key]) : "{{" + key + "}}");
@@ -1958,7 +1967,88 @@ var drawbridge_default2 = {
         };
       }
     },
-    inbound: false,
+    // INBOUND SMS to the platform number. Twilio's webhook, verified and
+    // processed HERE — the manifest owns its own inbound, the same as every
+    // other vendor, and the bespoke webhooks route + the handler that lived in
+    // sync's buffer table are gone.
+    inbound: {
+      // EVERY POST ON THIS CHANNEL IS AN INBOUND MESSAGE. Twilio sends no
+      // topic header — the registered url IS the topic.
+      event: () => "message.inbound",
+      // STOP AND START, AS DESCRIBED WRITES. A withdrawn number is withdrawn
+      // for everyone — organization : null is the platform floor canSend()
+      // reads on every send path. $setOnInsert + upsert so webhook replays
+      // and repeat STOPs collapse onto the unique { channel, address,
+      // organization } index instead of erroring.
+      process: ({ context }) => {
+        var _a, _b;
+        const keyword = String(((_a = context == null ? void 0 : context.data) == null ? void 0 : _a.Body) || "").trim().toUpperCase();
+        const address = toE164((_b = context == null ? void 0 : context.data) == null ? void 0 : _b.From);
+        if (!address) return { message: "Inbound SMS carried no usable sender number.", skipped: true };
+        if (STOP_KEYWORDS.includes(keyword)) {
+          return {
+            message: "STOP recorded \u2014 " + address + " is suppressed on SMS everywhere.",
+            request: { keyword },
+            writes: [{
+              collection: "suppression",
+              data: {
+                $setOnInsert: {
+                  address,
+                  channel: "sms",
+                  organization: null,
+                  reason: keyword,
+                  source: "stop"
+                }
+              },
+              operation: "update",
+              options: { upsert: true },
+              query: {
+                address,
+                channel: "sms",
+                organization: null
+              }
+            }]
+          };
+        }
+        if (START_KEYWORDS.includes(keyword)) {
+          return {
+            message: "START recorded \u2014 " + address + " can receive SMS again.",
+            request: { keyword },
+            writes: [{
+              collection: "suppression",
+              operation: "delete",
+              query: {
+                address,
+                channel: "sms",
+                organization: null
+              }
+            }]
+          };
+        }
+        return { message: "A real reply, not a keyword \u2014 nothing to record.", skipped: true };
+      },
+      receive: ({ payload }) => ({
+        data: payload,
+        provider: { id: (payload == null ? void 0 : payload.MessageSid) || null }
+      }),
+      // TWILIO'S SCHEME, from docs.twilio.com/usage/security: take the full
+      // registered url, sort the POST parameters alphabetically (Unix-style,
+      // case-sensitive), append each name and value with no delimiters, sign
+      // with HMAC-SHA1 keyed by the AuthToken, base64 — compared against
+      // X-Twilio-Signature. It signs the URL rather than the raw body, which
+      // is exactly why the shared body-HMAC verifier cannot cover it and this
+      // hook exists.
+      verify: ({ body, headers, secret, url }) => {
+        if (!secret) throw Object.assign(new Error("Missing webhook secret: TWILIO_AUTH_TOKEN"), { status: 500 });
+        const params = new URLSearchParams(String(body || ""));
+        const signed = url + [...params.keys()].sort().map((key) => key + params.get(key)).join("");
+        const expected = (0, import_node_crypto2.createHmac)("sha1", secret).update(signed).digest("base64");
+        const provided = String((headers == null ? void 0 : headers["x-twilio-signature"]) || "");
+        const matches = expected.length === provided.length && (0, import_node_crypto2.timingSafeEqual)(Buffer.from(expected), Buffer.from(provided));
+        if (!matches) throw Object.assign(new Error("Invalid Twilio signature"), { status: 401 });
+        return Object.fromEntries(params);
+      }
+    },
     lifecycle: false,
     resources: {
       audiences: false,
@@ -2137,6 +2227,18 @@ var drawbridge_default2 = {
     webhook: false
   },
   icon: drawbridge_default,
+  // WHERE TWILIO PUTS THINGS on an inbound request, and WHICH credential
+  // verifies it. `secret` names the drawbridge provider's smsToken — the route
+  // resolves the name to the stored value and hands it to verify.
+  inbound: {
+    headers: {
+      id: "i-twilio-idempotency-token",
+      signature: "x-twilio-signature"
+    },
+    signature: {
+      secret: "TWILIO_AUTH_TOKEN"
+    }
+  },
   // PRIVATE: never in the catalog, always available to the builder.
   private: true,
   // THE PLATFORM'S OWN SENDING CREDENTIALS — SendGrid, Twilio, and the internal
@@ -2752,9 +2854,13 @@ var klaviyo_default2 = {
     }
   },
   // WHY, in the merchant's words, and what to do about it.
+  // ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+  // is reconnecting — prompting "choose a list" there asks the merchant to
+  // configure a grant that no longer exists. `pending` is exactly this task's
+  // moment: the grant is good and the list is the missing half.
   tasks: (data2) => {
     var _a;
-    return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? [] : [
+    return !["active", "pending"].includes(data2 == null ? void 0 : data2.status) || ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? [] : [
       {
         message: "Choose which Klaviyo list your contacts should sync into. Until you do, nothing is being synced.",
         title: "Choose a list"
@@ -2765,7 +2871,7 @@ var klaviyo_default2 = {
 };
 
 // lib/connections/providers/mailchimp.js
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 
 // lib/connections/icons/mailchimp.js
 var mailchimp_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
@@ -2797,7 +2903,7 @@ var api3 = async (path, { dc, fetcher = fetch, method = "GET", payload, token })
   }
   return response.json();
 };
-var subscriberHash = (email) => (0, import_node_crypto2.createHash)("md5").update(String(email).trim().toLowerCase()).digest("hex");
+var subscriberHash = (email) => (0, import_node_crypto3.createHash)("md5").update(String(email).trim().toLowerCase()).digest("hex");
 var mailchimp_default2 = {
   // OAUTH 2, authorization code. Every url below is quoted from
   // mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/ rather
@@ -2839,7 +2945,7 @@ var mailchimp_default2 = {
   content: {
     confirm: "Disconnecting removes Drawbridge's stored Mailchimp access. You can also remove Drawbridge from the Authorized Apps page in your Mailchimp account. Your contacts stay in both Drawbridge and Mailchimp \u2014 neither list is deleted.",
     description: [
-      "Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Networking in your organization settings puts your own brand in the from line.",
+      "Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Messaging in your organization settings puts your own brand in the from line.",
       "Connecting Mailchimp lets Drawbridge sync the contacts your campaigns collect into a Mailchimp audience, so the people who enter a giveaway can be marketed to alongside the rest of your list.",
       "Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.",
       "Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before."
@@ -3067,9 +3173,13 @@ var mailchimp_default2 = {
     }
   },
   // WHY, in the merchant's words, and what to do about it.
+  // ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+  // is reconnecting — prompting "choose a audience" there asks the merchant to
+  // configure a grant that no longer exists. `pending` is exactly this task's
+  // moment: the grant is good and the audience is the missing half.
   tasks: (data2) => {
     var _a;
-    return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.audience) ? [] : [
+    return !["active", "pending"].includes(data2 == null ? void 0 : data2.status) || ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.audience) ? [] : [
       {
         message: "Choose which Mailchimp audience your contacts should sync into. Until you do, nothing is being synced.",
         title: "Choose an audience"
@@ -3080,7 +3190,7 @@ var mailchimp_default2 = {
 };
 
 // lib/connections/providers/shopify.js
-var import_node_crypto4 = require("crypto");
+var import_node_crypto5 = require("crypto");
 var import_nanoid2 = require("nanoid");
 
 // lib/connections/icons/shopify.js
@@ -3091,7 +3201,7 @@ var shopify_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill=
 </svg>`;
 
 // lib/connections/inbound.js
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var verifySignature = ({ body, descriptor, headers, secret }) => {
   if (!secret) {
     throw Object.assign(new Error("Missing webhook secret: " + descriptor.signature.secret), { status: 500 });
@@ -3100,10 +3210,10 @@ var verifySignature = ({ body, descriptor, headers, secret }) => {
   if (!provided) {
     throw Object.assign(new Error("Missing webhook signature"), { status: 401 });
   }
-  const digest = (0, import_node_crypto3.createHmac)(descriptor.signature.algorithm, secret).update(body).digest(descriptor.signature.encoding);
+  const digest = (0, import_node_crypto4.createHmac)(descriptor.signature.algorithm, secret).update(body).digest(descriptor.signature.encoding);
   const digestBuffer = Buffer.from(digest, descriptor.signature.encoding);
   const providedBuffer = Buffer.from(provided, descriptor.signature.encoding);
-  if (digestBuffer.length !== providedBuffer.length || !(0, import_node_crypto3.timingSafeEqual)(digestBuffer, providedBuffer)) {
+  if (digestBuffer.length !== providedBuffer.length || !(0, import_node_crypto4.timingSafeEqual)(digestBuffer, providedBuffer)) {
     throw Object.assign(new Error("Invalid webhook signature"), { status: 401 });
   }
   return JSON.parse(body.toString());
@@ -3842,7 +3952,7 @@ var shopify_default2 = {
                 event: "shopify.register.webhooks"
               },
               name: "register",
-              options: { jobId: "connection.update.register." + workflow.connection + "." + (0, import_node_crypto4.randomUUID)() },
+              options: { jobId: "connection.update.register." + workflow.connection + "." + (0, import_node_crypto5.randomUUID)() },
               queue: "connection"
             }],
             message: (scopesMissing == null ? void 0 : scopesMissing.length) ? "Health check: ping ok, webhooks reconciled \u2014 connection errored, granted scopes are missing: " + scopesMissing.join(", ") + "." : refreshTokenRotated ? "Health check passed \u2014 refresh token rotated, ping ok, webhooks reconciled." : "Health check passed \u2014 ping ok, webhooks reconciled.",
@@ -4129,7 +4239,7 @@ var shopify_default2 = {
 };
 
 // lib/connections/providers/webhook.js
-var import_node_crypto5 = __toESM(require("crypto"), 1);
+var import_node_crypto6 = __toESM(require("crypto"), 1);
 
 // lib/safe-http.js
 var import_dns2 = __toESM(require("dns"), 1);
@@ -4361,7 +4471,7 @@ var webhook_default = {
         request2.body = body;
         const outgoing = { ...headers };
         if (settings == null ? void 0 : settings.secret) {
-          outgoing["X-Drawbridge-Signature"] = "sha256=" + import_node_crypto5.default.createHmac("sha256", settings.secret).update(JSON.stringify(body)).digest("hex");
+          outgoing["X-Drawbridge-Signature"] = "sha256=" + import_node_crypto6.default.createHmac("sha256", settings.secret).update(JSON.stringify(body)).digest("hex");
         }
         const response = await send2({ body, headers: outgoing, method, url });
         return { message: "Webhook POSTed to " + url + ".", request: request2, response: response || { delivered: true } };
@@ -4407,7 +4517,10 @@ var webhook_default = {
   // pressing Connect will do; afterwards it states the verification the
   // merchant's own endpoint has to perform, because a signed payload nobody
   // checks is an unsigned payload.
-  tasks: ({ settings }) => (settings == null ? void 0 : settings.secret) ? [
+  // The connect prompt only where connecting is not already the card's whole
+  // story: a disconnected or errored document renders a Connect action itself,
+  // and a task repeating it talks over the button.
+  tasks: ({ settings, status } = {}) => ["disconnected", "error"].includes(status) ? [] : (settings == null ? void 0 : settings.secret) ? [
     {
       message: "Compute HMAC-SHA256( secret, body ) and compare against the X-Drawbridge-Signature header to confirm each payload.",
       title: "Requests must be verified",
@@ -4432,7 +4545,7 @@ var leaves = (node, path = []) => Object.entries(node || {}).flatMap(
   ([key, value]) => typeof value === "function" ? [[[...path, key].join("."), value]] : value && typeof value === "object" ? leaves(value, [...path, key]) : []
 );
 var build = (manifest) => {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t;
   if (!(manifest == null ? void 0 : manifest.slug)) throw new Error("A connection needs a slug");
   if (!(manifest == null ? void 0 : manifest.title)) throw new Error(manifest.slug + " needs a title");
   if (!(manifest == null ? void 0 : manifest.private) && !(manifest == null ? void 0 : manifest.feature)) throw new Error(manifest.slug + " needs a plan feature key");
@@ -4511,16 +4624,16 @@ var build = (manifest) => {
       );
     }
   }
-  if (implemented(manifest.hooks, "inbound.event") && !((_l = (_k = manifest.inbound) == null ? void 0 : _k.headers) == null ? void 0 : _l.event)) {
+  if (implemented(manifest.hooks, "inbound.event") && typeof ((_l = (_k = manifest.hooks) == null ? void 0 : _k.inbound) == null ? void 0 : _l.event) !== "function" && !((_n = (_m = manifest.inbound) == null ? void 0 : _m.headers) == null ? void 0 : _n.event)) {
     throw new Error(manifest.slug + " implements inbound.event but declares no inbound.headers.event");
   }
-  if (implemented(manifest.hooks, "inbound.verify") && !((_n = (_m = manifest.inbound) == null ? void 0 : _m.headers) == null ? void 0 : _n.signature)) {
+  if (implemented(manifest.hooks, "inbound.verify") && !((_p = (_o = manifest.inbound) == null ? void 0 : _o.headers) == null ? void 0 : _p.signature)) {
     throw new Error(manifest.slug + " implements inbound.verify but declares no inbound.headers.signature");
   }
   if (typeof (manifest == null ? void 0 : manifest.status) !== "function") {
     throw new Error(manifest.slug + " must declare status( data ) \u2014 return null to accept the connection's own status, or { message, status } to override it");
   }
-  if (!Array.isArray((_o = manifest == null ? void 0 : manifest.content) == null ? void 0 : _o.guide) || !manifest.content.guide.length) {
+  if (!Array.isArray((_q = manifest == null ? void 0 : manifest.content) == null ? void 0 : _q.guide) || !manifest.content.guide.length) {
     throw new Error(manifest.slug + " needs content.guide \u2014 an array of steps for its page");
   }
   if (typeof (manifest == null ? void 0 : manifest.status) !== "function") {
@@ -4532,8 +4645,8 @@ var build = (manifest) => {
   }
   for (const [domain, verbs] of Object.entries(HOOKS)) {
     for (const verb of verbs) {
-      const hook = (_q = (_p = manifest.hooks) == null ? void 0 : _p[domain]) == null ? void 0 : _q[verb];
-      if (((_r = manifest.hooks) == null ? void 0 : _r[domain]) === false) continue;
+      const hook = (_s = (_r = manifest.hooks) == null ? void 0 : _r[domain]) == null ? void 0 : _s[verb];
+      if (((_t = manifest.hooks) == null ? void 0 : _t[domain]) === false) continue;
       if (hook !== false && !implemented({ [domain]: { [verb]: hook } }, domain + "." + verb)) {
         throw new Error(manifest.slug + " must answer hooks." + domain + "." + verb + " \u2014 false, a function, or {} if another repo implements it");
       }

package/dist/connections/index.d.cts

@@ -1,9 +1,9 @@
 import { authToken } from './oauth.cjs';
 export { consentUrl, pkcePair } from './oauth.cjs';
 import { toE164, detectCountry } from '../phone.cjs';
+import crypto, { createHmac, timingSafeEqual, createHash, randomUUID } from 'node:crypto';
 import { request } from '../http.cjs';
 import { channels } from '../pricing.cjs';
-import crypto, { createHash, createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
 import { customAlphabet } from 'nanoid';
 import { toCanonicalEmail } from '../email.cjs';
 import { conversionRate } from '../plans.cjs';
@@ -282,7 +282,7 @@ const HOOK_EFFECTS = Object.freeze([ 'enqueues', 'events', 'writes' ]);
 // The controller methods a described write may become. Only the two that a hook
 // has ever needed — a deletion is a cascade, and cascades are owned by
 // drawbridge-sync's streams rather than by a step.
-const WRITE_OPERATIONS = Object.freeze([ 'create', 'update' ]);
+const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 
 // READ A HOOK'S EFFECTS, or refuse them.
 //
@@ -414,13 +414,15 @@ const effectsOf = ( answer ) => {
 
 		}
 
-		if( ! write?.data ) throw new Error( 'A described write on ' + write.collection + ' carries no data' );
+		// A delete says WHICH, not WHAT — its query is its whole statement.
+		if( write.operation !== 'delete' && ! write?.data ) throw new Error( 'A described write on ' + write.collection + ' carries no data' );
 
-		// AN UPDATE WITH NO QUERY IS EVERY DOCUMENT IN THE COLLECTION. Refused here
-		// rather than survived, because the controller would happily run it.
-		if( write.operation === 'update' && ! write.query ){
+		// AN UPDATE OR DELETE WITH NO QUERY IS EVERY DOCUMENT IN THE COLLECTION.
+		// Refused here rather than survived, because the controller would happily
+		// run it.
+		if( [ 'delete', 'update' ].includes( write.operation ) && ! write.query ){
 
-			throw new Error( 'A described update on ' + write.collection + ' has no query — that is every document in it' );
+			throw new Error( 'A described ' + write.operation + ' on ' + write.collection + ' has no query — that is every document in it' );
 
 		}
 
@@ -1233,7 +1235,11 @@ var attentive = {
 
 	},
 	// WHY, in the merchant's words, and what to do about it.
-	tasks : ( data ) => ( data?.settings?.segment
+	// ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+	// is reconnecting — prompting "choose a segment" there asks the merchant to
+	// configure a grant that no longer exists. `pending` is exactly this task's
+	// moment: the grant is good and the segment is the missing half.
+	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.segment
 		? []
 		: [
 			{
@@ -1573,6 +1579,14 @@ var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 </defs>
 </svg>`;
 
+// TWILIO'S OWN KEYWORD LISTS. STOP-family withdraws consent for the number —
+// platform-wide, because every organization sends from the same platform number,
+// so a withdrawal cannot be scoped narrower than the number it was sent to.
+// START-family re-subscribes. Anything else is a real reply and none of our
+// business.
+const STOP_KEYWORDS = [ 'STOP', 'STOPALL', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT' ];
+const START_KEYWORDS = [ 'START', 'UNSTOP', 'YES' ];
+
 // Drawbridge itself — the PRIVATE connection.
 //
 // Nobody connects this. There is no credential, no consent, and no card on the
@@ -1927,7 +1941,113 @@ var drawbridge = {
 			}
 
 		},
-		inbound : false,
+		// INBOUND SMS to the platform number. Twilio's webhook, verified and
+		// processed HERE — the manifest owns its own inbound, the same as every
+		// other vendor, and the bespoke webhooks route + the handler that lived in
+		// sync's buffer table are gone.
+		inbound : {
+
+			// EVERY POST ON THIS CHANNEL IS AN INBOUND MESSAGE. Twilio sends no
+			// topic header — the registered url IS the topic.
+			event : () => 'message.inbound',
+
+			// STOP AND START, AS DESCRIBED WRITES. A withdrawn number is withdrawn
+			// for everyone — organization : null is the platform floor canSend()
+			// reads on every send path. $setOnInsert + upsert so webhook replays
+			// and repeat STOPs collapse onto the unique { channel, address,
+			// organization } index instead of erroring.
+			process : ({ context }) => {
+
+				const keyword = String( context?.data?.Body || '' ).trim().toUpperCase();
+				const address = toE164( context?.data?.From );
+
+				if( ! address ) return { message : 'Inbound SMS carried no usable sender number.', skipped : true };
+
+				if( STOP_KEYWORDS.includes( keyword ) ){
+
+					return {
+						message : 'STOP recorded — ' + address + ' is suppressed on SMS everywhere.',
+						request : { keyword },
+						writes : [ {
+							collection : 'suppression',
+							data : {
+								$setOnInsert : {
+									address,
+									channel : 'sms',
+									organization : null,
+									reason : keyword,
+									source : 'stop'
+								}
+							},
+							operation : 'update',
+							options : { upsert : true },
+							query : {
+								address,
+								channel : 'sms',
+								organization : null
+							}
+						} ]
+					};
+
+				}
+
+				if( START_KEYWORDS.includes( keyword ) ){
+
+					return {
+						message : 'START recorded — ' + address + ' can receive SMS again.',
+						request : { keyword },
+						writes : [ {
+							collection : 'suppression',
+							operation : 'delete',
+							query : {
+								address,
+								channel : 'sms',
+								organization : null
+							}
+						} ]
+					};
+
+				}
+
+				return { message : 'A real reply, not a keyword — nothing to record.', skipped : true };
+
+			},
+
+			receive : ({ payload }) => ({
+				data : payload,
+				provider : { id : payload?.MessageSid || null }
+			}),
+
+			// TWILIO'S SCHEME, from docs.twilio.com/usage/security: take the full
+			// registered url, sort the POST parameters alphabetically (Unix-style,
+			// case-sensitive), append each name and value with no delimiters, sign
+			// with HMAC-SHA1 keyed by the AuthToken, base64 — compared against
+			// X-Twilio-Signature. It signs the URL rather than the raw body, which
+			// is exactly why the shared body-HMAC verifier cannot cover it and this
+			// hook exists.
+			verify : ({ body, headers, secret, url }) => {
+
+				// OUR misconfiguration, never a forgery — a missing credential must
+				// not be answered 401.
+				if( ! secret ) throw Object.assign( new Error( 'Missing webhook secret: TWILIO_AUTH_TOKEN' ), { status : 500 });
+
+				const params = new URLSearchParams( String( body || '' ) );
+
+				const signed = url + [ ...params.keys() ].sort().map( ( key ) => key + params.get( key ) ).join( '' );
+
+				const expected = createHmac( 'sha1', secret ).update( signed ).digest( 'base64' );
+				const provided = String( headers?.[ 'x-twilio-signature' ] || '' );
+
+				const matches = expected.length === provided.length
+					&& timingSafeEqual( Buffer.from( expected ), Buffer.from( provided ) );
+
+				if( ! matches ) throw Object.assign( new Error( 'Invalid Twilio signature' ), { status : 401 });
+
+				return Object.fromEntries( params );
+
+			}
+
+		},
 		lifecycle : false,
 		resources : {
 			audiences : false,
@@ -2196,6 +2316,19 @@ var drawbridge = {
 		webhook : false
 	},
 	icon: icon$3,
+
+	// WHERE TWILIO PUTS THINGS on an inbound request, and WHICH credential
+	// verifies it. `secret` names the drawbridge provider's smsToken — the route
+	// resolves the name to the stored value and hands it to verify.
+	inbound : {
+		headers : {
+			id : 'i-twilio-idempotency-token',
+			signature : 'x-twilio-signature'
+		},
+		signature : {
+			secret : 'TWILIO_AUTH_TOKEN'
+		}
+	},
 	// PRIVATE: never in the catalog, always available to the builder.
 	private : true,
 	// THE PLATFORM'S OWN SENDING CREDENTIALS — SendGrid, Twilio, and the internal
@@ -2959,7 +3092,11 @@ var klaviyo = {
 
 	},
 	// WHY, in the merchant's words, and what to do about it.
-	tasks : ( data ) => ( data?.settings?.list
+	// ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+	// is reconnecting — prompting "choose a list" there asks the merchant to
+	// configure a grant that no longer exists. `pending` is exactly this task's
+	// moment: the grant is good and the list is the missing half.
+	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.list
 		? []
 		: [
 			{
@@ -3089,7 +3226,7 @@ var mailchimp = {
 	content : {
 		confirm : 'Disconnecting removes Drawbridge\'s stored Mailchimp access. You can also remove Drawbridge from the Authorized Apps page in your Mailchimp account. Your contacts stay in both Drawbridge and Mailchimp — neither list is deleted.',
 		description : [
-			'Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Networking in your organization settings puts your own brand in the from line.',
+			'Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Messaging in your organization settings puts your own brand in the from line.',
 			'Connecting Mailchimp lets Drawbridge sync the contacts your campaigns collect into a Mailchimp audience, so the people who enter a giveaway can be marketed to alongside the rest of your list.',
 			'Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
 			'Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before.'
@@ -3392,7 +3529,11 @@ var mailchimp = {
 
 	},
 	// WHY, in the merchant's words, and what to do about it.
-	tasks : ( data ) => ( data?.settings?.audience
+	// ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+	// is reconnecting — prompting "choose a audience" there asks the merchant to
+	// configure a grant that no longer exists. `pending` is exactly this task's
+	// moment: the grant is good and the audience is the missing half.
+	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.audience
 		? []
 		: [
 			{
@@ -5003,7 +5144,12 @@ var webhook = {
 	// pressing Connect will do; afterwards it states the verification the
 	// merchant's own endpoint has to perform, because a signed payload nobody
 	// checks is an unsigned payload.
-	tasks : ( { settings } ) => ( settings?.secret
+	// The connect prompt only where connecting is not already the card's whole
+	// story: a disconnected or errored document renders a Connect action itself,
+	// and a task repeating it talks over the button.
+	tasks : ( { settings, status } = {} ) => ( [ 'disconnected', 'error' ].includes( status )
+		? []
+		: settings?.secret
 		? [
 			{
 				message : 'Compute HMAC-SHA256( secret, body ) and compare against the X-Drawbridge-Signature header to confirm each payload.',
@@ -5017,7 +5163,7 @@ var webhook = {
 				title : 'Webhook signing'
 			}
 		]
-	),
+	 ),
 	title : 'Webhooks'
 };
 
@@ -5315,7 +5461,17 @@ const build = ( manifest ) => {
 	// A vendor that receives from the outside must say where it puts the event
 	// name. Without it the receiver has nothing to dispatch on, and the failure
 	// is a request accepted and dropped rather than an error.
-	if( implemented( manifest.hooks, 'inbound.event' ) && ! manifest.inbound?.headers?.event ){
+	//
+	// A vendor may derive the event from the CHANNEL instead — Twilio sends no
+	// topic header, so drawbridge's inbound.event is a constant and the
+	// registered url is the topic. What is required is that SOMETHING names the
+	// event: a declared header, or an event hook that answers without one. The
+	// build cannot see inside the function, so the hook's existence is the
+	// declaration — and a hook that returns nothing still fails at the route,
+	// where a null event is refused before it is buffered.
+	if( implemented( manifest.hooks, 'inbound.event' )
+		&& typeof manifest.hooks?.inbound?.event !== 'function'
+		&& ! manifest.inbound?.headers?.event ){
 
 		throw new Error( manifest.slug + ' implements inbound.event but declares no inbound.headers.event' );