@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/server/features/invoicing/issue.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Issuing an invoice: allocate the number, render, store the bytes (Phase 7).
+ *
+ * ## 🛑 WHERE the PDF goes, and why it is not the media path
+ *
+ * `private/invoices/{orderId}/{uuid}.pdf`, with **no `mediaAssets` row** and a
+ * **random** object name. An invoice carries the buyer's full name, address and
+ * phone.
+ *
+ * Three facts, each of which alone would be enough:
+ *
+ * 1. `/api/media/[...slug]` applies **no authentication at all** — it is a
+ *    deliberately bare handler whose job is watermarking public product
+ *    photography.
+ * 2. The bucket's storage rule is `allow read: if true`.
+ * 3. Media filenames in this codebase are content-derived and therefore
+ *    GUESSABLE — `generateInvoiceFilename` is `invoice-{orderId}-{YYYYMMDD}`.
+ *
+ * So the random name is against the SEO-slug convention everywhere else *on
+ * purpose*: guessable is the one property this must not have. And the `private/`
+ * prefix is refused by the proxy's raw-path fallback — a check, not a naming
+ * convention, which is precisely the distinction the digital-content comment
+ * got wrong for weeks.
+ *
+ * ## 🛑 Store the bytes; never re-render to serve or to email
+ *
+ * Two renders can disagree — a changed template, a different library version,
+ * a settings read that moved — and the buyer's copy must be byte-identical to
+ * ours. So the bytes are written once, at issue time, and every later consumer
+ * reads that object. On-demand rendering survives only as a fallback for orders
+ * that predate this phase and have no stored path.
+ */
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+/** Storage prefix. Mirrors `private/digital-content/` — refused by the proxy. */
+export declare const INVOICE_PREFIX_PATH = "private/invoices";
+/**
+ * Renders the PDF for an order.
+ *
+ * Injected rather than imported, because the renderer lives in
+ * `functions/src/invoice-pdf.ts` — it pulls `pdfkit`, which is a Functions
+ * dependency and has no business in appkit's module graph (Rule #6's build
+ * weight, and Root Cause #18's import-chain trap).
+ */
+export type InvoiceRenderer = (order: OrderDocument) => Promise<Buffer>;
+export interface IssueInvoiceResult {
+    invoiceNumber: string;
+    invoiceStoragePath: string;
+    /** False when the order already had an invoice — the normal re-entry case. */
+    issued: boolean;
+}
+/**
+ * Give a paid order its invoice number and its stored PDF.
+ *
+ * 🛑 Idempotent through `allocateSeriesNumber`'s transactional claim.
+ * `onOrderStatusChange` can fire more than once, and two numbers for one order
+ * is the single unrecoverable failure in this phase — a number cannot be
+ * withdrawn without leaving a gap.
+ *
+ * 🛑 Called on `paymentStatus → paid`, never at creation. COD and manual orders
+ * are created `pending`.
+ */
+export declare function issueInvoiceForOrder(order: OrderDocument, render: InvoiceRenderer): Promise<IssueInvoiceResult>;
+/**
+ * Persist bytes rendered on demand, for an order that is already NUMBERED.
+ *
+ * ## Why the lazy path exists at all
+ *
+ * Numbering happens in `onOrderStatusChange`, which runs in appkit and cannot
+ * render — `pdfkit` is a Functions dependency and bringing it into appkit's
+ * module graph would add it to every consumer build (Rule #6's build weight,
+ * Root Cause #18's import chain). So the two halves are split: the number is
+ * allocated immediately and transactionally, the bytes are produced the first
+ * time anyone asks for them and then stored forever.
+ *
+ * That split is a deliberate trade and worth naming: the first download of a
+ * given invoice pays a render, and every later one does not. The alternative —
+ * a second Firestore trigger on `orders` living in `functions/` — is the shape
+ * that burned a million invocations a day in Root Cause #92.
+ *
+ * 🛑 Refuses to overwrite an existing path. A second numbered copy of one
+ * invoice is two documents claiming one number, and the one a buyer already
+ * downloaded is the one that counts.
+ *
+ * 🛑 Refuses an un-numbered order. Storing a PDF before the number exists
+ * would freeze a pre-payment snapshot as "the invoice", and the real issuance
+ * would then find a path already set.
+ */
+export declare function storeRenderedInvoice(orderId: string, bytes: Buffer): Promise<string | null>;
+/**
+ * The stored bytes for an already-issued invoice, or null.
+ *
+ * Returns null rather than throwing on a missing object, because the caller's
+ * correct response is to fall back to an on-demand render for a pre-Phase-7
+ * order — and a throw would turn a legacy order's invoice page into an error.
+ */
+export declare function readStoredInvoice(storagePath: string | undefined): Promise<Buffer | null>;

