Browser and desktop SDK client for error tracking, session replay, voice tracking, and incident creation
OverseerClient
The OverseerClient is the primary SDK for integrating Overseer into browser and desktop (Electron/Tauri) applications. It provides error tracking, session replay, voice command tracking, performance monitoring, and automatic incident creation for the self-healing loop.
Installation
import { OverseerClient, createOverseerClient, init } from "@codmir/overseer";Initialization
init(config: OverseerClientConfig): OverseerClient
Creates and stores a global client instance. Use this for most applications.
import { init } from "@codmir/overseer";
const overseer = init({
dsn: "https://api.codmir.com/overseer",
service: "web-app",
environment: "production",
apiKey: "osk_...",
projectId: "proj_abc123",
// Sampling
errorSampleRate: 1,
replaySampleRate: 0.1,
// Features
enableReplay: true,
enableVoiceTracking: true,
enablePerformance: true,
enableIncidents: true,
// Privacy
maskAllInputs: true,
maskSelectors: [".sensitive", "[data-private]"],
// Hooks
beforeSend: (event) => {
if (event.message.includes("ResizeObserver")) return null;
return event;
},
onIncidentCreated: (incident) => {
console.log(`Incident ${incident.code} created`);
},
});createOverseerClient(config: OverseerClientConfig): OverseerClient
Creates a standalone client instance without setting the global reference.
import { createOverseerClient } from "@codmir/overseer";
const client = createOverseerClient({
dsn: "https://api.codmir.com/overseer",
service: "desktop-app",
environment: "production",
});getClient(): OverseerClient | null
Returns the global client created by init(), or null if not initialized.
Configuration
OverseerClientConfig
| Property | Type | Default | Description |
|---|---|---|---|
dsn | string | required | API endpoint URL |
service | string | required | Service name (e.g., "web-app") |
environment | string | required | Environment ("production", "staging", etc.) |
release | string | undefined | Build version / release tag |
apiKey | string | undefined | API key for authenticating with the ingest endpoint (osk_...) |
projectId | string | undefined | Project ID for incident creation |
errorSampleRate | number | 1 | Error sampling rate (0-1) |
replaySampleRate | number | 0.1 | Session replay sampling rate (0-1) |
replayOnErrorSampleRate | number | 1 | Replay sample rate when an error occurs (0-1) |
enableReplay | boolean | true | Enable session replay recording |
enableVoiceTracking | boolean | true | Enable voice command tracking |
enablePerformance | boolean | false | Enable automatic Web Vitals tracking |
enableIncidents | boolean | true | Auto-create incidents from errors |
maskAllInputs | boolean | false | Mask all input values in replay |
maskSelectors | string[] | [] | CSS selectors to mask in replay |
maxBatchSize | number | 100 | Max events per flush batch |
flushInterval | number | 30000 | Flush interval in milliseconds |
beforeSend | (event: ErrorEvent) => ErrorEvent | null | identity | Hook to modify or drop events before sending |
onIncidentCreated | (incident: { id: string; code: string }) => void | undefined | Called when an incident is created from an error |
Error Tracking
captureError(error, options?): string | null
Captures an error and returns the event ID, or null if the event was sampled out or dropped by beforeSend.
captureError(
error: Error | string,
options?: {
level?: "fatal" | "error" | "warning" | "info" | "debug";
tags?: Record<string, string>;
extra?: Record<string, unknown>;
}
): string | nulltry {
await riskyOperation();
} catch (error) {
overseer.captureError(error, {
level: "error",
tags: { module: "checkout" },
extra: { cartId: "abc123" },
});
}captureMessage(message, level?): string | null
Captures a message event.
captureMessage(message: string, level?: "fatal" | "error" | "warning" | "info" | "debug"): string | nulloverseer.captureMessage("User completed checkout", "info");addBreadcrumb(breadcrumb): void
Adds a breadcrumb for context. Breadcrumbs are included with subsequent error events.
addBreadcrumb(breadcrumb: {
type?: string;
category?: string;
message?: string;
data?: Record<string, unknown>;
level?: "fatal" | "error" | "warning" | "info" | "debug";
}): voidoverseer.addBreadcrumb({
type: "navigation",
category: "route",
message: "/dashboard",
level: "info",
});setUser(user): void
Sets user context for all subsequent events.
setUser(user: { id?: string; email?: string; username?: string; ip_address?: string } | undefined): voidoverseer.setUser({
id: "user_123",
email: "user@example.com",
username: "jdoe",
});
// Clear user on logout
overseer.setUser(undefined);setTags(tags): void
Sets global tags included with all events.
overseer.setTags({ version: "2.1.0", region: "us-east-1" });setExtra(extra): void
Sets extra context data included with all events.
overseer.setExtra({ featureFlags: { newCheckout: true } });setConversationId(conversationId): void
Sets the conversation ID for correlating errors with AI chat sessions.
overseer.setConversationId("conv_abc123");getConversationId(): string | null
Returns the current conversation ID.
Session Replay
startReplay(): string | null
Starts session replay recording. Returns the replay session ID, or null if replay could not start.
const replayId = overseer.startReplay();stopReplay(): ReplaySession | null
Stops replay recording and returns the completed session.
const session = overseer.stopReplay();isReplayActive(): boolean
Returns whether replay is currently recording.
getReplaySessionId(): string | null
Returns the current replay session ID, or null if not recording.
Chrome extension offloading: When the Codmir Chrome extension is installed, replay recording is automatically offloaded to the extension. The extension maintains a 15-second DVR buffer and flushes it on error. The client detects the extension via a DOM marker or custom event and stops its in-process recorder.
Voice Command Tracking
trackVoiceCommand(command, options): void
Tracks a voice command execution. Automatically adds a breadcrumb and queues the event for sending. If the command failed, a warning message is also captured.
trackVoiceCommand(
command: string,
options: {
transcript: string;
confidence: number;
duration: number;
result?: "success" | "failure" | "partial";
errorMessage?: string;
metadata?: Record<string, unknown>;
}
): voidoverseer.trackVoiceCommand("navigate", {
transcript: "go to the dashboard",
confidence: 0.95,
duration: 1200,
result: "success",
metadata: { page: "dashboard" },
});startVoiceSession(): void
Marks the beginning of a continuous voice session.
endVoiceSession(): VoiceCommand[]
Ends the voice session and returns all commands recorded during it.
isVoiceSessionActive(): boolean
Returns whether a voice session is currently active.
Performance Tracking
trackMetric(name, value, unit?, tags?): void
Tracks a custom performance metric.
trackMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): voidoverseer.trackMetric("api_latency", 142, "ms", { endpoint: "/api/users" });timeOperation<T>(name, operation, tags?): Promise<T>
Times an async operation and records the duration as a metric.
const result = await overseer.timeOperation(
"fetch_users",
() => fetch("/api/users").then((r) => r.json()),
{ source: "dashboard" },
);When enablePerformance is true, the client automatically tracks:
- LCP (Largest Contentful Paint)
- FID (First Input Delay)
- CLS (Cumulative Layout Shift)
- TTFB (Time to First Byte)
- DOM Load and Page Load times
Lifecycle
flush(): Promise<void>
Immediately sends all queued events to the Overseer API. Error events are flushed immediately by default; other event types batch on the flushInterval.
await overseer.flush();close(): Promise<void>
Stops replay, disconnects the performance observer, flushes remaining events, and cleans up timers.
await overseer.close();Automatic Behaviors
The client automatically:
- Captures unhandled errors via
window.onerror - Captures unhandled promise rejections via
unhandledrejection - Tracks navigation via
popstateevents (breadcrumbs) - Tracks clicks as UI breadcrumbs (element tag, id, class, inner text)
- Flushes on page unload via
beforeunload - Creates incidents from errors when
enableIncidentsistrue(first occurrence per error group per session) - Starts replay on error if not already recording, based on
replayOnErrorSampleRate
Types
VoiceCommand
interface VoiceCommand {
id: string;
command: string;
transcript: string;
confidence: number;
timestamp: Date;
duration: number;
result?: "success" | "failure" | "partial";
errorMessage?: string;
metadata?: Record<string, unknown>;
}PerformanceMetric
interface PerformanceMetric {
name: string;
value: number;
unit: string;
timestamp: Date;
tags?: Record<string, string>;
}