@tuwaio/nova-connect 1.0.0-fix-integrate-orbit-alpha.30.3d6b687 → 1.0.0-fix-test-alpha.1.1de2063

package/dist/providers/index.d.cts

@@ -1,35 +1,10 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
 import { ComponentPropsWithoutRef, ComponentType, ReactNode } from 'react';
-import { ToastContainer, toast, ToastPosition } from 'react-toastify';
 import { OrbitAdapter } from '@tuwaio/orbit-core';
 import { ISatelliteConnectStore, BaseWallet } from '@tuwaio/satellite-core';
 import { StoreApi } from 'zustand/index';
-
-/**
- * @description
- * This interface is intentionally left empty.
- * Other packages (@tuwaio/satellite-*) will use module
- * augmentation to add their specific wallet types here.
- */
-interface AllWallets {
-}
-/**
- * @description
- * This interface is intentionally left empty.
- * It will be augmented by satellite packages.
- */
-interface AllConnectors {
-}
-/**
- * Union type for all supported wallet types.
- * It's created from the values of the AllWallets interface.
- * e.g., { evm: EVMWallet, solana: SolanaWallet } -> EVMWallet | SolanaWallet
- */
-type Wallet = AllWallets[keyof AllWallets];
-/**
- * Union type for all supported connector types.
- */
-type Connector = AllConnectors[keyof AllConnectors];
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ToastContainer, toast, ToastPosition } from 'react-toastify';
 
 /**
  * Type definitions for NovaConnect component translations
@@ -128,14 +103,44 @@ type NovaConnectLabels = {
     impersonateAddressConnected: string;
 };
 
+/**
+ * @description
+ * This interface is intentionally left empty.
+ * Other packages (@tuwaio/satellite-*) will use module
+ * augmentation to add their specific wallet types here.
+ */
+interface AllWallets {
+}
+/**
+ * @description
+ * This interface is intentionally left empty.
+ * It will be augmented by satellite packages.
+ */
+interface AllConnectors {
+}
+/**
+ * Union type for all supported wallet types.
+ * It's created from the values of the AllWallets interface.
+ * e.g., { evm: EVMWallet, solana: SolanaWallet } -> EVMWallet | SolanaWallet
+ */
+type Wallet = AllWallets[keyof AllWallets];
+/**
+ * Union type for all supported connector types.
+ */
+type Connector = AllConnectors[keyof AllConnectors];
+
 type ButtonTxStatus = 'idle' | 'loading' | 'succeed' | 'failed' | 'replaced';
 type ConnectContentType = 'network' | 'connectors' | 'about' | 'getWallet' | 'connecting' | 'impersonate';
 type ConnectedContentType = 'main' | 'transactions' | 'chains';
