@gatectr/sdk 0.1.0

package/dist/esm/http.js

@@ -0,0 +1,160 @@
+// sdk-node/src/http.ts
+import { GateCtrApiError, GateCtrNetworkError, GateCtrTimeoutError } from "./errors.js";
+/** Status codes that warrant automatic retry */
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+/** Status codes that should never be retried */
+const NON_RETRYABLE_STATUSES = new Set([400, 401, 403, 404]);
+/**
+ * Exponential backoff with jitter.
+ * delay = min(500 * 2^attempt + jitter(0-100ms), 10_000ms)
+ */
+export function backoffMs(attempt) {
+    const base = 500 * Math.pow(2, attempt);
+    const jitter = Math.floor(Math.random() * 101);
+    return Math.min(base + jitter, 10_000);
+}
+/** Sleep for the given number of milliseconds */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Combines multiple AbortSignals into one. Safe for Node 18+.
+ * The returned signal aborts when any of the input signals abort.
+ */
+function combineSignals(signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            return controller.signal;
+        }
+        signal.addEventListener("abort", () => {
+            controller.abort(signal.reason);
+        }, { once: true });
+    }
+    return controller.signal;
+}
+/**
+ * Core HTTP request function with retry loop and timeout.
+ * Throws typed GateCtr errors — never raw fetch errors.
+ */
+export async function httpRequest(opts) {
+    const { method, url, headers, body, signal: callerSignal, timeoutMs, maxRetries } = opts;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        // Apply backoff before retry attempts (not before the first attempt)
+        if (attempt > 0) {
+            await sleep(backoffMs(attempt - 1));
+        }
+        // Create a per-attempt AbortController for timeout
+        const timeoutController = new AbortController();
+        const timeoutId = setTimeout(() => {
+            timeoutController.abort();
+        }, timeoutMs);
+        // Combine caller signal with timeout signal
+        const combinedSignal = callerSignal
+            ? combineSignals([callerSignal, timeoutController.signal])
+            : timeoutController.signal;
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: combinedSignal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            // Distinguish timeout from other network errors
+            if (timeoutController.signal.aborted && !callerSignal?.aborted) {
+                throw new GateCtrTimeoutError(timeoutMs);
+            }
+            // Caller cancelled — rethrow as-is so the caller can handle it
+            if (callerSignal?.aborted) {
+                throw err;
+            }
+            // Other network error (DNS, ECONNREFUSED, etc.)
+            lastError = new GateCtrNetworkError(`Network error: ${err instanceof Error ? err.message : String(err)}`, err);
+            // Network errors are retryable
+            if (attempt < maxRetries) {
+                continue;
+            }
+            throw lastError;
+        }
+        clearTimeout(timeoutId);
+        // 2xx — success
+        if (response.status >= 200 && response.status < 300) {
+            return {
+                status: response.status,
+                headers: response.headers,
+                body: response.body,
+                json: () => response.json(),
+            };
+        }
+        // Non-retryable client errors — throw immediately
+        if (NON_RETRYABLE_STATUSES.has(response.status)) {
+            const requestId = response.headers.get("x-gatectr-request-id") ?? undefined;
+            let code = "api_error";
+            let message = `HTTP ${String(response.status)}`;
+            try {
+                const errorBody = (await response.json());
+                if (typeof errorBody["code"] === "string")
+                    code = errorBody["code"];
+                if (typeof errorBody["message"] === "string")
+                    message = errorBody["message"];
+                if (typeof errorBody["error"] === "string")
+                    message = errorBody["error"];
+            }
+            catch {
+                // ignore parse errors
+            }
+            throw new GateCtrApiError({
+                message,
+                status: response.status,
+                code,
+                ...(requestId !== undefined ? { requestId } : {}),
+            });
+        }
+        // Retryable server errors
+        if (RETRYABLE_STATUSES.has(response.status)) {
+            const requestId = response.headers.get("x-gatectr-request-id") ?? undefined;
+            let code = "server_error";
+            let message = `HTTP ${String(response.status)}`;
+            try {
+                const errorBody = (await response.json());
+                if (typeof errorBody["code"] === "string")
+                    code = errorBody["code"];
+                if (typeof errorBody["message"] === "string")
+                    message = errorBody["message"];
+            }
+            catch {
+                // ignore parse errors
+            }
+            lastError = new GateCtrApiError({
+                message,
+                status: response.status,
+                code,
+                ...(requestId !== undefined ? { requestId } : {}),
+            });
+            if (attempt < maxRetries) {
+                continue;
+            }
+            throw lastError;
+        }
+        // Unknown status — treat as non-retryable
+        const requestId = response.headers.get("x-gatectr-request-id") ?? undefined;
+        throw new GateCtrApiError({
+            message: `Unexpected HTTP status ${String(response.status)}`,
+            status: response.status,
+            code: "unexpected_status",
+            ...(requestId !== undefined ? { requestId } : {}),
+        });
+    }
+    // Should never reach here, but TypeScript needs it
+    const fallback = lastError instanceof Error
+        ? lastError
+        : new GateCtrNetworkError("Request failed after retries");
+    throw fallback;
+}
+//# sourceMappingURL=http.js.map

