tallyd 0.0.0-stage → 0.1.0

package/dist/statement/line.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A single line from a bank statement.
+ *
+ * Note what this is *not*: it is not a journal entry. A statement line is
+ * someone else's record of what happened, and the whole reconciliation problem
+ * exists because it disagrees with ours. So it keeps its own raw text, its own
+ * sign convention (positive is money into the account), and the row it came
+ * from, so a match can be explained by pointing at the source.
+ */
+import type { Money } from "../money/money.js";
+import type { CalendarDate } from "../ledger/date.js";
+export interface StatementLineInput {
+    id: string;
+    date: CalendarDate;
+    /** Where the money actually settled, when the export distinguishes the two. */
+    valueDate?: CalendarDate;
+    description: string;
+    amount: Money;
+    balance?: Money;
+    reference?: string;
+    type?: string;
+    /** Zero-based index in the source file, after the header. */
+    sourceRow: number;
+    raw?: Readonly<Record<string, string>>;
+}
+export interface StatementLine {
+    readonly id: string;
+    readonly date: CalendarDate;
+    readonly valueDate: CalendarDate | null;
+    readonly description: string;
+    /** Positive is money in, negative is money out. */
+    readonly amount: Money;
+    readonly balance: Money | null;
+    readonly reference: string | null;
+    readonly type: string | null;
+    readonly sourceRow: number;
+    readonly raw: Readonly<Record<string, string>>;
+    /** Description reduced to comparable form. */
+    readonly normalisedDescription: string;
+    /** Stable hash of date, amount and normalised description. */
+    readonly fingerprint: string;
+}
+/**
+ * Reduce a description to something comparable.
+ *
+ * Card descriptors carry a lot of noise that varies between otherwise
+ * identical transactions: terminal ids, dates baked into the text, the `SQ *`
+ * and `PAYPAL *` processor prefixes, and inconsistent spacing. Stripping them
+ * is what lets two records of one purchase look alike.
+ */
+export declare function normaliseDescription(input: string): string;
+/**
+ * A short, stable hash. FNV-1a: not cryptographic, but deterministic across
+ * runs and platforms, which is what a fingerprint needs to be.
+ */
+export declare function hashString(input: string): string;
+export declare function fingerprintOf(date: CalendarDate, amount: Money, normalisedDescription: string): string;
+export declare function statementLine(input: StatementLineInput): StatementLine;
+export declare function isMoneyIn(line: StatementLine): boolean;
+export declare function isMoneyOut(line: StatementLine): boolean;

package/dist/statement/line.js

