@bentolabs/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BentoLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# BentoLabs SDK
+
+A TypeScript SDK for user session recording and analytics using rrweb.
+
+[![CI/CD Pipeline](https://github.com/bentolabs/bentolabs-sdk/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/bentolabs/bentolabs-sdk/actions)
+[![Code Quality](https://github.com/bentolabs/bentolabs-sdk/workflows/Code%20Quality/badge.svg)](https://github.com/bentolabs/bentolabs-sdk/actions)
+[![npm version](https://badge.fury.io/js/%40bentolabs%2Fsdk.svg)](https://badge.fury.io/js/%40bentolabs%2Fsdk)
+
+## Installation
+
+```bash
+npm install @bentolabs/sdk
+```
+
+## CI/CD Pipeline
+
+This project includes a streamlined CI/CD pipeline with:
+
+- ✅ **Release-Triggered Builds** - Only runs when you create a GitHub release
+- ✅ **Automated Testing** on Node.js 18.x
+- ✅ **Code Quality Checks** (ESLint, Prettier, TypeScript)
+- ✅ **Automated Build** and validation
+- ✅ **Automated NPM Publishing** on releases
+- ✅ **Dependency Management** with Dependabot
+
+### Quick Setup
+
+1. **Set NPM Token**: Add `NPM_TOKEN` to GitHub repository secrets
+2. **Create Release**: Tag and release on GitHub to automatically build, test, and publish to npm
+
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed setup instructions.
+
+## Quick Start
+
+```typescript
+import { BentoLabsSDK } from '@bentolabs/sdk';
+
+// Create SDK instance
+const sdk = new BentoLabsSDK();
+
+// Initialize with your API key
+sdk.init('your-api-key', {
+  endpoint: 'https://api.bentolabs.ai',
+  debug: true,
+});
+
+// Check status
+console.log('Session ID:', sdk.getSessionId());
+console.log('Recording:', sdk.isRecordingActive());
+```
+
+## API Reference
+
+### Initialization
+
+#### `init(apiKey: string, options?: SDKOptions)`
+
+Initialize the SDK with your API key and optional configuration.
+
+**Parameters:**
+
+- `apiKey` (string): Your BentoLabs API key
+- `options` (SDKOptions, optional): Configuration options
+
+**Options:**
+
+```typescript
+interface SDKOptions {
+  endpoint?: string; // API endpoint URL (default: 'https://api.bentolabs.ai')
+  debug?: boolean; // Enable debug logging (default: false)
+}
+```
+
+**Example:**
+
+```typescript
+sdk.init('your-api-key', {
+  endpoint: 'https://custom-endpoint.com',
+  debug: true,
+});
+```
+
+### Methods
+
+#### `getSessionId(): string`
+
+Returns the current session ID.
+
+```typescript
+const sessionId = sdk.getSessionId();
+console.log('Current session:', sessionId); // sess_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+#### `isRecordingActive(): boolean`
+
+Check if recording is currently active.
+
+```typescript
+if (sdk.isRecordingActive()) {
+  console.log('Recording user interactions...');
+}
+```
+
+#### `getConfig(): Omit<SDKConfig, 'apiKey'> & { apiKey: string }`
+
+Get current configuration with masked API key for security.
+
+```typescript
+const config = sdk.getConfig();
+console.log(config);
+// {
+//   apiKey: 'your-api...',
+//   endpoint: 'https://api.bentolabs.ai',
+//   debug: false
+// }
+```
+
+## Examples
+
+### React Integration
+
+```typescript
+import React, { useEffect, useState } from 'react';
+import { BentoLabsSDK } from '@bentolabs/sdk';
+
+function App() {
+  const [sdk] = useState(() => new BentoLabsSDK());
+  const [sessionId, setSessionId] = useState('');
+
+  useEffect(() => {
+    sdk.init('your-api-key', { debug: true });
+    setSessionId(sdk.getSessionId());
+  }, [sdk]);
+
+  return (
+    <div>
+      <h1>My App</h1>
+      <p>Session: {sessionId}</p>
+      <p>Recording: {sdk.isRecordingActive() ? 'Active' : 'Inactive'}</p>
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="https://unpkg.com/@bentolabs/sdk@latest/dist/index.js"></script>
+  </head>
+  <body>
+    <script>
+      const sdk = new BentoLabsSDK();
+      sdk.init('your-api-key', { debug: true });
+
+      console.log('Session ID:', sdk.getSessionId());
+      console.log('Recording:', sdk.isRecordingActive());
+    </script>
+  </body>
+</html>
+```
+
+## Examples Directory
+
+Check out the [examples](./examples/) directory for complete working examples:
+
+- **[React Example](./examples/react-example/)**: Comprehensive React application with interactive demo
+- **[Vanilla JS Example](./examples/vanilla-js/)**: Simple HTML/JavaScript integration
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/bentolabs/bentolabs-sdk.git
+cd bentolabs-sdk
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Start development mode
+npm run dev
+```
+
+### Scripts
+
+- `npm run build` - Build the TypeScript project
+- `npm run dev` - Start TypeScript compiler in watch mode
+- `npm test` - Run all tests
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Run tests with coverage report
+- `npm run lint` - Run ESLint
+- `npm run format` - Format code with Prettier
+
+### Project Structure
+
+```
+bentolabs-sdk/
+├── src/                 # Source code
+│   └── index.ts        # Main SDK implementation
+├── tests/              # Test files
+│   ├── BentoLabsSDK.test.ts
+│   └── integration.test.ts
+├── examples/           # Example applications
+│   └── react-example/  # React example
+├── dist/               # Built files (generated)
+├── coverage/           # Test coverage (generated)
+└── .github/            # GitHub Actions workflows
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes and add tests
+4. Run tests: `npm test`
+5. Run linting: `npm run lint`
+6. Commit your changes: `git commit -am 'Add my feature'`
+7. Push to the branch: `git push origin feature/my-feature`
+8. Submit a pull request
+
+## Publishing
+
+### Stable Release
+
+1. Create a GitHub release with a version tag (e.g., `v1.0.0`)
+2. GitHub Actions will automatically publish to npm
+
+### Beta Release
+
+1. Push changes to the `develop` branch
+2. GitHub Actions will automatically publish a beta version
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📖 [Documentation](https://github.com/bentolabs/bentolabs-sdk)
+- 🐛 [Issue Tracker](https://github.com/bentolabs/bentolabs-sdk/issues)
+- 💬 [Discussions](https://github.com/bentolabs/bentolabs-sdk/discussions)

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+interface SDKConfig {
+    apiKey: string;
+    endpoint: string;
+    debug: boolean;
+    batchSize: number;
+    batchInterval: number;
+    enableRecording: boolean;
+    maxRetries: number;
+    baseRetryDelay: number;
+}
+interface SDKOptions {
+    endpoint?: string;
+    debug?: boolean;
+    batchSize?: number;
+    batchInterval?: number;
+    enableRecording?: boolean;
+    maxRetries?: number;
+    baseRetryDelay?: number;
+}
+export declare class BentoLabsSDK {
+    private config;
+    private sessionId;
+    private events;
+    private isRecording;
+    private batchTimer;
+    private retryTimer;
+    private stopRecording;
+    constructor();
+    /**
+     * Initialize the BentoLabs SDK
+     * @param apiKey - Your API key for authentication
+     * @param options - Optional configuration options
+     */
+    init(apiKey: string, options?: SDKOptions): void;
+    /**
+     * Generate a unique session ID with 'sess_' prefix
+     */
+    private generateSessionId;
+    /**
+     * Generate a simple UUID v4
+     */
+    private generateUUID;
+    /**
+     * Start recording user interactions
+     */
+    private startRecording;
+    /**
+     * Start batching events for transmission
+     */
+    private startBatching;
+    /**
+     * Add an event to the events array
+     */
+    private addEvent;
+    /**
+     * Send batched events to the API with exponential backoff retry
+     */
+    private sendBatch;
+    /**
+     * Schedule retry attempts for failed events
+     */
+    private scheduleRetry;
+    /**
+     * Stop recording and clean up resources
+     */
+    stop(): void;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Check if recording is active
+     */
+    isRecordingActive(): boolean;
+    /**
+     * Get current configuration (without exposing sensitive data)
+     */
+    getConfig(): Omit<SDKConfig, 'apiKey'> & {
+        apiKey: string;
+    };
+    /**
+     * Get current event queue length
+     */
+    getEventQueueLength(): number;
+    /**
+     * Manually trigger a batch send
+     */
+    flushEvents(): Promise<void>;
+}
+declare const _default: BentoLabsSDK;
+export default _default;

package/dist/index.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BentoLabsSDK = void 0;
+const rrweb_1 = require("rrweb");
+class BentoLabsSDK {
+    constructor() {
+        this.config = {
+            apiKey: '',
+            endpoint: '',
+            debug: false,
+            batchSize: 50,
+            batchInterval: 10000, // 10 seconds
+            enableRecording: true,
+            maxRetries: 3,
+            baseRetryDelay: 1000,
+        };
+        this.sessionId = '';
+        this.events = [];
+        this.isRecording = false;
+        this.batchTimer = null;
+        this.retryTimer = null;
+        this.stopRecording = null;
+    }
+    /**
+     * Initialize the BentoLabs SDK
+     * @param apiKey - Your API key for authentication
+     * @param options - Optional configuration options
+     */
+    init(apiKey, options) {
+        var _a;
+        // Merge options with defaults
+        const defaultOptions = {
+            endpoint: 'https://api.bentolabs.ai',
+            debug: false,
+            batchSize: 100, // Increased from 50 to reduce API calls
+            batchInterval: 30000, // 30 seconds (increased from 10s)
+            enableRecording: true,
+            maxRetries: 3,
+            baseRetryDelay: 1000, // 1 second
+        };
+        const mergedOptions = Object.assign(Object.assign(Object.assign({}, defaultOptions), options), { 
+            // Ensure debug is always a boolean
+            debug: (_a = options === null || options === void 0 ? void 0 : options.debug) !== null && _a !== void 0 ? _a : defaultOptions.debug });
+        // Set up configuration
+        this.config = {
+            apiKey,
+            endpoint: mergedOptions.endpoint,
+            debug: mergedOptions.debug,
+            batchSize: mergedOptions.batchSize,
+            batchInterval: mergedOptions.batchInterval,
+            enableRecording: mergedOptions.enableRecording,
+            maxRetries: mergedOptions.maxRetries,
+            baseRetryDelay: mergedOptions.baseRetryDelay,
+        };
+        // Generate session ID with 'sess_' prefix
+        this.sessionId = this.generateSessionId();
+        // Log initialization if debug mode is on
+        if (this.config.debug) {
+            console.log('[BentoLabsSDK] Initialized with config:', {
+                apiKey: apiKey.substring(0, 8) + '...',
+                endpoint: this.config.endpoint,
+                debug: this.config.debug,
+                sessionId: this.sessionId,
+            });
+        }
+        // Start recording and batching
+        this.startRecording();
+        this.startBatching();
+    }
+    /**
+     * Generate a unique session ID with 'sess_' prefix
+     */
+    generateSessionId() {
+        const uuid = this.generateUUID();
+        return `sess_${uuid}`;
+    }
+    /**
+     * Generate a simple UUID v4
+     */
+    generateUUID() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+    /**
+     * Start recording user interactions
+     */
+    startRecording() {
+        if (!this.config.enableRecording) {
+            if (this.config.debug) {
+                console.log('[BentoLabsSDK] Recording disabled in configuration');
+            }
+            return;
+        }
+        if (this.config.debug) {
+            console.log('[BentoLabsSDK] Starting recording for session:', this.sessionId);
+        }
+        try {
+            const stopFn = (0, rrweb_1.record)({
+                emit: (event) => {
+                    this.addEvent({
+                        timestamp: event.timestamp,
+                        type: event.type.toString(),
+                        data: event,
+                        sessionId: this.sessionId,
+                    });
+                },
+                recordCanvas: true,
+                collectFonts: true,
+                plugins: [],
+                // Sampling and throttling to reduce event volume
+                sampling: {
+                    mousemove: true, // Sample mouse movements
+                    mouseInteraction: { click: false, dblclick: false }, // Capture all clicks
+                    scroll: 150, // Throttle scroll events to 150ms
+                    input: 'last', // Only record final input value
+                },
+                checkoutEveryNms: 5 * 60 * 1000, // Take full snapshot every 5 minutes
+            });
+            this.stopRecording = stopFn || null;
+            this.isRecording = true;
+            if (this.config.debug) {
+                console.log('[BentoLabsSDK] Recording started successfully');
+            }
+        }
+        catch (error) {
+            console.error('[BentoLabsSDK] Failed to start recording:', error);
+            this.isRecording = false;
+        }
+    }
+    /**
+     * Start batching events for transmission
+     */
+    startBatching() {
+        if (this.config.debug) {
+            console.log('[BentoLabsSDK] Starting event batching');
+        }
+        // Clear any existing timer
+        if (this.batchTimer) {
+            clearInterval(this.batchTimer);
+        }
+        // Set up periodic batch sending
+        this.batchTimer = setInterval(() => {
+            this.sendBatch();
+        }, this.config.batchInterval);
+        if (this.config.debug) {
+            console.log(`[BentoLabsSDK] Batch timer set for ${this.config.batchInterval}ms intervals`);
+        }
+    }
+    /**
+     * Add an event to the events array
+     */
+    addEvent(event) {
+        this.events.push(event);
+        if (this.config.debug) {
+            console.log('[BentoLabsSDK] Event added:', event.type);
+        }
+        // Check if we should send a batch based on size
+        if (this.events.length >= this.config.batchSize) {
+            if (this.config.debug) {
+                console.log(`[BentoLabsSDK] Batch size limit reached (${this.config.batchSize}), sending batch`);
+            }
+            this.sendBatch();
+        }
+    }
+    /**
+     * Send batched events to the API with exponential backoff retry
+     */
+    async sendBatch() {
+        // Filter out events that are not ready for retry yet
+        const now = Date.now();
+        const readyEvents = this.events.filter(event => {
+            if ('nextRetryTime' in event) {
+                return now >= event.nextRetryTime;
+            }
+            return true;
+        });
+        if (readyEvents.length === 0) {
+            return;
+        }
+        // Remove ready events from the main array
+        this.events = this.events.filter(event => !readyEvents.includes(event));
+        const payload = {
+            sessionId: this.sessionId,
+            events: readyEvents,
+            timestamp: now,
+            userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'Unknown',
+            url: typeof window !== 'undefined' ? window.location.href : 'Unknown',
+        };
+        if (this.config.debug) {
+            console.log(`[BentoLabsSDK] Sending batch with ${readyEvents.length} events`);
+        }
+        try {
+            const response = await fetch(`${this.config.endpoint}/events/`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    'X-Session-ID': this.sessionId,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            if (this.config.debug) {
+                console.log('[BentoLabsSDK] Batch sent successfully');
+            }
+        }
+        catch (error) {
+            console.error('[BentoLabsSDK] Failed to send batch:', error);
+            // Convert events to retryable events with exponential backoff
+            const retryableEvents = readyEvents.map(event => {
+                const retryCount = 'retryCount' in event ? event.retryCount + 1 : 1;
+                const delay = this.config.baseRetryDelay * Math.pow(2, retryCount - 1);
+                return Object.assign(Object.assign({}, event), { retryCount, nextRetryTime: now + delay });
+            });
+            // Filter out events that have exceeded max retries
+            const eventsToRetry = retryableEvents.filter(event => event.retryCount <= this.config.maxRetries);
+            const droppedEvents = retryableEvents.length - eventsToRetry.length;
+            if (droppedEvents > 0 && this.config.debug) {
+                console.log(`[BentoLabsSDK] Dropped ${droppedEvents} events after max retries`);
+            }
+            // Re-add events that can still be retried
+            this.events.unshift(...eventsToRetry);
+            if (this.config.debug && eventsToRetry.length > 0) {
+                const nextRetryIn = Math.min(...eventsToRetry.map(e => e.nextRetryTime)) - now;
+                console.log(`[BentoLabsSDK] ${eventsToRetry.length} events re-queued for retry in ${nextRetryIn}ms`);
+            }
+            // Set up retry timer if we have events to retry
+            this.scheduleRetry();
+        }
+    }
+    /**
+     * Schedule retry attempts for failed events
+     */
+    scheduleRetry() {
+        // Clear existing retry timer
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        // Find the next retry time
+        const now = Date.now();
+        const retryableEvents = this.events.filter(event => 'nextRetryTime' in event);
+        if (retryableEvents.length === 0) {
+            return;
+        }
+        const nextRetryTime = Math.min(...retryableEvents.map(e => e.nextRetryTime));
+        const delay = Math.max(0, nextRetryTime - now);
+        if (this.config.debug) {
+            console.log(`[BentoLabsSDK] Scheduling retry in ${delay}ms`);
+        }
+        this.retryTimer = setTimeout(() => {
+            this.sendBatch();
+        }, delay);
+    }
+    /**
+     * Stop recording and clean up resources
+     */
+    stop() {
+        if (this.config.debug) {
+            console.log('[BentoLabsSDK] Stopping recording and batching');
+        }
+        // Stop rrweb recording
+        if (this.stopRecording) {
+            this.stopRecording();
+            this.stopRecording = null;
+        }
+        // Clear batch timer
+        if (this.batchTimer) {
+            clearInterval(this.batchTimer);
+            this.batchTimer = null;
+        }
+        // Clear retry timer
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        // Send any remaining events
+        if (this.events.length > 0) {
+            this.sendBatch();
+        }
+        this.isRecording = false;
+        if (this.config.debug) {
+            console.log('[BentoLabsSDK] Stopped successfully');
+        }
+    }
+    /**
+     * Get current session ID
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Check if recording is active
+     */
+    isRecordingActive() {
+        return this.isRecording;
+    }
+    /**
+     * Get current configuration (without exposing sensitive data)
+     */
+    getConfig() {
+        return {
+            apiKey: this.config.apiKey
+                ? this.config.apiKey.substring(0, 8) + '...'
+                : '',
+            endpoint: this.config.endpoint,
+            debug: this.config.debug,
+            batchSize: this.config.batchSize,
+            batchInterval: this.config.batchInterval,
+            enableRecording: this.config.enableRecording,
+            maxRetries: this.config.maxRetries,
+            baseRetryDelay: this.config.baseRetryDelay,
+        };
+    }
+    /**
+     * Get current event queue length
+     */
+    getEventQueueLength() {
+        return this.events.length;
+    }
+    /**
+     * Manually trigger a batch send
+     */
+    async flushEvents() {
+        await this.sendBatch();
+    }
+}
+exports.BentoLabsSDK = BentoLabsSDK;
+// Export a default instance for convenience
+exports.default = new BentoLabsSDK();

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@bentolabs/sdk",
+  "version": "0.2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:ci": "jest --ci --coverage --watchAll=false",
+    "lint": "eslint src/**/*.ts --fix",
+    "lint:check": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.{ts,js,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js,json}\"",
+    "prepublishOnly": "npm run build && npm test",
+    "preversion": "npm run lint:check && npm test"
+  },
+  "description": "BentoLabs SDK for user session recording and analytics",
+  "keywords": [
+    "analytics",
+    "session-recording",
+    "user-tracking",
+    "rrweb",
+    "typescript",
+    "sdk"
+  ],
+  "author": "kacppian",
+  "license": "MIT",
+  "homepage": "https://github.com/bentolabs/bentolabs-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bentolabs/bentolabs-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bentolabs/bentolabs-sdk/issues"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.5.1",
+    "@typescript-eslint/eslint-plugin": "^7.2.0",
+    "@typescript-eslint/parser": "^7.2.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^30.1.3",
+    "jest-environment-jsdom": "^30.1.2",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.2",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "rrweb": "^1.1.3"
+  }
+}