@drawbridge/drawbridge-utils 0.0.157 → 0.0.159

package/dist/providers.js

@@ -791,7 +791,53 @@ var attentive_default2 = {
 };
 
 // lib/connections/providers/drawbridge.js
-import { createHmac, timingSafeEqual } from "crypto";
+import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+
+// lib/connections/inbound.js
+import { createHmac, createVerify, timingSafeEqual } from "crypto";
+var verifySignature = ({ body, descriptor, headers, secret }) => {
+  if (!secret) {
+    throw Object.assign(new Error("Missing webhook secret: " + descriptor.signature.secret), { status: 500 });
+  }
+  const provided = headers[descriptor.headers.signature];
+  if (!provided) {
+    throw Object.assign(new Error("Missing webhook signature"), { status: 401 });
+  }
+  const digest = 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 || !timingSafeEqual(digestBuffer, providedBuffer)) {
+    throw Object.assign(new Error("Invalid webhook signature"), { status: 401 });
+  }
+  return JSON.parse(body.toString());
+};
+var REPLAY_TOLERANCE_SECONDS = 5 * 60;
+var asPem = (key) => [
+  "-----BEGIN PUBLIC KEY-----",
+  ...key.match(/.{1,64}/g) || [],
+  "-----END PUBLIC KEY-----"
+].join("\n");
+var verifyEcdsa = ({ body, descriptor, headers, secret }) => {
+  if (!secret) {
+    throw Object.assign(new Error("Missing webhook key: " + descriptor.signature.secret), { status: 500 });
+  }
+  const provided = headers[descriptor.headers.signature];
+  const timestamp = headers[descriptor.headers.timestamp];
+  if (!provided || !timestamp) {
+    throw Object.assign(new Error("Missing webhook signature"), { status: 401 });
+  }
+  const age = Math.abs(Math.floor(Date.now() / 1e3) - Number(timestamp));
+  if (!(age <= REPLAY_TOLERANCE_SECONDS)) {
+    throw Object.assign(new Error("Stale webhook signature"), { status: 401 });
+  }
+  const payload = Buffer.concat([Buffer.from(String(timestamp), "utf8"), body]);
+  const verified = createVerify("sha256").update(payload).verify(asPem(secret), Buffer.from(provided, "base64"));
+  if (!verified) {
+    throw Object.assign(new Error("Invalid webhook signature"), { status: 401 });
+  }
+  return JSON.parse(body.toString());
+};
+var readEventHeader = ({ descriptor, headers }) => headers[descriptor.headers.event];
 
 // lib/http.js
 var DEFAULT_TIMEOUT_MS = 15e3;
