@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/dist/cjs/ai/tools/protocols/shared.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @module ai/tools/protocols/shared
+ * @description Shared infrastructure for protocol-specific AI tools.
+ *
+ * Provides:
+ * - `ProtocolMethod` — typed schema descriptor for LLM tool discovery
+ * - `ProtocolHttpClient` — lightweight REST client for external APIs (Jupiter, Raydium)
+ * - `buildProtocolTools` — generic factory that wires schemas → LangChain tools
+ *
+ * @since 1.0.0
+ */
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+/**
+ * @description A registered protocol method with Zod schemas for agent discovery.
+ * @since 1.0.0
+ */
+export interface ProtocolMethod {
+    /** Unique method name within the protocol (e.g. 'getQuote'). */
+    name: string;
+    /** Human-readable description for the LLM. */
+    description?: string;
+    /** Zod schema for validated input parameters. */
+    input: z.ZodTypeAny;
+    /** Zod schema documenting the expected output shape. */
+    output: z.ZodTypeAny;
+    /** Protocol identifier (e.g. 'jupiter', 'raydium', 'metaplex'). */
+    protocol: string;
+    /** HTTP verb for REST APIs — ignored for RPC-based protocols. */
+    httpMethod?: 'GET' | 'POST';
+    /** API path relative to the protocol base URL. */
+    path?: string;
+}
+/**
+ * @description Creates an isolated method registry scoped to a single protocol.
+ *
+ * Each schema file calls `register()` to push methods into the
+ * protocol-local array, avoiding any cross-protocol collisions.
+ *
+ * @param {string} protocol - The protocol identifier (e.g. 'jupiter', 'raydium', 'metaplex')
+ * @returns {{ register: Function, methods: ProtocolMethod[] }} Registry with register function and methods array
+ * @since 1.0.0
+ */
+export declare function createMethodRegistry(protocol: string): {
+    readonly register: <I extends z.ZodTypeAny, O extends z.ZodTypeAny>(name: string, input: I, output: O, description: string, opts?: {
+        httpMethod?: "GET" | "POST";
+        path?: string;
+    }) => ProtocolMethod;
+    readonly methods: ProtocolMethod[];
+};
+/**
+ * @description Configuration for a protocol HTTP client instance.
+ * @since 1.0.0
+ */
+export interface ProtocolClientConfig {
+    /** Base URL (e.g. 'https://api.jup.ag'). Trailing slash stripped. */
+    baseUrl: string;
+    /** Request timeout in ms (default: 30 000). */
+    timeout?: number;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Bearer token — set as Authorization header. */
+    apiKey?: string;
+    /** Override the global fetch (useful for testing / Node 16). */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * @description Lightweight HTTP client for protocol REST APIs.
+ * Uses native fetch with timeout support, header management, and error handling.
+ * @since 1.0.0
+ */
+export declare class ProtocolHttpClient {
+    readonly baseUrl: string;
+    private readonly timeout;
+    private readonly headers;
+    private readonly _fetch;
+    constructor(config: ProtocolClientConfig);
+    /** HTTP GET with query-string serialisation. */
+    get<T = unknown>(path: string, params?: Record<string, unknown>): Promise<T>;
+    /** HTTP POST with JSON body. */
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+}
+/**
+ * @description Typed error for protocol REST API failures.
+ * Contains HTTP status code, response body, and the request path.
+ * @since 1.0.0
+ */
+export declare class ProtocolApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly path: string;
+    constructor(status: number, body: string, path: string);
+}
+/**
+ * @description A single LangChain-compatible tool for a protocol method.
+ * @since 1.0.0
+ */
+export type ProtocolTool = ReturnType<typeof tool>;
+/**
+ * @description Toolkit shape returned by every `createXxxTools()` factory.
+ * Contains tools array, keyed map, and method metadata.
+ * @since 1.0.0
+ */
+export interface ProtocolToolkit {
+    /** Protocol identifier. */
+    protocol: string;
+    /** Flat tool array — pass directly to an agent. */
+    tools: ProtocolTool[];
+    /** Keyed map for cherry-picking individual tools. */
+    toolMap: Record<string, ProtocolTool>;
+    /** Registered method schemas (useful for introspection). */
+    methods: ProtocolMethod[];
+    /** All method names available in this toolkit. */
+    methodNames: string[];
+}
+/**
+ * @description Common options accepted by every `createXxxTools()` factory.
+ * @since 1.0.0
+ */
+export interface CreateProtocolToolsOpts {
+    /** Prefix prepended to every tool name (default: `"<protocol>_"`). */
+    prefix?: string;
+    /** Restrict to a subset of method names. */
+    include?: string[];
+    /** Exclude specific method names (applied after include). */
+    exclude?: string[];
+    /** Pretty-print JSON output (default: true). */
+    prettyJson?: boolean;
+}
+/**
+ * @description Generic factory that wires ProtocolMethod schemas into real LangChain tools.
+ * Every protocol provides an `execute` callback; this function wraps each method.
+ *
+ * @param {readonly ProtocolMethod[]} methods - Registered protocol methods with Zod schemas
+ * @param {Function} execute - Async callback that executes a method with validated input
+ * @param {CreateProtocolToolsOpts & { defaultPrefix?: string }} [opts={}] - Tool creation options
+ * @returns {ProtocolToolkit} Toolkit with tools array, toolMap, and method metadata
+ * @since 1.0.0
+ */
+export declare function buildProtocolTools(methods: readonly ProtocolMethod[], execute: (method: ProtocolMethod, input: Record<string, unknown>) => Promise<unknown>, opts?: CreateProtocolToolsOpts & {
+    defaultPrefix?: string;
+}): ProtocolToolkit;
+//# sourceMappingURL=shared.d.ts.map

