Siwat Sirichai
ad1424a79a
- Bump version in package.json and package-lock.json from 1.2.2 to 1.2.5 - Add Jest configuration file for testing - Update build scripts to use npm instead of bun - Add linting and testing scripts to package.json - Include tsconfig files in package.json files array
116 lines
No EOL
4.5 KiB
Markdown
116 lines
No EOL
4.5 KiB
Markdown
# 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 Node.js as the primary runtime with npm as the package manager.**
|
|
|
|
### 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 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
|
|
|
|
### Running TypeScript Directly
|
|
- Use `npx ts-node` to run TypeScript files directly during development
|
|
|
|
## 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 |