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

package/src/utils/schemas.ts

@@ -0,0 +1,190 @@
+/**
+ * Zod Schemas for Runtime Validation
+ * 
+ * Provides Zod schemas for all WDK types to replace manual if/else type guards.
+ * These schemas provide better error messages and are easier to maintain.
+ */
+
+import { z } from 'zod'
+
+/**
+ * Ethereum address schema (0x followed by 40 hex characters)
+ */
+export const ethereumAddressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, {
+  message: 'Must be a valid Ethereum address (0x followed by 40 hex characters)',
+})
+
+/**
+ * Spark address schema (Bech32 format: spark1/sparkt1/sparkrt1 followed by base32 characters)
+ */
+export const sparkAddressSchema = z.string().regex(/^spark(1|t1|rt1|test1)[a-z0-9]+$/, {
+  message: 'Must be a valid Spark address (spark1/sparkt1/sparkrt1 followed by base32 characters)',
+}).min(14).max(90)
+
+/**
+ * Address schema (Ethereum or Spark)
+ */
+export const addressSchema = z.union([ethereumAddressSchema, sparkAddressSchema])
+
+/**
+ * Network configuration schema
+ */
+export const networkConfigSchema = z.object({
+  chainId: z.number().int().positive(),
+  blockchain: z.string().min(1),
+  provider: z.string().min(1).optional(),
+  bundlerUrl: z.string().min(1).optional(),
+  paymasterUrl: z.string().min(1).optional(),
+  paymasterAddress: ethereumAddressSchema.optional(),
+  entryPointAddress: ethereumAddressSchema.optional(),
+  transferMaxFee: z.number().nonnegative().optional(),
+})
+
+/**
+ * Network configurations schema
+ */
+export const networkConfigsSchema = z.record(
+  z.string().regex(/^[a-zA-Z0-9_-]+$/, {
+    message: 'Network name must contain only alphanumeric characters, hyphens, and underscores',
+  }),
+  networkConfigSchema
+).refine((configs) => Object.keys(configs).length > 0, {
+  message: 'NetworkConfigs must contain at least one network',
+})
+
+/**
+ * Token configuration schema
+ */
+export const tokenConfigSchema = z.object({
+  symbol: z.string().min(1),
+  name: z.string().min(1),
+  decimals: z.number().int().min(0).max(18),
+  address: z.union([ethereumAddressSchema, z.null()]),
+})
+
+/**
+ * Network tokens schema
+ */
+export const networkTokensSchema = z.object({
+  native: tokenConfigSchema,
+  tokens: z.array(tokenConfigSchema),
+})
+
+/**
+ * Token configurations schema
+ */
+export const tokenConfigsSchema = z.record(
+  z.string().min(1),
+  networkTokensSchema
+).refine((configs) => Object.keys(configs).length > 0, {
+  message: 'TokenConfigs must contain at least one network',
+})
+
+/**
+ * Account index schema
+ */
+export const accountIndexSchema = z.number().int().nonnegative()
+
+/**
+ * Network name schema
+ */
+export const networkNameSchema = z.string().regex(/^[a-zA-Z0-9_-]+$/, {
+  message: 'Network name must contain only alphanumeric characters, hyphens, and underscores',
+}).min(1)
+
+/**
+ * Balance string schema (valid number string)
+ */
+export const balanceStringSchema = z.string().regex(/^-?\d+(\.\d+)?$/, {
+  message: 'Balance must be a valid number string',
+})
+
+/**
+ * Wallet addresses schema
+ * Maps network -> accountIndex -> address
+ */
+export const walletAddressesSchema = z.record(
+  networkNameSchema,
+  z.record(
+    z.string().transform((val) => {
+      const num = parseInt(val, 10)
+      if (isNaN(num) || num < 0) {
+        throw new Error('Account index must be a non-negative integer')
+      }
+      return num
+    }),
+    addressSchema
+  )
+)
+
+/**
+ * Wallet balances schema
+ * Maps network -> accountIndex -> tokenAddress -> balance
+ */
+export const walletBalancesSchema = z.record(
+  networkNameSchema,
+  z.record(
+    z.string().transform((val) => {
+      const num = parseInt(val, 10)
+      if (isNaN(num) || num < 0) {
+        throw new Error('Account index must be a non-negative integer')
+      }
+      return num
+    }),
+    z.record(z.string(), balanceStringSchema)
+  )
+)
+
+/**
+ * Balance loading states schema
+ * Maps "network-accountIndex-tokenAddress" -> boolean
+ */
+export const balanceLoadingStatesSchema = z.record(z.string(), z.boolean())
+
+/**
+ * Balance fetch result schema
+ */
+export const balanceFetchResultSchema = z.object({
+  success: z.boolean(),
+  network: networkNameSchema,
+  accountIndex: accountIndexSchema,
+  tokenAddress: z.union([ethereumAddressSchema, z.null()]),
+  balance: z.union([balanceStringSchema, z.null()]),
+  error: z.string().optional(),
+})
+
+/**
+ * Wallet schema
+ */
+export const walletSchema = z.object({
+  accountIndex: accountIndexSchema,
+  identifier: z.string().min(1),
+  name: z.string().min(1),
+  createdAt: z.number().int().nonnegative(),
+  updatedAt: z.number().int().nonnegative(),
+})
+
+/**
+ * Worklet response schemas for runtime validation
+ */
+export const workletResponseSchema = z.object({
+  result: z.string(),
+  error: z.string().optional(),
+})
+
+/**
+ * Balance response schema (numeric string)
+ */
+export const balanceResponseSchema = z.string().regex(/^\d+$/, {
+  message: 'Balance must be a numeric string',
+})
+
+/**
+ * Account method response schema (union of possible return types)
+ */
+export const accountMethodResponseSchema = z.union([
+  balanceResponseSchema,
+  z.string(), // For addresses
+  z.object({}).passthrough(), // For other responses (objects)
+])
+

