@gravito/signal 3.0.3 → 3.0.4

package/src/Mailable.ts

@@ -11,21 +11,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
  */
@@ -41,7 +73,17 @@ export 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 {
     this.envelope.from = typeof address === 'string' ? { address } : address
@@ -51,7 +93,17 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.to = this.normalizeAddressArray(address)
@@ -61,7 +113,15 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.cc = this.normalizeAddressArray(address)
@@ -71,7 +131,15 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.bcc = this.normalizeAddressArray(address)
@@ -81,7 +149,15 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.replyTo = typeof address === 'string' ? { address } : address
@@ -91,7 +167,15 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.subject = subject
@@ -101,7 +185,15 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.priority = level
@@ -111,7 +203,18 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.envelope.attachments = this.envelope.attachments || []
@@ -122,9 +225,17 @@ export abstract class Mailable implements Queueable {
   // ===== 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: string): this {
     this.renderer = new HtmlRenderer(content)
@@ -134,8 +245,17 @@ export abstract class Mailable implements Queueable {
   /**
    * 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 {
     this.renderer = new TemplateRenderer(template, undefined) // Dir will be injected later if possible, or use default
@@ -145,11 +265,19 @@ export abstract class Mailable implements Queueable {
 
   /**
    * 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,
@@ -168,11 +296,19 @@ export abstract class Mailable implements Queueable {
 
   /**
    * 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,
@@ -190,11 +326,91 @@ export abstract class Mailable implements Queueable {
     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: string, options?: Record<string, any> & { layout?: string }): this {
+    const finalContent = options?.layout?.includes('{{content}}')
+      ? options.layout.replace('{{content}}', content)
+      : content
+
+    this.rendererResolver = async () => {
+      const { MjmlRenderer } = await import('./renderers/MjmlRenderer')
+      return new MjmlRenderer(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<P extends object>(
+    component: ComponentType,
+    props?: P,
+    options?: Record<string, any>
+  ): this {
+    this.rendererResolver = async () => {
+      const { ReactMjmlRenderer } = await import('./renderers/ReactMjmlRenderer')
+      return new ReactMjmlRenderer(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<P extends object>(
+    component: ComponentType,
+    props?: P,
+    options?: Record<string, any>
+  ): this {
+    this.rendererResolver = async () => {
+      const { VueMjmlRenderer } = await import('./renderers/VueMjmlRenderer')
+      return new VueMjmlRenderer(component, props, options)
+    }
+    return this
+  }
+
   // ===== Life Cycle =====
 
   /**
-   * Setup the mailable. This is where you call from(), to(), view(), etc.
-   * This method must be implemented by concrete classes.
+   * 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
 
@@ -210,7 +426,15 @@ export abstract class Mailable implements Queueable {
   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 {
     this.queueName = queue
@@ -218,7 +442,15 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * 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 {
     this.connectionName = connection
@@ -226,7 +458,17 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * 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 {
     this.delaySeconds = seconds
@@ -234,7 +476,17 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * 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 {
     this.priority = priority
@@ -242,8 +494,17 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * 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(): Promise<void> {
     // We should ideally use the container to get the mail service
@@ -268,9 +529,17 @@ export abstract class Mailable implements Queueable {
   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 {
     this.currentLocale = locale
@@ -288,11 +557,18 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * 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 {
     if (this.translator) {
@@ -304,8 +580,18 @@ export abstract class Mailable implements Queueable {
   // ===== 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: MailConfig | Promise<MailConfig>): Promise<Envelope> {
     const config = await Promise.resolve(configPromise)
@@ -348,8 +634,18 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * 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(): Promise<{ html: string; text?: string }> {
     // Resolve lazy renderer if needed