TypeScript 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 when you want ready-made terminal commands. Use Public API when you need direct HTTP API control from another language.

https://www.npmjs.com/package/@bugbug-io/sdkwww.npmjs.com

Requirements

BugBug TypeScript SDK access requires a Business BugBug plan because it uses API access.

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:

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.

export BUGBUG_API_TOKEN=<api-token>

Create the SDK client

Import createBugBug and pass your token:

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:

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:

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:

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

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

Override variables for a single run:

await bugbug.tests.startRun('test-id-or-name', {
  variables: [
    { key: 'username', value: '[e-mail]' },
    { key: 'plan', value: 'pro' },
  ],
});

Run a suite

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.

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:

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:

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.

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.

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