@drawbridge/drawbridge-utils 0.0.107 → 0.0.109

package/dist/connections/index.d.cts

@@ -1,5 +1,6 @@
-export { consentUrl, exchange, pkcePair, refresh } from './oauth.cjs';
-import 'node:crypto';
+import { refresh } from './oauth.cjs';
+export { consentUrl, exchange, pkcePair } from './oauth.cjs';
+import { createHmac, timingSafeEqual } from 'node:crypto';
 
 // THE HOOK VOCABULARY. Closed, and every connection answers all of it.
 //
@@ -48,14 +49,49 @@ const HOOKS = Object.freeze({
 	]),
 
 	// Receiving from the vendor.
+	//
+	// Split across TWO SERVICES, and the split is the point. `verify` and `event`
+	// and `receive` run in drawbridge-webhooks against the vendor's open
+	// connection, where the budget is whatever that vendor's timeout is —
+	// Shopify's is about five seconds, and missing it means they retry and the
+	// delivery is buffered twice. `process` runs in drawbridge-sync off the
+	// buffer, where it can take as long as it needs and retry without the vendor
+	// ever knowing.
+	//
+	// One hook spanning that seam would hide it, and the thing it hides is the
+	// one most likely to bite: slow work written on the receiving side turns
+	// into duplicate deliveries.
 	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.
+		// Prove the request came from the vendor, AND return the payload it
+		// carries. One hook rather than two because for some vendors they are
+		// genuinely one operation: a JWT-bodied webhook (Kinde) cannot be decoded
+		// into anything trustworthy without verifying it first, and a decode that
+		// runs before the signature check is exactly the bug this shape prevents.
+		//
+		// So the raw bytes stop here. Everything downstream receives the payload
+		// this returned, which means nothing downstream can act on unverified
+		// data even by mistake.
+		//
+		// It is also where a request gets refused for any other reason — an event
+		// outside the allowlist, a connection in the wrong state. Anything that
+		// can reject belongs here, so the route holds no rules of its own.
 		'verify',
-		// Name the event, from wherever this vendor puts it.
-		'topic',
-		// Do the work the event implies.
-		'handle'
+		// Name the event, from wherever this vendor puts it. A header for
+		// Shopify, the route itself for Twilio, a claim in the payload for a
+		// JWT-bodied vendor.
+		'event',
+		// What to buffer and what to answer RIGHT NOW, while the vendor waits.
+		// Thin by obligation. Most vendors only shape a buffer doc here; one that
+		// must reply with content (Twilio answers HELP inline with TwiML, which
+		// carriers require) returns that too.
+		'receive',
+		// Do the work the event implies. Runs in drawbridge-sync, off the buffer.
+		//
+		// DECLARED here, IMPLEMENTED there — the same split as the step handlers,
+		// and for the same reason: this half needs controllers, queues and vendor
+		// SDKs, and putting those behind a published package makes every consumer
+		// carry them. The declaration is what proves the implementation exists.
+		'process'
 	]),
 
 	// Vendor data a campaign draws on. Named for what every store platform has,
@@ -155,6 +191,113 @@ const INPUTS = Object.freeze([
 	'url'
 ]);
 
