npm - @ctxprotocol/sdk - Versions diffs - 0.1.2 → 0.2.0 - Mend

@ctxprotocol/sdk 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -1,269 +1 @@
-/**
- * Configuration options for initializing the ContextClient
- */
-interface ContextClientOptions {
-    /**
-     * Your Context Protocol API key
-     * @example "sk_live_abc123..."
-     */
-    apiKey: string;
-    /**
-     * Base URL for the Context Protocol API
-     * @default "https://ctxprotocol.com"
-     */
-    baseUrl?: string;
-}
-/**
- * An individual MCP tool exposed by a tool listing
- */
-interface McpTool {
-    /** Name of the MCP tool method */
-    name: string;
-    /** Description of what this method does */
-    description: string;
-}
-/**
- * Represents a tool available on the Context Protocol marketplace
- */
-interface Tool {
-    /** Unique identifier for the tool (UUID) */
-    id: string;
-    /** Human-readable name of the tool */
-    name: string;
-    /** Description of what the tool does */
-    description: string;
-    /** Price per execution in USDC */
-    price: string;
-    /** Tool category (e.g., "defi", "nft") */
-    category?: string;
-    /** Whether the tool is verified by Context Protocol */
-    isVerified?: boolean;
-    /** Type of tool (e.g., "mcp") */
-    kind?: string;
-    /**
-     * Available MCP tool methods
-     * Use items from this array as `toolName` when executing
-     */
-    mcpTools?: McpTool[];
-    /** Creation timestamp */
-    createdAt?: string;
-    /** Last update timestamp */
-    updatedAt?: string;
-}
-/**
- * Response from the tools search endpoint
- */
-interface SearchResponse {
-    /** Array of matching tools */
-    tools: Tool[];
-    /** The search query that was used */
-    query: string;
-    /** Total number of results */
-    count: number;
-}
-/**
- * Options for searching tools
- */
-interface SearchOptions {
-    /** Search query (semantic search) */
-    query?: string;
-    /** Maximum number of results (1-50, default 10) */
-    limit?: number;
-}
-/**
- * Options for executing a tool
- */
-interface ExecuteOptions {
-    /** The UUID of the tool to execute (from search results) */
-    toolId: string;
-    /** The specific MCP tool name to call (from tool's mcpTools array) */
-    toolName: string;
-    /** Arguments to pass to the tool */
-    args?: Record<string, unknown>;
-}
-/**
- * Successful execution response from the API
- */
-interface ExecuteApiSuccessResponse {
-    success: true;
-    /** The result data from the tool execution */
-    result: unknown;
-    /** Information about the executed tool */
-    tool: {
-        id: string;
-        name: string;
-    };
-    /** Execution duration in milliseconds */
-    durationMs: number;
-}
-/**
- * Error response from the API
- */
-interface ExecuteApiErrorResponse {
-    /** Human-readable error message */
-    error: string;
-    /** Error code for programmatic handling */
-    code?: ContextErrorCode;
-    /** URL to help resolve the issue */
-    helpUrl?: string;
-}
-/**
- * Raw API response from the execute endpoint
- */
-type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;
-/**
- * The resolved result returned to the user after SDK processing
- */
-interface ExecutionResult<T = unknown> {
-    /** The data returned by the tool */
-    result: T;
-    /** Information about the executed tool */
-    tool: {
-        id: string;
-        name: string;
-    };
-    /** Execution duration in milliseconds */
-    durationMs: number;
-}
-/**
- * Specific error codes returned by the Context Protocol API
- */
-type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed";
-/**
- * Error thrown by the Context Protocol client
- */
-declare class ContextError extends Error {
-    readonly code?: (ContextErrorCode | string) | undefined;
-    readonly statusCode?: number | undefined;
-    readonly helpUrl?: string | undefined;
-    constructor(message: string, code?: (ContextErrorCode | string) | undefined, statusCode?: number | undefined, helpUrl?: string | undefined);
-}
-/**
- * Discovery resource for searching and finding tools on the Context Protocol marketplace
- */
-declare class Discovery {
-    private client;
-    constructor(client: ContextClient);
-    /**
-     * 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
-     * ```
-     */
-    search(query: string, limit?: number): Promise<Tool[]>;
-    /**
-     * 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);
-     * ```
-     */
-    getFeatured(limit?: number): Promise<Tool[]>;
-}
-/**
- * Tools resource for executing tools on the Context Protocol marketplace
- */
-declare class Tools {
-    private client;
-    constructor(client: ContextClient);
-    /**
-     * 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
-     * ```
-     */
-    execute<T = unknown>(options: ExecuteOptions): Promise<ExecutionResult<T>>;
-}
-/**
- * The official TypeScript client for the Context Protocol.
- *
- * Use this client to discover and execute AI tools programmatically.
- *
- * @example
- * ```typescript
- * import { ContextClient } from "@contextprotocol/client";
- *
- * const client = new ContextClient({
- *   apiKey: "sk_live_..."
- * });
- *
- * // Discover tools
- * const tools = await client.discovery.search("gas prices");
- *
- * // Execute a tool method
- * const result = await client.tools.execute({
- *   toolId: tools[0].id,
- *   toolName: tools[0].mcpTools[0].name,
- *   args: { chainId: 1 }
- * });
- * ```
- */
-declare class ContextClient {
-    private readonly apiKey;
-    private readonly baseUrl;
-    /**
-     * Discovery resource for searching tools
-     */
-    readonly discovery: Discovery;
-    /**
-     * Tools resource for executing tools
-     */
-    readonly 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: ContextClientOptions);
-    /**
-     * Internal method for making authenticated HTTP requests
-     * All requests include the Authorization header with the API key
-     *
-     * @internal
-     */
-    fetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
-}
-export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecutionResult, type McpTool, type SearchOptions, type SearchResponse, type Tool, Tools };
+export { ContextClient, ContextClientOptions, ContextError, ContextErrorCode, Discovery, ExecuteApiErrorResponse, ExecuteApiResponse, ExecuteApiSuccessResponse, ExecuteOptions, ExecutionResult, McpTool, SearchOptions, SearchResponse, Tool, Tools } from './client/index.js';

