@pi-stef/finance-api 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefano Fiorini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @pi-stef/finance-api
+
+Always-on local service for financial data ingestion, storage, and deterministic quant analysis.
+
+## Install
+
+### Docker (Recommended)
+
+```bash
+cd packages/finance-api/docker
+docker compose up --build
+```
+
+The service will be available at `http://127.0.0.1:7780`.
+
+### Native
+
+```bash
+pnpm install
+pnpm serve
+```
+
+See [docs/native-run.md](docs/native-run.md) for launchd/systemd setup.
+
+## Configuration
+
+Environment variables (prefix `SF_FINANCE_`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SF_FINANCE_HOST` | `127.0.0.1` | Server host (use `0.0.0.0` for Docker) |
+| `SF_FINANCE_PORT` | `7780` | Server port |
+| `SF_FINANCE_DB` | `~/.pi/sf/finance/finance.db` | SQLite database path |
+| `SF_FINANCE_DATA_FEED` | `stooq` | Price data feed (`stooq` or `yfinance`) |
+
+## Secrets
+
+Create `~/.pi/sf/finance/secrets.json` with provider credentials:
+
+```json
+{
+  "coinbase": {
+    "keyName": "your-api-key",
+    "privateKey": "your-private-key"
+  },
+  "fidelity": {
+    "filePath": "~/Downloads/fidelity-positions.csv"
+  },
+  "boa": {
+    "filePath": "~/Downloads/boa-transactions.ofx"
+  }
+}
+```
+
+The file is automatically `chmod 600` on creation.
+
+## Providers
+
+| Provider | Kind | Auth | Status |
+|----------|------|------|--------|
+| File Import (CSV/OFX) | brokerage/banking | `filePath` | ✅ Working |
+| Coinbase | crypto | `keyName` + `privateKey` | ⚠️ Stub (HMAC not implemented) |
+| SnapTrade | brokerage | `clientId` + `consumerKey` | ⚠️ Stub |
+| SimpleFIN | banking | `accessKey` | ⚠️ Stub |
+| Teller | banking | `token` | ⚠️ Stub |
+
+## First Run
+
+1. Start the service
+2. Import holdings: `POST /v1/import {"filePath": "positions.csv"}`
+3. Set investment goal: `POST /v1/goals {"id": "g1", "name": "Growth", "targetAllocation": {"equity": 0.8, "bonds": 0.2}}`
+4. Check drift: `GET /v1/drift`
+
+## API
+
+All endpoints (except `/v1/health`) require `Authorization: Bearer <token>` header.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v1/health` | Health check (public) |
+| GET | `/v1/market-status` | Current market session |
+| GET | `/v1/holdings` | All holdings |
+| GET | `/v1/net-worth` | Total portfolio value |
+| GET | `/v1/drift` | Allocation drift |
+| GET | `/v1/allocation` | Current allocation |
+| GET | `/v1/goals` | Investment goals |
+| POST | `/v1/goals` | Create/update goal |
+| GET | `/v1/suggestions` | Pending suggestions |
+| POST | `/v1/suggestions/dismiss` | Dismiss suggestion |
+| POST | `/v1/sync` | Trigger sync |
+| POST | `/v1/import` | Import from file |
+| GET | `/v1/history` | Price history |
+| POST | `/v1/export` | Export data |
+
+## Cost
+
+- **Free tier**: File imports (CSV/OFX) — no API costs
+- **Optional**: Coinbase API (free, view-only scope)
+- **Optional**: SnapTrade/SimpleFIN/Teller aggregators (may have fees)
+
+## Disclaimer
+
+**This is not financial advice.** The service provides deterministic calculations based on your data and configured goals. Suggestions are informational only — no trades are executed automatically.
+
+## License
+
+[MIT](../../LICENSE)

package/bin/finance-api.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env tsx
+// finance-api service entry point
+import { loadFinanceApiConfig, ensureToken, openDb, startServer, createLogger, loadSecrets, buildDefaultRegistry, startDaemon } from "../src/index";
+
+const log = createLogger();
+
+async function main() {
+  try {
+    log.info("Starting finance-api service...");
+    
+    // Load config
+    const config = await loadFinanceApiConfig();
+    log.info("Config loaded", { port: config.port, dbPath: config.dbPath });
+    
+    // Ensure bearer token
+    const token = await ensureToken(config.tokenPath);
+    log.info("Token ready");
+    
+    // Open database
+    const db = openDb(config.dbPath);
+    log.info("Database opened");
+    
+    // Load secrets
+    const secrets = loadSecrets(config.secretsPath);
+    log.info("Secrets loaded", { providerCount: Object.keys(secrets).length });
+    
+    // Build provider registry
+    const registry = buildDefaultRegistry();
+    
+    // Start server
+    const server = await startServer({
+      db,
+      token,
+      host: config.host,
+      port: config.port,
+      log,
+      registry,
+      creds: secrets,
+    });
+    
+    log.info("Server started", { host: config.host, port: server.port });
+    
+    // Start scheduler daemon
+    const daemon = startDaemon({
+      db,
+      registry,
+      creds: secrets,
+      log,
+      dataFeed: config.dataFeed,
+    });
+    log.info("Daemon started");
+    
+    // Graceful shutdown
+    const shutdown = () => {
+      log.info("Shutting down...");
+      daemon.stop();
+      server.close();
+      db.close();
+      process.exit(0);
+    };
+    
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    
+  } catch (err) {
+    log.error("Failed to start", { error: err instanceof Error ? err.message : String(err) });
+    process.exit(1);
+  }
+}
+
+main();

package/docker/Dockerfile

@@ -0,0 +1,44 @@
+# ---- build stage: install + compile native deps (better-sqlite3) ----
+FROM node:20-slim AS build
+WORKDIR /app
+
+# Install build tools for native deps
+RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+
+# Enable pnpm
+RUN corepack enable && corepack prepare pnpm@10 --activate
+
+# Copy workspace root files (build context = repo root)
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/finance-api/package.json ./packages/finance-api/package.json
+COPY packages/paths/package.json ./packages/paths/package.json
+
+# Install dependencies
+RUN pnpm install --prod --frozen-lockfile --filter @pi-stef/finance-api
+
+# Copy source
+COPY packages/finance-api/src ./packages/finance-api/src
+COPY packages/finance-api/bin ./packages/finance-api/bin
+COPY packages/paths/src ./packages/paths/src
+
+# ---- runtime stage: slim, no build tooling ----
+FROM node:20-slim AS runtime
+WORKDIR /app
+
+# Install curl for healthcheck
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+
+# Copy built app
+COPY --from=build /app /app
+
+# Set environment
+ENV SF_FINANCE_HOST=0.0.0.0
+ENV SF_FINANCE_PORT=7780
+EXPOSE 7780
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD curl -fsS http://127.0.0.1:7780/v1/health || exit 1
+
+# Run with tsx for TypeScript support
+CMD ["npx", "tsx", "packages/finance-api/bin/finance-api.ts"]

package/docker/README.md

@@ -0,0 +1,3 @@
+# Docker packaging for finance-api
+
+Dockerfile and docker-compose.yml will be added in M10 (Docker packaging).

package/docker/docker-compose.yml

@@ -0,0 +1,26 @@
+version: "3.8"
+
+services:
+  finance-api:
+    build:
+      context: ../..  # Repo root
+      dockerfile: packages/finance-api/docker/Dockerfile
+    ports:
+      - "127.0.0.1:7780:7780"  # Localhost only for security
+    volumes:
+      - finance-data:/data
+      - finance-config:/root/.pi/sf/finance
+    environment:
+      - SF_FINANCE_DB=/data/finance.db
+      - SF_FINANCE_HOST=0.0.0.0
+      - SF_FINANCE_PORT=7780
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:7780/v1/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  finance-data:
+  finance-config:

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pi-stef/finance-api",
+  "version": "0.1.1",
+  "description": "Always-on local service for @pi-stef/finance: ingests financial-account data, stores locally, runs a deterministic quant engine and market-aware scheduler.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sfiorini/pi-stef.git",
+    "directory": "packages/finance-api"
+  },
+  "homepage": "https://sfiorini.github.io/pi-stef/packages/finance-api.html",
+  "files": [
+    "src/",
+    "bin/",
+    "docker/"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-library",
+    "finance-api",
+    "portfolio",
+    "sqlite"
+  ],
+  "dependencies": {
+    "@hono/node-server": "^2.0.6",
+    "@pi-stef/paths": "^0.3.0",
+    "@sinclair/typebox": "*",
+    "better-sqlite3": "^12.11.1",
+    "hono": "^4.6.0",
+    "tsx": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11"
+  },
+  "pi": {},
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "serve": "tsx bin/finance-api.ts"
+  }
+}

