@aglyn/plugins-commerce 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/server/revenue-source.js

@@ -0,0 +1,286 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ /**
+ * The storefront's take on the operator's revenue report (AGL-2486, AGL-3080).
+ *
+ * Answered through the platform's revenue source contract
+ * (`@aglyn/aglyn/plugin-manager/plugin-revenue-sources`). The report folds the
+ * operator's own invoices; this is what storefront orders earned it — and the
+ * one figure on that page most likely to be reported wrongly.
+ *
+ * An order's `feeCents` is the Connect `application_fee_amount`, which since
+ * AGL-2152 is the advertised take PLUS Stripe's processing cost:
+ *
+ *     fee = take%(goods) + processing%(charge) + 30¢
+ *
+ * Every storefront charge is a DESTINATION charge, so Stripe moves the whole
+ * amount to the merchant and debits its processing fee from the PLATFORM's
+ * balance; the pass-through half of that fee exists purely to recover a cost
+ * the platform has already paid. Reporting `feeCents` as earnings would
+ * overstate the margin on every single storefront sale — and on a small order
+ * it would report the 30¢ Stripe just took as money the platform made.
+ *
+ * So the pass-through is recomputed with the SAME helper the fee was charged
+ * from (`saleProcessingCostCents`) and subtracted. Both halves are
+ * reported, because "we collected X of which Y was Stripe's" is the sentence a
+ * margin figure needs.
+ *
+ * The recomputation is an estimate in one direction only: it re-derives the
+ * cost from the stored charge amount rather than reading Stripe's actual
+ * balance-transaction fee, and it prices it at the DEAREST enabled payment
+ * method's rate (BNPL, 6%) because that is the rate the fee was charged at.
+ * A card-family order really costs 2.9%, so on those orders this subtracts
+ * more than Stripe took and the take is UNDERSTATED — the safe direction, and
+ * stated on the page rather than left to be discovered.
+ *
+ * ## Subscription cycles, and the one cycle this understates
+ *
+ * A storefront SUBSCRIPTION cycle carries a `subscriptionId`. Since AGL-2655
+ * its fee carries the same pass-through, folded into
+ * `application_fee_percent` as a rate because a Stripe subscription cannot
+ * express a fixed 30¢ — so it is netted out here exactly as a one-time sale's
+ * is. The percent is sized on the recurring goods and the recomputed cost here
+ * is sized on the whole amount paid, tax included, so a taxed cycle subtracts
+ * slightly more than was recovered: understated, the safe direction.
+ *
+ * A subscription sold before the pass-through existed is carried onto it by
+ * the renewal re-price (AGL-2289) at its next paid invoice — but THAT invoice
+ * was billed at the bare take, so its row's `feeCents` holds no pass-through
+ * and the clamp reports its take as zero. One cycle per legacy subscription,
+ * and the count beside the figure is how a reader sees how much of the book
+ * that is.
+ */ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { saleProcessingCostCents } from "@aglyn/aglyn/server";
+import { PLATFORM_BRAND_NAME } from "@aglyn/aglyn/app-utils/platform-brand";
+import { stripeIdIsTestMode } from "@aglyn/aglyn/app-utils/stripe-deployment-mode";
+import { groupRevenueAttribution } from "@aglyn/aglyn/plugin-manager/plugin-revenue-sources";
+/** Cents from anything, defaulting to 0 rather than NaN. */ function cents(value) {
+    const parsed = Number(value != null ? value : 0);
+    return Number.isFinite(parsed) ? Math.round(parsed) : 0;
+}
+/**
+ * Whether this order row was a test-mode rehearsal.
+ *
+ * A recorded `livemode` wins, and the session id's prefix is the fallback for
+ * rows written before anything recorded it. An order with neither signal is
+ * LIVE: a POS cash sale carries no Stripe session at all, and answering "test"
+ * for anything unidentifiable would erase genuine revenue from the report.
+ */ function isTestModeOrderRow(row) {
+    var _row_checkoutSessionId;
+    if (typeof row.livemode === 'boolean') return !row.livemode;
+    return stripeIdIsTestMode((_row_checkoutSessionId = row.checkoutSessionId) != null ? _row_checkoutSessionId : row.id);
+}
+export function commerceSettledSummary(rows, truncated = false) {
+    const out = {
+        transactionCount: 0,
+        grossCents: 0,
+        applicationFeeCents: 0,
+        processingPassThroughCents: 0,
+        commissionCents: 0,
+        commissionRefundedCents: 0,
+        commissionNetCents: 0,
+        subscriptionOrders: 0,
+        truncated: truncated === true
+    };
+    for (const row of rows != null ? rows : []){
+        // A REHEARSAL IS NOT REVENUE. A smoke-test checkout writes a real order
+        // document — Stripe never moved money for it, and its session id says so.
+        // Skipped ENTIRELY rather than counted at zero, because `transactionCount`
+        // is read as "how many sales", and a rehearsal is not one.
+        if (isTestModeOrderRow(row)) continue;
+        const split = commerceOrderTake(row);
+        out.transactionCount += 1;
+        out.grossCents += split.gross;
+        out.applicationFeeCents += split.fee;
+        if (split.isSubscriptionOrder) out.subscriptionOrders += 1;
+        out.processingPassThroughCents += split.passThrough;
+        out.commissionCents += split.take;
+        out.commissionRefundedCents += split.takeRefunded;
+        out.commissionNetCents += split.takeNet;
+    }
+    return out;
+}
+/**
+ * One storefront order's take, in ONE place.
+ *
+ * Shared with the per-host attribution so a host table cannot sum to
+ * something other than the storefront line above it.
+ *
+ * A zero-fee order contributes its gross and its count and nothing else —
+ * there is no take to attribute, and inventing one from the gross would
+ * report a merchant's money as the platform's.
+ */ export function commerceOrderTake(row) {
+    const gross = cents(row == null ? void 0 : row.amountCents);
+    const fee = Math.max(0, cents(row == null ? void 0 : row.feeCents));
+    const isSubscriptionOrder = typeof (row == null ? void 0 : row.subscriptionId) === 'string' && row.subscriptionId.length > 0;
+    if (fee <= 0) {
+        return {
+            gross,
+            fee,
+            isSubscriptionOrder,
+            passThrough: 0,
+            take: 0,
+            takeRefunded: 0,
+            takeNet: 0
+        };
+    }
+    // Every fee bundles the recovery — a one-time sale's in cents, a
+    // subscription cycle's as a rate (AGL-2655). Clamped to the fee itself: the
+    // recomputed cost can exceed a fee charged under an older rate, and a
+    // negative take would subtract from another order's real margin.
+    const passThrough = Math.min(fee, saleProcessingCostCents(gross));
+    const take = fee - passThrough;
+    const refunded = Math.min(gross, Math.max(0, cents(row == null ? void 0 : row.refundedCents)));
+    const takeRefunded = gross > 0 ? Math.round(refunded * take / gross) : 0;
+    return {
+        gross,
+        fee,
+        isSubscriptionOrder,
+        passThrough,
+        take,
+        takeRefunded,
+        takeNet: take - takeRefunded
+    };
+}
+/**
+ * Storefront take by HOST.
+ *
+ * By host and not by org on purpose: one org can run several storefronts, and
+ * "which store earns" is the question a per-org roll-up destroys.
+ */ export function commerceHostAttribution(rows, limit = 100) {
+    return groupRevenueAttribution((rows != null ? rows : []).map((row)=>{
+        var _ref;
+        const split = commerceOrderTake(row);
+        return {
+            key: String((_ref = row == null ? void 0 : row.hostId) != null ? _ref : ''),
+            detail: '',
+            gain: split.takeNet,
+            loss: split.takeRefunded
+        };
+    }), limit, 'Host not recorded');
+}
+/**
+ * The storefront's answer for one period, from figures already folded. Pure,
+ * so what the report prints can be proved from fixtures.
+ *
+ * `failed` is a sweep that could not run — a collection-group index this
+ * deployment has not built answers FAILED_PRECONDITION — and it is reported as
+ * a failure with figures of zero, never as a cap: "we read part of it" and "we
+ * read none of it" have different remedies.
+ */ export function commerceRevenueAnswer(read) {
+    var _settled_commissionNetCents, _settled_subscriptionOrders;
+    const brand = PLATFORM_BRAND_NAME;
+    const { settled } = read;
+    return {
+        id: 'commerce',
+        name: 'storefront orders',
+        earned: {
+            label: 'Storefront commission',
+            cents: Number((_settled_commissionNetCents = settled.commissionNetCents) != null ? _settled_commissionNetCents : 0),
+            note: 'The advertised take on merchant storefront sales, net of refunds — ' + 'with Stripe’s card processing removed. The platform fee charged on a ' + 'storefront sale bundles that processing cost and passes it through at ' + 'cost; it is a recovery, not earnings.'
+        },
+        grossToNet: [
+            {
+                label: 'Storefront sales (shopper gross)',
+                cents: settled.grossCents,
+                deduction: false,
+                note: 'The merchant’s. It transfers straight to their connected account ' + 'and is shown only for scale.'
+            },
+            {
+                label: 'Storefront platform fee collected',
+                cents: settled.applicationFeeCents,
+                deduction: false,
+                note: `Not all ${brand}’s — see the next line.`
+            },
+            {
+                label: '— less card processing passed through at cost',
+                cents: settled.processingPassThroughCents,
+                deduction: true,
+                note: `Stripe’s. On a destination charge Stripe debits ${brand}’s balance for processing, and this half of the fee recovers exactly that. It is a recovery, not earnings, and reporting it as revenue would overstate every storefront sale.`
+            }
+        ],
+        notes: Number((_settled_subscriptionOrders = settled.subscriptionOrders) != null ? _settled_subscriptionOrders : 0) > 0 ? [
+            {
+                label: `${settled.subscriptionOrders} storefront subscription cycles — one billed before its re-price reports no take`,
+                tone: 'warning'
+            }
+        ] : [],
+        attribution: [
+            _extends({
+                id: 'byHost',
+                heading: 'Storefront take by host',
+                unit: 'Storefront',
+                countLabel: 'Orders',
+                empty: `No storefront order settled in this period. Note this is ${brand}'s take only — the shopper's spend is the merchant's money and is never counted here.`,
+                chartEmpty: 'No storefront earned a take in this period — nothing to plot yet.'
+            }, read.byHost)
+        ],
+        attributionNote: "Storefront figures above are the advertised take with Stripe's " + 'processing cost already subtracted, on the basis stated in “Gross ' + 'versus net” below. Attribution is by host rather than by org because ' + 'one org can run several storefronts, and rolling them up destroys the ' + 'question.',
+        truncated: settled.truncated,
+        failure: read.failed ? {
+            title: 'Storefront orders could not be read',
+            detail: 'The storefront commission below reads $0 because the query ' + 'failed, not because there were no sales. The sweep needs the ' + 'COLLECTION_GROUP index on orders.createdAtMs — check it is still ' + 'declared in the Firestore index config and actually deployed, ' + 'since indexes ship separately from the app.'
+        } : null,
+        summary: settled
+    };
+}
+/**
+ * The storefront's source, registered on the console's API surface: the
+ * staff revenue report awaits that surface before it asks.
+ */ export const commerceRevenueSource = {
+    async read (request) {
+        var _ref;
+        const firestore = firebaseAdmin.app().firestore();
+        // Storefront orders live per host (`hosts/{hostId}/orders`), so this is a
+        // collection-GROUP range — ranged on `createdAtMs`, the NUMBER, and not on
+        // the `createdAt` Timestamp beside it. A collection-group range needs a
+        // COLLECTION_GROUP-scoped single-field index — Firestore's automatic ones
+        // are COLLECTION scope only — and the index that is declared and deployed
+        // is on `createdAtMs` (AGL-1793). The `createdAt` form answers
+        // FAILED_PRECONDITION on every request, which is how the report once read
+        // $0 for every storefront.
+        let swept;
+        try {
+            swept = await request.sweep(firestore.collectionGroup('orders').where('createdAtMs', '>=', request.start.getTime()).where('createdAtMs', '<', request.end.getTime()), 'createdAtMs');
+        } catch (unused) {
+            swept = null;
+        }
+        const rows = ((_ref = swept == null ? void 0 : swept.docs) != null ? _ref : []).map((doc)=>{
+            var _ref;
+            var _doc_ref_parent_parent;
+            return _extends({
+                id: doc.id,
+                // The storefront that earned the take is in the PATH.
+                hostId: (_ref = (_doc_ref_parent_parent = doc.ref.parent.parent) == null ? void 0 : _doc_ref_parent_parent.id) != null ? _ref : ''
+            }, doc.data());
+        });
+        const settled = commerceSettledSummary(rows, (swept == null ? void 0 : swept.truncated) === true);
+        const byHost = commerceHostAttribution(rows, request.attributionLimit);
+        await request.nameRows(byHost.rows, {
+            collection: 'hosts',
+            nameField: 'displayName',
+            detailField: 'subdomain'
+        });
+        return commerceRevenueAnswer({
+            settled,
+            byHost,
+            failed: swept === null
+        });
+    }
+};
+
+//# sourceMappingURL=revenue-source.js.map

