@drawbridge/drawbridge-utils 0.0.168 → 0.0.170

package/dist/providers.js

@@ -129,7 +129,20 @@ var HOOKS = Object.freeze({
     "digest"
   ]),
   sms: Object.freeze(["send"]),
-  segment: Object.freeze(["sync"]),
+  segment: Object.freeze([
+    // Make this segment's object exist at the vendor, carrying the segment's
+    // current title, and describe the row that points at it. IDEMPOTENT: the
+    // same call creates it, renames it after an edit, and backfills a segment
+    // that predates the connection — so one hook serves every path and there
+    // is no create-vs-update branch to keep in step.
+    "register",
+    // Remove the vendor object this connection's row points at. Called with
+    // the pre-image on a segment delete, because by then the document is gone.
+    "remove",
+    // Recalculate Drawbridge-side membership. Private to the drawbridge
+    // manifest; a vendor does not own who is in a Drawbridge segment.
+    "sync"
+  ]),
   // OUTBOUND DELIVERY to an address the merchant owns, rather than to a vendor.
   // The Webhooks connection is the only thing here with no third party behind
   // it, and the destination is per STEP rather than per connection.
@@ -238,6 +251,8 @@ var STEPS = Object.freeze({
   "email.digest": "Digest",
   "email.notify": "Notification",
   "email.send": "Send email",
+  "segment.register": "Register segment",
+  "segment.remove": "Remove segment",
   "segment.sync": "Sync segment",
   "sms.send": "Send SMS",
   "webhook.send": "Send webhook"
@@ -373,7 +388,16 @@ var tokenSettings = ({ existing = {}, now = Date.now(), tokens }) => ({
   ...tokens.expiresIn && {
     expiresAt: new Date(now + tokens.expiresIn * 1e3).toISOString()
   },
-  ...tokens.scope && { scope: tokens.scope }
+  // A VENDOR NEED NOT RETURN `scope` ON A REFRESH. Klaviyo documents it on the
+  // authorization_code response and documents no response body at all for the
+  // refresh grant, so taking the minted value alone drops the stored one. That
+  // matters because `scope` is load-bearing: the segment hooks gate on
+  // `segments:write` and answer `skipped` when it is absent, so a connection
+  // that dropped it disables its whole segment half without failing anything
+  // and shows a reconnect task that reconnecting has already fixed.
+  ...(tokens.scope || existing.scope) && {
+    scope: tokens.scope || existing.scope
+  }
 });
 var accessToken = async ({
   clientId,
@@ -436,6 +460,98 @@ var detectCountry = (value) => {
   }
 };
 
+// lib/connections/segment-rows.js
+import { randomUUID } from "crypto";
+var row = ({ connection: connection2, data: data2, manifest, row: described }) => {
+  var _a, _b;
+  return {
+    connection: connection2 == null ? void 0 : connection2.id,
+    // ALWAYS A STRING. Mailchimp tag ids are integers, Klaviyo segment ids are
+    // strings, and one type in the schema is one comparison in the $or below.
+    id: String(described == null ? void 0 : described.id),
+    slug: connection2 == null ? void 0 : connection2.slug,
+    type: described == null ? void 0 : described.type,
+    // NULL, NEVER UNDEFINED: undefined drops the key, and the schema requires it.
+    // The url is built HERE, while the settings are decrypted and the vendor
+    // facts are in hand — an api reading the row later has neither.
+    url: ((_b = (_a = manifest == null ? void 0 : manifest.urls) == null ? void 0 : _a.segment) == null ? void 0 : _b.call(_a, { ...described, id: String(described == null ? void 0 : described.id) }, data2)) || null
+  };
+};
+var segmentRowWrites = ({ connection: connection2, data: data2, manifest, row: described, segment }) => {
+  const built = row({ connection: connection2, data: data2, manifest, row: described });
+  return [
+    // PUSH IF ABSENT. The $ne guard is what makes a second concurrent register
+    // add nothing rather than a duplicate row for one connection.
+    {
+      collection: "segment",
+      data: { $push: { connections: built } },
+      operation: "update",
+      query: {
+        id: segment == null ? void 0 : segment.id,
+        "connections.connection": { $ne: connection2 == null ? void 0 : connection2.id }
+      }
+    },
+    // SET IF DIFFERENT. $elemMatch selects this connection's row only when one
+    // of its three mutable fields disagrees, so the steady state — the same
+    // vendor object, the same url — matches nothing and writes nothing.
+    {
+      collection: "segment",
+      data: { $set: { "connections.$": built } },
+      operation: "update",
+      query: {
+        id: segment == null ? void 0 : segment.id,
+        connections: {
+          $elemMatch: {
+            connection: connection2 == null ? void 0 : connection2.id,
+            $or: [
+              { id: { $ne: built.id } },
+              { type: { $ne: built.type } },
+              { url: { $ne: built.url } }
+            ]
+          }
+        }
+      }
+    }
+  ];
+};
+var segmentRowRemoveWrites = ({ connection: connection2, segment }) => [
+  {
+    collection: "segment",
+    data: { $pull: { connections: { connection: connection2 == null ? void 0 : connection2.id } } },
+    operation: "update",
+    query: { id: segment == null ? void 0 : segment.id }
+  }
+];
+var segmentRowFor = ({ connection: connection2, segment }) => ((segment == null ? void 0 : segment.connections) || []).find((entry) => (entry == null ? void 0 : entry.connection) === (connection2 == null ? void 0 : connection2.id));
+var currentSegment = async ({ read, segment }) => {
+  if (!(read == null ? void 0 : read.get) || !(segment == null ? void 0 : segment.id)) return segment;
+  return read.get({
+    collection: "segment",
+    query: { id: segment.id }
+  });
+};
+var driftEnqueues = async ({ applied, read, segment, workflow }) => {
+  if (!(workflow == null ? void 0 : workflow.id)) return [];
+  const fresh = await currentSegment({ read, segment });
+  if (!(fresh == null ? void 0 : fresh.id) || fresh.title === applied) return [];
+  return [{
+    data: {
+      triggerData: {
+        organization: fresh.organization || (workflow == null ? void 0 : workflow.organization),
+        segment: fresh
+      },
+      workflowId: workflow == null ? void 0 : workflow.id
+    },
+    name: "execute",
+    options: {
+      jobId: "workflow.insert.execute." + (workflow == null ? void 0 : workflow.id) + ".segment.register." + fresh.id + ".drift." + Date.now() + "." + randomUUID().slice(0, 8),
+      removeOnComplete: true,
+      removeOnFail: true
+    },
+    queue: "workflow"
+  }];
+};
+
 // lib/connections/providers/attentive.js
 var api = async (path, { fetcher = fetch, method = "GET", payload, token }) => {
   const response = await fetcher("https://api.attentivemobile.com" + path, {
@@ -488,7 +604,7 @@ var attentive_default2 = {
     // has to say so rather than let them believe otherwise.
     confirm: "Disconnecting removes Drawbridge's stored Attentive token. Attentive does not offer a way for us to revoke it, so remove the Drawbridge integration in Attentive as well if you want its access fully withdrawn. Your subscribers stay in both Attentive and Drawbridge \u2014 neither list is deleted.",
     description: [
-      "Attentive is where your SMS marketing lives, and this connection syncs the contacts your campaigns collect into an Attentive segment \u2014 subscribed for marketing and added to the segment you choose.",
+      "This connection syncs the contacts your campaigns collect into your Attentive account \u2014 subscribed for marketing, and added to the segment you choose.",
       "You authorize Drawbridge from inside Attentive and can revoke that access there at any time. Drawbridge never sees or stores your Attentive password.",
       "Anyone who has opted out in Drawbridge is sent to Attentive as an unsubscribe rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.",
       "Attentive accepts these updates and applies them in the background, so a contact appears in your segment shortly after the sync rather than the instant it runs."
@@ -530,10 +646,9 @@ var attentive_default2 = {
     }
   ],
   group: "contacts",
-  // A HOOK'S VALUE IS ITS ANSWER. The consent is stored and can be revoked;
-  // nothing else is built yet, because subscriber sync has not shipped. Every
-  // false here is "not yet" rather than "never" — when the sync lands, probe
-  // and contacts.sync are the first to flip.
+  // WHAT THIS VENDOR DOES AND DOES NOT DO is the value of each hook below, not
+  // a paragraph up here that goes stale the moment one of them is implemented
+  // — which is exactly what happened to the note this replaces.
   hooks: {
     auth: {
       // FALSE, NOT {}. `{}` means "supported, implemented in the repo with the
@@ -546,7 +661,7 @@ var attentive_default2 = {
       // nobody re-derives it. Klaviyo's connect reads the account name back so
       // the card is not blank; Attentive's card stays blank. There IS an
       // endpoint — GET https://api.attentivemobile.com/v1/me, Bearer, described
-      // on docs.attentive.com/pages/authentication/ as returning "information
+      // on docs.attentive.com/docs/authentication as returning "information
       // specific to your company" — but its RESPONSE SCHEMA is published
       // nowhere we can read: the docs show the curl and no body. Reading
       // `body.name` would be a guess, and a guess here fails at the worst
@@ -713,7 +828,62 @@ var attentive_default2 = {
       products: false,
       promotions: false
     },
-    segment: false,
+    segment: {
+      // A FOUNDATION, AND HONEST ABOUT IT. Attentive's segments API can create
+      // one with an externalId we choose (docs.attentive.com/reference/
+      // createsegment.md, fetched 2026-09-11: POST /v2/segments, `name`
+      // required, `externalId` optional and "auto-generated if not supplied"),
+      // which would give a real per-segment object — but it takes
+      // segments:write, and scopes ride on the app registration, which does not
+      // exist yet.
+      //
+      // So the row points at the connection-level segment the merchant chose,
+      // `type` says so, and turning this into a per-segment object later is a
+      // change to this file and nothing else: create with
+      // externalId = segment.id, PATCH to rename, archive on remove. Their
+      // update and archive endpoints are BOTH keyed by external id
+      // (docs.attentive.com/reference/patchsegmentbyexternalid.md and
+      // /deletesegmentbyexternalid.md, fetched 2026-09-11), so the segment id we
+      // already hold addresses every one of the three calls.
+      //
+      // NO DRIFT CHECK, unlike the other two: the row points at the
+      // connection's own segment and the link is the index page, so nothing
+      // here depends on the Drawbridge segment's title — a rename has nothing
+      // to apply and nothing to race with. That comes back with the
+      // per-segment object.
+      //
+      // THE RE-READ STAYS ALL THE SAME. It changes nothing today, and this is
+      // the simplest of the three registers and therefore the one the next
+      // vendor gets copied from — one job id serves four dispatch sites, so a
+      // copy that trusts context.segment applies whichever trigger data won
+      // the race, at a vendor where the title does matter.
+      register: async ({ connection: connection2, context, manifest, settings }, { read } = {}) => {
+        const segment = await currentSegment({ read, segment: context == null ? void 0 : context.segment });
+        if (!(segment == null ? void 0 : segment.id) || segment.system) return { message: "That segment is not one this connection publishes.", skipped: true };
+        if (!(settings == null ? void 0 : settings.segment)) return { message: "No Attentive segment is chosen for this connection.", skipped: true };
+        return {
+          events: [{
+            event: "organization.segments",
+            payload: { id: segment.id },
+            room: "organization." + (connection2 == null ? void 0 : connection2.organization)
+          }],
+          message: "Contacts in this segment are added to the Attentive segment chosen on this connection.",
+          writes: segmentRowWrites({
+            connection: connection2,
+            data: { ...connection2, settings },
+            manifest,
+            row: { id: settings.segment, type: "segment" },
+            segment
+          })
+        };
+      },
+      // NOT OURS TO DELETE. The segment on this connection is the merchant's,
+      // and it is where every Drawbridge segment's contacts go — removing it
+      // because one Drawbridge segment was deleted would empty the others.
+      remove: false,
+      // Drawbridge-side membership belongs to the private manifest.
+      sync: false
+    },
     sms: false,
     webhook: false
   },
@@ -742,6 +912,21 @@ var attentive_default2 = {
     "ATTENTIVE_OAUTH_CLIENT_ID",
     "ATTENTIVE_OAUTH_CLIENT_SECRET"
   ],
+  // THE CHECKLIST'S RECEIPT — see drawbridge-docs reference/connection-hooks.md.
+  review: {
+    api: "https://docs.attentive.com/reference/listsegments",
+    dashboard: "https://docs.attentive.com/docs/segments",
+    // THIS PAGE DOES NOT LIST EVERY SCOPE. Its table names five —
+    // events:write, ecommerce:write, subscriptions:write, attributes:write,
+    // privacy_requests:write — and says nothing about segments:read or
+    // segments:write, which the segments API this manifest calls does take.
+    // The header at the top of this file carries that distinction; it is
+    // repeated here so a reviewer following the link is not misled by what the
+    // table omits (fetched 2026-09-11).
+    scopes: "https://docs.attentive.com/docs/authentication",
+    content: "2026-09-11",
+    verified: null
+  },
   slug: "attentive",
   // A consent with no segment chosen is authenticated and inert — the sync needs
   // somewhere to put people — so the card says Pending rather than Active over
@@ -779,6 +964,24 @@ var attentive_default2 = {
         triggers: ["lead.insert", "segment.contact.add"],
         usage: { actions: 1 }
       })
+    },
+    segment: {
+      // SYSTEM, so the builder never offers it and a merchant POST refuses it:
+      // this fires from the segment's own lifecycle, not from a workflow
+      // somebody assembled. The trigger is declared here rather than hard-coded
+      // in drawbridge-sync.
+      //
+      // REGISTER ONLY. There is no remove step because hooks.segment.remove is
+      // declined, and build() refuses a step pointing at a hook this vendor does
+      // not implement — so the two are one decision, enforced at import.
+      register: () => ({
+        description: "Records which Attentive segment a Drawbridge segment's contacts are added to.",
+        hook: "segment.register",
+        key: "Attentive Segment Register",
+        queue: "connection",
+        system: true,
+        trigger: { event: "segment.register", type: "event" }
+      })
     }
   },
   // WHY, in the merchant's words, and what to do about it.
@@ -795,7 +998,21 @@ var attentive_default2 = {
       }
     ];
   },
-  title: "Attentive"
+  title: "Attentive",
+  // ATTENTIVE'S SEGMENTS INDEX. There is no documented per-segment url, and the
+  // only identifier we hold is the API's externalId, which their UI may not
+  // path by — so this lands on the list, where the merchant finds it by name.
+  // A per-segment link arrives with the per-segment object (see hooks.segment).
+  //
+  // THE PATH ITSELF IS NOT PUBLISHED ANYWHERE CITABLE, the same gap Klaviyo's
+  // segment url carries. What is on record is that the segments area lives at
+  // ui.attentivemobile.com/segments — its /segments/create/ and /segments/manual
+  // sub-routes are publicly indexed pages (fetched 2026-09-11) — while the /all
+  // tab is not, and Attentive's help centre refuses automated fetches. The dev
+  // walk-through confirms this against a real account before promote.
+  urls: {
+    segment: () => "https://ui.attentivemobile.com/segments/all"
+  }
 };
 
 // lib/connections/providers/drawbridge.js
@@ -1915,7 +2132,7 @@ var drawbridge_default2 = {
   content: {
     confirm: "This connection is part of Drawbridge and cannot be disconnected.",
     description: [
-      "Drawbridge sends your notification email and SMS, keeps your segments in sync, and posts to your own endpoints. These are built in rather than connected, so there is nothing here to set up."
+      "Drawbridge sends your notification emails and your entrants' emails, and recalculates segment membership on a schedule. It is always on and needs nothing connected."
     ],
     excerpt: "The steps Drawbridge runs itself.",
     guide: [
@@ -2228,6 +2445,11 @@ var drawbridge_default2 = {
       promotions: false
     },
     segment: {
+      // NOT DRAWBRIDGE'S. Registering a segment means creating an object at a
+      // vendor, and this manifest has no vendor behind it — the three that do
+      // implement these.
+      register: false,
+      remove: false,
       // RECALCULATE SEGMENT MEMBERSHIP. The one FAN-OUT hook: it evaluates every
       // contact in an organization against every segment, which is too much for
       // one job, so it returns chunks and the shell defers completion.
@@ -2503,6 +2725,33 @@ var drawbridge_default2 = {
   // caught exactly that: availableConnections({}) went from [ 'drawbridge' ] to
   // empty the moment this was added.
   requires: [],
+  // PRIVATE, NOT VENDORLESS. SendGrid, Twilio and HubSpot are behind this
+  // manifest, so `false` would be a lie about which reads were made.
+  //
+  // ONE ENTRY PER VENDOR, because three vendors are three reads. A single
+  // citation here would evidence one of them and read as though it covered all
+  // three, which is the omission this key exists to catch.
+  review: {
+    api: {
+      // lib/hubspot.js posts to /crm/v3/objects/contacts.
+      hubspot: "https://developers.hubspot.com/docs/reference/api/crm/objects/contacts",
+      // lib/sendgrid.js posts to /v3/mail/send.
+      sendgrid: "https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send",
+      // lib/twilio.js posts to /2010-04-01/Accounts/{Sid}/Messages.json, and
+      // hooks.inbound.verify reads the MessageStatus this resource documents.
+      twilio: "https://www.twilio.com/docs/messaging/api/message-resource"
+    },
+    dashboard: {
+      hubspot: "https://knowledge.hubspot.com/contacts/create-contacts",
+      sendgrid: "https://www.twilio.com/docs/sendgrid/ui/analytics-and-reporting/email-activity-feed",
+      twilio: "https://www.twilio.com/docs/messaging/guides/debugging-tools"
+    },
+    // An admin types these keys in; there is no merchant consent and no scope
+    // model on any of the three.
+    scopes: false,
+    content: "2026-09-11",
+    verified: null
+  },
   slug: "drawbridge",
   // Always on. There is no credential that could go bad and no configuration a
   // merchant could leave half-finished.
@@ -2694,6 +2943,8 @@ var api2 = async (path, { fetcher = fetch, method = "GET", payload, token }) =>
   }
   return response.status === 204 ? null : response.json();
 };
+var segmentName = (title) => "Drawbridge: " + title;
+var canManageSegments = (settings) => String((settings == null ? void 0 : settings.scope) || "").split(/\s+/).includes("segments:write");
 var klaviyo_default2 = {
   // OAuth 2.1, and PKCE is REQUIRED rather than recommended: Klaviyo refuses an
   // exchange without a code_verifier matching the challenge the consent
@@ -2723,9 +2974,21 @@ var klaviyo_default2 = {
       // exchange, and a copy here would be a second answer that goes stale.
       expiry: 90 * 24 * 60 * 60,
       pkce: true,
+      // EVERY SCOPE THE MANIFEST'S HOOKS NEED, not the ones today's hooks use.
+      // Klaviyo holds scopes on the APP — "Pinpoint which scopes your app uses
+      // and set them using a space-separated list"
+      // (developers.klaviyo.com/en/docs/create_a_public_oauth_app, fetched
+      // 2026-09-11) — and a merchant's token only ever carries what they
+      // consented to, so a scope added later is a reconnect for every one of
+      // them. That is what segments cost when they were left out here.
+      //
       // Space separated. accounts:read is required by Klaviyo on every app
-      // and must stay in the list; the rest are what a contact sync needs.
-      scopes: "accounts:read lists:read lists:write profiles:read profiles:write",
+      // and must stay in the list; the rest are what a contact sync and the
+      // segment hooks need — Get Segments lists `segments:read`, Create,
+      // Update and Delete Segment each list `segments:write`
+      // (raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable.json,
+      // revision 2026-07-15, fetched 2026-09-11).
+      scopes: "accounts:read lists:read lists:write profiles:read profiles:write segments:read segments:write",
       // EVERY VENDOR URL, in one place. `revoke` used to be a literal inside
       // the disconnect hook — three vendor addresses, two of them declared,
       // which is exactly the kind of split that goes unnoticed.
@@ -2774,9 +3037,10 @@ var klaviyo_default2 = {
     // Shown at disconnect, so it says what is lost and what is not.
     confirm: "Disconnecting revokes Drawbridge's access to your Klaviyo account. Your profiles and lists stay in both Klaviyo and Drawbridge \u2014 neither is deleted.",
     description: [
-      "Connecting Klaviyo lets Drawbridge sync the contacts your campaigns collect into a Klaviyo list, so the people who enter a giveaway can be marketed to alongside the rest of your audience.",
+      "Connecting Klaviyo lets Drawbridge sync the contacts your campaigns collect into a Klaviyo list, so you can market to the people who enter a giveaway alongside the rest of your audience.",
       "You authorize Drawbridge from inside Klaviyo and can revoke that access there at any time. Drawbridge never sees or stores your Klaviyo password, and only asks for the permissions listed on the consent screen.",
-      "Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing."
+      "Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.",
+      "Drawbridge writes its own properties onto the profiles it syncs: how many of your campaigns someone entered, their entries, draws and orders, the revenue their orders attributed to your campaigns, and which Drawbridge segments they are in. You can build Klaviyo segments and flows on any of them."
     ],
     // KEYED BY WHAT FAILED, not nested inside it. Errors are the thing most
     // likely to grow — resources.* has already earned somewhere to put "we
@@ -2933,6 +3197,7 @@ var klaviyo_default2 = {
         if (!email) return { message: "That lead has no email address to sync.", 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",
@@ -2946,13 +3211,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
@@ -2971,7 +3236,14 @@ var klaviyo_default2 = {
                   // `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) }
+                  ...segments && { drawbridge_segments: segments.map((entry) => entry.title).filter(Boolean) },
+                  // THE IDS, which is what a Drawbridge-made segment's definition
+                  // filters on. Ids rather than titles, so renaming a segment is a
+                  // name change at Klaviyo and not a resync of every profile.
+                  //
+                  // The titles stay beside them: merchants have been building
+                  // their own segments on that array since it shipped.
+                  ...segments && { drawbridge_segment_ids: segments.map((entry) => entry.id).filter(Boolean) }
                 }
               },
               type: "profile"
@@ -3015,17 +3287,141 @@ var klaviyo_default2 = {
         };
       }
     },
-    // A WHOLE DOMAIN CAN DECLINE AT ONCE. Klaviyo sends us nothing and we
-    // register nothing with it, so listing four falses would be noise around a
-    // single decision. Still explicit — absence would not say whether anybody
-    // considered it.
-    // Drawbridge sends its own notification email and SMS, and owns its own
-    // segments — see the private `drawbridge` manifest. A vendor answering
-    // these would be a second sender, which is the arrangement the platform
-    // sender replaced.
+    // Drawbridge sends its own notification email. A vendor answering this
+    // would be a second sender, which is the arrangement the platform sender
+    // replaced. Declined as one line rather than one per verb, because the whole
+    // domain is one decision — still explicit, since absence would not say
+    // whether anybody considered it.
     email: false,
-    segment: false,
+    // SEGMENTS ARE SHARED, not owned by one side. Drawbridge holds the
+    // membership — see the private `drawbridge` manifest, and `sync : false`
+    // below — while register and remove keep a Klaviyo segment standing for
+    // each Drawbridge segment, so the merchant can target one in their own
+    // flows.
+    segment: {
+      // THE KLAVIYO SEGMENT THIS DRAWBRIDGE SEGMENT BECOMES.
+      //
+      // Klaviyo owns no writable membership — its segments are computed from
+      // rules — so the segment we create is DEFINED BY the profile property
+      // contacts.sync writes. The definition filters on the Drawbridge
+      // segment's ID, never its title, which is what makes a rename one PATCH
+      // instead of a resync of every profile in it.
+      register: async ({ connection: connection2, context, manifest, settings, token, workflow }, { fetcher, read } = {}) => {
+        var _a, _b, _c, _d, _e;
+        const segment = await currentSegment({ read, segment: context == null ? void 0 : context.segment });
+        if (!(segment == null ? void 0 : segment.id) || segment.system) return { message: "That segment is not one this connection publishes.", skipped: true };
+        if (!canManageSegments(settings)) {
+          return {
+            message: "Reconnect Klaviyo to let Drawbridge manage segments \u2014 this connection was made before that permission was asked for.",
+            skipped: true
+          };
+        }
+        const name = segmentName(segment.title);
+        const existing = segmentRowFor({ connection: connection2, segment });
+        let id = null;
+        if (existing == null ? void 0 : existing.id) {
+          try {
+            const found = await api2("/segments/" + existing.id, { fetcher, token });
+            id = ((_a = found == null ? void 0 : found.data) == null ? void 0 : _a.id) ?? existing.id;
+            if (((_c = (_b = found == null ? void 0 : found.data) == null ? void 0 : _b.attributes) == null ? void 0 : _c.name) !== name) {
+              await api2("/segments/" + existing.id, {
+                fetcher,
+                method: "PATCH",
+                payload: { data: { attributes: { name }, id: existing.id, type: "segment" } },
+                token
+              });
+            }
+          } catch (error) {
+            if (error.status !== 404) throw error;
+            id = null;
+          }
+        }
+        if (!id) {
+          const search = await api2("/segments?filter=" + encodeURIComponent('equals(name,"' + name.replace(/"/g, '\\"') + '")'), { fetcher, token });
+          id = ((_d = ((search == null ? void 0 : search.data) || []).find((entry) => {
+            var _a2;
+            return ((_a2 = entry == null ? void 0 : entry.attributes) == null ? void 0 : _a2.name) === name;
+          })) == null ? void 0 : _d.id) ?? null;
+        }
+        if (!id) {
+          const created = await api2("/segments", {
+            fetcher,
+            method: "POST",
+            // THE DEFINITION IS THE MEMBERSHIP. Create Segment requires one
+            // — `name` and `definition` are both required on its attributes
+            // — and a custom profile property is addressed as
+            // "properties['property name']", tested with a list filter whose
+            // operator is `contains`
+            // (raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable.json,
+            // revision 2026-07-15, fetched 2026-09-11).
+            payload: {
+              data: {
+                attributes: {
+                  definition: {
+                    condition_groups: [{
+                      conditions: [{
+                        filter: { operator: "contains", type: "list", value: segment.id },
+                        property: "properties['drawbridge_segment_ids']",
+                        type: "profile-property"
+                      }]
+                    }]
+                  },
+                  name
+                },
+                type: "segment"
+              }
+            },
+            token
+          });
+          id = (_e = created == null ? void 0 : created.data) == null ? void 0 : _e.id;
+        }
+        if (!id) return { message: "Klaviyo returned no segment id.", skipped: true };
+        return {
+          // A RENAME THAT ARRIVED WHILE THIS RAN was dropped by the
+          // coalescing job id, so the last thing this does is look again.
+          enqueues: await driftEnqueues({ applied: segment.title, read, segment, workflow }),
+          events: [{
+            event: "organization.segments",
+            payload: { id: segment.id },
+            room: "organization." + (connection2 == null ? void 0 : connection2.organization)
+          }],
+          message: 'Klaviyo is carrying this segment as "' + name + '".',
+          writes: segmentRowWrites({
+            connection: connection2,
+            data: { ...connection2, settings },
+            manifest,
+            row: { id, type: "segment" },
+            segment
+          })
+        };
+      },
+      // NO RE-READ. The segment is already deleted; the pre-image is the only
+      // copy, and it carries the row naming what to delete.
+      remove: async ({ connection: connection2, context, settings, token }, { fetcher } = {}) => {
+        const segment = context == null ? void 0 : context.segment;
+        const existing = segmentRowFor({ connection: connection2, segment });
+        if (!(existing == null ? void 0 : existing.id)) return { message: "Klaviyo was never carrying this segment.", skipped: true };
+        if (!canManageSegments(settings)) {
+          return { message: "Reconnect Klaviyo to let Drawbridge manage segments.", skipped: true };
+        }
+        try {
+          await api2("/segments/" + existing.id, { fetcher, method: "DELETE", token });
+        } catch (error) {
+          if (error.status !== 404) throw error;
+        }
+        return {
+          message: "Klaviyo is no longer carrying this segment.",
+          writes: segmentRowRemoveWrites({ connection: connection2, segment })
+        };
+      },
+      // Drawbridge-side membership belongs to the private manifest.
+      sync: false
+    },
+    // Declined for the same reason as `email` above: Drawbridge sends its own
+    // notification SMS, and a vendor answering this would be a second sender.
     sms: false,
+    // Klaviyo sends us nothing — no inbound message to receive, no signature
+    // to verify.
     inbound: false,
     // Nothing to set up or tear down at the vendor: the grant is the whole
     // integration. What CAN rot is the grant itself, so health is the one
@@ -3146,6 +3542,18 @@ var klaviyo_default2 = {
     "KLAVIYO_OAUTH_CLIENT_ID",
     "KLAVIYO_OAUTH_CLIENT_SECRET"
   ],
+  // THE CHECKLIST'S RECEIPT — see drawbridge-docs reference/connection-hooks.md.
+  review: {
+    api: "https://developers.klaviyo.com/en/reference/api_overview",
+    dashboard: "https://help.klaviyo.com/hc/en-us/articles/115005078647",
+    // THE SCOPE TABLE, not the OAuth walk-through. set_up_oauth carries one
+    // example scope string and nothing to check a manifest against; this page
+    // lists the scopes each API takes, segments:read and segments:write among
+    // them (fetched 2026-09-11).
+    scopes: "https://developers.klaviyo.com/en/docs/authenticate_",
+    content: "2026-09-11",
+    verified: null
+  },
   slug: "klaviyo",
   // ONE OF THE FOUR STATES AND NOTHING ELSE — the reason sits in `tasks`, which
   // is already the merchant-facing copy channel and is already rendered.
@@ -3176,7 +3584,8 @@ var klaviyo_default2 = {
           hook: "lifecycle.health",
           key: "Klaviyo Connection Health",
           queue: "connection",
-          system: true
+          system: true,
+          trigger: { event: "day", type: "schedule" }
         })
       }
     },
@@ -3220,6 +3629,28 @@ var klaviyo_default2 = {
           usage: { actions: 1 }
         };
       }
+    },
+    segment: {
+      // SYSTEM, so the builder never offers it and a merchant POST refuses it:
+      // these fire from the segment's own lifecycle, not from a workflow
+      // somebody assembled. The trigger is declared here rather than hard-coded
+      // in drawbridge-sync.
+      register: () => ({
+        description: "Keeps a matching Klaviyo segment for each Drawbridge segment, built on the segment ids Drawbridge writes onto your profiles.",
+        hook: "segment.register",
+        key: "Klaviyo Segment Register",
+        queue: "connection",
+        system: true,
+        trigger: { event: "segment.register", type: "event" }
+      }),
+      remove: () => ({
+        description: "Deletes the Klaviyo segment for a Drawbridge segment when the segment is deleted.",
+        hook: "segment.remove",
+        key: "Klaviyo Segment Remove",
+        queue: "connection",
+        system: true,
+        trigger: { event: "segment.remove", type: "event" }
+      })
     }
   },
   // WHY, in the merchant's words, and what to do about it.
@@ -3229,14 +3660,32 @@ var klaviyo_default2 = {
   // moment: the grant is good and the list is the missing half.
   tasks: (data2) => {
     var _a;
-    return !["active", "pending"].includes(data2 == null ? void 0 : data2.status) || ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? [] : [
-      {
+    if (!["active", "pending"].includes(data2 == null ? void 0 : data2.status)) return [];
+    return [
+      // A connection made before segments were requested is authenticated and
+      // cannot manage them, and no error surfaces anywhere else — the register
+      // runs skip rather than fail.
+      ...canManageSegments(data2 == null ? void 0 : data2.settings) ? [] : [{
+        message: "Drawbridge now keeps a Klaviyo segment in step with each of your Drawbridge segments. Reconnect Klaviyo to allow it.",
+        title: "Reconnect Klaviyo"
+      }],
+      ...((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? [] : [{
         message: "Choose which Klaviyo list your contacts should sync into. Until you do, nothing is being synced.",
         title: "Choose a list"
-      }
+      }]
     ];
   },
-  title: "Klaviyo"
+  title: "Klaviyo",
+  // KLAVIYO PUBLISHES NO DASHBOARD URLS in its API reference. What is on record
+  // is its own help centre on a list: "you can find a list's ID in the URL in
+  // your browser when viewing this list"
+  // (help.klaviyo.com/hc/en-us/articles/115005078647, fetched 2026-09-11), and a
+  // segment's page is the sibling form of it. The path itself is NOT published
+  // anywhere citable, so the dev walk-through confirms this against a real
+  // account before promote.
+  urls: {
+    segment: (row2) => (row2 == null ? void 0 : row2.id) ? "https://www.klaviyo.com/segment/" + row2.id : null
+  }
 };
 
 // lib/connections/providers/mailchimp.js
@@ -3273,6 +3722,8 @@ var api3 = async (path, { dc, fetcher = fetch, method = "GET", payload, token })
   return response.status === 204 ? null : response.json();
 };
 var subscriberHash = (email) => createHash2("md5").update(String(email).trim().toLowerCase()).digest("hex");
+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
@@ -3315,7 +3766,7 @@ var mailchimp_default2 = {
     confirm: "Disconnecting removes Drawbridge's stored Mailchimp access. You can also remove Drawbridge from the Authorized Apps page in your Mailchimp account. Your contacts stay in both Drawbridge and Mailchimp \u2014 neither list is deleted.",
     description: [
       "Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Messaging in your organization settings puts your own brand in the from line.",
-      "Connecting Mailchimp lets Drawbridge sync the contacts your campaigns collect into a Mailchimp audience, so the people who enter a giveaway can be marketed to alongside the rest of your list.",
+      "Connecting Mailchimp lets Drawbridge sync the contacts your campaigns collect into a Mailchimp audience, so you can market to the people who enter a giveaway alongside the rest of your list.",
       "Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.",
       "Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before."
     ],
@@ -3328,6 +3779,7 @@ var mailchimp_default2 = {
       "Sign in to Mailchimp if you are not already, and choose the account to connect.",
       "You come back here to pick the audience your contacts should sync into.",
       "The connection shows Pending until you pick an audience, then Active.",
+      'Each of your Drawbridge segments appears in that audience as a tag named "Drawbridge: " plus the segment name. Renaming a segment in Drawbridge renames its tag, and deleting the segment deletes the tag.',
       "You can remove Drawbridge at any time from the Authorized Apps page in your Mailchimp account."
     ]
   },
@@ -3353,10 +3805,9 @@ var mailchimp_default2 = {
     }
   ],
   group: "contacts",
-  // A HOOK'S VALUE IS ITS ANSWER. A key is stored and can be removed; nothing
-  // else is built yet, because audience sync has not shipped. Every false here
-  // is "not yet" rather than "never" — when the sync lands, probe and
-  // contacts.sync are the first to flip.
+  // WHAT THIS VENDOR DOES AND DOES NOT DO is the value of each hook below, not
+  // a paragraph up here that goes stale the moment one of them is implemented
+  // — which is exactly what happened to the note this replaces.
   hooks: {
     auth: {
       // WHERE THE ACCOUNT LIVES. Not enrichment — without this the connection
@@ -3410,26 +3861,32 @@ 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;
+        var _a, _b, _c;
         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 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 mergeFields = {
+          ...firstName && { FNAME: firstName },
+          ...lastName && { LNAME: lastName },
+          ...phone && { PHONE: phone }
+        };
         const member = await api3("/lists/" + audience + "/members/" + hash, {
           dc: settings == null ? void 0 : settings.dc,
           fetcher,
           method: "PUT",
           payload: {
             email_address: email,
-            // FNAME ONLY. Unlike Klaviyo, Mailchimp's custom fields are not
-            // schemaless — a merge tag that does not exist on the audience is
-            // refused, taking the whole request with it — and FNAME is one of
-            // the two tags every audience is created with. The Drawbridge
-            // totals Klaviyo receives cannot travel until something registers
-            // merge fields on the chosen audience, which is lifecycle.register's
-            // job and is not built.
-            ...(lead == null ? void 0 : lead.name) && { merge_fields: { FNAME: String(lead.name).trim().split(/\s+/)[0] } },
+            // Built above. Omitted entirely when there is nothing to say, so a
+            // lead with only an address does not send an empty object. The
+            // Drawbridge totals Klaviyo receives still cannot travel this way —
+            // those are custom tags, and registering them on the chosen audience
+            // is lifecycle.register's job and is not built.
+            ...Object.keys(mergeFields).length > 0 && { merge_fields: mergeFields },
             ...suppressed && { status: "unsubscribed" },
             status_if_new: suppressed ? "unsubscribed" : "subscribed"
           },
@@ -3452,7 +3909,7 @@ var mailchimp_default2 = {
           });
           const joined = new Set(segments.map((entry) => entry.title));
           const tags = (owned || []).map((entry) => entry.title).filter(Boolean).map((title) => ({
-            name: "Drawbridge: " + title,
+            name: tagName(title),
             status: joined.has(title) ? "active" : "inactive"
           }));
           if (tags.length > 0) {
@@ -3475,12 +3932,122 @@ var mailchimp_default2 = {
         };
       }
     },
-    // Drawbridge sends its own notification email and SMS, and owns its own
-    // segments — see the private `drawbridge` manifest. A vendor answering
-    // these would be a second sender, which is the arrangement the platform
-    // sender replaced.
+    // Drawbridge sends its own notification email. A vendor answering this
+    // would be a second sender, which is the arrangement the platform sender
+    // replaced.
     email: false,
-    segment: false,
+    // SEGMENTS ARE SHARED, not owned by one side. Drawbridge holds the
+    // membership — see the private `drawbridge` manifest, and `sync : false`
+    // below — while register and remove keep a Mailchimp tag standing for each
+    // Drawbridge segment, so the merchant can target one in their own audience.
+    segment: {
+      // THE TAG THIS SEGMENT IS, held by id at last.
+      //
+      // Tags ARE static segments in Mailchimp's model — same collection, same
+      // ids — so this creates one through /segments and the member write goes
+      // 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/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 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;
+        const audience = settings == null ? void 0 : settings.audience;
+        if (!audience) return { message: "No Mailchimp audience is chosen for this connection.", skipped: true };
+        const segment = await currentSegment({ read, segment: context == null ? void 0 : context.segment });
+        if (!(segment == null ? void 0 : segment.id) || segment.system) return { message: "That segment is not one this connection publishes.", skipped: true };
+        const name = tagName(segment.title);
+        const existing = segmentRowFor({ connection: connection2, segment });
+        let id = null;
+        if (existing == null ? void 0 : existing.id) {
+          try {
+            const found = await api3("/lists/" + audience + "/segments/" + existing.id, { dc: settings == null ? void 0 : settings.dc, fetcher, token });
+            id = (found == null ? void 0 : found.id) ?? existing.id;
+            if ((found == null ? void 0 : found.name) !== name) {
+              await api3("/lists/" + audience + "/segments/" + existing.id, {
+                dc: settings == null ? void 0 : settings.dc,
+                fetcher,
+                method: "PATCH",
+                payload: { name },
+                token
+              });
+            }
+          } catch (error) {
+            if (error.status !== 404) throw error;
+            id = null;
+          }
+        }
+        if (!id) {
+          const search = await api3("/lists/" + audience + "/tag-search?name=" + encodeURIComponent(name), { dc: settings == null ? void 0 : settings.dc, fetcher, token });
+          id = ((_a = ((search == null ? void 0 : search.tags) || []).find((tag) => (tag == null ? void 0 : tag.name) === name)) == null ? void 0 : _a.id) ?? null;
+        }
+        if (!id) {
+          const created = await api3("/lists/" + audience + "/segments", {
+            dc: settings == null ? void 0 : settings.dc,
+            fetcher,
+            method: "POST",
+            // STATIC WITH NO MEMBERS. The member sync attaches people by
+            // name; this call only has to make the object exist. Mailchimp's
+            // own wording for the empty array: "Passing an empty array will
+            // create a static segment without any subscribers."
+            payload: { name, static_segment: [] },
+            token
+          });
+          id = created == null ? void 0 : created.id;
+        }
+        if (!id) return { message: "Mailchimp returned no tag id.", skipped: true };
+        const audienceDetail = await api3("/lists/" + audience + "?fields=web_id", { dc: settings == null ? void 0 : settings.dc, fetcher, token });
+        return {
+          // A RENAME THAT ARRIVED WHILE THIS RAN was dropped by the
+          // coalescing job id, so the last thing this does is look again.
+          enqueues: await driftEnqueues({ applied: segment.title, read, segment, workflow }),
+          events: [{
+            event: "organization.segments",
+            payload: { id: segment.id },
+            room: "organization." + (connection2 == null ? void 0 : connection2.organization)
+          }],
+          message: 'Mailchimp is carrying this segment as the tag "' + name + '".',
+          writes: segmentRowWrites({
+            connection: connection2,
+            data: { ...connection2, settings },
+            manifest,
+            row: { id, type: "tag", webId: audienceDetail == null ? void 0 : audienceDetail.web_id },
+            segment
+          })
+        };
+      },
+      // THE TAG GOES WITH THE SEGMENT. Leaving it behind is the orphan this
+      // whole pair exists to stop — every member would keep a label for a
+      // segment that no longer exists.
+      remove: async ({ connection: connection2, context, settings, token }, { fetcher } = {}) => {
+        const segment = context == null ? void 0 : context.segment;
+        const existing = segmentRowFor({ connection: connection2, segment });
+        if (!(existing == null ? void 0 : existing.id)) return { message: "Mailchimp was never carrying this segment.", skipped: true };
+        try {
+          await api3("/lists/" + (settings == null ? void 0 : settings.audience) + "/segments/" + existing.id, {
+            dc: settings == null ? void 0 : settings.dc,
+            fetcher,
+            method: "DELETE",
+            token
+          });
+        } catch (error) {
+          if (error.status !== 404) throw error;
+        }
+        return {
+          message: "Mailchimp is no longer carrying this segment.",
+          writes: segmentRowRemoveWrites({ connection: connection2, segment })
+        };
+      },
+      // Drawbridge-side membership belongs to the private manifest.
+      sync: false
+    },
+    // Declined for the same reason as `email` above: Drawbridge sends its own
+    // notification SMS, and a vendor answering this would be a second sender.
     sms: false,
     inbound: false,
     lifecycle: false,
@@ -3543,6 +4110,16 @@ var mailchimp_default2 = {
     "MAILCHIMP_OAUTH_CLIENT_ID",
     "MAILCHIMP_OAUTH_CLIENT_SECRET"
   ],
+  // THE CHECKLIST'S RECEIPT — see drawbridge-docs reference/connection-hooks.md.
+  review: {
+    api: "https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/",
+    dashboard: "https://mailchimp.com/help/manage-tags/",
+    // NO SCOPES EXIST. Mailchimp's OAuth guide describes none, and a token is
+    // account-wide — so there is nothing to request and nothing to re-consent.
+    scopes: false,
+    content: "2026-09-11",
+    verified: null
+  },
   slug: "mailchimp",
   // A grant with no audience chosen is authenticated and useless — the sync has
   // nowhere to put anyone — so the card must say Pending rather than Active over
@@ -3588,6 +4165,30 @@ var mailchimp_default2 = {
         // adds this step, and what is charged when it runs.
         usage: { actions: 1 }
       })
+    },
+    segment: {
+      // SYSTEM, so the builder never offers it and a merchant POST refuses it:
+      // these fire from the segment's own lifecycle, not from a workflow
+      // somebody assembled.
+      //
+      // The trigger is declared HERE rather than hard-coded in drawbridge-sync,
+      // which is what lets a vendor arrive with its own without a queue edit.
+      register: () => ({
+        description: "Keeps a matching tag in your Mailchimp audience for each Drawbridge segment, and renames it when the segment is renamed.",
+        hook: "segment.register",
+        key: "Mailchimp Segment Register",
+        queue: "connection",
+        system: true,
+        trigger: { event: "segment.register", type: "event" }
+      }),
+      remove: () => ({
+        description: "Deletes the Mailchimp tag for a Drawbridge segment when the segment is deleted.",
+        hook: "segment.remove",
+        key: "Mailchimp Segment Remove",
+        queue: "connection",
+        system: true,
+        trigger: { event: "segment.remove", type: "event" }
+      })
     }
   },
   // WHY, in the merchant's words, and what to do about it.
@@ -3604,11 +4205,27 @@ var mailchimp_default2 = {
       }
     ];
   },
-  title: "Mailchimp"
+  title: "Mailchimp",
+  // THE MERCHANT'S OWN ADMIN. Mailchimp's list schema states the shape outright:
+  // the web_id field is "The ID used in the Mailchimp web application. View this
+  // list in your Mailchimp account at
+  // https://{dc}.admin.mailchimp.com/lists/members/?id={web_id}"
+  // (api.mailchimp.com/schema/3.0/Definitions/Lists/Response.json, fetched
+  // 2026-09-11).
+  //
+  // It lands on the audience's contacts, where the Drawbridge tag is one filter
+  // away. Mailchimp documents no url that pre-selects a tag, so this stops one
+  // click short rather than guessing at one that could break silently.
+  urls: {
+    segment: (row2, data2) => {
+      var _a;
+      return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.dc) && (row2 == null ? void 0 : row2.webId) ? "https://" + data2.settings.dc + ".admin.mailchimp.com/lists/members/?id=" + row2.webId : null;
+    }
+  }
 };
 
 // lib/connections/providers/shopify.js
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { customAlphabet as customAlphabet2 } from "nanoid";
 
 // lib/connections/icons/shopify.js
