@drawbridge/drawbridge-utils 0.0.114 → 0.0.116

package/dist/connections/index.d.cts

@@ -519,6 +519,262 @@ const accessToken = async ({
 
 };
 
+// Attentive, exported from the brand kit and left as authored — the yellow
+// field and the mark's fills are the vendor's own, 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 through dist.
+var icon$4 = `<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="#FFD967"/>
+<path d="M239.369 127.404C260.863 122.013 284.964 132.569 295.576 152.039C321.796 201.286 347.928 250.567 374.131 299.825C380.149 311.989 381.244 326.564 376.733 339.41C371.446 355.097 358.039 367.69 342.107 372.089C326.274 376.67 308.351 372.871 295.741 362.255C288.865 356.892 284.161 349.359 280.354 341.629C261.869 306.95 243.478 272.217 225.071 237.501C214.409 218.614 187.221 212.656 169.622 225.315C168.104 227.309 164.159 226.857 164.72 223.796C176.911 202.569 189.361 181.497 201.662 160.331C205.183 154.428 208.214 148.129 212.967 143.091C219.844 135.272 229.263 129.782 239.374 127.404" fill="#1E1C1C"/>
+<path d="M166.04 261.805C180.228 259.107 195.528 261.893 207.581 269.971C218.512 277.079 226.908 288.136 230.604 300.657C234.835 314.103 233.614 329.124 227.485 341.788C220.097 356.875 205.782 368.543 189.317 372.089C173.957 375.652 157.089 372.386 144.304 363.103C132.971 355.295 124.912 342.989 121.891 329.581C118.943 316.636 120.725 302.656 127.002 290.938C134.699 275.951 149.503 264.933 166.046 261.811" fill="#1E1C1C"/>
+</svg>`;
+
+// Attentive — SMS-first marketing, installed as a distributed Attentive app.
+//
+// EVERY VENDOR FACT BELOW IS CITED from docs.attentive.com (fetched 2026-09-01):
+//
+//   authorize   docs.attentive.com/docs/authentication — the install prompt is
+//               ui.attentivemobile.com/integrations/oauth-install, documented
+//               with `client_id` and `redirect_uri` parameters.
+//
+//   token       docs.attentive.com/reference/createtokenviaauthorizationcode.md —
+//               POST api.attentivemobile.com/v1/authorization-codes/tokens, all
+//               parameters as FORM FIELDS (grant_type, code, redirect_uri,
+//               client_id, client_secret). Credentials in the body is our
+//               runner's default, so unlike Klaviyo there is nothing to wrap
+//               for auth — see hooks.auth.token for what IS wrapped, and why.
+//
+//   response    { access_token, id_token, token_type : "Bearer",
+//               expires_in : 900 } — and NO refresh_token, which matters below.
+//
+//   scopes      events:write, ecommerce:write, subscriptions:write,
+//               attributes:write, privacy_requests:write; the segments API
+//               takes segments:read or segments:write. Scopes ride on the app's
+//               registration (the generated distribution URL carries them), not
+//               on each consent — so none are declared here.
+//
+//   segments    docs.attentive.com/reference/listsegments.md —
+//               GET api.attentivemobile.com/v2/segments with `name` (partial
+//               match), `cursor` and `limit` (1-1000, default 20); responds
+//               { segments : [ { externalId, name, ... } ], cursor, hasMore }.
+//
+// DORMANT UNTIL REGISTERED. `requires` names the client credentials that only
+// exist once the Attentive app is created (their console: enable distribution,
+// set the redirect URL, Generate Credentials). Until those env vars land, no
+// deployment offers this connection — the manifest ships complete and inert.
+//
+// THREE THINGS TO VERIFY AT REGISTRATION, because the docs conflict or are
+// silent, and only a live install answers them:
+//
+//   1. TOKEN LIFETIME. The auth overview says access tokens "do not expire";
+//      the token response carries expires_in : 900 and no refresh_token. If
+//      the token really died at 15 minutes with nothing to renew it, every
+//      connection would need reconnecting a quarter-hour after consent.
+//      hooks.auth.token below models the overview's answer — see its comment.
+//
+//   2. STATE ECHO. Our callback requires the parked `state` to round-trip, and
+//      their authorize URL is documented with only client_id and redirect_uri.
+//      If the consent drops unknown params, the flow breaks at the callback.
+//
+//   3. PER-ENVIRONMENT REDIRECTS. The redirect must byte-match the app's
+//      registration, and dev and prod have different callback hosts — one app
+//      with multiple redirect URLs, or two apps like Shopify's two tomls.
+var attentive = {
+	auth : {
+		oauth : {
+			// NAMES of the env vars holding OUR app's client — set at registration,
+			// never before. No `headers` on the client: Attentive takes credentials
+			// as form fields, which is the runner's default.
+			client : {
+				id : 'ATTENTIVE_OAUTH_CLIENT_ID',
+				secret : 'ATTENTIVE_OAUTH_CLIENT_SECRET'
+			},
+			urls : {
+				authorize : 'https://ui.attentivemobile.com/integrations/oauth-install',
+				redirect : '/api/connection/attentive/callback',
+				token : 'https://api.attentivemobile.com/v1/authorization-codes/tokens'
+			}
+		},
+		type : 'oauth'
+	},
+	// EVERYTHING A MERCHANT READS. `errors` would live in here too — the
+	// connection DOCUMENT carries its own `errors` array and is spread OVER the
+	// resolved manifest downstream, so a top-level one would never render.
+	content : {
+		// SAYS WHAT ACTUALLY HAPPENS. This used to promise that disconnecting
+		// revokes Drawbridge's access, and it cannot: Attentive documents no
+		// revocation endpoint, and their authentication page states an access
+		// token "does not expire". So the grant survives a disconnect forever
+		// unless the merchant removes the integration at Attentive, and the copy
+		// has to say so rather than let them believe otherwise.
+		confirm : 'Disconnecting removes Drawbridge\'s stored Attentive token. Attentive does not offer a way for us to revoke it, so remove the Drawbridge integration in Attentive as well if you want its access fully withdrawn. Your subscribers stay in both Attentive and Drawbridge — neither list is deleted.',
+		description : [
+			'Attentive is where your SMS marketing lives, and this connection is becoming the way your Drawbridge contacts sync into an Attentive segment.',
+			'You authorize Drawbridge from inside Attentive and can revoke that access there at any time. Drawbridge never sees or stores your Attentive password.',
+			'Subscriber syncing is not live yet, so connecting today does nothing except choose the segment it will use when it ships.'
+		],
+		excerpt : 'Sync your Drawbridge contacts into an Attentive segment.',
+		guide : [
+			'Press Connect. Drawbridge sends you to Attentive to approve access.',
+			'Sign in to Attentive if you are not already, and authorize the permissions listed.',
+			'You are returned here — choose which Attentive segment your contacts should sync into.'
+		]
+	},
+	// A contact destination, like Klaviyo and Mailchimp — a merchant could
+	// reasonably keep several up to date at once.
+	exclusive : false,
+	feature : 'organization:connection:attentive',
+	fields : [
+		{
+			input : 'select',
+			key : 'segment',
+			label : 'Attentive segment',
+			message : 'Contacts your campaigns collect are synced into this segment.',
+			hook : 'resources.audiences',
+			required : true
+			// No `search : false` here, and that is a first: /v2/segments takes a
+			// `name` filter (partial match, cited above), so this picker searches
+			// the ACCOUNT — Klaviyo and Mailchimp can only match the fetched page.
+		}
+	],
+	group : 'contacts',
+	// A HOOK'S VALUE IS ITS ANSWER. The consent is stored and can be revoked;
+	// nothing else is built yet, because subscriber sync has not shipped. Every
+	// false here is "not yet" rather than "never" — when the sync lands, probe
+	// and contacts.sync are the first to flip.
+	hooks : {
+
+		auth : {
+			// The exchange already yields the tokens, and Attentive documents no
+			// account-identity endpoint to enrich them with — Klaviyo's connect
+			// reads the account name back; this has nothing cited to read. The
+			// callback stores the tokens and skips enrichment on `unimplemented`.
+			// FALSE, NOT {}. `{}` means "supported, implemented in the repo with the
+			// dependencies", and nothing anywhere implements either of these —
+			// there is nothing for them to do. The exchange already yields the
+			// tokens and Attentive documents no account-identity endpoint to
+			// enrich them with, so connect has nothing to add; and they document
+			// no revocation endpoint at all, so disconnect has nothing to call.
+			// Recorded as a decision rather than left as an unkept promise.
+			connect : false,
+			disconnect : false,
+			probe : false,
+			scopes : false,
+			// THE ONE THING WRAPPED, and it is about the response rather than the
+			// request. Attentive's token reply carries expires_in : 900 while their
+			// auth overview says access tokens "do not expire" — and no refresh
+			// token exists to renew with. Storing that expiry would have
+			// accessToken() declaring the credential spent fifteen minutes after
+			// consent, with nothing to renew it: every connection would demand
+			// reconnecting four times an hour.
+			//
+			// The overview's answer is modelled — the expiry is dropped, so the
+			// token is treated as long-lived. Registration item 1 in the header is
+			// the live exchange that proves this right or wrong.
+			token : async ( args ) => {
+
+				const minted = await authToken( args );
+
+				return { ...minted, expiresIn : null };
+
+			}
+		},
+		commerce : false,
+		contacts : { remove : false, sync : false },
+		email : false,
+		inbound : false,
+		lifecycle : false,
+		resources : {
+
+			// The segments a merchant can sync into, for the picker on their
+			// connection.
+			//
+			// GET /v2/segments (cited in the header). `limit` caps at 1000 in their
+			// own spec, defaulting to 20 — low enough that leaving it unset would
+			// show a picker quietly missing most of a real account. The response's
+			// only identifier is `externalId`, so an entry without one cannot be
+			// stored and is dropped.
+			audiences : async ({ cursor, fetcher = fetch, limit = 100, search, token }) => {
+
+				const query = new URLSearchParams({
+					limit : String( Math.min( limit, 1000 ) ),
+					...( cursor && { cursor } ),
+					...( search?.value && { name : String( search.value ).trim() } )
+				});
+
+				const response = await fetcher(
+					'https://api.attentivemobile.com/v2/segments?' + query,
+					{
+						headers : { authorization : 'Bearer ' + token },
+						signal : AbortSignal.timeout( 15000 )
+					}
+				);
+
+				if( ! response.ok ){
+
+					throw Object.assign(
+						new Error( 'Attentive refused the request (' + response.status + ')' ),
+						{ status : response.status }
+					);
+
+				}
+
+				const body = await response.json();
+
+				return {
+					items : ( body?.segments || [] )
+						.filter( ( segment ) => segment?.externalId )
+						.map( ( segment ) => ({ id : segment.externalId, title : segment?.name || segment.externalId }) ),
+					pageInfo : {
+						endCursor : body?.hasMore ? ( body?.cursor || null ) : null,
+						hasNextPage : Boolean( body?.hasMore )
+					}
+				};
+
+			},
+			prices : false,
+			products : false,
+			promotions : false
+
+		},
+		segment : false,
+		sms : false,
+		webhook : false
+
+	},
+	icon: icon$4,
+	requires : [
+		'ATTENTIVE_OAUTH_CLIENT_ID',
+		'ATTENTIVE_OAUTH_CLIENT_SECRET'
+	],
+	slug : 'attentive',
+	// A consent with no segment chosen is authenticated and inert — the sync,
+	// when it ships, needs somewhere to put people.
+	status : ( data ) => ( data?.settings?.segment ? data.status : 'pending' ),
+	// No steps: subscriber sync has not shipped, so this vendor contributes
+	// nothing to a workflow yet. An empty steps object is the honest declaration.
+	steps : {},
+	tasks : ( data ) => [
+		...( data?.settings?.segment
+			? []
+			: [
+				{
+					message : 'Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.',
+					title : 'Choose a segment'
+				}
+			]
+		),
+		{
+			message : 'Contact syncing to Attentive segments has not shipped yet. Nothing is being sent to Attentive right now.',
+			title : 'Subscriber sync not available yet',
+			type : 'warning'
+		}
+	],
+	title : 'Attentive'
+};
+
 // Drawbridge, exported from the brand kit and left as authored — the fills are the
 // vendor's own mark, not a recolour.
 //
@@ -1775,10 +2031,14 @@ var mailchimp = {
 	hooks : {
 
 		auth : {
-			// Implemented outside this package: storing a typed key needs no vendor
-			// call, so the api's own form handler does it.
-			connect : {},
-			disconnect : {},
+			// FALSE, NOT {}. `{}` promises an implementation living in the repo that
+			// holds the dependencies, and there is no implementation anywhere
+			// because there is nothing to implement: storing and clearing a typed
+			// key needs no vendor call, and the api's own form handler does it.
+			// Declaring `{}` made the coverage check chase a body that does not
+			// exist, and made a caller wait on an answer that never comes.
+			connect : false,
+			disconnect : false,
 			probe : false,
 			scopes : false,
 			// Keys today. When Mailchimp's OAuth lands this becomes a wrapper that
@@ -2079,10 +2339,30 @@ var shopify = {
 			// re-registers rather than answering "is this token still good", and
 			// scope drift is its own hook because a token can be perfectly valid
 			// while the grant is too narrow.
-			connect : {},
-			disconnect : {},
+			//
+			// connect and disconnect are FALSE rather than `{}`: there is nothing to
+			// call on either side. The install already hands the callback everything
+			// it stores, and a Shopify grant is withdrawn by UNINSTALLING the app in
+			// Shopify admin — which Drawbridge learns about from the app_uninstalled
+			// webhook rather than by asking. `{}` claimed a body implemented
+			// elsewhere; none exists, and none could.
+			connect : false,
+			disconnect : false,
 			probe : false,
-			scopes : {},
+
+			// WHETHER THE GRANT IS STILL WIDE ENOUGH. A token can be perfectly valid
+			// and still too narrow — a deploy that adds a scope leaves every existing
+			// install short of it, and no webhook fires to say so.
+			//
+			// The comparison is the vendor's, so it belongs here. Reading WHICH
+			// scopes a store granted is not: that lives in the `shop` collection and
+			// needs a controller, which is precisely what a hook in a published
+			// package must not be handed. The caller reads the grant and passes the
+			// string; this answers what is missing from it.
+			//
+			// `shopify` is injected for the same reason it is everywhere else — this
+			// package cannot import @drawbridge/shopify, which depends on it.
+			scopes : ({ scope, shopify }) => ( scope ? shopify.oauth.missingScopes( scope ) : null ),
 			// Shopify's install grant is exchanged inside its own app flow, not
 			// through the shared OAuth runner.
 			token : false
@@ -2144,8 +2424,68 @@ var shopify = {
 			// variant and arrives with it, so there is nothing for prices to answer
 			// that products does not already.
 			prices : false,
-			products : {},
-			promotions : {}
+
+			// WHAT THE VENDOR ANSWERS, shaped for a picker. Both of these were api
+			// ROUTES — /organization/:organization/shopify/products and
+			// .../connection/:id/shopify/discounts — vendor-named urls in a service
+			// that is supposed to have none, reachable only by knowing the path.
+			// They are the same two questions every other vendor answers through
+			// resources.*, so they answer them the same way now.
+			//
+			// `shopify` is INJECTED: this package cannot import @drawbridge/shopify,
+			// which depends on it. What arrives is the SDK's pure HTTP namespaces
+			// and nothing else — no controller, no collection access. Resolving the
+			// credential is the caller's job because it is Drawbridge's job: the
+			// admin token refreshes and writes itself back, which is service work,
+			// not vendor work.
+			products : async ({ cursor, limit = 100, search, settings, shopify, sort }) => {
+
+				const products = await shopify.storefront.getProducts({
+					cursor,
+					domain : settings?.domain,
+					limit : Number( limit ),
+					search : search?.value || null,
+					sort,
+					storefrontAccessToken : settings?.storefrontAccessToken
+				});
+
+				return {
+					items : ( products?.edges || [] ).map( ( edge ) => edge.node ),
+					pageInfo : {
+						endCursor : products?.pageInfo?.endCursor || null,
+						hasNextPage : Boolean( products?.pageInfo?.hasNextPage ),
+						hasPreviousPage : Boolean( products?.pageInfo?.hasPreviousPage ),
+						startCursor : products?.pageInfo?.startCursor || null
+					}
+				};
+
+			},
+
+			promotions : async ({ cursor, limit = 100, search, settings, shopify }) => {
+
+				const discounts = await shopify.admin.getDiscounts({
+					adminAccessToken : settings?.adminAccessToken,
+					cursor,
+					domain : settings?.domain,
+					limit : Number( limit ),
+					search : search?.value || null
+				});
+
+				return {
+					// The GLOBAL id is what Shopify returns and the bare id is what a
+					// picker stores, which is why the tail is taken here rather than by
+					// each caller that happened to remember.
+					items : ( discounts?.edges || [] ).map( ( edge ) => ({
+						id : String( edge?.node?.id || '' ).split( '/' ).pop(),
+						title : edge?.node?.codeDiscount?.title
+					}) ),
+					pageInfo : {
+						endCursor : discounts?.pageInfo?.endCursor || null,
+						hasNextPage : Boolean( discounts?.pageInfo?.hasNextPage )
+					}
+				};
+
+			}
 		}
 ,
 
@@ -2380,10 +2720,12 @@ var webhook = {
 	// connect generates a secret rather than proving a credential.
 	hooks : {
 		auth : {
-			// Minting and clearing a secret needs no vendor call, so the api's own
-			// handler does both.
-			connect : {},
-			disconnect : {},
+			// FALSE, NOT {}. There is no vendor here at all — connecting mints a
+			// secret and disconnecting clears it, both done by the api's own
+			// handler. `{}` would promise a body implemented elsewhere, and none
+			// exists or could.
+			connect : false,
+			disconnect : false,
 			probe : false,
 			scopes : false,
 			// Nothing to mint. Connecting generates a secret; there is no vendor.
@@ -2945,6 +3287,7 @@ const stepLabels = ( catalog = connections ) => Object.fromEntries(
 );
 
 const connections = Object.freeze({
+	attentive : build( attentive ),
 	drawbridge : build( drawbridge ),
 	hubspot : build( hubspot ),
 	klaviyo : build( klaviyo ),
@@ -3140,6 +3483,39 @@ const stepQueues = ( env = {} ) => Object.fromEntries(
 	connectionSteps( env ).map( ( step ) => [ step.type, step.queue ] )
 );
 
+// THE WHOLE ROUTING TABLE: live step types plus the retired ones still stored
+// on workflow documents.
+//
+// Both halves were already facts here — stepQueues answers new→queue and
+// RETIRED answers old→new — but the composition of the two lived in sync as a
+// hand-written block of `step.shopify.* : 'connection'` literals. That block
+// and this file had to be edited together and nothing said so, which is the
+// exact shape of the drift that orphans a queue: retire a step type here,
+// forget the literal there, and the dispatcher logs unknown-step-type while
+// the work silently stops.
+//
+// A retired type routes wherever its REPLACEMENT routes, because that is what
+// retiring meant — same work, new name. So there is no second table to keep;
+// moving a live step to a different queue moves its aliases with it.
+//
+// Retired entries whose replacement is not currently live (a vendor gated off
+// by env) are omitted rather than guessed: no queue exists to route them to,
+// and a made-up destination is worse than a clean unknown-step-type.
+const stepRoutes = ( env = {} ) => {
+
+	const live = stepQueues( env );
+
+	return Object.freeze({
+		...live,
+		...Object.fromEntries(
+			Object.entries( RETIRED )
+				.filter( ( [ , replacement ] ) => live[ replacement ] )
+				.map( ( [ retired, replacement ] ) => [ retired, live[ replacement ] ] )
+		)
+	});
+
+};
+
 // Merchant-facing scope-drift copy.
 //
 // THIS IS A CROSS-REPO CONTRACT. drawbridge-sync writes it onto the connection
@@ -3277,4 +3653,4 @@ const resolveConnection = ( item, data, env = {} ) => {
 
 };
 
-export { AUTH_TYPES, GROUPS, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, RETIRED, STATUSES, STEPS, STEP_TYPES, accessToken, authToken, availableConnections, build, catalogConnections, connectFields, connectionSteps, connections, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, resolveConnection, runHook, scopesMessage, stepLabels, stepQueues, tokenSettings };
+export { AUTH_TYPES, GROUPS, HOOKS, HOOK_NAMES, INPUTS, OAUTH_FIELDS, OUTCOMES, RETIRED, STATUSES, STEPS, STEP_TYPES, accessToken, authToken, availableConnections, build, catalogConnections, connectFields, connectionSteps, connections, hookSupport, isStale, mergeSettings, projectConnection, publicConnectionKeys, publicSettingsBySlug, redactSettings, resolveConnection, runHook, scopesMessage, stepLabels, stepQueues, stepRoutes, tokenSettings };