{"_id":"@araneadev/usage-tracker-sdk","_rev":"2-dc6af3f20ae91ec0411ff85a7906f08e","name":"@araneadev/usage-tracker-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@araneadev/usage-tracker-sdk","version":"1.0.0","keywords":["analytics","tracking","privacy","self-hosted","web-analytics","browser","lightweight"],"author":"","license":"MIT","_id":"@araneadev/usage-tracker-sdk@1.0.0","maintainers":[{"name":"araneadev","email":"info@aranea-development.nl"}],"dist":{"shasum":"4171c9983ec1bb5ea56bac8344561985a4ef8dd3","tarball":"https://registry.npmjs.org/@araneadev/usage-tracker-sdk/-/usage-tracker-sdk-1.0.0.tgz","fileCount":7,"integrity":"sha512-dk89iKfl0lK7z81WEQCADmF18AnWlMSn1J0RHUYYpVt8JJ7Ptc4MAnNvU4SCn1yg1qh2G3IlZCgmXXiCsnM8EA==","signatures":[{"sig":"MEYCIQDc5SpjL+KxeRIwLDB2gCcDDK1VMtGSvs7I4tXUp9jnhwIhAIzVItGOh2ejP15HHV4Bzb/t93oYaI5Wd3u4oSwMhc7b","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":79707},"main":"dist/t.js","type":"commonjs","types":"types/index.d.ts","module":"dist/esm.mjs","exports":{".":{"types":"./types/index.d.ts","import":"./dist/esm.mjs","require":"./dist/t.js"}},"gitHead":"3d1e0e4e29f885f2b125318c9040b3faea22812a","scripts":{"dev":"vite","lint":"eslint src","test":"vitest run","build":"vite build && vite build --config vite.config.esm.ts","preview":"vite preview","lint:fix":"eslint src --fix","build:esm":"vite build --config vite.config.esm.ts","postbuild":"HASH=$(openssl dgst -sha384 -binary dist/t.js | openssl base64 -A) && printf '{\"t.js\":\"sha384-%s\"}\\n' \"$HASH\" > dist/sri.json","build:iife":"vite build","publish:jsr":"npx jsr publish","publish:npm":"npm publish --access public","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"araneadev","email":"info@aranea-development.nl"},"repository":{"type":"git","directory":"sdk/browser"},"_npmVersion":"10.8.2","description":"Lightweight, privacy-first browser analytics tracker for self-hosted Usage Tracker","directories":{},"sideEffects":false,"_nodeVersion":"20.20.0","_hasShrinkwrap":false,"devDependencies":{"vite":"^7.3.1","jsdom":"^27.4.0","eslint":"^9.39.2","terser":"^5.46.0","vitest":"^4.0.17","@eslint/js":"^9.39.2","typescript":"^5.9.3","typescript-eslint":"^8.53.0","@vitest/coverage-v8":"^4.0.17"},"_npmOperationalInternal":{"tmp":"tmp/usage-tracker-sdk_1.0.0_1774345671770_0.7749801731854107","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@araneadev/usage-tracker-sdk","version":"1.0.1","description":"Lightweight, privacy-first browser analytics tracker for self-hosted Usage Tracker","main":"dist/t.js","module":"dist/esm.mjs","types":"types/index.d.ts","exports":{".":{"types":"./types/index.d.ts","import":"./dist/esm.mjs","require":"./dist/t.js"}},"sideEffects":false,"scripts":{"dev":"vite","build":"vite build && vite build --config vite.config.esm.ts","postbuild":"HASH=$(openssl dgst -sha384 -binary dist/t.js | openssl base64 -A) && printf '{\"t.js\":\"sha384-%s\"}\\n' \"$HASH\" > dist/sri.json","build:iife":"vite build","build:esm":"vite build --config vite.config.esm.ts","preview":"vite preview","lint":"eslint src","lint:fix":"eslint src --fix","test":"vitest run","prepublishOnly":"npm run build && npm run test","publish:npm":"npm publish --access public","publish:jsr":"npx jsr publish"},"keywords":["analytics","tracking","privacy","self-hosted","web-analytics","browser","lightweight"],"author":"","license":"MIT","repository":{"type":"git","directory":"sdk/browser"},"type":"commonjs","devDependencies":{"@eslint/js":"^9.39.2","@vitest/coverage-v8":"^4.0.17","eslint":"^9.39.2","jsdom":"^27.4.0","terser":"^5.46.0","typescript":"^5.9.3","typescript-eslint":"^8.53.0","vite":"^7.3.1","vitest":"^4.0.17"},"_id":"@araneadev/usage-tracker-sdk@1.0.1","gitHead":"3d1e0e4e29f885f2b125318c9040b3faea22812a","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-sDc4MNqX19sR9iEx1EqJOTmXJrzt/FLTOgxv5KUelvCj9wNK82VDXa2AF8DiFJFXZSxXE52yYencfylAjz3Ugg==","shasum":"b9100feb39e7c4e6ba1228a42885d80b0ddb3150","tarball":"https://registry.npmjs.org/@araneadev/usage-tracker-sdk/-/usage-tracker-sdk-1.0.1.tgz","fileCount":7,"unpackedSize":79729,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDeI9Vz3Yx+iBCP/5gtb2b2tOzS6jjq0APDL35JKPrxUgIgKUqD6wwZvDdUmdfjV+fIUarElGX+ZtrrcOQBi/O7g+E="}]},"_npmUser":{"name":"araneadev","email":"info@aranea-development.nl"},"directories":{},"maintainers":[{"name":"araneadev","email":"info@aranea-development.nl"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/usage-tracker-sdk_1.0.1_1774346061860_0.6762342068374487"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-24T09:47:51.677Z","modified":"2026-03-24T09:54:22.106Z","1.0.0":"2026-03-24T09:47:51.903Z","1.0.1":"2026-03-24T09:54:21.986Z"},"license":"MIT","keywords":["analytics","tracking","privacy","self-hosted","web-analytics","browser","lightweight"],"repository":{"type":"git","directory":"sdk/browser"},"description":"Lightweight, privacy-first browser analytics tracker for self-hosted Usage Tracker","maintainers":[{"name":"araneadev","email":"info@aranea-development.nl"}],"readme":"# Usage Tracker SDK\n\nLightweight (~15KB), privacy-first browser analytics tracker. Collects anonymous usage data and sends it to your self-hosted Usage Tracker server.\n\n## Installation\n\n### Script tag (auto-init)\n\n```html\n<script src=\"https://your-server.com/t.js\" data-key=\"YOUR_API_KEY\"></script>\n```\n\nAuto-initializes when `data-key` is present. The endpoint is auto-detected from the script `src`.\n\n### npm / ESM\n\n```bash\nnpm install @araneadev/usage-tracker-sdk\n```\n\n```js\nimport { Tracker } from '@araneadev/usage-tracker-sdk';\n\nconst tracker = new Tracker({\n  apiKey: 'YOUR_API_KEY',\n  endpoint: 'https://your-server.com',\n});\n```\n\n### JSR (Deno / modern runtimes)\n\n```bash\nnpx jsr add @usage-tracker/browser\n```\n\n```ts\nimport { Tracker } from \"@usage-tracker/browser\";\n\nconst tracker = new Tracker({\n  apiKey: \"YOUR_API_KEY\",\n  endpoint: \"https://your-server.com\",\n});\n```\n\n### Manual initialization\n\n```html\n<script src=\"https://your-server.com/t.js\"></script>\n<script>\n  const tracker = window.UsageTracker.init({\n    apiKey: 'YOUR_API_KEY',\n  });\n</script>\n```\n\n## Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `apiKey` | `string` | *required* | Project API key |\n| `endpoint` | `string` | auto-detect | Server URL (auto-detected from script src) |\n| `enabled` | `boolean` | `true` | Set `false` for consent mode (start disabled) |\n| `flushInterval` | `number` | `30000` | Milliseconds between event flushes |\n| `batchSize` | `number` | `50` | Max queued events before auto-flush |\n| `debug` | `boolean` | `false` | Log events to console |\n| `piiFilter` | `boolean` | `true` | Auto-filter PII field names |\n| `requireHttps` | `boolean` | `true` (prod) | Require HTTPS endpoint |\n| `scrollTracking` | `boolean` | `true` | Track scroll depth |\n| `errorTracking` | `boolean` | `true` | Track JavaScript errors |\n| `performanceTracking` | `boolean` | `true` | Track Core Web Vitals |\n| `formTracking` | `boolean` | `true` | Track form interactions |\n| `wireframeCapture` | `boolean` | `true` | Capture page wireframes for heatmaps |\n| `consentStorageKey` | `string` | `'tracker_consent'` | localStorage key for consent state |\n| `persistConsent` | `boolean` | `true` | Persist consent to localStorage |\n\n## Custom Events\n\n```js\ntracker.track('custom', { name: 'signup_complete', plan: 'pro' });\n```\n\n## Consent Mode\n\nStart disabled and enable after user consent:\n\n```js\nconst tracker = new Tracker({\n  apiKey: 'YOUR_API_KEY',\n  enabled: false,\n});\n\n// After user gives consent:\ntracker.enable();\n\n// Revoke consent:\ntracker.disable();\n\n// Check state:\ntracker.isEnabled();           // boolean\ntracker.getConsentTimestamp();  // Unix ms or null\n```\n\nConsent state persists to localStorage by default.\n\n## API\n\n| Method | Description |\n|--------|-------------|\n| `tracker.track(type, payload?, selector?)` | Send a custom event |\n| `tracker.enable()` | Enable tracking (consent granted) |\n| `tracker.disable()` | Disable tracking (consent revoked) |\n| `tracker.isEnabled()` | Check if tracking is active |\n| `tracker.getConsentTimestamp()` | Get consent timestamp (ms) or null |\n| `tracker.start()` | Start tracking (called automatically) |\n| `tracker.destroy()` | Stop tracking and clean up |\n\n## Event Types\n\n| Event | Data Captured |\n|-------|---------------|\n| `pageview` | URL, referrer, title, viewport |\n| `click` | Selector, text, x, y, width, height |\n| `scroll` | Depth (25%, 50%, 75%, 90%, 100%) |\n| `form` | Form name, action, field names (never values) |\n| `error` | Message, stack, URL, line, column |\n| `performance` | loadTime, FCP, LCP, CLS |\n| `wireframe` | Page layout skeleton for heatmap overlays |\n| `context` | User agent, viewport, referrer (sent once per session) |\n\n## Plugin Architecture\n\nThe SDK uses a plugin system. Each plugin implements the `TrackerPlugin` interface:\n\n```\ninit(core) → onPageChange(url) → destroy()\n```\n\nBuilt-in plugins:\n- **ClickPlugin** — Click position and element tracking\n- **ScrollPlugin** — Scroll depth at 25/50/75/90/100% thresholds\n- **ErrorsPlugin** — `window.onerror` and `unhandledrejection` capture\n- **PerformancePlugin** — Core Web Vitals (LCP, CLS) and page load time\n- **FormsPlugin** — Form field interactions (names only, never values)\n- **WireframesPlugin** — DOM skeleton capture for heatmap overlays\n\n## Session Management\n\n- Sessions use `sess_` prefixed random IDs\n- Stored in `sessionStorage` (scoped to the browser tab)\n- Automatically expires when the tab is closed\n- A new session is created on each new tab/window\n\n## Privacy\n\n- No cookies, no fingerprinting\n- Session IDs are random, not tied to identity\n- PII field names auto-filtered (email, password, ssn, credit card, etc.)\n- Form values are never captured — only field names and types\n- All data stays on your server\n- HTTPS required by default\n- Code is unobfuscated and fully inspectable\n\n## Development\n\n```bash\nnpm install          # Install dependencies\nnpm run build        # Build SDK (IIFE + ESM)\nnpm run build:iife   # Build IIFE only\nnpm run build:esm    # Build ESM only\nnpm run dev          # Watch mode\nnpm test             # Run tests\nnpm test -- --watch  # Watch mode tests\nnpm run publish:jsr  # Publish to JSR\n```\n\n## Build Output\n\n- `dist/t.js` — IIFE bundle (~15KB)\n- `dist/esm.mjs` — ES module build\n\n## License\n\nMIT\n","readmeFilename":"README.md"}