@satianurag/hiero-mirror-client 0.2.2 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ Built for precision, type safety, and developer ergonomics — no silent data co
 
 ## Features
 
-- **Full API coverage** — 46 methods across 9 resource groups
+- **Full API coverage** — 49 methods across 9 resource groups
 - **Safe JSON parsing** — int64 values preserved as strings (no precision loss)
 - **Three pagination patterns** — `await`, `for await...of`, `.pages()`
 - **Adaptive HCS streaming** — topic message polling with auto-backoff
@@ -14,6 +14,10 @@ Built for precision, type safety, and developer ergonomics — no silent data co
 - **Typed errors** — structured error hierarchy (`HieroNotFoundError`, `HieroRateLimitError`, etc.)
 - **Dual output** — ESM + CJS with full `.d.ts` declarations
 - **Zero platform dependencies** — works in Node.js 22+, Deno, Bun, and browsers
+- **HBAR conversion utilities** — `tinybarToHbar`, `hbarToTinybar`, `formatHbar`
+- **Scheduled transaction helpers** — poll execution, track signatures, filter by account
+- **Transaction confirmation poller** — `waitFor()` bridges consensus-to-mirror-node lag
+- **MCP tool descriptors** — AI agent integration via Model Context Protocol
 
 ## Installation
 
