@mr-zwets/bchn-api-wrapper 1.0.1

package/dist/restClient.js

@@ -0,0 +1,100 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { validateUrl } from "./utils/utils.js";
+export class BchnRestClient {
+    constructor(config) {
+        var _a, _b;
+        this.baseUrl = validateUrl(config.url);
+        this.timeoutMs = (_a = config.timeoutMs) !== null && _a !== void 0 ? _a : 5000;
+        this.logger = (_b = config.logger) !== null && _b !== void 0 ? _b : console;
+    }
+    fetchFromNode(endpoint, format) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield 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 yield response.json();
+                }
+                else {
+                    return yield response.text(); // For 'bin' and 'hex', return raw text
+                }
+            }
+            catch (error) {
+                let errorMessage;
+                // 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
+    getTransaction(txid_1) {
+        return __awaiter(this, arguments, void 0, function* (txid, format = 'json') {
+            return this.fetchFromNode(`tx/${txid}.${format}`, format);
+        });
+    }
+    // getBlock Implementation
+    getBlock(blockhash_1, includeTxDetails_1) {
+        return __awaiter(this, arguments, void 0, function* (blockhash, includeTxDetails, format = 'json') {
+            const path = includeTxDetails ? 'block' : 'block/notxdetails';
+            return this.fetchFromNode(`${path}/${blockhash}.${format}`, format);
+        });
+    }
+    // Get block headers starting from a specific block hash
+    getBlockHeaders(count_1, blockhash_1) {
+        return __awaiter(this, arguments, void 0, function* (count, blockhash, format = 'json') {
+            return this.fetchFromNode(`headers/${count}/${blockhash}.${format}`, format);
+        });
+    }
+    // Get chain info (chain state details)
+    getChainInfo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode('chaininfo.json', 'json');
+        });
+    }
+    // Query UTXO set based on specific outpoints (txid and vout)
+    getUTXOs(checkmempool_1, outpoints_1) {
+        return __awaiter(this, arguments, void 0, function* (checkmempool, outpoints, format = 'json') {
+            const path = (checkmempool ? 'checkmempool/' : '') + outpoints.join('/');
+            const endpoint = `getutxos/${path}.${format}`;
+            return this.fetchFromNode(endpoint, format);
+        });
+    }
+    // Get mempool information (basic)
+    getMempoolInfo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode('mempool/info.json', 'json');
+        });
+    }
+    // Get mempool contents (transactions currently in the mempool)
+    getMempoolContents() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode('mempool/contents.json', 'json');
+        });
+    }
+}

package/dist/rpcClient.d.ts

@@ -0,0 +1,12 @@
+import type { RpcClientConfig, RpcRequest } from "./interfaces/interfaces.js";
+export declare class BchnRpcClient {
+    private url;
+    private rpcUser;
+    private rpcPassword;
+    private maxRetries;
+    private retryDelayMs;
+    private logger;
+    private timeoutMs;
+    constructor(config: RpcClientConfig);
+    request<T extends RpcRequest>(endpoint: T['method'], ...params: T['params']): Promise<T['response']>;
+}

package/dist/rpcClient.js

