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:

Messages queued by priority (CRITICAL > HIGH > NORMAL > LOW)
Auto-connect when queue has messages
Sequential processing with retry logic (configurable retry count)
Auto-disconnect when queue empty
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

4.4 KiB Raw Blame History