@mohasinac/appkit 4.62.0 → 4.63.0

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

@@ -0,0 +1,162 @@
+/**
+ * Allocating a number from a gapless series (Phase 7, D12).
+ *
+ * ## The whole design in one paragraph
+ *
+ * One transaction does three things: read the (series, FY) counter, `.create()`
+ * an allocation claim keyed on the subject, and write `lastNumber + 1`. Any one
+ * of the three failing rolls back all of them, so there is no state where a
+ * number was consumed without being recorded, and no state where a subject
+ * holds two numbers.
+ *
+ * ## 🛑 Why the claim is INSIDE the transaction
+ *
+ * The obvious shape is "check whether this order already has a number, then
+ * allocate". That is a read-then-write race: two concurrent triggers both read
+ * "no number", both allocate, and the order ends up with two — one of which is
+ * a permanent gap in a series an auditor reads.
+ *
+ * `.create()` inside the transaction makes it impossible rather than unlikely.
+ * A duplicate attempt fails the transaction, and the caller treats that as
+ * "already allocated" and reads the existing number back. This is the fourth
+ * use of that primitive in this codebase (refund claims, the gateway-event
+ * inbox, the gateway-order claim), and the one with the least recoverable
+ * failure mode.
+ *
+ * ## 🛑 Allocate on `paymentStatus → paid`, never at order creation
+ *
+ * COD and manual orders are created `pending`. Numbering at creation burns a
+ * number on every abandoned order, and *gapless* means those gaps are
+ * unexplainable — "that one was abandoned" is not an answer an auditor accepts
+ * for a missing invoice number.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { INVOICE_ALLOCATION_COLLECTION, INVOICE_COUNTER_COLLECTION, } from "../../../../features/invoicing/schemas/firestore.js";
+import { CREDIT_NOTE_PREFIX, INVOICE_PREFIX, financialYearLabel, formatSeriesNumber, } from "../../../../features/invoicing/utils/financial-year.js";
+function prefixFor(kind) {
+    return kind === "credit_note" ? CREDIT_NOTE_PREFIX : INVOICE_PREFIX;
+}
+/**
+ * Allocate (or return the already-allocated) number for one subject.
+ *
+ * 🛑 Idempotent and NOT best-effort. It throws rather than returning a
+ * sentinel, because every caller's correct response to "we could not number
+ * this" is to leave the order un-invoiced and retry — a caller that treated
+ * failure as "no number needed" would produce a paid order with no invoice,
+ * silently.
+ */
+export async function allocateSeriesNumber(input) {
+    const db = getAdminDb();
+    const at = input.at ?? new Date();
+    const fy = financialYearLabel(at);
+    const counterRef = db
+        .collection(INVOICE_COUNTER_COLLECTION)
+        .doc(`${input.kind}_${fy}`);
+    const claimRef = db.collection(INVOICE_ALLOCATION_COLLECTION).doc(input.subjectId);
+    try {
+        return await db.runTransaction(async (tx) => {
+            /*
+             * 🛑 Both reads BEFORE any write — a Firestore transaction requires it,
+             * and the claim read is what lets an already-allocated subject return
+             * its existing number instead of failing.
+             */
+            const [claimSnap, counterSnap] = await Promise.all([
+                tx.get(claimRef),
+                tx.get(counterRef),
+            ]);
+            if (claimSnap.exists) {
+                const existing = claimSnap.data();
+                return {
+                    number: existing.number,
+                    fy: existing.fy,
+                    sequence: existing.sequence,
+                    allocated: false,
+                };
+            }
+            const last = counterSnap.exists
+                ? (counterSnap.data().lastNumber ?? 0)
+                : 0;
+            const sequence = last + 1;
+            const number = formatSeriesNumber(prefixFor(input.kind), fy, sequence);
+            /*
+             * `set(..., { merge: true })` on the counter rather than `update`,
+             * because the first allocation of a financial year creates it — and
+             * `update` on a missing document throws, which would make 1 April the
+             * one day of the year invoicing breaks.
+             */
+            tx.set(counterRef, {
+                kind: input.kind,
+                fy,
+                lastNumber: sequence,
+                lastIssuedAt: at,
+                updatedAt: at,
+                ...(counterSnap.exists ? {} : { createdAt: at }),
+            }, { merge: true });
+            /*
+             * 🛑 `create`, not `set`. Within a transaction both are atomic against
+             * the counter, but `create` additionally refuses if the claim appeared
+             * between our read and our write — which is exactly the window a
+             * concurrent trigger occupies.
+             */
+            tx.create(claimRef, {
+                kind: input.kind,
+                subjectId: input.subjectId,
+                orderId: input.orderId,
+                number,
+                fy,
+                sequence,
+                issuedAt: at,
+                createdAt: at,
+                updatedAt: at,
+            });
+            return { number, fy, sequence, allocated: true };
+        });
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        /*
+         * A lost race: the other side created the claim first. Read it back rather
+         * than failing — both callers want the same answer, and whoever wrote it
+         * wrote the number this subject now permanently has.
+         */
+        /*
+         * Logged, not swallowed. `.catch(() => null)` alone made a Firestore
+         * failure indistinguishable from "the claim genuinely is not there" — and
+         * the two take opposite branches below: one must fall through to a fresh
+         * allocation, the other must NOT, because re-allocating over a claim that
+         * exists is how an invoice number gets issued twice. Root Cause #59's
+         * shape, in the one place in this codebase where a silent degrade would
+         * duplicate a filed document number.
+         */
+        const after = await claimRef.get().catch((readErr) => {
+            const e = normalizeError(readErr);
+            serverLogger.error("[invoicing] could not re-read the allocation claim after a race", {
+                collection: INVOICE_ALLOCATION_COLLECTION,
+                subjectId: input.subjectId,
+                error: e.message,
+            });
+            return null;
+        });
+        if (after?.exists) {
+            const existing = after.data();
+            serverLogger.info("[invoicing] allocation race resolved to the existing number", {
+                subjectId: input.subjectId,
+                number: existing.number,
+            });
+            return {
+                number: existing.number,
+                fy: existing.fy,
+                sequence: existing.sequence,
+                allocated: false,
+            };
+        }
+        serverLogger.error("[invoicing] allocation failed", {
+            subjectId: input.subjectId,
+            kind: input.kind,
+            error: normalized.message,
+        });
+        throw err;
+    }
+}