package/src/lib/server/revenue-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/revenue-source.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\n/**\n * The storefront's take on the operator's revenue report (AGL-2486, AGL-3080).\n *\n * Answered through the platform's revenue source contract\n * (`@aglyn/aglyn/plugin-manager/plugin-revenue-sources`). The report folds the\n * operator's own invoices; this is what storefront orders earned it — and the\n * one figure on that page most likely to be reported wrongly.\n *\n * An order's `feeCents` is the Connect `application_fee_amount`, which since\n * AGL-2152 is the advertised take PLUS Stripe's processing cost:\n *\n *     fee = take%(goods) + processing%(charge) + 30¢\n *\n * Every storefront charge is a DESTINATION charge, so Stripe moves the whole\n * amount to the merchant and debits its processing fee from the PLATFORM's\n * balance; the pass-through half of that fee exists purely to recover a cost\n * the platform has already paid. Reporting `feeCents` as earnings would\n * overstate the margin on every single storefront sale — and on a small order\n * it would report the 30¢ Stripe just took as money the platform made.\n *\n * So the pass-through is recomputed with the SAME helper the fee was charged\n * from (`saleProcessingCostCents`) and subtracted. Both halves are\n * reported, because \"we collected X of which Y was Stripe's\" is the sentence a\n * margin figure needs.\n *\n * The recomputation is an estimate in one direction only: it re-derives the\n * cost from the stored charge amount rather than reading Stripe's actual\n * balance-transaction fee, and it prices it at the DEAREST enabled payment\n * method's rate (BNPL, 6%) because that is the rate the fee was charged at.\n * A card-family order really costs 2.9%, so on those orders this subtracts\n * more than Stripe took and the take is UNDERSTATED — the safe direction, and\n * stated on the page rather than left to be discovered.\n *\n * ## Subscription cycles, and the one cycle this understates\n *\n * A storefront SUBSCRIPTION cycle carries a `subscriptionId`. Since AGL-2655\n * its fee carries the same pass-through, folded into\n * `application_fee_percent` as a rate because a Stripe subscription cannot\n * express a fixed 30¢ — so it is netted out here exactly as a one-time sale's\n * is. The percent is sized on the recurring goods and the recomputed cost here\n * is sized on the whole amount paid, tax included, so a taxed cycle subtracts\n * slightly more than was recovered: understated, the safe direction.\n *\n * A subscription sold before the pass-through existed is carried onto it by\n * the renewal re-price (AGL-2289) at its next paid invoice — but THAT invoice\n * was billed at the bare take, so its row's `feeCents` holds no pass-through\n * and the clamp reports its take as zero. One cycle per legacy subscription,\n * and the count beside the figure is how a reader sees how much of the book\n * that is.\n */\n\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { saleProcessingCostCents } from '@aglyn/aglyn/server'\nimport { PLATFORM_BRAND_NAME } from '@aglyn/aglyn/app-utils/platform-brand'\nimport { stripeIdIsTestMode } from '@aglyn/aglyn/app-utils/stripe-deployment-mode'\nimport {\n  groupRevenueAttribution,\n  type RevenueAttribution,\n  type RevenueSource,\n  type RevenueSourceAnswer,\n} from '@aglyn/aglyn/plugin-manager/plugin-revenue-sources'\n\n/** One `hosts/{hostId}/orders/{orderId}` row — a storefront sale. */\nexport interface CommerceOrderRowInput {\n  id: string\n  /** What the shopper paid, tax and shipping included. */\n  amountCents?: unknown\n  /**\n   * The Connect `application_fee_amount`: the platform's advertised take PLUS\n   * Stripe's processing cost passed through at cost (AGL-2152). NOT margin —\n   * see the module note.\n   */\n  feeCents?: unknown\n  /**\n   * Present ONLY on a storefront SUBSCRIPTION renewal, and it changes how\n   * `feeCents` must be read — see the module note.\n   */\n  subscriptionId?: unknown\n  /** Merchant refunds AND chargebacks both land here (`refund.ts`). */\n  refundedCents?: unknown\n  /**\n   * WHICH storefront the order belongs to — the attribution key.\n   *\n   * Orders live at `hosts/{hostId}/orders/{orderId}`, so this is lifted from\n   * the document PATH by the reader rather than read from a field. It costs no\n   * extra read and cannot disagree with where the document actually is.\n   */\n  hostId?: unknown\n  createdAt?: unknown\n  /**\n   * Whether Stripe moved real money, stamped from `event.livemode` by the\n   * webhook. Authoritative when present, and absent on every order written\n   * before that stamp shipped — which is why {@link isTestModeOrderRow} falls\n   * back to the id below rather than treating absence as an answer.\n   */\n  livemode?: unknown\n  /**\n   * The Checkout Session that produced the order. It carries its own mode\n   * (`cs_test_…`), which a subscription renewal's invoice id does not — so\n   * this is the fallback discriminator for rows predating `livemode`.\n   */\n  checkoutSessionId?: unknown\n}\n\nexport interface CommerceSettled {\n  transactionCount: number\n  /** Shopper spend across storefronts. Overwhelmingly the merchant's. */\n  grossCents: number\n  /** The whole `application_fee_amount` the platform collected. NOT margin. */\n  applicationFeeCents: number\n  /** Stripe's processing cost this recovered, at cost. Subtracted, never earnings. */\n  processingPassThroughCents: number\n  /** Application fee minus the pass-through: the advertised take. */\n  commissionCents: number\n  /** Take handed back with refunds and chargebacks, pro-rata. */\n  commissionRefundedCents: number\n  /** Take net of reversals. */\n  commissionNetCents: number\n  /**\n   * Storefront SUBSCRIPTION cycles in this period. Counted because a cycle\n   * billed before its subscription was re-priced onto the pass-through\n   * reports no take at all — see the module note.\n   */\n  subscriptionOrders: number\n  /**\n   * The sweep hit its ceiling, so every figure above is a LOWER BOUND and must\n   * not be quoted as a total. Narrow the period instead.\n   */\n  truncated: boolean\n}\n\n/** Cents from anything, defaulting to 0 rather than NaN. */\nfunction cents(value: unknown): number {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) ? Math.round(parsed) : 0\n}\n\n/**\n * Whether this order row was a test-mode rehearsal.\n *\n * A recorded `livemode` wins, and the session id's prefix is the fallback for\n * rows written before anything recorded it. An order with neither signal is\n * LIVE: a POS cash sale carries no Stripe session at all, and answering \"test\"\n * for anything unidentifiable would erase genuine revenue from the report.\n */\nfunction isTestModeOrderRow(row: CommerceOrderRowInput): boolean {\n  if (typeof row.livemode === 'boolean') return !row.livemode\n  return stripeIdIsTestMode(row.checkoutSessionId ?? row.id)\n}\n\nexport function commerceSettledSummary(\n  rows: readonly CommerceOrderRowInput[],\n  truncated = false,\n): CommerceSettled {\n  const out: CommerceSettled = {\n    transactionCount: 0,\n    grossCents: 0,\n    applicationFeeCents: 0,\n    processingPassThroughCents: 0,\n    commissionCents: 0,\n    commissionRefundedCents: 0,\n    commissionNetCents: 0,\n    subscriptionOrders: 0,\n    truncated: truncated === true,\n  }\n  for (const row of rows ?? []) {\n    // A REHEARSAL IS NOT REVENUE. A smoke-test checkout writes a real order\n    // document — Stripe never moved money for it, and its session id says so.\n    // Skipped ENTIRELY rather than counted at zero, because `transactionCount`\n    // is read as \"how many sales\", and a rehearsal is not one.\n    if (isTestModeOrderRow(row)) continue\n    const split = commerceOrderTake(row)\n    out.transactionCount += 1\n    out.grossCents += split.gross\n    out.applicationFeeCents += split.fee\n    if (split.isSubscriptionOrder) out.subscriptionOrders += 1\n    out.processingPassThroughCents += split.passThrough\n    out.commissionCents += split.take\n    out.commissionRefundedCents += split.takeRefunded\n    out.commissionNetCents += split.takeNet\n  }\n  return out\n}\n\n/**\n * One storefront order's take, in ONE place.\n *\n * Shared with the per-host attribution so a host table cannot sum to\n * something other than the storefront line above it.\n *\n * A zero-fee order contributes its gross and its count and nothing else —\n * there is no take to attribute, and inventing one from the gross would\n * report a merchant's money as the platform's.\n */\nexport function commerceOrderTake(row: CommerceOrderRowInput | null): {\n  gross: number\n  fee: number\n  isSubscriptionOrder: boolean\n  passThrough: number\n  take: number\n  takeRefunded: number\n  takeNet: number\n} {\n  const gross = cents(row?.amountCents)\n  const fee = Math.max(0, cents(row?.feeCents))\n  const isSubscriptionOrder =\n    typeof row?.subscriptionId === 'string' && row.subscriptionId.length > 0\n  if (fee <= 0) {\n    return {\n      gross,\n      fee,\n      isSubscriptionOrder,\n      passThrough: 0,\n      take: 0,\n      takeRefunded: 0,\n      takeNet: 0,\n    }\n  }\n  // Every fee bundles the recovery — a one-time sale's in cents, a\n  // subscription cycle's as a rate (AGL-2655). Clamped to the fee itself: the\n  // recomputed cost can exceed a fee charged under an older rate, and a\n  // negative take would subtract from another order's real margin.\n  const passThrough = Math.min(fee, saleProcessingCostCents(gross))\n  const take = fee - passThrough\n  const refunded = Math.min(gross, Math.max(0, cents(row?.refundedCents)))\n  const takeRefunded = gross > 0 ? Math.round((refunded * take) / gross) : 0\n  return {\n    gross,\n    fee,\n    isSubscriptionOrder,\n    passThrough,\n    take,\n    takeRefunded,\n    takeNet: take - takeRefunded,\n  }\n}\n\n/**\n * Storefront take by HOST.\n *\n * By host and not by org on purpose: one org can run several storefronts, and\n * \"which store earns\" is the question a per-org roll-up destroys.\n */\nexport function commerceHostAttribution(\n  rows: readonly CommerceOrderRowInput[],\n  limit = 100,\n): RevenueAttribution {\n  return groupRevenueAttribution(\n    (rows ?? []).map((row) => {\n      const split = commerceOrderTake(row)\n      return {\n        key: String(row?.hostId ?? ''),\n        detail: '',\n        gain: split.takeNet,\n        loss: split.takeRefunded,\n      }\n    }),\n    limit,\n    'Host not recorded',\n  )\n}\n\n/**\n * The storefront's answer for one period, from figures already folded. Pure,\n * so what the report prints can be proved from fixtures.\n *\n * `failed` is a sweep that could not run — a collection-group index this\n * deployment has not built answers FAILED_PRECONDITION — and it is reported as\n * a failure with figures of zero, never as a cap: \"we read part of it\" and \"we\n * read none of it\" have different remedies.\n */\nexport function commerceRevenueAnswer(read: {\n  settled: CommerceSettled\n  byHost: RevenueAttribution\n  failed: boolean\n}): RevenueSourceAnswer {\n  const brand = PLATFORM_BRAND_NAME\n  const { settled } = read\n  return {\n    id: 'commerce',\n    name: 'storefront orders',\n    earned: {\n      label: 'Storefront commission',\n      cents: Number(settled.commissionNetCents ?? 0),\n      note:\n        'The advertised take on merchant storefront sales, net of refunds — ' +\n        'with Stripe’s card processing removed. The platform fee charged on a ' +\n        'storefront sale bundles that processing cost and passes it through at ' +\n        'cost; it is a recovery, not earnings.',\n    },\n    grossToNet: [\n      {\n        label: 'Storefront sales (shopper gross)',\n        cents: settled.grossCents,\n        deduction: false,\n        note:\n          'The merchant’s. It transfers straight to their connected account ' +\n          'and is shown only for scale.',\n      },\n      {\n        label: 'Storefront platform fee collected',\n        cents: settled.applicationFeeCents,\n        deduction: false,\n        note: `Not all ${brand}’s — see the next line.`,\n      },\n      {\n        label: '— less card processing passed through at cost',\n        cents: settled.processingPassThroughCents,\n        deduction: true,\n        note: `Stripe’s. On a destination charge Stripe debits ${brand}’s balance for processing, and this half of the fee recovers exactly that. It is a recovery, not earnings, and reporting it as revenue would overstate every storefront sale.`,\n      },\n    ],\n    notes:\n      Number(settled.subscriptionOrders ?? 0) > 0\n        ? [\n            {\n              label: `${settled.subscriptionOrders} storefront subscription cycles — one billed before its re-price reports no take`,\n              tone: 'warning',\n            },\n          ]\n        : [],\n    attribution: [\n      {\n        id: 'byHost',\n        heading: 'Storefront take by host',\n        unit: 'Storefront',\n        countLabel: 'Orders',\n        empty: `No storefront order settled in this period. Note this is ${brand}'s take only — the shopper's spend is the merchant's money and is never counted here.`,\n        chartEmpty: 'No storefront earned a take in this period — nothing to plot yet.',\n        ...read.byHost,\n      },\n    ],\n    attributionNote:\n      \"Storefront figures above are the advertised take with Stripe's \" +\n      'processing cost already subtracted, on the basis stated in “Gross ' +\n      'versus net” below. Attribution is by host rather than by org because ' +\n      'one org can run several storefronts, and rolling them up destroys the ' +\n      'question.',\n    truncated: settled.truncated,\n    failure: read.failed\n      ? {\n          title: 'Storefront orders could not be read',\n          detail:\n            'The storefront commission below reads $0 because the query ' +\n            'failed, not because there were no sales. The sweep needs the ' +\n            'COLLECTION_GROUP index on orders.createdAtMs — check it is still ' +\n            'declared in the Firestore index config and actually deployed, ' +\n            'since indexes ship separately from the app.',\n        }\n      : null,\n    summary: settled,\n  }\n}\n\n/**\n * The storefront's source, registered on the console's API surface: the\n * staff revenue report awaits that surface before it asks.\n */\nexport const commerceRevenueSource: RevenueSource = {\n  async read(request) {\n    const firestore = firebaseAdmin.app().firestore()\n    // Storefront orders live per host (`hosts/{hostId}/orders`), so this is a\n    // collection-GROUP range — ranged on `createdAtMs`, the NUMBER, and not on\n    // the `createdAt` Timestamp beside it. A collection-group range needs a\n    // COLLECTION_GROUP-scoped single-field index — Firestore's automatic ones\n    // are COLLECTION scope only — and the index that is declared and deployed\n    // is on `createdAtMs` (AGL-1793). The `createdAt` form answers\n    // FAILED_PRECONDITION on every request, which is how the report once read\n    // $0 for every storefront.\n    let swept: {\n      docs: FirebaseFirestore.QueryDocumentSnapshot[]\n      truncated: boolean\n    } | null\n    try {\n      swept = await request.sweep<FirebaseFirestore.QueryDocumentSnapshot>(\n        firestore\n          .collectionGroup('orders')\n          .where('createdAtMs', '>=', request.start.getTime())\n          .where('createdAtMs', '<', request.end.getTime()),\n        'createdAtMs',\n      )\n    } catch {\n      swept = null\n    }\n    const rows: CommerceOrderRowInput[] = (swept?.docs ?? []).map((doc) => ({\n      id: doc.id,\n      // The storefront that earned the take is in the PATH.\n      hostId: doc.ref.parent.parent?.id ?? '',\n      ...(doc.data() as object),\n    }))\n    const settled = commerceSettledSummary(rows, swept?.truncated === true)\n    const byHost = commerceHostAttribution(rows, request.attributionLimit)\n    await request.nameRows(byHost.rows, {\n      collection: 'hosts',\n      nameField: 'displayName',\n      detailField: 'subdomain',\n    })\n    return commerceRevenueAnswer({ settled, byHost, failed: swept === null })\n  },\n}\n"],"names":["firebaseAdmin","saleProcessingCostCents","PLATFORM_BRAND_NAME","stripeIdIsTestMode","groupRevenueAttribution","cents","value","parsed","Number","isFinite","Math","round","isTestModeOrderRow","row","livemode","checkoutSessionId","id","commerceSettledSummary","rows","truncated","out","transactionCount","grossCents","applicationFeeCents","processingPassThroughCents","commissionCents","commissionRefundedCents","commissionNetCents","subscriptionOrders","split","commerceOrderTake","gross","fee","isSubscriptionOrder","passThrough","take","takeRefunded","takeNet","amountCents","max","feeCents","subscriptionId","length","min","refunded","refundedCents","commerceHostAttribution","limit","map","key","String","hostId","detail","gain","loss","commerceRevenueAnswer","read","settled","brand","name","earned","label","note","grossToNet","deduction","notes","tone","attribution","heading","unit","countLabel","empty","chartEmpty","byHost","attributionNote","failure","failed","title","summary","commerceRevenueSource","request","firestore","app","swept","sweep","collectionGroup","where","start","getTime","end","docs","doc","ref","parent","data","attributionLimit","nameRows","collection","nameField","detailField"],"mappings":"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"}

package/src/lib/server/supplier-outbox.js

@@ -16,6 +16,7 @@
  */ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { describeConfiguredUrlRefusal, fetchConfiguredPublicUrl, firebaseAdmin, flagLookalikeDomain, notifyHostManagers } from "@aglyn/tenant-data-admin";
 import { isDocumentId } from "@aglyn/tenant-data-admin/server/document-id";
+import { formatOrderNumber } from "../model/commerce-orders.js";
 import { createHmac } from "crypto";
 /**
  * The durable outbox for the dropship supplier notification (AGL-2473).
@@ -191,6 +192,18 @@ import { createHmac } from "crypto";
         })
     }).catch(()=>undefined);
 }
+/**
+ * The number the merchant knows an order by ("#1042"), for a notice about it
+ * (AGL-3432). The queued row carries only the document id, which is the Stripe
+ * session id and appears nowhere in the console. A read that fails falls back
+ * to the id, so the notice still goes out.
+ */ async function orderLabelFor(firestore, hostId, orderId) {
+    if (!isDocumentId(hostId) || !isDocumentId(orderId)) return orderId;
+    const number = await firestore.collection('hosts').doc(hostId).collection('orders').doc(orderId).get().then((snapshot)=>snapshot.get('number')).catch(()=>undefined);
+    return formatOrderNumber({
+        number: number != null ? number : undefined
+    }, orderId);
+}
 /**
  * One delivery attempt.
  *
@@ -291,10 +304,12 @@ import { createHmac } from "crypto";
     await stampOrderRoutingFailure(firestore, hostId, orderId, `Could not reach ${supplierName} after ${attempts} attempts ` + `(${reason}). This order was never routed.`);
     // The bell as well as the timeline: nobody opens an order they have no
     // reason to suspect.
+    // The consequence and the action (AGL-3432): the supplier has not been
+    // asked to ship this order, so the merchant has to.
     await notifyHostManagers(hostId, {
         type: 'content.order',
         title: `Order not routed to ${supplierName}`,
-        body: `Order ${orderId} could not be sent after ${attempts} attempts.`,
+        body: `Order ${await orderLabelFor(firestore, hostId, orderId)} on {site} ` + `never reached ${supplierName}: ${attempts} delivery attempts failed ` + `(${reason}). They have not been asked to ship it; send it to them ` + 'yourself or fulfill it by hand.',
         link: `/${hostId}/products`
     }).catch(()=>undefined);
     return 'dead-lettered';

package/src/lib/server/supplier-outbox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/supplier-outbox.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 {\n  describeConfiguredUrlRefusal,\n  fetchConfiguredPublicUrl,\n  firebaseAdmin,\n  flagLookalikeDomain,\n  notifyHostManagers,\n} from '@aglyn/tenant-data-admin'\nimport { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\nimport { createHmac } from 'crypto'\n\n/**\n * The durable outbox for the dropship supplier notification (AGL-2473).\n *\n * ## What was wrong\n *\n * `billing-webhook.ts` routed a paid dropship order inside\n * `void (async () => { … })()`, and the last thing that block did was\n * `await fetch(supplier.webhookUrl, …)` — an endpoint the MERCHANT typed into\n * a console field, on a host Aglyn neither runs nor monitors. Vercel freezes\n * the container the instant the response is written, so a supplier that is\n * slow, rate-limiting, or simply down is a supplier that is never told. The\n * order is paid, the buyer is thanked, the merchant sees \"Sent to supplier X\"\n * on the timeline, and NOTHING ANYWHERE records that the POST is still owed —\n * so no later pass can find it and no report can list it. It surfaces when the\n * customer asks where their parcel is.\n *\n * ## Why not just `await` it\n *\n * AGL-2161 fixed the other four fire-and-forget sites in that file and\n * deliberately left this one, because awaiting it is worse rather than better:\n * a supplier taking 30s pushes the handler past Stripe's delivery window,\n * Stripe redelivers, and the redelivery re-enters a fan-out whose only\n * idempotency is one `created` flag upstream. A silently dropped notification\n * would have been traded for a DUPLICATED order. `refund.ts` awaits its own\n * sibling and says so in a comment — correctly, because that sibling only\n * touches our own Firestore.\n *\n * So the line this module draws is not \"fast vs slow\" but **ours vs theirs**.\n * Everything the routing block does to Aglyn's own storage — the callback\n * token, the timeline entry, the supplier email through our own provider — is\n * now AWAITED on the response path, exactly like `refund.ts`. The one call to a\n * stranger's server becomes a row here, and the response no longer waits on it.\n *\n * ## The mechanism\n *\n * A Firestore-backed outbox drained by the plugin-job beat that already runs\n * the two commerce recovery passes (`server.ts`). No new infrastructure: the\n * beat is a Cloud Scheduler function POSTing the tenant runner route, and it\n * has carried bounded scans since AGL-2227.\n *\n *  * **Idempotent enqueue.** The id is `{hostId}__{orderId}__{supplierId}` and\n *    the write is `create()`, which REFUSES an existing document, so a\n *    redelivery cannot reset a retry part-way through its backoff. The AGL-498\n *    existence guard upstream already returns before this fan-out, but\n *    `reconcile-stock.ts` documents at length why one flag over a dozen effects\n *    is not something to lean on.\n *  * **Backoff.** 1m, 5m, 15m, 1h, 6h — about seven and a half hours of cover,\n *    which is a supplier's overnight deploy but not their week off.\n *  * **Dead letter.** After {@link SUPPLIER_DELIVERY_MAX_ATTEMPTS} the row is\n *    left as `failed`, the ORDER's own timeline is stamped, and host managers\n *    get a notification. The merchant reading the order they were paid for can\n *    see that it never reached the supplier — the thing the old code could not\n *    tell anyone, because it wrote nothing down.\n *\n * ## Two placement decisions, both deliberate\n *\n * **TOP-LEVEL, not `hosts/{hostId}/supplierDeliveries`.** The host catch-all in\n * the rules file is PERMISSIVE by default — a subcollection nobody names in its\n * three exclusion lists is one every site editor can write from the browser —\n * and the row carries the exact JSON body we sign and POST, so an editor-\n * writable row is an editor-chosen payload delivered under the supplier's own\n * shared secret. A top-level collection matches no rule in\n * `cloud/firebase-firestore.rules` at all and is therefore denied to every\n * client by default, the same footing as `platform/pluginJobs`. It also keeps\n * the drain on an ordinary collection query: a collection-GROUP `where` would\n * need a `COLLECTION_GROUP_ASC` fieldOverride, and AGL-1793 is the record of\n * both commerce crons being silently dead in production for want of exactly\n * that. Neither a rules deploy nor an index deploy is owed for this change.\n *\n * **A delivered row is DELETED, not stamped `delivered`.** The body holds the\n * buyer's email and name, and a top-level document is outside the\n * `hosts/{hostId}` recursive delete an erasure request runs. Retaining the\n * happy path would accumulate third-party PII in a place erasure does not\n * reach, to record something the order's own `routed` timeline entry already\n * says. Dead-lettered rows survive, because those are the ones a human has to\n * act on and the merchant has been told about them.\n */\n\n/** Top-level collection. Matches no rule, so no client may read or write it. */\nexport const SUPPLIER_DELIVERY_COLLECTION = 'supplierDeliveries'\n\n/** Attempts before a delivery is dead-lettered. */\nexport const SUPPLIER_DELIVERY_MAX_ATTEMPTS = 6\n\n/**\n * Delay before the next retry, indexed by attempts ALREADY made.\n *\n * The first entry is 60s and the job beat is also 60s, so a supplier that\n * blipped is retried on the next tick rather than a quarter of an hour later —\n * the difference between a parcel that ships today and one that does not.\n */\nexport const SUPPLIER_DELIVERY_BACKOFF_MS: readonly number[] = [\n  60_000,\n  300_000,\n  900_000,\n  3_600_000,\n  21_600_000,\n]\n\n/**\n * Per-attempt timeout. Nothing user-facing waits on this — it exists so one\n * hung supplier cannot hold the shared job beat open for the whole scan.\n */\nexport const SUPPLIER_DELIVERY_TIMEOUT_MS = 10_000\n\n/** Rows examined per drain. Bounded like every other scan on the beat. */\nexport const SUPPLIER_DELIVERY_SCAN_LIMIT = 100\n\nexport type SupplierDeliveryStatus = 'pending' | 'failed'\n\nexport interface SupplierDeliveryRecord {\n  status: SupplierDeliveryStatus\n  hostId: string\n  orderId: string\n  supplierId: string\n  supplierName: string\n  /** The endpoint as configured when the order was routed, for the record. */\n  url: string\n  /** The exact JSON the supplier is sent; signed at delivery time. */\n  body: string\n  attempts: number\n  nextAttemptAtMs: number\n  createdAtMs: number\n  lastError?: string\n  lastStatus?: number\n  failedAtMs?: number\n}\n\nexport interface SupplierDeliveryScanResult {\n  scanned: number\n  delivered: number\n  retried: number\n  deadLettered: number\n  /** Retired without delivery because the merchant removed the endpoint. */\n  cancelled: number\n  /** Left pending, with the retry budget intact, because the site is locked. */\n  skippedLocked: number\n}\n\n/** gRPC `Status.ALREADY_EXISTS` — what `create()` on a live path carries. */\nconst GRPC_ALREADY_EXISTS = 6\n\n/**\n * The delay owed after `attempts` failures, clamped to the last step.\n *\n * Clamped rather than extrapolated: the tail entry is already six hours, and a\n * dead letter is what comes after it, not a longer and longer silence.\n */\nexport function supplierDeliveryBackoffMs(attempts: number): number {\n  const last = SUPPLIER_DELIVERY_BACKOFF_MS.length - 1\n  return SUPPLIER_DELIVERY_BACKOFF_MS[\n    Math.max(0, Math.min(attempts - 1, last))\n  ]\n}\n\n/**\n * The outbox document id for one host/order/supplier triple.\n *\n * Deterministic, so `create()` is the idempotency. `__` rather than `:` or `/`:\n * a slash would make `.doc()` build a PATH instead of an id (AGL-1771), and the\n * separator has to survive a Stripe session id, which already contains `_`.\n * Firestore reserves ids fully matching `__.*__`; this never is, because all\n * three parts are non-empty and the id neither starts nor ends with `__`.\n */\nexport function supplierDeliveryId(\n  hostId: string,\n  orderId: string,\n  supplierId: string,\n): string {\n  return `${hostId}__${orderId}__${supplierId}`\n}\n\n/**\n * Records that a supplier POST is owed. One Firestore write, awaited.\n *\n * Returns `'queued'`, `'exists'` when a row for this triple is already in\n * flight, or `'skipped'`. NEVER THROWS: the caller is a paid order's fulfilment\n * path, and a queue that cannot be written must not take the receipt down with\n * it. The refusal is logged, which is strictly more than the old code managed\n * on the same failure.\n */\nexport async function enqueueSupplierDelivery(options: {\n  firestore: FirebaseFirestore.Firestore\n  hostId: string\n  orderId: string\n  supplierId: string\n  supplierName: string\n  url: string\n  body: string\n  now?: number\n}): Promise<'queued' | 'exists' | 'skipped'> {\n  const { firestore, hostId, orderId, supplierId, supplierName, url, body } =\n    options\n  const now = options.now ?? Date.now()\n  const id = supplierDeliveryId(hostId, orderId, supplierId)\n  if (!isDocumentId(id)) {\n    console.error('Supplier delivery not queued: unusable id', id)\n    return 'skipped'\n  }\n  const record: SupplierDeliveryRecord = {\n    status: 'pending',\n    hostId,\n    orderId,\n    supplierId,\n    supplierName,\n    url,\n    body,\n    attempts: 0,\n    // Due immediately: the next beat picks it up, at most a minute out.\n    nextAttemptAtMs: now,\n    createdAtMs: now,\n  }\n  try {\n    await firestore\n      .collection(SUPPLIER_DELIVERY_COLLECTION)\n      .doc(id)\n      .create(record as unknown as FirebaseFirestore.DocumentData)\n    return 'queued'\n  } catch (error) {\n    if ((error as { code?: number })?.code === GRPC_ALREADY_EXISTS) {\n      return 'exists'\n    }\n    console.error('Supplier delivery not queued', hostId, orderId, error)\n    return 'skipped'\n  }\n}\n\n/**\n * Stamps a routing failure on the order the merchant actually reads.\n *\n * `update()`, not a merge-set, for `recordRedemptionOrphan`'s reason: the order\n * exists — the delivery was queued from its own fulfilment — and a merge would\n * mint an order stub on the one path where it does not.\n */\nasync function stampOrderRoutingFailure(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  orderId: string,\n  detail: string,\n): Promise<void> {\n  if (!isDocumentId(hostId) || !isDocumentId(orderId)) return\n  await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('orders')\n    .doc(orderId)\n    .update({\n      timeline: firebaseAdmin.firestore.FieldValue.arrayUnion({\n        atMs: Date.now(),\n        event: 'routing-failed',\n        detail,\n      }),\n    })\n    .catch(() => undefined)\n}\n\ntype DeliveryOutcome = 'delivered' | 'retried' | 'dead-lettered' | 'cancelled'\n\n/**\n * One delivery attempt.\n *\n * Never throws: the drain is a shared beat, and one merchant's supplier must\n * not abort every other merchant's queue — the `process-restock.ts` lesson,\n * where a single poisoned row killed back-in-stock email platform-wide.\n */\nasync function attemptSupplierDelivery(\n  firestore: FirebaseFirestore.Firestore,\n  snapshot: FirebaseFirestore.QueryDocumentSnapshot,\n  now: number,\n): Promise<DeliveryOutcome> {\n  const data = snapshot.data() as SupplierDeliveryRecord\n  const hostId = String(data.hostId ?? '')\n  const attempts = Number(data.attempts ?? 0) + 1\n\n  const retire = async (): Promise<'cancelled'> => {\n    await snapshot.ref.delete().catch(() => undefined)\n    return 'cancelled'\n  }\n  if (!isDocumentId(hostId) || !isDocumentId(String(data.supplierId ?? ''))) {\n    return retire()\n  }\n\n  // The endpoint and the secret are read FRESH rather than frozen into the row:\n  // a merchant correcting a typo'd URL corrects what is already queued, and the\n  // supplier's shared secret is never copied into a second document.\n  const supplierSnapshot = await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('suppliers')\n    .doc(String(data.supplierId))\n    .get()\n    .catch(() => null)\n  // A read that FAILED is not a supplier that is gone. Retrying beats retiring\n  // a real delivery on a transient Firestore error — the `reconcile-stock.ts`\n  // rule that a failed read is not an absent marker.\n  if (!supplierSnapshot) {\n    return recordFailure(\n      firestore,\n      snapshot,\n      data,\n      attempts,\n      now,\n      'could not read the supplier record',\n      undefined,\n    )\n  }\n  const url = String(supplierSnapshot.get('webhookUrl') ?? '')\n  if (!url) {\n    // Deliberately NOT a dead letter: the merchant removed the endpoint (or the\n    // supplier), which is a decision rather than an outage. Alarming them about\n    // a delivery they cancelled is how an alert stops being read.\n    return retire()\n  }\n  const secret = String(supplierSnapshot.get('webhookSecret') ?? '')\n  const body = String(data.body ?? '')\n\n  let status: number\n  try {\n    // A merchant-typed address, called from the platform's servers: https\n    // only, public addresses only (pinned), never a lookalike, never a\n    // followed redirect (AGL-3363). A bare `fetch` here reached any address a\n    // merchant typed, the cloud metadata endpoint included.\n    const called = await fetchConfiguredPublicUrl(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        // NO EMPTY-KEY HMAC (AGL-2455). A signature computed under `''` is one\n        // any party can compute, and a supplier who also left their secret\n        // unset would verify it and believe the delivery was authenticated. An\n        // absent header fails their check closed; a forgeable one passes it.\n        ...(secret\n          ? {\n              'x-aglyn-signature': createHmac('sha256', secret)\n                .update(body)\n                .digest('hex'),\n            }\n          : {}),\n      },\n      body,\n      signal: AbortSignal.timeout(SUPPLIER_DELIVERY_TIMEOUT_MS),\n    })\n    if (called.ok === false) {\n      if (called.refusal === 'lookalike' && called.host) {\n        await flagLookalikeDomain({\n          kind: 'link',\n          hostId,\n          orgId: null,\n          domain: called.host,\n          where: 'a supplier order webhook',\n        })\n      }\n      return recordFailure(\n        firestore,\n        snapshot,\n        data,\n        attempts,\n        now,\n        `the supplier's webhook address was not called: ${describeConfiguredUrlRefusal(called.refusal)}`,\n        undefined,\n      )\n    }\n    status = called.status\n    if (!(status >= 200 && status < 300)) {\n      return recordFailure(\n        firestore,\n        snapshot,\n        data,\n        attempts,\n        now,\n        `supplier answered HTTP ${status}`,\n        status,\n      )\n    }\n  } catch (error) {\n    return recordFailure(\n      firestore,\n      snapshot,\n      data,\n      attempts,\n      now,\n      String((error as Error)?.message ?? error),\n      undefined,\n    )\n  }\n\n  // Delivered rows are DELETED rather than stamped — see the module note: the\n  // body holds the buyer's email and name, and a top-level document is outside\n  // the recursive delete an erasure request runs over `hosts/{hostId}`.\n  await snapshot.ref.delete().catch(() => undefined)\n  return 'delivered'\n}\n\n/** Books one failure: another retry, or the dead letter and its two alarms. */\nasync function recordFailure(\n  firestore: FirebaseFirestore.Firestore,\n  snapshot: FirebaseFirestore.QueryDocumentSnapshot,\n  data: SupplierDeliveryRecord,\n  attempts: number,\n  now: number,\n  reason: string,\n  status: number | undefined,\n): Promise<'retried' | 'dead-lettered'> {\n  const exhausted = attempts >= SUPPLIER_DELIVERY_MAX_ATTEMPTS\n  await snapshot.ref\n    .update({\n      status: exhausted ? 'failed' : 'pending',\n      attempts,\n      lastError: reason,\n      ...(status ? { lastStatus: status } : {}),\n      ...(exhausted\n        ? { failedAtMs: now }\n        : { nextAttemptAtMs: now + supplierDeliveryBackoffMs(attempts) }),\n    })\n    .catch(() => undefined)\n  if (!exhausted) return 'retried'\n\n  const hostId = String(data.hostId ?? '')\n  const orderId = String(data.orderId ?? '')\n  const supplierName = String(data.supplierName ?? '') || 'the supplier'\n  await stampOrderRoutingFailure(\n    firestore,\n    hostId,\n    orderId,\n    `Could not reach ${supplierName} after ${attempts} attempts ` +\n      `(${reason}). This order was never routed.`,\n  )\n  // The bell as well as the timeline: nobody opens an order they have no\n  // reason to suspect.\n  await notifyHostManagers(hostId, {\n    type: 'content.order',\n    title: `Order not routed to ${supplierName}`,\n    body: `Order ${orderId} could not be sent after ${attempts} attempts.`,\n    link: `/${hostId}/products`,\n  }).catch(() => undefined)\n  return 'dead-lettered'\n}\n\n/**\n * Drains the supplier outbox. Bounded, and safe to run twice.\n *\n * `nextAttemptAtMs` is filtered IN MEMORY rather than added to the query, which\n * would need a composite index for one field's worth of selectivity. The cost\n * is that a row still inside its backoff occupies one of the\n * {@link SUPPLIER_DELIVERY_SCAN_LIMIT} slots; with at most\n * {@link SUPPLIER_DELIVERY_MAX_ATTEMPTS} attempts per row the queue always\n * drains rather than growing a permanent head.\n */\nexport async function scanSupplierDeliveries(\n  /** The lockdown gate, injected by the caller (AGL-2495). Not optional. */\n  gate: PluginJobHostGate,\n  now: number = Date.now(),\n): Promise<SupplierDeliveryScanResult> {\n  const firestore = firebaseAdmin.app().firestore()\n  const pending = await firestore\n    .collection(SUPPLIER_DELIVERY_COLLECTION)\n    .where('status', '==', 'pending')\n    .limit(SUPPLIER_DELIVERY_SCAN_LIMIT)\n    .get()\n  const result: SupplierDeliveryScanResult = {\n    scanned: pending.size,\n    delivered: 0,\n    retried: 0,\n    deadLettered: 0,\n    cancelled: 0,\n    skippedLocked: 0,\n  }\n  for (const snapshot of pending.docs) {\n    const data = snapshot.data() as SupplierDeliveryRecord\n    // LOCKDOWN (AGL-2495). The row is a TOP-LEVEL document carrying its own\n    // `hostId` rather than living under `hosts/{hostId}`, so the host is read\n    // from the record instead of the parent chain — the one job of the six\n    // whose subject is not in its path.\n    //\n    // An outbound POST to the merchant's supplier is this platform acting in\n    // a suspended merchant's name against a third party, which is precisely\n    // what a takedown is for. The attempt also mutates the row (`attempts`,\n    // `nextAttemptAtMs`, or the dead-letter) and can notify the host's\n    // managers.\n    //\n    // SKIPPED, NOT DROPPED, and the strongest case of the six: the row stays\n    // `pending` with its `attempts` count untouched, so a long lock cannot\n    // burn a paid order's retry budget and dead-letter it for being locked.\n    // The queue drains from where it stood the minute the lock lifts.\n    if (await gate.isLocked(String(data?.hostId ?? ''))) {\n      result.skippedLocked += 1\n      continue\n    }\n    if (Number(data?.nextAttemptAtMs ?? 0) > now) continue\n    const outcome = await attemptSupplierDelivery(\n      firestore,\n      snapshot,\n      now,\n    ).catch((error) => {\n      console.error(\n        'Supplier delivery attempt failed',\n        snapshot.ref.path,\n        error,\n      )\n      return null\n    })\n    if (outcome === 'delivered') result.delivered += 1\n    else if (outcome === 'retried') result.retried += 1\n    else if (outcome === 'dead-lettered') result.deadLettered += 1\n    else if (outcome === 'cancelled') result.cancelled += 1\n  }\n  return result\n}\n"],"names":["describeConfiguredUrlRefusal","fetchConfiguredPublicUrl","firebaseAdmin","flagLookalikeDomain","notifyHostManagers","isDocumentId","createHmac","SUPPLIER_DELIVERY_COLLECTION","SUPPLIER_DELIVERY_MAX_ATTEMPTS","SUPPLIER_DELIVERY_BACKOFF_MS","SUPPLIER_DELIVERY_TIMEOUT_MS","SUPPLIER_DELIVERY_SCAN_LIMIT","GRPC_ALREADY_EXISTS","supplierDeliveryBackoffMs","attempts","last","length","Math","max","min","supplierDeliveryId","hostId","orderId","supplierId","enqueueSupplierDelivery","options","firestore","supplierName","url","body","now","Date","id","console","error","record","status","nextAttemptAtMs","createdAtMs","collection","doc","create","code","stampOrderRoutingFailure","detail","update","timeline","FieldValue","arrayUnion","atMs","event","catch","undefined","attemptSupplierDelivery","snapshot","data","supplierSnapshot","String","Number","retire","ref","delete","get","recordFailure","secret","called","method","headers","digest","signal","AbortSignal","timeout","ok","refusal","host","kind","orgId","domain","where","message","reason","exhausted","lastError","lastStatus","failedAtMs","type","title","link","scanSupplierDeliveries","gate","app","pending","limit","result","scanned","size","delivered","retried","deadLettered","cancelled","skippedLocked","docs","isLocked","outcome","path"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/supplier-outbox.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 {\n  describeConfiguredUrlRefusal,\n  fetchConfiguredPublicUrl,\n  firebaseAdmin,\n  flagLookalikeDomain,\n  notifyHostManagers,\n} from '@aglyn/tenant-data-admin'\nimport { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\nimport { formatOrderNumber } from '../model/commerce-orders'\nimport { createHmac } from 'crypto'\n\n/**\n * The durable outbox for the dropship supplier notification (AGL-2473).\n *\n * ## What was wrong\n *\n * `billing-webhook.ts` routed a paid dropship order inside\n * `void (async () => { … })()`, and the last thing that block did was\n * `await fetch(supplier.webhookUrl, …)` — an endpoint the MERCHANT typed into\n * a console field, on a host Aglyn neither runs nor monitors. Vercel freezes\n * the container the instant the response is written, so a supplier that is\n * slow, rate-limiting, or simply down is a supplier that is never told. The\n * order is paid, the buyer is thanked, the merchant sees \"Sent to supplier X\"\n * on the timeline, and NOTHING ANYWHERE records that the POST is still owed —\n * so no later pass can find it and no report can list it. It surfaces when the\n * customer asks where their parcel is.\n *\n * ## Why not just `await` it\n *\n * AGL-2161 fixed the other four fire-and-forget sites in that file and\n * deliberately left this one, because awaiting it is worse rather than better:\n * a supplier taking 30s pushes the handler past Stripe's delivery window,\n * Stripe redelivers, and the redelivery re-enters a fan-out whose only\n * idempotency is one `created` flag upstream. A silently dropped notification\n * would have been traded for a DUPLICATED order. `refund.ts` awaits its own\n * sibling and says so in a comment — correctly, because that sibling only\n * touches our own Firestore.\n *\n * So the line this module draws is not \"fast vs slow\" but **ours vs theirs**.\n * Everything the routing block does to Aglyn's own storage — the callback\n * token, the timeline entry, the supplier email through our own provider — is\n * now AWAITED on the response path, exactly like `refund.ts`. The one call to a\n * stranger's server becomes a row here, and the response no longer waits on it.\n *\n * ## The mechanism\n *\n * A Firestore-backed outbox drained by the plugin-job beat that already runs\n * the two commerce recovery passes (`server.ts`). No new infrastructure: the\n * beat is a Cloud Scheduler function POSTing the tenant runner route, and it\n * has carried bounded scans since AGL-2227.\n *\n *  * **Idempotent enqueue.** The id is `{hostId}__{orderId}__{supplierId}` and\n *    the write is `create()`, which REFUSES an existing document, so a\n *    redelivery cannot reset a retry part-way through its backoff. The AGL-498\n *    existence guard upstream already returns before this fan-out, but\n *    `reconcile-stock.ts` documents at length why one flag over a dozen effects\n *    is not something to lean on.\n *  * **Backoff.** 1m, 5m, 15m, 1h, 6h — about seven and a half hours of cover,\n *    which is a supplier's overnight deploy but not their week off.\n *  * **Dead letter.** After {@link SUPPLIER_DELIVERY_MAX_ATTEMPTS} the row is\n *    left as `failed`, the ORDER's own timeline is stamped, and host managers\n *    get a notification. The merchant reading the order they were paid for can\n *    see that it never reached the supplier — the thing the old code could not\n *    tell anyone, because it wrote nothing down.\n *\n * ## Two placement decisions, both deliberate\n *\n * **TOP-LEVEL, not `hosts/{hostId}/supplierDeliveries`.** The host catch-all in\n * the rules file is PERMISSIVE by default — a subcollection nobody names in its\n * three exclusion lists is one every site editor can write from the browser —\n * and the row carries the exact JSON body we sign and POST, so an editor-\n * writable row is an editor-chosen payload delivered under the supplier's own\n * shared secret. A top-level collection matches no rule in\n * `cloud/firebase-firestore.rules` at all and is therefore denied to every\n * client by default, the same footing as `platform/pluginJobs`. It also keeps\n * the drain on an ordinary collection query: a collection-GROUP `where` would\n * need a `COLLECTION_GROUP_ASC` fieldOverride, and AGL-1793 is the record of\n * both commerce crons being silently dead in production for want of exactly\n * that. Neither a rules deploy nor an index deploy is owed for this change.\n *\n * **A delivered row is DELETED, not stamped `delivered`.** The body holds the\n * buyer's email and name, and a top-level document is outside the\n * `hosts/{hostId}` recursive delete an erasure request runs. Retaining the\n * happy path would accumulate third-party PII in a place erasure does not\n * reach, to record something the order's own `routed` timeline entry already\n * says. Dead-lettered rows survive, because those are the ones a human has to\n * act on and the merchant has been told about them.\n */\n\n/** Top-level collection. Matches no rule, so no client may read or write it. */\nexport const SUPPLIER_DELIVERY_COLLECTION = 'supplierDeliveries'\n\n/** Attempts before a delivery is dead-lettered. */\nexport const SUPPLIER_DELIVERY_MAX_ATTEMPTS = 6\n\n/**\n * Delay before the next retry, indexed by attempts ALREADY made.\n *\n * The first entry is 60s and the job beat is also 60s, so a supplier that\n * blipped is retried on the next tick rather than a quarter of an hour later —\n * the difference between a parcel that ships today and one that does not.\n */\nexport const SUPPLIER_DELIVERY_BACKOFF_MS: readonly number[] = [\n  60_000,\n  300_000,\n  900_000,\n  3_600_000,\n  21_600_000,\n]\n\n/**\n * Per-attempt timeout. Nothing user-facing waits on this — it exists so one\n * hung supplier cannot hold the shared job beat open for the whole scan.\n */\nexport const SUPPLIER_DELIVERY_TIMEOUT_MS = 10_000\n\n/** Rows examined per drain. Bounded like every other scan on the beat. */\nexport const SUPPLIER_DELIVERY_SCAN_LIMIT = 100\n\nexport type SupplierDeliveryStatus = 'pending' | 'failed'\n\nexport interface SupplierDeliveryRecord {\n  status: SupplierDeliveryStatus\n  hostId: string\n  orderId: string\n  supplierId: string\n  supplierName: string\n  /** The endpoint as configured when the order was routed, for the record. */\n  url: string\n  /** The exact JSON the supplier is sent; signed at delivery time. */\n  body: string\n  attempts: number\n  nextAttemptAtMs: number\n  createdAtMs: number\n  lastError?: string\n  lastStatus?: number\n  failedAtMs?: number\n}\n\nexport interface SupplierDeliveryScanResult {\n  scanned: number\n  delivered: number\n  retried: number\n  deadLettered: number\n  /** Retired without delivery because the merchant removed the endpoint. */\n  cancelled: number\n  /** Left pending, with the retry budget intact, because the site is locked. */\n  skippedLocked: number\n}\n\n/** gRPC `Status.ALREADY_EXISTS` — what `create()` on a live path carries. */\nconst GRPC_ALREADY_EXISTS = 6\n\n/**\n * The delay owed after `attempts` failures, clamped to the last step.\n *\n * Clamped rather than extrapolated: the tail entry is already six hours, and a\n * dead letter is what comes after it, not a longer and longer silence.\n */\nexport function supplierDeliveryBackoffMs(attempts: number): number {\n  const last = SUPPLIER_DELIVERY_BACKOFF_MS.length - 1\n  return SUPPLIER_DELIVERY_BACKOFF_MS[\n    Math.max(0, Math.min(attempts - 1, last))\n  ]\n}\n\n/**\n * The outbox document id for one host/order/supplier triple.\n *\n * Deterministic, so `create()` is the idempotency. `__` rather than `:` or `/`:\n * a slash would make `.doc()` build a PATH instead of an id (AGL-1771), and the\n * separator has to survive a Stripe session id, which already contains `_`.\n * Firestore reserves ids fully matching `__.*__`; this never is, because all\n * three parts are non-empty and the id neither starts nor ends with `__`.\n */\nexport function supplierDeliveryId(\n  hostId: string,\n  orderId: string,\n  supplierId: string,\n): string {\n  return `${hostId}__${orderId}__${supplierId}`\n}\n\n/**\n * Records that a supplier POST is owed. One Firestore write, awaited.\n *\n * Returns `'queued'`, `'exists'` when a row for this triple is already in\n * flight, or `'skipped'`. NEVER THROWS: the caller is a paid order's fulfilment\n * path, and a queue that cannot be written must not take the receipt down with\n * it. The refusal is logged, which is strictly more than the old code managed\n * on the same failure.\n */\nexport async function enqueueSupplierDelivery(options: {\n  firestore: FirebaseFirestore.Firestore\n  hostId: string\n  orderId: string\n  supplierId: string\n  supplierName: string\n  url: string\n  body: string\n  now?: number\n}): Promise<'queued' | 'exists' | 'skipped'> {\n  const { firestore, hostId, orderId, supplierId, supplierName, url, body } =\n    options\n  const now = options.now ?? Date.now()\n  const id = supplierDeliveryId(hostId, orderId, supplierId)\n  if (!isDocumentId(id)) {\n    console.error('Supplier delivery not queued: unusable id', id)\n    return 'skipped'\n  }\n  const record: SupplierDeliveryRecord = {\n    status: 'pending',\n    hostId,\n    orderId,\n    supplierId,\n    supplierName,\n    url,\n    body,\n    attempts: 0,\n    // Due immediately: the next beat picks it up, at most a minute out.\n    nextAttemptAtMs: now,\n    createdAtMs: now,\n  }\n  try {\n    await firestore\n      .collection(SUPPLIER_DELIVERY_COLLECTION)\n      .doc(id)\n      .create(record as unknown as FirebaseFirestore.DocumentData)\n    return 'queued'\n  } catch (error) {\n    if ((error as { code?: number })?.code === GRPC_ALREADY_EXISTS) {\n      return 'exists'\n    }\n    console.error('Supplier delivery not queued', hostId, orderId, error)\n    return 'skipped'\n  }\n}\n\n/**\n * Stamps a routing failure on the order the merchant actually reads.\n *\n * `update()`, not a merge-set, for `recordRedemptionOrphan`'s reason: the order\n * exists — the delivery was queued from its own fulfilment — and a merge would\n * mint an order stub on the one path where it does not.\n */\nasync function stampOrderRoutingFailure(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  orderId: string,\n  detail: string,\n): Promise<void> {\n  if (!isDocumentId(hostId) || !isDocumentId(orderId)) return\n  await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('orders')\n    .doc(orderId)\n    .update({\n      timeline: firebaseAdmin.firestore.FieldValue.arrayUnion({\n        atMs: Date.now(),\n        event: 'routing-failed',\n        detail,\n      }),\n    })\n    .catch(() => undefined)\n}\n\n/**\n * The number the merchant knows an order by (\"#1042\"), for a notice about it\n * (AGL-3432). The queued row carries only the document id, which is the Stripe\n * session id and appears nowhere in the console. A read that fails falls back\n * to the id, so the notice still goes out.\n */\nasync function orderLabelFor(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  orderId: string,\n): Promise<string> {\n  if (!isDocumentId(hostId) || !isDocumentId(orderId)) return orderId\n  const number = await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('orders')\n    .doc(orderId)\n    .get()\n    .then((snapshot) => snapshot.get('number') as number | undefined)\n    .catch(() => undefined)\n  return formatOrderNumber({ number: number ?? undefined }, orderId)\n}\n\ntype DeliveryOutcome = 'delivered' | 'retried' | 'dead-lettered' | 'cancelled'\n\n/**\n * One delivery attempt.\n *\n * Never throws: the drain is a shared beat, and one merchant's supplier must\n * not abort every other merchant's queue — the `process-restock.ts` lesson,\n * where a single poisoned row killed back-in-stock email platform-wide.\n */\nasync function attemptSupplierDelivery(\n  firestore: FirebaseFirestore.Firestore,\n  snapshot: FirebaseFirestore.QueryDocumentSnapshot,\n  now: number,\n): Promise<DeliveryOutcome> {\n  const data = snapshot.data() as SupplierDeliveryRecord\n  const hostId = String(data.hostId ?? '')\n  const attempts = Number(data.attempts ?? 0) + 1\n\n  const retire = async (): Promise<'cancelled'> => {\n    await snapshot.ref.delete().catch(() => undefined)\n    return 'cancelled'\n  }\n  if (!isDocumentId(hostId) || !isDocumentId(String(data.supplierId ?? ''))) {\n    return retire()\n  }\n\n  // The endpoint and the secret are read FRESH rather than frozen into the row:\n  // a merchant correcting a typo'd URL corrects what is already queued, and the\n  // supplier's shared secret is never copied into a second document.\n  const supplierSnapshot = await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('suppliers')\n    .doc(String(data.supplierId))\n    .get()\n    .catch(() => null)\n  // A read that FAILED is not a supplier that is gone. Retrying beats retiring\n  // a real delivery on a transient Firestore error — the `reconcile-stock.ts`\n  // rule that a failed read is not an absent marker.\n  if (!supplierSnapshot) {\n    return recordFailure(\n      firestore,\n      snapshot,\n      data,\n      attempts,\n      now,\n      'could not read the supplier record',\n      undefined,\n    )\n  }\n  const url = String(supplierSnapshot.get('webhookUrl') ?? '')\n  if (!url) {\n    // Deliberately NOT a dead letter: the merchant removed the endpoint (or the\n    // supplier), which is a decision rather than an outage. Alarming them about\n    // a delivery they cancelled is how an alert stops being read.\n    return retire()\n  }\n  const secret = String(supplierSnapshot.get('webhookSecret') ?? '')\n  const body = String(data.body ?? '')\n\n  let status: number\n  try {\n    // A merchant-typed address, called from the platform's servers: https\n    // only, public addresses only (pinned), never a lookalike, never a\n    // followed redirect (AGL-3363). A bare `fetch` here reached any address a\n    // merchant typed, the cloud metadata endpoint included.\n    const called = await fetchConfiguredPublicUrl(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        // NO EMPTY-KEY HMAC (AGL-2455). A signature computed under `''` is one\n        // any party can compute, and a supplier who also left their secret\n        // unset would verify it and believe the delivery was authenticated. An\n        // absent header fails their check closed; a forgeable one passes it.\n        ...(secret\n          ? {\n              'x-aglyn-signature': createHmac('sha256', secret)\n                .update(body)\n                .digest('hex'),\n            }\n          : {}),\n      },\n      body,\n      signal: AbortSignal.timeout(SUPPLIER_DELIVERY_TIMEOUT_MS),\n    })\n    if (called.ok === false) {\n      if (called.refusal === 'lookalike' && called.host) {\n        await flagLookalikeDomain({\n          kind: 'link',\n          hostId,\n          orgId: null,\n          domain: called.host,\n          where: 'a supplier order webhook',\n        })\n      }\n      return recordFailure(\n        firestore,\n        snapshot,\n        data,\n        attempts,\n        now,\n        `the supplier's webhook address was not called: ${describeConfiguredUrlRefusal(called.refusal)}`,\n        undefined,\n      )\n    }\n    status = called.status\n    if (!(status >= 200 && status < 300)) {\n      return recordFailure(\n        firestore,\n        snapshot,\n        data,\n        attempts,\n        now,\n        `supplier answered HTTP ${status}`,\n        status,\n      )\n    }\n  } catch (error) {\n    return recordFailure(\n      firestore,\n      snapshot,\n      data,\n      attempts,\n      now,\n      String((error as Error)?.message ?? error),\n      undefined,\n    )\n  }\n\n  // Delivered rows are DELETED rather than stamped — see the module note: the\n  // body holds the buyer's email and name, and a top-level document is outside\n  // the recursive delete an erasure request runs over `hosts/{hostId}`.\n  await snapshot.ref.delete().catch(() => undefined)\n  return 'delivered'\n}\n\n/** Books one failure: another retry, or the dead letter and its two alarms. */\nasync function recordFailure(\n  firestore: FirebaseFirestore.Firestore,\n  snapshot: FirebaseFirestore.QueryDocumentSnapshot,\n  data: SupplierDeliveryRecord,\n  attempts: number,\n  now: number,\n  reason: string,\n  status: number | undefined,\n): Promise<'retried' | 'dead-lettered'> {\n  const exhausted = attempts >= SUPPLIER_DELIVERY_MAX_ATTEMPTS\n  await snapshot.ref\n    .update({\n      status: exhausted ? 'failed' : 'pending',\n      attempts,\n      lastError: reason,\n      ...(status ? { lastStatus: status } : {}),\n      ...(exhausted\n        ? { failedAtMs: now }\n        : { nextAttemptAtMs: now + supplierDeliveryBackoffMs(attempts) }),\n    })\n    .catch(() => undefined)\n  if (!exhausted) return 'retried'\n\n  const hostId = String(data.hostId ?? '')\n  const orderId = String(data.orderId ?? '')\n  const supplierName = String(data.supplierName ?? '') || 'the supplier'\n  await stampOrderRoutingFailure(\n    firestore,\n    hostId,\n    orderId,\n    `Could not reach ${supplierName} after ${attempts} attempts ` +\n      `(${reason}). This order was never routed.`,\n  )\n  // The bell as well as the timeline: nobody opens an order they have no\n  // reason to suspect.\n  // The consequence and the action (AGL-3432): the supplier has not been\n  // asked to ship this order, so the merchant has to.\n  await notifyHostManagers(hostId, {\n    type: 'content.order',\n    title: `Order not routed to ${supplierName}`,\n    body:\n      `Order ${await orderLabelFor(firestore, hostId, orderId)} on {site} ` +\n      `never reached ${supplierName}: ${attempts} delivery attempts failed ` +\n      `(${reason}). They have not been asked to ship it; send it to them ` +\n      'yourself or fulfill it by hand.',\n    link: `/${hostId}/products`,\n  }).catch(() => undefined)\n  return 'dead-lettered'\n}\n\n/**\n * Drains the supplier outbox. Bounded, and safe to run twice.\n *\n * `nextAttemptAtMs` is filtered IN MEMORY rather than added to the query, which\n * would need a composite index for one field's worth of selectivity. The cost\n * is that a row still inside its backoff occupies one of the\n * {@link SUPPLIER_DELIVERY_SCAN_LIMIT} slots; with at most\n * {@link SUPPLIER_DELIVERY_MAX_ATTEMPTS} attempts per row the queue always\n * drains rather than growing a permanent head.\n */\nexport async function scanSupplierDeliveries(\n  /** The lockdown gate, injected by the caller (AGL-2495). Not optional. */\n  gate: PluginJobHostGate,\n  now: number = Date.now(),\n): Promise<SupplierDeliveryScanResult> {\n  const firestore = firebaseAdmin.app().firestore()\n  const pending = await firestore\n    .collection(SUPPLIER_DELIVERY_COLLECTION)\n    .where('status', '==', 'pending')\n    .limit(SUPPLIER_DELIVERY_SCAN_LIMIT)\n    .get()\n  const result: SupplierDeliveryScanResult = {\n    scanned: pending.size,\n    delivered: 0,\n    retried: 0,\n    deadLettered: 0,\n    cancelled: 0,\n    skippedLocked: 0,\n  }\n  for (const snapshot of pending.docs) {\n    const data = snapshot.data() as SupplierDeliveryRecord\n    // LOCKDOWN (AGL-2495). The row is a TOP-LEVEL document carrying its own\n    // `hostId` rather than living under `hosts/{hostId}`, so the host is read\n    // from the record instead of the parent chain — the one job of the six\n    // whose subject is not in its path.\n    //\n    // An outbound POST to the merchant's supplier is this platform acting in\n    // a suspended merchant's name against a third party, which is precisely\n    // what a takedown is for. The attempt also mutates the row (`attempts`,\n    // `nextAttemptAtMs`, or the dead-letter) and can notify the host's\n    // managers.\n    //\n    // SKIPPED, NOT DROPPED, and the strongest case of the six: the row stays\n    // `pending` with its `attempts` count untouched, so a long lock cannot\n    // burn a paid order's retry budget and dead-letter it for being locked.\n    // The queue drains from where it stood the minute the lock lifts.\n    if (await gate.isLocked(String(data?.hostId ?? ''))) {\n      result.skippedLocked += 1\n      continue\n    }\n    if (Number(data?.nextAttemptAtMs ?? 0) > now) continue\n    const outcome = await attemptSupplierDelivery(\n      firestore,\n      snapshot,\n      now,\n    ).catch((error) => {\n      console.error(\n        'Supplier delivery attempt failed',\n        snapshot.ref.path,\n        error,\n      )\n      return null\n    })\n    if (outcome === 'delivered') result.delivered += 1\n    else if (outcome === 'retried') result.retried += 1\n    else if (outcome === 'dead-lettered') result.deadLettered += 1\n    else if (outcome === 'cancelled') result.cancelled += 1\n  }\n  return result\n}\n"],"names":["describeConfiguredUrlRefusal","fetchConfiguredPublicUrl","firebaseAdmin","flagLookalikeDomain","notifyHostManagers","isDocumentId","formatOrderNumber","createHmac","SUPPLIER_DELIVERY_COLLECTION","SUPPLIER_DELIVERY_MAX_ATTEMPTS","SUPPLIER_DELIVERY_BACKOFF_MS","SUPPLIER_DELIVERY_TIMEOUT_MS","SUPPLIER_DELIVERY_SCAN_LIMIT","GRPC_ALREADY_EXISTS","supplierDeliveryBackoffMs","attempts","last","length","Math","max","min","supplierDeliveryId","hostId","orderId","supplierId","enqueueSupplierDelivery","options","firestore","supplierName","url","body","now","Date","id","console","error","record","status","nextAttemptAtMs","createdAtMs","collection","doc","create","code","stampOrderRoutingFailure","detail","update","timeline","FieldValue","arrayUnion","atMs","event","catch","undefined","orderLabelFor","number","get","then","snapshot","attemptSupplierDelivery","data","supplierSnapshot","String","Number","retire","ref","delete","recordFailure","secret","called","method","headers","digest","signal","AbortSignal","timeout","ok","refusal","host","kind","orgId","domain","where","message","reason","exhausted","lastError","lastStatus","failedAtMs","type","title","link","scanSupplierDeliveries","gate","app","pending","limit","result","scanned","size","delivered","retried","deadLettered","cancelled","skippedLocked","docs","isLocked","outcome","path"],"mappings":"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"}

package/src/lib/server/supplier-update.js

@@ -106,7 +106,7 @@ import { tokenSigningSecret } from "./download.js";
         });
     }
     try {
-        var _outcome_remaining;
+        var _outcome_remaining, _ref;
         const firestore = firebaseAdmin.app().firestore();
         const orderRef = firestore.collection('hosts').doc(hostId).collection('orders').doc(orderId);
         // A GET NEVER MOVES THE ORDER (AGL-2268). The supplier email carries this
@@ -120,7 +120,11 @@ import { tokenSigningSecret } from "./download.js";
         if (req.method === 'GET') {
             res.setHeader('Content-Type', 'text/html');
             const field = (name, value)=>`<input type="hidden" name="${name}" value="${escapeHtml(value)}">`;
-            return res.status(200).send('<h3>Confirm this shipment</h3>' + '<p>Press the button to record it against the order.</p>' + '<form method="POST">' + field('hostId', hostId) + field('orderId', orderId) + field('token', token) + field('carrier', carrier) + field('trackingNumber', trackingNumber) + '<button type="submit">Mark as shipped</button>' + '</form>');
+            // The carrier and the number are FIELDS the supplier fills in
+            // (AGL-3432), so the emailed link needs no placeholders for them to
+            // edit in the URL. A value a link does carry arrives filled in.
+            const input = (name, label, value)=>`<p><label>${label}<br>` + `<input type="text" name="${name}" value="${escapeHtml(value)}"></label></p>`;
+            return res.status(200).send('<h3>Record this shipment</h3>' + '<p>Enter the carrier and tracking number, then press the button ' + 'to record it against the order.</p>' + '<form method="POST">' + field('hostId', hostId) + field('orderId', orderId) + field('token', token) + input('carrier', 'Carrier', carrier) + input('trackingNumber', 'Tracking number', trackingNumber) + '<button type="submit">Mark as shipped</button>' + '</form>');
         }
         // THE READ, THE TRANSITION CHECK AND THE WRITE ARE ONE ACT (AGL-2268).
         // They used to be a plain `get()`, a check, and a `set(…, {merge:true})`,
@@ -258,7 +262,8 @@ import { tokenSigningSecret } from "./download.js";
                 },
                 order,
                 nextStatus,
-                remaining
+                remaining,
+                supplierId: postingSupplier
             };
         });
         if (outcome.status !== 200) {
@@ -269,14 +274,19 @@ import { tokenSigningSecret } from "./download.js";
         // as done, which is the same misreport the status literal made — the
         // merchant would stop watching an order that is two thirds unshipped.
         const outstanding = Number((_outcome_remaining = outcome.remaining) != null ? _outcome_remaining : 0);
-        void notifyHostManagers(hostId, _extends({
+        const orderLabel = CommerceModel.formatOrderNumber(outcome.order, orderId);
+        // Which supplier, which order, where, and the tracking (AGL-3432).
+        const supplierId = outcome.supplierId;
+        const supplierName = supplierId ? String((_ref = await firestore.collection('hosts').doc(hostId).collection('suppliers').doc(supplierId).get().then((snapshot)=>snapshot.get('name')).catch(()=>'')) != null ? _ref : '').trim() : '';
+        void notifyHostManagers(hostId, {
             type: 'content.order',
-            title: `Supplier shipped ${CommerceModel.formatOrderNumber(outcome.order, orderId)}${outstanding > 0 ? ` — ${outstanding} line${outstanding === 1 ? '' : 's'} still to ship` : ''}`
-        }, trackingNumber ? {
-            body: `${carrier} ${trackingNumber}`
-        } : {}, {
+            title: `Supplier shipped ${orderLabel}${outstanding > 0 ? ` — ${outstanding} line${outstanding === 1 ? '' : 's'} still to ship` : ''}`,
+            body: `${supplierName || 'Your supplier'} shipped their part of order ` + `${orderLabel} on {site}.` + (trackingNumber ? ` Tracking: ${[
+                carrier,
+                trackingNumber
+            ].filter(Boolean).join(' ')}.` : ' No tracking number was given.') + (outstanding > 0 ? ` ${outstanding} line${outstanding === 1 ? ' is' : 's are'} still to ship.` : ''),
             link: `/${hostId}/products`
-        }));
+        });
         return res.status(200).json(outcome.body);
     } catch (error) {
         console.error(error);