@pi-stef/finance-api 0.1.1

package/src/server/app.ts

@@ -0,0 +1,54 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { bearerAuth } from "./auth";
+import { marketStatusRoutes } from "./routes/market-status";
+import { holdingsRoutes } from "./routes/holdings";
+import { netWorthRoutes } from "./routes/net-worth";
+import { allocationRoutes } from "./routes/allocation";
+import { goalsRoutes } from "./routes/goals";
+import { suggestionsRoutes } from "./routes/suggestions";
+import { syncRoutes } from "./routes/sync";
+import { importRoutes } from "./routes/import-route";
+import { historyRoutes } from "./routes/history";
+import { healthRoutes } from "./health";
+import { exportRoutes } from "./routes/export";
+import { driftRoutes } from "./routes/drift";
+
+export interface AppDeps {
+  db: Database.Database;
+  token: string;
+  registry?: import("../ingest/registry").AdapterRegistry;
+  creds?: import("../ingest/registry").IngestCreds;
+  fetcher?: typeof fetch;
+  dataFeed?: "stooq" | "yfinance";
+}
+
+export function createApp(deps: AppDeps): Hono {
+  const app = new Hono();
+  
+  // Health endpoint is public (no auth)
+  app.route("/v1/health", healthRoutes());
+  
+  // All other /v1 routes require bearer token
+  app.use("/v1/*", bearerAuth(deps.token));
+  
+  // Mount routes
+  app.route("/v1/market-status", marketStatusRoutes());
+  app.route("/v1/holdings", holdingsRoutes(deps.db));
+  app.route("/v1/net-worth", netWorthRoutes(deps.db));
+  app.route("/v1/allocation", allocationRoutes(deps.db));
+  app.route("/v1/goals", goalsRoutes(deps.db));
+  app.route("/v1/suggestions", suggestionsRoutes(deps.db));
+  app.route("/v1/sync", syncRoutes(deps.db, {
+    registry: deps.registry ?? new Map(),
+    creds: deps.creds ?? {},
+    fetcher: deps.fetcher,
+    dataFeed: deps.dataFeed,
+  }));
+  app.route("/v1/import", importRoutes(deps.db));
+  app.route("/v1/history", historyRoutes(deps.db));
+  app.route("/v1/export", exportRoutes(deps.db));
+  app.route("/v1/drift", driftRoutes(deps.db));
+  
+  return app;
+}

package/src/server/auth.ts

@@ -0,0 +1,25 @@
+import { timingSafeEqual } from "node:crypto";
+import type { Context, Next } from "hono";
+
+/**
+ * Bearer-token auth middleware for Hono.
+ * Compares the Authorization header against the expected token using constant-time comparison.
+ */
+export function bearerAuth(token: string) {
+  return async (c: Context, next: Next): Promise<Response | void> => {
+    const auth = c.req.header("Authorization") ?? "";
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    if (!match) {
+      return c.json({ ok: false, error: { code: "unauthorized", message: "Missing or invalid Authorization header" } }, 401);
+    }
+    
+    const provided = Buffer.from(match[1]);
+    const expected = Buffer.from(token);
+    
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected)) {
+      return c.json({ ok: false, error: { code: "unauthorized", message: "Invalid token" } }, 401);
+    }
+    
+    await next();
+  };
+}

package/src/server/bootstrap.ts

