@mohasinac/appkit 4.43.0 → 4.45.0

package/dist/_internal/shared/features/returns/custody.js

@@ -0,0 +1,172 @@
+/**
+ * Return custody — C5g. Where a returned parcel is, and who owns the next step.
+ *
+ * ## 🛑 The gap this closes, measured
+ *
+ * `OrderStatus` has exactly TWO return states: `return_requested` → `returned`.
+ * There is no `returnAddress`, no `rmaNumber` and no inspection field anywhere
+ * on `OrderDocument` (grepped: zero hits). So a buyer whose return is approved
+ * today is told nothing about where to send the item, and the status jumps from
+ * "requested" straight to "returned" with no custody in between.
+ *
+ * Two statuses cannot express *"the buyer posted it and we have not received
+ * it"*, which is the single most-asked question in any returns flow. And that
+ * gap exists on the ORDINARY seller path too, not only on protected claims —
+ * a return with no address is unactionable for either party, which is why this
+ * is worth closing regardless of whether escrow ever ships.
+ *
+ * ## 🛑 Why a SUB-STATUS and not five new `OrderStatus` members
+ *
+ * The plan left this open as "a schema decision worth taking deliberately".
+ * Taken: custody is its own field, and `OrderStatus` keeps its two values.
+ *
+ *   1. `OrderStatus` drives every order surface — nine status chips, the
+ *      Active/Closed scope map (`Record<OrderStatus, …>`), badges, filters,
+ *      `mergeOrderScopeFilter`. Five new members would appear in all of them
+ *      while applying only to a return, and all five would map to "Active",
+ *      so they would add a chip and no information.
+ *   2. A return is a SUB-PROCESS of an order, not a phase of it. The order's
+ *      own fact is "a return is in progress"; the rest belongs to the return.
+ *   3. It composes with what is already per-item. `OrderDocumentItem` already
+ *      carries `cancelledQuantity`, so partial returns are an item-level idea —
+ *      and an order-level status could never express two items in different
+ *      custody states.
+ *
+ * And NOT a separate `returns` collection either, which was the third option:
+ * that would make a fourth place order state lives (the order, its items, its
+ * `statusHistory`, and a return document), and the first three already have to
+ * agree.
+ */
+/**
+ * The custody chain. Ordered, and the order is load-bearing — `canAdvance`
+ * reads it rather than hand-listing transitions.
+ */
+export const RETURN_CUSTODY_STATES = [
+    /** The buyer asked. Nobody has agreed to anything yet. */
+    "requested",
+    /** Approved, and the buyer has been given a destination. */
+    "approved",
+    /** The buyer says they have posted it. Our records show nothing yet. */
+    "in_transit",
+    /** It physically arrived, wherever it was routed to. */
+    "received",
+    /** A human has opened it and recorded a finding. */
+    "inspected",
+    /** Refund (or refusal) issued; money has moved. */
+    "resolved",
+];
+/**
+ * 🛑 A `Record<ReturnCustodyState, …>`, so a seventh state cannot compile
+ * without someone answering what the buyer is told during it.
+ *
+ * The copy matters more than it looks: `in_transit` is the state that exists
+ * ENTIRELY so a buyer who has posted something is not shown "requested" for a
+ * week, and a label that does not say "we have not received it yet" wastes the
+ * state.
+ */
+export const RETURN_CUSTODY_COPY = {
+    requested: {
+        label: "Return requested",
+        buyerNote: "We have your request. You will get a return address once it is approved.",
+    },
+    approved: {
+        label: "Return approved",
+        buyerNote: "Approved. Post the item to the address below, then mark it as sent.",
+    },
+    in_transit: {
+        label: "On its way back",
+        buyerNote: "You have marked this as posted. We have not received it yet.",
+    },
+    received: {
+        label: "Received",
+        buyerNote: "It arrived. We are checking it now.",
+    },
+    inspected: {
+        label: "Checked",
+        buyerNote: "We have checked the item. Your refund is being processed.",
+    },
+    resolved: {
+        label: "Return complete",
+        buyerNote: "Done — see the refund on this order.",
+    },
+};
+/** Terminal: nothing follows `resolved`. */
+export function isTerminalCustody(state) {
+    return state === "resolved";
+}
+/**
+ * Whether `next` may follow `current`.
+ *
+ * 🛑 Strictly forward, one step at a time, and that is deliberate rather than
+ * lazy. A flow that permits skipping lets `approved → resolved` refund an item
+ * nobody ever received, which is the exact shape of the fraud
+ * `return_swap_fraud` describes; and a flow that permits going backwards lets a
+ * seller un-receive a parcel to re-open a settled inspection.
+ *
+ * The one exception is the identity transition, which is allowed so an
+ * idempotent writer (a retry, a double-clicked button) is a no-op rather than
+ * an error.
+ */
+export function canAdvanceCustody(current, next) {
+    if (current === next)
+        return true;
+    const i = RETURN_CUSTODY_STATES.indexOf(current);
+    const j = RETURN_CUSTODY_STATES.indexOf(next);
+    if (i < 0 || j < 0)
+        return false;
+    return j === i + 1;
+}
+/** The next state, or `null` at the end of the chain. */
+export function nextCustodyState(current) {
+    const i = RETURN_CUSTODY_STATES.indexOf(current);
+    if (i < 0 || i === RETURN_CUSTODY_STATES.length - 1)
+        return null;
+    return RETURN_CUSTODY_STATES[i + 1];
+}
+/**
+ * Who owns the next action.
+ *
+ * 🛑 This is the half of C5g that CLAUDE.md gets wrong today. It records
+ * `return_requested` as deliberately in the *Active* order scope because it is
+ * "the seller's next action item" — and with warehouse routing that is no
+ * longer true for an untrusted seller's protected claim: it is OUR action item
+ * until inspection completes. A queue that shows it as the seller's is a queue
+ * where returns sit waiting on us.
+ *
+ * `buyer` during `approved`/`in_transit` is not a formality either — the buyer
+ * is the only party who can post the parcel, and showing a seller an action
+ * they cannot take is how a return stalls with everyone waiting.
+ */
+export function custodyOwner(state, destination) {
+    switch (state) {
+        case "requested":
+            // Whoever will receive it decides whether to accept it.
+            return destination === "warehouse" ? "platform" : "seller";
+        case "approved":
+        case "in_transit":
+            return "buyer";
+        case "received":
+        case "inspected":
+            return destination === "warehouse" ? "platform" : "seller";
+        case "resolved":
+            // Nothing to do. Reported as the platform's so a stale queue entry is
+            // ours to clear rather than a seller's to wonder about.
+            return "platform";
+        default: {
+            const unreachable = state;
+            return unreachable;
+        }
+    }
+}
+/**
+ * Whether this custody state should appear in a WORK QUEUE for `viewer`.
+ *
+ * Deliberately not `custodyOwner(...) === viewer`: `resolved` belongs to nobody
+ * and must leave every queue, and a terminal row in a queue is how a queue
+ * stops being read.
+ */
+export function isActionableBy(state, destination, viewer) {
+    if (isTerminalCustody(state))
+        return false;
+    return custodyOwner(state, destination) === viewer;
+}

