@hsuite/native-connect-angular 1.0.0

package/src/lib/providers/wallet-error-handler.ts

@@ -0,0 +1,349 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+/**
+ * @file wallet-error-handler.ts
+ * @description Configurable error handler with automatic toast notifications
+ *
+ * Provides automatic error handling for wallet operations with beautiful
+ * Ionic toast notifications. Fully customizable per error type.
+ */
+
+import { Injectable, Provider, inject, InjectionToken } from '@angular/core';
+import { getLogger } from '@hsuite/native-connect-sdk';
+import { ToastController } from '@ionic/angular/standalone';
+
+import { WalletEventBus } from '../services/wallet-event-bus.service';
+
+const logger = getLogger().scoped?.('WalletErrorHandler') ?? getLogger();
+
+/**
+ * Error category for categorizing wallet errors
+ */
+export type WalletErrorCategory =
+  | 'network' // Network connectivity issues
+  | 'auth' // Authentication failures (PIN, biometric)
+  | 'user_cancelled' // User cancelled the operation
+  | 'provider' // Provider-specific errors
+  | 'transaction' // Transaction failures
+  | 'validation' // Input validation errors
+  | 'unknown'; // Uncategorized errors
+
+/**
+ * Categorized wallet error with user-friendly message
+ */
+export interface CategorizedError {
+  /** Original error */
+  original: Error;
+  /** Error category */
+  category: WalletErrorCategory;
+  /** User-friendly message */
+  userMessage: string;
+  /** Whether this error is recoverable */
+  recoverable: boolean;
+}
+
+/**
+ * Configuration for the wallet error handler
+ */
+export interface WalletErrorHandlerConfig {
+  /**
+   * Whether to show toast notifications for errors (default: true)
+   */
+  showToasts?: boolean;
+
+  /**
+   * Custom handler for connection errors
+   */
+  onConnectionError?: (error: Error) => void;
+
+  /**
+   * Custom handler for transaction errors
+   */
+  onTransactionError?: (error: Error) => void;
+
+  /**
+   * Custom handler for provider errors
+   */
+  onProviderError?: (error: Error) => void;
+
+  /**
+   * Toast duration in milliseconds (default: 4000)
+   */
+  toastDuration?: number;
+
+  /**
+   * Toast position (default: 'top')
+   */
+  toastPosition?: 'top' | 'bottom' | 'middle';
+}
+
+/**
+ * Injection token for error handler config
+ */
+export const WALLET_ERROR_HANDLER_CONFIG = new InjectionToken<WalletErrorHandlerConfig>(
+  'WALLET_ERROR_HANDLER_CONFIG',
+);
+
+/**
+ * Wallet error handler service
+ *
+ * Automatically subscribes to wallet events and shows error toasts.
+ * Can be customized via configuration.
+ */
+@Injectable()
+export class WalletErrorHandler {
+  private readonly config = inject(WALLET_ERROR_HANDLER_CONFIG, { optional: true });
+  private readonly eventBus = inject(WalletEventBus);
+  private readonly toastController = inject(ToastController);
+
+  /**
+   *
+   */
+  constructor() {
+    // Setup error listeners
+    this.setupErrorListeners();
+    logger.debug('Initialized with config', { config: this.config });
+  }
+
+  /**
+   * Setup listeners for wallet errors
+   */
+  private setupErrorListeners(): void {
+    // Listen to provider errors
+    this.eventBus.providerError.subscribe((event) => {
+      logger.error('Provider error', { event });
+
+      // Custom handler
+      if (this.config?.onProviderError) {
+        this.config.onProviderError(
+          event.error instanceof Error ? event.error : new Error(String(event.error)),
+        );
+      }
+
+      // Show toast if enabled (default: true)
+      if (this.config?.showToasts !== false) {
+        void this.showErrorToast(
+          'Wallet Error',
+          event.error instanceof Error ? event.error.message : String(event.error),
+        );
+      }
+    });
+
+    // Listen to disconnections for unexpected disconnects
+    this.eventBus.disconnected.subscribe((event) => {
+      if (event.reason === 'wallet_initiated_disconnect' || event.reason === 'session_terminated') {
+        logger.warn('Unexpected disconnect', { event });
+
+        // Show toast if enabled
+        if (this.config?.showToasts !== false) {
+          void this.showWarningToast(
+            'Wallet Disconnected',
+            `${event.providerType === 'hsuite-native' ? 'HSuite Wallet' : 'WalletConnect'} session ended`,
+          );
+        }
+      }
+    });
+  }
+
+  /**
+   * Show error toast
+   * Uses cssClass-only styling (no Ionic color property) for theme compatibility.
+   * @param header
+   * @param message
+   */
+  private async showErrorToast(header: string, message: string): Promise<void> {
+    const toast = await this.toastController.create({
+      header,
+      message,
+      duration: this.config?.toastDuration || 4000,
+      position: this.config?.toastPosition || 'top',
+      cssClass: 'toast-danger toast-compact',
+      buttons: [{ icon: 'close', role: 'cancel' }],
+    });
+
+    await toast.present();
+  }
+
+  /**
+   * Show warning toast
+   * Uses cssClass-only styling (no Ionic color property) for theme compatibility.
+   * @param header
+   * @param message
+   */
+  private async showWarningToast(header: string, message: string): Promise<void> {
+    const toast = await this.toastController.create({
+      header,
+      message,
+      duration: this.config?.toastDuration || 4000,
+      position: this.config?.toastPosition || 'top',
+      cssClass: 'toast-warning toast-compact',
+      buttons: [{ icon: 'close', role: 'cancel' }],
+    });
+
+    await toast.present();
+  }
+
+  /**
+   * Manually handle an error (for use in components)
+   * @param title
+   * @param error
+   */
+  async handleError(title: string, error: Error | string): Promise<void> {
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (this.config?.showToasts !== false) {
+      await this.showErrorToast(title, message);
+    }
+  }
+
+  /**
+   * Manually show success toast (convenience method)
+   * Uses cssClass-only styling (no Ionic color property) for theme compatibility.
+   * @param header
+   * @param message
+   */
+  async showSuccess(header: string, message: string): Promise<void> {
+    const toast = await this.toastController.create({
+      header,
+      message,
+      duration: this.config?.toastDuration || 3000,
+      position: this.config?.toastPosition || 'top',
+      cssClass: 'toast-success toast-compact',
+      buttons: [{ icon: 'close', role: 'cancel' }],
+    });
+
+    await toast.present();
+  }
+
+  /**
+   * Categorize an error for better handling
+   * @param error - The error to categorize
+   * @returns Categorized error with user-friendly message
+   */
+  categorizeError(error: Error | string): CategorizedError {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const lowerMessage = errorMessage.toLowerCase();
+
+    // Network errors
+    if (
+      lowerMessage.includes('network') ||
+      lowerMessage.includes('timeout') ||
+      lowerMessage.includes('fetch') ||
+      lowerMessage.includes('connection')
+    ) {
+      return {
+        original: error instanceof Error ? error : new Error(errorMessage),
+        category: 'network',
+        userMessage: 'Network connection issue. Please check your internet connection.',
+        recoverable: true,
+      };
+    }
+
+    // User cancelled
+    if (
+      lowerMessage.includes('cancel') ||
+      lowerMessage.includes('rejected') ||
+      lowerMessage.includes('denied') ||
+      lowerMessage.includes('user rejected')
+    ) {
+      return {
+        original: error instanceof Error ? error : new Error(errorMessage),
+        category: 'user_cancelled',
+        userMessage: 'Operation cancelled.',
+        recoverable: true,
+      };
+    }
+
+    // Authentication errors
+    if (
+      lowerMessage.includes('pin') ||
+      lowerMessage.includes('biometric') ||
+      lowerMessage.includes('auth') ||
+      lowerMessage.includes('unlock')
+    ) {
+      return {
+        original: error instanceof Error ? error : new Error(errorMessage),
+        category: 'auth',
+        userMessage: 'Authentication failed. Please try again.',
+        recoverable: true,
+      };
+    }
+
+    // Transaction errors
+    if (
+      lowerMessage.includes('transaction') ||
+      lowerMessage.includes('insufficient') ||
+      lowerMessage.includes('balance') ||
+      lowerMessage.includes('sign')
+    ) {
+      return {
+        original: error instanceof Error ? error : new Error(errorMessage),
+        category: 'transaction',
+        userMessage: 'Transaction failed. Please check the details and try again.',
+        recoverable: true,
+      };
+    }
+
+    // Validation errors
+    if (
+      lowerMessage.includes('invalid') ||
+      lowerMessage.includes('required') ||
+      lowerMessage.includes('format')
+    ) {
+      return {
+        original: error instanceof Error ? error : new Error(errorMessage),
+        category: 'validation',
+        userMessage: errorMessage,
+        recoverable: true,
+      };
+    }
+
+    // Provider errors
+    if (
+      lowerMessage.includes('provider') ||
+      lowerMessage.includes('wallet') ||
+      lowerMessage.includes('session')
+    ) {
+      return {
+        original: error instanceof Error ? error : new Error(errorMessage),
+        category: 'provider',
+        userMessage: 'Wallet connection issue. Please reconnect.',
+        recoverable: true,
+      };
+    }
+
+    // Unknown
+    return {
+      original: error instanceof Error ? error : new Error(errorMessage),
+      category: 'unknown',
+      userMessage: 'An unexpected error occurred.',
+      recoverable: false,
+    };
+  }
+}
+
+/**
+ * Provider function for WalletErrorHandler
+ *
+ * Call this in your app configuration to enable automatic error handling.
+ *
+ * @param config - Optional configuration
+ * @returns Angular providers
+ */
+export function provideWalletErrorHandler(config?: WalletErrorHandlerConfig): Provider[] {
+  return [
+    {
+      provide: WALLET_ERROR_HANDLER_CONFIG,
+      useValue: config || { showToasts: true },
+    },
+    WalletErrorHandler,
+  ];
+}

