@mohasinac/appkit 4.62.1 → 4.63.0

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

@@ -0,0 +1,12 @@
+import type { Order } from "../types";
+export interface BalancePaymentPanelProps {
+    order: Pick<Order, "id" | "balance" | "currency">;
+    /** Uploads one file and resolves to the stored `/media/…` slug. */
+    onUpload: (file: File) => Promise<string>;
+    /** POSTs to `/api/orders/{id}/balance-proof`. Throws on failure. */
+    onSubmit: (input: {
+        proofUrl: string;
+        transactionId: string;
+    }) => Promise<void>;
+}
+export declare function BalancePaymentPanel({ order, onUpload, onSubmit }: BalancePaymentPanelProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,94 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * D55 — the buyer's panel for paying a pre-order balance.
+ *
+ * ## 🛑 This exists because the figure was already on screen
+ *
+ * `OrderProvenanceCard` has printed "Balance due ₹X" on every pre-order since
+ * Part 2, and nothing in the product could accept that money. A buyer who
+ * reads an amount owed and finds no control does not conclude "the feature is
+ * coming" — they conclude the site is broken, and the seller waiting on the
+ * money has no way to chase it.
+ *
+ * ## Why it is NOT a second page
+ *
+ * The deposit's proof upload is its own route (`/user/orders/[id]/payment`)
+ * because it runs against a 15-minute window with a countdown, a UPI address
+ * to copy and a fraud declaration — a task with its own screen. The balance
+ * has a 7-day window and no countdown, so sending the buyer somewhere else to
+ * fill in two fields would add a navigation and a back button for nothing.
+ *
+ * ## The four states
+ *
+ * | `balance.status` | What the buyer sees |
+ * |---|---|
+ * | absent | NOTHING — the seller has not opened collection; the goods do not exist yet |
+ * | `awaiting` / `rejected` | the form, with the rejection note when there is one |
+ * | `submitted` | "under review", no form |
+ * | `paid` | a confirmation line and the reference |
+ *
+ * 🛑 The absent case rendering nothing is the load-bearing one. A pre-order's
+ * premise is that the item has not been made yet, so a payable-looking balance
+ * before the seller opens it would be asking the buyer to fund inventory.
+ */
+import { useState } from "react";
+import { Button } from "../../../ui/components/Button.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Text, Span } from "../../../ui/components/Typography.js";
+import { Form } from "../../../ui/components/Form.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary.js";
+import { MediaUploadField } from "../../media/upload/MediaUploadField.js";
+import { balanceProofSchema } from "../schemas/balance.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+function dueText(dueBy) {
+    if (!dueBy)
+        return "";
+    const d = new Date(dueBy);
+    if (Number.isNaN(d.getTime()))
+        return "";
+    return ` Due by ${d.toLocaleDateString("en-IN", { day: "numeric", month: "short", year: "numeric" })}.`;
+}
+export function BalancePaymentPanel({ order, onUpload, onSubmit }) {
+    const [proofUrl, setProofUrl] = useState("");
+    const [transactionId, setTransactionId] = useState("");
+    const [isPending, setIsPending] = useState(false);
+    const balance = order.balance;
+    // Nothing to collect yet — see the header. Not an empty card, no card.
+    if (!balance)
+        return null;
+    const amount = formatCurrency(balance.amount, order.currency);
+    if (balance.status === "paid") {
+        return (_jsxs(Div, { surface: "card", padding: "md", className: "mt-4", children: [_jsx(Span, { layout: "inline-flex", color: "success", surface: "success-surface", weight: "semibold", className: "text-[10px]", rounded: "full", padding: "pill-xs", children: "Balance paid" }), _jsxs(Text, { className: "mt-1", color: "muted", size: "xs", children: [amount, " received. This order is ready to ship.", balance.transactionId ? ` Reference: ${balance.transactionId}` : ""] })] }));
+    }
+    if (balance.status === "submitted") {
+        return (_jsxs(Div, { surface: "card", padding: "md", className: "mt-4", children: [_jsx(Span, { layout: "inline-flex", color: "info", surface: "info-surface", weight: "semibold", className: "text-[10px]", rounded: "full", padding: "pill-xs", children: "Balance under review" }), _jsxs(Text, { className: "mt-1", color: "muted", size: "xs", children: ["We have your proof for ", amount, ". Our team checks it against the reference you gave, and the order ships once it clears."] })] }));
+    }
+    const rejected = balance.status === "rejected";
+    const handleSubmit = async () => {
+        setIsPending(true);
+        try {
+            await onSubmit({ proofUrl, transactionId: transactionId.trim() });
+        }
+        finally {
+            /*
+             * Cleared even on failure. The caller surfaces the error; leaving the
+             * button spinning forever is how a recoverable 400 reads as a hang.
+             */
+            setIsPending(false);
+        }
+    };
+    return (_jsx(Div, { surface: "card", padding: "md", className: "mt-4", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsx(Span, { layout: "inline-flex", color: rejected ? "error" : "warning", surface: rejected ? "danger-surface" : "warning-surface", weight: "semibold", className: "text-[10px]", rounded: "full", padding: "pill-xs", children: rejected ? "Balance proof needs correction" : "Balance due" }), _jsx(Text, { className: "mt-1", color: "muted", size: "xs", children: rejected
+                                ? /*
+                                   * The note is REQUIRED on a rejection server-side, so the
+                                   * fallback here should effectively never render — it exists
+                                   * because a row written before that rule would otherwise say
+                                   * nothing at all, which is the one thing a rejection must not do.
+                                   */
+                                    balance.reviewNote
+                                        ? `Our team could not accept the last proof: ${balance.reviewNote}`
+                                        : "Our team could not accept the last proof. Please send a clearer screenshot."
+                                : `Your item is ready. Pay the remaining ${amount} and upload the receipt.${dueText(balance.dueBy)}` })] }), _jsx(Form, { schema: balanceProofSchema, onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Stack, { gap: "md", children: [_jsx(FormErrorSummary, {}), _jsx(MediaUploadField, { label: "Payment screenshot (JPG/PNG/PDF)", value: proofUrl, onChange: setProofUrl, onUpload: onUpload, kind: "image", accept: "image/*,application/pdf", showYoutube: false, showExternal: false, helperText: "The confirmation screen from your bank or UPI app." }), _jsx(FieldInput, { name: "transactionId", label: "UTR / Transaction reference", required: true, value: transactionId, onChange: (value) => setTransactionId(value), placeholder: "e.g. 123456789012", hint: "Required \u2014 it is the only thing our team can check the payment against. A screenshot on its own is a picture." }), _jsx(Row, { gap: "3", children: _jsx(Button, { type: "button", variant: "primary", disabled: isPending || !proofUrl || transactionId.trim().length < 4, onClick: handleSubmit, paddingX: "md", paddingY: "sm", textSize: "sm", weight: "semibold", children: isPending ? "Sending…" : rejected ? "Re-send proof" : "Submit payment proof" }) })] })) })] }) }));
+}

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

