@ctxprotocol/sdk 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { ContextClient, ContextClientOptions, ContextError, ContextErrorCode, Discovery, ExecuteApiErrorResponse, ExecuteApiResponse, ExecuteApiSuccessResponse, ExecuteOptions, ExecuteSessionApiResponse, ExecuteSessionApiSuccessResponse, ExecuteSessionResult, ExecuteSessionSpend, ExecuteSessionStartOptions, ExecuteSessionStatus, ExecutionResult, McpTool, McpToolMeta, McpToolRateLimitHints, Query, QueryApiResponse, QueryApiSuccessResponse, QueryCost, QueryDeepMode, QueryDeveloperTrace, QueryDeveloperTraceLoopInfo, QueryDeveloperTraceStep, QueryDeveloperTraceSummary, QueryDeveloperTraceToolRef, QueryOptions, QueryResult, QueryStreamDeveloperTraceEvent, QueryStreamDoneEvent, QueryStreamErrorEvent, QueryStreamEvent, QueryStreamTextDeltaEvent, QueryStreamToolStatusEvent, QueryToolUsage, SearchOptions, SearchResponse, Tool, Tools } from './client/index.js';
+export { ContextClient, Developer, Discovery, Query, Tools } from './client/index.js';
+export { D as ContextClientOptions, B as ContextError, al as ContextErrorCode, U as ExecuteApiErrorResponse, V as ExecuteApiResponse, P as ExecuteApiSuccessResponse, I as ExecuteOptions, X as ExecuteSessionApiResponse, W as ExecuteSessionApiSuccessResponse, N as ExecuteSessionResult, L as ExecuteSessionSpend, J as ExecuteSessionStartOptions, K as ExecuteSessionStatus, O as ExecutionResult, M as McpTool, E as McpToolMeta, F as McpToolRateLimitHints, ac as QueryApiResponse, ab as QueryApiSuccessResponse, Z as QueryAttemptForkReason, _ as QueryAttemptReference, a5 as QueryCompletenessRepairEvent, a4 as QueryCost, Y as QueryDeepMode, Q as QueryDeveloperTrace, a6 as QueryDeveloperTraceDiagnostics, aa as QueryDeveloperTraceLoopInfo, a8 as QueryDeveloperTraceStep, a7 as QueryDeveloperTraceSummary, a9 as QueryDeveloperTraceToolRef, $ as QueryForkReference, a0 as QueryOptions, a1 as QueryResult, a2 as QuerySessionState, ag as QueryStreamDeveloperTraceEvent, ah as QueryStreamDoneEvent, ai as QueryStreamErrorEvent, ad as QueryStreamEvent, af as QueryStreamTextDeltaEvent, ae as QueryStreamToolStatusEvent, a3 as QueryToolUsage, H as SearchOptions, G as SearchResponse, T as Tool, aj as UpdateToolOptions, ak as UpdateToolResult } from './types-DRbq-FA6.js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -461,6 +462,10 @@ declare function createContextMiddleware(options?: CreateContextMiddlewareOption
  * of their MCP response. The Context platform intercepts these and
  * presents the appropriate UI to the user.
  *
+ * These helpers define the contributor-side MCP response contract.
+ * They do not create a headless Query API approval/resume flow; completing
+ * a handshake currently requires the Context chat app UI.
+ *
  * ## Action Types
  *
  * - `signature_request`: For EIP-712 signatures (Hyperliquid, Polymarket, etc.)
@@ -661,6 +666,9 @@ declare function createAuthRequired(params: Omit<AuthRequired, "_action">): Auth
  *
  * MCP tools should return handshake actions in `_meta.handshakeAction` to prevent
  * the MCP SDK from stripping unknown fields.
