hiero-sdk-utils 0.1.0

package/dist/cjs/client/HieroClient.d.ts

@@ -0,0 +1,70 @@
+import type { HieroClientConfig } from './types.js';
+import { AccountsResource } from '../resources/accounts.js';
+import { TransactionsResource } from '../resources/transactions.js';
+import { TokensResource } from '../resources/tokens.js';
+import { TopicsResource } from '../resources/topics.js';
+import { ContractsResource } from '../resources/contracts.js';
+import { NftsResource } from '../resources/nfts.js';
+import { BalancesResource } from '../resources/balances.js';
+import { BlocksResource } from '../resources/blocks.js';
+import { SchedulesResource } from '../resources/schedules.js';
+/**
+ * Core HTTP client for the Hedera Mirror Node REST API.
+ * Provides typed access to all Mirror Node resources with automatic
+ * rate limiting, retries, and error handling.
+ *
+ * @example
+ * ```ts
+ * import { HieroClient, Networks } from 'hiero-sdk-utils';
+ *
+ * const client = new HieroClient({ baseUrl: Networks.testnet });
+ * const account = await client.accounts.getById('0.0.1234');
+ * ```
+ */
+export declare class HieroClient {
+    /** Base URL for the Mirror Node (no trailing slash) */
+    readonly baseUrl: string;
+    private readonly fetchFn;
+    private readonly rateLimiter;
+    private readonly defaultHeaders;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    /** Account-related Mirror Node queries */
+    readonly accounts: AccountsResource;
+    /** Transaction-related Mirror Node queries */
+    readonly transactions: TransactionsResource;
+    /** Token-related Mirror Node queries */
+    readonly tokens: TokensResource;
+    /** Topic-related Mirror Node queries */
+    readonly topics: TopicsResource;
+    /** Contract-related Mirror Node queries */
+    readonly contracts: ContractsResource;
+    /** NFT-related Mirror Node queries */
+    readonly nfts: NftsResource;
+    /** Balance-related Mirror Node queries */
+    readonly balances: BalancesResource;
+    /** Block-related Mirror Node queries */
+    readonly blocks: BlocksResource;
+    /** Schedule-related Mirror Node queries */
+    readonly schedules: SchedulesResource;
+    /**
+     * Creates a new HieroClient.
+     *
+     * @param config - Client configuration including base URL and optional overrides
+     * @throws {Error} If baseUrl is empty
+     */
+    constructor(config: HieroClientConfig);
+    /**
+     * Makes a GET request to the Mirror Node and returns typed JSON.
+     * Handles rate limiting, retries on 429/503, and timeout.
+     *
+     * @param path - The API path (e.g., '/api/v1/accounts/0.0.2') or full next-page URL
+     * @returns Parsed JSON response typed as T
+     * @throws {MirrorNodeError} If the API returns a non-2xx response after retries
+     */
+    get<T>(path: string): Promise<T>;
+    private statusToCode;
+    private safeReadBody;
+    private sleep;
+}
+//# sourceMappingURL=HieroClient.d.ts.map

package/dist/cjs/client/HieroClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HieroClient.d.ts","sourceRoot":"","sources":["../../../src/client/HieroClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAY9D;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,uDAAuD;IACvD,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,0CAA0C;IAC1C,SAAgB,QAAQ,EAAE,gBAAgB,CAAC;IAC3C,8CAA8C;IAC9C,SAAgB,YAAY,EAAE,oBAAoB,CAAC;IACnD,wCAAwC;IACxC,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,wCAAwC;IACxC,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,2CAA2C;IAC3C,SAAgB,SAAS,EAAE,iBAAiB,CAAC;IAC7C,sCAAsC;IACtC,SAAgB,IAAI,EAAE,YAAY,CAAC;IACnC,0CAA0C;IAC1C,SAAgB,QAAQ,EAAE,gBAAgB,CAAC;IAC3C,wCAAwC;IACxC,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,2CAA2C;IAC3C,SAAgB,SAAS,EAAE,iBAAiB,CAAC;IAE7C;;;;;OAKG;gBACS,MAAM,EAAE,iBAAiB;IA4BrC;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAiEtC,OAAO,CAAC,YAAY;YAUN,YAAY;IAS1B,OAAO,CAAC,KAAK;CAKd"}