package/src/config/load.ts

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { globalConfig, globalDir } from "@pi-stef/paths";
+import type { FinanceApiConfig, DataFeed } from "./types";
+
+export async function loadFinanceApiConfig(
+  env: Record<string, string | undefined> = process.env,
+  homeDir: string = process.env.HOME ?? process.cwd(),
+): Promise<FinanceApiConfig> {
+  const dir = globalDir("finance", homeDir);
+  const defaults: FinanceApiConfig = {
+    host: "127.0.0.1",
+    port: 7780,
+    dbPath: path.join(dir, "finance.db"),
+    secretsPath: path.join(dir, "secrets.json"),
+    tokenPath: path.join(dir, "token"),
+    dataFeed: "stooq",
+    timezone: "America/New_York",
+  };
+
+  let fileConfig: Partial<FinanceApiConfig> = {};
+  try {
+    const file = env.SF_FINANCE_CONFIG ?? globalConfig("finance", homeDir);
+    fileConfig = JSON.parse(await readFile(file, "utf8")) as Partial<FinanceApiConfig>;
+  } catch (e) {
+    if (!(e instanceof Error && "code" in e && (e as { code: string }).code === "ENOENT")) throw e;
+  }
+
+  const envFeed: DataFeed | undefined = env.SF_FINANCE_DATA_FEED === "yfinance" ? "yfinance" : env.SF_FINANCE_DATA_FEED === "stooq" ? "stooq" : undefined;
+  const rawPort = env.SF_FINANCE_PORT ? Number(env.SF_FINANCE_PORT) : undefined;
+  const envPort = Number.isFinite(rawPort) && rawPort! > 0 ? rawPort : undefined;
+
+  return {
+    host: env.SF_FINANCE_HOST ?? fileConfig.host ?? defaults.host,
+    port: envPort ?? fileConfig.port ?? defaults.port,
+    dbPath: env.SF_FINANCE_DB ?? fileConfig.dbPath ?? defaults.dbPath,
+    secretsPath: fileConfig.secretsPath ?? defaults.secretsPath,
+    tokenPath: fileConfig.tokenPath ?? defaults.tokenPath,
+    dataFeed: envFeed ?? fileConfig.dataFeed ?? defaults.dataFeed,
+    timezone: fileConfig.timezone ?? defaults.timezone,
+  };
+}

