@mohasinac/appkit 4.71.0 → 4.71.2

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

@@ -16,40 +16,228 @@
  */
 import { roundRupees } from "../../../utils/number.formatter.js";
 import { resolveStateKey } from "./india-states.js";
-/** Buyer-facing platform commission ceiling, in decimal rupees. */
-const DEFAULT_PLATFORM_FEE_MAX = 10;
+/**
+ * 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 const DEFAULT_PLATFORM_FEE_UNIT_BANDS = [
+    { minUnits: 1, ratePerUnit: 10 },
+    { minUnits: 5, ratePerUnit: 8 },
+    { minUnits: 10, ratePerUnit: 6.5 },
+    { minUnits: 25, ratePerUnit: 5 },
+];
+/**
+ * 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 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 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 function resolvePlatformFeeUnitRate(units, 
+/*
+ * 🛑 The WHOLE rates object, not a `Pick` of the three fields this reads.
+ * All three are optional, so a `Pick` of them is a WEAK TYPE — and `tsc`
+ * rejects `siteSettings.commissions` against it outright ("no properties in
+ * common") until that schema gains the fields, which is another lane's
+ * change. Taking the same shape `computeCheckoutFees` takes also guarantees
+ * the two resolve the rate from one object rather than from two views of it.
+ */
+commissions) {
+    const floor = Math.max(0, commissions.platformFeePerUnitFloor ?? DEFAULT_PLATFORM_FEE_PER_UNIT_FLOOR);
+    /*
+     * A configured flat rate with no table is the pre-taper ruling, honoured
+     * verbatim — including `0`, which is the one value allowed below the floor
+     * because it means "off" rather than "cheap".
+     */
+    if (!commissions.platformFeeUnitBands && commissions.platformFeePerListingUnit !== undefined) {
+        const flat = commissions.platformFeePerListingUnit;
+        if (!Number.isFinite(flat) || flat <= 0)
+            return Math.max(0, flat === 0 ? 0 : floor);
+        return Math.max(floor, flat);
+    }
+    const bands = (commissions.platformFeeUnitBands ?? DEFAULT_PLATFORM_FEE_UNIT_BANDS)
+        .filter((b) => Number.isFinite(b.minUnits) && Number.isFinite(b.ratePerUnit))
+        .slice()
+        .sort((a, b) => a.minUnits - b.minUnits);
+    if (bands.length === 0)
+        return floor;
+    const n = Number.isFinite(units) ? Math.max(0, Math.floor(units)) : 0;
+    /*
+     * The highest band the line REACHES. Falls back to the first band for a line
+     * below every threshold — a quantity of 1 against a table starting at 5 is a
+     * gap in the table, and charging the dearest configured rate is the
+     * conservative reading of a table that forgot to cover it.
+     */
+    let rate = bands[0].ratePerUnit;
+    for (const band of bands) {
+        if (n >= band.minUnits)
+            rate = band.ratePerUnit;
+    }
+    return Math.max(floor, rate);
+}
 /**
  * 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 function computeCheckoutFees(subtotal, commissions) {
-    const uncapped = roundRupees(subtotal * (commissions.platformFeePercent / 100));
-    const cap = commissions.platformFeeMax ?? DEFAULT_PLATFORM_FEE_MAX;
-    const platformFee = Math.min(uncapped, cap);
+export function computeCheckoutFees(subtotal, commissions, lineUnitCounts) {
+    const lines = (lineUnitCounts ?? []).map((raw) => {
+        /*
+         * Clamped and integer-floored defensively. Quantities come from
+         * server-resolved cart items in every caller, so they cannot be negative or
+         * fractional today — but each is a multiplier on a charge, and a NaN here
+         * would produce a NaN total the gateway would reject only after the buyer
+         * pressed pay.
+         */
+        const units = Number.isFinite(raw) ? Math.max(0, Math.floor(raw)) : 0;
+        const ratePerUnit = resolvePlatformFeeUnitRate(units, commissions);
+        return { units, ratePerUnit, amount: roundRupees(units * ratePerUnit) };
+    });
+    const unitCount = lines.reduce((n, l) => n + l.units, 0);
+    const platformFee = roundRupees(lines.reduce((sum, l) => sum + l.amount, 0));
     const gstOnFee = roundRupees(platformFee * (commissions.gstPercent / 100));