package/dist/_internal/server/features/invoicing/issue.js

@@ -0,0 +1,202 @@
+/**
+ * Issuing an invoice: allocate the number, render, store the bytes (Phase 7).
+ *
+ * ## 🛑 WHERE the PDF goes, and why it is not the media path
+ *
+ * `private/invoices/{orderId}/{uuid}.pdf`, with **no `mediaAssets` row** and a
+ * **random** object name. An invoice carries the buyer's full name, address and
+ * phone.
+ *
+ * Three facts, each of which alone would be enough:
+ *
+ * 1. `/api/media/[...slug]` applies **no authentication at all** — it is a
+ *    deliberately bare handler whose job is watermarking public product
+ *    photography.
+ * 2. The bucket's storage rule is `allow read: if true`.
+ * 3. Media filenames in this codebase are content-derived and therefore
+ *    GUESSABLE — `generateInvoiceFilename` is `invoice-{orderId}-{YYYYMMDD}`.
+ *
+ * So the random name is against the SEO-slug convention everywhere else *on
+ * purpose*: guessable is the one property this must not have. And the `private/`
+ * prefix is refused by the proxy's raw-path fallback — a check, not a naming
+ * convention, which is precisely the distinction the digital-content comment
+ * got wrong for weeks.
+ *
+ * ## 🛑 Store the bytes; never re-render to serve or to email
+ *
+ * Two renders can disagree — a changed template, a different library version,
+ * a settings read that moved — and the buyer's copy must be byte-identical to
+ * ours. So the bytes are written once, at issue time, and every later consumer
+ * reads that object. On-demand rendering survives only as a fallback for orders
+ * that predate this phase and have no stored path.
+ */
+import { randomUUID } from "node:crypto";
+import { getAdminStorage } from "../../../../providers/db-firebase/index.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { allocateSeriesNumber } from "./allocate.js";
+/** Storage prefix. Mirrors `private/digital-content/` — refused by the proxy. */
+export const INVOICE_PREFIX_PATH = "private/invoices";
+/**
+ * Give a paid order its invoice number and its stored PDF.
+ *
+ * 🛑 Idempotent through `allocateSeriesNumber`'s transactional claim.
+ * `onOrderStatusChange` can fire more than once, and two numbers for one order
+ * is the single unrecoverable failure in this phase — a number cannot be
+ * withdrawn without leaving a gap.
+ *
+ * 🛑 Called on `paymentStatus → paid`, never at creation. COD and manual orders
+ * are created `pending`.
+ */
+export async function issueInvoiceForOrder(order, render) {
+    /*
+     * The fast path, and the common one: a second trigger on an order that is
+     * already invoiced does no work and touches no counter. Checked before the
+     * transaction purely to save the round trip — the transaction would reach
+     * the same answer, which is what makes this safe rather than a race.
+     */
+    if (order.invoiceNumber && order.invoiceStoragePath) {
+        return {
+            invoiceNumber: order.invoiceNumber,
+            invoiceStoragePath: order.invoiceStoragePath,
+            issued: false,
+        };
+    }
+    const issuedAt = new Date();
+    const allocation = await allocateSeriesNumber({
+        kind: "invoice",
+        subjectId: order.id,
+        orderId: order.id,
+        at: issuedAt,
+    });
+    /*
+     * 🛑 `randomUUID()`, and the ORDER ID is in the directory rather than the
+     * filename. The directory makes an operator's life possible (every document
+     * for one order is in one place); the random leaf is what makes the object
+     * unguessable. Putting the order id in the FILENAME would undo the second
+     * without improving the first.
+     */
+    const storagePath = `${INVOICE_PREFIX_PATH}/${order.id}/${randomUUID()}.pdf`;
+    /*
+     * Rendered with the number already on the order object, so the PDF carries
+     * the number it was allocated — the renderer reads `order.invoiceNumber`,
+     * and handing it the un-numbered document would produce an invoice with no
+     * number printed on it while the database said otherwise.
+     */
+    const buffer = await render({
+        ...order,
+        invoiceNumber: allocation.number,
+        invoiceIssuedAt: issuedAt,
+    });
+    await getAdminStorage()
+        .bucket()
+        .file(storagePath)
+        .save(buffer, {
+        contentType: "application/pdf",
+        /*
+         * 🛑 `private, no-store` on the OBJECT as well as on every response that
+         * serves it. The object is not reachable without a signed URL or the
+         * Admin SDK, but an intermediate cache that ever saw one must not keep
+         * it: an invoice is one buyer's address, not a product photo.
+         */
+        metadata: { cacheControl: "private, no-store" },
+        resumable: false,
+    });
+    /*
+     * 🛑 The order is updated AFTER the bytes exist. The reverse ordering would
+     * leave an order claiming an `invoiceStoragePath` that resolves to nothing,
+     * and the serve route would then 404 on a document the buyer is entitled to
+     * — while the number is already consumed, so retrying cannot re-issue it.
+     *
+     * A crash between the save and this update leaves an unreferenced object
+     * (a few KB) and an order with a number but no path, which the next trigger
+     * re-renders into a NEW object. Wasteful and harmless, which is the right
+     * side of this trade.
+     */
+    await orderRepository.update(order.id, {
+        invoiceNumber: allocation.number,
+        invoiceIssuedAt: issuedAt,
+        invoiceStoragePath: storagePath,
+    });
+    serverLogger.info("[invoicing] invoice issued", {
+        orderId: order.id,
+        invoiceNumber: allocation.number,
+    });
+    return {
+        invoiceNumber: allocation.number,
+        invoiceStoragePath: storagePath,
+        issued: allocation.allocated,
+    };
+}
+/**
+ * Persist bytes rendered on demand, for an order that is already NUMBERED.
+ *
+ * ## Why the lazy path exists at all
+ *
+ * Numbering happens in `onOrderStatusChange`, which runs in appkit and cannot
+ * render — `pdfkit` is a Functions dependency and bringing it into appkit's
+ * module graph would add it to every consumer build (Rule #6's build weight,
+ * Root Cause #18's import chain). So the two halves are split: the number is
+ * allocated immediately and transactionally, the bytes are produced the first
+ * time anyone asks for them and then stored forever.
+ *
+ * That split is a deliberate trade and worth naming: the first download of a
+ * given invoice pays a render, and every later one does not. The alternative —
+ * a second Firestore trigger on `orders` living in `functions/` — is the shape
+ * that burned a million invocations a day in Root Cause #92.
+ *
+ * 🛑 Refuses to overwrite an existing path. A second numbered copy of one
+ * invoice is two documents claiming one number, and the one a buyer already
+ * downloaded is the one that counts.
+ *
+ * 🛑 Refuses an un-numbered order. Storing a PDF before the number exists
+ * would freeze a pre-payment snapshot as "the invoice", and the real issuance
+ * would then find a path already set.
+ */
+export async function storeRenderedInvoice(orderId, bytes) {
+    const order = await orderRepository.findById(orderId);
+    if (!order?.invoiceNumber)
+        return null;
+    if (order.invoiceStoragePath)
+        return order.invoiceStoragePath;
+    const storagePath = `${INVOICE_PREFIX_PATH}/${orderId}/${randomUUID()}.pdf`;
+    await getAdminStorage()
+        .bucket()
+        .file(storagePath)
+        .save(bytes, {
+        contentType: "application/pdf",
+        metadata: { cacheControl: "private, no-store" },
+        resumable: false,
+    });
+    // Path written only after the bytes exist — the reverse would point at
+    // nothing and 404 a document the buyer is entitled to.
+    await orderRepository.update(orderId, { invoiceStoragePath: storagePath });
+    serverLogger.info("[invoicing] invoice bytes stored on first download", {
+        orderId,
+        invoiceNumber: order.invoiceNumber,
+    });
+    return storagePath;
+}
+/**
+ * The stored bytes for an already-issued invoice, or null.
+ *
+ * Returns null rather than throwing on a missing object, because the caller's
+ * correct response is to fall back to an on-demand render for a pre-Phase-7
+ * order — and a throw would turn a legacy order's invoice page into an error.
+ */
+export async function readStoredInvoice(storagePath) {
+    if (!storagePath)
+        return null;
+    try {
+        const [buffer] = await getAdminStorage().bucket().file(storagePath).download();
+        return buffer;
+    }
+    catch (err) {
+        serverLogger.warn("[invoicing] stored invoice unreadable — falling back to render", {
+            storagePath,
+            error: normalizeError(err).message,
+        });
+        return null;
+    }
+}

