@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/shared/content/disclaimers.js

@@ -0,0 +1,217 @@
+/**
+ * Disclaimers — one registry, rendered by `<Disclaimer id>` (Phase 12).
+ *
+ * ## 🛑 Why a registry and not a sentence per surface
+ *
+ * Same failure mode as the published numbers in Phase 9: if each surface
+ * writes its own, they drift, and **the legally material ones end up
+ * weakest** — because the surface that most needs a careful disclaimer is
+ * usually the one whose author was busiest. The scam registry is the example:
+ * naming a person a scammer is defamation exposure, and it had no disclaimer
+ * at all.
+ *
+ * ## The three rules every entry obeys
+ *
+ * 1. **Visible BEFORE the decision it qualifies**, not only on a policy page
+ *    reachable from the footer. The protection disclaimer belongs beside the
+ *    checkbox, not in `/refund-policy`.
+ * 2. **It names a LIMIT or an EXCLUSION.** A disclaimer that only says "we
+ *    try our best" qualifies nothing and is worse than none — it reads as
+ *    cover while providing none.
+ * 3. **It AGREES with the code.** Limits render from the constants that
+ *    enforce them (`SALE_PROTECTION_MAX_VALUE`, the claim windows), through
+ *    the same `{{token}}` mechanism as Phase 9, so a constant change updates
+ *    the published terms rather than contradicting them.
+ *
+ * ## 🛑 NOT a cookie-banner blanket
+ *
+ * A disclaimer that appears everywhere is read nowhere. Each entry names the
+ * specific surfaces that need it, and `audit-disclaimer-coverage` checks those
+ * surfaces render one — not that every page does.
+ */
+export const DISCLAIMERS = {
+    /*
+     * ── 🛑 THE DEFAMATION ONE. Read this before editing it ────────────────────
+     *
+     * A scam profile names a real person, with their payment handle and their
+     * phone number, on a public page. That is defamation exposure, and the
+     * registry had NO disclaimer of any kind.
+     *
+     * Four things this text must do, each for a specific reason:
+     *
+     *  1. **Distinguish an ALLEGATION from a verified finding.** The status badge
+     *     already says `pending_review` vs `verified`, but a visitor reads the
+     *     name and the amount, not the badge — so the distinction has to be in
+     *     words.
+     *  2. **State the evidence standard**, because "we checked" is not a standard
+     *     and invites the reader to assume a higher one than we applied.
+     *  3. **Name the removal route.** A person named here needs a way to contest
+     *     it that does not begin with a lawyer, and publishing one is itself part
+     *     of the defence.
+     *  4. 🛑 **Refuse the shared-guilt inference.** `relatedScammerIds` means
+     *     SAME IDENTITY — the same person under another handle — and never
+     *     "similar pattern". A reader who takes it as the latter concludes that
+     *     everyone in a cluster is guilty of everyone else's conduct, which is
+     *     the single most damaging misreading this page permits.
+     */
+    "scam-registry": {
+        heading: "About these reports",
+        body: "These are reports submitted by buyers and sellers, not findings of fact or a legal judgment. " +
+            "A profile marked **under review** is an unverified allegation. A profile marked **verified** means " +
+            "our team has seen supporting evidence — payment records, messages or delivery proof — supplied by the " +
+            "person reporting; it is not a court finding and we are not able to investigate beyond the documents " +
+            "we are shown. " +
+            "Linked profiles indicate the SAME person under another name or handle, and never that separate people " +
+            "are connected to each other's conduct. " +
+            "If you are named here and believe it is wrong, contact us and we will review the report and remove it " +
+            "if it is not supported.",
+        tone: "warning",
+        surfaces: ["ScamProfileView", "ScamRegistryView", "/report"],
+    },
+    /*
+     * Gaming law in India is STATE-SPECIFIC, and the distinction that matters
+     * legally is skill versus chance. The entry names the exclusions rather than
+     * claiming a position we cannot defend in every state.
+     */
+    "prize-draw": {
+        heading: "Prize draw terms",
+        body: "Entry requires a purchase and is void where prohibited by local law. Residents of states that " +
+            "restrict prize draws or games of chance are not eligible, and an entry from such a state will be " +
+            "refunded rather than drawn. Prizes are as described on the listing, are not transferable and cannot " +
+            "be exchanged for cash. The draw is run by {{siteName}} and is not affiliated with any government lottery.",
+        tone: "warning",
+        surfaces: ["PrizeDrawDetailPageView", "/prize-draws", "/lottery", "PrizeRevealModal"],
+    },
+    /*
+     * 🛑 Shown wherever a historical price appears. Collectibles displayed with
+     * past realised prices invite an appreciation inference, and the moment a
+     * buyer treats that as a projection we are giving investment advice we are
+     * not licensed to give.
+     */
+    "not-investment-advice": {
+        body: "Prices shown are past transactions, not a valuation, a projection or a guarantee. Collectibles can " +
+            "fall in value as easily as rise, may be difficult to sell at any price, and {{siteName}} does not provide " +
+            "investment advice. Nothing here should be relied on as a reason to buy.",
+        tone: "legal",
+        surfaces: ["PriceIndexView", "RealisedPriceStrip", "/franchise", "ProductDetailPageView"],
+    },
+    /*
+     * 🛑 Names the SAMPLE, because an index built from four sales reads exactly
+     * like one built from four hundred — and "asked ≠ sold" is the distinction a
+     * seller pricing against it most needs.
+     */
+    "price-index": {
+        body: "Each figure is drawn from a limited number of observed sales over the period shown, and a small " +
+            "sample can move sharply on one unusual transaction. Asking prices are not sale prices: an item " +
+            "listed at a figure may never have sold at it.",
+        tone: "legal",
+        surfaces: ["PriceIndexView", "PriceBandChart"],
+    },
+    "authenticity": {
+        body: "{{siteName}} is not an authentication or grading service. We do not inspect, test or re-grade items, " +
+            "and a grade shown on a listing is the one the seller states a third-party grader assigned. " +
+            "Guidance on spotting a counterfeit is general information, not a verification of any particular item.",
+        tone: "legal",
+        surfaces: ["/spot-a-fake", "ProductDetailPageView", "authenticityKnowledge"],
+    },
+    /*
+     * 🛑 **"Not insurance" is the load-bearing phrase.** There is no insurer —
+     * this is our own cover, funded by us, and calling it insurance would be a
+     * regulatory misstatement as well as a false one.
+     *
+     * Every limit renders from the constant that enforces it, so a change to
+     * `SALE_PROTECTION_MAX_VALUE` or a claim window updates this text rather
+     * than contradicting it.
+     */
+    "protection-cover": {
+        heading: "What protection covers",
+        body: "Buyer protection is cover provided by {{siteName}}. It is **not insurance** and there is no insurer. " +
+            "Shipment protection covers loss or damage in transit and must be claimed within " +
+            "{{shipmentClaimHours}} hours of delivery. Sale protection covers an item up to " +
+            "{{saleProtectionMaxValue}} and must be claimed within {{saleClaimHours}} hours of delivery. " +
+            "Neither covers a change of mind, an item sold as final sale, or a claim made after its window has " +
+            "closed.",
+        tone: "legal",
+        surfaces: ["StoreAddonsPicker", "/fees", "/refund-policy", "ProtectionClaimForm"],
+    },
+    /*
+     * 🛑 "Management figures, not audited accounts" — and the GSTR-1 export is
+     * the INPUT to a filing, never a filing. Implying a return had been filed
+     * when it had not is the most consequential thing this product could say.
+     */
+    "accounting-output": {
+        body: "These are management figures produced from this platform's own records. They are not audited " +
+            "accounts and have not been reviewed by an accountant. The GSTR-1 export is a draft for your " +
+            "accountant to check and use — nothing here is filed with any tax authority, and {{siteName}} has no " +
+            "connection to the GST portal.",
+        tone: "warning",
+        surfaces: ["AdminInvoicingView", "AdminAnalyticsView", "ProfitLossView", "TrialBalanceView"],
+    },
+    "live-items": {
+        heading: "Live item terms",
+        body: "Live animals and plants ship only where law permits, and some species cannot be sent across state " +
+            "or international borders at all — CITES-listed species in particular. The buyer is responsible for " +
+            "holding any licence their own jurisdiction requires. No guarantee of health, size, sex or lifespan " +
+            "is given beyond what the listing states, and a live item cannot be returned for a change of mind.",
+        tone: "warning",
+        surfaces: ["LiveItemDetailPageView", "/live"],
+    },
+    "pre-order": {
+        body: "A release date on a pre-order is the manufacturer's estimate and can move or be cancelled by them. " +
+            "Your deposit is refundable until the item ships; the remaining balance is charged when it is ready " +
+            "to dispatch, against the terms shown when you placed the pre-order.",
+        tone: "legal",
+        surfaces: ["PreOrderDetailPageView", "/pre-orders"],
+    },
+    "auction-binding": {
+        body: "A bid is a binding offer to buy at that price and cannot be withdrawn. If the reserve price is not " +
+            "met the item does not sell, even if yours was the highest bid. Winning starts a payment window — " +
+            "miss it and the win is forfeited.",
+        tone: "warning",
+        surfaces: ["PlaceBidForm", "AuctionDetailPageView", "/auctions"],
+    },
+    "emi": {
+        body: "EMI adds a surcharge to the order total, shown before you pay. The instalment plan is between you " +
+            "and {{siteName}} rather than a bank, and a missed instalment may suspend access to the order and is " +
+            "recoverable as a debt.",
+        tone: "legal",
+        surfaces: ["CheckoutRouteClient", "/fees", "EmiScheduleTable"],
+    },
+    "delivery-estimate": {
+        body: "Delivery dates are estimates from the courier, not guarantees, and can be affected by weather, " +
+            "strikes and customs. A late delivery is not by itself grounds for a refund.",
+        tone: "legal",
+        surfaces: ["CheckoutRouteClient", "ProductDetailPageView", "OrderTrackView"],
+    },
+    "user-content": {
+        body: "Reviews, catalogue entries and comments are the opinions of the people who wrote them, not " +
+            "{{siteName}}'s. We remove content that breaks our rules when it is reported, but we do not verify every " +
+            "claim made in it.",
+        tone: "legal",
+        surfaces: ["ReviewsList", "ReviewDetailShell", "PublicProfileView", "BlogPostView"],
+    },
+    "tax-computation": {
+        body: "GST shown is computed from the information available to us at the time of supply — the item's tax " +
+            "code and the delivery address you gave. Your own tax position, including any input credit, is yours " +
+            "to determine with your accountant.",
+        tone: "legal",
+        surfaces: ["InvoicePageView", "/gst", "OrderSummary"],
+    },
+    /*
+     * 🛑 The Phase 5b obligations act on timers — cancelling orders, approving
+     * returns, completing orders. A buyer whose order was cancelled by a sweep
+     * must be TOLD it was automatic and how to contest it; otherwise the first
+     * they know is a refund they did not request, which reads as us losing their
+     * order.
+     */
+    "automated-decision": {
+        body: "This was done automatically, by a time limit rather than by a person. If you think it was wrong, " +
+            "reply to this notification or open a support ticket and a person will look at it.",
+        tone: "legal",
+        surfaces: [
+            "obligation notifications",
+            "OrderStatusTimeline",
+            "AdminObligationsView",
+        ],
+    },
+};

