@coffer-org/plugin-finance 1.2.0

package/dist/account/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@coffer-org/sdk/module").ModuleDef;
+export default _default;

package/dist/account/index.js

@@ -0,0 +1,40 @@
+import { defineModule } from '@coffer-org/sdk/module';
+import { field } from '@coffer-org/sdk/fields';
+import { iban } from "../fields/iban.js";
+export default defineModule({
+    module: 'account',
+    vault: 'finance',
+    label: 'finance.account.label',
+    icon: 'lucide:landmark',
+    claude: `Firefly III account (read-only mirror). kind — account type.
+current_balance — current balance. firefly_id — external key (do not edit).`,
+    views: {
+        table: ['kind', 'currency', 'current_balance'],
+    },
+    fields: [
+        field.title({ key: 'name', label: 'core.fields.name' }),
+        field.sheet({
+            fields: [
+                [
+                    field.select({
+                        key: 'kind',
+                        label: 'finance.account.fields.kind',
+                        options: [
+                            { value: 'asset', title: 'finance.account.options.asset' },
+                            { value: 'expense', title: 'finance.account.options.expense' },
+                            { value: 'revenue', title: 'finance.account.options.revenue' },
+                            { value: 'liability', title: 'finance.account.options.liability' },
+                            { value: 'cash', title: 'finance.account.options.cash' },
+                        ],
+                    }),
+                    field.string({ key: 'currency', label: 'finance.account.fields.currency', rules: { max: 3 } }),
+                ],
+                [
+                    field.money({ key: 'current_balance', label: 'finance.account.fields.current_balance' }),
+                    iban({ key: 'iban', label: 'finance.account.fields.iban' }),
+                ],
+            ],
+        }),
+        field.string({ key: 'firefly_id', label: 'finance.account.fields.firefly_id', rules: { max: 32 } }),
+    ],
+});

package/dist/bill/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@coffer-org/sdk/module").ModuleDef;
+export default _default;

package/dist/bill/index.js

@@ -0,0 +1,39 @@
+import { defineModule } from '@coffer-org/sdk/module';
+import { field } from '@coffer-org/sdk/fields';
+export default defineModule({
+    module: 'bill',
+    vault: 'finance',
+    label: 'finance.bill.label',
+    icon: 'lucide:receipt',
+    claude: `Recurring Firefly III payment (Bill = subscription, read-only).
+repeat — recurrence. next_expected — next expected date. firefly_id — do not edit.`,
+    views: {
+        table: ['amount_min', 'repeat', 'next_expected', 'active'],
+    },
+    fields: [
+        field.title({ key: 'name', label: 'core.fields.name' }),
+        field.sheet({
+            fields: [
+                [
+                    field.money({ key: 'amount_min', label: 'finance.bill.fields.amount_min' }),
+                    field.money({ key: 'amount_max', label: 'finance.bill.fields.amount_max' }),
+                ],
+                [
+                    field.select({
+                        key: 'repeat',
+                        label: 'finance.bill.fields.repeat',
+                        options: [
+                            { value: 'weekly', title: 'finance.bill.options.weekly' },
+                            { value: 'monthly', title: 'finance.bill.options.monthly' },
+                            { value: 'quarterly', title: 'finance.bill.options.quarterly' },
+                            { value: 'yearly', title: 'finance.bill.options.yearly' },
+                        ],
+                    }),
+                    field.date({ key: 'next_expected', label: 'finance.bill.fields.next_expected' }),
+                ],
+            ],
+        }),
+        field.boolean({ key: 'active', label: 'finance.bill.fields.active' }),
+        field.string({ key: 'firefly_id', label: 'finance.bill.fields.firefly_id', rules: { max: 32 } }),
+    ],
+});

package/dist/fields/iban.d.ts

