@logspace/sdk 1.0.0

package/sdk/types.d.ts

@@ -0,0 +1,411 @@
+import { LogEntry, LogType, LogSeverity, SessionStats } from '../shared/types';
+import { eventWithTime } from 'rrweb';
+export type { LogEntry, LogType, LogSeverity, SessionStats };
+export type { NetworkLog, ConsoleLog, ErrorLog, InteractionLog, PerformanceLog, WebSocketLog, SSELog, StorageLog, AnnotationLog, } from '../shared/types';
+export type { eventWithTime };
+/**
+ * Recording type - determines replay format
+ */
+export type RecordingType = 'video' | 'rrweb';
+/**
+ * SDK Session state
+ */
+export interface SDKSession {
+    id: string;
+    startTime: number;
+    endTime?: number;
+    status: 'idle' | 'recording' | 'paused' | 'stopped';
+    userId?: string;
+    userTraits?: Record<string, any>;
+    metadata?: Record<string, any>;
+    stats: SessionStats;
+    url: string;
+    title: string;
+}
+/**
+ * Capture configuration - what to record
+ */
+export interface CaptureConfig {
+    /** Enable rrweb DOM recording for visual replay
+     * @default true
+     */
+    rrweb?: boolean;
+    /** Capture console logs (log, info, warn, error, debug)
+     * @default true
+     */
+    console?: boolean;
+    /** Capture network requests (XHR/Fetch)
+     * @default true
+     */
+    network?: boolean;
+    /** Capture JavaScript errors
+     * @default true
+     */
+    errors?: boolean;
+    /** Capture user interactions (clicks, inputs)
+     * @default true
+     */
+    interactions?: boolean;
+    /** Capture performance metrics
+     * @default true
+     */
+    performance?: boolean;
+    /** Capture WebSocket connections
+     * @default true
+     */
+    websocket?: boolean;
+    /** Capture Server-Sent Events
+     * @default true
+     */
+    sse?: boolean;
+    /** Capture localStorage/sessionStorage changes
+     * @default true
+     */
+    storage?: boolean;
+    /** Capture resource loading (CSS, JS, images, fonts)
+     * @default true
+     */
+    resources?: boolean;
+    /** Capture SPA route changes (History API, hash changes)
+     * @default true
+     */
+    spaNavigation?: boolean;
+}
+/**
+ * rrweb specific configuration
+ */
+export interface RRWebConfig {
+    /** Mask all text input values for privacy
+     * @default false
+     */
+    maskAllInputs?: boolean;
+    /** Mask text content matching these CSS selectors
+     * @default undefined
+     */
+    maskTextSelector?: string;
+    /** Block elements matching these CSS selectors from being recorded
+     * @default undefined
+     */
+    blockSelector?: string;
+    /** Ignore elements matching these CSS selectors
+     * @default undefined
+     */
+    ignoreSelector?: string;
+    /** Record canvas content (can be expensive)
+     * @default false
+     */
+    recordCanvas?: boolean;
+    /** Take a full DOM snapshot every N events
+     * @default 200
+     */
+    checkoutEveryNth?: number;
+}
+/**
+ * Privacy configuration
+ */
+export interface PrivacyConfig {
+    /** Mask PII patterns (emails, phones, SSN, credit cards)
+     * @default true
+     */
+    maskSensitiveData?: boolean;
+    /** CSS selectors to always mask
+     * @default []
+     */
+    maskSelectors?: string[];
+    /** URL patterns to exclude from logging (regex strings)
+     * @default []
+     */
+    excludeUrls?: string[];
+    /** Network URL patterns to block request/response bodies
+     * @default []
+     */
+    blockNetworkBodies?: string[];
+    /** Header names to always redact
+     * @default []
+     */
+    redactHeaders?: string[];
+    /** Console log levels to capture
+     * @default ['log', 'info', 'warn', 'error', 'debug']
+     */
+    logLevels?: LogSeverity[];
+}
+/**
+ * Session limits - protection against infinite loops and memory issues
+ */
+export interface SessionLimits {
+    /** Maximum logs per session before auto-ending
+     * @default 10000
+     */
+    maxLogs?: number;
+    /** Maximum session size in bytes before auto-ending
+     * @default 10485760 (10MB)
+     */
+    maxSize?: number;
+    /** Maximum session duration in seconds before auto-ending
+     * @default 300 (5 minutes)
+     */
+    maxDuration?: number;
+    /** Idle timeout in seconds - auto-end if no activity
+     * @default 30
+     */
+    idleTimeout?: number;
+    /** Navigate away timeout in seconds - grace period when tab becomes hidden
+     * Session only ends after this period of being hidden (like switching tabs)
+     * @default 120 (2 minutes)
+     */
+    navigateAwayTimeout?: number;
+    /** Rate limit - max logs per second (excess logs are dropped)
+     * @default 100
+     */
+    rateLimit?: number;
+    /** Deduplicate consecutive identical logs
+     * @default true
+     */
+    deduplicate?: boolean;
+}
+/**
+ * Session end triggers
+ */
+export interface SessionEndConfig {
+    /** Continue session across page refreshes instead of creating new sessions.
+     * When true, refreshing the page merges data into the same session.
+     * When false, each page load creates a new session.
+     * Note: Data is always saved to storage on page unload for reliability.
+     * @default true
+     */
+    continueOnRefresh?: boolean;
+    /** Auto-end session on idle timeout
+     * @default true
+     */
+    onIdle?: boolean;
+    /** Auto-end session when limits are reached
+     * @default true
+     */
+    onLimitReached?: boolean;
+}
+/**
+ * Sampling configuration - only record sessions when specific events occur
+ * When enabled, the SDK keeps a rolling buffer and only sends sessions when triggered
+ */
+export interface SamplingConfig {
+    /** Enable sampling mode - only send sessions when triggered by errors or custom events
+     * @default false
+     */
+    enabled?: boolean;
+    /** Seconds of logs to keep before the trigger event
+     * @default 15
+     */
+    bufferBefore?: number;
+    /** Seconds to continue recording after the trigger event
+     * @default 15
+     */
+    recordAfter?: number;
+    /** What triggers a session to be saved */
+    triggers?: {
+        /** Trigger on uncaught JavaScript errors
+         * @default true
+         */
+        onError?: boolean;
+        /** Trigger on console.error calls
+         * @default true
+         */
+        onConsoleError?: boolean;
+        /** Trigger on specific HTTP status codes (e.g., [500, 502, 503])
+         * @default [500, 502, 503, 504]
+         */
+        onNetworkStatus?: number[];
+    };
+}
+/**
+ * Lifecycle hooks
+ */
+export interface HooksConfig {
+    /** Called on every captured action
+     * @default undefined
+     */
+    onAction?: (log: LogEntry, session: SDKSession) => void;
+    /** Transform/filter logs before sending - return null to drop all logs
+     * @default undefined
+     */
+    beforeSend?: (logs: LogEntry[]) => LogEntry[] | null;
+    /** Called when session starts
+     * @default undefined
+     */
+    onSessionStart?: (session: SDKSession) => void;
+    /** Called when session ends
+     * @default undefined
+     */
+    onSessionEnd?: (session: SDKSession, logs: LogEntry[]) => void;
+    /** Called when session auto-ends due to limits
+     * @default undefined
+     */
+    onLimitReached?: (reason: 'maxLogs' | 'maxSize' | 'maxDuration' | 'idle') => void;
+    /** Called when sampling is triggered (error detected)
+     * @default undefined
+     */
+    onSamplingTrigger?: (trigger: 'error' | 'consoleError' | 'networkError' | 'manual', log?: LogEntry) => void;
+    /** Called on transport/network errors
+     * @default undefined
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Main SDK configuration - all fields are optional
+ */
+export interface LogSpaceConfig {
+    /** Server URL for sending sessions. If not provided, sessions are stored locally only.
+     * @default undefined
+     */
+    serverUrl?: string;
+    /** API key in format 'project_id:environment_id' for authentication
+     * @default undefined
+     */
+    apiKey?: string;
+    /** Configure what to capture (console, network, errors, etc.)
+     * @default All capture options enabled (true)
+     */
+    capture?: CaptureConfig;
+    /** rrweb DOM recording settings
+     * @default { maskAllInputs: false, recordCanvas: false, checkoutEveryNth: 200 }
+     */
+    rrweb?: RRWebConfig;
+    /** Privacy settings for masking sensitive data
+     * @default { maskSensitiveData: true, maskSelectors: [], excludeUrls: [], blockNetworkBodies: [], redactHeaders: [], logLevels: ['log', 'info', 'warn', 'error', 'debug'] }
+     */
+    privacy?: PrivacyConfig;
+    /** Session limits for protection against memory issues
+     * @default { maxLogs: 10000, maxSize: 10485760, maxDuration: 300, idleTimeout: 30, rateLimit: 100, deduplicate: true }
+     */
+    limits?: SessionLimits;
+    /** Configure when to auto-end sessions
+     * @default { continueOnRefresh: true, onIdle: true, onLimitReached: true }
+     */
+    autoEnd?: SessionEndConfig;
+    /** Sampling configuration - only save sessions when errors occur
+     * When enabled, keeps a rolling buffer and only sends when triggered by errors
+     * @default { enabled: false }
+     */
+    sampling?: SamplingConfig;
+    /** Lifecycle hooks for customizing behavior
+     * @default All hooks undefined
+     */
+    hooks?: HooksConfig;
+    /** Custom headers to include in API requests
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /** Enable debug logging to console
+     * @default false
+     */
+    debug?: boolean;
+    /** Dry run mode - log payload instead of sending (for testing)
+     * @default false
+     */
+    dryRun?: boolean;
+}
+/**
+ * Normalized config with all defaults applied
+ */
+export interface NormalizedConfig {
+    serverUrl?: string;
+    apiKey?: string;
+    capture: Required<CaptureConfig>;
+    rrweb: RRWebConfig;
+    privacy: Required<PrivacyConfig>;
+    limits: Required<SessionLimits>;
+    autoEnd: Required<SessionEndConfig>;
+    sampling: Required<Omit<SamplingConfig, 'triggers'>> & {
+        triggers: Required<NonNullable<SamplingConfig['triggers']>>;
+    };
+    hooks: HooksConfig;
+    headers: Record<string, string>;
+    debug: boolean;
+    dryRun: boolean;
+}
+/**
+ * Session payload sent to server
+ */
+export interface SessionPayload {
+    id: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    url: string;
+    title: string;
+    userId?: string;
+    userTraits?: Record<string, any>;
+    metadata?: Record<string, any>;
+    logs: LogEntry[];
+    stats: SessionStats;
+    endReason: 'manual' | 'unload' | 'idle' | 'navigateAway' | 'maxLogs' | 'maxSize' | 'maxDuration' | 'samplingTriggered' | 'crash';
+    /** Recording type - 'rrweb' for SDK, 'video' for extension */
+    recordingType: RecordingType;
+    /** rrweb DOM events for visual replay (SDK only) */
+    rrwebEvents?: eventWithTime[];
+    /** What triggered the sampling (only present when sampling is enabled) */
+    samplingTrigger?: 'error' | 'consoleError' | 'networkError' | 'manual';
+    /** User agent string */
+    userAgent?: string;
+    /** SDK version */
+    sdkVersion?: string;
+}
+/**
+ * Public SDK interface
+ */
+export interface LogSpaceSDK {
+    /** Initialize the SDK */
+    init(config: LogSpaceConfig): void;
+    /** Identify user */
+    identify(userId: string, traits?: Record<string, any>): void;
+    /** Track custom event */
+    track(event: string, properties?: Record<string, any>): void;
+    /** Add breadcrumb */
+    breadcrumb(message: string, category?: string): void;
+    /** Start recording session */
+    startSession(metadata?: Record<string, any>): void;
+    /** Stop recording session and send to server */
+    stopSession(): Promise<void>;
+    /** Pause recording */
+    pauseRecording(): void;
+    /** Resume recording */
+    resumeRecording(): void;
+    /** Get current session */
+    getSession(): SDKSession | null;
+    /** Get all logs for current session */
+    getSessionLogs(): LogEntry[];
+    /** Get session data (for local export without server) */
+    getSessionData(): SessionPayload | null;
+    /** Destroy SDK and cleanup */
+    destroy(): void;
+}
+/**
+ * Plugin interface for extending SDK
+ */
+export interface LogSpacePlugin {
+    name: string;
+    setup(sdk: LogSpaceSDK, config: NormalizedConfig): void;
+    teardown?(): void;
+}
+/**
+ * Internal capture handler type
+ * Accepts partial log data, SDK adds id/timestamp/tabId/tabUrl
+ */
+export type CaptureHandler = (log: {
+    type: LogEntry['type'];
+    data: any;
+    severity?: LogEntry['severity'];
+}) => void;
+/**
+ * Rate limiter state
+ */
+export interface RateLimiterState {
+    count: number;
+    windowStart: number;
+}
+/**
+ * Deduplication state
+ */
+export interface DeduplicationState {
+    lastLogHash: string | null;
+    lastLogCount: number;
+}

package/shared/browser-detection.d.ts

@@ -0,0 +1,38 @@
+import { default as Browser } from 'webextension-polyfill';
+/**
+ * Cross-browser API namespace
+ * Uses webextension-polyfill for Firefox/Safari compatibility
+ * Falls back to chrome namespace if polyfill not available
+ */
+export declare const browser: typeof Browser;
+export interface BrowserCapabilities {
+    hasTabCapture: boolean;
+    hasDisplayMedia: boolean;
+    hasOffscreenDocuments: boolean;
+    hasMediaRecorder: boolean;
+    recommendedMode: 'auto' | 'fullscreen' | 'custom';
+    browserName: string;
+    isChromium: boolean;
+}
+/**
+ * Detect browser capabilities
+ */
+export declare function detectBrowserCapabilities(): BrowserCapabilities;
+/**
+ * Get user-friendly description for capture mode
+ */
+export declare function getCaptureModeDescription(mode: 'auto' | 'fullscreen' | 'custom'): string;
+/**
+ * Check if a capture mode is available in current browser
+ */
+export declare function isCaptureModeAvailable(mode: 'auto' | 'fullscreen' | 'custom'): boolean;
+/**
+ * Get list of available capture modes for UI
+ */
+export declare function getAvailableCaptureModes(): Array<{
+    mode: 'auto' | 'fullscreen' | 'custom';
+    label: string;
+    description: string;
+    icon: string;
+    available: boolean;
+}>;

package/shared/displayMediaCapture.d.ts

@@ -0,0 +1,23 @@
+import { CaptureMode } from './types';
+export interface DisplayMediaOptions {
+    mode: 'fullscreen' | 'tab' | 'custom';
+    preferCurrentTab?: boolean;
+    frameRate?: number;
+    videoQuality?: 'low' | 'medium' | 'high';
+}
+/**
+ * Request display media capture from user
+ * This must be called from a user gesture (e.g., button click)
+ */
+export declare function requestDisplayMedia(options: DisplayMediaOptions): Promise<MediaStream>;
+/**
+ * Transfer MediaStream to offscreen for recording
+ * Since we can't serialize MediaStream, we'll use a different approach:
+ * Store the stream globally and let offscreen access it
+ */
+export declare function transferStreamToBackground(stream: MediaStream, sessionId: string, mode: CaptureMode): Promise<void>;
+/**
+ * Alternative: Create offscreen document to handle getDisplayMedia
+ * This avoids stream transfer issues by letting offscreen handle everything
+ */
+export declare function requestOffscreenDisplayMedia(sessionId: string, mode: 'fullscreen' | 'tab' | 'custom'): Promise<void>;

package/shared/export.d.ts

@@ -0,0 +1,15 @@
+import { RecordingSession } from './types';
+/**
+ * Export session data as a .zip file containing:
+ * - session.json: Session metadata and logs (compressed)
+ * - video.webm: Recorded video (if available)
+ */
+export declare function exportSession(session: RecordingSession): Promise<void>;
+/**
+ * Export session as separate JSON file (no video)
+ */
+export declare function exportSessionJSON(session: RecordingSession): Promise<void>;
+/**
+ * Export video only
+ */
+export declare function exportSessionVideo(sessionId: string): Promise<void>;

package/shared/log-optimizer.d.ts

@@ -0,0 +1,47 @@
+import { LogEntry } from './types';
+/**
+ * Optimized log entry for storage (normalized)
+ */
+export interface OptimizedLogEntry {
+    id: string;
+    ts: number;
+    type: string;
+    data: any;
+    sev?: string;
+}
+/**
+ * Session context stored once per session
+ */
+export interface SessionContext {
+    id: string;
+    startTime: number;
+    tabs: Record<number, TabContext>;
+}
+/**
+ * Tab context stored once per tab
+ */
+export interface TabContext {
+    url: string;
+    title: string;
+    startTime: number;
+}
+/**
+ * Optimize log entry for storage
+ * Removes redundant fields that can be inferred from context
+ */
+export declare function optimizeLog(log: LogEntry, sessionId: string): OptimizedLogEntry;
+/**
+ * Denormalize log entry for export/usage
+ * Restores the full LogEntry structure with context
+ */
+export declare function denormalizeLog(optimized: OptimizedLogEntry | any, // Accept any to handle stored format
+sessionId: string, tabId: number, tabUrl: string): LogEntry;
+/**
+ * Calculate storage savings
+ */
+export declare function calculateSavings(original: LogEntry[], optimized: OptimizedLogEntry[]): {
+    originalSize: number;
+    optimizedSize: number;
+    savingsBytes: number;
+    savingsPercent: number;
+};