package/dist/_internal/shared/content/published-values.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 token that may appear in published copy.
+ *
+ * 🛑 A `Record` over this union, so a token added to the type without a value
+ * is a COMPILE error — and a token used in copy that is not in the union is
+ * caught by `resolvePublishedCopy` leaving it visibly unresolved rather than
+ * silently blanking it. Both directions matter: a blanked token reads as a
+ * sentence with a word missing, which nobody reports, while `{{wrongKey}}` on
+ * a live page gets reported in minutes.
+ */
+export type PublishedValueKey = "returnWindowDays" | "sellerAcceptDays" | "sellerDispatchBusinessDays" | "returnRespondHours" | "returnPostDays" | "offerCheckoutHours" | "paymentWindowMinutes" | "deliveryConfirmDays" | "orderCompleteDays" | "shipmentClaimHours" | "saleClaimHours" | "disputeTransitWindowDays" | "disputeNotReachedGraceDays" | "platformFeeMax" | "platformFeePercent" | "shipmentProtectionPercent" | "shipmentProtectionMin" | "saleProtectionPercent" | "saleProtectionMin" | "saleProtectionMaxValue" | "codHandlingPercent" | "codDepositPercent" | "giftWrapFee" | "pointsEarnPercent" | "pointsMaxRedemptionPercent" | "pointsExpiryMonths" | "refundBusinessDaysMin" | "refundBusinessDaysMax" | "siteName";
+export type PublishedValues = Record<PublishedValueKey, string>;
+/**
+ * The settings this registry reads, where a value genuinely is configurable.
+ *
+ * Deliberately a narrow shape rather than `SiteSettingsDocument`: this module
+ * is imported by client components to render copy, and widening it to the
+ * whole settings document would invite a caller to pass one in — which is Root
+ * Cause #70's leak (a raw document reaching a Client Component prop, where
+ * TypeScript's structural typing strips nothing at runtime).
+ */
+export interface PublishedValueSettings {
+    /**
+     * The operator's display name, for the disclaimers that name who is making
+     * the statement. Falls back to `SITE_CONFIG.brand.name`.
+     */
+    siteName?: string;
+    platformFeeMax?: number;
+    platformFeePercent?: number;
+    shipmentProtectionFeePercent?: number;
+    shipmentProtectionFeeMin?: number;
+    saleProtectionFeePercent?: number;
+    saleProtectionFeeMin?: number;
+    codHandlingFeePercent?: number;
+    codDepositPercent?: number;
+    giftWrapFee?: number;
+    returnWindowDays?: number;
+}
+/**
+ * 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 declare function resolvePublishedValues(settings?: PublishedValueSettings): PublishedValues;
+/**
+ * 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 declare function resolvePublishedCopy(text: string, values: PublishedValues): string;

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

@@ -0,0 +1,206 @@
+/**
+ * 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 { SITE_CONFIG } from "../../../core/site-config.js";
+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",
+        /*
+         * `SITE_CONFIG.brand.name` is appkit's own neutral default ("App") until a
+         * consumer overrides it, which is exactly the right failure mode here: a
+         * fork that forgets to configure its brand publishes a visibly generic
+         * disclaimer rather than silently attributing its legal statements to us.
+         */
+        siteName: settings?.siteName ?? SITE_CONFIG.brand.name,
+    };
+}
+/**
+ * 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,139 @@
+/**
+ * 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.
+ */
+/**
+ * The settings groups an integration switch may write, and nothing else.
+ *
+ * 🛑 Deliberately a LOCAL shape rather than `Partial<SiteSettingsDocument>`.
+ * This module sits in `_internal/shared` and the settings schema pulls in the
+ * whole admin feature; importing it here to describe four booleans would add
+ * an edge `audit-import-cycles` exists to keep out. The four groups below are
+ * the entire surface these two functions write, so a local type is both
+ * narrower and honest.
+ *
+ * It replaces `Record<string, unknown>`, which said "some object" and
+ * therefore type-checked a patch that wrote a misspelled group or the wrong
+ * value shape — on a function whose whole job is flipping production kill
+ * switches.
+ */
+export interface IntegrationPatch {
+    payment?: {
+        razorpayEnabled?: boolean;
+        phonepeEnabled?: boolean;
+    };
+    messaging?: {
+        emailEnabled: boolean;
+    };
+    shipping?: {
+        provider: "manual" | "shiprocket";
+    };
+    support?: {
+        enabled: boolean;
+    };
+}
+export declare function integrationPatch(id: IntegrationId, enabled: boolean): IntegrationPatch;
+/** Every patch for a bulk enable/disable, merged into one object. */
+export declare function allIntegrationsPatch(enabled: boolean): IntegrationPatch;