@drawbridge/drawbridge-utils 0.0.111 → 0.0.114

package/dist/connections/index.d.ts

@@ -1,6 +1,26 @@
-import { refresh } from './oauth.js';
-export { consentUrl, exchange, pkcePair } from './oauth.js';
-import { createHmac, timingSafeEqual } from 'node:crypto';
+import { authToken } from './oauth.js';
+export { consentUrl, pkcePair } from './oauth.js';
+import { channels } from '../pricing.js';
+import { request } from '../http.js';
+import crypto, { createHmac, timingSafeEqual } from 'node:crypto';
+import { safeRequest } from '../safe-http.js';
+import '../plans.js';
+import '../features.js';
+import '../index.js';
+import 'currency-codes';
+import 'nanoid';
+import '../color.js';
+import 'tinycolor2';
+import '../usage.js';
+import '../billing.js';
+import '../transactions.js';
+import '@drawbridge/drawbridge-telemetry';
+import 'dns';
+import 'node:http';
+import 'node:https';
+import '../axios.js';
+import 'axios';
+import 'net';
 
 // THE HOOK VOCABULARY. Closed, and every connection answers all of it.
 //
@@ -34,11 +54,26 @@ const HOOKS = Object.freeze({
 		// the credential can be valid and the grant still be too narrow.
 		'scopes',
 		// Revoke at the vendor and drop what we hold.
-		'disconnect'
+		'disconnect',
+		// MINT A TOKEN — from a consent code, or from a stored refresh token. Both
+		// are the same POST, so they are one hook.
+		//
+		// The default body is authToken() in oauth.js and most vendors point
+		// straight at it. It is a hook rather than a declared flag because the
+		// vendors that differ, differ in ways config cannot express: Klaviyo needs
+		// HTTP Basic where others want body fields, and Mailchimp cannot use the
+		// token it receives until a second call tells it which data centre the
+		// account is behind.
+		'token'
 	]),
 
 	// What happens around connecting and disconnecting, beyond the credential.
 	lifecycle : Object.freeze([
+		// KEEP ACCESS WORKING. Rotate a credential before its window closes, prove
+		// it still works, and reconcile whatever the vendor has changed underneath
+		// — scopes, webhooks. Distinct from auth.probe, which only answers "is this
+		// still good": this one FIXES what it can and reports what it cannot.
+		'health',
 		// Post-connect setup: register the vendor's webhooks, create the system
 		// workflows that describe them.
 		'register',
@@ -94,10 +129,89 @@ const HOOKS = Object.freeze({
 		'process'
 	]),
 
-	// Vendor data a campaign draws on. Named for what every store platform has,
-	// not for what Shopify calls it: Shopify says discounts, Stripe says coupons
-	// and promotion codes, BigCommerce says coupons and promotions.
-	catalog : Object.freeze([
+	// WHAT A WORKFLOW STEP DOES, as a verb like any other. Step handlers used to
+	// live in drawbridge-sync keyed by step type, which meant a vendor's logic sat
+	// in a repo the vendor file could not see — the split this whole exercise
+	// exists to close.
+	//
+	// A `steps` entry points at one of these; the step says when it runs and what
+	// it costs, the hook does the work.
+	contacts : Object.freeze([
+		// Forget a contact at the vendor. Distinct from suppression, which keeps the
+		// record and marks it unsubscribed: this is deletion, for account closure.
+		'remove',
+		// Push one contact into the audience the merchant chose, honouring
+		// suppression rather than omitting an opted-out person — omission lets them
+		// quietly reappear on the next sync.
+		'sync'
+	]),
+
+	commerce : Object.freeze([
+		// Mint a discount code against this merchant's store, mapped to one lead.
+		'code',
+		// Create the buyer at the vendor, so an order can be attributed to them.
+		'customer',
+		// An order arrived at the vendor: attribute it, record it, update totals.
+		'order',
+		// Pull product data across on a vendor update.
+		'product'
+	]),
+
+	// WHAT DRAWBRIDGE ITSELF DOES. These are not a third party's verbs — nobody
+	// connects an account to send email through Drawbridge — but they are steps a
+	// workflow runs, and a step points at a hook. So they live on a PRIVATE
+	// connection: one that contributes steps and never appears in the catalog.
+	//
+	// Without it the base steps stay the exception the shell has to know about,
+	// and "every step is a declaration pointing at a hook" stops being true the
+	// moment somebody looks at the six most common ones.
+	email : Object.freeze([
+		// To a lead. Suppression applies, and the send is billed.
+		'send',
+		// To organization members. Never suppressed — an entrant's opt-out must not
+		// silence an alert to staff — and never billed.
+		'notify',
+		// A batched summary to members.
+		'digest'
+	]),
+
+	sms : Object.freeze([ 'send' ]),
+
+	segment : Object.freeze([ '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.
+	webhook : Object.freeze([ 'send' ]),
+
+	// Vendor data we READ — the things a merchant picks from. Named `resources`
+	// rather than `catalog` because it also holds audiences, and a catalog is a
+	// commerce word for something that is not only commerce. It matches the
+	// pickers that render it, too: InputResource and ListResource.
+	//
+	// The verbs are named for what every vendor has, not for what one calls it:
+	// Shopify says discounts, Stripe says coupons and promotion codes,
+	// BigCommerce says coupons and promotions.
+	//
+	// ONE SHAPE FOR ALL OF THEM — searchable and cursor-paged:
+	//
+	//   ({ connection, cursor, limit, search, settings, token })
+	//     -> { items : [ { id, title, ... } ], pageInfo : { endCursor, hasNextPage } }
+	//
+	// Lifted from what the Shopify product picker already does, rather than
+	// invented: that endpoint takes cursor/limit/search and returns items plus a
+	// pageInfo, and ListResource consumes exactly that. It was a good contract
+	// written once for one vendor; this makes it the contract.
+	//
+	// `title` is not arbitrary — ListResource searches `[ 'title' ]` by default,
+	// so normalising to { id, title } is what lets a picker work with no
+	// per-vendor configuration.
+	//
+	// HOW a vendor searches is its own business, which is the point of a hook.
+	// Shopify pushes the term into its GraphQL query, Klaviyo has a filter
+	// parameter, and Mailchimp's /lists has no name filter at all so its hook
+	// matches against what it fetched. The caller never learns which.
+	resources : Object.freeze([
 		// The named groups a contact can be synced INTO. Klaviyo calls them lists,
 		// Mailchimp calls them audiences; `audiences` is the industry-generic term
 		// and belongs to neither vendor's API. Read at form time, so a merchant
@@ -114,6 +228,78 @@ const HOOKS = Object.freeze({
 
 });
 
+// WHAT A WORKFLOW STEP CAN BE. Closed, and the LABEL LIVES HERE rather than on a
+// vendor, because a step type belongs to the capability and not to whoever
+// implements it: Klaviyo and Mailchimp both do contacts.sync, and a label taken
+// from either would give a merchant two identically-named builder entries — the
+// exact mistake step.shopify.* made before the rename to step.commerce.*
+//
+// KEYED BY THE FULL NAME, not nested, because these strings are STORED on
+// workflow documents and several are three segments deep
+// (commerce.customer.insert). A manifest still nests its `steps` for
+// readability; the path is joined to produce these keys, at whatever depth the
+// vendor wrote it. Renaming any of them is a backfill, not an edit.
+//
+// A manifest's own `key` is the INSTANCE label ("Sync contact to Acme Co"),
+// which is a different sentence for a different place.
+//
+// drawbridge-api's enums.step.type — the $jsonSchema validator on the workflow
+// collection — UNIONS this over its own map rather than replacing it. A stored
+// document carrying a retired type must stay writable, including by the
+// migration that retires it.
+const STEPS = Object.freeze({
+	'commerce.code.issue' : 'Issue discount code',
+	'commerce.customer.insert' : 'Create customer',
+	'commerce.order.record' : 'Record order',
+	'commerce.product.sync' : 'Sync product',
+	// Not commerce at all — connection lifecycle, and they generalise to any
+	// vendor holding a rotating credential.
+	'connection.health.check' : 'Connection health check',
+	'connection.token.exchange' : 'Exchange token',
+	'connection.token.refresh' : 'Refresh token',
+	'contacts.sync' : 'Sync contact',
+	'email.digest' : 'Digest',
+	'email.notify' : 'Notification',
+	'email.send' : 'Send email',
+	'segment.sync' : 'Sync segment',
+	'sms.send' : 'Send SMS',
+	'webhook.send' : 'Send webhook'
+});
+
+// WHAT EACH RETIRED STEP TYPE BECAME.
+//
+// `step.shopify.*` was renamed to `step.commerce.*` because a step type belongs
+// to the CAPABILITY and not to whoever implements it — a second store platform
+// does the same four things, and vendor-namespaced types would have shown a
+// merchant two "Create customer" entries.
+//
+// Stored documents still carry the old names until the backfill runs, so both
+// must keep working. This is the one place that says which is which: the queue
+// resolves a legacy type through it to find the manifest that declares its
+// replacement, and drawbridge-api's enums.step.type keeps every key here in its
+// validator so those documents stay writable — including by the migration that
+// retires them.
+//
+// A type is removed from here a release AFTER its backfill, never with it.
+const RETIRED = Object.freeze({
+	'step.shopify.customer.insert' : 'step.commerce.customer.insert',
+	'step.shopify.discount.update' : 'step.commerce.code.issue',
+	'step.shopify.health.check' : 'step.connection.health.check',
+	'step.shopify.order.record' : 'step.commerce.order.record',
+	'step.shopify.product.sync' : 'step.commerce.product.sync',
+	'step.shopify.token.exchange' : 'step.connection.token.exchange',
+	'step.shopify.token.refresh' : 'step.connection.token.refresh'
+});
+
+// 'step.<name>' — the string stored on a workflow document.
+const STEP_TYPES = Object.freeze( Object.keys( STEPS ).map( ( name ) => 'step.' + name ) );
+
+// The same vocabulary as { 'step.<name>' : label }, the shape enums.step.type
+// is written in.
+const STEP_LABELS = Object.freeze( Object.fromEntries(
+	Object.entries( STEPS ).map( ( [ name, label ] ) => [ 'step.' + name, label ] )
+) );
+
 // Flat 'domain.verb' names, which is how a manifest declares support and how a
 // caller asks for one.
 const HOOK_NAMES = Object.freeze(
@@ -135,6 +321,22 @@ const OUTCOMES = Object.freeze({
 	unsupported : 'unsupported'
 });
 
+// WHAT A CONNECTION'S STATE IS. A connection's `status()` returns one of these
+// and nothing else — the SENTENCE explaining a state belongs in `tasks`, which
+// already exists to carry merchant-facing copy and is already rendered.
+//
+// Mirrors enums.connection.status in drawbridge-api, which is the $jsonSchema
+// validator on the connection collection — a value not in that enum is rejected
+// by the DATABASE with "Document failed validation", the opaque error a missing
+// `feature` field already cost an hour to trace. Declared here because
+// drawbridge-sync cannot import the api, and a copy in each is the two-repo trap
+// this package exists to close.
+//
+// NO `incomplete`. That is an ORGANIZATION status meaning outstanding invoices,
+// and reusing the word for a connection would leave nobody able to say which
+// object a status referred to.
+const STATUSES = Object.freeze([ 'active', 'disconnected', 'error', 'pending' ]);
+
 // HOW A VENDOR IS CONNECTED. Four kinds, because the merchant's experience of
 // each is genuinely different and the dashboard renders from this:
 //
@@ -147,12 +349,17 @@ const OUTCOMES = Object.freeze({
 // merchant never sees a consent screen we sent them to — they start at the
 // vendor's app store — and a dashboard that offers a Connect button for one is
 // lying about the other.
-const AUTH_TYPES = Object.freeze([ 'generated', 'install', 'keys', 'oauth' ]);
+// `none` is the private case: Drawbridge sending its own email authenticates
+// against nothing, and there is no merchant action that could connect it.
+const AUTH_TYPES = Object.freeze([ 'generated', 'install', 'keys', 'none', 'oauth' ]);
 
 // WHAT KIND OF VENDOR THIS IS. Closed, because a card list that works at three
-// connections stops working the day every CMS joins it, and a category nobody
+// connections stops working the day every CMS joins it, and a group nobody
 // spelled right is a filter chip that silently shows nothing.
-const CATEGORIES = Object.freeze([ 'commerce', 'contacts', 'developer', 'messaging' ]);
+//
+// One word for one fact. `category` used to sit beside `group` meaning the same
+// thing, which left nobody able to say which one a page read.
+const GROUPS = Object.freeze([ 'commerce', 'contacts', 'developer', 'messaging' ]);
 
 // WHAT AN OAUTH VENDOR MUST DECLARE, so one implementation serves all of them
 // rather than one module per vendor.
@@ -168,7 +375,11 @@ const CATEGORIES = Object.freeze([ 'commerce', 'contacts', 'developer', 'messagi
 //   params     vendor quirks (Google wants access_type=offline)
 //   pkce       Klaviyo's OAuth 2.1 REQUIRES a code_verifier/code_challenge pair;
 //              most vendors do not. A flag rather than a Klaviyo module.
-const OAUTH_FIELDS = Object.freeze([ 'authorize', 'client', 'redirect', 'token' ]);
+// `client` sits on auth.oauth; the rest are addresses and live under
+// auth.oauth.urls with every other vendor URL, so `revoke` stopped being a
+// literal buried in the disconnect hook.
+const OAUTH_FIELDS = Object.freeze([ 'client' ]);
+const OAUTH_URLS = Object.freeze([ 'authorize', 'redirect', 'token' ]);
 
 // HOW A FIELD IS EDITED. Closed, because the dashboard renders one form for
 // every connection and it can only render what it has a component for. An open
@@ -288,7 +499,11 @@ const accessToken = async ({
 
 	}
 
-	const minted = await refresh({
+	// THE VENDOR'S OWN auth.token, called directly rather than through runHook.
+	// This runs inside hooks — a step hook awaits accessToken before its vendor
+	// call — so going through the outcome wrapper would be re-entrant and would
+	// wrap an error that attempt() already handles.
+	const minted = await manifest.hooks.auth.token({
 		clientId,
 		clientSecret,
 		descriptor : manifest.auth.oauth,
@@ -304,33 +519,601 @@ const accessToken = async ({
 
 };
 
-// Klaviyo, exported from the brand kit and left as authored — the fills are the
+// Drawbridge, exported from the brand kit and left as authored — the fills are the
 // vendor's own mark, not a recolour.
 //
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
 var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="500" height="500" fill="#BAEC5F"/>
+<g clip-path="url(#clip0_2115_2832)">
+<path d="M140.224 127.586L174.803 188.73V311.176L140 372.32L176.084 392.031L216.111 321.753V178.278L176.341 108L140.224 127.586Z" fill="#0D1314"/>
+<path d="M360.001 127.523L323.693 108.282L284.948 178.498V321.596L322.923 391.749L359.393 372.79L326.224 311.52V188.73L360.001 127.523Z" fill="#0D1314"/>
+</g>
+<defs>
+<clipPath id="clip0_2115_2832">
+<rect width="220" height="284" fill="white" transform="translate(140 108)"/>
+</clipPath>
+</defs>
+</svg>`;
+
+// Drawbridge itself — the PRIVATE connection.
+//
+// Nobody connects this. There is no credential, no consent, and no card on the
+// connections page. It exists because a workflow step points at a hook, and the
+// six most common steps — sending an email, alerting a member, syncing a segment
+// — are things Drawbridge does rather than things a vendor does.
+//
+// Before this, those steps were the exception: every other step resolved through
+// a manifest and these resolved through a hardcoded registry in drawbridge-sync.
+// One exception is all it takes for "every step is a declaration pointing at a
+// hook" to stop being a rule somebody can rely on.
+//
+// PRIVATE is a real distinction, not a flag to hide a card. A public connection
+// answers "can this merchant connect it" through `requires` and a plan feature.
+// A private one is always present, in every deployment, for every organization —
+// so it declares neither, and build() knows not to ask.
+var drawbridge = {
+	auth : {
+		type : 'none'
+	},
+	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.'
+		],
+		excerpt : 'The steps Drawbridge runs itself.',
+		guide : [
+			'Nothing to do. These steps are available in every workflow builder.'
+		]
+	},
+	exclusive : false,
+	fields : [],
+	group : 'developer',
+	// EVERY BODY LIVES IN drawbridge-sync. Sending needs the provider clients, the
+	// suppression collection and the queues; segment sync needs the streams. A
+	// published package carrying those makes every consumer carry them, which is
+	// the reason `{}` exists as an answer.
+	hooks : {
+		auth : {
+			// Nothing to connect, revoke, probe or re-scope.
+			connect : false,
+			disconnect : false,
+			probe : false,
+			scopes : false,
+			token : false
+		},
+		commerce : false,
+		contacts : { remove : false, sync : false },
+		email : {
+			digest : {},
+			// To organization members. NEVER suppressed and never billed: an
+			// entrant's opt-out must not silence an alert to staff, and staff mail is
+			// not a metered send.
+			notify : {},
+			// To a lead. Suppression applies and the send is billed.
+			send : {}
+		},
+		inbound : false,
+		lifecycle : false,
+		resources : {
+			audiences : false,
+			prices : false,
+			products : false,
+			promotions : false
+		},
+		segment : { sync : {} },
+		sms : { send : {} },
+		webhook : false
+	},
+	icon: icon$3,
+	// PRIVATE: never in the catalog, always available to the builder.
+	private : true,
+	requires : [],
+	slug : 'drawbridge',
+	// Always on. There is no credential that could go bad and no configuration a
+	// merchant could leave half-finished.
+	status : () => 'active',
+	// DERIVED FROM drawbridge-api/lib/workflows.js, not invented. Every value
+	// below — trigger, billable, settings — is what that catalog and the workflow
+	// route already enforce today, because this replaces them rather than
+	// competing with them.
+	//
+	// NOT HERE, deliberately:
+	//
+	//   step.segment.sync  a SYSTEM step, dispatched by drawbridge-sync rather
+	//                      than offered in the builder. It fans out, so the shell
+	//                      opens its step document and the chunks close it.
+	steps : {
+
+		email : {
+
+			// SCHEDULE-TRIGGERED, not lead-triggered: it is offered under Daily,
+			// Weekly and Monthly. Those triggers had offered no steps at all, so a
+			// scheduled workflow was selectable and inert until this landed.
+			digest : () => ({
+				hook : 'email.digest',
+				key : 'Email — Digest',
+				queue : 'notification',
+				settings : {
+					// The organization OWNER is always a recipient, resolved in sync,
+					// so this is additional recipients rather than the list. It cannot
+					// be required: the members endpoint is owner-gated and the owner is
+					// not a member document, so a solo merchant has nothing to pick and
+					// could never save the step.
+					members : { of : 'string', type : 'array' },
+					message : { required : true, type : 'string' },
+					subject : { required : true, type : 'string' }
+				},
+				triggers : [ 'schedule.day', 'schedule.week', 'schedule.month' ],
+				usage : { actions : 0 }
+			}),
+
+			// To organization MEMBERS. Never suppressed — an entrant's opt-out must
+			// not silence an alert to staff — and not billed.
+			notify : () => ({
+				hook : 'email.notify',
+				key : 'Email — Notification',
+				queue : 'notification',
+				settings : {
+					members : { of : 'string', type : 'array' },
+					message : { required : true, type : 'string' },
+					subject : { required : true, type : 'string' }
+				},
+				triggers : [ 'lead.insert' ],
+				// Zero is a PRICE, and a deliberate one. Declared rather than omitted
+				// so "this is free" and "nobody decided" stay different statements;
+				// completeStep bills only when actions > 0.
+				usage : { actions : 0 }
+			}),
+
+			// To a LEAD. Suppression applies and the send is billed.
+			send : () => ({
+				hook : 'email.send',
+				key : 'Email — Send email',
+				queue : 'notification',
+				settings : {
+					message : { required : true, type : 'string' },
+					subject : { required : true, type : 'string' }
+				},
+				triggers : [ 'lead.insert' ],
+				// ONE SOURCE FOR THE PRICE. lib/pricing.js is the index of every
+				// customer-facing number; the handler read it too, so the same fact
+				// was stated in two places and only one of them was reviewed.
+				usage : { actions : channels.email.actionsPerSend }
+			})
+
+		},
+
+		// WITHDRAWN, which is a third thing from builder and system: declared,
+		// routed and runnable, but never offered.
+		//
+		// It went when the twilio connection did — a connection-gated step with no
+		// connection to gate on could only ever render permanently disabled. Stored
+		// workflows still carry it, so it must keep running, and enums.step.type
+		// keeps it for the same reason.
+		//
+		// NO TRIGGERS is what keeps it out of the builder: the catalog derives from
+		// triggers, so a step with none is unreachable by a merchant without a
+		// second list saying so.
+		//
+		// Platform SMS returns as a base step the way email did. That is this entry
+		// gaining triggers, not a new one.
+		sms : {
+
+			send : () => ({
+				hook : 'sms.send',
+				key : 'Send an SMS',
+				queue : 'notification',
+				settings : {
+					message : { required : true, type : 'string' },
+					subject : { required : true, type : 'string' }
+				},
+				// Priced per SEGMENT and billed from the first, which the send
+				// resolves from the message length. This is the floor.
+				usage : { actions : channels.sms.actionsPerSegment },
+				withdrawn : true
+			})
+
+		},
+
+		segment : {
+
+			// FANS OUT. It evaluates every contact in the organization against every
+			// segment, which is too much for one job — so the hook returns chunks and
+			// the shell defers completion: openStep writes the document with a slot
+			// per chunk, and whichever chunk lands last closes it and resumes the
+			// chain.
+			//
+			// It carries a hook like every other step. An earlier version declared
+			// none, on the theory that fan-out was a second protocol the shell could
+			// not run; it is the same protocol with the ending deferred, and a step
+			// declaring no hook is silently SKIPPED by the runner.
+			sync : () => ({
+				description : 'Recalculates segment membership on a daily schedule.',
+				hook : 'segment.sync',
+				key : 'Segment Sync',
+				queue : 'segment',
+				system : true
+			})
+
+		}
+
+	},
+	tasks : () => [],
+	title : 'Drawbridge'
+};
+
+// HubSpot — PRIVATE, and Drawbridge's own CRM rather than a merchant's.
+//
+// A signup's UTM properties go onto a contact in OUR portal, keyed by the
+// `hubspotId` cached on the `user` document. There is no merchant credential and
+// no card: one Private App token, one portal, ours.
+//
+// PRIVATE RATHER THAN ABSENT, so the last vendor transport outside a manifest
+// comes inside one. Its hooks are called by drawbridge-sync's user stream rather
+// than by a workflow step — which is not unusual: auth.* hooks are called by the
+// OAuth runner and inbound.* by the webhooks route. A hook is a verb, and only
+// some verbs are steps.
+//
+// FLIPPING IT PUBLIC LATER is a real possibility — merchants syncing their own
+// entrants to their own portal is the Klaviyo shape exactly. When that happens it
+// is a SECOND manifest, not this one edited: this writes Drawbridge account
+// holders into our sales pipeline, and a merchant's entrants must never land
+// there. `token` is already a parameter so the two can share this transport
+// without ever sharing a credential.
+
+const HUBSPOT_BASE = 'https://api.hubapi.com';
+
+// Best-effort: with no Private App token configured the whole integration
+// no-ops so a missing secret never crashes sync. Callers wrap these in
+// try/catch and treat a missing id gracefully.
+const hubspotRequest = ({ body, fetcher, method, path, query, token }) => {
+
+	return ( fetcher || request )({
+		body,
+		headers : {
+			'Authorization' : 'Bearer ' + ( token || process.env.HUBSPOT_ACCESS_TOKEN )
+		},
+		method,
+		query,
+		url : HUBSPOT_BASE + path
+	});
+
+};
+
+// Custom contact properties carrying the campaign a signup arrived on
+// (`user.utm`, written by provisionUser in the api's route/oauth.js).
+//
+// CUSTOM BECAUSE HUBSPOT HAS NO EQUIVALENT — verified against the portal's own
+// property list, where nothing is named or labelled utm. See the note on
+// CLICK_PROPERTIES below for what the analytics family can and cannot do.
+//
+// THESE MUST EXIST IN THE PORTAL — Settings -> Properties -> Contacts, single-line
+// text — or HubSpot rejects the whole payload. See the retry in send() below, which
+// is what stops a missing property from costing a new user its contact.
+//
+// NAMED FOR THE PARAMETER, not for us. These are the six names Google's Campaign URL
+// Builder emits, so the property is called exactly what the link that produced it
+// carried — utm_source holds what arrived as ?utm_source=. A drawbridge_ prefix would
+// have made them ours to explain; this way anything that already speaks the standard,
+// including a future import or a tool somebody adds to the portal, maps onto them with
+// nothing to translate.
+//
+// The underscores are the convention's, not a slip: these are external property names
+// matching a url parameter, which is the one place that spelling is correct.
+//
+// `id` matters most: drawbridge-growth stamps utm_id with the campaign slug, so it is
+// what resolves a contact back to one campaign document. The rest describe it.
+const UTM_PROPERTIES = {
+	campaign : 'utm_campaign',
+	content : 'utm_content',
+	id : 'utm_id',
+	medium : 'utm_medium',
+	source : 'utm_source',
+	term : 'utm_term'
+};
+
+// Click ids go into HubSpot's OWN properties, which are writable and already exist in
+// every portal — checked against ours, where modificationMetadata.readOnlyValue is
+// false on all five. A custom property here would have been a worse copy of a field
+// HubSpot's ads tooling already understands, and one more thing somebody has to create
+// by hand.
+//
+// There is no equivalent for the utm tags. Nothing in the contact schema is named or
+// labelled utm; the nearest family is hs_analytics_*, and it cannot hold these:
+// hs_analytics_source is a coarse enumeration (PAID_SEARCH, SOCIAL_MEDIA...) with no
+// room for a campaign id, and the drill-downs that DO carry campaign detail --
+// hs_analytics_source_data_1 and _2 -- are read-only, written only by HubSpot's own
+// tracking script. Hence the custom properties above, and only above.
+const CLICK_PROPERTIES = {
+	fbclid : 'hs_facebook_click_id',
+	gclid : 'hs_google_click_id',
+	liFatId : 'hs_linkedin_click_id',
+	msclkid : 'hs_bing_click_id',
+	ttclid : 'hs_tiktok_click_id'
+};
+
+// Which properties may not exist in the portal, and so are the ones worth dropping on
+// a 400. The native click ids are NOT in this set: they ship with every portal, so a
+// 400 mentioning one is a real error rather than a setup gap, and silently dropping it
+// would hide that.
+//
+// Derived from the map above rather than matched on a `utm_` prefix, so the two cannot
+// disagree — and so a property added here later is not silently made droppable by the
+// shape of its name.
+const DROPPABLE = new Set( Object.values( UTM_PROPERTIES ) );
+
+const isUtmProperty = ( key ) => DROPPABLE.has( key );
+
+// HubSpot contact properties are lowercase (email/firstname/lastname). Only
+// send the keys we actually have so a name-less user doesn't clear fields —
+// the same rule applies to the campaign, which most contacts will not have.
+const toProperties = ({ email, firstName, lastName, utm }) => {
+
+	const properties = {};
+
+	if( email !== undefined ) properties.email = email;
+	if( firstName !== undefined ) properties.firstname = firstName;
+	if( lastName !== undefined ) properties.lastname = lastName;
+
+	if( utm ){
+
+		for( const [ key, property ] of Object.entries( UTM_PROPERTIES ) ){
+
+			if( utm[ key ] ) properties[ property ] = utm[ key ];
+
+		}
+		// Each click id into the property HubSpot already keeps for that platform.
+		// Only one is ever set in practice — whichever platform the click came from —
+		// so the other four simply never appear.
+		for( const [ key, property ] of Object.entries( CLICK_PROPERTIES ) ){
+
+			if( utm.click?.[ key ] ) properties[ property ] = utm.click[ key ];
+
+		}
+	}
+	return properties;
+
+};
+
+// One request, with a retry that drops the campaign properties.
+//
+// HubSpot 400s the ENTIRE request if a single property does not exist in the portal,
+// and stream/user.js swallows the error — so without this fallback a portal missing
+// the custom properties would silently cost every new user its hubspotId, breaking
+// the CRM link for a reason nobody would think to look for. Losing the campaign is
+// acceptable; losing the contact is not.
+//
+// Worth having even with the properties in place: somebody renaming or archiving one
+// in the portal is a change this repo cannot see coming.
+const send = async ({ doc, fetcher, method, path, token }) => {
+
+	const properties = toProperties( doc );
+
+	try {
+
+		return await hubspotRequest({
+			body : { properties },
+			fetcher,
+			method,
+			path,
+			token
+		});
+
+	} catch ( error ) {
+
+		const enriched = Object.keys( properties ).some( isUtmProperty );
+
+		if( error?.status !== 400 || ! enriched ) throw error;
+
+		return await hubspotRequest({
+			body : {
+				properties : Object.fromEntries(
+					Object.entries( properties ).filter( ( [ key ] ) => ! isUtmProperty( key ) )
+				)
+			},
+			fetcher,
+			method,
+			path,
+			token
+		});
+
+	}
+
+};
+
+// Find a contact id by email. Swallows its own errors: a search that fails must
+// not stop the create that would follow it.
+const lookup = async ({ email, fetcher, token }) => {
+
+	if( ! token || ! email ) return;
+
+	try {
+
+		const body = await hubspotRequest({
+			body : {
+				filterGroups : [
+					{
+						filters : [
+							{
+								operator : 'EQ',
+								propertyName : 'email',
+								value : email
+							}
+						]
+					}
+				],
+				limit : 1,
+				properties : [ 'email' ]
+			},
+			fetcher,
+			method : 'POST',
+			path : '/crm/v3/objects/contacts/search',
+			token
+		});
+
+		return body?.results?.[ 0 ]?.id;
+
+	} catch ( error ){
+
+		// Deliberately swallowed.
+
+	}
+
+};
+
+var hubspot = {
+	auth : {
+		// A Private App token from our own portal. Nothing to connect, nothing to
+		// consent to, and no merchant involved.
+		type : 'none'
+	},
+	content : {
+		confirm : 'This connection is part of Drawbridge and cannot be disconnected.',
+		description : [
+			'Drawbridge keeps its own HubSpot portal in step with account signups, so the campaign a customer arrived on is on their contact record.'
+		],
+		excerpt : 'Drawbridge\'s own CRM sync.',
+		guide : [
+			'Nothing to do. This is internal to Drawbridge.'
+		]
+	},
+	exclusive : false,
+	fields : [],
+	group : 'contacts',
+	hooks : {
+		auth : {
+			connect : false,
+			disconnect : false,
+			probe : false,
+			scopes : false,
+			token : false
+		},
+		commerce : false,
+		contacts : {
+
+			// FORGET A CONTACT, by id or by email. Account deletion — the caller had
+			// to search then remove, which is one round trip it should not have to
+			// know about.
+			remove : async ({ email, fetcher, id, token }) => {
+
+				const key = token || process.env.HUBSPOT_ACCESS_TOKEN;
+
+				if( ! key ) return;
+
+				const contact = id || await lookup({ email, fetcher, token : key });
+
+				if( ! contact ) return;
+
+				return hubspotRequest({
+					fetcher,
+					method : 'DELETE',
+					path : '/crm/v3/objects/contacts/' + contact,
+					token : key
+				});
+
+			},
+
+			// Connect an account to its contact by email, creating it if absent, and
+			// return the contact id. Unlike SendGrid, HubSpot renames a contact's
+			// email in place, so an email change is a plain PATCH on the cached id —
+			// no delete-old-then-create-new.
+			//
+			// Prefer the cached hubspotId; fall back to a search; create last.
+			sync : async ({ doc, fetcher, token }) => {
+
+				const key = token || process.env.HUBSPOT_ACCESS_TOKEN;
+
+				// NO TOKEN IS A NO-OP, not an error. A deployment without a portal
+				// configured must not crash the user stream.
+				if( ! key ) return;
+
+				if( doc?.hubspotId ){
+
+					try {
+
+						return ( await send({ doc, fetcher, method : 'PATCH', path : '/crm/v3/objects/contacts/' + doc.hubspotId, token : key }) )?.id;
+
+					} catch ( error ){
+
+						// The cached contact was deleted in HubSpot (404) or is otherwise
+						// unusable — fall through to search and create.
+						if( error?.status !== 404 ) throw error;
+
+					}
+
+				}
+
+				const existing = await lookup({ email : doc?.email, fetcher, token : key });
+
+				return ( await send({
+					doc,
+					fetcher,
+					method : existing ? 'PATCH' : 'POST',
+					path : existing ? '/crm/v3/objects/contacts/' + existing : '/crm/v3/objects/contacts',
+					token : key
+				}) )?.id;
+
+			}
+
+		},
+		email : false,
+		inbound : false,
+		lifecycle : false,
+		resources : {
+			audiences : false,
+			prices : false,
+			products : false,
+			promotions : false
+		},
+		segment : false,
+		sms : false,
+		webhook : false
+	},
+	icon: icon$3,
+	// Borrowed: the Drawbridge mark, because this is ours and never rendered.
+	private : true,
+	// Absent the token the hooks no-op, so a deployment without a portal simply
+	// contributes nothing rather than failing.
+	requires : [ 'HUBSPOT_ACCESS_TOKEN' ],
+	slug : 'hubspot',
+	status : () => 'active',
+	// No workflow steps. The hooks are called by the user stream, not the builder.
+	steps : {},
+	tasks : () => [],
+	title : 'HubSpot'
+};
+
+// Klaviyo, exported from the brand kit and left as authored — the fills are the
+// vendor's own mark, not a recolour.
+//
+// A .js wrapper around otherwise untouched SVG so `node --test` can run against
+// lib/ directly. A bare .svg import would need a bundler loader and force the
+// tests onto dist/, which is a worse trade than one line of wrapper.
+var icon$2 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="white"/>
 <path d="M365.047 327.038H134.954V172.964H365.047L316.856 250.001L365.047 327.038Z" fill="#232121"/>
 </svg>`;
 
-// Klaviyo pins its API by DATE. A request without this header is refused, and
-// one with an old date keeps the response shape that date shipped with — which
-// is the point: bumping it is a deliberate act with a changelog to read, not
-// something that drifts under us.
-const REVISION = '2026-07-15';
-
-const api = async ( path, { fetcher = fetch, token } ) => {
+const api = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
 
 	const response = await fetcher( 'https://a.klaviyo.com/api' + path, {
+		...( payload && { body : JSON.stringify( payload ) }),
 		headers : {
 			// Bearer, not Klaviyo-API-Key — that header is for private keys, and
 			// sending it with an OAuth token fails in a way that reads like a bad
 			// token rather than a bad scheme.
 			authorization : 'Bearer ' + token,
-			revision : REVISION
+			...( payload && { 'content-type' : 'application/json' }),
+			// Klaviyo pins its API by DATE. A request without this header is
+			// refused, and one with an old date keeps the response shape that date
+			// shipped with — which is the point: bumping it is a deliberate act
+			// with a changelog to read, not something that drifts under us.
+			revision : '2026-07-15'
 		},
+		method,
 		signal : AbortSignal.timeout( 15000 )
 	});
 
@@ -343,272 +1126,553 @@ const api = async ( path, { fetcher = fetch, token } ) => {
 
 	}
 
-	return response.json();
+	// 204 on a subscription write — nothing to parse, and asking for json throws.
+	return response.status === 204 ? null : response.json();
 
 };
 
-// Klaviyo — contact and event sync, over OAuth.
+// Klaviyo — contact sync, over OAuth.
+//
+// EVERYTHING ABOUT THIS VENDOR IS IN THIS FILE. Its copy, the fields it stores,
+// how it authenticates, what it can be asked for, and what its workflow step
+// does. Nothing about Klaviyo lives in the api, in drawbridge-sync, or in a
+// form component.
+//
+// TWO MAPS, and they are different things rather than one thing split in half:
+//
+//   hooks   protocol operations. Called synchronously, return data, never
+//           user-facing. Grouped by domain, mirroring the vocabulary.
+//   steps   workflow units. Queued, billable, offered in the builder by
+//           trigger, and their type is stored in documents under a Mongo enum.
+//
+// A HOOK'S VALUE IS ITS ANSWER, which is why no separate `supports` map exists
+// to drift from this one:
 //
-// THE FIRST VENDOR ADDED AS A MANIFEST AND NOTHING ELSE. No form component, no
-// connect route, no consent builder, no token exchange: the shared runner in
-// oauth.js reads the descriptor below and does all of it. That is the test of
-// whether this exercise worked, and the things it forced out are the interesting
-// part — clientAuth and pkce both exist because Klaviyo needs them and Google
-// does not.
+//   false      declined — a decision recorded, not silence
+//   function   supported, and the body is here
+//   {}         supported, implemented in the repo that has the dependencies
 var klaviyo = {
 	// OAuth 2.1, and PKCE is REQUIRED rather than recommended: Klaviyo refuses an
 	// exchange without a code_verifier matching the challenge the consent
 	// carried. Most vendors treat it as optional hardening; this one does not,
 	// which is why it is a descriptor flag and not a global.
 	//
-	// clientAuth is the other thing Klaviyo does differently. The token endpoint
-	// wants HTTP Basic — base64( client_id : client_secret ) in an Authorization
-	// header — and rejects the same pair sent as form fields, which is how every
-	// Google product wants it.
+	// HTTP Basic on the token endpoint is the other thing Klaviyo does
+	// differently, and it says so in hooks.auth.token rather than as a flag here.
 	auth : {
 		oauth : {
-			// TWO DIFFERENT HOSTS, and swapping them fails in opposite directions.
-			//
-			// authorize is a page a HUMAN loads, and it lives on www. Pointing it at
-			// a.klaviyo.com -- their API host -- sends the merchant somewhere that
-			// never renders a consent screen, so the journey stalls with no error
-			// anybody can see.
-			//
-			// token is a server call and must stay on a.klaviyo.com: Klaviyo began
-			// blocking OAuth token traffic through www on 2025-03-31, so the mirror
-			// image of this mistake breaks the exchange instead of the consent.
-			authorize : 'https://www.klaviyo.com/oauth/authorize',
 			// NAMES the env vars holding OUR application's client. One identity,
 			// every merchant — the token is the merchant's and arrives from their
 			// own consent, which is what stops one organization reading another's
 			// data.
+			//
 			client : {
 				id : 'KLAVIYO_OAUTH_CLIENT_ID',
 				secret : 'KLAVIYO_OAUTH_CLIENT_SECRET'
 			},
-			clientAuth : 'basic',
-			pkce : true,
-			// DECLARED, never derived from the slug. It is registered in Klaviyo's
-			// app settings and they refuse anything that does not byte-match, so
-			// it is a fact about someone else's records rather than a string this
-			// code computes. Deriving one from a provider key produced
-			// redirect_uri_mismatch on a connection nobody had touched.
 			// Klaviyo drops a refresh token after 90 days of NON-USE. The vendor
 			// never mentions this at runtime — you discover it when a refresh fails
 			// on a connection nobody touched — so it is declared, and it is why
 			// auth.probe has to run on a schedule rather than only before a call.
-			idleExpiry : 90 * 24 * 60 * 60,
-			redirect : '/api/connection/klaviyo/callback',
+			//
+			// Token lifetime is NOT declared: the vendor states it on every
+			// exchange, and a copy here would be a second answer that goes stale.
+			expiry : 90 * 24 * 60 * 60,
+			pkce : true,
 			// 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',
-			token : 'https://a.klaviyo.com/oauth/token'
+			// 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.
+			urls : {
+				// TWO DIFFERENT HOSTS, and swapping them fails in opposite ways.
+				//
+				// authorize is a page a HUMAN loads, and it lives on www. Pointing it
+				// at a.klaviyo.com — their API host — sends the merchant somewhere
+				// that never renders a consent screen, so the journey stalls with no
+				// error anybody can see.
+				//
+				// token and revoke are server calls and must stay on a.klaviyo.com:
+				// Klaviyo began blocking OAuth token traffic through www on
+				// 2025-03-31, so the mirror image of this mistake breaks the exchange
+				// instead of the consent.
+				authorize : 'https://www.klaviyo.com/oauth/authorize',
+				// WHERE THE MERCHANT LANDS — the dashboard, not drawbridge-api. The
+				// `/api/` segment is Next's route-handler convention, which reads as
+				// the api service to everyone who sees it; it is not, and the route
+				// has never moved. build() pins it against the one callback route
+				// that exists, because declared-but-wrong fails AFTER consent — a
+				// 404 for someone who has already granted access.
+				//
+				// Registered in Klaviyo's own app settings, and they refuse anything
+				// that does not byte-match, so it is a fact about someone else's
+				// records rather than a string this code computes.
+				redirect : '/api/connection/klaviyo/callback',
+				revoke : 'https://a.klaviyo.com/oauth/revoke',
+				token : 'https://a.klaviyo.com/oauth/token'
+			}
 		},
 		type : 'oauth'
 	},
-	category : 'contacts',
-	confirm : 'Disconnecting revokes Drawbridge\'s access to your Klaviyo account. Your profiles and lists stay in both Klaviyo and Drawbridge — neither is deleted.',
-	connect : {
+	// EVERYTHING A MERCHANT READS. Grouped by who it is for rather than by what
+	// kind of sentence it is, so the question on the next vendor is "does a person
+	// read this", which nobody gets wrong, instead of "is this marketing", which
+	// someone will.
+	//
+	// `errors` is in here rather than at the top level, and that is not a
+	// preference. The connection DOCUMENT carries its own `errors` array of
+	// scope-drift entries, and the document is spread OVER the resolved manifest
+	// downstream — so a top-level `errors` here would be silently replaced by that
+	// array and this copy would never render. `fields`/`settings` already carry a
+	// comment about the same collision.
+	content : {
+
+		// 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 — 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.',
+			'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.'
+		],
+
+		// KEYED BY WHAT FAILED, not nested inside it. Errors are the thing most
+		// likely to grow — resources.* has already earned somewhere to put "we
+		// could not load your lists" — so a new area adds a key here rather than a
+		// second errors object somewhere else.
+		//
+		// `connect` no longer exists as a container above: its only other member
+		// was `redirect`, which moved to auth.oauth.urls with the rest of the
+		// vendor's addresses.
 		errors : {
-			denied : 'The Klaviyo authorization was declined, so nothing was connected.',
-			invalid : 'We couldn\'t complete the Klaviyo connection. Try connecting again.'
-		}
+			connect : {
+				denied : 'The Klaviyo authorization was declined, so nothing was connected.',
+				invalid : 'We couldn\'t complete the Klaviyo connection. Try connecting again.'
+			}
+		},
+
+		excerpt : 'Sync the contacts your campaigns collect into a Klaviyo list.',
+
+		// HOW TO CONNECT, in the merchant's words. Was `setup`, which nothing
+		// rendered — four useful instructions no component displayed.
+		guide : [
+			'Press Connect. Drawbridge sends you to Klaviyo to approve access.',
+			'Sign in to Klaviyo if you are not already, and choose the account to connect.',
+			'Approve the permissions Klaviyo lists. You are returned here and the connection shows Active.',
+			'You can revoke access at any time from Klaviyo, under Integrations.'
+		]
+
 	},
-	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.',
-		'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.'
-	],
-	excerpt : 'Sync the contacts your campaigns collect into a Klaviyo list.',
+	// CAN A MERCHANT KEEP TWO OF THESE AT ONCE?
+	//
+	// Required, and false is a decision rather than a default. Shopify is
+	// exclusive because a store maps to exactly one organization. Contact syncs
+	// are destinations — someone can reasonably keep Klaviyo and Mailchimp both
+	// current — so the exclusivity that once applied when these were SENDERS is
+	// deliberately gone. That was removed once already; declaring it out loud is
+	// what stops it coming back by inference.
+	exclusive : false,
 	feature : 'organization:connection:klaviyo',
-	// Nothing typed. The consent returns the grant, and the account it belongs to
-	// is read back from Klaviyo rather than asked for.
 	fields : [
 		{
 			key : 'account',
 			label : 'Klaviyo account'
 		},
 		{
+			// The choices come from the merchant's own account, so the field names
+			// the capability and the client composes the url.
+			hook : 'resources.audiences',
 			input : 'select',
 			key : 'list',
 			label : 'Klaviyo list',
 			message : 'Contacts your campaigns collect are synced into this list.',
 			required : true,
-			// The choices come from the merchant's own account, not from here — see
-			// catalog.audiences below. Static options would mean asking somebody to
-			// paste a list id copied out of another browser tab.
-			source : 'catalog.audiences'
+			// Klaviyo's list endpoint carries no name filter, so the hook can only
+			// match what it already fetched. A search box that searches one page is
+			// worse than none, so the picker does not offer one.
+			search : false
 		}
 	],
-	// The three auth hooks, all pure HTTP against Klaviyo — which is why they
-	// live here rather than in sync. A vendor's own protocol belongs beside the
-	// vendor.
+	// WHAT KIND OF THING THIS IS. One field, not two — `category` said the same
+	// thing and was read by nothing, while `group` was quietly doing double duty
+	// as the mutual-exclusion key. The exclusion moved to `exclusive` above, so
+	// this is purely how a connection is grouped and labelled.
+	group : 'contacts',
+
+	// Nothing typed at connect. The consent returns the grant, and the account it
+	// belongs to is read back from Klaviyo rather than asked for.
 	hooks : {
-		// Turn a fresh grant into settings worth showing. Without this the card
-		// renders an empty "Klaviyo account" field, because the merchant is never
-		// asked which account they connected — the consent already decided it and
-		// asking again would be a question we can answer ourselves.
-		'auth.connect' : async ({ fetcher, tokens }) => {
 
-			const body = await api( '/accounts', { fetcher, token : tokens.accessToken });
+		auth : {
 
-			const account = body?.data?.[ 0 ];
+			// Turn a fresh grant into settings worth showing. Without this the card
+			// renders an empty "Klaviyo account" field, because the merchant is
+			// never asked which account they connected — the consent already
+			// decided it, and asking again would be a question we can answer.
+			connect : async ({ fetcher, tokens }) => {
 
-			return {
-				account : account?.attributes?.contact_information?.organization_name || account?.id || null,
-				accountId : account?.id || null
-			};
+				const body = await api( '/accounts', { fetcher, token : tokens.accessToken });
 
-		},
-		// Revoke at KLAVIYO, not just locally. Forgetting our copy leaves the
-		// grant live in the merchant's account, so a disconnect that looks
-		// complete here still shows Drawbridge with access over there.
-		//
-		// Basic auth with our client, exactly like the token exchange — the token
-		// being revoked is the subject, not the credential.
-		// The lists a merchant can sync into, for the picker on their connection.
-		//
-		// PAGINATED DELIBERATELY. Klaviyo caps page[size] at 10 and defaults to it,
-		// so a single call quietly returns the first ten lists and an account with
-		// more would show a picker missing the one they wanted — with nothing to
-		// indicate anything was cut. Follows links.next, bounded so a runaway
-		// cursor cannot spin forever.
-		'catalog.audiences' : async ({ fetcher, token }) => {
+				const account = body?.data?.[ 0 ];
 
-			const audiences = [];
+				return {
+					account : account?.attributes?.contact_information?.organization_name || account?.id || null,
+					accountId : account?.id || null
+				};
 
-			let path = '/lists?page%5Bsize%5D=10';
-			let pages = 0;
+			},
 
-			while( path && pages < 20 ){
+			// Revoke at KLAVIYO, not just locally. Forgetting our copy leaves the
+			// grant live in the merchant's account, so a disconnect that looks
+			// complete here still shows Drawbridge with access over there.
+			//
+			// Basic auth with our client, exactly like the token exchange — the
+			// token being revoked is the subject, not the credential.
+			disconnect : async ({ clientId, clientSecret, fetcher = fetch, manifest, settings }) => {
+
+				const token = settings?.refreshToken || settings?.accessToken;
+
+				if( ! token ) return { revoked : false };
+
+				const response = await fetcher( manifest.auth.oauth.urls.revoke, {
+					body : new URLSearchParams({
+						token,
+						token_type_hint : settings?.refreshToken ? 'refresh_token' : 'access_token'
+					}),
+					headers : {
+						authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ),
+						'content-type' : 'application/x-www-form-urlencoded'
+					},
+					method : 'POST',
+					signal : AbortSignal.timeout( 15000 )
+				});
 
-				const body = await api( path, { fetcher, token });
+				// A grant already revoked at the vendor answers non-2xx, and that is
+				// the outcome we wanted — surfacing it as a failure would leave a
+				// merchant unable to finish disconnecting.
+				return { revoked : response.ok };
 
-				for( const list of ( body?.data || [] ) ){
+			},
 
-					audiences.push({ label : list?.attributes?.name || list.id, value : list.id });
+			// THE MINT IS THE PROBE. Asking "is this token still good" by
+			// inspecting what we stored answers the wrong question — a grant
+			// revoked inside Klaviyo still looks perfect in our database. Spending
+			// the refresh token is the only thing that asks Klaviyo.
+			//
+			// It also keeps the grant warm against the 90-day idle window above.
+			probe : async ({ clientId, clientSecret, fetcher, manifest, settings }) => {
+
+				const token = await accessToken({
+					clientId,
+					clientSecret,
+					fetcher,
+					// Mint even if the stored token still looks good — a probe that
+					// short-circuits never reaches Klaviyo and reports healthy on a
+					// grant revoked an hour ago.
+					force : true,
+					manifest,
+					settings
+				});
+
+				return { ok : Boolean( token ) };
 
-				}
+			},
 
-				const next = body?.links?.next;
+			// Klaviyo scopes are fixed at app level and re-consented, not drifted.
+			scopes : false,
 
-				// Klaviyo returns an absolute url; the shared caller prefixes its own
-				// base, so only the part after /api travels on.
-				path = next ? String( next ).replace( /^https:\/\/a\.klaviyo\.com\/api/, '' ) : null;
+			// KLAVIYO REQUIRES HTTP BASIC on the token endpoint and rejects the same
+			// client_id/client_secret pair as body fields. Everything else about the
+			// request is standard, so this is the shared implementation told the one
+			// thing that differs — in Klaviyo's own file, beside the rest of what
+			// makes Klaviyo unusual, rather than as a flag a caller has to know to
+			// read.
+			token : ( args ) => authToken({ ...args, basic : true })
 
-				pages = pages + 1;
+		},
 
-			}
 
-			return audiences;
+		// No commerce here. Klaviyo tracks orders, but Drawbridge's order data comes
+		// from the store that took the money — a second source for the same event
+		// is two answers to "did this person buy", and the one we can bill from is
+		// the store's.
+		commerce : false,
+
+		// The verb the contacts.sync step points at. It does the work — including
+		// writing the profile id back onto the lead — and returns what happened.
+		contacts : {
+
+			// Not yet. Suppression syncs an opt-out as unsubscribed, which is a
+			// different thing from deleting the profile.
+			remove : false,
+
+			sync : async ({ contact, fetcher, lead, settings, suppressed, token }) => {
+
+				const list = settings?.list;
+
+				// incomplete() already stops a connection reaching Active without a
+				// list; this is the belt to that braces. A workflow saved before the
+				// list was chosen must not silently write into nothing.
+				if( ! list ) return { message : 'No Klaviyo list is chosen for this connection.', skipped : true };
+
+				const email = lead?.canonical?.email?.value || lead?.email;
+
+				if( ! email ) return { message : 'That lead has no email address to sync.', skipped : true };
+
+				// A Klaviyo profile is keyed on an email, so IDENTITY comes from the
+				// lead. RANKING comes from the contact behind it, because only a
+				// contact knows money: order attribution is person-level and merges
+				// across every address a human used, so revenue and orders cannot
+				// exist on a single-address record.
+				const totals = contact?.totals || {};
+
+				const profile = await api( '/profiles/', {
+					fetcher,
+					method : 'POST',
+					payload : {
+						data : {
+							attributes : {
+								email,
+								...( lead?.name && { first_name : String( lead.name ).trim().split( /\s+/ )[ 0 ] }),
+								properties : {
+									drawbridge_campaigns : ( contact?.campaigns || [] ).length,
+									drawbridge_draws : totals.draws || 0,
+									drawbridge_entries : totals.entries || 0,
+									drawbridge_orders : totals.orders || 0,
+									// Campaign-attributed, NOT lifetime. A merchant running
+									// Shopify already has lifetime revenue in Klaviyo through
+									// Klaviyo's own integration; what only we can say is how
+									// much a campaign drove. Named so the two cannot be
+									// mistaken for one another in a segment builder.
+									drawbridge_revenue : totals.gross || 0
+								}
+							},
+							type : 'profile'
+						}
+					},
+					token
+				});
+
+				const profileId = profile?.data?.id;
+
+				if( ! profileId ) return { message : 'Klaviyo returned no profile id.', skipped : true };
+
+				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
+				//
+				// Omitting them means Klaviyo never learns they said no, so the
+				// merchant can import them from somewhere else and start mailing them
+				// again. Pushing them as unsubscribed makes the suppression travel
+				// with the person, which is the reason this connection is allowed to
+				// send anything at all.
+				//
+				// `suppressed` arrives as an argument because canSend() is sync's —
+				// a manifest cannot reach it, and this rule is too important to infer.
+				await api( '/profile-subscription-bulk-create-jobs/', {
+					fetcher,
+					method : 'POST',
+					payload : {
+						data : {
+							attributes : {
+								profiles : {
+									data : [ {
+										attributes : {
+											email,
+											subscriptions : {
+												email : { marketing : { consent : suppressed ? 'UNSUBSCRIBED' : 'SUBSCRIBED' } }
+											}
+										},
+										type : 'profile'
+									} ]
+								}
+							},
+							relationships : { list : { data : { id : list, type : 'list' } } },
+							type : 'profile-subscription-bulk-create-job'
+						}
+					},
+					token
+				});
+
+				return {
+					// Merged into `context` for later steps in this run.
+					context : { klaviyoProfileId : profileId },
+					message : suppressed
+						? 'Synced to Klaviyo as unsubscribed — this contact has opted out.'
+						: 'Synced to the Klaviyo list.',
+					// Recorded on the run for support to read back, not a write
+					// instruction — the hook has already written what it needed to.
+					response : { klaviyoProfileId : profileId }
+				};
+
+			}
 
 		},
-		'auth.disconnect' : async ({ clientId, clientSecret, fetcher = fetch, settings }) => {
 
-			const token = settings?.refreshToken || settings?.accessToken;
+		// 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.
+		email : false,
+		segment : false,
+		sms : false,
+		inbound : false,
+
+		// Nothing to set up or tear down at the vendor: the grant is the whole
+		// integration, and revoking it is auth.disconnect's job.
+		lifecycle : false,
+
+		resources : {
+
+			// The lists a merchant can sync into, for the picker on their
+			// connection.
+			//
+			// PAGINATED DELIBERATELY. Klaviyo caps page[size] at 10 and defaults to
+			// it, so one call quietly returns the first ten lists and an account
+			// with more shows a picker missing the one they wanted, with nothing to
+			// indicate anything was cut.
+			audiences : async ({ cursor, fetcher, limit = 100, search, token }) => {
 
-			if( ! token ) return { revoked : false };
+				// `limit` is what the CALLER wants back rather than what one request
+				// can carry — the loop keeps pulling until it has that many or the
+				// vendor runs out, and stops as soon as it does.
+				const audiences = [];
 
-			const response = await fetcher( 'https://a.klaviyo.com/oauth/revoke', {
-				body : new URLSearchParams({
-					token,
-					token_type_hint : settings?.refreshToken ? 'refresh_token' : 'access_token'
-				}),
-				headers : {
-					authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ),
-					'content-type' : 'application/x-www-form-urlencoded'
-				},
-				method : 'POST',
-				signal : AbortSignal.timeout( 15000 )
-			});
+				let next = cursor
+					? '/lists?page%5Bsize%5D=10&page%5Bcursor%5D=' + encodeURIComponent( cursor )
+					: '/lists?page%5Bsize%5D=10';
+
+				let pages = 0;
+
+				while( next && audiences.length < limit && pages < 20 ){
+
+					const body = await api( next, { fetcher, token });
+
+					for( const list of ( body?.data || [] ) ){
+
+						audiences.push({ id : list.id, title : list?.attributes?.name || list.id });
+
+					}
+
+					const link = body?.links?.next;
 
-			// A grant already revoked at the vendor answers non-2xx, and that is
-			// the outcome we wanted — surfacing it as a failure would leave a
-			// merchant unable to finish disconnecting.
-			return { revoked : response.ok };
+					// Klaviyo returns an absolute url; only the part after /api travels
+					// on, because `api` prefixes its own base.
+					next = link ? String( link ).replace( /^https:\/\/a\.klaviyo\.com\/api/, '' ) : null;
+
+					pages = pages + 1;
+
+				}
+
+				// Klaviyo's list endpoint has no name filter, so a search term is
+				// applied to what came back. Honest about its own limits: with more
+				// lists than `limit`, a term matching only later ones finds nothing.
+				const term = String( search?.value || '' ).trim().toLowerCase();
+
+				return {
+					items : term
+						? audiences.filter( ( entry ) => entry.title.toLowerCase().includes( term ) )
+						: audiences,
+					pageInfo : {
+						endCursor : next,
+						hasNextPage : Boolean( next )
+					}
+				};
+
+			},
+
+			// Klaviyo sells no products and mints no discount codes.
+			prices : false,
+			products : false,
+			promotions : false
 
 		},
-		// THE MINT IS THE PROBE. Asking "is this token still good" by inspecting
-		// what we stored answers the wrong question — a grant revoked inside
-		// Klaviyo still looks perfect in our database. Spending the refresh token
-		// is the only thing that asks Klaviyo.
-		//
-		// It also keeps the grant warm: Klaviyo expires a refresh token after 90
-		// days of NON-USE, so a connection nobody touches dies silently without
-		// this running.
-		'auth.probe' : async ({ clientId, clientSecret, fetcher, manifest, settings }) => {
-
-			const token = await accessToken({
-				clientId,
-				clientSecret,
-				fetcher,
-				// Mint even if the stored token still looks good — a probe that
-				// short-circuits never reaches Klaviyo and reports healthy on a
-				// grant revoked an hour ago.
-				force : true,
-				manifest,
-				settings
-			});
-
-			return { ok : Boolean( token ) };
 
-		}
+		// Drawbridge posts to a merchant's own endpoint, never through a vendor.
+		webhook : false
+
 	},
-	icon: icon$3,
-	// A grant with no list chosen is authenticated and useless. The list cannot
-	// be part of the consent flow — enumerating lists needs the token the consent
-	// returns — so it is always a second step, and the card must say so rather
-	// than showing Active over nothing.
-	incomplete : ( data ) => ( data?.settings?.list
-		? null
-		: 'Choose which Klaviyo list your contacts should sync into.'
-	),
-	label : 'klaviyo',
+	icon: icon$2,
 	requires : [
 		'KLAVIYO_OAUTH_CLIENT_ID',
 		'KLAVIYO_OAUTH_CLIENT_SECRET'
 	],
-	setup : [
-		'Press Connect. Drawbridge sends you to Klaviyo to approve access.',
-		'Sign in to Klaviyo if you are not already, and choose the account to connect.',
-		'Approve the permissions Klaviyo lists. You are returned here and the connection shows Active.',
-		'You can revoke access at any time from Klaviyo, under Integrations.'
-	],
 	slug : 'klaviyo',
-	// No steps yet. The sync itself is unbuilt, and a step offered in the builder
-	// that nothing runs is worse than no step at all — the merchant configures it
-	// and waits for something that never happens.
-	steps : {},
-	supports : {
-		'auth.connect' : true,
-		'auth.disconnect' : true,
-		// The refresh mint IS the probe: a revoked or rotated grant fails there in
-		// Klaviyo's own words rather than as an empty sync three steps later.
-		'auth.probe' : true,
-		// Klaviyo scopes are fixed at app level and re-consented, not drifted.
-		'auth.scopes' : false,
-		'catalog.audiences' : true,
-		'catalog.prices' : false,
-		'catalog.products' : false,
-		'catalog.promotions' : false,
-		'inbound.event' : false,
-		'inbound.process' : false,
-		'inbound.receive' : false,
-		'inbound.verify' : false,
-		'lifecycle.cleanup' : false,
-		'lifecycle.register' : false,
-		'lifecycle.rehydrate' : false
-	},
-	tasks : () => [
-		// Mailchimp carries the same warning, deliberately worded the same way. A
-		// merchant who connects either one and is told nothing reasonably assumes
-		// contacts are flowing, and finds out weeks later that they are not.
-		{
-			message : 'Contact syncing to Klaviyo lists has not shipped yet. Connecting stores your authorization so it is ready, but nothing is being sent to Klaviyo right now.',
-			title : 'List sync not available yet',
-			type : 'warning'
+	// 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.
+	//
+	// A grant with no list chosen is authenticated and useless. The list cannot be
+	// part of the consent flow — enumerating lists needs the token the consent
+	// returns — so it is always a second step, and the card must say Pending
+	// rather than Active over nothing.
+	//
+	// Otherwise the credential's own verdict stands. A manifest can only ever
+	// DOWNGRADE: it can see the settings, and it cannot see whether the grant was
+	// revoked at Klaviyo an hour ago.
+	//
+	// Computed at read time rather than written, for the same reason
+	// shopifyMissingScopes is: it becomes true the moment a merchant clears the
+	// list, without waiting for something to notice and write it down.
+	status : ( data ) => ( data?.settings?.list ? data.status : 'pending' ),
+
+	steps : {
+
+		contacts : {
+
+			// A DECLARATION, not the work. It names the hook that does the work, and
+			// says where that hook's values belong. Nested like the hooks, and the
+			// nesting IS the name: this is `step.contacts.sync`, which is what a
+			// workflow document stores.
+			//
+			// A function, so it can depend on what this deployment or this
+			// merchant's connection knows — a static object would have to be true
+			// for every deployment at publish time.
+			sync : ({ data }) => ({
+
+				hook : 'contacts.sync',
+
+				// The account the merchant actually connected, read back by
+				// auth.connect. The builder reads "Sync contact to Acme Co" rather
+				// than a label that could be any of their Klaviyo accounts.
+				key : 'Sync contact to ' + ( data?.settings?.account || 'Klaviyo' ),
+
+				queue : 'connection',
+
+				// Nothing for a merchant to configure on the step itself — the list
+				// is chosen once on the connection. Declared empty rather than
+				// omitted, so "this step takes no settings" and "nobody thought about
+				// settings" are different statements.
+				settings : {},
+
+				// BOTH triggers. lead.insert alone only ever fires for someone with
+				// no history yet — a brand-new entrant has no orders and no revenue,
+				// so a profile written then carries an email and nothing else.
+				// Crossing into a segment is the moment the ranking data exists.
+				triggers : [ 'lead.insert', 'segment.contact.add' ],
+
+				// One source for cost: what the builder discloses before a merchant
+				// adds this step, and what is charged when it runs.
+				usage : { actions : 1 }
+
+			})
+
 		}
-	],
+
+	},
+	// WHY, in the merchant's words, and what to do about it.
+	tasks : ( data ) => ( 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'
 };
 
@@ -618,7 +1682,7 @@ var klaviyo = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$2 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon$1 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#FFE01B"/>
 <path d="M310.633 243.561C312.49 243.336 314.249 243.308 315.882 243.561C316.81 241.394 316.979 237.665 316.149 233.598C314.882 227.561 313.18 223.917 309.662 224.508C306.13 225.071 305.989 229.433 307.269 235.47C307.973 238.847 309.24 241.746 310.633 243.561ZM280.392 248.332C282.925 249.429 284.473 250.147 285.05 249.542C285.458 249.148 285.345 248.36 284.74 247.375C283.112 245.042 280.844 243.229 278.211 242.154C275.397 240.982 272.328 240.556 269.301 240.916C266.274 241.275 263.391 242.41 260.93 244.209C259.256 245.447 257.666 247.15 257.863 248.191C257.961 248.515 258.186 248.782 258.777 248.895C260.17 249.049 265.025 246.587 270.64 246.249C274.608 245.968 277.859 247.206 280.392 248.332ZM275.312 251.216C272.047 251.737 270.232 252.807 269.078 253.848C268.079 254.72 267.488 255.649 267.488 256.339L267.741 256.93L268.262 257.127C269.008 257.127 270.668 256.479 270.668 256.479C275.228 254.861 278.253 255.044 281.25 255.382C282.897 255.579 283.671 255.663 284.037 255.1C284.135 254.931 284.29 254.608 283.938 254.059C283.15 252.778 279.843 250.682 275.312 251.216ZM300.416 261.855C302.654 262.953 305.102 262.502 305.904 260.884C306.735 259.266 305.567 257.056 303.329 255.973C301.106 254.861 298.643 255.283 297.841 256.902C297.039 258.52 298.207 260.757 300.416 261.855ZM314.742 249.317C312.94 249.289 311.449 251.259 311.393 253.764C311.35 256.254 312.8 258.281 314.615 258.295C316.43 258.323 317.922 256.339 317.964 253.862C318.006 251.385 316.571 249.359 314.742 249.317ZM193.103 294.108C192.653 293.545 191.907 293.7 191.189 293.897C190.683 293.995 190.12 294.136 189.515 294.122C188.909 294.134 188.308 293.998 187.767 293.726C187.225 293.454 186.757 293.054 186.405 292.56C185.575 291.294 185.617 289.394 186.546 287.241L186.968 286.27C188.431 283.019 190.838 277.559 188.122 272.367C187.234 270.534 185.908 268.948 184.261 267.75C182.614 266.553 180.697 265.78 178.679 265.5C176.772 265.256 174.835 265.469 173.026 266.123C171.218 266.776 169.591 267.85 168.28 269.257C164.284 273.661 163.679 279.684 164.439 281.823C164.734 282.611 165.184 282.822 165.494 282.864C166.169 282.963 167.169 282.456 167.802 280.754L167.999 280.219C168.28 279.318 168.801 277.63 169.659 276.307C170.717 274.689 172.375 273.558 174.267 273.162C176.159 272.766 178.131 273.138 179.749 274.196C182.563 276.039 183.619 279.473 182.423 282.752C181.803 284.455 180.804 287.691 181.015 290.351C181.466 295.74 184.815 297.907 187.77 298.175C190.669 298.273 192.695 296.655 193.216 295.459C193.511 294.713 193.258 294.277 193.103 294.108Z" fill="#231E15"/>
 <path d="M360.476 284.243C360.35 283.835 359.618 281.204 358.647 278.052L356.621 272.648C360.575 266.696 360.645 261.405 360.124 258.393C359.531 254.519 357.693 250.944 354.89 248.205C351.766 244.94 345.363 241.563 336.385 239.044L331.671 237.736C331.643 237.524 331.418 226.619 331.235 221.933C331.08 218.555 330.798 213.264 329.152 208.058C327.182 200.993 323.791 194.858 319.527 190.876C331.277 178.717 338.594 165.307 338.58 153.81C338.538 131.703 311.379 124.976 277.902 138.851L270.824 141.863C270.795 141.835 258.004 129.283 257.821 129.128C219.63 95.8334 100.327 228.476 138.49 260.687L146.835 267.737C144.581 273.775 143.781 280.259 144.499 286.664C145.414 295.543 149.973 304.029 157.375 310.6C164.411 316.82 173.684 320.788 182.648 320.774C197.494 354.998 231.408 375.965 271.175 377.161C313.842 378.427 349.641 358.403 364.67 322.435C365.641 319.916 369.806 308.546 369.806 298.513C369.792 288.409 364.093 284.229 360.476 284.243ZM185.913 311.149C184.613 311.381 183.293 311.48 181.973 311.445C169.083 311.079 155.166 299.483 153.787 285.735C152.253 270.537 160.02 258.829 173.783 256.071C175.415 255.72 177.414 255.537 179.552 255.635C187.264 256.085 198.606 261.996 201.209 278.784C203.517 293.63 199.858 308.785 185.913 311.149ZM171.545 246.953C163.179 248.499 155.744 253.244 150.817 260.18C148.045 257.873 142.909 253.426 142.008 251.681C134.635 237.693 150.043 210.478 160.823 195.111C187.405 157.145 229.086 128.424 248.393 133.603C251.517 134.503 261.902 146.563 261.902 146.563C261.902 146.563 242.623 157.244 224.724 172.16C200.646 190.735 182.423 217.697 171.545 246.953ZM306.792 305.464C306.937 305.403 307.057 305.295 307.134 305.157C307.211 305.019 307.239 304.86 307.214 304.704C307.205 304.61 307.178 304.519 307.133 304.436C307.088 304.353 307.027 304.28 306.954 304.221C306.88 304.162 306.796 304.118 306.705 304.092C306.614 304.066 306.519 304.059 306.426 304.071C306.426 304.071 286.246 307.054 267.179 300.089C269.247 293.348 274.792 295.754 283.137 296.444C296.108 297.209 309.116 295.802 321.623 292.279C330.25 289.788 341.592 284.905 350.401 277.953C353.384 284.497 354.425 291.674 354.425 291.674C354.425 291.674 356.719 291.265 358.647 292.447C360.476 293.573 361.799 295.895 360.898 301.89C359.027 313.119 354.271 322.224 346.235 330.611C341.236 336.036 335.277 340.492 328.659 343.754C324.983 345.691 321.151 347.32 317.205 348.623C286.964 358.487 256.006 347.638 246.029 324.321C245.224 322.535 244.556 320.691 244.03 318.804C239.781 303.438 243.383 285.032 254.655 273.408C255.372 272.676 256.09 271.804 256.09 270.706C256.09 269.806 255.499 268.835 255.007 268.131C251.066 262.418 237.374 252.666 240.132 233.795C242.088 220.23 253.951 210.689 265.012 211.252L267.826 211.421C272.611 211.702 276.79 212.307 280.73 212.49C287.344 212.758 293.268 211.801 300.304 205.947C302.683 203.949 304.582 202.246 307.791 201.711C308.128 201.627 308.973 201.359 310.647 201.416C312.365 201.485 314.032 202.015 315.474 202.949C321.103 206.693 321.905 215.783 322.214 222.439C322.383 226.225 322.848 235.414 322.988 238.031C323.354 244.054 324.944 244.912 328.125 245.954C329.94 246.573 331.615 246.995 334.077 247.713C341.521 249.781 345.968 251.934 348.754 254.65C350.198 256.049 351.13 257.893 351.4 259.885C352.315 266.316 346.432 274.252 330.925 281.457C313.954 289.324 293.367 291.322 279.154 289.732L274.173 289.169C262.774 287.649 256.315 302.34 263.14 312.402C267.545 318.889 279.52 323.11 291.523 323.11C319.006 323.139 340.142 311.402 348.023 301.242L348.642 300.356C349.008 299.765 348.712 299.469 348.22 299.779C341.817 304.169 313.279 321.619 282.771 316.384C282.771 316.384 279.056 315.765 275.678 314.442C273.005 313.429 267.362 310.811 266.686 305.042C291.27 312.683 306.792 305.478 306.792 305.464ZM220.671 194.971C230.127 184.051 241.765 174.538 252.206 169.219C252.558 169.022 252.938 169.43 252.741 169.754C251.46 172 250.476 174.403 249.814 176.902C249.73 177.282 250.138 177.592 250.461 177.353C256.963 172.934 268.248 168.192 278.155 167.601C278.251 167.584 278.351 167.601 278.436 167.65C278.521 167.698 278.586 167.775 278.621 167.866C278.656 167.957 278.658 168.058 278.627 168.151C278.596 168.244 278.533 168.323 278.451 168.375C276.809 169.634 275.342 171.105 274.088 172.751C273.891 173.032 274.074 173.44 274.426 173.44C281.378 173.483 291.186 175.903 297.56 179.491C297.982 179.745 297.673 180.575 297.209 180.462C287.527 178.253 271.724 176.564 255.288 180.575C240.597 184.149 229.396 189.666 221.248 195.618C220.826 195.899 220.333 195.351 220.671 194.971Z" fill="#231E15"/>
@@ -639,11 +1703,6 @@ const base = ( apiKey ) => {
 };
 
 // Mailchimp — contact sync, not a sender.
-//
-// Deliberately no `group`. Mailchimp and SendGrid shared one while they were
-// SENDERS, where an org picking two providers to send the same mail was
-// meaningless. As contact syncs they are destinations, and a merchant could
-// reasonably keep several up to date, so the exclusivity is gone.
 var mailchimp = {
 	// Keys TODAY. Mailchimp integrations authenticate with OAuth 2 (authorization
 	// code) and that is where this goes, so the endpoints are recorded here
@@ -664,13 +1723,28 @@ var mailchimp = {
 	auth : {
 		type : 'keys'
 	},
-	category : 'contacts',
-	confirm : 'Disconnecting removes your stored Mailchimp key. 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 Networking in your organization settings puts your own brand in the from line.',
-		'This connection is becoming the way your Drawbridge contacts sync into a Mailchimp audience. Audience syncing is not live yet, so a key stored here does nothing today.'
-	],
-	excerpt : 'Sync your Drawbridge contacts into a Mailchimp audience.',
+	// EVERYTHING A MERCHANT READS. `errors` belongs in here rather than at the
+	// top level because the connection DOCUMENT carries its own `errors` array
+	// and the document is spread OVER the resolved manifest downstream — a
+	// top-level one would be replaced by that array and never render.
+	content : {
+		confirm : 'Disconnecting removes your stored Mailchimp key. 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 Networking in your organization settings puts your own brand in the from line.',
+			'This connection is becoming the way your Drawbridge contacts sync into a Mailchimp audience. Audience syncing is not live yet, so a key stored here does nothing today.'
+		],
+		excerpt : 'Sync your Drawbridge contacts into a Mailchimp audience.',
+		guide : [
+			'In Mailchimp, open Account & billing, then Extras, then API keys.',
+			'Create a key and copy it.',
+			'Paste it here. The key ends in a data-centre suffix like -us19, which tells Drawbridge which Mailchimp server your account is on.'
+		]
+	},
+	// Mailchimp and SendGrid shared a group while they were SENDERS, where an org
+	// picking two providers to send the same mail was meaningless. As contact
+	// syncs they are destinations, and a merchant could reasonably keep several
+	// up to date, so the exclusivity is gone.
+	exclusive : false,
 	feature : 'organization:connection:mailchimp',
 	fields : [
 		{
@@ -687,36 +1761,66 @@ var mailchimp = {
 			key : 'audience',
 			label : 'Mailchimp audience',
 			message : 'Contacts your campaigns collect are synced into this audience.',
+			hook : 'resources.audiences',
 			required : true,
-			source : 'catalog.audiences'
+			// Mailchimp's /lists takes no name filter either — same reason.
+			search : false
 		}
 	],
-	// The audiences a merchant can sync into, for the picker on their connection.
-	//
-	// count DEFAULTS TO 10 and maxes at 1000 (their own OpenAPI spec), so leaving
-	// it unset returns the first ten audiences and looks entirely successful —
-	// the same silent truncation Klaviyo has, at a different number. Paged
-	// against total_items so an account past a thousand still resolves.
+	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.
 	hooks : {
-		'catalog.audiences' : async ({ fetcher = fetch, settings }) => {
 
-			const key = settings?.apiKey;
-
-			const headers = {
-				// Basic with any username — Mailchimp reads only the password half.
-				authorization : 'Basic ' + Buffer.from( 'drawbridge:' + key ).toString( 'base64' )
-			};
-
-			const audiences = [];
+		auth : {
+			// Implemented outside this package: storing a typed key needs no vendor
+			// call, so the api's own form handler does it.
+			connect : {},
+			disconnect : {},
+			probe : false,
+			scopes : false,
+			// Keys today. When Mailchimp's OAuth lands this becomes a wrapper that
+			// follows the exchange with /oauth2/metadata — the data-centre call that
+			// is the whole reason its OAuth cannot be pure configuration.
+			token : false
+		},
+		commerce : false,
+		contacts : { remove : false, sync : false },
+		// 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.
+		email : false,
+		segment : false,
+		sms : false,
+		inbound : false,
+		lifecycle : false,
+		resources : {
+
+			// The audiences a merchant can sync into, for the picker on their
+			// connection.
+			//
+			// count DEFAULTS TO 10 and maxes at 1000 (Mailchimp's own OpenAPI spec),
+			// so leaving it unset returns the first ten audiences and looks entirely
+			// successful — the same silent truncation Klaviyo has, at a different
+			// number. Paged against total_items so an account past a thousand still
+			// resolves.
+			audiences : async ({ cursor, fetcher = fetch, limit = 100, search, settings }) => {
 
-			let offset = 0;
-			let total = null;
+				const key = settings?.apiKey;
 
-			while( total === null || ( offset < total && offset < 5000 ) ){
+				const count = Math.min( limit, 1000 );
+				const offset = Number( cursor || 0 );
 
 				const response = await fetcher(
-					base( key ) + '/lists?count=1000&offset=' + offset + '&fields=lists.id,lists.name,total_items',
-					{ headers, signal : AbortSignal.timeout( 15000 ) }
+					base( key ) + '/lists?count=' + count + '&offset=' + offset + '&fields=lists.id,lists.name,total_items',
+					{
+						// Basic with any username — Mailchimp reads only the password half.
+						headers : { authorization : 'Basic ' + Buffer.from( 'drawbridge:' + key ).toString( 'base64' ) },
+						signal : AbortSignal.timeout( 15000 )
+					}
 				);
 
 				if( ! response.ok ){
@@ -730,64 +1834,61 @@ var mailchimp = {
 
 				const body = await response.json();
 
-				for( const list of ( body?.lists || [] ) ){
+				const audiences = ( body?.lists || [] ).map( ( list ) => ({ id : list.id, title : list?.name || list.id }) );
 
-					audiences.push({ label : list?.name || list.id, value : list.id });
+				// Mailchimp's /lists takes no name filter, so a term is matched against
+				// this page rather than the account. Stated plainly because it is a real
+				// limit: a term matching only an audience on a later page finds nothing.
+				const term = String( search?.value || '' ).trim().toLowerCase();
 
-				}
+				const items = term
+					? audiences.filter( ( entry ) => entry.title.toLowerCase().includes( term ) )
+					: audiences;
 
-				total = body?.total_items ?? audiences.length;
-				offset = offset + 1000;
+				const nextOffset = offset + count;
+				const more = nextOffset < Number( body?.total_items || 0 );
 
-			}
+				return {
+					items,
+					pageInfo : {
+						endCursor : more ? String( nextOffset ) : null,
+						hasNextPage : more
+					}
+				};
 
-			return audiences;
+			},
+			prices : false,
+			products : false,
+			promotions : false
 
 		}
+,
+
+		// Drawbridge posts to a merchant's own endpoint, never through a vendor.
+		webhook : false
 	},
-	icon: icon$2,
+	icon: icon$1,
+	slug : 'mailchimp',
 	// A key with no audience chosen is authenticated and inert. Mailchimp also
 	// needs its merge fields created on that audience before any Drawbridge total
 	// can be written to a member — unlike Klaviyo, its custom fields are not
 	// schemaless — so the audience must be picked before lifecycle.register has
 	// anything to register against.
-	incomplete : ( data ) => ( data?.settings?.audience
-		? null
-		: 'Choose which Mailchimp audience your contacts should sync into.'
-	),
-	label : 'mailchimp',
-	// Uniform surface, honest answers. 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", not "never" — when the sync lands, probe and catalog become
-	// the first two to flip.
-	supports : {
-		'auth.connect' : true,
-		'auth.disconnect' : true,
-		'auth.probe' : false,
-		'auth.scopes' : false,
-		'catalog.audiences' : true,
-		'catalog.prices' : false,
-		'catalog.products' : false,
-		'catalog.promotions' : false,
-		'inbound.event' : false,
-		'inbound.process' : false,
-		'inbound.receive' : false,
-		'inbound.verify' : false,
-		'lifecycle.cleanup' : false,
-		'lifecycle.register' : false,
-		'lifecycle.rehydrate' : false
-	},
-	setup : [
-		'In Mailchimp, open Account & billing, then Extras, then API keys.',
-		'Create a key and copy it.',
-		'Paste it here. The key ends in a data-centre suffix like -us19, which tells Drawbridge which Mailchimp server your account is on.'
-	],
-	slug : 'mailchimp',
+	status : ( data ) => ( data?.settings?.audience ? data.status : 'pending' ),
 	// No steps: audience sync has not shipped, so this vendor contributes nothing
 	// to a workflow yet. An empty steps object is the honest declaration — the
 	// catalog renders the connection, and no builder offers a step it cannot run.
 	steps : {},
-	tasks : () => [
+	tasks : ( data ) => [
+		...( data?.settings?.audience
+			? []
+			: [
+				{
+					message : 'Choose which Mailchimp audience your contacts should sync into. Until you do, nothing is being synced.',
+					title : 'Choose an audience'
+				}
+			]
+		),
 		{
 			message : 'Contact syncing to Mailchimp audiences has not shipped yet, and this connection no longer sends your email. Nothing is being sent to Mailchimp right now.',
 			title : 'Audience sync not available yet',
@@ -803,7 +1904,7 @@ var mailchimp = {
 // A .js wrapper around otherwise untouched SVG so `node --test` can run against
 // lib/ directly. A bare .svg import would need a bundler loader and force the
 // tests onto dist/, which is a worse trade than one line of wrapper.
-var icon$1 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="white"/>
 <path fill-rule="evenodd" clip-rule="evenodd" d="M309.524 407.192L308.799 128.423C306.921 126.545 303.258 127.112 301.827 127.531L292.29 130.487C291.113 126.613 289.585 122.854 287.726 119.258C280.959 106.337 271.069 99.5052 259.096 99.4866H259.059C258.259 99.4866 257.469 99.5609 256.67 99.626L256.577 99.6353C256.231 99.2089 255.871 98.7935 255.499 98.3897C250.293 92.8125 243.601 90.0889 235.588 90.3213C220.139 90.7675 204.755 101.941 192.271 121.786C183.487 135.757 176.823 153.298 174.917 166.878L144.493 176.313C135.542 179.129 135.263 179.408 134.082 187.858C133.199 194.253 109.766 375.69 109.766 375.69L306.159 409.692L309.524 407.192ZM245.181 103.065C242.569 101.346 239.511 100.546 235.885 100.621C212.033 101.308 191.23 138.611 185.923 163.467L208.771 156.384L212.851 155.119C215.845 139.336 223.355 122.957 233.181 112.416C236.616 108.639 240.671 105.477 245.172 103.065H245.181ZM224.145 151.615L256.94 141.446C257.042 132.894 256.112 120.252 251.836 111.329C247.282 113.207 243.452 116.497 240.7 119.444C233.329 127.373 227.315 139.466 224.155 151.615H224.145ZM267.211 138.267L282.455 133.536C280.02 125.616 274.238 112.342 262.517 110.111C266.161 119.527 267.099 130.431 267.211 138.267Z" fill="#95BF47"/>
 <path d="M353.528 149.156C352.356 149.063 329.657 148.709 329.657 148.709C329.657 148.709 310.666 130.249 308.789 128.362C308.062 127.691 307.141 127.268 306.158 127.153V409.64L391.257 388.456C391.257 388.456 356.53 153.366 356.307 151.758C356.199 151.075 355.866 150.448 355.361 149.976C354.856 149.505 354.216 149.216 353.528 149.156Z" fill="#5E8E3E"/>
@@ -909,31 +2010,48 @@ var shopify = {
 	auth : {
 		type : 'install'
 	},
-	category : 'commerce',
-	confirm : 'Disconnecting deactivates all products from this store, drafts any advertisements that use them, disables Shopify steps in your workflows until you reconnect, and stops revenue tracking for this organization.',
-	// How connecting is DESCRIBED — the copy and destination. What kind of connect
-	// it is lives in auth.type, once, so the two cannot disagree.
+	// EVERYTHING A MERCHANT READS.
+	//
+	// `errors` is in here rather than at the top level, and that is not a
+	// preference: the connection DOCUMENT carries its own `errors` array of
+	// scope-drift entries, and the document is spread OVER the resolved manifest
+	// downstream — a top-level one would be replaced by that array and never
+	// render.
 	//
-	// The redirect title is copy: it names where the link GOES rather than what it
-	// does, since installing happens on the App Store listing and the dashboard
-	// must never imply a store can be linked from inside it.
-	connect : {
+	// `connect` no longer exists as a container. Its other member was `redirect`,
+	// which is a URL and now sits with the vendor's other addresses.
+	content : {
+		confirm : 'Disconnecting deactivates all products from this store, drafts any advertisements that use them, disables Shopify steps in your workflows until you reconnect, and stops revenue tracking for this organization.',
+		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.'
+		],
 		errors : {
-			conflict : 'This store is already connected to another Drawbridge organization.',
-			currency : 'This store settles in a currency we can\'t bill yet. Connect a store with a supported settlement currency.',
-			invalid : 'We couldn\'t verify the install. Please try connecting again from the Shopify App Store.'
+			connect : {
+				conflict : 'This store is already connected to another Drawbridge organization.',
+				currency : 'This store settles in a currency we can\'t bill yet. Connect a store with a supported settlement currency.',
+				invalid : 'We couldn\'t verify the install. Please try connecting again from the Shopify App Store.'
+			}
 		},
+		excerpt : 'Connect your Shopify store to feature products in your campaigns and track conversions.',
+		guide : [
+			'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.',
+			'Choose a plan when Shopify asks. The connection shows Pending until you do, then Active.',
+			'Come back here — the connections list updates on its own once the install lands.'
+		],
+		// 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
+		// linked from inside it.
 		redirect : {
 			env : 'SHOPIFY_APP_LISTING_URL',
 			title : 'View on the Shopify App Store'
 		}
 	},
-	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 catalog.'
-	],
-	excerpt : 'Connect your Shopify store to feature products in your campaigns and track conversions.',
+	// ONE STORE PER ORGANIZATION. Two Shopify stores on one org would give every
+	// attributed order two possible sources.
+	exclusive : true,
 	feature : 'organization:connection:shopify',
 	fields : [
 		{
@@ -944,12 +2062,9 @@ var shopify = {
 			label : 'Store domain'
 		}
 	],
-	group : 'ecommerce',
-	// 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
-	// finish, which is a credential problem rather than a setup one, so the
-	// stored status already says so.
-	incomplete : () => null,
+	// Was `category : 'commerce'` AND `group : 'ecommerce'` — two words for one
+	// fact, which left nobody able to say which one a page read.
+	group : 'commerce',
 	// verify and event lean entirely on the shared HMAC helper — Shopify's scheme
 	// is exactly the shape it covers, so there is nothing vendor-specific to
 	// write for either. receive is the one hook that genuinely differs by
@@ -957,8 +2072,50 @@ var shopify = {
 	// /compliance enforces the topic allowlist above, because answering one late
 	// is a legal deadline rather than a retry.
 	hooks : {
-		'inbound.event' : ( args ) => readEventHeader({ ...args, descriptor : inbound }),
-		'inbound.receive' : ({ channel, event, headers, payload }) => {
+
+		auth : {
+			// The install completes inside Shopify admin; the api's callback stores
+			// what it hands back. auth.probe is false deliberately: the health check
+			// re-registers rather than answering "is this token still good", and
+			// scope drift is its own hook because a token can be perfectly valid
+			// while the grant is too narrow.
+			connect : {},
+			disconnect : {},
+			probe : false,
+			scopes : {},
+			// Shopify's install grant is exchanged inside its own app flow, not
+			// through the shared OAuth runner.
+			token : false
+		},
+		// Implemented in drawbridge-sync, which owns the attribution and the
+		// controllers it needs. Declared here so the steps below can point at them:
+		// a step naming a hook the vendor does not implement is a workflow that
+		// accepts the step and then silently does nothing.
+		commerce : {
+			code : {},
+			customer : {},
+			order : {},
+			product : {}
+		},
+		contacts : { remove : false, sync : false },
+
+		// verify and event lean entirely on the shared HMAC helper — Shopify's
+		// scheme is exactly the shape it covers, so there is nothing vendor-specific
+		// to write for either. receive is the one hook that genuinely differs by
+		// channel: /events buffers whatever arrives with the shop domain stamped on;
+		// /compliance enforces the topic allowlist above, because answering one late
+		// is a legal deadline rather than a retry.
+		// 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.
+		email : false,
+		segment : false,
+		sms : false,
+		inbound : {
+			event : ( args ) => readEventHeader({ ...args, descriptor : inbound }),
+			process : {},
+			receive : ({ channel, event, headers, payload }) => {
 
 			if( channel === 'compliance' && ! COMPLIANCE_TOPICS.has( event ) ){
 
@@ -977,12 +2134,44 @@ var shopify = {
 				provider : { id : headers[ inbound.headers.id ] || null }
 			};
 
+			},
+			verify : ( args ) => verifySignature({ ...args, descriptor : inbound })
 		},
-		'inbound.verify' : ( args ) => verifySignature({ ...args, descriptor : inbound })
+		lifecycle : { cleanup : {}, health : {}, register : {}, rehydrate : {} },
+		resources : {
+			audiences : false,
+			// Shopify has no separate price resource — a price belongs to a product
+			// variant and arrives with it, so there is nothing for prices to answer
+			// that products does not already.
+			prices : false,
+			products : {},
+			promotions : {}
+		}
+,
+
+		// Drawbridge posts to a merchant's own endpoint, never through a vendor.
+		webhook : false
 	},
-	icon: icon$1,
+	icon,
 	inbound,
-	label : 'shopify',
+	// 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;
+
+	},
 	// A pre-launch integration: it only surfaces once the App Store listing
 	// exists and the app is fully configured. Requiring all four means it can
 	// never render half-configured — and absence of any one excludes the
@@ -993,139 +2182,150 @@ var shopify = {
 		'SHOPIFY_APP_LISTING_URL',
 		'SHOPIFY_APP_HANDLE'
 	],
-	// The only vendor implementing most of the surface, which is why it was the
-	// one every slug branch in three repos was written for.
-	//
-	// auth.probe is false deliberately: the health check re-registers webhooks
-	// rather than answering "is this token still good", and scope drift is its own
-	// hook because a token can be perfectly valid while the grant is too narrow.
-	supports : {
-		'auth.connect' : true,
-		'auth.disconnect' : true,
-		'auth.probe' : false,
-		'auth.scopes' : true,
-		// Shopify has no separate price resource — a price belongs to a product
-		// variant and arrives with it, so there is nothing for prices to answer
-		// that products does not already.
-		'catalog.audiences' : false,
-		'catalog.prices' : false,
-		'catalog.products' : true,
-		'catalog.promotions' : true,
-		'inbound.event' : true,
-		'inbound.process' : true,
-		'inbound.receive' : true,
-		'inbound.verify' : true,
-		'lifecycle.cleanup' : true,
-		'lifecycle.register' : true,
-		'lifecycle.rehydrate' : true
-	},
-	setup : [
-		'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.',
-		'Choose a plan when Shopify asks. The connection shows Pending until you do, then Active.',
-		'Come back here — the connections list updates on its own once the install lands.'
-	],
 	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
+	// finish, which is a credential problem rather than a setup one, so the
+	// stored status already says so.
+	// Nothing to add — no setting can make this connection unusable, so the
+	// credential's own verdict stands.
+	status : ( data ) => data?.status,
 	// Step types name the CAPABILITY, not this vendor. A second store platform
 	// implements the same four commerce steps, and the connection on the step
 	// says which store it runs against — so a merchant sees one "Create
 	// customer", not one per platform. The three connection.* steps are not
 	// commerce at all: any vendor holding a rotating credential needs them.
+	// Step types name the CAPABILITY, not this vendor. A second store platform
+	// implements the same commerce steps, and the connection on the step says
+	// which store it runs against — so a merchant sees one "Create customer", not
+	// one per platform.
+	//
+	// Nested for readability and flattened to the stored name, at whatever depth:
+	// steps.commerce.customer.insert is `step.commerce.customer.insert` on a
+	// workflow document, and those strings cannot be renamed without a backfill.
+	//
+	// EVERY LEAF IS A FUNCTION so a step can read the merchant's own connection.
+	// The bodies these point at still live in drawbridge-sync; moving them is the
+	// next unit, and commerce.order.record is the one that decides whether the
+	// shape holds — 569 lines and 15 controller calls.
 	steps : {
-		'step.commerce.customer.insert' : {
-			billable : true,
-			key : 'Create customer',
-			queue : 'connection',
-			returns : [
-				{ key : 'shopifyCustomerId', label : 'Shopify Customer ID' }
-			],
-			settings : {},
-			triggers : [ 'lead.insert' ]
-		},
-		'step.commerce.code.issue' : {
-			billable : true,
-			key : 'Issue a discount code',
-			queue : 'connection',
-			returns : [
-				{ key : 'shopifyDiscountCode', label : 'Shopify Discount Code' },
-				{ key : 'shopifyDiscountId', label : 'Shopify Discount ID' }
-			],
-			settings : {
-				discount : {
-					required : true,
-					shape : {
-						id : { required : true, type : 'string' }
+
+		commerce : {
+
+			code : {
+				issue : () => ({
+					hook : 'commerce.code',
+					key : 'Issue a discount code',
+					queue : 'connection',
+					settings : {
+						discount : {
+							required : true,
+							shape : {
+								id : { required : true, type : 'string' }
+							},
+							type : 'object'
+						}
 					},
-					type : 'object'
-				}
+					triggers : [ 'lead.insert' ],
+					usage : { actions : 1 }
+				})
 			},
-			triggers : [ 'lead.insert' ]
-		},
-		// System steps: dispatched by sync itself rather than offered in the
-		// builder, so they carry no trigger. They are declared because the
-		// routing table and the system-workflow descriptions both read from here.
-		// Not a webhook monitor, despite the name it carried. Webhooks are
-		// declarative — declared in the app's toml, applied by Shopify to every
-		// install — so nothing registers or checks them here. This rotates the
-		// access token before Shopify's idle window closes, and reconciles the
-		// scopes the store granted against the ones the app now needs.
-		'step.connection.health.check' : {
-			description : 'Keeps store access working — refreshes the access token before it goes stale and reports when the store\'s approved permissions fall behind.',
-			key : 'Shopify Connection Health',
-			queue : 'connection',
-			system : true
-		},
-		'step.commerce.order.record' : {
-			description : 'Records an order and billing charge when a purchase is made via a Drawbridge campaign link.',
-			key : 'Shopify Order Tracking',
-			queue : 'connection',
-			system : true
-		},
-		'step.commerce.product.sync' : {
-			description : 'Syncs Shopify product data on webhook updates.',
-			key : 'Shopify Product Sync',
-			queue : 'connection',
-			system : true
-		},
-		// Audit-only. The "Shopify Token Activity" system workflow lists these for
-		// descriptive grouping, but its audit step docs are written manually at
-		// OAuth time — the workflow is never dispatched. Routing is declared
-		// defensively so that if it ever IS dispatched, the job lands on a real
-		// queue and the handler lookup misses cleanly instead of throwing
-		// "Unknown step type".
-		'step.connection.token.exchange' : {
-			key : 'Shopify Token Exchange',
-			queue : 'connection',
-			system : true
+
+			customer : {
+				insert : () => ({
+					hook : 'commerce.customer',
+					key : 'Create customer',
+					queue : 'connection',
+					settings : {},
+					triggers : [ 'lead.insert' ],
+					usage : { actions : 1 }
+				})
+			},
+
+			// 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.
+			order : {
+				record : () => ({
+					description : 'Records an order and billing charge when a purchase is made via a Drawbridge campaign link.',
+					hook : 'commerce.order',
+					key : 'Shopify Order Tracking',
+					queue : 'connection',
+					system : true
+				})
+			},
+
+			product : {
+				sync : () => ({
+					description : 'Syncs Shopify product data on webhook updates.',
+					hook : 'commerce.product',
+					key : 'Shopify Product Sync',
+					queue : 'connection',
+					system : true
+				})
+			}
+
 		},
-		'step.connection.token.refresh' : {
-			key : 'Shopify Token Refresh',
-			queue : 'connection',
-			system : true
+
+		connection : {
+
+			// Not a webhook monitor, despite the name it once carried. Webhooks are
+			// declarative — declared in the app's toml, applied by Shopify to every
+			// install — so nothing registers or checks them here. This rotates the
+			// access token before Shopify's idle window closes, and reconciles the
+			// scopes the store granted against the ones the app now needs.
+			health : {
+				check : () => ({
+					description : 'Keeps store access working — refreshes the access token before it goes stale and reports when the store\'s approved permissions fall behind.',
+					hook : 'lifecycle.health',
+					key : 'Shopify Connection Health',
+					queue : 'connection',
+					system : true
+				})
+			},
+
+			// Audit-only. The "Shopify Token Activity" system workflow lists these
+			// for descriptive grouping, but its audit step docs are written manually
+			// at OAuth time — the workflow is never dispatched. Routing is declared
+			// defensively so that if it ever IS dispatched, the job lands on a real
+			// queue and the handler lookup misses cleanly instead of throwing
+			// "Unknown step type".
+			token : {
+				exchange : () => ({
+					description : 'Records the token exchange that completed an install. Audit only — never dispatched.',
+					key : 'Shopify Token Exchange',
+					queue : 'connection',
+					system : true
+				}),
+				refresh : () => ({
+					description : 'Records a token rotation. Audit only — never dispatched.',
+					key : 'Shopify Token Refresh',
+					queue : 'connection',
+					system : true
+				})
+			}
+
 		}
+
 	},
+	// Shopify sits pending between the install landing and the merchant choosing a
+	// plan, and nothing on our side can move it — so the card says what they need
+	// to go and do rather than showing Pending with no next step.
+	//
+	// Scope drift is NOT here: drawbridge-sync writes it onto the connection
+	// document, and the document's own warnings render beside these.
+	tasks : ( data ) => ( data?.status === 'pending'
+		? [
+			{
+				message : 'Open the Drawbridge app in your Shopify admin and choose a plan. The connection activates once Shopify confirms it.',
+				title : 'Choose a plan in Shopify'
+			}
+		]
+		: []
+	),
 	title : 'Shopify'
 };
 
-// Drawbridge, exported from the brand kit and left as authored — the fills are the
-// vendor's own mark, not a recolour.
-//
-// A .js wrapper around otherwise untouched SVG so `node --test` can run against
-// lib/ directly. A bare .svg import would need a bundler loader and force the
-// tests onto dist/, which is a worse trade than one line of wrapper.
-var icon = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
-<rect width="500" height="500" fill="#BAEC5F"/>
-<g clip-path="url(#clip0_2115_2832)">
-<path d="M140.224 127.586L174.803 188.73V311.176L140 372.32L176.084 392.031L216.111 321.753V178.278L176.341 108L140.224 127.586Z" fill="#0D1314"/>
-<path d="M360.001 127.523L323.693 108.282L284.948 178.498V321.596L322.923 391.749L359.393 372.79L326.224 311.52V188.73L360.001 127.523Z" fill="#0D1314"/>
-</g>
-<defs>
-<clipPath id="clip0_2115_2832">
-<rect width="220" height="284" fill="white" transform="translate(140 108)"/>
-</clipPath>
-</defs>
-</svg>`;
-
 // Webhooks — the only connection with no third party behind it. Connecting
 // generates a signing secret rather than asking for a credential, which is why
 // its one field declares no `input`.
@@ -1141,13 +2341,26 @@ var webhook = {
 	auth : {
 		type : 'generated'
 	},
-	category : 'developer',
-	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.',
-		'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.',
+	// EVERYTHING A MERCHANT READS. `errors` would belong here too — the
+	// connection DOCUMENT carries its own `errors` array and is spread OVER the
+	// resolved manifest downstream, so a top-level one is replaced by that array.
+	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.',
+			'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.',
+		guide : [
+			'Press Connect. Drawbridge generates a signing secret and shows it here.',
+			'Copy the secret into your own endpoint.',
+			'On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload.'
+		]
+	},
+	// Nothing to be exclusive with — there is no second webhook vendor, and a
+	// merchant with two endpoints is a step-level choice rather than a second
+	// connection.
+	exclusive : false,
 	feature : 'organization:connection:webhook',
 	fields : [
 		{
@@ -1160,14 +2373,91 @@ var webhook = {
 			label : 'Signing secret'
 		}
 	],
+	group : 'developer',
+	// 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 —
+	// connect generates a secret rather than proving a credential.
+	hooks : {
+		auth : {
+			// Minting and clearing a secret needs no vendor call, so the api's own
+			// handler does both.
+			connect : {},
+			disconnect : {},
+			probe : false,
+			scopes : false,
+			// Nothing to mint. Connecting generates a secret; there is no vendor.
+			token : false
+		},
+		commerce : false,
+		contacts : { remove : false, sync : false },
+		// 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.
+		email : false,
+		segment : false,
+		sms : false,
+		inbound : false,
+		lifecycle : false,
+		resources : {
+			audiences : false,
+			prices : false,
+			products : false,
+			promotions : false
+		},
+		// THE BODY IS HERE, not in drawbridge-sync. It needs `crypto` and an HTTP
+		// client and nothing else — no controller, no queue, no database — so
+		// there was never a reason for it to live in another repo.
+		//
+		// That is the rule the whole split runs on: a hook lives in sync only if it
+		// needs Drawbridge's own database, sockets or queues. This one does not.
+		webhook : {
+
+			send : async ({ context, controller, request : send = safeRequest, settings, step }) => {
+
+			const { headers = {}, method = 'POST', url } = step.settings || {};
+
+			const request = { method, url : url || null };
+
+			if( ! url ) return { message : 'Outgoing webhook URL is not configured for this step.', request, response : { skipped : true }, skipped : true };
+
+			// The LEAD, when there is one, rather than the accumulated context. A
+			// receiver wants the entrant's record, not our internal step state.
+			const lead = context?.lead
+			? await controller.get({ collection : 'lead', query : { id : context.lead } })
+			: null;
+
+			const body = lead || context;
+
+			request.body = body;
+
+			const outgoing = { ...headers };
+
+			// Signed with the connection's secret when it has one. A payload nobody can
+			// verify is an unsigned payload, which is why the connection's own task card
+			// tells the merchant to check it.
+			if( settings?.secret ){
+
+			outgoing[ 'X-Drawbridge-Signature' ] = 'sha256=' + crypto
+			.createHmac( 'sha256', settings.secret )
+			.update( JSON.stringify( body ) )
+			.digest( 'hex' );
+
+			}
+
+			const response = await send({ body, headers : outgoing, method, url });
+
+			return { message : 'Webhook POSTed to ' + url + '.', request, response : response || { delivered : true } };
+
+
+			}
+		}
+	},
 	// Borrowed: this is the Drawbridge mark, because Webhooks has none of its own.
 	// It is the one card that reads wrong — our logo among vendor logos — and it
 	// wants a mark of its own when there is one.
-	icon,
-	// The destination url is supplied per step, not per connection, so there is
-	// nothing to finish here — generating the secret IS connecting.
-	incomplete : () => null,
-	label : 'webhook',
+	icon: icon$3,
 	// 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' ],
@@ -1175,39 +2465,28 @@ var webhook = {
 	// 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 —
 	// connect generates a secret rather than proving a credential.
-	supports : {
-		'auth.connect' : true,
-		'auth.disconnect' : true,
-		'auth.probe' : false,
-		'auth.scopes' : false,
-		'catalog.audiences' : false,
-		'catalog.prices' : false,
-		'catalog.products' : false,
-		'catalog.promotions' : false,
-		'inbound.event' : false,
-		'inbound.process' : false,
-		'inbound.receive' : false,
-		'inbound.verify' : false,
-		'lifecycle.cleanup' : false,
-		'lifecycle.register' : false,
-		'lifecycle.rehydrate' : false
-	},
-	setup : [
-		'Press Connect. Drawbridge generates a signing secret and shows it here.',
-		'Copy the secret into your own endpoint.',
-		'On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload.'
-	],
 	slug : 'webhook',
+	// The destination url is supplied per step, not per connection, so there is
+	// nothing to finish here — generating the secret IS connecting, and no
+	// setting can make this connection unusable. The credential's own verdict
+	// stands.
+	status : ( data ) => data?.status,
 	steps : {
-		'step.webhook.send' : {
-			billable : true,
-			key : 'Send webhook',
-			queue : 'webhook',
-			returns : [],
-			settings : {
-				url : { format : 'url', required : true, type : 'string' }
-			},
-			triggers : [ 'lead.insert', 'lead.delete' ]
+		webhook : {
+			send : () => ({
+				hook : 'webhook.send',
+				key : 'Send webhook',
+				queue : 'webhook',
+				settings : {
+					url : { format : 'url', required : true, type : 'string' }
+				},
+				triggers : [ 'lead.insert', 'lead.delete' ],
+				// Replaces `billable : true`, which fed BILLABLE_STEP_TYPES, which set
+				// workflow.billable at save, which sync then checked against a usage
+				// the handler returned — three hops for one fact, two of which could
+				// disagree silently.
+				usage : { actions : 1 }
+			})
 		}
 	},
 	// The card the connection page raises. Before connecting it explains what
@@ -1257,9 +2536,30 @@ var webhook = {
 
 // The queues sync runs. A step routes to exactly one, and naming them here is
 // what lets sync derive its routing table instead of maintaining a parallel copy
-// that can fall out of step with the catalog.
+// that can fall out of step with the resources.
 const QUEUES = [ 'connection', 'notification', 'segment', 'webhook' ];
 
+// A HOOK'S VALUE IS ITS ANSWER — false is a decision recorded, a function is the
+// body, and {} means supported but implemented in the repo holding the vendor's
+// dependencies. Anything else, including absence, is not implemented.
+const implemented = ( hooks, path ) => {
+
+	const hook = path.split( '.' ).reduce( ( node, key ) => node?.[ key ], hooks );
+
+	return typeof hook === 'function' || ( !! hook && typeof hook === 'object' );
+
+};
+
+// Walk a nested map to its FUNCTION leaves, returning [ 'a.b.c', fn ] pairs.
+// Depth is whatever the vendor wrote, because stored step types run three and
+// four segments deep and those strings cannot be renamed without a backfill.
+const leaves = ( node, path = [] ) => Object.entries( node || {} ).flatMap(
+	( [ key, value ] ) => ( typeof value === 'function'
+		? [ [ [ ...path, key ].join( '.' ), value ] ]
+		: value && typeof value === 'object' ? leaves( value, [ ...path, key ] ) : []
+	)
+);
+
 // WHAT A CONNECTION MUST DECLARE. Thrown at import rather than discovered by a
 // merchant looking at a broken card, or by a workflow that accepted a step it
 // could never run.
@@ -1267,12 +2567,24 @@ const build = ( manifest ) => {
 
 	if( ! manifest?.slug ) throw new Error( 'A connection needs a slug' );
 	if( ! manifest?.title ) throw new Error( manifest.slug + ' needs a title' );
-	if( ! manifest?.feature ) throw new Error( manifest.slug + ' needs a plan feature key' );
-	if( ! manifest?.excerpt ) throw new Error( manifest.slug + ' needs an excerpt for its card' );
+	// A PRIVATE connection is Drawbridge itself: always present, in every
+	// deployment, for every organization. It contributes steps and never appears
+	// in the catalog, so the two questions a public connection answers — can this
+	// merchant connect it (`requires`) and does their plan allow it (`feature`) —
+	// have no meaning and are not asked.
+	if( ! manifest?.private && ! manifest?.feature ) throw new Error( manifest.slug + ' needs a plan feature key' );
+	// EVERYTHING A MERCHANT READS lives under `content`, so the question on a new
+	// vendor is "does a person read this" rather than "is this marketing".
+	//
+	// `errors` is in there for a harder reason than tidiness: the connection
+	// DOCUMENT carries its own `errors` array, and the document is spread OVER the
+	// resolved manifest downstream — a top-level `errors` here would be replaced
+	// by that array and never render.
+	if( ! manifest?.content?.excerpt ) throw new Error( manifest.slug + ' needs content.excerpt for its card' );
 
-	if( ! Array.isArray( manifest?.description ) || ! manifest.description.length ){
+	if( ! Array.isArray( manifest?.content?.description ) || ! manifest.content.description.length ){
 
-		throw new Error( manifest.slug + ' needs a description — an array of paragraphs for its page' );
+		throw new Error( manifest.slug + ' needs content.description — an array of paragraphs for its page' );
 
 	}
 
@@ -1300,26 +2612,46 @@ const build = ( manifest ) => {
 		// merchant, at form time. A Klaviyo list cannot be a static list here —
 		// it exists in their account, not in this package — and the alternative is
 		// asking a merchant to paste an id from another browser tab.
-		if( field.input === 'select' && ! ( field.options || [] ).length && ! field.source ){
+		if( field.input === 'select' && ! ( field.options || [] ).length && ! field.hook ){
 
-			throw new Error( manifest.slug + '.' + field.key + ' is a select and must declare options or a source' );
+			throw new Error( manifest.slug + '.' + field.key + ' is a select and must declare options or a hook' );
 
 		}
 
-		// A source names a hook, and the manifest must actually support it —
-		// otherwise the form asks for choices from something that will answer
-		// `unsupported`, and the merchant sees a dropdown that never fills.
-		if( field.source ){
+		// A HOOK, named outright. ListResource and InputResource take an
+		// `endpoint`, and the client composes one from this — building a path from
+		// a name, rather than the manifest carrying the api's route shape. That
+		// route has already moved twice; a path here would ship the old one to
+		// five repos that upgrade at different times.
+		//
+		// It also lifts a limit nobody decided: a connection needing a list AND a
+		// segment is two fields with two hooks, where one `source` per form
+		// quietly loaded only the first.
+		if( field.hook ){
+
+			if( ! HOOK_NAMES.includes( field.hook ) ){
+
+				throw new Error( manifest.slug + '.' + field.key + ' names an unknown hook: ' + field.hook );
+
+			}
 
-			if( ! HOOK_NAMES.includes( field.source ) ){
+			// The picker route is a GET, and a GET must be safe to repeat — Next
+			// prefetches, proxies retry. `resources.*` is the read-only domain, so a
+			// field cannot point a dropdown at auth.disconnect. `supports` alone
+			// would not catch that: Klaviyo really does support auth.disconnect.
+			if( ! field.hook.startsWith( 'resources.' ) ){
 
-				throw new Error( manifest.slug + '.' + field.key + ' sources options from an unknown hook: ' + field.source );
+				throw new Error( manifest.slug + '.' + field.key + ' reads from ' + field.hook + ' — a picker may only read resources.*' );
 
 			}
 
-			if( manifest.supports?.[ field.source ] !== true ){
+			// ASK THE HOOK ITSELF. This used to consult a parallel `supports` map,
+			// which is two places to say one thing and therefore two places to
+			// disagree — a picker pointed at a hook the vendor had since removed
+			// still passed, because the map still said true.
+			if( ! implemented( manifest.hooks, field.hook ) ){
 
-				throw new Error( manifest.slug + '.' + field.key + ' sources options from ' + field.source + ', which it declares unsupported' );
+				throw new Error( manifest.slug + '.' + field.key + ' reads ' + field.hook + ', which this vendor does not implement' );
 
 			}
 
@@ -1355,9 +2687,12 @@ const build = ( manifest ) => {
 
 	}
 
-	if( ! CATEGORIES.includes( manifest?.category ) ){
+	// `group` does the actual grouping on the connections page, and `category`
+	// was a second word for the same fact — so it is gone rather than kept as an
+	// alias nobody could tell apart from this one.
+	if( ! GROUPS.includes( manifest?.group ) ){
 
-		throw new Error( manifest.slug + ' needs a category — one of ' + CATEGORIES.join( ', ' ) );
+		throw new Error( manifest.slug + ' needs a group — one of ' + GROUPS.join( ', ' ) );
 
 	}
 
@@ -1392,6 +2727,25 @@ const build = ( manifest ) => {
 
 		}
 
+		// THE TOKEN REQUEST IS A HOOK, and an oauth vendor that does not implement
+		// it cannot mint anything. Refused here rather than discovered at the
+		// callback, which is after the merchant has consented and left.
+		if( typeof manifest.hooks?.auth?.token !== 'function' ){
+
+			throw new Error( manifest.slug + ' is oauth and must implement hooks.auth.token — point it at authToken() or wrap it' );
+
+		}
+
+		for( const url of OAUTH_URLS ){
+
+			if( ! manifest.auth.oauth?.urls?.[ url ] ){
+
+				throw new Error( manifest.slug + ' is oauth and must declare auth.oauth.urls.' + url );
+
+			}
+
+		}
+
 		// THE REDIRECT MUST BE THE ONE PATH THE DASHBOARD SERVES.
 		//
 		// There is exactly one callback route — app/api/connection/[slug]/callback
@@ -1404,10 +2758,10 @@ const build = ( manifest ) => {
 		// registered at the vendor, and fails AFTER the merchant has consented —
 		// they hit a dashboard 404 having already granted access. Cheaper to refuse
 		// the manifest at import.
-		if( manifest.auth.oauth.redirect !== '/api/connection/' + manifest.slug + '/callback' ){
+		if( manifest.auth.oauth.urls.redirect !== '/api/connection/' + manifest.slug + '/callback' ){
 
 			throw new Error(
-				manifest.slug + ' declares auth.oauth.redirect ' + manifest.auth.oauth.redirect
+				manifest.slug + ' declares auth.oauth.urls.redirect ' + manifest.auth.oauth.urls.redirect
 				+ ' but the only callback route is /api/connection/' + manifest.slug + '/callback'
 			);
 
@@ -1418,15 +2772,15 @@ const build = ( manifest ) => {
 	// A vendor that receives from the outside must say where it puts the event
 	// name. Without it the receiver has nothing to dispatch on, and the failure
 	// is a request accepted and dropped rather than an error.
-	if( manifest.supports?.[ 'inbound.event' ] && ! manifest.inbound?.headers?.event ){
+	if( implemented( manifest.hooks, 'inbound.event' ) && ! manifest.inbound?.headers?.event ){
 
-		throw new Error( manifest.slug + ' supports inbound.event but declares no inbound.headers.event' );
+		throw new Error( manifest.slug + ' implements inbound.event but declares no inbound.headers.event' );
 
 	}
 
-	if( manifest.supports?.[ 'inbound.verify' ] && ! manifest.inbound?.headers?.signature ){
+	if( implemented( manifest.hooks, 'inbound.verify' ) && ! manifest.inbound?.headers?.signature ){
 
-		throw new Error( manifest.slug + ' supports inbound.verify but declares no inbound.headers.signature' );
+		throw new Error( manifest.slug + ' implements inbound.verify but declares no inbound.headers.signature' );
 
 	}
 
@@ -1445,101 +2799,125 @@ const build = ( manifest ) => {
 	// Required on every manifest for the same reason `supports` is: a missing
 	// answer is indistinguishable from a vendor written before the question
 	// existed.
-	if( typeof manifest?.incomplete !== 'function' ){
+	if( typeof manifest?.status !== 'function' ){
 
-		throw new Error( manifest.slug + ' must declare incomplete( data ) — return null when the connection is usable, or the reason it is not' );
+		throw new Error( manifest.slug + ' must declare status( data ) — return null to accept the connection\'s own status, or { message, status } to override it' );
 
 	}
 
-	// How to get the credential, in the merchant's words. A connection page that
-	// cannot say where to find an API key sends somebody to a vendor's docs
-	// written for a different integration.
-	if( ! Array.isArray( manifest?.setup ) || ! manifest.setup.length ){
+	// How to connect, in the merchant's words. A connection page that cannot say
+	// where to find an API key sends somebody to a vendor's docs written for a
+	// different integration.
+	if( ! Array.isArray( manifest?.content?.guide ) || ! manifest.content.guide.length ){
 
-		throw new Error( manifest.slug + ' needs a setup guide — an array of steps for its page' );
+		throw new Error( manifest.slug + ' needs content.guide — an array of steps for its page' );
 
 	}
 
-	// HOOKS A MANIFEST CAN CARRY ITSELF.
-	//
-	// Not every hook can live here — a step handler needs a queue, a controller
-	// and vendor SDKs, and putting those behind a published package makes every
-	// consumer carry them. But the hooks that are pure or plain HTTP can, and
-	// auth.connect is the one that matters most: it is the only vendor-specific
-	// step in an OAuth callback, so putting it here is what lets ONE route serve
-	// every OAuth vendor instead of one route each.
-	//
-	// Keyed flat ('auth.connect') to match the vocabulary and the supports map,
-	// so the three cannot drift apart in naming.
-	for( const [ name, hook ] of Object.entries( manifest.hooks || {} ) ){
+	// A STATUS THE SCHEMA WILL ACCEPT. Called with nothing, which is the catalog
+	// case — a vendor nobody has connected — so undefined is a legitimate answer.
+	// Anything else must be one of the four, because a typo here surfaces as a
+	// Mongo "Document failed validation" with no clue which field caused it.
+	if( typeof manifest?.status !== 'function' ){
 
-		if( ! HOOK_NAMES.includes( name ) ){
+		throw new Error( manifest.slug + ' must declare status( data ) — one of ' + STATUSES.join( ', ' ) );
 
-			throw new Error( manifest.slug + ' implements an unknown hook: ' + name );
-
-		}
+	}
 
-		if( typeof hook !== 'function' ){
+	const status = manifest.status({});
 
-			throw new Error( manifest.slug + ' declares hook ' + name + ' but it is not a function' );
+	if( status != null && ! STATUSES.includes( status ) ){
 
-		}
+		throw new Error( manifest.slug + ' status() returned ' + status + ' — must be one of ' + STATUSES.join( ', ' ) );
 
-		// Implementing a hook you declared unsupported is the support matrix
-		// lying, and the matrix is what a caller reads to decide whether to
-		// bother asking. Caught here rather than discovered as a hook that is
-		// never called.
-		if( manifest.supports?.[ name ] !== true ){
+	}
 
-			throw new Error( manifest.slug + ' implements ' + name + ' but declares supports[ \'' + name + '\' ] false' );
+	// THE UNIFORM SURFACE — every connection answers every hook in the vocabulary,
+	// and the ANSWER IS THE VALUE. There is no `supports` map any more: it was a
+	// second place to say the same thing, so a manifest could implement a hook it
+	// declared unsupported, or claim one it had since deleted, and build() had two
+	// separate checks trying to keep them honest.
+	//
+	//   false      declined — a decision recorded, not silence
+	//   function   supported, and the body is right here
+	//   {}         supported, implemented in the repo holding the dependencies
+	//
+	// A missing entry is rejected rather than defaulted, because a default is the
+	// silence this exists to remove: it would be impossible to tell a vendor that
+	// declined a hook from one written before the hook existed.
+	for( const [ domain, verbs ] of Object.entries( HOOKS ) ){
 
-		}
+		for( const verb of verbs ){
 
-	}
+			const hook = manifest.hooks?.[ domain ]?.[ verb ];
 
-	// THE UNIFORM SURFACE. Every connection answers every hook in the vocabulary,
-	// with true where it implements one and false where it deliberately does not.
-	// A missing entry is rejected rather than defaulted, because a default is
-	// exactly the silence this exists to remove: it would be impossible to tell a
-	// vendor that declined a hook from one written before the hook existed.
-	const supports = manifest.supports || {};
+			// A domain answered wholesale — `inbound : false` rather than four
+			// falses — is how a vendor that receives nothing says so once.
+			if( manifest.hooks?.[ domain ] === false ) continue;
 
-	for( const name of HOOK_NAMES ){
+			if( hook !== false && ! implemented( { [ domain ] : { [ verb ] : hook } }, domain + '.' + verb ) ){
 
-		if( typeof supports[ name ] !== 'boolean' ){
+				throw new Error( manifest.slug + ' must answer hooks.' + domain + '.' + verb + ' — false, a function, or {} if another repo implements it' );
 
-			throw new Error( manifest.slug + ' must declare supports[ \'' + name + '\' ] as true or false' );
+			}
 
 		}
 
 	}
 
-	for( const name of Object.keys( supports ) ){
+	for( const [ domain, verbs ] of Object.entries( manifest.hooks || {} ) ){
+
+		if( ! HOOKS[ domain ] ) throw new Error( manifest.slug + ' implements an unknown hook domain: ' + domain );
 
-		if( ! HOOK_NAMES.includes( name ) ){
+		for( const verb of Object.keys( verbs === false ? {} : verbs ) ){
 
-			throw new Error( manifest.slug + ' declares an unknown hook: ' + name );
+			if( ! HOOKS[ domain ].includes( verb ) ){
+
+				throw new Error( manifest.slug + ' implements an unknown hook: ' + domain + '.' + verb );
+
+			}
 
 		}
 
 	}
 
-	for( const [ type, step ] of Object.entries( manifest.steps || {} ) ){
+	// STEPS ARE NESTED FOR READABILITY and flattened to their stored name. Each
+	// leaf is a FUNCTION — a step can depend on what the merchant's connection
+	// knows, which a static object would have to be true for at publish time.
+	for( const [ name, step ] of leaves( manifest.steps ) ){
+
+		const type = 'step.' + name;
 
-		if( ! type.startsWith( 'step.' ) ){
+		// A step nobody added to the vocabulary is a workflow document the database
+		// will refuse — and refuse naming no field. Said here instead, at import,
+		// where the file that caused it is obvious.
+		if( ! STEPS[ name ] ){
 
-			throw new Error( manifest.slug + ' declares a step type that is not step.<domain>.<verb>: ' + type );
+			throw new Error( manifest.slug + ' declares an unknown step: ' + type + ' — add it to STEPS in contract.js' );
 
 		}
 
-		if( ! step?.key ) throw new Error( manifest.slug + ' step ' + type + ' needs a key — the label the builder shows' );
+		// Called with nothing, which is what a step must tolerate: the builder lists
+		// steps for a merchant who has not chosen a connection yet.
+		const declared = step({});
 
-		if( ! QUEUES.includes( step?.queue ) ){
+		if( ! declared?.key ) throw new Error( manifest.slug + ' step ' + type + ' needs a key — the label the builder shows' );
+
+		if( ! QUEUES.includes( declared?.queue ) ){
 
 			throw new Error( manifest.slug + ' step ' + type + ' needs a queue — one of ' + QUEUES.join( ', ' ) );
 
 		}
 
+		// A step pointing at a hook this vendor does not implement is a workflow
+		// that accepts the step and then silently does nothing. System steps carry
+		// no hook: drawbridge-sync dispatches them and owns their handlers.
+		if( declared.hook && ! implemented( manifest.hooks, declared.hook ) ){
+
+			throw new Error( manifest.slug + ' step ' + type + ' points at hook ' + declared.hook + ', which this vendor does not implement' );
+
+		}
+
 	}
 
 	return Object.freeze({
@@ -1547,15 +2925,28 @@ const build = ( manifest ) => {
 		fields : Object.freeze( manifest.fields || [] ),
 		hooks : Object.freeze( manifest.hooks || {} ),
 		inbound : Object.freeze( manifest.inbound || {} ),
-		setup : Object.freeze( manifest.setup || [] ),
-		supports : Object.freeze( supports ),
 		requires : Object.freeze( manifest.requires || [] ),
 		steps : Object.freeze( manifest.steps || {} )
 	});
 
 };
 
+// EVERY STEP TYPE ANY VENDOR IMPLEMENTS, as { 'step.domain.verb' : label }.
+//
+// drawbridge-api's enums.step.type — the $jsonSchema validator on the workflow
+// collection — unions this over its own map, so adding a vendor step is a
+// manifest change and nothing else. It UNIONS rather than replaces: retired and
+// not-yet-migrated types must stay writable, or the migration that retires them
+// cannot write either.
+const stepLabels = ( catalog = connections ) => Object.fromEntries(
+	Object.values( catalog ).flatMap(
+		( vendor ) => leaves( vendor.steps ).map( ( [ name ] ) => [ 'step.' + name, STEP_LABELS[ 'step.' + name ] ] )
+	)
+);
+
 const connections = Object.freeze({
+	drawbridge : build( drawbridge ),
+	hubspot : build( hubspot ),
 	klaviyo : build( klaviyo ),
 	mailchimp : build( mailchimp ),
 	shopify : build( shopify ),
@@ -1580,7 +2971,10 @@ const connections = Object.freeze({
 
 	for( const [ slug, manifest ] of Object.entries( connections ) ){
 
-		for( const type of Object.keys( manifest.steps ) ){
+		for( const [ name ] of leaves( manifest.steps ) ){
+
+			const type = 'step.' + name;
+
 
 			if( owners[ type ] ){
 
@@ -1606,6 +3000,21 @@ const availableConnections = ( env = {} ) => Object.fromEntries(
 	)
 );
 
+// WHAT A MERCHANT CAN SEE AND CONNECT. Everything available, minus the private
+// ones.
+//
+// The two lists are different questions and both are needed: `drawbridge` is
+// runnable everywhere and contributes the base workflow steps, so
+// availableConnections MUST include it — but it is not a card, has no credential
+// and nothing to connect, so the connections page must not offer it.
+//
+// Splitting them rather than filtering at the call site because there are two
+// listing sites in route/organization-connection.js, and a filter applied to one
+// and forgotten on the other is exactly how a private connection surfaces.
+const catalogConnections = ( env = {} ) => Object.fromEntries(
+	Object.entries( availableConnections( env ) ).filter( ( [ , manifest ] ) => ! manifest.private )
+);
+
 // Per-slug allowlist of stored setting keys safe to return in an API response.
 // DERIVED from each vendor's own field declaration — a field is public unless it
 // says `redact : true`. An unknown slug gets an empty allowlist, so a leftover
@@ -1620,16 +3029,23 @@ const publicSettingsBySlug = Object.fromEntries(
 // Every step every configured vendor contributes, flattened and stamped with the
 // slug that owns it. The api builds its workflow catalog from this and sync
 // builds its routing table from it, so a step cannot exist on one side only.
+// SHAPE PRESERVED DELIBERATELY: still { ...step, slug, type }. drawbridge-sync
+// derives its whole routing table from this and its step-handler coverage test
+// reads it, so nesting the manifests must not change what comes out — otherwise
+// a manifest refactor becomes a sync release.
+//
+// Each step is now a FUNCTION, called here with no connection: this is the
+// catalog view, the same one the builder shows before a merchant picks anything.
 const connectionSteps = ( env = {} ) => Object.entries( availableConnections( env ) )
-	.flatMap( ( [ slug, manifest ] ) => Object.entries( manifest.steps )
-		.map( ( [ type, step ] ) => ({ ...step, slug, type }) )
+	.flatMap( ( [ slug, manifest ] ) => leaves( manifest.steps )
+		.map( ( [ name, step ] ) => ({ ...step({}), slug, type : 'step.' + name }) )
 	);
 
 // Which vendors implement a given hook. The uniform surface makes this total —
 // every vendor appears in exactly one of the two lists, never neither.
 const hookSupport = ( name ) => ({
-	no : Object.keys( connections ).filter( ( slug ) => ! connections[ slug ].supports[ name ] ),
-	yes : Object.keys( connections ).filter( ( slug ) => connections[ slug ].supports[ name ] )
+	no : Object.keys( connections ).filter( ( slug ) => ! implemented( connections[ slug ].hooks, name ) ),
+	yes : Object.keys( connections ).filter( ( slug ) => implemented( connections[ slug ].hooks, name ) )
 });
 
 // A vendor's fields, described for the dashboard. Served so one generic form
@@ -1644,8 +3060,9 @@ const hookSupport = ( name ) => ({
 // VALUE is withheld independently by whatever redacts stored settings, and a
 // test asserts no descriptor ever carries one.
 const connectFields = ( slug ) => ( connections[ slug ]?.fields || [] )
-	.map( ({ copy, from, input, key, label, message, options, placeholder, redact, required }) => ({
+	.map( ({ copy, from, hook, input, key, label, message, options, placeholder, redact, required, search }) => ({
 		...( copy && { copy : true }),
+		...( hook && { hook }),
 		...( from && { from }),
 		...( input && { input }),
 		key,
@@ -1653,6 +3070,9 @@ const connectFields = ( slug ) => ( connections[ slug ]?.fields || [] )
 		...( message && { message }),
 		...( options && { options }),
 		...( placeholder && { placeholder }),
+		// Declared false only where the vendor cannot filter, so a picker does not
+		// offer a search box that quietly searches one page.
+		...( search === false && { search : false }),
 		required : Boolean( required ),
 		// A UI hint, not a leak: the form uses it to stop requiring the field once
 		// the connection exists, and to say "leave blank to keep" — because the GET
@@ -1675,9 +3095,15 @@ const runHook = async ( slug, name, args = {} ) => {
 
 	if( ! manifest ) return { outcome : OUTCOMES.unsupported, reason : 'no such connection: ' + slug };
 
-	if( ! manifest.supports?.[ name ] ) return { outcome : OUTCOMES.unsupported, reason : slug + ' does not implement ' + name };
+	// The hook's own value is the answer — there is no `supports` map to consult,
+	// and therefore none to disagree with what is actually here.
+	const hook = name.split( '.' ).reduce( ( node, key ) => node?.[ key ], manifest.hooks );
+
+	if( hook === false || hook == null ){
 
-	const hook = manifest.hooks?.[ name ];
+		return { outcome : OUTCOMES.unsupported, reason : slug + ' does not implement ' + name };
+
+	}
 
 	// Declared supported, implemented somewhere else. Sync owns the step handlers
 	// and lifecycle jobs, so this is a legitimate answer here rather than a fault
@@ -1690,7 +3116,12 @@ const runHook = async ( slug, name, args = {} ) => {
 
 	try {
 
-		return { outcome : OUTCOMES.answered, result : await hook( args ) };
+		// THE MANIFEST RIDES ALONG so a hook can read its own declared urls rather
+		// than repeating them as literals — `revoke` was a literal in klaviyo's
+		// disconnect until auth.oauth.urls gathered every vendor address in one
+		// place, and a hook that cannot see its own manifest would have forced it
+		// back. Callers never have to know to pass it.
+		return { outcome : OUTCOMES.answered, result : await hook({ ...args, manifest }) };
 
 	} catch ( error ) {
 
@@ -1766,22 +3197,27 @@ const redactSettings = ({ slug, settings }) => {
 // dropped rather than carried forward as keys that look supported.
 const publicConnectionKeys = Object.freeze([
 	'actions',
-	'category',
-	'confirm',
+	// API-COMPOSED, not manifest-declared: the api's resolve() builds it from
+	// auth.type, content.redirect and the manifest's 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
+	// composed object from every response and broke all three.
 	'connect',
+	// EVERYTHING A MERCHANT READS, in one key: confirm, description, errors,
+	// excerpt, guide, and any vendor redirect copy.
+	'content',
 	'createdAt',
+	// The connection DOCUMENT's own errors array — scope-drift entries written by
+	// drawbridge-sync. NOT the manifest's error copy, which is content.errors:
+	// the document is spread OVER the resolved manifest downstream, so the two
+	// sharing this key means the array silently wins.
 	'errors',
-	'description',
-	'excerpt',
 	'fields',
 	'group',
 	'id',
 	'image',
-	// The reason a connected vendor still is not usable — a Klaviyo grant with no
-	// list chosen. Public because the card that shows Pending has to say why.
-	'incomplete',
-	'label',
-	'setup',
+
 	'settings',
 	'shop',
 	'slug',
@@ -1821,7 +3257,12 @@ const projectConnection = ( record ) => {
 // never reach the output under that name: the connection DOCUMENT's own
 // `settings` is spread over this downstream, and two different things sharing a
 // key is how a redaction quietly stops applying.
-const resolveConnection = ( item, data ) => {
+// `env` reaches a function field as its SECOND argument, so a manifest can name
+// a deployment's variables without reading process.env itself — the same reason
+// auth.oauth.client names them rather than holding them. A published package
+// that reads its consumer's environment is one that behaves differently
+// depending on who imported it.
+const resolveConnection = ( item, data, env = {} ) => {
 
 	if( ! item ) return item;
 
@@ -1830,10 +3271,10 @@ const resolveConnection = ( item, data ) => {
 			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'requires', 'steps', 'supports' ].includes( key ) )
 			.map( ( [ key, value ] ) => [
 				key,
-				( typeof value === 'function' ? value( data ) : value )
+				( typeof value === 'function' ? value( data, env ) : value )
 			] )
 	);
 
 };
 
-export { AUTH_TYPES, CATEGORIES, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, accessToken, availableConnections, build, connectFields, connectionSteps, connections, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, refresh, resolveConnection, runHook, scopesMessage, stepQueues, tokenSettings };
+export { AUTH_TYPES, GROUPS, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, RETIRED, STATUSES, STEPS, STEP_TYPES, accessToken, authToken, availableConnections, build, catalogConnections, connectFields, connectionSteps, connections, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, resolveConnection, runHook, scopesMessage, stepLabels, stepQueues, tokenSettings };