{"_id":"@achado/web-analytics","_rev":"2-cbb2548309d4d627c6662149caf4ce1c","name":"@achado/web-analytics","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@achado/web-analytics","version":"0.0.1","_id":"@achado/web-analytics@0.0.1","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"dist":{"shasum":"e698acb70c09b89338a3f5df2f7cd93f5fb508c9","tarball":"https://registry.npmjs.org/@achado/web-analytics/-/web-analytics-0.0.1.tgz","fileCount":62,"integrity":"sha512-guLFj5UMGfxGabCJFb8JjYyncDK3sMmV20ONhigUZDGCB0JpiJKezOGvOx0m5IPm+cS8Sy6uwT62QR7TCRV9hA==","signatures":[{"sig":"MEUCIGEUNNSGulZ95wts1B6to75RlCNOAglDSeCCWNKOXFAcAiEA8B18ycId2H7o9MUjVa+8Xni5ag6x/ji8A/qMJG/y840=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":267676},"main":"dist/index.js","type":"commonjs","_from":"file:achado-web-analytics-0.0.1.tgz","types":"dist/types/index.d.ts","module":"dist/index.esm.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./plugin":{"types":"./dist/types/web-analytics-plugin.d.ts","import":"./dist/esm/web-analytics-plugin.js","require":"./dist/cjs/web-analytics-plugin.js"},"./package.json":"./package.json","./trackers/form":{"types":"./dist/types/trackers/form-tracker.d.ts","import":"./dist/esm/trackers/form-tracker.js","require":"./dist/cjs/trackers/form-tracker.js"},"./web-analytics":{"types":"./dist/types/web-analytics.d.ts","import":"./dist/esm/web-analytics.js","require":"./dist/cjs/web-analytics.js"},"./trackers/click":{"types":"./dist/types/trackers/click-tracker.d.ts","import":"./dist/esm/trackers/click-tracker.js","require":"./dist/cjs/trackers/click-tracker.js"},"./trackers/error":{"types":"./dist/types/trackers/error-tracker.d.ts","import":"./dist/esm/trackers/error-tracker.js","require":"./dist/cjs/trackers/error-tracker.js"},"./trackers/scroll":{"types":"./dist/types/trackers/scroll-tracker.d.ts","import":"./dist/esm/trackers/scroll-tracker.js","require":"./dist/cjs/trackers/scroll-tracker.js"}},"scripts":{"dev":"rollup -c -w","lint":"eslint src --ext .ts,.tsx","test":"vitest run","build":"rollup -c","clean":"rm -rf dist","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"achado","email":"achadolabs@gmail.com"},"_resolved":"/tmp/1c67f3a37967a16e1948d18b43bf53a7/achado-web-analytics-0.0.1.tgz","_integrity":"sha512-guLFj5UMGfxGabCJFb8JjYyncDK3sMmV20ONhigUZDGCB0JpiJKezOGvOx0m5IPm+cS8Sy6uwT62QR7TCRV9hA==","_npmVersion":"10.9.3","description":"Automatic web analytics tracking for Achado platform","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","dependencies":{"@achado/core":"0.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{},"peerDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/web-analytics_0.0.1_1759924668612_0.16561466296922056","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@achado/web-analytics","version":"0.0.2","type":"commonjs","description":"Automatic web analytics tracking for Achado platform","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/types/index.d.ts","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.js","types":"./dist/types/index.d.ts"},"./web-analytics":{"import":"./dist/esm/web-analytics.js","require":"./dist/cjs/web-analytics.js","types":"./dist/types/web-analytics.d.ts"},"./plugin":{"import":"./dist/esm/web-analytics-plugin.js","require":"./dist/cjs/web-analytics-plugin.js","types":"./dist/types/web-analytics-plugin.d.ts"},"./trackers/click":{"import":"./dist/esm/trackers/click-tracker.js","require":"./dist/cjs/trackers/click-tracker.js","types":"./dist/types/trackers/click-tracker.d.ts"},"./trackers/error":{"import":"./dist/esm/trackers/error-tracker.js","require":"./dist/cjs/trackers/error-tracker.js","types":"./dist/types/trackers/error-tracker.d.ts"},"./trackers/form":{"import":"./dist/esm/trackers/form-tracker.js","require":"./dist/cjs/trackers/form-tracker.js","types":"./dist/types/trackers/form-tracker.d.ts"},"./trackers/scroll":{"import":"./dist/esm/trackers/scroll-tracker.js","require":"./dist/cjs/trackers/scroll-tracker.js","types":"./dist/types/trackers/scroll-tracker.d.ts"},"./package.json":"./package.json"},"sideEffects":false,"dependencies":{"@achado/core":"0.0.2"},"devDependencies":{},"peerDependencies":{},"publishConfig":{"access":"public"},"scripts":{"build":"rollup -c","dev":"rollup -c -w","test":"vitest run","test:watch":"vitest","lint":"eslint src --ext .ts,.tsx","type-check":"tsc --noEmit","clean":"rm -rf dist"},"_id":"@achado/web-analytics@0.0.2","_integrity":"sha512-QJd7S+jsgxKQaij0FcvnZ+WNfLVhpVpTV7CPTmAYaG1N6i06jAceSI5ksyKW6a09tOmlonVoIWPnL5HgOuNjpA==","_resolved":"/tmp/a7ecc3ce35ca03f23d8bd607be05421a/achado-web-analytics-0.0.2.tgz","_from":"file:achado-web-analytics-0.0.2.tgz","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-QJd7S+jsgxKQaij0FcvnZ+WNfLVhpVpTV7CPTmAYaG1N6i06jAceSI5ksyKW6a09tOmlonVoIWPnL5HgOuNjpA==","shasum":"610153e20255216ed0e627a14f89404fb29bff6b","tarball":"https://registry.npmjs.org/@achado/web-analytics/-/web-analytics-0.0.2.tgz","fileCount":62,"unpackedSize":267676,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDBrd9qLMMAl/RF4D6fRDeO1TN5UtIUDJy6G/KXCv8oAwIhAPfY7GGLJgW3lDSCzAB9l+SFak2qxRTYnggRdsfZ1L9U"}]},"_npmUser":{"name":"achado","email":"achadolabs@gmail.com"},"directories":{},"maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/web-analytics_0.0.2_1759937318858_0.6322661467015702"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-08T11:57:48.491Z","modified":"2025-10-08T15:28:39.203Z","0.0.1":"2025-10-08T11:57:48.817Z","0.0.2":"2025-10-08T15:28:39.039Z"},"description":"Automatic web analytics tracking for Achado platform","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"readme":"# @achado/web-analytics\n\nAutomatic web analytics tracking for the Achado platform. Tracks user interactions, page views, scroll depth, form interactions, and more without requiring manual tracking calls.\n\n## Installation\n\n```bash\nnpm install @achado/core @achado/web-analytics\n```\n\n## Quick Start\n\n```typescript\nimport { AchadoClient } from '@achado/core';\nimport { WebAnalytics } from '@achado/web-analytics';\n\nconst client = new AchadoClient({ apiKey: 'your-api-key' });\nconst webAnalytics = new WebAnalytics(client);\n\nawait client.initialize();\nawait webAnalytics.initialize();\n\n// Analytics are now tracking automatically!\n```\n\n## Features\n\n### 🔄 Automatic Page View Tracking\n\n- Traditional page loads\n- Single Page Application (SPA) navigation\n- Time on page measurement\n- Page exit tracking\n\n### 👆 Click Tracking\n\n- Button clicks\n- Link clicks\n- Custom elements with `data-track-click`\n- Click coordinates and element context\n\n### 📝 Form Analytics\n\n- Form field focus/blur events\n- Form submissions\n- Field-level interaction tracking\n- Privacy-safe value capture\n\n### 📊 Scroll Depth Tracking\n\n- Milestone tracking (25%, 50%, 75%, 100%)\n- Maximum scroll depth per session\n- Scroll velocity analytics\n\n### ❌ Error Tracking\n\n- JavaScript errors\n- Promise rejections\n- Custom error reporting\n- Error context capture\n\n### 🎵 Media Tracking\n\n- Video/audio play, pause, ended events\n- Progress milestones\n- Engagement duration\n- Media completion rates\n\n### 💤 User Activity Tracking\n\n- Inactivity detection\n- Return behavior tracking\n- Session engagement scoring\n- Focus/blur detection\n\n### 🚪 Exit Intent Detection\n\n- Mouse movement-based detection\n- Before unload events\n- Exit prevention opportunities\n\n## Configuration\n\n```typescript\ninterface WebAnalyticsConfig {\n  enablePageViews?: boolean; // Default: true\n  enableClickTracking?: boolean; // Default: true\n  enableFormTracking?: boolean; // Default: true\n  enableScrollTracking?: boolean; // Default: true\n  enableErrorTracking?: boolean; // Default: true\n  enableInactivityTracking?: boolean; // Default: true\n  enableMediaTracking?: boolean; // Default: true\n  enableExitIntentTracking?: boolean; // Default: true\n\n  scrollThresholds?: number[]; // Default: [25, 50, 75, 100]\n  inactivityThreshold?: number; // Default: 300000 (5 minutes)\n  clickSelectors?: string[]; // Default: ['button', 'a', '[data-track-click]']\n  excludeSelectors?: string[]; // Default: ['[data-no-track]']\n  mediaSelectors?: string[]; // Default: ['video', 'audio']\n}\n```\n\n### Example Configuration\n\n```typescript\nconst webAnalytics = new WebAnalytics(client, {\n  enablePageViews: true,\n  enableClickTracking: true,\n  enableFormTracking: true,\n  enableScrollTracking: true,\n  scrollThresholds: [10, 25, 50, 75, 90, 100],\n  inactivityThreshold: 120000, // 2 minutes\n  clickSelectors: ['button', 'a', '.trackable', '[data-track]'],\n  excludeSelectors: ['[data-no-track]', '.private'],\n});\n```\n\n## API Reference\n\n### WebAnalytics Class\n\n#### Constructor\n\n```typescript\nnew WebAnalytics(client: AchadoClient, config?: WebAnalyticsConfig)\n```\n\n#### Methods\n\n##### `initialize(): Promise<void>`\n\nStart automatic tracking.\n\n##### `trackPageView(path?: string, title?: string): void`\n\nManually track a page view.\n\n```typescript\nwebAnalytics.trackPageView('/custom-page', 'Custom Page Title');\n```\n\n##### `trackEvent(eventName: string, properties?: Record<string, any>): void`\n\nTrack a custom event.\n\n```typescript\nwebAnalytics.trackEvent('video_shared', {\n  videoId: 'vid-123',\n  platform: 'twitter',\n  duration: 45,\n});\n```\n\n##### `trackError(error: Error, context?: Record<string, any>): void`\n\nManually track an error.\n\n```typescript\ntry {\n  // risky operation\n} catch (error) {\n  webAnalytics.trackError(error, {\n    component: 'payment-form',\n    step: 'validation',\n  });\n}\n```\n\n##### `getScrollProgress(): number`\n\nGet the maximum scroll percentage for the current page.\n\n##### `enableExitIntent(): void` / `disableExitIntent(): void`\n\nControl exit intent tracking.\n\n##### `updateConfig(config: Partial<WebAnalyticsConfig>): void`\n\nUpdate configuration at runtime.\n\n##### `getConfig(): WebAnalyticsConfig`\n\nGet current configuration.\n\n##### `destroy(): void`\n\nStop tracking and clean up.\n\n## Tracked Events\n\n### Page Views\n\n```typescript\n{\n  eventName: 'page_view',\n  properties: {\n    path: '/products',\n    title: 'Products - Achado',\n    url: 'https://example.com/products',\n    referrer: 'https://google.com',\n    search: '?category=analytics',\n    hash: '#features'\n  }\n}\n```\n\n### Click Events\n\n```typescript\n{\n  eventName: 'click',\n  properties: {\n    element: 'button#signup',\n    text: 'Sign Up Now',\n    href: null,\n    x: 245,\n    y: 156\n  }\n}\n```\n\n### Form Interactions\n\n```typescript\n{\n  eventName: 'form_interaction',\n  properties: {\n    formId: 'contact-form',\n    fieldName: 'email',\n    fieldType: 'email',\n    eventType: 'focus', // 'focus', 'blur', 'change', 'submit'\n    value: 'user@example.com' // Only for non-sensitive fields\n  }\n}\n```\n\n### Scroll Depth\n\n```typescript\n{\n  eventName: 'scroll_depth',\n  properties: {\n    percentage: 50,\n    depth: 1200 // pixels\n  }\n}\n```\n\n### Errors\n\n```typescript\n{\n  eventName: 'javascript_error',\n  properties: {\n    message: 'Cannot read property of undefined',\n    filename: 'app.js',\n    lineno: 42,\n    colno: 15,\n    stack: '...'\n  }\n}\n```\n\n## Privacy & Compliance\n\n### Data Protection\n\n- **Sensitive Data Filtering**: Passwords, credit cards, SSNs automatically excluded\n- **Custom Exclusions**: Use `data-no-track` to exclude elements\n- **Value Masking**: Form values masked for sensitive fields\n- **Configurable Tracking**: Granular control over what gets tracked\n\n### Opt-out Support\n\n```typescript\n// Disable specific tracking\nwebAnalytics.updateConfig({\n  enableFormTracking: false,\n  enableClickTracking: false,\n});\n\n// Or destroy completely\nwebAnalytics.destroy();\n```\n\n### GDPR Compliance\n\n```typescript\n// Wait for consent before initializing\nif (userHasConsented) {\n  await webAnalytics.initialize();\n}\n\n// Stop tracking if consent is withdrawn\nwebAnalytics.destroy();\n```\n\n## HTML Attributes\n\n### Track Specific Elements\n\n```html\n<!-- Force tracking on any element -->\n<div data-track-click>Custom tracking area</div>\n\n<!-- Exclude from tracking -->\n<button data-no-track>Private button</button>\n\n<!-- Sensitive form fields -->\n<input type=\"password\" data-sensitive />\n<input type=\"text\" data-sensitive placeholder=\"SSN\" />\n```\n\n### Media Tracking\n\n```html\n<video controls data-track-media>\n  <source src=\"video.mp4\" type=\"video/mp4\" />\n</video>\n\n<audio controls data-track-media>\n  <source src=\"audio.mp3\" type=\"audio/mpeg\" />\n</audio>\n```\n\n## Performance\n\n- **Passive Listeners**: Non-blocking event listeners\n- **Debounced Tracking**: Prevents event spam\n- **Efficient Selectors**: Optimized DOM queries\n- **Minimal Overhead**: < 1ms impact on user interactions\n\n## Browser Support\n\n- Chrome 70+\n- Firefox 65+\n- Safari 12+\n- Edge 79+\n\n## Examples\n\n### E-commerce Tracking\n\n```typescript\nconst webAnalytics = new WebAnalytics(client, {\n  enablePageViews: true,\n  enableClickTracking: true,\n  clickSelectors: [\n    'button',\n    'a',\n    '.product-card',\n    '.add-to-cart',\n    '.checkout-button',\n  ],\n  excludeSelectors: ['.admin-only', '[data-internal]'],\n});\n```\n\n### Content Site Tracking\n\n```typescript\nconst webAnalytics = new WebAnalytics(client, {\n  enableScrollTracking: true,\n  scrollThresholds: [10, 25, 50, 75, 90, 100],\n  enableMediaTracking: true,\n  mediaSelectors: ['video', 'audio', '.embedded-media'],\n  inactivityThreshold: 180000, // 3 minutes\n});\n```\n\n### SaaS Application Tracking\n\n```typescript\nconst webAnalytics = new WebAnalytics(client, {\n  enableFormTracking: true,\n  enableErrorTracking: true,\n  enableInactivityTracking: true,\n  inactivityThreshold: 600000, // 10 minutes\n  clickSelectors: ['button', '.feature-button', '[data-action]', '.nav-item'],\n});\n```\n","readmeFilename":"README.md"}