npm package: @hsuite/connect-angular
Description: Angular integration SDK for HSuite Wallet - provides direct SDK integration without wrappers
Latest version: 2.0.0

# @hsuite/connect-angular

> Type-safe Angular/Ionic SDK for building multi-chain dApps with unified wallet connectivity via HSuite Channel Protocol and WalletConnect v2.

## Features

- **HSuite Channel Protocol** - Native `hsc:` protocol with Nostr + P2P transport
- **WalletConnect v2** - Universal wallet connectivity
- **Reactive State** - Angular signals for real-time updates
- **Pre-built Components** - Ready-to-use UI components
- **Transaction Builders** - Type-safe transaction construction for Hedera and XRPL
- **Multi-Account Support** - Manage multiple accounts across ledgers

## Quick Start

```bash
# Install in your project
npm install @hsuite/connect-angular
# or
pnpm add @hsuite/connect-angular

# Build from source
pnpm --filter @hsuite/connect-angular build

# Run tests
pnpm --filter @hsuite/connect-angular test
```

---

## Installation & Setup

The SDK supports both **module-based** and **standalone** Angular applications.

### Option A: Module-Based Apps (Traditional Angular)

```typescript
// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { IonicModule } from '@ionic/angular';
import { HsuiteWalletModule } from '@hsuite/connect-angular';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    IonicModule.forRoot(),
    HsuiteWalletModule, // Add this line
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}
```

### Option B: Standalone Components (Modern Angular)

```typescript
// home.component.ts
import { Component, inject } from '@angular/core';
import { 
  WalletConnectButtonComponent,
  WalletSessionDisplayComponent,
  UnifiedWalletService 
} from '@hsuite/connect-angular';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [
    WalletConnectButtonComponent,
    WalletSessionDisplayComponent,
  ],
  template: `
    <wallet-connect-button [walletConnectProjectId]="'YOUR_PROJECT_ID'">
    </wallet-connect-button>
    <wallet-session-display></wallet-session-display>
  `
})
export class HomeComponent {
  wallet = inject(UnifiedWalletService);
}
```

---

## Core Services

### UnifiedWalletService

Central service for multi-protocol wallet management:

```typescript
import { Component, inject } from '@angular/core';
import { UnifiedWalletService } from '@hsuite/connect-angular';

@Component({
  template: `
    <button (click)="connectHsuiteNative()">Connect via HSuite</button>
    <button (click)="connectWalletConnect()">Connect via WalletConnect</button>
    <div *ngIf="account()">Connected: {{ account()!.address }}</div>
  `
})
export class MyComponent {
  wallet = inject(UnifiedWalletService);
  account = this.wallet.activeAccount; // Signal

  // Connect via HSuite Native (hsc: protocol)
  async connectHsuiteNative() {
    await this.wallet.connect('hsuite-native', {
      ledgerId: 'hedera',
      networkId: 'hedera:testnet',
      appId: 'my-dapp',
      appName: 'My dApp',
    });
  }

  // Connect via WalletConnect v2
  async connectWalletConnect() {
    await this.wallet.connect('walletconnect-v2', {
      projectId: 'YOUR_PROJECT_ID',
      ledgerId: 'hedera',
      networkId: 'hedera:testnet'
    });
  }
}
```

#### Convenience Methods

```typescript
const wallet = inject(UnifiedWalletService);

// Connection state
wallet.isConnected();              // boolean - any provider connected?
wallet.getConnectedLedgers();      // string[] - ['hedera', 'xrpl']

// Account management
wallet.getAccountsByLedger('hedera');        // UnifiedAccount[]
wallet.hasAccountsForLedger('xrpl');         // boolean
wallet.getPrimaryAccountForLedger('hedera'); // UnifiedAccount | undefined
wallet.switchAccount(accountId);             // boolean - switch by ID

// Active account (signal)
wallet.activeAccount();  // UnifiedAccount | null
```

---

### ChannelClientService (HSuite Native)

Angular wrapper for the HSuite Channel Protocol:

