@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/promotion-hold.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @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.
+ */
+/**
+ * Reserve-then-settle for promotion redemption slots (AGL-2453).
+ *
+ * The I/O half of `model/commerce-promotions.ts` — read that file first; it
+ * carries the decision this one implements. Three call sites share it, and
+ * sharing is the point: the typed coupon (`coupons/{code}`), the automatic
+ * AGL-305 discount (`discounts/{id}`) and buy-now's coupon are three doors onto
+ * the same counter, and a hold placed at one of them has to be visible at the
+ * other two. Three copies of this transaction would be three chances for one of
+ * them to drift back to a plain `.get()`.
+ */
+/** What a placed hold gives back to the caller. */
+export interface PromotionSlotHold {
+    /**
+     * The key the hold was stored under, or `''` when the promotion is uncapped
+     * and no hold was needed. Carried in the session metadata so the webhook can
+     * settle exactly this reservation; its absence is what tells the webhook to
+     * fall back to the unconditional increment.
+     */
+    holdKey: string;
+    /**
+     * Drop the hold. Called by every refusal BELOW the checkout claim, and by
+     * `checkout.session.expired`. Best-effort and never throws: the TTL is the
+     * backstop, and tidying a reservation must not turn a clean 400 into a 500.
+     */
+    release: () => Promise<void>;
+}
+/**
+ * Why a slot could not be claimed.
+ *
+ * - `exhausted` — every slot is spoken for, by a settled redemption or a live
+ *   hold. The one refusal a shopper is told about by name.
+ * - `missing` — the promotion document is gone, deleted between the resolver's
+ *   read and this transaction.
+ * - `error` — Firestore refused. The discount is REFUSED rather than given
+ *   away uncounted: a promotion applied against a counter that could not be
+ *   reserved is the defect this file exists to close.
+ */
+export type PromotionSlotRefusal = 'exhausted' | 'missing' | 'error';
+/**
+ * Written as a two-member union with `reason` on BOTH members rather than a
+ * `{ ok: true } & PromotionSlotHold` intersection. Discriminated-union
+ * narrowing does not reach through the intersection under this repo's compiler
+ * settings (`strictNullChecks` is off repo-wide), so the intersection form
+ * compiled to `Property 'reason' does not exist` at every call site.
+ */
+export type PromotionSlotOutcome = {
+    ok: true;
+    reason?: undefined;
+    holdKey: string;
+    release: () => Promise<void>;
+} | {
+    ok: false;
+    reason: PromotionSlotRefusal;
+};
+/**
+ * A stable per-attempt hold key.
+ *
+ * `claim.stripeKey` when the client sent an Idempotency-Key, so a retry of one
+ * attempt re-claims its OWN slot rather than being refused by it. When it did
+ * not, a fresh random key per request — NOT the literal string `'null'`, which
+ * is what `String(claim.stripeKey)` yields and which would make every keyless
+ * shopper on the site share one hold. Sharing a hold key is the defect: two
+ * shoppers would each read the other's reservation as their own retry and both
+ * pass a cap of one.
+ *
+ * A keyless retry therefore holds a second slot. That is the safe direction —
+ * it over-reserves and releases on refusal or expiry — and the keyless path is
+ * already recorded as a real hole in `api-idempotency.ts` (AGL-2163) rather
+ * than something this fix can close.
+ */
+export declare function promotionHoldKey(stripeKey: string | null): string;
+/**
+ * Claim one redemption slot, or refuse.
+ *
+ * The re-check and the write are ONE transaction over the SAME document, which
+ * is the whole fix: the old code read the counter with a plain `.get()` at
+ * session creation and the webhook incremented it minutes later without ever
+ * re-asking. Firestore aborts and re-runs this callback if the promotion
+ * changed between the read and the commit, so two checkouts contending for the
+ * last slot cannot both observe it free.
+ *
+ * An UNCAPPED promotion writes nothing at all and returns an empty `holdKey`.
+ * There is no slot to reserve, and keeping the unlimited case off this write
+ * path keeps the fix's blast radius on the capped case.
+ */
+export declare function holdPromotionSlot(options: {
+    firestore: FirebaseFirestore.Firestore;
+    ref: FirebaseFirestore.DocumentReference;
+    holdKey: string;
+    nowMs?: number;
+    /** Label for the failure log; never shown to a shopper. */
+    label: string;
+}): Promise<PromotionSlotOutcome>;
+/**
+ * Give a slot back.
+ *
+ * A bare merge-set with the delete sentinel rather than a transaction: removing
+ * one key is not a read-modify-write, and a release must not be able to fail
+ * the response it is tidying up after. Swallows its own error for the same
+ * reason — the TTL still releases the slot.
+ */
+export declare function releasePromotionHold(ref: FirebaseFirestore.DocumentReference, holdKey: string): Promise<void>;
+/** What a settlement did, for the caller's orphan reporting. */
+export type PromotionSettlement = 
+/** The hold was found and converted into a redemption. */
+'settled'
+/** No hold under this key: a redelivery, already counted. Do nothing. */
+ | 'already-settled'
+/** The promotion document is gone; the redemption cannot be recorded. */
+ | 'missing'
+/** Firestore refused; the hold stands and lapses on its own. */
+ | 'error';
+/**
+ * Convert a held slot into a counted redemption.
+ *
+ * Idempotent under Stripe's at-least-once delivery, which is the property
+ * `reconcile-stock.ts:52-58` asks any webhook-side guard on these counters to
+ * have: the redemption is owed only by the presence of the HOLD, so a second
+ * delivery finds none and takes nothing. The increment and the removal are one
+ * write, so there is no window in which the slot is both counted and held.
+ */
+export declare function settlePromotionSlot(options: {
+    firestore: FirebaseFirestore.Firestore;
+    ref: FirebaseFirestore.DocumentReference;
+    holdKey: string;
+    label: string;
+}): Promise<PromotionSettlement>;

