ray-finance 0.2.2 → 0.2.3

package/src/queries/index.test.ts

@@ -0,0 +1,397 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import Database from "better-sqlite3-multiple-ciphers";
+import { migrate } from "../db/schema.js";
+import {
+  formatMoney,
+  categoryLabel,
+  getNetWorth,
+  getAccountBalances,
+  getBudgetStatuses,
+  getGoals,
+  getCashFlowThisMonth,
+  getTransactionsFiltered,
+  searchTransactions,
+  compareSpending,
+  getNetWorthTrend,
+  forecastBalance,
+  getPortfolio,
+  getInvestmentPerformance,
+  getDebts,
+  getCashFlow,
+  getIncome,
+} from "./index.js";
+
+type DB = InstanceType<typeof Database>;
+
+function createTestDb(): DB {
+  const db = new Database(":memory:");
+  db.pragma("foreign_keys = ON");
+  migrate(db);
+  return db;
+}
+
+// Seed helpers
+function seedInstitution(db: DB, id = "inst-1") {
+  db.prepare(`INSERT OR IGNORE INTO institutions (item_id, access_token, name) VALUES (?, 'tok', ?)`).run(id, "Test Bank");
+}
+
+function seedAccount(db: DB, opts: { id: string; type: string; balance: number; subtype?: string; itemId?: string; name?: string }) {
+  seedInstitution(db, opts.itemId || "inst-1");
+  db.prepare(
+    `INSERT OR REPLACE INTO accounts (account_id, item_id, name, type, subtype, current_balance) VALUES (?, ?, ?, ?, ?, ?)`
+  ).run(opts.id, opts.itemId || "inst-1", opts.name || opts.id, opts.type, opts.subtype || null, opts.balance);
+}
+
+function seedTransaction(db: DB, opts: { id: string; accountId: string; amount: number; date: string; name: string; category?: string; merchant?: string; pending?: number; subcategory?: string }) {
+  db.prepare(
+    `INSERT OR REPLACE INTO transactions (transaction_id, account_id, amount, date, name, merchant_name, category, subcategory, pending) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(opts.id, opts.accountId, opts.amount, opts.date, opts.name, opts.merchant || null, opts.category || "OTHER", opts.subcategory || null, opts.pending ?? 0);
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function daysAgo(n: number): string {
+  return new Date(Date.now() - n * 86400000).toISOString().slice(0, 10);
+}
+
+// ─── Pure functions ───
+
+describe("formatMoney", () => {
+  it("formats positive", () => expect(formatMoney(1234.5)).toBe("$1,234.50"));
+  it("formats negative as absolute", () => expect(formatMoney(-99)).toBe("$99.00"));
+  it("formats zero", () => expect(formatMoney(0)).toBe("$0.00"));
+});
+
+describe("categoryLabel", () => {
+  it("maps known categories", () => {
+    expect(categoryLabel("FOOD_AND_DRINK")).toBe("Food & Drink");
+    expect(categoryLabel("ENTERTAINMENT")).toBe("Entertainment");
+  });
+  it("returns raw value for unknown", () => {
+    expect(categoryLabel("CUSTOM_CAT")).toBe("CUSTOM_CAT");
+  });
+});
+
+// ─── Database query functions ───
+
+let db: DB;
+
+beforeEach(() => {
+  db = createTestDb();
+});
+
+describe("getNetWorth", () => {
+  it("returns zeros with no accounts", () => {
+    const nw = getNetWorth(db);
+    expect(nw.net_worth).toBe(0);
+    expect(nw.assets).toBe(0);
+    expect(nw.liabilities).toBe(0);
+  });
+
+  it("computes assets - liabilities", () => {
+    seedAccount(db, { id: "checking", type: "depository", balance: 5000 });
+    seedAccount(db, { id: "invest", type: "investment", balance: 10000 });
+    seedAccount(db, { id: "cc", type: "credit", balance: 2000 });
+
+    const nw = getNetWorth(db);
+    expect(nw.assets).toBe(15000);
+    expect(nw.liabilities).toBe(2000);
+    expect(nw.net_worth).toBe(13000);
+    expect(nw.cash).toBe(5000);
+    expect(nw.investments).toBe(10000);
+    expect(nw.credit_debt).toBe(2000);
+  });
+
+  it("computes home equity", () => {
+    seedAccount(db, { id: "home", type: "other", subtype: "property", balance: 400000 });
+    seedAccount(db, { id: "mort", type: "loan", subtype: "mortgage", balance: 300000 });
+
+    const nw = getNetWorth(db);
+    expect(nw.home_value).toBe(400000);
+    expect(nw.home_equity).toBe(100000);
+    expect(nw.mortgage).toBe(300000);
+  });
+
+  it("returns prev_net_worth from history", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 1000 });
+    db.prepare(`INSERT INTO net_worth_history (date, total_assets, total_liabilities, net_worth) VALUES (?, ?, ?, ?)`)
+      .run(daysAgo(2), 900, 0, 900);
+
+    const nw = getNetWorth(db);
+    expect(nw.prev_net_worth).toBe(900);
+  });
+
+  it("returns null prev_net_worth when no history", () => {
+    const nw = getNetWorth(db);
+    expect(nw.prev_net_worth).toBeNull();
+  });
+});
+
+describe("getAccountBalances", () => {
+  it("returns depository and credit accounts sorted", () => {
+    seedAccount(db, { id: "a", type: "credit", balance: 500, name: "CC" });
+    seedAccount(db, { id: "b", type: "depository", balance: 3000, name: "Checking" });
+    seedAccount(db, { id: "c", type: "depository", balance: 1000, name: "Savings" });
+    seedAccount(db, { id: "d", type: "investment", balance: 9999, name: "Brokerage" });
+
+    const balances = getAccountBalances(db);
+    // investment excluded, credit and depository included
+    expect(balances.map((b) => b.name)).not.toContain("Brokerage");
+    expect(balances.length).toBe(3);
+    // depository sorted by balance desc, then credit
+    expect(balances[0].name).toBe("CC");
+    expect(balances[1].name).toBe("Checking");
+    expect(balances[2].name).toBe("Savings");
+  });
+});
+
+describe("getBudgetStatuses", () => {
+  it("tracks spending against budget", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 1000 });
+    db.prepare(`INSERT INTO budgets (category, monthly_limit) VALUES (?, ?)`).run("FOOD_AND_DRINK", 500);
+
+    // Spend $300 this month
+    seedTransaction(db, { id: "t1", accountId: "a", amount: 200, date: today(), name: "Restaurant", category: "FOOD_AND_DRINK" });
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 100, date: today(), name: "Groceries", category: "FOOD_AND_DRINK" });
+
+    const [budget] = getBudgetStatuses(db);
+    expect(budget.category).toBe("FOOD_AND_DRINK");
+    expect(budget.budget).toBe(500);
+    expect(budget.spent).toBe(300);
+    expect(budget.remaining).toBe(200);
+    expect(budget.pct_used).toBe(60);
+    expect(budget.over_budget).toBe(false);
+  });
+
+  it("flags over budget", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 1000 });
+    db.prepare(`INSERT INTO budgets (category, monthly_limit) VALUES (?, ?)`).run("ENTERTAINMENT", 100);
+    seedTransaction(db, { id: "t1", accountId: "a", amount: 150, date: today(), name: "Concert", category: "ENTERTAINMENT" });
+
+    const [budget] = getBudgetStatuses(db);
+    expect(budget.over_budget).toBe(true);
+    expect(budget.remaining).toBe(-50);
+  });
+});
+
+describe("getGoals", () => {
+  it("computes progress and monthly needed", () => {
+    const futureDate = new Date();
+    futureDate.setMonth(futureDate.getMonth() + 6);
+    const targetDate = futureDate.toISOString().slice(0, 10);
+
+    db.prepare(`INSERT INTO goals (name, target_amount, current_amount, target_date) VALUES (?, ?, ?, ?)`)
+      .run("Emergency Fund", 10000, 4000, targetDate);
+
+    const [goal] = getGoals(db);
+    expect(goal.name).toBe("Emergency Fund");
+    expect(goal.target).toBe(10000);
+    expect(goal.current).toBe(4000);
+    expect(goal.remaining).toBe(6000);
+    expect(goal.progress_pct).toBe(40);
+    expect(goal.monthly_needed).toBe(1000);
+  });
+});
+
+describe("getCashFlowThisMonth", () => {
+  it("separates income and expenses", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 5000 });
+
+    // Income: negative amounts in Plaid convention
+    seedTransaction(db, { id: "t1", accountId: "a", amount: -3000, date: today(), name: "Paycheck", category: "INCOME" });
+    // Expense: positive amounts
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 50, date: today(), name: "Coffee", category: "FOOD_AND_DRINK" });
+    seedTransaction(db, { id: "t3", accountId: "a", amount: 200, date: today(), name: "Gas", category: "TRANSPORTATION" });
+
+    const cf = getCashFlowThisMonth(db);
+    expect(cf.income).toBe(3000);
+    expect(cf.expenses).toBe(250);
+    expect(cf.net).toBe(2750);
+  });
+
+  it("excludes transfers", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 5000 });
+    seedTransaction(db, { id: "t1", accountId: "a", amount: -500, date: today(), name: "Transfer", category: "TRANSFER_IN" });
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 500, date: today(), name: "Transfer", category: "TRANSFER_OUT" });
+
+    const cf = getCashFlowThisMonth(db);
+    expect(cf.income).toBe(0);
+    expect(cf.expenses).toBe(0);
+  });
+});
+
+describe("getTransactionsFiltered", () => {
+  beforeEach(() => {
+    seedAccount(db, { id: "a", type: "depository", balance: 1000 });
+    seedTransaction(db, { id: "t1", accountId: "a", amount: 50, date: "2025-01-15", name: "Coffee Shop", merchant: "Starbucks", category: "FOOD_AND_DRINK" });
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 200, date: "2025-02-10", name: "Electronics", merchant: "Best Buy", category: "GENERAL_MERCHANDISE" });
+    seedTransaction(db, { id: "t3", accountId: "a", amount: 15, date: "2025-02-20", name: "Snack", merchant: "7-Eleven", category: "FOOD_AND_DRINK" });
+  });
+
+  it("filters by date range", () => {
+    const txns = getTransactionsFiltered(db, { startDate: "2025-02-01", endDate: "2025-02-28" });
+    expect(txns.length).toBe(2);
+  });
+
+  it("filters by category", () => {
+    const txns = getTransactionsFiltered(db, { category: "FOOD_AND_DRINK" });
+    expect(txns.length).toBe(2);
+  });
+
+  it("filters by merchant (LIKE match)", () => {
+    const txns = getTransactionsFiltered(db, { merchant: "Star" });
+    expect(txns.length).toBe(1);
+    expect(txns[0].name).toBe("Coffee Shop");
+  });
+
+  it("filters by amount range", () => {
+    const txns = getTransactionsFiltered(db, { minAmount: 20, maxAmount: 100 });
+    expect(txns.length).toBe(1);
+    expect(txns[0].amount).toBe(50);
+  });
+
+  it("respects limit", () => {
+    const txns = getTransactionsFiltered(db, { limit: 1 });
+    expect(txns.length).toBe(1);
+  });
+});
+
+describe("searchTransactions", () => {
+  beforeEach(() => {
+    seedAccount(db, { id: "a", type: "depository", balance: 1000 });
+    seedTransaction(db, { id: "t1", accountId: "a", amount: 50, date: "2025-01-15", name: "Uber Eats", category: "FOOD_AND_DRINK" });
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 30, date: "2025-01-16", name: "Uber Ride", category: "TRANSPORTATION" });
+  });
+
+  it("matches on name", () => {
+    const results = searchTransactions(db, "Uber");
+    expect(results.length).toBe(2);
+  });
+
+  it("matches on category", () => {
+    const results = searchTransactions(db, "TRANSPORT");
+    expect(results.length).toBe(1);
+  });
+});
+
+describe("compareSpending", () => {
+  it("computes period differences by category", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 5000 });
+    // Period 1: Jan
+    seedTransaction(db, { id: "t1", accountId: "a", amount: 200, date: "2025-01-15", name: "Food", category: "FOOD_AND_DRINK" });
+    // Period 2: Feb - more food spending
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 350, date: "2025-02-15", name: "Food", category: "FOOD_AND_DRINK" });
+
+    const result = compareSpending(db, "2025-01-01", "2025-01-31", "2025-02-01", "2025-02-28");
+    expect(result.period1Total).toBe(200);
+    expect(result.period2Total).toBe(350);
+    expect(result.difference).toBe(150);
+    expect(result.categories.length).toBe(1);
+    expect(result.categories[0].diff).toBe(150);
+  });
+});
+
+describe("getNetWorthTrend", () => {
+  it("returns history in chronological order", () => {
+    db.prepare(`INSERT INTO net_worth_history (date, total_assets, total_liabilities, net_worth) VALUES (?, ?, ?, ?)`)
+      .run("2025-01-01", 1000, 100, 900);
+    db.prepare(`INSERT INTO net_worth_history (date, total_assets, total_liabilities, net_worth) VALUES (?, ?, ?, ?)`)
+      .run("2025-01-02", 1100, 100, 1000);
+
+    const trend = getNetWorthTrend(db);
+    expect(trend.length).toBe(2);
+    expect(trend[0].date).toBe("2025-01-01");
+    expect(trend[1].date).toBe("2025-01-02");
+  });
+
+  it("respects limit", () => {
+    for (let i = 1; i <= 5; i++) {
+      db.prepare(`INSERT INTO net_worth_history (date, total_assets, total_liabilities, net_worth) VALUES (?, ?, ?, ?)`)
+        .run(`2025-01-0${i}`, 1000 * i, 0, 1000 * i);
+    }
+    expect(getNetWorthTrend(db, 3).length).toBe(3);
+  });
+});
+
+describe("forecastBalance", () => {
+  it("projects future balances", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 10000 });
+
+    // Seed 3 months of transactions for averaging
+    for (let m = 1; m <= 3; m++) {
+      const date = daysAgo(m * 30);
+      seedTransaction(db, { id: `inc-${m}`, accountId: "a", amount: -5000, date, name: "Paycheck" });
+      seedTransaction(db, { id: `exp-${m}`, accountId: "a", amount: 3000, date, name: "Rent" });
+    }
+
+    const forecast = forecastBalance(db);
+    expect(forecast.currentBalance).toBe(10000);
+    expect(forecast.projections.length).toBe(6);
+    // Net positive cash flow → projections should increase
+    expect(forecast.projections[5].projected).toBeGreaterThan(forecast.currentBalance);
+  });
+});
+
+describe("getPortfolio", () => {
+  it("returns holdings with gain/loss", () => {
+    seedAccount(db, { id: "brok", type: "investment", balance: 10000 });
+    db.prepare(`INSERT INTO securities (security_id, name, ticker) VALUES (?, ?, ?)`).run("sec-1", "Apple Inc", "AAPL");
+    db.prepare(`INSERT INTO holdings (account_id, security_id, quantity, value, cost_basis) VALUES (?, ?, ?, ?, ?)`)
+      .run("brok", "sec-1", 10, 1500, 1000);
+
+    const portfolio = getPortfolio(db);
+    expect(portfolio.totalValue).toBe(1500);
+    expect(portfolio.totalCostBasis).toBe(1000);
+    expect(portfolio.totalGainLoss).toBe(500);
+    expect(portfolio.holdings[0].ticker).toBe("AAPL");
+    expect(portfolio.holdings[0].gainLoss).toBe(500);
+  });
+});
+
+describe("getDebts", () => {
+  it("returns liabilities sorted by rate", () => {
+    seedAccount(db, { id: "cc", type: "credit", balance: 1000 });
+    db.prepare(`INSERT INTO liabilities (account_id, type, interest_rate, current_balance, minimum_payment) VALUES (?, ?, ?, ?, ?)`)
+      .run("cc", "credit", 24.99, 1000, 25);
+
+    const result = getDebts(db);
+    expect(result.totalDebt).toBe(1000);
+    expect(result.debts[0].rate).toBe(24.99);
+  });
+
+  it("falls back to credit accounts when no liabilities", () => {
+    seedAccount(db, { id: "cc", type: "credit", balance: 500 });
+    const result = getDebts(db);
+    expect(result.totalDebt).toBe(500);
+  });
+});
+
+describe("getCashFlow", () => {
+  it("computes savings rate", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 5000 });
+    seedTransaction(db, { id: "t1", accountId: "a", amount: -5000, date: "2025-01-15", name: "Salary", category: "INCOME" });
+    seedTransaction(db, { id: "t2", accountId: "a", amount: 2000, date: "2025-01-20", name: "Rent", category: "RENT_AND_UTILITIES" });
+
+    const cf = getCashFlow(db, "2025-01-01", "2025-01-31");
+    expect(cf.income).toBe(5000);
+    expect(cf.expenses).toBe(2000);
+    expect(cf.net).toBe(3000);
+    expect(cf.savingsRate).toBe(60);
+    expect(cf.monthly.length).toBe(1);
+  });
+});
+
+describe("getIncome", () => {
+  it("groups income by source", () => {
+    seedAccount(db, { id: "a", type: "depository", balance: 5000 });
+    seedTransaction(db, { id: "t1", accountId: "a", amount: -3000, date: "2025-01-10", name: "Payroll", merchant: "Acme Corp", category: "INCOME" });
+    seedTransaction(db, { id: "t2", accountId: "a", amount: -500, date: "2025-01-15", name: "Freelance", merchant: "Client LLC", category: "INCOME" });
+
+    const income = getIncome(db, "2025-01-01", "2025-01-31");
+    expect(income.length).toBe(2);
+    expect(income[0].total).toBe(3000); // sorted desc
+    expect(income[0].source).toBe("Acme Corp");
+  });
+});

package/src/queries/index.ts

@@ -396,13 +396,13 @@ export function getPortfolio(db: Database): {
   holdings: { account: string; security: string; ticker: string; quantity: number; value: number; costBasis: number; gainLoss: number }[];
 } {
   const rows = db.prepare(
-    `SELECT a.name as account, s.name as security, s.ticker_symbol as ticker,
-       h.quantity, h.institution_value as value, h.cost_basis,
-       (h.institution_value - COALESCE(h.cost_basis, h.institution_value)) as gain_loss
+    `SELECT a.name as account, s.name as security, s.ticker,
+       h.quantity, h.value, h.cost_basis,
+       (h.value - COALESCE(h.cost_basis, h.value)) as gain_loss
      FROM holdings h
      JOIN accounts a ON h.account_id = a.account_id
      LEFT JOIN securities s ON h.security_id = s.security_id
-     ORDER BY h.institution_value DESC`
+     ORDER BY h.value DESC`
   ).all() as any[];
 
   const totalValue = rows.reduce((s: number, r: any) => s + (r.value || 0), 0);
@@ -431,12 +431,12 @@ export function getInvestmentPerformance(db: Database): {
   holdings: { security: string; ticker: string; value: number; costBasis: number; returnPct: number }[];
 } {
   const rows = db.prepare(
-    `SELECT s.name as security, s.ticker_symbol as ticker,
-       h.institution_value as value, h.cost_basis
+    `SELECT s.name as security, s.ticker,
+       h.value, h.cost_basis
      FROM holdings h
      LEFT JOIN securities s ON h.security_id = s.security_id
-     WHERE h.institution_value IS NOT NULL
-     ORDER BY h.institution_value DESC`
+     WHERE h.value IS NOT NULL
+     ORDER BY h.value DESC`
   ).all() as any[];
 
   const totalValue = rows.reduce((s: number, r: any) => s + (r.value || 0), 0);

package/src/server.ts

@@ -16,6 +16,22 @@ const __dirname = dirname(__filename);
 // Session map for Plaid Link — maps sessionId → true (single-user, no chatId needed)
 const linkSessions = new Map<string, boolean>();
 
+// Simple rate limiter: track request counts per IP
+const rateLimits = new Map<string, { count: number; resetAt: number }>();
+const RATE_LIMIT_WINDOW = 60_000; // 1 minute
+const RATE_LIMIT_MAX = 10; // max requests per window
+
+function isRateLimited(ip: string): boolean {
+  const now = Date.now();
+  const entry = rateLimits.get(ip);
+  if (!entry || now > entry.resetAt) {
+    rateLimits.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW });
+    return false;
+  }
+  entry.count++;
+  return entry.count > RATE_LIMIT_MAX;
+}
+
 interface LinkResult {
   url: string;
   waitForComplete: () => Promise<void>;
@@ -25,6 +41,26 @@ interface LinkResult {
 export function startLinkServer(): LinkResult {
   const app = express();
   app.use(express.json());
+
+  // Only allow requests from localhost origin
+  app.use((req, res, next) => {
+    const origin = req.headers.origin || req.headers.referer || "";
+    const ip = req.ip || req.socket.remoteAddress || "";
+    if (req.path.startsWith("/api/")) {
+      // Check origin for API routes
+      if (origin && !origin.startsWith(`http://localhost:${config.port}`) && !origin.startsWith(`http://127.0.0.1:${config.port}`)) {
+        res.status(403).json({ error: "Forbidden" });
+        return;
+      }
+      // Rate limit API routes
+      if (isRateLimited(ip)) {
+        res.status(429).json({ error: "Too many requests" });
+        return;
+      }
+    }
+    next();
+  });
+
   app.use(express.static(resolve(__dirname, "public")));
 
   const sessionId = randomUUID();
@@ -139,7 +175,7 @@ export function startLinkServer(): LinkResult {
     }
   });
 
-  const server = app.listen(config.port);
+  const server = app.listen(config.port, "127.0.0.1");
 
   const url = `http://localhost:${config.port}/link/${sessionId}`;
 

package/tsconfig.json

@@ -12,5 +12,5 @@
     "declaration": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
 }

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});