@drawbridge/drawbridge-utils 0.0.169 → 0.0.171

package/dist/connections/index.cjs

@@ -865,10 +865,11 @@ var attentive_default2 = {
       sync: async ({ lead, settings, suppressed, token }, { fetcher } = {}) => {
         var _a, _b, _c, _d;
         const segment = settings == null ? void 0 : settings.segment;
-        if (!segment) return { message: "No Attentive segment 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);
         const phone = toE164(((_d = (_c = lead == null ? void 0 : lead.canonical) == null ? void 0 : _c.phone) == null ? void 0 : _d.value) || (lead == null ? void 0 : lead.phone));
-        if (!email && !phone) return { message: "That lead has no email address or phone number to sync.", skipped: true };
+        const request2 = { email: email || null, phone: phone || null, segment: (settings == null ? void 0 : settings.segment) || null };
+        if (!segment) return { message: "No Attentive segment is chosen for this connection.", request: request2, skipped: true };
+        if (!email && !phone) return { message: "That lead has no email address or phone number to sync.", request: request2, skipped: true };
         const user = {
           ...email && { email },
           ...phone && { phone }
@@ -890,6 +891,7 @@ var attentive_default2 = {
           });
           return {
             message: "Attentive accepted an unsubscribe for this contact \u2014 they have opted out.",
+            request: request2,
             response: { accepted: true, unsubscribed: true }
           };
         }
@@ -930,6 +932,7 @@ var attentive_default2 = {
           // queued them — a merchant who reads "synced" and looks for the person
           // in Attentive a second later has been told the wrong thing.
           message: "Attentive accepted this contact for the segment. Attentive processes these asynchronously, so it appears there shortly.",
+          request: request2,
           response: {
             accepted: true,
             ...(membership == null ? void 0 : membership.batchJobId) && { batchJobId: membership.batchJobId }
@@ -2946,7 +2949,7 @@ var drawbridge_default2 = {
           text: { max: 2e3, type: "string" }
         },
         triggers: ["schedule.day", "schedule.week", "schedule.month"],
-        usage: { actions: 0 }
+        usage: { actions: channels.email.actionsPerSend }
       }),
       // To organization MEMBERS. Never suppressed — an entrant's opt-out must
       // not silence an alert to staff — and not billed.
@@ -2971,10 +2974,14 @@ var drawbridge_default2 = {
           subject: { max: 150, type: "string" }
         },
         triggers: ["lead.insert"],
-        // Zero is a PRICE, and a deliberate one. Declared rather than omitted
-        // so "this is free" and "nobody decided" stay different statements;
-        // completeStep bills only when actions > 0.
-        usage: { actions: 0 }
+        // EVERY STEP IN A BILLABLE WORKFLOW COUNTS, team mail included. This
+        // leaves our SendGrid account and costs the same to send as any other
+        // email, so it carries the same weight. Whether anything is charged at
+        // all is the workflow's `billable` tag, not the step's audience — and
+        // this step triggers on lead.insert, so a merchant notifying
+        // themselves on every entry spends against their allowance twice per
+        // lead, once for the entry and once for the notification.
+        usage: { actions: channels.email.actionsPerSend }
       }),
       // To a LEAD. Suppression applies and the send is billed.
       send: () => ({
@@ -3330,13 +3337,15 @@ var klaviyo_default2 = {
       // different thing from deleting the profile.
       remove: false,
       sync: async ({ context, lead, segments, settings, suppressed, token }, { fetcher } = {}) => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         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 request2 = { 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) || null, list: (settings == null ? void 0 : settings.list) || null };
+        if (!list) return { message: "No Klaviyo list is chosen for this connection.", request: request2, skipped: true };
+        const email = ((_d = (_c = lead == null ? void 0 : lead.canonical) == null ? void 0 : _c.email) == null ? void 0 : _d.value) || (lead == null ? void 0 : lead.email);
+        if (!email) return { message: "That lead has no email address to sync.", request: request2, skipped: true };
         const person = (context == null ? void 0 : context.contact) || null;
         const totals = (person == null ? void 0 : person.totals) || {};
+        const count = (value) => typeof value === "number" ? value : (value == null ? void 0 : value.total) || 0;
         const profile = await api2("/profile-import", {
           fetcher,
           method: "POST",
@@ -3350,13 +3359,13 @@ var klaviyo_default2 = {
                     drawbridge_campaigns: (person.campaigns || []).length,
                     drawbridge_draws: totals.draws || 0,
                     drawbridge_entries: totals.entries || 0,
-                    drawbridge_orders: totals.orders || 0,
+                    drawbridge_orders: count(totals.orders),
                     // 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
+                    drawbridge_revenue: count(totals.gross)
                   },
                   // THE DRAWBRIDGE SEGMENTS THEY ARE IN, as a list property the
                   // merchant builds Klaviyo segments on top of. Klaviyo owns no
@@ -3390,8 +3399,8 @@ var klaviyo_default2 = {
           },
           token
         });
-        const profileId = (_c = profile == null ? void 0 : profile.data) == null ? void 0 : _c.id;
-        if (!profileId) return { message: "Klaviyo returned no profile id.", skipped: true };
+        const profileId = (_e = profile == null ? void 0 : profile.data) == null ? void 0 : _e.id;
+        if (!profileId) return { message: "Klaviyo returned no profile id.", request: request2, skipped: true };
         await api2("/profile-subscription-bulk-create-jobs/", {
           fetcher,
           method: "POST",
@@ -3420,6 +3429,7 @@ var klaviyo_default2 = {
           // Merged into `context` for later steps in this run.
           context: { klaviyoProfileId: profileId },
           message: suppressed ? "Synced to Klaviyo as unsubscribed \u2014 this contact has opted out." : "Synced to the Klaviyo list.",
+          request: request2,
           // Recorded on the run for support to read back, not a write
           // instruction — the hook has already written what it needed to.
           response: { klaviyoProfileId: profileId }
@@ -3861,7 +3871,8 @@ var api3 = async (path, { dc, fetcher = fetch, method = "GET", payload, token })
   return response.status === 204 ? null : response.json();
 };
 var subscriberHash = (email) => (0, import_node_crypto5.createHash)("md5").update(String(email).trim().toLowerCase()).digest("hex");
-var tagName = (title) => "Drawbridge: " + title;
+var TAG_NAME_LIMIT = 100;
+var tagName = (title) => ("Drawbridge: " + title).slice(0, TAG_NAME_LIMIT);
 var mailchimp_default2 = {
   // OAUTH 2, authorization code. Every url below is quoted from
   // mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/ rather
@@ -3999,15 +4010,16 @@ var mailchimp_default2 = {
       // why there is no create-or-update branch here. Quoted from Mailchimp's
       // Marketing API reference for the list-members resource.
       sync: async ({ connection: connection2, lead, segments, settings, suppressed, token }, { fetcher, read } = {}) => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         const audience = settings == null ? void 0 : settings.audience;
-        if (!audience) return { message: "No Mailchimp audience 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 request2 = { audience: (settings == null ? void 0 : settings.audience) || null, 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) || null };
+        if (!audience) return { message: "No Mailchimp audience is chosen for this connection.", request: request2, skipped: true };
+        const email = ((_d = (_c = lead == null ? void 0 : lead.canonical) == null ? void 0 : _c.email) == null ? void 0 : _d.value) || (lead == null ? void 0 : lead.email);
+        if (!email) return { message: "That lead has no email address to sync.", request: request2, skipped: true };
         const hash = subscriberHash(email);
         const [firstName, ...restOfName] = String((lead == null ? void 0 : lead.name) || "").trim().split(/\s+/).filter(Boolean);
         const lastName = restOfName.join(" ");
-        const phone = ((_c = lead == null ? void 0 : lead.phone) == null ? void 0 : _c.number) || null;
+        const phone = ((_e = lead == null ? void 0 : lead.phone) == null ? void 0 : _e.number) || null;
         const mergeFields = {
           ...firstName && { FNAME: firstName },
           ...lastName && { LNAME: lastName },
@@ -4064,6 +4076,7 @@ var mailchimp_default2 = {
           // Merged into `context` for later steps in this run.
           context: { mailchimpMemberId: (member == null ? void 0 : member.id) || hash },
           message: suppressed ? "Synced to Mailchimp as unsubscribed \u2014 this contact has opted out." : "Synced to the Mailchimp audience.",
+          request: request2,
           // Recorded on the run for support to read back, not a write
           // instruction — the hook has already written what it needed to.
           response: { mailchimpMemberId: (member == null ? void 0 : member.id) || hash }
@@ -4086,10 +4099,12 @@ var mailchimp_default2 = {
       // on attaching people to it by name. Both address the same object. The
       // segment schema says it outright: "The type of segment. Static segments
       // are now known as tags"
-      // (api.mailchimp.com/schema/3.0/Swagger.json, fetched 2026-09-11).
+      // (api.mailchimp.com/schema/3.0/Definitions/Lists/Segments/Response.json,
+      // fetched 2026-09-12 — the root Swagger.json carries no prose, only $refs
+      // into fragment files like this one).
       //
-      // IDEMPOTENT ON EVERY PATH: called on create, on rename, on the boot
-      // sweep and on backfill, it converges. That is what lets one hook serve
+      // IDEMPOTENT ON EVERY PATH: called on create, on rename, on a connection
+      // finishing its configuration, and on the backfill migration, it converges. That is what lets one hook serve
       // all four without a create-vs-update branch anywhere else.
       register: async ({ connection: connection2, context, manifest, settings, token, workflow }, { fetcher, read } = {}) => {
         var _a;
@@ -5097,7 +5112,7 @@ var shopify_default2 = {
       //
       // The shell has already refused a missing or inactive Shopify connection,
       // so what is left is the two things only this hook can know are wrong.
-      product: async ({ connection: connection2, context, workflow }, { mintId } = {}) => {
+      product: async ({ connection: connection2, context, workflow }, { mintId, read } = {}) => {
         const request2 = {
           numericId: (context == null ? void 0 : context.id) || null,
           organizationId: workflow.organization,
@@ -5106,7 +5121,13 @@ var shopify_default2 = {
         if (!(context == null ? void 0 : context.id)) return { message: "Skipped \u2014 product webhook payload had no id.", request: request2, response: { skipped: true }, skipped: true };
         if (!connection2.shop) return { message: "Skipped \u2014 Shopify connection is missing shop domain.", request: request2, response: { skipped: true }, skipped: true };
         const providerId = "gid://shopify/Product/" + context.id;
-        const productId = mintId();
+        const query = {
+          "provider.id": providerId,
+          "provider.slug": "shopify",
+          "source.domain": connection2.shop
+        };
+        const existing = (read == null ? void 0 : read.get) ? await read.get({ collection: "product", query }) : null;
+        const productId = (existing == null ? void 0 : existing.id) || mintId();
         return {
           enqueues: [{
             data: { product: productId, providerId, shop: connection2.shop },
@@ -5136,11 +5157,7 @@ var shopify_default2 = {
             },
             operation: "update",
             options: { upsert: true },
-            query: {
-              "provider.id": providerId,
-              "provider.slug": "shopify",
-              "source.domain": connection2.shop
-            }
+            query
           }]
         };
       }
@@ -5410,7 +5427,7 @@ var shopify_default2 = {
               options: { jobId: "connection.update.register." + workflow.connection + "." + (0, import_node_crypto6.randomUUID)() },
               queue: "connection"
             }],
-            message: ((scopesMissing == null ? void 0 : scopesMissing.length) ? "Health check: ping ok, webhooks reconciled \u2014 connection errored, granted scopes are missing: " + scopesMissing.join(", ") + "." : refreshTokenRotated ? "Health check passed \u2014 refresh token rotated, ping ok, webhooks reconciled." : "Health check passed \u2014 ping ok, webhooks reconciled.") + (sourceRepaired ? " Billing source repaired from the live shop." : "") + (metered === null ? " No usage line on the store's approved plan \u2014 order billing needs the merchant to approve the updated plan." : ""),
+            message: ((scopesMissing == null ? void 0 : scopesMissing.length) ? "Health check: ping ok, scopes reconciled \u2014 connection errored, granted scopes are missing: " + scopesMissing.join(", ") + "." : refreshTokenRotated ? "Health check passed \u2014 refresh token rotated, ping ok, scopes reconciled." : "Health check passed \u2014 ping ok, scopes reconciled.") + (sourceRepaired ? " Billing source repaired from the live shop." : "") + (metered === null ? " No usage line on the store's approved plan \u2014 order billing needs the merchant to approve the updated plan." : ""),
             request: request2,
             response: {
               billingProbeFailed,

package/dist/connections/index.d.cts

@@ -1234,8 +1234,6 @@ var attentive = {
 				// status() already stops a connection reaching Active without a
 				// segment; this is the belt to that braces. A workflow saved before the
 				// segment was chosen must not silently write into nothing.
-				if( ! segment ) return { message : 'No Attentive segment is chosen for this connection.', skipped : true };
-
 				const email = lead?.canonical?.email?.value || lead?.email;
 
 				// E.164 OR NOTHING. Attentive requires it, and a national-format number
@@ -1243,9 +1241,22 @@ var attentive = {
 				// and the email carries the sync instead.
 				const phone = toE164( lead?.canonical?.phone?.value || lead?.phone );
 
+				// WHAT WENT TO THE VENDOR, so a sync run in the activity feed can
+				// answer what was actually sent. The three contact syncs were the only
+				// hook family carrying none, and a merchant opening one saw
+				// request : null. Attentive identifies on either channel, so both are
+				// recorded — which of the two carried the sync is the first question
+				// anyone debugging one of these asks.
+				const request = { email : email || null, phone : phone || null, segment : settings?.segment || null };
+
+				// status() already stops a connection reaching Active without a
+				// segment; this is the belt to that braces. A workflow saved before the
+				// segment was chosen must not silently write into nothing.
+				if( ! segment ) return { message : 'No Attentive segment is chosen for this connection.', request, skipped : true };
+
 				// Their `user` requires phone OR email. With neither there is nobody to
 				// subscribe, so this is a skip rather than a failure.
-				if( ! email && ! phone ) return { message : 'That lead has no email address or phone number to sync.', skipped : true };
+				if( ! email && ! phone ) return { message : 'That lead has no email address or phone number to sync.', request, skipped : true };
 
 				const user = {
 					...( email && { email }),
@@ -1285,6 +1296,7 @@ var attentive = {
 
 					return {
 						message : 'Attentive accepted an unsubscribe for this contact — they have opted out.',
+						request,
 						response : { accepted : true, unsubscribed : true }
 					};
 
@@ -1332,6 +1344,7 @@ var attentive = {
 					// queued them — a merchant who reads "synced" and looks for the person
 					// in Attentive a second later has been told the wrong thing.
 					message : 'Attentive accepted this contact for the segment. Attentive processes these asynchronously, so it appears there shortly.',
+					request,
 					response : {
 						accepted : true,
 						...( membership?.batchJobId && { batchJobId : membership.batchJobId })
@@ -3353,7 +3366,7 @@ var drawbridge = {
 					text : { max : 2000, type : 'string' }
 				},
 				triggers : [ 'schedule.day', 'schedule.week', 'schedule.month' ],
-				usage : { actions : 0 }
+				usage : { actions : channels.email.actionsPerSend }
 			}),
 
 			// To organization MEMBERS. Never suppressed — an entrant's opt-out must
@@ -3379,10 +3392,14 @@ var drawbridge = {
 					subject : { max : 150, type : 'string' }
 				},
 				triggers : [ 'lead.insert' ],
-				// Zero is a PRICE, and a deliberate one. Declared rather than omitted
-				// so "this is free" and "nobody decided" stay different statements;
-				// completeStep bills only when actions > 0.
-				usage : { actions : 0 }
+				// EVERY STEP IN A BILLABLE WORKFLOW COUNTS, team mail included. This
+				// leaves our SendGrid account and costs the same to send as any other
+				// email, so it carries the same weight. Whether anything is charged at
+				// all is the workflow's `billable` tag, not the step's audience — and
+				// this step triggers on lead.insert, so a merchant notifying
+				// themselves on every entry spends against their allowance twice per
+				// lead, once for the entry and once for the notification.
+				usage : { actions : channels.email.actionsPerSend }
 			}),
 
 			// To a LEAD. Suppression applies and the send is billed.
@@ -3835,11 +3852,16 @@ var klaviyo = {
 				// incomplete() already stops a connection reaching Active without a
 				// list; this is the belt to that braces. A workflow saved before the
 				// list was chosen must not silently write into nothing.
-				if( ! list ) return { message : 'No Klaviyo list is chosen for this connection.', skipped : true };
+				// WHAT WENT TO THE VENDOR, so a sync run in the activity feed can answer
+				// what was actually sent. The three contact syncs were the only hook
+				// family that carried none, so a merchant opening one saw request : null.
+				const request = { email : lead?.canonical?.email?.value || lead?.email || null, list : settings?.list || null };
+
+				if( ! list ) return { message : 'No Klaviyo list is chosen for this connection.', request, skipped : true };
 
 				const email = lead?.canonical?.email?.value || lead?.email;
 
-				if( ! email ) return { message : 'That lead has no email address to sync.', skipped : true };
+				if( ! email ) return { message : 'That lead has no email address to sync.', request, skipped : true };
 
 				// A Klaviyo profile is keyed on an email, so IDENTITY comes from the
 				// lead. RANKING comes from the contact behind it, because only a
@@ -3867,6 +3889,13 @@ var klaviyo = {
 				// fetched 2026-09-09).
 				//
 				// IT MERGES, and that is why the blocks below are conditional rather
+				// GROUPED OR FLAT, read as one number. contact.totals.orders and .gross
+				// are { total, conversions, redemptions } now, but a contact the
+				// backfill has not reached still holds the old flat number — and a
+				// naked `totals.orders || 0` would hand Klaviyo the whole object as a
+				// profile property. Klaviyo gets the total either way.
+				const count = ( value ) => typeof value === 'number' ? value : ( value?.total || 0 );
+
 				// 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
@@ -3884,13 +3913,13 @@ var klaviyo = {
 										drawbridge_campaigns : ( person.campaigns || [] ).length,
 										drawbridge_draws : totals.draws || 0,
 										drawbridge_entries : totals.entries || 0,
-										drawbridge_orders : totals.orders || 0,
+										drawbridge_orders : count( totals.orders ),
 										// 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
+										drawbridge_revenue : count( totals.gross )
 									}),
 									// THE DRAWBRIDGE SEGMENTS THEY ARE IN, as a list property the
 									// merchant builds Klaviyo segments on top of. Klaviyo owns no
@@ -3927,7 +3956,7 @@ var klaviyo = {
 
 				const profileId = profile?.data?.id;
 
-				if( ! profileId ) return { message : 'Klaviyo returned no profile id.', skipped : true };
+				if( ! profileId ) return { message : 'Klaviyo returned no profile id.', request, skipped : true };
 
 				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
 				//
@@ -3970,6 +3999,7 @@ var klaviyo = {
 					message : suppressed
 						? 'Synced to Klaviyo as unsubscribed — this contact has opted out.'
 						: 'Synced to the Klaviyo list.',
+					request,
 					// Recorded on the run for support to read back, not a write
 					// instruction — the hook has already written what it needed to.
 					response : { klaviyoProfileId : profileId }
@@ -4616,7 +4646,24 @@ const subscriberHash = ( email ) => createHash( 'md5' )
 // THE TAG'S NAME, and the one place it is spelled. The member write and the
 // register hook must agree character for character — they address the same
 // object, one by name and one by id — so a prefix change is one edit here.
-const tagName = ( title ) => 'Drawbridge: ' + title;
+//
+// TRUNCATED TO 100, because that is Mailchimp's documented ceiling for a tag
+// name ("Tag names can be a maximum of 100 characters",
+// mailchimp.com/help/create-add-remove-tags, fetched 2026-09-12) and a segment
+// title can be 100 on its own — so the prefix pushes any title over 88 past it.
+// The limit is in their help centre and NOT in the API schema, which constrains
+// `name` to a bare string, so what the API does with an over-long name is
+// unspecified: it may reject the whole write or truncate server-side, and a
+// server-side truncation is the worse outcome because register would then look
+// for a name Mailchimp had silently changed.
+//
+// ponytail: two segments whose first 88 characters match would share one tag.
+// The upgrade is to append a short hash of the segment id, which costs the name
+// its readability in the merchant's own audience — not worth it until somebody
+// actually collides.
+const TAG_NAME_LIMIT = 100;
+
+const tagName = ( title ) => ( 'Drawbridge: ' + title ).slice( 0, TAG_NAME_LIMIT );
 
 // Mailchimp — contact sync, not a sender.
 var mailchimp = {
@@ -4773,16 +4820,24 @@ var mailchimp = {
 
 				const audience = settings?.audience;
 
+				// WHAT WENT TO THE VENDOR, recorded on the step so the activity feed
+				// can answer "what did we actually send". Every other hook family
+				// carries one; the three contact syncs did not, so a merchant opening
+				// a sync run saw `request : null` and learned nothing — which is
+				// exactly how it was reported. The audience and the address are the
+				// whole identity of this write.
+				const request = { audience : settings?.audience || null, email : lead?.canonical?.email?.value || lead?.email || null };
+
 				// status() already stops a connection reaching Active without an
 				// audience; this is the belt to that braces. A workflow saved before
 				// the audience was chosen must not silently write into nothing.
-				if( ! audience ) return { message : 'No Mailchimp audience is chosen for this connection.', skipped : true };
+				if( ! audience ) return { message : 'No Mailchimp audience is chosen for this connection.', request, skipped : true };
 
 				const email = lead?.canonical?.email?.value || lead?.email;
 
 				// A Mailchimp member IS an email address — there is no other identity
 				// to write, so a lead without one is skipped rather than failed.
-				if( ! email ) return { message : 'That lead has no email address to sync.', skipped : true };
+				if( ! email ) return { message : 'That lead has no email address to sync.', request, skipped : true };
 
 				const hash = subscriberHash( email );
 
@@ -4938,6 +4993,7 @@ var mailchimp = {
 					message : suppressed
 						? 'Synced to Mailchimp as unsubscribed — this contact has opted out.'
 						: 'Synced to the Mailchimp audience.',
+					request,
 					// Recorded on the run for support to read back, not a write
 					// instruction — the hook has already written what it needed to.
 					response : { mailchimpMemberId : member?.id || hash }
@@ -4964,10 +5020,12 @@ var mailchimp = {
 			// on attaching people to it by name. Both address the same object. The
 			// segment schema says it outright: "The type of segment. Static segments
 			// are now known as tags"
-			// (api.mailchimp.com/schema/3.0/Swagger.json, fetched 2026-09-11).
+			// (api.mailchimp.com/schema/3.0/Definitions/Lists/Segments/Response.json,
+			// fetched 2026-09-12 — the root Swagger.json carries no prose, only $refs
+			// into fragment files like this one).
 			//
-			// IDEMPOTENT ON EVERY PATH: called on create, on rename, on the boot
-			// sweep and on backfill, it converges. That is what lets one hook serve
+			// IDEMPOTENT ON EVERY PATH: called on create, on rename, on a connection
+			// finishing its configuration, and on the backfill migration, it converges. That is what lets one hook serve
 			// all four without a create-vs-update branch anywhere else.
 			register : async ( { connection, context, manifest, settings, token, workflow }, { fetcher, read } = {} ) => {
 
@@ -5033,7 +5091,9 @@ var mailchimp = {
 				// tag-search matches on PREFIX, not on the exact name: "The search
 				// query will be compared to each tag as a prefix, so all tags that
 				// have a name starting with this field will be returned"
-				// (api.mailchimp.com/schema/3.0/Swagger.json, fetched 2026-09-11). So
+				// (api.mailchimp.com/schema/3.0/Parameters/PrefixTagSearchName.json,
+				// fetched 2026-09-12 — the TagSearch path only $refs this parameter, and
+				// the root Swagger.json carries no prose at all). So
 				// "Drawbridge: VIP" answers for "Drawbridge: VIPs" too, and attaching
 				// the row to the first result would point this segment at a different
 				// merchant's tag. The exact name is filtered here.
@@ -6385,7 +6445,7 @@ var shopify = {
 			//
 			// The shell has already refused a missing or inactive Shopify connection,
 			// so what is left is the two things only this hook can know are wrong.
-			product : async ( { connection, context, workflow }, { mintId } = {} ) => {
+			product : async ( { connection, context, workflow }, { mintId, read } = {} ) => {
 
 				const request = {
 					numericId : context?.id || null,
@@ -6401,11 +6461,30 @@ var shopify = {
 
 				const providerId = 'gid://shopify/Product/' + context.id;
 
-				// Minted so the enqueue can name the row this upsert makes — and the
-				// job carries the PROVIDER identity too, because under a concurrent
-				// redelivery this id may be the one that lost the upsert race. The
-				// worker falls back to provider + shop, which are stable either way.
-				const productId = mintId();
+				// THE ROW'S OWN ID WHEN IT ALREADY EXISTS, a fresh one only when it
+				// does not.
+				//
+				// The write below is an upsert whose `id` sits in $setOnInsert, so a
+				// product we have seen before keeps the id it was first given and a
+				// newly minted one is silently discarded. Minting unconditionally
+				// therefore published an id belonging to no row: the enqueue named a
+				// product the worker then had to fall back off, and the step's
+				// response showed QA a value that matched nothing they could look up
+				// — which is exactly how it was reported.
+				//
+				// Reading first costs one indexed lookup on the same key the upsert
+				// matches. A concurrent redelivery can still have both runs miss and
+				// mint, which is why the job carries the PROVIDER identity too and the
+				// worker falls back to provider + shop — stable either way.
+				const query = {
+					'provider.id' : providerId,
+					'provider.slug' : 'shopify',
+					'source.domain' : connection.shop
+				};
+
+				const existing = read?.get ? await read.get({ collection : 'product', query }) : null;
+
+				const productId = existing?.id || mintId();
 
 				return {
 					enqueues : [ {
@@ -6436,11 +6515,7 @@ var shopify = {
 						},
 						operation : 'update',
 						options : { upsert : true },
-						query : {
-							'provider.id' : providerId,
-							'provider.slug' : 'shopify',
-							'source.domain' : connection.shop
-						}
+						query
 					} ]
 				};
 
@@ -6913,10 +6988,10 @@ var shopify = {
 							queue : 'connection'
 						} ],
 						message : ( scopesMissing?.length
-							? 'Health check: ping ok, webhooks reconciled — connection errored, granted scopes are missing: ' + scopesMissing.join( ', ' ) + '.'
+							? 'Health check: ping ok, scopes reconciled — connection errored, granted scopes are missing: ' + scopesMissing.join( ', ' ) + '.'
 							: refreshTokenRotated
-								? 'Health check passed — refresh token rotated, ping ok, webhooks reconciled.'
-								: 'Health check passed — ping ok, webhooks reconciled.'
+								? 'Health check passed — refresh token rotated, ping ok, scopes reconciled.'
+								: 'Health check passed — ping ok, scopes reconciled.'
 						)
 							+ ( sourceRepaired ? ' Billing source repaired from the live shop.' : '' )
 							+ ( metered === null ? ' No usage line on the store\'s approved plan — order billing needs the merchant to approve the updated plan.' : '' ),