@drawbridge/drawbridge-utils 0.0.136 → 0.0.139

package/dist/connections/index.d.ts

@@ -7,6 +7,7 @@ import { channels } from '../pricing.js';
 import { customAlphabet } from 'nanoid';
 import { toCanonicalEmail } from '../email.js';
 import { conversionRate } from '../plans.js';
+import { slugify } from '../slugify.js';
 import { safeRequest } from '../safe-http.js';
 import 'libphonenumber-js';
 import '../billing.js';
@@ -18,6 +19,7 @@ import '../index.js';
 import 'currency-codes';
 import '../color.js';
 import 'tinycolor2';
+import 'slugify';
 import 'dns';
 import 'node:http';
 import 'node:https';
@@ -912,6 +914,9 @@ var attentive = {
 	},
 	// A contact destination, like Klaviyo and Mailchimp — a merchant could
 	// reasonably keep several up to date at once.
+	// No vendor-facing event identities — declared empty so the contract stays
+	// explicit: a vendor that gains one adds it here, never as a side channel.
+	events : {},
 	exclusive : false,
 	feature : 'organization:connection:attentive',
 	fields : [
@@ -1703,6 +1708,9 @@ var drawbridge = {
 			'Nothing to do. These steps are available in every workflow builder.'
 		]
 	},
+	// No vendor-facing event identities — declared empty so the contract stays
+	// explicit: a vendor that gains one adds it here, never as a side channel.
+	events : {},
 	exclusive : false,
 	fields : [],
 	group : 'developer',
