financialclaw 1.0.0

package/README.es.md

@@ -0,0 +1,72 @@
+# financialclaw — Documentación en español
+
+[![CI](https://github.com/riclara/financialclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/riclara/financialclaw/actions/workflows/ci.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/riclara/financialclaw)
+
+Plugin de OpenClaw para finanzas personales. Registra gastos, ingresos, pagos recurrentes y genera resúmenes. Compatible con cualquier canal soportado por OpenClaw (Telegram, WhatsApp, etc.). El OCR de recibos es agéntico: si tu canal permite enviar imágenes, podés fotografiar un recibo y el agente extrae los datos automáticamente. Base de datos SQLite embebida. Soporte multi-moneda.
+
+## Estado del proyecto
+
+El plugin registra 11 tools en OpenClaw. Los reminders y el sync diario corren mediante el sistema de cron integrado de OpenClaw — no se requiere configuración externa.
+
+Si necesitas el detalle de avance por tarea, revisa [docs/hitos.md](docs/hitos.md).
+
+## Capacidades principales
+
+- Tools de OpenClaw para gastos, ingresos, reglas recurrentes y consultas.
+- OCR de recibos agéntico: el agente OpenClaw extrae los datos y los pasa al tool `log_expense_from_receipt`.
+- Persistencia en SQLite embebida.
+- Resolución explícita de moneda con soporte multi-moneda y placeholder inicial `XXX`.
+
+## Instalación
+
+```bash
+openclaw plugins install financialclaw
+npx financialclaw financialclaw-setup
+openclaw gateway restart
+```
+
+### ¿Por qué es necesario `financialclaw-setup`?
+
+`openclaw plugins install` registra el plugin pero no lo agrega a `plugins.allow`. Una vez que ese campo existe, OpenClaw lo usa como allowlist explícita — todo lo que no esté listado deja de funcionar, incluyendo canales activos como Telegram.
+
+`financialclaw-setup` lee el config actual y aplica tres cambios requeridos:
+
+1. **`plugins.allow`** — agrega `financialclaw` junto a todos los canales y plugins activos para que nada deje de funcionar.
+2. **`tools.profile`** — lo cambia a `"full"`. Profiles como `"coding"` o `"minimal"` excluyen tools de plugins, haciéndolos invisibles para el agente.
+3. **`tools.allow`** — agrega `"financialclaw"` como entrada explícita en el allowlist de tools.
+
+También configura `dbPath` para que la BD persista entre reinstalaciones (por defecto: `~/.openclaw/workspace/financialclaw.db`).
+
+### Opciones
+
+```bash
+# Ruta personalizada para la BD
+npx financialclaw financialclaw-setup --db-path /tu/ruta/financialclaw.db
+
+# Si el config de OpenClaw está en una ubicación no estándar
+npx financialclaw financialclaw-setup --config /ruta/openclaw.json
+```
+
+La guía completa está en [docs/setup.es.md](docs/setup.es.md).
+
+## Requisitos
+
+Se requiere Node.js 24+. El plugin usa `node:sqlite`, el módulo SQLite integrado disponible desde Node.js 24 — no requiere addons nativos ni compilación.
+
+## Verificación mínima
+
+Después de instalar dependencias:
+
+```bash
+npx tsc --noEmit
+npm run test:unit
+npm run test:integration
+npm run build
+```
+
+## Documentación
+
+- [docs/setup.es.md](docs/setup.es.md): instalación y troubleshooting — [English](docs/setup.md)
+- [docs/hitos.md](docs/hitos.md): estado final de implementación
+- [docs/testing.md](docs/testing.md): estrategia de pruebas

package/README.md

@@ -0,0 +1,65 @@
+# financialclaw
+
+[![CI](https://github.com/riclara/financialclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/riclara/financialclaw/actions/workflows/ci.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/riclara/financialclaw)
+
+> [Documentación en español](README.es.md)
+
+Personal finance plugin for OpenClaw. Registers expenses, income, recurring payments, and generates summaries. Works with any OpenClaw-supported channel (Telegram, WhatsApp, etc.). Receipt OCR is handled agentically — if your channel supports sending images, you can photograph a receipt and the agent will extract the data automatically. Embedded SQLite database. Multi-currency support.
+
+## Installation
+
+```bash
+openclaw plugins install financialclaw
+npx financialclaw financialclaw-setup
+openclaw gateway restart
+```
+
+### Why is `financialclaw-setup` needed?
+
+`openclaw plugins install` registers the plugin but does not add it to `plugins.allow`. Once that field exists, OpenClaw uses it as an explicit allowlist — anything not listed stops working, including active channels like Telegram.
+
+`financialclaw-setup` reads your current config and applies three required changes:
+
+1. **`plugins.allow`** — adds `financialclaw` alongside all active channels and plugins so nothing stops working.
+2. **`tools.profile`** — sets it to `"full"`. Profiles like `"coding"` or `"minimal"` exclude plugin tools entirely, making them invisible to the agent.
+3. **`tools.allow`** — adds `"financialclaw"` as an explicit tool allowlist entry.
+
+It also sets `plugins.entries.financialclaw.config.dbPath` so the database persists across reinstalls (default: `~/.openclaw/workspace/financialclaw.db`).
+
+### Options
+
+```bash
+# Custom database path
+npx financialclaw financialclaw-setup --db-path /your/path/financialclaw.db
+
+# If the OpenClaw config is in a non-standard location
+npx financialclaw financialclaw-setup --config /path/to/openclaw.json
+```
+
+## Available tools
+
+| Tool | Description |
+|---|---|
+| `manage_currency` | Add currencies, list them, set the default |
+| `log_expense_from_receipt` | Record an expense from structured OCR data |
+| `log_expense_manual` | Record an expense manually |
+| `log_income` | Record income |
+| `log_income_receipt` | Record a payment received linked to an income |
+| `add_recurring_expense` | Create a recurring expense rule |
+| `mark_expense_paid` | Mark an existing expense as paid |
+| `get_financial_summary` | Get a financial summary for a period |
+| `list_expenses` | List expenses with filters |
+| `list_incomes` | List incomes with filters |
+| `run_daily_sync` | Run the daily sync: generate recurring expenses, mark overdue, send reminders |
+
+## Requirements
+
+Node.js 24+ is required. The plugin uses `node:sqlite`, the built-in SQLite module available since Node.js 24 — no native addons or compilation needed.
+
+## Documentation
+
+- [README.es.md](README.es.md): documentación en español
+- [docs/setup.md](docs/setup.md): full setup guide and troubleshooting — [español](docs/setup.es.md)
+- [docs/hitos.md](docs/hitos.md): implementation status
+- [docs/testing.md](docs/testing.md): testing strategy

package/bin/financialclaw-setup.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * ensure-plugins-allow.mjs
+ *
+ * Run this script once after `openclaw plugins install` to configure
+ * financialclaw in the OpenClaw config file.
+ *
+ * What it does:
+ *   1. Adds "financialclaw" to plugins.allow (preserving active channels
+ *      and plugins so they don't get blocked)
+ *   2. Sets plugins.entries.financialclaw.config.dbPath if not already set
+ *   3. Sets tools.profile to "full" so plugin tools are visible to the agent
+ *   4. Adds "financialclaw" to tools.allow as explicit allowlist entry
+ *
+ * Usage:
+ *   node scripts/ensure-plugins-allow.mjs [--config /ruta/openclaw.json] [--db-path /ruta/financialclaw.db]
+ *
+ * Config path resolution order:
+ *   1. --config argument
+ *   2. OPENCLAW_CONFIG env var
+ *   3. First existing file among known locations (see CANDIDATE_PATHS)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+function parseArg(name) {
+  const i = process.argv.indexOf(name);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : null;
+}
+
+function resolveConfigPath() {
+  // 1. --config argument
+  const arg = parseArg("--config");
+  if (arg) return arg;
+
+  // 2. env var
+  if (process.env.OPENCLAW_CONFIG) return process.env.OPENCLAW_CONFIG;
+
+  // 3. known locations in priority order
+  const home = homedir();
+  const CANDIDATE_PATHS = [
+    join(home, ".openclaw", "openclaw.json"),   // most common
+    join(home, "openclaw.json"),                // some installs
+    join(home, ".config", "openclaw", "openclaw.json"),
+  ];
+
+  for (const p of CANDIDATE_PATHS) {
+    if (existsSync(p)) return p;
+  }
+
+  // Return first candidate as default even if it doesn't exist yet
+  // (will fail below with a helpful error)
+  return CANDIDATE_PATHS[0];
+}
+
+const configPath = resolveConfigPath();
+
+if (!existsSync(configPath)) {
+  console.error(`Config not found: ${configPath}`);
+  if (!parseArg("--config") && !process.env.OPENCLAW_CONFIG) {
+    console.error(`Tried: ~/.openclaw/openclaw.json, ~/openclaw.json, ~/.config/openclaw/openclaw.json`);
+    console.error(`Use --config /ruta/al/config to specify the path explicitly.`);
+  }
+  process.exit(1);
+}
+
+console.log(`Using config: ${configPath}`);
+
+const dbPath =
+  parseArg("--db-path") ??
+  join(homedir(), ".openclaw", "workspace", "financialclaw.db");
+
+const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+const plugins = (cfg.plugins ??= {});
+
+// 1. Ensure plugins.allow includes financialclaw and all active entries
+// Always rediscover active channels and plugins so re-runs fix missing entries
+{
+  const allow = new Set(plugins.allow ?? []);
+  allow.add("financialclaw");
+
+  if (cfg.channels) {
+    for (const [name, ch] of Object.entries(cfg.channels)) {
+      if (ch.enabled !== false) allow.add(name);
+    }
+  }
+
+  if (plugins.entries) {
+    for (const [name, entry] of Object.entries(plugins.entries)) {
+      if (entry.enabled !== false) allow.add(name);
+    }
+  }
+
+  plugins.allow = [...allow];
+  console.log(`Updated plugins.allow:`, JSON.stringify(plugins.allow));
+}
+
+// 2. Set dbPath in plugins.entries.financialclaw.config if not already set
+const entries = (plugins.entries ??= {});
+const fc = (entries.financialclaw ??= { enabled: true, config: {} });
+fc.config ??= {};
+
+if (!fc.config.dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  fc.config.dbPath = dbPath;
+  console.log(`Set dbPath: ${dbPath}`);
+} else {
+  console.log(`dbPath already set: ${fc.config.dbPath}`);
+}
+
+// 3. Ensure tools.profile is "full" so plugin tools are visible to the agent
+// Profiles like "coding" or "minimal" exclude plugin tools entirely
+{
+  const tools = (cfg.tools ??= {});
+  const prev = tools.profile;
+  if (prev && prev !== "full") {
+    tools.profile = "full";
+    console.log(`Updated tools.profile: "${prev}" -> "full" (required for plugin tools)`);
+  } else if (!prev) {
+    tools.profile = "full";
+    console.log(`Set tools.profile: "full"`);
+  } else {
+    console.log(`tools.profile already "full"`);
+  }
+}
+
+// 4. Ensure tools.allow includes "financialclaw" as explicit allowlist entry
+{
+  const tools = (cfg.tools ??= {});
+  const toolsAllow = new Set(tools.allow ?? []);
+  toolsAllow.add("financialclaw");
+  tools.allow = [...toolsAllow];
+  console.log(`Updated tools.allow:`, JSON.stringify(tools.allow));
+}
+
+writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n");
+console.log("Done. Restart gateway: openclaw gateway restart");

package/bin/postinstall-message.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Skip in CI environments
+if (process.env.CI || process.env.GITHUB_ACTIONS) process.exit(0);
+
+console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║              financialclaw — setup required                  ║
+╠══════════════════════════════════════════════════════════════╣
+║  Run this before restarting the gateway:                     ║
+║                                                              ║
+║    npx financialclaw financialclaw-setup                     ║
+║                                                              ║
+║  This adds financialclaw to plugins.allow and configures     ║
+║  a persistent database path. Without it, active channels     ║
+║  (Telegram, etc.) may stop working.                          ║
+╚══════════════════════════════════════════════════════════════╝
+`);

package/dist/src/db/database.d.ts

@@ -0,0 +1,3 @@
+import { DatabaseSync } from "node:sqlite";
+export declare function configureDb(dbPath: string): void;
+export declare function getDb(): DatabaseSync;

package/dist/src/db/database.js

@@ -0,0 +1,58 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { ALL_MIGRATIONS, ALL_SEEDS } from "./schema.js";
+const DEFAULT_DB_PATH = join(homedir(), ".openclaw", "workspace", "financialclaw.db");
+let _db;
+let _dbPath;
+function shouldIgnoreMigrationError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message;
+    return /duplicate column name: (updated_at|status|failure_code)/i.test(message);
+}
+function runMigrations(db) {
+    for (const sql of ALL_MIGRATIONS) {
+        try {
+            db.exec(sql);
+        }
+        catch (error) {
+            if (!shouldIgnoreMigrationError(error)) {
+                throw error;
+            }
+        }
+    }
+}
+function initializeDb(db) {
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec("BEGIN");
+    try {
+        runMigrations(db);
+        for (const sql of ALL_SEEDS) {
+            db.exec(sql);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+}
+export function configureDb(dbPath) {
+    if (_db !== undefined) {
+        throw new Error("Cannot reconfigure the database after the singleton has been initialized.");
+    }
+    _dbPath = dbPath;
+}
+export function getDb() {
+    if (_db === undefined) {
+        _dbPath = _dbPath ?? process.env.FINANCIALCLAW_DB_PATH ?? DEFAULT_DB_PATH;
+        mkdirSync(dirname(_dbPath), { recursive: true });
+        _db = new DatabaseSync(_dbPath);
+        initializeDb(_db);
+    }
+    return _db;
+}

package/dist/src/db/schema.d.ts

@@ -0,0 +1,16 @@
+export declare const CREATE_CURRENCIES_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS currencies (\n  code TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  symbol TEXT NOT NULL,\n  is_default INTEGER NOT NULL DEFAULT 0 CHECK (is_default IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n";
+export declare const CREATE_OCR_EXTRACTIONS_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS ocr_extractions (\n  id TEXT PRIMARY KEY,\n  provider TEXT NOT NULL,\n  source_path TEXT,\n  raw_text TEXT,\n  lines_json TEXT,\n  average_confidence REAL,\n  suggested_amount INTEGER,\n  suggested_currency TEXT,\n  suggested_date TEXT,\n  suggested_merchant TEXT,\n  suggested_category TEXT,\n  failure_reason TEXT,\n  failure_detail TEXT,\n  status TEXT NOT NULL DEFAULT 'COMPLETED',\n  failure_code TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n";
+export declare const CREATE_RECURRING_EXPENSE_RULES_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS recurring_expense_rules (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  amount INTEGER NOT NULL,\n  category TEXT,\n  currency TEXT NOT NULL,\n  frequency TEXT NOT NULL,\n  interval_days INTEGER,\n  day_of_month INTEGER,\n  starts_on TEXT NOT NULL,\n  ends_on TEXT,\n  reminder_days_before INTEGER NOT NULL DEFAULT 0,\n  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (currency) REFERENCES currencies (code)\n);\n";
+export declare const CREATE_EXPENSES_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS expenses (\n  id TEXT PRIMARY KEY,\n  amount INTEGER NOT NULL,\n  currency TEXT NOT NULL,\n  category TEXT,\n  merchant TEXT,\n  description TEXT NOT NULL,\n  due_date TEXT NOT NULL,\n  payment_date TEXT,\n  status TEXT NOT NULL,\n  source TEXT NOT NULL,\n  ocr_extraction_id TEXT,\n  recurring_rule_id TEXT,\n  generated_from_rule INTEGER NOT NULL DEFAULT 0 CHECK (generated_from_rule IN (0, 1)),\n  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (currency) REFERENCES currencies (code),\n  FOREIGN KEY (ocr_extraction_id) REFERENCES ocr_extractions (id),\n  FOREIGN KEY (recurring_rule_id) REFERENCES recurring_expense_rules (id)\n);\n";
+export declare const ADD_EXPENSES_UPDATED_AT_COLUMN_SQL = "\nALTER TABLE expenses ADD COLUMN updated_at TEXT;\n";
+export declare const BACKFILL_EXPENSES_UPDATED_AT_SQL = "\nUPDATE expenses\nSET updated_at = created_at\nWHERE updated_at IS NULL;\n";
+export declare const ADD_OCR_EXTRACTIONS_STATUS_COLUMN_SQL = "\nALTER TABLE ocr_extractions ADD COLUMN status TEXT NOT NULL DEFAULT 'COMPLETED'\n";
+export declare const ADD_OCR_EXTRACTIONS_FAILURE_CODE_COLUMN_SQL = "\nALTER TABLE ocr_extractions ADD COLUMN failure_code TEXT\n";
+export declare const CREATE_EXPENSES_RECURRING_UNIQUE_INDEX_SQL = "\nCREATE UNIQUE INDEX IF NOT EXISTS idx_expenses_recurring_rule_due_date\nON expenses (recurring_rule_id, due_date)\nWHERE recurring_rule_id IS NOT NULL;\n";
+export declare const CREATE_INCOMES_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS incomes (\n  id TEXT PRIMARY KEY,\n  reason TEXT NOT NULL,\n  expected_amount INTEGER NOT NULL,\n  currency TEXT NOT NULL,\n  date TEXT NOT NULL,\n  frequency TEXT,\n  interval_days INTEGER,\n  is_recurring INTEGER NOT NULL DEFAULT 0 CHECK (is_recurring IN (0, 1)),\n  next_expected_receipt_date TEXT,\n  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (currency) REFERENCES currencies (code)\n);\n";
+export declare const CREATE_INCOME_RECEIPTS_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS income_receipts (\n  id TEXT PRIMARY KEY,\n  income_id TEXT NOT NULL,\n  amount INTEGER NOT NULL,\n  currency TEXT NOT NULL,\n  date TEXT NOT NULL,\n  notes TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (income_id) REFERENCES incomes (id),\n  FOREIGN KEY (currency) REFERENCES currencies (code)\n);\n";
+export declare const CREATE_REMINDERS_TABLE_SQL = "\nCREATE TABLE IF NOT EXISTS reminders (\n  id TEXT PRIMARY KEY,\n  expense_id TEXT NOT NULL,\n  scheduled_date TEXT NOT NULL,\n  days_before INTEGER NOT NULL,\n  sent INTEGER NOT NULL DEFAULT 0 CHECK (sent IN (0, 1)),\n  sent_at TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (expense_id) REFERENCES expenses (id)\n);\n";
+export declare const CREATE_REMINDERS_UNIQUE_INDEX_SQL = "\nCREATE UNIQUE INDEX IF NOT EXISTS idx_reminders_expense_schedule_days_before\nON reminders (expense_id, scheduled_date, days_before);\n";
+export declare const SEED_PLACEHOLDER_CURRENCY_SQL = "\nINSERT OR IGNORE INTO currencies (code, name, symbol, is_default)\nVALUES ('XXX', 'Sin configurar', '\u00A4', 1);\n";
+export declare const ALL_MIGRATIONS: readonly ["\nCREATE TABLE IF NOT EXISTS currencies (\n  code TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  symbol TEXT NOT NULL,\n  is_default INTEGER NOT NULL DEFAULT 0 CHECK (is_default IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n", "\nCREATE TABLE IF NOT EXISTS ocr_extractions (\n  id TEXT PRIMARY KEY,\n  provider TEXT NOT NULL,\n  source_path TEXT,\n  raw_text TEXT,\n  lines_json TEXT,\n  average_confidence REAL,\n  suggested_amount INTEGER,\n  suggested_currency TEXT,\n  suggested_date TEXT,\n  suggested_merchant TEXT,\n  suggested_category TEXT,\n  failure_reason TEXT,\n  failure_detail TEXT,\n  status TEXT NOT NULL DEFAULT 'COMPLETED',\n  failure_code TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n", "\nCREATE TABLE IF NOT EXISTS recurring_expense_rules (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  amount INTEGER NOT NULL,\n  category TEXT,\n  currency TEXT NOT NULL,\n  frequency TEXT NOT NULL,\n  interval_days INTEGER,\n  day_of_month INTEGER,\n  starts_on TEXT NOT NULL,\n  ends_on TEXT,\n  reminder_days_before INTEGER NOT NULL DEFAULT 0,\n  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (currency) REFERENCES currencies (code)\n);\n", "\nCREATE TABLE IF NOT EXISTS expenses (\n  id TEXT PRIMARY KEY,\n  amount INTEGER NOT NULL,\n  currency TEXT NOT NULL,\n  category TEXT,\n  merchant TEXT,\n  description TEXT NOT NULL,\n  due_date TEXT NOT NULL,\n  payment_date TEXT,\n  status TEXT NOT NULL,\n  source TEXT NOT NULL,\n  ocr_extraction_id TEXT,\n  recurring_rule_id TEXT,\n  generated_from_rule INTEGER NOT NULL DEFAULT 0 CHECK (generated_from_rule IN (0, 1)),\n  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (currency) REFERENCES currencies (code),\n  FOREIGN KEY (ocr_extraction_id) REFERENCES ocr_extractions (id),\n  FOREIGN KEY (recurring_rule_id) REFERENCES recurring_expense_rules (id)\n);\n", "\nALTER TABLE expenses ADD COLUMN updated_at TEXT;\n", "\nUPDATE expenses\nSET updated_at = created_at\nWHERE updated_at IS NULL;\n", "\nCREATE UNIQUE INDEX IF NOT EXISTS idx_expenses_recurring_rule_due_date\nON expenses (recurring_rule_id, due_date)\nWHERE recurring_rule_id IS NOT NULL;\n", "\nCREATE TABLE IF NOT EXISTS incomes (\n  id TEXT PRIMARY KEY,\n  reason TEXT NOT NULL,\n  expected_amount INTEGER NOT NULL,\n  currency TEXT NOT NULL,\n  date TEXT NOT NULL,\n  frequency TEXT,\n  interval_days INTEGER,\n  is_recurring INTEGER NOT NULL DEFAULT 0 CHECK (is_recurring IN (0, 1)),\n  next_expected_receipt_date TEXT,\n  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (currency) REFERENCES currencies (code)\n);\n", "\nCREATE TABLE IF NOT EXISTS income_receipts (\n  id TEXT PRIMARY KEY,\n  income_id TEXT NOT NULL,\n  amount INTEGER NOT NULL,\n  currency TEXT NOT NULL,\n  date TEXT NOT NULL,\n  notes TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (income_id) REFERENCES incomes (id),\n  FOREIGN KEY (currency) REFERENCES currencies (code)\n);\n", "\nCREATE TABLE IF NOT EXISTS reminders (\n  id TEXT PRIMARY KEY,\n  expense_id TEXT NOT NULL,\n  scheduled_date TEXT NOT NULL,\n  days_before INTEGER NOT NULL,\n  sent INTEGER NOT NULL DEFAULT 0 CHECK (sent IN (0, 1)),\n  sent_at TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  FOREIGN KEY (expense_id) REFERENCES expenses (id)\n);\n", "\nCREATE UNIQUE INDEX IF NOT EXISTS idx_reminders_expense_schedule_days_before\nON reminders (expense_id, scheduled_date, days_before);\n", "\nALTER TABLE ocr_extractions ADD COLUMN status TEXT NOT NULL DEFAULT 'COMPLETED'\n", "\nALTER TABLE ocr_extractions ADD COLUMN failure_code TEXT\n"];
+export declare const ALL_SEEDS: readonly ["\nINSERT OR IGNORE INTO currencies (code, name, symbol, is_default)\nVALUES ('XXX', 'Sin configurar', '¤', 1);\n"];

package/dist/src/db/schema.js

@@ -0,0 +1,154 @@
+export const CREATE_CURRENCIES_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS currencies (
+  code TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  symbol TEXT NOT NULL,
+  is_default INTEGER NOT NULL DEFAULT 0 CHECK (is_default IN (0, 1)),
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+`;
+export const CREATE_OCR_EXTRACTIONS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS ocr_extractions (
+  id TEXT PRIMARY KEY,
+  provider TEXT NOT NULL,
+  source_path TEXT,
+  raw_text TEXT,
+  lines_json TEXT,
+  average_confidence REAL,
+  suggested_amount INTEGER,
+  suggested_currency TEXT,
+  suggested_date TEXT,
+  suggested_merchant TEXT,
+  suggested_category TEXT,
+  failure_reason TEXT,
+  failure_detail TEXT,
+  status TEXT NOT NULL DEFAULT 'COMPLETED',
+  failure_code TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+`;
+export const CREATE_RECURRING_EXPENSE_RULES_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS recurring_expense_rules (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  amount INTEGER NOT NULL,
+  category TEXT,
+  currency TEXT NOT NULL,
+  frequency TEXT NOT NULL,
+  interval_days INTEGER,
+  day_of_month INTEGER,
+  starts_on TEXT NOT NULL,
+  ends_on TEXT,
+  reminder_days_before INTEGER NOT NULL DEFAULT 0,
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (currency) REFERENCES currencies (code)
+);
+`;
+export const CREATE_EXPENSES_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS expenses (
+  id TEXT PRIMARY KEY,
+  amount INTEGER NOT NULL,
+  currency TEXT NOT NULL,
+  category TEXT,
+  merchant TEXT,
+  description TEXT NOT NULL,
+  due_date TEXT NOT NULL,
+  payment_date TEXT,
+  status TEXT NOT NULL,
+  source TEXT NOT NULL,
+  ocr_extraction_id TEXT,
+  recurring_rule_id TEXT,
+  generated_from_rule INTEGER NOT NULL DEFAULT 0 CHECK (generated_from_rule IN (0, 1)),
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (currency) REFERENCES currencies (code),
+  FOREIGN KEY (ocr_extraction_id) REFERENCES ocr_extractions (id),
+  FOREIGN KEY (recurring_rule_id) REFERENCES recurring_expense_rules (id)
+);
+`;
+export const ADD_EXPENSES_UPDATED_AT_COLUMN_SQL = `
+ALTER TABLE expenses ADD COLUMN updated_at TEXT;
+`;
+export const BACKFILL_EXPENSES_UPDATED_AT_SQL = `
+UPDATE expenses
+SET updated_at = created_at
+WHERE updated_at IS NULL;
+`;
+export const ADD_OCR_EXTRACTIONS_STATUS_COLUMN_SQL = `
+ALTER TABLE ocr_extractions ADD COLUMN status TEXT NOT NULL DEFAULT 'COMPLETED'
+`;
+export const ADD_OCR_EXTRACTIONS_FAILURE_CODE_COLUMN_SQL = `
+ALTER TABLE ocr_extractions ADD COLUMN failure_code TEXT
+`;
+export const CREATE_EXPENSES_RECURRING_UNIQUE_INDEX_SQL = `
+CREATE UNIQUE INDEX IF NOT EXISTS idx_expenses_recurring_rule_due_date
+ON expenses (recurring_rule_id, due_date)
+WHERE recurring_rule_id IS NOT NULL;
+`;
+export const CREATE_INCOMES_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS incomes (
+  id TEXT PRIMARY KEY,
+  reason TEXT NOT NULL,
+  expected_amount INTEGER NOT NULL,
+  currency TEXT NOT NULL,
+  date TEXT NOT NULL,
+  frequency TEXT,
+  interval_days INTEGER,
+  is_recurring INTEGER NOT NULL DEFAULT 0 CHECK (is_recurring IN (0, 1)),
+  next_expected_receipt_date TEXT,
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (currency) REFERENCES currencies (code)
+);
+`;
+export const CREATE_INCOME_RECEIPTS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS income_receipts (
+  id TEXT PRIMARY KEY,
+  income_id TEXT NOT NULL,
+  amount INTEGER NOT NULL,
+  currency TEXT NOT NULL,
+  date TEXT NOT NULL,
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (income_id) REFERENCES incomes (id),
+  FOREIGN KEY (currency) REFERENCES currencies (code)
+);
+`;
+export const CREATE_REMINDERS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS reminders (
+  id TEXT PRIMARY KEY,
+  expense_id TEXT NOT NULL,
+  scheduled_date TEXT NOT NULL,
+  days_before INTEGER NOT NULL,
+  sent INTEGER NOT NULL DEFAULT 0 CHECK (sent IN (0, 1)),
+  sent_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (expense_id) REFERENCES expenses (id)
+);
+`;
+export const CREATE_REMINDERS_UNIQUE_INDEX_SQL = `
+CREATE UNIQUE INDEX IF NOT EXISTS idx_reminders_expense_schedule_days_before
+ON reminders (expense_id, scheduled_date, days_before);
+`;
+export const SEED_PLACEHOLDER_CURRENCY_SQL = `
+INSERT OR IGNORE INTO currencies (code, name, symbol, is_default)
+VALUES ('XXX', 'Sin configurar', '¤', 1);
+`;
+export const ALL_MIGRATIONS = [
+    CREATE_CURRENCIES_TABLE_SQL,
+    CREATE_OCR_EXTRACTIONS_TABLE_SQL,
+    CREATE_RECURRING_EXPENSE_RULES_TABLE_SQL,
+    CREATE_EXPENSES_TABLE_SQL,
+    ADD_EXPENSES_UPDATED_AT_COLUMN_SQL,
+    BACKFILL_EXPENSES_UPDATED_AT_SQL,
+    CREATE_EXPENSES_RECURRING_UNIQUE_INDEX_SQL,
+    CREATE_INCOMES_TABLE_SQL,
+    CREATE_INCOME_RECEIPTS_TABLE_SQL,
+    CREATE_REMINDERS_TABLE_SQL,
+    CREATE_REMINDERS_UNIQUE_INDEX_SQL,
+    ADD_OCR_EXTRACTIONS_STATUS_COLUMN_SQL,
+    ADD_OCR_EXTRACTIONS_FAILURE_CODE_COLUMN_SQL,
+];
+export const ALL_SEEDS = [SEED_PLACEHOLDER_CURRENCY_SQL];

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind">;
+export default _default;

package/dist/src/index.js

@@ -0,0 +1,112 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { configureDb } from "./db/database.js";
+import { InputSchema as ManageCurrencyInputSchema, executeManageCurrency } from "./tools/manage-currency.js";
+import { InputSchema as LogExpenseFromReceiptInputSchema, executeLogExpenseFromReceipt } from "./tools/log-expense-from-receipt.js";
+import { InputSchema as LogExpenseManualInputSchema, executeLogExpenseManual } from "./tools/log-expense-manual.js";
+import { InputSchema as LogIncomeInputSchema, executeLogIncome } from "./tools/log-income.js";
+import { InputSchema as LogIncomeReceiptInputSchema, executeLogIncomeReceipt } from "./tools/log-income-receipt.js";
+import { InputSchema as AddRecurringExpenseInputSchema, executeAddRecurringExpense } from "./tools/add-recurring-expense.js";
+import { InputSchema as MarkExpensePaidInputSchema, executeMarkExpensePaid } from "./tools/mark-expense-paid.js";
+import { InputSchema as GetFinancialSummaryInputSchema, executeGetFinancialSummary } from "./tools/get-financial-summary.js";
+import { InputSchema as ListExpensesInputSchema, executeListExpenses } from "./tools/list-expenses.js";
+import { InputSchema as ListIncomesInputSchema, executeListIncomes } from "./tools/list-incomes.js";
+import { InputSchema as RunDailySyncInputSchema, executeRunDailySync } from "./tools/run-daily-sync.js";
+function wrapExecute(fn) {
+    return async (_id, params) => {
+        const text = await fn(params);
+        return {
+            content: [{ type: "text", text }],
+            details: undefined,
+        };
+    };
+}
+export default definePluginEntry({
+    id: "financialclaw",
+    name: "FinancialClaw",
+    description: "Personal finance plugin: expenses, income, recurring payments, and receipt OCR",
+    register(api) {
+        const config = api.pluginConfig ?? {};
+        if (config.dbPath) {
+            configureDb(config.dbPath);
+        }
+        // Python CMD config removed - OCR is now agentic
+        api.registerTool({
+            name: "manage_currency",
+            label: "Manage Currency",
+            description: "Manage configured currencies (add, list, set default)",
+            parameters: ManageCurrencyInputSchema,
+            execute: wrapExecute(executeManageCurrency),
+        });
+        // log_expense_from_image removed - replaced by log_expense_from_receipt (agentic OCR)
+        api.registerTool({
+            name: "log_expense_from_receipt",
+            label: "Log Expense From Receipt",
+            description: "Log an expense from structured OCR data provided by the agent",
+            parameters: LogExpenseFromReceiptInputSchema,
+            execute: wrapExecute(executeLogExpenseFromReceipt),
+        });
+        api.registerTool({
+            name: "log_expense_manual",
+            label: "Log Expense Manual",
+            description: "Log an expense manually",
+            parameters: LogExpenseManualInputSchema,
+            execute: wrapExecute(executeLogExpenseManual),
+        });
+        api.registerTool({
+            name: "log_income",
+            label: "Log Income",
+            description: "Log an income entry",
+            parameters: LogIncomeInputSchema,
+            execute: wrapExecute(executeLogIncome),
+        });
+        api.registerTool({
+            name: "log_income_receipt",
+            label: "Log Income Receipt",
+            description: "Log a received payment linked to an income entry",
+            parameters: LogIncomeReceiptInputSchema,
+            execute: wrapExecute(executeLogIncomeReceipt),
+        });
+        api.registerTool({
+            name: "add_recurring_expense",
+            label: "Add Recurring Expense",
+            description: "Create a recurring expense rule",
+            parameters: AddRecurringExpenseInputSchema,
+            execute: wrapExecute(executeAddRecurringExpense),
+        });
+        api.registerTool({
+            name: "mark_expense_paid",
+            label: "Mark Expense Paid",
+            description: "Mark an existing expense as paid",
+            parameters: MarkExpensePaidInputSchema,
+            execute: wrapExecute(executeMarkExpensePaid),
+        });
+        api.registerTool({
+            name: "get_financial_summary",
+            label: "Get Financial Summary",
+            description: "Get a financial summary for a given period",
+            parameters: GetFinancialSummaryInputSchema,
+            execute: wrapExecute(executeGetFinancialSummary),
+        });
+        api.registerTool({
+            name: "list_expenses",
+            label: "List Expenses",
+            description: "List expenses with filters by period, status, category, or search term",
+            parameters: ListExpensesInputSchema,
+            execute: wrapExecute(executeListExpenses),
+        });
+        api.registerTool({
+            name: "list_incomes",
+            label: "List Incomes",
+            description: "List income entries with filters",
+            parameters: ListIncomesInputSchema,
+            execute: wrapExecute(executeListIncomes),
+        });
+        api.registerTool({
+            name: "run_daily_sync",
+            label: "Run Daily Sync",
+            description: "Run the daily sync: generates pending recurring expense instances, marks overdue ones, and returns payment reminders for the day. Invoke from automatic cron or when the user wants to see pending items.",
+            parameters: RunDailySyncInputSchema,
+            execute: wrapExecute(executeRunDailySync),
+        });
+    },
+});