SDK API reference: methods and user context

Bugdump.init() returns an instance with a full programmatic API. Use it to attach identity, add your own context, and control the widget from your code.

import { Bugdump } from '@bugdump/sdk';

const bugdump = Bugdump.init({ apiKey: 'your-api-key' });

In React and Next.js, @bugdump/react creates the instance for you and useBugdump() returns it.

Reaching the instance

init() returns the instance, so hold onto it when you can. When you cannot — a script-tag setup where auto-init ran, or code far from your init site — use the static accessor:

Bugdump.getInstance();   // the instance, or null

It returns null until initialization has succeeded, so always guard before calling a method on it:

Bugdump.getInstance()?.open();

An unguarded Bugdump.getInstance().open() throws a TypeError in your page whenever the key was missing, revoked, or the script had not finished loading.

init() itself only takes effect once: if an instance already exists, a second call returns it and ignores the configuration passed in. See Choosing an installation method.

The script-tag command form

Pages that load the SDK from a <script> tag get a second calling convention: a global bugdump(command, ...args) function, paired with a three-line stub in the install snippet. Calls made before the async script has loaded are queued and replayed in order once it arrives, so timing never matters:

bugdump('init', { apiKey: 'your-api-key' });
bugdump('identify', { id: 'user_123', email: 'ada@example.com' });
bugdump('open', { taskId: 42 });

The available commands are the fire-and-forget methods: init, identify, reset, setContext, setTheme, open, close, identifyTask, clearTask, captureException, and destroy. Each maps to the instance method of the same name. Methods that return a value — getInstance, submit, collectTelemetry, getConfig, getActiveTaskId, isWidgetOpen — are not commands, because a queued call has nowhere to return a result; call those on window.Bugdump after the script has loaded. An unknown command logs a console warning and does nothing.

See Choosing an installation method for the stub itself and when to use it.

Identifying the reporter

identify() attaches user information to every report from that point on, so reporters don't have to type their own name and email.

bugdump.identify({
  id: 'user_123',
  email: 'ada@example.com',
  name: 'Ada Lovelace',
  plan: 'pro',
});

id, email, and name are recognized fields. Any other properties you add are carried along too, so plan, accountAge, or orgId all work.

Call this once your user is authenticated. It is the single highest-value line you can add after installation: it turns "some user hit a bug" into "this specific customer hit a bug."

reset() clears it — call it on logout, so the next person using the browser is not reported as the previous one.

bugdump.reset();

Adding your own context

setContext() attaches arbitrary application state to reports.

bugdump.setContext({
  featureFlags: ['new-checkout', 'beta-search'],
  cartItems: 3,
  route: '/checkout/payment',
  buildSha: 'a1b2c3d',
});

The buildSha is worth calling out. Knowing which build a report came from tells you instantly whether a bug predates or postdates a deploy, and that single field regularly saves an afternoon.

Each call merges into the context set before, and reset() clears it. Reports and error events show it on their Context tab, one key per row.

getContext() and getUser() return the current values if you need to read them back.

Controlling the widget

bugdump.open();                    // open the panel
bugdump.open({ taskId: 42 });      // open pre-attached to task #42
bugdump.close();                   // close it
bugdump.isWidgetOpen();            // boolean

open() is what you call from your own trigger when running with hideButton: true:

document.querySelector('#report-bug').addEventListener('click', () => {
  bugdump.open();
});

There is no way to open the panel without initializing first, since initialization is what mounts it. On an instance you have already destroyed, these calls do nothing.

Sending a report from your own form

submit() files a report without the panel: pass what your own form collected, and the SDK attaches the same console logs, network requests, actions, context and session replay the widget would.

const { taskPublicId } = await bugdump.submit({
  description: 'I clicked Pay and nothing happened',   // required
  reporterEmail: 'ada@example.com',                     // falls back to identify()
  priority: 'High',                                     // one of your project's priority labels
  files: Array.from(fileInput.files ?? []),
});

It also takes reporterName and taskId, resolves with { id, taskId, taskPublicId }, and rejects with a BugdumpApiError when the report is refused. Pair it with hideButton: true. Available from version 0.0.40.