+ * Headless Query clients may observe raw internal handshake markers in
+ * execution data, but they cannot submit approval results through the
+ * Query API today.
  *
  * @example
  * ```typescript

package/dist/index.js

@@ -1,6 +1,18 @@
 import { jwtVerify, importSPKI } from 'jose';
 
 // src/client/types.ts
+var ALLOWED_TOOL_CATEGORIES = [
+  "Crypto & DeFi",
+  "Financial Markets",
+  "Business & Sales",
+  "Marketing & SEO",
+  "Legal & Regulatory",
+  "Real World",
+  "Developer Tools",
+  "Research & Academia",
+  "Utility",
+  "Other"
+];
 var ContextError = class _ContextError extends Error {
   constructor(message, code, statusCode, helpUrl) {
     super(message);
@@ -12,6 +24,57 @@ var ContextError = class _ContextError extends Error {
   }
 };
 
+// src/client/resources/developer.ts
+var Developer = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Update a tool listing's metadata (name, description, category).
+   *
+   * Requires an API key belonging to the tool's owner.
+   *
+   * @param toolId - The UUID of the tool to update
+   * @param updates - Fields to update (at least one required)
+   * @returns The updated tool metadata
+   *
+   * @throws {ContextError} If authentication fails or the caller does not own the tool
+   *
+   * @example
+   * ```typescript
+   * const updated = await client.developer.updateTool("tool-uuid", {
+   *   description: "Updated description with better showcase prompts",
+   *   category: "crypto",
+   * });
+   * console.log(updated.updatedAt);
+   * ```
+   */
+  async updateTool(toolId, updates) {
+    if (!toolId) {
+      throw new ContextError("toolId is required");
+    }
+    if (updates.name === void 0 && updates.description === void 0 && updates.category === void 0) {
+      throw new ContextError(
+        "At least one field required: name, description, or category"
+      );
+    }
+    if (updates.category !== void 0 && updates.category !== null && !ALLOWED_TOOL_CATEGORIES.includes(updates.category)) {
+      throw new ContextError(
+        `category must be one of: ${ALLOWED_TOOL_CATEGORIES.join(", ")}`
+      );
+    }
+    const encodedToolId = encodeURIComponent(toolId);
+    return this.client._fetch(
+      `/api/v1/tools/${encodedToolId}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify(updates)
+      },
+      { retry: false }
+    );
+  }
+};
+
 // src/client/resources/discovery.ts
 var Discovery = class {
   constructor(client) {
@@ -236,6 +299,47 @@ var Query = class {
   constructor(client) {
     this.client = client;
   }
+  normalizeResult(result) {
+    const candidate = result;
+    if (candidate.outcomeType === "clarification_required" && "clarification" in candidate && candidate.clarification) {
+      return candidate;
+    }
+    if (candidate.outcomeType === "capability_miss" && "capabilityMiss" in candidate && candidate.capabilityMiss) {
+      return candidate;
+    }
+    return {
+      ...candidate,
+      outcomeType: "answer"
+    };
+  }
+  buildPolicyErrorEvent(params) {
+    if (params.clarificationPolicy !== "error") {
+      return;
+    }
+    if (params.result.outcomeType === "clarification_required") {
+      return {
+        type: "error",
+        error: params.result.response,
+        code: "clarification_required",
+        reasonCode: "clarification_required",
+        outcomeType: "clarification_required",
+        clarification: params.result.clarification,
+        querySession: params.result.querySession
+      };
+    }
+    if (params.result.outcomeType === "capability_miss") {
+      return {
+        type: "error",
+        error: params.result.response,
+        code: "capability_miss",
+        reasonCode: "capability_miss",
+        outcomeType: "capability_miss",
+        capabilityMiss: params.result.capabilityMiss,
+        querySession: params.result.querySession
+      };
+    }
+    return void 0;
+  }
   buildSyntheticTraceFromRunResult(params) {
     const timeline = params.toolsUsed.map((tool, index) => ({
       stepType: "tool-call",
@@ -378,6 +482,7 @@ var Query = class {
   async run(options) {
     const opts = typeof options === "string" ? { query: options } : options;
     let terminalError;
+    let finalResult;
     for await (const event of this.stream(opts)) {
       if (event.type === "error") {
         terminalError = {
@@ -389,9 +494,12 @@ var Query = class {
         continue;
       }
       if (event.type === "done") {
-        return event.result;
+        finalResult = event.result;
       }
     }
+    if (finalResult) {
+      return finalResult;
+    }
     if (terminalError) {
       throw new ContextError(terminalError.error, terminalError.code);
     }
@@ -443,7 +551,11 @@ var Query = class {
       body: JSON.stringify({
         query: opts.query,
         tools: opts.tools,
-        modelId: opts.modelId,
+        resumeFrom: opts.resumeFrom,
+        forkFrom: opts.forkFrom,
+        clarificationPolicy: opts.clarificationPolicy,
+        answerModelId: opts.answerModelId,
+        responseShape: opts.responseShape,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
         includeDeveloperTrace: opts.includeDeveloperTrace,
@@ -481,22 +593,31 @@ var Query = class {
         return event;
       }
       if (event.type === "done") {
+        const normalizedResult = this.normalizeResult(event.result);
         let mergedTrace = this.mergeDeveloperTrace(
           aggregatedTrace,
-          event.result.developerTrace
+          normalizedResult.developerTrace
         );
         if (!mergedTrace && opts.includeDeveloperTrace) {
           mergedTrace = statusTimeline.length > 0 ? this.buildSyntheticTraceFromStreamStatus({
             statusTimeline,
-            toolsUsed: event.result.toolsUsed,
-            durationMs: event.result.durationMs
+            toolsUsed: normalizedResult.toolsUsed,
+            durationMs: normalizedResult.durationMs
           }) : this.buildSyntheticTraceFromRunResult({
-            toolsUsed: event.result.toolsUsed,
-            durationMs: event.result.durationMs
+            toolsUsed: normalizedResult.toolsUsed,
+            durationMs: normalizedResult.durationMs
           });
         }
         if (mergedTrace) {
-          event.result.developerTrace = mergedTrace;
+          normalizedResult.developerTrace = mergedTrace;
+        }
+        event.result = normalizedResult;
+        const policyErrorEvent = this.buildPolicyErrorEvent({
+          result: normalizedResult,
+          clarificationPolicy: opts.clarificationPolicy
+        });
+        if (policyErrorEvent) {
+          return policyErrorEvent;
         }
       }
       return event;
@@ -551,6 +672,10 @@ var ContextClient = class {
   requestTimeoutMs;
   streamTimeoutMs;
   _closed = false;
+  /**
+   * Developer resource for managing tool listings (contributor/developer concerns).
+   */
+  developer;
   /**
    * Discovery resource for searching tools
    */
@@ -592,6 +717,7 @@ var ContextClient = class {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.requestTimeoutMs = requestTimeoutMs;
     this.streamTimeoutMs = streamTimeoutMs;
+    this.developer = new Developer(this);
     this.discovery = new Discovery(this);
     this.tools = new Tools(this);
     this.query = new Query(this);
@@ -912,6 +1038,6 @@ function wrapHandshakeResponse(action) {
   };
 }
 
-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 };
+export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Developer, 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