@ioka-technologies/asyncapi-ts-client-template 0.0.7 → 0.0.10

package/README.md

@@ -1,163 +1,424 @@
-# TypeScript AsyncAPI Client Generator Template
+# TypeScript AsyncAPI Client Generator
 
-A production-ready AsyncAPI code generator template for TypeScript clients. This template generates fully-typed TypeScript clients from AsyncAPI specifications with support for WebSocket and HTTP transports, compatible with the rust-asyncapi patterns.
+**Type safety across the network boundary - the missing piece of full-stack AsyncAPI development**
 
-## 🎯 Key Features
+This template solves the fundamental challenge of maintaining type safety and API consistency between async servers and their clients. Instead of hand-writing clients that drift out of sync, we generate **production-ready TypeScript clients** that automatically stay in perfect alignment with your AsyncAPI servers.
 
-- 🦀 **Rust-AsyncAPI Compatible**: Generated clients are type-compatible with rust-asyncapi servers
-- 🔄 **Multiple Transports**: WebSocket and HTTP support with automatic transport selection
-- 🛡️ **Type Safe**: Full TypeScript support with generated interfaces from AsyncAPI schemas
-- 🔧 **Smart Method Names**: Automatic sanitization of operation names to valid JavaScript identifiers
-- 🔌 **Auto Reconnection**: WebSocket reconnection with configurable retry logic
-- 🔐 **Authentication**: JWT, API Key, and custom authentication support
-- ⚡ **Promise Based**: Modern async/await API
-- 📦 **Zero Config**: Works out of the box with sensible defaults
-- 🧪 **Well Tested**: Comprehensive examples and documentation
+## 🎯 The Full-Stack Vision
 
-## 🚀 Quick Start
+**The Problem**: Traditional async API development breaks down at the client boundary. You have a perfectly typed server, but clients are hand-written, error-prone, and constantly fall out of sync with server changes.
 
-### Prerequisites
+**Our Solution**: **Automatic Type-Safe Client Generation**
 