package/src/utils/storeHelpers.ts

@@ -0,0 +1,236 @@
+/**
+ * Store helper utilities
+ * 
+ * Provides common patterns for accessing and validating store state
+ * to reduce code duplication across services.
+ */
+
+import type { HRPC } from '@spacesops/pear-wrk-wdk'
+
+import { getWorkletStore } from '../store/workletStore'
+import { getWalletStore } from '../store/walletStore'
+import { asExtendedHRPC } from '../types/hrpc'
+import type { WalletState } from '../store/walletStore'
+
+/**
+ * Require that worklet is initialized and return HRPC instance
+ * 
+ * @throws Error if worklet is not initialized
+ * @returns HRPC instance
+ * 
+ * @example
+ * ```typescript
+ * const hrpc = requireInitialized()
+ * await hrpc.callMethod(...)
+ * ```
+ */
+export function requireInitialized(): HRPC {
+  const state = getWorkletStore().getState()
+  if (!state.isInitialized || !state.hrpc) {
+    throw new Error('WDK not initialized')
+  }
+  return state.hrpc
+}
+
+/**
+ * Require that worklet is initialized and return extended HRPC instance
+ * 
+ * @throws Error if worklet is not initialized
+ * @returns Extended HRPC instance
+ * 
+ * @example
+ * ```typescript
+ * const hrpc = requireExtendedHRPC()
+ * await hrpc.initializeWDK(...)
+ * ```
+ */
+export function requireExtendedHRPC(): ReturnType<typeof asExtendedHRPC> {
+  const hrpc = requireInitialized()
+  return asExtendedHRPC(hrpc)
+}
+
+/**
+ * Check if worklet is initialized
+ * 
+ * @returns true if worklet is initialized, false otherwise
+ */
+export function isInitialized(): boolean {
+  const state = getWorkletStore().getState()
+  return state.isInitialized && state.hrpc !== null
+}
+
+/**
+ * Update balance in wallet state (helper for nested state updates)
+ * 
+ * @param prev - Previous wallet state
+ * @param walletId - Wallet identifier
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param tokenKey - Token key (address or 'native')
+ * @param balance - Balance value
+ * @returns Partial state update
+ */
+export function updateBalanceInState(
+  prev: WalletState,
+  walletId: string,
+  network: string,
+  accountIndex: number,
+  tokenKey: string,
+  balance: string
+): Partial<WalletState> {
+  const walletBalances = prev.balances[walletId] || {}
+  const networkBalances = walletBalances[network] || {}
+  const accountBalances = networkBalances[accountIndex] || {}
+  return {
+    balances: {
+      ...prev.balances,
+      [walletId]: {
+        ...walletBalances,
+        [network]: {
+          ...networkBalances,
+          [accountIndex]: {
+            ...accountBalances,
+            [tokenKey]: balance,
+          },
+        },
+      },
+    },
+  }
+}
+
+/**
+ * Update address in wallet state (helper for nested state updates)
+ * 
+ * @param prev - Previous wallet state
+ * @param walletId - Wallet identifier
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param address - Address value
+ * @returns Partial state update
+ */
+export function updateAddressInState(
+  prev: WalletState,
+  walletId: string,
+  network: string,
+  accountIndex: number,
+  address: string
+): Partial<WalletState> {
+  const walletAddresses = prev.addresses[walletId] || {}
+  const networkAddresses = walletAddresses[network] || {}
+  return {
+    addresses: {
+      ...prev.addresses,
+      [walletId]: {
+        ...walletAddresses,
+        [network]: {
+          ...networkAddresses,
+          [accountIndex]: address,
+        },
+      },
+    },
+  }
+}
+
+/**
+ * Resolve wallet identifier from parameter or store
+ * 
+ * This helper function standardizes the pattern for resolving walletId across the codebase.
+ * It checks the provided walletId parameter first, then falls back to activeWalletId from store,
+ * and finally to '__temporary__' if no wallet is active.
+ * 
+ * @param walletId - Optional wallet identifier parameter
+ * @returns Resolved wallet identifier (never null)
+ * 
+ * @example
+ * ```typescript
+ * const targetWalletId = resolveWalletId(walletId)
+ * // Use targetWalletId for operations
+ * ```
+ */
+export function resolveWalletId(walletId?: string): string {
+  if (walletId) {
+    return walletId
+  }
+  
+  const walletStore = getWalletStore()
+  const activeWalletId = walletStore.getState().activeWalletId
+  
+  return activeWalletId || '__temporary__'
+}
+
+/**
+ * Safely get nested property from an object
+ * 
+ * @param obj - Object to access
+ * @param path - Array of keys representing the path
+ * @param defaultValue - Default value if path doesn't exist
+ * @returns Value at path or default value
+ * 
+ * @example
+ * ```typescript
+ * const balance = getNestedState(state.balances, [walletId, network, accountIndex, tokenKey], null)
+ * ```
+ */
+export function getNestedState<T>(
+  obj: Record<string, unknown>,
+  path: (string | number)[],
+  defaultValue: T
+): T {
+  let current: unknown = obj
+  for (const key of path) {
+    if (current == null || typeof current !== 'object') {
+      return defaultValue
+    }
+    if (!(key in current)) {
+      return defaultValue
+    }
+    current = (current as Record<string | number, unknown>)[key]
+  }
+  return (current as T) ?? defaultValue
+}
+
+/**
+ * Update nested state structure (generic helper for deep state updates)
+ * 
+ * Creates a new nested object structure with the updated value at the specified path.
+ * All intermediate objects are shallow copied to maintain immutability.
+ * 
+ * @param prev - Previous state object
+ * @param path - Array of keys representing the path to update
+ * @param value - Value to set at the path
+ * @returns New state object with updated value
+ * 
+ * @example
+ * ```typescript
+ * const newState = updateNestedState(prev, ['balances', walletId, network, accountIndex, tokenKey], balance)
+ * ```
+ */
+export function updateNestedState<T extends Record<string, unknown>>(
+  prev: T,
+  path: (string | number)[],
+  value: unknown
+): Partial<T> {
+  if (path.length === 0) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      return { ...prev, ...(value as Partial<T>) }
+    }
+    return prev
+  }
+
+  const [firstKey, ...restPath] = path
+  const keyString = String(firstKey)
+  const currentValue = prev[keyString]
+  const currentValueObj = (typeof currentValue === 'object' && currentValue !== null && !Array.isArray(currentValue))
+    ? (currentValue as Record<string | number, unknown>)
+    : {}
+  const updatedValue = restPath.length > 0
+    ? updateNestedState(currentValueObj, restPath, value)
+    : value
+
+  return {
+    ...prev,
+    [keyString]: updatedValue,
+  } as Partial<T>
+}
+
+

