@ctxprotocol/sdk 0.5.6 → 0.7.0

package/dist/index.js

@@ -1,13 +1,14 @@
-import { importSPKI, jwtVerify } from 'jose';
+import { jwtVerify, importSPKI } from 'jose';
 
 // 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,12 +428,13 @@ var ContextClient = class {
       }
       throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
     }
-    return response.json();
+    return response;
   }
 };
 
 // src/context/index.ts
 var CONTEXT_REQUIREMENTS_KEY = "x-context-requirements";
+var META_CONTEXT_REQUIREMENTS_KEY = "contextRequirements";
 var CONTEXT_PLATFORM_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs9YOgdpkmVQ5aoNovjsu
 chJdV54OT7dUdbVXz914a7Px8EwnpDqhsvG7WO8xL8sj2Rn6ueAJBk+04Hy/P/UN
@@ -197,6 +444,41 @@ lfOKbr7w0u72dZjiZPwnNDsX6PEEgvfmoautTFYTQgnZjDzq8UimTcv3KF+hJ5Ep
 weipe6amt9lzQzi8WXaFKpOXHQs//WDlUytz/Hl8pvd5craZKzo6Kyrg1Vfan7H3
 TQIDAQAB
 -----END PUBLIC KEY-----`;
+var JWKS_URL = "https://ctxprotocol.com/.well-known/jwks.json";
+var KEY_CACHE_TTL_MS = 36e5;
+var cachedPublicKey = null;
+var cacheTimestamp = 0;
+async function getPlatformPublicKey() {
+  const now = Date.now();
+  if (cachedPublicKey && now - cacheTimestamp < KEY_CACHE_TTL_MS) {
+    return cachedPublicKey;
+  }
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    const response = await fetch(JWKS_URL, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (response.ok) {
+      const jwks = await response.json();
+      if (jwks.keys && jwks.keys.length > 0) {
+        const key = jwks.keys[0];
+        if (key.x5c && key.x5c.length > 0) {
+          const pem = `-----BEGIN CERTIFICATE-----
+${key.x5c[0]}
+-----END CERTIFICATE-----`;
+          const { importX509 } = await import('jose');
+          cachedPublicKey = await importX509(pem, "RS256");
+          cacheTimestamp = now;
+          return cachedPublicKey;
+        }
+      }
+    }
+  } catch {
+  }
+  cachedPublicKey = await importSPKI(CONTEXT_PLATFORM_PUBLIC_KEY_PEM, "RS256");
+  cacheTimestamp = now;
+  return cachedPublicKey;
+}
 var PROTECTED_MCP_METHODS = /* @__PURE__ */ new Set([
   "tools/call"
   // Uncomment these if you want to protect resource/prompt access:
@@ -228,7 +510,7 @@ async function verifyContextRequest(options) {
   }
   const token = authorizationHeader.split(" ")[1];
   try {
-    const publicKey = await importSPKI(CONTEXT_PLATFORM_PUBLIC_KEY_PEM, "RS256");
+    const publicKey = await getPlatformPublicKey();
     const { payload } = await jwtVerify(token, publicKey, {
       issuer: "https://ctxprotocol.com",
       audience
@@ -312,6 +594,6 @@ function wrapHandshakeResponse(action) {
   };
 }
 
-export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, Tools, createAuthRequired, createContextMiddleware, createSignatureRequest, createTransactionProposal, isAuthRequired, isHandshakeAction, isOpenMcpMethod, isProtectedMcpMethod, isSignatureRequest, isTransactionProposal, verifyContextRequest, wrapHandshakeResponse };
+export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, META_CONTEXT_REQUIREMENTS_KEY, Query, Tools, createAuthRequired, createContextMiddleware, createSignatureRequest, createTransactionProposal, isAuthRequired, isHandshakeAction, isOpenMcpMethod, isProtectedMcpMethod, isSignatureRequest, isTransactionProposal, verifyContextRequest, wrapHandshakeResponse };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map