@spacesops/wdk-react-native-core 1.0.0-beta.40

package/dist/types/hrpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hrpc.js","sourceRoot":"","sources":["../../src/types/hrpc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkDH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,OAAO,CACL,OAAQ,IAA2C,CAAC,aAAa,KAAK,UAAU;QAChF,OAAQ,IAA2C,CAAC,yBAAyB,KAAK,UAAU;QAC5F,OAAQ,IAA2C,CAAC,sBAAsB,KAAK,UAAU;QACzF,OAAQ,IAA2C,CAAC,6BAA6B,KAAK,UAAU,CACjG,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAA;IAC1E,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Core Type Definitions
+ *
+ * All network, token, and wallet type definitions for the WDK React Native Core library.
+ */
+/**
+ * Network Configuration
+ *
+ * Defines the configuration for a blockchain network.
+ */
+export interface NetworkConfig {
+    /** Chain ID for the network */
+    chainId: number;
+    /** Blockchain name (e.g., "ethereum", "polygon") */
+    blockchain: string;
+    /** Optional RPC provider URL */
+    provider?: string;
+    /** Optional bundler URL for account abstraction */
+    bundlerUrl?: string;
+    /** Optional paymaster URL for account abstraction */
+    paymasterUrl?: string;
+    /** Optional paymaster contract address */
+    paymasterAddress?: string;
+    /** Optional entry point contract address */
+    entryPointAddress?: string;
+    /** Optional maximum fee for transfers */
+    transferMaxFee?: number;
+}
+/**
+ * Network Configurations
+ *
+ * Maps network names to their configurations.
+ */
+export type NetworkConfigs = Record<string, NetworkConfig>;
+/**
+ * Token Configuration
+ *
+ * Defines the configuration for a token (native or ERC20).
+ */
+export interface TokenConfig {
+    /** Token symbol (e.g., "ETH", "USDT") */
+    symbol: string;
+    /** Token name (e.g., "Ethereum", "Tether") */
+    name: string;
+    /** Number of decimals (0-18) */
+    decimals: number;
+    /** Token contract address (null for native tokens) */
+    address: string | null;
+}
+/**
+ * Network Tokens
+ *
+ * Defines the tokens available for a network (native + ERC20 tokens).
+ */
+export interface NetworkTokens {
+    /** Native token configuration */
+    native: TokenConfig;
+    /** Array of ERC20 token configurations */
+    tokens: TokenConfig[];
+}
+/**
+ * Token Configurations
+ *
+ * Maps network names to their token configurations.
+ */
+export type TokenConfigs = Record<string, NetworkTokens>;
+/**
+ * Wallet
+ *
+ * Represents a wallet instance with metadata.
+ */
+export interface Wallet {
+    /** Account index (0-based) */
+    accountIndex: number;
+    /** Unique wallet identifier */
+    identifier: string;
+    /** Wallet display name */
+    name: string;
+    /** Timestamp when wallet was created */
+    createdAt: number;
+    /** Timestamp when wallet was last updated */
+    updatedAt: number;
+}
+/**
+ * Wallet Addresses
+ *
+ * Maps network -> accountIndex -> address
+ * Structure: { [network]: { [accountIndex]: address } }
+ */
+export type WalletAddresses = Record<string, Record<number, string>>;
+/**
+ * Wallet Addresses by Wallet Identifier
+ *
+ * Maps walletId -> network -> accountIndex -> address
+ * Structure: { [walletId]: { [network]: { [accountIndex]: address } } }
+ */
+export type WalletAddressesByWallet = Record<string, WalletAddresses>;
+/**
+ * Wallet Balances
+ *
+ * Maps network -> accountIndex -> tokenAddress -> balance
+ * Structure: { [network]: { [accountIndex]: { [tokenAddress]: balance } } }
+ * Note: balance is stored as a string to handle BigInt values
+ */
+export type WalletBalances = Record<string, Record<number, Record<string, string>>>;
+/**
+ * Wallet Balances by Wallet Identifier
+ *
+ * Maps walletId -> network -> accountIndex -> tokenAddress -> balance
+ * Structure: { [walletId]: { [network]: { [accountIndex]: { [tokenAddress]: balance } } } }
+ */
+export type WalletBalancesByWallet = Record<string, WalletBalances>;
+/**
+ * Balance Loading States
+ *
+ * Maps "network-accountIndex-tokenAddress" -> boolean
+ * Used to track which balances are currently being fetched.
+ */
+export type BalanceLoadingStates = Record<string, boolean>;
+/**
+ * Balance Fetch Result
+ *
+ * Result of a balance fetch operation.
+ */
+export interface BalanceFetchResult {
+    /** Whether the fetch was successful */
+    success: boolean;
+    /** Network name */
+    network: string;
+    /** Account index */
+    accountIndex: number;
+    /** Token address (null for native tokens) */
+    tokenAddress: string | null;
+    /** Balance as a string (null if fetch failed) */
+    balance: string | null;
+    /** Error message (only present if success is false) */
+    error?: string;
+}
+/**
+ * Token Config Provider
+ *
+ * Either a TokenConfigs object or a function that returns TokenConfigs.
+ * Allows for dynamic token configuration.
+ */
+export type TokenConfigProvider = TokenConfigs | (() => TokenConfigs);
+/**
+ * Token Helpers
+ *
+ * Helper functions for working with token configurations.
+ */
+export interface TokenHelpers {
+    /** Get all tokens (native + ERC20) for a network */
+    getTokensForNetwork: (network: string) => TokenConfig[];
+    /** Get all supported network names */
+    getSupportedNetworks: () => string[];
+}
+/**
+ * Wallet Store Interface
+ *
+ * Interface for wallet store implementations that provide account methods
+ * and wallet initialization status.
+ */
+export interface WalletStore {
+    /** Call a method on a wallet account */
+    callAccountMethod: <T = unknown>(network: string, accountIndex: number, methodName: string, args?: unknown) => Promise<T>;
+    /** Check if the wallet is initialized */
+    isWalletInitialized: () => boolean;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Core Type Definitions
+ *
+ * All network, token, and wallet type definitions for the WDK React Native Core library.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utils/balanceUtils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Balance utility functions
+ */
+/**
+ * Convert a value to string, handling BigInt values
+ */
+export declare function convertBalanceToString(value: unknown): string;
+/**
+ * Recursively convert BigInt values to strings in objects/arrays
+ * Prevents serialization errors when BigInt values are present
+ *
+ * @param value - Value that may contain BigInt values
+ * @returns Value with all BigInt values converted to strings
+ */
+export declare function convertBigIntToString(value: unknown): unknown;
+/**
+ * Format a balance from wei/smallest unit to readable format
+ *
+ * @param balance - Balance as string (from wei/smallest unit)
+ * @param decimals - Number of decimals for the token (e.g., 18 for ETH, 6 for USDT)
+ * @returns Formatted balance string (e.g., "1.5" or "1000")
+ *
+ * @example
+ * ```ts
+ * formatBalance("1500000000000000000", 18) // "1.5"
+ * formatBalance("1000000", 6) // "1"
+ * formatBalance("1000001", 6) // "1.000001"
+ * ```
+ */
+export declare function formatBalance(balance: string | null, decimals: number): string;

package/dist/utils/balanceUtils.js

@@ -0,0 +1,86 @@
+/**
+ * Balance utility functions
+ */
+import { logError } from './logger';
+/**
+ * Convert a value to string, handling BigInt values
+ */
+export function convertBalanceToString(value) {
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return value.toString();
+    }
+    // Fallback: try to convert to string
+    return String(value);
+}
+/**
+ * Recursively convert BigInt values to strings in objects/arrays
+ * Prevents serialization errors when BigInt values are present
+ *
+ * @param value - Value that may contain BigInt values
+ * @returns Value with all BigInt values converted to strings
+ */
+export function convertBigIntToString(value) {
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(convertBigIntToString);
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, convertBigIntToString(val)]));
+    }
+    return value;
+}
+/**
+ * Format a balance from wei/smallest unit to readable format
+ *
+ * @param balance - Balance as string (from wei/smallest unit)
+ * @param decimals - Number of decimals for the token (e.g., 18 for ETH, 6 for USDT)
+ * @returns Formatted balance string (e.g., "1.5" or "1000")
+ *
+ * @example
+ * ```ts
+ * formatBalance("1500000000000000000", 18) // "1.5"
+ * formatBalance("1000000", 6) // "1"
+ * formatBalance("1000001", 6) // "1.000001"
+ * ```
+ */
+export function formatBalance(balance, decimals) {
+    if (!balance || balance === '0' || balance === 'null') {
+        return '0';
+    }
+    // Validate that balance is a valid numeric string before attempting BigInt conversion
+    // BigInt accepts: digits only, or digits with optional leading minus sign
+    if (!/^-?\d+$/.test(balance.trim())) {
+        // Invalid format - return as-is (for backwards compatibility with test expectations)
+        return balance;
+    }
+    try {
+        const balanceBigInt = BigInt(balance);
+        const divisor = BigInt(10 ** decimals);
+        const wholePart = balanceBigInt / divisor;
+        const fractionalPart = balanceBigInt % divisor;
+        if (fractionalPart === BigInt(0)) {
+            return wholePart.toString();
+        }
+        // Format fractional part with leading zeros if needed
+        const fractionalStr = fractionalPart.toString().padStart(decimals, '0');
+        // Remove trailing zeros
+        const fractionalTrimmed = fractionalStr.replace(/0+$/, '');
+        if (fractionalTrimmed === '') {
+            return wholePart.toString();
+        }
+        return `${wholePart}.${fractionalTrimmed}`;
+    }
+    catch (error) {
+        logError('Error formatting balance:', error);
+        return balance;
+    }
+}
+//# sourceMappingURL=balanceUtils.js.map

