@drawbridge/drawbridge-utils 0.0.175 → 0.0.177

package/dist/billing-Bc4yo9XG.d.cts

@@ -0,0 +1,175 @@
+import { request } from './http.cjs';
+import { SHOPIFY_APP_API_VERSION } from './shopify/constants.cjs';
+
+// Shopify App Pricing usage billing goes through the App Events API
+// (api.shopify.com), NOT the shop-scoped Admin Billing API. Events are
+// app-level: authenticated with the app's own client credentials and addressed
+// by `shop_id`, so no merchant admin token or subscription line item is needed.
+// An event whose `event_handle` matches a meter configured in the app's pricing
+// is billed as `value × the meter's per-unit rate` within the current cycle.
+// There is no capped amount — accrual is uncapped.
+
+const APP_API = 'https://api.shopify.com';
+
+// Env-overridable so a stable App Events version can be adopted without a
+// republish; defaults to the only documented version today ('unstable').
+const APP_API_VERSION = process.env.SHOPIFY_APP_API_VERSION || SHOPIFY_APP_API_VERSION;
+
+// App-level bearer tokens from client_credentials, cached per clientId until
+// just before they expire — one process can serve several apps' credentials,
+// and a shared slot would send app A's token for app B's billing event.
+// Cleared + re-fetched on a 401.
+const cachedTokens = {};
+
+const fetchAppToken = async ({ clientId, clientSecret, fetcher }) => {
+
+	const data = await request({
+		fetcher,
+		method : 'POST',
+		url : APP_API + '/auth/access_token',
+		body : {
+			client_id : clientId,
+			client_secret : clientSecret,
+			grant_type : 'client_credentials'
+		}
+	});
+
+	if( ! data?.access_token ){
+
+		throw new Error( 'Shopify app token request failed: no access token returned' );
+
+	}
+	const ttl = ( data.expires_in ? data.expires_in * 1000 : 60 * 60 * 1000 );
+
+	cachedTokens[ clientId ] = {
+		expiresAt : Date.now() + ttl - ( 60 * 1000 ),
+		token : data.access_token
+	};
+
+	return data.access_token;
+
+};
+
+const getAppToken = async ({ clientId, clientSecret, fetcher }) => {
+
+	const cached = cachedTokens[ clientId ];
+
+	if( cached && cached.expiresAt > Date.now() ){
+
+		return cached.token;
+
+	}
+	return fetchAppToken({ clientId, clientSecret, fetcher });
+
+};
+
+const toShopGid = ( shopId ) => (
+	String( shopId ).startsWith( 'gid://' ) ? String( shopId ) : ( 'gid://shopify/Shop/' + shopId )
+);
+
+// Send an event to the Shopify App Events API for an app-installed store. When
+// `eventHandle` matches a usage meter in the app's pricing config, Shopify bills
+// `value × the meter's per-unit rate` — so this doubles as the usage-billing call.
+// `value` is the event quantity (e.g. the commission in cents).
+//
+// `eventHandle` is REQUIRED — deliberately no default. The handle is the string
+// that decides whether the event bills or is silently ingested as a plain
+// custom event, so every caller must pass the value it verified (the shopify
+// manifest's events.order.handle for order billing); a package-level fallback
+// is exactly the second unvalidated copy that let handle drift go unnoticed.
+// `SHOPIFY_USAGE_ORDERS_EVENT_HANDLE` in lib/constants.js remains the recorded
+// contract value the manifest must agree with. `idempotencyKey` (e.g. the
+// order id) dedupes retries — Shopify's window is 24h for custom events but
+// PERMANENT for billing events. Retries once on a 401 (stale cached token).
+//
+// `revision` suffixes the idempotency key ('.r' + revision) for a corrective
+// resend once a key has been spent — a 202 consumes the key whether or not the
+// event actually billed. The encoding lives HERE, and only here, because both
+// drawbridge-sync's billing handler and drawbridge-api's recovery migration
+// resend the same orders: two hand-rolled copies of the suffix would drift, and
+// against a permanent idempotency ledger a drifted key either double-bills a
+// merchant or misses the key it meant to supersede. Callers pass the bare order
+// id plus revision and never build keys themselves.
+//
+// `clientId` / `clientSecret` are the app's own credentials — read from the
+// encrypted `provider` record by the calling app, never from the environment —
+// and back the client_credentials grant this authenticates with.
+//
+// `reference` is an optional opaque tracing attribute (e.g. the order document
+// id) carried alongside the required `value`. Attributes allow at most 15
+// scalar keys and must never contain personal data — pass ids, not people.
+const sendAppEvent = async ({ fetcher, clientId, clientSecret, eventHandle, idempotencyKey, reference, revision, shopId, timestamp, value }) => {
+
+	if( ! shopId || ! eventHandle || ! ( Number( value ) > 0 ) ){
+
+		throw new Error( 'sendAppEvent requires shopId, eventHandle, and a positive value' );
+
+	}
+	// Checked here, not in fetchAppToken, so a missing credential fails the same
+	// way on every call. Deferred to the grant it would ride the module-level
+	// cached token until that expired, turning a config error into an
+	// intermittent billing outage against a PERMANENT idempotency ledger.
+	if( ! clientId || ! clientSecret ){
+
+		throw new Error( 'sendAppEvent requires clientId and clientSecret' );
+
+	}
+	// The 64-char cap truncates the BASE, never the suffix — a cap that ate
+	// '.rN' would collide a corrective resend with the spent original. The
+	// Math.max keeps the slice bound non-negative should a revision ever
+	// arrive long enough to swallow the whole budget.
+	const suffix = ( revision ? '.r' + revision : '' );
+
+	const key = idempotencyKey && (
+		String( idempotencyKey ).slice( 0, Math.max( 0, 64 - suffix.length ) ) + suffix
+	);
+
+	const body = {
+		attributes : {
+			value : Number( value ),
+			...( reference && {
+				reference : String( reference ).slice( 0, 128 )
+			})
+		},
+		event_handle : eventHandle,
+		shop_id : toShopGid( shopId ),
+		timestamp : timestamp || new Date().toISOString(),
+		...( key && {
+			idempotency_key : key
+		})
+	};
+
+	const send = async ( token ) => request({
+		method : 'POST',
+		url : APP_API + '/app/' + APP_API_VERSION + '/events',
+		headers : {
+			'Authorization' : 'Bearer ' + token
+		},
+		body
+	});
+
+	try {
+
+		return await send( await getAppToken({ clientId, clientSecret, fetcher }) );
+
+	} catch ( error ) {
+
+		if( error?.status === 401 ){
+
+			delete cachedTokens[ clientId ];
+
+			return send( await fetchAppToken({ clientId, clientSecret, fetcher }) );
+
+		}
+		throw error;
+
+	}
+
+};
+
+declare const shopifyBilling_sendAppEvent: typeof sendAppEvent;
+declare namespace shopifyBilling {
+  export { shopifyBilling_sendAppEvent as sendAppEvent };
+}
+
+export { shopifyBilling as a, sendAppEvent as s };

