@logspace/sdk 1.0.0

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@logspace/sdk",
+	"version": "1.0.0",
+	"description": "LogSpace JavaScript SDK for session recording and logging",
+	"type": "module",
+	"main": "./logspace.umd.js",
+	"module": "./logspace.esm.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./index.d.ts",
+				"default": "./logspace.esm.js"
+			},
+			"require": {
+				"types": "./index.d.ts",
+				"default": "./logspace.umd.js"
+			}
+		}
+	},
+	"files": [
+		"logspace.esm.js",
+		"logspace.esm.js.map",
+		"logspace.umd.js",
+		"logspace.umd.js.map",
+		"logspace.iife.js",
+		"logspace.iife.js.map",
+		"index.d.ts",
+		"sdk",
+		"shared"
+	],
+	"keywords": [
+		"logging",
+		"session-recording",
+		"rrweb",
+		"debugging",
+		"monitoring"
+	],
+	"author": "LogSpace",
+	"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

@@ -0,0 +1,45 @@
+import { LogEntry, LogType } from '../../shared/types';
+import { CaptureHandler, PrivacyConfig } from '../types';
+import { generateId, safeStringify, maskSensitiveData, maskHeaders } from '../../shared/utils';
+export { generateId, safeStringify, maskSensitiveData, maskHeaders };
+/**
+ * Check if running in browser environment (SSR safety)
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Check if URL should be excluded from capture
+ */
+export declare function shouldExcludeUrl(url: string, excludePatterns: string[]): boolean;
+/**
+ * Get call stack for request initiator
+ */
+export declare function getCallStack(): string;
+/**
+ * Truncate large JSON objects while maintaining structure
+ */
+export declare function truncateJSON(obj: any, maxLength: number): any;
+/**
+ * Truncate message content
+ */
+export declare function truncateMessage(message: any, isBinary: boolean, maxSize?: number): {
+    content: string;
+    size: number;
+    truncated: boolean;
+};
+/**
+ * Create a log entry with common fields
+ */
+export declare function createLogEntry(type: LogType, data: any, severity?: 'info' | 'warn' | 'error'): Omit<LogEntry, 'tabId' | 'tabUrl'>;
+/**
+ * Apply privacy settings to log data
+ */
+export declare function applyPrivacy(log: LogEntry, privacy: PrivacyConfig): LogEntry;
+/**
+ * Capture module interface
+ */
+export interface CaptureModule {
+    name: string;
+    install(handler: CaptureHandler, privacy: PrivacyConfig): void;
+    uninstall(): void;
+    reset?(): void;
+}

package/sdk/capture/console.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Console capture module
+ */
+export declare const consoleCapture: CaptureModule;

package/sdk/capture/errors.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Error capture module
+ */
+export declare const errorCapture: CaptureModule;

package/sdk/capture/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Capture Module Index
+ * Re-exports all capture modules
+ */
+export { consoleCapture } from './console';
+export { networkCapture } from './network';
+export { errorCapture } from './errors';
+export { websocketCapture } from './websocket';
+export { sseCapture } from './sse';
+export { storageCapture } from './storage';
+export { interactionCapture } from './interactions';
+export { performanceCapture } from './performance';
+export { resourceCapture } from './resources';
+export { spaNavigationCapture } from './spa-navigation';
+export type { CaptureModule } from './base';
+export { applyPrivacy, createLogEntry, isBrowser } from './base';

package/sdk/capture/interactions.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Interaction capture module
+ */
+export declare const interactionCapture: CaptureModule;

package/sdk/capture/network.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Network capture module
+ */
+export declare const networkCapture: CaptureModule;

package/sdk/capture/performance.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Performance capture module
+ */
+export declare const performanceCapture: CaptureModule;

package/sdk/capture/resources.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Resource capture module
+ */
+export declare const resourceCapture: CaptureModule;

package/sdk/capture/rrweb.d.ts

