{"_id":"@alemm12/eventlens","name":"@alemm12/eventlens","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alemm12/eventlens","version":"0.1.0","description":"A small, consistent analytics API (track/identify/captureException) shared across projects, backed by PostHog.","license":"MIT","author":{"name":"Alejandro Matta Morales"},"repository":{"type":"git","url":"git+https://github.com/alejandromattamorales-wq/eventlens.git"},"type":"module","sideEffects":false,"publishConfig":{"access":"public"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./browser":{"types":"./dist/browser.d.ts","import":"./dist/browser.js","require":"./dist/browser.cjs"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","require":"./dist/server.cjs"}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"eslint .","test":"vitest run","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"dependencies":{"posthog-js":"^1.404.1","posthog-node":"^5.45.2"},"devDependencies":{"@eslint/js":"^10.0.1","@types/node":"^22","eslint":"^10.7.0","tsup":"^8.5.1","typescript":"^5","typescript-eslint":"^8.64.0","vitest":"^4.1.10"},"engines":{"node":">=20.20.0"},"_id":"@alemm12/eventlens@0.1.0","gitHead":"ccbe7855c05ae634b56108d02967798e4aa7a8f2","bugs":{"url":"https://github.com/alejandromattamorales-wq/eventlens/issues"},"homepage":"https://github.com/alejandromattamorales-wq/eventlens#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-/grMVdfKDhDYQh2xovvuHAicl2YuDYPk2VAa5QP5w5v6PzGQYekwiDwB8rQW/VPBt16wBTA/o5Tsgo6Rc7ZXHA==","shasum":"57d016337252e6478f965071848afe006e733c65","tarball":"https://registry.npmjs.org/@alemm12/eventlens/-/eventlens-0.1.0.tgz","fileCount":21,"unpackedSize":23264,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCahvmffa0vws+k4T0H0ZgmlZDaCusP2+JRWoMoJpZR5wIgG6s5xDA3v0EeEqxjP5YmprPkUB4fzmFy1lnezJo5lFA="}]},"_npmUser":{"name":"alemm12","email":"alejandro.matta.morales@gmail.com"},"directories":{},"maintainers":[{"name":"alemm12","email":"alejandro.matta.morales@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/eventlens_0.1.0_1784332603085_0.3904873718490045"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-17T23:56:42.943Z","0.1.0":"2026-07-17T23:56:43.210Z","modified":"2026-07-17T23:56:43.385Z"},"maintainers":[{"name":"alemm12","email":"alejandro.matta.morales@gmail.com"}],"description":"A small, consistent analytics API (track/identify/captureException) shared across projects, backed by PostHog.","homepage":"https://github.com/alejandromattamorales-wq/eventlens#readme","repository":{"type":"git","url":"git+https://github.com/alejandromattamorales-wq/eventlens.git"},"author":{"name":"Alejandro Matta Morales"},"bugs":{"url":"https://github.com/alejandromattamorales-wq/eventlens/issues"},"license":"MIT","readme":"# eventlens\n\nA small, consistent analytics API — `track`, `identify`, `captureException` — shared across projects, backed by [PostHog](https://posthog.com).\n\nIt's a thin wrapper: `@alemm12/eventlens/browser` wraps [`posthog-js`](https://posthog.com/docs/libraries/js) and `@alemm12/eventlens/server` wraps [`posthog-node`](https://posthog.com/docs/libraries/node). The point is that consuming projects depend on **this** package's stable API instead of calling a specific PostHog SDK directly, so the underlying provider can change in one place without touching every project.\n\n## Install\n\n```sh\nnpm install @alemm12/eventlens\n```\n\nYou'll need a PostHog project API key. PostHog's free tier covers 1M events/month, 100K exceptions/month, and 5K session recordings/month — see [posthog.com/pricing](https://posthog.com/pricing). Self-hosting is also free (MIT-licensed core) if you'd rather run it yourself.\n\n## Browser usage\n\nFor client-side apps (React, Next.js, etc). Call `createBrowserAnalytics` once at startup — repeat calls reuse the same underlying PostHog instance.\n\n```ts\nimport { createBrowserAnalytics } from \"@alemm12/eventlens/browser\";\n\nconst analytics = createBrowserAnalytics({\n  apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!,\n  apiHost: process.env.NEXT_PUBLIC_POSTHOG_HOST, // optional, defaults to PostHog Cloud US\n});\n\nanalytics.track(\"ticket_purchased\", { tier: \"vip\", priceCents: 5000 });\nanalytics.identify(\"user_123\", { plan: \"pro\" });\nanalytics.captureException(error, { page: \"/checkout\" });\nanalytics.reset(); // call on logout\n```\n\n## Server usage\n\nFor backend services / API routes / scripts. There's no persisted session, so every call takes an explicit `distinctId` for the actor the event belongs to.\n\n```ts\nimport { createServerAnalytics } from \"@alemm12/eventlens/server\";\n\nconst analytics = createServerAnalytics({\n  apiKey: process.env.POSTHOG_KEY!,\n  apiHost: process.env.POSTHOG_HOST, // optional\n});\n\nanalytics.track(\"user_123\", \"ticket_purchased\", { tier: \"vip\" });\nanalytics.identify(\"user_123\", { plan: \"pro\" });\nanalytics.captureException(error, \"user_123\", { job: \"send-confirmation-email\" });\n\n// Before the process exits (serverless handlers, scripts, shutdown hooks):\nawait analytics.shutdown();\n```\n\nBy default the server client flushes every event immediately (`flushImmediately: true`), since short-lived environments like serverless functions may exit before a batched flush would fire. Pass `flushImmediately: false` for long-running processes where batching (up to 20 events / 10s) is fine and reduces request volume.\n\n## Why two entry points instead of one?\n\n`@alemm12/eventlens` (the default import) only exports shared types — no SDK code. Importing `@alemm12/eventlens/browser` or `@alemm12/eventlens/server` explicitly means a backend project never bundles `posthog-js`, and a browser bundle never pulls in `posthog-node`.\n\n## Development\n\n```sh\nnpm install\nnpm run build      # tsup -> dist/\nnpm run typecheck\nnpm run lint\nnpm run test\n```\n","readmeFilename":"README.md","_rev":"1-c2e8fbb24faf355bd4f8baeba1d57470"}