blinker-sdk 1.0.0 → 2.0.0

package/README.md

@@ -4,12 +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
-- 📊 **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
 
@@ -29,7 +36,7 @@ pnpm add blinker-sdk
 <script src="https://unpkg.com/blinker-sdk/dist/blinker.min.js"></script>
 <script>
   const { blinker } = BlinkerSDK;
-  blinker.init({ token: 'your-token', api: 'https://api.example.com' });
+  blinker.init({ token: 'your-token' });
 </script>
 ```
 
@@ -38,13 +45,15 @@ pnpm add blinker-sdk
 ```javascript
 import { blinker } from 'blinker-sdk';
 
-// Initialize the SDK
-blinker.init({
-  token: 'your-blinker-token',
-  api: 'https://api.example.com'
-});
+// Initialize the SDK - just pass your token!
+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
 ```
 
 ## Usage
@@ -54,13 +63,105 @@ blinker.init({
 ```javascript
 import { blinker } from 'blinker-sdk';
 
+// Minimal setup - just the token!
+blinker.init({ token: 'your-blinker-token' });
+
+// Or with all options
 blinker.init({
-  token: 'your-blinker-token',       // Required: Your API token
-  api: 'https://api.example.com',    // Required: API endpoint
-  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
@@ -96,6 +197,72 @@ try {
 blinker.captureError('Something went wrong', { userId: '123' });
 ```
 
+### Error Filters (Smart Defaults)
+
+The SDK comes with **intelligent default filters** that ignore common non-bug errors.
+
+#### Default Behavior
+
+By default, the SDK **ignores**:
+- `401` and `403` HTTP errors (authentication/authorization - usually expected behavior)
+- `ResizeObserver loop` errors (benign browser behavior)
+- `Script error` (cross-origin errors with no useful info)
+
+```javascript
+// Minimal initialization - all defaults applied automatically!
+blinker.init({ token: 'your-token' });
+```
+
+#### Capture Everything
+
+```javascript
+blinker.init({
+  token: 'your-token',
+  filters: { captureAll: true }
+});
+```
+
+#### Custom HTTP Code Filters
+
+```javascript
+// Only ignore 401 (capture 403)
+blinker.init({
+  token: 'your-token',
+  filters: { ignoreHttpCodes: [401] }
+});
+
+// Ignore more codes
+blinker.init({
+  token: 'your-token',
+  filters: { ignoreHttpCodes: [401, 403, 404, 429] }
+});
+```
+
+#### Ignore Specific Error Types
+
+```javascript
+blinker.init({
+  token: 'your-token',
+  filters: { ignoreErrorTypes: ['TypeError', 'SyntaxError'] }
+});
+```
+
+#### Ignore Message Patterns
+
+```javascript
+blinker.init({
+  token: 'your-token',
+  filters: {
+    ignoreMessagePatterns: [
+      'ResizeObserver loop',
+      'Script error',
+      'ChunkLoadError',
+      'Network request failed'
+    ]
+  }
+});
+```
+
 ### Check SDK Status
 
 ```javascript
@@ -106,6 +273,9 @@ if (blinker.isInitialized()) {
 
 // Get current config (without sensitive data)
 const config = blinker.getConfig();
+
+// Get current filters
+const filters = blinker.getFilters();
 ```
 
 ### Cleanup
@@ -123,12 +293,13 @@ blinker.destroy();
 // app.jsx or index.jsx
 import { blinker } from 'blinker-sdk';
 
-blinker.init({
-  token: process.env.REACT_APP_BLINKER_TOKEN,
-  api: process.env.REACT_APP_BLINKER_API
-});
+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' });
   };
@@ -148,10 +319,7 @@ import { blinker } from 'blinker-sdk';
 
 export default function RootLayout({ children }) {
   useEffect(() => {
-    blinker.init({
-      token: process.env.NEXT_PUBLIC_BLINKER_TOKEN,
-      api: process.env.NEXT_PUBLIC_BLINKER_API
-    });
+    blinker.init({ token: process.env.NEXT_PUBLIC_BLINKER_TOKEN });
   }, []);
 
   return (
@@ -170,31 +338,11 @@ import { createApp } from 'vue';
 import { blinker } from 'blinker-sdk';
 import App from './App.vue';
 
-blinker.init({
-  token: import.meta.env.VITE_BLINKER_TOKEN,
-  api: import.meta.env.VITE_BLINKER_API
-});
+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,
-  api: environment.blinkerApi
-});
-
-@NgModule({
-  // ...
-})
-export class AppModule {}
-```
-
 ### Vanilla JavaScript
 
 ```html
@@ -205,15 +353,15 @@ export class AppModule {}
 </head>
 <body>
   <button id="myButton">Click me</button>
-  
+
   <script>
     const { blinker } = BlinkerSDK;
-    
-    blinker.init({
-      token: 'your-token',
-      api: 'https://api.example.com'
-    });
-    
+
+    blinker.init({ token: 'your-token' });
+
+    // Identify user
+    blinker.identify('user-123', { name: 'John' });
+
     document.getElementById('myButton').addEventListener('click', () => {
       blinker.track('click', 'Button clicked');
     });
@@ -231,40 +379,83 @@ Initialize the SDK with configuration options.
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `token` | `string` | **required** | Your Blinker API token |
-| `api` | `string` | **required** | API endpoint URL |
 | `captureErrors` | `boolean` | `true` | Auto-capture window errors |
 | `captureRejections` | `boolean` | `true` | Auto-capture unhandled rejections |
+| `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 |
+| `ignoreMessagePatterns` | `string[]` | `['ResizeObserver loop', 'Script error']` | Message patterns to ignore |
+| `captureAll` | `boolean` | `false` | When true, disables all filters |
+
 ### `blinker.track(type, message, payload?)`
 
 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()`
 
@@ -274,54 +465,67 @@ Check if SDK is initialized. Returns `boolean`.
 
 Get current configuration (without token). Returns config object or `null`.
 
+### `blinker.getFilters()`
+
+Get current filter settings. Returns `FilterSettings` object.
+
 ### `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, BlinkerEvent } from 'blinker-sdk';
+import { blinker, BlinkerConfig, FilterSettings, SessionInfo } from 'blinker-sdk';
 
 const config: BlinkerConfig = {
   token: 'your-token',
-  api: 'https://api.example.com'
+  enableBatching: true,
+  sampleRate: 0.5,
+  filters: {
+    ignoreHttpCodes: [401, 403, 404],
+    captureAll: false
+  }
 };
 
 blinker.init(config);
+
+const filters: FilterSettings = blinker.getFilters();
+const session: SessionInfo | null = blinker.getSession();
 ```
 
 ## Multiple Instances
 
-If you need multiple SDK instances:
-
 ```javascript
 import { Blinker } from 'blinker-sdk';
 
-const instance1 = new Blinker();
-const instance2 = new Blinker();
+const frontendErrors = new Blinker();
+const backendErrors = new Blinker();
 
-instance1.init({ token: 'token1', api: 'https://api1.example.com' });
-instance2.init({ token: 'token2', api: 'https://api2.example.com' });
+frontendErrors.init({ token: 'frontend-token' });
+backendErrors.init({ token: 'backend-token' });
 ```
 
 ## Browser Support
@@ -336,4 +540,3 @@ The SDK uses modern JavaScript features (ES2018) including `async/await` and `fe
 ## License
 
 MIT
-