@raykolabs/analytics-server

Server SDK for Rayko Analytics.

Universal fetch-based — works in Node 18+, Next.js API routes, Vercel Edge, Cloudflare Workers, Bun, and Deno. ~9KB minified.

Install

npm install @raykolabs/analytics-server

Usage

import { rayko } from "@raykolabs/analytics-server";

rayko.init({
  apiKey: process.env.RAYKO_SERVER_KEY!,        // rk_secret_xxx
  apiHost: "https://data.example.com",
  app: "my-api",
});

await rayko.capture({
  distinctId: visitorIdFromCookie,
  event: "lead_captured",
  properties: { source: "demo", plan: "pro" },
});

await rayko.identify({
  distinctId: visitorIdFromCookie,
  userId: leadId,
  traits: { email, name },
});

await rayko.group({
  distinctId: leadId,
  type: "company",
  key: companyId,
  traits: { name, plan },
});

await rayko.flush();      // drain queue (call before serverless return)
await rayko.shutdown();   // flush + stop timers

Why server-side?

Critical conversion events should fire server-side because:

• They beat browser-level ad blockers
• They survive client-side errors / network flaps
• They run with the canonical state of the world (DB transaction succeeded, payment processed, etc.)

Typical server-side events: lead_captured, signup_completed, payment_succeeded, subscription_created.

Configuration

rayko.init({
  apiKey: "rk_secret_xxx",
  apiHost: "https://data.example.com",
  // Optional:
  app: "my-api",
  env: "production",
  flushAt: 1,             // 1 = no batching (default; right for serverless)
  flushIntervalMs: 0,     // 0 = no timer flushes (default)
  retryMax: 3,
  timeoutMs: 5000,
  fetch: customFetch,     // override fetch implementation
});

Browser-side?

For client-side events (autocapture, pageviews, identify on form submit), use @raykolabs/analytics.

License

MIT