```typescript
import { Component, inject } from '@angular/core';
import { ChannelClientService } from '@hsuite/connect-angular';

@Component({
  template: `
    <div>State: {{ state() }}</div>
    <div>Transport: {{ transportState() }}</div>
    <div *ngIf="accounts().length">
      Accounts: {{ accounts() | json }}
    </div>
    <button (click)="connect()">Connect</button>
  `
})
export class ChannelComponent {
  private channelService = inject(ChannelClientService);

  // Reactive signals
  readonly state = this.channelService.state;
  readonly transportState = this.channelService.transportState;
  readonly accounts = this.channelService.accounts;

  async connect() {
    const invite = await this.channelService.connect({
      type: 'session',
      appId: 'my-dapp',
      appName: 'My dApp',
      ledgerId: 'hedera',
      networkId: 'hedera:testnet',
    });

    // Open wallet with invite URL
    const walletUrl = this.channelService.getWalletInviteUrl(
      invite,
      'https://wallet.hsuite.io'
    );
    window.open(walletUrl, 'hsuite-wallet');
  }

  async signTransaction(payload: Uint8Array) {
    const result = await this.channelService.signTransaction({
      payload,
      accountAddress: this.accounts()[0].address,
      ledgerId: 'hedera',
      networkId: 'hedera:testnet',
    });
    console.log('Signature:', result.signature);
  }
}
```

#### Channel States

| State | Description |
|-------|-------------|
| `idle` | No active connection |
| `connecting` | Establishing channel |
| `pending` | Waiting for wallet approval |
| `connected` | Session active |
| `error` | Connection failed |

#### Transport States

| State | Description |
|-------|-------------|
| `nostr-only` | Using Nostr relay |
| `upgrading` | Attempting P2P |
| `p2p-connected` | Direct P2P active |
| `p2p-failed` | P2P failed, using Nostr |

---

### HsuiteNativeProvider

Provider implementation for `UnifiedWalletService`:

```typescript
/**
 * HsuiteNativeProvider
 * 
 * Implements BaseWalletProvider for HSuite Native Connect.
 * Uses ChannelClientService internally for channel-based communication.
 * 
 * Features:
 * - Automatic session persistence
 * - P2P transport upgrade
 * - Reactive account synchronization
 */
@Injectable({ providedIn: 'root' })
export class HsuiteNativeProvider extends BaseWalletProvider {
  readonly id = 'hsuite-native';
  
  // Status computed from channel state
  readonly status = computed<ConnectionStatus>(() => {
    const state = this.channelService.state();
    // Maps channel states to provider status
  });

  // Accounts from channel service
  readonly accounts = computed<UnifiedAccount[]>(() => {
    return this.channelService.accounts();
  });
}
```

---

### Transaction Builders

Type-safe transaction construction for Hedera and XRPL:

```typescript
import { Component, inject } from '@angular/core';
import { 
  HederaTransactionBuilderService,
  XrplTransactionBuilderService,
  UnifiedWalletService 
} from '@hsuite/connect-angular';

@Component({...})
export class TransactionComponent {
  private readonly wallet = inject(UnifiedWalletService);
  private readonly hederaBuilder = inject(HederaTransactionBuilderService);
  private readonly xrplBuilder = inject(XrplTransactionBuilderService);
  
  // Build and sign a Hedera HBAR transfer
  async sendHbar() {
    const payload = await this.hederaBuilder.buildSendHbar(
      '0.0.12345',  // from
      '0.0.67890',  // to
      10            // amount in HBAR
    );
    
    const result = await this.wallet.signAndSubmitTransaction({
      payload,
      ledgerId: 'hedera',
      networkId: 'hedera:testnet'
    });
  }
  
  // Build and sign an XRPL payment
  async sendXrp() {
    const payload = await this.xrplBuilder.buildPayment(
      'rAccountSource',  // from
      'rAccountDest',    // to
      '1000000'          // amount in drops (1 XRP)
    );
    
    const result = await this.wallet.signAndSubmitTransaction({
      payload,
      ledgerId: 'xrpl',
      networkId: 'xrpl:testnet'
    });
  }
}
```

#### Hedera Transaction Types

- `buildSendHbar()` - Transfer HBAR
- `buildSendToken()` - Transfer fungible tokens
- `buildSendNft()` - Transfer NFTs
- `buildAssociateToken()` - Associate tokens
- `buildDissociateToken()` - Dissociate tokens
- `buildTokenCreate()` - Create new tokens
- `buildTokenMint()` / `buildTokenBurn()` - Mint/burn tokens
- `buildTopicCreate()` / `buildTopicMessageSubmit()` - HCS topics
- `buildBatchTransaction()` - Batch transactions

#### XRPL Transaction Types

