blinker-sdk 1.0.1 → 2.0.0

package/README.md

@@ -4,13 +4,19 @@ Universal JavaScript SDK for error tracking and event capture. Works with **any
 
 ## Features
 
-- 🚀 **Zero dependencies** - Lightweight and fast
-- 🌐 **Universal** - Works in any JavaScript environment
-- 🔄 **Automatic error capture** - Catches global errors and unhandled rejections
-- 🧠 **Smart filtering** - Ignores common non-bugs (401, 403, ResizeObserver) by default
-- 📊 **Custom events** - Track any event you need
-- 📦 **Multiple formats** - ESM, CommonJS, and UMD (CDN)
-- 🔒 **Type-safe** - Full TypeScript support
+- **Zero dependencies** - Lightweight and fast
+- **Universal** - Works in any JavaScript environment
+- **Automatic error capture** - Catches global errors and unhandled rejections
+- **Smart filtering** - Ignores common non-bugs (401, 403, ResizeObserver) by default
+- **Event batching** - Efficient sending with configurable batch size
+- **Offline support** - Persists events when offline, sends when back online
+- **Deduplication** - Prevents flood of identical errors
+- **Rate limiting** - Protects against excessive event sending
+- **Sampling** - Sample events for high-traffic apps
+- **Session tracking** - Automatic session management with pageview counting
+- **User context** - Identify users and attach custom context
+- **Multiple formats** - ESM, CommonJS, and UMD (CDN)
+- **Type-safe** - Full TypeScript support
 
 ## Installation
 
@@ -43,8 +49,11 @@ import { blinker } from 'blinker-sdk';
 blinker.init({ token: 'your-blinker-token' });
 
 // That's it! Errors are now automatically captured.
+// ✅ Batches events for efficient sending
+// ✅ Works offline with localStorage persistence
+// ✅ Deduplicates repeated errors
 // ✅ Ignores 401/403 errors by default
-// ✅ Filters out common browser noise (ResizeObserver, Script error)
+// ✅ Filters out common browser noise
 ```
 
 ## Usage
@@ -57,18 +66,140 @@ import { blinker } from 'blinker-sdk';
 // Minimal setup - just the token!
 blinker.init({ token: 'your-blinker-token' });
 
-// Or with custom options
+// Or with all options
 blinker.init({
-  token: 'your-blinker-token',       // Required: Your API token
-  captureErrors: true,                // Optional: Auto-capture errors (default: true)
-  captureRejections: true,            // Optional: Auto-capture promise rejections (default: true)
-  debug: false                        // Optional: Enable debug logging (default: false)
+  token: 'your-blinker-token',
+  // Capture options
+  captureErrors: true,
+  captureRejections: true,
+  // Batching
+  enableBatching: true,
+  batchSize: 10,
+  flushInterval: 5000,
+  // Offline persistence
+  enableOfflineStorage: true,
+  maxStoredEvents: 100,
+  // Deduplication
+  enableDeduplication: true,
+  deduplicationWindow: 60000,
+  // Rate limiting & sampling
+  maxEventsPerMinute: 100,
+  sampleRate: 1.0,
+  // Filters
+  filters: {
+    ignoreHttpCodes: [401, 403],
+    captureAll: false
+  },
+  // Debug
+  debug: false
 });
 ```
 