package/dist/_internal/server/features/offers/destinations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Server-side verification that a coordinated purchase's destinations are real
+ * and belong to the people naming them.
+ *
+ * ## 🛑 Why this file exists at all
+ *
+ * `CoordinationMember.destinationAddressId` is a REFERENCE, which is the right
+ * shape — copying the address inline would put a name, a phone number and a
+ * street into an offer document with no encryption story and no retention
+ * story. But a reference has a failure mode a copy does not:
+ *
+ * **An id is guessable in a way an address is not.** Without this check a
+ * member supplies any `addresses` document id and the parcel ships to a
+ * stranger's house, at the coordinator's expense, with every other part of
+ * the flow behaving correctly. Nothing errors; the order is valid; the goods
+ * simply go somewhere nobody chose.
+ *
+ * So the rule is: **an id that crosses the wire is never trusted, and is
+ * resolved against its claimed owner before anything is written.**
+ */
+import type { CoordinationMember } from "../../../shared/features/offers/coordination";
+/**
+ * Every named destination must exist and belong to the member who named it.
+ *
+ * 🛑 **Owned by THAT MEMBER, not merely by someone.** Checking only that the
+ * address exists and has `ownerType: "user"` would let a member ship to any
+ * other user's saved address — the weaker check reads as a real one and
+ * closes nothing.
+ *
+ * 🛑 **Fails the whole request, naming the member.** Dropping a bad
+ * destination and shipping that member's parcel to the coordinator instead
+ * would be a silent substitution of somebody's delivery address, which is
+ * exactly the class of quiet wrongness this check exists to prevent. Grouped
+ * cart lines take the same position for the same reason.
+ *
+ * One `getAll` over the distinct ids, not one read per member: five members
+ * sharing two destinations is two reads, and Rule #6's budget is per request
+ * rather than per member.
+ */
+export declare function assertOwnedAddresses(members: readonly CoordinationMember[]): Promise<void>;