package/dist/utils/balanceUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balanceUtils.js","sourceRoot":"","sources":["../../src/utils/balanceUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAA;IACzB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAA;IACzB,CAAC;IACD,qCAAqC;IACrC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAA;IACzB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAA;IACzC,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,CAC7E,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB,EAAE,QAAgB;IACpE,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACtD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,sFAAsF;IACtF,0EAA0E;IAC1E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACpC,qFAAqF;QACrF,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;QACrC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,IAAI,QAAQ,CAAC,CAAA;QACtC,MAAM,SAAS,GAAG,aAAa,GAAG,OAAO,CAAA;QACzC,MAAM,cAAc,GAAG,aAAa,GAAG,OAAO,CAAA;QAE9C,IAAI,cAAc,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAA;QAC7B,CAAC;QAED,sDAAsD;QACtD,MAAM,aAAa,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;QACvE,wBAAwB;QACxB,MAAM,iBAAiB,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAE1D,IAAI,iBAAiB,KAAK,EAAE,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAA;QAC7B,CAAC;QAED,OAAO,GAAG,SAAS,IAAI,iBAAiB,EAAE,CAAA;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAA;QAC5C,OAAO,OAAO,CAAA;IAChB,CAAC;AACH,CAAC"}

package/dist/utils/constants.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Application constants
+ *
+ * Centralized location for magic numbers and configuration values
+ * to improve maintainability and documentation.
+ */
+/**
+ * Default balance refresh interval in milliseconds
+ *
+ * How often to automatically refresh wallet balances when auto-fetch is enabled.
+ * 30 seconds provides a good balance between freshness and performance.
+ */
+export declare const DEFAULT_BALANCE_REFRESH_INTERVAL_MS = 30000;
+/**
+ * Valid mnemonic word counts
+ *
+ * BIP-39 standard supports 12-word (128 bits) and 24-word (256 bits) mnemonics.
+ */
+export declare const MNEMONIC_WORD_COUNTS: {
+    /** 12-word mnemonic (128 bits of entropy) */
+    readonly TWELVE: 12;
+    /** 24-word mnemonic (256 bits of entropy) */
+    readonly TWENTY_FOUR: 24;
+};
+/**
+ * Default mnemonic word count
+ *
+ * 12 words is the most common choice, providing 128 bits of entropy
+ * which is sufficient for most use cases.
+ */
+export declare const DEFAULT_MNEMONIC_WORD_COUNT: 12;
+/**
+ * Account method names for balance operations
+ */
+export declare const ACCOUNT_METHOD_GET_BALANCE = "getBalance";
+export declare const ACCOUNT_METHOD_GET_TOKEN_BALANCE = "getTokenBalance";
+/**
+ * Wallet identifier constants
+ */
+export declare const WALLET_IDENTIFIER_PREFIX = "wallet-";
+export declare const MAIN_WALLET_NAME = "Main Wallet";
+export declare const WALLET_NAME_PREFIX = "Wallet ";
+/**
+ * Token key for native tokens in balance storage
+ */
+export declare const NATIVE_TOKEN_KEY = "native";
+/**
+ * Default query stale time in milliseconds
+ *
+ * How long data is considered fresh before TanStack Query refetches it.
+ * 30 seconds provides a good balance between freshness and performance.
+ */
+export declare const DEFAULT_QUERY_STALE_TIME_MS: number;
+/**
+ * Default query garbage collection time in milliseconds
+ *
+ * How long unused query data is kept in cache before being garbage collected.
+ * 5 minutes provides a good balance between cache efficiency and memory usage.
+ */
+export declare const DEFAULT_QUERY_GC_TIME_MS: number;
+/**
+ * Allowed account methods whitelist
+ * Only these methods can be called through AccountService for security
+ */
+export declare const ALLOWED_ACCOUNT_METHODS: readonly ["getAddress", "getBalance", "getTokenBalance", "signMessage", "signTransaction", "sendTransaction"];
+export type AllowedAccountMethod = typeof ALLOWED_ACCOUNT_METHODS[number];

