@mohasinac/appkit 4.71.0 → 4.71.2

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

@@ -1,5 +1,13 @@
 import { roundRupees } from "../../../utils/number.formatter.js";
-import { calculateGstInclusive, taxableFromInclusive } from "../fees/calculator.js";
+import { calculateGstInclusive } from "../fees/calculator.js";
+/*
+ * 🛑 The payout base moved to `./payout-base` on 2026-10-31 — this file had
+ * reached its 1000-line ceiling and a split capture needed a third caller of
+ * the same rule. Re-exported rather than relocated-and-repointed so the ~20
+ * existing importers keep working; new code should import from the module
+ * that defines it (Root Cause #18).
+ */
+export { orderTaxableValue, ordersTaxableValue, linesTaxableValue, commissionRecordRates, } from "./payout-base.js";
 /*
  * Points: the CAP arithmetic only. `maxRedeemablePoints` lives beside
  * `POINTS_MAX_REDEMPTION_PERCENT`, which is the constant that defines it, so
@@ -8,12 +16,67 @@ import { calculateGstInclusive, taxableFromInclusive } from "../fees/calculator.
  * plain data with no Firestore import.
  */
 import { maxRedeemablePoints } from "../../../features/points/schemas/firestore.js";
+/**
+ * Resolve the wholesale quantity break that applies at `quantity` units.
+ *
+ * ## 🛑 This field was STORED AND NEVER READ
+ *
+ * `bulkDiscounts` has been declared on `ProductDocument`, validated by the
+ * product zod schema (so the API accepted and persisted it) and carried in the
+ * public projection — with **zero readers anywhere in the tree**. A seller
+ * could save "10+ = 15% off", a buyer could order 10, and be charged full
+ * price. Measured 2026-11-08: three occurrences of the identifier, all three
+ * declarations.
+ *
+ * That is the worst of the three possible states — it looks configured and does
+ * nothing — which is why the owner's ruling was to wire it up rather than
+ * delete it.
+ *
+ * ## The rule
+ *
+ * The BEST applicable tier wins, selected by highest `discountPercent` and not
+ * by position or by highest threshold. Tiers are seller-entered data: nothing
+ * guarantees they arrive sorted, and nothing guarantees they are monotonic, so
+ * `[{10, 15}, {25, 5}]` is a shape a seller can save. Picking by threshold
+ * would charge a buyer of 25 units MORE than a buyer of 10. Picking the best
+ * discount the quantity qualifies for cannot do that.
+ *
+ * Malformed rows are skipped rather than clamped to a boundary: a negative or
+ * non-finite percent is a data error, and treating it as 0 silently applies no
+ * discount where the seller meant one, while treating it as 100 gives the goods
+ * away. Skipping leaves the next-best valid tier to apply.
+ *
+ * `>= 100` is excluded for the same reason — a free line is never what a volume
+ * break means, and it would make the gateway capture ₹0 on a real order.
+ *
+ * Returns 0 when nothing applies, so the caller multiplies by 1.
+ */
+export function resolveBulkDiscountPercent(tiers, quantity) {
+    if (!tiers?.length)
+        return 0;
+    if (!Number.isFinite(quantity) || quantity < 1)
+        return 0;
+    let best = 0;
+    for (const tier of tiers) {
+        if (!Number.isFinite(tier?.quantity) || !Number.isFinite(tier?.discountPercent))
+            continue;
+        if (tier.quantity < 1)
+            continue;
+        if (tier.discountPercent <= 0 || tier.discountPercent >= 100)
+            continue;
+        if (quantity < tier.quantity)
+            continue;
+        if (tier.discountPercent > best)
+            best = tier.discountPercent;
+    }
+    return best;
+}
 /**
  * The single source of truth for "what do we charge for ONE COPY of this line".
  *
- * Four cases, in priority order:
+ * Five cases, in priority order:
  *
- *  1. **A locked price** — an accepted offer or a won auction. `lockedPrice` is
+ *  1. **A locked price** — an accepted offer or a won collector drop. `lockedPrice` is
  *     the negotiated/won amount and it OVERRIDES the current listing price, which
  *     is the whole point of the negotiation. Until 2026-08-21 none of the five
  *     copies of this function looked at `lockedPrice`, so an accepted offer was
@@ -29,6 +92,11 @@ import { maxRedeemablePoints } from "../../../features/points/schemas/firestore.
  *     see the invariant on `CartLineMember`.
  *  4. **Everything else** — the live Firestore price, so a stale cart-cached
  *     price is never charged on a COD/UPI order.
+ *  5. **…less a wholesale quantity break**, when the live listing declares
+ *     `bulkDiscounts` and this line's quantity qualifies. Last on purpose:
+ *     cases 1–3 return before it, so a negotiated price, a bundle price and a
+ *     group's member sum can never have a tier stacked on top of them. See
+ *     `resolveBulkDiscountPercent`.
  *
  * `product` may be null for a locked line whose listing has since been archived;
  * the locked price is still owed, so that case must not dereference `product`.
@@ -60,7 +128,43 @@ export function unitPriceFor(item, product) {
     // summary/preview path) already guarded with `product?.price ?? item.price`,
     // and collapsing onto a non-null assertion would have regressed it into a
     // crash whenever a cart line outlives its listing.
-    return product?.price ?? item.price;
+    const base = product?.price ?? item.price;
+    /*
+     * ── Case 5: a WHOLESALE quantity break on an ordinary listing ─────────────
+     *
+     * 🛑 LAST, and deliberately unreachable from the three branches above:
+     *
+     *  · a LOCKED price outranks a volume tier. An accepted offer or a won
+     *    collector drop is a negotiated amount, and a quantity break silently
+     *    overriding it would move a price both parties already agreed. It
+     *    returns early above, so this is structural, not a convention.
+     *  · a BUNDLE already carries its own price, set below the sum of its
+     *    members. Stacking a tier on top discounts a discount.
+     *  · a GROUP line's price is the sum of member snapshots and already has
+     *    `groupDiscountPercent` applied in the repository's `deriveLinePrice`.
+     *    Applying a tier here would be the second application that makes the
+     *    cart total disagree with the invoice (Root Cause #75).
+     *
+     * Read off the LIVE product, never off the cart line: `PricedCartLine` has no
+     * tier field and must not gain one. The same reasoning as the live-price
+     * fallback directly above — a snapshot taken at add time is a price the
+     * seller may since have changed, and a stale tier is a stale price.
+     *
+     * 🛑 `item.quantity` is COPIES of this line, which is the right basis for an
+     * ordinary single-product line because copies ARE units there. It is not the
+     * right basis for a multi-member line, which is another reason this sits
+     * after those branches rather than in front of them.
+     *
+     * 🛑 NOT the platform fee. The ₹10-per-line fee also tapers with quantity
+     * (W-SHIP, band table in config), and the two must never be conflated: this
+     * is the SELLER discounting their goods, that is the PLATFORM pricing its
+     * own service. They move different money in different directions and appear
+     * as different lines on the invoice.
+     */
+    const bulkPercent = resolveBulkDiscountPercent(product?.bulkDiscounts, item.quantity);
+    if (bulkPercent > 0)
+        return roundRupees(base * (1 - bulkPercent / 100));
+    return base;
 }
 /**
  * What this line contributes to a subtotal: one copy's price × the number of
@@ -455,52 +559,6 @@ export function orderGoodsValue(order) {
 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));
-}
 /**
  * Postage the seller is owed back on one order — **D45, and it is NOT revenue.**
  *

package/dist/_internal/shared/checkout/payout-base.d.ts

@@ -0,0 +1,51 @@
+/** Exactly the fields `orderTaxableValue` reads. */
+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;
+}
+/** One priced line, before any order exists. */
+export interface TaxableLineLike {
+    /** Tax-INCLUSIVE line total, from `lineTotalFor`. Never `price × quantity`. */
+    lineTotal: number;
+    gstRate?: number;
+}
+/**
+ * The payout base for one order: taxable value, never the gross.
+ *
+ *   - inclusive seller, ₹999 @5% → buyer pays ₹999, taxable ₹951.43
+ *   - exclusive seller types ₹999 → grossed up on write to ₹1,048.95, buyer
+ *     pays ₹1,048.95, taxable ₹999.00
+ */
+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;
+/**
+ * The same base for lines with no order yet — a split capture is instructed
+ * BEFORE the orders are created.
+ */
+export declare function linesTaxableValue(lines: readonly TaxableLineLike[]): number;
+/**
+ * The three RATE fields a `payouts` row stores to explain its fee figures.
+ *
+ * 🛑 Rates, not percents: an admin types `5`, a row stores `0.05`, both are
+ * bare numbers with no type between them, and swapping them bills a seller
+ * 100× or 1/100×.
+ */
+export declare function commissionRecordRates(commissions: {
+    platformFeePercent: number;
+    gatewayFeePercent?: number;
+    gstPercent: number;
+}): {
+    platformFeeRate: number;
+    gatewayFeeRate: number;
+    gstRate: number;
+};

