@tensorcost/sdk 1.2.1 → 1.3.1

package/dist/proxy-client.d.ts

@@ -1,132 +0,0 @@
-/**
- * Applied-mode proxy HTTP client.
- *
- * This is the single place that combines retries, timeouts, typed errors,
- * telemetry hooks, and the fail-open circuit breaker. The provider wrappers
- * (openai.ts, anthropic.ts) call `proxyRequest()` instead of hitting the
- * proxy directly.
- *
- * The contract:
- *   - Returns the parsed response body on success.
- *   - On all non-success outcomes, throws a subclass of TensorCostError.
- *   - Never swallows errors — the provider wrapper's fail-open logic
- *     (fall back to direct call on proxy failure) lives in the provider
- *     wrapper, not here.
- *
- * Timeout handling:
- *   - `headersTimeoutMs` (default 2s): abort if the proxy never returns
- *     response headers (TCP accepted but wedged). Fail-open to direct.
- *   - `timeoutMs` (default 60s): wall-clock budget for the full response
- *     body after headers (model time through the proxy).
- *   - Streaming through steer is refused at the provider wrapper; proxy
- *     server supports SSE but the SDK client does not consume streams yet.
- *
- * Retry logic:
- *   - Retries on 5xx + network errors + 429.
- *   - Respects Retry-After on 429.
- *   - Stops at maxAttempts.
- *   - Does not retry on 4xx (except 429).
- *
- * Circuit breaker:
- *   - Maintained on the CircuitBreaker instance passed in.
- *   - When open, throws TensorCostProxyError immediately with a clear
- *     message so the provider wrapper can activate the direct-provider
- *     fallback.
- */
-import { TensorCostError } from "./errors.js";
-import type { RetryConfig } from "./retry.js";
-import type { CircuitBreaker } from "./circuit.js";
-import type { LifecycleEventCallback } from "./telemetry.js";
-import type { Provider } from "./telemetry.js";
-import { type ControlLayer } from "./layer.js";
-export interface ProxyRequestOptions {
-    proxyUrl: string;
-    bearerToken: string;
-    providerUrl: string;
-    providerAuth: string;
-    body: Record<string, unknown>;
-    model: string;
-    provider: Provider;
-    operation: string;
-    correlationId: string;
-    environment: string | null;
-    /**
-     * Per-agent-run attribution, forwarded as `x-tc-agent-id` /
-     * `x-tc-workflow-id`. These are what let the proxy scope a spend cap to
-     * a run; without the workflow id it has no run to cap. Same values the
-     * observation envelope carries as `agent_id` / `workflow_id`.
-     */
-    agentId?: string | undefined;
-    workflowId?: string | undefined;
-    /** A-04 chargeback → `x-tc-customer`. */
-    customer?: string | undefined;
-    /** A-04 chargeback → `x-tc-feature`. */
-    feature?: string | undefined;
-    /** Routing-policy application scope → `x-tc-application`. */
-    application?: string | null | undefined;
-    /** Routing-policy tags → comma-separated `x-tc-tags`. */
-    tags?: string[] | undefined;
-    /** Compliance team scope → `x-tc-team-id`. */
-    teamId?: string | undefined;
-    retry?: RetryConfig;
-    timeoutMs?: number;
-    /** Max wait for proxy response headers before fail-open. Default 2s. */
-    headersTimeoutMs?: number;
-    onLifecycleEvent?: LifecycleEventCallback;
-    circuit: CircuitBreaker;
-    maxLayer?: ControlLayer;
-    /**
-     * When true (steer fail-open), do not retry proxy *network* errors —
-     * fail immediately so the wrapper can go direct. 429/5xx still retry.
-     * Timeouts still retry: a timeout usually means the upstream model is slow.
-     */
-    failOpenFast?: boolean;
-    /** Injected fetch implementation (for testing). Defaults to globalThis.fetch. */
-    fetchImpl?: typeof fetch;
-}
-export interface ProxyRequestResult {
-    body: unknown;
-    decisionHeader: string | null;
-}
-/**
- * Execute a single proxied request with retries, timeouts, telemetry,
- * and circuit-breaker integration.
- *
- * Throws a `TensorCostError` subclass on any failure.
- * Returns the parsed JSON body on success.
- */
-export declare function proxyRequest(opts: ProxyRequestOptions): Promise<ProxyRequestResult>;
-/**
- * Should a failed proxy attempt fall back to calling the provider
- * directly?
- *
- * The applied-mode fail-open contract exists so that TensorCost being
- * down never takes the customer's inference down with it. Every transport
- * failure — timeout, network error, 5xx, open circuit — is therefore a
- * "go around us" signal and returns true.
- *
- * A policy refusal (run budget, model governance, guardrail hard_stop) is
- * when the proxy is healthy and the refusal IS the product. Falling back
- * would issue the provider call anyway and turn enforcement into a log line.
- */
-export declare function shouldFallBackToProvider(err: unknown): boolean;
-export interface ProxyStreamResult {
-    /** Raw SSE body from the proxy — same wire shape as the upstream provider. */
-    stream: ReadableStream<Uint8Array>;
-    decisionHeader: string | null;
-}
-/** Abort SSE consumption when no chunk arrives within idleTimeoutMs. */
-export declare function wrapStreamWithIdleTimeout(body: ReadableStream<Uint8Array>, idleTimeoutMs: number): ReadableStream<Uint8Array>;
-/**
- * Steer/route a streaming request through the inference proxy.
- * Uses the short headers timeout; no JSON body read. Retries only before
- * headers arrive (5xx/429/network). Once SSE starts, the stream is returned
- * as-is for the provider wrapper to consume.
- */
-export declare function proxyRequestStream(opts: ProxyRequestOptions & {
-    idleTimeoutMs?: number;
-}): Promise<ProxyStreamResult>;
-/** Parse OpenAI-compatible SSE into an async iterable for streaming wrappers. */
-export declare function sseChunksFromStream(body: ReadableStream<Uint8Array>): AsyncIterable<Record<string, unknown>>;
-export { TensorCostError };
-//# sourceMappingURL=proxy-client.d.ts.map

