@lukso/transaction-view-headless 0.2.2-dev.a8c9315

package/src/composables/use-transaction-view.ts

@@ -0,0 +1,309 @@
+import type {
+  AddressIdentityCache,
+  DataKey,
+  DecoderResult,
+  EnhancedInfo,
+} from '@lukso/transaction-decoder'
+import {
+  fetchMultipleAddresses,
+  getGraphQLEndpoint,
+} from '@lukso/transaction-decoder'
+import type { Chain } from 'viem'
+import { getGlobalLoader, ViewLoadingError } from '../registry/view-loader'
+import { getGlobalRegistry } from '../registry/view-registry'
+import type {
+  ViewMatch,
+  ViewMatchOptions,
+  ViewRegistry,
+} from '../types/view-matching'
+
+/**
+ * Options for the transaction view composable
+ */
+export interface UseTransactionViewOptions extends Partial<ViewMatchOptions> {
+  /** Custom registry to use instead of global */
+  registry?: ViewRegistry
+  /** Whether to automatically load the best matching component */
+  autoLoad?: boolean
+  /** Fallback view ID to use if no matches found */
+  fallbackViewId?: string
+  /** Whether to resolve addresses for this view (uses transaction.addresses array) */
+  resolve?: boolean
+  /** Chain for address resolution (required if resolve: true) */
+  chain?: Chain
+  /** Optional cache adapter for address resolution */
+  addressCache?: AddressIdentityCache
+}
+
+/**
+ * Result from the transaction view composable
+ */
+export interface UseTransactionViewResult {
+  /** All matching views sorted by score */
+  matches: ViewMatch[]
+  /** The best matching view (highest score) */
+  bestMatch: ViewMatch | null
+  /** The loaded component (if autoLoad is true) */
+  component: any
+  /** Loading state */
+  isLoading: boolean
+  /** Error state */
+  error: ViewLoadingError | null
+  /** Address resolution loading state */
+  isResolvingAddresses: boolean
+  /** Resolved address data map (if resolve: true) */
+  resolvedAddresses: Record<string, EnhancedInfo>
+  /** Function to manually load a specific match */
+  loadMatch: (match: ViewMatch) => Promise<any>
+  /** Function to load the best match */
+  loadBestMatch: () => Promise<any>
+  /** Function to refresh matches (useful if registry changes) */
+  refreshMatches: () => void
+  /** Function to manually trigger address resolution */
+  resolveAddresses: () => Promise<void>
+}
+
+/**
+ * Framework-agnostic composable for finding and loading transaction views
+ *
+ * This is the main entry point for the view system. It handles:
+ * - Finding matching views based on transaction data
+ * - Loading components using the appropriate strategy
+ * - Providing a consistent API across all frameworks
+ *
+ * Usage in Vue:
+ * ```ts
+ * const { bestMatch, component, isLoading, resolvedAddresses } = useTransactionView(transaction, {
+ *   framework: 'lit',
+ *   autoLoad: true,
+ *   resolve: true,           // Auto-resolve addresses from transaction.addresses array
+ *   chain: lukso,           // Required for address resolution
+ *   addressCache: cache     // Optional cache adapter
+ * })
+ * ```
+ *
+ * Usage in React/React Native:
+ * ```ts
+ * const { bestMatch, component, loadBestMatch, resolvedAddresses, isResolvingAddresses } = useTransactionView(transaction, {
+ *   framework: 'react-native',
+ *   resolve: true,
+ *   chain: luksoTestnet,
+ *   addressCache: myCache
+ * })
+ * useEffect(() => {
+ *   loadBestMatch()
+ * }, [transaction])
+ * ```
+ */
+export function useTransactionView(
+  transaction: DecoderResult,
+  options: UseTransactionViewOptions
+): UseTransactionViewResult {
+  const {
+    registry = getGlobalRegistry(),
+    autoLoad = false,
+    fallbackViewId,
+    framework = 'lit',
+    minScore = 0,
+    maxMatches,
+    includeFrameworkConfig = true,
+    resolve = false,
+    chain,
+    addressCache,
+  } = options
+
+  const loader = getGlobalLoader()
+
+  // Internal state (framework-specific implementations will handle reactivity)
+  let matches: ViewMatch[] = []
+  let bestMatch: ViewMatch | null = null
+  let component: any = null
+  let isLoading = false
+  let error: ViewLoadingError | null = null
+  let isResolvingAddresses = false
+  let resolvedAddresses: Record<string, EnhancedInfo> = {}
+
+  // Find matching views
+  const refreshMatches = () => {
+    const matchOptions: ViewMatchOptions = {
+      framework: framework as any,
+      minScore,
+      maxMatches,
+      includeFrameworkConfig,
+    }
+
+    matches = registry.findMatches(transaction, matchOptions)
+    bestMatch = matches[0] || null
+
+    // If no matches and we have a fallback, try to get it
+    if (!bestMatch && fallbackViewId) {
+      const fallbackView = registry.getView(fallbackViewId)
+      if (fallbackView && fallbackView.frameworks[framework]) {
+        bestMatch = {
+          view: fallbackView,
+          score: 0,
+          matchedCriteria: [],
+          frameworkConfig: includeFrameworkConfig
+            ? fallbackView.frameworks[framework]
+            : undefined,
+        }
+      }
+    }
+  }
+
+  // Load a specific match
+  const loadMatch = async (match: ViewMatch): Promise<any> => {
+    if (!match.frameworkConfig) {
+      throw new ViewLoadingError(
+        `No framework config for view "${match.view.id}" and framework "${framework}"`,
+        { type: 'dynamic-import', path: '' },
+        {} as any
+      )
+    }
+
+    isLoading = true
+    error = null
+
+    try {
+      const loadedComponent = await loader.loadFromMatch(match)
+      component = loadedComponent
+      return loadedComponent
+    } catch (err) {
+      error =
+        err instanceof ViewLoadingError
+          ? err
+          : new ViewLoadingError(
+              'Unknown loading error',
+              match.frameworkConfig.loader,
+              match.frameworkConfig,
+              err instanceof Error ? err : new Error(String(err))
+            )
+      throw error
+    } finally {
+      isLoading = false
+    }
+  }
+
+  // Load the best match
+  const loadBestMatch = async (): Promise<any> => {
+    if (!bestMatch) {
+      throw new Error('No matching view found for transaction')
+    }
+    return loadMatch(bestMatch)
+  }
+
+  // Address resolution function
+  const resolveAddressesFunc = async (): Promise<void> => {
+    if (
+      !resolve ||
+      !transaction.addresses ||
+      transaction.addresses.length === 0
+    ) {
+      return
+    }
+
+    if (!chain) {
+      console.warn(
+        'Address resolution requested but no chain provided. Pass chain option to resolve addresses.'
+      )
+      return
+    }
+
+    isResolvingAddresses = true
+
+    try {
+      // Convert addresses to DataKey format
+      const dataKeys: DataKey[] = transaction.addresses
+        .filter((addr) => addr && typeof addr === 'string')
+        .map((addr) => addr.toLowerCase() as DataKey)
+
+      if (dataKeys.length === 0) {
+        return
+      }
+
+      // Get GraphQL endpoint based on chain
+      const endpoint = getGraphQLEndpoint(chain)
+
+      // Use raw fetchMultipleAddresses with optional cache
+      const resolvedMap = await fetchMultipleAddresses(
+        dataKeys,
+        endpoint,
+        addressCache
+      )
+
+      // Convert Map to Record for easier consumption
+      const resolved: Record<string, EnhancedInfo> = {}
+      resolvedMap.forEach((enhancedInfo, dataKey) => {
+        resolved[dataKey] = enhancedInfo
+      })
+
+      resolvedAddresses = resolved
+    } catch (err) {
+      console.error('Address resolution failed:', err)
+    } finally {
+      isResolvingAddresses = false
+    }
+  }
+
+  // Initialize
+  refreshMatches()
+
+  // Auto-resolve addresses if requested
+  if (resolve) {
+    resolveAddressesFunc().catch((err) => {
+      console.error('Auto address resolution failed:', err)
+    })
+  }
+
+  // Auto-load if requested
+  if (autoLoad && bestMatch) {
+    loadBestMatch().catch((err) => {
+      console.error('Auto-load failed:', err)
+    })
+  }
+
+  return {
+    matches,
+    bestMatch,
+    component,
+    isLoading,
+    error,
+    isResolvingAddresses,
+    resolvedAddresses,
+    loadMatch,
+    loadBestMatch,
+    refreshMatches,
+    resolveAddresses: resolveAddressesFunc,
+  }
+}
+
+/**
+ * Simplified version that just returns the best matching view without loading
+ */
+export function findBestTransactionView(
+  transaction: DecoderResult,
+  framework: 'lit' | 'rn',
+  registry?: ViewRegistry
+): ViewMatch | null {
+  const reg = registry || getGlobalRegistry()
+  const matches = reg.findMatches(transaction, {
+    framework,
+    includeFrameworkConfig: true,
+  })
+  return matches.length > 0 ? matches[0] : null
+}
+
+/**
+ * Get all matching views without loading
+ */
+export function findAllTransactionViews(
+  transaction: DecoderResult,
+  framework: 'lit' | 'rn',
+  registry?: ViewRegistry
+): ViewMatch[] {
+  const reg = registry || getGlobalRegistry()
+  return reg.findMatches(transaction, {
+    framework,
+    includeFrameworkConfig: true,
+  })
+}

