@gravito/signal 3.0.4 → 3.1.2

package/src/transports/BaseTransport.ts

@@ -1,148 +0,0 @@
-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

@@ -1,55 +0,0 @@
-import type { Message, Transport } from '../types'
-
-/**
- * Log transport for development and testing.
- *
- * 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
- * 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>'
- * });
- * ```
- *
- * @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('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
-    console.log(
-      `From:    ${message.from.name ? `${message.from.name} <${message.from.address}>` : message.from.address}`
-    )
-    console.log(`To:      ${message.to.map((t) => t.address).join(', ')}`)
-    console.log(`Subject: ${message.subject}`)
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
-    // console.log(message.html); // Too verbose usually
-    console.log(`[Content Size]: ${message.html.length} chars (HTML)`)
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n')
-  }
-}

package/src/transports/MemoryTransport.ts

@@ -1,55 +0,0 @@
-import type { DevMailbox } from '../dev/DevMailbox'
-import type { Message, Transport } from '../types'
-
-/**
- * Memory transport for development mode.
- *
- * 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
- * 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
- * ```
- *
- * @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,129 +0,0 @@
-import { SESClient, SendRawEmailCommand } from '@aws-sdk/client-ses'
-import nodemailer from 'nodemailer'
-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
- */
-export interface SesConfig extends TransportOptions {
-  /** AWS region where the SES service is hosted (e.g., 'us-east-1'). */
-  region: string
-  /** AWS access key ID. If omitted, the SDK will attempt to use default credential providers. */
-  accessKeyId?: string
-  /** AWS secret access key. Required if accessKeyId is provided. */
-  secretAccessKey?: string
-}
-
-/**
- * AWS SES (Simple Email Service) transport with automatic retry.
- *
- * 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-west-2'
- * });
- *
- * await transport.send(message);
- * ```
- *
- * @public
- */
-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) {
-      clientConfig.credentials = {
-        accessKeyId: config.accessKeyId,
-        secretAccessKey: config.secretAccessKey,
-      }
-    }
-
-    const ses = new SESClient(clientConfig)
-
-    this.transporter = nodemailer.createTransport({
-      SES: { ses, aws: { SendRawEmailCommand } },
-    } as any)
-  }
-
-  /**
-   * 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),
-      cc: message.cc?.map(this.formatAddress),
-      bcc: message.bcc?.map(this.formatAddress),
-      replyTo: message.replyTo ? this.formatAddress(message.replyTo) : undefined,
-      subject: message.subject,
-      html: message.html,
-      text: message.text,
-      headers: message.headers,
-      priority: message.priority,
-      attachments: message.attachments?.map((a) => ({
-        filename: a.filename,
-        content: a.content,
-        contentType: a.contentType,
-        cid: a.cid,
-        encoding: a.encoding,
-      })),
-    })
-  }
-
-  /**
-   * 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,184 +0,0 @@
-import nodemailer from 'nodemailer'
-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
- */
-export interface SmtpConfig extends TransportOptions {
-  /** SMTP server hostname or IP address. */
-  host: string
-  /** SMTP server port (typically 25, 465, or 587). */
-  port: number
-  /** Whether to use a secure TLS/SSL connection. Should be true for port 465. */
-  secure?: boolean
-  /** Authentication credentials for the SMTP server. */
-  auth?: {
-    /** SMTP username. */
-    user: string
-    /** SMTP password. */
-    pass: string
-  }
-  /** TLS specific options for the connection. */
-  tls?: {
-    /** Whether to reject unauthorized certificates (useful for self-signed certs). */
-    rejectUnauthorized?: boolean
-    /** 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 with connection pooling and automatic retry.
- *
- * 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.example.com',
- *   port: 587,
- *   auth: { user: 'user', pass: 'pass' }
- * });
- *
- * await transport.send(message);
- * ```
- *
- * @public
- */
-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) {
-    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,
-    })
-  }
-
-  /**
-   * 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),
-      cc: message.cc?.map(this.formatAddress),
-      bcc: message.bcc?.map(this.formatAddress),
-      replyTo: message.replyTo ? this.formatAddress(message.replyTo) : undefined,
-      subject: message.subject,
-      html: message.html,
-      text: message.text,
-      headers: message.headers,
-      priority: message.priority,
-      attachments: message.attachments?.map((a) => ({
-        filename: a.filename,
-        content: a.content,
-        contentType: a.contentType,
-        cid: a.cid,
-        encoding: a.encoding,
-      })),
-    })
-  }
-
-  /**
-   * 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,45 +0,0 @@
-import type { Message } from '../types'
-
-/**
- * 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
- */
-export interface 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.
-   *
-   * @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>
-}