-    const totalFee = Math.max(platformFee + gstOnFee, commissions.minimumTransactionFee ?? 0);
-    return { platformFee, gstOnFee, totalFee };
+    /*
+     * 🛑 `roundRupees` around the sum, which the pre-taper version did NOT do.
+     * `72 + 12.96` evaluates to `84.96000000000001` in IEEE-754, and `totalFee`
+     * is not a display figure — D41 established it as the amount the capture
+     * route charges. An eleven-decimal float there is a paisa dispute between the
+     * gateway and the order record waiting for a cart big enough to surface it;
+     * the old flat ₹10 fee never produced one, the taper's ₹6.50 band does.
+     */
+    const totalFee = roundRupees(Math.max(platformFee + gstOnFee, commissions.minimumTransactionFee ?? 0));
+    return { platformFee, gstOnFee, totalFee, unitCount, lines };
 }
 /**
- * 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 function allocateCheckoutFees(groupSubtotals, fees) {
+export function allocateCheckoutFees(groupSubtotals, fees, groupLineUnitCounts, commissions) {
     const allocation = new Map();
     if (groupSubtotals.length === 0)
         return allocation;
-    const total = groupSubtotals.reduce((sum, [, subtotal]) => sum + subtotal, 0);
     /*
      * ── D41: THE `minimumTransactionFee` FLOOR IS APPLIED HERE, ONCE ──────────
      *
@@ -77,15 +265,50 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
      */
     const feeShortfall = Math.max(0, roundRupees(fees.totalFee - (fees.platformFee + fees.gstOnFee)));
     const flooredPlatformFee = roundRupees(fees.platformFee + feeShortfall);
