@gravito/signal 3.0.3 → 3.0.4

package/src/dev/DevMailbox.ts

@@ -1,45 +1,66 @@
 import { randomUUID } from 'node:crypto'
-import type { Envelope, Message } from '../types'
+import type { Message } from '../types'
+import type { MailboxStorage } from './storage/MailboxStorage'
+import { MemoryMailboxStorage } from './storage/MemoryMailboxStorage'
 
 /**
- * Represents a captured email in the development mailbox.
- *
- * @public
+ * Entry structure for messages stored in DevMailbox.
  */
 export interface MailboxEntry {
-  /** Unique identifier for the email */
+  /** Unique identifier for the entry. */
   id: string
-  /** Email envelope information (from, to, subject, etc.) */
-  envelope: Envelope
-  /** HTML content of the email */
+  /** The email envelope metadata. */
+  envelope: any
+  /** The rendered HTML content. */
   html: string
-  /** Plain text content of the email (optional) */
+  /** Optional plain text content. */
   text?: string
-  /** Timestamp when the email was captured */
+  /** Timestamp when the message was captured. */
   sentAt: Date
 }
 
 /**
- * In-memory mailbox for capturing emails during development.
+ * Capture and store emails during development for preview and testing.
  *
- * Stores up to 50 recent emails and provides methods to list,
- * retrieve, and delete captured messages.
+ * Supports different storage engines (Memory, FileSystem) and implements
+ * capacity limits via a Ring Buffer strategy.
  *
  * @example
  * ```typescript
+ * // Default memory mailbox
  * const mailbox = new DevMailbox()
- * mailbox.add(message)
- * const emails = mailbox.list()
+ *
+ * // Persistent file mailbox
+ * const storage = new FileMailboxStorage('./storage/mail')
+ * const persistentMailbox = new DevMailbox(100, storage)
  * ```
  *
  * @since 3.0.0
  * @public
  */
 export class DevMailbox {
-  private entries: MailboxEntry[] = []
-  private maxEntries = 50
+  private storage: MailboxStorage
+  private _maxEntries = 50
 
-  add(message: Message): MailboxEntry {
+  /**
+   * Creates an instance of DevMailbox.
+   *
+   * @param maxEntries - Maximum number of emails to store (default: 50)
+   * @param storage - Optional custom storage engine (defaults to Memory)
+   */
+  constructor(maxEntries?: number, storage?: MailboxStorage) {
+    if (maxEntries !== undefined) {
+      this._maxEntries = maxEntries
+    }
+    this.storage = storage ?? new MemoryMailboxStorage()
+  }
+
+  /**
+   * Adds a new message to the mailbox.
+   *
+   * If the mailbox exceeds the maximum capacity, the oldest messages are removed.
+   */
+  async add(message: Message): Promise<MailboxEntry> {
     const entry: MailboxEntry = {
       id: randomUUID(),
       envelope: {
@@ -57,34 +78,69 @@ export class DevMailbox {
       sentAt: new Date(),
     }
 
-    this.entries.unshift(entry)
-
-    // Limit size
-    if (this.entries.length > this.maxEntries) {
-      this.entries = this.entries.slice(0, this.maxEntries)
-    }
+    await this.storage.push(entry)
+    await this.storage.trim(this._maxEntries)
 
     return entry
   }
 
-  list(): MailboxEntry[] {
-    return this.entries
+  /**
+   * Sets the maximum number of emails to store.
+   *
+   * If the current mailbox exceeds the new capacity, the oldest messages are removed.
+   */
+  async setMaxEntries(count: number): Promise<void> {
+    this._maxEntries = count
+    await this.storage.trim(this._maxEntries)
+  }
+
+  /**
+   * Returns the maximum capacity of the mailbox.
+   */
+  get maxEntries(): number {
+    return this._maxEntries
   }
 
-  get(id: string): MailboxEntry | undefined {
-    return this.entries.find((e) => e.id === id)
+  /**
+   * Lists all messages in the mailbox.
+   */
+  async list(): Promise<MailboxEntry[]> {
+    return await this.storage.all()
   }
 
-  delete(id: string): boolean {
-    const index = this.entries.findIndex((e) => e.id === id)
+  /**
+   * Retrieves a specific message by ID.
+   */
+  async get(id: string): Promise<MailboxEntry | undefined> {
+    const entries = await this.storage.all()
+    return entries.find((e) => e.id === id)
+  }
+
+  /**
+   * Deletes a specific message by ID.
+   */
+  async delete(id: string): Promise<boolean> {
+    if (this.storage.delete) {
+      return await this.storage.delete(id)
+    }
+
+    const entries = await this.storage.all()
+    const index = entries.findIndex((e) => e.id === id)
     if (index !== -1) {
-      this.entries.splice(index, 1)
+      await this.clear()
+      entries.splice(index, 1)
+      for (const entry of entries.reverse()) {
+        await this.storage.push(entry)
+      }
       return true
     }
     return false
   }
 
-  clear(): void {
-    this.entries = []
+  /**
+   * Clears all messages from the mailbox.
+   */
+  async clear(): Promise<void> {
+    await this.storage.clear()
   }
 }

package/src/dev/DevServer.ts

@@ -78,8 +78,8 @@ export class DevServer {
     // 1. Mailbox List
     router.get(
       prefix,
-      wrap((ctx) => {
-        const entries = this.mailbox.list()
+      wrap(async (ctx) => {
+        const entries = await this.mailbox.list()
         ctx.header('Content-Type', 'text/html; charset=utf-8')
         return ctx.html(getMailboxHtml(entries, prefix))
       })
@@ -88,13 +88,13 @@ export class DevServer {
     // 2. Single Email Preview
     router.get(
       `${prefix}/:id`,
-      wrap((ctx) => {
+      wrap(async (ctx) => {
         const id = ctx.req.param('id')
         if (!id) {
           return ctx.text('Bad Request', 400)
         }
 
-        const entry = this.mailbox.get(id)
+        const entry = await this.mailbox.get(id)
         if (!entry) {
           return ctx.text('Email not found', 404)
         }
@@ -106,13 +106,13 @@ export class DevServer {
     // 3. Iframe Content: HTML
     router.get(
       `${prefix}/:id/html`,
-      wrap((ctx) => {
+      wrap(async (ctx) => {
         const id = ctx.req.param('id')
         if (!id) {
           return ctx.text('Bad Request', 400)
         }
 
-        const entry = this.mailbox.get(id)
+        const entry = await this.mailbox.get(id)
         if (!entry) {
           return ctx.text('Not found', 404)
         }
@@ -124,13 +124,13 @@ export class DevServer {
     // 4. Iframe Content: Text
     router.get(
       `${prefix}/:id/text`,
-      wrap((ctx) => {
+      wrap(async (ctx) => {
         const id = ctx.req.param('id')
         if (!id) {
           return ctx.text('Bad Request', 400)
         }
 
-        const entry = this.mailbox.get(id)
+        const entry = await this.mailbox.get(id)
         if (!entry) {
           return ctx.text('Not found', 404)
         }
@@ -143,13 +143,13 @@ export class DevServer {
     // 5. Raw JSON
     router.get(
       `${prefix}/:id/raw`,
-      wrap((ctx) => {
+      wrap(async (ctx) => {
         const id = ctx.req.param('id')
         if (!id) {
           return ctx.json({ error: 'Bad Request' }, 400)
         }
 
-        const entry = this.mailbox.get(id)
+        const entry = await this.mailbox.get(id)
         if (!entry) {
           return ctx.json({ error: 'Not found' }, 404)
         }
@@ -167,13 +167,13 @@ export class DevServer {
 
     router.delete(
       `${prefix}/:id`,
-      wrap((ctx) => {
+      wrap(async (ctx) => {
         const id = ctx.req.param('id')
         if (!id) {
           return ctx.json({ success: false, error: 'Bad Request' }, 400)
         }
 
-        const success = this.mailbox.delete(id)
+        const success = await this.mailbox.delete(id)
         return ctx.json({ success })
       })
     )
@@ -181,8 +181,8 @@ export class DevServer {
     // 7. API: Clear All
     router.delete(
       prefix,
-      wrap((ctx) => {
-        this.mailbox.clear()
+      wrap(async (ctx) => {
+        await this.mailbox.clear()
         return ctx.json({ success: true })
       })
     )

package/src/dev/storage/FileMailboxStorage.ts

@@ -0,0 +1,66 @@
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { MailboxEntry } from '../DevMailbox'
+import type { MailboxStorage } from './MailboxStorage'
+
+/**
+ * File-based storage for DevMailbox (Persistence).
+ * Stores emails as JSON in a specified directory.
+ */
+export class FileMailboxStorage implements MailboxStorage {
+  private filePath: string
+
+  constructor(storageDir: string) {
+    this.filePath = join(storageDir, 'mailbox.json')
+  }
+
+  async all(): Promise<MailboxEntry[]> {
+    try {
+      const content = await readFile(this.filePath, 'utf-8')
+      return JSON.parse(content)
+    } catch (_e) {
+      return []
+    }
+  }
+
+  async push(entry: MailboxEntry): Promise<void> {
+    const entries = await this.all()
+    entries.unshift(entry)
+    await this.save(entries)
+  }
+
+  async trim(max: number): Promise<void> {
+    const entries = await this.all()
+    if (entries.length > max) {
+      await this.save(entries.slice(0, max))
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      await unlink(this.filePath)
+    } catch (_e) {
+      // Ignore if file doesn't exist
+    }
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const entries = await this.all()
+    const index = entries.findIndex((e) => e.id === id)
+    if (index !== -1) {
+      entries.splice(index, 1)
+      await this.save(entries)
+      return true
+    }
+    return false
+  }
+
+  private async save(entries: MailboxEntry[]): Promise<void> {
+    try {
+      await mkdir(join(this.filePath, '..'), { recursive: true })
+      await writeFile(this.filePath, JSON.stringify(entries, null, 2), 'utf-8')
+    } catch (error) {
+      console.error('[FileMailboxStorage] Failed to save mailbox:', error)
+    }
+  }
+}

package/src/dev/storage/MailboxStorage.ts

@@ -0,0 +1,15 @@
+import type { MailboxEntry } from '../DevMailbox'
+
+/**
+ * Interface for DevMailbox storage engines.
+ */
+export interface MailboxStorage {
+  /** Retrieve all entries. */
+  all(): Promise<MailboxEntry[]>
+  /** Add a single entry. */
+  push(entry: MailboxEntry): Promise<void>
+  /** Trim entries to a specific count. */
+  trim(max: number): Promise<void>
+  clear(): Promise<void>
+  delete?(id: string): Promise<boolean>
+}

package/src/dev/storage/MemoryMailboxStorage.ts

@@ -0,0 +1,36 @@
+import type { MailboxEntry } from '../DevMailbox'
+import type { MailboxStorage } from './MailboxStorage'
+
+/**
+ * Memory-based storage for DevMailbox (Default).
+ */
+export class MemoryMailboxStorage implements MailboxStorage {
+  private entries: MailboxEntry[] = []
+
+  async all(): Promise<MailboxEntry[]> {
+    return [...this.entries]
+  }
+
+  async push(entry: MailboxEntry): Promise<void> {
+    this.entries.unshift(entry)
+  }
+
+  async trim(max: number): Promise<void> {
+    if (this.entries.length > max) {
+      this.entries = this.entries.slice(0, max)
+    }
+  }
+
+  async clear(): Promise<void> {
+    this.entries = []
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const index = this.entries.findIndex((e) => e.id === id)
+    if (index !== -1) {
+      this.entries.splice(index, 1)
+      return true
+    }
+    return false
+  }
+}

package/src/dev/ui/mailbox.ts

@@ -47,7 +47,7 @@ export function getMailboxHtml(entries: MailboxEntry[], prefix: string): string
           ${entry.envelope.subject || '(No Subject)'}
         </div>
         <div class="meta" style="margin-top: 4px;">
-           To: ${entry.envelope.to?.map((t) => t.address).join(', ')}
+           To: ${entry.envelope.to?.map((t: any) => t.address).join(', ')}
         </div>
       </a>
     `

package/src/dev/ui/preview.ts

@@ -14,7 +14,7 @@ export function getPreviewHtml(entry: MailboxEntry, prefix: string): string {
   const from = entry.envelope.from
     ? `${entry.envelope.from.name || ''} <${entry.envelope.from.address}>`
     : 'Unknown'
-  const to = entry.envelope.to?.map((t) => t.address).join(', ') || 'Unknown'
+  const to = entry.envelope.to?.map((t: any) => t.address).join(', ') || 'Unknown'
 
   const content = `
     <div class="header">
@@ -31,12 +31,12 @@ export function getPreviewHtml(entry: MailboxEntry, prefix: string): string {
       <div class="meta" style="margin-bottom: 5px;">To: ${to}</div>
       ${
         entry.envelope.cc
-          ? `<div class="meta" style="margin-bottom: 5px;">CC: ${entry.envelope.cc.map((t) => t.address).join(', ')}</div>`
+          ? `<div class="meta" style="margin-bottom: 5px;">CC: ${entry.envelope.cc.map((t: any) => t.address).join(', ')}</div>`
           : ''
       }
       ${
         entry.envelope.bcc
-          ? `<div class="meta" style="margin-bottom: 5px;">BCC: ${entry.envelope.bcc.map((t) => t.address).join(', ')}</div>`
+          ? `<div class="meta" style="margin-bottom: 5px;">BCC: ${entry.envelope.bcc.map((t: any) => t.address).join(', ')}</div>`
           : ''
       }
       ${entry.envelope.priority ? `<div class="meta" style="margin-bottom: 5px;">Priority: ${entry.envelope.priority}</div>` : ''}
@@ -49,7 +49,7 @@ export function getPreviewHtml(entry: MailboxEntry, prefix: string): string {
           <div style="display: flex; gap: 10px; flex-wrap: wrap;">
             ${entry.envelope.attachments
               .map(
-                (att) => `
+                (att: any) => `
               <div style="background: var(--bg-dark); padding: 8px 12px; border-radius: 6px; border: 1px solid var(--border); display: flex; align-items: center; gap: 8px;">
                 <span style="font-size: 20px;">📎</span>
                 <div>

package/src/errors.ts

@@ -0,0 +1,69 @@
+/**
+ * Mail transport error codes.
+ *
+ * Categorizes common failure modes in the mail delivery process to allow
+ * for programmatic handling (e.g., retries on rate limits).
+ *
+ * @public
+ * @since 3.1.0
+ */
+export enum MailErrorCode {
+  /** Connection to mail server failed */
+  CONNECTION_FAILED = 'CONNECTION_FAILED',
+  /** Authentication with mail server failed */
+  AUTH_FAILED = 'AUTH_FAILED',
+  /** One or more recipients were rejected by the server */
+  RECIPIENT_REJECTED = 'RECIPIENT_REJECTED',
+  /** The message was rejected by the server */
+  MESSAGE_REJECTED = 'MESSAGE_REJECTED',
+  /** Rate limit exceeded */
+  RATE_LIMIT = 'RATE_LIMIT',
+  /** Unknown or unclassified error */
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * Error class for mail transport failures.
+ *
+ * Provides structured error information for mail sending failures,
+ * including error codes and original cause tracking for debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new MailTransportError(
+ *   'Failed to connect to SMTP server',
+ *   MailErrorCode.CONNECTION_FAILED,
+ *   originalError
+ * )
+ * ```
+ *
+ * @public
+ * @since 3.1.0
+ */
+export class MailTransportError extends Error {
+  /**
+   * Create a new mail transport error.
+   *
+   * @param message - Human-readable error message
+   * @param code - Categorized error code
+   * @param cause - Original error that caused this failure
+   *
+   * @example
+   * ```typescript
+   * const error = new MailTransportError('Auth failed', MailErrorCode.AUTH_FAILED);
+   * ```
+   */
+  constructor(
+    message: string,
+    public readonly code: MailErrorCode,
+    public readonly cause?: Error
+  ) {
+    super(message)
+    this.name = 'MailTransportError'
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, MailTransportError)
+    }
+  }
+}

package/src/events.ts

@@ -0,0 +1,72 @@
+import type { Mailable } from './Mailable'
+import type { Message } from './types'
+
+/**
+ * Mail event types.
+ *
+ * Defines the available lifecycle hooks for the mail service.
+ *
+ * @public
+ * @since 3.1.0
+ */
+export type MailEventType =
+  | 'beforeSend'
+  | 'afterSend'
+  | 'sendFailed'
+  | 'beforeRender'
+  | 'afterRender'
+  | 'webhookReceived'
+
+/**
+ * Mail lifecycle event.
+ *
+ * Emitted at key points during email sending lifecycle.
+ * Used for logging, analytics, or custom processing.
+ *
+ * @example
+ * ```typescript
+ * mail.on('afterSend', async (event) => {
+ *   console.log('Email sent to:', event.message?.to)
+ * })
+ * ```
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface MailEvent {
+  /** Type of event */
+  type: MailEventType
+  /** Mailable instance that triggered the event */
+  mailable: Mailable
+  /** Finalized message (available for send events) */
+  message?: Message
+  /** Error that occurred (available for sendFailed event) */
+  error?: Error
+  /** Timestamp when event occurred */
+  timestamp: Date
+  /** Webhook payload (available for webhookReceived event) */
+  webhook?: {
+    driver: string
+    event: string
+    payload: any
+  }
+}
+
+/**
+ * Mail event handler function.
+ *
+ * Defines the signature for functions that subscribe to mail events.
+ *
+ * @param event - The mail event object
+ *
+ * @example
+ * ```typescript
+ * const handler: MailEventHandler = (event) => {
+ *   console.log(`Event ${event.type} triggered`);
+ * };
+ * ```
+ *
+ * @public
+ * @since 3.1.0
+ */
+export type MailEventHandler = (event: MailEvent) => void | Promise<void>

package/src/index.ts

@@ -1,17 +1,34 @@
+/**
+ * OrbitSignal - The central Event Bus and Mail Service for Gravito.
+ *
+ * This module provides the core infrastructure for sending emails and managing
+ * cross-module signals within the Gravito ecosystem. It supports multiple
+ * transport drivers, template rendering, and a robust development environment.
+ *
+ * @packageDocumentation
+ */
+
 // import './augmentation'
 
 export type { Queueable } from '@gravito/stream'
 export { DevMailbox, type MailboxEntry } from './dev/DevMailbox'
+export { MailErrorCode, MailTransportError } from './errors'
+export type { MailEvent, MailEventHandler, MailEventType } from './events'
 export { Mailable } from './Mailable'
 export { OrbitSignal } from './OrbitSignal'
 export { HtmlRenderer } from './renderers/HtmlRenderer'
+export { MjmlRenderer } from './renderers/MjmlRenderer'
+export * from './renderers/mjml-templates'
+export { ReactMjmlRenderer } from './renderers/ReactMjmlRenderer'
 export type { Renderer, RenderResult } from './renderers/Renderer'
 export { TemplateRenderer } from './renderers/TemplateRenderer'
+export { VueMjmlRenderer } from './renderers/VueMjmlRenderer'
+export { TypedMailable } from './TypedMailable'
+export { BaseTransport, type TransportOptions } from './transports/BaseTransport'
 export { LogTransport } from './transports/LogTransport'
 export { MemoryTransport } from './transports/MemoryTransport'
 export { SesTransport } from './transports/SesTransport'
 export { SmtpTransport } from './transports/SmtpTransport'
-
 export type { Transport } from './transports/Transport'
 export type {
   Address,
@@ -20,3 +37,5 @@ export type {
   MailConfig,
   Message,
 } from './types'
+export { type SendGridWebhookConfig, SendGridWebhookDriver } from './webhooks/SendGridWebhookDriver'
+export { SesWebhookDriver } from './webhooks/SesWebhookDriver'

package/src/renderers/HtmlRenderer.ts

@@ -1,39 +1,41 @@
+import { stripHtml } from '../utils/html'
 import type { Renderer, RenderResult } from './Renderer'
 
 /**
  * Renderer for plain HTML content.
  *
- * Renders static HTML strings and automatically generates
- * a plain text version by stripping HTML tags.
+ * The simplest renderer - accepts raw HTML strings and automatically generates
+ * a plain text version by stripping HTML tags. Ideal for pre-rendered HTML or
+ * when using external HTML generation libraries.
  *
  * @example
  * ```typescript
- * const renderer = new HtmlRenderer('<h1>Hello</h1><p>World</p>')
- * const { html, text } = await renderer.render()
- * // html: '<h1>Hello</h1><p>World</p>'
- * // text: 'Hello World'
+ * const renderer = new HtmlRenderer('<h1>Hello</h1>');
+ * const result = await renderer.render();
+ * // result.html: '<h1>Hello</h1>'
+ * // result.text: 'Hello'
  * ```
  *
- * @since 3.0.0
  * @public
+ * @since 3.0.0
  */
 export class HtmlRenderer implements Renderer {
+  /**
+   * Creates an instance of HtmlRenderer.
+   *
+   * @param content - The raw HTML string to be rendered.
+   */
   constructor(private content: string) {}
 
+  /**
+   * Returns the original HTML and a stripped plain text version.
+   *
+   * @returns A promise resolving to the rendered content.
+   */
   async render(): Promise<RenderResult> {
     return {
       html: this.content,
-      text: this.stripHtml(this.content),
+      text: stripHtml(this.content),
     }
   }
-
-  private stripHtml(html: string): string {
-    return html
-      .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '') // Remove styles
-      .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '') // Remove scripts
-      .replace(/<[^>]+>/g, '') // Remove tags
-      .replace(/&nbsp;/g, ' ') // Replace non-breaking space
-      .replace(/\s+/g, ' ') // Collapse whitespace
-      .trim()
-  }
 }