@@ -0,0 +1,73 @@
+/**
+ * A single line from a bank statement.
+ *
+ * Note what this is *not*: it is not a journal entry. A statement line is
+ * someone else's record of what happened, and the whole reconciliation problem
+ * exists because it disagrees with ours. So it keeps its own raw text, its own
+ * sign convention (positive is money into the account), and the row it came
+ * from, so a match can be explained by pointing at the source.
+ */
+/**
+ * Reduce a description to something comparable.
+ *
+ * Card descriptors carry a lot of noise that varies between otherwise
+ * identical transactions: terminal ids, dates baked into the text, the `SQ *`
+ * and `PAYPAL *` processor prefixes, and inconsistent spacing. Stripping them
+ * is what lets two records of one purchase look alike.
+ */
+export function normaliseDescription(input) {
+    let text = input.toUpperCase();
+    // Processor prefixes: "SQ *COFFEE", "PAYPAL *ACME", "IZ *SHOP".
+    text = text.replace(/\b(SQ|PAYPAL|PP|IZ|TST|SP|WWW)\s*\*\s*/g, " ");
+    // Card-scheme noise.
+    text = text.replace(/\b(VISA|MASTERCARD|MAESTRO|DEBIT|CREDIT)\s+(CARD\s+)?(PAYMENT|PURCHASE)\b/g, " ");
+    text = text.replace(/\bCARD\s+(PAYMENT|PURCHASE)\b/g, " ");
+    text = text.replace(/\b(POS|ATM|CHQ|BGC|DD|SO|FPI|FPO|TFR)\b/g, " ");
+    text = text.replace(/\bON\s+\d{1,2}[-/ ][A-Z]{3}[-/ ]?\d{0,4}\b/g, " ");
+    // Dates and long digit runs baked into the descriptor.
+    text = text.replace(/\b\d{1,2}[-/.]\d{1,2}([-/.]\d{2,4})?\b/g, " ");
+    text = text.replace(/\b\d{6,}\b/g, " ");
+    // Trailing terminal/reference numbers: "COFFEE 4471".
+    text = text.replace(/\s+\d{2,6}\s*$/, " ");
+    text = text.replace(/[^A-Z0-9 ]+/g, " ");
+    text = text.replace(/\s+/g, " ").trim();
+    return text;
+}
+/**
+ * A short, stable hash. FNV-1a: not cryptographic, but deterministic across
+ * runs and platforms, which is what a fingerprint needs to be.
+ */
+export function hashString(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+export function fingerprintOf(date, amount, normalisedDescription) {
+    return hashString(`${date}|${amount.currency.code}|${amount.minorUnits.toString()}|${normalisedDescription}`);
+}
+export function statementLine(input) {
+    const normalisedDescription = normaliseDescription(input.description);
+    return Object.freeze({
+        id: input.id,
+        date: input.date,
+        valueDate: input.valueDate ?? null,
+        description: input.description.trim(),
+        amount: input.amount,
+        balance: input.balance ?? null,
+        reference: input.reference?.trim() ?? null,
+        type: input.type?.trim() ?? null,
+        sourceRow: input.sourceRow,
+        raw: Object.freeze({ ...(input.raw ?? {}) }),
+        normalisedDescription,
+        fingerprint: fingerprintOf(input.date, input.amount, normalisedDescription),
+    });
+}
+export function isMoneyIn(line) {
+    return line.amount.isPositive;
+}
+export function isMoneyOut(line) {
+    return line.amount.isNegative;
+}

package/dist/statement/ofx.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A reader for the subset of OFX/QFX that bank downloads actually contain.
+ *
+ * OFX is SGML, not XML: tags are frequently unclosed, so `<NAME>TESCO` runs to
+ * the end of the line. A strict XML parser fails on nearly every real file.
+ * This reads the aggregate structure directly, which is both simpler and more
+ * tolerant, and it only understands the handful of tags a bank statement uses.
+ *
+ * Not supported, deliberately: investment transactions, bill-pay aggregates
+ * and the OFX request/response envelope. Those are a different product.
+ */
+import { Money } from "../money/money.js";
+import type { Currency } from "../money/currency.js";
+import { type CalendarDate } from "../ledger/date.js";
+import type { RowError } from "./import.js";
+import { type StatementLine } from "./line.js";
+export interface OfxAccount {
+    readonly bankId: string | null;
+    readonly accountId: string | null;
+    readonly accountType: string | null;
+    readonly currency: Currency;
+}
+export interface OfxImportResult {
+    readonly lines: readonly StatementLine[];
+    readonly errors: readonly RowError[];
+    readonly warnings: readonly string[];
+    readonly account: OfxAccount;
+    readonly ledgerBalance: Money | null;
+    readonly balanceAsOf: CalendarDate | null;
+    readonly transactionCount: number;
+}
+/**
+ * Read an OFX datetime: `YYYYMMDD`, optionally with a time and a bracketed
+ * timezone, e.g. `20260814120000[-5:EST]`. Only the date survives — see the
+ * note in `ledger/date.ts` on why postings do not carry an instant.
+ */
+export declare function parseOfxDate(raw: string): CalendarDate;
+/** Split out every `<STMTTRN>` aggregate. */
+export declare function extractTransactionBlocks(input: string): readonly string[];
+export interface OfxImportOptions {
+    /** Fallback when the file does not declare one. */
+    currency?: Currency | string;
+    idPrefix?: string;
+}
+export declare function importOfx(input: string, options?: OfxImportOptions): OfxImportResult;
+/** True when the text looks like OFX rather than CSV. */
+export declare function looksLikeOfx(input: string): boolean;

package/dist/statement/ofx.js

@@ -0,0 +1,199 @@
+/**
+ * A reader for the subset of OFX/QFX that bank downloads actually contain.
+ *
+ * OFX is SGML, not XML: tags are frequently unclosed, so `<NAME>TESCO` runs to
+ * the end of the line. A strict XML parser fails on nearly every real file.
+ * This reads the aggregate structure directly, which is both simpler and more
+ * tolerant, and it only understands the handful of tags a bank statement uses.
+ *
+ * Not supported, deliberately: investment transactions, bill-pay aggregates
+ * and the OFX request/response envelope. Those are a different product.
+ */
+import { Money } from "../money/money.js";
+import { currency as lookupCurrency, isRegistered } from "../money/currency.js";
+import { date as toCalendarDate } from "../ledger/date.js";
+import { statementLine } from "./line.js";
+/**
+ * Read an OFX datetime: `YYYYMMDD`, optionally with a time and a bracketed
+ * timezone, e.g. `20260814120000[-5:EST]`. Only the date survives — see the
+ * note in `ledger/date.ts` on why postings do not carry an instant.
+ */
+export function parseOfxDate(raw) {
+    const text = raw.trim();
+    const match = /^(\d{4})(\d{2})(\d{2})/.exec(text);
+    if (match === null)
+        throw new RangeError(`Not an OFX date: ${JSON.stringify(raw)}`);
+    return toCalendarDate(`${match[1]}-${match[2]}-${match[3]}`);
+}
+/** Pull the value of an unclosed-or-closed SGML tag from one aggregate. */
+function tagValue(block, tag) {
+    const pattern = new RegExp(`<${tag}>([^<\\r\\n]*)`, "i");
+    const match = pattern.exec(block);
+    if (match === null)
+        return null;
+    const value = (match[1] ?? "").trim();
+    return value === "" ? null : value;
+}
+function decodeEntities(input) {
+    return input
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&apos;/gi, "'")
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)));
+}
+/** Split out every `<STMTTRN>` aggregate. */
+export function extractTransactionBlocks(input) {
+    const blocks = [];
+    const pattern = /<STMTTRN>([\s\S]*?)(?:<\/STMTTRN>|(?=<STMTTRN>)|$)/gi;
+    let match;
+    while ((match = pattern.exec(input)) !== null) {
+        const body = match[1] ?? "";
+        if (body.trim() !== "")
+            blocks.push(body);
+    }
+    return blocks;
+}
+export function importOfx(input, options = {}) {
+    const text = input.replace(/\r\n/g, "\n");
+    const warnings = [];
+    const errors = [];
+    const declared = tagValue(text, "CURDEF");
+    const fallback = typeof options.currency === "string"
+        ? lookupCurrency(options.currency)
+        : (options.currency ?? lookupCurrency("GBP"));
+    let currency = fallback;
+    if (declared !== null) {
+        if (isRegistered(declared)) {
+            currency = lookupCurrency(declared);
+        }
+        else {
+            warnings.push(`File declares unknown currency ${declared}; using ${fallback.code}`);
+        }
+    }
+    else {
+        warnings.push(`File declares no currency; assuming ${fallback.code}`);
+    }
+    const account = Object.freeze({
+        bankId: tagValue(text, "BANKID"),
+        accountId: tagValue(text, "ACCTID"),
+        accountType: tagValue(text, "ACCTTYPE"),
+        currency,
+    });
+    const blocks = extractTransactionBlocks(text);
+    const prefix = options.idPrefix ?? "OFX";
+    const lines = [];
+    blocks.forEach((block, index) => {
+        const rawDate = tagValue(block, "DTPOSTED");
+        const rawAmount = tagValue(block, "TRNAMT");
+        if (rawDate === null) {
+            errors.push({ row: index, reason: "transaction has no DTPOSTED", cells: [block.trim()] });
+            return;
+        }
+        if (rawAmount === null) {
+            errors.push({ row: index, reason: "transaction has no TRNAMT", cells: [block.trim()] });
+            return;
+        }
+        let when;
+        try {
+            when = parseOfxDate(rawDate);
+        }
+        catch (error) {
+            errors.push({
+                row: index,
+                reason: error instanceof Error ? error.message : String(error),
+                cells: [block.trim()],
+            });
+            return;
+        }
+        let amount;
+        try {
+            // OFX mandates a dot decimal and no grouping, and signs the amount
+            // itself: negative is money out, which matches our convention already.
+            amount = Money.parse(rawAmount.replace(/,/g, ""), currency);
+        }
+        catch (error) {
+            errors.push({
+                row: index,
+                reason: error instanceof Error ? error.message : String(error),
+                cells: [block.trim()],
+            });
+            return;
+        }
+        const name = tagValue(block, "NAME");
+        const memo = tagValue(block, "MEMO");
+        const payee = tagValue(block, "PAYEE");
+        const description = decodeEntities([payee, name, memo].filter((v) => v !== null).join(" — "));
+        const fitId = tagValue(block, "FITID");
+        const checkNum = tagValue(block, "CHECKNUM");
+        const type = tagValue(block, "TRNTYPE");
+        let valueDate;
+        const rawValueDate = tagValue(block, "DTAVAIL");
+        if (rawValueDate !== null) {
+            try {
+                valueDate = parseOfxDate(rawValueDate);
+            }
+            catch {
+                warnings.push(`Transaction ${index}: could not read DTAVAIL`);
+            }
+        }
+        const raw = {};
+        for (const tag of ["FITID", "TRNTYPE", "DTPOSTED", "TRNAMT", "NAME", "MEMO", "CHECKNUM"]) {
+            const value = tagValue(block, tag);
+            if (value !== null)
+                raw[tag] = value;
+        }
+        lines.push(statementLine({
+            // FITID is the bank's own unique id and is the right thing to key on
+            // when present, because it survives a re-download of the same period.
+            id: fitId !== null ? `${prefix}-${fitId}` : `${prefix}-${String(index + 1).padStart(4, "0")}`,
+            date: when,
+            ...(valueDate === undefined ? {} : { valueDate }),
+            description,
+            amount,
+            ...(checkNum === null ? {} : { reference: checkNum }),
+            ...(type === null ? {} : { type }),
+            sourceRow: index,
+            raw,
+        }));
+    });
+    let ledgerBalance = null;
+    let balanceAsOf = null;
+    const ledgerBalanceBlock = /<LEDGERBAL>([\s\S]*?)(?:<\/LEDGERBAL>|$)/i.exec(text);
+    if (ledgerBalanceBlock !== null) {
+        const body = ledgerBalanceBlock[1] ?? "";
+        const rawBalance = tagValue(body, "BALAMT");
+        if (rawBalance !== null) {
+            try {
+                ledgerBalance = Money.parse(rawBalance.replace(/,/g, ""), currency);
+            }
+            catch {
+                warnings.push(`Could not read LEDGERBAL BALAMT ${JSON.stringify(rawBalance)}`);
+            }
+        }
+        const rawAsOf = tagValue(body, "DTASOF");
+        if (rawAsOf !== null) {
+            try {
+                balanceAsOf = parseOfxDate(rawAsOf);
+            }
+            catch {
+                warnings.push("Could not read LEDGERBAL DTASOF");
+            }
+        }
+    }
+    return Object.freeze({
+        lines: Object.freeze(lines),
+        errors: Object.freeze(errors),
+        warnings: Object.freeze(warnings),
+        account,
+        ledgerBalance,
+        balanceAsOf,
+        transactionCount: blocks.length,
+    });
+}
+/** True when the text looks like OFX rather than CSV. */
+export function looksLikeOfx(input) {
+    const head = input.slice(0, 4096).toUpperCase();
+    return head.includes("<OFX>") || head.includes("OFXHEADER") || head.includes("<STMTTRN>");
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "tallyd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Double-entry ledger and bank-reconciliation engine",
+  "type": "module",
+  "license": "MIT",
+  "author": "Daniyal",
+  "keywords": [
+    "accounting",
+    "double-entry",
+    "ledger",
+    "bookkeeping",
+    "reconciliation",
+    "bank-statement",
+    "trial-balance",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DaniyalMlk/tallyd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DaniyalMlk/tallyd/issues"
+  },
+  "homepage": "https://github.com/DaniyalMlk/tallyd#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "tallyd": "dist/cli/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "demo": "vite-node src/demo/main.ts",
+    "demo:ingest": "vite-node src/demo/mainIngest.ts",
+    "demo:reconcile": "vite-node src/demo/mainReconcile.ts",
+    "demo:reports": "vite-node src/demo/mainStatements.ts",
+    "demo:foreign": "vite-node src/demo/mainForeign.ts",
+    "demo:group": "vite-node src/demo/mainGroup.ts",
+    "demo:periods": "vite-node src/demo/mainGroupPeriods.ts",
+    "demo:midyear": "vite-node src/demo/mainMidYear.ts",
+    "demo:disposal": "vite-node src/demo/mainDisposal.ts",
+    "demo:evidence": "vite-node src/demo/mainEvidence.ts",
+    "cli": "vite-node src/cli/main.ts --",
+    "bench": "vite-node src/cli/main.ts -- bench",
+    "generate": "vite-node src/cli/main.ts -- generate"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "fast-check": "^3.23.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}