package/dist/utils/constants.js

@@ -0,0 +1,73 @@
+/**
+ * Application constants
+ *
+ * Centralized location for magic numbers and configuration values
+ * to improve maintainability and documentation.
+ */
+/**
+ * Default balance refresh interval in milliseconds
+ *
+ * How often to automatically refresh wallet balances when auto-fetch is enabled.
+ * 30 seconds provides a good balance between freshness and performance.
+ */
+export const DEFAULT_BALANCE_REFRESH_INTERVAL_MS = 30000;
+/**
+ * Valid mnemonic word counts
+ *
+ * BIP-39 standard supports 12-word (128 bits) and 24-word (256 bits) mnemonics.
+ */
+export const MNEMONIC_WORD_COUNTS = {
+    /** 12-word mnemonic (128 bits of entropy) */
+    TWELVE: 12,
+    /** 24-word mnemonic (256 bits of entropy) */
+    TWENTY_FOUR: 24,
+};
+/**
+ * Default mnemonic word count
+ *
+ * 12 words is the most common choice, providing 128 bits of entropy
+ * which is sufficient for most use cases.
+ */
+export const DEFAULT_MNEMONIC_WORD_COUNT = MNEMONIC_WORD_COUNTS.TWELVE;
+/**
+ * Account method names for balance operations
+ */
+export const ACCOUNT_METHOD_GET_BALANCE = 'getBalance';
+export const ACCOUNT_METHOD_GET_TOKEN_BALANCE = 'getTokenBalance';
+/**
+ * Wallet identifier constants
+ */
+export const WALLET_IDENTIFIER_PREFIX = 'wallet-';
+export const MAIN_WALLET_NAME = 'Main Wallet';
+export const WALLET_NAME_PREFIX = 'Wallet ';
+/**
+ * Token key for native tokens in balance storage
+ */
+export const NATIVE_TOKEN_KEY = 'native';
+/**
+ * Default query stale time in milliseconds
+ *
+ * How long data is considered fresh before TanStack Query refetches it.
+ * 30 seconds provides a good balance between freshness and performance.
+ */
+export const DEFAULT_QUERY_STALE_TIME_MS = 30 * 1000;
+/**
+ * Default query garbage collection time in milliseconds
+ *
+ * How long unused query data is kept in cache before being garbage collected.
+ * 5 minutes provides a good balance between cache efficiency and memory usage.
+ */
+export const DEFAULT_QUERY_GC_TIME_MS = 5 * 60 * 1000;
+/**
+ * Allowed account methods whitelist
+ * Only these methods can be called through AccountService for security
+ */
+export const ALLOWED_ACCOUNT_METHODS = [
+    'getAddress',
+    'getBalance',
+    'getTokenBalance',
+    'signMessage',
+    'signTransaction',
+    'sendTransaction',
+];
+//# sourceMappingURL=constants.js.map