@@ -1682,6 +1728,144 @@ var MINIMUM_ACTION_CENTS = Math.round(
 // lib/connections/providers/drawbridge.js
 var STOP_KEYWORDS = ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"];
 var START_KEYWORDS = ["START", "UNSTOP", "YES"];
+var sendgridInbound = {
+  headers: {
+    signature: "x-twilio-email-event-webhook-signature",
+    timestamp: "x-twilio-email-event-webhook-timestamp"
+  },
+  signature: {
+    secret: "SENDGRID_EVENT_WEBHOOK_KEY"
+  }
+};
+var REFUSALS = /* @__PURE__ */ new Set(["blocked", "bounce", "deferred", "dropped", "spamreport"]);
+var DELIVERY = {
+  queued: 10,
+  sent: 20,
+  deferred: 30,
+  blocked: 40,
+  delivered: 50,
+  bounced: 60,
+  complained: 70
+};
+var fromSendgrid = (event) => {
+  if ((event == null ? void 0 : event.event) === "bounce") return event.type === "blocked" ? "blocked" : "bounced";
+  return {
+    blocked: "blocked",
+    deferred: "deferred",
+    delivered: "delivered",
+    dropped: "bounced",
+    processed: "queued",
+    spamreport: "complained"
+  }[event == null ? void 0 : event.event] || null;
+};
+var fromTwilio = (status) => ({
+  delivered: "delivered",
+  failed: "bounced",
+  queued: "queued",
+  sending: "sent",
+  sent: "sent",
+  undelivered: "bounced"
+})[String(status || "").toLowerCase()] || null;
+var deliveryWrite = ({ at, code: code2, notification, permanent, provider, reason, status }) => {
+  const rank = DELIVERY[status];
+  if (!notification || !rank) return null;
+  return {
+    collection: "notification",
+    data: {
+      $set: {
+        "meta.delivery": {
+          at: at || /* @__PURE__ */ new Date(),
+          ...code2 !== void 0 && code2 !== null && { code: String(code2) },
+          ...permanent !== void 0 && { permanent },
+          provider,
+          rank,
+          ...reason && { reason: String(reason) },
+          status
+        }
+      }
+    },
+    operation: "update",
+    query: {
+      id: notification,
+      // NEVER an upsert. A callback naming a notification we do not have is a
+      // vendor talking about someone else's message, not a document to create.
+      $or: [
+        { "meta.delivery.rank": { $exists: false } },
+        { "meta.delivery.rank": { $lt: rank } }
+      ]
+    }
+  };
+};
+var summariseEvents = (events) => {
+  const list = Array.isArray(events) ? events : [];
+  if (!list.length) return { message: "SendGrid delivered an empty event batch.", skipped: true };
+  const counts = {};
+  for (const { event } of list) {
+    const name = event || "unknown";
+    counts[name] = (counts[name] || 0) + 1;
+  }
+  const tally = Object.entries(counts).map(([name, count]) => count + " " + name).join(", ");
+  const refused = list.filter(({ event }) => REFUSALS.has(event)).slice(0, 5).map(({ email, reason, response, status }) => email + " \u2014 " + (reason || response || status || "no reason given"));
+  const writes = list.map((event) => {
+    var _a;
+    return deliveryWrite({
+      at: event.timestamp ? new Date(event.timestamp * 1e3) : void 0,
+      code: event.status,
+      // Read BOTH shapes. SendGrid echoes custom_args as siblings of `email`
+      // and `event`, which is why it warns about colliding with reserved
+      // names — but this is the one thing in the design that cannot be proved
+      // until a real event arrives, and reading the nested form too costs a
+      // token and removes the only silent failure left here.
+      notification: event.notification || ((_a = event.custom_args) == null ? void 0 : _a.notification),
+      // Only a bounce carries the distinction, and only a real one is
+      // permanent — `blocked` is this attempt refused, not this address dead.
+      ...event.event === "bounce" && { permanent: event.type !== "blocked" },
+      provider: { slug: "sendgrid", id: event.sg_message_id || null },
+      reason: event.reason || event.response,
+      status: fromSendgrid(event)
+    });
+  }).filter(Boolean);
+  return {
+    message: [list.length + " SendGrid event(s): " + tally, ...refused].join(" | "),
+    ...writes.length ? { writes } : { skipped: true }
+  };
+};
+var statusCallback = (data2) => {
+  const status = fromTwilio((data2 == null ? void 0 : data2.MessageStatus) || (data2 == null ? void 0 : data2.SmsStatus));
+  if (!status) return { message: "Twilio sent a status this does not map: " + ((data2 == null ? void 0 : data2.MessageStatus) || "none"), skipped: true };
+  const rank = DELIVERY[status];
+  const write = {
+    collection: "notification",
+    data: {
+      $set: {
+        "meta.delivery": {
+          at: /* @__PURE__ */ new Date(),
+          ...(data2 == null ? void 0 : data2.ErrorCode) && { code: String(data2.ErrorCode) },
+          // `failed` never left Twilio and `undelivered` was refused by the
+          // carrier. Both are dead ends for this handset, so neither is
+          // reported as a temporary condition.
+          ...status === "bounced" && { permanent: true },
+          provider: { slug: "twilio", id: (data2 == null ? void 0 : data2.MessageSid) || null },
+          rank,
+          ...(data2 == null ? void 0 : data2.ErrorMessage) && { reason: String(data2.ErrorMessage) },
+          status
+        }
+      }
+    },
+    operation: "update",
+    query: {
+      "meta.delivery.provider.id": data2 == null ? void 0 : data2.MessageSid,
+      $or: [
+        { "meta.delivery.rank": { $exists: false } },
+        { "meta.delivery.rank": { $lt: rank } }
+      ]
+    }
+  };
+  return {
+    message: "Twilio " + status + " for " + ((data2 == null ? void 0 : data2.MessageSid) || "an unnamed message") + ((data2 == null ? void 0 : data2.ErrorCode) ? " (" + data2.ErrorCode + ")" : ""),
+    ...(data2 == null ? void 0 : data2.MessageSid) ? { writes: [write] } : { skipped: true }
+  };
+};
 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 + "}}");
