ray-finance 0.3.0 → 0.3.2

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src=".github/ray-logo.png" alt="Ray" width="120" />
+  <img src=".github/ray-logo.png" alt="Ray" width="108" />
 </p>
 
 <p align="center">
@@ -14,40 +14,17 @@
 
 <br />
 
-```
-  Friday, Mar 28
-
-  net worth  $45,230 +$120
-
-  spending   $2,340 this month · $340 less vs last month
-             Dining -$114  ·  Shopping -$142  ·  Groceries -$73
-
-  ▓▓▓▓▓▓▓░  Dining 92%
-
-  ▓▓▓▓░░░░  Emergency fund $18,200/$40,000
-
-  upcoming   Netflix $16 in 3d  ·  Comcast $142 in 6d
-
-  score      72/100  ·  5d no dining  ·  3d on pace
-
-  ──────────────────────────────────────────────────
-
-  ❯ if I quit my job to freelance, how long can I survive?
-
-  Based on your last 3 months: you burn $4,820/mo after
-  fixed costs. With $18,200 in savings, that's
-  3.8 months of runway at current spend.
-
-  Cut dining and shopping to last-month levels and
-  you stretch to 5.1 months. Land one $8k contract
-  in that window and you never dip below $10k.
-```
+<p align="center">
+  <img src=".github/ray-demo.png" alt="Ray demo" />
+</p>
 
 Open Ray and it shows your net worth, spending vs last month, budget pacing, and upcoming bills — before you type a word. Ask a question and it answers from your real data, not guesses. Local-first. Encrypted. Open source.
 
 ## Features
 
 - **It already knows** — Every conversation starts with a real-time financial briefing. Net worth, spending velocity, budget alerts, goal pace, upcoming bills, and your daily score. No "let me look that up."
+- **Persistent context** — Ray maintains a financial profile that evolves with you: income, goals, strategy, key decisions, and open items. It updates this context as your situation changes, so every conversation picks up where the last one left off.
+- **Long-term memory** — Important details from conversations are saved as memories. Mention you're saving for a house or switching jobs and Ray remembers — without you repeating yourself.
 - **Bank sync via Plaid** — Connect checking, savings, credit cards, investments, and loans
 - **Encrypted local database** — All data stays on your machine in an AES-256 encrypted SQLite database
 - **Daily scoring** — A 0-100 behavior score with streaks and 14 unlockable achievements. No restaurants for a week? That's Kitchen Hero. Five zero-spend days? Monk Mode.
@@ -65,6 +42,26 @@ Open Ray and it shows your net worth, spending vs last month, budget pacing, and
 npm install -g ray-finance
 ```
 
+## Try It
+
+Explore Ray with realistic fake data — no bank accounts needed.
+
+```bash
+ray demo                # seed a demo database
+ray --demo status       # financial overview
+ray --demo accounts     # linked accounts with balances
+ray --demo spending     # spending breakdown by category
+ray --demo budgets      # budget tracking
+ray --demo goals        # financial goal progress
+ray --demo score        # daily score, streaks, achievements
+ray --demo alerts       # financial alerts
+ray --demo transactions # recent transactions
+```
+
+The dashboard commands work with no setup at all. To also try the AI chat with demo data, run `ray setup` first and add an [Anthropic API key](https://console.anthropic.com) or Ray API key — then `ray --demo` will start an interactive session where you can ask questions about the fake portfolio.
+
+When you're ready to connect real accounts, run `ray link`.
+
 ## Quick Start
 
 ```bash
@@ -98,6 +95,8 @@ Run `ray --help` to see all available commands.
 | Command | Description |
 |---------|-------------|
 | `ray` | Interactive AI chat with your financial advisor |
+| `ray demo` | Seed a demo database with realistic fake data |
+| `ray --demo <cmd>` | Run any command against demo data |
 | `ray setup` | Configure API keys and preferences |
 | `ray link` | Connect a new bank account |
 | `ray sync` | Pull latest transactions and balances |
@@ -155,6 +154,7 @@ Ray stores everything in `~/.ray/`:
   context.md           # Persistent financial context for AI
   data/
     finance.db         # Encrypted SQLite database
