{"_id":"@aiur-io/core","name":"@aiur-io/core","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aiur-io/core","version":"1.0.0","description":"Core JavaScript/TypeScript client and event protocol for the Aiur platform.","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":{"zod":"^4.1.13"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts","clean":"rm -rf dist"},"_id":"@aiur-io/core@1.0.0","_integrity":"sha512-Yb7Jaow1elFClKgEIiLShA1U3fiJ+KC9FCsITrHauqlY8hgJ2RRCnyQCg0guYkXcCGR0SHs50LOx+oJHuCOj6w==","_resolved":"/private/var/folders/b6/pnmbx3fx0qq_d33s5rfx_gg00000gn/T/9ecfcec25b7cbf6c783b212ce7d057b7/aiur-io-core-1.0.0.tgz","_from":"file:aiur-io-core-1.0.0.tgz","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Yb7Jaow1elFClKgEIiLShA1U3fiJ+KC9FCsITrHauqlY8hgJ2RRCnyQCg0guYkXcCGR0SHs50LOx+oJHuCOj6w==","shasum":"011bd74882d232f09345634a6175985a39627715","tarball":"https://registry.npmjs.org/@aiur-io/core/-/core-1.0.0.tgz","fileCount":8,"unpackedSize":354219,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDs35G4lYOgy1HMTdtg6w6bGp1xvvmNltjXxkws+dfDyQIgfx6nwblR5xipb1WtCNBNIEh1luSe0KxVzskC+LYmvYY="}]},"_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/core_1.0.0_1765572314827_0.4613029302664913"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-12T20:45:14.767Z","1.0.0":"2025-12-12T20:45:15.023Z","modified":"2025-12-12T20:45:15.287Z"},"maintainers":[{"name":"aiur-bot","email":"ops@aiur.io"}],"description":"Core JavaScript/TypeScript client and event protocol for the Aiur platform.","license":"MIT","readme":"# @aiur-io/core\n\nLow-level JavaScript/TypeScript client for emitting **verified events** into a\nNexus on the Aiur platform.\n\nThis package defines the **canonical event protocol**, initialization flow,\ndelivery semantics, and the fundamental primitives (`track`, `identify`,\n`emit`) used by all higher-level Aiur SDKs:\n\n- `aiur-io` (meta package)\n- `@aiur-io/react`\n- `@aiur-io/next`\n- server runtimes, workers, and edge environments\n\nMost applications should install the unified entrypoint:\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/core` directly when you need **full control**, or when integrating\nAiur outside of React/Next/browser contexts.\n\n---\n\n## Installation\n\n```bash\npnpm add @aiur-io/core\n# or\nnpm install @aiur-io/core\n# or\nyarn add @aiur-io/core\n# or\nbun add @aiur-io/core\n```\n\n---\n\n## Overview\n\n`@aiur-io/core` provides:\n\n- A stable, versioned event model (`AiurEvent`)\n- Client initialization (`init`, `initServer`)\n- Event emission (`track`, `emit`)\n- User identity management (`identify`)\n- Server-safe isolated clients (`createClient`)\n- Browser context enrichment (URL, session, device)\n- Deterministic batching, retries, and backoff\n- Offline persistence in browser environments\n\nIt intentionally does **not** include:\n\n- React bindings\n- Next.js routing awareness\n- Automatic capture of clicks, forms, or page views\n\nThose behaviors live in higher-level packages.\n\n---\n\n## Quickstart (browser or simple app)\n\n```ts\nimport { init, track, identify } from \"@aiur-io/core\";\n\ninit({\n  publicKey: \"aiur_pk_test_demo\",\n  endpoint: \"https://capture.aiur.io/events\", // optional\n});\n\ntrack(\"demo.event\", { location: \"homepage\" });\n\nidentify(\"user_123\", { plan: \"pro\" });\n```\n\nCall `init()` once before emitting events.\n\n---\n\n## Server usage (recommended pattern)\n\nOn servers, **do not use the singleton client**.\nAlways create an isolated client per request or job scope.\n\n```ts\nimport { createClient } from \"@aiur-io/core\";\n\nexport async function handler(req: Request) {\n  const aiur = createClient({\n    publicKey: process.env.AIUR_PUBLIC_KEY!,\n    env: \"prod\",\n  });\n\n  aiur.identify(\"user_123\");\n  aiur.track(\"purchase.completed\", { value: 42 });\n\n  await aiur.flush(); // best-effort delivery before returning\n}\n```\n\nThis prevents identity bleed across concurrent requests.\n\n---\n\n## API Reference\n\n### `init(config: AiurConfig): void`\n\nInitialize the singleton client (browser / simple usage).\n\n```ts\ntype AiurConfig = {\n  publicKey: string;\n  endpoint?: string; // defaults to Aiur capture endpoint\n  env?: \"dev\" | \"staging\" | \"prod\";\n  debug?: boolean;\n};\n```\n\n---\n\n### `createClient(config: AiurConfig)`\n\nCreate an isolated client instance.\n\n```ts\nconst aiur = createClient({ publicKey });\naiur.track(\"event.type\");\nawait aiur.flush();\n```\n\nUse this for:\n\n- servers\n- workers\n- background jobs\n- concurrent request handling\n\n---\n\n### `track(type, properties?, options?)`\n\nEmit a structured event.\n\n```ts\ntrack(\"ui.click\", {\n  path: \"/checkout\",\n  element: \"button\",\n});\n```\n\nOptional per-call options:\n\n```ts\ntype TrackOptions = {\n  timestamp?: string;\n  userId?: string;\n  anonymousId?: string;\n  contextOverrides?: Record<string, unknown>;\n};\n```\n\n---\n\n### `identify(userId, traits?, options?)`\n\nAssociate a stable user identity with subsequent events.\n\n```ts\nidentify(\"user_123\", { plan: \"pro\" });\n```\n\nThis also emits a `user.identify` event.\n\n---\n\n### `emit(event: AiurEvent)`\n\nSend a fully constructed event object.\n\nUse this only when you need total control over the payload.\n\n---\n\n### `flush(): Promise<void>`\n\nAttempt to deliver queued events immediately.\n\n- On servers: call explicitly if you need best-effort delivery before exit.\n- In browsers: usually not required (automatic flushing is installed).\n\n---\n\n## Event Model (v1)\n\nAll events sent to Aiur use a **stable, versioned wire format**:\n\n```ts\ntype AiurEvent = {\n  version: 1;\n  eventId: string; // UUID v4\n  type: string;\n  timestamp: string; // ISO-8601 UTC\n\n  user?: {\n    id?: string;\n    anonymousId?: string;\n  };\n\n  context?: Record<string, unknown>;\n  properties?: Record<string, unknown>;\n\n  source: {\n    sdkName: string; // e.g. \"aiur-js-core\"\n    sdkVersion: string;\n    env?: string;\n  };\n};\n```\n\nThe SDK guarantees:\n\n- stable `eventId` across retries\n- deterministic retry behavior\n- compatibility across browser, Node, Edge, and worker runtimes\n\n---\n\n## Delivery Guarantees (v1)\n\n`@aiur-io/core` provides **concrete, tested guarantees**:\n\n- **At-least-once delivery** within a bounded retry window\n- **Deterministic retries** with exponential backoff\n- **Offline persistence** in browsers via IndexedDB\n- **ACK-driven deletion** (events removed only after acceptance)\n- **Bounded durability** (events dropped after configured age/attempt limits)\n- **Safe payload handling** (non-serializable payloads are rejected locally)\n\nAll guarantees are enforced by automated contract tests.\n\nFor full semantics and edge cases, see:\n\n→ [`docs/sdk-v1.md`](../../docs/sdk-v1.md)\n\n---\n\n## Versioning\n\n`@aiur-io/core` 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-7ed3dd04382b9a8e0e2888a428720b19"}