@book.dev/sdk 3.5.0 → 3.6.0

package/dist/ledgerCsv.js

@@ -0,0 +1,197 @@
+/**
+ * Canonical postings CSV (LGR-7): the ledger's insurance export.
+ *
+ * A book must always be able to LEAVE the app in a canonical, tool-agnostic
+ * form. This module is a PURE function from ledger entities to CSV bytes —
+ * no I/O, no clock, no locale — with the hard guarantee that the SAME DATA
+ * always produces IDENTICAL BYTES:
+ *
+ *  - one row per posting, long form (a transaction with N postings emits N rows);
+ *  - deterministic ordering: transactions by (entry_no ascending, drafts —
+ *    which have no entry number — after all numbered entries by createdAt then
+ *    id), postings in creation order within their transaction;
+ *  - RFC-4180 quoting (fields containing `"` `,` CR or LF are quoted, inner
+ *    quotes doubled), LF line endings, UTF-8 with NO BOM, trailing newline;
+ *  - amounts appear twice: `amount_minor` (the raw signed integer of minor
+ *    units — the authoritative value) and `amount_formatted` (the locale-pinned
+ *    {@link formatAmount} display string, e.g. `$1,234.56`);
+ *  - output depends only on FIELD VALUES, never on object key order.
+ */
+import { formatAmount } from './money';
+/**
+ * The canonical column set, in order.
+ *
+ * | column            | content                                                            |
+ * |-------------------|--------------------------------------------------------------------|
+ * | entry_no          | server-assigned monotonic entry number; empty for drafts           |
+ * | transaction_id    | transaction row id (UUID)                                          |
+ * | date              | transaction ISO date (`YYYY-MM-DD`)                                |
+ * | description       | transaction description (free text — see the apostrophe note)      |
+ * | state             | `draft` / `posted` / `void`                                        |
+ * | posting_id        | posting row id (UUID)                                              |
+ * | account_name      | hierarchical account name (`Assets:Bank:Checking`)                 |
+ * | account_type      | `asset` / `liability` / `equity` / `revenue` / `expense`           |
+ * | amount_minor      | signed integer minor units (authoritative; ALWAYS verbatim)        |
+ * | amount_formatted  | {@link formatAmount} display string; EMPTY if the amount is corrupt |
+ * | currency          | the account's ISO-4217-shaped code                                 |
+ * | cleared           | `pending` / `cleared` / `reconciled`                               |
+ * | reconciliation_id | reconciliation row id, empty when none                             |
+ * | reverses          | id of the transaction this entry reverses, empty when none         |
+ * | posted_at         | ISO timestamp stamped at post time, empty for drafts               |
+ * | posted_by         | principal subject that posted, empty for drafts                    |
+ * | evidence_sha256s  | semicolon-joined SHA-256 hashes of attached evidence               |
+ * | memo              | the POSTING's own free-text note (LGR-16); empty when none        |
+ *
+ * **Adding a column.** `memo` was APPENDED (LGR-16), never inserted: this list
+ * is a documented contract, and a consumer that reads columns POSITIONALLY —
+ * the spreadsheet formula somebody wrote against `I2`, the awk one-liner in a
+ * runbook — keeps working across the change iff existing columns do not move.
+ * Every future column belongs at the end for the same reason.
+ *
+ * **Free-text columns and the leading apostrophe.** `description`, `memo`,
+ * `account_name` and `posted_by` carry text a ledger writer authored, so a
+ * value that would open as a spreadsheet FORMULA (leading `=` `+` `-` `@`, tab
+ * or CR) is emitted with a single leading apostrophe — the universal
+ * "treat this as text" marker. A value that ALREADY begins with `'` is prefixed
+ * too, which is what makes the escape INJECTIVE: a RE-IMPORTER strips ONE
+ * leading `'` from exactly these four columns and recovers the original value
+ * exactly, whether it was a formula lead-in or a genuine apostrophe. No other
+ * column is ever prefixed (notably `amount_minor`, whose negatives legitimately
+ * start with `-`), so machine columns round-trip byte-exactly.
+ */
+export const LEDGER_CSV_COLUMNS = [
+    'entry_no',
+    'transaction_id',
+    'date',
+    'description',
+    'state',
+    'posting_id',
+    'account_name',
+    'account_type',
+    'amount_minor',
+    'amount_formatted',
+    'currency',
+    'cleared',
+    'reconciliation_id',
+    'reverses',
+    'posted_at',
+    'posted_by',
+    'evidence_sha256s',
+    'memo',
+];
+/**
+ * The FREE-TEXT columns — the ones whose content a ledger writer authors. Only
+ * these get spreadsheet-formula neutralization ({@link csvText}); the machine
+ * columns (ids, enums, dates, and above all `amount_minor`) are emitted
+ * verbatim so the file stays exactly parseable as data.
+ */
+const TEXT_COLUMNS = new Set(['description', 'memo', 'account_name', 'posted_by']);
+/**
+ * Leading characters a spreadsheet treats as the start of a FORMULA rather than
+ * text (`=SUM(...)`, `+`, `-`, `@`, and the tab/CR lead-ins some parsers strip
+ * before dispatching). See {@link csvText}.
+ */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+/** RFC-4180: quote a field iff it contains a quote, comma, CR, or LF; double inner quotes. */
+function csvField(value) {
+    return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+/**
+ * A free-text field, neutralized against CSV formula injection: a value that
+ * would otherwise open as a spreadsheet FORMULA is prefixed with a single
+ * apostrophe (the universal "treat as text" marker) before RFC-4180 quoting.
+ * Scoped deliberately to {@link TEXT_COLUMNS} — a blanket prefix would corrupt
+ * `amount_minor` (every negative amount starts with `-`) and break the
+ * byte-canonical contract for machine columns.
+ */
+function csvText(value) {
+    // Prefix a value that ALREADY starts with `'` too, so the escape stays
+    // INJECTIVE: without it `=SUM(1)` and `'=SUM(1)` would both emit `'=SUM(1)`,
+    // and the documented "strip ONE leading apostrophe" re-import rule would
+    // silently corrupt every value that legitimately begins with an apostrophe.
+    const needsPrefix = FORMULA_LEAD.test(value) || value.startsWith('\'');
+    return csvField(needsPrefix ? `'${value}` : value);
+}
+/**
+ * The display amount, or `''` when the stored amount is too corrupt to format.
+ *
+ * The insurance export must NEVER throw on the very corruption it exists to
+ * survive: a raw-mutated `amount_minor` (a float, a string, an unsafe integer)
+ * makes `formatAmount` reject, which would fail the whole export at the exact
+ * moment the book most needs to leave the building. The raw `amount_minor`
+ * column still carries the stored value verbatim, and the verifier reports the
+ * corruption as `invalid-amount`.
+ */
+function money(minor, currency) {
+    try {
+        return currency === undefined ? formatAmount(minor) : formatAmount(minor, { currency });
+    }
+    catch {
+        return '';
+    }
+}
+/** Locale-independent, byte-deterministic string compare (never `localeCompare`). */
+function byteCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Build the canonical postings CSV from the full account list and the full
+ * transaction list (with postings). Pure and deterministic — see module doc.
+ *
+ * Ordering: numbered entries (posted/void) ascend by `entryNo`; drafts (no
+ * entry number) follow, ordered by (`createdAt`, `id`). Postings keep the
+ * creation order their transaction carries. A posting whose account does not
+ * resolve (should never happen — the verifier flags it) emits empty
+ * account_name/account_type/currency and a currency-less formatted amount
+ * rather than throwing, and an unformattable (raw-corrupted) amount emits an
+ * empty `amount_formatted` while `amount_minor` keeps the stored value
+ * verbatim — the insurance export always leaves the building.
+ */
+export function buildLedgerPostingsCsv(accounts, transactions) {
+    const accountById = new Map();
+    for (const account of accounts)
+        accountById.set(account.id, account);
+    const ordered = [...transactions].sort((a, b) => {
+        const an = a.entryNo ?? Number.POSITIVE_INFINITY;
+        const bn = b.entryNo ?? Number.POSITIVE_INFINITY;
+        if (an !== bn)
+            return an < bn ? -1 : 1;
+        return byteCompare(a.createdAt, b.createdAt) || byteCompare(a.id, b.id);
+    });
+    const lines = [LEDGER_CSV_COLUMNS.join(',')];
+    for (const tx of ordered) {
+        // Defensive per ELEMENT, not just per array: raw storage can hold a null
+        // (or otherwise shapeless) evidence entry, and the insurance export must
+        // never throw on the corruption it exists to survive.
+        const evidence = tx.evidence.map((e) => String(e?.sha256 ?? '')).join(';');
+        for (const posting of tx.postings) {
+            const account = accountById.get(posting.accountId);
+            const fields = [
+                tx.entryNo == null ? '' : String(tx.entryNo),
+                tx.id,
+                tx.date,
+                tx.description,
+                tx.state,
+                posting.id,
+                account?.name ?? '',
+                account?.type ?? '',
+                String(posting.amountMinor),
+                money(posting.amountMinor, account?.currency),
+                account?.currency ?? '',
+                posting.cleared,
+                posting.reconciliationId ?? '',
+                tx.reverses ?? '',
+                tx.postedAt ?? '',
+                tx.postedBy ?? '',
+                evidence,
+                // Defensive `?? ''`, not just for `null`: a raw-mutated row can hold a
+                // non-string here, and the insurance export must emit SOMETHING rather
+                // than `undefined` or a throw.
+                typeof posting.memo === 'string' ? posting.memo : '',
+            ];
+            lines.push(fields.map((value, i) => (TEXT_COLUMNS.has(LEDGER_CSV_COLUMNS[i]) ? csvText(value) : csvField(value))).join(','));
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=ledgerCsv.js.map

package/dist/ledgerCsv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledgerCsv.js","sourceRoot":"","sources":["../src/ledgerCsv.ts"],"names":[],"mappings":"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"}

package/dist/money.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Money core (LGR-2): signed integer minor-unit amounts for the ledger.
+ *
+ * INVARIANT — amounts are SIGNED INTEGER MINOR UNITS (cents) everywhere:
+ * storage, arithmetic, wire, and the boundaries of this API. No floats ever
+ * cross this API: every function throws a typed {@link MoneyError} subclass on
+ * non-integer or out-of-range numbers instead of rounding, truncating, or
+ * returning `NaN`.
+ *
+ * Bounds: amounts must satisfy `Number.isSafeInteger`, i.e. lie within
+ * ±(2^53 − 1) minor units (`±9,007,199,254,740,991` ≈ ±$90 trillion at 2
+ * decimal places). Anything beyond is rejected with {@link MoneyRangeError}.
+ * Internally, parsing and formatting route digit math through `BigInt` so the
+ * bound check itself is exact.
+ *
+ * Scale (v1): a fixed 2-decimal minor-unit scale (1 major unit = 100 minor
+ * units) for ALL currencies. Zero-decimal currencies (JPY-style) are
+ * v1-unsupported as a scale: `formatAmount(minor, {currency: 'JPY'})` still
+ * renders `minor / 100` with 2 decimals. Per-currency exponents are a later
+ * ledger task.
+ */
+/** Discriminant for {@link MoneyError} subclasses. */
+export type MoneyErrorCode = 'parse' | 'range' | 'currency';
+/**
+ * Base class for all money errors. Callers can `instanceof`-match the
+ * subclasses ({@link MoneyParseError}, {@link MoneyRangeError},
+ * {@link MoneyCurrencyError}) or switch on {@link MoneyError.code}.
+ */
+export declare class MoneyError extends Error {
+    /** Machine-readable error category. */
+    readonly code: MoneyErrorCode;
+    constructor(code: MoneyErrorCode, message: string);
+}
+/** Input text could not be parsed as a money amount (malformed, ambiguous, empty…). */
+export declare class MoneyParseError extends MoneyError {
+    constructor(message: string);
+}
+/**
+ * A numeric amount is not an integer or exceeds the safe bound of
+ * ±(2^53 − 1) minor units (non-integer input, unsafe magnitude, or overflow
+ * during arithmetic).
+ */
+export declare class MoneyRangeError extends MoneyError {
+    constructor(message: string);
+}
+/** A currency code is malformed, or amounts mix currencies where one is required. */
+export declare class MoneyCurrencyError extends MoneyError {
+    constructor(message: string);
+}
+/** Largest representable amount: 2^53 − 1 minor units (≈ $90,071,992,547,409.91). */
+export declare const MAX_AMOUNT_MINOR: number;
+/** Smallest representable amount: −(2^53 − 1) minor units. */
+export declare const MIN_AMOUNT_MINOR: number;
+/**
+ * True iff `n` is a valid minor-unit amount: a `number` that is a safe integer
+ * (`Number.isSafeInteger`), i.e. within ±(2^53 − 1). Narrowing type guard.
+ */
+export declare function isValidMinor(n: unknown): n is number;
+/** Options for {@link parseAmount}. */
+export interface ParseAmountOptions {
+    /** Accept accounting-style parentheses for negatives, e.g. `(12.30)`. Default `true`. */
+    allowParens?: boolean;
+    /** Accept a leading currency symbol (`$ € £ ¥ ₹`), e.g. `$1,234.56`. Default `true`. */
+    allowCurrencySymbol?: boolean;
+    /**
+     * What DECIMAL-POINT-FREE input means (`"1234"`, `"+1,000"`, `"0"`):
+     *
+     * - `'major'` (default, and the historical behaviour): whole MAJOR units —
+     *   `"1234"` → `123400`.
+     * - `'reject'`: throw {@link MoneyParseError}. For MACHINE input whose scale
+     *   is not established by the data itself.
+     *
+     * WHY THIS EXISTS. For a human typing into a form, "1234" unambiguously means
+     * 1234 dollars, and `'major'` is right. For a BANK or PROCESSOR export it is
+     * not: Stripe-style feeds denominate in MINOR units ("amount in cents"), where
+     * the same bare integer means 1/100th as much. Defaulting silently in that
+     * context is the single worst failure this module exists to prevent — a
+     * 100× import error that balances perfectly and looks plausible. So an
+     * importer must DECIDE (from profile detection, or by asking) and pass an
+     * explicit value; `'reject'` is how it makes an unestablished scale fail
+     * LOUDLY at the parse instead of quietly at the wrong magnitude.
+     *
+     * `'reject'` keys off the DECIMAL POINT, not the value: `".5"` and `"12.30"`
+     * pass, `"0"` and `"1,000"` do not.
+     */
+    bareDigits?: 'major' | 'reject';
+}
+/**
+ * Parse human-typed money input into signed integer minor units (cents).
+ *
+ * Rules:
+ * - Input is in MAJOR units; input without a decimal point is whole major
+ *   units: `"1234"` → `123400`, `"1,234.56"` → `123456`, `".5"` → `50`.
+ *   Machine input whose scale is not established by the data can opt out of
+ *   that assumption with `bareDigits: 'reject'` (see
+ *   {@link ParseAmountOptions.bareDigits}) — the default is unchanged.
+ * - Negatives: leading sign (`"-12.30"`) or accounting parentheses
+ *   (`"(12.30)"`) → `-1230`. Combining both is rejected as ambiguous.
+ * - A single leading currency symbol (`$ € £ ¥ ₹`) is tolerated, before or
+ *   after the sign: `"$-1,234.56"` and `"-$1,234.56"` both → `-123456`.
+ * - Thousands grouping uses commas in strict 3-digit groups; the decimal
+ *   separator is `.` with at most 2 digits. (Locale-specific separators —
+ *   `1.234,56`, space grouping — are v1-unsupported and rejected.)
+ *
+ * Rejections (typed errors, never `NaN`):
+ * - {@link MoneyParseError}: empty/sign-only input, non-numeric text, more
+ *   than 2 decimals, ambiguous or misplaced separators (`"1,23.45"`),
+ *   trailing dot (`"12."`), unbalanced parentheses, conflicting signs, and —
+ *   under `bareDigits: 'reject'` — any input with no decimal point.
+ * - {@link MoneyRangeError}: magnitude beyond ±(2^53 − 1) minor units.
+ *
+ * @param input Human-typed amount text.
+ * @param opts See {@link ParseAmountOptions}.
+ * @returns The amount in signed integer minor units.
+ */
+export declare function parseAmount(input: string, opts?: ParseAmountOptions): number;
+/** Options for {@link formatAmount}. */
+export interface FormatAmountOptions {
+    /**
+     * ISO-4217-shaped currency code (3 uppercase letters). Known codes
+     * (USD, EUR, GBP, JPY, INR) render their symbol as a prefix
+     * (`$1,234.56`); other valid codes render as a code prefix
+     * (`CAD 1,234.56`). Invalid codes throw {@link MoneyCurrencyError}.
+     */
+    currency?: string;
+    /** Negative style: `'sign'` → `-1,234.56` (default); `'parens'` → `(1,234.56)`. */
+    negative?: 'sign' | 'parens';
+}
+/**
+ * Format signed integer minor units for display: fixed 2 decimals, comma
+ * thousands grouping, locale-pinned (the output is built from digits — it
+ * never consults the host locale, so it is byte-identical across
+ * machines/runs). `123456` → `"1,234.56"`.
+ *
+ * Negative zero normalises to positive `"0.00"`. Round-trips through
+ * {@link parseAmount} exactly for every valid amount (including `'parens'`
+ * style and symbol-prefixed currencies).
+ *
+ * Zero-decimal currencies (JPY-style) are v1-unsupported as a scale: the
+ * amount still renders as `minor / 100` with 2 decimals (see module doc).
+ *
+ * @param minor Amount in signed integer minor units; invalid amounts throw {@link MoneyRangeError}.
+ * @param opts See {@link FormatAmountOptions}.
+ */
+export declare function formatAmount(minor: number, opts?: FormatAmountOptions): string;
+/**
+ * Add minor-unit amounts exactly. Every input and the running sum must be a
+ * safe integer; otherwise {@link MoneyRangeError} is thrown (no silent float
+ * drift, no wrap-around). `addAmounts()` → `0`.
+ */
+export declare function addAmounts(...amounts: number[]): number;
+/**
+ * Sum an iterable of minor-unit amounts exactly. Each value is validated with
+ * {@link isValidMinor}, and the running sum is re-validated after every step
+ * so overflow past ±(2^53 − 1) throws {@link MoneyRangeError} instead of
+ * losing precision. An empty iterable sums to `0`.
+ */
+export declare function sumAmounts(amounts: Iterable<number>): number;
+/** Negate a minor-unit amount (`negateAmount(0)` stays `0`, never `-0`). Throws {@link MoneyRangeError} on invalid input. */
+export declare function negateAmount(minor: number): number;
+/**
+ * Three-way comparison of minor-unit amounts: `-1` if `a < b`, `0` if equal,
+ * `1` if `a > b`. Suitable as an `Array.prototype.sort` comparator. Throws
+ * {@link MoneyRangeError} on invalid inputs.
+ */
+export declare function compareAmounts(a: number, b: number): -1 | 0 | 1;
+/**
+ * True iff `code` is ISO-4217-shaped: exactly 3 uppercase ASCII letters
+ * (`USD`, `EUR`…). Shape-only — this does not check the code against the
+ * live ISO registry. Narrowing type guard.
+ */
+export declare function isValidCurrencyCode(code: unknown): code is string;
+/**
+ * Assert every code in `codes` is valid ({@link isValidCurrencyCode}) and
+ * identical — ledger entries must not silently mix currencies. Returns the
+ * uniform code, or `undefined` for an empty iterable. Throws
+ * {@link MoneyCurrencyError} on an invalid code or a mix.
+ */
+export declare function assertUniformCurrency(codes: Iterable<string>): string | undefined;

package/dist/money.js

@@ -0,0 +1,283 @@
+/**
+ * Money core (LGR-2): signed integer minor-unit amounts for the ledger.
+ *
+ * INVARIANT — amounts are SIGNED INTEGER MINOR UNITS (cents) everywhere:
+ * storage, arithmetic, wire, and the boundaries of this API. No floats ever
+ * cross this API: every function throws a typed {@link MoneyError} subclass on
+ * non-integer or out-of-range numbers instead of rounding, truncating, or
+ * returning `NaN`.
+ *
+ * Bounds: amounts must satisfy `Number.isSafeInteger`, i.e. lie within
+ * ±(2^53 − 1) minor units (`±9,007,199,254,740,991` ≈ ±$90 trillion at 2
+ * decimal places). Anything beyond is rejected with {@link MoneyRangeError}.
+ * Internally, parsing and formatting route digit math through `BigInt` so the
+ * bound check itself is exact.
+ *
+ * Scale (v1): a fixed 2-decimal minor-unit scale (1 major unit = 100 minor
+ * units) for ALL currencies. Zero-decimal currencies (JPY-style) are
+ * v1-unsupported as a scale: `formatAmount(minor, {currency: 'JPY'})` still
+ * renders `minor / 100` with 2 decimals. Per-currency exponents are a later
+ * ledger task.
+ */
+/**
+ * Base class for all money errors. Callers can `instanceof`-match the
+ * subclasses ({@link MoneyParseError}, {@link MoneyRangeError},
+ * {@link MoneyCurrencyError}) or switch on {@link MoneyError.code}.
+ */
+export class MoneyError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+/** Input text could not be parsed as a money amount (malformed, ambiguous, empty…). */
+export class MoneyParseError extends MoneyError {
+    constructor(message) {
+        super('parse', message);
+    }
+}
+/**
+ * A numeric amount is not an integer or exceeds the safe bound of
+ * ±(2^53 − 1) minor units (non-integer input, unsafe magnitude, or overflow
+ * during arithmetic).
+ */
+export class MoneyRangeError extends MoneyError {
+    constructor(message) {
+        super('range', message);
+    }
+}
+/** A currency code is malformed, or amounts mix currencies where one is required. */
+export class MoneyCurrencyError extends MoneyError {
+    constructor(message) {
+        super('currency', message);
+    }
+}
+/** Largest representable amount: 2^53 − 1 minor units (≈ $90,071,992,547,409.91). */
+export const MAX_AMOUNT_MINOR = Number.MAX_SAFE_INTEGER;
+/** Smallest representable amount: −(2^53 − 1) minor units. */
+export const MIN_AMOUNT_MINOR = -Number.MAX_SAFE_INTEGER;
+const MAX_MINOR_BIG = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * True iff `n` is a valid minor-unit amount: a `number` that is a safe integer
+ * (`Number.isSafeInteger`), i.e. within ±(2^53 − 1). Narrowing type guard.
+ */
+export function isValidMinor(n) {
+    return typeof n === 'number' && Number.isSafeInteger(n);
+}
+/** Throw {@link MoneyRangeError} unless `n` is a valid minor-unit amount. */
+function assertMinor(n, context) {
+    if (!isValidMinor(n)) {
+        throw new MoneyRangeError(`${context}: amount must be a safe integer of minor units, got ${String(n)}`);
+    }
+}
+const CURRENCY_SYMBOLS = new Set(['$', '€', '£', '¥', '₹']);
+// Digits of a human-typed amount, after sign/symbol/paren stripping:
+// either comma-grouped thousands (strict 3-digit groups) or plain digits,
+// with an optional dot and exactly 1–2 fraction digits. The integer part may
+// be empty only when a fraction is present (".5"). Anything else — >2
+// decimals, misplaced separators ("1,23.45"), trailing dot, stray text —
+// fails to match and is rejected.
+const AMOUNT_DIGITS_RE = /^(\d{1,3}(?:,\d{3})+|\d*)(?:\.(\d{1,2}))?$/;
+/**
+ * Parse human-typed money input into signed integer minor units (cents).
+ *
+ * Rules:
+ * - Input is in MAJOR units; input without a decimal point is whole major
+ *   units: `"1234"` → `123400`, `"1,234.56"` → `123456`, `".5"` → `50`.
+ *   Machine input whose scale is not established by the data can opt out of
+ *   that assumption with `bareDigits: 'reject'` (see
+ *   {@link ParseAmountOptions.bareDigits}) — the default is unchanged.
+ * - Negatives: leading sign (`"-12.30"`) or accounting parentheses
+ *   (`"(12.30)"`) → `-1230`. Combining both is rejected as ambiguous.
+ * - A single leading currency symbol (`$ € £ ¥ ₹`) is tolerated, before or
+ *   after the sign: `"$-1,234.56"` and `"-$1,234.56"` both → `-123456`.
+ * - Thousands grouping uses commas in strict 3-digit groups; the decimal
+ *   separator is `.` with at most 2 digits. (Locale-specific separators —
+ *   `1.234,56`, space grouping — are v1-unsupported and rejected.)
+ *
+ * Rejections (typed errors, never `NaN`):
+ * - {@link MoneyParseError}: empty/sign-only input, non-numeric text, more
+ *   than 2 decimals, ambiguous or misplaced separators (`"1,23.45"`),
+ *   trailing dot (`"12."`), unbalanced parentheses, conflicting signs, and —
+ *   under `bareDigits: 'reject'` — any input with no decimal point.
+ * - {@link MoneyRangeError}: magnitude beyond ±(2^53 − 1) minor units.
+ *
+ * @param input Human-typed amount text.
+ * @param opts See {@link ParseAmountOptions}.
+ * @returns The amount in signed integer minor units.
+ */
+export function parseAmount(input, opts) {
+    const allowParens = opts?.allowParens ?? true;
+    const allowSymbol = opts?.allowCurrencySymbol ?? true;
+    if (typeof input !== 'string')
+        throw new MoneyParseError('amount must be a string');
+    let s = input.trim();
+    if (s === '')
+        throw new MoneyParseError('empty amount');
+    let parenNegative = false;
+    if (s.startsWith('(') || s.endsWith(')')) {
+        if (!allowParens)
+            throw new MoneyParseError(`parentheses not allowed: ${JSON.stringify(input)}`);
+        if (!s.startsWith('(') || !s.endsWith(')')) {
+            throw new MoneyParseError(`unbalanced parentheses: ${JSON.stringify(input)}`);
+        }
+        parenNegative = true;
+        s = s.slice(1, -1).trim();
+    }
+    // Optional sign and currency symbol, in either order, then the digits.
+    let sign = '';
+    const takeSign = () => {
+        if (s.startsWith('-') || s.startsWith('+')) {
+            if (sign !== '')
+                throw new MoneyParseError(`conflicting signs: ${JSON.stringify(input)}`);
+            sign = s[0];
+            s = s.slice(1).trimStart();
+        }
+    };
+    takeSign();
+    if (s.length > 0 && CURRENCY_SYMBOLS.has(s[0])) {
+        if (!allowSymbol)
+            throw new MoneyParseError(`currency symbol not allowed: ${JSON.stringify(input)}`);
+        s = s.slice(1).trimStart();
+    }
+    takeSign();
+    if (parenNegative && sign !== '') {
+        throw new MoneyParseError(`ambiguous negative (both sign and parentheses): ${JSON.stringify(input)}`);
+    }
+    const m = AMOUNT_DIGITS_RE.exec(s);
+    if (m === null)
+        throw new MoneyParseError(`unparseable amount: ${JSON.stringify(input)}`);
+    const intDigits = m[1].replace(/,/g, '');
+    const fracDigits = m[2] ?? '';
+    if (intDigits === '' && fracDigits === '') {
+        throw new MoneyParseError(`no digits in amount: ${JSON.stringify(input)}`);
+    }
+    // A caller that has NOT established the scale of bare digits refuses them
+    // outright rather than inheriting the major-units default. The test is
+    // structural — group 2 is absent exactly when the input carried no `.` — so
+    // it does not depend on the value, the sign, or any separator.
+    if (opts?.bareDigits === 'reject' && m[2] === undefined) {
+        throw new MoneyParseError(`amount has no decimal point and its scale is not established — major or minor units is ambiguous: ${JSON.stringify(input)}`);
+    }
+    // Exact digit math via BigInt so the safe-integer bound check cannot drift.
+    const magnitude = BigInt(intDigits === '' ? '0' : intDigits) * 100n + BigInt(fracDigits.padEnd(2, '0') || '0');
+    if (magnitude > MAX_MINOR_BIG) {
+        throw new MoneyRangeError(`amount exceeds ±(2^53 − 1) minor units: ${JSON.stringify(input)}`);
+    }
+    const minor = Number(magnitude);
+    return parenNegative || sign === '-' ? (minor === 0 ? 0 : -minor) : minor;
+}
+const CURRENCY_SYMBOL_BY_CODE = {
+    USD: '$',
+    EUR: '€',
+    GBP: '£',
+    JPY: '¥',
+    INR: '₹',
+};
+/**
+ * Format signed integer minor units for display: fixed 2 decimals, comma
+ * thousands grouping, locale-pinned (the output is built from digits — it
+ * never consults the host locale, so it is byte-identical across
+ * machines/runs). `123456` → `"1,234.56"`.
+ *
+ * Negative zero normalises to positive `"0.00"`. Round-trips through
+ * {@link parseAmount} exactly for every valid amount (including `'parens'`
+ * style and symbol-prefixed currencies).
+ *
+ * Zero-decimal currencies (JPY-style) are v1-unsupported as a scale: the
+ * amount still renders as `minor / 100` with 2 decimals (see module doc).
+ *
+ * @param minor Amount in signed integer minor units; invalid amounts throw {@link MoneyRangeError}.
+ * @param opts See {@link FormatAmountOptions}.
+ */
+export function formatAmount(minor, opts) {
+    assertMinor(minor, 'formatAmount');
+    const currency = opts?.currency;
+    if (currency !== undefined && !isValidCurrencyCode(currency)) {
+        throw new MoneyCurrencyError(`invalid currency code: ${JSON.stringify(currency)}`);
+    }
+    // Exact split into whole/fraction via BigInt (float division of large
+    // magnitudes is inexact; digit math is not).
+    const big = BigInt(minor);
+    const negative = big < 0n;
+    const abs = negative ? -big : big;
+    const whole = (abs / 100n).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    const frac = (abs % 100n).toString().padStart(2, '0');
+    const digits = `${whole}.${frac}`;
+    const symbol = currency !== undefined ? CURRENCY_SYMBOL_BY_CODE[currency] : undefined;
+    const codePrefix = currency !== undefined && symbol === undefined ? `${currency} ` : '';
+    const body = `${symbol ?? ''}${digits}`;
+    if (!negative)
+        return `${codePrefix}${body}`;
+    return opts?.negative === 'parens' ? `${codePrefix}(${body})` : `${codePrefix}-${body}`;
+}
+/**
+ * Add minor-unit amounts exactly. Every input and the running sum must be a
+ * safe integer; otherwise {@link MoneyRangeError} is thrown (no silent float
+ * drift, no wrap-around). `addAmounts()` → `0`.
+ */
+export function addAmounts(...amounts) {
+    return sumAmounts(amounts);
+}
+/**
+ * Sum an iterable of minor-unit amounts exactly. Each value is validated with
+ * {@link isValidMinor}, and the running sum is re-validated after every step
+ * so overflow past ±(2^53 − 1) throws {@link MoneyRangeError} instead of
+ * losing precision. An empty iterable sums to `0`.
+ */
+export function sumAmounts(amounts) {
+    let sum = 0;
+    for (const amount of amounts) {
+        assertMinor(amount, 'sumAmounts');
+        sum += amount;
+        if (!Number.isSafeInteger(sum)) {
+            throw new MoneyRangeError('sumAmounts: sum exceeds ±(2^53 − 1) minor units');
+        }
+    }
+    return sum;
+}
+/** Negate a minor-unit amount (`negateAmount(0)` stays `0`, never `-0`). Throws {@link MoneyRangeError} on invalid input. */
+export function negateAmount(minor) {
+    assertMinor(minor, 'negateAmount');
+    return minor === 0 ? 0 : -minor;
+}
+/**
+ * Three-way comparison of minor-unit amounts: `-1` if `a < b`, `0` if equal,
+ * `1` if `a > b`. Suitable as an `Array.prototype.sort` comparator. Throws
+ * {@link MoneyRangeError} on invalid inputs.
+ */
+export function compareAmounts(a, b) {
+    assertMinor(a, 'compareAmounts');
+    assertMinor(b, 'compareAmounts');
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * True iff `code` is ISO-4217-shaped: exactly 3 uppercase ASCII letters
+ * (`USD`, `EUR`…). Shape-only — this does not check the code against the
+ * live ISO registry. Narrowing type guard.
+ */
+export function isValidCurrencyCode(code) {
+    return typeof code === 'string' && /^[A-Z]{3}$/.test(code);
+}
+/**
+ * Assert every code in `codes` is valid ({@link isValidCurrencyCode}) and
+ * identical — ledger entries must not silently mix currencies. Returns the
+ * uniform code, or `undefined` for an empty iterable. Throws
+ * {@link MoneyCurrencyError} on an invalid code or a mix.
+ */
+export function assertUniformCurrency(codes) {
+    let uniform;
+    for (const code of codes) {
+        if (!isValidCurrencyCode(code)) {
+            throw new MoneyCurrencyError(`invalid currency code: ${JSON.stringify(code)}`);
+        }
+        if (uniform === undefined)
+            uniform = code;
+        else if (code !== uniform) {
+            throw new MoneyCurrencyError(`mixed currencies: ${uniform} vs ${code}`);
+        }
+    }
+    return uniform;
+}
+//# sourceMappingURL=money.js.map