@hsuite/native-connect-angular 1.0.0

package/src/lib/services/wallet-context.service.ts

@@ -0,0 +1,184 @@
+/**
+ * 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
+ */
+
+/**
+ * @fileoverview Centralized wallet context aggregation service.
+ *
+ * @module services/wallet-context
+ *
+ * @description
+ * WalletContextService computes and exposes a unified, reactive wallet context by aggregating
+ * state from UnifiedWalletService. It provides a single computed signal containing all
+ * wallet state, eliminating the need to manually track multiple signals across different services.
+ *
+ * This service is the primary data source for the structural directives (`*walletContext`
+ * and `*walletConnected`) that enable declarative wallet state access in templates.
+ *
+ * **Key Capabilities:**
+ * - Aggregates connection status, accounts, sessions, and providers into a single context
+ * - Provides both signal-based (modern) and Observable-based (RxJS) access patterns
+ * - Automatically recomputes when any underlying state changes
+ * - Handles edge cases like P2P sessions with restored accounts
+ *
+ * @Component({ template: `...` })
+ * export class MyComponent {
+ *   private contextService = inject(WalletContextService);
+ *
+ *   constructor() {
+ *     effect(() => {
+ *       const context = this.contextService.context();
+ *       console.log('Connected:', context.isConnected);
+ *       console.log('Active:', context.activeAccount?.address);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+import { Injectable, computed, inject } from '@angular/core';
+import { toObservable } from '@angular/core/rxjs-interop';
+import { Observable } from 'rxjs';
+import { UnifiedWalletService } from './unified-wallet.service';
+import type { WalletContext } from '../models/wallet-context.model';
+
+/**
+ * Angular service that aggregates wallet state into a unified context.
+ *
+ * @service WalletContextService
+ *
+ * @description
+ * Provides a single reactive context object that combines all wallet state:
+ * - Connection status (computed from provider states and account availability)
+ * - Active account (currently selected account across all providers)
+ * - All accounts (aggregated from all connected providers)
+ * - Active sessions (with metadata for each provider)
+ * - Provider instances (both connected and disconnected)
+ *
+ * This service is used internally by `*walletContext` and `*walletConnected` directives
+ * to provide declarative state access in templates.
+ *
+ * @providedIn root
+ *
+ * @Component({
+ *   template: `
+ *     @if (isConnected()) {
+ *       <p>Connected as {{ activeAccount()?.address }}</p>
+ *     }
+ *   `
+ * })
+ * export class MyComponent {
+ *   private contextService = inject(WalletContextService);
+ *
+ *   isConnected = () => this.contextService.isConnected();
+ *   activeAccount = () => this.contextService.getActiveAccount();
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class WalletContextService {
+  private readonly walletService = inject(UnifiedWalletService);
+
+  /**
+   * Computed wallet context signal
+   *
+   * Automatically recomputes when unknown underlying state changes.
+   *
+   * **Connection Status Logic:**
+   * - `isConnected = true` if:
+   *   - Any provider is actively connected AND has accounts, OR
+   *   - Any provider has restored accounts (e.g., P2P session metadata from localStorage)
+   *
+   * This ensures P2P sessions with restored accounts show as "connected" in the UI,
+   * even though WebRTC needs re-pairing for actual operations. Operations will fail
+   * gracefully if the transport isn't connected.
+   */
+  readonly context = computed<WalletContext>(() => {
+    const activeAccount = this.walletService.activeAccount();
+    const allAccounts = this.walletService.allAccounts();
+    const connectedProviders = this.walletService.connectedProviders();
+    const sessions = this.walletService.getActiveSessions();
+
+    // Compute connection status:
+    // Consider "connected" if we have accounts available (even from restored sessions)
+    // This allows P2P sessions with persisted accounts to show in the UI
+    const isConnected = allAccounts.length > 0;
+
+    return {
+      isConnected,
+      activeAccount,
+      allAccounts,
+      sessions,
+      providers: Array.from(this.getAllProviders()),
+      connectedProviders,
+    };
+  });
+
+  /**
+   * Observable stream of wallet context for RxJS composition
+   */
+  readonly context$: Observable<WalletContext> = toObservable(this.context);
+
+  /**
+   * Checks if any wallet provider is currently connected.
+   *
+   * @description
+   * Convenience method that returns the isConnected property from the context.
+   * Connection is determined by account availability, not just provider state.
+   *
+   * @returns True if at least one account is available
+   */
+  isConnected(): boolean {
+    return this.context().isConnected;
+  }
+
+  /**
+   * Gets the currently active account.
+   *
+   * @description
+   * Convenience method that returns the activeAccount property from the context.
+   * The active account is the one currently selected for wallet operations.
+   *
+   * @returns The active account, or null if no account is selected
+   */
+  getActiveAccount() {
+    return this.context().activeAccount;
+  }
+
+  /**
+   * Gets all accounts from all connected providers.
+   *
+   * @description
+   * Convenience method that returns the allAccounts array from the context.
+   * Includes accounts from all providers (HSuite Native, WalletConnect, P2P).
+   *
+   * @returns Array of all connected accounts, empty if none
+   */
+  getAllAccounts() {
+    return this.context().allAccounts;
+  }
+
+  /**
+   * Get all providers from UnifiedWalletService
+   * Private helper to access providers map
+   */
+  private getAllProviders() {
+    // Access through public methods since providers map is private
+    const hsuite = this.walletService.getProvider('hsuite-native');
+    const walletconnect = this.walletService.getProvider('walletconnect-v2');
+    const mobileNative = this.walletService.getProvider('mobile-native');
+
+    const providers = [];
+    if (hsuite) providers.push(hsuite);
+    if (walletconnect) providers.push(walletconnect);
+    if (mobileNative) providers.push(mobileNative);
+
+    return providers;
+  }
+}

