@mohasinac/appkit 4.55.0 → 4.56.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.55.0",
-  "head": "e683e7b08996d66d9b6bef65cf4712b8e63454ea",
+  "version": "4.56.0",
+  "head": "a2d85e72b5cac1f1a55ae7386f661b293eccd704",
   "branch": "main",
-  "dirty": false,
-  "builtAt": "2026-10-20T15:42:52.181Z"
+  "dirty": true,
+  "builtAt": "2026-10-20T16:58:51.945Z"
 }

package/dist/_internal/server/features/checkout/actions.d.ts

@@ -105,6 +105,18 @@ export interface CheckoutPricingPreviewInput {
      * is currently gated off.
      */
     lane?: CartLane;
+    /**
+     * The chosen EMI tenure, when `paymentMethod` is `"emi"`.
+     *
+     * 🛑 REQUIRED for an EMI preview to be truthful. The surcharge is
+     * `principalRemaining × surchargePercentPerMonth × tenureMonths`, so it
+     * cannot be derived from the cart alone — and without it this function
+     * returned a total that `createOrderForGroup` then exceeded by exactly that
+     * amount. Unlike the add-ons below, the tenure is NOT on the cart document:
+     * it is picked on the payment step and belongs to the order, so it has to
+     * travel with the request.
+     */
+    emiTenureMonths?: number;
 }
 /** One store's slice of the preview — what that seller's order will cost. */
 export interface CheckoutPricingPreviewStore {
@@ -116,6 +128,14 @@ export interface CheckoutPricingPreviewStore {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /**
+     * EMI surcharge for THIS seller, when the buyer is previewing an EMI order.
+     *
+     * Per store because `computeEmiSchedule` takes a SELLER subtotal — the
+     * financed principal is per order, not per cart, so a cart-wide figure
+     * would not match any order written.
+     */
+    emiSurcharge: number;
     gstAmount: number;
     couponDiscount: number;
     total: number;
@@ -147,6 +167,8 @@ export interface CheckoutPricingPreview {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /** Total EMI surcharge across sellers. Zero unless previewing an EMI order. */
+    emiSurcharge: number;
     gstAmount: number;
     couponDiscount: number;
     /** Buyer-facing platform commission, capped, charged once for this checkout. */

package/dist/_internal/server/features/checkout/actions.js

@@ -44,7 +44,7 @@ import { verifyPaymentSignature as verifyRazorpayPaymentSignature } from "../../
 import { resolveKeys } from "../../../../core/integration-keys.js";
 import { paiseToRupees } from "../../../../core/money.js";
 import { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_DEFAULT_EMI_SETTINGS } from "../../../shared/features/checkout/config.js";
-import { checkEmiEligibility, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
+import { checkEmiEligibility, computeBuyerEmiQuote, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
 import { formatShippingAddress } from "./data.js";
 import { enforceMaxPerUserForCart } from "./prize-bundle-gates.js";
 import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, } from "../../../shared/checkout/rules/index.js";
@@ -1172,6 +1172,7 @@ const EMPTY_PRICING_PREVIEW = {
     giftWrapFee: 0,
     shipmentProtectionFee: 0,
     saleProtectionFee: 0,
+    emiSurcharge: 0,
     gstAmount: 0,
     couponDiscount: 0,
     platformFee: 0,
@@ -1189,7 +1190,7 @@ const EMPTY_PRICING_PREVIEW = {
  * stock, creates an order, or writes coupon usage.
  */
 export async function previewCheckoutPricing(input) {
-    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, } = input;
+    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, emiTenureMonths, } = input;
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
     const cart = await unitOfWork.carts.getOrCreate(uid);
@@ -1242,7 +1243,7 @@ export async function previewCheckoutPricing(input) {
     for (const { items: group } of orderGroups) {
         const firstItem = group[0].item;
         const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
-        const { shippingFee: groupShippingFee, storeState, storeProtections } = await resolveShippingCost(firstItem.storeId);
+        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId);
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
         const addons = cart.storeAddons?.[firstItem.storeId] ?? {};
@@ -1250,6 +1251,36 @@ export async function previewCheckoutPricing(input) {
         // ever charged for literal "cod" (pay the courier), never upi_manual or
         // cash (both pre-paid via UPI/bank transfer before dispatch).
         const groupCodHandlingFee = paymentMethod === "cod" ? computeCodHandlingFee(groupTotal, commissions) : 0;
+        /*
+         * 🛑 The EMI surcharge is a TERM OF THE TOTAL, and it was missing here
+         * while `createOrderForGroup` added it — a shown-vs-charged drift of
+         * exactly the kind this function exists to prevent.
+         *
+         * Measured on the live settings (tokenPercent 10, surchargePercentPerMonth
+         * 1) against the ₹20,000 listing: token ₹2,000, financed ₹18,000, so the
+         * surcharge is ₹360 at the default 2-month tenure and ₹1,080 at 6. The
+         * Order Summary showed ₹20,011.80 either way, and the order recorded up to
+         * ₹1,080 more. Worse, the EMI panel beside it already displayed
+         * instalments computed WITH the surcharge, so the page disagreed with
+         * itself.
+         *
+         * `computeBuyerEmiQuote`, never `computeEmiSchedule`: the latter also
+         * returns the platform/seller split of the surcharge, which is our
+         * commercial arrangement with the seller and has no business reaching a
+         * browser (see § "Buyer-facing fees").
+         *
+         * Eligibility is deliberately NOT enforced here. A preview that threw
+         * would blank the Order Summary; `createOrderForGroup` still refuses an
+         * ineligible EMI order, which is where refusing belongs. An ineligible
+         * cart simply previews no surcharge, because the tenure never applies.
+         */
+        let groupEmiSurcharge = 0;
+        if (paymentMethod === "emi" && emiTenureMonths && siteSettings?.emi) {
+            const emiSettings = siteSettings.emi;
+            if (checkEmiEligibility(groupTotal, storeEmiEnabled, emiSettings).eligible) {
+                groupEmiSurcharge = computeBuyerEmiQuote(groupTotal, emiTenureMonths, emiSettings).surchargeAmount;
+            }
+        }
         const groupGiftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissions);
         /*
          * C5e — the same three tiers `createOrderForGroup` enforces, so the figure
@@ -1302,6 +1333,7 @@ export async function previewCheckoutPricing(input) {
             subtotal: groupTotal,
             shippingFee: groupShippingFee,
             codHandlingFee: groupCodHandlingFee,
+            emiSurcharge: groupEmiSurcharge,
             giftWrapFee: groupGiftWrapFee,
             shipmentProtectionFee: groupShipmentProtectionFee,
             saleProtectionFee: groupSaleProtectionFee,
@@ -1319,6 +1351,7 @@ export async function previewCheckoutPricing(input) {
             total: Math.max(0, groupTotal - groupCouponDiscount) +
                 groupShippingFee +
                 groupCodHandlingFee +
+                groupEmiSurcharge +
                 groupGiftWrapFee +
                 groupShipmentProtectionFee +
                 groupSaleProtectionFee,
@@ -1330,6 +1363,7 @@ export async function previewCheckoutPricing(input) {
     const sum = (pick) => stores.reduce((acc, s) => acc + pick(s), 0);
     const shippingFee = sum((s) => s.shippingFee);
     const codHandlingFee = sum((s) => s.codHandlingFee);
+    const emiSurcharge = sum((s) => s.emiSurcharge);
     const giftWrapFeeTotal = sum((s) => s.giftWrapFee);
     const shipmentProtectionFeeTotal = sum((s) => s.shipmentProtectionFee);
     const saleProtectionFeeTotal = sum((s) => s.saleProtectionFee);
@@ -1366,6 +1400,7 @@ export async function previewCheckoutPricing(input) {
     const total = Math.max(0, cartSubtotal - couponDiscount) +
         shippingFee +
         codHandlingFee +
+        emiSurcharge +
         giftWrapFeeTotal +
         shipmentProtectionFeeTotal +
         saleProtectionFeeTotal +
@@ -1375,6 +1410,7 @@ export async function previewCheckoutPricing(input) {
         subtotal: cartSubtotal,
         shippingFee,
         codHandlingFee,
+        emiSurcharge,
         giftWrapFee: giftWrapFeeTotal,
         shipmentProtectionFee: shipmentProtectionFeeTotal,
         saleProtectionFee: saleProtectionFeeTotal,

package/dist/_internal/server/features/shipping/reconcile.d.ts

@@ -0,0 +1,28 @@
+import { type ActualShipmentCost } from "../../../shared/shipping/quote";
+export interface ReconcileShippingResult {
+    /** `null` when there was nothing to reconcile — see the reasons below. */
+    outcome: "credited" | "seller-absorbed" | "exact" | null;
+    sellerAbsorbs: number;
+    buyerPoints: number;
+    /** Why nothing happened, when `outcome` is null. For logs and the UI. */
+    skipped?: "no-quote" | "already-reconciled" | "no-buyer";
+}
+/**
+ * 🛑 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 declare function reconcileOrderShipping(orderId: string, actual: ActualShipmentCost): Promise<ReconcileShippingResult>;

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/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[];