Client Options

Create a Talonic instance by passing a configuration object to the constructor. The only required field is apiKey; all other options have sensible defaults. The client validates the key format on construction and throws a TypeError if it is missing or empty.

import { Talonic } from '@talonic/node'

const talonic = new Talonic({
  apiKey: process.env.TALONIC_API_KEY!,
  baseUrl: 'https://api.talonic.com',   // default
  timeout: 60_000,                       // ms; default 60s
  maxRetries: 3,                         // 429, 500, 502, 503, 504, network, timeout
  fetch: customFetch,                    // optional override (e.g. for testing)
})

The TalonicConfig interface defines the constructor shape. The apiKey field is the only required parameter and must be a non-empty string. The constructor does not validate the tlnc_ prefix or make any network calls; it only checks that the key is present and that a fetch implementation is available. Authentication failures surface on the first API call as a TalonicAuthError with status 401 (invalid key) or 403 (insufficient permissions).

The fetch option lets you inject a custom implementation for testing or proxying. In production on Node.js 18+, the SDK uses the built-in globalThis.fetch automatically. If no fetch implementation is available (Node < 18 without a polyfill), the constructor throws a TypeError with a clear message.

import { Talonic } from '@talonic/node'

// Inject a custom fetch for testing
const mockFetch = async (url: string, init?: RequestInit) => {
  console.log(`Request: ${init?.method} ${url}`)
  return new Response(JSON.stringify({ balance_credits: 1000, tier: 'free' }), {
    status: 200,
    headers: { 'content-type': 'application/json' },
  })
}

const talonic = new Talonic({
  apiKey: 'tlnc_test_key',
  fetch: mockFetch as typeof fetch,
})

const balance = await talonic.credits.getBalance()
console.log(balance.balance_credits) // 1000

Adjust timeout for long-running extractions on large documents; the default of 60 seconds covers most cases. For multi-page PDFs or image-heavy documents, consider increasing to 120 seconds or more. Set maxRetries to 0 to disable automatic retries entirely, which is useful during development when you want to see errors immediately. In production, the default of 3 retries with exponential backoff handles most transient failures without any manual intervention.

// Production: higher timeout for large documents, default retries
const talonic = new Talonic({
  apiKey: process.env.TALONIC_API_KEY!,
  timeout: 120_000, // 2 minutes for large documents
  maxRetries: 3,    // default — retries 429, 5xx, network, timeout
})

// Development: fast feedback, no retries
const devClient = new Talonic({
  apiKey: process.env.TALONIC_API_KEY!,
  timeout: 30_000,
  maxRetries: 0, // fail immediately on errors
})

The baseUrl option defaults to https://api.talonic.com and is useful for pointing at staging environments or local proxies during development. Trailing slashes are stripped automatically. Every HTTP request sent by the SDK includes an Authorization: Bearer <apiKey> header, a User-Agent: talonic-node/<version> header, and Accept: application/json. For non-FormData bodies, Content-Type: application/json is set automatically. You can override headers on individual requests through the transport layer, but the constructor-level options cover all common configuration needs.