@gravito/signal 3.0.0 → 3.0.3

package/dist/index.d.ts

@@ -2,96 +2,178 @@ import { Queueable } from '@gravito/stream';
 export { Queueable } from '@gravito/stream';
 import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
 
-declare module '@gravito/core' {
-    interface GravitoVariables {
-        /** Mail service for sending emails */
-        mail?: {
-            send: (mailable: any) => Promise<void>;
-            queue: (mailable: any) => Promise<void>;
-        };
-    }
-}
-
+/**
+ * Interface for email transport mechanisms (SMTP, SES, etc.).
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface Transport {
     /**
-     * Send the given message
+     * Send the given message using the underlying transport.
+     *
+     * @param message - The finalized message to send.
      */
     send(message: Message): Promise<void>;
 }
 
+/**
+ * Representation of an email address with optional display name.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface Address {
+    /** The display name of the recipient/sender, e.g., "John Doe". */
     name?: string;
+    /** The actual email address string. */
     address: string;
 }
+/**
+ * Configuration for an email attachment.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface Attachment {
+    /** The filename of the attachment. */
     filename: string;
+    /** The content of the attachment as a string or Buffer. */
     content: string | Buffer;
+    /** Optional MIME type of the content. */
     contentType?: string;
+    /** Optional Content-ID for referencing within HTML content (inline images). */
     cid?: string;
+    /** Optional content encoding. */
     encoding?: string;
 }
+/**
+ * The envelope containing metadata for an email message.
+ *
+ * Used during the construction phase of a Mailable.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface Envelope {
+    /** The sender's address. */
     from?: Address | undefined;
+    /** Primary recipients. */
     to?: Address[] | undefined;
+    /** Carbon copy recipients. */
     cc?: Address[] | undefined;
+    /** Blind carbon copy recipients. */
     bcc?: Address[] | undefined;
+    /** Reply-to address. */
     replyTo?: Address | undefined;
+    /** Email subject line. */
     subject?: string | undefined;
+    /** Importance level of the email. */
     priority?: 'high' | 'normal' | 'low' | undefined;
+    /** List of file attachments. */
     attachments?: Attachment[] | undefined;
 }
+/**
+ * A fully finalized email message ready to be sent by a transport.
+ *
+ * Requires mandatory fields that were optional in the Envelope.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface Message extends Envelope {
+    /** The mandatory sender's address. */
     from: Address;
+    /** At least one recipient is required. */
     to: Address[];
+    /** Mandatory subject. */
     subject: string;
+    /** The rendered HTML body content. */
     html: string;
+    /** Optional rendered plain text body content. */
     text?: string;
+    /** Custom SMTP headers. */
     headers?: Record<string, string>;
 }
+/**
+ * Global configuration options for OrbitSignal and Mailable instances.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface MailConfig {
     /**
-     * Default sender address
+     * Default sender address used if not specified in the Mailable.
      */
     from?: Address;
     /**
-     * The transport mechanism used to send emails
+     * The transport mechanism used to send emails (e.g., SMTP, SES, Log).
      */
     transport?: Transport;
     /**
-     * Enable development mode (intercepts emails)
+     * Enable development mode.
+     * When true, emails are intercepted by the DevMailbox instead of being sent.
      */
     devMode?: boolean | undefined;
     /**
-     * Directory where email templates are located (for OrbitPrism)
+     * Directory where email templates are located for use with OrbitPrism.
      * Default: src/emails
      */
     viewsDir?: string | undefined;
     /**
-     * URL prefix for Dev UI
+     * URL prefix for the Mail Dev UI.
      * Default: /__mail
      */
     devUiPrefix?: string | undefined;
     /**
-     * Allow Dev UI in production. Default: false.
+     * Whether to allow access to the Mail Dev UI in production environments.
+     * @default false
      */
     devUiAllowInProduction?: boolean | undefined;
     /**
-     * Gate access to Dev UI (required in production unless allowInProduction is true).
+     * Authorization gate for the Mail Dev UI.
+     * Should return true to allow access to the UI.
      */
     devUiGate?: ((ctx: GravitoContext) => boolean | Promise<boolean>) | undefined;
     /**
-     * Translation function for i18n support
+     * Translation function for internationalization within emails.
      */
     translator?: ((key: string, replace?: Record<string, unknown>, locale?: string) => string) | undefined;
 }
 