+// A LIVE ACCESS TOKEN, for any vendor that issues an expiring one.
+//
+// Written once here rather than per vendor, because every OAuth connection ends
+// up needing it and the failure when it is missing is the same everywhere: a
+// call that worked in testing and returns 401 an hour later.
+//
+// REFRESH BEFORE USE, not on a schedule. Correctness cannot depend on a job
+// having run — a worker that was down, a queue that was drained, a connection
+// nobody touched for a week all leave a scheduled refresh behind, and the next
+// call fails. Doing it at the point of use also does work proportional to what
+// is actually used rather than to how many connections exist.
+//
+// The scheduled probe (auth.probe, dispatched from sync) is a SEPARATE concern
+// and both are needed: this one keeps calls working, that one keeps the grant
+// alive against a vendor's idle window and reports health honestly.
+
+// How long before real expiry a token counts as stale. Tokens are minted with a
+// lifetime measured in the vendor's clock and spent against ours, and a request
+// takes time to arrive — a token expiring in ten seconds is already too late for
+// a call that has to travel.
+const SKEW_SECONDS = 120;
+
+const isStale = ( settings, now = Date.now() ) => {
+
+	// No expiry recorded means the vendor issues tokens that do not expire
+	// (Mailchimp) or a grant stored before expiry was tracked. Either way there
+	// is nothing to refresh toward, and treating unknown as stale would spend a
+	// refresh token on every single call.
+	if( ! settings?.expiresAt ) return false;
+
+	return new Date( settings.expiresAt ).getTime() - ( SKEW_SECONDS * 1000 ) <= now;
+
+};
+
+// Compute what to store from a mint. Exported because the OAuth callback stores
+// the same shape at connect time, and two places deriving `expiresAt` from
+// `expiresIn` separately is how they come to disagree.
+const tokenSettings = ({ existing = {}, now = Date.now(), tokens }) => ({
+	accessToken : tokens.accessToken,
+	// A vendor that does not rotate its refresh token returns none on a refresh
+	// (Klaviyo). Keeping the existing one is what makes the NEXT refresh work —
+	// dropping it invalidates the grant one call later, nowhere near the cause.
+	...( ( tokens.refreshToken || existing.refreshToken ) && {
+		refreshToken : tokens.refreshToken || existing.refreshToken
+	}),
+	// Absent when the vendor issues non-expiring tokens, and absent is meaningful
+	// — isStale reads it as "nothing to refresh toward".
+	...( tokens.expiresIn && {
+		expiresAt : new Date( now + ( tokens.expiresIn * 1000 ) ).toISOString()
+	}),
+	...( tokens.scope && { scope : tokens.scope })
+});
+
+// Returns a token that is good right now, refreshing and persisting first if the
+// stored one is spent.
+//
+// `save` is injected because this package cannot reach a database — the same
+// reason `fetcher` is. It receives the settings to store and is responsible for
+// encrypting them; forgetting to persist means a refresh on every call, which
+// works but burns the vendor's rate limit and eventually trips it.
+// `force` mints even when the stored token still looks good. That is what
+// auth.probe needs: a probe that short-circuits on an unexpired token never
+// reaches the vendor, so it reports healthy on a grant revoked an hour ago.
+const accessToken = async ({
+	clientId,
+	clientSecret,
+	fetcher,
+	force = false,
+	manifest,
+	now = Date.now(),
+	save,
+	settings
+} = {}) => {
+
+	if( ! settings?.accessToken && ! settings?.refreshToken ){
+
+		throw new Error( 'This connection holds no credential, so there is no token to use' );
+
+	}
+
+	if( ! force && ! isStale( settings, now ) ) return settings.accessToken;
+
+	if( ! settings.refreshToken ){
+
+		// Expired with no way to mint another. Said plainly rather than returning
+		// a token the vendor will refuse — the merchant has to reconnect and the
+		// error should say so.
+		throw new Error( 'This connection has expired and cannot be renewed automatically. Reconnect it.' );
+
+	}
+
+	const minted = await refresh({
+		clientId,
+		clientSecret,
+		descriptor : manifest.auth.oauth,
+		...( fetcher && { fetcher }),
+		refreshToken : settings.refreshToken
+	});
+
+	const next = tokenSettings({ existing : settings, now, tokens : minted });
+
+	if( save ) await save( next );
+
+	return next.accessToken;
+
+};
+
 // Klaviyo, exported from the brand kit and left as authored — the fills are the
 // vendor's own mark, not a recolour.
 //