package/dist/_internal/server/features/invoicing/credit-note.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Credit notes — the document that reverses tax on a refund (Phase 7, 7c).
+ *
+ * ## 🛑 A refund needs a credit note; it never needs a re-issued invoice
+ *
+ * A GST invoice is issued once. When money goes back, the reversal is its own
+ * numbered document referencing the original invoice — which is why there are
+ * two series rather than a revision suffix on one.
+ *
+ * ## 🛑 Numbered on SETTLEMENT, not on reservation
+ *
+ * `processRefundAction` is two-phase: it reserves an entry, calls the provider,
+ * then settles to `processed` or `failed`. A credit note numbered at
+ * reservation would leave a numbered reversal in the series for money that
+ * never moved, on every provider failure — and the number could not be
+ * withdrawn.
+ *
+ * So this is called from the SETTLE step, for `processed` only.
+ *
+ * ## One per refund event, keyed accordingly
+ *
+ * An order can be refunded several times. The allocation claim is therefore
+ * `${orderId}_${refundId}` — keying on the order alone would refuse the second
+ * credit note, which is the inverse of the invoice's rule and is why
+ * `allocateSeriesNumber` takes `subjectId` separately from `orderId`.
+ */
+import type { OrderDocument, OrderRefundEvent } from "../../../../features/orders/schemas/firestore";
+/** Same private prefix family as invoices — refused by the media proxy. */
+export declare const CREDIT_NOTE_PREFIX_PATH = "private/credit-notes";
+/**
+ * Renders a credit note. Injected for the same reason as `InvoiceRenderer`:
+ * `pdfkit` is a Functions dependency.
+ */
+export type CreditNoteRenderer = (order: OrderDocument, refund: OrderRefundEvent, creditNoteNumber: string) => Promise<Buffer>;
+export interface IssueCreditNoteResult {
+    creditNoteNumber: string;
+    creditNoteStoragePath?: string;
+    issued: boolean;
+}
+/**
+ * Number and (optionally) render the credit note for one settled refund.
+ *
+ * 🛑 **Best-effort by design, and that is the opposite of the invoice rule.**
+ * It is called from the refund settle path, where the money has ALREADY left
+ * the gateway. Throwing here would turn a successful refund into a failed
+ * action — the buyer has their money, our code reports an error, and an
+ * operator retries a refund that already happened. A missing credit note is a
+ * reporting gap recoverable by a backfill; a double refund is not.
+ *
+ * The invoice path throws for the mirror-image reason: nothing irreversible has
+ * happened yet there, so refusing to proceed is the safe direction.
+ *
+ * `render` is optional — passing none numbers the reversal without producing a
+ * document, which is what the GSTR-1 export actually needs (it reconciles
+ * numbers and amounts, not PDFs). The PDF is for the buyer.
+ */
+export declare function issueCreditNoteForRefund(order: OrderDocument, refund: OrderRefundEvent, render?: CreditNoteRenderer): Promise<IssueCreditNoteResult | null>;