package/src/lib/services/wallet-event-bus.service.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 Centralized event bus for wallet-level events.
+ *
+ * @module services/wallet-event-bus
+ *
+ * @description
+ * WalletEventBus provides a decoupled way for the angular-sdk to emit events
+ * that dApps can subscribe to. It enables reactive handling of wallet lifecycle
+ * events without tight coupling between components.
+ *
+ * **Supported Events:**
+ * - `connected` - Provider successfully connected
+ * - `disconnected` - Provider disconnected (user or wallet initiated)
+ * - `accountChanged` - Active account switched
+ * - `accountsUpdated` - Provider's account list changed
+ * - `sessionCreated` - New session established
+ * - `sessionDeleted` - Session terminated
+ * - `sessionRestored` - Session restored from storage
+ * - `providerStatusChanged` - Provider status changed
+ * - `providerError` - Provider encountered an error
+ *
+ * Each event is available as both an Angular EventEmitter (for template bindings)
+ * and an RxJS Observable (for advanced composition with operators).
+ */
+
+import { Injectable, EventEmitter } from '@angular/core';
+import { getLogger } from '@hsuite/native-connect-sdk';
+import { Observable } from 'rxjs';
+
+import type {
+  ConnectionEvent,
+  DisconnectionEvent,
+  AccountChangeEvent,
+  AccountsUpdateEvent,
+  SessionEvent,
+  ProviderStatusEvent,
+  ProviderErrorEvent,
+} from '../models/wallet-events.model';
+
+const logger = getLogger().scoped?.('WalletEventBus') ?? getLogger();
+
+/**
+ * Centralized event bus for wallet events.
+ *
+ * @service WalletEventBus
+ *
+ * @description
+ * Provides EventEmitters for all wallet-level events that dApps might want to react to.
+ * This service is automatically used by UnifiedWalletService to emit events, and dApps
+ * can subscribe to these events to handle wallet state changes.
+ *
+ * All events include a `timestamp` field for ordering and debugging purposes.
+ *
+ * @providedIn root
+ */
+@Injectable({ providedIn: 'root' })
+export class WalletEventBus {
+  /**
+   * Emitted when a provider successfully connects
+   *
+   * @event connected
+   */
+  readonly connected = new EventEmitter<ConnectionEvent>();
+
+  /**
+   * Emitted when a provider disconnects
+   *
+   * @event disconnected
+   */
+  readonly disconnected = new EventEmitter<DisconnectionEvent>();
+
+  /**
+   * Emitted when the active account changes
+   *
+   * @event accountChanged
+   */
+  readonly accountChanged = new EventEmitter<AccountChangeEvent>();
+
+  /**
+   * Emitted when a provider's account list updates
+   *
+   * @event accountsUpdated
+   */
+  readonly accountsUpdated = new EventEmitter<AccountsUpdateEvent>();
+
+  /**
+   * Emitted when a new session is created
+   *
+   * @event sessionCreated
+   */
+  readonly sessionCreated = new EventEmitter<SessionEvent>();
+
+  /**
+   * Emitted when a session is deleted
+   *
+   * @event sessionDeleted
+   */
+  readonly sessionDeleted = new EventEmitter<SessionEvent>();
+
+  /**
+   * Emitted when a session is restored from storage
+   *
+   * @event sessionRestored
+   */
+  readonly sessionRestored = new EventEmitter<SessionEvent>();
+
+  /**
+   * Emitted when a provider's status changes
+   *
+   * @event providerStatusChanged
+   */
+  readonly providerStatusChanged = new EventEmitter<ProviderStatusEvent>();
+
+  /**
+   * Emitted when a provider encounters an error
+   *
+   * @event providerError
+   */
+  readonly providerError = new EventEmitter<ProviderErrorEvent>();
+
+  // RxJS Observable streams for advanced composition
+  // These allow using RxJS operators like debounceTime, switchMap, filter, etc.
+
+  /**
+   * Observable stream for connection events
+   */
+  readonly connected$: Observable<ConnectionEvent> = this.connected.asObservable();
+
+  /**
+   * Observable stream for disconnection events
+   */
+  readonly disconnected$: Observable<DisconnectionEvent> = this.disconnected.asObservable();
+
+  /**
+   * Observable stream for account change events
+   */
+  readonly accountChanged$: Observable<AccountChangeEvent> = this.accountChanged.asObservable();
+
+  /**
+   * Observable stream for accounts update events
+   */
+  readonly accountsUpdated$: Observable<AccountsUpdateEvent> = this.accountsUpdated.asObservable();
+
+  /**
+   * Observable stream for session creation events
+   */
+  readonly sessionCreated$: Observable<SessionEvent> = this.sessionCreated.asObservable();
+
+  /**
+   * Observable stream for session deletion events
+   */
+  readonly sessionDeleted$: Observable<SessionEvent> = this.sessionDeleted.asObservable();
+
+  /**
+   * Observable stream for session restoration events
+   */
+  readonly sessionRestored$: Observable<SessionEvent> = this.sessionRestored.asObservable();
+
+  /**
+   * Observable stream for provider status change events
+   */
+  readonly providerStatusChanged$: Observable<ProviderStatusEvent> =
+    this.providerStatusChanged.asObservable();
+
+  /**
+   * Observable stream for provider error events
+   */
+  readonly providerError$: Observable<ProviderErrorEvent> = this.providerError.asObservable();
+
+  /**
+   *
+   */
+  constructor() {
+    logger.debug('Event bus initialized');
+  }
+}

