@mohasinac/appkit 4.61.0 → 4.62.1

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

@@ -0,0 +1,63 @@
+/**
+ * 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 { type InvoiceSeriesKind } from "../../../../features/invoicing/schemas/firestore";
+export interface AllocateSeriesNumberInput {
+    kind: InvoiceSeriesKind;
+    /**
+     * What the number is FOR, and the idempotency key.
+     *
+     * An invoice passes the order id. A credit note passes
+     * `${orderId}_${refundId}`, because an order may have several.
+     */
+    subjectId: string;
+    orderId: string;
+    /** Defaults to now. Injectable so a backfill can issue into a past FY. */
+    at?: Date;
+}
+export interface AllocateSeriesNumberResult {
+    number: string;
+    fy: string;
+    sequence: number;
+    /** True when this call did the allocating; false when it found an existing one. */
+    allocated: boolean;
+}
+/**
+ * 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 declare function allocateSeriesNumber(input: AllocateSeriesNumberInput): Promise<AllocateSeriesNumberResult>;

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;