@mohasinac/appkit 4.42.18 → 4.44.0

package/dist/_internal/client/features/lottery/LotteryDetailView.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { Stack, Row, Text, Heading, Badge, Section, Container, Div, Anchor, } from "../../../../ui";
 import { MediaImage } from "../../../../features/media/MediaImage";
+import { useOptionalSession } from "../../../../react/contexts/SessionContext";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { LotterySlotGrid } from "./LotterySlotGrid";
 import { LotteryPullForm } from "./LotteryPullForm";
@@ -13,10 +14,30 @@ import { slotsToCollageItems } from "./slot-collage-items";
  * Shows cover + description + slot grid + pull form (if active + logged in).
  */
 export function LotteryDetailView({ event, user, currentEntry }) {
+    /*
+     * 🛑 Viewer identity is read on the CLIENT, not taken from the `user` prop.
+     *
+     * The page used to `await getServerSessionUser()` to supply that prop, which
+     * cost twice over: `cookies()` forced dynamic rendering, so the route's
+     * `revalidate = 30` was silently inert (Root Cause #94) and every visit paid a
+     * full render; and the HTML then varied per viewer, so it could never be
+     * cached or shared even once the TTL was fixed.
+     *
+     * `useOptionalSession` — not `useSession` — because library code that adjusts
+     * for the viewer must not require a provider to be mounted (Root Cause #20);
+     * absent, it fails CLOSED to the signed-out branch.
+     *
+     * The `user` prop is kept as an optional SEED so a caller that genuinely has
+     * the viewer (an authenticated dashboard mount) still renders correctly on
+     * first paint.
+     */
+    const session = useOptionalSession();
+    const isAuthResolving = session?.loading ?? false;
+    const viewer = session?.user ?? user ?? null;
     const [pulledEntry, setPulledEntry] = useState(currentEntry?.assignedPrizeSlotNumber != null ? currentEntry : null);
     const config = event.lotteryConfig;
     const prizeItems = slotsToCollageItems(config?.slots ?? []);
     const isActive = event.status === "active";
     const isEnded = event.status === "ended" || event.status === "cancelled";
-    return (_jsx(Container, { children: _jsx(Section, { children: _jsxs(Stack, { gap: "xl", children: [event.coverImageUrl || event.coverImage?.url ? (_jsx(Div, { rounded: "2xl", className: "relative overflow-hidden", style: { aspectRatio: "16/9", maxHeight: "16rem" }, children: _jsx(MediaImage, { src: event.coverImageUrl || event.coverImage?.url || "", alt: event.title, size: "hero" }) })) : (_jsx(Div, { rounded: "2xl", surface: "subtle", padding: "xl", align: "center", justify: "center", children: _jsx(Text, { size: "5xl", children: "\uD83C\uDFB0" }) })), _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Badge, { variant: isActive ? "success" : isEnded ? "danger" : "warning", children: event.status }), config && (_jsxs(Badge, { variant: "info", children: [config.slots.filter((s) => s.isBooked).length, "/", config.totalSlots, " slots claimed"] }))] }), _jsx(Heading, { level: 1, size: "3xl", weight: "bold", children: event.title }), event.description ? (_jsx(Text, { color: "muted", size: "sm", children: event.description.replace(/<[^>]+>/g, "").slice(0, 200) })) : null, event.endsAt ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Ends: ", new Date(event.endsAt).toLocaleDateString("en-IN", { dateStyle: "long" })] })) : null] }), prizeItems.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Prizes" }), _jsx(PrizeDrawCollage, { items: prizeItems, wonLabel: "Claimed" })] })) : null, config && config.slots.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Slots" }), _jsx(LotterySlotGrid, { slots: config.slots, totalSlots: config.totalSlots })] })) : null, isActive && config && (_jsx(Div, { padding: "md", rounded: "2xl", surface: "card", className: "border border-[var(--appkit-color-border)]", children: !user ? (_jsxs(Stack, { gap: "md", className: "text-center", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Want to Participate?" }), _jsx(Text, { color: "muted", children: "Log in to submit your lottery entry." }), _jsx(Anchor, { href: String(ROUTES.AUTH.LOGIN), tone: "brand", children: "Log In to Enter" })] })) : pulledEntry ? (_jsxs(Stack, { gap: "sm", surface: "success-surface", padding: "md", rounded: "xl", className: "border border-success/20", children: [_jsxs(Heading, { level: 2, size: "lg", weight: "bold", className: "text-success", children: ["You're Lottery #", pulledEntry.userLotteryNumber, "!"] }), _jsxs(Text, { className: "text-success", size: "sm", children: ["Assigned to Slot #", pulledEntry.assignedPrizeSlotNumber, pulledEntry.slotName ? ` — ${pulledEntry.slotName}` : "", "."] })] })) : (_jsx(LotteryPullForm, { sourceType: "event", eventId: event.id, totalSlots: config.totalSlots, maxPullsPerUser: config.maxPullsPerUser, onSuccess: (res) => setPulledEntry(res) })) })), isEnded && !pulledEntry && (_jsx(Stack, { gap: "sm", surface: "muted", padding: "md", rounded: "xl", children: _jsx(Text, { color: "muted", weight: "semibold", children: "This lottery has ended." }) }))] }) }) }));
+    return (_jsx(Container, { children: _jsx(Section, { children: _jsxs(Stack, { gap: "xl", children: [event.coverImageUrl || event.coverImage?.url ? (_jsx(Div, { rounded: "2xl", className: "relative overflow-hidden", style: { aspectRatio: "16/9", maxHeight: "16rem" }, children: _jsx(MediaImage, { src: event.coverImageUrl || event.coverImage?.url || "", alt: event.title, size: "hero" }) })) : (_jsx(Div, { rounded: "2xl", surface: "subtle", padding: "xl", align: "center", justify: "center", children: _jsx(Text, { size: "5xl", children: "\uD83C\uDFB0" }) })), _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Badge, { variant: isActive ? "success" : isEnded ? "danger" : "warning", children: event.status }), config && (_jsxs(Badge, { variant: "info", children: [config.slots.filter((s) => s.isBooked).length, "/", config.totalSlots, " slots claimed"] }))] }), _jsx(Heading, { level: 1, size: "3xl", weight: "bold", children: event.title }), event.description ? (_jsx(Text, { color: "muted", size: "sm", children: event.description.replace(/<[^>]+>/g, "").slice(0, 200) })) : null, event.endsAt ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Ends: ", new Date(event.endsAt).toLocaleDateString("en-IN", { dateStyle: "long" })] })) : null] }), prizeItems.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Prizes" }), _jsx(PrizeDrawCollage, { items: prizeItems, wonLabel: "Claimed" })] })) : null, config && config.slots.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Slots" }), _jsx(LotterySlotGrid, { slots: config.slots, totalSlots: config.totalSlots })] })) : null, isActive && config && (_jsx(Div, { padding: "md", rounded: "2xl", surface: "card", className: "border border-[var(--appkit-color-border)]", children: isAuthResolving ? (_jsx(Stack, { gap: "md", className: "text-center", children: _jsx(Text, { color: "muted", children: "Checking your session\u2026" }) })) : !viewer ? (_jsxs(Stack, { gap: "md", className: "text-center", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Want to Participate?" }), _jsx(Text, { color: "muted", children: "Log in to submit your lottery entry." }), _jsx(Anchor, { href: String(ROUTES.AUTH.LOGIN), tone: "brand", children: "Log In to Enter" })] })) : pulledEntry ? (_jsxs(Stack, { gap: "sm", surface: "success-surface", padding: "md", rounded: "xl", className: "border border-success/20", children: [_jsxs(Heading, { level: 2, size: "lg", weight: "bold", className: "text-success", children: ["You're Lottery #", pulledEntry.userLotteryNumber, "!"] }), _jsxs(Text, { className: "text-success", size: "sm", children: ["Assigned to Slot #", pulledEntry.assignedPrizeSlotNumber, pulledEntry.slotName ? ` — ${pulledEntry.slotName}` : "", "."] })] })) : (_jsx(LotteryPullForm, { sourceType: "event", eventId: event.id, totalSlots: config.totalSlots, maxPullsPerUser: config.maxPullsPerUser, onSuccess: (res) => setPulledEntry(res) })) })), isEnded && !pulledEntry && (_jsx(Stack, { gap: "sm", surface: "muted", padding: "md", rounded: "xl", children: _jsx(Text, { color: "muted", weight: "semibold", children: "This lottery has ended." }) }))] }) }) }));
 }

