@zenglobal/api-client

TypeScript client for the Zen API v1, generated from the OpenAPI specification using @hey-api/openapi-ts.

Installation

npm install @zenglobal/api-client ky

ky is a peer dependency — you must install it alongside the client.

Quick Start

import {
  configureZenClient,
  loyaltyGetCard,
  pingPing,
} from "@zenglobal/api-client";

// Configure once at startup
configureZenClient({
  baseUrl: "https://api.zenglobal.au/v1",
  username: process.env.ZEN_API_USER,
  password: process.env.ZEN_API_PASS,
  partner: {
    partnerId: "q74vzg9o",
    name: "my-pos-app",
    version: "1.0.0",
  },
});

// Call any endpoint with full type safety
const { data: ping } = await pingPing();

const { data: card } = await loyaltyGetCard({
  path: { cardNumber: "12345" },
});

Error Handling

The client provides two error classes for different failure modes:

ZenApiError — Business-Logic Errors (HTTP 200)

Zen sometimes returns HTTP 200 with a non-zero result field indicating a business-logic error. The client automatically throws these as ZenApiError:

import { ZenApiError, voucherEnquireVoucher } from "@zenglobal/api-client";

try {
  const { data } = await voucherEnquireVoucher({
    body: { voucher: { voucherNumber: "999" } },
  });
} catch (error) {
  if (error instanceof ZenApiError) {
    console.error(`Zen error ${error.code}: ${error.errorMessage}`);
    // error.issue, error.reason — optional detail fields
    // error.response — the original Response
  }
}

ZenHttpError — HTTP Errors (4xx/5xx)

When throwOnError: true is set and the server returns an HTTP error, the client throws a ZenHttpError with structured details:

import { ZenHttpError, loyaltyGetCard } from "@zenglobal/api-client";

try {
  const { data } = await loyaltyGetCard({
    path: { cardNumber: "12345" },
    throwOnError: true,
  });
} catch (error) {
  if (error instanceof ZenHttpError) {
    console.error(error.message);
    // "HTTP 400 GET https://api.zenglobal.au/v1/loyalty/card/12345: Bad Request"
    // error.status — HTTP status code
    // error.statusText — HTTP status text
    // error.body — parsed response body (JSON or text)
    // error.url — request URL
    // error.method — HTTP method
    // error.response — the original Response
  }
}

Both error classes extend Error, so instanceof Error works for catch-all handling.

Configuration Options

| Option | Type | Default | Description | | ---------- | ------------ | -------------- | ---------------------------------- | | baseUrl | string | — | Zen API base URL | | username | string | — | HTTP Basic Auth username | | password | string | — | HTTP Basic Auth password | | partner | ZenPartner | — | Partner identification (see below) | | timeout | number | 30000 | Request timeout in ms | | retry | object | { limit: 3 } | Retry configuration |

Partner Identification

Every client must specify a partner identity via the partner property. This sets the zen-client-user-agent header on all requests, allowing Zen to attribute API traffic to the correct integration partner.

| Field | Type | Description | | ----------- | -------- | -------------------------------------- | | partnerId | string | 8-character partner ID assigned by Zen | | name | string | Name of the integrating application | | version | string | Version of the integrating application |

Contact Zen Global to obtain your partner ID.

Advanced Usage

Direct Client Access

For advanced scenarios, access the underlying client directly:

import { client } from "@zenglobal/api-client";

// Add custom interceptors
client.interceptors.request.use((request, options) => {
  request.headers.set("X-Request-ID", crypto.randomUUID());
  return request;
});

Regenerating

When the OpenAPI spec changes, run the unified pipeline:

cd packages/zen-api-client
npm run pipeline

This runs all steps in order:

1. Breaking change detection — oasdiff compares current snapshot against the compiled spec
2. Changelog generation — auto-generates CHANGELOG.md entries with SemVer suggestion
3. SDK regeneration — @hey-api/openapi-ts regenerates src/client/
4. Snapshot update — copies the new spec to openapi.snapshot.yaml
5. Typecheck — tsc --noEmit
6. Tests — vitest run

If breaking changes are detected, the pipeline blocks. Use --force to allow breaking changes (bumps major version):

npm run pipeline -- --force

Individual Scripts

npm run generate            # Regenerate SDK only
npm run check:breaking      # Check for breaking API changes
npm run changelog:generate  # Generate changelog entries
npm run test                # Run tests
npm run typecheck           # TypeScript type check

oasdiff is auto-installed to .bin/ on first run if not found on PATH (macOS and Linux).

Available SDK Functions

100 typed functions covering all Zen v1 API endpoints. Functions follow camelCase naming derived from the OpenAPI operationIds:

• loyaltyGetCard, loyaltyCreateCard, loyaltySearchCards, ...
• voucherEnquireVoucher, voucherRedeemVoucher, ...
• membershipGetMember, membershipCreateMember, ...
• transactionCreateTransaction, transactionGetTransaction
• inventoryGetItem, inventorySearchInventory, ...
• orderCreateOrder, orderGetOrder, orderSearchOrders, ...
• offerList, offerCreate, offerUpdate, offerDelete
• smsSendSms, smsGetSmsBalance, ...
• pingPing, versionGetVersion, sitesGetSites
• And many more — see src/client/sdk.gen.ts for the full list.