@klime/node 1.0.3

package/README.md

@@ -0,0 +1,229 @@
+# @klime/node
+
+Klime SDK for Node.js.
+
+## Installation
+
+```bash
+npm install @klime/node
+```
+
+## Quick Start
+
+```javascript
+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);
+});
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+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)
+})
+```
+
+### Methods
+
+#### `track(event: string, properties?: object, options?: { userId?, groupId?, ip? })`
+
+Track a user event. A `userId` is required for events to be useful in Klime.
+
+```javascript
+client.track(
+  "Button Clicked",
+  {
+    buttonName: "Sign up",
+    plan: "pro",
+  },
+  { userId: "user_123" }
+);
+
+// With IP address (for geolocation)
+client.track(
+  "Button Clicked",
+  {
+    buttonName: "Sign up",
+    plan: "pro",
+  },
+  {
+    userId: "user_123",
+    ip: "192.168.1.1",
+  }
+);
+```
+
+> **Advanced**: The `groupId` option is available for multi-tenant scenarios where a user belongs to multiple organizations and you need to specify which organization context the event occurred in.
+
+#### `identify(userId: string, traits?: object, options?: { ip? })`
+
+Identify a user with traits.
+
+```javascript
+client.identify(
+  "user_123",
+  {
+    email: "user@example.com",
+    name: "Stefan",
+  },
+  {
+    ip: "192.168.1.1",
+  }
+);
+```
+
+#### `group(groupId: string, traits?: object, options?: { userId?, ip? })`
+
+Associate a user with a group and/or set group traits.
+
+```javascript
+// 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 });
+```
+
+#### `flush(): Promise<void>`
+
+Manually flush queued events immediately.
+
+```javascript
+await client.flush();
+```
+
+#### `shutdown(): Promise<void>`
+
+Gracefully shutdown the client, flushing remaining events.
+
+```javascript
+await client.shutdown();
+```
+
+## Features
+
+- **Automatic Batching**: Events are automatically batched and sent every 2 seconds or when the batch size reaches 20 events
+- **Automatic Retries**: Failed requests are automatically retried with exponential backoff
+- **Process Exit Handling**: Automatically flushes events on SIGTERM/SIGINT
+- **Zero Dependencies**: Uses only Node.js standard library (fetch for Node 18+, https/http for older versions)
+
+## Configuration
+
+### Default Values
+
+- `flushInterval`: 2000ms
+- `maxBatchSize`: 20 events
+- `maxQueueSize`: 1000 events
+- `retryMaxAttempts`: 5 attempts
+- `retryInitialDelay`: 1000ms
+- `flushOnShutdown`: true
+
+## Error Handling
+
+The SDK automatically handles:
+
+- **Transient errors** (429, 503, network failures): Retries with exponential backoff
+- **Permanent errors** (400, 401): Logs error and drops event
+- **Rate limiting**: Respects `Retry-After` header
+
+## Size Limits
+
+- Maximum event size: 200KB
+- Maximum batch size: 10MB
+- Maximum events per batch: 100
+
+Events exceeding these limits are rejected and logged.
+
+## Express.js Example
+
+```javascript
+const express = require("express");
+const { KlimeClient } = require("@klime/node");
+
+const app = express();
+const client = new KlimeClient({
+  writeKey: process.env.KLIME_WRITE_KEY,
+});
+
+app.post("/api/button-clicked", (req, res) => {
+  client.track(
+    "Button Clicked",
+    {
+      buttonName: req.body.buttonName,
+    },
+    {
+      userId: req.user.id,
+      ip: req.ip,
+    }
+  );
+
+  res.json({ success: true });
+});
+
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  await client.shutdown();
+  process.exit(0);
+});
+```
+
+## Requirements
+
+- Node.js 14.0.0 or higher
+- For Node.js 18+, native `fetch` is used
+- For Node.js 14-17, `https`/`http` modules are used
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { KlimeConfig, TrackOptions, IdentifyOptions, GroupOptions } from "./types";
+export declare class KlimeClient {
+    private config;
+    private queue;
+    private flushTimer;
+    private isShutdown;
+    private flushPromise;
+    private shutdownHandlers;
+    constructor(config: KlimeConfig);
+    track(event: string, properties?: Record<string, any>, options?: TrackOptions): void;
+    identify(userId: string, traits?: Record<string, any>, options?: IdentifyOptions): void;
+    group(groupId: string, traits?: Record<string, any>, options?: GroupOptions): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private enqueue;
+    private doFlush;
+    private extractBatch;
+    private sendBatch;
+    private sendBatchWithFetch;
+    private sendBatchWithHttps;
+    private makeRequest;
+    private scheduleFlush;
+    private generateUUID;
+    private generateTimestamp;
+    private getContext;
+    private estimateEventSize;
+    private sleep;
+}