package/dist/_internal/server/features/categories/adapters.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Category adapters — the single allow-list projection for every public
+ * category response.
+ *
+ * Every field of `CategoryDocument` is triaged into exactly one of
+ * `PUBLIC_CATEGORY_FIELDS` (mapped into the returned literal) or
+ * `PRIVATE_CATEGORY_FIELDS` (with a stated reason), mirroring the store and
+ * site-settings adapters. A field added to the schema and to neither list
+ * fails `scripts/audit-public-projection-parity.mjs`, so new fields are
+ * private by default.
+ *
+ * Why this exists (2026-10-10): `GET /api/categories` returned `result.data`
+ * raw — the whole document — on an unauthenticated, hour-edge-cached route.
+ * That published `createdBy` (a uid), `createdByStoreId`, `createdByStoreName`
+ * and, worst, `metrics.productIds[]` / `metrics.auctionIds[]`: two UNBOUNDED
+ * arrays that grow with the catalogue. `CategoryInlineSelect` calls that route
+ * with `pageSize=200` on every seller-form open, so the payload scaled with
+ * both the number of categories and the number of products in each.
+ *
+ * 🛑 There is an older `CATEGORIES_PUBLIC_FIELDS` in
+ * `features/categories/schemas/firestore.ts`. It has ZERO runtime consumers,
+ * predates `categoryType` / `highlights` / `faqs` / `itemCode` / the brand and
+ * bundle fields, and is a `.select()`-style dot-path list rather than a
+ * projection. It is deliberately not reused here; this module is the one the
+ * route actually calls.
+ */
+import type { CategoryDocument } from "../../../../features/categories/schemas/firestore";
+import type { CategoryItem } from "../../../../features/categories/types/index";
+/**
+ * Document fields that may reach an unauthenticated client. Keep in sync with
+ * the object literal in `toCategoryListItem` — the audit asserts both
+ * directions.
+ */
+export declare const PUBLIC_CATEGORY_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "isLeaf", "ancestors", "categoryType", "itemCode", "isFeatured", "featuredPriority", "seo", "display", "isActive", "highlights", "faqs", "brandWebsite", "brandCountry", "brandFounded", "metrics", "createdAt", "updatedAt"];
+/**
+ * Fields withheld, each with the reason. Never remove one without replacing
+ * the reason — "it seemed unused" is how a field ends up public by accident.
+ */
+export declare const PRIVATE_CATEGORY_FIELDS: readonly ["position", "subtreeSize", "createdBy", "createdByType", "createdByStoreId", "createdByStoreName", "viewCount", "isBrand", "showOnHomepage", "isSearchable", "searchTxt", "aliases", "brandSlug", "bundleKind", "bundlePrice", "bundleStockStatus", "bundleProductIds", "bundleCategorySlugs", "bundleOriginalTotal", "bundleItemDetails", "contentBody", "descriptionTemplates", "productDefaults", "isTestData", "testDataExpiresAt", "bundleQueryRule", "bundleQueryResolvedAt"];
+/**
+ * Project a stored category into the public shape.
+ *
+ * Built by NAMING each field, never by spreading and deleting — a deny-list
+ * publishes every field nobody thought to remove, including ones the
+ * interface does not declare (Root Cause #70).
+ */
+export declare function toCategoryListItem(doc: CategoryDocument): CategoryItem;

