@suparse/sdk

@suparse/sdk

Official JavaScript and TypeScript SDK for the Suparse Document Processing API.

Suparse is an AI-powered document processing API for extracting structured data from any document type, including invoices, receipts, bank statements, purchase orders and many more.

Requirements

• Node.js 20+
• Browser, edge, or Node.js runtime with fetch, Blob, and FormData

Installation

npm install @suparse/sdk

Authentication

You'll need an API key to use the SDK. To obtain one:

• Sign in at suparse.com
• Go to the API Keys tab
• Enter a key name and click Generate New Key
• Copy the key value. It will be shown only once.

Set it as an environment variable when using the Node client:

export SUPARSE_API_KEY="your_api_key_here"

Or pass it directly to the SDK constructor:

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient({ apiKey: "your_api_key_here" });

Browser Key Safety

Do not put an unrestricted Suparse API key in browser code, public repositories, or client-side bundles. Browser users can inspect bundled JavaScript and network requests.

Use SuparseClient directly in the browser only with a key that Suparse explicitly marks as safe for public browser use, with origin, permission, and quota limits that match your application. Otherwise, keep SUPARSE_API_KEY on your server or edge runtime and have the browser call your own authenticated endpoint.

Quick Start

// Node.js SDK, with SUPARSE_API_KEY set
import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();

try {
  const result = await client.extract("invoice.pdf");

  for (const item of result.succeeded) {
    console.log(item.original_file);
    console.log(item.documents.map((doc) => doc.extracted_data));
  }
} finally {
  await client.close();
}

// Browser runtime calling your server or edge proxy
const file = new File([fileBytes], "invoice.pdf", { type: "application/pdf" });
const formData = new FormData();
formData.append("file", file);

const response = await fetch("/api/suparse/extract", {
  method: "POST",
  body: formData,
});

const result = await response.json();
console.log(result.succeeded);

SDK Usage

The SDK exports two clients:

• SuparseClient from @suparse/sdk: browser/edge-compatible client for Blob, File, and URL inputs
• SuparseNodeClient from @suparse/sdk/node: Node.js client with file paths, folder processing, and disk output helpers

Both clients handle uploads, polling, exports, retries, rate limits, and parallel batch processing. Batch extraction runs up to 10 files concurrently.

Node.js

Use @suparse/sdk/node for local files and server-side applications.

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();

try {
  const result = await client.extract(["invoice1.pdf", "invoice2.pdf"]);

  for (const item of result.succeeded) {
    console.log(item.original_file);
    console.log(item.documents.map((doc) => doc.extracted_data));
  }

  for (const failed of result.failed) {
    console.error(failed.file, failed.error);
  }
} finally {
  await client.close();
}

The Node client reads SUPARSE_API_KEY and SUPARSE_API_URL from environment variables by default, so you can use new SuparseNodeClient() if those are set. Pass apiKey and baseUrl directly when you do not want to use environment variables.

Browser and Edge

Use @suparse/sdk for runtimes without Node.js file-system APIs.

In browser applications, call your server or edge proxy by default so the Suparse API key stays outside the client bundle:

const formData = new FormData();
formData.append("file", fileInput.files![0]);

const response = await fetch("/api/suparse/extract", {
  method: "POST",
  body: formData,
});

const result = await response.json();

for (const item of result.succeeded) {
  console.log(item.documents.map((doc) => doc.extracted_data));
}

On a server or edge route, keep the API key in the runtime environment and call Suparse from there:

import { SuparseClient } from "@suparse/sdk";

const client = new SuparseClient({ apiKey: process.env.SUPARSE_API_KEY! });

export async function POST(request: Request): Promise<Response> {
  const formData = await request.formData();
  const file = formData.get("file");

  if (!(file instanceof File)) {
    return Response.json({ error: "file is required" }, { status: 400 });
  }

  const result = await client.extract(file, { split: true });
  return Response.json(result);
}

Only skip the proxy when the key is explicitly browser-restricted by Suparse for public use.

