@hsuite/native-connect-angular 1.0.0

package/src/lib/models/provider-types.ts

@@ -0,0 +1,164 @@
+/**
+ * @file Type definitions for wallet connection providers.
+ *
+ * @module models/provider-types
+ *
+ * @description
+ * Defines the core type definitions used throughout the Angular SDK for wallet
+ * provider management. Includes provider types, connection status, metadata
+ * interfaces, and configuration interfaces for each supported protocol.
+ *
+ * **Provider Types:**
+ * - `hsuite-native` - HSuite Native Connect protocol
+ * - `walletconnect-v2` - WalletConnect v2 protocol
+ * - `mobile-native` - P2P Native mobile connections
+ *
+ * **Connection Status Lifecycle:**
+ * ```
+ * idle -> connecting -> connected -> disconnecting -> disconnected
+ *                  \-> error
+ * ```
+ */
+
+/**
+ * Supported wallet connection protocol types.
+ *
+ * @description
+ * Identifies the wallet connection protocol used by a provider.
+ * Each type has different capabilities and configuration requirements.
+ *
+ * - `hsuite-native` - Direct HSuite wallet connections via Nostr/WebRTC
+ * - `walletconnect-v2` - WalletConnect v2 protocol for mobile wallets
+ * - `mobile-native` - Direct P2P connections to mobile wallets
+ */
+export type ProviderType = 'hsuite-native' | 'walletconnect-v2' | 'mobile-native';
+
+/**
+ * Connection status for a provider.
+ *
+ * @description
+ * Tracks the lifecycle state of a wallet connection. UI components can
+ * use this to show appropriate feedback (loading spinners, error messages, etc.).
+ *
+ * **Status Values:**
+ * - `idle` - Not connected, no connection attempt in progress
+ * - `connecting` - Connection attempt in progress
+ * - `connected` - Successfully connected to wallet
+ * - `disconnecting` - Disconnection in progress
+ * - `disconnected` - Previously connected, now disconnected
+ * - `error` - Connection failed
+ */
+export type ConnectionStatus =
+  | 'idle'
+  | 'connecting'
+  | 'connected'
+  | 'disconnecting'
+  | 'disconnected'
+  | 'error';
+
+/**
+ * Provider metadata for display purposes.
+ *
+ * @description
+ * Contains display information about a wallet provider, used by UI components
+ * to show provider information in connection dialogs and account selectors.
+ */
+export interface ProviderMetadata {
+  id?: string;
+  name: string;
+  type: ProviderType;
+  description: string;
+  iconUrl?: string;
+  icon?: string;
+  supportsMultipleAccounts?: boolean;
+  features?: string[];
+}
+
+/**
+ * Production HSuite Wallet URL.
+ *
+ * @description
+ * Single source of truth for the wallet origin the SDK targets when a consuming
+ * dApp does not supply its own `walletUrl`. Point local development at a dev
+ * server by passing an explicit `walletUrl` (e.g. `http://localhost:8100`) on the
+ * connection config or UI component; the SDK default must stay production-safe so
+ * published dApps never open the wallet on localhost.
+ */
+export const DEFAULT_WALLET_URL = 'https://wallet.hsuite.app';
+
+/**
+ * HSuite Native Connect configuration.
+ *
+ * @description
+ * Configuration for connecting via the HSuite Native protocol. This protocol
+ * uses Nostr for discovery and WebRTC for direct P2P communication.
+ *
+ * **Required Fields:**
+ * - `type` - Must be 'hsuite-native'
+ * - `appId` - Unique identifier for your dApp
+ * - `appName` - Display name for your dApp
+ * - `ledgerId` - Target blockchain ('hedera' or 'xrpl')
+ * - `networkId` - Target network (e.g., 'testnet', 'mainnet')
+ */
+export interface HsuiteNativeConfig {
+  type: 'hsuite-native';
+  appId: string;
+  appName: string;
+  ledgerId: string;
+  networkId: string;
+  appUrl?: string;
+  appIconUrl?: string;
+  /** Wallet origin to open. Defaults to {@link DEFAULT_WALLET_URL} (production); set to a dev server for local testing. */
+  walletUrl?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * WalletConnect v2 configuration.
+ *
+ * @description
+ * Configuration for connecting via WalletConnect v2 protocol. Requires a
+ * WalletConnect Cloud project ID obtained from https://cloud.walletconnect.com.
+ *
+ * **Required Fields:**
+ * - `type` - Must be 'walletconnect-v2'
+ * - `projectId` - WalletConnect Cloud project ID
+ * - `ledgerId` - Target blockchain ('hedera' or 'xrpl')
+ * - `networkId` - Target network (e.g., 'hedera:testnet')
+ */
+export interface WalletConnectV2Config {
+  type: 'walletconnect-v2';
+  projectId: string; // WalletConnect Cloud project ID - REQUIRED
+  ledgerId: 'hedera' | 'xrpl'; // Which ledger to connect to
+  networkId: string; // e.g., 'hedera:testnet' or 'xrpl:testnet'
+  appName?: string;
+  appDescription?: string;
+  appIconUrl?: string;
+}
+
+/**
+ * Mobile Native P2P configuration.
+ *
+ * @description
+ * Configuration for direct P2P connections to mobile wallets. This protocol
+ * bypasses relay servers for direct device-to-device communication.
+ *
+ * All fields are optional as the P2P provider can operate with defaults.
+ */
+export interface MobileNativeConfig {
+  type: 'mobile-native';
+  appId?: string;
+  appName?: string;
+  ledgerId?: string;
+  networkId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Union type of all connection configurations.
+ *
+ * @description
+ * Represents any valid connection configuration for the supported wallet providers.
+ * Use type guards from connection-config.model.ts to narrow to specific config types.
+ */
+export type ConnectionConfig = HsuiteNativeConfig | WalletConnectV2Config | MobileNativeConfig;

package/src/lib/models/unified-account.model.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 Unified account model that works across all wallet providers.
+ *
+ * @module models/unified-account
+ *
+ * @description
+ * Defines the UnifiedAccount interface that provides a consistent representation
+ * of blockchain accounts regardless of the underlying wallet provider or ledger type.
+ * This normalization allows dApps to work with accounts uniformly whether they come
+ * from HSuite Native, WalletConnect, or P2P Native connections.
+ *
+ * **Key Properties:**
+ * - `id` - Unique identifier combining provider and address
+ * - `address` - Blockchain-specific account identifier
+ * - `ledgerId` - Which blockchain ('hedera', 'xrpl')
+ * - `networkId` - Which network ('testnet', 'mainnet')
+ * - `providerId` - Which provider manages this account
+ * - `metadata` - Provider-specific additional data
+ */
+
+import type { ProviderType } from './provider-types';
+
+/**
+ * Unified account representation across all wallet providers.
+ *
+ * @description
+ * A normalized account interface that provides consistent access to account
+ * properties regardless of the underlying wallet type. All connected accounts
+ * from all providers are represented using this interface.
+ */
+export interface UnifiedAccount {
+  /** Unique identifier for this account */
+  id: string;
+
+  /** Account address/public key */
+  address: string;
+
+  /** Human-readable label */
+  label?: string;
+
+  /** Ledger ID (e.g., 'hedera', 'xrpl') */
+  ledgerId: string;
+
+  /** Network ID (e.g., 'hedera:testnet', 'xrpl:mainnet') */
+  networkId: string;
+
+  /** Provider that manages this account */
+  providerId: string;
+  providerType: ProviderType;
+
+  /** Optional metadata from the provider */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Account with balance information.
+ *
+ * @description
+ * Extension of UnifiedAccount that includes balance data for display purposes.
+ * Used by UI components that need to show account balances.
+ */
+export interface AccountWithBalance extends UnifiedAccount {
+  balance?: string;
+  balanceFormatted?: string;
+  currencySymbol?: string;
+}

package/src/lib/models/wallet-context.model.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 Unified wallet context model for declarative state access.
+ *
+ * @module models/wallet-context
+ *
+ * @description
+ * Defines the WalletContext interface that provides a single, cohesive interface
+ * for all wallet state. This model eliminates the need to manually track multiple
+ * signals across different services by aggregating all wallet information.
+ *
+ * The WalletContext is the primary data structure used by:
+ * - {@link WalletContextService} to compute and expose wallet state
+ * - {@link WalletContextDirective} to provide context to templates
+ * - {@link WalletConnectedDirective} for conditional rendering
+ */
+
+import type { UnifiedAccount } from './unified-account.model';
+import type { BaseWalletProvider } from '../providers/base-wallet-provider';
+
+/**
+ * Unified wallet context interface.
+ *
+ * @description
+ * Aggregates all wallet state into a single, reactive context object.
+ * Used by `*walletContext` and `*walletConnected` directives to provide
+ * declarative state access in templates.
+ *
+ * **Properties:**
+ * - `isConnected` - True if any account is available
+ * - `activeAccount` - Currently selected account (null if none)
+ * - `allAccounts` - All accounts from all providers
+ * - `sessions` - Active sessions with metadata
+ * - `providers` - All registered providers
+ * - `connectedProviders` - Only providers with active connections
+ */
+export interface WalletContext {
+  /**
+   * Whether unknown wallet provider is currently connected
+   */
+  isConnected: boolean;
+
+  /**
+   * The currently active account across all providers
+   * Null if no account is selected
+   */
+  activeAccount: UnifiedAccount | null;
+
+  /**
+   * All accounts from all connected providers
+   * Empty array if no providers are connected
+   */
+  allAccounts: UnifiedAccount[];
+
+  /**
+   * All active sessions across providers
+   * For HSuite Native: single session with multiple accounts
+   * For WalletConnect: multiple sessions, one per wallet
+   */
+  sessions: WalletSession[];
+
+  /**
+   * All registered wallet providers
+   * Includes both connected and disconnected providers
+   */
+  providers: BaseWalletProvider[];
+
+  /**
+   * Only the currently connected providers
+   */
+  connectedProviders: BaseWalletProvider[];
+}
+
+/**
+ * Session information for display and management.
+ *
+ * @description
+ * Represents a single wallet session, which may contain multiple accounts.
+ * For HSuite Native, there's typically one session with multiple accounts.
+ * For WalletConnect, there may be multiple sessions (one per paired wallet).
+ */
+export interface WalletSession {
+  /**
+   * Unique provider identifier
+   */
+  providerId: string;
+
+  /**
+   * Provider type (hsuite-native, walletconnect-v2)
+   */
+  providerType: string;
+
+  /**
+   * Human-readable provider name
+   */
+  providerName: string;
+
+  /**
+   * Accounts in this session
+   */
+  accounts: UnifiedAccount[];
+
+  /**
+   * Additional session metadata
+   */
+  metadata?: {
+    sessionKey?: string;
+    topic?: string;
+    networkId?: string;
+    [key: string]: any;
+  };
+}

package/src/lib/models/wallet-events.model.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 Event types for the WalletEventBus system.
+ *
+ * @module models/wallet-events
+ *
+ * @description
+ * Defines the event interfaces used by the WalletEventBus system. These events
+ * allow dApps to react to wallet-level changes that happen outside direct user
+ * interaction, such as wallet-initiated disconnects, session restorations,
+ * and account switches.
+ *
+ * **Event Types:**
+ * - {@link ConnectionEvent} - Provider connected
+ * - {@link DisconnectionEvent} - Provider disconnected
+ * - {@link AccountChangeEvent} - Active account changed
+ * - {@link AccountsUpdateEvent} - Account list updated
+ * - {@link SessionEvent} - Session created/deleted/restored
+ * - {@link ProviderStatusEvent} - Provider status changed
+ * - {@link ProviderErrorEvent} - Provider error occurred
+ *
+ * All events include a `timestamp` field (Unix milliseconds) for ordering
+ * and debugging purposes.
+ */
+
+import type { UnifiedAccount } from './unified-account.model';
+
+/**
+ * Emitted when a provider successfully connects.
+ *
+ * @description
+ * Fired after a wallet connection is established and accounts are available.
+ * Use this event to update UI, fetch balances, or perform post-connection logic.
+ */
+export interface ConnectionEvent {
+  providerId: string;
+  providerType: 'hsuite-native' | 'walletconnect-v2';
+  accounts: UnifiedAccount[];
+  timestamp: number;
+}
+
+/**
+ * Emitted when a provider disconnects.
+ *
+ * @description
+ * Fired when a wallet connection is terminated. Can be user-initiated
+ * (via disconnect button) or wallet-initiated (remote disconnect).
+ *
+ * **Reason Values:**
+ * - `'user_initiated'` - User clicked disconnect in dApp
+ * - `'wallet_initiated_disconnect'` - Wallet app terminated session
+ * - `'session_terminated'` - Session ended by protocol
+ * - `'session_expired'` - Session timed out
+ */
+export interface DisconnectionEvent {
+  providerId: string;
+  providerType: string;
+  sessionKey?: string;
+  reason?:
+    | 'user_initiated'
+    | 'wallet_initiated_disconnect'
+    | 'session_terminated'
+    | 'session_expired'
+    | string;
+  timestamp: number;
+}
+
+/**
+ * Emitted when the active account changes.
+ *
+ * @description
+ * Fired when the user switches between accounts via setActiveAccount() or
+ * account selector UI. Includes both the previous and new account for
+ * comparison and transition logic.
+ */
+export interface AccountChangeEvent {
+  previousAccount: UnifiedAccount | null;
+  newAccount: UnifiedAccount | null;
+  timestamp: number;
+}
+
+/**
+ * Emitted when a provider's account list updates.
+ *
+ * @description
+ * Fired when accounts are added or removed from a provider. This can happen
+ * when the wallet adds new accounts or when the user grants access to
+ * additional accounts.
+ */
+export interface AccountsUpdateEvent {
+  providerId: string;
+  accounts: UnifiedAccount[];
+  totalAccounts: number;
+  timestamp: number;
+}
+
+/**
+ * Emitted for session lifecycle events (created, deleted, restored).
+ *
+ * @description
+ * Fired when a session is created, deleted, or restored. Sessions represent
+ * a logical connection to a wallet, which may contain multiple accounts.
+ *
+ * This same interface is used for:
+ * - `sessionCreated` - New session established
+ * - `sessionDeleted` - Session terminated
+ * - `sessionRestored` - Session restored from storage
+ */
+export interface SessionEvent {
+  providerId: string;
+  sessionKey: string;
+  accounts: UnifiedAccount[];
+  metadata?: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * Emitted when a provider's status changes.
+ *
+ * @description
+ * Fired when a provider transitions between connection states. Useful for
+ * showing loading indicators or status badges.
+ *
+ * **Status Values:**
+ * - `'connecting'` - Connection attempt in progress
+ * - `'connected'` - Successfully connected
+ * - `'disconnected'` - Not connected
+ * - `'error'` - Connection failed
+ */
+export interface ProviderStatusEvent {
+  providerId: string;
+  status: 'connecting' | 'connected' | 'disconnected' | 'error';
+  timestamp: number;
+}
+
+/**
+ * Emitted when a provider encounters an error.
+ *
+ * @description
+ * Fired when a wallet operation fails. Includes the error details and
+ * optional context about what operation failed. Use this to display
+ * error messages to users or for debugging.
+ */
+export interface ProviderErrorEvent {
+  providerId: string;
+  error: Error | string;
+  context?: string;
+  timestamp: number;
+}