@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/_internal/shared/features/site-settings/toggle-catalog.js

@@ -0,0 +1,204 @@
+/**
+ * TOGGLE_CATALOG — 1A-vi. Replaces `common-toggles.ts`'s hand-typed 3-entry
+ * array with the full, curated set of site-wide boolean switches on
+ * `SiteSettingsDocument`: payments, fee add-ons, tax, messaging channels,
+ * maintenance, chat, the assistant, support, the announcement bar — the
+ * owner's own "everything disableable, header to footer."
+ *
+ * 🛑 NOT build-time generated from the schema, deliberately. A brace-depth
+ * scan over a 1700-line interface cannot reliably tell a genuine top-level
+ * feature toggle (`chat.enabled`) from a config detail nested the same way
+ * (a color-overlay flag two levels deep) — confirmed during this phase's own
+ * discovery pass, which found `features.enabled` as a false positive (an
+ * array ITEM's own field, not a singleton group — and the whole `features`
+ * array is itself dead code, zero callers outside its own repository
+ * methods, flagged for Phase 8B deletion). `scripts/find-toggle-fields.mjs`
+ * is the discovery tool; this file is the human-curated result, kept honest
+ * by `audit-toggle-catalog-drift.mjs` re-running that same heuristic and
+ * failing if a listed `dotPath` stops resolving, OR if a newly-discovered
+ * candidate isn't yet triaged into (or explicitly excluded from) this list.
+ *
+ * The server-side write path (`PATCH /api/admin/site-settings/common-toggle/[id]`)
+ * still validates `id` against this closed array — a client cannot name an
+ * arbitrary `siteSettings.*` path to flip, same closed-set safety
+ * `common-toggles.ts` always had, just backed by 18 real entries instead of 3.
+ *
+ * @tag domain:site-settings
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+export const TOGGLE_CATALOG = [
+    {
+        id: "maintenance-mode",
+        dotPath: "maintenance.enabled",
+        label: "Maintenance mode",
+        group: "maintenance",
+        keywords: ["down", "closed", "offline", "site settings"],
+        priority: 10,
+        confirmation: {
+            title: "Change maintenance mode?",
+            body: "Turning this on takes the whole storefront offline for every visitor until it's turned back off. Turning it off brings the site back live immediately.",
+            confirmLabel: "Change it",
+            confirmKind: "danger",
+        },
+    },
+    {
+        id: "razorpay-enabled",
+        dotPath: "payment.razorpayEnabled",
+        label: "Razorpay enabled",
+        group: "payment",
+        keywords: ["payment", "gateway", "card", "upi", "netbanking", "checkout"],
+        priority: 8,
+        confirmation: {
+            title: "Change Razorpay?",
+            body: "Disabling this removes Razorpay as a payment option at checkout for every buyer — they'll only see whichever other methods are still enabled.",
+            confirmLabel: "Change it",
+            confirmKind: "danger",
+        },
+    },
+    {
+        id: "phonepe-enabled",
+        dotPath: "payment.phonepeEnabled",
+        label: "PhonePe enabled",
+        group: "payment",
+        keywords: ["payment", "gateway", "upi", "checkout"],
+        priority: 8,
+        confirmation: {
+            title: "Change PhonePe?",
+            body: "Disabling this removes PhonePe as a payment option at checkout for every buyer — they'll only see whichever other methods are still enabled.",
+            confirmLabel: "Change it",
+            confirmKind: "danger",
+        },
+    },
+    {
+        id: "cashfree-enabled",
+        dotPath: "payment.cashfreeEnabled",
+        label: "Cashfree Payments enabled",
+        group: "payment",
+        keywords: ["payment", "gateway", "split settlement", "checkout"],
+        priority: 8,
+        confirmation: {
+            title: "Change Cashfree Payments?",
+            body: "Disabling this removes Cashfree as a payment option at checkout for every buyer — they'll only see whichever other methods are still enabled.",
+            confirmLabel: "Change it",
+            confirmKind: "danger",
+        },
+    },
+    {
+        id: "cod-enabled",
+        dotPath: "payment.codEnabled",
+        label: "Cash on delivery enabled",
+        group: "payment",
+        keywords: ["cod", "payment", "checkout"],
+        priority: 7,
+    },
+    {
+        id: "upi-manual-enabled",
+        dotPath: "payment.upiManualEnabled",
+        label: "Manual UPI/bank transfer enabled",
+        group: "payment",
+        keywords: ["payment", "manual", "upi", "bank transfer", "checkout"],
+        priority: 6,
+    },
+    {
+        id: "emi-enabled",
+        dotPath: "emi.enabled",
+        label: "EMI (installments) enabled",
+        group: "emi",
+        keywords: ["emi", "installment", "checkout", "payment"],
+        priority: 6,
+    },
+    {
+        id: "gst-enabled",
+        dotPath: "gst.enabled",
+        label: "GST enabled",
+        group: "gst",
+        keywords: ["gst", "tax", "compliance"],
+        priority: 7,
+    },
+    {
+        id: "whatsapp-notify-fee-enabled",
+        dotPath: "commissions.whatsappNotifyFeeEnabled",
+        label: "WhatsApp order updates add-on enabled",
+        group: "commissions",
+        keywords: ["whatsapp", "add-on", "fee", "checkout"],
+        priority: 3,
+    },
+    {
+        id: "gift-wrap-fee-enabled",
+        dotPath: "commissions.giftWrapFeeEnabled",
+        label: "Gift wrap add-on enabled",
+        group: "commissions",
+        keywords: ["gift wrap", "add-on", "fee", "checkout"],
+        priority: 3,
+    },
+    {
+        id: "shipment-protection-fee-enabled",
+        dotPath: "commissions.shipmentProtectionFeeEnabled",
+        label: "Shipment protection add-on enabled",
+        group: "commissions",
+        keywords: ["protection", "insurance", "add-on", "fee", "checkout"],
+        priority: 3,
+    },
+    {
+        id: "sale-protection-fee-enabled",
+        dotPath: "commissions.saleProtectionFeeEnabled",
+        label: "Sale protection add-on enabled",
+        group: "commissions",
+        keywords: ["protection", "insurance", "add-on", "fee", "checkout"],
+        priority: 3,
+    },
+    {
+        id: "messaging-email-enabled",
+        dotPath: "messaging.emailEnabled",
+        label: "User-facing email enabled",
+        group: "messaging",
+        keywords: ["email", "notifications", "resend"],
+        priority: 5,
+    },
+    {
+        id: "messaging-whatsapp-enabled",
+        dotPath: "messaging.whatsappEnabled",
+        label: "User-facing WhatsApp enabled",
+        group: "messaging",
+        keywords: ["whatsapp", "notifications"],
+        priority: 5,
+    },
+    {
+        id: "buyer-seller-messaging",
+        dotPath: "chat.enabled",
+        label: "Buyer-seller messaging",
+        group: "chat",
+        keywords: ["chat", "messages", "messaging", "site settings"],
+        priority: 7,
+    },
+    {
+        id: "customer-assistant",
+        dotPath: "assistant.enabled",
+        label: "Customer assistant",
+        group: "assistant",
+        keywords: ["ai", "chatbot", "help widget", "assistant", "site settings"],
+        priority: 7,
+    },
+    {
+        id: "support-enabled",
+        dotPath: "support.enabled",
+        label: "Support tickets enabled",
+        group: "support",
+        keywords: ["support", "tickets", "help"],
+        priority: 6,
+    },
+    {
+        id: "announcement-bar-enabled",
+        dotPath: "announcementBar.enabled",
+        label: "Announcement bar enabled",
+        group: "announcementBar",
+        keywords: ["banner", "announcement", "site settings"],
+        priority: 4,
+    },
+];
+export function toggleCatalogById(id) {
+    return TOGGLE_CATALOG.find((t) => t.id === id);
+}
+export const TOGGLE_CATALOG_IDS = TOGGLE_CATALOG.map((t) => t.id);

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

@@ -13,7 +13,7 @@
  * proven client reader is how the endpoint drifted in the first place.
  */
 import type { SiteSettingsDocument } from "../../../../features/admin/schemas/firestore";
