financialclaw 1.0.0

package/dist/src/tools/list-expenses.js

@@ -0,0 +1,142 @@
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDb } from "../db/database.js";
+import { resolvePeriodRange } from "./helpers/date-utils.js";
+import { resolveCurrency, formatAmount } from "./helpers/currency-utils.js";
+export const InputSchema = Type.Object({
+    period: Type.Optional(Type.Union([
+        Type.Literal("this_month"),
+        Type.Literal("last_month"),
+        Type.Literal("last_30_days"),
+        Type.Literal("this_year"),
+        Type.Literal("all"),
+    ])),
+    start_date: Type.Optional(Type.String({ pattern: "^\\d{4}-\\d{2}-\\d{2}$" })),
+    end_date: Type.Optional(Type.String({ pattern: "^\\d{4}-\\d{2}-\\d{2}$" })),
+    category: Type.Optional(Type.String()),
+    status: Type.Optional(Type.Union([
+        Type.Literal("PENDING"),
+        Type.Literal("PAID"),
+        Type.Literal("OVERDUE"),
+    ])),
+    search: Type.Optional(Type.String()),
+    currency: Type.Optional(Type.String()),
+    source: Type.Optional(Type.Union([
+        Type.Literal("MANUAL"),
+        Type.Literal("OCR"),
+    ])),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false });
+function assertValidInput(input) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: check the types of period, status, source, limit, offset, and date format (YYYY-MM-DD).");
+    }
+}
+function validateDateRange(startDate, endDate) {
+    if (startDate !== undefined && endDate === undefined) {
+        throw new Error("If you provide start_date, you must also provide end_date.");
+    }
+    if (startDate === undefined && endDate !== undefined) {
+        throw new Error("If you provide end_date, you must also provide start_date.");
+    }
+    if (startDate !== undefined && endDate !== undefined) {
+        if (startDate > endDate) {
+            throw new Error("start_date cannot be greater than end_date.");
+        }
+    }
+}
+export function executeListExpenses(input, db = getDb()) {
+    assertValidInput(input);
+    const limit = input.limit ?? 20;
+    const offset = input.offset ?? 0;
+    validateDateRange(input.start_date, input.end_date);
+    let dateRange = null;
+    if (input.start_date && input.end_date) {
+        dateRange = { start: input.start_date, end: input.end_date };
+    }
+    else if (input.period) {
+        dateRange = resolvePeriodRange(input.period);
+    }
+    else {
+        dateRange = resolvePeriodRange("this_month");
+    }
+    const currencyRow = input.currency
+        ? resolveCurrency(input.currency, db)
+        : null;
+    const params = [];
+    const conditions = ["is_active = 1"];
+    if (dateRange) {
+        conditions.push("due_date >= ? AND due_date <= ?");
+        params.push(dateRange.start, dateRange.end);
+    }
+    if (input.category) {
+        conditions.push("category = ?");
+        params.push(input.category.toUpperCase());
+    }
+    if (input.status) {
+        conditions.push("status = ?");
+        params.push(input.status);
+    }
+    if (input.search) {
+        const searchTerm = `%${input.search}%`;
+        conditions.push("(description LIKE ? OR merchant LIKE ?)");
+        params.push(searchTerm, searchTerm);
+    }
+    if (currencyRow) {
+        conditions.push("currency = ?");
+        params.push(currencyRow.code);
+    }
+    if (input.source) {
+        conditions.push("source = ?");
+        params.push(input.source);
+    }
+    const whereClause = conditions.join(" AND ");
+    const countSql = `SELECT COUNT(*) as total FROM expenses WHERE ${whereClause}`;
+    const countResult = db.prepare(countSql).get(...params);
+    const total = countResult.total;
+    const orderClause = "ORDER BY due_date DESC";
+    const paginatedParams = [...params, limit, offset];
+    const sql = `SELECT id, amount, currency, category, merchant, description,
+    due_date, payment_date, status, source, created_at
+  FROM expenses
+  WHERE ${whereClause}
+  ${orderClause}
+  LIMIT ? OFFSET ?`;
+    const rows = db.prepare(sql).all(...paginatedParams);
+    if (rows.length === 0) {
+        const hint = total === 0
+            ? "No expenses recorded."
+            : `No expenses on the requested page (total: ${total}).`;
+        return `${hint}\n\nTry different filters or change the offset.`;
+    }
+    const currencyCache = new Map();
+    function getCurrencyRow(code) {
+        if (!currencyCache.has(code)) {
+            currencyCache.set(code, resolveCurrency(code, db));
+        }
+        return currencyCache.get(code);
+    }
+    const lines = [
+        `📋 Expenses (${rows.length} of ${total} total)`,
+        "",
+    ];
+    for (const row of rows) {
+        const curr = getCurrencyRow(row.currency);
+        const formattedAmount = formatAmount(row.amount, curr, db);
+        const date = row.due_date;
+        const category = row.category || "UNCATEGORIZED";
+        const merchant = row.merchant ? ` - ${row.merchant}` : "";
+        const statusIcon = row.status === "PAID" ? "✓" : row.status === "OVERDUE" ? "⚠" : "○";
+        const sourceTag = row.source === "OCR" ? " [OCR]" : "";
+        lines.push(`${date} ${statusIcon} ${formattedAmount}${sourceTag}`, `   ${row.description}${merchant}`, `   ${category} • ${row.status}`, `   ID: ${row.id}`, "");
+    }
+    if (total > limit + offset) {
+        const nextOffset = offset + limit;
+        lines.push(`→ More results available. Use offset=${nextOffset} to see the next page.`);
+    }
+    else if (offset > 0) {
+        lines.push("← End of results.");
+    }
+    return lines.join("\n");
+}

