@hsuite/client

A comprehensive NestJS module providing client functionality for HSUITE applications, with built-in support for Web3 authentication, node communication, and network resilience.

Features

• 🔐 Web3-based authentication flow

• 🌐 Dynamic node connection management

• 🔄 Automatic network resilience and failover

• 🍪 Session management with cookie support

• ⚡ HTTP client with axios integration

• 🛡️ Secure cryptographic signing

• 📡 Periodic health monitoring

• 🔌 Flexible module configuration

• 🎯 Global module scope support

Installation

npm install @hsuite/client

Peer Dependencies

This module requires the following peer dependencies:

{
  "@nestjs/common": "^10.4.2",
  "@nestjs/core": "^10.4.2"
}

Quick Start

1. Import the module in your app.module.ts:

import { ClientModule } from '@hsuite/client';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    ClientModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        baseUrl: configService.get('CLIENT_BASE_URL'),
        operator: {
          accountId: configService.get('OPERATOR_ID'),
          privateKey: configService.get('OPERATOR_KEY'),
          publicKey: configService.get('OPERATOR_PUBLIC_KEY')
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}

1. Inject and use the ClientService in your components:

@Injectable()
class YourService {
  constructor(private clientService: ClientService) {}

  async yourMethod() {
    // Access authenticated client
    const loginInfo = this.clientService.login;
    
    // Make authenticated requests
    const response = await this.clientService.axios.get('/your-endpoint');
  }
}

API Reference

ClientModule

The main module that provides client functionality.

Methods

• forRootAsync(options: ClientModuleAsyncOptions): Configures the module asynchronously with dependency injection support.

ClientService

Core service for managing client operations and authentication.

Properties

• login: Get current Web3 login credentials

• operator: Get current operator information

• axios: Get configured axios instance for making HTTP requests

Methods

• onModuleInit(): Initializes client connection and authentication

• Private methods handle node connection, network resilience, and data signing

Configuration Options

The module supports three configuration patterns:

1. Factory Function Pattern:

ClientModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    baseUrl: config.get('API_URL'),
    operator: {
      accountId: config.get('OPERATOR_ID'),
      privateKey: config.get('OPERATOR_KEY'),
      publicKey: config.get('OPERATOR_PUBLIC_KEY')
    }
  }),
  inject: [ConfigService]
});

1. Existing Provider Pattern:

ClientModule.forRootAsync({
  useExisting: [ExistingConfigService]
});

1. Class Provider Pattern:

ClientModule.forRootAsync({
  useClass: CustomClientOptionsFactory
});

Features in Detail

Web3 Authentication Flow

The module implements a complete Web3 authentication flow:

1. Requests authentication challenge

2. Signs challenge with operator credentials

3. Submits signed proof for verification

4. Establishes authenticated session

5. Sets up periodic health monitoring

Network Resilience

Built-in support for handling network issues:

• Automatic failover to alternative nodes

• Connection error handling (ECONNREFUSED, ECONNABORTED, ECONNRESET)

• Dynamic node selection

• Session maintenance during node failures

Security Features

• Cryptographic signing of requests

• Secure cookie handling

• Private key management

• Session-based authentication

Documentation

Detailed documentation can be generated using Compodoc:

npm run compodoc

To check documentation coverage:

npm run compodoc:coverage

Dependencies

Core dependencies:

• @hsuite/smart-network-types: "2.0.0"

• @hsuite/auth-types: "2.0.0"

• @hsuite/nestjs-swagger: "2.0.0"

• @hsuite/smart-config: "2.0.0"

Development dependencies:

• @compodoc/compodoc: "^1.1.23"

Version

Current version: 2.0.0

License

This package is part of the HSuite Enterprise solution.

---

Built with ❤️ by the HbarSuite Team Copyright © 2024 HbarSuite. All rights reserved.