@ctxprotocol/sdk 0.8.1 → 0.8.3

package/dist/client/index.d.ts

@@ -9,9 +9,19 @@ interface ContextClientOptions {
     apiKey: string;
     /**
      * Base URL for the Context Protocol API
-     * @default "https://ctxprotocol.com"
+     * @default "https://www.ctxprotocol.com"
      */
     baseUrl?: string;
+    /**
+     * Request timeout for non-streaming API calls in milliseconds.
+     * @default 300000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Request timeout for establishing streaming API calls in milliseconds.
+     * @default 600000
+     */
+    streamTimeoutMs?: number;
 }
 /**
  * An individual MCP tool exposed by a tool listing
@@ -30,7 +40,27 @@ interface McpToolRateLimitHints {
     /** Optional human-readable notes for planning */
     notes?: string;
 }
+type DiscoveryMode = "query" | "execute";
+type McpToolSurface = "answer" | "execute" | "both";
+type McpToolLatencyClass = "instant" | "fast" | "slow" | "streaming";
+interface McpToolPricingMeta {
+    executeUsd?: string;
+    queryUsd?: string;
+    [key: string]: unknown;
+}
 interface McpToolMeta {
+    /** Declared method surface */
+    surface?: McpToolSurface;
+    /** Whether this method can be selected in query mode */
+    queryEligible?: boolean;
+    /** Declared latency class for planner/runtime gating */
+    latencyClass?: McpToolLatencyClass;
+    /** Method-level pricing metadata */
+    pricing?: McpToolPricingMeta;
+    /** Derived discovery flag for execute eligibility */
+    executeEligible?: boolean;
+    /** Derived discovery field for explicit execute pricing visibility */
+    executePriceUsd?: string;
     /** Context injection requirements handled by the Context runtime */
     contextRequirements?: string[];
     /**
@@ -48,6 +78,14 @@ interface McpToolMeta {
     notes?: string;
     [key: string]: unknown;
 }
+interface StructuredMethodGuidanceHints {
+    /** Suggested call-order sequence extracted from method descriptions */
+    callOrderHints?: string[];
+    /** Parameter usage caveats extracted from method descriptions */
+    parameterCaveats?: string[];
+    /** Edge-case behavior notes extracted from method descriptions */
+    edgeCaseNotes?: string[];
+}
 interface McpTool {
     /** Name of the MCP tool method */
     name: string;
@@ -65,6 +103,14 @@ interface McpTool {
     outputSchema?: Record<string, unknown>;
     /** MCP metadata extensions (context injection, rate-limit hints) */
     _meta?: McpToolMeta;
+    /** Explicit execute eligibility in discovery responses */
+    executeEligible?: boolean;
+    /** Explicit execute price visibility in discovery responses */
+    executePriceUsd?: string | null;
+    /** Whether this method has normalized structured guidance hints */
+    hasStructuredGuidance?: boolean;
+    /** Optional structured guidance hints derived from the method description */
+    structuredGuidance?: StructuredMethodGuidanceHints;
 }
 /**
  * Represents a tool available on the Context Protocol marketplace
@@ -106,6 +152,8 @@ interface Tool {
 interface SearchResponse {
     /** Array of matching tools */
     tools: Tool[];
+    /** Discovery mode used by the server */
+    mode?: DiscoveryMode;
     /** The search query that was used */
     query: string;
     /** Total number of results */
@@ -119,6 +167,18 @@ interface SearchOptions {
     query?: string;
     /** Maximum number of results (1-50, default 10) */
     limit?: number;
+    /** Discovery mode with billing semantics */
+    mode?: DiscoveryMode;
+    /** Optional explicit method surface filter */
+    surface?: McpToolSurface;
+    /** Require methods marked query eligible */
+    queryEligible?: boolean;
+    /** Require explicit method execute pricing */
+    requireExecutePricing?: boolean;
+    /** Exclude methods by latency class */
+    excludeLatencyClasses?: McpToolLatencyClass[];
+    /** Convenience switch to exclude slow methods in query mode */
+    excludeSlow?: boolean;
 }
 /**
  * Options for executing a tool
@@ -135,12 +195,36 @@ interface ExecuteOptions {
      * Reuse the same key when retrying the same logical request.
      */
     idempotencyKey?: string;
+    /** Explicit execute mode label for request clarity */
+    mode?: "execute";
+    /** Optional execute session identifier */
+    sessionId?: string;
+    /** Optional per-session spend budget envelope (USD) */
+    maxSpendUsd?: string;
+    /** Request session closure after this execute call settles */
+    closeSession?: boolean;
+}
+type ExecuteSessionStatus = "open" | "closed" | "expired";
+interface ExecuteSessionSpend {
+    mode: "execute";
+    sessionId: string | null;
+    methodPrice: string;
+    spent: string;
+    remaining: string | null;
+    maxSpend: string | null;
+    /** Optional lifecycle fields when the API returns session state */
+    status?: ExecuteSessionStatus;
+    expiresAt?: string;
+    closeRequested?: boolean;
+    pendingAccruedCount?: number;
+    pendingAccruedUsd?: string;
 }
 /**
  * Successful execution response from the API
  */
 interface ExecuteApiSuccessResponse {
     success: true;
+    mode: "execute";
     /** The result data from the tool execution */
     result: unknown;
     /** Information about the executed tool */
@@ -148,6 +232,13 @@ interface ExecuteApiSuccessResponse {
         id: string;
         name: string;
     };
+    /** Method-level execute pricing used for this call */
+    method: {
+        name: string;
+        executePriceUsd: string;
+    };
+    /** Spend envelope visibility for execute sessions */
+    session: ExecuteSessionSpend;
     /** Execution duration in milliseconds */
     durationMs: number;
 }