package/dist/_internal/shared/checkout/payout-base.js

@@ -0,0 +1,84 @@
+/*
+ * WHY: The amount a seller is paid, and the rates that explain it.
+ *
+ *      Split out of `order-math.ts` on 2026-10-31 because that file had
+ *      reached its 1000-line ceiling and a split capture needs a THIRD caller
+ *      of the same payout base — the two payout sweeps already share it, and a
+ *      capture is instructed before any order exists, so it needs a
+ *      line-shaped entry point beside the order-shaped one.
+ *
+ * WHAT: One per-line rule for backing tax out of an inclusive total, in both
+ *       shapes, plus the commission rates a `payouts` row records.
+ *
+ * ## 🛑 THE SPLIT AND THE SWEEPS MUST AGREE TO THE RUPEE
+ *
+ * A seller paid one amount by the gateway and shown another by their dashboard
+ * is the failure this file exists to prevent, and agreement is only structural
+ * if both read the SAME rule — including the `?? 0` default. Defaulting a
+ * missing rate to `DEFAULT_GST_RATE` in one path and `0` in the other diverges
+ * for exactly the listings that carry no rate.
+ *
+ * The back-out is per ITEM, never blended: a mixed 5% + 18% group cannot be
+ * undone with a single rate, and an order-level rate does not exist.
+ *
+ * ## 🛑 Two different things are called `gstRate` here
+ *
+ * `TaxableLineLike.gstRate` is the BUYER's tax on the goods.
+ * `commissionRecordRates().gstRate` is GST on OUR COMMISSION. They collide
+ * only in name, and `audit-tax-provider-boundary` matches on the name — which
+ * is why both live here, commented, instead of being open-coded at each payout
+ * writer where the distinction would have to be rediscovered.
+ *
+ * EXPORTS: PayableOrderLike, TaxableLineLike, orderTaxableValue,
+ *          ordersTaxableValue, linesTaxableValue, commissionRecordRates
+ *
+ * @tag domain:checkout
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+import { roundRupees } from "../../../utils/number.formatter.js";
+import { commissionPercentToRate, taxableFromInclusive } from "../fees/calculator.js";
+/**
+ * The payout base for one order: taxable value, never the gross.
+ *
+ *   - inclusive seller, ₹999 @5% → buyer pays ₹999, taxable ₹951.43
+ *   - exclusive seller types ₹999 → grossed up on write to ₹1,048.95, buyer
+ *     pays ₹1,048.95, taxable ₹999.00
+ */
+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));
+}
+/**
+ * The same base for lines with no order yet — a split capture is instructed
+ * BEFORE the orders are created.
+ */
+export function linesTaxableValue(lines) {
+    return roundRupees(lines.reduce((sum, l) => sum + taxableFromInclusive(l.lineTotal, l.gstRate ?? 0), 0));
+}
+/**
+ * The three RATE fields a `payouts` row stores to explain its fee figures.
+ *
+ * 🛑 Rates, not percents: an admin types `5`, a row stores `0.05`, both are
+ * bare numbers with no type between them, and swapping them bills a seller
+ * 100× or 1/100×.
+ */
+export function commissionRecordRates(commissions) {
+    return {
+        platformFeeRate: commissionPercentToRate(commissions.platformFeePercent),
+        gatewayFeeRate: commissionPercentToRate(commissions.gatewayFeePercent),
+        gstRate: commissionPercentToRate(commissions.gstPercent),
+    };
+}