package/dist/retry.d.ts

@@ -1,50 +0,0 @@
-/**
- * Retry utilities for the TensorCost applied-mode request path.
- *
- * Retries use jittered exponential backoff:
- *
- *   delay = min(maxDelayMs, baseDelayMs * 2^attempt) * (0.5 + Math.random() * 0.5)
- *
- * where `attempt` is 0-indexed. With defaults (baseDelayMs=500, maxDelayMs=30 000),
- * the sequence of *maximum* delays is:
- *   attempt 1: 500ms
- *   attempt 2: 1 000ms
- *   attempt 3: 2 000ms
- *   attempt 4: 4 000ms
- *   attempt 5: 8 000ms
- * The jitter factor halves the minimum so actual delays are 50–100% of those
- * maximums. This matches the posture used by the OpenAI Node SDK.
- *
- * Rules:
- *   - Never retry 4xx responses (except 429).
- *   - Always retry 5xx responses and network errors.
- *   - On 429: honour the `Retry-After` response header when present
- *     (overrides the backoff delay).
- *   - Non-idempotent verbs (POST without `stream:false` is still idempotent
- *     at the proxy level — the proxy is stateless) default to idempotent for
- *     all chat/completions calls.
- */
-export interface RetryConfig {
-    /** Maximum number of total attempts (1 = no retries). Default: 5. */
-    maxAttempts: number;
-    /** Base backoff interval in milliseconds. Default: 500. */
-    baseDelayMs: number;
-    /** Cap on any single backoff interval. Default: 30 000 (30s). */
-    maxDelayMs: number;
-}
-export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
-/**
- * Compute the delay before the next attempt.
- *
- * When `retryAfterMs` is provided (from a 429 Retry-After header) it
- * overrides the exponential calculation but is still capped at maxDelayMs.
- */
-export declare function computeDelay(attempt: number, // 0-indexed
-config: RetryConfig, retryAfterMs?: number): number;
-/** True for HTTP status codes the SDK should retry on. */
-export declare function isRetryableStatus(status: number): boolean;
-/** Extract Retry-After delay in milliseconds from a fetch Response. */
-export declare function retryAfterMs(resp: Response): number | undefined;
-/** Sleep for `ms` milliseconds (abortable). */
-export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
-//# sourceMappingURL=retry.d.ts.map

package/dist/runtime.d.ts

@@ -1,24 +0,0 @@
-/**
- * Process-wide shared transport + sdk-layer clients so `prewarm()` and
- * `wrap()` reuse the same JWT and published-layer cache.
- */
-import { SdkLayerClient } from "./sdk-layer.js";
-import { ObservationTransport } from "./transport.js";
-import type { ResolvedConfig, WrapOptions } from "./types.js";
-export interface TensorCostRuntime {
-    transport: ObservationTransport;
-    sdkLayer: SdkLayerClient;
-}
-export declare function sharedRuntimeKey(config: {
-    baseUrl: string;
-    apiKey: string;
-    tenantId: string | null;
-    failOpen?: boolean;
-}): string;
-export declare function getSharedRuntime(options: WrapOptions | ResolvedConfig): TensorCostRuntime;
-/** Fire-and-forget JWT + sdk-layer warmup on the shared runtime. */
-export declare function warmupSharedRuntime(config: ResolvedConfig): void;
-export declare const __test__: {
-    clearRuntimes(): void;
-};
-//# sourceMappingURL=runtime.d.ts.map

