@tangle-network/tcloud 0.2.0 → 0.3.0

package/dist/{client-CcuHG7_w.d.ts → client-DskWX_BT.d.cts}

@@ -2,6 +2,8 @@
 interface TCloudConfig {
     /** API base URL (default: https://router.tangle.tools/v1) */
     baseURL?: string;
+    /** Platform API URL for billing/keys (default: https://id.tangle.tools) */
+    platformURL?: string;
     /** API key for standard (non-private) mode */
     apiKey?: string;
     /** Default model */
@@ -260,6 +262,91 @@ interface ChatMessage {
     content: string;
     name?: string;
 }
+/** Gateway-level options for routing, compliance, and inference strategies. */
+interface GatewayOptions {
+    /** BYOK: per-request provider credentials. Zero markup. */
+    byok?: Record<string, Array<{
+        apiKey?: string;
+    }>>;
+    /** Route only through ZDR-verified providers. */
+    zeroDataRetention?: boolean;
+    /** Route only through providers that don't train on prompts. */
+    disallowPromptTraining?: boolean;
+    /** Inject cache_control markers for providers that need them. */
+    caching?: 'auto' | false;
+    /** Provider priority order. */
+    order?: string[];
+    /** Restrict to these providers only. */
+    only?: string[];
+    /** Fallback model list tried in order. */
+    models?: string[];
+    /** Per-provider or global timeout (ms, clamped 1s–120s). */
+    timeout?: number | Record<string, number>;
+    /** Smart routing hint. 'quality' auto-enables RSA. */
+    optimize?: 'cost' | 'latency' | 'quality';
+    /** Disable response cache for this request. */
+    cache?: boolean;
+    /**
+     * RSA / MoA: population-based quality amplification.
+     * Spawns N parallel calls, aggregates K at a time, refines over T rounds.
+     * Add `models` for Mixture-of-Agents (diverse models per slot).
+     */
+    rsa?: {
+        n?: number;
+        k?: number;
+        t?: number;
+        /** MoA: diverse models for generation (round-robin). Aggregation uses primary model. */
+        models?: string[];
+    };
+    /**
+     * Best-of-N: generate N candidates, score, return the winner.
+     * Scorer: webhook (your HTTP endpoint) or llm (LLM-as-judge).
+     */
+    bestOfN?: {
+        n?: number;
+        /** Diverse models for generation (round-robin). */
+        models?: string[];
+        scorer: {
+            type: 'webhook';
+            url: string;
+            timeout?: number;
+        } | {
+            type: 'llm';
+            model: string;
+            prompt: string;
+        };
+    };
+}
+/**
+ * Bridge options — route a single chat call through the Tangle Router's
+ * cli-bridge short-circuit. The bridge drives subscription-backed CLIs
+ * (Claude Code, Codex, Kimi Code, opencode) as OpenAI-compatible
+ * harnesses with persistent session resume.
+ *
+ * When `bridge` is set, the client:
+ *   1. Rewrites `model` to `bridge/<harness>/<model>` (or `bridge/<harness>`
+ *      if no model is given — uses the harness default)
+ *   2. Injects `X-Bridge-Unlock` with the caller's unlock token
+ *   3. Injects `X-Resume` so follow-up calls with the same id resume
+ *      the CLI's native session (no re-tokenizing prior turns)
+ *   4. Optionally injects BYOB headers `X-Bridge-Url` + `X-Bridge-Bearer`
+ *      if the caller wants to target their own cli-bridge instance
+ *      (requires the router to be deployed with CLI_BRIDGE_BYOB_ENABLED)
+ */
+interface BridgeOptions {
+    /** Which harness to drive. Picks the backend on the bridge. */
+    harness: 'claude' | 'claudish' | 'codex' | 'opencode' | 'kimi' | 'openai' | 'anthropic' | 'moonshot' | 'zai';
+    /** Model id inside the harness (e.g. `sonnet`, `kimi-for-coding`, `gpt-5-codex`). Omit for harness default. */
+    model?: string;
+    /** Router-issued unlock token. Required unless operator has disabled the gate. */
+    unlock: string;
+    /** Stable caller-owned id for session resume. Map one id per logical conversation. */
+    resume?: string;
+    /** BYOB: point at your own cli-bridge instance. Router must have BYOB enabled. */
+    bridgeUrl?: string;
+    /** BYOB: bearer your cli-bridge expects. */
+    bridgeBearer?: string;
+}
 interface ChatOptions {
     /** Model to use */
     model?: string;
@@ -292,12 +379,23 @@ interface ChatOptions {
             name: string;
         };
     };
+    /**
+     * Gateway options: routing, compliance, inference strategies (RSA/MoA/Best-of-N).
+     * Sent as `body.gateway` to the Router.
+     */
+    gateway?: GatewayOptions;
     /**
      * Provider-specific parameters passed through to the upstream API.
      * These are spread into the request body alongside standard fields.
      * Example: `{ thinking: { type: 'enabled', budget_tokens: 8000 } }`
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Route this call through the Tangle Router's cli-bridge short-circuit.
+     * See {@link BridgeOptions}. When set, `model` is rewritten to
+     * `bridge/<harness>/<model>` and bridge headers are injected.
+     */
+    bridge?: BridgeOptions;
 }
 interface ChatCompletion {
     id: string;
@@ -380,6 +478,51 @@ interface CreditBalance {
         createdAt: string;
     }[];
 }
