@hbar-kit/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr Ostrovskyi
+
+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.

package/README.md

@@ -0,0 +1,17 @@
+# @hbar-kit/core
+
+Zero-dependency primitives for [hbar-kit](https://github.com/devwhodevs/hbar-kit): network config,
+decimal-safe bigint money, account/token/transaction id helpers, nanosecond timestamps, and a
+typed error hierarchy.
+
+```ts
+import { parseHbar, formatHbar, resolveNetwork, txIdToMirror } from "@hbar-kit/core"
+
+parseHbar("25") // 2_500_000_000n  (tinybars)
+formatHbar(99_306n) // "0.00099306"
+resolveNetwork({ network: "testnet" }).baseUrl
+// "https://testnet.mirrornode.hedera.com"
+txIdToMirror("0.0.10@1748625594.1") // "0.0.10-1748625594-000000001"
+```
+
+All amounts are `bigint` in the smallest unit. See the [docs](https://github.com/devwhodevs/hbar-kit).

package/dist/index.cjs

@@ -0,0 +1,245 @@
+'use strict';
+
+// src/errors.ts
+var HbarKitError = class extends Error {
+  shortMessage;
+  details;
+  docsPath;
+  constructor(message, opts = {}) {
+    super(message, opts.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "HbarKitError";
+    this.shortMessage = message;
+    this.details = opts.details;
+    this.docsPath = opts.docsPath;
+  }
+  /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */
+  walk(fn) {
+    return walkCauseChain(this, fn);
+  }
+};
+function walkCauseChain(start, fn) {
+  let current = start;
+  while (current) {
+    if (fn?.(current)) return current;
+    const next = current.cause;
+    if (!next) return fn ? null : current;
+    current = next;
+  }
+  return null;
+}
+var MirrorHttpError = class extends HbarKitError {
+  status;
+  constructor(message, status, opts) {
+    super(message, opts);
+    this.name = "MirrorHttpError";
+    this.status = status;
+  }
+};
+var RateLimitError = class extends MirrorHttpError {
+  retryAfter;
+  constructor(message, opts) {
+    super(message, 429, opts);
+    this.name = "RateLimitError";
+    this.retryAfter = opts?.retryAfter;
+  }
+};
+var NotFoundError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "NotFoundError";
+  }
+};
+var TimeoutError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "TimeoutError";
+  }
+};
+var NetworkError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "NetworkError";
+  }
+};
+var InvalidAmountError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "InvalidAmountError";
+  }
+};
+var InvalidParamsError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "InvalidParamsError";
+  }
+};
+var PaymentVerificationError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "PaymentVerificationError";
+  }
+};
+
+// src/network.ts
+var NETWORKS = {
+  mainnet: {
+    network: "mainnet",
+    baseUrl: "https://mainnet-public.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/mainnet",
+    currency: { symbol: "HBAR", decimals: 8 }
+  },
+  testnet: {
+    network: "testnet",
+    baseUrl: "https://testnet.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/testnet",
+    currency: { symbol: "HBAR", decimals: 8 }
+  },
+  previewnet: {
+    network: "previewnet",
+    baseUrl: "https://previewnet.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/previewnet",
+    currency: { symbol: "HBAR", decimals: 8 }
+  }
+};
+function resolveNetwork(input) {
+  if (!input.network && !input.baseUrl) {
+    throw new InvalidParamsError("`network` (or `baseUrl`) is required \u2014 there is no default");
+  }
+  const network = input.network ?? "mainnet";
+  const preset = NETWORKS[network];
+  const baseUrl = input.baseUrl ? input.baseUrl.replace(/\/+$/, "") : preset.baseUrl;
+  return { ...preset, baseUrl };
+}
+
+// src/units.ts
+var AMOUNT_RE = /^(-?)(\d*)(?:\.(\d*))?$/;
+function parseUnits(value, decimals) {
+  const m = AMOUNT_RE.exec(value);
+  if (!m || value === "" || value === "-" || value === ".") {
+    throw new InvalidAmountError(`Invalid amount: "${value}"`);
+  }
+  const [, sign, whole = "", frac = ""] = m;
+  if (frac.length > decimals) {
+    throw new InvalidAmountError(
+      `Amount "${value}" has more precision than ${decimals} decimals allow`
+    );
+  }
+  const digits = `${whole}${frac.padEnd(decimals, "0")}` || "0";
+  const base = BigInt(digits === "" ? "0" : digits);
+  return sign === "-" ? -base : base;
+}
+function formatUnits(value, decimals) {
+  const neg = value < 0n;
+  const abs = neg ? -value : value;
+  const s = abs.toString().padStart(decimals + 1, "0");
+  const whole = s.slice(0, s.length - decimals);
+  const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "");
+  const out = frac ? `${whole}.${frac}` : whole;
+  return neg && out !== "0" ? `-${out}` : out;
+}
+var HBAR_DECIMALS = 8;
+var parseHbar = (value) => parseUnits(value, HBAR_DECIMALS);
+var formatHbar = (value) => formatUnits(value, HBAR_DECIMALS);
+
+// src/ids.ts
+var ENTITY_RE = /^\d+\.\d+\.\d+$/;
+function isEntityId(value) {
+  return ENTITY_RE.test(value);
+}
+function assertEntityId(value) {
+  if (!isEntityId(value)) throw new InvalidParamsError(`Invalid account/entity id: "${value}"`);
+  return value;
+}
+var padNanos = (nanos) => nanos.padStart(9, "0").slice(0, 9);
+var SDK_TX_RE = /^(\d+\.\d+\.\d+)@(\d+)\.(\d+)$/;
+var MIRROR_TX_RE = /^(\d+\.\d+\.\d+)-(\d+)-(\d+)$/;
+function txIdToMirror(id) {
+  if (MIRROR_TX_RE.test(id)) return id;
+  const m = SDK_TX_RE.exec(id);
+  if (!m) throw new InvalidParamsError(`Invalid transaction id: "${id}"`);
+  const [, account, seconds, nanos] = m;
+  return `${account}-${seconds}-${padNanos(nanos)}`;
+}
+function txIdToSdk(id) {
+  if (SDK_TX_RE.test(id)) return id;
+  const m = MIRROR_TX_RE.exec(id);
+  if (!m) throw new InvalidParamsError(`Invalid transaction id: "${id}"`);
+  const [, account, seconds, nanos] = m;
+  return `${account}@${seconds}.${padNanos(nanos)}`;
+}
+
+// src/timestamp.ts
+var TS_RE = /^(\d{1,15})(?:\.(\d{1,9}))?$/;
+function parseTimestamp(raw) {
+  const m = TS_RE.exec(raw);
+  if (!m) throw new InvalidParamsError(`Invalid timestamp: "${raw}"`);
+  const seconds = Number(m[1]);
+  const nanosStr = (m[2] ?? "").padEnd(9, "0");
+  const nanos = Number(nanosStr);
+  return {
+    raw,
+    seconds,
+    nanos,
+    toNanos: () => BigInt(m[1]) * 1000000000n + BigInt(nanosStr || "0"),
+    toDate: () => new Date(seconds * 1e3 + Math.floor(nanos / 1e6))
+  };
+}
+function dateToTimestamp(date) {
+  const ms = date.getTime();
+  const seconds = Math.floor(ms / 1e3);
+  const millis = ms - seconds * 1e3;
+  return `${seconds}.${String(millis).padStart(3, "0")}000000`;
+}
+function tsFilter(op, value) {
+  const v = value instanceof Date ? dateToTimestamp(value) : value;
+  return `${op}:${v}`;
+}
+
+// src/query.ts
+function hashFn(key) {
+  return JSON.stringify(key, (_k, value) => {
+    if (typeof value === "bigint") return `${value}#bigint`;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce((acc, k) => {
+        acc[k] = value[k];
+        return acc;
+      }, {});
+    }
+    return value;
+  });
+}
+function makeQueryKey(resource, options) {
+  const filtered = {};
+  for (const [k, v] of Object.entries(options)) {
+    if (v !== void 0) filtered[k] = v;
+  }
+  return [resource, filtered];
+}
+
+exports.HBAR_DECIMALS = HBAR_DECIMALS;
+exports.HbarKitError = HbarKitError;
+exports.InvalidAmountError = InvalidAmountError;
+exports.InvalidParamsError = InvalidParamsError;
+exports.MirrorHttpError = MirrorHttpError;
+exports.NETWORKS = NETWORKS;
+exports.NetworkError = NetworkError;
+exports.NotFoundError = NotFoundError;
+exports.PaymentVerificationError = PaymentVerificationError;
+exports.RateLimitError = RateLimitError;
+exports.TimeoutError = TimeoutError;
+exports.assertEntityId = assertEntityId;
+exports.dateToTimestamp = dateToTimestamp;
+exports.formatHbar = formatHbar;
+exports.formatUnits = formatUnits;
+exports.hashFn = hashFn;
+exports.isEntityId = isEntityId;
+exports.makeQueryKey = makeQueryKey;
+exports.parseHbar = parseHbar;
+exports.parseTimestamp = parseTimestamp;
+exports.parseUnits = parseUnits;
+exports.resolveNetwork = resolveNetwork;
+exports.tsFilter = tsFilter;
+exports.txIdToMirror = txIdToMirror;
+exports.txIdToSdk = txIdToSdk;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/network.ts","../src/units.ts","../src/ids.ts","../src/timestamp.ts","../src/query.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["export interface HbarKitErrorOptions {\n  cause?: unknown\n  details?: string\n  docsPath?: string\n}\n\nexport class HbarKitError extends Error {\n  readonly shortMessage: string\n  readonly details: string | undefined\n  readonly docsPath: string | undefined\n  constructor(message: string, opts: HbarKitErrorOptions = {}) {\n    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined)\n    this.name = \"HbarKitError\"\n    this.shortMessage = message\n    this.details = opts.details\n    this.docsPath = opts.docsPath\n  }\n  /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */\n  walk(fn?: (err: unknown) => boolean): unknown {\n    return walkCauseChain(this, fn)\n  }\n}\n\n/** Walk an error's cause chain; returns the first match for fn, or the deepest cause. */\nfunction walkCauseChain(start: unknown, fn?: (err: unknown) => boolean): unknown {\n  let current: unknown = start\n  while (current) {\n    if (fn?.(current)) return current\n    const next: unknown = (current as { cause?: unknown }).cause\n    if (!next) return fn ? null : current\n    current = next\n  }\n  return null\n}\n\nexport class MirrorHttpError extends HbarKitError {\n  readonly status: number\n  constructor(message: string, status: number, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"MirrorHttpError\"\n    this.status = status\n  }\n}\nexport class RateLimitError extends MirrorHttpError {\n  readonly retryAfter: number | undefined\n  constructor(message: string, opts?: HbarKitErrorOptions & { retryAfter?: number }) {\n    super(message, 429, opts)\n    this.name = \"RateLimitError\"\n    this.retryAfter = opts?.retryAfter\n  }\n}\nexport class NotFoundError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"NotFoundError\"\n  }\n}\nexport class TimeoutError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"TimeoutError\"\n  }\n}\nexport class NetworkError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"NetworkError\"\n  }\n}\nexport class InvalidAmountError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"InvalidAmountError\"\n  }\n}\nexport class InvalidParamsError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"InvalidParamsError\"\n  }\n}\nexport class PaymentVerificationError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"PaymentVerificationError\"\n  }\n}\n","import { InvalidParamsError } from \"./errors.js\"\n\nexport type HederaNetwork = \"mainnet\" | \"testnet\" | \"previewnet\"\n\nexport interface NetworkConfig {\n  network: HederaNetwork\n  baseUrl: string\n  hashscan: string\n  currency: { symbol: \"HBAR\"; decimals: 8 }\n}\n\nexport const NETWORKS: Record<HederaNetwork, NetworkConfig> = {\n  mainnet: {\n    network: \"mainnet\",\n    baseUrl: \"https://mainnet-public.mirrornode.hedera.com\",\n    hashscan: \"https://hashscan.io/mainnet\",\n    currency: { symbol: \"HBAR\", decimals: 8 },\n  },\n  testnet: {\n    network: \"testnet\",\n    baseUrl: \"https://testnet.mirrornode.hedera.com\",\n    hashscan: \"https://hashscan.io/testnet\",\n    currency: { symbol: \"HBAR\", decimals: 8 },\n  },\n  previewnet: {\n    network: \"previewnet\",\n    baseUrl: \"https://previewnet.mirrornode.hedera.com\",\n    hashscan: \"https://hashscan.io/previewnet\",\n    currency: { symbol: \"HBAR\", decimals: 8 },\n  },\n}\n\nexport interface NetworkInput {\n  network?: HederaNetwork\n  baseUrl?: string\n}\n\n/** Resolve a network input to a full config. Requires `network` or `baseUrl`. */\nexport function resolveNetwork(input: NetworkInput): NetworkConfig {\n  if (!input.network && !input.baseUrl) {\n    throw new InvalidParamsError(\"`network` (or `baseUrl`) is required — there is no default\")\n  }\n  const network: HederaNetwork = input.network ?? \"mainnet\"\n  const preset = NETWORKS[network]\n  const baseUrl = input.baseUrl ? input.baseUrl.replace(/\\/+$/, \"\") : preset.baseUrl\n  return { ...preset, baseUrl }\n}\n","import { InvalidAmountError } from \"./errors.js\"\n\nconst AMOUNT_RE = /^(-?)(\\d*)(?:\\.(\\d*))?$/\n\n/** Parse a decimal string into a bigint in the smallest unit. Strict: rejects excess precision. */\nexport function parseUnits(value: string, decimals: number): bigint {\n  const m = AMOUNT_RE.exec(value)\n  if (!m || value === \"\" || value === \"-\" || value === \".\") {\n    throw new InvalidAmountError(`Invalid amount: \"${value}\"`)\n  }\n  const [, sign, whole = \"\", frac = \"\"] = m\n  if (frac.length > decimals) {\n    throw new InvalidAmountError(\n      `Amount \"${value}\" has more precision than ${decimals} decimals allow`,\n    )\n  }\n  const digits = `${whole}${frac.padEnd(decimals, \"0\")}` || \"0\"\n  const base = BigInt(digits === \"\" ? \"0\" : digits)\n  return sign === \"-\" ? -base : base\n}\n\n/** Format a bigint smallest-unit value into a trimmed decimal string. */\nexport function formatUnits(value: bigint, decimals: number): string {\n  const neg = value < 0n\n  const abs = neg ? -value : value\n  const s = abs.toString().padStart(decimals + 1, \"0\")\n  const whole = s.slice(0, s.length - decimals)\n  const frac = decimals === 0 ? \"\" : s.slice(s.length - decimals).replace(/0+$/, \"\")\n  const out = frac ? `${whole}.${frac}` : whole\n  return neg && out !== \"0\" ? `-${out}` : out\n}\n\nexport const HBAR_DECIMALS = 8\nexport const parseHbar = (value: string): bigint => parseUnits(value, HBAR_DECIMALS)\nexport const formatHbar = (value: bigint): string => formatUnits(value, HBAR_DECIMALS)\n","import { InvalidParamsError } from \"./errors.js\"\n\nconst ENTITY_RE = /^\\d+\\.\\d+\\.\\d+$/\n\nexport function isEntityId(value: string): boolean {\n  return ENTITY_RE.test(value)\n}\nexport function assertEntityId(value: string): string {\n  if (!isEntityId(value)) throw new InvalidParamsError(`Invalid account/entity id: \"${value}\"`)\n  return value\n}\n\nconst padNanos = (nanos: string): string => nanos.padStart(9, \"0\").slice(0, 9)\n\n// SDK form:  0.0.payer@seconds.nanos     Mirror form: 0.0.payer-seconds-nanos\nconst SDK_TX_RE = /^(\\d+\\.\\d+\\.\\d+)@(\\d+)\\.(\\d+)$/\nconst MIRROR_TX_RE = /^(\\d+\\.\\d+\\.\\d+)-(\\d+)-(\\d+)$/\n\nexport function txIdToMirror(id: string): string {\n  if (MIRROR_TX_RE.test(id)) return id\n  const m = SDK_TX_RE.exec(id)\n  if (!m) throw new InvalidParamsError(`Invalid transaction id: \"${id}\"`)\n  const [, account, seconds, nanos] = m\n  return `${account}-${seconds}-${padNanos(nanos!)}`\n}\nexport function txIdToSdk(id: string): string {\n  if (SDK_TX_RE.test(id)) return id\n  const m = MIRROR_TX_RE.exec(id)\n  if (!m) throw new InvalidParamsError(`Invalid transaction id: \"${id}\"`)\n  const [, account, seconds, nanos] = m\n  return `${account}@${seconds}.${padNanos(nanos!)}`\n}\n","import { InvalidParamsError } from \"./errors.js\"\n\nexport interface HederaTimestamp {\n  readonly raw: string\n  readonly seconds: number\n  readonly nanos: number\n  toNanos(): bigint\n  toDate(): Date\n}\n\nconst TS_RE = /^(\\d{1,15})(?:\\.(\\d{1,9}))?$/\n\nexport function parseTimestamp(raw: string): HederaTimestamp {\n  const m = TS_RE.exec(raw)\n  if (!m) throw new InvalidParamsError(`Invalid timestamp: \"${raw}\"`)\n  const seconds = Number(m[1])\n  const nanosStr = (m[2] ?? \"\").padEnd(9, \"0\")\n  const nanos = Number(nanosStr)\n  return {\n    raw,\n    seconds,\n    nanos,\n    toNanos: () => BigInt(m![1]!) * 1_000_000_000n + BigInt(nanosStr || \"0\"),\n    toDate: () => new Date(seconds * 1000 + Math.floor(nanos / 1_000_000)),\n  }\n}\n\nexport function dateToTimestamp(date: Date): string {\n  const ms = date.getTime()\n  const seconds = Math.floor(ms / 1000)\n  const millis = ms - seconds * 1000\n  return `${seconds}.${String(millis).padStart(3, \"0\")}000000`\n}\n\nexport type TsOp = \"eq\" | \"ne\" | \"gt\" | \"gte\" | \"lt\" | \"lte\"\n\nexport function tsFilter(op: TsOp, value: string | Date): string {\n  const v = value instanceof Date ? dateToTimestamp(value) : value\n  return `${op}:${v}`\n}\n","/** Deterministic, bigint-safe hash for TanStack Query keys (used from Phase 3). */\nexport function hashFn(key: unknown): string {\n  return JSON.stringify(key, (_k, value) => {\n    if (typeof value === \"bigint\") return `${value}#bigint`\n    if (value && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce<Record<string, unknown>>((acc, k) => {\n          acc[k] = (value as Record<string, unknown>)[k]\n          return acc\n        }, {})\n    }\n    return value\n  })\n}\n\n/** Build a const-style [resource, options] query key, dropping undefined entries. */\nexport function makeQueryKey<T extends Record<string, unknown>>(\n  resource: string,\n  options: T,\n): readonly [string, Partial<T>] {\n  const filtered: Partial<T> = {}\n  for (const [k, v] of Object.entries(options)) {\n    if (v !== undefined) filtered[k as keyof T] = v as T[keyof T]\n  }\n  return [resource, filtered] as const\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,91 @@
+interface HbarKitErrorOptions {
+    cause?: unknown;
+    details?: string;
+    docsPath?: string;
+}
+declare class HbarKitError extends Error {
+    readonly shortMessage: string;
+    readonly details: string | undefined;
+    readonly docsPath: string | undefined;
+    constructor(message: string, opts?: HbarKitErrorOptions);
+    /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */
+    walk(fn?: (err: unknown) => boolean): unknown;
+}
+declare class MirrorHttpError extends HbarKitError {
+    readonly status: number;
+    constructor(message: string, status: number, opts?: HbarKitErrorOptions);
+}
+declare class RateLimitError extends MirrorHttpError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, opts?: HbarKitErrorOptions & {
+        retryAfter?: number;
+    });
+}
+declare class NotFoundError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class TimeoutError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class NetworkError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class InvalidAmountError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class InvalidParamsError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class PaymentVerificationError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+
+type HederaNetwork = "mainnet" | "testnet" | "previewnet";
+interface NetworkConfig {
+    network: HederaNetwork;
+    baseUrl: string;
+    hashscan: string;
+    currency: {
+        symbol: "HBAR";
+        decimals: 8;
+    };
+}
+declare const NETWORKS: Record<HederaNetwork, NetworkConfig>;
+interface NetworkInput {
+    network?: HederaNetwork;
+    baseUrl?: string;
+}
+/** Resolve a network input to a full config. Requires `network` or `baseUrl`. */
+declare function resolveNetwork(input: NetworkInput): NetworkConfig;
+
+/** Parse a decimal string into a bigint in the smallest unit. Strict: rejects excess precision. */
+declare function parseUnits(value: string, decimals: number): bigint;
+/** Format a bigint smallest-unit value into a trimmed decimal string. */
+declare function formatUnits(value: bigint, decimals: number): string;
+declare const HBAR_DECIMALS = 8;
+declare const parseHbar: (value: string) => bigint;
+declare const formatHbar: (value: bigint) => string;
+
+declare function isEntityId(value: string): boolean;
+declare function assertEntityId(value: string): string;
+declare function txIdToMirror(id: string): string;
+declare function txIdToSdk(id: string): string;
+
+interface HederaTimestamp {
+    readonly raw: string;
+    readonly seconds: number;
+    readonly nanos: number;
+    toNanos(): bigint;
+    toDate(): Date;
+}
+declare function parseTimestamp(raw: string): HederaTimestamp;
+declare function dateToTimestamp(date: Date): string;
+type TsOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+declare function tsFilter(op: TsOp, value: string | Date): string;
+
+/** Deterministic, bigint-safe hash for TanStack Query keys (used from Phase 3). */
+declare function hashFn(key: unknown): string;
+/** Build a const-style [resource, options] query key, dropping undefined entries. */
+declare function makeQueryKey<T extends Record<string, unknown>>(resource: string, options: T): readonly [string, Partial<T>];
+
+export { HBAR_DECIMALS, HbarKitError, type HbarKitErrorOptions, type HederaNetwork, type HederaTimestamp, InvalidAmountError, InvalidParamsError, MirrorHttpError, NETWORKS, type NetworkConfig, NetworkError, type NetworkInput, NotFoundError, PaymentVerificationError, RateLimitError, TimeoutError, type TsOp, assertEntityId, dateToTimestamp, formatHbar, formatUnits, hashFn, isEntityId, makeQueryKey, parseHbar, parseTimestamp, parseUnits, resolveNetwork, tsFilter, txIdToMirror, txIdToSdk };

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+interface HbarKitErrorOptions {
+    cause?: unknown;
+    details?: string;
+    docsPath?: string;
+}
+declare class HbarKitError extends Error {
+    readonly shortMessage: string;
+    readonly details: string | undefined;
+    readonly docsPath: string | undefined;
+    constructor(message: string, opts?: HbarKitErrorOptions);
+    /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */
+    walk(fn?: (err: unknown) => boolean): unknown;
+}
+declare class MirrorHttpError extends HbarKitError {
+    readonly status: number;
+    constructor(message: string, status: number, opts?: HbarKitErrorOptions);
+}
+declare class RateLimitError extends MirrorHttpError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, opts?: HbarKitErrorOptions & {
+        retryAfter?: number;
+    });
+}
+declare class NotFoundError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class TimeoutError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class NetworkError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class InvalidAmountError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class InvalidParamsError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+declare class PaymentVerificationError extends HbarKitError {
+    constructor(message: string, opts?: HbarKitErrorOptions);
+}
+
+type HederaNetwork = "mainnet" | "testnet" | "previewnet";
+interface NetworkConfig {
+    network: HederaNetwork;
+    baseUrl: string;
+    hashscan: string;
+    currency: {
+        symbol: "HBAR";
+        decimals: 8;
+    };
+}
+declare const NETWORKS: Record<HederaNetwork, NetworkConfig>;
+interface NetworkInput {
+    network?: HederaNetwork;
+    baseUrl?: string;
+}
+/** Resolve a network input to a full config. Requires `network` or `baseUrl`. */
+declare function resolveNetwork(input: NetworkInput): NetworkConfig;
+
+/** Parse a decimal string into a bigint in the smallest unit. Strict: rejects excess precision. */
+declare function parseUnits(value: string, decimals: number): bigint;
+/** Format a bigint smallest-unit value into a trimmed decimal string. */
+declare function formatUnits(value: bigint, decimals: number): string;
+declare const HBAR_DECIMALS = 8;
+declare const parseHbar: (value: string) => bigint;
+declare const formatHbar: (value: bigint) => string;
+
+declare function isEntityId(value: string): boolean;
+declare function assertEntityId(value: string): string;
+declare function txIdToMirror(id: string): string;
+declare function txIdToSdk(id: string): string;
+
+interface HederaTimestamp {
+    readonly raw: string;
+    readonly seconds: number;
+    readonly nanos: number;
+    toNanos(): bigint;
+    toDate(): Date;
+}
+declare function parseTimestamp(raw: string): HederaTimestamp;
+declare function dateToTimestamp(date: Date): string;
+type TsOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+declare function tsFilter(op: TsOp, value: string | Date): string;
+
+/** Deterministic, bigint-safe hash for TanStack Query keys (used from Phase 3). */
+declare function hashFn(key: unknown): string;
+/** Build a const-style [resource, options] query key, dropping undefined entries. */
+declare function makeQueryKey<T extends Record<string, unknown>>(resource: string, options: T): readonly [string, Partial<T>];
+
+export { HBAR_DECIMALS, HbarKitError, type HbarKitErrorOptions, type HederaNetwork, type HederaTimestamp, InvalidAmountError, InvalidParamsError, MirrorHttpError, NETWORKS, type NetworkConfig, NetworkError, type NetworkInput, NotFoundError, PaymentVerificationError, RateLimitError, TimeoutError, type TsOp, assertEntityId, dateToTimestamp, formatHbar, formatUnits, hashFn, isEntityId, makeQueryKey, parseHbar, parseTimestamp, parseUnits, resolveNetwork, tsFilter, txIdToMirror, txIdToSdk };

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/errors.ts
+var HbarKitError = class extends Error {
+  shortMessage;
+  details;
+  docsPath;
+  constructor(message, opts = {}) {
+    super(message, opts.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "HbarKitError";
+    this.shortMessage = message;
+    this.details = opts.details;
+    this.docsPath = opts.docsPath;
+  }
+  /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */
+  walk(fn) {
+    return walkCauseChain(this, fn);
+  }
+};
+function walkCauseChain(start, fn) {
+  let current = start;
+  while (current) {
+    if (fn?.(current)) return current;
+    const next = current.cause;
+    if (!next) return fn ? null : current;
+    current = next;
+  }
+  return null;
+}
+var MirrorHttpError = class extends HbarKitError {
+  status;
+  constructor(message, status, opts) {
+    super(message, opts);
+    this.name = "MirrorHttpError";
+    this.status = status;
+  }
+};
+var RateLimitError = class extends MirrorHttpError {
+  retryAfter;
+  constructor(message, opts) {
+    super(message, 429, opts);
+    this.name = "RateLimitError";
+    this.retryAfter = opts?.retryAfter;
+  }
+};
+var NotFoundError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "NotFoundError";
+  }
+};
+var TimeoutError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "TimeoutError";
+  }
+};
+var NetworkError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "NetworkError";
+  }
+};
+var InvalidAmountError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "InvalidAmountError";
+  }
+};
+var InvalidParamsError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "InvalidParamsError";
+  }
+};
+var PaymentVerificationError = class extends HbarKitError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "PaymentVerificationError";
+  }
+};
+
+// src/network.ts
+var NETWORKS = {
+  mainnet: {
+    network: "mainnet",
+    baseUrl: "https://mainnet-public.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/mainnet",
+    currency: { symbol: "HBAR", decimals: 8 }
+  },
+  testnet: {
+    network: "testnet",
+    baseUrl: "https://testnet.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/testnet",
+    currency: { symbol: "HBAR", decimals: 8 }
+  },
+  previewnet: {
+    network: "previewnet",
+    baseUrl: "https://previewnet.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/previewnet",
+    currency: { symbol: "HBAR", decimals: 8 }
+  }
+};
+function resolveNetwork(input) {
+  if (!input.network && !input.baseUrl) {
+    throw new InvalidParamsError("`network` (or `baseUrl`) is required \u2014 there is no default");
+  }
+  const network = input.network ?? "mainnet";
+  const preset = NETWORKS[network];
+  const baseUrl = input.baseUrl ? input.baseUrl.replace(/\/+$/, "") : preset.baseUrl;
+  return { ...preset, baseUrl };
+}
+
+// src/units.ts
+var AMOUNT_RE = /^(-?)(\d*)(?:\.(\d*))?$/;
+function parseUnits(value, decimals) {
+  const m = AMOUNT_RE.exec(value);
+  if (!m || value === "" || value === "-" || value === ".") {
+    throw new InvalidAmountError(`Invalid amount: "${value}"`);
+  }
+  const [, sign, whole = "", frac = ""] = m;
+  if (frac.length > decimals) {
+    throw new InvalidAmountError(
+      `Amount "${value}" has more precision than ${decimals} decimals allow`
+    );
+  }
+  const digits = `${whole}${frac.padEnd(decimals, "0")}` || "0";
+  const base = BigInt(digits === "" ? "0" : digits);
+  return sign === "-" ? -base : base;
+}
+function formatUnits(value, decimals) {
+  const neg = value < 0n;
+  const abs = neg ? -value : value;
+  const s = abs.toString().padStart(decimals + 1, "0");
+  const whole = s.slice(0, s.length - decimals);
+  const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "");
+  const out = frac ? `${whole}.${frac}` : whole;
+  return neg && out !== "0" ? `-${out}` : out;
+}
+var HBAR_DECIMALS = 8;
+var parseHbar = (value) => parseUnits(value, HBAR_DECIMALS);
+var formatHbar = (value) => formatUnits(value, HBAR_DECIMALS);
+
+// src/ids.ts
+var ENTITY_RE = /^\d+\.\d+\.\d+$/;
+function isEntityId(value) {
+  return ENTITY_RE.test(value);
+}
+function assertEntityId(value) {
+  if (!isEntityId(value)) throw new InvalidParamsError(`Invalid account/entity id: "${value}"`);
+  return value;
+}
+var padNanos = (nanos) => nanos.padStart(9, "0").slice(0, 9);
+var SDK_TX_RE = /^(\d+\.\d+\.\d+)@(\d+)\.(\d+)$/;
+var MIRROR_TX_RE = /^(\d+\.\d+\.\d+)-(\d+)-(\d+)$/;
+function txIdToMirror(id) {
+  if (MIRROR_TX_RE.test(id)) return id;
+  const m = SDK_TX_RE.exec(id);
+  if (!m) throw new InvalidParamsError(`Invalid transaction id: "${id}"`);
+  const [, account, seconds, nanos] = m;
+  return `${account}-${seconds}-${padNanos(nanos)}`;
+}
+function txIdToSdk(id) {
+  if (SDK_TX_RE.test(id)) return id;
+  const m = MIRROR_TX_RE.exec(id);
+  if (!m) throw new InvalidParamsError(`Invalid transaction id: "${id}"`);
+  const [, account, seconds, nanos] = m;
+  return `${account}@${seconds}.${padNanos(nanos)}`;
+}
+
+// src/timestamp.ts
+var TS_RE = /^(\d{1,15})(?:\.(\d{1,9}))?$/;
+function parseTimestamp(raw) {
+  const m = TS_RE.exec(raw);
+  if (!m) throw new InvalidParamsError(`Invalid timestamp: "${raw}"`);
+  const seconds = Number(m[1]);
+  const nanosStr = (m[2] ?? "").padEnd(9, "0");
+  const nanos = Number(nanosStr);
+  return {
+    raw,
+    seconds,
+    nanos,
+    toNanos: () => BigInt(m[1]) * 1000000000n + BigInt(nanosStr || "0"),
+    toDate: () => new Date(seconds * 1e3 + Math.floor(nanos / 1e6))
+  };
+}
+function dateToTimestamp(date) {
+  const ms = date.getTime();
+  const seconds = Math.floor(ms / 1e3);
+  const millis = ms - seconds * 1e3;
+  return `${seconds}.${String(millis).padStart(3, "0")}000000`;
+}
+function tsFilter(op, value) {
+  const v = value instanceof Date ? dateToTimestamp(value) : value;
+  return `${op}:${v}`;
+}
+
+// src/query.ts
+function hashFn(key) {
+  return JSON.stringify(key, (_k, value) => {
+    if (typeof value === "bigint") return `${value}#bigint`;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce((acc, k) => {
+        acc[k] = value[k];
+        return acc;
+      }, {});
+    }
+    return value;
+  });
+}
+function makeQueryKey(resource, options) {
+  const filtered = {};
+  for (const [k, v] of Object.entries(options)) {
+    if (v !== void 0) filtered[k] = v;
+  }
+  return [resource, filtered];
+}
+
+export { HBAR_DECIMALS, HbarKitError, InvalidAmountError, InvalidParamsError, MirrorHttpError, NETWORKS, NetworkError, NotFoundError, PaymentVerificationError, RateLimitError, TimeoutError, assertEntityId, dateToTimestamp, formatHbar, formatUnits, hashFn, isEntityId, makeQueryKey, parseHbar, parseTimestamp, parseUnits, resolveNetwork, tsFilter, txIdToMirror, txIdToSdk };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/network.ts","../src/units.ts","../src/ids.ts","../src/timestamp.ts","../src/query.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export interface HbarKitErrorOptions {\n  cause?: unknown\n  details?: string\n  docsPath?: string\n}\n\nexport class HbarKitError extends Error {\n  readonly shortMessage: string\n  readonly details: string | undefined\n  readonly docsPath: string | undefined\n  constructor(message: string, opts: HbarKitErrorOptions = {}) {\n    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined)\n    this.name = \"HbarKitError\"\n    this.shortMessage = message\n    this.details = opts.details\n    this.docsPath = opts.docsPath\n  }\n  /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */\n  walk(fn?: (err: unknown) => boolean): unknown {\n    return walkCauseChain(this, fn)\n  }\n}\n\n/** Walk an error's cause chain; returns the first match for fn, or the deepest cause. */\nfunction walkCauseChain(start: unknown, fn?: (err: unknown) => boolean): unknown {\n  let current: unknown = start\n  while (current) {\n    if (fn?.(current)) return current\n    const next: unknown = (current as { cause?: unknown }).cause\n    if (!next) return fn ? null : current\n    current = next\n  }\n  return null\n}\n\nexport class MirrorHttpError extends HbarKitError {\n  readonly status: number\n  constructor(message: string, status: number, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"MirrorHttpError\"\n    this.status = status\n  }\n}\nexport class RateLimitError extends MirrorHttpError {\n  readonly retryAfter: number | undefined\n  constructor(message: string, opts?: HbarKitErrorOptions & { retryAfter?: number }) {\n    super(message, 429, opts)\n    this.name = \"RateLimitError\"\n    this.retryAfter = opts?.retryAfter\n  }\n}\nexport class NotFoundError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"NotFoundError\"\n  }\n}\nexport class TimeoutError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"TimeoutError\"\n  }\n}\nexport class NetworkError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"NetworkError\"\n  }\n}\nexport class InvalidAmountError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"InvalidAmountError\"\n  }\n}\nexport class InvalidParamsError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"InvalidParamsError\"\n  }\n}\nexport class PaymentVerificationError extends HbarKitError {\n  constructor(message: string, opts?: HbarKitErrorOptions) {\n    super(message, opts)\n    this.name = \"PaymentVerificationError\"\n  }\n}\n","import { InvalidParamsError } from \"./errors.js\"\n\nexport type HederaNetwork = \"mainnet\" | \"testnet\" | \"previewnet\"\n\nexport interface NetworkConfig {\n  network: HederaNetwork\n  baseUrl: string\n  hashscan: string\n  currency: { symbol: \"HBAR\"; decimals: 8 }\n}\n\nexport const NETWORKS: Record<HederaNetwork, NetworkConfig> = {\n  mainnet: {\n    network: \"mainnet\",\n    baseUrl: \"https://mainnet-public.mirrornode.hedera.com\",\n    hashscan: \"https://hashscan.io/mainnet\",\n    currency: { symbol: \"HBAR\", decimals: 8 },\n  },\n  testnet: {\n    network: \"testnet\",\n    baseUrl: \"https://testnet.mirrornode.hedera.com\",\n    hashscan: \"https://hashscan.io/testnet\",\n    currency: { symbol: \"HBAR\", decimals: 8 },\n  },\n  previewnet: {\n    network: \"previewnet\",\n    baseUrl: \"https://previewnet.mirrornode.hedera.com\",\n    hashscan: \"https://hashscan.io/previewnet\",\n    currency: { symbol: \"HBAR\", decimals: 8 },\n  },\n}\n\nexport interface NetworkInput {\n  network?: HederaNetwork\n  baseUrl?: string\n}\n\n/** Resolve a network input to a full config. Requires `network` or `baseUrl`. */\nexport function resolveNetwork(input: NetworkInput): NetworkConfig {\n  if (!input.network && !input.baseUrl) {\n    throw new InvalidParamsError(\"`network` (or `baseUrl`) is required — there is no default\")\n  }\n  const network: HederaNetwork = input.network ?? \"mainnet\"\n  const preset = NETWORKS[network]\n  const baseUrl = input.baseUrl ? input.baseUrl.replace(/\\/+$/, \"\") : preset.baseUrl\n  return { ...preset, baseUrl }\n}\n","import { InvalidAmountError } from \"./errors.js\"\n\nconst AMOUNT_RE = /^(-?)(\\d*)(?:\\.(\\d*))?$/\n\n/** Parse a decimal string into a bigint in the smallest unit. Strict: rejects excess precision. */\nexport function parseUnits(value: string, decimals: number): bigint {\n  const m = AMOUNT_RE.exec(value)\n  if (!m || value === \"\" || value === \"-\" || value === \".\") {\n    throw new InvalidAmountError(`Invalid amount: \"${value}\"`)\n  }\n  const [, sign, whole = \"\", frac = \"\"] = m\n  if (frac.length > decimals) {\n    throw new InvalidAmountError(\n      `Amount \"${value}\" has more precision than ${decimals} decimals allow`,\n    )\n  }\n  const digits = `${whole}${frac.padEnd(decimals, \"0\")}` || \"0\"\n  const base = BigInt(digits === \"\" ? \"0\" : digits)\n  return sign === \"-\" ? -base : base\n}\n\n/** Format a bigint smallest-unit value into a trimmed decimal string. */\nexport function formatUnits(value: bigint, decimals: number): string {\n  const neg = value < 0n\n  const abs = neg ? -value : value\n  const s = abs.toString().padStart(decimals + 1, \"0\")\n  const whole = s.slice(0, s.length - decimals)\n  const frac = decimals === 0 ? \"\" : s.slice(s.length - decimals).replace(/0+$/, \"\")\n  const out = frac ? `${whole}.${frac}` : whole\n  return neg && out !== \"0\" ? `-${out}` : out\n}\n\nexport const HBAR_DECIMALS = 8\nexport const parseHbar = (value: string): bigint => parseUnits(value, HBAR_DECIMALS)\nexport const formatHbar = (value: bigint): string => formatUnits(value, HBAR_DECIMALS)\n","import { InvalidParamsError } from \"./errors.js\"\n\nconst ENTITY_RE = /^\\d+\\.\\d+\\.\\d+$/\n\nexport function isEntityId(value: string): boolean {\n  return ENTITY_RE.test(value)\n}\nexport function assertEntityId(value: string): string {\n  if (!isEntityId(value)) throw new InvalidParamsError(`Invalid account/entity id: \"${value}\"`)\n  return value\n}\n\nconst padNanos = (nanos: string): string => nanos.padStart(9, \"0\").slice(0, 9)\n\n// SDK form:  0.0.payer@seconds.nanos     Mirror form: 0.0.payer-seconds-nanos\nconst SDK_TX_RE = /^(\\d+\\.\\d+\\.\\d+)@(\\d+)\\.(\\d+)$/\nconst MIRROR_TX_RE = /^(\\d+\\.\\d+\\.\\d+)-(\\d+)-(\\d+)$/\n\nexport function txIdToMirror(id: string): string {\n  if (MIRROR_TX_RE.test(id)) return id\n  const m = SDK_TX_RE.exec(id)\n  if (!m) throw new InvalidParamsError(`Invalid transaction id: \"${id}\"`)\n  const [, account, seconds, nanos] = m\n  return `${account}-${seconds}-${padNanos(nanos!)}`\n}\nexport function txIdToSdk(id: string): string {\n  if (SDK_TX_RE.test(id)) return id\n  const m = MIRROR_TX_RE.exec(id)\n  if (!m) throw new InvalidParamsError(`Invalid transaction id: \"${id}\"`)\n  const [, account, seconds, nanos] = m\n  return `${account}@${seconds}.${padNanos(nanos!)}`\n}\n","import { InvalidParamsError } from \"./errors.js\"\n\nexport interface HederaTimestamp {\n  readonly raw: string\n  readonly seconds: number\n  readonly nanos: number\n  toNanos(): bigint\n  toDate(): Date\n}\n\nconst TS_RE = /^(\\d{1,15})(?:\\.(\\d{1,9}))?$/\n\nexport function parseTimestamp(raw: string): HederaTimestamp {\n  const m = TS_RE.exec(raw)\n  if (!m) throw new InvalidParamsError(`Invalid timestamp: \"${raw}\"`)\n  const seconds = Number(m[1])\n  const nanosStr = (m[2] ?? \"\").padEnd(9, \"0\")\n  const nanos = Number(nanosStr)\n  return {\n    raw,\n    seconds,\n    nanos,\n    toNanos: () => BigInt(m![1]!) * 1_000_000_000n + BigInt(nanosStr || \"0\"),\n    toDate: () => new Date(seconds * 1000 + Math.floor(nanos / 1_000_000)),\n  }\n}\n\nexport function dateToTimestamp(date: Date): string {\n  const ms = date.getTime()\n  const seconds = Math.floor(ms / 1000)\n  const millis = ms - seconds * 1000\n  return `${seconds}.${String(millis).padStart(3, \"0\")}000000`\n}\n\nexport type TsOp = \"eq\" | \"ne\" | \"gt\" | \"gte\" | \"lt\" | \"lte\"\n\nexport function tsFilter(op: TsOp, value: string | Date): string {\n  const v = value instanceof Date ? dateToTimestamp(value) : value\n  return `${op}:${v}`\n}\n","/** Deterministic, bigint-safe hash for TanStack Query keys (used from Phase 3). */\nexport function hashFn(key: unknown): string {\n  return JSON.stringify(key, (_k, value) => {\n    if (typeof value === \"bigint\") return `${value}#bigint`\n    if (value && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce<Record<string, unknown>>((acc, k) => {\n          acc[k] = (value as Record<string, unknown>)[k]\n          return acc\n        }, {})\n    }\n    return value\n  })\n}\n\n/** Build a const-style [resource, options] query key, dropping undefined entries. */\nexport function makeQueryKey<T extends Record<string, unknown>>(\n  resource: string,\n  options: T,\n): readonly [string, Partial<T>] {\n  const filtered: Partial<T> = {}\n  for (const [k, v] of Object.entries(options)) {\n    if (v !== undefined) filtered[k as keyof T] = v as T[keyof T]\n  }\n  return [resource, filtered] as const\n}\n"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@hbar-kit/core",
+  "version": "0.1.0",
+  "description": "Zero-dependency primitives for hbar-kit: network config, bigint money, id/timestamp parsing, errors.",
+  "license": "MIT",
+  "homepage": "https://devwhodevs.github.io/hbar-kit/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devwhodevs/hbar-kit.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/devwhodevs/hbar-kit/issues",
+  "keywords": [
+    "hedera",
+    "hbar",
+    "hts",
+    "mirror-node",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@hashgraph/sdk": ">=2.63",
+    "@hiero-ledger/sdk": ">=2.79"
+  },
+  "peerDependenciesMeta": {
+    "@hashgraph/sdk": {
+      "optional": true
+    },
+    "@hiero-ledger/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "check:publish": "publint --strict && attw --pack ."
+  }
+}

