SDK API reference

Every public export of the @belvador/* packages, version 0.6.1, grouped by import path. Anything not listed here — @belvador/core, the /internal subpaths and helper functions used between packages — is internal and can change without notice.

Which functions each import path has#

The root @belvador/tanstack-start export holds the middleware: belvadorRequestMiddleware, belvadorFunctionMiddleware, withBelvadorRouter, belvadorOnCatch, isExpectedError and SDK_VERSION.

Starting the SDK#

init(options): boolean#

From @belvador/browser, @belvador/react and @belvador/tanstack-start/client. Starts error tracking in the browser and returns whether it is running. It never throws: an invalid DSN logs one warning and leaves the SDK off. A second call with the same DSN does nothing; a different DSN does not replace the running client. Options: SDK options.

withBelvador(options, handler): handler#

From @belvador/cloudflare and @belvador/tanstack-start/server. options is a function (env) => WorkerOptions | undefined, called with the Worker's environment. Returns a handler object of the same shape that reports errors from fetch, scheduled, queue, email and tail, re-throws them and leaves responses unchanged. Needs nodejs_compat.

privacyPolicy(json): BelvadorPrivacyPolicy | null#

Checks a policy copied from the project's Privacy page (Copy as code) and prepares it for init({ privacyPolicy }). Returns null and reports BLV_PRIVACY_POLICY_INVALID when it is not valid; never throws. See Data protection. Since 0.6.0.

Capturing#

captureException(error, context?): string#

Reports an error. context can carry tags, extra, contexts, level, user or fingerprint for this event only. Returns an event ID, or "" when the SDK is off.

captureException(error, { tags: { feature: "import" }, level: "warning" });

captureMessage(message, level?): string#

Reports a message without an exception, for example a state that should never happen. level is one of fatal, error, warning, log, info, debug.

captureResult(result, { operation, expected? }): result#

Reports the error of a { data, error } result — Supabase, PostgREST or any client that returns errors instead of throwing — as one event typed by its database code, grouped by type and operation, and returns result unchanged. Never sends the SQL, details or hint. See Database errors. Since 0.6.0.

lastEventId(): string#

The ID of the last event this page sent, or "".

Context#

Everything you set passes through the same scrubbing as events. On Workers and TanStack Start servers, each request has its own scope, so context never leaks into another request.

withScope(callback)#

Runs callback(scope) with a temporary scope, for context that should apply to one capture only:

import { captureException, withScope } from "@belvador/browser";withScope((scope) => {  scope.setTag("job", "nightly-sync");  scope.setFingerprint(["nightly-sync", "{{ default }}"]);  captureException(error);});

scope is the engine's scope object. When the SDK is off, the callback still runs, without a usable scope — do not rely on it there.

Delivery#

flush(timeoutMs = 2000): Promise<boolean>#

Waits until queued events are sent or the timeout passes. Resolves true when everything pending finished in time. Useful at the end of a script. On Workers you do not need it — withBelvador already waits in waitUntil.

close(timeoutMs = 2000): Promise<boolean>#

Flushes, then shuts the SDK down. Nothing is sent afterwards.

React#

ErrorBoundary#

A component that reports render errors from its children once, with the component stack, and renders fallback — an element or ({ error, componentStack, eventId, resetError }) => element. Supports onError, onReset, onMount, onUnmount and beforeCapture like the Sentry React boundary. The user-feedback dialog props are not available.

withErrorBoundary(Component, props)#

Wraps a component in ErrorBoundary with the given props.

reactErrorHandler(callback?)#

Returns a handler for React 19's onUncaughtError, onCaughtError and onRecoverableError root options. The optional callback(error, errorInfo, eventId) runs after the report.

TanStack Start#

Monitors#

Server packages only (@belvador/cloudflare, @belvador/tanstack-start/server), from 0.3.0. None of them throws. How to use them: Add monitors with the SDK.

withMonitor(slug, fn, options?): ReturnType<fn>#

Runs fn(run) as one monitored attempt and returns exactly what fn returns (or throws what it throws). run.skip(reason) marks the run Skipped, run.unknown(reason) marks it Outcome unknown; run.checkInId and run.runId are the ids sent. options: schedule, timezone, checkinMargin, maxRuntime, failureIssueThreshold, recoveryThreshold (create or update the monitor from code), environment, runId, attempt, willRetry.

captureCheckIn(checkIn, monitorConfig?): string#

Sends one check-in { monitorSlug, status: "in_progress" | "ok" | "error", checkInId?, duration?, environment?, runId?, attempt?, willRetry?, outcome?: "skipped" | "unknown", reason? } and returns its id ("" when the SDK is off or the slug is invalid).

heartbeat(slug, options?): void#

Sends one ok check-in, for every-N-minutes monitors. options.environment overrides the SDK's environment.

Types#