@mohasinac/appkit 4.44.0 → 4.45.0

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

@@ -0,0 +1,112 @@
+/**
+ * How a store prices shipping — C5b.
+ *
+ * ## What this replaces
+ *
+ * `resolveShippingCost(storeId)` returned ONE flat rupee number per store:
+ * `shippingConfig.customShippingPrice ?? 0`, read off the store OWNER's user
+ * document, with no weight, destination, pincode or courier anywhere in it.
+ *
+ * ## 🛑 And there was a second, richer config that no money path read
+ *
+ * `ShippingConfigDocument` (collection `shippingConfigs`) has `method`
+ * (free/flat/weight/express/pickup/custom), `flatRate`, `pricePerKg`,
+ * `freeAbove`, `expressSurcharge`, `estimatedDays` and `zones` — with full
+ * CRUD routes, a form schema and seed data. **`shippingConfigsRepository` is
+ * called from no money path at all.** So there were two shipping-config
+ * systems and the authoritative one was the flat number, by accident.
+ *
+ * This is the one mode, and it is deliberately narrower than that document:
+ *
+ *   `free`      the seller absorbs it. Implies they ship manually.
+ *   `flat`      a fixed amount the seller sets.
+ *   `estimate`  a live address-to-address carrier rate, which the buyer pays
+ *               and we HOLD — the escrow flow.
+ *
+ * Zones and per-kg tables are dropped: once a real carrier quotes the rate, a
+ * hand-maintained zone table earns nothing and is one more thing to drift.
+ *
+ * `freeAbove` SURVIVES as an override on every mode, because "free shipping
+ * over ₹999" is a merchandising lever no carrier can give you and every
+ * competitor in the crawl uses some form of it.
+ */
+/** Amounts are decimal rupees throughout, matching every other money field. */
+export type StoreShippingMode = {
+    kind: "free";
+} | {
+    kind: "flat";
+    amount: number;
+} | {
+    kind: "estimate";
+};
+export interface StoreShippingPolicy {
+    mode: StoreShippingMode;
+    /**
+     * Order goods value at or above which shipping is free, whatever the mode.
+     *
+     * 🛑 Compared against the GOODS value, not the grand total. Comparing a
+     * free-shipping threshold against a total that already includes shipping,
+     * GST and the platform fee makes the threshold depend on itself — a cart can
+     * cross ₹999 *because of* the shipping it is about to waive.
+     */
+    freeAbove?: number;
+}
+/**
+ * The default for a store that has configured nothing.
+ *
+ * 🛑 `free`, not `estimate`, and that is the conservative choice rather than
+ * the generous-looking one. `estimate` means we quote a live carrier rate and
+ * hold the buyer's money against a booking the seller may not be set up to
+ * make; a store that has never opened its shipping settings has not agreed to
+ * that. `free` charges the buyer nothing and leaves the seller shipping
+ * manually, which is what an unconfigured store was doing anyway — the old
+ * code's `?? 0` had exactly this effect, so this preserves behaviour for every
+ * existing store rather than silently switching them into escrow.
+ */
+export declare const DEFAULT_STORE_SHIPPING_POLICY: StoreShippingPolicy;
+/** Narrow an arbitrary stored value, falling back to the safe default. */
+export declare function toStoreShippingPolicy(raw: unknown): StoreShippingPolicy;
+export interface ShippingQuoteInput {
+    policy: StoreShippingPolicy;
+    /** GOODS value of this store's lines — see `freeAbove`. */
+    goodsValue: number;
+    /**
+     * The live carrier rate, when one was obtained.
+     *
+     * `null` means we could not get one — which is NOT the same as zero and is
+     * why this is nullable. See `quoteShipping`'s `needsCarrierRate`.
+     */
+    carrierRate?: number | null;
+}
+export type ShippingQuote = {
+    kind: "charge";
+    amount: number;
+    reason: "flat" | "estimate";
+} | {
+    kind: "free";
+    reason: "mode" | "freeAbove";
+}
+/**
+ * 🛑 The third outcome, and the reason this returns a union rather than a
+ * number. An `estimate`-mode store whose carrier rate could not be obtained
+ * has NO quote — and a `0` there would ship the parcel for free at our
+ * expense, silently, on every order until someone noticed. The caller must
+ * decide: block the purchase, or fall back. It cannot accidentally charge
+ * nothing.
+ */
+ | {
+    kind: "unavailable";
+    reason: "no-carrier-rate";
+};
+/**
+ * What this store's lines cost to ship.
+ *
+ * Order of resolution matters: `freeAbove` is checked FIRST, because a cart
+ * over the threshold is free regardless of mode and there is no point
+ * obtaining a carrier rate we are about to waive. That also means an
+ * `estimate`-mode store with a `freeAbove` does not fail on an unavailable
+ * carrier rate for a qualifying cart.
+ */
+export declare function quoteShipping(input: ShippingQuoteInput): ShippingQuote;
+/** Whether this quote needs a carrier call at all — saves a round trip. */
+export declare function needsCarrierRate(policy: StoreShippingPolicy, goodsValue: number): boolean;