package/dist/billing-mNsKflmQ.d.ts

@@ -0,0 +1,175 @@
+import { request } from './http.js';
+import { SHOPIFY_APP_API_VERSION } from './shopify/constants.js';
+
+// Shopify App Pricing usage billing goes through the App Events API
+// (api.shopify.com), NOT the shop-scoped Admin Billing API. Events are
+// app-level: authenticated with the app's own client credentials and addressed
+// by `shop_id`, so no merchant admin token or subscription line item is needed.
+// An event whose `event_handle` matches a meter configured in the app's pricing
+// is billed as `value × the meter's per-unit rate` within the current cycle.
+// There is no capped amount — accrual is uncapped.
+
+const APP_API = 'https://api.shopify.com';
+
+// Env-overridable so a stable App Events version can be adopted without a
+// republish; defaults to the only documented version today ('unstable').
+const APP_API_VERSION = process.env.SHOPIFY_APP_API_VERSION || SHOPIFY_APP_API_VERSION;
+
+// App-level bearer tokens from client_credentials, cached per clientId until
+// just before they expire — one process can serve several apps' credentials,
+// and a shared slot would send app A's token for app B's billing event.
+// Cleared + re-fetched on a 401.
+const cachedTokens = {};
+
+const fetchAppToken = async ({ clientId, clientSecret, fetcher }) => {
+
+	const data = await request({
+		fetcher,
+		method : 'POST',
+		url : APP_API + '/auth/access_token',
+		body : {
+			client_id : clientId,
+			client_secret : clientSecret,
+			grant_type : 'client_credentials'
+		}
+	});
+
+	if( ! data?.access_token ){
+
+		throw new Error( 'Shopify app token request failed: no access token returned' );
+
+	}
+	const ttl = ( data.expires_in ? data.expires_in * 1000 : 60 * 60 * 1000 );
+
+	cachedTokens[ clientId ] = {
+		expiresAt : Date.now() + ttl - ( 60 * 1000 ),
+		token : data.access_token
+	};
+
+	return data.access_token;
+
+};
+
+const getAppToken = async ({ clientId, clientSecret, fetcher }) => {
+
+	const cached = cachedTokens[ clientId ];
+
+	if( cached && cached.expiresAt > Date.now() ){
+
+		return cached.token;
+
+	}
+	return fetchAppToken({ clientId, clientSecret, fetcher });
+
+};
+
+const toShopGid = ( shopId ) => (
+	String( shopId ).startsWith( 'gid://' ) ? String( shopId ) : ( 'gid://shopify/Shop/' + shopId )
+);
+
+// Send an event to the Shopify App Events API for an app-installed store. When
+// `eventHandle` matches a usage meter in the app's pricing config, Shopify bills
+// `value × the meter's per-unit rate` — so this doubles as the usage-billing call.
+// `value` is the event quantity (e.g. the commission in cents).
+//
+// `eventHandle` is REQUIRED — deliberately no default. The handle is the string
+// that decides whether the event bills or is silently ingested as a plain
+// custom event, so every caller must pass the value it verified (the shopify
+// manifest's events.order.handle for order billing); a package-level fallback
+// is exactly the second unvalidated copy that let handle drift go unnoticed.
+// `SHOPIFY_USAGE_ORDERS_EVENT_HANDLE` in lib/constants.js remains the recorded
+// contract value the manifest must agree with. `idempotencyKey` (e.g. the
+// order id) dedupes retries — Shopify's window is 24h for custom events but
+// PERMANENT for billing events. Retries once on a 401 (stale cached token).
+//
+// `revision` suffixes the idempotency key ('.r' + revision) for a corrective
+// resend once a key has been spent — a 202 consumes the key whether or not the
+// event actually billed. The encoding lives HERE, and only here, because both
+// drawbridge-sync's billing handler and drawbridge-api's recovery migration
+// resend the same orders: two hand-rolled copies of the suffix would drift, and
+// against a permanent idempotency ledger a drifted key either double-bills a
+// merchant or misses the key it meant to supersede. Callers pass the bare order
+// id plus revision and never build keys themselves.
+//
+// `clientId` / `clientSecret` are the app's own credentials — read from the
+// encrypted `provider` record by the calling app, never from the environment —
+// and back the client_credentials grant this authenticates with.
+//
+// `reference` is an optional opaque tracing attribute (e.g. the order document
+// id) carried alongside the required `value`. Attributes allow at most 15
+// scalar keys and must never contain personal data — pass ids, not people.
+const sendAppEvent = async ({ fetcher, clientId, clientSecret, eventHandle, idempotencyKey, reference, revision, shopId, timestamp, value }) => {
+
+	if( ! shopId || ! eventHandle || ! ( Number( value ) > 0 ) ){
+
+		throw new Error( 'sendAppEvent requires shopId, eventHandle, and a positive value' );
+
+	}
+	// Checked here, not in fetchAppToken, so a missing credential fails the same
+	// way on every call. Deferred to the grant it would ride the module-level
+	// cached token until that expired, turning a config error into an
+	// intermittent billing outage against a PERMANENT idempotency ledger.
+	if( ! clientId || ! clientSecret ){
+
+		throw new Error( 'sendAppEvent requires clientId and clientSecret' );
+
+	}
+	// The 64-char cap truncates the BASE, never the suffix — a cap that ate
+	// '.rN' would collide a corrective resend with the spent original. The
+	// Math.max keeps the slice bound non-negative should a revision ever
+	// arrive long enough to swallow the whole budget.
+	const suffix = ( revision ? '.r' + revision : '' );
+
+	const key = idempotencyKey && (
+		String( idempotencyKey ).slice( 0, Math.max( 0, 64 - suffix.length ) ) + suffix
+	);
+
+	const body = {
+		attributes : {
+			value : Number( value ),
+			...( reference && {
+				reference : String( reference ).slice( 0, 128 )
+			})
+		},
+		event_handle : eventHandle,
+		shop_id : toShopGid( shopId ),
+		timestamp : timestamp || new Date().toISOString(),
+		...( key && {
+			idempotency_key : key
+		})
+	};
+
+	const send = async ( token ) => request({
+		method : 'POST',
+		url : APP_API + '/app/' + APP_API_VERSION + '/events',
+		headers : {
+			'Authorization' : 'Bearer ' + token
+		},
+		body
+	});
+
+	try {
+
+		return await send( await getAppToken({ clientId, clientSecret, fetcher }) );
+
+	} catch ( error ) {
+
+		if( error?.status === 401 ){
+
+			delete cachedTokens[ clientId ];
+
+			return send( await fetchAppToken({ clientId, clientSecret, fetcher }) );
+
+		}
+		throw error;
+
+	}
+
+};
+
+declare const shopifyBilling_sendAppEvent: typeof sendAppEvent;
+declare namespace shopifyBilling {
+  export { shopifyBilling_sendAppEvent as sendAppEvent };
+}
+
+export { shopifyBilling as a, sendAppEvent as s };

