@mohasinac/appkit 4.62.0 → 4.63.0

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/lottery/schemas/zod.d.ts

@@ -42,12 +42,12 @@ export declare const reopenLotterySlotSchema: z.ZodObject<{
     adminUserId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     slotNumber: number;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     sourceId: string;
     adminUserId: string;
 }, {
     slotNumber: number;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     sourceId: string;
     adminUserId: string;
 }>;
@@ -68,7 +68,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -79,7 +79,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -90,7 +90,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -101,7 +101,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;

package/dist/features/media/MediaImage.js

@@ -113,8 +113,29 @@ export function MediaImage({ src, alt, size = "card", priority = false, loading,
      * the placeholder, the `<picture>` and the plain `<Image>` cannot disagree
      * about their dimensions — a fallback that occupies a different box from the
      * image it replaces makes a grid jump as things load.
+     *
+     * 🛑 `max-h-full` IS THE OTHER HALF OF SIZE_BOX, added 2026-10-23. SIZE_BOX
+     * alone fixed the auto-height parent and broke the ALREADY-SIZED one: a
+     * parent that is 320x128 got a 320x320 box, so `overflow-hidden` cropped it
+     * to the top 40% of a letterboxed square. Measured 89 of 143 call sites in
+     * that shape — every image preview on the review, document and site-settings
+     * surfaces. `max-height:100%` resolves to `none` against an auto-height
+     * parent, so it clamps ONLY in the broken case.
+     *
+     * Measured in a browser (box for each parent shape), not argued:
+     *
+     *   parent               w-full aspect  +max-h-full   +h-full
+     *   320x128 definite     320x320  ✗     320x128  ✓    320x128 ✓
+     *   h128, width shrink   320x320  ✗     320x128  ✓    320x128 ✓
+     *   width 200, h AUTO    200x200  ✓     200x200  ✓    200x784 ✗
+     *   64px thumb stretched
+     *     by a flex row       64x64   ✓      64x64   ✓     64x90  ✗
+     *
+     * So `h-full` is NOT the fix — it wins over `aspect-ratio` whenever the
+     * parent's height is definite, including the height a flex/grid row hands a
+     * thumbnail by stretching it. That is why this is a MAX and not a height.
      */
-    const boxClass = fill ? "h-full" : SIZE_BOX[size];
+    const boxClass = fill ? "h-full" : `${SIZE_BOX[size]} max-h-full`;
     // Reset error/load/retry state whenever the resolved src actually changes.
     // Without this, a component instance that hit a load failure once (e.g.
     // lost the post-upload propagation race above) latches hasError forever,

package/dist/features/media/upload/ImageUpload.js

@@ -222,7 +222,7 @@ accept = IMAGE_ACCEPT_ATTR, maxSizeMB = MAX_IMAGE_BYTES / MEGABYTE, label = "Upl
             fileInputRef.current.value = "";
         onChange?.("");
     };
-    return (_jsxs(Stack, { gap: "3", children: [label && (_jsx(Label, { className: "block", color: "muted", size: "sm", weight: "medium", children: label })), _jsx(Div, { className: "relative", children: preview ? (_jsxs(Stack, { gap: "sm", children: [_jsxs(Div, { className: `relative h-32 max-w-xs mx-auto ${__O.hidden}`, rounded: "lg", border: "default", children: [_jsx(MediaImage, { src: preview, alt: "Preview", size: "card" }), uploading && progress > 0 && (_jsx(Div, { className: "absolute inset-x-0 bottom-0", children: _jsx(Progress, { value: progress, size: "sm" }) }))] }), !uploading && (_jsxs(Row, { wrap: true, gap: "sm", children: [(enableCrop || enableAdvancedCrop) && (_jsx(Button, { type: "button", onClick: () => openEditor(preview), variant: "secondary", size: "sm", children: tMediaEditor("editImage") })), _jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), variant: "outline", size: "sm", children: tUpload("change") }), _jsx(Button, { type: "button", onClick: handleRemove, variant: "danger", size: "sm", children: tUpload("remove") })] }))] })) : (_jsxs(_Fragment, { children: [showCamera && isCameraSupported && (_jsx(CameraCapture, { mode: "photo", facingMode: "environment", onCapture: handleCameraCapture, onError: setError })), !showCamera && (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "sm", wrap: true, children: [showFileInput && (_jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), disabled: uploading, variant: "outline", size: "sm", children: uploading ? tUpload("uploading") : tUpload("clickToUpload") })), captureSource !== "file-only" && isCameraSupported && (_jsx(Button, { type: "button", onClick: () => setCaptureMode("camera"), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") })), captureSource !== "file-only" && !isCameraSupported && (_jsx(Button, { type: "button", onClick: () => mobileCaptureRef.current?.click(), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") }))] }), _jsxs(Text, { size: "xs", variant: "secondary", children: [accept === "image/*"
+    return (_jsxs(Stack, { gap: "3", children: [label && (_jsx(Label, { className: "block", color: "muted", size: "sm", weight: "medium", children: label })), _jsx(Div, { className: "relative", children: preview ? (_jsxs(Stack, { gap: "sm", children: [_jsxs(Div, { className: `relative w-full h-32 max-w-xs mx-auto ${__O.hidden}`, rounded: "lg", border: "default", children: [_jsx(MediaImage, { src: preview, alt: "Preview", size: "card" }), uploading && progress > 0 && (_jsx(Div, { className: "absolute inset-x-0 bottom-0", children: _jsx(Progress, { value: progress, size: "sm" }) }))] }), !uploading && (_jsxs(Row, { wrap: true, gap: "sm", children: [(enableCrop || enableAdvancedCrop) && (_jsx(Button, { type: "button", onClick: () => openEditor(preview), variant: "secondary", size: "sm", children: tMediaEditor("editImage") })), _jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), variant: "outline", size: "sm", children: tUpload("change") }), _jsx(Button, { type: "button", onClick: handleRemove, variant: "danger", size: "sm", children: tUpload("remove") })] }))] })) : (_jsxs(_Fragment, { children: [showCamera && isCameraSupported && (_jsx(CameraCapture, { mode: "photo", facingMode: "environment", onCapture: handleCameraCapture, onError: setError })), !showCamera && (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "sm", wrap: true, children: [showFileInput && (_jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), disabled: uploading, variant: "outline", size: "sm", children: uploading ? tUpload("uploading") : tUpload("clickToUpload") })), captureSource !== "file-only" && isCameraSupported && (_jsx(Button, { type: "button", onClick: () => setCaptureMode("camera"), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") })), captureSource !== "file-only" && !isCameraSupported && (_jsx(Button, { type: "button", onClick: () => mobileCaptureRef.current?.click(), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") }))] }), _jsxs(Text, { size: "xs", variant: "secondary", children: [accept === "image/*"
                                             ? `JPG PNG GIF WebP`
                                             : accept.split(",").map((a) => a.split("/")[1]?.toUpperCase() ?? a).join(" "), " ", "\u2014 max ", maxSizeMB, "MB"] })] }))] })) }), _jsx("input", { ref: fileInputRef, type: "file", accept: accept, onChange: handleFileChange, className: "hidden", "aria-hidden": "true", "data-testid": "media-upload-input" }), showCamera && !isCameraSupported && (_jsx("input", { ref: mobileCaptureRef, type: "file", accept: IMAGE_ACCEPT_ATTR, capture: "environment", onChange: handleFileChange, className: "hidden", "aria-hidden": "true", "data-testid": "media-upload-capture-input" })), helperText && !error && (_jsx(Text, { variant: "secondary", size: "xs", children: helperText })), error && _jsx(Alert, { variant: "error", children: error }), uploading && (_jsxs(Row, { gap: "sm", children: [_jsx(Spinner, { size: "sm" }), _jsx(Text, { size: "sm", variant: "secondary", children: tUpload("uploadingProgress", { progress }) })] })), cropPreviewUrl && !enableAdvancedCrop && (_jsx(ImageCropModal, { isOpen: showCropModal, imageUrl: cropPreviewUrl, onClose: handleCropClose, onSave: handleCropSave })), cropPreviewUrl && enableAdvancedCrop && (_jsx(ImageEditor, { isOpen: showAdvancedEditor, imageUrl: cropPreviewUrl, onClose: handleAdvancedEditorClose, onSave: handleAdvancedEditorSave, aspectRatio: cropAspectRatio }))] }));
 }

