@hbar-kit/mirror 0.1.0

package/src/normalize.ts

@@ -0,0 +1,81 @@
+import { parseTimestamp } from "@hbar-kit/core"
+import type {
+  RawTransaction,
+  Transaction,
+  RawToken,
+  Token,
+  RawAccount,
+  AccountBalance,
+  RawStatus,
+} from "./types.js"
+
+const decodeMemo = (b64: string): string => (b64 ? Buffer.from(b64, "base64").toString("utf8") : "")
+
+export function normalizeTransaction(raw: RawTransaction): Transaction {
+  return {
+    transactionId: raw.transaction_id,
+    consensusTimestamp: parseTimestamp(raw.consensus_timestamp),
+    validStartTimestamp: raw.valid_start_timestamp
+      ? parseTimestamp(raw.valid_start_timestamp)
+      : undefined,
+    result: raw.result,
+    name: raw.name,
+    chargedTxFee: raw.charged_tx_fee,
+    memo: decodeMemo(raw.memo_base64),
+    nonce: raw.nonce,
+    scheduled: raw.scheduled,
+    parentConsensusTimestamp: raw.parent_consensus_timestamp,
+    transfers: (raw.transfers ?? []).map((t) => ({
+      account: t.account,
+      amount: t.amount,
+      isApproval: t.is_approval ?? false,
+    })),
+    tokenTransfers: (raw.token_transfers ?? []).map((t) => ({
+      tokenId: t.token_id,
+      account: t.account,
+      amount: t.amount,
+      isApproval: t.is_approval ?? false,
+    })),
+    nftTransfers: (raw.nft_transfers ?? []).map((t) => ({
+      tokenId: t.token_id,
+      sender: t.sender_account_id,
+      receiver: t.receiver_account_id,
+      serial: t.serial_number,
+      isApproval: t.is_approval ?? false,
+    })),
+    raw,
+  }
+}
+
+export function normalizeToken(raw: RawToken): Token {
+  return {
+    tokenId: raw.token_id,
+    decimals: Number(raw.decimals),
+    symbol: raw.symbol,
+    name: raw.name,
+    type: raw.type,
+    totalSupply: raw.total_supply != null ? BigInt(raw.total_supply) : undefined,
+    maxSupply: raw.max_supply != null ? BigInt(raw.max_supply) : undefined,
+    treasuryAccountId: raw.treasury_account_id,
+    raw,
+  }
+}
+
+export function normalizeAccountBalance(raw: RawAccount): AccountBalance {
+  return {
+    accountId: raw.account,
+    balance: raw.balance.balance,
+    tokens: (raw.balance.tokens ?? []).map((t) => ({ tokenId: t.token_id, balance: t.balance })),
+    raw,
+  }
+}
+
+/** Detect Mirror Node not-found: the _status envelope, or an empty transactions array. */
+export function isNotFound(body: unknown): boolean {
+  if (!body || typeof body !== "object") return false
+  const status = (body as RawStatus)._status
+  if (status?.messages?.some((m) => /not found/i.test(m.message))) return true
+  const txs = (body as { transactions?: unknown[] }).transactions
+  if (Array.isArray(txs) && txs.length === 0) return true
+  return false
+}

package/src/paginate.ts

@@ -0,0 +1,23 @@
+import type { Transport } from "./transport.js"
+
+export interface PaginateOptions {
+  maxPages?: number
+}
+
+/** Async-iterate a list endpoint by following links.next verbatim until null. */
+export async function* paginate<T>(
+  transport: Transport,
+  firstPath: string,
+  select: (page: unknown) => T[],
+  options: PaginateOptions = {},
+): AsyncGenerator<T, void, unknown> {
+  const maxPages = options.maxPages ?? 1000
+  let path: string | null = firstPath
+  let pages = 0
+  while (path && pages < maxPages) {
+    const page: unknown = await transport.get(path)
+    for (const item of select(page)) yield item
+    path = (page as { links?: { next: string | null } }).links?.next ?? null
+    pages++
+  }
+}

package/src/resources/accounts.ts

@@ -0,0 +1,28 @@
+import { assertEntityId } from "@hbar-kit/core"
+import type { Transport } from "../transport.js"
+import { normalizeAccountBalance } from "../normalize.js"
+import type { AccountBalance, RawAccount } from "../types.js"
+
+export interface AccountsResource {
+  getBalance(accountId: string): Promise<AccountBalance>
+  isAssociated(accountId: string, tokenId: string): Promise<boolean>
+}
+
+export function createAccountsResource(transport: Transport): AccountsResource {
+  return {
+    async getBalance(accountId) {
+      assertEntityId(accountId)
+      return normalizeAccountBalance(
+        (await transport.get(`/api/v1/accounts/${accountId}`)) as RawAccount,
+      )
+    },
+    async isAssociated(accountId, tokenId) {
+      assertEntityId(accountId)
+      assertEntityId(tokenId)
+      const body = (await transport.get(
+        `/api/v1/accounts/${accountId}/tokens?token.id=${tokenId}`,
+      )) as { tokens?: unknown[] }
+      return Array.isArray(body.tokens) && body.tokens.length > 0
+    },
+  }
+}