@@ -0,0 +1,32 @@
+import { openSync, closeSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+
+/**
+ * Ensures a bearer token exists at the given path. Race-safe via O_EXCL:
+ * the first caller creates the file; concurrent callers catch EEXIST and read.
+ */
+export async function ensureToken(tokenPath: string): Promise<string> {
+  const dir = dirname(tokenPath);
+  mkdirSync(dir, { recursive: true });
+  
+  const token = randomUUID();
+  try {
+    // Atomic create-exclusive: O_CREAT | O_EXCL fails with EEXIST if file exists
+    const fd = openSync(tokenPath, "wx", 0o600);
+    try {
+      writeFileSync(fd, token, "utf8");
+    } finally {
+      closeSync(fd);
+    }
+    // Ensure permissions are restrictive (in case umask modified them)
+    try { chmodSync(tokenPath, 0o600); } catch { /* best effort */ }
+    return token;
+  } catch (e) {
+    if (e instanceof Error && "code" in e && (e as { code: string }).code === "EEXIST") {
+      // Another caller won the race; read their token
+      return readFileSync(tokenPath, "utf8").trim();
+    }
+    throw e;
+  }
+}

package/src/server/errors.ts

@@ -0,0 +1,20 @@
+export function ok<T>(data: T) {
+  return { ok: true as const, data };
+}
+
+export function fail(code: string, message: string) {
+  return { ok: false as const, error: { code, message } };
+}
+
+export interface StalenessInfo {
+  staleAt?: number | null;
+  staleReason?: string | null;
+}
+
+export function withStaleness<T extends Record<string, unknown>>(data: T, stale?: StalenessInfo): T & { staleAt?: number | null; staleReason?: string | null } {
+  return {
+    ...data,
+    staleAt: stale?.staleAt ?? null,
+    staleReason: stale?.staleReason ?? null,
+  };
+}

package/src/server/health.ts

@@ -0,0 +1,14 @@
+import { Hono } from "hono";
+import { ok } from "./errors";
+
+export function healthRoutes() {
+  const r = new Hono();
+  const startTime = Date.now();
+  
+  r.get("/", (c) => {
+    const uptimeS = Math.floor((Date.now() - startTime) / 1000);
+    return c.json(ok({ status: "ok", uptimeS }));
+  });
+  
+  return r;
+}

package/src/server/logger.ts

@@ -0,0 +1,29 @@
+const SENSITIVE_KEYS = new Set(["token", "privateKey", "consumerKey", "accessKey", "secret", "password"]);
+
+function redact(obj: unknown): unknown {
+  if (typeof obj !== "object" || obj === null) return obj;
+  if (Array.isArray(obj)) return obj.map(redact);
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    result[k] = SENSITIVE_KEYS.has(k) ? "[REDACTED]" : redact(v);
+  }
+  return result;
+}
+
+export interface Logger {
+  info(msg: string, ctx?: unknown): void;
+  warn(msg: string, ctx?: unknown): void;
+  error(msg: string, ctx?: unknown): void;
+}
+
+export function createLogger(): Logger {
+  const log = (level: string, msg: string, ctx?: unknown) => {
+    const entry = { level, msg, ts: new Date().toISOString(), ...(ctx ? { ctx: redact(ctx) } : {}) };
+    process.stderr.write(JSON.stringify(entry) + "\n");
+  };
+  return {
+    info: (msg, ctx) => log("info", msg, ctx),
+    warn: (msg, ctx) => log("warn", msg, ctx),
+    error: (msg, ctx) => log("error", msg, ctx),
+  };
+}

package/src/server/routes/allocation.ts

@@ -0,0 +1,26 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+// listHoldings not needed - using direct SQL query
+import { ok } from "../errors";
+
+export function allocationRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    const allHoldings = db.prepare("SELECT * FROM holdings").all() as { account_id: string; symbol: string; quantity: number; avg_cost: number | null; asset_class: string }[];
+    const byClass = new Map<string, number>();
+    let total = 0;
+    for (const h of allHoldings) {
+      // Use latest price from prices table if available, otherwise fall back to avg_cost
+      const priceRow = db.prepare("SELECT close FROM prices WHERE symbol=? ORDER BY date DESC LIMIT 1").get(h.symbol) as { close: number } | undefined;
+      const price = priceRow?.close ?? h.avg_cost ?? 0;
+      const value = h.quantity * price;
+      byClass.set(h.asset_class, (byClass.get(h.asset_class) ?? 0) + value);
+      total += value;
+    }
+    const allocation = Object.fromEntries(
+      [...byClass.entries()].map(([cls, value]) => [cls, total > 0 ? value / total : 0])
+    );
+    return c.json(ok({ allocation, totalValue: total }));
+  });
+  return r;
+}

package/src/server/routes/drift.ts

