cocoon-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,462 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * TCP + TLS connection with Cocoon framing.
+ *
+ * Connection flow:
+ * 1. Raw TCP connect
+ * 2. Receive PoW challenge (24 bytes), solve it, send response (12 bytes)
+ * 3. Upgrade to TLS on same socket
+ * 4. TL framing begins: [4 bytes LE size][4 bytes LE seqno][payload]
+ *    Where `size` is the length of `payload` only.
+ */
+
+interface ConnectionOptions {
+    host: string;
+    port: number;
+    useTls?: boolean;
+    timeout?: number;
+    /** PEM-encoded TLS client certificate (for RA-TLS / mTLS) */
+    tlsCert?: string | Buffer;
+    /** PEM-encoded TLS client private key (for RA-TLS / mTLS) */
+    tlsKey?: string | Buffer;
+}
+
+/**
+ * TypeScript interfaces for TL objects used in the Cocoon protocol.
+ * Derived from cocoon_api.tl schema.
+ */
+type TLInt = number;
+type TLLong = bigint;
+type TLDouble = number;
+type TLInt256 = Buffer;
+type TLBytes = Buffer;
+type TLString = string;
+type TLBool = boolean;
+interface ProxyParams {
+    _type: 'proxy.params';
+    flags: TLInt;
+    proxyPublicKey: TLInt256;
+    proxyOwnerAddress: TLString;
+    proxyScAddress: TLString;
+    isTest?: TLBool;
+    protoVersion?: TLInt;
+}
+interface TokensUsed {
+    _type: 'tokensUsed';
+    promptTokensUsed: TLLong;
+    cachedTokensUsed: TLLong;
+    completionTokensUsed: TLLong;
+    reasoningTokensUsed: TLLong;
+    totalTokensUsed: TLLong;
+}
+interface ClientQueryFinalInfo {
+    _type: 'client.queryFinalInfo';
+    flags: TLInt;
+    tokensUsed: TokensUsed;
+    workerDebug?: TLString;
+    proxyDebug?: TLString;
+    proxyStartTime?: TLDouble;
+    proxyEndTime?: TLDouble;
+    workerStartTime?: TLDouble;
+    workerEndTime?: TLDouble;
+}
+interface ClientQueryAnswerEx {
+    _type: 'client.queryAnswerEx';
+    requestId: TLInt256;
+    answer: TLBytes;
+    flags: TLInt;
+    finalInfo?: ClientQueryFinalInfo;
+}
+interface ClientQueryAnswerErrorEx {
+    _type: 'client.queryAnswerErrorEx';
+    requestId: TLInt256;
+    errorCode: TLInt;
+    error: TLString;
+    flags: TLInt;
+    finalInfo?: ClientQueryFinalInfo;
+}
+interface ClientQueryAnswerPartEx {
+    _type: 'client.queryAnswerPartEx';
+    requestId: TLInt256;
+    answer: TLBytes;
+    flags: TLInt;
+    finalInfo?: ClientQueryFinalInfo;
+}
+type ClientQueryAnswerExType = ClientQueryAnswerEx | ClientQueryAnswerErrorEx | ClientQueryAnswerPartEx;
+interface HttpHeader {
+    _type: 'http.header';
+    name: TLString;
+    value: TLString;
+}
+interface HttpRequest {
+    _type: 'http.request';
+    method: TLString;
+    url: TLString;
+    httpVersion: TLString;
+    headers: HttpHeader[];
+    payload: TLBytes;
+}
+
+/**
+ * Cocoon protocol handshake.
+ *
+ * Flow:
+ * 1. Client sends tcp.connect(id) → Server replies tcp.connected(id)
+ * 2. Client sends client.connectToProxy(params, minConfigVersion)
+ *    → Server replies client.connectedToProxy(params, clientScAddress, auth, signedPayment)
+ * 3. Auth: short (secret hash match) or long (blockchain registration)
+ *    - Short: client.authorizeWithProxyShort(secretData)
+ *    - Long: client.authorizeWithProxyLong() (after on-chain tx)
+ *    → Server replies client.AuthorizationWithProxy (success or failed)
+ */
+
+interface LongAuthContext {
+    nonce: bigint;
+    clientScAddress: string;
+    proxyParams: ProxyParams;
+}
+type LongAuthHandler = (context: LongAuthContext) => Promise<void>;
+
+/**
+ * Cocoon Session — manages an authenticated connection to a proxy.
+ *
+ * Handles:
+ * - Keepalive (tcp.ping/tcp.pong)
+ * - Query dispatch and response routing by requestId
+ * - Streaming response assembly
+ */
+
+interface SessionOptions extends ConnectionOptions {
+    ownerAddress: string;
+    secretString: string;
+    configVersion?: number;
+    onLongAuthRequired?: LongAuthHandler;
+}
+declare class CocoonSession extends EventEmitter {
+    private conn;
+    private handshakeResult;
+    private pendingQueries;
+    private keepaliveTimer;
+    private _connected;
+    private readonly options;
+    constructor(options: SessionOptions);
+    get connected(): boolean;
+    get protoVersion(): number;
+    connect(): Promise<void>;
+    /**
+     * Send a query and wait for the complete answer.
+     */
+    sendQuery(modelName: string, httpRequest: HttpRequest, options?: {
+        maxCoefficient?: number;
+        maxTokens?: number;
+        timeout?: number;
+        enableDebug?: boolean;
+        onPart?: (part: ClientQueryAnswerExType) => void;
+    }): Promise<ClientQueryAnswerExType>;
+    /**
+     * Send a raw TL function (for getWorkerTypesV2, etc.)
+     */
+    sendRpcQuery(tlObject: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+    disconnect(): Promise<void>;
+    private handleFrame;
+    private handleInnerPacket;
+    private isTerminalQueryAnswer;
+    private startKeepalive;
+    private cleanup;
+}
+
+/**
+ * Stream<T> — an async iterable wrapper for streaming responses.
+ * Follows the OpenAI SDK pattern.
+ */
+declare class Stream<T> implements AsyncIterable<T> {
+    private controller;
+    private stream;
+    private _done;
+    constructor();
+    /**
+     * Push a chunk into the stream.
+     */
+    push(chunk: T): void;
+    /**
+     * Signal that the stream is complete.
+     */
+    end(): void;
+    /**
+     * Signal an error on the stream.
+     */
+    error(err: Error): void;
+    get done(): boolean;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+/**
+ * Common types shared across the API.
+ */
+interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cached_tokens?: number;
+    reasoning_tokens?: number;
+}
+type FinishReason = 'stop' | 'length' | 'content_filter' | 'tool_calls' | null;
+
+/**
+ * OpenAI-compatible chat completion types.
+ */
+
+type ChatRole = 'system' | 'user' | 'assistant';
+interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+interface ChatCompletionCreateParams {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    stream?: boolean;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    /** Cocoon-specific: max coefficient for worker selection */
+    max_coefficient?: number;
+    /** Cocoon-specific: request timeout in ms */
+    timeout?: number;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: FinishReason;
+}
+interface ChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: Usage;
+}
+interface ChatCompletionChunkDelta {
+    role?: ChatRole;
+    content?: string;
+}
+interface ChatCompletionChunkChoice {
+    index: number;
+    delta: ChatCompletionChunkDelta;
+    finish_reason: FinishReason;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+    usage?: Usage;
+}
+
+/**
+ * Chat Completions resource — the main API for AI inference.
+ *
+ * Implements both non-streaming and streaming modes:
+ * - Non-streaming: collects all queryAnswerPartEx + final queryAnswerEx,
+ *   parses the HTTP response body as JSON, returns ChatCompletion.
+ * - Streaming: wraps parts in Stream<ChatCompletionChunk>, parses SSE from chunks.
+ */
+
+type SessionProvider$1 = () => Promise<CocoonSession>;
+declare class Completions {
+    private readonly getSession;
+    constructor(getSession: SessionProvider$1);
+    private extractHttpData;
+    private parseErrorPayload;
+    /**
+     * Create a chat completion.
+     *
+     * @param params - OpenAI-compatible chat completion parameters
+     * @returns ChatCompletion (non-streaming) or Stream<ChatCompletionChunk> (streaming)
+     */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): Promise<Stream<ChatCompletionChunk>>;
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+    private createNonStreaming;
+    private createStreaming;
+    private processSSEBuffer;
+}
+
+/**
+ * OpenAI-compatible model types.
+ */
+interface Model {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+    /** Cocoon-specific: number of active workers for this model */
+    active_workers?: number;
+    /** Cocoon-specific: coefficient range */
+    coefficient_min?: number;
+    coefficient_max?: number;
+}
+interface ModelList {
+    object: 'list';
+    data: Model[];
+}
+
+/**
+ * Models resource — list available AI models on the network.
+ *
+ * Uses client.getWorkerTypesV2 TL function to query the proxy.
+ */
+
+type SessionProvider = () => Promise<CocoonSession>;
+declare class Models {
+    private readonly getSession;
+    constructor(getSession: SessionProvider);
+    /**
+     * List all available models on the network.
+     */
+    list(): Promise<ModelList>;
+}
+
+interface ClientTlsCredentials {
+    cert: string | Buffer;
+    key: string | Buffer;
+}
+interface AttestationContext {
+    host: string;
+    port: number;
+    network: 'mainnet' | 'testnet';
+}
+/**
+ * Provides RA-TLS client credentials (certificate + private key) for mTLS.
+ * Implementations may load static values, files, or fetch from sidecars.
+ */
+interface AttestationProvider {
+    getClientTlsCredentials(context: AttestationContext): Promise<ClientTlsCredentials>;
+}
+/**
+ * Uses already available in-memory credentials.
+ */
+declare class StaticAttestationProvider implements AttestationProvider {
+    private readonly credentials;
+    constructor(credentials: ClientTlsCredentials);
+    getClientTlsCredentials(): Promise<ClientTlsCredentials>;
+}
+/**
+ * Loads credentials from PEM files on each call.
+ * Useful when credentials are rotated externally.
+ */
+declare class FileAttestationProvider implements AttestationProvider {
+    private readonly certPath;
+    private readonly keyPath;
+    constructor(certPath: string, keyPath: string);
+    getClientTlsCredentials(): Promise<ClientTlsCredentials>;
+}
+
+/**
+ * Cocoon SDK Client — the main entry point.
+ *
+ * Usage:
+ *   const client = new Cocoon({
+ *     wallet: '24 word mnemonic...',
+ *     network: 'mainnet',
+ *   });
+ *
+ *   const response = await client.chat.completions.create({
+ *     model: 'deepseek-r1',
+ *     messages: [{ role: 'user', content: 'Hello!' }],
+ *   });
+ */
+
+interface CocoonOptions {
+    /** 24-word mnemonic phrase */
+    wallet: string;
+    /** Network: mainnet or testnet. Default: mainnet */
+    network?: 'mainnet' | 'testnet';
+    /** Direct proxy URL (bypasses discovery). Format: host:port */
+    proxyUrl?: string;
+    /** Request timeout in ms. Default: 120000 */
+    timeout?: number;
+    /** Optional TON JSON-RPC endpoint for on-chain operations (registration, wallet tx). */
+    tonEndpoint?: string;
+    /** Optional TON v4 endpoint used for wallet transaction sending. */
+    tonV4Endpoint?: string;
+    /** Secret string for short auth. Auto-generated if not provided. */
+    secretString?: string;
+    /** Use TLS for proxy connection. Default: true */
+    useTls?: boolean;
+    /** PEM-encoded TLS client certificate for RA-TLS / mTLS authentication */
+    tlsCert?: string | Buffer;
+    /** PEM-encoded TLS client private key for RA-TLS / mTLS authentication */
+    tlsKey?: string | Buffer;
+    /** Dynamic provider for RA-TLS credentials (e.g. sidecar, file rotation). */
+    attestationProvider?: AttestationProvider;
+    /**
+     * If true, automatically perform on-chain long-auth registration when proxy requests it.
+     * This sends a TON transaction from the mnemonic wallet.
+     * Default: true
+     */
+    autoRegisterOnLongAuth?: boolean;
+    /** Amount in TON to attach to auto long-auth registration tx. Default: "1" */
+    longAuthRegisterAmountTon?: string;
+}
+declare class Cocoon {
+    readonly chat: {
+        completions: Completions;
+    };
+    readonly models: Models;
+    private readonly mnemonicWallet;
+    private readonly discovery;
+    private session;
+    private connecting;
+    private readonly options;
+    constructor(options: CocoonOptions);
+    /**
+     * Explicitly connect to a proxy. Called lazily on first API call if not called manually.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the proxy.
+     */
+    disconnect(): Promise<void>;
+    private ensureSession;
+    private createSession;
+}
+
+/**
+ * Error classes for the Cocoon SDK.
+ */
+declare class CocoonError extends Error {
+    constructor(message: string);
+}
+declare class ConnectionError extends CocoonError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+declare class ProtocolError extends CocoonError {
+    readonly code?: number | undefined;
+    constructor(message: string, code?: number | undefined);
+}
+declare class APIError extends CocoonError {
+    readonly statusCode: number;
+    readonly errorBody?: unknown | undefined;
+    constructor(message: string, statusCode: number, errorBody?: unknown | undefined);
+}
+declare class AuthenticationError extends CocoonError {
+    readonly code?: number | undefined;
+    constructor(message: string, code?: number | undefined);
+}
+declare class TimeoutError extends CocoonError {
+    constructor(message?: string);
+}
+
+export { APIError, type AttestationContext, type AttestationProvider, AuthenticationError, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionChunkChoice, type ChatCompletionChunkDelta, type ChatCompletionCreateParams, type ChatMessage, type ChatRole, type ClientTlsCredentials, Cocoon, CocoonError, type CocoonOptions, ConnectionError, FileAttestationProvider, type FinishReason, type Model, type ModelList, ProtocolError, StaticAttestationProvider, Stream, TimeoutError, type Usage };