@gravito/signal 3.0.4 → 3.1.2

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

package/{src/Queueable.ts → dist/Queueable.d.ts}

@@ -6,4 +6,4 @@
  *
  * @deprecated Use `import type { Queueable } from '@gravito/stream'`
  */
-export type { Queueable } from '@gravito/stream'
+export type { Queueable } from '@gravito/stream';

package/{src/TypedMailable.ts → dist/TypedMailable.d.ts}

@@ -1,5 +1,4 @@
-import { Mailable } from './Mailable'
-
+import { Mailable } from './Mailable';
 /**
  * Abstract base class for strongly-typed Mailable messages.
  *
@@ -82,15 +81,15 @@ import { Mailable } from './Mailable'
  * @public
  * @since 3.0.0
  */
-export abstract class TypedMailable<TData extends Record<string, unknown>> extends Mailable {
-  /**
-   * The strongly-typed data for this mailable.
-   *
-   * This property holds the data that will be passed to the template or component
-   * during rendering. By defining it as an abstract property with the generic
-   * type TData, we force subclasses to provide a concrete, type-safe implementation.
-   *
-   * @protected
-   */
-  protected abstract data: TData
+export declare abstract class TypedMailable<TData extends Record<string, unknown>> extends Mailable {
+    /**
+     * The strongly-typed data for this mailable.
+     *
+     * This property holds the data that will be passed to the template or component
+     * during rendering. By defining it as an abstract property with the generic
+     * type TData, we force subclasses to provide a concrete, type-safe implementation.
+     *
+     * @protected
+     */
+    protected abstract data: TData;
 }

package/dist/dev/DevMailbox.d.ts

@@ -0,0 +1,79 @@
+import type { Message } from '../types';
+import type { MailboxStorage } from './storage/MailboxStorage';
+/**
+ * Entry structure for messages stored in DevMailbox.
+ */
+export interface MailboxEntry {
+    /** Unique identifier for the entry. */
+    id: string;
+    /** The email envelope metadata. */
+    envelope: any;
+    /** The rendered HTML content. */
+    html: string;
+    /** Optional plain text content. */
+    text?: string;
+    /** Timestamp when the message was captured. */
+    sentAt: Date;
+}
+/**
+ * Capture and store emails during development for preview and testing.
+ *
+ * Supports different storage engines (Memory, FileSystem) and implements
+ * capacity limits via a Ring Buffer strategy.
+ *
+ * @example
+ * ```typescript
+ * // Default memory mailbox
+ * const mailbox = new DevMailbox()
+ *
+ * // Persistent file mailbox
+ * const storage = new FileMailboxStorage('./storage/mail')
+ * const persistentMailbox = new DevMailbox(100, storage)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
+export declare class DevMailbox {
+    private storage;
+    private _maxEntries;
+    /**
+     * Creates an instance of DevMailbox.
+     *
+     * @param maxEntries - Maximum number of emails to store (default: 50)
+     * @param storage - Optional custom storage engine (defaults to Memory)
+     */
+    constructor(maxEntries?: number, storage?: MailboxStorage);
+    /**
+     * Adds a new message to the mailbox.
+     *
+     * If the mailbox exceeds the maximum capacity, the oldest messages are removed.
+     */
+    add(message: Message): Promise<MailboxEntry>;
+    /**
+     * Sets the maximum number of emails to store.
+     *
+     * If the current mailbox exceeds the new capacity, the oldest messages are removed.
+     */
+    setMaxEntries(count: number): Promise<void>;
+    /**
+     * Returns the maximum capacity of the mailbox.
+     */
+    get maxEntries(): number;
+    /**
+     * Lists all messages in the mailbox.
+     */
+    list(): Promise<MailboxEntry[]>;
+    /**
+     * Retrieves a specific message by ID.
+     */
+    get(id: string): Promise<MailboxEntry | undefined>;
+    /**
+     * Deletes a specific message by ID.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Clears all messages from the mailbox.
+     */
+    clear(): Promise<void>;
+}

package/dist/dev/DevServer.d.ts

