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
| Option | Type | Default | Notes |
|---|---|---|---|
apiKey | string | — (required) | X-Api-Key. Stored non-enumerably; never logged/serialized. |
tenantId | string | — (required) | X-Tenant — must be GUID-shaped. |
baseUrl | string | https://api.zrexpress.app | API origin (http/https). |
apiVersion | string | '1' | Path version → /api/v1. |
timeoutMs | number | 30000 | Per-attempt timeout (AbortSignal.timeout). |
retry | ZrRetryOptions | see below | Retry policy. |
fetch | typeof fetch | global fetch | Injectable — for tests or a custom dispatcher. |
logger | ZrLogger | silent | { debug, info, warn, error }; never receives the key. |
userAgent | string | '' | Appended to zrexpress-sdk/<version> node/<v>. |
ZrRetryOptions
| Option | Type | Default | Notes |
|---|---|---|---|
maxRetries | number | 2 | Attempts after the first. |
retryNonIdempotent | boolean | false | Also retry non-idempotent methods. Search POSTs opt in per-operation regardless. |
baseDelayMs | number | 300 | Exponential backoff base (×2^attempt, full jitter). |
maxDelayMs | number | 5000 | Backoff 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 searchPOSTs (marked retryable per-operation). Everything else is retried only if you setretryNonIdempotent: 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 atmaxDelayMs.
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, orrequestId(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),
},
});