@gravito/signal 3.1.0 → 4.0.0

package/src/OrbitSignal.ts

@@ -1,451 +0,0 @@
-import type { GravitoContext, GravitoNext, GravitoOrbit, PlanetCore } from '@gravito/core'
-import { DevMailbox } from './dev/DevMailbox'
-import { DevServer } from './dev/DevServer'
-import type { MailEvent, MailEventHandler, MailEventType } from './events'
-import type { Mailable } from './Mailable'
-import { LogTransport } from './transports/LogTransport'
-import { MemoryTransport } from './transports/MemoryTransport'
-import type { MailConfig, Message } 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 class OrbitSignal implements GravitoOrbit {
-  private config: MailConfig
-  private devMailbox?: DevMailbox
-  private core?: PlanetCore
-  private eventHandlers = new Map<MailEventType, MailEventHandler[]>()
-
-  constructor(config: MailConfig = {}) {
-    this.config = config
-  }
-
-  /**
-   * 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 {
-    this.core = core
-    core.logger.info('[OrbitSignal] Initializing Mail Service')
-
-    // 1. Ensure transport exists (fallback to Log if not set)
-    if (!this.config.transport && !this.config.devMode) {
-      this.config.transport = new LogTransport()
-    }
-
-    // 2. In Dev Mode, override transport and setup Dev Server
-    if (this.config.devMode) {
-      this.devMailbox = new DevMailbox()
-      this.config.transport = new MemoryTransport(this.devMailbox)
-      core.logger.info('[OrbitSignal] Dev Mode Enabled: Emails will be intercepted to Dev Mailbox')
-
-      const devServer = new DevServer(this.devMailbox, this.config.devUiPrefix || '/__mail', {
-        allowInProduction: this.config.devUiAllowInProduction,
-        gate: this.config.devUiGate,
-      })
-      devServer.register(core)
-    }
-
-    // 3. Register in container
-    core.container.instance('mail', this)
-
-    // 4. Inject mail service into context for easy access in routes
-    core.adapter.use('*', async (c: GravitoContext, next: GravitoNext) => {
-      c.set('mail', this)
-      return await next()
-    })
-
-    // 5. Register Webhook Endpoint
-    if (this.config.webhookPrefix) {
-      // @ts-expect-error: Accessing internal adapter methods
-      core.adapter.post(`${this.config.webhookPrefix}/:driver`, async (c: GravitoContext) => {
-        const driverName = c.req.param('driver')
-        const driver = this.config.webhookDrivers?.[driverName as string]
-
-        if (!driver) {
-          return c.json({ error: `Webhook driver "${driverName}" not found` }, 404)
-        }
-
-        try {
-          const results = await driver.handle(c)
-          if (results && Array.isArray(results)) {
-            for (const result of results) {
-              await this.handleWebhook(driverName as string, result.event, result.payload)
-            }
-          }
-          return c.json({ success: true })
-        } catch (error) {
-          core.logger.error(`[OrbitSignal] Webhook error (${driverName}):`, error)
-          return c.json({ error: 'Webhook processing failed' }, 500)
-        }
-      })
-    }
-  }
-
-  /**
-   * Internal: Handle processed webhook.
-   */
-  private async handleWebhook(driver: string, event: string, payload: any): Promise<void> {
-    // We don't have a specific mailable for generic webhooks, so we create a dummy or pass null
-    // But since MailEvent requires a mailable, we might need to adjust the interface or pass a Proxy
-    // For now, let's assume it's acceptable to emit with a partial event if types allow,
-    // or we might need to add a specialized emitWebhook method.
-
-    await this.emit({
-      type: 'webhookReceived',
-      // biome-ignore lint/suspicious/noExplicitAny: Dummy mailable for webhook events
-      mailable: {} as any,
-      timestamp: new Date(),
-      webhook: { driver, event, payload },
-    })
-  }
-
-  /**
-   * 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));
-   * ```
-   */
-  async send(mailable: Mailable): Promise<void> {
-    try {
-      // 1. Build envelope and get configuration
-      const envelope = await mailable.buildEnvelope(this.config)
-
-      // Validate required fields
-      if (!envelope.from) {
-        throw new Error('Message is missing "from" address')
-      }
-      if (!envelope.to || envelope.to.length === 0) {
-        throw new Error('Message is missing "to" address')
-      }
-
-      // 2. Emit beforeRender event
-      await this.emit({
-        type: 'beforeRender',
-        mailable,
-        timestamp: new Date(),
-      })
-
-      // 3. Render content
-      const content = await mailable.renderContent()
-
-      // 4. Emit afterRender event
-      await this.emit({
-        type: 'afterRender',
-        mailable,
-        timestamp: new Date(),
-      })
-
-      // 5. Construct full message
-      const message: Message = {
-        ...envelope,
-        from: envelope.from!,
-        to: envelope.to!,
-        subject: envelope.subject || '(No Subject)',
-        priority: envelope.priority || 'normal',
-        html: content.html,
-      }
-
-      if (content.text) {
-        message.text = content.text
-      }
-
-      // 6. Emit beforeSend event
-      await this.emit({
-        type: 'beforeSend',
-        mailable,
-        message,
-        timestamp: new Date(),
-      })
-
-      // 7. Send via transport
-      if (!this.config.transport) {
-        throw new Error('[OrbitSignal] No transport configured. Did you call register the orbit?')
-      }
-      await this.config.transport.send(message)
-
-      // 8. Emit afterSend event
-      await this.emit({
-        type: 'afterSend',
-        mailable,
-        message,
-        timestamp: new Date(),
-      })
-    } catch (error) {
-      // Emit sendFailed event
-      await this.emit({
-        type: 'sendFailed',
-        mailable,
-        error: error as Error,
-        timestamp: new Date(),
-      })
-      throw error
-    }
-  }
-
-  /**
-   * 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));
-   * ```
-   */
-  async queue(mailable: Mailable): Promise<void> {
-    try {
-      // 嘗試從容器獲取隊列服務 (OrbitStream)
-      const queue = this.core?.container.make<any>('queue')
-      if (queue) {
-        await queue.push(mailable)
-        return
-      }
-    } catch (_e) {
-      // 找不到隊列服務時，會拋出錯誤，我們捕捉並降級
-    }
-
-    // Fallback: 直接發送
-    await this.send(mailable)
-  }
-
-  /**
-   * 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 {
-    const handlers = this.eventHandlers.get(event) || []
-    handlers.push(handler)
-    this.eventHandlers.set(event, handlers)
-    return this
-  }
-
-  private async emit(event: MailEvent): Promise<void> {
-    const handlers = this.eventHandlers.get(event.type) || []
-    for (const handler of handlers) {
-      await handler(event)
-    }
-  }
-}
-
-// Module augmentation for GravitoVariables
-declare module '@gravito/core' {
-  interface GravitoVariables {
-    /** Mail service for sending emails */
-    mail?: OrbitSignal
-  }
-}

