@mohasinac/appkit 4.60.1 → 4.62.0

package/dist/features/inventory/components/ReceiveStationView.js

@@ -31,6 +31,8 @@ import { apiClient } from "../../../http/index.js";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { operatorMessage } from "./operator-message.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { trackError, ErrorCategory, ErrorSeverity, } from "../../../monitoring/error-tracking.js";
 import { MAX_RECEIVE_ROWS } from "../schemas/firestore.js";
 /** `boxId::productId` — the staging table's natural key, mirroring `placementId`. */
 function rowKey(boxId, productId) {
@@ -67,6 +69,21 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
         rowsRef.current = computed;
         setRows(computed);
     }
+    /**
+     * Drop one staged row. Named rather than inline in the table's Remove
+     * button, where the updater's block body sat a brace too deep.
+     */
+    function removeRow(key) {
+        applyRows((c) => {
+            const next = { ...c };
+            delete next[key];
+            return next;
+        });
+    }
+    /** Set one staged row's quantity. Same reason as `removeRow`. */
+    function setRowQuantity(key, quantity) {
+        applyRows((c) => ({ ...c, [key]: { ...c[key], quantity } }));
+    }
     const [scan, setScan] = useState("");
     const [committing, setCommitting] = useState(false);
     /** The in-flight guard. State renders the spinner; this prevents the second send. */
@@ -197,6 +214,12 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
      * It runs only on a miss, so the common case stays instant and a box-arm is
      * roughly one scan in twenty anyway.
      */
+    /*
+     * Three outcomes, and the third is the point: `BoxOption` (found), `null`
+     * (asked, no such box), `undefined` (could not ask). The caller used to see
+     * only the first two and told the operator "No box registered as …" for a
+     * network failure.
+     */
     async function resolveBoxFromServer(code) {
         const bare = code.startsWith("BOX-") ? code.slice(4) : code;
         try {
@@ -206,10 +229,26 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
                 ? { id: hit.id, code: hit.code, location: hit.location ?? null }
                 : null;
         }
-        catch {
-            // A failed lookup must not masquerade as "no such box" — the caller
-            // distinguishes the two in what it tells the operator.
-            return null;
+        catch (err) {
+            /*
+             * 🛑 The predecessor comment here claimed "a failed lookup must not
+             * masquerade as 'no such box' — the caller distinguishes the two". It
+             * could not: the success path returns `null` on a miss and this returned
+             * the same `null`, so the two were indistinguishable by construction and
+             * a network failure WAS reported to the operator as an unrecognised
+             * code. That is the exact confusion the function's own header says it
+             * exists to prevent.
+             *
+             * Classified and recorded rather than swallowed, and `undefined` now
+             * means "could not ask" while `null` keeps meaning "asked, no such box".
+             */
+            const n = normalizeError(err);
+            trackError(n.message, ErrorCategory.API, ErrorSeverity.MEDIUM, {
+                component: "ReceiveStationView",
+                action: "resolveBoxFromServer",
+                metadata: { code: bare },
+            });
+            return undefined;
         }
     }
     async function handleScan(raw) {
@@ -235,10 +274,18 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
                 setLastScan({ text: `Armed ${fetched.code}`, tone: "ok" });
                 return;
             }
-            setLastScan({
-                text: `No box registered as ${code.slice(4)} — register it first`,
-                tone: "bad",
-            });
+            setLastScan(fetched === undefined
+                ? {
+                    // "Could not ask" — never "does not exist". The operator is
+                    // holding the box; telling them it is unregistered sends them
+                    // to re-register something that is already in the system.
+                    text: `Could not check ${code.slice(4)} — connection problem, scan again`,
+                    tone: "bad",
+                }
+                : {
+                    text: `No box registered as ${code.slice(4)} — register it first`,
+                    tone: "bad",
+                });
             return;
         }
         const item = byCode.get(code);
