npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@arina-ai/arina-grid-di

v0.3.0

Published

TypeScript SDK for the Arina Document Intelligence API: schema-driven extraction with spatial citations, layout parsing, and reusable extractors.

Readme

Arina Document Intelligence API

This library provides convenient access to the Arina Document Intelligence API from TypeScript or JavaScript.

The full API of this library can be found in api.md.

Contents

Installation

npm install @arina-ai/arina-grid-di

Authentication

Every request carries one credential: an API key, sent as the X-API-Key header. The key is the tenant. It names your organisation and what it may do, so no request names an organisation: there is no organizationId to pass anywhere.

Get your key

Sign in to the GRID portal, open API keys and create one. The secret is shown once; keep it in a secret manager or the ARINA_GRID_API_KEY environment variable, never in source control. Keys look like grid_<12 hex>_<64 hex>.

A key carries scopes, one per group of operations:

| Scope | Allows | | --- | --- | | extract | client.extraction.* | | parse | client.parse.* | | extractors:read | client.extractors.list / retrieve and client.extractors.versions.* | | extractors:write | client.extractors.create / update / delete |

client.account.whoAmI() needs no scope.

Check your key

import ArinaDocumentIntelligenceAPI from '@arina-ai/arina-grid-di';

const client = new ArinaDocumentIntelligenceAPI({ apiKey: '<your key>', baseURL: 'https://<your base url>' });

const me = await client.account.whoAmI();
console.log(me.organization.slug, me.keyId, me.scopes);

A missing, revoked or expired key throws AuthenticationError (401). A key without a scope the operation needs throws PermissionDeniedError (403) whose body names the missing scopes; see Errors.

The client reads ARINA_GRID_API_KEY and ARINA_GRID_BASE_URL when the options are not passed. This version targets deployments that enforce API keys: Arina's hosted service, and your organisation's own deployment once it has been switched over.

Usage

You need the base URL of the service you are using (Arina-hosted, or your organisation's own deployment) and an API key for it. Both are required: the client has no default host.

import { readFile, writeFile } from 'node:fs/promises';
import ArinaDocumentIntelligenceAPI from '@arina-ai/arina-grid-di';

const client = new ArinaDocumentIntelligenceAPI({
  apiKey: '<your key>',
  baseURL: 'https://<your base url>',
});

// Runs are asynchronous: POST returns 202 with a run id, then you poll.
// `config` is the ExtractRunRequest object as a JSON string (one multipart form field).
const run = await client.extraction.createExtractRun({
  file: new File([await readFile('invoice.pdf')], 'invoice.pdf', { type: 'application/pdf' }),
  config: JSON.stringify({
    config: {
      jsonSchema: {
        type: 'object',
        properties: {
          invoiceNumber: { type: ['string', 'null'] },
          invoiceTotal: { type: ['number', 'null'], description: 'Total amount due' },
        },
      },
      citationsEnabled: true,
    },
  }),
});
console.log(run.id, run.status); // exr_..., PENDING or PROCESSING

The examples in the following sections assume a client configured as shown above.

See the API reference for every available operation.

Waiting for a run

@arina-ai/arina-grid-di/lib adds helpers that poll a run until it reaches a terminal status (PROCESSED, FAILED, CANCELLED), with backoff, a timeout and an optional AbortSignal:

import { waitForExtractRun } from '@arina-ai/arina-grid-di/lib';

const done = await waitForExtractRun(client, run.id, { timeoutMs: 120_000 });

const total = done.output?.value?.['invoiceTotal'];
// `citations` is an array when the value was located, [] when found but not located,
// and undefined/null when citations were disabled — so guard before iterating.
for (const citation of done.output?.metadata?.['invoiceTotal']?.citations ?? []) {
  console.log(citation.page?.number, citation.polygon, citation.referenceText);
}

// The page image the polygons were measured against:
const page = await client.extraction.listExtractRunPage(done.id);
await writeFile('page.jpg', Buffer.from(await page.arrayBuffer()));

waitForParseRun does the same for parse runs. A FAILED or CANCELLED run throws RunFailedError (the run is on .run); pass raiseOnFailure: false to get it back instead. Exceeding timeoutMs throws RunTimeoutError. Unknown statuses are treated as still running, because status is an open string.

Many documents at once

POST /parse_runs/batches and POST /extract_runs/batches take up to 100 documents under one config (15 MB each, 90 MB per request) and return a batch to poll instead of a hundred runs. Each document still becomes an ordinary run, listed in batch.items with its run id, so results are read from the runs as above. Batches need queued execution on the server; where it is off the endpoint answers 503.

import { readdir } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { toFile } from '@arina-ai/arina-grid-di';
import { submitExtractBatches, waitForExtractBatch } from '@arina-ai/arina-grid-di/lib';

// Any File objects (PDF, PNG, JPEG). In Node, `toFile` turns a stream or buffer into one.
const names = (await readdir('invoices')).filter((n) => n.endsWith('.pdf'));
const documents = await Promise.all(names.map((n) => toFile(createReadStream(`invoices/${n}`), n)));

// Checked against the limits before anything is uploaded and split into as many requests as
// needed; one batch comes back per request.
const batches = await submitExtractBatches(client, documents, { config: { jsonSchema: schema } });

for (const submitted of batches) {
  const batch = await waitForExtractBatch(client, submitted.id, {
    timeoutMs: 1_800_000,
    onPoll: (b) => console.log(`${b.counts?.processed} of ${b.counts?.total} done`),
  });
  for (const item of batch.items ?? []) {
    if (item.status === 'PROCESSED' && item.runId) {
      const run = await client.extraction.retrieveExtractRun(item.runId);
      console.log(item.documentName, run.output?.value);
    } else {
      console.log(item.documentName, 'failed:', item.failureReason, item.failureMessage);
    }
  }
}

A batch is COMPLETED once every document is PROCESSED or FAILED; failures are counted in batch.counts.failed and named on the items, never thrown, so a batch with two failed documents is still complete. waitForExtractBatch throws BatchTimeoutError (the batch is on .batch) if that takes longer than timeoutMs; the runs keep going server-side. planBatches(documents) is the grouping on its own. The parse twins are submitParseBatches and waitForParseBatch. To send one request yourself, call the generated methods directly: client.parse.createBatch({ files, config }) and client.parse.retrieveBatch(id) (createExtractBatch / retrieveExtractBatch for extraction). Each member run also reports its batchId.

Errors

Non-success responses throw generated API errors, all subclasses of APIError. Each carries status, headers and the parsed JSON body as error.

import { APIError, AuthenticationError, PermissionDeniedError } from '@arina-ai/arina-grid-di';

try {
  const extractor = await client.extractors.create({ name: 'Invoices', config: { jsonSchema: { type: 'object' } } });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401: the key is missing, unknown, revoked or expired. The body is a bare {"detail": "Unauthorized"}.
  } else if (err instanceof PermissionDeniedError) {
    // 403: the key lacks a scope this operation needs.
    const detail = (err.error as { detail: { code: string; message: string; missing?: string[] } }).detail;
    console.log(detail.code, detail.missing); // 'missing_scope', ['extractors:write']
  } else if (err instanceof APIError) {
    console.log(err.status, err.name, err.error);
  }
  throw err;
}

