@emilfrom/n8n-nodes-actual-budget 1.0.2 → 2.0.1

package/README.md

@@ -1,8 +1,7 @@
 # @emilfrom/n8n-nodes-actual-budget
 
-This is an n8n community node for importing income and expenses into
-[Actual Budget](https://actualbudget.org/) through
-[actual-http-api](https://github.com/jhonderson/actual-http-api).
+This is an n8n community node for working with [Actual Budget](https://actualbudget.org/)
+through [actual-http-api](https://github.com/jhonderson/actual-http-api).
 
 [n8n](https://n8n.io/) is a workflow automation platform.
 
@@ -51,39 +50,60 @@ Create an `Actual HTTP API` credential in n8n with:
 
 The credential test calls `GET /budgets/{budgetSyncId}/accounts`.
 
-## Operations
+## Node version 2 (breaking change)
 
-### Transaction: Import Expense/Income
+Version **2** of the **Actual Budget** node removes the old **Import** operation (which used
+`POST .../transactions/import` and `imported_id` dedupe). Workflows must use **Transaction: Create**
+and amounts as **integer minor units**, matching the [actual-http-api](https://github.com/jhonderson/actual-http-api)
+contract (`value * 100` for most currencies).
 
-Imports one transaction per incoming n8n item using Actual's transaction import
-endpoint. This operation is idempotent when the same transaction UUID is reused,
-because the UUID is sent as `imported_id`.
+## Actions
 
-Required fields:
+Pick an **Action** on the node:
 
-- `Account`: Actual account ID, selectable from actual-http-api
-- `Transaction Type`: `Expense` or `Income`
-- `Amount`: Positive decimal amount, for example `12.34`
-- `Date`: Transaction date or date-time. Actual stores the date only.
-- `Transaction UUID`: Stable unique identifier for dedupe/upsert behavior
-- `Payee`: Existing payee from the dropdown or a payee name
-- `Category`: Actual category ID, selectable from actual-http-api
+### Transaction: Create
 
-Optional fields:
+Creates one transaction per input item using the official single-create endpoint:
 
-- `Notes`
-- `Cleared`
-- `Default Cleared`
-- `Dry Run`
-- `Reimport Deleted`
+`POST /budgets/{budgetSyncId}/accounts/{accountId}/transactions`
 
-## Amounts
+Request body matches the API: `learnCategories`, `runTransfers`, and `transaction` with
+`account`, `category`, `amount`, `payee_name`, `date`, `cleared` only.
 
-Enter positive decimal amounts. The node converts them to Actual's integer amount
-format:
+- **Account** / **Category**: selectable lists from `GET /accounts` and `GET /categories`
+- **Amount**: integer minor units (for example `-7374` for `-73.74` in a two-decimal currency)
+- **Date**: stored as `YYYY-MM-DD`
+- **Payee Name**: plain text (for example `Amazon`)
+- **Cleared**, **Learn Categories**, **Run Transfers**: booleans
 
-- Expense `12.34` becomes `-1234`
-- Income `12.34` becomes `1234`
+### Budget: Get Month
+
+`GET /budgets/{budgetSyncId}/months/{month}` — pass **Month** as `YYYY-MM`. Output includes the API
+`data` payload (totals, category groups, etc.).
+
+### Account: List
+
+`GET /budgets/{budgetSyncId}/accounts` — returns the API response (including `data`).
+
+### Category: List
+
+`GET /budgets/{budgetSyncId}/categories` — returns the API response (including `data`).
+
+## Debugging (logs)
+
+This node uses n8n’s **`LoggerProxy`** from `n8n-workflow` (same approach as [n8n’s logging docs](https://docs.n8n.io/hosting/logging-monitoring/logging/)): each outbound call logs at **info** (method, resource, URL with the sync id redacted), extra hints at **debug**, and **warn** if the request fails (HTTP status when present).
+
+**Where to read logs:** server stdout/stderr (Docker/Kubernetes logs) or the log file if you enable file output — not the workflow execution panel in the editor.
+
+**Environment variables** (optional; defaults are usually enough until you need more detail):
+
+| Variable | Typical value | Purpose |
+|----------|-----------------|--------|
+| `N8N_LOG_LEVEL` | `info` (default) | Use **`debug`** to include `Logger.debug` lines (credential-shape hints). |
+| `N8N_LOG_OUTPUT` | `console` (default) | Use `console,file` and set `N8N_LOG_FILE_LOCATION` if you want a persistent log file. |
+| `N8N_LOG_FILE_LOCATION` | e.g. `/home/node/.n8n/logs/n8n.log` | Path when `N8N_LOG_OUTPUT` includes `file`. |
+
+After changing env vars, restart n8n.
 
 ## Development
 

package/dist/nodes/ActualBudget/ActualBudget.node.d.ts

@@ -5,12 +5,10 @@ export declare class ActualBudget implements INodeType {
         listSearch: {
             getAccounts: typeof getAccounts;
             getCategories: typeof getCategories;
-            getPayees: typeof getPayees;
         };
     };
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
 }
 declare function getAccounts(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
 declare function getCategories(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
-declare function getPayees(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
 export {};

package/dist/nodes/ActualBudget/ActualBudget.node.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ActualBudget = void 0;
 const n8n_workflow_1 = require("n8n-workflow");
 const transport_1 = require("./transport");
-const showForImportTransaction = {
-    resource: ['transaction'],
-    operation: ['import'],
+const showForTransactionCreate = {
+    action: ['transactionCreate'],
+};
+const showForBudgetGet = {
+    action: ['budgetGet'],
 };
 function parseActualDate(value) {
     const rawDate = value.trim();
@@ -19,12 +21,15 @@ function parseActualDate(value) {
     }
     return parsedDate.toISOString().slice(0, 10);
 }
-function decimalToActualAmount(value, transactionType) {
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new n8n_workflow_1.ApplicationError('Amount must be a positive number');
+function parseMinorUnitsAmount(value) {
+    if (!Number.isFinite(value)) {
+        throw new n8n_workflow_1.ApplicationError('Amount must be an integer in minor currency units (e.g. -7374 for -73.74)');
+    }
+    const rounded = Math.round(value);
+    if (Math.abs(value - rounded) > 1e-9) {
+        throw new n8n_workflow_1.ApplicationError('Amount must be an integer in minor currency units (e.g. -7374 for -73.74)');
     }
-    const unsignedAmount = Math.round(value * 100);
-    return transactionType === 'expense' ? -unsignedAmount : unsignedAmount;
+    return rounded;
 }
 function filterResults(items, filter) {
     if (!filter) {
@@ -40,9 +45,9 @@ class ActualBudget {
             name: 'actualBudget',
             icon: { light: 'file:actual-budget.svg', dark: 'file:actual-budget.dark.svg' },
             group: ['input'],
-            version: 1,
-            subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
-            description: 'Import income and expenses into Actual Budget via actual-http-api',
+            version: 2,
+            subtitle: '={{$parameter["action"]}}',
+            description: 'Read budgets and create transactions in Actual Budget via actual-http-api (official endpoints)',
             defaults: {
                 name: 'Actual Budget',
             },
@@ -57,37 +62,37 @@ class ActualBudget {
             ],
             properties: [
                 {
-                    displayName: 'Resource',
-                    name: 'resource',
+                    displayName: 'Action',
+                    name: 'action',
                     type: 'options',
                     noDataExpression: true,
                     options: [
                         {
-                            name: 'Transaction',
-                            value: 'transaction',
+                            name: 'Account: List',
+                            value: 'accountList',
+                            action: 'List accounts',
+                            description: 'GET /accounts',
                         },
-                    ],
-                    default: 'transaction',
-                },
-                {
-                    displayName: 'Operation',
-                    name: 'operation',
-                    type: 'options',
-                    noDataExpression: true,
-                    displayOptions: {
-                        show: {
-                            resource: ['transaction'],
+                        {
+                            name: 'Budget: Get Month',
+                            value: 'budgetGet',
+                            action: 'Get budget month',
+                            description: 'GET /months/{month}',
+                        },
+                        {
+                            name: 'Category: List',
+                            value: 'categoryList',
+                            action: 'List categories',
+                            description: 'GET /categories',
                         },
-                    },
-                    options: [
                         {
-                            name: 'Import Expense/Income',
-                            value: 'import',
-                            action: 'Import an income or expense transaction',
-                            description: 'Import one transaction using Actual import dedupe behavior',
+                            name: 'Transaction: Create',
+                            value: 'transactionCreate',
+                            action: 'Create a transaction',
+                            description: 'POST /accounts/{ID}/transactions',
                         },
                     ],
-                    default: 'import',
+                    default: 'transactionCreate',
                 },
                 {
                     displayName: 'Account',
@@ -96,7 +101,7 @@ class ActualBudget {
                     default: { mode: 'list', value: '' },
                     required: true,
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
                     modes: [
                         {
@@ -117,27 +122,37 @@ class ActualBudget {
                             placeholder: 'e.g. 729cb492-4eab-468b-9522-75d455cded22',
                         },
                     ],
-                    description: 'Actual account to import the transaction into',
+                    description: 'Account for the transaction',
                 },
                 {
-                    displayName: 'Transaction Type',
-                    name: 'transactionType',
-                    type: 'options',
+                    displayName: 'Category',
+                    name: 'categoryId',
+                    type: 'resourceLocator',
+                    default: { mode: 'list', value: '' },
+                    required: true,
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
-                    options: [
+                    modes: [
                         {
-                            name: 'Expense',
-                            value: 'expense',
+                            displayName: 'Category',
+                            name: 'list',
+                            type: 'list',
+                            placeholder: 'Select a category...',
+                            typeOptions: {
+                                searchListMethod: 'getCategories',
+                                searchable: true,
+                                searchFilterRequired: false,
+                            },
                         },
                         {
-                            name: 'Income',
-                            value: 'income',
+                            displayName: 'By ID',
+                            name: 'id',
+                            type: 'string',
+                            placeholder: 'e.g. 9fa2550c-c3ff-498b-8df6-e0fbe2a62e0e',
                         },
                     ],
-                    default: 'expense',
-                    description: 'Whether the positive amount should be imported as money out or money in',
+                    description: 'Category ID for the transaction',
                 },
                 {
                     displayName: 'Amount',
@@ -145,14 +160,13 @@ class ActualBudget {
                     type: 'number',
                     required: true,
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
                     typeOptions: {
-                        minValue: 0,
-                        numberPrecision: 2,
+                        numberPrecision: 0,
                     },
                     default: 0,
-                    description: 'Positive decimal amount, for example 12.34',
+                    description: 'Integer minor units (see actual-http-api docs). Example: expense -7374 means -73.74.',
                 },
                 {
                     displayName: 'Date',
@@ -160,143 +174,64 @@ class ActualBudget {
                     type: 'dateTime',
                     required: true,
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
                     default: '',
-                    description: 'Transaction date. Actual stores transactions by date, so time is ignored.',
+                    description: 'Transaction date (YYYY-MM-DD); time is ignored',
                 },
                 {
-                    displayName: 'Transaction UUID',
-                    name: 'transactionUuid',
+                    displayName: 'Payee Name',
+                    name: 'payeeName',
                     type: 'string',
                     required: true,
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
                     default: '',
-                    description: 'Stable transaction identifier to send as imported_id for dedupe/upsert behavior',
+                    placeholder: 'e.g. Amazon',
+                    description: 'Payee label for the transaction',
                 },
                 {
-                    displayName: 'Payee',
-                    name: 'payeeName',
-                    type: 'resourceLocator',
-                    default: { mode: 'list', value: '' },
-                    required: true,
+                    displayName: 'Cleared',
+                    name: 'cleared',
+                    type: 'boolean',
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
-                    modes: [
-                        {
-                            displayName: 'Payee',
-                            name: 'list',
-                            type: 'list',
-                            placeholder: 'Select a payee...',
-                            typeOptions: {
-                                searchListMethod: 'getPayees',
-                                searchable: true,
-                                searchFilterRequired: false,
-                            },
-                        },
-                        {
-                            displayName: 'By Name',
-                            name: 'name',
-                            type: 'string',
-                            placeholder: 'e.g. Grocery Store',
-                        },
-                    ],
-                    description: 'Existing payee to use, or a payee name for Actual to match/create',
+                    default: false,
+                    description: 'Whether the transaction is cleared',
                 },
                 {
-                    displayName: 'Category',
-                    name: 'categoryId',
-                    type: 'resourceLocator',
-                    default: { mode: 'list', value: '' },
-                    required: true,
+                    displayName: 'Learn Categories',
+                    name: 'learnCategories',
+                    type: 'boolean',
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
-                    modes: [
-                        {
-                            displayName: 'Category',
-                            name: 'list',
-                            type: 'list',
-                            placeholder: 'Select a category...',
-                            typeOptions: {
-                                searchListMethod: 'getCategories',
-                                searchable: true,
-                                searchFilterRequired: false,
-                            },
-                        },
-                        {
-                            displayName: 'By ID',
-                            name: 'id',
-                            type: 'string',
-                            placeholder: 'e.g. 9fa2550c-c3ff-498b-8df6-e0fbe2a62e0e',
-                        },
-                    ],
-                    description: 'Actual category for the transaction',
+                    default: false,
+                    description: 'Whether to pass learnCategories to actual-http-api',
                 },
                 {
-                    displayName: 'Additional Fields',
-                    name: 'additionalFields',
-                    type: 'collection',
-                    placeholder: 'Add Field',
-                    default: {},
+                    displayName: 'Run Transfers',
+                    name: 'runTransfers',
+                    type: 'boolean',
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForTransactionCreate,
                     },
-                    options: [
-                        {
-                            displayName: 'Cleared',
-                            name: 'cleared',
-                            type: 'boolean',
-                            default: true,
-                            description: 'Whether this transaction should be marked as cleared',
-                        },
-                        {
-                            displayName: 'Notes',
-                            name: 'notes',
-                            type: 'string',
-                            typeOptions: {
-                                rows: 3,
-                            },
-                            default: '',
-                            description: 'Optional transaction notes',
-                        },
-                    ],
+                    default: false,
+                    description: 'Whether to pass runTransfers to actual-http-api',
                 },
                 {
-                    displayName: 'Import Options',
-                    name: 'importOptions',
-                    type: 'collection',
-                    placeholder: 'Add Option',
-                    default: {},
+                    displayName: 'Month',
+                    name: 'month',
+                    type: 'string',
+                    required: true,
                     displayOptions: {
-                        show: showForImportTransaction,
+                        show: showForBudgetGet,
                     },
-                    options: [
-                        {
-                            displayName: 'Default Cleared',
-                            name: 'defaultCleared',
-                            type: 'boolean',
-                            default: true,
-                            description: 'Whether imported transactions should default to cleared',
-                        },
-                        {
-                            displayName: 'Dry Run',
-                            name: 'dryRun',
-                            type: 'boolean',
-                            default: false,
-                            description: 'Whether to preview import results without changing the budget',
-                        },
-                        {
-                            displayName: 'Reimport Deleted',
-                            name: 'reimportDeleted',
-                            type: 'boolean',
-                            default: false,
-                            description: 'Whether to reimport transactions previously deleted in Actual',
-                        },
-                    ],
+                    default: '',
+                    placeholder: '2026-05',
+                    description: 'Budget month in YYYY-MM format',
                 },
             ],
         };
@@ -304,58 +239,80 @@ class ActualBudget {
             listSearch: {
                 getAccounts,
                 getCategories,
-                getPayees,
             },
         };
     }
     async execute() {
-        var _a, _b, _c;
         const items = this.getInputData();
         const returnData = [];
         for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
             try {
-                const accountId = this.getNodeParameter('accountId', itemIndex, '', {
-                    extractValue: true,
-                });
-                const categoryId = this.getNodeParameter('categoryId', itemIndex, '', {
-                    extractValue: true,
-                });
-                const payeeName = this.getNodeParameter('payeeName', itemIndex, '', {
-                    extractValue: true,
-                });
-                const transactionType = this.getNodeParameter('transactionType', itemIndex);
-                const amount = this.getNodeParameter('amount', itemIndex);
-                const date = this.getNodeParameter('date', itemIndex);
-                const transactionUuid = this.getNodeParameter('transactionUuid', itemIndex);
-                const additionalFields = this.getNodeParameter('additionalFields', itemIndex, {});
-                const importOptions = this.getNodeParameter('importOptions', itemIndex, {});
-                const transaction = {
-                    account: accountId,
-                    amount: decimalToActualAmount(amount, transactionType),
-                    category: categoryId,
-                    date: parseActualDate(date),
-                    imported_id: transactionUuid,
-                    payee_name: payeeName,
-                };
-                if (additionalFields.notes) {
-                    transaction.notes = additionalFields.notes;
+                const action = this.getNodeParameter('action', itemIndex);
+                if (action === 'transactionCreate') {
+                    const accountId = this.getNodeParameter('accountId', itemIndex, '', {
+                        extractValue: true,
+                    });
+                    const categoryId = this.getNodeParameter('categoryId', itemIndex, '', {
+                        extractValue: true,
+                    });
+                    const amount = parseMinorUnitsAmount(this.getNodeParameter('amount', itemIndex));
+                    const date = this.getNodeParameter('date', itemIndex);
+                    const payeeName = this.getNodeParameter('payeeName', itemIndex);
+                    const cleared = this.getNodeParameter('cleared', itemIndex, false);
+                    const learnCategories = this.getNodeParameter('learnCategories', itemIndex, false);
+                    const runTransfers = this.getNodeParameter('runTransfers', itemIndex, false);
+                    const body = {
+                        learnCategories,
+                        runTransfers,
+                        transaction: {
+                            account: accountId,
+                            category: categoryId,
+                            amount,
+                            payee_name: payeeName,
+                            date: parseActualDate(date),
+                            cleared,
+                        },
+                    };
+                    const responseData = (await transport_1.actualApiRequest.call(this, 'POST', `/accounts/${encodeURIComponent(accountId)}/transactions`, body));
+                    returnData.push({
+                        json: {
+                            ...responseData,
+                            request: body,
+                        },
+                        pairedItem: itemIndex,
+                    });
+                    continue;
                 }
-                if (additionalFields.cleared !== undefined) {
-                    transaction.cleared = additionalFields.cleared;
+                if (action === 'budgetGet') {
+                    const month = this.getNodeParameter('month', itemIndex);
+                    const trimmed = month.trim();
+                    if (!/^\d{4}-\d{2}$/.test(trimmed)) {
+                        throw new n8n_workflow_1.ApplicationError('Month must be in YYYY-MM format');
+                    }
+                    const response = (await transport_1.actualApiRequest.call(this, 'GET', `/months/${encodeURIComponent(trimmed)}`));
+                    returnData.push({
+                        json: response,
+                        pairedItem: itemIndex,
+                    });
+                    continue;
                 }
-                const responseData = (await transport_1.actualApiRequest.call(this, 'POST', `/accounts/${encodeURIComponent(accountId)}/transactions/import`, {
-                    transactions: [transaction],
-                    defaultCleared: (_a = importOptions.defaultCleared) !== null && _a !== void 0 ? _a : true,
-                    dryRun: (_b = importOptions.dryRun) !== null && _b !== void 0 ? _b : false,
-                    reimportDeleted: (_c = importOptions.reimportDeleted) !== null && _c !== void 0 ? _c : false,
-                }));
-                returnData.push({
-                    json: {
-                        ...responseData,
-                        transaction,
-                    },
-                    pairedItem: itemIndex,
-                });
+                if (action === 'accountList') {
+                    const response = (await transport_1.actualApiRequest.call(this, 'GET', '/accounts'));
+                    returnData.push({
+                        json: response,
+                        pairedItem: itemIndex,
+                    });
+                    continue;
+                }
+                if (action === 'categoryList') {
+                    const response = (await transport_1.actualApiRequest.call(this, 'GET', '/categories'));
+                    returnData.push({
+                        json: response,
+                        pairedItem: itemIndex,
+                    });
+                    continue;
+                }
+                throw new n8n_workflow_1.ApplicationError(`Unsupported action: ${action}`);
             }
             catch (error) {
                 if (this.continueOnFail()) {
@@ -387,33 +344,13 @@ async function getAccounts(filter) {
     return { results };
 }
 async function getCategories(filter) {
-    var _a, _b;
-    const response = (await transport_1.actualApiRequest.call(this, 'GET', '/categorygroups'));
-    const results = [];
-    for (const group of (_a = response.data) !== null && _a !== void 0 ? _a : []) {
-        if (group.hidden) {
-            continue;
-        }
-        for (const category of (_b = group.categories) !== null && _b !== void 0 ? _b : []) {
-            if (category.hidden) {
-                continue;
-            }
-            results.push({
-                name: `${group.name} / ${category.name}`,
-                value: category.id,
-            });
-        }
-    }
-    return { results: filterResults(results, filter) };
-}
-async function getPayees(filter) {
     var _a;
-    const response = (await transport_1.actualApiRequest.call(this, 'GET', '/payees'));
-    const payees = filterResults((_a = response.data) !== null && _a !== void 0 ? _a : [], filter);
-    const results = payees.map((payee) => ({
-        name: payee.name,
-        value: payee.name,
+    const response = (await transport_1.actualApiRequest.call(this, 'GET', '/categories'));
+    const visible = ((_a = response.data) !== null && _a !== void 0 ? _a : []).filter((c) => !c.hidden);
+    const results = visible.map((category) => ({
+        name: category.name,
+        value: category.id,
     }));
-    return { results };
+    return { results: filterResults(results, filter) };
 }
 //# sourceMappingURL=ActualBudget.node.js.map