package/dist/cjs/ai/tools/protocols/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../../src/ai/tools/protocols/shared.ts"],"names":[],"mappings":"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"}

package/dist/cjs/ai/tools/protocols/shared.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolApiError = exports.ProtocolHttpClient = void 0;
+exports.createMethodRegistry = createMethodRegistry;
+exports.buildProtocolTools = buildProtocolTools;
+const tools_1 = require("@langchain/core/tools");
+/**
+ * @description Creates an isolated method registry scoped to a single protocol.
+ *
+ * Each schema file calls `register()` to push methods into the
+ * protocol-local array, avoiding any cross-protocol collisions.
+ *
+ * @param {string} protocol - The protocol identifier (e.g. 'jupiter', 'raydium', 'metaplex')
+ * @returns {{ register: Function, methods: ProtocolMethod[] }} Registry with register function and methods array
+ * @since 1.0.0
+ */
+function createMethodRegistry(protocol) {
+    const methods = [];
+    function register(name, input, output, description, opts) {
+        const method = {
+            name,
+            input,
+            output,
+            description,
+            protocol,
+            httpMethod: opts?.httpMethod,
+            path: opts?.path,
+        };
+        methods.push(method);
+        return method;
+    }
+    return { register, methods };
+}
+/**
+ * @description Lightweight HTTP client for protocol REST APIs.
+ * Uses native fetch with timeout support, header management, and error handling.
+ * @since 1.0.0
+ */
+class ProtocolHttpClient {
+    baseUrl;
+    timeout;
+    headers;
+    _fetch;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.timeout = config.timeout ?? 30_000;
+        this.headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...config.headers,
+        };
+        if (config.apiKey) {
+            this.headers['Authorization'] = `Bearer ${config.apiKey}`;
+        }
+        this._fetch = config.fetch ?? globalThis.fetch;
+    }
+    /** HTTP GET with query-string serialisation. */
+    async get(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v === undefined || v === null)
+                    continue;
+                if (Array.isArray(v)) {
+                    url.searchParams.set(k, v.join(','));
+                }
+                else {
+                    url.searchParams.set(k, String(v));
+                }
+            }
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await this._fetch(url.toString(), {
+                method: 'GET',
+                headers: this.headers,
+                signal: controller.signal,
+            });
+            if (!res.ok)
+                throw new ProtocolApiError(res.status, await res.text(), path);
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** HTTP POST with JSON body. */
+    async post(path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await this._fetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: this.headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!res.ok)
+                throw new ProtocolApiError(res.status, await res.text(), path);
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.ProtocolHttpClient = ProtocolHttpClient;
+/**
+ * @description Typed error for protocol REST API failures.
+ * Contains HTTP status code, response body, and the request path.
+ * @since 1.0.0
+ */
+class ProtocolApiError extends Error {
+    status;
+    body;
+    path;
+    constructor(status, body, path) {
+        super(`Protocol API error ${status} on ${path}: ${body.slice(0, 200)}`);
+        this.status = status;
+        this.body = body;
+        this.path = path;
+        this.name = 'ProtocolApiError';
+    }
+}
+exports.ProtocolApiError = ProtocolApiError;
+/* ═══════════════════════════════════════════════════════════════
+ *  buildProtocolTools() — generic factory wiring
+ *
+ *  Every protocol provides an `execute` callback; this function
+ *  wraps each ProtocolMethod into a real LangChain tool.
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Generic factory that wires ProtocolMethod schemas into real LangChain tools.
+ * Every protocol provides an `execute` callback; this function wraps each method.
+ *
+ * @param {readonly ProtocolMethod[]} methods - Registered protocol methods with Zod schemas
+ * @param {Function} execute - Async callback that executes a method with validated input
+ * @param {CreateProtocolToolsOpts & { defaultPrefix?: string }} [opts={}] - Tool creation options
+ * @returns {ProtocolToolkit} Toolkit with tools array, toolMap, and method metadata
+ * @since 1.0.0
+ */
+function buildProtocolTools(methods, execute, opts = {}) {
+    const protocol = methods[0]?.protocol ?? 'unknown';
+    const { prefix = opts.defaultPrefix ?? `${protocol}_`, include, exclude, prettyJson = true, } = opts;
+    const tools = [];
+    const toolMap = {};
+    for (const method of methods) {
+        if (include && !include.includes(method.name))
+            continue;
+        if (exclude && exclude.includes(method.name))
+            continue;
+        const toolName = `${prefix}${method.name}`;
+        const t = (0, tools_1.tool)(async (input) => {
+            try {
+                const result = await execute(method, input);
+                return prettyJson ? JSON.stringify(result, null, 2) : JSON.stringify(result);
+            }
+            catch (err) {
+                return JSON.stringify({
+                    error: true,
+                    protocol,
+                    method: method.name,
+                    message: err?.message ?? String(err),
+                });
+            }
+        }, {
+            name: toolName,
+            description: method.description ?? `${protocol}: ${method.name}`,
+            schema: method.input,
+        });
+        tools.push(t);
+        toolMap[method.name] = t;
+    }
+    return {
+        protocol,
+        tools,
+        toolMap,
+        methods: methods,
+        methodNames: methods.map((m) => m.name),
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/cjs/ai/tools/protocols/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../../../src/ai/tools/protocols/shared.ts"],"names":[],"mappings":"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"}

package/dist/cjs/ai/tools/zod/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module ai/tools/zod
+ * @description Zod schema registry for Solana RPC methods.
+ *
+ * Provides a registration system for RPC method schemas that agents
+ * can use for input validation and discovery. Each method is registered
+ * with Zod input/output schemas and a human-readable description.
+ *
+ * @since 1.0.0
+ */
+import './types';
+import { z } from 'zod';
+import type { AgentRpcMethod } from './types';
+export type { AgentRpcMethod } from './types';
+/**
+ * @description Public immutable view of all registered Solana RPC method schemas.
+ * Populated during module evaluation by `registerRpcMethod()` calls from `./types`.
+ * @since 1.0.0
+ */
+export declare const agentRpcMethods: AgentRpcMethod[];
+/**
+ * @description Register an RPC method with Zod input/output schemas for agent discovery.
+ * Called during module evaluation to populate the shared `agentRpcMethods` array.
+ *
+ * @template I - Zod schema type for input parameters
+ * @template O - Zod schema type for output
+ * @param {string} name - The JSON-RPC method name (e.g. 'getBalance')
+ * @param {I} input - Zod schema for validated input parameters
+ * @param {O} output - Zod schema documenting the expected output shape
+ * @param {string} [description] - Human-readable description for LLM discovery
+ * @returns {AgentRpcMethod} The registered method descriptor
+ * @since 1.0.0
+ */
+export declare function registerRpcMethod<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(name: string, input: I, output: O, description?: string): AgentRpcMethod;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/ai/tools/zod/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ai/tools/zod/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,SAAS,CAAC;AAEjB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAc9C;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,EAAoB,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU,EAC9E,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,EACT,WAAW,CAAC,EAAE,MAAM,GACnB,cAAc,CAKhB"}

package/dist/cjs/ai/tools/zod/index.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * @module ai/tools/zod
+ * @description Zod schema registry for Solana RPC methods.
+ *
+ * Provides a registration system for RPC method schemas that agents
+ * can use for input validation and discovery. Each method is registered
+ * with Zod input/output schemas and a human-readable description.
+ *
+ * @since 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentRpcMethods = void 0;
+exports.registerRpcMethod = registerRpcMethod;
+/* Side-effect import: executes all registerRpcMethod() calls.
+ * MUST come before `agentRpcMethods` declaration so that in ESM
+ * module evaluation (where imports are hoisted), the types module
+ * runs first and populates `_registry` via `registerRpcMethod()`. */
+require("./types");
+/**
+ * Internal mutable registry — populated during module evaluation by
+ * `registerRpcMethod()` calls originating from `./types`.
+ *
+ * We keep a module-scoped array that `registerRpcMethod` pushes into.
+ * Because `_registry` is initialised via `var` (hoisted, so it exists
+ * as `undefined` during import evaluation), the `registerRpcMethod`
+ * function creates the array on first call to avoid the TDZ issue.
+ */
+// eslint-disable-next-line no-var
+var _registry;
+/**
+ * @description Public immutable view of all registered Solana RPC method schemas.
+ * Populated during module evaluation by `registerRpcMethod()` calls from `./types`.
+ * @since 1.0.0
+ */
+exports.agentRpcMethods = _registry ?? [];
+/**
+ * @description Register an RPC method with Zod input/output schemas for agent discovery.
+ * Called during module evaluation to populate the shared `agentRpcMethods` array.
+ *
+ * @template I - Zod schema type for input parameters
+ * @template O - Zod schema type for output
+ * @param {string} name - The JSON-RPC method name (e.g. 'getBalance')
+ * @param {I} input - Zod schema for validated input parameters
+ * @param {O} output - Zod schema documenting the expected output shape
+ * @param {string} [description] - Human-readable description for LLM discovery
+ * @returns {AgentRpcMethod} The registered method descriptor
+ * @since 1.0.0
+ */
+function registerRpcMethod(name, input, output, description) {
+    if (!_registry)
+        _registry = [];
+    const method = { name, input, output, description };
+    _registry.push(method);
+    return method;
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/ai/tools/zod/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/ai/tools/zod/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AA6CH,8CAUC;AArDD;;;qEAGqE;AACrE,mBAAiB;AAOjB;;;;;;;;GAQG;AACH,kCAAkC;AAClC,IAAI,SAAuC,CAAC;AAE5C;;;;GAIG;AACU,QAAA,eAAe,GAAqB,SAAS,IAAI,EAAE,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,SAAgB,iBAAiB,CAC/B,IAAY,EACZ,KAAQ,EACR,MAAS,EACT,WAAoB;IAEpB,IAAI,CAAC,SAAS;QAAE,SAAS,GAAG,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACpE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cjs/ai/tools/zod/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module ai/tools/zod/types
+ * @description Zod schemas for all 53 Solana JSON-RPC methods.
+ *
+ * Each method is registered with typed input/output schemas for
+ * agent discovery, validation, and LLM tool creation.
+ *
+ * @since 1.0.0
+ */
+import { z } from 'zod';
+/**
+ * @description Descriptor for a registered Solana RPC method with Zod schemas.
+ * @since 1.0.0
+ */
+export interface AgentRpcMethod {
+    /** The JSON-RPC method name (e.g. 'getBalance'). */
+    name: string;
+    /** Human-readable description for agent/LLM discovery. */
+    description?: string;
+    /** Zod schema for validated input parameters. */
+    input: z.ZodTypeAny;
+    /** Zod schema documenting the expected output shape. */
+    output: z.ZodTypeAny;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/ai/tools/zod/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/ai/tools/zod/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC;IACpB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;CACtB"}