error.detail is a string for most refusals, an array of {loc, msg} objects for a request-validation failure (422), and an object {code, message, ...} where you are meant to branch on code. A resource that belongs to another organisation is a plain 404.

Documented error statuses: 400, 401, 403, 404, 409, 422, 503. A 503 (key check or run storage unavailable) carries Retry-After and is retried automatically; see below.

Client Options

Configure the generated client by setting any of these options when you create it.

import ArinaDocumentIntelligenceAPI from '@arina-ai/arina-grid-di';

const client = new ArinaDocumentIntelligenceAPI({
  timeout: 60000,
  maxRetries: 2,
  logLevel: 'debug',
});

| Option | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string \| AuthTokenProvider | process.env["ARINA_GRID_API_KEY"] | Credential for the ApiKey scheme, sent as X-API-Key. | | baseURL | string | process.env["ARINA_GRID_BASE_URL"] | Where the service is. Required: there is no default host. | | timeout | number | 60000 | Maximum time in milliseconds to wait for a response before aborting a request. | | maxRetries | number | 2 | Number of retries for temporary failures. | | defaultHeaders | HeadersInit | - | Headers sent with every request. | | defaultQuery | Record<string, string \| undefined> | - | Query parameters sent with every request. | | fetchOptions | RequestInit | - | Additional fetch options sent with every request. | | fetch | Fetch | - | Custom fetch implementation. | | logLevel | "off" \| "error" \| "warn" \| "info" \| "debug" \| null | process.env["ARINA_GRID_LOG"] | Controls request and retry debug logging. | | logger | Logger \| null | console | Custom logger implementation. |

ARINA_GRID_CUSTOM_HEADERS (newline-separated Name: value lines) adds headers to every request, like defaultHeaders; an explicit defaultHeaders wins on a clash.

Request Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | headers | HeadersInit | - | Per-request headers. | | query | Record<string, unknown> | - | Per-request query parameters. | | body | unknown | - | Override the generated request body. | | timeout | number | - | Per-request timeout in milliseconds. | | maxRetries | number | - | Per-request retry count. | | signal | AbortSignal | - | Abort an in-flight request. | | fetchOptions | RequestInit | - | Per-request fetch options. | | idempotencyKey | string | - | Idempotency key for retry-safe operations. Applies to this request and its retries. |

Retries and Timeouts

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.

Helpers

  • Use .withResponse() on any request to inspect both parsed data and the raw Response object.
  • Every operation returns an APIPromise, so you can await it directly or chain .withResponse().

Logging

  • Set logLevel: "debug" (or the ARINA_GRID_LOG environment variable) to log request URLs, options, response status, response headers, and retry attempts.
  • Pass a custom logger to route logs into your own observability pipeline.
  • Set logLevel: null to disable environment-driven logging.

Requirements

  • Node.js 20+, a modern browser, or any runtime with fetch support

Contributing

Client code under src/ (except src/lib/) is generated from the API's OpenAPI document; helpers, tests and release automation are maintained here. See CONTRIBUTING.md. Security reports: SECURITY.md.

Client generated with Scalar.