@mohasinac/appkit 4.55.0 → 4.57.0

package/dist/_internal/server/features/shipping/reconcile.js

@@ -0,0 +1,93 @@
+/**
+ * Close the loop on one order's shipping: compare what the buyer was charged
+ * with what the seller actually spent, and credit the difference as points.
+ *
+ * Called from the seller's dispatch path, once the real postage is known.
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { reconcileShipping, } from "../../../shared/shipping/quote.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+/**
+ * 🛑 IDEMPOTENT, and the guard is `order.shippingReconciliation` being unset.
+ *
+ * Crediting points is an APPEND to a ledger. Appends do not deduplicate
+ * themselves, so a dispatch action that fired twice — a double-clicked button,
+ * a retried job, a webhook delivered again — would pay the buyer twice, and
+ * nothing downstream could distinguish that from two genuine savings. The
+ * reconciliation record is written in the same step as the credit precisely so
+ * it can be the key.
+ *
+ * It deliberately does NOT use a transaction spanning the order and the
+ * ledger: `pointsRepository.append` already runs its own transaction over the
+ * ledger and the balance mirror, and nesting would mean reading the order
+ * inside it for no added safety. The residual risk is a crash between the
+ * credit and the order write, which leaves a credited buyer and an order that
+ * looks unreconciled — recoverable, and strictly better than the alternative
+ * ordering, which would mark the order done and then fail to pay.
+ */
+export async function reconcileOrderShipping(orderId, actual) {
+    const order = await orderRepository.findById(orderId);
+    if (!order) {
+        return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-quote" };
+    }
+    /*
+     * No quote means this order never went through the courier picker — a
+     * manually-shipped seller, or an order placed before the feature. There is
+     * no charged figure to measure against, so there is nothing to reconcile.
+     * Inventing one from the flat `shippingFee` would compare the buyer's spend
+     * against a number that was never a courier quote.
+     */
+    if (!order.selectedShippingQuote) {
+        return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-quote" };
+    }
+    if (order.shippingReconciliation) {
+        return {
+            outcome: null,
+            sellerAbsorbs: order.shippingReconciliation.sellerAbsorbs,
+            buyerPoints: order.shippingReconciliation.buyerPoints,
+            skipped: "already-reconciled",
+        };
+    }
+    const result = reconcileShipping(order.selectedShippingQuote, actual);
+    const buyerUid = order.userId;
+    if (result.buyerPoints > 0) {
+        if (!buyerUid) {
+            /*
+             * A credit with nobody to credit. Recorded rather than thrown: the
+             * parcel has shipped and the seller's dispatch must not fail because we
+             * cannot find the buyer — but this is a real data fault and has to be
+             * loud enough to find.
+             */
+            serverLogger.error("shipping reconciliation has points but no buyer", {
+                orderId,
+                buyerPoints: result.buyerPoints,
+            });
+            return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-buyer" };
+        }
+        await pointsRepository.append({
+            userId: buyerUid,
+            kind: "shipping_saving",
+            amount: result.buyerPoints,
+            orderId,
+            /*
+             * Names both couriers and both figures, because "53 points" on its own
+             * is unexplainable six weeks later — and this string is written once and
+             * never re-derived, so it stays true of the moment it describes even if
+             * the order is edited afterwards.
+             */
+            description: `Shipping saving on ${orderId}: charged ₹${order.selectedShippingQuote.chargedRate} ` +
+                `for ${order.selectedShippingQuote.courierName}, shipped ₹${actual.actualRate} ` +
+                `via ${actual.courierName}.`,
+        });
+    }
+    await orderRepository.update(orderId, {
+        actualShipmentCost: actual,
+        shippingReconciliation: { ...result, reconciledAt: new Date() },
+    });
+    return {
+        outcome: result.buyerPoints > 0 ? "credited" : result.sellerAbsorbs > 0 ? "seller-absorbed" : "exact",
+        sellerAbsorbs: result.sellerAbsorbs,
+        buyerPoints: result.buyerPoints,
+    };
+}

package/dist/_internal/shared/actions/action-registry.js