@@ -3724,6 +4341,28 @@ var attributeLineItems = (lineItems = []) => lineItems.reduce(
   { attrMap: {}, attributedGross: 0, attributedLines: [] }
 );
 var generateDiscountCode = customAlphabet2("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ", 8);
+var blockedReason = (discount) => {
+  var _a;
+  if ((discount == null ? void 0 : discount.status) === "EXPIRED") return "This discount has expired.";
+  const buyers = (_a = discount == null ? void 0 : discount.context) == null ? void 0 : _a.__typename;
+  if (buyers && buyers !== "DiscountBuyerSelectionAll") {
+    return "This discount is limited to specific buyers in Shopify, so a code issued to an entrant won't work. Set it to all customers to use it here.";
+  }
+  ;
+  if (typeof (discount == null ? void 0 : discount.usageLimit) === "number" && discount.usageLimit > 0 && ((discount == null ? void 0 : discount.asyncUsageCount) || 0) >= discount.usageLimit) {
+    return "This discount has reached its total usage limit.";
+  }
+  ;
+  return null;
+};
+var discountWarning = (discount) => {
+  if ((discount == null ? void 0 : discount.status) === "SCHEDULED") {
+    return "This discount hasn't started yet, so codes issued before it does won't work until then.";
+  }
+  ;
+  if (discount == null ? void 0 : discount.appliesOncePerCustomer) return "Each customer can use this discount only once.";
+  return null;
+};
 var ORDER_EVENT_HANDLE = slugify("drawbridge-orders");
 var REFRESH_TOKEN_FRESHNESS_BUFFER_MS = 5 * 24 * 60 * 60 * 1e3;
 var OAUTH_ERROR_SOURCE = "oauth";
