@logspace/sdk 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@logspace/sdk",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"description": "LogSpace JavaScript SDK for session recording and logging",
 	"type": "module",
 	"main": "./logspace.umd.js",
@@ -19,7 +19,6 @@
 		}
 	},
 	"files": [
-		"README.md",
 		"logspace.esm.js",
 		"logspace.esm.js.map",
 		"logspace.umd.js",
@@ -38,5 +37,8 @@
 		"monitoring"
 	],
 	"author": "LogSpace",
-	"license": "MIT"
+	"license": "MIT",
+	"scripts": {
+		"preinstall": "npx only-allow bun && bun --version | grep -q '^1.2.21$' || (echo 'Error: Bun version 1.2.21 is required' && exit 1)"
+	}
 }

package/sdk/capture/base.d.ts

@@ -1,7 +1,7 @@
 import { LogEntry, LogType } from '../../shared/types';
 import { CaptureHandler, PrivacyConfig } from '../types';
-import { generateId, safeStringify, maskSensitiveData, maskHeaders } from '../../shared/utils';
-export { generateId, safeStringify, maskSensitiveData, maskHeaders };
+import { generateId, safeStringify, maskSensitiveData, maskHeaders, maskConsoleArgs } from '../../shared/utils';
+export { generateId, safeStringify, maskSensitiveData, maskHeaders, maskConsoleArgs };
 /**
  * Check if running in browser environment (SSR safety)
  */
@@ -39,7 +39,9 @@ export declare function applyPrivacy(log: LogEntry, privacy: PrivacyConfig): Log
  */
 export interface CaptureModule {
     name: string;
-    install(handler: CaptureHandler, privacy: PrivacyConfig): void;
+    install(handler: CaptureHandler, privacy: PrivacyConfig, onActivity?: () => void, limits?: {
+        maxNetworkBodySize?: number;
+    }): void;
     uninstall(): void;
     reset?(): void;
 }

package/sdk/capture/sse.d.ts

@@ -1,5 +1,2 @@
 import { CaptureModule } from './base';
-/**
- * SSE capture module
- */
 export declare const sseCapture: CaptureModule;

package/sdk/capture/websocket.d.ts

@@ -1,5 +1,2 @@
 import { CaptureModule } from './base';
-/**
- * WebSocket capture module
- */
 export declare const websocketCapture: CaptureModule;

package/sdk/index.d.ts

@@ -1,9 +1,10 @@
 import { LogEntry } from '../shared/types';
