hiero-sdk-utils 0.1.0

package/dist/esm/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/esm/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/esm/client/rateLimiter.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.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
+ * ```
+ */
+export 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);
+        });
+    }
+}
+//# sourceMappingURL=rateLimiter.js.map

package/dist/esm/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,MAAM,OAAO,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"}

package/dist/esm/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/esm/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/esm/client/types.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Pre-configured network endpoints for the Hedera Mirror Node */
+export const 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/esm/client/types.js.map

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

package/dist/esm/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/esm/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/esm/errors/index.js

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.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'
+ *   }
+ * }
+ * ```
+ */
+export 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);
+    }
+}
+/**
+ * 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 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;
+    }
+}
+/**
+ * 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 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);
+    }
+}
+/**
+ * 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 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);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/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,MAAM,OAAO,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;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,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;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,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;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,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"}

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

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGxE,OAAO,EACL,UAAU,EACV,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,YAAY,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,GAAG,GACJ,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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
+ */
+// Client
+export { HieroClient } from './client/HieroClient.js';
+export { Networks } from './client/types.js';
+// Errors
+export { HieroError, MirrorNodeError, ValidationError, PaginationError, } from './errors/index.js';
+// Resources
+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';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,SAAS;AACT,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C,SAAS;AACT,OAAO,EACL,UAAU,EACV,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,YAAY;AACZ,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/esm/pagination/paginator.d.ts

@@ -0,0 +1,21 @@
+import type { HieroClient } from '../client/HieroClient.js';
+/**
+ * Creates an async generator that paginates through a Mirror Node list endpoint.
+ * Follows the `links.next` field to automatically fetch subsequent pages.
+ *
+ * @param client - The HieroClient instance to use for HTTP requests
+ * @param path - The API path for the list endpoint (e.g., '/api/v1/accounts')
+ * @param dataKey - The key in the response object that contains the data array (e.g., 'accounts')
+ * @param params - Optional query parameters for filtering/sorting
+ * @returns An async generator that yields individual items of type T
+ * @throws {PaginationError} If the response shape is unexpected
+ *
+ * @example
+ * ```ts
+ * for await (const account of paginate<AccountInfo>(client, '/api/v1/accounts', 'accounts')) {
+ *   console.log(account.account);
+ * }
+ * ```
+ */
+export declare function paginate<T>(client: HieroClient, path: string, dataKey: string, params?: Record<string, string | number | boolean | undefined>): AsyncGenerator<T, void, undefined>;
+//# sourceMappingURL=paginator.d.ts.map

package/dist/esm/pagination/paginator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../../src/pagination/paginator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA+C5D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAC/B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC7D,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAkCpC"}

package/dist/esm/pagination/paginator.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+import { PaginationError } from '../errors/index.js';
+/**
+ * Builds a query string from parameters.
+ *
+ * @param path - The base API path
+ * @param params - Optional key-value query parameters
+ * @returns The full path with query string appended
+ */
+function buildUrl(path, params) {
+    if (!params) {
+        return path;
+    }
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            searchParams.set(key, String(value));
+        }
+    }
+    const queryString = searchParams.toString();
+    return queryString ? `${path}?${queryString}` : path;
+}
+/**
+ * Extracts the `links.next` value from a Mirror Node paginated response.
+ *
+ * @param body - The raw JSON response object
+ * @returns The next page URL or null
+ */
+function extractNextLink(body) {
+    const links = body['links'];
+    if (links !== null && typeof links === 'object' && !Array.isArray(links)) {
+        const linksObj = links;
+        const next = linksObj['next'];
+        if (typeof next === 'string' && next.length > 0) {
+            return next;
+        }
+    }
+    return null;
+}
+/**
+ * Creates an async generator that paginates through a Mirror Node list endpoint.
+ * Follows the `links.next` field to automatically fetch subsequent pages.
+ *
+ * @param client - The HieroClient instance to use for HTTP requests
+ * @param path - The API path for the list endpoint (e.g., '/api/v1/accounts')
+ * @param dataKey - The key in the response object that contains the data array (e.g., 'accounts')
+ * @param params - Optional query parameters for filtering/sorting
+ * @returns An async generator that yields individual items of type T
+ * @throws {PaginationError} If the response shape is unexpected
+ *
+ * @example
+ * ```ts
+ * for await (const account of paginate<AccountInfo>(client, '/api/v1/accounts', 'accounts')) {
+ *   console.log(account.account);
+ * }
+ * ```
+ */
+export async function* paginate(client, path, dataKey, params) {
+    let url = buildUrl(path, params);
+    while (url !== null) {
+        const body = await client.get(url);
+        const items = body[dataKey];
+        if (!Array.isArray(items)) {
+            throw new PaginationError(`Expected array at key "${dataKey}" in response from ${url}, got ${typeof items}`, 'INVALID_RESPONSE_SHAPE');
+        }
+        for (const item of items) {
+            yield item;
+        }
+        // If the page was empty, stop regardless of links
+        if (items.length === 0) {
+            break;
+        }
+        const nextLink = extractNextLink(body);
+        if (nextLink === null) {
+            url = null;
+        }
+        else if (nextLink.startsWith('http')) {
+            url = nextLink;
+        }
+        else {
+            // Relative URL from the Mirror Node
+            url = nextLink.startsWith('/') ? nextLink : `/${nextLink}`;
+        }
+    }
+}
+//# sourceMappingURL=paginator.js.map