package/dist/_internal/server/features/categories/adapters.js

@@ -0,0 +1,235 @@
+/**
+ * Document fields that may reach an unauthenticated client. Keep in sync with
+ * the object literal in `toCategoryListItem` — the audit asserts both
+ * directions.
+ */
+export const PUBLIC_CATEGORY_FIELDS = [
+    "id",
+    "name",
+    "slug",
+    "description",
+    // Structure. The client builds its own tree and breadcrumbs from these.
+    "rootId",
+    "parentIds",
+    "childrenIds",
+    "tier",
+    "path",
+    "order",
+    "isLeaf",
+    "ancestors",
+    // Discriminator — public because every consumer must tell a listing
+    // category apart from a brand/bundle/sublisting row, and a plain category
+    // OMITS the field, so the test can only be done client-side.
+    "categoryType",
+    "itemCode",
+    // Presentation.
+    "isFeatured",
+    "featuredPriority",
+    "seo",
+    "display",
+    // Read by `AdminCategoriesView`'s Status column off this very route.
+    "isActive",
+    // Editorial copy — already rendered publicly by
+    // `CategoryHighlightsAndFaqSection` on the category and brand pages.
+    "highlights",
+    "faqs",
+    // Brand-row fields, rendered in the "About this brand" panel.
+    "brandWebsite",
+    "brandCountry",
+    "brandFounded",
+    // Rollup counts only — see `metrics` in the private list.
+    "metrics",
+    "createdAt",
+    "updatedAt",
+];
+/**
+ * Fields withheld, each with the reason. Never remove one without replacing
+ * the reason — "it seemed unused" is how a field ends up public by accident.
+ */
+export const PRIVATE_CATEGORY_FIELDS = [
+    // Internal DFS coordinates. Useful only to `onCategoryWrite` and
+    // `positionsReconcile`; publishing them invites a client to depend on an
+    // ordering we renumber on every reseed.
+    "position",
+    "subtreeSize",
+    // Operator identity. `createdBy` is a raw uid.
+    "createdBy",
+    "createdByType",
+    "createdByStoreId",
+    "createdByStoreName",
+    // Analytics, not content.
+    "viewCount",
+    // @deprecated duplicate of `categoryType === "brand"`.
+    "isBrand",
+    /*
+     * The next four are withheld NOT because they are sensitive but because
+     * no client reads them off THIS route — verified by grep, per consumer:
+     *
+     *   showOnHomepage  — homepage curation runs server-side; `CategoryItem`
+     *                     declares no such field and nothing reads one.
+     *   isSearchable    — a query-time flag. No client branches on it.
+     *   brandSlug       — a bundle's own brand tag. Its two readers are
+     *                     `AdminBundleEditorView` (via ADMIN_ENDPOINTS.BUNDLES,
+     *                     a different route) and `BrandDetailPageView` (which
+     *                     holds the raw `CategoryDocument` server-side).
+     *   bundle*         — same story: every bundle surface is fed by
+     *                     ADMIN_ENDPOINTS.BUNDLES or by a server-side read.
+     *
+     * 🛑 If a bundle card is ever fed from `/api/categories`, promote the
+     * bundle fields HERE and add them to `CategoryItem` — do not reach for a
+     * cast at the call site, which is Root Cause #70's exact mechanism.
+     */
+    "showOnHomepage",
+    "isSearchable",
+    /*
+     * The prefix-expanded search index. Withheld for two reasons, not one:
+     *
+     *   - No client reads it. Searching is a SERVER concern — the term is pushed
+     *     down as an `array-contains` on `CATEGORY_FIELDS.SEARCH_TXT`; a browser
+     *     has no use for the token array.
+     *   - It is 53–160 tokens per row (measured, cap 600). Publishing it would
+     *     roughly double this payload on a route `CategoryInlineSelect` hits
+     *     with `pageSize=200` on every seller-form open — the exact cost
+     *     Root Cause #104 was about.
+     */
+    "searchTxt",
+    /*
+     * `aliases` — B5. The alternate names a leaf is searched by ("Lost
+     * Longinus" for the row stored as "Luinor L2", plus its product code).
+     *
+     * Withheld from THIS route because nothing reads it here: the aliases exist
+     * to be folded into `searchTxt` at write time, and the matching happens
+     * server-side. `CategoryItem` declares no such field, and the only consumer
+     * of this route at scale is `CategoryInlineSelect` at `pageSize=200`, which
+     * shows a name and nothing else.
+     *
+     * 🛑 Not secret, and the distinction matters for the next person: every
+     * alias is ALREADY inferable from search results, because it is tokenised
+     * into the index this route helps query. If a detail page ever wants to
+     * render an "also known as" line — which would be genuinely useful on a
+     * named-model leaf — promote it here AND add it to `CategoryItem`, rather
+     * than casting at the call site (Root Cause #70's exact mechanism).
+     */
+    "aliases",
+    "brandSlug",
+    "bundleKind",
+    "bundlePrice",
+    "bundleStockStatus",
+    "bundleProductIds",
+    "bundleCategorySlugs",
+    "bundleOriginalTotal",
+    "bundleItemDetails",
+    /*
+     * ── Category-owned content (B3) ──────────────────────────────────────────
+     *
+     * All three are PRIVATE on this route and that is a payload decision, not a
+     * secrecy one — they are genuinely public content, just not from here.
+     *
+     * This is the LIST projection, and `CategoryInlineSelect` calls it with
+     * `pageSize=200` on every seller-form open. `contentBody` alone is 400–900
+     * chars of HTML per row, so publishing it here would add ~180 KB to a
+     * response whose only job is to fill a picker — the Fast-Origin-Transfer
+     * shape of Root Cause #104, on the resource this project is most over on.
+     *
+     * Each has exactly one real reader and neither is this route:
+     *
+     *   contentBody          — the category DETAIL page, which holds the raw
+     *                          CategoryDocument server-side (getCategoryBySlug).
+     *   descriptionTemplates — the seller form, via the narrow
+     *                          /api/categories/[id]/description-template
+     *                          endpoint (C2), one category at a time, edge-cached
+     *                          for an hour.
+     *   productDefaults      — `deriveTaxonomy`, server-side, on the product
+     *                          write path; plus the same narrow endpoint for the
+     *                          seller-facing price hint.
+     *
+     * 🛑 If a surface ever needs one of these from the list route, promote it
+     * here AND add it to `CategoryItem` AND to the literal in
+     * `toCategoryListItem` — do not cast at the call site, which is Root Cause
+     * #70's exact mechanism.
+     */
+    "contentBody",
+    "descriptionTemplates",
+    "productDefaults",
+    // Test-data plumbing. `hidePublicTestData()` filters on these server-side;
+    // a client has no business branching on them.
+    "isTestData",
+    "testDataExpiresAt",
+    // The rule that resolves a dynamic bundle's members. Publishing it hands
+    // out the query, and the resolved `bundleProductIds` is already public.
+    "bundleQueryRule",
+    "bundleQueryResolvedAt",
+];
+/**
+ * Rollup counters only.
+ *
+ * 🛑 `metrics.productIds[]` and `metrics.auctionIds[]` are deliberately
+ * dropped. They are unbounded arrays — one entry per product in the category
+ * — and they were the bulk of the raw payload. Nothing client-side reads them
+ * that a query cannot answer, and a category page already fetches its own
+ * products.
+ */
+function toPublicMetrics(m) {
+    return {
+        productCount: m?.productCount ?? 0,
+        auctionCount: m?.auctionCount ?? 0,
+        totalProductCount: m?.totalProductCount ?? 0,
+        totalAuctionCount: m?.totalAuctionCount ?? 0,
+        totalItemCount: m?.totalItemCount ?? 0,
+    };
+}
+/**
+ * Project a stored category into the public shape.
+ *
+ * Built by NAMING each field, never by spreading and deleting — a deny-list
+ * publishes every field nobody thought to remove, including ones the
+ * interface does not declare (Root Cause #70).
+ */
+export function toCategoryListItem(doc) {
+    /*
+     * No `as CategoryItem` on the literal below, on purpose. The cast is what
+     * lets a shape drift silently; without it tsc checks every key, and it
+     * already caught `createdAt` being a Date where the contract wants a
+     * string.
+     */
+    return {
+        id: doc.id,
+        name: doc.name,
+        slug: doc.slug,
+        description: doc.description,
+        rootId: doc.rootId,
+        parentIds: doc.parentIds,
+        childrenIds: doc.childrenIds,
+        tier: doc.tier,
+        path: doc.path,
+        order: doc.order,
+        isLeaf: doc.isLeaf,
+        ancestors: doc.ancestors,
+        categoryType: doc.categoryType,
+        itemCode: doc.itemCode,
+        isFeatured: doc.isFeatured,
+        featuredPriority: doc.featuredPriority,
+        seo: doc.seo,
+        display: doc.display,
+        isActive: doc.isActive,
+        highlights: doc.highlights,
+        faqs: doc.faqs,
+        brandWebsite: doc.brandWebsite,
+        brandCountry: doc.brandCountry,
+        brandFounded: doc.brandFounded,
+        metrics: toPublicMetrics(doc.metrics),
+        // 🛑 `CategoryDocument` stores Dates; `CategoryItem` declares strings —
+        // this projection is also the serialisation boundary. Converting here
+        // rather than casting is deliberate: `as unknown as CategoryItem` has no
+        // runtime effect and would have shipped raw `Timestamp`/`Date` objects
+        // into an RSC payload, which is Root Cause #70's exact mechanism.
+        createdAt: toIsoString(doc.createdAt),
+        updatedAt: toIsoString(doc.updatedAt),
+    };
+}
+/** Firestore hands back `Date`; the client contract is an ISO string. */
+function toIsoString(value) {
+    if (!value)
+        return undefined;
+    return value instanceof Date ? value.toISOString() : String(value);
+}

