@mohasinac/appkit 4.44.0 → 4.45.0

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;

package/dist/_internal/shared/features/shipping/courier-rating.js

@@ -0,0 +1,114 @@
+/**
+ * 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 const COURIER_RATING_MIN_CONFIDENT_SAMPLES = 5;
+/**
+ * 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 function courierRatingDisplay(pair) {
+    const provider = typeof pair.providerRating === "number" && pair.providerRating > 0
+        ? pair.providerRating
+        : undefined;
+    const ours = pair.platformRating && pair.platformRating.count >= COURIER_RATING_MIN_CONFIDENT_SAMPLES
+        ? pair.platformRating
+        : undefined;
+    if (provider != null && ours) {
+        return { kind: "both", providerRating: provider, average: ours.average, count: ours.count };
+    }
+    if (provider != null) {
+        return { kind: "provider-only", providerRating: provider, ourLabel: "not enough data yet" };
+    }
+    if (ours)
+        return { kind: "ours-only", average: ours.average, count: ours.count };
+    return { kind: "none", label: "not rated yet" };
+}
+/**
+ * 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 function isValidCourierVote(vote) {
+    if (!vote.courierId || !vote.orderId || !vote.userId)
+        return false;
+    if (typeof vote.rating !== "number" || !Number.isInteger(vote.rating))
+        return false;
+    return vote.rating >= 1 && vote.rating <= 5;
+}
+/** The deterministic id — a re-vote overwrites rather than double-counting. */
+export function courierVoteId(orderId, userId) {
+    return `${orderId}__${userId}`;
+}
+/**
+ * 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 function rollUpCourierVotes(courierId, votes, now) {
+    const valid = votes.filter((v) => isValidCourierVote(v));
+    if (valid.length === 0)
+        return null;
+    const sum = valid.reduce((s, v) => s + v.rating, 0);
+    const onTime = valid.filter((v) => v.onTime).length;
+    return {
+        courierId,
+        average: Math.round((sum / valid.length) * 100) / 100,
+        count: valid.length,
+        onTimeShare: Math.round((onTime / valid.length) * 100) / 100,
+        computedAt: now,
+    };
+}