near-kit 0.0.0 → 0.2.0

package/dist/utils/amount.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Amount utilities for NEAR tokens.
+ *
+ * All amounts must specify units explicitly:
+ * - `Amount.NEAR(10)` → `"10 NEAR"`
+ * - `Amount.yocto(1000n)` → `"1000 yocto"`
+ * - `"10 NEAR"` (string literal)
+ * - `"1000 yocto"` (string literal)
+ * - `1000n` (bigint literal, treated as yoctoNEAR)
+ *
+ * No bare numbers are accepted in order to prevent accidental unit confusion.
+ */
+/**
+ * Amount input type - must be a string with unit specification or bigint.
+ *
+ * Accepts:
+ * - Literal strings: "10 NEAR", "10.5 NEAR", "1000 yocto"
+ * - Constructor output: Amount.NEAR(10), Amount.yocto(1000n)
+ * - Raw bigint: 1000000n (interpreted as yoctoNEAR)
+ *
+ * For variables, use 'as const' to preserve literal type:
+ * @example
+ * const amount = "10 NEAR" as const
+ * const yocto = 1000000n  // Direct bigint is treated as yoctoNEAR
+ */
+export type AmountInput = `${number} NEAR` | `${number}.${number} NEAR` | `${number} yocto` | ReturnType<typeof Amount.NEAR> | ReturnType<typeof Amount.yocto> | bigint;
+/**
+ * Amount namespace - explicit constructors for NEAR values.
+ *
+ * @example
+ * Amount.NEAR(10)           // "10 NEAR"
+ * Amount.NEAR(10.5)         // "10.5 NEAR"
+ * Amount.NEAR("10.5")       // "10.5 NEAR"
+ * Amount.yocto(1000000n)    // "1000000 yocto"
+ * Amount.yocto("1000000")   // "1000000 yocto"
+ */
+export declare const Amount: {
+    /**
+     * Create a NEAR amount.
+     * @param value - Amount in NEAR.
+     * @returns Formatted string `"X NEAR"`.
+     */
+    readonly NEAR: (value: number | string) => string;
+    /**
+     * Create a yoctoNEAR amount (10^-24 NEAR).
+     * @param value - Amount in yoctoNEAR.
+     * @returns Formatted string `"X yocto"`.
+     */
+    readonly yocto: (value: bigint | string) => string;
+    /**
+     * Common amount constants.
+     */
+    readonly ZERO: "0 yocto";
+    readonly ONE_NEAR: "1 NEAR";
+    readonly ONE_YOCTO: "1 yocto";
+};
+/**
+ * Parse amount to yoctoNEAR.
+ *
+ * @param amount - Amount with unit (e.g., `"10 NEAR"`, `"1000 yocto"`) or bigint (treated as yoctoNEAR).
+ * @returns Amount in yoctoNEAR as a string.
+ * @throws Error If the format is invalid or ambiguous (e.g. bare numbers).
+ */
+export declare function parseAmount(amount: AmountInput): string;
+/**
+ * Format yoctoNEAR to human-readable NEAR
+ * @param yocto - Amount in yoctoNEAR
+ * @param options - Formatting options
+ * @returns Formatted string (e.g., "10.50 NEAR")
+ */
+export declare function formatAmount(yocto: string | bigint, options?: {
+    precision?: number;
+    includeSuffix?: boolean;
+    trimZeros?: boolean;
+}): string;
+//# sourceMappingURL=amount.d.ts.map

package/dist/utils/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../src/utils/amount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACnB,GAAG,MAAM,OAAO,GAChB,GAAG,MAAM,IAAI,MAAM,OAAO,GAC1B,GAAG,MAAM,QAAQ,GACjB,UAAU,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,GAC9B,UAAU,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,GAC/B,MAAM,CAAA;AAEV;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM;IACjB;;;;OAIG;2BACS,MAAM,GAAG,MAAM,KAAG,MAAM;IAIpC;;;;OAIG;4BACU,MAAM,GAAG,MAAM,KAAG,MAAM;IAIrC;;OAEG;;;;CAIK,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA+CvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GACA,MAAM,CA4BR"}

package/dist/utils/amount.js

