@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/reconcile-stock.js

@@ -0,0 +1,349 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { firebaseAdmin, notifyHostManagers } from "@aglyn/tenant-data-admin";
+import * as CommerceModel from "../model/index.js";
+/**
+ * THE MISSING-DECREMENT DETECTOR (AGL-2358).
+ *
+ * Every order-minting branch of `billing-webhook.ts` commits the order in a
+ * transaction and decrements stock AFTER it, and every branch guards on a
+ * replay flag that transaction set — `created` for cart and buy-now,
+ * `flipped` for the draft/POS-card branch, the invoice-id guard for a
+ * subscription cycle. So a process that dies in the window between the two
+ * loses the decrement PERMANENTLY: Stripe redelivers, the guard says the
+ * order already exists, and the handler returns without ever reaching the
+ * stock write. The merchant has a paid order and an untouched shelf, and
+ * before this nothing anywhere recorded that they had diverged.
+ *
+ * `/api/billing/webhook`'s own claim marker makes the same window wider, not
+ * narrower: AGL-2157 decided that an event which throws mid-dispatch KEEPS
+ * its claim — deliberately, because re-running the dispatch could double-apply
+ * a gift-card spend or a coupon redemption — and told staff to "reconcile by
+ * hand". This is the thing they reconcile with. It is also the only detector
+ * for the death AGL-2157 cannot catch at all: a timeout, an OOM or a deploy
+ * kill unwinds no stack, so that route's `catch` never runs and no staff
+ * notice is ever raised.
+ *
+ * WHY A DETECTOR AND NOT THE FIX. The two real fixes were both weighed and
+ * both rejected for this side of the Sept 1 freeze:
+ *
+ *  - Folding the decrement into the order transaction would restructure the
+ *    checkout path's largest and most contended transaction, days before
+ *    launch, on the path that takes money. The cart branch alone would have
+ *    to pull N product reads into a transaction that currently reads two
+ *    documents, and every contended retry would then re-run order numbering.
+ *  - A second replay flag with a re-entry path is worse, not better. The
+ *    `created` guard is not protecting the decrement — it is protecting
+ *    licence-key assignment, coupon redemption counters, gift-card balances,
+ *    receipt email and contact ingestion, all behind ONE flag. Any re-entry
+ *    past it needs every one of those to become individually idempotent
+ *    first, which is precisely the "per-EFFECT idempotency sweep" AGL-2157
+ *    named as the real fix and deferred for the same reason.
+ *
+ *    And the flag is not even the only lock. Deleting it does not make a
+ *    redelivery decrement: `cartRef.delete()` runs between the guard and the
+ *    inventory loop, so the second delivery iterates an empty cart. A
+ *    resumable path would additionally have to stop reading the cart and
+ *    start reading the order's own `lineItems`. That is measured, not
+ *    assumed — `stock-decrement-reconciliation.spec.ts` pins it.
+ *
+ * This is read-only against orders, products and the ledger. The only thing
+ * it writes is its own report marker, in a collection nothing else touches.
+ */ /**
+ * The statuses an order can only be in if its stock decrement was ATTEMPTED.
+ *
+ * `pending` is excluded because it is the pre-payment state of a draft link
+ * and a POS card sale — neither has decremented yet, and both are supposed to
+ * look exactly like this. `cancelled` and `refunded` are excluded because
+ * `cancel-order.ts` and `refund.ts` write `reason: 'cancellation'` /
+ * `'refund'` rows and may have released the units already; a sale row missing
+ * from an order that has been through a release is a question this detector
+ * cannot answer from the ledger alone, and guessing would be worse than
+ * staying quiet.
+ */ const DECREMENTED_STATUSES = new Set([
+    'paid',
+    'partially_fulfilled',
+    'fulfilled',
+    'delivered'
+]);
+/**
+ * How long an order gets to finish its own decrement before it counts as
+ * diverged. The decrement runs milliseconds to seconds after the order
+ * commits, so ten minutes is far past any healthy webhook — and a beat that
+ * flagged an order the webhook was still working on would report a divergence
+ * that fixed itself, which is the fastest way to make a signal ignored.
+ */ const DEFAULT_GRACE_MS = 10 * 60 * 1000;
+/**
+ * Compares one host's recently-decremented orders against the
+ * `reason: 'sale'` rows joined to them, and reports the lines whose decrement
+ * is missing.
+ *
+ * Reads are bounded and cheap in the healthy case: two collection queries per
+ * host, and a product read ONLY for a line that already looks divergent.
+ *
+ * Two equality-free queries so the automatic single-field indexes answer them
+ * (the `cancel-order.ts` rule): `orderBy(createdAtMs desc).limit()` and
+ * `orderBy(atMs desc).limit()`, with the status test applied in memory over
+ * the handful of documents that come back.
+ */ export async function reconcileHostStockDecrements(options) {
+    var _orderSnapshot_docs, _ledgerSnapshot_docs;
+    const { hostRef, hostId, nowMs = Date.now(), graceMs = DEFAULT_GRACE_MS, orderLimit = 100, ledgerLimit = 500 } = options;
+    const empty = {
+        ordersScanned: 0,
+        ordersChecked: 0,
+        missing: [],
+        ledgerTruncated: false
+    };
+    const orderSnapshot = await hostRef.collection('orders').orderBy('createdAtMs', 'desc').limit(orderLimit).get().catch(()=>null);
+    if (!orderSnapshot) return empty;
+    const orderDocs = (_orderSnapshot_docs = orderSnapshot.docs) != null ? _orderSnapshot_docs : [];
+    const settledBefore = nowMs - graceMs;
+    let candidates = orderDocs.map((doc)=>{
+        var _doc_get, _doc_get1, _doc_get2;
+        return {
+            id: String(doc.id),
+            status: String((_doc_get = doc.get('status')) != null ? _doc_get : ''),
+            createdAtMs: Number((_doc_get1 = doc.get('createdAtMs')) != null ? _doc_get1 : 0),
+            number: doc.get('number') == null ? null : Number(doc.get('number')),
+            lineItems: (_doc_get2 = doc.get('lineItems')) != null ? _doc_get2 : []
+        };
+    }).filter((order)=>DECREMENTED_STATUSES.has(order.status) && order.createdAtMs > 0 && order.createdAtMs <= settledBefore);
+    if (!candidates.length) {
+        return _extends({}, empty, {
+            ordersScanned: orderDocs.length
+        });
+    }
+    const ledgerSnapshot = await hostRef.collection('inventoryAdjustments').orderBy('atMs', 'desc').limit(ledgerLimit).get().catch(()=>null);
+    if (!ledgerSnapshot) {
+        return _extends({}, empty, {
+            ordersScanned: orderDocs.length
+        });
+    }
+    const ledgerDocs = (_ledgerSnapshot_docs = ledgerSnapshot.docs) != null ? _ledgerSnapshot_docs : [];
+    // `orderId|productId` -> the variant ids that order's sale rows name.
+    const soldVariants = new Map();
+    let oldestLedgerMs = Number.POSITIVE_INFINITY;
+    for (const row of ledgerDocs){
+        var _row_get, _row_get1, _row_get2, _soldVariants_get, _row_get3;
+        const atMs = Number((_row_get = row.get('atMs')) != null ? _row_get : 0);
+        if (atMs > 0) oldestLedgerMs = Math.min(oldestLedgerMs, atMs);
+        if (row.get('reason') !== 'sale') continue;
+        const orderId = String((_row_get1 = row.get('orderId')) != null ? _row_get1 : '');
+        const productId = String((_row_get2 = row.get('productId')) != null ? _row_get2 : '');
+        if (!orderId || !productId) continue;
+        const key = `${orderId}|${productId}`;
+        const seen = (_soldVariants_get = soldVariants.get(key)) != null ? _soldVariants_get : new Set();
+        seen.add(String((_row_get3 = row.get('variantId')) != null ? _row_get3 : ''));
+        soldVariants.set(key, seen);
+    }
+    // A ledger read that hit its limit says nothing about anything older than
+    // its oldest row. Those orders are dropped, not judged.
+    const ledgerTruncated = ledgerDocs.length >= ledgerLimit && Number.isFinite(oldestLedgerMs) && candidates.some((order)=>order.createdAtMs < oldestLedgerMs);
+    if (ledgerTruncated) {
+        candidates = candidates.filter((order)=>order.createdAtMs >= oldestLedgerMs);
+    }
+    const missing = [];
+    const productCache = new Map();
+    for (const order of candidates){
+        var _order_lineItems;
+        for (const line of (_order_lineItems = order.lineItems) != null ? _order_lineItems : []){
+            var _ref, _ref1, _ref2, _ref3, _product_name;
+            var _product_variants_;
+            const productId = String((_ref = line == null ? void 0 : line.productId) != null ? _ref : '');
+            const quantity = Number((_ref1 = line == null ? void 0 : line.quantity) != null ? _ref1 : 0);
+            if (!productId || quantity <= 0) continue;
+            // A digital or service line never decrements — `decrementVariantStock`
+            // refuses an untracked variant — so its missing sale row is the correct
+            // outcome and must not cost a product read on every pass. The line's
+            // own purchase-time snapshot answers this; anything else falls through
+            // to the live tracked-ness test below.
+            if ((line == null ? void 0 : line.productType) === 'digital' || (line == null ? void 0 : line.productType) === 'service') {
+                continue;
+            }
+            const sold = soldVariants.get(`${order.id}|${productId}`);
+            const declaredVariantId = (line == null ? void 0 : line.variantId) ? String(line.variantId) : '';
+            if (declaredVariantId && (sold == null ? void 0 : sold.has(declaredVariantId))) continue;
+            if (!declaredVariantId && (sold == null ? void 0 : sold.size)) continue;
+            // Only now is a product read worth taking: this line already looks
+            // divergent, and the live product is what says whether it could ever
+            // have decremented at all.
+            if (!productCache.has(productId)) {
+                const productDoc = await hostRef.collection('products').doc(productId).get().catch(()=>null);
+                productCache.set(productId, (productDoc == null ? void 0 : productDoc.exists) ? CommerceModel.liftLegacyProduct(productDoc.data()) : null);
+            }
+            const product = productCache.get(productId);
+            // A product deleted since the sale is the `unresolvedLines` case the
+            // webhook already reports on the order itself (AGL-2149). Nothing here
+            // can tell whether its variant was tracked, so it is left alone.
+            if (!product) continue;
+            const variantId = declaredVariantId || String((_ref2 = (_product_variants_ = product.variants[0]) == null ? void 0 : _product_variants_.id) != null ? _ref2 : '');
+            if (!variantId) continue;
+            // Re-asked for a line that named no variant: the ledger row records the
+            // RESOLVED id, so the default variant has to be resolved before the
+            // absence means anything.
+            if (!declaredVariantId && (sold == null ? void 0 : sold.has(variantId))) continue;
+            const tracked = product.variants.some((variant)=>variant.id === variantId && variant.inventory != null);
+            // An untracked variant is a shelf nobody is counting. Its sale row is
+            // absent by design, and this is also the one place the detector can be
+            // wrong in the merchant's favour: tracking turned ON after the sale
+            // makes an order that correctly never decremented look divergent. The
+            // window is bounded by `orderLimit` and the report says what it is.
+            if (!tracked) continue;
+            missing.push({
+                hostId,
+                orderId: order.id,
+                orderNumber: order.number,
+                orderStatus: order.status,
+                orderCreatedAtMs: order.createdAtMs,
+                productId,
+                productName: String((_ref3 = (_product_name = product.name) != null ? _product_name : line == null ? void 0 : line.name) != null ? _ref3 : 'Product'),
+                variantId,
+                quantity
+            });
+        }
+    }
+    return {
+        ordersScanned: orderDocs.length,
+        ordersChecked: candidates.length,
+        missing,
+        ledgerTruncated
+    };
+}
+/**
+ * Reports a host's divergences to its managers, once per order.
+ *
+ * The marker in `hosts/{hostId}/inventoryReconciliation/{orderId}` is the only
+ * write this whole pass makes, and it lives in a collection nothing else on
+ * the platform reads or writes — the detector must not be able to affect the
+ * money path it is watching. Without it a beat would re-nag every hour about
+ * an order the merchant has already corrected, and an alert that repeats
+ * forever is one that gets muted.
+ */ export async function reportMissingSaleDecrements(hostId, missing) {
+    if (!missing.length) return 0;
+    const firestore = firebaseAdmin.app().firestore();
+    const hostRef = firestore.collection('hosts').doc(hostId);
+    const byOrder = new Map();
+    for (const row of missing){
+        var _byOrder_get;
+        byOrder.set(row.orderId, [
+            ...(_byOrder_get = byOrder.get(row.orderId)) != null ? _byOrder_get : [],
+            row
+        ]);
+    }
+    let reported = 0;
+    for (const [orderId, lines] of byOrder){
+        const markerRef = hostRef.collection('inventoryReconciliation').doc(orderId);
+        const marker = await markerRef.get().catch(()=>null);
+        // A read that FAILED is not a marker that is absent. Skipping here costs
+        // one delayed report; treating it as absent would re-notify every pass
+        // for as long as the read kept failing.
+        if (!marker || marker.exists) continue;
+        const units = lines.reduce((sum, line)=>sum + line.quantity, 0);
+        const label = lines[0].orderNumber == null ? orderId : `#${lines[0].orderNumber}`;
+        await markerRef.set({
+            orderId,
+            reportedAtMs: Date.now(),
+            lines: lines.map((line)=>({
+                    productId: line.productId,
+                    variantId: line.variantId,
+                    quantity: line.quantity
+                }))
+        }).catch(()=>undefined);
+        reported += 1;
+        console.error('commerce stock decrement missing', {
+            hostId,
+            orderId,
+            lines: lines.map((line)=>({
+                    productId: line.productId,
+                    variantId: line.variantId,
+                    quantity: line.quantity
+                }))
+        });
+        void notifyHostManagers(hostId, {
+            type: 'content.lowStock',
+            title: `Stock never came off the shelf — order ${label}`,
+            body: `Order ${label} is ${lines[0].orderStatus} but ${units} unit` + `${units === 1 ? '' : 's'} of ` + `${lines.map((line)=>line.productName).join(', ')} were never ` + 'taken off the count, so the storefront is still offering stock ' + 'that has been sold. Adjust the count by hand.',
+            link: `/${hostId}/products`
+        });
+    }
+    return reported;
+}
+/**
+ * The platform beat: the most recent orders across every host, grouped by
+ * host and reconciled one host at a time.
+ *
+ * Ordered by `createdAtMs` and NOT filtered by status, because an equality
+ * filter plus an ordering is a composite index and the ordering alone is a
+ * field override — the same trade `cancel-order.ts` takes. Every order writer
+ * in the plugin stamps `createdAtMs` (cart, buy-now, draft, POS cash, POS
+ * card, subscription cycle), so nothing is invisible to the ordering.
+ */ export async function scanStockDecrements(/** The lockdown gate, injected by the caller (AGL-2495). Not optional. */ gate, options) {
+    var _ref, _snapshot_docs;
+    const firestore = firebaseAdmin.app().firestore();
+    const snapshot = await firestore.collectionGroup('orders').orderBy('createdAtMs', 'desc').limit((_ref = options == null ? void 0 : options.orderLimit) != null ? _ref : 300).get().catch((error)=>{
+        console.error('commerce stock reconciliation scan failed', error);
+        return null;
+    });
+    const scan = {
+        hosts: 0,
+        ordersScanned: 0,
+        missingLines: 0,
+        reportedOrders: 0,
+        truncatedHosts: 0,
+        skippedLocked: 0
+    };
+    if (!snapshot) return scan;
+    const hostIds = new Set();
+    for (const doc of (_snapshot_docs = snapshot.docs) != null ? _snapshot_docs : []){
+        var _doc_ref_parent, _doc_ref, _hostRef_parent;
+        const hostRef = (_doc_ref = doc.ref) == null ? void 0 : (_doc_ref_parent = _doc_ref.parent) == null ? void 0 : _doc_ref_parent.parent;
+        // `hosts/{hostId}/orders` is the only shape this collection group has
+        // today; the check is what keeps that true if a second one appears.
+        if (!hostRef || ((_hostRef_parent = hostRef.parent) == null ? void 0 : _hostRef_parent.id) !== 'hosts') continue;
+        hostIds.add(String(hostRef.id));
+    }
+    scan.hosts = hostIds.size;
+    for (const hostId of hostIds){
+        // LOCKDOWN (AGL-2495). This pass posts a console notification and stamps
+        // the order timeline, so it is a write for the host — and on a site taken
+        // down for abuse or a legal order, telling its managers about stock is
+        // both a mutation and a message the takedown was meant to stop.
+        //
+        // SKIPPED, NOT DROPPED: the reconciliation is a DETECTOR with no cursor.
+        // It re-derives everything from the last N orders on every beat, so a
+        // host skipped now is reconciled in full on the first hourly beat after
+        // the lift, and nothing it would have found is lost by waiting.
+        if (await gate.isLocked(hostId)) {
+            scan.skippedLocked += 1;
+            continue;
+        }
+        const result = await reconcileHostStockDecrements(_extends({
+            firestore,
+            hostRef: firestore.collection('hosts').doc(hostId),
+            hostId
+        }, (options == null ? void 0 : options.nowMs) == null ? {} : {
+            nowMs: options.nowMs
+        }));
+        scan.ordersScanned += result.ordersScanned;
+        scan.missingLines += result.missing.length;
+        if (result.ledgerTruncated) scan.truncatedHosts += 1;
+        scan.reportedOrders += await reportMissingSaleDecrements(hostId, result.missing);
+    }
+    return scan;
+}
+
+//# sourceMappingURL=reconcile-stock.js.map

