SDK · Node / TypeScript

`ocrqueen` — Node / TypeScript

Typed client for Node 18+. Zero runtime dependencies — uses the built-in fetch and FormData. Dual ESM / CJS build with .d.ts shipped.

Install

bash

npm install ocrqueen
# or
pnpm add ocrqueen
# or
yarn add ocrqueen

Quickstart

typescript

import { OCRQueen } from "ocrqueen";
import fs from "node:fs";

const client = new OCRQueen({ apiKey: "pk_test_xxx" });

const job = await client.extract.create({
  file: fs.readFileSync("invoice.pdf"),
});
const final = await client.jobs.wait(job);

console.log(final.markdown);
for (const page of (final.document?.pages ?? []) as Array<Record<string, any>>) {
  for (const block of page.blocks ?? []) {
    console.log(block.type, block.text ?? "");
  }
}

That's the whole loop. extract.create() uploads and returns a job; jobs.wait() polls with exponential backoff until the job reaches a terminal status. Small documents finish in under a second.

Environment variables

bash

export OCRQUEEN_API_KEY=pk_live_xxx
# optional — for staging / self-hosted
export OCRQUEEN_BASE_URL=https://api.ocrqueen.com

With those set you can drop the apiKey argument: new OCRQueen() reads from the environment.

Idempotent retries

typescript

const job = await client.extract.create({
  file: fs.readFileSync("invoice.pdf"),
  idempotencyKey: "invoice-3034-2026-05-14",
});

See the idempotency reference for the contract.

Inputs

client.extract.create() accepts a path string, a Uint8Array / Buffer, or a Blob:

typescript

// 1. Filesystem path (Node only)
await client.extract.create({ file: "./invoice.pdf" });

// 2. Buffer / Uint8Array (works in serverless / edge)
await client.extract.create({
  file: buffer,
  filename: "invoice.pdf",     // optional — used for MIME inference
});

// 3. Blob — set the type so the server accepts it
await client.extract.create({
  file: new Blob([bytes], { type: "application/pdf" }),
  filename: "invoice.pdf",
});

Fire-and-forget with webhooks

typescript

const job = await client.extract.create({
  file: fs.readFileSync("invoice.pdf"),
  options: { callback_url: "https://your-server.com/hooks/ocrqueen" },
});
console.log(job.id);  // save this so the webhook handler can correlate

See the batch + webhooks cookbook for a complete receiver with HMAC verification.

Error handling

typescript

import {
  RateLimitError,
  BadRequestError,
  APIError,
} from "ocrqueen";

try {
  const job = await client.extract.create({ file: "./doc.pdf" });
  const final = await client.jobs.wait(job);
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep(5_000);
    // retry
  } else if (err instanceof BadRequestError) {
    throw err; // bad input — don't retry
  } else if (err instanceof APIError) {
    console.error("extraction failed:", err.errorCode);
  }
}

Full reference

Every method, option, and exception type is documented in the package README:

github.com/ocrqueen/ocrqueen-node →