@@ -0,0 +1,137 @@
+/**
+ * Amount utilities for NEAR tokens.
+ *
+ * All amounts must specify units explicitly:
+ * - `Amount.NEAR(10)` → `"10 NEAR"`
+ * - `Amount.yocto(1000n)` → `"1000 yocto"`
+ * - `"10 NEAR"` (string literal)
+ * - `"1000 yocto"` (string literal)
+ * - `1000n` (bigint literal, treated as yoctoNEAR)
+ *
+ * No bare numbers are accepted in order to prevent accidental unit confusion.
+ */
+import { YOCTO_PER_NEAR } from "../core/constants.js";
+/**
+ * Amount namespace - explicit constructors for NEAR values.
+ *
+ * @example
+ * Amount.NEAR(10)           // "10 NEAR"
+ * Amount.NEAR(10.5)         // "10.5 NEAR"
+ * Amount.NEAR("10.5")       // "10.5 NEAR"
+ * Amount.yocto(1000000n)    // "1000000 yocto"
+ * Amount.yocto("1000000")   // "1000000 yocto"
+ */
+export const Amount = {
+    /**
+     * Create a NEAR amount.
+     * @param value - Amount in NEAR.
+     * @returns Formatted string `"X NEAR"`.
+     */
+    NEAR(value) {
+        return `${value} NEAR`;
+    },
+    /**
+     * Create a yoctoNEAR amount (10^-24 NEAR).
+     * @param value - Amount in yoctoNEAR.
+     * @returns Formatted string `"X yocto"`.
+     */
+    yocto(value) {
+        return `${value} yocto`;
+    },
+    /**
+     * Common amount constants.
+     */
+    ZERO: "0 yocto",
+    ONE_NEAR: "1 NEAR",
+    ONE_YOCTO: "1 yocto",
+};
+/**
+ * Parse amount to yoctoNEAR.
+ *
+ * @param amount - Amount with unit (e.g., `"10 NEAR"`, `"1000 yocto"`) or bigint (treated as yoctoNEAR).
+ * @returns Amount in yoctoNEAR as a string.
+ * @throws Error If the format is invalid or ambiguous (e.g. bare numbers).
+ */
+export function parseAmount(amount) {
+    // Handle bigint directly (treated as yoctoNEAR)
+    if (typeof amount === "bigint") {
+        return amount.toString();
+    }
+    const trimmed = amount.trim();
+    // Parse "X NEAR" format (case insensitive)
+    const nearMatch = trimmed.match(/^([\d.]+)\s+NEAR$/i);
+    if (nearMatch) {
+        // Safe to use non-null assertion after match check
+        // biome-ignore lint/style/noNonNullAssertion: regex capture group guaranteed to exist when match succeeds
+        const value = nearMatch[1];
+        return parseNearToYocto(value);
+    }
+    // Parse "X yocto" format
+    const yoctoMatch = trimmed.match(/^(\d+)\s+yocto$/i);
+    if (yoctoMatch) {
+        // Safe to use non-null assertion after match check
+        // biome-ignore lint/style/noNonNullAssertion: regex capture group guaranteed to exist when match succeeds
+        return yoctoMatch[1];
+    }
+    // Common mistake: bare number
+    if (/^[\d.]+$/.test(trimmed)) {
+        throw new Error(`Ambiguous amount: "${amount}". Did you mean "${amount} NEAR"?\n` +
+            `  - Use Amount.NEAR(${amount}) for NEAR\n` +
+            `  - Use Amount.yocto(${amount}n) for yoctoNEAR\n` +
+            `  - Or write "${amount} NEAR" or "${amount} yocto"\n` +
+            `  - Or pass ${amount}n as bigint for yoctoNEAR\n` +
+            `\n` +
+            `💡 TypeScript tip: Use 'as const' for variables:\n` +
+            `   const amount = "10 NEAR" as const`);
+    }
+    // Invalid format
+    throw new Error(`Invalid amount format: "${amount}"\n` +
+        `Expected formats:\n` +
+        `  - "10 NEAR" or Amount.NEAR(10)\n` +
+        `  - "1000000 yocto" or Amount.yocto(1000000n)\n` +
+        `  - 1000000n (bigint, treated as yoctoNEAR)`);
+}
+/**
+ * Format yoctoNEAR to human-readable NEAR
+ * @param yocto - Amount in yoctoNEAR
+ * @param options - Formatting options
+ * @returns Formatted string (e.g., "10.50 NEAR")
+ */
+export function formatAmount(yocto, options) {
+    const { precision = 2, includeSuffix = true, trimZeros = false, } = options || {};
+    const amount = typeof yocto === "string" ? BigInt(yocto) : yocto;
+    const wholePart = amount / YOCTO_PER_NEAR;
+    const fracPart = amount % YOCTO_PER_NEAR;
+    let result;
+    if (fracPart === BigInt(0)) {
+        result = wholePart.toString();
+    }
+    else {
+        const fracStr = fracPart.toString().padStart(24, "0");
+        let decimals = fracStr.substring(0, precision);
+        if (trimZeros) {
+            decimals = decimals.replace(/0+$/, "");
+        }
+        result = decimals ? `${wholePart}.${decimals}` : wholePart.toString();
+    }
+    return includeSuffix ? `${result} NEAR` : result;
+}
+/**
+ * Internal: Parse NEAR value to yoctoNEAR
+ * Note: The caller (parseAmount) already validates the format with the same regex,
+ * so the value is guaranteed to match [\d.]+ pattern when it reaches this function.
+ */
+function parseNearToYocto(value) {
+    // Split into whole and fractional parts
+    const parts = value.split(".");
+    const wholePart = parts[0] || "0";
+    const fracPart = (parts[1] || "").padEnd(24, "0").substring(0, 24);
+    // Check for negative values
+    if (wholePart.startsWith("-")) {
+        throw new Error("NEAR amount must be non-negative");
+    }
+    // Convert to yoctoNEAR
+    const yocto = BigInt(wholePart) * YOCTO_PER_NEAR + BigInt(fracPart);
+    return yocto.toString();
+}
+//# sourceMappingURL=amount.js.map