@@ -0,0 +1,37 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { listHoldings } from "../../store/repo";
+import { computeDrift, type HoldingValued } from "../../quant/drift";
+import { ok } from "../errors";
+
+export function driftRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    // Get all holdings with latest prices
+    const accounts = db.prepare("SELECT id FROM accounts").all() as { id: string }[];
+    const holdingsValued: HoldingValued[] = [];
+    
+    for (const a of accounts) {
+      const holdings = listHoldings(db, a.id);
+      for (const h of holdings) {
+        // Get latest price from prices table, fall back to avg_cost
+        const priceRow = db.prepare("SELECT close FROM prices WHERE symbol=? ORDER BY date DESC LIMIT 1").get(h.symbol) as { close: number } | undefined;
+        const price = priceRow?.close ?? h.avg_cost ?? 0;
+        holdingsValued.push({
+          symbol: h.symbol,
+          assetClass: h.asset_class,
+          quantity: h.quantity,
+          price,
+        });
+      }
+    }
+    
+    // Get goals for target allocation
+    const goals = db.prepare("SELECT target_allocation FROM goals LIMIT 1").get() as { target_allocation: string } | undefined;
+    const targetAllocation = goals ? JSON.parse(goals.target_allocation) : {};
+    
+    const drift = computeDrift(holdingsValued, { targetAllocation });
+    return c.json(ok({ drift }));
+  });
+  return r;
+}

package/src/server/routes/export.ts

@@ -0,0 +1,32 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { exportJson, backupDb } from "../../store/backup";
+import { ok, fail } from "../errors";
+import { globalDir } from "@pi-stef/paths";
+import path from "node:path";
+import { mkdirSync } from "node:fs";
+
+export function exportRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.post("/", async (c) => {
+    const { format, path: requestedPath } = await c.req.json();
+    if (format === "json") {
+      const data = exportJson(db);
+      return c.json(ok(data));
+    }
+    if (format === "sqlite") {
+      // Restrict backup path to the finance directory for security
+      const backupDir = globalDir("finance");
+      const filename = requestedPath ? path.basename(requestedPath) : `backup-${Date.now()}.db`;
+      const backupPath = path.join(backupDir, "backups", filename);
+      
+      // Ensure backup directory exists
+      mkdirSync(path.dirname(backupPath), { recursive: true });
+      
+      await backupDb(db, backupPath);
+      return c.json(ok({ backupPath }));
+    }
+    return c.json(fail("bad_request", "Invalid format (must be json or sqlite)"), 400);
+  });
+  return r;
+}

package/src/server/routes/goals.ts

@@ -0,0 +1,44 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { upsertGoal, listGoals } from "../../store/repo";
+import { validateGoal } from "../../quant/validate";
+import { ok, fail } from "../errors";
+
+export function goalsRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    const goals = listGoals(db).map((g) => ({
+      ...g,
+      targetAllocation: JSON.parse(g.target_allocation),
+      riskLimits: JSON.parse(g.risk_limits),
+    }));
+    return c.json(ok({ goals }));
+  });
+  r.post("/", async (c) => {
+    const body = await c.req.json();
+    
+    // Validate required fields
+    if (!body.id || !body.name) {
+      return c.json(fail("bad_request", "Missing required fields: id, name"), 400);
+    }
+    if (!body.targetAllocation || typeof body.targetAllocation !== "object") {
+      return c.json(fail("bad_request", "Missing or invalid targetAllocation"), 400);
+    }
+    
+    // Validate goal configuration
+    const errors = validateGoal({ targetAllocation: body.targetAllocation, riskLimits: body.riskLimits ?? {} });
+    if (errors.length > 0) {
+      return c.json(fail("validation_error", errors.join("; ")), 400);
+    }
+    
+    upsertGoal(db, {
+      id: body.id,
+      name: body.name,
+      target_allocation: JSON.stringify(body.targetAllocation),
+      risk_limits: JSON.stringify(body.riskLimits),
+      horizon_years: body.horizonYears ?? null,
+    });
+    return c.json(ok({ id: body.id }));
+  });
+  return r;
+}

package/src/server/routes/history.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { ok, fail } from "../errors";
+
+export function historyRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    const symbol = c.req.query("symbol");
+    const accountId = c.req.query("accountId");
+    if (!symbol) return c.json(fail("bad_request", "Missing symbol query param"), 400);
+    
+    let rows;
+    if (accountId) {
+      // Filter by account: join through holdings to get account-specific prices
+      rows = db.prepare(`
+        SELECT DISTINCT p.* FROM prices p
+        JOIN holdings h ON h.symbol = p.symbol
+        WHERE p.symbol = ? AND h.account_id = ?
+        ORDER BY p.date DESC
+      `).all(symbol, accountId);
+    } else {
+      rows = db.prepare("SELECT * FROM prices WHERE symbol=? ORDER BY date DESC").all(symbol);
+    }
+    return c.json(ok({ history: rows }));
+  });
+  return r;
+}

