@morroc/open-ledger 0.14.1

package/dist/db/queries/files.js

@@ -0,0 +1,72 @@
+/** Missing status buckets are filled with 0 so callers get a stable shape without null checks. */
+export function countFiles(db) {
+    const rows = db
+        .prepare(`SELECT status, COUNT(*) AS n FROM files GROUP BY status`)
+        .all();
+    const totals = { ingested: 0, pending: 0, failed: 0 };
+    for (const row of rows) {
+        if (row.status === "ingested" || row.status === "pending" || row.status === "failed") {
+            totals[row.status] = row.n;
+        }
+    }
+    return totals;
+}
+const FILE_SELECT = `SELECT id, path, file_hash, mime, status, ingested_at, source, error, created_at
+   FROM files`;
+export function listFiles(db) {
+    return db
+        .prepare(`${FILE_SELECT} ORDER BY ingested_at DESC, created_at DESC`)
+        .all();
+}
+export function findFileById(db, id) {
+    const row = db.prepare(`${FILE_SELECT} WHERE id = ?`).get(id);
+    return row ?? null;
+}
+/** The row a file's bytes already registered as; `file_hash` is UNIQUE, so a content match is exactly one row. */
+export function findFileByHash(db, hash) {
+    const row = db.prepare(`${FILE_SELECT} WHERE file_hash = ?`).get(hash);
+    return row ?? null;
+}
+export function insertPendingFile(db, file) {
+    db.prepare(`INSERT INTO files (id, path, file_hash, mime, status) VALUES (?, ?, ?, ?, 'pending')`).run(file.id, file.path, file.file_hash, file.mime);
+}
+/**
+ * Delete leads (file_hash is UNIQUE) then re-insert, atomically; the delete cascades away
+ * the prior row's transactions and questions (ON DELETE CASCADE).
+ */
+export function replaceFile(db, priorId, file) {
+    const tx = db.transaction(() => {
+        deleteFile(db, priorId);
+        insertPendingFile(db, file);
+    });
+    tx();
+}
+/**
+ * Cascaded transaction/question counts are gathered before the DELETE runs —
+ * CASCADE would make them unrecoverable after.
+ */
+export function deleteFile(db, id) {
+    const removed = findFileById(db, id);
+    if (!removed) {
+        return { removed: null, removedTransactions: 0, removedQuestions: 0 };
+    }
+    const removedTransactions = db
+        .prepare(`SELECT COUNT(*) AS n FROM transactions WHERE source_file_id = ?`)
+        .get(id).n;
+    const removedQuestions = db
+        .prepare(`SELECT COUNT(*) AS n FROM questions WHERE file_id = ?`)
+        .get(id).n;
+    db.prepare(`DELETE FROM files WHERE id = ?`).run(id);
+    return { removed, removedTransactions, removedQuestions };
+}
+export function markFileIngested(db, fileId, opts) {
+    return db
+        .prepare(`UPDATE files SET status = 'ingested', ingested_at = datetime('now'), source = ? WHERE id = ?`)
+        .run(opts.source ?? null, fileId).changes;
+}
+/** ingested_at is left untouched: a failed file was never successfully ingested. */
+export function markFileFailed(db, fileId, opts) {
+    return db
+        .prepare(`UPDATE files SET status = 'failed', source = ?, error = ? WHERE id = ?`)
+        .run(opts.source ?? null, opts.error, fileId).changes;
+}

package/dist/db/queries/merchants.js