-- [AsyncAPI CLI](https://github.com/asyncapi/cli) installed
-- [Node.js](https://nodejs.org/) 16+ installed
+```typescript
+// Generated client with perfect server compatibility
+const client = new ChatClient({
+    transport: 'websocket',  // or 'http' - same interface
+    websocket: { url: 'wss://api.example.com', reconnect: true }
+});
+
+// Type-safe method calls with IntelliSense
+const user = await client.createUser({
+    name: "John",     // ✅ TypeScript knows this is required
+    email: "john@...", // ✅ TypeScript validates email format
+    age: 25           // ✅ TypeScript knows this is optional
+});
+
+// Response is fully typed - no runtime surprises
+console.log(user.id);        // ✅ TypeScript provides autocomplete
+console.log(user.createdAt); // ✅ TypeScript knows this is a Date
+```
+
+**Why This Changes Everything**:
+- 🔄 **Perfect Sync**: Client and server types are generated from the same AsyncAPI spec
+- 🛡️ **Compile-Time Safety**: Catch API mismatches before they reach production
+- 🚀 **Zero Configuration**: Works out of the box with intelligent defaults
+- 🌐 **Transport Agnostic**: Same code works over WebSocket or HTTP
+- 🔌 **Production Ready**: Built-in reconnection, error handling, and monitoring
+
+## 🚀 The 2-Minute Full-Stack Experience
+
+**Goal**: Experience the power of synchronized client-server development.
 
-### Generate Your Client
+### The Business Scenario
+You have a Rust AsyncAPI server handling user management. You need web and mobile clients that stay perfectly in sync as the API evolves.
 
+### Step 1: Generate Type-Safe Client (30 seconds)
 ```bash
 # Install AsyncAPI CLI
 npm install -g @asyncapi/cli
 
-# Generate TypeScript client from your AsyncAPI specification
-asyncapi generate fromTemplate asyncapi.yaml ./template -o ./my-client
+# Generate client from the SAME spec as your Rust server
+asyncapi generate fromTemplate your-user-api.yaml ./ts-client -o user-client
 
-# Install dependencies and build
-cd my-client
-npm install
+# Install and build
+cd user-client && npm install && npm run build
+```
+
+### Step 2: Use in Your Application (1 minute)
+```typescript
+// React/Vue/Angular - works everywhere
+import { UserApiClient } from './user-client';
+
+const client = new UserApiClient({
+    transport: 'websocket',
+    websocket: {
+        url: 'wss://api.yourcompany.com',
+        auth: { jwt: getAuthToken() },
+        reconnect: true  // Production-ready resilience
+    }
+});
+
+// Type-safe API calls with IntelliSense
+const App = () => {
+    const [users, setUsers] = useState([]);
+
+    useEffect(() => {
+        client.connect();
+
+        // Real-time updates
+        client.onUserCreated((user) => {
+            setUsers(prev => [...prev, user]);
+        });
+
+        return () => client.disconnect();
+    }, []);
+
+    const createUser = async (userData) => {
+        // Fully type-safe - catches errors at compile time
+        const newUser = await client.createUser({
+            name: userData.name,     // Required field
+            email: userData.email,   // Validated format
+            preferences: {           // Nested object support
+                newsletter: true,
+                theme: 'dark'
+            }
+        });
+
+        // Response is fully typed
+        console.log(`Created user ${newUser.id} at ${newUser.createdAt}`);
+    };
+};
+```
+
+### Step 3: Experience the Magic (30 seconds)
+```bash
+# Server team updates AsyncAPI spec (adds new field)
+# Regenerate client
+asyncapi generate fromTemplate updated-api.yaml ./ts-client -o user-client --force-write
+
+# TypeScript compiler immediately shows what changed
 npm run build
+# ✅ New fields are available with IntelliSense
+# ✅ Removed fields cause compile errors (catch before production)
+# ✅ Changed types are automatically updated
 ```
 
-## 📁 Project Structure
+**Result**: Your client and server are always perfectly synchronized. API changes are caught at compile time, not in production.
+
+## 📁 Generated Client Architecture
+
+**The Strategic Design**: Every generated file serves the full-stack development experience.
+
+```
+user-client/                          # Your generated TypeScript client
+├── package.json                     # NPM package ready for publishing
+├── tsconfig.json                    # TypeScript configuration
+├── README.md                        # Client-specific documentation
+├── USAGE.md                         # Integration examples
+├── src/
+│   ├── index.ts                    # Public API exports
+│   ├── client.ts                   # Main client class
+│   ├── models.ts                   # Generated TypeScript interfaces
+│   ├── transports.ts               # Transport layer exports
+│   └── runtime/                    # Production-ready runtime
+│       ├── types.ts               # Core type definitions
+│       ├── errors.ts              # Typed error classes
+│       └── transports/            # Transport implementations
+│           ├── factory.ts         # Intelligent transport selection
+│           ├── websocket.ts       # Real-time WebSocket transport
+│           └── http.ts            # Reliable HTTP transport
+├── examples/                        # Ready-to-run examples
+│   ├── websocket-example.ts        # WebSocket integration
+│   ├── http-example.ts             # HTTP integration
+│   └── react-example.tsx           # React component example
+└── dist/                           # Compiled JavaScript (after build)
+    ├── index.js                    # ES modules
+    ├── index.d.ts                  # TypeScript declarations
+    └── ...                         # All compiled outputs
+```
+
+### The Architecture Strategy
+
+**Generated Types** (src/models.ts): Perfect server compatibility
+- **Synchronized**: Generated from the same AsyncAPI spec as your Rust server
+- **Type-safe**: Catch mismatches at compile time, not runtime
+- **Rich**: Support for nested objects, enums, optional fields, validation
+
+**Transport Layer** (src/runtime/transports/): Production resilience
+- **WebSocket**: Real-time communication with automatic reconnection
+- **HTTP**: Reliable request/response with retry logic
+- **Unified Interface**: Same API regardless of transport choice
+
+**Client Class** (src/client.ts): Developer experience
+- **IntelliSense**: Full autocomplete for all operations
+- **Promise-based**: Modern async/await patterns
+- **Event-driven**: Subscribe to real-time updates
+- **Error handling**: Typed exceptions for robust error handling
 
+### Integration Patterns
+
+**React/Vue/Angular Integration**:
+```typescript
+// Hook-based integration
+const useUserApi = () => {
+    const [client] = useState(() => new UserApiClient({
+        transport: 'websocket',
+        websocket: { url: process.env.REACT_APP_API_URL }
+    }));
+
+    useEffect(() => {
+        client.connect();
+        return () => client.disconnect();
+    }, []);
+
+    return client;
+};
 ```
-ts-asyncapi/
-├── README.md                           # This file
-├── USAGE.md                           # Comprehensive usage guide
-├── PROJECT_SUMMARY.md                 # Project summary and achievements
-├── example-api.yaml                   # Example AsyncAPI specification
-├── package.json                       # Project dependencies
-└── template/                         # AsyncAPI Generator Template
-    ├── package.json                  # Template dependencies
-    ├── index.jsx                     # Template entry point
-    ├── README.md                     # Template documentation
-    ├── test.js                       # Template testing script
-    └── components/                   # Template components
-        ├── PackageJson.js            # Package.json generator
-        ├── IndexFile.js              # Main index.ts generator
-        ├── ClientFile.js             # Client class generator
-        ├── ModelsFile.js             # Type definitions generator
-        ├── TransportsFile.js         # Transport exports
-        ├── TsConfigFile.js           # TypeScript config generator
-        ├── ReadmeFile.js             # Generated README
-        ├── UsageFile.js              # Generated usage docs
-        ├── examples/                 # Example generators
-        │   ├── WebSocketExample.js   # WebSocket example generator
-        │   └── HttpExample.js        # HTTP example generator
-        └── runtime/                  # Runtime implementation generators
-            ├── RuntimeTypes.js       # Core type definitions
-            ├── RuntimeErrors.js      # Error classes
-            ├── TransportFactory.js   # Transport factory
-            ├── WebSocketTransport.js # WebSocket implementation
-            └── HttpTransport.js      # HTTP implementation
+
+**Node.js Backend Integration**:
+```typescript
+// Server-to-server communication
+const apiClient = new UserApiClient({
+    transport: 'http',
+    http: {
+        baseUrl: 'https://internal-api.company.com',
+        auth: { apiKey: process.env.API_KEY },
+        retry: { attempts: 3, backoff: 'exponential' }
+    }
+});
 ```
 
-## 🔧 Template Parameters
+**Mobile App Integration**:
+```typescript
+// React Native / Expo
+const client = new UserApiClient({
+    transport: 'websocket',
+    websocket: {
+        url: 'wss://api.company.com',
+        auth: { jwt: await getStoredToken() },
+        reconnect: true,
+        reconnectInterval: 5000
+    }
+});
+```
+
+## 🔧 Configuration: Tailored for Your Stack
+
+**Strategic Configuration**: Every parameter serves a specific architectural purpose.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `clientName` | string | `"{{info.title}}Client"` | Name of the generated client class |
-| `packageName` | string | `"{{info.title | kebabCase}}-client"` | Name of the generated npm package |
-| `packageVersion` | string | `"{{info.version}}"` | Version of the generated package |
-| `author` | string | `"AsyncAPI Generator"` | Package author |
-| `license` | string | `"Apache-2.0"` | Package license |
-| `generateTests` | boolean | `true` | Generate unit tests |
-| `includeExamples` | boolean | `true` | Include usage examples |
-| `transports` | string | `"websocket,http"` | Comma-separated list of transports |
+| Parameter | Type | Default | Purpose |
+|-----------|------|---------|---------|
+| `clientName` | string | `"{{info.title}}Client"` | **Class naming**: Controls the main client class name for your codebase |
+| `packageName` | string | `"{{info.title | kebabCase}}-client"` | **NPM publishing**: Package name for internal/public npm registry |
+| `packageVersion` | string | `"{{info.version}}"` | **Versioning**: Syncs client version with AsyncAPI spec version |
+| `author` | string | `"AsyncAPI Generator"` | **Attribution**: Your team/company name for package metadata |
+| `license` | string | `"Apache-2.0"` | **Legal**: License for your generated client package |
+| `transports` | string | `"websocket,http"` | **Architecture**: Which transport layers to include |
+| `generateTests` | boolean | `true` | **Quality**: Include comprehensive test suite |
+| `includeExamples` | boolean | `true` | **Developer Experience**: Include integration examples |
 
-### Example with Parameters
+### Real-World Configuration Examples
 
+**Enterprise Microservice Client**:
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml ./template \
-  -o ./my-client \
-  -p clientName=MyAwesomeClient \
-  -p packageName=my-awesome-client \
-  -p packageVersion=1.0.0 \
-  -p author="Your Name" \
-  -p transports=websocket
+asyncapi generate fromTemplate user-service.yaml ./ts-client \
+  -o @company/user-service-client \
+  -p clientName=UserServiceClient \
+  -p packageName=@company/user-service-client \
+  -p packageVersion=2.1.0 \
+  -p author="Platform Team <platform@company.com>" \
+  -p transports=http \
+  -p generateTests=true
 ```
 
-## 📨 Message Envelope Standard
+**Real-Time Web Application Client**:
+```bash
+asyncapi generate fromTemplate chat-api.yaml ./ts-client \
+  -o chat-web-client \
+  -p clientName=ChatClient \
+  -p packageName=chat-web-client \
+  -p transports=websocket \
+  -p includeExamples=true
+```
+
+**Mobile App Client**:
+```bash
+asyncapi generate fromTemplate mobile-api.yaml ./ts-client \
+  -o @myapp/api-client \
+  -p clientName=MobileApiClient \
+  -p packageName=@myapp/api-client \
+  -p transports=websocket,http \
+  -p generateTests=false \
+  -p includeExamples=true
+```
+
+**IoT Dashboard Client**:
+```bash
+asyncapi generate fromTemplate iot-telemetry.yaml ./ts-client \
+  -o iot-dashboard-client \
+  -p clientName=IoTDashboardClient \
+  -p transports=websocket \
+  -p author="IoT Team" \
+  -p license=MIT
+```
+
+## 📨 The Message Envelope: Cross-Language Compatibility
 
-This template implements a standardized message envelope format for all AsyncAPI communications, enabling operation-based routing and consistent message handling across transports.
+**The Innovation**: A standardized message format that enables perfect compatibility between Rust servers and TypeScript clients, regardless of transport protocol.
 
-### Message Envelope Structure
+**Why This Matters**: Traditional async APIs suffer from protocol-specific message formats. Our envelope provides a universal standard that works across WebSocket, HTTP, MQTT, and any future transport.
+
+### Universal Message Structure
 
 ```typescript
 interface MessageEnvelope {
-    operation: string;           // AsyncAPI operation ID
-    id?: string;                // Correlation ID for request/response
-    channel?: string;           // Optional channel context
-    payload: any;               // Message payload
-    timestamp?: number;         // Message timestamp
-    error?: {                   // Error information
-        code: string;
-        message: string;
+    operation: string;           // AsyncAPI operation ID for routing
+    id?: string;                // Correlation ID for request/response tracking
+    channel?: string;           // Channel context for debugging and routing
+    payload: any;               // Strongly-typed message payload
+    timestamp?: number;         // Message timing for analytics
+    error?: {                   // Standardized error format
+        code: string;           // Machine-readable error code
+        message: string;        // Human-readable error message
     };
 }
 ```
 
-### Message Flow Examples
+**The Architecture Benefits**:
+- 🔄 **Operation Routing**: Servers route messages based on operation field
+- 🎯 **Request/Response Correlation**: Built-in correlation ID support
+- 🛡️ **Standardized Errors**: Consistent error handling across all operations
+- 🌐 **Transport Agnostic**: Same envelope works over any protocol
+- 📊 **Observability**: Built-in timing and debugging information
+
+### Real-World Message Flows
 
-#### Request/Response Pattern
+**The Power**: These patterns work identically whether you're using WebSocket, HTTP, or any other transport.
+
+#### Enterprise User Management Flow
 ```typescript
-// Client sends:
+// 1. Client Request (WebSocket or HTTP - same format)
 {
-    "operation": "getUserProfile",
-    "id": "uuid-1234",
-    "channel": "user/profile",
-    "payload": { "userId": "123" },
-    "timestamp": 1234567890
+    "operation": "createUser",
+    "id": "req_789abc",
+    "channel": "user/management",
+    "payload": {
+        "name": "Sarah Johnson",
+        "email": "sarah@company.com",
+        "department": "Engineering",
+        "role": "Senior Developer"
+    },
+    "timestamp": 1640995200000
 }
 
-// Server responds:
+// 2. Server Success Response
 {
-    "operation": "getUserProfile",
-    "id": "uuid-1234",
-    "payload": { "id": "123", "name": "John" },
-    "timestamp": 1234567891
+    "operation": "createUser",
+    "id": "req_789abc",
+    "payload": {
+        "userId": "usr_456def",
+        "name": "Sarah Johnson",
+        "email": "sarah@company.com",
+        "createdAt": "2021-12-31T12:00:00Z",
+        "onboardingTasks": [
+            "complete_profile",
+            "setup_2fa",
+            "join_team_channels"
+        ]
+    },
+    "timestamp": 1640995201500
+}
+
+// 3. Real-Time Notification (to other users)
+{
+    "operation": "userJoined",
+    "channel": "team/notifications",
+    "payload": {
+        "userId": "usr_456def",
+        "name": "Sarah Johnson",
+        "department": "Engineering",
+        "joinedAt": "2021-12-31T12:00:00Z"
+    },
+    "timestamp": 1640995201600
 }
 ```
 
-#### Subscription Pattern
+#### Error Handling with Business Context
 ```typescript
-// Server publishes:
+// Business Logic Error
 {
-    "operation": "onMessageReceived",
-    "channel": "chat/receive",
-    "payload": { "text": "Hello", "from": "Alice" },
-    "timestamp": 1234567892
+    "operation": "createUser",
+    "id": "req_789abc",
+    "error": {
+        "code": "EMAIL_ALREADY_EXISTS",
+        "message": "A user with email sarah@company.com already exists"
+    },
+    "timestamp": 1640995201000
+}
+
+// Validation Error
+{
+    "operation": "createUser",
+    "id": "req_789abc",
+    "error": {
+        "code": "VALIDATION_FAILED",
+        "message": "Invalid email format: not-an-email"
+    },
+    "timestamp": 1640995201000
+}
+
+// Infrastructure Error
+{
+    "operation": "createUser",
+    "id": "req_789abc",
+    "error": {
+        "code": "SERVICE_UNAVAILABLE",
+        "message": "User database is temporarily unavailable"
+    },
+    "timestamp": 1640995201000
 }
 ```
 
-#### Error Response
+#### IoT Telemetry Stream
 ```typescript
+// Sensor Data (MQTT → WebSocket bridge)
 {
-    "operation": "getUserProfile",
-    "id": "uuid-1234",
-    "error": {
-        "code": "USER_NOT_FOUND",
-        "message": "User with ID 123 not found"
+    "operation": "sensorReading",
+    "channel": "sensors/temperature",
+    "payload": {
+        "sensorId": "temp_001",
+        "location": "server_room_a",
+        "temperature": 23.5,
+        "humidity": 45.2,
+        "batteryLevel": 87
+    },
+    "timestamp": 1640995202000
+}
+
+// Alert Trigger
+{
+    "operation": "alertTriggered",
+    "channel": "alerts/critical",
+    "payload": {
+        "alertId": "alert_456",
+        "type": "TEMPERATURE_HIGH",
+        "sensorId": "temp_001",
+        "currentValue": 35.8,
+        "threshold": 30.0,
+        "severity": "CRITICAL"
     },
-    "timestamp": 1234567893
+    "timestamp": 1640995203000
 }
 ```
 
@@ -256,38 +517,123 @@ const response = await client.getUserProfile({
 console.log(response.user.name); // TypeScript provides autocomplete
 ```
 
-## 🔐 Authentication Support
+## 🔐 Authentication & Retry Support
+
+The generated client includes comprehensive authentication and retry capabilities inspired by the Rust server template.
 
-### JWT Tokens
+### JWT Authentication
 
 ```typescript
-{
+const client = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
     auth: {
-        token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
     }
-}
+});
+
+// JWT token is automatically added to Authorization header
+const response = await client.getUserProfile({ userId: '123' });
 ```
 
-### API Keys
+### Basic Authentication
 
 ```typescript
-{
+const client = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
     auth: {
-        apiKey: 'your-api-key'
+        basic: {
+            username: 'myuser',
+            password: 'mypassword'
+        }
     }
-}
+});
 ```
 
-### Custom Headers
+### API Key Authentication
 
 ```typescript
-{
+// API Key in header
+const client = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
     auth: {
-        headers: {
-            'X-Custom-Auth': 'custom-value'
+        apikey: {
+            key: 'my-api-key-123',
+            location: 'header',
+            name: 'X-API-Key'
         }
     }
-}
+});
+
+// API Key in query parameter
+const client2 = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
+    auth: {
+        apikey: {
+            key: 'my-api-key-123',
+            location: 'query',
+            name: 'apikey'
+        }
+    }
+});
+```
+
+### Retry Configuration
+
+```typescript
+// Using retry presets
+const client = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
+    retry: 'balanced'  // 'conservative', 'balanced', 'aggressive', or 'none'
+});
+
+// Custom retry configuration
+const client2 = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
+    retry: {
+        enabled: true,
+        maxAttempts: 3,
+        baseDelay: 1000,
+        maxDelay: 30000,
+        backoffMultiplier: 2,
+        jitter: true,
+        retryableStatusCodes: [429, 500, 502, 503, 504],
+        retryableErrors: ['NETWORK_ERROR', 'TIMEOUT']
+    }
+});
+
+// Per-request retry override
+const response = await client.createUser(userData, {
+    retry: 'aggressive',
+    timeout: 10000
+});
+```
+
+### Auth Error Handling
+
+```typescript
+const client = new MyServiceClient({
+    transport: 'http',
+    url: 'https://api.example.com',
+    auth: { jwt: 'your-token' },
+    authCallbacks: {
+        onAuthError: async () => {
+            // Handle 401 errors - refresh token, etc.
+            console.log('Authentication failed, attempting to refresh...');
+            return false; // Return true to retry with updated auth
+        }
+    },
+    retryCallbacks: {
+        onRetry: (attempt, error, delay) => {
+            console.log(`Retry attempt ${attempt} after ${delay}ms`);
+        }
+    }
+});
 ```
 
 ## 🔄 Error Handling