+/**
+ * Represents a captured email in the development mailbox.
+ *
+ * @public
+ */
 interface MailboxEntry {
+    /** Unique identifier for the email */
     id: string;
+    /** Email envelope information (from, to, subject, etc.) */
     envelope: Envelope;
+    /** HTML content of the email */
     html: string;
+    /** Plain text content of the email (optional) */
     text?: string;
+    /** Timestamp when the email was captured */
     sentAt: Date;
 }
+/**
+ * In-memory mailbox for capturing emails during development.
+ *
+ * Stores up to 50 recent emails and provides methods to list,
+ * retrieve, and delete captured messages.
+ *
+ * @example
+ * ```typescript
+ * const mailbox = new DevMailbox()
+ * mailbox.add(message)
+ * const emails = mailbox.list()
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class DevMailbox {
     private entries;
     private maxEntries;
@@ -102,45 +184,129 @@ declare class DevMailbox {
     clear(): void;
 }
 
+/**
+ * Result of a content rendering operation.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RenderResult {
+    /** Rendered HTML string. */
     html: string;
+    /** Optional rendered plain text string. */
     text?: string;
 }
+/**
+ * Interface for email content renderers (HTML, Template, React, Vue).
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface Renderer {
     /**
-     * Render the content into HTML and optionally plain text
+     * Render the content into HTML and optionally plain text.
+     *
+     * @param data - The data context for rendering.
      */
     render(data: Record<string, unknown>): Promise<RenderResult>;
 }
 
 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).
