@sketchlog/client 1.2.3

package/README.md

@@ -0,0 +1,35 @@
+# `@sketchlog/client`
+
+TypeScript HTTP client for SketchLog.
+
+```bash
+npm install @sketchlog/client
+```
+
+```typescript
+import { SketchLogClient } from "@sketchlog/client";
+
+const client = new SketchLogClient({
+  endpoint: "https://metrics.example",
+  authTokenProvider: async () => obtainRotatedToken(),
+  timeoutMs: 5000,
+  maxRetries: 3,
+});
+
+await client.ingestEvents("api", {
+  latencies: [42.5],
+  events: { request: 1 },
+});
+
+await client.close();
+```
+
+Static credentials can be supplied with `authToken`. Authentication is sent in
+`X-SketchLog-Auth-Token`, never in the URL.
+
+GET, PUT, and DELETE requests retry transport failures, HTTP 429, and 5xx
+responses with bounded exponential backoff and jitter. Ingestion POSTs are not
+retried automatically because replay could double-count events.
+
+See the [SDK documentation](https://sbalavignesh123.github.io/sketchlog/sdks/)
+for configuration and conformance details.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export declare class SketchLogError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export interface ClientOptions {
+    endpoint: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+    authToken?: string;
+    authTokenProvider?: () => string | Promise<string>;
+}
+export interface EventBatch {
+    latencies?: number[];
+    uniques?: string[];
+    events?: Record<string, number>;
+}
+export declare class SketchLogClient {
+    private static readonly MAX_RESPONSE_BYTES;
+    private endpoint;
+    private maxRetries;
+    private timeoutMs;
+    private agent;
+    private authToken?;
+    private authTokenProvider?;
+    constructor(options: ClientOptions);
+    private readResponse;
+    private request;
+    private delay;
+    health(): Promise<any>;
+    ingestEvents(streamId: string, batch: EventBatch, signal?: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SketchLogClient = exports.SketchLogError = void 0;
+const undici_1 = require("undici");
+class SketchLogError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'SketchLogError';
+    }
+}
+exports.SketchLogError = SketchLogError;
+class SketchLogClient {
+    static MAX_RESPONSE_BYTES = 1024 * 1024;
+    endpoint;
+    maxRetries;
+    timeoutMs;
+    agent;
+    authToken;
+    authTokenProvider;
+    constructor(options) {
+        const endpoint = new URL(options.endpoint);
+        if (!['http:', 'https:'].includes(endpoint.protocol)
+            || endpoint.username || endpoint.password
+            || (endpoint.pathname !== '' && endpoint.pathname !== '/')
+            || endpoint.search || endpoint.hash) {
+            throw new TypeError('endpoint must be an HTTP(S) origin without credentials or a path');
+        }
+        if (options.maxRetries !== undefined
+            && (!Number.isInteger(options.maxRetries)
+                || options.maxRetries < 0 || options.maxRetries > 10)) {
+            throw new TypeError('maxRetries must be an integer in [0, 10]');
+        }
+        if (options.timeoutMs !== undefined
+            && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+            throw new TypeError('timeoutMs must be a positive finite number');
+        }
+        this.endpoint = endpoint.origin;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.timeoutMs = options.timeoutMs ?? 5000;
+        this.authToken = options.authToken;
+        this.authTokenProvider = options.authTokenProvider;
+        // Connection pooling
+        this.agent = new undici_1.Agent({
+            keepAliveTimeout: 10000,
+            keepAliveMaxTimeout: 10000,
+        });
+    }
+    async readResponse(res) {
+        const contentLength = Number(res.headers.get('content-length'));
+        if (Number.isFinite(contentLength)
+            && contentLength > SketchLogClient.MAX_RESPONSE_BYTES) {
+            await res.body?.cancel();
+            throw new SketchLogError(502, 'Response body exceeds 1 MiB');
+        }
+        if (!res.body)
+            return '';
+        const reader = res.body.getReader();
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > SketchLogClient.MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new SketchLogError(502, 'Response body exceeds 1 MiB');
+            }
+            chunks.push(value);
+        }
+        const combined = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            combined.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return new TextDecoder().decode(combined);
+    }
+    async request(method, path, body, signal) {
+        const url = `${this.endpoint}${path}`;
+        const isIdempotent = method === 'GET' || method === 'PUT' || method === 'DELETE';
+        let attempt = 0;
+        while (true) {
+            attempt++;
+            let timeoutId;
+            try {
+                const controller = new AbortController();
+                timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+                // Combine provided signal with our timeout signal so neither is ignored
+                const activeSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+                const token = this.authTokenProvider
+                    ? await this.authTokenProvider()
+                    : this.authToken;
+                const headers = {};
+                if (body)
+                    headers['Content-Type'] = 'application/json';
+                if (token)
+                    headers['X-SketchLog-Auth-Token'] = token;
+                const res = await (0, undici_1.fetch)(url, {
+                    method,
+                    headers: Object.keys(headers).length ? headers : undefined,
+                    body: body ? JSON.stringify(body) : undefined,
+                    dispatcher: this.agent,
+                    signal: activeSignal,
+                    redirect: 'error',
+                });
+                if (res.status >= 200 && res.status < 300) {
+                    if (res.status === 204)
+                        return null;
+                    const responseText = await this.readResponse(res);
+                    try {
+                        return responseText ? JSON.parse(responseText) : null;
+                    }
+                    catch {
+                        throw new SketchLogError(502, 'Server returned invalid JSON');
+                    }
+                }
+                // Retry on 5xx or 429
+                if ((res.status >= 500 || res.status === 429) && isIdempotent && attempt <= this.maxRetries) {
+                    await this.readResponse(res); // Consume to free the pooled socket.
+                    await this.delay(attempt);
+                    continue;
+                }
+                throw new SketchLogError(res.status, await this.readResponse(res));
+            }
+            catch (err) {
+                if (err instanceof SketchLogError) {
+                    throw err;
+                }
+                if (err.name === 'AbortError') {
+                    if (signal?.aborted) {
+                        throw signal.reason || err;
+                    }
+                    throw new SketchLogError(408, 'Request Timeout');
+                }
+                if (isIdempotent && attempt <= this.maxRetries) {
+                    await this.delay(attempt);
+                    continue;
+                }
+                throw new SketchLogError(0, err.message || 'Unknown network error');
+            }
+            finally {
+                if (timeoutId !== undefined)
+                    clearTimeout(timeoutId);
+            }
+        }
+    }
+    delay(attempt) {
+        const base = 100 * Math.pow(2, attempt - 1);
+        const jitter = Math.random() * 50;
+        return new Promise(resolve => setTimeout(resolve, base + jitter));
+    }
+    async health() {
+        return this.request('GET', '/health');
+    }
+    async ingestEvents(streamId, batch, signal) {
+        await this.request('POST', `/v1/streams/${encodeURIComponent(streamId)}/events`, batch, signal);
+    }
+    async close() {
+        await this.agent.close();
+    }
+}
+exports.SketchLogClient = SketchLogClient;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sketchlog/client",
+  "version": "1.2.3",
+  "description": "TypeScript SDK for SketchLog",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.cjs"
+  },
+  "keywords": ["sketchlog", "observability", "metrics", "streaming"],
+  "author": "Bala Vignesh S",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SBALAVIGNESH123/sketchlog.git",
+    "directory": "clients/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/SBALAVIGNESH123/sketchlog/issues"
+  },
+  "homepage": "https://github.com/SBALAVIGNESH123/sketchlog/tree/main/clients/typescript",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "undici": "^6.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}