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

package/src/hooks/useWdkApp.ts

@@ -0,0 +1,78 @@
+/**
+ * useWdkApp Hook
+ *
+ * Hook to access WdkAppProvider context for app-level initialization state.
+ * Must be used within WdkAppProvider.
+ *
+ * Purpose: Check if the app is ready and get initialization status.
+ * - Use this to check: "Is the app ready? What's the initialization status?"
+ * - For wallet operations (addresses, account methods): Use useWallet()
+ * - For wallet lifecycle (create, load, import, delete): Use useWalletManager()
+ *
+ * @example
+ * Simple usage (most common):
+ * ```tsx
+ * import { AppStatus } from '@tetherto/wdk-react-native-core'
+ * 
+ * function MyComponent() {
+ *   const { status, isReady, activeWalletId, error } = useWdkApp()
+ *
+ *   if (isReady) {
+ *     return <AppContent walletId={activeWalletId} />
+ *   }
+ *
+ *   if (status === AppStatus.ERROR) {
+ *     return <ErrorScreen error={error} />
+ *   }
+ *
+ *   return <LoadingScreen />
+ * }
+ * ```
+ *
+ * @example
+ * Advanced usage (granular control):
+ * ```tsx
+ * function MyComponent() {
+ *   const { workletState, walletState, activeWalletId } = useWdkApp()
+ *
+ *   // Show different UI based on specific states
+ *   if (workletState.isReady && walletState.status === 'not_loaded') {
+ *     return <SelectWalletScreen />
+ *   }
+ *
+ *   if (workletState.error) {
+ *     return <WorkletErrorScreen error={workletState.error} />
+ *   }
+ *
+ *   if (walletState.error) {
+ *     return <WalletErrorScreen error={walletState.error} />
+ *   }
+ *
+ *   if (walletState.status === 'ready') {
+ *     return <AppContent walletId={activeWalletId} />
+ *   }
+ *
+ *   return <LoadingScreen />
+ * }
+ * ```
+ */
+
+import { useContext } from 'react'
+
+import { WdkAppContext } from '../provider/WdkAppProvider'
+import type { WdkAppContextValue } from '../provider/WdkAppProvider'
+
+/**
+ * Hook to access WdkAppProvider context
+ *
+ * @returns WdkApp context value with initialization state
+ * @throws Error if used outside WdkAppProvider
+ */
+export function useWdkApp(): WdkAppContextValue {
+  const context = useContext(WdkAppContext)
+  if (!context) {
+    throw new Error('useWdkApp must be used within WdkAppProvider')
+  }
+  return context
+}
+

package/src/hooks/useWorklet.ts