package/dist/esm/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { GateCtr } from "./client.js";
+export { GateCtrError, GateCtrConfigError, GateCtrApiError, GateCtrTimeoutError, GateCtrStreamError, GateCtrNetworkError, } from "./errors.js";
+export type { GateCtrConfig, PerRequestOptions, Message, GateCtrMetadata, UsageCounts, CompleteParams, CompleteResponse, ChatParams, ChatResponse, StreamParams, StreamChunk, ModelInfo, ModelsResponse, UsageParams, UsageByProject, UsageResponse, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+// sdk-node/src/index.ts
+// Public API surface for @gatectr/sdk
+export { GateCtr } from "./client.js";
+export { GateCtrError, GateCtrConfigError, GateCtrApiError, GateCtrTimeoutError, GateCtrStreamError, GateCtrNetworkError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,sCAAsC;AAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,aAAa,CAAC"}

package/dist/esm/stream.d.ts

@@ -0,0 +1,8 @@
+import type { StreamChunk } from "./types.js";
+/**
+ * Parses a Server-Sent Events (SSE) stream from a ReadableStream body.
+ * Yields StreamChunk for each data line, stops cleanly on [DONE] sentinel.
+ * Propagates GateCtrStreamError on connection abort or parse error.
+ */
+export declare function parseSSE(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<StreamChunk>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/esm/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,wBAAuB,QAAQ,CAC7B,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,WAAW,CAAC,CAqG7B"}

package/dist/esm/stream.js

@@ -0,0 +1,97 @@
+// sdk-node/src/stream.ts
+import { GateCtrStreamError } from "./errors.js";
+/**
+ * Parses a Server-Sent Events (SSE) stream from a ReadableStream body.
+ * Yields StreamChunk for each data line, stops cleanly on [DONE] sentinel.
+ * Propagates GateCtrStreamError on connection abort or parse error.
+ */
+export async function* parseSSE(body, signal) {
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    let buffer = "";
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        while (true) {
+            // Check for cancellation before each read
+            if (signal !== undefined && signal.aborted) {
+                throw new GateCtrStreamError("Stream cancelled by caller");
+            }
+            let done;
+            let value;
+            try {
+                ({ done, value } = await reader.read());
+            }
+            catch (err) {
+                throw new GateCtrStreamError(`Stream read error: ${err instanceof Error ? err.message : String(err)}`, err);
+            }
+            if (done)
+                break;
+            if (value !== undefined) {
+                buffer += decoder.decode(value, { stream: true });
+            }
+            // Process all complete lines in the buffer
+            const lines = buffer.split("\n");
+            // Keep the last (potentially incomplete) line in the buffer
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                // Skip empty lines and comment lines
+                if (trimmed === "" || trimmed.startsWith(":"))
+                    continue;
+                // Parse data lines
+                if (trimmed.startsWith("data:")) {
+                    const data = trimmed.slice(5).trim();
+                    // [DONE] sentinel — stream is complete
+                    if (data === "[DONE]") {
+                        return;
+                    }
+                    // Parse JSON payload
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(data);
+                    }
+                    catch (err) {
+                        throw new GateCtrStreamError(`Failed to parse SSE data as JSON: ${data}`, err);
+                    }
+                    const chunk = parsed;
+                    const choices = chunk["choices"];
+                    const firstChoice = choices?.[0];
+                    const delta = firstChoice?.["delta"];
+                    const content = delta?.["content"];
+                    const finishReason = firstChoice?.["finish_reason"];
+                    yield {
+                        id: typeof chunk["id"] === "string" ? chunk["id"] : "",
+                        delta: typeof content === "string" ? content : null,
+                        finishReason: typeof finishReason === "string" ? finishReason : null,
+                    };
+                }
+            }
+        }
+        // Flush any remaining buffer content
+        if (buffer.trim().startsWith("data:")) {
+            const data = buffer.trim().slice(5).trim();
+            if (data !== "[DONE]" && data !== "") {
+                try {
+                    const parsed = JSON.parse(data);
+                    const choices = parsed["choices"];
+                    const firstChoice = choices?.[0];
+                    const delta = firstChoice?.["delta"];
+                    const content = delta?.["content"];
+                    const finishReason = firstChoice?.["finish_reason"];
+                    yield {
+                        id: typeof parsed["id"] === "string" ? parsed["id"] : "",
+                        delta: typeof content === "string" ? content : null,
+                        finishReason: typeof finishReason === "string" ? finishReason : null,
+                    };
+                }
+                catch {
+                    // ignore incomplete final chunk
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/esm/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -0,0 +1,155 @@
+/** Client configuration passed to the GateCtr constructor */
+export interface GateCtrConfig {
+    /** Bearer token for authentication. Falls back to GATECTR_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for the GateCtr API. Default: "https://api.gatectr.com/v1" */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+    /** Maximum number of retries for transient errors. Default: 3 */
+    maxRetries?: number;
+    /** Enable Context Optimizer globally. Default: true */
+    optimize?: boolean;
+    /** Enable Model Router globally. Default: false */
+    route?: boolean;
+}
+/** Per-request GateCtr overrides passed in params.gatectr */
+export interface PerRequestOptions {
+    /** Budget ID to enforce for this request */
+    budgetId?: string;
+    /** Override client-level optimize setting for this request */
+    optimize?: boolean;
+    /** Override client-level route setting for this request */
+    route?: boolean;
+}
+/** OpenAI-compatible message shape */
+export interface Message {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** GateCtr metadata present on every response */
+export interface GateCtrMetadata {
+    /** Unique request ID from X-GateCtr-Request-Id header */
+    requestId: string;
+    /** Request latency in ms from X-GateCtr-Latency-Ms header */
+    latencyMs: number;
+    /** Whether the request exceeded the budget, from X-GateCtr-Overage header */
+    overage: boolean;
+    /** The model that actually processed the request */
+    modelUsed: string;
+    /** Number of tokens saved by the Context Optimizer */
+    tokensSaved: number;
+}
+/** Token usage counts */
+export interface UsageCounts {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/** Parameters for client.complete() */
+export interface CompleteParams {
+    model: string;
+    messages: Message[];
+    max_tokens?: number;
+    temperature?: number;
+    /** Per-request GateCtr overrides */
+    gatectr?: PerRequestOptions;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+/** Response from client.complete() */
+export interface CompleteResponse {
+    id: string;
+    object: "text_completion";
+    model: string;
+    choices: Array<{
+        text: string;
+        finish_reason: string;
+    }>;
+    usage: UsageCounts;
+    gatectr: GateCtrMetadata;
+}
+/** Parameters for client.chat() */
+export interface ChatParams {
+    model: string;
+    messages: Message[];
+    max_tokens?: number;
+    temperature?: number;
+    /** Per-request GateCtr overrides */
+    gatectr?: PerRequestOptions;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+/** Response from client.chat() */
+export interface ChatResponse {
+    id: string;
+    object: "chat.completion";
+    model: string;
+    choices: Array<{
+        message: Message;
+        finish_reason: string;
+    }>;
+    usage: UsageCounts;
+    gatectr: GateCtrMetadata;
+}
+/** Parameters for client.stream() */
+export interface StreamParams {
+    model: string;
+    messages: Message[];
+    max_tokens?: number;
+    temperature?: number;
+    /** Per-request GateCtr overrides */
+    gatectr?: PerRequestOptions;
+    /** AbortSignal to cancel the stream */
+    signal?: AbortSignal;
+}
+/** A single SSE chunk yielded by client.stream() */
+export interface StreamChunk {
+    /** Completion ID */
+    id: string;
+    /** Incremental text delta, null on final chunk */
+    delta: string | null;
+    /** Finish reason, non-null on final chunk */
+    finishReason: string | null;
+}
+/** Information about a single available model */
+export interface ModelInfo {
+    modelId: string;
+    displayName: string;
+    provider: string;
+    contextWindow: number;
+    capabilities: string[];
+}
+/** Response from client.models() */
+export interface ModelsResponse {
+    models: ModelInfo[];
+    requestId: string;
+}
+/** Optional filters for client.usage() */
+export interface UsageParams {
+    /** Start date in YYYY-MM-DD format */
+    from?: string;
+    /** End date in YYYY-MM-DD format */
+    to?: string;
+    /** Filter by project ID */
+    projectId?: string;
+}
+/** Per-project usage breakdown */
+export interface UsageByProject {
+    projectId: string | null;
+    totalTokens: number;
+    totalRequests: number;
+    totalCostUsd: number;
+}
+/** Response from client.usage() */
+export interface UsageResponse {
+    totalTokens: number;
+    totalRequests: number;
+    totalCostUsd: number;
+    savedTokens: number;
+    from: string;
+    to: string;
+    byProject: UsageByProject[];
+    budgetStatus?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@gatectr/sdk",
+  "version": "0.1.0",
+  "description": "Node.js SDK for GateCtr — One gateway. Every LLM.",
+  "license": "MIT",
+  "author": "GateCtr",
+  "homepage": "https://gatectr.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GateCtr/sdk-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GateCtr/sdk-node/issues"
+  },
+  "keywords": [
+    "llm",
+    "openai",
+    "anthropic",
+    "gateway",
+    "ai",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.32.1",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/postbuild.mjs",
+    "clean": "node scripts/clean.mjs",
+    "lint": "eslint src/ tests/",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish",
+    "prepublishOnly": "pnpm clean && pnpm build && pnpm test",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/node": "^22.0.0",
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^9.0.0",
+    "fast-check": "^3.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "msw": "^2.12.11",
+    "prettier": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "tests/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}