package/dist/utils/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../src/utils/amount.ts"],"names":[],"mappings":"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"}

package/dist/utils/gas.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gas utilities for NEAR transactions.
+ *
+ * Gas amounts should specify units explicitly:
+ * - `Gas.Tgas(30)` → `"30 Tgas"`
+ * - `"30 Tgas"` (string literal)
+ *
+ * Raw gas units (e.g. `"30000000000000"`) are also supported for advanced use cases.
+ */
+/**
+ * Gas input type - string with unit specification.
+ *
+ * Accepts:
+ * - Literal strings: "30 Tgas", "30.5 Tgas"
+ * - Raw gas strings: "30000000000000"
+ * - Constructor output: Gas.Tgas(30)
+ *
+ * For variables, use 'as const' to preserve literal type:
+ * @example
+ * const gas = "30 Tgas" as const
+ */
+export type GasInput = `${number} Tgas` | `${number}.${number} Tgas` | `${number}` | ReturnType<typeof Gas.Tgas>;
+/**
+ * Gas namespace - explicit constructors.
+ *
+ * @example
+ * Gas.Tgas(30)        // "30 Tgas"
+ * Gas.Tgas(300)       // "300 Tgas"
+ */
+export declare const Gas: {
+    /**
+     * Create gas amount in TGas (teragas).
+     * @param value - Amount in TGas.
+     */
+    readonly Tgas: (value: number | string) => string;
+    /**
+     * Common gas amounts.
+     */
+    readonly DEFAULT: "30 Tgas";
+    readonly MAX: "300 Tgas";
+};
+/**
+ * Parse gas string to raw gas units.
+ *
+ * @param gas - Gas with unit (e.g., `"30 Tgas"`) or raw gas number.
+ * @returns Gas in raw units as a string.
+ */
+export declare function parseGas(gas: GasInput | number): string;
+/**
+ * Format gas to TGas.
+ *
+ * @param gas - Gas in raw units.
+ * @param precision - Decimal places (default: 2).
+ * @returns Formatted gas with `' Tgas'` suffix.
+ */
+export declare function formatGas(gas: string | bigint, precision?: number): string;
+/**
+ * Convert TGas to raw gas units.
+ * @param tgas - Amount in TGas.
+ * @returns Gas amount as string.
+ */
+export declare function toGas(tgas: number): string;
+/**
+ * Convert raw gas to TGas.
+ * @param gas - Gas amount in raw units.
+ * @returns Amount in TGas.
+ */
+export declare function toTGas(gas: string | bigint): number;
+//# sourceMappingURL=gas.d.ts.map

package/dist/utils/gas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../../src/utils/gas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAChB,GAAG,MAAM,OAAO,GAChB,GAAG,MAAM,IAAI,MAAM,OAAO,GAC1B,GAAG,MAAM,EAAE,GACX,UAAU,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,CAAA;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,GAAG;IACd;;;OAGG;2BACS,MAAM,GAAG,MAAM,KAAG,MAAM;IAIpC;;OAEG;;;CAGK,CAAA;AAEV;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CA6BvD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,SAAI,GAAG,MAAM,CAIrE;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGnD"}