package/src/errors.ts

@@ -0,0 +1,87 @@
+export interface HbarKitErrorOptions {
+  cause?: unknown
+  details?: string
+  docsPath?: string
+}
+
+export class HbarKitError extends Error {
+  readonly shortMessage: string
+  readonly details: string | undefined
+  readonly docsPath: string | undefined
+  constructor(message: string, opts: HbarKitErrorOptions = {}) {
+    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined)
+    this.name = "HbarKitError"
+    this.shortMessage = message
+    this.details = opts.details
+    this.docsPath = opts.docsPath
+  }
+  /** Walk the cause chain; returns the first error matching fn, or the deepest cause. */
+  walk(fn?: (err: unknown) => boolean): unknown {
+    return walkCauseChain(this, fn)
+  }
+}
+
+/** Walk an error's cause chain; returns the first match for fn, or the deepest cause. */
+function walkCauseChain(start: unknown, fn?: (err: unknown) => boolean): unknown {
+  let current: unknown = start
+  while (current) {
+    if (fn?.(current)) return current
+    const next: unknown = (current as { cause?: unknown }).cause
+    if (!next) return fn ? null : current
+    current = next
+  }
+  return null
+}
+
+export class MirrorHttpError extends HbarKitError {
+  readonly status: number
+  constructor(message: string, status: number, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "MirrorHttpError"
+    this.status = status
+  }
+}
+export class RateLimitError extends MirrorHttpError {
+  readonly retryAfter: number | undefined
+  constructor(message: string, opts?: HbarKitErrorOptions & { retryAfter?: number }) {
+    super(message, 429, opts)
+    this.name = "RateLimitError"
+    this.retryAfter = opts?.retryAfter
+  }
+}
+export class NotFoundError extends HbarKitError {
+  constructor(message: string, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "NotFoundError"
+  }
+}
+export class TimeoutError extends HbarKitError {
+  constructor(message: string, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "TimeoutError"
+  }
+}
+export class NetworkError extends HbarKitError {
+  constructor(message: string, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "NetworkError"
+  }
+}
+export class InvalidAmountError extends HbarKitError {
+  constructor(message: string, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "InvalidAmountError"
+  }
+}
+export class InvalidParamsError extends HbarKitError {
+  constructor(message: string, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "InvalidParamsError"
+  }
+}
+export class PaymentVerificationError extends HbarKitError {
+  constructor(message: string, opts?: HbarKitErrorOptions) {
+    super(message, opts)
+    this.name = "PaymentVerificationError"
+  }
+}