package/dist/utils/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,KAAK,CAAA;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,6CAA6C;IAC7C,MAAM,EAAE,EAAE;IACV,6CAA6C;IAC7C,WAAW,EAAE,EAAE;CACP,CAAA;AAEV;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,oBAAoB,CAAC,MAAM,CAAA;AAEtE;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,YAAY,CAAA;AACtD,MAAM,CAAC,MAAM,gCAAgC,GAAG,iBAAiB,CAAA;AAEjE;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAA;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAA;AAC7C,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAE3C;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAA;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,GAAG,IAAI,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAErD;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,aAAa;IACb,iBAAiB;IACjB,iBAAiB;CACT,CAAA"}

package/dist/utils/errorHandling.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Error handling utilities for services
+ *
+ * Provides consistent error handling patterns across all services
+ * to reduce code duplication and improve maintainability.
+ *
+ * ## Usage Guidelines
+ *
+ * **For Services**: Use `handleServiceError()` - this provides consistent normalization
+ * and logging for service-layer errors. Errors are NOT sanitized (sanitizeLevel: false)
+ * because services log internally and need full error details for debugging.
+ *
+ * **For Hooks/UI**: Use `normalizeError()` directly with appropriate sanitization level.
+ * Hooks should sanitize errors before exposing them to UI components.
+ *
+ * @example Service usage:
+ * ```typescript
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   handleServiceError(error, 'AddressService', 'getAddress', { network, accountIndex })
+ * }
+ * ```
+ *
+ * @example Hook/UI usage:
+ * ```typescript
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   const normalized = normalizeError(error, true, { component: 'MyHook', operation: 'fetchData' })
+ *   setError(normalized.message)
+ * }
+ * ```
+ */
+/**
+ * Handle service errors with consistent normalization and logging
+ *
+ * **Use this in services** - provides consistent error handling with full error details
+ * (no sanitization) for internal logging and debugging.
+ *
+ * @param error - Error to handle
+ * @param component - Component/service name where error occurred
+ * @param operation - Operation name that failed
+ * @param context - Additional context for error
+ * @throws Normalized error
+ */
+export declare function handleServiceError(error: unknown, component: string, operation: string, context?: Record<string, unknown>): never;