@@ -0,0 +1,101 @@
+import { eventWithTime } from 'rrweb';
+import { RecordPlugin } from '@rrweb/types';
+export interface RRWebCaptureConfig {
+    /** Mask all text input values (default: true) */
+    maskAllInputs?: boolean;
+    /** Mask text content matching these CSS selectors */
+    maskTextSelector?: string;
+    /** Block elements matching these CSS selectors from being recorded */
+    blockSelector?: string;
+    /** Ignore elements matching these CSS selectors */
+    ignoreSelector?: string;
+    /** Inline stylesheets for accurate replay (default: true) */
+    inlineStylesheet?: boolean;
+    /** Sample mouse movements to reduce data (default: true) */
+    sampling?: {
+        mousemove?: boolean | number;
+        mouseInteraction?: boolean | Record<string, boolean | undefined>;
+        scroll?: number;
+        media?: number;
+        input?: 'last' | 'all';
+        canvas?: number | 'all';
+    };
+    /** Take a full DOM snapshot every N events (default: 200) */
+    checkoutEveryNth?: number;
+    /** Take a full DOM snapshot every N milliseconds */
+    checkoutEveryNms?: number;
+    /** Record canvas content (default: false - can be expensive) */
+    recordCanvas?: boolean;
+    /** Collect fonts for replay (default: false) */
+    collectFonts?: boolean;
+    /** Enable inline images for replay (default: true) */
+    inlineImages?: boolean;
+    /** Plugins to use */
+    plugins?: RecordPlugin[];
+}
+export interface RRWebCaptureState {
+    isRecording: boolean;
+    events: eventWithTime[];
+    stopFn: (() => void) | null;
+    startTime: number | null;
+}
+/**
+ * Extended rrweb event with tab information
+ */
+export type TabAwareEvent = eventWithTime & {
+    tabId?: string;
+};
+/**
+ * Start rrweb DOM recording
+ * @param config - rrweb configuration options
+ * @param onEvent - callback for each recorded event
+ * @param tabId - optional tab identifier for multi-tab recording
+ */
+export declare function startRRWebRecording(config?: RRWebCaptureConfig, onEvent?: (event: TabAwareEvent) => void, tabId?: string): boolean;
+/**
+ * Stop rrweb DOM recording and return captured events
+ */
+export declare function stopRRWebRecording(): eventWithTime[];
+/**
+ * Get current recording state
+ */
+export declare function getRRWebState(): Readonly<RRWebCaptureState>;
+/**
+ * Get current events (for incremental sending if needed)
+ */
+export declare function getRRWebEvents(): eventWithTime[];
+/**
+ * Clear current events (useful for chunked sending)
+ */
+export declare function clearRRWebEvents(): void;
+/**
+ * Get recording duration in milliseconds
+ */
+export declare function getRRWebDuration(): number;
+/**
+ * Check if recording is active
+ */
+export declare function isRRWebRecording(): boolean;
+/**
+ * Get estimated size of recorded events in bytes
+ */
+export declare function getRRWebEventsSize(): number;
+/**
+ * Force a full DOM snapshot
+ * Call this when the tab becomes visible to ensure complete DOM context
+ */
+export declare function forceFullSnapshot(): void;
+/**
+ * Add a custom event to the rrweb recording
+ * Used for marking tab switches, navigation, etc.
+ */
+export declare function addRRWebCustomEvent<T>(tag: string, payload: T): void;
+/**
+ * Get current tab ID
+ */
+export declare function getRRWebTabId(): string | null;
+/**
+ * Set current tab ID (for when tab becomes leader)
+ */
+export declare function setRRWebTabId(tabId: string): void;
+export type { eventWithTime } from 'rrweb';

package/sdk/capture/spa-navigation.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * SPA navigation capture module
+ */
+export declare const spaNavigationCapture: CaptureModule;

package/sdk/capture/sse.d.ts

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

package/sdk/capture/storage.d.ts

@@ -0,0 +1,5 @@
+import { CaptureModule } from './base';
+/**
+ * Storage capture module
+ */
+export declare const storageCapture: CaptureModule;

package/sdk/capture/websocket.d.ts

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

package/sdk/core/console-api.d.ts

@@ -0,0 +1,26 @@
+import { CaptureHandler } from '../types';
+/**
+ * LogSpace console interface
+ */
+export interface LogSpaceConsole {
+    /** Log a custom event */
+    (event: string, data?: any): void;
+    /** Log an error with context */
+    error: (name: string, error: Error | any, context?: Record<string, any>) => void;
+    /** Add a breadcrumb */
+    breadcrumb: (message: string, category?: string) => void;
+    /** Log debug info (only in development) */
+    debug: (message: string, data?: any) => void;
+}
+/**
+ * Install console.logspace on the window object
+ */
+export declare function installConsoleAPI(handler: CaptureHandler, debug?: boolean): void;
+/**
+ * Uninstall console.logspace
+ */
+export declare function uninstallConsoleAPI(): void;
+/**
+ * Get the logspace console (for direct use)
+ */
+export declare function getLogSpaceConsole(): LogSpaceConsole;