@@ -166,6 +309,38 @@ var icon$3 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <path d="M365.047 327.038H134.954V172.964H365.047L316.856 250.001L365.047 327.038Z" fill="#232121"/>
 </svg>`;
 
+// Klaviyo pins its API by DATE. A request without this header is refused, and
+// one with an old date keeps the response shape that date shipped with — which
+// is the point: bumping it is a deliberate act with a changelog to read, not
+// something that drifts under us.
+const REVISION = '2026-07-15';
+
+const api = async ( path, { fetcher = fetch, token } ) => {
+
+	const response = await fetcher( 'https://a.klaviyo.com/api' + path, {
+		headers : {
+			// Bearer, not Klaviyo-API-Key — that header is for private keys, and
+			// sending it with an OAuth token fails in a way that reads like a bad
+			// token rather than a bad scheme.
+			authorization : 'Bearer ' + token,
+			revision : REVISION
+		},
+		signal : AbortSignal.timeout( 15000 )
+	});
+
+	if( ! response.ok ){
+
+		throw Object.assign(
+			new Error( 'Klaviyo refused the request (' + response.status + ')' ),
+			{ status : response.status }
+		);
+
+	}
+
+	return response.json();
+
+};
+
 // Klaviyo — contact and event sync, over OAuth.
 //
 // THE FIRST VENDOR ADDED AS A MANIFEST AND NOTHING ELSE. No form component, no
@@ -202,6 +377,11 @@ var klaviyo = {
 			// it is a fact about someone else's records rather than a string this
 			// code computes. Deriving one from a provider key produced
 			// redirect_uri_mismatch on a connection nobody had touched.
+			// Klaviyo drops a refresh token after 90 days of NON-USE. The vendor
+			// never mentions this at runtime — you discover it when a refresh fails
+			// on a connection nobody touched — so it is declared, and it is why
+			// auth.probe has to run on a schedule rather than only before a call.
+			idleExpiry : 90 * 24 * 60 * 60,
 			redirect : '/api/connection/klaviyo/callback',
 			// 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.
@@ -233,7 +413,92 @@ var klaviyo = {
 			label : 'Klaviyo account'
 		}
 	],
+	// The three auth hooks, all pure HTTP against Klaviyo — which is why they
+	// live here rather than in sync. A vendor's own protocol belongs beside the
+	// vendor.
+	hooks : {
+		// Turn a fresh grant into settings worth showing. Without this the card
+		// renders an empty "Klaviyo account" field, because the merchant is never
+		// asked which account they connected — the consent already decided it and
+		// asking again would be a question we can answer ourselves.
+		'auth.connect' : async ({ fetcher, tokens }) => {
+
+			const body = await api( '/accounts', { fetcher, token : tokens.accessToken });
+
+			const account = body?.data?.[ 0 ];
+
+			return {
+				account : account?.attributes?.contact_information?.organization_name || account?.id || null,
+				accountId : account?.id || null
+			};
+
+		},
+		// Revoke at KLAVIYO, not just locally. Forgetting our copy leaves the
+		// grant live in the merchant's account, so a disconnect that looks
+		// complete here still shows Drawbridge with access over there.
+		//
+		// Basic auth with our client, exactly like the token exchange — the token
+		// being revoked is the subject, not the credential.
+		'auth.disconnect' : async ({ clientId, clientSecret, fetcher = fetch, settings }) => {
+
+			const token = settings?.refreshToken || settings?.accessToken;
+
+			if( ! token ) return { revoked : false };
+
+			const response = await fetcher( 'https://a.klaviyo.com/oauth/revoke', {
+				body : new URLSearchParams({
+					token,
+					token_type_hint : settings?.refreshToken ? 'refresh_token' : 'access_token'
+				}),
+				headers : {
+					authorization : 'Basic ' + Buffer.from( clientId + ':' + clientSecret ).toString( 'base64' ),
+					'content-type' : 'application/x-www-form-urlencoded'
+				},
+				method : 'POST',
+				signal : AbortSignal.timeout( 15000 )
+			});
+
+			// A grant already revoked at the vendor answers non-2xx, and that is
+			// the outcome we wanted — surfacing it as a failure would leave a
+			// merchant unable to finish disconnecting.
+			return { revoked : response.ok };
+
+		},
+		// THE MINT IS THE PROBE. Asking "is this token still good" by inspecting
+		// what we stored answers the wrong question — a grant revoked inside
+		// Klaviyo still looks perfect in our database. Spending the refresh token
+		// is the only thing that asks Klaviyo.
+		//
+		// It also keeps the grant warm: Klaviyo expires a refresh token after 90
+		// days of NON-USE, so a connection nobody touches dies silently without
+		// this running.
+		'auth.probe' : async ({ clientId, clientSecret, fetcher, manifest, settings }) => {
+
+			const token = await accessToken({
+				clientId,
+				clientSecret,
+				fetcher,
+				// Mint even if the stored token still looks good — a probe that
+				// short-circuits never reaches Klaviyo and reports healthy on a
+				// grant revoked an hour ago.
+				force : true,
+				manifest,
+				settings
+			});
+
+			return { ok : Boolean( token ) };
+
+		}
+	},
 	icon: icon$3,
+	// A grant with no list chosen is authenticated and useless. The list cannot
+	// be part of the consent flow — enumerating lists needs the token the consent
+	// returns — so it is always a second step, and the card must say so rather
+	// than showing Active over nothing.
+	incomplete : ( data ) => ( data?.settings?.list
+		? null
+		: 'Choose which Klaviyo list your contacts should sync into.'
+	),
 	label : 'klaviyo',
 	requires : [
 		'KLAVIYO_OAUTH_CLIENT_ID',
@@ -261,13 +526,24 @@ var klaviyo = {
 		'catalog.prices' : false,
 		'catalog.products' : false,
 		'catalog.promotions' : false,
-		'inbound.handle' : false,
-		'inbound.topic' : false,
+		'inbound.event' : false,
+		'inbound.process' : false,
+		'inbound.receive' : false,
 		'inbound.verify' : false,
 		'lifecycle.cleanup' : false,
 		'lifecycle.register' : false,
 		'lifecycle.rehydrate' : false
 	},
+	tasks : () => [
+		// Mailchimp carries the same warning, deliberately worded the same way. A
+		// merchant who connects either one and is told nothing reasonably assumes
+		// contacts are flowing, and finds out weeks later that they are not.
+		{
+			message : 'Contact syncing to Klaviyo lists has not shipped yet. Connecting stores your authorization so it is ready, but nothing is being sent to Klaviyo right now.',
+			title : 'List sync not available yet',
+			type : 'warning'
+		}
+	],
 	title : 'Klaviyo'
 };
 
@@ -329,6 +605,15 @@ var mailchimp = {
 		}
 	],
 	icon: icon$2,
+	// A key with no audience chosen is authenticated and inert. Mailchimp also
+	// needs its merge fields created on that audience before any Drawbridge total
+	// can be written to a member — unlike Klaviyo, its custom fields are not
+	// schemaless — so the audience must be picked before lifecycle.register has
+	// anything to register against.
+	incomplete : ( data ) => ( data?.settings?.audience
+		? null
+		: 'Choose which Mailchimp audience your contacts should sync into.'
+	),
 	label : 'mailchimp',
 	// Uniform surface, honest answers. A key is stored and can be removed; nothing
 	// else is built yet, because audience sync has not shipped. Every false here
@@ -342,8 +627,9 @@ var mailchimp = {
 		'catalog.prices' : false,
 		'catalog.products' : false,
 		'catalog.promotions' : false,
-		'inbound.handle' : false,
-		'inbound.topic' : false,
+		'inbound.event' : false,
+		'inbound.process' : false,
+		'inbound.receive' : false,
 		'inbound.verify' : false,
 		'lifecycle.cleanup' : false,
 		'lifecycle.register' : false,
@@ -382,6 +668,96 @@ var icon$1 = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xm
 <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>`;
 
