# Node.js and TypeScript

Run the local Python engine from Node.js, integrate typed results and handle refusals separately from execution errors.

Source: https://openbooks.lumeo.co.in/docs/node

Use these packages in a Node.js process with Python 3.11+ and `openbooks` installed. The wrapper starts a child process on the same machine, checks schema compatibility, and validates the result. Keep calls in your application server or job runner.

## Set up your first run [#set-up-your-first-run]

1. Follow the [Node.js installation steps](/docs/installation) to install the wrapper and Python engine.
2. Run `python -m openbooks engine-info` in the same project environment. If the Node.js process uses a different environment, set `OPENBOOKS_PYTHON` to the absolute path of the interpreter that reported the engine.
3. Work through the [Node.js quickstart](/docs/quickstart) with the sample before adding multiple files.

## Process a batch [#process-a-batch]

This example uses two CSV files with the same verified opening amount, currency, and date order. Save it as an `.mjs` file to run it with Node.js, or use it in a TypeScript project.

~~~ts
import { EngineError, isReleased, runFiles } from "@lumeo_hq/openbooks-core";

try {
  const results = await runFiles(["january.csv", "february.csv"], {
    currency: "INR",
    dateOrder: "dmy",
    opening: "1000.00",
    runTimeoutMs: 120_000,
  });
  for (const result of results) {
    if (isReleased(result)) {
      console.log(result.file, result.document.data.transactions.length);
    } else {
      console.warn(result.file, result.code, result.message);
    }
  }
} catch (error) {
  if (!(error instanceof EngineError)) throw error;
  console.error(error.kind, error.message, error.hint);
  process.exitCode = 1;
}
~~~

Batch options apply to every file in the call. Results arrive as an array in input order, with one result per input when the batch completes. Use `runFile()` for individual settings, or use the job stream below for many files with different options.

## Stream jobs with per-file options [#stream-jobs-with-per-file-options]

The core package and format wrappers expose `runJobs()` from version 0.2.1. Pass an iterable or async iterable of jobs and handle each result as it arrives in input order. This lets you persist or review each result without holding an entire completed batch in memory. Runtime settings such as the interpreter, layout allowlist, and response limits apply across the stream.

Install `@lumeo_hq/openbooks-statements` for this example. Shared options set the currency and date order. Each job supplies its own opening balance.

~~~ts
import { runJobs } from "@lumeo_hq/openbooks-statements";

for await (const result of runJobs([
  { file: "jan.csv", options: { opening: "1000.00" } },
  { file: "feb.csv", options: { opening: "1590.12" } },
], { currency: "INR", dateOrder: "dmy", maxDocumentBytes: 64 * 1024 * 1024 })) {
  console.log(result.file, result.kind);
}
~~~

## RunOptions [#runoptions]

| Options | Behavior |
| --- | --- |
| `currency`, `opening`, `account` | Context for the parser. Pass `opening` as a plain decimal string. |
| `dateOrder`, `allowDerivedOpening` | Set numeric date order or permit a derived opening where supported. |
| `ocr`, `model` | Enabled by default for document processing. Set `model: false` for text-layer PDF use with the base engine. |
| `python` | Overrides the interpreter path. Otherwise discovery checks `OPENBOOKS_PYTHON`, a project `.venv`, then supported system Python candidates. |
| `runTimeoutMs`, `signal`, `maxOutputBytes` | Bound runtime and process output and support cancellation. The run timeout defaults to 120,000 ms. |
| `maxDocumentBytes` | Bounds the size of a serialized proof document separately from subprocess logs. Defaults to 64 MiB. |
| `accept` | Layout ID allowlist. A withheld release is returned as `UNKNOWN_LAYOUT` with `restricted: true`. |

## Pick the wrapper [#pick-the-wrapper]

| Package | Exports and scope |
| --- | --- |
| `@lumeo_hq/openbooks-core` | `runFile`, `runFiles`, `isReleased`, `findEngine`, validation helpers and contract types. Supports the engine's installed layouts. |
| `@lumeo_hq/openbooks-statements` | The runner and `LAYOUTS` for bank CSV, OFX/QFX, MT940 and bank statement PDFs/scans. |
| `@lumeo_hq/openbooks-gateways` | The runner and `LAYOUTS` for Stripe, Razorpay, PayPal and Wise. |
| `@lumeo_hq/openbooks-tax` | The runner and `LAYOUTS` for Form 26AS, AIS, FIRA, Form 1099-B and trial balance. |
| `@lumeo_hq/openbooks-doctor` | `runDoctor(options)` returns checks, summary counts and `ok`. Set `deep: true` to load the model. |
| `@lumeo_hq/openbooks` | CLI, engine installer and programmatic `main` and `installEngine` entry points. |

## Handle results and errors [#handle-results-and-errors]

| What you receive | How to handle it |
| --- | --- |
| Result with `kind: "released"` | Use `isReleased()` to narrow the TypeScript type, then read `result.document` for records and proof. |
| Result with `kind: "refused"` | Use `code` and `message` for review. `restricted` indicates an allowlist decision and `internal` flags an unexpected engine problem. Keep the refusal document when present. |
| Thrown `EngineError` | Use `kind` and `hint` to decide whether to retry or repair the environment. Examples include `engine_not_installed`, `engine_version`, `timeout`, `aborted`, and `bad_output`. |

See [refusal handling](/docs/refusals) for source-file problems and [troubleshooting](/docs/troubleshooting) for engine discovery, version, and runtime errors.
