@crewhaus/tool-ledger 0.7.0

package/dist/lib/db.js

@@ -0,0 +1,326 @@
+/**
+ * The store: one `bun:sqlite` file, opened the way `@crewhaus/durable-state`
+ * opens one, with the whole of a posting inside a single `BEGIN IMMEDIATE`.
+ *
+ * THE INVARIANT THIS FILE EXISTS FOR
+ *
+ * A posting is three writes that are only correct together: the rows, the hash
+ * chain's new head, and the idempotency claim that says this batch has been
+ * seen. Commit them separately and there is a window in which the process can
+ * die leaving a ledger whose chain verifies perfectly and whose duplicate
+ * suppression has forgotten the entry — so the retry posts the same payment a
+ * second time, and every check anybody runs says the books are fine. Invoice
+ * numbering has the same shape from the other side: allocate the number, die
+ * before the document is recorded, and the sequence has a gap, which in most
+ * jurisdictions is not untidiness but a finding.
+ *
+ * So every mutation below happens inside ONE `tx.immediate(...)`. `IMMEDIATE`
+ * takes the write lock at BEGIN rather than at the first write, which is what
+ * makes the read half (is this key claimed? what is the chain head? what is the
+ * next invoice number?) serialize against another writer instead of racing it;
+ * `busy_timeout` is what makes the loser wait rather than fail instantly. Bun's
+ * `db.transaction()` rolls the whole thing back on a throw, so a failure
+ * anywhere in the batch leaves the file exactly as it was — no rows, no claim,
+ * no advanced head, no burnt invoice number.
+ *
+ * Amounts are stored as TEXT holding a bigint's decimal digits. SQLite would
+ * take them as INTEGER, but `bun:sqlite` hands an INTEGER column back as a JS
+ * number, and `SUM()` over one silently becomes a float once it overflows —
+ * both of which lose exactly the pennies this package is for.
+ */
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { LedgerError, byString, canonicalJson, sha256Hex } from "./amount";
+/** Bumped when the on-disk shape changes. A mismatch is refused, never migrated silently. */
+export const SCHEMA_VERSION = 1;
+/** The `prev_hash` of the first entry. Nothing precedes it. */
+export const GENESIS_HASH = "0".repeat(64);
+/** How long a writer waits for another writer's lock before giving up. */
+export const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+/** The five account types, and the side each one increases on. */
+export const ACCOUNT_TYPES = ["asset", "liability", "equity", "income", "expense"];
+/**
+ * Which side an account's balance is normally on.
+ *
+ * This lives with the chart of accounts, never in a query. A P&L that decides
+ * the sign of "revenue" by looking at the account's name is a report that is
+ * wrong the first time somebody calls an account "Revenue refunds".
+ */
+export const NORMAL_BALANCE = Object.freeze({
+    asset: "debit",
+    expense: "debit",
+    liability: "credit",
+    equity: "credit",
+    income: "credit",
+});
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS accounts (
+  code TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL CHECK (type IN ('asset','liability','equity','income','expense'))
+);
+CREATE TABLE IF NOT EXISTS entries (
+  seq           INTEGER PRIMARY KEY,
+  entry_id      TEXT NOT NULL UNIQUE,
+  date          TEXT NOT NULL,
+  memo          TEXT NOT NULL,
+  reference     TEXT NOT NULL,
+  tags          TEXT NOT NULL,
+  source_system TEXT,
+  source_id     TEXT,
+  base_currency TEXT NOT NULL,
+  posted_at     TEXT NOT NULL,
+  prev_hash     TEXT NOT NULL,
+  hash          TEXT NOT NULL
+);
+-- A partial index: the pair is unique WHEN there is a source, and an entry
+-- posted by hand has neither, so a thousand manual entries do not collide on
+-- (NULL, NULL). This is the constraint that actually stops a double post; the
+-- SELECT in the same transaction is the readable half of the same rule.
+CREATE UNIQUE INDEX IF NOT EXISTS entries_source
+  ON entries (source_system, source_id)
+  WHERE source_system IS NOT NULL AND source_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS entries_date ON entries (date);
+CREATE TABLE IF NOT EXISTS lines (
+  entry_seq         INTEGER NOT NULL REFERENCES entries (seq),
+  idx               INTEGER NOT NULL,
+  account           TEXT NOT NULL,
+  debit_minor       TEXT NOT NULL,
+  credit_minor      TEXT NOT NULL,
+  currency          TEXT NOT NULL,
+  exponent          INTEGER NOT NULL,
+  fx_rate           TEXT,
+  base_debit_minor  TEXT NOT NULL,
+  base_credit_minor TEXT NOT NULL,
+  counterparty      TEXT,
+  due_date          TEXT,
+  line_memo         TEXT,
+  PRIMARY KEY (entry_seq, idx)
+);
+CREATE INDEX IF NOT EXISTS lines_account ON lines (account);
+CREATE TABLE IF NOT EXISTS idempotency (
+  key          TEXT PRIMARY KEY,
+  payload_hash TEXT NOT NULL,
+  result       TEXT NOT NULL,
+  claimed_at   TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS sequences (
+  name  TEXT PRIMARY KEY,
+  next  INTEGER NOT NULL,
+  start INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS documents (
+  number          TEXT PRIMARY KEY,
+  kind            TEXT NOT NULL,
+  sequence_name   TEXT NOT NULL,
+  ordinal         INTEGER NOT NULL,
+  issue_date      TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL UNIQUE,
+  payload_hash    TEXT NOT NULL,
+  files           TEXT NOT NULL,
+  created_at      TEXT NOT NULL
+);
+`;
+/**
+ * Open the ledger file.
+ *
+ * `read` opens with SQLite's own read-only flag rather than a promise to
+ * behave: `LedgerQuery` and `LedgerReconcile` are declared read-only tools,
+ * and a declaration the database does not enforce is a comment. It also means
+ * a query against a ledger that does not exist is a refusal naming the path,
+ * not an empty ledger conjured into existence by the act of reading it.
+ */
+export function openDb(realPath, mode, busyTimeoutMs, 
+/**
+ * What to call the file in a message. Every other refusal in this package
+ * names the workspace-relative path, and this one used to name the absolute
+ * one — putting the machine's home directory into a result that goes
+ * straight into a model's context. Defaults to the real path for the
+ * in-memory and direct-library callers, which have no relative form.
+ */
+label = realPath) {
+    if (mode === "read") {
+        // Checked before the open rather than after: SQLite defers the real work,
+        // so a missing file surfaces as a confusing error on the first query
+        // instead of here, where the path can still be named.
+        if (!existsSync(realPath)) {
+            throw new LedgerError(`no ledger at "${label}" — LedgerPost creates one; a read will not, because an empty ledger that answers "balance: 0" is worse than a refusal`);
+        }
+        const db = new Database(realPath, { readonly: true });
+        db.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+        assertSchemaVersion(db);
+        return db;
+    }
+    mkdirSync(dirname(realPath), { recursive: true });
+    const db = new Database(realPath, { create: true });
+    // WAL so a reader is never blocked by the writer, and the busy timeout so a
+    // second writer waits for the lock instead of failing the posting outright.
+    db.run("PRAGMA journal_mode = WAL");
+    db.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+    db.run("PRAGMA foreign_keys = ON");
+    // The DDL runs only when the tables are absent. `CREATE TABLE IF NOT EXISTS`
+    // is a no-op on an existing schema but still wants the write lock, so a
+    // second writer would fail HERE — with a raw SQLITE_BUSY from an open, not
+    // with the sentence `inImmediateTransaction` produces — and the caller would
+    // be told the wrong thing about what went wrong.
+    const built = db
+        .query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'entries'")
+        .get();
+    if (built === null) {
+        db.run(SCHEMA);
+        writeMeta(db, "schemaVersion", String(SCHEMA_VERSION));
+    }
+    else {
+        assertSchemaVersion(db);
+    }
+    return db;
+}
+function assertSchemaVersion(db) {
+    const found = readMeta(db, "schemaVersion");
+    if (found === null) {
+        throw new LedgerError("this file is not a crewhaus ledger (it has no schema version) — refusing to write into a database somebody else owns");
+    }
+    if (found !== String(SCHEMA_VERSION)) {
+        throw new LedgerError(`the ledger was written by schema version ${found} and this build speaks ${SCHEMA_VERSION} — refusing rather than migrating a book of record without being asked`);
+    }
+}
+export function readMeta(db, key) {
+    const row = db.query("SELECT value FROM meta WHERE key = ?").get(key);
+    return row === null ? null : row.value;
+}
+export function writeMeta(db, key, value) {
+    db.run("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = ?", [
+        key,
+        value,
+        value,
+    ]);
+}
+/**
+ * The head is stored, not derived.
+ *
+ * A prefix of a valid hash chain is itself a valid hash chain, so recomputing
+ * the head from the rows cannot tell a complete ledger from one somebody
+ * truncated. The stored head can: `length` disagreeing with the row count is
+ * the only evidence that entries were removed.
+ */
+export function readHead(db) {
+    const hash = readMeta(db, "chainHead") ?? GENESIS_HASH;
+    const length = Number(readMeta(db, "chainLength") ?? "0");
+    return { hash, length };
+}
+/** The bytes one entry's hash is taken over. Order is fixed by canonicalJson. */
+export function entryHash(prevHash, payload) {
+    return sha256Hex(`${prevHash}\n${canonicalJson(payload)}`);
+}
+/**
+ * Walk the chain from the genesis hash and report every break.
+ *
+ * Reports ALL of them rather than the first: "the chain broke at entry 4" and
+ * "the chain broke at entries 4, 900 and 901" are different findings, and the
+ * second one is the one that means somebody edited the file.
+ */
+export function verifyChain(db, payloadOf) {
+    const entries = db.query("SELECT * FROM entries ORDER BY seq ASC").all();
+    const lines = db.query("SELECT * FROM lines ORDER BY entry_seq ASC, idx ASC").all();
+    const byEntry = new Map();
+    for (const line of lines) {
+        const bucket = byEntry.get(line.entry_seq);
+        if (bucket === undefined)
+            byEntry.set(line.entry_seq, [line]);
+        else
+            bucket.push(line);
+    }
+    const problems = [];
+    let prev = GENESIS_HASH;
+    let expectedSeq = 1;
+    for (const entry of entries) {
+        if (entry.seq !== expectedSeq) {
+            problems.push({
+                seq: entry.seq,
+                reason: `sequence jumps from ${expectedSeq - 1} to ${entry.seq}; entries were removed`,
+            });
+            expectedSeq = entry.seq;
+        }
+        if (entry.prev_hash !== prev) {
+            problems.push({
+                seq: entry.seq,
+                reason: `prev_hash ${entry.prev_hash.slice(0, 12)}… does not follow ${prev.slice(0, 12)}…`,
+            });
+        }
+        const recomputed = entryHash(entry.prev_hash, payloadOf(entry, byEntry.get(entry.seq) ?? []));
+        if (recomputed !== entry.hash) {
+            problems.push({
+                seq: entry.seq,
+                reason: `the stored hash does not match the entry's contents — this entry was edited after it was posted`,
+            });
+        }
+        prev = entry.hash;
+        expectedSeq += 1;
+    }
+    const stored = readHead(db);
+    if (stored.hash !== prev) {
+        problems.push({
+            seq: null,
+            reason: `the recorded head ${stored.hash.slice(0, 12)}… is not the last entry's hash ${prev.slice(0, 12)}… — entries were removed from the end`,
+        });
+    }
+    if (stored.length !== entries.length) {
+        problems.push({
+            seq: null,
+            reason: `the ledger records ${stored.length} entries and ${entries.length} are present`,
+        });
+    }
+    return {
+        ok: problems.length === 0,
+        entries: entries.length,
+        head: prev,
+        storedHead: stored.hash,
+        storedLength: stored.length,
+        problems: problems.sort((a, b) => (a.seq ?? 1e9) - (b.seq ?? 1e9) || byString(a.reason, b.reason)),
+    };
+}
+/**
+ * A rollback asked for on purpose.
+ *
+ * `dryRun` runs the real posting — every validation, every insert, the chain
+ * advance, the claim — and then throws this to undo it. Running a separate
+ * "check only" path instead is how a dry run comes back clean and the real
+ * call fails: the two paths drift, and the one nobody exercises is the one
+ * that matters.
+ */
+export class DryRunRollback extends Error {
+    payload;
+    constructor(payload) {
+        super("dry run: rolled back on purpose");
+        this.name = "DryRunRollback";
+        this.payload = payload;
+    }
+}
+/**
+ * Run `work` inside one `BEGIN IMMEDIATE`, and turn SQLite's lock failure into
+ * a sentence that names the cause.
+ *
+ * The distinction matters for a caller deciding whether to retry: "another
+ * writer holds the ledger" is worth retrying and "debits do not equal credits"
+ * never is, and a bare `SQLITE_BUSY` stack trace tells a model neither.
+ */
+export function inImmediateTransaction(db, work) {
+    const tx = db.transaction(work);
+    try {
+        return tx.immediate();
+    }
+    catch (err) {
+        if (err instanceof DryRunRollback)
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        if (/SQLITE_BUSY|database is locked|database table is locked/i.test(message)) {
+            throw new LedgerError(`another writer holds the ledger's write lock and it did not clear within the busy timeout — nothing was posted, the claim was not taken and the chain head did not move; retry the call unchanged (${message})`);
+        }
+        throw err;
+    }
+}

