@drawbridge/drawbridge-utils 0.0.175 → 0.0.177

package/dist/oauth-DveZMLHx.d.ts

@@ -0,0 +1,527 @@
+import { encrypt, decrypt } from './encrypt.js';
+import { a as adminFetch } from './admin-C3HtEM6h.js';
+import { SHOPIFY_REQUIRED_SCOPES, SHOPIFY_ADMIN_API_VERSION, ACCESS_TOKEN_REFRESH_BUFFER_MS, REFRESH_TOKEN_LIFETIME_MS } from './shopify/constants.js';
+
+// The app's client_id / client_secret live encrypted in the `provider`
+// collection and are read at the point of use by the calling app — this
+// package never reads them from the environment. Every credential is
+// therefore a required parameter, and a missing one MUST throw here rather
+// than fall through: Shopify answers a token grant carrying no client_id with
+// an opaque OAuth error page, which reads as "the app is gone" rather than
+// "the caller passed no credential" — a config error with nothing in the logs
+// to say so.
+
+const required = ( name, value ) => {
+
+	if( ! value ){
+
+		throw new Error( 'Shopify ' + name + ' is required' );
+
+	}
+	return value;
+
+};
+
+// Diff a store's granted scopes (the `scope` string Shopify returns from
+// token exchange, persisted on the shop record's settings) against the
+// canonical required list. Shopify omits implied grants — write_foo covers
+// read_foo (same for the unauthenticated_ pair) — so a required read scope
+// counts as satisfied when its write counterpart was granted. Returns the
+// required scopes the store is missing; non-empty means the merchant needs
+// to re-open the app in Shopify admin (managed install re-prompts there).
+const missingScopes = ( granted ) => {
+
+	const grantedSet = new Set(
+		( Array.isArray( granted ) ? granted : String( granted || '' ).split( ',' ) )
+			.map( ( scope ) => scope.trim() )
+			.filter( Boolean )
+	);
+
+	const satisfied = ( scope ) =>
+		grantedSet.has( scope ) || grantedSet.has( scope.replace( /(^|_)read_/, '$1write_' ) );
+
+	return SHOPIFY_REQUIRED_SCOPES.filter( ( scope ) => ! satisfied( scope ) );
+
+};
+
+// Bare-fetch admin endpoint health check used by refreshAdminToken to
+// validate a freshly-rotated access token before persisting it. Throws on
+// failure so refreshAdminToken aborts the connection update if the new
+// token doesn't authenticate. A minimal GraphQL query rather than a REST
+// resource fetch — the Admin REST API is legacy and App-Store review
+// requires GraphQL-only.
+
+const ping = async ({ fetcher, adminAccessToken, domain }) => {
+
+	const response = await fetch(
+		`https://${ domain }/admin/api/${ SHOPIFY_ADMIN_API_VERSION }/graphql.json`,
+		{
+			body : JSON.stringify({ query : '{ shop { name } }' }),
+			headers : {
+				'Content-Type' : 'application/json',
+				'X-Shopify-Access-Token' : adminAccessToken
+			},
+			method : 'POST'
+		}
+	);
+
+	if( ! response.ok ){
+
+		const text = await response.text().catch( () => '' );
+		const error = new Error( response.status + ': ' + text );
+
+		error.status = response.status;
+
+		throw error;
+
+	}
+	// GraphQL can 200 with a top-level errors array (e.g. a token that
+	// authenticates but can't query) — treat that as a failed ping too.
+	const { errors } = await response.json().catch( () => ({}) );
+
+	if( errors?.length ){
+
+		throw new Error( 'GraphQL: ' + ( errors[ 0 ]?.message || 'unknown error' ) );
+
+	}
+};
+
+// Shopify's OAuth token endpoint reports a failed grant one of two ways: a
+// JSON body ({ error, error_description }, the documented shape) or — for
+// some rejections, e.g. a client_id whose app no longer exists at the shop —
+// a rendered HTML error page whose <title> reads "NNN - Oauth error <code>".
+// Extract a stable code from either so callers can act on it (see
+// application_cannot_be_found in drawbridge-sync's health check) instead of
+// string-matching the raw page body.
+const OAUTH_ERROR_TITLE_PATTERN = /Oauth error (\w+)/i;
+
+const parseOAuthErrorCode = ( text ) => {
+
+	try {
+
+		const parsed = JSON.parse( text );
+
+		if( parsed?.error ) return parsed.error;
+
+	} catch {}
+	return text.match( OAUTH_ERROR_TITLE_PATTERN )?.[ 1 ] || null;
+
+};
+
+const shopifyOAuthFetch = async ( url, body ) => {
+
+	const response = await fetch( url, {
+		method : 'POST',
+		headers : {
+			'Content-Type' : 'application/json'
+		},
+		body : JSON.stringify( body )
+	});
+
+	if( ! response.ok ){
+
+		const text = await response.text().catch( () => '' );
+		const error = new Error( response.status + ': ' + text );
+
+		error.status = response.status;
+		error.code = parseOAuthErrorCode( text );
+
+		throw error;
+
+	}
+	return response.json();
+
+};
+
+// Install-time token-setup calls (shop lookup, storefront access tokens)
+// go through the Admin GraphQL client in admin.js — the REST endpoints
+// they used to hit are legacy and App-Store review requires GraphQL-only.
+
+// Fetch the shop record (currency, id, name, myshopifyDomain) for a connected store.
+// `id` is returned as the bare numeric string (the GID tail) — it persists
+// to connection.source.id, and billing's toShopGid() re-derives the GID.
+
+const getShop = async ({ fetcher, adminAccessToken, shop }) => {
+
+	const data = await adminFetch({
+		fetcher,
+		adminAccessToken,
+		domain : shop,
+		query : `{
+			shop {
+				currencyCode
+				id
+				myshopifyDomain
+				name
+			}
+		}`
+	});
+
+	const shopData = data?.shop;
+
+	if( ! shopData?.id ){
+
+		throw new Error( 'Shopify shop lookup failed: no shop returned' );
+
+	}
+	return {
+		currency : shopData.currencyCode || null,
+		id : shopData.id.split( '/' ).pop(),
+		myshopifyDomain : shopData.myshopifyDomain,
+		name : shopData.name
+	};
+
+};
+
+// Issue a Storefront access token titled 'Drawbridge', reaping any prior
+// Drawbridge-titled tokens first — Shopify caps these at 100/shop and they're
+// immutable, so a fresh OAuth scope set requires minting a new one.
+
+const createStorefrontToken = async ({ fetcher, adminAccessToken, shop }) => {
+
+	try {
+
+		const listed = await adminFetch({
+		fetcher,
+			adminAccessToken,
+			domain : shop,
+			query : `{
+				shop {
+					storefrontAccessTokens(first: 100) {
+						edges {
+							node {
+								id
+								title
+							}
+						}
+					}
+				}
+			}`
+		});
+
+		const existing = ( listed?.shop?.storefrontAccessTokens?.edges || [] ).map( ( edge ) => edge?.node );
+		const orphaned = existing.filter( ( token ) => token?.title === 'Drawbridge' );
+
+		await Promise.allSettled(
+			orphaned.map( ( token ) => adminFetch({
+				adminAccessToken,
+				domain : shop,
+				query : `
+					mutation StorefrontAccessTokenDelete($input: StorefrontAccessTokenDeleteInput!) {
+						storefrontAccessTokenDelete(input: $input) {
+							deletedStorefrontAccessTokenId
+							userErrors {
+								field
+								message
+							}
+						}
+					}
+				`,
+				variables : {
+					input : {
+						id : token.id
+					}
+				}
+			}) )
+		);
+
+	} catch {}
+
+	const created = await adminFetch({
+		fetcher,
+		adminAccessToken,
+		domain : shop,
+		query : `
+			mutation StorefrontAccessTokenCreate($input: StorefrontAccessTokenInput!) {
+				storefrontAccessTokenCreate(input: $input) {
+					storefrontAccessToken {
+						accessToken
+					}
+					userErrors {
+						field
+						message
+					}
+				}
+			}
+		`,
+		variables : {
+			input : {
+				title : 'Drawbridge'
+			}
+		}
+	});
+
+	const createErrors = created?.storefrontAccessTokenCreate?.userErrors;
+
+	if( createErrors?.length ){
+
+		throw new Error( 'Shopify storefront token create failed: ' + createErrors[ 0 ].message );
+
+	}
+	return created?.storefrontAccessTokenCreate?.storefrontAccessToken?.accessToken || null;
+
+};
+
+// A Shopify connection carries its token blob one of two ways:
+//   * legacy 1:1 install — the token blob lives on `connection.settings` directly.
+//   * embedded / multi-org — `connection.settings` is a pointer `{ ref:'shop', shop }`
+//     and the token of record lives on the shared per-shop `shop` record: the offline
+//     session in `shop.settings` (accessToken/expires/refreshToken/refreshTokenExpires)
+//     and the long-lived storefront token in `shop.storefront` ({ token }). N org
+//     connections for the same store share that one record.
+// resolveTokenContext normalizes both into a single settings blob the callers read
+// (getAdminToken / product sync / storefront reads) and records where a token rotation
+// must be written back (`target`). Following the pointer needs a `controller` to read
+// the shop record; callers all pass one.
+
+const resolveTokenContext = async ({ connection, controller }) => {
+
+	const decrypted = connection?.settings ? decrypt( connection.settings ) : {};
+
+	// Legacy: the token blob is the connection's own settings. `raw` carries the
+	// stored (encrypted) blob so a rotation can compare-and-swap against it.
+	if( decrypted?.ref !== 'shop' ){
+
+		return {
+			raw : connection?.settings || null,
+			session : null,
+			settings : decrypted,
+			shop : null,
+			target : 'connection'
+		};
+
+	}
+	const shop = decrypted.shop;
+
+	// Pointer with no way (or nothing) to resolve — surface an empty blob so callers
+	// treat it as "no token" rather than throwing.
+	if( ! controller || ! shop ){
+
+		return { raw : null, session : {}, settings : {}, shop, target : 'shop' };
+
+	}
+	const record = await controller.get({ collection : 'shop', query : { shop } });
+	const session = record?.settings ? decrypt( record.settings ) : {};
+	const storefront = record?.storefront ? decrypt( record.storefront ) : null;
+
+	return {
+		raw : record?.settings || null,
+		session,
+		settings : {
+			adminAccessToken : session.accessToken || null,
+			refreshToken : session.refreshToken || null,
+			refreshTokenExpiresAt : session.refreshTokenExpires || null,
+			storefrontAccessToken : storefront?.token || null,
+			tokenExpiresAt : session.expires || null
+		},
+		shop,
+		target : 'shop'
+	};
+
+};
+
+// Returns the resolved token blob for a connection (admin + storefront tokens and
+// their expiries), following the shared-per-shop pointer when present. Backward
+// compatible: a legacy connection's settings pass straight through.
+
+const resolveConnectionSettings = async ({ fetcher, connection, controller }) => {
+
+	const { settings } = await resolveTokenContext({ connection, controller });
+
+	return settings;
+
+};
+
+// Rotates an admin access token using the stored refresh_token grant.
+// Shopify expiring-token installs return a fresh access_token + a fresh
+// refresh_token each refresh — and rotation RETIRES the old pair at Shopify
+// the moment the grant returns. Ordering and concurrency both follow from
+// that:
+//   * PERSIST BEFORE PING — the old pair is already dead once the grant
+//     returns, so failing to persist (e.g. a transient ping blip) would
+//     strand the only working refresh token forever. Persist first; ping
+//     after, purely as a visible health signal (a throw here fails the job,
+//     which retries against the persisted, valid pair).
+//   * COMPARE-AND-SWAP on the stored blob — the shared shop record has many
+//     writers (every org's health check, eager getAdminToken rotation, the
+//     embedded app's session writes). The write-back is keyed on the exact
+//     blob that was read; on a miss we converge on DB truth: if another
+//     writer rotated first, THEIR pair is the live one — return it and don't
+//     overwrite.
+
+const refreshAdminToken = async ({ fetcher, clientId, clientSecret, connection, controller }) => {
+
+	const { raw, session, settings, shop, target } = await resolveTokenContext({ connection, controller });
+	const domain = connection?.shop || settings.source?.domain || settings.domain || shop;
+	const { refreshToken } = settings;
+
+	const data = await shopifyOAuthFetch(
+		`https://${ domain }/admin/oauth/access_token`,
+		{
+			grant_type : 'refresh_token',
+			// Throw before the grant: rotation RETIRES the old pair the moment it
+			// returns, so a credential-less call that Shopify rejects opaquely is
+			// the one failure mode worth being loud about.
+			client_id : required( 'clientId', clientId ),
+			client_secret : required( 'clientSecret', clientSecret ),
+			refresh_token : refreshToken
+		}
+	);
+
+	const adminAccessToken = data.access_token;
+	const newRefreshToken = data.refresh_token;
+	const expiresIn = data.expires_in;
+	const tokenExpiresAt = expiresIn ? new Date( Date.now() + ( expiresIn * 1000 ) ) : null;
+	const refreshTokenExpiresAt = new Date( Date.now() + REFRESH_TOKEN_LIFETIME_MS );
+
+	let liveToken = adminAccessToken;
+
+	if( target === 'shop' ){
+
+		// Token of record is the shared `shop` record's offline session blob. Rotate
+		// in place, preserving the non-token session fields (id/state/scope/isOnline).
+		// The storefront token lives on a separate `shop.storefront` field, untouched.
+		const written = await controller.update({
+			collection : 'shop',
+			data : {
+				$set : {
+					settings : encrypt({
+						...session,
+						accessToken : adminAccessToken,
+						expires : tokenExpiresAt,
+						refreshToken : newRefreshToken,
+						refreshTokenExpires : refreshTokenExpiresAt
+					})
+				}
+			},
+			query : {
+				shop,
+				...( raw && { settings : raw } )
+			}
+		});
+
+		if( ! written ){
+
+			const current = await controller.get({ collection : 'shop', query : { shop } });
+
+			if( ! current?.settings ){
+
+				throw new Error( 'Shopify token refresh write-back failed: shop record missing for ' + shop );
+
+			}
+			const currentSession = decrypt( current.settings );
+
+			// A different live token means another writer's rotation landed (or ours
+			// did, under a controller that doesn't return the doc) — that pair is the
+			// token of record now.
+			if( currentSession?.accessToken && currentSession.accessToken !== settings.adminAccessToken ){
+
+				liveToken = currentSession.accessToken;
+
+			} else {
+
+				throw new Error( 'Shopify token refresh write-back failed for ' + shop );
+
+			}
+		}
+	} else {
+
+		const written = await controller.update({
+			collection : 'connection',
+			data : {
+				$set : {
+					settings : encrypt({
+						...settings,
+						adminAccessToken,
+						refreshToken : newRefreshToken,
+						refreshTokenExpiresAt,
+						tokenExpiresAt
+					})
+				}
+			},
+			query : {
+				id : connection.id,
+				...( raw && { settings : raw } )
+			}
+		});
+
+		if( ! written ){
+
+			const current = await controller.get({ collection : 'connection', query : { id : connection.id } });
+			const currentSettings = current?.settings ? decrypt( current.settings ) : null;
+
+			if( currentSettings?.adminAccessToken && currentSettings.adminAccessToken !== settings.adminAccessToken ){
+
+				liveToken = currentSettings.adminAccessToken;
+
+			} else {
+
+				throw new Error( 'Shopify token refresh write-back failed for connection ' + connection?.id );
+
+			}
+		}
+	}
+	// Health signal only — the pair is already persisted (see header comment).
+	await ping({ adminAccessToken : liveToken, domain });
+
+	return liveToken;
+
+};
+
+// Returns a live admin access token for the connection, resolving the token of
+// record (connection or shared shop record). For refresh-token installs, rotates
+// eagerly when `tokenExpiresAt` is within ACCESS_TOKEN_REFRESH_BUFFER_MS — Shopify
+// rejects expired tokens immediately, so we never make the actual API call with one.
+// Takes the app credentials only to hand them to that rotation — callers should
+// always pass them, since whether a given call rotates depends on the clock.
+
+const getAdminToken = async ({ fetcher, clientId, clientSecret, connection, controller }) => {
+
+	// VALIDATED HERE even though this function's own body never uses them.
+	//
+	// It only forwards them to refreshAdminToken, which throws — so without this
+	// a caller that omits them succeeds for as long as the stored token is fresh
+	// and fails weeks later, at rotation, on a code path nobody changed. Failing
+	// on the first call instead makes a missing credential a bug you find while
+	// writing the call site rather than an incident.
+	required( 'clientId', clientId );
+	required( 'clientSecret', clientSecret );
+
+	const settings = await resolveConnectionSettings({ connection, controller });
+	const { adminAccessToken, refreshToken, tokenExpiresAt } = settings;
+
+	if( ! adminAccessToken ){
+
+		return null;
+
+	}
+	if( ! refreshToken ){
+
+		return adminAccessToken;
+
+	}
+	const needsRefresh = ! tokenExpiresAt ||
+		new Date( tokenExpiresAt ) < new Date( Date.now() + ACCESS_TOKEN_REFRESH_BUFFER_MS );
+
+	if( needsRefresh ){
+
+		return refreshAdminToken({ clientId, clientSecret, connection, controller });
+
+	}
+	return adminAccessToken;
+
+};
+
+declare const shopifyOauth_SHOPIFY_REQUIRED_SCOPES: typeof SHOPIFY_REQUIRED_SCOPES;
+declare const shopifyOauth_createStorefrontToken: typeof createStorefrontToken;
+declare const shopifyOauth_getAdminToken: typeof getAdminToken;
+declare const shopifyOauth_getShop: typeof getShop;
+declare const shopifyOauth_missingScopes: typeof missingScopes;
+declare const shopifyOauth_ping: typeof ping;
+declare const shopifyOauth_refreshAdminToken: typeof refreshAdminToken;
+declare const shopifyOauth_resolveConnectionSettings: typeof resolveConnectionSettings;
+declare namespace shopifyOauth {
+  export { shopifyOauth_SHOPIFY_REQUIRED_SCOPES as SHOPIFY_REQUIRED_SCOPES, shopifyOauth_createStorefrontToken as createStorefrontToken, shopifyOauth_getAdminToken as getAdminToken, shopifyOauth_getShop as getShop, shopifyOauth_missingScopes as missingScopes, shopifyOauth_ping as ping, shopifyOauth_refreshAdminToken as refreshAdminToken, shopifyOauth_resolveConnectionSettings as resolveConnectionSettings };
+}
+
+export { getShop as a, resolveConnectionSettings as b, createStorefrontToken as c, getAdminToken as g, missingScopes as m, ping as p, refreshAdminToken as r, shopifyOauth as s };

