@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

1. Always use interfaces for type definitions - Import from IClient namespace
2. Use models for runtime validation - Instantiate Client.Options for validation
3. Handle configuration errors - Wrap instantiation in try-catch blocks
4. 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.