@mr-zwets/bchn-api-wrapper 1.0.2 → 1.0.3

package/dist/src/restClient.js

@@ -0,0 +1,113 @@
+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";
+/** REST client for read-only BCHN blockchain access via the REST interface. */
+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);
+            }
+        });
+    }
+    /** Returns transaction details by txid. */
+    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);
+        });
+    }
+    /** Returns 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);
+        });
+    }
+    /** Returns current chain state (network, sync progress, best block). */
+    getChainInfo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode('chaininfo.json', 'json');
+        });
+    }
+    /** Queries UTXO set for specific outpoints. Outpoints format: "txid-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);
+        });
+    }
+    /** Returns mempool statistics (size, bytes, fee rates). */
+    getMempoolInfo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode('mempool/info.json', 'json');
+        });
+    }
+    /** Returns all transactions currently in the mempool. */
+    getMempoolContents() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode('mempool/contents.json', 'json');
+        });
+    }
+    /** Returns block with bytecode pattern data (v29.0.0+). */
+    getBlockWithPatterns(blockhash) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode(`block/withpatterns/${blockhash}.json`, 'json');
+        });
+    }
+    /** Returns transaction with bytecode pattern data (v29.0.0+). */
+    getTransactionWithPatterns(txid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchFromNode(`tx/withpatterns/${txid}.json`, 'json');
+        });
+    }
+}

package/dist/src/rpcClient.d.ts

@@ -0,0 +1,19 @@
+import type { RpcClientConfig, RpcRequest } from "./interfaces/interfaces.js";
+/** RPC client for full BCHN node interaction via JSON-RPC. */
+export declare class BchnRpcClient {
+    private url;
+    private rpcUser;
+    private rpcPassword;
+    private maxRetries;
+    private retryDelayMs;
+    private logger;
+    private timeoutMs;
+    constructor(config: RpcClientConfig);
+    /**
+     * Sends a typed RPC request to the BCHN node.
+     * @example
+     * const result = await client.request<GetBlockCount>("getblockcount");
+     * const block = await client.request<GetBlockVerbosity1>("getblock", hash, 1);
+     */
+    request<T extends RpcRequest>(endpoint: T['method'], ...params: T['params']): Promise<T['response']>;
+}

package/dist/src/rpcClient.js

@@ -0,0 +1,92 @@
+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";
+/** RPC client for full BCHN node interaction via JSON-RPC. */
+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;
+    }
+    /**
+     * Sends a typed RPC request to the BCHN node.
+     * @example
+     * const result = await client.request<GetBlockCount>("getblockcount");
+     * const block = await client.request<GetBlockVerbosity1>("getblock", hash, 1);
+     */
+    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/src/utils/errors.d.ts

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

package/dist/src/utils/errors.js

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

package/dist/src/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/src/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

@@ -1,11 +1,15 @@
 {
   "name": "@mr-zwets/bchn-api-wrapper",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "a Typescript wrapper for interacting with the Bitcoin Cash Node (BCHN) API ",
   "type": "module",
+  "files": [
+    "dist"
+  ],
   "main": "dist/index.js",
   "author": "mr-zwets",
   "scripts": {
+    "prepare": "pnpm build",
     "build": "tsc",
     "test": "vitest"
   },
@@ -13,8 +17,8 @@
   "devDependencies": {
     "@types/node": "^24.10.4",
     "msw": "^2.12.4",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   },
   "directories": {
     "test": "test"

package/.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:docs.bitcoincashnode.org)"
-    ]
-  }
-}

package/.github/workflows/ci.yaml

@@ -1,36 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Build
-        run: pnpm build
-
-      - name: Run tests
-        run: pnpm test run

package/CLAUDE.md

@@ -1,70 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Build & Test Commands
-
-```bash
-pnpm build          # Compile TypeScript to dist/
-pnpm test           # Run all tests with Vitest
-pnpm test <file>    # Run a specific test file
-```
-
-## Architecture
-
-TypeScript library providing type-safe wrappers for Bitcoin Cash Node (BCHN) JSON-RPC and REST interfaces. Types compatible with **BCHN v29.0.0**. Zero runtime dependencies.
-
-### Two Client Classes
-
-**BchnRestClient** (`src/restClient.ts`)
-- Wraps 11 REST endpoints for read-only blockchain access-
-- Class with dedicated methods for each endpoint
-- Supports format options (`json`, `hex`, `bin`) via conditional return types
-- Uses function overloads for type-safe returns based on parameters (e.g., `getBlock` with `includeTxDetails`)
-
-**BchnRpcClient** (`src/rpcClient.ts`)
-- Wraps 136 RPC commands for full node interaction
-- Single generic `request<T extends RpcRequest>()` method
-- Type safety achieved through discriminated union interfaces
-- Each RPC command interface defines: `method`, `params[]`, and `response` type
-
-### Interface Organization
-
-```
-src/interfaces/
-├── interfaces.ts              # Config types, RpcRequest base, shared types
-├── restInterfaces/            # REST response types
-└── rpcInterfaces/             # 136 RPC command interfaces across 9 files
-    ├── blockchain.ts          # 33 commands
-    ├── wallet.ts              # 52 commands
-    ├── rawtransactions.ts
-    ├── network.ts             # 14 commands
-    ├── mining.ts
-    ├── control.ts             # 6 commands
-    ├── util.ts
-    ├── generating.ts
-    └── zmq.ts
-```
-
-### RPC Type Pattern
-
-RPC interfaces follow this pattern for full type inference:
-
-```typescript
-export interface GetBlockVerbosity1 extends GetBlockBase {
-  params: [blockhash: string, verbosity?: 1 | true];
-  response: { hash: string; /* ... */ };
-}
-
-// Usage - params and response are fully typed:
-const result = await rpcClient.request<GetBlockVerbosity1>("getblock", hash, 1);
-```
-
-### Configuration Types
-
-- `RpcClientConfig`: Supports URL-based (`{url, rpcUser, rpcPassword}`) or host-based (`{protocol, host, port, rpcUser, rpcPassword}`) configuration
-- `RestClientConfig`: Requires `url`, optional `logger` and `timeoutMs`
-
-### Testing
-
-Tests use Vitest with MSW (Mock Service Worker) for HTTP interception. Mock server setup is in `test/setupTests.ts`.