@@ -0,0 +1,39 @@
+import type { GravitoContext, PlanetCore } from '@gravito/core';
+import type { DevMailbox } from './DevMailbox';
+/**
+ * Configuration options for the development mail server.
+ *
+ * @public
+ */
+export type DevServerOptions = {
+    /** Allow access in production environment (use with caution) */
+    allowInProduction?: boolean;
+    /** Custom gate function to control access to the dev UI */
+    gate?: (c: GravitoContext) => boolean | Promise<boolean>;
+};
+/**
+ * Development mail server for previewing captured emails.
+ *
+ * Provides a web UI at the configured base path (default: `/__mail`)
+ * to view, preview, and manage emails captured during development.
+ *
+ * @example
+ * ```typescript
+ * const mailbox = new DevMailbox()
+ * const devServer = new DevServer(mailbox, '/__mail', {
+ *   gate: (c) => c.get('user')?.isAdmin
+ * })
+ * devServer.register(core)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
+export declare class DevServer {
+    private mailbox;
+    private base;
+    private options?;
+    constructor(mailbox: DevMailbox, base?: string, options?: DevServerOptions);
+    private canAccess;
+    register(core: PlanetCore): void;
+}

package/dist/dev/storage/FileMailboxStorage.d.ts

@@ -0,0 +1,16 @@
+import type { MailboxEntry } from '../DevMailbox';
+import type { MailboxStorage } from './MailboxStorage';
+/**
+ * File-based storage for DevMailbox (Persistence).
+ * Stores emails as JSON in a specified directory.
+ */
+export declare class FileMailboxStorage implements MailboxStorage {
+    private filePath;
+    constructor(storageDir: string);
+    all(): Promise<MailboxEntry[]>;
+    push(entry: MailboxEntry): Promise<void>;
+    trim(max: number): Promise<void>;
+    clear(): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    private save;
+}

package/dist/dev/storage/MailboxStorage.d.ts

@@ -0,0 +1,14 @@
+import type { MailboxEntry } from '../DevMailbox';
+/**
+ * Interface for DevMailbox storage engines.
+ */
+export interface MailboxStorage {
+    /** Retrieve all entries. */
+    all(): Promise<MailboxEntry[]>;
+    /** Add a single entry. */
+    push(entry: MailboxEntry): Promise<void>;
+    /** Trim entries to a specific count. */
+    trim(max: number): Promise<void>;
+    clear(): Promise<void>;
+    delete?(id: string): Promise<boolean>;
+}

package/dist/dev/storage/MemoryMailboxStorage.d.ts

@@ -0,0 +1,13 @@
+import type { MailboxEntry } from '../DevMailbox';
+import type { MailboxStorage } from './MailboxStorage';
+/**
+ * Memory-based storage for DevMailbox (Default).
+ */
+export declare class MemoryMailboxStorage implements MailboxStorage {
+    private entries;
+    all(): Promise<MailboxEntry[]>;
+    push(entry: MailboxEntry): Promise<void>;
+    trim(max: number): Promise<void>;
+    clear(): Promise<void>;
+    delete(id: string): Promise<boolean>;
+}

package/dist/dev/ui/mailbox.d.ts

@@ -0,0 +1,11 @@
+import type { MailboxEntry } from '../DevMailbox';
+/**
+ * Generates the HTML for the mailbox list view.
+ *
+ * @param entries - Array of mailbox entries to display
+ * @param prefix - Base URL prefix for the dev server
+ * @returns HTML string for the mailbox UI
+ *
+ * @internal
+ */
+export declare function getMailboxHtml(entries: MailboxEntry[], prefix: string): string;

package/dist/dev/ui/preview.d.ts

@@ -0,0 +1,11 @@
+import type { MailboxEntry } from '../DevMailbox';
+/**
+ * Generates the HTML for the email preview page.
+ *
+ * @param entry - Mailbox entry to preview
+ * @param prefix - Base URL prefix for the dev server
+ * @returns HTML string for the preview UI
+ *
+ * @internal
+ */
+export declare function getPreviewHtml(entry: MailboxEntry, prefix: string): string;

package/dist/dev/ui/shared.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CSS styles for the development mail UI.
+ * @internal
+ */
+export declare const styles = "\n:root {\n  --primary: #6366f1;\n  --primary-dark: #4f46e5;\n  --bg-dark: #0f172a;\n  --bg-card: #1e293b;\n  --text: #f1f5f9;\n  --text-muted: #94a3b8;\n  --border: #334155;\n  --danger: #ef4444;\n}\nbody { background: var(--bg-dark); color: var(--text); font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif; margin: 0; padding: 20px; }\n.container { max-width: 1000px; margin: 0 auto; }\n.header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px; }\n.title { font-size: 24px; font-weight: bold; display: flex; align-items: center; gap: 10px; }\n.card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }\n.btn { background: var(--border); color: var(--text); border: none; padding: 8px 16px; border-radius: 6px; cursor: pointer; text-decoration: none; font-size: 14px; transition: 0.2s; }\n.btn:hover { background: var(--bg-card-hover); }\n.btn-primary { background: var(--primary); color: white; }\n.btn-primary:hover { background: var(--primary-dark); }\n.btn-danger { background: var(--danger); color: white; }\n.list-item { padding: 16px; border-bottom: 1px solid var(--border); display: flex; flex-direction: column; gap: 4px; text-decoration: none; color: inherit; transition: background 0.2s; }\n.list-item:last-child { border-bottom: none; }\n.list-item:hover { background: #334155; }\n.meta { display: flex; justify-content: space-between; font-size: 14px; color: var(--text-muted); }\n.subject { font-weight: 600; font-size: 16px; }\n.from { color: #cbd5e1; }\n.badge { background: #475569; padding: 2px 6px; border-radius: 4px; font-size: 12px; }\n.badge-high { background: #dc2626; color: white; }\n.empty { padding: 40px; text-align: center; color: var(--text-muted); }\n";
+/**
+ * HTML layout wrapper for dev mail UI pages.
+ *
+ * @param title - Page title
+ * @param content - HTML content to inject
+ * @returns Complete HTML document
+ *
+ * @internal
+ */
+export declare const layout: (title: string, content: string) => string;

