@ctxprotocol/sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,103 +1,281 @@
-# 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 official TypeScript SDK for the [Context Protocol](https://ctxprotocol.com) — the monetization layer for MCP. Discover and execute AI tools programmatically.
 
----
+[![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
-
-Using **pnpm**:
+## Installation
 
 ```bash
-pnpm add @ctxprotocol/sdk zod
+npm install @ctxprotocol/sdk
 ```
 
-Using **npm**:
+```bash
+pnpm add @ctxprotocol/sdk
+```
 
 ```bash
-npm install @ctxprotocol/sdk zod
-```
-
----
-
-## 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(),
-    };
-  },
+yarn add @ctxprotocol/sdk
+```
+
+## Prerequisites
+
+Before using the API, you must complete setup via the web dashboard:
+
+1. **Sign in** at [ctxprotocol.com](https://ctxprotocol.com) — 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";
+
+// Initialize the client with your API key
+const client = new ContextClient({
+  apiKey: "sk_live_...",
 });
 
-export async function handler(req: Request) {
-  const body = await req.json();
-  const result = await executeHttpTool(tool, body.input, {
-    headers: Object.fromEntries(req.headers.entries()),
-  });
+// 1. Discover tools
+const tools = await client.discovery.search("gas prices");
+console.log(tools[0].name);        // "Gas Price Oracle"
+console.log(tools[0].mcpTools);    // Available methods
+
+// 2. Execute a tool method
+const result = await client.tools.execute({
+  toolId: tools[0].id,
+  toolName: tools[0].mcpTools[0].name,  // e.g., "get_gas_prices"
+  args: { chainId: 1 },
+});
+
+console.log(result.result);     // Tool output data
+console.log(result.durationMs); // Execution time in ms
+```
+
+## Configuration
+
+### 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 usage
+const client = new ContextClient({
+  apiKey: process.env.CONTEXT_API_KEY!,
+});
+
+// Development/testing with local server
+const devClient = new ContextClient({
+  apiKey: "sk_test_...",
+  baseUrl: "http://localhost:3000",
+});
+```
+
+## API Reference
+
+### Discovery
+
+#### `client.discovery.search(query, limit?)`
+
+Search for tools matching a query string.
+
+```typescript
+const tools = await client.discovery.search("gas prices", 10);
+
+// Returns: Tool[]
+// [
+//   {
+//     id: "uuid-string",
+//     name: "Gas Price Oracle",
+//     description: "Get current gas prices",
+//     price: "0.001",
+//     category: "defi",
+//     isVerified: true,
+//     kind: "mcp",
+//     mcpTools: [
+//       { name: "get_gas_prices", description: "Get gas prices for a chain" },
+//       { name: "get_supported_chains", description: "List supported chains" }
+//     ]
+//   }
+// ]
+```
+
+#### `client.discovery.getFeatured(limit?)`
+
+Get featured/popular tools.
+
+```typescript
+const featured = await client.discovery.getFeatured(5);
+```
+
+### Tools
 
-  return Response.json(result);
+#### `client.tools.execute(options)`
+
+Execute a tool method with the provided arguments.
+
+```typescript
+const result = await client.tools.execute({
+  toolId: "uuid-of-tool",           // From search results
+  toolName: "get_gas_prices",        // From tool's mcpTools array
+  args: { chainId: 1 },              // Tool-specific arguments
+});
+
+// Returns: ExecutionResult<T>
+// {
+//   result: { gasPrice: "25.5", unit: "gwei", ... },
+//   tool: { id: "uuid", name: "Gas Price Oracle" },
+//   durationMs: 245
+// }
+```
+
+## Types
+
+All types are exported for full TypeScript autocomplete support:
+
+```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;
+  kind?: string;
+  mcpTools?: McpTool[];
+}
+
+interface McpTool {
+  name: string;
+  description: string;
 }
 ```
 
-See `examples/blocknative-contributor/` for a full Express server that wraps
-the Blocknative Gas Platform.
+### ExecuteOptions
 
----
+```typescript
+interface ExecuteOptions {
+  toolId: string;    // UUID of the tool
+  toolName: string;  // MCP method name from mcpTools array
+  args?: Record<string, unknown>;
+}
+```
 
-## Scripts
+### ExecutionResult
 
-From the repo root:
+```typescript
+interface ExecutionResult<T = unknown> {
+  result: T;
+  tool: { id: string; name: string };
+  durationMs: number;
+}
+```
 
-- **Build** – bundle to `dist/`:
+## Error Handling
 
-  ```bash
-  pnpm run build
-  ```
+The SDK throws `ContextError` for all API errors with specific error codes:
 
-- **Lint** – Biome checks:
+```typescript
+import { ContextClient, ContextError } from "@ctxprotocol/sdk";
 
-  ```bash
-  pnpm run lint
-  ```
+try {
+  const result = await client.tools.execute({
+    toolId: "...",
+    toolName: "...",
+    args: {},
+  });
+} catch (error) {
+  if (error instanceof ContextError) {
+    console.error("Error:", error.message);
+    console.error("Code:", error.code);
+    console.error("HTTP Status:", error.statusCode);
 
-- **Test** – Vitest (add tests as needed):
+    // Handle specific error cases
+    switch (error.code) {
+      case "no_wallet":
+        console.log("Please set up your wallet at", error.helpUrl);
+        break;
+      case "insufficient_allowance":
+        console.log("Please enable Auto Pay at", error.helpUrl);
+        break;
+      case "payment_failed":
+        console.log("Payment transaction failed");
+        break;
+      case "execution_failed":
+        console.log("Tool execution failed");
+        break;
+    }
+  }
+}
+```
 
-  ```bash
-  pnpm run test
-  ```
+### Error Codes
 
----
+| Code                     | Description                              |
+| ------------------------ | ---------------------------------------- |
+| `unauthorized`           | Missing or invalid API key               |
+| `no_wallet`              | User hasn't set up wallet via dashboard  |
+| `insufficient_allowance` | Auto Pay not enabled or allowance too low|
+| `payment_failed`         | On-chain payment transaction failed      |
+| `execution_failed`       | MCP tool execution error                 |
 
-## Publishing (for maintainers)
+## Authentication
 
-Install dependencies, build once to ensure everything compiles, then publish:
+All requests are automatically authenticated using the Bearer token scheme:
 
-```bash
-pnpm install
-pnpm run build
-pnpm publish --access public
 ```
+Authorization: Bearer sk_live_...
+```
+
+Your API key should be kept secret. Use environment variables in production:
+
+```typescript
+const client = new ContextClient({
+  apiKey: process.env.CONTEXT_API_KEY!,
+});
+```
+
+## Payment Flow
+
+When you execute a tool:
+
+1. Your pre-approved USDC allowance is used for payment
+2. **90%** goes to the tool developer
+3. **10%** goes to the protocol
+4. Tool executes and returns results
+
+Ensure your wallet has sufficient USDC balance before executing paid tools.
+
+## Links
+
+- [Context Protocol](https://ctxprotocol.com) — Main website
+- [GitHub](https://github.com/ctxprotocol/context) — Main project repository
+- [SDK Repository](https://github.com/ctxprotocol/sdk) — This SDK
+- [NPM Package](https://www.npmjs.com/package/@ctxprotocol/sdk)
+
+## Requirements
+
+- Node.js 18.0.0 or later (for native `fetch` support)
+- TypeScript 5.0+ (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/**\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  /** Type of tool (e.g., \"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  /** 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"]}