package/dist/utils/gas.js

@@ -0,0 +1,92 @@
+/**
+ * Gas utilities for NEAR transactions.
+ *
+ * Gas amounts should specify units explicitly:
+ * - `Gas.Tgas(30)` → `"30 Tgas"`
+ * - `"30 Tgas"` (string literal)
+ *
+ * Raw gas units (e.g. `"30000000000000"`) are also supported for advanced use cases.
+ */
+import { GAS_PER_TGAS } from "../core/constants.js";
+/**
+ * Gas namespace - explicit constructors.
+ *
+ * @example
+ * Gas.Tgas(30)        // "30 Tgas"
+ * Gas.Tgas(300)       // "300 Tgas"
+ */
+export const Gas = {
+    /**
+     * Create gas amount in TGas (teragas).
+     * @param value - Amount in TGas.
+     */
+    Tgas(value) {
+        return `${value} Tgas`;
+    },
+    /**
+     * Common gas amounts.
+     */
+    DEFAULT: "30 Tgas",
+    MAX: "300 Tgas",
+};
+/**
+ * Parse gas string to raw gas units.
+ *
+ * @param gas - Gas with unit (e.g., `"30 Tgas"`) or raw gas number.
+ * @returns Gas in raw units as a string.
+ */
+export function parseGas(gas) {
+    const gasStr = typeof gas === "number" ? gas.toString() : gas;
+    const trimmed = gasStr.trim();
+    // Parse "X Tgas" format (case insensitive)
+    const tgasMatch = trimmed.match(/^([\d.]+)\s+Tgas$/i);
+    if (tgasMatch) {
+        // Safe to use non-null assertion after match check
+        // biome-ignore lint/style/noNonNullAssertion: regex capture group guaranteed to exist when match succeeds
+        const tgas = parseFloat(tgasMatch[1]);
+        if (Number.isNaN(tgas) || tgas < 0) {
+            // biome-ignore lint/style/noNonNullAssertion: same capture group as above
+            throw new Error(`Invalid Tgas value: ${tgasMatch[1]}`);
+        }
+        return BigInt(Math.floor(tgas * 1e12)).toString();
+    }
+    // Raw number (no unit) - assume it's already in gas units
+    // This allows power users to specify exact gas amounts
+    if (/^\d+$/.test(trimmed)) {
+        return trimmed;
+    }
+    // Invalid format
+    throw new Error(`Invalid gas format: "${gas}"\n` +
+        `Expected: "30 Tgas" or Gas.Tgas(30)\n` +
+        `Or provide raw gas units as a number string`);
+}
+/**
+ * Format gas to TGas.
+ *
+ * @param gas - Gas in raw units.
+ * @param precision - Decimal places (default: 2).
+ * @returns Formatted gas with `' Tgas'` suffix.
+ */
+export function formatGas(gas, precision = 2) {
+    const amount = typeof gas === "string" ? BigInt(gas) : gas;
+    const tgas = Number(amount) / Number(GAS_PER_TGAS);
+    return `${tgas.toFixed(precision)} Tgas`;
+}
+/**
+ * Convert TGas to raw gas units.
+ * @param tgas - Amount in TGas.
+ * @returns Gas amount as string.
+ */
+export function toGas(tgas) {
+    return (BigInt(Math.floor(tgas * 1e12)) * BigInt(1)).toString();
+}
+/**
+ * Convert raw gas to TGas.
+ * @param gas - Gas amount in raw units.
+ * @returns Amount in TGas.
+ */
+export function toTGas(gas) {
+    const amount = typeof gas === "string" ? BigInt(gas) : gas;
+    return Number(amount) / Number(GAS_PER_TGAS);
+}
+//# sourceMappingURL=gas.js.map

