financialclaw 1.0.0

package/dist/src/services/daily-sync.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseSync } from "node:sqlite";
+export interface DailySyncReminder {
+    expense_id: string;
+    reminder_id: string;
+    description: string;
+    amount: number;
+    currency: string;
+    due_date: string;
+    days_before: number;
+}
+export interface DailySyncResult {
+    expensesGenerated: number;
+    expensesMarkedOverdue: number;
+    remindersDue: DailySyncReminder[];
+}
+export declare function dailySync(db?: DatabaseSync, today?: string): DailySyncResult;

package/dist/src/services/daily-sync.js

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { getDb } from "../db/database.js";
+import { computeNextDate, todayISO } from "../tools/helpers/date-utils.js";
+function subtractDaysFromIso(dateStr, days) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr);
+    if (match === null) {
+        throw new Error(`La fecha "${dateStr}" no tiene el formato YYYY-MM-DD.`);
+    }
+    const [, yearPart, monthPart, dayPart] = match;
+    const year = Number.parseInt(yearPart, 10);
+    const month = Number.parseInt(monthPart, 10);
+    const day = Number.parseInt(dayPart, 10);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    date.setUTCDate(date.getUTCDate() - days);
+    return [
+        date.getUTCFullYear(),
+        String(date.getUTCMonth() + 1).padStart(2, "0"),
+        String(date.getUTCDate()).padStart(2, "0"),
+    ].join("-");
+}
+function nextDueDate(rule, lastGeneratedDate) {
+    if (lastGeneratedDate === null) {
+        return rule.starts_on;
+    }
+    return computeNextDate(lastGeneratedDate, rule.frequency, rule.interval_days ?? 0);
+}
+export function dailySync(db = getDb(), today = todayISO()) {
+    const selectRulesStmt = db.prepare(`
+    SELECT
+      id,
+      name,
+      amount,
+      category,
+      currency,
+      frequency,
+      interval_days,
+      starts_on,
+      ends_on,
+      reminder_days_before
+    FROM recurring_expense_rules
+    WHERE is_active = 1
+    ORDER BY starts_on ASC, created_at ASC
+  `);
+    const selectLastDateStmt = db.prepare(`
+    SELECT MAX(due_date) AS last_date
+    FROM expenses
+    WHERE recurring_rule_id = ? AND generated_from_rule = 1
+  `);
+    const insertExpenseStmt = 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const insertReminderStmt = db.prepare(`
+    INSERT INTO reminders (
+      id,
+      expense_id,
+      scheduled_date,
+      days_before,
+      sent,
+      created_at
+    ) VALUES (?, ?, ?, ?, ?, ?)
+  `);
+    const markOverdueStmt = db.prepare(`
+    UPDATE expenses
+    SET status = 'OVERDUE', updated_at = ?
+    WHERE status = 'PENDING' AND due_date < ? AND is_active = 1
+  `);
+    const selectRemindersDueStmt = db.prepare(`
+    SELECT
+      r.id AS reminder_id,
+      r.expense_id,
+      e.description,
+      e.amount,
+      e.currency,
+      e.due_date,
+      r.days_before
+    FROM reminders r
+    JOIN expenses e ON e.id = r.expense_id
+    WHERE r.scheduled_date <= ? AND r.sent = 0
+    ORDER BY e.due_date ASC, r.scheduled_date ASC, r.id ASC
+  `);
+    db.exec("BEGIN");
+    let expensesGenerated = 0;
+    let expensesMarkedOverdue = 0;
+    try {
+        const recurringRules = selectRulesStmt.all();
+        const now = new Date().toISOString();
+        for (const rule of recurringRules) {
+            const lastExpense = selectLastDateStmt.get(rule.id);
+            let dueDate = nextDueDate(rule, lastExpense?.last_date ?? null);
+            while (dueDate <= today) {
+                if (rule.ends_on !== null && dueDate > rule.ends_on) {
+                    break;
+                }
+                const expenseId = randomUUID();
+                insertExpenseStmt.run(expenseId, rule.amount, rule.currency, rule.category, null, rule.name, dueDate, null, "PENDING", "MANUAL", null, rule.id, 1, 1, now, now);
+                expensesGenerated += 1;
+                if (rule.reminder_days_before > 0) {
+                    insertReminderStmt.run(randomUUID(), expenseId, subtractDaysFromIso(dueDate, rule.reminder_days_before), rule.reminder_days_before, 0, now);
+                }
+                dueDate = computeNextDate(dueDate, rule.frequency, rule.interval_days ?? 0);
+            }
+        }
+        const overdueResult = markOverdueStmt.run(now, today);
+        expensesMarkedOverdue = overdueResult.changes;
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    const mutationResult = { expensesGenerated, expensesMarkedOverdue };
+    const remindersDue = selectRemindersDueStmt.all(today);
+    return {
+        expensesGenerated: mutationResult.expensesGenerated,
+        expensesMarkedOverdue: mutationResult.expensesMarkedOverdue,
+        remindersDue,
+    };
+}

package/dist/src/tools/add-recurring-expense.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    description: import("@sinclair/typebox").TString;
+    amount: import("@sinclair/typebox").TNumber;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    category: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    merchant: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    frequency: 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>;
+    starts_on: import("@sinclair/typebox").TString;
+    ends_on: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    reminder_days_before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export type AddRecurringExpenseInput = Static<typeof InputSchema>;
+export declare function executeAddRecurringExpense(input: AddRecurringExpenseInput, db?: DatabaseSync): string;

package/dist/src/tools/add-recurring-expense.js

@@ -0,0 +1,126 @@
+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);
+}
+function subtractDaysFromIso(dateStr, days) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr);
+    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));
+    d.setUTCDate(d.getUTCDate() - days);
+    return [
+        d.getUTCFullYear(),
+        String(d.getUTCMonth() + 1).padStart(2, "0"),
+        String(d.getUTCDate()).padStart(2, "0"),
+    ].join("-");
+}
+export const InputSchema = Type.Object({
+    description: Type.String({ minLength: 1 }),
+    amount: Type.Number({ minimum: 0 }),
+    currency: Type.Optional(Type.String()),
+    category: Type.Optional(Type.String()),
+    merchant: Type.Optional(Type.String()),
+    frequency: Type.Union([
+        Type.Literal("WEEKLY"),
+        Type.Literal("BIWEEKLY"),
+        Type.Literal("MONTHLY"),
+        Type.Literal("INTERVAL_DAYS"),
+    ]),
+    interval_days: Type.Optional(Type.Integer({ minimum: 1 })),
+    starts_on: Type.String({ pattern: ISO_DATE_PATTERN }),
+    ends_on: Type.Optional(Type.String({ pattern: ISO_DATE_PATTERN })),
+    reminder_days_before: Type.Optional(Type.Integer({ minimum: 1 })),
+}, { additionalProperties: false });
+export function executeAddRecurringExpense(input, db = getDb()) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: check description, amount, frequency, and starts_on.");
+    }
+    const trimmedDescription = input.description.trim();
+    if (trimmedDescription.length === 0) {
+        throw new Error("The description field must not be empty or blank.");
+    }
+    if (!isValidCalendarDate(input.starts_on)) {
+        throw new Error(`The starts_on date "${input.starts_on}" is not a valid calendar date.`);
+    }
+    if (input.ends_on !== undefined && !isValidCalendarDate(input.ends_on)) {
+        throw new Error(`The ends_on date "${input.ends_on}" is not a valid calendar date.`);
+    }
+    if (input.ends_on !== undefined && input.starts_on > input.ends_on) {
+        throw new Error(`The starts_on date "${input.starts_on}" cannot be later than ends_on "${input.ends_on}".`);
+    }
+    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?.trim(), db);
+    const category = input.category?.trim() || "OTHER";
+    // Pre-compute reminder date if applicable (used in transaction and response)
+    const scheduledDate = input.reminder_days_before !== undefined
+        ? subtractDaysFromIso(input.starts_on, input.reminder_days_before)
+        : null;
+    const nextDate = computeNextDate(input.starts_on, input.frequency, input.interval_days ?? 0);
+    const ruleId = randomUUID();
+    const expenseId = randomUUID();
+    const now = new Date().toISOString();
+    db.exec("BEGIN");
+    try {
+        // 1. Insert recurring rule
+        // day_of_month stays NULL (MONTHLY anchors to the day of starts_on)
+        db.prepare(`INSERT INTO recurring_expense_rules (
+        id, name, amount, category, currency, frequency,
+        interval_days, day_of_month, starts_on, ends_on,
+        reminder_days_before, is_active, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(ruleId, trimmedDescription, input.amount, category, currency.code, input.frequency, input.interval_days ?? null, null, input.starts_on, input.ends_on ?? null, input.reminder_days_before ?? 0, 1, now);
+        // 2. Insert first expense generated by the rule
+        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, input.amount, currency.code, category, input.merchant ?? null, trimmedDescription, input.starts_on, null, "PENDING", "MANUAL", null, ruleId, 1, 1, now, now);
+        // 3. Insert first reminder if applicable
+        if (scheduledDate !== null && input.reminder_days_before !== undefined) {
+            db.prepare(`INSERT INTO reminders (id, expense_id, scheduled_date, days_before, sent, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`).run(randomUUID(), expenseId, scheduledDate, input.reminder_days_before, 0, now);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    // Format response
+    const formattedAmount = formatAmount(input.amount, currency);
+    let message = `Rule created: ${formattedAmount} · ${trimmedDescription} · ${input.frequency} from ${input.starts_on} (rule: ${ruleId})`;
+    message += `\nFirst expense generated due on ${input.starts_on} (expense: ${expenseId})`;
+    const nextDateWithinWindow = input.ends_on === undefined || nextDate <= input.ends_on;
+    if (nextDateWithinWindow) {
+        message += `\nNext date: ${nextDate}`;
+    }
+    else {
+        message += `\nNo next occurrence within the validity window (ends_on: ${input.ends_on}).`;
+    }
+    if (scheduledDate !== null) {
+        message += `\nReminder scheduled for ${scheduledDate} (${input.reminder_days_before} days before)`;
+    }
+    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/get-financial-summary.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<{
+    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"this_month">, import("@sinclair/typebox").TLiteral<"last_month">, import("@sinclair/typebox").TLiteral<"last_30_days">, import("@sinclair/typebox").TLiteral<"this_year">]>>;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type GetFinancialSummaryInput = Static<typeof InputSchema>;
+export declare function executeGetFinancialSummary(input: GetFinancialSummaryInput, db?: DatabaseSync): string;

package/dist/src/tools/get-financial-summary.js

@@ -0,0 +1,158 @@
+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 { formatAmount, resolveCurrency, } 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"),
+    ])),
+    currency: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+const PERIOD_LABELS = {
+    this_month: "this month",
+    last_month: "last month",
+    last_30_days: "last 30 days",
+    this_year: "this year",
+    all: "all",
+};
+function monthlyEquivalent(amount, frequency, intervalDays) {
+    switch (frequency) {
+        case "MONTHLY":
+            return amount;
+        case "WEEKLY":
+            return Math.round(amount * 4.33);
+        case "BIWEEKLY":
+            return Math.round(amount * 2.17);
+        case "INTERVAL_DAYS":
+            return intervalDays ? Math.round((amount * 30) / intervalDays) : amount;
+        default:
+            return amount;
+    }
+}
+export function executeGetFinancialSummary(input, db = getDb()) {
+    if (!Value.Check(InputSchema, input)) {
+        throw new Error("Invalid parameters: period must be one of: this_month, last_month, last_30_days, this_year.");
+    }
+    const period = (input.period ?? "this_month");
+    const range = resolvePeriodRange(period);
+    if (!range) {
+        throw new Error("The 'all' period is not supported by get_financial_summary.");
+    }
+    // Validate currency filter if provided — throws descriptively if not registered
+    const filterCode = input.currency?.trim() || undefined;
+    if (filterCode) {
+        resolveCurrency(filterCode, db);
+    }
+    const filter = filterCode ?? null;
+    // ── Queries ────────────────────────────────────────────────────────────────
+    // Total expenses by currency and category within the period
+    const expenseByCat = db
+        .prepare(`SELECT currency, category, SUM(amount) AS total
+       FROM expenses
+       WHERE due_date BETWEEN ? AND ? AND is_active = 1
+         AND (? IS NULL OR currency = ?)
+       GROUP BY currency, category`)
+        .all(range.start, range.end, filter, filter);
+    // Pending expenses by currency within the period
+    const pendingByCurrency = db
+        .prepare(`SELECT currency, SUM(amount) AS total
+       FROM expenses
+       WHERE status = 'PENDING' AND due_date BETWEEN ? AND ? AND is_active = 1
+         AND (? IS NULL OR currency = ?)
+       GROUP BY currency`)
+        .all(range.start, range.end, filter, filter);
+    // Income received by currency within the period
+    // (income_receipts.amount / income_receipts.date — real columns, not doc aliases)
+    const incomeByCurrency = db
+        .prepare(`SELECT currency, SUM(amount) AS total
+       FROM income_receipts
+       WHERE date BETWEEN ? AND ?
+         AND (? IS NULL OR currency = ?)
+       GROUP BY currency`)
+        .all(range.start, range.end, filter, filter);
+    // Active recurring rules — independent of the period
+    // recurring_expense_rules.name = what the user called "description" in the input
+    const rules = db
+        .prepare(`SELECT name, amount, currency, frequency, interval_days
+       FROM recurring_expense_rules
+       WHERE is_active = 1
+         AND (? IS NULL OR currency = ?)`)
+        .all(filter, filter);
+    // ── Collect all relevant currencies ───────────────────────────────────────
+    const allCurrencies = new Set();
+    for (const r of expenseByCat)
+        allCurrencies.add(r.currency);
+    for (const r of pendingByCurrency)
+        allCurrencies.add(r.currency);
+    for (const r of incomeByCurrency)
+        allCurrencies.add(r.currency);
+    for (const r of rules)
+        allCurrencies.add(r.currency);
+    // If a currency filter was applied, always show that section even if empty
+    if (filterCode)
+        allCurrencies.add(filterCode);
+    // ── Format output ──────────────────────────────────────────────────────────
+    const periodLabel = PERIOD_LABELS[period];
+    const lines = [
+        `Period: ${periodLabel} (${range.start} – ${range.end})`,
+        "",
+    ];
+    if (allCurrencies.size === 0) {
+        lines.push("No transactions recorded in this period.");
+        lines.push("");
+        lines.push("Active recurring commitments: 0");
+        return lines.join("\n");
+    }
+    // Fetch currency rows for amount formatting
+    const currencyCache = new Map();
+    for (const code of allCurrencies) {
+        const row = db
+            .prepare(`SELECT code, name, symbol, is_default FROM currencies WHERE code = ?`)
+            .get(code);
+        if (row)
+            currencyCache.set(code, row);
+    }
+    // One section per currency, sorted alphabetically
+    for (const code of [...allCurrencies].sort()) {
+        const currencyRow = currencyCache.get(code);
+        if (!currencyRow)
+            continue;
+        const fmt = (amount) => formatAmount(amount, currencyRow);
+        const catRows = expenseByCat.filter((r) => r.currency === code);
+        const totalExpenses = catRows.reduce((sum, r) => sum + r.total, 0);
+        const totalPending = pendingByCurrency.find((r) => r.currency === code)?.total ?? 0;
+        const totalIncome = incomeByCurrency.find((r) => r.currency === code)?.total ?? 0;
+        const balance = totalIncome - totalExpenses;
+        lines.push(code);
+        lines.push(`Income received:     ${fmt(totalIncome)}`);
+        lines.push(`Total expenses:      ${fmt(totalExpenses)}`);
+        lines.push(`Pending expenses:    ${fmt(totalPending)}`);
+        lines.push(`Received balance:    ${fmt(balance)}`);
+        if (catRows.length > 0) {
+            lines.push("");
+            lines.push("By category:");
+            for (const cat of [...catRows].sort((a, b) => b.total - a.total)) {
+                lines.push(`  ${cat.category ?? "UNCATEGORIZED"}  ${fmt(cat.total)}`);
+            }
+        }
+        const currencyRules = rules.filter((r) => r.currency === code);
+        if (currencyRules.length > 0) {
+            const totalMonthly = currencyRules.reduce((sum, r) => sum + monthlyEquivalent(r.amount, r.frequency, r.interval_days), 0);
+            lines.push("");
+            lines.push(`Active recurring commitments: ${currencyRules.length} (${fmt(totalMonthly)}/mo)`);
+            for (const rule of currencyRules) {
+                lines.push(`  ${rule.name}  ${fmt(rule.amount)} (${rule.frequency})`);
+            }
+        }
+        lines.push("");
+    }
+    // If no active rules exist at all, append global zero count
+    if (rules.length === 0) {
+        lines.push("Active recurring commitments: 0");
+    }
+    return lines.join("\n").trimEnd();
+}

package/dist/src/tools/helpers/currency-utils.d.ts

@@ -0,0 +1,17 @@
+export declare const PLACEHOLDER_CURRENCY = "XXX";
+interface StatementLike {
+    get(...params: unknown[]): unknown;
+}
+interface DbLike {
+    prepare(sql: string): StatementLike;
+}
+export interface CurrencyRow {
+    code: string;
+    name: string;
+    symbol: string;
+    is_default?: number;
+}
+export declare function resolveCurrency(inputCode?: string, db?: DbLike): CurrencyRow;
+export declare function isPlaceholderCurrency(db?: DbLike): boolean;
+export declare function formatAmount(amount: number, currency: CurrencyRow, _db?: DbLike): string;
+export {};

package/dist/src/tools/helpers/currency-utils.js

@@ -0,0 +1,47 @@
+import { getDb } from "../../db/database.js";
+export const PLACEHOLDER_CURRENCY = "XXX";
+function getDefaultCurrency(db) {
+    const currency = db
+        .prepare(`
+        SELECT code, name, symbol, is_default
+        FROM currencies
+        WHERE is_default = 1
+        ORDER BY created_at ASC
+        LIMIT 1
+      `)
+        .get();
+    if (currency === undefined) {
+        throw new Error("No default currency configured.");
+    }
+    return currency;
+}
+export function resolveCurrency(inputCode, db = getDb()) {
+    const normalizedCode = inputCode?.trim().toUpperCase();
+    if (normalizedCode === undefined || normalizedCode === "") {
+        return getDefaultCurrency(db);
+    }
+    const currency = db
+        .prepare(`
+        SELECT code, name, symbol, is_default
+        FROM currencies
+        WHERE code = ?
+        LIMIT 1
+      `)
+        .get(normalizedCode);
+    if (currency === undefined) {
+        throw new Error(`Currency ${normalizedCode} is not registered. Use manage_currency to add it first.`);
+    }
+    return currency;
+}
+export function isPlaceholderCurrency(db = getDb()) {
+    return resolveCurrency(undefined, db).code === PLACEHOLDER_CURRENCY;
+}
+export function formatAmount(amount, currency, _db) {
+    const sign = amount < 0 ? "-" : "";
+    const absoluteAmount = Math.abs(amount);
+    const formattedNumber = absoluteAmount.toLocaleString("es-CO", {
+        minimumFractionDigits: 0,
+        maximumFractionDigits: Number.isInteger(absoluteAmount) ? 0 : 2,
+    });
+    return `${sign}${currency.symbol}${formattedNumber} ${currency.code}`;
+}

package/dist/src/tools/helpers/date-utils.d.ts

@@ -0,0 +1,8 @@
+export type SupportedPeriod = "this_month" | "last_month" | "last_30_days" | "this_year" | "all";
+export interface DateRange {
+    start: string;
+    end: string;
+}
+export declare function todayISO(): string;
+export declare function computeNextDate(date: string, frequency: string, intervalDays?: number): string;
+export declare function resolvePeriodRange(period: SupportedPeriod, referenceDate?: string): DateRange | null;

package/dist/src/tools/helpers/date-utils.js

@@ -0,0 +1,102 @@
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+function formatDateUtc(date) {
+    return [
+        date.getUTCFullYear(),
+        pad(date.getUTCMonth() + 1),
+        pad(date.getUTCDate()),
+    ].join("-");
+}
+function createUtcDate(year, month, day) {
+    return new Date(Date.UTC(year, month, day));
+}
+function parseIsoDate(date) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (match === null) {
+        throw new Error(`The date "${date}" does not match the YYYY-MM-DD format.`);
+    }
+    const [, yearPart, monthPart, dayPart] = match;
+    const year = Number.parseInt(yearPart, 10);
+    const month = Number.parseInt(monthPart, 10);
+    const day = Number.parseInt(dayPart, 10);
+    const parsed = createUtcDate(year, month - 1, day);
+    if (parsed.getUTCFullYear() !== year ||
+        parsed.getUTCMonth() !== month - 1 ||
+        parsed.getUTCDate() !== day) {
+        throw new Error(`The date "${date}" is not valid.`);
+    }
+    return parsed;
+}
+function addDays(date, days) {
+    const next = new Date(date.getTime());
+    next.setUTCDate(next.getUTCDate() + days);
+    return next;
+}
+function addMonthsClamped(date, months) {
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth();
+    const day = date.getUTCDate();
+    const targetMonthIndex = month + months;
+    const targetYear = year + Math.floor(targetMonthIndex / 12);
+    const normalizedMonth = ((targetMonthIndex % 12) + 12) % 12;
+    const lastDayOfTargetMonth = createUtcDate(targetYear, normalizedMonth + 1, 0).getUTCDate();
+    return createUtcDate(targetYear, normalizedMonth, Math.min(day, lastDayOfTargetMonth));
+}
+export function todayISO() {
+    const now = new Date();
+    return [
+        now.getFullYear(),
+        pad(now.getMonth() + 1),
+        pad(now.getDate()),
+    ].join("-");
+}
+export function computeNextDate(date, frequency, intervalDays = 0) {
+    const baseDate = parseIsoDate(date);
+    switch (frequency) {
+        case "WEEKLY":
+            return formatDateUtc(addDays(baseDate, 7));
+        case "BIWEEKLY":
+            return formatDateUtc(addDays(baseDate, 14));
+        case "MONTHLY":
+            return formatDateUtc(addMonthsClamped(baseDate, 1));
+        case "INTERVAL_DAYS":
+            return formatDateUtc(addDays(baseDate, intervalDays));
+        default:
+            throw new Error(`The frequency "${frequency}" is not valid.`);
+    }
+}
+export function resolvePeriodRange(period, referenceDate = todayISO()) {
+    if (period === "all") {
+        return null;
+    }
+    const reference = parseIsoDate(referenceDate);
+    switch (period) {
+        case "this_month":
+            return {
+                start: formatDateUtc(createUtcDate(reference.getUTCFullYear(), reference.getUTCMonth(), 1)),
+                end: formatDateUtc(reference),
+            };
+        case "last_month": {
+            const lastMonthDate = addMonthsClamped(reference, -1);
+            const year = lastMonthDate.getUTCFullYear();
+            const month = lastMonthDate.getUTCMonth();
+            return {
+                start: formatDateUtc(createUtcDate(year, month, 1)),
+                end: formatDateUtc(createUtcDate(year, month + 1, 0)),
+            };
+        }
+        case "last_30_days":
+            return {
+                start: formatDateUtc(addDays(reference, -29)),
+                end: formatDateUtc(reference),
+            };
+        case "this_year":
+            return {
+                start: formatDateUtc(createUtcDate(reference.getUTCFullYear(), 0, 1)),
+                end: formatDateUtc(reference),
+            };
+        default:
+            throw new Error(`The period "${period}" is not valid.`);
+    }
+}

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

@@ -0,0 +1,16 @@
+import { DatabaseSync } from "node:sqlite";
+import { type Static } from "@sinclair/typebox";
+export declare const InputSchema: import("@sinclair/typebox").TObject<{
+    period: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"this_month">, import("@sinclair/typebox").TLiteral<"last_month">, import("@sinclair/typebox").TLiteral<"last_30_days">, import("@sinclair/typebox").TLiteral<"this_year">, import("@sinclair/typebox").TLiteral<"all">]>>;
+    start_date: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    end_date: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    category: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"PENDING">, import("@sinclair/typebox").TLiteral<"PAID">, import("@sinclair/typebox").TLiteral<"OVERDUE">]>>;
+    search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    currency: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    source: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"MANUAL">, import("@sinclair/typebox").TLiteral<"OCR">]>>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export type Input = Static<typeof InputSchema>;
+export declare function executeListExpenses(input: Input, db?: DatabaseSync): string;