package/src/lib/providers/walletconnect/core/base-signer.interface.ts

@@ -0,0 +1,122 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+/**
+ * @file base-signer.interface.ts
+ * @description Abstract signer interface for WalletConnect multi-chain support
+ *
+ * Defines the contract that all ledger-specific signers must implement.
+ * This enables the Strategy Pattern for clean separation of ledger logic.
+ */
+
+import type { SignResult, SubmitResult, SignMessageResult } from '../../base-wallet-provider';
+import type SignClient from '@walletconnect/sign-client';
+
+/**
+ * Configuration for initializing a WalletConnect signer
+ */
+export interface WalletConnectSignerConfig {
+  ledgerId: string;
+  networkId: string;
+  chainId: string; // e.g., 'hedera:testnet', 'xrpl:testnet'
+}
+
+/**
+ * Parameters for signing operations
+ */
+export interface SignerOperationParams {
+  client: SignClient;
+  topic: string;
+  accountAddress: string;
+  payload: string;
+  networkId: string;
+}
+
+/**
+ * Interface that all WalletConnect signers must implement.
+ * Each ledger (Hedera, XRPL, etc.) provides its own implementation.
+ *
+ * This follows the Strategy Pattern, allowing the WalletConnect provider
+ * to delegate ledger-specific logic to the appropriate signer.
+ */
+export interface IWalletConnectSigner {
+  /**
+   * Unique identifier for this ledger (e.g., 'hedera', 'xrpl')
+   */
+  readonly ledgerId: string;
+
+  /**
+   * Build WalletConnect namespace configuration for this ledger.
+   * Defines the JSON-RPC methods, chains, and events supported.
+   *
+   * @param networkId - The network identifier (e.g., 'hedera:testnet')
+   * @returns Namespace configuration object
+   */
+  buildNamespace(networkId: string): {
+    methods: string[];
+    chains: string[];
+    events: string[];
+  };
+
+  /**
+   * Sign a transaction without submitting to the network.
+   * Used for multi-sig workflows or when the dApp handles submission.
+   *
+   * @param params - Signing parameters including client, topic, account, and payload
+   * @returns Promise resolving to signed transaction data
+   */
+  signTransaction(params: SignerOperationParams): Promise<SignResult>;
+
+  /**
+   * Sign and submit a transaction to the network.
+   * The wallet handles both signing and network submission.
+   *
+   * @param params - Submission parameters including client, topic, account, and payload
+   * @returns Promise resolving to transaction ID and metadata
+   */
+  submitTransaction(params: SignerOperationParams): Promise<SubmitResult>;
+
+  /**
+   * Sign and execute a transaction in one call (preferred method to avoid double prompts).
+   * This uses the wallet's native sign+execute method when available (e.g., hedera_signAndExecuteTransaction).
+   * Falls back to sign then submit for wallets that don't support it.
+   *
+   * @param params - Transaction parameters including client, topic, account, and payload
+   * @returns Promise resolving to transaction ID and metadata
+   */
+  signAndExecuteTransaction?(params: SignerOperationParams): Promise<SubmitResult>;
+
+  /**
+   * Sign an arbitrary message (e.g., for DAO votes, authentication, proofs).
+   * The message can be plain text or base64 encoded.
+   *
+   * @param params - Signing parameters with message string
+   * @returns Promise resolving to signature and optional public key
+   */
+  signMessage(
+    params: SignerOperationParams & { message: string; encoding?: 'utf-8' | 'base64' },
+  ): Promise<SignMessageResult>;
+
+  /**
+   * Parse accounts from WalletConnect session namespace.
+   * Extracts account addresses and chain IDs from the session data.
+   *
+   * Optionally filters accounts to only include those matching a target network.
+   * This is important for respecting the user's network selection in the dApp.
+   *
+   * @param namespace - The WalletConnect namespace object for this ledger
+   * @param targetNetworkId - Optional network ID to filter accounts (e.g., 'hedera:mainnet')
+   * @returns Array of parsed account objects, filtered by target network if specified
+   */
+  parseAccounts(
+    namespace: any,
+    targetNetworkId?: string,
+  ): Array<{ address: string; chainId: string }>;
+}

