@klime/browser 1.0.3

package/README.md

@@ -0,0 +1,166 @@
+# @klime/browser
+
+Klime SDK for browsers.
+
+## Installation
+
+```bash
+npm install @klime/browser
+```
+
+## Quick Start
+
+```javascript
+import { KlimeClient } from "@klime/browser";
+
+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" });
+```
+
+## 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)
+  autoFlushOnUnload?: boolean;   // Optional: Auto-flush on page unload (default: true)
+})
+```
+
+### Methods
+
+#### `track(event: string, properties?: object, options?: { userId?, groupId? })`
+
+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" }
+);
+```
+
+> **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)`
+
+Identify a user with traits.
+
+```javascript
+client.identify("user_123", {
+  email: "user@example.com",
+  name: "Stefan",
+});
+```
+
+#### `group(groupId: string, traits?: object, options?: { userId? })`
+
+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
+- **Browser Context**: Automatically captures userAgent, locale, and timezone
+- **Page Unload Handling**: Automatically flushes events when the page is about to unload
+- **Zero Dependencies**: Uses only native browser APIs
+
+## Configuration
+
+### Default Values
+
+- `flushInterval`: 2000ms
+- `maxBatchSize`: 20 events
+- `maxQueueSize`: 1000 events
+- `retryMaxAttempts`: 5 attempts
+- `retryInitialDelay`: 1000ms
+- `autoFlushOnUnload`: 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.
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,296 @@
+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";
+export class KlimeClient {
+    constructor(config) {
+        this.queue = [];
+        this.flushTimer = null;
+        this.isShutdown = false;
+        this.flushPromise = null;
+        this.unloadHandler = null;
+        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,
+            autoFlushOnUnload: config.autoFlushOnUnload ?? true,
+        };
+        if (this.config.autoFlushOnUnload && typeof window !== "undefined") {
+            this.unloadHandler = () => {
+                this.flush();
+            };
+            window.addEventListener("beforeunload", this.unloadHandler);
+        }
+        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(),
+        };
+        if (options?.userId) {
+            eventObj.userId = options.userId;
+        }
+        if (options?.groupId) {
+            eventObj.groupId = options.groupId;
+        }
+        this.enqueue(eventObj);
+    }
+    identify(userId, traits) {
+        if (this.isShutdown) {
+            return;
+        }
+        const eventObj = {
+            type: "identify",
+            messageId: this.generateUUID(),
+            userId,
+            timestamp: this.generateTimestamp(),
+            traits: traits || {},
+            context: this.getContext(),
+        };
+        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(),
+        };
+        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;
+        if (this.unloadHandler && typeof window !== "undefined") {
+            window.removeEventListener("beforeunload", this.unloadHandler);
+        }
+        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 url = `${this.config.endpoint}/v1/batch`;
+        let attempt = 0;
+        let delay = this.config.retryInitialDelay;
+        while (attempt < this.config.retryMaxAttempts) {
+            try {
+                const response = await fetch(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.config.writeKey}`,
+                    },
+                    body: JSON.stringify(request),
+                });
+                const data = await response.json();
+                if (response.ok) {
+                    // Success - check for partial failures
+                    if (data.failed > 0 && data.errors) {
+                        console.warn(`Klime: Batch partially failed. Accepted: ${data.accepted}, Failed: ${data.failed}`, data.errors);
+                    }
+                    return;
+                }
+                // Handle error responses
+                if (response.status === 400 || response.status === 401) {
+                    // Permanent errors - don't retry
+                    console.error(`Klime: Permanent error (${response.status}):`, data);
+                    return;
+                }
+                // Transient errors - retry with backoff
+                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); // Cap at 16s
+                        continue;
+                    }
+                }
+                // Other errors - retry
+                attempt++;
+                if (attempt < this.config.retryMaxAttempts) {
+                    await this.sleep(delay);
+                    delay = Math.min(delay * 2, 16000);
+                }
+            }
+            catch (error) {
+                // Network errors - retry
+                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);
+                }
+            }
+        }
+    }
+    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 older browsers
+        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() {
+        const context = {
+            library: {
+                name: "js-sdk",
+                version: SDK_VERSION,
+            },
+        };
+        if (typeof navigator !== "undefined") {
+            if (navigator.userAgent) {
+                context.userAgent = navigator.userAgent;
+            }
+            if (navigator.language) {
+                context.locale = navigator.language;
+            }
+        }
+        if (typeof Intl !== "undefined" && Intl.DateTimeFormat) {
+            try {
+                const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+                if (timezone) {
+                    context.timezone = timezone;
+                }
+            }
+            catch (e) {
+                // Ignore timezone errors
+            }
+        }
+        return context;
+    }
+    estimateEventSize(event) {
+        // Rough estimate: JSON stringified size
+        try {
+            return JSON.stringify(event).length;
+        }
+        catch {
+            // Fallback: rough estimate based on structure
+            return 500; // Conservative estimate
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export interface KlimeConfig {
+    writeKey: string;
+    endpoint?: string;
+    flushInterval?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    retryMaxAttempts?: number;
+    retryInitialDelay?: number;
+    autoFlushOnUnload?: boolean;
+}
+export interface TrackOptions {
+    userId?: string;
+    groupId?: 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;
+    };
+    userAgent?: string;
+    locale?: string;
+    timezone?: 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 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@klime/browser",
+  "version": "1.0.3",
+  "description": "Klime SDK for browsers",
+  "main": "dist/index.js",
+  "module": "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",
+    "browser"
+  ],
+  "author": "Klime",
+  "license": "MIT",
+  "devDependencies": {
+    "jsdom": "^25.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/klimeapp/klime-js.git",
+    "directory": "packages/browser"
+  },
+  "homepage": "https://github.com/klimeapp/klime-js/tree/main/packages/browser#readme"
+}