package/dist/features/obligations/constants/policies.js

@@ -37,6 +37,7 @@
 import { ORDER_RETURN_WINDOW_DAYS, ORDER_AUTO_CONFIRM_DAYS, } from "../../../_internal/shared/features/orders/config.js";
 import { PROTECTION_CLAIM_WINDOW_HOURS } from "../../../_internal/shared/features/shipping/protections.js";
 import { PAYMENT_WINDOW_MINUTES } from "../../orders/constants/payment-window.js";
+import { hasOpenCourierBlock } from "../../orders/utils/courier-block.js";
 const isPaid = (o) => o.paymentStatus === "paid";
 const notTerminal = (o) => o.status !== "cancelled" && o.status !== "refunded";
 /**
@@ -87,7 +88,29 @@ export const OBLIGATION_POLICIES = {
         anchor: (o) => o.acceptedAt,
         duration: { value: 2, unit: "days", calendar: "business" },
         warnAt: [{ value: 8, unit: "hours", calendar: "calendar" }],
-        precondition: (o) => isPaid(o) && notTerminal(o) && !hasDispatched(o),
+        /*
+         * 🛑 `!hasOpenCourierBlock(o)` — DO NOT REMOVE, and do not "simplify" it
+         * into the stored field.
+         *
+         * This is `onDue: "act"`, so firing cancels the order and refunds the
+         * buyer with the seller recorded as having failed to dispatch. When the
+         * platform's own courier wallet is empty, nothing the seller can do makes
+         * the booking succeed — so without this guard our funding state cancels a
+         * paid order and blames them for it.
+         *
+         * The engine re-evaluates `precondition` at fire time and closes
+         * `superseded` when it returns false, so the clock PAUSES while blocked and
+         * resumes when the block clears. No new mechanism, no stored timer.
+         *
+         * 🛑 This is the ONLY `onDue: "act"` policy that needs the guard, and the
+         * others were checked rather than assumed: `hasDispatched` is
+         * `Boolean(o.shippingDate)`, so `delivery-confirm` (which REQUIRES
+         * `hasDispatched`) and everything post-delivery can never fire on an order
+         * that was never booked. `seller-accept` requires `!o.acceptedAt`, and a
+         * booking is only attempted after acceptance. Adding the guard there too
+         * would be redundant and would imply nobody traced it.
+         */
+        precondition: (o) => isPaid(o) && notTerminal(o) && !hasDispatched(o) && !hasOpenCourierBlock(o),
         blockedBy: ["seller-accept"],
         onDue: "act",
         publishedCopyKey: "obligations.sellerDispatch",

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/OrderPaymentSummary.js