package/dist/_internal/server/features/invoicing/credit-note.js

@@ -0,0 +1,126 @@
+/**
+ * Credit notes — the document that reverses tax on a refund (Phase 7, 7c).
+ *
+ * ## 🛑 A refund needs a credit note; it never needs a re-issued invoice
+ *
+ * A GST invoice is issued once. When money goes back, the reversal is its own
+ * numbered document referencing the original invoice — which is why there are
+ * two series rather than a revision suffix on one.
+ *
+ * ## 🛑 Numbered on SETTLEMENT, not on reservation
+ *
+ * `processRefundAction` is two-phase: it reserves an entry, calls the provider,
+ * then settles to `processed` or `failed`. A credit note numbered at
+ * reservation would leave a numbered reversal in the series for money that
+ * never moved, on every provider failure — and the number could not be
+ * withdrawn.
+ *
+ * So this is called from the SETTLE step, for `processed` only.
+ *
+ * ## One per refund event, keyed accordingly
+ *
+ * An order can be refunded several times. The allocation claim is therefore
+ * `${orderId}_${refundId}` — keying on the order alone would refuse the second
+ * credit note, which is the inverse of the invoice's rule and is why
+ * `allocateSeriesNumber` takes `subjectId` separately from `orderId`.
+ */
+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";
+/** Same private prefix family as invoices — refused by the media proxy. */
+export const CREDIT_NOTE_PREFIX_PATH = "private/credit-notes";
+/**
+ * Number and (optionally) render the credit note for one settled refund.
+ *
+ * 🛑 **Best-effort by design, and that is the opposite of the invoice rule.**
+ * It is called from the refund settle path, where the money has ALREADY left
+ * the gateway. Throwing here would turn a successful refund into a failed
+ * action — the buyer has their money, our code reports an error, and an
+ * operator retries a refund that already happened. A missing credit note is a
+ * reporting gap recoverable by a backfill; a double refund is not.
+ *
+ * The invoice path throws for the mirror-image reason: nothing irreversible has
+ * happened yet there, so refusing to proceed is the safe direction.
+ *
+ * `render` is optional — passing none numbers the reversal without producing a
+ * document, which is what the GSTR-1 export actually needs (it reconciles
+ * numbers and amounts, not PDFs). The PDF is for the buyer.
+ */
+export async function issueCreditNoteForRefund(order, refund, render) {
+    if (refund.creditNoteNumber) {
+        return {
+            creditNoteNumber: refund.creditNoteNumber,
+            creditNoteStoragePath: refund.creditNoteStoragePath,
+            issued: false,
+        };
+    }
+    /*
+     * 🛑 Only a refund that actually moved money gets a number. `status`
+     * undefined means "committed" to every reader (rows written before the
+     * two-phase lifecycle existed carry none), so the test admits those and
+     * refuses only an explicit `reserved` or `failed`.
+     */
+    if (refund.status === "reserved" || refund.status === "failed") {
+        return null;
+    }
+    try {
+        const issuedAt = new Date();
+        const allocation = await allocateSeriesNumber({
+            kind: "credit_note",
+            subjectId: `${order.id}_${refund.refundId}`,
+            orderId: order.id,
+            at: issuedAt,
+        });
+        let storagePath;
+        if (render) {
+            storagePath = `${CREDIT_NOTE_PREFIX_PATH}/${order.id}/${randomUUID()}.pdf`;
+            const buffer = await render(order, refund, allocation.number);
+            await getAdminStorage()
+                .bucket()
+                .file(storagePath)
+                .save(buffer, {
+                contentType: "application/pdf",
+                metadata: { cacheControl: "private, no-store" },
+                resumable: false,
+            });
+        }
+        /*
+         * 🛑 Written through the repository's own refund-event mutator, NOT by
+         * read-modify-writing `refunds[]`. That array is appended by a transaction
+         * precisely because a read-then-`[...existing, event]` write LOSES an
+         * event under concurrency (D6), and stamping a credit-note number the
+         * naive way would reintroduce exactly that defect on the same array.
+         */
+        await orderRepository.setRefundCreditNote(order.id, refund.refundId, {
+            creditNoteNumber: allocation.number,
+            creditNoteIssuedAt: issuedAt,
+            ...(storagePath ? { creditNoteStoragePath: storagePath } : {}),
+        });
+        serverLogger.info("[invoicing] credit note issued", {
+            orderId: order.id,
+            refundId: refund.refundId,
+            creditNoteNumber: allocation.number,
+        });
+        return {
+            creditNoteNumber: allocation.number,
+            creditNoteStoragePath: storagePath,
+            issued: allocation.allocated,
+        };
+    }
+    catch (err) {
+        /*
+         * Reported loudly and swallowed — see the 🛑 on this function. A refund
+         * that succeeded must not be reported as failed because its paperwork
+         * could not be numbered.
+         */
+        serverLogger.error("[invoicing] credit note FAILED — refund stands, reporting gap", {
+            orderId: order.id,
+            refundId: refund.refundId,
+            error: normalizeError(err).message,
+        });
+        return null;
+    }
+}

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

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+export interface Gstr1Row {
+    /** `LIR/26-27/0001` or `LIRCN/26-27/0001`. */
+    documentNumber: string;
+    documentType: "invoice" | "credit_note";
+    documentDate: string;
+    orderId: string;
+    /** The buyer's state, which decides CGST+SGST vs IGST. */
+    placeOfSupply: string;
+    gstRate: number;
+    taxableValue: number;
+    cgst: number;
+    sgst: number;
+    igst: number;
+    total: number;
+}
+export interface Gstr1Export {
+    rows: Gstr1Row[];
+    /** Net of credit notes — what the period actually owes. */
+    totals: {
+        taxableValue: number;
+        cgst: number;
+        sgst: number;
+        igst: number;
+        total: number;
+    };
+    /**
+     * Orders in the window that are PAID but carry no invoice number.
+     *
+     * 🛑 Reported, never silently excluded. A paid order missing from a tax
+     * return is the one error this export must not hide, and "the row simply
+     * wasn't there" is indistinguishable from "there was nothing to report" in a
+     * CSV. Root Cause #84's lesson applied to an accounting artefact: a count
+     * that goes quiet is as likely to have stopped looking as to be satisfied.
+     */
+    unnumberedPaidOrders: string[];
+}
+/**
+ * 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 declare function buildGstr1Export(from: Date, to: Date): Promise<Gstr1Export>;
+export declare function gstr1ToCsv(data: Gstr1Export): string;

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");
+}