@crewhaus/tool-money 0.7.0

package/dist/lib/identifiers.js

@@ -0,0 +1,303 @@
+/**
+ * Payment identifier validation.
+ *
+ * Every one of these carries a checksum precisely so a typo is caught before
+ * money moves, and every one of them is arithmetic — there is nothing for a
+ * model to judge. Getting it wrong is expensive in a way that most wrong
+ * answers are not, so each algorithm here is the published one and the tests
+ * use published vectors.
+ *
+ * A valid checksum means the identifier is well-formed. It does not mean the
+ * account exists, is open, or belongs to who you think. Nothing here reaches
+ * a network, and the result says as much.
+ */
+export const IDENTIFIER_KINDS = ["iban", "bic", "aba", "card", "sortcode"];
+/**
+ * IBAN length by country. The length is part of the standard, so a string
+ * that passes mod-97 at the wrong length is still not an IBAN — and mod-97
+ * alone accepts plenty of those.
+ */
+const IBAN_LENGTHS = new Map(Object.entries({
+    AD: 24,
+    AE: 23,
+    AL: 28,
+    AT: 20,
+    AZ: 28,
+    BA: 20,
+    BE: 16,
+    BG: 22,
+    BH: 22,
+    BR: 29,
+    BY: 28,
+    CH: 21,
+    CR: 22,
+    CY: 28,
+    CZ: 24,
+    DE: 22,
+    DK: 18,
+    DO: 28,
+    EE: 20,
+    EG: 29,
+    ES: 24,
+    FI: 18,
+    FO: 18,
+    FR: 27,
+    GB: 22,
+    GE: 22,
+    GI: 23,
+    GL: 18,
+    GR: 27,
+    GT: 28,
+    HR: 21,
+    HU: 28,
+    IE: 22,
+    IL: 23,
+    IQ: 23,
+    IS: 26,
+    IT: 27,
+    JO: 30,
+    KW: 30,
+    KZ: 20,
+    LB: 28,
+    LC: 32,
+    LI: 21,
+    LT: 20,
+    LU: 20,
+    LV: 21,
+    LY: 25,
+    MC: 27,
+    MD: 24,
+    ME: 22,
+    MK: 19,
+    MR: 27,
+    MT: 31,
+    MU: 30,
+    NL: 18,
+    NO: 15,
+    PK: 24,
+    PL: 28,
+    PS: 29,
+    PT: 25,
+    QA: 29,
+    RO: 24,
+    RS: 22,
+    SA: 24,
+    SC: 31,
+    SD: 18,
+    SE: 24,
+    SI: 19,
+    SK: 24,
+    SM: 27,
+    ST: 25,
+    SV: 28,
+    TL: 23,
+    TN: 24,
+    TR: 26,
+    UA: 29,
+    VA: 22,
+    VG: 24,
+    XK: 20,
+}).map(([k, v]) => [k, v]));
+const strip = (raw) => raw.replace(/[\s-]/g, "").toUpperCase();
+/**
+ * ISO 7064 MOD-97-10, computed a chunk at a time.
+ *
+ * The whole rearranged IBAN as one integer is up to 36 digits, past what a
+ * JS number holds exactly — so it is folded 7 digits at a time, which is the
+ * standard's own suggestion and stays inside the safe integer range.
+ */
+function mod97(digits) {
+    let remainder = 0;
+    for (let i = 0; i < digits.length; i += 7) {
+        remainder = Number(`${remainder}${digits.slice(i, i + 7)}`) % 97;
+    }
+    return remainder;
+}
+export function validateIban(raw) {
+    const normalized = strip(raw);
+    const base = {
+        kind: "iban",
+        normalized,
+        formatted: (normalized.match(/.{1,4}/g) ?? []).join(" "),
+        parts: {},
+    };
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]+$/.test(normalized)) {
+        return {
+            ...base,
+            valid: false,
+            reason: "not in IBAN form: two letters, two digits, then alphanumerics",
+        };
+    }
+    const country = normalized.slice(0, 2);
+    const expected = IBAN_LENGTHS.get(country);
+    if (expected === undefined) {
+        return { ...base, valid: false, reason: `"${country}" is not a country that issues IBANs` };
+    }
+    if (normalized.length !== expected) {
+        return {
+            ...base,
+            valid: false,
+            reason: `${country} IBANs are ${expected} characters; this is ${normalized.length}`,
+        };
+    }
+    // Move the first four characters to the end, then letters become numbers.
+    const rearranged = normalized.slice(4) + normalized.slice(0, 4);
+    const digits = [...rearranged]
+        .map((ch) => (/[A-Z]/.test(ch) ? String(ch.charCodeAt(0) - 55) : ch))
+        .join("");
+    const ok = mod97(digits) === 1;
+    return {
+        ...base,
+        valid: ok,
+        reason: ok ? "" : "the check digits do not match the rest of the IBAN",
+        parts: { country, checkDigits: normalized.slice(2, 4), bban: normalized.slice(4) },
+    };
+}
+export function validateBic(raw) {
+    const normalized = strip(raw);
+    const match = /^([A-Z]{4})([A-Z]{2})([A-Z0-9]{2})([A-Z0-9]{3})?$/.exec(normalized);
+    if (!match) {
+        return {
+            kind: "bic",
+            valid: false,
+            normalized,
+            formatted: normalized,
+            reason: "a BIC is 8 or 11 characters: 4 bank, 2 country, 2 location, optionally 3 branch",
+            parts: {},
+        };
+    }
+    return {
+        kind: "bic",
+        valid: true,
+        normalized,
+        formatted: normalized,
+        reason: "",
+        parts: {
+            bank: match[1],
+            country: match[2],
+            location: match[3],
+            branch: match[4] ?? "",
+        },
+    };
+}
+/** ABA routing number: a weighted sum over nine digits, 3-7-1 repeating. */
+export function validateAba(raw) {
+    const normalized = raw.replace(/[\s-]/g, "");
+    const base = { kind: "aba", normalized, formatted: normalized, parts: {} };
+    if (!/^\d{9}$/.test(normalized)) {
+        return { ...base, valid: false, reason: "a routing number is exactly nine digits" };
+    }
+    const weights = [3, 7, 1, 3, 7, 1, 3, 7, 1];
+    const sum = [...normalized].reduce((total, digit, i) => total + Number(digit) * weights[i], 0);
+    const ok = sum % 10 === 0;
+    return {
+        ...base,
+        valid: ok,
+        reason: ok ? "" : "the checksum does not match",
+        parts: {
+            federalReserve: normalized.slice(0, 4),
+            institution: normalized.slice(4, 8),
+            check: normalized.slice(8),
+        },
+    };
+}
+/** Luhn, as used by payment cards. */
+export function luhnOk(digits) {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let value = Number(digits[i]);
+        if (double) {
+            value *= 2;
+            if (value > 9)
+                value -= 9;
+        }
+        sum += value;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+/** Card brands, by the prefixes and lengths the networks publish. */
+function cardBrand(digits) {
+    if (/^4\d{12}(\d{3})?(\d{3})?$/.test(digits))
+        return "visa";
+    if (/^(5[1-5]\d{14}|2(2[2-9]\d{12}|[3-6]\d{13}|7[01]\d{12}|720\d{12}))$/.test(digits))
+        return "mastercard";
+    if (/^3[47]\d{13}$/.test(digits))
+        return "amex";
+    if (/^(6011\d{12}|65\d{14}|64[4-9]\d{13})$/.test(digits))
+        return "discover";
+    if (/^3(0[0-5]|[68]\d)\d{11}$/.test(digits))
+        return "diners";
+    if (/^35(2[89]|[3-8]\d)\d{12}$/.test(digits))
+        return "jcb";
+    return "unknown";
+}
+/**
+ * Validate a card number's checksum.
+ *
+ * Only the last four digits are ever echoed. A validator that returned the
+ * number it was given would take a value the caller has to protect and copy
+ * it into a log, a transcript and a model's context.
+ */
+export function validateCard(raw) {
+    const digits = raw.replace(/[\s-]/g, "");
+    const masked = digits.length >= 4 ? `${"*".repeat(Math.max(0, digits.length - 4))}${digits.slice(-4)}` : "";
+    const base = { kind: "card", normalized: masked, formatted: masked, parts: {} };
+    if (!/^\d{12,19}$/.test(digits)) {
+        return { ...base, valid: false, reason: "a card number is 12 to 19 digits" };
+    }
+    const ok = luhnOk(digits);
+    return {
+        ...base,
+        valid: ok,
+        reason: ok ? "" : "the Luhn checksum does not match",
+        parts: { brand: cardBrand(digits), last4: digits.slice(-4), length: String(digits.length) },
+    };
+}
+/** UK sort code: six digits, and no checksum exists to check. */
+export function validateSortCode(raw) {
+    const normalized = raw.replace(/[\s-]/g, "");
+    const ok = /^\d{6}$/.test(normalized);
+    return {
+        kind: "sortcode",
+        valid: ok,
+        normalized,
+        formatted: ok ? (normalized.match(/.{2}/g) ?? []).join("-") : normalized,
+        // Said plainly: a well-formed sort code is not a verified one, and a
+        // caller that reads `valid` as "this bank exists" would be wrong.
+        reason: ok ? "" : "a sort code is exactly six digits",
+        parts: ok ? { note: "a sort code carries no checksum; only its shape was checked" } : {},
+    };
+}
+/** Guess which kind an identifier is, for callers that do not know. */
+export function detectKind(raw) {
+    const normalized = strip(raw);
+    if (/^[A-Z]{2}\d{2}[A-Z0-9]{10,30}$/.test(normalized) &&
+        IBAN_LENGTHS.has(normalized.slice(0, 2))) {
+        return "iban";
+    }
+    if (/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/.test(normalized))
+        return "bic";
+    if (/^\d{9}$/.test(normalized))
+        return "aba";
+    if (/^\d{6}$/.test(normalized))
+        return "sortcode";
+    if (/^\d{12,19}$/.test(normalized))
+        return "card";
+    return null;
+}
+export function validateIdentifier(raw, kind) {
+    switch (kind) {
+        case "iban":
+            return validateIban(raw);
+        case "bic":
+            return validateBic(raw);
+        case "aba":
+            return validateAba(raw);
+        case "card":
+            return validateCard(raw);
+        case "sortcode":
+            return validateSortCode(raw);
+    }
+}

package/dist/lib/lots.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Lot consumption and realized gain.
+ *
+ * Which lots a disposal consumes is a policy choice with a tax consequence,
+ * and once the policy is chosen the arithmetic is fixed. A model asked to do
+ * this will produce a plausible number that cannot be reproduced next
+ * quarter, which is the one property a cost-basis figure must have.
+ *
+ * Cost is integer minor units. Quantity is a decimal, because a lot can be
+ * 0.37 of a share or of a coin — but the cost attached to a lot is tracked
+ * as an integer remainder and the final consumption takes whatever is left,
+ * so a fully consumed lot always accounts for exactly its cost with no
+ * rounding drift.
+ */
+export declare const LOT_METHODS: readonly ["fifo", "lifo", "hifo", "specific"];
+export type LotMethod = (typeof LOT_METHODS)[number];
+export type Lot = {
+    readonly id: string;
+    /** ISO-8601 with an offset. Acquisition time. */
+    readonly acquiredAt: string;
+    readonly quantity: number;
+    /** What the whole lot cost, in minor units. */
+    readonly costMinor: number;
+};
+export type Disposal = {
+    readonly id: string;
+    readonly disposedAt: string;
+    readonly quantity: number;
+    /** What the whole disposal realized, in minor units. */
+    readonly proceedsMinor: number;
+    /** `specific` only: which lots to consume, in order. */
+    readonly lotIds?: ReadonlyArray<string>;
+};
+export type Consumption = {
+    readonly lotId: string;
+    readonly quantity: number;
+    readonly costMinor: number;
+    readonly acquiredAt: string;
+    /** True when held over a year, which most jurisdictions treat differently. */
+    readonly longTerm: boolean;
+};
+export type DisposalResult = {
+    readonly id: string;
+    readonly quantity: number;
+    readonly proceedsMinor: number;
+    readonly costMinor: number;
+    readonly gainMinor: number;
+    readonly shortTermGainMinor: number;
+    readonly longTermGainMinor: number;
+    readonly consumed: ReadonlyArray<Consumption>;
+};
+export type CostBasisResult = {
+    readonly method: LotMethod;
+    readonly disposals: ReadonlyArray<DisposalResult>;
+    readonly realizedGainMinor: number;
+    readonly remainingLots: ReadonlyArray<Lot>;
+    readonly remainingQuantity: number;
+    readonly remainingCostMinor: number;
+};
+export declare function computeCostBasis(lots: ReadonlyArray<Lot>, disposals: ReadonlyArray<Disposal>, method: LotMethod): CostBasisResult;

package/dist/lib/lots.js

@@ -0,0 +1,142 @@
+/**
+ * Lot consumption and realized gain.
+ *
+ * Which lots a disposal consumes is a policy choice with a tax consequence,
+ * and once the policy is chosen the arithmetic is fixed. A model asked to do
+ * this will produce a plausible number that cannot be reproduced next
+ * quarter, which is the one property a cost-basis figure must have.
+ *
+ * Cost is integer minor units. Quantity is a decimal, because a lot can be
+ * 0.37 of a share or of a coin — but the cost attached to a lot is tracked
+ * as an integer remainder and the final consumption takes whatever is left,
+ * so a fully consumed lot always accounts for exactly its cost with no
+ * rounding drift.
+ */
+export const LOT_METHODS = ["fifo", "lifo", "hifo", "specific"];
+const YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+function instant(value, what) {
+    if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value.trim())) {
+        throw new Error(`${what} ("${value}") has no UTC offset — an offset-less timestamp means local time and would put a holding period on the wrong side of a year boundary depending on the machine`);
+    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        throw new Error(`${what} ("${value}") is not a valid ISO-8601 instant`);
+    return parsed;
+}
+export function computeCostBasis(lots, disposals, method) {
+    const seen = new Set();
+    for (const lot of lots) {
+        if (seen.has(lot.id))
+            throw new Error(`two lots share the id "${lot.id}"`);
+        seen.add(lot.id);
+        if (lot.quantity <= 0)
+            throw new Error(`lot "${lot.id}" has quantity ${lot.quantity}`);
+        if (!Number.isInteger(lot.costMinor))
+            throw new Error(`lot "${lot.id}" cost must be minor units`);
+        instant(lot.acquiredAt, `lot "${lot.id}" acquiredAt`);
+    }
+    // Working copies: remaining cost is an integer so a lot cannot drift.
+    const open = lots.map((lot) => ({
+        ...lot,
+        remainingQuantity: lot.quantity,
+        remainingCostMinor: lot.costMinor,
+        acquiredMs: instant(lot.acquiredAt, "acquiredAt"),
+    }));
+    const results = [];
+    for (const disposal of disposals) {
+        const disposedMs = instant(disposal.disposedAt, `disposal "${disposal.id}" disposedAt`);
+        if (disposal.quantity <= 0) {
+            throw new Error(`disposal "${disposal.id}" has quantity ${disposal.quantity}`);
+        }
+        let order = open.filter((l) => l.remainingQuantity > 0);
+        if (method === "specific") {
+            const wanted = disposal.lotIds;
+            if (!wanted || wanted.length === 0) {
+                throw new Error(`disposal "${disposal.id}" uses the specific-identification method but names no lots`);
+            }
+            const index = new Map(order.map((l) => [l.id, l]));
+            order = wanted.map((id) => {
+                const lot = index.get(id);
+                if (!lot) {
+                    throw new Error(`disposal "${disposal.id}" names lot "${id}", which is not open`);
+                }
+                return lot;
+            });
+        }
+        else if (method === "fifo") {
+            order = [...order].sort((a, b) => a.acquiredMs - b.acquiredMs || (a.id < b.id ? -1 : 1));
+        }
+        else if (method === "lifo") {
+            order = [...order].sort((a, b) => b.acquiredMs - a.acquiredMs || (a.id < b.id ? -1 : 1));
+        }
+        else {
+            // Highest cost per unit first, which realizes the smallest gain.
+            order = [...order].sort((a, b) => b.remainingCostMinor / b.remainingQuantity - a.remainingCostMinor / a.remainingQuantity ||
+                (a.id < b.id ? -1 : 1));
+        }
+        let toConsume = disposal.quantity;
+        const consumed = [];
+        let costMinor = 0;
+        for (const lot of order) {
+            if (toConsume <= 0)
+                break;
+            const take = Math.min(toConsume, lot.remainingQuantity);
+            // Taking the whole remainder consumes the whole remaining cost. That
+            // is what keeps a lot's costs summing to exactly what it cost, however
+            // many partial disposals came before.
+            const takeCost = take === lot.remainingQuantity
+                ? lot.remainingCostMinor
+                : Math.round((lot.remainingCostMinor * take) / lot.remainingQuantity);
+            lot.remainingQuantity -= take;
+            lot.remainingCostMinor -= takeCost;
+            toConsume -= take;
+            costMinor += takeCost;
+            consumed.push({
+                lotId: lot.id,
+                quantity: take,
+                costMinor: takeCost,
+                acquiredAt: lot.acquiredAt,
+                longTerm: disposedMs - lot.acquiredMs > YEAR_MS,
+            });
+        }
+        if (toConsume > 1e-9) {
+            throw new Error(`disposal "${disposal.id}" needs ${disposal.quantity} but only ${disposal.quantity - toConsume} was open — a disposal cannot exceed the lots held`);
+        }
+        // Proceeds follow the units, so the split between short and long term is
+        // allocated by quantity rather than by cost.
+        const gainMinor = disposal.proceedsMinor - costMinor;
+        let longTermProceeds = 0;
+        let longTermCost = 0;
+        for (const entry of consumed) {
+            if (!entry.longTerm)
+                continue;
+            longTermProceeds += Math.round((disposal.proceedsMinor * entry.quantity) / disposal.quantity);
+            longTermCost += entry.costMinor;
+        }
+        const longTermGainMinor = longTermProceeds - longTermCost;
+        results.push({
+            id: disposal.id,
+            quantity: disposal.quantity,
+            proceedsMinor: disposal.proceedsMinor,
+            costMinor,
+            gainMinor,
+            longTermGainMinor,
+            shortTermGainMinor: gainMinor - longTermGainMinor,
+            consumed,
+        });
+    }
+    const remaining = open.filter((l) => l.remainingQuantity > 0);
+    return {
+        method,
+        disposals: results,
+        realizedGainMinor: results.reduce((s, r) => s + r.gainMinor, 0),
+        remainingLots: remaining.map((l) => ({
+            id: l.id,
+            acquiredAt: l.acquiredAt,
+            quantity: l.remainingQuantity,
+            costMinor: l.remainingCostMinor,
+        })),
+        remainingQuantity: remaining.reduce((s, l) => s + l.remainingQuantity, 0),
+        remainingCostMinor: remaining.reduce((s, l) => s + l.remainingCostMinor, 0),
+    };
+}

