@satianurag/hiero-mirror-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1425 @@
+//#region src/http/retry.d.ts
+/**
+ * Exponential backoff with jitter for retrying failed requests.
+ *
+ * Retry rules:
+ * - Always retry: 5xx, network errors, 429
+ * - Never retry: 400, 401, 403, 404 (client errors are not transient)
+ * - 429: Always retry, use `Retry-After` header if present
+ *
+ * @internal
+ */
+interface RetryOptions {
+  /** Maximum number of retries. Default: 2. */
+  maxRetries: number;
+  /** Base delay in milliseconds. Default: 500ms. */
+  baseDelay: number;
+  /** Maximum delay cap in milliseconds. Default: 10000ms. */
+  maxDelay: number;
+}
+//#endregion
+//#region src/http/url-builder.d.ts
+/**
+ * Operator types supported by the Mirror Node API query parameters.
+ * Used with `.append()` for multi-value/range queries: `timestamp=gt:1234`.
+ */
+type QueryOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+/**
+ * A query parameter value with an optional operator prefix.
+ */
+interface OperatorValue {
+  operator: QueryOperator;
+  value: string | number;
+}
+/**
+ * Raw query parameter types accepted by the URL builder.
+ */
+type QueryParamValue = string | number | boolean | OperatorValue | OperatorValue[] | undefined | null;
+interface QueryParams {
+  [key: string]: QueryParamValue;
+}
+//#endregion
+//#region src/http/client.d.ts
+interface HttpClientOptions {
+  /** Base URL for the mirror node. */
+  baseUrl: string;
+  /** Request timeout in milliseconds. Default: 30000. */
+  timeout?: number;
+  /** Retry options. */
+  retry?: Partial<RetryOptions>;
+  /** Rate limit in requests per second. Default: 50. */
+  rateLimitRps?: number;
+  /** Optional logger for debug output. */
+  logger?: Logger$1;
+  /** Custom fetch implementation (for testing). */
+  fetch?: typeof globalThis.fetch;
+}
+interface Logger$1 {
+  debug?: (message: string, ...args: unknown[]) => void;
+  info?: (message: string, ...args: unknown[]) => void;
+  warn?: (message: string, ...args: unknown[]) => void;
+  error?: (message: string, ...args: unknown[]) => void;
+}
+interface RequestOptions {
+  /** Additional headers to send. */
+  headers?: Record<string, string>;
+  /** Override the default timeout for this request. */
+  timeout?: number;
+  /** Abort signal for request cancellation. */
+  signal?: AbortSignal;
+}
+interface HttpResponse<T = unknown> {
+  /** Parsed response body. */
+  data: T;
+  /** HTTP status code. */
+  status: number;
+  /** Response headers. */
+  headers: Headers;
+}
+declare class HttpClient {
+  private readonly baseUrl;
+  private readonly timeout;
+  private readonly retryOptions;
+  private readonly rateLimiter;
+  private readonly inflight;
+  private readonly etagCache;
+  private readonly logger;
+  private readonly fetchFn;
+  constructor(options: HttpClientOptions);
+  /**
+   * Performs a GET request with in-flight deduplication.
+   *
+   * @param path - API path (e.g., `/api/v1/accounts`)
+   * @param params - Optional query parameters
+   * @param options - Optional request options
+   * @returns Parsed response
+   */
+  get<T = unknown>(path: string, params?: QueryParams, options?: RequestOptions): Promise<HttpResponse<T>>;
+  /**
+   * Performs a POST request.
+   *
+   * POST requests are NOT deduplicated (they have side effects).
+   *
+   * @param path - API path
+   * @param body - Request body (will be JSON-serialized)
+   * @param options - Optional request options
+   * @returns Parsed response
+   */
+  post<T = unknown>(path: string, body: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+  /**
+   * Core request method with retry, rate limiting, timeout, and error handling.
+   */
+  private request;
+  /**
+   * Handles the HTTP response: checks content type, parses JSON safely,
+   * and throws appropriate errors for non-2xx responses.
+   */
+  private handleResponse;
+}
+//#endregion
+//#region src/types/common.d.ts
+/**
+ * Shared types used across all Hiero Mirror Client SDK resources.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Pagination link container returned by list endpoints.
+ */
+interface PaginationLinks {
+  next: string | null;
+}
+/**
+ * A page of results from a list endpoint.
+ */
+interface Page<T> {
+  data: T[];
+  links: PaginationLinks;
+}
+/**
+ * Sort order for list endpoints.
+ *
+ * The API accepts case-insensitive values but only `asc` and `desc`
+ * are valid enums.
+ */
+type Order = 'asc' | 'desc';
+/**
+ * A `0x`-prefixed hexadecimal string.
+ *
+ * This is a branded type alias — it is still a plain `string` at runtime
+ * but provides additional type safety at the TypeScript level.
+ */
+type Hex = string & {
+  readonly __brand: 'Hex';
+};
+/**
+ * A range timestamp used by blocks and network stake endpoints.
+ *
+ * `to` can be `null` for open-ended ranges (e.g., currently active nodes).
+ *
+ * EC28: `{ from: string; to: string | null }`
+ */
+interface TimestampRange {
+  from: string;
+  to: string | null;
+}
+/**
+ * Discriminated union for Hedera public key types.
+ *
+ * EC27: Three variants based on `_type`:
+ * - `ED25519` — 32-byte Ed25519 public key (64 hex chars)
+ * - `ECDSA_SECP256K1` — 33-byte compressed ECDSA key (66 hex chars)
+ * - `ProtobufEncoded` — opaque protobuf-serialized key structure
+ */
+type HieroKey = {
+  _type: 'ED25519';
+  key: string;
+} | {
+  _type: 'ECDSA_SECP256K1';
+  key: string;
+} | {
+  _type: 'ProtobufEncoded';
+  key: string;
+};
+/**
+ * A single token balance entry.
+ */
+interface TokenBalance {
+  token_id: string;
+  balance: string;
+}
+/**
+ * Freeze status for token-account relationships (EC35).
+ */
+type FreezeStatus = 'FROZEN' | 'UNFROZEN' | 'NOT_APPLICABLE';
+/**
+ * KYC status for token-account relationships (EC35).
+ */
+type KycStatus = 'GRANTED' | 'REVOKED' | 'NOT_APPLICABLE';
+/**
+ * Filter for transaction result status.
+ */
+type TransactionResult = 'success' | 'fail';
+/**
+ * Token types supported by the Hedera network.
+ */
+type TokenType = 'FUNGIBLE_COMMON' | 'NON_FUNGIBLE_UNIQUE';
+/**
+ * An operator-based query filter.
+ *
+ * Allows expressing range/equality queries in the Stripe-style object pattern:
+ * ```typescript
+ * { timestamp: { gt: '1234', lte: '5678' } }
+ * ```
+ *
+ * EC83/EC123: Supports all 6 operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.
+ */
+interface OperatorFilter<T = string> {
+  eq?: T;
+  ne?: T;
+  gt?: T;
+  gte?: T;
+  lt?: T;
+  lte?: T;
+}
+/**
+ * A query parameter value that can be either a direct value or an operator filter.
+ */
+type OperatorQuery<T = string> = T | OperatorFilter<T>;
+/**
+ * Optional logger interface.
+ *
+ * Compatible with `console`, `pino`, `winston`, or any object
+ * with `debug/info/warn/error` methods.
+ */
+interface Logger {
+  debug?: (message: string, ...args: unknown[]) => void;
+  info?: (message: string, ...args: unknown[]) => void;
+  warn?: (message: string, ...args: unknown[]) => void;
+  error?: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * An HBAR transfer within a transaction.
+ */
+interface Transfer {
+  account: string;
+  amount: string;
+  is_approval: boolean;
+}
+/**
+ * A token transfer within a transaction.
+ */
+interface TokenTransfer {
+  account: string;
+  amount: string;
+  is_approval: boolean;
+  token_id: string;
+}
+/**
+ * An NFT transfer within a transaction.
+ */
+interface NftTransfer {
+  is_approval: boolean;
+  receiver_account_id: string | null;
+  sender_account_id: string | null;
+  serial_number: string;
+  token_id: string;
+}
+/**
+ * A staking reward transfer.
+ *
+ * EC135: Always an array (never null or missing).
+ */
+interface StakingRewardTransfer {
+  account: string;
+  amount: string;
+}
+//#endregion
+//#region src/pagination/paginator.d.ts
+/**
+ * A function that extracts `/api/v1/...` items from a raw API response
+ * and returns a {@link Page} of mapped items.
+ */
+type PageExtractor<T> = (raw: unknown) => Page<T>;
+/**
+ * Configuration for creating a Paginator.
+ */
+interface PaginatorOptions<T> {
+  /** The HTTP client instance. */
+  client: HttpClient;
+  /** The initial API path (e.g., `/api/v1/accounts`). */
+  path: string;
+  /** Query parameters for the first request. */
+  params?: Record<string, unknown>;
+  /** Mapper function: raw JSON → Page<T>. */
+  extract: PageExtractor<T>;
+}
+/**
+ * Lazy paginator that fetches pages on demand.
+ *
+ * Implements `PromiseLike<Page<T>>` so `await` returns the first page.
+ * Implements `AsyncIterable<T>` so `for await...of` yields items.
+ *
+ * EC19: Uses `links.next` as an opaque cursor (never constructs cursors).
+ * EC47: Terminates when `links.next` is null.
+ * EC8: Resolves relative `links.next` URLs against the base URL.
+ */
+declare class Paginator<T> implements PromiseLike<Page<T>>, AsyncIterable<T> {
+  private readonly client;
+  private readonly initialPath;
+  private readonly params?;
+  private readonly extract;
+  constructor(options: PaginatorOptions<T>);
+  then<TResult1 = Page<T>, TResult2 = never>(onfulfilled?: ((value: Page<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+  /**
+   * Returns an async iterable of page objects.
+   *
+   * Follows `links.next` until null (EC47).
+   */
+  pages(): AsyncIterable<Page<T>>;
+  private fetchFirstPage;
+}
+//#endregion
+//#region src/types/accounts.d.ts
+interface AccountSummary {
+  account: string;
+  alias: string | null;
+  auto_renew_period: string | null;
+  balance: AccountBalance;
+  created_timestamp: string | null;
+  decline_reward: boolean;
+  deleted: boolean;
+  ethereum_nonce: string;
+  evm_address: string | null;
+  expiry_timestamp: string | null;
+  key: HieroKey | null;
+  max_automatic_token_associations: number;
+  memo: string;
+  pending_reward: string;
+  receiver_sig_required: boolean | null;
+  staked_account_id: string | null;
+  /** EC137: Plain number, not `0.0.X` format (EC32). */
+  staked_node_id: number | null;
+  stake_period_start: string | null;
+}
+interface AccountDetail extends AccountSummary {
+  /** Embedded recent transactions (sub-resource with own pagination). */
+  transactions: AccountTransaction[];
+  links: {
+    next: string | null;
+  };
+}
+/**
+ * Nested balance object on account detail.
+ *
+ * EC40: This is NOT the same shape as `BalanceEntry` from `/balances`.
+ */
+interface AccountBalance {
+  balance: string;
+  timestamp: string;
+  tokens: TokenBalance[];
+}
+interface TokenRelationship {
+  automatic_association: boolean;
+  balance: string;
+  created_timestamp: string;
+  decimals: string;
+  freeze_status: FreezeStatus;
+  kyc_status: KycStatus;
+  token_id: string;
+}
+interface StakingReward {
+  account_id: string;
+  amount: string;
+  timestamp: string;
+}
+interface CryptoAllowance {
+  amount: string;
+  amount_granted: string;
+  owner: string;
+  spender: string;
+  timestamp: {
+    from: string;
+    to: string | null;
+  };
+}
+interface TokenAllowance {
+  amount: string;
+  amount_granted: string;
+  owner: string;
+  spender: string;
+  token_id: string;
+  timestamp: {
+    from: string;
+    to: string | null;
+  };
+}
+interface NftAllowance {
+  approved_for_all: boolean;
+  owner: string;
+  spender: string;
+  token_id: string;
+  timestamp: {
+    from: string;
+    to: string | null;
+  };
+}
+interface Airdrop {
+  amount: string;
+  receiver_id: string;
+  sender_id: string;
+  serial_number: string | null;
+  token_id: string;
+  timestamp: {
+    from: string;
+    to: string | null;
+  };
+}
+interface AccountTransaction {
+  bytes: string | null;
+  charged_tx_fee: string;
+  consensus_timestamp: string;
+  entity_id: string | null;
+  max_fee: string;
+  memo_base64: string;
+  name: string;
+  nft_transfers: NftTransfer[];
+  node: string | null;
+  nonce: number;
+  parent_consensus_timestamp: string | null;
+  result: string;
+  scheduled: boolean;
+  staking_reward_transfers: StakingRewardTransfer[];
+  token_transfers: TokenTransfer[];
+  transaction_hash: string;
+  transaction_id: string;
+  transfers: Transfer[];
+  valid_duration_seconds: string;
+  valid_start_timestamp: string;
+}
+interface AccountListParams {
+  'account.id'?: string | OperatorFilter<string>;
+  'account.publickey'?: string;
+  balance?: boolean;
+  limit?: number;
+  order?: Order;
+}
+interface AccountTokensParams {
+  'token.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+interface AccountNftsParams {
+  'token.id'?: string | OperatorFilter<string>;
+  serialnumber?: number;
+  'spender.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+interface AccountRewardsParams {
+  timestamp?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+interface AllowanceCryptoParams {
+  'spender.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+interface AllowanceTokenParams {
+  'spender.id'?: string | OperatorFilter<string>;
+  'token.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+interface AllowanceNftParams {
+  'account.id'?: string | OperatorFilter<string>;
+  'token.id'?: string | OperatorFilter<string>;
+  /** EC69: This is an Account ID string, NOT a boolean. */
+  owner?: string;
+  limit?: number;
+  order?: Order;
+}
+interface AirdropParams {
+  'receiver.id'?: string | OperatorFilter<string>;
+  'sender.id'?: string | OperatorFilter<string>;
+  'token.id'?: string | OperatorFilter<string>;
+  serialnumber?: number;
+  limit?: number;
+  order?: Order;
+}
+//#endregion
+//#region src/types/tokens.d.ts
+interface FractionAmount {
+  numerator: number;
+  denominator: number;
+}
+interface FixedFee {
+  all_collectors_are_exempt: boolean;
+  amount: string;
+  collector_account_id: string;
+  denominating_token_id: string | null;
+}
+interface FractionalFee {
+  all_collectors_are_exempt: boolean;
+  amount: FractionAmount;
+  collector_account_id: string;
+  denominating_token_id: string | null;
+  maximum: string | null;
+  minimum: string;
+  net_of_transfers: boolean;
+}
+interface RoyaltyFee {
+  all_collectors_are_exempt: boolean;
+  amount: FractionAmount;
+  collector_account_id: string;
+  fallback_fee: FixedFee | null;
+}
+interface CustomFees {
+  created_timestamp: string;
+  fixed_fees: FixedFee[];
+  fractional_fees: FractionalFee[];
+  royalty_fees: RoyaltyFee[];
+}
+interface TokenSummary {
+  admin_key: HieroKey | null;
+  /** EC14/88: Always `string`, even though list returns `number`. */
+  decimals: string;
+  metadata: string;
+  name: string;
+  symbol: string;
+  token_id: string;
+  type: TokenType;
+}
+interface TokenDetail extends TokenSummary {
+  auto_renew_account: string | null;
+  auto_renew_period: string | null;
+  created_timestamp: string;
+  custom_fees: CustomFees;
+  deleted: boolean;
+  expiry_timestamp: string | null;
+  fee_schedule_key: HieroKey | null;
+  freeze_default: boolean;
+  freeze_key: HieroKey | null;
+  initial_supply: string;
+  kyc_key: HieroKey | null;
+  max_supply: string;
+  memo: string;
+  metadata_key: HieroKey | null;
+  modified_timestamp: string;
+  pause_key: HieroKey | null;
+  pause_status: string;
+  supply_key: HieroKey | null;
+  supply_type: string;
+  total_supply: string;
+  treasury_account_id: string;
+  wipe_key: HieroKey | null;
+}
+interface TokenNft {
+  account_id: string;
+  created_timestamp: string;
+  delegating_spender: string | null;
+  deleted: boolean;
+  metadata: string;
+  modified_timestamp: string;
+  serial_number: string;
+  spender: string | null;
+  token_id: string;
+}
+interface TokenBalanceEntry {
+  account: string;
+  balance: string;
+  decimals: string;
+}
+interface TokenBalanceResponse {
+  /** EC134: Can be null. */
+  timestamp: string | null;
+  balances: TokenBalanceEntry[];
+  links: {
+    next: string | null;
+  };
+}
+interface TokenListParams {
+  'account.id'?: string;
+  limit?: number;
+  name?: string;
+  order?: Order;
+  publickey?: string;
+  'token.id'?: string | OperatorFilter<string>;
+  /** EC126: Case-insensitive, normalized to UPPERCASE. */
+  type?: TokenType;
+}
+interface TokenNftListParams {
+  'account.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+  /** EC129: No operators allowed on serialnumber for NFTs. */
+  serialnumber?: number;
+}
+interface TokenBalanceParams {
+  'account.id'?: string | OperatorFilter<string>;
+  timestamp?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+//#endregion
+//#region src/resources/accounts.d.ts
+declare class AccountsResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: AccountListParams): Paginator<AccountSummary>;
+  get(idOrAliasOrEvmAddress: string): Promise<AccountDetail>;
+  getNFTs(idOrAliasOrEvmAddress: string, params?: AccountNftsParams): Paginator<TokenNft>;
+  getTokens(idOrAliasOrEvmAddress: string, params?: AccountTokensParams): Paginator<TokenRelationship>;
+  getRewards(idOrAliasOrEvmAddress: string, params?: AccountRewardsParams): Paginator<StakingReward>;
+  getCryptoAllowances(idOrAliasOrEvmAddress: string, params?: AllowanceCryptoParams): Paginator<CryptoAllowance>;
+  getTokenAllowances(idOrAliasOrEvmAddress: string, params?: AllowanceTokenParams): Paginator<TokenAllowance>;
+  getNftAllowances(idOrAliasOrEvmAddress: string, params?: AllowanceNftParams): Paginator<NftAllowance>;
+  getOutstandingAirdrops(idOrAliasOrEvmAddress: string, params?: AirdropParams): Paginator<Airdrop>;
+  getPendingAirdrops(idOrAliasOrEvmAddress: string, params?: AirdropParams): Paginator<Airdrop>;
+}
+//#endregion
+//#region src/types/balances.d.ts
+/**
+ * A balance entry from the global `/balances` endpoint.
+ *
+ * EC40: This is NOT the nested `AccountBalance` shape from `/accounts/{id}`.
+ */
+interface BalanceEntry {
+  account: string;
+  balance: string;
+  tokens: TokenBalance[];
+}
+interface BalanceListParams {
+  'account.id'?: string | OperatorFilter<string>;
+  'account.publickey'?: string;
+  'account.balance'?: string | OperatorFilter<string>;
+  timestamp?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+//#endregion
+//#region src/resources/balances.d.ts
+declare class BalancesResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: BalanceListParams): Paginator<BalanceEntry>;
+}
+//#endregion
+//#region src/types/blocks.d.ts
+/**
+ * A block on the Hedera network.
+ *
+ * EC15/28: `timestamp` is a `TimestampRange` (object), NOT a string.
+ * List and detail have the same shape (0 drift).
+ */
+interface Block {
+  count: number;
+  gas_used: string;
+  hapi_version: string;
+  hash: string;
+  logs_bloom: string;
+  name: string;
+  number: number;
+  previous_hash: string;
+  size: number;
+  /** EC15/28: Object with `from` and `to` fields, not a string. */
+  timestamp: TimestampRange;
+}
+interface BlockListParams {
+  /** EC90: Supports hex string block IDs in query. */
+  'block.number'?: number | string | OperatorFilter<number | string>;
+  limit?: number;
+  order?: Order;
+  timestamp?: string | OperatorFilter<string>;
+}
+//#endregion
+//#region src/resources/blocks.d.ts
+declare class BlocksResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: BlockListParams): Paginator<Block>;
+  get(hashOrNumber: string | number): Promise<Block>;
+}
+//#endregion
+//#region src/types/contracts.d.ts
+interface ContractSummary {
+  admin_key: HieroKey | null;
+  auto_renew_account: string | null;
+  auto_renew_period: string | null;
+  contract_id: string;
+  created_timestamp: string;
+  deleted: boolean;
+  evm_address: string;
+  expiration_timestamp: string | null;
+  file_id: string | null;
+  max_automatic_token_associations: number;
+  memo: string;
+  nonce: string;
+  obtainer_id: string | null;
+  permanent_removal: boolean | null;
+  proxy_account_id: string | null;
+  timestamp: TimestampRange;
+}
+interface ContractDetail extends ContractSummary {
+  bytecode: string;
+  runtime_bytecode: string;
+}
+interface ContractResult {
+  access_list: string | null;
+  address: string;
+  amount: string;
+  block_gas_used: string;
+  block_hash: string;
+  block_number: number;
+  bloom: string;
+  call_result: string | null;
+  chain_id: string;
+  contract_id: string | null;
+  created_contract_ids: string[];
+  error_message: string | null;
+  /** Hex-decoded human-readable error (EC24). */
+  error_message_decoded: string | null;
+  failed_initcode: string | null;
+  from: string;
+  function_parameters: string;
+  gas_consumed: string | null;
+  gas_limit: string;
+  gas_price: string;
+  gas_used: string;
+  hash: string;
+  logs: ContractLog[];
+  max_fee_per_gas: string;
+  max_priority_fee_per_gas: string;
+  nonce: number;
+  r: string;
+  result: string;
+  s: string;
+  state_changes: StateChange[];
+  status: string;
+  timestamp: string;
+  to: string | null;
+  transaction_index: number;
+  type: number;
+  v: number;
+}
+interface ContractLog {
+  address: string;
+  bloom: string;
+  contract_id: string;
+  data: string;
+  index: number;
+  /** EC138: 0-4 items, each `0x`-prefixed hex string. */
+  topics: string[];
+  root_contract_id: string | null;
+  timestamp: string;
+  block_hash: string;
+  block_number: number;
+  transaction_hash: string;
+  transaction_index: number;
+}
+interface StateChange {
+  address: string;
+  contract_id: string;
+  slot: string;
+  value_read: string;
+  /** Null for read-only accesses. */
+  value_written: string | null;
+}
+interface ContractAction {
+  call_depth: number;
+  call_operation_type: string;
+  call_type: string;
+  caller: string;
+  caller_type: string;
+  from: string;
+  gas: string;
+  gas_used: string;
+  index: number;
+  input: string | null;
+  recipient: string | null;
+  recipient_type: string | null;
+  result_data: string | null;
+  result_data_type: string;
+  timestamp: string;
+  to: string | null;
+  value: string;
+}
+/**
+ * Request body for `client.contracts.call()`.
+ *
+ * EC132: `value` is NOT accepted (read-only simulation).
+ */
+interface ContractCallRequest {
+  /** Block tag or number. Default: `"latest"` (EC130). */
+  block?: string;
+  data: string;
+  estimate?: boolean;
+  /** EC133: Optional sender address for simulation. */
+  from?: string;
+  /** EC131: Must be > 0. */
+  gas?: number;
+  gasPrice?: number;
+  to: string;
+}
+interface ContractCallResponse {
+  result: string;
+}
+interface ContractListParams {
+  'contract.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+}
+interface ContractResultsParams {
+  block_hash?: string;
+  block_number?: number | OperatorFilter<number>;
+  from?: string;
+  internal?: boolean;
+  limit?: number;
+  order?: Order;
+  timestamp?: string | OperatorFilter<string>;
+  transaction_index?: number;
+}
+interface ContractLogsParams {
+  index?: number | OperatorFilter<number>;
+  limit?: number;
+  order?: Order;
+  timestamp?: string | OperatorFilter<string>;
+  topic0?: string | OperatorFilter<string>;
+  topic1?: string | OperatorFilter<string>;
+  topic2?: string | OperatorFilter<string>;
+  topic3?: string | OperatorFilter<string>;
+}
+interface ContractStateParams {
+  limit?: number;
+  order?: Order;
+  slot?: string | OperatorFilter<string>;
+  timestamp?: string | OperatorFilter<string>;
+}
+//#endregion
+//#region src/resources/contracts.d.ts
+declare class ContractsResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: ContractListParams): Paginator<ContractSummary>;
+  get(contractIdOrAddress: string): Promise<ContractDetail>;
+  /**
+   * POST /api/v1/contracts/call — smart contract read-only simulation.
+   *
+   * EC29/51/130-133.
+   */
+  call(request: ContractCallRequest): Promise<ContractCallResponse>;
+  getResults(params?: ContractResultsParams): Paginator<ContractResult>;
+  getResultsByContract(contractIdOrAddress: string, params?: ContractResultsParams): Paginator<ContractResult>;
+  getResultByTimestamp(contractIdOrAddress: string, timestamp: string): Promise<ContractResult>;
+  getResultByTransactionIdOrHash(transactionIdOrHash: string): Promise<ContractResult>;
+  getActions(transactionIdOrHash: string): Paginator<ContractAction>;
+  getLogs(params?: ContractLogsParams): Paginator<ContractLog>;
+  getLogsByContract(contractIdOrAddress: string, params?: ContractLogsParams): Paginator<ContractLog>;
+  getState(contractIdOrAddress: string, params?: ContractStateParams): Paginator<StateChange>;
+  getOpcodes(transactionIdOrHash: string): Promise<unknown>;
+}
+//#endregion
+//#region src/types/network.d.ts
+/**
+ * A consensus node in the Hedera network.
+ *
+ * EC32: `node_id` is a plain number, NOT `0.0.X` format.
+ * EC60: `stake` is `string` (int64, may exceed MAX_SAFE_INTEGER).
+ * EC28: `timestamp` is a `TimestampRange` (to can be null for active nodes).
+ */
+interface NetworkNode {
+  admin_key: unknown | null;
+  description: string;
+  file_id: string;
+  max_stake: string;
+  memo: string;
+  min_stake: string;
+  node_account_id: string;
+  /** EC32: Plain number, not entity ID format. */
+  node_id: number;
+  node_cert_hash: string;
+  public_key: string;
+  reward_rate_start: string;
+  service_endpoints: ServiceEndpoint[];
+  /** EC60: String (int64, may exceed MAX_SAFE_INTEGER). */
+  stake: string;
+  stake_not_rewarded: string;
+  stake_rewarded: string;
+  staking_period: TimestampRange;
+  /** EC28: `to` can be null for currently active nodes. */
+  timestamp: TimestampRange;
+}
+interface ServiceEndpoint {
+  ip_address_v4: string;
+  port: number;
+  domain_name: string;
+}
+/**
+ * Network staking information.
+ *
+ * EC36: All staking values as `string` (raw numbers exceed MAX_SAFE_INTEGER).
+ */
+interface NetworkStake {
+  max_stake_rewarded: string;
+  max_staking_reward_rate_per_hbar: string;
+  max_total_reward: string;
+  node_reward_fee_fraction: number;
+  reserved_staking_rewards: string;
+  reward_balance_threshold: string;
+  stake_total: string;
+  staking_period: TimestampRange;
+  staking_period_duration: string;
+  staking_periods_stored: string;
+  staking_reward_fee_fraction: number;
+  staking_reward_rate: string;
+  staking_start_threshold: string;
+  unreserved_staking_reward_balance: string;
+}
+interface ExchangeRate {
+  cent_equivalent: number;
+  expiration_time: number;
+  hbar_equivalent: number;
+}
+interface ExchangeRateSet {
+  current_rate: ExchangeRate;
+  next_rate: ExchangeRate;
+  timestamp: string;
+}
+interface Supply {
+  released_supply: string;
+  timestamp: string;
+  total_supply: string;
+}
+interface Fee {
+  gas: string;
+  transaction_type: string;
+}
+interface FeeSchedule {
+  current?: Fee[];
+  next?: Fee[];
+  timestamp: string;
+}
+interface NetworkNodeParams {
+  /** EC59: `file_id` is rejected by server. Not included. */
+  limit?: number;
+  'node.id'?: number | OperatorFilter<number>;
+  order?: Order;
+}
+interface NetworkFeeParams {
+  order?: Order;
+  timestamp?: string | OperatorFilter<string>;
+}
+interface NetworkSupplyParams {
+  timestamp?: string | OperatorFilter<string>;
+}
+//#endregion
+//#region src/resources/network.d.ts
+declare class NetworkResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  getExchangeRate(): Promise<ExchangeRateSet>;
+  getFees(params?: NetworkFeeParams): Promise<FeeSchedule>;
+  /**
+   * POST /api/v1/network/fees — estimate fees from protobuf payload.
+   *
+   * EC52: Accepts raw Uint8Array (user must serialize protobuf externally).
+   */
+  estimateFees(body: Uint8Array): Promise<unknown>;
+  getNodes(params?: NetworkNodeParams): Paginator<NetworkNode>;
+  getStake(): Promise<NetworkStake>;
+  getSupply(params?: NetworkSupplyParams): Promise<Supply>;
+}
+//#endregion
+//#region src/types/schedules.d.ts
+interface Schedule {
+  admin_key: HieroKey | null;
+  consensus_timestamp: string | null;
+  creator_account_id: string;
+  deleted: boolean;
+  executed_timestamp: string | null;
+  expiration_time: string | null;
+  memo: string;
+  payer_account_id: string;
+  schedule_id: string;
+  signatures: ScheduleSignature[];
+  transaction_body: string;
+  wait_for_expiry: boolean;
+}
+interface ScheduleSignature {
+  consensus_timestamp: string;
+  public_key_prefix: string;
+  signature: string;
+  type: string;
+}
+interface ScheduleListParams {
+  'account.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+  'schedule.id'?: string | OperatorFilter<string>;
+}
+//#endregion
+//#region src/resources/schedules.d.ts
+declare class SchedulesResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: ScheduleListParams): Paginator<Schedule>;
+  get(scheduleId: string): Promise<Schedule>;
+}
+//#endregion
+//#region src/types/transactions.d.ts
+interface Transaction {
+  bytes: string | null;
+  charged_tx_fee: string;
+  consensus_timestamp: string;
+  /** EC39: Null on failed transactions. */
+  entity_id: string | null;
+  max_fee: string;
+  memo_base64: string;
+  name: string;
+  nft_transfers: NftTransfer[];
+  node: string | null;
+  nonce: number;
+  parent_consensus_timestamp: string | null;
+  result: string;
+  scheduled: boolean;
+  /** EC135: Always an array, never null or missing. */
+  staking_reward_transfers: StakingRewardTransfer[];
+  token_transfers: TokenTransfer[];
+  /** Base64-encoded hash. Use `base64ToHex()` for `0x` format. */
+  transaction_hash: string;
+  transaction_id: string;
+  transfers: Transfer[];
+  valid_duration_seconds: string;
+  valid_start_timestamp: string;
+}
+/**
+ * NFT-specific transaction from `/tokens/{id}/nfts/{serial}/transactions`.
+ *
+ * EC77: Has top-level `receiver_account_id` and `sender_account_id` fields
+ * instead of nested `transfers`.
+ */
+interface NftTransaction {
+  consensus_timestamp: string;
+  is_approval: boolean;
+  nonce: number;
+  receiver_account_id: string | null;
+  sender_account_id: string | null;
+  transaction_id: string;
+  type: string;
+}
+interface TransactionListParams {
+  'account.id'?: string | OperatorFilter<string>;
+  limit?: number;
+  order?: Order;
+  result?: TransactionResult;
+  timestamp?: string | OperatorFilter<string>;
+  /** EC127: Case-insensitive, normalized to UPPERCASE. */
+  transactiontype?: string;
+}
+/**
+ * Parameters for `transactions.get()`.
+ *
+ * EC124/125: `nonce` and `scheduled` are only valid on detail, NOT on list.
+ */
+interface TransactionGetParams {
+  nonce?: number;
+  scheduled?: boolean;
+}
+//#endregion
+//#region src/resources/tokens.d.ts
+declare class TokensResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: TokenListParams): Paginator<TokenSummary>;
+  get(tokenId: string): Promise<TokenDetail>;
+  getBalances(tokenId: string, params?: TokenBalanceParams): Paginator<TokenBalanceEntry>;
+  getNFTs(tokenId: string, params?: TokenNftListParams): Paginator<TokenNft>;
+  getNFTBySerial(tokenId: string, serialNumber: number | string): Promise<TokenNft>;
+  getNFTTransactions(tokenId: string, serialNumber: number | string, params?: TransactionListParams): Paginator<NftTransaction>;
+}
+//#endregion
+//#region src/types/topics.d.ts
+/**
+ * A message published to a Hedera Consensus Service topic.
+ *
+ * EC3/18: `message` and `running_hash` are auto-decoded from Base64
+ * to `Uint8Array` by the response mapper.
+ */
+interface TopicMessage {
+  chunk_info: ChunkInfo | null;
+  consensus_timestamp: string;
+  message: Uint8Array;
+  payer_account_id: string;
+  running_hash: Uint8Array;
+  running_hash_version: number;
+  sequence_number: string;
+  topic_id: string;
+}
+interface ChunkInfo {
+  initial_transaction_id: {
+    account_id: string;
+    nonce: number;
+    scheduled: boolean;
+    transaction_valid_start: string;
+  };
+  number: number;
+  total: number;
+}
+interface TopicInfo {
+  admin_key: unknown | null;
+  auto_renew_account: string | null;
+  auto_renew_period: string | null;
+  created_timestamp: string;
+  deleted: boolean;
+  memo: string;
+  submit_key: unknown | null;
+  timestamp: {
+    from: string;
+    to: string | null;
+  };
+  topic_id: string;
+}
+interface TopicMessageParams {
+  /** EC44/72: `'base64'` (default) or `'utf-8'`. */
+  encoding?: 'base64' | 'utf-8';
+  limit?: number;
+  order?: Order;
+  sequencenumber?: number | OperatorFilter<number>;
+  timestamp?: string | OperatorFilter<string>;
+}
+interface TopicStreamOptions$1 {
+  /** Starting timestamp cursor. Default: `'now'`. */
+  startTimestamp?: string;
+  /** Polling interval in ms. Default: adaptive (500–5000ms). */
+  interval?: number;
+  /** Limit per poll request. Default: 100. */
+  limit?: number;
+  /** AbortSignal for cancellation. */
+  signal?: AbortSignal;
+}
+//#endregion
+//#region src/pagination/stream.d.ts
+interface TopicStreamOptions {
+  /** Starting timestamp cursor. Default: current time. */
+  startTimestamp?: string;
+  /** Base polling interval in ms. Default: 500ms (active), backs off to 5s. */
+  interval?: number;
+  /** Maximum items per poll request. Default: 100. */
+  limit?: number;
+  /** AbortSignal for cancellation. */
+  signal?: AbortSignal;
+}
+/**
+ * Adaptive polling stream for topic messages.
+ *
+ * - Polls at high frequency (500ms) when messages are flowing.
+ * - Backs off exponentially (up to 5s) when no messages arrive.
+ * - Cancellable via `AbortController`.
+ * - Rate-limit aware (shares the HttpClient's token bucket).
+ */
+declare class TopicStream implements AsyncIterable<TopicMessage> {
+  private readonly client;
+  private readonly topicId;
+  private readonly options;
+  /** Minimum polling interval (ms). */
+  private static readonly MIN_INTERVAL;
+  /** Maximum polling interval (ms). */
+  private static readonly MAX_INTERVAL;
+  /** Factor by which interval increases on empty polls. */
+  private static readonly BACKOFF_FACTOR;
+  constructor(client: HttpClient, topicId: string, options?: TopicStreamOptions);
+  [Symbol.asyncIterator](): AsyncIterator<TopicMessage>;
+  private sleep;
+}
+//#endregion
+//#region src/resources/topics.d.ts
+declare class TopicsResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  get(topicId: string): Promise<TopicInfo>;
+  getMessages(topicId: string, params?: TopicMessageParams): Paginator<TopicMessage>;
+  getMessageBySequence(topicId: string, sequenceNumber: number | string): Promise<TopicMessage>;
+  getMessageByTimestamp(timestamp: string): Promise<TopicMessage>;
+  stream(topicId: string, options?: TopicStreamOptions$1): TopicStream;
+}
+//#endregion
+//#region src/resources/transactions.d.ts
+declare class TransactionsResource {
+  private readonly client;
+  constructor(client: HttpClient);
+  list(params?: TransactionListParams): Paginator<Transaction>;
+  /**
+   * Get a transaction by ID.
+   *
+   * EC21/150/151: The API returns `{ transactions: [{ ... }] }`.
+   * This method unwraps to return the single transaction.
+   */
+  get(transactionId: string, params?: TransactionGetParams): Promise<Transaction>;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Built-in network presets for the Hedera/Hiero Mirror Node.
+ */
+type HieroNetwork = 'mainnet' | 'testnet' | 'previewnet';
+interface MirrorNodeClientOptions {
+  /**
+   * Network preset. Mutually exclusive with `baseUrl`.
+   *
+   * If neither `network` nor `baseUrl` is provided, defaults to `'mainnet'`.
+   */
+  network?: HieroNetwork;
+  /**
+   * Custom base URL. Mutually exclusive with `network`.
+   *
+   * Useful for self-hosted mirror nodes or proxies.
+   */
+  baseUrl?: string;
+  /** Request timeout in ms. Default: `30_000`. */
+  timeout?: number;
+  /** Maximum retry attempts for retryable failures. Default: `2`. */
+  maxRetries?: number;
+  /** Rate limit in requests per second. Default: `50`. */
+  rateLimitRps?: number;
+  /** Optional logger. Compatible with `console`, `pino`, `winston`. */
+  logger?: Logger$1;
+  /** Custom `fetch` implementation (for testing or environments without global fetch). */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * The main Hiero Mirror Client SDK entry point.
+ *
+ * Provides typed access to all Mirror Node REST API resources with:
+ * - Automatic pagination via `Paginator`
+ * - Safe JSON parsing for int64 precision
+ * - ETag caching, retry/backoff, and rate limiting
+ * - Type-safe responses via response mappers
+ */
+declare class MirrorNodeClient {
+  /** Account operations: list, get, NFTs, tokens, rewards, allowances, airdrops. */
+  readonly accounts: AccountsResource;
+  /** Global balance queries. */
+  readonly balances: BalancesResource;
+  /** Block queries. */
+  readonly blocks: BlocksResource;
+  /** Contract queries and smart contract call simulation. */
+  readonly contracts: ContractsResource;
+  /** Network info: exchange rate, fees, nodes, stake, supply. */
+  readonly network: NetworkResource;
+  /** Schedule queries. */
+  readonly schedules: SchedulesResource;
+  /** Token queries: list, get, balances, NFTs, NFT transactions. */
+  readonly tokens: TokensResource;
+  /** Topic queries and HCS message streaming. */
+  readonly topics: TopicsResource;
+  /** Transaction queries. */
+  readonly transactions: TransactionsResource;
+  /** The underlying HTTP client (exposed for advanced usage). */
+  readonly httpClient: HttpClient;
+  constructor(options?: MirrorNodeClientOptions);
+}
+//#endregion
+//#region src/errors/HieroError.d.ts
+/**
+ * Base error class for all Hiero Mirror Client errors.
+ *
+ * Modeled after Stripe's error hierarchy — every SDK error extends this class,
+ * enabling `instanceof HieroError` to catch all SDK-specific errors.
+ *
+ * @public
+ */
+declare class HieroError extends Error {
+  /** HTTP status code, if the error originated from an HTTP response. */
+  readonly statusCode?: number;
+  /** The raw response body, if available. */
+  readonly rawBody?: string;
+  constructor(message: string, options?: {
+    statusCode?: number;
+    rawBody?: string;
+    cause?: unknown;
+  });
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+//#region src/errors/HieroParseError.d.ts
+/**
+ * Thrown when the response body cannot be parsed as JSON,
+ * or when the response Content-Type is unexpected (e.g., `text/html`
+ * for Unicode parameter errors — EC153).
+ *
+ * @public
+ */
+declare class HieroParseError extends HieroError {
+  /** The raw body text that could not be parsed. */
+  readonly body: string;
+  constructor(message: string, options: {
+    body: string;
+    statusCode?: number;
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/errors/HieroCapabilityError.d.ts
+/**
+ * Thrown when a known feature is disabled on the mirror node
+ * (e.g., `/stateproof` returns 404 on valid transaction IDs — EC62).
+ *
+ * Distinct from {@link HieroNotFoundError} because the entity exists
+ * but the feature is unavailable on this mirror node instance.
+ *
+ * @public
+ */
+declare class HieroCapabilityError extends HieroError {
+  /** The feature/endpoint that is disabled. */
+  readonly feature: string;
+  constructor(message: string, options: {
+    feature: string;
+    rawBody?: string;
+  });
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+//#region src/errors/HieroNetworkError.d.ts
+/**
+ * Thrown when a network-level error occurs: DNS resolution failure,
+ * connection refused, socket hangup, etc.
+ *
+ * @public
+ */
+declare class HieroNetworkError extends HieroError {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/errors/HieroNotFoundError.d.ts
+/**
+ * Thrown when the server returns HTTP 404 (Not Found) for a specific entity.
+ *
+ * @public
+ */
+declare class HieroNotFoundError extends HieroError {
+  /** The entity ID that was not found, if available. */
+  readonly entityId?: string;
+  constructor(message: string, options?: {
+    entityId?: string;
+    rawBody?: string;
+  });
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+//#region src/errors/HieroRateLimitError.d.ts
+/**
+ * Thrown when the server returns HTTP 429 (Too Many Requests).
+ *
+ * @public
+ */
+declare class HieroRateLimitError extends HieroError {
+  /** Seconds to wait before retrying, parsed from `Retry-After` header. */
+  readonly retryAfter?: number;
+  constructor(message: string, options?: {
+    retryAfter?: number;
+    rawBody?: string;
+  });
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+//#region src/errors/HieroServerError.d.ts
+/**
+ * Thrown when the server returns an HTTP 5xx error.
+ *
+ * @public
+ */
+declare class HieroServerError extends HieroError {
+  constructor(message: string, options?: {
+    statusCode?: number;
+    rawBody?: string;
+  });
+}
+//#endregion
+//#region src/errors/HieroTimeoutError.d.ts
+/**
+ * Thrown when a request exceeds the configured timeout (AbortController).
+ *
+ * @public
+ */
+declare class HieroTimeoutError extends HieroError {
+  /** The timeout duration in milliseconds that was exceeded. */
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/errors/HieroValidationError.d.ts
+/**
+ * Thrown when the server returns HTTP 400 or 415, or when client-side
+ * input validation fails before the request is sent.
+ *
+ * @public
+ */
+declare class HieroValidationError extends HieroError {
+  /** The specific parameter that caused the validation error, if known. */
+  readonly parameter?: string;
+  constructor(message: string, options?: {
+    statusCode?: number;
+    parameter?: string;
+    rawBody?: string;
+  });
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * @satianurag/hiero-mirror-client
+ *
+ * Standalone TypeScript client for the Hedera/Hiero Mirror Node REST API.
+ *
+ * @packageDocumentation
+ */
+declare const VERSION = "0.0.0";
+//#endregion
+export { AccountBalance, AccountDetail, AccountListParams, AccountNftsParams, AccountRewardsParams, AccountSummary, AccountTokensParams, AccountTransaction, Airdrop, AirdropParams, AllowanceCryptoParams, AllowanceNftParams, AllowanceTokenParams, BalanceEntry, BalanceListParams, Block, BlockListParams, ChunkInfo, ContractAction, ContractCallRequest, ContractCallResponse, ContractDetail, ContractListParams, ContractLog, ContractLogsParams, ContractResult, ContractResultsParams, ContractStateParams, ContractSummary, CryptoAllowance, CustomFees, ExchangeRate, ExchangeRateSet, Fee, FeeSchedule, FixedFee, FractionAmount, FractionalFee, FreezeStatus, Hex, HieroCapabilityError, HieroError, HieroKey, type HieroNetwork, HieroNetworkError, HieroNotFoundError, HieroParseError, HieroRateLimitError, HieroServerError, HieroTimeoutError, HieroValidationError, KycStatus, Logger, MirrorNodeClient, type MirrorNodeClientOptions, NetworkFeeParams, NetworkNode, NetworkNodeParams, NetworkStake, NetworkSupplyParams, NftAllowance, NftTransaction, NftTransfer, OperatorFilter, OperatorQuery, Order, Page, type PageExtractor, PaginationLinks, Paginator, type PaginatorOptions, RoyaltyFee, Schedule, ScheduleListParams, ScheduleSignature, ServiceEndpoint, StakingReward, StakingRewardTransfer, StateChange, Supply, TimestampRange, TokenAllowance, TokenBalance, TokenBalanceEntry, TokenBalanceParams, TokenBalanceResponse, TokenDetail, TokenListParams, TokenNft, TokenNftListParams, TokenRelationship, TokenSummary, TokenTransfer, TokenType, TopicInfo, TopicMessage, TopicMessageParams, TopicStream, type TopicStreamOptions, Transaction, TransactionGetParams, TransactionListParams, TransactionResult, Transfer, VERSION };
+//# sourceMappingURL=index.d.mts.map