+// THE SHARED HALF OF inbound.verify.
+//
+// A vendor whose scheme is "hash the raw body with a shared secret and compare,
+// constant-time, against a header" declares that shape as `inbound.signature`
+// data on its manifest (algorithm, encoding, the env var naming the secret) and
+// wires this straight in as its hook — Shopify does exactly that.
+//
+// A vendor whose scheme is not that shape — Twilio signs the REGISTERED URL
+// rather than the body, a JWT-bodied vendor verifies against a JWKS — writes its
+// own inbound.verify instead. That is why verify is a hook and not config: this
+// file covers the common case, not the contract.
+const verifySignature = ({ body, descriptor, headers }) => {
+
+	const provided = headers[ descriptor.headers.signature ];
+
+	if( ! provided ){
+
+		throw Object.assign( new Error( 'Missing webhook signature' ), { status : 401 });
+
+	}
+
+	const digest = createHmac( descriptor.signature.algorithm, process.env[ descriptor.signature.secret ] )
+		.update( body )
+		.digest( descriptor.signature.encoding );
+
+	// Buffers of different lengths crash timingSafeEqual rather than compare
+	// false — decided here, before the length itself becomes a timing signal.
+	const digestBuffer = Buffer.from( digest, descriptor.signature.encoding );
+	const providedBuffer = Buffer.from( provided, descriptor.signature.encoding );
+
+	if(
+		digestBuffer.length !== providedBuffer.length ||
+		! timingSafeEqual( digestBuffer, providedBuffer )
+	){
+
+		throw Object.assign( new Error( 'Invalid webhook signature' ), { status : 401 });
+
+	}
+
+	// The proof and the parse happen together on purpose. Nothing downstream of
+	// inbound.verify ever sees the raw bytes, which is what makes acting on
+	// unverified data impossible rather than merely discouraged.
+	return JSON.parse( body.toString() );
+
+};
+
+// THE SHARED HALF OF inbound.event, for a vendor that puts it in a header.
+const readEventHeader = ({ descriptor, headers }) => headers[ descriptor.headers.event ];
+
+// 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.
+//
+// Pulled out to a const (rather than written inline under `inbound:` below) so
+// the hooks further down can reference the SAME object the manifest publishes,
+// instead of a second copy that could drift from it.
+//
+// `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 declare no signature block and
+// implement inbound.verify themselves — a JWT-bodied vendor (Kinde) verifies
+// against a JWKS and returns the decoded claims, and Twilio signs the
+// registered URL rather than the body. That is why verify is a hook and not
+// config.
+const inbound = {
+	headers : {
+		event : 'x-shopify-topic',
+		id : 'x-shopify-webhook-id',
+		shop : 'x-shopify-shop-domain',
+		signature : 'x-shopify-hmac-sha256'
+	},
+	signature : {
+		algorithm : 'sha256',
+		encoding : 'base64',
+		secret : 'SHOPIFY_API_SECRET'
+	}
+};
+
+// Shopify's own GDPR deadline, not ours — these three are the only topics
+// registered under `compliance_topics` in the app toml, and Shopify expects an
+// answer even for a shop that has already uninstalled. Anything else on this
+// channel is refused here rather than buffered, the same way a bad signature is:
+// it is a request that should never have arrived.
+const COMPLIANCE_TOPICS = new Set([
+	'customers/data_request',
+	'customers/redact',
+	'shop/redact'
+]);
+
 // 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
