@drawbridge/drawbridge-utils 0.0.156 → 0.0.158

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.156"
+  "version": "0.0.158"
 }