@devskin/browser-sdk 1.0.0

package/README.md

@@ -0,0 +1,298 @@
+# DevSkin Browser SDK
+
+Comprehensive browser monitoring SDK for collecting user analytics, performance metrics, errors, and session recordings.
+
+## Features
+
+- 📊 **Product Analytics**: Track custom events, page views, and user behavior
+- 🎯 **Session Recording**: Record and replay user sessions with privacy controls
+- ⚡ **Performance Monitoring**: Collect Core Web Vitals (LCP, FID, CLS, FCP, TTFB)
+- 🐛 **Error Tracking**: Automatic error capture with breadcrumbs and context
+- 🌐 **Network Monitoring**: Track all network requests (fetch, XHR)
+- 📱 **Device Detection**: Comprehensive device, browser, and OS information
+- 🌍 **Geolocation**: Optional location tracking with user permission
+- 🔒 **Privacy-First**: Built-in privacy controls and data masking
+
+## Installation
+
+### Via CDN
+
+```html
+<script src="https://cdn.devskin.com/sdk/devskin.umd.min.js"></script>
+<script>
+  DevSkin.init({
+    apiKey: 'your-api-key',
+    appId: 'your-app-id',
+  });
+</script>
+```
+
+### Via npm
+
+```bash
+npm install @devskin/browser-sdk
+```
+
+```javascript
+import DevSkin from '@devskin/browser-sdk';
+
+DevSkin.init({
+  apiKey: 'your-api-key',
+  appId: 'your-app-id',
+});
+```
+
+## Configuration
+
+```javascript
+DevSkin.init({
+  // Required
+  apiKey: 'your-api-key',
+  appId: 'your-app-id',
+
+  // Optional
+  apiUrl: 'https://api.devskin.com',
+  debug: false,
+  environment: 'production',
+  release: '1.0.0',
+
+  // Feature flags
+  captureWebVitals: true,
+  captureNetworkRequests: true,
+  captureErrors: true,
+  captureUserAgent: true,
+  captureLocation: true,
+  captureDevice: true,
+
+  // Session Recording
+  sessionRecording: {
+    enabled: true,
+    maskAllInputs: true,
+    maskTextSelector: '.sensitive',
+    blockSelector: '.private',
+    sampling: 0.1, // Record 10% of sessions
+    recordCanvas: false,
+    recordCrossOriginIframes: false,
+    ignoreClass: 'devskin-block',
+  },
+
+  // Heatmap & User Behavior
+  heatmapOptions: {
+    enabled: true,
+    trackClicks: true, // Track click heatmaps
+    trackScroll: true, // Track scroll depth
+    trackMouseMovement: false, // Track mouse movement (can be heavy)
+    mouseMoveSampling: 0.1, // Sample 10% of mouse movements
+  },
+
+  // Network options
+  networkRequestOptions: {
+    ignoreUrls: [/analytics\.google\.com/],
+    captureHeaders: false,
+    captureBody: false,
+    captureFailedOnly: false,
+  },
+
+  // Error options
+  errorOptions: {
+    ignoreErrors: [/Script error/i],
+    denyUrls: [/extensions\//],
+    includeLocalVariables: true,
+    maxBreadcrumbs: 30,
+  },
+
+  // Privacy
+  privacy: {
+    respectDoNotTrack: true,
+    cookieConsent: false,
+  },
+
+  // Long task threshold (ms)
+  longTaskThreshold: 50,
+
+  // Callbacks
+  beforeSend: (event) => {
+    // Modify or filter events before sending
+    return event;
+  },
+});
+```
+
+## Usage
+
+### Track Events
+
+```javascript
+// Track a custom event
+DevSkin.track('button_clicked', {
+  buttonId: 'signup',
+  page: '/landing',
+});
+
+// Track page view
+DevSkin.trackPageView({
+  title: 'Home Page',
+});
+```
+
+### Identify Users
+
+```javascript
+DevSkin.identify('user-123', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  plan: 'premium',
+});
+```
+
+### Capture Errors
+
+```javascript
+try {
+  // Your code
+} catch (error) {
+  DevSkin.captureError(error, {
+    context: 'checkout_process',
+    step: 'payment',
+  });
+}
+```
+
+### Add Breadcrumbs
+
+```javascript
+DevSkin.addBreadcrumb({
+  category: 'ui',
+  message: 'User clicked submit button',
+  level: 'info',
+  data: {
+    formId: 'checkout-form',
+  },
+});
+```
+
+### Control Recording
+
+```javascript
+// Start recording
+DevSkin.startRecording();
+
+// Stop recording
+DevSkin.stopRecording();
+```
+
+### Privacy Controls
+
+```javascript
+// Opt out
+DevSkin.optOut();
+
+// Opt in
+DevSkin.optIn();
+```
+
+## Data Collected
+
+### Automatic Data Collection
+
+The SDK automatically collects:
+
+- **Browser Info**: Name, version, engine, language, viewport size
+- **Device Info**: Type (mobile/tablet/desktop), OS, screen resolution, memory, CPU cores
+- **Location Info**: URL, hostname, pathname, referrer, timezone
+- **Performance Metrics**: Core Web Vitals, navigation timing, resource timing
+- **Network Requests**: URL, method, status, duration, size
+- **Errors**: Message, stack trace, breadcrumbs, context
+- **User Actions**: Clicks, navigation, console logs
+- **Heatmap Data**: Click positions, scroll depth, mouse movement (if enabled)
+
+### Optional Data Collection
+
+With user permission:
+- **Geolocation**: Country, region, city, latitude, longitude
+- **Session Recordings**: Full DOM replay with privacy controls
+
+## Privacy & Security
+
+### Data Masking
+
+- All password inputs are automatically masked
+- Email addresses are masked by default
+- Use CSS classes to mask sensitive data:
+  - `.devskin-mask` - Mask text content
+  - `.devskin-block` - Completely block element from recording
+
+### Sampling
+
+Record only a percentage of sessions to reduce data collection:
+
+```javascript
+sessionRecording: {
+  enabled: true,
+  sampling: 0.1, // Record 10% of sessions
+}
+```
+
+### Do Not Track
+
+Respect browser DNT settings:
+
+```javascript
+privacy: {
+  respectDoNotTrack: true,
+}
+```
+
+### Cookie Consent
+
+Wait for cookie consent before tracking:
+
+```javascript
+privacy: {
+  cookieConsent: true,
+}
+
+// Later, after consent is given:
+DevSkin.optIn();
+```
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- Mobile browsers: iOS Safari 12+, Chrome Android
+
+## Performance Impact
+
+The SDK is designed for minimal performance impact:
+
+- Async initialization
+- Efficient event batching
+- Lazy loading of features
+- Compressed payloads
+- ~15KB gzipped
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Development build with watch
+npm run dev
+
+# Production build
+npm run build
+
+# Type checking
+npm run type-check
+```
+
+## License
+
+MIT License
+
+## Support
+
+For issues and questions, please visit: https://github.com/devskin/browser-sdk

package/dist/collectors/browser.d.ts

@@ -0,0 +1,11 @@
+import { DevSkinConfig, BrowserInfo } from '../types';
+export declare class BrowserCollector {
+    private config;
+    constructor(config: DevSkinConfig);
+    collect(): BrowserInfo;
+    private getBrowserName;
+    private getBrowserVersion;
+    private getEngine;
+    private getDoNotTrack;
+}
+//# sourceMappingURL=browser.d.ts.map

package/dist/collectors/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/collectors/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEtD,qBAAa,gBAAgB;IACf,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEzC,OAAO,IAAI,WAAW;IAmBtB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,aAAa;CAStB"}

package/dist/collectors/device.d.ts

@@ -0,0 +1,16 @@
+import { DevSkinConfig, DeviceInfo } from '../types';
+export declare class DeviceCollector {
+    private config;
+    constructor(config: DevSkinConfig);
+    collect(): DeviceInfo;
+    private getDeviceType;
+    private getVendor;
+    private getModel;
+    private getOS;
+    private getScreenInfo;
+    private getOrientation;
+    private getMemory;
+    private getCores;
+    private getConnection;
+}
+//# sourceMappingURL=device.d.ts.map

package/dist/collectors/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/collectors/device.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAErD,qBAAa,eAAe;IACd,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEzC,OAAO,IAAI,UAAU;IAarB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,KAAK;IAoCb,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,aAAa;CAatB"}

package/dist/collectors/error.d.ts

@@ -0,0 +1,23 @@
+import { DevSkinConfig, Breadcrumb } from '../types';
+import { Transport } from '../transport';
+export declare class ErrorCollector {
+    private config;
+    private transport;
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    constructor(config: DevSkinConfig, transport: Transport);
+    start(): void;
+    captureError(error: Error | string, context?: Record<string, any>): void;
+    addBreadcrumb(breadcrumb: {
+        category: string;
+        message: string;
+        level?: 'info' | 'warning' | 'error';
+        data?: Record<string, any>;
+    }): void;
+    private handleError;
+    private shouldIgnoreError;
+    private setupAutomaticBreadcrumbs;
+    private wrapConsole;
+    getBreadcrumbs(): Breadcrumb[];
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/collectors/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/collectors/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,qBAAa,cAAc;IAKvB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS;IALnB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,cAAc,CAAS;gBAGrB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS;IAK9B,KAAK,IAAI,IAAI;IAqBb,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAIxE,aAAa,CAAC,UAAU,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;QACrC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC5B,GAAG,IAAI;IAqBR,OAAO,CAAC,WAAW;IA2EnB,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,yBAAyB;IAwDjC,OAAO,CAAC,WAAW;IAsBnB,cAAc,IAAI,UAAU,EAAE;CAG/B"}

package/dist/collectors/heatmap.d.ts

@@ -0,0 +1,21 @@
+import { DevSkinConfig } from '../types';
+import { Transport } from '../transport';
+export declare class HeatmapCollector {
+    private config;
+    private transport;
+    private clickData;
+    private scrollData;
+    private mouseMoveData;
+    private maxScrollDepth;
+    private flushInterval;
+    private mouseMoveSampling;
+    constructor(config: DevSkinConfig, transport: Transport);
+    start(): void;
+    stop(): void;
+    private trackClicks;
+    private trackScrollDepth;
+    private trackMouseMovement;
+    private flush;
+    private getElementSelector;
+}
+//# sourceMappingURL=heatmap.d.ts.map

package/dist/collectors/heatmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../../src/collectors/heatmap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAkCzC,qBAAa,gBAAgB;IASzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS;IATnB,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,iBAAiB,CAAO;gBAGtB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS;IAG9B,KAAK,IAAI,IAAI;IAoCb,IAAI,IAAI,IAAI;IAQZ,OAAO,CAAC,WAAW;IA8CnB,OAAO,CAAC,gBAAgB;IA2CxB,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,KAAK;IA0Bb,OAAO,CAAC,kBAAkB;CAc3B"}

package/dist/collectors/location.d.ts

@@ -0,0 +1,10 @@
+import { DevSkinConfig, LocationInfo } from '../types';
+export declare class LocationCollector {
+    private config;
+    private geoData;
+    constructor(config: DevSkinConfig);
+    collect(): LocationInfo;
+    private requestGeolocation;
+    private reverseGeocode;
+}
+//# sourceMappingURL=location.d.ts.map

package/dist/collectors/location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../src/collectors/location.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvD,qBAAa,iBAAiB;IAUhB,OAAO,CAAC,MAAM;IAT1B,OAAO,CAAC,OAAO,CAOC;gBAEI,MAAM,EAAE,aAAa;IAMzC,OAAO,IAAI,YAAY;YAcT,kBAAkB;YAqClB,cAAc;CA6B7B"}

package/dist/collectors/network.d.ts

@@ -0,0 +1,15 @@
+import { DevSkinConfig } from '../types';
+import { Transport } from '../transport';
+export declare class NetworkCollector {
+    private config;
+    private transport;
+    constructor(config: DevSkinConfig, transport: Transport);
+    start(): void;
+    private interceptFetch;
+    private interceptXHR;
+    private shouldIgnoreUrl;
+    private getResponseSize;
+    private headersToObject;
+    private parseResponseHeaders;
+}
+//# sourceMappingURL=network.d.ts.map

package/dist/collectors/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/collectors/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS;gBADT,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS;IAG9B,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,cAAc;IA6FtB,OAAO,CAAC,YAAY;IA8HpB,OAAO,CAAC,eAAe;YAiBT,eAAe;IAS7B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,oBAAoB;CAgB7B"}

package/dist/collectors/performance.d.ts

@@ -0,0 +1,15 @@
+import { DevSkinConfig, PerformanceMetrics } from '../types';
+import { Transport } from '../transport';
+export declare class PerformanceCollector {
+    private config;
+    private transport;
+    private metrics;
+    constructor(config: DevSkinConfig, transport: Transport);
+    start(): void;
+    private handleMetric;
+    private collectNavigationTimings;
+    private collectResourceTimings;
+    private observeLongTasks;
+    getMetrics(): PerformanceMetrics;
+}
+//# sourceMappingURL=performance.d.ts.map

package/dist/collectors/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../src/collectors/performance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,qBAAa,oBAAoB;IAI7B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS;IAJnB,OAAO,CAAC,OAAO,CAA0B;gBAG/B,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS;IAG9B,KAAK,IAAI,IAAI;IAoBb,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,wBAAwB;IA0ChC,OAAO,CAAC,sBAAsB;IA0C9B,OAAO,CAAC,gBAAgB;IAiCxB,UAAU,IAAI,kBAAkB;CAGjC"}