@drawbridge/drawbridge-utils 0.0.176 → 0.0.177

package/dist/partner-ed2OfW1J.d.cts

@@ -0,0 +1,94 @@
+import { request } from './http.cjs';
+import { PARTNER_API_VERSION } from './shopify/constants.cjs';
+
+// 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 };