{"_id":"@aiur-io/react","name":"@aiur-io/react","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aiur-io/react","version":"1.0.0","description":"React bindings for the Aiur JavaScript SDK.","private":false,"license":"MIT","main":"dist/index.cjs","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs","types":"./dist/index.d.ts"}},"sideEffects":false,"dependencies":{"@aiur-io/core":"1.0.0"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts","clean":"rm -rf dist"},"_id":"@aiur-io/react@1.0.0","_integrity":"sha512-Au4k9eW57YBJuMiHufixGJS/3ccSag1iwUWjSSjzLgZgBsQ0WgxtiyaYeX4z9EyO3i1nDJejEqAwLQjuE951Aw==","_resolved":"/private/var/folders/b6/pnmbx3fx0qq_d33s5rfx_gg00000gn/T/8bfc224b441103af8ffd5fefa4413828/aiur-io-react-1.0.0.tgz","_from":"file:aiur-io-react-1.0.0.tgz","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Au4k9eW57YBJuMiHufixGJS/3ccSag1iwUWjSSjzLgZgBsQ0WgxtiyaYeX4z9EyO3i1nDJejEqAwLQjuE951Aw==","shasum":"f3c40ec2022ca6225ff451d6861d2751eeb0d131","tarball":"https://registry.npmjs.org/@aiur-io/react/-/react-1.0.0.tgz","fileCount":8,"unpackedSize":97381,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBcfdnmqBpZmfMqtyXcJZF3UMMC0p+ERM911XTDyhjCpAiEAq+dw7jlI+7juyBKxFFTo1sqwaR3oKvbTlVQxWxmusuQ="}]},"_npmUser":{"name":"aiur-bot","email":"ops@aiur.io"},"directories":{},"maintainers":[{"name":"aiur-bot","email":"ops@aiur.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react_1.0.0_1765572384159_0.026382202208196093"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-12T20:46:23.951Z","1.0.0":"2025-12-12T20:46:24.365Z","modified":"2025-12-12T20:46:24.683Z"},"maintainers":[{"name":"aiur-bot","email":"ops@aiur.io"}],"description":"React bindings for the Aiur JavaScript SDK.","license":"MIT","readme":"# @aiur-io/react\n\nReact bindings for the Aiur JavaScript / TypeScript SDK.\n\nThis package provides idiomatic React primitives for integrating Aiur into\nclient-side React applications. It builds on top of `@aiur-io/core` and\nadds:\n\n- A top-level provider (`AiurProvider`)\n- A hook for emitting events (`useAiur`)\n- Optional automatic capture of user interactions (clicks, forms, media)\n- Access to remotely managed SDK configuration\n\nMost React applications should install the unified entrypoint instead:\n\n```bash\npnpm add aiur-io\n# or\nnpm install aiur-io\n# or\nyarn add aiur-io\n# or\nbun add aiur-io\n```\n\nUse `@aiur-io/react` directly when you want explicit control over React\nintegration without the Next.js routing layer.\n\n---\n\n## Installation\n\n```bash\npnpm add @aiur-io/react\n# or\nnpm install @aiur-io/react\n# or\nyarn add @aiur-io/react\n# or\nbun add @aiur-io/react\n```\n\n---\n\n## What this package does (and does not do)\n\n### Provides\n\n- React context for the Aiur client\n- `useAiur()` hook for `track` and `identify`\n- Automatic interaction capture (optional, remote-controlled)\n- Safe default initialization of `@aiur-io/core` in the browser\n\n### Does NOT provide\n\n- Server-side support (use `@aiur-io/core` directly)\n- Next.js routing awareness (use `@aiur-io/next`)\n- Any business logic, analytics UI, or dashboards\n\n---\n\n## Quickstart\n\nWrap your application near the root:\n\n```tsx\nimport { AiurProvider } from \"@aiur-io/react\";\n\nexport default function App({ children }: { children: React.ReactNode }) {\n  return <AiurProvider publicKey=\"aiur_pk_test_demo\">{children}</AiurProvider>;\n}\n```\n\nEmit events anywhere in the tree:\n\n```tsx\nimport { useAiur } from \"@aiur-io/react\";\n\nfunction ExampleButton() {\n  const { track } = useAiur();\n\n  return (\n    <button onClick={() => track(\"demo.click\", { location: \"home\" })}>\n      Click me\n    </button>\n  );\n}\n```\n\n---\n\n## `useAiur()` hook\n\n```ts\nconst { track, identify, config } = useAiur();\n```\n\n### Returned values\n\n- `track(type, properties?, options?)`\n- `identify(userId, traits?, options?)`\n- `config.sdk` – remote SDK configuration (`SdkConfig | null`)\n- `config.client` – client initialization config (`AiurConfig | null`)\n\nExample:\n\n```tsx\nconst { track, identify, config } = useAiur();\n\nidentify(\"user_123\");\n\ntrack(\"profile.updated\", {\n  source: \"settings_page\",\n});\n\nif (config.sdk?.autoCapture?.clicks) {\n  // remote config is available\n}\n```\n\n---\n\n## Auto-Capture (optional)\n\nWhen enabled, the SDK can automatically emit:\n\n- Click interactions\n- Form submissions (metadata only, never values)\n- Media interactions (play / pause / seek)\n\n### Key points\n\n- **Off by default**\n- Controlled remotely from the Aiur console\n- Changes apply without redeploying\n- Safe by default (no form values, sanitized URLs)\n\nAuto-capture is installed automatically by `AiurProvider`.\n\nYou can override behavior locally:\n\n```tsx\n<AiurProvider publicKey=\"aiur_pk_test_demo\" autoCapture={{ clicks: false }}>\n  {children}\n</AiurProvider>\n```\n\nLocal overrides take precedence over remote config for that category.\n\n---\n\n## Configuration\n\n`AiurProvider` accepts the same configuration as `@aiur-io/core`, plus\noptional React-specific hints:\n\n```ts\ntype AiurProviderProps = {\n  publicKey: string;\n  endpoint?: string;\n  env?: \"dev\" | \"staging\" | \"prod\";\n  debug?: boolean;\n\n  autoCapture?: {\n    clicks?: boolean;\n    forms?: boolean;\n    media?: boolean;\n  };\n\n  children?: React.ReactNode;\n};\n```\n\n---\n\n## Runtime guarantees\n\nWhen used in a browser environment, `@aiur-io/react` inherits all guarantees\nfrom `@aiur-io/core`, including:\n\n- At-least-once delivery within a bounded retry window\n- Stable event IDs across retries\n- Offline persistence via IndexedDB\n- ACK-driven deletion\n- Deterministic retry and backoff behavior\n\nThese guarantees are enforced by automated contract tests.\n\nFor full semantics, see:\n\n→ [`docs/sdk-v1.md`](../../docs/sdk-v1.md)\n\n---\n\n## When NOT to use this package\n\n- Server-only environments (Node, workers, cron jobs)\n- Next.js applications that need route tracking\n- Non-React frameworks\n\nIn those cases, use:\n\n- `@aiur-io/core` (server / framework-agnostic)\n- `@aiur-io/next` (Next.js)\n\n---\n\n## Versioning\n\n`@aiur-io/react` follows unified semantic versioning with all Aiur JS packages.\n\nBreaking changes result in a major version bump.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-fa97589076622ae3fd6c62c4bf8280bb"}