@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/model/commerce-orders.js

@@ -0,0 +1,1022 @@
+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.
+ */ /**
+ * Orders model v1 (AGL-283): line items snapshot the product/variant at
+ * purchase time (renames and price changes never rewrite history), a
+ * small status machine gates transitions, and totals are integer cents.
+ * Docs live at `hosts/{hostId}/orders/{id}`; the Stripe webhook creates
+ * them and the orders console (AGL-287) drives transitions. Pure — no
+ * I/O here.
+ */ import { stripeIdIsTestMode } from "@aglyn/aglyn/app-utils/stripe-deployment-mode";
+/**
+ * Legal status transitions. Refund/cancel policies: anything paid can
+ * refund; only unfulfilled orders cancel (refund instead once shipped).
+ *
+ * `cancelled` IS NOT TERMINAL, and treating it as one trapped money (AGL-2149).
+ * `cancel-order.ts` accepts a **paid** order — `paid: [… 'cancelled' …]` above
+ * — and moves no money when it does: it flips the status and returns the stock.
+ * `refund.ts` gates on `canTransitionOrder(order.status, 'refunded')`, so with
+ * `cancelled: []` the refund door closed behind the cancel and answered "orders
+ * in cancelled cannot refund" forever. An admin who cancelled a paid order
+ * instead of refunding it — the two buttons sit next to each other in the order
+ * dialog — had permanently locked the shopper's money out of every refund route
+ * this product has. The shopper's only remaining recourse was a chargeback,
+ * which costs the merchant the goods, the money AND the dispute fee.
+ *
+ * Whether cancelling a PAID order should refuse, or refund on the merchant's
+ * behalf, is a real product question and is deliberately NOT answered here:
+ * either would change what an existing console button does to money. Making the
+ * money reachable is the part that must not wait for that answer.
+ *
+ * A cancelled order that never took money simply has nothing to refund —
+ * `refund.ts` resolves no payment intent and answers "No payment to refund" —
+ * so the widened edge costs a lapsed `pending` order nothing.
+ */ const ORDER_TRANSITIONS = {
+    pending: [
+        'paid',
+        'cancelled'
+    ],
+    paid: [
+        'partially_fulfilled',
+        'fulfilled',
+        'cancelled',
+        'refunded'
+    ],
+    partially_fulfilled: [
+        'fulfilled',
+        'refunded'
+    ],
+    fulfilled: [
+        'delivered',
+        'refunded'
+    ],
+    delivered: [
+        'refunded'
+    ],
+    cancelled: [
+        'refunded'
+    ],
+    refunded: []
+};
+export function canTransitionOrder(from, to) {
+    var _ORDER_TRANSITIONS_from;
+    return ((_ORDER_TRANSITIONS_from = ORDER_TRANSITIONS[from]) != null ? _ORDER_TRANSITIONS_from : []).includes(to);
+}
+/**
+ * One money part, coerced to a whole non-negative number of cents (AGL-2224).
+ *
+ * `Math.max(0, Math.round(x))` is NOT this guard, and the difference is the
+ * whole defect: `Math.max` and `Math.min` PROPAGATE `NaN` rather than
+ * discarding it, so a single non-finite input made every field below `NaN` and
+ * `totalCents` with them. That is not a cosmetic wrong number — it is a number
+ * that defeats comparison. `cashReceivedCents < NaN` is `false`, so the POS
+ * "cash received is short" guard passed a sale that had taken no money; and a
+ * `NaN` written to Firestore (a legal double there) poisons every downstream
+ * sum, so ONE bad order renders a merchant's whole revenue figure `NaN`
+ * forever after.
+ *
+ * The inputs that can be non-finite are real, not theoretical: a POS
+ * `discountPct` that is not a number, a product whose `priceUsd` is a string
+ * or absent (`Number(undefined) * 100`), a `taxCents` derived from either. So
+ * this coerces at the boundary every order in the product passes through,
+ * rather than at each of the five callers, and answers 0 — the only value that
+ * cannot silently overstate what the shopper owes.
+ */ const wholeCents = (value)=>{
+    const cents = Math.round(Number(value != null ? value : 0));
+    return Number.isFinite(cents) && cents > 0 ? cents : 0;
+};
+/**
+ * Split `totalCents` across `weights` so the parts sum to it EXACTLY.
+ *
+ * Largest-remainder (Hamilton) apportionment. Each weight takes its exact
+ * share, the shares are floored, and the cents left over by flooring are handed
+ * one each to the largest fractional parts, ties going to the lower index so
+ * the answer is deterministic for a given input.
+ *
+ * The exactness is the whole point and it is a money property, not a
+ * neatness one: `Math.round` per line loses or invents cents against the total
+ * — three lines splitting a 10¢ discount round to 3+3+3=9 and the missing cent
+ * has to come from somewhere. A refund built on a split that does not close is
+ * a reconciliation defect that surfaces months later against Stripe's numbers.
+ *
+ * Pure and total. A non-positive total, an empty weight list, or weights that
+ * sum to nothing all answer zeros — never a division by zero, never a NaN
+ * propagated into an amount someone is charged.
+ */ export function apportionCents(weights, totalCents) {
+    const safe = (weights != null ? weights : []).map((weight)=>Math.max(0, Math.round(Number(weight != null ? weight : 0))));
+    const basis = safe.reduce((sum, weight)=>sum + weight, 0);
+    const total = Math.max(0, Math.round(Number(totalCents != null ? totalCents : 0)));
+    if (safe.length === 0 || basis <= 0 || total <= 0) return safe.map(()=>0);
+    // Never hand back more than there is to split. A discount larger than the
+    // items it came off is a data fault, and apportioning it in full would
+    // credit lines with money the order never carried.
+    const pot = Math.min(total, basis);
+    const exact = safe.map((weight)=>weight * pot / basis);
+    const shares = exact.map((value)=>Math.floor(value));
+    let remainder = pot - shares.reduce((sum, share)=>sum + share, 0);
+    const order = exact.map((value, index)=>({
+            index,
+            fraction: value - Math.floor(value)
+        })).sort((a, b)=>b.fraction - a.fraction || a.index - b.index);
+    for (const entry of order){
+        if (remainder <= 0) break;
+        shares[entry.index] += 1;
+        remainder -= 1;
+    }
+    return shares;
+}
+/**
+ * What refunding the named lines is actually worth.
+ *
+ * A line's LIST value is `unitAmountCents x quantity`, and that is what the
+ * refund route used to hand back. It is the wrong number on any order that
+ * carried an order-level discount, because the buyer never paid it: a $10
+ * coupon on two $50 lines means each line cost $45, and refunding one at $50
+ * pays back $5 the buyer never spent. The order then has less left than its
+ * remaining line is worth, so the SECOND line refund is refused outright and
+ * the merchant cannot finish the job they started.
+ *
+ * So each line carries its share of the discount, apportioned by list value
+ * through {@link apportionCents} — which guarantees the shares sum to the whole
+ * discount, so refunding every line returns exactly `itemsCents - discountCents`
+ * and no cent is stranded or invented.
+ *
+ * SHIPPING AND TAX ARE DELIBERATELY NOT IN THIS FIGURE. Refunding a line
+ * returns what the goods cost. Shipping is charged for the consignment rather
+ * than the line, so no split of it is defensible without knowing whether the
+ * parcel still ships; tax follows the goods but is Stripe's to recompute, and
+ * an order whose tax was collected under Aglyn's own registration
+ * (`taxMode: 'stripe-automatic'`) is not one this function may quietly decide
+ * to hand back. Both remain whole-order concerns, refundable by amount.
+ *
+ * Pure: unknown indexes contribute nothing rather than throwing.
+ */ export function orderLineRefundCents(order, lineIndexes) {
+    var _ref, _ref1;
+    var _order_totals;
+    const lines = (_ref = order == null ? void 0 : order.lineItems) != null ? _ref : [];
+    const gross = lines.map((line)=>{
+        var _ref, _ref1;
+        return Math.max(0, Math.round(Number((_ref = line == null ? void 0 : line.unitAmountCents) != null ? _ref : 0)) * Math.max(1, Math.round(Number((_ref1 = line == null ? void 0 : line.quantity) != null ? _ref1 : 1))));
+    });
+    const shares = apportionCents(gross, Math.max(0, Math.round(Number((_ref1 = order == null ? void 0 : (_order_totals = order.totals) == null ? void 0 : _order_totals.discountCents) != null ? _ref1 : 0))));
+    const wanted = new Set((lineIndexes != null ? lineIndexes : []).filter((index)=>Number.isInteger(index) && index >= 0 && index < lines.length));
+    let cents = 0;
+    for (const index of wanted)cents += gross[index] - shares[index];
+    return Math.max(0, cents);
+}
+/**
+ * A REHEARSAL IS NOT REVENUE.
+ *
+ * A smoke-test checkout writes a real order document. Stripe never moved money
+ * for it — the session id is `cs_test_…` — but every surface that sums paid
+ * orders counted it, so a storefront with one test order and no sales reported
+ * revenue it had never earned. Found in production: a single $18.00 order from
+ * an end-to-end run, standing as the whole platform's storefront revenue.
+ *
+ * ## Two signals, in order of trust
+ *
+ * `livemode` is a RECORDED FACT and wins whenever it is present: the webhook
+ * knows which Stripe environment an event came from and now writes it onto the
+ * order. Only a literal boolean counts, the same three-valued reading every
+ * other money gate in this codebase uses.
+ *
+ * The session id prefix is the FALLBACK, for the orders written before
+ * anything recorded the fact. It is Stripe's convention rather than our data,
+ * so it lives behind `stripeIdIsTestMode` and is not spelled out here.
+ *
+ * ## An unknowable order is LIVE
+ *
+ * An order with no `livemode` and no Stripe session id — a POS cash sale, a
+ * folio charge, a draft order paid offline — is real money and is counted.
+ * Answering "test" for anything we cannot identify would zero genuine sales,
+ * which is the one direction this must never fail in: a merchant under-reporting
+ * their own revenue has no way to tell it is happening.
+ */ export function orderIsTestMode(order) {
+    if (typeof (order == null ? void 0 : order.livemode) === 'boolean') return !order.livemode;
+    // `$id` as well as the field: every storefront order is keyed BY its session
+    // id, so the doc id carries the same signal and is present on rows read
+    // straight out of Firestore even where the field was never written. A POS or
+    // draft order has an auto-generated id, which matches no Stripe prefix and
+    // correctly reads as live.
+    return stripeIdIsTestMode(order == null ? void 0 : order.checkoutSessionId) || stripeIdIsTestMode(order == null ? void 0 : order.$id);
+}
+/** Sums line items and folds in shipping/tax/discount/fee, all cents. */ export function computeOrderTotals(lineItems, parts) {
+    const itemsCents = (lineItems != null ? lineItems : []).reduce((sum, line)=>sum + wholeCents((line == null ? void 0 : line.unitAmountCents) * (line == null ? void 0 : line.quantity)), 0);
+    const shippingCents = wholeCents(parts == null ? void 0 : parts.shippingCents);
+    const taxCents = wholeCents(parts == null ? void 0 : parts.taxCents);
+    const discountCents = Math.min(wholeCents(parts == null ? void 0 : parts.discountCents), itemsCents + shippingCents);
+    return {
+        itemsCents,
+        shippingCents,
+        taxCents,
+        discountCents,
+        feeCents: wholeCents(parts == null ? void 0 : parts.feeCents),
+        totalCents: itemsCents + shippingCents + taxCents - discountCents
+    };
+}
+export function computeCheckoutSessionTotals(lineItems, session, parts) {
+    var _ref, _ref1, _ref2, _ref3, _ref4, _ref5, _ref6, _ref7;
+    const details = (_ref = session == null ? void 0 : session.total_details) != null ? _ref : {};
+    const totals = computeOrderTotals(lineItems, {
+        feeCents: Number((_ref1 = parts == null ? void 0 : parts.feeCents) != null ? _ref1 : 0),
+        taxCents: Number((_ref2 = details == null ? void 0 : details.amount_tax) != null ? _ref2 : 0) + Number((_ref3 = parts == null ? void 0 : parts.lineItemTaxCents) != null ? _ref3 : 0),
+        shippingCents: Number((_ref4 = details == null ? void 0 : details.amount_shipping) != null ? _ref4 : 0),
+        discountCents: Number((_ref5 = details == null ? void 0 : details.amount_discount) != null ? _ref5 : 0) + Number((_ref6 = parts == null ? void 0 : parts.pricedInDiscountCents) != null ? _ref6 : 0)
+    });
+    const amountTotal = Number((_ref7 = session == null ? void 0 : session.amount_total) != null ? _ref7 : NaN);
+    return _extends({}, totals, {
+        totalCents: Number.isFinite(amountTotal) ? amountTotal : totals.totalCents
+    });
+}
+/** Non-negative integer cents from an untyped metadata value; 0 otherwise. */ function metadataCents(value) {
+    const cents = Math.round(Number(value != null ? value : 0));
+    return Number.isFinite(cents) && cents > 0 ? cents : 0;
+}
+/**
+ * The stored line items and totals for a `commerce-order` (buy-now) session
+ * (AGL-1711).
+ *
+ * ## What was wrong
+ *
+ * The webhook built the whole order from one number — it read
+ * `object.amount_total` into `amountCents`, wrote a single line item with
+ * `quantity` literal 1 and `unitAmountCents` set to that `amountCents`, and
+ * passed `computeOrderTotals` nothing but `feeCents`.
+ *
+ * `amount_total` is the ENTIRE charge, so the merchant's record said the
+ * product's unit price was the whole session total, that one unit was sold, and
+ * that tax and discount were zero. A 3 × $100 purchase recorded as 1 × $300.
+ *
+ * The dangerous property, and why this outlived AGL-1698: it is not internally
+ * inconsistent. `itemsCents` equalled `totalCents`, so the parts summed and any
+ * arithmetic check passed while every individual component was wrong. The
+ * useful test is not "do the parts sum" but "does each part match what Stripe
+ * actually charged", which is what the fixtures assert component by component.
+ *
+ * ## Why metadata, when AGL-1698's lesson was to read Stripe's own fields
+ *
+ * Two of the four parts are genuinely absent from Stripe's decomposition, and
+ * `checkout.ts` is what hid them:
+ *
+ * - **Tax.** In `manual` mode the tax is appended as `line_items[1]`, a normal
+ *   product line labelled e.g. "Tax (8.25%)". Stripe does not know it is tax,
+ *   so `total_details.amount_tax` is 0 while the money sits in `amount_total`.
+ *   (In `stripe` mode `automatic_tax` makes `amount_tax` real — and it was not
+ *   read either, so that tax was lost as well.)
+ * - **Discount.** A host coupon is applied by lowering the unit price we send,
+ *   not as a Stripe discount, so `total_details.amount_discount` is 0.
+ *
+ * So `checkout.ts` now records both figures, plus the list unit price, in the
+ * session metadata as it computes them. This is NOT the reconstruction AGL-1698
+ * warned against: the guard there is against pricing from the host's product
+ * docs at webhook time, where an edit between session creation and delivery
+ * makes our sum disagree with the actual charge. Metadata is a snapshot of the
+ * numbers we handed Stripe, frozen at session creation, so it cannot drift.
+ * Everything Stripe does know — `amount_total`, `amount_tax`, `amount_shipping`,
+ * `amount_discount` — still comes from Stripe, via the shared
+ * `computeCheckoutSessionTotals` rather than a parallel decomposition.
+ *
+ * Shipping is read even though `checkout.ts` declares no `shipping_options`
+ * today (AGL-1720): the read is not conditioned on that, so the figure lands on
+ * its own the moment buy-now starts charging shipping.
+ *
+ * ## Sessions created before this change
+ *
+ * They carry `quantity` (always sent) but none of the three new keys, so the
+ * unit price falls back to what Stripe charged per unit, derived from
+ * `amount_total` with tax, shipping and discount taken back out. Those orders
+ * still reconcile against `amount_total` and their quantity is now right; what
+ * cannot be recovered is a priced-in coupon, which stays folded into the unit
+ * price exactly as it is today. Deriving from the product doc instead would
+ * make `itemsCents` gross with no matching `discountCents`, breaking the sum.
+ *
+ * ## Worked example — the spec fixture
+ *
+ * Three $100 units, a 10% host coupon, manual destination tax at 8.25%:
+ *
+ *   listUnit              10000   metadata `unitAmountCents`
+ *   × quantity                3   metadata `quantity`
+ *   = itemsCents          30000
+ *   - discountCents        3000   metadata `discountCents` (priced into the
+ *                                 9000 unit price sent to Stripe)
+ *   + taxCents             2228   metadata `taxCents` (Stripe `line_items[1]`;
+ *                                 `total_details.amount_tax` is 0)
+ *   + shippingCents           0   Stripe `total_details.amount_shipping`
+ *   = totalCents          29228   Stripe `amount_total`, verbatim
+ *
+ * The pre-fix record for the same purchase: `1 × 29228`, tax 0, discount 0 —
+ * which also sums to 29228.
+ *
+ * ## Also the subscription sale record (AGL-1732)
+ *
+ * `checkout.ts` builds a subscription session with the same function and the
+ * same metadata snapshot — only `mode` differs — so the initial charge of a
+ * storefront subscription decomposes identically. The webhook's
+ * `commerce-subscription` branch stores the result on the subscription
+ * document rather than as an order; the arithmetic is the same either way,
+ * which is why it lives here and is not duplicated there.
+ */ export function computeBuyNowOrder(session, snapshot) {
+    var _ref, _ref1, _metadata_quantity, _ref2, _ref3, _ref4, _ref5, _metadata_variantId, _metadata_productId;
+    const metadata = (_ref = session == null ? void 0 : session.metadata) != null ? _ref : {};
+    const details = (_ref1 = session == null ? void 0 : session.total_details) != null ? _ref1 : {};
+    const rawQuantity = Math.round(Number((_metadata_quantity = metadata.quantity) != null ? _metadata_quantity : 1));
+    const quantity = Number.isFinite(rawQuantity) && rawQuantity > 0 ? rawQuantity : 1;
+    const lineItemTaxCents = metadataCents(metadata.taxCents);
+    const pricedInDiscountCents = metadataCents(metadata.discountCents);
+    // What Stripe charged for the goods themselves, used only when the session
+    // predates the `unitAmountCents` metadata: strip every non-goods component
+    // back out of the total and add the discount back in.
+    const goodsCents = Number((_ref2 = session == null ? void 0 : session.amount_total) != null ? _ref2 : 0) - Number((_ref3 = details == null ? void 0 : details.amount_tax) != null ? _ref3 : 0) - Number((_ref4 = details == null ? void 0 : details.amount_shipping) != null ? _ref4 : 0) - lineItemTaxCents + Number((_ref5 = details == null ? void 0 : details.amount_discount) != null ? _ref5 : 0) + pricedInDiscountCents;
+    const unitAmountCents = metadataCents(metadata.unitAmountCents) || Math.max(0, Math.round(goodsCents / quantity));
+    const variantId = String((_metadata_variantId = metadata.variantId) != null ? _metadata_variantId : '');
+    const lineItems = [
+        _extends({
+            productId: String((_metadata_productId = metadata.productId) != null ? _metadata_productId : '')
+        }, variantId ? {
+            variantId
+        } : {}, {
+            name: snapshot.name
+        }, snapshot.variantLabel ? {
+            variantLabel: snapshot.variantLabel
+        } : {}, snapshot.sku ? {
+            sku: snapshot.sku
+        } : {}, snapshot.productType ? {
+            productType: snapshot.productType
+        } : {}, snapshot.supplierId ? {
+            supplierId: snapshot.supplierId
+        } : {}, {
+            quantity,
+            unitAmountCents
+        })
+    ];
+    return {
+        lineItems,
+        totals: computeCheckoutSessionTotals(lineItems, session, {
+            feeCents: metadataCents(metadata.feeCents),
+            lineItemTaxCents,
+            pricedInDiscountCents
+        })
+    };
+}
+/**
+ * The base a subscription invoice's platform fee SHOULD be taken on
+ * (AGL-2317): post-discount items, with tax and shipping removed.
+ *
+ * Every one-time door — `checkout.ts`, `cart-checkout.ts`, `draft-order.ts`,
+ * `pos-order.ts` and (since AGL-2315) bookings — sends a cents amount computed
+ * on items alone. The recurring door sent `application_fee_percent`, which
+ * Stripe applies to the WHOLE invoice, so Aglyn took a cut of sales tax — money
+ * that is the state's — and of shipping. On the issue's worked example ($30/mo
+ * digital, Business 2%, an 8.25% TX rate) the one-time base is $30.00 → 60¢ and
+ * the invoice total is $32.48 → 65¢.
+ *
+ * `total` and not a re-summed `lines.data[]`, deliberately. Stripe's own total
+ * is already net of every invoice-level discount and of any proration CREDIT,
+ * both of which `computeSubscriptionInvoiceOrder` drops (it floors a line at 0,
+ * which is right for a stored line item and wrong for a fee base — a mid-cycle
+ * downgrade credit reduces what the merchant is actually paid). Subtracting the
+ * two parts Stripe reports separately leaves exactly what was charged for goods.
+ *
+ * Tax is read on both spellings for the reason stated on `SubscriptionInvoiceSource`
+ * — the scalar was removed on newer API versions and the endpoint's version is
+ * dashboard configuration this repo cannot see. Reading only one of them would
+ * silently value tax at 0 and hand back the whole invoice total as the base,
+ * which is the very bug this closes.
+ */ export function subscriptionInvoiceFeeBasisCents(invoice) {
+    var _ref, _ref1;
+    var _invoice_shipping_cost;
+    const totalCents = metadataCents(invoice == null ? void 0 : invoice.total);
+    if (totalCents <= 0) return 0;
+    const scalarTax = Number((_ref = invoice == null ? void 0 : invoice.tax) != null ? _ref : NaN);
+    const taxCents = Number.isFinite(scalarTax) && scalarTax > 0 ? scalarTax : sumAmounts((_ref1 = invoice == null ? void 0 : invoice.total_taxes) != null ? _ref1 : invoice == null ? void 0 : invoice.total_tax_amounts);
+    const shippingCents = metadataCents(invoice == null ? void 0 : (_invoice_shipping_cost = invoice.shipping_cost) == null ? void 0 : _invoice_shipping_cost.amount_total);
+    return Math.max(0, totalCents - Math.max(0, taxCents) - shippingCents);
+}
+/**
+ * What the platform fee on a paid subscription invoice WOULD have been on the
+ * items-only base, at the rate Stripe actually applied (AGL-2317).
+ *
+ * ## The rate is never named here, on purpose
+ *
+ * Pricing is locked for Sept 1, so this is a BASE correction and must not be
+ * able to become a rate change. It therefore takes no plan, no entitlement and
+ * no `resolveTransactionFeePct` call: it scales the fee Stripe already charged
+ * by `base / total`. Whatever rate produced `application_fee_amount` — the
+ * sale-time one, a rate AGL-2289 has since re-priced, or a staff override —
+ * comes through untouched, and the only thing removed is the portion that was
+ * taken on tax and shipping. A test that changed a rate could not make this
+ * function agree with it.
+ *
+ * `Math.max(1, …)` matches `checkout.ts`: where a rate applies at all, the
+ * floor is a cent, never zero. An invoice with no fee, no total, or nothing but
+ * tax answers 0 and asks for no correction it cannot justify.
+ */ export function subscriptionInvoiceItemsOnlyFeeCents(invoice) {
+    const chargedCents = metadataCents(invoice == null ? void 0 : invoice.application_fee_amount);
+    if (chargedCents <= 0) return 0;
+    const totalCents = metadataCents(invoice == null ? void 0 : invoice.total);
+    // Nothing to scale against — leave what Stripe took rather than inventing a
+    // reduction from a total we cannot read.
+    if (totalCents <= 0) return chargedCents;
+    const basisCents = subscriptionInvoiceFeeBasisCents(invoice);
+    if (basisCents <= 0) return 0;
+    // Tax-free and shipping-free invoices — the majority — land here and are
+    // byte-identical to today, which is what makes this safe inside the freeze.
+    if (basisCents >= totalCents) return chargedCents;
+    return Math.max(1, Math.round(chargedCents * basisCents / totalCents));
+}
+/**
+ * The recurring goods a storefront subscription's `application_fee_percent`
+ * is sized against when a paid invoice re-prices it (AGL-2655).
+ *
+ * The percent carries Stripe's fixed 30¢ folded into a rate, so it depends
+ * on the amount it will be applied to — and the amount that matters is the
+ * NEXT cycle's, which nobody has yet. The best predictor is this cycle's
+ * items-only basis, for a cycle that bills the full recurring price:
+ * `subscription_cycle`, and `subscription_create` for the opening charge.
+ * Any other reason — a `subscription_update` proration, a threshold
+ * invoice — bills a fraction, and a percent sized on a fraction would be
+ * applied to the following full cycle and over-recover on it. Those, and a
+ * $0 opening invoice (a trial converts later), fall back to what the sale
+ * recorded: the sold lines' price × quantity, the stable figure the
+ * subscription bills every cycle it is not being adjusted.
+ *
+ * Zero when neither source knows — and the caller then leaves the rate as it
+ * stands rather than sizing a percent on nothing.
+ */ export function subscriptionRecurringBasisCents(invoice, soldLineItems) {
+    var _ref;
+    const reason = String((_ref = invoice == null ? void 0 : invoice.billing_reason) != null ? _ref : '');
+    const billsTheFullPrice = reason === 'subscription_cycle' || reason === 'subscription_create';
+    const cycleBasis = billsTheFullPrice ? subscriptionInvoiceFeeBasisCents(invoice) : 0;
+    if (cycleBasis > 0) return cycleBasis;
+    return (soldLineItems != null ? soldLineItems : []).reduce((sum, line)=>{
+        var _ref, _ref1;
+        const unit = Math.round(Number((_ref = line == null ? void 0 : line.unitAmountCents) != null ? _ref : 0));
+        const quantity = Math.round(Number((_ref1 = line == null ? void 0 : line.quantity) != null ? _ref1 : 0));
+        if (!Number.isFinite(unit) || !Number.isFinite(quantity)) return sum;
+        return sum + Math.max(0, unit) * Math.max(0, quantity);
+    }, 0);
+}
+/** Sum of an `[{ amount }]` list, ignoring anything unreadable. */ function sumAmounts(list) {
+    return (list != null ? list : []).reduce((sum, entry)=>{
+        var _ref;
+        const amount = Number((_ref = entry == null ? void 0 : entry.amount) != null ? _ref : 0);
+        return sum + (Number.isFinite(amount) ? amount : 0);
+    }, 0);
+}
+/** `price.recurring.interval` when it is one we sell, else undefined. */ function lineInterval(line) {
+    var _line_price_recurring, _line_price;
+    const interval = line == null ? void 0 : (_line_price = line.price) == null ? void 0 : (_line_price_recurring = _line_price.recurring) == null ? void 0 : _line_price_recurring.interval;
+    return interval === 'month' || interval === 'year' ? interval : undefined;
+}
+/**
+ * The line that describes the SUBSCRIPTION being billed.
+ *
+ * `lines.data[0]` is not it, for the AGL-1640 reason: a mid-cycle plan switch
+ * invoices the proration against the OLD price ahead of the new plan, and an
+ * invoice also carries one-off items and credits, any of which can sort first.
+ * Prefer a non-proration line stating a cadence; fall back to a proration one,
+ * since Stripe requires every recurring item on one subscription to share a
+ * cadence; fall back to the first line so a renewal still records a name.
+ */ export function selectSubscriptionInvoiceLine(invoice) {
+    var _ref, _ref1, _lines_find;
+    var _invoice_lines;
+    const lines = (_ref = invoice == null ? void 0 : (_invoice_lines = invoice.lines) == null ? void 0 : _invoice_lines.data) != null ? _ref : [];
+    return (_ref1 = (_lines_find = lines.find((line)=>!(line == null ? void 0 : line.proration) && lineInterval(line))) != null ? _lines_find : lines.find((line)=>lineInterval(line))) != null ? _ref1 : lines[0];
+}
+/**
+ * The cadence a paid invoice was billed on, or undefined when it does not say.
+ *
+ * Never guessed — the same three-state discipline as `billingIntervalFromInvoice`
+ * (AGL-1640). Storing `month` for an invoice that did not state one would make
+ * the merchant's own record of what a subscriber pays wrong in the one way that
+ * cannot be spotted by looking at it.
+ */ export function subscriptionInvoiceInterval(invoice) {
+    return lineInterval(selectSubscriptionInvoiceLine(invoice));
+}
+/**
+ * The stored line items and totals for one paid subscription invoice
+ * (AGL-1743) — a renewal, or the opening cycle.
+ *
+ * `snapshot` supplies the product identity, taken from what the sale already
+ * recorded rather than re-derived: an invoice line knows a description and a
+ * price, not a productId, a variant or a SKU. It is applied to the
+ * subscription's own line only; a proration or one-off line on the same invoice
+ * keeps Stripe's description and carries no product identity, because it is not
+ * a sale of that product.
+ *
+ * `totalCents` is Stripe's `amount_paid` verbatim, for the AGL-1698 reason —
+ * our sum is priced from lines we did not authorize and must never become the
+ * stored truth. Where a customer credit balance covers part of an invoice the
+ * parts will therefore exceed the collected total; the collected figure is the
+ * one that matters and the invoice's own `total` is stored beside it.
+ */ export function computeSubscriptionInvoiceOrder(invoice, snapshot) {
+    var _ref, _ref1, _ref2;
+    var _invoice_lines, _invoice_shipping_cost;
+    const subscriptionLine = selectSubscriptionInvoiceLine(invoice);
+    const lineItems = [];
+    for (const line of (_ref = invoice == null ? void 0 : (_invoice_lines = invoice.lines) == null ? void 0 : _invoice_lines.data) != null ? _ref : []){
+        var _ref3, _ref4, _ref5, _ref6;
+        var _line_price;
+        const amount = Math.round(Number((_ref3 = line == null ? void 0 : line.amount) != null ? _ref3 : 0));
+        // A credit line (negative proration) is not a sale of anything, and
+        // `computeOrderTotals` floors a line at 0 rather than subtracting it.
+        // Stripe's own collected total still carries its effect.
+        if (!Number.isFinite(amount) || amount <= 0) continue;
+        const rawQuantity = Math.round(Number((_ref4 = line == null ? void 0 : line.quantity) != null ? _ref4 : 1));
+        const quantity = Number.isFinite(rawQuantity) && rawQuantity > 0 ? rawQuantity : 1;
+        // The list unit price, except on a proration line, where `unit_amount` is
+        // the full price and `amount` is only the fraction being billed.
+        const listUnit = Math.round(Number((_ref5 = line == null ? void 0 : (_line_price = line.price) == null ? void 0 : _line_price.unit_amount) != null ? _ref5 : 0));
+        const unitAmountCents = !(line == null ? void 0 : line.proration) && Number.isFinite(listUnit) && listUnit > 0 ? listUnit : Math.max(0, Math.round(amount / quantity));
+        const isSubscriptionLine = line === subscriptionLine;
+        lineItems.push(_extends({
+            productId: isSubscriptionLine ? snapshot.productId : ''
+        }, isSubscriptionLine && snapshot.variantId ? {
+            variantId: snapshot.variantId
+        } : {}, {
+            name: isSubscriptionLine ? snapshot.name : String((_ref6 = line == null ? void 0 : line.description) != null ? _ref6 : 'Adjustment').slice(0, 200)
+        }, isSubscriptionLine && snapshot.variantLabel ? {
+            variantLabel: snapshot.variantLabel
+        } : {}, isSubscriptionLine && snapshot.sku ? {
+            sku: snapshot.sku
+        } : {}, isSubscriptionLine && snapshot.productType ? {
+            productType: snapshot.productType
+        } : {}, isSubscriptionLine && snapshot.supplierId ? {
+            supplierId: snapshot.supplierId
+        } : {}, {
+            quantity,
+            unitAmountCents
+        }));
+    }
+    const scalarTax = Number((_ref1 = invoice == null ? void 0 : invoice.tax) != null ? _ref1 : NaN);
+    const taxCents = Number.isFinite(scalarTax) && scalarTax > 0 ? scalarTax : // scalar; they do not coexist, so this cannot double-count.
+    sumAmounts((_ref2 = invoice == null ? void 0 : invoice.total_taxes) != null ? _ref2 : invoice == null ? void 0 : invoice.total_tax_amounts);
+    return {
+        lineItems,
+        totals: computeCheckoutSessionTotals(lineItems, {
+            amount_total: invoice == null ? void 0 : invoice.amount_paid,
+            total_details: {
+                amount_tax: taxCents,
+                amount_shipping: metadataCents(invoice == null ? void 0 : (_invoice_shipping_cost = invoice.shipping_cost) == null ? void 0 : _invoice_shipping_cost.amount_total),
+                amount_discount: sumAmounts(invoice == null ? void 0 : invoice.total_discount_amounts)
+            }
+        }, {
+            feeCents: metadataCents(invoice == null ? void 0 : invoice.application_fee_amount)
+        })
+    };
+}
+/** Display form: `#1042`; falls back to a doc-id stub for legacy rows. */ export function formatOrderNumber(order, docId) {
+    if (order.number != null) return `#${order.number}`;
+    return docId ? `#${docId.slice(-6).toUpperCase()}` : '#—';
+}
+/**
+ * Lifts a legacy Commerce Starter order row (flat productId/amountCents)
+ * into the v1 shape for display; already-shaped orders pass through.
+ */ export function liftLegacyOrder(raw) {
+    var _raw_amountCents, _raw_status, _raw_channel, _raw_totals, _raw_feeCents;
+    if (Array.isArray(raw.lineItems) && raw.lineItems.length > 0) {
+        return _extends({
+            status: 'paid'
+        }, raw);
+    }
+    const amountCents = Number((_raw_amountCents = raw.amountCents) != null ? _raw_amountCents : 0);
+    return _extends({}, raw, {
+        status: (_raw_status = raw.status) != null ? _raw_status : 'paid',
+        channel: (_raw_channel = raw.channel) != null ? _raw_channel : 'online',
+        lineItems: raw.productId ? [
+            {
+                productId: raw.productId,
+                name: 'Product',
+                quantity: 1,
+                unitAmountCents: amountCents
+            }
+        ] : [],
+        totals: (_raw_totals = raw.totals) != null ? _raw_totals : {
+            itemsCents: amountCents,
+            shippingCents: 0,
+            taxCents: 0,
+            discountCents: 0,
+            feeCents: Number((_raw_feeCents = raw.feeCents) != null ? _raw_feeCents : 0),
+            totalCents: amountCents
+        }
+    });
+}
+/**
+ * Does this order contain `productId`?
+ *
+ * Line items first, legacy flat `productId` as the fallback — the same test
+ * `gate.ts`, `download.ts` and `reviews.ts` already apply. Only the two
+ * buy-now-shaped Stripe paths ever write the flat field, so a legacy-only
+ * check silently excludes every cart, POS and draft order.
+ */ export function orderContainsProduct(order, productId) {
+    var _order_lineItems;
+    return ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).some((line)=>line.productId === productId) || order.productId === productId;
+}
+/**
+ * Line indexes already covered by a recorded fulfillment (AGL-2455).
+ *
+ * The set the supplier callback and the console's own fulfil both have to
+ * reason about, and the reason `status` alone could not: `supplier-update.ts`
+ * wrote `status: 'fulfilled'` as a LITERAL, so the first supplier to post
+ * tracking on a two-supplier order marked every line shipped — including lines
+ * they have never seen — and the second supplier's POST met a 409 because
+ * `fulfilled` cannot transition to `fulfilled`. The buyer was told their whole
+ * order shipped with one carrier and one tracking number.
+ */ export function coveredLineItemIds(order) {
+    var _order_fulfillments;
+    const covered = new Set();
+    for (const fulfillment of (_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []){
+        var _ref;
+        for (const index of (_ref = fulfillment == null ? void 0 : fulfillment.lineItemIds) != null ? _ref : []){
+            const line = Math.round(Number(index));
+            if (Number.isFinite(line) && line >= 0) covered.add(line);
+        }
+    }
+    return covered;
+}
+/** Distinct suppliers with at least one line on this order (AGL-2455). */ export function orderSupplierIds(order) {
+    var _order_lineItems;
+    return [
+        ...new Set(((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line)=>{
+            var _line_supplierId;
+            return String((_line_supplierId = line.supplierId) != null ? _line_supplierId : '');
+        }).filter(Boolean))
+    ];
+}
+/** Line indexes belonging to one supplier (AGL-2455). */ export function supplierLineItemIds(order, supplierId) {
+    var _order_lineItems;
+    return ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line, index)=>({
+            line,
+            index
+        })).filter(({ line })=>{
+        var _line_supplierId;
+        return String((_line_supplierId = line.supplierId) != null ? _line_supplierId : '') === supplierId;
+    }).map(({ index })=>index);
+}
+/**
+ * The status an order reaches once `covered` lines are shipped (AGL-2455).
+ *
+ * COMPUTED from the fulfillment set rather than written as a literal, which is
+ * the whole of this issue's third requirement. `partially_fulfilled` has existed
+ * in `ORDER_TRANSITIONS` since orders shipped and nothing ever wrote it.
+ *
+ * An order with no lines at all reads as fulfilled — there is nothing left to
+ * ship, and answering `partially_fulfilled` would strand it forever.
+ */ export function statusAfterFulfilling(order, covered) {
+    var _order_lineItems;
+    const lines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    if (lines.length === 0) return 'fulfilled';
+    return lines.every((_line, index)=>covered.has(index)) ? 'fulfilled' : 'partially_fulfilled';
+}
+/**
+ * Statuses under which an order grants NO entitlement at all (AGL-2454).
+ *
+ * `pending` has not paid, `cancelled` was undone, `refunded` was given back.
+ * The literal list was copied into `download.ts`, `gate.ts`,
+ * `membership-account.ts` and `reviews.ts`; it lives here now so a change to
+ * what "withdrawn" means reaches all of them at once.
+ */ const WITHDRAWN_ORDER_STATUSES = [
+    'pending',
+    'cancelled',
+    'refunded'
+];
+/**
+ * How much of this order has been given back (AGL-2454).
+ *
+ * `full` follows `status` OR the money, because the two can legitimately
+ * disagree for a moment: `refund.ts` reserves `refundedCents` before it calls
+ * Stripe and flips `status` after, and a lost dispute reverses money on an
+ * order whose status is still `paid` until it closes. Reading only the status
+ * would treat that window as "nothing refunded".
+ */ export function orderRefundState(order) {
+    var _order_refundedCents, _ref, _order_amountCents;
+    var _order_totals;
+    const refundedCents = Math.max(0, Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0));
+    const totalCents = (_ref = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref : Number((_order_amountCents = order.amountCents) != null ? _order_amountCents : 0);
+    if (order.status === 'refunded') return 'full';
+    if (!(refundedCents > 0)) return 'none';
+    return totalCents > 0 && refundedCents >= totalCents ? 'full' : 'partial';
+}
+/**
+ * Is this line's entitlement withdrawn?
+ *
+ * By INDEX, matching `refundedLineItemIds`. A cart can hold the same product on
+ * two lines and only one may be coming back, so a product-keyed test would
+ * revoke goods the buyer still owns.
+ */ export function orderLineRefunded(order, lineIndex) {
+    var _order_refundedLineItemIds;
+    return ((_order_refundedLineItemIds = order.refundedLineItemIds) != null ? _order_refundedLineItemIds : []).includes(lineIndex);
+}
+/**
+ * THE ONE ENTITLEMENT TEST (AGL-2454). Does this order still entitle the buyer
+ * to `productId`?
+ *
+ * Five gates asked this question and all five asked it as
+ * `!['pending','cancelled','refunded'].includes(status) && orderContainsProduct(…)`.
+ * That reading is why a partial refund revoked NOTHING: `refund.ts` writes
+ * `status: 'refunded'` only when the order is FULLY refunded, so a 99%-refunded
+ * order stayed `paid` and every gate said yes — downloads, licence keys, gated
+ * content and the right to post a verified review, all still live.
+ *
+ * Withdrawn now means either of two things, and both had to be expressible in
+ * one place or the five gates would drift again:
+ *
+ *  - the whole order is withdrawn by `status`, as before; or
+ *  - every line carrying this product was refunded BY NAME, which is the case a
+ *    line-scoped refund creates and the only case where an amount can honestly
+ *    be attributed to goods.
+ *
+ * `'any'` asks whether the order still entitles ANYTHING, which is what the
+ * membership paywall's subscription-shaped probe needs.
+ *
+ * The legacy flat `productId` order (one line, no `lineItems`) is lifted by
+ * `liftLegacyOrder` before it gets here, so index 0 is its only line and a
+ * line-scoped refund of it behaves like a full one.
+ */ export function orderEntitlesProduct(order, productId) {
+    var _order_lineItems;
+    if (WITHDRAWN_ORDER_STATUSES.includes(order.status)) {
+        return false;
+    }
+    const lines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    if (productId === 'any') {
+        if (lines.length === 0) return true;
+        return lines.some((_line, index)=>!orderLineRefunded(order, index));
+    }
+    const matching = lines.map((line, index)=>({
+            line,
+            index
+        })).filter(({ line })=>line.productId === productId);
+    if (matching.length === 0) {
+        // The legacy flat shape, which `liftLegacyOrder` normally converts. Kept so
+        // an unlifted row is not silently un-entitled — a false negative here locks
+        // a paying buyer out of goods they bought.
+        return order.productId === productId;
+    }
+    return matching.some(({ index })=>!orderLineRefunded(order, index));
+}
+/**
+ * Product ids whose entitlement this order has withdrawn line by line
+ * (AGL-2454) — every line for the product refunded, none left standing.
+ *
+ * What `refund.ts` uses to decide which licence keys to RETIRE. Not "any line
+ * refunded": a buyer who returned one of two copies still holds the product.
+ */ export function refundedProductIds(order) {
+    var _order_lineItems;
+    const lines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    const ids = new Set();
+    for (const line of lines){
+        if (!ids.has(line.productId) && !orderEntitlesProduct(order, line.productId)) {
+            ids.add(line.productId);
+        }
+    }
+    return [
+        ...ids
+    ];
+}
+/**
+ * The refund line the console and the merchant read (AGL-2454).
+ *
+ * Kept in the model because three surfaces show it and "partially refunded"
+ * must not mean different things on two of them. Empty for an order with
+ * nothing refunded — there is nothing to say.
+ */ export function orderRefundSummary(order) {
+    var _order_refundedCents, _ref, _order_amountCents, _order_refundedLineItemIds, _order_lineItems;
+    var _order_totals;
+    const state = orderRefundState(order);
+    if (state === 'none') return '';
+    const refundedCents = Math.max(0, Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0));
+    const totalCents = (_ref = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref : Number((_order_amountCents = order.amountCents) != null ? _order_amountCents : 0);
+    if (state === 'full') return `Refunded in full ($${usd(refundedCents)})`;
+    const revoked = ((_order_refundedLineItemIds = order.refundedLineItemIds) != null ? _order_refundedLineItemIds : []).length;
+    const lines = ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).length;
+    const scope = revoked > 0 ? `${revoked} of ${lines} line${lines === 1 ? '' : 's'} withdrawn` : 'no lines withdrawn — refunded by amount';
+    return `Partially refunded ($${usd(refundedCents)} of $${usd(totalCents)}) — ${scope}`;
+}
+/** `12345` -> `123.45`, the CSV's money format. */ function usd(cents) {
+    return (cents / 100).toFixed(2);
+}
+/**
+ * Display labels for {@link OrderStatus}, and the MUI chip colour each one
+ * carries (AGL-2136). The orders screen advertised on `/product/commerce`
+ * shows the status as a COLOURED pill — `Paid`, `Fulfilled`, `Refunded` in
+ * three different colours — where the console rendered every status as the
+ * same default outlined chip, so the one column a merchant scans first
+ * carried no signal at all.
+ *
+ * Kept in the model rather than in the card because three surfaces render a
+ * status (the orders list, the detail dialog and the dashboard glance
+ * widget) and a colour that means "refunded" on one of them must not mean
+ * something else on the next.
+ */ export const ORDER_STATUS_LABELS = {
+    pending: 'Pending',
+    paid: 'Paid',
+    partially_fulfilled: 'Partly fulfilled',
+    fulfilled: 'Fulfilled',
+    delivered: 'Delivered',
+    cancelled: 'Canceled',
+    refunded: 'Refunded'
+};
+/**
+ * Chip colour per status. `pending` is deliberately `default` rather than
+ * `warning`: an unpaid order is not a problem, it is simply not money yet,
+ * and reserving the alarming colours for `cancelled`/`refunded` is what
+ * makes them readable at a glance.
+ */ export const ORDER_STATUS_COLOR = {
+    pending: 'default',
+    paid: 'success',
+    partially_fulfilled: 'warning',
+    fulfilled: 'info',
+    delivered: 'info',
+    cancelled: 'default',
+    refunded: 'error'
+};
+/** Display labels for {@link OrderChannel}. */ export const ORDER_CHANNEL_LABELS = {
+    online: 'Online',
+    pos: 'POS',
+    draft: 'Draft',
+    subscription: 'Subscription'
+};
+/** Human label for a channel, tolerating a legacy/unknown value. */ export function orderChannelLabel(channel) {
+    var _ref, _ORDER_CHANNEL_LABELS_;
+    return (_ref = (_ORDER_CHANNEL_LABELS_ = ORDER_CHANNEL_LABELS[channel != null ? channel : 'online']) != null ? _ORDER_CHANNEL_LABELS_ : channel) != null ? _ref : 'Online';
+}
+/**
+ * Net cents an order actually earned: the charged total less anything
+ * refunded. The three commerce surfaces each had their own inline copy of
+ * this expression; a refunded order counted as revenue on whichever one
+ * was written first.
+ */ export function orderNetCents(order) {
+    var _ref, _ref1, _order_refundedCents;
+    var _order_totals;
+    const gross = Number((_ref = (_ref1 = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref1 : order.amountCents) != null ? _ref : 0);
+    return gross - Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0);
+}
+/** Milliseconds an order was created at, across every writer's field shape. */ export function orderCreatedAtMs(order) {
+    var _order_createdAt, _order_createdAt_toDate, _order_createdAt1;
+    if (typeof order.createdAtMs === 'number') return order.createdAtMs;
+    const seconds = (_order_createdAt = order.createdAt) == null ? void 0 : _order_createdAt.seconds;
+    if (typeof seconds === 'number') return seconds * 1000;
+    const date = (_order_createdAt1 = order.createdAt) == null ? void 0 : (_order_createdAt_toDate = _order_createdAt1.toDate) == null ? void 0 : _order_createdAt_toDate.call(_order_createdAt1);
+    return date ? date.getTime() : 0;
+}
+const ORDER_WINDOW_DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Percentage change from `previous` to `current`, or `null` when there is
+ * no baseline to divide by.
+ */ function deltaPct(current, previous) {
+    if (!previous) return null;
+    return Math.round((current - previous) / previous * 1000) / 10;
+}
+/**
+ * Summarises a window of orders and the window before it (AGL-2136).
+ *
+ * Every commerce mockup we advertise shows the money tiles carrying a
+ * period-over-period delta — `Revenue $26,540 +8.1%` — and the product had
+ * no prior-window computation anywhere in the repo, so no surface could
+ * have rendered one.
+ *
+ * `pending` and `cancelled` orders are excluded, matching the analytics
+ * card: neither is money. Refunds are subtracted rather than dropped, so a
+ * refund inside the window pushes the delta DOWN, which is the whole point
+ * of showing it.
+ */ export function summarizeOrderWindow(orders, options) {
+    var _options_days;
+    const days = (_options_days = options.days) != null ? _options_days : 30;
+    const spanMs = days * ORDER_WINDOW_DAY_MS;
+    const { nowMs } = options;
+    let revenueCents = 0;
+    let count = 0;
+    let priorRevenueCents = 0;
+    let priorCount = 0;
+    for (const order of orders){
+        const lifted = liftLegacyOrder(order);
+        if (lifted.status === 'pending' || lifted.status === 'cancelled') continue;
+        const age = nowMs - orderCreatedAtMs(order);
+        if (age < 0) continue;
+        if (age < spanMs) {
+            revenueCents += orderNetCents(order);
+            count += 1;
+        } else if (age < spanMs * 2) {
+            priorRevenueCents += orderNetCents(order);
+            priorCount += 1;
+        }
+    }
+    const aovCents = count ? Math.round(revenueCents / count) : 0;
+    const priorAovCents = priorCount ? Math.round(priorRevenueCents / priorCount) : 0;
+    return {
+        revenueCents,
+        orders: count,
+        aovCents,
+        revenueDeltaPct: deltaPct(revenueCents, priorRevenueCents),
+        ordersDeltaPct: deltaPct(count, priorCount),
+        aovDeltaPct: deltaPct(aovCents, priorAovCents)
+    };
+}
+/**
+ * Header for {@link buildOrdersCsv}. The original seven columns (AGL-96) keep
+ * their names AND their positions, so a saved import mapping — by name or by
+ * index — still resolves; the four reconciliation columns are appended.
+ */ export const ORDERS_CSV_HEADER = 'date,product,amountUsd,feeUsd,customerEmail,coupon,orderId,' + 'status,channel,refundedUsd,netUsd';
+/**
+ * The orders console's `orders.csv` (AGL-1747).
+ *
+ * ## What was wrong
+ *
+ * The export read `amountCents`, `feeCents` and `productId` — the legacy
+ * Commerce Starter flat fields (AGL-90) — and nothing else. Checked writer by
+ * writer, only the two buy-now-shaped Stripe paths write them:
+ *
+ * | Order path | `amountCents` | `productId` |
+ * | -- | -- | -- |
+ * | buy-now (`commerce-order`, `billing-webhook.ts`) | yes | yes |
+ * | cart (`commerce-cart`, `billing-webhook.ts`) | yes | **no** |
+ * | POS cash and POS card (`pos-order.ts`) | **no** | **no** |
+ * | draft (`draft-order.ts`, paid by `commerce-draft`) | **no** | **no** |
+ *
+ * So every POS and draft order exported as `$0.00` and every cart order
+ * exported with a blank product, each beside a plausible date, email and order
+ * id — nothing in the file signals that the number is missing rather than
+ * genuinely zero. The console screen was right the whole time: the table row
+ * beside the export button, the detail dialog, the analytics card and lifetime
+ * purchases all read `totals` with the flat field only as a fallback. The
+ * export was the sole reader that had the precedence backwards, and a CSV is
+ * the artefact that reaches a bookkeeper.
+ *
+ * ## What "correct" means
+ *
+ * Per AGL-1711's lesson, the useful test is not "do the parts sum" but "does
+ * each column match what was actually charged" — a total-only assertion passes
+ * against a row whose every component is wrong. The spec therefore pins each
+ * cell of a worked example individually.
+ *
+ * ## Refunds
+ *
+ * `amountUsd` stays gross, which is what it has always meant, and the appended
+ * `refundedUsd`/`netUsd` carry the rest. A refunded order previously exported
+ * at its gross with nothing beside it to say so — the same class of error, in
+ * that the file understated nothing but overstated revenue.
+ */ export function buildOrdersCsv(orders, productNames = {}) {
+    const escape = (cell)=>/[",\n]/.test(cell) ? `"${cell.replace(/"/g, '""')}"` : cell;
+    return [
+        ORDERS_CSV_HEADER,
+        ...orders.map((order)=>{
+            var _order_lineItems, _ref, _ref1, _ref2, _ref3, _order_productId, _ref4, _ref5, _ref6, _ref7, _order_refundedCents, _order_customerEmail, _order_couponCode, _order_$id, _lifted_channel;
+            var _order_createdAt_toDate, _order_createdAt, _lineItems_, _lifted_totals, _lifted_totals1;
+            const lifted = liftLegacyOrder(order);
+            // The STORED line items, not the lifted ones: `liftLegacyOrder` gives a
+            // legacy flat row a synthetic line named "Product", which would shadow
+            // the real name the `productNames` lookup still recovers for those rows.
+            const lineItems = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+            // A cart order has several lines and no single product; name the first
+            // and count the rest, the way the table row renders it. `serverTimestamp`
+            // reads back null until the write lands, so `createdAtMs` — which every
+            // modern writer sets alongside it — covers the local snapshot.
+            const date = (_ref = (_order_createdAt = order.createdAt) == null ? void 0 : (_order_createdAt_toDate = _order_createdAt.toDate) == null ? void 0 : _order_createdAt_toDate.call(_order_createdAt)) != null ? _ref : order.createdAtMs ? new Date(order.createdAtMs) : null;
+            const product = (_ref1 = (_ref2 = (_ref3 = (_lineItems_ = lineItems[0]) == null ? void 0 : _lineItems_.name) != null ? _ref3 : productNames[(_order_productId = order.productId) != null ? _order_productId : '']) != null ? _ref2 : order.productId) != null ? _ref1 : '';
+            const totalCents = Number((_ref4 = (_ref5 = (_lifted_totals = lifted.totals) == null ? void 0 : _lifted_totals.totalCents) != null ? _ref5 : order.amountCents) != null ? _ref4 : 0);
+            const feeCents = Number((_ref6 = (_ref7 = (_lifted_totals1 = lifted.totals) == null ? void 0 : _lifted_totals1.feeCents) != null ? _ref7 : order.feeCents) != null ? _ref6 : 0);
+            const refundedCents = Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0);
+            return [
+                date ? date.toISOString() : '',
+                lineItems.length > 1 ? `${product} +${lineItems.length - 1} more` : product,
+                usd(totalCents),
+                usd(feeCents),
+                (_order_customerEmail = order.customerEmail) != null ? _order_customerEmail : '',
+                (_order_couponCode = order.couponCode) != null ? _order_couponCode : '',
+                (_order_$id = order.$id) != null ? _order_$id : '',
+                lifted.status,
+                (_lifted_channel = lifted.channel) != null ? _lifted_channel : 'online',
+                usd(refundedCents),
+                usd(totalCents - refundedCents)
+            ].map((cell)=>escape(String(cell))).join(',');
+        })
+    ].join('\n');
+}
+/** Appends a timeline event immutably (webhook + console share this). */ export function appendOrderEvent(order, event, detail, atMs = Date.now()) {
+    var _order_timeline;
+    return [
+        ...(_order_timeline = order.timeline) != null ? _order_timeline : [],
+        _extends({
+            atMs,
+            event
+        }, detail ? {
+            detail
+        } : {})
+    ];
+}
+
+//# sourceMappingURL=commerce-orders.js.map