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 | null

try {
  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 | null

overseer.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";
}): void

overseer.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): void

overseer.setUser({
  id: "user_123",
  email: "[email protected]",
  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>;
  }
): void

overseer.trackVoiceCommand("navigate", {
  transcript: "go to the dashboard",
  confidence: 0.95,
  duration: 1200,
  result: "success",
  metadata: { page: "dashboard" },
});

trackMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): void

overseer.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 popstate events (breadcrumbs)
Tracks clicks as UI breadcrumbs (element tag, id, class, inner text)
Flushes on page unload via beforeunload
Creates incidents from errors when enableIncidents is true (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>;
}