package/src/lib/server/reconcile-stock.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/reconcile-stock.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { type PluginJobHostGate } from '@aglyn/aglyn/server'\nimport { firebaseAdmin, notifyHostManagers } from '@aglyn/tenant-data-admin'\nimport * as CommerceModel from '../model'\n\n/**\n * THE MISSING-DECREMENT DETECTOR (AGL-2358).\n *\n * Every order-minting branch of `billing-webhook.ts` commits the order in a\n * transaction and decrements stock AFTER it, and every branch guards on a\n * replay flag that transaction set — `created` for cart and buy-now,\n * `flipped` for the draft/POS-card branch, the invoice-id guard for a\n * subscription cycle. So a process that dies in the window between the two\n * loses the decrement PERMANENTLY: Stripe redelivers, the guard says the\n * order already exists, and the handler returns without ever reaching the\n * stock write. The merchant has a paid order and an untouched shelf, and\n * before this nothing anywhere recorded that they had diverged.\n *\n * `/api/billing/webhook`'s own claim marker makes the same window wider, not\n * narrower: AGL-2157 decided that an event which throws mid-dispatch KEEPS\n * its claim — deliberately, because re-running the dispatch could double-apply\n * a gift-card spend or a coupon redemption — and told staff to \"reconcile by\n * hand\". This is the thing they reconcile with. It is also the only detector\n * for the death AGL-2157 cannot catch at all: a timeout, an OOM or a deploy\n * kill unwinds no stack, so that route's `catch` never runs and no staff\n * notice is ever raised.\n *\n * WHY A DETECTOR AND NOT THE FIX. The two real fixes were both weighed and\n * both rejected for this side of the Sept 1 freeze:\n *\n *  - Folding the decrement into the order transaction would restructure the\n *    checkout path's largest and most contended transaction, days before\n *    launch, on the path that takes money. The cart branch alone would have\n *    to pull N product reads into a transaction that currently reads two\n *    documents, and every contended retry would then re-run order numbering.\n *  - A second replay flag with a re-entry path is worse, not better. The\n *    `created` guard is not protecting the decrement — it is protecting\n *    licence-key assignment, coupon redemption counters, gift-card balances,\n *    receipt email and contact ingestion, all behind ONE flag. Any re-entry\n *    past it needs every one of those to become individually idempotent\n *    first, which is precisely the \"per-EFFECT idempotency sweep\" AGL-2157\n *    named as the real fix and deferred for the same reason.\n *\n *    And the flag is not even the only lock. Deleting it does not make a\n *    redelivery decrement: `cartRef.delete()` runs between the guard and the\n *    inventory loop, so the second delivery iterates an empty cart. A\n *    resumable path would additionally have to stop reading the cart and\n *    start reading the order's own `lineItems`. That is measured, not\n *    assumed — `stock-decrement-reconciliation.spec.ts` pins it.\n *\n * This is read-only against orders, products and the ledger. The only thing\n * it writes is its own report marker, in a collection nothing else touches.\n */\n\n/**\n * The statuses an order can only be in if its stock decrement was ATTEMPTED.\n *\n * `pending` is excluded because it is the pre-payment state of a draft link\n * and a POS card sale — neither has decremented yet, and both are supposed to\n * look exactly like this. `cancelled` and `refunded` are excluded because\n * `cancel-order.ts` and `refund.ts` write `reason: 'cancellation'` /\n * `'refund'` rows and may have released the units already; a sale row missing\n * from an order that has been through a release is a question this detector\n * cannot answer from the ledger alone, and guessing would be worse than\n * staying quiet.\n */\nconst DECREMENTED_STATUSES: ReadonlySet<string> = new Set([\n  'paid',\n  'partially_fulfilled',\n  'fulfilled',\n  'delivered',\n])\n\n/**\n * How long an order gets to finish its own decrement before it counts as\n * diverged. The decrement runs milliseconds to seconds after the order\n * commits, so ten minutes is far past any healthy webhook — and a beat that\n * flagged an order the webhook was still working on would report a divergence\n * that fixed itself, which is the fastest way to make a signal ignored.\n */\nconst DEFAULT_GRACE_MS = 10 * 60 * 1000\n\nexport interface MissingSaleDecrement {\n  hostId: string\n  orderId: string\n  /** The merchant-facing sequential number, when the doc carries one. */\n  orderNumber: number | null\n  orderStatus: string\n  orderCreatedAtMs: number\n  productId: string\n  /** Live product name — the order's snapshot name is used as a fallback. */\n  productName: string\n  variantId: string\n  /** Units the order says were sold, and the shelf therefore still holds. */\n  quantity: number\n}\n\nexport interface StockReconciliationResult {\n  ordersScanned: number\n  /** Orders that reached the ledger comparison (post status/grace filter). */\n  ordersChecked: number\n  missing: MissingSaleDecrement[]\n  /**\n   * The ledger read hit its limit before reaching back as far as the oldest\n   * order considered, so orders older than the ledger window were DROPPED\n   * rather than judged against rows that were never read.\n   *\n   * Recorded and reported rather than swallowed, for the AGL-2321 reason:\n   * `siteSizeTruncated` exists because a number that is silently a lower\n   * bound is worse than one that says so. A truncated pass under-reports; it\n   * must never be read as \"all matched\".\n   */\n  ledgerTruncated: boolean\n}\n\n/**\n * Compares one host's recently-decremented orders against the\n * `reason: 'sale'` rows joined to them, and reports the lines whose decrement\n * is missing.\n *\n * Reads are bounded and cheap in the healthy case: two collection queries per\n * host, and a product read ONLY for a line that already looks divergent.\n *\n * Two equality-free queries so the automatic single-field indexes answer them\n * (the `cancel-order.ts` rule): `orderBy(createdAtMs desc).limit()` and\n * `orderBy(atMs desc).limit()`, with the status test applied in memory over\n * the handful of documents that come back.\n */\nexport async function reconcileHostStockDecrements(options: {\n  firestore: any\n  hostRef: any\n  hostId: string\n  nowMs?: number\n  graceMs?: number\n  orderLimit?: number\n  ledgerLimit?: number\n}): Promise<StockReconciliationResult> {\n  const {\n    hostRef,\n    hostId,\n    nowMs = Date.now(),\n    graceMs = DEFAULT_GRACE_MS,\n    orderLimit = 100,\n    ledgerLimit = 500,\n  } = options\n  const empty: StockReconciliationResult = {\n    ordersScanned: 0,\n    ordersChecked: 0,\n    missing: [],\n    ledgerTruncated: false,\n  }\n  const orderSnapshot = await hostRef\n    .collection('orders')\n    .orderBy('createdAtMs', 'desc')\n    .limit(orderLimit)\n    .get()\n    .catch(() => null)\n  if (!orderSnapshot) return empty\n  const orderDocs: any[] = orderSnapshot.docs ?? []\n  const settledBefore = nowMs - graceMs\n  let candidates = orderDocs\n    .map((doc) => ({\n      id: String(doc.id),\n      status: String(doc.get('status') ?? ''),\n      createdAtMs: Number(doc.get('createdAtMs') ?? 0),\n      number: doc.get('number') == null ? null : Number(doc.get('number')),\n      lineItems: (doc.get('lineItems') ?? []) as CommerceModel.OrderLineItem[],\n    }))\n    .filter(\n      (order) =>\n        DECREMENTED_STATUSES.has(order.status) &&\n        order.createdAtMs > 0 &&\n        order.createdAtMs <= settledBefore,\n    )\n  if (!candidates.length) {\n    return { ...empty, ordersScanned: orderDocs.length }\n  }\n  const ledgerSnapshot = await hostRef\n    .collection('inventoryAdjustments')\n    .orderBy('atMs', 'desc')\n    .limit(ledgerLimit)\n    .get()\n    .catch(() => null)\n  if (!ledgerSnapshot) {\n    return { ...empty, ordersScanned: orderDocs.length }\n  }\n  const ledgerDocs: any[] = ledgerSnapshot.docs ?? []\n  // `orderId|productId` -> the variant ids that order's sale rows name.\n  const soldVariants = new Map<string, Set<string>>()\n  let oldestLedgerMs = Number.POSITIVE_INFINITY\n  for (const row of ledgerDocs) {\n    const atMs = Number(row.get('atMs') ?? 0)\n    if (atMs > 0) oldestLedgerMs = Math.min(oldestLedgerMs, atMs)\n    if (row.get('reason') !== 'sale') continue\n    const orderId = String(row.get('orderId') ?? '')\n    const productId = String(row.get('productId') ?? '')\n    if (!orderId || !productId) continue\n    const key = `${orderId}|${productId}`\n    const seen = soldVariants.get(key) ?? new Set<string>()\n    seen.add(String(row.get('variantId') ?? ''))\n    soldVariants.set(key, seen)\n  }\n  // A ledger read that hit its limit says nothing about anything older than\n  // its oldest row. Those orders are dropped, not judged.\n  const ledgerTruncated =\n    ledgerDocs.length >= ledgerLimit &&\n    Number.isFinite(oldestLedgerMs) &&\n    candidates.some((order) => order.createdAtMs < oldestLedgerMs)\n  if (ledgerTruncated) {\n    candidates = candidates.filter(\n      (order) => order.createdAtMs >= oldestLedgerMs,\n    )\n  }\n  const missing: MissingSaleDecrement[] = []\n  const productCache = new Map<string, CommerceModel.HostProduct | null>()\n  for (const order of candidates) {\n    for (const line of order.lineItems ?? []) {\n      const productId = String(line?.productId ?? '')\n      const quantity = Number(line?.quantity ?? 0)\n      if (!productId || quantity <= 0) continue\n      // A digital or service line never decrements — `decrementVariantStock`\n      // refuses an untracked variant — so its missing sale row is the correct\n      // outcome and must not cost a product read on every pass. The line's\n      // own purchase-time snapshot answers this; anything else falls through\n      // to the live tracked-ness test below.\n      if (line?.productType === 'digital' || line?.productType === 'service') {\n        continue\n      }\n      const sold = soldVariants.get(`${order.id}|${productId}`)\n      const declaredVariantId = line?.variantId ? String(line.variantId) : ''\n      if (declaredVariantId && sold?.has(declaredVariantId)) continue\n      if (!declaredVariantId && sold?.size) continue\n      // Only now is a product read worth taking: this line already looks\n      // divergent, and the live product is what says whether it could ever\n      // have decremented at all.\n      if (!productCache.has(productId)) {\n        const productDoc = await hostRef\n          .collection('products')\n          .doc(productId)\n          .get()\n          .catch(() => null)\n        productCache.set(\n          productId,\n          productDoc?.exists\n            ? CommerceModel.liftLegacyProduct(productDoc.data() as any)\n            : null,\n        )\n      }\n      const product = productCache.get(productId)\n      // A product deleted since the sale is the `unresolvedLines` case the\n      // webhook already reports on the order itself (AGL-2149). Nothing here\n      // can tell whether its variant was tracked, so it is left alone.\n      if (!product) continue\n      const variantId =\n        declaredVariantId || String(product.variants[0]?.id ?? '')\n      if (!variantId) continue\n      // Re-asked for a line that named no variant: the ledger row records the\n      // RESOLVED id, so the default variant has to be resolved before the\n      // absence means anything.\n      if (!declaredVariantId && sold?.has(variantId)) continue\n      const tracked = product.variants.some(\n        (variant) => variant.id === variantId && variant.inventory != null,\n      )\n      // An untracked variant is a shelf nobody is counting. Its sale row is\n      // absent by design, and this is also the one place the detector can be\n      // wrong in the merchant's favour: tracking turned ON after the sale\n      // makes an order that correctly never decremented look divergent. The\n      // window is bounded by `orderLimit` and the report says what it is.\n      if (!tracked) continue\n      missing.push({\n        hostId,\n        orderId: order.id,\n        orderNumber: order.number,\n        orderStatus: order.status,\n        orderCreatedAtMs: order.createdAtMs,\n        productId,\n        productName: String(product.name ?? line?.name ?? 'Product'),\n        variantId,\n        quantity,\n      })\n    }\n  }\n  return {\n    ordersScanned: orderDocs.length,\n    ordersChecked: candidates.length,\n    missing,\n    ledgerTruncated,\n  }\n}\n\n/**\n * Reports a host's divergences to its managers, once per order.\n *\n * The marker in `hosts/{hostId}/inventoryReconciliation/{orderId}` is the only\n * write this whole pass makes, and it lives in a collection nothing else on\n * the platform reads or writes — the detector must not be able to affect the\n * money path it is watching. Without it a beat would re-nag every hour about\n * an order the merchant has already corrected, and an alert that repeats\n * forever is one that gets muted.\n */\nexport async function reportMissingSaleDecrements(\n  hostId: string,\n  missing: readonly MissingSaleDecrement[],\n): Promise<number> {\n  if (!missing.length) return 0\n  const firestore = firebaseAdmin.app().firestore()\n  const hostRef = firestore.collection('hosts').doc(hostId)\n  const byOrder = new Map<string, MissingSaleDecrement[]>()\n  for (const row of missing) {\n    byOrder.set(row.orderId, [...(byOrder.get(row.orderId) ?? []), row])\n  }\n  let reported = 0\n  for (const [orderId, lines] of byOrder) {\n    const markerRef = hostRef.collection('inventoryReconciliation').doc(orderId)\n    const marker = await markerRef.get().catch(() => null)\n    // A read that FAILED is not a marker that is absent. Skipping here costs\n    // one delayed report; treating it as absent would re-notify every pass\n    // for as long as the read kept failing.\n    if (!marker || marker.exists) continue\n    const units = lines.reduce((sum, line) => sum + line.quantity, 0)\n    const label =\n      lines[0].orderNumber == null ? orderId : `#${lines[0].orderNumber}`\n    await markerRef\n      .set({\n        orderId,\n        reportedAtMs: Date.now(),\n        lines: lines.map((line) => ({\n          productId: line.productId,\n          variantId: line.variantId,\n          quantity: line.quantity,\n        })),\n      })\n      .catch(() => undefined)\n    reported += 1\n    console.error('commerce stock decrement missing', {\n      hostId,\n      orderId,\n      lines: lines.map((line) => ({\n        productId: line.productId,\n        variantId: line.variantId,\n        quantity: line.quantity,\n      })),\n    })\n    void notifyHostManagers(hostId, {\n      type: 'content.lowStock',\n      title: `Stock never came off the shelf — order ${label}`,\n      body:\n        `Order ${label} is ${lines[0].orderStatus} but ${units} unit` +\n        `${units === 1 ? '' : 's'} of ` +\n        `${lines.map((line) => line.productName).join(', ')} were never ` +\n        'taken off the count, so the storefront is still offering stock ' +\n        'that has been sold. Adjust the count by hand.',\n      link: `/${hostId}/products`,\n    })\n  }\n  return reported\n}\n\nexport interface StockReconciliationScan {\n  hosts: number\n  ordersScanned: number\n  missingLines: number\n  reportedOrders: number\n  truncatedHosts: number\n  /** Hosts left unreconciled because they are locked (AGL-2495). */\n  skippedLocked: number\n}\n\n/**\n * The platform beat: the most recent orders across every host, grouped by\n * host and reconciled one host at a time.\n *\n * Ordered by `createdAtMs` and NOT filtered by status, because an equality\n * filter plus an ordering is a composite index and the ordering alone is a\n * field override — the same trade `cancel-order.ts` takes. Every order writer\n * in the plugin stamps `createdAtMs` (cart, buy-now, draft, POS cash, POS\n * card, subscription cycle), so nothing is invisible to the ordering.\n */\nexport async function scanStockDecrements(\n  /** The lockdown gate, injected by the caller (AGL-2495). Not optional. */\n  gate: PluginJobHostGate,\n  options?: {\n    orderLimit?: number\n    nowMs?: number\n  },\n): Promise<StockReconciliationScan> {\n  const firestore = firebaseAdmin.app().firestore()\n  const snapshot = await firestore\n    .collectionGroup('orders')\n    .orderBy('createdAtMs', 'desc')\n    .limit(options?.orderLimit ?? 300)\n    .get()\n    .catch((error: unknown) => {\n      console.error('commerce stock reconciliation scan failed', error)\n      return null\n    })\n  const scan: StockReconciliationScan = {\n    hosts: 0,\n    ordersScanned: 0,\n    missingLines: 0,\n    reportedOrders: 0,\n    truncatedHosts: 0,\n    skippedLocked: 0,\n  }\n  if (!snapshot) return scan\n  const hostIds = new Set<string>()\n  for (const doc of (snapshot.docs ?? []) as any[]) {\n    const hostRef = doc.ref?.parent?.parent\n    // `hosts/{hostId}/orders` is the only shape this collection group has\n    // today; the check is what keeps that true if a second one appears.\n    if (!hostRef || hostRef.parent?.id !== 'hosts') continue\n    hostIds.add(String(hostRef.id))\n  }\n  scan.hosts = hostIds.size\n  for (const hostId of hostIds) {\n    // LOCKDOWN (AGL-2495). This pass posts a console notification and stamps\n    // the order timeline, so it is a write for the host — and on a site taken\n    // down for abuse or a legal order, telling its managers about stock is\n    // both a mutation and a message the takedown was meant to stop.\n    //\n    // SKIPPED, NOT DROPPED: the reconciliation is a DETECTOR with no cursor.\n    // It re-derives everything from the last N orders on every beat, so a\n    // host skipped now is reconciled in full on the first hourly beat after\n    // the lift, and nothing it would have found is lost by waiting.\n    if (await gate.isLocked(hostId)) {\n      scan.skippedLocked += 1\n      continue\n    }\n    const result = await reconcileHostStockDecrements({\n      firestore,\n      hostRef: firestore.collection('hosts').doc(hostId),\n      hostId,\n      ...(options?.nowMs == null ? {} : { nowMs: options.nowMs }),\n    })\n    scan.ordersScanned += result.ordersScanned\n    scan.missingLines += result.missing.length\n    if (result.ledgerTruncated) scan.truncatedHosts += 1\n    scan.reportedOrders += await reportMissingSaleDecrements(\n      hostId,\n      result.missing,\n    )\n  }\n  return scan\n}\n"],"names":["firebaseAdmin","notifyHostManagers","CommerceModel","DECREMENTED_STATUSES","Set","DEFAULT_GRACE_MS","reconcileHostStockDecrements","options","orderSnapshot","ledgerSnapshot","hostRef","hostId","nowMs","Date","now","graceMs","orderLimit","ledgerLimit","empty","ordersScanned","ordersChecked","missing","ledgerTruncated","collection","orderBy","limit","get","catch","orderDocs","docs","settledBefore","candidates","map","doc","id","String","status","createdAtMs","Number","number","lineItems","filter","order","has","length","ledgerDocs","soldVariants","Map","oldestLedgerMs","POSITIVE_INFINITY","row","atMs","Math","min","orderId","productId","key","seen","add","set","isFinite","some","productCache","line","product","quantity","productType","sold","declaredVariantId","variantId","size","productDoc","exists","liftLegacyProduct","data","variants","tracked","variant","inventory","push","orderNumber","orderStatus","orderCreatedAtMs","productName","name","reportMissingSaleDecrements","firestore","app","byOrder","reported","lines","markerRef","marker","units","reduce","sum","label","reportedAtMs","undefined","console","error","type","title","body","join","link","scanStockDecrements","gate","snapshot","collectionGroup","scan","hosts","missingLines","reportedOrders","truncatedHosts","skippedLocked","hostIds","ref","parent","isLocked","result"],"mappings":"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"}

package/src/lib/server/refund.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * Order refunds (AGL-287): full or partial via Stripe, site-admin only
+ * (it moves money). Destination charges reverse the transfer and the
+ * platform fee proportionally. Full refunds transition the order to
+ * `refunded`; partial refunds accumulate `refundedCents` and stay in
+ * the current status.
+ *
+ * Two SEPARATE controls guard the money (AGL-1696), and conflating them is
+ * how the original went wrong:
+ *
+ *  - The idempotency key stops a DUPLICATE refund — one attempt sent twice
+ *    because the response was lost, the admin double-clicked, or a client
+ *    retried. It is minted per attempt by the console and deliberately not
+ *    derived from the order or the amount: two $10 refunds on a $50 order are
+ *    two real refunds, exactly as a cashier ringing the same coffee twice is a
+ *    real second sale.
+ *  - The cap stops an OVER-refund — several partials summing past what was
+ *    captured, including two admins refunding at once, where the two attempts
+ *    are genuinely distinct and no key can help. That needs the counter read
+ *    and written inside one transaction.
+ *
+ * The original had a cap that looked like both and was neither: it read
+ * `refundedCents` and wrote it back only AFTER the Stripe call, outside any
+ * transaction. A guard that reads state the guarded operation writes too late
+ * is not a guard — measured, two concurrent refunds each sent a full $50 to
+ * Stripe with no idempotency header on either.
+ */
+export declare const refundHandler: PluginApiHandler;