@drawbridge/drawbridge-utils 0.0.162 → 0.0.164

package/dist/connections/index.cjs

@@ -634,10 +634,15 @@ var attentive_default2 = {
       "Attentive accepts these updates and applies them in the background, so a contact appears in your segment shortly after the sync rather than the instant it runs."
     ],
     excerpt: "Sync your Drawbridge contacts into an Attentive segment.",
+    // NAMES THE SEGMENT STEP, because `status` below gates on it: a grant with
+    // no segment chosen sits at Pending, and a guide that stops at the consent
+    // leaves a merchant looking at a connection they think is broken. Same
+    // omission Klaviyo's guide already carries a note about.
     guide: [
       "Press Connect. Drawbridge sends you to Attentive to approve access.",
       "Sign in to Attentive if you are not already, and authorize the permissions listed.",
-      "You are returned here \u2014 choose which Attentive segment your contacts should sync into."
+      "You come back here to choose which Attentive segment your contacts should sync into.",
+      "The connection shows Pending until you choose a segment, then Active."
     ]
   },
   // A contact destination, like Klaviyo and Mailchimp — a merchant could
@@ -900,6 +905,9 @@ var attentive_default2 = {
         // merchant would recognise in a builder label.
         key: "Sync contact to Attentive",
         queue: "connection",
+        // Attentive applies the update in the background and returns no id we
+        // could hand on, so there is nothing for a later step to interpolate.
+        returns: [],
         // Nothing for a merchant to configure on the step itself — the segment
         // is chosen once on the connection. Declared empty rather than omitted,
         // so "this step takes no settings" and "nobody thought about settings"
@@ -2127,13 +2135,18 @@ var drawbridge_default2 = {
           request: request2,
           response: { count, notified: recipients.length },
           writes: recipients.map((member) => {
-            var _a2, _b2;
+            var _a2, _b2, _c2;
             return queueNotification({
               audience: "member",
               message: interpolate((_a2 = step.settings) == null ? void 0 : _a2.message, values),
               organization: workflow.organization,
               send: { type: "email", email: member.email },
-              title: interpolate((_b2 = step.settings) == null ? void 0 : _b2.subject, values),
+              // The editor's plain rendering, interpolated the same way so
+              // {{count}} resolves in the text part too. Spread rather than
+              // written as null: a step saved before `text` existed has none,
+              // and the send path strips the markup itself for those.
+              ...((_b2 = step.settings) == null ? void 0 : _b2.text) && { text: interpolate(step.settings.text, values) },
+              title: interpolate((_c2 = step.settings) == null ? void 0 : _c2.subject, values),
               workflow: workflow.id
             });
           })
@@ -2202,7 +2215,7 @@ var drawbridge_default2 = {
       // unsubscribe token and the CAN-SPAM footer. The step's job is to say who
       // and what, correctly, and to refuse early when it must not send at all.
       send: async ({ context, step, workflow }, { canSend, read } = {}) => {
-        var _a, _b;
+        var _a, _b, _c;
         const to = context == null ? void 0 : context.email;
         if (!to) throw new Error("No email address on context (context.email is required)");
         const request2 = { to };
@@ -2239,7 +2252,11 @@ var drawbridge_default2 = {
               message: interpolate((_a = step.settings) == null ? void 0 : _a.message, context),
               organization: workflow.organization,
               send: { type: "email", email: to },
-              title: interpolate((_b = step.settings) == null ? void 0 : _b.subject, context),
+              // The editor's plain rendering, so the text/plain part of this
+              // email is what the merchant wrote rather than a regex's guess at
+              // it. See the digest above for why it is spread, not nulled.
+              ...((_b = step.settings) == null ? void 0 : _b.text) && { text: interpolate(step.settings.text, context) },
+              title: interpolate((_c = step.settings) == null ? void 0 : _c.subject, context),
               workflow: workflow.id
             })
           ]
@@ -2659,6 +2676,11 @@ var drawbridge_default2 = {
         hook: "email.digest",
         key: "Email \u2014 Digest",
         queue: "notification",
+        // Nothing for a later step to interpolate. Declared empty rather than
+        // omitted, so "this step leaves nothing behind" and "nobody thought
+        // about it" stay different statements — the second is what emptied the
+        // builder's Variables menu for every step in the product.
+        returns: [],
         settings: {
           // The organization OWNER is always a recipient, resolved by the
           // hook, so this is additional recipients rather than the list. It
@@ -2667,7 +2689,22 @@ var drawbridge_default2 = {
           // pick and could never save the step.
           members: { of: "string", type: "array" },
           message: { max: 2e3, required: true, type: "string" },
-          subject: { max: 150, required: true, type: "string" }
+          // THE LAST SPAM CHECK, stored beside the copy it measured. Shape is
+          // pinned no further than the pair that proves the match, which is the
+          // only part the api reads; the rest is SpamAssassin's own output and
+          // is stored as it arrives. Same declaration the campaign's draw
+          // notification validates against.
+          //
+          // Undeclared, this was silently dropped at submit — the settings
+          // validator is noUnknown().strict(), so the dashboard's step form
+          // mapped the key away rather than 400 — and every open of a workflow
+          // step re-ran a check against a free service to be told what the last
+          // open had already been told.
+          score: { shape: { message: { type: "string" }, subject: { type: "string" } }, type: "object" },
+          subject: { max: 150, required: true, type: "string" },
+          // The editor's plain rendering of `message`, written beside it rather
+          // than reconstructed by running a regex over the markup at send time.
+          text: { max: 2e3, type: "string" }
         },
         triggers: ["schedule.day", "schedule.week", "schedule.month"],
         usage: { actions: 0 }
@@ -2688,6 +2725,7 @@ var drawbridge_default2 = {
         hook: "email.notify",
         key: "Email \u2014 Notification",
         queue: "notification",
+        returns: [],
         settings: {
           members: { of: "string", type: "array" },
           message: { max: 2e3, type: "string" },
@@ -2704,9 +2742,14 @@ var drawbridge_default2 = {
         hook: "email.send",
         key: "Email \u2014 Send email",
         queue: "notification",
+        returns: [],
         settings: {
           message: { max: 2e3, required: true, type: "string" },
-          subject: { max: 150, required: true, type: "string" }
+          // See email.digest above — the last spam check, and the editor's
+          // plain rendering of the message.
+          score: { shape: { message: { type: "string" }, subject: { type: "string" } }, type: "object" },
+          subject: { max: 150, required: true, type: "string" },
+          text: { max: 2e3, type: "string" }
         },
         triggers: ["lead.insert"],
         // ONE SOURCE FOR THE PRICE. lib/pricing.js is the index of every
@@ -3305,6 +3348,13 @@ var klaviyo_default2 = {
           // than a label that could be any of their Klaviyo accounts.
           key: "Sync contact to " + (((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.account) || "Klaviyo"),
           queue: "connection",
+          // The key the hook puts in `context`, which the runner merges into the
+          // run so a later step can interpolate {{klaviyoProfileId}}. Declared
+          // beside the hook that writes it — see the note on Shopify's
+          // commerce.code, which is where this came back from.
+          returns: [
+            { key: "klaviyoProfileId", label: "Klaviyo Profile ID" }
+          ],
           // Nothing for a merchant to configure on the step itself — the list
           // is chosen once on the connection. Declared empty rather than
           // omitted, so "this step takes no settings" and "nobody thought about
@@ -3420,10 +3470,15 @@ var mailchimp_default2 = {
       "Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before."
     ],
     excerpt: "Sync your Drawbridge contacts into a Mailchimp audience.",
+    // NAMES THE AUDIENCE STEP, because `status` below gates on it: a grant with
+    // no audience chosen sits at Pending, and a guide that stops at the consent
+    // leaves a merchant looking at a connection they think is broken.
     guide: [
       "Press Connect. Drawbridge sends you to Mailchimp to approve access.",
       "Sign in to Mailchimp if you are not already, and choose the account to connect.",
-      "You come back here to pick the audience your contacts should sync into."
+      "You come back here to pick the audience your contacts should sync into.",
+      "The connection shows Pending until you pick an audience, then Active.",
+      "You can remove Drawbridge at any time from the Authorized Apps page in your Mailchimp account."
     ]
   },
   // Mailchimp and SendGrid shared a group while they were SENDERS, where an org
@@ -3665,6 +3720,11 @@ var mailchimp_default2 = {
         // than showing a string like a1b2c3d4e5.
         key: "Sync contact to Mailchimp",
         queue: "connection",
+        // The key the hook puts in `context`, for a later step to interpolate
+        // as {{mailchimpMemberId}}. Same reasoning as Klaviyo's.
+        returns: [
+          { key: "mailchimpMemberId", label: "Mailchimp Member ID" }
+        ],
         // Nothing for a merchant to configure on the step itself — the audience
         // is chosen once on the connection. Declared empty rather than omitted,
         // so "this step takes no settings" and "nobody thought about settings"
@@ -4926,6 +4986,24 @@ var shopify_default2 = {
           hook: "commerce.code",
           key: "Issue a discount code",
           queue: "connection",
+          // WHAT THIS STEP LEAVES BEHIND FOR THE ONES AFTER IT, and the only
+          // reason the builder can offer a Variables menu.
+          //
+          // These are the exact keys the hook puts in `context` — the runner
+          // merges that into the run's context, and a later step interpolates
+          // {{shopifyDiscountCode}} out of it. Declared beside the hook that
+          // writes them so the two cannot drift; there is nowhere else that
+          // knows both.
+          //
+          // They existed as a hand-written list in the api's workflow catalog
+          // until it was derived from these manifests, and the derivation
+          // hardcoded `returns : []` for every step. Nothing has offered a
+          // variable since — an email step after a discount step had no way to
+          // name the code it was supposed to send.
+          returns: [
+            { key: "shopifyDiscountCode", label: "Shopify Discount Code" },
+            { key: "shopifyDiscountId", label: "Shopify Discount ID" }
+          ],
           settings: {
             discount: {
               required: true,
@@ -4944,6 +5022,12 @@ var shopify_default2 = {
           hook: "commerce.customer",
           key: "Create customer",
           queue: "connection",
+          // Written on every path the hook can take — created, reused from an
+          // earlier step, or reused from the lead — so a later step can rely on
+          // it being there whenever this one succeeded.
+          returns: [
+            { key: "shopifyCustomerId", label: "Shopify Customer ID" }
+          ],
           settings: {},
           triggers: ["lead.insert"],
           usage: { actions: 1 }
@@ -5341,6 +5425,13 @@ var webhook_default = {
         hook: "webhook.send",
         key: "Send webhook",
         queue: "webhook",
+        // The receiver's response is buffered, not merged into the run — a
+        // receiver owes us a status, not a document — so there is nothing here
+        // for a later step to interpolate. Declared empty rather than omitted:
+        // "leaves nothing behind" and "nobody thought about it" are different
+        // statements, and the second one is what emptied the builder's
+        // Variables menu for every step in the product.
+        returns: [],
         settings: {
           url: { format: "url", required: true, type: "string" }
         },
@@ -5717,6 +5808,12 @@ var publicConnectionKeys = Object.freeze([
   // excerpt, guide, and any vendor redirect copy.
   "content",
   "createdAt",
+  // THE MERCHANT'S OWN SWITCH. `enabled : false` is a connection the merchant
+  // paused — kept, configured, and not run — as distinct from a vendor the
+  // platform switched off (which the api overlays as an error). Absent means
+  // on; the dashboard renders Paused from it and the sync gates refuse a paused
+  // connection the way they refuse a missing one.
+  "enabled",
   // The connection DOCUMENT's own errors array — scope-drift entries written by
   // drawbridge-sync. NOT the manifest's error copy, which is content.errors:
   // the document is spread OVER the resolved manifest downstream, so the two

package/dist/connections/index.d.cts

@@ -914,10 +914,15 @@ var attentive = {
 			'Attentive accepts these updates and applies them in the background, so a contact appears in your segment shortly after the sync rather than the instant it runs.'
 		],
 		excerpt : 'Sync your Drawbridge contacts into an Attentive segment.',
+		// NAMES THE SEGMENT STEP, because `status` below gates on it: a grant with
+		// no segment chosen sits at Pending, and a guide that stops at the consent
+		// leaves a merchant looking at a connection they think is broken. Same
+		// omission Klaviyo's guide already carries a note about.
 		guide : [
 			'Press Connect. Drawbridge sends you to Attentive to approve access.',
 			'Sign in to Attentive if you are not already, and authorize the permissions listed.',
-			'You are returned here — choose which Attentive segment your contacts should sync into.'
+			'You come back here to choose which Attentive segment your contacts should sync into.',
+			'The connection shows Pending until you choose a segment, then Active.'
 		]
 	},
 	// A contact destination, like Klaviyo and Mailchimp — a merchant could
@@ -1239,6 +1244,10 @@ var attentive = {
 
 				queue : 'connection',
 
+				// Attentive applies the update in the background and returns no id we
+				// could hand on, so there is nothing for a later step to interpolate.
+				returns : [],
+
 				// Nothing for a merchant to configure on the step itself — the segment
 				// is chosen once on the connection. Declared empty rather than omitted,
 				// so "this step takes no settings" and "nobody thought about settings"
@@ -2236,6 +2245,11 @@ var drawbridge = {
 						message : interpolate( step.settings?.message, values ),
 						organization : workflow.organization,
 						send : { type : 'email', email : member.email },
+						// The editor's plain rendering, interpolated the same way so
+						// {{count}} resolves in the text part too. Spread rather than
+						// written as null: a step saved before `text` existed has none,
+						// and the send path strips the markup itself for those.
+						...( step.settings?.text && { text : interpolate( step.settings.text, values ) }),
 						title : interpolate( step.settings?.subject, values ),
 						workflow : workflow.id
 					}) )
@@ -2423,6 +2437,10 @@ var drawbridge = {
 							message : interpolate( step.settings?.message, context ),
 							organization : workflow.organization,
 							send : { type : 'email', email : to },
+							// The editor's plain rendering, so the text/plain part of this
+							// email is what the merchant wrote rather than a regex's guess at
+							// it. See the digest above for why it is spread, not nulled.
+							...( step.settings?.text && { text : interpolate( step.settings.text, context ) }),
 							title : interpolate( step.settings?.subject, context ),
 							workflow : workflow.id
 						})
@@ -2978,6 +2996,11 @@ var drawbridge = {
 				hook : 'email.digest',
 				key : 'Email — Digest',
 				queue : 'notification',
+				// Nothing for a later step to interpolate. Declared empty rather than
+				// omitted, so "this step leaves nothing behind" and "nobody thought
+				// about it" stay different statements — the second is what emptied the
+				// builder's Variables menu for every step in the product.
+				returns : [],
 				settings : {
 					// The organization OWNER is always a recipient, resolved by the
 					// hook, so this is additional recipients rather than the list. It
@@ -2986,7 +3009,22 @@ var drawbridge = {
 					// pick and could never save the step.
 					members : { of : 'string', type : 'array' },
 					message : { max : 2000, required : true, type : 'string' },
-					subject : { max : 150, required : true, type : 'string' }
+					// THE LAST SPAM CHECK, stored beside the copy it measured. Shape is
+					// pinned no further than the pair that proves the match, which is the
+					// only part the api reads; the rest is SpamAssassin's own output and
+					// is stored as it arrives. Same declaration the campaign's draw
+					// notification validates against.
+					//
+					// Undeclared, this was silently dropped at submit — the settings
+					// validator is noUnknown().strict(), so the dashboard's step form
+					// mapped the key away rather than 400 — and every open of a workflow
+					// step re-ran a check against a free service to be told what the last
+					// open had already been told.
+					score : { shape : { message : { type : 'string' }, subject : { type : 'string' } }, type : 'object' },
+					subject : { max : 150, required : true, type : 'string' },
+					// The editor's plain rendering of `message`, written beside it rather
+					// than reconstructed by running a regex over the markup at send time.
+					text : { max : 2000, type : 'string' }
 				},
 				triggers : [ 'schedule.day', 'schedule.week', 'schedule.month' ],
 				usage : { actions : 0 }
@@ -3008,6 +3046,7 @@ var drawbridge = {
 				hook : 'email.notify',
 				key : 'Email — Notification',
 				queue : 'notification',
+				returns : [],
 				settings : {
 					members : { of : 'string', type : 'array' },
 					message : { max : 2000, type : 'string' },
@@ -3025,9 +3064,14 @@ var drawbridge = {
 				hook : 'email.send',
 				key : 'Email — Send email',
 				queue : 'notification',
+				returns : [],
 				settings : {
 					message : { max : 2000, required : true, type : 'string' },
-					subject : { max : 150, required : true, type : 'string' }
+					// See email.digest above — the last spam check, and the editor's
+					// plain rendering of the message.
+					score : { shape : { message : { type : 'string' }, subject : { type : 'string' } }, type : 'object' },
+					subject : { max : 150, required : true, type : 'string' },
+					text : { max : 2000, type : 'string' }
 				},
 				triggers : [ 'lead.insert' ],
 				// ONE SOURCE FOR THE PRICE. lib/pricing.js is the index of every
@@ -3813,6 +3857,14 @@ var klaviyo = {
 
 				queue : 'connection',
 
+				// The key the hook puts in `context`, which the runner merges into the
+				// run so a later step can interpolate {{klaviyoProfileId}}. Declared
+				// beside the hook that writes it — see the note on Shopify's
+				// commerce.code, which is where this came back from.
+				returns : [
+					{ key : 'klaviyoProfileId', label : 'Klaviyo Profile ID' }
+				],
+
 				// Nothing for a merchant to configure on the step itself — the list
 				// is chosen once on the connection. Declared empty rather than
 				// omitted, so "this step takes no settings" and "nobody thought about
@@ -3978,10 +4030,15 @@ var mailchimp = {
 			'Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before.'
 		],
 		excerpt : 'Sync your Drawbridge contacts into a Mailchimp audience.',
+		// NAMES THE AUDIENCE STEP, because `status` below gates on it: a grant with
+		// no audience chosen sits at Pending, and a guide that stops at the consent
+		// leaves a merchant looking at a connection they think is broken.
 		guide : [
 			'Press Connect. Drawbridge sends you to Mailchimp to approve access.',
 			'Sign in to Mailchimp if you are not already, and choose the account to connect.',
-			'You come back here to pick the audience your contacts should sync into.'
+			'You come back here to pick the audience your contacts should sync into.',
+			'The connection shows Pending until you pick an audience, then Active.',
+			'You can remove Drawbridge at any time from the Authorized Apps page in your Mailchimp account.'
 		]
 	},
 	// Mailchimp and SendGrid shared a group while they were SENDERS, where an org
@@ -4332,6 +4389,12 @@ var mailchimp = {
 
 				queue : 'connection',
 
+				// The key the hook puts in `context`, for a later step to interpolate
+				// as {{mailchimpMemberId}}. Same reasoning as Klaviyo's.
+				returns : [
+					{ key : 'mailchimpMemberId', label : 'Mailchimp Member ID' }
+				],
+
 				// Nothing for a merchant to configure on the step itself — the audience
 				// is chosen once on the connection. Declared empty rather than omitted,
 				// so "this step takes no settings" and "nobody thought about settings"
@@ -6096,6 +6159,24 @@ var shopify = {
 					hook : 'commerce.code',
 					key : 'Issue a discount code',
 					queue : 'connection',
+					// WHAT THIS STEP LEAVES BEHIND FOR THE ONES AFTER IT, and the only
+					// reason the builder can offer a Variables menu.
+					//
+					// These are the exact keys the hook puts in `context` — the runner
+					// merges that into the run's context, and a later step interpolates
+					// {{shopifyDiscountCode}} out of it. Declared beside the hook that
+					// writes them so the two cannot drift; there is nowhere else that
+					// knows both.
+					//
+					// They existed as a hand-written list in the api's workflow catalog
+					// until it was derived from these manifests, and the derivation
+					// hardcoded `returns : []` for every step. Nothing has offered a
+					// variable since — an email step after a discount step had no way to
+					// name the code it was supposed to send.
+					returns : [
+						{ key : 'shopifyDiscountCode', label : 'Shopify Discount Code' },
+						{ key : 'shopifyDiscountId', label : 'Shopify Discount ID' }
+					],
 					settings : {
 						discount : {
 							required : true,
@@ -6115,6 +6196,12 @@ var shopify = {
 					hook : 'commerce.customer',
 					key : 'Create customer',
 					queue : 'connection',
+					// Written on every path the hook can take — created, reused from an
+					// earlier step, or reused from the lead — so a later step can rely on
+					// it being there whenever this one succeeded.
+					returns : [
+						{ key : 'shopifyCustomerId', label : 'Shopify Customer ID' }
+					],
 					settings : {},
 					triggers : [ 'lead.insert' ],
 					usage : { actions : 1 }
@@ -6425,6 +6512,13 @@ var webhook = {
 				hook : 'webhook.send',
 				key : 'Send webhook',
 				queue : 'webhook',
+				// The receiver's response is buffered, not merged into the run — a
+				// receiver owes us a status, not a document — so there is nothing here
+				// for a later step to interpolate. Declared empty rather than omitted:
+				// "leaves nothing behind" and "nobody thought about it" are different
+				// statements, and the second one is what emptied the builder's
+				// Variables menu for every step in the product.
+				returns : [],
 				settings : {
 					url : { format : 'url', required : true, type : 'string' }
 				},
@@ -7406,6 +7500,12 @@ const publicConnectionKeys = Object.freeze([
 	// excerpt, guide, and any vendor redirect copy.
 	'content',
 	'createdAt',
+	// THE MERCHANT'S OWN SWITCH. `enabled : false` is a connection the merchant
+	// paused — kept, configured, and not run — as distinct from a vendor the
+	// platform switched off (which the api overlays as an error). Absent means
+	// on; the dashboard renders Paused from it and the sync gates refuse a paused
+	// connection the way they refuse a missing one.
+	'enabled',
 	// The connection DOCUMENT's own errors array — scope-drift entries written by
 	// drawbridge-sync. NOT the manifest's error copy, which is content.errors:
 	// the document is spread OVER the resolved manifest downstream, so the two