@drawbridge/drawbridge-utils 0.0.105 → 0.0.107

package/dist/connections/index.d.cts

@@ -0,0 +1,1228 @@
+export { consentUrl, exchange, pkcePair, refresh } from './oauth.cjs';
+import 'node:crypto';
+
+// THE HOOK VOCABULARY. Closed, and every connection answers all of it.
+//
+// A vendor does not get to be silent about a hook. It declares `true` where it
+// implements one and `false` where it does not, and `build()` rejects a manifest
+// that leaves any entry out. That is what makes the connections COMPARABLE: the
+// table of vendors against hooks has no empty cells, so "does Shopify do
+// catalog.products" is answered by the manifest rather than by reading sync.
+//
+// The alternative — carry only the hooks you implement, and let the caller
+// filter — is what drawbridge-growth does, and it drifts: 26 of its 35 hooks are
+// implemented by exactly one vendor, and nothing tells you whether the other
+// twelve considered that hook and declined or never knew it existed.
+//
+// `false` is a DECISION, recorded. It is not the same as a hook that is
+// supported and returned nothing, and it is not the same as a connection that
+// is not currently connected. All three are different answers to "why is there
+// no data", and an operator debugging an empty result needs to tell them apart.
+const HOOKS = Object.freeze({
+
+	// Proving and holding the credential.
+	auth : Object.freeze([
+		// Accept what the merchant supplied — a form submission or an OAuth
+		// callback — and store what is needed to call the vendor later.
+		'connect',
+		// Is the stored credential still good? Answered by the cheapest real call
+		// the vendor offers, never by inspecting what we stored: a key that was
+		// revoked at the vendor still looks perfect in our database.
+		'probe',
+		// Which permissions we asked for and no longer hold. Distinct from probe:
+		// the credential can be valid and the grant still be too narrow.
+		'scopes',
+		// Revoke at the vendor and drop what we hold.
+		'disconnect'
+	]),
+
+	// What happens around connecting and disconnecting, beyond the credential.
+	lifecycle : Object.freeze([
+		// Post-connect setup: register the vendor's webhooks, create the system
+		// workflows that describe them.
+		'register',
+		// Re-pull vendor state we mirror, after a reconnect or on a schedule.
+		'rehydrate',
+		// Undo `register` — deregister webhooks, release anything reserved.
+		'cleanup'
+	]),
+
+	// Receiving from the vendor.
+	inbound : Object.freeze([
+		// Prove the request came from the vendor. Signature schemes differ per
+		// vendor, which is exactly why this is a hook and not one shared function.
+		'verify',
+		// Name the event, from wherever this vendor puts it.
+		'topic',
+		// Do the work the event implies.
+		'handle'
+	]),
+
+	// 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([
+		'products',
+		// Shopify folds price into the product variant; Stripe makes Price a
+		// first-class object beside Product. Declared so a vendor that separates
+		// them has somewhere to answer.
+		'prices',
+		'promotions'
+	])
+
+});
+
+// Flat 'domain.verb' names, which is how a manifest declares support and how a
+// caller asks for one.
+const HOOK_NAMES = Object.freeze(
+	Object.entries( HOOKS ).flatMap( ( [ domain, verbs ] ) => verbs.map( ( verb ) => domain + '.' + verb ) )
+);
+
+// Why a hook produced nothing. Returned by the call surface rather than an empty
+// array, because "not supported", "not connected" and "supported, found nothing"
+// lead to three different next actions and collapsing them loses the one that
+// matters.
+const OUTCOMES = Object.freeze({
+	answered : 'answered',
+	disconnected : 'disconnected',
+	failed : 'failed',
+	// Declared supported, implemented in a consumer rather than in this package —
+	// sync owns the step handlers and lifecycle jobs. Different from unsupported,
+	// which means the vendor cannot do it at all.
+	unimplemented : 'unimplemented',
+	unsupported : 'unsupported'
+});
+
+// HOW A VENDOR IS CONNECTED. Four kinds, because the merchant's experience of
+// each is genuinely different and the dashboard renders from this:
+//
+//   keys       they paste a credential in                 (Mailchimp today)
+//   oauth      they consent at the vendor and come back   (Mailchimp next, Klaviyo)
+//   install    they install an app at the vendor          (Shopify)
+//   generated  Drawbridge mints it, nobody types anything (Webhooks)
+//
+// `install` is separate from `oauth` on purpose. Both end in a token, but the
+// 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' ]);
+
+// 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
+// spelled right is a filter chip that silently shows nothing.
+const CATEGORIES = 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.
+//
+//   authorize  the consent url
+//   token      the exchange/refresh url
+//   client     the ENV VAR NAMES holding our own id and secret, never the values
+//   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
+//              rather than a string this code gets to compute.
+//   scopes     what we ask for
+//   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' ]);
+
+// 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
+// list means a vendor declares `kind : "toggle"`, the form falls through to a
+// text box, and a merchant types the word true into it.
+//
+//   text      a line of text
+//   password  a secret — masked, and never returned once stored
+//   email     text, validated as an address
+//   url       text, validated as a url
+//   number    a numeric field
+//   textarea  multi-line, for things like an allow-list or a template
+//   select    a fixed choice; the field must also declare `options`
+//   checkbox  on or off
+//
+// A field with NO input is not editable at all: it is read-only on the page,
+// which is how a generated secret and an installed store domain are shown.
+const INPUTS = Object.freeze([
+	'checkbox',
+	'email',
+	'number',
+	'password',
+	'select',
+	'text',
+	'textarea',
+	'url'
+]);
+
+// 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$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="white"/>
+<path d="M365.047 327.038H134.954V172.964H365.047L316.856 250.001L365.047 327.038Z" fill="#232121"/>
+</svg>`;
+
+// Klaviyo — contact and event sync, over OAuth.
+//
+// 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.
+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.
+	auth : {
+		oauth : {
+			authorize : 'https://a.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.
+			redirect : '/api/connection/klaviyo/callback',
+			// 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'
+		},
+		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 : {
+		errors : {
+			denied : 'The Klaviyo authorization was declined, so nothing was connected.',
+			invalid : 'We couldn\'t complete the Klaviyo connection. Try connecting again.'
+		}
+	},
+	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.',
+	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'
+		}
+	],
+	icon: icon$3,
+	label : 'klaviyo',
+	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.prices' : false,
+		'catalog.products' : false,
+		'catalog.promotions' : false,
+		'inbound.handle' : false,
+		'inbound.topic' : false,
+		'inbound.verify' : false,
+		'lifecycle.cleanup' : false,
+		'lifecycle.register' : false,
+		'lifecycle.rehydrate' : false
+	},
+	title : 'Klaviyo'
+};
+
+// Mailchimp, 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="#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"/>
+</svg>`;
+
+// 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
+	// rather than researched again later:
+	//
+	//   authorize  https://login.mailchimp.com/oauth2/authorize
+	//   token      https://login.mailchimp.com/oauth2/token
+	//   metadata   https://login.mailchimp.com/oauth2/metadata
+	//
+	// The metadata call is Mailchimp's quirk and cannot be skipped: the access
+	// token alone is not enough to call the Marketing API, because every account
+	// lives behind a data-centre prefix (us1, us19...) that only that call
+	// returns and every subsequent request needs in its host. No PKCE.
+	//
+	// Switching is filling in auth.oauth and moving the apiKey field out. It is
+	// still a publish -- a manifest change always is -- but a value change
+	// rather than a shape one.
+	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.',
+	feature : 'organization:connection:mailchimp',
+	fields : [
+		{
+			input : 'password',
+			key : 'apiKey',
+			label : 'Mailchimp API key',
+			message : 'Your Mailchimp API key',
+			placeholder : '••••••••••••••••••••••••••••••••-us1',
+			redact : true,
+			required : true
+		}
+	],
+	icon: icon$2,
+	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.prices' : false,
+		'catalog.products' : false,
+		'catalog.promotions' : false,
+		'inbound.handle' : false,
+		'inbound.topic' : 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',
+	// 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 : () => [
+		{
+			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'
+		}
+	],
+	title : 'Mailchimp'
+};
+
+// Shopify, 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$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="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"/>
+</svg>`;
+
+// Shopify — installed from the App Store, never connected with keys.
+var shopify = {
+	// INSTALL, not oauth. The grant is an OAuth grant, but the merchant never
+	// sees a consent screen we sent them to -- they start at the App Store, and
+	// the install completes inside Shopify admin without redirecting back. A
+	// Connect button here would be lying about where connecting happens.
+	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.
+	//
+	// 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 : {
+		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.'
+		},
+		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.',
+	feature : 'organization:connection:shopify',
+	fields : [
+		{
+			// `shop` on the connection record wins when present — it is written by
+			// the install, while settings.domain is the stored copy.
+			from : 'shop',
+			key : 'domain',
+			label : 'Store domain'
+		}
+	],
+	group : 'ecommerce',
+	// WHERE THIS VENDOR PUTS THINGS ON AN INBOUND REQUEST. Header names are facts
+	// about someone else's product, so they belong beside the rest of the vendor
+	// rather than as string literals in a route — which is where they were, and
+	// is why a second inbound vendor meant a second route file.
+	//
+	// `signature` describes an HMAC scheme the shared verifier can run: hash the
+	// raw body with the named secret and compare, constant-time, against the
+	// header. Vendors whose scheme is not that shape — Stripe signs a timestamped
+	// payload — declare no signature block and implement inbound.verify instead.
+	// That is why verify is a hook and not config.
+	inbound : {
+		headers : {
+			id : 'x-shopify-webhook-id',
+			shop : 'x-shopify-shop-domain',
+			signature : 'x-shopify-hmac-sha256',
+			topic : 'x-shopify-topic'
+		},
+		signature : {
+			algorithm : 'sha256',
+			encoding : 'base64',
+			secret : 'SHOPIFY_API_SECRET'
+		}
+	},
+	icon: icon$1,
+	label : 'shopify',
+	// 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
+	// connection AND every step below it.
+	requires : [
+		'SHOPIFY_API_KEY',
+		'SHOPIFY_API_SECRET',
+		'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.prices' : false,
+		'catalog.products' : true,
+		'catalog.promotions' : true,
+		'inbound.handle' : true,
+		'inbound.topic' : 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',
+	// 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.
+	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' }
+					},
+					type : 'object'
+				}
+			},
+			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
+		},
+		'step.connection.token.refresh' : {
+			key : 'Shopify Token Refresh',
+			queue : 'connection',
+			system : true
+		}
+	},
+	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`.
+var webhook = {
+	// Connecting GENERATES the secret rather than storing one the merchant typed,
+	// so the buttons say what actually happens.
+	actions : {
+		create : 'Connect',
+		update : 'Regenerate secret'
+	},
+	// GENERATED. There is no third party and nothing to authenticate against --
+	// connecting mints a secret rather than proving a credential.
+	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.',
+	feature : 'organization:connection:webhook',
+	fields : [
+		{
+			// No `input`: Drawbridge generates this, the merchant never types it.
+			// No `redact` either — it is shared with the merchant's own endpoint
+			// rather than being a third-party credential, so it round-trips for
+			// them to copy and configure.
+			copy : true,
+			key : 'secret',
+			label : 'Signing secret'
+		}
+	],
+	// 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,
+	label : 'webhook',
+	// Gated on the encryption secret: without it the signing secret could not be
+	// stored safely, so the connection must not be offered at all.
+	requires : [ 'ENCRYPT_CONNECTION_SECRET' ],
+	// 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.
+	supports : {
+		'auth.connect' : true,
+		'auth.disconnect' : true,
+		'auth.probe' : false,
+		'auth.scopes' : false,
+		'catalog.prices' : false,
+		'catalog.products' : false,
+		'catalog.promotions' : false,
+		'inbound.handle' : false,
+		'inbound.topic' : 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',
+	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' ]
+		}
+	},
+	// The card the connection page raises. Before connecting it explains what
+	// 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
+		? [
+			{
+				message : 'Compute HMAC-SHA256( secret, body ) and compare against the X-Drawbridge-Signature header to confirm each payload.',
+				title : 'Requests must be verified',
+				type : 'warning'
+			}
+		]
+		: [
+			{
+				message : 'Connect to generate a signing secret. Drawbridge signs every webhook it sends with it.',
+				title : 'Webhook signing'
+			}
+		]
+	),
+	title : 'Webhooks'
+};
+
+// Every connection, one file each, and this is the whole registry.
+//
+// It lives in utils rather than in the api because BOTH sides need it and they
+// cannot import each other. The api renders the catalog, validates step settings
+// and redacts stored values; sync routes a step to a queue and runs it. Before
+// this, adding one vendor meant editing nine places across two repos and a third
+// for the form, and the two halves could disagree — a step the api would happily
+// persist that sync had no route for is a workflow that silently never runs.
+//
+// WHAT LIVES HERE is everything true about a vendor regardless of environment:
+// its copy, the fields it stores, and the steps it contributes. WHAT DOES NOT is
+// anything that reads process.env — image origins, OAuth redirect urls, whether
+// the integration is configured at all. Those are deployment facts, they differ
+// per environment, and a package baked at publish time is the wrong place for
+// them. A manifest names what it needs (`requires`) and the api resolves it.
+//
+// WHAT SYNC OWNS is the step HANDLERS. They need vendor SDKs, a queue, a
+// controller and a logger, and putting those behind a published package would
+// make every consumer carry them. The manifest declares the step and sync
+// implements it — and because the declaration is the source of truth, a declared
+// step with no handler is a failing test rather than a workflow that quietly
+// does nothing.
+
+// 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.
+const QUEUES = [ 'connection', 'notification', 'segment', 'webhook' ];
+
+// 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.
+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' );
+
+	if( ! Array.isArray( manifest?.description ) || ! manifest.description.length ){
+
+		throw new Error( manifest.slug + ' needs a description — an array of paragraphs for its page' );
+
+	}
+
+	for( const field of manifest.fields || [] ){
+
+		if( ! field?.key || ! field?.label ){
+
+			throw new Error( manifest.slug + ' declares a field with no key or label' );
+
+		}
+
+		// An editable field must name an input the form can actually render. A
+		// kind nobody implemented falls through to a text box, which is how a
+		// merchant ends up typing the word true into a toggle.
+		if( field.input && ! INPUTS.includes( field.input ) ){
+
+			throw new Error( manifest.slug + '.' + field.key + ' declares an unknown input: ' + field.input + ' — one of ' + INPUTS.join( ', ' ) );
+
+		}
+
+		// A choice with nothing to choose from renders an empty dropdown, which
+		// looks like a loading state that never resolves.
+		if( field.input === 'select' && ! ( field.options || [] ).length ){
+
+			throw new Error( manifest.slug + '.' + field.key + ' is a select and must declare options' );
+
+		}
+
+	}
+
+	// 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.
+	//
+	// Checked for the three things that actually break a card:
+	//   it must be an svg          a filename here means the file is elsewhere again
+	//   it must carry a viewBox    without one it will not scale into the 50px tile
+	//   it must not wrap a raster  Figma exports a placed bitmap inside an <svg>
+	//                              shell, which looks like a vector, weighs 90KB and
+	//                              blurs exactly like the png it actually is
+	if( typeof manifest?.icon !== 'string' || ! manifest.icon.includes( '<svg' ) ){
+
+		throw new Error( manifest.slug + ' needs an icon — the svg markup itself, not a path to one' );
+
+	}
+
+	if( ! manifest.icon.includes( 'viewBox' ) ){
+
+		throw new Error( manifest.slug + ' icon has no viewBox, so it cannot scale' );
+
+	}
+
+	if( manifest.icon.includes( '<image' ) ){
+
+		throw new Error( manifest.slug + ' icon wraps a raster — re-export it as vector shapes' );
+
+	}
+
+	if( ! CATEGORIES.includes( manifest?.category ) ){
+
+		throw new Error( manifest.slug + ' needs a category — one of ' + CATEGORIES.join( ', ' ) );
+
+	}
+
+	// One field says how a vendor is connected, and it is auth.type. `connect`
+	// carries the COPY around connecting (errors, where a link goes); a `type`
+	// there too is a second answer to one question, and two answers drift.
+	if( manifest?.connect?.type ){
+
+		throw new Error( manifest.slug + ' declares connect.type — that is auth.type now' );
+
+	}
+
+	if( ! AUTH_TYPES.includes( manifest?.auth?.type ) ){
+
+		throw new Error( manifest.slug + ' needs auth.type — one of ' + AUTH_TYPES.join( ', ' ) );
+
+	}
+
+	// An oauth vendor declares the whole flow, so one implementation serves all
+	// of them. Half a descriptor is worse than none: it looks connectable and
+	// fails at the callback, which is the point a merchant has already left the
+	// dashboard and consented.
+	if( manifest.auth.type === 'oauth' ){
+
+		for( const field of OAUTH_FIELDS ){
+
+			if( ! manifest.auth.oauth?.[ field ] ){
+
+				throw new Error( manifest.slug + ' is oauth and must declare auth.oauth.' + field );
+
+			}
+
+		}
+
+	}
+
+	// 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.topic' ] && ! manifest.inbound?.headers?.topic ){
+
+		throw new Error( manifest.slug + ' supports inbound.topic but declares no inbound.headers.topic' );
+
+	}
+
+	if( manifest.supports?.[ 'inbound.verify' ] && ! manifest.inbound?.headers?.signature ){
+
+		throw new Error( manifest.slug + ' supports inbound.verify but declares no inbound.headers.signature' );
+
+	}
+
+	// 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 ){
+
+		throw new Error( manifest.slug + ' needs a setup 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 || {} ) ){
+
+		if( ! HOOK_NAMES.includes( name ) ){
+
+			throw new Error( manifest.slug + ' implements an unknown hook: ' + name );
+
+		}
+
+		if( typeof hook !== 'function' ){
+
+			throw new Error( manifest.slug + ' declares hook ' + name + ' but it is not a function' );
+
+		}
+
+		// 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,
+	// 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 || {};
+
+	for( const name of HOOK_NAMES ){
+
+		if( typeof supports[ name ] !== 'boolean' ){
+
+			throw new Error( manifest.slug + ' must declare supports[ \'' + name + '\' ] as true or false' );
+
+		}
+
+	}
+
+	for( const name of Object.keys( supports ) ){
+
+		if( ! HOOK_NAMES.includes( name ) ){
+
+			throw new Error( manifest.slug + ' declares an unknown hook: ' + name );
+
+		}
+
+	}
+
+	for( const [ type, step ] of Object.entries( manifest.steps || {} ) ){
+
+		if( ! type.startsWith( 'step.' ) ){
+
+			throw new Error( manifest.slug + ' declares a step type that is not step.<domain>.<verb>: ' + type );
+
+		}
+
+		if( ! step?.key ) throw new Error( manifest.slug + ' step ' + type + ' needs a key — the label the builder shows' );
+
+		if( ! QUEUES.includes( step?.queue ) ){
+
+			throw new Error( manifest.slug + ' step ' + type + ' needs a queue — one of ' + QUEUES.join( ', ' ) );
+
+		}
+
+	}
+
+	return Object.freeze({
+		...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 || {} )
+	});
+
+};
+
+const connections = Object.freeze({
+	klaviyo : build( klaviyo ),
+	mailchimp : build( mailchimp ),
+	shopify : build( shopify ),
+	webhook : build( webhook )
+});
+
+// A step type belongs to exactly one vendor.
+//
+// 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.
+//
+// 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.
+( () => {
+
+	const owners = {};
+
+	for( const [ slug, manifest ] of Object.entries( connections ) ){
+
+		for( const type of Object.keys( manifest.steps ) ){
+
+			if( owners[ type ] ){
+
+				throw new Error( 'Step ' + type + ' is declared by both ' + owners[ type ] + ' and ' + slug );
+
+			}
+
+			owners[ type ] = slug;
+
+		}
+
+	}
+
+})();
+
+// The vendors whose environment is actually configured. Every consumer asks this
+// the same way, so "is Shopify available" has one answer rather than one per
+// repo — the api gated it on four env vars and sync inferred it from a different
+// signal, which is how the two drifted.
+const availableConnections = ( env = {} ) => Object.fromEntries(
+	Object.entries( connections ).filter(
+		( [ , manifest ] ) => manifest.requires.every( ( name ) => Boolean( env[ name ] ) )
+	)
+);
+
+// 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
+// document for a withdrawn vendor redacts entirely on its way out.
+const publicSettingsBySlug = Object.fromEntries(
+	Object.entries( connections ).map( ( [ slug, manifest ] ) => [
+		slug,
+		manifest.fields.filter( ( field ) => ! field.redact ).map( ( field ) => field.key )
+	] )
+);
+
+// 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.
+const connectionSteps = ( env = {} ) => Object.entries( availableConnections( env ) )
+	.flatMap( ( [ slug, manifest ] ) => Object.entries( manifest.steps )
+		.map( ( [ type, step ] ) => ({ ...step, slug, type }) )
+	);
+
+// 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 ] )
+});
+
+// A vendor's fields, described for the dashboard. Served so one generic form
+// covers every vendor — a new connection needs no new component.
+//
+// EVERY field, not only the editable ones. A field without an `input` is not
+// absent from the page, it is READ-ONLY there: the webhook signing secret is
+// displayed with a copy button, the Shopify store domain as text. The form
+// decides which of the two a field is; this only describes it.
+//
+// Safe to send for secret fields because a descriptor is a key and a label. The
+// 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 }) => ({
+		...( copy && { copy : true }),
+		...( from && { from }),
+		...( input && { input }),
+		key,
+		label,
+		...( message && { message }),
+		...( options && { options }),
+		...( placeholder && { placeholder }),
+		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
+		// response deliberately never returns the stored value.
+		secret : Boolean( redact )
+	}) );
+
+// Run a vendor's hook, or say why it did not run.
+//
+// ONE CALL SURFACE. A route, a worker or a form handler asks for a hook by name
+// and never names a vendor — which is what lets a variable endpoint like
+// /connection/:slug/callback serve every vendor that declares one.
+//
+// The four outcomes are the point. "unsupported", "unimplemented", "failed" and
+// a result are different answers to why there is no data, and collapsing them is
+// how "this vendor cannot do that" becomes indistinguishable from "it broke".
+const runHook = async ( slug, name, args = {} ) => {
+
+	const manifest = connections[ slug ];
+
+	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 };
+
+	const hook = manifest.hooks?.[ 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
+	// — the caller in that repo has its own registry.
+	if( typeof hook !== 'function' ){
+
+		return { outcome : OUTCOMES.unimplemented, reason : slug + ' implements ' + name + ' outside this package' };
+
+	}
+
+	try {
+
+		return { outcome : OUTCOMES.answered, result : await hook( args ) };
+
+	} catch ( error ) {
+
+		return { error : error?.message || 'failed', outcome : OUTCOMES.failed };
+
+	}
+
+};
+
+// step type → queue name. Sync's router reads this instead of a hand-kept map.
+const stepQueues = ( env = {} ) => Object.fromEntries(
+	connectionSteps( env ).map( ( step ) => [ step.type, step.queue ] )
+);
+
+// Merchant-facing scope-drift copy.
+//
+// THIS IS A CROSS-REPO CONTRACT. drawbridge-sync writes it onto the connection
+// document (reconcileConnectionScopes) and drawbridge-api reads the same text
+// back out, so the two repos each held a copy of one string and a change to
+// either produced a connection whose message changed as the document converged.
+// One copy, here, because neither repo can import the other.
+const scopesMessage = 'Shopify permissions are out of date. Open the Drawbridge app in your Shopify admin to approve the updated permissions.';
+
+// Merge incoming settings into stored ones. Keys whose incoming value is empty
+// are PRESERVED, which is how "leave blank to keep your current key" works —
+// the GET response never returns a secret, so blank has to mean keep rather
+// than clear.
+const mergeSettings = ({ existing, incoming }) => {
+
+	if( ! existing || typeof existing !== 'object' ) return incoming;
+
+	const merged = { ...existing };
+
+	for( const [ key, value ] of Object.entries( incoming || {} ) ){
+
+		if( value !== undefined && value !== null && value !== '' ){
+
+			merged[ key ] = value;
+
+		}
+	}
+	return merged;
+
+};
+
+// Project stored settings to the keys that are safe to return, per slug.
+//
+// THE SECURITY BOUNDARY. It derives from each vendor's own field declaration —
+// public unless the field says `redact` — so a credential added to a form
+// cannot be forgotten here. An unknown slug gets an empty allowlist, so a
+// leftover document for a withdrawn vendor redacts entirely on its way out.
+const redactSettings = ({ slug, settings }) => {
+
+	if( ! settings || typeof settings !== 'object' ) return settings;
+
+	const allowed = publicSettingsBySlug[ slug ] || [];
+
+	return Object.fromEntries(
+		Object.entries( settings ).filter( ( [ key ] ) => allowed.includes( key ) )
+	);
+
+};
+
+// Connection-record fields safe to return in an API response. Defense in depth:
+// anything absent here is stripped, so an internal field added to the document
+// later does not reach a browser by default.
+//
+// `docs` and `links` were listed and set by no vendor and read by nothing —
+// dropped rather than carried forward as keys that look supported.
+const publicConnectionKeys = Object.freeze([
+	'actions',
+	'category',
+	'confirm',
+	'connect',
+	'createdAt',
+	'errors',
+	'description',
+	'excerpt',
+	'fields',
+	'group',
+	'id',
+	'image',
+	'label',
+	'setup',
+	'settings',
+	'shop',
+	'slug',
+	'status',
+	'tasks',
+	'title',
+	'updatedAt',
+	'warnings'
+]);
+
+const projectConnection = ( record ) => {
+
+	if( ! record || typeof record !== 'object' ) return record;
+
+	return publicConnectionKeys.reduce(
+		( accumulator, key ) => {
+
+			if( record[ key ] !== undefined ){
+
+				accumulator[ key ] = record[ key ];
+
+			}
+			return accumulator;
+
+		},
+		{}
+	);
+
+};
+
+// Resolve a manifest against its stored data: any field declared as a function
+// is called with the data, everything else passes through. This lets a field
+// pivot on database state — webhook `tasks` depend on whether a secret exists —
+// while leaving static metadata directly readable.
+//
+// Catalog wiring is dropped rather than resolved. `fields` in particular must
+// 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 ) => {
+
+	if( ! item ) return item;
+
+	return Object.fromEntries(
+		Object.entries( item )
+			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'inbound', 'requires', 'steps', 'supports' ].includes( key ) )
+			.map( ( [ key, value ] ) => [
+				key,
+				( typeof value === 'function' ? value( data ) : value )
+			] )
+	);
+
+};
+
+export { AUTH_TYPES, CATEGORIES, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, availableConnections, build, connectFields, connectionSteps, connections, hookSupport, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, resolveConnection, runHook, scopesMessage, stepQueues };