Skip to Content
Open Books for developers

Node.js and TypeScript

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

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

  1. Follow the Node.js installation steps 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 with the sample before adding multiple files.

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.

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

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.

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

OptionsBehavior
currency, opening, accountContext for the parser. Pass opening as a plain decimal string.
dateOrder, allowDerivedOpeningSet numeric date order or permit a derived opening where supported.
ocr, modelEnabled by default for document processing. Set model: false for text-layer PDF use with the base engine.
pythonOverrides the interpreter path. Otherwise discovery checks OPENBOOKS_PYTHON, a project .venv, then supported system Python candidates.
runTimeoutMs, signal, maxOutputBytesBound runtime and process output and support cancellation. The run timeout defaults to 120,000 ms.
maxDocumentBytesBounds the size of a serialized proof document separately from subprocess logs. Defaults to 64 MiB.
acceptLayout ID allowlist. A withheld release is returned as UNKNOWN_LAYOUT with restricted: true.

Pick the wrapper

PackageExports and scope
@lumeo_hq/openbooks-corerunFile, runFiles, isReleased, findEngine, validation helpers and contract types. Supports the engine's installed layouts.
@lumeo_hq/openbooks-statementsThe runner and LAYOUTS for bank CSV, OFX/QFX, MT940 and bank statement PDFs/scans.
@lumeo_hq/openbooks-gatewaysThe runner and LAYOUTS for Stripe, Razorpay, PayPal and Wise.
@lumeo_hq/openbooks-taxThe runner and LAYOUTS for Form 26AS, AIS, FIRA, Form 1099-B and trial balance.
@lumeo_hq/openbooks-doctorrunDoctor(options) returns checks, summary counts and ok. Set deep: true to load the model.
@lumeo_hq/openbooksCLI, engine installer and programmatic main and installEngine entry points.

Handle results and errors

What you receiveHow 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 EngineErrorUse 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 for source-file problems and troubleshooting for engine discovery, version, and runtime errors.

View this page as Markdown