@@ -1925,18 +2109,27 @@ var drawbridge_default2 = {
     // 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",
+      // THE REGISTERED URL IS THE TOPIC. Neither vendor sends a topic header,
+      // so the channel it arrived on names the event — `sms` is one inbound
+      // message, `email` is a batch of SendGrid delivery events.
+      //
+      // Defaulted because the drain calls `event()` with nothing when it only
+      // wants the SMS name.
+      event: ({ channel } = {}) => ({
+        email: "email.events",
+        "sms-status": "sms.status"
+      })[channel] || "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);
+        var _a, _b, _c;
+        if ((context == null ? void 0 : context.topic) === "email.events") return summariseEvents((_a = context == null ? void 0 : context.data) == null ? void 0 : _a.events);
+        if ((context == null ? void 0 : context.topic) === "sms.status") return statusCallback(context == null ? void 0 : context.data);
+        const keyword = String(((_b = context == null ? void 0 : context.data) == null ? void 0 : _b.Body) || "").trim().toUpperCase();
+        const address = toE164((_c = context == null ? void 0 : context.data) == null ? void 0 : _c.From);
         if (!address) return { message: "Inbound SMS carried no usable sender number.", skipped: true };
         if (STOP_KEYWORDS.includes(keyword)) {
           return {
@@ -1980,9 +2173,24 @@ var drawbridge_default2 = {
         }
         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 }
+      // A SendGrid batch carries many sg_message_ids and no single identity, so
+      // it names no provider id. That means no dedupe key for a redelivery —
+      // acceptable because SendGrid only retries a non-2xx, and the cost of a
+      // duplicate here is a second buffer row rather than a repeated side
+      // effect. Revisit if this ever writes suppressions.
+      //
+      // THE BATCH IS WRAPPED, and it has to be. SendGrid posts a JSON ARRAY
+      // where every other vendor posts an object, and drawbridge-api's
+      // schema/buffer.js declares `data : { bsonType : 'object' }` — which in
+      // JSON Schema does NOT match an array. Writing the array raw fails
+      // validation, answers 500, and puts SendGrid into a retry loop for a
+      // webhook we would never accept.
+      //
+      // Wrapped here rather than widening the schema: `data` stays one shape
+      // for every consumer, and the vendor that is odd carries the oddity.
+      receive: ({ channel, payload }) => ({
+        data: channel === "email" ? { events: payload } : payload,
+        provider: { id: channel === "email" ? null : (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,
@@ -1991,13 +2199,14 @@ var drawbridge_default2 = {
       // 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 }) => {
+      verify: ({ body, channel, headers, secret, url }) => {
+        if (channel === "email") return verifyEcdsa({ body, descriptor: sendgridInbound, headers, secret });
         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 expected = createHmac2("sha1", secret).update(signed).digest("base64");
         const provided = String((headers == null ? void 0 : headers["x-twilio-signature"]) || "");
-        const matches = expected.length === provided.length && timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
+        const matches = expected.length === provided.length && timingSafeEqual2(Buffer.from(expected), Buffer.from(provided));
         if (!matches) throw Object.assign(new Error("Invalid Twilio signature"), { status: 401 });
         return Object.fromEntries(params);
       }
@@ -2181,15 +2390,30 @@ var drawbridge_default2 = {
   },
   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.
+  // verifies each channel. The route resolves the NAME to the stored value and
+  // hands it to verify; this manifest never reads a store.
+  //
+  // `signature.channels` because this is the one manifest that receives from two
+  // different vendors — Twilio on `sms`, SendGrid on `email` — which need
+  // different credentials and share no scheme. A manifest whose channels all
+  // verify the same way keeps declaring `signature` flat, and the route falls
+  // back to it; Shopify's two channels do exactly that.
   inbound: {
     headers: {
       id: "i-twilio-idempotency-token",
       signature: "x-twilio-signature"
     },
     signature: {
-      secret: "TWILIO_AUTH_TOKEN"
+      channels: {
+        email: sendgridInbound.signature,
+        sms: { secret: "TWILIO_AUTH_TOKEN" },
+        // Outbound delivery receipts, which Twilio signs exactly as it signs
+        // an inbound message — same scheme, same credential, different url.
+        // Separate channel because the payload is a MessageStatus rather than
+        // a message, and conflating them would put a STOP keyword check on a
+        // delivery receipt.
+        "sms-status": { secret: "TWILIO_AUTH_TOKEN" }
+      }
     }
   },
   // PRIVATE: never in the catalog, always available to the builder.
@@ -2221,6 +2445,13 @@ var drawbridge_default2 = {
           // Optional: SENDGRID_SEND_FROM_ADDRESS is not boot-required in sync
           // either. Unset, it degrades to the account sender rather than
           // refusing to start.
+          // NOT redacted, because it is a PUBLIC key. Marking it secret would
+          // be theatre, and it would stop an operator reading back the value
+          // they need to compare against the SendGrid console.
+          //
+          // Optional: absent, the event webhook answers 500 on verify rather
+          // than accepting unverified deliveries, and nothing else notices.
+          { input: "text", key: "eventKey", credential: "SENDGRID_EVENT_WEBHOOK_KEY", label: "Event webhook key", message: "SendGrid, Settings, Mail Settings, Event Webhook \u2014 the verification key shown once signature verification is enabled. Public, not a secret." },
           { input: "email", key: "leadSender", credential: "SENDGRID_SEND_FROM_ADDRESS", label: "Lead sender", message: "The default for lead-facing mail when a merchant has not verified their own domain." }
         ],
         icon: sendgrid_default,
@@ -3335,26 +3566,6 @@ var shopify_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill=
 <path d="M300.325 382.771L368 365.96C368 365.96 338.904 169.185 338.689 167.892C338.473 166.599 337.396 165.737 336.318 165.737C335.24 165.737 316.274 165.306 316.274 165.306C316.274 165.306 304.636 154.099 300.325 149.788V382.771Z" fill="white"/>
 </svg>`;
 
-// lib/connections/inbound.js
-import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
-var verifySignature = ({ body, descriptor, headers, secret }) => {
-  if (!secret) {
-    throw Object.assign(new Error("Missing webhook secret: " + descriptor.signature.secret), { status: 500 });
-  }
-  const provided = headers[descriptor.headers.signature];
-  if (!provided) {
-    throw Object.assign(new Error("Missing webhook signature"), { status: 401 });
-  }
-  const digest = createHmac2(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 || !timingSafeEqual2(digestBuffer, providedBuffer)) {
-    throw Object.assign(new Error("Invalid webhook signature"), { status: 401 });
-  }
-  return JSON.parse(body.toString());
-};
-var readEventHeader = ({ descriptor, headers }) => headers[descriptor.headers.event];
-
 // lib/email.js
 var GMAIL_DOMAINS = /* @__PURE__ */ new Set(["gmail.com", "googlemail.com"]);
 var toCanonicalEmail = (value) => {

package/dist/sendgrid.cjs

@@ -115,11 +115,27 @@ var sendgrid = {
   // `headers` (optional) carries the List-Unsubscribe pair on lead-facing
   // commercial sends; omitted, the request body is byte-identical to the
   // pre-opt-out-floor shape so system mail is untouched.
-  send: async ({ apiKey, from, headers, html, request: request2, subject, text, to }) => {
+  // `args` (optional) rides out as SendGrid's custom_args and comes BACK on every
+  // Event Webhook event for the message. That is what makes a delivery event
+  // answerable: an event carries the recipient and the receiving server's
+  // reason, but nothing about who we sent as or why, so without these a bounce
+  // cannot be told from a lead send or a member one.
+  //
+  // Cheaper than the alternative, which was storing SendGrid's message id on the
+  // notification and joining on it — a schema-gated field, and schema-gated
+  // fields have to ship api-first and booted. This needs no collection to change.
+  //
+  // String values only, 10,000 bytes total (SendGrid's limit). One caveat worth
+  // knowing when reading events: a bounce delivered asynchronously against the
+  // Return-Path does not carry them.
+  send: async ({ apiKey, args, from, headers, html, request: request2, subject, text, to }) => {
     var _a, _b;
     try {
       if (!(from == null ? void 0 : from.email)) throw new Error("SendGrid sender missing \u2014 pass from.email (the drawbridge provider's accountSender)");
       const sender = { name: "Drawbridge", ...from };
+      const custom = Object.fromEntries(
+        Object.entries(args || {}).filter(([, value]) => value !== void 0 && value !== null && value !== "").map(([key, value]) => [key, String(value)])
+      );
       await sendWithRetry(() => sendgridRequest({
         apiKey,
         ...request2 && { request: request2 },
@@ -137,6 +153,7 @@ var sendgrid = {
             }
           ],
           from: sender,
+          ...Object.keys(custom).length && { custom_args: custom },
           ...headers && { headers },
           personalizations: [
             {

package/dist/sendgrid.d.cts

@@ -114,7 +114,20 @@ const sendgrid = {
 	// `headers` (optional) carries the List-Unsubscribe pair on lead-facing
 	// commercial sends; omitted, the request body is byte-identical to the
 	// pre-opt-out-floor shape so system mail is untouched.
-	send : async ({ apiKey, from, headers, html, request, subject, text, to }) => {
+	// `args` (optional) rides out as SendGrid's custom_args and comes BACK on every
+	// Event Webhook event for the message. That is what makes a delivery event
+	// answerable: an event carries the recipient and the receiving server's
+	// reason, but nothing about who we sent as or why, so without these a bounce
+	// cannot be told from a lead send or a member one.
+	//
+	// Cheaper than the alternative, which was storing SendGrid's message id on the
+	// notification and joining on it — a schema-gated field, and schema-gated
+	// fields have to ship api-first and booted. This needs no collection to change.
+	//
+	// String values only, 10,000 bytes total (SendGrid's limit). One caveat worth
+	// knowing when reading events: a bounce delivered asynchronously against the
+	// Return-Path does not carry them.
+	send : async ({ apiKey, args, from, headers, html, request, subject, text, to }) => {
 
 		try {
 
@@ -127,6 +140,15 @@ const sendgrid = {
 
 			const sender = { name : 'Drawbridge', ...from };
 
+			// Coerced and pruned here rather than at every call site. SendGrid
+			// rejects a non-string value outright, and an absent one would come back
+			// as the literal "undefined" on every event it tagged.
+			const custom = Object.fromEntries(
+				Object.entries( args || {} )
+					.filter( ( [ , value ] ) => value !== undefined && value !== null && value !== '' )
+					.map( ( [ key, value ] ) => [ key, String( value ) ] )
+			);
+
 			await sendWithRetry( () => sendgridRequest({
 				apiKey,
 				...( request && { request }),
@@ -144,6 +166,7 @@ const sendgrid = {
 						}
 					],
 					from : sender,
+					...( Object.keys( custom ).length && { custom_args : custom } ),
 					...( headers && { headers } ),
 					personalizations : [
 						{

package/dist/sendgrid.d.ts

@@ -114,7 +114,20 @@ const sendgrid = {
 	// `headers` (optional) carries the List-Unsubscribe pair on lead-facing
 	// commercial sends; omitted, the request body is byte-identical to the
 	// pre-opt-out-floor shape so system mail is untouched.
-	send : async ({ apiKey, from, headers, html, request, subject, text, to }) => {
+	// `args` (optional) rides out as SendGrid's custom_args and comes BACK on every
+	// Event Webhook event for the message. That is what makes a delivery event
+	// answerable: an event carries the recipient and the receiving server's
+	// reason, but nothing about who we sent as or why, so without these a bounce
+	// cannot be told from a lead send or a member one.
+	//
+	// Cheaper than the alternative, which was storing SendGrid's message id on the
+	// notification and joining on it — a schema-gated field, and schema-gated
+	// fields have to ship api-first and booted. This needs no collection to change.
+	//
+	// String values only, 10,000 bytes total (SendGrid's limit). One caveat worth
+	// knowing when reading events: a bounce delivered asynchronously against the
+	// Return-Path does not carry them.
+	send : async ({ apiKey, args, from, headers, html, request, subject, text, to }) => {
 
 		try {
 
@@ -127,6 +140,15 @@ const sendgrid = {
 
 			const sender = { name : 'Drawbridge', ...from };
 
+			// Coerced and pruned here rather than at every call site. SendGrid
+			// rejects a non-string value outright, and an absent one would come back
+			// as the literal "undefined" on every event it tagged.
+			const custom = Object.fromEntries(
+				Object.entries( args || {} )
+					.filter( ( [ , value ] ) => value !== undefined && value !== null && value !== '' )
+					.map( ( [ key, value ] ) => [ key, String( value ) ] )
+			);
+
 			await sendWithRetry( () => sendgridRequest({
 				apiKey,
 				...( request && { request }),
@@ -144,6 +166,7 @@ const sendgrid = {
 						}
 					],
 					from : sender,
+					...( Object.keys( custom ).length && { custom_args : custom } ),
 					...( headers && { headers } ),
 					personalizations : [
 						{

package/dist/sendgrid.js

@@ -88,11 +88,27 @@ var sendgrid = {
   // `headers` (optional) carries the List-Unsubscribe pair on lead-facing
   // commercial sends; omitted, the request body is byte-identical to the
   // pre-opt-out-floor shape so system mail is untouched.
-  send: async ({ apiKey, from, headers, html, request: request2, subject, text, to }) => {
+  // `args` (optional) rides out as SendGrid's custom_args and comes BACK on every
+  // Event Webhook event for the message. That is what makes a delivery event
+  // answerable: an event carries the recipient and the receiving server's
+  // reason, but nothing about who we sent as or why, so without these a bounce
+  // cannot be told from a lead send or a member one.
+  //
+  // Cheaper than the alternative, which was storing SendGrid's message id on the
+  // notification and joining on it — a schema-gated field, and schema-gated
+  // fields have to ship api-first and booted. This needs no collection to change.
+  //
+  // String values only, 10,000 bytes total (SendGrid's limit). One caveat worth
+  // knowing when reading events: a bounce delivered asynchronously against the
+  // Return-Path does not carry them.
+  send: async ({ apiKey, args, from, headers, html, request: request2, subject, text, to }) => {
     var _a, _b;
     try {
       if (!(from == null ? void 0 : from.email)) throw new Error("SendGrid sender missing \u2014 pass from.email (the drawbridge provider's accountSender)");
       const sender = { name: "Drawbridge", ...from };
+      const custom = Object.fromEntries(
+        Object.entries(args || {}).filter(([, value]) => value !== void 0 && value !== null && value !== "").map(([key, value]) => [key, String(value)])
+      );
       await sendWithRetry(() => sendgridRequest({
         apiKey,
         ...request2 && { request: request2 },
@@ -110,6 +126,7 @@ var sendgrid = {
             }
           ],
           from: sender,
+          ...Object.keys(custom).length && { custom_args: custom },
           ...headers && { headers },
           personalizations: [
             {

package/package.json

@@ -216,5 +216,5 @@
     "prepublishOnly": ". \"$HOME/.nvm/nvm.sh\" && nvm use && tsup && node --test"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.157"
+  "version": "0.0.159"
 }