package/dist/sdk-layer.d.ts

@@ -1,38 +0,0 @@
-/**
- * Fetches the console-published control layer with a 30s cache.
- * Decays to govern when the endpoint is unreachable for SDK_LAYER_DECAY_MS.
- *
- * Refresh never blocks an agent call once a snapshot exists: expired cache
- * is served immediately (stale-while-revalidate). Cold fetch is capped at
- * SDK_LAYER_FETCH_TIMEOUT_MS so a hung TensorCost cannot stall the model call.
- */
-import type { CompiledComplianceSnapshot, ControlLayer } from "./layer.js";
-import { type DataGrant } from "./layer.js";
-export interface SdkLayerClientOptions {
-    baseUrl: string;
-    getToken: () => Promise<string>;
-    /** Optional team scope for compliance overlay (narrow-only). */
-    teamId?: string | null;
-    fetchImpl?: typeof fetch;
-}
-export declare class SdkLayerClient {
-    private readonly baseUrl;
-    private readonly getToken;
-    private readonly teamId;
-    private readonly fetchImpl;
-    private cache;
-    /** 0 until the first successful fetch — cold start must not skip decay-to-govern. */
-    private lastSuccessAt;
-    private refreshInflight;
-    constructor(opts: SdkLayerClientOptions);
-    /** Compiled compliance snapshot (cached with sdk-layer). */
-    getComplianceSnapshot(codeMaxLayer?: ControlLayer): Promise<CompiledComplianceSnapshot | null>;
-    /** effective = min(codeMaxLayer, published). */
-    effectiveLayer(codeMaxLayer: ControlLayer): Promise<ControlLayer>;
-    /** intersect(codeMaxGrants, console.data_grants). Absent codeMax = all console grants. */
-    effectiveGrants(codeMaxGrants?: readonly DataGrant[], codeMaxLayer?: ControlLayer): Promise<DataGrant[]>;
-    private fetchPublishedSnapshot;
-    private scheduleRefresh;
-    private refreshNow;
-}
-//# sourceMappingURL=sdk-layer.d.ts.map

package/dist/telemetry.d.ts

@@ -1,70 +0,0 @@
-/**
- * Telemetry hook types for the TensorCost Node SDK.
- *
- * Customers pass `onLifecycleEvent` in WrapOptions to receive typed events
- * at each stage of a request lifecycle. The default is no-op — not providing
- * the callback adds zero overhead to the hot path.
- *
- * What's included in every event:
- *   - provider, model, operation — request identity
- *   - attemptNumber             — 1-based; increments on each retry
- *   - elapsedMs                 — wall-clock time since the first attempt began
- *
- * What is never included:
- *   - prompt / completion content
- *   - request or response bodies
- *   - credentials
- *
- * The five event kinds map to the lifecycle stages:
- *
- *   before_request   fires before each attempt (including retried ones)
- *   after_response   fires when a request completes successfully
- *   on_retry         fires when a request is going to be retried, with the
- *                    reason and how long the SDK will wait before the next
- *                    attempt
- *   on_error         fires when the SDK gives up (all retries exhausted or
- *                    a non-retriable error occurred)
- *   on_fallback      fires when the circuit breaker opens and the SDK routes
- *                    to the provider directly instead of the proxy
- */
-export type Provider = "openai" | "anthropic";
-/** Common fields shared by every lifecycle event. */
-export interface TelemetryBase {
-    provider: Provider;
-    model: string;
-    operation: string;
-    attemptNumber: number;
-    /** Wall-clock milliseconds since the first attempt for this call began. */
-    elapsedMs: number;
-}
-export interface BeforeRequestEvent extends TelemetryBase {
-    kind: "before_request";
-}
-export interface AfterResponseEvent extends TelemetryBase {
-    kind: "after_response";
-    status: number;
-    /** Request ID from the X-TC-Request-ID header, when the proxy set it. */
-    requestId: string | null;
-}
-export interface OnRetryEvent extends TelemetryBase {
-    kind: "on_retry";
-    reason: "5xx" | "network_error" | "quota_429";
-    status: number | null;
-    /** How many milliseconds the SDK will wait before the next attempt. */
-    delayMs: number;
-}
-export interface OnErrorEvent extends TelemetryBase {
-    kind: "on_error";
-    errorClass: string;
-    status: number | null;
-}
-export interface OnFallbackEvent extends TelemetryBase {
-    kind: "on_fallback";
-    /** Number of consecutive proxy failures that tripped the circuit. */
-    consecutiveFailures: number;
-}
-export type LifecycleEvent = BeforeRequestEvent | AfterResponseEvent | OnRetryEvent | OnErrorEvent | OnFallbackEvent;
-export type LifecycleEventCallback = (event: LifecycleEvent) => void;
-/** Call `cb` if defined — errors in the callback are always swallowed. */
-export declare function emitEvent(cb: LifecycleEventCallback | undefined, event: LifecycleEvent): void;
-//# sourceMappingURL=telemetry.d.ts.map