@@ -362,7 +409,11 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
             setLastScan({ text: "Committed. Carry on.", tone: "ok" });
         }
         catch (err) {
-            showToast(operatorMessage(err), "error");
+            // Normalized first: `operatorMessage` duck-types `.status`/`.code`/
+            // `.message`, and the api/app branches of `NormalizedError` carry exactly
+            // those three — so the 4xx passthrough still works and every other kind
+            // correctly falls through to a constant instead of server text.
+            showToast(operatorMessage(normalizeError(err)), "error");
         }
         finally {
             committingRef.current = false;
@@ -382,14 +433,7 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
                                         return (_jsxs(Tr, { children: [_jsx(Td, { children: _jsx(Badge, { variant: "info", children: r.boxCode }) }), _jsx(Td, { children: r.productTitle }), _jsx(Td, { children: _jsx(Text, { numeric: true, size: "sm", children: r.code ?? "—" }) }), _jsx(Td, { children: _jsx(QuantityStepper, { value: r.quantity, min: 1, max: 9999, 
                                                         // Many steppers on one page, so a bare "Quantity"
                                                         // names none of them.
-                                                        ariaLabel: `Quantity of ${r.productTitle} for ${r.boxCode}`, onChange: (n) => applyRows((c) => ({
-                                                            ...c,
-                                                            [key]: { ...c[key], quantity: n },
-                                                        })) }) }), _jsx(Td, { children: _jsx(Button, { variant: "ghost", onClick: () => applyRows((c) => {
-                                                            const next = { ...c };
-                                                            delete next[key];
-                                                            return next;
-                                                        }), children: "Remove" }) })] }, key));
+                                                        ariaLabel: `Quantity of ${r.productTitle} for ${r.boxCode}`, onChange: (n) => setRowQuantity(key, n) }) }), _jsx(Td, { children: _jsx(Button, { variant: "ghost", onClick: () => removeRow(key), children: "Remove" }) })] }, key));
                                     }) })] }))] }) }), _jsx(Card, { variant: "default", children: _jsxs(CardBody, { children: [_jsx(Heading, { level: 2, size: "lg", children: "Add by hand" }), items.length === 0 ? (_jsx(Text, { color: "muted", children: "No linked items on this shipment yet." })) : (_jsxs(Table, { children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { children: "Item" }), _jsx(Th, { children: "Scan code" }), _jsx(Th, { children: "Expected" }), _jsx(Th, { children: "Add" })] }) }), _jsx(Tbody, { children: items.map((it) => (_jsxs(Tr, { children: [_jsx(Td, { children: it.productTitle }), _jsx(Td, { children: _jsx(Text, { numeric: true, size: "sm", children: it.barcodeId ??
                                                         it.sku ??
                                                         "no code yet — add by hand, or run the SKU backfill" }) }), _jsx(Td, { children: it.expectedQuantity }), _jsx(Td, { children: _jsx(Button, { variant: "outline", 

package/dist/features/inventory/repository/storage-boxes.repository.d.ts

@@ -37,7 +37,9 @@ export declare class StorageBoxesRepository extends BaseRepository<StorageBoxDoc
      * recurse, which is the entire reason for the choice.
      */
     setRollup(id: string, distinctProducts: number, totalUnits: number): Promise<void>;
-    listForAdmin(model: SieveModel): Promise<FirebaseSieveResult<StorageBoxDocument>>;
+    listForAdmin(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<StorageBoxDocument>>;
     /** Every Timestamp field carries `parseSieveDateValue` — Root Cause #47. */
     static readonly SIEVE_FIELDS: {
         id: {

package/dist/features/inventory/repository/storage-boxes.repository.js

@@ -15,9 +15,13 @@
  * @tag access:server
  * @tag sideEffects:firestore
  */
-import { BaseRepository, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { BaseRepository, parseSieveDateValue, applySieveToFirestore, } from "../../../providers/db-firebase/index.js";
 import { generateStorageBoxId } from "../../../utils/id-generators.js";
 import { buildStorageBoxSearchTxt } from "../../../utils/search-txt-builders.js";
+// The shared three — hand-writing them is how ten repositories each ended up
+// with two of the three, which reads as a working multi-word search and
+// silently cannot reach page 2.
+import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../utils/search-txt-query.js";
 import { BoxStatusValues, BoxTypeValues, STORAGE_BOXES_COLLECTION, STORAGE_BOX_FIELDS, } from "../schemas/firestore.js";
 /**
  * `AC60-03` → ordinal 3.
@@ -100,8 +104,37 @@ export class StorageBoxesRepository extends BaseRepository {
             updatedAt: new Date(),
         });
     }
-    async listForAdmin(model) {
-        return this.sieveQuery(model, StorageBoxesRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 50 });
+    async listForAdmin(model, opts) {
+        /*
+         * 🛑 `searchTxt` HAD NO READER. `buildStorageBoxSearchTxt` wrote tokens on
+         * every create and update, `SIEVE_FIELDS` listed the field as filterable,
+         * and `AdminStorageBoxesView` rendered a search box promising "Search by
+         * code or location" — and this method ignored the term entirely. Typing in
+         * it returned the unfiltered list with a 200, which reads as "no box
+         * matches that" only if you already know the box exists.
+         *
+         * Same two-part shape as the other migrated collections: `plan.head` is
+         * one `array-contains` on the longest term, `plan.rest` is AND-refined in
+         * memory. Via `planSearchTxt` for the `empty` guard — a query that
+         * normalises to no usable token must return NOTHING, because emitting no
+         * clause returns the whole collection and calls it a search result.
+         */
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        if (!plan.head) {
+            return this.sieveQuery(model, StorageBoxesRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 50 });
+        }
+        const baseQuery = this.getCollection().where(STORAGE_BOX_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        const win = beginSearchWindow(model, plan);
+        const result = await applySieveToFirestore({
+            baseQuery,
+            model: win.model,
+            options: { maxPageSize: win.maxPageSize(100) },
+            fields: StorageBoxesRepository.SIEVE_FIELDS,
+            mapDoc: (snap) => this.mapDoc(snap),
+        });
+        return win.finish(result);
     }
 }
 /** Every Timestamp field carries `parseSieveDateValue` — Root Cause #47. */

package/dist/features/layout/hooks/useFormBottomActions.js

@@ -3,6 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useContext, useMemo } from "react";
 import { FormShellContext } from "../../../ui/forms/FormShell.js";
 import { FormErrorList } from "../../../ui/forms/FormErrorList.js";
+import { Div } from "../../../ui/components/Div.js";
 import { useIsInsideOverlay } from "../../../ui/components/overlay-context.js";
 import { useBottomActions } from "./useBottomActions.js";
 /**
@@ -98,7 +99,25 @@ export function useFormBottomActions({ onSubmit, onCancel, submitLabel = "Save",
         infoLabel: showErrors
             ? `Fix ${errorCount} ${errorCount === 1 ? "issue" : "issues"}`
             : undefined,
-        infoPanel: showErrors && ctx ? _jsx(FormErrorList, { ctx: ctx }) : undefined,
+        /*
+         * 🛑 The alert region lives HERE, not in `FormErrorList`.
+         *
+         * Without it a failed submit on a phone announced nothing at all: the
+         * list has no role, `InfoPanel` has no role, and the only signal was the
+         * disclosure button's text changing — which a screen reader does not read
+         * out unprompted. This is the whole error surface on mobile, since
+         * `useBottomActions` defaults to `desktop: "hidden"`.
+         *
+         * It cannot go on `FormErrorList` itself: the list's other consumer is
+         * `<FormErrorSummary>`, whose wrapper is already `role="alert"`, and
+         * nesting one alert region inside another makes the announcement
+         * ambiguous and duplicated.
+         *
+         * `aria-live="polite"` rather than `role="alert"`'s implicit assertive —
+         * the user has just pressed Save and is expecting a response, so there is
+         * nothing to interrupt. Same choice `FormErrorSummary` makes.
+         */
+        infoPanel: showErrors && ctx ? (_jsx(Div, { role: "alert", "aria-live": "polite", children: _jsx(FormErrorList, { ctx: ctx }) })) : undefined,
         // Bumped by every submit attempt, so a second failed Save re-opens a
         // sheet the user collapsed — while an ordinary re-render does not.
         infoOpenSignal: showErrors ? ctx?.submitAttemptCount : undefined,

package/dist/features/obligations/repository/obligations.repository.js

@@ -1,5 +1,6 @@
 import { BaseRepository, prepareForFirestore } from "../../../providers/db-firebase/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
+import { serverLogger } from "../../../monitoring/index.js";
 import { OBLIGATIONS_COLLECTION, OBLIGATION_ACTIVE_STATES, OBLIGATION_FIELDS, createObligationId, } from "../schemas/firestore.js";
 export class ObligationsRepository extends BaseRepository {
     /*
@@ -138,7 +139,15 @@ export class ObligationsRepository extends BaseRepository {
             });
         }
         catch (err) {
-            void normalizeError(err);
+            /*
+             * Best effort, but RECORDED. `void normalizeError(err)` alone types the
+             * error and reports it nowhere — as silent as `catch {}` while looking
+             * handled, which is what audit-silent-degrade calls normalize theatre.
+             * Swallowing is still correct here (a warning marker is a derived hint; the next order write reconciles again); losing the reason is not.
+             */
+            serverLogger.warn("obligations.warn failed", {
+                error: normalizeError(err).message,
+            });
         }
     }
     /** Refs for a subject's obligations — used when an order is hard-deleted. */

package/dist/features/orders/components/EmiInstallmentsPanel.js

@@ -4,6 +4,7 @@ import { useState } from "react";
 import { Badge, Button, Div, Form, Row, Stack, Text, useToast } from "../../../ui/index.js";
 import { FieldInput } from "../../../ui/forms/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 import { normalizeError } from "../../../errors/normalize.js";
 function stateOf(i) {
     if (i.status === "paid")
@@ -28,19 +29,34 @@ export function EmiInstallmentsPanel({ orderId, installments, remainingBalance,
     const money = (value) => formatCurrency(value, currency);
     const ordered = [...installments].sort((a, b) => a.index - b.index);
     const outstanding = ordered.filter((i) => i.status !== "paid").length;
-    const submit = async (index) => {
+    /*
+     * Takes `setFieldError` from the <Form> render prop rather than closing
+     * over state, because the failure belongs ON the reference field.
+     *
+     * This panel used to be toast-only AND gate submission by disabling the
+     * button on an empty reference — so an incomplete form could not be sent
+     * and said nothing about why, and a rejected reference produced a toast
+     * that was gone before the buyer looked back at the input. Both are money
+     * surfaces on somebody's order.
+     */
+    const submit = async (index, fieldName, setFieldError) => {
+        const trimmed = reference.trim();
+        if (trimmed.length === 0) {
+            setFieldError(fieldName, "Enter the UTR or reference number from your transfer.");
+            return;
+        }
         setIsSubmitting(true);
         try {
-            await onSubmit({ installmentIndex: index, transactionId: reference.trim() });
+            await onSubmit({ installmentIndex: index, transactionId: trimmed });
             showToast("Payment reference submitted — the seller will confirm it.", "success");
             setOpenIndex(null);
             setReference("");
         }
         catch (err) {
-            void normalizeError(err);
-            // The action's own message is surfaced by the caller's error mapping;
-            // this only has to stop the panel pretending the submission landed.
-            showToast("Couldn't submit that payment. Please try again.", "error");
+            const normalized = normalizeError(err);
+            setFieldError(fieldName, toUserMessage(normalized.code, undefined, {
+                fallback: "Couldn't submit that payment reference. Please try again.",
+            }));
         }
         finally {
             setIsSubmitting(false);
@@ -49,9 +65,11 @@ export function EmiInstallmentsPanel({ orderId, installments, remainingBalance,
     return (_jsx(Div, { surface: "card", border: "default", rounded: "lg", padding: "md", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { weight: "semibold", children: "Your EMI plan" }), remainingBalance !== undefined && remainingBalance > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: [money(remainingBalance), " outstanding across ", outstanding, " instalment", outstanding === 1 ? "" : "s"] }))] }), _jsx(Text, { size: "xs", color: "muted", children: "You can pay any instalment whenever you like, including ahead of its due date \u2014 paying early settles the plan sooner and does not cost more." }), _jsx(Stack, { gap: "xs", children: ordered.map((inst) => {
                         const state = stateOf(inst);
                         const due = inst.dueDate ? new Date(inst.dueDate) : null;
+                        // Per-installment, so each open row's error is keyed to its own field.
+                        const fieldName = `emi-reference-${orderId}-${inst.index}`;
                         return (_jsxs(Div, { border: "default", rounded: "md", padding: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Text, { size: "sm", weight: "medium", children: ["Instalment ", inst.index, " \u00B7 ", money(inst.amount)] }), _jsx(Text, { size: "xs", color: "muted", children: due ? `Due ${due.toLocaleDateString()}` : "No due date recorded" })] }), _jsxs(Row, { align: "center", gap: "xs", className: "flex-shrink-0", children: [_jsx(Badge, { variant: state === "paid" ? "success" : state === "awaiting-review" ? "warning" : "default", children: STATE_LABEL[state] }), state === "payable" && (_jsx(Button, { type: "button", size: "sm", variant: "secondary", onClick: () => {
                                                         setOpenIndex(openIndex === inst.index ? null : inst.index);
                                                         setReference("");
-                                                    }, children: openIndex === inst.index ? "Cancel" : "Pay now" }))] })] }), openIndex === inst.index && (_jsx(Div, { className: "mt-3", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Transfer ", money(inst.amount), " to the seller, then enter the UTR or reference number so they can confirm it."] }), _jsx(FieldInput, { name: `emi-reference-${orderId}-${inst.index}`, label: "UTR / reference number", required: true, value: reference, onChange: setReference }), _jsx(Button, { type: "submit", size: "sm", isLoading: isSubmitting, disabled: reference.trim().length === 0 || isSubmitting, onClick: () => { void submit(inst.index); }, children: "Submit payment reference" })] })) }) }))] }, inst.index));
+                                                    }, children: openIndex === inst.index ? "Cancel" : "Pay now" }))] })] }), openIndex === inst.index && (_jsx(Div, { className: "mt-3", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Transfer ", money(inst.amount), " to the seller, then enter the UTR or reference number so they can confirm it."] }), _jsx(FieldInput, { name: fieldName, label: "UTR / reference number", required: true, value: reference, onChange: (v) => { clearErrors(); setReference(v); } }), _jsx(Button, { type: "submit", size: "sm", isLoading: isSubmitting, disabled: isSubmitting, onClick: () => { void submit(inst.index, fieldName, setFieldError); }, children: "Submit payment reference" })] })) }) }))] }, inst.index));
                     }) })] }) }));
 }

package/dist/features/orders/components/RefundRequestView.js

@@ -71,7 +71,7 @@ export function RefundRequestView({ order, onSubmitRequest, isLoading = false, c
             label: "Why are you returning this?",
             required: true,
             fields: ["reasonCode", "reasonNote"],
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "sm", color: "muted", children: [REFUND_COPY.request.orderTotalLabel, " ", _jsx(Span, { weight: "bold", children: formatCurrency(order.total, order.currency ?? "INR") })] }), hasFinalSaleLine && (_jsx(Alert, { variant: "warning", title: REFUND_COPY.request.finalSaleNoticeHeading, children: "You can\u2019t return it for a change of mind, but you can still claim if it never arrived, arrived damaged, was the wrong item, wasn\u2019t as described, or is counterfeit. Only those reasons are listed below." })), _jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", weight: "semibold", children: [REFUND_COPY.request.reasonSelectLabel, " ", _jsx(Span, { "aria-hidden": true, children: "*" })] }), _jsx(PaginatedSelect, { value: values.reasonCode === "" ? null : values.reasonCode, onChange: (v) => onChange({ reasonCode: v ?? "" }), options: allowedReasons.map((r) => ({
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "sm", color: "muted", children: [REFUND_COPY.request.orderTotalLabel, " ", _jsx(Span, { weight: "bold", children: formatCurrency(order.total, order.currency ?? "INR") })] }), hasFinalSaleLine && (_jsx(Alert, { variant: "warning", title: REFUND_COPY.request.finalSaleNoticeHeading, children: "You can\u2019t return it for a change of mind, but you can still claim if it never arrived, arrived damaged, was the wrong item, wasn\u2019t as described, or is counterfeit. Only those reasons are listed below." })), _jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", weight: "semibold", children: [REFUND_COPY.request.reasonSelectLabel, " ", _jsx(Span, { "aria-hidden": true, children: "*" })] }), _jsx(PaginatedSelect, { name: "reasonCode", error: errors.reasonCode, value: values.reasonCode === "" ? null : values.reasonCode, onChange: (v) => onChange({ reasonCode: v ?? "" }), options: allowedReasons.map((r) => ({
                                     value: r,
                                     label: RETURN_REASON_LABEL[r],
                                 })), placeholder: REFUND_COPY.request.reasonSelectPlaceholder, ariaLabel: REFUND_COPY.request.reasonSelectLabel })] }), _jsx(FieldTextarea, { name: "reasonNote", label: REFUND_COPY.request.reasonNoteLabel, value: values.reasonNote, onChange: (v) => onChange({ reasonNote: v }), rows: 3, maxLength: 500, showCharCount: true })] })),
