@hsuite/native-connect-angular 1.0.0

package/src/lib/directives/wallet-context.directive.ts

@@ -0,0 +1,154 @@
+/**
+ * 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 Structural directive that provides unified wallet context to templates.
+ *
+ * @module directives/wallet-context
+ *
+ * @description
+ * WalletContextDirective is a structural directive that provides a unified wallet context
+ * to templates, eliminating the need to manually inject services and track multiple signals.
+ * It provides a single context variable with all wallet state.
+ *
+ * Unlike `*walletConnected`, this directive always renders its template and provides
+ * context regardless of connection status. Use this when you need access to wallet state
+ * but want to handle the connected/disconnected logic yourself.
+ *
+ * **Key Features:**
+ * - Provides complete wallet context (isConnected, accounts, sessions, providers)
+ * - Always renders (use *walletConnected for conditional rendering)
+ * - Automatically updates when any wallet state changes
+ * - Type-safe template context with full IDE support
+ *
+ * **Selector:** `*walletContext`
+ */
+
+import {
+  Directive,
+  TemplateRef,
+  ViewContainerRef,
+  inject,
+  effect,
+  EmbeddedViewRef,
+} from '@angular/core';
+import { WalletContextService } from '../services/wallet-context.service';
+import type { WalletContext } from '../models/wallet-context.model';
+
+/**
+ * Context object passed to the template.
+ *
+ * @description
+ * Contains the wallet context that is exposed to the template when using
+ * the `*walletContext` structural directive. Both `$implicit` and
+ * `walletContext` contain the same context for flexible access.
+ */
+export class WalletContextDirectiveContext {
+  constructor(
+    public $implicit: WalletContext,
+    public walletContext: WalletContext,
+  ) {}
+}
+
+/**
+ * Structural directive that provides unified wallet context.
+ *
+ * @directive WalletContextDirective
+ * @selector [walletContext]
+ *
+ * @description
+ * Automatically updates the view when wallet state changes, exposing a single
+ * `WalletContext` object with all wallet state. Unlike `*walletConnected`,
+ * this directive always renders its template.
+ *
+ * The directive uses Angular's effect() to reactively update the context
+ * whenever any underlying wallet state changes.
+ *
+ *   @if (w.isConnected) {
+ *     <account-selector [accounts]="w.allAccounts" />
+ *   } @else {
+ *     <wallet-connect-button />
+ *   }
+ * </div>
+ * ```
+ */
+@Directive({
+  selector: '[walletContext]',
+  standalone: true,
+})
+export class WalletContextDirective {
+  private readonly contextService = inject(WalletContextService);
+  private readonly templateRef = inject(TemplateRef<WalletContextDirectiveContext>);
+  private readonly viewContainer = inject(ViewContainerRef);
+
+  private viewRef: EmbeddedViewRef<WalletContextDirectiveContext> | null = null;
+
+  constructor() {
+    // Create the view immediately
+    this.createView();
+
+    // Update context reactively when wallet state changes
+    effect(() => {
+      const context = this.contextService.context();
+      this.updateContext(context);
+    });
+  }
+
+  /**
+   * Creates the embedded view with initial context.
+   *
+   * @description
+   * Called once during directive construction to create the view.
+   * The view is created immediately and then updated reactively.
+   */
+  private createView(): void {
+    if (!this.viewRef) {
+      const initialContext = this.contextService.context();
+      const context = new WalletContextDirectiveContext(initialContext, initialContext);
+      this.viewRef = this.viewContainer.createEmbeddedView(this.templateRef, context);
+    }
+  }
+
+  /**
+   * Updates the context when wallet state changes.
+   *
+   * @description
+   * Called reactively by Angular's effect() whenever the wallet context
+   * signal changes. Updates both the implicit and named context properties.
+   *
+   * @param walletContext - The new wallet context
+   */
+  private updateContext(walletContext: WalletContext): void {
+    if (this.viewRef) {
+      this.viewRef.context.$implicit = walletContext;
+      this.viewRef.context.walletContext = walletContext;
+      this.viewRef.markForCheck();
+    }
+  }
+
+  /**
+   * Static type guard for Angular template type checking.
+   *
+   * @description
+   * Enables TypeScript type inference in templates when using the directive.
+   * This allows the template to have proper types for the context variable.
+   *
+   * @param dir - The directive instance
+   * @param ctx - The context to type-guard
+   *
+   * @returns True, asserting that ctx is WalletContextDirectiveContext
+   */
+  static ngTemplateContextGuard(
+    dir: WalletContextDirective,
+    ctx: any,
+  ): ctx is WalletContextDirectiveContext {
+    return true;
+  }
+}