package/dist/_internal/server/features/checkout/actions.js

@@ -13,6 +13,7 @@ import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../
 import { ORDER_FIELDS } from "../../../../constants/field-names";
 import { serverLogger } from "../../../../monitoring";
 import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories";
+import { isIntraStateSupply } from "../../../shared/fees/calculator";
 import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository";
 import { sendOrderConfirmationEmail } from "../../../../features/contact/server";
@@ -411,16 +412,37 @@ async function createOrderForGroup(group, orderType, ctx) {
     // unknown (digital-only carts have no shipping address).
     let gstBreakdown;
     if (gstSettings?.enabled && buyerState) {
-        const intraState = !!storeState && storeState === buyerState;
+        /*
+         * 🛑 `isIntraStateSupply`, not `storeState === buyerState`. That raw
+         * comparison read "Karnataka" / "karnataka" / "KA" as three different
+         * states — the exact drift `constants/geo/subdivisions.ts` opens by
+         * documenting — and a store with no address resolved to `false`, i.e.
+         * silently inter-state. `null` means "cannot tell" and is logged rather
+         * than guessed; the AMOUNT is identical either way (IGST total ==
+         * CGST+SGST total), so what was wrong was the split on the invoice.
+         */
+        const intra = isIntraStateSupply(storeState, buyerState);
+        if (intra === null) {
+            serverLogger.warn("[gst] place of supply undetermined — defaulting to inter-state (IGST)", { storeId: firstItem.storeId, hasStoreState: !!storeState });
+        }
         // Per-member, not per-line: a bundle or grouped line spans several products
         // with several different rates, and taxing the whole line at one product's
         // rate is wrong in both directions. Shared with previewCheckoutPricing so
         // the figure shown and the figure charged cannot drift.
-        const { taxableAmount, gstAmount } = sumGroupGst(group.map(({ item }) => item), ctx.productById, intraState);
-        if (taxableAmount > 0) {
-            gstBreakdown = intraState
-                ? { taxableAmount, cgst: Math.round(gstAmount / 2), sgst: gstAmount - Math.round(gstAmount / 2), igst: 0, gstAmount }
-                : { taxableAmount, cgst: 0, sgst: 0, igst: gstAmount, gstAmount };
+        const summary = sumGroupGst(group.map(({ item }) => item), ctx.productById, intra ?? false);
+        /*
+         * The split is taken AS COMPUTED, per slice, by `calculateGst` inside
+         * `sumGroupGst`. It used to be re-derived here as
+         * `Math.round(gstAmount / 2)` — whole rupees, so ₹161.82 became
+         * 81.00/80.82 rather than 80.91/80.91, and a ₹0.52 total rounded to 0 and
+         * was then dropped off the invoice entirely by the `|| undefined` below.
+         *
+         * The guard is on EITHER base: an order of purely exempt goods has a real
+         * taxable value to report and zero tax, and skipping it left the invoice
+         * unable to reconcile.
+         */
+        if (summary.taxableAmount > 0 || summary.exemptAmount > 0) {
+            gstBreakdown = summary;
         }
     }
     const isCodLike = paymentMethod === "cod" || paymentMethod === "upi_manual" || paymentMethod === "cash";
@@ -458,7 +480,19 @@ async function createOrderForGroup(group, orderType, ctx) {
     // The platform commission is now charged on EVERY payment method. It used to
     // be added only on the online-payment path, so COD / UPI-manual / cash / EMI
     // buyers silently never paid it.
-    const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + whatsappNotifyFee + giftWrapFee + shipmentProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0) + (gstBreakdown?.gstAmount ?? 0);
+    const orderTotal = 
+    /*
+     * 🛑 Product GST is NOT a term here, and its absence is the model.
+     *
+     * Prices are tax-INCLUSIVE: the GST is already inside `groupTotal`, backed
+     * out by `sumGroupGst` for reporting rather than added on top. A ₹999
+     * listing at 5% charges ₹999, of which ₹47.57 is tax we remit.
+     *
+     * `platformFeeGst` IS a term, and the asymmetry is correct: that is GST on
+     * OUR service fee to the seller, charged to the buyer on top of the fee —
+     * not tax on the goods.
+     */
+    Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + whatsappNotifyFee + giftWrapFee + shipmentProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0);
     const imageUrls = [
         ...new Set(group
             .map(({ product }) => product.mainImage)
@@ -535,6 +569,20 @@ async function createOrderForGroup(group, orderType, ctx) {
         shipmentProtectionAddon: !adminBypass && shipmentProtectionFee > 0 ? true : undefined,
         shipmentProtectionFee: !adminBypass && shipmentProtectionFee > 0 ? shipmentProtectionFee : undefined,
         taxableAmount: gstBreakdown?.taxableAmount,
+        /* Exempt goods are a reportable nil-rated supply, kept OUT of
+         * `taxableAmount` so the taxed base stays the base the tax was charged on,
+         * and recorded here so the invoice's columns can reconcile. */
+        exemptAmount: gstBreakdown?.exemptAmount || undefined,
+        /* Our registration AS IT STANDS NOW. A tax invoice without the supplier's
+         * GSTIN is not a tax invoice, and the invoice page cannot read it from
+         * site settings — `gst` is in PRIVATE_SITE_FIELDS. See the schema. */
+        supplierGstin: gstSettings?.enabled ? gstSettings.gstin || undefined : undefined,
+        supplierLegalName: gstSettings?.enabled ? gstSettings.legalName || undefined : undefined,
+        supplierAddress: gstSettings?.enabled ? gstSettings.address || undefined : undefined,
+        /* Per-rate, for Rule 46. Computed by `sumGroupGst` rather than re-derived
+         * downstream — a mixed 5%+18% order cannot produce a compliant invoice
+         * from the aggregate triple alone. */
+        gstByRate: gstBreakdown?.byRate.length ? gstBreakdown.byRate : undefined,
         /*
          * 🛑 This must include the GST on the PLATFORM FEE, not just product GST.
          *
@@ -985,11 +1033,18 @@ export async function previewCheckoutPricing(input) {
         const groupShipmentProtectionFee = computeShipmentProtectionFee(groupTotal, addons.shipmentProtectionAddon ?? false, commissions);
         let groupGstAmount = 0;
         if (siteSettings?.gst?.enabled && resolvedAddress?.state) {
-            const intraState = !!storeState && storeState === resolvedAddress.state;
+            /*
+             * `isIntraStateSupply`, matching `createOrderForGroup` exactly — this
+             * was the same raw `===` and had to change with it, or the figure SHOWN
+             * and the figure CHARGED would split on different state comparisons.
+             * The total is unaffected by the answer (IGST total == CGST+SGST total),
+             * but using one rule in both places is what keeps that true.
+             */
+            const intra = isIntraStateSupply(storeState, resolvedAddress.state);
             // Same helper createOrderForGroup uses — the two disagreeing is the
             // recurring defect here (Root Cause #59), and it is the buyer seeing one
             // tax figure and being charged another.
-            groupGstAmount = sumGroupGst(group.map(({ item }) => item), resolvedProductById, intraState).gstAmount;
+            groupGstAmount = sumGroupGst(group.map(({ item }) => item), resolvedProductById, intra ?? false).gstAmount;
         }
         const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
         const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
@@ -1002,6 +1057,15 @@ export async function previewCheckoutPricing(input) {
             whatsappNotifyFee: groupWhatsappFee,
             giftWrapFee: groupGiftWrapFee,
             shipmentProtectionFee: groupShipmentProtectionFee,
+            /*
+             * INFORMATIONAL — the tax already INSIDE these prices, so checkout can
+             * render "incl. GST ₹47.57". 🛑 Deliberately NOT added to `total` below:
+             * it was, under the old add-on-top math, and removing it from all five
+             * money sites together is what the tax-inclusive model consists of. A
+             * preview that still added it would show a total ₹47.57 higher than the
+             * order it previews — the shown-vs-charged drift this field exists to
+             * prevent, reintroduced from the other direction.
+             */
             gstAmount: groupGstAmount,
             couponDiscount: groupCouponDiscount,
             total: Math.max(0, groupTotal - groupCouponDiscount) +
@@ -1009,8 +1073,7 @@ export async function previewCheckoutPricing(input) {
                 groupCodHandlingFee +
                 groupWhatsappFee +
                 groupGiftWrapFee +
-                groupShipmentProtectionFee +
-                groupGstAmount,
+                groupShipmentProtectionFee,
         });
     }
     const sum = (pick) => stores.reduce((acc, s) => acc + pick(s), 0);
@@ -1184,13 +1247,13 @@ async function refundDroppedItemsForPhonePeCheckout(input) {
  * from the inline version this replaced.
  */
 async function createPhonePeGroupOrder(group, orderType, ctx) {
-    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, } = ctx;
+    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, } = ctx;
     const firstItem = group[0].item;
     const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
     // Reuses the same store/seller lookup as the COD/UPI path above instead
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
-    const { shippingFee, storeOwnerId } = await resolveShippingCost(firstItem.storeId);
+    const { shippingFee, storeOwnerId, storeState } = await resolveShippingCost(firstItem.storeId);
     const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
     const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
     // Mirrors createOrderForGroup — without this the online-payment path wrote
@@ -1221,16 +1284,39 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     const giftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates);
     const giftWrapMessage = addons.giftWrapMessage;
     const shipmentProtectionFee = computeShipmentProtectionFee(groupTotal, addons.shipmentProtectionAddon ?? false, commissionRates);
+    /*
+     * P-8 GST — now wired through this path. C0c defect 1.
+     *
+     * The comment that used to sit here deferred it, correctly identifying the
+     * blocker: `expectedPaymentAmountRs` compares against what PhonePe already
+     * captured, so adding product GST here WITHOUT adding it to the upstream
+     * pre-payment amount would either fail the mismatch check or silently
+     * under-charge. Both halves move in this change, plus the create-order route
+     * that decides the captured amount.
+     *
+     * 🛑 What unblocked it: the GST TOTAL does not depend on the place of
+     * supply. IGST total equals CGST+SGST total, so `/api/payment/create-order`
+     * can compute the amount before the delivery address is even known — which
+     * is the thing it genuinely cannot see. Measured across ~285k rate/base
+     * combinations, the two differ by at most ₹0.01 (from `round(half × 2)` in
+     * the intra branch), and the guard's tolerance is ₹1.
+     *
+     * Only the SPLIT needs the address, and this function has it.
+     */
+    let phonepeGst;
+    if (siteSettings?.gst?.enabled && buyerState) {
+        const intra = isIntraStateSupply(storeState, buyerState);
+        if (intra === null) {
+            serverLogger.warn("[gst] place of supply undetermined on the online path — defaulting to inter-state (IGST)", { storeId: firstItem.storeId, hasStoreState: !!storeState });
+        }
+        const summary = sumGroupGst(group.map(({ item }) => item), phonepeProductById, intra ?? false);
+        if (summary.taxableAmount > 0 || summary.exemptAmount > 0)
+            phonepeGst = summary;
+    }
+    /* Product GST is not a term — prices are tax-inclusive, so it is already
+     * inside `groupTotal`. Matches the COD/UPI path exactly; `platformFeeGst`
+     * stays because that is GST on our fee, charged on top. */
     const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + whatsappNotifyFee + giftWrapFee + shipmentProtectionFee + platformFee + platformFeeGst;
-    // P-8 GST — deliberately NOT wired into this PhonePe-verify path. The
-    // amount-mismatch check above (expectedPaymentAmountRs) compares against
-    // what the buyer already paid via the PhonePe order created earlier in
-    // the flow; adding product GST here without also adding it to that
-    // upstream pre-payment amount calculation would either fail the mismatch
-    // check or silently under/over-charge. Wiring GST through the full
-    // PhonePe create→confirm round-trip is separate follow-up work, tracked
-    // alongside P-13 (PhonePe is disabled by default today, so this order
-    // type doesn't currently carry a GST breakdown).
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     // Same expansion as the COD/UPI path. This was a THIRD hand-rolled copy of
     // the price rule (`isBundle ? item.price : product.price`) that — like the
@@ -1311,6 +1397,26 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         giftWrapMessage: giftWrapFee > 0 ? giftWrapMessage?.slice(0, 500) : undefined,
         shipmentProtectionAddon: shipmentProtectionFee > 0 ? true : undefined,
         shipmentProtectionFee: shipmentProtectionFee > 0 ? shipmentProtectionFee : undefined,
+        /*
+         * The tax breakdown, matching `createOrderForGroup` field for field.
+         * This path recorded NONE of it before C0c defect 1 — so an online order
+         * carried no `taxableAmount`, no `gstAmount` and no split, and the order
+         * page's Tax row could not render even once GST was enabled. Both the
+         * product GST and the platform-fee GST are summed into `gstAmount`, which
+         * is what makes the order's own lines reconcile to its total.
+         */
+        taxableAmount: phonepeGst?.taxableAmount,
+        exemptAmount: phonepeGst?.exemptAmount || undefined,
+        // Our registration at the moment of supply — see the schema. Mirrors the
+        // COD/UPI path so both produce an invoiceable order.
+        supplierGstin: siteSettings?.gst?.enabled ? siteSettings.gst.gstin || undefined : undefined,
+        supplierLegalName: siteSettings?.gst?.enabled ? siteSettings.gst.legalName || undefined : undefined,
+        supplierAddress: siteSettings?.gst?.enabled ? siteSettings.gst.address || undefined : undefined,
+        gstByRate: phonepeGst?.byRate.length ? phonepeGst.byRate : undefined,
+        gstAmount: (phonepeGst?.gstAmount ?? 0) + platformFeeGst || undefined,
+        cgst: phonepeGst?.cgst || undefined,
+        sgst: phonepeGst?.sgst || undefined,
+        igst: phonepeGst?.igst || undefined,
         couponCode: appliedDiscounts[0]?.code,
         couponDiscount: couponDiscount > 0 ? couponDiscount : undefined,
         appliedDiscounts: appliedDiscounts.length > 0 ? appliedDiscounts : undefined,
@@ -1563,6 +1669,35 @@ export async function verifyAndPlacePhonePeOrderAction(input) {
                 computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
                 computeShipmentProtectionFee(groupSubtotal, addons.shipmentProtectionAddon ?? false, commissionRates));
         }, 0);