+    /*
+     * EXACT shares when the caller supplied quantities. Each store's own tapered
+     * sum, re-resolved through the one rate function — never a second formula.
+     */
+    const exactShares = groupLineUnitCounts && commissions
+        ? groupSubtotals.map(([storeId]) => roundRupees((groupLineUnitCounts.get(storeId) ?? []).reduce((sum, raw) => {
+            const units = Number.isFinite(raw) ? Math.max(0, Math.floor(raw)) : 0;
+            return sum + units * resolvePlatformFeeUnitRate(units, commissions);
+        }, 0)))
+        : null;
+    const exactTotal = exactShares ? roundRupees(exactShares.reduce((a, b) => a + b, 0)) : 0;
+    /*
+     * 🛑 The exact path is used ONLY when it reconciles with the cart-level
+     * figure. If the two disagree — a caller passing a different line set than it
+     * priced — falling back to pro-rata keeps the invariant "shares sum to the
+     * charge" intact, which is the property that actually protects the buyer. A
+     * silent disagreement between two derivations of one charge is the D37 shape;
+     * preferring the reconciling one is how it stays visible instead of billed.
+     */
+    const useExact = exactShares !== null && exactTotal === fees.platformFee;
+    const proRataTotal = groupSubtotals.reduce((sum, [, subtotal]) => sum + subtotal, 0);
     let platformRemaining = flooredPlatformFee;
     let gstRemaining = fees.gstOnFee;
     groupSubtotals.forEach(([storeId, subtotal], index) => {
         const isLast = index === groupSubtotals.length - 1;
-        // An all-zero cart can't be apportioned by share — fall back to giving the
-        // whole (necessarily zero-ish) fee to the last group rather than dividing
-        // by zero.
-        const share = total > 0 ? subtotal / total : 0;
-        const platformFee = isLast ? roundRupees(platformRemaining) : roundRupees(flooredPlatformFee * share);
+        /*
+         * The last group takes whatever is left, so the shares sum to exactly what
+         * was charged — including the `minimumTransactionFee` shortfall, which
+         * belongs to no particular store. An all-zero cart can't be apportioned by
+         * share either, so it falls through the same way rather than dividing by
+         * zero.
+         */
+        const share = useExact
+            ? flooredPlatformFee > 0
+                ? (exactShares?.[index] ?? 0) / fees.platformFee
+                : 0
+            : proRataTotal > 0
+                ? subtotal / proRataTotal
+                : 0;
+        const platformFee = isLast
+            ? roundRupees(platformRemaining)
+            : useExact && feeShortfall === 0
+                ? (exactShares?.[index] ?? 0)
+                : roundRupees(flooredPlatformFee * share);
         const gstOnFee = isLast ? roundRupees(gstRemaining) : roundRupees(fees.gstOnFee * share);
         platformRemaining = roundRupees(platformRemaining - platformFee);
         gstRemaining = roundRupees(gstRemaining - gstOnFee);
@@ -136,6 +359,26 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
  *
  * 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 function commissionPercentToRate(percent) {
+    return (percent ?? 0) / 100;
+}
 export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0, pointsFunded = 0) {
     const platformFee = roundRupees(grossAmount * (commissions.platformFeePercent / 100));
     const gatewayFee = roundRupees(grossAmount * ((commissions.gatewayFeePercent ?? 0) / 100));

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

@@ -33,6 +33,7 @@
  */
 import type { BuyerEmiSettings, BuyerFacingFees } from "../features/site-settings/fees";
 import type { BuyerEmiQuote } from "../features/emi/schedule";
+import type { PlatformFeeLine } from "./calculator";
 /** One rendered explanation: a short claim plus the steps behind it. */
 export interface FeeDerivation {
     /** One sentence answering "why am I paying this". */
@@ -41,13 +42,27 @@ export interface FeeDerivation {
     steps: string[];
 }
 /**
- * The platform commission.
+ * The platform fee — a TAPERED per-unit rate, summed per cart line.
  *
- * 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.
+ * 🛑 REWRITTEN TWICE on 2026-11-08, with the model it explains. It first
+ * described a percentage of the subtotal capped at ₹10, then a flat ₹10 per
+ * unit; the charge is now `Σ over lines ( taperedRate(units) × units )`.
+ * Leaving either version behind would have been the precise defect this
+ * module's own header warns about — "a second, prose implementation of the same
+ * rule, free to drift" — except worse, because the drifted version is shown to
+ * the person paying.
+ *
+ * 🛑 TAKES THE SERVER'S PER-LINE DERIVATION, and does not recompute it.
+ * Under a flat rate a renderer could honestly re-derive "count × rate"; under a
+ * taper it would have to re-implement the band lookup, in a browser, where a
+ * disagreement with the charge is invisible until someone adds up the invoice.
+ * So `lines` comes from `CheckoutFees.lines` — the same array the money was
+ * summed from — and this function only formats it.
+ *
+ * The derivation stays checkable in one reading: each line shows its quantity,
+ * the rate that quantity earned, and the product.
  */
-export declare function explainPlatformFee(subtotal: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+export declare function explainPlatformFee(lines: readonly PlatformFeeLine[], charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
 /**
  * GST on the commission.
  *

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

@@ -4,37 +4,57 @@ function pct(value) {
     return `${Number(value.toFixed(2))}%`;
 }
 /**
- * The platform commission.
+ * The platform fee — a TAPERED per-unit rate, summed per cart line.
  *
- * 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.
+ * 🛑 REWRITTEN TWICE on 2026-11-08, with the model it explains. It first
+ * described a percentage of the subtotal capped at ₹10, then a flat ₹10 per
+ * unit; the charge is now `Σ over lines ( taperedRate(units) × units )`.
+ * Leaving either version behind would have been the precise defect this
+ * module's own header warns about — "a second, prose implementation of the same
+ * rule, free to drift" — except worse, because the drifted version is shown to
+ * the person paying.
+ *
+ * 🛑 TAKES THE SERVER'S PER-LINE DERIVATION, and does not recompute it.
+ * Under a flat rate a renderer could honestly re-derive "count × rate"; under a
+ * taper it would have to re-implement the band lookup, in a browser, where a
+ * disagreement with the charge is invisible until someone adds up the invoice.
+ * So `lines` comes from `CheckoutFees.lines` — the same array the money was
+ * summed from — and this function only formats it.
+ *
+ * The derivation stays checkable in one reading: each line shows its quantity,
+ * the rate that quantity earned, and the product.
  */
-export function explainPlatformFee(subtotal, charged, fees, currency = "INR") {
-    if (!fees || fees.platformFeePercent === undefined)
+export function explainPlatformFee(lines, charged, fees, currency = "INR") {
+    if (!fees)
         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`);
-    }
+    const billable = lines.filter((l) => l.units > 0);
+    if (billable.length === 0)
+        return null;
+    const base = billable.reduce((sum, l) => sum + l.amount, 0);
+    const rates = new Set(billable.map((l) => l.ratePerUnit));
+    const topRate = Math.max(...billable.map((l) => l.ratePerUnit));
+    const tapered = rates.size > 1 || billable.some((l) => l.ratePerUnit < topRate);
+    const steps = billable.map((l) => l.units === 1
+        ? `${money(l.ratePerUnit)} for 1 item = ${money(l.amount)}`
+        : `${money(l.ratePerUnit)} × ${l.units} = ${money(l.amount)}`);
+    if (billable.length > 1)
+        steps.push(`Items together = ${money(base)}`);
     /*
      * 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`);
+    if (fees.minimumTransactionFee !== undefined && charged > base) {
+        steps.push(`Raised to meet the ${money(fees.minimumTransactionFee)} minimum transaction fee, which covers the fee and its GST together`);
     }
     steps.push(`You pay ${money(charged)}`);
+    const cheapest = Math.min(...billable.map((l) => l.ratePerUnit));
     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.`,
+        summary: tapered
+            ? `Our platform fee is per item, and it drops the more of one item you buy — down to ${money(cheapest)} each on this order.`
+            : `Our platform fee is ${money(topRate)} per item, and it drops the more of one item you buy.`,
         steps,
     };
 }

package/dist/_internal/shared/listing-types/_registry.d.ts

@@ -15,8 +15,8 @@
  * hand-copied. Before this, at least nine independent "list every listing
  * type" arrays existed (tab constants, admin type-filter maps, the seller
  * TypeDropdown, useListingTypeFlags, SORT_OPTIONS_BY_LISTING_TYPE, …) and
- * they had silently drifted: `art` and `stickers` were missing from most of
- * them, `bundle` — which stopped being a listingType in SB-UNI-D — was still
+ * they had silently drifted: `art-and-stickers` (then two separate members)
+ * was missing from most of them, `bundle` — which stopped being a listingType in SB-UNI-D — was still
  * present in others, and the public /products chips offered only 4 of 9
  * types. `scripts/audit-listing-type-tab-coverage.mjs` now blocks any array
  * that doesn't cover the full union.
@@ -38,13 +38,25 @@ import { type AvailabilityFilter } from "../../../constants/field-names";
  *   "closed" — hide rows that stopped accepting entries/orders
  */
 export type ListingHideDefault = "sold" | "ended" | "closed";
+/**
+ * 1A-v (overhaul brief, Single-scoped action/CTA gating) — which primary
+ * action a listing type's own PDP exposes. Each type's real buy-bar
+ * component (`renderPrimaryActions`/`functionalSlot`'s `pdp-primary-actions`)
+ * already renders the one correct control for its type via a type-safe
+ * callback prop, not a runtime lookup — this registry field does not gate
+ * that rendering (nothing needs it to). It exists so OTHER surfaces that
+ * only need to know "what kind of action is this" (search result labels,
+ * admin triage, a future cross-type summary) read one typed value instead
+ * of re-deriving it from `listingType` by hand.
+ */
+export type ActionKind = "buy-now" | "bid" | "reserve" | "enter-draw" | "make-offer";
 export interface ListingTypePlugin {
     listingType: ListingType;
     slugPrefix: string;
     cartLine: "single-product" | "blocked" | "bundle-expand";
     /** Public detail-page href builder — replaces the ad-hoc per-type href pickers duplicated across card/link components. */
     detailRoute: (idOrSlug: string) => string;
-    /** Card-grid badge shown for time-sensitive/action-required types (auction/pre-order); undefined = no badge. */
+    /** Card-grid badge shown for time-sensitive/action-required types (collector drop/pre-order); undefined = no badge. */
     badge?: {
         label: string;
         className: string;
@@ -78,7 +90,7 @@ export interface ListingTypePlugin {
      * Dedicated public browse page for this type.
      *
      * EVERY type has one today, including `standard` (→ `/products`) and
-     * `art`/`stickers` (→ the combined `/art`). This field is therefore NOT a
+     * `art-and-stickers` (→ `/art`). This field is therefore NOT a
      * "does it have its own page" discriminator — use `inGeneralCatalogue` for
      * that. (This comment used to claim `null` meant "browses on /products",
      * which no config has ever matched.)
@@ -116,7 +128,7 @@ export interface ListingTypePlugin {
      * picks quantities per member through `GroupMemberPicker`.
      *
      * 🛑 `findByGroupId` used to hard-code `["standard", "pre-order"]`, which
-     * made this field's answer invisible and wrong: a `stickers` or `art` member
+     * made this field's answer invisible and wrong: an `art-and-stickers` member
      * was silently dropped from the query, so `ShowGroupSection` saw one member
      * and returned null — the picker was unreachable with nothing erroring. That
      * is Root Cause #58's shape, a union member missing from the one allowlist
@@ -126,7 +138,7 @@ export interface ListingTypePlugin {
      * tenth type must not compile until someone decides.
      *
      * False where the type's own pricing or lifecycle makes "pick N of these"
-     * meaningless — an auction is one unique lot, a pre-order is a deposit
+     * meaningless — a collector drop is one unique lot, a pre-order is a deposit
      * against a future release, a prize-draw sells entries, a classified has no
      * cart, a digital-code is a fungible pool, and a live item is
      * jurisdiction-gated per buyer.
@@ -171,19 +183,22 @@ export interface ListingTypePlugin {
     publicSortOptions: readonly SortOption[];
     /**
      * `TABLE_KEYS` values for facets that only make sense for this type
-     * (auction bid range, classified meetup city, live-item species, …). The
+     * (collector drop bid range, classified meetup city, live-item species, …). The
      * shared product facets (category/brand/price/condition) are implicit.
      */
     extraFacetKeys: readonly string[];
+    /** See `ActionKind`. Required for the same reason as `inGeneralCatalogue`/
+     * `iconKey`: a tenth listing type must not compile until someone has
+     * answered what its PDP's primary action actually is. */
+    primaryActionKind: ActionKind;
 }
-export declare const LISTING_TYPE_REGISTRY: Record<ListingType, ListingTypePlugin>;
-export declare function pluginFor(type: ListingType): ListingTypePlugin;
 /**
- * Infer a listing type from a product slug/id by matching its registered
- * `slugPrefix` — replaces ad-hoc `id.startsWith("auction-")` chains in
- * contexts (guest carts, unauthenticated payloads) that don't carry an
- * explicit `listingType` field. Falls back to "standard" when no prefix matches.
+ * The read half of 1A-v. A plain lookup, not a gate — see `ActionKind`'s
+ * own doc comment for why nothing in the real rendering path needs this.
  */
+export declare function actionsForListingType(listingType: ListingType): ActionKind;
+export declare const LISTING_TYPE_REGISTRY: Record<ListingType, ListingTypePlugin>;
+export declare function pluginFor(type: ListingType): ListingTypePlugin;
 export declare function detectListingTypeFromSlug(slug: string): ListingType;
 /**
  * Sort options for a listing type. Replaces the hand-written
@@ -205,7 +220,7 @@ export declare function sortOptionsFor(type: ListingType, variant?: "admin" | "p
 export declare function commonSortOptionsFor(types: readonly ListingType[], variant?: "admin" | "public"): readonly SortOption[];
 /**
  * Which "Show X" quick-filter applies to a set of listing types. A mixed
- * selection can need more than one toggle (auctions end, products sell out),
+ * selection can need more than one toggle (collector drops end, products sell out),
  * so this returns every distinct default across the set.
  */
 export declare function hideDefaultsFor(types: readonly ListingType[]): ListingHideDefault[];
@@ -216,7 +231,7 @@ export interface AvailabilityTab {
 /**
  * The three-tab availability bar for a set of listing types.
  *
- * The middle label is derived, not a constant: `/auctions` reads "Ended",
+ * The middle label is derived, not a constant: `/collector-drops` reads "Ended",
  * `/art` reads "Sold", and `/products` — which spans both kinds — reads
  * "Sold & Ended". Ordering is fixed rather than set-iteration order so the
  * label can never flip to "Ended & Sold" between renders.