package/dist/_internal/server/features/offers/destinations.js

@@ -0,0 +1,65 @@
+/**
+ * Server-side verification that a coordinated purchase's destinations are real
+ * and belong to the people naming them.
+ *
+ * ## 🛑 Why this file exists at all
+ *
+ * `CoordinationMember.destinationAddressId` is a REFERENCE, which is the right
+ * shape — copying the address inline would put a name, a phone number and a
+ * street into an offer document with no encryption story and no retention
+ * story. But a reference has a failure mode a copy does not:
+ *
+ * **An id is guessable in a way an address is not.** Without this check a
+ * member supplies any `addresses` document id and the parcel ships to a
+ * stranger's house, at the coordinator's expense, with every other part of
+ * the flow behaving correctly. Nothing errors; the order is valid; the goods
+ * simply go somewhere nobody chose.
+ *
+ * So the rule is: **an id that crosses the wire is never trusted, and is
+ * resolved against its claimed owner before anything is written.**
+ */
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+/**
+ * Every named destination must exist and belong to the member who named it.
+ *
+ * 🛑 **Owned by THAT MEMBER, not merely by someone.** Checking only that the
+ * address exists and has `ownerType: "user"` would let a member ship to any
+ * other user's saved address — the weaker check reads as a real one and
+ * closes nothing.
+ *
+ * 🛑 **Fails the whole request, naming the member.** Dropping a bad
+ * destination and shipping that member's parcel to the coordinator instead
+ * would be a silent substitution of somebody's delivery address, which is
+ * exactly the class of quiet wrongness this check exists to prevent. Grouped
+ * cart lines take the same position for the same reason.
+ *
+ * One `getAll` over the distinct ids, not one read per member: five members
+ * sharing two destinations is two reads, and Rule #6's budget is per request
+ * rather than per member.
+ */
+export async function assertOwnedAddresses(members) {
+    const named = members.filter((m) => !!m.destinationAddressId);
+    if (named.length === 0)
+        return;
+    const ids = [...new Set(named.map((m) => m.destinationAddressId))];
+    const docs = await Promise.all(ids.map((id) => addressesRepository.findById(id)));
+    const byId = new Map(ids.map((id, i) => [id, docs[i]]));
+    for (const member of named) {
+        const address = byId.get(member.destinationAddressId);
+        /*
+         * 🛑 ONE message for "does not exist" and "is not yours".
+         *
+         * Distinguishing them turns this endpoint into an oracle for which
+         * `addresses` ids are real — a caller probes ids and reads existence off
+         * the error text. The member who typed a genuinely stale id and the
+         * member probing somebody else's get the same answer, and only the first
+         * of those has a legitimate next step anyway (pick again).
+         */
+        if (!address || address.ownerType !== "user" || address.ownerId !== member.uid) {
+            throw new ValidationError("A chosen delivery address is not available.", {
+                destinationAddressId: `${member.uid}: that address cannot be used.`,
+            });
+        }
+    }
+}

