SDK Overview

The @kraiter/sdk package gives you a typed, Promise-based interface to every Kraiter API resource. It handles authentication, pagination, and error handling so you can focus on your integration logic.

Installation

npm install @kraiter/sdk

Or with your preferred package manager:

pnpm add @kraiter/sdk
yarn add @kraiter/sdk

Initialisation

Create a client instance by passing your API key. Generate one from Settings in the dashboard.

import { Kraiter } from '@kraiter/sdk';

const kraiter = new Kraiter({
  apiKey: process.env.KRAITER_API_KEY,
});

Configuration options

* Either apiKey or getToken must be provided.

Authentication

The SDK uses bearer-token authentication. When you provide an apiKey, it is sent as a Bearer token with every request. No token refresh logic is needed — API keys do not expire (but can be revoked from the dashboard).

const kraiter = new Kraiter({
  apiKey: process.env.KRAITER_API_KEY,
});

Error handling

All SDK methods throw a KraiterError when the API returns a non-2xx response. The error includes structured information about what went wrong.

import { KraiterError } from '@kraiter/sdk';

try {
  await kraiter.contacts.get('non-existent-id');
} catch (error) {
  if (error instanceof KraiterError) {
    console.error(error.code);       // e.g. "NOT_FOUND"
    console.error(error.message);    // e.g. "Contact not found"
    console.error(error.statusCode); // e.g. 404
  }
}

KraiterError properties

Common error codes

Pagination

Methods that return collections use async iterators. This means you can use for await...of to iterate through all results without manually managing cursors.

for await (const contact of kraiter.contacts.list()) {
  console.log(contact.email);
}

The SDK fetches pages behind the scenes and yields items one by one. You can pass limit and cursor to control page size and starting position.

// Fetch contacts in pages of 50
for await (const contact of kraiter.contacts.list({ limit: 50 })) {
  console.log(contact.email);
}

If you need to break out of iteration early, simply use break — the SDK will stop fetching subsequent pages.

let count = 0;
for await (const contact of kraiter.contacts.list()) {
  console.log(contact.email);
  count++;
  if (count >= 10) break; // stop after 10 results
}

Resource namespaces

The SDK organises methods under resource namespaces on the client instance: