Node / TypeScript SDK

Official @oligon/receipts package. Works in Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers.

Install

npm install @oligon/receipts
pnpm add @oligon/receipts
yarn add @oligon/receipts

Quickstart

import { OligonReceipts } from "@oligon/receipts";
 
const client = new OligonReceipts({ apiKey: process.env.OLIGON_API_KEY });
const r = await client.extract({ file: "./receipt.jpg", type: "nfe" });
 
console.log(r.merchantName, r.total);

Configuration

Option	Default	Description
`apiKey`	`OLIGON_API_KEY` env	Required.
`baseUrl`	`https://api.receipts.oligontech.com`	Override host.
`timeout`	`30000` (ms)	Per-request timeout.
`maxRetries`	`5`	Auto-retries on 429/5xx.
`fetch`	`globalThis.fetch`	Inject your own (undici, polyfills).
`defaultHeaders`	`{}`	Merged onto every request.

Browser direct upload

import { OligonReceipts } from "@oligon/receipts";
 
const client = new OligonReceipts({
  apiKey: "pk_publishable_...", // browser-safe scope
});
 
inputEl.addEventListener("change", async () => {
  const file = inputEl.files![0];
  const r = await client.extract({ file, type: "receipt" });
  render(r);
});

Use a pk_publishable_… key for browsers. It can only upload and read its own receipts.

Pagination

for await (const r of client.receipts.list({ type: "nfe", limit: 100 })) {
  console.log(r.id);
}

Or one page at a time with client.receipts.listPage({ cursor }).

Errors

import {
  AuthError, RateLimitError, ValidationError, OligonAPIError,
} from "@oligon/receipts";
 
try {
  await client.extract({ file });
} catch (err) {
  if (err instanceof RateLimitError) await sleep(err.retryAfter ?? 1000);
  else if (err instanceof AuthError) rotateKey();
  else if (err instanceof OligonAPIError) log(err.status, err.requestId);
  else throw err;
}

Webhook verification

import { verifyWebhook } from "@oligon/receipts";
 
const ok = await verifyWebhook(rawBody, signatureHeader, secret);

Uses WebCrypto — works in Workers / Deno / browsers, no Node-only crypto dep.

Source

github.com/gogoncalves/oligon-receipts/tree/main/sdks/node (opens in a new tab)

Python Go