Skip to content

Client & Configuration ​

The client is constructed once with a plain options object and reused. Options are validated eagerly — anything invalid throws ZrExpressConfigError at construction.

ts
import { ZrExpressClient } from '@terminaldz/zrexpress-sdk';

const zr = new ZrExpressClient({
  apiKey: process.env.ZREXPRESS_API_KEY!,
  tenantId: process.env.ZREXPRESS_TENANT_ID!,
  timeoutMs: 30_000,
  retry: { maxRetries: 2, baseDelayMs: 300, maxDelayMs: 5_000 },
});

ZrExpressOptions ​

OptionTypeDefaultNotes
apiKeystring— (required)X-Api-Key. Stored non-enumerably; never logged/serialized.
tenantIdstring— (required)X-Tenant — must be GUID-shaped.
baseUrlstringhttps://api.zrexpress.appAPI origin (http/https).
apiVersionstring'1'Path version → /api/v1.
timeoutMsnumber30000Per-attempt timeout (AbortSignal.timeout).
retryZrRetryOptionssee belowRetry policy.
fetchtypeof fetchglobal fetchInjectable — for tests or a custom dispatcher.
loggerZrLoggersilent{ debug, info, warn, error }; never receives the key.
userAgentstring''Appended to zrexpress-sdk/<version> node/<v>.

ZrRetryOptions ​

OptionTypeDefaultNotes
maxRetriesnumber2Attempts after the first.
retryNonIdempotentbooleanfalseAlso retry non-idempotent methods. Search POSTs opt in per-operation regardless.
baseDelayMsnumber300Exponential backoff base (×2^attempt, full jitter).
maxDelayMsnumber5000Backoff cap. Must be ≥ baseDelayMs.

See the generated ZrExpressOptions for the exact type.

Retry policy ​

The transport retries only when it is safe:

  • Which errors: 429, 5xx, and network errors/timeouts.
  • Which requests: idempotent methods (GET / PUT / DELETE), plus the read-only search POSTs (marked retryable per-operation). Everything else is retried only if you set retryNonIdempotent: true.
  • Never retried: parcel creation and webhook creation — a retried create could duplicate a real shipment or endpoint.
  • Retry-After (seconds or HTTP date) is honoured when present; otherwise exponential backoff with full jitter, capped at maxDelayMs.

A per-attempt timeout that fires surfaces as ZrExpressNetworkError with timedOut: true.

Injecting fetch ​

Pass your own fetch to test without a network or to use a custom undici dispatcher:

ts
const zr = new ZrExpressClient({
  apiKey: 'test-key',
  tenantId: '11111111-1111-1111-1111-111111111111',
  fetch: async (url, init) => new Response(JSON.stringify({ items: [] }), { status: 200 }),
});

This is exactly how the SDK's own tests and the Playground's credential-free e2e run.

Redaction guarantee ​

The API key is stored on a non-enumerable field. It never appears in:

  • console.log(zr) / JSON.stringify(zr) / util.inspect(zr)
  • any error's message, serialized form, or requestId (which is only { method, path } — never headers or body)
  • anything passed to your logger

This is enforced by a dedicated redaction unit test in the SDK.

A logger ​

ts
const zr = new ZrExpressClient({
  apiKey: process.env.ZREXPRESS_API_KEY!,
  tenantId: process.env.ZREXPRESS_TENANT_ID!,
  logger: {
    debug: (m, f) => console.debug(m, f),
    info: (m, f) => console.info(m, f),
    warn: (m, f) => console.warn(m, f),
    error: (m, f) => console.error(m, f),
  },
});

Released under the MIT License. Not affiliated with ZR Express.