package/src/lib/directives/wallet-events.directive.ts

@@ -0,0 +1,232 @@
+/**
+ * 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 Attribute directive for declarative wallet event subscriptions.
+ *
+ * @module directives/wallet-events
+ *
+ * @description
+ * WalletEventsDirective is an attribute directive that provides declarative event
+ * subscriptions for wallet lifecycle events. It automatically subscribes to wallet
+ * events and unsubscribes on directive destruction, eliminating manual subscription
+ * management boilerplate.
+ *
+ * **Key Features:**
+ * - Automatic subscription management (subscribe on init, unsubscribe on destroy)
+ * - All wallet events exposed as Angular @Output() bindings
+ * - Works with any element or component
+ * - Type-safe event payloads
+ *
+ * **Available Events:**
+ * - `connected` - Provider successfully connected
+ * - `disconnected` - Provider disconnected
+ * - `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
+ *
+ * **Selector:** `[walletEvents]`
+ */
+
+import { Directive, Output, EventEmitter, inject, OnDestroy } from '@angular/core';
+import { Subscription } from 'rxjs';
+import { WalletEventBus } from '../services/wallet-event-bus.service';
+import type {
+  ConnectionEvent,
+  DisconnectionEvent,
+  AccountChangeEvent,
+  AccountsUpdateEvent,
+  SessionEvent,
+  ProviderStatusEvent,
+  ProviderErrorEvent,
+} from '../models/wallet-events.model';
+
+/**
+ * Attribute directive that provides declarative event subscriptions.
+ *
+ * @directive WalletEventsDirective
+ * @selector [walletEvents]
+ *
+ * @description
+ * Automatically manages subscriptions and cleanup - no manual ngOnDestroy needed.
+ * Simply declare which events you want to handle in your template using Angular's
+ * output binding syntax.
+ *
+ * All subscriptions are collected in a single Subscription object and cleaned up
+ * together when the directive is destroyed.
+ *
+ * @Component({
+ *   template: `
+ *     <div walletEvents
+ *          (disconnected)="handleDisconnect($event)"
+ *          (providerError)="handleError($event)">
+ *     </div>
+ *   `
+ * })
+ * export class MyComponent {
+ *   handleDisconnect(event: DisconnectionEvent) {
+ *     if (event.reason === 'wallet_initiated_disconnect') {
+ *       this.toast.warning('Wallet disconnected by remote');
+ *     }
+ *   }
+ *
+ *   handleError(event: ProviderErrorEvent) {
+ *     this.toast.error('Error: ' + event.error);
+ *   }
+ * }
+ * ```
+ */
+@Directive({
+  selector: '[walletEvents]',
+  standalone: true,
+})
+export class WalletEventsDirective implements OnDestroy {
+  private readonly eventBus = inject(WalletEventBus);
+  private readonly subscriptions = new Subscription();
+
+  /**
+   * Emitted when a provider successfully connects.
+   *
+   * @description
+   * Fired after a wallet connection is established. The event includes
+   * the provider ID, type, and the list of accounts that are now available.
+   */
+  @Output() connected = new EventEmitter<ConnectionEvent>();
+
+  /**
+   * Emitted when a provider disconnects.
+   *
+   * @description
+   * Fired when a wallet connection is terminated. The event includes
+   * the reason for disconnection (user-initiated, wallet-initiated, expired).
+   */
+  @Output() disconnected = new EventEmitter<DisconnectionEvent>();
+
+  /**
+   * Emitted when the active account changes.
+   *
+   * @description
+   * Fired when the user switches between accounts. Includes both the
+   * previous account and the newly selected account.
+   */
+  @Output() accountChanged = new EventEmitter<AccountChangeEvent>();
+
+  /**
+   * Emitted when a provider's account list updates.
+   *
+   * @description
+   * Fired when accounts are added or removed from a provider. Includes
+   * the updated account list and total count.
+   */
+  @Output() accountsUpdated = new EventEmitter<AccountsUpdateEvent>();
+
+  /**
+   * Emitted when a new session is created.
+   *
+   * @description
+   * Fired when a new wallet session is established. Includes session
+   * key, accounts, and metadata.
+   */
+  @Output() sessionCreated = new EventEmitter<SessionEvent>();
+
+  /**
+   * Emitted when a session is deleted.
+   *
+   * @description
+   * Fired when a wallet session is terminated. Includes session key
+   * and optional reason metadata.
+   */
+  @Output() sessionDeleted = new EventEmitter<SessionEvent>();
+
+  /**
+   * Emitted when a session is restored from storage.
+   *
+   * @description
+   * Fired when a previously saved session is restored (e.g., after page reload).
+   * Includes the restored accounts and session metadata.
+   */
+  @Output() sessionRestored = new EventEmitter<SessionEvent>();
+
+  /**
+   * Emitted when a provider's status changes.
+   *
+   * @description
+   * Fired when a provider transitions between states (connecting, connected,
+   * disconnected, error).
+   */
+  @Output() providerStatusChanged = new EventEmitter<ProviderStatusEvent>();
+
+  /**
+   * Emitted when a provider encounters an error.
+   *
+   * @description
+   * Fired when a wallet operation fails. Includes the error message
+   * and optional context about what operation failed.
+   */
+  @Output() providerError = new EventEmitter<ProviderErrorEvent>();
+
+  constructor() {
+    // Auto-subscribe to all events and forward to outputs
+    // Subscriptions are automatically cleaned up in ngOnDestroy
+
+    this.subscriptions.add(
+      this.eventBus.connected.subscribe((event) => this.connected.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.disconnected.subscribe((event) => this.disconnected.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.accountChanged.subscribe((event) => this.accountChanged.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.accountsUpdated.subscribe((event) => this.accountsUpdated.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.sessionCreated.subscribe((event) => this.sessionCreated.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.sessionDeleted.subscribe((event) => this.sessionDeleted.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.sessionRestored.subscribe((event) => this.sessionRestored.emit(event)),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.providerStatusChanged.subscribe((event) =>
+        this.providerStatusChanged.emit(event),
+      ),
+    );
+
+    this.subscriptions.add(
+      this.eventBus.providerError.subscribe((event) => this.providerError.emit(event)),
+    );
+  }
+
+  /**
+   * Cleans up all subscriptions on directive destruction.
+   *
+   * @description
+   * Called automatically by Angular when the directive is destroyed.
+   * Unsubscribes from all wallet events to prevent memory leaks.
+   */
+  ngOnDestroy(): void {
+    this.subscriptions.unsubscribe();
+  }
+}

package/src/lib/hsuite-wallet.module.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 NgModule wrapper for HSuite Wallet Angular SDK.
+ *
+ * @module HsuiteWalletModule
+ *
+ * @description
+ * Provides a traditional NgModule for module-based Angular/Ionic applications.
+ * All components internally use @ionic/angular/standalone imports but are re-exported
+ * through this module for compatibility with module-based apps.
+ *
+ * **When to Use This Module:**
+ * - Your Angular application uses NgModule-based architecture
+ * - You're migrating an existing Ionic/Angular app to use wallet features
+ * - You prefer importing a single module over individual components
+ *
+ * **When to Use Standalone Components Instead:**
+ * - New Angular 17+ applications using standalone components
+ * - You only need a few components and want tree-shaking benefits
+ * - Following modern Angular best practices
+ *
+ * **Included Components:**
+ * - WalletConnectButtonComponent - Ready-to-use connection button
+ * - WalletSessionDisplayComponent - Session information display
+ * - WalletTransactionStatusComponent - Transaction status indicator
+ * - AccountSelectorComponent - Multi-account dropdown
+ * - WalletAccountDisplayComponent - Account details display
+ * - WalletConnectPromptComponent - Connection prompt UI
+ * - WalletConnectedGuardComponent - Protected route guard
+ * - WalletConnectionModalComponent - Multi-protocol connection modal
+ *
+ * **Included Directives:**
+ * - WalletContextDirective (*walletContext) - Unified context access
+ * - WalletConnectedDirective (*walletConnected) - Conditional rendering
+ * - WalletEventsDirective (walletEvents) - Event subscriptions
+ *
+ * **Note:** Services (UnifiedWalletService, WalletEventBus, etc.) are NOT provided
+ * by this module because they use `providedIn: 'root'`. They're automatically
+ * available throughout your application.
+ *
+ * @NgModule({
+ *   imports: [HsuiteWalletModule],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @Component({
+ *   standalone: true,
+ *   imports: [WalletConnectButtonComponent],
+ * })
+ * export class MyComponent {}
+ * ```
+ */
+
+import { CommonModule } from '@angular/common';
+import { NgModule } from '@angular/core';
+import { IonicModule } from '@ionic/angular';
+
+// Components
+import { AccountActionsComponent } from './components/account-selector/account-actions/account-actions.component';
+import { AccountFilterComponent } from './components/account-selector/account-filter/account-filter.component';
+import { AccountListComponent } from './components/account-selector/account-list/account-list.component';
+import { AccountSelectorComponent } from './components/account-selector/account-selector.component';
+import { WalletAccountDisplayComponent } from './components/wallet-account-display/wallet-account-display.component';
+import { WalletConnectButtonComponent } from './components/wallet-connect-button/wallet-connect-button.component';
+import { WalletConnectPromptComponent } from './components/wallet-connect-prompt/wallet-connect-prompt.component';
+import { WalletConnectedGuardComponent } from './components/wallet-connected-guard/wallet-connected-guard.component';
+import { WalletConnectionModalComponent } from './components/wallet-connection-modal/wallet-connection-modal.component';
+import { WalletSessionDisplayComponent } from './components/wallet-session-display/wallet-session-display.component';
+import { WalletTransactionStatusComponent } from './components/wallet-transaction-status/wallet-transaction-status.component';
+
+// Directives
+import { WalletConnectedDirective } from './directives/wallet-connected.directive';
+import { WalletContextDirective } from './directives/wallet-context.directive';
+import { WalletEventsDirective } from './directives/wallet-events.directive';
+
+/**
+ * @module HsuiteWalletModule
+ *
+ * NgModule wrapper for HSuite Wallet Angular SDK components, directives, and services.
+ *
+ * **What's Included:**
+ *
+ * **Components:**
+ * - `WalletConnectButtonComponent` - Ready-to-use wallet connection button
+ * - `WalletSessionDisplayComponent` - Display connected session information
+ * - `WalletTransactionStatusComponent` - Transaction status indicator
+ * - `AccountSelectorComponent` - Multi-account dropdown selector
+ * - `WalletAccountDisplayComponent` - Display account details
+ * - `WalletConnectPromptComponent` - Connection prompt UI
+ * - `WalletConnectedGuardComponent` - Guard component for protected routes
+ * - `WalletConnectionModalComponent` - Multi-protocol connection modal
+ *
+ * **Directives:**
+ * - `WalletContextDirective` (*walletContext) - Structural directive for wallet context
+ * - `WalletConnectedDirective` (*walletConnected) - Conditional rendering based on connection
+ * - `WalletEventsDirective` (walletEvents) - Listen to wallet events
+ *
+ * **Services:**
+ * - `UnifiedWalletService` - Multi-protocol wallet service (recommended)
+ * - `WalletEventBus` - Event system for wallet lifecycle
+ * - `WalletContextService` - Centralized wallet context
+ * - `TransactionService` - Transaction helper utilities
+ *
+ * **Usage:**
+ *
+ * Import this module in your app's main module:
+ *
+ * ```typescript
+ * import { NgModule } from '@angular/core';
+ * import { BrowserModule } from '@angular/platform-browser';
+ * import { IonicModule } from '@ionic/angular';
+ * import { HsuiteWalletModule } from '@hsuite/native-connect-angular';
+ * import { AppComponent } from './app.component';
+ *
+ * @NgModule({
+ *   declarations: [AppComponent],
+ *   imports: [
+ *     BrowserModule,
+ *     IonicModule.forRoot(),
+ *     HsuiteWalletModule, // Add this
+ *   ],
+ *   bootstrap: [AppComponent],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * Then use components in your templates:
+ *
+ * ```html
+ * <wallet-connect-button
+ *   [walletConnectProjectId]="'YOUR_PROJECT_ID'"
+ *   [showSessionInfo]="true">
+ * </wallet-connect-button>
+ *
+ * <wallet-session-display></wallet-session-display>
+ *
+ * <wallet-account-selector
+ *   [selectedAddress]="currentAccount"
+ *   (accountChanged)="onAccountChange($event)">
+ * </wallet-account-selector>
+ * ```
+ *
+ * **Note:** This module is designed for module-based Angular apps. If you're using
+ * Angular standalone components (recommended for new projects), you can import
+ * components individually instead:
+ *
+ * ```typescript
+ * import { WalletConnectButtonComponent } from '@hsuite/native-connect-angular';
+ *
+ * @Component({
+ *   standalone: true,
+ *   imports: [WalletConnectButtonComponent],
+ *   // ...
+ * })
+ * export class MyComponent {}
+ * ```
+ */
+@NgModule({
+  imports: [
+    CommonModule,
+    IonicModule,
+    // Import all standalone components
+    WalletConnectButtonComponent,
+    WalletSessionDisplayComponent,
+    WalletTransactionStatusComponent,
+    AccountSelectorComponent,
+    AccountListComponent,
+    AccountFilterComponent,
+    AccountActionsComponent,
+    WalletAccountDisplayComponent,
+    WalletConnectPromptComponent,
+    WalletConnectedGuardComponent,
+    WalletConnectionModalComponent,
+    // Import all standalone directives
+    WalletContextDirective,
+    WalletConnectedDirective,
+    WalletEventsDirective,
+  ],
+  exports: [
+    // Export all components for use in module-based apps
+    WalletConnectButtonComponent,
+    WalletSessionDisplayComponent,
+    WalletTransactionStatusComponent,
+    AccountSelectorComponent,
+    AccountListComponent,
+    AccountFilterComponent,
+    AccountActionsComponent,
+    WalletAccountDisplayComponent,
+    WalletConnectPromptComponent,
+    WalletConnectedGuardComponent,
+    WalletConnectionModalComponent,
+    // Export all directives
+    WalletContextDirective,
+    WalletConnectedDirective,
+    WalletEventsDirective,
+  ],
+  // NOTE: Services are NOT provided here because they already have providedIn: 'root'
+  // Providing them here would cause a double-provider error
+})
+export class HsuiteWalletModule {}

package/src/lib/models/connection-config.model.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 Configuration models for different connection protocols.
+ *
+ * @module models/connection-config
+ *
+ * @description
+ * Defines configuration types and type guards for wallet connection protocols.
+ * Each provider type has its own configuration interface with protocol-specific
+ * options. The ConnectionConfig union type allows type-safe handling of
+ * different provider configurations.
+ *
+ * **Configuration Types:**
+ * - {@link HsuiteNativeConfig} - HSuite Native Connect protocol
+ * - {@link WalletConnectV2Config} - WalletConnect v2 protocol
+ * - {@link MobileNativeConfig} - P2P Native mobile connections
+ */
+
+import type { HsuiteNativeConfig, WalletConnectV2Config } from './provider-types';
+
+/**
+ * Union type of all connection configurations.
+ *
+ * @description
+ * Represents any valid connection configuration for the supported wallet providers.
+ * Use type guards to narrow to specific config types when needed.
+ */
+export type ConnectionConfig = HsuiteNativeConfig | WalletConnectV2Config;
+
+/**
+ * Type guard for HSuite Native configuration.
+ *
+ * @description
+ * Narrows a ConnectionConfig to HsuiteNativeConfig based on the type property.
+ *
+ * @param config - Configuration to check
+ *
+ * @returns True if config is HsuiteNativeConfig
+ */
+export function isHsuiteNativeConfig(config: ConnectionConfig): config is HsuiteNativeConfig {
+  return config.type === 'hsuite-native';
+}
+
+/**
+ * Type guard for WalletConnect v2 configuration.
+ *
+ * @description
+ * Narrows a ConnectionConfig to WalletConnectV2Config based on the type property.
+ *
+ * @param config - Configuration to check
+ *
+ * @returns True if config is WalletConnectV2Config
+ */
+export function isWalletConnectV2Config(config: ConnectionConfig): config is WalletConnectV2Config {
+  return config.type === 'walletconnect-v2';
+}