@ctxprotocol/sdk 0.6.0 → 0.8.0

package/README.md

@@ -64,10 +64,41 @@ 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, completeness checks, model-aware context budgeting, and AI synthesis for one flat fee:
+```typescript
+const answer = await client.query.run({
+  query: "What are the top whale movements on Base?",
+  modelId: "glm-model",      // optional: choose a supported model
+  includeDataUrl: true,      // optional: persist full execution data to blob
+});
+console.log(answer.response);   // AI-synthesized answer
+console.log(answer.toolsUsed);  // Which tools were used
+console.log(answer.cost);       // Cost breakdown
+console.log(answer.dataUrl);    // Optional blob URL with full data
+```
+
 ## Quick Start
 
 ```typescript
@@ -77,16 +108,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);
 ```
 
@@ -143,9 +175,18 @@ const result = await client.tools.execute({
   args: llmDecision.args,
 });
 
-// Feed the result back to your LLM for synthesis
+// Feed a bounded, structured summary back to your LLM for synthesis.
+// Prefer client.query.run() when you want server-managed synthesis.
+const resultPreview = JSON.stringify(result.result, null, 2).slice(0, 50_000);
+const resultKeys =
+  result.result && typeof result.result === "object"
+    ? Object.keys(result.result as Record<string, unknown>)
+    : [];
+
 const finalAnswer = await myLLM.generate(
-  `The tool returned: ${JSON.stringify(result.result)}. Summarize this for the user.`
+  `Tool output keys: ${resultKeys.join(", ") || "(non-object result)"}\n\n` +
+    `Tool output preview (truncated):\n${resultPreview}\n\n` +
+    "Summarize this for the user and mention if more data may exist beyond the preview."
 );
 ```
 
@@ -207,11 +248,17 @@ If you can answer without a tool, just respond normally.`;
         args: toolCall.args || {},
       });
 
-      // 6. Let LLM synthesize the result
+      // 6. Let LLM synthesize a bounded preview (avoid injecting giant JSON blobs)
+      const resultPreview = JSON.stringify(result.result, null, 2).slice(0, 50_000);
+      const resultKeys =
+        result.result && typeof result.result === "object"
+          ? Object.keys(result.result as Record<string, unknown>)
+          : [];
+
       return await myLLM.chat(
-        `Tool "${toolCall.toolName}" returned: ${JSON.stringify(result.result)}
-        
-Please provide a helpful response to the user's original question: "${userQuery}"`
+        `Tool "${toolCall.toolName}" returned keys: ${resultKeys.join(", ") || "(non-object result)"}\n\n` +
+        `Preview (truncated):\n${resultPreview}\n\n` +
+        `Please provide a helpful response to the user's original question: "${userQuery}"`
       );
     }
   } catch {
@@ -265,11 +312,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 +326,53 @@ 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), applies model-aware mediator/data budgeting, 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
+  modelId: "kimi-model-thinking",          // optional
+  includeData: true,                       // optional: include execution data inline
+  includeDataUrl: true,                    // optional: include blob URL for full data
+});
+
+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
+console.log(answer.data);         // Optional execution data (when includeData=true)
+console.log(answer.dataUrl);      // Optional blob URL (when includeDataUrl=true)
+```
+
+#### `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 +390,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 +432,7 @@ interface McpTool {
 }
 ```
 
-### ExecutionResult
+### ExecutionResult (Pay-Per-Request)
 
 ```typescript
 interface ExecutionResult<T = unknown> {
@@ -343,6 +442,19 @@ 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;
+  data?: unknown;                      // Optional execution data (includeData=true)
+  dataUrl?: string;                    // Optional blob URL (includeDataUrl=true)
+}
+```
+
 ### Context Requirement Types (MCP Server Contributors)
 
 ```typescript
@@ -386,8 +498,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 +519,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 +538,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 +819,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

