@drawbridge/drawbridge-utils 0.0.154 → 0.0.156

package/dist/providers.cjs

@@ -245,6 +245,7 @@ var HOOK_PROPS = Object.freeze([
   "scope",
   "search",
   "secret",
+  "segments",
   "settings",
   "sort",
   "step",
@@ -2574,10 +2575,15 @@ var klaviyo_default2 = {
     excerpt: "Sync the contacts your campaigns collect into a Klaviyo list.",
     // HOW TO CONNECT, in the merchant's words. Was `setup`, which nothing
     // rendered — four useful instructions no component displayed.
+    // NAMES THE LIST STEP, because `status` below gates on it: a grant with no
+    // list chosen sits at Pending, and this told the merchant it would show
+    // Active. The one required action was the one action the guide omitted, so
+    // anybody following it landed on a connection that looked broken.
     guide: [
       "Press Connect. Drawbridge sends you to Klaviyo to approve access.",
       "Sign in to Klaviyo if you are not already, and choose the account to connect.",
-      "Approve the permissions Klaviyo lists. You are returned here and the connection shows Active.",
+      "Approve the permissions Klaviyo lists. You come back here to pick the list your contacts should sync into.",
+      "The connection shows Pending until you pick a list, then Active.",
       "You can revoke access at any time from Klaviyo, under Integrations."
     ]
   },
@@ -2699,14 +2705,15 @@ var klaviyo_default2 = {
       // Not yet. Suppression syncs an opt-out as unsubscribed, which is a
       // different thing from deleting the profile.
       remove: false,
-      sync: async ({ contact, lead, settings, suppressed, token }, { fetcher } = {}) => {
+      sync: async ({ context, lead, segments, settings, suppressed, token }, { fetcher } = {}) => {
         var _a, _b, _c;
         const list = settings == null ? void 0 : settings.list;
         if (!list) return { message: "No Klaviyo list is chosen for this connection.", skipped: true };
         const email = ((_b = (_a = lead == null ? void 0 : lead.canonical) == null ? void 0 : _a.email) == null ? void 0 : _b.value) || (lead == null ? void 0 : lead.email);
         if (!email) return { message: "That lead has no email address to sync.", skipped: true };
-        const totals = (contact == null ? void 0 : contact.totals) || {};
-        const profile = await api2("/profiles/", {
+        const person = (context == null ? void 0 : context.contact) || null;
+        const totals = (person == null ? void 0 : person.totals) || {};
+        const profile = await api2("/profile-import", {
           fetcher,
           method: "POST",
           payload: {
@@ -2715,16 +2722,36 @@ var klaviyo_default2 = {
                 email,
                 ...(lead == null ? void 0 : lead.name) && { first_name: String(lead.name).trim().split(/\s+/)[0] },
                 properties: {
-                  drawbridge_campaigns: ((contact == null ? void 0 : contact.campaigns) || []).length,
-                  drawbridge_draws: totals.draws || 0,
-                  drawbridge_entries: totals.entries || 0,
-                  drawbridge_orders: totals.orders || 0,
-                  // Campaign-attributed, NOT lifetime. A merchant running
-                  // Shopify already has lifetime revenue in Klaviyo through
-                  // Klaviyo's own integration; what only we can say is how
-                  // much a campaign drove. Named so the two cannot be
-                  // mistaken for one another in a segment builder.
-                  drawbridge_revenue: totals.gross || 0
+                  ...person && {
+                    drawbridge_campaigns: (person.campaigns || []).length,
+                    drawbridge_draws: totals.draws || 0,
+                    drawbridge_entries: totals.entries || 0,
+                    drawbridge_orders: totals.orders || 0,
+                    // Campaign-attributed, NOT lifetime. A merchant running
+                    // Shopify already has lifetime revenue in Klaviyo through
+                    // Klaviyo's own integration; what only we can say is how
+                    // much a campaign drove. Named so the two cannot be
+                    // mistaken for one another in a segment builder.
+                    drawbridge_revenue: totals.gross || 0
+                  },
+                  // THE DRAWBRIDGE SEGMENTS THEY ARE IN, as a list property the
+                  // merchant builds Klaviyo segments on top of. Klaviyo owns no
+                  // writable membership — its segments are computed from rules,
+                  // so a profile cannot be put in one — and this is the nearest
+                  // honest equivalent.
+                  //
+                  // WHOLESALE, WHICH IS WHAT MAKES IT SELF-HEALING. Drawbridge
+                  // segments are dynamic and nothing dispatches a leave event —
+                  // only segment.contact.add exists — so a property that was
+                  // only ever appended to would outlive the membership that
+                  // earned it. Rewriting the whole array each run means every
+                  // sync corrects whatever the last one got wrong, with no
+                  // removal path to build.
+                  //
+                  // `segments` is null when the run carried no contact document,
+                  // meaning nobody looked — different from [], which means they
+                  // are in none. Null omits the key and merge leaves it alone.
+                  ...segments && { drawbridge_segments: segments.map((entry) => entry.title).filter(Boolean) }
                 }
               },
               type: "profile"
@@ -3016,7 +3043,7 @@ var api3 = async (path, { dc, fetcher = fetch, method = "GET", payload, token })
       { status: response.status }
     );
   }
-  return response.json();
+  return response.status === 204 ? null : response.json();
 };
 var subscriberHash = (email) => (0, import_node_crypto3.createHash)("md5").update(String(email).trim().toLowerCase()).digest("hex");
 var mailchimp_default2 = {
@@ -3150,7 +3177,7 @@ var mailchimp_default2 = {
       // PUT /lists/{list_id}/members/{subscriber_hash} — an UPSERT, which is
       // why there is no create-or-update branch here. Quoted from Mailchimp's
       // Marketing API reference for the list-members resource.
-      sync: async ({ lead, settings, suppressed, token }, { fetcher } = {}) => {
+      sync: async ({ connection: connection2, lead, segments, settings, suppressed, token }, { fetcher, read } = {}) => {
         var _a, _b;
         const audience = settings == null ? void 0 : settings.audience;
         if (!audience) return { message: "No Mailchimp audience is chosen for this connection.", skipped: true };
@@ -3176,6 +3203,36 @@ var mailchimp_default2 = {
           },
           token
         });
+        if (segments && read) {
+          const owned = await read.aggregate({
+            collection: "segment",
+            pipeline: [
+              {
+                $match: {
+                  organization: connection2 == null ? void 0 : connection2.organization,
+                  system: { $ne: true }
+                }
+              },
+              {
+                $project: { _id: 0, title: 1 }
+              }
+            ]
+          });
+          const joined = new Set(segments.map((entry) => entry.title));
+          const tags = (owned || []).map((entry) => entry.title).filter(Boolean).map((title) => ({
+            name: "Drawbridge: " + title,
+            status: joined.has(title) ? "active" : "inactive"
+          }));
+          if (tags.length > 0) {
+            await api3("/lists/" + audience + "/members/" + hash + "/tags", {
+              dc: settings == null ? void 0 : settings.dc,
+              fetcher,
+              method: "POST",
+              payload: { tags },
+              token
+            });
+          }
+        }
         return {
           // Merged into `context` for later steps in this run.
           context: { mailchimpMemberId: (member == null ? void 0 : member.id) || hash },
@@ -4863,9 +4920,14 @@ var webhook_default = {
       "Generate a signing secret and Drawbridge signs every request with it. Your endpoint recomputes the signature to confirm each payload genuinely came from Drawbridge before acting on it."
     ],
     excerpt: "Sign outgoing webhook payloads with an HMAC secret to verify authenticity.",
+    // SAYS WHERE THE URL GOES. Connecting only mints a secret, so a merchant
+    // following this had nowhere to put the endpoint they came to configure —
+    // the destination lives on the step (see steps.webhook.send.settings), and
+    // the guide never said so.
     guide: [
       "Press Connect. Drawbridge generates a signing secret and shows it here.",
       "Copy the secret into your own endpoint.",
+      "Add a Send webhook step to a workflow and put your endpoint URL on it. The URL belongs to the step rather than the connection, so one connection can serve several endpoints.",
       "On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload."
     ]
   },

package/dist/providers.js

@@ -199,6 +199,7 @@ var HOOK_PROPS = Object.freeze([
   "scope",
   "search",
   "secret",
+  "segments",
   "settings",
   "sort",
   "step",
@@ -2528,10 +2529,15 @@ var klaviyo_default2 = {
     excerpt: "Sync the contacts your campaigns collect into a Klaviyo list.",
     // HOW TO CONNECT, in the merchant's words. Was `setup`, which nothing
     // rendered — four useful instructions no component displayed.
+    // NAMES THE LIST STEP, because `status` below gates on it: a grant with no
+    // list chosen sits at Pending, and this told the merchant it would show
+    // Active. The one required action was the one action the guide omitted, so
+    // anybody following it landed on a connection that looked broken.
     guide: [
       "Press Connect. Drawbridge sends you to Klaviyo to approve access.",
       "Sign in to Klaviyo if you are not already, and choose the account to connect.",
-      "Approve the permissions Klaviyo lists. You are returned here and the connection shows Active.",
+      "Approve the permissions Klaviyo lists. You come back here to pick the list your contacts should sync into.",
+      "The connection shows Pending until you pick a list, then Active.",
       "You can revoke access at any time from Klaviyo, under Integrations."
     ]
   },
@@ -2653,14 +2659,15 @@ var klaviyo_default2 = {
       // Not yet. Suppression syncs an opt-out as unsubscribed, which is a
       // different thing from deleting the profile.
       remove: false,
-      sync: async ({ contact, lead, settings, suppressed, token }, { fetcher } = {}) => {
+      sync: async ({ context, lead, segments, settings, suppressed, token }, { fetcher } = {}) => {
         var _a, _b, _c;
         const list = settings == null ? void 0 : settings.list;
         if (!list) return { message: "No Klaviyo list is chosen for this connection.", skipped: true };
         const email = ((_b = (_a = lead == null ? void 0 : lead.canonical) == null ? void 0 : _a.email) == null ? void 0 : _b.value) || (lead == null ? void 0 : lead.email);
         if (!email) return { message: "That lead has no email address to sync.", skipped: true };
-        const totals = (contact == null ? void 0 : contact.totals) || {};
-        const profile = await api2("/profiles/", {
+        const person = (context == null ? void 0 : context.contact) || null;
+        const totals = (person == null ? void 0 : person.totals) || {};
+        const profile = await api2("/profile-import", {
           fetcher,
           method: "POST",
           payload: {
@@ -2669,16 +2676,36 @@ var klaviyo_default2 = {
                 email,
                 ...(lead == null ? void 0 : lead.name) && { first_name: String(lead.name).trim().split(/\s+/)[0] },
                 properties: {
-                  drawbridge_campaigns: ((contact == null ? void 0 : contact.campaigns) || []).length,
-                  drawbridge_draws: totals.draws || 0,
-                  drawbridge_entries: totals.entries || 0,
-                  drawbridge_orders: totals.orders || 0,
-                  // Campaign-attributed, NOT lifetime. A merchant running
-                  // Shopify already has lifetime revenue in Klaviyo through
-                  // Klaviyo's own integration; what only we can say is how
-                  // much a campaign drove. Named so the two cannot be
-                  // mistaken for one another in a segment builder.
-                  drawbridge_revenue: totals.gross || 0
+                  ...person && {
+                    drawbridge_campaigns: (person.campaigns || []).length,
+                    drawbridge_draws: totals.draws || 0,
+                    drawbridge_entries: totals.entries || 0,
+                    drawbridge_orders: totals.orders || 0,
+                    // Campaign-attributed, NOT lifetime. A merchant running
+                    // Shopify already has lifetime revenue in Klaviyo through
+                    // Klaviyo's own integration; what only we can say is how
+                    // much a campaign drove. Named so the two cannot be
+                    // mistaken for one another in a segment builder.
+                    drawbridge_revenue: totals.gross || 0
+                  },
+                  // THE DRAWBRIDGE SEGMENTS THEY ARE IN, as a list property the
+                  // merchant builds Klaviyo segments on top of. Klaviyo owns no
+                  // writable membership — its segments are computed from rules,
+                  // so a profile cannot be put in one — and this is the nearest
+                  // honest equivalent.
+                  //
+                  // WHOLESALE, WHICH IS WHAT MAKES IT SELF-HEALING. Drawbridge
+                  // segments are dynamic and nothing dispatches a leave event —
+                  // only segment.contact.add exists — so a property that was
+                  // only ever appended to would outlive the membership that
+                  // earned it. Rewriting the whole array each run means every
+                  // sync corrects whatever the last one got wrong, with no
+                  // removal path to build.
+                  //
+                  // `segments` is null when the run carried no contact document,
+                  // meaning nobody looked — different from [], which means they
+                  // are in none. Null omits the key and merge leaves it alone.
+                  ...segments && { drawbridge_segments: segments.map((entry) => entry.title).filter(Boolean) }
                 }
               },
               type: "profile"
@@ -2970,7 +2997,7 @@ var api3 = async (path, { dc, fetcher = fetch, method = "GET", payload, token })
       { status: response.status }
     );
   }
-  return response.json();
+  return response.status === 204 ? null : response.json();
 };
 var subscriberHash = (email) => createHash2("md5").update(String(email).trim().toLowerCase()).digest("hex");
 var mailchimp_default2 = {
@@ -3104,7 +3131,7 @@ var mailchimp_default2 = {
       // PUT /lists/{list_id}/members/{subscriber_hash} — an UPSERT, which is
       // why there is no create-or-update branch here. Quoted from Mailchimp's
       // Marketing API reference for the list-members resource.
-      sync: async ({ lead, settings, suppressed, token }, { fetcher } = {}) => {
+      sync: async ({ connection: connection2, lead, segments, settings, suppressed, token }, { fetcher, read } = {}) => {
         var _a, _b;
         const audience = settings == null ? void 0 : settings.audience;
         if (!audience) return { message: "No Mailchimp audience is chosen for this connection.", skipped: true };
@@ -3130,6 +3157,36 @@ var mailchimp_default2 = {
           },
           token
         });
+        if (segments && read) {
+          const owned = await read.aggregate({
+            collection: "segment",
+            pipeline: [
+              {
+                $match: {
+                  organization: connection2 == null ? void 0 : connection2.organization,
+                  system: { $ne: true }
+                }
+              },
+              {
+                $project: { _id: 0, title: 1 }
+              }
+            ]
+          });
+          const joined = new Set(segments.map((entry) => entry.title));
+          const tags = (owned || []).map((entry) => entry.title).filter(Boolean).map((title) => ({
+            name: "Drawbridge: " + title,
+            status: joined.has(title) ? "active" : "inactive"
+          }));
+          if (tags.length > 0) {
+            await api3("/lists/" + audience + "/members/" + hash + "/tags", {
+              dc: settings == null ? void 0 : settings.dc,
+              fetcher,
+              method: "POST",
+              payload: { tags },
+              token
+            });
+          }
+        }
         return {
           // Merged into `context` for later steps in this run.
           context: { mailchimpMemberId: (member == null ? void 0 : member.id) || hash },
@@ -4817,9 +4874,14 @@ var webhook_default = {
       "Generate a signing secret and Drawbridge signs every request with it. Your endpoint recomputes the signature to confirm each payload genuinely came from Drawbridge before acting on it."
     ],
     excerpt: "Sign outgoing webhook payloads with an HMAC secret to verify authenticity.",
+    // SAYS WHERE THE URL GOES. Connecting only mints a secret, so a merchant
+    // following this had nowhere to put the endpoint they came to configure —
+    // the destination lives on the step (see steps.webhook.send.settings), and
+    // the guide never said so.
     guide: [
       "Press Connect. Drawbridge generates a signing secret and shows it here.",
       "Copy the secret into your own endpoint.",
+      "Add a Send webhook step to a workflow and put your endpoint URL on it. The URL belongs to the step rather than the connection, so one connection can serve several endpoints.",
       "On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload."
     ]
   },

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.154"
+  "version": "0.0.156"
 }