package/src/ids.ts

@@ -0,0 +1,32 @@
+import { InvalidParamsError } from "./errors.js"
+
+const ENTITY_RE = /^\d+\.\d+\.\d+$/
+
+export function isEntityId(value: string): boolean {
+  return ENTITY_RE.test(value)
+}
+export function assertEntityId(value: string): string {
+  if (!isEntityId(value)) throw new InvalidParamsError(`Invalid account/entity id: "${value}"`)
+  return value
+}
+
+const padNanos = (nanos: string): string => nanos.padStart(9, "0").slice(0, 9)
+
+// SDK form:  0.0.payer@seconds.nanos     Mirror form: 0.0.payer-seconds-nanos
+const SDK_TX_RE = /^(\d+\.\d+\.\d+)@(\d+)\.(\d+)$/
+const MIRROR_TX_RE = /^(\d+\.\d+\.\d+)-(\d+)-(\d+)$/
+
+export function txIdToMirror(id: string): string {
+  if (MIRROR_TX_RE.test(id)) return id
+  const m = SDK_TX_RE.exec(id)
+  if (!m) throw new InvalidParamsError(`Invalid transaction id: "${id}"`)
+  const [, account, seconds, nanos] = m
+  return `${account}-${seconds}-${padNanos(nanos!)}`
+}
+export function txIdToSdk(id: string): string {
+  if (SDK_TX_RE.test(id)) return id
+  const m = MIRROR_TX_RE.exec(id)
+  if (!m) throw new InvalidParamsError(`Invalid transaction id: "${id}"`)
+  const [, account, seconds, nanos] = m
+  return `${account}@${seconds}.${padNanos(nanos!)}`
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./errors.js"
+export * from "./network.js"
+export * from "./units.js"
+export * from "./ids.js"
+export * from "./timestamp.js"
+export * from "./query.js"

package/src/network.ts

@@ -0,0 +1,47 @@
+import { InvalidParamsError } from "./errors.js"
+
+export type HederaNetwork = "mainnet" | "testnet" | "previewnet"
+
+export interface NetworkConfig {
+  network: HederaNetwork
+  baseUrl: string
+  hashscan: string
+  currency: { symbol: "HBAR"; decimals: 8 }
+}
+
+export const NETWORKS: Record<HederaNetwork, NetworkConfig> = {
+  mainnet: {
+    network: "mainnet",
+    baseUrl: "https://mainnet-public.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/mainnet",
+    currency: { symbol: "HBAR", decimals: 8 },
+  },
+  testnet: {
+    network: "testnet",
+    baseUrl: "https://testnet.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/testnet",
+    currency: { symbol: "HBAR", decimals: 8 },
+  },
+  previewnet: {
+    network: "previewnet",
+    baseUrl: "https://previewnet.mirrornode.hedera.com",
+    hashscan: "https://hashscan.io/previewnet",
+    currency: { symbol: "HBAR", decimals: 8 },
+  },
+}
+
+export interface NetworkInput {
+  network?: HederaNetwork
+  baseUrl?: string
+}
+
+/** Resolve a network input to a full config. Requires `network` or `baseUrl`. */
+export function resolveNetwork(input: NetworkInput): NetworkConfig {
+  if (!input.network && !input.baseUrl) {
+    throw new InvalidParamsError("`network` (or `baseUrl`) is required — there is no default")
+  }
+  const network: HederaNetwork = input.network ?? "mainnet"
+  const preset = NETWORKS[network]
+  const baseUrl = input.baseUrl ? input.baseUrl.replace(/\/+$/, "") : preset.baseUrl
+  return { ...preset, baseUrl }
+}

package/src/query.ts

@@ -0,0 +1,27 @@
+/** Deterministic, bigint-safe hash for TanStack Query keys (used from Phase 3). */
+export function hashFn(key: unknown): string {
+  return JSON.stringify(key, (_k, value) => {
+    if (typeof value === "bigint") return `${value}#bigint`
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value as Record<string, unknown>)
+        .sort()
+        .reduce<Record<string, unknown>>((acc, k) => {
+          acc[k] = (value as Record<string, unknown>)[k]
+          return acc
+        }, {})
+    }
+    return value
+  })
+}
+
+/** Build a const-style [resource, options] query key, dropping undefined entries. */
+export function makeQueryKey<T extends Record<string, unknown>>(
+  resource: string,
+  options: T,
+): readonly [string, Partial<T>] {
+  const filtered: Partial<T> = {}
+  for (const [k, v] of Object.entries(options)) {
+    if (v !== undefined) filtered[k as keyof T] = v as T[keyof T]
+  }
+  return [resource, filtered] as const
+}

