india2actual 0.1.0

package/dist/narration/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The transaction families Indian banks encode into the narration/particulars
+ * column. `other` covers interest postings, charges, cheques and anything else
+ * we do not recognise — it is not an error.
+ */
+export type NarrationKind = 'upi' | 'neft' | 'imps' | 'rtgs' | 'pos' | 'ach' | 'atm' | 'other';
+export type ParsedNarration = {
+    kind: NarrationKind;
+    /**
+     * Display payee. Guaranteed non-empty: when nothing can be extracted this
+     * falls back to the raw narration, so the worst case matches what Actual
+     * would have shown anyway.
+     */
+    merchant: string;
+    /** Virtual Payment Address, e.g. `swiggy@ybl`, when present. */
+    vpa?: string;
+    /**
+     * Bank-issued UPI reference (UTR/RRN). Only set when we are confident it is
+     * genuinely per-transaction unique, because a non-unique value here would
+     * make Actual collapse distinct transactions. See `extractRef`.
+     */
+    ref?: string;
+    /** The narration exactly as the bank wrote it. */
+    raw: string;
+};

package/dist/narration/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/narration/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/narration/types.ts"],"names":[],"mappings":""}

package/dist/out/csv.d.ts

@@ -0,0 +1,21 @@
+import type { StatementTransaction } from '../interpret/rows.js';
+/**
+ * Columns chosen to match what Actual's import dialog can actually map:
+ * date, payee, notes and amount.
+ *
+ * Note the deliberate compromise on notes. Actual's CSV field mapping has no
+ * `imported_payee` slot (only date, amount, payee, notes, category, in/out and
+ * inflow/outflow), so the raw narration goes into Notes to keep it visible.
+ * The API path does not have this limitation and sets `imported_payee`
+ * properly — this is the one place the CSV route is lossier.
+ *
+ * `Reference` is emitted for human inspection; leave it unmapped on import.
+ *
+ * This header is also the signature the round-trip path matches on, so that
+ * the tool can read its own output back and push a CSV you have reviewed.
+ * Renaming or reordering a column here means updating
+ * `interpret/roundtrip.ts`; a test asserts the two agree.
+ */
+export declare const COLUMNS: readonly ["Date", "Payee", "Notes", "Amount", "Reference"];
+export declare function toCsv(transactions: StatementTransaction[]): string;
+export declare function writeCsv(path: string, transactions: StatementTransaction[]): Promise<void>;

package/dist/out/csv.js

@@ -0,0 +1,40 @@
+import { writeFile } from 'node:fs/promises';
+import { stringify } from 'csv-stringify/sync';
+/**
+ * Columns chosen to match what Actual's import dialog can actually map:
+ * date, payee, notes and amount.
+ *
+ * Note the deliberate compromise on notes. Actual's CSV field mapping has no
+ * `imported_payee` slot (only date, amount, payee, notes, category, in/out and
+ * inflow/outflow), so the raw narration goes into Notes to keep it visible.
+ * The API path does not have this limitation and sets `imported_payee`
+ * properly — this is the one place the CSV route is lossier.
+ *
+ * `Reference` is emitted for human inspection; leave it unmapped on import.
+ *
+ * This header is also the signature the round-trip path matches on, so that
+ * the tool can read its own output back and push a CSV you have reviewed.
+ * Renaming or reordering a column here means updating
+ * `interpret/roundtrip.ts`; a test asserts the two agree.
+ */
+export const COLUMNS = [
+    'Date',
+    'Payee',
+    'Notes',
+    'Amount',
+    'Reference',
+];
+export function toCsv(transactions) {
+    const rows = transactions.map(transaction => [
+        transaction.date,
+        transaction.payee,
+        transaction.raw,
+        transaction.amount.toFixed(2),
+        transaction.ref ?? '',
+    ]);
+    return stringify(rows, { header: true, columns: [...COLUMNS] });
+}
+export async function writeCsv(path, transactions) {
+    await writeFile(path, toCsv(transactions), 'utf8');
+}
+//# sourceMappingURL=csv.js.map