package/dist/_internal/shared/checkout/policy-consent.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Buyer policy agreement at checkout — the CLAUSE MODEL (item 1.39).
+ *
+ * ## Why this exists
+ *
+ * The platform ships a no-cancel-after-reveal and no-refund-after-ship
+ * mechanic. Those terms remove rights the buyer would otherwise have, so they
+ * have to be accepted **knowingly, per purchase**, and the acceptance has to be
+ * provable afterwards. A boolean `termsAccepted: true` on an order is not a
+ * consent record — it says somebody ticked something, not WHAT they were
+ * shown. This module owns the "what".
+ *
+ * ## 🛑 Capability-driven, never type-driven
+ *
+ * Which clauses apply to a cart is decided by reading the listing-type
+ * CAPABILITY REGISTRY, never by `if (listingType === "clearance")`. A clause
+ * declares the capability it is a consequence of:
+ *
+ *   `supportsSurpriseReveal`    → "no cancellation once you reveal"
+ *   `supportsShipping`          → "no refund once it ships"
+ *   `hasInstantFulfillment`     → "delivered instantly, not returnable"
+ *   `requiresJurisdictionCheck` → "you confirm it is legal where you are"
+ *
+ * So the day the owner enables the reveal mechanic on stickers, the reveal
+ * clause starts appearing on sticker checkouts with **no code change** — one
+ * row in `LISTING_TYPE_CAPABILITIES` flips and this resolver follows it. That
+ * is the governing principle of the rework applied to the consent step.
+ *
+ * ## The clause set is DATA
+ *
+ * `siteSettings.checkoutPolicies.clauses` is the editable copy, so an admin
+ * rewords a consequence without a deploy and a different client in a different
+ * vertical writes their own. `DEFAULT_CHECKOUT_POLICY_CLAUSES` below is the
+ * FAIL-CLOSED fallback used when settings carry nothing: an install that has
+ * never configured policies still blocks checkout behind a consent step rather
+ * than silently waiving it.
+ *
+ * ## What is NOT here
+ *
+ * Hashing and persistence are server-only and live in
+ * `_internal/server/payments/policy-consent.ts`. This module is isomorphic on
+ * purpose — the checkout UI renders the same clause objects the gate judges, so
+ * the text the buyer reads and the text that gets hashed cannot drift.
+ */
+import { type ListingTypeCapability } from "../listing-types/capabilities";
+import type { ListingType } from "../../../features/products/types/index";
+/**
+ * What a clause is a consequence OF.
+ *
+ * `"always"` is the unconditional clause every order carries (the baseline
+ * terms acknowledgement). Everything else names a capability key, which is
+ * typed against the registry — so deleting a capability is a compile error
+ * here rather than a clause that silently stops applying.
+ */
+export type CheckoutPolicyPredicate = "always" | keyof ListingTypeCapability;
+export interface CheckoutPolicyClause {
+    /**
+     * Stable identity. Recorded on the order, so renaming an id breaks the
+     * ability to say "this buyer accepted that clause" — change the `text` and
+     * bump `version` instead.
+     */
+    id: string;
+    /**
+     * The consequence, in plain language, as the buyer reads it INLINE at the
+     * point of agreement. 🛑 Not a link to a policy page: the whole point of the
+     * blocking step is that the consequence is in front of them when they tick.
+     */
+    text: string;
+    /**
+     * When this clause applies. See `CheckoutPolicyPredicate` — a capability
+     * name, resolved through the registry, or `"always"`.
+     */
+    appliesWhen: CheckoutPolicyPredicate;
+    /**
+     * Invert the predicate: the clause applies when the capability is FALSE.
+     * Needed for the honest shape of some consequences — "nothing in this order
+     * ships, so there is no delivery window" is the absence of a capability, not
+     * the presence of one.
+     */
+    negate?: boolean;
+}
+/**
+ * The stored shape in `siteSettings.checkoutPolicies`.
+ *
+ * `version` is admin-bumped and travels onto the order beside the hash. The
+ * hash proves WHAT was accepted; the version is the human-readable handle for
+ * it in a dispute ("policy v3"), and is why both are stored rather than one.
+ */
+export interface CheckoutPolicySettings {
+    version: number;
+    clauses: CheckoutPolicyClause[];
+}
+/**
+ * FAIL-CLOSED defaults. Used whenever settings carry no clause list.
+ *
+ * 🛑 Every entry's `appliesWhen` is a capability, not a listing type. Grep for
+ * `listingType ===` in this file: zero, and that is the acceptance test for the
+ * whole rework.
+ */
+export declare const DEFAULT_CHECKOUT_POLICY_CLAUSES: readonly CheckoutPolicyClause[];
+/**
+ * 2, not 1 — bumped when `no-refund-after-ship` was split into the
+ * cancellation-window and returns-window clauses above.
+ *
+ * 🛑 Bumping is not cosmetic and is not optional on a wording change. The hash
+ * proves WHAT was accepted; the version is the handle a human uses to talk
+ * about it ("they accepted policy v1, which said the wrong thing about
+ * cancellation"). Leaving it at 1 across a material rewrite would make two
+ * genuinely different documents indistinguishable by name, and the only way to
+ * tell them apart would be to re-derive a hash from an old settings snapshot
+ * nobody kept.
+ */
+export declare const DEFAULT_CHECKOUT_POLICY_VERSION = 2;
+/**
+ * The clause set for THIS checkout, in declaration order.
+ *
+ * Caller supplies the listing types actually in the cart. Resolution is pure,
+ * so the UI and the server gate run the identical function over the identical
+ * settings and cannot disagree about what was required.
+ */
+export declare function resolveCheckoutPolicyClauses(settings: CheckoutPolicySettings | undefined, listingTypes: readonly ListingType[]): CheckoutPolicyClause[];
+export declare function resolveCheckoutPolicyVersion(settings: CheckoutPolicySettings | undefined): number;
+/**
+ * The exact bytes the hash is taken over.
+ *
+ * 🛑 Canonical and explicit, never `JSON.stringify(clauses)`. Key order in a
+ * stringified object is an implementation detail, and a hash that changed
+ * because a field moved would invalidate every buyer's acceptance on a no-op
+ * edit. Only `id` and `text` participate: those are what the buyer actually
+ * read. The predicate is how we DECIDED to show it, which is our business and
+ * not part of what they agreed to.
+ */
+export declare function canonicalisePolicyClauses(clauses: readonly {
+    id: string;
+    text: string;
+}[]): string;
+/**
+ * What the buyer is shown, and what they must echo back.
+ *
+ * The client never computes the hash — it receives this object and returns the
+ * `version`/`hash` it was given. The server re-resolves both from the cart and
+ * compares. So a tampered hash cannot widen anything: it can only fail the
+ * comparison, which is a refusal.
+ */
+export interface CheckoutPolicyOffer {
+    version: number;
+    hash: string;
+    clauses: CheckoutPolicyClause[];
+}
+/**
+ * THE CONSENT RECORD, as stamped onto every order the consent covers.
+ *
+ * 🛑 `clauses` carries the VERBATIM TEXT, not a pointer to the current
+ * settings. A pointer to "whatever the policy says today" is worthless in a
+ * dispute — the whole question is what the buyer was shown at the time, and an
+ * admin editing a clause afterwards would rewrite history. The hash lets
+ * anyone confirm the stored text is the text that was hashed; the stored text
+ * is what makes the hash mean anything.
+ */
+export interface OrderPolicyConsent {
+    /** The `buyerPolicyConsents` document this order's consent was recorded as. */
+    consentId: string;
+    /** Who agreed. Duplicated from the order's `userId` so the record stands alone. */
+    buyerId: string;
+    /** `siteSettings.checkoutPolicies.version` in force when they agreed. */
+    version: number;
+    /** `sha256(canonicalisePolicyClauses(clauses))`, hex. */
+    hash: string;
+    acceptedAt: Date;
+    /** Verbatim — see the 🛑 above. */
+    clauses: {
+        id: string;
+        text: string;
+    }[];
+    /**
+     * Which checkout path captured it. A dispute asks "where did this consent
+     * come from", and on the gateway path the answer is "the create-order
+     * request, before the money moved" — the fact that makes the pre-capture
+     * enforcement provable rather than asserted.
+     */
+    capturedOn: "checkout" | "gateway-create-order" | "admin-bypass";
+}