@mohasinac/appkit 4.61.0 → 4.62.1

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

@@ -0,0 +1,185 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * OrderProvenanceCard — renders `OrderDocument.sourceContext`, the record of
+ * HOW the buyer earned the right to buy at this price.
+ *
+ * ## Why this component had to be written
+ *
+ * `sourceContext` is a six-variant discriminated union, assembled at a real
+ * cost — an auction pays one `findByProductSorted`, an offer one `findById` —
+ * written on every order by both checkout paths, mapped through to the client
+ * type by `orderDocumentToOrder` (adapters.ts:359) … and, until this file,
+ * rendered in **zero** `.tsx` files anywhere in the repo.
+ *
+ * That is Root Cause #52/#57: the data was already present and complete, and
+ * no surface was ever wired to present it. The buyer could not see what they
+ * had agreed, the seller could not see what they had accepted, and support
+ * could not see either.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * **`standard` renders nothing.** Its only field is the list price, which the
+ * order total already shows — a card reading "Standard purchase" on every
+ * ordinary order is noise that would teach people to ignore the card on the
+ * orders where it matters. It is still an explicit `case`, so the switch stays
+ * exhaustive.
+ *
+ * **A saving is shown only where it is real.** Not every variant records a
+ * displaced price: `auction-buy-now` has `listPrice`, `offer-accepted` has
+ * `listPriceAtOffer`, and `auction-won` has only `startingBid` — which is a
+ * floor, not an asking price, so presenting the gap as a discount would be a
+ * fabrication. Where a displaced price exists it is shown only when it is
+ * strictly greater than what was paid.
+ *
+ * **Nothing is fetched.** It is handed the context the page already loaded; a
+ * component that fetched would fire one request per opened drawer per portal.
+ */
+import { Badge, Card, DescriptionField, Heading, Row, Stack, Text } from "../../../ui/index.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { formatDate } from "../../../utils/date.formatter.js";
+/**
+ * A date on a `sourceContext` survives a Firestore round trip as a Timestamp,
+ * an ISO string or a Date depending on which path loaded it, so normalise
+ * rather than assuming. An unparseable value renders an em-dash — never
+ * `new Date()`, which would invent a timestamp for a record that has none
+ * (the rule `OrderStatusTimeline` already follows).
+ */
+function dateText(value) {
+    if (value === null || value === undefined)
+        return "—";
+    const raw = typeof value === "object" && value !== null && "toDate" in value
+        ? value.toDate()
+        : value;
+    const d = raw instanceof Date ? raw : new Date(raw);
+    return Number.isFinite(d.getTime()) ? formatDate(d) : "—";
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function contentFor(ctx, currency) {
+    const money = (n) => formatCurrency(n, currency);
+    switch (ctx.path) {
+        case "standard":
+            // Deliberately silent — see the header. Explicit so the switch is exhaustive.
+            return null;
+        case "auction-won": {
+            const rows = [
+                { label: "Winning bid", value: money(ctx.winningBidAmount) },
+                { label: "Bids in the auction", value: String(ctx.bidCount) },
+                { label: "Starting bid", value: money(ctx.startingBid) },
+            ];
+            if (ctx.runnerUpAmount !== undefined) {
+                rows.push({ label: "Runner-up bid", value: money(ctx.runnerUpAmount) });
+            }
+            if (ctx.reservePrice !== undefined) {
+                rows.push({
+                    label: "Reserve",
+                    value: `${money(ctx.reservePrice)} — ${ctx.reserveMet ? "met" : "not met"}`,
+                });
+            }
+            rows.push({ label: "Auction ended", value: dateText(ctx.auctionEndedAt) });
+            return {
+                title: "Won at auction",
+                tone: "success",
+                summary: ctx.bidCount > 1
+                    ? `Highest of ${plural(ctx.bidCount, "bid", "bids")}.`
+                    : "The only bid placed.",
+                rows,
+            };
+        }
+        case "auction-buy-now": {
+            const rows = [
+                { label: "Buy Now price", value: money(ctx.buyNowPrice) },
+                { label: "List price", value: money(ctx.listPrice) },
+                {
+                    label: "Standing bid beaten",
+                    value: ctx.standingBidAtBuyout > 0 ? money(ctx.standingBidAtBuyout) : "none",
+                },
+                { label: "Bids at buyout", value: String(ctx.bidCount) },
+                { label: "Bought", value: dateText(ctx.boughtAt) },
+            ];
+            return {
+                title: "Bought now, ending the auction",
+                tone: "info",
+                /*
+                 * A buyout IS a real bid (the schema's own note: recording bidCount 0
+                 * would bake a falsehood into an immutable record), so the summary
+                 * must not claim nobody had bid when somebody had.
+                 */
+                summary: ctx.bidCount > 0
+                    ? `Taken at the Buy Now price while ${plural(ctx.bidCount, "bid was", "bids were")} live.`
+                    : "Taken at the Buy Now price before any bids were placed.",
+                rows,
+                saved: ctx.listPrice > ctx.buyNowPrice ? ctx.listPrice - ctx.buyNowPrice : undefined,
+            };
+        }
+        case "offer-accepted": {
+            const rows = [
+                { label: "Agreed price", value: money(ctx.offeredAmount) },
+                { label: "Asking price when offered", value: money(ctx.listPriceAtOffer) },
+            ];
+            if (ctx.counterAmount !== undefined) {
+                rows.push({ label: "Final counter", value: money(ctx.counterAmount) });
+            }
+            rows.push({ label: "Negotiation", value: plural(ctx.counterRounds, "round", "rounds") }, { label: "Accepted", value: dateText(ctx.acceptedAt) });
+            return {
+                title: "Price agreed by offer",
+                tone: "primary",
+                summary: ctx.counterRounds > 1
+                    ? `Agreed after ${plural(ctx.counterRounds, "round", "rounds")} of counter-offers.`
+                    : "Accepted outright, with no counter-offer.",
+                rows,
+                saved: ctx.listPriceAtOffer > ctx.offeredAmount
+                    ? ctx.listPriceAtOffer - ctx.offeredAmount
+                    : undefined,
+            };
+        }
+        case "pre-order":
+            return {
+                title: "Pre-order",
+                tone: "warning",
+                summary: ctx.balanceDue > 0
+                    ? "A deposit was taken at checkout; the balance is due before dispatch."
+                    : "Paid in full at checkout.",
+                rows: [
+                    { label: "Deposit paid", value: money(ctx.depositAmount) },
+                    { label: "Balance due", value: money(ctx.balanceDue) },
+                    { label: "Expected delivery", value: dateText(ctx.expectedDeliveryDate) },
+                ],
+            };
+        case "prize-draw":
+            return {
+                title: "Prize draw entry",
+                tone: "info",
+                summary: ctx.revealMode === "instant"
+                    ? "The result was revealed immediately."
+                    : "The result is revealed at the scheduled draw.",
+                rows: [
+                    { label: "Entries bought", value: plural(ctx.entryCount, "entry", "entries") },
+                    { label: "Price per entry", value: money(ctx.pricePerEntry) },
+                    { label: "Reveal", value: ctx.revealMode === "instant" ? "Instant" : "Scheduled" },
+                ],
+            };
+        default: {
+            /*
+             * Exhaustive. A seventh variant — the shared-purchase path S5a still
+             * needs — will not compile rather than silently rendering nothing, which
+             * is the failure mode of `default: return null` and is precisely how this
+             * union came to have six populated variants and no reader at all.
+             */
+            const unreachable = ctx;
+            return unreachable;
+        }
+    }
+}
+export function OrderProvenanceCard({ sourceContext, currency, className, }) {
+    // Every order written before W2 has no context at all — absence is normal
+    // and is not an error state to announce.
+    if (!sourceContext)
+        return null;
+    const content = contentFor(sourceContext, currency);
+    if (!content)
+        return null;
+    return (_jsx(Card, { variant: "outlined", padding: "md", className: className, children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", gap: "sm", wrap: true, children: [_jsx(Heading, { level: 3, size: "sm", children: content.title }), content.saved !== undefined ? (_jsx(Badge, { variant: "success", children: `Saved ${formatCurrency(content.saved, currency)}` })) : null] }), content.summary ? (_jsx(Text, { size: "sm", color: "muted", children: content.summary })) : null, _jsx(Row, { as: "dl", wrap: true, gap: "md", children: content.rows.map((row) => (_jsx(DescriptionField, { label: row.label, value: row.value }, row.label))) })] }) }));
+}

package/dist/features/orders/components/RaiseDisputeForm.d.ts

@@ -0,0 +1,14 @@
+import { type DisputeGateOrder, type DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+export interface RaiseDisputeFormProps {
+    /** The gate reads four dates off this; an `OrderDocument` satisfies it. */
+    order: DisputeGateOrder;
+    /** `GET ?kind=` / `POST` — supplied by the consumer so appkit holds no route. */
+    reasonsEndpoint: string;
+    onSubmit: (input: {
+        kind: DisputeKind;
+        reasonId: string;
+        detail?: string;
+    }) => Promise<void>;
+    onDone?: () => void;
+}
+export declare function RaiseDisputeForm({ order, reasonsEndpoint, onSubmit, onDone, }: RaiseDisputeFormProps): import("react").JSX.Element;

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

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The buyer's dispute form: pick a kind, pick a reason, say what happened.
+ *
+ * ## Why the kind comes first
+ *
+ * The two kinds have MUTUALLY EXCLUSIVE gates — an item problem needs the
+ * order to have arrived, a non-delivery needs it not to have. So the kind is
+ * the first choice, it scopes the reason list, and it decides which gate the
+ * server will apply. Offering one merged list of reasons would mean a buyer
+ * could pick "it never arrived" on a delivered order and have the server
+ * refuse them, which reads as the form being broken rather than as the wrong
+ * choice.
+ *
+ * ## The gate is checked HERE for the affordance and AGAIN on the server
+ *
+ * 🛑 This copy decides what to OFFER. The server decides what to ACCEPT, and
+ * it is the authority — `raiseOrderDisputeAction` re-runs `checkDisputeGate`
+ * on the real order. Showing a kind the server would refuse is the dead-end
+ * shape (CLAUDE.md's rule for `OrderCompletionPanel`: never offer a button the
+ * server will refuse), and trusting this copy alone would be a client-side
+ * security gate.
+ */
+import { useCallback, useMemo, useState } from "react";
+import { DISPUTE_KIND, DISPUTE_KIND_LABEL, checkDisputeGate, disputeNotReachedFilableFrom, } from "../../../_internal/shared/features/orders/dispute-reasons.js";
+import { Alert, Button, Div, FieldTextarea, Form, Stack, Text, useToast } from "../../../ui/index.js";
+import { PaginatedSelect } from "../../../ui/components/PaginatedSelect.js";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { normalizeError } from "../../../errors/normalize.js";
+export function RaiseDisputeForm({ order, reasonsEndpoint, onSubmit, onDone, }) {
+    const { showToast } = useToast();
+    const [kind, setKind] = useState(null);
+    const [reasonId, setReasonId] = useState(null);
+    const [detail, setDetail] = useState("");
+    const [isPending, setIsPending] = useState(false);
+    /*
+     * Which kinds this order can actually support, with the server's own gate.
+     * A kind that would be refused is shown DISABLED with the reason rather than
+     * hidden: "why can't I report this?" is a question the form should answer,
+     * and a silently missing option looks like a bug.
+     */
+    const kindStates = useMemo(() => DISPUTE_KIND.map((k) => ({
+        kind: k,
+        label: DISPUTE_KIND_LABEL[k],
+        gate: checkDisputeGate(k, order),
+    })), [order]);
+    const filableFrom = useMemo(() => disputeNotReachedFilableFrom(order), [order]);
+    /*
+     * 🛑 Keyed on `kind` so switching kind refetches. `PaginatedSelect` caches
+     * per `loadOptions` identity, so a stable callback would keep showing the
+     * previous kind's reasons — which is the one thing that must never happen
+     * here, because a mismatched reason is refused by the server.
+     */
+    const loadReasons = useCallback(async (query, page) => {
+        if (!kind)
+            return { items: [], hasMore: false };
+        const res = await fetch(`${reasonsEndpoint}?kind=${encodeURIComponent(kind)}`);
+        if (!res.ok) {
+            /*
+             * Surfaced, not swallowed into an empty list. An empty picker is
+             * indistinguishable from "there are no reasons", and the buyer would
+             * sit on a required field with nothing in it (Root Cause #59).
+             */
+            throw new Error("Could not load the list of reasons. Please try again.");
+        }
+        const json = (await res.json());
+        const rows = json.data?.items ?? [];
+        const q = query.trim().toLowerCase();
+        const filtered = q ? rows.filter((r) => r.label.toLowerCase().includes(q)) : rows;
+        return {
+            // `items`, not `options` — checked against `AsyncPage` rather than
+            // guessed; the wrong key yields an empty picker with no error.
+            items: filtered.map((r) => ({ value: r.id, label: r.label })),
+            // The route caps at 50 and the list is short by design; there is no
+            // second page to promise. `page` is unused for the same reason.
+            hasMore: false,
+        };
+    }, [kind, reasonsEndpoint]);
+    const chooseKind = (next) => {
+        setKind(next);
+        // Clearing is required: a reason from the previous kind would be refused.
+        setReasonId(null);
+    };
+    const submit = async () => {
+        if (!kind || !reasonId)
+            return;
+        setIsPending(true);
+        try {
+            await onSubmit({ kind, reasonId, detail: detail.trim() || undefined });
+            showToast("Thanks — we've recorded it and will look into it.", "success");
+            onDone?.();
+        }
+        catch (err) {
+            // The server's message names the next action; show it verbatim rather
+            // than replacing it with a generic failure.
+            showToast(normalizeError(err).message, "error");
+        }
+        finally {
+            setIsPending(false);
+        }
+    };
+    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "What's the problem?" }), kindStates.map((k) => (_jsxs(Div, { children: [_jsx(Button, { variant: kind === k.kind ? "primary" : "secondary", disabled: !k.gate.allowed, onClick: () => chooseKind(k.kind), children: k.label }), !k.gate.allowed ? (_jsx(Text, { size: "xs", color: "muted", children: k.gate.message })) : null] }, k.kind)))] }), kind ? (_jsxs(_Fragment, { children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Reason" }), _jsx(PaginatedSelect, { ariaLabel: "Reason for the dispute", 
+                            /*
+                             * 🛑 `?? null`, not `?? ""`. PaginatedSelect renders its
+                             * placeholder only on `value == null`; an empty string paints a
+                             * BLANK trigger with no prompt, which reads as a broken control
+                             * rather than an unmade choice.
+                             */
+                            value: reasonId ?? null, onChange: (v) => setReasonId(v), loadOptions: loadReasons, placeholder: "Pick the closest match\u2026" }), _jsx(FieldTextarea, { name: "detail", label: "What happened? (optional)", value: detail, onChange: setDetail, maxLength: 2000 }), kind === "not_reached" && filableFrom ? (_jsx(Alert, { variant: "info", children: `We'll chase the courier. If it turns up before we finish, let us know.` })) : null, _jsx(Button, { type: "submit", action: ACTIONS.SUPPORT["raise-dispute"], isLoading: isPending, disabled: !reasonId, onClick: submit, children: "Report this" })] })) : null] }) }));
+}

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

