@ctxprotocol/sdk 0.5.5 → 0.6.0

package/dist/index.d.ts

@@ -90,8 +90,14 @@ interface PolymarketOrder {
  * This is what gets passed to MCP tools for personalized analysis.
  */
 interface PolymarketContext {
-    /** The wallet address this context is for */
+    /** The wallet address this context is for (may be comma-separated if multiple) */
     walletAddress: string;
+    /**
+     * The active wallet address for signing (the one with Polymarket activity).
+     * When multiple wallets are linked, this is the wallet that should be used
+     * for placing orders. Determined by activity detection on the client.
+     */
+    activeWalletAddress?: string;
     /** All open positions */
     positions: PolymarketPosition[];
     /** All open orders */
@@ -228,9 +234,11 @@ interface HyperliquidContext {
  * DECLARING CONTEXT REQUIREMENTS
  * =============================================================================
  *
- * Since the MCP protocol only transmits standard fields (name, description,
- * inputSchema, outputSchema), context requirements MUST be embedded in the
- * inputSchema using the "x-context-requirements" JSON Schema extension.
+ * Context requirements are declared via `_meta.contextRequirements` at the tool level.
+ * This is the primary mechanism that the Context Platform reads.
+ *
+ * Previously, `x-context-requirements` in inputSchema was recommended, but the MCP SDK
+ * may strip extension properties during transport. Use `_meta` instead.
  *
  * @example
  * ```typescript
@@ -239,9 +247,11 @@ interface HyperliquidContext {
  *
  * const tool = {
  *   name: "analyze_my_positions",
+ *   _meta: {
+ *     contextRequirements: ["hyperliquid"] as ContextRequirementType[],
+ *   },
  *   inputSchema: {
  *     type: "object",
- *     [CONTEXT_REQUIREMENTS_KEY]: ["hyperliquid"] as ContextRequirementType[],
  *     properties: {
  *       portfolio: { type: "object" }
  *     },
@@ -260,30 +270,33 @@ interface HyperliquidContext {
  */
 
 /**
- * JSON Schema extension key for declaring context requirements.
+ * @deprecated Use `_meta.contextRequirements` instead (see META_CONTEXT_REQUIREMENTS_KEY).
  *
- * WHY THIS APPROACH?
- * - MCP protocol only transmits: name, description, inputSchema, outputSchema
- * - Custom fields like `requirements` get stripped by MCP SDK during transport
- * - JSON Schema allows custom "x-" prefixed extension properties
- * - inputSchema is preserved end-to-end through MCP transport
+ * This key was designed for embedding requirements in inputSchema,
+ * but the MCP SDK may strip `x-` prefixed extension properties during transport.
+ * The `_meta.contextRequirements` approach is what the Context Platform reads.
+ */
+declare const CONTEXT_REQUIREMENTS_KEY: "x-context-requirements";
+/**
+ * The key used inside `_meta` to declare context requirements.
+ * This is the PRIMARY mechanism — the Context Platform reads `_meta.contextRequirements`.
  *
  * @example
  * ```typescript
- * import { CONTEXT_REQUIREMENTS_KEY } from "@ctxprotocol/sdk";
- *
  * const tool = {
  *   name: "analyze_my_positions",
+ *   _meta: {
+ *     [META_CONTEXT_REQUIREMENTS_KEY]: ["hyperliquid"] as ContextRequirementType[],
+ *   },
  *   inputSchema: {
  *     type: "object",
- *     [CONTEXT_REQUIREMENTS_KEY]: ["hyperliquid"],
  *     properties: { portfolio: { type: "object" } },
  *     required: ["portfolio"]
  *   }
  * };
  * ```
  */
-declare const CONTEXT_REQUIREMENTS_KEY: "x-context-requirements";
+declare const META_CONTEXT_REQUIREMENTS_KEY: "contextRequirements";
 /**
  * Context requirement types supported by the Context marketplace.
  * Maps to protocol-specific context builders on the platform.
@@ -434,4 +447,245 @@ interface CreateContextMiddlewareOptions {
  */
 declare function createContextMiddleware(options?: CreateContextMiddlewareOptions): (req: ContextRequest, res: ContextResponse, next: NextFunction) => Promise<void>;
 
-export { CONTEXT_REQUIREMENTS_KEY, type ContextMiddlewareRequest, type ContextRequirementType, type CreateContextMiddlewareOptions, type ERC20Context, type ERC20TokenBalance, type HyperliquidAccountSummary, type HyperliquidContext, type HyperliquidOrder, type HyperliquidPerpPosition, type HyperliquidSpotBalance, type PolymarketContext, type PolymarketOrder, type PolymarketPosition, type ToolRequirements, type UserContext, type VerifyRequestOptions, type WalletContext, createContextMiddleware, isOpenMcpMethod, isProtectedMcpMethod, verifyContextRequest };
+/**
+ * Handshake Types for MCP Tool Developers
+ *
+ * Use these types when your tool needs to request user interaction
+ * before completing an action (signatures, transactions, OAuth).
+ *
+ * @see https://docs.ctxprotocol.com/guides/handshake-architecture
+ *
+ * ## Usage Pattern
+ *
+ * Tools return handshake actions in the `_meta.handshakeAction` field
+ * of their MCP response. The Context platform intercepts these and
+ * presents the appropriate UI to the user.
+ *
+ * ## Action Types
+ *
+ * - `signature_request`: For EIP-712 signatures (Hyperliquid, Polymarket, etc.)
+ * - `transaction_proposal`: For direct on-chain transactions (Uniswap, NFT mints)
+ * - `auth_required`: For OAuth flows (Discord, Twitter, etc.)
+ */
+type HandshakeMeta = {
+    /** Human-readable description of the action */
+    description: string;
+    /** Protocol name (e.g., "Hyperliquid", "Polymarket") */
+    protocol?: string;
+    /** Action verb (e.g., "Place Order", "Place Bid") */
+    action?: string;
+    /** Token symbol if relevant */
+    tokenSymbol?: string;
+    /** Human-readable token amount */
+    tokenAmount?: string;
+    /** UI warning level */
+    warningLevel?: "info" | "caution" | "danger";
+    /** Custom title for the signature card (marketplace-friendly, overrides action-based title) */
+    title?: string;
+    /** Custom subtitle for the signature card (overrides tool name display) */
+    subtitle?: string;
+};
+type EIP712Domain = {
+    /** Domain name (e.g., "Hyperliquid", "ClobAuthDomain") */
+    name: string;
+    /** Domain version */
+    version: string;
+    /** Chain ID (informational - signing is chain-agnostic) */
+    chainId: number;
+    /** Optional verifying contract address */
+    verifyingContract?: `0x${string}`;
+};
+type EIP712TypeField = {
+    name: string;
+    type: string;
+};
+/**
+ * Signature Request
+ *
+ * Use this for platforms with proxy wallets (Hyperliquid, Polymarket, dYdX).
+ *
+ * Benefits:
+ * - No gas required (user signs a message, not a transaction)
+ * - No network switching needed (signing is chain-agnostic)
+ * - Works with Privy embedded wallets on any chain
+ *
+ * @example
+ * ```typescript
+ * return {
+ *   structuredContent: {
+ *     _meta: {
+ *       handshakeAction: createSignatureRequest({
+ *         domain: { name: "Hyperliquid", version: "1", chainId: 42161 },
+ *         types: { Order: [...] },
+ *         primaryType: "Order",
+ *         message: { asset: 4, isBuy: true, ... },
+ *         meta: { description: "Place Long ETH order", protocol: "Hyperliquid" }
+ *       })
+ *     }
+ *   }
+ * };
+ * ```
+ */
+type SignatureRequest = {
+    _action: "signature_request";
+    /** EIP-712 domain separator */
+    domain: EIP712Domain;
+    /** EIP-712 type definitions */
+    types: Record<string, EIP712TypeField[]>;
+    /** The primary type being signed */
+    primaryType: string;
+    /** The message data to sign */
+    message: Record<string, unknown>;
+    /** UI metadata for the approval card */
+    meta?: HandshakeMeta;
+    /**
+     * Optional: Tool name to call with the signature result.
+     * If provided, the platform will call this tool with { signature, originalParams }
+     * after the user signs.
+     */
+    callbackToolName?: string;
+};
+type TransactionProposalMeta = HandshakeMeta & {
+    /** Estimated gas cost (informational - Context may sponsor) */
+    estimatedGas?: string;
+    /** Link to contract on block explorer */
+    explorerUrl?: string;
+};
+/**
+ * Transaction Proposal
+ *
+ * Use this for protocols without proxy wallets (Uniswap, NFT mints, etc.).
+ *
+ * Note: May require network switching and gas fees.
+ *
+ * @example
+ * ```typescript
+ * return {
+ *   structuredContent: {
+ *     _meta: {
+ *       handshakeAction: createTransactionProposal({
+ *         chainId: 8453,
+ *         to: "0x...",
+ *         data: "0x...",
+ *         meta: { description: "Swap 100 USDC for ETH", protocol: "Uniswap" }
+ *       })
+ *     }
+ *   }
+ * };
+ * ```
+ */
+type TransactionProposal = {
+    _action: "transaction_proposal";
+    /** EVM chain ID (e.g., 137 for Polygon, 8453 for Base) */
+    chainId: number;
+    /** Target contract address */
+    to: `0x${string}`;
+    /** Encoded calldata */
+    data: `0x${string}`;
+    /** Wei to send (as string, default "0") */
+    value?: string;
+    /** UI metadata for the approval card */
+    meta?: TransactionProposalMeta;
+};
+type AuthRequiredMeta = {
+    /** Human-friendly service name */
+    displayName?: string;
+    /** Permissions being requested */
+    scopes?: string[];
+    /** Description of what access is needed */
+    description?: string;
+    /** Tool's icon URL */
+    iconUrl?: string;
+    /** How long authorization lasts */
+    expiresIn?: string;
+};
+/**
+ * Auth Required
+ *
+ * Use this when your tool needs the user to authenticate with an external service.
+ *
+ * @example
+ * ```typescript
+ * if (!hasUserToken(contextDid)) {
+ *   return {
+ *     structuredContent: {
+ *       _meta: {
+ *         handshakeAction: createAuthRequired({
+ *           provider: "discord",
+ *           authUrl: "https://your-server.com/oauth/discord",
+ *           meta: { displayName: "Discord Bot", scopes: ["send_messages"] }
+ *         })
+ *       }
+ *     }
+ *   };
+ * }
+ * ```
+ */
+type AuthRequired = {
+    _action: "auth_required";
+    /** Service identifier (e.g., "discord", "slack") */
+    provider: string;
+    /** Your OAuth initiation endpoint (MUST be HTTPS) */
+    authUrl: string;
+    /** UI metadata for the auth card */
+    meta?: AuthRequiredMeta;
+};
+type HandshakeAction = SignatureRequest | TransactionProposal | AuthRequired;
+declare function isHandshakeAction(value: unknown): value is HandshakeAction;
+declare function isSignatureRequest(value: unknown): value is SignatureRequest;
+declare function isTransactionProposal(value: unknown): value is TransactionProposal;
+declare function isAuthRequired(value: unknown): value is AuthRequired;
+/**
+ * Create a signature request response.
+ * Return this from your tool when you need the user to sign EIP-712 typed data.
+ *
+ * Use this for platforms with proxy wallets (Hyperliquid, Polymarket, dYdX).
+ * Benefits: No gas required, no network switching needed.
+ */
+declare function createSignatureRequest(params: Omit<SignatureRequest, "_action">): SignatureRequest;
+/**
+ * Create a transaction proposal response.
+ * Return this from your tool when you need the user to sign a direct on-chain transaction.
+ *
+ * Use this for protocols that don't use proxy wallets (Uniswap, NFT mints, etc.).
+ * Note: May require network switching and gas.
+ */
+declare function createTransactionProposal(params: Omit<TransactionProposal, "_action">): TransactionProposal;
+/**
+ * Create an auth required response.
+ * Return this from your tool when you need the user to authenticate via OAuth.
+ */
+declare function createAuthRequired(params: Omit<AuthRequired, "_action">): AuthRequired;
+/**
+ * Wrap a handshake action in the proper MCP response format.
+ *
+ * MCP tools should return handshake actions in `_meta.handshakeAction` to prevent
+ * the MCP SDK from stripping unknown fields.
+ *
+ * @example
+ * ```typescript
+ * // In your tool handler:
+ * return wrapHandshakeResponse(createSignatureRequest({
+ *   domain: { name: "Hyperliquid", version: "1", chainId: 42161 },
+ *   types: { Order: [...] },
+ *   primaryType: "Order",
+ *   message: orderData,
+ *   meta: { description: "Place order", protocol: "Hyperliquid" }
+ * }));
+ * ```
+ */
+declare function wrapHandshakeResponse(action: HandshakeAction): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: {
+        _meta: {
+            handshakeAction: HandshakeAction;
+        };
+        status: string;
+        message: string;
+    };
+};
+
+export { type AuthRequired, type AuthRequiredMeta, CONTEXT_REQUIREMENTS_KEY, type ContextMiddlewareRequest, type ContextRequirementType, type CreateContextMiddlewareOptions, type EIP712Domain, type EIP712TypeField, type ERC20Context, type ERC20TokenBalance, type HandshakeAction, type HandshakeMeta, type HyperliquidAccountSummary, type HyperliquidContext, type HyperliquidOrder, type HyperliquidPerpPosition, type HyperliquidSpotBalance, META_CONTEXT_REQUIREMENTS_KEY, type PolymarketContext, type PolymarketOrder, type PolymarketPosition, type SignatureRequest, type ToolRequirements, type TransactionProposal, type TransactionProposalMeta, type UserContext, type VerifyRequestOptions, type WalletContext, createAuthRequired, createContextMiddleware, createSignatureRequest, createTransactionProposal, isAuthRequired, isHandshakeAction, isOpenMcpMethod, isProtectedMcpMethod, isSignatureRequest, isTransactionProposal, verifyContextRequest, wrapHandshakeResponse };

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;
   }
   /**
@@ -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
       );
     }
@@ -127,6 +129,7 @@ var Tools = class {
 var ContextClient = class {
   apiKey;
   baseUrl;
+  _closed = false;
   /**
    * Discovery resource for searching tools
    */
@@ -151,43 +154,95 @@ var ContextClient = class {
     this.discovery = new Discovery(this);
     this.tools = new Tools(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 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;
+    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 errorBody = await response.json();
-        if (errorBody.error) {
-          errorMessage = errorBody.error;
-          errorCode = errorBody.code;
-          helpUrl = errorBody.helpUrl;
+        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;
         }
-      } catch {
+        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 new ContextError(errorMessage, errorCode, response.status, helpUrl);
     }
-    return response.json();
+    throw lastError ?? new ContextError("Request failed after retries");
   }
 };
 
 // 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 +252,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 +318,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
@@ -262,6 +352,56 @@ function createContextMiddleware(options = {}) {
   };
 }
 
-export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, Tools, createContextMiddleware, isOpenMcpMethod, isProtectedMcpMethod, verifyContextRequest };
+// src/handshake/types.ts
+function isHandshakeAction(value) {
+  return typeof value === "object" && value !== null && "_action" in value && (value._action === "signature_request" || value._action === "transaction_proposal" || value._action === "auth_required");
+}
+function isSignatureRequest(value) {
+  return isHandshakeAction(value) && value._action === "signature_request";
+}
+function isTransactionProposal(value) {
+  return isHandshakeAction(value) && value._action === "transaction_proposal";
+}
+function isAuthRequired(value) {
+  return isHandshakeAction(value) && value._action === "auth_required";
+}
+function createSignatureRequest(params) {
+  return {
+    _action: "signature_request",
+    ...params
+  };
+}
+function createTransactionProposal(params) {
+  return {
+    _action: "transaction_proposal",
+    ...params
+  };
+}
+function createAuthRequired(params) {
+  return {
+    _action: "auth_required",
+    ...params
+  };
+}
+function wrapHandshakeResponse(action) {
+  const actionType = action._action.replace("_", " ");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Handshake required: ${actionType}. Please approve in the Context app.`
+      }
+    ],
+    structuredContent: {
+      _meta: {
+        handshakeAction: action
+      },
+      status: "handshake_required",
+      message: action.meta?.description ?? `${actionType} required`
+    }
+  };
+}
+
+export { CONTEXT_REQUIREMENTS_KEY, ContextClient, ContextError, Discovery, META_CONTEXT_REQUIREMENTS_KEY, Tools, createAuthRequired, createContextMiddleware, createSignatureRequest, createTransactionProposal, isAuthRequired, isHandshakeAction, isOpenMcpMethod, isProtectedMcpMethod, isSignatureRequest, isTransactionProposal, verifyContextRequest, wrapHandshakeResponse };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map