@gravito/signal 3.0.3 → 3.1.0

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 {};

package/dist/OrbitSignal.d.ts

@@ -0,0 +1,267 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+import type { MailEventHandler, MailEventType } from './events';
+import type { Mailable } from './Mailable';
+import type { MailConfig } from './types';
+/**
+ * OrbitSignal - Mail service orbit for Gravito framework.
+ *
+ * @description
+ * A production-ready email service providing multi-transport support, automatic retry,
+ * event-driven lifecycle hooks, and development tooling. Integrates seamlessly with
+ * Gravito's orbit system and queue infrastructure.
+ *
+ * @architecture
+ * ```
+ * OrbitSignal
+ *   ├── Configuration (MailConfig)
+ *   │   ├── transport: Transport (SMTP, SES, Log, Memory)
+ *   │   ├── from: Default sender
+ *   │   ├── devMode: Development interception
+ *   │   └── translator: i18n support
+ *   ├── Lifecycle Events
+ *   │   ├── beforeRender → afterRender
+ *   │   ├── beforeSend → afterSend
+ *   │   └── sendFailed (on error)
+ *   ├── Transport Layer
+ *   │   ├── BaseTransport (retry, backoff)
+ *   │   ├── SmtpTransport (connection pooling)
+ *   │   ├── SesTransport (AWS SES)
+ *   │   ├── LogTransport (console output)
+ *   │   └── MemoryTransport (dev mode)
+ *   └── Dev Tools
+ *       ├── DevMailbox (in-memory storage)
+ *       └── DevServer (preview UI at /__mail)
+ * ```
+ *
+ * @example
+ * **Basic SMTP Configuration**
+ * ```typescript
+ * import { OrbitSignal, SmtpTransport } from '@gravito/signal'
+ *
+ * const mail = new OrbitSignal({
+ *   transport: new SmtpTransport({
+ *     host: 'smtp.mailtrap.io',
+ *     port: 2525,
+ *     auth: { user: 'username', pass: 'password' }
+ *   }),
+ *   from: { name: 'My App', address: 'noreply@myapp.com' }
+ * })
+ *
+ * mail.install(core)
+ * ```
+ *
+ * @example
+ * **AWS SES with Retry Configuration**
+ * ```typescript
+ * import { OrbitSignal, SesTransport } from '@gravito/signal'
+ *
+ * const mail = new OrbitSignal({
+ *   transport: new SesTransport({
+ *     region: 'us-east-1',
+ *     retries: 3,
+ *     retryDelay: 1000,
+ *     retryMultiplier: 2
+ *   }),
+ *   from: { name: 'Production App', address: 'noreply@example.com' }
+ * })
+ * ```
+ *
+ * @example
+ * **Development Mode with Preview UI**
+ * ```typescript
+ * const mail = new OrbitSignal({
+ *   devMode: process.env.NODE_ENV === 'development',
+ *   devUiPrefix: '/__mail',
+ *   from: { name: 'Dev App', address: 'dev@localhost' }
+ * })
+ *
+ * // All emails intercepted to memory, view at http://localhost:3000/__mail
+ * ```
+ *
+ * @example
+ * **Event-Driven Analytics & Error Handling**
+ * ```typescript
+ * const mail = new OrbitSignal({ ... })
+ *
+ * // Track successful sends
+ * mail.on('afterSend', async (event) => {
+ *   await analytics.track('email_sent', {
+ *     to: event.message?.to,
+ *     subject: event.message?.subject,
+ *     timestamp: event.timestamp
+ *   })
+ * })
+ *
+ * // Log failures for monitoring
+ * mail.on('sendFailed', async (event) => {
+ *   logger.error('Email send failed', {
+ *     error: event.error?.message,
+ *     mailable: event.mailable.constructor.name
+ *   })
+ *   await sentry.captureException(event.error)
+ * })
+ * ```
+ *
+ * @example
+ * **SMTP with Connection Pooling**
+ * ```typescript
+ * const mail = new OrbitSignal({
+ *   transport: new SmtpTransport({
+ *     host: 'smtp.gmail.com',
+ *     port: 465,
+ *     secure: true,
+ *     auth: { user: 'user@gmail.com', pass: 'app-password' },
+ *     poolSize: 5,
+ *     maxIdleTime: 30000
+ *   })
+ * })
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', async () => {
+ *   await mail.config.transport?.close?.()
+ * })
+ * ```
+ *
+ * @example
+ * **Usage in Route Handlers**
+ * ```typescript
+ * // Injected automatically into GravitoContext
+ * app.post('/register', async (c) => {
+ *   const user = await createUser(c.req.json())
+ *
+ *   await c.get('mail').send(new WelcomeEmail(user))
+ *
+ *   return c.json({ success: true })
+ * })
+ * ```
+ *
+ * @example
+ * **Queue Integration for Background Processing**
+ * ```typescript
+ * // Requires @gravito/stream
+ * const email = new WelcomeEmail(user)
+ *   .onQueue('emails')
+ *   .delay(60)
+ *
+ * await email.queue()
+ * ```
+ *
+ * @example
+ * **Error Handling Best Practices**
+ * ```typescript
+ * try {
+ *   await mail.send(new InvoiceEmail(order))
+ * } catch (error) {
+ *   if (error instanceof MailTransportError) {
+ *     switch (error.code) {
+ *       case MailErrorCode.RATE_LIMIT:
+ *         await queue.pushDelayed(email, 300)
+ *         break
+ *       case MailErrorCode.RECIPIENT_REJECTED:
+ *         await markUserEmailInvalid(user.id)
+ *         break
+ *       default:
+ *         throw error
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Mailable} Base class for email definitions
+ * @see {@link TypedMailable} Strongly-typed mailable with generic data
+ * @see {@link Transport} Transport interface
+ * @see {@link BaseTransport} Retry-enabled base transport
+ * @see {@link MailConfig} Configuration interface
+ * @see {@link MailEvent} Event types
+ * @see {@link MailTransportError} Error handling
+ *
+ * @since 3.0.0
+ * @public
+ */
+export declare class OrbitSignal implements GravitoOrbit {
+    private config;
+    private devMailbox?;
+    private core?;
+    private eventHandlers;
+    constructor(config?: MailConfig);
+    /**
+     * Install the orbit into PlanetCore.
+     *
+     * Registers the mail service in the IoC container and sets up development
+     * tools if enabled. It also injects the service into the GravitoContext
+     * for easy access in route handlers.
+     *
+     * @param core - The PlanetCore instance to install into
+     *
+     * @example
+     * ```typescript
+     * const mail = new OrbitSignal(config);
+     * mail.install(core);
+     * ```
+     */
+    install(core: PlanetCore): void;
+    /**
+     * Internal: Handle processed webhook.
+     */
+    private handleWebhook;
+    /**
+     * Send a mailable instance immediately.
+     *
+     * Orchestrates the full email sending lifecycle: building the envelope,
+     * rendering content, emitting events, and delivering via the configured transport.
+     *
+     * @param mailable - The email definition to send
+     * @throws {Error} If mandatory fields (from, to) are missing or transport fails
+     *
+     * @example
+     * ```typescript
+     * await mail.send(new WelcomeEmail(user));
+     * ```
+     */
+    send(mailable: Mailable): Promise<void>;
+    /**
+     * Queue a mailable instance for background processing.
+     *
+     * Attempts to use the 'queue' service (OrbitStream) if available in the
+     * container. Falls back to immediate sending if no queue service is found.
+     *
+     * @param mailable - The email definition to queue
+     *
+     * @example
+     * ```typescript
+     * await mail.queue(new WelcomeEmail(user));
+     * ```
+     */
+    queue(mailable: Mailable): Promise<void>;
+    /**
+     * Register an event handler.
+     *
+     * @description
+     * Subscribe to mail lifecycle events for logging, analytics, or custom processing.
+     *
+     * @param event - The event type to listen for
+     * @param handler - The handler function to execute
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * mail.on('afterSend', async (event) => {
+     *   await analytics.track('email_sent', {
+     *     to: event.message?.to,
+     *     subject: event.message?.subject
+     *   })
+     * })
+     * ```
+     *
+     * @public
+     * @since 3.1.0
+     */
+    on(event: MailEventType, handler: MailEventHandler): this;
+    private emit;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Mail service for sending emails */
+        mail?: OrbitSignal;
+    }
+}