@mohasinac/appkit 4.62.0 → 4.62.1

package/dist/features/admin/components/AdminOrdersGuideView.js

@@ -2,6 +2,16 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ShoppingBag, Hash, Scale, Wallet, RotateCcw, DollarSign, Gavel } from "lucide-react";
 import { Code, Div, Heading, Li, Row, Section, Span, Stack, Text, Ul } from "../../../ui/index.js";
 import { GC } from "../../_guide-cls.js";
+import { resolvePublishedValues } from "../../../_internal/shared/content/published-values.js";
+/*
+ * Phase 9 — read from the published-value registry rather than restated.
+ *
+ * 🛑 No settings argument, deliberately: this is the OBLIGATION-derived window
+ * and it has no settings override, so passing settings would imply an
+ * admin-editable number that does not exist (the 18-dead-settings pattern,
+ * from the "control that appears to do something the code ignores" direction).
+ */
+const { returnRespondHours: RETURN_RESPOND_HOURS, refundBusinessDaysMin: REFUND_DAYS_MIN, refundBusinessDaysMax: REFUND_DAYS_MAX, } = resolvePublishedValues();
 export function AdminOrdersGuideView() {
     return (_jsxs(Stack, { className: "max-w-3xl mx-auto", padding: "b-2xl", gap: "xl", children: [_jsxs(Section, { children: [_jsxs(Row, { className: "mb-2", align: "center", gap: "3", children: [_jsx(Row, { className: "flex-shrink-0 w-10 h-10 [background:linear-gradient(135deg,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_100%)]", align: "center", justify: "center", rounded: "xl", children: _jsx(ShoppingBag, { className: "w-5 h-5 text-white" }) }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] tracking-widest", size: "sm", weight: "semibold", transform: "uppercase", children: "Admin Guide" })] }), _jsx(Heading, { level: 1, className: "text-[var(--appkit-color-text)] mb-2", mdSize: "3xl", size: "2xl", weight: "bold", children: "Orders & Finance" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", children: "Order statuses, payouts, disputes, returns, and commission math on LetItRip." })] }), [
                 {
@@ -11,7 +21,18 @@ export function AdminOrdersGuideView() {
                                 ["PROCESSING", "Seller has acknowledged and is packing."],
                                 ["SHIPPED", "Dispatched. Tracking number provided by seller."],
                                 ["DELIVERED", "Carrier confirmed delivery."],
-                                ["RETURN_REQUESTED", "Buyer opened a return. Seller has 3 days to respond."],
+                                /*
+                                 * 🛑 Phase 9, decision 23 — this said "3 days" while the FAQ
+                                 * said 48 hours, and the FAQ WINS: it is the buyer-facing
+                                 * promise and the one a buyer has already read. The number now
+                                 * comes from `OBLIGATION_POLICIES["return-respond"]`, which is
+                                 * what actually closes the window — so a staff-facing guide can
+                                 * no longer quietly contradict what the buyer was told.
+                                 */
+                                [
+                                    "RETURN_REQUESTED",
+                                    `Buyer opened a return. Seller has ${RETURN_RESPOND_HOURS} hours to respond.`,
+                                ],
                                 ["REFUNDED", "Return accepted and refund issued via Razorpay."],
                                 ["CANCELLED", "Cancelled before shipping. Payment returned."],
                             ].map(([status, note]) => (_jsxs(Row, { gap: "3", children: [_jsx(Text, { className: "flex-shrink-0 font-mono text-[var(--appkit-color-primary)] w-40", size: "xs", weight: "semibold", children: status }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", children: note })] }, status))), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] pt-[0.5rem]", size: "sm", children: "Admin-only transitions: force-cancel (any status before DELIVERED), force-refund (post-DELIVERED dispute)." })] })),
@@ -30,7 +51,7 @@ export function AdminOrdersGuideView() {
                 },
                 {
                     Icon: RotateCcw, title: "Return Requests",
-                    content: (_jsxs(Ul, { className: GC.listMuted, children: [_jsx(Li, { children: "Admin can view the return reason and attached photos on the order detail page." }), _jsxs(Li, { children: [_jsx(Span, { weight: "bold", children: "When to override a seller rejection" }), ": Only when photographic evidence clearly supports the buyer's claim of a significant not-as-described defect. Do not override for buyer's remorse."] }), _jsx(Li, { children: "After admin override: refund is issued automatically via Razorpay (3\u20137 business days for card, 1\u20132 for UPI). Seller payout for that order is withheld." })] })),
+                    content: (_jsxs(Ul, { className: GC.listMuted, children: [_jsx(Li, { children: "Admin can view the return reason and attached photos on the order detail page." }), _jsxs(Li, { children: [_jsx(Span, { weight: "bold", children: "When to override a seller rejection" }), ": Only when photographic evidence clearly supports the buyer's claim of a significant not-as-described defect. Do not override for buyer's remorse."] }), _jsxs(Li, { children: ["After admin override: the refund is issued automatically (", REFUND_DAYS_MIN, "\u2013", REFUND_DAYS_MAX, " business days for card, 1\u20132 for UPI). Seller payout for that order is withheld."] })] })),
                 },
                 {
                     Icon: DollarSign, title: "Commission & Settlement Math",

package/dist/features/admin/components/AdminOrdersView.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { groupOrderItemsByLine } from "../../orders/utils/bundle-grouping.js";
 import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit/client";
 import { sortBy } from "@mohasinac/appkit/client";
 import React, { useState, useCallback } from "react";
@@ -61,14 +62,70 @@ function toOrderItemRows(item) {
         quantity: typeof entry.quantity === "number" ? entry.quantity : 1,
         unitPrice: typeof entry.unitPrice === "number" ? entry.unitPrice : 0,
         totalPrice: typeof entry.totalPrice === "number" ? entry.totalPrice : 0,
+        /*
+         * The collapse keys, carried so the editor can group a bundle or
+         * buyer-assembled group back into one line the way the buyer's receipt
+         * does. Narrowed by `typeof` like every field above rather than cast —
+         * this function's whole job is turning a loose record into a typed row,
+         * and a cast here is how `title`/`price` once slipped through (RC#45).
+         */
+        groupSlug: typeof entry.groupSlug === "string" ? entry.groupSlug : undefined,
+        groupTitle: typeof entry.groupTitle === "string" ? entry.groupTitle : undefined,
+        bundleCategorySlug: typeof entry.bundleCategorySlug === "string" ? entry.bundleCategorySlug : undefined,
+        bundleProductIds: Array.isArray(entry.bundleProductIds)
+            ? entry.bundleProductIds.filter((v) => typeof v === "string")
+            : undefined,
     }));
 }
+/*
+ * The row's headline, counted in LINES rather than item rows.
+ *
+ * 🛑 `extraCount` deliberately changed meaning when grouping landed: it was
+ * `items.length - 1`, so a bundle of four read "Dranzer S +3 more" — naming an
+ * arbitrary member and implying four separate things were bought. It is now
+ * `groups.length - 1`, so the same order reads "Starter Bundle +0" and a
+ * bundle plus one standalone reads "+1 more". The number a buyer or admin
+ * reads on a row should match the number of lines they will see inside it.
+ */
+/*
+ * `sourceContext` arrives as JsonValue off the raw admin-list doc, so it can
+ * be a string, an array or null — none of which `OrderProvenanceCard` can
+ * switch on. This narrows to "an object carrying a `path` tag" and nothing
+ * further: that is deliberately NOT the card's own switch duplicated, it only
+ * establishes that there is a tag to switch on, which is what makes the single
+ * cast true instead of hopeful. `as unknown as OrderSourceContext` would
+ * assert exactly the same thing while checking nothing (Root Cause #98).
+ */
+function toSourceContext(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    /*
+     * Via `object` rather than straight off the JsonValue union, for two
+     * reasons that pull the same way. `Array.isArray` does not narrow
+     * `JsonArray | JsonObject` apart, so `value.path` does not resolve; and
+     * `OrderSourceContext` is not assignable to `JsonObject` (its optional
+     * members admit `undefined`, which is not a JsonValue), so TS refuses that
+     * conversion outright. Probing as `{ path?: string }` keeps both the probe
+     * and the assertion legal without an `unknown` anywhere.
+     */
+    const obj = value;
+    return typeof obj.path === "string"
+        ? obj
+        : undefined;
+}
 function firstOrderItem(item) {
-    const items = toOrderItemRows(item);
+    const groups = groupOrderItemsByLine(toOrderItemRows(item));
+    const first = groups[0];
+    const extraCount = Math.max(0, groups.length - 1);
+    if (!first)
+        return { extraCount: 0 };
+    if (first.kind === "single") {
+        return { image: first.item.image, title: first.item.title, extraCount };
+    }
     return {
-        image: items[0]?.image,
-        title: items[0]?.title,
-        extraCount: Math.max(0, items.length - 1),
+        image: first.items[0]?.item.image,
+        title: first.groupTitle ?? "Grouped purchase",
+        extraCount,
     };
 }
 /**
@@ -206,6 +263,11 @@ export function AdminOrdersView({ children, ...props }) {
                     couponCode: toStringValue(item.couponCode) || undefined,
                     couponDiscount: Number(item.couponDiscount ?? 0) || undefined,
                 },
+                // Raw doc in, so no serializer entry — but unlike `addons` above,
+                // which coerces every field by hand, this one needs a tag check
+                // before it can be trusted. See `toSourceContext`.
+                sourceContext: toSourceContext(item.sourceContext),
+                currency: toStringValue(item.currency, "") || undefined,
             };
         }),
         getTotal: (response, mappedRows) => typeof response.meta?.total === "number" ? response.meta.total : mappedRows.length,
@@ -289,5 +351,5 @@ export function AdminOrdersView({ children, ...props }) {
             ] })),
         renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(_Fragment, { children: [_jsx(FilterChipGroup, { label: "Status", tabs: ADMIN_ORDER_STATUS_TABS, value: pendingFilters.status ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, status: id, paymentReview: "" })) }), _jsx(FilterChipGroup, { label: "Manual payment", tabs: ADMIN_ORDER_PAYMENT_REVIEW_TABS, value: pendingFilters.paymentReview ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, paymentReview: id, status: "" })) })] })),
     };
-    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(AdminOrderEditorView, { open: drawerOpen, onClose: () => setDrawerOpen(false), orderId: selectedRow?.id, orderLabel: selectedRow?.primary, currentStatus: selectedRow?.status, items: selectedRow?.items, paymentProofUrl: selectedRow?.paymentProofUrl, paymentTransactionId: selectedRow?.paymentTransactionId, paymentMethod: selectedRow?.paymentMethod, paymentStatus: selectedRow?.paymentStatus, displayedUpiId: selectedRow?.displayedUpiId, buyerReportedUpiId: selectedRow?.buyerReportedUpiId, paymentUpiMismatch: selectedRow?.paymentUpiMismatch, buyerMarkedPaid: selectedRow?.buyerMarkedPaid, buyerFraudAgreementAccepted: selectedRow?.buyerFraudAgreementAccepted, paymentReviewOutcome: selectedRow?.paymentReviewOutcome, addons: selectedRow?.addons })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(AdminOrderEditorView, { open: drawerOpen, onClose: () => setDrawerOpen(false), orderId: selectedRow?.id, orderLabel: selectedRow?.primary, currentStatus: selectedRow?.status, items: selectedRow?.items, paymentProofUrl: selectedRow?.paymentProofUrl, paymentTransactionId: selectedRow?.paymentTransactionId, paymentMethod: selectedRow?.paymentMethod, paymentStatus: selectedRow?.paymentStatus, displayedUpiId: selectedRow?.displayedUpiId, buyerReportedUpiId: selectedRow?.buyerReportedUpiId, paymentUpiMismatch: selectedRow?.paymentUpiMismatch, buyerMarkedPaid: selectedRow?.buyerMarkedPaid, buyerFraudAgreementAccepted: selectedRow?.buyerFraudAgreementAccepted, paymentReviewOutcome: selectedRow?.paymentReviewOutcome, addons: selectedRow?.addons, sourceContext: selectedRow?.sourceContext, currency: selectedRow?.currency })] }));
 }

package/dist/features/admin/components/OwnerQuickActions.js

@@ -236,6 +236,28 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
      * 🛑 `inline-flex`, never `w-full`. In normal flow this must shrink to its
      * own content — a full-width bar would read as a section divider and would
      * stretch across a card body it is only a corner of.
+     *
+     * 🛑 `shrink-0` IS THE MOBILE FIX, and it is one word because the bug was
+     * one missing word.
+     *
+     * A flex item's default is `flex-shrink: 1`, so in the title/actions row
+     * this toolbar lives in — `<Row justify="between">` with an `<h1>` on the
+     * left — the heading and the toolbar compete for width, and at ~390px the
+     * toolbar LOSES. It compresses below its own content: the icons slide under
+     * each other, the padding collapses, and the 44px tap targets stop being
+     * 44px wide. That is the "works incorrectly on mobile" report.
+     *
+     * With `shrink-0` the toolbar keeps its intrinsic size and the HEADING gives
+     * way instead — which is right, because a heading wraps gracefully onto a
+     * second line and a row of hit targets does not.
+     *
+     * 🛑 Note what this is NOT: the desktop fix (`d94496c42`) gave the toolbar a
+     * container and added an audit whose two rules are about DOM ORDER — must
+     * come after the `<h1>`, must not share the heading's row unless that row is
+     * `justify="between"`. Both pass here. R2's exemption actively WHITELISTS
+     * the layout that breaks, so the surfaces that satisfy that audit are
+     * precisely the ones most likely to be wrong at phone width. A source-order
+     * rule cannot see a width problem.
      */
     const boxClass = onDark
         ? /*
@@ -244,12 +266,12 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
            * LIGHT background in every light theme, so a themed box on a dark hero
            * photo is a white rectangle over the artwork.
            */
-            "inline-flex rounded-[var(--appkit-radius-lg)] bg-black/55 backdrop-blur-sm p-[var(--appkit-space-1)] shadow-md"
+            "inline-flex shrink-0 rounded-[var(--appkit-radius-lg)] bg-black/55 backdrop-blur-sm p-[var(--appkit-space-1)] shadow-md"
         : /*
            * Off media: the real surface tokens, so it inverts with the theme
            * instead of being a fixed near-white that disappears in dark mode.
            */
-            "inline-flex rounded-[var(--appkit-radius-lg)] bg-[var(--appkit-color-surface-elevated)] border border-[var(--appkit-color-border)] p-[var(--appkit-space-1)] shadow-sm";
+            "inline-flex shrink-0 rounded-[var(--appkit-radius-lg)] bg-[var(--appkit-color-surface-elevated)] border border-[var(--appkit-color-border)] p-[var(--appkit-space-1)] shadow-sm";
     return (_jsxs(_Fragment, { children: [_jsxs(Row, { gap: "xs", align: "center", className: `${boxClass} ${className}`.trim(), 
                 /*
                  * Stops the click reaching an ancestor `<Link>` or the card's own

package/dist/features/admin/constants/filter-tabs.d.ts

@@ -457,6 +457,9 @@ export declare const ADMIN_COUPON_TYPE_TABS: readonly [{
 }, {
     readonly id: "buy_x_get_y";
     readonly label: "Buy X Get Y";
+}, {
+    readonly id: "points_earn";
+    readonly label: "Points Back";
 }];
 /** Empty-sentinel variant for views (like SellerBidsView) that drive the
  *  filter URL with `""` instead of `"All"` so the `"" == no filter` invariant
@@ -757,6 +760,9 @@ export declare const ADMIN_PAYMENT_CASE_KIND_TABS: readonly [{
 }, {
     readonly id: "shipping_unpriced";
     readonly label: "Shipping unpriced";
+}, {
+    readonly id: "courier_unavailable";
+    readonly label: "Courier unavailable";
 }, {
     readonly id: "dead_job";
     readonly label: "Dead job";

package/dist/features/admin/constants/filter-tabs.js

@@ -245,6 +245,11 @@ export const ADMIN_COUPON_TYPE_TABS = [
     { id: "fixed", label: "Fixed" },
     { id: "free_shipping", label: "Free Shipping" },
     { id: "buy_x_get_y", label: "Buy X Get Y" },
+    // D51. `audit-filter-tab-enums`' COVERAGE rule fails on a real union value
+    // with no chip — which is what it was extended to catch after ten such gaps
+    // were found at once (Root Cause #72), including sellers being unable to
+    // filter their own `in_review` listings.
+    { id: "points_earn", label: "Points Back" },
 ];
 // ---------------------------------------------------------------------------
 // Seller-dashboard filter-chip tab sets
@@ -441,6 +446,7 @@ export const ADMIN_PAYMENT_CASE_KIND_TABS = [
     { id: "protection_claim", label: "Protection claim" },
     { id: "grievance", label: "Grievance" },
     { id: "shipping_unpriced", label: "Shipping unpriced" },
+    { id: "courier_unavailable", label: "Courier unavailable" },
     { id: "dead_job", label: "Dead job" },
     { id: "ledger_drift", label: "Points drift" },
 ];

package/dist/features/admin/constants/site-settings-tabs.d.ts

@@ -102,7 +102,7 @@ export declare const SITE_SETTINGS_TABS: readonly [{
     readonly description: "Which listing types sellers may create, and their defaults.";
     readonly keywords: ["listing types", "auctions on", "enable", "categories"];
 }];
-export declare const SITE_SETTINGS_TAB_IDS: ("about" | "shipping" | "notifications" | "contact" | "auction" | "seo" | "listings" | "appearance" | "emi" | "gst" | "watermark" | "integrations" | "limits" | "announcement" | "branding" | "themes" | "fees" | "legal" | "procurement")[];
+export declare const SITE_SETTINGS_TAB_IDS: ("about" | "shipping" | "notifications" | "contact" | "auction" | "seo" | "listings" | "emi" | "legal" | "appearance" | "gst" | "watermark" | "integrations" | "limits" | "announcement" | "branding" | "themes" | "fees" | "procurement")[];
 /**
  * The union `?tab=` is validated against.
  *

package/dist/features/admin/hooks/useAdminListingData.js

@@ -2,6 +2,9 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient, ApiClientError } from "../../../http/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
+// The defining module, not a barrel (Root Cause #18). `hasEncPrefix` is a pure
+// string test with no crypto in its import chain, so it is client-safe.
+import { hasEncPrefix } from "../../../security/pii-mask.js";
 function withQueryParams(endpoint, params) {
     const hasQuery = endpoint.includes("?");
     const query = new URLSearchParams(params).toString();
@@ -50,6 +53,19 @@ export function toRecordArray(value) {
 }
 export function toStringValue(value, fallback = "-") {
     if (typeof value === "string") {
+        /*
+         * 🛑 Ciphertext is not a display value. See the twin in
+         * `features/seller/hooks/useSellerListingData.ts` for the full account —
+         * the short version is that `mapDoc` does not decrypt, so a route that
+         * forgets `revealOrders`/`maskedOrders` hands this a stored `enc:v1:…`
+         * blob which is a perfectly ordinary `string` and renders verbatim.
+         *
+         * `/api/admin/orders` already hit this ("measured live at 3 visible
+         * `enc:v1:` strings") and fixed it at the route. This is the backstop for
+         * the next one.
+         */
+        if (hasEncPrefix(value))
+            return fallback;
         return value.trim() || fallback;
     }
     if (typeof value === "number" || typeof value === "boolean") {

package/dist/features/admin/schemas/admin-user-form.d.ts

@@ -82,13 +82,13 @@ export declare const lotteryPullSchema: z.ZodObject<{
     userPhone: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
 }, "strip", z.ZodTypeAny, {
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone?: string | undefined;
 }, {
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone?: string | undefined;

package/dist/features/admin/schemas/firestore.d.ts

@@ -690,6 +690,36 @@ export interface SiteSettingsDocument extends BaseDocument {
     returns: {
         windowDays: number;
     };
+    /**
+     * The support integration's on/off switch.
+     *
+     * 🛑 The ONLY new integration flag. The other three the admin page switches
+     * already have an authoritative field — `payment.razorpayEnabled`,
+     * `messaging.emailEnabled` (which `guardSend` reads), and
+     * `shipping.provider`. Adding a parallel `integrationSwitches.*` beside
+     * those would be a denormalised mirror that drifts the first time one path
+     * writes only one of a pair (Root Cause #42), and the page would then
+     * disagree with the code that enforces it. The page is a VIEW over the real
+     * fields; this is the one field that did not exist.
+     *
+     * 🛑 Also not under `siteSettings.integrations` — that key is live and holds
+     * analytics/tag IDs (GA, FB Pixel, GTM).
+     *
+     * OFF hides the WHOLE support surface from BUYERS: no nav entry, no ticket
+     * list, no contact form. Staff keep full access, so an open ticket is still
+     * workable and the employee pay-per-ticket basis survives.
+     *
+     * 🛑 A buyer mid-conversation loses sight of their thread. That is the
+     * owner's decision, accepted knowingly — and the admin row must SAY it
+     * rather than implying the switch only stops new tickets.
+     *
+     * Defaults to `true`: support being reachable is the safe state, and a
+     * settings document written before this field existed must not read as
+     * "support is off".
+     */
+    support: {
+        enabled: boolean;
+    };
     faq: {
         variables: {
             shippingDays: number;

package/dist/features/admin/schemas/firestore.js

@@ -377,6 +377,11 @@ export const DEFAULT_SITE_SETTINGS_DATA = {
     returns: {
         windowDays: 7,
     },
+    // Reachable is the safe default, and an older settings document with no
+    // `support` group must not read as "support is off".
+    support: {
+        enabled: true,
+    },
     announcementBar: {
         enabled: true,
         message: "🎉 Up to 15% Off on Pokémon TCG this week — Use code SAVE15",

package/dist/features/audit-log/schemas/firestore.d.ts

@@ -44,6 +44,21 @@ export declare const AdminAuditActionValues: {
      * same class as `payout_mark_paid` and `coupon_update`, which are both here.
      */
     readonly POINTS_ADJUST: "points_adjust";
+    /**
+     * Staff added a buyer-facing dispute reason.
+     *
+     * 🛑 Here because the list is POLICY VOCABULARY, even though no single row
+     * decides money. The reasons are what buyers are offered when something goes
+     * wrong, so the wording shapes what gets reported and how it is triaged —
+     * and a badly-worded or leading option is the kind of thing that is only
+     * ever noticed later, by which time "who added this, and when" is the
+     * question. `createdByName` on the row answers it for the list; this answers
+     * it in the one place an admin looks for "what have staff done lately".
+     *
+     * Recorded only on a REAL creation. Re-adding wording that already exists
+     * returns the existing row, which is not an act worth logging.
+     */
+    readonly DISPUTE_REASON_CREATE: "dispute_reason_create";
 };
 export type AdminAuditAction = (typeof AdminAuditActionValues)[keyof typeof AdminAuditActionValues];
 export interface AdminAuditLogDocument extends BaseDocument {
@@ -97,5 +112,20 @@ export declare const ADMIN_AUDIT_LOG_FIELDS: {
          * same class as `payout_mark_paid` and `coupon_update`, which are both here.
          */
         readonly POINTS_ADJUST: "points_adjust";
+        /**
+         * Staff added a buyer-facing dispute reason.
+         *
+         * 🛑 Here because the list is POLICY VOCABULARY, even though no single row
+         * decides money. The reasons are what buyers are offered when something goes
+         * wrong, so the wording shapes what gets reported and how it is triaged —
+         * and a badly-worded or leading option is the kind of thing that is only
+         * ever noticed later, by which time "who added this, and when" is the
+         * question. `createdByName` on the row answers it for the list; this answers
+         * it in the one place an admin looks for "what have staff done lately".
+         *
+         * Recorded only on a REAL creation. Re-adding wording that already exists
+         * returns the existing row, which is not an act worth logging.
+         */
+        readonly DISPUTE_REASON_CREATE: "dispute_reason_create";
     };
 };

package/dist/features/audit-log/schemas/firestore.js

@@ -42,6 +42,21 @@ export const AdminAuditActionValues = {
      * same class as `payout_mark_paid` and `coupon_update`, which are both here.
      */
     POINTS_ADJUST: "points_adjust",
+    /**
+     * Staff added a buyer-facing dispute reason.
+     *
+     * 🛑 Here because the list is POLICY VOCABULARY, even though no single row
+     * decides money. The reasons are what buyers are offered when something goes
+     * wrong, so the wording shapes what gets reported and how it is triaged —
+     * and a badly-worded or leading option is the kind of thing that is only
+     * ever noticed later, by which time "who added this, and when" is the
+     * question. `createdByName` on the row answers it for the list; this answers
+     * it in the one place an admin looks for "what have staff done lately".
+     *
+     * Recorded only on a REAL creation. Re-adding wording that already exists
+     * returns the existing row, which is not an act worth logging.
+     */
+    DISPUTE_REASON_CREATE: "dispute_reason_create",
 };
 export const ADMIN_AUDIT_LOG_FIELDS = {
     ACTOR_UID: "actorUid",

package/dist/features/auth/permissions/constants.js

@@ -344,6 +344,19 @@ export const ROUTE_PERMISSION_MAP = {
     // Payment protection — admin-only, see the permission union's own 🛑 note.
     "/admin/money-cases": "admin:payment-cases:read",
     "/admin/protection-claims": "admin:protection-claims:read",
+    /*
+     * Phase 7 invoicing — the GSTR-1 draft export.
+     *
+     * 🛑 `settings:write` rather than a new permission, and that is a judgement
+     * worth stating. The page exports the company's tax position for a quarter
+     * plus every buyer's place of supply; the set of people who should see that
+     * is the set who can already change the GSTIN and the fee schedule, which is
+     * exactly what `settings:write` names. Minting
+     * `admin:invoicing:read` would add a permission with one route and one
+     * holder — a distinction with no decision behind it, which is how a
+     * permission union becomes unreadable.
+     */
+    "/admin/invoicing": "admin:settings:write",
 };
 /**
  * Every capability, as a runtime value.

package/dist/features/cart/components/CartPriceBreakdown.d.ts

@@ -32,6 +32,11 @@ export interface CartPriceBreakdownStore {
     supportsShippingProtection: boolean;
     supportsSaleProtection: boolean;
     hasFinalSaleItem: boolean;
+    /** D46/D47 + decision 22 — whether this seller accepts points, and how many. */
+    acceptsPoints: boolean;
+    pointsApplied: number;
+    /** S5a — handling + extra shipping legs for this store's order. */
+    sharedPurchaseFee: number;
 }
 /** Mirrors `CheckoutPricingPreview` without importing server code. */
 export interface CartPriceBreakdownData {
@@ -46,7 +51,15 @@ export interface CartPriceBreakdownData {
     couponDiscount: number;
     platformFee: number;
     gstOnFee: number;
+    /** S5a — handling + extra shipping legs across the cart. */
+    sharedPurchaseFee: number;
     total: number;
+    /** D46/D47 — points applied across every accepting store. */
+    pointsApplied: number;
+    /** What the buyer actually pays: `total − pointsApplied`. */
+    amountDue: number;
+    /** Their remaining balance, for the toggle's own label. */
+    pointsBalance: number;
     stores: CartPriceBreakdownStore[];
 }
 export interface CartPriceBreakdownProps {

package/dist/features/cart/components/CartPriceBreakdown.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Div, Row, Stack, Text } from "../../../ui/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 function Line({ label, amount, tone = "muted", strong = false, }) {
@@ -21,5 +21,9 @@ export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unava
     const subtotalLabel = itemCount !== undefined
         ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""}${storeCount > 1 ? `, ${storeCount} stores` : ""})`
         : "Subtotal";
-    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: true }) }), preview.gstAmount > 0 && (_jsxs(Text, { size: "xs", color: "muted", children: ["Includes GST of ", money(preview.gstAmount)] })), errorNote ? (_jsx(Text, { size: "xs", color: "error", children: errorNote })) : (isLoading && (_jsx(Text, { size: "xs", color: "muted", children: "Updating\u2026" })))] }));
+    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
+                    ? "Your points could not be applied to this order."
+                    : storeCount > 1
+                        ? "None of these sellers accepts points."
+                        : "This seller does not accept points." })), preview.gstAmount > 0 && (_jsxs(Text, { size: "xs", color: "muted", children: ["Includes GST of ", money(preview.gstAmount)] })), errorNote ? (_jsx(Text, { size: "xs", color: "error", children: errorNote })) : (isLoading && (_jsx(Text, { size: "xs", color: "muted", children: "Updating\u2026" })))] }));
 }

package/dist/features/cart/components/PointsTenderPicker.d.ts

@@ -0,0 +1,61 @@
+import React from "react";
+/**
+ * "Pay with my points" — one checkbox for the whole cart (D46/D47).
+ *
+ * ## Why ONE control for the cart, where add-ons get one per store
+ *
+ * An add-on is a thing the buyer buys from a particular seller, so choosing it
+ * per seller is the only coherent shape. Points are the buyer's own balance:
+ * they do not belong to a seller, and asking "how many of your points would you
+ * like to spend at each of these three shops" is a question nobody wants to
+ * answer. So the buyer opts in once and the server spends what it can, in group
+ * order, at the sellers who accept them (decision 22).
+ *
+ * ## 🛑 A checkbox and NOT a number input, deliberately
+ *
+ * Decision 24: tick it and as many points as the 50% cap allows are applied;
+ * whatever cannot be applied stays in the balance for a later order. Nothing is
+ * forfeited, so there is no amount worth agonising over — and more importantly,
+ * an amount the client can send is an amount the client can lie about. The
+ * figure is always derived server-side from the live balance.
+ *
+ * ## It renders nothing when there is nothing to offer
+ *
+ * A zero balance gets no control at all rather than a disabled one. A disabled
+ * checkbox beside "0 points" is an advertisement, and the place to advertise
+ * the programme is the points page, not the cart of somebody who cannot use it.
+ */
+export interface PointsTenderPickerProps {
+    /** Current cart flag. */
+    value: boolean;
+    onChange: (next: boolean) => void;
+    /**
+     * The buyer's live balance, in points (1 point = ₹1).
+     *
+     * 🛑 Zero when the cart has not opted in, because the server only reads a
+     * balance it is going to use — so this cannot be relied on to decide whether
+     * to RENDER. `hasBalance` below exists for that.
+     */
+    balance: number;
+    /**
+     * Points actually applied to this cart, from the server preview. Undefined
+     * while the preview is in flight.
+     */
+    applied?: number;
+    /**
+     * Whether the buyer has ANY points, independent of the opt-in state.
+     *
+     * Separate from `balance` for the reason above: with the toggle off the
+     * preview returns `pointsBalance: 0`, so a control gated on `balance > 0`
+     * could never be switched back on once switched off — a one-way door, the
+     * `BackToTop` failure in Root Cause #41.
+     */
+    hasBalance: boolean;
+    /** No store in the cart accepts points — the control says so instead of hiding. */
+    noAcceptingStore?: boolean;
+    currency?: string;
+    disabled?: boolean;
+    disabledReason?: string;
+    className?: string;
+}
+export declare function PointsTenderPicker({ value, onChange, balance, applied, hasBalance, noAcceptingStore, currency, disabled, disabledReason, className, }: PointsTenderPickerProps): React.JSX.Element | null;

package/dist/features/cart/components/PointsTenderPicker.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { IconBox } from "../../../ui/components/IconBox.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+export function PointsTenderPicker({ value, onChange, balance, applied, hasBalance, noAcceptingStore = false, currency = "INR", disabled = false, disabledReason, className = "", }) {
+    if (!hasBalance)
+        return null;
+    const shownBalance = value ? balance : 0;
+    return (_jsx(Div, { surface: "muted", rounded: "lg", padding: "sm", className: className, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { align: "center", gap: "sm", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "brand", rounded: "lg", children: _jsx(Icon, { name: "points", size: "sm" }) }), _jsx(Div, { className: "min-w-0 flex-1", children: _jsx(FieldCheckbox, { name: "useAllPoints", label: "Pay with my points", checked: value, onChange: onChange, disabled: disabled || noAcceptingStore }) })] }), noAcceptingStore ? (_jsx(Text, { size: "xs", color: "muted", children: "Points cannot be used with the seller(s) in this cart." })) : disabled && disabledReason ? (_jsx(Text, { size: "xs", color: "muted", children: disabledReason })) : value && applied !== undefined ? (applied > 0 ? (_jsxs(Text, { size: "xs", color: "muted", children: [applied.toLocaleString("en-IN"), " points applied (", formatCurrency(applied, currency), ")", shownBalance > applied
+                            ? ` · ${(shownBalance - applied).toLocaleString("en-IN")} left over`
+                            : ""] })) : (_jsx(Text, { size: "xs", color: "muted", children: "No points could be applied to this order." }))) : (_jsx(Text, { size: "xs", color: "muted", children: "Up to half of an order can be paid with points." }))] }) }));
+}

package/dist/features/cart/components/StoreAddonsPicker.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Gift, ShieldAlert, ShieldCheck, ShieldOff } from "lucide-react";
 import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { Disclaimer } from "../../../ui/components/Disclaimer.js";
 import { IconBox } from "../../../ui/components/IconBox.js";
 import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox.js";
 import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
@@ -54,5 +55,5 @@ export function StoreAddonsPicker({ storeId, storeSubtotal, value, onChange, rat
                             ? "This seller does not offer shipment or sale protection."
                             : shippingDeclined
                                 ? "This seller does not offer shipment protection."
-                                : "This seller does not offer sale protection." })] })), saleBlockedByFinalSale && (_jsxs(Row, { gap: "sm", align: "start", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "muted", children: _jsx(ShieldOff, { size: 14 }) }), _jsx(Text, { size: "xs", color: "muted", className: "flex-1 min-w-0", children: "Sale protection is not available \u2014 this basket contains a final-sale item. Shipment protection is unaffected." })] }))] }));
+                                : "This seller does not offer sale protection." })] })), saleBlockedByFinalSale && (_jsxs(Row, { gap: "sm", align: "start", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "muted", children: _jsx(ShieldOff, { size: 14 }) }), _jsx(Text, { size: "xs", color: "muted", className: "flex-1 min-w-0", children: "Sale protection is not available \u2014 this basket contains a final-sale item. Shipment protection is unaffected." })] })), (shippingOffered || saleOffered) && _jsx(Disclaimer, { id: "protection-cover", inline: true })] }));
 }

package/dist/features/cart/components/index.d.ts

@@ -7,6 +7,8 @@ export { CartSummary } from "./CartSummary";
 export type { CartSummaryProps } from "./CartSummary";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./StoreAddonsPicker";
 export type { StoreAddonsPickerProps, StoreAddonsValue, StoreAddonsRates, } from "./StoreAddonsPicker";
+export { PointsTenderPicker } from "./PointsTenderPicker";
+export type { PointsTenderPickerProps } from "./PointsTenderPicker";
 export { CartPriceBreakdown } from "./CartPriceBreakdown";
 export type { CartPriceBreakdownProps, CartPriceBreakdownData, CartPriceBreakdownStore, } from "./CartPriceBreakdown";
 export { CheckoutView } from "./CheckoutView";

package/dist/features/cart/components/index.js

@@ -3,6 +3,7 @@ export { CartGroupLineRow } from "./CartGroupLineRow.js";
 export { CartView } from "./CartView.js";
 export { CartSummary } from "./CartSummary.js";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./StoreAddonsPicker.js";
+export { PointsTenderPicker } from "./PointsTenderPicker.js";
 export { CartPriceBreakdown } from "./CartPriceBreakdown.js";
 export { CheckoutView } from "./CheckoutView.js";
 export { CheckoutAddressStep } from "./CheckoutAddressStep.js";