# @hsuite/client-types - Client Type Definitions

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

```bash
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

```typescript
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

```typescript
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:

```typescript
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:

```bash
npm run compodoc
```

Check documentation coverage:

```bash
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](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/libs/client-types/CHANGELOG.md) for version history and updates.

## License

This package is part of the HSuite Enterprise ecosystem.

***

<p align="center">Built with ❤️ by the HSuite Team<br>Copyright © 2025 HSuite. All rights reserved.</p>