@@ -0,0 +1,163 @@
+import { randomUUID } from "crypto";
+/**
+ * Strips store ids, terminal codes, city tags, and transaction-type words so
+ * "STARBUCKS #1234 BKK CHARGE" and "Starbucks #5678 BANGKOK" both normalize
+ * to "starbucks" — the form `merchant_aliases.normalized_pattern` indexes.
+ */
+const NOISE_TOKENS = new Set([
+    "bkk", "bangkok", "thailand", "th", "tha",
+    "charge", "purchase", "payment", "pmt", "ref", "txn", "trx", "tx",
+    "pos", "atm", "online", "web", "mobile", "app",
+    "co", "ltd", "company", "inc", "llc", "plc", "intl",
+]);
+export function normalizeDescriptor(raw) {
+    if (!raw)
+        return "";
+    const lowered = raw.toLowerCase();
+    const stripped = lowered
+        .replace(/[#*][a-z0-9]+/gi, " ")
+        .replace(/\b\d{2,}\b/g, " ")
+        .replace(/[^a-z0-9\s]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!stripped)
+        return "";
+    const tokens = stripped.split(" ").filter(t => t.length > 1 && !NOISE_TOKENS.has(t));
+    if (tokens.length === 0)
+        return stripped;
+    return tokens.join(" ");
+}
+/**
+ * Meant to run inside the same DB transaction as the write it serves, so a
+ * transaction never lands without its merchant.
+ */
+export function upsertMerchant(db, input) {
+    const canonical = input.canonical_name.trim();
+    if (!canonical) {
+        throw new Error("merchant canonical_name is required");
+    }
+    const existing = db
+        .prepare(`SELECT id, canonical_name, default_account_id, created_at FROM merchants WHERE canonical_name = ?`)
+        .get(canonical);
+    let merchant;
+    if (existing) {
+        merchant = existing;
+        if (input.default_account_id && input.default_account_id !== existing.default_account_id) {
+            db.prepare(`UPDATE merchants SET default_account_id = ? WHERE id = ?`)
+                .run(input.default_account_id, existing.id);
+            merchant = { ...existing, default_account_id: input.default_account_id };
+        }
+    }
+    else {
+        const id = `m:${randomUUID()}`;
+        db.prepare(`INSERT INTO merchants (id, canonical_name, default_account_id) VALUES (?, ?, ?)`).run(id, canonical, input.default_account_id ?? null);
+        merchant = {
+            id,
+            canonical_name: canonical,
+            default_account_id: input.default_account_id ?? null,
+            created_at: new Date().toISOString(),
+        };
+    }
+    let aliasConflict;
+    if (input.alias) {
+        const normalized = normalizeDescriptor(input.alias);
+        if (normalized) {
+            const existsAlias = db
+                .prepare(`SELECT merchant_id FROM merchant_aliases WHERE normalized_pattern = ?`)
+                .get(normalized);
+            if (!existsAlias) {
+                db.prepare(`INSERT INTO merchant_aliases (id, merchant_id, normalized_pattern) VALUES (?, ?, ?)`).run(`ma:${randomUUID()}`, merchant.id, normalized);
+            }
+            else if (existsAlias.merchant_id !== merchant.id) {
+                aliasConflict = { pattern: normalized, held_by: existsAlias.merchant_id };
+            }
+        }
+    }
+    return aliasConflict ? { ...merchant, alias_conflict: aliasConflict } : merchant;
+}
+export function findMerchantByAlias(db, rawDescriptor) {
+    const normalized = normalizeDescriptor(rawDescriptor);
+    if (!normalized)
+        return null;
+    const row = db.prepare(`SELECT m.id, m.canonical_name, m.default_account_id, m.created_at
+     FROM merchant_aliases ma
+     JOIN merchants m ON m.id = ma.merchant_id
+     WHERE ma.normalized_pattern = ?`).get(normalized);
+    if (!row)
+        return null;
+    return { merchant: row, default_account_id: row.default_account_id };
+}
+export function listMerchants(db, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 200, 1), 1000);
+    return db.prepare(`SELECT m.id, m.canonical_name, m.default_account_id, m.created_at,
+            (SELECT COUNT(*) FROM merchant_aliases ma WHERE ma.merchant_id = m.id) AS alias_count
+     FROM merchants m
+     ORDER BY m.canonical_name
+     LIMIT ?`).all(limit);
+}
+export function countMerchants(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM merchants`).get();
+    return row.n;
+}
+export function merchantExists(db, id) {
+    return !!db.prepare(`SELECT 1 FROM merchants WHERE id = ?`).get(id);
+}
+export function findMerchantById(db, id) {
+    const row = db
+        .prepare(`SELECT id, canonical_name, default_account_id, created_at FROM merchants WHERE id = ?`)
+        .get(id);
+    return row ?? null;
+}
+export function setMerchantDefaultAccount(db, merchantId, accountId) {
+    const before = db
+        .prepare(`SELECT default_account_id FROM merchants WHERE id = ?`)
+        .get(merchantId);
+    if (!before)
+        throw new Error(`merchant not found: ${merchantId}`);
+    db.prepare(`UPDATE merchants SET default_account_id = ? WHERE id = ?`)
+        .run(accountId, merchantId);
+    return { before: before.default_account_id, after: accountId };
+}
+export function clearMerchantDefaultAccount(db, merchantId) {
+    const row = db
+        .prepare(`SELECT default_account_id FROM merchants WHERE id = ?`)
+        .get(merchantId);
+    if (!row)
+        return null;
+    db.prepare(`UPDATE merchants SET default_account_id = NULL WHERE id = ?`).run(merchantId);
+    return { before: row.default_account_id };
+}
+/** One transaction, so a partial merge never persists. */
+export function mergeMerchants(db, fromId, toId) {
+    if (fromId === toId)
+        throw new Error("Cannot merge a merchant into itself.");
+    const from = findMerchantById(db, fromId);
+    if (!from)
+        throw new Error(`Source merchant ${fromId} not found.`);
+    const to = findMerchantById(db, toId);
+    if (!to)
+        throw new Error(`Destination merchant ${toId} not found.`);
+    let movedTransactions = 0;
+    let movedAliases = 0;
+    let adoptedDefaultAccount;
+    const tx = db.transaction(() => {
+        movedTransactions = db
+            .prepare(`UPDATE transactions SET merchant_id = ? WHERE merchant_id = ?`)
+            .run(toId, fromId).changes;
+        movedAliases = db
+            .prepare(`UPDATE merchant_aliases SET merchant_id = ? WHERE merchant_id = ?`)
+            .run(toId, fromId).changes;
+        if (!to.default_account_id && from.default_account_id) {
+            db.prepare(`UPDATE merchants SET default_account_id = ? WHERE id = ?`)
+                .run(from.default_account_id, toId);
+            adoptedDefaultAccount = from.default_account_id;
+        }
+        db.prepare(`DELETE FROM merchants WHERE id = ?`).run(fromId);
+    });
+    tx();
+    return {
+        moved_transactions: movedTransactions,
+        moved_aliases: movedAliases,
+        ...(adoptedDefaultAccount ? { adopted_default_account: adoptedDefaultAccount } : {}),
+    };
+}

package/dist/db/queries/notes.js

@@ -0,0 +1,28 @@
+export function listNotes(db) {
+    return db.prepare(`SELECT id, content, category, created_at FROM notes ORDER BY created_at DESC`).all();
+}
+export function countNotes(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM notes`).get();
+    return row.n;
+}
+/**
+ * Idempotent on (category, content): a verbatim repeat is a no-op. Semantic
+ * dedup (different wording for the same note) is the calling agent's job.
+ */
+export function addNote(db, content, category = "fact") {
+    const existing = db
+        .prepare(`SELECT 1 FROM notes WHERE category = ? AND content = ? LIMIT 1`)
+        .get(category, content);
+    if (existing)
+        return;
+    db.prepare(`INSERT INTO notes (content, category) VALUES (?, ?)`).run(content, category);
+}
+export function deleteNote(db, id) {
+    const row = db
+        .prepare(`SELECT id, content, category, created_at FROM notes WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    db.prepare(`DELETE FROM notes WHERE id = ?`).run(id);
+    return row;
+}

package/dist/db/queries/questions.js

@@ -0,0 +1,117 @@
+import { randomUUID } from "crypto";
+import { parseJsonOrNull } from "../../lib/json.js";
+/** The `cn:` id prefix is opaque - nothing else parses it. */
+export function recordQuestion(db, input) {
+    const id = `cn:${randomUUID()}`;
+    db.prepare(`INSERT INTO questions (id, batch_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.batch_id ?? null, input.file_id, input.transaction_id ?? null, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null, input.context ? JSON.stringify(input.context) : null);
+    if (input.transaction_id) {
+        db.prepare(`UPDATE transactions SET has_question = 1 WHERE id = ?`).run(input.transaction_id);
+    }
+    if (input.account_id) {
+        db.prepare(`UPDATE accounts SET has_question = 1 WHERE id = ?`).run(input.account_id);
+    }
+    return id;
+}
+/** Deletes the row outright (rather than marking it closed); null if the id doesn't exist. */
+export function closeQuestion(db, id, answer) {
+    const row = db
+        .prepare(`SELECT prompt, kind, transaction_id, account_id, context_json FROM questions WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    db.prepare(`DELETE FROM questions WHERE id = ?`).run(id);
+    maybeClearHasQuestionFlags(db, {
+        transaction_id: row.transaction_id,
+        account_id: row.account_id,
+    });
+    return {
+        prompt: row.prompt,
+        kind: row.kind,
+        answer,
+        rule_key: extractRuleKey(row.context_json),
+    };
+}
+function extractRuleKey(contextJson) {
+    const parsed = parseJsonOrNull(contextJson);
+    return typeof parsed?.rule_key === "string" ? parsed.rule_key : null;
+}
+// Safe to call after any resolution; idempotent.
+function maybeClearHasQuestionFlags(db, target) {
+    if (target.transaction_id) {
+        const open = db
+            .prepare(`SELECT 1 FROM questions WHERE transaction_id = ? LIMIT 1`)
+            .get(target.transaction_id);
+        if (!open)
+            db.prepare(`UPDATE transactions SET has_question = 0 WHERE id = ?`).run(target.transaction_id);
+    }
+    if (target.account_id) {
+        const open = db
+            .prepare(`SELECT 1 FROM questions WHERE account_id = ? LIMIT 1`)
+            .get(target.account_id);
+        if (!open)
+            db.prepare(`UPDATE accounts SET has_question = 0 WHERE id = ?`).run(target.account_id);
+    }
+}
+const ACTIVE_DEFERRED_CLAUSE = "(deferred_until IS NULL OR deferred_until <= datetime('now'))";
+export function countQuestions(db, scope = {}) {
+    const conditions = [];
+    const params = [];
+    if (scope.file_id) {
+        conditions.push("file_id = ?");
+        params.push(scope.file_id);
+    }
+    if (scope.transaction_id) {
+        conditions.push("transaction_id = ?");
+        params.push(scope.transaction_id);
+    }
+    if (scope.account_id) {
+        conditions.push("account_id = ?");
+        params.push(scope.account_id);
+    }
+    if (scope.kind) {
+        conditions.push("kind = ?");
+        params.push(scope.kind);
+    }
+    if (scope.batch_id) {
+        conditions.push("batch_id = ?");
+        params.push(scope.batch_id);
+    }
+    if (!scope.includeDeferred)
+        conditions.push(ACTIVE_DEFERRED_CLAUSE);
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM questions ${where}`)
+        .get(...params);
+    return row.n;
+}
+const ROW_COLUMNS = "id, batch_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, deferred_until, created_at";
+export function listQuestions(db, opts = {}) {
+    const capped = Math.min(Math.max(opts.limit ?? 200, 1), 1000);
+    const conditions = [];
+    const params = [];
+    if (opts.batchId) {
+        conditions.push("batch_id = ?");
+        params.push(opts.batchId);
+    }
+    if (!opts.includeDeferred)
+        conditions.push(ACTIVE_DEFERRED_CLAUSE);
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    params.push(capped);
+    return db.prepare(`SELECT ${ROW_COLUMNS}
+     FROM questions
+     ${where}
+     ORDER BY created_at ASC
+     LIMIT ?`).all(...params);
+}
+/**
+ * `listQuestions`/`countQuestions` hide deferred rows by default until the
+ * timestamp passes; pass `includeDeferred: true` for an unfiltered view.
+ */
+export function deferQuestion(db, id, days) {
+    const safeDays = Math.max(1, Math.floor(days));
+    const result = db
+        .prepare(`UPDATE questions SET deferred_until = datetime('now', ?) WHERE id = ?`)
+        .run(`+${safeDays} days`, id);
+    return result.changes > 0;
+}

package/dist/db/queries/transactions-dedup.js

@@ -0,0 +1,80 @@
+/**
+ * Rows sharing a non-null group_id never match each other (a salary's legs aren't
+ * duplicates); returns components of size >= 2.
+ */
+export function findDuplicateTransactions(db, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 2));
+    const minAmount = opts.minAmount ?? 0;
+    const rows = db
+        .prepare(`SELECT t.id, t.group_id, t.date, t.description, t.amount, t.currency,
+              t.source_file_id, t.merchant_id, t.debit_account_id, t.credit_account_id,
+              da.name AS debit_account_name, ca.name AS credit_account_name
+         FROM transactions t
+         LEFT JOIN accounts da ON da.id = t.debit_account_id
+         LEFT JOIN accounts ca ON ca.id = t.credit_account_id
+        WHERE t.void_of IS NULL`)
+        .all();
+    const buckets = new Map();
+    for (const r of rows) {
+        if (r.amount < minAmount)
+            continue;
+        const key = `${r.amount}|${r.debit_account_id}|${r.credit_account_id}`;
+        const arr = buckets.get(key) ?? [];
+        arr.push(r);
+        buckets.set(key, arr);
+    }
+    const groups = [];
+    for (const bucket of buckets.values()) {
+        if (bucket.length < 2)
+            continue;
+        for (const comp of proximityComponents(bucket, toleranceDays)) {
+            if (comp.length >= 2)
+                groups.push(comp);
+        }
+    }
+    return groups;
+}
+function proximityComponents(bucket, toleranceDays) {
+    const n = bucket.length;
+    const parent = Array.from({ length: n }, (_, i) => i);
+    const find = (x) => {
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+        }
+        return x;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[ra] = rb;
+    };
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const a = bucket[i];
+            const b = bucket[j];
+            if (dayDiff(a.date, b.date) > toleranceDays)
+                continue;
+            if (a.group_id && b.group_id && a.group_id === b.group_id)
+                continue;
+            union(i, j);
+        }
+    }
+    const comps = new Map();
+    for (let i = 0; i < n; i++) {
+        const root = find(i);
+        const arr = comps.get(root) ?? [];
+        arr.push(bucket[i]);
+        comps.set(root, arr);
+    }
+    return [...comps.values()];
+}
+/** Whole-day distance between two ISO dates; +Infinity on unparseable input. */
+function dayDiff(a, b) {
+    const aDate = Date.parse(a);
+    const bDate = Date.parse(b);
+    if (Number.isNaN(aDate) || Number.isNaN(bDate))
+        return Number.POSITIVE_INFINITY;
+    return Math.abs(Math.round((bDate - aDate) / 86_400_000));
+}