@@ -427,30 +803,43 @@ var shopify = {
 		}
 	],
 	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'
+	// The install is the whole configuration — Shopify hands back the shop and
+	// there is nothing further to choose. `shop` absent means the install did not
+	// finish, which is a credential problem rather than a setup one, so the
+	// stored status already says so.
+	incomplete : () => null,
+	// verify and event lean entirely on the shared HMAC helper — Shopify's scheme
+	// is exactly the shape it covers, so there is nothing vendor-specific to
+	// write for either. receive is the one hook that genuinely differs by
+	// channel: /events buffers whatever arrives with the shop domain stamped on;
+	// /compliance enforces the topic allowlist above, because answering one late
+	// is a legal deadline rather than a retry.
+	hooks : {
+		'inbound.event' : ( args ) => readEventHeader({ ...args, descriptor : inbound }),
+		'inbound.receive' : ({ channel, event, headers, payload }) => {
+
+			if( channel === 'compliance' && ! COMPLIANCE_TOPICS.has( event ) ){
+
+				throw Object.assign( new Error( 'Unrecognized compliance topic: ' + event ), { status : 401 });
+
+			}
+
+			return {
+				// Compliance payloads already carry shop_domain in the body — Shopify's
+				// own GDPR shape. The app-level event stream does not; that domain
+				// lives only in the header, so it is stamped on here rather than left
+				// for drawbridge-sync to reach into headers nobody hands it.
+				data : channel === 'compliance'
+					? payload
+					: { ...payload, shop_domain : headers[ inbound.headers.shop ] || null },
+				provider : { id : headers[ inbound.headers.id ] || null }
+			};
+
 		},
-		signature : {
-			algorithm : 'sha256',
-			encoding : 'base64',
-			secret : 'SHOPIFY_API_SECRET'
-		}
+		'inbound.verify' : ( args ) => verifySignature({ ...args, descriptor : inbound })
 	},
 	icon: icon$1,
+	inbound,
 	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
