@logspace/sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,269 @@
+# @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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@logspace/sdk",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "LogSpace JavaScript SDK for session recording and logging",
 	"type": "module",
 	"main": "./logspace.umd.js",
@@ -19,6 +19,7 @@
 		}
 	},
 	"files": [
+		"README.md",
 		"logspace.esm.js",
 		"logspace.esm.js.map",
 		"logspace.umd.js",
@@ -37,8 +38,5 @@
 		"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)"
-	}
+	"license": "MIT"
 }