package/src/lib/server/promotion-hold.js

@@ -0,0 +1,174 @@
+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.
+ */ import * as CommerceModel from "../model/index.js";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { randomUUID } from "crypto";
+/**
+ * A stable per-attempt hold key.
+ *
+ * `claim.stripeKey` when the client sent an Idempotency-Key, so a retry of one
+ * attempt re-claims its OWN slot rather than being refused by it. When it did
+ * not, a fresh random key per request — NOT the literal string `'null'`, which
+ * is what `String(claim.stripeKey)` yields and which would make every keyless
+ * shopper on the site share one hold. Sharing a hold key is the defect: two
+ * shoppers would each read the other's reservation as their own retry and both
+ * pass a cap of one.
+ *
+ * A keyless retry therefore holds a second slot. That is the safe direction —
+ * it over-reserves and releases on refusal or expiry — and the keyless path is
+ * already recorded as a real hole in `api-idempotency.ts` (AGL-2163) rather
+ * than something this fix can close.
+ */ export function promotionHoldKey(stripeKey) {
+    return stripeKey || `anon-${randomUUID()}`;
+}
+/**
+ * Claim one redemption slot, or refuse.
+ *
+ * The re-check and the write are ONE transaction over the SAME document, which
+ * is the whole fix: the old code read the counter with a plain `.get()` at
+ * session creation and the webhook incremented it minutes later without ever
+ * re-asking. Firestore aborts and re-runs this callback if the promotion
+ * changed between the read and the commit, so two checkouts contending for the
+ * last slot cannot both observe it free.
+ *
+ * An UNCAPPED promotion writes nothing at all and returns an empty `holdKey`.
+ * There is no slot to reserve, and keeping the unlimited case off this write
+ * path keeps the fix's blast radius on the capped case.
+ */ export async function holdPromotionSlot(options) {
+    var _options_nowMs;
+    const { firestore, ref, holdKey, label } = options;
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const outcome = await firestore.runTransaction(async (transaction)=>{
+        var _fresh_data, _promotion_holds;
+        const fresh = await transaction.get(ref);
+        if (!fresh.exists) return 'missing';
+        const promotion = (_fresh_data = fresh.data()) != null ? _fresh_data : {};
+        // Uncapped: nothing to reserve, and nothing written. The webhook keeps
+        // the plain `increment(1)` for these, exactly as before this issue.
+        if (CommerceModel.promotionRemainingSlots(promotion, nowMs, holdKey) == null) {
+            return 'uncapped';
+        }
+        // This attempt's own prior hold does not stand in its way — a retry must
+        // be able to re-claim what it already reserved, or the second press of
+        // the same button refuses the shopper a slot they are already holding.
+        if (CommerceModel.promotionExhausted(promotion, nowMs, holdKey)) {
+            return 'exhausted';
+        }
+        // Lapsed holds are removed by SENTINEL, never by writing back a locally
+        // pruned copy of the map: `set(…, { merge: true })` DEEP-merges nested
+        // maps, so an object with the key removed leaves the stored key exactly
+        // where it was. Correctness does not depend on the sweep — every read
+        // prunes again — but without it the document grows one dead key per
+        // abandoned checkout, forever. The same sentinel is load-bearing at
+        // SETTLEMENT below, where writing back a pruned map would leave the hold
+        // standing and let a webhook redelivery count the redemption twice.
+        const live = CommerceModel.prunePromotionHolds(promotion.holds, nowMs);
+        const swept = {};
+        for (const stale of Object.keys((_promotion_holds = promotion.holds) != null ? _promotion_holds : {})){
+            if (stale !== holdKey && !live[stale]) {
+                swept[stale] = firebaseAdmin.firestore.FieldValue.delete();
+            }
+        }
+        transaction.set(ref, {
+            holds: _extends({}, swept, {
+                [holdKey]: {
+                    expiresAtMs: nowMs + CommerceModel.PROMOTION_HOLD_TTL_MS
+                }
+            })
+        }, {
+            merge: true
+        });
+        return 'held';
+    }).catch((error)=>{
+        console.error('Promotion hold failed', label, error);
+        return 'error';
+    });
+    if (outcome === 'uncapped') {
+        return {
+            ok: true,
+            holdKey: '',
+            release: async ()=>undefined
+        };
+    }
+    if (outcome === 'held') {
+        return {
+            ok: true,
+            holdKey,
+            release: ()=>releasePromotionHold(ref, holdKey)
+        };
+    }
+    return {
+        ok: false,
+        reason: outcome
+    };
+}
+/**
+ * Give a slot back.
+ *
+ * A bare merge-set with the delete sentinel rather than a transaction: removing
+ * one key is not a read-modify-write, and a release must not be able to fail
+ * the response it is tidying up after. Swallows its own error for the same
+ * reason — the TTL still releases the slot.
+ */ export async function releasePromotionHold(ref, holdKey) {
+    if (!holdKey) return;
+    await ref.set({
+        holds: {
+            [holdKey]: firebaseAdmin.firestore.FieldValue.delete()
+        }
+    }, {
+        merge: true
+    }).catch((error)=>{
+        console.error('Promotion hold release failed', ref.path, error);
+    });
+}
+/**
+ * Convert a held slot into a counted redemption.
+ *
+ * Idempotent under Stripe's at-least-once delivery, which is the property
+ * `reconcile-stock.ts:52-58` asks any webhook-side guard on these counters to
+ * have: the redemption is owed only by the presence of the HOLD, so a second
+ * delivery finds none and takes nothing. The increment and the removal are one
+ * write, so there is no window in which the slot is both counted and held.
+ */ export async function settlePromotionSlot(options) {
+    const { firestore, ref, holdKey, label } = options;
+    return await firestore.runTransaction(async (transaction)=>{
+        var _fresh_data;
+        const fresh = await transaction.get(ref);
+        if (!fresh.exists) return 'missing';
+        const promotion = (_fresh_data = fresh.data()) != null ? _fresh_data : {};
+        if (!CommerceModel.promotionSettles(promotion, holdKey)) {
+            return 'already-settled';
+        }
+        transaction.set(ref, {
+            redemptions: firebaseAdmin.firestore.FieldValue.increment(1),
+            // `FieldValue.delete()`, NOT a pruned copy of the map — see the note
+            // in `holdPromotionSlot`. A merged-back object would leave the hold
+            // standing and a redelivery would increment a SECOND time.
+            holds: {
+                [holdKey]: firebaseAdmin.firestore.FieldValue.delete()
+            }
+        }, {
+            merge: true
+        });
+        return 'settled';
+    }).catch((error)=>{
+        console.error('Promotion settlement failed', label, error);
+        return 'error';
+    });
+}
+
+//# sourceMappingURL=promotion-hold.js.map

