@tangle-network/tcloud 0.1.0

package/dist/shielded-BRhsV-s-.d.ts

@@ -0,0 +1,343 @@
+import { Hex } from 'viem';
+
+/** Core types for the tcloud SDK */
+interface TCloudConfig {
+    /** API base URL (default: https://api.tangleai.cloud/v1) */
+    baseURL?: string;
+    /** API key for standard (non-private) mode */
+    apiKey?: string;
+    /** Default model */
+    model?: string;
+    /** Operator routing preferences */
+    routing?: RoutingConfig;
+    /** Enable shielded (private) mode */
+    shielded?: ShieldedConfig | boolean;
+    /** Privacy proxy configuration for IP hiding */
+    privacy?: PrivacyConfig;
+    /** Spending limits and metering */
+    limits?: SpendingLimits;
+}
+interface SpendingLimits {
+    /** Max USD to spend per request. Rejects if estimated cost exceeds this. */
+    maxCostPerRequest?: number;
+    /** Max USD to spend across all requests in this client's lifetime. Stops at limit. */
+    maxTotalSpend?: number;
+    /** Max requests allowed. Stops at limit. */
+    maxRequests?: number;
+    /** Callback when a limit is approached (80% threshold) */
+    onLimitWarning?: (info: {
+        type: 'cost' | 'total' | 'requests';
+        current: number;
+        limit: number;
+    }) => void;
+    /** Callback when a limit is hit (request blocked) */
+    onLimitReached?: (info: {
+        type: 'cost' | 'total' | 'requests';
+        current: number;
+        limit: number;
+    }) => void;
+}
+interface RoutingConfig {
+    /** Preferred operator slug */
+    prefer?: string;
+    /** Routing strategy */
+    strategy?: 'lowest-latency' | 'lowest-price' | 'highest-reputation' | 'round-robin';
+    /** Region filter */
+    region?: string;
+    /** Fallback operator slugs (tried in order) */
+    fallback?: string[];
+}
+interface PrivacyConfig {
+    /** 'direct' — no proxy (default). 'relayer' — route through tcloud-relayer. 'socks5' — route through SOCKS5 proxy (e.g. Tor). */
+    mode: 'direct' | 'relayer' | 'socks5';
+    /** Relayer URL for 'relayer' mode (e.g. 'http://localhost:3030') */
+    relayerUrl?: string;
+    /**
+     * SOCKS5 proxy URL for 'socks5' mode (e.g. 'socks5://127.0.0.1:9050' for Tor).
+     * Requires `socks-proxy-agent` as an optional peer dependency.
+     */
+    socksProxy?: string;
+}
+interface ShieldedConfig {
+    /** Pre-existing spending private key (hex). If not set, generates ephemeral. */
+    spendingKey?: string;
+    /** Pre-existing commitment. If not set, derives from key. */
+    commitment?: string;
+    /** Chain ID (default: 3799 for Tangle testnet) */
+    chainId?: number;
+    /** ShieldedCredits contract address */
+    creditsAddress?: string;
+    /** Service ID for the blueprint */
+    serviceId?: bigint;
+    /** Privacy proxy configuration for IP hiding */
+    privacy?: PrivacyConfig;
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    name?: string;
+}
+interface ChatOptions {
+    /** Model to use */
+    model?: string;
+    /** Messages */
+    messages: ChatMessage[];
+    /** Temperature (0-2) */
+    temperature?: number;
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Stream response */
+    stream?: boolean;
+    /** Stop sequences */
+    stop?: string | string[];
+    /** Top-p sampling */
+    topP?: number;
+    /** Frequency penalty */
+    frequencyPenalty?: number;
+    /** Presence penalty */
+    presencePenalty?: number;
+    /** JSON mode */
+    responseFormat?: {
+        type: 'text' | 'json_object';
+    };
+    /** Tools / function calling */
+    tools?: any[];
+}
+interface ChatCompletion {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        message: ChatMessage;
+        finish_reason: string;
+    }[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        delta: Partial<ChatMessage>;
+        finish_reason: string | null;
+    }[];
+}
+interface Model {
+    id: string;
+    name: string;
+    description?: string;
+    context_length: number;
+    pricing: {
+        prompt: string;
+        completion: string;
+    };
+    _provider?: string;
+    architecture?: {
+        input_modalities?: string[];
+        output_modalities?: string[];
+    };
+}
+interface Operator {
+    id: string;
+    slug: string;
+    name: string;
+    description?: string;
+    status: string;
+    endpointUrl: string;
+    blueprintType: string;
+    reputationScore: number;
+    uptimePercent: number;
+    avgLatencyMs: number;
+    totalRequests: number;
+    stakeTnt: number;
+    models: {
+        modelId: string;
+        inputPrice: number;
+        outputPrice: number;
+    }[];
+}
+interface CreditBalance {
+    balance: number;
+    transactions: {
+        id: string;
+        amount: number;
+        type: string;
+        description: string;
+        createdAt: string;
+    }[];
+}
+interface SpendAuth {
+    commitment: string;
+    serviceId: string;
+    jobIndex: number;
+    amount: string;
+    operator: string;
+    nonce: string;
+    expiry: string;
+    signature: string;
+}
+
+/**
+ * Core HTTP client for Tangle AI Cloud.
+ * Shared between CLI and SDK.
+ */
+
+declare class TCloudClient {
+    readonly baseURL: string;
+    readonly apiKey?: string;
+    readonly model: string;
+    private headers;
+    private spendAuthFn?;
+    private privacy?;
+    private limits?;
+    private _totalSpent;
+    private _requestCount;
+    constructor(config?: TCloudConfig);
+    /** Set the SpendAuth signer for private mode */
+    setSpendAuthSigner(fn: () => Promise<SpendAuth>): void;
+    /** Current metering stats */
+    get usage(): {
+        totalSpent: number;
+        requestCount: number;
+        limits: {
+            maxCostPerRequest?: number;
+            maxTotalSpend?: number;
+            maxRequests?: number;
+            onLimitWarning?: (info: {
+                type: "cost" | "total" | "requests";
+                current: number;
+                limit: number;
+            }) => void;
+            onLimitReached?: (info: {
+                type: "cost" | "total" | "requests";
+                current: number;
+                limit: number;
+            }) => void;
+        } | undefined;
+    };
+    /** Check spending limits before a request. Throws TCloudError if blocked. */
+    private checkLimits;
+    /** Track cost after a response */
+    private trackCost;
+    /** Chat completion (non-streaming) */
+    chat(options: ChatOptions): Promise<ChatCompletion>;
+    /** Chat completion (streaming) — returns an async iterator of chunks */
+    chatStream(options: ChatOptions): AsyncGenerator<ChatCompletionChunk>;
+    /** 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) */
+    askFull(message: string, modelOrOptions?: string | Partial<ChatOptions>): Promise<ChatCompletion>;
+    /** Convenience: stream a single message and yield text chunks */
+    askStream(message: string, modelOrOptions?: string | Partial<ChatOptions>): AsyncGenerator<string>;
+    /** List available models */
+    models(): Promise<Model[]>;
+    /** List active operators */
+    operators(): Promise<{
+        operators: Operator[];
+        stats: any;
+    }>;
+    /** Get credit balance */
+    credits(): Promise<CreditBalance>;
+    /** Add credits */
+    addCredits(amount: number): Promise<{
+        balance: number;
+    }>;
+    /** Create a new API key */
+    createKey(name: string): Promise<{
+        key: string;
+        id: string;
+    }>;
+    /** List API keys */
+    keys(): Promise<{
+        id: string;
+        name: string;
+        prefix: string;
+        createdAt: string;
+        lastUsedAt: string | null;
+    }[]>;
+    /** Revoke an API key */
+    revokeKey(id: string): Promise<void>;
+    /** Search models by name, provider, or capability */
+    searchModels(query: string): Promise<Model[]>;
+    /** Estimate cost for a request (without sending it) */
+    estimateCost(options: {
+        model?: string;
+        inputTokens: number;
+        outputTokens: number;
+    }): Promise<{
+        inputCost: number;
+        outputCost: number;
+        total: number;
+    }>;
+}
+declare class TCloudError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+
+/**
+ * tcloud/shielded — Ephemeral wallet generation, SpendAuth signing, private inference.
+ *
+ * import { TCloud } from 'tcloud'
+ * const client = TCloud.shielded()  // anonymous, no API key
+ */
+
+interface ShieldedWallet {
+    /** Ephemeral spending private key (hex) */
+    privateKey: Hex;
+    /** Derived address */
+    address: string;
+    /** Credit account commitment */
+    commitment: Hex;
+    /** Random salt */
+    salt: Hex;
+}
+/** Generate a new ephemeral shielded wallet */
+declare function generateWallet(): ShieldedWallet;
+/** Sign a SpendAuth for a request */
+declare function signSpendAuth(wallet: ShieldedWallet, params: {
+    serviceId: bigint;
+    jobIndex: number;
+    amount: bigint;
+    operator: Hex;
+    nonce: bigint;
+    expiry: bigint;
+    chainId: number;
+    creditsAddress: Hex;
+}): Promise<SpendAuth>;
+/** Estimate cost in tsUSD base units (6 decimals) */
+declare function estimateCost(inputTokens: number, maxOutputTokens: number, inputPricePerM?: number, outputPricePerM?: number): bigint;
+interface AutoReplenishOptions {
+    minBalance: bigint;
+    replenishAmount: bigint;
+    checkIntervalMs?: number;
+    fundingSource: 'relayer' | 'direct';
+    relayerUrl?: string;
+    fundingWalletKey?: Hex;
+    tokenAddress?: Hex;
+}
+/**
+ * Create a shielded TCloudClient that signs SpendAuth automatically.
+ * Every request is anonymous — no API key, no identity.
+ */
+declare function createShieldedClient(config?: TCloudConfig & {
+    wallet?: ShieldedWallet;
+    operatorAddress?: Hex;
+    chainId?: number;
+    creditsAddress?: Hex;
+    serviceId?: bigint;
+    autoReplenish?: AutoReplenishOptions;
+}): TCloudClient & {
+    wallet: ShieldedWallet;
+    stopAutoReplenish: () => void;
+};
+
+export { type AutoReplenishOptions as A, type ChatCompletion as C, type Model as M, type Operator as O, type PrivacyConfig as P, type RoutingConfig as R, type ShieldedWallet as S, TCloudClient as T, type TCloudConfig as a, type ChatCompletionChunk as b, type ChatMessage as c, type ChatOptions as d, type CreditBalance as e, type ShieldedConfig as f, generateWallet as g, type SpendAuth as h, type SpendingLimits as i, TCloudError as j, createShieldedClient as k, estimateCost as l, signSpendAuth as s };