{"_id":"@alexpodify/browser-sdk","name":"@alexpodify/browser-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alexpodify/browser-sdk","version":"1.0.0","description":"BotCiu browser tracker — public, privacy-first interaction events (page/listing views, clicks, Telegram links, forms) for WordPress, React, Vue, Next, Nuxt and plain HTML.","type":"module","license":"MIT","author":{"name":"BotCiu"},"homepage":"https://github.com/Gdymora/botciu-browser-sdk","repository":{"type":"git","url":"git+https://github.com/Gdymora/botciu-browser-sdk.git"},"keywords":["botciu","tracking","analytics","browser","attribution","wordpress","privacy"],"sideEffects":["./dist/botciu-tracker.global.js"],"main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./global":"./dist/botciu-tracker.global.js","./package.json":"./package.json"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"publishConfig":{"access":"public"},"engines":{"node":">=16"},"devDependencies":{"@types/node":"^20.19.43","tsup":"^8.0.0","typescript":"^5.4.0","vitest":"^1.6.0"},"_id":"@alexpodify/browser-sdk@1.0.0","gitHead":"11ee40d7f37271b8246589f55913e67827d0e502","bugs":{"url":"https://github.com/Gdymora/botciu-browser-sdk/issues"},"_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qD7PNF3dMuWQwyRZPQCyNRIcYZZJBahte0luLbadrVGOQU0RYtWK8LfCi+AyZlzJRvqfK/Fc+y1TtIfGWuEfYw==","shasum":"13df67b870cc9825e6819d0608416c4a4a0b4bfc","tarball":"https://registry.npmjs.org/@alexpodify/browser-sdk/-/browser-sdk-1.0.0.tgz","fileCount":11,"unpackedSize":135066,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDvYZ/4CWU1qqnscUb7YJtmc5CFHop7gZDMvVXEC+KTkgIgenqiYRwWINiOdQyaSZ2qG7ebX32PK0AkNG5XxaHavH0="}]},"_npmUser":{"name":"alexpodify","email":"alekspetrofint@gmail.com"},"directories":{},"maintainers":[{"name":"alexpodify","email":"alekspetrofint@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/browser-sdk_1.0.0_1784355386793_0.06126636329316382"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-18T06:16:26.631Z","1.0.0":"2026-07-18T06:16:26.964Z","modified":"2026-07-18T06:16:27.227Z"},"maintainers":[{"name":"alexpodify","email":"alekspetrofint@gmail.com"}],"description":"BotCiu browser tracker — public, privacy-first interaction events (page/listing views, clicks, Telegram links, forms) for WordPress, React, Vue, Next, Nuxt and plain HTML.","homepage":"https://github.com/Gdymora/botciu-browser-sdk","keywords":["botciu","tracking","analytics","browser","attribution","wordpress","privacy"],"repository":{"type":"git","url":"git+https://github.com/Gdymora/botciu-browser-sdk.git"},"author":{"name":"BotCiu"},"bugs":{"url":"https://github.com/Gdymora/botciu-browser-sdk/issues"},"license":"MIT","readme":"# @alexpodify/browser-sdk\n\nPrivacy-first browser tracker for **public interaction events** — page/listing\nviews, declarative clicks, Telegram links and forms — that stream to a BotCiu\nbackend (`POST /api/public/events`). Works in WordPress, React, Vue, Next, Nuxt\nand plain HTML.\n\n- **Zero runtime dependencies**, TypeScript, ESM + CJS + types + an auto-init IIFE bundle (~8 KB min).\n- **No fingerprinting, no cookies, no PII, no form values.** Only an allow-list of\n  attribution params leaves the page; the backend sanitizer + producer-trust policy\n  are the final authority.\n- The **public site token** is only ever sent in the `Authorization` header (never a URL).\n\n## Install\n\n```bash\nnpm install @alexpodify/browser-sdk\n```\n\nOr use the auto bundle via a `<script>` tag (see below).\n\n## Quick start (module API)\n\n```ts\nimport { createTracker } from '@alexpodify/browser-sdk';\n\nconst tracker = createTracker({\n  endpoint: 'https://your-backend/api/public/events',\n  siteToken: 'bt_site_...',                 // public token from the BotCiu Integration Registry\n  context: { external_type: 'hp_listing', external_id: '1905' },\n  settings: { consentMode: 'always' },      // 'always' | 'after_consent' | 'disabled'\n});\n\ntracker.startAuto();                        // page.viewed (+ listing.viewed) + auto click/telegram/form\ntracker.track('button.clicked', { data: { action: 'contact_owner' } });\n```\n\n## Quick start (script tag / auto)\n\n```html\n<script>\n  window.BotCiuConfig = {\n    endpoint: 'https://your-backend/api/public/events',\n    siteToken: 'bt_site_...',\n    context: { external_type: 'hp_listing', external_id: '1905' }\n  };\n</script>\n<script src=\"https://unpkg.com/@alexpodify/browser-sdk/dist/botciu-tracker.global.js\"></script>\n<!-- window.BotCiuTracker.track('button.clicked', { data: { action: 'buy' } }) -->\n```\n\nThis is exactly what the BotCiu WordPress plugin ships — the plugin injects\n`window.BotCiuConfig` and loads this same bundle.\n\n## Public API\n\n| Export | Description |\n|---|---|\n| `createTracker(config, env?)` | Create a `Tracker`. |\n| `Tracker#track(type, opts?)` | Emit an allow-listed event (`page.viewed`, `listing.viewed`, `button.clicked`, `telegram.link_opened`, `form.started`, `form.submitted`). Others are dropped. |\n| `Tracker#trackPage()` | Send `page.viewed` (+ `listing.viewed` for a HivePress listing) once per lifecycle. |\n| `Tracker#startAuto()` | Wait for consent, bind delegated click/telegram/form listeners, send the initial page view. |\n| `ConsentManager` | Consent gate (`always` / `after_consent` / `disabled`). |\n\nThe `env` parameter injects `{ fetch, storage, now, win, doc, crypto }` — used for\ntesting and non-DOM runtimes; it defaults to the browser globals.\n\n## Events & payloads\n\nOnly these six types are ever emitted; the DOM cannot produce anything else\n(`sale.*`, `payment.*`, `lead.qualified`, `classification`, `subject_id`,\n`project_id` are impossible client-side, and rejected server-side too):\n\n`page.viewed` · `listing.viewed` · `button.clicked` · `telegram.link_opened` ·\n`form.started` · `form.submitted`\n\nDeclarative click / Telegram tracking needs no JS:\n\n```html\n<a href=\"/contact\"\n   data-botciu-event=\"button.clicked\"\n   data-botciu-action=\"contact_owner\"\n   data-botciu-label=\"Contact owner\">Contact owner</a>\n<a href=\"https://t.me/mychannel\">Telegram</a>\n```\n\nForms send **metadata only** (`form_id`, `form_name`, `form_type`, `action_path`) —\nnever field values, emails, phones, nonces or `FormData`. `form.submitted` is **not**\na trusted `lead.created`.\n\n## Identity, consent, attribution\n\n- `visitor_id` (`btv_…`, localStorage) is stable; `session_id` (`bts_…`) rotates after\n  30 min of inactivity. Both opaque, no PII.\n- Consent: in `after_consent` mode nothing is stored or sent until `grant()` or a\n  `botciu:consent-granted` DOM event.\n- Attribution allow-list: `utm_source/medium/campaign/term/content`, `gclid/gbraid/wbraid/fbclid`,\n  `referrer`, `landing_url` (first landing captured once).\n\n## Frameworks\n\nSee [`examples/`](./examples): `vanilla` (script tag), `react` (`useBotCiu` hook),\n`vue` (composable), `next` (App Router client provider), `nuxt` (client plugin).\nFor SPA navigation dispatch `window.dispatchEvent(new Event('botciu:navigation'))`\nafter a route change to fire a fresh `page.viewed`.\n\n## Not in scope\n\nAnalytics dashboards, CRM, fingerprinting, cross-device identity, offline conversions.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a018af6fce7a28a6e01f3ada5744a175"}