package/src/Queueable.ts

@@ -1,9 +0,0 @@
-/**
- * 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/src/TypedMailable.ts

@@ -1,96 +0,0 @@
-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 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/src/dev/DevMailbox.ts

@@ -1,146 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import type { Message } from '../types'
-import type { MailboxStorage } from './storage/MailboxStorage'
-import { MemoryMailboxStorage } from './storage/MemoryMailboxStorage'
-
-/**
- * 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 class DevMailbox {
-  private storage: MailboxStorage
-  private _maxEntries = 50
-
-  /**
-   * 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) {
-    if (maxEntries !== undefined) {
-      this._maxEntries = maxEntries
-    }
-    this.storage = storage ?? new MemoryMailboxStorage()
-  }
-
-  /**
-   * Adds a new message to the mailbox.
-   *
-   * If the mailbox exceeds the maximum capacity, the oldest messages are removed.
-   */
-  async add(message: Message): Promise<MailboxEntry> {
-    const entry: MailboxEntry = {
-      id: randomUUID(),
-      envelope: {
-        from: message.from,
-        to: message.to,
-        ...(message.cc ? { cc: message.cc } : {}),
-        ...(message.bcc ? { bcc: message.bcc } : {}),
-        ...(message.replyTo ? { replyTo: message.replyTo } : {}),
-        subject: message.subject,
-        ...(message.priority ? { priority: message.priority } : {}),
-        ...(message.attachments ? { attachments: message.attachments } : {}),
-      },
-      html: message.html,
-      ...(message.text ? { text: message.text } : {}),
-      sentAt: new Date(),
-    }
-
-    await this.storage.push(entry)
-    await this.storage.trim(this._maxEntries)
-
-    return entry
-  }
-
-  /**
-   * Sets the maximum number of emails to store.
-   *
-   * If the current mailbox exceeds the new capacity, the oldest messages are removed.
-   */
-  async setMaxEntries(count: number): Promise<void> {
-    this._maxEntries = count
-    await this.storage.trim(this._maxEntries)
-  }
-
-  /**
-   * Returns the maximum capacity of the mailbox.
-   */
-  get maxEntries(): number {
-    return this._maxEntries
-  }
-
-  /**
-   * Lists all messages in the mailbox.
-   */
-  async list(): Promise<MailboxEntry[]> {
-    return await this.storage.all()
-  }
-
-  /**
-   * Retrieves a specific message by ID.
-   */
-  async get(id: string): Promise<MailboxEntry | undefined> {
-    const entries = await this.storage.all()
-    return entries.find((e) => e.id === id)
-  }
-
-  /**
-   * Deletes a specific message by ID.
-   */
-  async delete(id: string): Promise<boolean> {
-    if (this.storage.delete) {
-      return await this.storage.delete(id)
-    }
-
-    const entries = await this.storage.all()
-    const index = entries.findIndex((e) => e.id === id)
-    if (index !== -1) {
-      await this.clear()
-      entries.splice(index, 1)
-      for (const entry of entries.reverse()) {
-        await this.storage.push(entry)
-      }
-      return true
-    }
-    return false
-  }
-
-  /**
-   * Clears all messages from the mailbox.
-   */
-  async clear(): Promise<void> {
-    await this.storage.clear()
-  }
-}