financialclaw 1.0.0

package/dist/src/tools/log-income.js

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDb } from "../db/database.js";
+import { computeNextDate } from "./helpers/date-utils.js";
+import { formatAmount, isPlaceholderCurrency, resolveCurrency, } from "./helpers/currency-utils.js";
+const ISO_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+function isValidCalendarDate(dateStr) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr);
+    if (match === null)
+        return false;
+    const year = Number.parseInt(match[1], 10);
+    const month = Number.parseInt(match[2], 10);
+    const day = Number.parseInt(match[3], 10);
+    const d = new Date(Date.UTC(year, month - 1, day));
+    return (d.getUTCFullYear() === year &&
+        d.getUTCMonth() === month - 1 &&
+        d.getUTCDate() === day);
+}
+export const InputSchema = Type.Object({
+    reason: Type.String({ minLength: 1 }),
+    expected_amount: Type.Number({ minimum: 0 }),
+    currency: Type.Optional(Type.String()),
+    date: Type.String({ pattern: ISO_DATE_PATTERN }),
+    recurring: Type.Optional(Type.Boolean()),
+    frequency: Type.Optional(Type.Union([
+        Type.Literal("WEEKLY"),
+        Type.Literal("BIWEEKLY"),
+        Type.Literal("MONTHLY"),
+        Type.Literal("INTERVAL_DAYS"),
+    ])),
+    interval_days: Type.Optional(Type.Integer({ minimum: 1 })),
+}, { additionalProperties: false });
+export function executeLogIncome(input, db = getDb()) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: reason must not be empty, expected_amount must be >= 0, and date must be in YYYY-MM-DD format.");
+    }
+    const trimmedReason = input.reason.trim();
+    if (trimmedReason.length === 0) {
+        throw new Error("The reason field must not be empty or blank.");
+    }
+    if (!isValidCalendarDate(input.date)) {
+        throw new Error(`The date "${input.date}" is not a valid calendar date.`);
+    }
+    const isRecurring = input.recurring ?? false;
+    if (isRecurring && !input.frequency) {
+        throw new Error("The frequency field is required for recurring income.");
+    }
+    if (input.frequency === "INTERVAL_DAYS" && !input.interval_days) {
+        throw new Error("The interval_days field is required when frequency is INTERVAL_DAYS.");
+    }
+    const currency = resolveCurrency(input.currency, db);
+    const nextDate = isRecurring && input.frequency
+        ? computeNextDate(input.date, input.frequency, input.interval_days ?? 0)
+        : null;
+    const now = new Date().toISOString();
+    const incomeId = randomUUID();
+    const receiptId = randomUUID();
+    db.exec("BEGIN");
+    try {
+        db.prepare(`
+        INSERT INTO incomes (
+          id,
+          reason,
+          expected_amount,
+          currency,
+          date,
+          frequency,
+          interval_days,
+          is_recurring,
+          next_expected_receipt_date,
+          is_active,
+          created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(incomeId, trimmedReason, input.expected_amount, currency.code, input.date, input.frequency ?? null, input.interval_days ?? null, isRecurring ? 1 : 0, nextDate, 1, now);
+        db.prepare(`
+        INSERT INTO income_receipts (
+          id,
+          income_id,
+          amount,
+          currency,
+          date,
+          notes,
+          created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(receiptId, incomeId, input.expected_amount, currency.code, input.date, null, now);
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    const formattedAmount = formatAmount(input.expected_amount, currency);
+    let message = `Income logged: ${formattedAmount} · ${trimmedReason} · ${input.date} (ID: ${incomeId})`;
+    if (nextDate !== null) {
+        message += `\nNext expected receipt: ${nextDate}`;
+    }
+    if (isPlaceholderCurrency(db)) {
+        message +=
+            "\n\nHint: you haven't configured a real currency yet. Use manage_currency to add yours and set it as default.";
+    }
+    return message;
+}

package/dist/src/tools/manage-currency.d.ts

@@ -0,0 +1,10 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"add" | "list" | "set_default">[]>;
+    code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    symbol: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type ManageCurrencyInput = Static<typeof InputSchema>;
+export declare function executeManageCurrency(input: ManageCurrencyInput, db?: DatabaseSync): string;

package/dist/src/tools/manage-currency.js

@@ -0,0 +1,104 @@
+import { Type } from "@sinclair/typebox";
+import { getDb } from "../db/database.js";
+const ACTIONS = ["add", "list", "set_default"];
+export const InputSchema = Type.Object({
+    action: Type.Union(ACTIONS.map((action) => Type.Literal(action))),
+    code: Type.Optional(Type.String()),
+    name: Type.Optional(Type.String()),
+    symbol: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+function requireText(value, fieldName, action) {
+    const normalized = value?.trim();
+    if (normalized === undefined || normalized === "") {
+        throw new Error(`Action ${action} requires the "${fieldName}" field.`);
+    }
+    return normalized;
+}
+function normalizeCode(code, action) {
+    return requireText(code, "code", action).toUpperCase();
+}
+function addCurrency(input, db) {
+    const code = normalizeCode(input.code, "add");
+    const name = requireText(input.name, "name", "add");
+    const symbol = requireText(input.symbol, "symbol", "add");
+    const existingCurrency = db
+        .prepare(`
+        SELECT code
+        FROM currencies
+        WHERE code = ?
+        LIMIT 1
+      `)
+        .get(code);
+    if (existingCurrency !== undefined) {
+        throw new Error(`Currency ${code} already exists. Use a different code or choose set_default.`);
+    }
+    db.prepare(`
+      INSERT INTO currencies (code, name, symbol, is_default)
+      VALUES (?, ?, ?, 0)
+    `).run(code, name, symbol);
+    return `Currency ${code} added successfully.`;
+}
+function listCurrencies(db) {
+    const currencies = db
+        .prepare(`
+        SELECT code, name, symbol, is_default
+        FROM currencies
+        ORDER BY is_default DESC, created_at ASC, code ASC
+      `)
+        .all();
+    if (currencies.length === 0) {
+        return "No currencies registered.";
+    }
+    const lines = currencies.map((currency) => {
+        const prefix = currency.is_default === 1 ? "*" : "-";
+        const suffix = currency.is_default === 1 ? " [default]" : "";
+        return `${prefix} ${currency.code} - ${currency.name} (${currency.symbol})${suffix}`;
+    });
+    return ["Registered currencies:", ...lines].join("\n");
+}
+function setDefaultCurrency(input, db) {
+    const code = normalizeCode(input.code, "set_default");
+    const existingCurrency = db
+        .prepare(`
+        SELECT code
+        FROM currencies
+        WHERE code = ?
+        LIMIT 1
+      `)
+        .get(code);
+    if (existingCurrency === undefined) {
+        throw new Error(`No registered currency found with code ${code}.`);
+    }
+    db.exec("BEGIN");
+    try {
+        db.prepare(`
+        UPDATE currencies
+        SET is_default = 0
+      `).run();
+        db.prepare(`
+        UPDATE currencies
+        SET is_default = 1
+        WHERE code = ?
+      `).run(code);
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    return `Currency ${code} set as default.`;
+}
+export function executeManageCurrency(input, db = getDb()) {
+    switch (input.action) {
+        case "add":
+            return addCurrency(input, db);
+        case "list":
+            return listCurrencies(db);
+        case "set_default":
+            return setDefaultCurrency(input, db);
+        default: {
+            const exhaustiveCheck = input.action;
+            throw new Error(`Unsupported action: ${exhaustiveCheck}`);
+        }
+    }
+}

package/dist/src/tools/mark-expense-paid.d.ts

@@ -0,0 +1,8 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    expense_id: import("@sinclair/typebox").TString;
+    payment_date: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type MarkExpensePaidInput = Static<typeof InputSchema>;
+export declare function executeMarkExpensePaid(input: MarkExpensePaidInput, db?: DatabaseSync): string;

package/dist/src/tools/mark-expense-paid.js

@@ -0,0 +1,44 @@
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDb } from "../db/database.js";
+const ISO_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+export const InputSchema = Type.Object({
+    expense_id: Type.String({ minLength: 1 }),
+    payment_date: Type.Optional(Type.String({ pattern: ISO_DATE_PATTERN })),
+}, { additionalProperties: false });
+function assertValidInput(input) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: expense_id is required and payment_date must be in YYYY-MM-DD format.");
+    }
+    if (input.expense_id.trim() === "") {
+        throw new Error("The expense_id field is required.");
+    }
+}
+export function executeMarkExpensePaid(input, db = getDb()) {
+    assertValidInput(input);
+    const expenseId = input.expense_id;
+    const expense = db
+        .prepare(`
+        SELECT id, status, payment_date, updated_at
+        FROM expenses
+        WHERE id = ?
+      `)
+        .get(expenseId);
+    if (expense === undefined) {
+        throw new Error(`No expense found with ID "${expenseId}".`);
+    }
+    if (expense.status === "PAID") {
+        return `Expense "${expenseId}" was already marked as paid.`;
+    }
+    const paymentDate = input.payment_date ?? new Date().toISOString().slice(0, 10);
+    const updatedAt = new Date().toISOString();
+    db.prepare(`
+      UPDATE expenses
+      SET status = 'PAID',
+          payment_date = ?,
+          updated_at = ?
+      WHERE id = ?
+        AND status != 'PAID'
+    `).run(paymentDate, updatedAt, expenseId);
+    return `Expense "${expenseId}" marked as paid on ${paymentDate}.`;
+}

package/dist/src/tools/run-daily-sync.d.ts

@@ -0,0 +1,5 @@
+import type { Static } from "@sinclair/typebox";
+import { DatabaseSync } from "node:sqlite";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{}>;
+export type Input = Static<typeof InputSchema>;
+export declare function executeRunDailySync(_params: Input, db?: DatabaseSync): Promise<string>;

package/dist/src/tools/run-daily-sync.js

@@ -0,0 +1,85 @@
+import { Type } from "@sinclair/typebox";
+import { getDb } from "../db/database.js";
+import { dailySync } from "../services/daily-sync.js";
+import { formatAmount, resolveCurrency } from "./helpers/currency-utils.js";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.js";
+export const InputSchema = Type.Object({});
+const UPDATE_CHECK_TIMEOUT_MS = 3_000;
+async function fetchLatestVersion(packageName) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => { controller.abort(); }, UPDATE_CHECK_TIMEOUT_MS);
+    try {
+        const encoded = encodeURIComponent(packageName).replace(/^%40/, "@");
+        const response = await fetch(`https://registry.npmjs.org/${encoded}/latest`, { signal: controller.signal });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function isNewerVersion(current, candidate) {
+    const parse = (v) => {
+        const [major = 0, minor = 0, patch = 0] = v.split(".").map(Number);
+        return [major, minor, patch];
+    };
+    const [cMaj, cMin, cPat] = parse(current);
+    const [lMaj, lMin, lPat] = parse(candidate);
+    if (lMaj !== cMaj)
+        return lMaj > cMaj;
+    if (lMin !== cMin)
+        return lMin > cMin;
+    return lPat > cPat;
+}
+function markRemindersSent(db, reminderIds) {
+    if (reminderIds.length === 0) {
+        return;
+    }
+    const stmt = db.prepare(`UPDATE reminders SET sent = 1, sent_at = ? WHERE id = ?`);
+    const now = new Date().toISOString();
+    for (const id of reminderIds) {
+        stmt.run(now, id);
+    }
+}
+function formatReminderLine(description, amount, currency, dueDate, daysBefore, db) {
+    const resolvedCurrency = resolveCurrency(currency, db);
+    const formattedAmount = formatAmount(amount, resolvedCurrency, db);
+    const timing = daysBefore > 0
+        ? `due in ${daysBefore} day${daysBefore > 1 ? "s" : ""} (${dueDate})`
+        : `due today (${dueDate})`;
+    return `• ${description}: ${formattedAmount} — ${timing}`;
+}
+export async function executeRunDailySync(_params, db = getDb()) {
+    const result = dailySync(db);
+    markRemindersSent(db, result.remindersDue.map((r) => r.reminder_id));
+    const lines = [];
+    lines.push(`Daily sync completed:`);
+    lines.push(`• Recurring expenses generated: ${result.expensesGenerated}`);
+    lines.push(`• Expenses marked as overdue: ${result.expensesMarkedOverdue}`);
+    if (result.remindersDue.length === 0) {
+        lines.push(`• No pending reminders — finances up to date ✓`);
+    }
+    else {
+        lines.push(`\nPending reminders (${result.remindersDue.length}):`);
+        for (const reminder of result.remindersDue) {
+            lines.push(formatReminderLine(reminder.description, reminder.amount, reminder.currency, reminder.due_date, reminder.days_before, db));
+        }
+    }
+    try {
+        const latestVersion = await fetchLatestVersion(PACKAGE_NAME);
+        if (latestVersion !== null && isNewerVersion(PACKAGE_VERSION, latestVersion)) {
+            lines.push(`\n⚠️ Update available: v${PACKAGE_VERSION} → v${latestVersion}`);
+            lines.push(`   To update: openclaw plugins update financialclaw && openclaw gateway restart`);
+        }
+    }
+    catch {
+        // Update check is non-critical — must never break the sync
+    }
+    return lines.join("\n");
+}

package/dist/src/version.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_NAME = "financialclaw";
+export declare const PACKAGE_VERSION = "1.0.0";

package/dist/src/version.js

@@ -0,0 +1,2 @@
+export const PACKAGE_NAME = "financialclaw";
+export const PACKAGE_VERSION = "1.0.0"; // x-release-please-version

package/openclaw.plugin.json

@@ -0,0 +1,24 @@
+{
+  "id": "financialclaw",
+  "name": "FinancialClaw",
+  "description": "Personal finance plugin: expenses, income, recurring payments, and receipt OCR",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "dbPath": {
+        "type": "string"
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "dbPath": {
+      "label": "Database path",
+      "help": "Absolute path to the SQLite database file. Defaults to ~/.openclaw/workspace/financialclaw.db",
+      "placeholder": "/home/user/.openclaw/workspace/financialclaw.db"
+    }
+  },
+  "skills": [
+    "skills/financialclaw"
+  ]
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "financialclaw",
+  "version": "1.0.0",
+  "description": "Personal finance plugin for OpenClaw: expenses, income, recurring payments, and receipt OCR",
+  "type": "module",
+  "bin": {
+    "financialclaw-setup": "bin/financialclaw-setup.mjs"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/src/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24",
+      "minGatewayVersion": "2026.3.24"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24",
+      "pluginSdkVersion": "2026.3.24"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "node bin/postinstall-message.mjs",
+    "test": "tsx --test tests/**/*.test.ts",
+    "test:unit": "tsx --test tests/unit/**/*.test.ts",
+    "test:integration": "tsx --test tests/integration/**/*.test.ts"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "openclaw": "^2026.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "bin/",
+    "dist/src/",
+    "skills/",
+    "openclaw.plugin.json"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}