npm package: @invoicedataextraction/sdk
Description: Official JavaScript SDK for Invoice Data Extraction.
Author: Invoice Data Extraction
Latest version: 0.1.0

# @invoicedataextraction/sdk

Official Node.js SDK for [Invoice Data Extraction](https://invoicedataextraction.com). Handles file upload, extraction submission, polling, and result download so you can go from local files to structured output in a few lines of code.

- Node.js 18 or later
- ESM only

## Install

```bash
npm install @invoicedataextraction/sdk
```

This package is ESM only. Your project's `package.json` must include `"type": "module"` (or use `.mjs` file extensions). TypeScript declarations are included.

## Quick Start

```js
import InvoiceDataExtraction from "@invoicedataextraction/sdk";

const client = new InvoiceDataExtraction({
  api_key: process.env.INVOICE_DATA_EXTRACTION_API_KEY,
});

const result = await client.extract({
  folder_path: "./invoices",
  prompt: "Extract invoice number and total",
  output_structure: "per_invoice",
  download: {
    formats: ["xlsx", "json"],
    output_path: "./output",
  },
  console_output: true, // remove to disable console logging
});
```

`extract(...)` uploads every file in the folder, submits the extraction, polls until it finishes, and downloads the results.

Generate an API key from your [dashboard](https://invoicedataextraction.com/dashboard?view=API). Every account includes 50 free pages per month. Additional credits can be purchase on a pay-as-you-go basis with no subscription needed.

## Staged Workflow

If you need control over individual steps — for example, uploading files in one part of your system and extracting in another — use the lower-level methods:

```js
const upload = await client.uploadFiles({
  files: ["./invoice1.pdf", "./invoice2.pdf"],
});

const submitted = await client.submitExtraction({
  upload_session_id: upload.upload_session_id,
  file_ids: upload.file_ids,
  prompt: "Extract invoice number and total",
  output_structure: "per_invoice",
});

const result = await client.waitForExtractionToFinish({
  extraction_id: submitted.extraction_id,
});

await client.downloadOutput({
  extraction_id: submitted.extraction_id,
  format: "xlsx",
  file_path: "./output/invoices.xlsx",
});
```

## Error Handling

SDK methods reject with a normal JavaScript `Error`. The structured error body is on `error.body`:

```js
try {
  await client.extract({ /* ... */ });
} catch (error) {
  console.log(error.body.error.code);    // e.g. "INVALID_INPUT"
  console.log(error.body.error.message); // Human-readable message
  console.log(error.body.error.retryable);
}
```

When an extraction task itself fails (e.g. insufficient credits), `extract(...)` returns the failed response rather than throwing — check `result.status` for `"completed"` or `"failed"`.

## Documentation

- [Node SDK docs](https://invoicedataextraction.com/sdk/node) — full method reference, parameters, return shapes, and examples
- [REST API docs](https://invoicedataextraction.com/api) — endpoint-level documentation for direct HTTP integration
- [Dashboard](https://invoicedataextraction.com/dashboard?view=API) — manage API keys and view extraction results

## License

MIT