@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/subscription-portal.js

@@ -0,0 +1,91 @@
+/**
+ * @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 { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { requireActiveMember } from "./membership.js";
+/**
+ * Subscriber self-service (AGL-303): opens the Stripe Billing Portal for
+ * the signed-in member's storefront subscription (cancel, switch
+ * payment method). Member-gated; the portal customer is matched by the
+ * member's email through the recorded subscription doc.
+ */ export const subscriptionPortalHandler = async (req, res)=>{
+    var _ref;
+    var _req_body;
+    if (req.method !== 'POST') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    if (!process.env.STRIPE_SECRET_KEY) {
+        return res.status(501).json({
+            error: 'Billing is not configured.'
+        });
+    }
+    const hostId = String((_ref = (_req_body = req.body) == null ? void 0 : _req_body.hostId) != null ? _ref : '');
+    if (!hostId) return res.status(400).json({
+        error: 'Missing hostId'
+    });
+    try {
+        var _auth_member_get, _req_headers_referer;
+        var _subscriptions_docs_;
+        // Suspension gate (AGL-550): suspended members (AGL-546) cannot
+        // open the billing portal — 403'd with the session cookie cleared.
+        const auth = await requireActiveMember(req, res, hostId);
+        if (!auth) return;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const email = String((_auth_member_get = auth.member.get('email')) != null ? _auth_member_get : '');
+        if (!email) return res.status(401).json({
+            error: 'Not signed in'
+        });
+        const subscriptions = await hostRef.collection('subscriptions').where('customerEmail', '==', email).limit(1).get();
+        const customerId = (_subscriptions_docs_ = subscriptions.docs[0]) == null ? void 0 : _subscriptions_docs_.get('stripeCustomerId');
+        if (!customerId) {
+            return res.status(404).json({
+                error: 'No subscription found'
+            });
+        }
+        const referer = String((_req_headers_referer = req.headers.referer) != null ? _req_headers_referer : '');
+        const origin = `https://${req.headers.host}`;
+        const response = await fetch('https://api.stripe.com/v1/billing_portal/sessions', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: new URLSearchParams({
+                customer: String(customerId),
+                return_url: referer.startsWith('http') ? referer : origin
+            }).toString()
+        });
+        const session = await response.json();
+        if (!response.ok || !session.url) {
+            console.error('Portal error', session == null ? void 0 : session.error);
+            return res.status(502).json({
+                error: 'Portal unavailable'
+            });
+        }
+        return res.status(200).json({
+            url: session.url
+        });
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Portal unavailable'
+        });
+    }
+};
+
+//# sourceMappingURL=subscription-portal.js.map