package/dist/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Mail transport error codes.
+ *
+ * Categorizes common failure modes in the mail delivery process to allow
+ * for programmatic handling (e.g., retries on rate limits).
+ *
+ * @public
+ * @since 3.1.0
+ */
+export declare enum MailErrorCode {
+    /** Connection to mail server failed */
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    /** Authentication with mail server failed */
+    AUTH_FAILED = "AUTH_FAILED",
+    /** One or more recipients were rejected by the server */
+    RECIPIENT_REJECTED = "RECIPIENT_REJECTED",
+    /** The message was rejected by the server */
+    MESSAGE_REJECTED = "MESSAGE_REJECTED",
+    /** Rate limit exceeded */
+    RATE_LIMIT = "RATE_LIMIT",
+    /** Unknown or unclassified error */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Error class for mail transport failures.
+ *
+ * Provides structured error information for mail sending failures,
+ * including error codes and original cause tracking for debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new MailTransportError(
+ *   'Failed to connect to SMTP server',
+ *   MailErrorCode.CONNECTION_FAILED,
+ *   originalError
+ * )
+ * ```
+ *
+ * @public
+ * @since 3.1.0
+ */
+export declare class MailTransportError extends Error {
+    readonly code: MailErrorCode;
+    readonly cause?: Error;
+    /**
+     * Create a new mail transport error.
+     *
+     * @param message - Human-readable error message
+     * @param code - Categorized error code
+     * @param cause - Original error that caused this failure
+     *
+     * @example
+     * ```typescript
+     * const error = new MailTransportError('Auth failed', MailErrorCode.AUTH_FAILED);
+     * ```
+     */
+    constructor(message: string, code: MailErrorCode, cause?: Error);
+}

package/{src/events.ts → dist/events.d.ts}

@@ -1,6 +1,5 @@
-import type { Mailable } from './Mailable'
-import type { Message } from './types'
-
+import type { Mailable } from './Mailable';
+import type { Message } from './types';
 /**
  * Mail event types.
  *
@@ -9,14 +8,7 @@ import type { Message } from './types'
  * @public
  * @since 3.1.0
  */
-export type MailEventType =
-  | 'beforeSend'
-  | 'afterSend'
-  | 'sendFailed'
-  | 'beforeRender'
-  | 'afterRender'
-  | 'webhookReceived'
-
+export type MailEventType = 'beforeSend' | 'afterSend' | 'sendFailed' | 'beforeRender' | 'afterRender' | 'webhookReceived';
 /**
  * Mail lifecycle event.
  *
@@ -34,24 +26,23 @@ export type MailEventType =
  * @since 3.1.0
  */
 export interface MailEvent {
-  /** Type of event */
-  type: MailEventType
-  /** Mailable instance that triggered the event */
-  mailable: Mailable
-  /** Finalized message (available for send events) */
-  message?: Message
-  /** Error that occurred (available for sendFailed event) */
-  error?: Error
-  /** Timestamp when event occurred */
-  timestamp: Date
-  /** Webhook payload (available for webhookReceived event) */
-  webhook?: {
-    driver: string
-    event: string
-    payload: any
-  }
+    /** Type of event */
+    type: MailEventType;
+    /** Mailable instance that triggered the event */
+    mailable: Mailable;
+    /** Finalized message (available for send events) */
+    message?: Message;
+    /** Error that occurred (available for sendFailed event) */
+    error?: Error;
+    /** Timestamp when event occurred */
+    timestamp: Date;
+    /** Webhook payload (available for webhookReceived event) */
+    webhook?: {
+        driver: string;
+        event: string;
+        payload: any;
+    };
 }
-
 /**
  * Mail event handler function.
  *
@@ -69,4 +60,4 @@ export interface MailEvent {
  * @public
  * @since 3.1.0
  */
-export type MailEventHandler = (event: MailEvent) => void | Promise<void>
+export type MailEventHandler = (event: MailEvent) => void | Promise<void>;