india2actual 0.1.0

package/.env.example

@@ -0,0 +1,23 @@
+# Real environment variables take precedence over this file, so a one-off
+# override still works:
+#
+#   ACTUAL_SYNC_ID=other-budget npx tsx src/cli.ts statement.pdf --push ...
+#
+# None of this is needed to convert a statement to CSV.
+
+# --- Encrypted statement PDFs ------------------------------------------------
+STATEMENT_PASSWORD=
+
+# --- Pushing into Actual (--push) --------------------------------------------
+# Your Actual sync server, and the password used to sign in to it
+ACTUAL_SERVER_URL=
+ACTUAL_PASSWORD=
+
+# The budget to import into: Settings > Advanced > Sync ID
+ACTUAL_SYNC_ID=
+
+# Only if this budget uses end-to-end encryption
+ACTUAL_ENCRYPTION_PASSWORD=
+
+# Where the API keeps its local copy of the budget. Defaults to ./.actual-cache
+ACTUAL_DATA_DIR=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil George
+
+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,280 @@
+# india2actual
+
+Convert Indian bank statements into [Actual Budget](https://actualbudget.org)
+transactions, with **real merchant names instead of UPI reference strings**.
+
+CSV, Excel, HTML-disguised `.xls` and PDF input all work. Every amount is
+cross-checked against the statement's own balance column.
+
+## The problem this solves
+
+Actual's CSV importer already handles Indian statements well: lakh grouping
+(`1,23,456.78`), `DD/MM/YYYY` dates and separate Withdrawal/Deposit columns all
+work, and it remembers your column mapping per account.
+
+The gap is the narration column, which embeds a unique reference in every
+transaction:
+
+```
+UPI/DR/412345678901/SWIGGY/YESB/swiggy@ybl/Payment
+UPI/DR/419876543210/SWIGGY/YESB/swiggy@ybl/Payment
+```
+
+Map that to Payee and the same merchant becomes two payees. Within months you
+have hundreds of junk payees, spending-by-payee is meaningless, and category
+learning has nothing to work with.
+
+This tool reads the structure inside the narration:
+
+```
+UPI/DR/412345678901/SWIGGY/YESB/swiggy@ybl/Payment
+       reference      name         VPA
+```
+
+and produces something importable:
+
+| Date       | Payee          | Notes                                                | Amount   |
+| ---------- | -------------- | ---------------------------------------------------- | -------- |
+| 2024-04-01 | Swiggy         | `UPI/DR/412345678901/SWIGGY/YESB/swiggy@ybl/Payment` | -450.50  |
+| 2024-04-03 | ATM Withdrawal | `ATW/1234/CASH WDL/BANGALORE`                        | -2000.00 |
+| 2024-04-04 | DMart          | `POS 1234XXXX5678 DMART BANGALORE`                   | -3250.75 |
+| 2024-04-05 | John Doe       | `UPI/412345678903/JOHN DOE/johndoe@oksbi`            | 1500.00  |
+
+The original narration is always preserved, never discarded.
+
+## Install
+
+Needs Node 22 or newer. Nothing to install: `npx` fetches it on first use.
+
+```bash
+npx india2actual statement.csv
+```
+
+Install it properly if you run it often:
+
+```bash
+npm install -g india2actual
+```
+
+## Usage
+
+```bash
+india2actual statement.csv          # writes statement.actual.csv
+india2actual statement.pdf --stdout # preview without writing
+```
+
+Then import the generated CSV through Actual's **Import transactions** dialog,
+mapping `Date`, `Payee`, `Notes` and `Amount`. Actual remembers that mapping per
+account, so you only do it once. Leave `Reference` unmapped.
+
+Or skip the CSV and [push straight into Actual](#pushing-straight-into-actual).
+
+### Supported input
+
+The format is detected by inspecting the file, not by its extension, because
+banks routinely name an HTML table `.xls`.
+
+| Actually is                         | Supported                     |
+| ----------------------------------- | ----------------------------- |
+| CSV / TSV (delimiter auto-detected) | yes                           |
+| Excel `.xlsx` (OOXML)               | yes                           |
+| HTML table named `.xls`             | yes                           |
+| Excel 2003 XML (SpreadsheetML)      | yes                           |
+| PDF, including password-protected   | yes                           |
+| Legacy binary `.xls` (OLE2)         | no, re-save as `.xlsx` or CSV |
+
+Columns are detected from the header row, using the synonyms Indian banks use
+for the same seven fields (date, narration, debit, credit, amount, balance,
+reference). Preamble and footer rows are skipped automatically.
+
+### Options
+
+| Option                       | Purpose                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------- |
+| `--out <path>`               | Where to write the CSV. Default `<input>.actual.csv`.                           |
+| `--stdout`                   | Write to stdout instead of a file.                                              |
+| `--date-order dmy\|mdy\|ymd` | Only affects all-numeric dates, where `01/02/2024` is ambiguous. Default `dmy`. |
+| `--delimiter <char>`         | Force the CSV delimiter instead of detecting it.                                |
+| `--merchants <path>`         | Your own merchant rules. See [below](#custom-merchant-rules).                   |
+| `--env-file <path>`          | Read settings from this file instead of `./.env`.                               |
+| `--push`                     | Send to Actual via its API instead of writing a CSV.                            |
+| `--account <name\|id>`       | Which Actual account to import into. Required with `--push`.                    |
+| `--dry-run`                  | With `--push`, report what would change without writing.                        |
+| `--force`                    | Write even if the balance check fails.                                          |
+| `--quiet`                    | Only report problems.                                                           |
+
+### Settings
+
+Passwords and server details come from a `.env` file in the current directory,
+never from command-line flags, which would end up in your shell history.
+
+```bash
+cp .env.example .env
+```
+
+Real environment variables take precedence over the file, so a one-off override
+works without editing it:
+
+```bash
+ACTUAL_SYNC_ID=other-budget india2actual statement.pdf --push --account Savings
+```
+
+| Setting                      | Purpose                                               |
+| ---------------------------- | ----------------------------------------------------- |
+| `STATEMENT_PASSWORD`         | Password on an encrypted statement PDF.               |
+| `ACTUAL_SERVER_URL`          | Your Actual sync server.                              |
+| `ACTUAL_PASSWORD`            | Password for that server. Not the statement password. |
+| `ACTUAL_SYNC_ID`             | Budget to import into: Settings > Advanced > Sync ID. |
+| `ACTUAL_ENCRYPTION_PASSWORD` | Only for end-to-end encrypted budgets.                |
+| `ACTUAL_DATA_DIR`            | Local budget cache. Default `./.actual-cache`.        |
+
+None of this is needed to convert a statement to CSV, unencrypted PDFs
+included.
+
+## Pushing straight into Actual
+
+```bash
+# Always preview first.
+india2actual statement.pdf --push --account "ICICI Savings" --dry-run
+# [dry run] ICICI Savings: would add 34, would update 0.
+
+india2actual statement.pdf --push --account "ICICI Savings"
+```
+
+`--dry-run` maps onto Actual's own preview mode, so nothing is written.
+
+The API path does two things the CSV path cannot:
+
+- Sets `imported_payee` to the raw narration, which is what Actual's payee
+  matching learns from, while `payee_name` gets the cleaned merchant. The CSV
+  field mapping has no `imported_payee` slot.
+- Sets `imported_id` from the bank reference, making re-imports of overlapping
+  date ranges idempotent.
+
+### Review before you push
+
+The tool reads its own output, so you can check and correct the CSV before
+anything reaches your budget:
+
+```bash
+india2actual statement.pdf
+$EDITOR statement.actual.csv
+india2actual statement.actual.csv --push --account "ICICI Savings"
+```
+
+Payees you edited are kept verbatim; converted output is passed through, not
+re-parsed. The `Reference` column survives, so deduplication still works.
+
+One caveat: the CSV has no balance column, so a run over converted output
+cannot re-verify the amounts and will say so. The check that matters already ran
+when the CSV was produced.
+
+## The balance check
+
+Almost every Indian statement carries a running balance, which makes the parse
+self-verifying: each transaction must equal the change in balance it caused. The
+tool **refuses to write a statement that does not reconcile**:
+
+```
+Balance check FAILED (4/5 rows agree).
+  1 of 5 rows do not agree with the balance column.
+  2024-04-03 "ATW/1234/CASH WDL/BANGALORE": balance moved by -2000.00 but the parsed amount is -9000.00
+Refusing to write a statement that does not reconcile. Re-run with --force to write it anyway.
+```
+
+This catches inverted debit and credit signs, dropped rows and misaligned
+columns. Both date orders are scored, so newest-first exports work too. It
+matters most for PDFs, where the table is reconstructed from the position of
+each piece of text and so is inherently less certain.
+
+## Custom merchant rules
+
+The built-in map covers common Indian merchants. Add your own in JSON:
+
+```json
+[
+  { "pattern": "^mylocalkirana", "name": "Kirana Store" },
+  { "pattern": "^acmecorp", "name": "Acme Payroll" }
+]
+```
+
+```bash
+india2actual statement.csv --merchants my-merchants.json
+```
+
+Patterns match a lowercased, punctuation-stripped form of the VPA local-part or
+merchant name, so write them without spaces or dots. Your rules take precedence
+over the built-ins.
+
+**Naming recurring mandates.** A NACH narration contains no name, only the
+collecting bank and a mandate reference, followed by a sequence number that
+changes every month. Those collections are grouped under the stable mandate
+reference, for example `NACH ICIC0000000000000001`, so name each one once:
+
+```json
+[{ "pattern": "icic0000000000000001", "name": "Home Loan EMI" }]
+```
+
+**Truncated name fields.** Some banks cut each narration field to about ten
+characters, so one counterparty can arrive as `Mr A N OTHE`, `A N OTHER` or
+`OTHER` depending on the payment route. A rule per variant collapses them.
+
+## Duplicate handling
+
+A 12-digit UPI reference (UTR or RRN) found in the narration is emitted in the
+`Reference` column, and becomes Actual's `imported_id` with `--push`.
+
+References are deliberately conservative: only exactly-12-digit values are
+accepted, and any value occurring more than once in a file is discarded. Account
+and card numbers appear in narrations at other lengths and are not unique per
+transaction, and a repeated `imported_id` makes Actual treat distinct
+transactions as the same one and drop them. Where no reference is set, Actual's
+own date and amount matching takes over.
+
+## Getting statements out of your bank
+
+Prefer internet banking over the mobile app. Bank apps often offer only PDF,
+while the web portal usually offers XLS or CSV for the same account. CSV is the
+most reliable input here and PDF the least, so use a spreadsheet if offered one.
+
+## Limitations
+
+- **PDF is the least reliable path.** Reconstructing a table from positioned
+  text can break when a bank changes its template. The balance check exists to
+  make that loud rather than silent.
+- **Line breaks inside a PDF are ambiguous.** A wrap and a deliberate break are
+  not always distinguishable, so a space can appear inside a long reference, or
+  be lost between two words. Dates, amounts, payees and the deduplication
+  reference do not depend on it.
+- **The merchant map is not authoritative.** Payment aggregators often mask the
+  real merchant. You get a consistent payee, which beats one per transaction,
+  but not always the actual shop.
+- **No automatic fetching, and there cannot be.** India's Account Aggregator
+  framework requires FIU registration and a commercial contract, so a free
+  always-on connector like Actual's European bank sync is not possible. This is
+  a converter you run on a statement you downloaded.
+
+## Contributing
+
+Adding a bank usually means adding column synonyms or narration token shapes,
+both small and contained. Narration strings are the most useful thing to
+contribute: the description column only, with names, account numbers and
+references replaced by realistic fakes.
+
+No real statement data belongs in this repository. Fixtures are synthetic.
+
+## Development
+
+```bash
+git clone https://github.com/emilgeo/india2actual.git
+cd india2actual
+npm install
+
+npm test
+npm run typecheck
+npm run dev -- statement.csv   # run the CLI from source
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import { basename, dirname, extname, join } from 'node:path';
+import { argv, cwd, exit, stderr, stdout } from 'node:process';
+import { loadEnvironmentFile, setting } from './env-file.js';
+import { describeFormat, extractTable } from './extract/index.js';
+import { interpretConvertedOutput, isConvertedOutput, } from './interpret/roundtrip.js';
+import { interpretTable } from './interpret/rows.js';
+import { validateBalances } from './interpret/validate.js';
+import { loadMerchantRules } from './merchants-file.js';
+import { toCsv, writeCsv } from './out/csv.js';
+import { pushTransactions } from './out/push.js';
+const USAGE = `
+india2actual — convert Indian bank statements for Actual Budget
+
+Usage:
+  india2actual <statement-file> [options]
+
+Options:
+  --out <path>          Where to write the normalised CSV.
+                        Default: <input>.actual.csv next to the input file.
+  --stdout              Write the CSV to stdout instead of a file.
+  --date-order <order>  dmy (default), mdy or ymd. Only affects all-numeric
+                        dates, where 01/02/2024 is genuinely ambiguous.
+  --delimiter <char>    Force the CSV delimiter instead of detecting it.
+  --merchants <path>    JSON file of { pattern, name } merchant rules, which
+                        take precedence over the built-in map.
+  --env-file <path>     Read settings from this file instead of ./.env.
+  --force               Write the CSV even if the balance check fails.
+  --quiet               Only report problems.
+  --help                Show this message.
+
+Pushing straight into Actual (instead of writing a CSV):
+  --push                Send the transactions to Actual via its API.
+  --account <name|id>   Which Actual account to import into. Required for --push.
+  --dry-run             With --push, report what would change without writing.
+
+  --push needs the API package: npm install @actual-app/api
+
+Settings come from a .env file in the current directory, or from real
+environment variables, which take precedence. Never from flags, which would
+end up in your shell history. Copy .env.example to .env to get started.
+
+    ACTUAL_SERVER_URL           e.g. https://actual.example.com
+    ACTUAL_PASSWORD             your Actual server password
+    ACTUAL_SYNC_ID              the budget's sync id (Settings > Advanced)
+    ACTUAL_ENCRYPTION_PASSWORD  only if the budget file is encrypted
+    ACTUAL_DATA_DIR             local cache dir (default: ./.actual-cache)
+    STATEMENT_PASSWORD          password for an encrypted statement PDF
+                                (not the same as ACTUAL_PASSWORD)
+
+Input is detected by content, not by extension, because banks routinely name
+HTML tables ".xls". Supported: CSV/TSV, Excel .xlsx, HTML tables, Excel 2003
+XML, and PDF (including password-protected). Legacy binary .xls must be
+re-saved as .xlsx or .csv first.
+`.trim();
+function parseArgs(args) {
+    if (!args.length || args.includes('--help') || args.includes('-h')) {
+        return null;
+    }
+    const options = {
+        input: '',
+        useStdout: false,
+        dateOrder: 'dmy',
+        force: false,
+        quiet: false,
+        push: false,
+        dryRun: false,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const next = () => {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return value;
+        };
+        switch (arg) {
+            case '--out':
+                options.out = next();
+                break;
+            case '--stdout':
+                options.useStdout = true;
+                break;
+            case '--date-order': {
+                const value = next();
+                if (value !== 'dmy' && value !== 'mdy' && value !== 'ymd') {
+                    throw new Error('--date-order must be dmy, mdy or ymd');
+                }
+                options.dateOrder = value;
+                break;
+            }
+            case '--delimiter':
+                options.delimiter = next();
+                break;
+            case '--merchants':
+                options.merchants = next();
+                break;
+            case '--env-file':
+                options.envFile = next();
+                break;
+            case '--push':
+                options.push = true;
+                break;
+            case '--account':
+                options.account = next();
+                break;
+            case '--dry-run':
+                options.dryRun = true;
+                break;
+            case '--force':
+                options.force = true;
+                break;
+            case '--quiet':
+                options.quiet = true;
+                break;
+            default:
+                if (arg === undefined || arg.startsWith('-')) {
+                    throw new Error(`Unknown option: ${arg}`);
+                }
+                if (options.input) {
+                    throw new Error('Only one input file at a time');
+                }
+                options.input = arg;
+        }
+    }
+    if (!options.input) {
+        throw new Error('No input file given');
+    }
+    if (options.push && !options.account) {
+        throw new Error('--push also needs --account <name|id>');
+    }
+    if (options.dryRun && !options.push) {
+        throw new Error('--dry-run only applies to --push');
+    }
+    return options;
+}
+function defaultOutPath(input) {
+    const extension = extname(input);
+    const name = basename(input, extension);
+    return join(dirname(input), `${name}.actual.csv`);
+}
+async function run(args) {
+    const options = parseArgs(args);
+    if (!options) {
+        stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    const log = (message) => {
+        if (!options.quiet) {
+            stderr.write(`${message}\n`);
+        }
+    };
+    // Before anything reads the environment. Both the statement password and the
+    // Actual credentials can come from here.
+    const envFile = loadEnvironmentFile(options.envFile ?? join(cwd(), '.env'));
+    if (envFile.loaded) {
+        log(`Loaded environment from ${envFile.path}`);
+    }
+    else if (options.envFile) {
+        // Explicitly asked for, so silence would be wrong.
+        throw new Error(`${options.envFile} does not exist`);
+    }
+    let merchantRules = [];
+    if (options.merchants) {
+        merchantRules = await loadMerchantRules(options.merchants);
+        log(`Loaded ${merchantRules.length} merchant rule(s) from ${options.merchants}`);
+    }
+    // Resolved before any parsing work so a missing credential or account fails
+    // immediately rather than after processing the whole statement.
+    const pushConfig = options.push ? pushConfigFromEnv(options) : null;
+    // From .env or the environment, never a flag, so it stays out of shell
+    // history.
+    const pdfPassword = setting('STATEMENT_PASSWORD');
+    const { table, format } = await extractTable(options.input, {
+        ...(options.delimiter ? { delimiter: options.delimiter } : {}),
+        ...(pdfPassword ? { password: pdfPassword } : {}),
+    });
+    log(`Read ${options.input} as ${describeFormat(format)}`);
+    // Our own output is passed through rather than re-parsed, so that payees
+    // corrected by hand in the CSV survive.
+    const converted = isConvertedOutput(table);
+    if (converted) {
+        log('Recognised this as already-converted output: payees kept as-is, ' +
+            'narrations kept in Notes.');
+    }
+    const result = converted
+        ? interpretConvertedOutput(table)
+        : interpretTable(table, {
+            dateOrder: options.dateOrder,
+            ...(merchantRules.length ? { merchantRules } : {}),
+        });
+    if (!result) {
+        stderr.write('Could not find a transaction table in this file.\n' +
+            'Expected columns resembling: Date, Narration/Particulars, ' +
+            'Withdrawal/Debit, Deposit/Credit, Balance.\n');
+        return 1;
+    }
+    const { transactions, skipped, header, droppedRefs } = result;
+    log(`Header on row ${header.index + 1}; columns: ${Object.entries(header.map)
+        .map(([role, column]) => `${role}=${column}`)
+        .join(', ')}`);
+    log(`Parsed ${transactions.length} transaction(s), skipped ${skipped.length} row(s)`);
+    if (droppedRefs) {
+        log(`Discarded ${droppedRefs} non-unique reference(s); those rows will rely ` +
+            `on Actual's date and amount matching instead.`);
+    }
+    if (!transactions.length) {
+        stderr.write('No transactions were parsed — nothing to write.\n');
+        return 1;
+    }
+    // The balance column is the only independent check we have that the parse is
+    // right, so a failure blocks the write unless explicitly overridden.
+    const validation = validateBalances(transactions);
+    if (validation.status === 'failed') {
+        stderr.write(`Balance check FAILED (${validation.matched}/${validation.checked} rows agree).\n`);
+        for (const issue of validation.issues) {
+            stderr.write(`  ${issue}\n`);
+        }
+        if (!options.force) {
+            stderr.write('Refusing to write a statement that does not reconcile. ' +
+                'Re-run with --force to write it anyway.\n');
+            return 2;
+        }
+        stderr.write('Writing anyway because --force was given.\n');
+    }
+    else if (validation.status === 'passed') {
+        log(`Balance check passed (${validation.matched}/${validation.checked} rows, ` +
+            `${validation.order} order).`);
+    }
+    else {
+        log(`Balance check skipped: ${validation.issues[0] ?? 'no balance data'}`);
+        if (converted) {
+            // Said plainly, because it is the one real cost of the round trip: the
+            // CSV carries no balance column, so these amounts are not independently
+            // verified here. They were when the CSV was produced.
+            log('Converted output carries no balance column, so this run cannot ' +
+                're-verify the amounts. Check the balance line from the run that ' +
+                'produced this CSV.');
+        }
+    }
+    if (pushConfig) {
+        const result = await pushTransactions(transactions, pushConfig);
+        const verb = result.dryRun ? 'would add' : 'added';
+        const alsoVerb = result.dryRun ? 'would update' : 'updated';
+        stderr.write(`${result.dryRun ? '[dry run] ' : ''}${result.accountName}: ` +
+            `${verb} ${result.added}, ${alsoVerb} ${result.updated}.\n`);
+        for (const error of result.errors) {
+            stderr.write(`  error: ${error}\n`);
+        }
+        return result.errors.length ? 1 : 0;
+    }
+    if (options.useStdout) {
+        stdout.write(toCsv(transactions));
+        return 0;
+    }
+    const outPath = options.out ?? defaultOutPath(options.input);
+    await writeCsv(outPath, transactions);
+    log(`Wrote ${outPath}`);
+    return 0;
+}
+/**
+ * Build the push configuration from the environment.
+ *
+ * Credentials are read from the environment rather than accepted as flags so
+ * they do not end up in shell history or process listings.
+ */
+function pushConfigFromEnv(options) {
+    if (!options.account) {
+        throw new Error('--push also needs --account <name|id>');
+    }
+    const missing = ['ACTUAL_SERVER_URL', 'ACTUAL_PASSWORD', 'ACTUAL_SYNC_ID'].filter(name => !setting(name));
+    if (missing.length) {
+        throw new Error(`--push needs these settings: ${missing.join(', ')}\n` +
+            'Set them in .env or in the environment. See --help for the full list.');
+    }
+    const encryptionPassword = setting('ACTUAL_ENCRYPTION_PASSWORD');
+    return {
+        serverURL: setting('ACTUAL_SERVER_URL'),
+        password: setting('ACTUAL_PASSWORD'),
+        syncId: setting('ACTUAL_SYNC_ID'),
+        dataDir: setting('ACTUAL_DATA_DIR') ?? join(cwd(), '.actual-cache'),
+        account: options.account,
+        dryRun: options.dryRun,
+        ...(encryptionPassword ? { encryptionPassword } : {}),
+    };
+}
+run(argv.slice(2))
+    .then(code => exit(code))
+    .catch((error) => {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/env-file.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Load a `.env` file into the environment.
+ *
+ * Uses Node's built-in loader rather than a dependency, which also fixes the
+ * precedence at the behaviour we want: variables already present in the
+ * environment are *not* overwritten. So a `.env` supplies the defaults while a
+ * one-off `ACTUAL_SYNC_ID=other india2actual ...` still wins, and CI can
+ * inject secrets without a file existing at all.
+ *
+ * Requires Node >= 22 (see `engines` in package.json).
+ */
+export type EnvFileResult = {
+    loaded: true;
+    path: string;
+} | {
+    loaded: false;
+    path: string;
+    reason: 'missing';
+};
+/**
+ * A missing file is not an error: the CSV path needs no configuration, so most
+ * runs legitimately have no `.env` at all. Anything else — unreadable, a
+ * directory, malformed contents — is reported, because it means the user
+ * believes they have configured something that is in fact being ignored. That
+ * would otherwise surface much later as a confusing "ACTUAL_SERVER_URL is not
+ * set".
+ */
+export declare function loadEnvironmentFile(path: string): EnvFileResult;
+/**
+ * Read a setting, treating blank as absent.
+ *
+ * `.env.example` ships its keys with empty values for the user to fill in, so
+ * a copied-but-unedited file leaves `ACTUAL_DATA_DIR=` set to the empty
+ * string. The empty string is not nullish, so a `??` default would not fire
+ * and the Actual API would be handed `''` as its data directory. Trimming also
+ * catches the trailing space left by `ACTUAL_SYNC_ID= ` .
+ */
+export declare function setting(name: string): string | undefined;