@drawbridge/drawbridge-utils 0.0.121 → 0.0.125

package/dist/connections/index.d.ts

@@ -1,18 +1,18 @@
 import { authToken } from './oauth.js';
 export { consentUrl, pkcePair } from './oauth.js';
+import { toE164, detectCountry } from '../phone.js';
 import { request } from '../http.js';
 import { channels } from '../pricing.js';
-import crypto, { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
+import crypto, { createHash, createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
 import { customAlphabet } from 'nanoid';
 import { toCanonicalEmail } from '../email.js';
-import { toE164 } from '../phone.js';
 import { conversionRate } from '../plans.js';
 import { safeRequest } from '../safe-http.js';
+import 'libphonenumber-js';
 import '../billing.js';
 import '../transactions.js';
 import '@drawbridge/drawbridge-telemetry';
 import '../usage.js';
-import 'libphonenumber-js';
 import '../features.js';
 import '../index.js';
 import 'currency-codes';
@@ -610,8 +610,8 @@ const GROUPS = Object.freeze([ 'commerce', 'contacts', 'developer', 'messaging'
 //   authorize  the consent url
 //   token      the exchange/refresh url
 //   client     the NAMES of our own id and secret, never the values — keys into
-//              the credential map the provider collection answers (historically
-//              env var names, kept as the stable vocabulary)
+//              the credential map the provider collection answers, matching a
+//              provider field's `credential`
 //   redirect   our callback path — DECLARED, never derived from the slug. It is
 //              registered in the vendor's console and they refuse anything that
 //              does not byte-match, so it is a fact about someone else's records
@@ -776,6 +776,38 @@ var icon$4 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <path d="M166.04 261.805C180.228 259.107 195.528 261.893 207.581 269.971C218.512 277.079 226.908 288.136 230.604 300.657C234.835 314.103 233.614 329.124 227.485 341.788C220.097 356.875 205.782 368.543 189.317 372.089C173.957 375.652 157.089 372.386 144.304 363.103C132.971 355.295 124.912 342.989 121.891 329.581C118.943 316.636 120.725 302.656 127.002 290.938C134.699 275.951 149.503 264.933 166.046 261.811" fill="#1E1C1C"/>
 </svg>`;
 
+// ONE REQUEST SHAPE for every Attentive call, the way Klaviyo's file has one.
+// The path carries its own version — the segments picker is v2 and the
+// subscription writes are v1 — because Attentive versions per resource rather
+// than per API.
+const api$2 = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
+
+	const response = await fetcher( 'https://api.attentivemobile.com' + path, {
+		...( payload && { body : JSON.stringify( payload ) }),
+		headers : {
+			authorization : 'Bearer ' + token,
+			...( payload && { 'content-type' : 'application/json' })
+		},
+		method,
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ){
+
+		throw Object.assign(
+			new Error( 'Attentive refused the request (' + response.status + ')' ),
+			{ status : response.status }
+		);
+
+	}
+
+	// 202 ACCEPTED may carry a body (the bulk-segment job id) or nothing at all,
+	// and asking json() for an empty body throws — which would report a write
+	// Attentive accepted as a failed step. A body that will not parse answers null.
+	return response.json().catch( () => null );
+
+};
+
 // Attentive — SMS-first marketing, installed as a distributed Attentive app.
 //
 // EVERY VENDOR FACT BELOW IS CITED from docs.attentive.com (fetched 2026-09-01):
@@ -860,9 +892,10 @@ var attentive = {
 		// has to say so rather than let them believe otherwise.
 		confirm : 'Disconnecting removes Drawbridge\'s stored Attentive token. Attentive does not offer a way for us to revoke it, so remove the Drawbridge integration in Attentive as well if you want its access fully withdrawn. Your subscribers stay in both Attentive and Drawbridge — neither list is deleted.',
 		description : [
-			'Attentive is where your SMS marketing lives, and this connection is becoming the way your Drawbridge contacts sync into an Attentive segment.',
+			'Attentive is where your SMS marketing lives, and this connection syncs the contacts your campaigns collect into an Attentive segment — subscribed for marketing and added to the segment you choose.',
 			'You authorize Drawbridge from inside Attentive and can revoke that access there at any time. Drawbridge never sees or stores your Attentive password.',
-			'Subscriber syncing is not live yet, so connecting today does nothing except choose the segment it will use when it ships.'
+			'Anyone who has opted out in Drawbridge is sent to Attentive as an unsubscribe rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
+			'Attentive accepts these updates and applies them in the background, so a contact appears in your segment shortly after the sync rather than the instant it runs.'
 		],
 		excerpt : 'Sync your Drawbridge contacts into an Attentive segment.',
 		guide : [
@@ -882,7 +915,11 @@ var attentive = {
 			label : 'Attentive segment',
 			message : 'Contacts your campaigns collect are synced into this segment.',
 			hook : 'resources.audiences',
-			required : true
+			required : true,
+			// CONSUMED BY THE MEMBERSHIP CALL, not by the subscribe. Attentive's
+			// /v1/subscriptions takes no segment id — subscription and segment
+			// membership are two operations here — so contacts.sync makes both calls
+			// and this value is the externalId the second one carries.
 			// No `search : false` here, and that is a first: /v2/segments takes a
 			// `name` filter (partial match, cited above), so this picker searches
 			// the ACCOUNT — Klaviyo and Mailchimp can only match the fetched page.
@@ -896,17 +933,25 @@ var attentive = {
 	hooks : {
 
 		auth : {
-			// The exchange already yields the tokens, and Attentive documents no
-			// account-identity endpoint to enrich them with — Klaviyo's connect
-			// reads the account name back; this has nothing cited to read. The
-			// callback stores the tokens and skips enrichment on `unimplemented`.
 			// FALSE, NOT {}. `{}` means "supported, implemented in the repo with the
-			// dependencies", and nothing anywhere implements either of these —
-			// there is nothing for them to do. The exchange already yields the
-			// tokens and Attentive documents no account-identity endpoint to
-			// enrich them with, so connect has nothing to add; and they document
-			// no revocation endpoint at all, so disconnect has nothing to call.
-			// Recorded as a decision rather than left as an unkept promise.
+			// dependencies", and nothing anywhere implements either of these — there
+			// is nothing for them to do. They document no revocation endpoint at all,
+			// so disconnect has nothing to call. Recorded as a decision rather than
+			// left as an unkept promise.
+			//
+			// STILL FALSE AFTER LOOKING AGAIN, and this is the reason written down so
+			// nobody re-derives it. Klaviyo's connect reads the account name back so
+			// the card is not blank; Attentive's card stays blank. There IS an
+			// endpoint — GET https://api.attentivemobile.com/v1/me, Bearer, described
+			// on docs.attentive.com/pages/authentication/ as returning "information
+			// specific to your company" — but its RESPONSE SCHEMA is published
+			// nowhere we can read: the docs show the curl and no body. Reading
+			// `body.name` would be a guess, and a guess here fails at the worst
+			// moment, in the callback, after the merchant has already consented.
+			//
+			// A live token settles it in one call, alongside the three registration
+			// checks in the header. Until then the honest state is a blank field, not
+			// a hopeful one.
 			connect : false,
 			disconnect : false,
 			probe : false,
@@ -931,7 +976,154 @@ var attentive = {
 			}
 		},
 		commerce : false,
-		contacts : { remove : false, sync : false },
+
+		// The verb the contacts.sync step points at.
+		contacts : {
+
+			// Not yet. Suppression syncs an opt-out as unsubscribed, which is a
+			// different thing from erasing the subscriber — Attentive's deletion sits
+			// behind their privacy-request API, which is a different grant.
+			remove : false,
+
+			// TWO CALLS, BECAUSE ATTENTIVE HAS TWO IDEAS.
+			//
+			// Subscribing and being in a segment are NOT the same operation here —
+			// unlike Klaviyo, where a subscription is created against the list itself.
+			// /v1/subscriptions takes no segment id at all, so the segment a merchant
+			// picked on this connection can only be honoured by the bulk segment
+			// membership API:
+			//
+			//   subscribe   POST /v1/subscriptions
+			//               { user : { email, phone }, locale, subscriptionType } — the
+			//               docs require EITHER signUpSourceId OR (locale +
+			//               subscriptionType), and we hold no sign-up source. 202.
+			//
+			//   membership  POST /v2/bulk/segments/members
+			//               { externalId, members : [ { email, phone } ] }, 1-10,000
+			//               members, 202 with a batchJobId
+			//               (docs.attentive.com/reference/postbulksegmentmembers).
+			//
+			//   unsubscribe POST /v1/subscriptions/unsubscribe
+			//               { user, subscriptions : [ { type, channel } ] }. 202.
+			//
+			// EVERY ONE OF THEM ANSWERS 202 ACCEPTED, which means Attentive took the
+			// job, not that it ran — the same distinction the Shopify usage charge
+			// makes between a 202 and a charge. The message below says accepted, and
+			// must keep saying accepted.
+			sync : async ( { lead, settings, suppressed, token }, { fetcher } = {} ) => {
+
+				const segment = settings?.segment;
+
+				// status() already stops a connection reaching Active without a
+				// segment; this is the belt to that braces. A workflow saved before the
+				// segment was chosen must not silently write into nothing.
+				if( ! segment ) return { message : 'No Attentive segment is chosen for this connection.', skipped : true };
+
+				const email = lead?.canonical?.email?.value || lead?.email;
+
+				// E.164 OR NOTHING. Attentive requires it, and a national-format number
+				// is refused with the whole request — so an unparseable one is dropped
+				// and the email carries the sync instead.
+				const phone = toE164( lead?.canonical?.phone?.value || lead?.phone );
+
+				// Their `user` requires phone OR email. With neither there is nobody to
+				// subscribe, so this is a skip rather than a failure.
+				if( ! email && ! phone ) return { message : 'That lead has no email address or phone number to sync.', skipped : true };
+
+				const user = {
+					...( email && { email }),
+					...( phone && { phone })
+				};
+
+				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
+				//
+				// Omitting them means Attentive never learns they said no, so the
+				// merchant can import them from somewhere else and start texting 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.
+				//
+				// AND THE SEGMENT IS SKIPPED for them: adding someone who opted out to
+				// a marketing segment is the same mistake as omitting the opt-out,
+				// wearing the other hat.
+				if( suppressed ){
+
+					await api$2( '/v1/subscriptions/unsubscribe', {
+						fetcher,
+						method : 'POST',
+						payload : {
+							// One entry per channel we can actually name them by. MARKETING
+							// is the only type Drawbridge ever subscribed them to.
+							subscriptions : [
+								...( phone ? [ { channel : 'TEXT', type : 'MARKETING' } ] : [] ),
+								...( email ? [ { channel : 'EMAIL', type : 'MARKETING' } ] : [] )
+							],
+							user
+						},
+						token
+					});
+
+					return {
+						message : 'Attentive accepted an unsubscribe for this contact — they have opted out.',
+						response : { accepted : true, unsubscribed : true }
+					};
+
+				}
+
+				await api$2( '/v1/subscriptions', {
+					fetcher,
+					method : 'POST',
+					payload : {
+						// LOCALE, because we hold no signUpSourceId and the docs require
+						// one or the other. The country is READ OFF the number when there
+						// is one — libphonenumber knows it from the calling code — rather
+						// than assumed; only the fallback pair below is a default, and it
+						// is the one value here that no vendor document dictates.
+						//
+						// ponytail: en/US default. A `signUpSourceId` field on the
+						// connection is the upgrade — Attentive's sign-up sources carry
+						// the consent language, which is a better answer than any locale
+						// we can infer — and it replaces this branch entirely.
+						locale : {
+							country : ( phone && detectCountry( phone ) ) || 'US',
+							language : 'en'
+						},
+						subscriptionType : 'MARKETING',
+						user
+					},
+					token
+				});
+
+				// THE SEGMENT THE MERCHANT PICKED, which the subscribe above cannot
+				// carry. One member per call rather than a batch: this hook is one
+				// contact, and their endpoint takes 1-10,000.
+				const membership = await api$2( '/v2/bulk/segments/members', {
+					fetcher,
+					method : 'POST',
+					payload : {
+						externalId : segment,
+						members : [ user ]
+					},
+					token
+				});
+
+				return {
+					// ACCEPTED, NOT LIVE. Both writes answered 202, which means Attentive
+					// queued them — a merchant who reads "synced" and looks for the person
+					// in Attentive a second later has been told the wrong thing.
+					message : 'Attentive accepted this contact for the segment. Attentive processes these asynchronously, so it appears there shortly.',
+					response : {
+						accepted : true,
+						...( membership?.batchJobId && { batchJobId : membership.batchJobId })
+					}
+				};
+
+			}
+
+		},
 		email : false,
 		inbound : false,
 		lifecycle : false,
@@ -945,7 +1137,7 @@ var attentive = {
 			// show a picker quietly missing most of a real account. The response's
 			// only identifier is `externalId`, so an entry without one cannot be
 			// stored and is dropped.
-			audiences : async ( { cursor, limit = 100, search, token }, { fetcher = fetch } = {} ) => {
+			audiences : async ( { cursor, limit = 100, search, token }, { fetcher } = {} ) => {
 
 				const query = new URLSearchParams({
 					limit : String( Math.min( limit, 1000 ) ),
@@ -953,24 +1145,7 @@ var attentive = {
 					...( search?.value && { name : String( search.value ).trim() } )
 				});
 
-				const response = await fetcher(
-					'https://api.attentivemobile.com/v2/segments?' + query,
-					{
-						headers : { authorization : 'Bearer ' + token },
-						signal : AbortSignal.timeout( 15000 )
-					}
-				);
-
-				if( ! response.ok ){
-
-					throw Object.assign(
-						new Error( 'Attentive refused the request (' + response.status + ')' ),
-						{ status : response.status }
-					);
-
-				}
-
-				const body = await response.json();
+				const body = await api$2( '/v2/segments?' + query, { fetcher, token });
 
 				return {
 					items : ( body?.segments || [] )
@@ -994,33 +1169,83 @@ var attentive = {
 
 	},
 	icon: icon$4,
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen, and the only declaration of it.
+	// It lives beside `requires`, which names the same variables: the manifest
+	// says what it needs and this says how someone supplies it, so a credential
+	// cannot be required by a vendor that offers nowhere to enter it.
+	//
+	// `redact` marks a secret — never returned by the api, and blank on save means
+	// keep the stored value. `required` drives the live check.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'clientId', credential : 'ATTENTIVE_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
+			{ input : 'password', key : 'clientSecret', credential : 'ATTENTIVE_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
+		]
+	},
 	requires : [
 		'ATTENTIVE_OAUTH_CLIENT_ID',
 		'ATTENTIVE_OAUTH_CLIENT_SECRET'
 	],
 	slug : 'attentive',
-	// A consent with no segment chosen is authenticated and inert — the sync,
-	// when it ships, needs somewhere to put people.
+	// A consent with no segment chosen is authenticated and inert — the sync needs
+	// somewhere to put people — so the card says Pending rather than Active over
+	// nothing.
 	status : ( data ) => ( data?.settings?.segment ? data.status : 'pending' ),
-	// No steps: subscriber sync has not shipped, so this vendor contributes
-	// nothing to a workflow yet. An empty steps object is the honest declaration.
-	steps : {},
-	tasks : ( data ) => [
-		...( data?.settings?.segment
-			? []
-			: [
-				{
-					message : 'Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.',
-					title : 'Choose a segment'
-				}
-			]
-		),
-		{
-			message : 'Contact syncing to Attentive segments has not shipped yet. Nothing is being sent to Attentive right now.',
-			title : 'Subscriber sync not available yet',
-			type : 'warning'
+
+	steps : {
+
+		contacts : {
+
+			// A DECLARATION, not the work. The nesting IS the name: this is
+			// `step.contacts.sync`, the string a workflow document stores. Klaviyo and
+			// Mailchimp declare the same type — a step belongs to the capability, not
+			// to whoever implements it — and the connection on the step document is
+			// what says which vendor runs.
+			sync : ({ data }) => ({
+
+				hook : 'contacts.sync',
+
+				// NO ACCOUNT NAME TO INTERPOLATE, unlike Klaviyo: auth.connect is false
+				// because Attentive publishes no account-identity response we can read
+				// (see its comment), and settings.segment is an opaque externalId no
+				// merchant would recognise in a builder label.
+				key : 'Sync contact to Attentive',
+
+				queue : 'connection',
+
+				// Nothing for a merchant to configure on the step itself — the segment
+				// is chosen once on the connection. Declared empty rather than omitted,
+				// so "this step takes no settings" and "nobody thought about settings"
+				// stay different statements.
+				settings : {},
+
+				// BOTH triggers, for the same reason as Klaviyo: lead.insert alone only
+				// ever fires for someone with no history yet, and crossing into a
+				// segment is the other moment a contact is worth pushing.
+				triggers : [ 'lead.insert', 'segment.contact.add' ],
+
+				usage : { actions : 1 }
+
+			})
+
 		}
-	],
+
+	},
+	// WHY, in the merchant's words, and what to do about it.
+	// ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+	// is reconnecting — prompting "choose a segment" there asks the merchant to
+	// configure a grant that no longer exists. `pending` is exactly this task's
+	// moment: the grant is good and the segment is the missing half.
+	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.segment
+		? []
+		: [
+			{
+				message : 'Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.',
+				title : 'Choose a segment'
+			}
+		]
+	),
 	title : 'Attentive'
 };
 
@@ -1343,7 +1568,7 @@ var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <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"/>
+<path d="M360.002 127.523L323.694 108.282L284.949 178.498V321.596L322.924 391.749L359.394 372.79L326.225 311.52V188.73L360.002 127.523Z" fill="#0D1314"/>
 </g>
 <defs>
 <clipPath id="clip0_2115_2832">
@@ -1977,6 +2202,34 @@ var drawbridge = {
 	icon: icon$3,
 	// PRIVATE: never in the catalog, always available to the builder.
 	private : true,
+	// THE PLATFORM'S OWN SENDING CREDENTIALS — SendGrid, Twilio, and the internal
+	// HubSpot portal. No merchant ever sees these; they are what an admin types on
+	// the provider screen so that Drawbridge itself can send.
+	//
+	// They belong on THIS manifest because this is the connection that sends: the
+	// email, sms and segment hooks below are the only things that spend them, and
+	// a private connection is still where a vendor fact lives.
+	//
+	// UNLIKE every public vendor, none of these appear in `requires` — see the
+	// comment there. Availability and configuration are different questions, and a
+	// missing CRM token must not take every base workflow step away.
+	provider : {
+		fields : [
+			{ input : 'email', key : 'accountSender', credential : 'SENDGRID_FROM_ADDRESS', label : 'Account sender', message : 'Verification codes and security alerts send from here.', required : true },
+			{ input : 'password', key : 'apiKey', credential : 'SENDGRID_API_KEY', label : 'SendGrid API key', redact : true, required : true },
+			// NOT required. The CRM sync is best-effort internal tooling and no-ops
+			// without a token — requiring it would make the whole drawbridge provider
+			// read not-live over something no merchant ever sees.
+			{ input : 'password', key : 'hubspotToken', credential : 'HUBSPOT_ACCESS_TOKEN', label : 'HubSpot access token', message : 'Drawbridge\'s own CRM portal. Internal — no merchant sees this.', redact : true },
+			// Optional: SENDGRID_SEND_FROM_ADDRESS is not boot-required in sync
+			// either. Unset, it degrades to the account sender rather than
+			// refusing to start.
+			{ input : 'email', key : 'leadSender', credential : 'SENDGRID_SEND_FROM_ADDRESS', label : 'Lead sender', message : 'The default for lead-facing mail when a merchant has not verified their own domain.' },
+			{ input : 'text', key : 'smsFrom', credential : 'TWILIO_ACCOUNT_FROM', label : 'SMS number', required : true },
+			{ input : 'password', key : 'smsSid', credential : 'TWILIO_ACCOUNT_SID', label : 'Twilio account SID', redact : true, required : true },
+			{ input : 'password', key : 'smsToken', credential : 'TWILIO_AUTH_TOKEN', label : 'Twilio auth token', redact : true, required : true }
+		]
+	},
 	// NOTHING, and HUBSPOT_ACCESS_TOKEN in particular must not be here.
 	//
 	// `requires` gates AVAILABILITY: a name in it that is unset removes the whole
@@ -2130,11 +2383,11 @@ var drawbridge = {
 // 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"/>
+<rect width="500" height="500" fill="#FF4B32"/>
 <path d="M365.047 327.038H134.954V172.964H365.047L316.856 250.001L365.047 327.038Z" fill="#232121"/>
 </svg>`;
 
-const api = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
+const api$1 = async ( path, { fetcher = fetch, method = 'GET', payload, token } ) => {
 
 	const response = await fetcher( 'https://a.klaviyo.com/api' + path, {
 		...( payload && { body : JSON.stringify( payload ) }),
@@ -2350,7 +2603,7 @@ var klaviyo = {
 			// decided it, and asking again would be a question we can answer.
 			connect : async ( { tokens }, { fetcher } = {} ) => {
 
-				const body = await api( '/accounts', { fetcher, token : tokens.accessToken });
+				const body = await api$1( '/accounts', { fetcher, token : tokens.accessToken });
 
 				const account = body?.data?.[ 0 ];
 
@@ -2464,7 +2717,7 @@ var klaviyo = {
 				// exist on a single-address record.
 				const totals = contact?.totals || {};
 
-				const profile = await api( '/profiles/', {
+				const profile = await api$1( '/profiles/', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -2505,7 +2758,7 @@ var klaviyo = {
 				//
 				// `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/', {
+				await api$1( '/profile-subscription-bulk-create-jobs/', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -2586,7 +2839,7 @@ var klaviyo = {
 
 				while( next && audiences.length < limit && pages < 20 ){
 
-					const body = await api( next, { fetcher, token });
+					const body = await api$1( next, { fetcher, token });
 
 					for( const list of ( body?.data || [] ) ){
 
@@ -2633,6 +2886,16 @@ var klaviyo = {
 
 	},
 	icon: icon$2,
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen. Declared here rather than in a
+	// table in lib/providers.js, so a vendor's credentials sit beside the
+	// `requires` that names the same variables.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'clientId', credential : 'KLAVIYO_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
+			{ input : 'password', key : 'clientSecret', credential : 'KLAVIYO_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
+		]
+	},
 	requires : [
 		'KLAVIYO_OAUTH_CLIENT_ID',
 		'KLAVIYO_OAUTH_CLIENT_SECRET'
@@ -2700,7 +2963,11 @@ var klaviyo = {
 
 	},
 	// WHY, in the merchant's words, and what to do about it.
-	tasks : ( data ) => ( data?.settings?.list
+	// ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+	// is reconnecting — prompting "choose a list" there asks the merchant to
+	// configure a grant that no longer exists. `pending` is exactly this task's
+	// moment: the grant is good and the list is the missing half.
+	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.list
 		? []
 		: [
 			{
@@ -2740,6 +3007,54 @@ const base = ( dc ) => {
 
 };
 
+// ONE REQUEST SHAPE for the Marketing API, the way Klaviyo's file has one.
+//
+// Bearer, not Basic. Mailchimp's fundamentals doc states "API keys and OAuth 2
+// tokens can be used to make authenticated requests the same way", so one header
+// serves both — the Basic form this used under keys was never OAuth-compatible.
+//
+// The host comes from base( dc ) on every call rather than being captured once:
+// there is no fixed host, and a request assembled without the stored data centre
+// is a 404 nobody can read.
+const api = async ( path, { dc, fetcher = fetch, method = 'GET', payload, token } ) => {
+
+	const response = await fetcher( base( dc ) + path, {
+		...( payload && { body : JSON.stringify( payload ) }),
+		headers : {
+			authorization : 'Bearer ' + token,
+			...( payload && { 'content-type' : 'application/json' })
+		},
+		method,
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ){
+
+		throw Object.assign(
+			new Error( 'Mailchimp refused the request (' + response.status + ')' ),
+			{ status : response.status }
+		);
+
+	}
+
+	return response.json();
+
+};
+
+// THE MEMBER ID IS COMPUTED, not handed back: Mailchimp addresses a member by
+// "the MD5 hash of the lowercase version of the list member's email address".
+//
+// That is what makes PUT an UPSERT — the same person hashes to the same id, so a
+// resync updates rather than creating a second member — and it is why the
+// address is lowercased before hashing rather than after: Ada@Example.com and
+// ada@example.com are one subscriber to Mailchimp and would otherwise be two.
+//
+// MD5 is the vendor's choice and nothing here is authenticated by it; it is an
+// address, not a secret.
+const subscriberHash = ( email ) => createHash( 'md5' )
+	.update( String( email ).trim().toLowerCase() )
+	.digest( 'hex' );
+
 // Mailchimp — contact sync, not a sender.
 var mailchimp = {
 	// OAUTH 2, authorization code. Every url below is quoted from
@@ -2782,8 +3097,10 @@ var mailchimp = {
 	content : {
 		confirm : 'Disconnecting removes Drawbridge\'s stored Mailchimp access. You can also remove Drawbridge from the Authorized Apps page in your Mailchimp account. Your contacts stay in both Drawbridge and Mailchimp — neither list is deleted.',
 		description : [
-			'Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under 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 connecting today does nothing except choose the audience it will use when it ships.'
+			'Drawbridge no longer sends email through Mailchimp. Notification email now sends from Drawbridge itself, and verifying a domain under Messaging in your organization settings puts your own brand in the from line.',
+			'Connecting Mailchimp lets Drawbridge sync the contacts your campaigns collect into a Mailchimp audience, so the people who enter a giveaway can be marketed to alongside the rest of your list.',
+			'Anyone who has opted out in Drawbridge is synced as unsubscribed rather than omitted, so a person who asked not to be contacted stays suppressed in both systems instead of quietly reappearing.',
+			'Someone who unsubscribed inside Mailchimp keeps that choice: a resync only sets the status of a subscriber Mailchimp has never seen before.'
 		],
 		excerpt : 'Sync your Drawbridge contacts into a Mailchimp audience.',
 		guide : [
@@ -2869,7 +3186,89 @@ var mailchimp = {
 			token : authToken
 		},
 		commerce : false,
-		contacts : { remove : false, sync : false },
+
+		// The verb the contacts.sync step points at.
+		contacts : {
+
+			// Not yet. Suppression syncs an opt-out as unsubscribed, which is a
+			// different thing from deleting the member — and Mailchimp's own delete is
+			// permanent, so the address can never be re-added.
+			remove : false,
+
+			// PUT /lists/{list_id}/members/{subscriber_hash} — an UPSERT, which is
+			// why there is no create-or-update branch here. Quoted from Mailchimp's
+			// Marketing API reference for the list-members resource.
+			sync : async ( { lead, settings, suppressed, token }, { fetcher } = {} ) => {
+
+				const audience = settings?.audience;
+
+				// status() already stops a connection reaching Active without an
+				// audience; this is the belt to that braces. A workflow saved before
+				// the audience was chosen must not silently write into nothing.
+				if( ! audience ) return { message : 'No Mailchimp audience is chosen for this connection.', skipped : true };
+
+				const email = lead?.canonical?.email?.value || lead?.email;
+
+				// A Mailchimp member IS an email address — there is no other identity
+				// to write, so a lead without one is skipped rather than failed.
+				if( ! email ) return { message : 'That lead has no email address to sync.', skipped : true };
+
+				const hash = subscriberHash( email );
+
+				// SUPPRESSED PEOPLE ARE SYNCED AS UNSUBSCRIBED, NEVER OMITTED.
+				//
+				// Omitting them means Mailchimp 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.
+				//
+				// STATUS_IF_NEW EVERYWHERE, `status` ONLY TO SUPPRESS, and the
+				// asymmetry is the whole point. status_if_new applies to a member being
+				// CREATED and is ignored for one that already exists, so a resync
+				// cannot overwrite what a subscriber themselves chose — someone who
+				// unsubscribed inside Mailchimp stays unsubscribed. An opt-out is the
+				// one thing allowed to overwrite, because it travels in the direction
+				// that protects the person; so suppression sets `status` outright, and
+				// sets status_if_new alongside it because the upsert leg still needs a
+				// status for a member Mailchimp has never seen.
+				const member = await api( '/lists/' + audience + '/members/' + hash, {
+					dc : settings?.dc,
+					fetcher,
+					method : 'PUT',
+					payload : {
+						email_address : email,
+						// FNAME ONLY. Unlike Klaviyo, Mailchimp's custom fields are not
+						// schemaless — a merge tag that does not exist on the audience is
+						// refused, taking the whole request with it — and FNAME is one of
+						// the two tags every audience is created with. The Drawbridge
+						// totals Klaviyo receives cannot travel until something registers
+						// merge fields on the chosen audience, which is lifecycle.register's
+						// job and is not built.
+						...( lead?.name && { merge_fields : { FNAME : String( lead.name ).trim().split( /\s+/ )[ 0 ] } }),
+						...( suppressed && { status : 'unsubscribed' }),
+						status_if_new : suppressed ? 'unsubscribed' : 'subscribed'
+					},
+					token
+				});
+
+				return {
+					// Merged into `context` for later steps in this run.
+					context : { mailchimpMemberId : member?.id || hash },
+					message : suppressed
+						? 'Synced to Mailchimp as unsubscribed — this contact has opted out.'
+						: 'Synced to the Mailchimp audience.',
+					// Recorded on the run for support to read back, not a write
+					// instruction — the hook has already written what it needed to.
+					response : { mailchimpMemberId : member?.id || hash }
+				};
+
+			}
+
+		},
 		// 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
@@ -2889,36 +3288,16 @@ var mailchimp = {
 			// 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, limit = 100, search, settings, token }, { fetcher = fetch } = {} ) => {
-
-				// Bearer, not Basic. Mailchimp's fundamentals doc states "API keys and
-				// OAuth 2 tokens can be used to make authenticated requests the same
-				// way", so one header serves both — the Basic form this used under
-				// keys was never OAuth-compatible.
-				const dc = settings?.dc;
+			audiences : async ( { cursor, limit = 100, search, settings, token }, { fetcher } = {} ) => {
 
 				const count = Math.min( limit, 1000 );
 				const offset = Number( cursor || 0 );
 
-				const response = await fetcher(
-					base( dc ) + '/lists?count=' + count + '&offset=' + offset + '&fields=lists.id,lists.name,total_items',
-					{
-						headers : { authorization : 'Bearer ' + token },
-						signal : AbortSignal.timeout( 15000 )
-					}
+				const body = await api(
+					'/lists?count=' + count + '&offset=' + offset + '&fields=lists.id,lists.name,total_items',
+					{ dc : settings?.dc, fetcher, token }
 				);
 
-				if( ! response.ok ){
-
-					throw Object.assign(
-						new Error( 'Mailchimp refused the request (' + response.status + ')' ),
-						{ status : response.status }
-					);
-
-				}
-
-				const body = await response.json();
-
 				const audiences = ( body?.lists || [] ).map( ( list ) => ({ id : list.id, title : list?.name || list.id }) );
 
 				// Mailchimp's /lists takes no name filter, so a term is matched against
@@ -2953,6 +3332,15 @@ var mailchimp = {
 		webhook : false
 	},
 	icon: icon$1,
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen, beside the `requires` naming the
+	// same variables.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'clientId', credential : 'MAILCHIMP_OAUTH_CLIENT_ID', label : 'Client ID', required : true },
+			{ input : 'password', key : 'clientSecret', credential : 'MAILCHIMP_OAUTH_CLIENT_SECRET', label : 'Client secret', redact : true, required : true }
+		]
+	},
 	// The OAuth client this deployment registered. Without both, the vendor drops
 	// out of availableConnections rather than offering a Connect button that
 	// cannot complete.
@@ -2961,32 +3349,70 @@ var mailchimp = {
 		'MAILCHIMP_OAUTH_CLIENT_SECRET'
 	],
 	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.
+	// A grant with no audience chosen is authenticated and useless — the sync has
+	// nowhere to put anyone — so the card must say Pending rather than Active over
+	// nothing. 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.
 	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 : ( 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',
-			type : 'warning'
+
+	steps : {
+
+		contacts : {
+
+			// A DECLARATION, not the work. It names the hook that does the work, and
+			// the nesting IS the name: this is `step.contacts.sync`, the string a
+			// workflow document stores. Klaviyo and Attentive declare the same type —
+			// a step belongs to the capability, not to whoever implements it — and the
+			// connection on the step document is what says which vendor runs.
+			sync : ({ data }) => ({
+
+				hook : 'contacts.sync',
+
+				// NO ACCOUNT NAME TO INTERPOLATE, unlike Klaviyo. Mailchimp's
+				// auth.connect deliberately stores only the data centre (a test pins
+				// that), and settings.audience is an opaque list id no merchant would
+				// recognise in a builder label — so the label names the vendor rather
+				// than showing a string like a1b2c3d4e5.
+				key : 'Sync contact to Mailchimp',
+
+				queue : 'connection',
+
+				// Nothing for a merchant to configure on the step itself — the audience
+				// is chosen once on the connection. Declared empty rather than omitted,
+				// so "this step takes no settings" and "nobody thought about settings"
+				// stay different statements.
+				settings : {},
+
+				// BOTH triggers, for the same reason as Klaviyo: lead.insert alone only
+				// ever fires for someone with no history yet, and crossing into a
+				// segment is the other moment a contact is worth pushing.
+				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.
+	// ONLY FOR A LIVE GRANT. A disconnected or errored connection's next step
+	// is reconnecting — prompting "choose a audience" there asks the merchant to
+	// configure a grant that no longer exists. `pending` is exactly this task's
+	// moment: the grant is good and the audience is the missing half.
+	tasks : ( data ) => ( ! [ 'active', 'pending' ].includes( data?.status ) || data?.settings?.audience
+		? []
+		: [
+			{
+				message : 'Choose which Mailchimp audience your contacts should sync into. Until you do, nothing is being synced.',
+				title : 'Choose an audience'
+			}
+		]
+	),
 	title : 'Mailchimp'
 };
 
@@ -2997,10 +3423,9 @@ var mailchimp = {
 // 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="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"/>
-<path d="M258.993 193.019L249.103 230.052C249.103 230.052 238.079 225.023 225 225.85C205.833 227.059 205.628 239.171 205.824 242.21C206.865 258.756 250.376 262.381 252.821 301.171C254.745 331.688 236.656 352.574 210.592 354.21C179.313 356.19 162.089 337.711 162.089 337.711L168.716 309.472C168.716 309.472 186.052 322.569 199.921 321.686C208.993 321.119 212.228 313.738 211.903 308.514C210.536 286.921 175.102 288.185 172.862 252.695C170.985 222.811 190.57 192.554 233.803 189.821C250.46 188.762 258.993 193.028 258.993 193.028" fill="white"/>
+<rect width="500" height="500" fill="#95C049"/>
+<path d="M292.997 147.633C292.997 147.633 289.98 148.495 285.023 150.004C284.161 147.202 282.868 143.969 281.144 140.521C275.54 129.744 267.134 123.925 257.22 123.925C256.574 123.925 255.927 123.925 255.065 124.141C254.849 123.71 254.418 123.494 254.203 123.063C249.892 118.322 244.289 116.166 237.607 116.382C224.676 116.813 211.744 126.081 201.399 142.676C194.071 154.314 188.468 168.97 186.959 180.393C172.088 184.919 161.743 188.152 161.527 188.367C153.984 190.738 153.768 190.954 152.906 198.066C151.613 203.454 132 355.4 132 355.4L294.937 383.633V147.202C294.075 147.418 293.429 147.418 292.997 147.633ZM255.281 159.271C246.66 161.858 237.176 164.875 227.909 167.677C230.495 157.547 235.668 147.418 241.702 140.736C244.073 138.365 247.306 135.564 250.97 133.839C254.634 141.598 255.496 152.159 255.281 159.271ZM237.823 125.003C240.84 125.003 243.427 125.649 245.582 126.943C242.133 128.667 238.685 131.469 235.452 134.702C227.262 143.538 221.012 157.332 218.426 170.479C210.667 172.85 202.908 175.22 195.796 177.376C200.322 156.901 217.779 125.649 237.823 125.003ZM212.607 243.542C213.469 257.335 249.892 260.353 252.048 292.897C253.556 318.545 238.47 336.002 216.701 337.295C190.407 339.02 175.967 323.502 175.967 323.502L181.571 299.794C181.571 299.794 196.011 310.786 207.649 309.924C215.193 309.493 217.995 303.242 217.779 298.932C216.701 280.828 186.959 281.905 185.019 252.163C183.295 227.377 199.675 202.161 235.883 199.79C249.892 198.928 257.005 202.377 257.005 202.377L248.815 233.412C248.815 233.412 239.547 229.102 228.555 229.964C212.607 231.041 212.391 241.171 212.607 243.542ZM263.902 156.685C263.902 150.219 263.039 140.952 260.022 133.193C269.936 135.133 274.678 146.124 276.833 152.806C272.954 153.883 268.643 155.176 263.902 156.685Z" fill="white"/>
+<path d="M300.325 382.771L368 365.96C368 365.96 338.904 169.185 338.689 167.892C338.473 166.599 337.396 165.737 336.318 165.737C335.24 165.737 316.274 165.306 316.274 165.306C316.274 165.306 304.636 154.099 300.325 149.788V382.771Z" fill="white"/>
 </svg>`;
 
 // THE SHARED HALF OF inbound.verify.
@@ -3222,7 +3647,7 @@ var shopify = {
 		// the App Store listing, and the dashboard must never imply a store can be
 		// linked from inside it.
 		redirect : {
-			env : 'SHOPIFY_APP_LISTING_URL',
+			credential : 'SHOPIFY_APP_LISTING_URL',
 			title : 'View on the Shopify App Store'
 		}
 	},
@@ -4259,6 +4684,19 @@ var shopify = {
 			: undefined;
 
 	},
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, as opposed to a merchant's —
+	// what an admin types on the provider screen. The four names below are exactly
+	// what `requires` gates on, which is the point of declaring them together: a
+	// name required by the manifest and enterable nowhere is a vendor that can
+	// never go live from the admin screen.
+	provider : {
+		fields : [
+			{ input : 'text', key : 'apiKey', credential : 'SHOPIFY_API_KEY', label : 'API key', required : true },
+			{ input : 'password', key : 'apiSecret', credential : 'SHOPIFY_API_SECRET', label : 'API secret', redact : true, required : true },
+			{ input : 'text', key : 'appHandle', credential : 'SHOPIFY_APP_HANDLE', label : 'App handle', required : true },
+			{ input : 'text', key : 'listingUrl', credential : 'SHOPIFY_APP_LISTING_URL', label : 'App listing URL', required : true }
+		]
+	},
 	// 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
@@ -4577,7 +5015,12 @@ var webhook = {
 	// pressing Connect will do; afterwards it states the verification the
 	// merchant's own endpoint has to perform, because a signed payload nobody
 	// checks is an unsigned payload.
-	tasks : ( { settings } ) => ( settings?.secret
+	// The connect prompt only where connecting is not already the card's whole
+	// story: a disconnected or errored document renders a Connect action itself,
+	// and a task repeating it talks over the button.
+	tasks : ( { settings, status } = {} ) => ( [ 'disconnected', 'error' ].includes( status )
+		? []
+		: settings?.secret
 		? [
 			{
 				message : 'Compute HMAC-SHA256( secret, body ) and compare against the X-Drawbridge-Signature header to confirm each payload.',
@@ -4591,7 +5034,7 @@ var webhook = {
 				title : 'Webhook signing'
 			}
 		]
-	),
+	 ),
 	title : 'Webhooks'
 };
 
@@ -4743,6 +5186,39 @@ const build = ( manifest ) => {
 
 	}
 
+	// DRAWBRIDGE'S OWN CREDENTIALS for this vendor, if it has any. A connection
+	// with no third party behind it — webhook — declares no block at all, which is
+	// what keeps it off the provider screen.
+	//
+	// Every field is checked harder than a merchant field: it must be editable
+	// (an admin cannot type into a read-only descriptor, and a credential nobody
+	// can enter is a vendor that can never go live), and a `password` MUST be
+	// redacted. That last one is a SECURITY BOUNDARY rather than tidiness —
+	// providerFields is what the api's redaction derives from, so a password field
+	// that forgot `redact : true` is a platform secret handed back over the wire
+	// to every admin screen that asks.
+	for( const field of manifest.provider?.fields || [] ){
+
+		if( ! field?.key || ! field?.label ){
+
+			throw new Error( manifest.slug + ' declares a provider field with no key or label' );
+
+		}
+
+		if( ! INPUTS.includes( field.input ) ){
+
+			throw new Error( manifest.slug + '.provider.' + field.key + ' needs an input the admin form can render — one of ' + INPUTS.join( ', ' ) );
+
+		}
+
+		if( field.input === 'password' && ! field.redact ){
+
+			throw new Error( manifest.slug + '.provider.' + field.key + ' is a password and must declare redact : true — the api would hand the value back' );
+
+		}
+
+	}
+
 	// THE ICON RIDES WITH THE MANIFEST, so a vendor cannot name an asset nobody
 	// added — which is what the old arrangement allowed, with the markup in one
 	// repo and the file in another.
@@ -5037,36 +5513,41 @@ const connections = Object.freeze({
 	webhook : build( webhook )
 });
 
-// A step type belongs to exactly one vendor.
+// A STEP TYPE MAY BE SHARED, BUT NOT ITS QUEUE.
 //
-// This is checked because the current naming HIDES the problem rather than
-// solving it: every commerce step is namespaced by vendor
-// (step.shopify.customer.insert), so a collision is impossible only for as long
-// as that holds. The moment a capability is named for what it does rather than
-// who does it — step.commerce.customer.insert, which is where this should go —
-// two vendors declaring it would silently collapse into one entry in stepQueues
-// and one of them would route nowhere.
+// A step type belongs to the CAPABILITY rather than to whoever implements it —
+// that is why step.shopify.* became step.commerce.*, and why Klaviyo, Mailchimp
+// and Attentive all declare step.contacts.sync. Sharing the name is the intent,
+// and the vendor is carried on the step DOCUMENT (its connection), not in the
+// type string.
 //
-// Fail at import instead. When the neutral names land, this is the guard that
-// makes the ambiguity visible on the first line of the first test run.
+// What must not be shared is the ROUTE. stepQueues is { type : queue }, so two
+// vendors declaring one type with different queues collapse into a single entry
+// and whichever loses is enqueued nowhere — a workflow that accepts the step and
+// silently never runs it. That is the real failure this guard was written for;
+// the ownership rule was a proxy for it that also refused the case it was
+// designed to anticipate.
 ( () => {
 
-	const owners = {};
+	const routes = {};
 
 	for( const [ slug, manifest ] of Object.entries( connections ) ){
 
-		for( const [ name ] of leaves( manifest.steps ) ){
+		for( const [ name, step ] of leaves( manifest.steps ) ){
 
 			const type = 'step.' + name;
+			const queue = step({})?.queue;
 
+			if( routes[ type ] && routes[ type ].queue !== queue ){
 
-			if( owners[ type ] ){
-
-				throw new Error( 'Step ' + type + ' is declared by both ' + owners[ type ] + ' and ' + slug );
+				throw new Error(
+					'Step ' + type + ' routes to ' + routes[ type ].queue + ' for ' + routes[ type ].slug
+					+ ' and ' + queue + ' for ' + slug + ' — one of them would be enqueued nowhere'
+				);
 
 			}
 
-			owners[ type ] = slug;
+			routes[ type ] = { queue, slug };
 
 		}
 
@@ -5409,7 +5890,11 @@ const resolveConnection = ( item, data, env = {} ) => {
 
 	return Object.fromEntries(
 		Object.entries( item )
-			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'requires', 'steps', 'supports' ].includes( key ) )
+			// `provider` is in the list for a different reason than the rest: it is
+			// PLATFORM configuration — which credentials an admin types in for this
+			// vendor — and no merchant-facing resolution has any business carrying
+			// it, even as bare descriptors.
+			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'provider', 'requires', 'steps', 'supports' ].includes( key ) )
 			.map( ( [ key, value ] ) => [
 				key,
 				( typeof value === 'function' ? value( data, env ) : value )