@mr-zwets/bchn-api-wrapper 1.0.1

package/src/restClient.ts

@@ -0,0 +1,119 @@
+import type { RestClientConfig, formatOptions, ResponseType } from "./interfaces/interfaces.js";
+import type {
+  BlockInfoNoTxDetails,
+  BlockInfoTxDetails,
+  ChainInfo,
+  HeaderInfo,
+  MempoolContent,
+  MempoolInfo,
+  TxDetails,
+  UtxosInfo
+} from "./interfaces/restInterfaces/interfaces.js";
+import { validateUrl } from "./utils/utils.js";
+
+export class BchnRestClient {
+  private baseUrl: string;
+  private timeoutMs: number;
+  private logger: Console;
+
+  constructor(config: RestClientConfig) {
+    this.baseUrl = validateUrl(config.url);
+    this.timeoutMs = config.timeoutMs ?? 5000;
+    this.logger = config.logger ?? console;
+  }
+
+  private async fetchFromNode<T, TFormat extends formatOptions>(
+    endpoint: string,
+    format: TFormat
+  ): Promise<ResponseType<TFormat, T>> {
+    try {
+      const response = await fetch(`${this.baseUrl}/rest/${endpoint}`, {
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+      
+      if (!response.ok) {
+        throw new Error(`Error fetching data from ${endpoint}: ${response.statusText}`);
+      }
+      
+      if (format === 'json') {
+        return await response.json() as ResponseType<TFormat, T>;
+      } else {
+        return await response.text() as ResponseType<TFormat, T>;  // For 'bin' and 'hex', return raw text
+      }
+    } catch(error) {
+      let errorMessage: string | undefined
+      
+      // Check if the error is due to timeout or other fetch-related issues
+      if (typeof error === 'string') {
+        errorMessage = error;
+        this.logger.error(error);
+      } else if (error instanceof DOMException && error.name === 'TimeoutError') {
+        // If error is an instance DOMException TimeoutError
+        errorMessage = 'Request timed out';
+        this.logger.error(`Request to ${endpoint} timed out after ${this.timeoutMs} ms`);
+      } else {
+        this.logger.error(`Unknown error occurred during request to ${endpoint}`);
+        throw new Error(`Unknown error: ${error}`);
+      }
+      
+      // Always rethrow the error after logging
+      throw new Error(errorMessage);
+    }
+  }
+
+  // Get transaction details by transaction hash
+  async getTransaction<TFormat extends formatOptions = 'json'>(
+    txid: string, format:TFormat = 'json' as TFormat
+  ) {
+    return this.fetchFromNode<TxDetails, TFormat>(`tx/${txid}.${format}`, format);
+  }
+
+  // getBlock overload signatures 
+  // This is needed so the getBlock return type can depend on the 'includeTxDetails' boolean flag
+  async getBlock<TFormat extends formatOptions = 'json'>(
+    blockhash: string, includeTxDetails: true, format?:TFormat
+  ): Promise<TFormat extends 'json' ? BlockInfoTxDetails : string>;
+
+  async getBlock<TFormat extends formatOptions = 'json'>(
+    blockhash: string, includeTxDetails: false, format?:TFormat
+  ): Promise<TFormat extends 'json' ? BlockInfoNoTxDetails : string>;
+
+  // getBlock Implementation
+  async getBlock<TFormat extends formatOptions = 'json'>(
+    blockhash: string, includeTxDetails: boolean, format:TFormat = 'json' as TFormat
+  ): Promise<any> {
+    const path = includeTxDetails ? 'block' : 'block/notxdetails';
+    return this.fetchFromNode(`${path}/${blockhash}.${format}`, format);
+  }
+
+  // Get block headers starting from a specific block hash
+  async getBlockHeaders<TFormat extends formatOptions = 'json'>(
+    count: number, blockhash: string, format:TFormat = 'json' as TFormat
+  ) {
+    return this.fetchFromNode<HeaderInfo, TFormat>(`headers/${count}/${blockhash}.${format}`, format);
+  }
+
+  // Get chain info (chain state details)
+  async getChainInfo() {
+    return this.fetchFromNode<ChainInfo, 'json'>('chaininfo.json', 'json');
+  }
+
+  // Query UTXO set based on specific outpoints (txid and vout)
+  async getUTXOs<TFormat extends formatOptions = 'json'>(
+    checkmempool: boolean, outpoints: string[], format:TFormat = 'json' as TFormat
+  ) {
+    const path = (checkmempool ? 'checkmempool/' : '') + outpoints.join('/');
+    const endpoint = `getutxos/${path}.${format}`;
+    return this.fetchFromNode<UtxosInfo, TFormat>(endpoint, format);
+  }
+
+  // Get mempool information (basic)
+  async getMempoolInfo() {
+    return this.fetchFromNode<MempoolInfo, 'json'>('mempool/info.json', 'json');
+  }
+
+  // Get mempool contents (transactions currently in the mempool)
+  async getMempoolContents() {
+    return this.fetchFromNode<MempoolContent, 'json'>('mempool/contents.json', 'json');
+  }
+}

package/src/rpcClient.ts

@@ -0,0 +1,93 @@
+import type { RpcClientConfig, RpcRequest } from "./interfaces/interfaces.js";
+import { getRandomId, validateAndConstructUrl } from "./utils/utils.js";
+import { RetryLimitExceededError } from "./utils/errors.js";
+
+export class BchnRpcClient {
+  private url: string
+  private rpcUser: string
+  private rpcPassword: string
+  
+  private maxRetries: number // number of retries before throwing an exception
+  private retryDelayMs: number // delay between each retry
+  private logger: typeof console // logger
+  private timeoutMs: number // max timeout for each retry
+
+  constructor(config: RpcClientConfig){
+    this.url = validateAndConstructUrl(config)
+    if(!config.rpcUser) throw new Error('Need to provide rpcUser in config')
+    if(!config.rpcPassword) throw new Error('Need to provide rpcPassword in config')
+    this.rpcUser = config.rpcUser;       
+    this.rpcPassword= config.rpcPassword;  
+
+    // optional config
+    this.maxRetries = config.maxRetries ?? 0;       
+    this.retryDelayMs= config.retryDelayMs ?? 100;  
+    this.logger = config.logger ?? console;         
+    this.timeoutMs = config.timeoutMs ?? 5000;      
+  }
+
+  async request<T extends RpcRequest>(
+    endpoint: T['method'],
+    ...params: T['params']
+  ): Promise<T['response']> {
+    const auth = Buffer.from(`${this.rpcUser}:${this.rpcPassword}`).toString('base64');
+    
+    // Retry logic
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        // Send the request with a timeout and retries
+        const response = await fetch(this.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Basic ${auth}`
+          },
+          body: JSON.stringify({ jsonrpc: '2.0', method: endpoint, params, id: getRandomId() }),
+          signal: AbortSignal.timeout(this.timeoutMs),
+        });
+  
+        const result = await response.json();
+  
+        // Handle response errors
+        if (!response.ok || result.error) {
+          throw new Error(`Error: ${result.error?.message || response.statusText}`);
+        }
+  
+        return result.result as T['response'];  // Return the result if successful
+  
+      } catch (error) {
+        let errorMessage: string | undefined
+        
+        // Check if the error is due to timeout or other fetch-related issues
+        if(typeof error == 'string'){
+          errorMessage = error
+          this.logger.error(error)
+        }
+        else if (error instanceof DOMException && error.name === 'TimeoutError') {
+          // If error is an instance DOMException TimeoutError
+          errorMessage = error.message
+          this.logger.error(`Request timed out after ${this.timeoutMs} ms`);
+        }
+        else if (error instanceof Error) {
+          // If error is an instance of Error, you can safely access its properties
+          errorMessage = error.message
+          this.logger.error(`Request failed with error: ${error.message}`);
+          
+        }
+  
+        // Retry if allowed
+        if (attempt < this.maxRetries) {
+          this.logger.warn(`Retrying request... (${attempt + 1}/${this.maxRetries})`);
+          await new Promise(res => setTimeout(res, this.retryDelayMs));  // Wait before retrying
+        } else {
+          // If no retries are left, throw the final error
+          throw new RetryLimitExceededError(`Request failed after ${this.maxRetries + 1} attempts: ${errorMessage}`);
+        }
+      }
+    }
+  
+    // This line ensures TypeScript is satisfied that a value will always be returned, but
+    // it should never be reached if the retries fail, as the last attempt should throw an error.
+    throw new Error('Request failed unexpectedly');
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,6 @@
+export class RetryLimitExceededError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RetryLimitExceededError';
+  }
+}

package/src/utils/utils.ts

@@ -0,0 +1,55 @@
+import type {
+  RpcClientConfig,
+  RpcClientUrlConfig,
+  RpcClientHostConfig,
+} from "../interfaces/interfaces.js";
+
+export function getRandomId(): number {
+  return Math.floor(Math.random() * 100000);
+}
+
+// A utility function to validate and construct the URL from the RpcClientConfig object
+export function validateAndConstructUrl(config: RpcClientConfig): string {
+  let url: string
+  if (isUrlConfig(config)) {
+    url = validateUrl(config.url)
+  } else if (isHostConfig(config)) {
+    const { protocol, host, port } = config;
+    if (protocol !== 'http' && protocol !== 'https') {
+      throw new Error("Protocol should be 'http' or 'https'");
+    }
+    url = validateUrl(`${protocol}://${host}:${port}`)
+  } else {
+    throw new Error('Invalid configuration: Either provide the url or protocol/host/port');
+  }
+  return url
+}
+
+// A utility function to validate a URL
+export function validateUrl(url: string) {
+  if(!url) throw new Error('URL is required');
+  try {
+    new URL(url);
+  } catch (err) {
+    throw new Error('Invalid URL format');
+  }
+  return url
+}
+
+// Type guard to check if the config is RpcClientUrlConfig
+function isUrlConfig(config: RpcClientConfig): config is RpcClientUrlConfig {
+  return 'url' in config;
+}
+
+// Type guard to check if the config is RpcClientHostConfig
+function isHostConfig(config: RpcClientConfig): config is RpcClientHostConfig {
+  return 'protocol' in config && 'hostname' in config && 'port' in config;
+}
+
+export enum BchnNetworkPort {
+  Mainnet = 8332,
+  Testnet = 18332,
+  Testnet4 = 28332,
+  Scalenet = 38332,
+  Regtest = 18443
+}

package/test/restClient.test.ts

@@ -0,0 +1,32 @@
+import { BchnRestClient } from '../src/index.js';
+
+describe('BchnRestClient URL validation tests', () => {
+  it('should create an instance with a valid URL', () => {
+    const client = new BchnRestClient({url: 'http://localhost:8332'});
+    expect(client).toBeInstanceOf(BchnRestClient);
+  });
+
+  it('should throw an error for an invalid URL', () => {
+    expect(() => new BchnRestClient({url: 'invalid-url'})).toThrow('Invalid URL');
+  });
+
+  it('should throw an error if the URL is missing', () => {
+    expect(() => new BchnRestClient({url: ''})).toThrow('URL is required');
+  });
+});
+
+describe('BchnRestClient Timeout Handling', () => {
+  const config = {
+    url: 'http://localhost:8332',
+    timeoutMs: 1000, // 1 second timeout
+  };
+  const restClient = new BchnRestClient(config);
+
+  it('should throw a timeout error if the request exceeds the timeout limit', async () => {
+    await expect(restClient.getChainInfo()).rejects.toThrow('Request timed out');
+  });
+
+  it('should not return a timeout error if the request completes in time', async () => {
+    await expect(restClient.getMempoolInfo()).resolves.toEqual({});
+  });
+});

package/test/rpcClient.test.ts

@@ -0,0 +1,115 @@
+import { BchnRpcClient, type GetBestBlockHash, type GetBlockCount, type GetBlockHash, type RpcClientConfig } from '../src/index.js';
+
+describe('BchnRpcClient should have the correct constructor arguments', () => {
+  it('should create an instance with a valid URL', () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword'
+    }
+    const client = new BchnRpcClient(config);
+    expect(client).toBeInstanceOf(BchnRpcClient);
+  });
+
+  it('should throw an error for an invalid URL', () => {
+    const config = {
+      url: 'invalid-url',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword'
+    }
+    expect(() => new BchnRpcClient(config)).toThrow('Invalid URL');
+  });
+
+  it('should throw an error if the URL is empty', () => {
+    const config = {
+      url: '',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword'
+    }
+    expect(() => new BchnRpcClient(config)).toThrow('URL is required');
+  });
+
+  it('should throw an error if the URL is missing', () => {
+    const config = {
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword'
+    } as RpcClientConfig
+    expect(() => new BchnRpcClient(config)).toThrow('Invalid configuration: Either provide the url or protocol/host/port');
+  });
+
+  it('should throw an error if rpcUser is missing', () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcPassword: 'rpcPassword'
+    } as RpcClientConfig
+    expect(() => new BchnRpcClient(config)).toThrow('Need to provide rpcUser in config');
+  });
+
+  it('should throw an error if rpcPassword is missing', () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser'
+    } as RpcClientConfig
+    expect(() => new BchnRpcClient(config)).toThrow('Need to provide rpcPassword in config');
+  });
+});
+
+describe('BchnRpcClient Timeout and Retry Handling', () => {
+  it('should throw a timeout error if the request exceeds the timeout limit', async () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword',
+      timeoutMs: 1000,
+    }
+    const rpcClient = new BchnRpcClient(config);
+
+    await expect(rpcClient.request("getbestblockhash")).rejects.toThrow('Request failed after 1 attempts: The operation was aborted due to timeout');
+  });
+
+  it('should not return a timeout error if the request completes in time', async () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword',
+      timeoutMs: 1000,
+    }
+    const rpcClient = new BchnRpcClient(config);
+
+    await expect(rpcClient.request<GetBlockCount>("getblockcount")).resolves.toEqual({});
+  });
+
+  it('should return an RetryLimitExceededError if all retries fail', async () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword',
+      maxRetries: 3,
+      timeoutMs: 1000,
+    }
+    const rpcClient = new BchnRpcClient(config);
+    await expect(rpcClient.request<GetBestBlockHash>("getbestblockhash")).rejects.toThrow("Request failed after 4 attempts: The operation was aborted due to timeout");
+  });
+});
+
+describe('BchnRpcClient Handling of Parameters', () => {
+  it('should error with incorrect number of params', async () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword',
+    }
+    const rpcClient = new BchnRpcClient(config);
+    await expect(rpcClient.request("getblockhash")).rejects.toThrow("Request failed after 1 attempts: Error: Invalid Request");
+  })
+
+  it('should not error with correct number of params', async () => {
+    const config = {
+      url: 'http://localhost:8332',
+      rpcUser: 'rpcUser',
+      rpcPassword: 'rpcPassword',
+    }
+    const rpcClient = new BchnRpcClient(config);
+    await expect(rpcClient.request<GetBlockHash>("getblockhash", 5)).resolves.toEqual({});
+  })
+})