@@ -2750,6 +2758,9 @@ var klaviyo = {
 	// current — so the exclusivity that once applied when these were SENDERS is
 	// deliberately gone. That was removed once already; declaring it out loud is
 	// what stops it coming back by inference.
+	// No vendor-facing event identities — declared empty so the contract stays
+	// explicit: a vendor that gains one adds it here, never as a side channel.
+	events : {},
 	exclusive : false,
 	feature : 'organization:connection:klaviyo',
 	fields : [
@@ -3392,6 +3403,9 @@ var mailchimp = {
 	// picking two providers to send the same mail was meaningless. As contact
 	// syncs they are destinations, and a merchant could reasonably keep several
 	// up to date, so the exclusivity is gone.
+	// No vendor-facing event identities — declared empty so the contract stays
+	// explicit: a vendor that gains one adds it here, never as a side channel.
+	events : {},
 	exclusive : false,
 	feature : 'organization:connection:mailchimp',
 	fields : [
@@ -3831,6 +3845,24 @@ const attributeLineItems = ( lineItems = [] ) => lineItems.reduce(
 // types them into a checkout.
 const generateDiscountCode = customAlphabet( '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', 8 );
 
+// THE USAGE METER'S EVENT HANDLE — the string that decides whether an order's
+// billing event bills or is silently ingested as a plain custom event. It must
+// equal, case-sensitively, the meter HANDLE configured on the app's plan in
+// the Dev Dashboard (the plan editor's Handle field — display names prove
+// nothing) and the SHOPIFY_USAGE_ORDERS_EVENT_HANDLE default in
+// @drawbridge/shopify, which this package cannot import. This is the single
+// mint point on the utils side: the transaction id is prefixed with it, the
+// billing enqueue carries it, and the manifest publishes it under
+// events.order.handle — so drawbridge-sync can refuse to send an event whose
+// transaction and handle disagree instead of burning a permanent idempotency
+// key on a mistraceable event.
+//
+// Slugified at definition: a handle can carry no spaces or capitals, and
+// classification is case-sensitive, so a future edit of the literal is forced
+// into the only shape a meter handle can legally take before it can mint a
+// single transaction.
+const ORDER_EVENT_HANDLE = slugify( 'drawbridge-orders' );
+
 // Rotate before the window closes rather than at it: Shopify's refresh token has
 // an expiry, and a rotation attempted after it has passed cannot succeed.
 const REFRESH_TOKEN_FRESHNESS_BUFFER_MS = 5 * 24 * 60 * 60 * 1000;
@@ -3919,7 +3951,7 @@ var shopify = {
 		guide : [
 			'Open the Drawbridge listing on the Shopify App Store.',
 			'Install the app on the store you want to connect. It opens in Shopify admin and stays there.',
-			'Choose a plan when Shopify asks. The connection shows Pending until you do, then Active.',
+			'Approve the Drawbridge plan when prompted — during install, or from the connection page here. The connection shows Pending until you do, then Active.',
 			'Come back here — the connections list updates on its own once the install lands.'
 		],
 		// Names where the link GOES rather than what it does: installing happens on
@@ -3933,6 +3965,29 @@ var shopify = {
 	// ONE STORE PER ORGANIZATION. Two Shopify stores on one org would give every
 	// attributed order two possible sources.
 	exclusive : true,
+	// VENDOR-FACING EVENT IDENTITY, published so readers outside this package
+	// (drawbridge-sync's usage queue, an operator checking the Dev Dashboard)
+	// see the same handle the order hook mints into transactions and enqueues.
+	events : {
+		order : {
+			handle : ORDER_EVENT_HANDLE,
+			// THE SUBSCRIPTION THE APP MINTS FOR ITSELF (Billing API, not the
+			// managed-pricing meter system): a $0 recurring line plus this usage
+			// line, approved by the org owner at Shopify's confirmation screen.
+			// `terms` is the merchant-visible consent copy; "up to" because the
+			// actual rate is plan-derived (conversionRate) and must never exceed
+			// what was approved. cappedAmount bounds one 30-day cycle's usage
+			// charges — a record beyond it errors until the merchant raises it.
+			// ponytail: $1,000 cap ≈ $66k attributed revenue/cycle at 1.5%; raise
+			// via a re-approved subscription when a merchant outgrows it.
+			pricing : {
+				cappedAmount : 1000,
+				currency : 'usd',
+				name : 'Drawbridge Orders',
+				terms : 'Up to 1.5% of revenue from orders attributed to Drawbridge campaigns'
+			}
+		}
+	},
 	feature : 'organization:connection:shopify',
 	fields : [
 		{
@@ -4535,9 +4590,39 @@ var shopify = {
 				// was charged when the order was first recorded. Enqueues run after
 				// the transaction commits, so the job can never observe rows that
 				// roll back.
-				const enqueues = ( org?.billingProvider === 'shopify' && fee > 0 && connection?.source?.id && ! backfill )
+				const billable = org?.billingProvider === 'shopify' && fee > 0 && ! backfill;
+
+				// A billable order with no shop id is revenue lost SILENTLY — the
+				// gate below just yields no job, the order records normally, and the
+				// connection looks healthy. An Error (not a warn) because this is
+				// money: the order id goes in the MESSAGE, since Sentry matches
+				// titles, and the health check's source self-heal is what makes the
+				// state rare enough to page on.
+				if( billable && ! connection?.source?.id ){
+
+					logger?.error?.( new Error(
+						'shopify.usage.billing.skipped on order ' + orderId + ': '
+						+ Math.round( fee * 100 ) + ' cents not billed — connection '
+						+ connection?.id + ' has no source.id'
+					), {
+						extra : {
+							connectionId : connection?.id,
+							fee,
+							orderDocId,
+							orderId : String( orderId )
+						}
+					});
+
+				}
+
+				const enqueues = ( billable && connection?.source?.id )
 					? [ {
 						data : {
+							// The meter handle travels WITH the job so the sender can
+							// verify it against the transaction prefix and refuse a
+							// drifted pair — idempotency keys are permanent, so a
+							// mistraceable event can never be resent under its own key.
+							handle : ORDER_EVENT_HANDLE,
 							idempotencyKey : String( orderId ),
 							orderDocId,
 							orderId : String( orderId ),
@@ -4547,7 +4632,7 @@ var shopify = {
 							// here — the event handle plus the order id — and sent as the
 							// event's `reference`. queue/usage.js stamps the same id onto
 							// the order as billed.transaction.
-							transaction : 'drawbridge-orders.' + orderId,
+							transaction : ORDER_EVENT_HANDLE + '.' + orderId,
 							value : Math.round( fee * 100 )
 						},
 						name : 'billing',
@@ -4728,7 +4813,7 @@ var shopify = {
 			// access token still works, reconciles the scopes the store granted
 			// against the ones the app now needs, and queues a webhook
 			// reconciliation.
-			health : async ( { connection, workflow }, { adminToken, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {} ) => {
+			health : async ( { connection, workflow }, { adminToken, logger, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {} ) => {
 
 				const request = {
 					connectionId : workflow.connection,
@@ -4772,7 +4857,102 @@ var shopify = {
 					// hook needs its RESULT to compose the message below.
 					const scopesMissing = await reconcileScopes({ shop : connection.shop });
 
+					// THE BILLING IDENTITY SELF-HEALS HERE, because nothing else ever
+					// repairs it. `source.id` is written once, at link time, from a
+					// getShop call inside a best-effort catch — a transient miss there
+					// used to leave the connection permanently unbillable while looking
+					// perfectly healthy: the order hook's billing enqueue gates on
+					// `source.id` and skips without it. The daily health check already
+					// holds a live admin token, so a missing source is one lookup away
+					// from fixed.
+					//
+					// `metered` rides on the same pass: whether the merchant's ACTIVE
+					// approval carries a usage line item. A meter added to the app's
+					// pricing config is never retroactive — it bills only from the
+					// moment the merchant approves the plan version that carries it —
+					// so an approval with no usage line means every order's usage event
+					// is 202-accepted and silently never billed. Stamped on the
+					// connection so tasks() can tell the merchant to re-approve, and
+					// probed every run so a re-approval clears the card within a day.
+					//
+					// Best-effort by design: the ping above already proved access, so a
+					// blip in either lookup must not error a healthy connection — the
+					// next daily run retries. `currency` is deliberately NOT repaired
+					// here: the connection schema constrains it to the billing-FX enum,
+					// which this package cannot see, so the live value is surfaced in
+					// the response for an operator instead of risking a validation
+					// failure on the write.
+					const writes = [];
+
+					let source = connection.source || null;
+					let sourceRepaired = false;
+					let metered = source?.metered ?? null;
+					let shopCurrency = null;
+					let billingProbeFailed = false;
+
+					try {
+
+						if( ! source?.id ){
+
+							const shopData = await shopify.oauth.getShop({ adminAccessToken, shop : connection.shop });
+
+							source = {
+								domain : shopData.myshopifyDomain,
+								id : String( shopData.id ),
+								label : shopData.name
+							};
+							shopCurrency = String( shopData.currency || '' ).toLowerCase() || null;
+							sourceRepaired = true;
+
+						}
+
+						const { subscriptions } = await shopify.admin.getActiveAppSubscriptions({
+							adminAccessToken,
+							domain : connection.shop
+						});
+
+						// Only an ACTIVE approval says anything about metering — no
+						// subscriptions (mid-install, plan pending) leaves the stamp
+						// untouched rather than asserting false from silence. The
+						// every-boolean guard is version skew insurance: an older
+						// @drawbridge/shopify returns subscriptions without the flag,
+						// and reading that silence as false would nag every healthy
+						// merchant to re-approve a plan that is fine.
+						if( subscriptions.length && subscriptions.every( ( subscription ) => typeof subscription.metered === 'boolean' ) ){
+
+							metered = subscriptions.some( ( subscription ) => subscription.metered );
+
+						}
+
+					} catch ( probeError ) {
+
+						billingProbeFailed = true;
+
+						logger?.warn?.( 'shopify.health.billing.probe.failed', {
+							connectionId : connection.id,
+							message : probeError?.message,
+							shop : connection.shop
+						});
+
+					}
+
+					if( sourceRepaired || ( metered !== null && metered !== ( connection.source?.metered ?? null ) ) ){
+
+						writes.push({
+							collection : 'connection',
+							data : {
+								$set : sourceRepaired
+									? { source : { ...source, ...( metered !== null && { metered }) } }
+									: { 'source.metered' : metered }
+							},
+							operation : 'update',
+							query : { id : connection.id }
+						});
+
+					}
+
 					return {
+						writes,
 						enqueues : [ {
 							data : {
 								data : {
@@ -4785,17 +4965,26 @@ var shopify = {
 							options : { jobId : 'connection.update.register.' + workflow.connection + '.' + randomUUID() },
 							queue : 'connection'
 						} ],
-						message : scopesMissing?.length
+						message : ( scopesMissing?.length
 							? 'Health check: ping ok, webhooks reconciled — connection errored, granted scopes are missing: ' + scopesMissing.join( ', ' ) + '.'
 							: refreshTokenRotated
 								? 'Health check passed — refresh token rotated, ping ok, webhooks reconciled.'
-								: 'Health check passed — ping ok, webhooks reconciled.',
+								: 'Health check passed — ping ok, webhooks reconciled.'
+						)
+							+ ( sourceRepaired ? ' Billing source repaired from the live shop.' : '' )
+							+ ( metered === false ? ' No usage line on the store\'s approved plan — order billing needs the merchant to approve the updated plan.' : '' ),
 						request,
 						response : {
+							billingProbeFailed,
+							metered,
 							pingedAt : new Date(),
 							refreshTokenExpiresAt : refreshTokenExpiresAt || null,
 							refreshTokenRotated,
 							scopesMissing,
+							// The live settlement currency, for an operator — never
+							// written, see above.
+							...( shopCurrency && { shopCurrency }),
+							sourceRepaired,
 							webhookReconciliationQueued : true
 						}
 					};
@@ -5115,15 +5304,38 @@ var shopify = {
 	//
 	// Scope drift is NOT here: drawbridge-sync writes it onto the connection
 	// document, and the document's own warnings render beside these.
-	tasks : ( data ) => ( data?.status === 'pending'
-		? [
-			{
-				message : 'Open the Drawbridge app in your Shopify admin and choose a plan. The connection activates once Shopify confirms it.',
-				title : 'Choose a plan in Shopify'
-			}
-		]
-		: []
-	),
+	// Both cards carry `action : 'billing'`: the dashboard renders it as a real
+	// button that mints the corrective subscription (POST .../billing) and sends
+	// the owner to Shopify's confirmation screen — the fix lives in OUR
+	// dashboard, and the one Shopify-hosted step is the charge consent no app
+	// can perform for a merchant.
+	tasks : ( data ) => [
+		...( data?.status === 'pending'
+			? [
+				{
+					action : 'billing',
+					message : 'Approve the Drawbridge plan to activate this connection. You\'ll confirm the pricing on Shopify, then everything else happens here.',
+					title : 'Approve your plan'
+				}
+			]
+			: []
+		),
+		// The store's ACTIVE approval carries no usage component — stamped by
+		// the daily health check and the approval webhook (`source.metered`).
+		// Approved pricing is never retroactive, so the fix is a fresh approval.
+		// Gated on an EXPLICIT false — a connection the probe hasn't reached
+		// (or couldn't read) shows nothing rather than nagging on silence.
+		...( data?.status === 'active' && data?.source?.metered === false
+			? [
+				{
+					action : 'billing',
+					message : 'Order billing isn\'t set up for this store, so campaign-attributed orders aren\'t being charged. Approve the updated plan to fix it — one click here, one confirmation on Shopify.',
+					title : 'Fix order billing'
+				}
+			]
+			: []
+		)
+	],
 	title : 'Shopify'
 };
 
@@ -5161,6 +5373,9 @@ var webhook = {
 	// Nothing to be exclusive with — there is no second webhook vendor, and a
 	// merchant with two endpoints is a step-level choice rather than a second
 	// connection.
+	// No vendor-facing event identities — declared empty so the contract stays
+	// explicit: a vendor that gains one adds it here, never as a side channel.
+	events : {},
 	exclusive : false,
 	feature : 'organization:connection:webhook',
 	fields : [