You can also pass a URL; the SDK fetches it and uploads the response body:

const result = await client.extract(new URL("https://example.com/invoice.pdf"));

Extract One or More Documents

extract() is the primary SDK API.

Node.js File Paths

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();

const result = await client.extract("invoice.pdf", {
  template_id: "276a0aa8-84bc-4491-a2e7-1ea13381790c",
  split: true,
  cleanup: true,
  onProgress: (item) => {
    if ("file" in item) {
      console.error(`Failed: ${item.file} - ${item.error}`);
    } else {
      console.log(`Done: ${item.original_file}`);
    }
  },
});

SuparseNodeClient accepts a single file path, an array of file paths, Blob/File objects, URL objects, or an array mixing those input types.

Batch Processing

const result = await client.extract(["receipts/jan.pdf", "receipts/feb.pdf"]);

for (const item of result.succeeded) {
  console.log(item.original_file, item.documents);
}

for (const failed of result.failed) {
  console.error(failed.file, failed.error);
}

console.log(`Total: ${result.total}`);

Browser Files

The same key-safety rule applies here: use this direct browser pattern only with a browser-restricted public key. Use a server or edge proxy for unrestricted API keys.

import { SuparseClient } from "@suparse/sdk";

const client = new SuparseClient({ apiKey: "browser_restricted_public_key" });
const files = Array.from(fileInput.files ?? []);

const result = await client.extract(files, {
  split: false,
  auto_approve: true,
});

SuparseClient accepts Blob, File, and URL inputs. Use SuparseNodeClient when you need local file paths or disk output helpers.

Extract a Folder

extractFolder() is available from SuparseNodeClient. It scans a directory for supported files and delegates to extract().

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();

const result = await client.extractFolder("./receipts/", {
  template_id: "276a0aa8-84bc-4491-a2e7-1ea13381790c",
  split: true,
  cleanup: true,
});

for (const item of result.succeeded) {
  console.log(item.original_file, item.documents);
}

extractFolder() scans the immediate directory only, filters to supported extensions, sorts the files by name, and returns an empty BatchResult when no supported files are found.

Result Data

Each successful item is a TaskExport. Its documents array contains the extracted document records and parsed fields:

for (const item of result.succeeded) {
  console.log(item.task_id);
  console.log(item.original_file);

  for (const document of item.documents) {
    console.log(document.document_id);
    console.log(document.template_id);
    console.log(document.page_start, document.page_end);
    console.log(document.credits_used);
    console.log(document.extracted_data);
  }
}

For single-page documents, documents usually has one entry. When split is enabled, a single uploaded PDF can produce multiple document entries with their own page ranges and template IDs.

Low-Level API

Use the low-level methods when you need direct control over upload, polling, export, and deletion.

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();

// Upload a file and get back a task ID
const taskId = await client.uploadFile("invoice.pdf", {
  template_id: "276a0aa8-84bc-4491-a2e7-1ea13381790c",
  split: false,
  auto_approve: true,
});

// Poll until processing completes
const { status, documentIds } = await client.pollTaskStatus(taskId);

// Fetch JSON results in memory
const exportsJson = await client.fetchResults(documentIds);

// Fetch a CSV/XLSX export in memory. The API may return a ZIP when
// multiple files are generated.
const xlsxExport = await client.fetchResults(documentIds, {
  format: "xlsx",
  export_type: "unified",
});
console.log(xlsxExport.filename, xlsxExport.contentType, xlsxExport.isZip);

// Export to Google Sheets. This requires a working Google integration.
const sheetsExport = await client.fetchResults(documentIds, {
  format: "google_sheets",
});
console.log(sheetsExport.spreadsheet_url ?? sheetsExport.folder_url);

// Or write results to disk. JSON remains the default format.
await client.downloadResults(documentIds, "output.json");

// For file formats, omit the output path to use the API filename,
// or pass a directory/file path explicitly.
await client.downloadResults(documentIds, "./exports", {
  format: "csv",
  export_type: "original",
});

