@gravito/signal 3.0.3 → 3.1.0

package/dist/Queueable.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Queueable interface has been moved to `@gravito/stream`.
+ *
+ * This file is kept only as a backward-compatible re-export.
+ * New code should import from `@gravito/stream` directly.
+ *
+ * @deprecated Use `import type { Queueable } from '@gravito/stream'`
+ */
+export type { Queueable } from '@gravito/stream';

package/dist/TypedMailable.d.ts

@@ -0,0 +1,95 @@
+import { Mailable } from './Mailable';
+/**
+ * Abstract base class for strongly-typed Mailable messages.
+ *
+ * @description
+ * TypedMailable extends the base Mailable class to provide compile-time type safety
+ * for email data props. This ensures that the data passed to templates, React, or Vue
+ * components is correctly typed and validated at build time.
+ *
+ * @typeParam TData - The shape of data required by this mailable's template/component.
+ *                    Must extend Record<string, unknown>.
+ *
+ * @example
+ * ```typescript
+ * import { TypedMailable } from '@gravito/signal'
+ *
+ * // Define the data interface
+ * interface WelcomeData {
+ *   name: string
+ *   email: string
+ *   activationUrl: string
+ * }
+ *
+ * // Create strongly-typed mailable
+ * class WelcomeEmail extends TypedMailable<WelcomeData> {
+ *   protected data: WelcomeData
+ *
+ *   constructor(data: WelcomeData) {
+ *     super()
+ *     this.data = data
+ *   }
+ *
+ *   build() {
+ *     return this
+ *       .to(this.data.email)
+ *       .subject('Welcome to Gravito!')
+ *       .view('emails/welcome', this.data) // Type-safe: compiler ensures WelcomeData matches template
+ *   }
+ * }
+ *
+ * // Usage - compiler enforces correct data shape
+ * const email = new WelcomeEmail({
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   activationUrl: 'https://app.com/activate?token=abc123'
+ * })
+ *
+ * await mail.send(email)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With React components
+ * interface InvoiceData {
+ *   invoiceNumber: string
+ *   amount: number
+ *   dueDate: Date
+ *   items: Array<{ name: string; price: number }>
+ * }
+ *
+ * class InvoiceEmail extends TypedMailable<InvoiceData> {
+ *   protected data: InvoiceData
+ *
+ *   constructor(data: InvoiceData) {
+ *     super()
+ *     this.data = data
+ *   }
+ *
+ *   build() {
+ *     return this
+ *       .to('billing@example.com')
+ *       .subject(`Invoice ${this.data.invoiceNumber}`)
+ *       .react(InvoiceComponent, this.data) // Type-safe props
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Mailable} Base mailable class
+ * @see {@link OrbitSignal} Mail service orchestrator
+ *
+ * @public
+ * @since 3.0.0
+ */
+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/dist/events.d.ts

@@ -0,0 +1,63 @@
+import type { Mailable } from './Mailable';
+import type { Message } from './types';
+/**
+ * Mail event types.
+ *
+ * Defines the available lifecycle hooks for the mail service.
+ *
+ * @public
+ * @since 3.1.0
+ */
+export type MailEventType = 'beforeSend' | 'afterSend' | 'sendFailed' | 'beforeRender' | 'afterRender' | 'webhookReceived';
+/**
+ * Mail lifecycle event.
+ *
+ * Emitted at key points during email sending lifecycle.
+ * Used for logging, analytics, or custom processing.
+ *
+ * @example
+ * ```typescript
+ * mail.on('afterSend', async (event) => {
+ *   console.log('Email sent to:', event.message?.to)
+ * })
+ * ```
+ *
+ * @public
+ * @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;
+    };
+}
+/**
+ * Mail event handler function.
+ *
+ * Defines the signature for functions that subscribe to mail events.
+ *
+ * @param event - The mail event object
+ *
+ * @example
+ * ```typescript
+ * const handler: MailEventHandler = (event) => {
+ *   console.log(`Event ${event.type} triggered`);
+ * };
+ * ```
+ *
+ * @public
+ * @since 3.1.0
+ */
+export type MailEventHandler = (event: MailEvent) => void | Promise<void>;