+interface CreateKeyOptions {
+    name: string;
+    /** Explicit parent key ID. When omitted and calling with an API key,
+     * the new key is auto-parented to the calling key. */
+    parentKeyId?: string;
+    product?: 'router' | 'sandbox' | 'evals' | 'blueprint-agent';
+    projectId?: string;
+    budgetUsd?: number;
+    allowedModels?: string[];
+    rpmLimit?: number;
+    /** ISO 8601 datetime. Must be in the future. */
+    expiresAt?: string;
+}
+interface CreatedKey {
+    id: string;
+    key: string;
+    prefix: string;
+    name: string;
+    product: string | null;
+    budgetUsd: number | null;
+    budgetRemaining: number | null;
+}
+interface ApiKeyInfo {
+    id: string;
+    keyPrefix: string;
+    name: string;
+    parentKeyId: string | null;
+    product: string | null;
+    projectId: string | null;
+    budgetUsd: number | null;
+    budgetSpent: number;
+    allowedModels: string[] | null;
+    rpmLimit: number | null;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+interface UpdateKeyOptions {
+    name?: string;
+    budgetUsd?: number;
+    allowedModels?: string[];
+    rpmLimit?: number | null;
+    expiresAt?: string | null;
+}
 /** Status event from an async job SSE stream */
 interface JobEvent {
     status: 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
@@ -482,6 +625,7 @@ declare class PrivateRouter {
 
 declare class TCloudClient {
     readonly baseURL: string;
+    readonly platformURL: string;
     readonly apiKey?: string;
     readonly model: string;
     private headers;
@@ -545,16 +689,38 @@ declare class TCloudClient {
      */
     private _requestRaw;
     /**
-     * Prepare headers for chat requests — operator routing + SpendAuth.
+     * Prepare headers for chat requests — operator routing + SpendAuth +
+     * bridge short-circuit headers when `options.bridge` is set.
      * Shared between chat() and chatStream() to eliminate duplication.
      */
     private _prepareChatRequest;
+    /**
+     * Resolve the effective model string. When a bridge is set, rewrite to
+     * `bridge/<harness>/<model>` (or `bridge/<harness>` if no model).
+     */
+    private _effectiveModel;
     /** Build the chat completions request body */
     private _chatBody;
     /** Chat completion (non-streaming) */
     chat(options: ChatOptions): Promise<ChatCompletion>;
     /** Chat completion (streaming) — returns an async iterator of chunks */
     chatStream(options: ChatOptions): AsyncGenerator<ChatCompletionChunk>;
+    /**
+     * Bridge — scoped helper for a subscription-backed CLI harness behind
+     * the Tangle Router's cli-bridge. Returns a mini-client bound to
+     * (harness, unlock, resume) so you don't thread those through every
+     * call.
+     *
+     * ```ts
+     * const kimi = tcloud.bridge({ harness: 'kimi', model: 'kimi-for-coding', unlock: UNLOCK, resume: 'pr-42' })
+     * await kimi.ask('review this diff…')
+     * for await (const chunk of kimi.stream('continue…')) process.stdout.write(chunk)
+     * ```
+     *
+     * Sessions persist across process restarts — use the same `resume` id
+     * to land on the same CLI conversation (context intact, no replay tax).
+     */
+    bridge(cfg: BridgeOptions): BridgeSession;
     /** Convenience: send a single message and get the text response */
     ask(message: string, modelOrOptions?: string | Partial<ChatOptions>): Promise<string>;
     /** Convenience: send a single message and get the full completion (with usage) */
@@ -570,25 +736,62 @@ declare class TCloudClient {
     }>;
     /** Get credit balance */
     credits(): Promise<CreditBalance>;
-    /** Add credits */
+    /** Add credits via Stripe checkout. Returns the checkout URL. */
     addCredits(amount: number): Promise<{
-        balance: number;
+        url: string;
     }>;
-    /** Create a new API key */
-    createKey(name: string): Promise<{
-        key: string;
+    /** Get transaction history */
+    transactions(limit?: number): Promise<{
         id: string;
+        amount: number;
+        type: string;
+        product: string | null;
+        description: string | null;
+        createdAt: string;
+    }[]>;
+    /**
+     * Create a new API key.
+     * When called with an API key (not session), the new key is automatically
+     * a child of the calling key — enabling hierarchical key delegation.
+     *
+     * Pass `parentKeyId` explicitly to create a child of a specific key.
+     * Child keys inherit the parent's product scope, allowedModels, and rpmLimit
+     * if not specified. Budget cannot exceed the parent's remaining budget.
+     */
+    createKey(opts: CreateKeyOptions): Promise<CreatedKey>;
+    /** Get a single API key by ID */
+    getKey(id: string): Promise<ApiKeyInfo>;
+    /**
+     * List API keys.
+     * Pass `children: true` to list child keys of the calling API key.
+     */
+    keys(opts?: {
+        children?: boolean;
+    }): Promise<ApiKeyInfo[]>;
+    /**
+     * Update an API key's limits.
+     * Can adjust budget, allowedModels, rpmLimit, expiresAt, and name.
+     */
+    updateKey(id: string, updates: UpdateKeyOptions): Promise<ApiKeyInfo>;
+    /** Revoke an API key. If the key has children, they are also revoked recursively. */
+    revokeKey(id: string): Promise<void>;
+    /** Rotate an API key — creates new key with same config, revokes old */
+    rotateKey(id: string): Promise<{
+        newKey: CreatedKey;
+        revokedKeyId: string;
+    }>;
+    /** Create a project for usage attribution */
+    createProject(name: string, product?: string): Promise<{
+        id: string;
+        name: string;
     }>;
-    /** List API keys */
-    keys(): Promise<{
+    /** List projects */
+    projects(): Promise<{
         id: string;
         name: string;
-        prefix: string;
+        product: string | null;
         createdAt: string;
-        lastUsedAt: string | null;
     }[]>;
-    /** Revoke an API key */
-    revokeKey(id: string): Promise<void>;
     /** Generate embeddings */
     embeddings(options: EmbeddingOptions): Promise<EmbeddingResponse>;
     /** Generate images */
@@ -696,6 +899,192 @@ declare class TCloudClient {
         model?: string;
         tiers?: number;
     }): Promise<PricingTier[]>;
+    private get _apiRoot();
+    eval(opts: {
+        models: string[];
+        scenarios: Array<{
+            id: string;
+            prompt: string;
+            rubric?: string;
+            category?: string;
+            expectedContains?: string[];
+            maxLatencyMs?: number;
+        }>;
+        judge?: string;
+        iterations?: number;
+        systemPrompt?: string;
+    }): Promise<{
+        results: Array<{
+            model: string;
+            summary: any;
+            scenarios: any[];
+        }>;
+    }>;
+    createSuite(opts: {
+        name: string;
+        scenarios: Array<{
+            id: string;
+            prompt: string;
+            rubric?: string;
+        }>;
+        models: string[];
+        judge?: string;
+        iterations?: number;
+        tags?: string[];
+    }): Promise<{
+        suite: {
+            id: string;
+            name: string;
+        };
+    }>;
+    listSuites(): Promise<{
+        suites: Array<{
+            id: string;
+            name: string;
+            models: string[];
+        }>;
+    }>;
+    runSuite(suiteId: string, opts?: {
+        baseline?: boolean;
+        concurrency?: number;
+    }): Promise<any>;
+    listRuns(suiteId: string): Promise<any>;
+    getRun(runId: string): Promise<any>;
+    setBaseline(runId: string): Promise<void>;
+    sandboxPricing(opts?: {
+        cpu?: number;
+        ram?: number;
+        disk?: number;
+    }): Promise<{
+        pricing: {
+            hourlyRate: number;
+            perMinuteRate: number;
+        };
+        plan: string;
+        limits: {
+            maxCpu: number;
+            maxRamGb: number;
+            maxDiskGb: number;
+        };
+        balance: number;
+        canAfford: {
+            minutes: number;
+            hours: number;
+        };
+    }>;
+    sandboxStatus(): Promise<{
+        linked: boolean;
+        keyPrefix?: string;
+        gatewayUrl?: string;
+    }>;
+    sandboxProvision(): Promise<{
+        provisioned: boolean;
+        minutesRemaining?: number;
+    }>;
+    sandboxCreate(opts: {
+        model?: string;
+        harness?: 'claude-code' | 'codex' | 'opencode' | 'amp' | 'factory';
+        cpu?: number;
+        ram?: number;
+        storage?: number;
+        gitUrl?: string;
+        systemPrompt?: string;
+    }): Promise<{
+        sessionId: string;
+        harness: string;
+        model: string;
+        minutesRemaining?: number;
+    }>;
+    sandboxList(): Promise<{
+        sessions: Array<{
+            id: string;
+            status: string;
+            model: string;
+            harness: string;
+        }>;
+    }>;
+    sandboxStats(sandboxId: string): Promise<{
+        config: {
+            cpu: number;
+            ramGb: number;
+            diskGb: number;
+        };
+        uptime: number;
+        computeMinutes: number;
+        live?: {
+            cpuPercent: number;
+            memoryUsedMb: number;
+            memoryTotalMb: number;
+        };
+    }>;
+    sandboxDestroy(sessionId: string): Promise<{
+        deleted: boolean;
+    }>;
+    userInfo(): Promise<{
+        user: {
+            id: string;
+            email: string;
+            name?: string;
+        };
+        balance: number;
+        subscription: {
+            plan: string;
+            status: string;
+        } | null;
+        usage: Record<string, {
+            cost: number;
+            count: number;
+        }>;
+    }>;
+}
+/** Select N evenly-spaced items, always including first and last. */
+/**
+ * BridgeSession — a chat client scoped to one bridge configuration.
+ *
+ * Instead of threading `{ harness, unlock, resume }` through every
+ * `chat()` call, create a session once and call `ask` / `stream` / `chat`
+ * on it. The session's `resume` id is stable across calls so follow-up
+ * turns land on the same CLI conversation.
+ *
+ * ```ts
+ * const tcloud = new TCloudClient({ apiKey, baseURL: 'https://router.tangle.tools/api' })
+ * const kimi = tcloud.bridge({ harness: 'kimi', model: 'kimi-for-coding', unlock: UNLOCK, resume: 'pr-42' })
+ *
+ * // one-shot
+ * const reply = await kimi.ask('summarize this diff')
+ *
+ * // streaming
+ * for await (const chunk of kimi.stream('continue…')) process.stdout.write(chunk)
+ *
+ * // full OpenAI-shaped request
+ * const completion = await kimi.chat({ messages, temperature: 0.2 })
+ *
+ * // new resume id for a different logical conversation
+ * const kimiOther = kimi.withResume('ticket-123')
+ * ```
+ */
+declare class BridgeSession {
+    private readonly client;
+    private readonly cfg;
+    constructor(client: TCloudClient, cfg: BridgeOptions);
+    /** Full chat completion (non-streaming). */
+    chat(options: Omit<ChatOptions, 'bridge'>): Promise<ChatCompletion>;
+    /** Stream OpenAI chat.completion.chunks. */
+    chatStream(options: Omit<ChatOptions, 'bridge'>): AsyncGenerator<ChatCompletionChunk>;
+    /** One-shot: send a string, get the assistant text. */
+    ask(message: string, extra?: Omit<Partial<ChatOptions>, 'bridge' | 'messages'>): Promise<string>;
+    /** One-shot: send a string, stream text deltas. */
+    stream(message: string, extra?: Omit<Partial<ChatOptions>, 'bridge' | 'messages'>): AsyncGenerator<string>;
+    /** Turn-based: send full message history, get assistant text. */
+    turn(messages: ChatMessage[], extra?: Omit<Partial<ChatOptions>, 'bridge' | 'messages'>): Promise<string>;
+    /** Clone with a new resume id — same harness, different logical conversation. */
+    withResume(resume: string): BridgeSession;
+    /** Clone with a different model inside the same harness. */
+    withModel(model: string): BridgeSession;
+    /** The effective model id that will land on the router (`bridge/<harness>/<model>`). */
+    get model(): string;
+    /** The resume id currently bound to this session, if any. */
+    get resume(): string | undefined;
 }
 interface TierConfig {
     name: string;
@@ -725,4 +1114,4 @@ declare class TCloudError extends Error {
     constructor(status: number, message: string);
 }
 
-export { type AvatarGenerateRequest as A, type BatchJobResponse as B, type ChatCompletion as C, type TranscriptionResponse as D, type EmbeddingOptions as E, type FineTuningJob as F, type VideoResponse as G, type ImageGenerateOptions as I, type JobEvent as J, type Model as M, type Operator as O, type PricingTier as P, type RerankOptions as R, type ShieldedConfig as S, TCloudClient as T, type VideoGenerateOptions as V, type WatchJobOptions as W, type TCloudConfig as a, type AvatarGenerateResponse as b, type AvatarJobStatus as c, type AvatarResult as d, type BatchRequest as e, type ChatCompletionChunk as f, type ChatMessage as g, type ChatOptions as h, type CompletionOptions as i, type CompletionResponse as j, type CreditBalance as k, type EmbeddingResponse as l, type FineTuningJobOptions as m, type ImageResponse as n, type OperatorInfo as o, type PrivacyConfig as p, PrivateRouter as q, type PrivateRouterConfig as r, type RerankResponse as s, type RetryConfig as t, type RoutingConfig as u, type RoutingStrategy as v, type SpendAuth as w, type SpendingLimits as x, TCloudError as y, type TierConfig as z };
+export { type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RoutingStrategy as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type SpendAuth as H, type ImageGenerateOptions as I, type JobEvent as J, type SpendingLimits as K, TCloudError as L, type Model as M, type TierConfig as N, type Operator as O, type PricingTier as P, type TranscriptionResponse as Q, type RerankOptions as R, type ShieldedConfig as S, TCloudClient as T, type UpdateKeyOptions as U, type VideoGenerateOptions as V, type VideoResponse as W, type WatchJobOptions as X, type TCloudConfig as a, type AvatarGenerateRequest as b, type AvatarGenerateResponse as c, type AvatarJobStatus as d, type AvatarResult as e, type BatchRequest as f, type BridgeOptions as g, BridgeSession as h, type ChatCompletionChunk as i, type ChatMessage as j, type ChatOptions as k, type CompletionOptions as l, type CompletionResponse as m, type CreateKeyOptions as n, type CreatedKey as o, type CreditBalance as p, type EmbeddingResponse as q, type FineTuningJobOptions as r, type ImageResponse as s, type OperatorInfo as t, type PrivacyConfig as u, PrivateRouter as v, type PrivateRouterConfig as w, type RerankResponse as x, type RetryConfig as y, type RoutingConfig as z };