@mohasinac/appkit 4.61.0 → 4.62.1

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

@@ -0,0 +1,251 @@
+/**
+ * GSTR-1 export (Phase 7d) — the INPUT to a human filing, never a filing.
+ *
+ * ## 🛑 What this is and is not
+ *
+ * It is a CSV an accountant opens, checks and uses. It is not a return, it is
+ * not filed, and nothing here talks to the GST portal — there is no webhook
+ * facility in existence and no GSP contract. Labelling it otherwise would be
+ * the most consequential lie in this codebase.
+ *
+ * ## 🛑 Credit notes are not optional
+ *
+ * A return listing invoices and no credit notes **does not reconcile**: the
+ * output tax declared would be the tax on every sale including the ones that
+ * were reversed. So both series are exported, the credit notes as negative
+ * amounts, and the file's own total is the net.
+ *
+ * That is also why the two series exist in the first place — a reversal is its
+ * own numbered document, so it has its own row here.
+ *
+ * ## The rate split comes from `gstByRate`
+ *
+ * Already on the order (`firestore.ts`), already per rate, already recorded at
+ * the moment of supply. Nothing is recomputed from today's tax codes: an order
+ * supplied under a rate that has since changed must appear at the rate it was
+ * charged, and re-deriving it would silently restate history — the same defect
+ * the PDF renderer's own 🛑 records about reading live site settings.
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { roundRupees } from "../../../../utils/number.formatter.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+/** One row per (document, rate) slice — which is what a GSTR-1 line is. */
+function rowsForOrder(order) {
+    /*
+     * 🛑 `placeOfSupply` ONLY — never parsed out of `shippingAddress`, which is
+     * a flat string on this document. Deriving a state from free text to file a
+     * tax return is not a thing to do, and an order placed before the field
+     * existed is reported as blank rather than guessed at.
+     */
+    const placeOfSupply = order.placeOfSupply ?? "";
+    const date = order.invoiceIssuedAt ?? order.orderDate ?? order.createdAt;
+    const dateStr = date instanceof Date ? date.toISOString().slice(0, 10) : "";
+    const byRate = order.gstByRate ?? [];
+    const invoiceRows = order.invoiceNumber
+        ? byRate.map((slice) => ({
+            documentNumber: order.invoiceNumber,
+            documentType: "invoice",
+            documentDate: dateStr,
+            orderId: order.id,
+            placeOfSupply,
+            gstRate: slice.gstRate,
+            taxableValue: roundRupees(slice.taxableAmount),
+            cgst: roundRupees(slice.cgst),
+            sgst: roundRupees(slice.sgst),
+            igst: roundRupees(slice.igst),
+            total: roundRupees(slice.taxableAmount + slice.cgst + slice.sgst + slice.igst),
+        }))
+        : [];
+    /*
+     * ── Credit notes, as NEGATIVE rows ────────────────────────────────────────
+     *
+     * 🛑 The tax reversed is apportioned across the SAME rate slices the invoice
+     * carried, pro-rata on the refunded amount. A refund is a rupee figure with
+     * no rate attached, and a multi-rate order's reversal has to be split
+     * somehow — pro-rata on the invoice's own slices is the only split that
+     * reconciles back to the invoice it adjusts.
+     *
+     * 🛑 Only SETTLED refunds appear, and only ones that were numbered. A
+     * `reserved` entry is money that has not moved; a numbered reversal for it
+     * would overstate the period's credit notes.
+     */
+    const invoiceTotal = byRate.reduce((s, r) => s + r.taxableAmount, 0);
+    const creditRows = [];
+    for (const refund of order.refunds ?? []) {
+        if (!refund.creditNoteNumber)
+            continue;
+        if (refund.status === "reserved" || refund.status === "failed")
+            continue;
+        const refundDate = refund.creditNoteIssuedAt ?? refund.refundedAt;
+        const refundDateStr = refundDate instanceof Date ? refundDate.toISOString().slice(0, 10) : dateStr;
+        // No rate information at all — reported as one untaxed row rather than
+        // dropped, so the CSV's total still matches the money that moved.
+        if (invoiceTotal <= 0 || byRate.length === 0) {
+            creditRows.push({
+                documentNumber: refund.creditNoteNumber,
+                documentType: "credit_note",
+                documentDate: refundDateStr,
+                orderId: order.id,
+                placeOfSupply,
+                gstRate: 0,
+                taxableValue: -roundRupees(refund.amount),
+                cgst: 0,
+                sgst: 0,
+                igst: 0,
+                total: -roundRupees(refund.amount),
+            });
+            continue;
+        }
+        for (const slice of byRate) {
+            /*
+             * The slice's share of the refund, and then that amount's share of the
+             * slice — two ratios, because a refund is a gross rupee figure while a
+             * slice is split into taxable value and tax.
+             *
+             * 🛑 `sliceTotal > 0` guards a 0%-rated (exempt) slice, where the tax is
+             * legitimately zero and a naive `portion / sliceTotal` would be a
+             * division by zero producing `Infinity` — and `roundRupees(Infinity)` is
+             * `NaN`, which propagates into the file's TOTAL row and makes every
+             * figure in it unusable. One bad cell would be visible; a NaN total is
+             * the whole return.
+             */
+            const share = slice.taxableAmount / invoiceTotal;
+            const portion = refund.amount * share;
+            const sliceTotal = slice.taxableAmount + slice.cgst + slice.sgst + slice.igst;
+            const taxFraction = sliceTotal > 0 ? portion / sliceTotal : 0;
+            creditRows.push({
+                documentNumber: refund.creditNoteNumber,
+                documentType: "credit_note",
+                documentDate: refundDateStr,
+                orderId: order.id,
+                placeOfSupply,
+                gstRate: slice.gstRate,
+                taxableValue: -roundRupees(slice.taxableAmount * taxFraction),
+                cgst: -roundRupees(slice.cgst * taxFraction),
+                sgst: -roundRupees(slice.sgst * taxFraction),
+                igst: -roundRupees(slice.igst * taxFraction),
+                total: -roundRupees(portion),
+            });
+        }
+    }
+    return [...invoiceRows, ...creditRows];
+}
+/**
+ * Build the export for a date window.
+ *
+ * 🛑 Windowed on the INVOICE date, not the order date. A COD order placed on
+ * 30 March and paid on 2 April is invoiced in the new financial year, and that
+ * is the period its tax belongs to — numbering happens at payment for exactly
+ * this reason.
+ */
+export async function buildGstr1Export(from, to) {
+    const orders = await orderRepository.listInvoicedBetween(from, to);
+    const rows = [];
+    const unnumberedPaidOrders = [];
+    for (const order of orders) {
+        if (order.paymentStatus === "paid" && !order.invoiceNumber) {
+            unnumberedPaidOrders.push(order.id);
+            continue;
+        }
+        rows.push(...rowsForOrder(order));
+    }
+    const totals = rows.reduce((acc, r) => ({
+        taxableValue: acc.taxableValue + r.taxableValue,
+        cgst: acc.cgst + r.cgst,
+        sgst: acc.sgst + r.sgst,
+        igst: acc.igst + r.igst,
+        total: acc.total + r.total,
+    }), { taxableValue: 0, cgst: 0, sgst: 0, igst: 0, total: 0 });
+    if (unnumberedPaidOrders.length > 0) {
+        serverLogger.warn("[gstr1] paid orders with no invoice number in window", {
+            count: unnumberedPaidOrders.length,
+            from: from.toISOString(),
+            to: to.toISOString(),
+        });
+    }
+    return {
+        rows,
+        totals: {
+            taxableValue: roundRupees(totals.taxableValue),
+            cgst: roundRupees(totals.cgst),
+            sgst: roundRupees(totals.sgst),
+            igst: roundRupees(totals.igst),
+            total: roundRupees(totals.total),
+        },
+        unnumberedPaidOrders,
+    };
+}
+const CSV_HEADER = [
+    "Document Number",
+    "Document Type",
+    "Document Date",
+    "Order ID",
+    "Place of Supply",
+    "GST Rate",
+    "Taxable Value",
+    "CGST",
+    "SGST",
+    "IGST",
+    "Total",
+].join(",");
+/**
+ * 🛑 Every field is quoted and internal quotes are doubled.
+ *
+ * An invoice number contains `/`, a place of supply can contain a comma, and a
+ * CSV whose columns shift by one on a single row is worse than no CSV — it
+ * reconciles to a plausible wrong number rather than failing to open.
+ */
+function csvCell(value) {
+    const s = String(value);
+    return `"${s.replace(/"/g, '""')}"`;
+}
+export function gstr1ToCsv(data) {
+    const lines = [CSV_HEADER];
+    for (const r of data.rows) {
+        lines.push([
+            r.documentNumber,
+            r.documentType === "credit_note" ? "Credit Note" : "Invoice",
+            r.documentDate,
+            r.orderId,
+            r.placeOfSupply,
+            r.gstRate,
+            r.taxableValue.toFixed(2),
+            r.cgst.toFixed(2),
+            r.sgst.toFixed(2),
+            r.igst.toFixed(2),
+            r.total.toFixed(2),
+        ]
+            .map(csvCell)
+            .join(","));
+    }
+    /*
+     * A TOTAL row, and it is net of credit notes. An accountant's first act is to
+     * check the file's own total against their own figure; making them sum 400
+     * rows to do it is how a transcription error enters a tax return.
+     */
+    lines.push([
+        "TOTAL",
+        "",
+        "",
+        "",
+        "",
+        "",
+        data.totals.taxableValue.toFixed(2),
+        data.totals.cgst.toFixed(2),
+        data.totals.sgst.toFixed(2),
+        data.totals.igst.toFixed(2),
+        data.totals.total.toFixed(2),
+    ]
+        .map(csvCell)
+        .join(","));
+    /*
+     * 🛑 The exceptions go IN the file, not only in a log. The person filing is
+     * not the person reading our logs, and a paid order absent from a tax return
+     * is the one error this export must not hide.
+     */
+    if (data.unnumberedPaidOrders.length > 0) {
+        lines.push("");
+        lines.push(csvCell(`WARNING: ${data.unnumberedPaidOrders.length} paid order(s) in this window carry no invoice number and are NOT included above: ${data.unnumberedPaidOrders.join(" ")}`));
+    }
+    return lines.join("\n");
+}

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/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.
  *