+ *
+ * @example
+ * ```typescript
+ * class WelcomeMail extends Mailable {
+ *   build() {
+ *     return this.subject('Welcome!')
+ *                .view('emails.welcome', { name: 'John' });
+ *   }
+ * }
+ *
+ * await new WelcomeMail().to('john@example.com').send();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 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.
+     *
+     * @param address - Email address or Address object.
+     */
     from(address: string | Address): this;
+    /**
+     * Set the primary recipient(s) for the email.
+     *
+     * @param address - Single address, address object, or array of either.
+     */
     to(address: string | Address | (string | Address)[]): this;
+    /**
+     * Set the carbon copy (CC) recipient(s).
+     *
+     * @param address - Single address, address object, or array of either.
+     */
     cc(address: string | Address | (string | Address)[]): this;
+    /**
+     * Set the blind carbon copy (BCC) recipient(s).
+     *
+     * @param address - Single address, address object, or array of either.
+     */
     bcc(address: string | Address | (string | Address)[]): this;
+    /**
+     * Set the reply-to address.
+     *
+     * @param address - Email address or Address object.
+     */
     replyTo(address: string | Address): this;
+    /**
+     * Set the subject line for the email.
+     *
+     * @param subject - The email subject.
+     */
     subject(subject: string): this;
+    /**
+     * Set the email priority.
+     *
+     * @param level - Priority level ('high', 'normal', or 'low').
+     */
     emailPriority(level: 'high' | 'normal' | 'low'): this;
+    /**
+     * Attach a file to the email.
+     *
+     * @param attachment - Attachment configuration object.
+     */
     attach(attachment: Attachment): this;
     /**
      * Set the content using raw HTML string.
+     *
+     * @param content - The HTML content string.
      */
     html(content: string): this;
     /**
      * Set the content using an OrbitPrism template.
-     * @param template Template name (relative to viewsDir/emails)
-     * @param data Data to pass to the template
+     *
+     * @param template - Template name (relative to viewsDir/emails).
+     * @param data - Optional data to pass to the template.
      */
     view(template: string, data?: Record<string, unknown>): this;
     /**
      * Set the content using a React component.
      * Dynamically imports ReactRenderer to avoid hard dependency errors if React is not installed.
+     *
+     * @param component - The React component to render.
+     * @param props - Optional props for the component.
+     * @param deps - Optional dependencies (React, ReactDOMServer) if not globally available.
      */
     react<P extends object>(component: ComponentType, props?: P, deps?: {
         createElement?: (...args: any[]) => any;
@@ -149,6 +315,10 @@ declare 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.
      */
     vue<P extends object>(component: ComponentType, props?: P, deps?: {
         createSSRApp?: (...args: any[]) => any;
@@ -157,40 +327,67 @@ declare abstract class Mailable implements Queueable {
     }): this;
     /**
      * Setup the mailable. This is where you call from(), to(), view(), etc.
+     * This method must be implemented by concrete classes.
      */
     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 queue name for this mailable.
+     */
     onQueue(queue: string): this;
+    /**
+     * Set the connection name for this mailable.
+     */
     onConnection(connection: string): this;
+    /**
+     * Set a delay for the queued mailable.
+     */
     delay(seconds: number): this;
+    /**
+     * Set the priority for the queued mailable.
+     */
     withPriority(priority: string | number): this;
     /**
      * Queue the mailable for sending.
+     * Attempts to resolve the mail service from the PlanetCore container.
      */
     queue(): Promise<void>;
     protected currentLocale?: string;
     protected translator?: (key: string, replace?: Record<string, unknown>, locale?: string) => string;
     /**
      * Set the locale for the message.
+     *
+     * @param locale - Valid locale string (e.g., 'en', 'zh-TW').
      */
     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 string using the configured translator.
+     *
+     * @param key - Translation key.
+     * @param replace - Interpolation variables.
+     * @returns Translated string or the key if translator is missing.
      */
     t(key: string, replace?: Record<string, unknown>): string;
     /**
      * Compile the envelope based on config defaults and mailable settings.
+     * Called by OrbitSignal before rendering/sending.
      */
     buildEnvelope(configPromise: MailConfig | Promise<MailConfig>): Promise<Envelope>;
     /**
-     * execute the renderer
+     * Execute the renderer and produce HTML/Text content.
+     * @returns Object containing rendered html and optional text content.
      */
     renderContent(): Promise<{
         html: string;
@@ -199,6 +396,37 @@ declare abstract class Mailable implements Queueable {
     private normalizeAddressArray;
 }
 
+/**
+ * OrbitSignal - Mail service orbit for Gravito framework.
+ *
+ * Provides email sending capabilities with support for multiple transports,
+ * development mode with email preview UI, and queue integration.
+ *
+ * @example
+ * ```typescript
+ * import { OrbitSignal } from '@gravito/signal'
+ * import { SmtpTransport } from '@gravito/signal'
+ *
+ * const app = new Application({
+ *   orbits: [
+ *     new OrbitSignal({
+ *       transport: new SmtpTransport({
+ *         host: 'smtp.example.com',
+ *         port: 587,
+ *         auth: { user: 'user', pass: 'pass' }
+ *       }),
+ *       from: { name: 'App', email: 'noreply@example.com' }
+ *     })
+ *   ]
+ * })
+ *
+ * // In route handler
+ * await c.get('mail').send(new WelcomeEmail(user))
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class OrbitSignal implements GravitoOrbit {
     private config;
     private devMailbox?;
@@ -212,10 +440,6 @@ declare class OrbitSignal implements GravitoOrbit {
     install(core: PlanetCore): void;
     /**
      * Send a mailable instance
-     *
-     * @param mailable - The mailable object to send.
-     * @returns A promise that resolves when the email is sent.
-     * @throws {Error} If the message is missing "from" or "to" addresses, or if no transport is configured.
      */
     send(mailable: Mailable): Promise<void>;
     /**
@@ -223,7 +447,30 @@ declare class OrbitSignal implements GravitoOrbit {
      */
     queue(mailable: Mailable): Promise<void>;
 }
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Mail service for sending emails */
+        mail?: OrbitSignal;
+    }
+}
 
