@gravito/signal 3.0.3 → 3.1.0

package/dist/index.d.ts

@@ -1,644 +1,32 @@
-import { Queueable } from '@gravito/stream';
-export { Queueable } from '@gravito/stream';
-import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
-
 /**
- * Interface for email transport mechanisms (SMTP, SES, etc.).
- *
- * @public
- * @since 3.0.0
- */
-interface Transport {
-    /**
-     * 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 used if not specified in the Mailable.
-     */
-    from?: Address;
-    /**
-     * The transport mechanism used to send emails (e.g., SMTP, SES, Log).
-     */
-    transport?: Transport;
-    /**
-     * 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 use with OrbitPrism.
-     * Default: src/emails
-     */
-    viewsDir?: string | undefined;
-    /**
-     * URL prefix for the Mail Dev UI.
-     * Default: /__mail
-     */
-    devUiPrefix?: string | undefined;
-    /**
-     * Whether to allow access to the Mail Dev UI in production environments.
-     * @default false
-     */
-    devUiAllowInProduction?: boolean | undefined;
-    /**
-     * 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 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;
-    add(message: Message): MailboxEntry;
-    list(): MailboxEntry[];
-    get(id: string): MailboxEntry | undefined;
-    delete(id: string): boolean;
-    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.
-     *
-     * @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 - 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;
-        renderToStaticMarkup?: (element: any) => string;
-    }): 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.
-     */
-    vue<P extends object>(component: ComponentType, props?: P, deps?: {
-        createSSRApp?: (...args: any[]) => any;
-        h?: (...args: any[]) => any;
-        renderToString?: (app: any) => Promise<string>;
-    }): 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 and produce HTML/Text content.
-     * @returns Object containing rendered html and optional text content.
-     */
-    renderContent(): Promise<{
-        html: string;
-        text?: string;
-    }>;
-    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?;
-    private core?;
-    constructor(config?: MailConfig);
-    /**
-     * Install the orbit into PlanetCore
-     *
-     * @param core - The PlanetCore instance.
-     */
-    install(core: PlanetCore): void;
-    /**
-     * Send a mailable instance
-     */
-    send(mailable: Mailable): Promise<void>;
-    /**
-     * Queue a mailable instance
-     */
-    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);
-    render(): Promise<RenderResult>;
-    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;
-    constructor(templateName: string, viewsDir?: string);
-    render(data: Record<string, unknown>): Promise<RenderResult>;
-    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);
-    send(message: Message): Promise<void>;
-    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);
-    send(message: Message): Promise<void>;
-    private formatAddress;
-}
-
-export { type Address, type Attachment, DevMailbox, type Envelope, HtmlRenderer, LogTransport, type MailConfig, Mailable, type MailboxEntry, MemoryTransport, type Message, OrbitSignal, type RenderResult, type Renderer, SesTransport, SmtpTransport, TemplateRenderer, type Transport };
+ * OrbitSignal - The central Event Bus and Mail Service for Gravito.
+ *
+ * This module provides the core infrastructure for sending emails and managing
+ * cross-module signals within the Gravito ecosystem. It supports multiple
+ * transport drivers, template rendering, and a robust development environment.
+ *
+ * @packageDocumentation
+ */
+export type { Queueable } from '@gravito/stream';
+export { DevMailbox, type MailboxEntry } from './dev/DevMailbox';
+export { MailErrorCode, MailTransportError } from './errors';
+export type { MailEvent, MailEventHandler, MailEventType } from './events';
+export { Mailable } from './Mailable';
+export { OrbitSignal } from './OrbitSignal';
+export { HtmlRenderer } from './renderers/HtmlRenderer';
+export { MjmlRenderer } from './renderers/MjmlRenderer';
+export * from './renderers/mjml-templates';
+export { ReactMjmlRenderer } from './renderers/ReactMjmlRenderer';
+export type { Renderer, RenderResult } from './renderers/Renderer';
+export { TemplateRenderer } from './renderers/TemplateRenderer';
+export { VueMjmlRenderer } from './renderers/VueMjmlRenderer';
+export { TypedMailable } from './TypedMailable';
+export { BaseTransport, type TransportOptions } from './transports/BaseTransport';
+export { LogTransport } from './transports/LogTransport';
+export { MemoryTransport } from './transports/MemoryTransport';
+export { SesTransport } from './transports/SesTransport';
+export { SmtpTransport } from './transports/SmtpTransport';
+export type { Transport } from './transports/Transport';
+export type { Address, Attachment, Envelope, MailConfig, Message, } from './types';
+export { type SendGridWebhookConfig, SendGridWebhookDriver } from './webhooks/SendGridWebhookDriver';
+export { SesWebhookDriver } from './webhooks/SesWebhookDriver';