@gravito/signal 3.0.3 → 3.0.4

package/src/transports/BaseTransport.ts

@@ -0,0 +1,148 @@
+import { MailErrorCode, MailTransportError } from '../errors'
+import type { Message, Transport } from '../types'
+
+/**
+ * Transport retry configuration options.
+ *
+ * Defines the behavior of the automatic retry mechanism, including the number of attempts
+ * and the timing between them using exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const options: TransportOptions = {
+ *   maxRetries: 5,
+ *   retryDelay: 500,
+ *   backoffMultiplier: 3
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface TransportOptions {
+  /**
+   * Maximum number of retry attempts before giving up.
+   * Set to 0 to disable retries.
+   */
+  maxRetries?: number
+  /**
+   * Initial delay in milliseconds before the first retry attempt.
+   */
+  retryDelay?: number
+  /**
+   * Multiplier applied to the delay after each failed attempt.
+   * Used to implement exponential backoff to avoid overwhelming the service.
+   */
+  backoffMultiplier?: number
+}
+
+/**
+ * Base transport class with automatic retry mechanism.
+ *
+ * This abstract class provides a robust foundation for all transport implementations by
+ * handling transient failures through an exponential backoff retry strategy. It ensures
+ * that temporary network issues or service rate limits do not immediately fail the email delivery.
+ *
+ * The retry mechanism works as follows:
+ * 1. Attempt to send the message via `doSend()`.
+ * 2. If it fails, wait for `retryDelay` milliseconds.
+ * 3. Increment the delay by `backoffMultiplier` for the next attempt.
+ * 4. Repeat until success or `maxRetries` is reached.
+ *
+ * @example
+ * ```typescript
+ * class MyTransport extends BaseTransport {
+ *   constructor() {
+ *     super({ maxRetries: 3, retryDelay: 1000 })
+ *   }
+ *
+ *   protected async doSend(message: Message): Promise<void> {
+ *     // Actual implementation of the sending logic
+ *     // If this throws, BaseTransport will catch and retry
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export abstract class BaseTransport implements Transport {
+  protected options: Required<TransportOptions>
+
+  /**
+   * Initializes the transport with retry options.
+   *
+   * @param options - Configuration for the retry mechanism.
+   */
+  constructor(options?: TransportOptions) {
+    this.options = {
+      maxRetries: options?.maxRetries ?? 3,
+      retryDelay: options?.retryDelay ?? 1000,
+      backoffMultiplier: options?.backoffMultiplier ?? 2,
+    }
+  }
+
+  /**
+   * Orchestrates the message delivery with retry logic.
+   *
+   * This method wraps the concrete `doSend` implementation in a retry loop.
+   * It tracks the last error encountered to provide context if all retries fail.
+   *
+   * @param message - The message to be delivered.
+   * @returns A promise that resolves when the message is successfully sent.
+   * @throws {MailTransportError} If the message cannot be sent after the maximum number of retries.
+   *
+   * @example
+   * ```typescript
+   * const transport = new SmtpTransport(config);
+   * try {
+   *   await transport.send(message);
+   * } catch (error) {
+   *   console.error('Failed to send email after retries', error);
+   * }
+   * ```
+   */
+  async send(message: Message): Promise<void> {
+    let lastError: Error | undefined
+    let delay = this.options.retryDelay
+
+    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+      try {
+        return await this.doSend(message)
+      } catch (error) {
+        lastError = error as Error
+
+        if (attempt < this.options.maxRetries) {
+          await this.sleep(delay)
+          delay *= this.options.backoffMultiplier
+        }
+      }
+    }
+
+    throw new MailTransportError(
+      `Mail sending failed after ${this.options.maxRetries} retries`,
+      MailErrorCode.UNKNOWN,
+      lastError
+    )
+  }
+
+  /**
+   * Actual transport implementation to be provided by subclasses.
+   *
+   * This method should contain the protocol-specific logic for delivering the message.
+   * It will be automatically retried by the `send` method if it throws an error.
+   *
+   * @param message - The message to send.
+   * @returns A promise that resolves when the delivery is successful.
+   * @throws {Error} Any error encountered during delivery, which will trigger a retry.
+   */
+  protected abstract doSend(message: Message): Promise<void>
+
+  /**
+   * Utility method to pause execution for a given duration.
+   *
+   * @param ms - Milliseconds to sleep.
+   * @returns A promise that resolves after the delay.
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}

package/src/transports/LogTransport.ts

@@ -3,20 +3,42 @@ import type { Message, Transport } from '../types'
 /**
  * Log transport for development and testing.
  *
- * Logs email details to the console instead of sending them.
- * Useful for debugging and local development.
+ * This transport outputs email details directly to the console instead of performing
+ * actual delivery. It is essential for local development to avoid sending real emails
+ * while still being able to verify the content, recipients, and subject of outgoing mail.
  *
  * @example
  * ```typescript
- * const transport = new LogTransport()
- * await transport.send(message)
- * // Outputs email details to console
+ * import { LogTransport } from '@gravito/signal';
+ *
+ * const transport = new LogTransport();
+ * await transport.send({
+ *   from: { address: 'dev@localhost' },
+ *   to: [{ address: 'user@example.com' }],
+ *   subject: 'Test Email',
+ *   html: '<h1>Hello</h1>'
+ * });
  * ```
  *
- * @since 3.0.0
  * @public
  */
 export class LogTransport implements Transport {
+  /**
+   * Outputs the message details to the system console.
+   *
+   * Formats the email metadata (From, To, Subject) and content size into a readable
+   * block in the console output.
+   *
+   * @param message - The message to log.
+   * @returns A promise that resolves immediately after logging.
+   *
+   * @example
+   * ```typescript
+   * const transport = new LogTransport();
+   * await transport.send(message);
+   * // Console: 📧 [OrbitSignal] Email Sent (Simulated)...
+   * ```
+   */
   async send(message: Message): Promise<void> {
     console.log('\n📧 [OrbitSignal] Email Sent (Simulated):')
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')

package/src/transports/MemoryTransport.ts

@@ -4,22 +4,50 @@ import type { Message, Transport } from '../types'
 /**
  * Memory transport for development mode.
  *
- * Captures emails to an in-memory mailbox instead of sending them.
- * Used automatically when `devMode` is enabled in OrbitSignal.
+ * This transport captures outgoing emails and stores them in an in-memory mailbox.
+ * It is primarily used by the Gravito Dev UI to provide a live preview of emails
+ * during development without requiring an external mail server.
  *
  * @example
  * ```typescript
- * const mailbox = new DevMailbox()
- * const transport = new MemoryTransport(mailbox)
- * await transport.send(message)
+ * import { DevMailbox, MemoryTransport } from '@gravito/signal';
+ *
+ * const mailbox = new DevMailbox();
+ * const transport = new MemoryTransport(mailbox);
+ * await transport.send(message);
+ *
+ * console.log(mailbox.getAll().length); // 1
  * ```
  *
- * @since 3.0.0
  * @public
  */
 export class MemoryTransport implements Transport {
+  /**
+   * Creates a new MemoryTransport instance.
+   *
+   * @param mailbox - The in-memory storage where messages will be collected.
+   */
   constructor(private mailbox: DevMailbox) {}
 
+  /**
+   * Stores the message in the associated mailbox.
+   *
+   * The message is added to the internal list of the `DevMailbox` instance,
+   * making it available for retrieval by the Dev UI or test assertions.
+   *
+   * @param message - The message to store.
+   * @returns A promise that resolves once the message is added to the mailbox.
+   *
+   * @example
+   * ```typescript
+   * await transport.send({
+   *   from: { address: 'dev@localhost' },
+   *   to: [{ address: 'test@example.com' }],
+   *   subject: 'Memory Test',
+   *   html: '<p>Stored in memory</p>'
+   * });
+   * ```
+   */
   async send(message: Message): Promise<void> {
     this.mailbox.add(message)
     // console.log(`[MemoryTransport] Email stored in DevMailbox for: ${message.to.map(t => t.address).join(', ')}`);

package/src/transports/SesTransport.ts

@@ -1,45 +1,74 @@
 import { SESClient, SendRawEmailCommand } from '@aws-sdk/client-ses'
 import nodemailer from 'nodemailer'
-import type { Address, Message, Transport } from '../types'
+import type { Address, Message } from '../types'
+import { BaseTransport, type TransportOptions } from './BaseTransport'
 
 /**
  * Configuration for AWS SES email transport.
  *
+ * Defines the AWS region and credentials required to communicate with the
+ * Amazon Simple Email Service API.
+ *
+ * @example
+ * ```typescript
+ * const config: SesConfig = {
+ *   region: 'us-east-1',
+ *   accessKeyId: 'AKIA...',
+ *   secretAccessKey: 'wJalr...',
+ *   maxRetries: 5
+ * };
+ * ```
+ *
  * @public
- * @since 3.0.0
  */
-export interface SesConfig {
-  /** AWS region (e.g., 'us-east-1') */
+export interface SesConfig extends TransportOptions {
+  /** AWS region where the SES service is hosted (e.g., 'us-east-1'). */
   region: string
-  /** AWS access key ID (optional, uses default credentials if not provided) */
+  /** AWS access key ID. If omitted, the SDK will attempt to use default credential providers. */
   accessKeyId?: string
-  /** AWS secret access key (optional, uses default credentials if not provided) */
+  /** AWS secret access key. Required if accessKeyId is provided. */
   secretAccessKey?: string
 }
 
 /**
- * AWS SES (Simple Email Service) transport.
+ * AWS SES (Simple Email Service) transport with automatic retry.
  *
- * Sends emails using Amazon SES with support for attachments,
- * HTML/text content, and all standard email features.
+ * This transport delivers emails via the Amazon SES API. It requires the
+ * `@aws-sdk/client-ses` package to be installed as a dependency. It provides
+ * a reliable way to send high volumes of email using AWS infrastructure and
+ * includes automatic retry logic for transient API errors.
  *
  * @example
  * ```typescript
+ * import { SesTransport } from '@gravito/signal';
+ *
  * const transport = new SesTransport({
- *   region: 'us-east-1',
- *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
- *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
- * })
- * await transport.send(message)
+ *   region: 'us-west-2'
+ * });
+ *
+ * await transport.send(message);
  * ```
  *
- * @since 3.0.0
  * @public
  */
-export class SesTransport implements Transport {
+export class SesTransport extends BaseTransport {
   private transporter: nodemailer.Transporter
 
+  /**
+   * Initializes the SES transport with the provided configuration.
+   *
+   * Configures the AWS SES client and wraps it in a nodemailer transporter
+   * for consistent message handling.
+   *
+   * @param config - AWS SES connection and retry configuration.
+   */
   constructor(config: SesConfig) {
+    super({
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+      backoffMultiplier: config.backoffMultiplier,
+    })
+
     const clientConfig: any = { region: config.region }
 
     if (config.accessKeyId && config.secretAccessKey) {
@@ -56,7 +85,17 @@ export class SesTransport implements Transport {
     } as any)
   }
 
-  async send(message: Message): Promise<void> {
+  /**
+   * Internal method to perform the actual SES delivery.
+   *
+   * Converts the generic `Message` object into a raw email format and sends it
+   * via the SES `SendRawEmail` API.
+   *
+   * @param message - The message to deliver.
+   * @returns A promise that resolves when SES accepts the message for delivery.
+   * @throws {Error} If the SES API returns an error or connection fails.
+   */
+  protected async doSend(message: Message): Promise<void> {
     await this.transporter.sendMail({
       from: this.formatAddress(message.from),
       to: message.to.map(this.formatAddress),
@@ -78,6 +117,12 @@ export class SesTransport implements Transport {
     })
   }
 
+  /**
+   * Formats an Address object into a standard RFC 822 string.
+   *
+   * @param addr - The address object to format.
+   * @returns A string in the format "Name <email@example.com>" or just "email@example.com".
+   */
   private formatAddress(addr: Address): string {
     return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address
   }

package/src/transports/SmtpTransport.ts

@@ -1,66 +1,118 @@
 import nodemailer from 'nodemailer'
-import type { Address, Message, Transport } from '../types'
+import type { Address, Message } from '../types'
+import { BaseTransport, type TransportOptions } from './BaseTransport'
 
 /**
  * Configuration for SMTP email transport.
  *
+ * Defines the connection parameters, authentication, and pooling settings for
+ * communicating with an SMTP server.
+ *
+ * @example
+ * ```typescript
+ * const config: SmtpConfig = {
+ *   host: 'smtp.mailtrap.io',
+ *   port: 2525,
+ *   auth: { user: 'username', pass: 'password' },
+ *   poolSize: 10
+ * };
+ * ```
+ *
  * @public
- * @since 3.0.0
  */
-export interface SmtpConfig {
-  /** SMTP server hostname */
+export interface SmtpConfig extends TransportOptions {
+  /** SMTP server hostname or IP address. */
   host: string
-  /** SMTP server port (typically 25, 465, or 587) */
+  /** SMTP server port (typically 25, 465, or 587). */
   port: number
-  /** Use TLS/SSL connection (true for port 465) */
+  /** Whether to use a secure TLS/SSL connection. Should be true for port 465. */
   secure?: boolean
-  /** Authentication credentials */
+  /** Authentication credentials for the SMTP server. */
   auth?: {
-    /** SMTP username */
+    /** SMTP username. */
     user: string
-    /** SMTP password */
+    /** SMTP password. */
     pass: string
   }
-  /** TLS options */
+  /** TLS specific options for the connection. */
   tls?: {
-    /** Reject unauthorized certificates */
+    /** Whether to reject unauthorized certificates (useful for self-signed certs). */
     rejectUnauthorized?: boolean
-    /** Cipher suite */
+    /** Specific cipher suite to use for the connection. */
     ciphers?: string
   }
+  /** Number of concurrent connections to maintain in the pool. */
+  poolSize?: number
+  /** Maximum time in milliseconds a connection can remain idle before being closed. */
+  maxIdleTime?: number
 }
 
 /**
- * SMTP email transport.
+ * SMTP email transport with connection pooling and automatic retry.
  *
- * Sends emails using standard SMTP protocol with support for
- * authentication, TLS/SSL, attachments, and all email features.
+ * This transport uses the standard SMTP protocol to deliver emails. It leverages
+ * `nodemailer` for robust protocol implementation and includes built-in support
+ * for connection pooling to improve performance when sending multiple emails.
+ * It inherits automatic retry logic from `BaseTransport`.
  *
  * @example
  * ```typescript
+ * import { SmtpTransport } from '@gravito/signal';
+ *
  * const transport = new SmtpTransport({
- *   host: 'smtp.gmail.com',
+ *   host: 'smtp.example.com',
  *   port: 587,
- *   secure: false,
- *   auth: {
- *     user: 'user@gmail.com',
- *     pass: 'app-password'
- *   }
- * })
- * await transport.send(message)
+ *   auth: { user: 'user', pass: 'pass' }
+ * });
+ *
+ * await transport.send(message);
  * ```
  *
- * @since 3.0.0
  * @public
  */
-export class SmtpTransport implements Transport {
+export class SmtpTransport extends BaseTransport {
   private transporter: nodemailer.Transporter
 
+  /**
+   * Initializes the SMTP transport with the provided configuration.
+   *
+   * Sets up the underlying nodemailer transporter with connection pooling enabled.
+   *
+   * @param config - SMTP connection and retry configuration.
+   */
   constructor(config: SmtpConfig) {
-    this.transporter = nodemailer.createTransport(config)
+    super({
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+      backoffMultiplier: config.backoffMultiplier,
+    })
+
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+      auth: config.auth,
+      tls: config.tls,
+      pool: true,
+      maxConnections: config.poolSize ?? 5,
+      maxMessages: Infinity,
+      rateDelta: 1000,
+      rateLimit: 10,
+      socketTimeout: config.maxIdleTime ?? 30000,
+      greetingTimeout: 30000,
+    })
   }
 
-  async send(message: Message): Promise<void> {
+  /**
+   * Internal method to perform the actual SMTP delivery.
+   *
+   * Maps the generic `Message` object to the format expected by nodemailer.
+   *
+   * @param message - The message to deliver.
+   * @returns A promise that resolves when the SMTP server accepts the message.
+   * @throws {Error} If the SMTP server rejects the message or connection fails.
+   */
+  protected async doSend(message: Message): Promise<void> {
     await this.transporter.sendMail({
       from: this.formatAddress(message.from),
       to: message.to.map(this.formatAddress),
@@ -82,6 +134,50 @@ export class SmtpTransport implements Transport {
     })
   }
 
+  /**
+   * Gracefully shuts down the transport and closes all pooled connections.
+   *
+   * This should be called during application shutdown to ensure no resources are leaked.
+   *
+   * @returns A promise that resolves when all connections are closed.
+   *
+   * @example
+   * ```typescript
+   * await transport.close();
+   * ```
+   */
+  async close(): Promise<void> {
+    this.transporter.close()
+  }
+
+  /**
+   * Verifies the SMTP connection and authentication.
+   *
+   * Useful for health checks or validating configuration during startup.
+   *
+   * @returns A promise that resolves to true if the connection is valid, false otherwise.
+   *
+   * @example
+   * ```typescript
+   * const isValid = await transport.verify();
+   * if (!isValid) throw new Error('SMTP configuration is invalid');
+   * ```
+   */
+  async verify(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Formats an Address object into a standard RFC 822 string.
+   *
+   * @param addr - The address object to format.
+   * @returns A string in the format "Name <email@example.com>" or just "email@example.com".
+   */
   private formatAddress(addr: Address): string {
     return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address
   }

package/src/transports/Transport.ts

@@ -1,16 +1,45 @@
 import type { Message } from '../types'
 
 /**
- * Interface for email transport mechanisms (SMTP, SES, etc.).
+ * Interface for email transport mechanisms.
+ *
+ * Transports are responsible for the final delivery of an email message to its destination,
+ * whether it's a real SMTP server, a cloud service like AWS SES, or a local log for development.
+ * This abstraction allows the core mail service to remain agnostic of the delivery method.
+ *
+ * @example
+ * ```typescript
+ * class CustomTransport implements Transport {
+ *   async send(message: Message): Promise<void> {
+ *     // Implementation logic to deliver the message
+ *     console.log(`Sending email to ${message.to[0].address}`);
+ *   }
+ * }
+ * ```
  *
  * @public
- * @since 3.0.0
  */
 export interface Transport {
   /**
-   * Send the given message using the underlying transport.
+   * Send the given message using the underlying transport mechanism.
+   *
+   * This method handles the actual communication with the delivery service.
+   * Implementations should handle connection management and protocol-specific logic.
+   *
+   * @param message - The finalized message object containing recipients, subject, and content.
+   * @returns A promise that resolves when the message has been successfully handed off to the transport.
+   * @throws {MailTransportError} If the delivery fails after all internal retry attempts.
    *
-   * @param message - The finalized message to send.
+   * @example
+   * ```typescript
+   * const transport: Transport = new LogTransport();
+   * await transport.send({
+   *   from: { address: 'sender@example.com' },
+   *   to: [{ address: 'receiver@example.com' }],
+   *   subject: 'Hello',
+   *   html: '<p>World</p>'
+   * });
+   * ```
    */
   send(message: Message): Promise<void>
 }