@@ -125,21 +129,94 @@ const client = new MirrorNodeClient({
 | Resource | Methods | Key Operations |
 |----------|---------|----------------|
 | `accounts` | 10 | list, get, NFTs, tokens, rewards, allowances, airdrops |
-| `balances` | 1 | list |
+| `balances` | 3 | list, getForAccount, getTokenBalance |
 | `blocks` | 2 | list, get |
 | `contracts` | 12 | list, get, call (POST), results, actions, logs, state, opcodes |
 | `network` | 6 | exchangeRate, fees, estimateFees (POST), nodes, stake, supply |
 | `schedules` | 2 | list, get |
 | `tokens` | 6 | list, get, balances, NFTs, NFT transactions |
 | `topics` | 5 | get, messages, stream |
-| `transactions` | 2 | list, get |
+| `transactions` | 3 | list, get, waitFor |
+
+## Transaction Confirmation Poller
+
+Bridge the consensus-to-mirror-node ingestion lag (typically 3-7s):
+
+```typescript
+// Poll until the transaction appears on the mirror node
+const tx = await client.transactions.waitFor(
+  '0.0.1234@1615422161.673238162',
+  { timeout: 15_000 },
+);
+console.log(tx.result, tx.consensus_timestamp);
+```
+
+## Balance Helpers
+
+Convenience methods for the most common balance queries:
+
+```typescript
+// Get full balance for an account (HBAR + tokens)
+const balance = await client.balances.getForAccount('0.0.98');
+console.log(balance.account, balance.balance, balance.tokens);
+
+// Get a specific token balance
+const tokenBal = await client.balances.getTokenBalance('0.0.98', '0.0.456');
+if (tokenBal) {
+  console.log(tokenBal.token_id, tokenBal.balance);
+}
+```
+
+## Scheduled Transaction Helpers
+
+High-level workflows for scheduled transactions:
+
+```typescript
+import {
+  waitForExecution,
+  getSignatureProgress,
+  listSchedulesByAccount,
+  decodeTransactionBody,
+} from '@satianurag/hiero-mirror-client';
+
+// Poll until a schedule executes, is deleted, or expires
+const result = await waitForExecution(client.schedules, '0.0.1234', {
+  interval: 2000,
+  timeout: 120_000,
+  onPoll: (schedule) => console.log('Polling...', schedule.schedule_id),
+});
+console.log(result.status); // 'executed' | 'deleted' | 'expired'
+
+// Check signature progress
+const progress = await getSignatureProgress(client.schedules, '0.0.1234');
+console.log(progress.signatureCount, progress.signedKeys);
+
+// List schedules by creator account, filtered by status
+const pending = await listSchedulesByAccount(client.schedules, '0.0.100', {
+  status: 'pending',
+});
+
+// Decode the base64 transaction body
+const decoded = decodeTransactionBody(schedule);
+console.log(decoded.hex, decoded.byteLength);
+```
 
 ## Utilities
 
 Additional utilities available via the `/utils` subpath:
 
 ```typescript
-import { base64ToHex, hexToBase64, fromString, toDate } from '@satianurag/hiero-mirror-client/utils';
+import {
+  base64ToHex, hexToBase64, fromString, toDate,
+  tinybarToHbar, hbarToTinybar, formatHbar,
+} from '@satianurag/hiero-mirror-client/utils';
+
+// HBAR conversion (BigInt-safe, handles up to 8 decimal places)
+tinybarToHbar('100000000');   // '1'
+tinybarToHbar('150000000');   // '1.5'
+tinybarToHbar('1');           // '0.00000001'
+hbarToTinybar('2.5');         // '250000000'
+formatHbar('100000000');      // '1 HBAR'
 
 // Encoding conversions
 const hex = base64ToHex('bZL5Ig==');  // '0x6d92f922'
@@ -150,6 +227,26 @@ ts.seconds; // 1710000000n (BigInt)
 ts.nanos;   // 123456789
 ```
 
+## MCP Tool Descriptors (AI Agent Integration)
+
+Export MCP-compatible tool descriptors for AI agent frameworks:
+
+```typescript
+import { MirrorNodeClient, mirrorNodeTools } from '@satianurag/hiero-mirror-client';
+
+const client = new MirrorNodeClient({ network: 'mainnet' });
+
+// Register with any MCP-compatible server
+for (const tool of mirrorNodeTools) {
+  server.registerTool(tool.name, tool.description, tool.inputSchema, (input) =>
+    tool.execute(client, input),
+  );
+}
+
+// 16 tools covering: accounts, balances, tokens, transactions,
+// schedules, topics, contracts, blocks, and network
+```
+
 ## TypeScript
 
 All types are exported for full TypeScript support:
@@ -160,6 +257,12 @@ import type {
   TokenSummary,
   Transaction,
   NetworkStake,
+  // New helper types
+  WaitForExecutionOptions,
+  ExecutionResult,
+  SignatureProgress,
+  WaitForTransactionOptions,
+  ToolDescriptor,
 } from '@satianurag/hiero-mirror-client';
 ```
 

package/dist/hbar.cjs

@@ -0,0 +1,214 @@
+//#region src/utils/encoding.ts
+/**
+* Cross-platform encoding utilities.
+*
+* No dependency on Node.js `Buffer` — uses Web-standard APIs only.
+*
+* @packageDocumentation
+*/
+/**
+* Base64-to-hex conversion.
+*
+* ```ts
+* base64ToHex('SGVsbG8=') // → '48656c6c6f'
+* ```
+*/
+function base64ToHex(base64) {
+	const bytes = base64ToBytes(base64);
+	return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Hex-to-base64 conversion.
+*
+* Accepts optional 0x prefix.
+*
+* ```ts
+* hexToBase64('48656c6c6f')   // → 'SGVsbG8='
+* hexToBase64('0x48656c6c6f') // → 'SGVsbG8='
+* ```
+*/
+function hexToBase64(hex) {
+	const cleaned = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+	if (cleaned.length % 2 !== 0) throw new Error(`Invalid hex string: odd length (${cleaned.length})`);
+	const bytes = new Uint8Array(cleaned.length / 2);
+	for (let i = 0; i < cleaned.length; i += 2) bytes[i / 2] = Number.parseInt(cleaned.slice(i, i + 2), 16);
+	return bytesToBase64(bytes);
+}
+/**
+* Convert a Uint8Array to a hex string (lowercase, no prefix).
+*/
+function bytesToHex(bytes) {
+	return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Convert a hex string (with optional 0x prefix) to Uint8Array.
+*/
+function hexToBytes(hex) {
+	const cleaned = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+	if (cleaned.length % 2 !== 0) throw new Error(`Invalid hex string: odd length (${cleaned.length})`);
+	const bytes = new Uint8Array(cleaned.length / 2);
+	for (let i = 0; i < cleaned.length; i += 2) bytes[i / 2] = Number.parseInt(cleaned.slice(i, i + 2), 16);
+	return bytes;
+}
+const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function base64ToBytes(base64) {
+	if (typeof atob === "function") {
+		const binary = atob(base64);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	}
+	const cleaned = base64.replace(/=+$/, "");
+	const byteLength = cleaned.length * 3 >> 2;
+	const bytes = new Uint8Array(byteLength);
+	let byteIndex = 0;
+	for (let i = 0; i < cleaned.length; i += 4) {
+		const a = BASE64_CHARS.indexOf(cleaned.charAt(i));
+		const b = BASE64_CHARS.indexOf(cleaned.charAt(i + 1));
+		const c = BASE64_CHARS.indexOf(i + 2 < cleaned.length ? cleaned.charAt(i + 2) : "A");
+		const d = BASE64_CHARS.indexOf(i + 3 < cleaned.length ? cleaned.charAt(i + 3) : "A");
+		bytes[byteIndex++] = a << 2 | b >> 4;
+		if (i + 2 < cleaned.length) bytes[byteIndex++] = (b & 15) << 4 | c >> 2;
+		if (i + 3 < cleaned.length) bytes[byteIndex++] = (c & 3) << 6 | d;
+	}
+	return bytes;
+}
+function bytesToBase64(bytes) {
+	if (typeof btoa === "function") {
+		let binary = "";
+		for (const b of bytes) binary += String.fromCharCode(b);
+		return btoa(binary);
+	}
+	let result = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const a = bytes[i];
+		const b = bytes[i + 1] ?? 0;
+		const c = bytes[i + 2] ?? 0;
+		result += BASE64_CHARS[a >> 2 & 63];
+		result += BASE64_CHARS[(a & 3) << 4 | b >> 4 & 15];
+		result += i + 1 < bytes.length ? BASE64_CHARS[(b & 15) << 2 | c >> 6 & 3] : "=";
+		result += i + 2 < bytes.length ? BASE64_CHARS[c & 63] : "=";
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/hbar.ts
+/**
+* HBAR / tinybar conversion utilities.
+*
+* The Hedera mirror node returns balances in **tinybars** (as strings for int64 safety).
+* 1 HBAR = 100,000,000 tinybars.
+*
+* These helpers eliminate the most common source of confusion when working
+* with Hedera balances.
+*
+* @packageDocumentation
+*/
+/** 1 HBAR = 100,000,000 tinybars. */
+const TINYBARS_PER_HBAR = 100000000n;
+/**
+* Converts tinybars (string) to HBAR (string) with up to 8 decimal places.
+*
+* ```ts
+* tinybarToHbar('100000000')  // '1'
+* tinybarToHbar('150000000')  // '1.5'
+* tinybarToHbar('1')          // '0.00000001'
+* tinybarToHbar('-250000000') // '-2.5'
+* ```
+*/
+function tinybarToHbar(tinybars) {
+	const value = BigInt(tinybars);
+	const negative = value < 0n;
+	const abs = negative ? -value : value;
+	const whole = abs / TINYBARS_PER_HBAR;
+	const remainder = abs % TINYBARS_PER_HBAR;
+	if (remainder === 0n) return `${negative ? "-" : ""}${whole}`;
+	const fracStr = remainder.toString().padStart(8, "0").replace(/0+$/, "");
+	return `${negative ? "-" : ""}${whole}.${fracStr}`;
+}
+/**
+* Converts HBAR (string or number) to tinybars (string).
+*
+* Accepts up to 8 decimal places.
+*
+* ```ts
+* hbarToTinybar('1')      // '100000000'
+* hbarToTinybar('1.5')    // '150000000'
+* hbarToTinybar('0.00000001') // '1'
+* hbarToTinybar('-2.5')   // '-250000000'
+* ```
+*/
+function hbarToTinybar(hbar) {
+	const str = String(hbar);
+	const negative = str.startsWith("-");
+	const abs = negative ? str.slice(1) : str;
+	const dotIndex = abs.indexOf(".");
+	if (dotIndex === -1) {
+		const result = BigInt(abs) * TINYBARS_PER_HBAR;
+		return `${negative ? "-" : ""}${result}`;
+	}
+	const wholePart = abs.slice(0, dotIndex) || "0";
+	const fracPart = abs.slice(dotIndex + 1);
+	if (fracPart.length > 8) throw new RangeError(`HBAR value "${str}" exceeds maximum precision of 8 decimal places (tinybars)`);
+	const paddedFrac = fracPart.padEnd(8, "0");
+	const total = BigInt(wholePart) * TINYBARS_PER_HBAR + BigInt(paddedFrac);
+	return `${negative ? "-" : ""}${total}`;
+}
+/**
+* Formats a tinybar amount as a human-readable HBAR string with the symbol.
+*
+* ```ts
+* formatHbar('100000000')  // '1 HBAR'
+* formatHbar('150000000')  // '1.5 HBAR'
+* formatHbar('1')          // '0.00000001 HBAR'
+* formatHbar('-250000000') // '-2.5 HBAR'
+* ```
+*/
+function formatHbar(tinybars) {
+	return `${tinybarToHbar(tinybars)} HBAR`;
+}
+//#endregion
+Object.defineProperty(exports, "base64ToHex", {
+	enumerable: true,
+	get: function() {
+		return base64ToHex;
+	}
+});
+Object.defineProperty(exports, "bytesToHex", {
+	enumerable: true,
+	get: function() {
+		return bytesToHex;
+	}
+});
+Object.defineProperty(exports, "formatHbar", {
+	enumerable: true,
+	get: function() {
+		return formatHbar;
+	}
+});
+Object.defineProperty(exports, "hbarToTinybar", {
+	enumerable: true,
+	get: function() {
+		return hbarToTinybar;
+	}
+});
+Object.defineProperty(exports, "hexToBase64", {
+	enumerable: true,
+	get: function() {
+		return hexToBase64;
+	}
+});
+Object.defineProperty(exports, "hexToBytes", {
+	enumerable: true,
+	get: function() {
+		return hexToBytes;
+	}
+});
+Object.defineProperty(exports, "tinybarToHbar", {
+	enumerable: true,
+	get: function() {
+		return tinybarToHbar;
+	}
+});
+
+//# sourceMappingURL=hbar.cjs.map

package/dist/hbar.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hbar.cjs","names":[],"sources":["../src/utils/encoding.ts","../src/utils/hbar.ts"],"sourcesContent":["/**\n * Cross-platform encoding utilities.\n *\n * No dependency on Node.js `Buffer` — uses Web-standard APIs only.\n *\n * @packageDocumentation\n */\n\n/**\n * Base64-to-hex conversion.\n *\n * ```ts\n * base64ToHex('SGVsbG8=') // → '48656c6c6f'\n * ```\n */\nexport function base64ToHex(base64: string): string {\n  const bytes = base64ToBytes(base64);\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\n/**\n * Hex-to-base64 conversion.\n *\n * Accepts optional 0x prefix.\n *\n * ```ts\n * hexToBase64('48656c6c6f')   // → 'SGVsbG8='\n * hexToBase64('0x48656c6c6f') // → 'SGVsbG8='\n * ```\n */\nexport function hexToBase64(hex: string): string {\n  const cleaned = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;\n  if (cleaned.length % 2 !== 0) {\n    throw new Error(`Invalid hex string: odd length (${cleaned.length})`);\n  }\n  const bytes = new Uint8Array(cleaned.length / 2);\n  for (let i = 0; i < cleaned.length; i += 2) {\n    bytes[i / 2] = Number.parseInt(cleaned.slice(i, i + 2), 16);\n  }\n  return bytesToBase64(bytes);\n}\n\n/**\n * Convert a Uint8Array to a hex string (lowercase, no prefix).\n */\nexport function bytesToHex(bytes: Uint8Array): string {\n  return Array.from(bytes)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\n/**\n * Convert a hex string (with optional 0x prefix) to Uint8Array.\n */\nexport function hexToBytes(hex: string): Uint8Array {\n  const cleaned = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;\n  if (cleaned.length % 2 !== 0) {\n    throw new Error(`Invalid hex string: odd length (${cleaned.length})`);\n  }\n  const bytes = new Uint8Array(cleaned.length / 2);\n  for (let i = 0; i < cleaned.length; i += 2) {\n    bytes[i / 2] = Number.parseInt(cleaned.slice(i, i + 2), 16);\n  }\n  return bytes;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers (no Buffer, cross-platform)\n// ---------------------------------------------------------------------------\n\nconst BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';\n\nfunction base64ToBytes(base64: string): Uint8Array {\n  // Use atob if available (browser + Node 16+)\n  if (typeof atob === 'function') {\n    const binary = atob(base64);\n    const bytes = new Uint8Array(binary.length);\n    for (let i = 0; i < binary.length; i++) {\n      bytes[i] = binary.charCodeAt(i);\n    }\n    return bytes;\n  }\n\n  // Manual fallback (should rarely be needed)\n  const cleaned = base64.replace(/=+$/, '');\n  const byteLength = (cleaned.length * 3) >> 2;\n  const bytes = new Uint8Array(byteLength);\n  let byteIndex = 0;\n\n  for (let i = 0; i < cleaned.length; i += 4) {\n    const a = BASE64_CHARS.indexOf(cleaned.charAt(i));\n    const b = BASE64_CHARS.indexOf(cleaned.charAt(i + 1));\n    const c = BASE64_CHARS.indexOf(i + 2 < cleaned.length ? cleaned.charAt(i + 2) : 'A');\n    const d = BASE64_CHARS.indexOf(i + 3 < cleaned.length ? cleaned.charAt(i + 3) : 'A');\n\n    bytes[byteIndex++] = (a << 2) | (b >> 4);\n    if (i + 2 < cleaned.length) bytes[byteIndex++] = ((b & 15) << 4) | (c >> 2);\n    if (i + 3 < cleaned.length) bytes[byteIndex++] = ((c & 3) << 6) | d;\n  }\n\n  return bytes;\n}\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  // Use btoa if available (browser + Node 16+)\n  if (typeof btoa === 'function') {\n    let binary = '';\n    for (const b of bytes) {\n      binary += String.fromCharCode(b);\n    }\n    return btoa(binary);\n  }\n\n  // Manual fallback\n  let result = '';\n  for (let i = 0; i < bytes.length; i += 3) {\n    const a = bytes[i]!;\n    const b = bytes[i + 1] ?? 0;\n    const c = bytes[i + 2] ?? 0;\n\n    result += BASE64_CHARS[(a >> 2) & 63];\n    result += BASE64_CHARS[((a & 3) << 4) | ((b >> 4) & 15)];\n    result += i + 1 < bytes.length ? BASE64_CHARS[((b & 15) << 2) | ((c >> 6) & 3)] : '=';\n    result += i + 2 < bytes.length ? BASE64_CHARS[c & 63] : '=';\n  }\n\n  return result;\n}\n","/**\n * HBAR / tinybar conversion utilities.\n *\n * The Hedera mirror node returns balances in **tinybars** (as strings for int64 safety).\n * 1 HBAR = 100,000,000 tinybars.\n *\n * These helpers eliminate the most common source of confusion when working\n * with Hedera balances.\n *\n * @packageDocumentation\n */\n\n/** 1 HBAR = 100,000,000 tinybars. */\nconst TINYBARS_PER_HBAR = 100_000_000n;\n\n/**\n * Converts tinybars (string) to HBAR (string) with up to 8 decimal places.\n *\n * ```ts\n * tinybarToHbar('100000000')  // '1'\n * tinybarToHbar('150000000')  // '1.5'\n * tinybarToHbar('1')          // '0.00000001'\n * tinybarToHbar('-250000000') // '-2.5'\n * ```\n */\nexport function tinybarToHbar(tinybars: string): string {\n  const value = BigInt(tinybars);\n  const negative = value < 0n;\n  const abs = negative ? -value : value;\n\n  const whole = abs / TINYBARS_PER_HBAR;\n  const remainder = abs % TINYBARS_PER_HBAR;\n\n  if (remainder === 0n) {\n    return `${negative ? '-' : ''}${whole}`;\n  }\n\n  // Pad remainder to 8 digits then strip trailing zeros\n  const fracStr = remainder.toString().padStart(8, '0').replace(/0+$/, '');\n  return `${negative ? '-' : ''}${whole}.${fracStr}`;\n}\n\n/**\n * Converts HBAR (string or number) to tinybars (string).\n *\n * Accepts up to 8 decimal places.\n *\n * ```ts\n * hbarToTinybar('1')      // '100000000'\n * hbarToTinybar('1.5')    // '150000000'\n * hbarToTinybar('0.00000001') // '1'\n * hbarToTinybar('-2.5')   // '-250000000'\n * ```\n */\nexport function hbarToTinybar(hbar: string | number): string {\n  const str = String(hbar);\n  const negative = str.startsWith('-');\n  const abs = negative ? str.slice(1) : str;\n\n  const dotIndex = abs.indexOf('.');\n  if (dotIndex === -1) {\n    // Whole number\n    const result = BigInt(abs) * TINYBARS_PER_HBAR;\n    return `${negative ? '-' : ''}${result}`;\n  }\n\n  const wholePart = abs.slice(0, dotIndex) || '0';\n  const fracPart = abs.slice(dotIndex + 1);\n\n  if (fracPart.length > 8) {\n    throw new RangeError(\n      `HBAR value \"${str}\" exceeds maximum precision of 8 decimal places (tinybars)`,\n    );\n  }\n\n  // Pad fractional part to exactly 8 digits\n  const paddedFrac = fracPart.padEnd(8, '0');\n  const wholeTinybars = BigInt(wholePart) * TINYBARS_PER_HBAR;\n  const fracTinybars = BigInt(paddedFrac);\n  const total = wholeTinybars + fracTinybars;\n\n  return `${negative ? '-' : ''}${total}`;\n}\n\n/**\n * Formats a tinybar amount as a human-readable HBAR string with the symbol.\n *\n * ```ts\n * formatHbar('100000000')  // '1 HBAR'\n * formatHbar('150000000')  // '1.5 HBAR'\n * formatHbar('1')          // '0.00000001 HBAR'\n * formatHbar('-250000000') // '-2.5 HBAR'\n * ```\n */\nexport function formatHbar(tinybars: string): string {\n  return `${tinybarToHbar(tinybars)} HBAR`;\n}\n"],"mappings":"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"}

package/dist/hbar.d.cts

@@ -0,0 +1,50 @@
+//#region src/utils/hbar.d.ts
+/**
+ * HBAR / tinybar conversion utilities.
+ *
+ * The Hedera mirror node returns balances in **tinybars** (as strings for int64 safety).
+ * 1 HBAR = 100,000,000 tinybars.
+ *
+ * These helpers eliminate the most common source of confusion when working
+ * with Hedera balances.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Converts tinybars (string) to HBAR (string) with up to 8 decimal places.
+ *
+ * ```ts
+ * tinybarToHbar('100000000')  // '1'
+ * tinybarToHbar('150000000')  // '1.5'
+ * tinybarToHbar('1')          // '0.00000001'
+ * tinybarToHbar('-250000000') // '-2.5'
+ * ```
+ */
+declare function tinybarToHbar(tinybars: string): string;
+/**
+ * Converts HBAR (string or number) to tinybars (string).
+ *
+ * Accepts up to 8 decimal places.
+ *
+ * ```ts
+ * hbarToTinybar('1')      // '100000000'
+ * hbarToTinybar('1.5')    // '150000000'
+ * hbarToTinybar('0.00000001') // '1'
+ * hbarToTinybar('-2.5')   // '-250000000'
+ * ```
+ */
+declare function hbarToTinybar(hbar: string | number): string;
+/**
+ * Formats a tinybar amount as a human-readable HBAR string with the symbol.
+ *
+ * ```ts
+ * formatHbar('100000000')  // '1 HBAR'
+ * formatHbar('150000000')  // '1.5 HBAR'
+ * formatHbar('1')          // '0.00000001 HBAR'
+ * formatHbar('-250000000') // '-2.5 HBAR'
+ * ```
+ */
+declare function formatHbar(tinybars: string): string;
+//#endregion
+export { hbarToTinybar as n, tinybarToHbar as r, formatHbar as t };
+//# sourceMappingURL=hbar.d.cts.map

package/dist/hbar.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hbar.d.cts","names":[],"sources":["../src/utils/hbar.ts"],"mappings":";;AAyBA;;;;;AA6BA;;;;;AAwCA;;;;;;;;;;AAAA,iBArEgB,aAAA,CAAc,QAAA;;;;;;;;;;;;;iBA6Bd,aAAA,CAAc,IAAA;;;;;;;;;;;iBAwCd,UAAA,CAAW,QAAA"}

package/dist/hbar.d.mts

@@ -0,0 +1,50 @@
+//#region src/utils/hbar.d.ts
+/**
+ * HBAR / tinybar conversion utilities.
+ *
+ * The Hedera mirror node returns balances in **tinybars** (as strings for int64 safety).
+ * 1 HBAR = 100,000,000 tinybars.
+ *
+ * These helpers eliminate the most common source of confusion when working
+ * with Hedera balances.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Converts tinybars (string) to HBAR (string) with up to 8 decimal places.
+ *
+ * ```ts
+ * tinybarToHbar('100000000')  // '1'
+ * tinybarToHbar('150000000')  // '1.5'
+ * tinybarToHbar('1')          // '0.00000001'
+ * tinybarToHbar('-250000000') // '-2.5'
+ * ```
+ */
+declare function tinybarToHbar(tinybars: string): string;
+/**
+ * Converts HBAR (string or number) to tinybars (string).
+ *
+ * Accepts up to 8 decimal places.
+ *
+ * ```ts
+ * hbarToTinybar('1')      // '100000000'
+ * hbarToTinybar('1.5')    // '150000000'
+ * hbarToTinybar('0.00000001') // '1'
+ * hbarToTinybar('-2.5')   // '-250000000'
+ * ```
+ */
+declare function hbarToTinybar(hbar: string | number): string;
+/**
+ * Formats a tinybar amount as a human-readable HBAR string with the symbol.
+ *
+ * ```ts
+ * formatHbar('100000000')  // '1 HBAR'
+ * formatHbar('150000000')  // '1.5 HBAR'
+ * formatHbar('1')          // '0.00000001 HBAR'
+ * formatHbar('-250000000') // '-2.5 HBAR'
+ * ```
+ */
+declare function formatHbar(tinybars: string): string;
+//#endregion
+export { hbarToTinybar as n, tinybarToHbar as r, formatHbar as t };
+//# sourceMappingURL=hbar.d.mts.map

package/dist/hbar.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hbar.d.mts","names":[],"sources":["../src/utils/hbar.ts"],"mappings":";;AAyBA;;;;;AA6BA;;;;;AAwCA;;;;;;;;;;AAAA,iBArEgB,aAAA,CAAc,QAAA;;;;;;;;;;;;;iBA6Bd,aAAA,CAAc,IAAA;;;;;;;;;;;iBAwCd,UAAA,CAAW,QAAA"}

package/dist/hbar.mjs

@@ -0,0 +1,173 @@
+//#region src/utils/encoding.ts
+/**
+* Cross-platform encoding utilities.
+*
+* No dependency on Node.js `Buffer` — uses Web-standard APIs only.
+*
+* @packageDocumentation
+*/
+/**
+* Base64-to-hex conversion.
+*
+* ```ts
+* base64ToHex('SGVsbG8=') // → '48656c6c6f'
+* ```
+*/
+function base64ToHex(base64) {
+	const bytes = base64ToBytes(base64);
+	return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Hex-to-base64 conversion.
+*
+* Accepts optional 0x prefix.
+*
+* ```ts
+* hexToBase64('48656c6c6f')   // → 'SGVsbG8='
+* hexToBase64('0x48656c6c6f') // → 'SGVsbG8='
+* ```
+*/
+function hexToBase64(hex) {
+	const cleaned = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+	if (cleaned.length % 2 !== 0) throw new Error(`Invalid hex string: odd length (${cleaned.length})`);
+	const bytes = new Uint8Array(cleaned.length / 2);
+	for (let i = 0; i < cleaned.length; i += 2) bytes[i / 2] = Number.parseInt(cleaned.slice(i, i + 2), 16);
+	return bytesToBase64(bytes);
+}
+/**
+* Convert a Uint8Array to a hex string (lowercase, no prefix).
+*/
+function bytesToHex(bytes) {
+	return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Convert a hex string (with optional 0x prefix) to Uint8Array.
+*/
+function hexToBytes(hex) {
+	const cleaned = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+	if (cleaned.length % 2 !== 0) throw new Error(`Invalid hex string: odd length (${cleaned.length})`);
+	const bytes = new Uint8Array(cleaned.length / 2);
+	for (let i = 0; i < cleaned.length; i += 2) bytes[i / 2] = Number.parseInt(cleaned.slice(i, i + 2), 16);
+	return bytes;
+}
+const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function base64ToBytes(base64) {
+	if (typeof atob === "function") {
+		const binary = atob(base64);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	}
+	const cleaned = base64.replace(/=+$/, "");
+	const byteLength = cleaned.length * 3 >> 2;
+	const bytes = new Uint8Array(byteLength);
+	let byteIndex = 0;
+	for (let i = 0; i < cleaned.length; i += 4) {
+		const a = BASE64_CHARS.indexOf(cleaned.charAt(i));
+		const b = BASE64_CHARS.indexOf(cleaned.charAt(i + 1));
+		const c = BASE64_CHARS.indexOf(i + 2 < cleaned.length ? cleaned.charAt(i + 2) : "A");
+		const d = BASE64_CHARS.indexOf(i + 3 < cleaned.length ? cleaned.charAt(i + 3) : "A");
+		bytes[byteIndex++] = a << 2 | b >> 4;
+		if (i + 2 < cleaned.length) bytes[byteIndex++] = (b & 15) << 4 | c >> 2;
+		if (i + 3 < cleaned.length) bytes[byteIndex++] = (c & 3) << 6 | d;
+	}
+	return bytes;
+}
+function bytesToBase64(bytes) {
+	if (typeof btoa === "function") {
+		let binary = "";
+		for (const b of bytes) binary += String.fromCharCode(b);
+		return btoa(binary);
+	}
+	let result = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const a = bytes[i];
+		const b = bytes[i + 1] ?? 0;
+		const c = bytes[i + 2] ?? 0;
+		result += BASE64_CHARS[a >> 2 & 63];
+		result += BASE64_CHARS[(a & 3) << 4 | b >> 4 & 15];
+		result += i + 1 < bytes.length ? BASE64_CHARS[(b & 15) << 2 | c >> 6 & 3] : "=";
+		result += i + 2 < bytes.length ? BASE64_CHARS[c & 63] : "=";
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/hbar.ts
+/**
+* HBAR / tinybar conversion utilities.
+*
+* The Hedera mirror node returns balances in **tinybars** (as strings for int64 safety).
+* 1 HBAR = 100,000,000 tinybars.
+*
+* These helpers eliminate the most common source of confusion when working
+* with Hedera balances.
+*
+* @packageDocumentation
+*/
+/** 1 HBAR = 100,000,000 tinybars. */
+const TINYBARS_PER_HBAR = 100000000n;
+/**
+* Converts tinybars (string) to HBAR (string) with up to 8 decimal places.
+*
+* ```ts
+* tinybarToHbar('100000000')  // '1'
+* tinybarToHbar('150000000')  // '1.5'
+* tinybarToHbar('1')          // '0.00000001'
+* tinybarToHbar('-250000000') // '-2.5'
+* ```
+*/
+function tinybarToHbar(tinybars) {
+	const value = BigInt(tinybars);
+	const negative = value < 0n;
+	const abs = negative ? -value : value;
+	const whole = abs / TINYBARS_PER_HBAR;
+	const remainder = abs % TINYBARS_PER_HBAR;
+	if (remainder === 0n) return `${negative ? "-" : ""}${whole}`;
+	const fracStr = remainder.toString().padStart(8, "0").replace(/0+$/, "");
+	return `${negative ? "-" : ""}${whole}.${fracStr}`;
+}
+/**
+* Converts HBAR (string or number) to tinybars (string).
+*
+* Accepts up to 8 decimal places.
+*
+* ```ts
+* hbarToTinybar('1')      // '100000000'
+* hbarToTinybar('1.5')    // '150000000'
+* hbarToTinybar('0.00000001') // '1'
+* hbarToTinybar('-2.5')   // '-250000000'
+* ```
+*/
+function hbarToTinybar(hbar) {
+	const str = String(hbar);
+	const negative = str.startsWith("-");
+	const abs = negative ? str.slice(1) : str;
+	const dotIndex = abs.indexOf(".");
+	if (dotIndex === -1) {
+		const result = BigInt(abs) * TINYBARS_PER_HBAR;
+		return `${negative ? "-" : ""}${result}`;
+	}
+	const wholePart = abs.slice(0, dotIndex) || "0";
+	const fracPart = abs.slice(dotIndex + 1);
+	if (fracPart.length > 8) throw new RangeError(`HBAR value "${str}" exceeds maximum precision of 8 decimal places (tinybars)`);
+	const paddedFrac = fracPart.padEnd(8, "0");
+	const total = BigInt(wholePart) * TINYBARS_PER_HBAR + BigInt(paddedFrac);
+	return `${negative ? "-" : ""}${total}`;
+}
+/**
+* Formats a tinybar amount as a human-readable HBAR string with the symbol.
+*
+* ```ts
+* formatHbar('100000000')  // '1 HBAR'
+* formatHbar('150000000')  // '1.5 HBAR'
+* formatHbar('1')          // '0.00000001 HBAR'
+* formatHbar('-250000000') // '-2.5 HBAR'
+* ```
+*/
+function formatHbar(tinybars) {
+	return `${tinybarToHbar(tinybars)} HBAR`;
+}
+//#endregion
+export { bytesToHex as a, base64ToHex as i, hbarToTinybar as n, hexToBase64 as o, tinybarToHbar as r, hexToBytes as s, formatHbar as t };
+
+//# sourceMappingURL=hbar.mjs.map