package/dist/_internal/shared/features/shipping/mode.js

@@ -0,0 +1,108 @@
+/**
+ * How a store prices shipping — C5b.
+ *
+ * ## What this replaces
+ *
+ * `resolveShippingCost(storeId)` returned ONE flat rupee number per store:
+ * `shippingConfig.customShippingPrice ?? 0`, read off the store OWNER's user
+ * document, with no weight, destination, pincode or courier anywhere in it.
+ *
+ * ## 🛑 And there was a second, richer config that no money path read
+ *
+ * `ShippingConfigDocument` (collection `shippingConfigs`) has `method`
+ * (free/flat/weight/express/pickup/custom), `flatRate`, `pricePerKg`,
+ * `freeAbove`, `expressSurcharge`, `estimatedDays` and `zones` — with full
+ * CRUD routes, a form schema and seed data. **`shippingConfigsRepository` is
+ * called from no money path at all.** So there were two shipping-config
+ * systems and the authoritative one was the flat number, by accident.
+ *
+ * This is the one mode, and it is deliberately narrower than that document:
+ *
+ *   `free`      the seller absorbs it. Implies they ship manually.
+ *   `flat`      a fixed amount the seller sets.
+ *   `estimate`  a live address-to-address carrier rate, which the buyer pays
+ *               and we HOLD — the escrow flow.
+ *
+ * Zones and per-kg tables are dropped: once a real carrier quotes the rate, a
+ * hand-maintained zone table earns nothing and is one more thing to drift.
+ *
+ * `freeAbove` SURVIVES as an override on every mode, because "free shipping
+ * over ₹999" is a merchandising lever no carrier can give you and every
+ * competitor in the crawl uses some form of it.
+ */
+/**
+ * The default for a store that has configured nothing.
+ *
+ * 🛑 `free`, not `estimate`, and that is the conservative choice rather than
+ * the generous-looking one. `estimate` means we quote a live carrier rate and
+ * hold the buyer's money against a booking the seller may not be set up to
+ * make; a store that has never opened its shipping settings has not agreed to
+ * that. `free` charges the buyer nothing and leaves the seller shipping
+ * manually, which is what an unconfigured store was doing anyway — the old
+ * code's `?? 0` had exactly this effect, so this preserves behaviour for every
+ * existing store rather than silently switching them into escrow.
+ */
+export const DEFAULT_STORE_SHIPPING_POLICY = {
+    mode: { kind: "free" },
+};
+/** Narrow an arbitrary stored value, falling back to the safe default. */
+export function toStoreShippingPolicy(raw) {
+    if (!raw || typeof raw !== "object")
+        return DEFAULT_STORE_SHIPPING_POLICY;
+    const r = raw;
+    const freeAbove = typeof r.freeAbove === "number" && r.freeAbove > 0 ? { freeAbove: r.freeAbove } : {};
+    const kind = r.mode?.kind;
+    if (kind === "estimate")
+        return { mode: { kind: "estimate" }, ...freeAbove };
+    if (kind === "flat") {
+        const amount = Number(r.mode?.amount ?? 0);
+        /*
+         * A `flat` mode with no amount is not a flat rate, it is an unfinished
+         * form. Treating it as ₹0 would silently make it `free` and hide the
+         * misconfiguration; falling back to the default does the same thing
+         * VISIBLY, because the seller's settings page will show `free` selected
+         * and they can see it is not what they chose.
+         */
+        if (!(amount > 0))
+            return { ...DEFAULT_STORE_SHIPPING_POLICY, ...freeAbove };
+        return { mode: { kind: "flat", amount }, ...freeAbove };
+    }
+    return { ...DEFAULT_STORE_SHIPPING_POLICY, ...freeAbove };
+}
+/**
+ * What this store's lines cost to ship.
+ *
+ * Order of resolution matters: `freeAbove` is checked FIRST, because a cart
+ * over the threshold is free regardless of mode and there is no point
+ * obtaining a carrier rate we are about to waive. That also means an
+ * `estimate`-mode store with a `freeAbove` does not fail on an unavailable
+ * carrier rate for a qualifying cart.
+ */
+export function quoteShipping(input) {
+    const { policy, goodsValue, carrierRate } = input;
+    if (policy.freeAbove != null && goodsValue >= policy.freeAbove) {
+        return { kind: "free", reason: "freeAbove" };
+    }
+    switch (policy.mode.kind) {
+        case "free":
+            return { kind: "free", reason: "mode" };
+        case "flat":
+            return { kind: "charge", amount: policy.mode.amount, reason: "flat" };
+        case "estimate":
+            if (typeof carrierRate !== "number" || !(carrierRate >= 0)) {
+                return { kind: "unavailable", reason: "no-carrier-rate" };
+            }
+            return { kind: "charge", amount: carrierRate, reason: "estimate" };
+        default: {
+            // Exhaustive: a fourth mode must not compile to a silent free shipment.
+            const unreachable = policy.mode;
+            return unreachable;
+        }
+    }
+}
+/** Whether this quote needs a carrier call at all — saves a round trip. */
+export function needsCarrierRate(policy, goodsValue) {
+    if (policy.freeAbove != null && goodsValue >= policy.freeAbove)
+        return false;
+    return policy.mode.kind === "estimate";
+}

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