// Delete documents by ID
await client.deleteDocuments(["550e8400-e29b-41d4-a716-446655440000"]);

// List available templates
const templates = await client.listTemplates();
for (const template of templates) {
  console.log(`${template.name} (${template.template_language})`);
}

// Include system templates too
const allTemplates = await client.listTemplates({ includeSystem: true });

Browser and edge runtimes can use uploadFromSource() instead of uploadFile(). In browser code, only pass a browser-restricted public key directly; otherwise call uploadFromSource() from your server or edge proxy.

import { SuparseClient } from "@suparse/sdk";

const client = new SuparseClient({ apiKey: "browser_restricted_public_key" });

const taskId = await client.uploadFromSource(fileInput.files![0], {
  split: true,
  auto_approve: true,
});
const { documentIds } = await client.pollTaskStatus(taskId);
const exportsJson = await client.fetchResults(documentIds);

Export Formats

JSON is the default export format for extract(), fetchResults(), downloadResults(), and processDocument() workflows. The low-level export helpers also support the formats exposed by the Suparse API:

Format	SDK result	Notes
json	TaskExport[]	Default structured extraction result
csv	FileExport with data, filename, contentType, and isZip	Saves as CSV or ZIP depending on the API response
xlsx	FileExport with data, filename, contentType, and isZip	Saves as XLSX or ZIP depending on the API response
google_sheets	GoogleSheetsExport	Returns spreadsheet or folder URLs; requires Google integration

export_type can be "unified" or "original" and defaults to "unified". It affects csv, xlsx, and google_sheets exports. JSON currently returns the same task-oriented shape for either export type.

Node Convenience Methods

SuparseNodeClient also exposes convenience methods for file-based workflows:

import { SuparseNodeClient } from "@suparse/sdk/node";

const client = new SuparseNodeClient();

// Process one document and write the JSON export to disk.
await client.processDocument("invoice.pdf", "results.json", {
  template_id: "276a0aa8-84bc-4491-a2e7-1ea13381790c",
  split: false,
  auto_approve: true,
  cleanup: true,
});

// Process one document and write an XLSX export to disk.
await client.processDocument("invoice.pdf", "./exports", {
  format: "xlsx",
  export_type: "unified",
});

// Process multiple files and receive raw task/document IDs.
const { succeeded, failed } = await client.processBatch(["a.pdf", "b.pdf"], {
  template_id: "276a0aa8-84bc-4491-a2e7-1ea13381790c",
  split: true,
});

for (const item of succeeded) {
  console.log(item.filePath, item.taskId, item.documentIds);
}

for (const item of failed) {
  console.error(item.filePath, item.taskId, item.error);
}

Error Handling

All SDK exceptions inherit from SuparseError.

import {
  SuparseNodeClient,
  SuparseError,
  SuparseAuthError,
  SuparseNetworkError,
  SuparsePollingTimeoutError,
} from "@suparse/sdk/node";

const client = new SuparseNodeClient({ apiKey: "your_api_key_here" });

try {
  const result = await client.extract("invoice.pdf");
  console.log(result.succeeded);
} catch (error) {
  if (error instanceof SuparseAuthError) {
    console.error("Invalid API key");
  } else if (error instanceof SuparseNetworkError) {
    console.error("Connection failed");
  } else if (error instanceof SuparsePollingTimeoutError) {
    console.error("Processing timed out");
  } else if (error instanceof SuparseError) {
    console.error(`Unexpected Suparse error: ${error.message}`);
  } else {
    throw error;
  }
}

For batch operations, check result.failed to handle per-file errors without catching exceptions:

const result = await client.extract(["a.pdf", "b.pdf", "c.pdf"]);

for (const item of result.succeeded) {
  console.log(`OK: ${item.original_file} -> ${item.documents.map((doc) => doc.document_id)}`);
}

for (const failed of result.failed) {
  console.error(`FAIL: ${failed.file} -> ${failed.error}`);
}

Reference

Constructor Parameters