package/dist/billing.d.cts

@@ -13,7 +13,7 @@ import { createLogger } from '@drawbridge/drawbridge-telemetry';
 //
 // Sits on top of transactions.js (the generic credit/debit money rail) and
 // usage.js (the action-ledger + usage-totals primitives). Shopify order fees are
-// NOT billed here — they meter through @drawbridge/shopify's recordUsage and stay
+// NOT billed here — they meter through the Shopify client's usage records and stay
 // Shopify-only by design. The Stripe meter EMIT for actions also stays in the
 // Stripe layer (utils must not depend on Stripe); billing.action.sum gives that
 // layer the authoritative number to report.

package/dist/billing.d.ts

@@ -13,7 +13,7 @@ import { createLogger } from '@drawbridge/drawbridge-telemetry';
 //
 // Sits on top of transactions.js (the generic credit/debit money rail) and
 // usage.js (the action-ledger + usage-totals primitives). Shopify order fees are
-// NOT billed here — they meter through @drawbridge/shopify's recordUsage and stay
+// NOT billed here — they meter through the Shopify client's usage records and stay
 // Shopify-only by design. The Stripe meter EMIT for actions also stays in the
 // Stripe layer (utils must not depend on Stripe); billing.action.sum gives that
 // layer the authoritative number to report.