package/dist/partner-BOZltuh2.d.ts

@@ -0,0 +1,94 @@
+import { request } from './http.js';
+import { PARTNER_API_VERSION } from './shopify/constants.js';
+
+// The Partner API is the ONE place meter billing is observable. The Admin API
+// never materializes managed-pricing meters as subscription line items
+// (measured 2026-09-04, every version), and the App Events API answers 202
+// whether or not anything billed — but a usage charge that ACCRUED appears
+// here as a CHARGE_USAGE event, with the charge id, the amount, and the
+// planHandle it classified under. Authenticated with a Partner API client
+// token (Partner Dashboard → Settings → Partner API clients, Manage-apps
+// permission), scoped to a partner organization.
+
+const PARTNER_API = 'https://partners.shopify.com';
+
+// The latest usage-charge accruals for an app, newest first, optionally
+// scoped to one shop. Returns plain rows the callers stamp and reconcile
+// with; throws on any GraphQL error — an unreadable ledger must never read
+// as an empty one.
+const getUsageChargeEvents = async ({ fetcher, appId, first = 10, occurredAtMin, organizationId, partnerToken, shopId }) => {
+
+	if( ! partnerToken || ! organizationId || ! appId ){
+
+		throw new Error( 'getUsageChargeEvents requires partnerToken, organizationId, and appId' );
+
+	}
+	const data = await request({
+		fetcher,
+		method : 'POST',
+		url : PARTNER_API + '/' + organizationId + '/api/' + PARTNER_API_VERSION + '/graphql.json',
+		headers : {
+			'X-Shopify-Access-Token' : partnerToken
+		},
+		body : {
+			query : `query usageCharges( $filter : EventFilterInput!, $first : Int! ) {
+				events( filter : $filter, orderBy : OCCURRED_AT_DESC, first : $first ) {
+					edges {
+						node {
+							id
+							occurredAt
+							eventType
+							shop { id myshopifyDomain }
+							... on Charge {
+								chargeId
+								chargeType
+								amount { amount currencyCode }
+								usageQuantity
+								planHandle
+								description
+							}
+						}
+					}
+					pageInfo { hasNextPage endCursor }
+				}
+			}`,
+			variables : {
+				filter : {
+					eventTypes : [ 'CHARGE_USAGE' ],
+					subjectId : String( appId ),
+					...( occurredAtMin && { occurredAtMin }),
+					...( shopId && { shopId : String( shopId ) })
+				},
+				first
+			}
+		}
+	});
+
+	if( data?.errors?.length ){
+
+		throw new Error( 'Shopify partner events query failed: ' + data.errors.map( ( entry ) => entry.message ).join( '; ' ) );
+
+	}
+	return ( data?.data?.events?.edges || [] ).map( ( edge ) => ({
+		amount : edge.node?.amount || null,
+		chargeId : edge.node?.chargeId || null,
+		// USAGE vs the recurring plan charge an approval emits — the
+		// disambiguator callers filter on.
+		chargeType : edge.node?.chargeType || null,
+		description : edge.node?.description || null,
+		eventType : edge.node?.eventType || null,
+		id : edge.node?.id || null,
+		occurredAt : edge.node?.occurredAt || null,
+		planHandle : edge.node?.planHandle || null,
+		shop : edge.node?.shop || null,
+		usageQuantity : edge.node?.usageQuantity ?? null
+	}) );
+
+};
+
+declare const shopifyPartner_getUsageChargeEvents: typeof getUsageChargeEvents;
+declare namespace shopifyPartner {
+  export { shopifyPartner_getUsageChargeEvents as getUsageChargeEvents };
+}
+
+export { getUsageChargeEvents as g, shopifyPartner as s };