package/dist/index.js CHANGED Viewed

@@ -1,4 +1,4 @@
-// src/types.ts
+// src/client/types.ts
 var ContextError = class extends Error {
   constructor(message, code, statusCode, helpUrl) {
     super(message);
@@ -9,7 +9,7 @@ var ContextError = class extends Error {
   }
 };
-// src/resources/discovery.ts
+// src/client/resources/discovery.ts
 var Discovery = class {
   constructor(client) {
     this.client = client;
@@ -57,7 +57,7 @@ var Discovery = class {
   }
 };
-// src/resources/tools.ts
+// src/client/resources/tools.ts
 var Tools = class {
   constructor(client) {
     this.client = client;
@@ -121,7 +121,7 @@ var Tools = class {
   }
 };
-// src/client.ts
+// src/client/client.ts
 var ContextClient = class {
   apiKey;
   baseUrl;

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
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.js","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"]}
1	+ {"version":3,"sources":["../src/client/types.ts","../src/client/resources/discovery.ts","../src/client/resources/tools.ts","../src/client/client.ts"],"names":[],"mappings":";AAsLO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EACtC,WAAA,CACE,OAAA,EACgB,IAAA,EACA,UAAA,EACA,OAAA,EAChB;AACA,IAAA,KAAA,CAAM,OAAO,CAAA;AAJG,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,UAAA,GAAA,UAAA;AACA,IAAA,IAAA,CAAA,OAAA,GAAA,OAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AAAA,EACd;AACF;;;AC1LO,IAAM,YAAN,MAAgB;AAAA,EACrB,YAAoB,MAAA,EAAuB;AAAvB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgB5C,MAAM,MAAA,CAAO,KAAA,EAAe,KAAA,EAAiC;AAC3D,IAAA,MAAM,MAAA,GAAS,IAAI,eAAA,EAAgB;AAEnC,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,MAAA,CAAO,GAAA,CAAI,KAAK,KAAK,CAAA;AAAA,IACvB;AAEA,IAAA,IAAI,UAAU,MAAA,EAAW;AACvB,MAAA,MAAA,CAAO,GAAA,CAAI,OAAA,EAAS,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,IACnC;AAEA,IAAA,MAAM,WAAA,GAAc,OAAO,QAAA,EAAS;AACpC,IAAA,MAAM,WAAW,CAAA,oBAAA,EAAuB,WAAA,GAAc,CAAA,CAAA,EAAI,WAAW,KAAK,EAAE,CAAA,CAAA;AAE5E,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,MAAA,CAAO,MAAsB,QAAQ,CAAA;AAEjE,IAAA,OAAO,QAAA,CAAS,KAAA;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,MAAM,YAAY,KAAA,EAAiC;AACjD,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,EAAA,EAAI,KAAK,CAAA;AAAA,EAC9B;AACF;;;AC7CO,IAAM,QAAN,MAAY;AAAA,EACjB,YAAoB,MAAA,EAAuB;AAAvB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiC5C,MAAM,QAAqB,OAAA,EAAsD;AAC/E,IAAA,MAAM,EAAE,MAAA,EAAQ,QAAA,EAAU,IAAA,EAAK,GAAI,OAAA;AAEnC,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,MACjC,uBAAA;AAAA,MACA;AAAA,QACE,MAAA,EAAQ,MAAA;AAAA,QACR,MAAM,IAAA,CAAK,SAAA,CAAU,EAAE,MAAA,EAAQ,QAAA,EAAU,MAAM;AAAA;AACjD,KACF;AAGA,IAAA,IAAI,WAAW,QAAA,EAAU;AACvB,MAAA,MAAM,IAAI,YAAA;AAAA,QACR,QAAA,CAAS,KAAA;AAAA,QACT,QAAA,CAAS,IAAA;AAAA,QACT,GAAA;AAAA,QACA,QAAA,CAAS;AAAA,OACX;AAAA,IACF;AAGA,IAAA,IAAI,SAAS,OAAA,EAAS;AACpB,MAAA,OAAO;AAAA,QACL,QAAQ,QAAA,CAAS,MAAA;AAAA,QACjB,MAAM,QAAA,CAAS,IAAA;AAAA,QACf,YAAY,QAAA,CAAS;AAAA,OACvB;AAAA,IACF;AAGA,IAAA,MAAM,IAAI,aAAa,qCAAqC,CAAA;AAAA,EAC9D;AACF;;;ACjDO,IAAM,gBAAN,MAAoB;AAAA,EACR,MAAA;AAAA,EACA,OAAA;AAAA;AAAA;AAAA;AAAA,EAKD,SAAA;AAAA;AAAA;AAAA;AAAA,EAKA,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAShB,YAAY,OAAA,EAA+B;AACzC,IAAA,IAAI,CAAC,QAAQ,MAAA,EAAQ;AACnB,MAAA,MAAM,IAAI,aAAa,qBAAqB,CAAA;AAAA,IAC9C;AAEA,IAAA,IAAA,CAAK,SAAS,OAAA,CAAQ,MAAA;AACtB,IAAA,IAAA,CAAK,WAAW,OAAA,CAAQ,OAAA,IAAW,yBAAA,EAA2B,OAAA,CAAQ,OAAO,EAAE,CAAA;AAG/E,IAAA,IAAA,CAAK,SAAA,GAAY,IAAI,SAAA,CAAU,IAAI,CAAA;AACnC,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAI,KAAA,CAAM,IAAI,CAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,KAAA,CAAS,QAAA,EAAkB,OAAA,GAAuB,EAAC,EAAe;AACtE,IAAA,MAAM,GAAA,GAAM,CAAA,EAAG,IAAA,CAAK,OAAO,GAAG,QAAQ,CAAA,CAAA;AAEtC,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK;AAAA,MAChC,GAAG,OAAA;AAAA,MACH,OAAA,EAAS;AAAA,QACP,cAAA,EAAgB,kBAAA;AAAA,QAChB,aAAA,EAAe,CAAA,OAAA,EAAU,IAAA,CAAK,MAAM,CAAA,CAAA;AAAA,QACpC,GAAG,OAAA,CAAQ;AAAA;AACb,KACD,CAAA;AAED,IAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,MAAA,IAAI,eAAe,CAAA,KAAA,EAAQ,QAAA,CAAS,MAAM,CAAA,EAAA,EAAK,SAAS,UAAU,CAAA,CAAA;AAClE,MAAA,IAAI,SAAA;AACJ,MAAA,IAAI,OAAA;AAEJ,MAAA,IAAI;AACF,QAAA,MAAM,SAAA,GAAY,MAAM,QAAA,CAAS,IAAA,EAAK;AACtC,QAAA,IAAI,UAAU,KAAA,EAAO;AACnB,UAAA,YAAA,GAAe,SAAA,CAAU,KAAA;AACzB,UAAA,SAAA,GAAY,SAAA,CAAU,IAAA;AACtB,UAAA,OAAA,GAAU,SAAA,CAAU,OAAA;AAAA,QACtB;AAAA,MACF,CAAA,CAAA,MAAQ;AAAA,MAER;AAEA,MAAA,MAAM,IAAI,YAAA,CAAa,YAAA,EAAc,SAAA,EAAW,QAAA,CAAS,QAAQ,OAAO,CAAA;AAAA,IAC1E;AAEA,IAAA,OAAO,SAAS,IAAA,EAAK;AAAA,EACvB;AACF","file":"index.js","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"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ctxprotocol/sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Official TypeScript SDK for the Context Protocol - Discover and execute AI tools programmatically",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -16,6 +16,16 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
     }
   },
   "files": [
@@ -47,6 +57,7 @@
   "bugs": {
     "url": "https://github.com/ctxprotocol/sdk/issues"
   },
+  "dependencies": {},
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2"
@@ -54,4 +65,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}