@ctxprotocol/sdk 0.5.6 → 0.7.0

package/README.md

@@ -64,10 +64,36 @@ yarn add @ctxprotocol/sdk
 Before using the API, complete setup at [ctxprotocol.com](https://ctxprotocol.com):
 
 1. **Sign in** — Creates your embedded wallet
-2. **Enable Auto Pay** — Approve USDC spending for tool payments
+2. **Set spending cap** — Approve USDC spending on the ContextRouter (one-time setup)
 3. **Fund wallet** — Add USDC for tool execution fees
 4. **Generate API key** — In Settings page
 
+## Two Modes: Precision vs Intelligence
+
+The SDK offers two payment models to serve different use cases:
+
+| Mode | Method | Payment Model | Use Case |
+|------|--------|---------------|----------|
+| **Execute** | `client.tools.execute()` | Pay-per-request | Simple data fetches, predictable costs, building custom pipelines |
+| **Query** | `client.query.run()` | Pay-per-response | Complex questions, multi-tool synthesis, curated intelligence |
+
+**Execute mode** gives you raw data and full control — one tool, one call, one payment:
+```typescript
+const result = await client.tools.execute({
+  toolId: "tool-uuid",
+  toolName: "whale_transactions",
+  args: { chain: "base", limit: 20 },
+});
+```
+
+**Query mode** gives you curated answers — the server handles tool discovery, multi-tool orchestration (up to 100 MCP calls per tool), self-healing retries, and AI synthesis for one flat fee:
+```typescript
+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
+```
+
 ## Quick Start
 
 ```typescript
@@ -77,16 +103,17 @@ const client = new ContextClient({
   apiKey: "sk_live_...",
 });
 
-// Discover tools
-const tools = await client.discovery.search("gas prices");
+// 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);
 
-// Execute a tool
+// Pay-per-request: Execute a specific tool for raw data
+const tools = await client.discovery.search("gas prices");
 const result = await client.tools.execute({
   toolId: tools[0].id,
   toolName: tools[0].mcpTools[0].name,
   args: { chainId: 1 },
 });
-
 console.log(result.result);
 ```
 
@@ -265,11 +292,11 @@ Get featured/popular tools.
 const featured = await client.discovery.getFeatured(5);
 ```
 
-### Tools
+### Tools (Pay-Per-Request)
 
 #### `client.tools.execute(options)`
 
-Execute a tool method.
+Execute a single tool method. One call, one payment, raw result.
 
 ```typescript
 const result = await client.tools.execute({
@@ -279,6 +306,48 @@ const result = await client.tools.execute({
 });
 ```
 
+### Query (Pay-Per-Response)
+
+#### `client.query.run(options)`
+
+Run an agentic query. The server discovers tools, executes the full pipeline (up to 100 MCP calls per tool), and returns an AI-synthesized answer.
+
+```typescript
+// Simple string
+const answer = await client.query.run("What are the top whale movements on Base?");
+
+// With options
+const answer = await client.query.run({
+  query: "Analyze whale activity on Base",
+  tools: ["tool-uuid-1", "tool-uuid-2"],  // optional — auto-discover if omitted
+});
+
+console.log(answer.response);     // AI-synthesized text
+console.log(answer.toolsUsed);    // [{ id, name, skillCalls }]
+console.log(answer.cost);         // { modelCostUsd, toolCostUsd, totalCostUsd }
+console.log(answer.durationMs);   // Total time
+```
+
+#### `client.query.stream(options)`
+
+Same as `run()` but streams events in real-time via SSE.
+
+```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("\nTotal cost:", event.result.cost.totalCostUsd);
+      break;
+  }
+}
+```
+
 ## Types
 
 ```typescript
@@ -296,6 +365,11 @@ import type {
   McpTool,
   ExecuteOptions,
   ExecutionResult,
+  // Query types (pay-per-response)
+  QueryOptions,
+  QueryResult,
+  QueryCost,
+  QueryStreamEvent,
   ContextErrorCode,
   // Auth types (for MCP server contributors)
   VerifyRequestOptions,
@@ -333,7 +407,7 @@ interface McpTool {
 }
 ```
 
-### ExecutionResult
+### ExecutionResult (Pay-Per-Request)
 
 ```typescript
 interface ExecutionResult<T = unknown> {
@@ -343,6 +417,17 @@ interface ExecutionResult<T = unknown> {
 }
 ```
 
+### QueryResult (Pay-Per-Response)
+
+```typescript
+interface QueryResult {
+  response: string;                    // AI-synthesized answer
+  toolsUsed: QueryToolUsage[];         // Tools used: { id, name, skillCalls }
+  cost: QueryCost;                     // { modelCostUsd, toolCostUsd, totalCostUsd }
+  durationMs: number;
+}
+```
+
 ### Context Requirement Types (MCP Server Contributors)
 
 ```typescript
@@ -386,8 +471,8 @@ try {
         console.log("Setup required:", error.helpUrl);
         break;
       case "insufficient_allowance":
-        // User needs to enable Auto Pay
-        console.log("Enable Auto Pay:", error.helpUrl);
+        // User needs to set a spending cap
+        console.log("Set spending cap:", error.helpUrl);
         break;
       case "payment_failed":
         // Insufficient USDC balance
@@ -407,7 +492,7 @@ try {
 | ------------------------ | ---------------------------------------- | ----------------------------------- |
 | `unauthorized`           | Invalid API key                          | Check configuration                 |
 | `no_wallet`              | Wallet not set up                        | Direct user to `helpUrl`            |
-| `insufficient_allowance` | Auto Pay not enabled                     | Direct user to `helpUrl`            |
+| `insufficient_allowance` | Spending cap not set                     | Direct user to `helpUrl`            |
 | `payment_failed`         | USDC payment failed                      | Check balance                       |
 | `execution_failed`       | Tool error                               | Feed error to LLM for retry         |
 
@@ -426,7 +511,7 @@ By adding 1 line of code to verify a JWT, Context saves you from building:
 - Refund and dispute logic
 
 **The "Stripe Webhook" Analogy:**
-Developers are used to verifying signatures for Stripe Webhooks or GitHub Apps. Context works the same way. When we send a request saying "Execute Tool (Payment Confirmed)", you verify the signature. Without this, anyone could curl your endpoint and drain your resources.
+Developers are used to verifying signatures for Stripe Webhooks or GitHub Apps. Context works the same way. When we send a request saying "Execute Tool (Authorized)", you verify the signature. Without this, anyone could curl your endpoint and drain your resources.
 
 ### Quick Implementation (1 Line)
 
@@ -707,12 +792,13 @@ pnpm add -D @types/express
 
 ## Payment Flow
 
-When you execute a tool:
+Context uses **deferred settlement** — tools execute first, and payment is settled in the background after the result is returned:
 
-1. Your pre-approved USDC allowance is used
-2. **90%** goes to the tool developer
-3. **10%** goes to the protocol
-4. Tool executes and returns results
+1. Your USDC spending cap (ERC-20 allowance on ContextRouter) is verified
+2. Tool executes and returns results
+3. Payment is settled server-side via the operator wallet (no client-side transactions)
+4. **90%** goes to the tool developer, **10%** goes to the protocol
+5. If execution fails, tool fees are **waived** — you only pay for successful results
 
 ## Documentation
 

package/dist/client/index.cjs

@@ -1,13 +1,14 @@
 'use strict';
 
 // 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);
   }
 };
 
@@ -40,7 +41,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;
   }
   /**
@@ -74,8 +75,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
@@ -97,7 +98,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",
@@ -108,7 +109,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
       );
     }
@@ -123,18 +125,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
    *
@@ -150,14 +308,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,
@@ -182,13 +428,14 @@ var ContextClient = class {
       }
       throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
     }
-    return response.json();
+    return response;
   }
 };
 
 exports.ContextClient = ContextClient;
 exports.ContextError = ContextError;
 exports.Discovery = Discovery;
+exports.Query = Query;
 exports.Tools = Tools;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map