@@ -1039,6 +1039,21 @@ export const ACTIONS = {
         },
     },
     BLOG: {
+        /*
+         * Clone, admin-only, backed by POST /api/admin/blog/[id]/duplicate. A
+         * templated post is the real use case: same structure and category, new
+         * subject. The copy starts as a DRAFT with a freshly derived slug — blog is
+         * a pure-slug resource, so reusing the source slug would overwrite it.
+         */
+        "duplicate-post": {
+            iconKey: "duplicate",
+            id: "blog.duplicate-post",
+            label: "Duplicate",
+            ariaLabel: "Duplicate this post as a draft",
+            description: "Copy this post into a new draft, without its views or featured flag.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
         "create-post": {
             iconKey: "create",
             id: "blog.create-post",
@@ -1113,6 +1128,23 @@ export const ACTIONS = {
         },
     },
     EVENT: {
+        /*
+         * Clone, admin-only, backed by POST /api/admin/events/[id]/duplicate. A
+         * recurring sale is the real use case: same copy, same prizes, new dates.
+         *
+         * 🛑 The endpoint rebuilds every lottery slot from its prize definition and
+         * resets the booking half — a spread would attribute a real buyer’s
+         * purchased slot to a brand-new event.
+         */
+        duplicate: {
+            iconKey: "duplicate",
+            id: "event.duplicate",
+            label: "Duplicate",
+            ariaLabel: "Duplicate this event as a draft",
+            description: "Copy this event into a new draft, without its entries, winner or slot bookings.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
         /*
          * This bucket had only register / cancel-registration / draw-raffle-winner
          * — no edit, no delete — so the owner affordance on an event card or detail
@@ -2208,6 +2240,27 @@ export const ACTIONS = {
             kind: "ghost",
             permissions: ["admin"],
         },
+        /*
+         * Homepage sections have no bucket of their own, so their edit leaf lives
+         * here beside the carousel pair for the same reason — both are homepage
+         * chrome an admin edits from a list rather than from a detail page.
+         *
+         * 🛑 There is deliberately NO `delete-section` counterpart. Section `order`
+         * is POSITIONAL, so removing one silently renumbers its neighbours — not
+         * something to offer from the public homepage, where the only confirmation
+         * a person gets is a dialog. `OwnerQuickActions` enforces the absence by
+         * omitting `remove` from the SECTION mapping, so no call site can pass a
+         * delete handler and have it render.
+         */
+        "edit-section": {
+            iconKey: "edit",
+            id: "admin.edit-section",
+            label: "Edit Section",
+            ariaLabel: "Edit this homepage section",
+            description: "Open the homepage sections list, which owns this section's config.",
+            kind: "ghost",
+            permissions: ["admin"],
+        },
         "delete-carousel": {
             iconKey: "delete",
             id: "admin.delete-carousel",

package/dist/_internal/shared/config/schema.d.ts

@@ -89,6 +89,12 @@ export interface AppkitBrandConfig {
     name: string;
     /** Short / abbreviated name, e.g. "LT" */
     shortName?: string;
+    /**
+     * Standalone lockup line under the homepage hero logo, e.g. "Let It Rip
+     * India". Not `name`: that one is a sentence ingredient ("Why Buyers Trust
+     * {name}") and this one stands alone, so they are spelled differently.
+     */
+    heroCaption?: string;
     /** One-line brand description used in meta tags and footers */
     description?: string;
     /** Tagline shown in footer / about sections */

package/dist/_internal/shared/listing-types/route-gating.d.ts

@@ -0,0 +1,56 @@
+/**
+ * "Does this href lead somewhere the site has switched off?"
+ *
+ * ## Why this exists
+ *
+ * `listings.listingTypes` already hides a disabled type everywhere the type is
+ * named — the nav, the `/products` chips, the admin tabs, the homepage
+ * SECTIONS (`HOMEPAGE_SECTION_LISTING_TYPE` in `MarketplaceHomepageView`). But
+ * a lot of this site's merchandising is free-text content that names a
+ * destination by URL and never mentions a listing type at all: a carousel
+ * slide's overlay button, a card's CTA, a promo-grid tile.
+ *
+ * Measured 2026-10-20 with `auction: false` live: the homepage hero carousel
+ * still shipped a "Live auctions / Place a bid before the timer runs out"
+ * CARD linking to `/auctions`, and a whole `slide-beyblade-auction` slide
+ * whose overlay read "Win it at your price". Both are authored content, so no
+ * type-keyed gate could see them — the only thing that identifies them is
+ * where they point.
+ *
+ * ## The rule, and the one case that makes it non-obvious
+ *
+ * A href is disabled when EVERY listing type that claims its route is
+ * disabled. Not "any" — `art` and `stickers` share `/art`, so a site that
+ * sells art but not stickers must keep `/art` reachable. Treating one disabled
+ * claimant as enough would silently delete a working destination.
+ *
+ * ## What it deliberately does NOT match
+ *
+ * Editorial pages that merely have a type's name in the path — `/help/auctions`,
+ * `/how-auctions-work`, `/seller-guide/prize-draws`. None of them starts with
+ * `/auctions`, so prefix matching excludes them for free, and that is correct:
+ * an explainer about auctions is still honest reading when auctions are off.
+ * A substring test would have eaten all three.
+ *
+ * Store tabs (`/stores/{slug}/auctions`) are also out of scope — those are
+ * resolved by `resolveStoreTabs`, which owns its own visibility, and a second
+ * owner is how a mirror drifts (Root Cause #42).
+ */
+import type { ListingType } from "../../../features/products/types/index";
+interface ListingFlagSnapshot {
+    listings?: {
+        listingTypes?: Partial<Record<ListingType, boolean>>;
+    };
+}
+/**
+ * `true` when `href` points at a listing type's browse page (or any page
+ * beneath it) and every type that browses there is disabled.
+ *
+ * Fails OPEN on anything it cannot classify: an unknown path, an external URL
+ * or a missing settings document all return `false`. A settings read that
+ * errored must not strip working destinations out of the homepage — the same
+ * reasoning as the suggestions endpoint's TTL cache and `src/proxy.ts`'s
+ * disabled-routes gate.
+ */
+export declare function isDisabledListingHref(href: string | undefined | null, settings: ListingFlagSnapshot | null | undefined): boolean;
+export {};

package/dist/_internal/shared/listing-types/route-gating.js

@@ -0,0 +1,114 @@
+/**
+ * "Does this href lead somewhere the site has switched off?"
+ *
+ * ## Why this exists
+ *
+ * `listings.listingTypes` already hides a disabled type everywhere the type is
+ * named — the nav, the `/products` chips, the admin tabs, the homepage
+ * SECTIONS (`HOMEPAGE_SECTION_LISTING_TYPE` in `MarketplaceHomepageView`). But
+ * a lot of this site's merchandising is free-text content that names a
+ * destination by URL and never mentions a listing type at all: a carousel
+ * slide's overlay button, a card's CTA, a promo-grid tile.
+ *
+ * Measured 2026-10-20 with `auction: false` live: the homepage hero carousel
+ * still shipped a "Live auctions / Place a bid before the timer runs out"
+ * CARD linking to `/auctions`, and a whole `slide-beyblade-auction` slide
+ * whose overlay read "Win it at your price". Both are authored content, so no
+ * type-keyed gate could see them — the only thing that identifies them is
+ * where they point.
+ *
+ * ## The rule, and the one case that makes it non-obvious
+ *
+ * A href is disabled when EVERY listing type that claims its route is
+ * disabled. Not "any" — `art` and `stickers` share `/art`, so a site that
+ * sells art but not stickers must keep `/art` reachable. Treating one disabled
+ * claimant as enough would silently delete a working destination.
+ *
+ * ## What it deliberately does NOT match
+ *
+ * Editorial pages that merely have a type's name in the path — `/help/auctions`,
+ * `/how-auctions-work`, `/seller-guide/prize-draws`. None of them starts with
+ * `/auctions`, so prefix matching excludes them for free, and that is correct:
+ * an explainer about auctions is still honest reading when auctions are off.
+ * A substring test would have eaten all three.
+ *
+ * Store tabs (`/stores/{slug}/auctions`) are also out of scope — those are
+ * resolved by `resolveStoreTabs`, which owns its own visibility, and a second
+ * owner is how a mirror drifts (Root Cause #42).
+ */
+import { LISTING_TYPE_REGISTRY } from "./_registry.js";
+import { ALL_LISTING_TYPES, isListingTypeEnabled } from "./feature-flags.js";
+/**
+ * browse route → every listing type that browses there.
+ *
+ * Built from the registry rather than hand-listed, so a tenth type joins it by
+ * existing. `art` and `stickers` both resolve to `/art`, which is the entire
+ * reason the value is an array.
+ */
+const TYPES_BY_BROWSE_ROUTE = (() => {
+    const map = new Map();
+    for (const type of ALL_LISTING_TYPES) {
+        const route = normalisePath(LISTING_TYPE_REGISTRY[type].browseRoute);
+        if (!route)
+            continue;
+        const existing = map.get(route);
+        if (existing)
+            existing.push(type);
+        else
+            map.set(route, [type]);
+    }
+    return map;
+})();
+/**
+ * Reduce an authored href to a comparable path.
+ *
+ * Returns `""` for anything that is not an in-app path — an absolute URL to
+ * another origin, a `mailto:`, an anchor. Those can never be a listing browse
+ * route, and a caller must not filter them out.
+ *
+ * 🛑 The locale prefix is stripped. `ROUTES` values are unprefixed
+ * (`/auctions`) and `next-intl` adds `/en` at navigation time, but an admin
+ * pasting a URL out of the address bar stores the prefixed form — so a
+ * comparison against the raw value matches the seed and misses the hand-typed
+ * one, which is the half most likely to be wrong.
+ */
+function normalisePath(href) {
+    if (typeof href !== "string")
+        return "";
+    const trimmed = href.trim();
+    if (!trimmed || !trimmed.startsWith("/"))
+        return "";
+    // Drop query + hash: `/auctions?sort=ending` is still /auctions.
+    const path = trimmed.split(/[?#]/)[0] ?? "";
+    // `/en/auctions` → `/auctions`. Two-letter segment only, so a real route
+    // whose first segment is short (there are none today, but `/ar` would be a
+    // plausible future one) is the only thing this could over-match — and it
+    // would have to collide with a locale code to do it.
+    const delocalised = path.replace(/^\/[a-z]{2}(?=\/)/, "");
+    // Trailing slash off, but never reduce "/" to "".
+    return delocalised.length > 1 ? delocalised.replace(/\/+$/, "") : delocalised;
+}
+/**
+ * `true` when `href` points at a listing type's browse page (or any page
+ * beneath it) and every type that browses there is disabled.
+ *
+ * Fails OPEN on anything it cannot classify: an unknown path, an external URL
+ * or a missing settings document all return `false`. A settings read that
+ * errored must not strip working destinations out of the homepage — the same
+ * reasoning as the suggestions endpoint's TTL cache and `src/proxy.ts`'s
+ * disabled-routes gate.
+ */
+export function isDisabledListingHref(href, settings) {
+    const path = normalisePath(href);
+    if (!path)
+        return false;
+    for (const [route, types] of TYPES_BY_BROWSE_ROUTE) {
+        // The browse page itself, or a detail page under it. `startsWith(route)`
+        // alone would match `/live` against `/livestream`, so the boundary is
+        // explicit.
+        if (path !== route && !path.startsWith(`${route}/`))
+            continue;
+        return types.every((type) => !isListingTypeEnabled(type, settings));
+    }
+    return false;
+}

package/dist/_internal/shared/shipping/quote.d.ts

@@ -0,0 +1,153 @@
+/**
+ * What the buyer is quoted for shipping, what the seller actually spent, and
+ * who wears the difference.
+ *
+ * Pure and synchronous — no I/O, no Firestore, no provider. Every surface that
+ * touches a shipping figure resolves through here so the quote shown at
+ * checkout, the amount charged, the order record and the reconciliation can
+ * never disagree (Root Cause #75: a rule reachable by copy-paste WILL be
+ * copied, and the copy never learns about the branch added later).
+ *
+ * ## The model
+ *
+ * 1. Shiprocket returns per-courier rates for the buyer's pincode.
+ * 2. Each rate is ROUNDED UP to the nearest ₹50 and that is what the buyer
+ *    sees and is charged. The raw rate is never shown and never billed.
+ * 3. The seller ships. If their courier is dearer than the charged figure they
+ *    absorb the difference; if it is cheaper the buyer is credited the
+ *    difference in points, 1 point = ₹1.
+ *
+ * ## 🛑 Reconciliation measures against the CHARGED figure, not the raw rate
+ *
+ * This is the decision that makes the whole thing coherent, and it is worth
+ * stating because the obvious alternative is defensible and wrong.
+ *
+ * Measuring against the raw rate would let the platform keep the round-up
+ * (₹70 raw → ₹100 charged → a silent ₹30 margin on every parcel) while still
+ * calling the ₹50 step a "rounding". Measuring against the charged figure
+ * means the buyer is made whole for every rupee they handed over that did not
+ * become postage: ₹100 charged, shipped at ₹47, 53 points back. The round-up
+ * stops being a margin and becomes a BUFFER that absorbs ordinary courier
+ * variance before the seller has to.
+ *
+ * It also makes the rule explainable in one sentence to both sides — "you pay
+ * the rounded quote and get back whatever we did not spend", "you keep the
+ * quote and cover any overage" — and a rule a seller can predict is a rule
+ * they do not dispute.
+ */
+/**
+ * Shipping is always billed in whole ₹50 steps.
+ *
+ * 🛑 Not a formatting choice. A courier rate is a volatile per-parcel number
+ * (fuel, zone, weight slab, surcharge) and quoting it to the rupee invites a
+ * dispute every time the actual differs by ₹3. A coarse step makes the quote
+ * stable, makes it look like a price rather than a machine reading, and buys
+ * the headroom that keeps most orders off the reconciliation path entirely.
+ */
+export declare const SHIPPING_ROUND_UP_TO = 50;
+/**
+ * Round a raw carrier rate up to the next ₹50.
+ *
+ * `Math.ceil`, so ₹70 → ₹100 and ₹100 → ₹100 — a rate exactly on a step is NOT
+ * pushed to the next one. ₹0 stays ₹0: free shipping must survive the rounding
+ * or every free-shipping order silently acquires a ₹50 charge.
+ *
+ * Negative input is clamped to 0 rather than rounded "up" toward zero, which
+ * would otherwise turn a bad provider response into a credit.
+ */
+export declare function roundShippingUp(rawRate: number): number;
+/** One courier the buyer may pick, as offered at checkout. */
+export interface ShippingQuoteOption {
+    /** Stable id from the carrier, so a pick survives a re-quote. */
+    courierId: string;
+    /** Display name — "Ekart", "Delhivery", "India Post". */
+    courierName: string;
+    /**
+     * The carrier's own rate, kept for the audit trail and NEVER rendered.
+     *
+     * 🛑 Showing both numbers would invite "why am I paying ₹100 for a ₹70
+     * courier" — a question whose honest answer (the difference comes back to
+     * you as points if it is not spent) is not something a buyer should have to
+     * reconstruct from two figures on a checkout page.
+     */
+    rawRate: number;
+    /** What the buyer sees and is charged. `roundShippingUp(rawRate)`. */
+    chargedRate: number;
+    estimatedDays: number;
+}
+/**
+ * The option the buyer committed to, frozen onto the order.
+ *
+ * 🛑 Stored, never recomputed. Carrier rates move hourly; re-quoting at
+ * reconciliation time would compare the seller's actual spend against a price
+ * nobody was ever charged, and the buyer's points would change depending on
+ * when the job happened to run. Same reasoning as `OrderSourceContext` being
+ * written once at creation.
+ */
+export interface SelectedShippingQuote {
+    courierId: string;
+    courierName: string;
+    rawRate: number;
+    /** The amount actually added to the order total. */
+    chargedRate: number;
+    estimatedDays: number;
+    /** When the quote was taken, so a stale pick is recognisable. */
+    quotedAt: Date;
+}
+/** What the seller really shipped with, recorded when they dispatch. */
+export interface ActualShipmentCost {
+    courierId: string;
+    courierName: string;
+    /** The seller's real postage, to the rupee. Not rounded. */
+    actualRate: number;
+}
+/**
+ * The outcome of comparing what was charged with what was spent.
+ *
+ * Exactly one of `sellerAbsorbs` / `buyerPoints` is non-zero, and both are
+ * non-negative — a signed "difference" field would make every consumer decide
+ * what its sign meant, and the two directions have completely different
+ * consequences (one is a cost to a seller, one is a credit to a buyer).
+ */
+export interface ShippingReconciliation {
+    /** Rupees the seller eats because their courier cost more than quoted. */
+    sellerAbsorbs: number;
+    /** Points credited to the buyer, 1 point = ₹1. */
+    buyerPoints: number;
+    /** True when the seller shipped with a courier the buyer did not choose. */
+    courierChanged: boolean;
+}
+/**
+ * Compare the charged quote against the real spend.
+ *
+ * 🛑 Works on the CHARGED figure (see the header). The worked examples from the
+ * spec, with the ₹70 Ekart quote billed at ₹100:
+ *
+ *   shipped Delhivery ₹100 → sellerAbsorbs 0,   buyerPoints 0
+ *   shipped Delhivery ₹120 → sellerAbsorbs 20,  buyerPoints 0
+ *   shipped India Post ₹47 → sellerAbsorbs 0,   buyerPoints 53
+ *
+ * Points are the EXACT rupee difference and are deliberately not rounded to a
+ * ₹50 step. The round-up exists to make a *quote* stable; applying it to a
+ * credit would either invent money (rounding up) or quietly keep some of the
+ * buyer's (rounding down).
+ */
+export declare function reconcileShipping(quote: Pick<SelectedShippingQuote, "chargedRate" | "courierId">, actual: ActualShipmentCost): ShippingReconciliation;
+/**
+ * Turn carrier serviceability results into offerable options.
+ *
+ * 🛑 Drops any courier whose rate is not a usable number instead of charging
+ * ₹0 for it. `resolveShippingCost` already carries this lesson in its
+ * `shippingUnavailable` flag: a zero there "would ship every parcel free at
+ * our expense, silently, until somebody noticed". A malformed row from a
+ * provider is missing data, never free postage.
+ *
+ * Sorted cheapest-first, then fastest — the buyer is choosing, so the default
+ * reading order should be the one most of them want.
+ */
+export declare function toQuoteOptions(couriers: readonly {
+    courierId?: string;
+    name: string;
+    rate: number;
+    estimatedDays: number;
+}[]): ShippingQuoteOption[];

package/dist/_internal/shared/shipping/quote.js

@@ -0,0 +1,123 @@
+/**
+ * What the buyer is quoted for shipping, what the seller actually spent, and
+ * who wears the difference.
+ *
+ * Pure and synchronous — no I/O, no Firestore, no provider. Every surface that
+ * touches a shipping figure resolves through here so the quote shown at
+ * checkout, the amount charged, the order record and the reconciliation can
+ * never disagree (Root Cause #75: a rule reachable by copy-paste WILL be
+ * copied, and the copy never learns about the branch added later).
+ *
+ * ## The model
+ *
+ * 1. Shiprocket returns per-courier rates for the buyer's pincode.
+ * 2. Each rate is ROUNDED UP to the nearest ₹50 and that is what the buyer
+ *    sees and is charged. The raw rate is never shown and never billed.
+ * 3. The seller ships. If their courier is dearer than the charged figure they
+ *    absorb the difference; if it is cheaper the buyer is credited the
+ *    difference in points, 1 point = ₹1.
+ *
+ * ## 🛑 Reconciliation measures against the CHARGED figure, not the raw rate
+ *
+ * This is the decision that makes the whole thing coherent, and it is worth
+ * stating because the obvious alternative is defensible and wrong.
+ *
+ * Measuring against the raw rate would let the platform keep the round-up
+ * (₹70 raw → ₹100 charged → a silent ₹30 margin on every parcel) while still
+ * calling the ₹50 step a "rounding". Measuring against the charged figure
+ * means the buyer is made whole for every rupee they handed over that did not
+ * become postage: ₹100 charged, shipped at ₹47, 53 points back. The round-up
+ * stops being a margin and becomes a BUFFER that absorbs ordinary courier
+ * variance before the seller has to.
+ *
+ * It also makes the rule explainable in one sentence to both sides — "you pay
+ * the rounded quote and get back whatever we did not spend", "you keep the
+ * quote and cover any overage" — and a rule a seller can predict is a rule
+ * they do not dispute.
+ */
+/**
+ * Shipping is always billed in whole ₹50 steps.
+ *
+ * 🛑 Not a formatting choice. A courier rate is a volatile per-parcel number
+ * (fuel, zone, weight slab, surcharge) and quoting it to the rupee invites a
+ * dispute every time the actual differs by ₹3. A coarse step makes the quote
+ * stable, makes it look like a price rather than a machine reading, and buys
+ * the headroom that keeps most orders off the reconciliation path entirely.
+ */
+export const SHIPPING_ROUND_UP_TO = 50;
+/**
+ * Round a raw carrier rate up to the next ₹50.
+ *
+ * `Math.ceil`, so ₹70 → ₹100 and ₹100 → ₹100 — a rate exactly on a step is NOT
+ * pushed to the next one. ₹0 stays ₹0: free shipping must survive the rounding
+ * or every free-shipping order silently acquires a ₹50 charge.
+ *
+ * Negative input is clamped to 0 rather than rounded "up" toward zero, which
+ * would otherwise turn a bad provider response into a credit.
+ */
+export function roundShippingUp(rawRate) {
+    if (!Number.isFinite(rawRate) || rawRate <= 0)
+        return 0;
+    return Math.ceil(rawRate / SHIPPING_ROUND_UP_TO) * SHIPPING_ROUND_UP_TO;
+}
+/**
+ * Compare the charged quote against the real spend.
+ *
+ * 🛑 Works on the CHARGED figure (see the header). The worked examples from the
+ * spec, with the ₹70 Ekart quote billed at ₹100:
+ *
+ *   shipped Delhivery ₹100 → sellerAbsorbs 0,   buyerPoints 0
+ *   shipped Delhivery ₹120 → sellerAbsorbs 20,  buyerPoints 0
+ *   shipped India Post ₹47 → sellerAbsorbs 0,   buyerPoints 53
+ *
+ * Points are the EXACT rupee difference and are deliberately not rounded to a
+ * ₹50 step. The round-up exists to make a *quote* stable; applying it to a
+ * credit would either invent money (rounding up) or quietly keep some of the
+ * buyer's (rounding down).
+ */
+export function reconcileShipping(quote, actual) {
+    const charged = Number.isFinite(quote.chargedRate) ? Math.max(0, quote.chargedRate) : 0;
+    const spent = Number.isFinite(actual.actualRate) ? Math.max(0, actual.actualRate) : 0;
+    const delta = roundMoney(charged - spent);
+    return {
+        sellerAbsorbs: delta < 0 ? Math.abs(delta) : 0,
+        buyerPoints: delta > 0 ? delta : 0,
+        courierChanged: quote.courierId !== actual.courierId,
+    };
+}
+/**
+ * Two decimal places.
+ *
+ * Money is stored as decimal rupees (Root Cause #31), so a subtraction can
+ * leave a float artefact — `100 - 47.1` is `52.900000000000006`, and that would
+ * become a points credit with eleven decimal places on a user's balance.
+ */
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * Turn carrier serviceability results into offerable options.
+ *
+ * 🛑 Drops any courier whose rate is not a usable number instead of charging
+ * ₹0 for it. `resolveShippingCost` already carries this lesson in its
+ * `shippingUnavailable` flag: a zero there "would ship every parcel free at
+ * our expense, silently, until somebody noticed". A malformed row from a
+ * provider is missing data, never free postage.
+ *
+ * Sorted cheapest-first, then fastest — the buyer is choosing, so the default
+ * reading order should be the one most of them want.
+ */
+export function toQuoteOptions(couriers) {
+    return couriers
+        .filter((c) => Number.isFinite(c.rate) && c.rate > 0 && Boolean(c.name))
+        .map((c) => ({
+        // Providers do not all return an id. Falling back to the name keeps the
+        // pick round-trippable; it is only ever compared against itself.
+        courierId: c.courierId ?? c.name,
+        courierName: c.name,
+        rawRate: c.rate,
+        chargedRate: roundShippingUp(c.rate),
+        estimatedDays: c.estimatedDays,
+    }))
+        .sort((a, b) => a.chargedRate - b.chargedRate || a.estimatedDays - b.estimatedDays);
+}

package/dist/client.d.ts

@@ -387,6 +387,8 @@ export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewP
 export { useOrders, useOrder, OrdersList } from "./features/orders/index";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./features/orders/components/OrderStatusTimeline";
+export { EmiInstallmentsPanel } from "./features/orders/components/EmiInstallmentsPanel";
+export type { EmiInstallmentsPanelProps } from "./features/orders/components/EmiInstallmentsPanel";
 export { CountdownDisplay } from "./ui/components/CountdownDisplay";
 export type { CountdownDisplayProps } from "./ui/components/CountdownDisplay";
 export { OrderAddonBadges } from "./features/orders/components/OrderAddonBadges";
@@ -534,6 +536,7 @@ export { SELLER_LISTING_TABS, type SellerListingTabId, } from "./features/produc
 export { ALL_TAB, EMPTY_TAB, ADMIN_PRODUCT_STATUS_TABS, ADMIN_PRODUCT_LISTING_TYPE_TABS, ADMIN_BLOG_STATUS_TABS, ADMIN_USER_STATUS_TABS, ADMIN_USER_ROLE_TABS, ADMIN_STORE_STATUS_TABS, ADMIN_PAYOUT_STATUS_TABS, ADMIN_ORDER_STATUS_TABS, ADMIN_REVIEW_STATUS_TABS, ADMIN_REVIEW_RATING_TABS, ADMIN_BID_STATUS_TABS, ADMIN_CONTACT_STATUS_TABS, ADMIN_NEWSLETTER_STATUS_TABS, ADMIN_EVENT_ENTRY_STATUS_TABS, ADMIN_EVENT_STATUS_TABS, ADMIN_CART_OWNERSHIP_TABS, ADMIN_COUPON_TYPE_TABS, SELLER_PRODUCT_STATUS_TABS, SELLER_AUCTION_STATUS_TABS, SELLER_ORDER_STATUS_TABS, SELLER_OFFER_STATUS_TABS, SELLER_BID_STATUS_TABS, } from "./features/admin/constants/filter-tabs";
 export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS, BID_FIELDS, AD_FIELDS, EVENT_FIELDS, EVENT_ENTRY_FIELDS, PAYOUT_FIELDS, STORE_FIELDS, CATEGORY_FIELDS, BLOG_FIELDS, USER_FIELDS, ADDRESS_FIELDS, BRAND_FIELDS, CART_FIELDS, WISHLIST_FIELDS, HISTORY_FIELDS, NOTIFICATION_FIELDS, SESSION_FIELDS, COUPON_USAGE_FIELDS, SCAMMER_FIELDS, SUPPORT_TICKET_FIELDS, CAROUSEL_FIELDS, COUPON_FIELDS, FAQ_FIELDS, HOMEPAGE_SECTION_FIELDS, SITE_SETTINGS_FIELDS, COMMON_FIELDS, OAUTH_STATE_VALUES, SCHEMA_DEFAULTS, } from "./constants/field-names";
 export { CART_LANE, CART_LANE_PRIORITY, CART_LANE_LABELS, laneOf, activeLane, laneItems, laneCounts, isLaneCheckoutable, laneBlockReason, isLockedLane, canAddNewItems, type CartLane, type LaneAssignable, } from "./_internal/shared/checkout/lanes";
+export { roundShippingUp, toQuoteOptions, reconcileShipping, SHIPPING_ROUND_UP_TO, type ShippingQuoteOption, type SelectedShippingQuote, type ActualShipmentCost, type ShippingReconciliation, } from "./_internal/shared/shipping/quote";
 export { getCartLineMembers, isMultiMemberLine, } from "./_internal/shared/checkout/line-members";
 export { newsletterSubscribeSchema, quickCreateTaxonomySchema, payoutMarkPaidSchema, } from "./features/admin/schemas/small-forms";
 export { raffleEntrySchema } from "./features/contact/schemas/inquiry-forms";
@@ -583,3 +586,22 @@ export { PriceIndexToolView } from "./features/price-index/components/PriceIndex
 export type { PriceIndexToolViewProps, PriceIndexToolResponse, PriceIndexResultRow, PriceIndexBandRow, PriceIndexConditionRow, } from "./features/price-index/components/PriceIndexToolView";
 export { COURIER_RATING_MIN_CONFIDENT_SAMPLES, courierRatingDisplay, isValidCourierVote, courierVoteId, rollUpCourierVotes, } from "./_internal/shared/features/shipping/courier-rating";
 export type { CourierRatingPair, CourierRatingDisplay, CourierRatingVote, CourierStats, } from "./_internal/shared/features/shipping/courier-rating";
+/**
+ * The `/api/checkout/pricing-preview` RESPONSE CONTRACT.
+ *
+ * 🛑 `export type`, from a `_internal/server` module, deliberately. A type-only
+ * re-export is fully erased at compile time — `audit-client-server-only-leak`
+ * states that explicitly — so this pulls no server chain into the client
+ * bundle. It is the one exception worth making for this module.
+ *
+ * The consumer had been keeping a HAND-WRITTEN copy of both shapes in
+ * `src/lib/api/payment-client.ts`, under a comment reading "mirrors
+ * `CheckoutPricingPreviewStore` on the server". It drifted exactly as Root
+ * Cause #42 predicts: the server gained `emiSurcharge`, the mirror did not, and
+ * the preview the cart rendered could not be assigned to the breakdown
+ * component that displays it. Four `tsc` errors across the cart and checkout
+ * clients, all from one missing field in a second definition of one shape.
+ *
+ * A response contract has exactly one owner — the handler that produces it.
+ */
+export type { CheckoutPricingPreview, CheckoutPricingPreviewStore, } from "./_internal/server/features/checkout/actions";