@@ -0,0 +1,115 @@
+/**
+ * The parcel a shipment is quoted and booked on — C5a.
+ *
+ * ## 🛑 Three tiers, and the distinction between them is the whole point
+ *
+ *   CATEGORY   `CategoryProductDefaults.weightG` / `dimensionsCm` — a PACKED
+ *              figure, seeded per leaf. Drives the checkout ESTIMATE.
+ *   PRODUCT    `ProductDocument.weightG` / `dimensionsCm` — OPTIONAL. Refines
+ *              the estimate when a seller has actually weighed a packed box.
+ *   SHIPMENT   entered by the seller at booking time. **What is booked.**
+ *
+ * The figure a carrier bills on is the packed parcel, not the item: a bey is
+ * ~30 g and ~300 g boxed. A required product weight would therefore be an item
+ * weight that systematically under-estimates every booking — and since the
+ * booking is capped at the amount collected from the buyer, systematic
+ * under-estimation means silently absorbing the difference on every order.
+ *
+ * So the seller enters the real number when they have the box in front of
+ * them, and the category default exists only to quote with before that exists.
+ *
+ * ## 🛑 And the estimate must never silently become zero
+ *
+ * A missing weight cannot resolve to `0` — a carrier rate for a 0 g parcel is
+ * either an error or the cheapest band, and the cheapest band is the one that
+ * loses money. `resolveParcel` returns `null` when nothing is known, and every
+ * caller has to decide what to do about it rather than being handed a number
+ * that looks usable.
+ *
+ * Pure. No Firestore, no React.
+ */
+/** A dimension triple, all three or nothing — see `normaliseDimensions`. */
+export interface ParcelDimensionsCm {
+    l: number;
+    w: number;
+    h: number;
+}
+export interface Parcel {
+    weightG: number;
+    dimensionsCm?: ParcelDimensionsCm;
+    /**
+     * Which tier supplied the weight, so a surface can say so.
+     *
+     * Carried because "₹140 estimated" and "₹140 estimated from the category's
+     * typical packed weight, because this listing has none" are different claims,
+     * and the second is the honest one most of the time.
+     */
+    source: "shipment" | "product" | "category";
+}
+/** What a product or category can offer. Structural, so either shape fits. */
+export interface ParcelSource {
+    weightG?: number | null;
+    dimensionsCm?: {
+        l?: number | null;
+        w?: number | null;
+        h?: number | null;
+    } | null;
+}
+/**
+ * All three dimensions or none.
+ *
+ * A box with a length and no width is not a dimension — a carrier's volumetric
+ * calculation needs the triple, and feeding it two of three yields either an
+ * error or a quote for a flat sheet. The product form and the admin editor
+ * both enforce this at input; this is the read-side twin so a document written
+ * before they did cannot leak a partial triple into a rate request.
+ */
+export declare function normaliseDimensions(d: ParcelSource["dimensionsCm"]): ParcelDimensionsCm | undefined;
+/**
+ * Resolve the parcel to quote on, most specific tier first.
+ *
+ * 🛑 Returns `null` rather than a zero-weight parcel when no tier supplies a
+ * weight. A caller must then either refuse to quote or fall back to a
+ * non-carrier shipping mode — both of which are visible decisions, where a
+ * `0` would have been an invisible one.
+ *
+ * Dimensions are resolved INDEPENDENTLY of the weight, because the two are
+ * declared independently: a seller who typed a weight and no box size should
+ * still get the category's box size rather than none. Taking both from
+ * whichever tier won on weight would discard information that exists.
+ */
+export declare function resolveParcel(shipment: ParcelSource | null | undefined, product: ParcelSource | null | undefined, category: ParcelSource | null | undefined): Parcel | null;
+/**
+ * The weight of a whole order group — what a single shipment actually carries.
+ *
+ * Summed across lines and multiplied by live quantity, because a carrier
+ * quotes one parcel per shipment and two beys in one box weigh more than one.
+ *
+ * 🛑 Returns `null` if ANY line has no resolvable weight, rather than summing
+ * the ones it knows. A partial sum is a confident under-estimate, which is the
+ * exact failure this module exists to prevent — and it is worse than no
+ * estimate, because no estimate is visible.
+ */
+export declare function resolveGroupWeightG(lines: ReadonlyArray<{
+    quantity: number;
+    parcel: Parcel | null;
+}>): number | null;
+/**
+ * Actual against estimated, recorded and NEVER blended.
+ *
+ * Same discipline as the price index's market-vs-sold pair, for the same
+ * reason: the estimate is what we charged the buyer and the actual is what the
+ * carrier billed, and **the gap is the thing worth watching**. A leaf whose
+ * actuals run consistently over its default is telling us the default is
+ * wrong, which is a report for a human — not an automatic correction, because
+ * a default that chases its own actuals has no anchor.
+ */
+export interface ParcelWeightVariance {
+    estimatedG: number;
+    actualG: number;
+    /** Positive means the real parcel was HEAVIER than quoted. */
+    deltaG: number;
+    /** Signed fraction of the estimate, rounded to 3dp. `null` if estimate is 0. */
+    deltaRatio: number | null;
+}
+export declare function parcelWeightVariance(estimatedG: number, actualG: number): ParcelWeightVariance;