package/dist/lib/match.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Three-way match: invoice against purchase order against goods receipt.
+ *
+ * This is the standard accounts-payable control, and it is entirely
+ * mechanical — pair the lines, compare price and quantity, and report what
+ * falls outside tolerance. A model reading two documents to decide whether
+ * 4,800 matches 4,750 is being paid to do subtraction, and it will sometimes
+ * get it wrong on an invoice nobody re-reads.
+ */
+export type MatchLine = {
+    readonly id: string;
+    /** Explicit link to a PO line, when the document carries one. */
+    readonly poLineId?: string;
+    readonly sku?: string;
+    readonly description?: string;
+    readonly quantity: number;
+    readonly unitPriceMinor: number;
+};
+export type Tolerance = {
+    /** Allowed unit-price variance, in basis points. 100 is 1%. */
+    readonly pricePercentBps?: number;
+    /** Allowed variance in absolute minor units, whichever is larger. */
+    readonly priceAbsoluteMinor?: number;
+    readonly quantityPercentBps?: number;
+    readonly quantityAbsolute?: number;
+};
+export declare const MATCH_STATUSES: readonly ["matched", "price-variance", "quantity-variance", "both-variance", "over-receipt", "not-received"];
+export type MatchStatus = (typeof MATCH_STATUSES)[number];
+export type MatchPair = {
+    readonly invoiceLineId: string;
+    readonly poLineId: string;
+    readonly matchedBy: "reference" | "sku" | "description";
+    readonly status: MatchStatus;
+    readonly invoiceUnitPriceMinor: number;
+    readonly poUnitPriceMinor: number;
+    readonly priceDeltaMinor: number;
+    readonly invoiceQuantity: number;
+    readonly poQuantity: number;
+    readonly receivedQuantity: number | null;
+    readonly quantityDelta: number;
+    /** What the variance costs, positive when the invoice asks for more. */
+    readonly exposureMinor: number;
+    readonly reasons: ReadonlyArray<string>;
+};
+export type MatchReport = {
+    readonly pairs: ReadonlyArray<MatchPair>;
+    readonly unmatchedInvoiceLines: ReadonlyArray<string>;
+    readonly unmatchedPoLines: ReadonlyArray<string>;
+    readonly ok: boolean;
+    readonly exceptions: number;
+    /** Net amount the invoice claims above the order, across every exception. */
+    readonly totalExposureMinor: number;
+    readonly threeWay: boolean;
+};
+export declare function matchInvoiceToPurchaseOrder(invoiceLines: ReadonlyArray<MatchLine>, poLines: ReadonlyArray<MatchLine>, receiptLines?: ReadonlyArray<{
+    readonly poLineId: string;
+    readonly quantity: number;
+}>, tolerance?: Tolerance): MatchReport;