@@ -81,9 +81,9 @@ export function RefundRequestView({ order, onSubmitRequest, isLoading = false, c
             label: REFUND_COPY.request.acknowledgeHeading,
             required: true,
             fields: ["acknowledged"],
-            render: ({ values, onChange }) => (_jsx(Stack, { gap: "sm", children: REFUND_COPY.request.acknowledgments.map((text, i) => (_jsx(Checkbox, { checked: values.acknowledged[i] ?? false, onChange: () => onChange({
-                        acknowledged: values.acknowledged.map((v, idx) => idx === i ? !v : v),
-                    }), label: _jsx(Text, { size: "sm", className: "leading-snug", children: text }), "aria-label": `Acknowledgment ${i + 1}` }, i))) })),
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "sm", children: [REFUND_COPY.request.acknowledgments.map((text, i) => (_jsx(Checkbox, { checked: values.acknowledged[i] ?? false, onChange: () => onChange({
+                            acknowledged: values.acknowledged.map((v, idx) => idx === i ? !v : v),
+                        }), label: _jsx(Text, { size: "sm", className: "leading-snug", children: text }), "aria-label": `Acknowledgment ${i + 1}`, "aria-invalid": errors.acknowledged ? "true" : undefined }, i))), errors.acknowledged && (_jsx(Text, { size: "sm", variant: "error", role: "alert", children: errors.acknowledged }))] })),
         },
     ], [order.total, order.currency, hasFinalSaleLine, allowedReasons]);
     const nav = useSectionFormNav(sections, draft);

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

