Installation & Setup

Install the package

# npm
npm install @ithbatiam/sdk

# yarn
yarn add @ithbatiam/sdk

# pnpm
pnpm add @ithbatiam/sdk

Requirements

• Node.js 18+ for server-side use (uses native fetch)
• TypeScript 5.0+ recommended (the package ships with bundled types)
• Any modern browser with fetch support for client-side use

Initialize the client

import { IthbatSDK } from '@ithbatiam/sdk';

const sdk = new IthbatSDK({
  basePath: 'https://api.ithbat.io/api/v1',
  tenantId: 'YOUR_TENANT_ID',
});

In most applications you create one client instance and export it as a module-level singleton.

// lib/ithbat.ts
import { IthbatSDK } from '@ithbatiam/sdk';

export const sdk = new IthbatSDK({
  basePath: process.env.ITHBAT_BASE_PATH ?? 'https://api.ithbat.io/api/v1',
  tenantId: process.env.ITHBAT_TENANT_ID,
});

Configuration options

The IthbatSDK constructor accepts the following options:

interface IthbatConfig {
  basePath: string;
  tenantId?: string;
  accessToken?: string;
  headers?: Record<string, string>;
  timeout?: number;
}

Option	Type	Default	Description
basePath	string	—	Required. Full base URL including the API version path, e.g. https://api.ithbat.io/api/v1.
tenantId	string	—	Tenant UUID. Sent as the X-Tenant-ID header on every request.
accessToken	string	—	Initial bearer token. Can also be set later with sdk.setAccessToken().
headers	Record<string, string>	—	Additional headers merged into every request.
timeout	number	30000	Request timeout in milliseconds.

Environment variables

We recommend storing your tenant ID and base path in environment variables:

# .env
ITHBAT_TENANT_ID=3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
ITHBAT_BASE_PATH=https://api.ithbat.io/api/v1

Then initialize the client:

import { IthbatSDK } from '@ithbatiam/sdk';

export const sdk = new IthbatSDK({
  basePath: process.env.ITHBAT_BASE_PATH!,
  tenantId: process.env.ITHBAT_TENANT_ID,
});

TypeScript setup

The SDK ships with full TypeScript declarations. No additional @types packages are needed.

Add the following to your tsconfig.json if it is not already present:

{
  "compilerOptions": {
    "target": "ES2020",
    "moduleResolution": "bundler",
    "strict": true
  }
}

The SDK uses moduleResolution: "bundler" exports conditions. If you are using an older setup with "moduleResolution": "node", use the CJS build:

const { IthbatSDK } = require('@ithbatiam/sdk');

Machine-to-machine authentication

For server-side admin operations, obtain a token via client credentials using sdk.authenticate(). This method calls the OAuth /token endpoint and applies the returned access token to the SDK instance automatically:

import { IthbatSDK } from '@ithbatiam/sdk';

const sdk = new IthbatSDK({
  basePath: process.env.ITHBAT_BASE_PATH!,
  tenantId: process.env.ITHBAT_TENANT_ID,
});

await sdk.authenticate(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

const users = await sdk.users.listUsers({ page: 1, limit: 25 });

warning

Never expose your client secret to the browser. Only use client credentials authentication from a server-side context such as a Node.js API route or a background worker.

Error handling

All SDK methods throw IthbatError on failure. Import it to inspect error codes:

import { IthbatSDK, IthbatError } from '@ithbatiam/sdk';

try {
  await sdk.auth.login({ email: '[email protected]', password: 'wrong' });
} catch (error) {
  if (error instanceof IthbatError) {
    console.error(error.code);       // e.g., "INVALID_CREDENTIALS"
    console.error(error.message);    // Human-readable description
    console.error(error.statusCode); // HTTP status code, e.g., 401
    console.error(error.details);    // Field-level validation details, if any
  }
}

Use the SDK's helper methods to classify errors without importing IthbatError directly:

try {
  await sdk.users.createUser({ email: 'bad-email' });
} catch (error) {
  if (sdk.isValidationError(error)) {
    const fields = sdk.getValidationErrors(error);
    fields.forEach((f) => console.error(`${f.field}: ${f.message}`));
  } else if (sdk.isAuthError(error)) {
    window.location.href = '/login';
  }
}

Common error codes:

Code	HTTP Status	Meaning
INVALID_CREDENTIALS	401	Email or password is incorrect
ACCOUNT_SUSPENDED	403	Account has been suspended by an admin
MFA_REQUIRED	200	Login succeeded but MFA challenge is required
VALIDATION_ERROR	400	Request body failed validation
NOT_FOUND	404	The requested resource does not exist
PERMISSION_DENIED	403	The caller lacks the required permission
RATE_LIMITED	429	Too many requests — back off and retry
NETWORK_ERROR	0	The request could not be sent (offline, timeout, etc.)