@mohasinac/appkit 4.71.0 → 4.71.2

package/dist/_internal/shared/features/products/schema.d.ts

@@ -6,25 +6,43 @@ export declare const productInputSchema: z.ZodObject<{} & {
 }, {
     [x: string]: unknown;
 }>;
+/**
+ * 🛑 The UPDATE path needs the cap as badly as create does, and did not have it.
+ *
+ * `preOrderDeliveryDate` reaches this schema through `EXTRA_WRITABLE_FIELDS`,
+ * i.e. as `z.unknown().optional()` — so before this a seller could create a
+ * compliant 30-day pre-order and immediately PATCH it to 200 days through
+ * `updateProductAction`, and every bound on the create side was decoration.
+ * This is the create/update asymmetry of Root Cause #39: a rule applied to one
+ * door and not the other is not a rule.
+ *
+ * `.extend()` AFTER `.partial()`, so the field stays optional (a partial update
+ * that does not mention the date must not be refused for not mentioning it)
+ * while a supplied value is bounded.
+ */
 export declare const productUpdateSchema: z.ZodObject<{
     [x: string]: z.ZodOptional<z.ZodOptional<z.ZodUnknown>>;
+} & {
+    preOrderDeliveryDate: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string | Date, string | Date>>;
 }, "strip", z.ZodTypeAny, {
     [x: string]: unknown;
+    preOrderDeliveryDate?: unknown;
 }, {
     [x: string]: unknown;
+    preOrderDeliveryDate?: unknown;
 }>;