@@ -1080,6 +1080,25 @@ export declare const ORDER_COLLECTION: "orders";
  * only list it belongs in. (I added it to both first; R1 would have failed.)
  */
 export declare const REFUND_CLAIMS_COLLECTION: "refundClaims";
+/**
+ * Field names on a refund-claim row.
+ *
+ * 🛑 `STATE`, and it is NOT `ADDRESS_FIELDS.STATE`.
+ * `audit-route-nav-field-constants` R3 suggested exactly that for the raw
+ * `where("state", …)` in `paymentReconcile` — a POSTAL state, on an address.
+ * Borrowing it would have made a refund-claim sweep read as though it filtered
+ * addresses. The field names here are the claim's own lifecycle.
+ *
+ * The collection has no document interface (it is written ad hoc by
+ * `processRefundAction` as an idempotency record), so this is the only place
+ * its field names are stated.
+ */
+export declare const REFUND_CLAIM_FIELDS: {
+    /** `"claimed"` while a refund is in flight — the idempotency latch. */
+    readonly STATE: "state";
+    readonly CLAIMED_AT: "claimedAt";
+    readonly ORDER_ID: "orderId";
+};
 export declare const ORDER_INDEXED_FIELDS: readonly ["searchTxt", "userId", "productId", "storeId", "status", "paymentStatus", "payoutStatus", "shippingMethod", "orderDate", "createdAt", "assignedWorkerId", "pickedAt", "packedAt"];
 export declare const DEFAULT_ORDER_DATA: Partial<OrderDocument>;
 export declare const ORDER_PUBLIC_FIELDS: readonly ["id", "productId", "productTitle", "quantity", "unitPrice", "totalPrice", "currency", "status", "paymentStatus", "shippingAddress", "trackingNumber", "notes", "orderDate", "shippingDate", "deliveryDate", "createdAt"];

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