package/dist/out/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../../src/out/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAI/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;IACR,WAAW;CACH,CAAC;AAEX,MAAM,UAAU,KAAK,CAAC,YAAoC;IACxD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3C,WAAW,CAAC,IAAI;QAChB,WAAW,CAAC,KAAK;QACjB,WAAW,CAAC,GAAG;QACf,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7B,WAAW,CAAC,GAAG,IAAI,EAAE;KACtB,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,YAAoC;IAEpC,MAAM,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC"}

package/dist/out/push.d.ts

@@ -0,0 +1,74 @@
+import type { StatementTransaction } from '../interpret/rows.js';
+/**
+ * The subset of Actual's `ImportTransactionEntity` we populate. Declared
+ * locally so this module type-checks without `@actual-app/api` installed —
+ * it is an optional peer dependency, since the CSV path is the default and
+ * the API package pulls in a native SQLite build.
+ */
+export type ActualImportTransaction = {
+    date: string;
+    /** Integer paise. */
+    amount: number;
+    payee_name: string;
+    imported_payee: string;
+    notes: string;
+    imported_id?: string;
+    cleared: boolean;
+};
+export type PushConfig = {
+    serverURL: string;
+    password: string;
+    syncId: string;
+    dataDir: string;
+    /** End-to-end encryption password, for encrypted budget files. */
+    encryptionPassword?: string;
+    /** Account name (case-insensitive) or id. */
+    account: string;
+    dryRun: boolean;
+};
+export type PushResult = {
+    accountName: string;
+    accountId: string;
+    added: number;
+    updated: number;
+    errors: string[];
+    dryRun: boolean;
+};
+/** Rupees to integer paise, matching Actual's own `amountToInteger`. */
+export declare function toPaise(amount: number): number;
+/**
+ * Map parsed statement rows onto Actual's import shape.
+ *
+ * Two deliberate choices:
+ *
+ * - `payee_name` gets the cleaned merchant and `imported_payee` the original
+ *   narration, which is exactly what those fields are for: the payee collapses
+ *   correctly while Actual's payee matching still sees the raw text. This is
+ *   the one thing the CSV output cannot do, since Actual's CSV field mapping
+ *   has no `imported_payee` slot.
+ * - `notes` also gets the narration, duplicating `imported_payee`. That
+ *   duplication looked redundant and was originally left out, which was wrong:
+ *   `imported_payee` is not a column you can read at a glance, whereas Notes
+ *   is one you can see, search and filter. Without it the narration is
+ *   effectively invisible after a push.
+ * - `imported_id` is only set when a reference survived the uniqueness checks.
+ *   Omitting it is the safe default: Actual falls back to matching on date and
+ *   amount within a week, whereas a non-unique id makes it treat distinct
+ *   transactions as the same one and drop them.
+ */
+export declare function toImportEntities(transactions: StatementTransaction[]): ActualImportTransaction[];
+type ActualAccount = {
+    id: string;
+    name: string;
+    closed?: boolean;
+};
+export declare function resolveAccount(accounts: ActualAccount[], wanted: string): ActualAccount;
+/**
+ * Send transactions to Actual.
+ *
+ * `@actual-app/api` is imported dynamically so the converter works without it
+ * installed, and so a missing install produces an actionable message rather
+ * than a module-resolution error at startup.
+ */
+export declare function pushTransactions(transactions: StatementTransaction[], config: PushConfig): Promise<PushResult>;
+export {};

package/dist/out/push.js