package/src/timestamp.ts

@@ -0,0 +1,40 @@
+import { InvalidParamsError } from "./errors.js"
+
+export interface HederaTimestamp {
+  readonly raw: string
+  readonly seconds: number
+  readonly nanos: number
+  toNanos(): bigint
+  toDate(): Date
+}
+
+const TS_RE = /^(\d{1,15})(?:\.(\d{1,9}))?$/
+
+export function parseTimestamp(raw: string): HederaTimestamp {
+  const m = TS_RE.exec(raw)
+  if (!m) throw new InvalidParamsError(`Invalid timestamp: "${raw}"`)
+  const seconds = Number(m[1])
+  const nanosStr = (m[2] ?? "").padEnd(9, "0")
+  const nanos = Number(nanosStr)
+  return {
+    raw,
+    seconds,
+    nanos,
+    toNanos: () => BigInt(m![1]!) * 1_000_000_000n + BigInt(nanosStr || "0"),
+    toDate: () => new Date(seconds * 1000 + Math.floor(nanos / 1_000_000)),
+  }
+}
+
+export function dateToTimestamp(date: Date): string {
+  const ms = date.getTime()
+  const seconds = Math.floor(ms / 1000)
+  const millis = ms - seconds * 1000
+  return `${seconds}.${String(millis).padStart(3, "0")}000000`
+}
+
+export type TsOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte"
+
+export function tsFilter(op: TsOp, value: string | Date): string {
+  const v = value instanceof Date ? dateToTimestamp(value) : value
+  return `${op}:${v}`
+}

