> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/integrations/typescript-sdk.md).

# TypeScript SDK

Build custom BugBug integrations in TypeScript or Node.js with a typed SDK.

## Build custom integrations with BugBug SDK

BugBug TypeScript SDK is a typed Node.js client for BugBug API. Use it when you want to call BugBug from your own scripts, services, CI/CD tools, internal dashboards, or AI-powered automation.

The SDK wraps BugBug API with TypeScript types, resource modules, request retries, rate limiting, error classes, cancellation support, and helpers for watching test and suite run progress.

Use SDK when you are writing JavaScript or TypeScript code. Use [CLI](/integrations/cli.md) when you want ready-made terminal commands. Use [Public API](/integrations/public-api.md) when you need direct HTTP API control from another language.

{% embed url="<https://www.npmjs.com/package/@bugbug-io/sdk>" %}

## Requirements

{% hint style="info" %}
BugBug TypeScript SDK access requires a **Business** BugBug plan because it uses API access.
{% endhint %}

You need:

* Node.js version **24 or newer**
* npm
* a BugBug account
* access to the BugBug project you want to manage
* a BugBug API token

## Install via NPM

Install the package in your project:

```bash
npm install @bugbug-io/sdk
```

## Get your API token

1. Go to the **Integrations** page.
2. Open the **API** or **CLI** tab.
3. Copy the project API token.

The API token belongs to a project. Treat it as a secret and store it in your environment or secret manager.

```bash
export BUGBUG_API_TOKEN=<api-token>
```

## Create the SDK client

Import `createBugBug` and pass your token:

```typescript
import { createBugBug } from '@bugbug-io/sdk';

const bugbug = createBugBug({
  apiToken: process.env.BUGBUG_API_TOKEN!,
});
```

You can also configure the API URL, request timeout, logging, and rate limiting:

```typescript
const bugbug = createBugBug({
  apiToken: process.env.BUGBUG_API_TOKEN!,
  apiUrl: 'https://app.bugbug.io/api/v2',
  timeout: 30000,
  verbose: true,
  rateLimit: {
    maxRequests: 100,
    windowMs: 60000,
  },
});
```

## Run a test

Run a test and wait until it finishes:

```typescript
const run = await bugbug.tests.startRun('test-id-or-name', {
  watchProgress: true,
  profileName: 'Production',
  onProgress: (state) => {
    console.log(`Status: ${state.status}`);
  },
});

console.log(`Finished with status: ${run.status}`);
```

Run a test without waiting:

```typescript
const runState = await bugbug.tests.startRun('test-id-or-name');

console.log(`Queued test run: ${runState.id}`);
```

Override variables for a single run:

```typescript
await bugbug.tests.startRun('test-id-or-name', {
  variables: [
    { key: 'username', value: 'test@example.com' },
    { key: 'plan', value: 'pro' },
  ],
});
```

## Run a suite

```typescript
const suiteRun = await bugbug.suites.startRun('suite-id', {
  watchProgress: true,
  profileName: 'Staging',
});

console.log(`Suite finished with status: ${suiteRun.status}`);
```

## Work with runs

After a test or suite is started, you can read run details, stop the run, or download reports.

```typescript
const testRun = await bugbug.tests.getRun('run-id');
const logs = await bugbug.tests.getRunLogs('run-id');
const junitXml = await bugbug.tests.downloadRunJunitReport('run-id');

await bugbug.tests.stopRun('run-id');
```

For suite runs:

```typescript
const suiteRun = await bugbug.suites.getRun('run-id');
const junitXml = await bugbug.suites.downloadRunJunitReport('run-id');

await bugbug.suites.stopRun('run-id');
```

## Manage BugBug resources

SDK modules are organized around BugBug resources:

| Module             | What it is used for                                                       |
| ------------------ | ------------------------------------------------------------------------- |
| `tests`            | List, create, update, delete, import, export, and run tests.              |
| `suites`           | List, inspect, and run suites.                                            |
| `profiles`         | List profiles and find profiles by name.                                  |
| `project`          | Read project settings, export project data, and import project ZIP files. |
| `projects`         | List projects available to the current credentials.                       |
| `groups`           | Manage groups and reusable test building blocks.                          |
| `components`       | List reusable components and check component usage.                       |
| `steps`            | Create, update, inspect, and delete test steps.                           |
| `stepRuns`         | Read step run details, including debug data.                              |
| `variables`        | Create and update project variables.                                      |
| `visualRegression` | Manage visual regression reference screenshots.                           |
| `projectArtifacts` | Upload project artifacts for upload-file steps.                           |
| `auth`             | Build OAuth-based authentication flows.                                   |

Example:

```typescript
const tests = await bugbug.tests.list({ query: 'login' });
const profiles = await bugbug.profiles.list();
const projectSettings = await bugbug.project.getSettings();
```

## Handle errors

The SDK exports typed error classes so your integration can react to common failure modes.

```typescript
import { AuthenticationError, RateLimitError, createBugBug } from '@bugbug-io/sdk';

const bugbug = createBugBug({ apiToken: process.env.BUGBUG_API_TOKEN! });

try {
  await bugbug.tests.startRun('test-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid BugBug API token.');
  } else if (error instanceof RateLimitError) {
    console.error('BugBug API rate limit reached.');
  } else {
    throw error;
  }
}
```

## Cancel requests

All requests support `AbortController`.

```typescript
const controller = new AbortController();

setTimeout(() => controller.abort(), 5000);

const tests = await bugbug.tests.list({
  signal: controller.signal,
});
```

## Technical documentation

The full generated SDK documentation includes exported classes, modules, options, and types:

[Open TypeScript SDK technical docs](https://app.bugbug.io/sdk/docs/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bugbug.io/integrations/typescript-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.