package/src/resources/balances.ts

@@ -0,0 +1,19 @@
+import { assertEntityId } from "@hbar-kit/core"
+import type { Transport } from "../transport.js"
+
+export interface BalancesResource {
+  get(accountId: string): Promise<{ accountId: string; balance: bigint; timestamp: string }>
+}
+
+export function createBalancesResource(transport: Transport): BalancesResource {
+  return {
+    async get(accountId) {
+      assertEntityId(accountId)
+      const body = (await transport.get(`/api/v1/balances?account.id=${accountId}&limit=1`)) as {
+        timestamp: string
+        balances: { account: string; balance: bigint }[]
+      }
+      return { accountId, balance: body.balances?.[0]?.balance ?? 0n, timestamp: body.timestamp }
+    },
+  }
+}

package/src/resources/tokens.ts

@@ -0,0 +1,17 @@
+import { assertEntityId } from "@hbar-kit/core"
+import type { Transport } from "../transport.js"
+import { normalizeToken } from "../normalize.js"
+import type { RawToken, Token } from "../types.js"
+
+export interface TokensResource {
+  get(tokenId: string): Promise<Token>
+}
+
+export function createTokensResource(transport: Transport): TokensResource {
+  return {
+    async get(tokenId) {
+      assertEntityId(tokenId)
+      return normalizeToken((await transport.get(`/api/v1/tokens/${tokenId}`)) as RawToken)
+    },
+  }
+}

package/src/resources/transactions.ts

@@ -0,0 +1,52 @@
+import { tsFilter, txIdToMirror } from "@hbar-kit/core"
+import type { Transport } from "../transport.js"
+import { normalizeTransaction } from "../normalize.js"
+import type { Page, RawTransaction, RawTransactionList, Transaction } from "../types.js"
+
+export interface FindTransactionsParams {
+  accountId?: string
+  transactionType?: string
+  result?: "success" | "fail"
+  order?: "asc" | "desc"
+  limit?: number
+  after?: Date | string
+  before?: Date | string
+}
+
+export interface TransactionsResource {
+  find(params?: FindTransactionsParams): Promise<Page<Transaction>>
+  get(transactionId: string): Promise<Transaction[]>
+}
+
+function buildQuery(params: FindTransactionsParams): string {
+  const q = new URLSearchParams()
+  if (params.accountId) q.set("account.id", params.accountId)
+  if (params.transactionType) q.set("transactiontype", params.transactionType)
+  if (params.result) q.set("result", params.result)
+  if (params.order) q.set("order", params.order)
+  q.set("limit", String(Math.min(params.limit ?? 25, 100)))
+  if (params.after) q.append("timestamp", tsFilter("gte", params.after))
+  if (params.before) q.append("timestamp", tsFilter("lt", params.before))
+  return q.toString()
+}
+
+export function createTransactionsResource(transport: Transport): TransactionsResource {
+  return {
+    async find(params = {}) {
+      const body = (await transport.get(
+        `/api/v1/transactions?${buildQuery(params)}`,
+      )) as RawTransactionList
+      return {
+        items: (body.transactions ?? []).map(normalizeTransaction),
+        next: body.links?.next ?? null,
+      }
+    },
+    async get(transactionId) {
+      const id = txIdToMirror(transactionId)
+      const body = (await transport.get(`/api/v1/transactions/${id}`)) as {
+        transactions?: RawTransaction[]
+      }
+      return (body.transactions ?? []).map(normalizeTransaction)
+    },
+  }
+}

package/src/transport.ts

