@mohasinac/appkit 4.62.0 → 4.63.0

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

@@ -0,0 +1,263 @@
+/**
+ * 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 },
+    };
+}
+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);
+        /*
+         * Merged per GROUP, so two integrations writing different fields of the
+         * same group (none do today, but `payment` already carries two flags)
+         * cannot clobber each other.
+         *
+         * Spelled out per key rather than via `Object.entries`, which erased the
+         * types this patch now carries — and listing the groups is also a forcing
+         * function: a fifth integration writing a NEW group does not silently
+         * vanish from the bulk switch, it fails to merge until someone adds the
+         * line. Same argument as the exhaustive `never` in `integrationPatch`.
+         */
+        if (patch.payment)
+            merged.payment = { ...merged.payment, ...patch.payment };
+        if (patch.messaging)
+            merged.messaging = { ...merged.messaging, ...patch.messaging };
+        if (patch.shipping)
+            merged.shipping = { ...merged.shipping, ...patch.shipping };
+        if (patch.support)
+            merged.support = { ...merged.support, ...patch.support };
+    }
+    return merged;
+}

package/dist/_internal/shared/features/dashboard/hub-sections.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Dashboard hub sections — one hub per nav group, derived from the nav itself.
+ *
+ * ## What a hub is
+ *
+ * Each dashboard (`/admin`, `/store`, `/user`) has a landing page listing its
+ * SECTIONS, and each section has a hub listing the SCREENS in it. Twelve admin
+ * sections, six store, four user — 22 hubs, served by three dynamic routes
+ * (`/{portal}/sections/[section]`), because a hub has no content of its own
+ * beyond the group it names.
+ *
+ * ## 🛑 Everything here is DERIVED. There is no second list.
+ *
+ * `ADMIN_NAV_GROUPS` / `STORE_NAV_GROUPS` / `USER_NAV_GROUPS` already carry a
+ * title per group and, per item, an href, a label, a `description` ("what this
+ * screen is FOR, in the user's words") and `keywords`. That is the whole card:
+ * a hub needs no copy of its own, and must not have any.
+ *
+ * The alternative was a hand-written array of 22 section descriptors, which is
+ * Root Cause #61 pre-written — ten independent enumerations of one union, nine
+ * of which silently did not grow. `AdminGuideHubView` is the live warning: it
+ * is already a hub, it is the visual pattern this follows, and it hand-writes
+ * its card list, so a guide added to the nav does not appear on it.
+ *
+ * ## The slug
+ *
+ * `hubSectionSlug` is the only mapping between a group title and its URL. It is
+ * lossy by construction ("Trust & Safety" → `trust-safety`), so two titles
+ * CAN collide — and a collision makes one hub permanently unreachable while
+ * the other answers for both, with nothing erroring.
+ *
+ * That is checked statically rather than defended at runtime:
+ * `audit-dashboard-hub-coverage` fails on a duplicate slug within a portal. A
+ * runtime throw would turn a naming choice into a 500 on a live dashboard, and
+ * a silent de-dupe would hide exactly the state the audit exists to name.
+ */
+import type { SidebarNavGroup, SidebarNavItem } from "../layout/types";
+/** One section of a dashboard: a nav group plus the slug its hub answers on. */
+export interface DashboardHubSection {
+    /** URL segment — derived from `title`, never authored. */
+    slug: string;
+    /** The group's own title, rendered verbatim as the section heading. */
+    title: string;
+    /** The screens in this section, already permission-filtered by the caller. */
+    items: SidebarNavItem[];
+}
+/**
+ * A group title as a URL segment.
+ *
+ * Deliberately the same shape as `navItemId`'s path normalisation — lower-case,
+ * non-alphanumerics collapsed to a single hyphen, no leading or trailing
+ * hyphen. `&` and `/` carry no meaning in a slug, so "Trust & Safety" and
+ * "Orders & Reviews" become `trust-safety` and `orders-reviews`.
+ */
+export declare function hubSectionSlug(title: string): string;
+/**
+ * Every section of a dashboard, in nav order.
+ *
+ * 🛑 Pass groups that are ALREADY permission-filtered (`filterNavGroups`). This
+ * function deliberately applies no filter of its own: two places deciding
+ * visibility is how a hub ends up offering a card the sidebar hides, and the
+ * sidebar's answer is the one the route guards agree with.
+ */
+export declare function hubSections(groups: readonly SidebarNavGroup[]): DashboardHubSection[];
+/**
+ * The section a `[section]` route segment names, or `undefined`.
+ *
+ * `undefined` is the caller's cue to `notFound()`. It must not fall back to the
+ * first section: a mistyped or retired slug would then render a real page under
+ * the wrong heading, which is indistinguishable from a working link.
+ */
+export declare function findHubSection(groups: readonly SidebarNavGroup[], slug: string): DashboardHubSection | undefined;

package/dist/_internal/shared/features/dashboard/hub-sections.js

@@ -0,0 +1,75 @@
+/**
+ * Dashboard hub sections — one hub per nav group, derived from the nav itself.
+ *
+ * ## What a hub is
+ *
+ * Each dashboard (`/admin`, `/store`, `/user`) has a landing page listing its
+ * SECTIONS, and each section has a hub listing the SCREENS in it. Twelve admin
+ * sections, six store, four user — 22 hubs, served by three dynamic routes
+ * (`/{portal}/sections/[section]`), because a hub has no content of its own
+ * beyond the group it names.
+ *
+ * ## 🛑 Everything here is DERIVED. There is no second list.
+ *
+ * `ADMIN_NAV_GROUPS` / `STORE_NAV_GROUPS` / `USER_NAV_GROUPS` already carry a
+ * title per group and, per item, an href, a label, a `description` ("what this
+ * screen is FOR, in the user's words") and `keywords`. That is the whole card:
+ * a hub needs no copy of its own, and must not have any.
+ *
+ * The alternative was a hand-written array of 22 section descriptors, which is
+ * Root Cause #61 pre-written — ten independent enumerations of one union, nine
+ * of which silently did not grow. `AdminGuideHubView` is the live warning: it
+ * is already a hub, it is the visual pattern this follows, and it hand-writes
+ * its card list, so a guide added to the nav does not appear on it.
+ *
+ * ## The slug
+ *
+ * `hubSectionSlug` is the only mapping between a group title and its URL. It is
+ * lossy by construction ("Trust & Safety" → `trust-safety`), so two titles
+ * CAN collide — and a collision makes one hub permanently unreachable while
+ * the other answers for both, with nothing erroring.
+ *
+ * That is checked statically rather than defended at runtime:
+ * `audit-dashboard-hub-coverage` fails on a duplicate slug within a portal. A
+ * runtime throw would turn a naming choice into a 500 on a live dashboard, and
+ * a silent de-dupe would hide exactly the state the audit exists to name.
+ */
+/**
+ * A group title as a URL segment.
+ *
+ * Deliberately the same shape as `navItemId`'s path normalisation — lower-case,
+ * non-alphanumerics collapsed to a single hyphen, no leading or trailing
+ * hyphen. `&` and `/` carry no meaning in a slug, so "Trust & Safety" and
+ * "Orders & Reviews" become `trust-safety` and `orders-reviews`.
+ */
+export function hubSectionSlug(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Every section of a dashboard, in nav order.
+ *
+ * 🛑 Pass groups that are ALREADY permission-filtered (`filterNavGroups`). This
+ * function deliberately applies no filter of its own: two places deciding
+ * visibility is how a hub ends up offering a card the sidebar hides, and the
+ * sidebar's answer is the one the route guards agree with.
+ */
+export function hubSections(groups) {
+    return groups.map((group) => ({
+        slug: hubSectionSlug(group.title),
+        title: group.title,
+        items: group.items,
+    }));
+}
+/**
+ * The section a `[section]` route segment names, or `undefined`.
+ *
+ * `undefined` is the caller's cue to `notFound()`. It must not fall back to the
+ * first section: a mistyped or retired slug would then render a real page under
+ * the wrong heading, which is indistinguishable from a working link.
+ */
+export function findHubSection(groups, slug) {
+    return hubSections(groups).find((section) => section.slug === slug);
+}

package/dist/_internal/shared/features/emi/choice.d.ts

@@ -0,0 +1,98 @@
+/**
+ * EMI is an OPT-IN ON THE ORDER, not a way of paying.
+ *
+ * 🛑 Until 2026-10-22 it was a sixth `paymentMethod`, and that conflated two
+ * independent decisions: *do I want to spread this over months* and *how does
+ * the money reach you*. A buyer who wanted instalments had, by picking "Pay in
+ * EMI", also implicitly chosen the tender — and the tender they got was the
+ * manual bank/UPI proof flow, because `MANUAL_PAYMENT_METHODS` is
+ * `["cash","upi_manual","emi"]` and `hasPaymentWindow` tested for `EMI`
+ * alongside the other two. Nothing in the UI said so.
+ *
+ * The two axes are now separate: `emiOptIn` + `emiTenureMonths` describe the
+ * arrangement, `paymentMethod` describes the tender for the token. Everything
+ * downstream — the schedule, the surcharge, the order fields — keys on
+ * `emiOptIn`, so an EMI order can be paid online or by hand.
+ *
+ * ── Why the legacy value is MAPPED rather than rejected ────────────────────
+ *
+ * A browser tab opened before this change still posts `paymentMethod: "emi"`.
+ * Mapping it to `{ tender: "upi_manual", emiOptIn: true }` is not a guess: it
+ * is exactly what that request did before, measured at
+ * `actions.ts`'s `hasPaymentWindow` (a 15-minute window plus a displayed UPI
+ * id — i.e. the manual-proof flow) and at `MANUAL_PAYMENT_METHODS`. So the
+ * stale tab keeps behaving identically instead of 400ing at the one moment a
+ * buyer is trying to pay.
+ *
+ * ── Why this returns a RESULT rather than throwing ─────────────────────────
+ *
+ * The same answer has to serve two callers with different jobs: the order
+ * action, which must refuse, and the pricing preview, which must still price
+ * *something* rather than 500 while a buyer fiddles with a radio. A plain
+ * value lets each decide.
+ */
+import type { CheckoutPaymentMethod } from "../checkout/config";
+/** The tender — `emi` is excluded by construction, which is the whole point. */
+export type EmiTender = Exclude<CheckoutPaymentMethod, "emi">;
+export interface EmiChoiceRequest {
+    paymentMethod: CheckoutPaymentMethod;
+    /**
+     * The DURABLE selection, read off `CartDocument.emiPlan`.
+     *
+     * 🛑 Not a request-body field, and that is the point: the online path
+     * decides the capture amount in one request and writes the order in
+     * another, so a body-carried choice cannot be read by both. See the schema
+     * note on `CartDocument.emiPlan`.
+     */
+    cartEmiPlan?: {
+        tenureMonths: number;
+    } | null;
+    /**
+     * Legacy only: a tab opened before 2026-10-22 posts
+     * `paymentMethod: "emi"` plus a tenure in the body, with nothing on the
+     * cart. Honoured so that buyer is not 400'd mid-payment, and ignored
+     * whenever the cart carries a plan.
+     */
+    legacyTenureMonths?: number;
+}
+export interface EmiChoice {
+    paymentMethod: EmiTender;
+    emiOptIn: boolean;
+    /**
+     * 🛑 Set ONLY when `emiOptIn` is true. A tenure left over from a radio the
+     * buyer un-ticked must not reach `computeBuyerEmiQuote`, or they are
+     * surcharged for an arrangement they declined.
+     */
+    emiTenureMonths?: number;
+}
+export type EmiChoiceResult = {
+    ok: true;
+    choice: EmiChoice;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Normalise a checkout request's payment axes. **Every** caller that reads
+ * `paymentMethod` or decides whether to build an EMI schedule must resolve
+ * through this — two copies of "is this an EMI order" is the drift that this
+ * function exists to end (Root Cause #75).
+ */
+/**
+ * The TENDER alone — a pure function of the request, needing no cart.
+ *
+ * Split out because the early checkout guards (is COD enabled, is manual UPI
+ * accepted) run *before* the cart is read and must already be talking about
+ * the real tender. `resolveEmiChoice` calls this, so the legacy mapping has
+ * one definition rather than two that agree today.
+ */
+export declare function emiTenderFor(method: CheckoutPaymentMethod): EmiTender;
+export declare function resolveEmiChoice(request: EmiChoiceRequest): EmiChoiceResult;
+/**
+ * The tenders a buyer may pick while opted in, for disabling a control rather
+ * than letting them pick it and be refused at submit. Derived from the same
+ * map the refusal reads, so the affordance and the rule cannot disagree.
+ */
+export declare function isTenderCompatibleWithEmi(method: EmiTender): boolean;
+/** Why a tender is unavailable while instalments are on. `null` when it is available. */
+export declare function emiTenderBlockReason(method: EmiTender): string | null;

package/dist/_internal/shared/features/emi/choice.js

@@ -0,0 +1,69 @@
+/** The tender a pre-2026-10-22 `paymentMethod: "emi"` request actually got. */
+const EMI_LEGACY_TENDER = "upi_manual";
+/**
+ * Tenders that cannot carry an instalment plan, with the reason stated rather
+ * than the combination silently dropped.
+ *
+ * - `cod` collects the balance at the door; "the balance" is precisely what an
+ *   instalment plan is for. The two describe opposite settlements of the same
+ *   money.
+ * - `admin_bypass` marks an order paid without a payment. The existing order
+ *   writer already nulls every `emi*` field under `adminBypass`, so the
+ *   combination has never produced an EMI order — this refuses it out loud
+ *   instead of producing a plain order that looks like the EMI one the tester
+ *   asked for.
+ */
+const EMI_INCOMPATIBLE = {
+    cod: "Cash on delivery collects the balance when the parcel arrives, so it cannot also be paid in monthly instalments. Pay the token online or by bank/UPI transfer instead.",
+    admin_bypass: "The admin bypass marks an order paid without taking a payment, so there is no token to collect and no instalment plan to start.",
+};
+/**
+ * Normalise a checkout request's payment axes. **Every** caller that reads
+ * `paymentMethod` or decides whether to build an EMI schedule must resolve
+ * through this — two copies of "is this an EMI order" is the drift that this
+ * function exists to end (Root Cause #75).
+ */
+/**
+ * The TENDER alone — a pure function of the request, needing no cart.
+ *
+ * Split out because the early checkout guards (is COD enabled, is manual UPI
+ * accepted) run *before* the cart is read and must already be talking about
+ * the real tender. `resolveEmiChoice` calls this, so the legacy mapping has
+ * one definition rather than two that agree today.
+ */
+export function emiTenderFor(method) {
+    return method === "emi" ? EMI_LEGACY_TENDER : method;
+}
+export function resolveEmiChoice(request) {
+    const legacy = request.paymentMethod === "emi";
+    const paymentMethod = emiTenderFor(request.paymentMethod);
+    /*
+     * The cart WINS. A stale tab's body tenure is a fallback for the one case
+     * where there is nothing on the cart to read — never an override, or a
+     * client could re-price an order the server has already quoted.
+     */
+    const tenureMonths = request.cartEmiPlan?.tenureMonths ?? (legacy ? request.legacyTenureMonths : undefined);
+    const emiOptIn = tenureMonths !== undefined;
+    if (!emiOptIn) {
+        return { ok: true, choice: { paymentMethod, emiOptIn: false } };
+    }
+    const incompatible = EMI_INCOMPATIBLE[paymentMethod];
+    if (incompatible)
+        return { ok: false, reason: incompatible };
+    return {
+        ok: true,
+        choice: { paymentMethod, emiOptIn: true, emiTenureMonths: tenureMonths },
+    };
+}
+/**
+ * The tenders a buyer may pick while opted in, for disabling a control rather
+ * than letting them pick it and be refused at submit. Derived from the same
+ * map the refusal reads, so the affordance and the rule cannot disagree.
+ */
+export function isTenderCompatibleWithEmi(method) {
+    return EMI_INCOMPATIBLE[method] === undefined;
+}
+/** Why a tender is unavailable while instalments are on. `null` when it is available. */
+export function emiTenderBlockReason(method) {
+    return EMI_INCOMPATIBLE[method] ?? null;
+}

package/dist/_internal/shared/features/emi/group.d.ts

@@ -0,0 +1,84 @@
+import { type BuyerEmiQuote, type EmiScheduleResult, type EmiSettings } from "./schedule";
+/** What every caller knows about one seller-group at the moment EMI is priced. */
+export interface GroupEmiInput {
+    /** Already normalised by `resolveEmiChoice` — never derived from a tender. */
+    emiOptIn: boolean;
+    emiTenureMonths?: number;
+    /** The group's GOODS subtotal, before coupon and before any fee. */
+    groupSubtotal: number;
+    /** `StoreDocument.emiEnabled` for this group's seller. */
+    sellerEmiEnabled: boolean;
+}
+/**
+ * The gate, shared so "does EMI apply to this group" is answered identically
+ * everywhere.
+ *
+ * 🛑 Returns a REASON rather than a boolean, because the two callers do
+ * opposite things with it: order creation must refuse (an ineligible EMI order
+ * that silently becomes a full-price order is money the buyer did not agree
+ * to), while the preview must carry on and simply price no surcharge (a
+ * preview that throws blanks the Order Summary while the buyer is still
+ * choosing). A boolean would have forced each to re-derive the reason.
+ */
+export type GroupEmiGate = {
+    applies: true;
+} | {
+    applies: false;
+    reason: "not_opted_in" | "no_tenure" | "no_settings" | string;
+};
+export declare function groupEmiGate(input: GroupEmiInput, settings: Pick<EmiSettings, "enabled" | "minOrderValue"> | null | undefined): GroupEmiGate;
+/**
+ * The buyer-visible quote for one group, or `null` when EMI does not apply.
+ *
+ * For the preview and for the gateway CAPTURE amount — neither needs the
+ * platform/seller surcharge split, and neither should be able to print it.
+ */
+export declare function groupEmiQuote(input: GroupEmiInput, settings: (Pick<EmiSettings, "enabled" | "minOrderValue" | "tokenPercent" | "billingDay" | "surchargePercentPerMonth">) | null | undefined, purchaseDate?: Date): BuyerEmiQuote | null;
+/**
+ * The server-side schedule for one group, including the surcharge split that
+ * is persisted onto the order. For the two order WRITERS only.
+ */
+export declare function groupEmiSchedule(input: GroupEmiInput, settings: EmiSettings | null | undefined, purchaseDate?: Date): EmiScheduleResult | null;
+/**
+ * What is actually collected at checkout: the order total, less any points
+ * tendered, less whatever has been deferred into instalments.
+ *
+ * 🛑 Composes with the points tender rather than replacing it. Both reduce
+ * what is collected and they are independent, so an EMI order part-funded by
+ * points must subtract both — writing `total − remainingBalance` would hand
+ * back the points discount, and `total − pointsApplied` alone is the bug this
+ * function exists to fix. Floored at zero: points can cover at most half an
+ * order, so the sum cannot genuinely go negative, and clamping means a future
+ * change to that cap degrades to "collect nothing" rather than to a refund.
+ */
+export declare function amountDueNow(args: {
+    orderTotal: number;
+    pointsApplied: number;
+    /** `EmiScheduleResult.remainingBalance`, or 0 on a non-EMI order. */
+    emiRemainingBalance: number;
+}): number;
+/**
+ * The `emi*` fields written onto an order document.
+ *
+ * 🛑 One builder for both creation paths. These are eleven fields that have to
+ * be written identically by `createOrderForGroup` and
+ * `createPhonePeGroupOrder`, and the second one carried **none of them** —
+ * every order paid online lost its instalment plan entirely. Two hand-written
+ * copies is the create-vs-create axis of Root Cause #39, and these two
+ * functions have already drifted once before over add-on fees (#65).
+ */
+export declare function emiOrderFields(schedule: EmiScheduleResult | null, emiTenureMonths: number | undefined): {
+    emiEnabled?: true;
+    emiTenureMonths?: number;
+    emiTokenAmount?: number;
+    emiSurchargeAmount?: number;
+    emiSurchargeSellerShare?: number;
+    emiInstallments?: Array<{
+        index: number;
+        dueDate: Date;
+        amount: number;
+        status: "pending";
+    }>;
+    emiRemainingBalance?: number;
+    emiComplete?: false;
+};