package/dist/_internal/server/features/orders/actions.d.ts

@@ -1,4 +1,5 @@
 import { type ActionResult } from "../../../shared/types/action-result";
+import { type DisputeKind } from "../../../shared/features/orders/dispute-reasons";
 export declare function createOrderAction(input: unknown): Promise<ActionResult<unknown>>;
 /**
  * Cancel an order, and give the money back if any was taken (D14).
@@ -58,7 +59,13 @@ export declare function adminRejectPaymentAsFraudAction(orderId: string, note: s
  * the seller (store owner), or admin/moderator. Does not itself reverse
  * payment/order status — surfaces to the admin queue for investigation.
  */
-export declare function raiseOrderDisputeAction(orderId: string, reason: string): Promise<ActionResult<void>>;
+export declare function raiseOrderDisputeAction(orderId: string, input: {
+    kind: DisputeKind;
+    /** `disputeReasons/{id}` — must exist and must match `kind`. */
+    reasonId: string;
+    /** The buyer's own words. Optional; the reason is the required part. */
+    detail?: string;
+}): Promise<ActionResult<void>>;
 /**
  * A buyer submits payment for ONE of their own EMI instalments.
  *

package/dist/_internal/server/features/orders/actions.js

@@ -15,6 +15,8 @@ import { adminNotificationsRepository, orderRepository, storeRepository } from "
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
 import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, returnRequestSchema, } from "../../../shared/features/orders/schema.js";
 import { isFinalSaleExempt } from "../../../shared/features/orders/return-reasons.js";
+import { DISPUTE_KIND_LABEL, checkDisputeGate, isDisputeKind, } from "../../../shared/features/orders/dispute-reasons.js";
+import { disputeReasonsRepository } from "../../../../features/dispute-reasons/repository/dispute-reasons.repository.js";
 import { REFUND_COPY } from "../../../shared/features/orders/refund-copy.js";
 import { assertOrderCancellable, assertReturnWindowOpen } from "./service.js";
 import { cancelOrderWithRefund } from "./cancellation-refund.js";
@@ -390,10 +392,12 @@ export async function adminRejectPaymentAsFraudAction(orderId, note) {
  * the seller (store owner), or admin/moderator. Does not itself reverse
  * payment/order status — surfaces to the admin queue for investigation.
  */
