@gravito/signal 3.0.3 → 3.0.4

package/dist/index.mjs

@@ -1,11 +1,69 @@
-import "./chunk-EBO3CZXG.mjs";
+import {
+  MjmlRenderer
+} from "./chunk-W6LXIJKK.mjs";
+import {
+  ReactMjmlRenderer
+} from "./chunk-DBFIVHHG.mjs";
+import {
+  VueMjmlRenderer
+} from "./chunk-KB7IDDBT.mjs";
+import {
+  stripHtml
+} from "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
 
 // src/dev/DevMailbox.ts
 import { randomUUID } from "crypto";
-var DevMailbox = class {
+
+// src/dev/storage/MemoryMailboxStorage.ts
+var MemoryMailboxStorage = class {
   entries = [];
-  maxEntries = 50;
-  add(message) {
+  async all() {
+    return [...this.entries];
+  }
+  async push(entry) {
+    this.entries.unshift(entry);
+  }
+  async trim(max) {
+    if (this.entries.length > max) {
+      this.entries = this.entries.slice(0, max);
+    }
+  }
+  async clear() {
+    this.entries = [];
+  }
+  async delete(id) {
+    const index = this.entries.findIndex((e) => e.id === id);
+    if (index !== -1) {
+      this.entries.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+};
+
+// src/dev/DevMailbox.ts
+var DevMailbox = class {
+  storage;
+  _maxEntries = 50;
+  /**
+   * 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, storage) {
+    if (maxEntries !== void 0) {
+      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) {
     const entry = {
       id: randomUUID(),
       envelope: {
@@ -22,66 +80,176 @@ var DevMailbox = class {
       ...message.text ? { text: message.text } : {},
       sentAt: /* @__PURE__ */ new Date()
     };
-    this.entries.unshift(entry);
-    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() {
-    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) {
+    this._maxEntries = count;
+    await this.storage.trim(this._maxEntries);
   }
-  get(id) {
-    return this.entries.find((e) => e.id === id);
+  /**
+   * Returns the maximum capacity of the mailbox.
+   */
+  get maxEntries() {
+    return this._maxEntries;
   }
-  delete(id) {
-    const index = this.entries.findIndex((e) => e.id === id);
+  /**
+   * Lists all messages in the mailbox.
+   */
+  async list() {
+    return await this.storage.all();
+  }
+  /**
+   * Retrieves a specific message by ID.
+   */
+  async get(id) {
+    const entries = await this.storage.all();
+    return entries.find((e) => e.id === id);
+  }
+  /**
+   * Deletes a specific message by ID.
+   */
+  async delete(id) {
+    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() {
-    this.entries = [];
+  /**
+   * Clears all messages from the mailbox.
+   */
+  async clear() {
+    await this.storage.clear();
+  }
+};
+
+// src/errors.ts
+var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
+  MailErrorCode2["CONNECTION_FAILED"] = "CONNECTION_FAILED";
+  MailErrorCode2["AUTH_FAILED"] = "AUTH_FAILED";
+  MailErrorCode2["RECIPIENT_REJECTED"] = "RECIPIENT_REJECTED";
+  MailErrorCode2["MESSAGE_REJECTED"] = "MESSAGE_REJECTED";
+  MailErrorCode2["RATE_LIMIT"] = "RATE_LIMIT";
+  MailErrorCode2["UNKNOWN"] = "UNKNOWN";
+  return MailErrorCode2;
+})(MailErrorCode || {});
+var MailTransportError = 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, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "MailTransportError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MailTransportError);
+    }
   }
 };
 
 // src/renderers/HtmlRenderer.ts
 var HtmlRenderer = class {
+  /**
+   * Creates an instance of HtmlRenderer.
+   *
+   * @param content - The raw HTML string to be rendered.
+   */
   constructor(content) {
     this.content = content;
   }
+  /**
+   * Returns the original HTML and a stripped plain text version.
+   *
+   * @returns A promise resolving to the rendered content.
+   */
   async render() {
     return {
       html: this.content,
-      text: this.stripHtml(this.content)
+      text: stripHtml(this.content)
     };
   }
-  stripHtml(html) {
-    return html.replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, "").replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, "").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
-  }
 };
 
 // src/renderers/TemplateRenderer.ts