@@ -0,0 +1,19 @@
+import { type FieldMeta, type FieldItem, type StaticEl } from '@coffer-org/sdk/fields';
+export interface IbanOpts {
+    key?: string;
+    value?: unknown;
+    label?: string;
+    required?: boolean;
+    multiple?: boolean;
+}
+export declare function iban(o: IbanOpts & {
+    key: string;
+}): FieldItem;
+export declare function iban(o: IbanOpts & {
+    value: unknown;
+    key?: undefined;
+}): StaticEl;
+export declare function iban(o: IbanOpts & {
+    key?: undefined;
+    value?: undefined;
+}): FieldMeta;

package/dist/fields/iban.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { vmsg, optionalize, applyMultiple, wrapKey } from '@coffer-org/sdk/fields';
+const IBAN_RE = /^[A-Za-z]{2}\d{2}[A-Za-z0-9]{11,30}$/;
+function ibanMod97(v) {
+    const s = v.toUpperCase().replace(/\s+/g, '');
+    const rearranged = s.slice(4) + s.slice(0, 4);
+    let digits = '';
+    for (const ch of rearranged) {
+        const code = ch.charCodeAt(0);
+        if (code >= 65 && code <= 90)
+            digits += (code - 55).toString();
+        else
+            digits += ch;
+    }
+    let rem = 0;
+    for (const d of digits)
+        rem = (rem * 10 + (d.charCodeAt(0) - 48)) % 97;
+    return rem === 1;
+}
+export function iban(o) {
+    const required = o.required ?? false;
+    const s = z
+        .string()
+        .regex(IBAN_RE, { message: vmsg('pattern', { messageKey: 'core.presets.iban' }) })
+        .refine(ibanMod97, { message: vmsg('pattern', { messageKey: 'core.presets.iban' }) });
+    const base = {
+        kind: 'text',
+        label: o.label ?? '',
+        required,
+        prim: 'text',
+        column: 'text',
+        hints: {},
+        zod: optionalize(s, required),
+    };
+    return wrapKey(o, applyMultiple(base, o.multiple ?? false));
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { iban } from './fields/iban.ts';
+export { iban } from './fields/iban.ts';
+export declare const fin: {
+    iban: typeof iban;
+};
+declare const _default: import("@coffer-org/sdk/plugin").PluginManifest;
+export default _default;

package/dist/index.js

@@ -0,0 +1,35 @@
+import { defineVault } from '@coffer-org/sdk/vault';
+import { definePlugin } from '@coffer-org/sdk/plugin';
+import { field } from '@coffer-org/sdk/fields';
+import { defineSettings } from '@coffer-org/sdk/settings';
+import account from "./account/index.js";
+import transaction from "./transaction/index.js";
+import bill from "./bill/index.js";
+import itemFinancing from "./item_financing/index.js";
+import { iban } from "./fields/iban.js";
+export { iban } from "./fields/iban.js";
+export const fin = { iban };
+export default definePlugin({
+    id: 'finance',
+    version: '1.0.0',
+    dependsOn: ['things', 'people'],
+    vaults: [
+        {
+            meta: defineVault({ id: 'finance', label: 'finance.vault.label', icon: 'lucide:wallet' }),
+            modules: [account, transaction, bill],
+        },
+    ],
+    extends_: [itemFinancing],
+    settings: defineSettings({
+        label: 'finance.settings.label',
+        fields: [
+            field.string({ key: 'firefly_url', label: 'finance.settings.firefly_url', required: true }),
+            field.password({ key: 'token', label: 'finance.settings.token', required: true }),
+            field.button({ label: 'finance.settings.test_button', value: 'finance.testConnection', icon: 'lucide:wifi' }),
+            field.button({ label: 'finance.settings.sync_button', value: 'finance.sync', icon: 'lucide:refresh-cw' }),
+            field.file({ key: 'wise_csv', label: 'finance.settings.wise_csv' }),
+            field.relation({ key: 'wise_account', label: 'finance.settings.wise_account', options: { vault: 'finance', module: 'account' } }),
+            field.button({ label: 'finance.settings.wise_import_button', value: 'finance.importWise', icon: 'lucide:upload' }),
+        ],
+    }),
+});

package/dist/item_financing/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@coffer-org/sdk/extend").ExtendDef;
+export default _default;

package/dist/item_financing/index.js

@@ -0,0 +1,37 @@
+import { defineExtend } from '@coffer-org/sdk/extend';
+import { field } from '@coffer-org/sdk/fields';
+export default defineExtend({
+    id: 'item_financing',
+    label: 'finance.item_financing.label',
+    icon: 'lucide:credit-card',
+    attachTo: [{ vault: 'things', module: 'item' }],
+    showWhen: { paymentStatus: { $in: ['installment', 'credit'] } },
+    claude: `Installment/credit details for an item. creditor — who is owed (bank/store).
+holder — which person the debt is registered to (relation people/person).
+total — full debt amount. monthly — monthly payment. termMonths/paidMonths — schedule.
+remaining — how much is left (manual). nextPayment — payment reminder. paidOff — settled.`,
+    fields: [
+        field.string({ key: 'creditor', label: 'finance.item_financing.fields.creditor', rules: { max: 120 } }),
+        field.relation({ key: 'holder', label: 'finance.item_financing.fields.holder', options: { vault: 'people', module: 'person' } }),
+        field.sheet({
+            fields: [
+                [
+                    field.money({ key: 'total', label: 'finance.item_financing.fields.total', rules: { defaultCurrency: 'UAH' } }),
+                    field.money({ key: 'downPayment', label: 'finance.item_financing.fields.downPayment', rules: { defaultCurrency: 'UAH' } }),
+                ],
+                [
+                    field.money({ key: 'monthly', label: 'finance.item_financing.fields.monthly', rules: { defaultCurrency: 'UAH' } }),
+                    field.money({ key: 'remaining', label: 'finance.item_financing.fields.remaining', rules: { defaultCurrency: 'UAH' } }),
+                ],
+                [
+                    field.int({ key: 'termMonths', label: 'finance.item_financing.fields.termMonths', rules: { min: 0 } }),
+                    field.int({ key: 'paidMonths', label: 'finance.item_financing.fields.paidMonths', rules: { min: 0 } }),
+                    field.real({ key: 'rate', label: 'finance.item_financing.fields.rate', rules: { min: 0 } }),
+                ],
+            ],
+        }),
+        field.date({ key: 'startDate', label: 'finance.item_financing.fields.startDate' }),
+        field.reminder({ key: 'nextPayment', label: 'finance.item_financing.fields.nextPayment', rules: { lead: 3 } }),
+        field.boolean({ key: 'paidOff', label: 'finance.item_financing.fields.paidOff' }),
+    ],
+});

package/dist/runtime/connection.d.ts

@@ -0,0 +1,5 @@
+export interface ConnectionResult {
+    ok: boolean;
+    error?: string;
+}
+export declare function checkFireflyConnection(url: string, token: string, fetchFn?: typeof fetch): Promise<ConnectionResult>;

package/dist/runtime/connection.js

@@ -0,0 +1,14 @@
+export async function checkFireflyConnection(url, token, fetchFn = fetch) {
+    const endpoint = `${url.replace(/\/$/, '')}/api/v1/about`;
+    try {
+        const resp = await fetchFn(endpoint, {
+            headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+        });
+        if (resp.ok)
+            return { ok: true };
+        return { ok: false, error: `Firefly returned ${resp.status}` };
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+}

package/dist/runtime/firefly.d.ts

@@ -0,0 +1,50 @@
+export interface FireflyCreds {
+    url: string;
+    token: string;
+}
+export interface FireflyItem<A> {
+    id: string;
+    attributes: A;
+}
+export interface AccountAttr {
+    name: string;
+    type: string;
+    account_role?: string | null;
+    currency_code?: string | null;
+    current_balance?: string | null;
+    iban?: string | null;
+}
+export interface TxnSplit {
+    transaction_journal_id?: string;
+    date: string;
+    amount: string;
+    type: string;
+    description: string;
+    source_id?: string | null;
+    destination_id?: string | null;
+    category_name?: string | null;
+    currency_code?: string | null;
+}
+export interface TxnAttr {
+    transactions: TxnSplit[];
+}
+export interface BillAttr {
+    name: string;
+    amount_min?: string | null;
+    amount_max?: string | null;
+    repeat_freq?: string | null;
+    next_expected_match?: string | null;
+    active?: boolean | null;
+    currency_code?: string | null;
+}
+export declare function fetchAccounts(creds: FireflyCreds, fetchFn?: typeof fetch): Promise<FireflyItem<AccountAttr>[]>;
+export declare function fetchTransactions(creds: FireflyCreds, start: string, end: string, fetchFn?: typeof fetch): Promise<FireflyItem<TxnAttr>[]>;
+export declare function fetchBills(creds: FireflyCreds, fetchFn?: typeof fetch): Promise<FireflyItem<BillAttr>[]>;
+export declare function createTransaction(creds: FireflyCreds, split: TxnSplit, fetchFn?: typeof fetch): Promise<{
+    ok: true;
+} | {
+    skip: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/runtime/firefly.js

@@ -0,0 +1,64 @@
+async function fetchAllPages(creds, path, fetchFn) {
+    const base = `${creds.url.replace(/\/$/, '')}${path}`;
+    const out = [];
+    let page = 1;
+    let totalPages = 1;
+    do {
+        const sep = base.includes('?') ? '&' : '?';
+        const resp = await fetchFn(`${base}${sep}page=${page}&limit=100`, {
+            headers: { Authorization: `Bearer ${creds.token}`, Accept: 'application/json' },
+        });
+        if (!resp.ok)
+            throw new Error(`Firefly ${path} returned ${resp.status}`);
+        const body = (await resp.json());
+        out.push(...body.data);
+        totalPages = body.meta?.pagination?.total_pages ?? 1;
+        page += 1;
+    } while (page <= totalPages);
+    return out;
+}
+export function fetchAccounts(creds, fetchFn = fetch) {
+    return fetchAllPages(creds, '/api/v1/accounts', fetchFn);
+}
+export function fetchTransactions(creds, start, end, fetchFn = fetch) {
+    return fetchAllPages(creds, `/api/v1/transactions?start=${start}&end=${end}`, fetchFn);
+}
+export function fetchBills(creds, fetchFn = fetch) {
+    return fetchAllPages(creds, '/api/v1/bills', fetchFn);
+}
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 2000;
+export async function createTransaction(creds, split, fetchFn = fetch) {
+    const url = `${creds.url.replace(/\/$/, '')}/api/v1/transactions`;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            const res = await fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${creds.token}`,
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ transactions: [split] }),
+            });
+            if (res.status === 200 || res.status === 201)
+                return { ok: true };
+            if (res.status === 422)
+                return { skip: true };
+            if (attempt < MAX_RETRIES - 1) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * 2 ** attempt));
+                continue;
+            }
+            const txt = await res.text().catch(() => '');
+            return { ok: false, error: `Firefly ${res.status}: ${txt.slice(0, 100)}` };
+        }
+        catch (e) {
+            if (attempt < MAX_RETRIES - 1) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * 2 ** attempt));
+                continue;
+            }
+            return { ok: false, error: e.message.slice(0, 100) };
+        }
+    }
+    return { ok: false, error: 'Max retries reached' };
+}

package/dist/runtime/import-wise.d.ts

@@ -0,0 +1,5 @@
+export declare function importWise(fetchFn?: typeof fetch): Promise<{
+    imported: number;
+    skipped: number;
+    errors: string[];
+}>;

package/dist/runtime/import-wise.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginSettings } from '@coffer-org/server/plugin-runtime';
+import { moduleTableName } from '@coffer-org/server/entity-schema';
+import { listRecords } from '@coffer-org/server/mutate';
+import { uploadsDir } from '@coffer-org/server/uploads';
+import { createTransaction } from "./firefly.js";
+import { parseWiseCsv, buildSplits } from "./wise.js";
+import { runSync } from "./sync.js";
+const VAULT = 'finance';
+export async function importWise(fetchFn = fetch) {
+    const settings = await getPluginSettings(VAULT);
+    const url = settings['firefly_url'];
+    const token = settings['token'];
+    if (!url || !token)
+        throw new Error('Finance settings not configured. Save Firefly URL and token first.');
+    const csv = settings['wise_csv'];
+    if (!csv?.name)
+        throw new Error('No Wise CSV uploaded. Pick a file in finance settings first.');
+    const accId = settings['wise_account'];
+    if (accId == null)
+        throw new Error('No target account selected.');
+    const accounts = (await listRecords(moduleTableName(VAULT, 'account')));
+    const acc = accounts.find((r) => String(r['id']) === String(accId));
+    const fireflyAccountId = acc?.['firefly_id'];
+    if (typeof fireflyAccountId !== 'string' || !fireflyAccountId) {
+        throw new Error('Selected account has no firefly_id — run a sync first.');
+    }
+    const content = readFileSync(join(uploadsDir(), csv.name), 'utf-8');
+    const { splits, skipped: convSkipped } = buildSplits(parseWiseCsv(content), fireflyAccountId);
+    const creds = { url, token };
+    let imported = 0;
+    let skipped = convSkipped;
+    const errors = [];
+    for (const split of splits) {
+        const r = await createTransaction(creds, split, fetchFn);
+        if ('ok' in r && r.ok)
+            imported++;
+        else if ('skip' in r)
+            skipped++;
+        else
+            errors.push(r.error);
+    }
+    await runSync(fetchFn);
+    return { imported, skipped, errors };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+import type { PluginHooks } from '@coffer-org/server/plugin-hooks';
+export { checkFireflyConnection } from './connection.ts';
+export { runSync } from './sync.ts';
+export { importWise } from './import-wise.ts';
+export declare function startSync(): Promise<void>;
+export declare function stopSync(): void;
+export declare const serverHooks: PluginHooks;

package/dist/runtime/index.js

@@ -0,0 +1,35 @@
+import { runSync } from "./sync.js";
+export { checkFireflyConnection } from "./connection.js";
+export { runSync } from "./sync.js";
+export { importWise } from "./import-wise.js";
+export async function startSync() {
+    const r = await runSync();
+    console.log(`[finance] sync: ${r.accounts} accounts, ${r.transactions} transactions, ${r.bills} bills`);
+}
+export function stopSync() { }
+export const serverHooks = {
+    init: () => {
+        void startSync().catch((e) => console.warn(`[finance] sync failed to start: ${e.message}`));
+    },
+    teardown: () => {
+        stopSync();
+    },
+    agent: {
+        instructions: 'Vault finance — accounts (account), bills to pay (bill), transactions (transaction). ' +
+            'account.current_balance — current balance in account.currency. transaction: amount + kind ' +
+            '(withdrawal/deposit/transfer), date (ISO), category. bill.next_expected — next payment date. ' +
+            'Data is mirrored from Firefly (firefly_id).' +
+            ' Do NOT edit current_balance manually — it is mirrored from Firefly; new operations live as transaction.',
+        tools: [
+            {
+                name: 'account_balances',
+                description: 'Current balances of all finance accounts.',
+                inputSchema: {},
+                handler: async (_args, { em }) => {
+                    const rows = (await em.fork().find('finance__account', {}));
+                    return rows.map((r) => ({ id: r.id, name: r.name, kind: r.kind, currency: r.currency, current_balance: r.current_balance }));
+                },
+            },
+        ],
+    },
+};

package/dist/runtime/mapping.d.ts

@@ -0,0 +1,8 @@
+import type { AccountAttr, BillAttr, FireflyItem, TxnAttr } from './firefly.ts';
+export interface CofferRecord {
+    firefly_id: string;
+    [k: string]: unknown;
+}
+export declare function mapAccount(item: FireflyItem<AccountAttr>): CofferRecord;
+export declare function mapBill(item: FireflyItem<BillAttr>): CofferRecord;
+export declare function mapTransactionSplits(item: FireflyItem<TxnAttr>, accIdByFireflyId: Map<string, number>): CofferRecord[];

package/dist/runtime/mapping.js

@@ -0,0 +1,68 @@
+function money(amount, currency) {
+    if (amount == null || amount === '')
+        return null;
+    const value = Number(amount);
+    if (Number.isNaN(value))
+        return null;
+    return { value, currency: currency ?? 'EUR' };
+}
+function accountKind(type, role) {
+    const t = (type || '').toLowerCase();
+    if (t === 'asset')
+        return role === 'cashWalletAsset' ? 'cash' : 'asset';
+    if (t === 'expense')
+        return 'expense';
+    if (t === 'revenue')
+        return 'revenue';
+    if (t === 'cash')
+        return 'cash';
+    if (['liability', 'loan', 'debt', 'mortgage'].includes(t))
+        return 'liability';
+    return 'asset';
+}
+function billRepeat(freq) {
+    const f = (freq || '').toLowerCase();
+    if (['weekly', 'monthly', 'quarterly', 'yearly'].includes(f))
+        return f;
+    return 'monthly';
+}
+const TXN_KINDS = new Set(['withdrawal', 'deposit', 'transfer']);
+function txnKind(type) {
+    const t = (type || '').toLowerCase();
+    return TXN_KINDS.has(t) ? t : 'withdrawal';
+}
+export function mapAccount(item) {
+    const a = item.attributes;
+    return {
+        firefly_id: item.id,
+        name: a.name,
+        kind: accountKind(a.type, a.account_role),
+        currency: a.currency_code ?? '',
+        current_balance: money(a.current_balance, a.currency_code),
+        iban: a.iban ?? '',
+    };
+}
+export function mapBill(item) {
+    const a = item.attributes;
+    return {
+        firefly_id: item.id,
+        name: a.name,
+        amount_min: money(a.amount_min, a.currency_code),
+        amount_max: money(a.amount_max, a.currency_code),
+        repeat: billRepeat(a.repeat_freq),
+        next_expected: a.next_expected_match ?? null,
+        active: a.active ?? false,
+    };
+}
+export function mapTransactionSplits(item, accIdByFireflyId) {
+    return item.attributes.transactions.map((s, i) => ({
+        firefly_id: s.transaction_journal_id ?? `${item.id}-${i}`,
+        description: s.description,
+        date: s.date.slice(0, 10),
+        amount: money(s.amount, s.currency_code),
+        kind: txnKind(s.type),
+        source: s.source_id != null ? (accIdByFireflyId.get(s.source_id) ?? null) : null,
+        destination: s.destination_id != null ? (accIdByFireflyId.get(s.destination_id) ?? null) : null,
+        category: s.category_name ?? '',
+    }));
+}

package/dist/runtime/sync.d.ts

@@ -0,0 +1,5 @@
+export declare function runSync(fetchFn?: typeof fetch): Promise<{
+    accounts: number;
+    transactions: number;
+    bills: number;
+}>;

package/dist/runtime/sync.js

@@ -0,0 +1,57 @@
+import { getPluginSettings } from '@coffer-org/server/plugin-runtime';
+import { getModule } from '@coffer-org/server/registry-context';
+import { moduleTableName } from '@coffer-org/server/entity-schema';
+import { listRecords } from '@coffer-org/server/mutate';
+import { localPost, localPatch } from '@coffer-org/server/local-api';
+import { fetchAccounts, fetchBills, fetchTransactions } from "./firefly.js";
+import { mapAccount, mapBill, mapTransactionSplits } from "./mapping.js";
+const VAULT = 'finance';
+async function existingMap(type) {
+    const ename = moduleTableName(VAULT, type);
+    const rows = (await listRecords(ename));
+    const m = new Map();
+    for (const r of rows) {
+        const fid = r['firefly_id'];
+        if (typeof fid === 'string')
+            m.set(fid, r['id']);
+    }
+    return m;
+}
+async function upsertAll(type, recs) {
+    const map = await existingMap(type);
+    for (const rec of recs) {
+        const existingId = map.get(rec.firefly_id);
+        if (existingId != null) {
+            await localPatch(VAULT, type, existingId, rec);
+        }
+        else {
+            const row = await localPost(VAULT, type, rec);
+            map.set(rec.firefly_id, row['id']);
+        }
+    }
+    return map;
+}
+function lastYearWindow(today) {
+    const [y, m, d] = today.split('-');
+    return { start: `${Number(y) - 1}-${m}-${d}`, end: today };
+}
+export async function runSync(fetchFn = fetch) {
+    const settings = await getPluginSettings('finance');
+    const url = settings['firefly_url'];
+    const token = settings['token'];
+    if (!url || !token)
+        throw new Error('Finance settings not configured. Save Firefly URL and token first.');
+    if (!getModule(VAULT, 'account'))
+        throw new Error('finance vault not registered');
+    const creds = { url, token };
+    const accounts = await fetchAccounts(creds, fetchFn);
+    const accMap = await upsertAll('account', accounts.map(mapAccount));
+    const today = new Date().toISOString().slice(0, 10);
+    const { start, end } = lastYearWindow(today);
+    const txns = await fetchTransactions(creds, start, end, fetchFn);
+    const txnRecs = txns.flatMap((t) => mapTransactionSplits(t, accMap));
+    await upsertAll('transaction', txnRecs);
+    const bills = await fetchBills(creds, fetchFn);
+    await upsertAll('bill', bills.map(mapBill));
+    return { accounts: accounts.length, transactions: txnRecs.length, bills: bills.length };
+}

package/dist/runtime/wise.d.ts

@@ -0,0 +1,8 @@
+import type { TxnSplit } from './firefly.ts';
+export type WiseRow = Record<string, string>;
+export declare function getCategory(merchant: string, description: string): string;
+export declare function parseWiseCsv(content: string): WiseRow[];
+export declare function buildSplits(rows: WiseRow[], fireflyAccountId: string): {
+    splits: TxnSplit[];
+    skipped: number;
+};

package/dist/runtime/wise.js

@@ -0,0 +1,107 @@
+const MERCHANT_CATEGORIES = {
+    Anthropic: 'ПО и подписки',
+    Hetzner: 'ПО и подписки',
+    Booking: 'Путешествия',
+    Kiwi: 'Путешествия',
+    Aliexpress: 'Покупки',
+    Temu: 'Покупки',
+    Banggood: 'Покупки',
+    Metro: 'Продукты',
+    Floreni: 'Продукты',
+    Rompetrol: 'Автомобиль',
+    'La Placinte': 'Продукты',
+    'Maib Farm': 'Продукты',
+    'Www Letz Md': 'Покупки',
+    'Alina Cosmetics': 'Косметика',
+};
+export function getCategory(merchant, description) {
+    const m = merchant.toLowerCase();
+    const d = description.toLowerCase();
+    for (const [key, category] of Object.entries(MERCHANT_CATEGORIES)) {
+        const k = key.toLowerCase();
+        if (m.includes(k) || d.includes(k))
+            return category;
+    }
+    if (description.includes('Card transaction'))
+        return 'Другое';
+    if (description.includes('Converted'))
+        return 'Конвертация';
+    if (description.includes('Sent money') || description.includes('Received'))
+        return 'Переводы';
+    return 'Другое';
+}
+export function parseWiseCsv(content) {
+    const lines = content.split(/\r?\n/).filter(Boolean);
+    if (!lines.length)
+        return [];
+    const header = (lines[0] ?? '').split(',').map((h) => h.trim().replace(/^"|"$/g, ''));
+    const rows = [];
+    for (const line of lines.slice(1)) {
+        if (!line.trim())
+            continue;
+        const cells = [];
+        let current = '';
+        let inQuote = false;
+        for (const ch of line) {
+            if (ch === '"')
+                inQuote = !inQuote;
+            else if (ch === ',' && !inQuote) {
+                cells.push(current.trim());
+                current = '';
+            }
+            else
+                current += ch;
+        }
+        cells.push(current.trim());
+        if (cells.length !== header.length)
+            continue;
+        const row = {};
+        header.forEach((h, i) => {
+            row[h] = cells[i] || '';
+        });
+        if (!row['Date'] || !row['Amount'])
+            continue;
+        rows.push(row);
+    }
+    return rows;
+}
+function convertDate(dateStr) {
+    const m = dateStr.match(/^(\d{2})-(\d{2})-(\d{4})$/);
+    return m ? `${m[3]}-${m[2]}-${m[1]}` : dateStr;
+}
+export function buildSplits(rows, fireflyAccountId) {
+    const main = {};
+    for (const row of rows) {
+        const id = row['TransferWise ID'] || '';
+        if (id.startsWith('FEE-'))
+            continue;
+        main[id || `${row['Date']}|${row['Amount']}`] = row;
+    }
+    const splits = [];
+    let skipped = 0;
+    for (const row of Object.values(main)) {
+        const raw = parseFloat(row['Amount'] || '0');
+        const type = (row['Transaction Type'] || '').toUpperCase();
+        if (type === 'CONVERSION') {
+            skipped++;
+            continue;
+        }
+        const amount = Math.abs(raw);
+        const kind = raw > 0 ? 'deposit' : 'withdrawal';
+        const description = (row['Description'] || '').trim();
+        const merchant = (row['Merchant'] || '').trim();
+        const split = {
+            type: kind,
+            date: convertDate(row['Date'] || ''),
+            amount: String(amount),
+            description,
+            category_name: getCategory(merchant, description),
+        };
+        if (kind === 'withdrawal')
+            split.source_id = fireflyAccountId;
+        else
+            split.destination_id = fireflyAccountId;
+        splits.push(split);
+    }
+    return { splits, skipped };
+}

package/dist/transaction/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@coffer-org/sdk/module").ModuleDef;
+export default _default;

package/dist/transaction/index.js

@@ -0,0 +1,41 @@
+import { defineModule } from '@coffer-org/sdk/module';
+import { field } from '@coffer-org/sdk/fields';
+export default defineModule({
+    module: 'transaction',
+    vault: 'finance',
+    label: 'finance.transaction.label',
+    icon: 'lucide:arrow-left-right',
+    claude: `Firefly III transaction (read-only). Each split = a separate record.
+source/destination — accounts. firefly_id — split journal id (do not edit).`,
+    views: {
+        table: ['date', 'amount', 'kind', 'description'],
+    },
+    fields: [
+        field.title({ key: 'description', label: 'finance.transaction.fields.description' }),
+        field.sheet({
+            fields: [
+                [
+                    field.date({ key: 'date', label: 'finance.transaction.fields.date' }),
+                    field.money({ key: 'amount', label: 'finance.transaction.fields.amount' }),
+                ],
+                [
+                    field.select({
+                        key: 'kind',
+                        label: 'finance.transaction.fields.kind',
+                        options: [
+                            { value: 'withdrawal', title: 'finance.transaction.options.withdrawal' },
+                            { value: 'deposit', title: 'finance.transaction.options.deposit' },
+                            { value: 'transfer', title: 'finance.transaction.options.transfer' },
+                        ],
+                    }),
+                    field.string({ key: 'category', label: 'finance.transaction.fields.category', rules: { max: 100 } }),
+                ],
+                [
+                    field.relation({ key: 'source', label: 'finance.transaction.fields.source', options: { vault: 'finance', module: 'account' } }),
+                    field.relation({ key: 'destination', label: 'finance.transaction.fields.destination', options: { vault: 'finance', module: 'account' } }),
+                ],
+            ],
+        }),
+        field.string({ key: 'firefly_id', label: 'finance.transaction.fields.firefly_id', rules: { max: 32 } }),
+    ],
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@coffer-org/plugin-finance",
+  "version": "1.2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "prepack": "npm run build && node ../../scripts/swap-exports.mjs dist",
+    "postpack": "node ../../scripts/swap-exports.mjs src",
+    "test": "node --import tsx/esm --test 'src/runtime/*.test.ts'"
+  },
+  "dependencies": {
+    "@coffer-org/sdk": "^1.2.0",
+    "@coffer-org/server": "^1.2.0",
+    "zod": "^4.4.3"
+  }
+}