@mohasinac/appkit 4.62.0 → 4.62.1

package/dist/_internal/shared/content/published-values.js

@@ -0,0 +1,198 @@
+/**
+ * Published numbers — ONE definition, rendered everywhere (Phase 9).
+ *
+ * ## 🛑 The problem this solves, stated as a measurement
+ *
+ * The same fact was published in four places with different answers. The
+ * refund timeline appeared as "5–7 business days via Razorpay" (policy page,
+ * naming the wrong gateway), "5–7 business days" (`REFUND_COPY`) and "3–5
+ * business days" (the FAQ). The return window appeared as 7 days, 2 days and
+ * 48 hours. The seller's return-response window is 48 hours in the FAQ and 3
+ * days in `AdminOrdersGuideView`. The offer checkout deadline is 48h in code
+ * and 24h in both the FAQ and the seed.
+ *
+ * Four owners, nothing reconciling them, and one of the four — the FAQ — is
+ * **seeded into Firestore and then admin-editable**, so a number quoted there
+ * drifts *after* deployment with no audit able to see it.
+ *
+ * ## 🛑 So copy carries TOKENS, and the token resolves at render time
+ *
+ * `{{returnWindowDays}}` in an FAQ answer is a promise that cannot drift: the
+ * FAQ is still admin-editable, but the NUMBER inside it comes from here. An
+ * admin can rewrite the sentence and cannot contradict the code.
+ *
+ * ## 🛑 This is NOT a settings group, and must not become one
+ *
+ * Nothing here is admin-editable. These are the values the CODE enforces —
+ * `ORDER_RETURN_WINDOW_MS`, the obligation policies, `LANE_CHECKOUT_WINDOW_MS`
+ * — surfaced for rendering. An editable copy of an enforced constant is two
+ * sources of truth with a settings UI making the wrong one look
+ * authoritative, which is the 18-dead-settings pattern (D28/D44/D57/D60)
+ * arriving from the opposite direction: not a control that does nothing, but a
+ * control that appears to do something the code ignores.
+ *
+ * Where a value genuinely IS configurable, the entry derives it from the
+ * setting rather than restating it — see `resolvePublishedValues`.
+ */
+/*
+ * 🛑 Every import here is the thing that ENFORCES the value, not a mirror of
+ * it. That is what makes "the code wins" structural rather than a convention
+ * somebody has to remember — and it is why there is no literal for the offer
+ * deadline or the claim windows even though both appear in published copy.
+ */
+import { OBLIGATION_POLICIES } from "../../../features/obligations/constants/policies.js";
+import { POINTS_EARN_PERCENT, POINTS_EXPIRY_MONTHS, POINTS_MAX_REDEMPTION_PERCENT, } from "../../../features/points/schemas/firestore.js";
+import { PAYMENT_WINDOW_MINUTES } from "../../../features/orders/constants/payment-window.js";
+import { SALE_PROTECTION_MAX_VALUE } from "../features/shipping/protections.js";
+import { LANE_CHECKOUT_WINDOW_MS } from "../checkout/lanes.js";
+import { DISPUTE_TRANSIT_WINDOW_DAYS, DISPUTE_NOT_REACHED_GRACE_DAYS, } from "../features/orders/dispute-reasons.js";
+/**
+ * The offer checkout deadline, in hours, derived from the constant the lapse
+ * sweep actually enforces.
+ *
+ * 🛑 Decision 23: the CODE wins this contradiction, not the FAQ's 24h and not
+ * the seed's. An offer accepted yesterday carries a 48h `checkoutDeadline`
+ * stored on it, so publishing 24 would be telling a buyer their live offer
+ * expires sooner than it does — and changing the code to match the FAQ would
+ * shorten deadlines already granted.
+ */
+const OFFER_CHECKOUT_HOURS = Math.round(LANE_CHECKOUT_WINDOW_MS.offer / 3600000);
+/*
+ * ── The decided values (decision 23) ─────────────────────────────────────────
+ *
+ * Two live contradictions are resolved by NAMING A WINNER rather than
+ * averaging:
+ *
+ *  - **return-response: 48 hours.** The FAQ wins over
+ *    `AdminOrdersGuideView`'s 3 days, because 48h is the buyer-facing promise
+ *    and the one a buyer has already read.
+ *  - **offer checkout: 48 hours.** The CODE wins over the FAQ's and the seed's
+ *    24h, because changing it would break live offers — an offer accepted
+ *    yesterday has a 48h deadline stored on it.
+ *
+ * Both are derived from the obligation policies and `LANE_CHECKOUT_WINDOW_MS`
+ * below rather than restated here, so "the code wins" is structural.
+ */
+/**
+ * A policy's duration in minutes, whatever unit it declares.
+ *
+ * 🛑 EXHAUSTIVE over `DurationUnit`, which is `minutes | hours | days` — not
+ * the two-case ternary this started as. A `minutes` duration read by a
+ * hours-or-days ternary would be published as that many HOURS: a 15-minute
+ * window rendered to a buyer as 15 hours, with nothing erroring. The
+ * `switch` with no default is what makes a fourth unit a compile error rather
+ * than a silent 60× on a published promise.
+ */
+function policyMinutes(kind) {
+    const d = OBLIGATION_POLICIES[kind].duration;
+    switch (d.unit) {
+        case "minutes":
+            return d.value;
+        case "hours":
+            return d.value * 60;
+        case "days":
+            return d.value * 24 * 60;
+    }
+}
+/**
+ * Days, rounded.
+ *
+ * 🛑 `Math.round`, not `Math.floor`. A 36-hour window floors to 1 day, which
+ * UNDERSTATES a promise to a buyer — and a published window shorter than the
+ * one the code enforces is the direction that generates complaints. Rounding
+ * up-or-nearest can only overstate, which is the safe error. A policy whose
+ * duration does not divide cleanly into days should be published in hours
+ * instead; this is for the ones that do.
+ */
+function policyDays(kind) {
+    return Math.round(policyMinutes(kind) / (24 * 60));
+}
+/** Hours, from the obligation policy that enforces it. */
+function policyHours(kind) {
+    return Math.round(policyMinutes(kind) / 60);
+}
+/**
+ * Resolve every published value.
+ *
+ * 🛑 Settings are read where they exist and the CODE is read where it does
+ * not. A value with no setting is not a gap to fill with a literal — it is a
+ * constant the code enforces, and restating it here is how the four
+ * contradictions above happened in the first place.
+ */
+export function resolvePublishedValues(settings) {
+    return {
+        // ── Windows: every one of these comes from the thing that enforces it ──
+        returnWindowDays: String(settings?.returnWindowDays ?? 7),
+        sellerAcceptDays: String(policyDays("seller-accept")),
+        sellerDispatchBusinessDays: String(policyDays("seller-dispatch")),
+        returnRespondHours: String(policyHours("return-respond")),
+        returnPostDays: String(policyDays("return-post")),
+        offerCheckoutHours: String(OFFER_CHECKOUT_HOURS),
+        paymentWindowMinutes: String(PAYMENT_WINDOW_MINUTES),
+        deliveryConfirmDays: String(policyDays("delivery-confirm")),
+        orderCompleteDays: String(policyDays("order-complete")),
+        shipmentClaimHours: String(policyHours("claim-shipping")),
+        saleClaimHours: String(policyHours("claim-sale")),
+        /*
+         * Straight from the dispute module's own constants, not re-typed here.
+         * Two copies of a published number is the exact drift Phase 9 exists to
+         * remove — the table in this file's own header records a return window
+         * that code said 7, one FAQ said 2 and another said 48 hours.
+         */
+        disputeTransitWindowDays: String(DISPUTE_TRANSIT_WINDOW_DAYS),
+        disputeNotReachedGraceDays: String(DISPUTE_NOT_REACHED_GRACE_DAYS),
+        // ── Money: settings-driven, with the schema defaults as the fallback ───
+        platformFeeMax: formatRupees(settings?.platformFeeMax ?? 10),
+        platformFeePercent: String(settings?.platformFeePercent ?? 2),
+        shipmentProtectionPercent: String(settings?.shipmentProtectionFeePercent ?? 2),
+        shipmentProtectionMin: formatRupees(settings?.shipmentProtectionFeeMin ?? 30),
+        saleProtectionPercent: String(settings?.saleProtectionFeePercent ?? 3),
+        saleProtectionMin: formatRupees(settings?.saleProtectionFeeMin ?? 49),
+        saleProtectionMaxValue: formatRupees(SALE_PROTECTION_MAX_VALUE),
+        codHandlingPercent: String(settings?.codHandlingFeePercent ?? 2),
+        codDepositPercent: String(settings?.codDepositPercent ?? 10),
+        giftWrapFee: formatRupees(settings?.giftWrapFee ?? 0),
+        // ── Points ─────────────────────────────────────────────────────────────
+        pointsEarnPercent: String(POINTS_EARN_PERCENT),
+        pointsMaxRedemptionPercent: String(POINTS_MAX_REDEMPTION_PERCENT),
+        pointsExpiryMonths: String(POINTS_EXPIRY_MONTHS),
+        // ── Refunds ────────────────────────────────────────────────────────────
+        /*
+         * 🛑 The gateway's own processing time, and the ONE value here that no
+         * code enforces — so it is a literal, and that is stated rather than
+         * hidden. It is also where the three-way contradiction lived (5–7 / 5–7 /
+         * 3–5), which is the argument for putting it here at all: a number nothing
+         * enforces is exactly the one that drifts.
+         *
+         * 🛑 And the published copy must NOT name the gateway. The policy page
+         * said "via Razorpay" while payment ran through PhonePe, and it will be
+         * wrong again the next time a provider changes — a fact about our vendor
+         * is not a fact the buyer needs.
+         */
+        refundBusinessDaysMin: "5",
+        refundBusinessDaysMax: "7",
+    };
+}
+/**
+ * Replace every `{{token}}` in a string.
+ *
+ * 🛑 An UNKNOWN token is left verbatim, never blanked. A blanked token reads
+ * as a sentence with a word missing — which looks like clumsy copy and nobody
+ * reports — while a visible `{{returnWindowDayz}}` on a live page is reported
+ * within minutes. Failing loudly is the whole point of a token system whose
+ * copy is admin-editable.
+ */
+export function resolvePublishedCopy(text, values) {
+    return text.replace(/\{\{(\w+)\}\}/g, (whole, key) => {
+        const resolved = values[key];
+        return resolved ?? whole;
+    });
+}
+/** `₹10`, `₹1,499.50` — no trailing `.00` on a whole rupee figure. */
+function formatRupees(amount) {
+    const whole = Number.isInteger(amount);
+    return `₹${amount.toLocaleString("en-IN", {
+        minimumFractionDigits: whole ? 0 : 2,
+        maximumFractionDigits: 2,
+    })}`;
+}

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;