SuparseClient requires apiKey directly. In browser code, that must be a browser-restricted public key; keep unrestricted keys on a server or edge runtime. SuparseNodeClient can read apiKey and baseUrl from environment variables.

Parameter	Type	Default	Description
apiKey	string	SUPARSE_API_KEY in SuparseNodeClient only	Your API key. Use only browser-restricted public keys in browser code
baseUrl	string	SUPARSE_API_URL env var or https://api.suparse.com/api/v1	API base URL
timeoutMs	number	60000	Request timeout in milliseconds
maxRetries	number	3	Max retry attempts for retryable network/API errors
pollInterval	number	5	Initial seconds between polling attempts
maxPollAttempts	number	300	Max polling attempts before timeout

Polling uses exponential backoff starting from pollInterval seconds and caps the delay at 15 seconds. maxPollAttempts limits the total number of poll attempts before SuparsePollingTimeoutError is thrown.

Result Objects

Object	Properties	Description
TaskExport	task_id, original_file, total_documents_extracted, documents	Successfully extracted file
DocumentExport	document_id, file_name, page_start, page_end, template_id, credits_used, extracted_data	Extracted document and parsed fields
ExtractionTemplateSummary	id, name, description, template_language, template_group_id, parent_template_id, version, team_id, is_active, is_system_template, created_at	Template summary returned by listTemplates
FileExport	format, contentType, filename, isZip, data	In-memory CSV/XLSX export bytes
GoogleSheetsExport	message, spreadsheet_id, spreadsheet_url, folder_url, spreadsheets	Google Sheets export response
FailedResult	file, error	File that failed during extraction
BatchResult	succeeded, failed, total	Container for batch results

Export Options

Option	Values	Default	Description
format	json, csv, xlsx, google_sheets	json	Export format for fetchResults, downloadResults, and processDocument
export_type	original, unified	unified	Export mode for CSV, XLSX, and Google Sheets exports

Exceptions

All exceptions inherit from SuparseError.

Exception	Raised When
SuparseError	Base exception for all SDK errors
SuparseNetworkError	Network connection fails or times out
SuparsePollingTimeoutError	Polling exceeds maxPollAttempts
SuparseProcessingError	Document fails to process on the server
SuparseAPIError	Base for HTTP error responses; has statusCode and responseBody
SuparseAuthError	401/403 authentication or authorization error
SuparseNotFoundError	404 resource not found
SuparseRateLimitError	429 too many requests
SuparseServerError	5xx server error
SuparseSDKError	SDK fails to parse or handle the expected API response

extract() Parameters

Parameter	Type	Default	Description
files	Node: string, Blob, File, URL, or array; browser/edge: Blob, File, URL, or array	required	One or more files to process
template_id	string	undefined	Template ID (auto-detect if omitted)
split	boolean	false	Auto-split multi-page documents
auto_approve	boolean	true	Set to false to require human review in the Suparse UI
cleanup	boolean	false	Delete documents from server after extraction
onProgress	(result) => void	undefined	Called with each TaskExport or FailedResult as it completes

cleanup deletes the uploaded parent task documents after results have been fetched. Deleting a parent document also deletes its child documents server-side.

extractFolder() Parameters

extractFolder() is available only in @suparse/sdk/node.

Parameter	Type	Default	Description
folder	string	required	Directory to scan
template_id	string	undefined	Template ID (auto-detect if omitted)
split	boolean	false	Auto-split multi-page documents
auto_approve	boolean	true	Set to false to require human review in the Suparse UI
cleanup	boolean	false	Delete documents from server after extraction
onProgress	(result) => void	undefined	Called with each result as it completes

Supported Files

Extension	MIME Type
.pdf	application/pdf
.jpg, .jpeg	image/jpeg
.png	image/png
.heic	image/heic
.heif	image/heif

CLI

The companion CLI is published as @suparse/cli:

npm install -g @suparse/cli
suparse process invoice.pdf -o results.json

Documentation

Full API documentation is available at suparse.com/docs.

License

MIT