package/dist/src/tools/list-incomes.d.ts

@@ -0,0 +1,12 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    recurring: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    include_receipts: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type Input = Static<typeof InputSchema>;
+export declare function executeListIncomes(input: Input, db?: DatabaseSync): string;

package/dist/src/tools/list-incomes.js

@@ -0,0 +1,124 @@
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDb } from "../db/database.js";
+import { resolveCurrency, formatAmount } from "./helpers/currency-utils.js";
+export const InputSchema = Type.Object({
+    recurring: Type.Optional(Type.Boolean()),
+    search: Type.Optional(Type.String()),
+    currency: Type.Optional(Type.String()),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    include_receipts: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+function assertValidInput(input) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: check the types of recurring, search, currency, limit, offset, and include_receipts.");
+    }
+}
+export function executeListIncomes(input, db = getDb()) {
+    assertValidInput(input);
+    const limit = input.limit ?? 20;
+    const offset = input.offset ?? 0;
+    const includeReceipts = input.include_receipts ?? false;
+    if (input.currency !== undefined) {
+        resolveCurrency(input.currency, db);
+    }
+    const conditions = ["1=1"];
+    const params = [];
+    if (input.recurring !== undefined) {
+        conditions.push(`is_recurring = ?`);
+        params.push(input.recurring ? 1 : 0);
+    }
+    if (input.search !== undefined && input.search.trim().length > 0) {
+        conditions.push(`reason LIKE ?`);
+        params.push(`%${input.search.trim()}%`);
+    }
+    if (input.currency !== undefined) {
+        conditions.push(`currency = ?`);
+        params.push(input.currency.trim().toUpperCase());
+    }
+    const whereClause = conditions.join(" AND ");
+    const countSql = `SELECT COUNT(*) as total FROM incomes WHERE ${whereClause}`;
+    const countResult = db.prepare(countSql).get(...params);
+    const total = countResult.total;
+    const listSql = `
+    SELECT id, reason, expected_amount, currency, date, frequency,
+           interval_days, is_recurring, next_expected_receipt_date,
+           is_active, created_at
+    FROM incomes
+    WHERE ${whereClause}
+    ORDER BY created_at DESC
+    LIMIT ? OFFSET ?
+  `;
+    const incomes = db.prepare(listSql).all(...params, limit, offset);
+    if (incomes.length === 0) {
+        return `No income entries recorded${total > 0 ? ` (total: ${total})` : ""}.`;
+    }
+    const currencyCache = new Map();
+    const getCurrency = (code) => {
+        if (!currencyCache.has(code)) {
+            currencyCache.set(code, resolveCurrency(code, db));
+        }
+        return currencyCache.get(code);
+    };
+    let receiptsByIncomeId;
+    if (includeReceipts) {
+        const incomeIds = incomes.map((i) => i.id);
+        if (incomeIds.length > 0) {
+            const placeholders = incomeIds.map(() => "?").join(",");
+            const receiptsSql = `
+        SELECT id, income_id, amount, currency, date, notes, created_at FROM (
+          SELECT *, ROW_NUMBER() OVER (PARTITION BY income_id ORDER BY date DESC) as rn
+          FROM income_receipts
+          WHERE income_id IN (${placeholders})
+        ) WHERE rn <= 5
+        ORDER BY income_id, date DESC
+      `;
+            const allReceipts = db.prepare(receiptsSql).all(...incomeIds);
+            receiptsByIncomeId = new Map();
+            for (const receipt of allReceipts) {
+                const existing = receiptsByIncomeId.get(receipt.income_id) ?? [];
+                existing.push(receipt);
+                receiptsByIncomeId.set(receipt.income_id, existing);
+            }
+        }
+    }
+    const lines = [];
+    lines.push(`📋 Income (${incomes.length}${total > limit ? ` of ${total}` : ""}):`);
+    for (const income of incomes) {
+        const currency = getCurrency(income.currency);
+        const formattedAmount = formatAmount(income.expected_amount, currency);
+        const recurrence = income.is_recurring === 1
+            ? ` [${income.frequency}${income.interval_days ? ` (every ${income.interval_days} days)` : ""}]`
+            : "";
+        const nextDate = income.next_expected_receipt_date
+            ? ` | Next: ${income.next_expected_receipt_date}`
+            : "";
+        const status = income.is_active === 1 ? "" : " (INACTIVE)";
+        lines.push(`- ${income.reason}${recurrence}${status}: ${formattedAmount} (expected: ${income.date})${nextDate}`);
+        lines.push(`  ID: ${income.id}`);
+        if (includeReceipts && receiptsByIncomeId) {
+            const receipts = receiptsByIncomeId.get(income.id);
+            if (receipts && receipts.length > 0) {
+                for (const receipt of receipts) {
+                    const recCurrency = getCurrency(receipt.currency);
+                    const recAmount = formatAmount(receipt.amount, recCurrency);
+                    const note = receipt.notes ? ` - ${receipt.notes}` : "";
+                    lines.push(`  └─ Received: ${recAmount} (${receipt.date})${note}`);
+                }
+            }
+            else {
+                lines.push(`  └─ No receipts recorded`);
+            }
+        }
+    }
+    if (total > limit + offset) {
+        lines.push("");
+        lines.push(`💡 More results available. Use offset=${offset + limit} to see more.`);
+    }
+    else if (offset > 0 && incomes.length > 0) {
+        lines.push("");
+        lines.push("ℹ️ End of results.");
+    }
+    return lines.join("\n");
+}

