@tensorcost/sdk 0.3.0

package/dist/transport.js

@@ -0,0 +1,150 @@
+/**
+ * Fire-and-forget HTTP transport for observation events.
+ *
+ * Design:
+ *
+ * * `post(observation)` returns synchronously the moment the observation
+ *   is enqueued. The actual fetch runs on the microtask queue via
+ *   `queueMicrotask`, so the customer's hot path is never blocked on
+ *   network IO.
+ * * If the in-flight queue saturates (>= MAX_QUEUE_DEPTH), we drop the
+ *   oldest observation rather than block. Losing one observation is
+ *   strictly preferable to slowing down the customer's request loop.
+ * * A short-lived JWT is fetched once via
+ *   `POST /api/inference-proxy/sdk-token/exchange` using the long-lived
+ *   API key.
+ *   The token is cached in-memory and refreshed when within
+ *   TOKEN_REFRESH_LEEWAY_MS of expiry.
+ * * All errors during posting are swallowed when `failOpen` is true
+ *   (the default) and surfaced via console.warn. The customer's call
+ *   site never sees an exception.
+ */
+const SDK_VERSION = "tensorcost-node/0.3.0";
+const TOKEN_REFRESH_LEEWAY_MS = 60_000;
+const DEFAULT_TOKEN_LIFETIME_MS = 15 * 60_000;
+const MAX_QUEUE_DEPTH = 1024;
+const DEFAULT_TIMEOUT_MS = 2_000;
+export class ObservationTransport {
+    constructor(opts) {
+        this.pending = 0;
+        this.tokenCache = null;
+        /** In-flight token-exchange promise; coalesces concurrent refreshes. */
+        this.tokenInflight = null;
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.failOpen = opts.failOpen ?? true;
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Enqueue an observation for fire-and-forget delivery. Returns
+     * immediately (synchronously). Errors are logged via console.warn,
+     * never thrown, when failOpen is true.
+     */
+    post(observation) {
+        if (this.pending >= MAX_QUEUE_DEPTH) {
+            // Backpressure: drop *this* observation (the "oldest" semantically
+            // is whichever is in-flight; in a microtask-dispatched queue we
+            // cannot pull in-flight work back, so we drop the newest enqueue
+            // attempt — the practical effect of "drop oldest when full" once
+            // the queue stays saturated.).
+            // eslint-disable-next-line no-console
+            console.warn("tensorcost: observation queue saturated; dropping observation");
+            return;
+        }
+        this.pending += 1;
+        queueMicrotask(() => {
+            void this.deliver(observation).finally(() => {
+                this.pending -= 1;
+            });
+        });
+    }
+    async deliver(observation) {
+        try {
+            const token = await this.getToken();
+            const url = `${this.baseUrl}/api/inference-proxy/observation`;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const resp = await this.fetchImpl(url, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                        "User-Agent": SDK_VERSION,
+                    },
+                    body: JSON.stringify(observation),
+                    signal: controller.signal,
+                });
+                if (!resp.ok) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`tensorcost: observation POST failed status=${resp.status}`);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch (err) {
+            if (!this.failOpen) {
+                throw err;
+            }
+            // eslint-disable-next-line no-console
+            console.warn(`tensorcost: observation delivery failed: ${err.message}`);
+        }
+    }
+    async getToken() {
+        const now = Date.now();
+        if (this.tokenCache &&
+            now < this.tokenCache.expiresAt - TOKEN_REFRESH_LEEWAY_MS) {
+            return this.tokenCache.token;
+        }
+        if (this.tokenInflight) {
+            return this.tokenInflight;
+        }
+        this.tokenInflight = this.exchangeToken().finally(() => {
+            this.tokenInflight = null;
+        });
+        return this.tokenInflight;
+    }
+    async exchangeToken() {
+        const url = `${this.baseUrl}/api/inference-proxy/sdk-token/exchange`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await this.fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "User-Agent": SDK_VERSION,
+                },
+                body: JSON.stringify({ api_key: this.apiKey }),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new Error(`token-exchange failed status=${resp.status}`);
+            }
+            const body = (await resp.json());
+            const token = body.token ?? body.access_token;
+            if (!token) {
+                throw new Error("token-exchange response missing token field");
+            }
+            const lifetimeMs = typeof body.expires_in === "number"
+                ? body.expires_in * 1000
+                : DEFAULT_TOKEN_LIFETIME_MS;
+            this.tokenCache = {
+                token,
+                expiresAt: Date.now() + lifetimeMs,
+            };
+            return token;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export const __test__ = {
+    SDK_VERSION,
+    MAX_QUEUE_DEPTH,
+};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Internal type defs for the TensorCost Node SDK.
+ *
+ * Kept intentionally narrow — the wrap() entry-point is generic over
+ * the customer's client type, so most provider shapes are duck-typed
+ * at runtime rather than expressed in TypeScript.
+ */
+export type Provider = "openai" | "anthropic";
+export type Operation = "chat.completions" | "completions" | "messages";
+export type ObservationStatus = "success" | "error";
+/**
+ * Wire shape posted to `POST /api/proxy/observation`. Mirrors the
+ * Python SDK's `Observation` model byte-for-byte so the two SDKs
+ * are interchangeable from the backend's point of view.
+ */
+export interface Observation {
+    sdk_version: string;
+    provider: Provider;
+    model: string;
+    operation: Operation;
+    request_at: string;
+    response_at: string;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    cost_usd_cents: number | null;
+    status: ObservationStatus;
+    error_message: string | null;
+    correlation_id: string;
+    tenant_id?: string | null;
+    /**
+     * Phase A4 batch 3 — per-environment data scoping. Optional. Stamped
+     * onto every observation envelope when the SDK was constructed with
+     * `wrap(client, { environment: 'staging' })`. Forwarded verbatim by
+     * the inference-proxy ObservationService onto the Kafka envelope;
+     * ai-service falls back to 'production' on omit.
+     */
+    environment?: string;
+    /**
+     * Phase A4 batch 4 — provider-connection identifier. Optional.
+     * Stamped onto every observation envelope when the SDK was
+     * constructed with `wrap(client, { connectionId: '...' })`.
+     * Forwarded verbatim by the inference-proxy onto the Kafka
+     * envelope; ai-service uses it as the second tier of its
+     * env-resolution chain (see ProxyObservationConsumer) when the SDK
+     * did not set `environment`.
+     */
+    connection_id?: string;
+}
+export interface WrapOptions {
+    /** Long-lived TensorCost API key. Falls back to `TENSORCOST_API_KEY`. */
+    apiKey?: string;
+    /** Backend base URL. Falls back to `TENSORCOST_BASE_URL`, then default. */
+    baseUrl?: string;
+    /** Optional explicit tenant id, useful for multi-tenant test harnesses. */
+    tenantId?: string;
+    /**
+     * Phase A4 batch 3 — environment tag. When present, the SDK reads
+     * the value once at `wrap()` time and stamps every outbound
+     * observation envelope with it. Falls back to
+     * `TENSORCOST_ENVIRONMENT`. When omitted entirely the field is
+     * absent from the envelope; the backend then falls back to the
+     * column default ('production'). Free-text per
+     * project_environment_scoping.md (1..64 chars).
+     */
+    environment?: string;
+    /**
+     * Phase A4 batch 4 — provider-connection identifier. When present,
+     * the SDK stamps it on every outbound observation envelope. Falls
+     * back to `TENSORCOST_CONNECTION_ID`. When the SDK is wrapping a
+     * client that talks to ONE provider connection, set this so the
+     * backend can resolve the connection's `environment` even if the
+     * SDK was not given an explicit `environment`.
+     *
+     * Precedence (most-specific wins):
+     *   1. SDK envelope `environment` (when set on the SDK or env var).
+     *   2. SDK envelope `connectionId` → backend looks up
+     *      `integration.cloud_account.environment` (60s LRU cache).
+     *   3. Backend column default `'production'`.
+     *
+     * Customers using ONE SDK instance across multiple connections
+     * should leave this unset and rely on `environment` per-init, OR
+     * construct a separate `wrap(...)` per connection.
+     */
+    connectionId?: string;
+    /**
+     * When true (the default), any internal observation-pipeline error is
+     * caught and logged via console.warn — the customer's call ALWAYS
+     * returns normally. Set to false only in SDK tests / CI smoke runs.
+     */
+    failOpen?: boolean;
+    /**
+     * Layer 2 applied mode. When true, the SDK routes every inference
+     * request through the TensorCost inference-proxy rather than sending
+     * it directly to the upstream AI provider. The proxy decides
+     * per-request whether to actually re-route or pass through unchanged.
+     *
+     * Defaults to false. Observe-only telemetry continues to fire
+     * regardless of this setting.
+     *
+     * Requires `proxyUrl` (or `TENSORCOST_PROXY_URL` env var) to be set;
+     * throws `TensorCostConfigError` at `wrap()` time if neither is present.
+     *
+     * Not yet supported for AWS Bedrock clients — `wrap()` will throw
+     * immediately if you enable applied mode with a Bedrock client.
+     */
+    appliedMode?: boolean;
+    /**
+     * TensorCost inference-proxy base URL used in applied mode.
+     * Falls back to `TENSORCOST_PROXY_URL`. When `appliedMode=true` and
+     * neither is set, `wrap()` throws `TensorCostConfigError`.
+     *
+     * Example: `https://proxy.tensorcost.com`
+     */
+    proxyUrl?: string;
+}
+export interface ResolvedConfig {
+    apiKey: string;
+    baseUrl: string;
+    tenantId: string | null;
+    /**
+     * Phase A4 batch 3 — resolved environment tag. `null` when the
+     * customer did not configure one; the SDK omits the `environment`
+     * field from the envelope in that case so the backend's default
+     * ('production') applies.
+     */
+    environment: string | null;
+    /**
+     * Phase A4 batch 4 — resolved provider-connection identifier.
+     * `null` when the customer did not configure one; the SDK omits the
+     * `connection_id` field from the envelope in that case.
+     */
+    connectionId: string | null;
+    failOpen: boolean;
+    /** Resolved applied-mode flag. */
+    appliedMode: boolean;
+    /**
+     * Resolved proxy base URL. Non-null only when `appliedMode=true`.
+     * Guaranteed by config resolution — `wrap()` throws before returning
+     * a config with `appliedMode=true` and `proxyUrl=null`.
+     */
+    proxyUrl: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG,kBAAkB,GAAG,aAAa,GAAG,UAAU,CAAC;AAExE,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Internal type defs for the TensorCost Node SDK.
+ *
+ * Kept intentionally narrow — the wrap() entry-point is generic over
+ * the customer's client type, so most provider shapes are duck-typed
+ * at runtime rather than expressed in TypeScript.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/wrap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The single public entry point: `wrap(client, options?)`.
+ *
+ * Returns the SAME client reference (mutates in place), per the SDK
+ * ergonomics non-negotiable: customer changes one line, no other code
+ * paths shift.
+ *
+ * Applied mode (Layer 2): when `options.appliedMode=true`, the client's
+ * baseURL is permanently redirected to the TensorCost inference-proxy and
+ * two custom headers (`x-tc-provider-url`, `x-tc-provider-auth`) are
+ * injected into `client.defaultHeaders`. The proxy handles per-request
+ * routing decisions. Observe-only telemetry still fires post-call.
+ */
+import type { WrapOptions } from "./types.js";
+export declare function wrap<T>(client: T, options?: WrapOptions): T;
+//# sourceMappingURL=wrap.d.ts.map

package/dist/wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../src/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAE,WAAgB,GAAG,CAAC,CAyC/D"}

package/dist/wrap.js

@@ -0,0 +1,48 @@
+/**
+ * The single public entry point: `wrap(client, options?)`.
+ *
+ * Returns the SAME client reference (mutates in place), per the SDK
+ * ergonomics non-negotiable: customer changes one line, no other code
+ * paths shift.
+ *
+ * Applied mode (Layer 2): when `options.appliedMode=true`, the client's
+ * baseURL is permanently redirected to the TensorCost inference-proxy and
+ * two custom headers (`x-tc-provider-url`, `x-tc-provider-auth`) are
+ * injected into `client.defaultHeaders`. The proxy handles per-request
+ * routing decisions. Observe-only telemetry still fires post-call.
+ */
+import { resolveConfig } from "./config.js";
+import { ObservationTransport } from "./transport.js";
+import { detectProvider } from "./providers/detect.js";
+import { installAppliedMode } from "./applied.js";
+import * as openaiProvider from "./providers/openai.js";
+import * as anthropicProvider from "./providers/anthropic.js";
+export function wrap(client, options = {}) {
+    // resolveConfig throws MissingConfigError when apiKey is absent, and
+    // TensorCostConfigError when appliedMode=true with no proxyUrl.
+    // Both are intentional non-fail-open cases — see config.ts header.
+    const config = resolveConfig(options);
+    const transport = new ObservationTransport({
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+        failOpen: config.failOpen,
+    });
+    const provider = detectProvider(client);
+    // Applied mode: redirect the client to the proxy before installing
+    // the observe-only wrappers. Order matters — installAppliedMode mutates
+    // baseURL and defaultHeaders, and the provider wrappers capture the
+    // (now-modified) bound methods, so post-call observations correctly
+    // attribute the response to the original provider model even though
+    // the network call went through the proxy.
+    if (config.appliedMode && config.proxyUrl !== null) {
+        installAppliedMode(client, config.proxyUrl, provider);
+    }
+    if (provider === "openai") {
+        openaiProvider.install(client, transport, config.tenantId, config.environment, config.connectionId);
+    }
+    else {
+        anthropicProvider.install(client, transport, config.tenantId, config.environment, config.connectionId);
+    }
+    return client;
+}
+//# sourceMappingURL=wrap.js.map

package/dist/wrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.js","sourceRoot":"","sources":["../src/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,iBAAiB,MAAM,0BAA0B,CAAC;AAG9D,MAAM,UAAU,IAAI,CAAI,MAAS,EAAE,UAAuB,EAAE;IAC1D,qEAAqE;IACrE,gEAAgE;IAChE,mEAAmE;IACnE,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,oBAAoB,CAAC;QACzC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAExC,mEAAmE;IACnE,wEAAwE;IACxE,oEAAoE;IACpE,oEAAoE;IACpE,oEAAoE;IACpE,2CAA2C;IAC3C,IAAI,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QACnD,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,cAAc,CAAC,OAAO,CACpB,MAAM,EACN,SAAS,EACT,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,YAAY,CACpB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,iBAAiB,CAAC,OAAO,CACvB,MAAM,EACN,SAAS,EACT,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,YAAY,CACpB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tensorcost/sdk",
+  "version": "0.3.0",
+  "description": "One-line wrapper SDK for TensorCost — fire-and-forget LLM observability for OpenAI and Anthropic clients.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "llm",
+    "openai",
+    "anthropic",
+    "observability",
+    "cost",
+    "tensorcost"
+  ],
+  "author": "Vaadh Labs / TensorCost <engineering@tensorcost.com>",
+  "homepage": "https://tensorcost.com",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "lint": "echo 'no lint configured'"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}