{"_id":"@achado/feature-tracking","_rev":"2-30100598506ada1dc9437747b87e6764","name":"@achado/feature-tracking","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@achado/feature-tracking","version":"0.0.1","_id":"@achado/feature-tracking@0.0.1","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"dist":{"shasum":"d42d0cfc59040bbf2530458aac9665fbe67e8e35","tarball":"https://registry.npmjs.org/@achado/feature-tracking/-/feature-tracking-0.0.1.tgz","fileCount":32,"integrity":"sha512-tdaCLAcoQMc4rNUZZH/WIquE9+83M8Qm4X55npAqVsJ+cndTFKbW93dwIznFnuYnyer9cev1SjxYBlYNMK7mNQ==","signatures":[{"sig":"MEUCIFPVsjzMlAl7Zxnw9YFEtytYA9ecnQIR7qy94Y9D6oIvAiEA1xfC0xAuqXIp+Jn7ptAHqFq0kTLms76M289xYGTEpxw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":219355},"main":"dist/index.js","type":"commonjs","_from":"file:achado-feature-tracking-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/feature-tracking-plugin.d.ts","import":"./dist/esm/feature-tracking-plugin.js","require":"./dist/cjs/feature-tracking-plugin.js"},"./observer":{"types":"./dist/types/feature-observer.d.ts","import":"./dist/esm/feature-observer.js","require":"./dist/cjs/feature-observer.js"},"./analytics":{"types":"./dist/types/feature-analytics.d.ts","import":"./dist/esm/feature-analytics.js","require":"./dist/cjs/feature-analytics.js"},"./package.json":"./package.json","./feature-tracking":{"types":"./dist/types/feature-tracking.d.ts","import":"./dist/esm/feature-tracking.js","require":"./dist/cjs/feature-tracking.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/c8eee2500e930682b2f1ae166b15a191/achado-feature-tracking-0.0.1.tgz","_integrity":"sha512-tdaCLAcoQMc4rNUZZH/WIquE9+83M8Qm4X55npAqVsJ+cndTFKbW93dwIznFnuYnyer9cev1SjxYBlYNMK7mNQ==","_npmVersion":"10.9.3","description":"Feature usage tracking via data-feature attributes 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/feature-tracking_0.0.1_1759924668518_0.4253154802846737","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@achado/feature-tracking","version":"0.0.2","type":"commonjs","description":"Feature usage tracking via data-feature attributes 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"},"./feature-tracking":{"import":"./dist/esm/feature-tracking.js","require":"./dist/cjs/feature-tracking.js","types":"./dist/types/feature-tracking.d.ts"},"./plugin":{"import":"./dist/esm/feature-tracking-plugin.js","require":"./dist/cjs/feature-tracking-plugin.js","types":"./dist/types/feature-tracking-plugin.d.ts"},"./observer":{"import":"./dist/esm/feature-observer.js","require":"./dist/cjs/feature-observer.js","types":"./dist/types/feature-observer.d.ts"},"./analytics":{"import":"./dist/esm/feature-analytics.js","require":"./dist/cjs/feature-analytics.js","types":"./dist/types/feature-analytics.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/feature-tracking@0.0.2","_integrity":"sha512-+KrZ3thMu5hZvO2fXDDv6PEJcMk3MgewYRjiFahNY1VSVd1M7jnbCFwlPvWvkm7BL6MyGSV/LnmXYHne/8abfw==","_resolved":"/tmp/9385d406f7d6d71bc37f82e1f262354c/achado-feature-tracking-0.0.2.tgz","_from":"file:achado-feature-tracking-0.0.2.tgz","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-+KrZ3thMu5hZvO2fXDDv6PEJcMk3MgewYRjiFahNY1VSVd1M7jnbCFwlPvWvkm7BL6MyGSV/LnmXYHne/8abfw==","shasum":"6c09d07876d28f86152d5113e55716f0e58efd7c","tarball":"https://registry.npmjs.org/@achado/feature-tracking/-/feature-tracking-0.0.2.tgz","fileCount":32,"unpackedSize":219355,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCr/RfxW237Ox3SFxe7tjEFklQyK855R+6ykBQSxrulEQIhANzuIVGkG+X8oXyuDh6gVWu6yXJNFF4Eyt0l59HjNcVG"}]},"_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/feature-tracking_0.0.2_1759937318499_0.36863163311786673"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-08T11:57:48.450Z","modified":"2025-10-08T15:28:38.844Z","0.0.1":"2025-10-08T11:57:48.697Z","0.0.2":"2025-10-08T15:28:38.672Z"},"description":"Feature usage tracking via data-feature attributes for Achado platform","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"readme":"# @achado/feature-tracking\n\nFeature usage tracking via data attributes for the Achado platform. Automatically track feature views, interactions, exposures, and conversions using simple HTML attributes.\n\n## Installation\n\n```bash\nnpm install @achado/core @achado/feature-tracking\n```\n\n## Quick Start\n\n```typescript\nimport { AchadoClient } from '@achado/core';\nimport { FeatureTracking } from '@achado/feature-tracking';\n\nconst client = new AchadoClient({ apiKey: 'your-api-key' });\nconst featureTracking = new FeatureTracking(client);\n\nawait client.initialize();\nawait featureTracking.initialize();\n\n// Features are now tracked automatically via data attributes!\n```\n\n```html\n<!-- Automatically tracked features -->\n<button data-feature=\"signup-button\">Sign Up</button>\n<div data-feature=\"pricing-table\">Pricing content...</div>\n<form data-feature=\"contact-form\">Contact form...</form>\n```\n\n## Features\n\n### 🏷️ Attribute-Based Tracking\n\n- Simple `data-feature` attributes\n- Automatic detection and tracking\n- No code changes required for tracking\n\n### 👁️ View Tracking\n\n- Automatic visibility detection\n- Intersection Observer-based\n- Viewport-aware measurement\n\n### 🖱️ Interaction Tracking\n\n- Click, focus, and submission events\n- Element context capture\n- Interaction type classification\n\n### ⏱️ Exposure Tracking\n\n- Time-based visibility measurement\n- Configurable exposure thresholds\n- Scroll-based exposure detection\n\n### 📈 Conversion Tracking\n\n- Goal completion measurement\n- Funnel analysis support\n- Custom conversion events\n\n### 🧪 A/B Testing\n\n- Built-in experiment management\n- Variant assignment and tracking\n- Feature flag integration\n\n### 📊 Analytics Dashboard\n\n- Real-time usage statistics\n- Conversion rate analysis\n- Feature performance metrics\n\n## Configuration\n\n```typescript\ninterface FeatureTrackingConfig {\n  enabled?: boolean; // Default: true\n  autoTrack?: boolean; // Default: true\n  trackViews?: boolean; // Default: true\n  trackInteractions?: boolean; // Default: true\n  trackExposure?: boolean; // Default: true\n  exposureThreshold?: number; // Default: 0.5 (50% visible)\n  debounceMs?: number; // Default: 250\n  attributeName?: string; // Default: 'data-feature'\n  excludeFeatures?: string[]; // Features to exclude\n  includeFeatures?: string[]; // Only track these features\n}\n```\n\n### Example Configuration\n\n```typescript\nconst featureTracking = new FeatureTracking(client, {\n  enabled: true,\n  autoTrack: true,\n  exposureThreshold: 0.75, // 75% visible for exposure\n  debounceMs: 500,\n  attributeName: 'data-track-feature',\n  excludeFeatures: ['debug-panel', 'admin-tools'],\n  includeFeatures: [], // Empty = track all (except excluded)\n});\n```\n\n## API Reference\n\n### FeatureTracking Class\n\n#### Constructor\n\n```typescript\nnew FeatureTracking(client: AchadoClient, config?: FeatureTrackingConfig)\n```\n\n#### Methods\n\n##### `initialize(): Promise<void>`\n\nStart automatic feature tracking.\n\n##### `trackFeature(featureName: string, eventType: 'view' | 'interaction' | 'exposure' | 'conversion', properties?: Record<string, any>): void`\n\nManually track a feature event.\n\n```typescript\nfeatureTracking.trackFeature('signup-button', 'view', {\n  location: 'header',\n  variant: 'blue',\n});\n```\n\n##### `trackConversion(featureName: string, properties?: Record<string, any>): void`\n\nTrack a conversion event.\n\n```typescript\nfeatureTracking.trackConversion('signup-button', {\n  userId: 'user-123',\n  revenue: 29.99,\n  plan: 'premium',\n});\n```\n\n##### `trackInteraction(featureName: string, interactionType: string, properties?: Record<string, any>): void`\n\nTrack a specific interaction.\n\n```typescript\nfeatureTracking.trackInteraction('video-player', 'play', {\n  duration: 120,\n  quality: '1080p',\n});\n```\n\n##### Experiment Management\n\n```typescript\n// Set up an experiment\nfeatureTracking.setExperiment('button-color', 'red', true, {\n  variant: 'A',\n  startDate: '2024-01-01',\n});\n\n// Get experiment info\nconst experiment = featureTracking.getExperiment('button-color');\nconst variant = featureTracking.getExperimentVariant('button-color');\nconst isEnabled = featureTracking.isExperimentEnabled('button-color');\n```\n\n##### Analytics Methods\n\n```typescript\n// Get feature statistics\nconst stats = featureTracking.getFeatureStats('signup-button');\n\n// Get all feature stats\nconst allStats = featureTracking.getAllFeatureStats();\n\n// Get top performing features\nconst topFeatures = featureTracking.getTopFeatures(10);\n\n// Get features by conversion rate\nconst bestConverting = featureTracking.getFeaturesByConversionRate(5);\n\n// Export all analytics data\nconst analyticsData = featureTracking.exportAnalytics();\n```\n\n##### Configuration Management\n\n```typescript\n// Update config at runtime\nfeatureTracking.updateConfig({\n  exposureThreshold: 0.8,\n  debounceMs: 300,\n});\n\n// Manage feature lists\nfeatureTracking.addFeatureToExclude('beta-feature');\nfeatureTracking.removeFeatureFromExclude('beta-feature');\nfeatureTracking.addFeatureToInclude('important-feature');\n```\n\n## HTML Usage\n\n### Basic Feature Tracking\n\n```html\n<!-- Button tracking -->\n<button data-feature=\"signup-cta\">Sign Up Now</button>\n\n<!-- Section tracking -->\n<section data-feature=\"pricing-section\">\n  <h2>Pricing Plans</h2>\n  <!-- Pricing content -->\n</section>\n\n<!-- Form tracking -->\n<form data-feature=\"newsletter-signup\">\n  <input type=\"email\" placeholder=\"Your email\" />\n  <button type=\"submit\">Subscribe</button>\n</form>\n```\n\n### Advanced Feature Tracking\n\n```html\n<!-- Custom attribute name -->\n<div data-track-feature=\"hero-banner\">Hero content</div>\n\n<!-- Multiple features on one element -->\n<button\n  data-feature=\"primary-cta\"\n  data-experiment=\"button-color\"\n  data-variant=\"blue\"\n>\n  Get Started\n</button>\n\n<!-- Excluded from tracking -->\n<div data-feature=\"admin-panel\" data-no-track>Admin only content</div>\n```\n\n### E-commerce Examples\n\n```html\n<!-- Product tracking -->\n<div data-feature=\"product-card\" data-product-id=\"prod-123\">\n  <img src=\"product.jpg\" alt=\"Product\" />\n  <h3>Product Name</h3>\n  <button data-feature=\"add-to-cart\">Add to Cart</button>\n</div>\n\n<!-- Checkout flow -->\n<form data-feature=\"checkout-form\">\n  <div data-feature=\"payment-methods\">\n    <input type=\"radio\" data-feature=\"credit-card\" /> Credit Card\n    <input type=\"radio\" data-feature=\"paypal\" /> PayPal\n  </div>\n  <button data-feature=\"complete-purchase\">Complete Purchase</button>\n</form>\n```\n\n### SaaS Application Examples\n\n```html\n<!-- Feature adoption tracking -->\n<div data-feature=\"dashboard-widget\" data-widget-type=\"analytics\">\n  <h3>Analytics Widget</h3>\n  <button data-feature=\"widget-configure\">Configure</button>\n</div>\n\n<!-- Onboarding flow -->\n<div data-feature=\"onboarding-step\" data-step=\"3\">\n  <h2>Step 3: Connect Your Data</h2>\n  <button data-feature=\"connect-integration\">Connect</button>\n  <button data-feature=\"skip-step\">Skip for Now</button>\n</div>\n```\n\n## Tracked Events\n\n### Feature View\n\n```typescript\n{\n  eventName: 'feature_usage',\n  properties: {\n    featureName: 'signup-button',\n    eventType: 'view',\n    timestamp: 1640995200000,\n    element: {\n      tagName: 'button',\n      id: 'signup-btn',\n      className: 'btn btn-primary',\n      textContent: 'Sign Up Now'\n    },\n    context: {\n      url: 'https://example.com',\n      viewport: { width: 1920, height: 1080 },\n      elementPosition: { x: 100, y: 200, width: 120, height: 40 }\n    }\n  }\n}\n```\n\n### Feature Interaction\n\n```typescript\n{\n  eventName: 'feature_usage',\n  properties: {\n    featureName: 'signup-button',\n    eventType: 'interaction',\n    properties: {\n      interactionType: 'click'\n    },\n    timestamp: 1640995250000,\n    // ... element and context data\n  }\n}\n```\n\n### Feature Conversion\n\n```typescript\n{\n  eventName: 'feature_usage',\n  properties: {\n    featureName: 'signup-button',\n    eventType: 'conversion',\n    properties: {\n      userId: 'user-123',\n      revenue: 29.99,\n      plan: 'premium'\n    },\n    timestamp: 1640995300000\n  }\n}\n```\n\n## Analytics Data\n\n### Feature Usage Statistics\n\n```typescript\ninterface FeatureUsage {\n  featureName: string;\n  totalViews: number;\n  totalInteractions: number;\n  totalExposures: number;\n  totalConversions: number;\n  firstSeen: number;\n  lastSeen: number;\n  uniqueSessions: number;\n  averageTimeToInteraction: number;\n  conversionRate: number;\n}\n```\n\n### Usage Example\n\n```typescript\nconst stats = featureTracking.getFeatureStats('signup-button');\nconsole.log(`Conversion rate: ${stats.conversionRate * 100}%`);\nconsole.log(`Total interactions: ${stats.totalInteractions}`);\nconsole.log(`Unique sessions: ${stats.uniqueSessions.size}`);\n```\n\n## A/B Testing Integration\n\n### Setting Up Experiments\n\n```typescript\n// Create experiment variants\nfeatureTracking.setExperiment('pricing-display', 'monthly-first', true, {\n  testGroup: 'A',\n  startDate: '2024-01-01',\n  endDate: '2024-01-31',\n});\n\nfeatureTracking.setExperiment('pricing-display', 'annual-first', true, {\n  testGroup: 'B',\n  startDate: '2024-01-01',\n  endDate: '2024-01-31',\n});\n```\n\n### Using Experiments in HTML\n\n```html\n<!-- Variant A -->\n<div\n  data-feature=\"pricing-table\"\n  data-experiment=\"pricing-display\"\n  data-variant=\"monthly-first\"\n>\n  <div>Monthly: $29/month</div>\n  <div>Annual: $290/year</div>\n</div>\n\n<!-- Variant B -->\n<div\n  data-feature=\"pricing-table\"\n  data-experiment=\"pricing-display\"\n  data-variant=\"annual-first\"\n>\n  <div>Annual: $290/year (Save 20%!)</div>\n  <div>Monthly: $29/month</div>\n</div>\n```\n\n### Experiment Analysis\n\n```typescript\n// Get conversion rates by variant\nconst experiments = featureTracking.getAllExperiments();\nexperiments.forEach((exp) => {\n  const stats = featureTracking.getFeatureStats(exp.name);\n  console.log(`${exp.variant}: ${stats.conversionRate * 100}% conversion`);\n});\n```\n\n## Performance\n\n### Optimization Features\n\n- **Intersection Observer**: Efficient visibility detection\n- **Debounced Events**: Prevents event spam\n- **Smart Querying**: Optimized DOM queries\n- **Memory Management**: Automatic cleanup\n\n### Performance Impact\n\n- **DOM Queries**: < 5ms per page scan\n- **Event Processing**: < 1ms per interaction\n- **Memory Usage**: < 1MB for typical usage\n- **Network**: Minimal additional payload\n\n## Browser Support\n\n- Chrome 70+\n- Firefox 65+\n- Safari 12+\n- Edge 79+\n\n## Examples\n\n### E-commerce Setup\n\n```typescript\nconst featureTracking = new FeatureTracking(client, {\n  enabled: true,\n  trackViews: true,\n  trackInteractions: true,\n  trackExposure: true,\n  exposureThreshold: 0.6,\n  includeFeatures: [\n    'product-card',\n    'add-to-cart',\n    'checkout-form',\n    'payment-method',\n    'complete-purchase',\n  ],\n});\n```\n\n### SaaS Dashboard Setup\n\n```typescript\nconst featureTracking = new FeatureTracking(client, {\n  enabled: true,\n  autoTrack: true,\n  exposureThreshold: 0.8,\n  excludeFeatures: ['admin-panel', 'debug-info', 'internal-tools'],\n  debounceMs: 500,\n});\n```\n\n### Content Site Setup\n\n```typescript\nconst featureTracking = new FeatureTracking(client, {\n  enabled: true,\n  trackExposure: true,\n  exposureThreshold: 0.5,\n  includeFeatures: [\n    'article-content',\n    'social-share',\n    'newsletter-signup',\n    'related-articles',\n    'comment-section',\n  ],\n});\n```\n","readmeFilename":"README.md"}