package/dist/_internal/shared/features/returns/destination.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Where a return or an RTO physically goes — C5g / C5h.
+ *
+ * ## 🛑 The address is DERIVED, never typed
+ *
+ * `returnDestination()` in `../shipping/protections` decides warehouse-vs-seller
+ * from the add-on and the admin trust flag; this module turns that decision into
+ * the actual address string.
+ *
+ * A free-text `returnAddress` field a human fills in would be a second owner of
+ * a value we can compute, and the wrong one is a parcel lost — which is a worse
+ * outcome than any of the drift this codebase usually pays for. So it is
+ * derived once, at approval, and then SNAPSHOTTED onto the order: an admin
+ * flipping `returnsDirectToSeller` while a parcel is in the post must not
+ * retroactively change where the buyer was told to send it.
+ */
+/** Minimal shape — whatever a store carries that could serve as a pickup point. */
+export interface SellerReturnAddressSource {
+    storeName?: string;
+    /** The store's own pickup address, when it has one. */
+    pickupAddress?: string;
+}
+export type ReturnAddressResolution = {
+    kind: "warehouse";
+    address: string;
+} | {
+    kind: "seller";
+    address: string;
+}
+/**
+ * 🛑 The third outcome, and the reason this returns a union rather than a
+ * string.
+ *
+ * A seller-routed return whose store has no pickup address has NO
+ * destination, and `""` would be rendered to the buyer as a blank address
+ * block — "post it to nowhere", with a success state. Measured 2026-10-11:
+ * `addresses` carries zero `ownerType:"store"` rows, so this is the common
+ * case today rather than a corner.
+ *
+ * The caller must refuse to approve the return and tell the seller to add a
+ * pickup address. It cannot accidentally hand out an empty one.
+ */
+ | {
+    kind: "unavailable";
+    reason: "seller-has-no-pickup-address" | "warehouse-not-configured";
+};
+export interface ResolveReturnAddressInput {
+    destination: "warehouse" | "seller";
+    /** `process.env.WAREHOUSE_ADDRESS` — config, not a secret. */
+    warehouseAddress?: string;
+    seller?: SellerReturnAddressSource;
+}
+/**
+ * The address to show the buyer.
+ *
+ * 🛑 `COMPANY_ADDRESS` is deliberately NOT consulted here, and must never
+ * become a fallback. It is a test fixture — a known-good destination for the
+ * smoke script — and substituting it for a missing warehouse or seller address
+ * would ship a real returned parcel to our own office while reporting success.
+ * That is the exact plausible-200 shape this plan keeps finding, and the
+ * tempting use is also the dangerous one.
+ */
+export declare function resolveReturnAddress(input: ResolveReturnAddressInput): ReturnAddressResolution;
+/**
+ * An RTO — Return To Origin — is the carrier sending a parcel back because it
+ * could not be delivered. Nobody asked for it.
+ *
+ * 🛑 That is what makes it a THIRD path rather than a variant of a return: no
+ * claim exists, no return was approved, and it arrives whether or not anyone is
+ * expecting it. So it cannot reuse the custody chain's `requested`/`approved`
+ * states — it enters at `received`, which is the first state that describes
+ * something physically present.
+ */
+export declare const RTO_ENTRY_CUSTODY: "received";
+export type RtoCostBearer = "platform" | "seller" | "buyer";
+/**
+ * Who bears the RTO leg.
+ *
+ * 🛑 **Us, either way**, and this is C5g-policy applied rather than re-decided.
+ * The common cause is a wrong or incomplete buyer address: charging the seller
+ * for a buyer's typo drives sellers off, and billing the buyer after the fact is
+ * uncollectable.
+ *
+ * But it is RECORDED rather than silently absorbed. An RTO has a real cost —
+ * the carrier bills the return leg, and under escrow the buyer's shipping money
+ * is already spent on the forward leg, so it is a genuine new charge with
+ * nothing collected behind it. Absorbing it quietly is how a cost becomes
+ * invisible and then structural; `reason` is what makes it a line someone can
+ * total.
+ */
+export declare function rtoCostBearer(): {
+    bearer: RtoCostBearer;
+    reason: string;
+};
+/**
+ * Scam-registry types an inspection finding can substantiate.
+ *
+ * 🛑 All four ALREADY EXIST in `features/scams/constants/scam-types.ts` —
+ * verified, not assumed. The registry anticipated this control before the
+ * control existed, so C5i adds no scam type.
+ *
+ * 🛑 And inspection is BIDIRECTIONAL evidence, not a buyer-fraud filter. It is
+ * the only point in the flow where a human sees the actual item, which makes it
+ * the only place either party's pattern can be substantiated. A plan that
+ * framed it as buyer-abuse control would be using half of it — so two of these
+ * four are seller-side.
+ */
+export declare const RETURN_ABUSE_SCAM_TYPES: {
+    /** BUYER: returned a different item. Literally why we inspect. */
+    readonly returnSwap: "return_swap_fraud";
+    /** BUYER: serial no-questions-asked refunds. */
+    readonly claimAbuse: "chargeback_fraud";
+    /** SELLER: items that keep coming back as "not as described". */
+    readonly sellerMisrepresentation: "condition_misrepresentation";
+    /** SELLER: shipped nothing. */
+    readonly sellerEmptyBox: "empty_box_ship";
+};
+export type ReturnAbuseSignal = (typeof RETURN_ABUSE_SCAM_TYPES)[keyof typeof RETURN_ABUSE_SCAM_TYPES];
+/**
+ * Thresholds at which a pattern is worth a human's attention.
+ *
+ * 🛑 A threshold is a SIGNAL, not a verdict. Crossing one opens a
+ * `ReportDocument` for admin review; it does not deny a claim and it does not
+ * ban anyone. An automatic exclusion on a count would punish an unlucky buyer
+ * who received two genuinely bad items, and the registry's own entries are
+ * written as patterns to RECOGNISE rather than rules to fire.
+ */
+export declare const RETURN_ABUSE_THRESHOLDS: {
+    /** Change-of-mind claims on a no-questions-asked cover, per buyer. */
+    readonly buyerChangeOfMindClaims: 3;
+    /** Genuine "not as described" findings against one seller. */
+    readonly sellerGenuineFindings: 3;
+};
+export interface ReturnAbuseCounters {
+    /** Protected change-of-mind claims by this buyer, pre-computed. */
+    buyerChangeOfMindClaims?: number;
+    /** Genuine findings against this seller, pre-computed. */
+    sellerGenuineFindings?: number;
+}
+/**
+ * Which signals this inspection substantiates.
+ *
+ * 🛑 The counters are PRE-COMPUTED and passed in. "How many claims has this
+ * buyer made" is an unbounded per-request aggregation over orders — the exact
+ * pattern that paused this project (Root Cause #104) — so it rides the daily
+ * job as one more pass, the same lever as the price index and the pageViews
+ * rollup. This function must never query.
+ */
+export declare function returnAbuseSignals(input: {
+    finding: "genuine" | "change-of-mind";
+    protectedSale: boolean;
+    /** True when inspection found a DIFFERENT item than the one sold. */
+    itemMismatch?: boolean;
+    /** True when inspection found an empty or itemless parcel. */
+    emptyParcel?: boolean;
+    counters?: ReturnAbuseCounters;
+}): ReturnAbuseSignal[];
+/**
+ * What enforcement actually is.
+ *
+ * 🛑 Withdrawing FUTURE eligibility, never denying a live claim. The moment
+ * inspection can block a protected refund the promise is false, and we are back
+ * to a badge that means nothing. A buyer flagged for claim abuse keeps the
+ * marketplace and loses the cover they abused — which composes with the
+ * existing soft-ban machinery (`BannedAction` is already a closed set) rather
+ * than extending it.
+ */
+export declare function enforcementFor(signals: readonly ReturnAbuseSignal[]): {
+    deniesCurrentClaim: false;
+    withdrawsFutureSaleProtection: boolean;
+    opensReportForReview: boolean;
+};