- `buildPayment()` - XRP or token payments
- `buildTrustSet()` - Establish trust lines
- `buildOfferCreate()` / `buildOfferCancel()` - DEX orders
- `buildEscrowCreate()` / `buildEscrowFinish()` / `buildEscrowCancel()` - Escrows
- `buildNFTMint()` / `buildNFTBurn()` - NFT operations
- `buildBatchTransaction()` - Batch transactions

---

## Components

| Component | Selector | Description |
|-----------|----------|-------------|
| `WalletConnectButtonComponent` | `<wallet-connect-button>` | Ready-to-use connection button |
| `WalletSessionDisplayComponent` | `<wallet-session-display>` | Display session information |
| `WalletTransactionStatusComponent` | `<wallet-transaction-status>` | Transaction status indicator |
| `AccountSelectorComponent` | `<wallet-account-selector>` | Multi-account dropdown |
| `WalletAccountDisplayComponent` | `<wallet-account-display>` | Account details display |
| `WalletConnectPromptComponent` | `<wallet-connect-prompt>` | Connection prompt UI |
| `WalletConnectedGuardComponent` | `<wallet-connected-guard>` | Guard for protected routes |
| `WalletConnectionModalComponent` | `<hsuite-wallet-connection-modal>` | Multi-protocol modal |

---

## Directives

| Directive | Usage | Description |
|-----------|-------|-------------|
| `WalletContextDirective` | `*walletContext` | Provides wallet context to templates |
| `WalletConnectedDirective` | `*walletConnected` | Conditional rendering based on connection |
| `WalletEventsDirective` | `walletEvents` | Listen to wallet events |

---

## Services

| Service | Description |
|---------|-------------|
| `UnifiedWalletService` | Multi-protocol wallet management |
| `ChannelClientService` | HSuite Channel Protocol client |
| `WalletEventBus` | Event system for wallet lifecycle |
| `WalletContextService` | Centralized wallet context |
| `TransactionService` | Transaction helper utilities |
| `WalletErrorHandler` | Automatic error handling |
| `LoggerService` | Scoped logging with production filtering |
| `HederaTransactionBuilderService` | Build Hedera transactions |
| `XrplTransactionBuilderService` | Build XRPL transactions |

---

## Directory Structure

```
src/lib/
├── components/                    # UI components
│   ├── account-selector/          # Multi-account dropdown
│   ├── wallet-connect-button/     # Connection button
│   ├── wallet-session-display/    # Session info display
│   └── ...
├── directives/                    # Structural directives
│   ├── wallet-connected.directive.ts
│   ├── wallet-context.directive.ts
│   └── wallet-events.directive.ts
├── models/                        # TypeScript interfaces
│   ├── connection-config.model.ts
│   ├── provider-types.ts
│   ├── unified-account.model.ts
│   └── wallet-events.model.ts
├── providers/                     # Wallet providers
│   ├── hsuite-native/             # HSuite Channel Protocol
│   │   └── channel-client.service.ts
│   ├── hsuite-native-provider.ts  # Provider implementation
│   └── walletconnect/             # WalletConnect v2
├── services/                      # Core services
│   ├── unified-wallet.service.ts
│   ├── transaction-builders/
│   │   ├── hedera-transaction-builder.service.ts
│   │   └── xrpl-transaction-builder.service.ts
│   └── ...
└── transports/                    # Transport implementations
    └── chrome-extension-transport.ts
```

---

## Scripts

| Command | Description |
|---------|-------------|
| `pnpm build` | Build library to `dist/` |
| `pnpm test` | Run Vitest tests |
| `pnpm test -- --watch` | Watch mode |
| `pnpm lint` | Lint code |

---

## Documentation

📚 **Full Documentation**: [docs/packages/angular-sdk.md](../../docs/packages/angular-sdk.md)

For comprehensive guides including:
- Complete API reference
- Multi-protocol integration
- Channel Protocol integration
- UI components and directives
- Event system
- Best practices

---

## Related

- [Main README](../../readme.md) - Project overview
- [Documentation Index](../../docs/readme.md) - All documentation
- [Native Wallet SDK](../native-wallet-sdk/readme.md) - Core SDK
- [Channel Protocol](../../docs/native-wallet-sdk/channel-protocol.md) - Protocol specification
- [Companion dApp](../../docs/apps/hsuite-wallet-dapp.md) - Working example

---

**Status:** ✅ Production Ready | **Framework:** Angular 20+ | **Protocols:** HSuite Native + WalletConnect v2 | **Tests:** 277+ passing