Getting Started
@terminaldz/zrexpress-sdk is a thin, faithful, fully-typed TypeScript client for the ZR Express Suppliers API (https://api.zrexpress.app, prefix /api/v1). It covers all 117 operations, runs on Node ≥ 20, ships ESM + CJS, and has a single runtime dependency (svix).
Prerequisites
- Node.js ≥ 20 (the SDK uses the native
fetchandAbortSignal.timeout). - A ZR Express API key and tenant id from the portal (API Rest → Token API).
Install
The package is published on the public npm registry as @terminaldz/zrexpress-sdk. Install it with your package manager:
pnpm add @terminaldz/zrexpress-sdknpm install @terminaldz/zrexpress-sdkyarn add @terminaldz/zrexpress-sdkNestJS (@nestjs/common / @nestjs/core, >=10 <12) is an optional peer — only required if you use the /nestjs subpath.
Configure the environment
The SDK never reads the environment itself — you pass options in — but the conventional variable names are:
| Variable | Purpose |
|---|---|
ZREXPRESS_API_KEY | API key (X-Api-Key) — required |
ZREXPRESS_TENANT_ID | tenant GUID (X-Tenant) — required |
ZREXPRESS_BASE_URL | override the API origin (optional) |
Never commit secrets
Keep credentials in a gitignored .env. The API key is a bearer secret — anyone with it can act as your account. Never hard-code it, log it, or commit it. The SDK stores the key non-enumerably and is proven never to leak it.
Your first call
import { ZrExpressClient } from '@terminaldz/zrexpress-sdk';
const zr = new ZrExpressClient({
apiKey: process.env.ZREXPRESS_API_KEY!,
tenantId: process.env.ZREXPRESS_TENANT_ID!,
// baseUrl defaults to https://api.zrexpress.app
});
// getProfile is tenant-exempt — it sends no X-Tenant header.
const profile = await zr.users.getProfile();
console.log(profile.email, profile.memberships?.length);Invalid options throw ZrExpressConfigError at construction (empty apiKey, non-GUID tenantId, bad numbers/URL), so misconfiguration fails fast.
A filtered search
Every */search method uses the shared filter DSL and returns a PagedList<T>:
const wilayas = await zr.territories.search({
pageSize: 100,
advancedFilter: { field: 'level', operator: 'eq', value: 'wilaya' },
});
console.log(wilayas.totalCount, wilayas.items[0]?.nameArabic);Where to next
- Core Concepts — tenants, headers, workflows, SAS URLs.
- Client & Configuration — every option, retries, redaction.
- Parcels — create/search/track/transition with the verified shapes.
- API Quirks & Compatibility — the live behaviours that will otherwise cost you a
400/403/500. Read this before your first write. - Playground Demo — a full app exercising the SDK end to end.