{"_id":"@aiur-io/next","name":"@aiur-io/next","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aiur-io/next","version":"1.0.0","description":"Next.js integration 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/react":"1.0.0","@aiur-io/core":"1.0.0"},"peerDependencies":{"next":"^13.0.0 || ^14.0.0 || ^15.0.0","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/next@1.0.0","_integrity":"sha512-ddd0tngYk2CdewYXRrHUt6l3oJ9eqDZJK8O1OL6TyemN0AUFNCpwYr0yYiMALLq0fvPGh2KWLsXYw7mtqlirWQ==","_resolved":"/private/var/folders/b6/pnmbx3fx0qq_d33s5rfx_gg00000gn/T/06655e0d6e5de169c6eb49827d056eb6/aiur-io-next-1.0.0.tgz","_from":"file:aiur-io-next-1.0.0.tgz","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-ddd0tngYk2CdewYXRrHUt6l3oJ9eqDZJK8O1OL6TyemN0AUFNCpwYr0yYiMALLq0fvPGh2KWLsXYw7mtqlirWQ==","shasum":"7b2ae75f0cf7afabd2f97125ea413b5a051423da","tarball":"https://registry.npmjs.org/@aiur-io/next/-/next-1.0.0.tgz","fileCount":8,"unpackedSize":48934,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCETFVM1D31N30uSI1mWfvafY094lBD510oIR3JdMXFMwIhAM7OpdKCqXbGyq1YjtmCQLeCnQufI4SwjjwUIEw/tAi/"}]},"_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/next_1.0.0_1765572405872_0.9439348371017537"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-12T20:46:45.703Z","1.0.0":"2025-12-12T20:46:46.057Z","modified":"2025-12-12T20:46:46.417Z"},"maintainers":[{"name":"aiur-bot","email":"ops@aiur.io"}],"description":"Next.js integration for the Aiur JavaScript SDK.","license":"MIT","readme":"# @aiur-io/next\n\nNext.js integration for the Aiur JavaScript / TypeScript SDK.\n\nThis package builds on top of `@aiur-io/react` and `@aiur-io/core` to provide\n**client-side route awareness** for Next.js applications.\n\nIt is the recommended package for integrating Aiur into:\n\n- Next.js App Router (`app/`)\n- Next.js Pages Router (`pages/`)\n\nMost Next.js 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/next` directly when you want explicit control over the Next.js\nintegration layer.\n\n---\n\n## Installation\n\n```bash\npnpm add @aiur-io/next\n# or\nnpm install @aiur-io/next\n# or\nyarn add @aiur-io/next\n# or\nbun add @aiur-io/next\n```\n\n---\n\n## What this package does (and does not do)\n\n### Provides\n\n- A Next-aware provider (`AiurNextProvider`)\n- Client-side route tracking (`page.view`, `route.change`)\n- Compatibility with both App Router and Pages Router\n- Remote-controlled route auto-capture\n\n### Does NOT provide\n\n- Server-side instrumentation (use `@aiur-io/core`)\n- React bindings beyond what `@aiur-io/react` already exposes\n- Automatic data fetching or middleware hooks\n\nThis package runs **only in the browser**.\n\n---\n\n## Quickstart (App Router)\n\nWrap your application layout:\n\n```tsx\n// app/layout.tsx\nimport { AiurNextProvider } from \"aiur-io\";\n\nexport default function RootLayout({\n children,\n}: {\n children: React.ReactNode;\n}) {\n return (\n \n \n \n {children}\n \n \n \n );\n}\n```\n\nEmit events anywhere in your app:\n\n```tsx\n\"use client\";\n\nimport { useAiur } from \"aiur-io\";\n\nexport default function Example() {\n const { track } = useAiur();\n\n return (\n \n );\n}\n```\n\n---\n\n## Quickstart (Pages Router)\n\n```tsx\n// pages/_app.tsx\nimport type { AppProps } from \"next/app\";\nimport { AiurNextProvider } from \"aiur-io\";\n\nexport default function MyApp({ Component, pageProps }: AppProps) {\n return (\n \n \n \n );\n}\n```\n\n---\n\n## Route Tracking\n\nWhen enabled, the SDK can automatically emit:\n\n- `page.view` – initial page load and subsequent navigations\n- `route.change` – transitions between routes\n\n### Key properties\n\n- Uses **sanitized URLs** (query and hash removed)\n- Does not emit duplicate events for query-only changes\n- Emits events only on the client\n\n### Control modes\n\nRoute tracking is controlled by **remote SDK configuration** fetched from\nthe Aiur console.\n\nYou can also override behavior locally:\n\n```tsx\n\n {children}\n\n```\n\nSupported modes:\n\n- `\"remote\"` (default) – obey remote config\n- `\"on\"` – always track routes\n- `\"off\"` – never track routes\n\n---\n\n## Configuration\n\n`AiurNextProvider` accepts all props supported by `AiurProvider`, plus an\noptional route tracking override:\n\n```ts\ntype AiurNextProviderProps = {\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 routeTrackingMode?: \"remote\" | \"on\" | \"off\";\n\n children?: React.ReactNode;\n};\n```\n\n---\n\n## Runtime guarantees\n\nWhen used in a Next.js browser environment, `@aiur-io/next` inherits all\ndelivery and persistence guarantees from `@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\nAll 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 (API routes, middleware, cron jobs)\n- Non-Next.js React apps\n- Worker or edge runtimes without a browser environment\n\nIn those cases, use:\n\n- `@aiur-io/core` (framework-agnostic)\n- `@aiur-io/react` (React without routing)\n\n---\n\n## Versioning\n\n`@aiur-io/next` 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-4ed3bb2be74537536bd105643e84ea31"}