@@ -28,6 +28,12 @@ import { Alert, Button, Div, FieldTextarea, Form, Stack, Text, useToast } from "
 import { PaginatedSelect } from "../../../ui/components/PaginatedSelect.js";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
 import { normalizeError } from "../../../errors/normalize.js";
+/*
+ * 🛑 From the DEFINING module, not the `@mohasinac/appkit/client` barrel. This
+ * is a `"use client"` component so either resolves, but a barrel import drags
+ * the whole client entry's graph in for one symbol (Root Cause #18).
+ */
+import { apiClient } from "../../../http/ApiClient.js";
 export function RaiseDisputeForm({ order, reasonsEndpoint, onSubmit, onDone, }) {
     const { showToast } = useToast();
     const [kind, setKind] = useState(null);
@@ -55,17 +61,19 @@ export function RaiseDisputeForm({ order, reasonsEndpoint, onSubmit, onDone, })
     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 ?? [];
+        /*
+         * `apiClient`, not a bare `fetch` — it carries the credentials and the
+         * error shape every other call in this feature uses, and the bare form
+         * is what `audit-form-mutation-hook` blocks inside a <Form>-rendering
+         * file. Same shape as `YourPurchaseStrip`'s read, one folder over.
+         *
+         * It THROWS on a non-2xx, which is the behaviour this call site already
+         * wanted: 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).
+         */
+        const json = await apiClient.get(`${reasonsEndpoint}?kind=${encodeURIComponent(kind)}`);
+        const rows = json?.data?.items ?? [];
         const q = query.trim().toLowerCase();
         const filtered = q ? rows.filter((r) => r.label.toLowerCase().includes(q)) : rows;
         return {

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

@@ -5,6 +5,7 @@ import { BaseRepository, parseSieveDateValue } from "../../../providers/db-fireb
 import { type OrderCreateInput, type OrderDocument, type OrderPlain, type OrderRefundEvent } from "../schemas";
 import { type HistoryActor, type FieldChange } from "../../../_internal/shared/history/index";
 import type { OrderStatus, PaymentStatus } from "../types";
+import type { OrderType } from "../utils/order-splitter";
 import { type PaymentReviewQueueMode } from "../constants/payment-window";
 /**
  * Who/why for a write that lands in `statusHistory`.
@@ -64,7 +65,7 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * encryption lived in a private method only three call sites remembered to
      * call.
      */
-    protected piiFields: readonly ["userName", "userEmail", "sellerEmail"];
+    protected piiFields: readonly ["userName", "userEmail", "sellerEmail", "deliveryFullName", "deliveryPhone", "deliveryAddressLine1", "deliveryAddressLine2", "deliveryLandmark", "deliveryAmendments[].fullName", "deliveryAmendments[].phone", "deliveryAmendments[].addressLine1", "deliveryAmendments[].addressLine2", "deliveryAmendments[].landmark"];
     /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
     revealOrder(doc: OrderDocument): OrderPlain;
     /** As `revealOrder`, for a list read. */
@@ -144,6 +145,20 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * `order.bundleId` at creation time (SB3 / SB6-C).
      */
     countByUserAndBundle(userId: string, bundleId: string): Promise<number>;
+    /**
+     * How many orders this buyer has placed, optionally scoped to one lane.
+     *
+     * A Firestore aggregation — billed at one read per 1000 index entries
+     * matched, not one per order — so it stays flat as an account's history
+     * grows. That matters because the only caller is the session profile
+     * endpoint, which every page load hits.
+     *
+     * 🛑 `orderType` may only name a NON-standard lane. The field was added
+     * after orders already existed, so an equality on `"standard"` would return
+     * zero for every legacy order while looking perfectly correct — see the
+     * constant's own note.
+     */
+    countForUser(userId: string, orderType?: Exclude<OrderType, "standard">): Promise<number>;
     deleteByUser(userId: string): Promise<number>;
     static readonly SELLER_SIEVE_FIELDS: {
         id: {
@@ -564,6 +579,18 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      */
     getEligibleAutomatic(cutoff: Date, opts?: {
         onWarn?: (msg: string, meta?: Record<string, JsonValue>) => void;
+        /**
+         * Stores paid at SHIPPING rather than at delivery.
+         *
+         * 🛑 A faster path through the SAME query, not a second one. A `shipped`
+         * row is admitted only for a store in this set, and then skips the hold
+         * anchor — being paid before delivery is the entire grant, so applying a
+         * post-delivery hold to it would make the flag do nothing.
+         *
+         * Omitted or empty means nobody is trusted, which is the correct default
+         * and reproduces the pre-existing behaviour exactly.
+         */
+        trustedStoreIds?: ReadonlySet<string>;
     }): Promise<Array<{
         id: string;
         ref: DocumentReference;

package/dist/features/orders/repository/orders.repository.js

@@ -9,7 +9,7 @@ import { normalizeError } from "../../../errors/normalize.js";
  * that mix-up swallowing ~100 call sites' validation messages.
  */
 import { DatabaseError, NotFoundError, ValidationError } from "../../../errors/index.js";
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, getFirestoreCount, } from "../../../providers/db-firebase/index.js";
 import { maskPii, revealPii, ORDER_PII_FIELDS, } from "../../../security/index.js";
 import { serverTimestamp, arrayUnion } from "../../../contracts/field-ops.js";
 import { createOrderId, ORDER_COLLECTION, ORDER_TRACKED_FIELDS, OrderStatusValues, } from "../schemas/index.js";
@@ -304,10 +304,11 @@ class OrderRepository extends BaseRepository {
             reason: ctx?.reason,
             note: ctx?.note,
             extraChanges: ctx?.extraChanges,
-            // `encryptPiiFields` is a flat top-level loop and never descends into
-            // arrays, so anything PII-named reaching `changes` would persist in
-            // PLAINTEXT inside statusHistory. None of ORDER_TRACKED_FIELDS is PII
-            // today — this is defence for the next field somebody adds.
+            // `encryptPiiFields` covers a field only where it is NAMED, so a
+            // PII-named value reaching `changes` is plaintext unless somebody
+            // declared `statusHistory[].changes.<that key>` — which nobody will.
+            // The scrub removes the guesswork. None of ORDER_TRACKED_FIELDS is PII
+            // today; this is defence for the next field somebody adds.
             piiFields: ORDER_PII_FIELDS,
             historyField: "statusHistory",
             truncatedField: "statusHistoryTruncated",
@@ -516,6 +517,26 @@ class OrderRepository extends BaseRepository {
             .get();
         return snapshot.size;
     }
+    /**
+     * How many orders this buyer has placed, optionally scoped to one lane.
+     *
+     * A Firestore aggregation — billed at one read per 1000 index entries
+     * matched, not one per order — so it stays flat as an account's history
+     * grows. That matters because the only caller is the session profile
+     * endpoint, which every page load hits.
+     *
+     * 🛑 `orderType` may only name a NON-standard lane. The field was added
+     * after orders already existed, so an equality on `"standard"` would return
+     * zero for every legacy order while looking perfectly correct — see the
+     * constant's own note.
+     */
+    async countForUser(userId, orderType) {
+        let query = this.getCollection().where(ORDER_FIELDS.USER_ID, "==", userId);
+        if (orderType) {
+            query = query.where(ORDER_FIELDS.ORDER_TYPE, "==", orderType);
+        }
+        return getFirestoreCount(query);
+    }
     async deleteByUser(userId) {
         try {
             const snapshot = await this.getCollection()
@@ -1139,10 +1160,23 @@ class OrderRepository extends BaseRepository {
          * and the anchor test is a per-row predicate below. One query, no new
          * composite index, and no way to silently return nothing.
          */
+        const trusted = opts?.trustedStoreIds ?? new Set();
         const snap = await this.db
             .collection(this.collection)
             .where(ORDER_FIELDS.PAYOUT_STATUS, "==", "eligible")
-            .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.DELIVERED)
+            /*
+             * 🛑 Widened to an `in` ONLY when some store is trusted.
+             *
+             * Firestore's `in` is an OR of equalities, so the existing
+             * `(payoutStatus, status)` composite serves both forms and no new index
+             * is needed. Keeping the plain equality when the set is empty matters
+             * anyway: a deployment with no trusted sellers then runs byte-identically
+             * to before, so the flag cannot change behaviour for anyone who has not
+             * been granted it.
+             */
+            .where(ORDER_FIELDS.STATUS, ...(trusted.size > 0
+            ? ["in", [OrderStatusValues.DELIVERED, OrderStatusValues.SHIPPED]]
+            : ["==", OrderStatusValues.DELIVERED]))
             .limit(500)
             .get();
         let missingAnchor = 0;
@@ -1153,6 +1187,26 @@ class OrderRepository extends BaseRepository {
             data: { id: d.id, ...d.data() },
         }))
             .filter((o) => !o.data.emiEnabled || o.data.emiComplete)
+            .filter((o) => {
+            /*
+             * 🛑 A SHIPPED row is admitted only for a TRUSTED store, and then
+             * bypasses the hold entirely — paying at shipping is the grant.
+             *
+             * Tested before the anchor rather than inside it, because a shipped
+             * order has no `deliveryDate` and would fall through to the
+             * `updatedAt` fallback — which is always LATER than delivery would
+             * have been. A trusted seller would be paid more SLOWLY than an
+             * untrusted one: the flag would read as working and do the opposite.
+             *
+             * The `in` above cannot express "shipped, but only for these stores",
+             * so the store test has to live here — otherwise one trusted seller
+             * anywhere would widen the sweep for every seller.
+             */
+            if (o.data.status === OrderStatusValues.SHIPPED) {
+                return typeof o.data.storeId === "string" && trusted.has(o.data.storeId);
+            }
+            return true;
+        })
             .filter((o) => {
             /*
              * The anchor, with a conservative fallback. `deliveryDate` is the

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

@@ -0,0 +1,40 @@
+/**
+ * D55 — write shapes for the pre-order balance collector.
+ *
+ * 🛑 Both are `.strict()`, and that is the Root Cause #76 lesson rather than
+ * tidiness: the balance block carries `status`, `reviewedBy`, `reviewedAt`
+ * and `amount`, and a write shape that can NAME a field is a write shape that
+ * can destroy it. A buyer must not be able to send `status: "paid"` or
+ * `amount: 1`, and `z.object()` merely STRIPS unknown keys — which is the
+ * same silent-success failure as the grouped-listings PATCH. `.strict()`
+ * makes it a 400 instead.
+ *
+ * Neither schema is where `amount` comes from. It is snapshotted from
+ * `sourceContext.balanceDue` when the seller opens collection, months before
+ * this, and is never re-read from the live product (D61).
+ */
+import { z } from "zod";
+/** The buyer's proof of payment. */
+export declare const balanceProofSchema: z.ZodObject<{
+    proofUrl: z.ZodString;
+    transactionId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    transactionId: string;
+    proofUrl: string;
+}, {
+    transactionId: string;
+    proofUrl: string;
+}>;
+export type BalanceProofInput = z.infer<typeof balanceProofSchema>;
+/** The admin's verdict on a submitted proof. */
+export declare const balanceReviewSchema: z.ZodObject<{
+    approve: z.ZodBoolean;
+    note: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    approve: boolean;
+    note?: string | undefined;
+}, {
+    approve: boolean;
+    note?: string | undefined;
+}>;
+export type BalanceReviewInput = z.infer<typeof balanceReviewSchema>;

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

@@ -0,0 +1,47 @@
+/**
+ * D55 — write shapes for the pre-order balance collector.
+ *
+ * 🛑 Both are `.strict()`, and that is the Root Cause #76 lesson rather than
+ * tidiness: the balance block carries `status`, `reviewedBy`, `reviewedAt`
+ * and `amount`, and a write shape that can NAME a field is a write shape that
+ * can destroy it. A buyer must not be able to send `status: "paid"` or
+ * `amount: 1`, and `z.object()` merely STRIPS unknown keys — which is the
+ * same silent-success failure as the grouped-listings PATCH. `.strict()`
+ * makes it a 400 instead.
+ *
+ * Neither schema is where `amount` comes from. It is snapshotted from
+ * `sourceContext.balanceDue` when the seller opens collection, months before
+ * this, and is never re-read from the live product (D61).
+ */
+import { z } from "zod";
+/** The buyer's proof of payment. */
+export const balanceProofSchema = z
+    .object({
+    /*
+     * A `/media/…` slug from the signed-URL upload flow — bytes never reach
+     * this route (Rule #6's 4.5 MB payload cap, and § Media Architecture).
+     */
+    proofUrl: z.string().min(1, "Upload a screenshot of the payment."),
+    /*
+     * The UTR or UPI reference. Required, because it is the only thing an
+     * admin can check the payment against — a screenshot alone is a picture.
+     */
+    transactionId: z
+        .string()
+        .min(4, "Enter the transaction reference from your bank or UPI app.")
+        .max(64),
+})
+    .strict();
+/** The admin's verdict on a submitted proof. */
+export const balanceReviewSchema = z
+    .object({
+    approve: z.boolean(),
+    /*
+     * Optional HERE and required in `reviewBalanceProof` when `approve` is
+     * false. Deliberately not a `.refine()`: the rule belongs with the
+     * transition it guards, and duplicating it would give two places to
+     * disagree. An approval genuinely needs no note.
+     */
+    note: z.string().max(300).optional(),
+})
+    .strict();

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

@@ -174,6 +174,68 @@ export declare const RefundStatusValues: {
     readonly REJECTED: "rejected";
 };
 /** Firestore storage shape for an order line item â€" distinct from the API display model OrderItem */
+/**
+ * The PII inside one amendment.
+ *
+ * 🛑 BARE keys, and `ORDER_PII_FIELDS` uses the `deliveryAmendments[].…`
+ * form for the same five fields. Two notations, two scopes, both correct:
+ * the `[]` form is for the whole ORDER document, where the hook has to walk
+ * into the array; these bare names are for ONE amendment object, where they
+ * are genuinely top-level.
+ *
+ * 🛑 This list was first justified as "`encryptPiiFields` CANNOT cover an
+ * array" — CLAUDE.md's wording, and FALSE. `encryptInArray` has always
+ * handled `a[].b`, in both directions. The real rule is that the encryptor
+ * does not infer: a field is covered only where it is NAMED, in the notation
+ * matching the object the list is applied to.
+ */
+export declare const AMENDMENT_PII_FIELDS: readonly ["fullName", "phone", "addressLine1", "addressLine2", "landmark"];
+/**
+ * A correction to the delivery address after the order was placed.
+ *
+ * 🛑 Carries the FULL new address, not a diff. A diff would make the current
+ * address reconstructable only by replaying every entry in order, so one
+ * malformed entry in the middle makes everything after it unreadable — and
+ * the parcel label is produced from the current address.
+ *
+ * PII in here is the same problem as everywhere else: `encryptPiiFields` does
+ * not descend into arrays, so these values are NOT encrypted by that
+ * mechanism. `scrubAmendmentPii` is what handles them; see its header.
+ */
+export interface DeliveryAmendment {
+    at: Date;
+    /** Who asked. `actorRole` distinguishes a buyer correction from a support fix. */
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    reason?: string;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    addressLine2?: string;
+    landmark?: string;
+    city: string;
+    state: string;
+    pincode: string;
+    country: string;
+}
+/**
+ * How much seller prose a single order line carries.
+ *
+ * 🛑 A Firestore document caps at 1 MiB and `items[]` is inline on the order.
+ * 2,000 characters × 20 lines is ~40 KB of description — comfortable. The
+ * same field unbounded is a rejected write at checkout, and the checkout is
+ * the one operation in the system that must never fail for a reason the buyer
+ * cannot act on.
+ */
+export declare const ORDER_ITEM_DESCRIPTION_MAX = 2000;
+/**
+ * How many spec rows one order line keeps.
+ *
+ * Capped by COUNT rather than characters: a spec table is rows, and half a
+ * row is worse than a missing one — "Weight: 4" with the unit cut off reads
+ * as a fact rather than as truncation.
+ */
+export declare const ORDER_ITEM_SPECIFICATIONS_MAX = 30;
 export interface OrderDocumentItem {
     productId: string;
     productTitle: string;
@@ -261,6 +323,37 @@ export interface OrderDocumentItem {
     /** Which kind of multi-member line produced these rows. */
     groupSource?: "bundle" | "product-group" | "grouped-listing";
     /** P-8 GST — snapshotted from the product at order time so the invoice stays accurate even if the product's HSN/rate later changes. */
+    /**
+     * The listing description as it read at purchase.
+     *
+     * 🛑 BOUNDED at `ORDER_ITEM_DESCRIPTION_MAX`, with `descriptionTruncated`
+     * recording that it was cut. A Firestore document caps at 1 MiB and this is
+     * free-form seller prose on every line of every order — an unbounded copy
+     * on a 20-line order is a rejected write AT CHECKOUT, which fails the one
+     * operation that must not fail. Truncation is recorded rather than silent
+     * for the same reason `statusHistoryTruncated` exists: a short description
+     * and a cut one must not read alike.
+     */
+    description?: string;
+    descriptionTruncated?: boolean;
+    /** The spec table as it read at purchase. */
+    specifications?: Array<{
+        name: string;
+        value: string;
+        unit?: string;
+    }>;
+    /**
+     * For a composed listing, the parts it was sold as containing.
+     *
+     * Ids and names only — the part CATALOGUE is a live reference work and
+     * copying its entries onto every order line would duplicate a research
+     * corpus per purchase. What matters for a dispute is which parts were
+     * claimed, not their current catalogue entry.
+     */
+    parts?: Array<{
+        code: string;
+        name: string;
+    }>;
     hsnCode?: string;
     gstRate?: 0 | 5 | 12 | 18 | 28;
     /**
@@ -425,7 +518,64 @@ export interface OrderDocument extends BaseDocument {
     paymentStatus: PaymentStatus;
     paymentId?: string;
     paymentMethod?: string;
+    /**
+     * 🛑 LEGACY. Never written for an order created after Part 14.
+     *
+     * Flat free text with no pincode, no phone and no address id — which is why
+     * `placeOfSupply` had to be written separately rather than derived, and why
+     * parcel booking could not be built at all (`CreateShipmentInput` needs a
+     * structured `{name, phone, addressLine1, city, state, pincode, country}`).
+     *
+     * It is ALSO in `ORDER_UPDATABLE_FIELDS`, so it is editable after the order
+     * — meaning it never recorded what the buyer actually chose. And it was
+     * never encrypted: `ORDER_PII_FIELDS` is `userName` / `userEmail` /
+     * `sellerEmail`, so every delivery address on every order up to now sits in
+     * Firestore in plaintext, despite the docs saying otherwise.
+     *
+     * Read it only as a fallback for orders that predate `deliveryAddress*`,
+     * and render it labelled as legacy. Forward-only; no backfill — parsing a
+     * state out of free text to file a tax return is the thing the
+     * `placeOfSupply` comment below already refuses.
+     */
     shippingAddress?: string;
+    /** PII — encrypted. See `ORDER_PII_FIELDS`. */
+    deliveryFullName?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryPhone?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryAddressLine1?: Encrypted<string>;
+    /** PII — encrypted. Optional second line / apartment. */
+    deliveryAddressLine2?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryLandmark?: Encrypted<string>;
+    deliveryCity?: string;
+    deliveryState?: string;
+    deliveryPincode?: string;
+    deliveryCountry?: string;
+    /**
+     * The `addresses` row this was taken from, for provenance only.
+     *
+     * 🛑 Never resolved at read time. The row can be edited or deleted after the
+     * order, and following it would make the invoice disagree with what the
+     * buyer chose — which is the entire failure a snapshot exists to prevent.
+     */
+    deliveryAddressId?: string;
+    /**
+     * Corrections after the fact, newest LAST. Append-only.
+     *
+     * 🛑 Its OWN array, not a passenger on `statusHistory`.
+     *
+     * `statusHistory` caps at 50 with FIFO eviction. Address edits riding that
+     * log would compete with status transitions for the same slots and evict
+     * the thing the timeline exists to show — and on a chatty order the
+     * creation entry goes first, which is precisely the value reconstruction
+     * depends on. The creation snapshot is a FIELD above for the same reason: a
+     * field cannot be truncated.
+     *
+     * Dispatch reads the latest amendment (or the snapshot when there is none).
+     * The invoice always reads the snapshot.
+     */
+    deliveryAmendments?: DeliveryAmendment[];
     trackingNumber?: string;
     notes?: string;
     orderDate: Date;
@@ -1130,6 +1280,58 @@ export interface OrderDocument extends BaseDocument {
     /** Buyer's required "this payment is genuine, no fraudulent tricks/chargebacks" agreement — server-validated, not just a client-side disable. */
     buyerFraudAgreementAccepted?: boolean;
     buyerFraudAgreementAcceptedAt?: Date;
+    /**
+     * ── D55: the pre-order BALANCE, which is a second payment ──────────────
+     *
+     * 🛑 Its own block rather than reusing the fields above, and that is the
+     * decision this whole feature turns on. Every field above describes ONE
+     * payment; a pre-order has two, months apart. Reusing `paymentProofUrl`
+     * for the balance overwrites the deposit's proof — the evidence for the
+     * payment that created the order — and `paymentReviewOutcome` then means
+     * two different things depending on when you read it.
+     *
+     * Worse, `paymentWindowTimeout` sweeps orders that are `pending`/`pending`
+     * with no `paymentProofUrl`, so clearing that field to collect a balance
+     * would make the sweep cancel and restock a PAID order.
+     *
+     * The balance is therefore its own small state machine beside the
+     * deposit's, sharing the review vocabulary but none of the storage.
+     */
+    balance?: {
+        /**
+         * 🛑 SNAPSHOTTED, not recomputed — D61, and the worst case in the
+         * codebase for it: a deposit-to-balance gap is months. It is copied from
+         * `sourceContext.balanceDue` at the moment the collection is opened, so
+         * a price change, a tax-rate change or a re-quote in between cannot move
+         * what the buyer was told they owe. Recomputing at payment time is how a
+         * buyer who agreed to ₹4,000 is charged ₹4,400.
+         */
+        amount: number;
+        /**
+         * `manual` only, today, and the field exists so the absence is explicit.
+         *
+         * 🛑 The AUTO path is not merely unbuilt — it is blocked on things
+         * outside this repo. A months-long gap cannot use authorise-then-capture
+         * (capture windows are days), so it needs a real RBI-compliant mandate:
+         * AFA at creation, a pre-debit notice at least 24 HOURS before every
+         * debit, and a max amount fixed at registration. Razorpay must also have
+         * recurring enabled, and production runs TEST keys with
+         * `razorpayEnabled` defaulting false. Declaring the union now means
+         * adding `auto` later is a compile-checked change rather than a new
+         * field nobody wires.
+         */
+        method: "manual";
+        status: "awaiting" | "submitted" | "paid" | "rejected";
+        /** Set when the collection is opened, so the buyer has a stated window. */
+        dueBy?: Date;
+        proofUrl?: string;
+        transactionId?: string;
+        submittedAt?: Date;
+        reviewedBy?: string;
+        reviewedAt?: Date;
+        /** Required on `rejected`, for the same reason a refund reason is. */
+        reviewNote?: string;
+    };
     /** Which of the three admin review actions was taken on this order's payment proof. */
     paymentReviewOutcome?: "approved" | "reupload_requested" | "rejected_fraud";
     /** Admin's reason text — required for both `reupload_requested` and `rejected_fraud`. */