@gravito/signal 3.0.4 → 3.1.2

package/README.md

@@ -2,21 +2,32 @@
 
 `@gravito/signal` is the powerful, multi-driver email framework for the Gravito ecosystem. It provides a clean, fluent API for building and sending emails with support for multiple rendering engines and transport drivers.
 
-## 🌟 Features
-
-- **Fluent API**: Expressive `Mailable` classes for building email messages.
-- **Multi-Driver Transport**: Support for SMTP (Nodemailer), AWS SES, Log (console), and Memory.
-- **Flexible Rendering**: Render email content using:
-  - Raw HTML
-  - **Prism** (Edge-optimized view engine)
-  - **React** Components (via `react-dom/server`)
-  - **Vue** Components (via `@vue/server-renderer`)
-- **Development Experience**:
-  - **Dev Mode**: Intercept emails locally and view them in a built-in UI.
-  - **Mailbox UI**: Access intercepted emails at `/__mail` during development.
-- **Queue Integration**: Built-in support for asynchronous email sending via `@gravito/stream`.
-- **Internationalization**: Integrated I18n support for localized email content.
-- **Type-Safe**: Written in TypeScript with full type safety for configuration and usage.
+## ✨ Features
+
+- 🚀 **Fluent API**: Expressive `Mailable` classes for building complex email messages with zero friction.
+- 🌌 **Galaxy-Ready**: A native Gravito Orbit that integrates seamlessly into the IoC container and context.
+- 🔌 **Multi-Driver Transport**: Support for SMTP, AWS SES, SendGrid, Log, and Memory drivers.
+- 🎨 **Modern Rendering**: Design emails using **React**, **Vue**, **MJML**, or **Prism** templates.
+- 📬 **Dev Mailbox UI**: Built-in visual interface at `/__mail` for local email inspection and debugging.
+- ⚙️ **Distributed Queueing**: Automatic offloading to `@gravito/stream` for background delivery.
+- 🛡️ **Webhook Processing**: Handle inbound delivery events (bounces, clicks) with ease.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Signal serves as the **Communication Nervous System**.
+
+- **Outbound Signal**: Satellites (domain plugins) trigger `Signal` to communicate with the outside world (users, other systems).
+- **Inbound Feedback**: Signal processes Webhooks from providers to update the state of the Galaxy (e.g., marking an email as invalid in the `Membership` Satellite).
+- **Event-Driven**: Leverages `@gravito/core`'s lifecycle to ensure emails are sent only after transactions are committed.
+
+```mermaid
+graph LR
+    S[Satellite] -->|Trigger| Signal[Signal Orbit]
+    Signal -->|Render| MW[MJML/React/Vue]
+    MW -->|Send| Provider[SES/SMTP]
+    Provider -.->|Webhook| Signal
+    Signal -.->|Event| S
+```
 
 ## 📦 Installation
 

package/dist/Mailable.d.ts

@@ -0,0 +1,453 @@
+import type { Queueable } from '@gravito/stream';
+import type { Renderer } from './renderers/Renderer';
+import type { Address, Attachment, Envelope, MailConfig } from './types';
+type ComponentType = any;
+/**
+ * Base class for all mailable messages.
+ *
+ * @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
+ * import { Mailable } from '@gravito/signal'
+ *
+ * class WelcomeEmail extends Mailable {
+ *   constructor(private user: User) {
+ *     super()
+ *   }
+ *
+ *   build() {
+ *     return this
+ *       .to(this.user.email)
+ *       .subject('Welcome!')
+ *       .view('emails/welcome', { name: this.user.name })
+ *   }
+ * }
+ *
+ * // 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
+ */
+export declare abstract class Mailable implements Queueable {
+    protected envelope: Partial<Envelope>;
+    protected renderer?: Renderer;
+    private rendererResolver?;
+    protected renderData: Record<string, unknown>;
+    protected config?: MailConfig;
+    /**
+     * Set the sender address for the email.
+     *
+     * 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.
+     *
+     * 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).
+     *
+     * 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).
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * 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 a raw HTML 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.
+     *
+     * 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.
+     *
+     * 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;
+        renderToStaticMarkup?: (element: any) => string;
+    }): this;
+    /**
+     * Set the content using a Vue component.
+     *
+     * 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;
+        h?: (...args: any[]) => any;
+        renderToString?: (app: any) => Promise<string>;
+    }): 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;
+    /**
+     * 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. */
+    queueName?: string;
+    /** The connection name for the queue. */
+    connectionName?: string;
+    /** Delay in seconds before the message is sent. */
+    delaySeconds?: number;
+    /** Priority of the message in the queue. */
+    priority?: number | string;
+    /**
+     * 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 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 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 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;
+    /**
+     * 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 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.
+     *
+     * @example
+     * ```typescript
+     * mailable.locale('es')
+     * ```
+     */
+    locale(locale: string): this;
+    /**
+     * Internal: Set the translator function (called by OrbitSignal)
+     * @internal
+     */
+    setTranslator(translator: (key: string, replace?: Record<string, unknown>, locale?: string) => string): void;
+    /**
+     * Translate a key into a localized string.
+     *
+     * 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 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>;
+    /**
+     * 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;
+        text?: string;
+    }>;
+    private normalizeAddressArray;
+}
+export {};