@drawbridge/drawbridge-utils 0.0.108 → 0.0.110

package/dist/connections/index.d.cts

@@ -1,4 +1,5 @@
-export { consentUrl, exchange, pkcePair, refresh } from './oauth.cjs';
+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.
@@ -190,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.
 //
@@ -201,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
@@ -221,7 +361,17 @@ var klaviyo = {
 	// Google product wants it.
 	auth : {
 		oauth : {
-			authorize : 'https://a.klaviyo.com/oauth/authorize',
+			// TWO DIFFERENT HOSTS, and swapping them fails in opposite directions.
+			//
+			// authorize is a page a HUMAN loads, and it lives on www. Pointing it at
+			// a.klaviyo.com -- their API host -- sends the merchant somewhere that
+			// never renders a consent screen, so the journey stalls with no error
+			// anybody can see.
+			//
+			// token is a server call and must stay on a.klaviyo.com: Klaviyo began
+			// blocking OAuth token traffic through www on 2025-03-31, so the mirror
+			// image of this mistake breaks the exchange instead of the consent.
+			authorize : 'https://www.klaviyo.com/oauth/authorize',
 			// NAMES the env vars holding OUR application's client. One identity,
 			// every merchant — the token is the merchant's and arrives from their
 			// own consent, which is what stops one organization reading another's
@@ -237,6 +387,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.
@@ -268,7 +423,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',
@@ -304,6 +544,16 @@ var klaviyo = {
 		'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'
 };
 
@@ -365,6 +615,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
@@ -501,7 +760,7 @@ const inbound = {
 // 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
-// action is refused here rather than buffered, the same way a bad signature is:
+// 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',
@@ -554,17 +813,22 @@ var shopify = {
 		}
 	],
 	group : 'ecommerce',
+	// The install is the whole configuration — Shopify hands back the shop and
+	// there is nothing further to choose. `shop` absent means the install did not
+	// finish, which is a credential problem rather than a setup one, so the
+	// stored status already says so.
+	incomplete : () => null,
 	// 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
-	// action: /events buffers whatever arrives with the shop domain stamped on;
+	// 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' : ({ action, event, headers, payload }) => {
+		'inbound.receive' : ({ channel, event, headers, payload }) => {
 
-			if( action === 'compliance' && ! COMPLIANCE_TOPICS.has( event ) ){
+			if( channel === 'compliance' && ! COMPLIANCE_TOPICS.has( event ) ){
 
 				throw Object.assign( new Error( 'Unrecognized compliance topic: ' + event ), { status : 401 });
 
@@ -575,7 +839,7 @@ var shopify = {
 				// 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 : action === 'compliance'
+				data : channel === 'compliance'
 					? payload
 					: { ...payload, shop_domain : headers[ inbound.headers.shop ] || null },
 				provider : { id : headers[ inbound.headers.id ] || null }
@@ -767,6 +1031,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.
@@ -967,6 +1234,27 @@ 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
@@ -984,6 +1272,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.
@@ -1310,6 +1619,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',
@@ -1366,4 +1678,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 };