@@ -32,7 +32,16 @@ function legacyFallback(order) {
         method,
         transactionId: order.paymentTransactionId ?? order.paymentId,
         proofUrl: order.paymentProofUrl,
-        amount: order.totalPrice,
+        /*
+         * 🛑 D46/D47 — `amountDue`, falling back to `totalPrice`. This figure is
+         * what a MANUAL payer is told to transfer and what an admin verifies the
+         * proof against, so on a points-funded order `totalPrice` would ask the
+         * buyer for money the order does not owe — and then the admin would reject
+         * a correct ₹750 UTR for not matching ₹1,000.
+         *
+         * `?? totalPrice`, never `?? 0`: absent means no points were used.
+         */
+        amount: order.amountDue ?? order.totalPrice,
         verificationMethod: method === "cod" ? "cod_collection" : method === "manual" ? "manual_review" : "order_status",
     };
 }

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

@@ -0,0 +1,8 @@
+import type { OrderSourceContext } from "../schemas/firestore";
+export interface OrderProvenanceCardProps {
+    sourceContext?: OrderSourceContext;
+    /** Falls back to the configured default currency when omitted. */
+    currency?: string;
+    className?: string;
+}
+export declare function OrderProvenanceCard({ sourceContext, currency, className, }: OrderProvenanceCardProps): import("react").JSX.Element | null;