rpc-express-toolkit 2.0.0

package/src/clients/rpc-client.js

@@ -0,0 +1,249 @@
+/**
+ * JSON-RPC 2.0 Client for browser and Node.js environments.
+ * Handles BigInt and Date serialization/deserialization automatically.
+ * 
+ * Note: We extend BigInt.prototype.toJSON to handle automatic serialization
+ * when JSON.stringify() is called, as BigInt doesn't have native JSON support.
+ */
+
+// Extend BigInt prototype to handle JSON serialization
+if (typeof BigInt !== 'undefined' && !BigInt.prototype.toJSON) {
+  BigInt.prototype.toJSON = function() { return this.toString(); };
+}
+
+// Polyfill for Node.js environments that don't have fetch
+let fetchFn;
+if (typeof fetch !== 'undefined') {
+  fetchFn = fetch;
+} else {
+  // Try to use node-fetch if available, otherwise use built-in fetch in Node.js 18+
+  try {
+    fetchFn = require('node-fetch');
+  } catch (e) {
+    // For Node.js 18+, use global fetch
+    if (typeof globalThis !== 'undefined' && globalThis.fetch) {
+      fetchFn = globalThis.fetch;
+    } else {
+      throw new Error('fetch is not available. Please install node-fetch or use Node.js 18+');
+    }
+  }
+}
+
+class RpcClient {
+  #endpoint;
+  #defaultHeaders;
+  #requestId;
+
+  /**
+   * @param {string} endpoint The JSON-RPC endpoint URL.
+   * @param {Object} [defaultHeaders={}] Optional default headers to include in requests.
+   */
+  constructor(endpoint, defaultHeaders = {}) {
+    this.#endpoint = endpoint;
+    this.#defaultHeaders = {
+      "Content-Type": "application/json", // Default header
+      ...defaultHeaders, // Merge with user-provided defaults
+    };
+    // Initialize request ID counter with timestamp + random component for uniqueness
+    this.#requestId = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+  }
+
+  /**
+   * Generate a unique request ID
+   * @returns {number} Unique request ID
+   */
+  #generateId() {
+    return ++this.#requestId;
+  }
+
+  /**
+   * Make a JSON-RPC call to the server.
+   * @param {string} method The RPC method name.
+   * @param {any} params The parameters to pass to the RPC method.
+   * @param {string|number|null} [id] The request ID (auto-generated if not provided).
+   * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
+   * @returns {Promise<any>} The result of the RPC call.
+   */
+  async call(method, params = {}, id = undefined, overrideHeaders = {}) {
+    // Auto-generate ID if not provided (null means notification)
+    const requestId = id === undefined ? this.#generateId() : id;
+    
+    const requestBody = {
+      jsonrpc: "2.0",
+      method,
+      params,
+      id: requestId,
+    };
+
+    try {
+      const response = await fetchFn(this.#endpoint, {
+        method: "POST",
+        headers: {
+          ...this.#defaultHeaders,
+          ...overrideHeaders,
+        },
+        // Since we have BigInt.prototype.toJSON, we don't need manual serialization
+        // JSON.stringify will handle BigInt and Date automatically
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+
+      const responseBody = await response.json();
+
+      if (responseBody.error) { throw responseBody.error; }
+
+      // Convert back BigInts and Dates in the result
+      return this.deserializeBigIntsAndDates(responseBody.result);
+    } catch (error) {
+      console.error("RPC call failed:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Send a notification (no response expected).
+   * @param {string} method The RPC method name.
+   * @param {any} params The parameters to pass to the RPC method.
+   * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
+   * @returns {Promise<void>} Promise that resolves when notification is sent.
+   */
+  async notify(method, params = {}, overrideHeaders = {}) {
+    await this.call(method, params, null, overrideHeaders);
+  }
+
+  /**
+   * Make multiple JSON-RPC calls in a single batch request.
+   * @param {Array<{method: string, params?: any, id?: string|number}>} requests Array of request objects.
+   * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
+   * @returns {Promise<Array<any>>} Array of results in the same order as requests.
+   */
+  async batch(requests, overrideHeaders = {}) {
+    const batchRequests = requests.map(req => ({
+      jsonrpc: "2.0",
+      method: req.method,
+      params: req.params || {},
+      id: req.id !== undefined ? req.id : this.#generateId()
+    }));
+
+    try {
+      const response = await fetchFn(this.#endpoint, {
+        method: "POST",
+        headers: {
+          ...this.#defaultHeaders,
+          ...overrideHeaders,
+        },
+        body: JSON.stringify(batchRequests),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+
+      const responseBody = await response.json();
+
+      // Handle batch response
+      if (Array.isArray(responseBody)) {
+        return responseBody.map(res => {
+          if (res.error) {
+            throw res.error;
+          }
+          return this.deserializeBigIntsAndDates(res.result);
+        });
+      } else {
+        // Single response in batch
+        if (responseBody.error) {
+          throw responseBody.error;
+        }
+        return [this.deserializeBigIntsAndDates(responseBody.result)];
+      }
+    } catch (error) {
+      console.error("Batch RPC call failed:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Recursively convert BigInt values to strings and Date objects to ISO strings
+   * so they can be JSON-serialized.
+   * @param {any} value
+   * @returns {any}
+   */
+  serializeBigIntsAndDates(value) {
+    if (typeof value === "bigint") {
+      // Convert BigInt to string
+      return value.toString();
+    } else if (Array.isArray(value)) {
+      // Recurse into arrays
+      return value.map((v) => this.serializeBigIntsAndDates(v));
+    } else if (value instanceof Date) {
+      // Convert Date to ISO string (UTC)
+      return value.toISOString();
+    } else if (value && typeof value === "object") {
+      // Recurse into plain objects
+      const result = {};
+      for (const [key, val] of Object.entries(value)) {
+        result[key] = this.serializeBigIntsAndDates(val);
+      }
+      return result;
+    }
+
+    // If it's neither an array, an object, a Date, nor a bigint, return as-is
+    return value;
+  }
+
+  /**
+   * Recursively convert stringified BigInt values back to BigInt
+   * and ISO 8601 date strings back to Date objects.
+   *
+   * @param {any} value The value to deserialize.
+   * @returns {any}
+   */
+  deserializeBigIntsAndDates(value) {
+    // More comprehensive ISO date regex that handles:
+    // - UTC: 2023-01-01T12:00:00.000Z
+    // - With timezone: 2023-01-01T12:00:00.000+01:00
+    // - Without timezone: 2023-01-01T12:00:00.000 (treated as local)
+    const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
+
+    // 1. Check if it's a string that might be a BigInt or a Date
+    if (typeof value === "string") {
+      // BigInt check: matches digits (including negative), optionally ending in "n"
+      // e.g., "42n", "42", "-42n", "-42"
+      if (/^-?\d+n?$/.test(value)) {
+        return BigInt(value.replace(/n$/, ""));
+      }
+      // Date check: matches an ISO 8601 string
+      if (ISO_DATE_REGEX.test(value)) {
+        const date = new Date(value);
+        // Ensure it's valid
+        if (!isNaN(date.getTime())) {
+          return date;
+        }
+      }
+    }
+
+    // 2. If it's an array, handle each element
+    if (Array.isArray(value)) {
+      return value.map((v) => this.deserializeBigIntsAndDates(v));
+    }
+
+    // 3. If it's a plain object, recurse into each property
+    if (value && typeof value === "object") {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, val]) => [
+          key,
+          this.deserializeBigIntsAndDates(val),
+        ])
+      );
+    }
+
+    // 4. Fallback for primitives, etc.
+    return value;
+  }
+}
+
+module.exports = RpcClient;
+module.exports.RpcClient = RpcClient;

package/src/clients/rpc-client.min.js

@@ -0,0 +1 @@
+let fetchFn;if("undefined"==typeof BigInt||BigInt.prototype.toJSON||(BigInt.prototype.toJSON=function(){return this.toString()}),"undefined"!=typeof fetch)fetchFn=fetch;else try{fetchFn=require("node-fetch")}catch(t){if("undefined"==typeof globalThis||!globalThis.fetch)throw new Error("fetch is not available. Please install node-fetch or use Node.js 18+");fetchFn=globalThis.fetch}class RpcClient{#t;#e;#r;constructor(t,e={}){this.#t=t,this.#e={"Content-Type":"application/json",...e},this.#r=1e3*Date.now()+Math.floor(1e3*Math.random())}#i(){return++this.#r}async call(t,e={},r=void 0,i={}){const s={jsonrpc:"2.0",method:t,params:e,id:void 0===r?this.#i():r};try{const t=await fetchFn(this.#t,{method:"POST",headers:{...this.#e,...i},body:JSON.stringify(s)});if(!t.ok)throw new Error(`HTTP Error: ${t.status} ${t.statusText}`);const e=await t.json();if(e.error)throw e.error;return this.deserializeBigIntsAndDates(e.result)}catch(t){throw console.error("RPC call failed:",t),t}}async notify(t,e={},r={}){await this.call(t,e,null,r)}async batch(t,e={}){const r=t.map(t=>({jsonrpc:"2.0",method:t.method,params:t.params||{},id:void 0!==t.id?t.id:this.#i()}));try{const t=await fetchFn(this.#t,{method:"POST",headers:{...this.#e,...e},body:JSON.stringify(r)});if(!t.ok)throw new Error(`HTTP Error: ${t.status} ${t.statusText}`);const i=await t.json();if(Array.isArray(i))return i.map(t=>{if(t.error)throw t.error;return this.deserializeBigIntsAndDates(t.result)});if(i.error)throw i.error;return[this.deserializeBigIntsAndDates(i.result)]}catch(t){throw console.error("Batch RPC call failed:",t),t}}serializeBigIntsAndDates(t){if("bigint"==typeof t)return t.toString();if(Array.isArray(t))return t.map(t=>this.serializeBigIntsAndDates(t));if(t instanceof Date)return t.toISOString();if(t&&"object"==typeof t){const e={};for(const[r,i]of Object.entries(t))e[r]=this.serializeBigIntsAndDates(i);return e}return t}deserializeBigIntsAndDates(t){const e=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;if("string"==typeof t){if(/^-?\d+n?$/.test(t))return BigInt(t.replace(/n$/,""));if(e.test(t)){const e=new Date(t);if(!isNaN(e.getTime()))return e}}return Array.isArray(t)?t.map(t=>this.deserializeBigIntsAndDates(t)):t&&"object"==typeof t?Object.fromEntries(Object.entries(t).map(([t,e])=>[t,this.deserializeBigIntsAndDates(e)])):t}}module.exports=RpcClient,module.exports.RpcClient=RpcClient;

package/src/clients/rpc-client.min.mjs

@@ -0,0 +1 @@
+let t;if("undefined"==typeof BigInt||BigInt.prototype.toJSON||(BigInt.prototype.toJSON=function(){return this.toString()}),"undefined"!=typeof fetch)t=fetch;else try{const{default:e}=await import("node-fetch");t=e}catch(e){if("undefined"==typeof globalThis||!globalThis.fetch)throw new Error("fetch is not available. Please install node-fetch or use Node.js 18+");t=globalThis.fetch}export class RpcClient{#t;#e;#r;constructor(t,e={}){this.#t=t,this.#e={"Content-Type":"application/json",...e},this.#r=1e3*Date.now()+Math.floor(1e3*Math.random())}async call(e,r={},i=null,s={}){null===i&&(i=++this.#r);const n={jsonrpc:"2.0",method:e,params:r,id:i};try{const e=await t(this.#t,{method:"POST",headers:{...this.#e,...s},body:JSON.stringify(n)});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const r=await e.json();if(r.error)throw r.error;return this.deserializeBigIntsAndDates(r.result)}catch(t){throw console.error("RPC call failed:",t),t}}async notify(e,r={},i={}){const s={jsonrpc:"2.0",method:e,params:r};try{const e=await t(this.#t,{method:"POST",headers:{...this.#e,...i},body:JSON.stringify(s)});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`)}catch(t){throw console.error("RPC notification failed:",t),t}}async batch(e,r={}){const i=e.map(t=>{const e={jsonrpc:"2.0",method:t.method,params:t.params||{}};return t.notification||(e.id=void 0!==t.id?t.id:++this.#r),e});try{const e=await t(this.#t,{method:"POST",headers:{...this.#e,...r},body:JSON.stringify(i)});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const s=await e.json();if(Array.isArray(s))return s.map(t=>{if(t.error)throw t.error;return this.deserializeBigIntsAndDates(t.result)});if(s.error)throw s.error;return[this.deserializeBigIntsAndDates(s.result)]}catch(t){throw console.error("RPC batch call failed:",t),t}}serializeBigIntsAndDates(t){if("bigint"==typeof t)return t.toString();if(Array.isArray(t))return t.map(t=>this.serializeBigIntsAndDates(t));if(t instanceof Date)return t.toISOString();if(t&&"object"==typeof t){const e={};for(const[r,i]of Object.entries(t))e[r]=this.serializeBigIntsAndDates(i);return e}return t}deserializeBigIntsAndDates(t){const e=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;if("string"==typeof t){if(/^-?\d+n?$/.test(t))return BigInt(t.replace(/n$/,""));if(e.test(t)){const e=new Date(t);if(!isNaN(e.getTime()))return e}}return Array.isArray(t)?t.map(t=>this.deserializeBigIntsAndDates(t)):t&&"object"==typeof t?Object.fromEntries(Object.entries(t).map(([t,e])=>[t,this.deserializeBigIntsAndDates(e)])):t}}export{RpcClient};

package/src/clients/rpc-client.mjs

@@ -0,0 +1,275 @@
+/**
+ * JSON-RPC 2.0 Client for browser and Node.js environments (ES Module).
+ * Handles BigInt and Date serialization/deserialization automatically.
+ * 
+ * Note: We extend BigInt.prototype.toJSON to handle automatic serialization
+ * when JSON.stringify() is called, as BigInt doesn't have native JSON support.
+ */
+
+// Extend BigInt prototype to handle JSON serialization
+if (typeof BigInt !== 'undefined' && !BigInt.prototype.toJSON) {
+  BigInt.prototype.toJSON = function() { return this.toString(); };
+}
+
+// Polyfill for Node.js environments that don't have fetch
+let fetchFn;
+if (typeof fetch !== 'undefined') {
+  fetchFn = fetch;
+} else {
+  // Try to use node-fetch if available, otherwise use built-in fetch in Node.js 18+
+  try {
+    const { default: nodeFetch } = await import('node-fetch');
+    fetchFn = nodeFetch;
+  } catch (e) {
+    // For Node.js 18+, use global fetch
+    if (typeof globalThis !== 'undefined' && globalThis.fetch) {
+      fetchFn = globalThis.fetch;
+    } else {
+      throw new Error('fetch is not available. Please install node-fetch or use Node.js 18+');
+    }
+  }
+}
+
+export class RpcClient {
+  #endpoint;
+  #defaultHeaders;
+  #requestId;
+
+  /**
+   * @param {string} endpoint The JSON-RPC endpoint URL.
+   * @param {Object} [defaultHeaders={}] Optional default headers to include in requests.
+   */
+  constructor(endpoint, defaultHeaders = {}) {
+    this.#endpoint = endpoint;
+    this.#defaultHeaders = {
+      "Content-Type": "application/json", // Default header
+      ...defaultHeaders, // Merge with user-provided defaults
+    };
+    // Initialize request ID counter with timestamp + random component for uniqueness
+    this.#requestId = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+  }
+
+  /**
+   * Make a JSON-RPC call to the server.
+   * @param {string} method The RPC method name.
+   * @param {any} params The parameters to pass to the RPC method.
+   * @param {string|number|null} [id] The request ID (optional for notifications). If null, auto-generates unique ID.
+   * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
+   * @returns {Promise<any>} The result of the RPC call.
+   */
+  async call(method, params = {}, id = null, overrideHeaders = {}) {
+    // Auto-generate unique ID if not provided
+    if (id === null) {
+      id = ++this.#requestId;
+    }
+
+    const requestBody = {
+      jsonrpc: "2.0",
+      method,
+      params,
+      id,
+    };
+
+    try {
+      const response = await fetchFn(this.#endpoint, {
+        method: "POST",
+        headers: {
+          ...this.#defaultHeaders,
+          ...overrideHeaders,
+        },
+        // Since we have BigInt.prototype.toJSON, we don't need manual serialization
+        // JSON.stringify will handle BigInt and Date automatically
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+
+      const responseBody = await response.json();
+
+      if (responseBody.error) { throw responseBody.error; }
+
+      // Convert back BigInts and Dates in the result
+      return this.deserializeBigIntsAndDates(responseBody.result);
+    } catch (error) {
+      console.error("RPC call failed:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Make a JSON-RPC notification (no response expected).
+   * @param {string} method The RPC method name.
+   * @param {any} params The parameters to pass to the RPC method.
+   * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
+   * @returns {Promise<void>}
+   */
+  async notify(method, params = {}, overrideHeaders = {}) {
+    const requestBody = {
+      jsonrpc: "2.0",
+      method,
+      params,
+      // No ID for notifications
+    };
+
+    try {
+      const response = await fetchFn(this.#endpoint, {
+        method: "POST",
+        headers: {
+          ...this.#defaultHeaders,
+          ...overrideHeaders,
+        },
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      console.error("RPC notification failed:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Make a batch JSON-RPC call to the server.
+   * @param {Array<{method: string, params: any, id?: string|number|null, notification?: boolean}>} requests Array of request objects.
+   * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
+   * @returns {Promise<Array<any>>} Array of results corresponding to the requests.
+   */
+  async batch(requests, overrideHeaders = {}) {
+    const requestBodies = requests.map(req => {
+      const body = {
+        jsonrpc: "2.0",
+        method: req.method,
+        params: req.params || {},
+      };
+
+      // If it's not a notification, add ID
+      if (!req.notification) {
+        body.id = req.id !== undefined ? req.id : ++this.#requestId;
+      }
+
+      return body;
+    });
+
+    try {
+      const response = await fetchFn(this.#endpoint, {
+        method: "POST",
+        headers: {
+          ...this.#defaultHeaders,
+          ...overrideHeaders,
+        },
+        body: JSON.stringify(requestBodies),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+
+      const responseBody = await response.json();
+
+      // Handle batch response
+      if (Array.isArray(responseBody)) {
+        return responseBody.map(res => {
+          if (res.error) {
+            throw res.error;
+          }
+          return this.deserializeBigIntsAndDates(res.result);
+        });
+      } else {
+        // Single response (shouldn't happen with batch, but handle gracefully)
+        if (responseBody.error) {
+          throw responseBody.error;
+        }
+        return [this.deserializeBigIntsAndDates(responseBody.result)];
+      }
+    } catch (error) {
+      console.error("RPC batch call failed:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Recursively convert BigInt values to strings and Date objects to ISO strings
+   * so they can be JSON-serialized.
+   * @param {any} value
+   * @returns {any}
+   */
+  serializeBigIntsAndDates(value) {
+    if (typeof value === "bigint") {
+      // Convert BigInt to string
+      return value.toString();
+    } else if (Array.isArray(value)) {
+      // Recurse into arrays
+      return value.map((v) => this.serializeBigIntsAndDates(v));
+    } else if (value instanceof Date) {
+      // Convert Date to ISO string (UTC)
+      return value.toISOString();
+    } else if (value && typeof value === "object") {
+      // Recurse into plain objects
+      const result = {};
+      for (const [key, val] of Object.entries(value)) {
+        result[key] = this.serializeBigIntsAndDates(val);
+      }
+      return result;
+    }
+
+    // If it's neither an array, an object, a Date, nor a bigint, return as-is
+    return value;
+  }
+
+  /**
+   * Recursively convert stringified BigInt values back to BigInt
+   * and ISO 8601 date strings back to Date objects.
+   *
+   * @param {any} value The value to deserialize.
+   * @returns {any}
+   */
+  deserializeBigIntsAndDates(value) {
+    // More comprehensive ISO date regex that handles:
+    // - UTC: 2023-01-01T12:00:00.000Z
+    // - With timezone: 2023-01-01T12:00:00.000+01:00
+    // - Without timezone: 2023-01-01T12:00:00.000 (treated as local)
+    const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
+
+    // 1. Check if it's a string that might be a BigInt or a Date
+    if (typeof value === "string") {
+      // BigInt check: matches digits (including negative), optionally ending in "n"
+      // e.g., "42n", "42", "-42n", "-42"
+      if (/^-?\d+n?$/.test(value)) {
+        return BigInt(value.replace(/n$/, ""));
+      }
+      // Date check: matches an ISO 8601 string
+      if (ISO_DATE_REGEX.test(value)) {
+        const date = new Date(value);
+        // Ensure it's valid
+        if (!isNaN(date.getTime())) {
+          return date;
+        }
+      }
+    }
+
+    // 2. If it's an array, handle each element
+    if (Array.isArray(value)) {
+      return value.map((v) => this.deserializeBigIntsAndDates(v));
+    }
+
+    // 3. If it's a plain object, recurse into each property
+    if (value && typeof value === "object") {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, val]) => [
+          key,
+          this.deserializeBigIntsAndDates(val),
+        ])
+      );
+    }
+
+    // 4. Fallback for primitives, etc.
+    return value;
+  }
+}
+
+// Export only the main class
+export { RpcClient };

package/src/index.d.ts

@@ -0,0 +1,147 @@
+// Type definitions for rpc-express-toolkit
+
+import type { Router, Request, Response } from "express";
+
+/**
+ * Definiamo il tipo della funzione "handler" che aggiungiamo tramite `addMethod`.
+ */
+type JSONRPCHandler<C> = (req: Request, context: C, params: any) => any | Promise<any>;
+
+interface JSONRPCError {
+  code: number;
+  message: string;
+  data?: any;
+}
+
+interface JSONRPCResponsePayload {
+  id?: string | number | null;
+  result?: any;
+  error?: JSONRPCError;
+}
+
+/**
+ * The main RpcEndpoint class for JSON-RPC 2.0 endpoints.
+ * The generics `<C>` represents the "context" type.
+ */
+declare class RpcEndpoint<C> {
+  /**
+   * Constructor.
+   * 
+   * @param router   - An Express.Router object
+   * @param context  - Generic object that will be passed to method handlers
+   * @param endpoint - Path on which to respond to JSON-RPC calls (default: "/api")
+   */
+  constructor(router: Router, context: C, endpoint?: string);
+
+  /**
+   * Returns the endpoint path, e.g. "/api".
+   */
+  get endpoint(): string;
+
+  /**
+   * Returns the map of all registered methods.
+   */
+  get methods(): { [methodName: string]: JSONRPCHandler<C> };
+
+  /**
+   * Adds a JSON-RPC method (e.g. "getUserData").
+   * 
+   * @param name    - Method name
+  /**
+   * Adds a JSON-RPC method (e.g. "getUserData").
+   * 
+   * @param name    - Method name
+   * @param handler - Handler function that receives (req, context, params)
+   */
+  addMethod(name: string, handler: JSONRPCHandler<C>): void;
+
+  /**
+   * Serve client scripts (for calling JSON-RPC from browser).
+   * 
+   * @param router - An Express.Router object
+   * @param url    - Path from which to serve scripts (default: "/vendor/rpc-client")
+   */
+  static serveScripts(router: Router, url?: string): void;
+
+  /**
+   * Send a JSON-RPC 2.0 response to the client.
+   */
+  reply(res: Response, responsePayload: JSONRPCResponsePayload): void;
+
+  /**
+   * Recursively serialize BigInt and Date to JSON-safe string formats.
+   */
+  serializeBigIntsAndDates(value: any): any;
+
+  /**
+   * Recursively deserialize strings representing BigInt and Date
+   * (produced by `serializeBigIntsAndDates`) to reconstruct original types.
+   */
+  deserializeBigIntsAndDates(value: any): any;
+}
+
+/**
+ * JSON-RPC 2.0 Client for Node.js environments.
+ * Handles BigInt and Date serialization/deserialization automatically.
+ */
+declare class RpcClient {
+  /**
+   * Client constructor.
+   * 
+   * @param endpoint - JSON-RPC endpoint URL
+   * @param defaultHeaders - Default headers to include in requests
+   */
+  constructor(endpoint: string, defaultHeaders?: Record<string, string>);
+
+  /**
+   * Make a JSON-RPC call to the server.
+   * 
+   * @param method - RPC method name
+   * @param params - Parameters to pass to the method
+   * @param id - Request ID (optional for notifications)
+   * @param overrideHeaders - Headers to override defaults for this request
+   * @returns Promise with the RPC call result
+   */
+  call(method: string, params?: any, id?: string | number | null, overrideHeaders?: Record<string, string>): Promise<any>;
+
+  /**
+   * Make a JSON-RPC notification (no response expected).
+   * 
+   * @param method - RPC method name
+   * @param params - Parameters to pass to the method
+   * @param overrideHeaders - Headers to override defaults for this request
+   */
+  notify(method: string, params?: any, overrideHeaders?: Record<string, string>): Promise<void>;
+
+  /**
+   * Make a batch JSON-RPC call.
+   * 
+   * @param requests - Array of request objects
+   * @param overrideHeaders - Headers to override defaults for this request
+   * @returns Promise with array of results
+   */
+  batch(requests: Array<{method: string, params?: any, id?: string|number|null, notification?: boolean}>, overrideHeaders?: Record<string, string>): Promise<any[]>;
+
+  /**
+   * Recursively serialize BigInt and Date to JSON-safe string formats.
+   */
+  serializeBigIntsAndDates(value: any): any;
+
+  /**
+   * Recursively deserialize strings representing BigInt and Date.
+   */
+  deserializeBigIntsAndDates(value: any): any;
+}
+
+/**
+ * Main export structure.
+ */
+declare const Main: {
+  new <C>(router: Router, context: C, endpoint?: string): RpcEndpoint<C>;
+  prototype: RpcEndpoint<any>;
+  serveScripts(router: Router, url?: string): void;
+  RpcEndpoint: typeof RpcEndpoint;
+  RpcClient: typeof RpcClient;
+};
+
+export = Main;