@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/restock-flag.js

@@ -0,0 +1,449 @@
+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";
+/**
+ * Stock left off the shelf by a reversed order (AGL-1797).
+ *
+ * The checkout webhook decrements variant inventory on a sale and NOTHING put
+ * it back — not `refund.ts`, not the lost-dispute handler (AGL-1787) — so a
+ * fully reversed order left the merchant's count permanently one lower than
+ * their shelf, compounding with every return.
+ *
+ * THIS FLAGS. IT DOES NOT RELEASE, and that is the decision.
+ *
+ * "Increment on reversal" is the obvious fix and it is wrong in two of the
+ * three cases it would fire on:
+ *
+ *  - a **returned** item does come back, but only once it is RECEIVED, and no
+ *    fulfilment event records receipt — `OrderFulfillment` has no returned
+ *    state, so the moment an automatic increment would need does not exist;
+ *  - a **refund with no return** (goodwill, damaged, lost in post) leaves the
+ *    goods gone. Incrementing there invents inventory the merchant does not
+ *    have, and that is strictly worse than the bug it replaces: the bug
+ *    under-counts and refuses a sale that could have been made, while the
+ *    "fix" over-counts and TAKES a sale that cannot be filled;
+ *  - a **chargeback** is the clearest do-not-restock case there is. The shopper
+ *    kept the item and took the money, and `product_not_received` — the most
+ *    common reason code — asserts the goods shipped.
+ *
+ * The quantities are not always knowable on a partial. A refund requested as an
+ * AMOUNT selects no line — "$17 of a $62 order" names nothing — and that is
+ * recorded rather than papered over: `quantity` is at most the units the line
+ * sold, capped to what the count actually gave up, and `fullyReversed` says
+ * whether that bound is a tight one.
+ *
+ * A refund that NAMES ITS LINES is scoped to them (AGL-2325). When this was
+ * written no reversal recorded which lines it covered; AGL-2454 changed that,
+ * and `refund.ts` commits `refundedLineItemIds` with the money, before this
+ * flag re-reads the order. A one-line refund on a three-line order that still
+ * asked about all three was the same over-statement this module already fixed
+ * on the units axis, arriving by a door that opened afterwards. See
+ * `reversalLineScope` for the three cases that stay whole-order.
+ *
+ * So the merchant is asked. They are the only party who knows whether the
+ * goods came back, and by the time they read this they know it.
+ *
+ * WHAT IS DELIBERATELY NOT BUILT HERE. No stock writer and no
+ * `InventoryAdjustment` row: the products hub's "Adjust stock" already writes
+ * the variant counts and logs the adjustment with a reason, so a second writer
+ * for one number would be a re-implementation, not an extension. And an
+ * adjustment row for stock that has NOT moved would corrupt the very ledger
+ * that hub renders as history. This writes the question; the existing action
+ * answers it.
+ *
+ * WHERE THE MERCHANT SEES IT. The order timeline, which the console order
+ * dialog already renders, so this needs no UI change to be visible at all. The
+ * `restockCheck` record beside it is the structured half a badge and a
+ * one-click action read; that console work is filed, not smuggled in.
+ *
+ * NO NOTIFICATION. A refund is initiated BY an admin in the console, so telling
+ * them about their own click is noise, and the chargeback door already sends a
+ * manager notification for the dispute itself — a second one for the same event
+ * would train them to ignore both.
+ *
+ * ONLY WHAT THE SALE DECREMENTED IS FLAGGED. Tracking lives on the product
+ * variant, not the order line, so this reads the products and applies the sale
+ * path's own test (`variant.inventory != null`). A store that tracks no stock
+ * therefore gets NO flag rather than a prompt it can never act on, which is the
+ * difference between a signal and noise. It costs a handful of reads on an
+ * event as rare as a reversal.
+ *
+ * The `inventoryAdjustments` ledger was the tempting shortcut for SELECTING the
+ * lines and it is not usable for that: the buy-now/subscription sale path
+ * decrements stock without writing a row (`billing-webhook.ts`, the
+ * `productId` branch), so the ledger has holes the order's own line items do
+ * not. The lines are still chosen from the order.
+ *
+ * IT IS READ TO BOUND THE NUMBER, THOUGH (AGL-2325), and the holes are exactly
+ * why that is safe in this direction. `line.quantity` is the units the line
+ * SOLD, and on a backorder product the inventory floor absorbed part or all of
+ * the decrement, so the prompt named units the count never gave up. The sale
+ * rows' `appliedDelta` says how many it did, and only pairs the ledger
+ * DESCRIBES are capped — a line it is silent about keeps the upper bound, so a
+ * hole costs an over-stated question rather than stock stranded off the shelf.
+ * `saleReleaseCaps` and `capRestockLines` are shared with the cancellation
+ * writer, so what this ASKS and what that RETURNS cannot drift apart.
+ *
+ * FAILURES ARE SWALLOWED, like `recordContactRefund`'s. The money has already
+ * moved and the order already records it; a flag that cannot be written must
+ * not fail a refund that has left the merchant's account.
+ */ export async function flagOrderRestock(options) {
+    try {
+        var _snapshot_data, _order_timeline;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(options.hostId);
+        const orderRef = hostRef.collection('orders').doc(options.orderId);
+        const snapshot = await orderRef.get();
+        if (!snapshot.exists) return;
+        const order = CommerceModel.liftLegacyOrder((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {});
+        // Once per open question — but "the question" is now a set of LINES, not
+        // the order (AGL-2325). A second partial that withdraws a line the open
+        // prompt already names adds nothing the merchant does not have; one that
+        // withdraws a DIFFERENT line is a genuinely new question, and swallowing it
+        // left those units off the shelf with nothing recording that they had gone.
+        // A check they already ANSWERED is a new question either way, because
+        // stock moved since.
+        const open = order.restockCheck && !order.restockCheck.resolution ? order.restockCheck : null;
+        const covered = open ? openCheckCoverage(open) : null;
+        // An open question that names no lines cannot be told apart from one that
+        // names these, so it stands. See `openCheckCoverage`.
+        if (open && covered === null) return;
+        // AN ORDER THAT WAS CANCELLED HAS NO RESTOCK QUESTION LEFT (AGL-2149).
+        // Until `cancelled: ['refunded']` this was unreachable — a cancelled order
+        // could not refund at all — and reaching it now would be the double-count
+        // this flag exists to avoid: `cancel-order.ts` already put the units back
+        // and wrote the `reason: 'cancellation'` ledger rows, so a fresh "N units
+        // may need restocking" prompt on top of that invites the merchant to
+        // restock the same units a SECOND time. (`cancel-order.ts` handles the
+        // opposite order of events — refund first, then cancel — by resolving the
+        // open check with what it actually did.)
+        //
+        // Read from the TIMELINE, not from `order.status`: a full refund flips the
+        // order to `refunded` in the transaction above this call, so by the time
+        // the flag runs the cancellation is no longer the current status — but the
+        // event it stamped is still there, and it is the durable record of the
+        // release. A partial refund would leave `cancelled` standing and a status
+        // test would catch that one case and silently miss the full one.
+        //
+        // The cases where the cancel released nothing are covered by the same skip:
+        // a `pending` cancel and a POS card order with no `sale` ledger row never
+        // decremented anything, so nothing is missing from the shelf to ask about.
+        if (((_order_timeline = order.timeline) != null ? _order_timeline : []).some((event)=>event.event === 'cancelled')) {
+            return;
+        }
+        // WHICH LINES THIS REVERSAL TOOK BACK, plus the ones an open question
+        // already names (AGL-2325). Extending rather than replacing is what keeps
+        // ONE prompt on the order: a second partial that withdraws a new line
+        // re-asks the whole standing question, so the merchant answers once and
+        // the units of the earlier line are not dropped on the way.
+        const scope = reversalLineScope(order, options.kind, options.closedTheOrder);
+        const extended = scope && covered ? new Set([
+            ...scope,
+            ...covered
+        ]) : scope;
+        const { lines: allLines } = await resolveTrackedRestockLines(hostRef, order, // A product this flag cannot read drops out rather than failing the
+        // flag: the money has already moved. The cancellation writer (AGL-1808)
+        // passes its TRANSACTION's read instead, because a line it silently
+        // dropped would leave stock off the shelf it just promised to return.
+        (ref)=>ref.get().catch(()=>null));
+        const lines = extended == null ? allLines : allLines.filter((line)=>extended.has(line.lineIndex));
+        // Nothing was ever decremented for this order, so nothing is missing from
+        // the shelf. Writing a prompt here would be the noise that teaches a
+        // merchant to ignore the ones that matter.
+        if (lines.length === 0) return;
+        // THE PROMPT COUNTS WHAT THE SHELF ACTUALLY LOST, NOT WHAT THE SALE SOLD
+        // (AGL-2325). `line.quantity` is the units the line sold, and on a
+        // BACKORDER product the inventory floor absorbed part or all of the
+        // decrement — stock 0, three units sell, the count stays 0 — so the
+        // merchant was asked to restock units the count never gave up. The same
+        // `appliedDelta` treatment AGL-2149 gave the cancellation cap, from the
+        // same ledger rows and through the same shared helpers, so the question
+        // this asks and the units a cancellation would return cannot disagree.
+        //
+        // The under-prompt this could have caused is what the cap rule already
+        // rules out: only pairs the ledger DESCRIBES are capped, so a line it says
+        // nothing about keeps the old upper bound rather than being zeroed by a
+        // ledger with holes in it. A read that FAILS degrades the same way, to no
+        // caps at all — an over-stated prompt is a question the merchant can
+        // answer, a missing one is stock left off the shelf for good.
+        const capped = capRestockLines(lines, await readSaleReleaseCaps(hostRef, options.orderId));
+        // Every tracked line was absorbed by the floor, so nothing is missing from
+        // the shelf and there is no question to ask.
+        if (capped.length === 0) return;
+        // Asked of the CAPPED lines, so a line the floor absorbed is not counted
+        // as something the open prompt is missing — it would re-flag on every
+        // reversal forever.
+        const asking = new Set(capped.map((line)=>line.lineIndex));
+        if (covered && alreadyCovered(asking, covered)) return;
+        const units = capped.reduce((sum, line)=>sum + line.quantity, 0);
+        const flaggedAtMs = Date.now();
+        const record = {
+            kind: options.kind,
+            lines: capped,
+            units,
+            fullyReversed: options.closedTheOrder,
+            flaggedAtMs
+        };
+        await firestore.runTransaction(async (transaction)=>{
+            var _fresh_data;
+            const fresh = await transaction.get(orderRef);
+            if (!fresh.exists) return;
+            const current = CommerceModel.liftLegacyOrder((_fresh_data = fresh.data()) != null ? _fresh_data : {});
+            // Re-asked inside the transaction that writes it, so two reversals
+            // settling at once cannot both flag — the same mechanism AGL-1754 used to
+            // make its status flip observable exactly once, and the reason this is
+            // not a bare `set(…, { merge: true })`. Re-asked in the same LINE terms
+            // as the check above (AGL-2325): a concurrent flag that already covers
+            // every line this one would ask about has asked the question, while one
+            // covering a different line leaves this one still worth writing.
+            const currentOpen = current.restockCheck && !current.restockCheck.resolution ? current.restockCheck : null;
+            if (currentOpen) {
+                const currentCoverage = openCheckCoverage(currentOpen);
+                if (currentCoverage === null || alreadyCovered(asking, currentCoverage)) {
+                    return;
+                }
+            }
+            // `update()`, and the whole `restockCheck` map at that. A merge recurses,
+            // so a re-flag after a merchant answered would inherit the previous
+            // `resolution`/`resolvedAtMs` and read as already handled while asking a
+            // brand-new question. `update()` replaces a nested map wholesale, which
+            // is the semantics this wants, and the transaction has just proven the
+            // document exists so it cannot `NOT_FOUND`.
+            transaction.update(orderRef, {
+                restockCheck: record,
+                timeline: CommerceModel.appendOrderEvent(current, 'restock-check', `${units} ${units === 1 ? 'unit' : 'units'} may need restocking` + (options.kind === 'chargeback' ? ' — the shopper kept the goods unless they came back' : '') + (options.closedTheOrder ? '' : ' (partial reversal, at most)'), flaggedAtMs)
+            });
+        });
+    } catch (error) {
+        console.error('flagOrderRestock failed', error);
+    }
+}
+/**
+ * The order lines THIS reversal took back, or `null` for "all of them"
+ * (AGL-2325).
+ *
+ * When AGL-2325 was filed a refund was an AMOUNT and nothing else — "$17 of a
+ * $62 order" selected no line — so naming every tracked line and labelling the
+ * total an upper bound was the only honest answer available. AGL-2454 ended
+ * that: `refund.ts` records `refundedLineItemIds` in the same transaction that
+ * moves the money, and it commits before this flag re-reads the order. A
+ * one-line refund on a three-line order that still asks about all three is the
+ * same over-statement this issue is about, arriving by a door that opened after
+ * it was written.
+ *
+ * `null` — the whole order — for the three cases where a line list is not the
+ * scope:
+ *
+ *  - a **chargeback** reverses the entire payment, so an earlier line-scoped
+ *    partial must not narrow it to the one line that admin picked;
+ *  - a refund that **closed the order** took everything back, however the
+ *    individual attempts were requested;
+ *  - a refund by **amount alone**, which names no line. That is the pre-AGL-2454
+ *    shape and still the shape of one requested without a line selection, and
+ *    it degrades to the upper bound this has always carried rather than to
+ *    silence.
+ */ function reversalLineScope(order, kind, closedTheOrder) {
+    var _order_refundedLineItemIds;
+    if (kind === 'chargeback' || closedTheOrder) return null;
+    const withdrawn = new Set();
+    for (const value of (_order_refundedLineItemIds = order.refundedLineItemIds) != null ? _order_refundedLineItemIds : []){
+        const index = Math.round(Number(value));
+        if (Number.isFinite(index) && index >= 0) withdrawn.add(index);
+    }
+    return withdrawn.size > 0 ? withdrawn : null;
+}
+/**
+ * Which order lines an OPEN restock question already covers (AGL-2325), or
+ * `null` when that cannot be told.
+ *
+ * `null` for a check written before `lineIndex` existed, and it is read as
+ * "covers the whole order" by the one caller — suppressing, which is the
+ * behaviour those checks were written under and the safe way to be wrong: a
+ * duplicate prompt for units already asked about would teach a merchant to
+ * ignore the ones that matter.
+ */ function openCheckCoverage(check) {
+    var _check_lines;
+    const covered = new Set();
+    for (const line of (_check_lines = check.lines) != null ? _check_lines : []){
+        if (line.lineIndex == null) return null;
+        covered.add(line.lineIndex);
+    }
+    return covered;
+}
+/** Does the open question already cover every line this reversal names? */ function alreadyCovered(scope, covered) {
+    for (const index of scope)if (!covered.has(index)) return false;
+    return true;
+}
+/**
+ * This order's sale-release caps, read outside any transaction (AGL-2325).
+ *
+ * SWALLOWS, like everything else on this path: the money has already moved,
+ * and an empty map means "cap nothing", which leaves the prompt at the upper
+ * bound it has always carried. One equality filter, so the automatic
+ * single-field index answers it; the `reason` test runs here, over the handful
+ * of rows one order has — the same query shape the cancellation writer runs
+ * inside its transaction.
+ */ async function readSaleReleaseCaps(hostRef, orderId) {
+    try {
+        const rows = await hostRef.collection('inventoryAdjustments').where('orderId', '==', orderId).get();
+        return saleReleaseCaps(rows.docs.filter((row)=>row.get('reason') === 'sale'));
+    } catch (error) {
+        console.error('readSaleReleaseCaps failed', error);
+        return new Map();
+    }
+}
+/**
+ * Key for one product+variant pair in a release-cap map.
+ *
+ * The separator is U+0000 written as an ESCAPE, not as a raw byte (AGL-2355).
+ * Emitted literally it made `file(1)` call the source `data`, so grep skipped
+ * the whole file as binary and an AGL-2320 sweep missed a call site in it.
+ * Same character at runtime. NUL is still the right separator: it cannot occur
+ * in a Firestore document id, so no pair can collide.
+ */ export const restockCapKey = (productId, variantId)=>`${productId}\u0000${variantId}`;
+/**
+ * How many units of each product+variant a sale ACTUALLY took off the shelf,
+ * read from that order's `reason: 'sale'` ledger rows (AGL-2149).
+ *
+ * The variant inventory writer floors at zero, and that floor silently absorbs
+ * the overshoot on a BACKORDER product: stock 0, `canPurchase` admits the sale
+ * because the policy says to, three units sell, `Math.max(0, 0 + -3)` leaves
+ * the count at 0. The rows carry both numbers for exactly this — `delta` stays
+ * the units SOLD, which is the merchant's history, and `appliedDelta` says how
+ * many the count could give up.
+ *
+ * The writer is deliberately NOT named here: `stock-decrement-race.spec.ts`
+ * sweeps every server source for that identifier to prove no file outside its
+ * allowlist hand-rolls a stock write, and it matches the bare name, so even a
+ * comment mentioning it would read as a call site. This module writes no stock
+ * at all — it writes the question.
+ *
+ * Shared by the cancellation writer, which uses it to bound how much stock
+ * goes back, and by the restock flag, which uses it to bound what it CLAIMS
+ * went missing (AGL-2325). Extracted rather than copied: the two must not
+ * drift, because a flag that names more units than the cancellation would
+ * return is the double-count both of them exist to avoid.
+ */ export function saleReleaseCaps(saleRows) {
+    const caps = new Map();
+    for (const row of saleRows){
+        var _row_get, _row_get1, _ref, _row_get2, _caps_get;
+        const productId = String((_row_get = row.get('productId')) != null ? _row_get : '');
+        const variantId = String((_row_get1 = row.get('variantId')) != null ? _row_get1 : '');
+        if (!productId || !variantId) continue;
+        const moved = Number((_ref = (_row_get2 = row.get('appliedDelta')) != null ? _row_get2 : row.get('delta')) != null ? _ref : 0);
+        // Sale rows are negative; the cap is how many units left the shelf.
+        caps.set(restockCapKey(productId, variantId), ((_caps_get = caps.get(restockCapKey(productId, variantId))) != null ? _caps_get : 0) + Math.max(0, -moved));
+    }
+    return caps;
+}
+/**
+ * Lines narrowed to what the count actually gave up, dropping any that gave up
+ * nothing (AGL-2149, AGL-2325).
+ *
+ * ONLY PAIRS THE LEDGER DESCRIBES ARE CAPPED, and that asymmetry is the whole
+ * safety argument. A pair with no row is left at the units it sold, which is
+ * what keeps the pre-AGL-1807 draft links — decremented with no row at all —
+ * and the buy-now path from being silently zeroed by a ledger that has holes
+ * in it. So an absent ledger degrades to the old upper bound rather than to
+ * saying nothing moved.
+ *
+ * The budget is consumed as it is spent, so two lines of the same
+ * product+variant share one rather than each claiming it whole. Takes a COPY,
+ * so a caller may reuse the map it passed.
+ */ export function capRestockLines(lines, caps) {
+    const budgets = new Map(caps);
+    const capped = [];
+    for (const line of lines){
+        const key = restockCapKey(line.productId, line.variantId);
+        const budget = budgets.get(key);
+        const quantity = budget == null ? line.quantity : Math.min(line.quantity, budget);
+        if (budget != null) budgets.set(key, budget - quantity);
+        if (quantity <= 0) continue;
+        capped.push(_extends({}, line, {
+            quantity
+        }));
+    }
+    return capped;
+}
+/**
+ * The order's lines whose stock the sale actually took off the shelf.
+ *
+ * The test is the sale path's own — `variant.inventory != null` on the variant
+ * that sold — read from the product as it stands NOW, because that is the
+ * count a restock would be applied to. A product deleted since the sale, or a
+ * variant removed from it, therefore drops out: there is no number left to put
+ * anything back into.
+ *
+ * Products are read once each, so a three-line order of the same product costs
+ * one read rather than three.
+ *
+ * `read` is the caller's, and the choice is not cosmetic (AGL-1808): the flag
+ * passes a swallowing `get()` because a product it cannot read must not fail a
+ * refund that already moved, while the cancellation writer passes its
+ * TRANSACTION's `get` so every product it is about to increment is read under
+ * the same transaction that writes it — and so a read failure aborts rather
+ * than quietly shortening the list.
+ */ export async function resolveTrackedRestockLines(hostRef, order, read) {
+    var _order_lineItems;
+    const products = new Map();
+    const lines = [];
+    const orderLines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    for(let lineIndex = 0; lineIndex < orderLines.length; lineIndex += 1){
+        var _ref, _ref1, _line_variantId, _product_variants;
+        var _product_variants_, _product_variants1;
+        const line = orderLines[lineIndex];
+        const productId = String((_ref = line == null ? void 0 : line.productId) != null ? _ref : '');
+        const quantity = Math.round(Number((_ref1 = line == null ? void 0 : line.quantity) != null ? _ref1 : 0));
+        if (!productId || !(quantity > 0)) continue;
+        // Firestore reserves `__…__` document ids and `.doc()` throws on one
+        // SYNCHRONOUSLY, which no `.catch()` on the returned promise would see. A
+        // single corrupt line item must not cost the whole flag.
+        if (/^__.*__$/.test(productId)) continue;
+        if (!products.has(productId)) {
+            var _snapshot_data;
+            const snapshot = await read(hostRef.collection('products').doc(productId));
+            products.set(productId, (snapshot == null ? void 0 : snapshot.exists) ? CommerceModel.liftLegacyProduct((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}) : null);
+        }
+        const product = products.get(productId);
+        if (!product) continue;
+        const variantId = (_line_variantId = line.variantId) != null ? _line_variantId : (_product_variants1 = product.variants) == null ? void 0 : (_product_variants_ = _product_variants1[0]) == null ? void 0 : _product_variants_.id;
+        const tracked = ((_product_variants = product.variants) != null ? _product_variants : []).some((variant)=>variant.id === variantId && variant.inventory != null);
+        if (!variantId || !tracked) continue;
+        lines.push(_extends({
+            productId,
+            variantId,
+            quantity,
+            lineIndex
+        }, line.name ? {
+            name: line.name
+        } : {}, line.variantLabel ? {
+            variantLabel: line.variantLabel
+        } : {}));
+    }
+    const resolved = new Map();
+    for (const line of lines){
+        const product = products.get(line.productId);
+        if (product) resolved.set(line.productId, product);
+    }
+    return {
+        lines,
+        products: resolved
+    };
+}
+
+//# sourceMappingURL=restock-flag.js.map

package/src/lib/server/restock-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/restock-flag.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'\n\n/**\n * Stock left off the shelf by a reversed order (AGL-1797).\n *\n * The checkout webhook decrements variant inventory on a sale and NOTHING put\n * it back — not `refund.ts`, not the lost-dispute handler (AGL-1787) — so a\n * fully reversed order left the merchant's count permanently one lower than\n * their shelf, compounding with every return.\n *\n * THIS FLAGS. IT DOES NOT RELEASE, and that is the decision.\n *\n * \"Increment on reversal\" is the obvious fix and it is wrong in two of the\n * three cases it would fire on:\n *\n *  - a **returned** item does come back, but only once it is RECEIVED, and no\n *    fulfilment event records receipt — `OrderFulfillment` has no returned\n *    state, so the moment an automatic increment would need does not exist;\n *  - a **refund with no return** (goodwill, damaged, lost in post) leaves the\n *    goods gone. Incrementing there invents inventory the merchant does not\n *    have, and that is strictly worse than the bug it replaces: the bug\n *    under-counts and refuses a sale that could have been made, while the\n *    \"fix\" over-counts and TAKES a sale that cannot be filled;\n *  - a **chargeback** is the clearest do-not-restock case there is. The shopper\n *    kept the item and took the money, and `product_not_received` — the most\n *    common reason code — asserts the goods shipped.\n *\n * The quantities are not always knowable on a partial. A refund requested as an\n * AMOUNT selects no line — \"$17 of a $62 order\" names nothing — and that is\n * recorded rather than papered over: `quantity` is at most the units the line\n * sold, capped to what the count actually gave up, and `fullyReversed` says\n * whether that bound is a tight one.\n *\n * A refund that NAMES ITS LINES is scoped to them (AGL-2325). When this was\n * written no reversal recorded which lines it covered; AGL-2454 changed that,\n * and `refund.ts` commits `refundedLineItemIds` with the money, before this\n * flag re-reads the order. A one-line refund on a three-line order that still\n * asked about all three was the same over-statement this module already fixed\n * on the units axis, arriving by a door that opened afterwards. See\n * `reversalLineScope` for the three cases that stay whole-order.\n *\n * So the merchant is asked. They are the only party who knows whether the\n * goods came back, and by the time they read this they know it.\n *\n * WHAT IS DELIBERATELY NOT BUILT HERE. No stock writer and no\n * `InventoryAdjustment` row: the products hub's \"Adjust stock\" already writes\n * the variant counts and logs the adjustment with a reason, so a second writer\n * for one number would be a re-implementation, not an extension. And an\n * adjustment row for stock that has NOT moved would corrupt the very ledger\n * that hub renders as history. This writes the question; the existing action\n * answers it.\n *\n * WHERE THE MERCHANT SEES IT. The order timeline, which the console order\n * dialog already renders, so this needs no UI change to be visible at all. The\n * `restockCheck` record beside it is the structured half a badge and a\n * one-click action read; that console work is filed, not smuggled in.\n *\n * NO NOTIFICATION. A refund is initiated BY an admin in the console, so telling\n * them about their own click is noise, and the chargeback door already sends a\n * manager notification for the dispute itself — a second one for the same event\n * would train them to ignore both.\n *\n * ONLY WHAT THE SALE DECREMENTED IS FLAGGED. Tracking lives on the product\n * variant, not the order line, so this reads the products and applies the sale\n * path's own test (`variant.inventory != null`). A store that tracks no stock\n * therefore gets NO flag rather than a prompt it can never act on, which is the\n * difference between a signal and noise. It costs a handful of reads on an\n * event as rare as a reversal.\n *\n * The `inventoryAdjustments` ledger was the tempting shortcut for SELECTING the\n * lines and it is not usable for that: the buy-now/subscription sale path\n * decrements stock without writing a row (`billing-webhook.ts`, the\n * `productId` branch), so the ledger has holes the order's own line items do\n * not. The lines are still chosen from the order.\n *\n * IT IS READ TO BOUND THE NUMBER, THOUGH (AGL-2325), and the holes are exactly\n * why that is safe in this direction. `line.quantity` is the units the line\n * SOLD, and on a backorder product the inventory floor absorbed part or all of\n * the decrement, so the prompt named units the count never gave up. The sale\n * rows' `appliedDelta` says how many it did, and only pairs the ledger\n * DESCRIBES are capped — a line it is silent about keeps the upper bound, so a\n * hole costs an over-stated question rather than stock stranded off the shelf.\n * `saleReleaseCaps` and `capRestockLines` are shared with the cancellation\n * writer, so what this ASKS and what that RETURNS cannot drift apart.\n *\n * FAILURES ARE SWALLOWED, like `recordContactRefund`'s. The money has already\n * moved and the order already records it; a flag that cannot be written must\n * not fail a refund that has left the merchant's account.\n */\nexport async function flagOrderRestock(options: {\n  hostId: string\n  orderId: string\n  /** Which door the money left by. Only the wording differs. */\n  kind: 'refund' | 'chargeback'\n  /**\n   * True only for the write that moved the order INTO `refunded` — the same\n   * signal `recordContactRefund` takes, decided by the caller from the status\n   * transition it made rather than from the total it read, because\n   * `fullyRefunded` is not a once-only signal (AGL-1754).\n   */\n  closedTheOrder: boolean\n}): Promise<void> {\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(options.hostId)\n    const orderRef = hostRef.collection('orders').doc(options.orderId)\n    const snapshot = await orderRef.get()\n    if (!snapshot.exists) return\n    const order = CommerceModel.liftLegacyOrder(\n      (snapshot.data() ?? {}) as never,\n    )\n    // Once per open question — but \"the question\" is now a set of LINES, not\n    // the order (AGL-2325). A second partial that withdraws a line the open\n    // prompt already names adds nothing the merchant does not have; one that\n    // withdraws a DIFFERENT line is a genuinely new question, and swallowing it\n    // left those units off the shelf with nothing recording that they had gone.\n    // A check they already ANSWERED is a new question either way, because\n    // stock moved since.\n    const open =\n      order.restockCheck && !order.restockCheck.resolution\n        ? order.restockCheck\n        : null\n    const covered = open ? openCheckCoverage(open) : null\n    // An open question that names no lines cannot be told apart from one that\n    // names these, so it stands. See `openCheckCoverage`.\n    if (open && covered === null) return\n    // AN ORDER THAT WAS CANCELLED HAS NO RESTOCK QUESTION LEFT (AGL-2149).\n    // Until `cancelled: ['refunded']` this was unreachable — a cancelled order\n    // could not refund at all — and reaching it now would be the double-count\n    // this flag exists to avoid: `cancel-order.ts` already put the units back\n    // and wrote the `reason: 'cancellation'` ledger rows, so a fresh \"N units\n    // may need restocking\" prompt on top of that invites the merchant to\n    // restock the same units a SECOND time. (`cancel-order.ts` handles the\n    // opposite order of events — refund first, then cancel — by resolving the\n    // open check with what it actually did.)\n    //\n    // Read from the TIMELINE, not from `order.status`: a full refund flips the\n    // order to `refunded` in the transaction above this call, so by the time\n    // the flag runs the cancellation is no longer the current status — but the\n    // event it stamped is still there, and it is the durable record of the\n    // release. A partial refund would leave `cancelled` standing and a status\n    // test would catch that one case and silently miss the full one.\n    //\n    // The cases where the cancel released nothing are covered by the same skip:\n    // a `pending` cancel and a POS card order with no `sale` ledger row never\n    // decremented anything, so nothing is missing from the shelf to ask about.\n    if ((order.timeline ?? []).some((event) => event.event === 'cancelled')) {\n      return\n    }\n\n    // WHICH LINES THIS REVERSAL TOOK BACK, plus the ones an open question\n    // already names (AGL-2325). Extending rather than replacing is what keeps\n    // ONE prompt on the order: a second partial that withdraws a new line\n    // re-asks the whole standing question, so the merchant answers once and\n    // the units of the earlier line are not dropped on the way.\n    const scope = reversalLineScope(order, options.kind, options.closedTheOrder)\n    const extended = scope && covered ? new Set([...scope, ...covered]) : scope\n    const { lines: allLines } = await resolveTrackedRestockLines(\n      hostRef,\n      order,\n      // A product this flag cannot read drops out rather than failing the\n      // flag: the money has already moved. The cancellation writer (AGL-1808)\n      // passes its TRANSACTION's read instead, because a line it silently\n      // dropped would leave stock off the shelf it just promised to return.\n      (ref) => ref.get().catch(() => null),\n    )\n    const lines =\n      extended == null\n        ? allLines\n        : allLines.filter((line) => extended.has(line.lineIndex))\n    // Nothing was ever decremented for this order, so nothing is missing from\n    // the shelf. Writing a prompt here would be the noise that teaches a\n    // merchant to ignore the ones that matter.\n    if (lines.length === 0) return\n\n    // THE PROMPT COUNTS WHAT THE SHELF ACTUALLY LOST, NOT WHAT THE SALE SOLD\n    // (AGL-2325). `line.quantity` is the units the line sold, and on a\n    // BACKORDER product the inventory floor absorbed part or all of the\n    // decrement — stock 0, three units sell, the count stays 0 — so the\n    // merchant was asked to restock units the count never gave up. The same\n    // `appliedDelta` treatment AGL-2149 gave the cancellation cap, from the\n    // same ledger rows and through the same shared helpers, so the question\n    // this asks and the units a cancellation would return cannot disagree.\n    //\n    // The under-prompt this could have caused is what the cap rule already\n    // rules out: only pairs the ledger DESCRIBES are capped, so a line it says\n    // nothing about keeps the old upper bound rather than being zeroed by a\n    // ledger with holes in it. A read that FAILS degrades the same way, to no\n    // caps at all — an over-stated prompt is a question the merchant can\n    // answer, a missing one is stock left off the shelf for good.\n    const capped = capRestockLines(\n      lines,\n      await readSaleReleaseCaps(hostRef, options.orderId),\n    )\n    // Every tracked line was absorbed by the floor, so nothing is missing from\n    // the shelf and there is no question to ask.\n    if (capped.length === 0) return\n\n    // Asked of the CAPPED lines, so a line the floor absorbed is not counted\n    // as something the open prompt is missing — it would re-flag on every\n    // reversal forever.\n    const asking = new Set(capped.map((line) => line.lineIndex))\n    if (covered && alreadyCovered(asking, covered)) return\n\n    const units = capped.reduce((sum, line) => sum + line.quantity, 0)\n    const flaggedAtMs = Date.now()\n    const record: CommerceModel.OrderRestockCheck = {\n      kind: options.kind,\n      lines: capped,\n      units,\n      fullyReversed: options.closedTheOrder,\n      flaggedAtMs,\n    }\n    await firestore.runTransaction(async (transaction) => {\n      const fresh = await transaction.get(orderRef)\n      if (!fresh.exists) return\n      const current = CommerceModel.liftLegacyOrder(\n        (fresh.data() ?? {}) as never,\n      )\n      // Re-asked inside the transaction that writes it, so two reversals\n      // settling at once cannot both flag — the same mechanism AGL-1754 used to\n      // make its status flip observable exactly once, and the reason this is\n      // not a bare `set(…, { merge: true })`. Re-asked in the same LINE terms\n      // as the check above (AGL-2325): a concurrent flag that already covers\n      // every line this one would ask about has asked the question, while one\n      // covering a different line leaves this one still worth writing.\n      const currentOpen =\n        current.restockCheck && !current.restockCheck.resolution\n          ? current.restockCheck\n          : null\n      if (currentOpen) {\n        const currentCoverage = openCheckCoverage(currentOpen)\n        if (\n          currentCoverage === null ||\n          alreadyCovered(asking, currentCoverage)\n        ) {\n          return\n        }\n      }\n      // `update()`, and the whole `restockCheck` map at that. A merge recurses,\n      // so a re-flag after a merchant answered would inherit the previous\n      // `resolution`/`resolvedAtMs` and read as already handled while asking a\n      // brand-new question. `update()` replaces a nested map wholesale, which\n      // is the semantics this wants, and the transaction has just proven the\n      // document exists so it cannot `NOT_FOUND`.\n      transaction.update(orderRef, {\n        restockCheck: record,\n        timeline: CommerceModel.appendOrderEvent(\n          current,\n          'restock-check',\n          `${units} ${units === 1 ? 'unit' : 'units'} may need restocking` +\n            (options.kind === 'chargeback'\n              ? ' — the shopper kept the goods unless they came back'\n              : '') +\n            (options.closedTheOrder ? '' : ' (partial reversal, at most)'),\n          flaggedAtMs,\n        ),\n      })\n    })\n  } catch (error) {\n    console.error('flagOrderRestock failed', error)\n  }\n}\n\n/**\n * The order lines THIS reversal took back, or `null` for \"all of them\"\n * (AGL-2325).\n *\n * When AGL-2325 was filed a refund was an AMOUNT and nothing else — \"$17 of a\n * $62 order\" selected no line — so naming every tracked line and labelling the\n * total an upper bound was the only honest answer available. AGL-2454 ended\n * that: `refund.ts` records `refundedLineItemIds` in the same transaction that\n * moves the money, and it commits before this flag re-reads the order. A\n * one-line refund on a three-line order that still asks about all three is the\n * same over-statement this issue is about, arriving by a door that opened after\n * it was written.\n *\n * `null` — the whole order — for the three cases where a line list is not the\n * scope:\n *\n *  - a **chargeback** reverses the entire payment, so an earlier line-scoped\n *    partial must not narrow it to the one line that admin picked;\n *  - a refund that **closed the order** took everything back, however the\n *    individual attempts were requested;\n *  - a refund by **amount alone**, which names no line. That is the pre-AGL-2454\n *    shape and still the shape of one requested without a line selection, and\n *    it degrades to the upper bound this has always carried rather than to\n *    silence.\n */\nfunction reversalLineScope(\n  order: CommerceModel.HostOrder,\n  kind: 'refund' | 'chargeback',\n  closedTheOrder: boolean,\n): Set<number> | null {\n  if (kind === 'chargeback' || closedTheOrder) return null\n  const withdrawn = new Set<number>()\n  for (const value of order.refundedLineItemIds ?? []) {\n    const index = Math.round(Number(value))\n    if (Number.isFinite(index) && index >= 0) withdrawn.add(index)\n  }\n  return withdrawn.size > 0 ? withdrawn : null\n}\n\n/**\n * Which order lines an OPEN restock question already covers (AGL-2325), or\n * `null` when that cannot be told.\n *\n * `null` for a check written before `lineIndex` existed, and it is read as\n * \"covers the whole order\" by the one caller — suppressing, which is the\n * behaviour those checks were written under and the safe way to be wrong: a\n * duplicate prompt for units already asked about would teach a merchant to\n * ignore the ones that matter.\n */\nfunction openCheckCoverage(\n  check: CommerceModel.OrderRestockCheck,\n): Set<number> | null {\n  const covered = new Set<number>()\n  for (const line of check.lines ?? []) {\n    if (line.lineIndex == null) return null\n    covered.add(line.lineIndex)\n  }\n  return covered\n}\n\n/** Does the open question already cover every line this reversal names? */\nfunction alreadyCovered(\n  scope: ReadonlySet<number>,\n  covered: ReadonlySet<number>,\n): boolean {\n  for (const index of scope) if (!covered.has(index)) return false\n  return true\n}\n\n/**\n * This order's sale-release caps, read outside any transaction (AGL-2325).\n *\n * SWALLOWS, like everything else on this path: the money has already moved,\n * and an empty map means \"cap nothing\", which leaves the prompt at the upper\n * bound it has always carried. One equality filter, so the automatic\n * single-field index answers it; the `reason` test runs here, over the handful\n * of rows one order has — the same query shape the cancellation writer runs\n * inside its transaction.\n */\nasync function readSaleReleaseCaps(\n  hostRef: FirebaseFirestore.DocumentReference,\n  orderId: string,\n): Promise<Map<string, number>> {\n  try {\n    const rows = await hostRef\n      .collection('inventoryAdjustments')\n      .where('orderId', '==', orderId)\n      .get()\n    return saleReleaseCaps(\n      rows.docs.filter((row) => row.get('reason') === 'sale'),\n    )\n  } catch (error) {\n    console.error('readSaleReleaseCaps failed', error)\n    return new Map()\n  }\n}\n\n/**\n * Key for one product+variant pair in a release-cap map.\n *\n * The separator is U+0000 written as an ESCAPE, not as a raw byte (AGL-2355).\n * Emitted literally it made `file(1)` call the source `data`, so grep skipped\n * the whole file as binary and an AGL-2320 sweep missed a call site in it.\n * Same character at runtime. NUL is still the right separator: it cannot occur\n * in a Firestore document id, so no pair can collide.\n */\nexport const restockCapKey = (productId: string, variantId: string): string =>\n  `${productId}\\u0000${variantId}`\n\n/**\n * How many units of each product+variant a sale ACTUALLY took off the shelf,\n * read from that order's `reason: 'sale'` ledger rows (AGL-2149).\n *\n * The variant inventory writer floors at zero, and that floor silently absorbs\n * the overshoot on a BACKORDER product: stock 0, `canPurchase` admits the sale\n * because the policy says to, three units sell, `Math.max(0, 0 + -3)` leaves\n * the count at 0. The rows carry both numbers for exactly this — `delta` stays\n * the units SOLD, which is the merchant's history, and `appliedDelta` says how\n * many the count could give up.\n *\n * The writer is deliberately NOT named here: `stock-decrement-race.spec.ts`\n * sweeps every server source for that identifier to prove no file outside its\n * allowlist hand-rolls a stock write, and it matches the bare name, so even a\n * comment mentioning it would read as a call site. This module writes no stock\n * at all — it writes the question.\n *\n * Shared by the cancellation writer, which uses it to bound how much stock\n * goes back, and by the restock flag, which uses it to bound what it CLAIMS\n * went missing (AGL-2325). Extracted rather than copied: the two must not\n * drift, because a flag that names more units than the cancellation would\n * return is the double-count both of them exist to avoid.\n */\nexport function saleReleaseCaps(\n  saleRows: readonly { get: (field: string) => unknown }[],\n): Map<string, number> {\n  const caps = new Map<string, number>()\n  for (const row of saleRows) {\n    const productId = String(row.get('productId') ?? '')\n    const variantId = String(row.get('variantId') ?? '')\n    if (!productId || !variantId) continue\n    const moved = Number(row.get('appliedDelta') ?? row.get('delta') ?? 0)\n    // Sale rows are negative; the cap is how many units left the shelf.\n    caps.set(\n      restockCapKey(productId, variantId),\n      (caps.get(restockCapKey(productId, variantId)) ?? 0) +\n        Math.max(0, -moved),\n    )\n  }\n  return caps\n}\n\n/**\n * Lines narrowed to what the count actually gave up, dropping any that gave up\n * nothing (AGL-2149, AGL-2325).\n *\n * ONLY PAIRS THE LEDGER DESCRIBES ARE CAPPED, and that asymmetry is the whole\n * safety argument. A pair with no row is left at the units it sold, which is\n * what keeps the pre-AGL-1807 draft links — decremented with no row at all —\n * and the buy-now path from being silently zeroed by a ledger that has holes\n * in it. So an absent ledger degrades to the old upper bound rather than to\n * saying nothing moved.\n *\n * The budget is consumed as it is spent, so two lines of the same\n * product+variant share one rather than each claiming it whole. Takes a COPY,\n * so a caller may reuse the map it passed.\n */\nexport function capRestockLines(\n  lines: readonly CommerceModel.OrderRestockLine[],\n  caps: ReadonlyMap<string, number>,\n): CommerceModel.OrderRestockLine[] {\n  const budgets = new Map(caps)\n  const capped: CommerceModel.OrderRestockLine[] = []\n  for (const line of lines) {\n    const key = restockCapKey(line.productId, line.variantId)\n    const budget = budgets.get(key)\n    const quantity =\n      budget == null ? line.quantity : Math.min(line.quantity, budget)\n    if (budget != null) budgets.set(key, budget - quantity)\n    if (quantity <= 0) continue\n    capped.push({ ...line, quantity })\n  }\n  return capped\n}\n\n/** What an order's tracked lines resolved to, with the products behind them. */\nexport interface TrackedRestockLines {\n  lines: CommerceModel.OrderRestockLine[]\n  /**\n   * The product doc behind each line, by product id — read once each, and\n   * handed back so a caller that WRITES stock (AGL-1808) does not read them a\n   * second time. Only products that contributed a line appear.\n   */\n  products: Map<string, CommerceModel.HostProduct>\n}\n\n/**\n * The order's lines whose stock the sale actually took off the shelf.\n *\n * The test is the sale path's own — `variant.inventory != null` on the variant\n * that sold — read from the product as it stands NOW, because that is the\n * count a restock would be applied to. A product deleted since the sale, or a\n * variant removed from it, therefore drops out: there is no number left to put\n * anything back into.\n *\n * Products are read once each, so a three-line order of the same product costs\n * one read rather than three.\n *\n * `read` is the caller's, and the choice is not cosmetic (AGL-1808): the flag\n * passes a swallowing `get()` because a product it cannot read must not fail a\n * refund that already moved, while the cancellation writer passes its\n * TRANSACTION's `get` so every product it is about to increment is read under\n * the same transaction that writes it — and so a read failure aborts rather\n * than quietly shortening the list.\n */\nexport async function resolveTrackedRestockLines(\n  hostRef: FirebaseFirestore.DocumentReference,\n  order: CommerceModel.HostOrder,\n  read: (\n    ref: FirebaseFirestore.DocumentReference,\n  ) => Promise<{ exists?: boolean; data?: () => unknown } | null>,\n): Promise<TrackedRestockLines> {\n  const products = new Map<string, CommerceModel.HostProduct | null>()\n  const lines: CommerceModel.OrderRestockLine[] = []\n  const orderLines = order.lineItems ?? []\n  for (let lineIndex = 0; lineIndex < orderLines.length; lineIndex += 1) {\n    const line = orderLines[lineIndex]\n    const productId = String(line?.productId ?? '')\n    const quantity = Math.round(Number(line?.quantity ?? 0))\n    if (!productId || !(quantity > 0)) continue\n    // Firestore reserves `__…__` document ids and `.doc()` throws on one\n    // SYNCHRONOUSLY, which no `.catch()` on the returned promise would see. A\n    // single corrupt line item must not cost the whole flag.\n    if (/^__.*__$/.test(productId)) continue\n    if (!products.has(productId)) {\n      const snapshot = await read(hostRef.collection('products').doc(productId))\n      products.set(\n        productId,\n        snapshot?.exists\n          ? CommerceModel.liftLegacyProduct((snapshot.data() ?? {}) as never)\n          : null,\n      )\n    }\n    const product = products.get(productId)\n    if (!product) continue\n    const variantId = line.variantId ?? product.variants?.[0]?.id\n    const tracked = (product.variants ?? []).some(\n      (variant) => variant.id === variantId && variant.inventory != null,\n    )\n    if (!variantId || !tracked) continue\n    lines.push({\n      productId,\n      variantId,\n      quantity,\n      lineIndex,\n      ...(line.name ? { name: line.name } : {}),\n      ...(line.variantLabel ? { variantLabel: line.variantLabel } : {}),\n    })\n  }\n  const resolved = new Map<string, CommerceModel.HostProduct>()\n  for (const line of lines) {\n    const product = products.get(line.productId)\n    if (product) resolved.set(line.productId, product)\n  }\n  return { lines, products: resolved }\n}\n"],"names":["CommerceModel","firebaseAdmin","flagOrderRestock","options","snapshot","order","firestore","app","hostRef","collection","doc","hostId","orderRef","orderId","get","exists","liftLegacyOrder","data","open","restockCheck","resolution","covered","openCheckCoverage","timeline","some","event","scope","reversalLineScope","kind","closedTheOrder","extended","Set","lines","allLines","resolveTrackedRestockLines","ref","catch","filter","line","has","lineIndex","length","capped","capRestockLines","readSaleReleaseCaps","asking","map","alreadyCovered","units","reduce","sum","quantity","flaggedAtMs","Date","now","record","fullyReversed","runTransaction","transaction","fresh","current","currentOpen","currentCoverage","update","appendOrderEvent","error","console","withdrawn","value","refundedLineItemIds","index","Math","round","Number","isFinite","add","size","check","rows","where","saleReleaseCaps","docs","row","Map","restockCapKey","productId","variantId","saleRows","caps","String","moved","set","max","budgets","key","budget","min","push","read","products","orderLines","lineItems","product","test","liftLegacyProduct","variants","id","tracked","variant","inventory","name","variantLabel","resolved"],"mappings":"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"}

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

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PluginApiHandler } from '@aglyn/aglyn/server';
+export interface PublicProductReview {
+    id: string;
+    rating: number;
+    body: string;
+    authorName: string;
+    verified: boolean;
+    reply: string | null;
+    createdAtMs: number;
+}
+export interface ProductReviewAggregate {
+    count: number;
+    /** Mean rating, one decimal. */
+    average: number;
+}
+/**
+ * Approved reviews for a product, newest first, plus their aggregate.
+ *
+ * Extracted from the handler (AGL-686) so the site-page resolver can nest
+ * `aggregateRating` inside the server-rendered `Product` node. Schema.org
+ * wants it as a PROPERTY of the product; the reviews block was emitting a
+ * free-standing `AggregateRating` node alongside it, which is orphaned and
+ * ignored. One reader means the rating in the structured data and the rating
+ * on the page cannot disagree.
+ */
+export declare function readProductReviews(hostId: string, productId: string): Promise<{
+    reviews: PublicProductReview[];
+    aggregate: ProductReviewAggregate;
+}>;
+/**
+ * Product reviews (AGL-324). GET returns approved reviews + aggregate;
+ * POST submits into the moderation queue, marking `verified` when the
+ * email has a paid order containing the product. Pro-plan gated.
+ */
+export declare const reviewsHandler: PluginApiHandler;