plasalid 0.4.1 → 0.5.0

package/dist/db/queries/merchants.js

@@ -0,0 +1,120 @@
+import { randomUUID } from "crypto";
+/**
+ * Strip the noise that PDF descriptors carry on top of a merchant identity:
+ * trailing store ids, terminal codes, city tags, transaction-type words. The
+ * normalized form is what `merchant_aliases.normalized_pattern` indexes, so
+ * "STARBUCKS #1234 BKK CHARGE" and "Starbucks #5678 BANGKOK" collapse to the
+ * same alias "starbucks".
+ */
+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(" ");
+}
+/**
+ * Upsert a merchant by canonical_name. Optionally upsert an alias and update
+ * the cached default_account_id. Idempotent: re-running with the same inputs
+ * does not duplicate rows. Designed to be called inside the same DB transaction
+ * as the posting writes 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(),
+        };
+    }
+    if (input.alias) {
+        const normalized = normalizeDescriptor(input.alias);
+        if (normalized) {
+            const existsAlias = db
+                .prepare(`SELECT 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);
+            }
+        }
+    }
+    return merchant;
+}
+/**
+ * Resolve a raw PDF descriptor to a known merchant via the alias table.
+ * Returns null if no alias matches. The scanner uses this in its pre-resolution
+ * pass so the LLM can skip re-categorizing already-seen merchants.
+ */
+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 where = opts.withDefaultOnly ? `WHERE m.default_account_id IS NOT NULL` : ``;
+    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
+     ${where}
+     ORDER BY m.canonical_name
+     LIMIT ?`).all(limit);
+}
+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 };
+}

package/dist/db/queries/recurrences.d.ts

@@ -6,7 +6,7 @@ export interface RecurrenceCandidate {
     amount: number;
     currency: string;
     side: "debit" | "credit";
-    entries: {
+    transactions: {
         id: string;
         date: string;
         description: string;
@@ -26,8 +26,8 @@ export interface RecordRecurrenceInput {
     frequency: RecurrenceFrequency;
     amount_typical?: number | null;
     currency?: string;
-    entry_ids: string[];
+    transaction_ids: string[];
     notes?: string | null;
 }
 export declare function recordRecurrence(db: Database.Database, input: RecordRecurrenceInput): string;
-export declare function linkEntryToRecurrence(db: Database.Database, entryId: string, recurrenceId: string): void;
+export declare function linkTransactionToRecurrence(db: Database.Database, transactionId: string, recurrenceId: string): void;

package/dist/db/queries/recurrences.js

@@ -1,24 +1,24 @@
 import { randomUUID } from "crypto";
-import { dayDiff } from "./journal.js";
+import { dayDiff } from "./transactions.js";
 export function findRecurrenceCandidates(db, opts = {}) {
     const minOccurrences = Math.max(2, opts.minOccurrences ?? 3);
-    const accountFilter = opts.accountId ? `AND jl.account_id = ?` : ``;
+    const accountFilter = opts.accountId ? `AND p.account_id = ?` : ``;
     const params = opts.accountId ? [opts.accountId] : [];
-    const rows = db.prepare(`SELECT jl.account_id,
+    const rows = db.prepare(`SELECT p.account_id,
             a.name AS account_name,
-            jl.currency,
-            CASE WHEN jl.debit > 0 THEN jl.debit ELSE jl.credit END AS amount,
-            CASE WHEN jl.debit > 0 THEN 'debit' ELSE 'credit' END AS side,
-            je.id AS entry_id,
-            je.date,
-            je.description
-     FROM journal_lines jl
-     JOIN journal_entries je ON je.id = jl.entry_id
-     JOIN accounts a ON a.id = jl.account_id
-     WHERE je.recurrence_id IS NULL
-       AND (jl.debit > 0 OR jl.credit > 0)
+            p.currency,
+            CASE WHEN p.debit > 0 THEN p.debit ELSE p.credit END AS amount,
+            CASE WHEN p.debit > 0 THEN 'debit' ELSE 'credit' END AS side,
+            t.id AS transaction_id,
+            t.date,
+            t.description
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     WHERE t.recurrence_id IS NULL
+       AND (p.debit > 0 OR p.credit > 0)
        ${accountFilter}
-     ORDER BY jl.account_id, jl.currency, amount, je.date`).all(...params);
+     ORDER BY p.account_id, p.currency, amount, t.date`).all(...params);
     const buckets = new Map();
     for (const r of rows) {
         const key = `${r.account_id}|${r.currency}|${Math.round(r.amount * 100)}|${r.side}`;
@@ -42,7 +42,7 @@ export function findRecurrenceCandidates(db, opts = {}) {
             amount: Math.round(bucket[0].amount * 100) / 100,
             currency: bucket[0].currency,
             side: bucket[0].side,
-            entries: bucket.map(r => ({ id: r.entry_id, date: r.date, description: r.description })),
+            transactions: bucket.map(r => ({ id: r.transaction_id, date: r.date, description: r.description })),
             median_days_between: median,
             implied_frequency: classifyFrequency(median),
         });
@@ -74,13 +74,13 @@ const FREQ_PERIOD_DAYS = {
     annually: 365,
 };
 export function recordRecurrence(db, input) {
-    if (!input.entry_ids || input.entry_ids.length === 0) {
-        throw new Error("recordRecurrence requires at least one entry_id.");
+    if (!input.transaction_ids || input.transaction_ids.length === 0) {
+        throw new Error("recordRecurrence requires at least one transaction_id.");
     }
-    const placeholders = input.entry_ids.map(() => "?").join(",");
-    const dateRows = db.prepare(`SELECT date FROM journal_entries WHERE id IN (${placeholders}) ORDER BY date ASC`).all(...input.entry_ids);
+    const placeholders = input.transaction_ids.map(() => "?").join(",");
+    const dateRows = db.prepare(`SELECT date FROM transactions WHERE id IN (${placeholders}) ORDER BY date ASC`).all(...input.transaction_ids);
     if (dateRows.length === 0) {
-        throw new Error("None of the supplied entry_ids exist.");
+        throw new Error("None of the supplied transaction_ids exist.");
     }
     const firstSeen = dateRows[0].date;
     const lastSeen = dateRows[dateRows.length - 1].date;
@@ -91,30 +91,28 @@ export function recordRecurrence(db, input) {
          (id, account_id, description, frequency, amount_typical, currency,
           first_seen_date, last_seen_date, next_expected_date, notes)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.account_id, input.description, input.frequency, input.amount_typical ?? null, input.currency || "THB", firstSeen, lastSeen, nextExpected, input.notes ?? null);
-        const updateEntry = db.prepare(`UPDATE journal_entries SET recurrence_id = ? WHERE id = ?`);
-        for (const entryId of input.entry_ids)
-            updateEntry.run(id, entryId);
+        const updateTx = db.prepare(`UPDATE transactions SET recurrence_id = ? WHERE id = ?`);
+        for (const transactionId of input.transaction_ids)
+            updateTx.run(id, transactionId);
     });
     tx();
     return id;
 }
-export function linkEntryToRecurrence(db, entryId, recurrenceId) {
+export function linkTransactionToRecurrence(db, transactionId, recurrenceId) {
     const recurrence = db
         .prepare(`SELECT frequency FROM recurrences WHERE id = ?`)
         .get(recurrenceId);
     if (!recurrence)
         throw new Error(`Recurrence ${recurrenceId} not found.`);
-    const entry = db
-        .prepare(`SELECT date FROM journal_entries WHERE id = ?`)
-        .get(entryId);
-    if (!entry)
-        throw new Error(`Entry ${entryId} not found.`);
+    const transaction = db
+        .prepare(`SELECT date FROM transactions WHERE id = ?`)
+        .get(transactionId);
+    if (!transaction)
+        throw new Error(`Transaction ${transactionId} not found.`);
     const tx = db.transaction(() => {
-        db.prepare(`UPDATE journal_entries SET recurrence_id = ? WHERE id = ?`).run(recurrenceId, entryId);
-        // Recompute first/last/next from the full member set so the recurrence
-        // metadata stays in sync after every attach.
+        db.prepare(`UPDATE transactions SET recurrence_id = ? WHERE id = ?`).run(recurrenceId, transactionId);
         const span = db
-            .prepare(`SELECT MIN(date) AS first, MAX(date) AS last FROM journal_entries WHERE recurrence_id = ?`)
+            .prepare(`SELECT MIN(date) AS first, MAX(date) AS last FROM transactions WHERE recurrence_id = ?`)
             .get(recurrenceId);
         const nextExpected = addDays(span.last, FREQ_PERIOD_DAYS[recurrence.frequency]);
         db.prepare(`UPDATE recurrences SET first_seen_date = ?, last_seen_date = ?, next_expected_date = ? WHERE id = ?`).run(span.first, span.last, nextExpected, recurrenceId);

package/dist/db/queries/search.d.ts

@@ -1,7 +1,8 @@
 import type Database from "libsql";
-import type { JournalLineRow } from "./journal.js";
+import type { PostingRow } from "./transactions.js";
 /**
- * Free-text search across journal entry descriptions, line memos, and account
- * names. Returns matching journal lines joined with account + entry metadata.
+ * Free-text search across transaction descriptions, posting memos, account
+ * names, and merchant canonical names. Returns matching postings joined with
+ * account + transaction + merchant metadata.
  */
-export declare function searchJournalLines(db: Database.Database, query: string, limit?: number): JournalLineRow[];
+export declare function searchPostings(db: Database.Database, query: string, limit?: number): PostingRow[];

package/dist/db/queries/search.js

@@ -1,19 +1,23 @@
 /**
- * Free-text search across journal entry descriptions, line memos, and account
- * names. Returns matching journal lines joined with account + entry metadata.
+ * Free-text search across transaction descriptions, posting memos, account
+ * names, and merchant canonical names. Returns matching postings joined with
+ * account + transaction + merchant metadata.
  */
-export function searchJournalLines(db, query, limit = 30) {
+export function searchPostings(db, query, limit = 30) {
     const needle = `%${query}%`;
     const capped = Math.min(Math.max(limit, 1), 200);
-    return db.prepare(`SELECT jl.id, jl.entry_id, jl.account_id, jl.debit, jl.credit, jl.currency, jl.memo,
+    return db.prepare(`SELECT p.id, p.transaction_id, p.account_id, p.debit, p.credit, p.currency, p.memo,
             a.name AS account_name, a.type AS account_type,
-            je.date AS entry_date, je.description AS entry_description
-     FROM journal_lines jl
-     JOIN journal_entries je ON je.id = jl.entry_id
-     JOIN accounts a ON a.id = jl.account_id
-     WHERE je.description LIKE ?
-        OR jl.memo LIKE ?
+            t.date AS transaction_date, t.description AS transaction_description,
+            m.canonical_name AS merchant_name
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     LEFT JOIN merchants m ON m.id = t.merchant_id
+     WHERE t.description LIKE ?
+        OR p.memo LIKE ?
         OR a.name LIKE ?
-     ORDER BY je.date DESC, je.id DESC
-     LIMIT ?`).all(needle, needle, needle, capped);
+        OR m.canonical_name LIKE ?
+     ORDER BY t.date DESC, t.id DESC
+     LIMIT ?`).all(needle, needle, needle, needle, capped);
 }

package/dist/db/queries/transactions.d.ts

@@ -0,0 +1,167 @@
+import type Database from "libsql";
+import { type MerchantUpsertInput } from "./merchants.js";
+export interface PostingInput {
+    account_id: string;
+    debit?: number;
+    credit?: number;
+    currency?: string;
+    memo?: string | null;
+    pii_flag?: boolean;
+}
+export interface TransactionInput {
+    /** Optional pre-assigned id. Used by the buffered-write path so concerns recorded mid-scan can reference the transaction before commit. */
+    id?: string;
+    date: string;
+    description: string;
+    source_file_id?: string | null;
+    source_page?: number | null;
+    raw_descriptor?: string | null;
+    merchant?: MerchantUpsertInput | null;
+    /** Pre-resolved merchant id (from scanner's alias pre-resolution pass). Overrides any `merchant` upsert when set. */
+    merchant_id?: string | null;
+    postings: PostingInput[];
+}
+export interface PostingRow {
+    id: string;
+    transaction_id: string;
+    account_id: string;
+    debit: number;
+    credit: number;
+    currency: string;
+    memo: string | null;
+    account_name?: string;
+    account_type?: string;
+    transaction_date?: string;
+    transaction_description?: string;
+    merchant_name?: string | null;
+}
+/**
+ * Insert a balanced transaction. Throws if SUM(debit) !== SUM(credit) or any
+ * posting both debits and credits. Transaction-wrapped: postings never land
+ * without a header, header never lands without postings.
+ */
+export declare function recordTransaction(db: Database.Database, input: TransactionInput): string;
+/**
+ * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
+ * both `recordTransaction` and the buffered-scan commit path; the latter
+ * already runs inside its own transaction and must not open another.
+ */
+export declare function validateTransaction(input: TransactionInput): TransactionInput & {
+    id: string;
+};
+/**
+ * Insert-only counterpart to `recordTransaction`. The caller is responsible
+ * for opening a transaction (or for accepting partial writes). Expects an
+ * already-validated input from `validateTransaction`.
+ */
+export declare function insertTransactionRows(db: Database.Database, input: TransactionInput & {
+    id: string;
+}): void;
+export interface ListPostingsOptions {
+    account_id?: string;
+    from?: string;
+    to?: string;
+    q?: string;
+    limit?: number;
+}
+export interface UpdateTransactionFields {
+    date?: string;
+    description?: string;
+    source_page?: number | null;
+}
+export declare function updateTransaction(db: Database.Database, transactionId: string, fields: UpdateTransactionFields): number;
+export interface UpdatePostingFields {
+    account_id?: string;
+    memo?: string | null;
+}
+/**
+ * Safe single-posting edits only. Refuses changes to `debit`, `credit`, or `currency`
+ * because those would silently break the transaction's balance — to fix amounts the
+ * caller must delete the transaction and record a fresh one.
+ */
+export declare function updatePosting(db: Database.Database, postingId: string, fields: UpdatePostingFields): number;
+/**
+ * Delete a transaction. ON DELETE CASCADE on `postings.transaction_id` removes
+ * the postings automatically.
+ */
+export declare function deleteTransaction(db: Database.Database, transactionId: string): number;
+export interface DuplicateGroupTransaction {
+    id: string;
+    date: string;
+    description: string;
+    amount: number;
+    account_ids: string[];
+    account_names: string[];
+}
+export interface FindDuplicateTransactionsOptions {
+    /** Days of slack when grouping by date. 0 means same-day only. Default 2. */
+    toleranceDays?: number;
+    /** Only consider transactions that have at least one posting on this account. */
+    accountId?: string;
+    /** Skip transactions whose total debit is below this value. */
+    minAmount?: number;
+}
+/**
+ * Heuristic duplicate finder: group transactions by (rounded total debit) and check
+ * pairs whose date difference is ≤ toleranceDays. Returns groups with ≥2 members.
+ * Each transaction carries both account_ids (for follow-up tool calls) and
+ * account_names (for human-readable presentation to the user).
+ */
+export declare function findDuplicateTransactions(db: Database.Database, opts?: FindDuplicateTransactionsOptions): DuplicateGroupTransaction[][];
+export declare function dayDiff(a: string, b: string): number;
+export interface CorrelatedTransactionPair {
+    amount: number;
+    currency: string;
+    day_gap: number;
+    a: {
+        id: string;
+        date: string;
+        description: string;
+        account_ids: string[];
+        account_names: string[];
+    };
+    b: {
+        id: string;
+        date: string;
+        description: string;
+        account_ids: string[];
+        account_names: string[];
+    };
+}
+export interface FindCorrelatedTransactionsOptions {
+    from?: string;
+    to?: string;
+    /** Max day difference between paired transactions. Default 3. */
+    toleranceDays?: number;
+    /** Skip transactions below this total debit. Default 0. */
+    minAmount?: number;
+}
+/**
+ * Heuristic: surface pairs of transactions that look like the same money movement
+ * recorded against different accounts (e.g. a bank-to-card transfer that lands
+ * once on the bank statement and again on the card statement). Filters out
+ * pairs whose account-id sets overlap (those are duplicates, not correlations).
+ */
+export declare function findCorrelatedTransactions(db: Database.Database, opts?: FindCorrelatedTransactionsOptions): CorrelatedTransactionPair[];
+export interface CorrelationCandidate {
+    id: string;
+    date: string;
+    description: string;
+    amount: number;
+    currency: string;
+    account_ids: string[];
+    account_names: string[];
+}
+/**
+ * Pure pair-finder: given an array of candidates already filtered by amount
+ * and equipped with account_ids/names, return the cross-pairs that look like
+ * the same money movement on different accounts (date within toleranceDays,
+ * same amount + currency, non-overlapping account sets).
+ *
+ * Used by the DB-backed `findCorrelatedTransactions` and by the scan-time
+ * coordinator that runs over buffered, not-yet-committed transactions.
+ */
+export declare function correlatePairs(candidates: CorrelationCandidate[], opts?: {
+    toleranceDays?: number;
+}): CorrelatedTransactionPair[];
+export declare function listPostings(db: Database.Database, opts?: ListPostingsOptions): PostingRow[];