ray-finance 0.4.0 → 0.4.2

package/dist/ai/agent.d.ts

@@ -7,4 +7,8 @@ export type ProgressCallback = (event: {
     toolCount: number;
     elapsedMs: number;
 }) => void;
-export declare function handleMessage(db: Database.Database, userMessage: string, onProgress?: ProgressCallback): Promise<string>;
+/** Thrown by handleMessage when the caller aborts via AbortSignal */
+export declare class AbortedError extends Error {
+    constructor();
+}
+export declare function handleMessage(db: Database.Database, userMessage: string, onProgress?: ProgressCallback, signal?: AbortSignal): Promise<string>;

package/dist/ai/agent.js

@@ -26,7 +26,14 @@ export const TOOL_LABELS = {
     save_memory: "Remembering that",
     update_context: "Updating your profile",
 };
-export async function handleMessage(db, userMessage, onProgress) {
+/** Thrown by handleMessage when the caller aborts via AbortSignal */
+export class AbortedError extends Error {
+    constructor() {
+        super("aborted");
+        this.name = "AbortedError";
+    }
+}
+export async function handleMessage(db, userMessage, onProgress, signal) {
     // Save incoming message
     saveMessage(db, "user", userMessage);
     // Load conversation context, truncated to fit token budget
@@ -55,7 +62,12 @@ export async function handleMessage(db, userMessage, onProgress) {
     const useThinking = config.thinkingBudget > 0
         && provider.supportsThinking
         && supportsThinking(config.model);
+    const throwIfAborted = () => {
+        if (signal?.aborted)
+            throw new AbortedError();
+    };
     try {
+        throwIfAborted();
         // Initial API call
         let response = await provider.sendMessage({
             model: config.model,
@@ -66,11 +78,13 @@ export async function handleMessage(db, userMessage, onProgress) {
             thinking: useThinking
                 ? { type: "enabled", budget_tokens: config.thinkingBudget }
                 : undefined,
+            signal,
         });
         // Agentic tool loop
         const startTime = Date.now();
         let toolCount = 0;
         while (response.stopReason === "tool_use" && toolCount < MAX_TOOL_STEPS) {
+            throwIfAborted();
             messages.push({ role: "assistant", content: response.content });
             const toolResults = [];
             for (const block of response.content) {
@@ -97,6 +111,7 @@ export async function handleMessage(db, userMessage, onProgress) {
                 toolCount,
                 elapsedMs: Date.now() - startTime,
             });
+            throwIfAborted();
             response = await provider.sendMessage({
                 model: config.model,
                 maxTokens: useThinking ? 16000 : 4096,
@@ -106,6 +121,7 @@ export async function handleMessage(db, userMessage, onProgress) {
                 thinking: useThinking
                     ? { type: "enabled", budget_tokens: config.thinkingBudget }
                     : undefined,
+                signal,
             });
         }
         // Extract text response, restore PII for display
@@ -116,6 +132,9 @@ export async function handleMessage(db, userMessage, onProgress) {
         return responseText || "I looked into that but couldn't formulate a response. Could you try rephrasing?";
     }
     catch (error) {
+        if (error instanceof AbortedError || error?.name === "AbortError" || signal?.aborted) {
+            throw new AbortedError();
+        }
         if (error.status === 403) {
             if (useManaged()) {
                 return "Your API key was rejected. This usually means your subscription is inactive. Run `ray billing` to check your payment status, or `ray setup` to reconfigure.";

package/dist/ai/insights.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { getNetWorth, getAccountBalances, getDebts, getBudgetStatuses, getGoals, compareSpending, formatMoney, categoryLabel, } from "../queries/index.js";
 import { getLatestScore } from "../scoring/index.js";
+import { getUpcomingBills } from "../db/bills.js";
 const MAX_CHARS = 6000;
 export function computeInsights(db) {
     // Fresh install guard
@@ -138,35 +139,14 @@ function buildGoals(db) {
 }
 function buildUpcoming(db) {
     const parts = [];
-    // Recurring bills due in next 7 days
-    const now = new Date();
-    const todayDay = now.getDate();
-    const daysInMonth = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
-    const endDay = todayDay + 7;
-    let bills = [];
-    if (endDay <= daysInMonth) {
-        bills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, endDay);
-    }
-    else {
-        // Wraparound: rest of this month + start of next
-        const thisMonthBills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, daysInMonth);
-        const nextMonthBills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN 1 AND ?`).all(endDay - daysInMonth);
-        bills = [...thisMonthBills, ...nextMonthBills];
-    }
-    // Also handle bills on day 31 in shorter months
-    if (daysInMonth < 31) {
-        const endOfMonthBills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month > ? AND day_of_month NOT IN (SELECT day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?)`).all(daysInMonth, todayDay + 1, Math.min(endDay, daysInMonth));
-        // These bills fall on the last day of the month
-        if (daysInMonth >= todayDay + 1 && daysInMonth <= endDay) {
-            bills.push(...endOfMonthBills);
-        }
-    }
+    const bills = getUpcomingBills(db, 7);
+    const today = startOfUtcDay(new Date());
     if (bills.length > 0) {
         const billStrs = bills.slice(0, 5).map(b => {
-            const daysUntil = b.day_of_month > todayDay
-                ? b.day_of_month - todayDay
-                : daysInMonth - todayDay + b.day_of_month;
-            return `${b.name} (${formatMoney(b.amount)}) due in ${daysUntil} days`;
+            const daysUntil = Math.round((b.date.getTime() - today.getTime()) / 86400000);
+            const amt = formatMoney(b.amount);
+            const extra = b.note ? ` ${b.note}` : "";
+            return `${b.name} (${amt}${extra}) due in ${daysUntil} days`;
         });
         parts.push(`UPCOMING: ${billStrs.join(", ")}`);
     }
@@ -318,21 +298,12 @@ export function cliBriefing(db) {
         }
     }
     // Upcoming bills
-    const todayDay = now.getDate();
-    const endDay = todayDay + 7;
-    let bills = [];
-    if (endDay <= daysInMonth) {
-        bills = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, endDay);
-    }
-    else {
-        const a = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN ? AND ?`).all(todayDay + 1, daysInMonth);
-        const b = db.prepare(`SELECT name, amount, day_of_month FROM recurring_bills WHERE day_of_month BETWEEN 1 AND ?`).all(endDay - daysInMonth);
-        bills = [...a, ...b];
-    }
+    const bills = getUpcomingBills(db, 7);
     if (bills.length > 0) {
         lines.push("");
+        const today = startOfUtcDay(new Date());
         const billStrs = bills.slice(0, 3).map(b => {
-            const daysUntil = b.day_of_month > todayDay ? b.day_of_month - todayDay : daysInMonth - todayDay + b.day_of_month;
+            const daysUntil = Math.round((b.date.getTime() - today.getTime()) / 86400000);
             return chalk.dim(`${b.name} ${fmtMoney(b.amount)}`) + chalk.dim(` in ${daysUntil}d`);
         });
         lines.push(`  ${chalk.dim("upcoming")}  ${billStrs.join(chalk.dim("  ·  "))}`);
@@ -357,6 +328,9 @@ export function cliBriefing(db) {
 function fmtMoney(n) {
     return "$" + Math.abs(n).toLocaleString("en-US", { minimumFractionDigits: 0, maximumFractionDigits: 0 });
 }
+function startOfUtcDay(d) {
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+}
 function miniBar(pct) {
     const width = 8;
     const clamped = Math.max(0, Math.min(100, pct));

package/dist/ai/provider.d.ts

@@ -50,6 +50,7 @@ export interface SendMessageParams {
         type: "enabled";
         budget_tokens: number;
     };
+    signal?: AbortSignal;
 }
 export interface Provider {
     name: string;

package/dist/ai/providers/anthropic.js

@@ -17,7 +17,9 @@ export function createAnthropicProvider(opts) {
             if (params.thinking) {
                 apiParams.thinking = params.thinking;
             }
-            const response = await client.messages.create(apiParams);
+            const response = await client.messages.create(apiParams, {
+                signal: params.signal,
+            });
             // Filter thinking blocks and normalize content
             const content = [];
             for (const block of response.content) {

package/dist/ai/providers/openai-compat.js

@@ -19,7 +19,7 @@ export function createOpenAICompatibleProvider(opts) {
                     max_tokens: params.maxTokens,
                     messages,
                     tools: tools.length > 0 ? tools : undefined,
-                });
+                }, { signal: params.signal });
             }
             catch (e) {
                 if (e.status === 400 && e.message?.includes("max_tokens")) {
@@ -28,7 +28,7 @@ export function createOpenAICompatibleProvider(opts) {
                         max_completion_tokens: params.maxTokens,
                         messages,
                         tools: tools.length > 0 ? tools : undefined,
-                    });
+                    }, { signal: params.signal });
                 }
                 else {
                     throw e;

package/dist/apple-import.d.ts

@@ -0,0 +1,53 @@
+import type BetterSqlite3 from "libsql";
+type Database = BetterSqlite3.Database;
+export interface AppleImportOptions {
+    csvPath: string;
+    balance?: number;
+    limit?: number;
+    replaceRange?: boolean;
+    dryRun?: boolean;
+}
+export interface AppleImportResult {
+    accountId: string;
+    accountCreated: boolean;
+    rowsParsed: number;
+    rowsInserted: number;
+    rowsSkipped: number;
+    rowsDeleted: number;
+    warnings: string[];
+    dateRange: {
+        first: string;
+        last: string;
+    } | null;
+    balance: number | null;
+}
+interface ParsedRow {
+    transactionDate: string;
+    description: string;
+    merchant: string;
+    category: string;
+    type: string;
+    amount: number;
+}
+/** Parse RFC 4180 CSV: handles quoted fields, embedded commas, and escaped quotes ("") */
+export declare function parseCsv(text: string): string[][];
+/** Parse CSV text. Returns parsed rows + warnings for malformed rows. Throws on bad header. */
+export declare function parseAppleCsv(text: string): {
+    rows: ParsedRow[];
+    warnings: string[];
+    replaceWindow: {
+        first: string;
+        last: string;
+    } | null;
+};
+/** True if the Apple Card account row already exists in the DB */
+export declare function appleAccountExists(db: Database): boolean;
+/** Returns the current balance of the Apple Card account, or null if it doesn't exist */
+export declare function getAppleAccountBalance(db: Database): number | null;
+/** Returns the current credit limit of the Apple Card account, or null if unset */
+export declare function getAppleAccountLimit(db: Database): number | null;
+/** Count of existing Apple Card rows within a date range (for --replace-range preview) */
+export declare function countAppleRowsInRange(db: Database, first: string, last: string): number;
+/** Run the import end-to-end. Returns a result struct for the CLI layer to format. */
+export declare function runAppleImport(db: Database, opts: AppleImportOptions): AppleImportResult;
+export {};

package/dist/apple-import.js

@@ -0,0 +1,372 @@
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+const INSTITUTION_ID = "manual-apple";
+const INSTITUTION_NAME = "Apple";
+const ACCOUNT_ID = "manual-apple-card";
+const ACCOUNT_NAME = "Apple Card";
+const EXPECTED_HEADER = [
+    "Transaction Date",
+    "Clearing Date",
+    "Description",
+    "Merchant",
+    "Category",
+    "Type",
+    "Amount (USD)",
+    "Purchased By",
+];
+// Apple exports Title Case categories; Ray's scoring and spending queries expect
+// Plaid UPPERCASE_SNAKE_CASE codes. Mapping here so Apple transactions participate
+// in restaurant/shopping counts, budget checks, and spending totals.
+const CATEGORY_MAP = {
+    Restaurants: { category: "FOOD_AND_DRINK", subcategory: "FOOD_AND_DRINK_RESTAURANT" },
+    Grocery: { category: "FOOD_AND_DRINK", subcategory: "FOOD_AND_DRINK_GROCERIES" },
+    Alcohol: { category: "FOOD_AND_DRINK", subcategory: "FOOD_AND_DRINK_ALCOHOL_AND_BARS" },
+    Shopping: { category: "GENERAL_MERCHANDISE", subcategory: null },
+    Gas: { category: "TRANSPORTATION", subcategory: "TRANSPORTATION_GAS" },
+    Transportation: { category: "TRANSPORTATION", subcategory: null },
+    Tolls: { category: "TRANSPORTATION", subcategory: "TRANSPORTATION_TOLLS" },
+    Airlines: { category: "TRAVEL", subcategory: "TRAVEL_FLIGHTS" },
+    Hotels: { category: "TRAVEL", subcategory: "TRAVEL_LODGING" },
+    Entertainment: { category: "ENTERTAINMENT", subcategory: null },
+    Medical: { category: "MEDICAL", subcategory: null },
+    Utilities: { category: "RENT_AND_UTILITIES", subcategory: null },
+    "Govt-services-parking": { category: "GOVERNMENT_AND_NON_PROFIT", subcategory: null },
+    // Payment (negative): card payment from your bank. Mapped to TRANSFER_IN
+    // because Ray's income queries (getIncome, getCashFlow*, compareSpending)
+    // exclude only TRANSFER_IN from `amount < 0`-as-income — LOAN_PAYMENTS would
+    // be counted as income and inflate cash-flow numbers. The corresponding
+    // outflow on the bank account will appear as TRANSFER_OUT via Plaid.
+    Payment: { category: "TRANSFER_IN", subcategory: null },
+    // Installment (positive): Apple Card monthly financing charge (e.g., iPhone).
+    // Amortization of a prior purchase, not new spending — LOAN_PAYMENTS keeps it
+    // out of total-spend aggregation.
+    Installment: { category: "LOAN_PAYMENTS", subcategory: null },
+    // Credit (negative): a refund. Without mapping, queries/index.ts would count
+    // it as income. TRANSFER_IN excludes it from income totals.
+    Credit: { category: "TRANSFER_IN", subcategory: null },
+    Other: { category: null, subcategory: null },
+};
+const TYPE_LABELS = {
+    Payment: "transfer",
+    Credit: "refund",
+    Installment: "installment",
+};
+/** Parse RFC 4180 CSV: handles quoted fields, embedded commas, and escaped quotes ("") */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let inQuotes = false;
+    let i = 0;
+    // Strip BOM if present
+    if (text.charCodeAt(0) === 0xfeff)
+        i = 1;
+    while (i < text.length) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i++;
+                continue;
+            }
+            field += c;
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            inQuotes = true;
+            i++;
+            continue;
+        }
+        if (c === ",") {
+            row.push(field);
+            field = "";
+            i++;
+            continue;
+        }
+        if (c === "\r") {
+            i++;
+            continue;
+        }
+        if (c === "\n") {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+            i++;
+            continue;
+        }
+        field += c;
+        i++;
+    }
+    // Final field / row (no trailing newline)
+    if (field.length > 0 || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+function parseDate(mdy) {
+    const m = mdy.match(/^(\d{2})\/(\d{2})\/(\d{4})$/);
+    if (!m)
+        return null;
+    return `${m[3]}-${m[1]}-${m[2]}`;
+}
+function parseAmount(s) {
+    const n = parseFloat(s);
+    return isNaN(n) ? null : n;
+}
+function transactionId(date, amount, merchant, occurrence) {
+    const key = `${date}|${amount}|${merchant}|${occurrence}`;
+    return "apple-" + createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+/**
+ * Assigns a stable occurrence index to rows sharing the same (date, amount, merchant).
+ * Without this, genuinely separate same-day same-merchant same-amount transactions
+ * (e.g. two $2.40 subway swipes) would collapse into one via hash collision.
+ *
+ * Stability requirement: the same CSV exported twice must produce the same indices
+ * so re-imports stay idempotent. We sort rows by every field before numbering so
+ * the order doesn't depend on Apple's export order.
+ */
+function assignOccurrenceIndices(rows) {
+    const sorted = [...rows].sort((a, b) => {
+        if (a.transactionDate !== b.transactionDate)
+            return a.transactionDate < b.transactionDate ? -1 : 1;
+        if (a.amount !== b.amount)
+            return a.amount - b.amount;
+        if (a.merchant !== b.merchant)
+            return a.merchant < b.merchant ? -1 : 1;
+        if (a.description !== b.description)
+            return a.description < b.description ? -1 : 1;
+        if (a.category !== b.category)
+            return a.category < b.category ? -1 : 1;
+        if (a.type !== b.type)
+            return a.type < b.type ? -1 : 1;
+        return 0;
+    });
+    const counts = {};
+    return sorted.map(r => {
+        const key = `${r.transactionDate}|${r.amount}|${r.merchant}`;
+        const occurrence = counts[key] ?? 0;
+        counts[key] = occurrence + 1;
+        return { ...r, occurrence };
+    });
+}
+function mapCategory(appleCat) {
+    return CATEGORY_MAP[appleCat] ?? { category: null, subcategory: null };
+}
+/** Parse CSV text. Returns parsed rows + warnings for malformed rows. Throws on bad header. */
+export function parseAppleCsv(text) {
+    const raw = parseCsv(text);
+    if (raw.length === 0)
+        throw new Error("CSV file is empty.");
+    const header = raw[0];
+    const headerMismatch = header.length !== EXPECTED_HEADER.length ||
+        EXPECTED_HEADER.some((col, i) => header[i] !== col);
+    if (headerMismatch) {
+        throw new Error(`This doesn't look like an Apple Card CSV export.\n` +
+            `  Expected columns: ${EXPECTED_HEADER.join(", ")}\n` +
+            `  Got:              ${header.join(", ")}\n` +
+            `  Export from https://card.apple.com/ (the web portal, not the Wallet app).`);
+    }
+    const rows = [];
+    const warnings = [];
+    // Every row whose Transaction Date parsed, including rows later skipped for
+    // bad amount/columns. `--replace-range` must delete across the *full* CSV
+    // window — narrowing to surviving rows would leave stale rows at the edges
+    // when a boundary row has a bad amount.
+    const allParsedDates = [];
+    for (let i = 1; i < raw.length; i++) {
+        const r = raw[i];
+        if (r.length === 1 && r[0] === "")
+            continue;
+        // Parse date first — recorded in allParsedDates regardless of later
+        // column/amount failures, so --replace-range covers the full CSV window
+        // even when a boundary row has too few columns.
+        const date = r.length >= 1 ? parseDate(r[0]) : null;
+        if (date)
+            allParsedDates.push(date);
+        if (r.length < EXPECTED_HEADER.length) {
+            warnings.push(`Row ${i + 1}: expected ${EXPECTED_HEADER.length} columns, got ${r.length} — skipped`);
+            continue;
+        }
+        if (!date) {
+            warnings.push(`Row ${i + 1}: unparseable Transaction Date "${r[0]}" — skipped`);
+            continue;
+        }
+        const amount = parseAmount(r[6]);
+        if (amount === null) {
+            warnings.push(`Row ${i + 1}: unparseable Amount "${r[6]}" — skipped`);
+            continue;
+        }
+        rows.push({
+            transactionDate: date,
+            description: r[2],
+            merchant: r[3],
+            category: r[4],
+            type: r[5],
+            amount,
+        });
+    }
+    let replaceWindow = null;
+    if (allParsedDates.length > 0) {
+        const sorted = [...allParsedDates].sort();
+        replaceWindow = { first: sorted[0], last: sorted[sorted.length - 1] };
+    }
+    return { rows, warnings, replaceWindow };
+}
+/** True if the Apple Card account row already exists in the DB */
+export function appleAccountExists(db) {
+    return Boolean(db.prepare(`SELECT 1 FROM accounts WHERE account_id = ?`).get(ACCOUNT_ID));
+}
+/** Returns the current balance of the Apple Card account, or null if it doesn't exist */
+export function getAppleAccountBalance(db) {
+    const r = db.prepare(`SELECT current_balance FROM accounts WHERE account_id = ?`).get(ACCOUNT_ID);
+    return r?.current_balance ?? null;
+}
+/** Returns the current credit limit of the Apple Card account, or null if unset */
+export function getAppleAccountLimit(db) {
+    const r = db.prepare(`SELECT balance_limit FROM accounts WHERE account_id = ?`).get(ACCOUNT_ID);
+    return r?.balance_limit ?? null;
+}
+/** Count of existing Apple Card rows within a date range (for --replace-range preview) */
+export function countAppleRowsInRange(db, first, last) {
+    const r = db
+        .prepare(`SELECT COUNT(*) as n FROM transactions WHERE account_id = ? AND date BETWEEN ? AND ?`)
+        .get(ACCOUNT_ID, first, last);
+    return r.n;
+}
+/** Run the import end-to-end. Returns a result struct for the CLI layer to format. */
+export function runAppleImport(db, opts) {
+    const text = readFileSync(opts.csvPath, "utf-8");
+    const { rows, warnings, replaceWindow } = parseAppleCsv(text);
+    if (rows.length === 0) {
+        return {
+            accountId: ACCOUNT_ID,
+            accountCreated: false,
+            rowsParsed: 0,
+            rowsInserted: 0,
+            rowsSkipped: 0,
+            rowsDeleted: 0,
+            warnings,
+            dateRange: null,
+            balance: null,
+        };
+    }
+    const dates = rows.map(r => r.transactionDate).sort();
+    const first = dates[0];
+    const last = dates[dates.length - 1];
+    const replaceFirst = replaceWindow?.first ?? first;
+    const replaceLast = replaceWindow?.last ?? last;
+    if (opts.dryRun) {
+        const rowsDeletedPreview = opts.replaceRange ? countAppleRowsInRange(db, replaceFirst, replaceLast) : 0;
+        // With --replace-range, every CSV row is a fresh insert (the prior rows are
+        // deleted first). Without it, count which transaction_ids already exist so
+        // the user sees a real would-insert vs would-skip breakdown — the whole
+        // point of --dry-run.
+        let wouldInsert = rows.length;
+        let wouldSkip = 0;
+        if (!opts.replaceRange) {
+            const exists = db.prepare(`SELECT 1 FROM transactions WHERE transaction_id = ?`);
+            const indexed = assignOccurrenceIndices(rows);
+            wouldInsert = 0;
+            for (const row of indexed) {
+                const id = transactionId(row.transactionDate, row.amount, row.merchant, row.occurrence);
+                if (exists.get(id))
+                    wouldSkip++;
+                else
+                    wouldInsert++;
+            }
+        }
+        return {
+            accountId: ACCOUNT_ID,
+            accountCreated: !appleAccountExists(db),
+            rowsParsed: rows.length,
+            rowsInserted: wouldInsert,
+            rowsSkipped: wouldSkip,
+            rowsDeleted: rowsDeletedPreview,
+            warnings,
+            dateRange: { first, last },
+            balance: opts.balance ?? getAppleAccountBalance(db),
+        };
+    }
+    const accountCreated = !appleAccountExists(db);
+    let rowsDeleted = 0;
+    let rowsInserted = 0;
+    let rowsSkipped = 0;
+    const insertInst = db.prepare(`INSERT INTO institutions (item_id, access_token, name, products)
+     VALUES (?, 'manual', ?, '[]')
+     ON CONFLICT(item_id) DO NOTHING`);
+    const insertAcc = db.prepare(`INSERT INTO accounts (account_id, item_id, name, type, subtype, currency, current_balance, balance_limit, updated_at)
+     VALUES (?, ?, ?, 'credit', 'credit card', 'USD', ?, ?, datetime('now'))
+     ON CONFLICT(account_id) DO UPDATE SET
+       current_balance = COALESCE(excluded.current_balance, current_balance),
+       balance_limit   = COALESCE(excluded.balance_limit, balance_limit),
+       updated_at      = datetime('now')`);
+    // Derive available_balance = limit - current_balance after the upsert resolves
+    // both fields (so re-runs that omit one of --balance/--limit still produce a
+    // correct value using the prior stored side). Without this, ai/insights.ts
+    // skips the card from utilization (it requires available_balance IS NOT NULL).
+    const updateAvailable = db.prepare(`UPDATE accounts
+     SET available_balance = balance_limit - current_balance
+     WHERE account_id = ?
+       AND balance_limit IS NOT NULL
+       AND current_balance IS NOT NULL`);
+    // Mirror the resolved balance into the liabilities table. getDebts() uses
+    // liabilities as the authoritative source (with rate/min payment/due date)
+    // for any account_id it covers, and falls through to accounts only for
+    // account_ids not in liabilities. Without this upsert, Apple Card debt would
+    // appear only in the fallback path without rate/min-payment metadata.
+    // type='credit' matches Plaid's syncLiabilities convention (src/plaid/sync.ts)
+    // — keeps debt-view labels consistent across import sources.
+    const upsertLiability = db.prepare(`INSERT INTO liabilities (account_id, type, current_balance, updated_at)
+     SELECT ?, 'credit', current_balance, datetime('now')
+     FROM accounts WHERE account_id = ? AND current_balance IS NOT NULL
+     ON CONFLICT(account_id, type) DO UPDATE SET
+       current_balance = excluded.current_balance,
+       updated_at      = datetime('now')`);
+    const deleteRange = db.prepare(`DELETE FROM transactions WHERE account_id = ? AND date BETWEEN ? AND ?`);
+    const insertTx = db.prepare(`INSERT OR IGNORE INTO transactions
+       (transaction_id, account_id, amount, date, name, merchant_name, category, subcategory,
+        pending, iso_currency_code, payment_channel, label, note)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, 'USD', NULL, ?, NULL)`);
+    const work = db.transaction(() => {
+        insertInst.run(INSTITUTION_ID, INSTITUTION_NAME);
+        insertAcc.run(ACCOUNT_ID, INSTITUTION_ID, ACCOUNT_NAME, opts.balance ?? null, opts.limit ?? null);
+        updateAvailable.run(ACCOUNT_ID);
+        upsertLiability.run(ACCOUNT_ID, ACCOUNT_ID);
+        if (opts.replaceRange) {
+            const info = deleteRange.run(ACCOUNT_ID, replaceFirst, replaceLast);
+            rowsDeleted = Number(info.changes);
+        }
+        const indexed = assignOccurrenceIndices(rows);
+        for (const row of indexed) {
+            const mapping = mapCategory(row.category);
+            const id = transactionId(row.transactionDate, row.amount, row.merchant, row.occurrence);
+            const label = TYPE_LABELS[row.type] ?? null;
+            const info = insertTx.run(id, ACCOUNT_ID, row.amount, row.transactionDate, row.description || row.merchant, row.merchant || null, mapping.category, mapping.subcategory, label);
+            if (Number(info.changes) === 1)
+                rowsInserted++;
+            else
+                rowsSkipped++;
+        }
+    });
+    work();
+    return {
+        accountId: ACCOUNT_ID,
+        accountCreated,
+        rowsParsed: rows.length,
+        rowsInserted,
+        rowsSkipped,
+        rowsDeleted,
+        warnings,
+        dateRange: { first, last },
+        balance: opts.balance ?? getAppleAccountBalance(db),
+    };
+}

package/dist/cli/chat.d.ts

@@ -1 +1,5 @@
+/**
+ * Pre-mount orchestration: banner, briefing, account check + optional runLink,
+ * then hand off to the Ink-rendered ChatApp.
+ */
 export declare function startChat(): Promise<void>;