israeli-banks-actual-budget-importer 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.10.0](https://github.com/tomerh2001/israeli-banks-actual-budget-importer/compare/v1.9.0...v1.10.0) (2026-01-04)
+
+
+### Features
+
+* enhance reconciliation options and update configuration schema ([2d873a5](https://github.com/tomerh2001/israeli-banks-actual-budget-importer/commit/2d873a542915be3d35ac7ab36003d4617d6256c4))
+
 # [1.9.0](https://github.com/tomerh2001/israeli-banks-actual-budget-importer/compare/v1.8.1...v1.9.0) (2026-01-03)
 
 

package/README.md

@@ -9,22 +9,29 @@ This project provides an importer from Israeli banks (via [israeli-bank-scrapers
 
 ## Features
 
-1. **Multi Bank Support**: Supports all of the institutions that the [israeli-bank-scrapers](https://github.com/eshaham/israeli-bank-scrapers) library covers (Bank Hapoalim, Cal, Leumi, Discount, etc.).
+1. **Multi Bank Support**  
+   Supports all of the institutions that the [israeli-bank-scrapers](https://github.com/eshaham/israeli-bank-scrapers) library covers (Bank Hapoalim, Cal, Leumi, Discount, etc.).
 
-2. **Prevents duplicate transactions** using Actual’s [`imported_id`](https://actualbudget.org/docs/api/reference/#transactions) logic.
+2. **Prevents duplicate transactions**  
+   Uses Actual’s [`imported_id`](https://actualbudget.org/docs/api/reference/#transactions) logic.
 
-3. **Automatic Account Creation**: If the bank account does not exist in Actual, it will be created automatically.
+3. **Automatic Account Creation**  
+   If the bank account does not exist in Actual, it will be created automatically.
 
-4. **Reconciliation:** Optional reconciliation to adjust account balances automatically.
+4. **Reconciliation**  
+   Optional reconciliation to adjust account balances automatically.
 
-5. **Credit Card / Multi-Account Mapping (Targets):** Supports mapping multiple scraped accounts/cards into one Actual account, or mapping each scraped card into its own Actual account (via `targets` and `accounts`).
+5. **Credit Card / Multi-Account Mapping (Targets)**  
+   Supports mapping multiple scraped accounts/cards into one Actual account, or mapping each scraped card into its own Actual account (via `targets` and `accounts`).
 
-6. **Concurrent Processing:** Uses a queue (via [p-queue](https://www.npmjs.com/package/p-queue)) to manage scraping tasks concurrently.
+6. **Concurrent Processing**  
+   Uses a queue (via [p-queue](https://www.npmjs.com/package/p-queue)) to manage scraping tasks concurrently.
 
 ## Installation
 
 ### Docker
 https://hub.docker.com/r/tomerh2001/israeli-banks-actual-budget-importer
+
 #### Example
 ```yml
 services:
@@ -44,18 +51,18 @@ services:
 
 ## Configuration
 
-The application configuration is defined using JSON and validated against a schema.
+The application configuration is defined using JSON and validated against a schema.  
 The main configuration file is `config.json`.
 
 The configuration has **two independent top-level sections**:
-1. `actual`: Configures the Actual Budget connection.
-2. `banks`: Configures bank scrapers and account mappings.
+1. `actual` – Configures the Actual Budget connection.
+2. `banks` – Configures bank scrapers and account mappings.
 
 ---
 
-### 1) `actual` configuration
+### 1) `actual` section
 
-This section configures the connection to your Actual Budget server and budget.
+This section configures the connection to your Actual Budget server and budget.  
 It is **always required**, regardless of how you configure banks or targets.
 
 ```json
@@ -78,7 +85,7 @@ Nothing in this block changes when using `targets`, credit cards, or multi-accou
 
 ---
 
-### 2) `banks` configuration
+### 2) `banks` section
 
 The `banks` section defines:
 - Which banks to scrape
@@ -86,11 +93,13 @@ The `banks` section defines:
 - How scraped accounts/cards are mapped into Actual accounts
 
 Each bank entry includes the credentials required by `israeli-bank-scrapers`
-(e.g. `userCode`, `username`, `password`, etc.) and supports **multiple mapping modes**.
+(e.g. `userCode`, `username`, `password`, etc.).
+
+---
 
-#### Using `targets` (recommended)
+### `targets` sub-section
 
-A single bank scrape (for example `visaCal`) may return **multiple accounts/cards**.
+A single bank scrape (for example `visaCal`) may return **multiple accounts/cards**.  
 Different users model these differently in Actual, so the importer supports `targets`.
 
 Each **target** represents:
@@ -99,12 +108,21 @@ Each **target** represents:
 
 For each target:
 - Imported transactions = concatenation of transactions from selected cards
-- Reconciliation (if enabled) = sum of balances of selected cards
+- Reconciliation (if enabled) = sum of balances of selected cards  
   (only cards with a valid numeric balance are included)
 
 ---
 
-#### Example A: One Actual account for all VisaCal cards (consolidated)
+### Reconciliation behavior
+
+- Reconciliation is controlled by the `reconcile` boolean.
+- When `reconcile: true`, **a new reconciliation transaction is created on every run** (no updates, no reconciliation).
+- Existing reconciliation transactions are never modified or reused.
+- If `reconcile` is omitted or set to `false`, no reconciliation transaction is created.
+
+---
+
+### Example A: One Actual account for all VisaCal cards
 
 ```json
 {
@@ -137,7 +155,7 @@ For each target:
 
 ---
 
-#### Example B: One Actual account per VisaCal card (separate accounts)
+### Example B: One Actual account per VisaCal card
 
 ```json
 {
@@ -175,7 +193,7 @@ For each target:
 
 ---
 
-#### Example C: Grouped cards into a single Actual account (subset)
+### Example C: Grouped cards into a single Actual account (subset)
 
 ```json
 {
@@ -210,7 +228,7 @@ For each target:
 
 ## Legacy configuration (single Actual account per bank)
 
-This configuration style is **fully supported for backward compatibility**,
+This configuration style is **fully supported for backward compatibility**,  
 but does **not** allow fine-grained control over multiple cards/accounts.
 
 It maps all scraped accounts from the bank into a single Actual account.
@@ -261,4 +279,4 @@ This project is open-source. Please see the [LICENSE](./LICENSE) file for licens
 
 - **israeli-bank-scrapers:** Thanks to the contributors of the bank scraper libraries.
 - **Actual App:** For providing a powerful budgeting API.
-- **Open-source Community:** Your support and contributions are appreciated.
+- **Open-source Community:** Your support and contributions are appreciated.

package/config.schema.json

@@ -64,6 +64,16 @@
         }
       ]
     },
+    "ReconcileOption": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "const": "consolidate"
+        }
+      ]
+    },
     "ConfigBankTarget": {
       "additionalProperties": false,
       "properties": {
@@ -71,7 +81,7 @@
           "type": "string"
         },
         "reconcile": {
-          "type": "boolean"
+          "$ref": "#/definitions/ReconcileOption"
         },
         "accounts": {
           "$ref": "#/definitions/AccountsSelector"
@@ -89,7 +99,7 @@
           "type": "string"
         },
         "reconcile": {
-          "type": "boolean"
+          "$ref": "#/definitions/ReconcileOption"
         }
       },
       "required": [
@@ -126,7 +136,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -167,7 +177,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -208,7 +218,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -252,7 +262,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -297,7 +307,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -342,7 +352,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -390,7 +400,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",
@@ -436,7 +446,7 @@
               "type": "string"
             },
             "reconcile": {
-              "type": "boolean"
+              "$ref": "#/definitions/ReconcileOption"
             },
             "targets": {
               "type": "array",

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.0",
+  "version": "1.10.0",
   "name": "israeli-banks-actual-budget-importer",
   "module": "index.ts",
   "type": "module",
@@ -25,7 +25,7 @@
   },
   "packageManager": "yarn@4.12.0",
   "dependencies": {
-    "@actual-app/api": "^25.12.0",
+    "@actual-app/api": "^26.1.0",
     "@tomerh2001/israeli-bank-scrapers": "6.4.0",
     "cronstrue": "^3.9.0",
     "lodash": "^4.17.21",

package/src/config.d.ts

@@ -17,6 +17,8 @@ export type ConfigActualBudget = {
 };
 
 export type ConfigBanks = Partial<Record<CompanyTypes, ConfigBank>>;
+export type AccountsSelector = string[] | 'all';
+export type ReconcileSelector = boolean | 'consolidate';
 
 /**
  * A single "import target" inside Actual.
@@ -30,8 +32,11 @@ export type ConfigBankTarget = {
 
 	/**
 	 * If true, create/update a reconciliation transaction to match the scraped balance.
+	 * If 'consolidate', reconcile once per Actual account using the consolidated balance
+	 * across all selected scraped accounts.
+	 * If false/undefined, do not reconcile.
 	 */
-	reconcile?: boolean;
+	reconcile?: ReconcileSelector;
 
 	/**
 	 * Which scraped accounts (by accountNumber) should be included in this target.
@@ -42,7 +47,7 @@ export type ConfigBankTarget = {
 	 * - treat as "all" for import, and for reconciliation use the first usable balance
 	 *   (you'll refine this in the implementation files).
 	 */
-	accounts?: 'all' | string[];
+	accounts?: AccountsSelector;
 };
 
 /**
@@ -61,5 +66,5 @@ export type ConfigBank = ScraperCredentials & {
 	 * If targets is provided, these should be ignored by runtime logic.
 	 */
 	actualAccountId?: string;
-	reconcile?: boolean;
+	reconcile?: ReconcileSelector;
 };

package/src/{utils.ts → importer.ts}

@@ -1,3 +1,6 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+/* eslint-disable no-await-in-loop */
+// Importer.ts
 /* eslint-disable @typescript-eslint/no-unsafe-argument */
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -8,73 +11,18 @@ import {createScraper, type ScraperCredentials} from '@tomerh2001/israeli-bank-s
 import _ from 'lodash';
 import moment from 'moment';
 import actual from '@actual-app/api';
-import {type PayeeEntity, type TransactionEntity} from '@actual-app/api/@types/loot-core/src/types/models';
+import {type PayeeEntity} from '@actual-app/api/@types/loot-core/src/types/models';
 import stdout from 'mute-stdout';
-import {type ScrapeTransactionsContext} from './utils.d';
-
-// If you exported these from your config types file, import them from there instead.
-type AccountsSelector = 'all' | string[];
-type BankTarget = {
-	actualAccountId: string;
-	reconcile?: boolean;
-	accounts?: AccountsSelector;
-};
-
-function isFiniteNumber(x: unknown): x is number {
-	return typeof x === 'number' && Number.isFinite(x);
-}
-
-function stripUndefined<T extends Record<string, any>>(object: T): T {
-	return Object.fromEntries(Object.entries(object).filter(([, v]) => v !== undefined)) as T;
-}
-
-function normalizeTargets(bank: any): BankTarget[] {
-	// New config: targets[]
-	if (Array.isArray(bank?.targets) && bank.targets.length > 0) {
-		return bank.targets
-			.filter((t: any) => t?.actualAccountId)
-			.map((t: any) => ({
-				actualAccountId: t.actualAccountId,
-				reconcile: Boolean(t.reconcile),
-				accounts: t.accounts,
-			}));
-	}
-
-	// Legacy config: actualAccountId + reconcile
-	if (bank?.actualAccountId) {
-		return [{
-			actualAccountId: bank.actualAccountId,
-			reconcile: Boolean(bank.reconcile),
-			// Legacy behavior did not support selecting accounts; treat as "all".
-			accounts: 'all',
-		}];
-	}
-
-	return [];
-}
-
-function selectScraperAccounts(
-	allAccounts: any[] | undefined,
-	selector: AccountsSelector | undefined,
-) {
-	const accounts = allAccounts ?? [];
-	if (selector === undefined || selector === 'all') {
-		return accounts;
-	}
-
-	const set = new Set(selector);
-	return accounts.filter(a => set.has(String(a.accountNumber)));
-}
-
-function stableImportedId(companyId: string, accountNumber: string | undefined, txn: any) {
-	// Prefer scraper identifier if present; fall back to a deterministic composite.
-	const idPart
-		= txn?.identifier
-			?? `${moment(txn?.date).format('YYYY-MM-DD')}:${txn?.chargedAmount}:${txn?.description ?? ''}:${txn?.memo ?? ''}`;
-
-	// AccountNumber is important once multiple cards are aggregated into one Actual account.
-	return `${companyId}:${accountNumber ?? 'unknown'}:${idPart}`;
-}
+import {type ScrapeTransactionsContext} from './importer.d';
+import {
+	normalizeTargets,
+	selectScraperAccounts,
+	stripUndefined,
+	stableImportedId,
+	isFiniteNumber,
+	reconciliationTargetKey,
+	uniqueReconciliationImportedId,
+} from './importer.utils';
 
 export async function scrapeAndImportTransactions({companyId, bank}: ScrapeTransactionsContext) {
 	function log(status: any, other?: Record<string, unknown>) {
@@ -118,7 +66,7 @@ export async function scrapeAndImportTransactions({companyId, bank}: ScrapeTrans
 
 		const payees: PayeeEntity[] = await actual.getPayees();
 
-		// Process each target independently (supports per-card, per-company, and consolidated).
+		// Process each target independently.
 		for (const target of targets) {
 			const selectedAccounts = selectScraperAccounts(result.accounts as any[], target.accounts);
 
@@ -156,6 +104,7 @@ export async function scrapeAndImportTransactions({companyId, bank}: ScrapeTrans
 				}
 			}
 
+			// Reconcile: boolean-only, and ALWAYS creates a NEW reconciliation txn (no updates).
 			if (!target.reconcile) {
 				continue;
 			}
@@ -184,46 +133,26 @@ export async function scrapeAndImportTransactions({companyId, bank}: ScrapeTrans
 			const currentBalance = actual.utils.integerToAmount(await actual.getAccountBalance(target.actualAccountId));
 			const balanceDiff = scraperBalance - currentBalance;
 
-			// Stable imported_id per Actual account so we update the same reconciliation txn each run.
-			const reconciliationImportedId = `reconciliation-${target.actualAccountId}`;
-
-			const allAccountTxns: TransactionEntity[] = await actual.getTransactions(
-				target.actualAccountId,
-				'2000-01-01',
-				moment().add(1, 'year').format('YYYY-MM-DD'),
-			);
-
-			const existingReconciliation = allAccountTxns.find(txn => txn.imported_id === reconciliationImportedId);
-
-			if (existingReconciliation && balanceDiff === 0) {
+			// If there is no diff, creating a reconciliation txn is typically noise.
+			// If you truly want a txn even for 0, remove this guard.
+			if (balanceDiff === 0) {
 				log('RECONCILIATION_NOT_NEEDED', {actualAccountId: target.actualAccountId});
 				continue;
 			}
 
+			const targetKey = reconciliationTargetKey(target.accounts, selectedAccounts);
+			const reconciliationImportedId = uniqueReconciliationImportedId(target.actualAccountId);
+
 			const reconciliationTxn = stripUndefined({
 				account: target.actualAccountId,
 				date: moment().format('YYYY-MM-DD'),
 				amount: actual.utils.amountToInteger(balanceDiff),
 				payee: null, // IMPORTANT: never pass undefined to updateTransaction schema
 				imported_payee: 'Reconciliation',
-				notes: `Reconciliation from ${currentBalance.toLocaleString()} to ${scraperBalance.toLocaleString()}`,
-				imported_id: reconciliationImportedId,
+				notes: `Reconciliation (${targetKey}) from ${currentBalance.toLocaleString()} to ${scraperBalance.toLocaleString()}`,
+				imported_id: reconciliationImportedId, // NEW every run
 			});
 
-			if (existingReconciliation) {
-				stdout.mute();
-				await actual.updateTransaction(existingReconciliation.id, reconciliationTxn);
-				stdout.unmute();
-
-				log('RECONCILIATION_UPDATED', {
-					actualAccountId: target.actualAccountId,
-					from: currentBalance,
-					to: scraperBalance,
-					diff: balanceDiff,
-				});
-				continue;
-			}
-
 			stdout.mute();
 			const reconciliationResult = await actual.importTransactions(target.actualAccountId, [reconciliationTxn]);
 			stdout.unmute();
@@ -236,6 +165,7 @@ export async function scrapeAndImportTransactions({companyId, bank}: ScrapeTrans
 					from: currentBalance,
 					to: scraperBalance,
 					diff: balanceDiff,
+					importedId: reconciliationImportedId,
 				});
 			}
 		}

package/src/importer.utils.ts

@@ -0,0 +1,98 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+
+import moment from 'moment';
+import type {ConfigBankTarget, AccountsSelector} from './config';
+
+export function isFiniteNumber(x: unknown): x is number {
+	return typeof x === 'number' && Number.isFinite(x);
+}
+
+export function stripUndefined<T extends Record<string, any>>(object: T): T {
+	return Object.fromEntries(Object.entries(object).filter(([, v]) => v !== undefined)) as T;
+}
+
+/**
+ * Normalizes bank config into a list of targets.
+ *
+ * IMPORTANT:
+ * - reconcile is boolean-only.
+ * - No consolidation modes.
+ */
+export function normalizeTargets(bank: any): ConfigBankTarget[] {
+	// New config: targets[]
+	if (Array.isArray(bank?.targets) && bank.targets.length > 0) {
+		return bank.targets
+			.filter((t: any) => t?.actualAccountId)
+			.map((t: any) => ({
+				actualAccountId: t.actualAccountId,
+				reconcile: Boolean(t.reconcile),
+				accounts: t.accounts as AccountsSelector | undefined,
+			}));
+	}
+
+	// Legacy config: actualAccountId + reconcile
+	if (bank?.actualAccountId) {
+		return [{
+			actualAccountId: bank.actualAccountId,
+			reconcile: Boolean(bank.reconcile),
+			accounts: 'all',
+		}];
+	}
+
+	return [];
+}
+
+export function selectScraperAccounts(
+	allAccounts: any[] | undefined,
+	selector: AccountsSelector | undefined,
+) {
+	const accounts = allAccounts ?? [];
+	if (selector === undefined || selector === 'all') {
+		return accounts;
+	}
+
+	const set = new Set(selector);
+	return accounts.filter(a => set.has(String(a.accountNumber)));
+}
+
+export function reconciliationTargetKey(selector: AccountsSelector | undefined, selectedAccounts: any[]) {
+	// Prefer concrete selected account numbers (deterministic once scrape ran)
+	const nums = selectedAccounts
+		.map(a => String(a?.accountNumber))
+		.filter(Boolean)
+		.sort();
+
+	if (nums.length > 0) {
+		return nums.join(',');
+	}
+
+	// Fallback
+	if (selector === undefined || selector === 'all') {
+		return 'all';
+	}
+
+	return [...selector].map(String).sort().join(',');
+}
+
+export function stableImportedId(companyId: string, accountNumber: string | undefined, txn: any) {
+	// Prefer scraper identifier if present; fall back to a deterministic composite.
+	const idPart = txn?.identifier
+		?? `${moment(txn?.date).format('YYYY-MM-DD')}:${txn?.chargedAmount}:${txn?.description ?? ''}:${txn?.memo ?? ''}`;
+
+	// AccountNumber is important once multiple cards are aggregated into one Actual account.
+	return `${companyId}:${accountNumber ?? 'unknown'}:${idPart}`;
+}
+
+/**
+ * Generates a unique reconciliation imported_id so a NEW txn is created every run.
+ * (No update logic; no consolidation logic.)
+ */
+export function uniqueReconciliationImportedId(actualAccountId: string) {
+	// Date-based + randomness to avoid collisions if multiple targets reconcile in the same second.
+	const ts = moment().format('YYYY-MM-DDTHH:mm:ss.SSS');
+	const rand = Math.random().toString(16).slice(2, 10);
+	return `reconciliation-${actualAccountId}:${ts}:${rand}`;
+}

package/src/index.ts

@@ -14,7 +14,7 @@ import cronstrue from 'cronstrue';
 import stdout from 'mute-stdout';
 import config from '../config.json' assert {type: 'json'};
 import type {ConfigBank} from './config.d.ts';
-import {scrapeAndImportTransactions} from './utils.ts';
+import {scrapeAndImportTransactions} from './importer';
 
 let scheduledTask: ScheduledTask;