package/src/lib/services/wallet-providers.service.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 Singleton service that manages shared wallet provider instances.
+ *
+ * @module services/wallet-providers
+ *
+ * @description
+ * WalletProvidersService manages the lifecycle and registration of wallet provider
+ * instances at application startup. It ensures that providers are created once and
+ * shared across all components and pages.
+ *
+ * **Key Responsibilities:**
+ * - Creates provider instances once during construction
+ * - Registers providers with UnifiedWalletService
+ * - Maintains references to provider instances for direct access
+ * - Ensures consistent provider state across the application
+ *
+ * **Note:** This service is typically not needed in most applications. The
+ * UnifiedWalletService automatically creates and registers built-in providers.
+ * This service exists for advanced use cases requiring direct provider access.
+ *
+ * @Component({ selector: 'app-root', ... })
+ * export class AppComponent {
+ *   // Inject to trigger initialization at app startup
+ *   constructor(private walletProviders: WalletProvidersService) {}
+ * }
+ * ```
+ */
+
+import { Injectable } from '@angular/core';
+import { getLogger } from '@hsuite/native-connect-sdk';
+
+import { HsuiteNativeProvider } from '../providers/hsuite-native-provider';
+import { WalletConnectV2Provider } from '../providers/walletconnect/core/walletconnect-provider';
+
+import { UnifiedWalletService } from './unified-wallet.service';
+
+
+const logger = getLogger().scoped?.('WalletProvidersService') ?? getLogger();
+
+/**
+ * Singleton service that creates and registers wallet providers at app startup.
+ *
+ * @service WalletProvidersService
+ *
+ * @description
+ * This service ensures providers are shared across all pages and components by
+ * creating and registering them once at application startup. It maintains references
+ * to provider instances for cases where direct access is needed.
+ *
+ * **When to Use:**
+ * - When you need direct access to a specific provider instance
+ * - When debugging provider-specific behavior
+ * - For advanced configurations not exposed through UnifiedWalletService
+ *
+ * **When NOT to Use:**
+ * - For typical wallet operations (use UnifiedWalletService instead)
+ * - For connecting/disconnecting (use UnifiedWalletService.connect/disconnect)
+ * - For signing transactions (use UnifiedWalletService or TransactionService)
+ *
+ * @providedIn root
+ *
+ * @Component({ selector: 'app-root', ... })
+ * export class AppComponent {
+ *   // Injection triggers provider registration
+ *   constructor(private walletProviders: WalletProvidersService) {}
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class WalletProvidersService {
+  /**
+   * Shared HSuite Native provider instance
+   */
+  readonly hsuiteProvider: HsuiteNativeProvider;
+
+  /**
+   * Shared WalletConnect v2 provider instance
+   */
+  readonly walletConnectProvider: WalletConnectV2Provider;
+
+  /**
+   *
+   * @param wallet
+   * @param hsuiteProvider
+   * @param walletConnectProvider
+   */
+  constructor(
+    private readonly wallet: UnifiedWalletService,
+    hsuiteProvider: HsuiteNativeProvider,
+    walletConnectProvider: WalletConnectV2Provider,
+  ) {
+    // Store injected provider instances
+    this.hsuiteProvider = hsuiteProvider;
+    this.walletConnectProvider = walletConnectProvider;
+
+    // Register providers once at app startup
+    this.wallet.registerProvider(this.hsuiteProvider);
+    this.wallet.registerProvider(this.walletConnectProvider);
+
+    logger.info('Providers registered', {
+      hsuite: this.hsuiteProvider.id,
+      walletConnect: this.walletConnectProvider.id,
+    });
+  }
+
+  /**
+   * Gets a specific provider by its identifier.
+   *
+   * @description
+   * Returns the provider instance for direct access. Use this only when you
+   * need provider-specific functionality not exposed through UnifiedWalletService.
+   *
+   * @param id - The provider identifier ('hsuite-native' or 'walletconnect-v2')
+   *
+   * @returns The provider instance, or null if the ID is invalid
+   */
+  getProvider(id: 'hsuite-native' | 'walletconnect-v2') {
+    switch (id) {
+      case 'hsuite-native':
+        return this.hsuiteProvider;
+      case 'walletconnect-v2':
+        return this.walletConnectProvider;
+      default:
+        return null;
+    }
+  }
+}