package/src/server/routes/holdings.ts

@@ -0,0 +1,16 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { listAccounts, listHoldings } from "../../store/repo";
+import { ok } from "../errors";
+
+export function holdingsRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    const accounts = listAccounts(db).map((a) => ({
+      ...a,
+      holdings: listHoldings(db, a.id),
+    }));
+    return c.json(ok({ accounts }));
+  });
+  return r;
+}

package/src/server/routes/import-route.ts

@@ -0,0 +1,29 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import path from "node:path";
+import { runIngest, type AdapterRegistry } from "../../ingest/registry";
+import { createFileAdapter } from "../../ingest/file";
+import { ok, fail } from "../errors";
+
+export function importRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.post("/", async (c) => {
+    const { filePath } = await c.req.json();
+    if (!filePath) return c.json(fail("bad_request", "Missing filePath"), 400);
+    
+    // Security: reject directory traversal (but allow absolute paths for local file imports)
+    if (filePath.includes("..") && !path.isAbsolute(filePath)) {
+      return c.json(fail("bad_request", "Directory traversal is not allowed"), 400);
+    }
+    
+    // Create a one-shot file adapter for this import
+    const fileRegistry: AdapterRegistry = new Map([
+      ["import", createFileAdapter("import", "brokerage")],
+    ]);
+    const creds = { import: { filePath } };
+    
+    const result = await runIngest(db, fileRegistry, creds);
+    return c.json(ok({ message: "Import complete", filePath, ...result }));
+  });
+  return r;
+}

package/src/server/routes/market-status.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import { classifySession } from "../../market/session";
+import { ok, fail } from "../errors";
+
+export function marketStatusRoutes() {
+  const r = new Hono();
+  r.get("/", (c) => {
+    try {
+      const session = classifySession(new Date());
+      return c.json(ok({ session, timestamp: Date.now() }));
+    } catch (err) {
+      // Handle year-guard throw gracefully
+      return c.json(fail("session_unavailable", err instanceof Error ? err.message : "Session classification failed"), 503);
+    }
+  });
+  return r;
+}

package/src/server/routes/net-worth.ts

@@ -0,0 +1,23 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { listAccounts, listHoldings } from "../../store/repo";
+import { ok } from "../errors";
+
+export function netWorthRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    const accounts = listAccounts(db);
+    let totalValue = 0;
+    for (const a of accounts) {
+      const holdings = listHoldings(db, a.id);
+      for (const h of holdings) {
+        // Use latest price from prices table if available, otherwise fall back to avg_cost
+        const priceRow = db.prepare("SELECT close FROM prices WHERE symbol=? ORDER BY date DESC LIMIT 1").get(h.symbol) as { close: number } | undefined;
+        const price = priceRow?.close ?? h.avg_cost ?? 0;
+        totalValue += h.quantity * price;
+      }
+    }
+    return c.json(ok({ netWorth: totalValue, accountCount: accounts.length }));
+  });
+  return r;
+}

package/src/server/routes/suggestions.ts

@@ -0,0 +1,22 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import { listPendingSuggestions, dismissSuggestion } from "../../store/repo";
+import { ok, fail } from "../errors";
+
+export function suggestionsRoutes(db: Database.Database) {
+  const r = new Hono();
+  r.get("/", (c) => {
+    const suggestions = listPendingSuggestions(db).map((s) => ({
+      ...s,
+      payload: JSON.parse(s.payload),
+    }));
+    return c.json(ok({ suggestions }));
+  });
+  r.post("/dismiss", async (c) => {
+    const { id } = await c.req.json();
+    if (!id) return c.json(fail("bad_request", "Missing id"), 400);
+    dismissSuggestion(db, id);
+    return c.json(ok({ dismissed: id }));
+  });
+  return r;
+}