package/dist/_internal/shared/features/returns/destination.js

@@ -0,0 +1,158 @@
+/**
+ * Where a return or an RTO physically goes — C5g / C5h.
+ *
+ * ## 🛑 The address is DERIVED, never typed
+ *
+ * `returnDestination()` in `../shipping/protections` decides warehouse-vs-seller
+ * from the add-on and the admin trust flag; this module turns that decision into
+ * the actual address string.
+ *
+ * A free-text `returnAddress` field a human fills in would be a second owner of
+ * a value we can compute, and the wrong one is a parcel lost — which is a worse
+ * outcome than any of the drift this codebase usually pays for. So it is
+ * derived once, at approval, and then SNAPSHOTTED onto the order: an admin
+ * flipping `returnsDirectToSeller` while a parcel is in the post must not
+ * retroactively change where the buyer was told to send it.
+ */
+/**
+ * The address to show the buyer.
+ *
+ * 🛑 `COMPANY_ADDRESS` is deliberately NOT consulted here, and must never
+ * become a fallback. It is a test fixture — a known-good destination for the
+ * smoke script — and substituting it for a missing warehouse or seller address
+ * would ship a real returned parcel to our own office while reporting success.
+ * That is the exact plausible-200 shape this plan keeps finding, and the
+ * tempting use is also the dangerous one.
+ */
+export function resolveReturnAddress(input) {
+    if (input.destination === "warehouse") {
+        const w = (input.warehouseAddress ?? "").trim();
+        if (!w)
+            return { kind: "unavailable", reason: "warehouse-not-configured" };
+        return { kind: "warehouse", address: w };
+    }
+    const s = (input.seller?.pickupAddress ?? "").trim();
+    if (!s)
+        return { kind: "unavailable", reason: "seller-has-no-pickup-address" };
+    return { kind: "seller", address: s };
+}
+// ── C5h: RTO ────────────────────────────────────────────────────────────────
+/**
+ * An RTO — Return To Origin — is the carrier sending a parcel back because it
+ * could not be delivered. Nobody asked for it.
+ *
+ * 🛑 That is what makes it a THIRD path rather than a variant of a return: no
+ * claim exists, no return was approved, and it arrives whether or not anyone is
+ * expecting it. So it cannot reuse the custody chain's `requested`/`approved`
+ * states — it enters at `received`, which is the first state that describes
+ * something physically present.
+ */
+export const RTO_ENTRY_CUSTODY = "received";
+/**
+ * Who bears the RTO leg.
+ *
+ * 🛑 **Us, either way**, and this is C5g-policy applied rather than re-decided.
+ * The common cause is a wrong or incomplete buyer address: charging the seller
+ * for a buyer's typo drives sellers off, and billing the buyer after the fact is
+ * uncollectable.
+ *
+ * But it is RECORDED rather than silently absorbed. An RTO has a real cost —
+ * the carrier bills the return leg, and under escrow the buyer's shipping money
+ * is already spent on the forward leg, so it is a genuine new charge with
+ * nothing collected behind it. Absorbing it quietly is how a cost becomes
+ * invisible and then structural; `reason` is what makes it a line someone can
+ * total.
+ */
+export function rtoCostBearer() {
+    return {
+        bearer: "platform",
+        reason: "RTO legs are absorbed by the platform (C5g-policy): the usual cause is a " +
+            "wrong or incomplete delivery address, which is nobody's fault we can bill.",
+    };
+}
+// ── C5i: abuse signal ───────────────────────────────────────────────────────
+/**
+ * Scam-registry types an inspection finding can substantiate.
+ *
+ * 🛑 All four ALREADY EXIST in `features/scams/constants/scam-types.ts` —
+ * verified, not assumed. The registry anticipated this control before the
+ * control existed, so C5i adds no scam type.
+ *
+ * 🛑 And inspection is BIDIRECTIONAL evidence, not a buyer-fraud filter. It is
+ * the only point in the flow where a human sees the actual item, which makes it
+ * the only place either party's pattern can be substantiated. A plan that
+ * framed it as buyer-abuse control would be using half of it — so two of these
+ * four are seller-side.
+ */
+export const RETURN_ABUSE_SCAM_TYPES = {
+    /** BUYER: returned a different item. Literally why we inspect. */
+    returnSwap: "return_swap_fraud",
+    /** BUYER: serial no-questions-asked refunds. */
+    claimAbuse: "chargeback_fraud",
+    /** SELLER: items that keep coming back as "not as described". */
+    sellerMisrepresentation: "condition_misrepresentation",
+    /** SELLER: shipped nothing. */
+    sellerEmptyBox: "empty_box_ship",
+};
+/**
+ * Thresholds at which a pattern is worth a human's attention.
+ *
+ * 🛑 A threshold is a SIGNAL, not a verdict. Crossing one opens a
+ * `ReportDocument` for admin review; it does not deny a claim and it does not
+ * ban anyone. An automatic exclusion on a count would punish an unlucky buyer
+ * who received two genuinely bad items, and the registry's own entries are
+ * written as patterns to RECOGNISE rather than rules to fire.
+ */
+export const RETURN_ABUSE_THRESHOLDS = {
+    /** Change-of-mind claims on a no-questions-asked cover, per buyer. */
+    buyerChangeOfMindClaims: 3,
+    /** Genuine "not as described" findings against one seller. */
+    sellerGenuineFindings: 3,
+};
+/**
+ * Which signals this inspection substantiates.
+ *
+ * 🛑 The counters are PRE-COMPUTED and passed in. "How many claims has this
+ * buyer made" is an unbounded per-request aggregation over orders — the exact
+ * pattern that paused this project (Root Cause #104) — so it rides the daily
+ * job as one more pass, the same lever as the price index and the pageViews
+ * rollup. This function must never query.
+ */
+export function returnAbuseSignals(input) {
+    const out = [];
+    const c = input.counters ?? {};
+    // Buyer side. A swap is substantiated by the item itself, with no threshold —
+    // one wrong item back is not a pattern, it is an act.
+    if (input.itemMismatch)
+        out.push(RETURN_ABUSE_SCAM_TYPES.returnSwap);
+    if (input.protectedSale &&
+        input.finding === "change-of-mind" &&
+        (c.buyerChangeOfMindClaims ?? 0) >= RETURN_ABUSE_THRESHOLDS.buyerChangeOfMindClaims) {
+        out.push(RETURN_ABUSE_SCAM_TYPES.claimAbuse);
+    }
+    // Seller side.
+    if (input.emptyParcel)
+        out.push(RETURN_ABUSE_SCAM_TYPES.sellerEmptyBox);
+    if (input.finding === "genuine" &&
+        (c.sellerGenuineFindings ?? 0) >= RETURN_ABUSE_THRESHOLDS.sellerGenuineFindings) {
+        out.push(RETURN_ABUSE_SCAM_TYPES.sellerMisrepresentation);
+    }
+    return out;
+}
+/**
+ * What enforcement actually is.
+ *
+ * 🛑 Withdrawing FUTURE eligibility, never denying a live claim. The moment
+ * inspection can block a protected refund the promise is false, and we are back
+ * to a badge that means nothing. A buyer flagged for claim abuse keeps the
+ * marketplace and loses the cover they abused — which composes with the
+ * existing soft-ban machinery (`BannedAction` is already a closed set) rather
+ * than extending it.
+ */
+export function enforcementFor(signals) {
+    return {
+        deniesCurrentClaim: false,
+        withdrawsFutureSaleProtection: signals.includes(RETURN_ABUSE_SCAM_TYPES.claimAbuse),
+        opensReportForReview: signals.length > 0,
+    };
+}

