@ctxprotocol/sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,103 +1,366 @@
-# Context SDK
-> Server-side helpers for publishing HTTP tools to the Context marketplace.
+# @ctxprotocol/sdk
 
-The Context SDK is a tiny server-side helper for contributors who want to
-expose HTTP-based tools to the Context marketplace in a safe, typed, and
-consistent way.
+**The Universal Adapter for AI Agents.**
 
----
+Connect your AI to the real world without managing API keys, hosting servers, or reading documentation.
+
+Context Protocol is **npm for AI capabilities**. Just as you install packages to add functionality to your code, use the Context SDK to give your Agent instant access to thousands of live data sources and actions—from DeFi and Gas Oracles to Weather and Search.
+
+[![npm version](https://img.shields.io/npm/v/@ctxprotocol/sdk.svg)](https://www.npmjs.com/package/@ctxprotocol/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+## Why use Context?
 
-Using **pnpm**:
+- **🔌 One Interface, Everything:** Stop integrating APIs one by one. Use a single SDK to access any tool in the marketplace.
+- **🧠 Zero-Ops:** We're a gateway to the best MCP tools. Just send the JSON and get the result.
+- **⚡️ Agentic Discovery:** Your Agent can search the marketplace at runtime to find tools it didn't know it needed.
+- **💸 Micro-Billing:** Pay only for what you use (e.g., $0.001/query). No monthly subscriptions for tools you rarely use.
+
+## Installation
 
 ```bash
-pnpm add @ctxprotocol/sdk zod
+npm install @ctxprotocol/sdk
 ```
 
-Using **npm**:
+```bash
+pnpm add @ctxprotocol/sdk
+```
 
 ```bash
-npm install @ctxprotocol/sdk zod
+yarn add @ctxprotocol/sdk
+```
+
+## Prerequisites
+
+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
+3. **Fund wallet** — Add USDC for tool execution fees
+4. **Generate API key** — In Settings page
+
+## Quick Start
+
+```typescript
+import { ContextClient } from "@ctxprotocol/sdk";
+
+const client = new ContextClient({
+  apiKey: "sk_live_...",
+});
+
+// Discover tools
+const tools = await client.discovery.search("gas prices");
+
+// Execute a tool
+const result = await client.tools.execute({
+  toolId: tools[0].id,
+  toolName: tools[0].mcpTools[0].name,
+  args: { chainId: 1 },
+});
+
+console.log(result.result);
 ```
 
 ---
 
-## Quick start
-
-Define a tool with input/output schemas and a handler, then expose it via a
-single HTTP endpoint:
-
-```ts
-import { z } from "zod";
-import { defineHttpTool, executeHttpTool } from "@ctxprotocol/sdk";
-
-const tool = defineHttpTool({
-  name: "blocknative_gas_base",
-  inputSchema: z.object({ chainId: z.number().default(8453) }),
-  outputSchema: z.object({
-    endpoint: z.string(),
-    data: z.unknown(),
-  }),
-  async handler(input) {
-    const response = await fetch("https://your-endpoint", {
-      method: "POST",
-      body: JSON.stringify(input),
-    });
-
-    return {
-      endpoint: "gas_price",
-      data: await response.json(),
-    };
-  },
+## The Agentic Pattern: How to Build Autonomous Bots
+
+The most powerful way to use this SDK is to let your LLM do the driving. Instead of hardcoding tool calls, follow this **Discovery → Schema → Execution** loop:
+
+### 1. Discover
+
+Let your Agent search for tools based on the user's intent.
+
+```typescript
+const tools = await client.discovery.search(userQuery);
+```
+
+### 2. Inspect Schemas
+
+Feed the discovered tool schemas (`inputSchema`) directly to your LLM's system prompt. This allows the LLM to understand exactly how to format the arguments—just like reading a manual.
+
+```typescript
+const systemPrompt = `
+You have access to the following tools:
+
+${tools.map(t => `
+Tool: ${t.name} (ID: ${t.id})
+Description: ${t.description}
+Price: ${t.price} USDC
+
+Methods:
+${t.mcpTools?.map(m => `
+  - ${m.name}: ${m.description}
+    Arguments: ${JSON.stringify(m.inputSchema, null, 2)}
+    Returns: ${JSON.stringify(m.outputSchema, null, 2)}
+`).join("\n") ?? "No methods available"}
+`).join("\n---\n")}
+
+To use a tool, respond with a JSON object: { "toolId": "...", "toolName": "...", "args": {...} }
+`;
+```
+
+### 3. Execute
+
+When the LLM generates the arguments, pass them directly to the SDK.
+
+```typescript
+// The LLM generates this object based on the schema you provided
+const llmDecision = await myLLM.generate(userMessage, systemPrompt);
+
+const result = await client.tools.execute({
+  toolId: llmDecision.toolId,
+  toolName: llmDecision.toolName,
+  args: llmDecision.args,
 });
 
-export async function handler(req: Request) {
-  const body = await req.json();
-  const result = await executeHttpTool(tool, body.input, {
-    headers: Object.fromEntries(req.headers.entries()),
-  });
+// Feed the result back to your LLM for synthesis
+const finalAnswer = await myLLM.generate(
+  `The tool returned: ${JSON.stringify(result.result)}. Summarize this for the user.`
+);
+```
+
+### Handling Data (Outputs)
+
+Context Tools return raw, structured JSON data (via `structuredContent`). This allows your Agent to programmatically filter, sort, or analyze results before showing them to the user.
+
+> **Note:** For large datasets (like CSVs or PDF analysis), the API may return a reference URL to keep your context window clean.
+
+### Full Agentic Loop Example
+
+```typescript
+import { ContextClient, ContextError } from "@ctxprotocol/sdk";
+
+const client = new ContextClient({ apiKey: process.env.CONTEXT_API_KEY! });
+
+async function agentLoop(userQuery: string) {
+  // 1. Discover relevant tools
+  const tools = await client.discovery.search(userQuery);
+  
+  if (tools.length === 0) {
+    return "I couldn't find any tools to help with that.";
+  }
+
+  // 2. Build the system prompt with schemas
+  const toolDescriptions = tools.slice(0, 5).map(t => ({
+    id: t.id,
+    name: t.name,
+    description: t.description,
+    methods: t.mcpTools?.map(m => ({
+      name: m.name,
+      description: m.description,
+      inputSchema: m.inputSchema,
+    })),
+  }));
+
+  const systemPrompt = `You are an AI assistant with access to real-time tools.
+
+Available tools:
+${JSON.stringify(toolDescriptions, null, 2)}
+
+If you need to use a tool, respond ONLY with JSON:
+{ "toolId": "...", "toolName": "...", "args": {...} }
+
+If you can answer without a tool, just respond normally.`;
 
-  return Response.json(result);
+  // 3. Ask the LLM what to do
+  const llmResponse = await myLLM.chat(userQuery, systemPrompt);
+
+  // 4. Check if LLM wants to use a tool
+  try {
+    const toolCall = JSON.parse(llmResponse);
+    
+    if (toolCall.toolId && toolCall.toolName) {
+      // 5. Execute the tool
+      const result = await client.tools.execute({
+        toolId: toolCall.toolId,
+        toolName: toolCall.toolName,
+        args: toolCall.args || {},
+      });
+
+      // 6. Let LLM synthesize the result
+      return await myLLM.chat(
+        `Tool "${toolCall.toolName}" returned: ${JSON.stringify(result.result)}
+        
+Please provide a helpful response to the user's original question: "${userQuery}"`
+      );
+    }
+  } catch {
+    // LLM responded with text, not JSON - return as-is
+    return llmResponse;
+  }
 }
 ```
 
-See `examples/blocknative-contributor/` for a full Express server that wraps
-the Blocknative Gas Platform.
-
 ---
 
-## Scripts
+## Configuration
 
-From the repo root:
+### Client Options
+
+| Option    | Type     | Required | Default                  | Description                    |
+| --------- | -------- | -------- | ------------------------ | ------------------------------ |
+| `apiKey`  | `string` | Yes      | —                        | Your Context Protocol API key  |
+| `baseUrl` | `string` | No       | `https://ctxprotocol.com`| API base URL (for development) |
+
+```typescript
+// Production
+const client = new ContextClient({
+  apiKey: process.env.CONTEXT_API_KEY!,
+});
 
-- **Build** – bundle to `dist/`:
+// Local development
+const client = new ContextClient({
+  apiKey: "sk_test_...",
+  baseUrl: "http://localhost:3000",
+});
+```
 
-  ```bash
-  pnpm run build
-  ```
+## API Reference
 
-- **Lint** – Biome checks:
+### Discovery
 
-  ```bash
-  pnpm run lint
-  ```
+#### `client.discovery.search(query, limit?)`
 
-- **Test** – Vitest (add tests as needed):
+Search for tools matching a query string.
 
-  ```bash
-  pnpm run test
-  ```
+```typescript
+const tools = await client.discovery.search("ethereum gas", 10);
+```
 
----
+#### `client.discovery.getFeatured(limit?)`
 
-## Publishing (for maintainers)
+Get featured/popular tools.
 
-Install dependencies, build once to ensure everything compiles, then publish:
+```typescript
+const featured = await client.discovery.getFeatured(5);
+```
 
-```bash
-pnpm install
-pnpm run build
-pnpm publish --access public
+### Tools
+
+#### `client.tools.execute(options)`
+
+Execute a tool method.
+
+```typescript
+const result = await client.tools.execute({
+  toolId: "uuid-of-tool",
+  toolName: "get_gas_prices",
+  args: { chainId: 1 },
+});
+```
+
+## Types
+
+```typescript
+import type {
+  ContextClientOptions,
+  Tool,
+  McpTool,
+  ExecuteOptions,
+  ExecutionResult,
+  ContextErrorCode,
+} from "@ctxprotocol/sdk";
+```
+
+### Tool
+
+```typescript
+interface Tool {
+  id: string;
+  name: string;
+  description: string;
+  price: string;
+  category?: string;
+  isVerified?: boolean;
+  mcpTools?: McpTool[];
+}
 ```
 
+### McpTool
+
+```typescript
+interface McpTool {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;  // JSON Schema for arguments
+  outputSchema?: Record<string, unknown>; // JSON Schema for response
+}
+```
+
+### ExecutionResult
+
+```typescript
+interface ExecutionResult<T = unknown> {
+  result: T;
+  tool: { id: string; name: string };
+  durationMs: number;
+}
+```
+
+## Error Handling
+
+The SDK throws `ContextError` with specific error codes. In an agentic context, you can feed errors back to your LLM so it can self-correct.
+
+```typescript
+import { ContextError } from "@ctxprotocol/sdk";
+
+try {
+  const result = await client.tools.execute({ ... });
+} catch (error) {
+  if (error instanceof ContextError) {
+    switch (error.code) {
+      case "no_wallet":
+        // User needs to set up wallet
+        console.log("Setup required:", error.helpUrl);
+        break;
+      case "insufficient_allowance":
+        // User needs to enable Auto Pay
+        console.log("Enable Auto Pay:", error.helpUrl);
+        break;
+      case "payment_failed":
+        // Insufficient USDC balance
+        break;
+      case "execution_failed":
+        // Tool execution error - feed back to LLM to retry with different args
+        const retryPrompt = `The tool failed with: ${error.message}. Try different arguments.`;
+        break;
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code                     | Description                              | Agentic Handling                    |
+| ------------------------ | ---------------------------------------- | ----------------------------------- |
+| `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`            |
+| `payment_failed`         | USDC payment failed                      | Check balance                       |
+| `execution_failed`       | Tool error                               | Feed error to LLM for retry         |
+
+## Payment Flow
+
+When you execute a tool:
+
+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
+
+## Links
+
+- [Context Protocol](https://ctxprotocol.com) — Main website
+- [GitHub](https://github.com/ctxprotocol/context) — Main project
+- [SDK Repository](https://github.com/ctxprotocol/sdk) — This SDK
+- [NPM Package](https://www.npmjs.com/package/@ctxprotocol/sdk)
+
+## Requirements
+
+- Node.js 18+ (for native `fetch`)
+- TypeScript 5+ (recommended)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+// src/types.ts
+var ContextError = class extends Error {
+  constructor(message, code, statusCode, helpUrl) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.helpUrl = helpUrl;
+    this.name = "ContextError";
+  }
+};
+
+// src/resources/discovery.ts
+var Discovery = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Search for tools matching a query string
+   *
+   * @param query - The search query (e.g., "gas prices", "nft metadata")
+   * @param limit - Maximum number of results (1-50, default 10)
+   * @returns Array of matching tools
+   *
+   * @example
+   * ```typescript
+   * const tools = await client.discovery.search("gas prices");
+   * console.log(tools[0].name); // "Gas Price Oracle"
+   * console.log(tools[0].mcpTools); // Available methods
+   * ```
+   */
+  async search(query, limit) {
+    const params = new URLSearchParams();
+    if (query) {
+      params.set("q", query);
+    }
+    if (limit !== void 0) {
+      params.set("limit", String(limit));
+    }
+    const queryString = params.toString();
+    const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : ""}`;
+    const response = await this.client.fetch(endpoint);
+    return response.tools;
+  }
+  /**
+   * Get featured/popular tools (empty query search)
+   *
+   * @param limit - Maximum number of results (1-50, default 10)
+   * @returns Array of featured tools
+   *
+   * @example
+   * ```typescript
+   * const featured = await client.discovery.getFeatured(5);
+   * ```
+   */
+  async getFeatured(limit) {
+    return this.search("", limit);
+  }
+};
+
+// src/resources/tools.ts
+var Tools = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Execute a tool with the provided arguments
+   *
+   * @param options - Execution options
+   * @param options.toolId - The UUID of the tool (from search results)
+   * @param options.toolName - The specific MCP tool method to call (from tool's mcpTools array)
+   * @param options.args - Arguments to pass to the tool
+   * @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 `execution_failed` if tool execution fails
+   *
+   * @example
+   * ```typescript
+   * // First, search for a tool
+   * const tools = await client.discovery.search("gas prices");
+   * const tool = tools[0];
+   *
+   * // Execute a specific method from the tool's mcpTools
+   * const result = await client.tools.execute({
+   *   toolId: tool.id,
+   *   toolName: tool.mcpTools[0].name, // e.g., "get_gas_prices"
+   *   args: { chainId: 1 }
+   * });
+   *
+   * console.log(result.result); // The tool's output
+   * console.log(result.durationMs); // Execution time
+   * ```
+   */
+  async execute(options) {
+    const { toolId, toolName, args } = options;
+    const response = await this.client.fetch(
+      "/api/v1/tools/execute",
+      {
+        method: "POST",
+        body: JSON.stringify({ toolId, toolName, args })
+      }
+    );
+    if ("error" in response) {
+      throw new ContextError(
+        response.error,
+        response.code,
+        400,
+        response.helpUrl
+      );
+    }
+    if (response.success) {
+      return {
+        result: response.result,
+        tool: response.tool,
+        durationMs: response.durationMs
+      };
+    }
+    throw new ContextError("Unexpected response format from API");
+  }
+};
+
+// src/client.ts
+var ContextClient = class {
+  apiKey;
+  baseUrl;
+  /**
+   * Discovery resource for searching tools
+   */
+  discovery;
+  /**
+   * Tools resource for executing tools
+   */
+  tools;
+  /**
+   * Creates a new Context Protocol client
+   *
+   * @param options - Client configuration options
+   * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
+   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
+   */
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new ContextError("API key is required");
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://ctxprotocol.com").replace(/\/$/, "");
+    this.discovery = new Discovery(this);
+    this.tools = new Tools(this);
+  }
+  /**
+   * Internal method for making authenticated HTTP requests
+   * All requests include the Authorization header with the API key
+   *
+   * @internal
+   */
+  async fetch(endpoint, options = {}) {
+    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.json();
+  }
+};
+
+exports.ContextClient = ContextClient;
+exports.ContextError = ContextError;
+exports.Discovery = Discovery;
+exports.Tools = Tools;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/resources/discovery.ts","../src/resources/tools.ts","../src/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  /**\n   * Available MCP tool methods\n   * Use items from this array as `toolName` when executing\n   */\n  mcpTools?: McpTool[];\n\n  /** Creation timestamp */\n  createdAt?: string;\n\n  /** Last update timestamp */\n  updatedAt?: string;\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  }\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        400,\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\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   * Internal method for making authenticated HTTP requests\n   * All requests include the Authorization header with the API key\n   *\n   * @internal\n   */\n  async fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {\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.json() as Promise<T>;\n  }\n}\n"]}