package/src/lib/server/promotion-hold.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/promotion-hold.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 * as CommerceModel from '../model'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { randomUUID } from 'crypto'\n\n/**\n * Reserve-then-settle for promotion redemption slots (AGL-2453).\n *\n * The I/O half of `model/commerce-promotions.ts` — read that file first; it\n * carries the decision this one implements. Three call sites share it, and\n * sharing is the point: the typed coupon (`coupons/{code}`), the automatic\n * AGL-305 discount (`discounts/{id}`) and buy-now's coupon are three doors onto\n * the same counter, and a hold placed at one of them has to be visible at the\n * other two. Three copies of this transaction would be three chances for one of\n * them to drift back to a plain `.get()`.\n */\n\n/** What a placed hold gives back to the caller. */\nexport interface PromotionSlotHold {\n  /**\n   * The key the hold was stored under, or `''` when the promotion is uncapped\n   * and no hold was needed. Carried in the session metadata so the webhook can\n   * settle exactly this reservation; its absence is what tells the webhook to\n   * fall back to the unconditional increment.\n   */\n  holdKey: string\n  /**\n   * Drop the hold. Called by every refusal BELOW the checkout claim, and by\n   * `checkout.session.expired`. Best-effort and never throws: the TTL is the\n   * backstop, and tidying a reservation must not turn a clean 400 into a 500.\n   */\n  release: () => Promise<void>\n}\n\n/**\n * Why a slot could not be claimed.\n *\n * - `exhausted` — every slot is spoken for, by a settled redemption or a live\n *   hold. The one refusal a shopper is told about by name.\n * - `missing` — the promotion document is gone, deleted between the resolver's\n *   read and this transaction.\n * - `error` — Firestore refused. The discount is REFUSED rather than given\n *   away uncounted: a promotion applied against a counter that could not be\n *   reserved is the defect this file exists to close.\n */\nexport type PromotionSlotRefusal = 'exhausted' | 'missing' | 'error'\n\n/**\n * Written as a two-member union with `reason` on BOTH members rather than a\n * `{ ok: true } & PromotionSlotHold` intersection. Discriminated-union\n * narrowing does not reach through the intersection under this repo's compiler\n * settings (`strictNullChecks` is off repo-wide), so the intersection form\n * compiled to `Property 'reason' does not exist` at every call site.\n */\nexport type PromotionSlotOutcome =\n  | { ok: true; reason?: undefined; holdKey: string; release: () => Promise<void> }\n  | { ok: false; reason: PromotionSlotRefusal }\n\n/**\n * A stable per-attempt hold key.\n *\n * `claim.stripeKey` when the client sent an Idempotency-Key, so a retry of one\n * attempt re-claims its OWN slot rather than being refused by it. When it did\n * not, a fresh random key per request — NOT the literal string `'null'`, which\n * is what `String(claim.stripeKey)` yields and which would make every keyless\n * shopper on the site share one hold. Sharing a hold key is the defect: two\n * shoppers would each read the other's reservation as their own retry and both\n * pass a cap of one.\n *\n * A keyless retry therefore holds a second slot. That is the safe direction —\n * it over-reserves and releases on refusal or expiry — and the keyless path is\n * already recorded as a real hole in `api-idempotency.ts` (AGL-2163) rather\n * than something this fix can close.\n */\nexport function promotionHoldKey(stripeKey: string | null): string {\n  return stripeKey || `anon-${randomUUID()}`\n}\n\n/**\n * Claim one redemption slot, or refuse.\n *\n * The re-check and the write are ONE transaction over the SAME document, which\n * is the whole fix: the old code read the counter with a plain `.get()` at\n * session creation and the webhook incremented it minutes later without ever\n * re-asking. Firestore aborts and re-runs this callback if the promotion\n * changed between the read and the commit, so two checkouts contending for the\n * last slot cannot both observe it free.\n *\n * An UNCAPPED promotion writes nothing at all and returns an empty `holdKey`.\n * There is no slot to reserve, and keeping the unlimited case off this write\n * path keeps the fix's blast radius on the capped case.\n */\nexport async function holdPromotionSlot(options: {\n  firestore: FirebaseFirestore.Firestore\n  ref: FirebaseFirestore.DocumentReference\n  holdKey: string\n  nowMs?: number\n  /** Label for the failure log; never shown to a shopper. */\n  label: string\n}): Promise<PromotionSlotOutcome> {\n  const { firestore, ref, holdKey, label } = options\n  const nowMs = options.nowMs ?? Date.now()\n  const outcome = await firestore\n    .runTransaction(async (transaction) => {\n      const fresh = await transaction.get(ref)\n      if (!fresh.exists) return 'missing' as const\n      const promotion = (fresh.data() ?? {}) as CommerceModel.HeldPromotion\n      // Uncapped: nothing to reserve, and nothing written. The webhook keeps\n      // the plain `increment(1)` for these, exactly as before this issue.\n      if (\n        CommerceModel.promotionRemainingSlots(promotion, nowMs, holdKey) == null\n      ) {\n        return 'uncapped' as const\n      }\n      // This attempt's own prior hold does not stand in its way — a retry must\n      // be able to re-claim what it already reserved, or the second press of\n      // the same button refuses the shopper a slot they are already holding.\n      if (CommerceModel.promotionExhausted(promotion, nowMs, holdKey)) {\n        return 'exhausted' as const\n      }\n      // Lapsed holds are removed by SENTINEL, never by writing back a locally\n      // pruned copy of the map: `set(…, { merge: true })` DEEP-merges nested\n      // maps, so an object with the key removed leaves the stored key exactly\n      // where it was. Correctness does not depend on the sweep — every read\n      // prunes again — but without it the document grows one dead key per\n      // abandoned checkout, forever. The same sentinel is load-bearing at\n      // SETTLEMENT below, where writing back a pruned map would leave the hold\n      // standing and let a webhook redelivery count the redemption twice.\n      const live = CommerceModel.prunePromotionHolds(promotion.holds, nowMs)\n      const swept: Record<string, unknown> = {}\n      for (const stale of Object.keys(promotion.holds ?? {})) {\n        if (stale !== holdKey && !live[stale]) {\n          swept[stale] = firebaseAdmin.firestore.FieldValue.delete()\n        }\n      }\n      transaction.set(\n        ref,\n        {\n          holds: {\n            ...swept,\n            [holdKey]: {\n              expiresAtMs: nowMs + CommerceModel.PROMOTION_HOLD_TTL_MS,\n            },\n          },\n        },\n        { merge: true },\n      )\n      return 'held' as const\n    })\n    .catch((error: unknown) => {\n      console.error('Promotion hold failed', label, error)\n      return 'error' as const\n    })\n  if (outcome === 'uncapped') {\n    return { ok: true, holdKey: '', release: async () => undefined }\n  }\n  if (outcome === 'held') {\n    return { ok: true, holdKey, release: () => releasePromotionHold(ref, holdKey) }\n  }\n  return { ok: false, reason: outcome }\n}\n\n/**\n * Give a slot back.\n *\n * A bare merge-set with the delete sentinel rather than a transaction: removing\n * one key is not a read-modify-write, and a release must not be able to fail\n * the response it is tidying up after. Swallows its own error for the same\n * reason — the TTL still releases the slot.\n */\nexport async function releasePromotionHold(\n  ref: FirebaseFirestore.DocumentReference,\n  holdKey: string,\n): Promise<void> {\n  if (!holdKey) return\n  await ref\n    .set(\n      { holds: { [holdKey]: firebaseAdmin.firestore.FieldValue.delete() } },\n      { merge: true },\n    )\n    .catch((error: unknown) => {\n      console.error('Promotion hold release failed', ref.path, error)\n    })\n}\n\n/** What a settlement did, for the caller's orphan reporting. */\nexport type PromotionSettlement =\n  /** The hold was found and converted into a redemption. */\n  | 'settled'\n  /** No hold under this key: a redelivery, already counted. Do nothing. */\n  | 'already-settled'\n  /** The promotion document is gone; the redemption cannot be recorded. */\n  | 'missing'\n  /** Firestore refused; the hold stands and lapses on its own. */\n  | 'error'\n\n/**\n * Convert a held slot into a counted redemption.\n *\n * Idempotent under Stripe's at-least-once delivery, which is the property\n * `reconcile-stock.ts:52-58` asks any webhook-side guard on these counters to\n * have: the redemption is owed only by the presence of the HOLD, so a second\n * delivery finds none and takes nothing. The increment and the removal are one\n * write, so there is no window in which the slot is both counted and held.\n */\nexport async function settlePromotionSlot(options: {\n  firestore: FirebaseFirestore.Firestore\n  ref: FirebaseFirestore.DocumentReference\n  holdKey: string\n  label: string\n}): Promise<PromotionSettlement> {\n  const { firestore, ref, holdKey, label } = options\n  return await firestore\n    .runTransaction(async (transaction) => {\n      const fresh = await transaction.get(ref)\n      if (!fresh.exists) return 'missing' as const\n      const promotion = (fresh.data() ?? {}) as CommerceModel.HeldPromotion\n      if (!CommerceModel.promotionSettles(promotion, holdKey)) {\n        return 'already-settled' as const\n      }\n      transaction.set(\n        ref,\n        {\n          redemptions: firebaseAdmin.firestore.FieldValue.increment(1),\n          // `FieldValue.delete()`, NOT a pruned copy of the map — see the note\n          // in `holdPromotionSlot`. A merged-back object would leave the hold\n          // standing and a redelivery would increment a SECOND time.\n          holds: {\n            [holdKey]: firebaseAdmin.firestore.FieldValue.delete(),\n          },\n        },\n        { merge: true },\n      )\n      return 'settled' as const\n    })\n    .catch((error: unknown) => {\n      console.error('Promotion settlement failed', label, error)\n      return 'error' as const\n    })\n}\n"],"names":["CommerceModel","firebaseAdmin","randomUUID","promotionHoldKey","stripeKey","holdPromotionSlot","options","firestore","ref","holdKey","label","nowMs","Date","now","outcome","runTransaction","transaction","fresh","promotion","get","exists","data","promotionRemainingSlots","promotionExhausted","live","prunePromotionHolds","holds","swept","stale","Object","keys","FieldValue","delete","set","expiresAtMs","PROMOTION_HOLD_TTL_MS","merge","catch","error","console","ok","release","undefined","releasePromotionHold","reason","path","settlePromotionSlot","promotionSettles","redemptions","increment"],"mappings":"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"}

package/src/lib/server/reconcile-stock.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @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';
+export interface MissingSaleDecrement {
+    hostId: string;
+    orderId: string;
+    /** The merchant-facing sequential number, when the doc carries one. */
+    orderNumber: number | null;
+    orderStatus: string;
+    orderCreatedAtMs: number;
+    productId: string;
+    /** Live product name — the order's snapshot name is used as a fallback. */
+    productName: string;
+    variantId: string;
+    /** Units the order says were sold, and the shelf therefore still holds. */
+    quantity: number;
+}
+export interface StockReconciliationResult {
+    ordersScanned: number;
+    /** Orders that reached the ledger comparison (post status/grace filter). */
+    ordersChecked: number;
+    missing: MissingSaleDecrement[];
+    /**
+     * The ledger read hit its limit before reaching back as far as the oldest
+     * order considered, so orders older than the ledger window were DROPPED
+     * rather than judged against rows that were never read.
+     *
+     * Recorded and reported rather than swallowed, for the AGL-2321 reason:
+     * `siteSizeTruncated` exists because a number that is silently a lower
+     * bound is worse than one that says so. A truncated pass under-reports; it
+     * must never be read as "all matched".
+     */
+    ledgerTruncated: boolean;
+}
+/**
+ * Compares one host's recently-decremented orders against the
+ * `reason: 'sale'` rows joined to them, and reports the lines whose decrement
+ * is missing.
+ *
+ * Reads are bounded and cheap in the healthy case: two collection queries per
+ * host, and a product read ONLY for a line that already looks divergent.
+ *
+ * Two equality-free queries so the automatic single-field indexes answer them
+ * (the `cancel-order.ts` rule): `orderBy(createdAtMs desc).limit()` and
+ * `orderBy(atMs desc).limit()`, with the status test applied in memory over
+ * the handful of documents that come back.
+ */
+export declare function reconcileHostStockDecrements(options: {
+    firestore: any;
+    hostRef: any;
+    hostId: string;
+    nowMs?: number;
+    graceMs?: number;
+    orderLimit?: number;
+    ledgerLimit?: number;
+}): Promise<StockReconciliationResult>;
+/**
+ * Reports a host's divergences to its managers, once per order.
+ *
+ * The marker in `hosts/{hostId}/inventoryReconciliation/{orderId}` is the only
+ * write this whole pass makes, and it lives in a collection nothing else on
+ * the platform reads or writes — the detector must not be able to affect the
+ * money path it is watching. Without it a beat would re-nag every hour about
+ * an order the merchant has already corrected, and an alert that repeats
+ * forever is one that gets muted.
+ */
+export declare function reportMissingSaleDecrements(hostId: string, missing: readonly MissingSaleDecrement[]): Promise<number>;
+export interface StockReconciliationScan {
+    hosts: number;
+    ordersScanned: number;
+    missingLines: number;
+    reportedOrders: number;
+    truncatedHosts: number;
+    /** Hosts left unreconciled because they are locked (AGL-2495). */
+    skippedLocked: number;
+}
+/**
+ * The platform beat: the most recent orders across every host, grouped by
+ * host and reconciled one host at a time.
+ *
+ * Ordered by `createdAtMs` and NOT filtered by status, because an equality
+ * filter plus an ordering is a composite index and the ordering alone is a
+ * field override — the same trade `cancel-order.ts` takes. Every order writer
+ * in the plugin stamps `createdAtMs` (cart, buy-now, draft, POS cash, POS
+ * card, subscription cycle), so nothing is invisible to the ordering.
+ */
+export declare function scanStockDecrements(
+/** The lockdown gate, injected by the caller (AGL-2495). Not optional. */
+gate: PluginJobHostGate, options?: {
+    orderLimit?: number;
+    nowMs?: number;
+}): Promise<StockReconciliationScan>;