@@ -157,19 +248,38 @@ interface ExecuteApiSuccessResponse {
 interface ExecuteApiErrorResponse {
     /** Human-readable error message */
     error: string;
+    /** Explicit mode label for clarity */
+    mode?: "execute";
     /** Error code for programmatic handling */
     code?: ContextErrorCode;
     /** URL to help resolve the issue */
     helpUrl?: string;
+    /** Optional spend envelope context when available */
+    session?: ExecuteSessionSpend;
 }
 /**
  * Raw API response from the execute endpoint
  */
 type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;
+interface ExecuteSessionStartOptions {
+    /** Maximum spend budget for the session (USD string) */
+    maxSpendUsd: string;
+}
+interface ExecuteSessionApiSuccessResponse {
+    success: true;
+    mode: "execute";
+    session: ExecuteSessionSpend;
+}
+type ExecuteSessionApiResponse = ExecuteSessionApiSuccessResponse | ExecuteApiErrorResponse;
+interface ExecuteSessionResult {
+    mode: "execute";
+    session: ExecuteSessionSpend;
+}
 /**
  * The resolved result returned to the user after SDK processing
  */
 interface ExecutionResult<T = unknown> {
+    mode: "execute";
     /** The data returned by the tool */
     result: T;
     /** Information about the executed tool */
@@ -177,9 +287,18 @@ interface ExecutionResult<T = unknown> {
         id: string;
         name: string;
     };
+    /** Method-level execute pricing used for this call */
+    method: {
+        name: string;
+        executePriceUsd: string;
+    };
+    /** Spend envelope visibility for execute calls */
+    session: ExecuteSessionSpend;
     /** Execution duration in milliseconds */
     durationMs: number;
 }
+/** Supported orchestration depth modes for query execution. */
+type QueryDepth = "fast" | "auto" | "deep";
 /**
  * Options for the agentic query endpoint (pay-per-response).
  *
@@ -212,6 +331,13 @@ interface QueryOptions {
      * Useful for large payload workflows where inline JSON is not ideal.
      */
     includeDataUrl?: boolean;
+    /**
+     * Query orchestration depth mode:
+     * - `fast`: lower-latency path
+     * - `auto`: server decides between fast/deep
+     * - `deep`: full completeness-oriented path
+     */
+    queryDepth?: QueryDepth;
     /**
      * Optional idempotency key (UUID recommended).
      * Reuse the same key when retrying the same logical request.
@@ -300,7 +426,7 @@ type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent |
 /**
  * Specific error codes returned by the Context Protocol API
  */
-type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed" | "query_failed";
+type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed" | "query_failed" | "invalid_tool_method" | "method_not_execute_eligible" | "invalid_max_spend" | "session_not_found" | "session_forbidden" | "session_closed" | "session_expired" | "max_spend_mismatch" | "session_budget_exceeded";
 /**
  * Error thrown by the Context Protocol client
  */
@@ -318,20 +444,14 @@ declare class Discovery {
     private client;
     constructor(client: ContextClient);
     /**
-     * Search for tools matching a query string
-     *
-     * @param query - The search query (e.g., "gas prices", "nft metadata")
-     * @param limit - Maximum number of results (1-50, default 10)
-     * @returns Array of matching tools
+     * Search for tools matching a query string.
      *
-     * @example
-     * ```typescript
-     * const tools = await client.discovery.search("gas prices");
-     * console.log(tools[0].name); // "Gas Price Oracle"
-     * console.log(tools[0].mcpTools); // Available methods
-     * ```
+     * Backward-compatible signatures:
+     * - `search("gas prices", 10)`
+     * - `search({ query: "gas prices", limit: 10, mode: "execute" })`
      */
     search(query: string, limit?: number): Promise<Tool[]>;
+    search(options: SearchOptions): Promise<Tool[]>;
     /**
      * Get featured/popular tools (empty query search)
      *
@@ -343,7 +463,7 @@ declare class Discovery {
      * const featured = await client.discovery.getFeatured(5);
      * ```
      */
-    getFeatured(limit?: number): Promise<Tool[]>;
+    getFeatured(limit?: number, options?: Omit<SearchOptions, "query" | "limit">): Promise<Tool[]>;
 }
 
 /**
@@ -384,6 +504,19 @@ declare class Tools {
      * ```
      */
     execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>>;
+    /**
+     * Start an execute session with a max spend budget.
+     */
+    startSession(options: ExecuteSessionStartOptions): Promise<ExecuteSessionResult>;
+    /**
+     * Fetch current execute session status by ID.
+     */
+    getSession(sessionId: string): Promise<ExecuteSessionResult>;
+    /**
+     * Close an execute session by ID.
+     */
+    closeSession(sessionId: string): Promise<ExecuteSessionResult>;
+    private resolveSessionLifecycleResponse;
 }
 
 /**
@@ -493,6 +626,8 @@ declare class Query {
 declare class ContextClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly streamTimeoutMs;
     private _closed;
     /**
      * Discovery resource for searching tools
@@ -515,7 +650,9 @@ declare class ContextClient {
      *
      * @param options - Client configuration options
      * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
-     * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
+     * @param options.baseUrl - Optional base URL override (defaults to https://www.ctxprotocol.com)
+     * @param options.requestTimeoutMs - Optional timeout for non-streaming requests (default 300000ms)
+     * @param options.streamTimeoutMs - Optional timeout for establishing stream requests (default 600000ms)
      */
     constructor(options: ContextClientOptions);
     /**
@@ -525,7 +662,7 @@ declare class ContextClient {
     close(): void;
     /**
      * Internal method for making authenticated HTTP requests
-     * Includes timeout (30s) and retry with exponential backoff for transient errors
+     * Includes timeout and retry with exponential backoff for transient errors
      *
      * @internal
      */