package/sdk/core/multi-tab.d.ts

@@ -0,0 +1,176 @@
+import { LogEntry } from '../../shared/types';
+import { eventWithTime } from 'rrweb';
+type TabAwareRRWebEvent = eventWithTime & {
+    tabId?: string;
+};
+type MultiTabMessage = {
+    type: 'leader-announce';
+    tabId: string;
+    sessionId: string;
+} | {
+    type: 'leader-leaving';
+    tabId: string;
+} | {
+    type: 'log';
+    tabId: string;
+    log: LogEntry;
+} | {
+    type: 'rrweb-event';
+    tabId: string;
+    event: TabAwareRRWebEvent;
+} | {
+    type: 'request-session';
+    tabId: string;
+} | {
+    type: 'session-info';
+    sessionId: string;
+    startTime: number;
+};
+interface LeaderState {
+    tabId: string;
+    sessionId: string;
+    heartbeat: number;
+}
+interface SessionState {
+    id: string;
+    startTime: number;
+    userId?: string;
+    userTraits?: Record<string, any>;
+}
+interface MultiTabCallbacks {
+    onBecomeLeader: (sessionId: string, isNewSession: boolean) => void;
+    onBecomeFollower: (sessionId: string) => void;
+    onReceiveLog: (log: LogEntry) => void;
+    onReceiveRRWebEvent: (event: TabAwareRRWebEvent) => void;
+    onLeaderChanged: (newLeaderTabId: string) => void;
+}
+declare class MultiTabCoordinator {
+    private tabId;
+    private channel;
+    private isLeader;
+    private callbacks;
+    private heartbeatTimer;
+    private leaderCheckTimer;
+    private currentSessionId;
+    private initialized;
+    private debug;
+    constructor();
+    /**
+     * Generate unique tab identifier
+     */
+    private generateTabId;
+    /**
+     * Check if BroadcastChannel is supported
+     */
+    isSupported(): boolean;
+    /**
+     * Initialize the multi-tab coordinator
+     */
+    init(callbacks: MultiTabCallbacks, debug?: boolean): void;
+    /**
+     * Attempt to become leader or join as follower
+     */
+    private electLeader;
+    /**
+     * Try to claim leadership
+     */
+    private tryBecomeLeader;
+    /**
+     * Become the leader tab
+     */
+    private becomeLeader;
+    /**
+     * Become a follower tab
+     */
+    private becomeFollower;
+    /**
+     * Handle incoming broadcast messages
+     */
+    private handleMessage;
+    /**
+     * Start heartbeat for leader
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat timer
+     */
+    private stopHeartbeat;
+    /**
+     * Update heartbeat in localStorage
+     */
+    private updateHeartbeat;
+    /**
+     * Start checking if leader is alive (for followers)
+     */
+    private startLeaderCheck;
+    /**
+     * Stop leader check timer
+     */
+    private stopLeaderCheck;
+    /**
+     * Check if leader heartbeat is stale
+     */
+    private isLeaderStale;
+    /**
+     * Get leader state from localStorage
+     */
+    private getLeaderState;
+    /**
+     * Get session state from localStorage
+     */
+    private getSessionState;
+    /**
+     * Generate session ID
+     */
+    private generateSessionId;
+    /**
+     * Broadcast message to other tabs
+     */
+    private broadcast;
+    /**
+     * Handle page unload - clean leader handoff
+     */
+    private handleUnload;
+    /**
+     * Send log to leader (for follower tabs)
+     */
+    sendLog(log: LogEntry): void;
+    /**
+     * Send rrweb event to leader (for follower tabs)
+     */
+    sendRRWebEvent(event: TabAwareRRWebEvent): void;
+    /**
+     * Update session user info (stored in localStorage for all tabs)
+     */
+    updateSessionUser(userId: string, traits?: Record<string, any>): void;
+    /**
+     * End session and clear shared state
+     */
+    endSession(): void;
+    /**
+     * Get current tab ID
+     */
+    getTabId(): string;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Check if this tab is the leader
+     */
+    isLeaderTab(): boolean;
+    /**
+     * Check if multi-tab mode is active
+     */
+    isActive(): boolean;
+    /**
+     * Clean up resources
+     */
+    cleanup(): void;
+    /**
+     * Force become leader (for testing or recovery)
+     */
+    forceLeadership(): void;
+}
+export declare const multiTabCoordinator: MultiTabCoordinator;
+export type { MultiTabCallbacks, LeaderState, SessionState, MultiTabMessage };