@@ -0,0 +1,109 @@
+import { useShallow } from 'zustand/react/shallow'
+
+import type { HRPC } from '@spacesops/pear-wrk-wdk'
+import type { WorkletStartResponse } from '@spacesops/pear-wrk-wdk/types/rpc'
+import type { Worklet } from '@spacesops/react-native-bare-kit'
+
+import { WorkletLifecycleService } from '../services/workletLifecycleService'
+import { getWorkletStore } from '../store/workletStore'
+import type { NetworkConfigs } from '../types'
+import type { WorkletStore } from '../store/workletStore'
+
+/**
+ * Hook to interact with the worklet
+ * 
+ * This is the main hook that components should use to access worklet functionality.
+ * 
+ * For wallet-specific operations (addresses, accounts), use `useWallet()` hook instead.
+ * 
+ * The worklet automatically starts when `WdkAppProvider` loads.
+ * 
+ * @example
+ * ```tsx
+ * const { hrpc, isInitialized, isLoading, initializeWDK, generateEntropyAndEncrypt, error } = useWorklet()
+ * 
+ * useEffect(() => {
+ *   if (isInitialized && !isLoading) {
+ *     // Worklet is already started by WdkAppProvider
+ *     const { encryptionKey, encryptedSeedBuffer } = await generateEntropyAndEncrypt(12)
+ *     await initializeWDK({ encryptionKey, encryptedSeed: encryptedSeedBuffer })
+ *   }
+ * }, [isInitialized, isLoading])
+ * ```
+ */
+export interface UseWorkletResult {
+  // State (reactive)
+  isWorkletStarted: boolean
+  isInitialized: boolean
+  isLoading: boolean
+  error: string | null
+  hrpc: HRPC | null
+  worklet: Worklet | null
+  workletStartResult: WorkletStartResponse | null
+  wdkInitResult: { status?: string | null } | null
+  encryptedSeed: string | null
+  encryptionKey: string | null
+  networkConfigs: NetworkConfigs | null
+  // Actions
+  initializeWDK: (options: { encryptionKey: string; encryptedSeed: string }) => Promise<void>
+  generateEntropyAndEncrypt: (wordCount?: 12 | 24) => Promise<{
+    encryptionKey: string
+    encryptedSeedBuffer: string
+    encryptedEntropyBuffer: string
+  }>
+  getMnemonicFromEntropy: (encryptedEntropy: string, encryptionKey: string) => Promise<{ mnemonic: string }>
+  getSeedAndEntropyFromMnemonic: (mnemonic: string) => Promise<{
+    encryptionKey: string
+    encryptedSeedBuffer: string
+    encryptedEntropyBuffer: string
+  }>
+  initializeWorklet: (options: {
+    encryptionKey: string
+    encryptedSeed: string
+    networkConfigs: NetworkConfigs
+  }) => Promise<void>
+  reset: () => void
+  clearError: () => void
+}
+
+export function useWorklet(): UseWorkletResult {
+  const store = getWorkletStore()
+
+  // Subscribe to state changes
+  const selector = useShallow((state: WorkletStore) => ({
+    isWorkletStarted: state.isWorkletStarted,
+    isInitialized: state.isInitialized,
+    isLoading: state.isLoading,
+    error: state.error,
+    hrpc: state.hrpc,
+    worklet: state.worklet,
+    workletStartResult: state.workletStartResult,
+    wdkInitResult: state.wdkInitResult,
+    encryptedSeed: state.encryptedSeed,
+    encryptionKey: state.encryptionKey,
+    networkConfigs: state.networkConfigs,
+  }))
+  const workletState = store(selector)
+
+  return {
+    isWorkletStarted: workletState.isWorkletStarted,
+    isInitialized: workletState.isInitialized,
+    isLoading: workletState.isLoading,
+    error: workletState.error,
+    hrpc: workletState.hrpc,
+    worklet: workletState.worklet,
+    workletStartResult: workletState.workletStartResult,
+    wdkInitResult: workletState.wdkInitResult,
+    encryptedSeed: workletState.encryptedSeed,
+    encryptionKey: workletState.encryptionKey,
+    networkConfigs: workletState.networkConfigs,
+    initializeWDK: WorkletLifecycleService.initializeWDK,
+    generateEntropyAndEncrypt: WorkletLifecycleService.generateEntropyAndEncrypt,
+    getMnemonicFromEntropy: WorkletLifecycleService.getMnemonicFromEntropy,
+    getSeedAndEntropyFromMnemonic: WorkletLifecycleService.getSeedAndEntropyFromMnemonic,
+    initializeWorklet: WorkletLifecycleService.initializeWorklet,
+    reset: WorkletLifecycleService.reset,
+    clearError: WorkletLifecycleService.clearError,
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * @tetherto/wdk-react-native-core
+ * 
+ * Core functionality for React Native wallets
+ * Provides wallet management, balance fetching, and worklet operations
+ */
+
+// Core Types (Network, Token, and Wallet types)
+export type {
+  NetworkConfig,
+  NetworkConfigs,
+  TokenConfig,
+  NetworkTokens,
+  TokenConfigs,
+  Wallet,
+  WalletAddresses,
+  WalletBalances,
+  BalanceLoadingStates,
+  BalanceFetchResult,
+  TokenConfigProvider,
+  TokenHelpers,
+  WalletStore,
+} from './types'
+
+// HRPC Type Extensions (for extending HRPC functionality)
+export type { ExtendedHRPC } from './types/hrpc'
+export { isExtendedHRPC, asExtendedHRPC } from './types/hrpc'
+
+// Provider (main entry point)
+export { WdkAppProvider } from './provider/WdkAppProvider'
+export type { WdkAppProviderProps, WdkAppContextValue } from './provider/WdkAppProvider'
+
+// Hooks (public API)
+export { useWorklet } from './hooks/useWorklet'
+export { useWallet } from './hooks/useWallet'
+export { useWdkApp } from './hooks/useWdkApp'
+
+export { useWalletManager } from './hooks/useWalletManager'
+export type { UseWalletManagerResult, WalletInfo } from './hooks/useWalletManager'
+export { useBalance, useBalancesForWallet, useBalancesForWallets, useRefreshBalance, balanceQueryKeys } from './hooks/useBalance'
+export type { AccountInfo } from './store/walletStore'
+
+// Validation Utilities (for validating configs before use)
+export { 
+  validateNetworkConfigs, 
+  validateTokenConfigs, 
+  validateBalanceRefreshInterval,
+  validateAccountIndex,
+  validateTokenAddress,
+} from './utils/validation'
+
+// Zod Schemas (for runtime validation)
+export {
+  networkConfigSchema,
+  networkConfigsSchema,
+  tokenConfigSchema,
+  tokenConfigsSchema,
+  walletAddressesSchema,
+  walletBalancesSchema,
+  accountIndexSchema,
+  networkNameSchema,
+  balanceStringSchema,
+  ethereumAddressSchema,
+  sparkAddressSchema,
+  addressSchema,
+} from './utils/schemas'
+
+// Type Guards (for runtime type checking)
+export { 
+  isNetworkConfigs, 
+  isTokenConfigs,
+  isEthereumAddress,
+  isValidAccountIndex,
+  isValidNetworkName,
+} from './utils/typeGuards'
+
+// Services
+export { WorkletLifecycleService } from './services/workletLifecycleService'
+export { AddressService } from './services/addressService'
+export { AccountService } from './services/accountService'
+export { BalanceService } from './services/balanceService'
+export { WalletSetupService } from './services/walletSetupService'
+export { WalletSwitchingService } from './services/walletSwitchingService'
+
+// Utility Functions
+export { validateMnemonic } from './utils/mnemonicUtils'
+export { convertBalanceToString, formatBalance, convertBigIntToString } from './utils/balanceUtils'
+export { normalizeError, getErrorMessage, isErrorType, createContextualError } from './utils/errorUtils'
+
+// Result Type (for error handling patterns)
+export type { Result } from './utils/result'
+export { ok, err, toResult, toResultSync } from './utils/result'
+
+// Initialization State Machine
+export { 
+  InitializationStatus, 
+  AppStatus,
+  isErrorStatus, 
+  isReadyStatus, 
+  isInProgressStatus,
+  isAppReadyStatus,
+  isAppInProgressStatus,
+  hasWorkletStarted,
+  canLoadWallet,
+  hasWorkletStartedApp,
+  canLoadWalletApp,
+  getStatusMessage,
+  getAppStatusMessage,
+  getWorkletStatus,
+  getCombinedStatus
+} from './utils/initializationState'
+