@bugban/js 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,349 @@
+/**
+ * Public types for the Bugban JavaScript SDK.
+ *
+ * Field names on the wire mirror the PHP SDK exactly, because both talk to the
+ * same ingest endpoints and the same server-side fingerprinting. Renaming a
+ * field here silently changes how errors group — don't.
+ */
+type Level = 'error' | 'warning' | 'info' | 'debug' | 'fatal';
+type BreadcrumbType = 'console' | 'navigation' | 'click' | 'http' | 'error' | 'manual';
+interface Breadcrumb {
+    type: BreadcrumbType;
+    /** Short human label, e.g. "GET /api/orders → 500". */
+    message: string;
+    level?: Level;
+    /** ISO-8601. */
+    timestamp: string;
+    data?: Record<string, unknown>;
+}
+interface StackFrame {
+    file?: string;
+    line?: number;
+    column?: number;
+    function?: string;
+    /** false for node_modules / framework frames — the panel collapses those. */
+    in_app?: boolean;
+}
+interface UserInfo {
+    id?: string | number;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/** What the browser measured about page load and responsiveness. */
+interface VitalMetric {
+    /** LCP | FCP | CLS | INP | TTFB | LONG_TASK | RESOURCE */
+    name: string;
+    value: number;
+    /** Google's good/needs-improvement/poor bucket, computed SDK-side. */
+    rating?: 'good' | 'needs-improvement' | 'poor';
+    url?: string;
+    /** Element selector or resource URL the metric is attributed to. */
+    target?: string;
+    navigation_type?: string;
+    occurred_at?: string;
+    data?: Record<string, unknown>;
+}
+/** A serialized DOM snapshot taken at error time (never a pixel image). */
+interface Snapshot {
+    kind: 'dom';
+    html: string;
+    /** Inlined same-origin stylesheet text, so the replay renders standalone. */
+    css?: string;
+    viewport?: {
+        width: number;
+        height: number;
+        scrollX: number;
+        scrollY: number;
+    };
+    url?: string;
+    taken_at?: string;
+}
+interface BugbanEvent {
+    exception_class?: string;
+    message?: string;
+    level?: Level;
+    type?: string;
+    file?: string;
+    line?: number;
+    handled?: boolean;
+    stacktrace?: StackFrame[];
+    release?: string;
+    environment?: string;
+    request?: Record<string, unknown>;
+    user?: UserInfo | null;
+    session?: Record<string, unknown>;
+    device?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    breadcrumbs?: Breadcrumb[];
+    snapshot?: Snapshot | null;
+    /** Server groups by this when present; otherwise it derives one. */
+    fingerprint?: string;
+}
+interface ConsoleOptions {
+    /** Which console methods become breadcrumbs. */
+    levels?: Array<'log' | 'info' | 'warn' | 'error' | 'debug'>;
+    /**
+     * Which console methods ALSO report a standalone error event.
+     * Defaults to ['error'] — console.error is how most apps surface a
+     * swallowed failure that never reaches window.onerror.
+     */
+    captureAsEvent?: Array<'warn' | 'error'>;
+}
+interface NetworkOptions {
+    /** Record fetch/XHR calls as breadcrumbs. */
+    enabled?: boolean;
+    /** Report failed requests (>=500, or network error) as their own event. */
+    captureFailures?: boolean;
+    /** Substrings; matching URLs are never recorded (in addition to our own). */
+    ignoreUrls?: Array<string | RegExp>;
+}
+interface SnapshotOptions {
+    enabled?: boolean;
+    /**
+     * Replace the value of every input/textarea/select before serializing.
+     * NON-NEGOTIABLE DEFAULT: true. Turning it off ships whatever the user had
+     * typed — including passwords and card numbers — to the Bugban server.
+     */
+    maskInputs?: boolean;
+    /** Extra CSS selectors whose text content is replaced with •. */
+    maskSelectors?: string[];
+    /** Skip the snapshot entirely once the HTML exceeds this many bytes. */
+    maxBytes?: number;
+}
+interface VitalsOptions {
+    enabled?: boolean;
+    /** 0..1 — fraction of sessions that report vitals. 1 = every session. */
+    sampleRate?: number;
+    /** Report tasks blocking the main thread longer than this (ms). */
+    longTaskMs?: number;
+    /** Report individual resources slower than this (ms). */
+    slowResourceMs?: number;
+}
+interface BugbanOptions {
+    /** Project API key. Without it the SDK is a silent no-op. */
+    apiKey?: string;
+    /** Bugban host, e.g. https://bugban.online */
+    host?: string;
+    /** Your app version — shown on the event and used for release grouping. */
+    release?: string;
+    environment?: string;
+    /** Framework name reported on the install ping (adapters set this). */
+    framework?: string;
+    frameworkVersion?: string;
+    /** Turn the whole SDK off without removing the code (e.g. in dev). */
+    enabled?: boolean;
+    debug?: boolean;
+    /** Max breadcrumbs kept in the ring buffer. */
+    maxBreadcrumbs?: number;
+    /** 0..1 — fraction of errors actually sent. */
+    sampleRate?: number;
+    console?: boolean | ConsoleOptions;
+    network?: boolean | NetworkOptions;
+    snapshot?: boolean | SnapshotOptions;
+    vitals?: boolean | VitalsOptions;
+    /** Capture window.onerror / unhandledrejection (browser) and the Node equivalents. */
+    globalHandlers?: boolean;
+    /** Record clicks and route changes as breadcrumbs. */
+    domBreadcrumbs?: boolean;
+    /** Send the one-time install ping so the panel shows "SDK connected". */
+    installPing?: boolean;
+    /** Extra request-header/body keys to redact, on top of the built-ins. */
+    redactKeys?: string[];
+    /** Drop an event (return null) or edit it before it is sent. */
+    beforeSend?: (event: BugbanEvent) => BugbanEvent | null;
+    /** Drop or edit a breadcrumb before it enters the buffer. */
+    beforeBreadcrumb?: (crumb: Breadcrumb) => Breadcrumb | null;
+    /** Errors whose message matches any of these are never sent. */
+    ignoreErrors?: Array<string | RegExp>;
+}
+/** Fully-resolved options — every optional field has a value. */
+interface ResolvedOptions extends BugbanOptions {
+    apiKey: string;
+    host: string;
+    enabled: boolean;
+    debug: boolean;
+    maxBreadcrumbs: number;
+    sampleRate: number;
+    console: Required<ConsoleOptions> | false;
+    network: Required<NetworkOptions> | false;
+    snapshot: Required<SnapshotOptions> | false;
+    vitals: Required<VitalsOptions> | false;
+    globalHandlers: boolean;
+    domBreadcrumbs: boolean;
+    installPing: boolean;
+    redactKeys: string[];
+    ignoreErrors: Array<string | RegExp>;
+}
+
+/**
+ * The SDK client.
+ *
+ * One rule governs every method here: nothing may throw into the host
+ * application, and nothing may block it. Every public entry point is wrapped,
+ * every optional browser API is feature-detected, and delivery is
+ * fire-and-forget. A monitoring tool that can take down the app it monitors is
+ * worse than no monitoring at all.
+ */
+declare class BugbanClient {
+    private opts;
+    private transport;
+    private crumbs;
+    private vitals?;
+    private teardown;
+    private user;
+    private context;
+    private sessionId;
+    private startedAt;
+    /** Events waiting to be sent, coalesced so an error storm is one request. */
+    private queue;
+    private flushTimer;
+    /** Guard against reporting an error that our own reporting caused. */
+    private sending;
+    private started;
+    constructor(options?: BugbanOptions);
+    get options(): ResolvedOptions;
+    /** Wire up integrations. Safe to call twice — the second call is ignored. */
+    start(): void;
+    private installIntegrations;
+    /**
+     * Send whatever is queued before the page goes away.
+     *
+     * Events are batched with a short debounce so an error loop becomes one
+     * request instead of hundreds. That debounce loses the last batch whenever
+     * the user navigates immediately after the error — which is the common
+     * case, not an edge case: click a link, something throws, the document is
+     * torn down before the timer fires. Observed exactly that while testing:
+     * an uncaught TypeError never arrived while the beacon-based vitals from the
+     * same page did.
+     *
+     * `visibilitychange` is the reliable signal (mobile Safari often skips
+     * `beforeunload`), and `pagehide` covers the bfcache case. Both drain with
+     * `beacon: true`, the only delivery a closing document is guaranteed to
+     * complete.
+     */
+    private installUnloadFlush;
+    addBreadcrumb(crumb: Omit<Breadcrumb, 'timestamp'> & {
+        timestamp?: string;
+    }): void;
+    setUser(user: UserInfo | null): void;
+    setContext(key: string, value: unknown): void;
+    captureMessage(message: string, level?: Level): void;
+    /** Report an error. Never throws, never blocks. */
+    capture(error: unknown, extra?: {
+        handled?: boolean;
+        level?: Level;
+        type?: string;
+        context?: Record<string, unknown>;
+        request?: Record<string, unknown>;
+    }): void;
+    /** Flush anything queued. Await it before a process exits. */
+    flush(): Promise<void>;
+    /** Remove every hook the SDK installed. */
+    close(): void;
+    /** Adapters use this to report render timings alongside browser vitals. */
+    recordMetric(metric: VitalMetric): void;
+    private requestInfo;
+    private enqueue;
+    private drain;
+    private sendVitals;
+    private debug;
+}
+
+declare function parseStack(stack: unknown, limit?: number): StackFrame[];
+/**
+ * Normalise anything a JS app can throw into an error-shaped object.
+ * `throw 'a string'` and `Promise.reject({code: 500})` are both common; both
+ * must produce a usable event rather than "undefined".
+ */
+declare function normalizeError(input: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+};
+
+/**
+ * Deep-redact an object by key name. Depth-limited so a pathological structure
+ * cannot lock up the main thread.
+ */
+declare function redact<T>(value: T, extraKeys?: string[], depth?: number): T;
+/**
+ * Strip credentials out of a URL: query params named like secrets, plus any
+ * user:pass@ prefix. Returns the input unchanged if it cannot be parsed.
+ */
+declare function redactUrl(url: string, extraKeys?: string[]): string;
+
+/**
+ * Runtime detection and environment facts.
+ *
+ * Every lookup is defensive: this file runs in browsers, in Node, in edge
+ * runtimes, and during SSR where `window` exists but `document` does not.
+ * Nothing here may throw — a crash in environment detection would take down
+ * the host application on import, which is exactly the failure the PHP SDK
+ * learned to avoid the hard way.
+ */
+declare const SDK_NAME = "bugban-js";
+declare const SDK_VERSION = "1.0.0";
+/** 'browser' | 'node' | 'unknown' — reported on the install ping. */
+declare function runtimeName(): string;
+/**
+ * The runtime's own version: Node's `v22.13.1`, or the browser's UA string.
+ * The panel shows this next to the framework version, the same way it shows
+ * the PHP version for the PHP SDKs.
+ */
+declare function runtimeVersion(): string | undefined;
+/**
+ * Read a dependency's version out of the host app's node_modules, so an
+ * adapter can report "react 19.0.0" without importing react itself.
+ */
+declare function dependencyVersion(pkg: string): Promise<string | undefined>;
+
+declare function init(options?: BugbanOptions): BugbanClient;
+/** The active client, or null when init() has not been called. */
+declare function getClient(): BugbanClient | null;
+/**
+ * Every helper below is a no-op before init(). That is deliberate: a component
+ * that calls captureError must not crash because the app forgot to configure
+ * monitoring, or because it is running in a test.
+ */
+declare function capture(error: unknown, extra?: {
+    handled?: boolean;
+    level?: Level;
+    type?: string;
+    context?: Record<string, unknown>;
+}): void;
+declare function captureMessage(message: string, level?: Level): void;
+declare function setUser(user: UserInfo | null): void;
+declare function setContext(key: string, value: unknown): void;
+declare function addBreadcrumb(crumb: Omit<Breadcrumb, 'timestamp'> & {
+    timestamp?: string;
+}): void;
+declare function recordMetric(metric: VitalMetric): void;
+declare function flush(): Promise<void>;
+declare function close(): void;
+/**
+ * Namespace form, so `Bugban.capture(e)` reads the same as the PHP facade.
+ *
+ * Deliberately NOT also a default export: mixing default and named exports
+ * makes the CommonJS build require `.default`, which is exactly the kind of
+ * "works in one install shape, breaks in another" trap that took a customer's
+ * site down on the PHP side. One import style, everywhere:
+ *
+ *   import { Bugban } from '@bugban/js';
+ *   const { Bugban } = require('@bugban/js');
+ */
+declare const Bugban: {
+    VERSION: string;
+    init: typeof init;
+    getClient: typeof getClient;
+    capture: typeof capture;
+    captureMessage: typeof captureMessage;
+    setUser: typeof setUser;
+    setContext: typeof setContext;
+    addBreadcrumb: typeof addBreadcrumb;
+    recordMetric: typeof recordMetric;
+    flush: typeof flush;
+    close: typeof close;
+};
+
+export { type Breadcrumb, type BreadcrumbType, Bugban, BugbanClient, type BugbanEvent, type BugbanOptions, type ConsoleOptions, type Level, type NetworkOptions, SDK_NAME, SDK_VERSION, type Snapshot, type SnapshotOptions, type StackFrame, type UserInfo, type VitalMetric, type VitalsOptions, addBreadcrumb, capture, captureMessage, close, dependencyVersion, flush, getClient, init, normalizeError, parseStack, recordMetric, redact, redactUrl, runtimeName, runtimeVersion, setContext, setUser };

package/dist/index.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Public types for the Bugban JavaScript SDK.
+ *
+ * Field names on the wire mirror the PHP SDK exactly, because both talk to the
+ * same ingest endpoints and the same server-side fingerprinting. Renaming a
+ * field here silently changes how errors group — don't.
+ */
+type Level = 'error' | 'warning' | 'info' | 'debug' | 'fatal';
+type BreadcrumbType = 'console' | 'navigation' | 'click' | 'http' | 'error' | 'manual';
+interface Breadcrumb {
+    type: BreadcrumbType;
+    /** Short human label, e.g. "GET /api/orders → 500". */
+    message: string;
+    level?: Level;
+    /** ISO-8601. */
+    timestamp: string;
+    data?: Record<string, unknown>;
+}
+interface StackFrame {
+    file?: string;
+    line?: number;
+    column?: number;
+    function?: string;
+    /** false for node_modules / framework frames — the panel collapses those. */
+    in_app?: boolean;
+}
+interface UserInfo {
+    id?: string | number;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/** What the browser measured about page load and responsiveness. */
+interface VitalMetric {
+    /** LCP | FCP | CLS | INP | TTFB | LONG_TASK | RESOURCE */
+    name: string;
+    value: number;
+    /** Google's good/needs-improvement/poor bucket, computed SDK-side. */
+    rating?: 'good' | 'needs-improvement' | 'poor';
+    url?: string;
+    /** Element selector or resource URL the metric is attributed to. */
+    target?: string;
+    navigation_type?: string;
+    occurred_at?: string;
+    data?: Record<string, unknown>;
+}
+/** A serialized DOM snapshot taken at error time (never a pixel image). */
+interface Snapshot {
+    kind: 'dom';
+    html: string;
+    /** Inlined same-origin stylesheet text, so the replay renders standalone. */
+    css?: string;
+    viewport?: {
+        width: number;
+        height: number;
+        scrollX: number;
+        scrollY: number;
+    };
+    url?: string;
+    taken_at?: string;
+}
+interface BugbanEvent {
+    exception_class?: string;
+    message?: string;
+    level?: Level;
+    type?: string;
+    file?: string;
+    line?: number;
+    handled?: boolean;
+    stacktrace?: StackFrame[];
+    release?: string;
+    environment?: string;
+    request?: Record<string, unknown>;
+    user?: UserInfo | null;
+    session?: Record<string, unknown>;
+    device?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    breadcrumbs?: Breadcrumb[];
+    snapshot?: Snapshot | null;
+    /** Server groups by this when present; otherwise it derives one. */
+    fingerprint?: string;
+}
+interface ConsoleOptions {
+    /** Which console methods become breadcrumbs. */
+    levels?: Array<'log' | 'info' | 'warn' | 'error' | 'debug'>;
+    /**
+     * Which console methods ALSO report a standalone error event.
+     * Defaults to ['error'] — console.error is how most apps surface a
+     * swallowed failure that never reaches window.onerror.
+     */
+    captureAsEvent?: Array<'warn' | 'error'>;
+}
+interface NetworkOptions {
+    /** Record fetch/XHR calls as breadcrumbs. */
+    enabled?: boolean;
+    /** Report failed requests (>=500, or network error) as their own event. */
+    captureFailures?: boolean;
+    /** Substrings; matching URLs are never recorded (in addition to our own). */
+    ignoreUrls?: Array<string | RegExp>;
+}
+interface SnapshotOptions {
+    enabled?: boolean;
+    /**
+     * Replace the value of every input/textarea/select before serializing.
+     * NON-NEGOTIABLE DEFAULT: true. Turning it off ships whatever the user had
+     * typed — including passwords and card numbers — to the Bugban server.
+     */
+    maskInputs?: boolean;
+    /** Extra CSS selectors whose text content is replaced with •. */
+    maskSelectors?: string[];
+    /** Skip the snapshot entirely once the HTML exceeds this many bytes. */
+    maxBytes?: number;
+}
+interface VitalsOptions {
+    enabled?: boolean;
+    /** 0..1 — fraction of sessions that report vitals. 1 = every session. */
+    sampleRate?: number;
+    /** Report tasks blocking the main thread longer than this (ms). */
+    longTaskMs?: number;
+    /** Report individual resources slower than this (ms). */
+    slowResourceMs?: number;
+}
+interface BugbanOptions {
+    /** Project API key. Without it the SDK is a silent no-op. */
+    apiKey?: string;
+    /** Bugban host, e.g. https://bugban.online */
+    host?: string;
+    /** Your app version — shown on the event and used for release grouping. */
+    release?: string;
+    environment?: string;
+    /** Framework name reported on the install ping (adapters set this). */
+    framework?: string;
+    frameworkVersion?: string;
+    /** Turn the whole SDK off without removing the code (e.g. in dev). */
+    enabled?: boolean;
+    debug?: boolean;
+    /** Max breadcrumbs kept in the ring buffer. */
+    maxBreadcrumbs?: number;
+    /** 0..1 — fraction of errors actually sent. */
+    sampleRate?: number;
+    console?: boolean | ConsoleOptions;
+    network?: boolean | NetworkOptions;
+    snapshot?: boolean | SnapshotOptions;
+    vitals?: boolean | VitalsOptions;
+    /** Capture window.onerror / unhandledrejection (browser) and the Node equivalents. */
+    globalHandlers?: boolean;
+    /** Record clicks and route changes as breadcrumbs. */
+    domBreadcrumbs?: boolean;
+    /** Send the one-time install ping so the panel shows "SDK connected". */
+    installPing?: boolean;
+    /** Extra request-header/body keys to redact, on top of the built-ins. */
+    redactKeys?: string[];
+    /** Drop an event (return null) or edit it before it is sent. */
+    beforeSend?: (event: BugbanEvent) => BugbanEvent | null;
+    /** Drop or edit a breadcrumb before it enters the buffer. */
+    beforeBreadcrumb?: (crumb: Breadcrumb) => Breadcrumb | null;
+    /** Errors whose message matches any of these are never sent. */
+    ignoreErrors?: Array<string | RegExp>;
+}
+/** Fully-resolved options — every optional field has a value. */
+interface ResolvedOptions extends BugbanOptions {
+    apiKey: string;
+    host: string;
+    enabled: boolean;
+    debug: boolean;
+    maxBreadcrumbs: number;
+    sampleRate: number;
+    console: Required<ConsoleOptions> | false;
+    network: Required<NetworkOptions> | false;
+    snapshot: Required<SnapshotOptions> | false;
+    vitals: Required<VitalsOptions> | false;
+    globalHandlers: boolean;
+    domBreadcrumbs: boolean;
+    installPing: boolean;
+    redactKeys: string[];
+    ignoreErrors: Array<string | RegExp>;
+}
+
+/**
+ * The SDK client.
+ *
+ * One rule governs every method here: nothing may throw into the host
+ * application, and nothing may block it. Every public entry point is wrapped,
+ * every optional browser API is feature-detected, and delivery is
+ * fire-and-forget. A monitoring tool that can take down the app it monitors is
+ * worse than no monitoring at all.
+ */
+declare class BugbanClient {
+    private opts;
+    private transport;
+    private crumbs;
+    private vitals?;
+    private teardown;
+    private user;
+    private context;
+    private sessionId;
+    private startedAt;
+    /** Events waiting to be sent, coalesced so an error storm is one request. */
+    private queue;
+    private flushTimer;
+    /** Guard against reporting an error that our own reporting caused. */
+    private sending;
+    private started;
+    constructor(options?: BugbanOptions);
+    get options(): ResolvedOptions;
+    /** Wire up integrations. Safe to call twice — the second call is ignored. */
+    start(): void;
+    private installIntegrations;
+    /**
+     * Send whatever is queued before the page goes away.
+     *
+     * Events are batched with a short debounce so an error loop becomes one
+     * request instead of hundreds. That debounce loses the last batch whenever
+     * the user navigates immediately after the error — which is the common
+     * case, not an edge case: click a link, something throws, the document is
+     * torn down before the timer fires. Observed exactly that while testing:
+     * an uncaught TypeError never arrived while the beacon-based vitals from the
+     * same page did.
+     *
+     * `visibilitychange` is the reliable signal (mobile Safari often skips
+     * `beforeunload`), and `pagehide` covers the bfcache case. Both drain with
+     * `beacon: true`, the only delivery a closing document is guaranteed to
+     * complete.
+     */
+    private installUnloadFlush;
+    addBreadcrumb(crumb: Omit<Breadcrumb, 'timestamp'> & {
+        timestamp?: string;
+    }): void;
+    setUser(user: UserInfo | null): void;
+    setContext(key: string, value: unknown): void;
+    captureMessage(message: string, level?: Level): void;
+    /** Report an error. Never throws, never blocks. */
+    capture(error: unknown, extra?: {
+        handled?: boolean;
+        level?: Level;
+        type?: string;
+        context?: Record<string, unknown>;
+        request?: Record<string, unknown>;
+    }): void;
+    /** Flush anything queued. Await it before a process exits. */
+    flush(): Promise<void>;
+    /** Remove every hook the SDK installed. */
+    close(): void;
+    /** Adapters use this to report render timings alongside browser vitals. */
+    recordMetric(metric: VitalMetric): void;
+    private requestInfo;
+    private enqueue;
+    private drain;
+    private sendVitals;
+    private debug;
+}
+
+declare function parseStack(stack: unknown, limit?: number): StackFrame[];
+/**
+ * Normalise anything a JS app can throw into an error-shaped object.
+ * `throw 'a string'` and `Promise.reject({code: 500})` are both common; both
+ * must produce a usable event rather than "undefined".
+ */
+declare function normalizeError(input: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+};
+
+/**
+ * Deep-redact an object by key name. Depth-limited so a pathological structure
+ * cannot lock up the main thread.
+ */
+declare function redact<T>(value: T, extraKeys?: string[], depth?: number): T;
+/**
+ * Strip credentials out of a URL: query params named like secrets, plus any
+ * user:pass@ prefix. Returns the input unchanged if it cannot be parsed.
+ */
+declare function redactUrl(url: string, extraKeys?: string[]): string;
+
+/**
+ * Runtime detection and environment facts.
+ *
+ * Every lookup is defensive: this file runs in browsers, in Node, in edge
+ * runtimes, and during SSR where `window` exists but `document` does not.
+ * Nothing here may throw — a crash in environment detection would take down
+ * the host application on import, which is exactly the failure the PHP SDK
+ * learned to avoid the hard way.
+ */
+declare const SDK_NAME = "bugban-js";
+declare const SDK_VERSION = "1.0.0";
+/** 'browser' | 'node' | 'unknown' — reported on the install ping. */
+declare function runtimeName(): string;
+/**
+ * The runtime's own version: Node's `v22.13.1`, or the browser's UA string.
+ * The panel shows this next to the framework version, the same way it shows
+ * the PHP version for the PHP SDKs.
+ */
+declare function runtimeVersion(): string | undefined;
+/**
+ * Read a dependency's version out of the host app's node_modules, so an
+ * adapter can report "react 19.0.0" without importing react itself.
+ */
+declare function dependencyVersion(pkg: string): Promise<string | undefined>;
+
+declare function init(options?: BugbanOptions): BugbanClient;
+/** The active client, or null when init() has not been called. */
+declare function getClient(): BugbanClient | null;
+/**
+ * Every helper below is a no-op before init(). That is deliberate: a component
+ * that calls captureError must not crash because the app forgot to configure
+ * monitoring, or because it is running in a test.
+ */
+declare function capture(error: unknown, extra?: {
+    handled?: boolean;
+    level?: Level;
+    type?: string;
+    context?: Record<string, unknown>;
+}): void;
+declare function captureMessage(message: string, level?: Level): void;
+declare function setUser(user: UserInfo | null): void;
+declare function setContext(key: string, value: unknown): void;
+declare function addBreadcrumb(crumb: Omit<Breadcrumb, 'timestamp'> & {
+    timestamp?: string;
+}): void;
+declare function recordMetric(metric: VitalMetric): void;
+declare function flush(): Promise<void>;
+declare function close(): void;
+/**
+ * Namespace form, so `Bugban.capture(e)` reads the same as the PHP facade.
+ *
+ * Deliberately NOT also a default export: mixing default and named exports
+ * makes the CommonJS build require `.default`, which is exactly the kind of
+ * "works in one install shape, breaks in another" trap that took a customer's
+ * site down on the PHP side. One import style, everywhere:
+ *
+ *   import { Bugban } from '@bugban/js';
+ *   const { Bugban } = require('@bugban/js');
+ */
+declare const Bugban: {
+    VERSION: string;
+    init: typeof init;
+    getClient: typeof getClient;
+    capture: typeof capture;
+    captureMessage: typeof captureMessage;
+    setUser: typeof setUser;
+    setContext: typeof setContext;
+    addBreadcrumb: typeof addBreadcrumb;
+    recordMetric: typeof recordMetric;
+    flush: typeof flush;
+    close: typeof close;
+};
+
+export { type Breadcrumb, type BreadcrumbType, Bugban, BugbanClient, type BugbanEvent, type BugbanOptions, type ConsoleOptions, type Level, type NetworkOptions, SDK_NAME, SDK_VERSION, type Snapshot, type SnapshotOptions, type StackFrame, type UserInfo, type VitalMetric, type VitalsOptions, addBreadcrumb, capture, captureMessage, close, dependencyVersion, flush, getClient, init, normalizeError, parseStack, recordMetric, redact, redactUrl, runtimeName, runtimeVersion, setContext, setUser };