@gravito/signal 3.0.3 → 3.0.4

package/dist/index.d.mts

@@ -3,23 +3,80 @@ export { Queueable } from '@gravito/stream';
 import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * 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
  */
 interface Transport {
     /**
-     * Send the given message using the underlying transport.
+     * Send the given message using the underlying transport mechanism.
      *
-     * @param message - The finalized message to send.
+     * 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>;
 }
 
+/**
+ * Interface for Webhook Drivers.
+ */
+interface WebhookDriver {
+    handle(c: GravitoContext): Promise<{
+        event: string;
+        payload: any;
+    }[] | null>;
+}
+
 /**
  * Representation of an email address with optional display name.
  *
+ * Defines the structure for email addresses used throughout the mail system.
+ * Supports both simple string addresses and formatted addresses with display names.
+ *
+ * @example
+ * ```typescript
+ * // Simple address
+ * const addr1: Address = { address: 'user@example.com' }
+ *
+ * // Address with display name
+ * const addr2: Address = {
+ *   name: 'John Doe',
+ *   address: 'john@example.com'
+ * }
+ * ```
+ *
+ * @see {@link Envelope} For the email envelope structure
+ * @see {@link Message} For the complete message structure
+ *
  * @public
  * @since 3.0.0
  */
@@ -32,6 +89,29 @@ interface Address {
 /**
  * Configuration for an email attachment.
  *
+ * Defines file attachments for email messages. Supports both regular attachments
+ * and inline attachments (e.g., embedded images referenced via Content-ID).
+ *
+ * @example
+ * ```typescript
+ * // Regular file attachment
+ * const attachment: Attachment = {
+ *   filename: 'document.pdf',
+ *   content: Buffer.from('...'),
+ *   contentType: 'application/pdf'
+ * }
+ *
+ * // Inline image attachment
+ * const inlineImage: Attachment = {
+ *   filename: 'logo.png',
+ *   content: Buffer.from('...'),
+ *   contentType: 'image/png',
+ *   cid: 'logo@example.com' // Reference in HTML: <img src="cid:logo@example.com">
+ * }
+ * ```
+ *
+ * @see {@link Envelope} For adding attachments to emails
+ *
  * @public
  * @since 3.0.0
  */
@@ -50,7 +130,22 @@ interface Attachment {
 /**
  * The envelope containing metadata for an email message.
  *
- * Used during the construction phase of a Mailable.
+ * Used during the construction phase of a Mailable. All fields are optional
+ * at this stage and will be validated when converting to a Message.
+ *
+ * @example
+ * ```typescript
+ * const envelope: Envelope = {
+ *   from: { name: 'App', address: 'noreply@app.com' },
+ *   to: [{ address: 'user@example.com' }],
+ *   subject: 'Welcome!',
+ *   priority: 'high',
+ *   replyTo: { address: 'support@app.com' }
+ * }
+ * ```
+ *
+ * @see {@link Mailable} For building envelopes fluently
+ * @see {@link Message} For the validated, finalized message structure
  *
  * @public
  * @since 3.0.0
@@ -77,6 +172,23 @@ interface Envelope {
  * A fully finalized email message ready to be sent by a transport.
  *
  * Requires mandatory fields that were optional in the Envelope.
+ * This structure is passed to Transport implementations for actual delivery.
+ *
+ * @example
+ * ```typescript
+ * const message: Message = {
+ *   from: { name: 'App', address: 'noreply@app.com' },
+ *   to: [{ address: 'user@example.com' }],
+ *   subject: 'Welcome to our service',
+ *   html: '<h1>Welcome!</h1><p>Thanks for joining.</p>',
+ *   text: 'Welcome! Thanks for joining.',
+ *   priority: 'normal',
+ *   headers: { 'X-Custom-Header': 'value' }
+ * }
+ * ```
+ *
+ * @see {@link Envelope} For the construction phase structure
+ * @see {@link Transport} For implementations that send messages
  *
  * @public
  * @since 3.0.0
@@ -98,106 +210,330 @@ interface Message extends Envelope {
 /**
  * Global configuration options for OrbitSignal and Mailable instances.
  *
+ * Configures the mail service behavior, transport mechanism, development tools,
+ * and internationalization support.
+ *
+ * @example
+ * ```typescript
+ * import { OrbitSignal, SmtpTransport } from '@gravito/signal'
+ *
+ * const config: MailConfig = {
+ *   from: { name: 'My App', address: 'noreply@myapp.com' },
+ *   transport: new SmtpTransport({
+ *     host: 'smtp.mailtrap.io',
+ *     port: 2525,
+ *     auth: { user: 'user', pass: 'pass' }
+ *   }),
+ *   devMode: process.env.NODE_ENV === 'development',
+ *   viewsDir: './src/emails',
+ *   devUiPrefix: '/__mail',
+ *   translator: (key, replace, locale) => i18n.t(key, { ...replace, locale })
+ * }
+ *
+ * const mail = new OrbitSignal(config)
+ * ```
+ *
+ * @see {@link OrbitSignal} For the mail service implementation
+ * @see {@link Transport} For available transport options
+ *
  * @public
  * @since 3.0.0
  */
 interface MailConfig {
     /**
      * Default sender address used if not specified in the Mailable.
+     *
+     * @example
+     * ```typescript
+     * from: { name: 'My App', address: 'noreply@myapp.com' }
+     * ```
      */
     from?: Address;
     /**
      * The transport mechanism used to send emails (e.g., SMTP, SES, Log).
+     *
+     * @example
+     * ```typescript
+     * import { SmtpTransport } from '@gravito/signal'
+     * transport: new SmtpTransport({ host: 'smtp.example.com', port: 587 })
+     * ```
      */
     transport?: Transport;
     /**
      * Enable development mode.
      * When true, emails are intercepted by the DevMailbox instead of being sent.
+     *
+     * @default false
+     * @example
+     * ```typescript
+     * devMode: process.env.NODE_ENV === 'development'
+     * ```
      */
     devMode?: boolean | undefined;
     /**
      * Directory where email templates are located for use with OrbitPrism.
-     * Default: src/emails
+     *
+     * @default "src/emails"
+     * @example
+     * ```typescript
+     * viewsDir: './resources/views/emails'
+     * ```
      */
     viewsDir?: string | undefined;
     /**
      * URL prefix for the Mail Dev UI.
-     * Default: /__mail
+     *
+     * @default "/__mail"
+     * @example
+     * ```typescript
+     * devUiPrefix: '/dev/mailbox'
+     * ```
      */
     devUiPrefix?: string | undefined;
     /**
      * Whether to allow access to the Mail Dev UI in production environments.
+     *
      * @default false
+     * @example
+     * ```typescript
+     * devUiAllowInProduction: process.env.ALLOW_MAIL_UI === 'true'
+     * ```
      */
     devUiAllowInProduction?: boolean | undefined;
     /**
      * Authorization gate for the Mail Dev UI.
      * Should return true to allow access to the UI.
+     *
+     * @example
+     * ```typescript
+     * devUiGate: async (ctx) => {
+     *   const user = await ctx.get('auth').user()
+     *   return user?.role === 'admin'
+     * }
+     * ```
      */
     devUiGate?: ((ctx: GravitoContext) => boolean | Promise<boolean>) | undefined;
     /**
      * Translation function for internationalization within emails.
+     *
+     * @example
+     * ```typescript
+     * translator: (key, replace, locale) => {
+     *   return i18n.t(key, { ...replace, locale: locale || 'en' })
+     * }
+     * ```
      */
     translator?: ((key: string, replace?: Record<string, unknown>, locale?: string) => string) | undefined;
+    /**
+     * URL prefix for Webhook endpoints.
+     */
+    webhookPrefix?: string | undefined;
+    /**
+     * Dictionary of registered webhook drivers.
+     */
+    webhookDrivers?: Record<string, WebhookDriver> | undefined;
 }
 
 /**
- * Represents a captured email in the development mailbox.
- *
- * @public
+ * Interface for DevMailbox storage engines.
+ */
+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>;
+}
+
+/**
+ * Entry structure for messages stored in DevMailbox.
  */
 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
  */
 declare class DevMailbox {
-    private entries;
-    private maxEntries;
-    add(message: Message): MailboxEntry;
-    list(): MailboxEntry[];
-    get(id: string): MailboxEntry | undefined;
-    delete(id: string): boolean;
-    clear(): void;
+    private storage;
+    private _maxEntries;
+    /**
+     * 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);
+    /**
+     * Adds a new message to the mailbox.
+     *
+     * If the mailbox exceeds the maximum capacity, the oldest messages are removed.
+     */
+    add(message: Message): Promise<MailboxEntry>;
+    /**
+     * Sets the maximum number of emails to store.
+     *
+     * If the current mailbox exceeds the new capacity, the oldest messages are removed.
+     */
+    setMaxEntries(count: number): Promise<void>;
+    /**
+     * Returns the maximum capacity of the mailbox.
+     */
+    get maxEntries(): number;
+    /**
+     * Lists all messages in the mailbox.
+     */
+    list(): Promise<MailboxEntry[]>;
+    /**
+     * Retrieves a specific message by ID.
+     */
+    get(id: string): Promise<MailboxEntry | undefined>;
+    /**
+     * Deletes a specific message by ID.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Clears all messages from the mailbox.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * 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
+ */
+declare 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
+ */
+declare class MailTransportError extends Error {
+    readonly code: MailErrorCode;
+    readonly cause?: Error | undefined;
+    /**
+     * 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, code: MailErrorCode, cause?: Error | undefined);
 }
 
 /**
  * Result of a content rendering operation.
  *
+ * This interface defines the structure of the output produced by any renderer.
+ * It ensures consistency across different rendering strategies (HTML, React, Vue, etc.),
+ * providing both the final HTML for the email body and an optional plain text version
+ * for clients that do not support HTML.
+ *
+ * @example
+ * ```typescript
+ * const result: RenderResult = {
+ *   html: '<html><body><h1>Hello</h1></body></html>',
+ *   text: 'Hello'
+ * };
+ * ```
+ *
  * @public
  * @since 3.0.0
  */
 interface RenderResult {
-    /** Rendered HTML string. */
+    /**
+     * The rendered HTML string.
+     *
+     * This is the primary content used for the email body.
+     */
     html: string;
-    /** Optional rendered plain text string. */
+    /**
+     * Optional rendered plain text string.
+     *
+     * Used as a fallback for email clients that cannot display HTML or for accessibility.
+     */
     text?: string;
 }
 /**
- * Interface for email content renderers (HTML, Template, React, Vue).
+ * Interface for email content renderers.
+ *
+ * Renderers are responsible for transforming various input formats (raw HTML,
+ * templates, or UI components) into a standardized {@link RenderResult}.
+ * This abstraction allows the mail system to support multiple view engines
+ * and frameworks interchangeably.
+ *
+ * @example
+ * ```typescript
+ * class MyRenderer implements Renderer {
+ *   async render(data: Record<string, unknown>): Promise<RenderResult> {
+ *     return { html: `<div>${data.name}</div>`, text: String(data.name) };
+ *   }
+ * }
+ * ```
  *
  * @public
  * @since 3.0.0
@@ -206,7 +542,12 @@ interface Renderer {
     /**
      * Render the content into HTML and optionally plain text.
      *
+     * This method performs the actual transformation of the source content
+     * using the provided data context.
+     *
      * @param data - The data context for rendering.
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If rendering fails due to syntax errors or missing dependencies.
      */
     render(data: Record<string, unknown>): Promise<RenderResult>;
 }
@@ -215,21 +556,53 @@ type ComponentType = any;
 /**
  * Base class for all mailable messages.
  *
- * Provides a fluent API for building email envelopes and rendering content
- * using various engines (raw HTML, Prism templates, React, or Vue).
+ * @description
+ * Mailable provides a fluent API to build email envelopes and render content
+ * using multiple engines: HTML, Prism templates, React, and Vue components.
+ *
+ * @architecture
+ * ```
+ * Mailable
+ *   ├── Envelope (from, to, subject, cc, bcc, attachments)
+ *   ├── Renderer (HtmlRenderer | TemplateRenderer | ReactRenderer | VueRenderer)
+ *   └── Queueable (queue support interface)
+ * ```
+ *
+ * @lifecycle
+ * 1. Create Mailable subclass
+ * 2. Implement build() method to configure envelope and content
+ * 3. Call send() to send immediately, or queue() for background processing
+ * 4. OrbitSignal calls buildEnvelope() → renderContent() → transport.send()
  *
  * @example
  * ```typescript
- * class WelcomeMail extends Mailable {
+ * import { Mailable } from '@gravito/signal'
+ *
+ * class WelcomeEmail extends Mailable {
+ *   constructor(private user: User) {
+ *     super()
+ *   }
+ *
  *   build() {
- *     return this.subject('Welcome!')
- *                .view('emails.welcome', { name: 'John' });
+ *     return this
+ *       .to(this.user.email)
+ *       .subject('Welcome!')
+ *       .view('emails/welcome', { name: this.user.name })
  *   }
  * }
  *
- * await new WelcomeMail().to('john@example.com').send();
+ * // Send immediately
+ * await mail.send(new WelcomeEmail(user))
+ *
+ * // Queue for background processing
+ * await new WelcomeEmail(user).onQueue('emails').queue()
  * ```
  *
+ * @see {@link OrbitSignal} Mail service orchestrator
+ * @see {@link Renderer} Content rendering interface
+ * @see {@link Envelope} Email metadata structure
+ * @see {@link Queueable} Queue integration interface
+ *
  * @public
  * @since 3.0.0
  */
@@ -242,71 +615,167 @@ declare abstract class Mailable implements Queueable {
     /**
      * Set the sender address for the email.
      *
-     * @param address - Email address or Address object.
+     * This defines the "From" field in the email envelope. If not called, the default
+     * sender from the mail configuration will be used.
+     *
+     * @param address - The email address or address object containing name and address.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.from('admin@example.com')
+     * mailable.from({ name: 'Support', address: 'support@example.com' })
+     * ```
      */
     from(address: string | Address): this;
     /**
      * Set the primary recipient(s) for the email.
      *
-     * @param address - Single address, address object, or array of either.
+     * Configures the "To" field. Supports single or multiple recipients in various formats.
+     *
+     * @param address - A single email string, an address object, or an array of either.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.to('user@example.com')
+     * mailable.to(['a@example.com', 'b@example.com'])
+     * mailable.to({ name: 'John', address: 'john@example.com' })
+     * ```
      */
     to(address: string | Address | (string | Address)[]): this;
     /**
      * Set the carbon copy (CC) recipient(s).
      *
-     * @param address - Single address, address object, or array of either.
+     * Adds recipients to the "Cc" field of the email.
+     *
+     * @param address - A single email string, an address object, or an array of either.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.cc('manager@example.com')
+     * ```
      */
     cc(address: string | Address | (string | Address)[]): this;
     /**
      * Set the blind carbon copy (BCC) recipient(s).
      *
-     * @param address - Single address, address object, or array of either.
+     * Adds recipients to the "Bcc" field. These recipients are hidden from others.
+     *
+     * @param address - A single email string, an address object, or an array of either.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.bcc('audit@example.com')
+     * ```
      */
     bcc(address: string | Address | (string | Address)[]): this;
     /**
      * Set the reply-to address.
      *
-     * @param address - Email address or Address object.
+     * Specifies where replies to this email should be directed.
+     *
+     * @param address - The email address or address object for replies.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.replyTo('no-reply@example.com')
+     * ```
      */
     replyTo(address: string | Address): this;
     /**
      * Set the subject line for the email.
      *
-     * @param subject - The email subject.
+     * Defines the text that appears in the recipient's inbox subject field.
+     *
+     * @param subject - The subject text.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.subject('Your Order Confirmation')
+     * ```
      */
     subject(subject: string): this;
     /**
      * Set the email priority.
      *
-     * @param level - Priority level ('high', 'normal', or 'low').
+     * Hints to the email client how urgent this message is.
+     *
+     * @param level - The priority level: 'high', 'normal', or 'low'.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.emailPriority('high')
+     * ```
      */
     emailPriority(level: 'high' | 'normal' | 'low'): this;
     /**
      * Attach a file to the email.
      *
-     * @param attachment - Attachment configuration object.
+     * Adds a file attachment to the message. Can be called multiple times for multiple files.
+     *
+     * @param attachment - The attachment configuration including path, content, or filename.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.attach({
+     *   filename: 'invoice.pdf',
+     *   path: './storage/invoices/123.pdf'
+     * })
+     * ```
      */
     attach(attachment: Attachment): this;
     /**
-     * Set the content using raw HTML string.
+     * Set the content using a raw HTML string.
      *
-     * @param content - The HTML content string.
+     * Use this for simple emails where a full template engine is not required.
+     *
+     * @param content - The raw HTML content.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.html('<h1>Hello</h1><p>Welcome to our platform.</p>')
+     * ```
      */
     html(content: string): this;
     /**
      * Set the content using an OrbitPrism template.
      *
-     * @param template - Template name (relative to viewsDir/emails).
-     * @param data - Optional data to pass to the template.
+     * Renders a template file with the provided data. This is the recommended way
+     * to build complex, data-driven emails.
+     *
+     * @param template - The template name or path relative to the configured views directory.
+     * @param data - The data object to be injected into the template.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.view('emails.welcome', { name: 'Alice' })
+     * ```
      */
     view(template: string, data?: Record<string, unknown>): this;
     /**
      * Set the content using a React component.
-     * Dynamically imports ReactRenderer to avoid hard dependency errors if React is not installed.
      *
-     * @param component - The React component to render.
-     * @param props - Optional props for the component.
-     * @param deps - Optional dependencies (React, ReactDOMServer) if not globally available.
+     * Leverages React's component model for email design. The renderer is loaded
+     * dynamically to keep the core package lightweight.
+     *
+     * @param component - The React component class or function.
+     * @param props - The properties to pass to the component.
+     * @param deps - Optional React/ReactDOMServer overrides for custom environments.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.react(WelcomeEmailComponent, { name: 'Alice' })
+     * ```
      */
     react<P extends object>(component: ComponentType, props?: P, deps?: {
         createElement?: (...args: any[]) => any;
@@ -314,11 +783,19 @@ declare abstract class Mailable implements Queueable {
     }): this;
     /**
      * Set the content using a Vue component.
-     * Dynamically imports VueRenderer to avoid hard dependency errors if Vue is not installed.
      *
-     * @param component - The Vue component to render.
-     * @param props - Optional props for the component.
-     * @param deps - Optional dependencies (Vue, VueServerRenderer) if not globally available.
+     * Leverages Vue's component model for email design. The renderer is loaded
+     * dynamically to keep the core package lightweight.
+     *
+     * @param component - The Vue component object.
+     * @param props - The properties to pass to the component.
+     * @param deps - Optional Vue/VueServerRenderer overrides for custom environments.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.vue(WelcomeEmailComponent, { name: 'Alice' })
+     * ```
      */
     vue<P extends object>(component: ComponentType, props?: P, deps?: {
         createSSRApp?: (...args: any[]) => any;
@@ -326,8 +803,57 @@ declare abstract class Mailable implements Queueable {
         renderToString?: (app: any) => Promise<string>;
     }): this;
     /**
-     * Setup the mailable. This is where you call from(), to(), view(), etc.
-     * This method must be implemented by concrete classes.
+     * Set the content using an MJML markup string.
+     *
+     * MJML ensures responsive email compatibility across various clients.
+     *
+     * @param content - The MJML markup string or inner content.
+     * @param options - MJML transformation options.
+     * @param options.layout - Optional full MJML layout string. Use '{{content}}' as placeholder.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.mjml('<mj-text>Hello</mj-text>', {
+     *   layout: '<mjml><mj-body>{{content}}</mj-body></mjml>'
+     * })
+     * ```
+     */
+    mjml(content: string, options?: Record<string, any> & {
+        layout?: string;
+    }): this;
+    /**
+     * Set the content using a React component that outputs MJML.
+     *
+     * @param component - The React component.
+     * @param props - Component properties.
+     * @param options - MJML options.
+     * @returns The current mailable instance for chaining.
+     */
+    mjmlReact<P extends object>(component: ComponentType, props?: P, options?: Record<string, any>): this;
+    /**
+     * Set the content using a Vue component that outputs MJML.
+     *
+     * @param component - The Vue component.
+     * @param props - Component properties.
+     * @param options - MJML options.
+     * @returns The current mailable instance for chaining.
+     */
+    mjmlVue<P extends object>(component: ComponentType, props?: P, options?: Record<string, any>): this;
+    /**
+     * Configure the mailable's envelope and content.
+     *
+     * This abstract method must be implemented by subclasses to define the email's
+     * recipients, subject, and body using the fluent API.
+     *
+     * @returns The current mailable instance.
+     *
+     * @example
+     * ```typescript
+     * build() {
+     *   return this.to('user@example.com').subject('Hi').html('...')
+     * }
+     * ```
      */
     abstract build(): this;
     /** The name of the queue to push this mailable to. */
@@ -339,32 +865,85 @@ declare abstract class Mailable implements Queueable {
     /** Priority of the message in the queue. */
     priority?: number | string;
     /**
-     * Set the queue name for this mailable.
+     * Set the target queue for background processing.
+     *
+     * @param queue - The name of the queue.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.onQueue('notifications')
+     * ```
      */
     onQueue(queue: string): this;
     /**
-     * Set the connection name for this mailable.
+     * Set the queue connection to be used.
+     *
+     * @param connection - The name of the connection (e.g., 'redis', 'sqs').
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.onConnection('redis')
+     * ```
      */
     onConnection(connection: string): this;
     /**
-     * Set a delay for the queued mailable.
+     * Set a delay for the queued message.
+     *
+     * The message will remain in the queue and only be processed after the delay.
+     *
+     * @param seconds - The delay in seconds.
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.delay(3600) // Delay for 1 hour
+     * ```
      */
     delay(seconds: number): this;
     /**
-     * Set the priority for the queued mailable.
+     * Set the priority for the queued message.
+     *
+     * Higher priority messages are typically processed before lower priority ones.
+     *
+     * @param priority - The priority value (numeric or string).
+     * @returns The current mailable instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * mailable.withPriority(10)
+     * ```
      */
     withPriority(priority: string | number): this;
     /**
-     * Queue the mailable for sending.
-     * Attempts to resolve the mail service from the PlanetCore container.
+     * Push the mailable onto the configured queue.
+     *
+     * Automatically resolves the mail service from the Gravito container and
+     * dispatches this mailable for background processing.
+     *
+     * @returns A promise that resolves when the mailable is queued.
+     *
+     * @example
+     * ```typescript
+     * await new WelcomeEmail(user).queue()
+     * ```
      */
     queue(): Promise<void>;
     protected currentLocale?: string;
     protected translator?: (key: string, replace?: Record<string, unknown>, locale?: string) => string;
     /**
-     * Set the locale for the message.
+     * Set the locale for the email content.
+     *
+     * Used by the translator to resolve localized strings in templates or components.
+     *
+     * @param locale - The locale identifier (e.g., 'en-US', 'fr').
+     * @returns The current mailable instance for chaining.
      *
-     * @param locale - Valid locale string (e.g., 'en', 'zh-TW').
+     * @example
+     * ```typescript
+     * mailable.locale('es')
+     * ```
      */
     locale(locale: string): this;
     /**
@@ -373,21 +952,48 @@ declare abstract class Mailable implements Queueable {
      */
     setTranslator(translator: (key: string, replace?: Record<string, unknown>, locale?: string) => string): void;
     /**
-     * Translate a string using the configured translator.
+     * Translate a key into a localized string.
      *
-     * @param key - Translation key.
-     * @param replace - Interpolation variables.
-     * @returns Translated string or the key if translator is missing.
+     * Uses the configured translator and current locale to resolve the key.
+     *
+     * @param key - The translation key.
+     * @param replace - Key-value pairs for string interpolation.
+     * @returns The translated string, or the key itself if no translator is available.
+     *
+     * @example
+     * ```typescript
+     * const text = mailable.t('messages.welcome', { name: 'Alice' })
+     * ```
      */
     t(key: string, replace?: Record<string, unknown>): string;
     /**
-     * Compile the envelope based on config defaults and mailable settings.
-     * Called by OrbitSignal before rendering/sending.
+     * Compile the final email envelope.
+     *
+     * Merges mailable-specific settings with global configuration defaults.
+     * This is called internally by the mail service before sending.
+     *
+     * @param configPromise - The mail configuration or a promise resolving to it.
+     * @returns The fully constructed envelope.
+     *
+     * @example
+     * ```typescript
+     * const envelope = await mailable.buildEnvelope(config)
+     * ```
      */
     buildEnvelope(configPromise: MailConfig | Promise<MailConfig>): Promise<Envelope>;
     /**
-     * Execute the renderer and produce HTML/Text content.
-     * @returns Object containing rendered html and optional text content.
+     * Render the email content to HTML and plain text.
+     *
+     * Executes the chosen renderer (HTML, Template, React, or Vue) with the
+     * provided data and i18n helpers.
+     *
+     * @returns The rendered HTML and optional plain text content.
+     * @throws {Error} If no renderer has been specified.
+     *
+     * @example
+     * ```typescript
+     * const { html } = await mailable.renderContent()
+     * ```
      */
     renderContent(): Promise<{
         html: string;
@@ -397,248 +1003,1113 @@ declare abstract class Mailable implements Queueable {
 }
 
 /**
- * OrbitSignal - Mail service orbit for Gravito framework.
- *
- * Provides email sending capabilities with support for multiple transports,
- * development mode with email preview UI, and queue integration.
- *
- * @example
- * ```typescript
- * import { OrbitSignal } from '@gravito/signal'
- * import { SmtpTransport } from '@gravito/signal'
- *
- * const app = new Application({
- *   orbits: [
- *     new OrbitSignal({
- *       transport: new SmtpTransport({
- *         host: 'smtp.example.com',
- *         port: 587,
- *         auth: { user: 'user', pass: 'pass' }
- *       }),
- *       from: { name: 'App', email: 'noreply@example.com' }
- *     })
- *   ]
- * })
+ * Mail event types.
  *
- * // In route handler
- * await c.get('mail').send(new WelcomeEmail(user))
- * ```
+ * Defines the available lifecycle hooks for the mail service.
  *
- * @since 3.0.0
  * @public
+ * @since 3.1.0
  */
-declare class OrbitSignal implements GravitoOrbit {
-    private config;
-    private devMailbox?;
-    private core?;
-    constructor(config?: MailConfig);
-    /**
-     * Install the orbit into PlanetCore
-     *
-     * @param core - The PlanetCore instance.
-     */
-    install(core: PlanetCore): void;
-    /**
-     * Send a mailable instance
-     */
-    send(mailable: Mailable): Promise<void>;
-    /**
-     * Queue a mailable instance
-     */
-    queue(mailable: Mailable): Promise<void>;
-}
-declare module '@gravito/core' {
-    interface GravitoVariables {
-        /** Mail service for sending emails */
-        mail?: OrbitSignal;
-    }
-}
-
+type MailEventType = 'beforeSend' | 'afterSend' | 'sendFailed' | 'beforeRender' | 'afterRender' | 'webhookReceived';
 /**
- * Renderer for plain HTML content.
+ * Mail lifecycle event.
  *
- * Renders static HTML strings and automatically generates
- * a plain text version by stripping HTML tags.
+ * Emitted at key points during email sending lifecycle.
+ * Used for logging, analytics, or custom processing.
  *
  * @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'
+ * mail.on('afterSend', async (event) => {
+ *   console.log('Email sent to:', event.message?.to)
+ * })
  * ```
  *
- * @since 3.0.0
  * @public
+ * @since 3.1.0
  */
-declare class HtmlRenderer implements Renderer {
-    private content;
-    constructor(content: string);
-    render(): Promise<RenderResult>;
-    private stripHtml;
+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;
+    };
 }
-
 /**
- * Renderer for template-based emails using Gravito Prism.
+ * Mail event handler function.
  *
- * Renders email templates from the filesystem using the Prism
- * template engine with support for data binding and layouts.
+ * Defines the signature for functions that subscribe to mail events.
+ *
+ * @param event - The mail event object
  *
  * @example
  * ```typescript
- * const renderer = new TemplateRenderer('welcome', './src/emails')
- * const { html, text } = await renderer.render({ name: 'John' })
+ * const handler: MailEventHandler = (event) => {
+ *   console.log(`Event ${event.type} triggered`);
+ * };
  * ```
  *
- * @since 3.0.0
  * @public
+ * @since 3.1.0
  */
-declare class TemplateRenderer implements Renderer {
-    private template;
-    private viewsDir;
-    constructor(templateName: string, viewsDir?: string);
-    render(data: Record<string, unknown>): Promise<RenderResult>;
-    private stripHtml;
-}
+type MailEventHandler = (event: MailEvent) => void | Promise<void>;
 
 /**
- * Log transport for development and testing.
+ * OrbitSignal - Mail service orbit for Gravito framework.
  *
- * Logs email details to the console instead of sending them.
- * Useful for debugging and local development.
+ * @description
+ * A production-ready email service providing multi-transport support, automatic retry,
+ * event-driven lifecycle hooks, and development tooling. Integrates seamlessly with
+ * Gravito's orbit system and queue infrastructure.
+ *
+ * @architecture
+ * ```
+ * OrbitSignal
+ *   ├── Configuration (MailConfig)
+ *   │   ├── transport: Transport (SMTP, SES, Log, Memory)
+ *   │   ├── from: Default sender
+ *   │   ├── devMode: Development interception
+ *   │   └── translator: i18n support
+ *   ├── Lifecycle Events
+ *   │   ├── beforeRender → afterRender
+ *   │   ├── beforeSend → afterSend
+ *   │   └── sendFailed (on error)
+ *   ├── Transport Layer
+ *   │   ├── BaseTransport (retry, backoff)
+ *   │   ├── SmtpTransport (connection pooling)
+ *   │   ├── SesTransport (AWS SES)
+ *   │   ├── LogTransport (console output)
+ *   │   └── MemoryTransport (dev mode)
+ *   └── Dev Tools
+ *       ├── DevMailbox (in-memory storage)
+ *       └── DevServer (preview UI at /__mail)
+ * ```
+ *
+ * @example
+ * **Basic SMTP Configuration**
+ * ```typescript
+ * import { OrbitSignal, SmtpTransport } from '@gravito/signal'
+ *
+ * const mail = new OrbitSignal({
+ *   transport: new SmtpTransport({
+ *     host: 'smtp.mailtrap.io',
+ *     port: 2525,
+ *     auth: { user: 'username', pass: 'password' }
+ *   }),
+ *   from: { name: 'My App', address: 'noreply@myapp.com' }
+ * })
+ *
+ * mail.install(core)
+ * ```
+ *
+ * @example
+ * **AWS SES with Retry Configuration**
+ * ```typescript
+ * import { OrbitSignal, SesTransport } from '@gravito/signal'
+ *
+ * const mail = new OrbitSignal({
+ *   transport: new SesTransport({
+ *     region: 'us-east-1',
+ *     retries: 3,
+ *     retryDelay: 1000,
+ *     retryMultiplier: 2
+ *   }),
+ *   from: { name: 'Production App', address: 'noreply@example.com' }
+ * })
+ * ```
+ *
+ * @example
+ * **Development Mode with Preview UI**
+ * ```typescript
+ * const mail = new OrbitSignal({
+ *   devMode: process.env.NODE_ENV === 'development',
+ *   devUiPrefix: '/__mail',
+ *   from: { name: 'Dev App', address: 'dev@localhost' }
+ * })
+ *
+ * // All emails intercepted to memory, view at http://localhost:3000/__mail
+ * ```
+ *
+ * @example
+ * **Event-Driven Analytics & Error Handling**
+ * ```typescript
+ * const mail = new OrbitSignal({ ... })
+ *
+ * // Track successful sends
+ * mail.on('afterSend', async (event) => {
+ *   await analytics.track('email_sent', {
+ *     to: event.message?.to,
+ *     subject: event.message?.subject,
+ *     timestamp: event.timestamp
+ *   })
+ * })
+ *
+ * // Log failures for monitoring
+ * mail.on('sendFailed', async (event) => {
+ *   logger.error('Email send failed', {
+ *     error: event.error?.message,
+ *     mailable: event.mailable.constructor.name
+ *   })
+ *   await sentry.captureException(event.error)
+ * })
+ * ```
+ *
+ * @example
+ * **SMTP with Connection Pooling**
+ * ```typescript
+ * const mail = new OrbitSignal({
+ *   transport: new SmtpTransport({
+ *     host: 'smtp.gmail.com',
+ *     port: 465,
+ *     secure: true,
+ *     auth: { user: 'user@gmail.com', pass: 'app-password' },
+ *     poolSize: 5,
+ *     maxIdleTime: 30000
+ *   })
+ * })
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', async () => {
+ *   await mail.config.transport?.close?.()
+ * })
+ * ```
+ *
+ * @example
+ * **Usage in Route Handlers**
+ * ```typescript
+ * // Injected automatically into GravitoContext
+ * app.post('/register', async (c) => {
+ *   const user = await createUser(c.req.json())
+ *
+ *   await c.get('mail').send(new WelcomeEmail(user))
+ *
+ *   return c.json({ success: true })
+ * })
+ * ```
  *
  * @example
+ * **Queue Integration for Background Processing**
  * ```typescript
- * const transport = new LogTransport()
- * await transport.send(message)
- * // Outputs email details to console
+ * // Requires @gravito/stream
+ * const email = new WelcomeEmail(user)
+ *   .onQueue('emails')
+ *   .delay(60)
+ *
+ * await email.queue()
  * ```
  *
+ * @example
+ * **Error Handling Best Practices**
+ * ```typescript
+ * try {
+ *   await mail.send(new InvoiceEmail(order))
+ * } catch (error) {
+ *   if (error instanceof MailTransportError) {
+ *     switch (error.code) {
+ *       case MailErrorCode.RATE_LIMIT:
+ *         await queue.pushDelayed(email, 300)
+ *         break
+ *       case MailErrorCode.RECIPIENT_REJECTED:
+ *         await markUserEmailInvalid(user.id)
+ *         break
+ *       default:
+ *         throw error
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Mailable} Base class for email definitions
+ * @see {@link TypedMailable} Strongly-typed mailable with generic data
+ * @see {@link Transport} Transport interface
+ * @see {@link BaseTransport} Retry-enabled base transport
+ * @see {@link MailConfig} Configuration interface
+ * @see {@link MailEvent} Event types
+ * @see {@link MailTransportError} Error handling
+ *
  * @since 3.0.0
  * @public
  */
+declare class OrbitSignal implements GravitoOrbit {
+    private config;
+    private devMailbox?;
+    private core?;
+    private eventHandlers;
+    constructor(config?: MailConfig);
+    /**
+     * Install the orbit into PlanetCore.
+     *
+     * Registers the mail service in the IoC container and sets up development
+     * tools if enabled. It also injects the service into the GravitoContext
+     * for easy access in route handlers.
+     *
+     * @param core - The PlanetCore instance to install into
+     *
+     * @example
+     * ```typescript
+     * const mail = new OrbitSignal(config);
+     * mail.install(core);
+     * ```
+     */
+    install(core: PlanetCore): void;
+    /**
+     * Internal: Handle processed webhook.
+     */
+    private handleWebhook;
+    /**
+     * Send a mailable instance immediately.
+     *
+     * Orchestrates the full email sending lifecycle: building the envelope,
+     * rendering content, emitting events, and delivering via the configured transport.
+     *
+     * @param mailable - The email definition to send
+     * @throws {Error} If mandatory fields (from, to) are missing or transport fails
+     *
+     * @example
+     * ```typescript
+     * await mail.send(new WelcomeEmail(user));
+     * ```
+     */
+    send(mailable: Mailable): Promise<void>;
+    /**
+     * Queue a mailable instance for background processing.
+     *
+     * Attempts to use the 'queue' service (OrbitStream) if available in the
+     * container. Falls back to immediate sending if no queue service is found.
+     *
+     * @param mailable - The email definition to queue
+     *
+     * @example
+     * ```typescript
+     * await mail.queue(new WelcomeEmail(user));
+     * ```
+     */
+    queue(mailable: Mailable): Promise<void>;
+    /**
+     * Register an event handler.
+     *
+     * @description
+     * Subscribe to mail lifecycle events for logging, analytics, or custom processing.
+     *
+     * @param event - The event type to listen for
+     * @param handler - The handler function to execute
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * mail.on('afterSend', async (event) => {
+     *   await analytics.track('email_sent', {
+     *     to: event.message?.to,
+     *     subject: event.message?.subject
+     *   })
+     * })
+     * ```
+     *
+     * @public
+     * @since 3.1.0
+     */
+    on(event: MailEventType, handler: MailEventHandler): this;
+    private emit;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Mail service for sending emails */
+        mail?: OrbitSignal;
+    }
+}
+
+/**
+ * Renderer for plain HTML content.
+ *
+ * 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>');
+ * const result = await renderer.render();
+ * // result.html: '<h1>Hello</h1>'
+ * // result.text: 'Hello'
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class HtmlRenderer implements Renderer {
+    private content;
+    /**
+     * Creates an instance of HtmlRenderer.
+     *
+     * @param content - The raw HTML string to be rendered.
+     */
+    constructor(content: string);
+    /**
+     * Returns the original HTML and a stripped plain text version.
+     *
+     * @returns A promise resolving to the rendered content.
+     */
+    render(): Promise<RenderResult>;
+}
+
+/**
+ * Renderer for MJML-based emails.
+ *
+ * MJML is a markup language designed to reduce the pain of coding a responsive email.
+ * This renderer lazily loads the `mjml` package to keep the core lightweight.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new MjmlRenderer('<mjml><mj-body>...</mj-body></mjml>');
+ * const result = await renderer.render();
+ * ```
+ *
+ * @public
+ * @since 1.1.0
+ */
+declare class MjmlRenderer implements Renderer {
+    private content;
+    private options;
+    private deps;
+    /**
+     * Creates an instance of MjmlRenderer.
+     *
+     * @param content - The MJML markup string to be rendered.
+     * @param options - Optional MJML transformation options.
+     * @param deps - Optional dependency injection for testing.
+     */
+    constructor(content: string, options?: Record<string, any>, deps?: {
+        mjml2html?: (mjml: string, options?: any) => any;
+    });
+    /**
+     * Renders the MJML content to static HTML.
+     *
+     * This method performs a dynamic import of `mjml` to ensure it's only
+     * loaded if this renderer is actually used.
+     *
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If MJML dependencies cannot be loaded or rendering fails.
+     */
+    render(): Promise<RenderResult>;
+}
+
+/**
+ * Base layout for MJML emails.
+ * Includes common head styles and responsive settings.
+ *
+ * Placeholder: {{content}}
+ */
+declare const baseLayout: string;
+/**
+ * A simple transactional component layout.
+ */
+declare const transactionLayout = "\n<mj-section background-color=\"#ffffff\" padding-top=\"0px\">\n  <mj-column>\n    {{content}}\n  </mj-column>\n</mj-section>\n";
+
+/**
+ * Renderer for React component-based MJML emails.
+ *
+ * Renders React components to MJML string using SSR, then converts
+ * the MJML to responsive HTML.
+ *
+ * @typeParam P - Props type for the React component.
+ * @public
+ * @since 1.1.0
+ */
+declare class ReactMjmlRenderer<P extends object = object> implements Renderer {
+    private component;
+    private props?;
+    private options;
+    private deps;
+    /**
+     * Creates an instance of ReactMjmlRenderer.
+     *
+     * @param component - The React component to render.
+     * @param props - Initial props for the component.
+     * @param options - Optional MJML transformation options.
+     * @param deps - Optional dependency injection for testing.
+     */
+    constructor(component: any, props?: P | undefined, options?: Record<string, any>, deps?: {
+        createElement?: (...args: any[]) => any;
+        renderToStaticMarkup?: (element: any) => string;
+        mjml2html?: (mjml: string, options?: any) => any;
+    });
+    /**
+     * Renders the React component to a static HTML string via MJML.
+     *
+     * @param data - Runtime data to be merged with initial props.
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If MJML rendering fails.
+     */
+    render(data: Record<string, unknown>): Promise<RenderResult>;
+}
+
+/**
+ * Renderer for template-based emails using Gravito Prism.
+ *
+ * Renders email templates from the filesystem using the Prism template engine.
+ * It uses a static cache for the template engine to avoid redundant initialization
+ * costs when rendering multiple emails from the same directory.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new TemplateRenderer('welcome', './src/emails');
+ * const result = await renderer.render({ name: 'John' });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class TemplateRenderer implements Renderer {
+    private template;
+    private viewsDir;
+    private static engineCache;
+    /**
+     * Creates an instance of TemplateRenderer.
+     *
+     * @param templateName - The name of the template file (without extension).
+     * @param viewsDir - The directory containing template files. Defaults to `src/emails`.
+     */
+    constructor(templateName: string, viewsDir?: string);
+    /**
+     * Renders the template with the provided data.
+     *
+     * This method lazily loads `@gravito/prism` to ensure the core package
+     * remains lightweight for users who don't need template rendering.
+     *
+     * @param data - The data context for template interpolation.
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If the template engine fails to load or rendering fails.
+     */
+    render(data: Record<string, unknown>): Promise<RenderResult>;
+    /**
+     * Clear template engine cache.
+     *
+     * Useful in development environments to force recompilation of templates
+     * after they have been modified on disk.
+     *
+     * @example
+     * ```typescript
+     * TemplateRenderer.clearCache();
+     * ```
+     *
+     * @public
+     * @since 3.1.0
+     */
+    static clearCache(): void;
+}
+
+/**
+ * Renderer for Vue component-based MJML emails.
+ *
+ * Renders Vue 3 components to MJML string using SSR, then converts
+ * the MJML to responsive HTML.
+ *
+ * @typeParam P - Props type for the Vue component.
+ * @public
+ * @since 1.1.0
+ */
+declare class VueMjmlRenderer<P extends object = object> implements Renderer {
+    private component;
+    private props?;
+    private options;
+    private deps;
+    /**
+     * Creates an instance of VueMjmlRenderer.
+     *
+     * @param component - The Vue component to render.
+     * @param props - Initial props for the component.
+     * @param options - Optional MJML transformation options.
+     * @param deps - Optional dependency injection for testing.
+     */
+    constructor(component: any, props?: P | undefined, options?: Record<string, any>, deps?: {
+        createSSRApp?: (...args: any[]) => any;
+        h?: (...args: any[]) => any;
+        renderToString?: (app: any) => Promise<string>;
+        mjml2html?: (mjml: string, options?: any) => any;
+    });
+    /**
+     * Renders the Vue component to a static HTML string via MJML.
+     *
+     * @param data - Runtime data to be merged with initial props.
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If MJML rendering fails.
+     */
+    render(data: Record<string, unknown>): Promise<RenderResult>;
+}
+
+/**
+ * Abstract base class for strongly-typed Mailable messages.
+ *
+ * @description
+ * TypedMailable extends the base Mailable class to provide compile-time type safety
+ * for email data props. This ensures that the data passed to templates, React, or Vue
+ * components is correctly typed and validated at build time.
+ *
+ * @typeParam TData - The shape of data required by this mailable's template/component.
+ *                    Must extend Record<string, unknown>.
+ *
+ * @example
+ * ```typescript
+ * import { TypedMailable } from '@gravito/signal'
+ *
+ * // Define the data interface
+ * interface WelcomeData {
+ *   name: string
+ *   email: string
+ *   activationUrl: string
+ * }
+ *
+ * // Create strongly-typed mailable
+ * class WelcomeEmail extends TypedMailable<WelcomeData> {
+ *   protected data: WelcomeData
+ *
+ *   constructor(data: WelcomeData) {
+ *     super()
+ *     this.data = data
+ *   }
+ *
+ *   build() {
+ *     return this
+ *       .to(this.data.email)
+ *       .subject('Welcome to Gravito!')
+ *       .view('emails/welcome', this.data) // Type-safe: compiler ensures WelcomeData matches template
+ *   }
+ * }
+ *
+ * // Usage - compiler enforces correct data shape
+ * const email = new WelcomeEmail({
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   activationUrl: 'https://app.com/activate?token=abc123'
+ * })
+ *
+ * await mail.send(email)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With React components
+ * interface InvoiceData {
+ *   invoiceNumber: string
+ *   amount: number
+ *   dueDate: Date
+ *   items: Array<{ name: string; price: number }>
+ * }
+ *
+ * class InvoiceEmail extends TypedMailable<InvoiceData> {
+ *   protected data: InvoiceData
+ *
+ *   constructor(data: InvoiceData) {
+ *     super()
+ *     this.data = data
+ *   }
+ *
+ *   build() {
+ *     return this
+ *       .to('billing@example.com')
+ *       .subject(`Invoice ${this.data.invoiceNumber}`)
+ *       .react(InvoiceComponent, this.data) // Type-safe props
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Mailable} Base mailable class
+ * @see {@link OrbitSignal} Mail service orchestrator
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare abstract class TypedMailable<TData extends Record<string, unknown>> extends Mailable {
+    /**
+     * The strongly-typed data for this mailable.
+     *
+     * This property holds the data that will be passed to the template or component
+     * during rendering. By defining it as an abstract property with the generic
+     * type TData, we force subclasses to provide a concrete, type-safe implementation.
+     *
+     * @protected
+     */
+    protected abstract data: TData;
+}
+
+/**
+ * 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
+ */
+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
+ */
+declare 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);
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    send(message: Message): Promise<void>;
+    /**
+     * 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;
+}
+
+/**
+ * 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
+ */
 declare 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)...
+     * ```
+     */
     send(message: Message): Promise<void>;
 }
 
 /**
  * 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
  */
 declare class MemoryTransport implements Transport {
     private mailbox;
+    /**
+     * Creates a new MemoryTransport instance.
+     *
+     * @param mailbox - The in-memory storage where messages will be collected.
+     */
     constructor(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>'
+     * });
+     * ```
+     */
     send(message: Message): Promise<void>;
 }
 
 /**
  * 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
  */
