> For the complete documentation index, see [llms.txt](https://docs.mindee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mindee.com/v1/integration/nodejs-sdk/nodejs-getting-started.md).

# Getting Started

This guide will help you get the most out of the Mindee Node.js client library to easily extract data from your documents.

{% hint style="success" %}
The library is written in TypeScript for your coding pleasure and is officially supported on all current LTS versions of Node.js.

All examples shown in this guide should work in both TypeScript and JavaScript.
{% endhint %}

## Installation

### Prerequisites

You'll need [npm and Node.js](https://nodejs.dev/download/package-manager/).

**Note**: When installing a Node.js instance, [nvm](https://github.com/nvm-sh/nvm) will also install a compatible npm version.

### Standard Installation

The easiest way to install the Mindee client library for your project is by using npm:

```shell
npm install mindee
```

### Development Installation

If you'll be modifying the source code, you'll need to follow these steps to get started.

1. First clone the repo.

```shell
git clone git@github.com:mindee/mindee-api-nodejs.git
```

2. Navigate to the cloned directory and install all required libraries.

```shell
cd mindee-api-node.js
npm install 
```

## Updating the Library

It is important to always check the version of the Mindee client library you are using, as new and updated features won’t work on older versions.

To get the latest version:

```shell
npm update mindee
```

To install a specific version of Mindee:

```shell
npm install mindee@<version>
```

## Usage

Using Mindee's APIs can be broken down into the following steps:

1. [Import the required classes](#importing-requirements) in your program
2. [Initialize a `Client`](#initializing-the-client)
3. [Load a file](#loading-a-document-file)
4. [Send the file](#sending-a-document) to Mindee's API
5. [Retrieve the response](#retrieving-the-response)
6. [Process the response](#processing-the-response) in some way

Let's take a deep dive into how this works.

### Importing Requirements

In most cases, you'll just need to `require` the `mindee` module:

```js
const mindee = require("mindee");
```

If you're building your own module, or using TypeScript, the equivalent would be:

```ts
import * as mindee from "mindee";
```

### Initializing the Client

The `Client` centralizes document configurations in a single object.

The `Client` requires your [API key](/v1/get-started/make-your-first-request.md#create-an-api-key).

You can either pass these directly to the constructor or through environment variables.

#### Pass the API key directly

```ts
// Init a new client and passing the key directly
const mindeeClient = new mindee.v1.Client({apiKey: "my-api-key"});
```

#### Set the API key in the environment

API keys should be set as environment variables, especially for any production deployment.

The following environment variable will set the global API key:

```shell
MINDEE_API_KEY="my-api-key"
```

Then in your code:

```ts
// Init a new client without an API key
const mindeeClient = new mindee.v1.Client();
```

## Loading a Document File

Before being able to send a document to the API, it must first be loaded.

You don't need to worry about different MIME types, the library will take care of handling\
all supported types automatically.

Once a document is loaded, interacting with it is done in exactly the same way, regardless\
of how it was loaded.

There are a few different ways of loading a document file, depending on your use case:

* [Path](#path)
* [File Object](#stream-object)
* [Base64](#base64)
* [URL](#url)

### Path

Load from a file directly from disk. Requires an absolute path, as a string.

```ts
const filePath = "/path/to/the/file.ext";
const inputSource = new mindee.PathInput({ inputPath: filePath });
```

### Stream Object

Load a standard readable stream object, for example as returned by the `fs.createReadStream()` function.

**Note**: The original filename is required when calling the method.

```ts
const stream = fs.createReadStream("/path/to/the/file.ext");
const inputSource = new mindee.StreamInput({
  inputStream: stream,
  filename: "file.ext",
});
```

### Base64

Load file contents from a base64-encoded string.

**Note**: The original filename is required when calling the method.

```ts
const b64String = "iVBORw0KGgoAAAANSUhEUgAAABgAAA ...";
const inputSource = new mindee.Base64Input({
  inputString: b64String,
  filename: "base64_file.txt",
});
```

### URL

Specify a URL to send to the Mindee API.

**Note**: The URL will not be downloaded locally, so checks (i.e. MIME type) and transformations (i.e. remove pages from a PDF) will not be possible.

```ts
const inputSource = new mindee.UrlInput({
  url: "https://example.com/file.ext"
});
```

## Sending a Document

To send a file to the API, we need to specify how to process the document.\
This will determine which API endpoint is used and how the API return will be handled internally by the library.

More specifically, we need to set a `Product` class as the first parameter of the `parse` method.

This is because the `parse` method is [generic](https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-classes), and its return type depends on its first argument.

Each document type available in the library has its corresponding class, which inherit from the base `Document` class.\
This is detailed in each document-specific guide.

### Off-the-Shelf Documents

Simply setting the correct class and passing the document is enough:

```ts
const respPromise = mindeeClient.parse(mindee.InvoiceV4, inputSource);
```

### Custom Documents (docTI)

The endpoint to use must also be set in third argument of the `enqueueAndParse` method. This argument is an object:

```ts
const customEndpoint = mindeeClient.createEndpoint(
  "my-endpoint",
  "my-account",
  // "my-version" // Optional: set the version, defaults to "1"
);
const respPromise = mindeeClient.enqueueAndParse(
  mindee.GeneratedV1,
  inputSource,
  {
    endpoint: customEndpoint
  }
);
```

This is because the `GeneratedV1` class is enough to handle the return processing, but the actual endpoint needs to be specified.

## Retrieving the Response

The return of the `parse` method is a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `Response` object.

More technically, the return object is instantiated depending on the specific `Document` class passed as the first argument to `parse`.

Handling the return is done like any other Promise:

```ts
respPromise.then((resp) => {
  console.log(resp.document);
});
```

Some other styles:

<pre class="language-ts"><code class="lang-ts">// One-liner
mindeeClient.parse(mindee.v1.product.InvoiceV4, inputSource).then((resp) => {
  console.log(resp.document);
});

// Async function
async function parseInvoice() {
  const filePath = "/path/to/the/file.ext";
<strong>  const inputSource = new mindee.PathInput({ inputPath: filePath });
</strong>  const response = await mindeeClient.parse(
    mindee.v1.product.InvoiceV4, inputSource
  );
}
</code></pre>

## Processing the Response

The `Response` objects all have the following attributes:

* `document` — [Document level prediction](#document-level-prediction)
* `pages` — [Page level prediction](#page-level-prediction)

### Document Level Prediction

The `document` attribute is an object specific to the type of document being processed.\
It is an instance of the `Document` class, to which a generic type is given.

It contains the data extracted from the entire document, all pages combined.\
It's possible to have the same field in various pages, but at the document level only the highest confidence field data will be shown (this is all done automatically at the API level).

```ts
// print a summary of the document-level info
 console.log(resp.document.toString());
// or
console.log(`${resp.document}`);
```

A `document`'s fields (attributes) can be accessed through it's `prediction` attribute, which have types that can vary from one product to another.\
These attributes are detailed in each product's respective guide.

### Page Level Prediction

The `pages` attribute is an array of `Page` objects. `Page` is a wrapper around elements that extend the [`Document` class](#Document-level-prediction).\
The `prediction` of a `Page` inherits from the product's own `Document`, and adds all page-specific fields to it.

The order of the elements in the array matches the order of the pages in the document.

All response objects have a `pages` property, regardless of the number of pages.\
Single-page documents will have a single entry.

Iteration over `pages` is done like with any JavaScript array, for example:

```ts
resp.pages.forEach((page) => {
  // as object, complete
  console.log(page.toString());

  // as string, summary
  console.log(`${page}`);
});
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mindee.com/v1/integration/nodejs-sdk/nodejs-getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.