package/src/server/routes/sync.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import type { AdapterRegistry, IngestCreds } from "../../ingest/registry";
+import { runTick } from "../../scheduler/tick";
+import { ok } from "../errors";
+
+export interface SyncDeps {
+  registry: AdapterRegistry;
+  creds: IngestCreds;
+  fetcher?: typeof fetch;
+  dataFeed?: "stooq" | "yfinance";
+}
+
+export function syncRoutes(db: Database.Database, deps: SyncDeps) {
+  const r = new Hono();
+  r.post("/", async (c) => {
+    const result = await runTick({
+      db,
+      registry: deps.registry,
+      creds: deps.creds,
+      fetcher: deps.fetcher,
+      dataFeed: deps.dataFeed,
+    });
+    return c.json(ok({ message: "Sync complete", ...result }));
+  });
+  return r;
+}

package/src/server/start.ts

@@ -0,0 +1,54 @@
+import { serve } from "@hono/node-server";
+import type Database from "better-sqlite3";
+import { createApp } from "./app";
+import type { Logger } from "./logger";
+
+export interface StartServerDeps {
+  db: Database.Database;
+  token: string;
+  host?: string;
+  port?: number;
+  log?: Logger;
+  registry?: import("../ingest/registry").AdapterRegistry;
+  creds?: import("../ingest/registry").IngestCreds;
+  fetcher?: typeof fetch;
+  dataFeed?: "stooq" | "yfinance";
+}
+
+export interface ServerHandle {
+  close: () => void;
+  port: number;
+}
+
+export async function startServer(deps: StartServerDeps): Promise<ServerHandle> {
+  const host = deps.host ?? "127.0.0.1";
+  const port = deps.port ?? 7780;
+  
+  const app = createApp({ db: deps.db, token: deps.token, registry: deps.registry, creds: deps.creds, fetcher: deps.fetcher, dataFeed: deps.dataFeed });
+  
+  return new Promise((resolve, reject) => {
+    try {
+      const server = serve({
+        fetch: app.fetch,
+        hostname: host,
+        port,
+      }, (info) => {
+        deps.log?.info("server started", { host, port: info.port });
+        resolve({
+          close: () => server.close(),
+          port: info.port,
+        });
+      });
+      
+      server.on("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "EADDRINUSE") {
+          reject(new Error(`Port ${port} is already in use (EADDRINUSE)`));
+        } else {
+          reject(err);
+        }
+      });
+    } catch (err) {
+      reject(err);
+    }
+  });
+}

package/src/store/backup.ts

@@ -0,0 +1,26 @@
+import type Database from "better-sqlite3";
+
+/**
+ * Creates a byte-identical, openable copy of the SQLite database using better-sqlite3's online backup API.
+ * Safe to call while the database is in use (WAL mode).
+ */
+export async function backupDb(db: Database.Database, destPath: string): Promise<void> {
+  await db.backup(destPath);
+}
+
+/**
+ * Returns a serializable snapshot of all tables for the /v1/export route.
+ */
+export function exportJson(db: Database.Database): Record<string, unknown[]> {
+  const tables = ["accounts", "holdings", "transactions", "prices", "lots", "goals", "suggestion_records", "market_sessions"];
+  const result: Record<string, unknown[]> = {};
+  for (const table of tables) {
+    try {
+      result[table] = db.prepare(`SELECT * FROM ${table}`).all();
+    } catch {
+      // Table might not exist yet
+      result[table] = [];
+    }
+  }
+  return result;
+}

package/src/store/db.ts

@@ -0,0 +1,8 @@
+import Database from "better-sqlite3";
+import { applyMigrations } from "./migrations";
+
+export function openDb(path: string): Database.Database {
+  const db = new Database(path);
+  applyMigrations(db);
+  return db;
+}

package/src/store/migrations.ts

@@ -0,0 +1,18 @@
+import type Database from "better-sqlite3";
+import { MIGRATIONS_V1, type Migration } from "./schema";
+
+export function applyMigrations(db: Database.Database, all: Migration[] = MIGRATIONS_V1): void {
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec(`CREATE TABLE IF NOT EXISTS schema_versions (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL)`);
+  const applied = new Set(
+    (db.prepare("SELECT version FROM schema_versions").all() as { version: number }[]).map((r) => r.version),
+  );
+  const apply = db.transaction((toApply: Migration[]) => {
+    for (const m of toApply) {
+      db.exec(m.statement);
+      db.prepare("INSERT INTO schema_versions (version, applied_at) VALUES (?, ?)").run(m.version, Date.now());
+    }
+  });
+  const pending = all.filter((m) => !applied.has(m.version)).sort((a, b) => a.version - b.version);
+  apply(pending);
+}