-interface SesConfig {
-    /** AWS region (e.g., 'us-east-1') */
+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
  */
-declare class SesTransport implements Transport {
+declare class SesTransport extends BaseTransport {
     private 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);
-    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 doSend(message: Message): Promise<void>;
+    /**
+     * 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;
 }
 
 /**
  * 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
  */
-interface SmtpConfig {
-    /** SMTP server hostname */
+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
  */
-declare class SmtpTransport implements Transport {
+declare class SmtpTransport extends BaseTransport {
     private 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);
-    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 doSend(message: Message): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    verify(): Promise<boolean>;
+    /**
+     * 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;
 }
 
-export { type Address, type Attachment, DevMailbox, type Envelope, HtmlRenderer, LogTransport, type MailConfig, Mailable, type MailboxEntry, MemoryTransport, type Message, OrbitSignal, type RenderResult, type Renderer, SesTransport, SmtpTransport, TemplateRenderer, type Transport };
+/**
+ * Configuration for SendGrid Webhook Driver.
+ */
+interface SendGridWebhookConfig {
+    /**
+     * Public key or Verification Secret for signature validation.
+     * If provided, all requests will be validated.
+     */
+    publicKey?: string;
+}
+/**
+ * SendGrid Webhook Driver.
+ *
+ * Handles Event Webhooks from SendGrid (delivered, bounced, opened, clicked, etc.).
+ *
+ * @see https://docs.sendgrid.com/for-developers/tracking-events/event-webhook
+ * @public
+ * @since 1.1.0
+ */
+declare class SendGridWebhookDriver implements WebhookDriver {
+    private config;
+    constructor(config?: SendGridWebhookConfig);
+    /**
+     * Handles the SendGrid webhook request.
+     */
+    handle(c: GravitoContext): Promise<{
+        event: string;
+        payload: any;
+    }[] | null>;
+    /**
+     * Verifies the SendGrid webhook signature.
+     *
+     * @param payload - Raw request body string.
+     * @param signature - Signature from X-Twilio-Email-Event-Webhook-Signature header.
+     * @param timestamp - Timestamp from X-Twilio-Email-Event-Webhook-Timestamp header.
+     * @returns True if signature is valid.
+     *
+     * @remarks
+     * Real SendGrid validation uses Elliptic Curve (ECDSA).
+     * This is a placeholder for the logic structure.
+     */
+    private verifySignature;
+}
+
+/**
+ * AWS SES Webhook Driver.
+ *
+ * Handles SES Notifications via Amazon SNS (Complaints, Bounces, Deliveries).
+ *
+ * @see https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity-using-notifications.html
+ * @public
+ * @since 1.1.0
+ */
+declare class SesWebhookDriver implements WebhookDriver {
+    /**
+     * Handles the AWS SES/SNS webhook request.
+     *
+     * @param c - The Gravito request context.
+     * @returns Array of processed events or null if ignored.
+     */
+    handle(c: GravitoContext): Promise<{
+        event: string;
+        payload: any;
+    }[] | null>;
+}
+
+export { type Address, type Attachment, BaseTransport, DevMailbox, type Envelope, HtmlRenderer, LogTransport, type MailConfig, MailErrorCode, type MailEvent, type MailEventHandler, type MailEventType, MailTransportError, Mailable, type MailboxEntry, MemoryTransport, type Message, MjmlRenderer, OrbitSignal, ReactMjmlRenderer, type RenderResult, type Renderer, type SendGridWebhookConfig, SendGridWebhookDriver, SesTransport, SesWebhookDriver, SmtpTransport, TemplateRenderer, type Transport, type TransportOptions, TypedMailable, VueMjmlRenderer, baseLayout, transactionLayout };