@mohasinac/appkit 4.42.18 → 4.44.0

package/dist/_internal/shared/actions/action-registry.js

@@ -528,6 +528,40 @@ export const ACTIONS = {
             description: "Navigate to the full product listing for this store.",
             kind: "link",
         },
+        // ── Category description templates (C2c) ─────────────────────────────
+        "apply-template": {
+            iconKey: "edit",
+            id: "store.apply-template",
+            label: "Use this description",
+            ariaLabel: "Fill the description from this category template",
+            description: "Fill the description field from the category's description template, with the listing's own details interpolated.",
+            kind: "secondary",
+            permissions: ["seller", "admin"],
+        },
+        "replace-description": {
+            iconKey: "edit",
+            id: "store.replace-description",
+            label: "Replace description",
+            ariaLabel: "Replace the description you have written with the category template",
+            description: "Overwrite the description with the category's template. The text currently in the field is lost.",
+            /*
+             * 🛑 `danger` with a confirmation, because it destroys authored text.
+             *
+             * The picker only ever offers this when `isDescriptionDirty` — i.e. the
+             * seller has typed something that is not a body we filled in. Rule #7:
+             * an action that cannot be undone needs the confirmation ON the
+             * ActionDef, not a `window.confirm` at the call site, so the copy lives
+             * with the action and is translatable.
+             */
+            kind: "danger",
+            permissions: ["seller", "admin"],
+            confirmation: {
+                title: "Replace what you have written?",
+                body: "The description you typed will be overwritten by the category template. This cannot be undone.",
+                confirmLabel: "Replace it",
+                confirmKind: "danger",
+            },
+        },
         // ── Offer management ─────────────────────────────────────────────────
         "accept-offer": {
             iconKey: "approve",

package/dist/_internal/shared/cache/revalidate-targets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Which PAGE paths a write to a collection makes stale.
+ *
+ * ## Why this exists
+ *
+ * Detail routes used to carry very short `revalidate` windows — 30s on
+ * `auctions/[id]`, 60s on `products/[slug]` — not because anyone wanted that
+ * freshness, but because **the window was the only freshness mechanism in the
+ * app**. Measured 2026-10-09: `revalidatePath` appeared three times in the whole
+ * repository, all `revalidatePath("/")`, and `revalidateTag` zero times.
+ *
+ * Short windows × many unique paths is how you manufacture ISR writes. 95
+ * products at 60s is up to 137K regenerations/day from one route, and the
+ * project was suspended for exceeding 200K ISR writes with 3.1M — the signature
+ * being writes outnumbering reads 3:1, i.e. entries regenerating before anyone
+ * read them twice.
+ *
+ * Invalidation keyed on the WRITE is both cheaper and more correct than any
+ * clock: a product that changed is stale immediately, and one that did not never
+ * regenerates at all.
+ *
+ * ## Contract
+ *
+ * Returns **locale-less** paths. The caller is responsible for prefixing each
+ * with the locales it serves — see the revalidate route, which does that from
+ * `routing.locales`, because prerendered entries live at `/en/...`.
+ *
+ * Paths are returned on a best-effort basis: a caller that cannot supply hints
+ * still gets the always-stale list, which is the part that matters for a
+ * listing. Over-revalidating is cheap (it marks an entry stale; it does not
+ * render). Under-revalidating is the failure that shows a buyer a sold-out
+ * listing as in stock, so when in doubt this returns MORE paths, not fewer.
+ */
+/** What the caller knows about the written document, when it knows anything. */
+export interface RevalidateHints {
+    /** `standard` | `auction` | `pre-order` | … — picks the right detail route. */
+    listingType?: string;
+    /** Full ancestor chain; every category page listing this product goes stale. */
+    categorySlugs?: string[];
+    brandSlug?: string;
+    storeId?: string;
+}
+/**
+ * Page paths made stale by a write to `collection`.
+ *
+ * `id` and `hints` are optional; omitting them yields only the always-stale
+ * listing pages, which is the correct answer for a bulk or unknown write.
+ */
+export declare function revalidateTargetsFor(collection: string, id?: string, hints?: RevalidateHints): string[];

package/dist/_internal/shared/cache/revalidate-targets.js

@@ -0,0 +1,157 @@
+/**
+ * Which PAGE paths a write to a collection makes stale.
+ *
+ * ## Why this exists
+ *
+ * Detail routes used to carry very short `revalidate` windows — 30s on
+ * `auctions/[id]`, 60s on `products/[slug]` — not because anyone wanted that
+ * freshness, but because **the window was the only freshness mechanism in the
+ * app**. Measured 2026-10-09: `revalidatePath` appeared three times in the whole
+ * repository, all `revalidatePath("/")`, and `revalidateTag` zero times.
+ *
+ * Short windows × many unique paths is how you manufacture ISR writes. 95
+ * products at 60s is up to 137K regenerations/day from one route, and the
+ * project was suspended for exceeding 200K ISR writes with 3.1M — the signature
+ * being writes outnumbering reads 3:1, i.e. entries regenerating before anyone
+ * read them twice.
+ *
+ * Invalidation keyed on the WRITE is both cheaper and more correct than any
+ * clock: a product that changed is stale immediately, and one that did not never
+ * regenerates at all.
+ *
+ * ## Contract
+ *
+ * Returns **locale-less** paths. The caller is responsible for prefixing each
+ * with the locales it serves — see the revalidate route, which does that from
+ * `routing.locales`, because prerendered entries live at `/en/...`.
+ *
+ * Paths are returned on a best-effort basis: a caller that cannot supply hints
+ * still gets the always-stale list, which is the part that matters for a
+ * listing. Over-revalidating is cheap (it marks an entry stale; it does not
+ * render). Under-revalidating is the failure that shows a buyer a sold-out
+ * listing as in stock, so when in doubt this returns MORE paths, not fewer.
+ */
+/** Detail route per listing type. Mirrors `ListingTypePlugin.detailRoute`. */
+const PRODUCT_DETAIL_BY_TYPE = {
+    standard: (id) => `/products/${id}`,
+    art: (id) => `/products/${id}`,
+    stickers: (id) => `/products/${id}`,
+    auction: (id) => `/auctions/${id}`,
+    "pre-order": (id) => `/pre-orders/${id}`,
+    "prize-draw": (id) => `/prize-draws/${id}`,
+    classified: (id) => `/classified/${id}`,
+    "digital-code": (id) => `/digital-codes/${id}`,
+    live: (id) => `/live/${id}`,
+};
+/**
+ * Infer the listing type from the id prefix when no hint was supplied.
+ *
+ * The slug prefix system (CLAUDE.md § Slug Prefix System) makes this reliable
+ * for seeded and generated ids — `auction-…`, `preorder-…`, `prizedraw-…` — and
+ * it is only a fallback: the Firestore trigger reads the document and passes
+ * `listingType` explicitly.
+ */
+function listingTypeFromId(id) {
+    if (id.startsWith("auction-"))
+        return "auction";
+    if (id.startsWith("preorder-"))
+        return "pre-order";
+    if (id.startsWith("prizedraw-"))
+        return "prize-draw";
+    if (id.startsWith("classified-"))
+        return "classified";
+    if (id.startsWith("digitalcode-"))
+        return "digital-code";
+    if (id.startsWith("live-"))
+        return "live";
+    if (id.startsWith("art-"))
+        return "art";
+    if (id.startsWith("sticker-"))
+        return "stickers";
+    if (id.startsWith("product-"))
+        return "standard";
+    return undefined;
+}
+function productTargets(id, hints) {
+    const out = ["/", "/products"];
+    if (!id)
+        return out;
+    const type = hints?.listingType ?? listingTypeFromId(id);
+    if (type && PRODUCT_DETAIL_BY_TYPE[type]) {
+        out.push(PRODUCT_DETAIL_BY_TYPE[type](id));
+        // The type's own browse page, when it has one distinct from /products.
+        const browse = PRODUCT_DETAIL_BY_TYPE[type](id).replace(/\/[^/]+$/, "");
+        if (browse && browse !== "/products")
+            out.push(browse);
+    }
+    else {
+        /*
+         * Unknown type: revalidate EVERY detail route for this id rather than
+         * guessing one. At most nine entries marked stale, none of which renders
+         * until requested — strictly cheaper than leaving the real one live.
+         */
+        for (const build of Object.values(PRODUCT_DETAIL_BY_TYPE))
+            out.push(build(id));
+    }
+    // A product's price/stock/status is rendered on every taxonomy page that
+    // lists it. `categorySlugs` is the full ancestor chain, so this covers the
+    // leaf and every parent up to the root.
+    for (const slug of hints?.categorySlugs ?? [])
+        out.push(`/categories/${slug}`);
+    if (hints?.brandSlug)
+        out.push(`/brands/${hints.brandSlug}`);
+    if (hints?.storeId)
+        out.push(`/stores/${hints.storeId}`);
+    return out;
+}
+/**
+ * Page paths made stale by a write to `collection`.
+ *
+ * `id` and `hints` are optional; omitting them yields only the always-stale
+ * listing pages, which is the correct answer for a bulk or unknown write.
+ */
+export function revalidateTargetsFor(collection, id, hints) {
+    let paths;
+    switch (collection) {
+        case "products":
+            paths = productTargets(id, hints);
+            break;
+        case "categories":
+            // Brands and pricing bundles are `categories` rows discriminated by
+            // `categoryType`, so all three detail shapes are marked.
+            paths = ["/", "/categories"];
+            if (id)
+                paths.push(`/categories/${id}`, `/brands/${id}`, `/bundles/${id}`);
+            break;
+        case "blogPosts":
+            paths = ["/", "/blog"];
+            if (id)
+                paths.push(`/blog/${id}`);
+            break;
+        case "events":
+            paths = ["/", "/events"];
+            if (id)
+                paths.push(`/events/${id}`);
+            break;
+        case "reviews":
+            // A new review changes the product's rating and the homepage stat.
+            paths = ["/", "/reviews"];
+            break;
+        case "stores":
+            paths = ["/", "/stores"];
+            if (id)
+                paths.push(`/stores/${id}`);
+            break;
+        case "carouselSlides":
+        case "homepageSections":
+        case "siteSettings":
+            paths = ["/"];
+            break;
+        case "faqs":
+            paths = ["/", "/faqs"];
+            break;
+        default:
+            paths = [];
+    }
+    return Array.from(new Set(paths));
+}

package/dist/_internal/shared/checkout/order-math.d.ts

@@ -101,7 +101,7 @@ export interface LineTaxComponent {
  * `productById` supplies the live `gstRate`; each member's snapshotted rate is
  * the fallback for a member whose listing has since been archived.
  */
-export declare function lineTaxComponentsFor(item: CartItemDocument, productById: Map<string, ProductDocument>): LineTaxComponent[];
+export declare function lineTaxComponentsFor(item: CartItemDocument, productById: Map<string, ProductDocument | null>): LineTaxComponent[];
 /**
  * Total GST for one order group, and the base it was charged on.
  *
@@ -111,10 +111,34 @@ export declare function lineTaxComponentsFor(item: CartItemDocument, productById
  * one and not the other — here that would mean quoting one tax figure and
  * charging another.
  */
-export declare function sumGroupGst(items: readonly CartItemDocument[], productById: Map<string, ProductDocument>, intraState: boolean): {
+export declare function sumGroupGst(items: readonly CartItemDocument[], productById: Map<string, ProductDocument | null>, intraState: boolean): GroupGstSummary;
+/** One rate's rollup within an order group — what Rule 46 asks an invoice to show. */
+export interface GstRateSlice {
+    gstRate: number;
+    taxableAmount: number;
+    cgst: number;
+    sgst: number;
+    igst: number;
+    gstAmount: number;
+}
+/**
+ * What one order group owes, with the split and the rate dimension intact.
+ *
+ * Widened from `{ taxableAmount, gstAmount }` — additive, so both existing
+ * callers keep working while neither has to re-derive a split the per-slice
+ * `calculateGst` calls above already computed correctly.
+ */
+export interface GroupGstSummary {
+    /** Taxable value of slices carrying a POSITIVE rate. */
     taxableAmount: number;
+    /** Taxable value of 0%-rated (exempt) slices. Not part of `taxableAmount`. */
+    exemptAmount: number;
+    cgst: number;
+    sgst: number;
+    igst: number;
     gstAmount: number;
-};
+    byRate: GstRateSlice[];
+}
 /**
  * Split `total` across members in proportion to their list prices, with the
  * rounding remainder pushed onto the LAST member so the parts sum to exactly
@@ -125,6 +149,92 @@ export declare function sumGroupGst(items: readonly CartItemDocument[], productB
  * items), which is the only case where proportion is undefined.
  */
 export declare function allocateAcrossMembers(total: number, weights: number[]): number[];
+/** Exactly the fields `orderGoodsValue` / `orderTaxableValue` read. */
+export interface PayableOrderLike {
+    items?: Array<{
+        quantity: number;
+        unitPrice: number;
+        cancelledQuantity?: number;
+        /** Snapshotted at purchase. Absent or 0 means no tax to back out. */
+        gstRate?: number;
+    }>;
+    /** The flat shape, authoritative when `items` is absent. */
+    quantity?: number;
+    unitPrice?: number;
+    gstRate?: number;
+}
+/**
+ * The GOODS VALUE of an order — the only correct base for a seller payout.
+ *
+ * 🛑 This is NOT `OrderDocument.totalPrice`, and conflating the two was a live
+ * money bug in all four payout paths (`autoPayoutEligibility`,
+ * `weeklyPayoutEligibility`, and both `seller-actions` entry points). That
+ * field is the GRAND TOTAL — `checkout/actions.ts` builds it as
+ * `goods − coupon + shipping + codHandling + whatsappNotify + giftWrap +
+ * shipmentProtection + platformFee + platformFeeGst + emiSurcharge + gstAmount`
+ * — so using it as the payout base did three wrong things at once:
+ *
+ *  1. **paid the seller the GST we collected** and must remit ourselves;
+ *  2. **took the platform fee twice** — the buyer already paid it as a term of
+ *     `totalPrice`, and `computePayoutDeduction` then charged the seller a
+ *     percentage of a figure that already included it;
+ *  3. **computed every percentage on an inflated base**, since shipping, COD
+ *     handling, add-on fees and the EMI surcharge were all inside it.
+ *
+ * The payout base is the **taxable value**, never the gross. That one sentence
+ * also covers GST-inclusive pricing: an inclusive ₹999 @5% backs out to a
+ * ₹951.43 taxable value and that is what is paid, while an exclusive ₹999
+ * charges the buyer ₹1,048.95 and pays ₹999.
+ *
+ * 🛑 Computed from `quantity − cancelledQuantity`, NOT from `item.totalPrice`.
+ * A partial cancellation sets `cancelledQuantity: item.quantity` and
+ * **deliberately leaves `totalPrice` untouched** (`order-actions.ts:97-106`),
+ * so summing `totalPrice` would pay the seller in full for lines the buyer
+ * cancelled. `stock-restore.ts:20` already derives the live quantity this way.
+ *
+ * 🛑 Falls back to the FLAT `quantity × unitPrice` when `items` is absent.
+ * `items?` is optional on `OrderDocument` and the flat fields are the primary
+ * shape, not legacy residue — a bare `Σ items[]` would silently pay **zero**
+ * on any flat-shaped order, which is indistinguishable from "this seller is
+ * owed nothing".
+ */
+export declare function orderGoodsValue(order: PayableOrderLike): number;
+/** Sum of `orderGoodsValue` across orders — the GROSS, not the payout base. */
+export declare function ordersGoodsValue(orders: readonly PayableOrderLike[]): number;
+/**
+ * The TAXABLE VALUE of an order — **the payout base.**
+ *
+ * 🛑 This is the second of two narrowings, and the distinction between them is
+ * worth keeping straight:
+ *
+ *  - C0 established the base is the **goods value**, not the order grand total
+ *    (which folded in GST, the platform fee the buyer already paid, shipping,
+ *    COD handling, add-ons and the EMI surcharge).
+ *  - This establishes it is the **taxable value**, not the gross goods value —
+ *    because every price here is tax-INCLUSIVE, so the goods value still has
+ *    our GST sitting inside it, and paying that out is the very thing C0 set
+ *    out to stop.
+ *
+ * The second narrowing was not possible until the pricing model was settled:
+ * under the old add-on-top math the goods value WAS the taxable value, so the
+ * two were indistinguishable and C0's fix was complete as written.
+ *
+ * One sentence covers both seller modes, which is the reason the flag is an
+ * authoring convenience and nothing more:
+ *
+ *   **the payout base is the taxable value, never the gross.**
+ *
+ *   - inclusive seller, ₹999 @5% → buyer pays ₹999, taxable ₹951.43, payout ₹951.43
+ *   - exclusive seller types ₹999 → grossed up on write to ₹1,048.95, buyer
+ *     pays ₹1,048.95, taxable ₹999.00, payout ₹999.00
+ *
+ * Per ITEM, using each line's own snapshotted `gstRate`: a mixed 5% + 18%
+ * order cannot be backed out with a single blended rate, and an order-level
+ * rate does not exist.
+ */
+export declare function orderTaxableValue(order: PayableOrderLike): number;
+/** Sum of `orderTaxableValue` across orders — the payout base for a batch. */
+export declare function ordersTaxableValue(orders: readonly PayableOrderLike[]): number;
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

package/dist/_internal/shared/checkout/order-math.js

@@ -1,5 +1,5 @@
 import { roundRupees } from "../../../utils/number.formatter";
-import { calculateGst } from "../fees/calculator";
+import { calculateGstInclusive, taxableFromInclusive } from "../fees/calculator";
 /**
  * The single source of truth for "what do we charge for ONE COPY of this line".
  *
@@ -88,7 +88,22 @@ export function lineTotalFor(item, product) {
  * `productById` supplies the live `gstRate`; each member's snapshotted rate is
  * the fallback for a member whose listing has since been archived.
  */
-export function lineTaxComponentsFor(item, productById) {
+export function lineTaxComponentsFor(item, 
+/*
+ * Tolerates a null value, and always did — every read below is
+ * `?.gstRate ?? 0` / `?? null`. The type was merely narrower than the
+ * behaviour, which forced the consumer's create-order route (whose
+ * `findById` map is honestly `| null`) to cast. `lineTotalFor` already
+ * declares `ProductDocument | null` for the same reason.
+ *
+ * 🛑 Caveat worth knowing: a MISSING product yields `gstRate ?? 0`, and
+ * since 2026-10-10 a 0 rate is accumulated into `exemptAmount` — so an
+ * unloadable product would be reported as exempt rather than as unknown.
+ * Every caller validates products before reaching here (the route throws on
+ * a missing or unpublished one), so this is theoretical; it would stop being
+ * theoretical if a caller ever skipped that check.
+ */
+productById) {
     const lineTotal = lineTotalFor(item, productById.get(item.productId) ?? null);
     const members = item.groupMembers;
     if (!members?.length) {
@@ -128,18 +143,94 @@ export function lineTaxComponentsFor(item, productById) {
  * one and not the other — here that would mean quoting one tax figure and
  * charging another.
  */
-export function sumGroupGst(items, productById, intraState) {
+export function sumGroupGst(items, 
+/* `| null` to match `lineTaxComponentsFor` and `lineTotalFor` — see the note
+ * there. The consumer's create-order route holds an honestly-nullable map. */
+productById, intraState) {
     let taxableAmount = 0;
+    let exemptAmount = 0;
+    let cgst = 0;
+    let sgst = 0;
+    let igst = 0;
     let gstAmount = 0;
+    const byRate = new Map();
     for (const item of items) {
         for (const slice of lineTaxComponentsFor(item, productById)) {
-            if (slice.gstRate <= 0)
+            /*
+             * 🛑 A 0%-rated slice is EXEMPT, not absent. It was `continue`d
+             * entirely, so `order.taxableAmount` excluded exempt goods while
+             * `items[]` included them — and no mixed exempt/taxed order could ever
+             * reconcile its own Taxable column against its own summary. It is
+             * accumulated separately instead: representable, without inflating the
+             * base the tax was actually charged on.
+             */
+            if (slice.gstRate <= 0) {
+                exemptAmount += slice.taxable;
                 continue;
-            taxableAmount += slice.taxable;
-            gstAmount += calculateGst(slice.gstRate, intraState, slice.taxable).gstAmount;
+            }
+            /*
+             * 🛑 `slice.taxable` is the line's GROSS share — prices are
+             * tax-INCLUSIVE — so the tax is backed OUT of it, never added on top.
+             * `lineTaxComponentsFor`'s documented invariant ("slices of a line sum
+             * to its line total") stays true of the gross, which is why the
+             * back-out lives here rather than in there.
+             *
+             * ₹999 @ 5% → taxable ₹951.43 + tax ₹47.57 = ₹999.00 exactly.
+             *
+             * `calculateGstInclusive`, not `calculateGst(…, taxableFromInclusive(…))`:
+             * that composition rounds twice and came to ₹999.01, so the invoice
+             * stopped reconciling with the amount charged. Under inclusive pricing
+             * the tax is a PARTITION of a fixed amount, not an addition to it.
+             */
+            const b = calculateGstInclusive(slice.gstRate, intraState, slice.taxable);
+            const slabTaxable = b.taxableAmount;
+            /*
+             * The split comes PER SLICE and is accumulated. `createOrderForGroup`
+             * used to re-derive it from the total with `Math.round(gstAmount / 2)` —
+             * whole rupees, so ₹161.82 split to 81.00/80.82 instead of 80.91/80.91,
+             * and ₹0.52 rounded to 0 and then `|| undefined` dropped the CGST line
+             * off the invoice entirely.
+             */
+            taxableAmount += slabTaxable;
+            cgst += b.cgst;
+            sgst += b.sgst;
+            igst += b.igst;
+            gstAmount += b.gstAmount;
+            /*
+             * Per-rate, because Rule 46 wants taxable value and tax PER RATE on the
+             * invoice. A mixed 5%+18% order cannot produce a compliant document from
+             * one aggregate triple, and re-deriving it downstream means a second
+             * implementation of this loop.
+             */
+            const prev = byRate.get(slice.gstRate);
+            if (prev) {
+                prev.taxableAmount = roundRupees(prev.taxableAmount + slabTaxable);
+                prev.cgst = roundRupees(prev.cgst + b.cgst);
+                prev.sgst = roundRupees(prev.sgst + b.sgst);
+                prev.igst = roundRupees(prev.igst + b.igst);
+                prev.gstAmount = roundRupees(prev.gstAmount + b.gstAmount);
+            }
+            else {
+                byRate.set(slice.gstRate, {
+                    gstRate: slice.gstRate,
+                    taxableAmount: roundRupees(slabTaxable),
+                    cgst: b.cgst,
+                    sgst: b.sgst,
+                    igst: b.igst,
+                    gstAmount: b.gstAmount,
+                });
+            }
         }
     }
-    return { taxableAmount, gstAmount };
+    return {
+        taxableAmount: roundRupees(taxableAmount),
+        exemptAmount: roundRupees(exemptAmount),
+        cgst: roundRupees(cgst),
+        sgst: roundRupees(sgst),
+        igst: roundRupees(igst),
+        gstAmount: roundRupees(gstAmount),
+        byRate: [...byRate.values()].sort((x, y) => x.gstRate - y.gstRate),
+    };
 }
 /**
  * Split `total` across members in proportion to their list prices, with the
@@ -166,6 +257,102 @@ export function allocateAcrossMembers(total, weights) {
     out.push(roundRupees(total - running));
     return out;
 }
+/**
+ * The GOODS VALUE of an order — the only correct base for a seller payout.
+ *
+ * 🛑 This is NOT `OrderDocument.totalPrice`, and conflating the two was a live
+ * money bug in all four payout paths (`autoPayoutEligibility`,
+ * `weeklyPayoutEligibility`, and both `seller-actions` entry points). That
+ * field is the GRAND TOTAL — `checkout/actions.ts` builds it as
+ * `goods − coupon + shipping + codHandling + whatsappNotify + giftWrap +
+ * shipmentProtection + platformFee + platformFeeGst + emiSurcharge + gstAmount`
+ * — so using it as the payout base did three wrong things at once:
+ *
+ *  1. **paid the seller the GST we collected** and must remit ourselves;
+ *  2. **took the platform fee twice** — the buyer already paid it as a term of
+ *     `totalPrice`, and `computePayoutDeduction` then charged the seller a
+ *     percentage of a figure that already included it;
+ *  3. **computed every percentage on an inflated base**, since shipping, COD
+ *     handling, add-on fees and the EMI surcharge were all inside it.
+ *
+ * The payout base is the **taxable value**, never the gross. That one sentence
+ * also covers GST-inclusive pricing: an inclusive ₹999 @5% backs out to a
+ * ₹951.43 taxable value and that is what is paid, while an exclusive ₹999
+ * charges the buyer ₹1,048.95 and pays ₹999.
+ *
+ * 🛑 Computed from `quantity − cancelledQuantity`, NOT from `item.totalPrice`.
+ * A partial cancellation sets `cancelledQuantity: item.quantity` and
+ * **deliberately leaves `totalPrice` untouched** (`order-actions.ts:97-106`),
+ * so summing `totalPrice` would pay the seller in full for lines the buyer
+ * cancelled. `stock-restore.ts:20` already derives the live quantity this way.
+ *
+ * 🛑 Falls back to the FLAT `quantity × unitPrice` when `items` is absent.
+ * `items?` is optional on `OrderDocument` and the flat fields are the primary
+ * shape, not legacy residue — a bare `Σ items[]` would silently pay **zero**
+ * on any flat-shaped order, which is indistinguishable from "this seller is
+ * owed nothing".
+ */
+export function orderGoodsValue(order) {
+    const items = order.items;
+    if (items?.length) {
+        const raw = items.reduce((sum, i) => {
+            const live = Math.max(0, i.quantity - (i.cancelledQuantity ?? 0));
+            return sum + live * i.unitPrice;
+        }, 0);
+        return roundRupees(raw);
+    }
+    return roundRupees((order.quantity ?? 0) * (order.unitPrice ?? 0));
+}
+/** Sum of `orderGoodsValue` across orders — the GROSS, not the payout base. */
+export function ordersGoodsValue(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderGoodsValue(o), 0));
+}
+/**
+ * The TAXABLE VALUE of an order — **the payout base.**
+ *
+ * 🛑 This is the second of two narrowings, and the distinction between them is
+ * worth keeping straight:
+ *
+ *  - C0 established the base is the **goods value**, not the order grand total
+ *    (which folded in GST, the platform fee the buyer already paid, shipping,
+ *    COD handling, add-ons and the EMI surcharge).
+ *  - This establishes it is the **taxable value**, not the gross goods value —
+ *    because every price here is tax-INCLUSIVE, so the goods value still has
+ *    our GST sitting inside it, and paying that out is the very thing C0 set
+ *    out to stop.
+ *
+ * The second narrowing was not possible until the pricing model was settled:
+ * under the old add-on-top math the goods value WAS the taxable value, so the
+ * two were indistinguishable and C0's fix was complete as written.
+ *
+ * One sentence covers both seller modes, which is the reason the flag is an
+ * authoring convenience and nothing more:
+ *
+ *   **the payout base is the taxable value, never the gross.**
+ *
+ *   - inclusive seller, ₹999 @5% → buyer pays ₹999, taxable ₹951.43, payout ₹951.43
+ *   - exclusive seller types ₹999 → grossed up on write to ₹1,048.95, buyer
+ *     pays ₹1,048.95, taxable ₹999.00, payout ₹999.00
+ *
+ * Per ITEM, using each line's own snapshotted `gstRate`: a mixed 5% + 18%
+ * order cannot be backed out with a single blended rate, and an order-level
+ * rate does not exist.
+ */
+export function orderTaxableValue(order) {
+    const items = order.items;
+    if (items?.length) {
+        const raw = items.reduce((sum, i) => {
+            const live = Math.max(0, i.quantity - (i.cancelledQuantity ?? 0));
+            return sum + taxableFromInclusive(live * i.unitPrice, i.gstRate ?? 0);
+        }, 0);
+        return roundRupees(raw);
+    }
+    return taxableFromInclusive((order.quantity ?? 0) * (order.unitPrice ?? 0), order.gstRate ?? 0);
+}
+/** Sum of `orderTaxableValue` across orders — the payout base for a batch. */
+export function ordersTaxableValue(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderTaxableValue(o), 0));
+}
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one