@@ -73,6 +73,25 @@ export const ORDER_COLLECTION = "orders";
  * only list it belongs in. (I added it to both first; R1 would have failed.)
  */
 export const REFUND_CLAIMS_COLLECTION = "refundClaims";
+/**
+ * Field names on a refund-claim row.
+ *
+ * 🛑 `STATE`, and it is NOT `ADDRESS_FIELDS.STATE`.
+ * `audit-route-nav-field-constants` R3 suggested exactly that for the raw
+ * `where("state", …)` in `paymentReconcile` — a POSTAL state, on an address.
+ * Borrowing it would have made a refund-claim sweep read as though it filtered
+ * addresses. The field names here are the claim's own lifecycle.
+ *
+ * The collection has no document interface (it is written ad hoc by
+ * `processRefundAction` as an idempotency record), so this is the only place
+ * its field names are stated.
+ */
+export const REFUND_CLAIM_FIELDS = {
+    /** `"claimed"` while a refund is in flight — the idempotency latch. */
+    STATE: "state",
+    CLAIMED_AT: "claimedAt",
+    ORDER_ID: "orderId",
+};
 export const ORDER_INDEXED_FIELDS = [
     "searchTxt",
     "userId",

package/dist/features/orders/schemas/index.d.ts

@@ -53,8 +53,8 @@ export declare const emiInstallmentSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>]>>;
 }, "strip", z.ZodTypeAny, {
     status: "paid" | "pending" | "overdue";
-    amount: number;
     index: number;
+    amount: number;
     dueDate: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -68,8 +68,8 @@ export declare const emiInstallmentSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
     status: "paid" | "pending" | "overdue";
-    amount: number;
     index: number;
+    amount: number;
     dueDate: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -405,8 +405,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">>]>>;
     }, "strip", z.ZodTypeAny, {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -420,8 +420,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough"> | undefined;
     }, {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -684,8 +684,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     emiSurchargeAmount?: number | undefined;
     emiInstallments?: {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -838,8 +838,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     emiSurchargeAmount?: number | undefined;
     emiInstallments?: {
         status: "paid" | "pending" | "overdue";
-        amount: number;
         index: number;
+        amount: number;
         dueDate: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;

package/dist/features/payment-cases/repository/payment-cases.repository.d.ts

@@ -2,6 +2,7 @@ import type { DocumentReference } from "firebase-admin/firestore";
 import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository } from "../../../providers/db-firebase";
 import { type PaymentCaseDocument, type PaymentCaseKind, type PaymentCaseSeverity, type PaymentCaseStatus } from "../schemas/firestore";
+/** gRPC `ALREADY_EXISTS` — the one `.create()` failure meaning "we have it". */
 export interface OpenCaseInput {
     kind: PaymentCaseKind;
     /** Identifies THE PROBLEM, not the observation — see `createPaymentCaseId`. */

package/dist/features/payment-cases/repository/payment-cases.repository.js

@@ -1,20 +1,9 @@
+// One shared predicate — this file had its own copy; see firestore-codes.ts.
+import { isAlreadyExistsError } from "../../../errors/firestore-codes.js";
 import { BaseRepository, applySieveToFirestore, parseSieveDateValue, prepareForFirestore, } from "../../../providers/db-firebase/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { buildHistoryEntry } from "../../../_internal/shared/history/history.js";
 import { PAYMENT_CASES_COLLECTION, PAYMENT_CASE_ACTIVE_STATUSES, PAYMENT_CASE_FIELDS, PAYMENT_CASE_RESOLUTION_MIN, PAYMENT_CASE_SEVERITY_RANK, createPaymentCaseId, } from "../schemas/firestore.js";
-/** gRPC `ALREADY_EXISTS` — the one `.create()` failure meaning "we have it". */
-const GRPC_ALREADY_EXISTS = 6;
-function isAlreadyExists(err) {
-    if (typeof err !== "object" || err === null)
-        return false;
-    const code = err.code;
-    if (code === GRPC_ALREADY_EXISTS)
-        return true;
-    if (code === "already-exists" || code === "ALREADY_EXISTS")
-        return true;
-    const message = err.message;
-    return typeof message === "string" && message.includes("ALREADY_EXISTS");
-}
 export class PaymentCasesRepository extends BaseRepository {
     constructor() {
         super(PAYMENT_CASES_COLLECTION);
@@ -78,7 +67,7 @@ export class PaymentCasesRepository extends BaseRepository {
             return { id, created: true };
         }
         catch (err) {
-            if (!isAlreadyExists(err)) {
+            if (!isAlreadyExistsError(err)) {
                 void normalizeError(err);
                 throw err;
             }

package/dist/features/pre-orders/components/MarketplacePreorderCard.js

@@ -88,5 +88,5 @@ export function MarketplacePreorderCard({ product, className = "", variant = "gr
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "flex h-full flex-col", children: [card, _jsx(Div, { className: "flex justify-end px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
+    return (_jsxs(Div, { layout: "flex-col", className: "h-full", children: [card, _jsx(Div, { layout: "flex", justify: "end", className: "px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
 }

package/dist/features/products/components/GroupMemberPicker.js

@@ -29,6 +29,7 @@ import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js"
 import { normalizeListingType } from "../utils/listing-type.js";
 import { resolveGroupMemberImage } from "../utils/group-member-image.js";
 import { checkGroupRules, describeGroupRules, EMPTY_GROUP_RULES, } from "../../../_internal/shared/features/products/group-rules.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 const __O = { xAuto: "overflow-x-auto", hidden: "overflow-hidden" };
 const memberImage = resolveGroupMemberImage;
 function memberHref(m) {
@@ -112,9 +113,11 @@ export function GroupMemberPicker({ groupId, groupSource, members, rules = EMPTY
                 onAuthRequired?.();
                 return;
             }
+            // `code` is the stable identifier the error envelope carries; `error` is
+            // the server's own sentence and is deliberately no longer read here.
             const json = (await res.json());
             if (!res.ok || json.success === false) {
-                setError(json.error ?? "Couldn't add those items to your cart.");
+                setError(toUserMessage(json.code, undefined, { fallback: "Couldn't add those items to your cart." }));
                 return;
             }
             setQty({});

package/dist/features/products/components/MarketplaceBundleCard.js

@@ -77,5 +77,5 @@ export function MarketplaceBundleCard({ bundle, className = "", variant = "grid"
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "flex h-full flex-col", children: [card, _jsx(Div, { className: "flex justify-end px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
+    return (_jsxs(Div, { layout: "flex-col", className: "h-full", children: [card, _jsx(Div, { layout: "flex", justify: "end", className: "px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
 }

package/dist/features/products/components/MarketplacePrizeDrawCard.js

@@ -119,5 +119,5 @@ export function MarketplacePrizeDrawCard({ product, className = "", variant = "g
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "flex h-full flex-col", children: [card, _jsx(Div, { className: "flex justify-end px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
+    return (_jsxs(Div, { layout: "flex-col", className: "h-full", children: [card, _jsx(Div, { layout: "flex", justify: "end", className: "px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
 }

package/dist/features/products/components/PrizeDrawEntryActions.js

@@ -12,6 +12,7 @@ import { NonRefundableConsentModal } from "./NonRefundableConsentModal.js";
 import { useAuthGate } from "../../../react/hooks/useAuthGate.js";
 import { ACTION_ID } from "../constants/action-defs.js";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 /**
  * Client buy panel for a prize-draw detail page (SB4-G).
  *
@@ -81,7 +82,7 @@ export function PrizeDrawEntryActions({ productId, productSlug, title, pricePerE
              * a correct refusal look like the same silent nothing this flow did
              * before it was repaired.
              */
-            showToast(n.message, "error");
+            showToast(toUserMessage(n.code, undefined, { fallback: "We couldn't enter you into that draw. Please try again." }), "error");
             return;
         }
         router.push(String(ROUTES.USER.CART));

package/dist/features/products/components/ProductDetailActions.js

@@ -15,6 +15,7 @@ import { useBottomActions } from "../../layout/hooks/useBottomActions.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { useCanSeePrices } from "../../../react/hooks/useCanSeePrices.js";
 import { normalizeError } from "../../../errors/normalize.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 /**
  * Wires the three primary product-detail CTAs (Buy Now / Add to Cart / Wishlist)
  * to the server APIs with guest-fallback. Replaces the previously-unwired
@@ -35,7 +36,7 @@ export function ProductDetailActions({ productId, productTitle, productImage, pr
     // itself — centralised so every add-to-cart call site gets the same
     // richer toast, not just this one.
     const addCart = useAddToCart({
-        onError: (err) => showToast(err?.message ?? "Could not add to cart", "error"),
+        onError: (err) => showToast(toUserMessage(err?.code, undefined, { fallback: "Could not add to cart" }), "error"),
     });
     async function handleAddToCart(then) {
         setBusy("cart");

package/dist/features/products/components/ProductForm.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Row } from "@mohasinac/appkit/ui";
 import { useRef } from "react";
 import { useTranslations } from "next-intl";
-import { Alert, Checkbox, Div, FormField, FormGroup, Heading, Label, RichTextEditor, Stack, TagInput, Text, Toggle, } from "../../../ui/index.js";
+import { Alert, Checkbox, Div, FormField, FormGroup, Heading, Label, Span, RichTextEditor, Stack, TagInput, Text, Toggle, } from "../../../ui/index.js";
 import { isFinalSale } from "../constants/final-sale.js";
 import { PRODUCT_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "../../../_internal/shared/media/limits.js";
 import { CustomSectionsEditor } from "./CustomSectionsEditor.js";
@@ -313,5 +313,5 @@ canEditTax = false, renderDescriptionEditor, renderCategorySelector, renderPrice
                 disabled: isReadonly,
             }), !isAuctionListing(product) && renderGroupSettings?.(product), _jsx(ProductFeaturesSelector, { value: product.features ?? [], onChange: (features) => update({ features }), productType: LISTING_TYPE_TO_FEATURE_PRODUCT_TYPE[normalizeListingType(product)], storeId: product.storeId, disabled: isReadonly }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Custom Sections" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Add up to 3 custom tabs to your product page \u2014 e.g. \"Box Contents\", \"Compatibility\", \"Grading Details\"." }), _jsx(CustomSectionsEditor, { sections: product.customSections ?? [], onChange: (sections) => update({ customSections: sections }) })] }), _jsx(FormField, { name: "shippingInfo", label: t("formShipping"), type: "textarea", value: product.shippingInfo || "", onChange: (value) => update({ shippingInfo: value }), disabled: isReadonly, placeholder: "Shipping information..." }), _jsxs(Div, { children: [_jsx(Toggle, { checked: !isFinalSale(product), onChange: (checked) => update({ finalSale: !checked }), disabled: isReadonly, label: "Accept change-of-mind returns" }), _jsx(Text, { className: "mt-1", size: "xs", color: "muted", children: isFinalSale(product)
                             ? "Final sale (default). Not-received, damaged, wrong-item, not-as-described and counterfeit claims are still accepted."
-                            : "Buyers can return this listing within the platform return window for any reason." })] }), _jsx(FormField, { name: "returnPolicy", label: t("formReturnPolicy"), type: "textarea", value: product.returnPolicy || "", onChange: (value) => update({ returnPolicy: value }), disabled: isReadonly, placeholder: "Return policy details..." }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Physical Inventory" }), existingLocation ? (_jsxs(Text, { className: "mb-3", color: "muted", size: "xs", children: ["Legacy location on this listing: ", _jsx("strong", { children: existingLocation }), ". It is still printed on labels, but it is free text with no box behind it \u2014 place this item in a storage box to replace it."] })) : (_jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Where this item is stored is recorded by placing it in a storage box, not typed here \u2014 a placement has a quantity, and one product can sit in two boxes. Use the receive station or the box's own page." }))] }), product.storeName && (_jsx(FormField, { name: "storeName", label: t("formSeller"), type: "text", value: product.storeName, onChange: () => { }, disabled: true }))] }));
+                            : "Buyers can return this listing within the platform return window for any reason." })] }), _jsx(FormField, { name: "returnPolicy", label: t("formReturnPolicy"), type: "textarea", value: product.returnPolicy || "", onChange: (value) => update({ returnPolicy: value }), disabled: isReadonly, placeholder: "Return policy details..." }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Physical Inventory" }), existingLocation ? (_jsxs(Text, { className: "mb-3", color: "muted", size: "xs", children: ["Legacy location on this listing: ", _jsx(Span, { weight: "semibold", children: existingLocation }), ". It is still printed on labels, but it is free text with no box behind it \u2014 place this item in a storage box to replace it."] })) : (_jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Where this item is stored is recorded by placing it in a storage box, not typed here \u2014 a placement has a quantity, and one product can sit in two boxes. Use the receive station or the box's own page." }))] }), product.storeName && (_jsx(FormField, { name: "storeName", label: t("formSeller"), type: "text", value: product.storeName, onChange: () => { }, disabled: true }))] }));
 }