package/src/config/types.ts

@@ -0,0 +1,11 @@
+export type DataFeed = "stooq" | "yfinance";
+
+export interface FinanceApiConfig {
+  host: string;        // always 127.0.0.1
+  port: number;        // default 7780
+  dbPath: string;      // ~/.pi/sf/finance/finance.db
+  secretsPath: string; // ~/.pi/sf/finance/secrets.json
+  tokenPath: string;   // ~/.pi/sf/finance/token  (generated bearer token)
+  dataFeed: DataFeed;
+  timezone: string;    // default "America/New_York" (US market)
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export const FINANCE_API_VERSION = "0.1.0";
+
+// Core exports
+export { startServer } from "./server/start";
+export { ensureToken } from "./server/bootstrap";
+export { loadFinanceApiConfig } from "./config/load";
+export { openDb } from "./store/db";
+export { createApp } from "./server/app";
+export { createLogger } from "./server/logger";
+export { loadSecrets } from "./ingest/secrets";
+export { buildDefaultRegistry } from "./ingest/matrix";
+export { runIngest } from "./ingest/registry";
+export { startDaemon } from "./scheduler/daemon";
+export { runTick } from "./scheduler/tick";

package/src/ingest/aggregator/simplefin.ts

@@ -0,0 +1,18 @@
+import type { ProviderAdapter, Credentials, Session, RawAccount, RawHolding, RawTxn, RawBalance } from "../contract";
+
+// SimpleFIN aggregates banking accounts (incl. Bank of America) via access tokens.
+// Live calls require a SimpleFIN accessKey (provisioned via simplefin.org).
+// Endpoints: https://bridge.simplefin.org/simplefin/accounts
+export function createSimplefinAdapter(): ProviderAdapter {
+  return {
+    kind: "banking", providerId: "boa-simplefin",
+    authenticate: async (creds: Credentials): Promise<Session> => {
+      if (!creds.accessKey) throw new Error("simplefin requires accessKey");
+      return { providerId: "boa-simplefin", creds };
+    },
+    listAccounts: async (): Promise<RawAccount[]> => [],         // GET /accounts — populated when live creds provided
+    getHoldings: async (): Promise<RawHolding[]> => [],          // Banking accounts have no equity holdings
+    getTransactions: async (): Promise<RawTxn[]> => [],
+    getBalances: async (): Promise<RawBalance> => ({ cash: 0, marketValue: 0, asOf: Date.now() }),
+  };
+}

package/src/ingest/aggregator/snaptrade.ts

@@ -0,0 +1,19 @@
+import type { ProviderAdapter, Credentials, Session, RawAccount, RawHolding, RawTxn, RawBalance } from "../contract";
+
+// SnapTrade aggregates brokerage accounts (incl. Fidelity) via OAuth-style user connections.
+// Live calls require SnapTrade clientId + consumerKey (developer-tier provisioning — open item).
+// Endpoints: https://api.snaptrade.com/api/v1/{accounts,positions,balances}
+export function createSnaptradeAdapter(): ProviderAdapter {
+  return {
+    kind: "brokerage", providerId: "fidelity-snaptrade",
+    authenticate: async (creds: Credentials): Promise<Session> => {
+      if (!creds.clientId || !creds.consumerKey) throw new Error("snaptrade requires clientId + consumerKey");
+      if (!creds.userSecret) throw new Error("snaptrade requires a registered userSecret (connection not established)");
+      return { providerId: "fidelity-snaptrade", creds };
+    },
+    listAccounts: async (): Promise<RawAccount[]> => [],         // GET /accounts — populated when live creds provided
+    getHoldings: async (): Promise<RawHolding[]> => [],          // GET /positions
+    getTransactions: async (): Promise<RawTxn[]> => [],
+    getBalances: async (): Promise<RawBalance> => ({ cash: 0, marketValue: 0, asOf: Date.now() }),
+  };
+}

package/src/ingest/aggregator/teller.ts

@@ -0,0 +1,19 @@
+import type { ProviderAdapter, Credentials, Session, RawAccount, RawHolding, RawTxn, RawBalance } from "../contract";
+
+// Teller aggregates banking accounts (incl. Bank of America) via device-based authentication.
+// NOTE: Teller uses device-based scraping which may have reliability/ToS implications.
+// Live calls require a Teller token (provisioned via teller.io).
+// Endpoints: https://api.teller.io/{accounts,balances,transactions}
+export function createTellerAdapter(): ProviderAdapter {
+  return {
+    kind: "banking", providerId: "boa-teller",
+    authenticate: async (creds: Credentials): Promise<Session> => {
+      if (!creds.token) throw new Error("teller requires token");
+      return { providerId: "boa-teller", creds };
+    },
+    listAccounts: async (): Promise<RawAccount[]> => [],         // GET /accounts — populated when live creds provided
+    getHoldings: async (): Promise<RawHolding[]> => [],          // Banking accounts have no equity holdings
+    getTransactions: async (): Promise<RawTxn[]> => [],
+    getBalances: async (): Promise<RawBalance> => ({ cash: 0, marketValue: 0, asOf: Date.now() }),
+  };
+}

package/src/ingest/contract.ts

@@ -0,0 +1,22 @@
+export type ProviderKind = "brokerage" | "retirement" | "banking" | "crypto";
+
+export interface Credentials { [key: string]: string }
+export interface Session { providerId: string; expiresAt?: number; creds?: Credentials }
+
+export interface RawAccount { providerAccountId: string; kind: ProviderKind; name: string; maskLast4?: string; currency: string }
+export interface RawHolding {
+  symbol: string; quantity: number; avgCost?: number; assetClass: string; subclass?: string;
+  lots?: { openDate: number; qty: number; costBasis: number }[];
+}
+export interface RawTxn { id: string; date: number; symbol?: string; qty?: number; price?: number; type: string; fees?: number }
+export interface RawBalance { cash: number; marketValue: number; asOf: number }
+
+export interface ProviderAdapter {
+  readonly kind: ProviderKind;
+  readonly providerId: string;
+  authenticate(creds: Credentials): Promise<Session>;
+  listAccounts(s: Session): Promise<RawAccount[]>;
+  getHoldings(s: Session, accountId: string): Promise<RawHolding[]>;
+  getTransactions(s: Session, accountId: string, since?: number): Promise<RawTxn[]>;
+  getBalances(s: Session, accountId: string): Promise<RawBalance>;
+}

package/src/ingest/direct/coinbase.ts

@@ -0,0 +1,44 @@
+import type { ProviderAdapter, Credentials, Session, RawAccount, RawHolding, RawTxn, RawBalance } from "../contract";
+
+const BASE = "https://api.coinbase.com/api/v3/brokerage";
+
+interface FetchLike { (url: string, init?: RequestInit): Promise<Response> }
+
+export interface CoinbaseDeps { fetcher?: FetchLike; now?: () => number }
+
+export function createCoinbaseAdapter(deps: CoinbaseDeps = {}): ProviderAdapter {
+  const fetcher = deps.fetcher ?? ((url: string, init?: RequestInit) => fetch(url, init));
+  const now = deps.now ?? (() => Date.now());
+
+  async function signedRequest(creds: Credentials, path: string): Promise<unknown> {
+    const timestamp = Math.floor(now() / 1000).toString();
+    // Real signing uses HMAC-SHA256 over timestamp+method+path+body with privateKey.
+    // This stub passes keyName as CB-ACCESS-KEY; full HMAC signing added when wiring real creds.
+    const res = await fetcher(`${BASE}${path}`, {
+      headers: {
+        "CB-ACCESS-KEY": creds.keyName,
+        "CB-ACCESS-TIMESTAMP": timestamp,
+      },
+    });
+    if (!res.ok) throw new Error(`coinbase ${path} ${res.status}`);
+    return res.json();
+  }
+
+  return {
+    kind: "crypto", providerId: "coinbase",
+    authenticate: async (creds: Credentials): Promise<Session> => {
+      if (!creds.keyName || !creds.privateKey) throw new Error("coinbase requires keyName + privateKey");
+      return { providerId: "coinbase", creds };
+    },
+    listAccounts: async (_s: Session): Promise<RawAccount[]> => [{ providerAccountId: "spot", kind: "crypto", name: "Coinbase Spot", currency: "USD" }],
+    getHoldings: async (s: Session): Promise<RawHolding[]> => {
+      const creds = s.creds ?? {};  // creds attached to Session by runIngest (see contract.ts Session.creds)
+      const body = (await signedRequest(creds, "/accounts")) as { accounts?: { currency: string; available_balance?: { value: string } }[] };
+      return (body.accounts ?? [])
+        .filter((a) => a.currency !== "USD")
+        .map((a) => ({ symbol: a.currency, quantity: Number(a.available_balance?.value ?? "0"), assetClass: "crypto" }));
+    },
+    getTransactions: async (): Promise<RawTxn[]> => [],
+    getBalances: async (): Promise<RawBalance> => ({ cash: 0, marketValue: 0, asOf: now() }),
+  };
+}

package/src/ingest/file/csv.ts

@@ -0,0 +1,30 @@
+import type { RawHolding } from "../contract";
+
+const EQUITY_HINTS = /^(FX|Fidelity|Vanguard|SW|VTI|SPY|AAPL|MSFT|GOOG|AMZN)/i; // crude; refined in 4.x if needed
+
+export function parsePositionsCsv(csv: string): RawHolding[] {
+  const lines = csv.split(/\r?\n/).filter((l) => l.trim());
+  if (lines.length < 2) return [];
+  const header = lines[0].split(",").map((h) => h.trim().toLowerCase());
+  const symIdx = header.findIndex((h) => h === "symbol");
+  const qtyIdx = header.findIndex((h) => h === "quantity" || h === "shares" || h === "qty");
+  const priceIdx = header.findIndex((h) => h === "last price" || h === "price");
+  if (symIdx === -1 || qtyIdx === -1) throw new Error("CSV missing Symbol or Quantity column");
+
+  const out: RawHolding[] = [];
+  for (let i = 1; i < lines.length; i++) {
+    const cols = lines[i].split(",");
+    const symbol = (cols[symIdx] ?? "").trim();
+    const qty = Number((cols[qtyIdx] ?? "").replace(/[^0-9.\-]/g, ""));
+    if (!symbol || !Number.isFinite(qty) || qty === 0) continue;
+    const price = priceIdx >= 0 ? Number((cols[priceIdx] ?? "").replace(/[^0-9.\-]/g, "")) : undefined;
+    out.push({
+      symbol,
+      quantity: Math.abs(qty),
+      avgCost: Number.isFinite(price) ? price : undefined,
+      assetClass: "equity", // file import defaults to equity; cash rows handled by OFX/txns
+      subclass: EQUITY_HINTS.test(symbol) ? "us" : "us",
+    });
+  }
+  return out;
+}

package/src/ingest/file/index.ts

@@ -0,0 +1,64 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import type { ProviderAdapter, ProviderKind, Credentials, Session, RawAccount, RawHolding, RawTxn, RawBalance } from "../contract";
+import { parsePositionsCsv } from "./csv";
+import { parseOfx } from "./ofx";
+
+/**
+ * Parse OFX date format (YYYYMMDD or YYYYMMDDHHMMSS) into unix ms.
+ * OFX dates are in the format: 20260101 or 20260101120000
+ */
+function parseOfxDate(dateStr: string): number {
+  if (!dateStr || dateStr.length < 8) return 0;
+  const year = parseInt(dateStr.slice(0, 4), 10);
+  const month = parseInt(dateStr.slice(4, 6), 10) - 1; // 0-indexed
+  const day = parseInt(dateStr.slice(6, 8), 10);
+  return new Date(year, month, day).getTime();
+}
+
+export function createFileAdapter(providerId: string, kind: ProviderKind): ProviderAdapter {
+  return {
+    kind, providerId,
+    authenticate: async (creds: Credentials): Promise<Session> => ({ providerId, expiresAt: undefined, creds }),
+    listAccounts: async (): Promise<RawAccount[]> => [{ providerAccountId: "file", kind, name: `${providerId} file import`, currency: "USD" }],
+    getHoldings: async (_s: Session, _id: string): Promise<RawHolding[]> => {
+      // filePath is passed via creds at authenticate time; stored on session.creds by runIngest
+      const creds = _s.creds ?? {};
+      const filePath = creds.filePath ?? "";
+      if (!filePath) return [];
+      const buf = await readFile(filePath, "utf8");
+      if (extname(filePath).toLowerCase() === ".ofx" || buf.includes("OFXHEADER")) {
+        // OFX is banking txns, not holdings; cash handled via getBalances
+        return [];
+      }
+      return parsePositionsCsv(buf);
+    },
+    getTransactions: async (_s: Session, _id: string): Promise<RawTxn[]> => {
+      const creds = _s.creds ?? {};
+      const filePath = creds.filePath ?? "";
+      if (!filePath) return [];
+      const buf = await readFile(filePath, "utf8");
+      if (buf.includes("OFXHEADER")) {
+        const ofx = parseOfx(buf);
+        return ofx.transactions.map((t, i) => ({
+          id: `${i}`,
+          date: parseOfxDate(t.date),
+          type: t.amount >= 0 ? "credit" : "debit",
+          fees: 0,
+        }));
+      }
+      return [];
+    },
+    getBalances: async (_s: Session, _id: string): Promise<RawBalance> => {
+      const creds = _s.creds ?? {};
+      const filePath = creds.filePath ?? "";
+      if (!filePath) return { cash: 0, marketValue: 0, asOf: Date.now() };
+      const buf = await readFile(filePath, "utf8");
+      if (buf.includes("OFXHEADER")) {
+        const ofx = parseOfx(buf);
+        return { cash: ofx.balance, marketValue: 0, asOf: Date.now() };
+      }
+      return { cash: 0, marketValue: 0, asOf: Date.now() };
+    },
+  };
+}

package/src/ingest/file/ofx.ts

@@ -0,0 +1,17 @@
+export interface OfxResult { accountId: string; balance: number; transactions: { amount: number; date: string; name: string }[] }
+
+function tag(s: string, name: string): string | undefined {
+  const m = s.match(new RegExp(`<${name}>([^<]*)</${name}>`));
+  return m ? m[1] : undefined;
+}
+
+export function parseOfx(ofx: string): OfxResult {
+  const accountId = tag(ofx, "ACCTID") ?? "unknown";
+  const balance = Number(tag(ofx, "BALAMT") ?? "0");
+  const transactions = [...ofx.matchAll(/<STMTTRN>([\s\S]*?)<\/STMTTRN>/g)].map((m) => ({
+    amount: Number(tag(m[1], "TRNAMT") ?? "0"),
+    date: tag(m[1], "DTPOSTED") ?? "",
+    name: tag(m[1], "NAME") ?? "",
+  }));
+  return { accountId, balance, transactions };
+}

package/src/ingest/matrix.ts

@@ -0,0 +1,17 @@
+import type { AdapterRegistry } from "./registry";
+import { createFileAdapter } from "./file";
+import { createCoinbaseAdapter } from "./direct/coinbase";
+import { createSnaptradeAdapter } from "./aggregator/snaptrade";
+import { createSimplefinAdapter } from "./aggregator/simplefin";
+import { createTellerAdapter } from "./aggregator/teller";
+
+export function buildDefaultRegistry(): AdapterRegistry {
+  return new Map([
+    ["fidelity", createFileAdapter("fidelity", "brokerage")],
+    ["boa", createFileAdapter("boa", "banking")],
+    ["coinbase", createCoinbaseAdapter()],
+    ["fidelity-snaptrade", createSnaptradeAdapter()],
+    ["boa-simplefin", createSimplefinAdapter()],
+    ["boa-teller", createTellerAdapter()],
+  ]);
+}