Ittybit

The Ittybit TypeScript library provides convenient access to the Ittybit API from TypeScript.

Installation

npm i -s @ittybit/sdk

Usage

Instantiate and use the client with the following:

import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({ token: "ITTYBIT_API_KEY" });
await ittybit.automations.create();

Request And Response Types

The SDK exports all request and response types as TypeScript interfaces. Simply import them with the following namespace:

import { Ittybit } from "@ittybit/sdk";

const request: Ittybit.AutomationsUpdateRequest = {
    ...
};

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

import { IttybitError } from "@ittybit/sdk";

try {
    await ittybit.automations.create(...);
} catch (err) {
    if (err instanceof IttybitError) {
        console.log(err.statusCode);
        console.log(err.message);
        console.log(err.body);
        console.log(err.rawResponse);
    }
}

Advanced

Additional Headers

If you would like to send additional headers as part of the request, use the headers request option.

const response = await ittybit.automations.create(..., {
    headers: {
        'X-Custom-Header': 'custom value'
    }
});

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

408 (Timeout)
429 (Too Many Requests)
5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

const response = await ittybit.automations.create(..., {
    maxRetries: 0 // override maxRetries at the request level
});

Timeouts

The SDK defaults to a 60 second timeout. Use the timeoutInSeconds option to configure this behavior.

const response = await ittybit.automations.create(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});

Aborting Requests

The SDK allows users to abort requests at any point by passing in an abort signal.

const controller = new AbortController();
const response = await ittybit.automations.create(..., {
    abortSignal: controller.signal
});
controller.abort(); // aborts the request

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the .withRawResponse() method. The .withRawResponse() method returns a promise that results to an object with a data and a rawResponse property.

const { data, rawResponse } = await ittybit.automations.create(...).withRawResponse();

console.log(data);
console.log(rawResponse.headers['X-My-Header']);

Runtime Compatibility

The SDK defaults to node-fetch but will use the global fetch client if present. The SDK works in the following runtimes:

Node.js 18+
Vercel
Cloudflare Workers
Deno v1.25+
Bun 1.0+
React Native

Customizing Fetch Client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an unsupported environment, this provides a way for you to break glass and ensure the SDK works.

import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
    ...
    fetcher: // provide your implementation here
});

TypeScript SDK