package/dist/cjs/client/HieroClient.js

@@ -0,0 +1,165 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HieroClient = void 0;
+const rateLimiter_js_1 = require("./rateLimiter.js");
+const index_js_1 = require("../errors/index.js");
+const accounts_js_1 = require("../resources/accounts.js");
+const transactions_js_1 = require("../resources/transactions.js");
+const tokens_js_1 = require("../resources/tokens.js");
+const topics_js_1 = require("../resources/topics.js");
+const contracts_js_1 = require("../resources/contracts.js");
+const nfts_js_1 = require("../resources/nfts.js");
+const balances_js_1 = require("../resources/balances.js");
+const blocks_js_1 = require("../resources/blocks.js");
+const schedules_js_1 = require("../resources/schedules.js");
+/** Retriable HTTP status codes */
+const RETRIABLE_STATUSES = new Set([429, 503]);
+/** Default configuration values */
+const DEFAULTS = {
+    maxRequestsPerSecond: 20,
+    timeoutMs: 30_000,
+    maxRetries: 3,
+};
+/**
+ * Core HTTP client for the Hedera Mirror Node REST API.
+ * Provides typed access to all Mirror Node resources with automatic
+ * rate limiting, retries, and error handling.
+ *
+ * @example
+ * ```ts
+ * import { HieroClient, Networks } from 'hiero-sdk-utils';
+ *
+ * const client = new HieroClient({ baseUrl: Networks.testnet });
+ * const account = await client.accounts.getById('0.0.1234');
+ * ```
+ */
+class HieroClient {
+    /** Base URL for the Mirror Node (no trailing slash) */
+    baseUrl;
+    fetchFn;
+    rateLimiter;
+    defaultHeaders;
+    timeoutMs;
+    maxRetries;
+    /** Account-related Mirror Node queries */
+    accounts;
+    /** Transaction-related Mirror Node queries */
+    transactions;
+    /** Token-related Mirror Node queries */
+    tokens;
+    /** Topic-related Mirror Node queries */
+    topics;
+    /** Contract-related Mirror Node queries */
+    contracts;
+    /** NFT-related Mirror Node queries */
+    nfts;
+    /** Balance-related Mirror Node queries */
+    balances;
+    /** Block-related Mirror Node queries */
+    blocks;
+    /** Schedule-related Mirror Node queries */
+    schedules;
+    /**
+     * Creates a new HieroClient.
+     *
+     * @param config - Client configuration including base URL and optional overrides
+     * @throws {Error} If baseUrl is empty
+     */
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new Error('baseUrl is required and must not be empty');
+        }
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+        this.rateLimiter = new rateLimiter_js_1.RateLimiter(config.maxRequestsPerSecond ?? DEFAULTS.maxRequestsPerSecond);
+        this.defaultHeaders = {
+            Accept: 'application/json',
+            ...config.headers,
+        };
+        this.timeoutMs = config.timeoutMs ?? DEFAULTS.timeoutMs;
+        this.maxRetries = config.maxRetries ?? DEFAULTS.maxRetries;
+        this.accounts = new accounts_js_1.AccountsResource(this);
+        this.transactions = new transactions_js_1.TransactionsResource(this);
+        this.tokens = new tokens_js_1.TokensResource(this);
+        this.topics = new topics_js_1.TopicsResource(this);
+        this.contracts = new contracts_js_1.ContractsResource(this);
+        this.nfts = new nfts_js_1.NftsResource(this);
+        this.balances = new balances_js_1.BalancesResource(this);
+        this.blocks = new blocks_js_1.BlocksResource(this);
+        this.schedules = new schedules_js_1.SchedulesResource(this);
+    }
+    /**
+     * Makes a GET request to the Mirror Node and returns typed JSON.
+     * Handles rate limiting, retries on 429/503, and timeout.
+     *
+     * @param path - The API path (e.g., '/api/v1/accounts/0.0.2') or full next-page URL
+     * @returns Parsed JSON response typed as T
+     * @throws {MirrorNodeError} If the API returns a non-2xx response after retries
+     */
+    async get(path) {
+        const url = path.startsWith('http') ? path : `${this.baseUrl}${path}`;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            await this.rateLimiter.acquire();
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const response = await this.fetchFn(url, {
+                    method: 'GET',
+                    headers: this.defaultHeaders,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (response.ok) {
+                    const json = await response.json();
+                    return json;
+                }
+                if (RETRIABLE_STATUSES.has(response.status) && attempt < this.maxRetries) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : 1000 * (attempt + 1);
+                    await this.sleep(waitMs);
+                    continue;
+                }
+                const errorBody = await this.safeReadBody(response);
+                throw new index_js_1.MirrorNodeError(`Mirror Node returned ${response.status} for ${url}: ${errorBody}`, this.statusToCode(response.status), response.status);
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (error instanceof index_js_1.MirrorNodeError) {
+                    throw error;
+                }
+                if (error instanceof DOMException && error.name === 'AbortError') {
+                    throw new index_js_1.MirrorNodeError(`Request timed out after ${this.timeoutMs}ms for ${url}`, 'REQUEST_TIMEOUT', 0, { cause: error });
+                }
+                throw new index_js_1.MirrorNodeError(`Network error for ${url}: ${error instanceof Error ? error.message : String(error)}`, 'NETWORK_ERROR', 0, { cause: error instanceof Error ? error : new Error(String(error)) });
+            }
+        }
+        /* v8 ignore next -- unreachable: loop always exits via return or throw */
+        throw new index_js_1.MirrorNodeError(`Request failed for ${url}`, 'MAX_RETRIES_EXCEEDED', 0);
+    }
+    statusToCode(status) {
+        switch (status) {
+            case 400: return 'BAD_REQUEST';
+            case 404: return 'NOT_FOUND';
+            case 429: return 'RATE_LIMITED';
+            case 503: return 'SERVICE_UNAVAILABLE';
+            default: return 'MIRROR_NODE_ERROR';
+        }
+    }
+    async safeReadBody(response) {
+        try {
+            const text = await response.text();
+            return text.substring(0, 500);
+        }
+        catch {
+            return '(unable to read response body)';
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        });
+    }
+}
+exports.HieroClient = HieroClient;
+//# sourceMappingURL=HieroClient.js.map

