@osirisai/sdk

Official JavaScript / TypeScript SDK for Osiris AI — a real-time analytics platform built on Kafka with Avro schema validation, a live event console, and 90-day searchable archive.

Works in browsers, Node.js (≥18), and edge runtimes that provide global fetch.

Quick links

• 🚀 Open the Osiris AI console — sign in, view events live, manage API keys
• 🔑 Create an API key — required for the SDK
• 📈 See your events — Live Stream tab, plus historical search up to 90 days
• 📖 Product page — features, pricing, architecture
• 💬 Get help — email [email protected]

Install

npm install @osirisai/sdk
# or
pnpm add @osirisai/sdk
# or
yarn add @osirisai/sdk

Get an API key

1. Sign in at talentmirror.ai/osirisai (Google SSO or magic link).
2. Open Settings → API Keys and click Create key.
3. Copy the key (it's shown once) and store it as OSIRIS_API_KEY in your environment.

ℹ️ API keys are workspace-scoped. Events sent with a key always land in that workspace's topic and archive.

Quick start

import { createClient } from '@osirisai/sdk';

const osiris = createClient({
  apiKey: process.env.OSIRIS_API_KEY!,
  endpoint: 'https://talentmirror.ai/osirisai', // or your self-hosted gateway
  source: 'web'
});

osiris.track({
  type: 'purchase',
  userId: 'usr_123',
  payload: { amount: 142.5, currency: 'USD', items: 3 }
});

osiris.identify('usr_123', { plan: 'pro', signed_up_at: '2026-01-12' });

Open the Live Stream tab in the console — your event will appear within ~1 second.

Behavior

• Batching. Events are buffered and flushed when the batch size (default 20) or interval (default 5s) is reached.
• Retries. Failed batches retry up to 3 times with exponential backoff + jitter. 4xx responses (except 429) drop the batch immediately.
• Browser unload. A pagehide / beforeunload handler flushes pending events via navigator.sendBeacon so nothing is lost when the user navigates away.
• Bring-your-own fetch. Pass config.fetch if you're targeting Node ≤17 or a runtime without a global fetch.

API

createClient(config) / new OsirisClient(config)

| Field | Type | Default | Notes | |---|---|---|---| | apiKey | string | required | Sent as Authorization: Bearer <key>. Get one at talentmirror.ai/osirisai. | | endpoint | string | required | Your gateway's base URL — usually https://talentmirror.ai/osirisai for hosted, or your own URL for self-hosted. The SDK appends /v1/events automatically. | | source | string | required | Logical source identifier (e.g. web, ios, checkout-service). | | batchSize | number | 20 | Auto-flush threshold. | | flushIntervalMs | number | 5000 | Auto-flush interval in ms. | | maxRetries | number | 3 | Per-batch retry count. | | fetch | typeof fetch | globalThis.fetch | Override fetch implementation. | | logger | { warn } | console | Diagnostic logger. | | traces.propagate | boolean | false | Auto-generate a W3C traceparent header per batch so the gateway becomes a child span. Use when you don't have your own OTel SDK active. | | traces.getTraceparent | () => string \| undefined | — | Plug in your app's active OTel span context. Takes precedence over propagate. |

client.track({ type, payload?, userId?, anonymousId?, metadata?, timestamp? })

Returns { eventId, delivered } where delivered is a Promise<boolean> resolving once the containing batch flushes.

client.identify(userId, traits?)

Sugar for track({ type: 'identify', userId, payload: traits }).

client.flush()

Force-flush the queue. Awaitable.

client.close()

Stop accepting new events and flush remaining. Use during graceful server shutdown.

Where do my events go?

Every event you track() lands in two places, both visible from the console:

1. Kafka topic osiris.events.<workspace> — real-time stream, 30-day retention. Powers the Live Stream tab.
2. Postgres archive (events_archive table) — 90-day searchable history. Powers the Search tab and historical analytics.

Right-to-erasure deletes propagate to both tiers immediately.

Distributed tracing

Pass traces to propagate W3C trace context from your application into the Osiris gateway:

// Option A — let the SDK generate trace IDs (no OTel setup required)
createClient({ ..., traces: { propagate: true } });

// Option B — forward your app's active OTel span
import { trace } from '@opentelemetry/api';

createClient({
  ...,
  traces: {
    getTraceparent: () => {
      const ctx = trace.getActiveSpan()?.spanContext();
      return ctx ? `00-${ctx.traceId}-${ctx.spanId}-01` : undefined;
    }
  }
});

Payload values

Payload values are constrained to primitives: string | number | boolean | null. Nest structured data via dot-prefixed keys (address.city) or stringify it.

Resources

• Console: talentmirror.ai/osirisai
• Product overview: talentmirror.ai/products/osirisai
• Support: talentmirror.ai/contact · [email protected]
• Privacy policy: talentmirror.ai/privacy-policy

License

MIT