+### User Identification
+
+Identify users to associate events with specific users:
+
+```javascript
+// Identify a user with just an ID
+blinker.identify('user-123');
+
+// Identify with traits
+blinker.identify('user-123', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  plan: 'pro',
+  company: 'Acme Inc'
+});
+
+// Clear user context on logout
+blinker.clearContext();
+```
+
+### Custom Context
+
+Add custom context that's included in all events:
+
+```javascript
+// Set context values
+blinker.setContext('environment', 'production');
+blinker.setContext('appVersion', '2.1.0');
+blinker.setContext('feature', 'checkout');
+
+// Get current context
+const context = blinker.getContext();
+// { environment: 'production', appVersion: '2.1.0', feature: 'checkout' }
+
+// Clear all context
+blinker.clearContext();
+```
+
+### Session Information
+
+Access session tracking data:
+
+```javascript
+// Get current session ID
+const sessionId = blinker.getSessionId();
+
+// Get full session info
+const session = blinker.getSession();
+// {
+//   sessionId: 'abc123...',
+//   startTime: 1706700000000,
+//   pageViews: 5,
+//   duration: 120000
+// }
+```
+
+### Queue Control
+
+Manage the event queue:
+
+```javascript
+// Get number of pending events
+const pending = blinker.getQueueSize();
+console.log(`${pending} events waiting to be sent`);
+
+// Force flush all queued events immediately
+await blinker.flush();
+```
+
+### Track Custom Events
+
+```javascript
+// Basic event
+blinker.track('click', 'Button clicked');
+
+// Event with payload
+blinker.track('purchase', 'User made a purchase', {
+  productId: '12345',
+  amount: 99.99,
+  currency: 'USD'
+});
+
+// Page view
+blinker.trackPageView();
+
+// Page view with custom name
+blinker.trackPageView('Home Page', { section: 'hero' });
+```
+
+### Manual Error Capture
+
+```javascript
+try {
+  // Your code
+} catch (error) {
+  blinker.captureError(error, { context: 'checkout' });
+}
+
+// Or with a string
+blinker.captureError('Something went wrong', { userId: '123' });
+```
+
 ### Error Filters (Smart Defaults)
 
-The SDK comes with **intelligent default filters** that ignore common non-bug errors. This prevents your error tracking from being cluttered with expected behaviors like authentication failures.
+The SDK comes with **intelligent default filters** that ignore common non-bug errors.
 
 #### Default Behavior
 
@@ -80,13 +211,10 @@ By default, the SDK **ignores**:
 ```javascript
 // Minimal initialization - all defaults applied automatically!
 blinker.init({ token: 'your-token' });
-// ✅ Automatically ignores: 401, 403, ResizeObserver loop, Script error
 ```
 
 #### Capture Everything
 