-export declare const auctionInputSchema: z.ZodObject<{
+export declare const collectorDropInputSchema: z.ZodObject<{
     [x: string]: z.ZodOptional<z.ZodUnknown>;
 } & {
-    listingType: z.ZodLiteral<"auction">;
+    listingType: z.ZodLiteral<"collector-drop">;
     startingBid: z.ZodNumber;
     reservePrice: z.ZodOptional<z.ZodNumber>;
     buyNowPrice: z.ZodOptional<z.ZodNumber>;
     minBidIncrement: z.ZodOptional<z.ZodNumber>;
-    auctionEndDate: z.ZodString;
+    collectorDropEndDate: z.ZodString;
     autoExtendable: z.ZodDefault<z.ZodBoolean>;
-    auctionExtensionMinutes: z.ZodOptional<z.ZodNumber>;
-    auctionShippingPaidBy: z.ZodOptional<z.ZodEnum<["seller", "winner"]>>;
+    collectorDropExtensionMinutes: z.ZodOptional<z.ZodNumber>;
+    collectorDropShippingPaidBy: z.ZodOptional<z.ZodEnum<["seller", "winner"]>>;
 }, "strip", z.ZodTypeAny, {
     [x: string]: unknown;
     listingType?: unknown;
@@ -32,10 +50,10 @@ export declare const auctionInputSchema: z.ZodObject<{
     reservePrice?: unknown;
     buyNowPrice?: unknown;
     minBidIncrement?: unknown;
-    auctionEndDate?: unknown;
+    collectorDropEndDate?: unknown;
     autoExtendable?: unknown;
-    auctionExtensionMinutes?: unknown;
-    auctionShippingPaidBy?: unknown;
+    collectorDropExtensionMinutes?: unknown;
+    collectorDropShippingPaidBy?: unknown;
 }, {
     [x: string]: unknown;
     listingType?: unknown;
@@ -43,16 +61,16 @@ export declare const auctionInputSchema: z.ZodObject<{
     reservePrice?: unknown;
     buyNowPrice?: unknown;
     minBidIncrement?: unknown;
-    auctionEndDate?: unknown;
+    collectorDropEndDate?: unknown;
     autoExtendable?: unknown;
-    auctionExtensionMinutes?: unknown;
-    auctionShippingPaidBy?: unknown;
+    collectorDropExtensionMinutes?: unknown;
+    collectorDropShippingPaidBy?: unknown;
 }>;
 export declare const preOrderInputSchema: z.ZodObject<{
     [x: string]: z.ZodOptional<z.ZodUnknown>;
 } & {
     listingType: z.ZodLiteral<"pre-order">;
-    preOrderDeliveryDate: z.ZodString;
+    preOrderDeliveryDate: z.ZodEffects<z.ZodString, string, string>;
     preOrderDepositPercent: z.ZodOptional<z.ZodNumber>;
     preOrderMaxQuantity: z.ZodOptional<z.ZodNumber>;
     preOrderProductionStatus: z.ZodDefault<z.ZodEnum<["upcoming", "in_production", "ready_to_ship"]>>;
@@ -96,5 +114,5 @@ export declare const setStatusSchema: z.ZodObject<{
 }>;
 export type ProductInput = z.infer<typeof productInputSchema>;
 export type ProductUpdate = z.infer<typeof productUpdateSchema>;
-export type AuctionInput = z.infer<typeof auctionInputSchema>;
+export type CollectorDropInput = z.infer<typeof collectorDropInputSchema>;
 export type PreOrderInput = z.infer<typeof preOrderInputSchema>;

package/dist/_internal/shared/features/products/schema.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { mediaUrlSchema } from "../../../../validation/schemas.js";
 import { PRODUCT_MAX_IMAGES } from "../../media/limits.js";
 import { PRODUCT_UPDATABLE_FIELDS } from "../../../../features/products/schemas/firestore.js";
+import { checkPreOrderDeliveryDate, preOrderDeliveryMessage, } from "../../../../features/products/constants/preorder-window.js";
 const priceSchema = z.number().min(0, "Price must be non-negative");
 const conditionSchema = z.enum(["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]);
 const productBaseShape = z.object({
@@ -60,32 +61,96 @@ const EXTRA_WRITABLE_FIELDS = [
     "video",
     "gstRate",
     "hsnCode",
-    // Auction terms. Writable while the listing is still a draft; once a real
+    // Collector Drop terms. Writable while the listing is still a draft; once a real
     // bid exists, `sellerUpdateProduct` refuses them — changing the starting bid
     // or the end date under a live bidder is the one case that must not pass.
     "startingBid",
-    "auctionEndDate",
+    "collectorDropEndDate",
 ];
 const declaredKeys = new Set(Object.keys(productBaseShape.shape));
 const extraWritableShape = Object.fromEntries(EXTRA_WRITABLE_FIELDS.filter((field) => !declaredKeys.has(field)).map((field) => [field, z.unknown().optional()]));
 export const productInputSchema = productBaseShape.extend(extraWritableShape);
-export const productUpdateSchema = productInputSchema.partial();
-export const auctionInputSchema = productInputSchema.extend({
-    // SB1-G — canonical discriminator. Locked to "auction" via literal.
-    listingType: z.literal("auction"),
+/**
+ * The 45-day pre-order delivery cap, as a field-level refinement.
+ *
+ * 🛑 FIELD level, not a whole-object `.refine()`. An object refinement carries
+ * no `path` unless one is supplied by hand, and a message with no path lands
+ * nowhere — `applyZodIssues` keys on the dotted path and `<FormErrorSummary>`
+ * offers a jump link from it, so an un-pathed issue is a save that fails with
+ * the field looking fine. Refining the field is what puts the message on the
+ * date input.
+ *
+ * Accepts `string | Date` because the two write paths disagree about the
+ * shape: a request body carries ISO text while `productToDraft`/an admin tool
+ * can hand back a real `Date`. The verdict function takes both, so neither
+ * caller needs a cast.
+ */
+const preOrderDeliveryDateRefinement = z
+    .union([z.string(), z.date()])
+    .superRefine((value, ctx) => {
+    const verdict = checkPreOrderDeliveryDate(value);
+    if (verdict === "ok" || verdict === "absent")
+        return;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: preOrderDeliveryMessage(verdict) ?? "Invalid delivery date",
+    });
+});
+/**
+ * 🛑 The UPDATE path needs the cap as badly as create does, and did not have it.
+ *
+ * `preOrderDeliveryDate` reaches this schema through `EXTRA_WRITABLE_FIELDS`,
+ * i.e. as `z.unknown().optional()` — so before this a seller could create a
+ * compliant 30-day pre-order and immediately PATCH it to 200 days through
+ * `updateProductAction`, and every bound on the create side was decoration.
+ * This is the create/update asymmetry of Root Cause #39: a rule applied to one
+ * door and not the other is not a rule.
+ *
+ * `.extend()` AFTER `.partial()`, so the field stays optional (a partial update
+ * that does not mention the date must not be refused for not mentioning it)
+ * while a supplied value is bounded.
+ */
+export const productUpdateSchema = productInputSchema.partial().extend({
+    preOrderDeliveryDate: preOrderDeliveryDateRefinement.optional(),
+});
+export const collectorDropInputSchema = productInputSchema.extend({
+    // SB1-G — canonical discriminator. Locked to "collector-drop" via literal.
+    listingType: z.literal("collector-drop"),
     startingBid: priceSchema,
     reservePrice: priceSchema.optional(),
     buyNowPrice: priceSchema.optional(),
     minBidIncrement: z.number().min(1).optional(),
-    auctionEndDate: z.string().datetime({ offset: true }),
+    collectorDropEndDate: z.string().datetime({ offset: true }),
     autoExtendable: z.boolean().default(false),
-    auctionExtensionMinutes: z.number().int().min(1).max(30).optional(),
-    auctionShippingPaidBy: z.enum(["seller", "winner"]).optional(),
+    collectorDropExtensionMinutes: z.number().int().min(1).max(30).optional(),
+    collectorDropShippingPaidBy: z.enum(["seller", "winner"]).optional(),
 });
 export const preOrderInputSchema = productInputSchema.extend({
     // SB1-G — canonical discriminator. Locked to "pre-order" via literal.
     listingType: z.literal("pre-order"),
-    preOrderDeliveryDate: z.string().datetime({ offset: true }),
+    /*
+     * 🛑 The ONE bound-check that covers the real create path
+     * (`createPreOrderAction`). It validated datetime FORMAT only until Phase 2,
+     * so a pre-order promising delivery in 200 days parsed cleanly — and Cashfree
+     * Easy Split cannot hold a settlement past 45 days, so that order's money had
+     * nowhere lawful to go. See `PREORDER_MAX_DELIVERY_DAYS`.
+     *
+     * The format check stays in front of the window check: `.datetime()` is what
+     * refuses `"tomorrow"` with a message about the format rather than about the
+     * window.
+     */
+    preOrderDeliveryDate: z
+        .string()
+        .datetime({ offset: true })
+        .superRefine((value, ctx) => {
+        const verdict = checkPreOrderDeliveryDate(value);
+        if (verdict === "ok")
+            return;
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: preOrderDeliveryMessage(verdict) ?? "Invalid delivery date",
+        });
+    }),
     preOrderDepositPercent: z.number().min(0).max(100).optional(),
     preOrderMaxQuantity: z.number().int().min(1).optional(),
     preOrderProductionStatus: z.enum(["upcoming", "in_production", "ready_to_ship"]).default("upcoming"),

package/dist/_internal/shared/features/products/to-product-item.js

@@ -51,7 +51,7 @@ export function toProductItem(doc) {
          *
          * `mainImage` FIRST, gallery as fallback — the seller chose `mainImage`
          * deliberately, and this matches the precedence every other card mapper
-         * uses (e.g. `StoreAuctionsListing`). `productImageUrls` is the one
+         * uses (e.g. `StoreCollectorDropsListing`). `productImageUrls` is the one
          * normaliser and it also accepts the legacy `string[]`.
          */
         mainImage: (typeof doc.mainImage === "string" ? doc.mainImage : undefined) ??

package/dist/_internal/shared/features/products/types.d.ts

@@ -23,7 +23,7 @@ export interface ProductDetailInitial {
     condition?: string;
     /** Canonical listing-kind discriminator (SB1-G — Phase 4 dropped legacy booleans). */
     listingType?: ListingType;
-    auctionEndDate?: string;
+    collectorDropEndDate?: string;
     startingBid?: number;
     currentBid?: number;
     bidCount?: number;

package/dist/_internal/shared/features/promotions/schema.d.ts

@@ -93,7 +93,7 @@ export declare const createCouponSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     scope: "seller" | "admin";
     discount: {
@@ -124,7 +124,7 @@ export declare const createCouponSchema: z.ZodObject<{
     } | undefined;
 }, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     scope: "seller" | "admin";
     discount: {
@@ -228,7 +228,7 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         applicableCategories?: string[] | undefined;
     }>>>;
 }, "code">, "strip", z.ZodTypeAny, {
-    type?: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y" | undefined;
+    type?: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y" | undefined;
     name?: string | undefined;
     scope?: "seller" | "admin" | undefined;
     discount?: {
@@ -258,7 +258,7 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         applicableCategories?: string[] | undefined;
     } | undefined;
 }, {
-    type?: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y" | undefined;
+    type?: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y" | undefined;
     name?: string | undefined;
     scope?: "seller" | "admin" | undefined;
     discount?: {

package/dist/_internal/shared/features/shipping/offer.d.ts

@@ -0,0 +1,408 @@
+/**
+ * THE SELLER'S SHIPPING OFFER, THE BUYER'S CHOICE, AND THE SERVER'S AUTHORITY.
+ *
+ * Pure and synchronous — no I/O, no Firestore, no provider. One module decides
+ * what a seller offers, what the buyer may pick, and what the buyer is charged,
+ * so the picker, the preview, the capture and the order record cannot disagree
+ * (Root Cause #75: a money rule reachable by copy-paste WILL be copied, and the
+ * copy never learns about the branch added later).
+ *
+ * ## Owner, 2026-11-08 — the spec this file implements, verbatim
+ *
+ * *"A seller agrees from their dashboard for the shipping option. If they
+ * select custom — i.e. their own — then they must set a per-order fee. But if
+ * they are okay with our shipping providers' quotes then they must accept that
+ * as well. Both can be enabled. When the buyer shops, at checkout they can
+ * select the custom shipping (say ₹200 set by the seller) or check the quote
+ * from the shipment integrations; if they find the other cheap they can choose
+ * whatever they wish. But if they have selected that, then it is up to the
+ * seller to fulfil as is — they cannot use the platform to ship for the other,
+ * as we have already taken money from the customer. If however they need to
+ * override it, they can refund the excess if any; and in case they needed to
+ * pay more for their custom shipping than what the buyer paid, they have to
+ * swallow that money as a loss."*
+ *
+ * ## 🛑 THE DEFECT THIS FILE EXISTS TO CLOSE
+ *
+ * Measured live 2026-11-08 on a ₹149 item at `checkout/actions.ts:1595`:
+ *
+ * ```
+ * shippingFee = roundShippingUp(selectedShippingQuote.chargedRate)
+ * ```
+ *
+ * honest request → charged total **₹172.69**
+ * forged `{ chargedRate: 1 }` → charged total **₹222.69**
+ *
+ * A number the CLIENT posted reached the charged total. The server's own
+ * `resolveShippingCost` result was computed and then discarded. The old comment
+ * argued the trust was "bounded" because `roundShippingUp` re-rounds it — but
+ * re-rounding a forged number only guarantees the forgery lands on a ₹50 step.
+ * ₹1 rounds to ₹50 and ₹10,000 rounds to ₹10,000; the bound is the attacker's
+ * choice, not ours. Undercutting was not exploitable only because no seeded
+ * store had `shippingPricing` configured, so every resolved fee was ₹0 — i.e.
+ * the protection was a data accident, due to expire the moment a vendor set a
+ * real rate.
+ *
+ * ## 🛑 Why the fix is NOT "forbid a client-supplied shipping value"
+ *
+ * This is the load-bearing architectural point, and the obvious fix is wrong.
+ *
+ * The buyer **legitimately chooses** between the seller's custom rate and a
+ * carrier quote — that is the owner's spec, not a loophole. So a client must be
+ * able to express *which* option it picked. What it must never be able to
+ * express is *what that option costs*.
+ *
+ * Therefore:
+ *
+ *   · a posted **amount** (`chargedRate`, `rawRate`) is ignored entirely;
+ *   · a posted **option identifier** is validated against the options this
+ *     seller actually offers, re-priced from stored config plus a
+ *     server-obtained carrier quote, and the SERVER's number is charged;
+ *   · an identifier that is not on that list is a **refusal**, never a silent
+ *     fallback. Falling back would charge the buyer for a method they did not
+ *     choose, which is the same class of defect pointing the other way.
+ *
+ * ## 🛑 Capability-driven, never type-driven
+ *
+ * Whether an order has shipping at all is `supportsShipping` on the capability
+ * registry, resolved by the caller through `cartRequiresShipping`. This module
+ * takes that answer as a boolean input and never looks at a listing type. A
+ * digital-code cart therefore acquires no fee and no obligation — not because
+ * this file knows what a digital code is, but because its caller said no line
+ * in the cart supports shipping.
+ */
+import { type ShippingQuoteOption } from "../../shipping/quote";
+import { type StoreShippingPolicy } from "./mode";
+/** Which side of the offer an option came from. */
+export type ShippingOptionKind = "platform" | "custom";
+/**
+ * What a seller will honour, as stored.
+ *
+ * Two INDEPENDENT axes, not one mode, and that is the whole difference from
+ * `StoreShippingPolicy`: the owner's spec says *"both can be enabled"*, and a
+ * single-valued mode cannot express that. `StoreShippingPolicy` survives
+ * underneath as the stored shape this is DERIVED from when a store has not yet
+ * saved an explicit offer (see `toSellerShippingOffer`) — one stored field, one
+ * reader, no second config system. `mode.ts`'s own header records what happened
+ * last time there were two.
+ */
+export interface SellerShippingOffer {
+    /**
+     * The seller accepts whatever our carrier integration quotes, and will book
+     * the label through the platform.
+     */
+    platformQuotesAccepted: boolean;
+    /** The seller ships themselves, at their own price. */
+    customEnabled: boolean;
+    /**
+     * REQUIRED when `customEnabled` — per ORDER, not per item.
+     *
+     * 🛑 Per order because the seller is quoting ONE parcel. A per-item custom
+     * fee is how a four-item order quietly becomes ₹800, and nothing about
+     * putting four beys in one box costs four times as much.
+     *
+     * 🛑 `null` is NOT zero. Zero is a seller deliberately offering free
+     * self-shipping, which is a real configuration; `null` is an unfinished form,
+     * and `validateSellerShippingOffer` refuses to save it rather than defaulting
+     * it to free. `mode.ts` already carries this exact lesson for `flat` with no
+     * amount.
+     */
+    customFeePerOrder: number | null;
+    /**
+     * Goods value at or above which the seller's own rate is free. `null` = no
+     * threshold.
+     *
+     * 🛑 Compared against the GOODS value, never a total that already contains
+     * shipping — otherwise the threshold depends on itself and a cart can cross
+     * ₹999 *because of* the shipping it is about to waive. Same rule, same
+     * reason, as `StoreShippingPolicy.freeAbove`.
+     */
+    customFreeAbove: number | null;
+    /** Shown beside the custom option so the buyer knows who is shipping. */
+    customLabel: string | null;
+}
+/**
+ * What a store that has configured nothing offers.
+ *
+ * 🛑 Custom at ₹0, NOT platform quotes — the conservative choice rather than
+ * the generous-looking one, and identical in effect to
+ * `DEFAULT_STORE_SHIPPING_POLICY`'s `free`. Defaulting to platform quotes would
+ * hold a buyer's money against a carrier booking the seller has never agreed
+ * to make, and the fulfilment obligation would bind a seller who never saw the
+ * setting. A store that has not opened its shipping page keeps doing exactly
+ * what it does today: charges nothing and ships manually.
+ */
+export declare const DEFAULT_SELLER_SHIPPING_OFFER: SellerShippingOffer;
+/** The stored offer, every field optional, every leaf a primitive. */
+export interface SellerShippingOfferWire {
+    platformQuotesAccepted?: boolean;
+    customEnabled?: boolean;
+    customFeePerOrder?: number | null;
+    customFreeAbove?: number | null;
+    customLabel?: string | null;
+}
+/**
+ * The offer implied by a legacy single-mode policy.
+ *
+ * 🛑 This is what stops this being a THIRD shipping-config system. Every store
+ * on the platform today has at most a `StoreShippingPolicy`, and the mapping is
+ * lossless in the direction that matters:
+ *
+ *   `free`             → custom at ₹0        (seller absorbs, ships manually)
+ *   `flat` amount A    → custom at ₹A        (the seller's own price)
+ *   `estimate`         → platform quotes     (our carrier account books it)
+ *
+ * So a seller who set ₹100 on the old surface keeps charging ₹100 and gains the
+ * obligation that already described what they were doing, rather than silently
+ * dropping to free or silently acquiring a carrier integration.
+ */
+export declare function offerFromPolicy(policy: StoreShippingPolicy): SellerShippingOffer;
+/**
+ * Narrow a stored `shippingPricing` value into the seller's offer.
+ *
+ * Reads the explicit `offer` when one has been saved, and derives it from the
+ * legacy mode otherwise. An offer that stores nothing usable — neither axis
+ * true — falls back to the derived policy rather than to "offers nothing",
+ * because "this store offers no shipping method" must come from a seller
+ * deliberately saying so (which `validateSellerShippingOffer` refuses anyway),
+ * never from a half-written document.
+ */
+export declare function toSellerShippingOffer(raw: unknown): SellerShippingOffer;
+/** Why a submitted offer cannot be saved. */
+export type ShippingOfferRefusal = 
+/** Neither axis enabled — the seller would offer no way to ship anything. */
+"no-method"
+/** `customEnabled` with no per-order fee. The owner's spec makes this invalid. */
+ | "custom-without-fee"
+/** A negative or non-finite fee. */
+ | "fee-not-a-price"
+/** A free-above threshold that is not a positive amount. */
+ | "threshold-not-a-price";
+export type ShippingOfferValidation = {
+    ok: true;
+    offer: SellerShippingOffer;
+} | {
+    ok: false;
+    reason: ShippingOfferRefusal;
+    message: string;
+};
+/**
+ * May this offer be saved?
+ *
+ * 🛑 REFUSES rather than defaulting, and that is the owner's spec read
+ * literally: *"if they select custom … then they MUST set a per-order fee"*.
+ * A missing fee defaulted to ₹0 is a seller who believes they are charging for
+ * postage and is not — they discover it when the payout arrives, by which time
+ * the parcels have been posted and the money cannot be recovered from the
+ * buyer. Refusing at save time costs one form error.
+ *
+ * 🛑 It also refuses an offer with NEITHER axis. A seller offering no shipping
+ * method cannot fulfil a physical order, and the honest place to say so is the
+ * settings form — not a buyer's checkout, where the only available answers are
+ * "charge nothing" (we ship free) or "block the purchase" (the seller loses the
+ * sale without being told why).
+ */
+export declare function validateSellerShippingOffer(input: SellerShippingOfferWire): ShippingOfferValidation;
+/** The id the buyer posts back for the seller's own rate. */
+export declare const CUSTOM_SHIPPING_OPTION_ID = "custom";
+/**
+ * The id for one carrier option.
+ *
+ * Namespaced so a carrier can never return the literal `"custom"` and collide
+ * with the seller's own option — which would let a tampered pick land on the
+ * wrong side of the fulfilment obligation.
+ */
+export declare function platformShippingOptionId(courierId: string): string;
+/** One option as offered at checkout. Every amount is server-computed. */
+export interface ShippingOptionOffer {
+    /** Stable id the buyer posts back. The ONLY field a client may influence. */
+    optionId: string;
+    kind: ShippingOptionKind;
+    label: string;
+    /** What the buyer is charged for choosing this. Decimal rupees. */
+    amount: number;
+    /** Why the amount is what it is — rendered as the sub-label. */
+    reason: "custom" | "custom-free-above" | "carrier";
+    estimatedDays?: number;
+    courierId?: string;
+    courierName?: string;
+}
+export interface BuildShippingOptionsInput {
+    offer: SellerShippingOffer;
+    /** GOODS value of this seller's lines — see `customFreeAbove`. */
+    goodsValue: number;
+    /**
+     * Carrier options already obtained SERVER-SIDE and already rounded by
+     * `toQuoteOptions`. Empty means we could not quote.
+     *
+     * 🛑 Passed in rather than fetched here so this module stays pure. The
+     * caller owns the outbound call; this owns the pricing.
+     */
+    carrierOptions?: readonly ShippingQuoteOption[];
+}
+/**
+ * Everything this seller is willing to ship by, priced.
+ *
+ * 🛑 The custom fee is NOT put through `roundShippingUp`, and the platform
+ * options already are. That asymmetry is deliberate and is the point of the
+ * ₹50 step: it exists to make a volatile machine-read CARRIER RATE look like a
+ * stable price. A seller's own ₹60 is already a price — a human typed it and
+ * published it — so rounding it to ₹100 would charge the buyer ₹40 the seller
+ * never asked for and show a figure that appears nowhere in the seller's
+ * settings. `toQuoteOptions` applies the step to carrier rates at the one place
+ * they enter the system; nothing else needs it.
+ *
+ * 🛑 A `customEnabled` offer with a `null` fee produces NO custom option rather
+ * than a free one. See `toSellerShippingOffer` — an unfinished configuration
+ * must fail visibly, not post parcels for free.
+ *
+ * Cheapest first, because the buyer is choosing and the owner's spec says
+ * explicitly that they may take whichever is cheaper.
+ */
+export declare function buildShippingOptions(input: BuildShippingOptionsInput): ShippingOptionOffer[];
+/**
+ * What the buyer committed to, frozen onto the order so the fulfilment
+ * obligation is evidenced rather than remembered.
+ *
+ * 🛑 This record is what makes part C of the spec enforceable at all. "The
+ * seller may not buy a platform label for an order the buyer paid custom
+ * shipping on" is a rule about a decision made at checkout and broken at pack
+ * time, possibly days later — a rule nobody can evidence after the fact is not
+ * a rule, it is an aspiration. `mustSelfFulfil` is the one field every
+ * downstream gate reads.
+ */
+export interface ShippingObligation {
+    /** Which side of the offer won. */
+    kind: ShippingOptionKind;
+    /** The option id charged, for the audit trail. */
+    optionId: string;
+    /** What the buyer actually paid for shipping. Decimal rupees. */
+    chargedAmount: number;
+    /** Seller-facing label of what was bought. */
+    label: string;
+    /**
+     * 🛑 TRUE when the buyer chose the seller's own shipping.
+     *
+     * The seller must post it themselves and may NOT book a platform label
+     * against this order, because the money was taken against the method the
+     * buyer named. If they override anyway: excess back to the buyer, shortfall
+     * absorbed by the seller. `reconcileShipping` already computes both
+     * directions from `chargedAmount` and the real spend — this flag is what says
+     * which of them the seller agreed to.
+     */
+    mustSelfFulfil: boolean;
+    courierId?: string;
+    courierName?: string;
+}
+export type ShippingSelectionOutcome = 
+/** Shipping resolved. `option` is the SERVER's pricing, not the client's. */
+{
+    kind: "resolved";
+    option: ShippingOptionOffer;
+    obligation: ShippingObligation;
+}
+/**
+ * No line in this order supports shipping. Zero fee, no obligation.
+ *
+ * 🛑 A distinct outcome rather than `resolved` at ₹0, so a caller cannot
+ * accidentally write a self-fulfilment obligation onto a digital-code order.
+ */
+ | {
+    kind: "not-required";
+}
+/**
+ * The buyer posted no option. The caller falls back to the seller's stored
+ * policy via `resolveShippingCost`.
+ *
+ * 🛑 Not a refusal, and not a hole: the fallback is a SERVER number resolved
+ * from stored seller config, so no client-supplied amount reaches the total
+ * on this branch either. It exists because a digital cart, a cart whose
+ * carrier quote failed, and every client written before the picker all omit
+ * the field — refusing them would convert a pricing bug into a checkout
+ * outage.
+ */
+ | {
+    kind: "unselected";
+}
+/**
+ * The posted option is not one this seller offers. REFUSE the order.
+ *
+ * 🛑 Never a silent fallback to the cheapest available. The buyer agreed to a
+ * named method at a named price; substituting another is the same wrong as
+ * trusting their number, pointed the other way.
+ */
+ | {
+    kind: "refused";
+    reason: "option-not-offered" | "no-method-available";
+    message: string;
+};
+export interface ResolveShippingSelectionInput {
+    /**
+     * Does any line in this order support shipping?
+     *
+     * 🛑 A CAPABILITY answer the caller resolves through `cartRequiresShipping`
+     * (which reads `supportsShipping` off the registry), never a listing-type
+     * comparison. This module must not know what a digital code is.
+     */
+    shippingRequired: boolean;
+    offer: SellerShippingOffer;
+    goodsValue: number;
+    carrierOptions?: readonly ShippingQuoteOption[];
+    /**
+     * The option id the client posted, if any.
+     *
+     * 🛑 An IDENTIFIER, never an amount. A client that also posts a `chargedRate`
+     * has it ignored — the caller is responsible for not passing one, and the
+     * type here is what makes that mechanical rather than disciplinary.
+     */
+    requestedOptionId?: string;
+}
+/**
+ * Re-resolve the buyer's chosen OPTION against the seller's stored offer and a
+ * server-obtained carrier quote, and return the SERVER's price for it.
+ *
+ * This is the single function that answers "what is this order charged for
+ * shipping, and what did the seller therefore agree to do".
+ */
+export declare function resolveShippingSelection(input: ResolveShippingSelectionInput): ShippingSelectionOutcome;
+/**
+ * The obligation an offer implies when the buyer made NO choice.
+ *
+ * ## 🛑 Why this exists, and why it only answers sometimes
+ *
+ * The gateway (online-payment) checkout prices shipping from the seller's
+ * stored policy and does not yet carry the buyer's per-store option — see the
+ * gap recorded at `createPhonePeGroupOrder`. Without this, every online order
+ * would carry NO `shippingObligation`, and `mayBookPlatformLabel` fails open on
+ * absence — so a seller who ships their own parcels could book a platform label
+ * against an order the buyer paid their custom rate for, which is the exact
+ * thing part C of the spec forbids.
+ *
+ * 🛑 It returns `null` whenever the offer leaves a genuine CHOICE (both axes
+ * enabled), because then the buyer's pick is the only thing that can decide and
+ * inventing one would record a contract nobody agreed to. It answers only when
+ * the seller offers exactly one method, where the method is a fact about the
+ * seller rather than a guess about the buyer.
+ *
+ * 🛑 It also returns `null` when nothing was charged. An obligation with no
+ * payment behind it would bind a seller to a price nobody paid.
+ */
+export declare function impliedObligation(offer: SellerShippingOffer, chargedAmount: number, shippingRequired: boolean): ShippingObligation | null;
+/**
+ * May the seller book a PLATFORM label against this order?
+ *
+ * 🛑 The enforcement point for part C, and it reads the frozen obligation
+ * rather than re-deriving anything. Gated on what the buyer CHOSE, exactly as
+ * `isReimbursableShipment` is gated on who BOOKED — a fact about the
+ * transaction, never something the claimant supplies at claim time.
+ *
+ * Absence returns TRUE, i.e. fails open, and that is a prerequisite rather than
+ * a bug: no order written before this field existed carries it, and a
+ * fail-closed gate would refuse every seller on every historical order. The day
+ * the Shiprocket booking path is wired, THE SAME COMMIT must call this — see
+ * `isReimbursableShipment`'s note for the identical hazard on the identical
+ * shape.
+ */
+export declare function mayBookPlatformLabel(order: {
+    shippingObligation?: Pick<ShippingObligation, "mustSelfFulfil">;
+}): boolean;