package/sdk/index.d.ts

@@ -0,0 +1,69 @@
+import { LogEntry } from '../shared/types';
+import { LogSpaceConfig, SDKSession, SessionPayload } from './types';
+import { eventWithTime } from './capture/rrweb';
+export declare const LogSpace: {
+    /**
+     * Initialize the SDK
+     */
+    init(userConfig: LogSpaceConfig): void;
+    /**
+     * Start a new recording session
+     */
+    startSession(metadata?: Record<string, any>): void;
+    /**
+     * Stop recording and send session to server
+     */
+    stopSession(): Promise<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;
+    /**
+     * Pause recording
+     */
+    pauseRecording(): void;
+    /**
+     * Resume recording
+     */
+    resumeRecording(): void;
+    /**
+     * Manually trigger sampling (when sampling mode is enabled)
+     * Use this to mark a session as important even without an error
+     */
+    trigger(reason?: string): 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;
+    /**
+     * Get rrweb events for current session
+     */
+    getRRWebEvents(): eventWithTime[];
+    /**
+     * Destroy SDK
+     */
+    destroy(): void;
+    /**
+     * SDK version
+     */
+    version: string;
+};
+export type { LogSpaceConfig, NormalizedConfig, SDKSession, SessionPayload, CaptureConfig, PrivacyConfig, SessionLimits, SessionEndConfig, SamplingConfig, HooksConfig, LogSpacePlugin, } from './types';
+export type { LogEntry, LogType, LogSeverity } from '../shared/types';
+export default LogSpace;

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

@@ -0,0 +1,72 @@
+import { LogEntry } from '../../shared/types';
+import { SessionPayload } from '../types';
+import { eventWithTime } from 'rrweb';
+interface StoredSession {
+    id: string;
+    data: SessionPayload;
+    createdAt: number;
+    retryCount: number;
+    lastRetryAt?: number;
+}
+interface CurrentSessionBackup {
+    id: string;
+    sessionId: string;
+    logs: LogEntry[];
+    rrwebEvents: eventWithTime[];
+    startTime: number;
+    url: string;
+    title: string;
+    userId?: string;
+    userTraits?: Record<string, any>;
+    metadata?: Record<string, any>;
+    lastCheckpoint: number;
+}
+/**
+ * Check if IndexedDB is available
+ */
+export declare function isIndexedDBAvailable(): boolean;
+/**
+ * Save current session checkpoint to IndexedDB
+ * Called periodically to backup session data
+ */
+export declare function saveSessionCheckpoint(sessionId: string, logs: LogEntry[], rrwebEvents: eventWithTime[], sessionData: {
+    startTime: number;
+    url: string;
+    title: string;
+    userId?: string;
+    userTraits?: Record<string, any>;
+    metadata?: Record<string, any>;
+}): Promise<void>;
+/**
+ * Get current session backup from IndexedDB
+ */
+export declare function getCurrentSessionBackup(): Promise<CurrentSessionBackup | null>;
+/**
+ * Clear current session backup (called after successful send)
+ */
+export declare function clearCurrentSessionBackup(): Promise<void>;
+/**
+ * Add a session to pending queue (for retry later)
+ */
+export declare function addPendingSession(payload: SessionPayload): Promise<void>;
+/**
+ * Get all pending sessions
+ */
+export declare function getPendingSessions(): Promise<StoredSession[]>;
+/**
+ * Remove a pending session (after successful send)
+ */
+export declare function removePendingSession(sessionId: string): Promise<void>;
+/**
+ * Update retry count for a pending session
+ */
+export declare function updatePendingSessionRetry(sessionId: string): Promise<void>;
+/**
+ * Clean up old pending sessions (older than 7 days or too many retries)
+ */
+export declare function cleanupOldPendingSessions(): Promise<void>;
+/**
+ * Close database connection
+ */
+export declare function closeDB(): void;
+export {};