@@ -0,0 +1,85 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { getRandomId, validateAndConstructUrl } from "./utils/utils.js";
+import { RetryLimitExceededError } from "./utils/errors.js";
+export class BchnRpcClient {
+    constructor(config) {
+        var _a, _b, _c, _d;
+        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 = (_a = config.maxRetries) !== null && _a !== void 0 ? _a : 0;
+        this.retryDelayMs = (_b = config.retryDelayMs) !== null && _b !== void 0 ? _b : 100;
+        this.logger = (_c = config.logger) !== null && _c !== void 0 ? _c : console;
+        this.timeoutMs = (_d = config.timeoutMs) !== null && _d !== void 0 ? _d : 5000;
+    }
+    request(endpoint, ...params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            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 = yield 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 = yield response.json();
+                    // Handle response errors
+                    if (!response.ok || result.error) {
+                        throw new Error(`Error: ${((_a = result.error) === null || _a === void 0 ? void 0 : _a.message) || response.statusText}`);
+                    }
+                    return result.result; // Return the result if successful
+                }
+                catch (error) {
+                    let errorMessage;
+                    // 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})`);
+                        yield 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/dist/utils/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class RetryLimitExceededError extends Error {
+    constructor(message: string);
+}

package/dist/utils/errors.js

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

package/dist/utils/utils.d.ts

@@ -0,0 +1,11 @@
+import type { RpcClientConfig } from "../interfaces/interfaces.js";
+export declare function getRandomId(): number;
+export declare function validateAndConstructUrl(config: RpcClientConfig): string;
+export declare function validateUrl(url: string): string;
+export declare enum BchnNetworkPort {
+    Mainnet = 8332,
+    Testnet = 18332,
+    Testnet4 = 28332,
+    Scalenet = 38332,
+    Regtest = 18443
+}

package/dist/utils/utils.js

@@ -0,0 +1,49 @@
+export function getRandomId() {
+    return Math.floor(Math.random() * 100000);
+}
+// A utility function to validate and construct the URL from the RpcClientConfig object
+export function validateAndConstructUrl(config) {
+    let url;
+    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) {
+    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) {
+    return 'url' in config;
+}
+// Type guard to check if the config is RpcClientHostConfig
+function isHostConfig(config) {
+    return 'protocol' in config && 'hostname' in config && 'port' in config;
+}
+export var BchnNetworkPort;
+(function (BchnNetworkPort) {
+    BchnNetworkPort[BchnNetworkPort["Mainnet"] = 8332] = "Mainnet";
+    BchnNetworkPort[BchnNetworkPort["Testnet"] = 18332] = "Testnet";
+    BchnNetworkPort[BchnNetworkPort["Testnet4"] = 28332] = "Testnet4";
+    BchnNetworkPort[BchnNetworkPort["Scalenet"] = 38332] = "Scalenet";
+    BchnNetworkPort[BchnNetworkPort["Regtest"] = 18443] = "Regtest";
+})(BchnNetworkPort || (BchnNetworkPort = {}));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mr-zwets/bchn-api-wrapper",
+  "version": "1.0.1",
+  "description": "a Typescript wrapper for interacting with the Bitcoin Cash Node (BCHN) API ",
+  "type": "module",
+  "main": "dist/index.js",
+  "author": "mr-zwets",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest"
+  },
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.7.7",
+    "cross-env": "^7.0.3",
+    "msw": "^2.5.1",
+    "tsc": "^2.0.4",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mr-zwets/bchn-api-wrapper.git"
+  },
+  "keywords": [
+    "bitcoin-cash",
+    "bitcoincash",
+    "bchn",
+    "bitcoind",
+    "rpc"
+  ],
+  "types": "./dist/index.d.ts",
+  "bugs": {
+    "url": "https://github.com/mr-zwets/bchn-api-wrapper/issues"
+  },
+  "homepage": "https://github.com/mr-zwets/bchn-api-wrapper#readme"
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './interfaces/interfaces.js'
+export * from './interfaces/rpcInterfaces/index.js'
+export { BchnRpcClient } from './rpcClient.js'
+export { BchnRestClient } from './restClient.js'

package/src/interfaces/interfaces.ts