@@ -533,10 +670,11 @@ declare class ContextClient {
     /**
      * Internal method for making authenticated HTTP requests that returns
      * the raw Response object. Used for streaming endpoints (SSE).
+     * Includes a configurable timeout for stream setup.
      *
      * @internal
      */
     _fetchRaw(endpoint: string, options?: RequestInit): Promise<Response>;
 }
 
-export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecutionResult, type McpTool, type McpToolMeta, type McpToolRateLimitHints, Query, type QueryApiResponse, type QueryApiSuccessResponse, type QueryCost, type QueryOptions, type QueryResult, type QueryStreamDoneEvent, type QueryStreamEvent, type QueryStreamTextDeltaEvent, type QueryStreamToolStatusEvent, type QueryToolUsage, type SearchOptions, type SearchResponse, type Tool, Tools };
+export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecuteSessionApiResponse, type ExecuteSessionApiSuccessResponse, type ExecuteSessionResult, type ExecuteSessionSpend, type ExecuteSessionStartOptions, type ExecuteSessionStatus, type ExecutionResult, type McpTool, type McpToolMeta, type McpToolRateLimitHints, Query, type QueryApiResponse, type QueryApiSuccessResponse, type QueryCost, type QueryOptions, type QueryResult, type QueryStreamDoneEvent, type QueryStreamEvent, type QueryStreamTextDeltaEvent, type QueryStreamToolStatusEvent, type QueryToolUsage, type SearchOptions, type SearchResponse, type Tool, Tools };

package/dist/client/index.js

