# TypeScript SDK

[View original](https://ittybit.com/sdks/typescript)

## Installation

<Tabs groupId="language" items={["npm", "yarn", "pnpm"]}>
  <Tab value="npm">
    ```bash
    npm i -s @ittybit/sdk
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @ittybit/sdk
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @ittybit/sdk
    ```
  </Tab>
</Tabs>

***

## Usage

Instantiate and use the client with the following:

```typescript
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:

```typescript
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.

```typescript
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.

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

***

### Retries

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
* [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
* [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)

Use the `maxRetries` request option to configure this behavior.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

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

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