@@ -0,0 +1,103 @@
+/** Rupees to integer paise, matching Actual's own `amountToInteger`. */
+export function toPaise(amount) {
+    return Math.round(amount * 100);
+}
+/**
+ * Map parsed statement rows onto Actual's import shape.
+ *
+ * Two deliberate choices:
+ *
+ * - `payee_name` gets the cleaned merchant and `imported_payee` the original
+ *   narration, which is exactly what those fields are for: the payee collapses
+ *   correctly while Actual's payee matching still sees the raw text. This is
+ *   the one thing the CSV output cannot do, since Actual's CSV field mapping
+ *   has no `imported_payee` slot.
+ * - `notes` also gets the narration, duplicating `imported_payee`. That
+ *   duplication looked redundant and was originally left out, which was wrong:
+ *   `imported_payee` is not a column you can read at a glance, whereas Notes
+ *   is one you can see, search and filter. Without it the narration is
+ *   effectively invisible after a push.
+ * - `imported_id` is only set when a reference survived the uniqueness checks.
+ *   Omitting it is the safe default: Actual falls back to matching on date and
+ *   amount within a week, whereas a non-unique id makes it treat distinct
+ *   transactions as the same one and drop them.
+ */
+export function toImportEntities(transactions) {
+    return transactions.map(transaction => ({
+        date: transaction.date,
+        amount: toPaise(transaction.amount),
+        payee_name: transaction.payee,
+        imported_payee: transaction.raw,
+        notes: transaction.raw,
+        ...(transaction.ref ? { imported_id: transaction.ref } : {}),
+        // Statement rows have already settled at the bank.
+        cleared: true,
+    }));
+}
+export function resolveAccount(accounts, wanted) {
+    const needle = wanted.trim().toLowerCase();
+    const match = accounts.find(account => account.id === wanted) ??
+        accounts.find(account => account.name.trim().toLowerCase() === needle);
+    if (!match) {
+        const available = accounts
+            .filter(account => !account.closed)
+            .map(account => `  ${account.name}`)
+            .join('\n');
+        throw new Error(`No account matching "${wanted}". Open accounts:\n${available || '  (none)'}`);
+    }
+    return match;
+}
+/**
+ * Send transactions to Actual.
+ *
+ * `@actual-app/api` is imported dynamically so the converter works without it
+ * installed, and so a missing install produces an actionable message rather
+ * than a module-resolution error at startup.
+ */
+export async function pushTransactions(transactions, config) {
+    let api;
+    try {
+        // Non-literal specifier on purpose: it keeps TypeScript from trying to
+        // resolve an optional dependency that may not be installed.
+        const specifier = '@actual-app/api';
+        api = (await import(specifier));
+    }
+    catch {
+        throw new Error('The --push option needs the Actual API package:\n' +
+            '  npm install @actual-app/api');
+    }
+    await api.init({
+        dataDir: config.dataDir,
+        serverURL: config.serverURL,
+        password: config.password,
+    });
+    try {
+        await api.downloadBudget(config.syncId, config.encryptionPassword
+            ? { password: config.encryptionPassword }
+            : undefined);
+        const accounts = await api.getAccounts();
+        const account = resolveAccount(accounts, config.account);
+        const result = await api.importTransactions(account.id, toImportEntities(transactions), {
+            dryRun: config.dryRun,
+            defaultCleared: true,
+            // Actual title-cases imported payees by default, which lowercases
+            // first: `DMart` would become `Dmart` and `HDFC ... SIP` would become
+            // `Hdfc ... Sip`. The names here are already deliberately cased.
+            payeeNameNormalization: 'original',
+        });
+        return {
+            accountName: account.name,
+            accountId: account.id,
+            added: result.added?.length ?? 0,
+            updated: result.updated?.length ?? 0,
+            errors: (result.errors ?? []).map(error => error.message),
+            dryRun: config.dryRun,
+        };
+    }
+    finally {
+        // Always shut down: this flushes the sync and closes the budget, and
+        // leaving it open corrupts the local cache for the next run.
+        await api.shutdown();
+    }
+}
+//# sourceMappingURL=push.js.map

package/dist/out/push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.js","sourceRoot":"","sources":["../../src/out/push.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "india2actual",
+  "version": "0.1.0",
+  "description": "Convert Indian bank statements (CSV, XLS, PDF) into Actual Budget transactions with real merchant names",
+  "license": "MIT",
+  "author": "emilgeo",
+  "homepage": "https://github.com/emilgeo/india2actual#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emilgeo/india2actual.git"
+  },
+  "bugs": {
+    "url": "https://github.com/emilgeo/india2actual/issues"
+  },
+  "keywords": [
+    "actual",
+    "actual-budget",
+    "budgeting",
+    "personal-finance",
+    "india",
+    "indian-banks",
+    "upi",
+    "bank-statement",
+    "csv",
+    "pdf",
+    "importer",
+    "converter"
+  ],
+  "bin": {
+    "india2actual": "dist/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "csv-parse": "^7.0.2",
+    "csv-stringify": "^6.5.0",
+    "exceljs": "^4.4.0",
+    "fast-xml-parser": "^5.11.1",
+    "node-html-parser": "^9.0.4",
+    "pdfjs-dist": "^6.3.289"
+  },
+  "optionalDependencies": {
+    "@actual-app/api": "^26.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}