@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/_internal/shared/features/shipping/parcel.d.ts

@@ -79,6 +79,129 @@ export declare function normaliseDimensions(d: ParcelSource["dimensionsCm"]): Pa
  * whichever tier won on weight would discard information that exists.
  */
 export declare function resolveParcel(shipment: ParcelSource | null | undefined, product: ParcelSource | null | undefined, category: ParcelSource | null | undefined): Parcel | null;
+/**
+ * Divisors, by service class.
+ *
+ * A carrier sells space, not mass, so it bills the greater of actual weight and
+ * `l × w × h ÷ divisor`. The divisor is the whole ballgame on this catalogue:
+ * collectible packaging is mostly air, so for a stadium box the volumetric
+ * figure is ~5× the actual and no per-kilo negotiation touches it.
+ *
+ * 🛑 `surfaceTight` is not a typo. Some Indian surface B2C plans quote ÷4000,
+ * which is a silent 25% increase over ÷5000 on every bulky parcel and is
+ * never the number on the front of the rate card. Read the contract, then set
+ * this per carrier — do not assume 5000 because it is the common default.
+ *
+ * Air uses a LARGER divisor, which means a very light bulky box can genuinely
+ * cost less by air than by surface. That is counter-intuitive and real.
+ */
+export declare const VOLUMETRIC_DIVISORS: {
+    readonly surfaceTight: 4000;
+    readonly standard: 5000;
+    readonly air: 6000;
+};
+export declare const DEFAULT_VOLUMETRIC_DIVISOR: 5000;
+/**
+ * Where a parcel sits against the two thresholds, and therefore which carrier
+ * class is cheaper. See `carrierClassFor` for why these numbers.
+ */
+export declare const VOLUMETRIC_RATIO_THRESHOLDS: {
+    /** Below this the two weights are close enough that the rate card decides. */
+    readonly private: 1.5;
+    /** At or above this the box is mostly air and a postal service wins. */
+    readonly postal: 2;
+};
+/**
+ * The first billing slab, in grams — the region where R means nothing.
+ *
+ * 🛑 This guard exists because the ratio rule is WRONG below it, and the error
+ * was caught by checking the rule against real tariffs instead of trusting it.
+ *
+ * A single boxed bey is 250 g actual / 448 g volumetric — R 1.79, which the
+ * thresholds above call `"either"`. The real bill at >2000 km is ₹106 by Speed
+ * Post against ₹50 by private courier: private wins by 2×, not "either".
+ *
+ * The reason is that both figures land inside each carrier's MINIMUM charge, so
+ * the comparison is floor against floor and the ratio describes nothing. India
+ * Post's 201–500 g floor is ₹90; a private first slab is around ₹42. Whenever
+ * both weights sit in that first slab, the lower floor wins and that is private.
+ */
+export declare const FIRST_SLAB_G = 500;
+export interface ChargeableWeight {
+    actualG: number;
+    /**
+     * `null` when the dimension triple is unknown — NEVER 0.
+     *
+     * A carrier with no dimensions bills actual weight, so `chargeableG` is still
+     * correct in that case. But a `0` here would read as "this box has no volume",
+     * and `ratio` would compute to 0, which routes a stadium to the private
+     * carrier that bills it at 7.3 kg. Unknown has to stay distinguishable from
+     * dense — same discipline as `resolveParcel` refusing to return weight 0.
+     */
+    volumetricG: number | null;
+    /** `max(actual, volumetric)` — what you are billed for. */
+    chargeableG: number;
+    divisor: number;
+    billedOn: "actual" | "volumetric";
+    /**
+     * **The R value**: volumetric ÷ actual, 2dp. `null` without dimensions.
+     *
+     * 1 means the box is exactly at the divisor's break-even density. Above 1 you
+     * are paying for air; below 1 the volume is free and actual weight bills.
+     */
+    ratio: number | null;
+    /** Packed density in kg/m³. `null` without dimensions. */
+    densityKgM3: number | null;
+    /**
+     * The density at which volumetric starts to bite, derived from the divisor
+     * rather than hardcoded: `1e6 / divisor`. 200 kg/m³ at ÷5000, 250 at ÷4000,
+     * ~167 at ÷6000. A parcel below this is billed on volume.
+     */
+    breakEvenKgM3: number;
+}
+/** Volumetric weight in grams. `l × w × h ÷ divisor` is kilos, hence ×1000. */
+export declare function volumetricWeightG(d: ParcelDimensionsCm, divisor?: number): number;
+/**
+ * What this parcel is billed at, and by how much volume beats mass.
+ *
+ * Pure arithmetic — it reports, it does not decide. `carrierClassFor` turns the
+ * result into a routing opinion, deliberately as a separate step so a surface
+ * can show the numbers without adopting the recommendation.
+ */
+export declare function chargeableWeight(parcel: Pick<Parcel, "weightG" | "dimensionsCm">, divisor?: number): ChargeableWeight;
+/**
+ * Which carrier class is cheaper for this parcel, on freight alone.
+ *
+ * India Post Speed Post bills ACTUAL weight and applies no volumetric
+ * calculation; every private carrier bills the greater of the two. So the
+ * freight comparison reduces to the R value:
+ *
+ *   R < 1.5   the two weights are close; the rate card decides, and a private
+ *             card is usually cheaper at low weight → `"private"`
+ *   1.5 ≤ R < 2   genuinely close; decide on pincode serviceability and
+ *             whether the item needs insurance → `"either"`
+ *   R ≥ 2     the box is mostly air and postal is materially cheaper → `"postal"`
+ *
+ * 🛑 `"unknown"` when dimensions are missing, and callers must not collapse it
+ * into a default. Defaulting to `"private"` is precisely the wrong way round:
+ * the parcels whose dimensions nobody recorded are disproportionately the big
+ * awkward ones, which are the parcels this function exists to divert.
+ *
+ * 🛑 This is a FREIGHT opinion and nothing more. Above roughly ₹8,000 of order
+ * value the decision stops being about freight — the delta is a few hundred
+ * rupees against an uninsured loss of the whole item — so an order-value test
+ * and serviceability both outrank this. It answers "which is cheaper", never
+ * "which should we book".
+ *
+ * ## Where it is weakest, stated rather than hidden
+ *
+ * At HIGH weight the per-additional-slab rates start to matter more than the
+ * ratio, and those are negotiated. A 8 kg / 14 kg parcel is R 1.75 → `"either"`,
+ * while one representative card puts it at ₹991 postal against ₹1,197 private —
+ * a real 21% gap the ratio does not see. `"either"` is the honest answer there:
+ * it means your own card decides, not that the two are equal.
+ */
+export declare function carrierClassFor(c: Pick<ChargeableWeight, "ratio" | "actualG" | "volumetricG">): "private" | "either" | "postal" | "unknown";
 /**
  * The weight of a whole order group — what a single shipment actually carries.
  *

package/dist/_internal/shared/features/shipping/parcel.js

@@ -88,6 +88,145 @@ export function resolveParcel(shipment, product, category) {
     }
     return { weightG, source, ...(dimensionsCm ? { dimensionsCm } : {}) };
 }
+/* ── Volumetric weight — what the carrier actually bills ──────────────────── */
+/**
+ * Divisors, by service class.
+ *
+ * A carrier sells space, not mass, so it bills the greater of actual weight and
+ * `l × w × h ÷ divisor`. The divisor is the whole ballgame on this catalogue:
+ * collectible packaging is mostly air, so for a stadium box the volumetric
+ * figure is ~5× the actual and no per-kilo negotiation touches it.
+ *
+ * 🛑 `surfaceTight` is not a typo. Some Indian surface B2C plans quote ÷4000,
+ * which is a silent 25% increase over ÷5000 on every bulky parcel and is
+ * never the number on the front of the rate card. Read the contract, then set
+ * this per carrier — do not assume 5000 because it is the common default.
+ *
+ * Air uses a LARGER divisor, which means a very light bulky box can genuinely
+ * cost less by air than by surface. That is counter-intuitive and real.
+ */
+export const VOLUMETRIC_DIVISORS = {
+    surfaceTight: 4000,
+    standard: 5000,
+    air: 6000,
+};
+export const DEFAULT_VOLUMETRIC_DIVISOR = VOLUMETRIC_DIVISORS.standard;
+/**
+ * Where a parcel sits against the two thresholds, and therefore which carrier
+ * class is cheaper. See `carrierClassFor` for why these numbers.
+ */
+export const VOLUMETRIC_RATIO_THRESHOLDS = {
+    /** Below this the two weights are close enough that the rate card decides. */
+    private: 1.5,
+    /** At or above this the box is mostly air and a postal service wins. */
+    postal: 2,
+};
+/**
+ * The first billing slab, in grams — the region where R means nothing.
+ *
+ * 🛑 This guard exists because the ratio rule is WRONG below it, and the error
+ * was caught by checking the rule against real tariffs instead of trusting it.
+ *
+ * A single boxed bey is 250 g actual / 448 g volumetric — R 1.79, which the
+ * thresholds above call `"either"`. The real bill at >2000 km is ₹106 by Speed
+ * Post against ₹50 by private courier: private wins by 2×, not "either".
+ *
+ * The reason is that both figures land inside each carrier's MINIMUM charge, so
+ * the comparison is floor against floor and the ratio describes nothing. India
+ * Post's 201–500 g floor is ₹90; a private first slab is around ₹42. Whenever
+ * both weights sit in that first slab, the lower floor wins and that is private.
+ */
+export const FIRST_SLAB_G = 500;
+/** Volumetric weight in grams. `l × w × h ÷ divisor` is kilos, hence ×1000. */
+export function volumetricWeightG(d, divisor = DEFAULT_VOLUMETRIC_DIVISOR) {
+    if (!(divisor > 0)) {
+        throw new RangeError(`volumetricWeightG: divisor must be > 0, got ${divisor}`);
+    }
+    return Math.round(((d.l * d.w * d.h) / divisor) * 1000);
+}
+/**
+ * What this parcel is billed at, and by how much volume beats mass.
+ *
+ * Pure arithmetic — it reports, it does not decide. `carrierClassFor` turns the
+ * result into a routing opinion, deliberately as a separate step so a surface
+ * can show the numbers without adopting the recommendation.
+ */
+export function chargeableWeight(parcel, divisor = DEFAULT_VOLUMETRIC_DIVISOR) {
+    const actualG = parcel.weightG;
+    const breakEvenKgM3 = Math.round((1000000 / divisor) * 10) / 10;
+    const d = parcel.dimensionsCm;
+    if (!d) {
+        return {
+            actualG,
+            volumetricG: null,
+            chargeableG: actualG,
+            divisor,
+            billedOn: "actual",
+            ratio: null,
+            densityKgM3: null,
+            breakEvenKgM3,
+        };
+    }
+    const volumetricG = volumetricWeightG(d, divisor);
+    const cm3 = d.l * d.w * d.h;
+    return {
+        actualG,
+        volumetricG,
+        chargeableG: Math.max(actualG, volumetricG),
+        divisor,
+        billedOn: volumetricG > actualG ? "volumetric" : "actual",
+        ratio: actualG > 0 ? Math.round((volumetricG / actualG) * 100) / 100 : null,
+        densityKgM3: cm3 > 0 ? Math.round(((actualG * 1000) / cm3) * 10) / 10 : null,
+        breakEvenKgM3,
+    };
+}
+/**
+ * Which carrier class is cheaper for this parcel, on freight alone.
+ *
+ * India Post Speed Post bills ACTUAL weight and applies no volumetric
+ * calculation; every private carrier bills the greater of the two. So the
+ * freight comparison reduces to the R value:
+ *
+ *   R < 1.5   the two weights are close; the rate card decides, and a private
+ *             card is usually cheaper at low weight → `"private"`
+ *   1.5 ≤ R < 2   genuinely close; decide on pincode serviceability and
+ *             whether the item needs insurance → `"either"`
+ *   R ≥ 2     the box is mostly air and postal is materially cheaper → `"postal"`
+ *
+ * 🛑 `"unknown"` when dimensions are missing, and callers must not collapse it
+ * into a default. Defaulting to `"private"` is precisely the wrong way round:
+ * the parcels whose dimensions nobody recorded are disproportionately the big
+ * awkward ones, which are the parcels this function exists to divert.
+ *
+ * 🛑 This is a FREIGHT opinion and nothing more. Above roughly ₹8,000 of order
+ * value the decision stops being about freight — the delta is a few hundred
+ * rupees against an uninsured loss of the whole item — so an order-value test
+ * and serviceability both outrank this. It answers "which is cheaper", never
+ * "which should we book".
+ *
+ * ## Where it is weakest, stated rather than hidden
+ *
+ * At HIGH weight the per-additional-slab rates start to matter more than the
+ * ratio, and those are negotiated. A 8 kg / 14 kg parcel is R 1.75 → `"either"`,
+ * while one representative card puts it at ₹991 postal against ₹1,197 private —
+ * a real 21% gap the ratio does not see. `"either"` is the honest answer there:
+ * it means your own card decides, not that the two are equal.
+ */
+export function carrierClassFor(c) {
+    if (c.ratio == null)
+        return "unknown";
+    // Both weights inside the first slab → floor vs floor; see FIRST_SLAB_G.
+    if (c.actualG <= FIRST_SLAB_G &&
+        c.volumetricG != null &&
+        c.volumetricG <= FIRST_SLAB_G) {
+        return "private";
+    }
+    if (c.ratio >= VOLUMETRIC_RATIO_THRESHOLDS.postal)
+        return "postal";
+    if (c.ratio >= VOLUMETRIC_RATIO_THRESHOLDS.private)
+        return "either";
+    return "private";
+}
 /**
  * The weight of a whole order group — what a single shipment actually carries.
  *

package/dist/_internal/shared/features/site-settings/fees.d.ts

@@ -38,17 +38,25 @@ export interface BuyerFacingFees {
     codHandlingFeeCap?: number;
     codHandlingFeePercent?: number;
     codDepositPercent?: number;
+    /** Commission rate applied to the cart subtotal, before the cap. */
+    platformFeePercent?: number;
+    /** Rupee ceiling on the commission — the reason a ₹39,500 order pays ₹10. */
+    platformFeeMax?: number;
+    /** GST rate levied on the commission actually charged (never on the uncapped figure). */
+    gstPercent?: number;
+    /** Rupee floor on `platformFee + gstOnFee` combined. */
+    minimumTransactionFee?: number;
 }
 /**
- * Withheld on purpose (15 of 25): platformFeePercent, gstPercent,
- * minimumTransactionFee, platformFeeMax, gatewayFeePercent,
- * sellerShippingFixed, platformShippingPercent, platformShippingFixedMin,
- * autoPayoutWindowDays, payoutHoldDays, minPayoutAmount, auctionListingFee,
- * preOrderListingFee, featuredSlotFee, promotedSlotFee.
+ * Withheld on purpose (11 of 25): gatewayFeePercent, sellerShippingFixed,
+ * platformShippingPercent, platformShippingFixedMin, autoPayoutWindowDays,
+ * payoutHoldDays, minPayoutAmount, auctionListingFee, preOrderListingFee,
+ * featuredSlotFee, promotedSlotFee — plus `surchargeSellerSharePercent`, which
+ * lives on the EMI block and is excluded by `BuyerEmiSettings` below.
  *
- * The buyer still SEES the platform fee and GST — as computed amounts in the
- * server pricing preview (`CartPriceBreakdownData`), never as the rates that
- * produced them.
+ * Every one of those prices something between us and a seller or a gateway.
+ * None of them changes what the buyer is asked to pay, so none of them has a
+ * reader in a browser.
  */
 export declare function toBuyerFacingFees(commissions: SiteSettingsDocument["commissions"] | null | undefined): BuyerFacingFees | null;
 /**

package/dist/_internal/shared/features/site-settings/fees.js

@@ -1,13 +1,13 @@
 /**
- * Withheld on purpose (15 of 25): platformFeePercent, gstPercent,
- * minimumTransactionFee, platformFeeMax, gatewayFeePercent,
- * sellerShippingFixed, platformShippingPercent, platformShippingFixedMin,
- * autoPayoutWindowDays, payoutHoldDays, minPayoutAmount, auctionListingFee,
- * preOrderListingFee, featuredSlotFee, promotedSlotFee.
+ * Withheld on purpose (11 of 25): gatewayFeePercent, sellerShippingFixed,
+ * platformShippingPercent, platformShippingFixedMin, autoPayoutWindowDays,
+ * payoutHoldDays, minPayoutAmount, auctionListingFee, preOrderListingFee,
+ * featuredSlotFee, promotedSlotFee — plus `surchargeSellerSharePercent`, which
+ * lives on the EMI block and is excluded by `BuyerEmiSettings` below.
  *
- * The buyer still SEES the platform fee and GST — as computed amounts in the
- * server pricing preview (`CartPriceBreakdownData`), never as the rates that
- * produced them.
+ * Every one of those prices something between us and a seller or a gateway.
+ * None of them changes what the buyer is asked to pay, so none of them has a
+ * reader in a browser.
  */
 export function toBuyerFacingFees(commissions) {
     if (!commissions)
@@ -24,6 +24,10 @@ export function toBuyerFacingFees(commissions) {
         codHandlingFeeCap: commissions.codHandlingFeeCap,
         codHandlingFeePercent: commissions.codHandlingFeePercent,
         codDepositPercent: commissions.codDepositPercent,
+        platformFeePercent: commissions.platformFeePercent,
+        platformFeeMax: commissions.platformFeeMax,
+        gstPercent: commissions.gstPercent,
+        minimumTransactionFee: commissions.minimumTransactionFee,
     };
 }
 export function toBuyerEmiSettings(emi) {

package/dist/_internal/shared/fees/explain.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Plain-language derivations for every fee line a buyer is shown.
+ *
+ * 🛑 The problem this solves is not presentation. The Order Summary listed
+ * `EMI surcharge ₹2,133.00`, `Platform fee ₹10.00` and `GST on platform fee
+ * ₹1.80` beside a `₹39,500.00` subtotal, and **none of the three could be
+ * checked by the person paying them.** ₹2,133 on ₹39,500 is 5.4% — a buyer has
+ * no way to tell whether that is a rate, a tenure, a rounding error or a bug,
+ * and the only honest response to an unexplained charge is to distrust it.
+ *
+ * ── Why the STRINGS live here and not in the component ────────────────────
+ *
+ * Each sentence is a claim about how a number was computed, and the number is
+ * computed in `calculator.ts` / `emi/schedule.ts`. Putting the sentence beside
+ * a `<Line>` would make it a second, prose implementation of the same rule —
+ * free to drift the moment a cap moves (Root Cause #75: a rule reachable by
+ * copy-paste gets copied, and the copy never learns about the branch added
+ * later). These functions read the SAME rate fields the calculators read.
+ *
+ * ── Why they take the CHARGED amount as an argument ───────────────────────
+ *
+ * They explain the figure actually on screen; they do not recompute it. If a
+ * derivation and the rendered amount ever disagree, the explanation must say
+ * so rather than quietly print a second, prettier number — so each function
+ * ends at the charged value and describes the route to it.
+ *
+ * 🛑 NOTHING HERE MAY NAME A SELLER-SIDE RATE. `surchargeSellerSharePercent`
+ * (the platform/seller split of the EMI surcharge), `gatewayFeePercent`,
+ * `payoutHoldDays` and `minPayoutAmount` are `PRIVATE_*_FIELDS`
+ * (Root Cause #70). The EMI functions below are typed against
+ * `BuyerEmiSettings`, which excludes the split structurally — so the omission
+ * is enforced by `tsc`, not by this paragraph.
+ */
+import type { BuyerEmiSettings, BuyerFacingFees } from "../features/site-settings/fees";
+import type { BuyerEmiQuote } from "../features/emi/schedule";
+/** One rendered explanation: a short claim plus the steps behind it. */
+export interface FeeDerivation {
+    /** One sentence answering "why am I paying this". */
+    summary: string;
+    /** The arithmetic, one step per line, in the order it is applied. */
+    steps: string[];
+}
+/**
+ * The platform commission.
+ *
+ * The cap is the interesting half and the reason this needed explaining at
+ * all: on a ₹39,500 order the uncapped commission is large and the charge is
+ * ₹10, so the number on screen bears no visible relation to the subtotal.
+ */
+export declare function explainPlatformFee(subtotal: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+/**
+ * GST on the commission.
+ *
+ * 🛑 Levied on the commission ACTUALLY CHARGED, never on the uncapped figure —
+ * which is the one thing a buyer checking ₹1.80 against a ₹39,500 subtotal
+ * would get wrong.
+ */
+export declare function explainGstOnPlatformFee(platformFee: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+/**
+ * The EMI surcharge — the cost of credit, stated as a cost of credit.
+ *
+ * 🛑 Takes a `BuyerEmiQuote`, which is `computeBuyerEmiQuote`'s return type and
+ * carries no surcharge split. `computeEmiSchedule`'s richer result is
+ * assignable to it, so the type does not stop a server caller passing the
+ * wrong one — but nothing here reads a field that only exists on the wider
+ * shape, so no split can be printed either.
+ */
+export declare function explainEmiSurcharge(sellerSubtotal: number, tenureMonths: number, quote: BuyerEmiQuote, emi: BuyerEmiSettings | null, currency?: string): FeeDerivation | null;
+/** COD handling — a cap that bites on most carts, same shape as the commission. */
+export declare function explainCodHandlingFee(subtotal: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+/**
+ * Every derivation a price breakdown can render, keyed by the line it belongs
+ * to. A key with no entry simply renders no disclosure — a line we cannot
+ * explain says nothing rather than guessing.
+ */
+export interface FeeDerivations {
+    platformFee?: FeeDerivation | null;
+    gstOnFee?: FeeDerivation | null;
+    emiSurcharge?: FeeDerivation | null;
+    codHandlingFee?: FeeDerivation | null;
+}

package/dist/_internal/shared/fees/explain.js

@@ -0,0 +1,101 @@
+import { formatCurrency } from "../../../utils/number.formatter.js";
+/** `2` → `"2%"`, `2.5` → `"2.5%"` — no trailing `.0`. */
+function pct(value) {
+    return `${Number(value.toFixed(2))}%`;
+}
+/**
+ * The platform commission.
+ *
+ * The cap is the interesting half and the reason this needed explaining at
+ * all: on a ₹39,500 order the uncapped commission is large and the charge is
+ * ₹10, so the number on screen bears no visible relation to the subtotal.
+ */
+export function explainPlatformFee(subtotal, charged, fees, currency = "INR") {
+    if (!fees || fees.platformFeePercent === undefined)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    const uncapped = (subtotal * fees.platformFeePercent) / 100;
+    const steps = [
+        `${pct(fees.platformFeePercent)} of ${money(subtotal)} = ${money(uncapped)}`,
+    ];
+    if (fees.platformFeeMax !== undefined && uncapped > fees.platformFeeMax) {
+        steps.push(`Capped at ${money(fees.platformFeeMax)} — you pay the cap, not the percentage`);
+    }
+    /*
+     * The floor is defined on `platformFee + gstOnFee` COMBINED and is applied
+     * once, inside `allocateCheckoutFees`, as extra platform fee with no GST of
+     * its own. So it is mentioned here and never on the GST line — see the D41
+     * note in `calculator.ts`.
+     */
+    if (fees.minimumTransactionFee !== undefined && charged > Math.min(uncapped, fees.platformFeeMax ?? uncapped)) {
+        steps.push(`Raised to meet the ${money(fees.minimumTransactionFee)} minimum transaction fee, which covers the commission and its GST together`);
+    }
+    steps.push(`You pay ${money(charged)}`);
+    return {
+        summary: fees.platformFeeMax !== undefined && uncapped > fees.platformFeeMax
+            ? `Our commission is ${pct(fees.platformFeePercent)}, capped at ${money(fees.platformFeeMax)} per order.`
+            : `Our commission is ${pct(fees.platformFeePercent)} of the order.`,
+        steps,
+    };
+}
+/**
+ * GST on the commission.
+ *
+ * 🛑 Levied on the commission ACTUALLY CHARGED, never on the uncapped figure —
+ * which is the one thing a buyer checking ₹1.80 against a ₹39,500 subtotal
+ * would get wrong.
+ */
+export function explainGstOnPlatformFee(platformFee, charged, fees, currency = "INR") {
+    if (!fees || fees.gstPercent === undefined)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    return {
+        summary: `GST at ${pct(fees.gstPercent)}, charged on our commission — not on the price of the items.`,
+        steps: [
+            `${pct(fees.gstPercent)} of the ${money(platformFee)} commission = ${money(charged)}`,
+            "Item prices already include their own GST, shown below the total",
+        ],
+    };
+}
+/**
+ * The EMI surcharge — the cost of credit, stated as a cost of credit.
+ *
+ * 🛑 Takes a `BuyerEmiQuote`, which is `computeBuyerEmiQuote`'s return type and
+ * carries no surcharge split. `computeEmiSchedule`'s richer result is
+ * assignable to it, so the type does not stop a server caller passing the
+ * wrong one — but nothing here reads a field that only exists on the wider
+ * shape, so no split can be printed either.
+ */
+export function explainEmiSurcharge(sellerSubtotal, tenureMonths, quote, emi, currency = "INR") {
+    if (!emi)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    const principal = sellerSubtotal - quote.tokenAmount;
+    const perMonth = quote.installments[0]?.amount ?? 0;
+    return {
+        summary: `Spreading ${money(sellerSubtotal)} over ${tenureMonths} months costs ${money(quote.surchargeAmount)} — that is the total cost of credit.`,
+        steps: [
+            `Token paid today: ${pct(emi.tokenPercent)} of ${money(sellerSubtotal)} = ${money(quote.tokenAmount)}`,
+            `Financed amount: ${money(sellerSubtotal)} − ${money(quote.tokenAmount)} = ${money(principal)}`,
+            `Surcharge: ${pct(emi.surchargePercentPerMonth)} of ${money(principal)} per month × ${tenureMonths} months = ${money(quote.surchargeAmount)}`,
+            `Repaid over ${tenureMonths} instalments of about ${money(perMonth)}, due on day ${emi.billingDay} of each month`,
+            `Total you will pay: ${money(quote.tokenAmount)} + ${money(quote.remainingBalance)} = ${money(quote.tokenAmount + quote.remainingBalance)}`,
+        ],
+    };
+}
+/** COD handling — a cap that bites on most carts, same shape as the commission. */
+export function explainCodHandlingFee(subtotal, charged, fees, currency = "INR") {
+    if (!fees || fees.codHandlingFeePercent === undefined)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    const uncapped = (subtotal * fees.codHandlingFeePercent) / 100;
+    const steps = [`${pct(fees.codHandlingFeePercent)} of ${money(subtotal)} = ${money(uncapped)}`];
+    if (fees.codHandlingFeeCap !== undefined && uncapped > fees.codHandlingFeeCap) {
+        steps.push(`Capped at ${money(fees.codHandlingFeeCap)}`);
+    }
+    steps.push(`You pay ${money(charged)}`);
+    return {
+        summary: "What it costs us to collect cash at your door and bank it.",
+        steps,
+    };
+}

package/dist/_internal/shared/history/index.d.ts

@@ -1,4 +1,4 @@
 export type { HistoryActorRole, HistoryActor, FieldChange, StatusChangeEntry, AppendHistoryResult, SerialisedStatusChangeEntry, } from "./types";
-export { STATUS_HISTORY_MAX } from "./types";
+export { STATUS_HISTORY_MAX, HISTORY_ACTOR_ROLE } from "./types";
 export type { BuildHistoryEntryInput } from "./history";
 export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/index.js

@@ -1,2 +1,2 @@
-export { STATUS_HISTORY_MAX } from "./types.js";
+export { STATUS_HISTORY_MAX, HISTORY_ACTOR_ROLE } from "./types.js";
 export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history.js";

package/dist/_internal/shared/history/types.d.ts

@@ -9,7 +9,13 @@ import type { FirestoreValue } from "../../../schemas/types";
  * entities had any history at all — `ads`, built inline in a route handler
  * with no type and no reuse.
  */
-export type HistoryActorRole = "buyer" | "seller" | "admin" | "system";
+export declare const HISTORY_ACTOR_ROLE: {
+    readonly BUYER: "buyer";
+    readonly SELLER: "seller";
+    readonly ADMIN: "admin";
+    readonly SYSTEM: "system";
+};
+export type HistoryActorRole = (typeof HISTORY_ACTOR_ROLE)[keyof typeof HISTORY_ACTOR_ROLE];
 export interface HistoryActor {
     /** Firebase Auth uid. Absent for `system` (cron jobs, Firestore triggers). */
     uid?: string;

package/dist/_internal/shared/history/types.js

@@ -1,3 +1,28 @@
+/**
+ * Generic entity status history — the shape shared by every entity that
+ * records how it got to its current state.
+ *
+ * Built for orders first (W2) and adopted by stores, payouts, offers, bids,
+ * support tickets, scammer profiles, catalogue approvals, shipments and
+ * returns in W15. Before this existed, exactly ONE of ~40 status-bearing
+ * entities had any history at all — `ads`, built inline in a route handler
+ * with no type and no reuse.
+ */
+/*
+ * 🛑 This is an ACTOR KIND, not a `UserDocument.role`. No user has the role
+ * "buyer" — a buyer's stored role is "user" — so the two namespaces must never
+ * be compared, and `audit-phantom-buyer-role` exists to catch exactly that
+ * mistake in a runtime auth gate.
+ *
+ * The constant below is what a gate should compare against: it names the
+ * namespace at the call site, where a bare `"buyer"` literal cannot.
+ */
+export const HISTORY_ACTOR_ROLE = {
+    BUYER: "buyer",
+    SELLER: "seller",
+    ADMIN: "admin",
+    SYSTEM: "system",
+};
 /**
  * Cap for any history array. Matches `HISTORY_MAX`'s reasoning: an unbounded
  * array on a hot document inflates every read of that document (Rule #6), and

package/dist/client.d.ts

@@ -402,6 +402,9 @@ export { OrderCompletionPanel } from "./features/orders/components/OrderCompleti
 export type { OrderCompletionPanelProps, RateableLine } from "./features/orders/components/OrderCompletionPanel";
 export { EmiInstallmentsPanel } from "./features/orders/components/EmiInstallmentsPanel";
 export type { EmiInstallmentsPanelProps } from "./features/orders/components/EmiInstallmentsPanel";
+export { BalancePaymentPanel } from "./features/orders/components/BalancePaymentPanel";
+export type { BalancePaymentPanelProps } from "./features/orders/components/BalancePaymentPanel";
+export { balanceProofSchema, balanceReviewSchema, type BalanceProofInput, type BalanceReviewInput, } from "./features/orders/schemas/balance";
 export { CountdownDisplay } from "./ui/components/CountdownDisplay";
 export type { CountdownDisplayProps } from "./ui/components/CountdownDisplay";
 export { OrderAddonBadges } from "./features/orders/components/OrderAddonBadges";
@@ -513,6 +516,7 @@ export { CommandPalette, useCommandPaletteHotkey } from "./features/shell/index"
 export type { CommandPaletteGroup } from "./features/shell/index";
 export { AdminBlogEditorView, AdminBundleEditorView, AdminCarouselEditorView, AdminCategoryEditorView, AdminCouponEditorView, AdminFaqEditorView, AdminFeatureEditorView, AdminOrderEditorView, AdminPayoutMarkPaidModal, AdminAuditLogView, AdminMoneyCasesView, AdminGatewayEventsView, ViewAuditLogEntryModal, AdminProductEditorView, AdminScammerEditorView, AdminEmployeeEditorView, AdminNavEditorView, AdminUserEditorView, AdminStoreEditorView, AdminSublistingCategoryEditorView, AdminSupportTicketDetailView, } from "./features/admin/index";
 export type { AdminStoreEditorViewProps, AdminPayoutMarkPaidModalProps, AdminAuditLogViewProps, AdminMoneyCasesViewProps, AuditLogEntryDetail, ViewAuditLogEntryModalProps } from "./features/admin/index";
+export type { AdminOrderEditorViewProps } from "./features/admin/components/AdminOrderEditorView";
 export type { NavItemData } from "./features/admin/index";
 export { PageLoader } from "./ui/index";
 export { ADMIN_CHECKOUT_BYPASS_FLAG_KEY } from "./features/admin/schemas/firestore";
@@ -534,6 +538,10 @@ export { BUNDLE_COPY } from "./_internal/shared/features/categories/bundle-copy"
 export { useSiteSettings } from "./core/index";
 export { checkEmiEligibility, computeEmiSchedule, computeBuyerEmiQuote, } from "./_internal/shared/features/emi/schedule";
 export type { EmiSettings, BuyerEmiQuote } from "./_internal/shared/features/emi/schedule";
+export { emiTenderBlockReason, isTenderCompatibleWithEmi } from "./_internal/shared/features/emi/choice";
+export type { EmiTender } from "./_internal/shared/features/emi/choice";
+export { explainCodHandlingFee, explainEmiSurcharge, explainGstOnPlatformFee, explainPlatformFee, } from "./_internal/shared/fees/explain";
+export type { FeeDerivation, FeeDerivations } from "./_internal/shared/fees/explain";
 export type { BuyerFacingFees, BuyerEmiSettings, } from "./_internal/shared/features/site-settings/fees";
 export type { PublicSiteSettings } from "./_internal/shared/features/site-settings/types";
 export { computeCodHandlingFee } from "./_internal/shared/fees/calculator";
@@ -558,6 +566,8 @@ export { raffleEntrySchema } from "./features/contact/schemas/inquiry-forms";
 export { orderCancelSchema, paymentProofSchema, } from "./features/orders/schemas/buyer-forms";
 export { scamReportFormSchema } from "./features/scams/schemas/report-form";
 export { sublistingCategoryFormSchema } from "./features/store-extensions/schemas/sublisting-category-form";
+export { adCreativeFormSchema } from "./features/ads/schemas/creative-form";
+export type { AdCreativeFormValues } from "./features/ads/schemas/creative-form";
 export { adminStoreUpdateSchema, announcementBarSchema, } from "./features/admin/schemas/admin-editor-forms";
 export { adminOrderUpdateSchema, employeeInviteSchema, hardBanReasonSchema, featureFlagsUpdateSchema, adminAdFormSchema, } from "./features/admin/schemas/admin-ops-forms";
 export { changeEmailSchema } from "./features/account/schemas/index";
@@ -596,7 +606,7 @@ export type { ReturnReason } from "./_internal/shared/features/orders/return-rea
 export { DISPUTE_KIND, DISPUTE_KIND_LABEL, DISPUTE_GATE, DISPUTE_TRANSIT_WINDOW_DAYS, DISPUTE_NOT_REACHED_GRACE_DAYS, isDisputeKind, checkDisputeGate, resolveDisputeEtd, disputeNotReachedFilableFrom, } from "./_internal/shared/features/orders/dispute-reasons";
 export type { DisputeKind, DisputeGateOrder, DisputeGateResult, } from "./_internal/shared/features/orders/dispute-reasons";
 export { INTEGRATIONS, INTEGRATION_ORDER, readIntegrationStates, integrationPatch, allIntegrationsPatch, } from "./_internal/shared/features/admin/integrations";
-export type { IntegrationId, IntegrationDescriptor, IntegrationState, } from "./_internal/shared/features/admin/integrations";
+export type { IntegrationId, IntegrationDescriptor, IntegrationPatch, IntegrationState, } from "./_internal/shared/features/admin/integrations";
 export { RefundRequestView } from "./features/orders/components/RefundRequestView";
 export type { RefundRequestViewProps, RefundRequestSubmission, } from "./features/orders/components/RefundRequestView";
 export { ORDER_RETURN_WINDOW_DAYS, ORDER_RETURN_WINDOW_MS, ORDER_CANCELLABLE_STATUSES, } from "./_internal/shared/features/orders/config";