@satianurag/hiero-mirror-client 0.2.2 → 0.4.0

package/LICENSE

@@ -1,21 +1,190 @@
-MIT License
-
-Copyright (c) 2026 satianurag
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 satianurag
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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,31 +129,125 @@ 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'
 
 // Timestamp handling with full nanosecond precision
+// Returns a ParsedTimestamp: { seconds: bigint, nanos: number, toString() }
 const ts = fromString('1710000000.123456789');
 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,7 +258,16 @@ import type {
   TokenSummary,
   Transaction,
   NetworkStake,
+  // Helper types
+  WaitForExecutionOptions,
+  ExecutionResult,
+  SignatureProgress,
+  WaitForTransactionOptions,
+  ToolDescriptor,
 } from '@satianurag/hiero-mirror-client';
+
+// Utility types from the /utils subpath
+import type { ParsedTimestamp } from '@satianurag/hiero-mirror-client/utils';
 ```
 
 ## Int64 Safety
@@ -175,4 +282,4 @@ This project uses the [Developer Certificate of Origin (DCO)](https://developerc
 
 ## License
 
-MIT — see [LICENSE](LICENSE) for details.
+Apache-2.0 — see [LICENSE](LICENSE) for details.

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