@mohasinac/appkit 4.62.1 → 4.63.1

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

@@ -0,0 +1,183 @@
+/**
+ * `chartOfAccounts` + `journalEntries` — Part 4's double-entry books.
+ *
+ * ## 🛑 THE LEDGER IS A PROJECTION. Orders, payouts and expenses are truth.
+ *
+ * The same split `obligations` takes, and for the same reason. An order says
+ * what was sold; a journal entry is an accounting *statement about* that
+ * order. So: **never read a balance to make an operational decision.** Do not
+ * gate a payout on a ledger figure, do not refuse a refund because an account
+ * looks short — read the payout and the order. A projection that starts
+ * making decisions becomes a second source of truth, and then the two
+ * disagree with no way to say which is wrong.
+ *
+ * ## 🛑 Every entry is MACHINE-GENERATED from a business event
+ *
+ * This is the one constraint that makes the whole thing safe. If a human has
+ * to remember that a gateway fee is `Dr Bank Charges / Cr Bank`, it will
+ * eventually be posted the other way round; if the settlement ingest posts
+ * it, it cannot be. `sourceEvent` is REQUIRED and names the event, not the
+ * person — a hand-posted adjustment uses `"manual-journal"`, which is a
+ * distinguishable value precisely so the exception stays countable.
+ *
+ * ## 🛑 A correction is a REVERSING ENTRY, never an edit
+ *
+ * The invoice/credit-note rule, applied to the books. `journalEntries` rows
+ * are append-only: `reverse()` writes a NEW entry with the legs swapped and
+ * the two pointed at each other. An edit would silently rewrite a period a
+ * GST return has already been filed for, and nothing downstream could tell.
+ *
+ * ## 🛑 Money is DECIMAL RUPEES, matching every other money field here
+ *
+ * Rupees with two decimal places, like every other money field here. The
+ * 2026-05 migration moved the whole codebase off minor units and
+ * `audit-money-units` enforces it; a ledger in minor units would be the one
+ * place a reader has to remember a different scale, which is how a 100×
+ * error gets written (Root Cause #31).
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const CHART_OF_ACCOUNTS_COLLECTION = "chartOfAccounts";
+export declare const JOURNAL_ENTRIES_COLLECTION = "journalEntries";
+export declare const ACCOUNTING_PERIODS_COLLECTION = "accountingPeriods";
+/**
+ * The five classical account types.
+ *
+ * Carried on the ACCOUNT rather than inferred from its code, because the
+ * normal-balance side and every report's sign convention derive from it —
+ * and a report that guesses the type from a code prefix breaks the first time
+ * somebody adds an account out of range.
+ */
+export type AccountType = "asset" | "liability" | "equity" | "income" | "expense";
+/**
+ * Which side INCREASES this account.
+ *
+ * Derived from `AccountType` by `normalBalanceFor`, never stored — a stored
+ * copy is a mirror that drifts the first time somebody types the wrong one
+ * (Root Cause #42), and the mapping is a fact about accounting rather than
+ * about this business.
+ */
+export type NormalBalance = "debit" | "credit";
+export declare function normalBalanceFor(type: AccountType): NormalBalance;
+export interface ChartAccountDocument extends BaseDocument {
+    /**
+     * Stable numeric code, e.g. `"1100"`. The id is `account-{code}`.
+     *
+     * 🛑 Codes are grouped by type in the conventional Indian small-business
+     * ranges (1xxx asset, 2xxx liability, 3xxx equity, 4xxx income, 5xxx
+     * expense) **so a CA can map them to Tally at a glance** — that is the
+     * entire reason for a numeric code rather than a slug. It is a convention
+     * for humans; nothing in the code derives `type` from the range, because a
+     * derivation would make adding an account outside it silently wrong.
+     */
+    code: string;
+    name: string;
+    type: AccountType;
+    /** A one-line note for whoever has to reconcile this against a bank statement. */
+    description?: string;
+    /**
+     * A closed account refuses new postings but keeps its history.
+     *
+     * Deliberately not a delete: an account with entries against it cannot be
+     * removed without orphaning them, and a closed row still has to appear in
+     * last year's trial balance.
+     */
+    isActive: boolean;
+}
+/**
+ * One side of one entry.
+ *
+ * 🛑 `debit` and `credit` are SEPARATE non-negative fields rather than one
+ * signed amount. A signed amount needs a sign convention, the convention
+ * differs per account type, and a reader then has to know the account's type
+ * to interpret the number — which is how a credit gets read as a debit. Two
+ * fields are unambiguous at the point of reading, which is where it matters.
+ *
+ * Exactly one of them is non-zero on any line; `assertBalanced` refuses both.
+ */
+export interface JournalLine {
+    accountCode: string;
+    debit: number;
+    credit: number;
+    /** Why this leg exists, for a human reading the entry a year later. */
+    memo?: string;
+    /**
+     * Who this leg is ABOUT, when that is a specific counterparty — a store for
+     * a seller payable, a vendor for a bill.
+     *
+     * Optional because most legs (bank, GST, sales) have no counterparty. Where
+     * it exists it is what makes a per-seller payable ageing possible without a
+     * separate ledger per store.
+     */
+    counterpartyId?: string;
+}
+/**
+ * What caused this entry. REQUIRED, and the closed list is the point.
+ *
+ * 🛑 `manual-journal` is a real member and must stay one. The alternative —
+ * letting a hand-posted entry claim an automated source — is how the "every
+ * entry is machine-generated" constraint stops being checkable. With it
+ * declared, "how many of our entries were typed by a person" is one query.
+ */
+export type JournalSourceEvent = "order-placed" | "order-delivered" | "order-refunded" | "payout-paid" | "settlement-ingest" | "expense-recorded" | "asset-purchased" | "opening-balance" | "manual-journal" | "reversal";
+export interface JournalEntryDocument extends BaseDocument {
+    /**
+     * The date the entry BELONGS TO, which is not when it was written.
+     *
+     * A settlement ingested on the 3rd for transactions on the 31st posts to
+     * the 31st. `createdAt` records when we learned; this records when it
+     * happened, and every report and the period lock read this one.
+     */
+    entryDate: Date;
+    /** `YYYY-MM`, derived from `entryDate` — the lock and the rollups key on it. */
+    period: string;
+    sourceEvent: JournalSourceEvent;
+    /**
+     * The record that caused this — an order id, a payout id, an expense id.
+     *
+     * Absent only for `opening-balance` and `manual-journal`, which have no
+     * causing record by definition. `verify-posting-rules` checks that pairing
+     * rather than trusting it.
+     */
+    sourceId?: string;
+    narration: string;
+    lines: JournalLine[];
+    /**
+     * Both totals, stored.
+     *
+     * 🛑 Redundant with `lines` ON PURPOSE, and this is the one place a mirror
+     * is right: a trial balance that had to sum every line of every entry is an
+     * unbounded read, and these two are written inside the same transaction
+     * that validated them. They cannot drift, because nothing can write an
+     * entry without going through `assertBalanced`.
+     */
+    totalDebit: number;
+    totalCredit: number;
+    /** Set on the entry this one reverses, and on the reversal, pointing both ways. */
+    reversedByEntryId?: string;
+    reversesEntryId?: string;
+}
+/**
+ * A period, and whether it is closed.
+ *
+ * Id is the period itself (`period-2026-10`), so the lock check is a single
+ * `get` by a key the caller already has — not a query.
+ */
+export interface AccountingPeriodDocument extends BaseDocument {
+    /** `YYYY-MM`. */
+    period: string;
+    status: "open" | "locked";
+    /** Set when locked — which GST return this period was filed under. */
+    lockedReason?: string;
+    lockedAt?: Date;
+    lockedByUid?: string;
+}
+export declare const LEDGER_FIELDS: {
+    readonly CODE: "code";
+    readonly TYPE: "type";
+    readonly IS_ACTIVE: "isActive";
+    readonly ENTRY_DATE: "entryDate";
+    readonly PERIOD: "period";
+    readonly SOURCE_EVENT: "sourceEvent";
+    readonly SOURCE_ID: "sourceId";
+    readonly STATUS: "status";
+};

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