package/dist/esm/pagination/paginator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginator.js","sourceRoot":"","sources":["../../../src/pagination/paginator.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAGtC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;GAMG;AACH,SAAS,QAAQ,CACf,IAAY,EACZ,MAA8D;IAE9D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,eAAe,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC;IAC5C,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,IAA6B;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,MAAM,QAAQ,GAAG,KAAgC,CAAC;QAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAC7B,MAAmB,EACnB,IAAY,EACZ,OAAe,EACf,MAA8D;IAE9D,IAAI,GAAG,GAAkB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEhD,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,GAA4B,MAAM,MAAM,CAAC,GAAG,CAA0B,GAAG,CAAC,CAAC;QACrF,MAAM,KAAK,GAAY,IAAI,CAAC,OAAO,CAAC,CAAC;QAErC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,eAAe,CACvB,0BAA0B,OAAO,sBAAsB,GAAG,SAAS,OAAO,KAAK,EAAE,EACjF,wBAAwB,CACzB,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAS,CAAC;QAClB,CAAC;QAED,kDAAkD;QAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM;QACR,CAAC;QAED,MAAM,QAAQ,GAAkB,eAAe,CAAC,IAAI,CAAC,CAAC;QAEtD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,GAAG,GAAG,IAAI,CAAC;QACb,CAAC;aAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,GAAG,GAAG,QAAQ,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,oCAAoC;YACpC,GAAG,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/esm/resources/accounts.d.ts

@@ -0,0 +1,43 @@
+import type { HieroClient } from '../client/HieroClient.js';
+import type { AccountInfo, AccountsQueryParams } from '../types/api.js';
+/**
+ * Provides access to Mirror Node account endpoints.
+ *
+ * @example
+ * ```ts
+ * const account = await client.accounts.getById('0.0.1234');
+ * for await (const a of client.accounts.list({ limit: 10 })) {
+ *   console.log(a.account);
+ * }
+ * ```
+ */
+export declare class AccountsResource {
+    private readonly client;
+    constructor(client: HieroClient);
+    /**
+     * Retrieves a single account by ID.
+     *
+     * @param accountId - Account in `0.0.X` format
+     * @returns The account info including balance, key, and staking data
+     * @throws {ValidationError} If accountId format is invalid
+     * @throws {MirrorNodeError} If the API request fails
+     */
+    getById(accountId: string): Promise<AccountInfo>;
+    /**
+     * Lists accounts with optional filters. Returns an async iterable
+     * that automatically handles pagination.
+     *
+     * @param params - Optional query parameters for filtering
+     * @returns Async iterable of account info objects
+     *
+     * @example
+     * ```ts
+     * for await (const account of client.accounts.list({ limit: 5, order: 'desc' })) {
+     *   console.log(account.account, account.balance.balance);
+     * }
+     * ```
+     */
+    list(params?: AccountsQueryParams): AsyncIterable<AccountInfo>;
+    private validateAccountId;
+}
+//# sourceMappingURL=accounts.d.ts.map

package/dist/esm/resources/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../../src/resources/accounts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAKxE;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,WAAW;IAEhD;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAKtD;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAAC,WAAW,CAAC;IAS9D,OAAO,CAAC,iBAAiB;CAQ1B"}