@lavarage/telemetry 1.0.0

package/README.md

@@ -0,0 +1,540 @@
+# @lavarage/telemetry
+
+Production telemetry SDK for Lavarage and partner applications. Track user activity, network requests, and errors with comprehensive filtering and privacy controls.
+
+## Installation
+
+```bash
+npm install @lavarage/telemetry
+```
+
+## Quick Start
+
+```typescript
+import { LavarageTelemetry } from '@lavarage/telemetry';
+
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+});
+
+// Intercept network requests
+telemetry.interceptFetch();
+
+// Connect wallet (triggers login event)
+telemetry.setWallet('YourWalletAddress123...');
+
+// Track trading pair views
+telemetry.trackPairView('SOL/USDC', { source: 'homepage' });
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: string;        // Required: Backend API endpoint
+  platform: string;           // Required: Platform identifier (e.g., 'lavarage-web')
+  captureHosts?: HostFilterInput;  // Optional: Host filtering configuration
+  errorFilters?: ErrorFilterConfig; // Optional: Error filtering configuration
+  batchSize?: number;         // Optional: Max events per batch (default: 50)
+  flushInterval?: number;     // Optional: Flush interval in ms (default: 5000)
+});
+```
+
+## Host Filtering
+
+Control which network requests are captured using flexible host filtering.
+
+### String Configuration
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+  captureHosts: 'api.lavarage.com', // Only capture requests to this host
+});
+```
+
+### Array Configuration
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+  captureHosts: [
+    'api.lavarage.com',
+    'partner-api.com',
+    '*.example.com' // Wildcard: matches any subdomain
+  ],
+});
+```
+
+### Object Configuration
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+  captureHosts: {
+    mode: 'include', // 'all' | 'none' | 'include' | 'exclude'
+    hosts: ['api.lavarage.com', '*.partner.com'],
+    patterns: ['^api\\..*\\.lavarage\\.com$'] // Regex patterns
+  },
+});
+```
+
+### Wildcard Matching
+
+- `*.example.com` - Matches any subdomain (e.g., `api.example.com`, `www.example.com`)
+- `example.com` - Matches the domain and all subdomains
+
+### Update Host Filter at Runtime
+
+```typescript
+telemetry.updateHostFilter({
+  mode: 'exclude',
+  hosts: ['analytics.google.com', '*.tracking.com']
+});
+```
+
+## Error Filtering
+
+Filter which errors are captured using include/exclude patterns.
+
+### Example 1: Only Capture Specific Errors
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+  errorFilters: {
+    include: [
+      'Failed to fetch',
+      'Network error',
+      'Transaction.*failed',
+      'RPC.*error'
+    ]
+  }
+});
+```
+
+### Example 2: Exclude Noisy Errors
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+  errorFilters: {
+    exclude: [
+      'ResizeObserver',
+      'Extension context invalidated',
+      'Script error',
+      'Non-Error promise rejection'
+    ]
+  }
+});
+```
+
+### Example 3: Combined Filtering
+
+```typescript
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+  errorFilters: {
+    include: ['.*'], // Capture everything
+    exclude: [
+      'chrome-extension://',
+      'moz-extension://',
+      'webkit-masked-url://',
+      'ResizeObserver loop',
+      'Script error\\.'
+    ]
+  }
+});
+```
+
+**Filter Logic:**
+- If `include` patterns are provided, ONLY errors matching those patterns are captured
+- If `exclude` patterns are provided, all errors EXCEPT those matching patterns are captured
+- If both are provided, `include` is applied first, then `exclude`
+
+## Axios Integration
+
+If you're using Axios, you can intercept Axios requests:
+
+```typescript
+import axios from 'axios';
+import { LavarageTelemetry } from '@lavarage/telemetry';
+
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+});
+
+const axiosInstance = axios.create({
+  baseURL: 'https://api.lavarage.com',
+});
+
+// Intercept Axios requests
+telemetry.interceptAxios(axiosInstance);
+```
+
+## Security Features
+
+### Automatic Data Sanitization
+
+The SDK automatically sanitizes sensitive data in all payloads and responses:
+
+- `privateKey`
+- `mnemonic`
+- `password`
+- `secret`
+- `token`
+- `apiKey`
+- `authorization`
+
+Sensitive fields are replaced with `[REDACTED]` recursively in nested objects and arrays.
+
+### Silent Error Handling
+
+All telemetry operations are wrapped in try-catch blocks. Telemetry errors will never disrupt your application.
+
+## API Reference
+
+### Methods
+
+#### `setWallet(walletAddress: string)`
+
+Set the current wallet address and trigger a login event.
+
+```typescript
+telemetry.setWallet('YourWalletAddress123...');
+```
+
+#### `interceptFetch()`
+
+Intercept the global `fetch` API to capture network requests.
+
+```typescript
+telemetry.interceptFetch();
+```
+
+#### `interceptAxios(axiosInstance: any)`
+
+Intercept an Axios instance to capture network requests.
+
+```typescript
+telemetry.interceptAxios(axiosInstance);
+```
+
+#### `trackPairView(pair: string, metadata?: object)`
+
+Track a trading pair view event.
+
+```typescript
+telemetry.trackPairView('SOL/USDC', {
+  source: 'homepage',
+  category: 'trending'
+});
+```
+
+#### `trackSystemEvent(category: string, message: string, level?: string, metadata?: object)`
+
+Track a system event (not tied to any wallet address). System events are displayed in a separate panel in the dashboard.
+
+```typescript
+// Track app startup
+telemetry.trackSystemEvent('app_start', 'Application initialized', 'info');
+
+// Track feature usage
+telemetry.trackSystemEvent('feature_used', 'User enabled dark mode', 'info', {
+  feature: 'dark_mode',
+  version: '1.2.3'
+});
+
+// Track configuration changes
+telemetry.trackSystemEvent('config_change', 'API endpoint updated', 'warning', {
+  old_endpoint: 'https://api.example.com',
+  new_endpoint: 'https://api2.example.com'
+});
+
+// Track errors
+telemetry.trackSystemEvent('system_error', 'Failed to load configuration', 'error', {
+  error_code: 'CONFIG_LOAD_FAILED'
+});
+```
+
+**Parameters:**
+- `category` - Event category (e.g., 'app_start', 'feature_used', 'config_change')
+- `message` - Event message
+- `level` - Event level: 'info' | 'warning' | 'error' | 'debug' (default: 'info')
+- `metadata` - Optional additional metadata object
+
+#### `updateHostFilter(captureHosts: HostFilterInput)`
+
+Update the host filter configuration at runtime.
+
+```typescript
+telemetry.updateHostFilter({
+  mode: 'exclude',
+  hosts: ['analytics.google.com']
+});
+```
+
+#### `logWalletEvent(walletAddress: string, eventType: string, message: string, metadata?: object)`
+
+Log a custom event with wallet address (backend-friendly method). Events are queued and sent in batches.
+
+```typescript
+telemetry.logWalletEvent(
+  'WalletAddress123...',
+  'transaction',
+  'Transaction completed',
+  { txHash: '0x...', amount: '100' }
+);
+```
+
+#### `sendLog(walletAddress: string, eventType: string, message: string, metadata?: object): Promise<void>`
+
+Send a log event immediately, bypassing the batch queue. Useful for critical logs.
+
+```typescript
+await telemetry.sendLog(
+  'WalletAddress123...',
+  'critical',
+  'Security alert',
+  { alertType: 'suspicious_activity' }
+);
+```
+
+#### `destroy()`
+
+Clean up the telemetry instance, restore original functions, and flush remaining events.
+
+```typescript
+telemetry.destroy();
+```
+
+## Event Types
+
+The SDK tracks the following event types:
+
+- **login**: Triggered when `setWallet()` is called
+- **pair_view**: Trading pair view events
+- **error**: Console errors, uncaught exceptions, and unhandled promise rejections
+- **request**: Network requests (fetch/Axios)
+- **system_event**: System-level events not tied to any wallet address (displayed in separate dashboard panel)
+- **log**: Custom log events (via `logWalletEvent()` or `sendLog()`)
+
+## Batching
+
+Events are automatically batched and sent to the backend:
+
+- **Default batch size**: 50 events
+- **Default flush interval**: 5 seconds
+- **Automatic flush**: On page unload (using `keepalive` for reliable delivery)
+
+## Backend Usage
+
+The SDK works in both browser and Node.js environments. For backend applications, you can use a subset of features focused on manual logging.
+
+### Installation for Backend
+
+```bash
+npm install @lavarage/telemetry
+# For Node.js < 18, also install node-fetch:
+npm install node-fetch@2
+```
+
+### Backend Quick Start
+
+```typescript
+import { LavarageTelemetry } from '@lavarage/telemetry';
+
+// Initialize telemetry for backend
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'my-backend-service',
+  batchSize: 100, // Larger batches for backend
+  flushInterval: 10000, // Flush every 10 seconds
+});
+
+// Log events related to a wallet address
+telemetry.logWalletEvent(
+  'DummyWallet123456789',
+  'transaction',
+  'Transaction completed successfully',
+  {
+    txHash: '0x123...',
+    amount: '100.5',
+    token: 'USDC'
+  }
+);
+
+// Log errors with wallet context
+telemetry.logWalletEvent(
+  'DummyWallet123456789',
+  'error',
+  'Failed to process transaction',
+  {
+    errorCode: 'INSUFFICIENT_FUNDS',
+    attemptedAmount: '200.0'
+  }
+);
+
+// Send critical logs immediately (bypasses batching)
+await telemetry.sendLog(
+  'DummyWallet123456789',
+  'critical',
+  'Security alert: suspicious activity detected',
+  {
+    alertType: 'unusual_pattern',
+    severity: 'high'
+  }
+);
+```
+
+### Backend API Methods
+
+#### `logWalletEvent(walletAddress: string, eventType: string, message: string, metadata?: object)`
+
+Queue a log event with a wallet address. Events are batched and sent automatically.
+
+```typescript
+telemetry.logWalletEvent(
+  'WalletAddress123...',
+  'transaction', // Event type (e.g., 'transaction', 'error', 'action')
+  'Transaction completed', // Log message
+  { txHash: '0x...', amount: '100' } // Optional metadata
+);
+```
+
+#### `sendLog(walletAddress: string, eventType: string, message: string, metadata?: object): Promise<void>`
+
+Send a log event immediately, bypassing the batch queue. Useful for critical logs that need immediate delivery.
+
+```typescript
+await telemetry.sendLog(
+  'WalletAddress123...',
+  'critical',
+  'Security alert',
+  { alertType: 'suspicious_activity' }
+);
+```
+
+#### `setWallet(walletAddress: string)`
+
+Set the default wallet address for subsequent events. This is optional for backend use since you can specify the wallet in each log call.
+
+```typescript
+telemetry.setWallet('WalletAddress123...');
+// Now all events will use this wallet by default
+telemetry.logWalletEvent(
+  null, // Will use the wallet set above
+  'action',
+  'User performed action'
+);
+```
+
+### Backend Example: Express.js Middleware
+
+```typescript
+import express from 'express';
+import { LavarageTelemetry } from '@lavarage/telemetry';
+
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: process.env.TELEMETRY_ENDPOINT!,
+  platform: 'api-server',
+});
+
+const app = express();
+
+// Middleware to log wallet-related requests
+app.use('/api/wallet/:walletAddress', (req, res, next) => {
+  const walletAddress = req.params.walletAddress;
+  
+  // Log the request
+  telemetry.logWalletEvent(
+    walletAddress,
+    'api_request',
+    `${req.method} ${req.path}`,
+    {
+      method: req.method,
+      path: req.path,
+      userAgent: req.get('user-agent'),
+    }
+  );
+  
+  next();
+});
+
+// Log transaction events
+app.post('/api/transactions', async (req, res) => {
+  const { walletAddress, txHash } = req.body;
+  
+  try {
+    // Process transaction...
+    
+    telemetry.logWalletEvent(
+      walletAddress,
+      'transaction',
+      'Transaction processed successfully',
+      { txHash, status: 'success' }
+    );
+    
+    res.json({ success: true });
+  } catch (error) {
+    telemetry.logWalletEvent(
+      walletAddress,
+      'error',
+      'Transaction failed',
+      { txHash, error: error.message }
+    );
+    
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+### Backend Example: Error Handler
+
+```typescript
+import { LavarageTelemetry } from '@lavarage/telemetry';
+
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: process.env.TELEMETRY_ENDPOINT!,
+  platform: 'api-server',
+});
+
+// Global error handler
+process.on('uncaughtException', (error) => {
+  // Extract wallet from error context if available
+  const walletAddress = (error as any).walletAddress || null;
+  
+  if (walletAddress) {
+    telemetry.logWalletEvent(
+      walletAddress,
+      'error',
+      `Uncaught exception: ${error.message}`,
+      {
+        stack: error.stack,
+        name: error.name,
+      }
+    );
+  }
+});
+```
+
+## Browser Support
+
+- Modern browsers with ES2020 support
+- Node.js 18+ (native fetch support)
+- Node.js < 18 requires `node-fetch` package
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { TelemetryConfig, TelemetryEvent, ErrorEvent, RequestEvent, HostFilterInput, HostFilterConfig, ErrorFilterConfig, SystemEvent } from './types';
+export type { TelemetryConfig, TelemetryEvent, ErrorEvent, RequestEvent, HostFilterInput, HostFilterConfig, ErrorFilterConfig, SystemEvent, };
+export declare class LavarageTelemetry {
+    private apiEndpoint;
+    private platform;
+    private wallet;
+    private sessionId;
+    private eventQueue;
+    private flushInterval;
+    private batchSize;
+    private flushTimer;
+    private hostFilter;
+    private errorFilters;
+    private originalFetch;
+    private originalConsoleError;
+    private requestMap;
+    constructor(config: TelemetryConfig);
+    private generateSessionId;
+    private generateRequestId;
+    private normalizeHostFilter;
+    private shouldCaptureHost;
+    private matchesHost;
+    private shouldCaptureError;
+    private sanitizePayload;
+    private safeReadResponse;
+    private enqueue;
+    private startFlushTimer;
+    private getFetch;
+    private flush;
+    private initializeCapture;
+    private trackError;
+    setWallet(walletAddress: string): void;
+    interceptFetch(): void;
+    interceptAxios(axiosInstance: any): void;
+    trackPairView(pair: string, metadata?: object): void;
+    /**
+     * Track a system event (not tied to any wallet address)
+     * System events are displayed in a separate panel in the dashboard
+     * @param category - Event category (e.g., 'app_start', 'feature_used', 'config_change')
+     * @param message - Event message
+     * @param level - Event level (info, warning, error, debug)
+     * @param metadata - Optional additional metadata
+     */
+    trackSystemEvent(category: string, message: string, level?: 'info' | 'warning' | 'error' | 'debug', metadata?: object): void;
+    /**
+     * Log a custom event with wallet address (backend-friendly method)
+     * @param walletAddress - The wallet address associated with this log
+     * @param eventType - Type of event (e.g., 'transaction', 'error', 'action')
+     * @param message - Log message
+     * @param metadata - Optional additional metadata
+     */
+    logWalletEvent(walletAddress: string, eventType: string, message: string, metadata?: object): void;
+    /**
+     * Send a log event immediately (bypasses batching, useful for critical logs)
+     * @param walletAddress - The wallet address associated with this log
+     * @param eventType - Type of event
+     * @param message - Log message
+     * @param metadata - Optional additional metadata
+     */
+    sendLog(walletAddress: string, eventType: string, message: string, metadata?: object): Promise<void>;
+    updateHostFilter(captureHosts: HostFilterInput): void;
+    destroy(): void;
+}

package/dist/index.js

@@ -0,0 +1,623 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LavarageTelemetry = void 0;
+class LavarageTelemetry {
+    constructor(config) {
+        this.wallet = null;
+        this.eventQueue = [];
+        this.flushTimer = null;
+        this.originalFetch = null;
+        this.originalConsoleError = null;
+        this.requestMap = new Map();
+        this.apiEndpoint = config.apiEndpoint;
+        this.platform = config.platform;
+        this.sessionId = this.generateSessionId();
+        this.flushInterval = config.flushInterval ?? 5000;
+        this.batchSize = config.batchSize ?? 50;
+        this.hostFilter = this.normalizeHostFilter(config.captureHosts);
+        this.errorFilters = config.errorFilters ?? {};
+        // Initialize event capture
+        this.initializeCapture();
+        // Start flush timer
+        this.startFlushTimer();
+        // Setup beforeunload handler
+        if (typeof window !== 'undefined') {
+            window.addEventListener('beforeunload', () => {
+                this.flush(true);
+            });
+        }
+    }
+    generateSessionId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}-${Math.random().toString(36).substring(2, 15)}`;
+    }
+    generateRequestId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    }
+    normalizeHostFilter(input) {
+        if (!input) {
+            return { mode: 'all' };
+        }
+        if (typeof input === 'string') {
+            return {
+                mode: 'include',
+                hosts: [input],
+            };
+        }
+        if (Array.isArray(input)) {
+            return {
+                mode: 'include',
+                hosts: input,
+            };
+        }
+        return input;
+    }
+    shouldCaptureHost(url) {
+        try {
+            const urlObj = new URL(url);
+            const hostname = urlObj.hostname;
+            const { mode, hosts = [], patterns = [] } = this.hostFilter;
+            if (mode === 'all')
+                return true;
+            if (mode === 'none')
+                return false;
+            // Check host patterns
+            for (const host of hosts) {
+                if (this.matchesHost(hostname, host)) {
+                    return mode === 'include';
+                }
+            }
+            // Check regex patterns
+            for (const pattern of patterns) {
+                try {
+                    const regex = new RegExp(pattern, 'i');
+                    if (regex.test(hostname)) {
+                        return mode === 'include';
+                    }
+                }
+                catch {
+                    // Invalid regex, skip
+                }
+            }
+            // If include mode and no matches, don't capture
+            // If exclude mode and no matches, capture
+            return mode === 'exclude';
+        }
+        catch {
+            // Invalid URL, don't capture
+            return false;
+        }
+    }
+    matchesHost(hostname, pattern) {
+        // Exact match
+        if (hostname === pattern)
+            return true;
+        // Wildcard subdomain: *.example.com
+        if (pattern.startsWith('*.')) {
+            const domain = pattern.substring(2);
+            return hostname === domain || hostname.endsWith('.' + domain);
+        }
+        // Domain match (matches domain and all subdomains)
+        if (hostname === pattern || hostname.endsWith('.' + pattern)) {
+            return true;
+        }
+        return false;
+    }
+    shouldCaptureError(errorMessage) {
+        const { include, exclude } = this.errorFilters;
+        // If no filters, capture everything
+        if (!include && !exclude)
+            return true;
+        // If include patterns specified, only capture matching errors
+        if (include && include.length > 0) {
+            const matchesInclude = include.some(pattern => {
+                try {
+                    return new RegExp(pattern, 'i').test(errorMessage);
+                }
+                catch {
+                    console.warn('Invalid error filter pattern:', pattern);
+                    return false;
+                }
+            });
+            if (!matchesInclude)
+                return false;
+        }
+        // If exclude patterns specified, exclude matching errors
+        if (exclude && exclude.length > 0) {
+            const matchesExclude = exclude.some(pattern => {
+                try {
+                    return new RegExp(pattern, 'i').test(errorMessage);
+                }
+                catch {
+                    console.warn('Invalid error filter pattern:', pattern);
+                    return false;
+                }
+            });
+            if (matchesExclude)
+                return false;
+        }
+        return true;
+    }
+    sanitizePayload(data) {
+        if (data === null || data === undefined) {
+            return data;
+        }
+        if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
+            return data;
+        }
+        if (Array.isArray(data)) {
+            return data.map(item => this.sanitizePayload(item));
+        }
+        if (typeof data === 'object') {
+            const sanitized = {};
+            const sensitiveKeys = ['privateKey', 'mnemonic', 'password', 'secret', 'token', 'apiKey', 'authorization'];
+            for (const [key, value] of Object.entries(data)) {
+                const lowerKey = key.toLowerCase();
+                const isSensitive = sensitiveKeys.some(sk => lowerKey.includes(sk.toLowerCase()));
+                if (isSensitive) {
+                    sanitized[key] = '[REDACTED]';
+                }
+                else {
+                    sanitized[key] = this.sanitizePayload(value);
+                }
+            }
+            return sanitized;
+        }
+        return data;
+    }
+    async safeReadResponse(response) {
+        try {
+            const cloned = response.clone();
+            const contentType = cloned.headers.get('content-type') || '';
+            if (contentType.includes('application/json')) {
+                const text = await cloned.text();
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return text;
+                }
+            }
+            if (contentType.includes('text/')) {
+                return await cloned.text();
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    enqueue(event) {
+        try {
+            this.eventQueue.push(event);
+            // Flush if batch size reached
+            if (this.eventQueue.length >= this.batchSize) {
+                this.flush();
+            }
+        }
+        catch (error) {
+            // Silently fail - don't disrupt the app
+        }
+    }
+    startFlushTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flushTimer = setInterval(() => {
+            this.flush();
+        }, this.flushInterval);
+    }
+    getFetch() {
+        // Use global fetch if available (Node.js 18+, modern browsers)
+        if (typeof fetch !== 'undefined') {
+            return fetch;
+        }
+        // Try to use node-fetch if available (for older Node.js)
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const nodeFetch = require('node-fetch');
+            // Handle both node-fetch v2 (default export) and v3 (named export)
+            return (nodeFetch.default || nodeFetch);
+        }
+        catch {
+            // Silently fail - will be caught in flush method
+            throw new Error('fetch is not available. Please use Node.js 18+ or install node-fetch');
+        }
+    }
+    async flush(useKeepalive = false) {
+        if (this.eventQueue.length === 0) {
+            return;
+        }
+        const events = [...this.eventQueue];
+        this.eventQueue = [];
+        try {
+            const fetchFn = this.getFetch();
+            const requestInit = {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ events }),
+            };
+            if (useKeepalive && typeof window !== 'undefined') {
+                requestInit.keepalive = true;
+            }
+            await fetchFn(`${this.apiEndpoint}/telemetry/batch`, requestInit);
+        }
+        catch (error) {
+            // Silently fail - don't disrupt the app
+            // Optionally, could re-queue events on failure, but for simplicity we'll drop them
+        }
+    }
+    initializeCapture() {
+        // Capture console errors
+        if (typeof console !== 'undefined' && console.error) {
+            this.originalConsoleError = console.error.bind(console);
+            console.error = (...args) => {
+                this.originalConsoleError?.(...args);
+                try {
+                    const message = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+                    if (this.shouldCaptureError(message)) {
+                        this.trackError({
+                            type: 'console',
+                            message,
+                        });
+                    }
+                }
+                catch {
+                    // Silently fail
+                }
+            };
+        }
+        // Capture uncaught errors
+        if (typeof window !== 'undefined') {
+            window.addEventListener('error', (event) => {
+                try {
+                    const message = event.message || 'Unknown error';
+                    if (this.shouldCaptureError(message)) {
+                        this.trackError({
+                            type: 'uncaught',
+                            message,
+                            stack: event.error?.stack,
+                            filename: event.filename,
+                            lineno: event.lineno,
+                            colno: event.colno,
+                        });
+                    }
+                }
+                catch {
+                    // Silently fail
+                }
+            });
+            // Capture unhandled promise rejections
+            window.addEventListener('unhandledrejection', (event) => {
+                try {
+                    const reason = event.reason;
+                    const message = reason instanceof Error ? reason.message : String(reason);
+                    if (this.shouldCaptureError(message)) {
+                        this.trackError({
+                            type: 'promise',
+                            message,
+                            stack: reason instanceof Error ? reason.stack : undefined,
+                        });
+                    }
+                }
+                catch {
+                    // Silently fail
+                }
+            });
+        }
+    }
+    trackError(error) {
+        this.enqueue({
+            type: 'error',
+            wallet: this.wallet,
+            platform: this.platform,
+            error,
+            timestamp: Date.now(),
+            sessionId: this.sessionId,
+            url: typeof window !== 'undefined' ? window.location.href : '',
+        });
+    }
+    setWallet(walletAddress) {
+        try {
+            this.wallet = walletAddress;
+            // Track login event
+            this.enqueue({
+                type: 'login',
+                wallet: this.wallet,
+                platform: this.platform,
+                timestamp: Date.now(),
+                sessionId: this.sessionId,
+                userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+            });
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    interceptFetch() {
+        // Only intercept in browser environments
+        if (typeof window === 'undefined') {
+            return;
+        }
+        // Check if fetch is available
+        if (typeof fetch === 'undefined') {
+            return;
+        }
+        if (this.originalFetch) {
+            return; // Already intercepted
+        }
+        this.originalFetch = window.fetch.bind(window);
+        window.fetch = async (input, init) => {
+            const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+            const method = init?.method || (typeof input === 'object' && 'method' in input ? input.method : 'GET');
+            // Check if we should capture this request
+            if (!this.shouldCaptureHost(url)) {
+                return this.originalFetch(input, init);
+            }
+            const requestId = this.generateRequestId();
+            const startTime = Date.now();
+            const payload = init?.body ? this.sanitizePayload(init.body) : undefined;
+            // Store request info
+            this.requestMap.set(requestId, { startTime, url, method });
+            // Track request start
+            this.enqueue({
+                type: 'request',
+                wallet: this.wallet,
+                platform: this.platform,
+                requestId,
+                url,
+                method,
+                payload: payload ? this.sanitizePayload(payload) : undefined,
+                timestamp: startTime,
+                sessionId: this.sessionId,
+            });
+            try {
+                const response = await this.originalFetch(input, init);
+                const duration = Date.now() - startTime;
+                // Read response safely
+                const responseData = await this.safeReadResponse(response);
+                // Track request completion
+                this.enqueue({
+                    type: 'request',
+                    wallet: this.wallet,
+                    platform: this.platform,
+                    requestId,
+                    url,
+                    method,
+                    status: response.status,
+                    response: this.sanitizePayload(responseData),
+                    duration,
+                    timestamp: Date.now(),
+                    sessionId: this.sessionId,
+                });
+                this.requestMap.delete(requestId);
+                return response;
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                // Track request error
+                this.enqueue({
+                    type: 'request',
+                    wallet: this.wallet,
+                    platform: this.platform,
+                    requestId,
+                    url,
+                    method,
+                    error: errorMessage,
+                    duration,
+                    timestamp: Date.now(),
+                    sessionId: this.sessionId,
+                });
+                this.requestMap.delete(requestId);
+                throw error;
+            }
+        };
+    }
+    interceptAxios(axiosInstance) {
+        if (!axiosInstance || !axiosInstance.interceptors) {
+            return;
+        }
+        // Request interceptor
+        axiosInstance.interceptors.request.use((config) => {
+            const url = config.url || (config.baseURL ? `${config.baseURL}${config.url || ''}` : '');
+            const method = config.method?.toUpperCase() || 'GET';
+            if (!this.shouldCaptureHost(url)) {
+                return config;
+            }
+            const requestId = this.generateRequestId();
+            const startTime = Date.now();
+            // Store request metadata
+            config._telemetryRequestId = requestId;
+            config._telemetryStartTime = startTime;
+            // Track request start
+            this.enqueue({
+                type: 'request',
+                wallet: this.wallet,
+                platform: this.platform,
+                requestId,
+                url,
+                method,
+                payload: config.data ? this.sanitizePayload(config.data) : undefined,
+                timestamp: startTime,
+                sessionId: this.sessionId,
+            });
+            return config;
+        }, (error) => {
+            return Promise.reject(error);
+        });
+        // Response interceptor
+        axiosInstance.interceptors.response.use((response) => {
+            const config = response.config || {};
+            const requestId = config._telemetryRequestId;
+            const startTime = config._telemetryStartTime;
+            if (requestId && startTime) {
+                const duration = Date.now() - startTime;
+                const url = response.config?.url || response.request?.responseURL || '';
+                this.enqueue({
+                    type: 'request',
+                    wallet: this.wallet,
+                    platform: this.platform,
+                    requestId,
+                    url,
+                    method: config.method?.toUpperCase() || 'GET',
+                    status: response.status,
+                    response: this.sanitizePayload(response.data),
+                    duration,
+                    timestamp: Date.now(),
+                    sessionId: this.sessionId,
+                });
+            }
+            return response;
+        }, (error) => {
+            const config = error.config || {};
+            const requestId = config._telemetryRequestId;
+            const startTime = config._telemetryStartTime;
+            if (requestId && startTime) {
+                const duration = Date.now() - startTime;
+                const url = config.url || error.request?.responseURL || '';
+                const errorMessage = error.message || 'Request failed';
+                this.enqueue({
+                    type: 'request',
+                    wallet: this.wallet,
+                    platform: this.platform,
+                    requestId,
+                    url,
+                    method: config.method?.toUpperCase() || 'GET',
+                    error: errorMessage,
+                    duration,
+                    timestamp: Date.now(),
+                    sessionId: this.sessionId,
+                });
+            }
+            return Promise.reject(error);
+        });
+    }
+    trackPairView(pair, metadata) {
+        try {
+            this.enqueue({
+                type: 'pair_view',
+                wallet: this.wallet,
+                platform: this.platform,
+                pair,
+                metadata: metadata ? this.sanitizePayload(metadata) : undefined,
+                timestamp: Date.now(),
+                sessionId: this.sessionId,
+            });
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    /**
+     * Track a system event (not tied to any wallet address)
+     * System events are displayed in a separate panel in the dashboard
+     * @param category - Event category (e.g., 'app_start', 'feature_used', 'config_change')
+     * @param message - Event message
+     * @param level - Event level (info, warning, error, debug)
+     * @param metadata - Optional additional metadata
+     */
+    trackSystemEvent(category, message, level = 'info', metadata) {
+        try {
+            this.enqueue({
+                type: 'system_event',
+                wallet: null, // System events are not tied to wallets
+                platform: this.platform,
+                category,
+                message,
+                level,
+                metadata: metadata ? this.sanitizePayload(metadata) : undefined,
+                timestamp: Date.now(),
+                sessionId: this.sessionId,
+                url: typeof window !== 'undefined' ? window.location.href : '',
+            });
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    /**
+     * Log a custom event with wallet address (backend-friendly method)
+     * @param walletAddress - The wallet address associated with this log
+     * @param eventType - Type of event (e.g., 'transaction', 'error', 'action')
+     * @param message - Log message
+     * @param metadata - Optional additional metadata
+     */
+    logWalletEvent(walletAddress, eventType, message, metadata) {
+        try {
+            this.enqueue({
+                type: 'log', // Custom log type
+                wallet: walletAddress,
+                platform: this.platform,
+                logType: eventType,
+                message,
+                metadata: metadata ? this.sanitizePayload(metadata) : undefined,
+                timestamp: Date.now(),
+                sessionId: this.sessionId,
+                url: typeof window !== 'undefined' ? window.location.href : '',
+            });
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    /**
+     * Send a log event immediately (bypasses batching, useful for critical logs)
+     * @param walletAddress - The wallet address associated with this log
+     * @param eventType - Type of event
+     * @param message - Log message
+     * @param metadata - Optional additional metadata
+     */
+    async sendLog(walletAddress, eventType, message, metadata) {
+        try {
+            const event = {
+                type: 'log',
+                wallet: walletAddress,
+                platform: this.platform,
+                logType: eventType,
+                message,
+                metadata: metadata ? this.sanitizePayload(metadata) : undefined,
+                timestamp: Date.now(),
+                sessionId: this.sessionId,
+                url: typeof window !== 'undefined' ? window.location.href : '',
+            };
+            const fetchFn = this.getFetch();
+            await fetchFn(`${this.apiEndpoint}/telemetry/batch`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ events: [event] }),
+            });
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    updateHostFilter(captureHosts) {
+        try {
+            this.hostFilter = this.normalizeHostFilter(captureHosts);
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    destroy() {
+        // Restore original functions
+        if (this.originalFetch && typeof window !== 'undefined') {
+            window.fetch = this.originalFetch;
+        }
+        if (this.originalConsoleError && typeof console !== 'undefined') {
+            console.error = this.originalConsoleError;
+        }
+        // Clear timer
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Flush remaining events
+        this.flush(true);
+    }
+}
+exports.LavarageTelemetry = LavarageTelemetry;

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+export interface TelemetryConfig {
+    apiEndpoint: string;
+    platform: string;
+    captureHosts?: HostFilterInput;
+    errorFilters?: ErrorFilterConfig;
+    batchSize?: number;
+    flushInterval?: number;
+}
+export type HostFilterInput = string | string[] | HostFilterConfig;
+export interface HostFilterConfig {
+    mode: 'all' | 'none' | 'include' | 'exclude';
+    hosts?: string[];
+    patterns?: string[];
+}
+export interface ErrorFilterConfig {
+    include?: string[];
+    exclude?: string[];
+}
+export interface TelemetryEvent {
+    type: 'login' | 'pair_view' | 'error' | 'request' | 'system_event';
+    wallet: string | null;
+    platform: string;
+    timestamp: number;
+    sessionId: string;
+    [key: string]: any;
+}
+export interface SystemEvent {
+    category: string;
+    message: string;
+    level?: 'info' | 'warning' | 'error' | 'debug';
+    metadata?: object;
+}
+export interface ErrorEvent {
+    type: 'console' | 'uncaught' | 'promise';
+    message: string;
+    stack?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+}
+export interface RequestEvent {
+    requestId: string;
+    url: string;
+    method?: string;
+    status?: number;
+    payload?: any;
+    response?: any;
+    error?: string;
+    duration?: number;
+    timestamp: number;
+    type: 'complete' | 'error';
+}
+export interface BatchIngestRequest {
+    events: TelemetryEvent[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lavarage/telemetry",
+  "version": "1.0.0",
+  "description": "Production telemetry SDK for Lavarage and partner applications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "keywords": ["telemetry", "analytics", "monitoring", "lavarage"],
+  "author": "Lavarage",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "node-fetch": "^2.6.0 || ^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "node-fetch": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0"
+  },
+  "files": ["dist", "README.md"]
+}
+