@tensorcost/sdk 1.2.0 → 1.3.1

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