package/dist/utils/gas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.js","sourceRoot":"","sources":["../../src/utils/gas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAoBnD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB;;;OAGG;IACH,IAAI,CAAC,KAAsB;QACzB,OAAO,GAAG,KAAK,OAAO,CAAA;IACxB,CAAC;IAED;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB,GAAG,EAAE,UAAU;CACP,CAAA;AAEV;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAsB;IAC7C,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;IAE7B,2CAA2C;IAC3C,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAA;IACrD,IAAI,SAAS,EAAE,CAAC;QACd,mDAAmD;QACnD,0GAA0G;QAC1G,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,CAAA;QACtC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACnC,0EAA0E;YAC1E,MAAM,IAAI,KAAK,CAAC,uBAAuB,SAAS,CAAC,CAAC,CAAE,EAAE,CAAC,CAAA;QACzD,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACnD,CAAC;IAED,0DAA0D;IAC1D,uDAAuD;IACvD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,iBAAiB;IACjB,MAAM,IAAI,KAAK,CACb,wBAAwB,GAAG,KAAK;QAC9B,uCAAuC;QACvC,6CAA6C,CAChD,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,GAAoB,EAAE,SAAS,GAAG,CAAC;IAC3D,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAA;IAClD,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAA;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,GAAoB;IACzC,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAA;AAC9C,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Utility functions for the NEAR client library.
+ *
+ * @remarks
+ * This module exposes helpers for working with human-readable amounts and gas,
+ * key generation and parsing, NEP-413 message signing, and validation of
+ * common NEAR types (account IDs, public/private keys, amounts, gas).
+ */
+export { Amount, type AmountInput, formatAmount, parseAmount, } from "./amount.js";
+export { formatGas, Gas, type GasInput, parseGas } from "./gas.js";
+export * from "./key.js";
+export { generateNep413Nonce, NEP413_TAG, serializeNep413Message, verifyNep413Signature, } from "./nep413.js";
+export { isPrivateKey, isValidAccountId, isValidPublicKey, type PrivateKey, validateAccountId, validatePrivateKey, validatePublicKey, } from "./validation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,MAAM,EACN,KAAK,WAAW,EAChB,YAAY,EACZ,WAAW,GACZ,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,QAAQ,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAClE,cAAc,UAAU,CAAA;AACxB,OAAO,EACL,mBAAmB,EACnB,UAAU,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,UAAU,EACf,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,iBAAiB,CAAA"}

package/dist/utils/index.js

@@ -0,0 +1,14 @@
+/**
+ * Utility functions for the NEAR client library.
+ *
+ * @remarks
+ * This module exposes helpers for working with human-readable amounts and gas,
+ * key generation and parsing, NEP-413 message signing, and validation of
+ * common NEAR types (account IDs, public/private keys, amounts, gas).
+ */
+export { Amount, formatAmount, parseAmount, } from "./amount.js";
+export { formatGas, Gas, parseGas } from "./gas.js";
+export * from "./key.js";
+export { generateNep413Nonce, NEP413_TAG, serializeNep413Message, verifyNep413Signature, } from "./nep413.js";
+export { isPrivateKey, isValidAccountId, isValidPublicKey, validateAccountId, validatePrivateKey, validatePublicKey, } from "./validation.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,MAAM,EAEN,YAAY,EACZ,WAAW,GACZ,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,SAAS,EAAE,GAAG,EAAiB,QAAQ,EAAE,MAAM,UAAU,CAAA;AAClE,cAAc,UAAU,CAAA;AACxB,OAAO,EACL,mBAAmB,EACnB,UAAU,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAEhB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,iBAAiB,CAAA"}

package/dist/utils/key.d.ts

