{"_id":"@abhi3004/heatmap","name":"@abhi3004/heatmap","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@abhi3004/heatmap","version":"0.2.0","description":"Worker-first user activity tracking with heatmap report generation.","keywords":["heatmap","analytics","cursor","click-tracking","web-worker","session-replay"],"license":"MIT","author":{"name":"Abhijeet Pareek"},"repository":{"type":"git","url":""},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"activity-heatmap":"dist/cli.cjs"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"sideEffects":false,"scripts":{"build":"tsup src/index.ts src/cli.ts --format esm,cjs --dts --clean","clean":"rimraf dist","dev":"tsup src/index.ts src/cli.ts --format esm,cjs --dts --watch","prepare":"npm run build"},"engines":{"node":">=18"},"devDependencies":{"@types/node":"^22.10.2","rimraf":"^5.0.0","tsup":"^8.3.0","typescript":"^5.6.3"},"_id":"@abhi3004/heatmap@0.2.0","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Fzcutu8haUWV/ZY7xLGZwySF23d3O2mh1/iwr66aiz97Jl3LXxNUorl8U4zfi1KyuSbuXzg2W3nZWgVelf5fNA==","shasum":"fbe2c11419b2789b40778e98b75d2f330243283f","tarball":"https://registry.npmjs.org/@abhi3004/heatmap/-/heatmap-0.2.0.tgz","fileCount":12,"unpackedSize":86084,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCIGEmguoBE0VrnnWCOCAe+rZQ0VHArEn50LhH7Y36uIwIgDIcZXASvC1sqy0s43gEKs90PCiqNRVANgysdnEtpDKE="}]},"_npmUser":{"name":"abhi3004","email":"abhijeet.pareek30@gmail.com"},"directories":{},"maintainers":[{"name":"abhi3004","email":"abhijeet.pareek30@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/heatmap_0.2.0_1771998530241_0.4957456490198169"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-25T05:48:50.170Z","0.2.0":"2026-02-25T05:48:50.397Z","modified":"2026-02-25T05:48:50.636Z"},"maintainers":[{"name":"abhi3004","email":"abhijeet.pareek30@gmail.com"}],"description":"Worker-first user activity tracking with heatmap report generation.","keywords":["heatmap","analytics","cursor","click-tracking","web-worker","session-replay"],"repository":{"type":"git","url":""},"author":{"name":"Abhijeet Pareek"},"license":"MIT","readme":"# heatmap\n\n`heatmap` is a worker-first activity tracking package for web apps.\nIt captures cursor movement, clicks, and scroll behavior with both absolute and screen-relative coordinates, and provides a separate CLI to generate heatmap reports.\n\n## What this package gives you\n\n- Browser tracker (`createActivityTracker`) with Web Worker processing by default.\n- Event payloads with:\n  - Absolute coordinates (`clientX`, `clientY`, `pageX`, `pageY`, `screenX`, `screenY`)\n  - Relative coordinates normalized to viewport/page (`0..1`)\n- Batched output so you can store data in your own DB.\n- Toggleable overlay renderer (`createHeatmapOverlay`) with blue -> green -> red intensity.\n- CLI command (`activity-heatmap generate`) to produce standalone HTML heatmap reports from exported JSON.\n\n## Install\n\n```bash\nnpm install heatmap\n```\n\n## Browser tracking (worker-backed)\n\n```ts\nimport { createActivityTracker } from \"heatmap\";\n\nconst tracker = createActivityTracker({\n  enabled: true,\n  useWorker: true,\n  sampleIntervalMs: 50,\n  flushIntervalMs: 1000,\n  batchSize: 200,\n  onBatch: (batch) => {\n    // Optional local hook\n    console.log(\"activity batch\", batch.sequence, batch.events.length);\n  },\n  transport: async (batch) => {\n    // Store in your backend / DB\n    await fetch(\"/api/activity\", {\n      method: \"POST\",\n      headers: { \"content-type\": \"application/json\" },\n      body: JSON.stringify(batch),\n    });\n  },\n});\n\ntracker.start();\n\n// Later:\n// tracker.flush();\n// tracker.stop();\n```\n\n## Toggle overlay (for selected envs)\n\n```ts\nimport { createHeatmapOverlay } from \"heatmap\";\n\nif (import.meta.env.MODE !== \"production\") {\n  const overlay = createHeatmapOverlay({\n    enabled: false,\n    toggleKey: \"h\",\n  });\n\n  // Feed aggregated data from API / exported state\n  overlay.updateFromBatches(batchesFromServer);\n\n  // Optional explicit control:\n  // overlay.show();\n  // overlay.hide();\n}\n```\n\n## CLI report generation\n\nGenerate a standalone HTML heatmap report from exported JSON.\n\n```bash\nactivity-heatmap generate \\\n  --input ./exports/activity.json \\\n  --output ./reports/heatmap.html \\\n  --title \"Checkout Flow Heatmap\"\n```\n\nInput supports:\n\n- `ActivityBatch[]`\n- `HeatCellAggregate[]`\n- `{ batches: ActivityBatch[] }`\n- `{ aggregates: HeatCellAggregate[] }`\n- NDJSON (one JSON object per line)\n\n## Build\n\n```bash\nnpm run build\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-b45a822529ce04d4c1b5f4129a09c676"}