@aiur-io/core

Low-level JavaScript/TypeScript client for emitting verified events into a Nexus on the Aiur platform.

This package defines the canonical event protocol, initialization flow, delivery semantics, and the fundamental primitives (track, identify, emit) used by all higher-level Aiur SDKs:

• aiur-io (meta package)
• @aiur-io/react
• @aiur-io/next
• server runtimes, workers, and edge environments

Most applications should install the unified entrypoint:

pnpm add aiur-io
# or
npm install aiur-io
# or
yarn add aiur-io
# or
bun add aiur-io

Use @aiur-io/core directly when you need full control, or when integrating Aiur outside of React/Next/browser contexts.

Installation

pnpm add @aiur-io/core
# or
npm install @aiur-io/core
# or
yarn add @aiur-io/core
# or
bun add @aiur-io/core

Overview

@aiur-io/core provides:

• A stable, versioned event model (AiurEvent)
• Client initialization (init, initServer)
• Event emission (track, emit)
• User identity management (identify)
• Server-safe isolated clients (createClient)
• Browser context enrichment (URL, session, device)
• Deterministic batching, retries, and backoff
• Offline persistence in browser environments

It intentionally does not include:

• React bindings
• Next.js routing awareness
• Automatic capture of clicks, forms, or page views

Those behaviors live in higher-level packages.

Quickstart (browser or simple app)

import { init, track, identify } from "@aiur-io/core";

init({
  publicKey: "aiur_pk_test_demo",
  endpoint: "https://capture.aiur.io/events", // optional
});

track("demo.event", { location: "homepage" });

identify("user_123", { plan: "pro" });

Call init() once before emitting events.

Server usage (recommended pattern)

On servers, do not use the singleton client. Always create an isolated client per request or job scope.

import { createClient } from "@aiur-io/core";

export async function handler(req: Request) {
  const aiur = createClient({
    publicKey: process.env.AIUR_PUBLIC_KEY!,
    env: "prod",
  });

  aiur.identify("user_123");
  aiur.track("purchase.completed", { value: 42 });

  await aiur.flush(); // best-effort delivery before returning
}

This prevents identity bleed across concurrent requests.

API Reference

init(config: AiurConfig): void

Initialize the singleton client (browser / simple usage).

type AiurConfig = {
  publicKey: string;
  endpoint?: string; // defaults to Aiur capture endpoint
  env?: "dev" | "staging" | "prod";
  debug?: boolean;
};

createClient(config: AiurConfig)

Create an isolated client instance.

const aiur = createClient({ publicKey });
aiur.track("event.type");
await aiur.flush();

Use this for:

• servers
• workers
• background jobs
• concurrent request handling

track(type, properties?, options?)

Emit a structured event.

track("ui.click", {
  path: "/checkout",
  element: "button",
});

Optional per-call options:

type TrackOptions = {
  timestamp?: string;
  userId?: string;
  anonymousId?: string;
  contextOverrides?: Record<string, unknown>;
};

identify(userId, traits?, options?)

Associate a stable user identity with subsequent events.

identify("user_123", { plan: "pro" });

This also emits a user.identify event.

emit(event: AiurEvent)

Send a fully constructed event object.

Use this only when you need total control over the payload.

flush(): Promise<void>

Attempt to deliver queued events immediately.

• On servers: call explicitly if you need best-effort delivery before exit.
• In browsers: usually not required (automatic flushing is installed).

Event Model (v1)

All events sent to Aiur use a stable, versioned wire format:

type AiurEvent = {
  version: 1;
  eventId: string; // UUID v4
  type: string;
  timestamp: string; // ISO-8601 UTC

  user?: {
    id?: string;
    anonymousId?: string;
  };

  context?: Record<string, unknown>;
  properties?: Record<string, unknown>;

  source: {
    sdkName: string; // e.g. "aiur-js-core"
    sdkVersion: string;
    env?: string;
  };
};

The SDK guarantees:

• stable eventId across retries
• deterministic retry behavior
• compatibility across browser, Node, Edge, and worker runtimes

Delivery Guarantees (v1)

@aiur-io/core provides concrete, tested guarantees:

• At-least-once delivery within a bounded retry window
• Deterministic retries with exponential backoff
• Offline persistence in browsers via IndexedDB
• ACK-driven deletion (events removed only after acceptance)
• Bounded durability (events dropped after configured age/attempt limits)
• Safe payload handling (non-serializable payloads are rejected locally)

All guarantees are enforced by automated contract tests.

For full semantics and edge cases, see:

→ docs/sdk-v1.md

Versioning

@aiur-io/core follows unified semantic versioning with all Aiur JS packages.

Breaking changes result in a major version bump.

License

MIT