@@ -15,27 +15,36 @@ var Discovery = class {
   constructor(client) {
     this.client = client;
   }
-  /**
-   * Search for tools matching a query string
-   *
-   * @param query - The search query (e.g., "gas prices", "nft metadata")
-   * @param limit - Maximum number of results (1-50, default 10)
-   * @returns Array of matching tools
-   *
-   * @example
-   * ```typescript
-   * const tools = await client.discovery.search("gas prices");
-   * console.log(tools[0].name); // "Gas Price Oracle"
-   * console.log(tools[0].mcpTools); // Available methods
-   * ```
-   */
-  async search(query, limit) {
+  async search(queryOrOptions, limit) {
+    const options = typeof queryOrOptions === "string" ? { query: queryOrOptions, limit } : queryOrOptions;
     const params = new URLSearchParams();
+    const query = options.query ?? "";
     if (query) {
       params.set("q", query);
     }
-    if (limit !== void 0) {
-      params.set("limit", String(limit));
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.mode) {
+      params.set("mode", options.mode);
+    }
+    if (options.surface) {
+      params.set("surface", options.surface);
+    }
+    if (options.queryEligible !== void 0) {
+      params.set("queryEligible", String(options.queryEligible));
+    }
+    if (options.requireExecutePricing !== void 0) {
+      params.set(
+        "requireExecutePricing",
+        String(options.requireExecutePricing)
+      );
+    }
+    if (options.excludeLatencyClasses && options.excludeLatencyClasses.length > 0) {
+      params.set("excludeLatency", options.excludeLatencyClasses.join(","));
+    }
+    if (options.excludeSlow !== void 0) {
+      params.set("excludeSlow", String(options.excludeSlow));
     }
     const queryString = params.toString();
     const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : ""}`;
@@ -53,8 +62,12 @@ var Discovery = class {
    * const featured = await client.discovery.getFeatured(5);
    * ```
    */
-  async getFeatured(limit) {
-    return this.search("", limit);
+  async getFeatured(limit, options) {
+    return this.search({
+      ...options ?? {},
+      query: "",
+      ...limit !== void 0 ? { limit } : {}
+    });
   }
 };
 
@@ -95,14 +108,31 @@ var Tools = class {
    * ```
    */
   async execute(options) {
-    const { toolId, toolName, args, idempotencyKey } = options;
+    const {
+      toolId,
+      toolName,
+      args,
+      idempotencyKey,
+      mode,
+      sessionId,
+      maxSpendUsd,
+      closeSession
+    } = options;
     const headers = idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0;
     const response = await this.client._fetch(
       "/api/v1/tools/execute",
       {
         method: "POST",
         headers,
-        body: JSON.stringify({ toolId, toolName, args })
+        body: JSON.stringify({
+          toolId,
+          toolName,
+          args,
+          mode: mode ?? "execute",
+          sessionId,
+          maxSpendUsd,
+          closeSession
+        })
       }
     );
     if ("error" in response) {
@@ -116,13 +146,79 @@ var Tools = class {
     }
     if (response.success) {
       return {
+        mode: response.mode,
         result: response.result,
         tool: response.tool,
+        method: response.method,
+        session: response.session,
         durationMs: response.durationMs
       };
     }
     throw new ContextError("Unexpected response format from API");
   }
+  /**
+   * Start an execute session with a max spend budget.
+   */
+  async startSession(options) {
+    const response = await this.client._fetch(
+      "/api/v1/tools/execute/sessions",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          mode: "execute",
+          maxSpendUsd: options.maxSpendUsd
+        })
+      }
+    );
+    return this.resolveSessionLifecycleResponse(response);
+  }
+  /**
+   * Fetch current execute session status by ID.
+   */
+  async getSession(sessionId) {
+    if (!sessionId) {
+      throw new ContextError("sessionId is required");
+    }
+    const encodedSessionId = encodeURIComponent(sessionId);
+    const response = await this.client._fetch(
+      `/api/v1/tools/execute/sessions/${encodedSessionId}`
+    );
+    return this.resolveSessionLifecycleResponse(response);
+  }
+  /**
+   * Close an execute session by ID.
+   */
+  async closeSession(sessionId) {
+    if (!sessionId) {
+      throw new ContextError("sessionId is required");
+    }
+    const encodedSessionId = encodeURIComponent(sessionId);
+    const response = await this.client._fetch(
+      `/api/v1/tools/execute/sessions/${encodedSessionId}/close`,
+      {
+        method: "POST",
+        body: JSON.stringify({ mode: "execute" })
+      }
+    );
+    return this.resolveSessionLifecycleResponse(response);
+  }
+  resolveSessionLifecycleResponse(response) {
+    if ("error" in response) {
+      throw new ContextError(
+        response.error,
+        response.code,
+        void 0,
+        response.helpUrl
+      );
+    }
+    if (response.success) {
+      return {
+        mode: response.mode,
+        session: response.session
+      };
+    }
+    throw new ContextError("Unexpected response format from API");
+  }
 };
 
 // src/client/resources/query.ts
@@ -175,6 +271,7 @@ var Query = class {
           modelId: opts.modelId,
           includeData: opts.includeData,
           includeDataUrl: opts.includeDataUrl,
+          queryDepth: opts.queryDepth,
           stream: false
         })
       }
@@ -240,6 +337,7 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        queryDepth: opts.queryDepth,
         stream: true
       })
     });
@@ -285,9 +383,14 @@ var Query = class {
 };
 
 // src/client/client.ts
+var DEFAULT_BASE_URL = "https://www.ctxprotocol.com";
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e5;
+var DEFAULT_STREAM_TIMEOUT_MS = 6e5;
 var ContextClient = class {
   apiKey;
   baseUrl;
+  requestTimeoutMs;
+  streamTimeoutMs;
   _closed = false;
   /**
    * Discovery resource for searching tools
@@ -310,14 +413,26 @@ var ContextClient = class {
    *
    * @param options - Client configuration options
    * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
-   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
+   * @param options.baseUrl - Optional base URL override (defaults to https://www.ctxprotocol.com)
+   * @param options.requestTimeoutMs - Optional timeout for non-streaming requests (default 300000ms)
+   * @param options.streamTimeoutMs - Optional timeout for establishing stream requests (default 600000ms)
    */
   constructor(options) {
     if (!options.apiKey) {
       throw new ContextError("API key is required");
     }
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const streamTimeoutMs = options.streamTimeoutMs ?? DEFAULT_STREAM_TIMEOUT_MS;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+      throw new ContextError("requestTimeoutMs must be a positive number");
+    }
+    if (!Number.isFinite(streamTimeoutMs) || streamTimeoutMs <= 0) {
+      throw new ContextError("streamTimeoutMs must be a positive number");
+    }
     this.apiKey = options.apiKey;
-    this.baseUrl = (options.baseUrl ?? "https://ctxprotocol.com").replace(/\/$/, "");
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.streamTimeoutMs = streamTimeoutMs;
     this.discovery = new Discovery(this);
     this.tools = new Tools(this);
     this.query = new Query(this);
@@ -331,7 +446,7 @@ var ContextClient = class {
   }
   /**
    * Internal method for making authenticated HTTP requests
-   * Includes timeout (30s) and retry with exponential backoff for transient errors
+   * Includes timeout and retry with exponential backoff for transient errors
    *
    * @internal
    */
@@ -341,7 +456,7 @@ var ContextClient = class {
     }
     const url = `${this.baseUrl}${endpoint}`;
     const maxRetries = 3;
-    const timeoutMs = 3e4;
+    const timeoutMs = this.requestTimeoutMs;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       const controller = new AbortController();
@@ -409,6 +524,7 @@ var ContextClient = class {
   /**
    * Internal method for making authenticated HTTP requests that returns
    * the raw Response object. Used for streaming endpoints (SSE).
+   * Includes a configurable timeout for stream setup.
    *
    * @internal
    */
@@ -417,14 +533,32 @@ var ContextClient = class {
       throw new ContextError("Client has been closed");
     }
     const url = `${this.baseUrl}${endpoint}`;
-    const response = await fetch(url, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-        ...options.headers
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.streamTimeoutMs);
+    let response;
+    try {
+      response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          ...options.headers
+        }
+      });
+    } catch (error) {
+      clearTimeout(timeout);
+      const lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.name === "AbortError") {
+        throw new ContextError(
+          `Streaming request timed out after ${this.streamTimeoutMs / 1e3}s`,
+          void 0,
+          408
+        );
       }
-    });
+      throw new ContextError(lastError.message);
+    }
+    clearTimeout(timeout);
     if (!response.ok) {
       let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
       let errorCode;