JavaScript (Node.js) SDK

npm install @klime/node

// ESM
import { KlimeClient } from "@klime/node";

// CommonJS
// const { KlimeClient } = require("@klime/node");

const client = new KlimeClient({
  writeKey: "your-write-key",
});

// Identify a user
client.identify("user_123", {
  email: "user@example.com",
  name: "Stefan",
});

// Track an event
client.track(
  "Button Clicked",
  {
    buttonName: "Sign up",
    plan: "pro",
  },
  { userId: "user_123" }
);

// Associate user with a group and set group traits
client.group(
  "org_456",
  { name: "Acme Inc", plan: "enterprise" },
  { userId: "user_123" }
);

// Or just link the user to a group (if traits are already set)
client.group("org_456", null, { userId: "user_123" });

// Shutdown gracefully
process.on("SIGTERM", async () => {
  await client.shutdown();
  process.exit(0);
});

new KlimeClient(config: {
  writeKey: string;              // Required: Your Klime write key
  endpoint?: string;              // Optional: API endpoint (default: https://i.klime.com)
  flushInterval?: number;        // Optional: Milliseconds between flushes (default: 2000)
  maxBatchSize?: number;         // Optional: Max events per batch (default: 20, max: 100)
  maxQueueSize?: number;         // Optional: Max queued events (default: 1000)
  retryMaxAttempts?: number;     // Optional: Max retry attempts (default: 5)
  retryInitialDelay?: number;    // Optional: Initial retry delay in ms (default: 1000)
  flushOnShutdown?: boolean;     // Optional: Auto-flush on SIGTERM/SIGINT (default: true)
  logger?: Logger;               // Optional: Custom logger (default: console with [Klime] prefix)
  onError?: (error, events) => void;   // Optional: Callback for batch failures
  onSuccess?: (response) => void;      // Optional: Callback for successful sends
})

// User event (most common)
client.track(
  "Button Clicked",
  {
    buttonName: "Sign up",
    plan: "pro",
  },
  { userId: "user_123" }
);

// Group event (for webhooks, cron jobs, system events)
client.track(
  "Events Received",
  {
    count: 100,
    source: "webhook",
  },
  { groupId: "org_456" }
);

client.identify("user_123", {
  email: "user@example.com",
  name: "Stefan",
});

// Associate user with a group and set group traits (most common)
client.group(
  "org_456",
  { name: "Acme Inc", plan: "enterprise" },
  { userId: "user_123" }
);

// Just link a user to a group (traits already set or not needed)
client.group("org_456", null, { userId: "user_123" });

// Just update group traits (e.g., from a webhook or background job)
client.group("org_456", { plan: "enterprise", employeeCount: 50 });

await client.flush();

await client.shutdown();

const pending = client.getQueueSize();
console.log(`${pending} events waiting to be sent`);

const { SendError } = require("@klime/node");

try {
  const response = await client.trackSync(
    "Critical Action",
    { key: "value" },
    { userId: "user_123" }
  );
  console.log(`Sent! Accepted: ${response.accepted}`);
} catch (error) {
  if (error instanceof SendError) {
    console.error(`Failed to send: ${error.message}`);
  }
}

// This returns immediately - no HTTP request is made here
client.track("Button Clicked", { button: "signup" }, { userId: "user_123" });

// Your code continues without waiting
res.json({ success: true });

const client = new KlimeClient({
  writeKey: "your-write-key",
  logger: {
    debug: (msg, ...args) => myLogger.debug(msg, ...args),
    info: (msg, ...args) => myLogger.info(msg, ...args),
    warn: (msg, ...args) => myLogger.warn(msg, ...args),
    error: (msg, ...args) => myLogger.error(msg, ...args),
  },
});

const client = new KlimeClient({
  writeKey: "your-write-key",
  onError: (error, events) => {
    // Report to your error tracking service
    Sentry.captureException(error);
    console.error(`Failed to send ${events.length} events: ${error.message}`);
  },
  onSuccess: (response) => {
    console.log(`Sent ${response.accepted} events`);
  },
});

const { KlimeClient, SendError } = require("@klime/node");

try {
  const response = await client.trackSync("Event", {}, { userId: "user_123" });
} catch (error) {
  if (error instanceof SendError) {
    console.error(`Failed: ${error.message}, events: ${error.events.length}`);
  }
}