package/dist/_internal/shared/features/shipping/parcel.js

@@ -0,0 +1,120 @@
+/**
+ * The parcel a shipment is quoted and booked on — C5a.
+ *
+ * ## 🛑 Three tiers, and the distinction between them is the whole point
+ *
+ *   CATEGORY   `CategoryProductDefaults.weightG` / `dimensionsCm` — a PACKED
+ *              figure, seeded per leaf. Drives the checkout ESTIMATE.
+ *   PRODUCT    `ProductDocument.weightG` / `dimensionsCm` — OPTIONAL. Refines
+ *              the estimate when a seller has actually weighed a packed box.
+ *   SHIPMENT   entered by the seller at booking time. **What is booked.**
+ *
+ * The figure a carrier bills on is the packed parcel, not the item: a bey is
+ * ~30 g and ~300 g boxed. A required product weight would therefore be an item
+ * weight that systematically under-estimates every booking — and since the
+ * booking is capped at the amount collected from the buyer, systematic
+ * under-estimation means silently absorbing the difference on every order.
+ *
+ * So the seller enters the real number when they have the box in front of
+ * them, and the category default exists only to quote with before that exists.
+ *
+ * ## 🛑 And the estimate must never silently become zero
+ *
+ * A missing weight cannot resolve to `0` — a carrier rate for a 0 g parcel is
+ * either an error or the cheapest band, and the cheapest band is the one that
+ * loses money. `resolveParcel` returns `null` when nothing is known, and every
+ * caller has to decide what to do about it rather than being handed a number
+ * that looks usable.
+ *
+ * Pure. No Firestore, no React.
+ */
+/**
+ * All three dimensions or none.
+ *
+ * A box with a length and no width is not a dimension — a carrier's volumetric
+ * calculation needs the triple, and feeding it two of three yields either an
+ * error or a quote for a flat sheet. The product form and the admin editor
+ * both enforce this at input; this is the read-side twin so a document written
+ * before they did cannot leak a partial triple into a rate request.
+ */
+export function normaliseDimensions(d) {
+    if (!d)
+        return undefined;
+    const l = Number(d.l ?? 0);
+    const w = Number(d.w ?? 0);
+    const h = Number(d.h ?? 0);
+    if (!(l > 0 && w > 0 && h > 0))
+        return undefined;
+    return { l, w, h };
+}
+/**
+ * Resolve the parcel to quote on, most specific tier first.
+ *
+ * 🛑 Returns `null` rather than a zero-weight parcel when no tier supplies a
+ * weight. A caller must then either refuse to quote or fall back to a
+ * non-carrier shipping mode — both of which are visible decisions, where a
+ * `0` would have been an invisible one.
+ *
+ * Dimensions are resolved INDEPENDENTLY of the weight, because the two are
+ * declared independently: a seller who typed a weight and no box size should
+ * still get the category's box size rather than none. Taking both from
+ * whichever tier won on weight would discard information that exists.
+ */
+export function resolveParcel(shipment, product, category) {
+    const tiers = [
+        ["shipment", shipment],
+        ["product", product],
+        ["category", category],
+    ];
+    let weightG = null;
+    let source = null;
+    for (const [name, t] of tiers) {
+        const w = t?.weightG;
+        if (typeof w === "number" && w > 0) {
+            weightG = w;
+            source = name;
+            break;
+        }
+    }
+    if (weightG == null || source == null)
+        return null;
+    let dimensionsCm;
+    for (const [, t] of tiers) {
+        const d = normaliseDimensions(t?.dimensionsCm);
+        if (d) {
+            dimensionsCm = d;
+            break;
+        }
+    }
+    return { weightG, source, ...(dimensionsCm ? { dimensionsCm } : {}) };
+}
+/**
+ * The weight of a whole order group — what a single shipment actually carries.
+ *
+ * Summed across lines and multiplied by live quantity, because a carrier
+ * quotes one parcel per shipment and two beys in one box weigh more than one.
+ *
+ * 🛑 Returns `null` if ANY line has no resolvable weight, rather than summing
+ * the ones it knows. A partial sum is a confident under-estimate, which is the
+ * exact failure this module exists to prevent — and it is worse than no
+ * estimate, because no estimate is visible.
+ */
+export function resolveGroupWeightG(lines) {
+    let total = 0;
+    for (const line of lines) {
+        if (!line.parcel)
+            return null;
+        const qty = Math.max(1, line.quantity);
+        total += line.parcel.weightG * qty;
+    }
+    return total > 0 ? total : null;
+}
+export function parcelWeightVariance(estimatedG, actualG) {
+    const deltaG = Math.round((actualG - estimatedG) * 1000) / 1000;
+    return {
+        estimatedG,
+        actualG,
+        deltaG,
+        deltaRatio: estimatedG > 0 ? Math.round((deltaG / estimatedG) * 1000) / 1000 : null,
+    };
+}

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