@@ -0,0 +1,69 @@
+/**
+ * `chartOfAccounts` + `journalEntries` — Part 4's double-entry books.
+ *
+ * ## 🛑 THE LEDGER IS A PROJECTION. Orders, payouts and expenses are truth.
+ *
+ * The same split `obligations` takes, and for the same reason. An order says
+ * what was sold; a journal entry is an accounting *statement about* that
+ * order. So: **never read a balance to make an operational decision.** Do not
+ * gate a payout on a ledger figure, do not refuse a refund because an account
+ * looks short — read the payout and the order. A projection that starts
+ * making decisions becomes a second source of truth, and then the two
+ * disagree with no way to say which is wrong.
+ *
+ * ## 🛑 Every entry is MACHINE-GENERATED from a business event
+ *
+ * This is the one constraint that makes the whole thing safe. If a human has
+ * to remember that a gateway fee is `Dr Bank Charges / Cr Bank`, it will
+ * eventually be posted the other way round; if the settlement ingest posts
+ * it, it cannot be. `sourceEvent` is REQUIRED and names the event, not the
+ * person — a hand-posted adjustment uses `"manual-journal"`, which is a
+ * distinguishable value precisely so the exception stays countable.
+ *
+ * ## 🛑 A correction is a REVERSING ENTRY, never an edit
+ *
+ * The invoice/credit-note rule, applied to the books. `journalEntries` rows
+ * are append-only: `reverse()` writes a NEW entry with the legs swapped and
+ * the two pointed at each other. An edit would silently rewrite a period a
+ * GST return has already been filed for, and nothing downstream could tell.
+ *
+ * ## 🛑 Money is DECIMAL RUPEES, matching every other money field here
+ *
+ * Rupees with two decimal places, like every other money field here. The
+ * 2026-05 migration moved the whole codebase off minor units and
+ * `audit-money-units` enforces it; a ledger in minor units would be the one
+ * place a reader has to remember a different scale, which is how a 100×
+ * error gets written (Root Cause #31).
+ */
+export const CHART_OF_ACCOUNTS_COLLECTION = "chartOfAccounts";
+export const JOURNAL_ENTRIES_COLLECTION = "journalEntries";
+export const ACCOUNTING_PERIODS_COLLECTION = "accountingPeriods";
+export function normalBalanceFor(type) {
+    return type === "asset" || type === "expense" ? "debit" : "credit";
+}
+export const LEDGER_FIELDS = {
+    CODE: "code",
+    TYPE: "type",
+    IS_ACTIVE: "isActive",
+    ENTRY_DATE: "entryDate",
+    PERIOD: "period",
+    SOURCE_EVENT: "sourceEvent",
+    SOURCE_ID: "sourceId",
+    STATUS: "status",
+};
+/*
+ * 🛑 `periodOf` LIVES IN `_internal/shared/features/ledger/posting.ts`, not
+ * here, and the reason is mechanical rather than taxonomic.
+ *
+ * `verify-posting-rules.mjs` imports the posting rules directly via Node's
+ * `--experimental-strip-types` so it exercises the shipped source rather
+ * than a build artefact (Root Cause #105). Type stripping erases
+ * `import type` entirely but cannot RESOLVE a runtime import — appkit source
+ * is written extensionless and the build adds `.js` — so a single runtime
+ * import in that file would make it unloadable and the audit would be a
+ * load-failure instead of a check.
+ *
+ * Deciding which period an entry belongs to is a posting rule anyway, and it
+ * is the one the audit most needs to exercise: a UTC derivation files every
+ * IST evening sale in the previous GST return.
+ */

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();