@@ -479,8 +868,9 @@ var shopify = {
 		'catalog.prices' : false,
 		'catalog.products' : true,
 		'catalog.promotions' : true,
-		'inbound.handle' : true,
-		'inbound.topic' : true,
+		'inbound.event' : true,
+		'inbound.process' : true,
+		'inbound.receive' : true,
 		'inbound.verify' : true,
 		'lifecycle.cleanup' : true,
 		'lifecycle.register' : true,
@@ -631,6 +1021,9 @@ var webhook = {
 	// It is the one card that reads wrong — our logo among vendor logos — and it
 	// wants a mark of its own when there is one.
 	icon,
+	// The destination url is supplied per step, not per connection, so there is
+	// nothing to finish here — generating the secret IS connecting.
+	incomplete : () => null,
 	label : 'webhook',
 	// Gated on the encryption secret: without it the signing secret could not be
 	// stored safely, so the connection must not be offered at all.
@@ -647,8 +1040,9 @@ var webhook = {
 		'catalog.prices' : false,
 		'catalog.products' : false,
 		'catalog.promotions' : false,
-		'inbound.handle' : false,
-		'inbound.topic' : false,
+		'inbound.event' : false,
+		'inbound.process' : false,
+		'inbound.receive' : false,
 		'inbound.verify' : false,
 		'lifecycle.cleanup' : false,
 		'lifecycle.register' : false,
@@ -830,14 +1224,35 @@ const build = ( manifest ) => {
 
 		}
 
+		// THE REDIRECT MUST BE THE ONE PATH THE DASHBOARD SERVES.
+		//
+		// There is exactly one callback route — app/api/connection/[slug]/callback
+		// in drawbridge-app-web — so this path is a fact about our own routing, not
+		// a free choice. It stays declared rather than derived because it is also a
+		// record of what is registered in the vendor's console, and reading it in
+		// the manifest is how somebody checks the two agree.
+		//
+		// Declared-but-wrong is the dangerous state: it passes review, gets
+		// registered at the vendor, and fails AFTER the merchant has consented —
+		// they hit a dashboard 404 having already granted access. Cheaper to refuse
+		// the manifest at import.
+		if( manifest.auth.oauth.redirect !== '/api/connection/' + manifest.slug + '/callback' ){
+
+			throw new Error(
+				manifest.slug + ' declares auth.oauth.redirect ' + manifest.auth.oauth.redirect
+				+ ' but the only callback route is /api/connection/' + manifest.slug + '/callback'
+			);
+
+		}
+
 	}
 
 	// 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 ){
+	if( manifest.supports?.[ 'inbound.event' ] && ! manifest.inbound?.headers?.event ){
 
-		throw new Error( manifest.slug + ' supports inbound.topic but declares no inbound.headers.topic' );
+		throw new Error( manifest.slug + ' supports inbound.event but declares no inbound.headers.event' );
 
 	}
 
@@ -847,6 +1262,27 @@ const build = ( manifest ) => {
 
 	}
 
+	// IS THE CREDENTIAL ENOUGH? For most vendors yes, and they answer with a bare
+	// `() => null`. But a credential is not always a working connection: a
+	// Klaviyo grant with no list chosen is authenticated and useless, and the
+	// merchant sees an Active card doing nothing — the exact silence this
+	// package exists to remove.
+	//
+	// Returns the REASON it is not usable yet, in the merchant's words, or null
+	// when it is. One function rather than a boolean plus a message, because two
+	// declarations of the same fact drift: the status the card shows and the
+	// sentence explaining it come from the same call or they eventually
+	// disagree.
+	//
+	// Required on every manifest for the same reason `supports` is: a missing
+	// answer is indistinguishable from a vendor written before the question
+	// existed.
+	if( typeof manifest?.incomplete !== 'function' ){
+
+		throw new Error( manifest.slug + ' must declare incomplete( data ) — return null when the connection is usable, or the reason it is not' );
+
+	}
+
 	// 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.
@@ -1090,7 +1526,11 @@ const runHook = async ( slug, name, args = {} ) => {
 
 	} catch ( error ) {
 
-		return { error : error?.message || 'failed', outcome : OUTCOMES.failed };
+		// A hook throws to REJECT, not just to report failure — inbound.verify
+		// on a forged signature, inbound.receive on a topic outside the vendor's
+		// declared set. The status rides along so a caller can answer 401 rather
+		// than always folding a hook's own rejection into a 500.
+		return { error : error?.message || 'failed', outcome : OUTCOMES.failed, status : error?.status || null };
 
 	}
 
@@ -1169,6 +1609,9 @@ const publicConnectionKeys = Object.freeze([
 	'group',
 	'id',
 	'image',
+	// The reason a connected vendor still is not usable — a Klaviyo grant with no
+	// list chosen. Public because the card that shows Pending has to say why.
+	'incomplete',
 	'label',
 	'setup',
 	'settings',
@@ -1216,7 +1659,7 @@ const resolveConnection = ( item, data ) => {
 
 	return Object.fromEntries(
 		Object.entries( item )
-			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'inbound', 'requires', 'steps', 'supports' ].includes( key ) )
+			.filter( ( [ key ] ) => ! [ 'auth', 'enabled', 'fields', 'hooks', 'inbound', 'requires', 'steps', 'supports' ].includes( key ) )
 			.map( ( [ key, value ] ) => [
 				key,
 				( typeof value === 'function' ? value( data ) : value )
@@ -1225,4 +1668,4 @@ const resolveConnection = ( item, data ) => {
 
 };
 
-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 };
+export { AUTH_TYPES, CATEGORIES, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, accessToken, availableConnections, build, connectFields, connectionSteps, connections, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, refresh, resolveConnection, runHook, scopesMessage, stepQueues, tokenSettings };