@@ -75,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,11 +97,13 @@ var Tools = class {
    * ```
    */
   async execute(options) {
-    const { toolId, toolName, args } = options;
+    const { toolId, toolName, args, idempotencyKey } = 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 })
       }
     );
@@ -125,6 +127,165 @@ 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 headers = opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0;
+    const response = await this.client._fetch(
+      "/api/v1/query",
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          query: opts.query,
+          tools: opts.tools,
+          modelId: opts.modelId,
+          includeData: opts.includeData,
+          includeDataUrl: opts.includeDataUrl,
+          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,
+        data: response.data,
+        dataUrl: response.dataUrl
+      };
+    }
+    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 headers = opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0;
+    const response = await this.client._fetchRaw("/api/v1/query", {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        query: opts.query,
+        tools: opts.tools,
+        modelId: opts.modelId,
+        includeData: opts.includeData,
+        includeDataUrl: opts.includeDataUrl,
+        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;
@@ -135,9 +296,17 @@ var ContextClient = class {
    */
   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
    *
@@ -153,6 +322,7 @@ 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.
@@ -238,11 +408,48 @@ var ContextClient = class {
     }
     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,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      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;
+  }
 };
 
 exports.ContextClient = ContextClient;
 exports.ContextError = ContextError;
 exports.Discovery = Discovery;
+exports.Query = Query;
 exports.Tools = Tools;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/client/types.ts","../../src/client/resources/discovery.ts","../../src/client/resources/tools.ts","../../src/client/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Configuration options for initializing the ContextClient\n */\nexport interface ContextClientOptions {\n  /**\n   * Your Context Protocol API key\n   * @example \"sk_live_abc123...\"\n   */\n  apiKey: string;\n\n  /**\n   * Base URL for the Context Protocol API\n   * @default \"https://ctxprotocol.com\"\n   */\n  baseUrl?: string;\n}\n\n/**\n * An individual MCP tool exposed by a tool listing\n */\nexport interface McpTool {\n  /** Name of the MCP tool method */\n  name: string;\n\n  /** Description of what this method does */\n  description: string;\n\n  /**\n   * JSON Schema for the input arguments this tool accepts.\n   * Used by LLMs to generate correct arguments.\n   */\n  inputSchema?: Record<string, unknown>;\n\n  /**\n   * JSON Schema for the output this tool returns.\n   * Used by LLMs to understand the response structure.\n   */\n  outputSchema?: Record<string, unknown>;\n}\n\n/**\n * Represents a tool available on the Context Protocol marketplace\n */\nexport interface Tool {\n  /** Unique identifier for the tool (UUID) */\n  id: string;\n\n  /** Human-readable name of the tool */\n  name: string;\n\n  /** Description of what the tool does */\n  description: string;\n\n  /** Price per execution in USDC */\n  price: string;\n\n  /** Tool category (e.g., \"defi\", \"nft\") */\n  category?: string;\n\n  /** Whether the tool is verified by Context Protocol */\n  isVerified?: boolean;\n\n  /** Tool type - currently always \"mcp\" */\n  kind?: string;\n\n  /**\n   * Available MCP tool methods\n   * Use items from this array as `toolName` when executing\n   */\n  mcpTools?: McpTool[];\n\n  // Trust metrics (Level 2 - Reputation Ledger)\n  /** Total number of queries processed */\n  totalQueries?: number;\n\n  /** Success rate percentage (0-100) */\n  successRate?: string;\n\n  /** Uptime percentage (0-100) */\n  uptimePercent?: string;\n\n  /** Total USDC staked by the developer */\n  totalStaked?: string;\n\n  /** Whether the tool has \"Proven\" status (100+ queries, >95% success, >98% uptime) */\n  isProven?: boolean;\n}\n\n/**\n * Response from the tools search endpoint\n */\nexport interface SearchResponse {\n  /** Array of matching tools */\n  tools: Tool[];\n\n  /** The search query that was used */\n  query: string;\n\n  /** Total number of results */\n  count: number;\n}\n\n/**\n * Options for searching tools\n */\nexport interface SearchOptions {\n  /** Search query (semantic search) */\n  query?: string;\n\n  /** Maximum number of results (1-50, default 10) */\n  limit?: number;\n}\n\n/**\n * Options for executing a tool\n */\nexport interface ExecuteOptions {\n  /** The UUID of the tool to execute (from search results) */\n  toolId: string;\n\n  /** The specific MCP tool name to call (from tool's mcpTools array) */\n  toolName: string;\n\n  /** Arguments to pass to the tool */\n  args?: Record<string, unknown>;\n}\n\n/**\n * Successful execution response from the API\n */\nexport interface ExecuteApiSuccessResponse {\n  success: true;\n\n  /** The result data from the tool execution */\n  result: unknown;\n\n  /** Information about the executed tool */\n  tool: {\n    id: string;\n    name: string;\n  };\n\n  /** Execution duration in milliseconds */\n  durationMs: number;\n}\n\n/**\n * Error response from the API\n */\nexport interface ExecuteApiErrorResponse {\n  /** Human-readable error message */\n  error: string;\n\n  /** Error code for programmatic handling */\n  code?: ContextErrorCode;\n\n  /** URL to help resolve the issue */\n  helpUrl?: string;\n}\n\n/**\n * Raw API response from the execute endpoint\n */\nexport type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;\n\n/**\n * The resolved result returned to the user after SDK processing\n */\nexport interface ExecutionResult<T = unknown> {\n  /** The data returned by the tool */\n  result: T;\n\n  /** Information about the executed tool */\n  tool: {\n    id: string;\n    name: string;\n  };\n\n  /** Execution duration in milliseconds */\n  durationMs: number;\n}\n\n/**\n * Specific error codes returned by the Context Protocol API\n */\nexport type ContextErrorCode =\n  | \"unauthorized\"\n  | \"no_wallet\"\n  | \"insufficient_allowance\"\n  | \"payment_failed\"\n  | \"execution_failed\";\n\n/**\n * Error thrown by the Context Protocol client\n */\nexport class ContextError extends Error {\n  constructor(\n    message: string,\n    public readonly code?: ContextErrorCode | string,\n    public readonly statusCode?: number,\n    public readonly helpUrl?: string\n  ) {\n    super(message);\n    this.name = \"ContextError\";\n    Object.setPrototypeOf(this, ContextError.prototype);\n  }\n}\n","import type { Tool, SearchResponse } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Discovery resource for searching and finding tools on the Context Protocol marketplace\n */\nexport class Discovery {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Search for tools matching a query string\n   *\n   * @param query - The search query (e.g., \"gas prices\", \"nft metadata\")\n   * @param limit - Maximum number of results (1-50, default 10)\n   * @returns Array of matching tools\n   *\n   * @example\n   * ```typescript\n   * const tools = await client.discovery.search(\"gas prices\");\n   * console.log(tools[0].name); // \"Gas Price Oracle\"\n   * console.log(tools[0].mcpTools); // Available methods\n   * ```\n   */\n  async search(query: string, limit?: number): Promise<Tool[]> {\n    const params = new URLSearchParams();\n\n    if (query) {\n      params.set(\"q\", query);\n    }\n\n    if (limit !== undefined) {\n      params.set(\"limit\", String(limit));\n    }\n\n    const queryString = params.toString();\n    const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : \"\"}`;\n\n    const response = await this.client._fetch<SearchResponse>(endpoint);\n\n    return response.tools;\n  }\n\n  /**\n   * Get featured/popular tools (empty query search)\n   *\n   * @param limit - Maximum number of results (1-50, default 10)\n   * @returns Array of featured tools\n   *\n   * @example\n   * ```typescript\n   * const featured = await client.discovery.getFeatured(5);\n   * ```\n   */\n  async getFeatured(limit?: number): Promise<Tool[]> {\n    return this.search(\"\", limit);\n  }\n}\n","import type {\n  ExecuteOptions,\n  ExecuteApiResponse,\n  ExecutionResult,\n} from \"../types.js\";\nimport { ContextError } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Tools resource for executing tools on the Context Protocol marketplace\n */\nexport class Tools {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Execute a tool with the provided arguments\n   *\n   * @param options - Execution options\n   * @param options.toolId - The UUID of the tool (from search results)\n   * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)\n   * @param options.args - Arguments to pass to the tool\n   * @returns The execution result with the tool's output data\n   *\n   * @throws {ContextError} With code `no_wallet` if wallet not set up\n   * @throws {ContextError} With code `insufficient_allowance` if Auto Pay not enabled\n   * @throws {ContextError} With code `payment_failed` if on-chain payment fails\n   * @throws {ContextError} With code `execution_failed` if tool execution fails\n   *\n   * @example\n   * ```typescript\n   * // First, search for a tool\n   * const tools = await client.discovery.search(\"gas prices\");\n   * const tool = tools[0];\n   *\n   * // Execute a specific method from the tool's mcpTools\n   * const result = await client.tools.execute({\n   *   toolId: tool.id,\n   *   toolName: tool.mcpTools[0].name, // e.g., \"get_gas_prices\"\n   *   args: { chainId: 1 }\n   * });\n   *\n   * console.log(result.result); // The tool's output\n   * console.log(result.durationMs); // Execution time\n   * ```\n   */\n  async execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>> {\n    const { toolId, toolName, args } = options;\n\n    const response = await this.client._fetch<ExecuteApiResponse>(\n      \"/api/v1/tools/execute\",\n      {\n        method: \"POST\",\n        body: JSON.stringify({ toolId, toolName, args }),\n      }\n    );\n\n    // Handle error response\n    if (\"error\" in response) {\n      throw new ContextError(\n        response.error,\n        response.code,\n        undefined, // Don't hardcode - this was a 200 OK with error body\n        response.helpUrl\n      );\n    }\n\n    // Handle success response\n    if (response.success) {\n      return {\n        result: response.result as T,\n        tool: response.tool,\n        durationMs: response.durationMs,\n      };\n    }\n\n    // Fallback - shouldn't reach here with valid API responses\n    throw new ContextError(\"Unexpected response format from API\");\n  }\n}\n","import type { ContextClientOptions } from \"./types.js\";\nimport { ContextError } from \"./types.js\";\nimport { Discovery } from \"./resources/discovery.js\";\nimport { Tools } from \"./resources/tools.js\";\n\n/**\n * The official TypeScript client for the Context Protocol.\n *\n * Use this client to discover and execute AI tools programmatically.\n *\n * @example\n * ```typescript\n * import { ContextClient } from \"@contextprotocol/client\";\n *\n * const client = new ContextClient({\n *   apiKey: \"sk_live_...\"\n * });\n *\n * // Discover tools\n * const tools = await client.discovery.search(\"gas prices\");\n *\n * // Execute a tool method\n * const result = await client.tools.execute({\n *   toolId: tools[0].id,\n *   toolName: tools[0].mcpTools[0].name,\n *   args: { chainId: 1 }\n * });\n * ```\n */\nexport class ContextClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private _closed = false;\n\n  /**\n   * Discovery resource for searching tools\n   */\n  public readonly discovery: Discovery;\n\n  /**\n   * Tools resource for executing tools\n   */\n  public readonly tools: Tools;\n\n  /**\n   * Creates a new Context Protocol client\n   *\n   * @param options - Client configuration options\n   * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)\n   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)\n   */\n  constructor(options: ContextClientOptions) {\n    if (!options.apiKey) {\n      throw new ContextError(\"API key is required\");\n    }\n\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? \"https://ctxprotocol.com\").replace(/\\/$/, \"\");\n\n    // Initialize resources\n    this.discovery = new Discovery(this);\n    this.tools = new Tools(this);\n  }\n\n  /**\n   * Close the client and clean up resources.\n   * After calling close(), any in-flight requests may be aborted.\n   */\n  close(): void {\n    this._closed = true;\n  }\n\n  /**\n   * Internal method for making authenticated HTTP requests\n   * Includes timeout (30s) and retry with exponential backoff for transient errors\n   *\n   * @internal\n   */\n  async _fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {\n    if (this._closed) {\n      throw new ContextError(\"Client has been closed\");\n    }\n\n    const url = `${this.baseUrl}${endpoint}`;\n    const maxRetries = 3;\n    const timeoutMs = 30_000;\n\n    let lastError: Error | undefined;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt++) {\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), timeoutMs);\n\n      try {\n        const response = await fetch(url, {\n          ...options,\n          signal: controller.signal,\n          headers: {\n            \"Content-Type\": \"application/json\",\n            Authorization: `Bearer ${this.apiKey}`,\n            ...options.headers,\n          },\n        });\n\n        clearTimeout(timeout);\n\n        if (!response.ok) {\n          // Retry on 5xx server errors\n          if (response.status >= 500 && attempt < maxRetries) {\n            const delay = Math.min(1000 * 2 ** attempt, 10_000);\n            await new Promise((resolve) => setTimeout(resolve, delay));\n            continue;\n          }\n\n          let errorMessage = `HTTP ${response.status}: ${response.statusText}`;\n          let errorCode: string | undefined;\n          let helpUrl: string | undefined;\n\n          try {\n            const errorBody = await response.json();\n            if (errorBody.error) {\n              errorMessage = errorBody.error;\n              errorCode = errorBody.code;\n              helpUrl = errorBody.helpUrl;\n            }\n          } catch {\n            // Use default error message if JSON parsing fails\n          }\n\n          throw new ContextError(errorMessage, errorCode, response.status, helpUrl);\n        }\n\n        return response.json() as Promise<T>;\n      } catch (error) {\n        clearTimeout(timeout);\n\n        if (error instanceof ContextError) {\n          throw error;\n        }\n\n        lastError = error instanceof Error ? error : new Error(String(error));\n\n        // Retry on network errors and timeouts\n        const isRetryable =\n          lastError.name === \"AbortError\" ||\n          lastError.message.includes(\"fetch failed\") ||\n          lastError.message.includes(\"ECONNRESET\") ||\n          lastError.message.includes(\"ETIMEDOUT\");\n\n        if (isRetryable && attempt < maxRetries) {\n          const delay = Math.min(1000 * 2 ** attempt, 10_000);\n          await new Promise((resolve) => setTimeout(resolve, delay));\n          continue;\n        }\n\n        if (lastError.name === \"AbortError\") {\n          throw new ContextError(\n            `Request timed out after ${timeoutMs / 1000}s`,\n            undefined,\n            408\n          );\n        }\n\n        throw new ContextError(\n          lastError.message,\n          undefined,\n          undefined\n        );\n      }\n    }\n\n    throw lastError ?? new ContextError(\"Request failed after retries\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/client/types.ts","../../src/client/resources/discovery.ts","../../src/client/resources/tools.ts","../../src/client/resources/query.ts","../../src/client/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Configuration options for initializing the ContextClient\n */\nexport interface ContextClientOptions {\n  /**\n   * Your Context Protocol API key\n   * @example \"sk_live_abc123...\"\n   */\n  apiKey: string;\n\n  /**\n   * Base URL for the Context Protocol API\n   * @default \"https://ctxprotocol.com\"\n   */\n  baseUrl?: string;\n}\n\n/**\n * An individual MCP tool exposed by a tool listing\n */\nexport interface McpTool {\n  /** Name of the MCP tool method */\n  name: string;\n\n  /** Description of what this method does */\n  description: string;\n\n  /**\n   * JSON Schema for the input arguments this tool accepts.\n   * Used by LLMs to generate correct arguments.\n   */\n  inputSchema?: Record<string, unknown>;\n\n  /**\n   * JSON Schema for the output this tool returns.\n   * Used by LLMs to understand the response structure.\n   */\n  outputSchema?: Record<string, unknown>;\n}\n\n/**\n * Represents a tool available on the Context Protocol marketplace\n */\nexport interface Tool {\n  /** Unique identifier for the tool (UUID) */\n  id: string;\n\n  /** Human-readable name of the tool */\n  name: string;\n\n  /** Description of what the tool does */\n  description: string;\n\n  /** Price per execution in USDC */\n  price: string;\n\n  /** Tool category (e.g., \"defi\", \"nft\") */\n  category?: string;\n\n  /** Whether the tool is verified by Context Protocol */\n  isVerified?: boolean;\n\n  /** Tool type - currently always \"mcp\" */\n  kind?: string;\n\n  /**\n   * Available MCP tool methods\n   * Use items from this array as `toolName` when executing\n   */\n  mcpTools?: McpTool[];\n\n  // Trust metrics (Level 2 - Reputation Ledger)\n  /** Total number of queries processed */\n  totalQueries?: number;\n\n  /** Success rate percentage (0-100) */\n  successRate?: string;\n\n  /** Uptime percentage (0-100) */\n  uptimePercent?: string;\n\n  /** Total USDC staked by the developer */\n  totalStaked?: string;\n\n  /** Whether the tool has \"Proven\" status (100+ queries, >95% success, >98% uptime) */\n  isProven?: boolean;\n}\n\n/**\n * Response from the tools search endpoint\n */\nexport interface SearchResponse {\n  /** Array of matching tools */\n  tools: Tool[];\n\n  /** The search query that was used */\n  query: string;\n\n  /** Total number of results */\n  count: number;\n}\n\n/**\n * Options for searching tools\n */\nexport interface SearchOptions {\n  /** Search query (semantic search) */\n  query?: string;\n\n  /** Maximum number of results (1-50, default 10) */\n  limit?: number;\n}\n\n/**\n * Options for executing a tool\n */\nexport interface ExecuteOptions {\n  /** The UUID of the tool to execute (from search results) */\n  toolId: string;\n\n  /** The specific MCP tool name to call (from tool's mcpTools array) */\n  toolName: string;\n\n  /** Arguments to pass to the tool */\n  args?: Record<string, unknown>;\n\n  /**\n   * Optional idempotency key (UUID recommended).\n   * Reuse the same key when retrying the same logical request.\n   */\n  idempotencyKey?: string;\n}\n\n/**\n * Successful execution response from the API\n */\nexport interface ExecuteApiSuccessResponse {\n  success: true;\n\n  /** The result data from the tool execution */\n  result: unknown;\n\n  /** Information about the executed tool */\n  tool: {\n    id: string;\n    name: string;\n  };\n\n  /** Execution duration in milliseconds */\n  durationMs: number;\n}\n\n/**\n * Error response from the API\n */\nexport interface ExecuteApiErrorResponse {\n  /** Human-readable error message */\n  error: string;\n\n  /** Error code for programmatic handling */\n  code?: ContextErrorCode;\n\n  /** URL to help resolve the issue */\n  helpUrl?: string;\n}\n\n/**\n * Raw API response from the execute endpoint\n */\nexport type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;\n\n/**\n * The resolved result returned to the user after SDK processing\n */\nexport interface ExecutionResult<T = unknown> {\n  /** The data returned by the tool */\n  result: T;\n\n  /** Information about the executed tool */\n  tool: {\n    id: string;\n    name: string;\n  };\n\n  /** Execution duration in milliseconds */\n  durationMs: number;\n}\n\n// ---------------------------------------------------------------------------\n// Query types (pay-per-response / agentic mode)\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the agentic query endpoint (pay-per-response).\n *\n * Unlike `execute()` which calls a single tool once, `query()` sends a\n * natural-language question and lets the server handle tool discovery,\n * multi-tool orchestration, self-healing retries, and AI synthesis.\n * One flat fee covers up to 100 MCP skill calls per tool.\n */\nexport interface QueryOptions {\n  /** The natural-language question to answer */\n  query: string;\n\n  /**\n   * Optional tool IDs to use. When omitted the server discovers tools\n   * automatically (Auto Mode). When provided, only these tools are used\n   * (Manual Mode).\n   */\n  tools?: string[];\n\n  /**\n   * Optional model ID for query orchestration/synthesis.\n   * Supported IDs are published by the Context API.\n   */\n  modelId?: string;\n\n  /**\n   * Include execution data inline in the query response.\n   * Useful for headless agents that need raw structured outputs.\n   */\n  includeData?: boolean;\n\n  /**\n   * Persist execution data to Vercel Blob and return a download URL.\n   * Useful for large payload workflows where inline JSON is not ideal.\n   */\n  includeDataUrl?: boolean;\n\n  /**\n   * Optional idempotency key (UUID recommended).\n   * Reuse the same key when retrying the same logical request.\n   */\n  idempotencyKey?: string;\n}\n\n/**\n * Information about a tool that was used during a query response\n */\nexport interface QueryToolUsage {\n  /** Tool ID */\n  id: string;\n\n  /** Tool name */\n  name: string;\n\n  /** Number of MCP skill calls made for this tool */\n  skillCalls: number;\n}\n\n/**\n * Cost breakdown for a query response.\n * All values are strings representing USD amounts.\n */\nexport interface QueryCost {\n  /** AI model inference cost */\n  modelCostUsd: string;\n\n  /** Sum of all tool fees */\n  toolCostUsd: string;\n\n  /** Total cost (model + tools) */\n  totalCostUsd: string;\n}\n\n/**\n * The resolved result of a pay-per-response query\n */\nexport interface QueryResult {\n  /** The AI-synthesized response text */\n  response: string;\n\n  /** Tools that were used to answer the query */\n  toolsUsed: QueryToolUsage[];\n\n  /** Cost breakdown */\n  cost: QueryCost;\n\n  /** Total duration in milliseconds */\n  durationMs: number;\n\n  /** Optional execution data from tools (when includeData=true) */\n  data?: unknown;\n\n  /** Optional blob URL for persisted execution data (when includeDataUrl=true) */\n  dataUrl?: string;\n}\n\n/**\n * Successful response from the /api/v1/query endpoint\n */\nexport interface QueryApiSuccessResponse {\n  success: true;\n  response: string;\n  toolsUsed: QueryToolUsage[];\n  cost: QueryCost;\n  durationMs: number;\n  data?: unknown;\n  dataUrl?: string;\n}\n\n/**\n * Raw API response from the query endpoint\n */\nexport type QueryApiResponse = QueryApiSuccessResponse | ExecuteApiErrorResponse;\n\n// ---------------------------------------------------------------------------\n// Query stream event types\n// ---------------------------------------------------------------------------\n\n/** Emitted when a tool starts or changes execution status */\nexport interface QueryStreamToolStatusEvent {\n  type: \"tool-status\";\n  tool: { id: string; name: string };\n  status: string;\n}\n\n/** Emitted for each chunk of the AI response text */\nexport interface QueryStreamTextDeltaEvent {\n  type: \"text-delta\";\n  delta: string;\n}\n\n/** Emitted when the full response is complete */\nexport interface QueryStreamDoneEvent {\n  type: \"done\";\n  result: QueryResult;\n}\n\n/**\n * Union of all events emitted during a streaming query\n */\nexport type QueryStreamEvent =\n  | QueryStreamToolStatusEvent\n  | QueryStreamTextDeltaEvent\n  | QueryStreamDoneEvent;\n\n// ---------------------------------------------------------------------------\n// Error types\n// ---------------------------------------------------------------------------\n\n/**\n * Specific error codes returned by the Context Protocol API\n */\nexport type ContextErrorCode =\n  | \"unauthorized\"\n  | \"no_wallet\"\n  | \"insufficient_allowance\"\n  | \"payment_failed\"\n  | \"execution_failed\"\n  | \"query_failed\";\n\n/**\n * Error thrown by the Context Protocol client\n */\nexport class ContextError extends Error {\n  constructor(\n    message: string,\n    public readonly code?: ContextErrorCode | string,\n    public readonly statusCode?: number,\n    public readonly helpUrl?: string\n  ) {\n    super(message);\n    this.name = \"ContextError\";\n    Object.setPrototypeOf(this, ContextError.prototype);\n  }\n}\n","import type { Tool, SearchResponse } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Discovery resource for searching and finding tools on the Context Protocol marketplace\n */\nexport class Discovery {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Search for tools matching a query string\n   *\n   * @param query - The search query (e.g., \"gas prices\", \"nft metadata\")\n   * @param limit - Maximum number of results (1-50, default 10)\n   * @returns Array of matching tools\n   *\n   * @example\n   * ```typescript\n   * const tools = await client.discovery.search(\"gas prices\");\n   * console.log(tools[0].name); // \"Gas Price Oracle\"\n   * console.log(tools[0].mcpTools); // Available methods\n   * ```\n   */\n  async search(query: string, limit?: number): Promise<Tool[]> {\n    const params = new URLSearchParams();\n\n    if (query) {\n      params.set(\"q\", query);\n    }\n\n    if (limit !== undefined) {\n      params.set(\"limit\", String(limit));\n    }\n\n    const queryString = params.toString();\n    const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : \"\"}`;\n\n    const response = await this.client._fetch<SearchResponse>(endpoint);\n\n    return response.tools;\n  }\n\n  /**\n   * Get featured/popular tools (empty query search)\n   *\n   * @param limit - Maximum number of results (1-50, default 10)\n   * @returns Array of featured tools\n   *\n   * @example\n   * ```typescript\n   * const featured = await client.discovery.getFeatured(5);\n   * ```\n   */\n  async getFeatured(limit?: number): Promise<Tool[]> {\n    return this.search(\"\", limit);\n  }\n}\n","import type {\n  ExecuteOptions,\n  ExecuteApiResponse,\n  ExecutionResult,\n} from \"../types.js\";\nimport { ContextError } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Tools resource for executing tools on the Context Protocol marketplace\n */\nexport class Tools {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Execute a tool with the provided arguments\n   *\n   * @param options - Execution options\n   * @param options.toolId - The UUID of the tool (from search results)\n   * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)\n   * @param options.args - Arguments to pass to the tool\n   * @returns The execution result with the tool's output data\n   *\n   * @throws {ContextError} With code `no_wallet` if wallet not set up\n   * @throws {ContextError} With code `insufficient_allowance` if spending cap not set\n   * @throws {ContextError} With code `payment_failed` if payment settlement fails\n   * @throws {ContextError} With code `execution_failed` if tool execution fails\n   *\n   * @example\n   * ```typescript\n   * // First, search for a tool\n   * const tools = await client.discovery.search(\"gas prices\");\n   * const tool = tools[0];\n   *\n   * // Execute a specific method from the tool's mcpTools\n   * const result = await client.tools.execute({\n   *   toolId: tool.id,\n   *   toolName: tool.mcpTools[0].name, // e.g., \"get_gas_prices\"\n   *   args: { chainId: 1 }\n   * });\n   *\n   * console.log(result.result); // The tool's output\n   * console.log(result.durationMs); // Execution time\n   * ```\n   */\n  async execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>> {\n    const { toolId, toolName, args, idempotencyKey } = options;\n    const headers = idempotencyKey\n      ? { \"Idempotency-Key\": idempotencyKey }\n      : undefined;\n\n    const response = await this.client._fetch<ExecuteApiResponse>(\n      \"/api/v1/tools/execute\",\n      {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({ toolId, toolName, args }),\n      }\n    );\n\n    // Handle error response\n    if (\"error\" in response) {\n      throw new ContextError(\n        response.error,\n        response.code,\n        undefined, // Don't hardcode - this was a 200 OK with error body\n        response.helpUrl\n      );\n    }\n\n    // Handle success response\n    if (response.success) {\n      return {\n        result: response.result as T,\n        tool: response.tool,\n        durationMs: response.durationMs,\n      };\n    }\n\n    // Fallback - shouldn't reach here with valid API responses\n    throw new ContextError(\"Unexpected response format from API\");\n  }\n}\n","import type {\n  QueryOptions,\n  QueryApiResponse,\n  QueryResult,\n  QueryStreamEvent,\n} from \"../types.js\";\nimport { ContextError } from \"../types.js\";\nimport type { ContextClient } from \"../client.js\";\n\n/**\n * Query resource for pay-per-response agentic queries.\n *\n * Unlike `tools.execute()` which calls a single tool once (pay-per-request),\n * the Query resource sends a natural-language question and lets the server\n * handle tool discovery, multi-tool orchestration, self-healing retries,\n * completeness checks, and AI synthesis — all for one flat fee.\n *\n * This is the \"prepared meal\" vs \"raw ingredients\" distinction:\n * - `tools.execute()` = raw data, full control, predictable cost\n * - `query.run()` / `query.stream()` = curated intelligence, one payment\n */\nexport class Query {\n  constructor(private client: ContextClient) {}\n\n  /**\n   * Run an agentic query and wait for the full response.\n   *\n   * The server discovers relevant tools (or uses the ones you specify),\n   * executes the full agentic pipeline (up to 100 MCP calls per tool),\n   * and returns an AI-synthesized answer. Payment is settled after\n   * successful execution via deferred settlement.\n   *\n   * @param options - Query options or a plain string question\n   * @returns The complete query result with response text, tools used, and cost\n   *\n   * @throws {ContextError} With code `no_wallet` if wallet not set up\n   * @throws {ContextError} With code `insufficient_allowance` if spending cap not set\n   * @throws {ContextError} With code `payment_failed` if payment settlement fails\n   * @throws {ContextError} With code `execution_failed` if the agentic pipeline fails\n   *\n   * @example\n   * ```typescript\n   * // Simple question — server discovers tools automatically\n   * const answer = await client.query.run(\"What are the top whale movements on Base?\");\n   * console.log(answer.response);      // AI-synthesized answer\n   * console.log(answer.toolsUsed);     // Which tools were used\n   * console.log(answer.cost);          // Cost breakdown\n   *\n   * // With specific tools (Manual Mode)\n   * const answer = await client.query.run({\n   *   query: \"Analyze whale activity\",\n   *   tools: [\"tool-uuid-1\", \"tool-uuid-2\"],\n   * });\n   * ```\n   */\n  async run(options: QueryOptions | string): Promise<QueryResult> {\n    const opts = typeof options === \"string\" ? { query: options } : options;\n    const headers = opts.idempotencyKey\n      ? { \"Idempotency-Key\": opts.idempotencyKey }\n      : undefined;\n\n    const response = await this.client._fetch<QueryApiResponse>(\n      \"/api/v1/query\",\n      {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({\n          query: opts.query,\n          tools: opts.tools,\n          modelId: opts.modelId,\n          includeData: opts.includeData,\n          includeDataUrl: opts.includeDataUrl,\n          stream: false,\n        }),\n      }\n    );\n\n    // Handle error response\n    if (\"error\" in response) {\n      throw new ContextError(\n        response.error,\n        response.code,\n        undefined,\n        response.helpUrl\n      );\n    }\n\n    // Handle success response\n    if (response.success) {\n      return {\n        response: response.response,\n        toolsUsed: response.toolsUsed,\n        cost: response.cost,\n        durationMs: response.durationMs,\n        data: response.data,\n        dataUrl: response.dataUrl,\n      };\n    }\n\n    throw new ContextError(\"Unexpected response format from query API\");\n  }\n\n  /**\n   * Run an agentic query with streaming. Returns an async iterable that\n   * yields events as the server processes the query in real-time.\n   *\n   * Event types:\n   * - `tool-status` — A tool started executing or changed status\n   * - `text-delta` — A chunk of the AI response text\n   * - `done` — The full response is complete (includes final `QueryResult`)\n   *\n   * @param options - Query options or a plain string question\n   * @returns An async iterable of stream events\n   *\n   * @example\n   * ```typescript\n   * for await (const event of client.query.stream(\"What are the top whale movements?\")) {\n   *   switch (event.type) {\n   *     case \"tool-status\":\n   *       console.log(`Tool ${event.tool.name}: ${event.status}`);\n   *       break;\n   *     case \"text-delta\":\n   *       process.stdout.write(event.delta);\n   *       break;\n   *     case \"done\":\n   *       console.log(\"\\nCost:\", event.result.cost.totalCostUsd);\n   *       break;\n   *   }\n   * }\n   * ```\n   */\n  async *stream(\n    options: QueryOptions | string\n  ): AsyncGenerator<QueryStreamEvent> {\n    const opts = typeof options === \"string\" ? { query: options } : options;\n    const headers = opts.idempotencyKey\n      ? { \"Idempotency-Key\": opts.idempotencyKey }\n      : undefined;\n\n    const response = await this.client._fetchRaw(\"/api/v1/query\", {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify({\n        query: opts.query,\n        tools: opts.tools,\n        modelId: opts.modelId,\n        includeData: opts.includeData,\n        includeDataUrl: opts.includeDataUrl,\n        stream: true,\n      }),\n    });\n\n    const body = response.body;\n    if (!body) {\n      throw new ContextError(\"No response body for streaming query\");\n    }\n\n    const reader = body.getReader();\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n\n        for (const line of lines) {\n          const trimmed = line.trim();\n          if (trimmed.startsWith(\"data: \")) {\n            const data = trimmed.slice(6);\n            if (data === \"[DONE]\") return;\n            try {\n              yield JSON.parse(data) as QueryStreamEvent;\n            } catch {\n              // Skip malformed SSE events\n            }\n          }\n        }\n      }\n\n      // Process any remaining buffer\n      if (buffer.trim().startsWith(\"data: \")) {\n        const data = buffer.trim().slice(6);\n        if (data !== \"[DONE]\") {\n          try {\n            yield JSON.parse(data) as QueryStreamEvent;\n          } catch {\n            // Skip malformed SSE events\n          }\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n","import type { ContextClientOptions } from \"./types.js\";\nimport { ContextError } from \"./types.js\";\nimport { Discovery } from \"./resources/discovery.js\";\nimport { Tools } from \"./resources/tools.js\";\nimport { Query } from \"./resources/query.js\";\n\n/**\n * The official TypeScript client for the Context Protocol.\n *\n * Use this client to discover and execute AI tools programmatically.\n *\n * @example\n * ```typescript\n * import { ContextClient } from \"@contextprotocol/client\";\n *\n * const client = new ContextClient({\n *   apiKey: \"sk_live_...\"\n * });\n *\n * // Pay-per-request: Execute a specific tool\n * const result = await client.tools.execute({\n *   toolId: \"tool-uuid\",\n *   toolName: \"get_gas_prices\",\n *   args: { chainId: 1 }\n * });\n *\n * // Pay-per-response: Ask a question, get a curated answer\n * const answer = await client.query.run(\"What are the top whale movements on Base?\");\n * console.log(answer.response);\n * ```\n */\nexport class ContextClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private _closed = false;\n\n  /**\n   * Discovery resource for searching tools\n   */\n  public readonly discovery: Discovery;\n\n  /**\n   * Tools resource for executing tools (pay-per-request)\n   */\n  public readonly tools: Tools;\n\n  /**\n   * Query resource for agentic queries (pay-per-response).\n   *\n   * Unlike `tools.execute()` which calls a single tool once, `query` sends\n   * a natural-language question and lets the server handle tool discovery,\n   * multi-tool orchestration, self-healing, and AI synthesis — one flat fee.\n   */\n  public readonly query: Query;\n\n  /**\n   * Creates a new Context Protocol client\n   *\n   * @param options - Client configuration options\n   * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)\n   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)\n   */\n  constructor(options: ContextClientOptions) {\n    if (!options.apiKey) {\n      throw new ContextError(\"API key is required\");\n    }\n\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? \"https://ctxprotocol.com\").replace(/\\/$/, \"\");\n\n    // Initialize resources\n    this.discovery = new Discovery(this);\n    this.tools = new Tools(this);\n    this.query = new Query(this);\n  }\n\n  /**\n   * Close the client and clean up resources.\n   * After calling close(), any in-flight requests may be aborted.\n   */\n  close(): void {\n    this._closed = true;\n  }\n\n  /**\n   * Internal method for making authenticated HTTP requests\n   * Includes timeout (30s) and retry with exponential backoff for transient errors\n   *\n   * @internal\n   */\n  async _fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {\n    if (this._closed) {\n      throw new ContextError(\"Client has been closed\");\n    }\n\n    const url = `${this.baseUrl}${endpoint}`;\n    const maxRetries = 3;\n    const timeoutMs = 30_000;\n\n    let lastError: Error | undefined;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt++) {\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), timeoutMs);\n\n      try {\n        const response = await fetch(url, {\n          ...options,\n          signal: controller.signal,\n          headers: {\n            \"Content-Type\": \"application/json\",\n            Authorization: `Bearer ${this.apiKey}`,\n            ...options.headers,\n          },\n        });\n\n        clearTimeout(timeout);\n\n        if (!response.ok) {\n          // Retry on 5xx server errors\n          if (response.status >= 500 && attempt < maxRetries) {\n            const delay = Math.min(1000 * 2 ** attempt, 10_000);\n            await new Promise((resolve) => setTimeout(resolve, delay));\n            continue;\n          }\n\n          let errorMessage = `HTTP ${response.status}: ${response.statusText}`;\n          let errorCode: string | undefined;\n          let helpUrl: string | undefined;\n\n          try {\n            const errorBody = await response.json();\n            if (errorBody.error) {\n              errorMessage = errorBody.error;\n              errorCode = errorBody.code;\n              helpUrl = errorBody.helpUrl;\n            }\n          } catch {\n            // Use default error message if JSON parsing fails\n          }\n\n          throw new ContextError(errorMessage, errorCode, response.status, helpUrl);\n        }\n\n        return response.json() as Promise<T>;\n      } catch (error) {\n        clearTimeout(timeout);\n\n        if (error instanceof ContextError) {\n          throw error;\n        }\n\n        lastError = error instanceof Error ? error : new Error(String(error));\n\n        // Retry on network errors and timeouts\n        const isRetryable =\n          lastError.name === \"AbortError\" ||\n          lastError.message.includes(\"fetch failed\") ||\n          lastError.message.includes(\"ECONNRESET\") ||\n          lastError.message.includes(\"ETIMEDOUT\");\n\n        if (isRetryable && attempt < maxRetries) {\n          const delay = Math.min(1000 * 2 ** attempt, 10_000);\n          await new Promise((resolve) => setTimeout(resolve, delay));\n          continue;\n        }\n\n        if (lastError.name === \"AbortError\") {\n          throw new ContextError(\n            `Request timed out after ${timeoutMs / 1000}s`,\n            undefined,\n            408\n          );\n        }\n\n        throw new ContextError(\n          lastError.message,\n          undefined,\n          undefined\n        );\n      }\n    }\n\n    throw lastError ?? new ContextError(\"Request failed after retries\");\n  }\n\n  /**\n   * Internal method for making authenticated HTTP requests that returns\n   * the raw Response object. Used for streaming endpoints (SSE).\n   *\n   * @internal\n   */\n  async _fetchRaw(endpoint: string, options: RequestInit = {}): Promise<Response> {\n    if (this._closed) {\n      throw new ContextError(\"Client has been closed\");\n    }\n\n    const url = `${this.baseUrl}${endpoint}`;\n\n    const response = await fetch(url, {\n      ...options,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${this.apiKey}`,\n        ...options.headers,\n      },\n    });\n\n    if (!response.ok) {\n      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;\n      let errorCode: string | undefined;\n      let helpUrl: string | undefined;\n\n      try {\n        const errorBody = await response.json();\n        if (errorBody.error) {\n          errorMessage = errorBody.error;\n          errorCode = errorBody.code;\n          helpUrl = errorBody.helpUrl;\n        }\n      } catch {\n        // Use default error message if JSON parsing fails\n      }\n\n      throw new ContextError(errorMessage, errorCode, response.status, helpUrl);\n    }\n\n    return response;\n  }\n}\n"]}