Skip to content

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 fetch and AbortSignal.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:

bash
pnpm add @terminaldz/zrexpress-sdk
bash
npm install @terminaldz/zrexpress-sdk
bash
yarn add @terminaldz/zrexpress-sdk

NestJS (@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:

VariablePurpose
ZREXPRESS_API_KEYAPI key (X-Api-Key) — required
ZREXPRESS_TENANT_IDtenant GUID (X-Tenant) — required
ZREXPRESS_BASE_URLoverride 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 ​

ts
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.

Every */search method uses the shared filter DSL and returns a PagedList<T>:

ts
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 ​

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