package/test/setupTests.ts

@@ -0,0 +1,54 @@
+import { http, delay, HttpResponse } from 'msw';
+import { setupServer, SetupServerApi } from 'msw/node';
+
+type jsonResult = { method: string; params?: unknown[] } | null | undefined
+
+const server: SetupServerApi = setupServer(
+  // Mock endpoint with a delay to simulate timeout
+  http.get('http://localhost:8332/rest/chaininfo.json', async() => {
+    // Introduce a delay longer than the timeout setting to simulate a timeout scenario
+    await delay(3000)
+    return HttpResponse.json({})
+  }),
+
+  http.get('http://localhost:8332/rest/mempool/info.json', async() => {
+    // Mock normally working REST endpoint
+    await delay(500)
+    return HttpResponse.json({})
+  }),
+
+  http.post('http://localhost:8332', async ({ request }) => {
+    const json = await request.json() as jsonResult;
+
+    if (json === null || json === undefined) {
+      throw new Error('Invalid JSON response');
+    }    
+
+    // Introduce a delay longer than the timeout setting to simulate a timeout scenario
+    if (json.method === 'getbestblockhash') {
+      await delay(3000)
+      return HttpResponse.json({"jsonrpc": "2.0", "result": {}, "id": 4})
+    }
+
+    if (json.method === 'getblockcount') {
+      // Mock normally working RPC command
+      await delay(500)
+      return HttpResponse.json({"jsonrpc": "2.0", "result": {}, "id": 5})
+    }
+
+    if (json.method === 'getblockhash') {
+      // Mock normally working RPC command
+      await delay(500)
+      if (json.params?.[0]) {
+        return HttpResponse.json({"jsonrpc": "2.0", "result": {}, "id": 6})
+      } else {
+        return HttpResponse.json({"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": 7})
+      }
+    }
+  })
+);
+
+// Start the server before tests and reset handlers after each test
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());

package/test/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["**/*"],
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "verbatimModuleSyntax": true,
+    "moduleResolution": "NodeNext",
+    "target": "ES6",
+    "strict": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "types": ["vitest/globals"],
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./test/setupTests.ts']
+  },
+})