actual-jev 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+# Fill in these values and run actual-jev --env-file .env --dry-run.
+ACTUAL_SERVER_URL=http://localhost:5006
+ACTUAL_PASSWORD=your-actual-password
+ACTUAL_SYNC_ID=your-budget-sync-id
+# Leave empty unless the budget uses end-to-end encryption.
+ACTUAL_ENCRYPTION_PASSWORD=
+TYPESAFE_API_KEY=your-typesafe-api-key

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessandro Cifani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# actual-jev
+
+Categorize uncategorized [Actual Budget](https://actualbudget.org/) transactions with [TypeSafe Jev](https://docs.typesafe.ai/sdk/javascript).
+
+## CLI
+
+Requires Node.js 24 (24.10 or newer), an Actual server, and a TypeSafe API key.
+
+```sh
+actual-jev setup       # Connect to Actual, choose a budget, save credentials
+actual-jev --dry-run   # Preview suggestions without changing transactions
+actual-jev             # Review each suggestion and choose a category or skip
+actual-jev --auto      # Apply suggestions with confidence of at least 0.9
+```
+
+Setup saves your settings locally, so the CLI works from any folder. Rerun `setup` to change them. `actual-jev config show` displays settings and storage paths with secrets hidden.
+
+Use `--threshold` to change automatic confidence, `--account`, `--from`, and `--to` to narrow the scan, or `--max-examples-per-category 0` to omit historical examples. See `actual-jev --help` for all options.
+
+The CLI handles on-budget transactions and uncategorized split items, skips internal transfers, and leaves conflicting payee history for manual review in automatic mode. Predictions send TypeSafe transaction details, category names and notes, and relevant categorized history (up to three examples per category by default).
+
+## Automation
+
+Supply the connection settings in [.env.example](.env.example) as exported environment variables or an explicit environment file:
+
+```sh
+actual-jev --auto                   # Use exported variables
+actual-jev --env-file .env --auto    # Read variables from a file
+```
+
+Either uses environment configuration independently of saved setup. Supply all required connection settings; exported values override matching values in the file. Find your budget's sync ID under **Actual → Settings → Show advanced settings → Sync ID**.
+
+## Library
+
+Pass initialized Actual and TypeSafe clients to `ActualJev`:
+
+```ts
+const classifier = new ActualJev({ actual, jev });
+const result = await classifier.classify({ payee_name: 'Fresh Market', amount: -2350 });
+```
+
+The library returns suggestions without updating Actual. See [library usage](docs/library.md) for complete examples, including supplying categories without an Actual server.

package/dist/actual-jev.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/actual-jev.test.js

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { q } from '@actual-app/api';
+import { ActualJev } from './actual.js';
+function jev(states) {
+    return {
+        systemOne(request) {
+            states.push(request.state);
+            return Promise.resolve({
+                answers: {
+                    category: {
+                        choice: 'category_0',
+                        confidence: 0.9,
+                        probabilities: { category_0: 0.9, none_of_the_above: 0.1 },
+                    },
+                },
+            });
+        },
+    };
+}
+void test('loads Actual data once on concurrent first calls and refreshes the snapshot', async () => {
+    let revision = 1;
+    let queries = 0;
+    const states = [];
+    const actual = {
+        q,
+        aqlQuery(query) {
+            assert.equal(query.state.table, 'transactions');
+            queries++;
+            return Promise.resolve({
+                data: [
+                    {
+                        id: 'old',
+                        account: 'checking',
+                        date: '2026-09-01',
+                        amount: -1000,
+                        payee: 'shop',
+                        category: `category-${revision}`,
+                    },
+                    {
+                        id: 'tracking',
+                        account: 'tracking',
+                        date: '2026-09-01',
+                        amount: -1000,
+                        payee: 'shop',
+                        category: `category-${revision}`,
+                    },
+                ],
+            });
+        },
+        getAccounts: () => Promise.resolve([
+            { id: 'checking', name: 'Checking', offbudget: false },
+            { id: 'tracking', name: 'Tracking', offbudget: true },
+        ]),
+        getCategoryGroups: () => Promise.resolve([
+            {
+                id: 'food',
+                name: 'Food',
+                categories: [{ id: `category-${revision}`, name: 'Groceries', group_id: 'food' }],
+            },
+        ]),
+        getPayees: () => Promise.resolve([{ id: 'shop', name: 'Fresh Market' }]),
+        getNote: () => Promise.resolve(null),
+    };
+    const classifier = new ActualJev({ actual, jev: jev(states) });
+    assert.deepEqual(classifier.categories, []);
+    const input = { id: 'new', account: 'checking', payee: 'shop', amount: -2350 };
+    const results = await Promise.all([classifier.classify(input), classifier.classify(input)]);
+    assert.equal(queries, 1);
+    assert.deepEqual(results.map((result) => result.categoryId), ['category-1', 'category-1']);
+    const state = states[0];
+    assert.equal(state.transaction.account, 'Checking');
+    assert.equal(state.transaction.payee, 'Fresh Market');
+    assert.equal(state.relevant_examples.length, 1);
+    revision = 2;
+    await classifier.refresh();
+    assert.equal(queries, 2);
+    assert.equal((await classifier.classify(input)).categoryId, 'category-2');
+});
+void test('retries a failed Actual load', async () => {
+    let queries = 0;
+    const actual = {
+        q,
+        aqlQuery() {
+            queries++;
+            if (queries === 1)
+                return Promise.reject(new Error('query failed'));
+            return Promise.resolve({ data: [] });
+        },
+        getAccounts: () => Promise.resolve([]),
+        getCategoryGroups: () => Promise.resolve([]),
+        getPayees: () => Promise.resolve([]),
+        getNote: () => Promise.resolve(null),
+    };
+    const classifier = new ActualJev({ actual, jev: jev([]) });
+    await assert.rejects(classifier.classify({}), /query failed/);
+    assert.equal((await classifier.classify({})).categoryId, null);
+    assert.equal(queries, 2);
+});
+void test('uses manual constructor data without an Actual client', async () => {
+    const states = [];
+    const classifier = new ActualJev({
+        jev: jev(states),
+        categories: [{ id: 'groceries', name: 'Groceries', groupName: 'Food' }],
+        examples: [{ categoryId: 'groceries', payeeName: 'Fresh Market' }],
+    });
+    await classifier.refresh();
+    const result = await classifier.classify({ payeeName: 'Fresh Market', amount: -2350 });
+    assert.equal(result.categoryId, 'groceries');
+    assert.equal(states[0].relevant_examples.length, 1);
+});

package/dist/actual.d.ts

@@ -0,0 +1,47 @@
+import type * as ActualApi from '@actual-app/api';
+import { type CategoryCandidate, type CategorizedExample, type Classification, type ClassifierOptions, type JevChoiceClient, type TransactionDetails } from './classifier.js';
+export type ActualTransaction = Awaited<ReturnType<typeof ActualApi.getTransactions>>[number];
+export type ActualClient = Pick<typeof ActualApi, 'getCategoryGroups' | 'getPayees' | 'getNote'>;
+export type ActualDataClient = ActualClient & Pick<typeof ActualApi, 'getAccounts' | 'aqlQuery' | 'q'>;
+export type ActualTransactionInput = Partial<ActualTransaction> & {
+    payee_name?: string;
+    accountName?: string;
+    payeeDefaultCategoryId?: string;
+};
+export interface ActualClassifier {
+    readonly categories: readonly CategoryCandidate[];
+    classify(transaction: ActualTransactionInput): Promise<Classification>;
+    refresh(): Promise<void>;
+}
+export interface ActualClassifierOptions extends ClassifierOptions {
+    history?: readonly ActualTransaction[];
+    eligibleAccountIds?: ReadonlySet<string>;
+}
+interface JevConfig {
+    jev: JevChoiceClient;
+    model?: string;
+    maxExamplesPerCategory?: number;
+}
+export type ActualJevConfig = JevConfig & ({
+    actual: ActualDataClient;
+    categories?: never;
+    examples?: never;
+} | {
+    actual?: never;
+    categories: readonly CategoryCandidate[];
+    examples?: readonly CategorizedExample[];
+});
+/** Reuses a loaded category catalog when classifying several imported transactions. */
+export declare function createActualClassifier(actual: ActualClient, options?: ActualClassifierOptions): Promise<ActualClassifier>;
+/** Classifies with either caller-supplied data or a lazily loaded Actual budget snapshot. */
+export declare class ActualJev {
+    private readonly config;
+    private snapshot;
+    private loading;
+    constructor(config: ActualJevConfig);
+    get categories(): readonly CategoryCandidate[];
+    private load;
+    refresh(): Promise<void>;
+    classify(transaction: ActualTransactionInput | TransactionDetails): Promise<Classification>;
+}
+export {};

package/dist/actual.js

@@ -0,0 +1,148 @@
+import { classifyTransaction, } from './classifier.js';
+function usefulNote(note) {
+    const text = note
+        ?.split('\n')
+        .filter((line) => !/^\s*#(?:template|goal)\b/i.test(line))
+        .join('\n')
+        .trim();
+    return text || undefined;
+}
+/** Reuses a loaded category catalog when classifying several imported transactions. */
+export async function createActualClassifier(actual, options = {}) {
+    let categories = [];
+    let payees = new Map();
+    let examples = [];
+    async function refresh() {
+        const [groups, currentPayees] = await Promise.all([
+            actual.getCategoryGroups({ hidden: false }),
+            actual.getPayees(),
+        ]);
+        const visible = groups.flatMap((group) => (group.categories ?? []).map((category) => ({
+            id: category.id,
+            name: category.name,
+            groupName: group.name,
+            isIncome: category.is_income ?? group.is_income ?? false,
+        })));
+        categories = await Promise.all(visible.map(async (category) => ({
+            ...category,
+            note: usefulNote((await actual.getNote(category.id))?.note),
+        })));
+        payees = new Map(currentPayees.map((payee) => [payee.id, payee.name]));
+        const transferPayees = new Set(currentPayees.filter((payee) => payee.transfer_acct).map((payee) => payee.id));
+        const visibleIds = new Set(categories.map((category) => category.id));
+        examples = [...(options.examples ?? [])];
+        for (const row of options.history ?? []) {
+            if (options.eligibleAccountIds && !options.eligibleAccountIds.has(row.account))
+                continue;
+            for (const transaction of row.subtransactions?.length ? row.subtransactions : [row]) {
+                if (!transaction.category ||
+                    !visibleIds.has(transaction.category) ||
+                    row.transfer_id ||
+                    transaction.transfer_id ||
+                    row.is_child)
+                    continue;
+                const payee = transaction.payee ?? row.payee;
+                if (payee && transferPayees.has(payee))
+                    continue;
+                examples.push({
+                    id: transaction.id,
+                    categoryId: transaction.category,
+                    payeeName: payee ? payees.get(payee) : undefined,
+                    importedPayee: transaction.imported_payee ?? row.imported_payee,
+                    notes: transaction.notes ?? row.notes,
+                    amount: transaction.amount,
+                    date: transaction.date ?? row.date,
+                });
+            }
+        }
+    }
+    await refresh();
+    return {
+        get categories() {
+            return categories;
+        },
+        refresh,
+        classify(transaction) {
+            const details = {
+                id: transaction.id,
+                payeeName: transaction.payee_name ?? (transaction.payee ? payees.get(transaction.payee) : undefined),
+                importedPayee: transaction.imported_payee,
+                notes: transaction.notes,
+                amount: transaction.amount,
+                date: transaction.date,
+                accountName: transaction.accountName,
+                payeeDefaultCategoryId: transaction.payeeDefaultCategoryId,
+            };
+            return classifyTransaction(details, categories, { ...options, examples });
+        },
+    };
+}
+/** Classifies with either caller-supplied data or a lazily loaded Actual budget snapshot. */
+export class ActualJev {
+    config;
+    snapshot;
+    loading;
+    constructor(config) {
+        this.config = config;
+        if (!config.jev)
+            throw new TypeError('A configured Jev client is required');
+    }
+    get categories() {
+        return 'actual' in this.config ? (this.snapshot?.classifier.categories ?? []) : this.config.categories;
+    }
+    async load() {
+        if (!this.config.actual)
+            throw new TypeError('Manual data cannot be refreshed from Actual');
+        const actual = this.config.actual;
+        const [accounts, queryResult] = await Promise.all([
+            actual.getAccounts(),
+            actual.aqlQuery(actual.q('transactions').select('*').options({ splits: 'grouped' })),
+        ]);
+        const history = queryResult.data;
+        if (!Array.isArray(history))
+            throw new Error('ActualQL did not return transaction rows');
+        const classifier = await createActualClassifier(actual, {
+            client: this.config.jev,
+            model: this.config.model,
+            maxExamplesPerCategory: this.config.maxExamplesPerCategory,
+            history,
+            eligibleAccountIds: new Set(accounts.filter((account) => !account.offbudget).map((account) => account.id)),
+        });
+        return { classifier, accountNames: new Map(accounts.map((account) => [account.id, account.name])) };
+    }
+    async refresh() {
+        if (!this.config.actual)
+            return;
+        if (!this.loading) {
+            const loading = this.load();
+            this.loading = loading;
+            void loading.then((snapshot) => {
+                this.snapshot = snapshot;
+                if (this.loading === loading)
+                    this.loading = undefined;
+            }, () => {
+                if (this.loading === loading)
+                    this.loading = undefined;
+            });
+        }
+        await this.loading;
+    }
+    async classify(transaction) {
+        if (!this.config.actual) {
+            return classifyTransaction(transaction, this.config.categories, {
+                client: this.config.jev,
+                model: this.config.model,
+                examples: this.config.examples,
+                maxExamplesPerCategory: this.config.maxExamplesPerCategory,
+            });
+        }
+        if (!this.snapshot)
+            await this.refresh();
+        const snapshot = this.snapshot;
+        const input = transaction;
+        return snapshot.classifier.classify({
+            ...input,
+            accountName: input.accountName ?? (input.account ? snapshot.accountNames.get(input.account) : undefined),
+        });
+    }
+}

package/dist/actual.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/actual.test.js

@@ -0,0 +1,139 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createActualClassifier } from './actual.js';
+void test('loads and refreshes the catalog and payees while preserving transaction mapping', async () => {
+    let revision = 1;
+    let loads = 0;
+    const states = [];
+    const actual = {
+        getCategoryGroups(options) {
+            assert.deepEqual(options, { hidden: false });
+            loads++;
+            return Promise.resolve([
+                {
+                    id: 'group',
+                    name: 'Income',
+                    is_income: true,
+                    categories: [{ id: `category-${revision}`, name: 'Salary', group_id: 'group' }],
+                },
+            ]);
+        },
+        getPayees() {
+            return Promise.resolve([{ id: 'employer', name: `Employer ${revision}` }]);
+        },
+        getNote() {
+            return Promise.resolve(null);
+        },
+    };
+    const client = {
+        systemOne(request) {
+            assert.equal(request.model, 'custom-model');
+            assert.equal(request.questions.category.criteria.category_0, 'Income / Salary (income)');
+            states.push(request.state);
+            return Promise.resolve({
+                answers: {
+                    category: {
+                        choice: 'category_0',
+                        confidence: 0.9,
+                        probabilities: { category_0: 0.9, none_of_the_above: 0.1 },
+                    },
+                },
+            });
+        },
+    };
+    const classifier = await createActualClassifier(actual, { client, model: 'custom-model' });
+    const transaction = {
+        payee: 'employer',
+        imported_payee: 'Deposit',
+        notes: 'Monthly',
+        amount: 10000,
+        date: '2026-09-01',
+        accountName: 'Checking',
+    };
+    assert.equal((await classifier.classify(transaction)).categoryId, 'category-1');
+    assert.deepEqual(states[0], {
+        transaction: {
+            payee: 'Employer 1',
+            imported_payee: 'Deposit',
+            notes: 'Monthly',
+            amount_minor_units: 10000,
+            date: '2026-09-01',
+            account: 'Checking',
+        },
+        payee_default_category: null,
+        relevant_examples: [],
+    });
+    await classifier.classify({ ...transaction, payee_name: 'Explicit name' });
+    assert.equal(states[1]?.transaction.payee, 'Explicit name');
+    assert.equal(loads, 1);
+    revision = 2;
+    await classifier.refresh();
+    assert.equal(loads, 2);
+    assert.equal(classifier.categories[0]?.id, 'category-2');
+    assert.equal((await classifier.classify(transaction)).categoryId, 'category-2');
+    assert.equal(states[2]?.transaction.payee, 'Employer 2');
+});
+void test('loads category notes and builds examples only from eligible categorized history', async () => {
+    const notes = [];
+    const actual = {
+        getCategoryGroups: () => Promise.resolve([
+            {
+                id: 'food',
+                name: 'Food',
+                categories: [
+                    { id: 'groceries', name: 'Groceries', group_id: 'food' },
+                    { id: 'restaurants', name: 'Restaurants', group_id: 'food' },
+                ],
+            },
+        ]),
+        getPayees: () => Promise.resolve([
+            { id: 'shop', name: 'Fresh Market' },
+            { id: 'transfer', name: 'Transfer', transfer_acct: 'other' },
+        ]),
+        getNote(id) {
+            notes.push(id);
+            return Promise.resolve(id === 'restaurants' ? { id, note: '#template 250\nPrepared deli meals\n#goal 1000' } : null);
+        },
+    };
+    const base = { account: 'checking', date: '2026-09-01', amount: -1000 };
+    const history = [
+        {
+            ...base,
+            id: 'parent',
+            payee: 'shop',
+            subtransactions: [
+                { ...base, id: 'grocery', category: 'groceries', is_child: true, notes: 'Produce' },
+                { ...base, id: 'deli', category: 'restaurants', is_child: true, notes: 'Deli lunch' },
+            ],
+        },
+        { ...base, id: 'transfer', payee: 'transfer', category: 'groceries' },
+        { ...base, id: 'tracking', account: 'tracking', payee: 'shop', category: 'groceries' },
+        { ...base, id: 'uncategorized', payee: 'shop' },
+    ];
+    const client = {
+        systemOne(request) {
+            assert.equal(request.questions.category.criteria.category_1, 'Food / Restaurants. Category note: Prepared deli meals');
+            const state = request.state;
+            assert.deepEqual(state.relevant_examples.map((example) => [example.notes, example.category]), [
+                ['Produce', 'category_0'],
+                ['Deli lunch', 'category_1'],
+            ]);
+            return Promise.resolve({
+                answers: {
+                    category: {
+                        choice: 'category_1',
+                        confidence: 0.9,
+                        probabilities: { category_0: 0.1, category_1: 0.9, none_of_the_above: 0 },
+                    },
+                },
+            });
+        },
+    };
+    const classifier = await createActualClassifier(actual, {
+        client,
+        history,
+        eligibleAccountIds: new Set(['checking']),
+    });
+    assert.deepEqual(notes, ['groceries', 'restaurants']);
+    assert.equal((await classifier.classify({ ...base, id: 'new', payee: 'shop' })).requiresReview, true);
+});

package/dist/args.d.ts

@@ -0,0 +1,9 @@
+import type { RunOptions } from './workflow.js';
+export type CliOptions = RunOptions & {
+    maxExamplesPerCategory?: number;
+    dataDir?: string;
+    envFile?: string;
+    help: boolean;
+    command: 'run' | 'setup' | 'config-show';
+};
+export declare function parseArgs(args: readonly string[]): CliOptions;

package/dist/args.js

@@ -0,0 +1,90 @@
+function parseDate(value, flag) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) ||
+        Number.isNaN(Date.parse(`${value}T00:00:00Z`)) ||
+        new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value) {
+        throw new Error(`${flag} requires a valid YYYY-MM-DD date`);
+    }
+    return value;
+}
+export function parseArgs(args) {
+    let command = 'run';
+    if (args[0] === 'setup') {
+        command = 'setup';
+        args = args.slice(1);
+    }
+    else if (args[0] === 'config' && args[1] === 'show') {
+        command = 'config-show';
+        args = args.slice(2);
+    }
+    let mode;
+    const options = {
+        command,
+        mode: 'interactive',
+        threshold: 0.9,
+        account: undefined,
+        from: undefined,
+        to: undefined,
+        dataDir: undefined,
+        help: false,
+    };
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (command === 'setup' && arg !== '--help' && arg !== '-h')
+            throw new Error('setup accepts only --help; it edits saved configuration');
+        if (command === 'config-show' &&
+            !['--env-file', '--threshold', '--max-examples-per-category', '--data-dir', '--help', '-h'].includes(arg))
+            throw new Error('config show accepts only --env-file, --threshold, --max-examples-per-category, --data-dir, and --help');
+        function value() {
+            const next = args[++index];
+            if (!next || next.startsWith('--'))
+                throw new Error(`${arg} requires a value`);
+            return next;
+        }
+        switch (arg) {
+            case '--help':
+            case '-h':
+                options.help = true;
+                break;
+            case '--auto':
+            case '--interactive':
+            case '--dry-run':
+                if (mode)
+                    throw new Error('Choose only one mode');
+                mode = arg.slice(2);
+                options.mode = mode;
+                break;
+            case '--threshold':
+                options.threshold = Number(value());
+                if (!Number.isFinite(options.threshold) || options.threshold < 0 || options.threshold > 1)
+                    throw new Error('--threshold must be between 0 and 1');
+                break;
+            case '--max-examples-per-category':
+                options.maxExamplesPerCategory = Number(value());
+                if (!Number.isSafeInteger(options.maxExamplesPerCategory) ||
+                    options.maxExamplesPerCategory < 0 ||
+                    options.maxExamplesPerCategory > 100)
+                    throw new Error('--max-examples-per-category must be an integer between 0 and 100');
+                break;
+            case '--account':
+                options.account = value();
+                break;
+            case '--from':
+                options.from = parseDate(value(), arg);
+                break;
+            case '--to':
+                options.to = parseDate(value(), arg);
+                break;
+            case '--env-file':
+                options.envFile = value();
+                break;
+            case '--data-dir':
+                options.dataDir = value();
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    if (options.from && options.to && options.from > options.to)
+        throw new Error('--from must be on or before --to');
+    return options;
+}

package/dist/args.test.d.ts

@@ -0,0 +1 @@
+export {};