package/src/lib/providers/walletconnect/core/session-health.ts

@@ -0,0 +1,196 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+/**
+ * @file session-health.ts
+ * @description Manages WalletConnect session health - ensures relay subscriptions
+ * are active before making requests. Transparent to dApp developers.
+ *
+ * This class handles the common WalletConnect issue where relay subscriptions
+ * become stale, causing requests to fail with empty error objects.
+ *
+ * Features:
+ * - Pre-request session ping to ensure relay subscription is active
+ * - Relay connection monitoring (connect/disconnect/error events)
+ * - Automatic ping cache management
+ * - Subscription refresh capability
+ */
+
+import { getLogger } from '@hsuite/native-connect-sdk';
+import type SignClient from '@walletconnect/sign-client';
+
+const logger = getLogger().scoped?.('WCSessionHealth') ?? getLogger();
+
+/**
+ * Manages WalletConnect session health to prevent stale relay subscription issues.
+ *
+ * The WalletConnect relay uses WebSocket connections that can become stale,
+ * causing push events to stop arriving. This manager:
+ * - Pings sessions before requests to ensure subscriptions are active
+ * - Monitors relay connection state
+ * - Clears ping cache on disconnect to force re-ping
+ */
+export class SessionHealthManager {
+  private client: SignClient;
+  private lastPingTime = new Map<string, number>();
+
+  /**
+   * Minimum interval between pings for the same topic (30 seconds).
+   * Pinging too frequently is unnecessary and adds latency.
+   */
+  private readonly PING_INTERVAL_MS = 30000;
+
+  /**
+   * Maximum time to wait for a ping response (5 seconds).
+   * If ping times out, we proceed anyway but log a warning.
+   */
+  private readonly PING_TIMEOUT_MS = 5000;
+
+  /**
+   * Create a new SessionHealthManager.
+   *
+   * @param client - Initialized WalletConnect SignClient instance
+   */
+  constructor(client: SignClient) {
+    this.client = client;
+    this.setupRelayMonitoring();
+    logger.info('SessionHealthManager initialized');
+  }
+
+  /**
+   * Ensure session is healthy before making a request.
+   *
+   * Pings the session if the last ping was more than 30 seconds ago.
+   * This refreshes the relay subscription and helps prevent the
+   * empty error object issue.
+   *
+   * Called automatically by WalletConnectClientManager before requests.
+   *
+   * @param topic - Session topic to verify
+   */
+  async ensureSessionHealth(topic: string): Promise<void> {
+    const lastPing = this.lastPingTime.get(topic) || 0;
+    const now = Date.now();
+
+    // Skip if we pinged recently
+    if (now - lastPing <= this.PING_INTERVAL_MS) {
+      logger.debug('Skipping ping - recent ping exists', {
+        topic: topic.substring(0, 16) + '...',
+        lastPingAge: now - lastPing,
+      });
+      return;
+    }
+
+    try {
+      logger.debug('Pinging session to ensure relay subscription', {
+        topic: topic.substring(0, 16) + '...',
+      });
+
+      // Race ping against timeout
+      await Promise.race([
+        this.client.ping({ topic }),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error('Ping timeout')), this.PING_TIMEOUT_MS),
+        ),
+      ]);
+
+      this.lastPingTime.set(topic, now);
+      logger.debug('Session ping successful', {
+        topic: topic.substring(0, 16) + '...',
+      });
+    } catch (err) {
+      // Log warning but don't throw - let the request attempt proceed
+      // The request might still succeed if the subscription is actually active
+      logger.warn('Session ping failed - relay subscription may be stale', {
+        topic: topic.substring(0, 16) + '...',
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  /**
+   * Force refresh relay subscription for a topic.
+   *
+   * Use this when you suspect the subscription is stale and want
+   * to explicitly re-subscribe rather than relying on ping.
+   *
+   * @param topic - Session topic to refresh subscription for
+   */
+  async refreshSubscription(topic: string): Promise<void> {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- WalletConnect internal API not typed
+      const relayer = (this.client as any).core?.relayer;
+      if (relayer?.subscribe) {
+        await relayer.subscribe(topic);
+        // Clear ping cache so next ensureSessionHealth will ping
+        this.lastPingTime.delete(topic);
+        logger.info('Refreshed relay subscription', {
+          topic: topic.substring(0, 16) + '...',
+        });
+      } else {
+        logger.warn('Relayer.subscribe not available');
+      }
+    } catch (err) {
+      logger.warn('Failed to refresh subscription', {
+        topic: topic.substring(0, 16) + '...',
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  /**
+   * Clear ping cache for a specific topic or all topics.
+   *
+   * @param topic - Optional topic to clear. If not provided, clears all.
+   */
+  clearPingCache(topic?: string): void {
+    if (topic) {
+      this.lastPingTime.delete(topic);
+    } else {
+      this.lastPingTime.clear();
+    }
+  }
+
+  /**
+   * Setup relay connection monitoring.
+   *
+   * Listens for:
+   * - connect: Logs when WebSocket connects
+   * - disconnect: Clears ping cache to force re-ping on next request
+   * - error: Logs relay errors
+   *
+   * @private
+   */
+  private setupRelayMonitoring(): void {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- WalletConnect internal API not typed
+    const relayer = (this.client as any).core?.relayer;
+    if (!relayer) {
+      logger.warn('Could not access relayer for monitoring');
+      return;
+    }
+
+    relayer.on('connect', () => {
+      logger.info('Relay WebSocket connected');
+    });
+
+    relayer.on('disconnect', () => {
+      logger.warn('Relay WebSocket disconnected - clearing ping cache');
+      this.lastPingTime.clear();
+    });
+
+    relayer.on('error', (err: Error) => {
+      logger.error('Relay error', {
+        error: err?.message || String(err),
+      });
+    });
+
+    logger.debug('Relay monitoring setup complete');
+  }
+}