-import type { MediaVideoWatermark } from "../../../../features/media/MediaVideo";
+import type { MediaVideoWatermark } from "../../../../ui/components/MediaVideo";
 /** The only notification-channel facts a browser is given: is each channel on. */
 export interface PublicNotificationChannels {
     email: {
@@ -53,15 +53,35 @@ export interface PublicSiteSettings {
      * Withholding it would leave every link to a closed section in the chrome,
      * pointing at a route that now 404s — a dead-end CTA on every page of the
      * site, which is a worse outcome than not having the flag at all.
+     *
+     * `bundlesEnabled` is a DERIVED single boolean, not the raw `categoryTypes`
+     * map — `categoryTypes.bundle` stays withheld like every other key in that
+     * object. `src/proxy.ts` already 404s `/bundles` when
+     * `isCategoryTypeEnabled("bundle", settings)` is false, but
+     * `LayoutShellClient`'s nav filter had no way to agree, because
+     * `bundles`/`bundle` is a `categoryType`, not a `ListingType`, so it was
+     * never in `NAV_KEY_LISTING_TYPES` or `browsePages` — the nav showed the
+     * link while the proxy 404'd it. This one field closes that gap without
+     * reopening the `categoryTypes` privacy boundary.
      */
     listings: {
         listingTypes?: NonNullable<SiteSettingsDocument["listings"]>["listingTypes"];
         browsePages?: NonNullable<SiteSettingsDocument["listings"]>["browsePages"];
+        bundlesEnabled?: boolean;
     };
     /** D9 — off by default; `enabled: false` is emitted rather than omitted, same `always-present` reasoning as `disabledRoutes` below. */
     chat?: {
         enabled: boolean;
     };
+    /**
+     * The customer-assistant floating widget / full-chat page. Read by
+     * `<AssistantWidget>`/`<AssistantPageView>`, both client components.
+     * Opposite polarity to `chat` above — a kill switch on an already-shipped
+     * path, so absence means ON; see the schema field's own doc comment.
+     */
+    assistant?: {
+        enabled: boolean;
+    };
     /**
      * Is the support desk reachable — read by `UserLayoutClient`, a client
      * component. Narrowed to the one boolean rather than passed by reference,
@@ -84,6 +104,12 @@ export interface PublicSiteSettings {
     search?: {
         indexEnabled: boolean;
     };
+    /**
+     * 2B — which locales the language switcher may offer. Absent/empty means
+     * every locale `routing.ts` declares is live (fail-open, same as every
+     * other flag here) — never narrowed by a failed settings read.
+     */
+    enabledLocales?: string[];
     /**
      * 🛑 NARROWER than `NotificationChannelConfig` on purpose, and it must stay
      * that way. The full config carries `minPriority` and a `types[]` allow-list

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

@@ -15,49 +15,266 @@
  * All money amounts are in decimal rupees.
  */
 export interface FeeCommissionRates {
+    /**
+     * Commission rate on the SELLER's payout (`computePayoutDeduction`).
+     *
+     * 🛑 NO LONGER THE BUYER-FACING MODEL. `computeCheckoutFees` charges
+     * `platformFeePerListingUnit × unitCount` — see that function's header for
+     * the owner's spec. This field is a seller-side commercial term and the two
+     * were never the same number; they merely shared a rate by accident.
+     */
     platformFeePercent: number;
     gstPercent: number;
     /** Rupee floor (not paise) — matches the existing `minimumTransactionFee` doc convention. */ minimumTransactionFee?: number;
     /**
-     * Rupee ceiling on the buyer-facing platform commission. Optional so
-     * siteSettings documents saved before this field existed keep working —
-     * falls back to DEFAULT_PLATFORM_FEE_MAX (₹10).
+     * 🛑 DEAD FOR CHECKOUT, and deliberately left declared rather than deleted.
      *
-     * Applies to `computeCheckoutFees` (what the BUYER pays) only. The seller-side
-     * `computePayoutDeduction` is deliberately uncapped — that is a separate
-     * commercial decision, not the same number.
+     * It was the rupee ceiling on the old percentage commission. The owner's
+     * 2026-11-08 ruling replaced that model outright with a flat fee per listing
+     * line, and **a ₹10 ceiling applied to `n × ₹10` would cap every order at ₹10
+     * and silently destroy the new rule** — which is exactly why this carries a
+     * warning instead of quietly staying in the arithmetic.
+     *
+     * Still declared because `siteSettings.commissions.platformFeeMax` is a live
+     * stored field with an admin form behind it, and `explainPlatformFee` must be
+     * able to recognise a legacy document. Removing the field from the schema is
+     * a cross-lane change (the `siteSettings` schema is not this lane's) and is
+     * reported rather than made here.
      */ platformFeeMax?: number;
+    /**
+     * The VOLUME TAPER for the buyer-facing platform fee — owner, 2026-11-08:
+     * *"scaling too, if you buy more the fees reduces as you go up, but never
+     * less than 5 rs"*.
+     *
+     * 🛑 A TABLE, not a formula, and that is the decision rather than an
+     * implementation detail. A seller and a buyer both have to *understand* the
+     * fee; a continuous decay curve is unexplainable on an invoice, while "1–4 at
+     * ₹10, 5–9 at ₹8" is a sentence. It is also the governing principle applied
+     * to pricing — bundles are DATA, not code — so changing the curve is a
+     * settings edit and never a deploy.
+     *
+     * Each band is "`minUnits` or more → this rate". Order does not matter;
+     * `resolvePlatformFeeUnitRate` sorts and picks the highest `minUnits` the
+     * line reaches.
+     *
+     * Falls back to `DEFAULT_PLATFORM_FEE_UNIT_BANDS` when absent.
+     */ platformFeeUnitBands?: readonly {
+        minUnits: number;
+        ratePerUnit: number;
+    }[];
+    /**
+     * The HARD FLOOR on the tapered per-unit rate. Never below this, whatever the
+     * table says.
+     *
+     * 🛑 Enforced STRUCTURALLY in `resolvePlatformFeeUnitRate`, not merely by
+     * the bottom band happening to equal it. A floor that holds only because
+     * someone typed the right number in the last row is not a floor — it is a
+     * coincidence that survives until the next person edits the table. The owner
+     * said *"never less than 5 rs"*; a badly-edited table must still obey that.
+     *
+     * Falls back to `DEFAULT_PLATFORM_FEE_PER_UNIT_FLOOR`.
+     */ platformFeePerUnitFloor?: number;
+    /**
+     * LEGACY single flat rate per unit, with no taper.
+     *
+     * Honoured as a one-band table when `platformFeeUnitBands` is absent, so a
+     * settings document written between the flat-rate ruling and the taper
+     * ruling (both 2026-11-08) keeps charging exactly what it charged.
+     *
+     * 🛑 A stored `0` is honoured as zero and is NOT the same as absent. An
+     * admin switching the fee off is a real configuration; `??` (not `||`) keeps
+     * the two distinguishable — and a configured `0` deliberately bypasses the
+     * floor, because "no platform fee" is a different statement from "a cheap
+     * one".
+     */ platformFeePerListingUnit?: number;
     gatewayFeePercent?: number;
 }
+/** One row of the volume taper: `minUnits` or more on a line → this rate. */
+export interface PlatformFeeUnitBand {
+    /** Smallest line quantity this rate applies to. */
+    minUnits: number;
+    /** ₹ charged per unit at that quantity. */ ratePerUnit: number;
+}
+/**
+ * The platform fee taper. Owner, 2026-11-08:
+ *
+ *   *"our website platform fees is 10rs per listing so an order with n items
+ *   is nx10 rs, plus gst 18%"*
+ *   *"scaling too, if you buy more the fees reduces as you go up, but never
+ *   less than 5 rs — the reduction you can decide"*
+ *   *"for the bx-53 case we bought 1 listing so yes 1 item count only not its
+ *   components"*
+ *
+ * ## 🛑 PER UNIT, with a BANDED taper, and a composite is ONE unit
+ *
+ * Three rulings, three distinct things, and they are easy to confuse:
+ *
+ *   · **Quantity multiplies.** One line at quantity 3 is 3 units → ₹30.
+ *   · **Components do not.** A BX-53 deck set is ONE listing purchased, so it
+ *     is **₹10, not ₹60**, however many parts are in the box. The count is
+ *     `item.quantity`, never `expandCartLineToOrderRows`'s output — that
+ *     expansion exists so each member can carry its own HSN and be cancelled
+ *     independently, and counting its rows would bill a buyer six times for one
+ *     purchase.
+ *   · **Volume tapers, per LINE.** 10 of one item bills cheaper per unit than
+ *     4 of it.
+ *
+ * ## ⚠ Three sources of truth existed for this; two are now stale
+ *
+ * `mocks/18-shipping-fees.qm` draws *"₹10 per LINE, not per unit"* with a
+ * worked table and no taper. It is wrong in BOTH directions now and is
+ * reported for correction by the session that owns it — not edited here. An
+ * earlier revision of this file implemented a flat per-unit ₹10; the taper
+ * supersedes it. Recorded rather than silently replaced, because a money
+ * formula with three readings is exactly how the divergences this codebase
+ * keeps paying for begin.
+ *
+ * ## 🛑 A FALLBACK, not the mechanism
+ *
+ * The table, the floor and the GST rate are all `FeeCommissionRates`
+ * configuration, because ₹10/₹5, these band edges and 18% are **today's India
+ * values**, not universal truths — tax already resolves by origin/destination
+ * country pair (plan A18). A hardcoded rate or `0.18` in the arithmetic is the
+ * vertical coupling the governing principle forbids.
+ *
+ * Defaulted HERE rather than only in `CHECKOUT_DEFAULT_COMMISSIONS`, because
+ * that object is used solely when the settings read FAILS
+ * (`siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS`). A live
+ * settings document predating the field would otherwise resolve `undefined`
+ * and the rule would be dead in production while looking configured — the
+ * "seam nobody used" shape D44 is about.
+ */
+export declare const DEFAULT_PLATFORM_FEE_UNIT_BANDS: readonly PlatformFeeUnitBand[];
+/**
+ * The hard floor on the per-unit rate — owner: *"never less than 5 rs"*.
+ *
+ * 🛑 Applied by `resolvePlatformFeeUnitRate` to whatever the table returns,
+ * so it holds even if the table is edited badly. The bottom band happens to
+ * equal it today; that agreement is a convenience, not the mechanism.
+ */
+export declare const DEFAULT_PLATFORM_FEE_PER_UNIT_FLOOR = 5;
+/** Kept for readers of the pre-taper flat rate; it is the top band's value. */
+export declare const DEFAULT_PLATFORM_FEE_PER_LISTING_UNIT = 10;
+/**
+ * The per-unit rate for ONE cart line of `units`.
+ *
+ * ## 🛑 PER LINE, not per order total
+ *
+ * 4 of item A plus 4 of item B is 8 units but TWO lines of 4, so both bill at
+ * the ₹10 band. Banding on the order total would let an unrelated bulk line
+ * cheapen everything beside it, which is not what *"if you buy more"* means —
+ * the discount is for buying more of a thing, not for having a big basket.
+ * (Hub ruling, 2026-11-08, flagged to the owner for overrule.)
+ *
+ * ## 🛑 The floor is STRUCTURAL
+ *
+ * `Math.max(floor, …)` is applied after the table lookup, so a table edited to
+ * say ₹2 still charges ₹5. The one deliberate exception is a configured flat
+ * rate of exactly `0` — "no platform fee" is a different statement from "a
+ * cheap one", and an admin switching the fee off must not be overruled into
+ * charging ₹5.
+ *
+ * An empty or unusable table resolves to the floor rather than to zero: a
+ * misconfiguration should cost us the taper, never the whole fee.
+ */
+export declare function resolvePlatformFeeUnitRate(units: number, commissions: FeeCommissionRates): number;
+/** One cart line's contribution to the platform fee, kept for the explainer. */
+export interface PlatformFeeLine {
+    /** `item.quantity` — a composite counts ONCE however many parts it has. */
+    units: number;
+    /** The tapered rate this line's quantity earned. */
+    ratePerUnit: number;
+    /** `units × ratePerUnit`. */
+    amount: number;
+}
 export interface CheckoutFees {
-    /** Platform commission in decimal rupees, capped at `platformFeeMax`. */
+    /** Platform fee in decimal rupees: `Σ over lines ( rate(units) × units )`. */
     platformFee: number;
-    /** GST on the (already capped) platform fee, in decimal rupees. */
+    /** GST on the platform fee, in decimal rupees. */
     gstOnFee: number;
     /** platformFee + gstOnFee, floored at minimumTransactionFee. */
     totalFee: number;
+    /**
+     * Total units the fee was computed from, carried so the explainer and the
+     * order record describe the same `n` the charge was derived from rather than
+     * recounting it from a different collection.
+     */
+    unitCount: number;
+    /**
+     * The per-line derivation, so `explainPlatformFee` can show a tapered fee
+     * the buyer can check.
+     *
+     * 🛑 Returned rather than recomputed by the renderer. With a taper the fee
+     * is no longer "count × one rate" — a browser re-deriving it would have to
+     * re-implement the band lookup, which is a second implementation of a money
+     * rule (Root Cause #75) living in the least trustworthy place.
+     */
+    lines: PlatformFeeLine[];
 }
 /**
  * What the buyer pays on top of the subtotal.
  *
- * The cap is applied to the commission BEFORE GST is computed, because GST is
- * levied on the commission actually charged — capping afterwards would bill tax
- * on money that was never collected.
+ * ## 🛑 `fee = Σ over cart lines ( rateFor(quantity) × quantity )`, then GST
+ *
+ * Owner, 2026-11-08, across three rulings — see
+ * `DEFAULT_PLATFORM_FEE_UNIT_BANDS` for the verbatim text and for why a
+ * composite listing is ONE unit.
+ *
+ * This REPLACED a percentage-of-subtotal model capped at ₹10. The two are not
+ * variations of each other: the old model charged **at most ₹10 for the whole
+ * checkout** however many items were in it. The cap is therefore not merely
+ * unused here, it is actively incompatible — see `platformFeeMax`.
+ *
+ * ## 🛑 `lineUnitCounts` IS REQUIRED, and it is an ARRAY for a reason
+ *
+ * The taper bands PER LINE, so a scalar total cannot express the input: 8 units
+ * as two lines of 4 bills at ₹10 (₹80), and as one line of 8 bills at ₹8 (₹64).
+ * Taking `readonly number[]` makes that distinction unrepresentable-wrong at
+ * every call site, and `tsc` forces all six of them to supply it — an optional
+ * parameter defaulting to the old model would be the D44 shape exactly: a seam
+ * declared, never passed, silently wrong at every money path until someone
+ * checked.
+ *
+ * ## Where GST rounds
+ *
+ * Once, on the whole fee base, through the same `roundRupees` every other money
+ * term uses — never per line. Rounding 18% of ₹10 three times accumulates a
+ * different number than rounding 18% of ₹30 once, and the invoice has to agree
+ * with the capture to the paisa. Each LINE's own amount is rounded too, because
+ * a band rate of ₹6.50 makes an odd quantity produce a half-paisa otherwise.
  */
-export declare function computeCheckoutFees(subtotal: number, commissions: FeeCommissionRates): CheckoutFees;
+export declare function computeCheckoutFees(subtotal: number, commissions: FeeCommissionRates, lineUnitCounts: readonly number[]): CheckoutFees;
 /**
- * Split one checkout's platform commission across the orders it produces.
- *
- * The buyer is charged a single capped commission for the transaction, but the
- * cart splits into one order per store, and each `OrderDocument` records its own
- * `platformFee` (invoices, reconciliation). Apportioning pro-rata by group
- * subtotal keeps those per-order figures meaningful; giving the last group the
- * rounding remainder guarantees they sum to exactly what was charged, so the
- * orders can never quietly total a rupee more or less than the buyer paid.
+ * Split one checkout's platform fee across the orders it produces.
+ *
+ * The buyer is charged one fee for the transaction, but the cart splits into
+ * one order per store and each `OrderDocument` records its own `platformFee`
+ * (invoices, reconciliation). The per-order figures must sum to EXACTLY what
+ * was charged, or the buyer's statement and our own records disagree.
+ *
+ * ## 🛑 EXACT PER STORE WHEN LINE QUANTITIES ARE SUPPLIED — not pro-rata
+ *
+ * Under the volume taper the fee is `Σ rate(units) × units` per LINE, so a
+ * store's share is a sum it OWNS, not a slice of someone else's number. It is
+ * computed from the same `resolvePlatformFeeUnitRate` the cart-level figure
+ * used, and the last group absorbs any rounding or `minimumTransactionFee`
+ * remainder so the shares still total the charge to the paisa.
+ *
+ * Pro-rata by subtotal — the original behaviour — is demonstrably wrong here
+ * and survives only as the fallback for callers that cannot supply quantities.
+ * A cart with one ₹5,000 unit at store A and one ₹100 unit at store B is
+ * charged ₹20, and by subtotal that apportions ₹19.61 / ₹0.39 when each order
+ * is in fact a one-unit ₹10 order. The total charged is identical either way,
+ * so this is an invoice-correctness defect rather than an overcharge — the same
+ * shape as `isIntraStateSupply`'s CGST/SGST-vs-IGST split, and it matters for
+ * the same reason: a GST return is built from the per-order rows, not the cart
+ * total.
  *
  * @param groupSubtotals `[storeId, subtotal]` pairs, in stable order.
+ * @param groupLineUnitCounts Per-store LINE quantities. Omit for pro-rata.
+ * @param commissions Needed to re-resolve the taper per store. Omit for pro-rata.
  */
-export declare function allocateCheckoutFees(groupSubtotals: readonly (readonly [string, number])[], fees: CheckoutFees): Map<string, {
+export declare function allocateCheckoutFees(groupSubtotals: readonly (readonly [string, number])[], fees: CheckoutFees, groupLineUnitCounts?: ReadonlyMap<string, readonly number[]>, commissions?: FeeCommissionRates): Map<string, {
     platformFee: number;
     gstOnFee: number;
 }>;
@@ -134,6 +351,24 @@ export interface PayoutDeduction {
  *
  * Also defaulted to 0, for the same reason.
  */
+/**
+ * A commission PERCENT (what an admin types) as a RATE (what a payout row
+ * stores). `5` becomes `0.05`.
+ *
+ * Trivial arithmetic, and it lives here anyway for two reasons. `/ 100` on a
+ * `commissions.*` field is exactly what `audit-money-paths` R3 forbids outside
+ * this file, because the two units are both bare numbers and swapping them
+ * silently charges a seller 100× or 1/100× — there is no type that separates
+ * them. And it was already open-coded identically in `autoPayoutEligibility`
+ * and `weeklyPayoutEligibility` (both staged in that audit), so the next
+ * writer copied the shape rather than a helper.
+ *
+ * 🛑 This is a UNIT CONVERSION, not a rounding site. Do not round here: the
+ * rate is stored to explain a fee that has already been computed and rounded
+ * by `computePayoutDeduction`, and rounding the explanation would make it
+ * disagree with the amount it explains.
+ */
+export declare function commissionPercentToRate(percent: number | undefined): number;
 export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates, shippingReimbursement?: number, pointsFunded?: number): PayoutDeduction;
 export interface CodHandlingFeeRates {
     /**