EROAD REST API

Typed, ESM-first JavaScript/TypeScript client for the EROAD REST API. The SDK is generated straight from the public Swagger definitions and supports both the New Zealand (APAC) and USA (North America) platforms.

• ✅ Full type coverage for requests, responses, and errors
• ✅ Region-aware base URL selection (nz or us)
• ✅ Async API key/header injection
• ✅ Tree-shakeable ESM output with automatic CommonJS fallback

ℹ️ Node.js 18+ (or any runtime that provides fetch) is required.

Installation

npm install eroad-sdk

Quick start

import { createEroadSdk } from 'eroad-sdk';

const sdk = createEroadSdk({
  country: 'us',
  apiKey: () => process.env.EROAD_API_KEY ?? '',
});

const drivers = await sdk.services.DriverService.getDrivers({ limit: 10 });
console.log(drivers);

Selecting a country

| Country | country value | Base URL | |---------|-----------------|-------------------------------------------| | USA | "us" | https://api.na.eroad.com/v1 | | NZ/APAC | "nz" | https://api.apac.eroad.com/v1 |

Pass baseUrl if you need to point at a non-production environment.

Configuration options

createEroadSdk({
  country: 'us',
  apiKey: async () => mySecretStore.get('eroad-api-key'),
  baseUrl: 'https://sandbox-api.na.eroad.com/v1',
  defaultHeaders: { 'X-Correlation-Id': 'demo' },
  withCredentials: false,
  credentials: 'include',
});

• apiKey (required) – string or async function returning the ApiKey header value.
• baseUrl – override the default endpoint for the chosen region.
• defaultHeaders – string map or async function returning headers added to every request.
• withCredentials / credentials – forwarded to fetch for browser scenarios.

createEroadSdk returns an object exposing region-scoped service classes via sdk.services. Each service mirrors the Swagger definition generated by openapi-typescript-codegen, so you can rely on the public API documentation when supplying arguments.

Working with types

All generated models, enums, and helpers remain available for type imports:

import type { NewZealandApi } from 'eroad-sdk';

type Driver = NewZealandApi.Driver;

New Zealand and USA exports are namespaced as NewZealandApi and UsaApi respectively.

Development

The SDK is generated from the SwaggerHub definitions shipped with this repository beneath openapi/.

# Regenerate clients (NZ + USA) and apply post-processing patches
npm run generate

# Build ESM + CommonJS bundles with type definitions
npm run build

Generation steps:

1. Download updated specs into openapi/ (links below).
2. Run npm run generate to emit the TypeScript clients under src/generated.
3. scripts/post-generate.js fixes the small boolean default mismatch present in the upstream Swagger definitions.
4. Build or publish as needed.

Swagger references

• New Zealand (APAC): https://app.swaggerhub.com/apis/EROAD/eroad-apac-api/1.6.8
• USA (North America): https://app.swaggerhub.com/apis/EROAD/eroad-na-api/1.6.8

License / Author

MIT © Vadim Goncharov