Configuration, cancellation, and errors

Client options

import {KaitenClient} from '@2chevskii/kaiten-client';

const client = new KaitenClient({
  origin: 'https://your-company.kaiten.ru',
  token: async () => await getCurrentToken(),
  apiVersion: 'latest',
  fetch: globalThis.fetch,
});

token accepts a string or a function returning a string or Promise<string>. The function runs before every request. Replace fetch, for example, in tests. REST uses /api/v1 by default; apiVersion: "latest" selects /api/latest. SCIM always uses /scim/v2.

Exported types include ClientOptions, RestClientOptions, TokenProvider, OperationOptions, and QueryValue. API fields retain Kaiten's snake_case names and dates stay strings. The client does not validate data schemas at runtime.

Cancel a request

const controller = new AbortController();
const request = client.cards.retrieveCardList(
  {limit: 50},
  {signal: controller.signal},
);

controller.abort();
await request; // Rejects with the cancellation error.

Cancellation also interrupts waiting for an asynchronous token provider, rejecting with the signal's reason. The provider controls cancellation of its own work. A token that resolves later will not start the cancelled HTTP request. This applies to REST, SCIM, and addon OAuth clients.

HTTP errors

import {KaitenHttpError} from '@2chevskii/kaiten-client';

try {
  await client.cards.retrieveCard(123);
} catch (error) {
  if (error instanceof KaitenHttpError) {
    console.error(error.status, error.method, error.url);
    console.error(error.headers.get('X-RateLimit-Reset'));
    console.error(error.body);
  } else {
    throw error;
  }
}

body is unknown: it can contain JSON, text, or undefined for an empty response. Network and token-provider errors propagate unchanged. Requests are never retried automatically; implement retries in your application with the method and Kaiten limits in mind.

Malformed JSON or an unexpectedly empty successful response throws KaitenResponseError. It exposes status, headers, method, url, the original response text in body, and the parsing error in cause. Documented operations without a response body return undefined.