@drawbridge/drawbridge-utils 0.0.161 → 0.0.163

package/dist/providers.d.ts

@@ -128,8 +128,9 @@ const mask = ( value ) => {
 // safe. Per-process state cannot be stale for anyone but the process holding it,
 // and it expires on its own.
 //
-// slug -> { at, value }, where value is the DECRYPTED settings. Exported only so
-// tests can age an entry without sleeping; nothing else should read it.
+// slug -> { at, value }, where value is { enabled, settings } — the decrypted
+// settings and whether the row is switched on. Exported only so tests can age an
+// entry without sleeping; nothing else should read it.
 const providerMemo = new Map();
 
 // SIXTY SECONDS, chosen for the human rather than for the load. The read is one
@@ -143,16 +144,35 @@ const MEMO_TTL_MS = 60 * 1000;
 // For tests. A save clears its own slug; this clears everything.
 const clearProviderMemo = () => providerMemo.clear();
 
-// Read a vendor's credentials, memoized, because this is on the path of every
-// OAuth callback and every send.
+// A VENDOR, as { enabled, settings } — the switch and the credentials, from one
+// read. Memoized, because this is on the path of every OAuth callback and every
+// send, so a guard costs a Map lookup rather than a document and a decrypt.
 //
-// An unconfigured vendor answers {} rather than throwing: the admin list has to
-// render the row that lets someone fix it.
+// THIS IS THE ROOT CHECK. There is no separate is-it-enabled function, because
+// one question with two ways to ask it is two things to keep agreeing:
+//
+//   const { enabled, settings } = await providerRow({ controller, slug : 'sendgrid' });
+//   if( ! enabled || ! settings.apiKey ) return;
+//
+// The switch is answered here and the caller names the credentials it needs.
+// Which credentials matter is the FEATURE's question, not the vendor's, and
+// folding the two together answers it wrong in both directions: `isLive` judges
+// the fields a vendor marks `required`, so a send needing SendGrid's optional
+// eventKey would pass a combined check and still fail, while one needing nothing
+// but eventKey would be refused because accountSender happens to be blank. A
+// vendor has one switch and many features.
+//
+// An unconfigured vendor answers enabled with no settings rather than throwing:
+// the admin list has to render the row that lets someone fix it.
+//
+// ABSENT MEANS ON. Every row that predates the switch has no `enabled` field,
+// and reading that as off would take every vendor down at once — so the flag is
+// only ever believed when it says false.
 //
 // The memoized object is handed to every reader inside the window rather than
 // copied per read — no caller mutates its credentials, and defending against one
 // that does not exist would cost a clone on every send.
-const providerSettings = async ({ controller, slug }) => {
+const providerRow = async ({ controller, slug }) => {
 
 	const memoized = providerMemo.get( slug );
 
@@ -163,7 +183,10 @@ const providerSettings = async ({ controller, slug }) => {
 		query : { slug }
 	});
 
-	const value = row?.settings ? decrypt( row.settings ) : {};
+	const value = {
+		enabled : row?.enabled !== false,
+		settings : row?.settings ? decrypt( row.settings ) : {}
+	};
 
 	providerMemo.set( slug, { at : Date.now(), value });
 
@@ -171,6 +194,39 @@ const providerSettings = async ({ controller, slug }) => {
 
 };
 
+// A vendor's credentials, or nothing at all if the vendor is switched off.
+//
+// SWITCHED OFF READS AS UNCONFIGURED, and that is the whole design. Every
+// consumer already handles a vendor with no credentials — availableConnections
+// drops it from the catalogue, isLive reports not live, a send has nothing to
+// send with — so turning one off needs no second code path anywhere. The keys
+// stay on the row, which is the point: this is the switch you reach for instead
+// of deleting a credential you will have to find again.
+//
+// `includeDisabled` is for the ADMIN SCREEN alone. That page exists to show what
+// is stored and to switch it back on, and it cannot do either if the credentials
+// disappear from its own view the moment they are turned off.
+const providerSettings = async ({ controller, includeDisabled = false, slug }) => {
+
+	const row = await providerRow({ controller, slug });
+
+	return ( row.enabled || includeDisabled ) ? row.settings : {};
+
+};
+
+// IS THIS VENDOR SWITCHED ON? The primitive both halves of the gate are built
+// from, named for what it takes: a VENDOR slug (sendgrid, twilio, klaviyo), not
+// a connection slug. The `provider` collection is one row per vendor, so this is
+// that row's switch and nothing else.
+//
+// Its parameter is `vendor` rather than `slug` on purpose. vendorsEnabled below
+// takes a CONNECTION slug and composes this across everything that connection
+// spends, and the two are a letter apart — the argument name is what makes which
+// one you are calling obvious at the call site.
+const vendorEnabled = async ({ controller, vendor }) => (
+	( await providerRow({ controller, slug : vendor }) ).enabled
+);
+
 // EVERYTHING A CONNECTION SPENDS, merged across the vendors its manifest
 // declares. `drawbridge` reads SendGrid, Twilio and HubSpot as one object, the
 // way it did when they sat on one row — the row split, the readers did not.
@@ -194,6 +250,30 @@ const vendorSettings = async ({ controller, slug }) => {
 
 };
 
+// EVERY VENDOR A CONNECTION SPENDS, SWITCHED ON.
+//
+// The connection-level answer to the provider-level question, and the two are
+// not one-to-one in either direction: `drawbridge` spends SendGrid, Twilio and
+// HubSpot, so switching any one of them off makes that connection unusable,
+// while `webhook` spends no vendor at all and can never be switched off.
+//
+// Same walk as vendorSettings, which is deliberate — a connection that reads
+// three rows as one settings object has to answer the switch across the same
+// three, or the two would disagree about which vendors a connection depends on.
+const vendorsEnabled = async ({ controller, slug }) => {
+
+	const declared = Object.hasOwn( connections, slug ) ? Object.keys( connections[ slug ].provider?.vendors || {} ) : [];
+
+	for( const vendor of declared ){
+
+		if( ! await vendorEnabled({ controller, vendor }) ) return false;
+
+	}
+
+	return true;
+
+};
+
 // Write a vendor's credentials.
 //
 // ONLY THE DECLARED FIELDS. The body arrives over the wire, so anything in it
@@ -203,7 +283,11 @@ const vendorSettings = async ({ controller, slug }) => {
 // BLANK MEANS KEEP. A redacted field is never returned by the GET, so an
 // unchanged form posts it back empty; treating that as a clear would wipe a
 // credential every time someone edited the field next to it.
-const saveProviderSettings = async ({ authenticated, clear, controller, settings, slug }) => {
+// SWITCHING OFF IS A SAVE, not its own route. The toggle sits in the same drawer
+// as the credentials and travels with them, so an admin who turns a vendor off
+// and corrects a key does it in one gesture. Omitted leaves the row's current
+// answer alone, the same way a blank credential does.
+const saveProviderSettings = async ({ authenticated, clear, controller, enabled, settings, slug }) => {
 
 	const fields = providerFields( slug );
 
@@ -263,6 +347,7 @@ const saveProviderSettings = async ({ authenticated, clear, controller, settings
 		collection : 'provider',
 		data : {
 			$set : {
+				...( enabled !== undefined && { enabled : Boolean( enabled ) }),
 				settings : encrypt( merged )
 			}
 		},
@@ -309,7 +394,14 @@ const providerEnvNames = () => new Set(
 //
 // A field with no value is OMITTED rather than set empty, so `requires` sees
 // the same absence it would for an unset variable.
-const providerCredentials = async ({ controller }) => {
+//
+// `includeDisabled` is for VERIFYING, not spending. Switching a vendor off means
+// we stop sending through it; it does not mean a message signed with its secret
+// stopped being genuine. Delivery events for mail already sent still arrive, and
+// a STOP reply is an obligation whether or not we are currently sending — so
+// the inbound routes read the secret with the switch ignored, and everything
+// that decides what a merchant can connect or a step can run reads it honoured.
+const providerCredentials = async ({ controller, includeDisabled = false }) => {
 
 	const credentials = {};
 
@@ -326,7 +418,7 @@ const providerCredentials = async ({ controller }) => {
 		// which is exactly where someone goes to fix it.
 		try {
 
-			const settings = await providerSettings({ controller, slug });
+			const settings = await providerSettings({ controller, includeDisabled, slug });
 
 			for( const field of providerFields( slug ) ){
 
@@ -348,4 +440,4 @@ const providerCredentials = async ({ controller }) => {
 
 };
 
-export { clearProviderMemo, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerMemo, providerSettings, providerSlugs, saveProviderSettings, vendorSettings, vendors };
+export { clearProviderMemo, isLive, mask, providerCredentials, providerEnvNames, providerFields, providerMemo, providerRow, providerSettings, providerSlugs, saveProviderSettings, vendorEnabled, vendorSettings, vendors, vendorsEnabled };

package/dist/providers.js

@@ -494,10 +494,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
@@ -760,6 +765,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"
@@ -1987,13 +1995,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
             });
           })
@@ -2062,7 +2075,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 };
@@ -2099,7 +2112,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
             })
           ]
@@ -2519,6 +2536,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
@@ -2527,7 +2549,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 }
@@ -2548,6 +2585,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" },
@@ -2564,9 +2602,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
@@ -3165,6 +3208,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
@@ -3280,10 +3330,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
@@ -3525,6 +3580,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"
@@ -4199,8 +4259,8 @@ var shopify_default2 = {
           }
         }
         const billable = (org == null ? void 0 : org.billingProvider) === "shopify" && fee > 0 && !backfill;
-        const providerRow = billable ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
-        const { orderEventHandle } = (providerRow == null ? void 0 : providerRow.settings) ? decrypt(providerRow.settings) : {};
+        const providerRow2 = billable ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
+        const { orderEventHandle } = (providerRow2 == null ? void 0 : providerRow2.settings) ? decrypt(providerRow2.settings) : {};
         const handle = typeof orderEventHandle === "string" && slugify(orderEventHandle) || ORDER_EVENT_HANDLE;
         if (billable && !((_f = connection2 == null ? void 0 : connection2.source) == null ? void 0 : _f.id)) {
           (_g = logger2 == null ? void 0 : logger2.error) == null ? void 0 : _g.call(logger2, new Error(
@@ -4805,6 +4865,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,
@@ -4823,6 +4901,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 }
@@ -5220,6 +5304,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" }
         },
@@ -5553,17 +5644,25 @@ var mask = (value) => {
 var providerMemo = /* @__PURE__ */ new Map();
 var MEMO_TTL_MS = 60 * 1e3;
 var clearProviderMemo = () => providerMemo.clear();
-var providerSettings = async ({ controller, slug: slug2 }) => {
+var providerRow = async ({ controller, slug: slug2 }) => {
   const memoized = providerMemo.get(slug2);
   if (memoized && Date.now() - memoized.at < MEMO_TTL_MS) return memoized.value;
   const row = await controller.get({
     collection: "provider",
     query: { slug: slug2 }
   });
-  const value = (row == null ? void 0 : row.settings) ? decrypt(row.settings) : {};
+  const value = {
+    enabled: (row == null ? void 0 : row.enabled) !== false,
+    settings: (row == null ? void 0 : row.settings) ? decrypt(row.settings) : {}
+  };
   providerMemo.set(slug2, { at: Date.now(), value });
   return value;
 };
+var providerSettings = async ({ controller, includeDisabled = false, slug: slug2 }) => {
+  const row = await providerRow({ controller, slug: slug2 });
+  return row.enabled || includeDisabled ? row.settings : {};
+};
+var vendorEnabled = async ({ controller, vendor }) => (await providerRow({ controller, slug: vendor })).enabled;
 var vendorSettings = async ({ controller, slug: slug2 }) => {
   var _a;
   const declared = Object.hasOwn(connections, slug2) ? Object.keys(((_a = connections[slug2].provider) == null ? void 0 : _a.vendors) || {}) : [];
@@ -5573,7 +5672,15 @@ var vendorSettings = async ({ controller, slug: slug2 }) => {
   }
   return merged;
 };
-var saveProviderSettings = async ({ authenticated, clear, controller, settings, slug: slug2 }) => {
+var vendorsEnabled = async ({ controller, slug: slug2 }) => {
+  var _a;
+  const declared = Object.hasOwn(connections, slug2) ? Object.keys(((_a = connections[slug2].provider) == null ? void 0 : _a.vendors) || {}) : [];
+  for (const vendor of declared) {
+    if (!await vendorEnabled({ controller, vendor })) return false;
+  }
+  return true;
+};
+var saveProviderSettings = async ({ authenticated, clear, controller, enabled, settings, slug: slug2 }) => {
   const fields2 = providerFields(slug2);
   if (!fields2.length) return null;
   const existing = await controller.get({
@@ -5595,6 +5702,7 @@ var saveProviderSettings = async ({ authenticated, clear, controller, settings,
     collection: "provider",
     data: {
       $set: {
+        ...enabled !== void 0 && { enabled: Boolean(enabled) },
         settings: encrypt(merged)
       }
     },
@@ -5609,11 +5717,11 @@ var saveProviderSettings = async ({ authenticated, clear, controller, settings,
 var providerEnvNames = () => new Set(
   providerSlugs().flatMap((slug2) => providerFields(slug2)).map((field2) => field2.credential).filter(Boolean)
 );
-var providerCredentials = async ({ controller }) => {
+var providerCredentials = async ({ controller, includeDisabled = false }) => {
   const credentials2 = {};
   for (const slug2 of providerSlugs()) {
     try {
-      const settings = await providerSettings({ controller, slug: slug2 });
+      const settings = await providerSettings({ controller, includeDisabled, slug: slug2 });
       for (const field2 of providerFields(slug2)) {
         const value = settings == null ? void 0 : settings[field2.key];
         if (field2.credential && value) credentials2[field2.credential] = value;
@@ -5632,9 +5740,12 @@ export {
   providerEnvNames,
   providerFields,
   providerMemo,
+  providerRow,
   providerSettings,
   providerSlugs,
   saveProviderSettings,
+  vendorEnabled,
   vendorSettings,
-  vendors
+  vendors,
+  vendorsEnabled
 };

package/package.json

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