package/src/utils/typeGuards.ts

@@ -0,0 +1,129 @@
+/**
+ * Runtime Type Guards
+ * 
+ * Provides runtime type checking for critical data paths to ensure type safety
+ * beyond TypeScript's compile-time checks.
+ * 
+ * NOTE: These type guards now use Zod schemas internally for validation.
+ * They are kept for backward compatibility but may be deprecated in the future.
+ */
+
+import {
+  networkConfigSchema,
+  networkConfigsSchema,
+  tokenConfigSchema,
+  tokenConfigsSchema,
+  walletAddressesSchema,
+  walletBalancesSchema,
+  ethereumAddressSchema,
+  sparkAddressSchema,
+  accountIndexSchema,
+  networkNameSchema,
+  balanceStringSchema,
+} from './schemas'
+import type {
+  NetworkConfig,
+  NetworkConfigs,
+  TokenConfig,
+  TokenConfigs,
+  WalletAddresses,
+  WalletBalances,
+} from '../types'
+
+/**
+ * Type guard to check if a value is a valid NetworkConfig
+ * Uses Zod schema internally for validation
+ */
+export function isNetworkConfig(value: unknown): value is NetworkConfig {
+  return networkConfigSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid NetworkConfigs
+ * Uses Zod schema internally for validation
+ */
+export function isNetworkConfigs(value: unknown): value is NetworkConfigs {
+  return networkConfigsSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid TokenConfig
+ * Uses Zod schema internally for validation
+ */
+export function isTokenConfig(value: unknown): value is TokenConfig {
+  return tokenConfigSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid TokenConfigs
+ * Uses Zod schema internally for validation
+ */
+export function isTokenConfigs(value: unknown): value is TokenConfigs {
+  return tokenConfigsSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid WalletAddresses structure
+ * Uses Zod schema internally for validation
+ */
+export function isWalletAddresses(value: unknown): value is WalletAddresses {
+  return walletAddressesSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid WalletBalances structure
+ * Uses Zod schema internally for validation
+ */
+export function isWalletBalances(value: unknown): value is WalletBalances {
+  return walletBalancesSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid Ethereum address
+ * Uses Zod schema internally for validation
+ */
+export function isEthereumAddress(value: unknown): value is string {
+  return ethereumAddressSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid Spark address (Bech32 format)
+ * Spark addresses start with "spark1" followed by Bech32-encoded characters
+ * Uses Zod schema internally for validation
+ */
+export function isSparkAddress(value: unknown): value is string {
+  return sparkAddressSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid address (Ethereum or Spark format)
+ */
+export function isValidAddress(value: unknown): value is string {
+  return isEthereumAddress(value) || isSparkAddress(value)
+}
+
+/**
+ * Type guard to check if a value is a valid account index
+ * Uses Zod schema internally for validation
+ */
+export function isValidAccountIndex(value: unknown): value is number {
+  return accountIndexSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid network name
+ * Uses Zod schema internally for validation
+ */
+export function isValidNetworkName(value: unknown): value is string {
+  return networkNameSchema.safeParse(value).success
+}
+
+/**
+ * Type guard to check if a value is a valid balance string
+ * Uses Zod schema internally for validation
+ */
+export function isValidBalanceString(value: unknown): value is string {
+  return balanceStringSchema.safeParse(value).success
+}
+
+