@drawbridge/drawbridge-utils 0.0.168 → 0.0.170

package/dist/connections/index.d.cts

@@ -1,7 +1,7 @@
 import { authToken } from './oauth.cjs';
 export { consentUrl, pkcePair } from './oauth.cjs';
 import { toE164, detectCountry } from '../phone.cjs';
-import crypto, { createHmac, timingSafeEqual, createVerify, createHash, randomUUID } from 'node:crypto';
+import crypto, { randomUUID, createHmac, timingSafeEqual, createVerify, createHash } from 'node:crypto';
 import { request } from '../http.cjs';
 import { channels } from '../pricing.cjs';
 import { customAlphabet } from 'nanoid';
@@ -186,7 +186,20 @@ const HOOKS = Object.freeze({
 
 	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
@@ -516,6 +529,8 @@ const 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'
@@ -715,7 +730,16 @@ const tokenSettings = ({ existing = {}, now = Date.now(), tokens }) => ({
 	...( tokens.expiresIn && {
 		expiresAt : new Date( now + ( tokens.expiresIn * 1000 ) ).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
+	})
 });
 
 // Returns a token that is good right now, refreshing and persisting first if the
@@ -792,6 +816,176 @@ var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <path d="M166.04 261.805C180.228 259.107 195.528 261.893 207.581 269.971C218.512 277.079 226.908 288.136 230.604 300.657C234.835 314.103 233.614 329.124 227.485 341.788C220.097 356.875 205.782 368.543 189.317 372.089C173.957 375.652 157.089 372.386 144.304 363.103C132.971 355.295 124.912 342.989 121.891 329.581C118.943 316.636 120.725 302.656 127.002 290.938C134.699 275.951 149.503 264.933 166.046 261.811" fill="#1E1C1C"/>
 </svg>`;
 
+// WHERE A DRAWBRIDGE SEGMENT WENT, one row per connection on the segment
+// document. The row is not membership — membership stays as each vendor keeps
+// it, as tags or properties or members — it says which vendor object stands for
+// this segment, and where a merchant can open it.
+//
+// Shared rather than repeated in three manifests because the upsert is the
+// subtle part: two descriptors, each a no-op when the other applies, so a
+// register that changes nothing writes nothing and two concurrent registers
+// converge on ONE ROW rather than two.
+//
+// THE ROW, NOT THE VENDOR OBJECT BEHIND IT. Each manifest searches by name
+// before it creates, which NARROWS the window rather than closing it: two
+// concurrent first registers can both search, both miss and both create, and a
+// drift re-queue carries a deliberately unique job id precisely so it can run
+// alongside a fresh dispatch. What the pair below guarantees is that only one of
+// them is ever pointed at — the loser is an orphaned vendor object, which a
+// merchant can see and delete, and not a row pointing at the wrong thing.
+
+// NO `env` HERE, unlike Shopify's urls.manage( data, env ). That third argument
+// is supplied by the api, which has one; a segment url is built inside a hook,
+// and `env` is not in HOOK_PROPS — so a vendor reaching for it would receive
+// undefined on every run. Threading a parameter nothing can fill is a trap for
+// whoever writes the next manifest.
+const row = ({ connection, data, manifest, row : described }) => ({
+	connection : connection?.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?.id ),
+	slug : connection?.slug,
+	type : 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 : manifest?.urls?.segment?.( { ...described, id : String( described?.id ) }, data ) || null
+});
+
+const segmentRowWrites = ({ connection, data, manifest, row : described, segment }) => {
+
+	const built = row({ connection, data, 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?.id,
+				'connections.connection' : { $ne : connection?.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?.id,
+				connections : {
+					$elemMatch : {
+						connection : connection?.id,
+						$or : [
+							{ id : { $ne : built.id } },
+							{ type : { $ne : built.type } },
+							{ url : { $ne : built.url } }
+						]
+					}
+				}
+			}
+		}
+	];
+
+};
+
+const segmentRowRemoveWrites = ({ connection, segment }) => [
+	{
+		collection : 'segment',
+		data : { $pull : { connections : { connection : connection?.id } } },
+		operation : 'update',
+		query : { id : segment?.id }
+	}
+];
+
+// THE ROW THIS CONNECTION ALREADY HAS, or undefined. The segments the shell
+// hands a hook carry `connections`, so a register can answer "nothing to do"
+// without a read.
+const segmentRowFor = ({ connection, segment }) => ( segment?.connections || [] )
+	.find( ( entry ) => entry?.connection === connection?.id );
+
+// THE SEGMENT AS IT IS NOW, not as it was when this run was dispatched.
+//
+// Four places dispatch register under ONE job id, which is what stops four
+// dispatches becoming four vendor round-trips — but it also means the run
+// carries whichever trigger data won the race. Re-reading is how a coalesced
+// run applies the current title rather than a stale one.
+//
+// Falls back to the passed document when no reader was injected. `read` is an
+// optional capability rather than a guaranteed one — a caller invoking runHook
+// without a database reader still gets a working hook, it just applies the
+// document it was handed.
+const currentSegment = async ({ read, segment }) => {
+
+	if( ! read?.get || ! segment?.id ) return segment;
+
+	return read.get({
+		collection : 'segment',
+		query : { id : segment.id }
+	});
+
+};
+
+// ONE MORE PASS WHEN THE TITLE MOVED UNDER US.
+//
+// A rename that arrives while a register is ACTIVE is dropped, because the
+// coalescing job id still exists — so the vendor object would keep the old name
+// forever. Re-reading at the end catches it, and the re-queue carries a UNIQUE
+// id, since the coalescing one is what dropped the rename in the first place.
+//
+// THE TIMESTAMP AND THE RANDOM SUFFIX ARE BOTH LOAD-BEARING. The timestamp is
+// for a person reading the queue, who needs to see when a drift pass was
+// raised; the random half is what actually makes the id unique, because two
+// drift re-queues for one segment inside the same millisecond would otherwise
+// collide back into a single job — dropping the very rename this exists to
+// recover.
+//
+// ponytail: NO `priority`, unlike every dispatch that goes through
+// drawbridge-sync's dispatchExecute — which computes one per organization so a
+// tenant spiking past its window is deprioritized behind everyone else. A drift
+// re-queue therefore enters at BullMQ's default and jumps that queue. Not
+// fixable by taking a `priority` argument either: the number comes from an
+// in-process counter in sync that this package cannot see and that a manifest
+// hook is never handed. Closing it means sync stamping a priority onto described
+// enqueues in step-runner's perform(), which is a change to every enqueue every
+// hook describes — worth doing when a second caller wants it, not for one
+// re-queue that fires only on a rename that landed mid-register.
+const driftEnqueues = async ({ applied, read, segment, workflow }) => {
+
+	// NOTHING TO RE-QUEUE WITHOUT A WORKFLOW. The enqueue names the workflow to
+	// execute and keys its job id on the same id, so an absent one queues a job
+	// carrying workflowId : undefined under an id holding the literal string
+	// "undefined" — a job that cannot run and that collides with every other
+	// workflowless drift pass.
+	if( ! workflow?.id ) return [];
+
+	const fresh = await currentSegment({ read, segment });
+
+	if( ! fresh?.id || fresh.title === applied ) return [];
+
+	return [ {
+		data : {
+			triggerData : {
+				organization : fresh.organization || workflow?.organization,
+				segment : fresh
+			},
+			workflowId : workflow?.id
+		},
+		name : 'execute',
+		options : {
+			jobId : 'workflow.insert.execute.' + workflow?.id + '.segment.register.' + fresh.id + '.drift.' + Date.now() + '.' + randomUUID().slice( 0, 8 ),
+			removeOnComplete : true,
+			removeOnFail : true
+		},
+		queue : 'workflow'
+	} ];
+
+};
+
 // ONE REQUEST SHAPE for every Attentive call, the way Klaviyo's file has one.
 // The path carries its own version — the segments picker is v2 and the
 // subscription writes are v1 — because Attentive versions per resource rather
@@ -908,7 +1102,7 @@ var attentive = {
 		// 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 — 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 — subscribed for marketing and added to the segment you choose.',
+			'This connection syncs the contacts your campaigns collect into your Attentive account — 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.'
@@ -950,10 +1144,9 @@ var attentive = {
 		}
 	],
 	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 : {
@@ -967,7 +1160,7 @@ var attentive = {
 			// 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
@@ -1187,7 +1380,71 @@ var attentive = {
 			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, context, manifest, settings }, { read } = {} ) => {
+
+				const segment = await currentSegment({ read, segment : context?.segment });
+
+				if( ! segment?.id || segment.system ) return { message : 'That segment is not one this connection publishes.', skipped : true };
+
+				if( ! 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.' + connection?.organization
+					} ],
+					message : 'Contacts in this segment are added to the Attentive segment chosen on this connection.',
+					writes : segmentRowWrites({
+						connection,
+						data : { ...connection, 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
 
@@ -1217,6 +1474,21 @@ var attentive = {
 		'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
@@ -1263,6 +1535,27 @@ var attentive = {
 
 			})
 
+		},
+
+		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' }
+			})
+
 		}
 
 	},
@@ -1280,7 +1573,22 @@ var attentive = {
 			}
 		]
 	),
-	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'
+	}
 };
 
 // THE SHARED HALF OF inbound.verify.
@@ -2145,7 +2453,7 @@ var drawbridge = {
 	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 : [
@@ -2591,6 +2899,12 @@ var drawbridge = {
 		},
 		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.
@@ -2956,6 +3270,33 @@ var drawbridge = {
 	// 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.
@@ -3171,6 +3512,25 @@ const api$1 = async ( path, { fetcher = fetch, method = 'GET', payload, token }
 
 };
 
+// The segment's name at Klaviyo, spelled once. It is a LABEL — the definition
+// below keys on the id — so a rename never has to touch a profile.
+const segmentName = ( title ) => 'Drawbridge: ' + title;
+
+// THE GRANT THIS NEEDS. Klaviyo's scopes are set on the app and a token carries
+// only what the merchant consented to, so a connection made before segments were
+// asked for holds one that cannot write a segment — 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). Answering 403 three times tells the merchant
+// nothing; this does.
+//
+// `scope` is the grant Klaviyo returned on the exchange, which its OAuth guide
+// describes as "The scopes that this access token has access to for accessing
+// API resources" (developers.klaviyo.com/en/docs/set_up_oauth, fetched
+// 2026-09-11) — not the list this manifest asks for, which is why a connection
+// older than the ask reads as false rather than true.
+const canManageSegments = ( settings ) => String( settings?.scope || '' ).split( /\s+/ ).includes( 'segments:write' );
+
 // Klaviyo — contact sync, over OAuth.
 //
 // EVERYTHING ABOUT THIS VENDOR IS IN THIS FILE. Its copy, the fields it stores,
@@ -3220,9 +3580,21 @@ var klaviyo = {
 			// 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.
@@ -3273,9 +3645,10 @@ var klaviyo = {
 		confirm : 'Disconnecting revokes Drawbridge\'s access to your Klaviyo account. Your profiles and lists stay in both Klaviyo and Drawbridge — 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
@@ -3494,6 +3867,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
@@ -3511,13 +3891,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
@@ -3536,7 +3916,14 @@ var klaviyo = {
 									// `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'
@@ -3599,17 +3986,218 @@ var klaviyo = {
 
 		},
 
-		// 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, context, manifest, settings, token, workflow }, { fetcher, read } = {} ) => {
+
+				// AS IT IS NOW — see the same note on Mailchimp's. One job id serves
+				// four dispatch sites, so the trigger data is whichever one won.
+				const segment = await currentSegment({ read, segment : context?.segment });
+
+				if( ! 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 — this connection was made before that permission was asked for.',
+						skipped : true
+					};
+
+				}
+
+				const name = segmentName( segment.title );
+				const existing = segmentRowFor({ connection, segment });
+
+				let id = null;
+
+				if( existing?.id ){
+
+					try {
+
+						const found = await api$1( '/segments/' + existing.id, { fetcher, token });
+
+						id = found?.data?.id ?? existing.id;
+
+						if( found?.data?.attributes?.name !== name ){
+
+							// NAME ONLY. Update Segment takes `name` on its own —
+							// nothing in its attributes is required — and the definition
+							// keys on the segment id, which has not changed, so rewriting
+							// it would rebuild the segment for nothing.
+							await api$1( '/segments/' + existing.id, {
+								fetcher,
+								method : 'PATCH',
+								payload : { data : { attributes : { name }, id : existing.id, type : 'segment' } },
+								token
+							});
+
+						}
+
+					} catch ( error ){
+
+						// A 404 means the merchant deleted the segment themselves — fall
+						// through and rebuild rather than failing a step they caused.
+						if( error.status !== 404 ) throw error;
+
+						id = null;
+
+					}
+
+				}
+
+				// BY NAME BEFORE CREATING, which NARROWS the window rather than
+				// closing it. Klaviyo segment names are not unique, so two
+				// overlapping registers — a contact joining seconds after the segment
+				// was made, or a drift re-queue whose deliberately unique job id lets
+				// it run alongside a fresh dispatch — would otherwise leave a second
+				// segment nothing points at. Two concurrent FIRST registers can still
+				// both search, both miss and both create; only one row survives, so
+				// the loser is an orphaned segment rather than a wrong one.
+				//
+				// `equals` is one of the two operators Get Segments allows on `name`,
+				// and a string argument is quoted: "we will accept either single
+				// quoted or double-quoted strings"
+				// (developers.klaviyo.com/en/docs/filtering_, fetched 2026-09-11).
+				// The whole expression is URI-encoded, which the same page requires.
+				//
+				// THE TITLE IS ESCAPED, because it is free text a merchant types and a
+				// double quote in it would otherwise close the literal early — a
+				// malformed filter is a 400 the step retries three times before
+				// failing with no row written. The same page gives the escape: "Single
+				// or double-quoted characters within strings (quoted with like quote
+				// characters) MUST be escaped with a single backslash (i.e. 'Tony\'s
+				// ball')". Only the matching quote needs it, so a double-quoted
+				// literal escapes double quotes and leaves apostrophes alone.
+				if( ! id ){
+
+					const search = await api$1( '/segments?filter=' + encodeURIComponent( 'equals(name,"' + name.replace( /"/g, '\\"' ) + '")' ), { fetcher, token });
+
+					id = ( search?.data || [] ).find( ( entry ) => entry?.attributes?.name === name )?.id ?? null;
+
+				}
+
+				if( ! id ){
+
+					const created = await api$1( '/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 = created?.data?.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.' + connection?.organization
+					} ],
+					message : 'Klaviyo is carrying this segment as "' + name + '".',
+					writes : segmentRowWrites({
+						connection,
+						data : { ...connection, 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, context, settings, token }, { fetcher } = {} ) => {
+
+				const segment = context?.segment;
+				const existing = segmentRowFor({ connection, segment });
+
+				if( ! 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 api$1( '/segments/' + existing.id, { fetcher, method : 'DELETE', token });
+
+				} catch ( error ){
+
+					// ALREADY GONE IS DONE. The merchant may have deleted it, and
+					// retrying a 404 twice more achieves nothing.
+					if( error.status !== 404 ) throw error;
+
+				}
+
+				return {
+					message : 'Klaviyo is no longer carrying this segment.',
+					writes : segmentRowRemoveWrites({ connection, 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
@@ -3785,6 +4373,18 @@ var klaviyo = {
 		'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.
@@ -3815,7 +4415,8 @@ var klaviyo = {
 					hook : 'lifecycle.health',
 					key : 'Klaviyo Connection Health',
 					queue : 'connection',
-					system : true
+					system : true,
+					trigger : { event : 'day', type : 'schedule' }
 				})
 			}
 
@@ -3868,6 +4469,32 @@ var klaviyo = {
 
 			})
 
+		},
+
+		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' }
+			})
+
 		}
 
 	},
@@ -3876,17 +4503,43 @@ var klaviyo = {
 	// is reconnecting — prompting "choose a list" there asks the merchant to
 	// configure a grant that no longer exists. `pending` is exactly this task's
 	// moment: the grant is good and the list is the missing half.
-	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.list
-		? []
-		: [
-			{
+	tasks : ( data ) => {
+
+		if( ! [ 'active', 'pending' ].includes( data?.status ) ) return [];
+
+		// BOTH, WHEN BOTH APPLY. These are independent facts about one connection
+		// — an old grant that cannot manage segments, and a list nobody picked —
+		// and returning only the first means a merchant fixes it, comes back, and
+		// discovers the second. The grant leads because reconnecting is the longer
+		// errand.
+		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( data?.settings ) ? [] : [ {
+				message : 'Drawbridge now keeps a Klaviyo segment in step with each of your Drawbridge segments. Reconnect Klaviyo to allow it.',
+				title : 'Reconnect Klaviyo'
+			} ] ),
+			...( data?.settings?.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 : ( row ) => ( row?.id ? 'https://www.klaviyo.com/segment/' + row.id : null )
+	}
 };
 
 // Mailchimp, exported from the brand kit and left as authored — the fills are the
@@ -3967,6 +4620,28 @@ const subscriberHash = ( email ) => createHash( 'md5' )
 	.update( String( email ).trim().toLowerCase() )
 	.digest( 'hex' );
 
+// 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.
+//
+// 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 = {
 	// OAUTH 2, authorization code. Every url below is quoted from
@@ -4010,7 +4685,7 @@ var mailchimp = {
 		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 — 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.'
 		],
@@ -4023,6 +4698,7 @@ var mailchimp = {
 			'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.'
 		]
 	},
@@ -4048,10 +4724,9 @@ var mailchimp = {
 		}
 	],
 	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 : {
@@ -4135,6 +4810,45 @@ var mailchimp = {
 
 				const hash = subscriberHash( email );
 
+				// NAME AND PHONE TRAVEL AS MERGE FIELDS, because there is no other
+				// way to write them. Mailchimp's member object has a `full_name`,
+				// but their own schema marks it `"readOnly" : true` — it is DERIVED
+				// from FNAME and LNAME
+				// (api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json,
+				// fetched 2026-09-11), so writing a whole name in one field is not
+				// on offer at any price.
+				//
+				// ONLY THE DEFAULT TAGS. A merge tag the audience does not have is
+				// refused along with the whole member request, and "merge fields
+				// with the tags *|FNAME|*, *|LNAME|*, *|ADDRESS|* and *|PHONE|* are
+				// present by default when an audience is created"
+				// (mailchimp.com/developer/marketing/docs/merge-fields, fetched
+				// 2026-09-11) — so these are the ones safe to send without
+				// registering anything first.
+				//
+				// ADDRESS IS LEFT OUT DELIBERATELY: `lead.address` is an array of
+				// free-text strings and Mailchimp's ADDRESS wants a structured
+				// object (addr1/city/state/zip/country). There is no honest mapping,
+				// and a malformed one takes the member request down with it.
+				//
+				// A lead carries ONE `name`, so the last name is everything after
+				// the first whitespace run — "Ada Lovelace" splits Ada/Lovelace, and
+				// a single-word name sends no LNAME rather than an empty one.
+				const [ firstName, ...restOfName ] = String( lead?.name || '' ).trim().split( /\s+/ ).filter( Boolean );
+
+				const lastName = restOfName.join( ' ' );
+
+				// The raw number the entrant gave, NOT the canonical form: this is a
+				// field the merchant will contact them on, and canonical values are
+				// for identity matching only.
+				const phone = lead?.phone?.number || null;
+
+				const mergeFields = {
+					...( firstName && { FNAME : firstName }),
+					...( lastName && { LNAME : lastName }),
+					...( phone && { PHONE : phone })
+				};
+
 				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
 				//
 				// Omitting them means Mailchimp never learns they said no, so the
@@ -4161,14 +4875,12 @@ var mailchimp = {
 					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?.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'
 					},
@@ -4184,8 +4896,8 @@ var mailchimp = {
 				// and is not built. A tag needs no setup: "If a tag that does not exist
 				// is passed in and set as 'active', a new tag will be created"
 				// (mailchimp.com/developer/marketing/api/list-member-tags/add-or-remove-member-tags,
-				// fetched 2026-09-09). Nothing for the merchant to prepare, so nothing
-				// to explain in the guide.
+				// fetched 2026-09-09). Nothing for the merchant to prepare — the guide
+				// says what appears in their audience, not what to set up first.
 				//
 				// ACTIVE AND INACTIVE IN ONE CALL, which is what keeps this correct
 				// over time. Drawbridge segments are dynamic, and nothing dispatches a
@@ -4226,7 +4938,7 @@ var mailchimp = {
 						.map( ( entry ) => entry.title )
 						.filter( Boolean )
 						.map( ( title ) => ({
-							name : 'Drawbridge: ' + title,
+							name : tagName( title ),
 							status : joined.has( title ) ? 'active' : 'inactive'
 						}) );
 
@@ -4258,12 +4970,215 @@ var mailchimp = {
 			}
 
 		},
-		// 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, context, manifest, settings, token, workflow }, { fetcher, read } = {} ) => {
+
+				const audience = settings?.audience;
+
+				if( ! audience ) return { message : 'No Mailchimp audience is chosen for this connection.', skipped : true };
+
+				// AS IT IS NOW, not as it was dispatched. Four places queue register
+				// under one job id, so this run carries whichever of them won — and
+				// applying that title would undo a rename that arrived after it.
+				const segment = await currentSegment({ read, segment : context?.segment });
+
+				if( ! 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, segment });
+
+				let id = null;
+
+				// BY ID FIRST, because that is the only path that can rename rather
+				// than orphan. A 404 means the merchant deleted the tag themselves —
+				// fall through and rebuild rather than failing a step they caused.
+				if( existing?.id ){
+
+					try {
+
+						const found = await api( '/lists/' + audience + '/segments/' + existing.id, { dc : settings?.dc, fetcher, token });
+
+						id = found?.id ?? existing.id;
+
+						if( found?.name !== name ){
+
+							await api( '/lists/' + audience + '/segments/' + existing.id, {
+								dc : settings?.dc,
+								fetcher,
+								method : 'PATCH',
+								payload : { name },
+								token
+							});
+
+						}
+
+					} catch ( error ){
+
+						if( error.status !== 404 ) throw error;
+
+						id = null;
+
+					}
+
+				}
+
+				// BY NAME BEFORE CREATING, which NARROWS the window rather than
+				// closing it. Two registers can overlap — a contact joining seconds
+				// after the segment was made does it, and a drift re-queue carries a
+				// deliberately unique job id so it can run alongside a fresh dispatch
+				// — and creating without looking leaves a second tag nothing points
+				// at. Two concurrent FIRST registers can still both search, both miss
+				// and both create; only one row survives, so the loser is an orphaned
+				// tag rather than a wrong one. Mailchimp offers no unique-name
+				// constraint to close it properly.
+				//
+				// 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/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.
+				//
+				// NO `count`, because the endpoint takes none: its only parameters are
+				// the list id and `name`
+				// (api.mailchimp.com/schema/3.0/Paths/Lists/TagSearch.json, fetched
+				// 2026-09-11), unlike the audiences hook above where the default of ten
+				// does bite. The response carries `total_items`, which is the one hint
+				// that a page was cut — so if a merchant ever keeps more tags under one
+				// Drawbridge prefix than a page holds, that field is where it shows.
+				if( ! id ){
+
+					const search = await api( '/lists/' + audience + '/tag-search?name=' + encodeURIComponent( name ), { dc : settings?.dc, fetcher, token });
+
+					id = ( search?.tags || [] ).find( ( tag ) => tag?.name === name )?.id ?? null;
+
+				}
+
+				if( ! id ){
+
+					const created = await api( '/lists/' + audience + '/segments', {
+						dc : 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?.id;
+
+				}
+
+				if( ! id ) return { message : 'Mailchimp returned no tag id.', skipped : true };
+
+				// THE AUDIENCE'S WEB ID, which is what the merchant's admin url is
+				// keyed on — the api id in `settings.audience` does not address a page.
+				// Read here rather than at page load, where the data centre is not
+				// decrypted and a vendor round-trip would be on the critical path.
+				const audienceDetail = await api( '/lists/' + audience + '?fields=web_id', { dc : 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.' + connection?.organization
+					} ],
+					message : 'Mailchimp is carrying this segment as the tag "' + name + '".',
+					writes : segmentRowWrites({
+						connection,
+						data : { ...connection, settings },
+						manifest,
+						row : { id, type : 'tag', webId : 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, context, settings, token }, { fetcher } = {} ) => {
+
+				// NO RE-READ HERE. The segment is already deleted — the pre-image is
+				// the only copy there is, and it carries the rows naming what to
+				// remove.
+				const segment = context?.segment;
+				const existing = segmentRowFor({ connection, segment });
+
+				if( ! existing?.id ) return { message : 'Mailchimp was never carrying this segment.', skipped : true };
+
+				try {
+
+					await api( '/lists/' + settings?.audience + '/segments/' + existing.id, {
+						dc : settings?.dc,
+						fetcher,
+						method : 'DELETE',
+						token
+					});
+
+				} catch ( error ){
+
+					// ALREADY GONE IS DONE. The merchant may have deleted it, and
+					// retrying a 404 twice more achieves nothing.
+					//
+					// Mailchimp writes down no 404 for this call — Delete segment
+					// declares a 204 and a generic problem detail and nothing else
+					// (api.mailchimp.com/schema/3.0/Paths/Lists/Segments/Instance.json,
+					// fetched 2026-09-11) — so this follows from their general error
+					// table rather than from anything documented about deleting a
+					// segment. It is still the right handling: a segment that is not
+					// there is the outcome we wanted.
+					if( error.status !== 404 ) throw error;
+
+				}
+
+				return {
+					message : 'Mailchimp is no longer carrying this segment.',
+					writes : segmentRowRemoveWrites({ connection, 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,
@@ -4343,6 +5258,16 @@ var mailchimp = {
 		'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
@@ -4397,6 +5322,34 @@ var mailchimp = {
 
 			})
 
+		},
+
+		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' }
+			})
+
 		}
 
 	},
@@ -4414,7 +5367,23 @@ var mailchimp = {
 			}
 		]
 	),
-	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 : ( row, data ) => ( data?.settings?.dc && row?.webId
+			? 'https://' + data.settings.dc + '.admin.mailchimp.com/lists/members/?id=' + row.webId
+			: null
+		)
+	}
 };
 
 // Shopify, exported from the brand kit and left as authored — the fills are the
@@ -4488,6 +5457,61 @@ const attributeLineItems = ( lineItems = [] ) => lineItems.reduce(
 // types them into a checkout.
 const generateDiscountCode = customAlphabet( '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', 8 );
 
+// WHY A DISCOUNT CANNOT BACK AN ISSUED CODE, as a sentence for the merchant or
+// null when nothing is wrong. Every rule here is about the code we are about to
+// mint being redeemable by an ENTRANT we picked — which is a narrower question
+// than whether the discount is valid in general, and the reason a discount that
+// looks fine in Shopify admin can still be the wrong one to choose.
+//
+// Field semantics cited in drawbridge-shopify's discountsQuery.
+const blockedReason = ( discount ) => {
+
+	if( discount?.status === 'EXPIRED' ) return 'This discount has expired.';
+
+	// The union's "anyone" member. Everything else — named customers, a saved
+	// segment, a market — restricts who may redeem, and a code we mint for an
+	// entrant who is not on that list is a code that fails at checkout. Creating
+	// the customer would not fix it: joining a discount's eligibility list is a
+	// separate write we do not make.
+	const buyers = discount?.context?.__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.';
+
+	}
+	// Documented as possibly lagging the true count, so this can only ever
+	// under-report — count >= limit means genuinely exhausted.
+	if( typeof discount?.usageLimit === 'number' && discount.usageLimit > 0
+		&& ( discount?.asyncUsageCount || 0 ) >= discount.usageLimit ){
+
+		return 'This discount has reached its total usage limit.';
+
+	}
+	return null;
+
+};
+
+// Usable, but about to behave in a way the merchant did not ask for. Separate
+// from blockedReason because the answer here is "go ahead, knowing this" — a
+// scheduled discount is the normal way to set up a campaign in advance, and
+// refusing it would be wrong.
+const discountWarning = ( discount ) => {
+
+	if( discount?.status === 'SCHEDULED' ){
+
+		return 'This discount hasn\'t started yet, so codes issued before it does won\'t work until then.';
+
+	}
+	// One redemption per person, which is usually intended — but it is the
+	// difference between a code that can be forwarded and one that cannot, and
+	// merchants do not expect a per-entrant code to also be per-person capped.
+	if( discount?.appliesOncePerCustomer ) return 'Each customer can use this discount only once.';
+
+	return null;
+
+};
+
 // THE USAGE METER'S EVENT HANDLE — the string that decides whether an order's
 // billing event bills or is silently ingested as a plain custom event. It must
 // equal, case-sensitively, the meter HANDLE configured on the app's plan in
@@ -4588,7 +5612,7 @@ var shopify = {
 		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 — matched through cart parameters and lead-mapped discount codes — 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 : {
@@ -4602,7 +5626,7 @@ var shopify = {
 			'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 — during install, or from the connection page here. The connection shows Pending until you do, then Active.',
-			'Come back here — the connections list updates on its own once the install lands.'
+			'Come back here — 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
@@ -5125,14 +6149,27 @@ var shopify = {
 					? { domain : connection.source.domain, id : connection.source.id }
 					: undefined;
 
+				// EVERY PURCHASE GETS AN ORDER DOCUMENT, whichever way it reached us.
+				//
+				// A redemption used to write only a redemption row, which meant the
+				// money existed on the Redemptions page and nowhere else: contact
+				// totals are summed from the ORDER collection, so a real purchase by a
+				// known entrant contributed nothing to their revenue and was invisible
+				// to every revenue segment. `type` keeps the two kinds apart for the
+				// figures that must stay causal (the fee, the Revenue page's
+				// conversion column) without splitting the source of truth in two.
+				const createsOrder = ! backfill && ( isConversion || Boolean( discount ) );
+
 				// MINTED HERE, because the redemption names its order and the usage
 				// job names both — a description cannot read a write's result, so the
-				// id exists before either does.
-				const orderDocId = existingOrder?.id || ( isConversion && ! backfill ? mintId() : null );
+				// id exists before either does. Minted for the redemption too, so the
+				// order can name it back.
+				const orderDocId = existingOrder?.id || ( createsOrder ? mintId() : null );
+				const redemptionDocId = discount ? mintId() : null;
 
 				const writes = [];
 
-				if( isConversion && ! backfill ){
+				if( createsOrder ){
 
 					writes.push({
 						collection : 'order',
@@ -5154,8 +6191,12 @@ var shopify = {
 							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'
 					});
@@ -5164,7 +6205,14 @@ var shopify = {
 
 						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 }
 						});
@@ -5175,7 +6223,15 @@ var shopify = {
 
 						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 }
@@ -5198,6 +6254,7 @@ var shopify = {
 							customer,
 							discount,
 							gross,
+							id : redemptionDocId,
 							lead : leadId,
 							order : orderDocId,
 							organization : campaignOrganization,
@@ -5233,6 +6290,23 @@ var shopify = {
 
 					}
 
+					// THE BACKFILL LEG: a conversion recorded earlier, matched to one of
+					// our codes now. The order already exists, so nothing above created
+					// it and nothing has told it which redemption it belongs to — this
+					// is the only write that closes that link. Skipped when the order
+					// was created in this same run, because it was minted carrying the
+					// id already.
+					if( backfill && orderDocId && redemptionDocId ){
+
+						writes.push({
+							collection : 'order',
+							data : { $set : { redemption : redemptionDocId } },
+							operation : 'update',
+							query : { id : orderDocId }
+						});
+
+					}
+
 				}
 
 				// SHOPIFY-BILLED ORGS ARE CHARGED THROUGH SHOPIFY, keyed on the order
@@ -6020,10 +7094,24 @@ var shopify = {
 					// The GLOBAL id is what Shopify returns and the bare id is what a
 					// picker stores, which is why the tail is taken here rather than by
 					// each caller that happened to remember.
-					items : ( discounts?.edges || [] ).map( ( edge ) => ({
-						id : String( edge?.node?.id || '' ).split( '/' ).pop(),
-						title : edge?.node?.codeDiscount?.title
-					}) ),
+					items : ( discounts?.edges || [] ).map( ( edge ) => {
+
+						const node = edge?.node?.codeDiscount || {};
+
+						return {
+							// 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( edge?.node?.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 : {
 						endCursor : discounts?.pageInfo?.endCursor || null,
 						hasNextPage : Boolean( discounts?.pageInfo?.hasNextPage )
@@ -6039,24 +7127,6 @@ var shopify = {
 	},
 	icon,
 	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 : ( data, env ) => {
-
-		const shop = data?.shop || data?.settings?.domain;
-
-		return shop
-			? 'https://admin.shopify.com/store/' + String( shop ).replace( '.myshopify.com', '' ) + '/apps/' + env?.SHOPIFY_APP_HANDLE
-			: undefined;
-
-	},
 	// 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
@@ -6102,6 +7172,14 @@ var shopify = {
 		'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
@@ -6194,8 +7272,11 @@ var shopify = {
 			},
 
 			// 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.',
@@ -6231,7 +7312,8 @@ var shopify = {
 					hook : 'lifecycle.health',
 					key : 'Shopify Connection Health',
 					queue : 'connection',
-					system : true
+					system : true,
+					trigger : { event : 'day', type : 'schedule' }
 				})
 			},
 
@@ -6298,7 +7380,34 @@ var shopify = {
 			: []
 		)
 	],
-	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 : ( data, env ) => {
+
+			const shop = data?.shop || data?.settings?.domain;
+
+			return shop
+				? 'https://admin.shopify.com/store/' + String( shop ).replace( '.myshopify.com', '' ) + '/apps/' + env?.SHOPIFY_APP_HANDLE
+				: undefined;
+
+		}
+	}
 };
 
 // Webhooks — the only connection with no third party behind it. Connecting
@@ -6355,7 +7464,7 @@ var webhook = {
 	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.',
@@ -6481,6 +7590,9 @@ var webhook = {
 	// 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 —
@@ -7475,7 +8587,7 @@ const redactSettings = ({ slug, settings }) => {
 const 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
@@ -7567,7 +8679,15 @@ const resolveConnection = ( item, data, env = {} ) => {
 			// answer baked a Pending badge into Klaviyo, Mailchimp and Attentive
 			// cards nobody had connected. Status belongs to the caller's own
 			// read-time pass (api's applyStatus), never to projection.
-			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'provider', 'requires', 'status', 'steps', 'supports' ].includes( key ) )
+			// `urls` is dropped for the same reason `provider` is: it holds raw
+			// functions, and a url built from stored settings must be built where
+			// those settings are already decrypted — the api calls urls.manage()
+			// itself and composes the result into connect.
+			//
+			// `review` is dropped because it is engineering metadata — which docs
+			// were read, on what day — with no client that reads it. Left in, it
+			// would ride on every connection response a merchant's browser loads.
+			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'provider', 'requires', 'review', 'status', 'steps', 'supports', 'urls' ].includes( key ) )
 			.map( ( [ key, value ] ) => [
 				key,
 				( typeof value === 'function' ? value( data, env ) : value )