@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/site-page-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/site-page-resolver.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 { SitePageResolver } from '@aglyn/aglyn/server'\nimport { hostCollectionKind } from '@aglyn/aglyn/server'\nimport composeScreenNodes from '@aglyn/tenant-runtime/compose-screen-nodes'\nimport getScreen from '@aglyn/tenant-runtime/get-screen'\nimport { collectSocialImageFacts } from '@aglyn/tenant-runtime/social-image-facts'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport * as CommerceModel from '../model'\nimport { toPublicProductDetail } from './product'\nimport { readProductReviews } from './reviews'\n\n/**\n * Commerce page resolver (AGL-292/298/418), relocated verbatim from the\n * tenant loader: /products/{slug} renders the host's designated PDP\n * template with product tokens, /collections/{slug} the collection\n * template — both compose server-side and return complete page props.\n * Runs only for paths that didn't match a published screen; returns\n * undefined for everything else so the loader falls through.\n */\nexport const commerceSitePageResolver: SitePageResolver = async ({\n  hostId,\n  host,\n  path,\n}) => {\n  const hostRes = { host }\n  // Product detail routes (AGL-292): /products/{slug} renders the\n  // host's designated PDP template screen (settings/store\n  // `pdpScreenId`, AGL-295) with product tokens; the product-detail\n  // block hydrates variants client-side from the same slug. Same\n  // mechanism as entry-template screens below.\n  const pdpSegments = path.split('/').filter(Boolean)\n  if (pdpSegments.length === 2 && pdpSegments[0] === 'products') {\n    const adminFirestore = firebaseAdmin.app().firestore()\n    const hostDocRef = adminFirestore.collection('hosts').doc(hostId)\n    const [storeSettings, productSnapshot] = await Promise.all([\n      hostDocRef.collection('settings').doc('store').get(),\n      hostDocRef\n        .collection('products')\n        .where('slug', '==', pdpSegments[1])\n        .limit(1)\n        .get(),\n    ])\n    const pdpScreenId = storeSettings.get('pdpScreenId')\n    const productRaw = productSnapshot.docs[0]?.data() as any\n    if (\n      pdpScreenId &&\n      productRaw &&\n      !productRaw.deletedAt &&\n      productRaw.status === 'active'\n    ) {\n      const product = CommerceModel.liftLegacyProduct(productRaw)\n      const templateRes = await getScreen({\n        hostId,\n        screenId: pdpScreenId,\n        // A PDP template renders against a routed PRODUCT, never at an address\n        // of its own, so it is served here and 404s everywhere else (AGL-1400).\n        allowTemplate: true,\n      })\n      if (templateRes.screen) {\n        const [minPrice, maxPrice] = CommerceModel.productPriceRange(product)\n        // Best-effort: a reviews read that fails costs the page its rating\n        // snippet, not the page.\n        const productReviews = await readProductReviews(\n          hostId,\n          productSnapshot.docs[0].id,\n        ).catch((error) => {\n          console.error('product review aggregate failed', error)\n          return { reviews: [], aggregate: { count: 0, average: 0 } }\n        })\n        // The head shares this page as the template's image, then the site\n        // default, so their documents are read in the template's own batch\n        // (AGL-2850).\n        const card = collectSocialImageFacts([\n          (templateRes.screen as any).seo?.image,\n          hostRes.host?.seo?.image,\n        ])\n        const templateNodes = await composeScreenNodes({\n          hostId,\n          screenId: pdpScreenId,\n          screen: templateRes.screen,\n          socialImages: card.socialImages,\n          // The template's host variables, and its layout's, fill in from\n          // this site as they do on every other page (AGL-2883).\n          host: hostRes.host,\n          tokens: {\n            'product.name': product.name,\n            'product.description': product.description ?? '',\n            'product.price':\n              minPrice === maxPrice\n                ? `$${minPrice}`\n                : `From $${minPrice}`,\n            'product.image':\n              product.mediaUrls?.[0] ?? product.imageUrl ?? '',\n            'product.slug': product.slug,\n          },\n        })\n        if (templateNodes) {\n          return {\n            props: JSON.parse(\n              JSON.stringify({\n                // The PDP block used to fetch this in an effect, so the\n                // server rendered a skeleton and crawlers saw a product page\n                // with no product in it (AGL-659). The product is already\n                // loaded here — hand it down so it renders server-side.\n                pageData: {\n                  commerce: {\n                    product: toPublicProductDetail(\n                      productSnapshot.docs[0].id,\n                      product,\n                    ),\n                    // Rating aggregate (AGL-686): needed HERE because\n                    // `aggregateRating` belongs nested inside the Product\n                    // structured data, and that is emitted server-side.\n                    // The reviews block used to publish a free-standing\n                    // AggregateRating node, which schema.org ignores.\n                    ...(productReviews.aggregate.count\n                      ? { reviews: productReviews }\n                      : {}),\n                  },\n                },\n                data: {\n                  host: hostRes.host,\n                  screen: {\n                    data: {\n                      ...templateRes.screen,\n                      // The product NAMES this page; the template's own name\n                      // (\"Product detail\") describes none of the products it\n                      // renders. Kept distinct from the SEO title because the\n                      // head treats an authored title as verbatim and a name\n                      // as the side the site title joins (AGL-1341) — so a\n                      // product with its own SEO title gets exactly that, and\n                      // one without gets \"Blue Widget – Acme Store\".\n                      displayName: product.name,\n                      seo: {\n                        ...((templateRes.screen as any).seo ?? {}),\n                        // Only when the PRODUCT authored one: inheriting the\n                        // template screen's title would give every product\n                        // page in the store the same `<title>`.\n                        title: product.seo?.title ?? undefined,\n                        description:\n                          product.seo?.description ??\n                          product.description ??\n                          undefined,\n                      },\n                    },\n                  },\n                },\n                nodes: templateNodes,\n                ...card.collected(),\n              }),\n            ),\n            revalidate: 60,\n          }\n        }\n      }\n    }\n  }\n  // Commerce collection routes (AGL-298): /collections/{slug} renders\n  // the designated collection template with collection tokens; the\n  // product-grid block derives the same slug from the URL.\n  if (pdpSegments.length === 2 && pdpSegments[0] === 'collections') {\n    const adminFirestore = firebaseAdmin.app().firestore()\n    const hostDocRef = adminFirestore.collection('hosts').doc(hostId)\n    const [storeSettings, collectionSnapshot] = await Promise.all([\n      hostDocRef.collection('settings').doc('store').get(),\n      hostDocRef\n        .collection('collections')\n        .where('slug', '==', pdpSegments[1])\n        .limit(5)\n        .get(),\n    ])\n    const collectionScreenId = storeSettings.get('collectionScreenId')\n    // Content collections share this path and a slug is only unique within a\n    // kind (AGL-954), so take the first CATALOG match rather than the first\n    // doc — otherwise a blog with the same slug renders as a product page.\n    const shopCollection = collectionSnapshot.docs\n      .find((docSnapshot) => hostCollectionKind(docSnapshot.data()) === 'catalog')\n      ?.data() as CommerceModel.HostCollection | undefined\n    if (collectionScreenId && shopCollection) {\n      const templateRes = await getScreen({\n        hostId,\n        screenId: collectionScreenId,\n        allowTemplate: true,\n      })\n      if (templateRes.screen) {\n        // As on the PDP above: the template's image, then the site default\n        // (AGL-2850).\n        const card = collectSocialImageFacts([\n          (templateRes.screen as any).seo?.image,\n          hostRes.host?.seo?.image,\n        ])\n        const templateNodes = await composeScreenNodes({\n          hostId,\n          screenId: collectionScreenId,\n          screen: templateRes.screen,\n          socialImages: card.socialImages,\n          // As on the PDP above (AGL-2883).\n          host: hostRes.host,\n          tokens: {\n            'collection.name': shopCollection.name,\n            'collection.description': shopCollection.description ?? '',\n            'collection.image': shopCollection.imageUrl ?? '',\n            'collection.slug': shopCollection.slug,\n          },\n        })\n        if (templateNodes) {\n          return {\n            props: JSON.parse(\n              JSON.stringify({\n                data: {\n                  host: hostRes.host,\n                  screen: {\n                    data: {\n                      ...templateRes.screen,\n                      // As on the PDP above: the catalog collection names the\n                      // page, and a name takes the site title after it while\n                      // an authored SEO title would not (AGL-1341). A shop\n                      // collection has no SEO title field of its own, so the\n                      // template's must not stand in for one.\n                      displayName: shopCollection.name,\n                      seo: {\n                        ...((templateRes.screen as any).seo ?? {}),\n                        title: undefined,\n                        description:\n                          shopCollection.description ?? undefined,\n                      },\n                    },\n                  },\n                },\n                nodes: templateNodes,\n                ...card.collected(),\n              }),\n            ),\n            revalidate: 60,\n          }\n        }\n      }\n    }\n  }\n  return undefined\n}\n"],"names":["hostCollectionKind","composeScreenNodes","getScreen","collectSocialImageFacts","firebaseAdmin","CommerceModel","toPublicProductDetail","readProductReviews","commerceSitePageResolver","hostId","host","path","hostRes","pdpSegments","split","filter","Boolean","length","productSnapshot","adminFirestore","app","firestore","hostDocRef","collection","doc","storeSettings","Promise","all","get","where","limit","pdpScreenId","productRaw","docs","data","deletedAt","status","product","liftLegacyProduct","templateRes","screenId","allowTemplate","screen","minPrice","maxPrice","productPriceRange","productReviews","id","catch","error","console","reviews","aggregate","count","average","card","seo","image","templateNodes","socialImages","tokens","name","description","mediaUrls","imageUrl","slug","props","JSON","parse","stringify","pageData","commerce","displayName","title","undefined","nodes","collected","revalidate","collectionSnapshot","collectionScreenId","shopCollection","find","docSnapshot"],"mappings":"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"}

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

@@ -0,0 +1,127 @@
+/**
+ * @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 STOCK (AGL-2356).
+ *
+ * The I/O half of `model/commerce-stock-holds.ts` — read that file first; it
+ * carries the decision this one implements, including why the hold does not
+ * touch `inventory` and why a lapsed hold is a release.
+ *
+ * This is the AGL-2453 promotion-slot shape applied to the one counter that
+ * moves real goods, with two differences that matter:
+ *
+ *   1. **A cart holds N products, so the hold is ONE transaction over all of
+ *      them.** Firestore serialises the whole set, so a two-product cart either
+ *      reserves both or reserves neither — a partial reservation would charge a
+ *      shopper for a basket the store cannot fill, which is the failure this
+ *      issue exists to prevent, arriving through the fix.
+ *   2. **The release needs an index.** A promotion hold is released against the
+ *      one document named in the session metadata; a cart hold spans documents
+ *      Stripe never hears about. `hosts/{hostId}/stockHolds/{holdKey}` is
+ *      written INSIDE the same transaction as the holds it names, so the index
+ *      cannot disagree with the reservations, and the session carries only the
+ *      key.
+ */
+/** One reserved line, already resolved to a real variant. */
+export interface StockHoldLine {
+    productId: string;
+    variantId: string;
+    quantity: number;
+}
+/**
+ * Why a reservation could not be taken.
+ *
+ * - `sold-out` — the units are not there, or are spoken for by another live
+ *   checkout. The one refusal a shopper is told about by name.
+ * - `missing` — the product document is gone, deleted between the pricing
+ *   loop's read and this transaction.
+ * - `error` — Firestore refused. The checkout is REFUSED rather than allowed
+ *   through unreserved: passing a shopper to Stripe on a reservation that
+ *   could not be taken is exactly the defect this file closes.
+ */
+export type StockHoldRefusal = 'sold-out' | 'missing' | 'error';
+/**
+ * A two-member union with `reason` and `productName` present on BOTH members
+ * rather than an intersection, for the reason `PromotionSlotOutcome` records:
+ * discriminated-union narrowing does not reach through an intersection under
+ * this repo's compiler settings (`strictNullChecks` is off repo-wide), and the
+ * intersection form fails to compile at every call site.
+ */
+export type StockHoldOutcome = {
+    ok: true;
+    reason?: undefined;
+    productName?: undefined;
+    /**
+     * The key the hold was stored under, or `''` when nothing needed
+     * reserving (every line untracked or backorder). Carried in the session
+     * metadata so the webhook can release exactly this reservation; its
+     * absence is what tells the webhook there is nothing to release.
+     */
+    holdKey: string;
+    /** Drop the reservation. Best-effort and never throws. */
+    release: () => Promise<void>;
+} | {
+    ok: false;
+    reason: StockHoldRefusal;
+    productName: string;
+};
+/**
+ * A stable per-attempt hold key — the same rule as `promotionHoldKey`.
+ *
+ * `claim.stripeKey` when the client sent an Idempotency-Key, so a retry of one
+ * attempt re-claims its OWN units rather than being refused by them. When it
+ * did not, a fresh random key per request — NOT `String(claim.stripeKey)`,
+ * which yields the literal `'null'` and would make every keyless shopper on the
+ * site share one reservation, each reading the other's hold as their own retry
+ * and both passing a shelf of one.
+ */
+export declare function stockHoldKey(stripeKey: string | null): string;
+/**
+ * Reserve every line, or refuse.
+ *
+ * The re-check and the write are ONE transaction over the SAME documents, which
+ * is the whole fix: the old code read the shelf with a plain `.get()` at
+ * session creation and the webhook decremented it minutes later without ever
+ * re-asking, so N shoppers all read `inventory: 1` and all passed.
+ * `Transaction.get()` takes a lock on each product document, so contending
+ * checkouts SERIALISE — the loser re-runs its callback against the winner's
+ * committed hold and is refused.
+ *
+ * Lines with nothing to reserve — an untracked variant, a `backorder` product —
+ * write nothing at all, exactly as an uncapped promotion does. A cart made
+ * entirely of those returns an empty `holdKey` and the session carries no
+ * reservation, so the digital-goods storefront is byte-identical to what it was
+ * before this issue.
+ */
+export declare function holdStock(options: {
+    firestore: any;
+    hostRef: any;
+    holdKey: string;
+    lines: StockHoldLine[];
+    nowMs?: number;
+    /** Label for the failure log; never shown to a shopper. */
+    label: string;
+}): Promise<StockHoldOutcome>;
+/**
+ * Release a reservation named only by its key — the webhook's door.
+ *
+ * Reads the index written by `holdStock`, so `checkout.session.expired` needs
+ * nothing in the session but `metadata[stockHoldKey]`. A missing index doc is
+ * NOT an error: it means the hold was already released, or the session predates
+ * this deploy, and in both cases there is nothing to do.
+ */
+export declare function releaseStockHold(hostRef: any, holdKey: string): Promise<void>;

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

@@ -0,0 +1,258 @@
+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 — the same rule as `promotionHoldKey`.
+ *
+ * `claim.stripeKey` when the client sent an Idempotency-Key, so a retry of one
+ * attempt re-claims its OWN units rather than being refused by them. When it
+ * did not, a fresh random key per request — NOT `String(claim.stripeKey)`,
+ * which yields the literal `'null'` and would make every keyless shopper on the
+ * site share one reservation, each reading the other's hold as their own retry
+ * and both passing a shelf of one.
+ */ export function stockHoldKey(stripeKey) {
+    return stripeKey || `anon-${randomUUID()}`;
+}
+/** Two lines of one product COMPOUND — a cart holds variants, not products. */ function groupLines(lines) {
+    const byProduct = new Map();
+    for (const line of lines){
+        var _byProduct_get, _variants_get;
+        const quantity = Math.round(Number(line == null ? void 0 : line.quantity) || 0);
+        if (!(line == null ? void 0 : line.productId) || !(line == null ? void 0 : line.variantId) || quantity <= 0) continue;
+        const variants = (_byProduct_get = byProduct.get(line.productId)) != null ? _byProduct_get : new Map();
+        variants.set(line.variantId, ((_variants_get = variants.get(line.variantId)) != null ? _variants_get : 0) + quantity);
+        byProduct.set(line.productId, variants);
+    }
+    return byProduct;
+}
+/**
+ * Reserve every line, or refuse.
+ *
+ * The re-check and the write are ONE transaction over the SAME documents, which
+ * is the whole fix: the old code read the shelf with a plain `.get()` at
+ * session creation and the webhook decremented it minutes later without ever
+ * re-asking, so N shoppers all read `inventory: 1` and all passed.
+ * `Transaction.get()` takes a lock on each product document, so contending
+ * checkouts SERIALISE — the loser re-runs its callback against the winner's
+ * committed hold and is refused.
+ *
+ * Lines with nothing to reserve — an untracked variant, a `backorder` product —
+ * write nothing at all, exactly as an uncapped promotion does. A cart made
+ * entirely of those returns an empty `holdKey` and the session carries no
+ * reservation, so the digital-goods storefront is byte-identical to what it was
+ * before this issue.
+ */ export async function holdStock(options) {
+    var _options_nowMs, _outcome_productName;
+    const { firestore, hostRef, holdKey, lines, label } = options;
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const expiresAtMs = nowMs + CommerceModel.STOCK_HOLD_TTL_MS;
+    const byProduct = groupLines(lines);
+    const noop = {
+        ok: true,
+        holdKey: '',
+        release: async ()=>undefined
+    };
+    if (byProduct.size === 0) return noop;
+    // try/catch and NOT a trailing `.catch()`. A `runTransaction` that is
+    // missing or throws synchronously — a broken client, or a test double that
+    // never modelled one — never returns a promise for a `.catch()` to attach to,
+    // so the throw escapes the guard and becomes a 500 from the caller's own
+    // catch. That is still a refusal and never an unreserved sale, but it is a
+    // refusal this function was supposed to have named.
+    let outcome;
+    try {
+        outcome = await firestore.runTransaction(async (transaction)=>{
+            const productIds = [
+                ...byProduct.keys()
+            ];
+            // ALL READS BEFORE ANY WRITE, which Firestore requires and which is also
+            // what makes the set atomic: every document is locked before the first
+            // decision is taken against any of them.
+            const snapshots = await Promise.all(productIds.map((productId)=>transaction.get(hostRef.collection('products').doc(productId))));
+            const writes = [];
+            const heldProductIds = [];
+            for(let index = 0; index < productIds.length; index++){
+                var _ref;
+                var _snapshot_data, _snapshot_data1;
+                const productId = productIds[index];
+                const snapshot = snapshots[index];
+                if (!(snapshot == null ? void 0 : snapshot.exists)) {
+                    return {
+                        kind: 'missing',
+                        productName: ''
+                    };
+                }
+                const product = CommerceModel.liftLegacyProduct(snapshot.data());
+                const wanted = byProduct.get(productId);
+                const units = {};
+                for (const [variantId, quantity] of wanted){
+                    // `== null` is the test, never `!available` — `0` is a legitimate
+                    // answer here and `strictNullChecks` is off repo-wide.
+                    if (!CommerceModel.stockIsReservable(product, variantId, nowMs)) {
+                        continue;
+                    }
+                    if (!CommerceModel.canReserveStock(product, variantId, quantity, nowMs, // This attempt's own prior hold does not stand in its way: a
+                    // retry must re-claim what it already reserved, or the second
+                    // press of the same button refuses the shopper their own units.
+                    holdKey)) {
+                        var _ref1;
+                        return {
+                            kind: 'sold-out',
+                            productName: String((_ref1 = product == null ? void 0 : product.name) != null ? _ref1 : '')
+                        };
+                    }
+                    units[variantId] = quantity;
+                }
+                if (Object.keys(units).length === 0) continue;
+                // 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 this sweep — every read
+                // prunes again — but without it the document grows one dead key per
+                // abandoned checkout, forever, on the one document class in this plugin
+                // that is already the largest.
+                const live = CommerceModel.pruneStockHolds((_snapshot_data = snapshot.data()) == null ? void 0 : _snapshot_data.stockHolds, nowMs);
+                const swept = {};
+                for (const stale of Object.keys((_ref = (_snapshot_data1 = snapshot.data()) == null ? void 0 : _snapshot_data1.stockHolds) != null ? _ref : {})){
+                    if (stale !== holdKey && !live[stale]) {
+                        swept[stale] = firebaseAdmin.firestore.FieldValue.delete();
+                    }
+                }
+                writes.push({
+                    ref: hostRef.collection('products').doc(productId),
+                    value: {
+                        stockHolds: _extends({}, swept, {
+                            // A whole-object write for THIS key, not a nested merge: the
+                            // retry of an attempt whose cart shrank must not keep reserving
+                            // the line it dropped, and a deep merge of `units` would.
+                            [holdKey]: {
+                                expiresAtMs,
+                                units
+                            }
+                        })
+                    }
+                });
+                heldProductIds.push(productId);
+            }
+            if (writes.length === 0) return {
+                kind: 'nothing-to-hold'
+            };
+            for (const write of writes){
+                transaction.set(write.ref, write.value, {
+                    merge: true
+                });
+            }
+            // THE RELEASE INDEX, in the same transaction as the reservations it
+            // names. Written last so it can never name a product whose hold did not
+            // commit; read by id (never queried) on `checkout.session.expired` and at
+            // settlement, so it needs no index of its own.
+            transaction.set(hostRef.collection('stockHolds').doc(holdKey), {
+                productIds: heldProductIds,
+                lines: heldProductIds.flatMap((productId)=>[
+                        ...byProduct.get(productId)
+                    ].map(([variantId, quantity])=>({
+                            productId,
+                            variantId,
+                            quantity
+                        }))),
+                expiresAtMs,
+                createdAtMs: nowMs
+            }, {
+                merge: false
+            });
+            return {
+                kind: 'held',
+                productIds: heldProductIds
+            };
+        });
+    } catch (error) {
+        console.error('Stock hold failed', label, error);
+        outcome = {
+            kind: 'error',
+            productName: ''
+        };
+    }
+    if (outcome.kind === 'nothing-to-hold') return noop;
+    if (outcome.kind === 'held') {
+        var _outcome_productIds;
+        const productIds = (_outcome_productIds = outcome.productIds) != null ? _outcome_productIds : [];
+        return {
+            ok: true,
+            holdKey,
+            // Captures the ids, so an in-request release costs no read. The webhook's
+            // release goes through `releaseStockHold` and reads the index instead.
+            release: ()=>dropStockHold(hostRef, holdKey, productIds)
+        };
+    }
+    return {
+        ok: false,
+        reason: outcome.kind,
+        productName: String((_outcome_productName = outcome.productName) != null ? _outcome_productName : '')
+    };
+}
+/**
+ * Give the units back, given the products to give them back on.
+ *
+ * Bare merge-sets 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 errors for the same
+ * reason — the TTL still releases the units.
+ */ async function dropStockHold(hostRef, holdKey, productIds) {
+    if (!holdKey) return;
+    // ONE try/catch around the whole thing, and not a `.catch()` per call. A
+    // release runs on the refusal paths — it is the last thing a 409 does on its
+    // way out — so anything it throws lands in the CALLER's catch and turns a
+    // clean, deliberate refusal into a 500 the shopper cannot act on. A trailing
+    // `.catch()` does not cover that: a method that is missing or throws
+    // synchronously never returns a promise for one to attach to.
+    //
+    // Swallowed rather than surfaced because the TTL still releases the units.
+    // Tidying up a reservation must not be able to fail the response it is
+    // tidying up after.
+    try {
+        for (const productId of productIds){
+            await hostRef.collection('products').doc(productId).set({
+                stockHolds: {
+                    [holdKey]: firebaseAdmin.firestore.FieldValue.delete()
+                }
+            }, {
+                merge: true
+            });
+        }
+        await hostRef.collection('stockHolds').doc(holdKey).delete();
+    } catch (error) {
+        console.error('Stock hold release failed', holdKey, error);
+    }
+}
+/**
+ * Release a reservation named only by its key — the webhook's door.
+ *
+ * Reads the index written by `holdStock`, so `checkout.session.expired` needs
+ * nothing in the session but `metadata[stockHoldKey]`. A missing index doc is
+ * NOT an error: it means the hold was already released, or the session predates
+ * this deploy, and in both cases there is nothing to do.
+ */ export async function releaseStockHold(hostRef, holdKey) {
+    var _snapshot_get;
+    if (!holdKey) return;
+    const snapshot = await Promise.resolve().then(()=>hostRef.collection('stockHolds').doc(holdKey).get()).catch(()=>null);
+    const productIds = Array.isArray(snapshot == null ? void 0 : (_snapshot_get = snapshot.get) == null ? void 0 : _snapshot_get.call(snapshot, 'productIds')) ? snapshot.get('productIds') : [];
+    await dropStockHold(hostRef, holdKey, productIds);
+}
+
+//# sourceMappingURL=stock-hold.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/stock-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 STOCK (AGL-2356).\n *\n * The I/O half of `model/commerce-stock-holds.ts` — read that file first; it\n * carries the decision this one implements, including why the hold does not\n * touch `inventory` and why a lapsed hold is a release.\n *\n * This is the AGL-2453 promotion-slot shape applied to the one counter that\n * moves real goods, with two differences that matter:\n *\n *   1. **A cart holds N products, so the hold is ONE transaction over all of\n *      them.** Firestore serialises the whole set, so a two-product cart either\n *      reserves both or reserves neither — a partial reservation would charge a\n *      shopper for a basket the store cannot fill, which is the failure this\n *      issue exists to prevent, arriving through the fix.\n *   2. **The release needs an index.** A promotion hold is released against the\n *      one document named in the session metadata; a cart hold spans documents\n *      Stripe never hears about. `hosts/{hostId}/stockHolds/{holdKey}` is\n *      written INSIDE the same transaction as the holds it names, so the index\n *      cannot disagree with the reservations, and the session carries only the\n *      key.\n */\n\n/** One reserved line, already resolved to a real variant. */\nexport interface StockHoldLine {\n  productId: string\n  variantId: string\n  quantity: number\n}\n\n/**\n * Why a reservation could not be taken.\n *\n * - `sold-out` — the units are not there, or are spoken for by another live\n *   checkout. The one refusal a shopper is told about by name.\n * - `missing` — the product document is gone, deleted between the pricing\n *   loop's read and this transaction.\n * - `error` — Firestore refused. The checkout is REFUSED rather than allowed\n *   through unreserved: passing a shopper to Stripe on a reservation that\n *   could not be taken is exactly the defect this file closes.\n */\nexport type StockHoldRefusal = 'sold-out' | 'missing' | 'error'\n\n/**\n * A two-member union with `reason` and `productName` present on BOTH members\n * rather than an intersection, for the reason `PromotionSlotOutcome` records:\n * discriminated-union narrowing does not reach through an intersection under\n * this repo's compiler settings (`strictNullChecks` is off repo-wide), and the\n * intersection form fails to compile at every call site.\n */\nexport type StockHoldOutcome =\n  | {\n      ok: true\n      reason?: undefined\n      productName?: undefined\n      /**\n       * The key the hold was stored under, or `''` when nothing needed\n       * reserving (every line untracked or backorder). Carried in the session\n       * metadata so the webhook can release exactly this reservation; its\n       * absence is what tells the webhook there is nothing to release.\n       */\n      holdKey: string\n      /** Drop the reservation. Best-effort and never throws. */\n      release: () => Promise<void>\n    }\n  | { ok: false; reason: StockHoldRefusal; productName: string }\n\n/**\n * A stable per-attempt hold key — the same rule as `promotionHoldKey`.\n *\n * `claim.stripeKey` when the client sent an Idempotency-Key, so a retry of one\n * attempt re-claims its OWN units rather than being refused by them. When it\n * did not, a fresh random key per request — NOT `String(claim.stripeKey)`,\n * which yields the literal `'null'` and would make every keyless shopper on the\n * site share one reservation, each reading the other's hold as their own retry\n * and both passing a shelf of one.\n */\nexport function stockHoldKey(stripeKey: string | null): string {\n  return stripeKey || `anon-${randomUUID()}`\n}\n\n/** Two lines of one product COMPOUND — a cart holds variants, not products. */\nfunction groupLines(lines: StockHoldLine[]): Map<string, Map<string, number>> {\n  const byProduct = new Map<string, Map<string, number>>()\n  for (const line of lines) {\n    const quantity = Math.round(Number(line?.quantity) || 0)\n    if (!line?.productId || !line?.variantId || quantity <= 0) continue\n    const variants = byProduct.get(line.productId) ?? new Map<string, number>()\n    variants.set(line.variantId, (variants.get(line.variantId) ?? 0) + quantity)\n    byProduct.set(line.productId, variants)\n  }\n  return byProduct\n}\n\n/**\n * Reserve every line, or refuse.\n *\n * The re-check and the write are ONE transaction over the SAME documents, which\n * is the whole fix: the old code read the shelf with a plain `.get()` at\n * session creation and the webhook decremented it minutes later without ever\n * re-asking, so N shoppers all read `inventory: 1` and all passed.\n * `Transaction.get()` takes a lock on each product document, so contending\n * checkouts SERIALISE — the loser re-runs its callback against the winner's\n * committed hold and is refused.\n *\n * Lines with nothing to reserve — an untracked variant, a `backorder` product —\n * write nothing at all, exactly as an uncapped promotion does. A cart made\n * entirely of those returns an empty `holdKey` and the session carries no\n * reservation, so the digital-goods storefront is byte-identical to what it was\n * before this issue.\n */\nexport async function holdStock(options: {\n  firestore: any\n  hostRef: any\n  holdKey: string\n  lines: StockHoldLine[]\n  nowMs?: number\n  /** Label for the failure log; never shown to a shopper. */\n  label: string\n}): Promise<StockHoldOutcome> {\n  const { firestore, hostRef, holdKey, lines, label } = options\n  const nowMs = options.nowMs ?? Date.now()\n  const expiresAtMs = nowMs + CommerceModel.STOCK_HOLD_TTL_MS\n  const byProduct = groupLines(lines)\n  const noop: StockHoldOutcome = {\n    ok: true,\n    holdKey: '',\n    release: async () => undefined,\n  }\n  if (byProduct.size === 0) return noop\n\n  // try/catch and NOT a trailing `.catch()`. A `runTransaction` that is\n  // missing or throws synchronously — a broken client, or a test double that\n  // never modelled one — never returns a promise for a `.catch()` to attach to,\n  // so the throw escapes the guard and becomes a 500 from the caller's own\n  // catch. That is still a refusal and never an unreserved sale, but it is a\n  // refusal this function was supposed to have named.\n  let outcome: any\n  try {\n    outcome = await firestore.runTransaction(async (transaction: any) => {\n      const productIds = [...byProduct.keys()]\n      // ALL READS BEFORE ANY WRITE, which Firestore requires and which is also\n      // what makes the set atomic: every document is locked before the first\n      // decision is taken against any of them.\n      const snapshots = await Promise.all(\n        productIds.map((productId) =>\n          transaction.get(hostRef.collection('products').doc(productId)),\n        ),\n      )\n      const writes: Array<{ ref: any; value: Record<string, unknown> }> = []\n      const heldProductIds: string[] = []\n      for (let index = 0; index < productIds.length; index++) {\n        const productId = productIds[index]\n        const snapshot = snapshots[index]\n        if (!snapshot?.exists) {\n          return { kind: 'missing' as const, productName: '' }\n        }\n        const product = CommerceModel.liftLegacyProduct(snapshot.data() as any)\n        const wanted = byProduct.get(productId) as Map<string, number>\n        const units: Record<string, number> = {}\n        for (const [variantId, quantity] of wanted) {\n          // `== null` is the test, never `!available` — `0` is a legitimate\n          // answer here and `strictNullChecks` is off repo-wide.\n          if (!CommerceModel.stockIsReservable(product, variantId, nowMs)) {\n            continue\n          }\n          if (\n            !CommerceModel.canReserveStock(\n              product,\n              variantId,\n              quantity,\n              nowMs,\n              // This attempt's own prior hold does not stand in its way: a\n              // retry must re-claim what it already reserved, or the second\n              // press of the same button refuses the shopper their own units.\n              holdKey,\n            )\n          ) {\n            return {\n              kind: 'sold-out' as const,\n              productName: String(product?.name ?? ''),\n            }\n          }\n          units[variantId] = quantity\n        }\n        if (Object.keys(units).length === 0) continue\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 this sweep — every read\n        // prunes again — but without it the document grows one dead key per\n        // abandoned checkout, forever, on the one document class in this plugin\n        // that is already the largest.\n        const live = CommerceModel.pruneStockHolds(\n          (snapshot.data() as any)?.stockHolds,\n          nowMs,\n        )\n        const swept: Record<string, unknown> = {}\n        for (const stale of Object.keys(\n          (snapshot.data() as any)?.stockHolds ?? {},\n        )) {\n          if (stale !== holdKey && !live[stale]) {\n            swept[stale] = firebaseAdmin.firestore.FieldValue.delete()\n          }\n        }\n        writes.push({\n          ref: hostRef.collection('products').doc(productId),\n          value: {\n            stockHolds: {\n              ...swept,\n              // A whole-object write for THIS key, not a nested merge: the\n              // retry of an attempt whose cart shrank must not keep reserving\n              // the line it dropped, and a deep merge of `units` would.\n              [holdKey]: { expiresAtMs, units },\n            },\n          },\n        })\n        heldProductIds.push(productId)\n      }\n      if (writes.length === 0) return { kind: 'nothing-to-hold' as const }\n      for (const write of writes) {\n        transaction.set(write.ref, write.value, { merge: true })\n      }\n      // THE RELEASE INDEX, in the same transaction as the reservations it\n      // names. Written last so it can never name a product whose hold did not\n      // commit; read by id (never queried) on `checkout.session.expired` and at\n      // settlement, so it needs no index of its own.\n      transaction.set(\n        hostRef.collection('stockHolds').doc(holdKey),\n        {\n          productIds: heldProductIds,\n          lines: heldProductIds.flatMap((productId) =>\n            [...(byProduct.get(productId) as Map<string, number>)].map(\n              ([variantId, quantity]) => ({ productId, variantId, quantity }),\n            ),\n          ),\n          expiresAtMs,\n          createdAtMs: nowMs,\n        },\n        { merge: false },\n      )\n      return { kind: 'held' as const, productIds: heldProductIds }\n    })\n  } catch (error: unknown) {\n    console.error('Stock hold failed', label, error)\n    outcome = { kind: 'error' as const, productName: '' }\n  }\n\n  if (outcome.kind === 'nothing-to-hold') return noop\n  if (outcome.kind === 'held') {\n    const productIds: string[] = outcome.productIds ?? []\n    return {\n      ok: true,\n      holdKey,\n      // Captures the ids, so an in-request release costs no read. The webhook's\n      // release goes through `releaseStockHold` and reads the index instead.\n      release: () => dropStockHold(hostRef, holdKey, productIds),\n    }\n  }\n  return {\n    ok: false,\n    reason: outcome.kind as StockHoldRefusal,\n    productName: String(outcome.productName ?? ''),\n  }\n}\n\n/**\n * Give the units back, given the products to give them back on.\n *\n * Bare merge-sets 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 errors for the same\n * reason — the TTL still releases the units.\n */\nasync function dropStockHold(\n  hostRef: any,\n  holdKey: string,\n  productIds: string[],\n): Promise<void> {\n  if (!holdKey) return\n  // ONE try/catch around the whole thing, and not a `.catch()` per call. A\n  // release runs on the refusal paths — it is the last thing a 409 does on its\n  // way out — so anything it throws lands in the CALLER's catch and turns a\n  // clean, deliberate refusal into a 500 the shopper cannot act on. A trailing\n  // `.catch()` does not cover that: a method that is missing or throws\n  // synchronously never returns a promise for one to attach to.\n  //\n  // Swallowed rather than surfaced because the TTL still releases the units.\n  // Tidying up a reservation must not be able to fail the response it is\n  // tidying up after.\n  try {\n    for (const productId of productIds) {\n      await hostRef\n        .collection('products')\n        .doc(productId)\n        .set(\n          {\n            stockHolds: {\n              [holdKey]: firebaseAdmin.firestore.FieldValue.delete(),\n            },\n          },\n          { merge: true },\n        )\n    }\n    await hostRef.collection('stockHolds').doc(holdKey).delete()\n  } catch (error: unknown) {\n    console.error('Stock hold release failed', holdKey, error)\n  }\n}\n\n/**\n * Release a reservation named only by its key — the webhook's door.\n *\n * Reads the index written by `holdStock`, so `checkout.session.expired` needs\n * nothing in the session but `metadata[stockHoldKey]`. A missing index doc is\n * NOT an error: it means the hold was already released, or the session predates\n * this deploy, and in both cases there is nothing to do.\n */\nexport async function releaseStockHold(\n  hostRef: any,\n  holdKey: string,\n): Promise<void> {\n  if (!holdKey) return\n  const snapshot = await Promise.resolve()\n    .then(() => hostRef.collection('stockHolds').doc(holdKey).get())\n    .catch(() => null)\n  const productIds: string[] = Array.isArray(snapshot?.get?.('productIds'))\n    ? snapshot.get('productIds')\n    : []\n  await dropStockHold(hostRef, holdKey, productIds)\n}\n"],"names":["CommerceModel","firebaseAdmin","randomUUID","stockHoldKey","stripeKey","groupLines","lines","byProduct","Map","line","variants","quantity","Math","round","Number","productId","variantId","get","set","holdStock","options","outcome","firestore","hostRef","holdKey","label","nowMs","Date","now","expiresAtMs","STOCK_HOLD_TTL_MS","noop","ok","release","undefined","size","runTransaction","transaction","productIds","keys","snapshots","Promise","all","map","collection","doc","writes","heldProductIds","index","length","snapshot","exists","kind","productName","product","liftLegacyProduct","data","wanted","units","stockIsReservable","canReserveStock","String","name","Object","live","pruneStockHolds","stockHolds","swept","stale","FieldValue","delete","push","ref","value","write","merge","flatMap","createdAtMs","error","console","dropStockHold","reason","releaseStockHold","resolve","then","catch","Array","isArray"],"mappings":"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"}

package/src/lib/server/storefront-tax-record.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 StorefrontTaxRow } from './storefront-tax';
+/**
+ * Records one storefront sale's tax, or does nothing when this event is not
+ * one. Returns the row written, for the specs — never for control flow.
+ */
+export declare function recordStorefrontTax(type: string, object: any): Promise<StorefrontTaxRow | null>;