-import { LogSpaceConfig, SDKSession, SessionPayload } from './types';
+import { LogSpaceConfig, NormalizedConfig, SDKSession, SessionPayload } from './types';
 import { eventWithTime } from './capture/rrweb';
 export declare const LogSpace: {
     /**
      * Initialize the SDK
+     * @throws Error if SDK is already initialized
      */
     init(userConfig: LogSpaceConfig): void;
     /**
@@ -16,6 +17,7 @@ export declare const LogSpace: {
     stopSession(): Promise<void>;
     /**
      * Identify user
+     * If called before session starts, the identity will be queued and applied when session starts
      */
     identify(userId: string, traits?: Record<string, any>): void;
     /**
@@ -55,6 +57,28 @@ export declare const LogSpace: {
      * Get rrweb events for current session
      */
     getRRWebEvents(): eventWithTime[];
+    /**
+     * Get current configuration (read-only)
+     * Returns the full NormalizedConfig plus convenience top-level fields
+     * that match the setConfig() interface for easy verification
+     */
+    getConfig(): (NormalizedConfig & {
+        rateLimit: number;
+        maxLogs: number;
+        maxSize: number;
+        idleTimeout: number;
+    }) | null;
+    /**
+     * Update configuration at runtime
+     * Only certain settings can be changed after initialization
+     */
+    setConfig(updates: {
+        rateLimit?: number;
+        maxLogs?: number;
+        maxSize?: number;
+        idleTimeout?: number;
+        debug?: boolean;
+    }): void;
     /**
      * Destroy SDK
      */

package/sdk/storage/indexed-db.d.ts

@@ -45,6 +45,10 @@ export declare function getCurrentSessionBackup(): Promise<CurrentSessionBackup
  * Clear current session backup (called after successful send)
  */
 export declare function clearCurrentSessionBackup(): Promise<void>;
+/**
+ * Clear current session backup only if it matches the provided session ID
+ */
+export declare function clearCurrentSessionBackupFor(sessionId: string): Promise<void>;
 /**
  * Add a session to pending queue (for retry later)
  */

package/sdk/types.d.ts

@@ -12,6 +12,7 @@ export type RecordingType = 'video' | 'rrweb';
  */
 export interface SDKSession {
     id: string;
+    tabId: string;
     startTime: number;
     endTime?: number;
     status: 'idle' | 'recording' | 'paused' | 'stopped';
@@ -96,7 +97,7 @@ export interface RRWebConfig {
      */
     recordCanvas?: boolean;
     /** Take a full DOM snapshot every N events
-     * @default 200
+     * @default 150
      */
     checkoutEveryNth?: number;
 }
@@ -146,7 +147,7 @@ export interface SessionLimits {
      */
     maxDuration?: number;
     /** Idle timeout in seconds - auto-end if no activity
-     * @default 30
+     * @default 120
      */
     idleTimeout?: number;
     /** Navigate away timeout in seconds - grace period when tab becomes hidden
@@ -162,6 +163,10 @@ export interface SessionLimits {
      * @default true
      */
     deduplicate?: boolean;
+    /** Maximum size for network request/response bodies in bytes
+     * @default 10240 (10KB)
+     */
+    maxNetworkBodySize?: number;
 }
 /**
  * Session end triggers
@@ -193,11 +198,11 @@ export interface SamplingConfig {
      */
     enabled?: boolean;
     /** Seconds of logs to keep before the trigger event
-     * @default 15
+     * @default 30
      */
     bufferBefore?: number;
     /** Seconds to continue recording after the trigger event
-     * @default 15
+     * @default 30
      */
     recordAfter?: number;
     /** What triggers a session to be saved */
@@ -244,6 +249,10 @@ export interface HooksConfig {
      * @default undefined
      */
     onSamplingTrigger?: (trigger: 'error' | 'consoleError' | 'networkError' | 'manual', log?: LogEntry) => void;
+    /** Called when a sampling session is discarded (no trigger occurred)
+     * @default undefined
+     */
+    onSessionDiscarded?: (session: SDKSession, reason: 'noTrigger' | 'idle' | 'maxDuration' | 'manual') => void;
     /** Called on transport/network errors
      * @default undefined
      */
@@ -266,7 +275,7 @@ export interface LogSpaceConfig {
      */
     capture?: CaptureConfig;
     /** rrweb DOM recording settings
-     * @default { maskAllInputs: false, recordCanvas: false, checkoutEveryNth: 200 }
+     * @default { maskAllInputs: false, recordCanvas: false, checkoutEveryNth: 150 }
      */
     rrweb?: RRWebConfig;
     /** Privacy settings for masking sensitive data
@@ -274,7 +283,7 @@ export interface LogSpaceConfig {
      */
     privacy?: PrivacyConfig;
     /** Session limits for protection against memory issues
-     * @default { maxLogs: 10000, maxSize: 10485760, maxDuration: 300, idleTimeout: 30, rateLimit: 100, deduplicate: true }
+     * @default { maxLogs: 10000, maxSize: 10485760, maxDuration: 1800, idleTimeout: 120, rateLimit: 100, deduplicate: true }
      */
     limits?: SessionLimits;
     /** Configure when to auto-end sessions

package/shared/types.d.ts

@@ -11,6 +11,7 @@ export interface RecordingSession {
     cspBlocked?: boolean;
     title?: string;
     comment?: string;
+    videoStartTime?: number;
 }
 export interface TabRecording {
     tabId: number;
@@ -233,8 +234,17 @@ export interface RecordingSettings {
     excludeDomains: string[];
     maskSensitiveData: boolean;
     logLevels: LogSeverity[];
+    maxNetworkBodySize: number;
 }
 export declare const DEFAULT_SETTINGS: RecordingSettings;
+export declare const API_TO_SETTINGS_KEY_MAP: Record<string, keyof RecordingSettings>;
+export interface RemoteSettingsState {
+    disabledKeys: Set<keyof RecordingSettings>;
+    lastFetched: number | null;
+    loading: boolean;
+    error: string | null;
+}
+export declare function parseApiSettingValue(apiKey: string, value: string, valueType: string): any;
 export interface SessionStats {
     logCount: number;
     networkLogCount: number;
@@ -300,6 +310,101 @@ export declare enum MessageType {
     CSP_DETECTED = "CSP_DETECTED",// CSP blocked script injection
     FETCH_ASSIGNED_LOGS = "FETCH_ASSIGNED_LOGS"
 }
+/**
+ * Internal message types used for communication between extension components
+ * These are not part of the public MessageType enum to avoid bloating it
+ *
+ * MESSAGE FLOW DOCUMENTATION:
+ *
+ * Background Script <-> Content Script:
+ * - REGISTER_TAB: Background registers a tab for recording
+ * - UNREGISTER_TAB: Background unregisters a tab
+ * - SHOW_COUNTDOWN: Background asks content to show countdown overlay
+ * - SELECT_AREA: Background asks content to show area selector
+ * - AREA_SELECTED: Content informs background of selected area
+ * - NETWORK_HEADERS_*: Background forwards network headers to content
+ * - show-webcam-overlay / hide-webcam-overlay: Webcam control
+ * - SAVE_ANNOTATION / SAVE_DRAWING_ANNOTATION: User annotations
+ * - STORAGE_SIZE_UPDATE: Background informs content of storage usage
+ * - SHOW_SAVE_MODAL / UPDATE_SAVE_MODAL_VIDEO: Save dialog control
+ *
+ * Background Script <-> Offscreen Document:
+ * - start-video-recording / stop-video-recording: Video recording control
+ * - start-display-media-recording: Screen capture control
+ * - test-microphone-permission / test-webcam-permission: Permission tests
+ * - start-microphone-visualization / stop-microphone-visualization: Audio levels
+ * - save-video: Offscreen sends video data to background
+ * - video-chunk-size: Offscreen reports chunk sizes
+ * - offscreen-log: Offscreen forwards logs to background
+ * - display-media-selected: User selected screen/window
+ * - microphone-audio-level: Audio visualization data
+ *
+ * Background Script <-> Popup:
+ * - CLOSE_POPUP: Background requests popup to close
+ * - RECORDING_STARTED / RECORDING_ERROR: Recording state notifications
+ * - All MessageType and AuthMessageType enums
+ */
+export declare enum InternalMessageType {
+    PING = "ping",
+    GET_TAB_ID = "GET_TAB_ID",
+    CANCEL_AREA_SELECTION = "CANCEL_AREA_SELECTION",
+    SHOW_COUNTDOWN = "SHOW_COUNTDOWN",
+    COUNTDOWN_COMPLETE = "COUNTDOWN_COMPLETE",
+    SELECT_AREA = "SELECT_AREA",
+    AREA_SELECTED = "AREA_SELECTED",
+    AREA_SELECTION_CANCELLED = "AREA_SELECTION_CANCELLED",
+    NETWORK_HEADERS_REQUEST = "NETWORK_HEADERS_REQUEST",
+    NETWORK_HEADERS_RESPONSE = "NETWORK_HEADERS_RESPONSE",
+    SHOW_WEBCAM_OVERLAY = "show-webcam-overlay",
+    HIDE_WEBCAM_OVERLAY = "hide-webcam-overlay",
+    SAVE_ANNOTATION = "SAVE_ANNOTATION",
+    SAVE_DRAWING_ANNOTATION = "SAVE_DRAWING_ANNOTATION",
+    STORAGE_SIZE_UPDATE = "STORAGE_SIZE_UPDATE",
+    SHOW_SAVE_MODAL = "SHOW_SAVE_MODAL",
+    UPDATE_SAVE_MODAL_VIDEO = "UPDATE_SAVE_MODAL_VIDEO",
+    START_VIDEO_RECORDING = "start-video-recording",
+    STOP_VIDEO_RECORDING = "stop-video-recording",
+    START_DISPLAY_MEDIA_RECORDING = "start-display-media-recording",
+    TEST_MICROPHONE_PERMISSION = "test-microphone-permission",
+    TEST_WEBCAM_PERMISSION = "test-webcam-permission",
+    START_MICROPHONE_VISUALIZATION = "start-microphone-visualization",
+    STOP_MICROPHONE_VISUALIZATION = "stop-microphone-visualization",
+    SAVE_VIDEO = "save-video",
+    VIDEO_CHUNK_SIZE = "video-chunk-size",
+    OFFSCREEN_LOG = "offscreen-log",
+    DISPLAY_MEDIA_SELECTED = "display-media-selected",
+    MICROPHONE_AUDIO_LEVEL = "microphone-audio-level",
+    BEGIN_MEDIA_RECORDING = "begin-media-recording",
+    VIDEO_RECORDING_STARTED = "video-recording-started",
+    SCREEN_SHARE_ENDED = "screen-share-ended",// User clicked browser's "Stop sharing" button
+    CLOSE_POPUP = "CLOSE_POPUP",
+    RECORDING_STARTED = "RECORDING_STARTED",
+    RECORDING_ERROR = "RECORDING_ERROR",
+    LOGIN_SUCCESS = "LOGIN_SUCCESS",
+    LOGIN_FAILED = "LOGIN_FAILED",
+    STATE_UPDATE = "STATE_UPDATE",
+    LOG_UPDATE = "LOG_UPDATE",
+    SAVE_RECORDING_METADATA = "SAVE_RECORDING_METADATA",
+    GET_SESSION_LOGS = "GET_SESSION_LOGS",
+    GET_UPLOAD_FORM_DATA = "GET_UPLOAD_FORM_DATA",
+    SEARCH_PROJECTS = "SEARCH_PROJECTS",
+    SEARCH_ENVIRONMENTS = "SEARCH_ENVIRONMENTS",
+    SEARCH_USERS = "SEARCH_USERS",
+    UPLOAD_RECORDING = "UPLOAD_RECORDING",
+    CONNECT = "CONNECT"
+}
+/**
+ * Validate that a message has a valid type
+ * @param message The message to validate
+ * @returns true if the message has a valid type property
+ */
+export declare function isValidMessage(message: unknown): boolean;
+/**
+ * Check if a message type is a known type
+ * @param type The message type to check
+ * @returns true if the type is in MessageType, AuthMessageType, or InternalMessageType
+ */
+export declare function isKnownMessageType(type: string): boolean;
 export interface Message {
     type: MessageType;
     payload?: any;
@@ -323,6 +428,7 @@ export interface StatusResponse {
     session: RecordingSession | null;
     error?: string;
     auth?: AuthState;
+    recordedTabIds?: number[];
 }
 export interface CspDetectedMessage extends Message {
     type: MessageType.CSP_DETECTED;
@@ -352,5 +458,6 @@ export interface AuthPollingState {
 export declare enum AuthMessageType {
     LOGIN_START = "LOGIN_START",
     LOGOUT = "LOGOUT",
-    VALIDATE_AUTH = "VALIDATE_AUTH"
+    VALIDATE_AUTH = "VALIDATE_AUTH",
+    SYNC_SETTINGS = "SYNC_SETTINGS"
 }

package/shared/utils.d.ts

@@ -27,10 +27,17 @@ export declare function safeStringify(value: any): string;
  * Mask sensitive data in strings for privacy protection
  */
 export declare function maskSensitiveData(text: string): string;
+/**
+ * Mask console arguments, handling the case where label and value are separate args
+ * e.g., console.log("Password:", "secret") produces ["Password:", "secret"]
+ */
+export declare function maskConsoleArgs(args: string[]): string[];
 /**
  * Mask sensitive data in HTTP headers for privacy protection
+ * @param headers - The headers object to mask
+ * @param additionalHeaders - Additional header names to redact (from config.privacy.redactHeaders)
  */
-export declare function maskHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function maskHeaders(headers: Record<string, string>, additionalHeaders?: string[]): Record<string, string>;
 /**
  * Check if a URL matches any of the excluded domain patterns
  * Supports regex patterns for flexible matching

package/README.md

@@ -1,269 +0,0 @@
-# @logspace/sdk
-
-A lightweight JavaScript SDK for session recording and debugging. Capture user sessions with DOM replay, console logs, network requests, errors, and more.
-
-## Installation
-
-```bash
-npm install @logspace/sdk
-```
-
-```bash
-yarn add @logspace/sdk
-```
-
-```bash
-pnpm add @logspace/sdk
-```
-
-## Quick Start
-
-```javascript
-import LogSpace from '@logspace/sdk';
-
-// Initialize the SDK
-LogSpace.init({
-	serverUrl: 'https://your-logspace-server.com',
-	apiKey: 'project_id:environment_id',
-});
-
-// Start recording
-LogSpace.startSession();
-
-// Identify the user (optional)
-LogSpace.identify('user-123', {
-	email: 'user@example.com',
-	plan: 'pro',
-});
-
-// Track custom events
-LogSpace.track('button_clicked', { buttonId: 'submit' });
-
-// Add breadcrumbs for debugging
-LogSpace.breadcrumb('User opened settings', 'navigation');
-
-// Stop recording and send to server
-await LogSpace.stopSession();
-```
-
-## Features
-
-- 🎬 **DOM Recording** - Full visual replay using rrweb
-- 📝 **Console Logs** - Capture all console output (log, warn, error, debug)
-- 🌐 **Network Requests** - Track XHR and Fetch calls with timing
-- ❌ **Error Tracking** - Catch JavaScript errors and unhandled rejections
-- 🖱️ **User Interactions** - Record clicks, inputs, and scrolls
-- 📊 **Performance Metrics** - Core Web Vitals and resource timing
-- 🔌 **WebSocket & SSE** - Monitor real-time connections
-- 💾 **Storage Changes** - Track localStorage/sessionStorage modifications
-- 🔒 **Privacy First** - Built-in PII masking and data sanitization
-
-## Configuration
-
-```javascript
-LogSpace.init({
-	// Server configuration
-	serverUrl: 'https://your-server.com',
-	apiKey: 'project_id:environment_id',
-
-	// What to capture
-	capture: {
-		rrweb: true, // DOM recording
-		console: true, // Console logs
-		network: true, // Network requests
-		errors: true, // JavaScript errors
-		interactions: true, // User interactions
-		performance: true, // Performance metrics
-		websocket: true, // WebSocket connections
-		sse: true, // Server-Sent Events
-		storage: true, // localStorage/sessionStorage
-		resources: true, // Resource loading
-		spaNavigation: true, // SPA route changes
-	},
-
-	// rrweb settings
-	rrweb: {
-		maskAllInputs: false, // Mask all input values
-		maskTextSelector: null, // CSS selector for text masking
-		blockSelector: null, // CSS selector to block elements
-		recordCanvas: false, // Record canvas content
-		checkoutEveryNth: 200, // Full snapshot interval
-	},
-
-	// Privacy settings
-	privacy: {
-		maskSensitiveData: true, // Auto-mask PII patterns
-		maskSelectors: [], // CSS selectors to mask
-		excludeUrls: [], // URL patterns to exclude
-		blockNetworkBodies: [], // Block request/response bodies
-		redactHeaders: [], // Headers to redact
-		logLevels: ['log', 'info', 'warn', 'error', 'debug'],
-	},
-
-	// Session limits
-	limits: {
-		maxLogs: 10000, // Max logs per session
-		maxSize: 10 * 1024 * 1024, // Max session size (10MB)
-		maxDuration: 300, // Max duration in seconds (5 min)
-		idleTimeout: 30, // Idle timeout in seconds
-		rateLimit: 100, // Max logs per second
-		deduplicate: true, // Deduplicate consecutive logs
-	},
-
-	// Auto-end behavior
-	autoEnd: {
-		continueOnRefresh: true, // Continue session on page refresh
-		onIdle: true, // End on idle timeout
-		onLimitReached: true, // End when limits reached
-	},
-
-	// Sampling mode (only record on errors)
-	sampling: {
-		enabled: false,
-		bufferBefore: 15, // Seconds before trigger
-		recordAfter: 15, // Seconds after trigger
-		triggers: {
-			onError: true,
-			onConsoleError: true,
-			onNetworkStatus: [500, 502, 503, 504],
-		},
-	},
-
-	// Lifecycle hooks
-	hooks: {
-		onAction: (log, session) => {},
-		beforeSend: (logs) => logs,
-		onSessionStart: (session) => {},
-		onSessionEnd: (session, logs) => {},
-		onLimitReached: (reason) => {},
-		onSamplingTrigger: (trigger, log) => {},
-		onError: (error) => {},
-	},
-
-	// Additional options
-	headers: {}, // Custom API headers
-	debug: false, // Enable debug logging
-});
-```
-
-## API Reference
-
-### Initialization
-
-#### `LogSpace.init(config)`
-
-Initialize the SDK with configuration options.
-
-### Session Control
-
-#### `LogSpace.startSession(metadata?)`
-
-Start a new recording session with optional metadata.
-
-```javascript
-LogSpace.startSession({ page: 'checkout', variant: 'A' });
-```
-
-#### `LogSpace.stopSession()`
-
-Stop recording and send the session to the server.
-
-```javascript
-await LogSpace.stopSession();
-```
-
-#### `LogSpace.pauseRecording()`
-
-Temporarily pause recording.
-
-#### `LogSpace.resumeRecording()`
-
-Resume a paused recording.
-
-### User Identification
-
-#### `LogSpace.identify(userId, traits?)`
-
-Associate the session with a user.
-
-```javascript
-LogSpace.identify('user-123', {
-	email: 'user@example.com',
-	name: 'John Doe',
-	plan: 'enterprise',
-});
-```
-
-### Custom Events
-
-#### `LogSpace.track(event, properties?)`
-
-Track a custom event.
-
-```javascript
-LogSpace.track('purchase_completed', {
-	orderId: 'ORD-123',
-	amount: 99.99,
-});
-```
-
-#### `LogSpace.breadcrumb(message, category?)`
-
-Add a breadcrumb for debugging context.
-
-```javascript
-LogSpace.breadcrumb('User clicked add to cart', 'action');
-```
-
-### Sampling Mode
-
-#### `LogSpace.trigger(reason?)`
-
-Manually trigger session capture in sampling mode.
-
-```javascript
-LogSpace.trigger('user_reported_issue');
-```
-
-### Session Data
-
-#### `LogSpace.getSession()`
-
-Get the current session object.
-
-#### `LogSpace.getSessionLogs()`
-
-Get all logs for the current session.
-
-#### `LogSpace.getSessionData()`
-
-Get full session payload for local export.
-
-#### `LogSpace.getRRWebEvents()`
-
-Get rrweb events for the current session.
-
-### Cleanup
-
-#### `LogSpace.destroy()`
-
-Destroy the SDK and clean up resources.
-
-## Usage Formats
-
-The SDK supports multiple module formats:
-
-- **ESM**: `import LogSpace from '@logspace/sdk'`
-- **CommonJS**: `const LogSpace = require('@logspace/sdk')`
-- **IIFE**: `<script src="logspace.iife.js"></script>` (exposes `window.LogSpace`)
-
-## Browser Support
-
-- Chrome 60+
-- Firefox 55+
-- Safari 12+
-- Edge 79+
-
-## License
-
-MIT