package/dist/cjs/client/HieroClient.js.map

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

package/dist/cjs/client/rateLimiter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A simple token-bucket rate limiter that throttles requests
+ * to stay within a specified requests-per-second limit.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(10); // 10 req/s
+ * await limiter.acquire(); // waits if needed
+ * ```
+ */
+export declare class RateLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly maxTokens;
+    private readonly refillRateMs;
+    /**
+     * Creates a new rate limiter.
+     *
+     * @param maxRequestsPerSecond - Maximum number of requests allowed per second
+     * @throws {Error} If maxRequestsPerSecond is not a positive number
+     */
+    constructor(maxRequestsPerSecond: number);
+    /**
+     * Acquires a token, waiting if necessary until one becomes available.
+     * Call this before each HTTP request.
+     *
+     * @returns A promise that resolves when a token is acquired
+     */
+    acquire(): Promise<void>;
+    private refill;
+    private sleep;
+}
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/cjs/client/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../../src/client/rateLimiter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;OAKG;gBACS,oBAAoB,EAAE,MAAM;IAYxC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB9B,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,KAAK;CAKd"}

package/dist/cjs/client/rateLimiter.js

@@ -0,0 +1,68 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+/**
+ * A simple token-bucket rate limiter that throttles requests
+ * to stay within a specified requests-per-second limit.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(10); // 10 req/s
+ * await limiter.acquire(); // waits if needed
+ * ```
+ */
+class RateLimiter {
+    tokens;
+    lastRefill;
+    maxTokens;
+    refillRateMs;
+    /**
+     * Creates a new rate limiter.
+     *
+     * @param maxRequestsPerSecond - Maximum number of requests allowed per second
+     * @throws {Error} If maxRequestsPerSecond is not a positive number
+     */
+    constructor(maxRequestsPerSecond) {
+        if (maxRequestsPerSecond <= 0) {
+            throw new Error(`maxRequestsPerSecond must be positive, got ${maxRequestsPerSecond}`);
+        }
+        this.maxTokens = maxRequestsPerSecond;
+        this.tokens = maxRequestsPerSecond;
+        this.lastRefill = Date.now();
+        this.refillRateMs = 1000 / maxRequestsPerSecond;
+    }
+    /**
+     * Acquires a token, waiting if necessary until one becomes available.
+     * Call this before each HTTP request.
+     *
+     * @returns A promise that resolves when a token is acquired
+     */
+    async acquire() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        const waitMs = this.refillRateMs - (Date.now() - this.lastRefill);
+        if (waitMs > 0) {
+            await this.sleep(waitMs);
+        }
+        this.refill();
+        this.tokens = Math.max(0, this.tokens - 1);
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        const tokensToAdd = elapsed / this.refillRateMs;
+        this.tokens = Math.min(this.maxTokens, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        });
+    }
+}
+exports.RateLimiter = RateLimiter;
+//# sourceMappingURL=rateLimiter.js.map