package/dist/_internal/shared/features/reviews/errors.js

@@ -1,4 +1,4 @@
-import { NotFoundError, ConflictError, UnauthorizedError } from "../../errors/index";
+import { NotFoundError, ConflictError, UnauthorizedError } from "../../errors/index.js";
 export class ReviewNotFoundError extends NotFoundError {
     constructor(id) {
         super("Review", id);

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { mediaUrlSchema } from "../../../../validation/schemas";
-import { REVIEW_BODY_MAX_LENGTH, REVIEW_BODY_MIN_LENGTH, REVIEW_TITLE_MAX_LENGTH, REVIEW_MIN_RATING, REVIEW_MAX_RATING, REVIEW_IMAGES_MAX, REVIEW_REPLY_MAX_LENGTH, } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas.js";
+import { REVIEW_BODY_MAX_LENGTH, REVIEW_BODY_MIN_LENGTH, REVIEW_TITLE_MAX_LENGTH, REVIEW_MIN_RATING, REVIEW_MAX_RATING, REVIEW_IMAGES_MAX, REVIEW_REPLY_MAX_LENGTH, } from "./config.js";
 export const createReviewSchema = z.object({
     productId: z.string().min(1),
     storeId: z.string().min(1),

package/dist/_internal/shared/features/shipping/courier-rating.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Courier ratings — C5f. Two numbers, side by side, NEVER blended.
+ *
+ * ## 🛑 The one rule
+ *
+ * The carrier's own rating (Shiprocket's, when a booking exists) and ours are
+ * shown separately and are never averaged into a third figure.
+ *
+ * Same discipline as market-vs-sold price and estimated-vs-actual parcel
+ * weight, and for the same reason in all three cases: **the gap is the
+ * information**. A courier Shiprocket rates 4.8 and our own buyers rate 4.1 is
+ * telling us something specific — that the aggregate across their whole book of
+ * business does not describe our lanes, our parcels or our buyers. Averaging
+ * the two to 4.45 destroys exactly that signal and launders a vendor's number
+ * into one that looks like ours.
+ *
+ * ```
+ * Blue Dart Air      Shiprocket 4.8★ · LetItRip 4.5★ (23)   1–2 days   ₹140
+ * Delhivery Surface  Shiprocket 4.6★ · not enough data yet   3–5 days    ₹60
+ * ```
+ *
+ * ## 🛑 Below the threshold: "not enough data yet", never a number
+ *
+ * Identical rule to the price index, and it has to be, because a courier list
+ * is a choice made under time pressure: a 5.0 from one rating reads as better
+ * than a 4.6 from four hundred, and the reader has no way to know otherwise
+ * unless we decline to print it.
+ *
+ * ## What this module is NOT
+ *
+ * It does not query, it does not aggregate, and it does not fetch. The rollup
+ * runs as a pass in the existing daily job — a new Cloud Scheduler job would be
+ * a real registered cost (§ Firebase budget) for a number nobody reads hourly.
+ *
+ * 🛑 And `aggregateRatingJsonLd` stays `Product`-typed and is deliberately NOT
+ * extended to cover this. A courier rating is operational feedback for a
+ * fulfilment choice, not a product review; marking it up invites a rich result
+ * for something we do not sell.
+ */
+/**
+ * Below this, our own rating renders as a sample count and no star figure.
+ *
+ * Exported so the rollup, the projection and the view agree. A threshold one
+ * applied and another did not would either hide real data or publish an average
+ * of two votes as a reliability score.
+ */
+export declare const COURIER_RATING_MIN_CONFIDENT_SAMPLES = 5;
+/** One courier's two numbers, as a renderer receives them. */
+export interface CourierRatingPair {
+    courierId: string;
+    name: string;
+    /**
+     * The carrier's own rating, passed through verbatim.
+     *
+     * 🛑 Absent is not zero. A courier Shiprocket has not rated has no vendor
+     * figure, and rendering 0★ would read as "rated terribly" rather than "not
+     * rated" — the same distinction `undefined` vs `0` carries on every count in
+     * this codebase (Root Cause #72).
+     */
+    providerRating?: number;
+    /** Ours, from `courierStats/{courierId}`. Absent until anyone has rated. */
+    platformRating?: {
+        average: number;
+        count: number;
+        onTimeShare?: number;
+    };
+}
+export type CourierRatingDisplay = {
+    kind: "none";
+    label: string;
+} | {
+    kind: "provider-only";
+    providerRating: number;
+    ourLabel: string;
+} | {
+    kind: "ours-only";
+    average: number;
+    count: number;
+} | {
+    kind: "both";
+    providerRating: number;
+    average: number;
+    count: number;
+};
+/**
+ * What to render for one courier.
+ *
+ * 🛑 Returns a discriminated union rather than two optional numbers, because
+ * the four cases read differently and a renderer that has to decide will
+ * eventually print `0★` for one of them. The union makes "we have no rating"
+ * impossible to confuse with "we have a rating of zero".
+ */
+export declare function courierRatingDisplay(pair: CourierRatingPair): CourierRatingDisplay;
+/**
+ * 🛑 There is deliberately NO `combinedRating()` in this module, and this
+ * comment is the enforcement.
+ *
+ * Every time a rating pair reaches a sort, a badge or a "best courier" pick,
+ * the cheapest-looking move is to average the two so there is one number to
+ * order by. Do not add it. If a single ordering is genuinely needed, order by
+ * OURS and fall back to the provider's — stating which one you used — because
+ * that is a choice a reader can evaluate, and a mean of two differently-sourced
+ * populations is not.
+ */
+/** One vote. The document shape of `courierRatings`. */
+export interface CourierRatingVote {
+    courierId: string;
+    orderId: string;
+    userId: string;
+    /** 1–5. */
+    rating: number;
+    /** Did it arrive by the promised date? Tracked separately from the stars. */
+    onTime: boolean;
+    comment?: string;
+}
+/**
+ * Is this vote acceptable?
+ *
+ * 🛑 One vote per user per ORDER, not per courier — a buyer who used Blue Dart
+ * four times has four legitimate opinions, and collapsing them to one would
+ * weight a frequent buyer the same as a one-off. Idempotency is by document id
+ * (`{orderId}__{userId}`), reusing the precedent `ReviewDocument.helpfulVoterIds`
+ * already sets rather than inventing a second one.
+ */
+export declare function isValidCourierVote(vote: Partial<CourierRatingVote>): boolean;
+/** The deterministic id — a re-vote overwrites rather than double-counting. */
+export declare function courierVoteId(orderId: string, userId: string): string;
+/** The rolled-up shape, written daily. */
+export interface CourierStats {
+    courierId: string;
+    average: number;
+    count: number;
+    /** Share of votes reporting on-time delivery, 0–1. */
+    onTimeShare: number;
+    computedAt: Date;
+}
+/**
+ * Roll a vote list into stats.
+ *
+ * Pure, so the daily job and any verification share one implementation.
+ * 🛑 Returns `null` for an empty list rather than a zeroed record — writing
+ * `average: 0, count: 0` would publish a courier as rated-zero, and a reader
+ * cannot tell that from a genuinely terrible courier.
+ */
+export declare function rollUpCourierVotes(courierId: string, votes: readonly CourierRatingVote[], now: Date): CourierStats | null;