+        /*
+         * Product GST, matching what `/api/payment/create-order` charged.
+         *
+         * 🛑 This term's ABSENCE was half of C0c defect 1. The guard agreed with
+         * the create path only because both omitted it, so an undercharge could
+         * never trip the check — the two were consistently wrong together, which
+         * is the worst available state for a guard.
+         *
+         * `intraState: false` is deliberate and is not a guess about the buyer's
+         * address: the TOTAL does not depend on the place of supply (IGST total ==
+         * CGST+SGST total), measured to within ₹0.01 across ~285k rate/base
+         * combinations, and this comparison already carries a ₹1 tolerance.
+         * Only the split needs the address, and the split is not checked here.
+         */
+        /*
+         * 🛑 No product-GST term, and the reason is the tax-inclusive model rather
+         * than the omission this guard was fixed for an hour earlier.
+         *
+         * Defect 1's fix added `expectedProductGst` here, because the three money
+         * sites had to AGREE with the preview and the preview added the tax. The
+         * model then changed: every price carries its tax inside, so the correct
+         * shared value became zero-added — at the capture route, at both order
+         * paths, at the preview, and here. The agreement defect 1 established is
+         * preserved; what changed is the figure all five agree on.
+         *
+         * `cartSubtotalRs` therefore already contains the GST, and adding it again
+         * would make this guard demand ~₹580 more than the buyer owes on a
+         * ₹5,547 cart — rejecting every correctly-charged order.
+         */
         const expectedPaymentAmountRs = cartSubtotalRs + expectedPlatformFee + expectedGstOnFee + expectedAddonFees + expectedShippingFee;
         // Reuses the order already fetched above to confirm COMPLETED — PhonePe's
         // own amount is in its wire-format smallest unit. // audit-money-units-ok: describes the PhonePe boundary conversion this line performs, not our storage convention
@@ -1611,6 +1746,10 @@ export async function verifyAndPlacePhonePeOrderAction(input) {
             phonepeOrderId: phonepeOrder.gatewayOrderId,
             transactionId: phonepeOrder.transactionId,
             shippingAddress,
+            // For the CGST/SGST vs IGST split. The TOTAL does not depend on it
+            // (see createPhonePeGroupOrder), which is what let the pre-payment
+            // amount be computed before this address was known.
+            buyerState: resolvedAddressPp?.state,
             notes,
             outOfStockPolicy,
             unavailablePaid,