@@ -0,0 +1,87 @@
+export interface BaseRpcClientConfig {
+  rpcUser: string;
+  rpcPassword: string;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  logger?: typeof console ;
+  timeoutMs?: number;
+}
+
+export interface RpcClientUrlConfig extends BaseRpcClientConfig {
+  url: string;
+}
+
+export interface RpcClientHostConfig extends BaseRpcClientConfig {
+  protocol: 'http' | 'https';
+  host: string;
+  port: number;
+}
+
+export type RpcClientConfig = RpcClientUrlConfig | RpcClientHostConfig
+
+export type RPCParameter = string | number | boolean | undefined | object;
+declare type RequestResponse = object | string | number | boolean | null | RequestResponse[];
+
+export interface RpcRequest {
+  method: string;
+  params: Array<RPCParameter>;
+  response: RequestResponse;
+}
+
+export interface RestClientConfig {
+  url: string;
+  logger?: typeof console ;
+  timeoutMs?: number;
+}
+
+
+export type formatOptions = 'bin' | 'hex' | 'json'
+
+// Conditional type to return the appropriate data type based on format
+export type ResponseType<TFormat extends formatOptions, TJson> = 
+  TFormat extends 'json' ? TJson :
+  TFormat extends 'hex' | 'bin' ? string :
+  never;
+
+// General interfaces used in both REST & RPC endpoints
+export interface Transaction {
+  txid: string;
+  hash: string;
+  size: number;
+  version: number;
+  locktime: number;
+  vin: TransactionInput[];
+  vout: TransactionOutput[];
+}
+
+export interface TransactionInput {
+  txid: string;
+  vout: number;
+  scriptSig: {
+    asm: string;
+    hex: string;
+  };
+  sequence: number;
+}
+
+export interface TransactionOutput {
+  value: number;
+  n: number;
+  scriptPubKey: {
+    asm: string;
+    hex: string;
+    reqSigs: number;
+    type: string;
+    addresses: string[];
+    tokenData: TokenData;
+  }
+}
+
+export interface TokenData {
+  category : string;
+  amount: string;
+  nft?: {
+    capability: 'none' | 'mutable' | 'minting';
+    commitment: string;
+  }
+}

package/src/interfaces/restInterfaces/interfaces.ts

@@ -0,0 +1,117 @@
+import type { Transaction } from "../interfaces.js";
+
+export interface BlockInfoNoTxDetails {
+  hash: string;
+  confirmations: number;
+  size: number;
+  height: number;
+  version: number;
+  versionHex: string;
+  merkleroot: string;
+  tx : string[]
+  time: number;
+  mediantime: number;
+  nonce: number;
+  bits: string;
+  difficulty: number;
+  chainwork: string;
+  nTx: number;
+  previousblockhash: string;
+  nextblockhash: string;
+  ablastate: {
+    epsilon: number;
+    beta: number;
+    blocksize: number;
+    blocksizelimit: number;
+    nextblocksizelimit: number;
+  }
+}
+
+export interface BlockInfoTxDetails extends Omit<BlockInfoNoTxDetails, 'tx'>{
+  tx: Transaction[]
+}
+
+export interface HeaderInfo {
+  hash: string;
+  confirmations: number;
+  height: number;
+  version: number;
+  versionHex: string;
+  merkleroot: string;
+  time: number;
+  mediantime: number;
+  nonce: number;
+  bits: string;
+  difficulty: number;
+  chainwork: string;
+  nTx: number;
+  previousblockhash: string;
+  nextblockhash: string;
+  ablastate: {
+    epsilon: number;
+    beta: number;
+    blocksize: number;
+    blocksizelimit: number;
+    nextblocksizelimit: number;
+  }
+}
+
+export interface ChainInfo {
+  chain: 'main' | 'test' | 'regtest';
+  blocks: number;
+  headers: number;
+  bestblockhash: string;
+  difficulty: number;
+  mediantime: number;
+  verificationprogress: number;
+  initialblockdownload: boolean,
+  chainwork: string;
+  size_on_disk: number;
+  pruned: boolean;
+  warnings: string;
+}
+
+export interface UtxosInfo {
+  chaintipHash: string;
+  chainHeight: number;
+  utxos: {
+    scriptPubKey: {
+      addresses: string[];
+      type: string;
+      hex: string;
+      reqSigs: number;
+      asm: string;
+    },
+    value: number
+    height: number
+    txvers: number
+  }[]
+  bitmap: string;
+}
+
+export interface MempoolInfo {
+  loaded: boolean;
+  size: number;
+  bytes: number;
+  usage: number;
+  maxmempool: number;
+  mempoolminfee: number;
+  minrelaytxfee: number;
+}
+
+export interface MempoolContent {
+  [txid: string]: {
+    fees: {
+      base: number;
+      modified: number;
+    },
+    size: number;
+    time: number;
+    depends: string[];
+    spentby: string[];
+  }
+}
+
+export interface TxDetails extends Transaction {
+  blockhash: string;
+}