# 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

**This project uses Bun as the primary runtime and package manager. TypeScript files can be run directly without building.**

### Build Commands
- `bun run build` - Build all formats (CommonJS, ESM, and type declarations)
- `bun run build:cjs` - Build CommonJS format only
- `bun run build:esm` - Build ES modules format only  
- `bun run build:types` - Build TypeScript declarations only
- `bun run dev` - Watch mode for development
- `bun run clean` - Remove build artifacts

### Testing Commands
- `bun test` - Run all tests
- `bun run test:watch` - Run tests in watch mode
- `bun run test:coverage` - Run tests with coverage report

### Code Quality Commands
- `bun run lint` - Lint TypeScript files
- `bun run lint:fix` - Lint and auto-fix issues
- `bun run format` - Format code with Prettier

### Example Commands
- `bun run examples/nodemailer-transport.ts` - Run Nodemailer transport example directly
- `bun run example:basic` - Run basic usage example
- `bun run example:queue` - Run queue management example

### Running TypeScript Directly
- `bun run src/index.ts` - Run source files directly without building
- `bun run examples/any-example.ts` - Run any example file directly

## 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