package/dist/index.js

@@ -0,0 +1,419 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KlimeClient = void 0;
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const url = __importStar(require("url"));
+const DEFAULT_ENDPOINT = "https://i.klime.com";
+const DEFAULT_FLUSH_INTERVAL = 2000;
+const DEFAULT_MAX_BATCH_SIZE = 20;
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+const DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+const DEFAULT_RETRY_INITIAL_DELAY = 1000;
+const MAX_BATCH_SIZE = 100;
+const MAX_EVENT_SIZE_BYTES = 200 * 1024; // 200KB
+const MAX_BATCH_SIZE_BYTES = 10 * 1024 * 1024; // 10MB
+const SDK_VERSION = "1.0.1";
+// Check if fetch is available (Node 18+)
+const hasNativeFetch = typeof fetch !== "undefined";
+class KlimeClient {
+    constructor(config) {
+        this.queue = [];
+        this.flushTimer = null;
+        this.isShutdown = false;
+        this.flushPromise = null;
+        this.shutdownHandlers = [];
+        if (!config.writeKey) {
+            throw new Error("writeKey is required");
+        }
+        this.config = {
+            writeKey: config.writeKey,
+            endpoint: config.endpoint || DEFAULT_ENDPOINT,
+            flushInterval: config.flushInterval ?? DEFAULT_FLUSH_INTERVAL,
+            maxBatchSize: Math.min(config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE, MAX_BATCH_SIZE),
+            maxQueueSize: config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
+            retryMaxAttempts: config.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
+            retryInitialDelay: config.retryInitialDelay ?? DEFAULT_RETRY_INITIAL_DELAY,
+            flushOnShutdown: config.flushOnShutdown ?? true,
+        };
+        if (this.config.flushOnShutdown) {
+            const shutdownHandler = async () => {
+                await this.shutdown();
+            };
+            process.on("SIGTERM", shutdownHandler);
+            process.on("SIGINT", shutdownHandler);
+            this.shutdownHandlers.push(() => {
+                process.removeListener("SIGTERM", shutdownHandler);
+                process.removeListener("SIGINT", shutdownHandler);
+            });
+        }
+        this.scheduleFlush();
+    }
+    track(event, properties, options) {
+        if (this.isShutdown) {
+            return;
+        }
+        const eventObj = {
+            type: "track",
+            messageId: this.generateUUID(),
+            event,
+            timestamp: this.generateTimestamp(),
+            properties: properties || {},
+            context: this.getContext(options?.ip),
+        };
+        if (options?.userId) {
+            eventObj.userId = options.userId;
+        }
+        if (options?.groupId) {
+            eventObj.groupId = options.groupId;
+        }
+        this.enqueue(eventObj);
+    }
+    identify(userId, traits, options) {
+        if (this.isShutdown) {
+            return;
+        }
+        const eventObj = {
+            type: "identify",
+            messageId: this.generateUUID(),
+            userId,
+            timestamp: this.generateTimestamp(),
+            traits: traits || {},
+            context: this.getContext(options?.ip),
+        };
+        this.enqueue(eventObj);
+    }
+    group(groupId, traits, options) {
+        if (this.isShutdown) {
+            return;
+        }
+        const eventObj = {
+            type: "group",
+            messageId: this.generateUUID(),
+            groupId,
+            timestamp: this.generateTimestamp(),
+            traits: traits || {},
+            context: this.getContext(options?.ip),
+        };
+        if (options?.userId) {
+            eventObj.userId = options.userId;
+        }
+        this.enqueue(eventObj);
+    }
+    async flush() {
+        if (this.flushPromise) {
+            return this.flushPromise;
+        }
+        this.flushPromise = this.doFlush();
+        try {
+            await this.flushPromise;
+        }
+        finally {
+            this.flushPromise = null;
+        }
+    }
+    async shutdown() {
+        if (this.isShutdown) {
+            return;
+        }
+        this.isShutdown = true;
+        // Remove shutdown handlers
+        this.shutdownHandlers.forEach((handler) => handler());
+        this.shutdownHandlers = [];
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+    enqueue(event) {
+        // Check event size
+        const eventSize = this.estimateEventSize(event);
+        if (eventSize > MAX_EVENT_SIZE_BYTES) {
+            console.error(`Klime: Event size (${eventSize} bytes) exceeds ${MAX_EVENT_SIZE_BYTES} bytes limit`);
+            return;
+        }
+        // Drop oldest if queue is full
+        if (this.queue.length >= this.config.maxQueueSize) {
+            this.queue.shift();
+        }
+        this.queue.push(event);
+        // Check if we should flush immediately
+        if (this.queue.length >= this.config.maxBatchSize) {
+            this.flush();
+        }
+    }
+    async doFlush() {
+        if (this.queue.length === 0) {
+            return;
+        }
+        // Clear the flush timer
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Process batches
+        while (this.queue.length > 0) {
+            const batch = this.extractBatch();
+            if (batch.length === 0) {
+                break;
+            }
+            await this.sendBatch(batch);
+        }
+        // Schedule next flush
+        this.scheduleFlush();
+    }
+    extractBatch() {
+        const batch = [];
+        let batchSize = 0;
+        while (this.queue.length > 0 && batch.length < MAX_BATCH_SIZE) {
+            const event = this.queue[0];
+            const eventSize = this.estimateEventSize(event);
+            // Check if adding this event would exceed batch size limit
+            if (batchSize + eventSize > MAX_BATCH_SIZE_BYTES) {
+                break;
+            }
+            batch.push(this.queue.shift());
+            batchSize += eventSize;
+        }
+        return batch;
+    }
+    async sendBatch(batch) {
+        if (batch.length === 0) {
+            return;
+        }
+        const request = { batch };
+        const requestBody = JSON.stringify(request);
+        if (hasNativeFetch) {
+            await this.sendBatchWithFetch(batch, requestBody);
+        }
+        else {
+            await this.sendBatchWithHttps(batch, requestBody);
+        }
+    }
+    async sendBatchWithFetch(batch, requestBody) {
+        const requestUrl = `${this.config.endpoint}/v1/batch`;
+        let attempt = 0;
+        let delay = this.config.retryInitialDelay;
+        while (attempt < this.config.retryMaxAttempts) {
+            try {
+                const response = await fetch(requestUrl, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.config.writeKey}`,
+                    },
+                    body: requestBody,
+                });
+                const data = (await response.json());
+                if (response.ok) {
+                    if (data.failed > 0 && data.errors) {
+                        console.warn(`Klime: Batch partially failed. Accepted: ${data.accepted}, Failed: ${data.failed}`, data.errors);
+                    }
+                    return;
+                }
+                if (response.status === 400 || response.status === 401) {
+                    console.error(`Klime: Permanent error (${response.status}):`, data);
+                    return;
+                }
+                if (response.status === 429 || response.status === 503) {
+                    const retryAfter = response.headers.get("Retry-After");
+                    if (retryAfter) {
+                        delay = parseInt(retryAfter, 10) * 1000;
+                    }
+                    attempt++;
+                    if (attempt < this.config.retryMaxAttempts) {
+                        await this.sleep(delay);
+                        delay = Math.min(delay * 2, 16000);
+                        continue;
+                    }
+                }
+                attempt++;
+                if (attempt < this.config.retryMaxAttempts) {
+                    await this.sleep(delay);
+                    delay = Math.min(delay * 2, 16000);
+                }
+            }
+            catch (error) {
+                attempt++;
+                if (attempt < this.config.retryMaxAttempts) {
+                    await this.sleep(delay);
+                    delay = Math.min(delay * 2, 16000);
+                }
+                else {
+                    console.error("Klime: Failed to send batch after retries:", error);
+                }
+            }
+        }
+    }
+    async sendBatchWithHttps(batch, requestBody) {
+        const parsedUrl = url.parse(this.config.endpoint);
+        const isHttps = parsedUrl.protocol === "https:";
+        const client = isHttps ? https : http;
+        const port = parsedUrl.port
+            ? parseInt(parsedUrl.port, 10)
+            : isHttps
+                ? 443
+                : 80;
+        const hostname = parsedUrl.hostname || "";
+        let attempt = 0;
+        let delay = this.config.retryInitialDelay;
+        while (attempt < this.config.retryMaxAttempts) {
+            try {
+                const result = await this.makeRequest(client, hostname, port, "/v1/batch", requestBody);
+                if (result.statusCode === 200) {
+                    const data = JSON.parse(result.body);
+                    if (data.failed > 0 && data.errors) {
+                        console.warn(`Klime: Batch partially failed. Accepted: ${data.accepted}, Failed: ${data.failed}`, data.errors);
+                    }
+                    return;
+                }
+                if (result.statusCode === 400 || result.statusCode === 401) {
+                    const data = JSON.parse(result.body);
+                    console.error(`Klime: Permanent error (${result.statusCode}):`, data);
+                    return;
+                }
+                if (result.statusCode === 429 || result.statusCode === 503) {
+                    const retryAfter = result.headers["retry-after"];
+                    if (retryAfter) {
+                        delay =
+                            parseInt(Array.isArray(retryAfter) ? retryAfter[0] : retryAfter, 10) * 1000;
+                    }
+                    attempt++;
+                    if (attempt < this.config.retryMaxAttempts) {
+                        await this.sleep(delay);
+                        delay = Math.min(delay * 2, 16000);
+                        continue;
+                    }
+                }
+                attempt++;
+                if (attempt < this.config.retryMaxAttempts) {
+                    await this.sleep(delay);
+                    delay = Math.min(delay * 2, 16000);
+                }
+            }
+            catch (error) {
+                attempt++;
+                if (attempt < this.config.retryMaxAttempts) {
+                    await this.sleep(delay);
+                    delay = Math.min(delay * 2, 16000);
+                }
+                else {
+                    console.error("Klime: Failed to send batch after retries:", error);
+                }
+            }
+        }
+    }
+    makeRequest(client, hostname, port, path, body) {
+        return new Promise((resolve, reject) => {
+            const options = {
+                hostname,
+                port,
+                path,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.config.writeKey}`,
+                    "Content-Length": Buffer.byteLength(body),
+                },
+            };
+            const req = client.request(options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk;
+                });
+                res.on("end", () => {
+                    resolve({
+                        statusCode: res.statusCode || 500,
+                        body: data,
+                        headers: res.headers,
+                    });
+                });
+            });
+            req.on("error", (error) => {
+                reject(error);
+            });
+            req.write(body);
+            req.end();
+        });
+    }
+    scheduleFlush() {
+        if (this.isShutdown || this.flushTimer) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flush();
+        }, this.config.flushInterval);
+    }
+    generateUUID() {
+        if (typeof crypto !== "undefined" && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        // Fallback for Node < 15
+        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === "x" ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+    generateTimestamp() {
+        return new Date().toISOString();
+    }
+    getContext(ip) {
+        const context = {
+            library: {
+                name: "node-sdk",
+                version: SDK_VERSION,
+            },
+        };
+        if (ip) {
+            context.ip = ip;
+        }
+        return context;
+    }
+    estimateEventSize(event) {
+        try {
+            return JSON.stringify(event).length;
+        }
+        catch {
+            return 500;
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.KlimeClient = KlimeClient;

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export interface KlimeConfig {
+    writeKey: string;
+    endpoint?: string;
+    flushInterval?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    retryMaxAttempts?: number;
+    retryInitialDelay?: number;
+    flushOnShutdown?: boolean;
+}
+export interface TrackOptions {
+    userId?: string;
+    groupId?: string;
+    ip?: string;
+}
+export interface IdentifyOptions {
+    ip?: string;
+}
+export interface GroupOptions {
+    userId?: string;
+    ip?: string;
+}
+export interface Event {
+    type: 'track' | 'identify' | 'group';
+    messageId: string;
+    event?: string;
+    userId?: string;
+    groupId?: string;
+    timestamp: string;
+    properties?: Record<string, any>;
+    traits?: Record<string, any>;
+    context?: EventContext;
+}
+export interface EventContext {
+    library?: {
+        name: string;
+        version: string;
+    };
+    ip?: string;
+}
+export interface BatchRequest {
+    batch: Event[];
+}
+export interface BatchResponse {
+    status: string;
+    accepted: number;
+    failed: number;
+    errors?: ValidationError[];
+}
+export interface ValidationError {
+    index: number;
+    message: string;
+    code: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@klime/node",
+  "version": "1.0.3",
+  "description": "Klime SDK for Node.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "klime",
+    "tracking",
+    "events",
+    "node"
+  ],
+  "author": "Klime",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/klimeapp/klime-js.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/klimeapp/klime-js/tree/main/packages/node#readme"
+}