package/dist/lib/invoice.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Invoices: the totals, the logic-less template, and the number.
+ *
+ * THE NUMBER IS THE HARD PART. A legally required document sequence has to be
+ * gap-free and monotonic, and the two obvious orderings both break it:
+ * allocate the number and then write the file, and a crash in between burns a
+ * number forever; write the file and then allocate, and two concurrent calls
+ * write two documents with the same number. What works is neither: allocate
+ * the number AND record the document — its idempotency key, and the hash of
+ * everything that determines its bytes — in one `BEGIN IMMEDIATE`
+ * transaction, then render. If the render dies, the same call repeated with
+ * the same key gets the SAME number back and re-renders the SAME bytes,
+ * because the rendering is a pure function of the recorded payload. Nothing is
+ * burnt and nothing is duplicated. `resetYearly` takes its year from
+ * `issueDate`, never from the clock, or an invoice back-dated across New Year
+ * lands in the wrong sequence.
+ *
+ * THE SECOND HARD PART IS BYTES. `Intl.NumberFormat` output moves with the
+ * ICU version the runtime was built against, so an invoice rendered on a
+ * developer's Mac and on a CI container can differ in the separator between
+ * thousands — on a document somebody files. This package therefore has no
+ * locale formatter at all: amounts are rendered from exact decimal strings
+ * with separators the caller names, and dates are ISO. Nothing here can move
+ * with an ICU upgrade because nothing here asks ICU anything.
+ */
+import type { Database } from "bun:sqlite";
+import { byString, exponentFor } from "./amount";
+export declare const DOCUMENT_KINDS: readonly ["invoice", "receipt", "credit_note", "quote"];
+export type DocumentKind = (typeof DOCUMENT_KINDS)[number];
+export declare const OUTPUT_FORMATS: readonly ["html", "markdown", "json"];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+export declare const INVOICE_LIMITS: {
+    readonly lines: 1000;
+    readonly templateBytes: number;
+};
+export type PartyInput = {
+    readonly name: string;
+    readonly address?: ReadonlyArray<string>;
+    readonly taxId?: string;
+    readonly email?: string;
+    readonly phone?: string;
+};
+export type InvoiceLineInput = {
+    readonly description: string;
+    readonly quantity?: string;
+    readonly unitAmount?: string;
+    readonly unitAmountMinor?: string | number;
+    readonly discount?: string;
+    readonly discountMinor?: string | number;
+    readonly taxRateBps?: number;
+    readonly taxMinor?: string | number;
+};
+export type NumberFormatOptions = {
+    readonly decimalSeparator?: string;
+    readonly groupSeparator?: string;
+};
+/**
+ * Minor units as the document shows them. No `Intl`, on purpose (see above):
+ * the digits come from exact bigint arithmetic and the separators come from
+ * the caller, so the same input renders the same bytes on every machine.
+ */
+export declare function formatAmount(minor: bigint, exponent: number, options?: NumberFormatOptions): string;
+export type ComputedLine = {
+    readonly index: number;
+    readonly description: string;
+    readonly quantity: string;
+    readonly unitAmountMinor: string;
+    readonly netMinor: string;
+    readonly discountMinor: string;
+    readonly taxMinor: string;
+    readonly taxRateBps: number | null;
+    readonly totalMinor: string;
+};
+/**
+ * The four figures a document shows, in the order it shows them and with the
+ * arithmetic a reader will do on them:
+ *
+ *     subtotal − discount + tax = total
+ *
+ * `subtotalMinor` is therefore the sum of the lines BEFORE discount. Making it
+ * the net instead — the sum after discount — leaves every individual figure
+ * defensible and the document as a whole wrong: 90.00 subtotal, 10.00
+ * discount, 18.00 tax and a 108.00 total is a page whose own sum is 98.00, and
+ * the first person to check the arithmetic is the customer being asked to pay
+ * it. `netMinor` is carried alongside for anybody who wants the after-discount
+ * figure without subtracting.
+ */
+export type ComputedTotals = {
+    readonly subtotalMinor: string;
+    readonly discountMinor: string;
+    readonly netMinor: string;
+    readonly taxMinor: string;
+    readonly totalMinor: string;
+};
+/**
+ * Totals are computed, never accepted.
+ *
+ * A total supplied alongside the lines is a second source of truth, and the
+ * one that gets believed is the one a model wrote. Quantities are exact
+ * decimals so "1.5 hours" is not a float, and each line rounds once.
+ *
+ * Tax here is a flat per-line rate, which covers the ordinary case. For
+ * compound rates, exemptions, reverse charge or per-invoice rounding scope,
+ * run `@crewhaus/tool-money`'s `TaxCalculate` and pass the answer in as
+ * `taxMinor` — this refuses both at once rather than guessing which wins.
+ */
+export declare function computeInvoice(lines: ReadonlyArray<InvoiceLineInput>, exponent: number): {
+    lines: ComputedLine[];
+    totals: ComputedTotals;
+};
+export type NumberingConfig = {
+    readonly prefix: string;
+    readonly pad: number;
+    readonly resetYearly: boolean;
+    readonly start: number;
+};
+export type Allocation = {
+    readonly number: string;
+    readonly ordinal: number;
+    readonly sequenceName: string;
+    readonly replayed: boolean;
+    /**
+     * Whether the sequence has issued every number between its start and its
+     * next — or `null` when there is no sequence to check, which is the case for
+     * a number the caller assigned. `null` is not `false` and it is emphatically
+     * not `true`: "I could not check this" has to survive to the caller, because
+     * a gap in a document sequence is a finding in most jurisdictions and a
+     * confident `true` from a check that never ran is how it gets missed.
+     */
+    readonly gapFree: boolean | null;
+    readonly files: ReadonlyArray<string>;
+};
+/** `INV-` + the issue date's year when the sequence resets yearly. */
+export declare function sequenceNameFor(kind: DocumentKind, config: NumberingConfig, issueDate: string): string;
+export declare function numberFor(config: NumberingConfig, issueDate: string, ordinal: number): string;
+/**
+ * A document number is also a FILE NAME, so it is contained like one.
+ *
+ * `outDir` goes through `resolveSafe`, but the leaf does not — the file is
+ * `${number}.${format}` under that directory — and the number is
+ * caller-supplied twice over: directly as `number`, and indirectly through
+ * `numbering.prefix`. Without this check `number: "../../escaped"` writes
+ * outside the workspace root, and because the write finishes with a rename it
+ * silently REPLACES whatever was already there. Containing the directory and
+ * not the leaf contains nothing.
+ *
+ * Called before the sequence is touched, for the reason the rest of this file
+ * is shaped the way it is: a refusal must not cost a number.
+ */
+export declare function assertNumberIsAFileName(number: string, where: string): string;
+/**
+ * Take the next number and record the document, in one transaction.
+ *
+ * The idempotency key is what makes a retry safe. A second call with the same
+ * key and the same payload gets the same number back and posts nothing; a
+ * second call with the same key and a DIFFERENT payload is refused, because
+ * that is somebody re-using a key for a new document and the alternative is
+ * two different invoices claiming one number.
+ */
+export declare function allocateDocument(db: Database, args: {
+    readonly kind: DocumentKind;
+    readonly config: NumberingConfig;
+    readonly issueDate: string;
+    readonly idempotencyKey: string;
+    readonly payloadHash: string;
+    readonly files: ReadonlyArray<string>;
+    readonly createdAt: string;
+}): Allocation;
+/**
+ * Markdown output escapes a pipe, because a pipe ENDS A TABLE CELL.
+ *
+ * A description of "Widget | Deluxe" renders six cells into a five-column
+ * table: the reader sees "Deluxe" as the quantity, the unit amount as the tax,
+ * and — because the last cell is dropped — a Total of 0.00 on a line worth a
+ * hundred. Nothing computes a wrong number; the document simply shows the
+ * wrong one. `renderRows` in ./query escapes the same character for the same
+ * reason, and this is the invoice's copy of that rule.
+ */
+export declare function escapeMarkdown(text: string): string;
+export declare function escapeHtml(text: string): string;
+/**
+ * A logic-less template: variables, array sections, inverted sections. No
+ * partials, no lambdas, no expressions — a template that can compute is a
+ * template that can compute a total, and totals come from `computeInvoice`.
+ *
+ * `strict` (on by default) refuses an unknown path instead of rendering the
+ * empty string. Mustache's silence is the right default for a web page and
+ * the wrong one for an invoice: a mistyped `{{seller.taxId}}` would drop the
+ * VAT number off the document and nothing would say so.
+ *
+ * Only ARRAYS iterate. A plain object never does, because the order it would
+ * iterate in is insertion order, and that is not a property of the document.
+ */
+export declare function renderTemplate(template: string, data: Record<string, unknown>, options: {
+    readonly escape: (text: string) => string;
+    readonly strict: boolean;
+}): string;
+/** Column order in the built-in templates, written out rather than iterated. */
+export declare const LINE_COLUMNS: readonly ["description", "quantity", "unitAmount", "tax", "total"];
+export declare const BUILTIN_TEMPLATES: Readonly<Record<"html" | "markdown", string>>;
+/** The object a template sees, and the `json` output verbatim. */
+export declare function documentModel(args: {
+    readonly kind: DocumentKind;
+    readonly number: string;
+    readonly currency: string;
+    readonly exponent: number;
+    readonly issueDate: string;
+    readonly dueDate?: string;
+    readonly reference?: string;
+    readonly notes?: string;
+    readonly paymentInstructions?: string;
+    readonly seller: PartyInput;
+    readonly buyer: PartyInput;
+    readonly computed: {
+        lines: ComputedLine[];
+        totals: ComputedTotals;
+    };
+    readonly numberFormat: NumberFormatOptions;
+}): Record<string, unknown>;
+/** Validate the dates an invoice carries, in one place. */
+export declare function validateInvoiceDates(issueDate: string, dueDate?: string): void;
+export { byString, exponentFor };