npm - @drawbridge/drawbridge-utils - Versions diffs - 0.0.153 → 0.0.155 - Mend

@drawbridge/drawbridge-utils 0.0.153 → 0.0.155

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/connections/index.cjs +81 -17
package/dist/connections/index.d.cts +150 -19
package/dist/connections/index.d.ts +150 -19
package/dist/connections/index.js +81 -17
package/dist/providers.cjs +81 -17
package/dist/providers.js +81 -17
package/package.json +1 -1

package/dist/connections/index.cjs CHANGED Viewed

@@ -275,6 +275,7 @@ var HOOK_PROPS = Object.freeze([
   "scope",
   "search",
   "secret",
+  "segments",
   "settings",
   "sort",
   "step",
@@ -2668,10 +2669,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."
     ]
   },
@@ -2793,14 +2799,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: {
@@ -2809,16 +2816,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"
@@ -3110,7 +3137,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 = {
@@ -3244,7 +3271,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 };
@@ -3270,6 +3297,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 },
@@ -4130,7 +4187,9 @@ var shopify_default2 = {
           enqueues: [{
             data: { product: productId, providerId, shop: connection2.shop },
             name: "workflow",
-            options: { jobId: "product.workflow.shopify." + providerId + "." + Date.now() },
+            // The numeric id, not the gid: BullMQ refuses a custom id with a
+            // colon in it, and every gid carries two.
+            options: { jobId: "product.workflow.shopify." + context.id + "." + Date.now() },
             queue: "product.shopify"
           }],
           message: "Product sync queued from Shopify webhook.",
@@ -4936,9 +4995,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/connections/index.d.cts CHANGED Viewed

@@ -334,6 +334,10 @@ const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 //   payload      the verified inbound body
 //   scope        the granted scope string being judged
 //   secret       the credential VALUE the caller resolved for verification
+//   segments     the non-system segments this contact is in, as { id, title },
+//                resolved by the shell — null when the run carried no contact
+//                document, which means nobody looked, where [] means they are
+//                in none. A hook handed null leaves the vendor's copy alone
 //   settings     the connection's decrypted settings
 //   step         the step document
 //   suppressed   the opt-out floor's answer for this lead, computed by the shell
@@ -383,7 +387,7 @@ const HOOK_PROPS = Object.freeze([
 	'channel', 'clientId', 'clientSecret', 'connection', 'contact', 'context',
 	'cursor', 'declaration', 'doc', 'email', 'event', 'headers', 'id', 'lead', 'limit',
 	'manifest', 'payload',
-	'scope', 'search', 'secret', 'settings', 'sort', 'step', 'suppressed',
+	'scope', 'search', 'secret', 'segments', 'settings', 'sort', 'step', 'suppressed',
 	'token', 'tokens', 'workflow'
 ]);
@@ -2834,10 +2838,15 @@ var klaviyo = {
 		// 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.'
 		]
@@ -2987,7 +2996,7 @@ var klaviyo = {
 			// 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 } = {} ) => {
 				const list = settings?.list;
@@ -3005,9 +3014,32 @@ var klaviyo = {
 				// contact knows money: order attribution is person-level and merges
 				// across every address a human used, so revenue and orders cannot
 				// exist on a single-address record.
-				const totals = contact?.totals || {};
-				const profile = await api$1( '/profiles/', {
+				//
+				// READ OFF `context`, NOT the shell's `contact` prop. That prop is the
+				// ADDRESS — a string — so `contact?.totals` was undefined on every run
+				// this hook has ever made, and all five properties below shipped as 0
+				// no matter what the person had entered, drawn or spent. Only a
+				// segment.contact.add run carries the document (drawbridge-sync
+				// lib/segment.js); lead.insert names a brand-new entrant who has no
+				// history to send anyway.
+				const person = context?.contact || null;
+				const totals = person?.totals || {};
+				// UPSERT, NOT CREATE. /profiles/ is the plain create and answers a
+				// conflict for a profile Klaviyo already holds — which is most of them,
+				// because the whole point of the segment trigger is syncing people who
+				// have been around long enough to earn a ranking. profile-import is
+				// Klaviyo's documented create-or-update: 201 when it made one, 200 when
+				// it updated one, and no conflict either way
+				// (developers.klaviyo.com/en/reference/create_or_update_profile,
+				// fetched 2026-09-09).
+				//
+				// IT MERGES, and that is why the blocks below are conditional rather
+				// than defaulted. "Not including a field in your request will leave it
+				// unchanged" — so omitting the totals on a lead.insert preserves
+				// whatever the last segment run published, where sending zeros would
+				// erase it. A property we cannot compute is one we must not write.
+				const profile = await api$1( '/profile-import', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -3016,16 +3048,36 @@ var klaviyo = {
 								email,
 								...( lead?.name && { first_name : String( lead.name ).trim().split( /\s+/ )[ 0 ] }),
 								properties : {
-									drawbridge_campaigns : ( 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'
@@ -3427,7 +3479,10 @@ const api = async ( path, { dc, fetcher = fetch, method = 'GET', payload, token
 	}
-	return response.json();
+	// 204 ON A TAG WRITE — nothing to parse, and asking an empty body for json
+	// throws, which would report a change Mailchimp accepted as a failed step.
+	// Klaviyo's file carries the same guard for the same reason.
+	return response.status === 204 ? null : response.json();
 };
@@ -3591,7 +3646,7 @@ var mailchimp = {
 			// 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, lead, segments, settings, suppressed, token }, { fetcher, read } = {} ) => {
 				const audience = settings?.audience;
@@ -3648,6 +3703,75 @@ var mailchimp = {
 					token
 				});
+				// THE DRAWBRIDGE SEGMENTS THIS PERSON IS IN, written as Mailchimp tags.
+				//
+				// TAGS, NOT MERGE FIELDS. A merge field has to exist on the audience
+				// before anything can be written to it, and an unregistered one is
+				// refused along with the whole member request — so carrying data that
+				// way means registering fields first, which is lifecycle.register's job
+				// and is not built. A tag needs no setup: "If a tag that does not exist
+				// is passed in and set as 'active', a new tag will be created"
+				// (mailchimp.com/developer/marketing/api/list-member-tags/add-or-remove-member-tags,
+				// fetched 2026-09-09). Nothing for the merchant to prepare, so nothing
+				// to explain in the guide.
+				//
+				// ACTIVE AND INACTIVE IN ONE CALL, which is what keeps this correct
+				// over time. Drawbridge segments are dynamic, and nothing dispatches a
+				// leave event — only segment.contact.add exists — so a tag that was
+				// only ever added would outlive the membership behind it and the
+				// merchant would target a condition that had stopped being true.
+				// Sending the whole list every time, each tag active or inactive
+				// against current membership, means each sync corrects the last.
+				//
+				// WRITTEN FOR A SUPPRESSED PERSON TOO. A tag is a label, not a
+				// permission: the `status : 'unsubscribed'` above is what stops mail
+				// reaching them, and letting their labels rot would leave the merchant
+				// a wrong answer about who belongs to what.
+				//
+				// PREFIXED, so a Drawbridge tag cannot collide with one the merchant
+				// keeps by hand, and so the inactive pass can only clear tags this
+				// integration wrote.
+				if( segments && read ){
+					const owned = await read.aggregate({
+						collection : 'segment',
+						pipeline : [
+							{
+								$match : {
+									organization : connection?.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 api( '/lists/' + audience + '/members/' + hash + '/tags', {
+							dc : settings?.dc,
+							fetcher,
+							method : 'POST',
+							payload : { tags },
+							token
+						});
+					}
+				}
 				return {
 					// Merged into `context` for later steps in this run.
 					context : { mailchimpMemberId : member?.id || hash },
@@ -4828,7 +4952,9 @@ var shopify = {
 					enqueues : [ {
 						data : { product : productId, providerId, shop : connection.shop },
 						name : 'workflow',
-						options : { jobId : 'product.workflow.shopify.' + providerId + '.' + Date.now() },
+						// The numeric id, not the gid: BullMQ refuses a custom id with a
+					// colon in it, and every gid carries two.
+					options : { jobId : 'product.workflow.shopify.' + context.id + '.' + Date.now() },
 						queue : 'product.shopify'
 					} ],
 					message : 'Product sync queued from Shopify webhook.',
@@ -5763,9 +5889,14 @@ var webhook = {
 			'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/connections/index.d.ts CHANGED Viewed

@@ -334,6 +334,10 @@ const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 //   payload      the verified inbound body
 //   scope        the granted scope string being judged
 //   secret       the credential VALUE the caller resolved for verification
+//   segments     the non-system segments this contact is in, as { id, title },
+//                resolved by the shell — null when the run carried no contact
+//                document, which means nobody looked, where [] means they are
+//                in none. A hook handed null leaves the vendor's copy alone
 //   settings     the connection's decrypted settings
 //   step         the step document
 //   suppressed   the opt-out floor's answer for this lead, computed by the shell
@@ -383,7 +387,7 @@ const HOOK_PROPS = Object.freeze([
 	'channel', 'clientId', 'clientSecret', 'connection', 'contact', 'context',
 	'cursor', 'declaration', 'doc', 'email', 'event', 'headers', 'id', 'lead', 'limit',
 	'manifest', 'payload',
-	'scope', 'search', 'secret', 'settings', 'sort', 'step', 'suppressed',
+	'scope', 'search', 'secret', 'segments', 'settings', 'sort', 'step', 'suppressed',
 	'token', 'tokens', 'workflow'
 ]);
@@ -2834,10 +2838,15 @@ var klaviyo = {
 		// 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.'
 		]
@@ -2987,7 +2996,7 @@ var klaviyo = {
 			// 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 } = {} ) => {
 				const list = settings?.list;
@@ -3005,9 +3014,32 @@ var klaviyo = {
 				// contact knows money: order attribution is person-level and merges
 				// across every address a human used, so revenue and orders cannot
 				// exist on a single-address record.
-				const totals = contact?.totals || {};
-				const profile = await api$1( '/profiles/', {
+				//
+				// READ OFF `context`, NOT the shell's `contact` prop. That prop is the
+				// ADDRESS — a string — so `contact?.totals` was undefined on every run
+				// this hook has ever made, and all five properties below shipped as 0
+				// no matter what the person had entered, drawn or spent. Only a
+				// segment.contact.add run carries the document (drawbridge-sync
+				// lib/segment.js); lead.insert names a brand-new entrant who has no
+				// history to send anyway.
+				const person = context?.contact || null;
+				const totals = person?.totals || {};
+				// UPSERT, NOT CREATE. /profiles/ is the plain create and answers a
+				// conflict for a profile Klaviyo already holds — which is most of them,
+				// because the whole point of the segment trigger is syncing people who
+				// have been around long enough to earn a ranking. profile-import is
+				// Klaviyo's documented create-or-update: 201 when it made one, 200 when
+				// it updated one, and no conflict either way
+				// (developers.klaviyo.com/en/reference/create_or_update_profile,
+				// fetched 2026-09-09).
+				//
+				// IT MERGES, and that is why the blocks below are conditional rather
+				// than defaulted. "Not including a field in your request will leave it
+				// unchanged" — so omitting the totals on a lead.insert preserves
+				// whatever the last segment run published, where sending zeros would
+				// erase it. A property we cannot compute is one we must not write.
+				const profile = await api$1( '/profile-import', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -3016,16 +3048,36 @@ var klaviyo = {
 								email,
 								...( lead?.name && { first_name : String( lead.name ).trim().split( /\s+/ )[ 0 ] }),
 								properties : {
-									drawbridge_campaigns : ( 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'
@@ -3427,7 +3479,10 @@ const api = async ( path, { dc, fetcher = fetch, method = 'GET', payload, token
 	}
-	return response.json();
+	// 204 ON A TAG WRITE — nothing to parse, and asking an empty body for json
+	// throws, which would report a change Mailchimp accepted as a failed step.
+	// Klaviyo's file carries the same guard for the same reason.
+	return response.status === 204 ? null : response.json();
 };
@@ -3591,7 +3646,7 @@ var mailchimp = {
 			// 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, lead, segments, settings, suppressed, token }, { fetcher, read } = {} ) => {
 				const audience = settings?.audience;
@@ -3648,6 +3703,75 @@ var mailchimp = {
 					token
 				});
+				// THE DRAWBRIDGE SEGMENTS THIS PERSON IS IN, written as Mailchimp tags.
+				//
+				// TAGS, NOT MERGE FIELDS. A merge field has to exist on the audience
+				// before anything can be written to it, and an unregistered one is
+				// refused along with the whole member request — so carrying data that
+				// way means registering fields first, which is lifecycle.register's job
+				// and is not built. A tag needs no setup: "If a tag that does not exist
+				// is passed in and set as 'active', a new tag will be created"
+				// (mailchimp.com/developer/marketing/api/list-member-tags/add-or-remove-member-tags,
+				// fetched 2026-09-09). Nothing for the merchant to prepare, so nothing
+				// to explain in the guide.
+				//
+				// ACTIVE AND INACTIVE IN ONE CALL, which is what keeps this correct
+				// over time. Drawbridge segments are dynamic, and nothing dispatches a
+				// leave event — only segment.contact.add exists — so a tag that was
+				// only ever added would outlive the membership behind it and the
+				// merchant would target a condition that had stopped being true.
+				// Sending the whole list every time, each tag active or inactive
+				// against current membership, means each sync corrects the last.
+				//
+				// WRITTEN FOR A SUPPRESSED PERSON TOO. A tag is a label, not a
+				// permission: the `status : 'unsubscribed'` above is what stops mail
+				// reaching them, and letting their labels rot would leave the merchant
+				// a wrong answer about who belongs to what.
+				//
+				// PREFIXED, so a Drawbridge tag cannot collide with one the merchant
+				// keeps by hand, and so the inactive pass can only clear tags this
+				// integration wrote.
+				if( segments && read ){
+					const owned = await read.aggregate({
+						collection : 'segment',
+						pipeline : [
+							{
+								$match : {
+									organization : connection?.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 api( '/lists/' + audience + '/members/' + hash + '/tags', {
+							dc : settings?.dc,
+							fetcher,
+							method : 'POST',
+							payload : { tags },
+							token
+						});
+					}
+				}
 				return {
 					// Merged into `context` for later steps in this run.
 					context : { mailchimpMemberId : member?.id || hash },
@@ -4828,7 +4952,9 @@ var shopify = {
 					enqueues : [ {
 						data : { product : productId, providerId, shop : connection.shop },
 						name : 'workflow',
-						options : { jobId : 'product.workflow.shopify.' + providerId + '.' + Date.now() },
+						// The numeric id, not the gid: BullMQ refuses a custom id with a
+					// colon in it, and every gid carries two.
+					options : { jobId : 'product.workflow.shopify.' + context.id + '.' + Date.now() },
 						queue : 'product.shopify'
 					} ],
 					message : 'Product sync queued from Shopify webhook.',
@@ -5763,9 +5889,14 @@ var webhook = {
 			'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/connections/index.js CHANGED Viewed

@@ -199,6 +199,7 @@ var HOOK_PROPS = Object.freeze([
   "scope",
   "search",
   "secret",
+  "segments",
   "settings",
   "sort",
   "step",
@@ -2592,10 +2593,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."
     ]
   },
@@ -2717,14 +2723,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: {
@@ -2733,16 +2740,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"
@@ -3034,7 +3061,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 = {
@@ -3168,7 +3195,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 };
@@ -3194,6 +3221,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 },
@@ -4054,7 +4111,9 @@ var shopify_default2 = {
           enqueues: [{
             data: { product: productId, providerId, shop: connection2.shop },
             name: "workflow",
-            options: { jobId: "product.workflow.shopify." + providerId + "." + Date.now() },
+            // The numeric id, not the gid: BullMQ refuses a custom id with a
+            // colon in it, and every gid carries two.
+            options: { jobId: "product.workflow.shopify." + context.id + "." + Date.now() },
             queue: "product.shopify"
           }],
           message: "Product sync queued from Shopify webhook.",
@@ -4860,9 +4919,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.cjs CHANGED Viewed

@@ -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 },
@@ -4055,7 +4112,9 @@ var shopify_default2 = {
           enqueues: [{
             data: { product: productId, providerId, shop: connection2.shop },
             name: "workflow",
-            options: { jobId: "product.workflow.shopify." + providerId + "." + Date.now() },
+            // The numeric id, not the gid: BullMQ refuses a custom id with a
+            // colon in it, and every gid carries two.
+            options: { jobId: "product.workflow.shopify." + context.id + "." + Date.now() },
             queue: "product.shopify"
           }],
           message: "Product sync queued from Shopify webhook.",
@@ -4861,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 CHANGED Viewed

@@ -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 },
@@ -4009,7 +4066,9 @@ var shopify_default2 = {
           enqueues: [{
             data: { product: productId, providerId, shop: connection2.shop },
             name: "workflow",
-            options: { jobId: "product.workflow.shopify." + providerId + "." + Date.now() },
+            // The numeric id, not the gid: BullMQ refuses a custom id with a
+            // colon in it, and every gid carries two.
+            options: { jobId: "product.workflow.shopify." + context.id + "." + Date.now() },
             queue: "product.shopify"
           }],
           message: "Product sync queued from Shopify webhook.",
@@ -4815,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 CHANGED Viewed

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