package/dist/utils/errorHandling.js

@@ -0,0 +1,54 @@
+/**
+ * Error handling utilities for services
+ *
+ * Provides consistent error handling patterns across all services
+ * to reduce code duplication and improve maintainability.
+ *
+ * ## Usage Guidelines
+ *
+ * **For Services**: Use `handleServiceError()` - this provides consistent normalization
+ * and logging for service-layer errors. Errors are NOT sanitized (sanitizeLevel: false)
+ * because services log internally and need full error details for debugging.
+ *
+ * **For Hooks/UI**: Use `normalizeError()` directly with appropriate sanitization level.
+ * Hooks should sanitize errors before exposing them to UI components.
+ *
+ * @example Service usage:
+ * ```typescript
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   handleServiceError(error, 'AddressService', 'getAddress', { network, accountIndex })
+ * }
+ * ```
+ *
+ * @example Hook/UI usage:
+ * ```typescript
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   const normalized = normalizeError(error, true, { component: 'MyHook', operation: 'fetchData' })
+ *   setError(normalized.message)
+ * }
+ * ```
+ */
+import { normalizeError } from './errorUtils';
+import { logError } from './logger';
+/**
+ * Handle service errors with consistent normalization and logging
+ *
+ * **Use this in services** - provides consistent error handling with full error details
+ * (no sanitization) for internal logging and debugging.
+ *
+ * @param error - Error to handle
+ * @param component - Component/service name where error occurred
+ * @param operation - Operation name that failed
+ * @param context - Additional context for error
+ * @throws Normalized error
+ */
+export function handleServiceError(error, component, operation, context) {
+    const normalized = normalizeError(error, false, { component, operation, ...context });
+    logError(`[${component}] ${operation} failed:`, normalized);
+    throw normalized;
+}
+//# sourceMappingURL=errorHandling.js.map