@@ -0,0 +1,84 @@
+import { MirrorHttpError, RateLimitError, TimeoutError, NetworkError } from "@hbar-kit/core"
+import { parseJsonWithBigInt } from "./json.js"
+
+export interface TransportOptions {
+  fetch?: typeof fetch
+  retryCount?: number
+  retryDelay?: number
+  timeout?: number
+  headers?: Record<string, string>
+}
+export interface Transport {
+  get(path: string): Promise<unknown>
+  baseUrl: string
+}
+
+const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504])
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+const jitter = (ms: number) => ms * (0.5 + Math.random())
+
+export function http(baseUrl: string, options: TransportOptions = {}): Transport {
+  const doFetch = options.fetch ?? globalThis.fetch
+  const retryCount = options.retryCount ?? 3
+  const retryDelay = options.retryDelay ?? 150
+  const timeout = options.timeout ?? 10_000
+  const base = baseUrl.replace(/\/+$/, "")
+
+  async function get(path: string): Promise<unknown> {
+    const url = path.startsWith("http") ? path : base + path
+    let attempt = 0
+    let lastErr: unknown
+    while (attempt <= retryCount) {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), timeout)
+      try {
+        const response = await doFetch(url, {
+          signal: controller.signal,
+          headers: { accept: "application/json", ...options.headers },
+        })
+        clearTimeout(timer)
+        if (response.ok) {
+          const text = await response.text()
+          return text ? parseJsonWithBigInt(text) : null
+        }
+        if (RETRYABLE.has(response.status) && attempt < retryCount) {
+          const retryAfter = Number(response.headers.get("retry-after"))
+          const wait =
+            Number.isFinite(retryAfter) && retryAfter > 0
+              ? retryAfter * 1000
+              : jitter(retryDelay * 2 ** attempt)
+          await sleep(wait)
+          attempt++
+          continue
+        }
+        const body = await response.text().catch(() => "")
+        if (response.status === 429) {
+          const ra = Number(response.headers.get("retry-after"))
+          throw new RateLimitError(
+            `Mirror Node rate limited (429)`,
+            Number.isFinite(ra) ? { details: body, retryAfter: ra } : { details: body },
+          )
+        }
+        throw new MirrorHttpError(`Mirror Node HTTP ${response.status}`, response.status, {
+          details: body,
+        })
+      } catch (err) {
+        clearTimeout(timer)
+        if (err instanceof MirrorHttpError) throw err
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw new TimeoutError(`Mirror Node request timed out after ${timeout}ms`, { cause: err })
+        }
+        lastErr = err
+        if (attempt < retryCount) {
+          await sleep(jitter(retryDelay * 2 ** attempt))
+          attempt++
+          continue
+        }
+        throw new NetworkError(`Mirror Node request failed: ${String(err)}`, { cause: err })
+      }
+    }
+    throw new NetworkError(`Mirror Node request failed`, { cause: lastErr })
+  }
+
+  return { get, baseUrl: base }
+}

package/src/types.ts

@@ -0,0 +1,120 @@
+import type { HederaTimestamp } from "@hbar-kit/core"
+
+// ---- Raw Mirror Node shapes ----
+export interface RawTransfer {
+  account: string
+  amount: bigint
+  is_approval?: boolean
+}
+export interface RawTokenTransfer {
+  token_id: string
+  account: string
+  amount: bigint
+  is_approval?: boolean
+}
+export interface RawNftTransfer {
+  token_id: string
+  sender_account_id: string | null
+  receiver_account_id: string | null
+  serial_number: bigint
+  is_approval?: boolean
+}
+export interface RawTransaction {
+  transaction_id: string
+  consensus_timestamp: string
+  valid_start_timestamp?: string
+  result: string
+  name: string
+  charged_tx_fee: bigint
+  memo_base64: string
+  node?: string
+  nonce: number
+  scheduled: boolean
+  parent_consensus_timestamp: string | null
+  transfers: RawTransfer[]
+  token_transfers: RawTokenTransfer[]
+  nft_transfers: RawNftTransfer[]
+}
+export interface RawListLinks {
+  next: string | null
+}
+export interface RawTransactionList {
+  transactions: RawTransaction[]
+  links: RawListLinks
+}
+export interface RawToken {
+  token_id: string
+  decimals: string | number
+  symbol: string
+  name: string
+  type: string
+  total_supply?: string
+  max_supply?: string
+  treasury_account_id?: string
+}
+export interface RawAccount {
+  account: string
+  evm_address?: string
+  deleted?: boolean
+  balance: { balance: bigint; timestamp: string; tokens: { token_id: string; balance: bigint }[] }
+}
+export interface RawStatus {
+  _status?: { messages?: { message: string }[] }
+}
+
+// ---- Normalized shapes ----
+export interface Transfer {
+  account: string
+  amount: bigint
+  isApproval: boolean
+}
+export interface TokenTransfer {
+  tokenId: string
+  account: string
+  amount: bigint
+  isApproval: boolean
+}
+export interface NftTransfer {
+  tokenId: string
+  sender: string | null
+  receiver: string | null
+  serial: bigint
+  isApproval: boolean
+}
+export interface Transaction {
+  transactionId: string
+  consensusTimestamp: HederaTimestamp
+  validStartTimestamp?: HederaTimestamp | undefined
+  result: string
+  name: string
+  chargedTxFee: bigint
+  memo: string
+  nonce: number
+  scheduled: boolean
+  parentConsensusTimestamp: string | null
+  transfers: Transfer[]
+  tokenTransfers: TokenTransfer[]
+  nftTransfers: NftTransfer[]
+  raw: RawTransaction
+}
+export interface Token {
+  tokenId: string
+  decimals: number
+  symbol: string
+  name: string
+  type: string
+  totalSupply?: bigint | undefined
+  maxSupply?: bigint | undefined
+  treasuryAccountId?: string | undefined
+  raw: RawToken
+}
+export interface AccountBalance {
+  accountId: string
+  balance: bigint
+  tokens: { tokenId: string; balance: bigint }[]
+  raw: RawAccount
+}
+export interface Page<T> {
+  items: T[]
+  next: string | null
+}