package/dist/transport.d.ts

@@ -1,68 +0,0 @@
-/**
- * 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.
- */
-import type { Observation } from "./types.js";
-export interface TransportOptions {
-    baseUrl: string;
-    apiKey: string;
-    /** Required for token exchange against current inference-proxy DTO. */
-    tenantId?: string | null;
-    timeoutMs?: number;
-    failOpen?: boolean;
-    /** Optional fetch override for testing. Defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-}
-export declare class ObservationTransport {
-    private readonly baseUrl;
-    private readonly apiKey;
-    private readonly tenantId;
-    private readonly timeoutMs;
-    private readonly failOpen;
-    private readonly fetchImpl;
-    private pending;
-    private tokenCache;
-    /** In-flight token-exchange promise; coalesces concurrent refreshes. */
-    private tokenInflight;
-    constructor(opts: TransportOptions);
-    /**
-     * 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: Observation): void;
-    private deliver;
-    /** Exchange or return cached JWT for proxy/admit/sdk-layer calls. */
-    getToken(): Promise<string>;
-    /** In-flight observation POST count (microtask queue + network). */
-    get pendingCount(): number;
-    /**
-     * Wait for queued observations to finish (Lambda shutdown / test teardown).
-     * Does not throw when the deadline is hit — best-effort only.
-     */
-    flush(timeoutMs?: number): Promise<void>;
-    private fetchToken;
-    private exchangeToken;
-}
-export declare const __test__: {
-    SDK_VERSION: string;
-    MAX_QUEUE_DEPTH: number;
-};
-//# sourceMappingURL=transport.d.ts.map

package/dist/wrap-overhead.d.ts

@@ -1,32 +0,0 @@
-/**
- * Measures synchronous SDK wrap overhead in the customer process.
- *
- * All awaited I/O (layer fetch, admit, proxy, provider) must run inside
- * `withAwaitExcluded` so RTT is not counted. Sync work before/after those
- * hops — token extraction, observation enqueue — is included. The async
- * HTTP delivery inside `transport.post`'s microtask is excluded.
- */
-import type { Observation } from "./types.js";
-import type { ObservationTransport } from "./transport.js";
-export declare class WrapOverhead {
-    private readonly hookStart;
-    private accumulatedMs;
-    private activeStart;
-    /** Pause the sync clock before an awaited hop. */
-    pauseForAwait(): void;
-    /** Resume the sync clock after an awaited hop returns. */
-    resumeAfterAwait(): void;
-    /** Milliseconds of synchronous wrap work (rounded, non-negative). */
-    sdkAddedMs(): number;
-}
-/** Run awaited work with wrap clock paused — use for every external I/O hop. */
-export declare function withAwaitExcluded<T>(overhead: WrapOverhead, fn: () => Promise<T>): Promise<T>;
-/**
- * Enqueue an observation with `sdk_added_ms` stamped. Fail-open — never throws.
- * Call after building the observation (token extraction included in overhead).
- */
-export declare function postObservation(transport: ObservationTransport, overhead: WrapOverhead, obs: Observation): void;
-export declare const __test__: {
-    WrapOverhead: typeof WrapOverhead;
-};
-//# sourceMappingURL=wrap-overhead.d.ts.map

package/dist/wrap.d.ts

@@ -1,24 +0,0 @@
-/**
- * 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.
- *
- * Control layers:
- *   off     — client returned unchanged (no transport, no hooks)
- *   observe — telemetry only
- *   govern  — admit (metadata) then direct provider call
- *   steer/route — proxy in request path (OpenAI / Anthropic only)
- */
-import { TensorCostConfigError } from "./config.js";
-import { layerRank } from "./layer.js";
-import type { WrapOptions } from "./types.js";
-declare function steerRouteUnsupportedError(provider: string, maxLayer: string): TensorCostConfigError;
-export declare function wrap<T>(client: T, options?: WrapOptions): T;
-export declare const __test__: {
-    layerRank: typeof layerRank;
-    steerRouteUnsupportedError: typeof steerRouteUnsupportedError;
-};
-export {};
-//# sourceMappingURL=wrap.d.ts.map