@@ -0,0 +1,117 @@
+import { type KeyPair, type PublicKey, type Signature, type SignedMessage, type SignMessageParams } from "../core/types.js";
+/**
+ * Ed25519 key pair implementation.
+ *
+ * @remarks
+ * Implements the {@link KeyPair} interface used throughout the library and
+ * provides NEP-413 message signing via {@link Ed25519KeyPair.signNep413Message}.
+ */
+export declare class Ed25519KeyPair implements KeyPair {
+    publicKey: PublicKey;
+    secretKey: string;
+    private privateKey;
+    constructor(secretKey: Uint8Array);
+    sign(message: Uint8Array): Signature;
+    /**
+     * Sign a message according to NEP-413 specification
+     *
+     * NEP-413 enables off-chain message signing for authentication and ownership verification.
+     * The message is signed with a full-access key but does not require gas or blockchain state.
+     *
+     * @param accountId - The NEAR account ID that owns this key
+     * @param params - Message signing parameters (message, recipient, nonce)
+     * @returns Signed message with account ID, public key, and base64-encoded signature
+     *
+     * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+     *
+     * @example
+     * ```typescript
+     * const nonce = crypto.getRandomValues(new Uint8Array(32))
+     * const signedMessage = keyPair.signNep413Message("alice.near", {
+     *   message: "Login to MyApp",
+     *   recipient: "myapp.near",
+     *   nonce,
+     * })
+     * console.log(signedMessage.signature) // Base64-encoded signature
+     * ```
+     */
+    signNep413Message(accountId: string, params: SignMessageParams): SignedMessage;
+    static fromRandom(): Ed25519KeyPair;
+    static fromString(keyString: string): Ed25519KeyPair;
+}
+/**
+ * Secp256k1 key pair implementation.
+ *
+ * NEAR expects secp256k1 public keys to be 64 bytes (uncompressed without 0x04 header).
+ * The secp256k1 library returns 65-byte uncompressed keys (with 0x04 header), so we
+ * manually remove/add that byte as needed.
+ *
+ * Signatures are 65 bytes: 64-byte signature + 1-byte recovery ID.
+ */
+export declare class Secp256k1KeyPair implements KeyPair {
+    publicKey: PublicKey;
+    secretKey: string;
+    private privateKey;
+    constructor(secretKey: Uint8Array);
+    sign(message: Uint8Array): Signature;
+    /**
+     * Sign a message according to NEP-413 specification
+     *
+     * NEP-413 enables off-chain message signing for authentication and ownership verification.
+     * The message is signed with a full-access key but does not require gas or blockchain state.
+     *
+     * @param accountId - The NEAR account ID that owns this key
+     * @param params - Message signing parameters (message, recipient, nonce)
+     * @returns Signed message with account ID, public key, and base64-encoded signature
+     *
+     * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+     *
+     * @example
+     * ```typescript
+     * const nonce = crypto.getRandomValues(new Uint8Array(32))
+     * const signedMessage = keyPair.signNep413Message("alice.near", {
+     *   message: "Login to MyApp",
+     *   recipient: "myapp.near",
+     *   nonce,
+     * })
+     * console.log(signedMessage.signature) // Base64-encoded signature
+     * ```
+     */
+    signNep413Message(accountId: string, params: SignMessageParams): SignedMessage;
+    static fromRandom(): Secp256k1KeyPair;
+    static fromString(keyString: string): Secp256k1KeyPair;
+}
+/**
+ * Generate a new random Ed25519 key pair.
+ * @returns A new {@link KeyPair} instance.
+ */
+export declare function generateKey(): KeyPair;
+/**
+ * Parse a key string to a {@link KeyPair}.
+ *
+ * @param keyString - Key string (e.g. `"ed25519:..."` or `"secp256k1:..."`).
+ * @returns A concrete {@link Ed25519KeyPair} or {@link Secp256k1KeyPair}.
+ */
+export declare function parseKey(keyString: string): KeyPair;
+/**
+ * Parse a public key string to a {@link PublicKey} object.
+ *
+ * @param publicKeyString - Public key string (e.g. `"ed25519:..."` or `"secp256k1:..."`).
+ * @returns {@link PublicKey} instance.
+ */
+export declare function parsePublicKey(publicKeyString: string): PublicKey;
+/**
+ * Generate a BIP39 seed phrase (12 words by default)
+ * Uses proper BIP39 implementation with cryptographically secure randomness
+ * @param wordCount - Number of words (12, 15, 18, 21, or 24). Defaults to 12
+ * @returns A BIP39 seed phrase string
+ */
+export declare function generateSeedPhrase(wordCount?: 12 | 15 | 18 | 21 | 24): string;
+/**
+ * Parse a BIP39 seed phrase to derive a key pair using proper BIP32/SLIP10 derivation
+ * @param phrase - BIP39 seed phrase (12-24 words)
+ * @param path - BIP32 derivation path (defaults to "m/44'/397'/0'" for NEAR)
+ * @returns KeyPair instance
+ */
+export declare function parseSeedPhrase(phrase: string, path?: string): KeyPair;
+//# sourceMappingURL=key.d.ts.map

package/dist/utils/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/utils/key.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAA;AAIzB;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,OAAO;IAC5C,SAAS,EAAE,SAAS,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,UAAU,CAAY;gBAElB,SAAS,EAAE,UAAU;IAcjC,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS;IAQpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,GACxB,aAAa;IAehB,MAAM,CAAC,UAAU,IAAI,cAAc;IAYnC,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc;CAKrD;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAC9C,SAAS,EAAE,SAAS,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,UAAU,CAAY;gBAElB,SAAS,EAAE,UAAU;IAcjC,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS;IAapC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,GACxB,aAAa;IAiBhB,MAAM,CAAC,UAAU,IAAI,gBAAgB;IAmBrC,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;CAKvD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAUnD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAsBjE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,GAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAO,GACrC,MAAM,CAWR;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAwB,GAC7B,OAAO,CA4BT"}