@gravito/signal 3.0.4 → 3.1.2

package/dist/renderers/HtmlRenderer.d.ts

@@ -0,0 +1,34 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * 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
+ */
+export 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>;
+}

package/dist/renderers/MjmlRenderer.d.ts

@@ -0,0 +1,41 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * 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
+ */
+export 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>;
+}

package/dist/renderers/ReactMjmlRenderer.d.ts

@@ -0,0 +1,38 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * 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
+ */
+export 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, 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>;
+}

package/dist/renderers/ReactRenderer.d.ts

@@ -0,0 +1,46 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * Renderer for React component-based emails.
+ *
+ * Renders React components to static HTML using server-side rendering (SSR).
+ * It lazily loads React and ReactDOM dependencies only when needed, preventing
+ * unnecessary bundle bloat for users who do not use React renderers.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new ReactRenderer(MyComponent, { title: 'Welcome' });
+ * const result = await renderer.render({ name: 'John' });
+ * ```
+ *
+ * @typeParam P - Props type for the React component.
+ * @public
+ * @since 3.0.0
+ */
+export declare class ReactRenderer<P extends object = object> implements Renderer {
+    private component;
+    private props?;
+    private deps;
+    /**
+     * Creates an instance of ReactRenderer.
+     *
+     * @param component - The React component to render.
+     * @param props - Initial props for the component.
+     * @param deps - Optional dependency injection for testing.
+     */
+    constructor(component: any, // Use any to avoid hard React dependency in types
+    props?: P, deps?: {
+        createElement?: (...args: any[]) => any;
+        renderToStaticMarkup?: (element: any) => string;
+    });
+    /**
+     * Renders the React component to a static HTML string.
+     *
+     * This method performs dynamic imports of `react` and `react-dom/server`
+     * to ensure they are only loaded if this renderer is actually used.
+     *
+     * @param data - Runtime data to be merged with initial props.
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If React dependencies cannot be loaded or rendering fails.
+     */
+    render(data: Record<string, unknown>): Promise<RenderResult>;
+}

package/{src/renderers/Renderer.ts → dist/renderers/Renderer.d.ts}

@@ -18,20 +18,19 @@
  * @since 3.0.0
  */
 export interface RenderResult {
-  /**
-   * The rendered HTML string.
-   *
-   * This is the primary content used for the email body.
-   */
-  html: string
-  /**
-   * Optional rendered plain text string.
-   *
-   * Used as a fallback for email clients that cannot display HTML or for accessibility.
-   */
-  text?: string
+    /**
+     * The rendered HTML string.
+     *
+     * This is the primary content used for the email body.
+     */
+    html: 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.
  *
@@ -53,15 +52,15 @@ export interface RenderResult {
  * @since 3.0.0
  */
 export 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>
+    /**
+     * 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>;
 }

package/dist/renderers/TemplateRenderer.d.ts

@@ -0,0 +1,55 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * 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
+ */
+export 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;
+}

package/dist/renderers/VueMjmlRenderer.d.ts

@@ -0,0 +1,39 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * 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
+ */
+export 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, 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>;
+}

package/dist/renderers/VueRenderer.d.ts

@@ -0,0 +1,47 @@
+import type { Renderer, RenderResult } from './Renderer';
+/**
+ * Renderer for Vue component-based emails.
+ *
+ * Renders Vue 3 components to static HTML using server-side rendering (SSR).
+ * It lazily loads Vue and `@vue/server-renderer` dependencies only when needed,
+ * preventing unnecessary bundle bloat for users who do not use Vue renderers.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new VueRenderer(MyComponent, { title: 'Welcome' });
+ * const result = await renderer.render({ name: 'John' });
+ * ```
+ *
+ * @typeParam P - Props type for the Vue component.
+ * @public
+ * @since 3.0.0
+ */
+export declare class VueRenderer<P extends object = object> implements Renderer {
+    private component;
+    private props?;
+    private deps;
+    /**
+     * Creates an instance of VueRenderer.
+     *
+     * @param component - The Vue component to render.
+     * @param props - Initial props for the component.
+     * @param deps - Optional dependency injection for testing.
+     */
+    constructor(component: any, // Use any to avoid hard Vue dependency in types
+    props?: P, deps?: {
+        createSSRApp?: (...args: any[]) => any;
+        h?: (...args: any[]) => any;
+        renderToString?: (app: any) => Promise<string>;
+    });
+    /**
+     * Renders the Vue component to a static HTML string.
+     *
+     * This method performs dynamic imports of `vue` and `@vue/server-renderer`
+     * to ensure they are only loaded if this renderer is actually used.
+     *
+     * @param data - Runtime data to be merged with initial props.
+     * @returns A promise resolving to the rendered content.
+     * @throws {Error} If Vue dependencies cannot be loaded or rendering fails.
+     */
+    render(data: Record<string, unknown>): Promise<RenderResult>;
+}

package/dist/renderers/mjml-templates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Base layout for MJML emails.
+ * Includes common head styles and responsive settings.
+ *
+ * Placeholder: {{content}}
+ */
+export declare const baseLayout: string;
+/**
+ * A simple transactional component layout.
+ */
+export declare const transactionLayout = "\n<mj-section background-color=\"#ffffff\" padding-top=\"0px\">\n  <mj-column>\n    {{content}}\n  </mj-column>\n</mj-section>\n";

package/dist/transports/BaseTransport.d.ts

@@ -0,0 +1,111 @@
+import type { Message, Transport } from '../types';
+/**
+ * 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
+ */
+export 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
+ */
+export 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;
+}

package/dist/transports/LogTransport.d.ts

@@ -0,0 +1,42 @@
+import type { Message, Transport } from '../types';
+/**
+ * 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
+ */
+export 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>;
+}

package/dist/transports/MemoryTransport.d.ts

@@ -0,0 +1,51 @@
+import type { DevMailbox } from '../dev/DevMailbox';
+import type { Message, Transport } from '../types';
+/**
+ * Memory transport for development mode.
+ *
+ * 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
+ * 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
+ * ```
+ *
+ * @public
+ */
+export 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>;
+}

package/dist/transports/SesTransport.d.ts

@@ -0,0 +1,79 @@
+import type { Message } from '../types';
+import { BaseTransport, type TransportOptions } from './BaseTransport';
+/**
+ * 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
+ */
+export interface SesConfig extends TransportOptions {
+    /** AWS region where the SES service is hosted (e.g., 'us-east-1'). */
+    region: string;
+    /** AWS access key ID. If omitted, the SDK will attempt to use default credential providers. */
+    accessKeyId?: string;
+    /** AWS secret access key. Required if accessKeyId is provided. */
+    secretAccessKey?: string;
+}
+/**
+ * AWS SES (Simple Email Service) transport with automatic retry.
+ *
+ * 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-west-2'
+ * });
+ *
+ * await transport.send(message);
+ * ```
+ *
+ * @public
+ */
+export 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);
+    /**
+     * 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;
+}