@hsuite/client-types

A comprehensive type system and validation library for Smart Node client operations. This library provides type definitions, interfaces, and runtime validation for client configuration and operations within the Smart Node ecosystem, supporting multiple distributed ledger networks.

Installation

npm install @hsuite/client-types

Features

Type-safe client configuration interfaces - Comprehensive TypeScript interfaces for client setup
Multi-ledger support - Configuration for multiple blockchain networks (Hashgraph, Ripple, etc.)
Runtime validation - Robust validation for client options with proper error handling
Swagger/OpenAPI documentation - Automatic API documentation generation support
Comprehensive JSDoc documentation - Detailed inline documentation for all types and interfaces
Modular architecture - Separated interfaces and models for clean separation of concerns

Dependencies

Peer Dependencies

@nestjs/common: ^10.4.2
@nestjs/core: ^10.4.2
@hsuite/hashgraph-types: ^2.0.3

Dependencies

@hsuite/nestjs-swagger: ^1.0.3

Dev Dependencies

@compodoc/compodoc: ^1.1.23

Usage

Basic Configuration

import { IClient, Client } from '@hsuite/client-types';
import { ChainType, LedgerNetwork } from '@hsuite/smart-ledgers';

// Using interfaces for type safety
const options: IClient.IOptions = {
  enabled: true,
  baseUrl: "https://api.smartnode.example.com",
  ledgers: {
    [ChainType.HASHGRAPH]: {
      chain: ChainType.HASHGRAPH,
      network: LedgerNetwork.HEDERA_TESTNET,
      credentials: {
        accountId: "0.0.123456",
        privateKey: "302e020100300506032b657004220420...",
        publicKey: "302a300506032b6570032100..."
      },
      options: {
        maxRetries: 3,
        timeout: 30000
      }
    }
  }
};

// Using models for runtime validation
const clientOptions = new Client.Options(options);

Multi-Ledger Configuration

import { ChainType, LedgerNetwork } from '@hsuite/smart-ledgers';

const multiLedgerOptions: IClient.IOptions = {
  enabled: true,
  baseUrl: "https://api.smartnode.example.com",
  ledgers: {
    [ChainType.HASHGRAPH]: {
      chain: ChainType.HASHGRAPH,
      network: LedgerNetwork.HEDERA_MAINNET,
      credentials: {
        accountId: "0.0.789012",
        privateKey: "302e020100300506032b657004220420...",
        publicKey: "302a300506032b6570032100..."
      }
    },
    [ChainType.RIPPLE]: {
      chain: ChainType.RIPPLE,
      network: LedgerNetwork.XRPL_TESTNET,
      credentials: {
        address: "rUocf1ixKzTuEe34kmVhRvGqNCofY1NJzV",
        seed: "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9"
      }
    }
  }
};

API Documentation

IClient Namespace

The IClient namespace provides interfaces and types for client operations:

IClient.IOptions

Configuration interface for Smart Node client setup:

enabled (boolean): Controls whether the client is active and processing requests
baseUrl (string): The root URL for all API calls made by the Smart Node client
ledgers (Record<ChainType, ILedgerConfig>): Configuration for multiple blockchain networks

Ledger Configuration Properties:

chain: The blockchain type (hashgraph, ripple, etc.)
network: Network environment (mainnet, testnet, etc.)
credentials: Authentication credentials specific to each chain type
options: Optional network-specific configuration parameters

Client Namespace

The Client namespace provides concrete implementations with runtime validation:

Client.Options

A class that extends _Options with comprehensive runtime validation:

Runtime validation of all configuration parameters
Type-safe instantiation with proper error handling
Swagger/OpenAPI decorators for automatic API documentation
Environment variable validation for ledger configurations

Constructor Validation:

Validates ledger configuration completeness
Ensures baseUrl is a valid HTTP(S) URL
Throws descriptive errors for invalid configurations

Error Handling

The library provides robust error handling:

try {
  const clientOptions = new Client.Options({
    enabled: true,
    baseUrl: "invalid-url", // This will throw an error
    ledgers: {}
  });
} catch (error) {
  console.error('Configuration error:', error.message);
  // Error: Invalid base URL
}

Architecture

src/
├── index.ts                                    # Main entry point
├── interfaces/
│   ├── client.namespace.ts                     # IClient namespace definition
│   └── interfaces/
│       └── client.options.interface.ts         # Client options interface
└── models/
    ├── client.namespace.ts                     # Client namespace definition
    └── models/
        └── client.options.model.ts             # Client options model implementation

Development

Documentation Generation

Generate comprehensive documentation using Compodoc:

npm run compodoc

Check documentation coverage:

npm run compodoc:coverage

Best Practices

Always use interfaces for type definitions - Import from IClient namespace
Use models for runtime validation - Instantiate Client.Options for validation
Handle configuration errors - Wrap instantiation in try-catch blocks
Validate environment variables - Ensure required ledger configurations are present

Version

Current version: 2.0.3

Changelog

See CHANGELOG.md for version history and updates.

License

This package is part of the HSuite Enterprise ecosystem.