HbarSuite Docs
  • Welcome to HbarSuite
  • HbarSuite Developer Documentation
    • HbarSuite Smart Engine Applications
      • @hsuite/cross-chain-exchange
      • @hsuite/dao
        • DAO Application Testing
      • @hsuite/exchange
      • @hsuite/launchpad
      • @hsuite/multisig
      • @hsuite/nft-exchange
      • HSuite Smart App - Enterprise Hedera Application Framework
    • HSuite Libraries
      • @hsuite/api-key - Enterprise API Key Authentication System
      • @hsuite/auth-types
      • @hsuite/auth - Authentication Module
      • @hsuite/client-types
      • @hsuite/client - Client Service Module
      • @hsuite/dkg-types - Distributed Key Generation Type Definitions
      • @hsuite/hashgraph-types - Hedera Hashgraph Type Definitions
      • @hsuite/health - Comprehensive System Health Monitoring
      • @hsuite/helpers - Utility Library
      • @hsuite/ipfs - InterPlanetary File System Integration
      • @hsuite/shared-types - Shared Type Definitions
      • @hsuite/smart-config - Configuration Management
      • @hsuite/smart-ledgers - Multi-Ledger Management
      • @hsuite/smart-network-types - Smart Network Type Definitions
      • @hsuite/smart-transaction-types - Smart Transaction Type Definitions
      • @hsuite/smartnode-sdk - SmartNode Software Development Kit
      • @hsuite/snapshots - Multi-Ledger Token Snapshot Management
      • @hsuite/subscriptions-types - Subscription Management Type Definitions
      • @hsuite/subscriptions - Enterprise Subscription Management System
      • @hsuite/throttler-types - Rate Limiting Type Definitions
      • @hsuite/throttler - Advanced Rate Limiting for NestJS
      • @hsuite/users-types - User Type Definitions
      • @hsuite/users - User Management Module
      • @hsuite/validators-types
  • General Documentation
    • Smart Apps and Interaction
      • Subscription-Based Model
      • Token-Gate Model
    • The Smart Node Network
      • security-layer
      • Type of Validators Explained
      • Understanding Validators in Our System
      • Automating Responses to Network Changes & Key Rotation
      • Ensuring Continuous Operation and Recovery
      • Generating and Sharing Keys Collaboratively
      • Handling Node Expulsion and Replacement
      • Managing Cluster Membership
      • Protecting Secrets with Shamir's Method
      • Security Layer Integration
      • Setting Up Secure Clusters
    • Tokenomics
      • Tokenomics v1
      • Tokenomics V2
    • What is a Smart Node?
  • Restful APIs Documentation
Powered by GitBook
On this page
  • Installation
  • Features
  • Dependencies
  • Peer Dependencies
  • Dependencies
  • Dev Dependencies
  • Usage
  • Basic Configuration
  • Multi-Ledger Configuration
  • API Documentation
  • IClient Namespace
  • Client Namespace
  • Error Handling
  • Architecture
  • Development
  • Documentation Generation
  • Best Practices
  • Version
  • Changelog
  • License
  1. HbarSuite Developer Documentation
  2. HSuite Libraries

@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

License

This package is part of the HSuite Enterprise ecosystem.


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

Previous@hsuite/auth - Authentication ModuleNext@hsuite/client - Client Service Module

Last updated 7 days ago

See for version history and updates.

CHANGELOG.md