-If you want to capture ALL errors including auth failures:
-
 ```javascript
 blinker.init({
   token: 'your-token',
@@ -96,8 +224,6 @@ blinker.init({
 
 #### Custom HTTP Code Filters
 
-Customize which HTTP codes to ignore:
-
 ```javascript
 // Only ignore 401 (capture 403)
 blinker.init({
@@ -110,18 +236,10 @@ blinker.init({
   token: 'your-token',
   filters: { ignoreHttpCodes: [401, 403, 404, 429] }
 });
-
-// Capture ALL HTTP errors (empty array)
-blinker.init({
-  token: 'your-token',
-  filters: { ignoreHttpCodes: [] }
-});
 ```
 
 #### Ignore Specific Error Types
 
-Filter out specific JavaScript error types:
-
 ```javascript
 blinker.init({
   token: 'your-token',
@@ -131,82 +249,20 @@ blinker.init({
 
 #### Ignore Message Patterns
 
-Filter errors by message content (case-insensitive substring matching):
-
 ```javascript
 blinker.init({
   token: 'your-token',
   filters: {
     ignoreMessagePatterns: [
-      'ResizeObserver loop',     // Default
-      'Script error',            // Default
-      'ChunkLoadError',          // Webpack chunk loading
-      'Loading chunk',           // Next.js chunk loading
-      'Network request failed',  // Offline users
-      'AbortError'               // Cancelled requests
+      'ResizeObserver loop',
+      'Script error',
+      'ChunkLoadError',
+      'Network request failed'
     ]
   }
 });
 ```
 
-#### Full Filter Configuration
-
-All filter options together:
-
-```javascript
-blinker.init({
-  token: 'your-token',
-  filters: {
-    ignoreHttpCodes: [401, 403, 404],
-    ignoreErrorTypes: ['AbortError'],
-    ignoreMessagePatterns: ['ResizeObserver loop', 'Script error', 'ChunkLoadError'],
-    captureAll: false
-  }
-});
-```
-
-#### Check Current Filters
-
-```javascript
-// Get the current filter configuration
-const filters = blinker.getFilters();
-console.log(filters);
-// { ignoreHttpCodes: [401, 403], ignoreErrorTypes: [], ... }
-```
-
-### Track Custom Events
-
-```javascript
-// Basic event
-blinker.track('click', 'Button clicked');
-
-// Event with payload
-blinker.track('purchase', 'User made a purchase', {
-  productId: '12345',
-  amount: 99.99,
-  currency: 'USD'
-});
-
-// Page view
-blinker.trackPageView();
-
-// Page view with custom name
-blinker.trackPageView('Home Page', { section: 'hero' });
-```
-
-### Manual Error Capture
-
-```javascript
-try {
-  // Your code
-} catch (error) {
-  blinker.captureError(error, { context: 'checkout' });
-}
-
-// Or with a string
-blinker.captureError('Something went wrong', { userId: '123' });
-```
-
 ### Check SDK Status
 
 ```javascript
@@ -217,6 +273,9 @@ if (blinker.isInitialized()) {
 
 // Get current config (without sensitive data)
 const config = blinker.getConfig();
+
+// Get current filters
+const filters = blinker.getFilters();
 ```
 
 ### Cleanup
@@ -237,6 +296,10 @@ import { blinker } from 'blinker-sdk';
 blinker.init({ token: process.env.REACT_APP_BLINKER_TOKEN });
 
 function App() {
+  useEffect(() => {
+    blinker.identify(user.id, { name: user.name, email: user.email });
+  }, [user]);
+
   const handleClick = () => {
     blinker.track('click', 'CTA button clicked', { page: 'home' });
   };
@@ -280,20 +343,6 @@ blinker.init({ token: import.meta.env.VITE_BLINKER_TOKEN });
 createApp(App).mount('#app');
 ```
 
-### Angular
-
-```typescript
-// app.module.ts
-import { blinker } from 'blinker-sdk';
-
-blinker.init({ token: environment.blinkerToken });
-
-@NgModule({
-  // ...
-})
-export class AppModule {}
-```
-
 ### Vanilla JavaScript
 
 ```html
@@ -304,12 +353,15 @@ export class AppModule {}
 </head>
 <body>
   <button id="myButton">Click me</button>
-  
+
   <script>
     const { blinker } = BlinkerSDK;
-    
+
     blinker.init({ token: 'your-token' });
-    
+
+    // Identify user
+    blinker.identify('user-123', { name: 'John' });
+
     document.getElementById('myButton').addEventListener('click', () => {
       blinker.track('click', 'Button clicked');
     });
@@ -329,15 +381,24 @@ Initialize the SDK with configuration options.
 | `token` | `string` | **required** | Your Blinker API token |
 | `captureErrors` | `boolean` | `true` | Auto-capture window errors |
 | `captureRejections` | `boolean` | `true` | Auto-capture unhandled rejections |
-| `debug` | `boolean` | `false` | Enable debug logging |
+| `enableBatching` | `boolean` | `true` | Enable event batching |
+| `batchSize` | `number` | `10` | Events per batch |
+| `flushInterval` | `number` | `5000` | Batch flush interval (ms) |
+| `enableOfflineStorage` | `boolean` | `true` | Persist events when offline |
+| `maxStoredEvents` | `number` | `100` | Max offline events to store |
+| `enableDeduplication` | `boolean` | `true` | Enable error deduplication |
+| `deduplicationWindow` | `number` | `60000` | Dedup window (ms) |
+| `maxEventsPerMinute` | `number` | `100` | Rate limit (0 = unlimited) |
+| `sampleRate` | `number` | `1.0` | Sample rate (0.0-1.0) |
 | `filters` | `FilterSettings` | see below | Error filter configuration |
+| `debug` | `boolean` | `false` | Enable debug logging |
 
 #### FilterSettings
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `ignoreHttpCodes` | `number[]` | `[401, 403]` | HTTP status codes to ignore |
-| `ignoreErrorTypes` | `string[]` | `[]` | JS error types to ignore (e.g., 'TypeError') |
+| `ignoreErrorTypes` | `string[]` | `[]` | JS error types to ignore |
 | `ignoreMessagePatterns` | `string[]` | `['ResizeObserver loop', 'Script error']` | Message patterns to ignore |
 | `captureAll` | `boolean` | `false` | When true, disables all filters |
 
@@ -345,31 +406,56 @@ Initialize the SDK with configuration options.
 
 Track a custom event.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `type` | `string` | Event type (e.g., 'click', 'purchase') |
-| `message` | `string` | Event description |
-| `payload` | `object` | Optional additional data |
-
 **Returns:** `Promise<{ success: boolean, error?: string }>`
 
 ### `blinker.captureError(error, payload?)`
 
 Manually capture an error.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `error` | `Error \| string` | Error object or message |
-| `payload` | `object` | Optional additional data |
-
 ### `blinker.trackPageView(pageName?, payload?)`
 
 Track a page view.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pageName` | `string` | Optional page name (defaults to URL path) |
-| `payload` | `object` | Optional additional data |
+### `blinker.identify(userId, traits?)`
+
+Identify the current user. Traits are optional metadata about the user.
+
+### `blinker.setContext(key, value)`
+
+Set a custom context value that will be included in all events.
+
+### `blinker.getContext()`
+
+Get all custom context values. Returns `Record<string, unknown>`.
+
+### `blinker.clearContext()`
+
+Clear all user context (use on logout).
+
+### `blinker.getSessionId()`
+
+Get current session ID. Returns `string`.
+
+### `blinker.getSession()`
+
+Get full session info. Returns `SessionInfo | null`.
+
+```typescript
+interface SessionInfo {
+  sessionId: string;
+  startTime: number;
+  pageViews: number;
+  duration: number;
+}
+```
+
+### `blinker.flush()`
+
+Force flush all queued events immediately. Returns `Promise<void>`.
+
+### `blinker.getQueueSize()`
+
+Get number of events waiting to be sent. Returns `number`.
 
 ### `blinker.isInitialized()`
 
@@ -383,45 +469,41 @@ Get current configuration (without token). Returns config object or `null`.
 
 Get current filter settings. Returns `FilterSettings` object.
 
-```javascript
-const filters = blinker.getFilters();
-// { ignoreHttpCodes: [401, 403], ignoreErrorTypes: [], ignoreMessagePatterns: [...], captureAll: false }
-```
-
 ### `blinker.destroy()`
 
 Remove error handlers and reset SDK state.
 
 ## Event Payload
 
-Events sent to the API have the following structure:
+Events sent to the API include:
 
 ```json
 {
   "type": "error",
   "message": "Error message",
-  "payload": {
-    "custom": "data"
-  },
+  "payload": { "custom": "data" },
   "timestamp": "2024-01-15T12:00:00.000Z",
   "url": "https://example.com/page",
-  "userAgent": "Mozilla/5.0..."
+  "userAgent": "Mozilla/5.0...",
+  "sessionId": "abc123...",
+  "userId": "user-123",
+  "userTraits": { "name": "John", "plan": "pro" },
+  "context": { "appVersion": "2.1.0" },
+  "count": 5
 }
 ```
 
 ## TypeScript
 
-The SDK is written in TypeScript and includes type definitions.
+The SDK includes full type definitions.
 
 ```typescript
-import { blinker, BlinkerConfig, FilterSettings } from 'blinker-sdk';
-
-// Minimal config - just the token!
-blinker.init({ token: 'your-token' });
+import { blinker, BlinkerConfig, FilterSettings, SessionInfo } from 'blinker-sdk';
 
-// Or with full typed config
 const config: BlinkerConfig = {
   token: 'your-token',
+  enableBatching: true,
+  sampleRate: 0.5,
   filters: {
     ignoreHttpCodes: [401, 403, 404],
     captureAll: false
@@ -430,14 +512,12 @@ const config: BlinkerConfig = {
 
 blinker.init(config);
 
-// Get typed filters
 const filters: FilterSettings = blinker.getFilters();
+const session: SessionInfo | null = blinker.getSession();
 ```
 
 ## Multiple Instances
 
-If you need multiple SDK instances (e.g., different tokens for different app sections):
-
 ```javascript
 import { Blinker } from 'blinker-sdk';
 
@@ -460,4 +540,3 @@ The SDK uses modern JavaScript features (ES2018) including `async/await` and `fe
 ## License
 
 MIT
-