@drawbridge/drawbridge-utils 0.0.151 → 0.0.152

package/dist/connections/index.cjs

@@ -4147,7 +4147,7 @@ var shopify_default2 = {
       // against the ones the app now needs, and queues a webhook
       // reconciliation.
       health: async ({ connection: connection2, workflow }, { adminToken, logger: logger2, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {}) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f;
         const request2 = {
           connectionId: workflow.connection,
           organizationId: workflow.organization,
@@ -4172,6 +4172,7 @@ var shopify_default2 = {
           let metered;
           let shopCurrency = null;
           let billingProbeFailed = false;
+          let reconciliation = null;
           try {
             if (!(source == null ? void 0 : source.id)) {
               const shopData = await shopify.oauth.getShop({ adminAccessToken, shop: connection2.shop });
@@ -4192,45 +4193,99 @@ var shopify_default2 = {
             const partnerRow = (read == null ? void 0 : read.get) ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
             const partner = (partnerRow == null ? void 0 : partnerRow.settings) ? decrypt(partnerRow.settings) : {};
             if (partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && (source == null ? void 0 : source.id) && ((_b = shopify.partner) == null ? void 0 : _b.getUsageChargeEvents)) {
+              const ledgerFloor = new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3);
               const accruals = await shopify.partner.getUsageChargeEvents({
                 appId: "gid://shopify/App/" + partner.partnerAppId,
-                first: 5,
-                occurredAtMin: new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3).toISOString(),
+                first: 10,
+                occurredAtMin: ledgerFloor.toISOString(),
                 organizationId: partner.partnerOrgId,
                 partnerToken: partner.partnerToken,
                 shopId: "gid://shopify/Shop/" + source.id
               });
-              const accrued = accruals.find((event) => Number(event.usageQuantity) > 0);
-              if (accrued) {
-                metered = String(accrued.chargeId || accrued.id);
-                writes.push({
+              const boundaries = accruals.filter((event) => event.occurredAt).sort((a, b) => new Date(a.occurredAt) - new Date(b.occurredAt));
+              const accrued = [...boundaries].reverse().find((event) => Number(event.usageQuantity) > 0);
+              if (accrued) metered = String(accrued.chargeId || accrued.id);
+              const stampedAt = (_c = boundaries.find(
+                (event) => {
+                  var _a2;
+                  return String(event.chargeId || event.id) === String(((_a2 = connection2.source) == null ? void 0 : _a2.metered) || "");
+                }
+              )) == null ? void 0 : _c.occurredAt;
+              reconciliation = [];
+              let windowStart = ledgerFloor;
+              for (const boundary of boundaries) {
+                const windowEnd = new Date(boundary.occurredAt);
+                const windowOpensAt = windowStart;
+                windowStart = windowEnd;
+                if (stampedAt && windowEnd <= new Date(stampedAt)) continue;
+                const charged = Math.round(Number(boundary.usageQuantity) || 0);
+                const [tally] = await read.aggregate({
                   collection: "order",
-                  data: {
-                    $set: { "billed.receipt": metered }
-                  },
-                  // Top-level, not an option — the controller takes
-                  // `multiple` beside `options`, and the shell
-                  // forwards it as such.
-                  multiple: true,
-                  operation: "update",
-                  query: {
-                    "billed.date": { $gte: new Date(accrued.occurredAt || 0) },
-                    "billed.receipt": { $in: [null] },
-                    organization: workflow.organization,
-                    "provider.slug": "shopify"
-                  }
-                });
+                  pipeline: [
+                    { $match: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    } },
+                    { $group: {
+                      _id: null,
+                      billed: { $sum: "$billed.amount" },
+                      orders: { $push: "$id" }
+                    } }
+                  ]
+                }) || [];
+                const billed = (tally == null ? void 0 : tally.billed) || 0;
+                const orders = (tally == null ? void 0 : tally.orders) || [];
+                const charge = String(boundary.chargeId || boundary.id);
+                const balanced = charged === billed;
+                if (!(charged || billed)) continue;
+                if (balanced) {
+                  writes.push({
+                    collection: "order",
+                    data: {
+                      $set: { "billed.receipt": charge }
+                    },
+                    // Top-level, not an option — the controller takes
+                    // `multiple` beside `options`, and the shell
+                    // forwards it as such.
+                    multiple: true,
+                    operation: "update",
+                    query: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.receipt": { $in: [null] },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    }
+                  });
+                } else {
+                  (_d = logger2 == null ? void 0 : logger2.error) == null ? void 0 : _d.call(logger2, new Error(
+                    "shopify.usage.reconciliation.mismatch on shop " + connection2.shop + ": charge " + charge + " charged " + charged + " cents but its window holds " + billed + " cents across " + orders.length + " billed orders \u2014 each cent of difference is commission that never charged"
+                  ), {
+                    extra: {
+                      billed,
+                      charge,
+                      charged,
+                      orders: orders.slice(0, 50),
+                      shop: connection2.shop,
+                      windowEnd,
+                      windowStart: windowOpensAt
+                    }
+                  });
+                }
+                reconciliation.push({ balanced, billed, charge, charged, occurredAt: boundary.occurredAt, orders: orders.length });
               }
             }
           } catch (probeError) {
             billingProbeFailed = true;
-            (_c = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _c.call(logger2, "shopify.health.billing.probe.failed", {
+            (_e = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _e.call(logger2, "shopify.health.billing.probe.failed", {
               connectionId: connection2.id,
               message: probeError == null ? void 0 : probeError.message,
               shop: connection2.shop
             });
           }
-          if (sourceRepaired || metered !== void 0 && metered !== (((_d = connection2.source) == null ? void 0 : _d.metered) ?? void 0)) {
+          if (sourceRepaired || metered !== void 0 && metered !== (((_f = connection2.source) == null ? void 0 : _f.metered) ?? void 0)) {
             writes.push({
               collection: "connection",
               data: {
@@ -4301,6 +4356,9 @@ var shopify_default2 = {
               metered: metered ?? null,
               meterProbed: metered !== void 0,
               pingedAt: /* @__PURE__ */ new Date(),
+              // One entry per boundary charge judged this run: what
+              // Shopify charged vs what the window's orders billed.
+              ...reconciliation && { reconciliation },
               refreshTokenExpiresAt: refreshTokenExpiresAt || null,
               refreshTokenRotated,
               scopesMissing,

package/dist/connections/index.d.cts

@@ -4931,6 +4931,9 @@ var shopify = {
 					let metered;
 					let shopCurrency = null;
 					let billingProbeFailed = false;
+					// Per-boundary reconciliation results, surfaced in the step
+					// response — the operator's ledger view of charged vs billed.
+					let reconciliation = null;
 
 					try {
 
@@ -4971,71 +4974,162 @@ var shopify = {
 						// THE REAL METER SIGNAL — Partner API accrual. A CHARGE_USAGE
 						// event for this shop is proof billing works: its charge id
 						// becomes the stamp (overriding the line-item probe, which
-						// managed pricing keeps blind). No accrual AND a billed order
-						// old enough that one should exist is the HONEST unmetered
-						// verdict — the null that re-arms the card, the Issue and the
-						// pager on truth instead of the Admin API's silence. Off
-						// entirely until the provider row carries the credentials.
+						// managed pricing keeps blind), and each charge row is a
+						// billing BOUNDARY the reconciler below balances the books
+						// against. Off entirely until the provider row carries the
+						// credentials.
 						const partnerRow = read?.get ? await read.get({ collection : 'provider', query : { slug : 'shopify' } }) : null;
 						const partner = partnerRow?.settings ? decrypt( partnerRow.settings ) : {};
 
 						if( partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && source?.id && shopify.partner?.getUsageChargeEvents ){
 
+							const ledgerFloor = new Date( Date.now() - 30 * 24 * 60 * 60 * 1000 );
+
 							const accruals = await shopify.partner.getUsageChargeEvents({
 								appId : 'gid://shopify/App/' + partner.partnerAppId,
-								first : 5,
-								occurredAtMin : new Date( Date.now() - 30 * 24 * 60 * 60 * 1000 ).toISOString(),
+								first : 10,
+								occurredAtMin : ledgerFloor.toISOString(),
 								organizationId : partner.partnerOrgId,
 								partnerToken : partner.partnerToken,
 								shopId : 'gid://shopify/Shop/' + source.id
 							});
 
+							// Oldest first: each charge row is a boundary that closes
+							// the window since the row before it.
+							const boundaries = accruals
+								.filter( ( event ) => event.occurredAt )
+								.sort( ( a, b ) => new Date( a.occurredAt ) - new Date( b.occurredAt ) );
+
 							// A usage ROW exists per subscription even before anything
 							// accrues (measured: a pre-meter approval shows qty 0), so
 							// the row is not the proof — a POSITIVE usageQuantity is.
-							const accrued = accruals.find( ( event ) => Number( event.usageQuantity ) > 0 );
-
-							if( accrued ){
+							// The LATEST positive row is the stamp.
+							const accrued = [ ...boundaries ].reverse().find( ( event ) => Number( event.usageQuantity ) > 0 );
+
+							if( accrued ) metered = String( accrued.chargeId || accrued.id );
+
+							// THE BOUNDARY RECONCILER. Money truth lives at boundaries:
+							// each charge row states what Shopify actually charged for
+							// the window since the previous row, and the orders billed
+							// inside that window state what we asked for — in the same
+							// cents (billed.amount IS the value the usage event
+							// carried). Balanced and positive → the window's orders get
+							// the charge id as billed.receipt (their invoice bucket).
+							// Mismatched → an alarm with the diff, and NO stamp: a
+							// short window is money silently lost, which is the one
+							// thing this whole chain exists to make loud.
+							//
+							// The stored stamp is the CURSOR: rows at or before the
+							// charge already stamped were judged on the run that
+							// stamped it, and re-judging them would page daily on the
+							// pre-meter era's known losses. (A store with losses and no
+							// positive row yet has no cursor, so its mismatch DOES
+							// re-alarm daily — deliberately: that nag is what drives
+							// the admin write-off, and voided orders leave the sums.)
+							const stampedAt = boundaries.find(
+								( event ) => String( event.chargeId || event.id ) === String( connection.source?.metered || '' )
+							)?.occurredAt;
+
+							reconciliation = [];
+
+							let windowStart = ledgerFloor;
+
+							for( const boundary of boundaries ){
+
+								const windowEnd = new Date( boundary.occurredAt );
+								const windowOpensAt = windowStart;
+
+								windowStart = windowEnd;
+
+								if( stampedAt && windowEnd <= new Date( stampedAt ) ) continue;
+
+								const charged = Math.round( Number( boundary.usageQuantity ) || 0 );
+
+								// Voided orders are written off — known unrecoverable,
+								// excluded so they stop swaying every future boundary.
+								// Already-receipted orders still COUNT in the sum (an
+								// early stamp must not read as missing money) but are
+								// never restamped.
+								const [ tally ] = await read.aggregate({
+									collection : 'order',
+									pipeline : [
+										{ $match : {
+											'billed.date' : { $gt : windowOpensAt, $lte : windowEnd },
+											'billed.void' : { $in : [ null ] },
+											organization : workflow.organization,
+											'provider.slug' : 'shopify'
+										} },
+										{ $group : {
+											_id : null,
+											billed : { $sum : '$billed.amount' },
+											orders : { $push : '$id' }
+										} }
+									]
+								}) || [];
+
+								const billed = tally?.billed || 0;
+								const orders = tally?.orders || [];
+								const charge = String( boundary.chargeId || boundary.id );
+								const balanced = charged === billed;
+
+								if( ! ( charged || billed ) ) continue;
+
+								if( balanced ){
+
+									writes.push({
+										collection : 'order',
+										data : {
+											$set : { 'billed.receipt' : charge }
+										},
+										// Top-level, not an option — the controller takes
+										// `multiple` beside `options`, and the shell
+										// forwards it as such.
+										multiple : true,
+										operation : 'update',
+										query : {
+											'billed.date' : { $gt : windowOpensAt, $lte : windowEnd },
+											'billed.receipt' : { $in : [ null ] },
+											'billed.void' : { $in : [ null ] },
+											organization : workflow.organization,
+											'provider.slug' : 'shopify'
+										}
+									});
+
+								} else {
+
+									logger?.error?.( new Error(
+										'shopify.usage.reconciliation.mismatch on shop ' + connection.shop
+										+ ': charge ' + charge + ' charged ' + charged + ' cents but its window holds '
+										+ billed + ' cents across ' + orders.length + ' billed orders'
+										+ ' — each cent of difference is commission that never charged'
+									), {
+										extra : {
+											billed,
+											charge,
+											charged,
+											orders : orders.slice( 0, 50 ),
+											shop : connection.shop,
+											windowEnd,
+											windowStart : windowOpensAt
+										}
+									});
 
-								metered = String( accrued.chargeId || accrued.id );
+								}
 
-								// THE BUCKET STAMPS ITS ORDERS. Partner accrual rows
-								// are per-subscription, not per-order, so the charge id
-								// is the invoice bucket every order billed since that
-								// subscription's approval rolled into — written onto
-								// billed.receipt (many-update; $in [null] matches both
-								// null and never-stamped). Orders billed before the
-								// window belong to earlier, possibly unbillable
-								// approvals and honestly stay unstamped.
-								writes.push({
-									collection : 'order',
-									data : {
-										$set : { 'billed.receipt' : metered }
-									},
-									// Top-level, not an option — the controller takes
-									// `multiple` beside `options`, and the shell
-									// forwards it as such.
-									multiple : true,
-									operation : 'update',
-									query : {
-										'billed.date' : { $gte : new Date( accrued.occurredAt || 0 ) },
-										'billed.receipt' : { $in : [ null ] },
-										organization : workflow.organization,
-										'provider.slug' : 'shopify'
-									}
-								});
+								reconciliation.push({ balanced, billed, charge, charged, occurredAt : boundary.occurredAt, orders : orders.length });
 
 							}
 
-							// NO negative verdict from an empty ledger: measured
-							// 2026-09-04, CHARGE_USAGE rows only materialize at
-							// BILLING moments (cycle end, cancellation/replacement)
-							// — usage accrues invisibly between them, so a
-							// first-cycle store with billed orders and no row is
-							// the NORMAL state, not an unmetered one. The honest
-							// negative is a boundary reconciliation (a charge-out
-							// row whose quantity falls short of the window's billed
-							// sum) — until that exists, absence stays a no-verdict.
+							// DELIBERATELY NO null verdict from a lossy boundary. A
+							// zero-charged window full of billed orders IS proof money
+							// was lost — but it cannot say whether the CURRENT approval
+							// is broken: the exact same shape appears the moment a
+							// merchant fixes their store (the release charges out qty 0
+							// and its window holds the pre-meter losses), and re-arming
+							// "Fix order billing" on a store that was just fixed sends
+							// the merchant through the flow again for nothing. The
+							// mismatch alarm above owns that truth for the operator,
+							// and the write-off drains it.
 
 						}
 
@@ -5154,6 +5248,9 @@ var shopify = {
 							metered : metered ?? null,
 							meterProbed : metered !== undefined,
 							pingedAt : new Date(),
+							// One entry per boundary charge judged this run: what
+							// Shopify charged vs what the window's orders billed.
+							...( reconciliation && { reconciliation }),
 							refreshTokenExpiresAt : refreshTokenExpiresAt || null,
 							refreshTokenRotated,
 							scopesMissing,

package/dist/connections/index.d.ts

@@ -4931,6 +4931,9 @@ var shopify = {
 					let metered;
 					let shopCurrency = null;
 					let billingProbeFailed = false;
+					// Per-boundary reconciliation results, surfaced in the step
+					// response — the operator's ledger view of charged vs billed.
+					let reconciliation = null;
 
 					try {
 
@@ -4971,71 +4974,162 @@ var shopify = {
 						// THE REAL METER SIGNAL — Partner API accrual. A CHARGE_USAGE
 						// event for this shop is proof billing works: its charge id
 						// becomes the stamp (overriding the line-item probe, which
-						// managed pricing keeps blind). No accrual AND a billed order
-						// old enough that one should exist is the HONEST unmetered
-						// verdict — the null that re-arms the card, the Issue and the
-						// pager on truth instead of the Admin API's silence. Off
-						// entirely until the provider row carries the credentials.
+						// managed pricing keeps blind), and each charge row is a
+						// billing BOUNDARY the reconciler below balances the books
+						// against. Off entirely until the provider row carries the
+						// credentials.
 						const partnerRow = read?.get ? await read.get({ collection : 'provider', query : { slug : 'shopify' } }) : null;
 						const partner = partnerRow?.settings ? decrypt( partnerRow.settings ) : {};
 
 						if( partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && source?.id && shopify.partner?.getUsageChargeEvents ){
 
+							const ledgerFloor = new Date( Date.now() - 30 * 24 * 60 * 60 * 1000 );
+
 							const accruals = await shopify.partner.getUsageChargeEvents({
 								appId : 'gid://shopify/App/' + partner.partnerAppId,
-								first : 5,
-								occurredAtMin : new Date( Date.now() - 30 * 24 * 60 * 60 * 1000 ).toISOString(),
+								first : 10,
+								occurredAtMin : ledgerFloor.toISOString(),
 								organizationId : partner.partnerOrgId,
 								partnerToken : partner.partnerToken,
 								shopId : 'gid://shopify/Shop/' + source.id
 							});
 
+							// Oldest first: each charge row is a boundary that closes
+							// the window since the row before it.
+							const boundaries = accruals
+								.filter( ( event ) => event.occurredAt )
+								.sort( ( a, b ) => new Date( a.occurredAt ) - new Date( b.occurredAt ) );
+
 							// A usage ROW exists per subscription even before anything
 							// accrues (measured: a pre-meter approval shows qty 0), so
 							// the row is not the proof — a POSITIVE usageQuantity is.
-							const accrued = accruals.find( ( event ) => Number( event.usageQuantity ) > 0 );
-
-							if( accrued ){
+							// The LATEST positive row is the stamp.
+							const accrued = [ ...boundaries ].reverse().find( ( event ) => Number( event.usageQuantity ) > 0 );
+
+							if( accrued ) metered = String( accrued.chargeId || accrued.id );
+
+							// THE BOUNDARY RECONCILER. Money truth lives at boundaries:
+							// each charge row states what Shopify actually charged for
+							// the window since the previous row, and the orders billed
+							// inside that window state what we asked for — in the same
+							// cents (billed.amount IS the value the usage event
+							// carried). Balanced and positive → the window's orders get
+							// the charge id as billed.receipt (their invoice bucket).
+							// Mismatched → an alarm with the diff, and NO stamp: a
+							// short window is money silently lost, which is the one
+							// thing this whole chain exists to make loud.
+							//
+							// The stored stamp is the CURSOR: rows at or before the
+							// charge already stamped were judged on the run that
+							// stamped it, and re-judging them would page daily on the
+							// pre-meter era's known losses. (A store with losses and no
+							// positive row yet has no cursor, so its mismatch DOES
+							// re-alarm daily — deliberately: that nag is what drives
+							// the admin write-off, and voided orders leave the sums.)
+							const stampedAt = boundaries.find(
+								( event ) => String( event.chargeId || event.id ) === String( connection.source?.metered || '' )
+							)?.occurredAt;
+
+							reconciliation = [];
+
+							let windowStart = ledgerFloor;
+
+							for( const boundary of boundaries ){
+
+								const windowEnd = new Date( boundary.occurredAt );
+								const windowOpensAt = windowStart;
+
+								windowStart = windowEnd;
+
+								if( stampedAt && windowEnd <= new Date( stampedAt ) ) continue;
+
+								const charged = Math.round( Number( boundary.usageQuantity ) || 0 );
+
+								// Voided orders are written off — known unrecoverable,
+								// excluded so they stop swaying every future boundary.
+								// Already-receipted orders still COUNT in the sum (an
+								// early stamp must not read as missing money) but are
+								// never restamped.
+								const [ tally ] = await read.aggregate({
+									collection : 'order',
+									pipeline : [
+										{ $match : {
+											'billed.date' : { $gt : windowOpensAt, $lte : windowEnd },
+											'billed.void' : { $in : [ null ] },
+											organization : workflow.organization,
+											'provider.slug' : 'shopify'
+										} },
+										{ $group : {
+											_id : null,
+											billed : { $sum : '$billed.amount' },
+											orders : { $push : '$id' }
+										} }
+									]
+								}) || [];
+
+								const billed = tally?.billed || 0;
+								const orders = tally?.orders || [];
+								const charge = String( boundary.chargeId || boundary.id );
+								const balanced = charged === billed;
+
+								if( ! ( charged || billed ) ) continue;
+
+								if( balanced ){
+
+									writes.push({
+										collection : 'order',
+										data : {
+											$set : { 'billed.receipt' : charge }
+										},
+										// Top-level, not an option — the controller takes
+										// `multiple` beside `options`, and the shell
+										// forwards it as such.
+										multiple : true,
+										operation : 'update',
+										query : {
+											'billed.date' : { $gt : windowOpensAt, $lte : windowEnd },
+											'billed.receipt' : { $in : [ null ] },
+											'billed.void' : { $in : [ null ] },
+											organization : workflow.organization,
+											'provider.slug' : 'shopify'
+										}
+									});
+
+								} else {
+
+									logger?.error?.( new Error(
+										'shopify.usage.reconciliation.mismatch on shop ' + connection.shop
+										+ ': charge ' + charge + ' charged ' + charged + ' cents but its window holds '
+										+ billed + ' cents across ' + orders.length + ' billed orders'
+										+ ' — each cent of difference is commission that never charged'
+									), {
+										extra : {
+											billed,
+											charge,
+											charged,
+											orders : orders.slice( 0, 50 ),
+											shop : connection.shop,
+											windowEnd,
+											windowStart : windowOpensAt
+										}
+									});
 
-								metered = String( accrued.chargeId || accrued.id );
+								}
 
-								// THE BUCKET STAMPS ITS ORDERS. Partner accrual rows
-								// are per-subscription, not per-order, so the charge id
-								// is the invoice bucket every order billed since that
-								// subscription's approval rolled into — written onto
-								// billed.receipt (many-update; $in [null] matches both
-								// null and never-stamped). Orders billed before the
-								// window belong to earlier, possibly unbillable
-								// approvals and honestly stay unstamped.
-								writes.push({
-									collection : 'order',
-									data : {
-										$set : { 'billed.receipt' : metered }
-									},
-									// Top-level, not an option — the controller takes
-									// `multiple` beside `options`, and the shell
-									// forwards it as such.
-									multiple : true,
-									operation : 'update',
-									query : {
-										'billed.date' : { $gte : new Date( accrued.occurredAt || 0 ) },
-										'billed.receipt' : { $in : [ null ] },
-										organization : workflow.organization,
-										'provider.slug' : 'shopify'
-									}
-								});
+								reconciliation.push({ balanced, billed, charge, charged, occurredAt : boundary.occurredAt, orders : orders.length });
 
 							}
 
-							// NO negative verdict from an empty ledger: measured
-							// 2026-09-04, CHARGE_USAGE rows only materialize at
-							// BILLING moments (cycle end, cancellation/replacement)
-							// — usage accrues invisibly between them, so a
-							// first-cycle store with billed orders and no row is
-							// the NORMAL state, not an unmetered one. The honest
-							// negative is a boundary reconciliation (a charge-out
-							// row whose quantity falls short of the window's billed
-							// sum) — until that exists, absence stays a no-verdict.
+							// DELIBERATELY NO null verdict from a lossy boundary. A
+							// zero-charged window full of billed orders IS proof money
+							// was lost — but it cannot say whether the CURRENT approval
+							// is broken: the exact same shape appears the moment a
+							// merchant fixes their store (the release charges out qty 0
+							// and its window holds the pre-meter losses), and re-arming
+							// "Fix order billing" on a store that was just fixed sends
+							// the merchant through the flow again for nothing. The
+							// mismatch alarm above owns that truth for the operator,
+							// and the write-off drains it.
 
 						}
 
@@ -5154,6 +5248,9 @@ var shopify = {
 							metered : metered ?? null,
 							meterProbed : metered !== undefined,
 							pingedAt : new Date(),
+							// One entry per boundary charge judged this run: what
+							// Shopify charged vs what the window's orders billed.
+							...( reconciliation && { reconciliation }),
 							refreshTokenExpiresAt : refreshTokenExpiresAt || null,
 							refreshTokenRotated,
 							scopesMissing,

package/dist/connections/index.js

@@ -4073,7 +4073,7 @@ var shopify_default2 = {
       // against the ones the app now needs, and queues a webhook
       // reconciliation.
       health: async ({ connection: connection2, workflow }, { adminToken, logger: logger2, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {}) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f;
         const request2 = {
           connectionId: workflow.connection,
           organizationId: workflow.organization,
@@ -4098,6 +4098,7 @@ var shopify_default2 = {
           let metered;
           let shopCurrency = null;
           let billingProbeFailed = false;
+          let reconciliation = null;
           try {
             if (!(source == null ? void 0 : source.id)) {
               const shopData = await shopify.oauth.getShop({ adminAccessToken, shop: connection2.shop });
@@ -4118,45 +4119,99 @@ var shopify_default2 = {
             const partnerRow = (read == null ? void 0 : read.get) ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
             const partner = (partnerRow == null ? void 0 : partnerRow.settings) ? decrypt(partnerRow.settings) : {};
             if (partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && (source == null ? void 0 : source.id) && ((_b = shopify.partner) == null ? void 0 : _b.getUsageChargeEvents)) {
+              const ledgerFloor = new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3);
               const accruals = await shopify.partner.getUsageChargeEvents({
                 appId: "gid://shopify/App/" + partner.partnerAppId,
-                first: 5,
-                occurredAtMin: new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3).toISOString(),
+                first: 10,
+                occurredAtMin: ledgerFloor.toISOString(),
                 organizationId: partner.partnerOrgId,
                 partnerToken: partner.partnerToken,
                 shopId: "gid://shopify/Shop/" + source.id
               });
-              const accrued = accruals.find((event) => Number(event.usageQuantity) > 0);
-              if (accrued) {
-                metered = String(accrued.chargeId || accrued.id);
-                writes.push({
+              const boundaries = accruals.filter((event) => event.occurredAt).sort((a, b) => new Date(a.occurredAt) - new Date(b.occurredAt));
+              const accrued = [...boundaries].reverse().find((event) => Number(event.usageQuantity) > 0);
+              if (accrued) metered = String(accrued.chargeId || accrued.id);
+              const stampedAt = (_c = boundaries.find(
+                (event) => {
+                  var _a2;
+                  return String(event.chargeId || event.id) === String(((_a2 = connection2.source) == null ? void 0 : _a2.metered) || "");
+                }
+              )) == null ? void 0 : _c.occurredAt;
+              reconciliation = [];
+              let windowStart = ledgerFloor;
+              for (const boundary of boundaries) {
+                const windowEnd = new Date(boundary.occurredAt);
+                const windowOpensAt = windowStart;
+                windowStart = windowEnd;
+                if (stampedAt && windowEnd <= new Date(stampedAt)) continue;
+                const charged = Math.round(Number(boundary.usageQuantity) || 0);
+                const [tally] = await read.aggregate({
                   collection: "order",
-                  data: {
-                    $set: { "billed.receipt": metered }
-                  },
-                  // Top-level, not an option — the controller takes
-                  // `multiple` beside `options`, and the shell
-                  // forwards it as such.
-                  multiple: true,
-                  operation: "update",
-                  query: {
-                    "billed.date": { $gte: new Date(accrued.occurredAt || 0) },
-                    "billed.receipt": { $in: [null] },
-                    organization: workflow.organization,
-                    "provider.slug": "shopify"
-                  }
-                });
+                  pipeline: [
+                    { $match: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    } },
+                    { $group: {
+                      _id: null,
+                      billed: { $sum: "$billed.amount" },
+                      orders: { $push: "$id" }
+                    } }
+                  ]
+                }) || [];
+                const billed = (tally == null ? void 0 : tally.billed) || 0;
+                const orders = (tally == null ? void 0 : tally.orders) || [];
+                const charge = String(boundary.chargeId || boundary.id);
+                const balanced = charged === billed;
+                if (!(charged || billed)) continue;
+                if (balanced) {
+                  writes.push({
+                    collection: "order",
+                    data: {
+                      $set: { "billed.receipt": charge }
+                    },
+                    // Top-level, not an option — the controller takes
+                    // `multiple` beside `options`, and the shell
+                    // forwards it as such.
+                    multiple: true,
+                    operation: "update",
+                    query: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.receipt": { $in: [null] },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    }
+                  });
+                } else {
+                  (_d = logger2 == null ? void 0 : logger2.error) == null ? void 0 : _d.call(logger2, new Error(
+                    "shopify.usage.reconciliation.mismatch on shop " + connection2.shop + ": charge " + charge + " charged " + charged + " cents but its window holds " + billed + " cents across " + orders.length + " billed orders \u2014 each cent of difference is commission that never charged"
+                  ), {
+                    extra: {
+                      billed,
+                      charge,
+                      charged,
+                      orders: orders.slice(0, 50),
+                      shop: connection2.shop,
+                      windowEnd,
+                      windowStart: windowOpensAt
+                    }
+                  });
+                }
+                reconciliation.push({ balanced, billed, charge, charged, occurredAt: boundary.occurredAt, orders: orders.length });
               }
             }
           } catch (probeError) {
             billingProbeFailed = true;
-            (_c = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _c.call(logger2, "shopify.health.billing.probe.failed", {
+            (_e = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _e.call(logger2, "shopify.health.billing.probe.failed", {
               connectionId: connection2.id,
               message: probeError == null ? void 0 : probeError.message,
               shop: connection2.shop
             });
           }
-          if (sourceRepaired || metered !== void 0 && metered !== (((_d = connection2.source) == null ? void 0 : _d.metered) ?? void 0)) {
+          if (sourceRepaired || metered !== void 0 && metered !== (((_f = connection2.source) == null ? void 0 : _f.metered) ?? void 0)) {
             writes.push({
               collection: "connection",
               data: {
@@ -4227,6 +4282,9 @@ var shopify_default2 = {
               metered: metered ?? null,
               meterProbed: metered !== void 0,
               pingedAt: /* @__PURE__ */ new Date(),
+              // One entry per boundary charge judged this run: what
+              // Shopify charged vs what the window's orders billed.
+              ...reconciliation && { reconciliation },
               refreshTokenExpiresAt: refreshTokenExpiresAt || null,
               refreshTokenRotated,
               scopesMissing,

package/dist/providers.cjs

@@ -4072,7 +4072,7 @@ var shopify_default2 = {
       // against the ones the app now needs, and queues a webhook
       // reconciliation.
       health: async ({ connection: connection2, workflow }, { adminToken, logger: logger2, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {}) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f;
         const request2 = {
           connectionId: workflow.connection,
           organizationId: workflow.organization,
@@ -4097,6 +4097,7 @@ var shopify_default2 = {
           let metered;
           let shopCurrency = null;
           let billingProbeFailed = false;
+          let reconciliation = null;
           try {
             if (!(source == null ? void 0 : source.id)) {
               const shopData = await shopify.oauth.getShop({ adminAccessToken, shop: connection2.shop });
@@ -4117,45 +4118,99 @@ var shopify_default2 = {
             const partnerRow = (read == null ? void 0 : read.get) ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
             const partner = (partnerRow == null ? void 0 : partnerRow.settings) ? decrypt(partnerRow.settings) : {};
             if (partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && (source == null ? void 0 : source.id) && ((_b = shopify.partner) == null ? void 0 : _b.getUsageChargeEvents)) {
+              const ledgerFloor = new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3);
               const accruals = await shopify.partner.getUsageChargeEvents({
                 appId: "gid://shopify/App/" + partner.partnerAppId,
-                first: 5,
-                occurredAtMin: new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3).toISOString(),
+                first: 10,
+                occurredAtMin: ledgerFloor.toISOString(),
                 organizationId: partner.partnerOrgId,
                 partnerToken: partner.partnerToken,
                 shopId: "gid://shopify/Shop/" + source.id
               });
-              const accrued = accruals.find((event) => Number(event.usageQuantity) > 0);
-              if (accrued) {
-                metered = String(accrued.chargeId || accrued.id);
-                writes.push({
+              const boundaries = accruals.filter((event) => event.occurredAt).sort((a, b) => new Date(a.occurredAt) - new Date(b.occurredAt));
+              const accrued = [...boundaries].reverse().find((event) => Number(event.usageQuantity) > 0);
+              if (accrued) metered = String(accrued.chargeId || accrued.id);
+              const stampedAt = (_c = boundaries.find(
+                (event) => {
+                  var _a2;
+                  return String(event.chargeId || event.id) === String(((_a2 = connection2.source) == null ? void 0 : _a2.metered) || "");
+                }
+              )) == null ? void 0 : _c.occurredAt;
+              reconciliation = [];
+              let windowStart = ledgerFloor;
+              for (const boundary of boundaries) {
+                const windowEnd = new Date(boundary.occurredAt);
+                const windowOpensAt = windowStart;
+                windowStart = windowEnd;
+                if (stampedAt && windowEnd <= new Date(stampedAt)) continue;
+                const charged = Math.round(Number(boundary.usageQuantity) || 0);
+                const [tally] = await read.aggregate({
                   collection: "order",
-                  data: {
-                    $set: { "billed.receipt": metered }
-                  },
-                  // Top-level, not an option — the controller takes
-                  // `multiple` beside `options`, and the shell
-                  // forwards it as such.
-                  multiple: true,
-                  operation: "update",
-                  query: {
-                    "billed.date": { $gte: new Date(accrued.occurredAt || 0) },
-                    "billed.receipt": { $in: [null] },
-                    organization: workflow.organization,
-                    "provider.slug": "shopify"
-                  }
-                });
+                  pipeline: [
+                    { $match: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    } },
+                    { $group: {
+                      _id: null,
+                      billed: { $sum: "$billed.amount" },
+                      orders: { $push: "$id" }
+                    } }
+                  ]
+                }) || [];
+                const billed = (tally == null ? void 0 : tally.billed) || 0;
+                const orders = (tally == null ? void 0 : tally.orders) || [];
+                const charge = String(boundary.chargeId || boundary.id);
+                const balanced = charged === billed;
+                if (!(charged || billed)) continue;
+                if (balanced) {
+                  writes.push({
+                    collection: "order",
+                    data: {
+                      $set: { "billed.receipt": charge }
+                    },
+                    // Top-level, not an option — the controller takes
+                    // `multiple` beside `options`, and the shell
+                    // forwards it as such.
+                    multiple: true,
+                    operation: "update",
+                    query: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.receipt": { $in: [null] },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    }
+                  });
+                } else {
+                  (_d = logger2 == null ? void 0 : logger2.error) == null ? void 0 : _d.call(logger2, new Error(
+                    "shopify.usage.reconciliation.mismatch on shop " + connection2.shop + ": charge " + charge + " charged " + charged + " cents but its window holds " + billed + " cents across " + orders.length + " billed orders \u2014 each cent of difference is commission that never charged"
+                  ), {
+                    extra: {
+                      billed,
+                      charge,
+                      charged,
+                      orders: orders.slice(0, 50),
+                      shop: connection2.shop,
+                      windowEnd,
+                      windowStart: windowOpensAt
+                    }
+                  });
+                }
+                reconciliation.push({ balanced, billed, charge, charged, occurredAt: boundary.occurredAt, orders: orders.length });
               }
             }
           } catch (probeError) {
             billingProbeFailed = true;
-            (_c = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _c.call(logger2, "shopify.health.billing.probe.failed", {
+            (_e = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _e.call(logger2, "shopify.health.billing.probe.failed", {
               connectionId: connection2.id,
               message: probeError == null ? void 0 : probeError.message,
               shop: connection2.shop
             });
           }
-          if (sourceRepaired || metered !== void 0 && metered !== (((_d = connection2.source) == null ? void 0 : _d.metered) ?? void 0)) {
+          if (sourceRepaired || metered !== void 0 && metered !== (((_f = connection2.source) == null ? void 0 : _f.metered) ?? void 0)) {
             writes.push({
               collection: "connection",
               data: {
@@ -4226,6 +4281,9 @@ var shopify_default2 = {
               metered: metered ?? null,
               meterProbed: metered !== void 0,
               pingedAt: /* @__PURE__ */ new Date(),
+              // One entry per boundary charge judged this run: what
+              // Shopify charged vs what the window's orders billed.
+              ...reconciliation && { reconciliation },
               refreshTokenExpiresAt: refreshTokenExpiresAt || null,
               refreshTokenRotated,
               scopesMissing,

package/dist/providers.js

@@ -4028,7 +4028,7 @@ var shopify_default2 = {
       // against the ones the app now needs, and queues a webhook
       // reconciliation.
       health: async ({ connection: connection2, workflow }, { adminToken, logger: logger2, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {}) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f;
         const request2 = {
           connectionId: workflow.connection,
           organizationId: workflow.organization,
@@ -4053,6 +4053,7 @@ var shopify_default2 = {
           let metered;
           let shopCurrency = null;
           let billingProbeFailed = false;
+          let reconciliation = null;
           try {
             if (!(source == null ? void 0 : source.id)) {
               const shopData = await shopify.oauth.getShop({ adminAccessToken, shop: connection2.shop });
@@ -4073,45 +4074,99 @@ var shopify_default2 = {
             const partnerRow = (read == null ? void 0 : read.get) ? await read.get({ collection: "provider", query: { slug: "shopify" } }) : null;
             const partner = (partnerRow == null ? void 0 : partnerRow.settings) ? decrypt(partnerRow.settings) : {};
             if (partner.partnerToken && partner.partnerOrgId && partner.partnerAppId && (source == null ? void 0 : source.id) && ((_b = shopify.partner) == null ? void 0 : _b.getUsageChargeEvents)) {
+              const ledgerFloor = new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3);
               const accruals = await shopify.partner.getUsageChargeEvents({
                 appId: "gid://shopify/App/" + partner.partnerAppId,
-                first: 5,
-                occurredAtMin: new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3).toISOString(),
+                first: 10,
+                occurredAtMin: ledgerFloor.toISOString(),
                 organizationId: partner.partnerOrgId,
                 partnerToken: partner.partnerToken,
                 shopId: "gid://shopify/Shop/" + source.id
               });
-              const accrued = accruals.find((event) => Number(event.usageQuantity) > 0);
-              if (accrued) {
-                metered = String(accrued.chargeId || accrued.id);
-                writes.push({
+              const boundaries = accruals.filter((event) => event.occurredAt).sort((a, b) => new Date(a.occurredAt) - new Date(b.occurredAt));
+              const accrued = [...boundaries].reverse().find((event) => Number(event.usageQuantity) > 0);
+              if (accrued) metered = String(accrued.chargeId || accrued.id);
+              const stampedAt = (_c = boundaries.find(
+                (event) => {
+                  var _a2;
+                  return String(event.chargeId || event.id) === String(((_a2 = connection2.source) == null ? void 0 : _a2.metered) || "");
+                }
+              )) == null ? void 0 : _c.occurredAt;
+              reconciliation = [];
+              let windowStart = ledgerFloor;
+              for (const boundary of boundaries) {
+                const windowEnd = new Date(boundary.occurredAt);
+                const windowOpensAt = windowStart;
+                windowStart = windowEnd;
+                if (stampedAt && windowEnd <= new Date(stampedAt)) continue;
+                const charged = Math.round(Number(boundary.usageQuantity) || 0);
+                const [tally] = await read.aggregate({
                   collection: "order",
-                  data: {
-                    $set: { "billed.receipt": metered }
-                  },
-                  // Top-level, not an option — the controller takes
-                  // `multiple` beside `options`, and the shell
-                  // forwards it as such.
-                  multiple: true,
-                  operation: "update",
-                  query: {
-                    "billed.date": { $gte: new Date(accrued.occurredAt || 0) },
-                    "billed.receipt": { $in: [null] },
-                    organization: workflow.organization,
-                    "provider.slug": "shopify"
-                  }
-                });
+                  pipeline: [
+                    { $match: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    } },
+                    { $group: {
+                      _id: null,
+                      billed: { $sum: "$billed.amount" },
+                      orders: { $push: "$id" }
+                    } }
+                  ]
+                }) || [];
+                const billed = (tally == null ? void 0 : tally.billed) || 0;
+                const orders = (tally == null ? void 0 : tally.orders) || [];
+                const charge = String(boundary.chargeId || boundary.id);
+                const balanced = charged === billed;
+                if (!(charged || billed)) continue;
+                if (balanced) {
+                  writes.push({
+                    collection: "order",
+                    data: {
+                      $set: { "billed.receipt": charge }
+                    },
+                    // Top-level, not an option — the controller takes
+                    // `multiple` beside `options`, and the shell
+                    // forwards it as such.
+                    multiple: true,
+                    operation: "update",
+                    query: {
+                      "billed.date": { $gt: windowOpensAt, $lte: windowEnd },
+                      "billed.receipt": { $in: [null] },
+                      "billed.void": { $in: [null] },
+                      organization: workflow.organization,
+                      "provider.slug": "shopify"
+                    }
+                  });
+                } else {
+                  (_d = logger2 == null ? void 0 : logger2.error) == null ? void 0 : _d.call(logger2, new Error(
+                    "shopify.usage.reconciliation.mismatch on shop " + connection2.shop + ": charge " + charge + " charged " + charged + " cents but its window holds " + billed + " cents across " + orders.length + " billed orders \u2014 each cent of difference is commission that never charged"
+                  ), {
+                    extra: {
+                      billed,
+                      charge,
+                      charged,
+                      orders: orders.slice(0, 50),
+                      shop: connection2.shop,
+                      windowEnd,
+                      windowStart: windowOpensAt
+                    }
+                  });
+                }
+                reconciliation.push({ balanced, billed, charge, charged, occurredAt: boundary.occurredAt, orders: orders.length });
               }
             }
           } catch (probeError) {
             billingProbeFailed = true;
-            (_c = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _c.call(logger2, "shopify.health.billing.probe.failed", {
+            (_e = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _e.call(logger2, "shopify.health.billing.probe.failed", {
               connectionId: connection2.id,
               message: probeError == null ? void 0 : probeError.message,
               shop: connection2.shop
             });
           }
-          if (sourceRepaired || metered !== void 0 && metered !== (((_d = connection2.source) == null ? void 0 : _d.metered) ?? void 0)) {
+          if (sourceRepaired || metered !== void 0 && metered !== (((_f = connection2.source) == null ? void 0 : _f.metered) ?? void 0)) {
             writes.push({
               collection: "connection",
               data: {
@@ -4182,6 +4237,9 @@ var shopify_default2 = {
               metered: metered ?? null,
               meterProbed: metered !== void 0,
               pingedAt: /* @__PURE__ */ new Date(),
+              // One entry per boundary charge judged this run: what
+              // Shopify charged vs what the window's orders billed.
+              ...reconciliation && { reconciliation },
               refreshTokenExpiresAt: refreshTokenExpiresAt || null,
               refreshTokenRotated,
               scopesMissing,

package/package.json

@@ -216,5 +216,5 @@
     "prepublishOnly": ". \"$HOME/.nvm/nvm.sh\" && nvm use && tsup && node --test"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.151"
+  "version": "0.0.152"
 }