package/dist/utils/errorHandling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandling.js","sourceRoot":"","sources":["../../src/utils/errorHandling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,SAAiB,EACjB,SAAiB,EACjB,OAAiC;IAEjC,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;IACrF,QAAQ,CAAC,IAAI,SAAS,KAAK,SAAS,UAAU,EAAE,UAAU,CAAC,CAAA;IAC3D,MAAM,UAAU,CAAA;AAClB,CAAC"}

package/dist/utils/errorUtils.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Error utility functions for consistent error handling
+ *
+ * ## Usage Guidelines
+ *
+ * **For Services**: Use `handleServiceError()` from `errorHandling.ts` - this provides
+ * consistent normalization and logging for service-layer errors. Errors are NOT sanitized
+ * (sanitizeLevel: false) because services log internally and need full error details.
+ *
+ * **For Hooks/UI**: Use `normalizeError()` directly with appropriate sanitization level.
+ * Hooks should sanitize errors before exposing them to UI components to prevent information leakage.
+ *
+ * @example Service usage (use handleServiceError instead):
+ * ```typescript
+ * import { handleServiceError } from './errorHandling'
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   handleServiceError(error, 'MyService', 'operationName', { context })
+ * }
+ * ```
+ *
+ * @example Hook/UI usage:
+ * ```typescript
+ * import { normalizeError } from './errorUtils'
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   const normalized = normalizeError(error, true, { component: 'MyHook', operation: 'fetchData' })
+ *   setError(normalized.message)
+ * }
+ * ```
+ */
+/**
+ * Sanitization levels for error messages
+ */
+export declare enum SanitizationLevel {
+    NONE = "none",// No sanitization (internal debugging only)
+    DEVELOPMENT = "dev",// Mask sensitive strings but show structure
+    PRODUCTION = "prod"
+}
+/**
+ * Sanitize error message to prevent information leakage
+ * Removes or masks sensitive information while preserving useful debugging info
+ *
+ * @param message - Error message to sanitize
+ * @param isDevelopment - Whether we're in development mode (less sanitization)
+ * @param context - Optional context about where the error occurred (for better sanitization)
+ * @returns Sanitized error message
+ */
+export declare function sanitizeErrorMessage(message: string, isDevelopment?: boolean, context?: {
+    operation?: string;
+    component?: string;
+}): string;
+/**
+ * Normalize error to Error instance
+ * Converts any error-like value to a proper Error object
+ * Always sanitizes the error message (with different levels) to prevent information leakage
+ *
+ * @param error - Error to normalize
+ * @param sanitizeLevel - Sanitization level or boolean (default: PRODUCTION in production, DEVELOPMENT in dev)
+ * @param context - Optional context about where the error occurred
+ * @returns Normalized Error instance
+ */
+export declare function normalizeError(error: unknown, sanitizeLevel?: SanitizationLevel | boolean, context?: {
+    operation?: string;
+    component?: string;
+    [key: string]: unknown;
+}): Error;
+/**
+ * Get error message from any error-like value
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Check if error is a specific type
+ */
+export declare function isErrorType(error: unknown, typeName: string): boolean;
+/**
+ * Create a standardized error with context
+ */
+export declare function createContextualError(message: string, context?: Record<string, unknown>): Error;
+/**
+ * Check if an error is an authentication error
+ * Used to prevent automatic retries when authentication fails
+ *
+ * @param error - Error to check
+ * @returns true if the error is an authentication error
+ */
+export declare function isAuthenticationError(error: unknown): boolean;