+    demo.db            # Demo database (created by `ray demo`)
   sync.log             # Daily sync output
 ```
 
@@ -174,6 +174,7 @@ RAY_API_KEY=           # Ray API key (managed mode, replaces the above)
 
 ## Roadmap
 
+- [ ] Bring your own model — use any LLM provider (OpenAI, Ollama, open-source models, etc.)
 - [ ] Daily digest email — morning summary of your finances
 
 Have an idea? [Open a PR](https://github.com/cdinnison/ray-finance/pulls).

package/dist/cli/commands.d.ts

@@ -11,4 +11,6 @@ export declare function showSpending(period?: string): Promise<void>;
 export declare function showBudgets(): void;
 export declare function showGoals(): void;
 export declare function showScore(): void;
+export declare function runAdd(): Promise<void>;
+export declare function runRemove(): Promise<void>;
 export declare function showAlerts(): void;

package/dist/cli/commands.js

@@ -5,6 +5,7 @@ import { getLatestScore, getAchievements, getMonthlySavings } from "../scoring/i
 import { generateAlerts } from "../alerts/index.js";
 import { runDailySync } from "../daily-sync.js";
 import { startLinkServer } from "../server.js";
+import { addManualAccount, getManualAccounts, removeManualAccount, scrapeRedfinEstimate } from "../property.js";
 import { heading, progressBar, formatMoney, formatMoneyColored, dim, formatDuration, formatError, renderLogo, institutionName } from "./format.js";
 export async function runSync() {
     const ora = (await import("ora")).default;
@@ -26,6 +27,7 @@ export async function runSync() {
 export async function runLink() {
     const open = (await import("open")).default;
     const ora = (await import("ora")).default;
+    const readline = await import("readline");
     const { url, waitForComplete, stop } = startLinkServer();
     console.log(`\n${heading("Link Account")}\n`);
     console.log(`Opening Plaid Link in your browser...\n`);
@@ -35,6 +37,37 @@ export async function runLink() {
     await waitForComplete();
     stop();
     spinner.succeed("Bank account linked successfully!");
+    // Check if a mortgage was linked and we don't already have a property account
+    const db = getDb();
+    const hasMortgage = db.prepare(`SELECT 1 FROM accounts WHERE type = 'loan' AND subtype = 'mortgage' LIMIT 1`).get();
+    const hasProperty = db.prepare(`SELECT 1 FROM accounts WHERE type = 'other' AND subtype = 'property' LIMIT 1`).get();
+    if (hasMortgage && !hasProperty) {
+        console.log(`\n${dim("Mortgage detected.")} Track your home value for accurate net worth.`);
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+        const listingUrl = (await ask(`${dim("Paste a Redfin URL (or press Enter to skip):")} `)).trim();
+        if (listingUrl) {
+            const name = (await ask(`${dim("Name (e.g. Primary Residence):")} `)).trim() || "Primary Residence";
+            rl.close();
+            const propSpinner = ora("Fetching home value...").start();
+            try {
+                const value = await scrapeRedfinEstimate(listingUrl);
+                if (value) {
+                    addManualAccount(db, name, "asset", value, listingUrl);
+                    propSpinner.succeed(`${name}: ${rawFormatMoney(value)} — updates automatically on sync.`);
+                }
+                else {
+                    propSpinner.fail("Could not determine home value from that URL. Try 'ray add' later.");
+                }
+            }
+            catch {
+                propSpinner.fail("Failed to fetch home value. Try 'ray add' later.");
+            }
+        }
+        else {
+            rl.close();
+        }
+    }
 }
 export async function showAccounts() {
     const db = getDb();
@@ -239,6 +272,108 @@ export function showScore() {
     }
     console.log();
 }
+export async function runAdd() {
+    const ora = (await import("ora")).default;
+    const inquirer = (await import("inquirer")).default;
+    const db = getDb();
+    const theme = {
+        prefix: { idle: " ", done: chalk.green(" ✓") },
+        style: { highlight: (text) => chalk.yellowBright(text) },
+    };
+    console.log(`\n${heading("Add Account")}`);
+    console.log(dim("  Track something not linked via Plaid — a home, car, crypto, loan, etc.\n"));
+    const { name } = await inquirer.prompt([{ theme,
+            type: "input",
+            name: "name",
+            message: "Name",
+            validate: (v) => v.trim() ? true : "Required",
+        }]);
+    const { type } = await inquirer.prompt([{ theme,
+            type: "list",
+            name: "type",
+            message: "Type",
+            choices: [
+                { name: "Asset — something you own (adds to net worth)", value: "asset" },
+                { name: "Liability — something you owe (subtracts from net worth)", value: "liability" },
+            ],
+        }]);
+    let finalBalance = 0;
+    let listingUrl;
+    // For assets: offer Redfin auto-tracking
+    if (type === "asset") {
+        const { redfin } = await inquirer.prompt([{ theme,
+                type: "input",
+                name: "redfin",
+                message: `Redfin URL ${dim("(optional — auto-tracks home value)")}`,
+            }]);
+        const url = redfin.trim();
+        if (url) {
+            try {
+                const parsed = new URL(url);
+                if (!parsed.hostname.includes("redfin")) {
+                    console.log(chalk.yellow("  Only Redfin URLs are supported."));
+                }
+                else {
+                    listingUrl = url;
+                    const spinner = ora("Fetching Redfin Estimate...").start();
+                    const scraped = await scrapeRedfinEstimate(url);
+                    if (scraped) {
+                        finalBalance = scraped;
+                        spinner.succeed(`Redfin Estimate: ${chalk.bold(rawFormatMoney(scraped))} ${dim("— updates on each sync")}`);
+                    }
+                    else {
+                        spinner.warn("Could not fetch estimate.");
+                        listingUrl = undefined;
+                    }
+                }
+            }
+            catch {
+                console.log(chalk.yellow("  Invalid URL."));
+            }
+        }
+    }
+    // Manual value if no Redfin
+    if (!listingUrl) {
+        const { balance } = await inquirer.prompt([{ theme,
+                type: "input",
+                name: "balance",
+                message: "Current value ($)",
+                validate: (v) => {
+                    const n = parseFloat(v.replace(/[$,]/g, ""));
+                    return isNaN(n) ? "Enter a number" : true;
+                },
+            }]);
+        finalBalance = parseFloat(balance.replace(/[$,]/g, ""));
+    }
+    addManualAccount(db, name.trim(), type, finalBalance, listingUrl);
+    const label = type === "asset" ? chalk.green("asset") : chalk.red("liability");
+    console.log(`\n  ${chalk.green("+")} ${chalk.bold(name.trim())}  ${rawFormatMoney(finalBalance)}  ${label}\n`);
+}
+export async function runRemove() {
+    const readline = await import("readline");
+    const db = getDb();
+    const accounts = getManualAccounts(db);
+    if (accounts.length === 0) {
+        console.log("\nNo manual accounts. Use 'ray add' to create one.");
+        return;
+    }
+    console.log(`\n${heading("Manual Accounts")}\n`);
+    for (let i = 0; i < accounts.length; i++) {
+        const a = accounts[i];
+        const typeLabel = a.type === "loan" || a.type === "credit" ? "liability" : "asset";
+        const url = a.listing_url ? dim(` — ${a.listing_url}`) : "";
+        console.log(`  ${dim(`${i + 1}.`)} ${a.name}  ${rawFormatMoney(a.current_balance)} (${typeLabel})${url}`);
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await new Promise(resolve => rl.question(`\n  Remove which? (number, or Enter to cancel): `, resolve))).trim();
+    rl.close();
+    const idx = parseInt(answer, 10) - 1;
+    if (isNaN(idx) || idx < 0 || idx >= accounts.length)
+        return;
+    removeManualAccount(db, accounts[idx].account_id);
+    console.log(chalk.green(`\n  Removed ${accounts[idx].name}.`));
+    console.log();
+}
 export function showAlerts() {
     const db = getDb();
     const alerts = generateAlerts(db);

package/dist/cli/index.js

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
+import { resolve } from "path";
+import { homedir } from "os";
+// --demo flag: use dedicated demo database (must run before config import)
+const isDemoMode = process.argv.includes("--demo");
+if (isDemoMode) {
+    process.argv = process.argv.filter(a => a !== "--demo");
+}
 import { Command } from "commander";
 import { createRequire } from "module";
 import { config, isConfigured, useManaged, RAY_PROXY_BASE } from "../config.js";
 import { helpScreen } from "./format.js";
+// Override config for demo mode (demo DB is unencrypted)
+if (isDemoMode) {
+    config.dbPath = resolve(homedir(), ".ray", "data", "demo.db");
+    config.dbEncryptionKey = "";
+}
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const program = new Command();
@@ -48,6 +60,22 @@ program
     const { runLink } = await import("./commands.js");
     await runLink();
 });
+program
+    .command("add")
+    .description("Add a manual account (home, car, crypto, etc.)")
+    .action(async () => {
+    ensureConfigured();
+    const { runAdd } = await import("./commands.js");
+    await runAdd();
+});
+program
+    .command("remove")
+    .description("Remove a manual account")
+    .action(async () => {
+    ensureConfigured();
+    const { runRemove } = await import("./commands.js");
+    await runRemove();
+});
 program
     .command("accounts")
     .description("Show linked accounts and balances")
@@ -181,6 +209,14 @@ program
     const { runDoctor } = await import("./doctor.js");
     await runDoctor();
 });
+program
+    .command("demo")
+    .description("Seed a demo database with realistic fake data")
+    .action(async () => {
+    const demoPath = resolve(homedir(), ".ray", "data", "demo.db");
+    const { seedDemoDb } = await import("../demo/seed.js");
+    seedDemoDb(demoPath);
+});
 program
     .command("completions")
     .description("Install shell completions")
@@ -189,6 +225,8 @@ program
     installCompletions();
 });
 function ensureConfigured() {
+    if (isDemoMode)
+        return;
     if (!isConfigured()) {
         console.error("Ray is not configured. Run 'ray setup' first.");
         process.exit(1);
@@ -199,6 +237,8 @@ program.configureHelp({
     formatHelp: () => helpScreen([
         { name: "setup", desc: "Configure Ray (API keys, preferences)" },
         { name: "link", desc: "Link a new financial account via Plaid" },
+        { name: "add", desc: "Add a manual account (home, car, crypto, etc.)" },
+        { name: "remove", desc: "Remove a manual account" },
         { name: "sync", desc: "Sync transactions from linked banks" },
         { name: "accounts", desc: "Show linked accounts and balances" },
         { name: "status", desc: "Show financial overview" },
@@ -213,6 +253,7 @@ program.configureHelp({
         { name: "billing", desc: "Manage your Ray subscription" },
         { name: "update", desc: "Update Ray to the latest version" },
         { name: "doctor", desc: "Check system health" },
+        { name: "demo", desc: "Seed a demo database with fake data" },
         { name: "completions", desc: "Install shell completions" },
     ]),
 });

package/dist/daily-sync.js

@@ -3,6 +3,7 @@ import { calculateDailyScore, checkAchievements } from "./scoring/index.js";
 import { decryptPlaidToken } from "./db/encryption.js";
 import { config } from "./config.js";
 import { institutionName } from "./cli/format.js";
+import { refreshPropertyValues, hasListingUrls } from "./property.js";
 /** Run the daily sync for a single database */
 export async function runDailySync(db) {
     const institutions = db
@@ -98,6 +99,15 @@ export async function runDailySync(db) {
             console.error(`  Error syncing ${inst.name}: ${err.message}`);
         }
     }
+    // Refresh property values from listing URLs if configured
+    if (hasListingUrls(db)) {
+        try {
+            await refreshPropertyValues(db);
+        }
+        catch {
+            // Non-fatal
+        }
+    }
     // Snapshot net worth
     const assets = db
         .prepare(`SELECT COALESCE(SUM(current_balance), 0) as total FROM accounts WHERE type IN ('depository', 'investment', 'other')`)

package/dist/demo/data.d.ts

@@ -0,0 +1,252 @@
+export declare const institutions: {
+    item_id: string;
+    access_token: string;
+    name: string;
+    products: string;
+    logo: string;
+    primary_color: string;
+}[];
+export declare const accounts: ({
+    account_id: string;
+    item_id: string;
+    name: string;
+    official_name: string;
+    type: string;
+    subtype: string;
+    mask: string;
+    current_balance: number;
+    available_balance: number;
+    currency: string;
+    balance_limit: null;
+} | {
+    account_id: string;
+    item_id: string;
+    name: string;
+    official_name: string;
+    type: string;
+    subtype: string;
+    mask: string;
+    current_balance: number;
+    available_balance: null;
+    currency: string;
+    balance_limit: null;
+} | {
+    account_id: string;
+    item_id: string;
+    name: string;
+    official_name: string;
+    type: string;
+    subtype: string;
+    mask: string;
+    current_balance: number;
+    available_balance: number;
+    currency: string;
+    balance_limit: number;
+} | {
+    account_id: string;
+    item_id: string;
+    name: string;
+    official_name: null;
+    type: string;
+    subtype: string;
+    mask: null;
+    current_balance: number;
+    available_balance: null;
+    currency: string;
+    balance_limit: null;
+})[];
+export declare const transactions: ({
+    transaction_id: string;
+    account_id: string;
+    amount: number;
+    date: string;
+    name: string;
+    merchant_name: string;
+    category: string;
+    subcategory: string;
+    pending: number;
+    payment_channel: string;
+} | {
+    transaction_id: string;
+    account_id: string;
+    amount: number;
+    date: string;
+    name: string;
+    merchant_name: null;
+    category: string;
+    subcategory: string;
+    pending: number;
+    payment_channel: string;
+})[];
+export declare const securities: {
+    security_id: string;
+    name: string;
+    ticker: string;
+    type: string;
+    close_price: number;
+    close_price_as_of: string;
+}[];
+export declare const holdings: ({
+    account_id: string;
+    security_id: string;
+    quantity: number;
+    value: number;
+    cost_basis: number;
+    price: number;
+    price_as_of: string;
+    vested_value: null;
+    vested_quantity: null;
+} | {
+    account_id: string;
+    security_id: string;
+    quantity: number;
+    value: number;
+    cost_basis: number;
+    price: number;
+    price_as_of: string;
+    vested_value: number;
+    vested_quantity: number;
+})[];
+export declare const liabilities: ({
+    account_id: string;
+    type: string;
+    interest_rate: number;
+    origination_date: null;
+    original_balance: null;
+    current_balance: number;
+    minimum_payment: number;
+    next_payment_due: string;
+    last_payment_amount: number;
+    last_payment_date: string;
+    credit_limit: number;
+    last_statement_issue_date: string;
+    is_overdue: number;
+    apr_type: string;
+    maturity_date: null;
+    loan_type: null;
+    property_address: null;
+    escrow_balance: null;
+    loan_status: null;
+    loan_name: null;
+    repayment_plan: null;
+    expected_payoff_date: null;
+    ytd_interest_paid: null;
+    ytd_principal_paid: null;
+} | {
+    account_id: string;
+    type: string;
+    interest_rate: number;
+    origination_date: string;
+    original_balance: number;
+    current_balance: number;
+    minimum_payment: number;
+    next_payment_due: string;
+    last_payment_amount: number;
+    last_payment_date: string;
+    credit_limit: null;
+    last_statement_issue_date: null;
+    is_overdue: number;
+    apr_type: string;
+    maturity_date: string;
+    loan_type: string;
+    property_address: string;
+    escrow_balance: number;
+    loan_status: string;
+    loan_name: string;
+    repayment_plan: null;
+    expected_payoff_date: string;
+    ytd_interest_paid: number;
+    ytd_principal_paid: number;
+})[];
+export declare const recurring: ({
+    stream_id: string;
+    account_id: string;
+    merchant_name: string;
+    description: string;
+    frequency: string;
+    category: string;
+    subcategory: string;
+    avg_amount: number;
+    last_amount: number;
+    first_date: string;
+    last_date: string;
+    is_active: number;
+    status: string;
+    stream_type: string;
+} | {
+    stream_id: string;
+    account_id: string;
+    merchant_name: null;
+    description: string;
+    frequency: string;
+    category: string;
+    subcategory: string;
+    avg_amount: number;
+    last_amount: number;
+    first_date: string;
+    last_date: string;
+    is_active: number;
+    status: string;
+    stream_type: string;
+})[];
+export declare const budgets: {
+    category: string;
+    monthly_limit: number;
+    period: string;
+}[];
+export declare const goals: {
+    name: string;
+    target_amount: number;
+    current_amount: number;
+    target_date: string;
+    status: string;
+}[];
+export declare const dailyScores: {
+    date: string;
+    score: number;
+    restaurant_count: number;
+    shopping_count: number;
+    food_spend: number;
+    total_spend: number;
+    zero_spend: number;
+    no_restaurant_streak: number;
+    no_shopping_streak: number;
+    on_pace_streak: number;
+}[];
+export declare const achievements: {
+    key: string;
+    name: string;
+    description: string;
+    unlocked_at: string;
+}[];
+export declare const netWorthHistory: {
+    date: string;
+    total_assets: number;
+    total_liabilities: number;
+    net_worth: number;
+}[];
+export declare const investmentTransactions: {
+    investment_transaction_id: string;
+    account_id: string;
+    security_id: string;
+    date: string;
+    name: string;
+    quantity: number;
+    amount: number;
+    price: number;
+    fees: number;
+    type: string;
+    subtype: string;
+    iso_currency_code: string;
+}[];
+export declare const recurringBills: {
+    name: string;
+    amount: number;
+    day_of_month: number;
+    type: string;
+    account_id: string;
+}[];
+export declare const memories: {
+    content: string;
+    category: string;
+}[];