@ctxprotocol/sdk 0.5.6 → 0.7.0

package/dist/client/index.d.ts

@@ -48,15 +48,23 @@ interface Tool {
     category?: string;
     /** Whether the tool is verified by Context Protocol */
     isVerified?: boolean;
+    /** Tool type - currently always "mcp" */
+    kind?: string;
     /**
      * Available MCP tool methods
      * Use items from this array as `toolName` when executing
      */
     mcpTools?: McpTool[];
-    /** Creation timestamp */
-    createdAt?: string;
-    /** Last update timestamp */
-    updatedAt?: string;
+    /** Total number of queries processed */
+    totalQueries?: number;
+    /** Success rate percentage (0-100) */
+    successRate?: string;
+    /** Uptime percentage (0-100) */
+    uptimePercent?: string;
+    /** Total USDC staked by the developer */
+    totalStaked?: string;
+    /** Whether the tool has "Proven" status (100+ queries, >95% success, >98% uptime) */
+    isProven?: boolean;
 }
 /**
  * Response from the tools search endpoint
@@ -133,10 +141,101 @@ interface ExecutionResult<T = unknown> {
     /** Execution duration in milliseconds */
     durationMs: number;
 }
+/**
+ * Options for the agentic query endpoint (pay-per-response).
+ *
+ * Unlike `execute()` which calls a single tool once, `query()` sends a
+ * natural-language question and lets the server handle tool discovery,
+ * multi-tool orchestration, self-healing retries, and AI synthesis.
+ * One flat fee covers up to 100 MCP skill calls per tool.
+ */
+interface QueryOptions {
+    /** The natural-language question to answer */
+    query: string;
+    /**
+     * Optional tool IDs to use. When omitted the server discovers tools
+     * automatically (Auto Mode). When provided, only these tools are used
+     * (Manual Mode).
+     */
+    tools?: string[];
+}
+/**
+ * Information about a tool that was used during a query response
+ */
+interface QueryToolUsage {
+    /** Tool ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Number of MCP skill calls made for this tool */
+    skillCalls: number;
+}
+/**
+ * Cost breakdown for a query response.
+ * All values are strings representing USD amounts.
+ */
+interface QueryCost {
+    /** AI model inference cost */
+    modelCostUsd: string;
+    /** Sum of all tool fees */
+    toolCostUsd: string;
+    /** Total cost (model + tools) */
+    totalCostUsd: string;
+}
+/**
+ * The resolved result of a pay-per-response query
+ */
+interface QueryResult {
+    /** The AI-synthesized response text */
+    response: string;
+    /** Tools that were used to answer the query */
+    toolsUsed: QueryToolUsage[];
+    /** Cost breakdown */
+    cost: QueryCost;
+    /** Total duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Successful response from the /api/v1/query endpoint
+ */
+interface QueryApiSuccessResponse {
+    success: true;
+    response: string;
+    toolsUsed: QueryToolUsage[];
+    cost: QueryCost;
+    durationMs: number;
+}
+/**
+ * Raw API response from the query endpoint
+ */
+type QueryApiResponse = QueryApiSuccessResponse | ExecuteApiErrorResponse;
+/** Emitted when a tool starts or changes execution status */
+interface QueryStreamToolStatusEvent {
+    type: "tool-status";
+    tool: {
+        id: string;
+        name: string;
+    };
+    status: string;
+}
+/** Emitted for each chunk of the AI response text */
+interface QueryStreamTextDeltaEvent {
+    type: "text-delta";
+    delta: string;
+}
+/** Emitted when the full response is complete */
+interface QueryStreamDoneEvent {
+    type: "done";
+    result: QueryResult;
+}
+/**
+ * Union of all events emitted during a streaming query
+ */
+type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent | QueryStreamDoneEvent;
 /**
  * Specific error codes returned by the Context Protocol API
  */
-type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed";
+type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed" | "query_failed";
 /**
  * Error thrown by the Context Protocol client
  */
@@ -198,8 +297,8 @@ declare class Tools {
      * @returns The execution result with the tool's output data
      *
      * @throws {ContextError} With code `no_wallet` if wallet not set up
-     * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled
-     * @throws {ContextError} With code `payment_failed` if on-chain payment fails
+     * @throws {ContextError} With code `insufficient_allowance` if spending cap not set
+     * @throws {ContextError} With code `payment_failed` if payment settlement fails
      * @throws {ContextError} With code `execution_failed` if tool execution fails
      *
      * @example
@@ -222,6 +321,85 @@ declare class Tools {
     execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>>;
 }
 
+/**
+ * Query resource for pay-per-response agentic queries.
+ *
+ * Unlike `tools.execute()` which calls a single tool once (pay-per-request),
+ * the Query resource sends a natural-language question and lets the server
+ * handle tool discovery, multi-tool orchestration, self-healing retries,
+ * completeness checks, and AI synthesis — all for one flat fee.
+ *
+ * This is the "prepared meal" vs "raw ingredients" distinction:
+ * - `tools.execute()` = raw data, full control, predictable cost
+ * - `query.run()` / `query.stream()` = curated intelligence, one payment
+ */
+declare class Query {
+    private client;
+    constructor(client: ContextClient);
+    /**
+     * Run an agentic query and wait for the full response.
+     *
+     * The server discovers relevant tools (or uses the ones you specify),
+     * executes the full agentic pipeline (up to 100 MCP calls per tool),
+     * and returns an AI-synthesized answer. Payment is settled after
+     * successful execution via deferred settlement.
+     *
+     * @param options - Query options or a plain string question
+     * @returns The complete query result with response text, tools used, and cost
+     *
+     * @throws {ContextError} With code `no_wallet` if wallet not set up
+     * @throws {ContextError} With code `insufficient_allowance` if spending cap not set
+     * @throws {ContextError} With code `payment_failed` if payment settlement fails
+     * @throws {ContextError} With code `execution_failed` if the agentic pipeline fails
+     *
+     * @example
+     * ```typescript
+     * // Simple question — server discovers tools automatically
+     * const answer = await client.query.run("What are the top whale movements on Base?");
+     * console.log(answer.response);      // AI-synthesized answer
+     * console.log(answer.toolsUsed);     // Which tools were used
+     * console.log(answer.cost);          // Cost breakdown
+     *
+     * // With specific tools (Manual Mode)
+     * const answer = await client.query.run({
+     *   query: "Analyze whale activity",
+     *   tools: ["tool-uuid-1", "tool-uuid-2"],
+     * });
+     * ```
+     */
+    run(options: QueryOptions | string): Promise<QueryResult>;
+    /**
+     * Run an agentic query with streaming. Returns an async iterable that
+     * yields events as the server processes the query in real-time.
+     *
+     * Event types:
+     * - `tool-status` — A tool started executing or changed status
+     * - `text-delta` — A chunk of the AI response text
+     * - `done` — The full response is complete (includes final `QueryResult`)
+     *
+     * @param options - Query options or a plain string question
+     * @returns An async iterable of stream events
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.query.stream("What are the top whale movements?")) {
+     *   switch (event.type) {
+     *     case "tool-status":
+     *       console.log(`Tool ${event.tool.name}: ${event.status}`);
+     *       break;
+     *     case "text-delta":
+     *       process.stdout.write(event.delta);
+     *       break;
+     *     case "done":
+     *       console.log("\nCost:", event.result.cost.totalCostUsd);
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    stream(options: QueryOptions | string): AsyncGenerator<QueryStreamEvent>;
+}
+
 /**
  * The official TypeScript client for the Context Protocol.
  *
@@ -235,28 +413,38 @@ declare class Tools {
  *   apiKey: "sk_live_..."
  * });
  *
- * // Discover tools
- * const tools = await client.discovery.search("gas prices");
- *
- * // Execute a tool method
+ * // Pay-per-request: Execute a specific tool
  * const result = await client.tools.execute({
- *   toolId: tools[0].id,
- *   toolName: tools[0].mcpTools[0].name,
+ *   toolId: "tool-uuid",
+ *   toolName: "get_gas_prices",
  *   args: { chainId: 1 }
  * });
+ *
+ * // Pay-per-response: Ask a question, get a curated answer
+ * const answer = await client.query.run("What are the top whale movements on Base?");
+ * console.log(answer.response);
  * ```
  */
 declare class ContextClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private _closed;
     /**
      * Discovery resource for searching tools
      */
     readonly discovery: Discovery;
     /**
-     * Tools resource for executing tools
+     * Tools resource for executing tools (pay-per-request)
      */
     readonly tools: Tools;
+    /**
+     * Query resource for agentic queries (pay-per-response).
+     *
+     * Unlike `tools.execute()` which calls a single tool once, `query` sends
+     * a natural-language question and lets the server handle tool discovery,
+     * multi-tool orchestration, self-healing, and AI synthesis — one flat fee.
+     */
+    readonly query: Query;
     /**
      * Creates a new Context Protocol client
      *
@@ -265,13 +453,25 @@ declare class ContextClient {
      * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
      */
     constructor(options: ContextClientOptions);
+    /**
+     * Close the client and clean up resources.
+     * After calling close(), any in-flight requests may be aborted.
+     */
+    close(): void;
     /**
      * Internal method for making authenticated HTTP requests
-     * All requests include the Authorization header with the API key
+     * Includes timeout (30s) and retry with exponential backoff for transient errors
+     *
+     * @internal
+     */
+    _fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    /**
+     * Internal method for making authenticated HTTP requests that returns
+     * the raw Response object. Used for streaming endpoints (SSE).
      *
      * @internal
      */
-    fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    _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 SearchOptions, type SearchResponse, type Tool, Tools };
+export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecutionResult, type McpTool, 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

@@ -1,11 +1,12 @@
 // src/client/types.ts
-var ContextError = class extends Error {
+var ContextError = class _ContextError extends Error {
   constructor(message, code, statusCode, helpUrl) {
     super(message);
     this.code = code;
     this.statusCode = statusCode;
     this.helpUrl = helpUrl;
     this.name = "ContextError";
+    Object.setPrototypeOf(this, _ContextError.prototype);
   }
 };
 
@@ -38,7 +39,7 @@ var Discovery = class {
     }
     const queryString = params.toString();
     const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : ""}`;
-    const response = await this.client.fetch(endpoint);
+    const response = await this.client._fetch(endpoint);
     return response.tools;
   }
   /**
@@ -72,8 +73,8 @@ var Tools = class {
    * @returns The execution result with the tool's output data
    *
    * @throws {ContextError} With code `no_wallet` if wallet not set up
-   * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled
-   * @throws {ContextError} With code `payment_failed` if on-chain payment fails
+   * @throws {ContextError} With code `insufficient_allowance` if spending cap not set
+   * @throws {ContextError} With code `payment_failed` if payment settlement fails
    * @throws {ContextError} With code `execution_failed` if tool execution fails
    *
    * @example
@@ -95,7 +96,7 @@ var Tools = class {
    */
   async execute(options) {
     const { toolId, toolName, args } = options;
-    const response = await this.client.fetch(
+    const response = await this.client._fetch(
       "/api/v1/tools/execute",
       {
         method: "POST",
@@ -106,7 +107,8 @@ var Tools = class {
       throw new ContextError(
         response.error,
         response.code,
-        400,
+        void 0,
+        // Don't hardcode - this was a 200 OK with error body
         response.helpUrl
       );
     }
@@ -121,18 +123,174 @@ var Tools = class {
   }
 };
 
+// src/client/resources/query.ts
+var Query = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Run an agentic query and wait for the full response.
+   *
+   * The server discovers relevant tools (or uses the ones you specify),
+   * executes the full agentic pipeline (up to 100 MCP calls per tool),
+   * and returns an AI-synthesized answer. Payment is settled after
+   * successful execution via deferred settlement.
+   *
+   * @param options - Query options or a plain string question
+   * @returns The complete query result with response text, tools used, and cost
+   *
+   * @throws {ContextError} With code `no_wallet` if wallet not set up
+   * @throws {ContextError} With code `insufficient_allowance` if spending cap not set
+   * @throws {ContextError} With code `payment_failed` if payment settlement fails
+   * @throws {ContextError} With code `execution_failed` if the agentic pipeline fails
+   *
+   * @example
+   * ```typescript
+   * // Simple question — server discovers tools automatically
+   * const answer = await client.query.run("What are the top whale movements on Base?");
+   * console.log(answer.response);      // AI-synthesized answer
+   * console.log(answer.toolsUsed);     // Which tools were used
+   * console.log(answer.cost);          // Cost breakdown
+   *
+   * // With specific tools (Manual Mode)
+   * const answer = await client.query.run({
+   *   query: "Analyze whale activity",
+   *   tools: ["tool-uuid-1", "tool-uuid-2"],
+   * });
+   * ```
+   */
+  async run(options) {
+    const opts = typeof options === "string" ? { query: options } : options;
+    const response = await this.client._fetch(
+      "/api/v1/query",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          query: opts.query,
+          tools: opts.tools,
+          stream: false
+        })
+      }
+    );
+    if ("error" in response) {
+      throw new ContextError(
+        response.error,
+        response.code,
+        void 0,
+        response.helpUrl
+      );
+    }
+    if (response.success) {
+      return {
+        response: response.response,
+        toolsUsed: response.toolsUsed,
+        cost: response.cost,
+        durationMs: response.durationMs
+      };
+    }
+    throw new ContextError("Unexpected response format from query API");
+  }
+  /**
+   * Run an agentic query with streaming. Returns an async iterable that
+   * yields events as the server processes the query in real-time.
+   *
+   * Event types:
+   * - `tool-status` — A tool started executing or changed status
+   * - `text-delta` — A chunk of the AI response text
+   * - `done` — The full response is complete (includes final `QueryResult`)
+   *
+   * @param options - Query options or a plain string question
+   * @returns An async iterable of stream events
+   *
+   * @example
+   * ```typescript
+   * for await (const event of client.query.stream("What are the top whale movements?")) {
+   *   switch (event.type) {
+   *     case "tool-status":
+   *       console.log(`Tool ${event.tool.name}: ${event.status}`);
+   *       break;
+   *     case "text-delta":
+   *       process.stdout.write(event.delta);
+   *       break;
+   *     case "done":
+   *       console.log("\nCost:", event.result.cost.totalCostUsd);
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *stream(options) {
+    const opts = typeof options === "string" ? { query: options } : options;
+    const response = await this.client._fetchRaw("/api/v1/query", {
+      method: "POST",
+      body: JSON.stringify({
+        query: opts.query,
+        tools: opts.tools,
+        stream: true
+      })
+    });
+    const body = response.body;
+    if (!body) {
+      throw new ContextError("No response body for streaming query");
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed.startsWith("data: ")) {
+            const data = trimmed.slice(6);
+            if (data === "[DONE]") return;
+            try {
+              yield JSON.parse(data);
+            } catch {
+            }
+          }
+        }
+      }
+      if (buffer.trim().startsWith("data: ")) {
+        const data = buffer.trim().slice(6);
+        if (data !== "[DONE]") {
+          try {
+            yield JSON.parse(data);
+          } catch {
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+
 // src/client/client.ts
 var ContextClient = class {
   apiKey;
   baseUrl;
+  _closed = false;
   /**
    * Discovery resource for searching tools
    */
   discovery;
   /**
-   * Tools resource for executing tools
+   * Tools resource for executing tools (pay-per-request)
    */
   tools;
+  /**
+   * Query resource for agentic queries (pay-per-response).
+   *
+   * Unlike `tools.execute()` which calls a single tool once, `query` sends
+   * a natural-language question and lets the server handle tool discovery,
+   * multi-tool orchestration, self-healing, and AI synthesis — one flat fee.
+   */
+  query;
   /**
    * Creates a new Context Protocol client
    *
@@ -148,14 +306,102 @@ var ContextClient = class {
     this.baseUrl = (options.baseUrl ?? "https://ctxprotocol.com").replace(/\/$/, "");
     this.discovery = new Discovery(this);
     this.tools = new Tools(this);
+    this.query = new Query(this);
+  }
+  /**
+   * Close the client and clean up resources.
+   * After calling close(), any in-flight requests may be aborted.
+   */
+  close() {
+    this._closed = true;
   }
   /**
    * Internal method for making authenticated HTTP requests
-   * All requests include the Authorization header with the API key
+   * Includes timeout (30s) and retry with exponential backoff for transient errors
    *
    * @internal
    */
-  async fetch(endpoint, options = {}) {
+  async _fetch(endpoint, options = {}) {
+    if (this._closed) {
+      throw new ContextError("Client has been closed");
+    }
+    const url = `${this.baseUrl}${endpoint}`;
+    const maxRetries = 3;
+    const timeoutMs = 3e4;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(url, {
+          ...options,
+          signal: controller.signal,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...options.headers
+          }
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+          if (response.status >= 500 && attempt < maxRetries) {
+            const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+          let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+          let errorCode;
+          let helpUrl;
+          try {
+            const errorBody = await response.json();
+            if (errorBody.error) {
+              errorMessage = errorBody.error;
+              errorCode = errorBody.code;
+              helpUrl = errorBody.helpUrl;
+            }
+          } catch {
+          }
+          throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
+        }
+        return response.json();
+      } catch (error) {
+        clearTimeout(timeout);
+        if (error instanceof ContextError) {
+          throw error;
+        }
+        lastError = error instanceof Error ? error : new Error(String(error));
+        const isRetryable = lastError.name === "AbortError" || lastError.message.includes("fetch failed") || lastError.message.includes("ECONNRESET") || lastError.message.includes("ETIMEDOUT");
+        if (isRetryable && attempt < maxRetries) {
+          const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        if (lastError.name === "AbortError") {
+          throw new ContextError(
+            `Request timed out after ${timeoutMs / 1e3}s`,
+            void 0,
+            408
+          );
+        }
+        throw new ContextError(
+          lastError.message,
+          void 0,
+          void 0
+        );
+      }
+    }
+    throw lastError ?? new ContextError("Request failed after retries");
+  }
+  /**
+   * Internal method for making authenticated HTTP requests that returns
+   * the raw Response object. Used for streaming endpoints (SSE).
+   *
+   * @internal
+   */
+  async _fetchRaw(endpoint, options = {}) {
+    if (this._closed) {
+      throw new ContextError("Client has been closed");
+    }
     const url = `${this.baseUrl}${endpoint}`;
     const response = await fetch(url, {
       ...options,
@@ -180,10 +426,10 @@ var ContextClient = class {
       }
       throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
     }
-    return response.json();
+    return response;
   }
 };
 
-export { ContextClient, ContextError, Discovery, Tools };
+export { ContextClient, ContextError, Discovery, Query, Tools };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map