package/src/units.ts

@@ -0,0 +1,35 @@
+import { InvalidAmountError } from "./errors.js"
+
+const AMOUNT_RE = /^(-?)(\d*)(?:\.(\d*))?$/
+
+/** Parse a decimal string into a bigint in the smallest unit. Strict: rejects excess precision. */
+export function parseUnits(value: string, decimals: number): bigint {
+  const m = AMOUNT_RE.exec(value)
+  if (!m || value === "" || value === "-" || value === ".") {
+    throw new InvalidAmountError(`Invalid amount: "${value}"`)
+  }
+  const [, sign, whole = "", frac = ""] = m
+  if (frac.length > decimals) {
+    throw new InvalidAmountError(
+      `Amount "${value}" has more precision than ${decimals} decimals allow`,
+    )
+  }
+  const digits = `${whole}${frac.padEnd(decimals, "0")}` || "0"
+  const base = BigInt(digits === "" ? "0" : digits)
+  return sign === "-" ? -base : base
+}
+
+/** Format a bigint smallest-unit value into a trimmed decimal string. */
+export function formatUnits(value: bigint, decimals: number): string {
+  const neg = value < 0n
+  const abs = neg ? -value : value
+  const s = abs.toString().padStart(decimals + 1, "0")
+  const whole = s.slice(0, s.length - decimals)
+  const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "")
+  const out = frac ? `${whole}.${frac}` : whole
+  return neg && out !== "0" ? `-${out}` : out
+}
+
+export const HBAR_DECIMALS = 8
+export const parseHbar = (value: string): bigint => parseUnits(value, HBAR_DECIMALS)
+export const formatHbar = (value: bigint): string => formatUnits(value, HBAR_DECIMALS)