-export async function raiseOrderDisputeAction(orderId, reason) {
+export async function raiseOrderDisputeAction(orderId, input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
-        if (!reason.trim())
+        if (!isDisputeKind(input.kind))
+            throw new ValidationError("Pick what kind of problem this is.");
+        if (!input.reasonId?.trim())
             throw new ValidationError(REASON_REQUIRED_MSG);
         const order = await orderRepository.findById(orderId);
         if (!order)
@@ -407,11 +411,50 @@ export async function raiseOrderDisputeAction(orderId, reason) {
         if (!isBuyer && !isSeller && !isAdminUser(user) && !isModeratorUser(user)) {
             throw new OrderOwnershipError(orderId);
         }
-        if (!order.autoApproved) {
-            throw new ValidationError("Disputes can only be raised on auto-approved orders. Use the return/refund flow for manually-reviewed orders.");
-        }
+        /*
+         * 🛑 THE `autoApproved` RESTRICTION IS GONE, and that is the one
+         * behaviour change an existing path will notice.
+         *
+         * It used to refuse every order whose payment was not auto-approved,
+         * telling the caller to use the return/refund flow — which made this a
+         * narrow "the 2-hour auto-approval might have been wrong" escalation
+         * rather than a dispute mechanism. The owner's rules are about delivery
+         * and item problems on ANY order, so the scope had to widen.
+         *
+         * What replaces it is a REAL gate per kind, below: the old check refused
+         * 99% of orders for a reason unrelated to the complaint, while accepting
+         * "it never arrived" on an order delivered last week.
+         */
         if (order.disputeStatus === "open")
             return; // idempotent
+        /*
+         * The reason must exist AND belong to the kind being claimed.
+         *
+         * 🛑 Both halves matter. Without the kind check a caller could pass an
+         * `item` reason with `kind: "not_reached"` and pass the wrong gate — the
+         * kind is what the gate keys on, so an unvalidated pairing is the gate
+         * being bypassed by the request body.
+         */
+        const reasonDoc = await disputeReasonsRepository.findById(input.reasonId.trim());
+        if (!reasonDoc || !reasonDoc.isActive) {
+            throw new ValidationError("That reason is no longer available. Pick another.");
+        }
+        if (reasonDoc.kind !== input.kind) {
+            throw new ValidationError("That reason doesn't match the kind of problem selected.");
+        }
+        /*
+         * ── THE GATES ─────────────────────────────────────────────────────────
+         *
+         * Owner's rules: an item dispute only after the order was received; a
+         * "not reached" dispute only once the ETD is more than 3 days past.
+         *
+         * Enforced HERE, where the request arrives, for the same reason the
+         * 7-day cutoff below is: a refusal has to live where the refusing
+         * happens. The message is buyer-facing and names the next action.
+         */
+        const gate = checkDisputeGate(input.kind, order);
+        if (!gate.allowed)
+            throw new ValidationError(gate.message);
         /*
          * ── THE DISPUTE CUTOFF ────────────────────────────────────────────────
          *
@@ -436,15 +479,39 @@ export async function raiseOrderDisputeAction(orderId, reason) {
          * `disputeWindowClosed` boolean would need a backfill and would drift from
          * the policy the day the duration changed (Root Cause #42).
          */
+        /*
+         * 🛑 This correctly does NOT apply to a `not_reached` dispute, and that is
+         * not an oversight to "fix".
+         *
+         * `order-complete` is anchored on `deliveryDate`, so `deadlinesFor` yields
+         * no such deadline when nothing was delivered — and you cannot be past a
+         * delivery window that never happened. Making the cutoff refuse
+         * undelivered parcels would block exactly the buyers whose parcel is lost,
+         * which is the opposite of what a dispute window is for.
+         */
         const completion = deadlinesFor(order).find((d) => d.kind === "order-complete");
         if (completion && completion.dueAt.getTime() <= Date.now()) {
             throw new ValidationError(`The dispute window for this order closed on ${completion.dueAt.toLocaleDateString("en-IN")} — 7 days after delivery. Contact support if you believe this is wrong.`);
         }
+        /*
+         * No `as any`. Every field below is declared on `OrderDocument`, and the
+         * cast that used to be here is precisely how a misspelled field reaches
+         * Firestore unnoticed — it silences the check on all six at once.
+         *
+         * 🛑 `disputeReason` stores the reason's LABEL, not its id. It is a
+         * SNAPSHOT: staff can retire or reword a `disputeReasons` row, and neither
+         * may rewrite what a buyer said months ago. `disputeReasonId` beside it is
+         * the join key for "what are buyers reporting"; the label is the record.
+         * Same discipline as the fee terms and the box presets.
+         */
         await orderRepository.update(orderId, {
             disputeRaised: true,
             disputeRaisedBy: user.uid,
             disputeRaisedAt: new Date(),
-            disputeReason: reason,
+            disputeKind: input.kind,
+            disputeReasonId: reasonDoc.id,
+            disputeReason: reasonDoc.label,
+            ...(input.detail?.trim() ? { disputeDetail: input.detail.trim() } : {}),
             disputeStatus: "open",
         });
         /*
@@ -463,8 +530,14 @@ export async function raiseOrderDisputeAction(orderId, reason) {
         await adminNotificationsRepository
             .create({
             category: "fraud",
-            title: "Dispute raised on auto-approved order",
-            body: `A dispute was raised on order "${order.productTitle}" (auto-approved payment). Reason: ${reason}.`,
+            /*
+             * 🛑 No longer "on auto-approved order". The title said that because
+             * the action refused everything else; now any order can be disputed,
+             * and a title naming a payment path the dispute has nothing to do with
+             * would send an operator looking in the wrong place.
+             */
+            title: `Dispute raised: ${DISPUTE_KIND_LABEL[input.kind]}`,
+            body: `A dispute was raised on order "${order.productTitle}". Reason: ${reasonDoc.label}.${input.detail?.trim() ? ` Buyer said: "${input.detail.trim()}"` : ""}`,
             severity: "error",
             isRead: false,
             entityType: "order",

package/dist/_internal/server/features/orders/adapters.js

@@ -203,6 +203,39 @@ export function orderDocumentToOrder(doc) {
         saleProtectionAddon: doc.saleProtectionAddon,
         saleProtectionFee: doc.saleProtectionFee,
         platformFee: doc.platformFee,
+        /*
+         * D46/D47 — the points tender, mapped for the same reason as everything
+         * above it and stated once more because this is the field most likely to
+         * be dropped: it is optional, it is absent on every historical order, and a
+         * surface that never receives it renders as though no points were used.
+         *
+         * That is Root Cause #57 exactly, and on this field it is not cosmetic —
+         * the order page would show a buyer "Total ₹1,000" and a card statement
+         * reading ₹750 with nothing on the page explaining the difference, which
+         * reads as an overcharge rather than as their own discount.
+         *
+         * Readers must use `amountDue ?? total`, never a `?? 0`: absent means "no
+         * points, the whole total was collected", and zero means free.
+         */
+        pointsApplied: doc.pointsApplied,
+        amountDue: doc.amountDue,
+        /*
+         * Phase 7 — the invoice number, mapped for the same Root Cause #57 reason
+         * as everything above. Unmapped, the buyer's invoice page would render a
+         * statutory document with no number on it while the database held one, and
+         * the only symptom would be a blank line where an auditor looks first.
+         *
+         * 🛑 `invoiceStoragePath` is deliberately NOT mapped. It is a raw Storage
+         * path, and the client has no use for one — the bytes are served by an
+         * authenticated route. Publishing the path into an RSC payload would hand
+         * every buyer a string pointing at a private object, which is the shape of
+         * Root Cause #70's leak even though the `private/` prefix is refused by
+         * the proxy.
+         */
+        invoiceNumber: doc.invoiceNumber,
+        invoiceIssuedAt: doc.invoiceIssuedAt
+            ? new Date(doc.invoiceIssuedAt).toISOString()
+            : undefined,
         /*
          * 🛑 `gstAmount` -> `tax`, and codHandlingFee alongside it.
          *
@@ -313,6 +346,27 @@ export function orderDocumentToOrder(doc) {
         timelineTruncated: doc.statusHistoryTruncated,
         /** How the buyer acquired the right to buy. Written once, at creation. */
         sourceContext: doc.sourceContext,
+        /*
+         * D55 — the pre-order balance, present only once a seller has opened it.
+         *
+         * 🛑 `reviewedBy` is deliberately NOT mapped. It is the reviewing staff
+         * member's uid and no buyer surface reads it, so it stays server-side by
+         * default (§ Public Data Projections — a field is private until someone
+         * names the client that reads it).
+         */
+        balance: doc.balance
+            ? {
+                amount: doc.balance.amount,
+                method: doc.balance.method,
+                status: doc.balance.status,
+                dueBy: toIsoOrUndefined(doc.balance.dueBy),
+                proofUrl: doc.balance.proofUrl,
+                transactionId: doc.balance.transactionId,
+                submittedAt: toIsoOrUndefined(doc.balance.submittedAt),
+                reviewedAt: toIsoOrUndefined(doc.balance.reviewedAt),
+                reviewNote: doc.balance.reviewNote,
+            }
+            : undefined,
         createdAt: doc.createdAt instanceof Date
             ? doc.createdAt.toISOString()
             : String(doc.createdAt),