@@ -3771,7 +4410,7 @@ var shopify_default2 = {
     description: [
       "Installing the Drawbridge app from the Shopify App Store links your store to a single Drawbridge organization and makes your product catalog available inside Drawbridge, so you can feature products in your campaigns and advertisements.",
       "Drawbridge attributes orders that originate from your campaigns \u2014 matched through cart parameters and lead-mapped discount codes \u2014 so you can see the revenue each campaign drives.",
-      "On connect, Drawbridge registers webhooks for product and order updates to keep your catalog and revenue in sync. Disconnecting removes those webhooks and unlinks the resources."
+      "Drawbridge reads your products, records orders placed through your campaigns, and can issue discount codes. Order and product updates reach Drawbridge through the app's own webhooks, which Shopify applies when the app is installed."
     ],
     errors: {
       connect: {
@@ -3785,7 +4424,7 @@ var shopify_default2 = {
       "Open the Drawbridge listing on the Shopify App Store.",
       "Install the app on the store you want to connect. It opens in Shopify admin and stays there.",
       "Approve the Drawbridge plan when prompted \u2014 during install, or from the connection page here. The connection shows Pending until you do, then Active.",
-      "Come back here \u2014 the connections list updates on its own once the install lands."
+      "Come back here \u2014 the connections list updates on its own once the install finishes."
     ],
     // Names where the link GOES rather than what it does: installing happens on
     // the App Store listing, and the dashboard must never imply a store can be
@@ -4161,9 +4800,11 @@ var shopify_default2 = {
           phone: customerPhone
         } : null;
         const source = (connection2 == null ? void 0 : connection2.source) ? { domain: connection2.source.domain, id: connection2.source.id } : void 0;
-        const orderDocId = (existingOrder == null ? void 0 : existingOrder.id) || (isConversion && !backfill ? mintId() : null);
+        const createsOrder = !backfill && (isConversion || Boolean(discount));
+        const orderDocId = (existingOrder == null ? void 0 : existingOrder.id) || (createsOrder ? mintId() : null);
+        const redemptionDocId = discount ? mintId() : null;
         const writes = [];
-        if (isConversion && !backfill) {
+        if (createsOrder) {
           writes.push({
             collection: "order",
             data: {
@@ -4184,15 +4825,25 @@ var shopify_default2 = {
               provider: { id: String(orderId), slug: "shopify" },
               purchasedAt,
               rate,
+              // Null on a conversion that matched no code of ours; the
+              // backfill branch below sets it when one arrives later.
+              redemption: redemptionDocId,
               source,
-              status: "completed"
+              status: "completed",
+              type: isConversion ? "conversion" : "redemption"
             },
             operation: "create"
           });
           if (org == null ? void 0 : org.usage) {
             writes.push({
               collection: "usage",
-              data: { $inc: { "totals.revenue": gross } },
+              // TWO METERS, NOT ONE SUMMED. `revenue` has always meant
+              // conversion revenue and is the figure the fee is charged
+              // against, so redemption money gets its own key rather than
+              // changing what an existing number means.
+              data: {
+                $inc: isConversion ? { "totals.revenue": gross } : { "totals.redemptionRevenue": gross }
+              },
               operation: "update",
               query: { id: org.usage }
             });
@@ -4200,7 +4851,12 @@ var shopify_default2 = {
           if (leadId) {
             writes.push({
               collection: "lead",
-              data: { $inc: { "totals.orders": 1 } },
+              // Same grouped shape the contact carries, so a lead and the
+              // contact built from it cannot be read two different ways.
+              data: { $inc: {
+                "totals.orders.total": 1,
+                ...isConversion ? { "totals.orders.conversions": 1 } : { "totals.orders.redemptions": 1 }
+              } },
               operation: "update",
               options: { bypassDocumentValidation: true },
               query: { id: leadId }
@@ -4219,6 +4875,7 @@ var shopify_default2 = {
               customer,
               discount,
               gross,
+              id: redemptionDocId,
               lead: leadId,
               order: orderDocId,
               organization: campaignOrganization,
@@ -4247,6 +4904,14 @@ var shopify_default2 = {
               query: { id: leadId }
             });
           }
+          if (backfill && orderDocId && redemptionDocId) {
+            writes.push({
+              collection: "order",
+              data: { $set: { redemption: redemptionDocId } },
+              operation: "update",
+              query: { id: orderDocId }
+            });
+          }
         }
         const billable = (org == null ? void 0 : org.billingProvider) === "shopify" && fee > 0 && !backfill;
         const providerRow2 = billable ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
@@ -4625,7 +5290,7 @@ var shopify_default2 = {
                 event: "shopify.register.webhooks"
               },
               name: "register",
-              options: { jobId: "connection.update.register." + workflow.connection + "." + randomUUID() },
+              options: { jobId: "connection.update.register." + workflow.connection + "." + randomUUID2() },
               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." : ""),
@@ -4739,10 +5404,19 @@ var shopify_default2 = {
           // picker stores, which is why the tail is taken here rather than by
           // each caller that happened to remember.
           items: ((discounts == null ? void 0 : discounts.edges) || []).map((edge) => {
-            var _a2, _b2, _c;
+            var _a2, _b2;
+            const node = ((_a2 = edge == null ? void 0 : edge.node) == null ? void 0 : _a2.codeDiscount) || {};
             return {
-              id: String(((_a2 = edge == null ? void 0 : edge.node) == null ? void 0 : _a2.id) || "").split("/").pop(),
-              title: (_c = (_b2 = edge == null ? void 0 : edge.node) == null ? void 0 : _b2.codeDiscount) == null ? void 0 : _c.title
+              // Null when the discount can be used, a sentence when it cannot.
+              // The picker greys the row and shows this instead of hiding it:
+              // a discount the merchant can see in Shopify admin, missing here
+              // with no explanation, reads as a bug in us.
+              blocked: blockedReason(node),
+              id: String(((_b2 = edge == null ? void 0 : edge.node) == null ? void 0 : _b2.id) || "").split("/").pop(),
+              // Usable, but not in the way the merchant probably expects.
+              // Shown beside the row without stopping them.
+              warning: discountWarning(node),
+              title: node.title
             };
           }),
           pageInfo: {
@@ -4757,20 +5431,6 @@ var shopify_default2 = {
   },
   icon: shopify_default,
   inbound,
-  // THE DEEP LINK into this store's Drawbridge app inside Shopify admin.
-  //
-  // Here rather than in drawbridge-api, which had `slug === 'shopify' && {...}`
-  // in the shared resolver — a hardcoded vendor branch in code every vendor runs
-  // through, which is the arrangement these manifests exist to remove.
-  //
-  // Undefined until a shop is linked, so the Manage button only appears on a
-  // connected connection. The app handle is NAMED by `requires` and read from
-  // the env the resolver passes, never from process.env here.
-  manage: (data2, env) => {
-    var _a;
-    const shop = (data2 == null ? void 0 : data2.shop) || ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.domain);
-    return shop ? "https://admin.shopify.com/store/" + String(shop).replace(".myshopify.com", "") + "/apps/" + (env == null ? void 0 : env.SHOPIFY_APP_HANDLE) : void 0;
-  },
   // DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
   // what an admin types on the provider screen. The four names below are exactly
   // what `requires` gates on, which is the point of declaring them together: a
@@ -4816,6 +5476,14 @@ var shopify_default2 = {
     "SHOPIFY_APP_LISTING_URL",
     "SHOPIFY_APP_HANDLE"
   ],
+  // THE CHECKLIST'S RECEIPT — see drawbridge-docs reference/connection-hooks.md.
+  review: {
+    api: "https://shopify.dev/docs/api/admin-graphql",
+    dashboard: "https://help.shopify.com/en/manual/apps",
+    scopes: "https://shopify.dev/docs/api/usage/access-scopes",
+    content: "2026-09-11",
+    verified: null
+  },
   slug: "shopify",
   // The install is the whole configuration — Shopify hands back the shop and
   // there is nothing further to choose. `shop` absent means the install did not
@@ -4903,8 +5571,11 @@ var shopify_default2 = {
         })
       },
       // SYSTEM STEPS: dispatched by drawbridge-sync itself rather than offered
-      // in the builder, so they carry no trigger and no usage. Declared because
-      // the routing table and the system-workflow descriptions both read here.
+      // in the builder, so they carry no usage. These two are fired by a webhook
+      // arriving rather than by a workflow trigger, so they name none either —
+      // and naming none is what stops a workflow being provisioned for them.
+      // Declared because the routing table and the system-workflow descriptions
+      // both read here.
       order: {
         record: () => ({
           description: "Records an order and billing charge when a purchase is made via a Drawbridge campaign link.",
@@ -4936,7 +5607,8 @@ var shopify_default2 = {
           hook: "lifecycle.health",
           key: "Shopify Connection Health",
           queue: "connection",
-          system: true
+          system: true,
+          trigger: { event: "day", type: "schedule" }
         })
       },
       // Audit-only. The "Shopify Token Activity" system workflow lists these
@@ -4997,7 +5669,30 @@ var shopify_default2 = {
       ] : []
     ];
   },
-  title: "Shopify"
+  title: "Shopify",
+  // THE VENDOR'S OWN ADMIN, one function per thing worth linking to. It lives
+  // here rather than at the top level so a second link (a product, an order)
+  // is a key in this object instead of a new manifest key nobody agreed on.
+  //
+  // AND HERE RATHER THAN IN drawbridge-api, which had `slug === 'shopify' &&
+  // {...}` in the shared resolver — a hardcoded vendor branch in code every
+  // vendor runs through, which is the arrangement these manifests exist to
+  // remove.
+  //
+  // Never projected: the api composes connect.manage from it, and
+  // resolveConnection drops the object, because a url built from settings is
+  // built where the settings are already decrypted.
+  urls: {
+    // Undefined until a shop is linked, so the Manage button only appears on a
+    // connected connection. The app handle is NAMED by `requires` and read from
+    // the env its caller passes — the api's resolve() hands it the stored
+    // credentials, never process.env.
+    manage: (data2, env) => {
+      var _a;
+      const shop = (data2 == null ? void 0 : data2.shop) || ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.domain);
+      return shop ? "https://admin.shopify.com/store/" + String(shop).replace(".myshopify.com", "") + "/apps/" + (env == null ? void 0 : env.SHOPIFY_APP_HANDLE) : void 0;
+    }
+  }
 };
 
 // lib/connections/providers/webhook.js
@@ -5177,7 +5872,7 @@ var webhook_default = {
   content: {
     confirm: "Disconnecting stops Drawbridge from sending signed webhook payloads to your endpoint.",
     description: [
-      "Drawbridge can POST event payloads to your endpoint as activity happens in your account, so your own systems can react in real time.",
+      "Drawbridge can POST event payloads to your endpoint as activity happens in your account, so your own systems can react to it.",
       "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.",
@@ -5278,6 +5973,9 @@ var webhook_default = {
   // Gated on the encryption secret: without it the signing secret could not be
   // stored safely, so the connection must not be offered at all.
   requires: ["ENCRYPT_CONNECTION_SECRET"],
+  // NO THIRD PARTY AT ALL. There is no vendor reference to read, no dashboard
+  // to link to and no scope to request: connecting mints a secret.
+  review: false,
   // Outbound only. inbound.* is false because the direction is the point: we
   // sign and POST to the merchant's endpoint, they never call us. Every other
   // false follows from there being no third party to authenticate against —
@@ -5584,7 +6282,7 @@ var mergeSettings = ({ existing, incoming }) => {
 var publicConnectionKeys = Object.freeze([
   "actions",
   // API-COMPOSED, not manifest-declared: the api's resolve() builds it from
-  // auth.type, content.redirect and the manifest's manage() — the client reads
+  // auth.type, content.redirect and the manifest's urls.manage() — the client reads
   // connect.type to choose entered-vs-installed, connect.redirect for the App
   // Store link, connect.manage for the admin deep link. It was dropped from
   // this list when the manifests stopped declaring it, which stripped the
@@ -5643,20 +6341,20 @@ var clearProviderMemo = () => providerMemo.clear();
 var providerRow = async ({ controller, slug: slug2 }) => {
   const memoized = providerMemo.get(slug2);
   if (memoized && Date.now() - memoized.at < MEMO_TTL_MS) return memoized.value;
-  const row = await controller.get({
+  const row2 = await controller.get({
     collection: "provider",
     query: { slug: slug2 }
   });
   const value = {
-    enabled: (row == null ? void 0 : row.enabled) !== false,
-    settings: (row == null ? void 0 : row.settings) ? decrypt(row.settings) : {}
+    enabled: (row2 == null ? void 0 : row2.enabled) !== false,
+    settings: (row2 == null ? void 0 : row2.settings) ? decrypt(row2.settings) : {}
   };
   providerMemo.set(slug2, { at: Date.now(), value });
   return value;
 };
 var providerSettings = async ({ controller, includeDisabled = false, slug: slug2 }) => {
-  const row = await providerRow({ controller, slug: slug2 });
-  return row.enabled || includeDisabled ? row.settings : {};
+  const row2 = await providerRow({ controller, slug: slug2 });
+  return row2.enabled || includeDisabled ? row2.settings : {};
 };
 var vendorEnabled = async ({ controller, vendor }) => (await providerRow({ controller, slug: vendor })).enabled;
 var vendorSettings = async ({ controller, slug: slug2 }) => {