@@ -28,11 +28,19 @@ import { FormShellContext, useFormShellState, FormErrorSummary, FieldTextarea, }
 import { SectionForm, useSectionFormNav } from "../../shell/index.js";
 import { z } from "zod";
 import { REFUND_COPY } from "../../../_internal/shared/features/orders/refund-copy.js";
+import { resolvePublishedCopy, resolvePublishedValues, } from "../../../_internal/shared/content/published-values.js";
 import { RETURN_REASON_LABEL, selectableReturnReasons, } from "../../../_internal/shared/features/orders/return-reasons.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
 const ACK_COUNT = REFUND_COPY.request.acknowledgments.length;
+/*
+ * Phase 9 — code-derived values, resolved once. No settings argument: the only
+ * token in this copy is the refund timeline, which has no setting (see the 🛑
+ * on `refundBusinessDaysMin` in the registry), so passing settings would imply
+ * an editable number that does not exist.
+ */
+const PUBLISHED_VALUES = resolvePublishedValues();
 export function RefundRequestView({ order, onSubmitRequest, isLoading = false, className = "", }) {
     /*
      * Does anything in this order carry the final-sale term? Read from the
@@ -71,7 +79,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 +89,19 @@ 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),
+                        }), 
+                        /*
+                         * 🛑 Phase 9 — resolved, because this is an ACKNOWLEDGEMENT
+                         * the buyer ticks. `REFUND_COPY`'s refund-timeline line now
+                         * carries `{{refundBusinessDaysMin}}`/`Max` so it has one
+                         * owner instead of being the third of three contradicting
+                         * statements — and an unresolved token inside something a
+                         * buyer is agreeing to is the strongest reason the unknown-key
+                         * rule leaves `{{…}}` VISIBLE rather than blanking it.
+                         */
+                        label: _jsx(Text, { size: "sm", className: "leading-snug", children: resolvePublishedCopy(text, PUBLISHED_VALUES) }), "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/components/index.d.ts

@@ -6,6 +6,10 @@ export { OrderSiblingPayments } from "./OrderSiblingPayments";
 export type { OrderSiblingPaymentsProps } from "./OrderSiblingPayments";
 export { OrderPaymentSummary } from "./OrderPaymentSummary";
 export type { OrderPaymentSummaryProps } from "./OrderPaymentSummary";
+export { OrderProvenanceCard } from "./OrderProvenanceCard";
+export type { OrderProvenanceCardProps } from "./OrderProvenanceCard";
+export { RaiseDisputeForm } from "./RaiseDisputeForm";
+export type { RaiseDisputeFormProps } from "./RaiseDisputeForm";
 export { OrderStatusTimeline } from "./OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./OrderStatusTimeline";
 export { RefundHistoryTable } from "./RefundHistoryTable";

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

@@ -3,6 +3,8 @@ export { OrderAddonBadges, } from "./OrderAddonBadges.js";
 export { OrderFilters, ORDER_FILTER_KEYS, ORDER_ADMIN_SORT_OPTIONS, ORDER_SELLER_SORT_OPTIONS, ORDER_USER_SORT_OPTIONS, getOrderFilterKeys, getOrderSortOptions, } from "./OrderFilters.js";
 export { OrderSiblingPayments } from "./OrderSiblingPayments.js";
 export { OrderPaymentSummary } from "./OrderPaymentSummary.js";
+export { OrderProvenanceCard } from "./OrderProvenanceCard.js";
+export { RaiseDisputeForm } from "./RaiseDisputeForm.js";
 export { OrderStatusTimeline } from "./OrderStatusTimeline.js";
 export { RefundHistoryTable } from "./RefundHistoryTable.js";
 export { RefundRequestView } from "./RefundRequestView.js";

package/dist/features/orders/constants/order-lane-tabs.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Order PROVENANCE tabs — the one definition, shared by the buyer's and the
+ * seller's order lists.
+ *
+ * ## Why this file exists
+ *
+ * The buyer's list had these tabs and the seller's did not. A seller could see
+ * every order and could not ask "show me the ones I accepted an offer on" or
+ * "show me the auction wins", which is exactly the split that changes how they
+ * are handled: an auction win has a forfeit deadline, an accepted offer has an
+ * agreed price that is not the listing price.
+ *
+ * Copying the array into the second view would have been the ninth
+ * hand-written enumeration of one union in this codebase (Root Cause #61), so
+ * the labels are a `Record<OrderType, string>` instead: a sixth lane is a
+ * COMPILE error here rather than a tab that silently never appears.
+ *
+ * 🛑 Three things about these ids, each of which has already cost a bug:
+ *
+ * 1. **Every id is EXACTLY a stored `OrderDocument.orderType` value.** Firestore
+ *    `==` is byte-exact, so a tab id that is merely plausible returns zero rows
+ *    forever with no error anywhere (Root Cause #33).
+ *
+ * 2. **`preorder` has NO HYPHEN and that is not a typo to tidy up.** `OrderType`
+ *    spells it `preorder`; `ListingType` spells the same concept `pre-order`.
+ *    Two unions, two spellings, and the tab must match the one actually stored.
+ *
+ * 3. **`standard` must be filtered IN MEMORY, never as a Firestore `==`.**
+ *    Orders written before `orderType` existed carry no such field, and an
+ *    equality excludes every document that lacks it — so the "Normal" tab would
+ *    hide every legacy order while looking like it worked. `mergeOrderScopeFilter`
+ *    and the server-side list both already honour this; see `ORDER_LANE_ALL` for
+ *    the "no filter" sentinel.
+ */
+import type { OrderType } from "../utils/order-splitter";
+/**
+ * The "All" tab's id. An empty string rather than a word, so it can never
+ * collide with a real `orderType` value and so `state.orderType ? … : null`
+ * reads as "no filter" at every call site.
+ */
+export declare const ORDER_LANE_ALL: "";
+/**
+ * 🛑 A `Record<OrderType, string>`, deliberately. Omitting a lane does not
+ * compile, which is the whole point — the buyer's list shipped with four tabs
+ * for five lanes, so pre-order and prize-draw orders were reachable only by
+ * landing on "All" and scrolling.
+ */
+export declare const ORDER_LANE_LABELS: Record<OrderType, string>;
+/**
+ * The stored `orderType` values a lane filter may name, for route-side
+ * validation.
+ *
+ * Derived from `ORDER_LANE_LABELS`, so it cannot drift from the tabs. Both
+ * `/api/user/orders` and `/api/store/orders` had — or would have needed — their
+ * own hand-written copy of these five strings; this is the eleventh
+ * enumeration of one union in this codebase collapsed into the union itself
+ * (Root Cause #61).
+ *
+ * 🛑 Validating against it is load-bearing, not hygiene: an unrecognised value
+ * interpolated into a Sieve filter string is a caller-controlled field name
+ * reaching the query builder.
+ */
+export declare const VALID_ORDER_TYPES: ReadonlySet<string>;
+export interface OrderLaneTab {
+    id: string;
+    label: string;
+}
+/** `All` first, then every lane in `LANE_ORDER`. */
+export declare const ORDER_LANE_TABS: readonly OrderLaneTab[];

package/dist/features/orders/constants/order-lane-tabs.js

@@ -0,0 +1,88 @@
+/**
+ * Order PROVENANCE tabs — the one definition, shared by the buyer's and the
+ * seller's order lists.
+ *
+ * ## Why this file exists
+ *
+ * The buyer's list had these tabs and the seller's did not. A seller could see
+ * every order and could not ask "show me the ones I accepted an offer on" or
+ * "show me the auction wins", which is exactly the split that changes how they
+ * are handled: an auction win has a forfeit deadline, an accepted offer has an
+ * agreed price that is not the listing price.
+ *
+ * Copying the array into the second view would have been the ninth
+ * hand-written enumeration of one union in this codebase (Root Cause #61), so
+ * the labels are a `Record<OrderType, string>` instead: a sixth lane is a
+ * COMPILE error here rather than a tab that silently never appears.
+ *
+ * 🛑 Three things about these ids, each of which has already cost a bug:
+ *
+ * 1. **Every id is EXACTLY a stored `OrderDocument.orderType` value.** Firestore
+ *    `==` is byte-exact, so a tab id that is merely plausible returns zero rows
+ *    forever with no error anywhere (Root Cause #33).
+ *
+ * 2. **`preorder` has NO HYPHEN and that is not a typo to tidy up.** `OrderType`
+ *    spells it `preorder`; `ListingType` spells the same concept `pre-order`.
+ *    Two unions, two spellings, and the tab must match the one actually stored.
+ *
+ * 3. **`standard` must be filtered IN MEMORY, never as a Firestore `==`.**
+ *    Orders written before `orderType` existed carry no such field, and an
+ *    equality excludes every document that lacks it — so the "Normal" tab would
+ *    hide every legacy order while looking like it worked. `mergeOrderScopeFilter`
+ *    and the server-side list both already honour this; see `ORDER_LANE_ALL` for
+ *    the "no filter" sentinel.
+ */
+/**
+ * The "All" tab's id. An empty string rather than a word, so it can never
+ * collide with a real `orderType` value and so `state.orderType ? … : null`
+ * reads as "no filter" at every call site.
+ */
+export const ORDER_LANE_ALL = "";
+/**
+ * 🛑 A `Record<OrderType, string>`, deliberately. Omitting a lane does not
+ * compile, which is the whole point — the buyer's list shipped with four tabs
+ * for five lanes, so pre-order and prize-draw orders were reachable only by
+ * landing on "All" and scrolling.
+ */
+export const ORDER_LANE_LABELS = {
+    standard: "Normal",
+    auction: "Auction wins",
+    offer: "Offer wins",
+    preorder: "Pre-orders",
+    "prize-draw": "Prize draws",
+};
+/**
+ * Display order, listed explicitly rather than taken from `Object.keys`.
+ *
+ * Key order on an object literal is not a contract anyone should rely on for
+ * UI ordering, and the intended order is not alphabetical: it mirrors the
+ * cart's lane PRIORITY (auction > offer > standard — highest obligation
+ * first), with the two schedule-driven lanes after them.
+ */
+const LANE_ORDER = [
+    "standard",
+    "auction",
+    "offer",
+    "preorder",
+    "prize-draw",
+];
+/**
+ * The stored `orderType` values a lane filter may name, for route-side
+ * validation.
+ *
+ * Derived from `ORDER_LANE_LABELS`, so it cannot drift from the tabs. Both
+ * `/api/user/orders` and `/api/store/orders` had — or would have needed — their
+ * own hand-written copy of these five strings; this is the eleventh
+ * enumeration of one union in this codebase collapsed into the union itself
+ * (Root Cause #61).
+ *
+ * 🛑 Validating against it is load-bearing, not hygiene: an unrecognised value
+ * interpolated into a Sieve filter string is a caller-controlled field name
+ * reaching the query builder.
+ */
+export const VALID_ORDER_TYPES = new Set(Object.keys(ORDER_LANE_LABELS));
+/** `All` first, then every lane in `LANE_ORDER`. */
+export const ORDER_LANE_TABS = [
+    { id: ORDER_LANE_ALL, label: "All" },
+    ...LANE_ORDER.map((type) => ({ id: type, label: ORDER_LANE_LABELS[type] })),
+];

package/dist/features/orders/repository/orders.repository.d.ts

@@ -196,6 +196,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        orderType: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         giftWrapAddon: {
             canFilter: boolean;
             canSort: boolean;
@@ -404,6 +408,32 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
         status: "failed";
         failureReason?: string;
     }, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
+    /**
+     * Stamp a credit-note number onto one settled refund event (Phase 7, 7c).
+     *
+     * ## 🛑 Why this is a repository method and not an inline update
+     *
+     * `refunds[]` is written by re-mapping the whole array, exactly as
+     * `settleRefund` directly above does — because a read-modify-write of
+     * `[...existing, event]` LOSES a concurrent event (D6), and that defect is
+     * just as reachable from a credit-note stamp as from a refund append.
+     * Letting the invoicing feature touch the array directly would reintroduce
+     * it one caller away from the fix.
+     *
+     * It goes through `updateWithHistory` for the same reason every other
+     * mutator here does: the transition guard and the status-history entry live
+     * there, and this is a real recorded event on the order.
+     *
+     * 🛑 A missing refund event is a NO-OP, not a throw. The caller is the
+     * refund settle path, where money has already moved; raising here would turn
+     * a successful refund into a reported failure. See
+     * `issueCreditNoteForRefund`'s own 🛑.
+     */
+    setRefundCreditNote(orderId: string, refundId: string, note: {
+        creditNoteNumber: string;
+        creditNoteIssuedAt: Date;
+        creditNoteStoragePath?: string;
+    }, ctx?: OrderWriteContext): Promise<OrderDocument | null>;
     /**
      * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
      *
@@ -442,6 +472,33 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * `paymentProofUrl != null` filter would silently exclude every doc where
      * the field isn't set at all — the opposite of what's needed here.
      */
+    /**
+     * Orders invoiced within a window — the GSTR-1 export's only query
+     * (Phase 7d).
+     *
+     * ## 🛑 Windowed on `invoiceIssuedAt`, not on the order date
+     *
+     * A COD order placed on 30 March and paid on 2 April is invoiced in the NEW
+     * financial year, and that is the period its tax belongs to. Numbering
+     * happens at the payment transition for exactly this reason, so the invoice
+     * date is the only correct axis — windowing on `orderDate` would file that
+     * order's tax in the year before it was invoiced.
+     *
+     * ## 🛑 It also returns PAID orders with no invoice number, deliberately
+     *
+     * Those are the ones the export must warn about rather than omit — a paid
+     * order silently absent from a tax return is the single error this whole
+     * feature exists to prevent. Firestore cannot OR across two fields, so the
+     * second query is a separate one and the caller merges; the alternative
+     * (one query on `paymentStatus`, filtered in memory) would scan every paid
+     * order ever placed.
+     *
+     * Unbounded `.limit(2000)`: a quarter's orders at this volume is a few
+     * hundred, and an export that silently truncated would understate a tax
+     * return. If this ever saturates, the fix is pagination with an explicit
+     * "more rows exist" signal in the CSV — never a higher cap.
+     */
+    listInvoicedBetween(from: Date, to: Date): Promise<OrderDocument[]>;
     getExpiredPaymentDeadlines(): Promise<Array<{
         id: string;
         ref: DocumentReference;