package/src/lib/server/subscription-portal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/subscription-portal.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 { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { requireActiveMember } from './membership'\n\n/**\n * Subscriber self-service (AGL-303): opens the Stripe Billing Portal for\n * the signed-in member's storefront subscription (cancel, switch\n * payment method). Member-gated; the portal customer is matched by the\n * member's email through the recorded subscription doc.\n */\nexport const subscriptionPortalHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  if (!process.env.STRIPE_SECRET_KEY) {\n    return res.status(501).json({ error: 'Billing is not configured.' })\n  }\n  const hostId = String(req.body?.hostId ?? '')\n  if (!hostId) return res.status(400).json({ error: 'Missing hostId' })\n\n  try {\n    // Suspension gate (AGL-550): suspended members (AGL-546) cannot\n    // open the billing portal — 403'd with the session cookie cleared.\n    const auth = await requireActiveMember(req, res, hostId)\n    if (!auth) return\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const email = String(auth.member.get('email') ?? '')\n    if (!email) return res.status(401).json({ error: 'Not signed in' })\n    const subscriptions = await hostRef\n      .collection('subscriptions')\n      .where('customerEmail', '==', email)\n      .limit(1)\n      .get()\n    const customerId = subscriptions.docs[0]?.get('stripeCustomerId')\n    if (!customerId) {\n      return res.status(404).json({ error: 'No subscription found' })\n    }\n    const referer = String(req.headers.referer ?? '')\n    const origin = `https://${req.headers.host}`\n    const response = await fetch(\n      'https://api.stripe.com/v1/billing_portal/sessions',\n      {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,\n          'Content-Type': 'application/x-www-form-urlencoded',\n        },\n        body: new URLSearchParams({\n          customer: String(customerId),\n          return_url: referer.startsWith('http') ? referer : origin,\n        }).toString(),\n      },\n    )\n    const session = await response.json()\n    if (!response.ok || !session.url) {\n      console.error('Portal error', session?.error)\n      return res.status(502).json({ error: 'Portal unavailable' })\n    }\n    return res.status(200).json({ url: session.url })\n  } catch (error) {\n    console.error(error)\n    return res.status(500).json({ error: 'Portal unavailable' })\n  }\n}\n"],"names":["firebaseAdmin","requireActiveMember","subscriptionPortalHandler","req","res","method","status","json","error","process","env","STRIPE_SECRET_KEY","hostId","String","body","auth","subscriptions","firestore","app","hostRef","collection","doc","email","member","get","where","limit","customerId","docs","referer","headers","origin","host","response","fetch","Authorization","URLSearchParams","customer","return_url","startsWith","toString","session","ok","url","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,aAAa,QAAQ,2BAA0B;AACxD,SAASC,mBAAmB,QAAQ,kBAAc;AAElD;;;;;CAKC,GACD,OAAO,MAAMC,4BAA8C,OAAOC,KAAKC;;QAO/CD;IANtB,IAAIA,IAAIE,MAAM,KAAK,QAAQ;QACzB,OAAOD,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAqB;IAC5D;IACA,IAAI,CAACC,QAAQC,GAAG,CAACC,iBAAiB,EAAE;QAClC,OAAOP,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAA6B;IACpE;IACA,MAAMI,SAASC,gBAAOV,YAAAA,IAAIW,IAAI,qBAARX,UAAUS,MAAM,mBAAI;IAC1C,IAAI,CAACA,QAAQ,OAAOR,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;QAAEC,OAAO;IAAiB;IAEnE,IAAI;YAOmBO,kBAWEZ;YAJJa;QAbnB,gEAAgE;QAChE,mEAAmE;QACnE,MAAMD,OAAO,MAAMd,oBAAoBE,KAAKC,KAAKQ;QACjD,IAAI,CAACG,MAAM;QACX,MAAME,YAAYjB,cAAckB,GAAG,GAAGD,SAAS;QAC/C,MAAME,UAAUF,UAAUG,UAAU,CAAC,SAASC,GAAG,CAACT;QAClD,MAAMU,QAAQT,QAAOE,mBAAAA,KAAKQ,MAAM,CAACC,GAAG,CAAC,oBAAhBT,mBAA4B;QACjD,IAAI,CAACO,OAAO,OAAOlB,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAgB;QACjE,MAAMQ,gBAAgB,MAAMG,QACzBC,UAAU,CAAC,iBACXK,KAAK,CAAC,iBAAiB,MAAMH,OAC7BI,KAAK,CAAC,GACNF,GAAG;QACN,MAAMG,cAAaX,uBAAAA,cAAcY,IAAI,CAAC,EAAE,qBAArBZ,qBAAuBQ,GAAG,CAAC;QAC9C,IAAI,CAACG,YAAY;YACf,OAAOvB,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;gBAAEC,OAAO;YAAwB;QAC/D;QACA,MAAMqB,UAAUhB,QAAOV,uBAAAA,IAAI2B,OAAO,CAACD,OAAO,YAAnB1B,uBAAuB;QAC9C,MAAM4B,SAAS,CAAC,QAAQ,EAAE5B,IAAI2B,OAAO,CAACE,IAAI,EAAE;QAC5C,MAAMC,WAAW,MAAMC,MACrB,qDACA;YACE7B,QAAQ;YACRyB,SAAS;gBACPK,eAAe,CAAC,OAAO,EAAE1B,QAAQC,GAAG,CAACC,iBAAiB,EAAE;gBACxD,gBAAgB;YAClB;YACAG,MAAM,IAAIsB,gBAAgB;gBACxBC,UAAUxB,OAAOc;gBACjBW,YAAYT,QAAQU,UAAU,CAAC,UAAUV,UAAUE;YACrD,GAAGS,QAAQ;QACb;QAEF,MAAMC,UAAU,MAAMR,SAAS1B,IAAI;QACnC,IAAI,CAAC0B,SAASS,EAAE,IAAI,CAACD,QAAQE,GAAG,EAAE;YAChCC,QAAQpC,KAAK,CAAC,gBAAgBiC,2BAAAA,QAASjC,KAAK;YAC5C,OAAOJ,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;gBAAEC,OAAO;YAAqB;QAC5D;QACA,OAAOJ,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEoC,KAAKF,QAAQE,GAAG;QAAC;IACjD,EAAE,OAAOnC,OAAO;QACdoC,QAAQpC,KAAK,CAACA;QACd,OAAOJ,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAqB;IAC5D;AACF,EAAC"}

package/src/lib/server/supplier-outbox.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @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 PluginJobHostGate } from '@aglyn/aglyn/server';
+/**
+ * The durable outbox for the dropship supplier notification (AGL-2473).
+ *
+ * ## What was wrong
+ *
+ * `billing-webhook.ts` routed a paid dropship order inside
+ * `void (async () => { … })()`, and the last thing that block did was
+ * `await fetch(supplier.webhookUrl, …)` — an endpoint the MERCHANT typed into
+ * a console field, on a host Aglyn neither runs nor monitors. Vercel freezes
+ * the container the instant the response is written, so a supplier that is
+ * slow, rate-limiting, or simply down is a supplier that is never told. The
+ * order is paid, the buyer is thanked, the merchant sees "Sent to supplier X"
+ * on the timeline, and NOTHING ANYWHERE records that the POST is still owed —
+ * so no later pass can find it and no report can list it. It surfaces when the
+ * customer asks where their parcel is.
+ *
+ * ## Why not just `await` it
+ *
+ * AGL-2161 fixed the other four fire-and-forget sites in that file and
+ * deliberately left this one, because awaiting it is worse rather than better:
+ * a supplier taking 30s pushes the handler past Stripe's delivery window,
+ * Stripe redelivers, and the redelivery re-enters a fan-out whose only
+ * idempotency is one `created` flag upstream. A silently dropped notification
+ * would have been traded for a DUPLICATED order. `refund.ts` awaits its own
+ * sibling and says so in a comment — correctly, because that sibling only
+ * touches our own Firestore.
+ *
+ * So the line this module draws is not "fast vs slow" but **ours vs theirs**.
+ * Everything the routing block does to Aglyn's own storage — the callback
+ * token, the timeline entry, the supplier email through our own provider — is
+ * now AWAITED on the response path, exactly like `refund.ts`. The one call to a
+ * stranger's server becomes a row here, and the response no longer waits on it.
+ *
+ * ## The mechanism
+ *
+ * A Firestore-backed outbox drained by the plugin-job beat that already runs
+ * the two commerce recovery passes (`server.ts`). No new infrastructure: the
+ * beat is a Cloud Scheduler function POSTing the tenant runner route, and it
+ * has carried bounded scans since AGL-2227.
+ *
+ *  * **Idempotent enqueue.** The id is `{hostId}__{orderId}__{supplierId}` and
+ *    the write is `create()`, which REFUSES an existing document, so a
+ *    redelivery cannot reset a retry part-way through its backoff. The AGL-498
+ *    existence guard upstream already returns before this fan-out, but
+ *    `reconcile-stock.ts` documents at length why one flag over a dozen effects
+ *    is not something to lean on.
+ *  * **Backoff.** 1m, 5m, 15m, 1h, 6h — about seven and a half hours of cover,
+ *    which is a supplier's overnight deploy but not their week off.
+ *  * **Dead letter.** After {@link SUPPLIER_DELIVERY_MAX_ATTEMPTS} the row is
+ *    left as `failed`, the ORDER's own timeline is stamped, and host managers
+ *    get a notification. The merchant reading the order they were paid for can
+ *    see that it never reached the supplier — the thing the old code could not
+ *    tell anyone, because it wrote nothing down.
+ *
+ * ## Two placement decisions, both deliberate
+ *
+ * **TOP-LEVEL, not `hosts/{hostId}/supplierDeliveries`.** The host catch-all in
+ * the rules file is PERMISSIVE by default — a subcollection nobody names in its
+ * three exclusion lists is one every site editor can write from the browser —
+ * and the row carries the exact JSON body we sign and POST, so an editor-
+ * writable row is an editor-chosen payload delivered under the supplier's own
+ * shared secret. A top-level collection matches no rule in
+ * `cloud/firebase-firestore.rules` at all and is therefore denied to every
+ * client by default, the same footing as `platform/pluginJobs`. It also keeps
+ * the drain on an ordinary collection query: a collection-GROUP `where` would
+ * need a `COLLECTION_GROUP_ASC` fieldOverride, and AGL-1793 is the record of
+ * both commerce crons being silently dead in production for want of exactly
+ * that. Neither a rules deploy nor an index deploy is owed for this change.
+ *
+ * **A delivered row is DELETED, not stamped `delivered`.** The body holds the
+ * buyer's email and name, and a top-level document is outside the
+ * `hosts/{hostId}` recursive delete an erasure request runs. Retaining the
+ * happy path would accumulate third-party PII in a place erasure does not
+ * reach, to record something the order's own `routed` timeline entry already
+ * says. Dead-lettered rows survive, because those are the ones a human has to
+ * act on and the merchant has been told about them.
+ */
+/** Top-level collection. Matches no rule, so no client may read or write it. */
+export declare const SUPPLIER_DELIVERY_COLLECTION = "supplierDeliveries";
+/** Attempts before a delivery is dead-lettered. */
+export declare const SUPPLIER_DELIVERY_MAX_ATTEMPTS = 6;
+/**
+ * Delay before the next retry, indexed by attempts ALREADY made.
+ *
+ * The first entry is 60s and the job beat is also 60s, so a supplier that
+ * blipped is retried on the next tick rather than a quarter of an hour later —
+ * the difference between a parcel that ships today and one that does not.
+ */
+export declare const SUPPLIER_DELIVERY_BACKOFF_MS: readonly number[];
+/**
+ * Per-attempt timeout. Nothing user-facing waits on this — it exists so one
+ * hung supplier cannot hold the shared job beat open for the whole scan.
+ */
+export declare const SUPPLIER_DELIVERY_TIMEOUT_MS = 10000;
+/** Rows examined per drain. Bounded like every other scan on the beat. */
+export declare const SUPPLIER_DELIVERY_SCAN_LIMIT = 100;
+export type SupplierDeliveryStatus = 'pending' | 'failed';
+export interface SupplierDeliveryRecord {
+    status: SupplierDeliveryStatus;
+    hostId: string;
+    orderId: string;
+    supplierId: string;
+    supplierName: string;
+    /** The endpoint as configured when the order was routed, for the record. */
+    url: string;
+    /** The exact JSON the supplier is sent; signed at delivery time. */
+    body: string;
+    attempts: number;
+    nextAttemptAtMs: number;
+    createdAtMs: number;
+    lastError?: string;
+    lastStatus?: number;
+    failedAtMs?: number;
+}
+export interface SupplierDeliveryScanResult {
+    scanned: number;
+    delivered: number;
+    retried: number;
+    deadLettered: number;
+    /** Retired without delivery because the merchant removed the endpoint. */
+    cancelled: number;
+    /** Left pending, with the retry budget intact, because the site is locked. */
+    skippedLocked: number;
+}
+/**
+ * The delay owed after `attempts` failures, clamped to the last step.
+ *
+ * Clamped rather than extrapolated: the tail entry is already six hours, and a
+ * dead letter is what comes after it, not a longer and longer silence.
+ */
+export declare function supplierDeliveryBackoffMs(attempts: number): number;
+/**
+ * The outbox document id for one host/order/supplier triple.
+ *
+ * Deterministic, so `create()` is the idempotency. `__` rather than `:` or `/`:
+ * a slash would make `.doc()` build a PATH instead of an id (AGL-1771), and the
+ * separator has to survive a Stripe session id, which already contains `_`.
+ * Firestore reserves ids fully matching `__.*__`; this never is, because all
+ * three parts are non-empty and the id neither starts nor ends with `__`.
+ */
+export declare function supplierDeliveryId(hostId: string, orderId: string, supplierId: string): string;
+/**
+ * Records that a supplier POST is owed. One Firestore write, awaited.
+ *
+ * Returns `'queued'`, `'exists'` when a row for this triple is already in
+ * flight, or `'skipped'`. NEVER THROWS: the caller is a paid order's fulfilment
+ * path, and a queue that cannot be written must not take the receipt down with
+ * it. The refusal is logged, which is strictly more than the old code managed
+ * on the same failure.
+ */
+export declare function enqueueSupplierDelivery(options: {
+    firestore: FirebaseFirestore.Firestore;
+    hostId: string;
+    orderId: string;
+    supplierId: string;
+    supplierName: string;
+    url: string;
+    body: string;
+    now?: number;
+}): Promise<'queued' | 'exists' | 'skipped'>;
+/**
+ * Drains the supplier outbox. Bounded, and safe to run twice.
+ *
+ * `nextAttemptAtMs` is filtered IN MEMORY rather than added to the query, which
+ * would need a composite index for one field's worth of selectivity. The cost
+ * is that a row still inside its backoff occupies one of the
+ * {@link SUPPLIER_DELIVERY_SCAN_LIMIT} slots; with at most
+ * {@link SUPPLIER_DELIVERY_MAX_ATTEMPTS} attempts per row the queue always
+ * drains rather than growing a permanent head.
+ */
+export declare function scanSupplierDeliveries(
+/** The lockdown gate, injected by the caller (AGL-2495). Not optional. */
+gate: PluginJobHostGate, now?: number): Promise<SupplierDeliveryScanResult>;

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

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