package/src/config/lukso-config.ts

@@ -0,0 +1,171 @@
+/**
+ * Framework-agnostic LUKSO configuration system
+ * Works across Vue, React, and Lit components
+ */
+
+import { signal } from '@preact/signals-core'
+import type { Chain } from 'viem'
+
+export interface LuksoConfig {
+  /** Chain ID for LUKSO network (42 for mainnet, 4201 for testnet) */
+  chainId: number
+  /** RPC endpoint for the LUKSO network */
+  rpcUrl: string
+  /** GraphQL endpoint for address resolution */
+  graphqlEndpoint?: string
+  /** IPFS gateway for profile images and metadata */
+  ipfsGateway?: string
+  /** Enable/disable address resolution */
+  enableAddressResolution?: boolean
+  /** Cache duration for resolved addresses (in milliseconds) */
+  cacheDuration?: number
+}
+
+const DEFAULT_CONFIG: LuksoConfig = {
+  chainId: 42, // LUKSO mainnet
+  rpcUrl: 'https://rpc.lukso.network',
+  graphqlEndpoint: '/api/graphql', // Use local API proxy
+  ipfsGateway: 'https://api.universalprofile.cloud/ipfs',
+  enableAddressResolution: true,
+  cacheDuration: 5 * 60 * 1000, // 5 minutes
+}
+
+let globalConfig: LuksoConfig = { ...DEFAULT_CONFIG }
+
+/**
+ * Set global LUKSO configuration
+ * Call this once to configure all transaction components
+ */
+export function setLuksoConfig(config: Partial<LuksoConfig>): void {
+  globalConfig = { ...globalConfig, ...config }
+
+  // Clear any existing address resolution cache when config changes
+  clearAddressCache()
+
+  if (typeof window !== 'undefined' && window.console) {
+    console.log('🌐 LUKSO Config Updated:', {
+      chainId: globalConfig.chainId,
+      network:
+        globalConfig.chainId === 42
+          ? 'mainnet'
+          : globalConfig.chainId === 4201
+            ? 'testnet'
+            : 'custom',
+      addressResolution: globalConfig.enableAddressResolution,
+    })
+  }
+}
+
+/**
+ * Get current LUKSO configuration
+ */
+export function getLuksoConfig(): LuksoConfig {
+  return { ...globalConfig }
+}
+
+/**
+ * Quick helper to set mainnet configuration
+ */
+export function useLuksoMainnet(): void {
+  setLuksoConfig({
+    chainId: 42,
+    rpcUrl: 'https://rpc.lukso.network',
+  })
+}
+
+/**
+ * Quick helper to set testnet configuration
+ */
+export function useLuksoTestnet(): void {
+  setLuksoConfig({
+    chainId: 4201,
+    rpcUrl: 'https://rpc.testnet.lukso.network',
+  })
+}
+
+/**
+ * Address resolution cache
+ */
+const addressCache = new Map<string, any>()
+const cacheTimestamps = new Map<string, number>()
+
+export function cacheAddress(address: string, data: any): void {
+  if (!globalConfig.enableAddressResolution) return
+
+  const key = address.toLowerCase()
+  addressCache.set(key, data)
+  cacheTimestamps.set(key, Date.now())
+}
+
+export function getCachedAddress(address: string): any | null {
+  if (!globalConfig.enableAddressResolution) return null
+
+  const key = address.toLowerCase()
+  const data = addressCache.get(key)
+  const timestamp = cacheTimestamps.get(key)
+
+  if (!data || !timestamp) return null
+
+  // Check if cache is expired
+  if (Date.now() - timestamp > globalConfig.cacheDuration!) {
+    addressCache.delete(key)
+    cacheTimestamps.delete(key)
+    return null
+  }
+
+  return data
+}
+
+export function clearAddressCache(): void {
+  addressCache.clear()
+  cacheTimestamps.clear()
+}
+
+/**
+ * Check if address resolution is enabled
+ */
+export function isAddressResolutionEnabled(): boolean {
+  return globalConfig.enableAddressResolution ?? true
+}
+
+/**
+ * Current chain signal for reactive chain state
+ */
+export const currentChainSignal = signal<Chain | null>(null)
+
+/**
+ * Set current chain signal from viem chain object
+ */
+export function setCurrentChain(chain: Chain): void {
+  currentChainSignal.value = chain
+
+  // Also update the legacy global config for backwards compatibility
+  setLuksoConfig({
+    chainId: chain.id,
+    rpcUrl: chain.rpcUrls.default.http[0],
+  })
+}
+
+/**
+ * Get current chain, falling back to chain derived from global config
+ */
+export function getCurrentChain(): Chain | null {
+  return currentChainSignal.value
+}
+
+/**
+ * Initialize chain signal from global config
+ */
+export async function initializeChainSignal(): Promise<void> {
+  if (currentChainSignal.value) return
+
+  try {
+    const { lukso, luksoTestnet } = await import('viem/chains')
+    const config = getLuksoConfig()
+
+    const chain = config.chainId === 42 ? lukso : luksoTestnet
+    currentChainSignal.value = chain
+  } catch (error) {
+    console.warn('Failed to initialize chain signal:', error)
+  }
+}