package/dist/src/tools/log-expense-from-receipt.d.ts

@@ -0,0 +1,13 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    amount: import("@sinclair/typebox").TNumber;
+    date: import("@sinclair/typebox").TString;
+    merchant: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    category: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    raw_text: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type LogExpenseFromReceiptInput = Static<typeof InputSchema>;
+export declare function executeLogExpenseFromReceipt(input: LogExpenseFromReceiptInput, db?: DatabaseSync): string;

package/dist/src/tools/log-expense-from-receipt.js

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDb } from "../db/database.js";
+import { formatAmount, isPlaceholderCurrency, resolveCurrency, } from "./helpers/currency-utils.js";
+const ISO_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+export const InputSchema = Type.Object({
+    amount: Type.Number({ minimum: 0.01 }),
+    date: Type.String({ pattern: ISO_DATE_PATTERN }),
+    merchant: Type.Optional(Type.String()),
+    category: Type.Optional(Type.String()),
+    currency: Type.Optional(Type.String()),
+    raw_text: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+function assertValidInput(input) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: amount is required and must be greater than 0, date is required in YYYY-MM-DD format.");
+    }
+    if (input.description !== undefined && input.description.trim().length === 0) {
+        throw new Error("description must not be blank.");
+    }
+    if (input.merchant !== undefined && input.merchant.trim().length === 0) {
+        throw new Error("merchant must not be blank.");
+    }
+    if (input.category !== undefined && input.category.trim().length === 0) {
+        throw new Error("category must not be blank.");
+    }
+    if (input.raw_text !== undefined && input.raw_text.trim().length === 0) {
+        throw new Error("raw_text must not be blank.");
+    }
+}
+export function executeLogExpenseFromReceipt(input, db = getDb()) {
+    assertValidInput(input);
+    const currency = resolveCurrency(input.currency, db);
+    const now = new Date().toISOString();
+    // Process inputs
+    const amount = input.amount;
+    const date = input.date;
+    const merchant = input.merchant?.trim() ?? null;
+    const category = (input.category?.trim() ?? "OTHER").toUpperCase();
+    const rawText = input.raw_text?.trim() ?? null;
+    const description = input.description?.trim();
+    // Determine description if not provided
+    const descriptionFinal = description ??
+        (merchant ? `Expense at ${merchant}` : "OCR expense");
+    // Generate IDs
+    const extractionId = randomUUID();
+    const expenseId = randomUUID();
+    // Use transaction for atomicity
+    db.exec("BEGIN");
+    try {
+        // Insert into ocr_extractions
+        db.prepare(`
+        INSERT INTO ocr_extractions (
+          id, provider, source_path, raw_text, lines_json,
+          average_confidence, suggested_amount, suggested_currency,
+          suggested_date, suggested_merchant, suggested_category,
+          status, failure_code, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(extractionId, "openclaw_agent", null, // source_path not applicable for agentic OCR
+        rawText, null, // lines_json not applicable for agentic OCR
+        null, // average_confidence not applicable for agentic OCR
+        amount, currency.code, date, merchant, category, "COMPLETED", null, // failure_code
+        now);
+        // Insert into expenses
+        db.prepare(`
+        INSERT INTO expenses (
+          id, amount, currency, category, merchant, description,
+          due_date, payment_date, status, source,
+          ocr_extraction_id, recurring_rule_id, generated_from_rule,
+          is_active, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(expenseId, amount, currency.code, category, merchant, descriptionFinal, date, date, "PAID", "OCR", extractionId, null, 0, 1, now, now);
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    // Format response
+    const formattedAmount = formatAmount(amount, currency);
+    const merchantPart = merchant ? ` — ${merchant}` : "";
+    const categoryPart = category !== "OTHER" ? ` [${category}]` : "";
+    let message = `OCR expense logged: ${formattedAmount}${categoryPart} · ${descriptionFinal}${merchantPart} · ${date} · Paid (ID: ${expenseId})`;
+    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/log-expense-manual.d.ts

@@ -0,0 +1,12 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    amount: import("@sinclair/typebox").TNumber;
+    description: import("@sinclair/typebox").TString;
+    due_date: import("@sinclair/typebox").TString;
+    category: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    merchant: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type LogExpenseManualInput = Static<typeof InputSchema>;
+export declare function executeLogExpenseManual(input: LogExpenseManualInput, db?: DatabaseSync): string;

package/dist/src/tools/log-expense-manual.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDb } from "../db/database.js";
+import { todayISO } from "./helpers/date-utils.js";
+import { formatAmount, isPlaceholderCurrency, resolveCurrency, } from "./helpers/currency-utils.js";
+const ISO_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+export const InputSchema = Type.Object({
+    amount: Type.Number({ exclusiveMinimum: 0 }),
+    description: Type.String({ minLength: 1 }),
+    due_date: Type.String({ pattern: ISO_DATE_PATTERN }),
+    category: Type.Optional(Type.String()),
+    currency: Type.Optional(Type.String()),
+    merchant: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+function assertValidInput(input) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: amount must be greater than 0, description must not be empty, and due_date must be in YYYY-MM-DD format.");
+    }
+}
+export function executeLogExpenseManual(input, db = getDb()) {
+    assertValidInput(input);
+    const currency = resolveCurrency(input.currency, db);
+    const category = input.category?.trim() || "OTHER";
+    const today = todayISO();
+    const isPaid = input.due_date <= today;
+    const status = isPaid ? "PAID" : "PENDING";
+    const paymentDate = isPaid ? input.due_date : null;
+    const now = new Date().toISOString();
+    const id = randomUUID();
+    db.prepare(`
+      INSERT INTO expenses (
+        id,
+        amount,
+        currency,
+        category,
+        merchant,
+        description,
+        due_date,
+        payment_date,
+        status,
+        source,
+        ocr_extraction_id,
+        recurring_rule_id,
+        generated_from_rule,
+        is_active,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.amount, currency.code, category, input.merchant ?? null, input.description, input.due_date, paymentDate, status, "MANUAL", null, null, 0, 1, now, now);
+    const formattedAmount = formatAmount(input.amount, currency);
+    const statusLabel = status === "PAID" ? "paid" : "pending";
+    const merchantPart = input.merchant != null ? ` — ${input.merchant}` : "";
+    let message = `Expense logged: ${formattedAmount} · ${input.description}${merchantPart} · ${input.due_date} · ${statusLabel} (ID: ${id})`;
+    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/log-income-receipt.d.ts

@@ -0,0 +1,11 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    income_id: import("@sinclair/typebox").TString;
+    received_amount: import("@sinclair/typebox").TNumber;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    received_on: import("@sinclair/typebox").TString;
+    note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type LogIncomeReceiptInput = Static<typeof InputSchema>;
+export declare function executeLogIncomeReceipt(input: LogIncomeReceiptInput, db?: DatabaseSync): string;

package/dist/src/tools/log-income-receipt.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, PLACEHOLDER_CURRENCY, 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({
+    income_id: Type.String({ minLength: 1 }),
+    received_amount: Type.Number({ minimum: 0 }),
+    currency: Type.Optional(Type.String()),
+    received_on: Type.String({ pattern: ISO_DATE_PATTERN }),
+    note: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+export function executeLogIncomeReceipt(input, db = getDb()) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: income_id must not be empty, received_amount must be >= 0, and received_on must be in YYYY-MM-DD format.");
+    }
+    if (!isValidCalendarDate(input.received_on)) {
+        throw new Error(`The date "${input.received_on}" is not a valid calendar date.`);
+    }
+    // 1. Look up income by income_id
+    const income = db
+        .prepare(`SELECT id, reason, expected_amount, currency, date, frequency, interval_days, is_recurring, next_expected_receipt_date
+       FROM incomes WHERE id = ?`)
+        .get(input.income_id);
+    if (income === undefined) {
+        throw new Error(`No income found with ID "${input.income_id}".`);
+    }
+    // 2. Resolve effective currency
+    let currency;
+    const trimmedCurrency = input.currency?.trim();
+    if (trimmedCurrency) {
+        // Validate explicitly provided currency (ignore if whitespace-only)
+        currency = resolveCurrency(trimmedCurrency, db);
+    }
+    else {
+        // Use the currency stored on the income (not the global default)
+        const incomeCurrency = db
+            .prepare(`SELECT code, name, symbol, is_default FROM currencies WHERE code = ?`)
+            .get(income.currency);
+        if (incomeCurrency === undefined) {
+            throw new Error(`The income currency (${income.currency}) is not registered in the database.`);
+        }
+        currency = incomeCurrency;
+    }
+    // 3. Compute next date if income is recurring
+    const isRecurring = income.is_recurring === 1;
+    let nextDate = null;
+    if (isRecurring && income.frequency) {
+        nextDate = computeNextDate(input.received_on, income.frequency, income.interval_days ?? 0);
+    }
+    // 4. Insert receipt and update income (atomic)
+    const receiptId = randomUUID();
+    const now = new Date().toISOString();
+    db.exec("BEGIN");
+    try {
+        db.prepare(`INSERT INTO income_receipts (id, income_id, amount, currency, date, notes, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(receiptId, input.income_id, input.received_amount, currency.code, input.received_on, input.note ?? null, now);
+        if (isRecurring && nextDate !== null) {
+            db.prepare(`UPDATE incomes SET next_expected_receipt_date = ? WHERE id = ?`).run(nextDate, input.income_id);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    // 5. Format response
+    const formattedReceived = formatAmount(input.received_amount, currency);
+    let message = `Receipt logged: ${formattedReceived} · ${income.reason} · ${input.received_on} (ID: ${receiptId})`;
+    // Difference vs expected_amount
+    const diff = input.received_amount - income.expected_amount;
+    if (diff !== 0) {
+        const formattedDiff = formatAmount(Math.abs(diff), currency);
+        if (diff > 0) {
+            message += `\nDifference: +${formattedDiff} above expected amount.`;
+        }
+        else {
+            message += `\nDifference: -${formattedDiff} below expected amount.`;
+        }
+    }
+    if (nextDate !== null) {
+        message += `\nNext expected receipt: ${nextDate}`;
+    }
+    if (currency.code === PLACEHOLDER_CURRENCY) {
+        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/log-income.d.ts

@@ -0,0 +1,13 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    reason: import("@sinclair/typebox").TString;
+    expected_amount: import("@sinclair/typebox").TNumber;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    date: import("@sinclair/typebox").TString;
+    recurring: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    frequency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"WEEKLY">, import("@sinclair/typebox").TLiteral<"BIWEEKLY">, import("@sinclair/typebox").TLiteral<"MONTHLY">, import("@sinclair/typebox").TLiteral<"INTERVAL_DAYS">]>>;
+    interval_days: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export type LogIncomeInput = Static<typeof InputSchema>;
+export declare function executeLogIncome(input: LogIncomeInput, db?: DatabaseSync): string;