package/dist/cjs/client/rateLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.js","sourceRoot":"","sources":["../../../src/client/rateLimiter.ts"],"names":[],"mappings":";AAAA,sCAAsC;;;AAEtC;;;;;;;;;GASG;AACH,MAAa,WAAW;IACd,MAAM,CAAS;IACf,UAAU,CAAS;IACV,SAAS,CAAS;IAClB,YAAY,CAAS;IAEtC;;;;;OAKG;IACH,YAAY,oBAA4B;QACtC,IAAI,oBAAoB,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,8CAA8C,oBAAoB,EAAE,CACrE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,oBAAoB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,oBAAoB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,GAAG,oBAAoB,CAAC;IAClD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAClE,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAEO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;QACtC,MAAM,WAAW,GAAG,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC;QAChD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;QAClE,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AA5DD,kCA4DC"}

package/dist/cjs/client/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration for the HieroClient.
+ */
+export interface HieroClientConfig {
+    /** The Mirror Node base URL (no trailing slash) */
+    baseUrl: string;
+    /** Maximum requests per second for rate limiting (default: 20) */
+    maxRequestsPerSecond?: number;
+    /** Custom fetch implementation — useful for testing */
+    fetch?: typeof globalThis.fetch;
+    /** Default headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+    /** Maximum number of retries for retriable errors (default: 3) */
+    maxRetries?: number;
+}
+/** Pre-configured network endpoints for the Hedera Mirror Node */
+export declare const Networks: {
+    readonly mainnet: "https://mainnet.mirrornode.hedera.com";
+    readonly testnet: "https://testnet.mirrornode.hedera.com";
+    readonly previewnet: "https://previewnet.mirrornode.hedera.com";
+};
+/** Network name keys */
+export type NetworkName = keyof typeof Networks;
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/client/types.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ;;;;CAIsB,CAAC;AAE5C,wBAAwB;AACxB,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,QAAQ,CAAC"}

package/dist/cjs/client/types.js

@@ -0,0 +1,11 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Networks = void 0;
+/** Pre-configured network endpoints for the Hedera Mirror Node */
+exports.Networks = {
+    mainnet: 'https://mainnet.mirrornode.hedera.com',
+    testnet: 'https://testnet.mirrornode.hedera.com',
+    previewnet: 'https://previewnet.mirrornode.hedera.com',
+};
+//# sourceMappingURL=types.js.map

package/dist/cjs/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/client/types.ts"],"names":[],"mappings":";AAAA,sCAAsC;;;AAoBtC,kEAAkE;AACrD,QAAA,QAAQ,GAAG;IACtB,OAAO,EAAE,uCAAuC;IAChD,OAAO,EAAE,uCAAuC;IAChD,UAAU,EAAE,0CAA0C;CACb,CAAC"}