-interface NovaConnectProviderProps$1 {
+interface NovaConnectProviderProps {
     store: StoreApi<ISatelliteConnectStore<Connector, Wallet>>;
     children: React.ReactNode;
     labels?: Partial<NovaConnectLabels>;
 }
+interface WalletBalance {
+    value: string;
+    symbol: string;
+}
 interface NovaConnectProviderType {
     activeWallet: BaseWallet | undefined;
     walletConnectionError: string | undefined;
@@ -162,6 +167,186 @@ interface NovaConnectProviderType {
     impersonatedAddress: string;
     setImpersonatedAddress: (value: string) => void;
 }
+declare class NovaConnectProviderError extends Error {
+    constructor(message?: string);
+}
+declare const NovaConnectProviderContext: React$1.Context<NovaConnectProviderType | undefined>;
+/**
+ * Hook to access NovaConnect context
+ *
+ * @throws {NovaConnectProviderError} When used outside of NovaConnectProvider
+ * @returns {NovaConnectProviderType} The NovaConnect context value
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { isConnected, handleConnectButtonClick } = useNovaConnect();
+ *
+ *   return (
+ *     <button onClick={handleConnectButtonClick}>
+ *       {isConnected ? 'Connected' : 'Connect Wallet'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useNovaConnect: () => NovaConnectProviderType;
+/**
+ * Hook to check if NovaConnect context is available
+ *
+ * @returns {boolean} True if context is available, false otherwise
+ *
+ * @example
+ * ```typescript
+ * function ConditionalComponent() {
+ *   const hasContext = useHasNovaConnectContext();
+ *
+ *   if (!hasContext) {
+ *     return <div>NovaConnect provider not found</div>;
+ *   }
+ *
+ *   return <ConnectedComponent />;
+ * }
+ * ```
+ */
+declare const useHasNovaConnectContext: () => boolean;
+/**
+ * Optional hook that returns null if provider is not available
+ *
+ * @returns {NovaConnectProviderType | null} Context value or null if not available
+ *
+ * @example
+ * ```typescript
+ * function OptionalComponent() {
+ *   const context = useNovaConnectOptional();
+ *
+ *   if (!context) {
+ *     return <div>No wallet provider available</div>;
+ *   }
+ *
+ *   return <div>Connected: {context.isConnected}</div>;
+ * }
+ * ```
+ */
+declare const useNovaConnectOptional: () => NovaConnectProviderType | null;
+
+interface WalletNameAndAvatarData {
+    /** The resolved name from the Name Service (e.g., ENS, like "alice.eth"), or null if not found. */
+    ensName: string | null;
+    /** The URL of the avatar associated with the name, or null if not found. */
+    ensAvatar: string | null;
+    /** True while the name service data is being fetched. */
+    isLoading: boolean;
+    /** A truncated version of the name for display, or the abbreviated address if no name. */
+    ensNameAbbreviated: string | undefined;
+    /** Error message if the name resolution failed. */
+    error: string | null;
+    /** Function to retry the name resolution manually. */
+    retry: () => void;
+}
+interface UseGetWalletNameAndAvatarOptions extends Pick<NovaConnectProviderProps, 'store'>, Pick<NovaConnectProviderType, 'activeWallet'> {
+    /** Number of characters to show on each side when abbreviating (default: 12) */
+    abbreviateSymbols?: number;
+    /** Maximum length before abbreviation is applied (default: 30) */
+    maxNameLength?: number;
+    /** Whether to automatically retry on failure (default: false) */
+    autoRetry?: boolean;
+    /** Retry delay in milliseconds (default: 3000) */
+    retryDelay?: number;
+}
+/**
+ * A custom hook to fetch the Name Service (e.g., ENS) name and avatar
+ * for the currently active wallet.
+ *
+ * This hook automatically detects the active wallet and its corresponding
+ * adapter via the `useSatelliteConnectStore` and attempts to resolve the
+ * wallet address to a human-readable name and avatar.
+ *
+ * @param options Configuration options for the hook
+ * @returns An object containing the resolved name, avatar, loading state, and utility functions
+ *
+ * @example
+ * ```typescript
+ * import { useGetWalletNameAndAvatar } from './useGetWalletNameAndAvatar';
+ *
+ * function DisplayWalletInfo() {
+ *   const { ensName, ensAvatar, isLoading, ensNameAbbreviated, error, retry } = useGetWalletNameAndAvatar({
+ *     abbreviateSymbols: 8,
+ *     maxNameLength: 25
+ *   });
+ *
+ *   if (isLoading) {
+ *     return <div>Resolving name...</div>;
+ *   }
+ *
+ *   if (error) {
+ *     return <div>Error: {error} <button onClick={retry}>Retry</button></div>;
+ *   }
+ *
+ *   return (
+ *     <div className="wallet-info">
+ *       {ensAvatar && <img src={ensAvatar} alt="Wallet Avatar" />}
+ *       <p title={ensName || ''}>{ensNameAbbreviated || 'No Name Found'}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useGetWalletNameAndAvatar(options: UseGetWalletNameAndAvatarOptions): WalletNameAndAvatarData;
+
+/**
+ * @interface NativeBalanceResult
+ * Represents the native token balance returned by the adapter.
+ * The value is already formatted for human readability.
+ * @property {string} value The native token balance formatted to standard decimals (e.g., "1.5").
+ * @property {string} symbol The symbol of the native token (e.g., "ETH").
+ */
+interface NativeBalanceResult {
+    value: string;
+    symbol: string;
+}
+type NativeBalanceState = NativeBalanceResult | null;
+/**
+ * @interface NativeBalanceData
+ * The object returned by the useWalletNativeBalance hook.
+ * @property {NativeBalanceState} balance The native token balance and symbol, or null.
+ * @property {boolean} isLoading True while the balance is being fetched for the current wallet/chain combination.
+ * @property {() => void} refetch Function to manually trigger a balance refresh.
+ */
+interface NativeBalanceData {
+    balance: NativeBalanceState;
+    isLoading: boolean;
+    refetch: () => void;
+}
+/**
+ * Custom hook to fetch the native token balance for the currently connected wallet
+ * on the active chain. It includes a local cache layer to prevent redundant network calls
+ * when switching between components or on re-renders for the same wallet/chain.
+ *
+ * @returns {NativeBalanceData} An object containing the balance data and loading state.
+ *
+ * @example
+ * ```typescript
+ * import { useWalletNativeBalance } from './useWalletNativeBalance';
+ *
+ * function NativeTokenDisplay() {
+ *   const { balance, isLoading, refetch } = useWalletNativeBalance();
+ *
+ *   if (isLoading) {
+ *     return <p>Loading balance...</p>;
+ *   }
+ *
+ *   // Display the formatted balance and symbol
+ *   return (
+ *     <div>
+ *       <p>Balance: {balance ? `${balance.value} ${balance.symbol}` : '0.00'}</p>
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useWalletNativeBalance({ store, activeWallet, }: Pick<NovaConnectProviderProps, 'store'> & Pick<NovaConnectProviderType, 'activeWallet'>): NativeBalanceData;
 
 type CustomIconProps = {
     isCopied: boolean;
@@ -302,7 +487,7 @@ type ErrorsProviderCustomization = {
         errorType: 'wallet' | 'switch' | null;
     }) => string | null;
 };
-interface ErrorsProviderProps extends Pick<NovaConnectProviderProps$1, 'store'> {
+interface ErrorsProviderProps extends Pick<NovaConnectProviderProps, 'store'> {
     /** Custom container ID for toast notifications */
     containerId?: string;
     /** Custom position for toast notifications */
@@ -445,7 +630,7 @@ type NovaConnectProviderCustomization = {
 /**
  * Extended props for NovaConnectProvider with full customization capabilities
  */
-interface NovaConnectProviderProps extends NovaConnectProviderProps$1 {
+interface NovaConnectProviderPropsWithCustomization extends NovaConnectProviderProps {
     /** Comprehensive customization options for the provider and its sub-components */
     customization?: NovaConnectProviderCustomization;
 }
@@ -498,9 +683,9 @@ interface NovaConnectProviderProps extends NovaConnectProviderProps$1 {
  *
  * @param props - Provider configuration and customization options
  */
-declare function NovaConnectProvider({ labels, store, children, customization }: NovaConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function NovaConnectProvider({ labels, store, children, customization, }: NovaConnectProviderPropsWithCustomization): react_jsx_runtime.JSX.Element;
 declare namespace NovaConnectProvider {
     var displayName: string;
 }
 
-export { ErrorsProvider, type ErrorsProviderCustomization, type ErrorsProviderProps, NovaConnectLabelsProvider, NovaConnectProvider, type NovaConnectProviderCustomization, type NovaConnectProviderProps };
+export { type ButtonTxStatus, type ConnectContentType, type ConnectedContentType, ErrorsProvider, type ErrorsProviderCustomization, type ErrorsProviderProps, type NativeBalanceResult, NovaConnectLabelsProvider, NovaConnectProvider, NovaConnectProviderContext, type NovaConnectProviderCustomization, NovaConnectProviderError, type NovaConnectProviderProps, type NovaConnectProviderPropsWithCustomization, type NovaConnectProviderType, type WalletBalance, type WalletNameAndAvatarData, useGetWalletNameAndAvatar, useHasNovaConnectContext, useNovaConnect, useNovaConnectOptional, useWalletNativeBalance };

package/dist/providers/index.d.ts

@@ -1,35 +1,10 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
 import { ComponentPropsWithoutRef, ComponentType, ReactNode } from 'react';
-import { ToastContainer, toast, ToastPosition } from 'react-toastify';
 import { OrbitAdapter } from '@tuwaio/orbit-core';
 import { ISatelliteConnectStore, BaseWallet } from '@tuwaio/satellite-core';
 import { StoreApi } from 'zustand/index';
-
-/**
- * @description
- * This interface is intentionally left empty.
- * Other packages (@tuwaio/satellite-*) will use module
- * augmentation to add their specific wallet types here.
- */
-interface AllWallets {
-}
-/**
- * @description
- * This interface is intentionally left empty.
- * It will be augmented by satellite packages.
- */
-interface AllConnectors {
-}
-/**
- * Union type for all supported wallet types.
- * It's created from the values of the AllWallets interface.
- * e.g., { evm: EVMWallet, solana: SolanaWallet } -> EVMWallet | SolanaWallet
- */
-type Wallet = AllWallets[keyof AllWallets];
-/**
- * Union type for all supported connector types.
- */
-type Connector = AllConnectors[keyof AllConnectors];
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ToastContainer, toast, ToastPosition } from 'react-toastify';
 
 /**
  * Type definitions for NovaConnect component translations
@@ -128,14 +103,44 @@ type NovaConnectLabels = {
     impersonateAddressConnected: string;
 };
 
+/**
+ * @description
+ * This interface is intentionally left empty.
+ * Other packages (@tuwaio/satellite-*) will use module
+ * augmentation to add their specific wallet types here.
+ */
+interface AllWallets {
+}
+/**
+ * @description
+ * This interface is intentionally left empty.
+ * It will be augmented by satellite packages.
+ */
+interface AllConnectors {
+}
+/**
+ * Union type for all supported wallet types.
+ * It's created from the values of the AllWallets interface.
+ * e.g., { evm: EVMWallet, solana: SolanaWallet } -> EVMWallet | SolanaWallet
+ */
+type Wallet = AllWallets[keyof AllWallets];
+/**
+ * Union type for all supported connector types.
+ */
+type Connector = AllConnectors[keyof AllConnectors];
+
 type ButtonTxStatus = 'idle' | 'loading' | 'succeed' | 'failed' | 'replaced';
 type ConnectContentType = 'network' | 'connectors' | 'about' | 'getWallet' | 'connecting' | 'impersonate';
 type ConnectedContentType = 'main' | 'transactions' | 'chains';
-interface NovaConnectProviderProps$1 {
+interface NovaConnectProviderProps {
     store: StoreApi<ISatelliteConnectStore<Connector, Wallet>>;
     children: React.ReactNode;
     labels?: Partial<NovaConnectLabels>;
 }
+interface WalletBalance {
+    value: string;
+    symbol: string;
+}
 interface NovaConnectProviderType {
     activeWallet: BaseWallet | undefined;
     walletConnectionError: string | undefined;
@@ -162,6 +167,186 @@ interface NovaConnectProviderType {
     impersonatedAddress: string;
     setImpersonatedAddress: (value: string) => void;
 }
+declare class NovaConnectProviderError extends Error {
+    constructor(message?: string);
+}
+declare const NovaConnectProviderContext: React$1.Context<NovaConnectProviderType | undefined>;
+/**
+ * Hook to access NovaConnect context
+ *
+ * @throws {NovaConnectProviderError} When used outside of NovaConnectProvider
+ * @returns {NovaConnectProviderType} The NovaConnect context value
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { isConnected, handleConnectButtonClick } = useNovaConnect();
+ *
+ *   return (
+ *     <button onClick={handleConnectButtonClick}>
+ *       {isConnected ? 'Connected' : 'Connect Wallet'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useNovaConnect: () => NovaConnectProviderType;
+/**
+ * Hook to check if NovaConnect context is available
+ *
+ * @returns {boolean} True if context is available, false otherwise
+ *
+ * @example
+ * ```typescript
+ * function ConditionalComponent() {
+ *   const hasContext = useHasNovaConnectContext();
+ *
+ *   if (!hasContext) {
+ *     return <div>NovaConnect provider not found</div>;
+ *   }
+ *
+ *   return <ConnectedComponent />;
+ * }
+ * ```
+ */
+declare const useHasNovaConnectContext: () => boolean;
+/**
+ * Optional hook that returns null if provider is not available
+ *
+ * @returns {NovaConnectProviderType | null} Context value or null if not available
+ *
+ * @example
+ * ```typescript
+ * function OptionalComponent() {
+ *   const context = useNovaConnectOptional();
+ *
+ *   if (!context) {
+ *     return <div>No wallet provider available</div>;
+ *   }
+ *
+ *   return <div>Connected: {context.isConnected}</div>;
+ * }
+ * ```
+ */
+declare const useNovaConnectOptional: () => NovaConnectProviderType | null;
+
+interface WalletNameAndAvatarData {
+    /** The resolved name from the Name Service (e.g., ENS, like "alice.eth"), or null if not found. */
+    ensName: string | null;
+    /** The URL of the avatar associated with the name, or null if not found. */
+    ensAvatar: string | null;
+    /** True while the name service data is being fetched. */
+    isLoading: boolean;
+    /** A truncated version of the name for display, or the abbreviated address if no name. */
+    ensNameAbbreviated: string | undefined;
+    /** Error message if the name resolution failed. */
+    error: string | null;
+    /** Function to retry the name resolution manually. */
+    retry: () => void;
+}
+interface UseGetWalletNameAndAvatarOptions extends Pick<NovaConnectProviderProps, 'store'>, Pick<NovaConnectProviderType, 'activeWallet'> {
+    /** Number of characters to show on each side when abbreviating (default: 12) */
+    abbreviateSymbols?: number;
+    /** Maximum length before abbreviation is applied (default: 30) */
+    maxNameLength?: number;
+    /** Whether to automatically retry on failure (default: false) */
+    autoRetry?: boolean;
+    /** Retry delay in milliseconds (default: 3000) */
+    retryDelay?: number;
+}
+/**
+ * A custom hook to fetch the Name Service (e.g., ENS) name and avatar
+ * for the currently active wallet.
+ *
+ * This hook automatically detects the active wallet and its corresponding
+ * adapter via the `useSatelliteConnectStore` and attempts to resolve the
+ * wallet address to a human-readable name and avatar.
+ *
+ * @param options Configuration options for the hook
+ * @returns An object containing the resolved name, avatar, loading state, and utility functions
+ *
+ * @example
+ * ```typescript
+ * import { useGetWalletNameAndAvatar } from './useGetWalletNameAndAvatar';
+ *
+ * function DisplayWalletInfo() {
+ *   const { ensName, ensAvatar, isLoading, ensNameAbbreviated, error, retry } = useGetWalletNameAndAvatar({
+ *     abbreviateSymbols: 8,
+ *     maxNameLength: 25
+ *   });
+ *
+ *   if (isLoading) {
+ *     return <div>Resolving name...</div>;
+ *   }
+ *
+ *   if (error) {
+ *     return <div>Error: {error} <button onClick={retry}>Retry</button></div>;
+ *   }
+ *
+ *   return (
+ *     <div className="wallet-info">
+ *       {ensAvatar && <img src={ensAvatar} alt="Wallet Avatar" />}
+ *       <p title={ensName || ''}>{ensNameAbbreviated || 'No Name Found'}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useGetWalletNameAndAvatar(options: UseGetWalletNameAndAvatarOptions): WalletNameAndAvatarData;
+
+/**
+ * @interface NativeBalanceResult
+ * Represents the native token balance returned by the adapter.
+ * The value is already formatted for human readability.
+ * @property {string} value The native token balance formatted to standard decimals (e.g., "1.5").
+ * @property {string} symbol The symbol of the native token (e.g., "ETH").
+ */
+interface NativeBalanceResult {
+    value: string;
+    symbol: string;
+}
+type NativeBalanceState = NativeBalanceResult | null;
+/**
+ * @interface NativeBalanceData
+ * The object returned by the useWalletNativeBalance hook.
+ * @property {NativeBalanceState} balance The native token balance and symbol, or null.
+ * @property {boolean} isLoading True while the balance is being fetched for the current wallet/chain combination.
+ * @property {() => void} refetch Function to manually trigger a balance refresh.
+ */
+interface NativeBalanceData {
+    balance: NativeBalanceState;
+    isLoading: boolean;
+    refetch: () => void;
+}
+/**
+ * Custom hook to fetch the native token balance for the currently connected wallet
+ * on the active chain. It includes a local cache layer to prevent redundant network calls
+ * when switching between components or on re-renders for the same wallet/chain.
+ *
+ * @returns {NativeBalanceData} An object containing the balance data and loading state.
+ *
+ * @example
+ * ```typescript
+ * import { useWalletNativeBalance } from './useWalletNativeBalance';
+ *
+ * function NativeTokenDisplay() {
+ *   const { balance, isLoading, refetch } = useWalletNativeBalance();
+ *
+ *   if (isLoading) {
+ *     return <p>Loading balance...</p>;
+ *   }
+ *
+ *   // Display the formatted balance and symbol
+ *   return (
+ *     <div>
+ *       <p>Balance: {balance ? `${balance.value} ${balance.symbol}` : '0.00'}</p>
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useWalletNativeBalance({ store, activeWallet, }: Pick<NovaConnectProviderProps, 'store'> & Pick<NovaConnectProviderType, 'activeWallet'>): NativeBalanceData;
 
 type CustomIconProps = {
     isCopied: boolean;
@@ -302,7 +487,7 @@ type ErrorsProviderCustomization = {
         errorType: 'wallet' | 'switch' | null;
     }) => string | null;
 };
-interface ErrorsProviderProps extends Pick<NovaConnectProviderProps$1, 'store'> {
+interface ErrorsProviderProps extends Pick<NovaConnectProviderProps, 'store'> {
     /** Custom container ID for toast notifications */
     containerId?: string;
     /** Custom position for toast notifications */
@@ -445,7 +630,7 @@ type NovaConnectProviderCustomization = {
 /**
  * Extended props for NovaConnectProvider with full customization capabilities
  */
-interface NovaConnectProviderProps extends NovaConnectProviderProps$1 {
+interface NovaConnectProviderPropsWithCustomization extends NovaConnectProviderProps {
     /** Comprehensive customization options for the provider and its sub-components */
     customization?: NovaConnectProviderCustomization;
 }
@@ -498,9 +683,9 @@ interface NovaConnectProviderProps extends NovaConnectProviderProps$1 {
  *
  * @param props - Provider configuration and customization options
  */
-declare function NovaConnectProvider({ labels, store, children, customization }: NovaConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function NovaConnectProvider({ labels, store, children, customization, }: NovaConnectProviderPropsWithCustomization): react_jsx_runtime.JSX.Element;
 declare namespace NovaConnectProvider {
     var displayName: string;
 }
 
-export { ErrorsProvider, type ErrorsProviderCustomization, type ErrorsProviderProps, NovaConnectLabelsProvider, NovaConnectProvider, type NovaConnectProviderCustomization, type NovaConnectProviderProps };
+export { type ButtonTxStatus, type ConnectContentType, type ConnectedContentType, ErrorsProvider, type ErrorsProviderCustomization, type ErrorsProviderProps, type NativeBalanceResult, NovaConnectLabelsProvider, NovaConnectProvider, NovaConnectProviderContext, type NovaConnectProviderCustomization, NovaConnectProviderError, type NovaConnectProviderProps, type NovaConnectProviderPropsWithCustomization, type NovaConnectProviderType, type WalletBalance, type WalletNameAndAvatarData, useGetWalletNameAndAvatar, useHasNovaConnectContext, useNovaConnect, useNovaConnectOptional, useWalletNativeBalance };