See Sending reports from your own form for every option, what is attached, React and Angular examples, and the error codes.

Sending errors you catch

The widget captures uncaught errors and unhandled promise rejections by itself. An error your code catches never reaches it, so send that one yourself:

try {
  await checkout();
} catch (error) {
  bugdump.captureException(error, { context: { step: 'payment' } });
  showErrorMessage();
}

captureException(error, options?) sends the error to the project's Errors page, marked Reported by the app. options.context is merged over your setContext() data for that event only, and beforeSend runs on it as on any other error.

It goes through even when captureErrors is false or sampleRate is 0, and follows the same limits as automatic capture: each distinct error once per browser tab session, and at most 10 error events a minute from one page. If an owner or admin has turned error capture off for the project, it is refused too. It never throws. From a script tag, use the command form: bugdump('captureException', error). Available from version 0.0.44.

See Capturing JavaScript errors automatically for the options that control error capture.

Changing the theme

bugdump.setTheme('dark');   // 'light', 'dark' or 'auto'

setTheme() switches the widget's color theme without re-initializing. The widget changes immediately, including a panel that is already open, and the screenshot annotation editor uses the new theme the next time it opens. Call it from your app's own theme toggle so the widget follows it. From a script tag, use the command form: bugdump('setTheme', 'dark').

The theme option (or data-theme on the script tag) still sets the theme the widget starts with. Pass it there as well, so the widget opens in the right colors before your own code runs. See Matching the widget to your app's theme for framework examples.

Working with tasks

When you already know which task a report belongs to, set it in code rather than asking the reporter to type an ID.

bugdump.identifyTask(42);        // all subsequent reports attach to #42
bugdump.getActiveTaskId();       // 42
bugdump.clearTask();             // back to normal

This suits internal QA: put the widget on a staging build with the task ID already set, and every report from that build lands on the right task automatically.

Reading telemetry yourself

collectTelemetry() returns a snapshot of everything the SDK has collected so far — console, network, actions, performance, and metadata — without submitting a report.

const snapshot = bugdump.collectTelemetry();

Useful when you want to attach the same diagnostic data to your own error handler, or to inspect what would be sent before enabling capture in production.

Teardown

bugdump.destroy();

Removes the widget, stops every collector, and clears the singleton. Call it when unmounting in a single-page app that tears down and rebuilds its root, so you do not stack multiple instances.

Because it clears the singleton, a later init() builds a fresh instance — making destroy-then-init the way to change configuration after the fact. The telemetry collected so far is discarded along with it. The theme is the exception: change it in place with setTheme(), which keeps the instance and its telemetry intact.

On a destroyed instance, identify, reset, setContext, setTheme, open, close, identifyTask and clearTask do nothing, so a cleanup that runs after teardown cannot crash your app, and captureException() logs a warning. collectTelemetry() and getHttpClient() throw This Bugdump instance was destroyed., and submit() rejects with it. Before version 0.0.45, those eight methods threw too.

Inspecting configuration

bugdump.getConfig();       // the resolved config, defaults filled in
bugdump.getHttpClient();   // the underlying HTTP client

getConfig() is the quickest way to confirm which options actually took effect, since defaults are merged in at init.

Error handling

Failed API calls throw BugdumpApiError, which is exported for narrowing. Its code is the error code — REPORT_QUOTA_EXCEEDED or TASK_LIMIT_REACHED (both 403) when the project is not accepting reports — and statusCode is the HTTP status:

import { BugdumpApiError } from '@bugdump/sdk';

try {
  // ...
} catch (error) {
  if (error instanceof BugdumpApiError) {
    // handle a BugDump-specific failure
  }
}

Types

The package is TypeScript-first. BugdumpConfig, BugdumpUserContext, BugdumpTheme, BugdumpPosition, BugdumpLocale, BugdumpTranslations, TelemetrySnapshot, ReportPayload, and the annotation and collector types are all exported.

See also

• Choosing an installation method

• Filtering console and network capture

• Widget configuration reference