Node.js SDK configuration

Configuration is explicit and server-side. The SDK does not read environment variables, global configuration, or framework helpers.

Client options

 1const bladePdf = new BladePdf({
 2  apiKey,
 3  baseUrl: 'https://api.bladepdf.com',
 4  timeoutMs: 60_000,
 5  retries: 1,
 6  retryDelayMs: 1_000,
 7  userAgent: 'invoice-service/2.0 bladepdf-node/1.0',
 8});

retries counts retries after the first attempt. Only network failures, internal request timeout before response delivery, and HTTP 429, 502, 503, and 504 are retried. Retry-After takes precedence over exponential delay. Caller abort, validation, authentication, payload, and plan-limit failures are not retried.

Custom fetch, proxy, or CA

The default transport uses Node's native fetch and platform TLS verification. The SDK does not expose an unsafe TLS-disable switch. Inject a compatible fetch implementation when your server needs a proxy, custom CA, dispatcher, tracing, or a test double.

 1const bladePdf = new BladePdf({
 2  apiKey,
 3  fetch: instrumentedFetch,
 4});

Cancellation

Pass a standard AbortSignal to render(), renderStream(), renderToFile(), or submit(). Caller cancellation keeps the standard AbortError.

 1const controller = new AbortController();
 2
 3const result = await render.render({
 4  signal: controller.signal,
 5});

Asset roots

documentRoot maps URL paths such as /images/logo.png. Ordered searchRoots resolve relative references. localHosts maps same-application HTTP URLs back to documentRoot instead of treating them as remote.

Every automatically located file is canonicalized with realpath and must remain inside an allowed root. Traversal, absolute paths outside roots, file:// escapes, and symlinks leaving a root throw AssetAccessDeniedError. No roots means no automatic filesystem reads.

Intentional file permission

assetFile() is an explicit caller grant and may attach one file outside automatic roots:

 1render.assetFile('/srv/tenants/acme/logo.svg', {
 2  target: 'tenant-logo.svg',
 3  mimeType: 'image/svg+xml',
 4});

In-memory assets

Use assetData() with a Buffer, Uint8Array, or ArrayBuffer. A target is required. Optional baseDirectory allows CSS dependencies to resolve through the configured roots.

 1render.assetData(chartBuffer, {
 2  target: 'chart.png',
 3  mimeType: 'image/png',
 4});

Dependency injection

Applications and test suites can replace the complete transport and optionally the resolver:

 1const bladePdf = BladePdf.fromDependencies({
 2  client: renderClient,
 3  assetResolver,
 4});