package/dist/cjs/errors/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Base error class for all hiero-sdk-utils errors.
+ * All errors thrown by this library extend this class.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.accounts.getById('invalid');
+ * } catch (error) {
+ *   if (error instanceof HieroError) {
+ *     console.log(error.code); // e.g., 'INVALID_ACCOUNT_ID'
+ *   }
+ * }
+ * ```
+ */
+export declare class HieroError extends Error {
+    readonly code: string;
+    /**
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code (e.g., 'ACCOUNT_NOT_FOUND')
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when the Mirror Node API returns an error response.
+ * Includes the HTTP status code for programmatic handling.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.accounts.getById('0.0.99999999999');
+ * } catch (error) {
+ *   if (error instanceof MirrorNodeError) {
+ *     console.log(error.status); // 404
+ *     console.log(error.code);   // 'MIRROR_NODE_ERROR'
+ *   }
+ * }
+ * ```
+ */
+export declare class MirrorNodeError extends HieroError {
+    readonly status: number;
+    /**
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code
+     * @param status - HTTP status code from the Mirror Node response
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message: string, code: string, status: number, options?: ErrorOptions);
+}
+/**
+ * Error thrown when input validation fails before making a network request.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.accounts.getById('not-an-id');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.code); // 'INVALID_ACCOUNT_ID'
+ *   }
+ * }
+ * ```
+ */
+export declare class ValidationError extends HieroError {
+    /**
+     * @param message - Human-readable description of what was invalid
+     * @param code - Machine-readable error code
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when pagination encounters an unexpected state.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   for await (const item of client.accounts.list()) { ... }
+ * } catch (error) {
+ *   if (error instanceof PaginationError) {
+ *     console.log(error.code); // 'INVALID_RESPONSE_SHAPE'
+ *   }
+ * }
+ * ```
+ */
+export declare class PaginationError extends HieroError {
+    /**
+     * @param message - Human-readable description of the pagination failure
+     * @param code - Machine-readable error code
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,SAAQ,KAAK;aAQjB,IAAI,EAAE,MAAM;IAP9B;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EAC5B,OAAO,CAAC,EAAE,YAAY;CAMzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,SAAQ,UAAU;aAU3B,MAAM,EAAE,MAAM;IAThC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACI,MAAM,EAAE,MAAM,EAC9B,OAAO,CAAC,EAAE,YAAY;CAIzB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGlE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGlE"}

package/dist/cjs/errors/index.js

@@ -0,0 +1,115 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationError = exports.ValidationError = exports.MirrorNodeError = exports.HieroError = void 0;
+/**
+ * Base error class for all hiero-sdk-utils errors.
+ * All errors thrown by this library extend this class.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.accounts.getById('invalid');
+ * } catch (error) {
+ *   if (error instanceof HieroError) {
+ *     console.log(error.code); // e.g., 'INVALID_ACCOUNT_ID'
+ *   }
+ * }
+ * ```
+ */
+class HieroError extends Error {
+    code;
+    /**
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code (e.g., 'ACCOUNT_NOT_FOUND')
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = this.constructor.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.HieroError = HieroError;
+/**
+ * Error thrown when the Mirror Node API returns an error response.
+ * Includes the HTTP status code for programmatic handling.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.accounts.getById('0.0.99999999999');
+ * } catch (error) {
+ *   if (error instanceof MirrorNodeError) {
+ *     console.log(error.status); // 404
+ *     console.log(error.code);   // 'MIRROR_NODE_ERROR'
+ *   }
+ * }
+ * ```
+ */
+class MirrorNodeError extends HieroError {
+    status;
+    /**
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code
+     * @param status - HTTP status code from the Mirror Node response
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message, code, status, options) {
+        super(message, code, options);
+        this.status = status;
+    }
+}
+exports.MirrorNodeError = MirrorNodeError;
+/**
+ * Error thrown when input validation fails before making a network request.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.accounts.getById('not-an-id');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.code); // 'INVALID_ACCOUNT_ID'
+ *   }
+ * }
+ * ```
+ */
+class ValidationError extends HieroError {
+    /**
+     * @param message - Human-readable description of what was invalid
+     * @param code - Machine-readable error code
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message, code, options) {
+        super(message, code, options);
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Error thrown when pagination encounters an unexpected state.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   for await (const item of client.accounts.list()) { ... }
+ * } catch (error) {
+ *   if (error instanceof PaginationError) {
+ *     console.log(error.code); // 'INVALID_RESPONSE_SHAPE'
+ *   }
+ * }
+ * ```
+ */
+class PaginationError extends HieroError {
+    /**
+     * @param message - Human-readable description of the pagination failure
+     * @param code - Machine-readable error code
+     * @param options - Standard ErrorOptions including cause chain
+     */
+    constructor(message, code, options) {
+        super(message, code, options);
+    }
+}
+exports.PaginationError = PaginationError;
+//# sourceMappingURL=index.js.map

package/dist/cjs/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":";AAAA,sCAAsC;;;AAEtC;;;;;;;;;;;;;;GAcG;AACH,MAAa,UAAW,SAAQ,KAAK;IAQjB;IAPlB;;;;OAIG;IACH,YACE,OAAe,EACC,IAAY,EAC5B,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAQ;QAI5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAfD,gCAeC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAa,eAAgB,SAAQ,UAAU;IAU3B;IATlB;;;;;OAKG;IACH,YACE,OAAe,EACf,IAAY,EACI,MAAc,EAC9B,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAHd,WAAM,GAAN,MAAM,CAAQ;IAIhC,CAAC;CACF;AAfD,0CAeC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAa,eAAgB,SAAQ,UAAU;IAC7C;;;;OAIG;IACH,YAAY,OAAe,EAAE,IAAY,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;CACF;AATD,0CASC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAa,eAAgB,SAAQ,UAAU;IAC7C;;;;OAIG;IACH,YAAY,OAAe,EAAE,IAAY,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;CACF;AATD,0CASC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * hiero-sdk-utils — TypeScript utilities for the Hedera/Hiero Mirror Node.
+ *
+ * @example
+ * ```ts
+ * import { HieroClient, Networks } from 'hiero-sdk-utils';
+ *
+ * const client = new HieroClient({ baseUrl: Networks.testnet });
+ *
+ * // Fetch a single account
+ * const account = await client.accounts.getById('0.0.1234');
+ *
+ * // Iterate through accounts with auto-pagination
+ * for await (const a of client.accounts.list({ limit: 10 })) {
+ *   console.log(a.account, a.balance.balance);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { HieroClient } from './client/HieroClient.js';
+export { Networks } from './client/types.js';
+export type { HieroClientConfig, NetworkName } from './client/types.js';
+export { HieroError, MirrorNodeError, ValidationError, PaginationError, } from './errors/index.js';
+export { AccountsResource } from './resources/accounts.js';
+export { TransactionsResource } from './resources/transactions.js';
+export { TokensResource } from './resources/tokens.js';
+export { TopicsResource } from './resources/topics.js';
+export { ContractsResource } from './resources/contracts.js';
+export { NftsResource } from './resources/nfts.js';
+export { BalancesResource } from './resources/balances.js';
+export { BlocksResource } from './resources/blocks.js';
+export { SchedulesResource } from './resources/schedules.js';
+export type { AccountInfo, AccountBalance, AccountsQueryParams, TransactionInfo, TransactionsQueryParams, Transfer, TokenTransfer, NftTransfer, TokenInfo, TokensQueryParams, TokenBalance, TopicInfo, TopicMessage, TopicMessagesQueryParams, ContractInfo, ContractsQueryParams, CustomFee, FixedFee, FractionalFee, FractionalAmount, RoyaltyFee, NftInfo, NftsQueryParams, BalanceEntry, BalancesQueryParams, BlockInfo, BlocksQueryParams, ScheduleInfo, SchedulesQueryParams, Key, } from './types/api.js';
+export type { BaseQueryParams, TimestampFilter, PaginationLinks, } from './types/common.js';
+//# sourceMappingURL=index.d.ts.map