@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/_internal/shared/features/admin/integrations.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The integration switches, and what turning each one OFF actually does.
+ *
+ * ## 🛑 This is a VIEW over existing fields, never a second store
+ *
+ * Three of the four already have an authoritative field:
+ *
+ *   payments  -> `payment.razorpayEnabled`
+ *   email     -> `messaging.emailEnabled`   (read by `guardSend`)
+ *   shipping  -> `shipping.provider`        ("manual" | "shiprocket")
+ *
+ * Adding an `integrationSwitches.payments` beside those would be a
+ * denormalised mirror, and it would drift the first time a path wrote one of
+ * the pair and not the other (Root Cause #42) — at which point the admin page
+ * says "on" while the code that enforces it reads "off". Only `support.enabled`
+ * is new, because only support had nothing.
+ *
+ * ## 🛑 Off does not mean the same thing twice
+ *
+ * "Payments off" stops money. "Support off" hides a contact route. "Shipping
+ * off" is not even expressible — a parcel still has to move, so the shipping
+ * switch selects manual (self-ship) rather than stopping anything.
+ *
+ * Presenting four interchangeable toggles would invite an admin to flip the
+ * expensive one by muscle memory, so every row carries its own
+ * `offConsequence` and the dangerous ones are marked.
+ */
+import type { SiteSettingsDocument } from "../../../../features/admin/schemas/firestore";
+export type IntegrationId = "payments" | "email" | "shipping" | "support";
+export interface IntegrationDescriptor {
+    id: IntegrationId;
+    label: string;
+    /** One line: what this integration IS. */
+    summary: string;
+    /** 🛑 Shown on the row. What switching it off does, in the admin's terms. */
+    offConsequence: string;
+    /**
+     * `true` when turning it off stops money or breaks a flow a user is
+     * mid-way through. Drives a confirmation and a visual warning — an
+     * accidental click here is expensive.
+     */
+    severe: boolean;
+    /** The settings path the switch actually writes. Named, so it is auditable. */
+    field: string;
+    /**
+     * Whether this integration's API routes are closed when it is off, and WHY
+     * that answer is what it is. Three different answers for four integrations,
+     * so a uniform wrapper applied to everything would be wrong three ways.
+     *
+     * - `"gated"`  — the routes 404 when off (payments, support).
+     * - `"none"`   — there is nothing to gate, stated with the reason, so nobody
+     *                later "completes" the set by guarding a route that must
+     *                stay open.
+     */
+    routeGuard: "gated" | "none";
+    /** Human reason for `routeGuard`, shown nowhere — it is for the next reader. */
+    routeGuardNote: string;
+    /**
+     * 🛑 Which way the guard fails when the settings read itself throws, and this
+     * genuinely DIFFERS per integration — a single uniform direction would be
+     * the wrong call for one of them whichever one was picked.
+     *
+     * `true` (payments): a Firestore blip must not open a money route. Closed is
+     * the safe direction for money.
+     *
+     * `false` (support): refusing support because Firestore hiccupped is worse
+     * than briefly allowing a ticket nobody wanted — and it is the same choice
+     * `guardSend` makes on the same read.
+     */
+    failClosed: boolean;
+}
+/**
+ * 🛑 A `Record<IntegrationId, …>`, so a fifth integration cannot be added
+ * without writing its off-consequence. A row with no stated consequence is
+ * exactly the interchangeable-toggle failure this file exists to prevent.
+ */
+export declare const INTEGRATIONS: Record<IntegrationId, IntegrationDescriptor>;
+/** Display order. Money first, because it is what an admin came to check. */
+export declare const INTEGRATION_ORDER: readonly IntegrationId[];
+/** What a switch reads/writes. `shipping` is a provider, not a boolean. */
+export type IntegrationState = {
+    enabled: boolean;
+};
+/**
+ * Read each switch out of a settings document.
+ *
+ * 🛑 Defaults differ per integration and are NOT a uniform `?? false`:
+ * `razorpayEnabled` genuinely defaults off (it is opt-in and the account runs
+ * test keys), while email and support default ON because an older settings
+ * document with no such field must not read as "we stopped talking to
+ * customers".
+ *
+ * 🛑 THIS FUNCTION IS THE EXPRESSION THE ROUTE GUARDS USE. `withOnlinePaymentEnabled`
+ * had hand-written the payments half, and the first version of this file
+ * reproduced it WRONG — see the payments line. Both now resolve here, so the
+ * admin page and the guard cannot disagree about whether an integration is on.
+ * That disagreement is the entire failure mode this file's header warns about
+ * (Root Cause #42), and it had already happened once, inside the file.
+ */
+export declare function readIntegrationStates(settings: Partial<SiteSettingsDocument> | null | undefined): Record<IntegrationId, IntegrationState>;
+/**
+ * Turn a desired state into the settings patch that expresses it.
+ *
+ * Returned as a nested partial rather than applied here, so the caller does
+ * one write and the audit log records one action.
+ */
+export declare function integrationPatch(id: IntegrationId, enabled: boolean): Record<string, unknown>;
+/** Every patch for a bulk enable/disable, merged into one object. */
+export declare function allIntegrationsPatch(enabled: boolean): Record<string, unknown>;

package/dist/_internal/shared/features/admin/integrations.js

@@ -0,0 +1,253 @@
+/**
+ * The integration switches, and what turning each one OFF actually does.
+ *
+ * ## 🛑 This is a VIEW over existing fields, never a second store
+ *
+ * Three of the four already have an authoritative field:
+ *
+ *   payments  -> `payment.razorpayEnabled`
+ *   email     -> `messaging.emailEnabled`   (read by `guardSend`)
+ *   shipping  -> `shipping.provider`        ("manual" | "shiprocket")
+ *
+ * Adding an `integrationSwitches.payments` beside those would be a
+ * denormalised mirror, and it would drift the first time a path wrote one of
+ * the pair and not the other (Root Cause #42) — at which point the admin page
+ * says "on" while the code that enforces it reads "off". Only `support.enabled`
+ * is new, because only support had nothing.
+ *
+ * ## 🛑 Off does not mean the same thing twice
+ *
+ * "Payments off" stops money. "Support off" hides a contact route. "Shipping
+ * off" is not even expressible — a parcel still has to move, so the shipping
+ * switch selects manual (self-ship) rather than stopping anything.
+ *
+ * Presenting four interchangeable toggles would invite an admin to flip the
+ * expensive one by muscle memory, so every row carries its own
+ * `offConsequence` and the dangerous ones are marked.
+ */
+/**
+ * 🛑 A `Record<IntegrationId, …>`, so a fifth integration cannot be added
+ * without writing its off-consequence. A row with no stated consequence is
+ * exactly the interchangeable-toggle failure this file exists to prevent.
+ */
+export const INTEGRATIONS = {
+    payments: {
+        id: "payments",
+        label: "Online payments",
+        summary: "Card, UPI and netbanking at checkout, through whichever gateway is live.",
+        /*
+         * 🛑 The second sentence is the one that matters and it was missing until
+         * the route guards were traced. `withOnlinePaymentEnabled` fails CLOSED and
+         * guards SIX routes including `/api/payment/verify` and the Razorpay
+         * WEBHOOK — so flipping this switch while a buyer is on the gateway's page
+         * abandons that payment: the money is captured and the callback that would
+         * have placed the order 404s. Razorpay retries on 5xx, NOT on 404, so it is
+         * not retried either.
+         *
+         * Ungating those two routes does not fix it — `providers.config.ts` only
+         * registers the gateway when this flag is on, so a completion path would
+         * reach `ManualPaymentProvider` and fail differently. The real fix is a
+         * bigger change (keep the provider registered for completion while refusing
+         * new orders), so until then this is a WARNING an admin must read rather
+         * than a hazard they discover.
+         */
+        offConsequence: "Buyers can no longer pay online. Checkout falls back to the manual methods (cash, UPI with a proof upload), which need an admin to verify every payment by hand. 🛑 Payments already in progress are abandoned — a buyer part-way through the gateway may be charged without an order being placed. Switch off when nobody is checking out.",
+        severe: true,
+        // Both gateways, because the enforcing guard is an OR across them. See the
+        // note on `readIntegrationStates`.
+        field: "payment.razorpayEnabled + payment.phonepeEnabled",
+        routeGuard: "gated",
+        routeGuardNote: "withOnlinePaymentEnabled, on all six /api/payment routes. Predates this page; this page now reads the same expression so the two cannot disagree.",
+        failClosed: true,
+    },
+    email: {
+        id: "email",
+        label: "Email sending (Resend)",
+        summary: "Order, offer and account emails.",
+        offConsequence: "Customer email stops. STAFF email is deliberately unaffected — the daily digest is how an operator notices a stuck payment or a new ticket, so switching customer mail off must not blind you.",
+        severe: true,
+        field: "messaging.emailEnabled",
+        routeGuard: "none",
+        /*
+         * 🛑 Not an oversight, and not a gap to close later. Email has no inbound
+         * route to guard — it is an OUTBOUND effect, and `guardSend` already
+         * enforces this flag at the single place that sends. Adding a route guard
+         * would mean inventing a route to guard.
+         */
+        routeGuardNote: "Nothing to gate: email is outbound. guardSend() enforces this flag at sendEmail(), the only sender.",
+        failClosed: false,
+    },
+    shipping: {
+        id: "shipping",
+        label: "Courier booking (Shiprocket)",
+        summary: "We book the courier and pay the freight.",
+        /*
+         * Not "shipping stops". The switch selects the PROVIDER, and manual is a
+         * working path, not a degraded one — it is the self-ship flow sellers
+         * already use and claim postage back through.
+         */
+        offConsequence: "We stop booking couriers. Sellers ship themselves and claim the postage back — the flow they already have. Nothing stops moving; in-flight shipments are unaffected.",
+        severe: false,
+        field: "shipping.provider",
+        routeGuard: "none",
+        /*
+         * 🛑 `/api/shipping/quote` must stay OPEN when this is off, and that is the
+         * whole reason this field exists rather than a blanket wrapper over every
+         * integration's routes.
+         *
+         * "Off" here means `provider: "manual"`, which is a WORKING path, not a
+         * disabled one. 404ing the quote route would break the self-ship flow that
+         * switching the integration off is specifically selecting — the guard would
+         * take out the fallback it is falling back to.
+         */
+        routeGuardNote: "Deliberately ungated: off means provider=manual, a working path. Guarding /api/shipping/quote would break the self-ship flow this switch selects.",
+        failClosed: false,
+    },
+    support: {
+        id: "support",
+        label: "Support & tickets",
+        summary: "The buyer's contact form and ticket history.",
+        /*
+         * The owner chose the widest reading of "off", and the consequence is real
+         * enough that the row has to state it plainly rather than let an admin
+         * discover it.
+         */
+        offConsequence: "The ticket surface disappears for buyers — no new tickets, no ticket list, no nav entry. The public Help Centre and its FAQs stay up, because self-service is what reduces tickets. Staff keep full access, so open tickets are still workable. A buyer with a conversation in progress loses sight of it.",
+        severe: true,
+        field: "support.enabled",
+        routeGuard: "gated",
+        /*
+         * 🛑 The line this note draws is RAISING vs ANSWERING, not buyer vs staff,
+         * and it decides three surfaces — so it is written down rather than left to
+         * be re-derived by whoever next "completes" the gating.
+         *
+         * GATED (raising): `/api/support/tickets` GET and POST, and a server layout
+         * over all of `/user/support/*`. The GET too, because gating only the write
+         * leaves a buyer looking at a ticket list they cannot reply to.
+         *
+         * NOT GATED (answering): `/admin/support-tickets`, and `/store/support` —
+         * which is the seller reading tickets raised ABOUT their store, not filing
+         * them. It is served by `SELLER_ENDPOINTS.SUPPORT`, a store-scoped endpoint,
+         * so it is untouched by the gate above and that is correct: the owner's rule
+         * is that open tickets stay workable, and a seller answering one is on the
+         * same side of that line as staff.
+         *
+         * EXEMPT: `unban_request`, the formal appeal channel. It already bypasses
+         * the soft-ban guard and the ticket cap, and an integration toggle must not
+         * be able to close a channel a soft ban is explicitly forbidden from
+         * closing.
+         */
+        routeGuardNote: "Gated on the RAISING side only: /api/support/tickets (GET+POST) and a server layout over /user/support/*. /store/support and /admin/support-tickets stay open — answering, not raising. unban_request is exempt.",
+        failClosed: false,
+    },
+};
+/** Display order. Money first, because it is what an admin came to check. */
+export const INTEGRATION_ORDER = [
+    "payments",
+    "email",
+    "shipping",
+    "support",
+];
+/**
+ * Read each switch out of a settings document.
+ *
+ * 🛑 Defaults differ per integration and are NOT a uniform `?? false`:
+ * `razorpayEnabled` genuinely defaults off (it is opt-in and the account runs
+ * test keys), while email and support default ON because an older settings
+ * document with no such field must not read as "we stopped talking to
+ * customers".
+ *
+ * 🛑 THIS FUNCTION IS THE EXPRESSION THE ROUTE GUARDS USE. `withOnlinePaymentEnabled`
+ * had hand-written the payments half, and the first version of this file
+ * reproduced it WRONG — see the payments line. Both now resolve here, so the
+ * admin page and the guard cannot disagree about whether an integration is on.
+ * That disagreement is the entire failure mode this file's header warns about
+ * (Root Cause #42), and it had already happened once, inside the file.
+ */
+export function readIntegrationStates(settings) {
+    return {
+        /*
+         * 🛑 An OR across BOTH gateways, not `razorpayEnabled` alone.
+         *
+         * This was wrong when written, and wrong in the direction that matters: the
+         * route guard is `razorpayEnabled === true || phonepeEnabled === true`, so
+         * with PhonePe on and Razorpay off the page would have reported "payments
+         * OFF" while all six /api/payment routes were OPEN and taking money. An
+         * admin reading that row would believe they had stopped payments.
+         *
+         * The guard's own docstring explains why it is an OR and must stay one:
+         * these routes are provider-AGNOSTIC — they call `getProviders().payment`,
+         * whichever single gateway `providers.config.ts` registered. The question
+         * is "is an online gateway live at all", asked once.
+         */
+        payments: {
+            enabled: settings?.payment?.razorpayEnabled === true ||
+                settings?.payment?.phonepeEnabled === true,
+        },
+        email: { enabled: settings?.messaging?.emailEnabled !== false },
+        // "Enabled" means we are booking couriers, i.e. the provider is not manual.
+        shipping: { enabled: settings?.shipping?.provider === "shiprocket" },
+        support: { enabled: settings?.support?.enabled !== false },
+    };
+}
+/**
+ * Turn a desired state into the settings patch that expresses it.
+ *
+ * Returned as a nested partial rather than applied here, so the caller does
+ * one write and the audit log records one action.
+ */
+export function integrationPatch(id, enabled) {
+    switch (id) {
+        case "payments":
+            /*
+             * 🛑 Writes BOTH gateway flags, and the OFF case is why.
+             *
+             * The guard is an OR, so clearing only `razorpayEnabled` while PhonePe
+             * was on would leave every /api/payment route open — the switch would
+             * report success and change nothing. "Disable payments" has to mean no
+             * online gateway is live, which is one flag per gateway.
+             *
+             * The ON case re-enables RAZORPAY only, deliberately asymmetric:
+             * `providers.config.ts` prefers Razorpay and ignores PhonePe when both
+             * are true (it logs exactly that), so turning both on would set a flag
+             * with no effect and make the page claim two gateways where there is
+             * one. Choosing a gateway is a different decision from switching
+             * payments on, and it belongs in Site Settings → Payment.
+             */
+            return enabled
+                ? { payment: { razorpayEnabled: true } }
+                : { payment: { razorpayEnabled: false, phonepeEnabled: false } };
+        case "email":
+            return { messaging: { emailEnabled: enabled } };
+        case "shipping":
+            /*
+             * 🛑 `manual`, never a missing value. The field's own docstring is
+             * explicit that a provider which fails to resolve must not silently
+             * become manual — so the OFF state has to be manual EXPLICITLY, and the
+             * absence of a value must never be how we express it.
+             */
+            return { shipping: { provider: enabled ? "shiprocket" : "manual" } };
+        case "support":
+            return { support: { enabled } };
+        default: {
+            /*
+             * Exhaustive. A fifth integration will not compile until someone decides
+             * which field it writes — which is the one decision that cannot be
+             * guessed later from the switch alone.
+             */
+            const unreachable = id;
+            return unreachable;
+        }
+    }
+}
+/** Every patch for a bulk enable/disable, merged into one object. */
+export function allIntegrationsPatch(enabled) {
+    const merged = {};
+    for (const id of INTEGRATION_ORDER) {
+        const patch = integrationPatch(id, enabled);
+        for (const [group, value] of Object.entries(patch)) {
+            merged[group] = { ...merged[group], ...value };
+        }
+    }
+    return merged;
+}

package/dist/_internal/shared/features/orders/dispute-reasons.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Dispute KINDS and the gate each one must pass.
+ *
+ * ## Why the kind is closed and the reason list is not
+ *
+ * The owner's two rules are policy:
+ *
+ * > An item dispute can only be raised after the order was received. A
+ * > "not reached" dispute is allowed once the ETD is more than 3 days past.
+ *
+ * A gate cannot branch on a user-created string. `return-reasons.ts` already
+ * makes this argument in its own header — *"'No returns, unless the buyer
+ * didn't get what they paid for' is not a policy that can be enforced against
+ * a free-text box: it needs a machine-readable statement of what went
+ * wrong"* — and it applies with more force here, because these two gates are
+ * MUTUALLY EXCLUSIVE.
+ *
+ * So there are two levels:
+ *
+ * 1. **`DisputeKind` — closed, here, two values.** It picks the gate.
+ * 2. **`disputeReasons` — a staff-creatable Firestore collection.** Every row
+ *    carries a `kind`, so a new reason inherits an existing gate and cannot
+ *    invent one. That list is for triage and analytics, never for policy.
+ *
+ * ## What this replaces
+ *
+ * `raiseOrderDisputeAction` took `reason: string` and checked only that it was
+ * non-empty. So today a buyer can file "it never arrived" on an order that was
+ * delivered last week, and "it arrived damaged" on one still in transit — both
+ * nonsense, both accepted, and both raising a `severity: "error"` fraud-category
+ * admin alert. The gate is the point of this file.
+ */
+export declare const DISPUTE_KIND: readonly ["item", "not_reached"];
+export type DisputeKind = (typeof DISPUTE_KIND)[number];
+/**
+ * 🛑 `Record<DisputeKind, string>`, so a third kind is a COMPILE error here
+ * rather than a dispute that renders `undefined` and passes no gate.
+ */
+export declare const DISPUTE_KIND_LABEL: Record<DisputeKind, string>;
+export declare function isDisputeKind(value: unknown): value is DisputeKind;
+/**
+ * How long after dispatch a parcel is ASSUMED to have been deliverable, when
+ * the courier gave us no estimate.
+ *
+ * 🛑 This exists so the `not_reached` gate is reachable AT ALL. There is no
+ * courier ETD on an order today: nothing platform-books (`createShipment` has
+ * zero callers), and a self-shipping seller types a tracking number with no
+ * estimate attached. Gate solely on a stored ETD and no buyer could ever file
+ * a non-delivery dispute — a gate nobody can pass is the same as no feature.
+ *
+ * Published through `PublishedValueKey` so the policy page and this gate
+ * cannot disagree (Phase 9).
+ */
+export declare const DISPUTE_TRANSIT_WINDOW_DAYS = 7;
+/**
+ * The owner's "more than 3 days" grace, measured from the ETD.
+ *
+ * Separate from the transit window on purpose: one is "when should it have
+ * arrived", the other is "how long after that before we believe it is lost".
+ * Folding them into a single 10 would make neither number explicable on a
+ * policy page.
+ */
+export declare const DISPUTE_NOT_REACHED_GRACE_DAYS = 3;
+/** Fields the gates read. Narrow, so a caller need not hold a whole order. */
+export interface DisputeGateOrder {
+    deliveryDate?: Date | null;
+    completedAt?: Date | null;
+    shippingDate?: Date | null;
+    estimatedDeliveryDate?: Date | null;
+}
+export type DisputeGateResult = {
+    allowed: true;
+}
+/** `message` is buyer-facing and must name the next action, not just refuse. */
+ | {
+    allowed: false;
+    message: string;
+};
+/**
+ * The effective ETD, and WHY we think so.
+ *
+ * Exported because the buyer-facing form needs to show the date they can file
+ * from — telling someone "not yet" without saying when is a dead end.
+ */
+export declare function resolveDisputeEtd(order: DisputeGateOrder, transitWindowDays?: number): {
+    etd: Date;
+    source: "courier" | "assumed";
+} | null;
+/** The date from which a `not_reached` dispute becomes filable. */
+export declare function disputeNotReachedFilableFrom(order: DisputeGateOrder, graceDays?: number): Date | null;
+/**
+ * 🛑 `Record<DisputeKind, …>`. A third kind cannot be added without deciding
+ * what gates it — which is the whole reason the kind is closed.
+ */
+export declare const DISPUTE_GATE: Record<DisputeKind, (order: DisputeGateOrder, now?: Date) => DisputeGateResult>;
+/**
+ * Convenience wrapper so callers do not index the record by hand.
+ *
+ * 🛑 Takes the NARROW `DisputeGateOrder`, and an `OrderDocument` satisfies it
+ * structurally — so no adapter is needed and none should be added.
+ *
+ * A first draft had a `toDisputeGateOrder(order: OrderDocument)` helper, which
+ * meant this module imported the order schema while the order schema imports
+ * `DisputeKind` from here. That cycle is type-only and therefore erased, so it
+ * would have compiled and run — but it is also entirely avoidable, and a
+ * module that defines a policy should not depend on the document the policy is
+ * applied to. `return-reasons.ts` beside it has no imports at all for the same
+ * reason.
+ *
+ * Nothing leaks by passing the whole order in: what crosses back out is a
+ * `DisputeGateResult`, never the document (Root Cause #70).
+ */
+export declare function checkDisputeGate(kind: DisputeKind, order: DisputeGateOrder, now?: Date): DisputeGateResult;

package/dist/_internal/shared/features/orders/dispute-reasons.js

@@ -0,0 +1,181 @@
+/**
+ * Dispute KINDS and the gate each one must pass.
+ *
+ * ## Why the kind is closed and the reason list is not
+ *
+ * The owner's two rules are policy:
+ *
+ * > An item dispute can only be raised after the order was received. A
+ * > "not reached" dispute is allowed once the ETD is more than 3 days past.
+ *
+ * A gate cannot branch on a user-created string. `return-reasons.ts` already
+ * makes this argument in its own header — *"'No returns, unless the buyer
+ * didn't get what they paid for' is not a policy that can be enforced against
+ * a free-text box: it needs a machine-readable statement of what went
+ * wrong"* — and it applies with more force here, because these two gates are
+ * MUTUALLY EXCLUSIVE.
+ *
+ * So there are two levels:
+ *
+ * 1. **`DisputeKind` — closed, here, two values.** It picks the gate.
+ * 2. **`disputeReasons` — a staff-creatable Firestore collection.** Every row
+ *    carries a `kind`, so a new reason inherits an existing gate and cannot
+ *    invent one. That list is for triage and analytics, never for policy.
+ *
+ * ## What this replaces
+ *
+ * `raiseOrderDisputeAction` took `reason: string` and checked only that it was
+ * non-empty. So today a buyer can file "it never arrived" on an order that was
+ * delivered last week, and "it arrived damaged" on one still in transit — both
+ * nonsense, both accepted, and both raising a `severity: "error"` fraud-category
+ * admin alert. The gate is the point of this file.
+ */
+export const DISPUTE_KIND = ["item", "not_reached"];
+/**
+ * 🛑 `Record<DisputeKind, string>`, so a third kind is a COMPILE error here
+ * rather than a dispute that renders `undefined` and passes no gate.
+ */
+export const DISPUTE_KIND_LABEL = {
+    item: "There's a problem with what I received",
+    not_reached: "My order hasn't arrived",
+};
+export function isDisputeKind(value) {
+    return typeof value === "string" && DISPUTE_KIND.includes(value);
+}
+/**
+ * How long after dispatch a parcel is ASSUMED to have been deliverable, when
+ * the courier gave us no estimate.
+ *
+ * 🛑 This exists so the `not_reached` gate is reachable AT ALL. There is no
+ * courier ETD on an order today: nothing platform-books (`createShipment` has
+ * zero callers), and a self-shipping seller types a tracking number with no
+ * estimate attached. Gate solely on a stored ETD and no buyer could ever file
+ * a non-delivery dispute — a gate nobody can pass is the same as no feature.
+ *
+ * Published through `PublishedValueKey` so the policy page and this gate
+ * cannot disagree (Phase 9).
+ */
+export const DISPUTE_TRANSIT_WINDOW_DAYS = 7;
+/**
+ * The owner's "more than 3 days" grace, measured from the ETD.
+ *
+ * Separate from the transit window on purpose: one is "when should it have
+ * arrived", the other is "how long after that before we believe it is lost".
+ * Folding them into a single 10 would make neither number explicable on a
+ * policy page.
+ */
+export const DISPUTE_NOT_REACHED_GRACE_DAYS = 3;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function asDate(v) {
+    if (!v)
+        return null;
+    const d = v instanceof Date ? v : new Date(v);
+    return Number.isFinite(d.getTime()) ? d : null;
+}
+function fmt(d) {
+    return d.toLocaleDateString("en-IN", { day: "numeric", month: "short", year: "numeric" });
+}
+/**
+ * The effective ETD, and WHY we think so.
+ *
+ * Exported because the buyer-facing form needs to show the date they can file
+ * from — telling someone "not yet" without saying when is a dead end.
+ */
+export function resolveDisputeEtd(order, transitWindowDays = DISPUTE_TRANSIT_WINDOW_DAYS) {
+    const courier = asDate(order.estimatedDeliveryDate);
+    if (courier)
+        return { etd: courier, source: "courier" };
+    const shipped = asDate(order.shippingDate);
+    if (shipped) {
+        return { etd: new Date(shipped.getTime() + transitWindowDays * DAY_MS), source: "assumed" };
+    }
+    return null;
+}
+/** The date from which a `not_reached` dispute becomes filable. */
+export function disputeNotReachedFilableFrom(order, graceDays = DISPUTE_NOT_REACHED_GRACE_DAYS) {
+    const resolved = resolveDisputeEtd(order);
+    if (!resolved)
+        return null;
+    return new Date(resolved.etd.getTime() + graceDays * DAY_MS);
+}
+/**
+ * 🛑 `Record<DisputeKind, …>`. A third kind cannot be added without deciding
+ * what gates it — which is the whole reason the kind is closed.
+ */
+export const DISPUTE_GATE = {
+    /**
+     * You cannot judge an item you have not seen.
+     *
+     * `completedAt` counts as well as `deliveryDate`: a buyer who pressed "Mark
+     * complete" has told us they received it, and refusing them because no
+     * courier scan landed would be refusing the more reliable signal of the two.
+     */
+    item: (order) => {
+        if (asDate(order.deliveryDate) || asDate(order.completedAt))
+            return { allowed: true };
+        return {
+            allowed: false,
+            message: "You can report a problem with an item once it arrives. If it hasn't arrived, raise a delivery issue instead.",
+        };
+    },
+    /**
+     * Only valid BEFORE receipt, and only once the parcel is genuinely late.
+     *
+     * Three refusals, each pointing somewhere:
+     *  - delivered → the wrong kind; offer the item route or a return.
+     *  - never dispatched → not a courier problem at all. That is the
+     *    `seller-dispatch` obligation's job, and it is already running.
+     *  - too early → say the date, not just "not yet".
+     */
+    not_reached: (order, now = new Date()) => {
+        const delivered = asDate(order.deliveryDate);
+        if (delivered) {
+            return {
+                allowed: false,
+                message: `This order was marked delivered on ${fmt(delivered)}. If something is wrong with what arrived, report a problem with the item instead.`,
+            };
+        }
+        if (!asDate(order.shippingDate) && !asDate(order.estimatedDeliveryDate)) {
+            return {
+                allowed: false,
+                message: "This order hasn't been dispatched yet, so there's nothing in transit to chase. We already track late dispatch and will act on it without you needing to do anything.",
+            };
+        }
+        const filableFrom = disputeNotReachedFilableFrom(order);
+        if (!filableFrom) {
+            // Unreachable given the check above; kept rather than asserted, because
+            // a thrown non-null assertion here would be a 500 on a buyer action.
+            return {
+                allowed: false,
+                message: "We can't work out an expected delivery date for this order yet. Contact support.",
+            };
+        }
+        if (now.getTime() < filableFrom.getTime()) {
+            return {
+                allowed: false,
+                message: `It's still within the expected delivery window. If it hasn't arrived by ${fmt(filableFrom)}, you can raise a delivery issue then.`,
+            };
+        }
+        return { allowed: true };
+    },
+};
+/**
+ * Convenience wrapper so callers do not index the record by hand.
+ *
+ * 🛑 Takes the NARROW `DisputeGateOrder`, and an `OrderDocument` satisfies it
+ * structurally — so no adapter is needed and none should be added.
+ *
+ * A first draft had a `toDisputeGateOrder(order: OrderDocument)` helper, which
+ * meant this module imported the order schema while the order schema imports
+ * `DisputeKind` from here. That cycle is type-only and therefore erased, so it
+ * would have compiled and run — but it is also entirely avoidable, and a
+ * module that defines a policy should not depend on the document the policy is
+ * applied to. `return-reasons.ts` beside it has no imports at all for the same
+ * reason.
+ *
+ * Nothing leaks by passing the whole order in: what crosses back out is a
+ * `DisputeGateResult`, never the document (Root Cause #70).
+ */
+export function checkDisputeGate(kind, order, now) {
+    return DISPUTE_GATE[kind](order, now);
+}

package/dist/_internal/shared/features/orders/refund-copy.d.ts

@@ -35,7 +35,7 @@ export declare const REFUND_COPY: {
         readonly reasonSelectPlaceholder: "Choose a reason";
         readonly reasonNoteLabel: "Anything else we should know? (optional)";
         readonly alreadyRefundedMessage: "A refund has already been processed on this order. No further disputes or refund requests can be filed.";
-        readonly acknowledgments: readonly ["I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.", "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).", "I understand the refund amount may take 5–7 business days to reflect and that platform fees may be non-recoverable."];
+        readonly acknowledgments: readonly ["I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.", "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).", "I understand the refund amount may take {{refundBusinessDaysMin}}–{{refundBusinessDaysMax}} business days to reflect and that platform fees may be non-recoverable."];
     };
     readonly siblingPayments: {
         readonly heading: (count: number) => string;