+/**
+ * Renderer for plain HTML content.
+ *
+ * Renders static HTML strings and automatically generates
+ * a plain text version by stripping HTML tags.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new HtmlRenderer('<h1>Hello</h1><p>World</p>')
+ * const { html, text } = await renderer.render()
+ * // html: '<h1>Hello</h1><p>World</p>'
+ * // text: 'Hello World'
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class HtmlRenderer implements Renderer {
     private content;
     constructor(content: string);
@@ -231,6 +478,21 @@ declare class HtmlRenderer implements Renderer {
     private stripHtml;
 }
 
+/**
+ * Renderer for template-based emails using Gravito Prism.
+ *
+ * Renders email templates from the filesystem using the Prism
+ * template engine with support for data binding and layouts.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new TemplateRenderer('welcome', './src/emails')
+ * const { html, text } = await renderer.render({ name: 'John' })
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class TemplateRenderer implements Renderer {
     private template;
     private viewsDir;
@@ -239,21 +501,81 @@ declare class TemplateRenderer implements Renderer {
     private stripHtml;
 }
 
+/**
+ * Log transport for development and testing.
+ *
+ * Logs email details to the console instead of sending them.
+ * Useful for debugging and local development.
+ *
+ * @example
+ * ```typescript
+ * const transport = new LogTransport()
+ * await transport.send(message)
+ * // Outputs email details to console
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class LogTransport implements Transport {
     send(message: Message): Promise<void>;
 }
 
+/**
+ * Memory transport for development mode.
+ *
+ * Captures emails to an in-memory mailbox instead of sending them.
+ * Used automatically when `devMode` is enabled in OrbitSignal.
+ *
+ * @example
+ * ```typescript
+ * const mailbox = new DevMailbox()
+ * const transport = new MemoryTransport(mailbox)
+ * await transport.send(message)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class MemoryTransport implements Transport {
     private mailbox;
     constructor(mailbox: DevMailbox);
     send(message: Message): Promise<void>;
 }
 
+/**
+ * Configuration for AWS SES email transport.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SesConfig {
+    /** AWS region (e.g., 'us-east-1') */
     region: string;
+    /** AWS access key ID (optional, uses default credentials if not provided) */
     accessKeyId?: string;
+    /** AWS secret access key (optional, uses default credentials if not provided) */
     secretAccessKey?: string;
 }
+/**
+ * AWS SES (Simple Email Service) transport.
+ *
+ * Sends emails using Amazon SES with support for attachments,
+ * HTML/text content, and all standard email features.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SesTransport({
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+ * })
+ * await transport.send(message)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class SesTransport implements Transport {
     private transporter;
     constructor(config: SesConfig);
@@ -261,19 +583,57 @@ declare class SesTransport implements Transport {
     private formatAddress;
 }
 
+/**
+ * Configuration for SMTP email transport.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SmtpConfig {
+    /** SMTP server hostname */
     host: string;
+    /** SMTP server port (typically 25, 465, or 587) */
     port: number;
+    /** Use TLS/SSL connection (true for port 465) */
     secure?: boolean;
+    /** Authentication credentials */
     auth?: {
+        /** SMTP username */
         user: string;
+        /** SMTP password */
         pass: string;
     };
+    /** TLS options */
     tls?: {
+        /** Reject unauthorized certificates */
         rejectUnauthorized?: boolean;
+        /** Cipher suite */
         ciphers?: string;
     };
 }
+/**
+ * SMTP email transport.
+ *
+ * Sends emails using standard SMTP protocol with support for
+ * authentication, TLS/SSL, attachments, and all email features.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SmtpTransport({
+ *   host: 'smtp.gmail.com',
+ *   port: 587,
+ *   secure: false,
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password'
+ *   }
+ * })
+ * await transport.send(message)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 declare class SmtpTransport implements Transport {
     private transporter;
     constructor(config: SmtpConfig);