@@ -0,0 +1,221 @@
+/**
+ * The two buyer protections — C5e.
+ *
+ * ## 🛑 What was wrong, and why the fix is a claim path rather than a deletion
+ *
+ * `computeShipmentProtectionFee` is real: `max(₹30, 2%)`, opt-in per store,
+ * written to the order as `shipmentProtectionAddon` / `shipmentProtectionFee`,
+ * rendered as a "Protected" chip. And `OrderAddonBadges.tsx` claims the flag
+ * *"changes how a loss claim is handled"* — while **no refund, dispute or RMA
+ * code reads it anywhere**. A buyer paid 2% for a promise the system could not
+ * keep.
+ *
+ * An earlier revision of the plan concluded "delete it". That was wrong. The
+ * diagnosis was right — the fee was real and the claim path did not exist —
+ * but the missing half is the claim, and **escrow is the pot it pays from**.
+ * Holding the buyer's funds until delivery is what turns the badge from a
+ * promise into a mechanism.
+ *
+ * ## TWO protections, because they fail independently
+ *
+ *   SHIPPING  loss or damage IN TRANSIT. We are the carrier's counterparty
+ *             under escrow, so the carrier claim is ours to pursue and the
+ *             buyer never argues with a courier.
+ *   SALE      the item itself — not as described, wrong item, item issues.
+ *             Branches the return flow, skipping the seller-fault
+ *             determination.
+ *
+ * A parcel that arrives intact containing the wrong bey is a SALE problem, not
+ * a shipping one. A single blended "protection" would charge once and have to
+ * answer both — and, worse, would have to be wholly offered or wholly withheld
+ * on a final-sale item, where the right answers differ (see below).
+ */
+/** Which protection. Deliberately not a boolean pair in the signatures. */
+export type ProtectionKind = "shipping" | "sale";
+export declare const PROTECTION_KINDS: readonly ProtectionKind[];
+/** Why a protection is not on offer. Rendered to the buyer, so it is copy. */
+export type ProtectionUnavailableReason = "platform-disabled" | "seller-not-supported" | "final-sale";
+export type ProtectionAvailability = {
+    available: true;
+} | {
+    available: false;
+    reason: ProtectionUnavailableReason;
+};
+export interface ProtectionTierInput {
+    /** TIER 1 — admin, platform-wide. `commissions.*FeeEnabled`. Default TRUE. */
+    platformEnabled: boolean;
+    /**
+     * TIER 2 — the seller, for their own orders. Default FALSE.
+     *
+     * 🛑 The two defaults are opposite ON PURPOSE and it is not an
+     * inconsistency. The admin flag answers "do we offer this product at all" —
+     * we built it, so `true`. The seller flag answers "has this seller agreed to
+     * be held to it" — they have not been asked, so `false`. Defaulting the
+     * seller flag to `true` would enrol every existing seller in a liability
+     * they never accepted, which is a worse failure than a day-one page full of
+     * risk notices.
+     */
+    sellerSupports: boolean;
+    /**
+     * TIER 3 — the item. `finalSale` from the ORDER ITEM's snapshot at claim
+     * time, or the product at purchase time.
+     */
+    finalSale: boolean;
+}
+/**
+ * Is this protection on offer, and if not, why.
+ *
+ * 🛑 `finalSale` is checked for SALE protection only, and the asymmetry is the
+ * strongest argument for keeping the two separate:
+ *
+ *   final sale + sale protection      INELIGIBLE. "No returns" and
+ *                                     "no-questions-asked refund" are a plain
+ *                                     contradiction, and `finalSale` exists
+ *                                     precisely so a seller cannot be made to
+ *                                     take an item back.
+ *   final sale + shipping protection  UNAFFECTED. A parcel lost in transit was
+ *                                     never delivered, so there is nothing for
+ *                                     "final" to be final about — the buyer
+ *                                     did not receive the item they accepted
+ *                                     as non-returnable.
+ *
+ * Order of checks is the order of ownership: platform, then seller, then item.
+ * That matters because the REASON is rendered, and "we do not offer this" is a
+ * different sentence from "this seller does not offer this".
+ */
+export declare function protectionAvailability(kind: ProtectionKind, input: ProtectionTierInput): ProtectionAvailability;
+/**
+ * Whether to show the buyer a pre-purchase RISK NOTICE.
+ *
+ * 🛑 Absence must read as "not supported", never as "unknown". A tri-state
+ * where `undefined` renders neither a badge nor a notice is the worst of the
+ * three outcomes: the buyer gets no signal at all and cannot tell a seller who
+ * declined from one who has not been asked.
+ *
+ * `platform-disabled` is the one reason that shows NOTHING — if we do not
+ * offer the product, there is nothing to disclose about this seller, and a
+ * notice would be us advertising a gap we created.
+ */
+export declare function showsRiskNotice(a: ProtectionAvailability): boolean;
+/**
+ * Whether to show the seller's safety BADGE.
+ *
+ * 🛑 Gated on the claim path existing, not merely on the flag. A badge for a
+ * promise the platform cannot keep is the dead `OrderAddonBadges` tooltip one
+ * level up — a seller opting into something we do not honour.
+ */
+export declare function showsSafetyBadge(a: ProtectionAvailability): boolean;
+/**
+ * 🛑 The two badges must never appear together on one card.
+ *
+ * "Final sale" beside "Sale protected" is incoherent to a buyer and they are
+ * right. A final-sale listing shows the final-sale badge and, when the seller
+ * supports it, the SHIPPING-protection badge only.
+ */
+export declare function badgesFor(input: ProtectionTierInput): {
+    finalSale: boolean;
+    shippingProtected: boolean;
+    saleProtected: boolean;
+};
+/**
+ * Both protection fees for one order group, with all three tiers applied.
+ *
+ * 🛑 This exists because there are THREE money sites that must agree — the
+ * pricing preview (what the buyer is shown), `createOrderForGroup` (what the
+ * order records) and `POST /api/payment/create-order` (what the gateway
+ * captures) — and a fee charged at one and refused at another is an overcharge
+ * with no record. Root Cause #75's shape: a rule reachable by copy-paste will
+ * be copied, and the copy made before a branch was added never learns about
+ * it. Exporting the whole computed pair rather than the predicate is what
+ * stops a caller re-deriving the `&&`.
+ *
+ * 🛑 The caller still supplies `finalSale` from the right source for its own
+ * moment: the live product at PREVIEW (no order exists yet), the order item's
+ * snapshot at CREATION and at CLAIM. That is deliberately not hidden in here —
+ * which source is correct depends on when you are asking, and a helper that
+ * guessed would get the claim-time case wrong, which is the one that matters.
+ */
+export declare function computeProtectionFees(input: {
+    /** Order-group goods value the percentage applies to. */
+    subtotal: number;
+    selected: {
+        shipping: boolean;
+        sale: boolean;
+    };
+    tiers: {
+        platformShipping: boolean;
+        platformSale: boolean;
+        sellerShipping: boolean;
+        sellerSale: boolean;
+        finalSale: boolean;
+    };
+    /** `(subtotal, selected, rates)` — pass the matching `compute*Fee`. */
+    shippingFee: (subtotal: number, selected: boolean) => number;
+    saleFee: (subtotal: number, selected: boolean) => number;
+}): {
+    shippingProtectionFee: number;
+    saleProtectionFee: number;
+};
+export type ClaimFinding = "genuine" | "change-of-mind";
+export interface ClaimOutcome {
+    /** Is the buyer refunded? */
+    refundBuyer: boolean;
+    /** Who absorbs the cost. */
+    costBorneBy: "seller" | "platform" | "buyer";
+    /** Whether a scam-registry signal should be raised for review. */
+    raisesReport: boolean;
+}
+/**
+ * 🛑 INSPECTION DECIDES WHO PAYS — NEVER WHETHER A PROTECTED BUYER IS
+ * REFUNDED.
+ *
+ * This is the part that must not be got wrong, because it is where the promise
+ * lives. Sale protection says *no questions asked*. If inspection could block
+ * a protected refund then "no questions asked" is false, and we would be
+ * rebuilding the dead-tooltip problem with extra steps.
+ *
+ *   protected + genuine          refunded · charged back to the SELLER
+ *   protected + change-of-mind   refunded · absorbed by the PLATFORM —
+ *                                this is what the fee prices
+ *   unprotected + genuine        refunded · the SELLER's fault, seller pays
+ *   unprotected + change-of-mind per the return policy — the BUYER pays
+ *
+ * What inspection gates is the chargeback, and that is also what makes the
+ * seller-level opt-in meaningful: a seller supporting the cover accepts that
+ * genuine claims land on them, and the fee covers the rest.
+ *
+ * `raisesReport` is a SIGNAL, not a verdict. A threshold opens a
+ * `ReportDocument` for a human; an automatic exclusion on a count would punish
+ * an unlucky buyer who received two genuinely bad items, and the scam
+ * registry's entries are written as patterns to recognise rather than rules to
+ * fire.
+ */
+export declare function adjudicateClaim(protectedSale: boolean, finding: ClaimFinding): ClaimOutcome;
+/**
+ * Where a RETURN ships to — C5g, stated here because it branches on the
+ * add-on and nothing else should re-derive that.
+ *
+ * 🛑 Warehouse routing applies ONLY to a sale-protection claim, not to returns
+ * in general. We take custody only where we are the ones underwriting the
+ * refund, which is also the only case where we need to know whether to charge
+ * the seller back. An ordinary return on an unprotected order stays between
+ * the buyer and the seller exactly as it does today.
+ *
+ * The admin trust flag sends even a protected claim to the seller.
+ */
+export declare function returnDestination(input: {
+    saleProtectedClaim: boolean;
+    /** `StoreDocument.returnsDirectToSeller` — ADMIN-granted, never seller-set. */
+    sellerTrustedByAdmin: boolean;
+}): "warehouse" | "seller";
+/**
+ * Where an RTO lands — C5h. Same rule, different trigger.
+ *
+ * An RTO is not buyer-initiated: the carrier is sending a parcel back because
+ * it could not be delivered. Nobody asked for it, so no claim exists — but the
+ * destination still follows who underwrote the order, because that is who has
+ * to inspect and account for it.
+ */
+export declare function rtoDestination(input: {
+    saleProtectedOrder: boolean;
+}): "warehouse" | "seller";