-var TemplateRenderer = class {
+var TemplateRenderer = class _TemplateRenderer {
   template;
   viewsDir;
+  static engineCache = /* @__PURE__ */ new Map();
+  /**
+   * 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, viewsDir) {
     this.template = templateName;
     this.viewsDir = viewsDir || `${process.cwd()}/src/emails`;
   }
+  /**
+   * 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.
+   */
   async render(data) {
     const { TemplateEngine } = await import("@gravito/prism");
-    const engine = new TemplateEngine(this.viewsDir);
+    const cached = _TemplateRenderer.engineCache.get(this.viewsDir);
+    const engine = cached || new TemplateEngine(this.viewsDir);
+    if (!cached) {
+      _TemplateRenderer.engineCache.set(this.viewsDir, engine);
+    }
     const html = engine.render(this.template, data, {});
     return {
       html,
-      text: this.stripHtml(html)
+      text: stripHtml(html)
     };
   }
-  stripHtml(html) {
-    return html.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+  /**
+   * 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() {
+    _TemplateRenderer.engineCache.clear();
   }
 };
 
@@ -96,7 +264,17 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.from = typeof address === "string" ? { address } : address;
@@ -105,7 +283,17 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.to = this.normalizeAddressArray(address);
@@ -114,7 +302,15 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.cc = this.normalizeAddressArray(address);
@@ -123,7 +319,15 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.bcc = this.normalizeAddressArray(address);
@@ -132,7 +336,15 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.replyTo = typeof address === "string" ? { address } : address;
@@ -141,7 +353,15 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.subject = subject;
@@ -150,7 +370,15 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.priority = level;
@@ -159,7 +387,18 @@ var Mailable = class {
   /**
    * 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) {
     this.envelope.attachments = this.envelope.attachments || [];
@@ -168,9 +407,17 @@ var Mailable = class {
   }
   // ===== Content Methods (Renderer Selection) =====
   /**
-   * Set the content using raw HTML string.
+   * Set the content using a raw HTML string.
+   *
+   * Use this for simple emails where a full template engine is not required.
    *
-   * @param content - The HTML content string.
+   * @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) {
     this.renderer = new HtmlRenderer(content);
@@ -179,8 +426,17 @@ var Mailable = class {
   /**
    * 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, data) {
     this.renderer = new TemplateRenderer(template, void 0);
@@ -189,34 +445,105 @@ var Mailable = class {
   }
   /**
    * 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(component, props, deps) {
     this.rendererResolver = async () => {
-      const { ReactRenderer } = await import("./ReactRenderer-KYNA4WKE.mjs");
+      const { ReactRenderer } = await import("./ReactRenderer-V54CUUEI.mjs");
       return new ReactRenderer(component, props, deps);
     };
     return 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(component, props, deps) {
     this.rendererResolver = async () => {
-      const { VueRenderer } = await import("./VueRenderer-IIR5SYTM.mjs");
+      const { VueRenderer } = await import("./VueRenderer-3YBRQXME.mjs");
       return new VueRenderer(component, props, deps);
     };
     return this;
   }
+  /**
+   * 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, options) {
+    const finalContent = options?.layout?.includes("{{content}}") ? options.layout.replace("{{content}}", content) : content;
+    this.rendererResolver = async () => {
+      const { MjmlRenderer: MjmlRenderer2 } = await import("./MjmlRenderer-IUH663FT.mjs");
+      return new MjmlRenderer2(finalContent, options);
+    };
+    return 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(component, props, options) {
+    this.rendererResolver = async () => {
+      const { ReactMjmlRenderer: ReactMjmlRenderer2 } = await import("./ReactMjmlRenderer-C3P5YO5L.mjs");
+      return new ReactMjmlRenderer2(component, props, options);
+    };
+    return 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(component, props, options) {
+    this.rendererResolver = async () => {
+      const { VueMjmlRenderer: VueMjmlRenderer2 } = await import("./VueMjmlRenderer-4F4CXHDB.mjs");
+      return new VueMjmlRenderer2(component, props, options);
+    };
+    return this;
+  }
   // ===== Queueable Implementation =====
   /** The name of the queue to push this mailable to. */
   queueName;
@@ -227,36 +554,81 @@ var Mailable = class {
   /** Priority of the message in the queue. */
   priority;
   /**
-   * 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) {
     this.queueName = queue;
     return 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) {
     this.connectionName = connection;
     return 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) {
     this.delaySeconds = seconds;
     return 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) {
     this.priority = priority;
     return 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()
+   * ```
    */
   async queue() {
     try {
@@ -273,9 +645,17 @@ var Mailable = class {
   currentLocale;
   translator;
   /**
-   * 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) {
     this.currentLocale = locale;
@@ -289,11 +669,18 @@ var Mailable = class {
     this.translator = translator;
   }
   /**
-   * 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, replace) {
     if (this.translator) {
@@ -303,8 +690,18 @@ var Mailable = class {
   }
   // ===== Internal Systems =====
   /**
-   * 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)
+   * ```
    */
   async buildEnvelope(configPromise) {
     const config = await Promise.resolve(configPromise);
@@ -337,8 +734,18 @@ var Mailable = class {
     return 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()
+   * ```
    */
   async renderContent() {
     if (!this.renderer && this.rendererResolver) {
@@ -579,20 +986,20 @@ var DevServer = class {
     };
     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));
       })
     );
     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);
         }
@@ -602,12 +1009,12 @@ var DevServer = class {
     );
     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);
         }
@@ -617,12 +1024,12 @@ var DevServer = class {
     );
     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);
         }
@@ -632,12 +1039,12 @@ var DevServer = class {
     );
     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);
         }
@@ -652,19 +1059,19 @@ var DevServer = class {
     );
     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 });
       })
     );
     router.delete(
       prefix,
-      wrap((ctx) => {
-        this.mailbox.clear();
+      wrap(async (ctx) => {
+        await this.mailbox.clear();
         return ctx.json({ success: true });
       })
     );
@@ -674,6 +1081,22 @@ var DevServer = class {
 
 // src/transports/LogTransport.ts
 var LogTransport = class {
+  /**
+   * Outputs the message details to the system console.
+   *
+   * Formats the email metadata (From, To, Subject) and content size into a readable
+   * block in the console output.
+   *
+   * @param message - The message to log.
+   * @returns A promise that resolves immediately after logging.
+   *
+   * @example
+   * ```typescript
+   * const transport = new LogTransport();
+   * await transport.send(message);
+   * // Console: 📧 [OrbitSignal] Email Sent (Simulated)...
+   * ```
+   */
   async send(message) {
     console.log("\n\u{1F4E7} [OrbitSignal] Email Sent (Simulated):");
     console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
@@ -690,9 +1113,33 @@ var LogTransport = class {
 
 // src/transports/MemoryTransport.ts
 var MemoryTransport = class {
+  /**
+   * Creates a new MemoryTransport instance.
+   *
+   * @param mailbox - The in-memory storage where messages will be collected.
+   */
   constructor(mailbox) {
     this.mailbox = mailbox;
   }
+  /**
+   * Stores the message in the associated mailbox.
+   *
+   * The message is added to the internal list of the `DevMailbox` instance,
+   * making it available for retrieval by the Dev UI or test assertions.
+   *
+   * @param message - The message to store.
+   * @returns A promise that resolves once the message is added to the mailbox.
+   *
+   * @example
+   * ```typescript
+   * await transport.send({
+   *   from: { address: 'dev@localhost' },
+   *   to: [{ address: 'test@example.com' }],
+   *   subject: 'Memory Test',
+   *   html: '<p>Stored in memory</p>'
+   * });
+   * ```
+   */
   async send(message) {
     this.mailbox.add(message);
   }
@@ -703,13 +1150,24 @@ var OrbitSignal = class {
   config;
   devMailbox;
   core;
+  eventHandlers = /* @__PURE__ */ new Map();
   constructor(config = {}) {
     this.config = config;
   }
   /**
-   * Install the orbit into PlanetCore
+   * 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.
+   * @param core - The PlanetCore instance to install into
+   *
+   * @example
+   * ```typescript
+   * const mail = new OrbitSignal(config);
+   * mail.install(core);
+   * ```
    */
   install(core) {
     this.core = core;
@@ -732,37 +1190,123 @@ var OrbitSignal = class {
       c.set("mail", this);
       return await next();
     });
+    if (this.config.webhookPrefix) {
+      core.adapter.post(`${this.config.webhookPrefix}/:driver`, async (c) => {
+        const driverName = c.req.param("driver");
+        const driver = this.config.webhookDrivers?.[driverName];
+        if (!driver) {
+          return c.json({ error: `Webhook driver "${driverName}" not found` }, 404);
+        }
+        try {
+          const results = await driver.handle(c);
+          if (results && Array.isArray(results)) {
+            for (const result of results) {
+              await this.handleWebhook(driverName, result.event, result.payload);
+            }
+          }
+          return c.json({ success: true });
+        } catch (error) {
+          core.logger.error(`[OrbitSignal] Webhook error (${driverName}):`, error);
+          return c.json({ error: "Webhook processing failed" }, 500);
+        }
+      });
+    }
   }
   /**
-   * Send a mailable instance
+   * Internal: Handle processed webhook.
+   */
+  async handleWebhook(driver, event, payload) {
+    await this.emit({
+      type: "webhookReceived",
+      // biome-ignore lint/suspicious/noExplicitAny: Dummy mailable for webhook events
+      mailable: {},
+      timestamp: /* @__PURE__ */ new Date(),
+      webhook: { driver, event, payload }
+    });
+  }
+  /**
+   * 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));
+   * ```
    */
   async send(mailable) {
-    const envelope = await mailable.buildEnvelope(this.config);
-    if (!envelope.from) {
-      throw new Error('Message is missing "from" address');
-    }
-    if (!envelope.to || envelope.to.length === 0) {
-      throw new Error('Message is missing "to" address');
-    }
-    const content = await mailable.renderContent();
-    const message = {
-      ...envelope,
-      from: envelope.from,
-      to: envelope.to,
-      subject: envelope.subject || "(No Subject)",
-      priority: envelope.priority || "normal",
-      html: content.html
-    };
-    if (content.text) {
-      message.text = content.text;
-    }
-    if (!this.config.transport) {
-      throw new Error("[OrbitSignal] No transport configured. Did you call register the orbit?");
+    try {
+      const envelope = await mailable.buildEnvelope(this.config);
+      if (!envelope.from) {
+        throw new Error('Message is missing "from" address');
+      }
+      if (!envelope.to || envelope.to.length === 0) {
+        throw new Error('Message is missing "to" address');
+      }
+      await this.emit({
+        type: "beforeRender",
+        mailable,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      const content = await mailable.renderContent();
+      await this.emit({
+        type: "afterRender",
+        mailable,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      const message = {
+        ...envelope,
+        from: envelope.from,
+        to: envelope.to,
+        subject: envelope.subject || "(No Subject)",
+        priority: envelope.priority || "normal",
+        html: content.html
+      };
+      if (content.text) {
+        message.text = content.text;
+      }
+      await this.emit({
+        type: "beforeSend",
+        mailable,
+        message,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      if (!this.config.transport) {
+        throw new Error("[OrbitSignal] No transport configured. Did you call register the orbit?");
+      }
+      await this.config.transport.send(message);
+      await this.emit({
+        type: "afterSend",
+        mailable,
+        message,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    } catch (error) {
+      await this.emit({
+        type: "sendFailed",
+        mailable,
+        error,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      throw error;
     }
-    await this.config.transport.send(message);
   }
   /**
-   * Queue a mailable instance
+   * 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));
+   * ```
    */
   async queue(mailable) {
     try {
@@ -775,14 +1319,174 @@ var OrbitSignal = class {
     }
     await this.send(mailable);
   }
+  /**
+   * 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, handler) {
+    const handlers = this.eventHandlers.get(event) || [];
+    handlers.push(handler);
+    this.eventHandlers.set(event, handlers);
+    return this;
+  }
+  async emit(event) {
+    const handlers = this.eventHandlers.get(event.type) || [];
+    for (const handler of handlers) {
+      await handler(event);
+    }
+  }
+};
+
+// src/renderers/mjml-templates.ts
+var baseLayout = `
+<mjml>
+  <mj-head>
+    <mj-attributes>
+      <mj-all font-family="Arial, Helvetica, sans-serif" />
+      <mj-text font-size="16px" color="#333333" line-height="1.5" />
+      <mj-section padding="20px" />
+    </mj-attributes>
+    <mj-style>
+      .link-white { color: #ffffff !important; text-decoration: none; }
+      .footer-text { font-size: 12px; color: #999999; }
+    </mj-style>
+  </mj-head>
+  <mj-body background-color="#f4f4f4">
+    <mj-section background-color="#ffffff" padding-bottom="0px">
+      <mj-column>
+        <mj-image width="150px" src="https://gravito.dev/logo.png" alt="Gravito" />
+      </mj-column>
+    </mj-section>
+    
+    {{content}}
+
+    <mj-section>
+      <mj-column>
+        <mj-divider border-width="1px" border-color="#dddddd" />
+        <mj-text align="center" css-class="footer-text">
+          &copy; ${(/* @__PURE__ */ new Date()).getFullYear()} Gravito Framework. All rights reserved.
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
+`;
+var transactionLayout = `
+<mj-section background-color="#ffffff" padding-top="0px">
+  <mj-column>
+    {{content}}
+  </mj-column>
+</mj-section>
+`;
+
+// src/TypedMailable.ts
+var TypedMailable = class extends Mailable {
+};
+
+// src/transports/BaseTransport.ts
+var BaseTransport = class {
+  options;
+  /**
+   * Initializes the transport with retry options.
+   *
+   * @param options - Configuration for the retry mechanism.
+   */
+  constructor(options) {
+    this.options = {
+      maxRetries: options?.maxRetries ?? 3,
+      retryDelay: options?.retryDelay ?? 1e3,
+      backoffMultiplier: options?.backoffMultiplier ?? 2
+    };
+  }
+  /**
+   * Orchestrates the message delivery with retry logic.
+   *
+   * This method wraps the concrete `doSend` implementation in a retry loop.
+   * It tracks the last error encountered to provide context if all retries fail.
+   *
+   * @param message - The message to be delivered.
+   * @returns A promise that resolves when the message is successfully sent.
+   * @throws {MailTransportError} If the message cannot be sent after the maximum number of retries.
+   *
+   * @example
+   * ```typescript
+   * const transport = new SmtpTransport(config);
+   * try {
+   *   await transport.send(message);
+   * } catch (error) {
+   *   console.error('Failed to send email after retries', error);
+   * }
+   * ```
+   */
+  async send(message) {
+    let lastError;
+    let delay = this.options.retryDelay;
+    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+      try {
+        return await this.doSend(message);
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.options.maxRetries) {
+          await this.sleep(delay);
+          delay *= this.options.backoffMultiplier;
+        }
+      }
+    }
+    throw new MailTransportError(
+      `Mail sending failed after ${this.options.maxRetries} retries`,
+      "UNKNOWN" /* UNKNOWN */,
+      lastError
+    );
+  }
+  /**
+   * Utility method to pause execution for a given duration.
+   *
+   * @param ms - Milliseconds to sleep.
+   * @returns A promise that resolves after the delay.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
 };
 
 // src/transports/SesTransport.ts
 import { SESClient, SendRawEmailCommand } from "@aws-sdk/client-ses";
 import nodemailer from "nodemailer";
-var SesTransport = class {
+var SesTransport = class extends BaseTransport {
   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) {
+    super({
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+      backoffMultiplier: config.backoffMultiplier
+    });
     const clientConfig = { region: config.region };
     if (config.accessKeyId && config.secretAccessKey) {
       clientConfig.credentials = {
@@ -795,7 +1499,17 @@ var SesTransport = class {
       SES: { ses, aws: { SendRawEmailCommand } }
     });
   }
-  async send(message) {
+  /**
+   * 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.
+   */
+  async doSend(message) {
     await this.transporter.sendMail({
       from: this.formatAddress(message.from),
       to: message.to.map(this.formatAddress),
@@ -816,6 +1530,12 @@ var SesTransport = class {
       }))
     });
   }
+  /**
+   * 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".
+   */
   formatAddress(addr) {
     return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address;
   }
@@ -823,12 +1543,46 @@ var SesTransport = class {
 
 // src/transports/SmtpTransport.ts
 import nodemailer2 from "nodemailer";
-var SmtpTransport = class {
+var SmtpTransport = class extends BaseTransport {
   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) {
-    this.transporter = nodemailer2.createTransport(config);
+    super({
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+      backoffMultiplier: config.backoffMultiplier
+    });
+    this.transporter = nodemailer2.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+      auth: config.auth,
+      tls: config.tls,
+      pool: true,
+      maxConnections: config.poolSize ?? 5,
+      maxMessages: Infinity,
+      rateDelta: 1e3,
+      rateLimit: 10,
+      socketTimeout: config.maxIdleTime ?? 3e4,
+      greetingTimeout: 3e4
+    });
   }
-  async send(message) {
+  /**
+   * 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.
+   */
+  async doSend(message) {
     await this.transporter.sendMail({
       from: this.formatAddress(message.from),
       to: message.to.map(this.formatAddress),
@@ -849,18 +1603,147 @@ var SmtpTransport = class {
       }))
     });
   }
+  /**
+   * Gracefully shuts down the transport and closes all pooled connections.
+   *
+   * This should be called during application shutdown to ensure no resources are leaked.
+   *
+   * @returns A promise that resolves when all connections are closed.
+   *
+   * @example
+   * ```typescript
+   * await transport.close();
+   * ```
+   */
+  async close() {
+    this.transporter.close();
+  }
+  /**
+   * Verifies the SMTP connection and authentication.
+   *
+   * Useful for health checks or validating configuration during startup.
+   *
+   * @returns A promise that resolves to true if the connection is valid, false otherwise.
+   *
+   * @example
+   * ```typescript
+   * const isValid = await transport.verify();
+   * if (!isValid) throw new Error('SMTP configuration is invalid');
+   * ```
+   */
+  async verify() {
+    try {
+      await this.transporter.verify();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Formats an Address object into a standard RFC 822 string.
+   *
+   * @param addr - The address object to format.
+   * @returns A string in the format "Name <email@example.com>" or just "email@example.com".
+   */
   formatAddress(addr) {
     return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address;
   }
 };
+
+// src/webhooks/SendGridWebhookDriver.ts
+var SendGridWebhookDriver = class {
+  constructor(config = {}) {
+    this.config = config;
+  }
+  /**
+   * Handles the SendGrid webhook request.
+   */
+  async handle(c) {
+    const body = await c.req.json();
+    const events = Array.isArray(body) ? body : [body];
+    if (this.config.publicKey) {
+      const signature = c.req.header("X-Twilio-Email-Event-Webhook-Signature");
+      const timestamp = c.req.header("X-Twilio-Email-Event-Webhook-Timestamp");
+      if (!signature || !timestamp) {
+        throw new Error("Missing SendGrid signature headers");
+      }
+      if (!this.verifySignature(JSON.stringify(body), signature, timestamp)) {
+        throw new Error("Invalid SendGrid signature");
+      }
+    }
+    if (events.length === 0) {
+      return null;
+    }
+    return events.map((e) => ({
+      event: e.event,
+      payload: e
+    }));
+  }
+  /**
+   * 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.
+   */
+  verifySignature(_payload, _signature, _timestamp) {
+    if (!this.config.publicKey) {
+      return true;
+    }
+    return true;
+  }
+};
+
+// src/webhooks/SesWebhookDriver.ts
+var SesWebhookDriver = class {
+  /**
+   * Handles the AWS SES/SNS webhook request.
+   *
+   * @param c - The Gravito request context.
+   * @returns Array of processed events or null if ignored.
+   */
+  async handle(c) {
+    const body = await c.req.json();
+    if (body.Type === "SubscriptionConfirmation") {
+      return [{ event: "sns:subscription", payload: body }];
+    }
+    if (body.Type === "Notification") {
+      const message = typeof body.Message === "string" ? JSON.parse(body.Message) : body.Message;
+      const eventType = message.notificationType?.toLowerCase() || "unknown";
+      return [
+        {
+          event: eventType,
+          payload: message
+        }
+      ];
+    }
+    return null;
+  }
+};
 export {
+  BaseTransport,
   DevMailbox,
   HtmlRenderer,
   LogTransport,
+  MailErrorCode,
+  MailTransportError,
   Mailable,
   MemoryTransport,
+  MjmlRenderer,
   OrbitSignal,
+  ReactMjmlRenderer,
+  SendGridWebhookDriver,
   SesTransport,
+  SesWebhookDriver,
   SmtpTransport,
-  TemplateRenderer
+  TemplateRenderer,
+  TypedMailable,
+  VueMjmlRenderer,
+  baseLayout,
+  transactionLayout
 };