@mohasinac/appkit 4.43.0 → 4.44.0

package/dist/_internal/server/jobs/core/priceIndexRollup.js

@@ -0,0 +1,234 @@
+/**
+ * Core: the realised-price index — what things actually SOLD for here.
+ *
+ * ## Why this exists
+ *
+ * Every price signal we show a seller today is an ASK: the seeded `market`
+ * band is a competitor's listed price, and a competitor's sold-out row proves
+ * the item is GONE, not that it sold at that figure. With 76–93% of listings
+ * across the crawled catalogues never selling, the gap between an ask and a
+ * realised price is the single most useful thing we can tell a seller — and we
+ * are the only party who can measure it on our own sales.
+ *
+ * A seeded blog post already tells sellers to *"check what similar items sold
+ * for on LetItRip in the last 30 days"*, which has never been possible.
+ *
+ * ## 🛑 `market` and `sold` are NEVER blended
+ *
+ * They answer different questions and the gap IS the information. Averaging
+ * them would launder an inference into a measurement. This job writes only the
+ * sold half, into its own collection, and never touches the seeded band.
+ *
+ * ## The authoritative field
+ *
+ * **`OrderDocument.items[].unitPrice`** — and specifically not:
+ *
+ *   `OrderDocument.unitPrice`  the FIRST line's price (`unitPriceFor(items[0])`),
+ *                              wrong for every other line
+ *   `OrderDocument.totalPrice` folds in GST, platform fee, shipping and add-ons
+ *   `BidDocument.status==won`  its own comment: `orderId` is absent on a
+ *                              won-but-unpaid bid
+ *   `OfferDocument==accepted`  an agreement, not a sale. `paid` is the sale
+ *   `product.currentBid`       a display mirror a pending buyout never writes
+ *
+ * Won auctions and accepted offers arrive through the same field via
+ * `lockedPrice`, so one field covers all six acquisition paths and
+ * `sourceContext` labels each for free.
+ *
+ * ## Why daily and never live
+ *
+ * A live index would scan orders per request — the unbounded-per-request
+ * pattern that paused this project on Hobby caps. One pre-computed read per
+ * row, with a visible "prices as of {date}". Deliberately one day stale.
+ */
+import { orderRepository, productRepository } from "../../../../repositories";
+import { priceIndexRepository, } from "../../../../features/categories/repository/price-index.repository";
+/** How far back a band looks. */
+export const PRICE_INDEX_WINDOW_DAYS = 90;
+/**
+ * Hard ceiling on the products scan.
+ *
+ * The scan exists only to build `productId → categorySlugs[0]`, and that join
+ * disappears for future orders once `categorySlugs[0]` is snapshotted onto the
+ * order item (done in the same change as this job). So the cap is a guard
+ * against a catalogue that grows faster than the snapshot backfills, not a
+ * permanent design limit — and it is logged when it bites rather than
+ * truncating silently.
+ */
+const PRODUCT_SCAN_LIMIT = 5000;
+function toDate(v) {
+    if (!v)
+        return null;
+    const d = v instanceof Date ? v : new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * Which acquisition path produced this sale.
+ *
+ * `sourceContext.path` is the richer signal — it distinguishes a settled
+ * auction win from a buy-now, which `orderType` cannot (both are `"auction"`).
+ * Falls back to `orderType`, then to `standard`.
+ */
+function pathOf(order) {
+    const p = order.sourceContext?.path ?? order.orderType;
+    if (p === "auction-won" || p === "auction-buy-now" || p === "auction")
+        return "auction";
+    if (p === "offer-accepted" || p === "offer")
+        return "offer";
+    return "standard";
+}
+/**
+ * 🛑 Completed means delivered AND paid AND not refunded.
+ *
+ * The repo's convention elsewhere is `delivered` alone, and **nothing
+ * currently excludes a delivered-then-refunded order** — whose realised price
+ * is zero. Including one would publish a sale that was undone as evidence of
+ * what things sell for.
+ */
+function isCompleted(order) {
+    if (order.status !== "delivered")
+        return false;
+    if (order.paymentStatus !== "paid")
+        return false;
+    return !(order.refunds && order.refunds.length > 0);
+}
+function median(sorted) {
+    const n = sorted.length;
+    if (n === 0)
+        return 0;
+    const mid = Math.floor(n / 2);
+    const raw = n % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+    return Math.round(raw * 100) / 100;
+}
+function toBand(samples) {
+    const amounts = samples.map((s) => s.amount).sort((a, b) => a - b);
+    const byPath = {};
+    for (const s of samples)
+        byPath[s.via] = (byPath[s.via] ?? 0) + 1;
+    const latest = samples.reduce((best, s) => (!best || s.at > best.at ? s : best), null);
+    return {
+        min: amounts[0],
+        median: median(amounts),
+        max: amounts[amounts.length - 1],
+        sampleSize: samples.length,
+        byPath,
+        ...(latest ? { lastSold: { amount: latest.amount, at: latest.at, via: latest.via } } : {}),
+    };
+}
+/** `YYYYMMDD` in UTC, so the id is stable regardless of where the job runs. */
+function utcDateKey(d) {
+    return `${d.getUTCFullYear()}${String(d.getUTCMonth() + 1).padStart(2, "0")}${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+export async function runPriceIndexRollup(ctx) {
+    const now = new Date();
+    const cutoff = new Date(now.getTime() - PRICE_INDEX_WINDOW_DAYS * 24 * 60 * 60 * 1000);
+    /*
+     * One products scan into a MAP, never N `findById` calls.
+     *
+     * `storeAnalytics.ts:94` does the per-item lookup and it is the pattern not
+     * to copy — an order with 4 items costs 4 reads there, so a 90-day window
+     * over a growing order list is an unbounded read multiplier.
+     */
+    const products = await productRepository.list({
+        page: 1,
+        pageSize: PRODUCT_SCAN_LIMIT,
+    });
+    const rows = products.items ?? [];
+    if (rows.length >= PRODUCT_SCAN_LIMIT) {
+        ctx.logger.warn("priceIndexRollup: product scan saturated — the leaf join may be incomplete", {
+            limit: PRODUCT_SCAN_LIMIT,
+        });
+    }
+    const leafOf = new Map();
+    const typeOf = new Map();
+    for (const p of rows) {
+        if (!p.id)
+            continue;
+        const leaf = p.categorySlugs?.[0];
+        if (leaf)
+            leafOf.set(p.id, leaf);
+        if (p.listingType)
+            typeOf.set(p.id, p.listingType);
+    }
+    const delivered = (await orderRepository.findByStatus("delivered"));
+    /** leafId → listingType → samples */
+    const byLeaf = new Map();
+    let considered = 0;
+    let skippedNoLeaf = 0;
+    for (const order of delivered) {
+        if (!isCompleted(order))
+            continue;
+        const at = toDate(order.orderDate) ?? toDate(order.createdAt);
+        if (!at || at < cutoff)
+            continue;
+        const via = pathOf(order);
+        for (const item of order.items ?? []) {
+            const amount = Number(item.unitPrice ?? 0);
+            if (!Number.isFinite(amount) || amount <= 0)
+                continue;
+            /*
+             * A fully-cancelled line is not a sale. A partially-cancelled one is —
+             * the units that shipped sold at that unit price, and the unit price is
+             * what a band is made of, so the quantity does not weight it.
+             */
+            const live = (item.quantity ?? 1) - (item.cancelledQuantity ?? 0);
+            if (live <= 0)
+                continue;
+            /*
+             * The snapshot first, the join second. New orders carry
+             * `categorySlug` and need no products read at all; older ones fall
+             * back to the map. An item whose product has since been deleted
+             * resolves to neither and is COUNTED AS SKIPPED rather than dropped
+             * silently — a band missing sales is indistinguishable from a quiet
+             * category unless somebody says so.
+             */
+            const leaf = item.categorySlug ?? (item.productId ? leafOf.get(item.productId) : undefined);
+            if (!leaf) {
+                skippedNoLeaf += 1;
+                continue;
+            }
+            const listingType = item.listingType ?? (item.productId ? typeOf.get(item.productId) : undefined) ?? "standard";
+            const types = byLeaf.get(leaf) ?? new Map();
+            const samples = types.get(listingType) ?? [];
+            samples.push({ amount, at, via });
+            types.set(listingType, samples);
+            byLeaf.set(leaf, types);
+            considered += 1;
+        }
+    }
+    const dateKey = utcDateKey(now);
+    let written = 0;
+    for (const [leafId, types] of byLeaf) {
+        const byListingType = {};
+        const point = {};
+        for (const [listingType, samples] of types) {
+            const band = toBand(samples);
+            byListingType[listingType] = band;
+            point[listingType] = { median: band.median, sampleSize: band.sampleSize };
+        }
+        /*
+         * 🛑 Only leaves WITH sales are written, and nothing is ever zeroed.
+         *
+         * An absent band means "we have no sales here", which the UI renders as
+         * silence. A zeroed one would render as "things sell here for ₹0", which
+         * is worse than silence and is exactly what a defaulting write would
+         * manufacture on the first quiet night. A refund removing the last sale in
+         * a leaf therefore leaves a stale band for a day and then it ages out of
+         * the window — which is the correct behaviour for a figure labelled "as
+         * of" a date.
+         */
+        await priceIndexRepository.setForLeaf(leafId, {
+            byListingType,
+            windowDays: PRICE_INDEX_WINDOW_DAYS,
+        });
+        await priceIndexRepository.setDailyPoint(leafId, dateKey, point);
+        written += 1;
+    }
+    ctx.logger.info("priceIndexRollup: complete", {
+        deliveredScanned: delivered.length,
+        salesCounted: considered,
+        leavesWritten: written,
+        skippedNoLeaf,
+        windowDays: PRICE_INDEX_WINDOW_DAYS,
+    });
+}

package/dist/_internal/server/jobs/core/{testerSandboxCleanup.d.ts → testDataCleanup.d.ts}

@@ -14,9 +14,9 @@ import type { JobContext } from "../runtime/types";
  * (This used to be shared with testerSandboxRefresh.ts, which was removed when
  * the tester runner took over fixture state — see scheduled.ts.)
  */
-export declare const SANDBOX_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events", "offers"];
-export interface TesterSandboxCleanupOptions {
+export declare const TEST_DATA_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events", "offers"];
+export interface TestDataCleanupOptions {
     /** true = wipe every isTestData:true doc regardless of testDataExpiresAt (manual force-purge). */
     force?: boolean;
 }
-export declare function runTesterSandboxCleanup(ctx: JobContext, opts?: TesterSandboxCleanupOptions): Promise<void>;
+export declare function runTestDataCleanup(ctx: JobContext, opts?: TestDataCleanupOptions): Promise<void>;

package/dist/_internal/server/jobs/core/{testerSandboxCleanup.js → testDataCleanup.js}

@@ -15,16 +15,16 @@ import { BID_FIELDS } from "../../../../constants/field-names";
  * (This used to be shared with testerSandboxRefresh.ts, which was removed when
  * the tester runner took over fixture state — see scheduled.ts.)
  */
-export const SANDBOX_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events", "offers"];
+export const TEST_DATA_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events", "offers"];
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
-export async function runTesterSandboxCleanup(ctx, opts = {}) {
+export async function runTestDataCleanup(ctx, opts = {}) {
     const cutoff = opts.force ? null : new Date();
     ctx.logger.info(opts.force
         ? "Force-purging all tester sandbox test data"
         : "Sweeping expired tester sandbox test data");
     const allRefs = [];
     let deletedProductIds = [];
-    for (const collection of SANDBOX_COLLECTIONS) {
+    for (const collection of TEST_DATA_COLLECTIONS) {
         const refs = await getTestDataRefs(ctx.db, collection, cutoff);
         allRefs.push(...refs);
         if (collection === "products") {

package/dist/_internal/server/jobs/core/weeklyPayoutEligibility.js

@@ -6,6 +6,7 @@ import { storeRepository, userRepository, orderRepository, payoutRepository, sit
 import { BATCH_LIMIT } from "../handlers/messages";
 import { getDefaultCurrency } from "../../../../core";
 import { computePayoutDeduction } from "../../../shared/fees/calculator";
+import { ordersTaxableValue } from "../../../shared/checkout/order-math";
 export async function runWeeklyPayoutEligibility(ctx) {
     if (ctx.env("FEATURE_PAYOUTS") !== "true") {
         ctx.logger.info("FEATURE_PAYOUTS disabled — skipping weekly payout eligibility");
@@ -42,7 +43,10 @@ export async function runWeeklyPayoutEligibility(ctx) {
             ctx.logger.warn(`Store/seller ${storeId} not found — skipping ${orders.length} order(s)`);
             continue;
         }
-        const grossAmount = orders.reduce((sum, o) => sum + (o.data.totalPrice ?? 0), 0);
+        /* The TAXABLE VALUE — see `orderTaxableValue`. This job and
+         * `autoPayoutEligibility` must agree, or the weekly run and the automatic
+         * one pay different amounts for the same orders. */
+        const grossAmount = ordersTaxableValue(orders.map((o) => o.data));
         const { platformFee, gatewayFee, gstOnFee, netAmount } = computePayoutDeduction(grossAmount, commissions);
         const payoutInput = {
             storeId,

package/dist/_internal/server/jobs/handlers/analyticsAlertEvaluate.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const analyticsAlertEvaluateHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/analyticsAlertEvaluate.js

@@ -0,0 +1,2 @@
+import { runAnalyticsAlertEvaluate } from "../core/analyticsAlertEvaluate";
+export const analyticsAlertEvaluateHandler = runAnalyticsAlertEvaluate;

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -28,6 +28,8 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
+export { priceIndexRollupHandler } from "./priceIndexRollup";
+export { analyticsAlertEvaluateHandler } from "./analyticsAlertEvaluate";
 export { pageViewRollupHandler } from "./pageViewRollup";
 export { pageViewPruneHandler } from "./pageViewPrune";
 export { dailyStatusDigestHandler } from "./dailyStatusDigest";
@@ -52,7 +54,7 @@ export { onUserBanChangeHandler } from "./onUserBanChange";
 export { onScamReportCreateHandler } from "./onScamReportCreate";
 export { onScamReportUpdateHandler } from "./onScamReportUpdate";
 export { draftPruneHandler } from "./draftPrune";
-export { testerSandboxCleanupHandler } from "./testerSandboxCleanup";
+export { testDataCleanupHandler } from "./testDataCleanup";
 export { emiInstallmentReminderHandler } from "./emiInstallmentReminder";
 export { onShipmentItemWriteHandler } from "./onShipmentItemWrite";
 export { onShipmentLotWriteHandler, onShipmentHeaderWriteHandler } from "./onShipmentAllocationSync";

package/dist/_internal/server/jobs/handlers/index.js

@@ -28,6 +28,8 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
+export { priceIndexRollupHandler } from "./priceIndexRollup";
+export { analyticsAlertEvaluateHandler } from "./analyticsAlertEvaluate";
 export { pageViewRollupHandler } from "./pageViewRollup";
 export { pageViewPruneHandler } from "./pageViewPrune";
 export { dailyStatusDigestHandler } from "./dailyStatusDigest";
@@ -64,7 +66,7 @@ export { onScamReportUpdateHandler } from "./onScamReportUpdate";
 // SB-UNI-Y-1 — 30-day draft prune
 export { draftPruneHandler } from "./draftPrune";
 // Tester program — 7-day auto-expiry sweep for the shared admin-seeded test sandbox
-export { testerSandboxCleanupHandler } from "./testerSandboxCleanup";
+export { testDataCleanupHandler } from "./testDataCleanup";
 // Tester program — every-4h revert-live-edits + prune-extras refresh (faster than the 7-day sweep above)
 // EMI — installment reminder + overdue-flagging sweep
 export { emiInstallmentReminderHandler } from "./emiInstallmentReminder";

package/dist/_internal/server/jobs/handlers/messages.d.ts

@@ -55,8 +55,11 @@ export declare const JOB_ERROR_MESSAGES: {
 export declare const CART_TTL_DAYS = 60;
 /** Default Notification TTL in days (matches functions/config/constants). */
 export declare const NOTIFICATION_TTL_DAYS = 30;
-/** Tester sandbox TTL in days — matches testDataExpiresAt() in features/tester/seed-data/tester-ttl.ts. */
-export declare const TESTER_SANDBOX_TTL_DAYS = 7;
+/**
+ * Test-data TTL in days. RE-EXPORTED, not re-declared — this was a second
+ * literal `7` whose only tie to the real one was a comment saying it matched.
+ */
+export { TEST_DATA_TTL_DAYS } from "../../../../seed/test-data-ttl";
 /** Firestore batch write hard ceiling. */
 export declare const BATCH_LIMIT = 500;
 /** Firestore single-query soft ceiling for reconcile sweeps. */

package/dist/_internal/server/jobs/handlers/messages.js

@@ -58,8 +58,11 @@ export const JOB_ERROR_MESSAGES = {
 export const CART_TTL_DAYS = 60;
 /** Default Notification TTL in days (matches functions/config/constants). */
 export const NOTIFICATION_TTL_DAYS = 30;
-/** Tester sandbox TTL in days — matches testDataExpiresAt() in features/tester/seed-data/tester-ttl.ts. */
-export const TESTER_SANDBOX_TTL_DAYS = 7;
+/**
+ * Test-data TTL in days. RE-EXPORTED, not re-declared — this was a second
+ * literal `7` whose only tie to the real one was a comment saying it matched.
+ */
+export { TEST_DATA_TTL_DAYS } from "../../../../seed/test-data-ttl";
 /** Firestore batch write hard ceiling. */
 export const BATCH_LIMIT = 500;
 /** Firestore single-query soft ceiling for reconcile sweeps. */

package/dist/_internal/server/jobs/handlers/priceIndexRollup.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const priceIndexRollupHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/priceIndexRollup.js

@@ -0,0 +1,2 @@
+import { runPriceIndexRollup } from "../core/priceIndexRollup";
+export const priceIndexRollupHandler = runPriceIndexRollup;

package/dist/_internal/server/jobs/handlers/testDataCleanup.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const testDataCleanupHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/testDataCleanup.js

@@ -0,0 +1,2 @@
+import { runTestDataCleanup } from "../core/testDataCleanup";
+export const testDataCleanupHandler = (ctx) => runTestDataCleanup(ctx);

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/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