initial commit

CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is **@siwatsystem/mxrelay-consumer**, a TypeScript client library for SMTP over WebSocket protocol. It provides intelligent queue management, automatic reconnection, and comprehensive error handling for sending emails through WebSocket-based SMTP relay servers.
+
+## Development Commands
+
+### Build Commands
+- `npm run build` - Build all formats (CommonJS, ESM, and type declarations)
+- `npm run build:cjs` - Build CommonJS format only
+- `npm run build:esm` - Build ES modules format only  
+- `npm run build:types` - Build TypeScript declarations only
+- `npm run dev` - Watch mode for development
+- `npm run clean` - Remove build artifacts
+
+### Testing Commands
+- `npm test` - Run all tests
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Run tests with coverage report
+
+### Code Quality Commands
+- `npm run lint` - Lint TypeScript files
+- `npm run lint:fix` - Lint and auto-fix issues
+- `npm run format` - Format code with Prettier
+
+### Example Commands
+- `npm run example:basic` - Run basic usage example
+- `npm run example:queue` - Run queue management example
+
+## Architecture
+
+### Core Components
+
+**SMTPOverWSClient (`src/client.ts`)** - Main client class that:
+- Manages WebSocket connections to SMTP relay servers
+- Implements intelligent message queuing with priority support
+- Handles automatic reconnection with exponential backoff  
+- Provides comprehensive error handling and recovery
+- Supports connection state management and event emission
+- Implements SMTP channel lifecycle management
+
+**Message Queue System** - Priority-based queue that:
+- Automatically connects when messages are queued
+- Processes messages sequentially with retry logic
+- Disconnects when queue is empty to optimize resources
+- Supports HIGH/NORMAL/LOW/CRITICAL priority levels
+
+**Connection State Machine** - Manages states:
+- DISCONNECTED → CONNECTING → CONNECTED → AUTHENTICATING → AUTHENTICATED
+- CHANNEL_OPENING → CHANNEL_READY → CHANNEL_CLOSED
+- RECONNECTING → FAILED (on max retry exhaustion)
+
+**SMTPWSTransport (`src/transport.ts`)** - Nodemailer-compatible transport that:
+- Converts Nodemailer mail objects to SMTP commands
+- Implements standard SMTP protocol flow (EHLO, MAIL FROM, RCPT TO, DATA, QUIT)
+- Handles recipient validation and error reporting
+- Provides transport verification and lifecycle management
+
+**Error Hierarchy (`src/errors.ts`)** - Structured errors:
+- `SMTPWSError` (base) → `ConnectionError`, `AuthenticationError`, `ChannelError`
+- `TimeoutError`, `QueueError`, `MessageError`, `ShutdownError`
+- `NetworkError`, `ProtocolError`, `ConfigurationError`
+- `ErrorFactory` for creating appropriate error instances
+
+### Protocol Implementation
+
+**WebSocket Message Types**:
+- Authentication: `AUTHENTICATE` ↔ `AUTHENTICATE_RESPONSE`
+- Channel lifecycle: `SMTP_CHANNEL_OPEN` → `SMTP_CHANNEL_READY` → `SMTP_CHANNEL_CLOSED`
+- Data transfer: `SMTP_TO_SERVER` ↔ `SMTP_FROM_SERVER`  
+- Error handling: `SMTP_CHANNEL_ERROR`
+
+**Queue Processing**:
+1. Messages queued by priority (CRITICAL > HIGH > NORMAL > LOW)
+2. Auto-connect when queue has messages
+3. Sequential processing with retry logic (configurable retry count)
+4. Auto-disconnect when queue empty
+5. Comprehensive timeout handling at all levels
+
+### Key Configuration Options
+
+- `url`: WebSocket server endpoint
+- `apiKey`: Authentication credential
+- `debug`: Enable console logging (default: false, library is silent by default)
+- `maxQueueSize`: Queue capacity limit (default: 1000)
+- `reconnectInterval`: Delay between reconnect attempts (default: 5000ms)
+- `maxReconnectAttempts`: Max retry count (default: 10)
+- `messageTimeout`: Per-message timeout (default: 60000ms)
+- `heartbeatInterval`: Keep-alive interval (default: 30000ms)
+
+### Build System
+
+The project uses multiple TypeScript configurations:
+- `tsconfig.json` - Main config for CommonJS build
+- `tsconfig.esm.json` - ES modules build  
+- `tsconfig.types.json` - Type declarations build
+- `tsconfig.cjs.json` - CommonJS specific build
+
+Output formats:
+- CommonJS: `lib/index.js`
+- ES Modules: `lib/index.esm.js`  
+- Type Declarations: `lib/index.d.ts`
+
+### Testing
+
+- Jest with TypeScript support
+- WebSocket mocking in `tests/setup.ts`
+- 30-second test timeout for integration tests
+- Coverage collection from all source files except index.ts