{"_id":"@ananthsankaralingam/metrics","name":"@ananthsankaralingam/metrics","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ananthsankaralingam/metrics","version":"0.1.0","description":"Lightweight metrics SDK for Chrome extensions - track usage events and send them to your chromie project","main":"dist/chromie-metrics.cjs.js","module":"dist/chromie-metrics.esm.js","browser":"dist/chromie-metrics.umd.js","unpkg":"dist/chromie-metrics.umd.min.js","jsdelivr":"dist/chromie-metrics.umd.min.js","types":"dist/types/index.d.ts","exports":{".":{"import":"./dist/chromie-metrics.esm.js","require":"./dist/chromie-metrics.cjs.js","types":"./dist/types/index.d.ts"},"./popup":{"import":"./dist/popup.esm.js","require":"./dist/popup.cjs.js","types":"./dist/types/popup/index.d.ts"},"./content":{"import":"./dist/content.esm.js","require":"./dist/content.cjs.js","types":"./dist/types/content/index.d.ts"}},"scripts":{"build":"rollup -c","build:watch":"rollup -c -w","typecheck":"tsc --noEmit","clean":"rimraf dist","prepublishOnly":"npm run clean && npm run build","test:prepare":"npm run build && npm run test:copy","test:copy":"cp dist/chromie-metrics.esm.js test/test-extension/ && cp dist/popup.esm.js test/test-extension/ && cp dist/content.esm.js test/test-extension/ && cp dist/chromie-metrics.umd.js test/simple/","test:node":"node test/simple/test.js","test:serve":"npx serve test/simple -p 3000"},"keywords":["chrome-extension","metrics","analytics","chromie","telemetry","events","tracking"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/AnanthSankaralingam/chromie-metrics.git"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-node-resolve":"^15.2.3","@rollup/plugin-terser":"^0.4.4","@rollup/plugin-typescript":"^11.1.6","@types/chrome":"^0.0.268","rimraf":"^5.0.5","rollup":"^4.9.6","tslib":"^2.6.2","typescript":"^5.3.3"},"peerDependencies":{},"engines":{"node":">=16.0.0"},"gitHead":"c82903c758a0752fb194504e5f13a50a96fe7c72","_id":"@ananthsankaralingam/metrics@0.1.0","bugs":{"url":"https://github.com/AnanthSankaralingam/chromie-metrics/issues"},"homepage":"https://github.com/AnanthSankaralingam/chromie-metrics#readme","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-aPkuPv9VIo+g+kne3bd+1QRXU5VdWsJ97GDPzuNFunv2c6pyypQtffbw5lX4TZvck0ziJ4Z9CWLr2NxcqHZS6g==","shasum":"8f4d28f86165b022737704a8cc93019e82f2fd43","tarball":"https://registry.npmjs.org/@ananthsankaralingam/metrics/-/metrics-0.1.0.tgz","fileCount":51,"unpackedSize":452310,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCQ6H2ilTLImu5+oxAyiKB8lSjleDlMKo8PV/pcdlHD+wIhANxORfJ7fKL5W5pwdXKSnMkyu+YAZ2Rdax0HgTwoPBy8"}]},"_npmUser":{"name":"ananthsankaralingam","email":"ananth.sankaralingam@gmail.com"},"directories":{},"maintainers":[{"name":"ananthsankaralingam","email":"ananth.sankaralingam@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/metrics_0.1.0_1769295658577_0.6444483287472824"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-24T23:00:58.470Z","0.1.0":"2026-01-24T23:00:58.741Z","modified":"2026-01-24T23:00:58.937Z"},"maintainers":[{"name":"ananthsankaralingam","email":"ananth.sankaralingam@gmail.com"}],"description":"Lightweight metrics SDK for Chrome extensions - track usage events and send them to your chromie project","homepage":"https://github.com/AnanthSankaralingam/chromie-metrics#readme","keywords":["chrome-extension","metrics","analytics","chromie","telemetry","events","tracking"],"repository":{"type":"git","url":"git+https://github.com/AnanthSankaralingam/chromie-metrics.git"},"bugs":{"url":"https://github.com/AnanthSankaralingam/chromie-metrics/issues"},"license":"MIT","readme":"# @chromie/metrics\n\nLightweight metrics SDK for Chrome extensions. Zero dependencies, automatic batching, offline support.\n\n## Installation\n\n```bash\nnpm install @chromie/metrics\n```\n\n## Quick Start\n\nThe SDK has three entry points optimized for each Chrome extension context:\n\n| Entry Point | Use In | Bundle Size |\n|-------------|--------|-------------|\n| `@chromie/metrics` | Background script | ~10KB min |\n| `@chromie/metrics/content` | Content scripts | ~1.5KB min |\n| `@chromie/metrics/popup` | Popup/options pages | ~1.3KB min |\n\n### 1. Background Script (Required)\n\nInitialize the SDK in your background script. This handles queuing, batching, and API communication.\n\n```javascript\n// background.js\nimport { ChromieMetrics } from '@chromie/metrics';\n\nconst metrics = ChromieMetrics.init({\n  apiKey: 'chromie_live_xxxxx'  // Get one at https://chromie.dev\n});\n\n// Track events (sync)\nmetrics.trackEvent('button_click', { button_id: 'icon' });\n```\n\n**Using UMD (service worker):**\n```javascript\nimportScripts('chromie-metrics.umd.js');\nconst metrics = ChromieMetrics.ChromieMetrics.init({ apiKey: 'chromie_live_xxxxx' });\n```\n\n### 2. Content Scripts (Optional)\n\nLightweight client that sends events to the background script. Auto-captures page URL and title.\n\n```javascript\n// content.js\nimport { ChromieMetricsClient } from '@chromie/metrics/content';\n\nconst metrics = ChromieMetricsClient.init();\n\n// Track events (async) - URL and title captured automatically\nawait metrics.trackPageView();\nawait metrics.trackButtonClick('save_btn');\nawait metrics.trackEvent('custom:feature_used', { feature: 'export' });\n```\n\n### 3. Popup/Options Scripts (Optional)\n\nSimilar to content scripts, but without auto-capture (popups have no meaningful URL).\n\n```javascript\n// popup.js\nimport { ChromieMetricsClient } from '@chromie/metrics/popup';\n\nconst metrics = ChromieMetricsClient.init();\n\nawait metrics.trackPageView('settings');\nawait metrics.trackButtonClick('export_btn');\n```\n\n## Event Types\n\n```javascript\n// Standard events\nmetrics.trackEvent('button_click', { button_id: 'save' });\nmetrics.trackEvent('page_view', { view: 'dashboard' });\nmetrics.trackEvent('api_call', { endpoint: '/users', status: 200 });\nmetrics.trackEvent('error', { message: 'Failed to load' });\n\n// Custom events (use custom: prefix)\nmetrics.trackEvent('custom:feature_enabled', { feature: 'dark_mode' });\n```\n\n## Configuration\n\n```javascript\nChromieMetrics.init({\n  apiKey: 'chromie_live_xxxxx',     // Required\n  batchSize: 20,                     // Events before sending (default: 20)\n  flushInterval: 30000,              // Send interval in ms (default: 30000)\n  debug: false,                      // Console logging (default: false)\n  autoTrackLifecycle: true,          // Track install/update (default: true)\n  maxRetries: 3,                     // Retry attempts (default: 3)\n  maxQueueSize: 500                  // Max queued events (default: 500)\n});\n```\n\n## API Reference\n\n### Background Script (`ChromieMetrics`)\n\n```javascript\n// Initialize (singleton)\nconst metrics = ChromieMetrics.init(options);\nconst metrics = ChromieMetrics.getInstance();\n\n// Track events (sync)\nmetrics.trackEvent(eventType, metadata);\nmetrics.trackButtonClick(buttonId, metadata);\nmetrics.trackPageView(viewName, metadata);\n\n// Control\nawait metrics.flush();           // Send queued events immediately\nmetrics.disable();               // Pause tracking\nmetrics.enable();                // Resume tracking\nmetrics.isEnabled();             // Check status\nmetrics.getQueueLength();        // Pending events count\nawait metrics.getUserId();       // Get anonymous user ID\nawait metrics.destroy();         // Cleanup\n```\n\n### Content/Popup Scripts (`ChromieMetricsClient`)\n\n```javascript\n// Initialize (singleton)\nconst metrics = ChromieMetricsClient.init({ debug: false });\nconst metrics = ChromieMetricsClient.getInstance();\n\n// Track events (async - sends to background)\nawait metrics.trackEvent(eventType, metadata);\nawait metrics.trackButtonClick(buttonId, metadata);\nawait metrics.trackPageView(viewName, metadata);  // viewName optional in content scripts\nawait metrics.trackApiCall(endpoint, metadata);\nawait metrics.trackError(error, metadata);\n```\n\n## Automatic Tracking\n\nThe background SDK automatically tracks:\n- **Install** - When extension is first installed\n- **Update** - When extension updates (includes `previous_version`)\n- **Uninstall** - Via Chrome's uninstall URL feature\n\nDisable with `autoTrackLifecycle: false`.\n\n## Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│ Content Script  │    │  Popup Script   │    │ Background      │\n│ (Lightweight)   │    │  (Lightweight)  │    │ (Full SDK)      │\n└────────┬────────┘    └────────┬────────┘    └────────┬────────┘\n         │                      │                      │\n         │   chrome.runtime.sendMessage()              │\n         └──────────────────────┴──────────────────────┤\n                                                       │\n                                              ┌────────▼────────┐\n                                              │ Queue & Batch   │\n                                              │ Retry & Storage │\n                                              └────────┬────────┘\n                                                       │\n                                              ┌────────▼────────┐\n                                              │  Chromie API    │\n                                              └─────────────────┘\n```\n\n## Privacy\n\n- Anonymous UUIDs (no personal data)\n- No cookies or tracking pixels\n- Local storage only (`chrome.storage.local`)\n- Opt-out via `metrics.disable()`\n\n## License\n\nMIT\n\n## Support\n\n- API keys: [chromie.dev](https://chromie.dev)\n- Issues: [GitHub](https://github.com/AnanathSankaralingam/chromie-metrics/issues)\n","readmeFilename":"README.md","_rev":"1-21c0278653e3db48c0534898c5531f33"}