@gravito/signal 3.1.0 → 3.1.2

package/src/dev/DevServer.ts

@@ -1,192 +0,0 @@
-import type { GravitoContext, PlanetCore } from '@gravito/core'
-import type { DevMailbox } from './DevMailbox'
-import { getMailboxHtml } from './ui/mailbox'
-import { getPreviewHtml } from './ui/preview'
-
-/**
- * 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 class DevServer {
-  constructor(
-    private mailbox: DevMailbox,
-    private base = '/__mail',
-    private options?: DevServerOptions
-  ) {}
-
-  private async canAccess(ctx: GravitoContext): Promise<boolean> {
-    const isProduction = process.env.NODE_ENV === 'production'
-    if (isProduction && !this.options?.allowInProduction && !this.options?.gate) {
-      return false
-    }
-    if (this.options?.gate) {
-      return await this.options.gate(ctx)
-    }
-    return true
-  }
-
-  register(core: PlanetCore): void {
-    const router = core.router
-    const isProduction = process.env.NODE_ENV === 'production'
-
-    if (isProduction && !this.options?.allowInProduction && !this.options?.gate) {
-      core.logger.warn(
-        '[OrbitSignal] Dev Mailbox disabled in production. Configure a gate to allow access.'
-      )
-      return
-    }
-
-    // Remove trailing slash
-    const prefix = this.base.replace(/\/$/, '')
-
-    const wrap = (handler: (ctx: GravitoContext) => Response | Promise<Response>) => {
-      return async (ctx: GravitoContext) => {
-        const allowed = await this.canAccess(ctx)
-        if (!allowed) {
-          return ctx.text('Unauthorized', 403)
-        }
-        return await handler(ctx)
-      }
-    }
-
-    // 1. Mailbox List
-    router.get(
-      prefix,
-      wrap(async (ctx) => {
-        const entries = await this.mailbox.list()
-        ctx.header('Content-Type', 'text/html; charset=utf-8')
-        return ctx.html(getMailboxHtml(entries, prefix))
-      })
-    )
-
-    // 2. Single Email Preview
-    router.get(
-      `${prefix}/:id`,
-      wrap(async (ctx) => {
-        const id = ctx.req.param('id')
-        if (!id) {
-          return ctx.text('Bad Request', 400)
-        }
-
-        const entry = await this.mailbox.get(id)
-        if (!entry) {
-          return ctx.text('Email not found', 404)
-        }
-        ctx.header('Content-Type', 'text/html; charset=utf-8')
-        return ctx.html(getPreviewHtml(entry, prefix))
-      })
-    )
-
-    // 3. Iframe Content: HTML
-    router.get(
-      `${prefix}/:id/html`,
-      wrap(async (ctx) => {
-        const id = ctx.req.param('id')
-        if (!id) {
-          return ctx.text('Bad Request', 400)
-        }
-
-        const entry = await this.mailbox.get(id)
-        if (!entry) {
-          return ctx.text('Not found', 404)
-        }
-        ctx.header('Content-Type', 'text/html; charset=utf-8')
-        return ctx.html(entry.html)
-      })
-    )
-
-    // 4. Iframe Content: Text
-    router.get(
-      `${prefix}/:id/text`,
-      wrap(async (ctx) => {
-        const id = ctx.req.param('id')
-        if (!id) {
-          return ctx.text('Bad Request', 400)
-        }
-
-        const entry = await this.mailbox.get(id)
-        if (!entry) {
-          return ctx.text('Not found', 404)
-        }
-
-        ctx.header('Content-Type', 'text/plain; charset=utf-8')
-        return ctx.text(entry.text || 'No text content', 200)
-      })
-    )
-
-    // 5. Raw JSON
-    router.get(
-      `${prefix}/:id/raw`,
-      wrap(async (ctx) => {
-        const id = ctx.req.param('id')
-        if (!id) {
-          return ctx.json({ error: 'Bad Request' }, 400)
-        }
-
-        const entry = await this.mailbox.get(id)
-        if (!entry) {
-          return ctx.json({ error: 'Not found' }, 404)
-        }
-        return ctx.json(entry)
-      })
-    )
-
-    // 6. API: Delete Single
-    router.get(
-      `${prefix}/:id/delete`,
-      wrap((ctx) => {
-        return ctx.text('Method not allowed', 405)
-      })
-    )
-
-    router.delete(
-      `${prefix}/:id`,
-      wrap(async (ctx) => {
-        const id = ctx.req.param('id')
-        if (!id) {
-          return ctx.json({ success: false, error: 'Bad Request' }, 400)
-        }
-
-        const success = await this.mailbox.delete(id)
-        return ctx.json({ success })
-      })
-    )
-
-    // 7. API: Clear All
-    router.delete(
-      prefix,
-      wrap(async (ctx) => {
-        await this.mailbox.clear()
-        return ctx.json({ success: true })
-      })
-    )
-
-    core.logger.info(`[OrbitSignal] Dev Mailbox available at ${prefix}`)
-  }
-}

package/src/dev/storage/FileMailboxStorage.ts

@@ -1,66 +0,0 @@
-import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-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 class FileMailboxStorage implements MailboxStorage {
-  private filePath: string
-
-  constructor(storageDir: string) {
-    this.filePath = join(storageDir, 'mailbox.json')
-  }
-
-  async all(): Promise<MailboxEntry[]> {
-    try {
-      const content = await readFile(this.filePath, 'utf-8')
-      return JSON.parse(content)
-    } catch (_e) {
-      return []
-    }
-  }
-
-  async push(entry: MailboxEntry): Promise<void> {
-    const entries = await this.all()
-    entries.unshift(entry)
-    await this.save(entries)
-  }
-
-  async trim(max: number): Promise<void> {
-    const entries = await this.all()
-    if (entries.length > max) {
-      await this.save(entries.slice(0, max))
-    }
-  }
-
-  async clear(): Promise<void> {
-    try {
-      await unlink(this.filePath)
-    } catch (_e) {
-      // Ignore if file doesn't exist
-    }
-  }
-
-  async delete(id: string): Promise<boolean> {
-    const entries = await this.all()
-    const index = entries.findIndex((e) => e.id === id)
-    if (index !== -1) {
-      entries.splice(index, 1)
-      await this.save(entries)
-      return true
-    }
-    return false
-  }
-
-  private async save(entries: MailboxEntry[]): Promise<void> {
-    try {
-      await mkdir(join(this.filePath, '..'), { recursive: true })
-      await writeFile(this.filePath, JSON.stringify(entries, null, 2), 'utf-8')
-    } catch (error) {
-      console.error('[FileMailboxStorage] Failed to save mailbox:', error)
-    }
-  }
-}

package/src/dev/storage/MailboxStorage.ts

@@ -1,15 +0,0 @@
-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/src/dev/storage/MemoryMailboxStorage.ts

@@ -1,36 +0,0 @@
-import type { MailboxEntry } from '../DevMailbox'
-import type { MailboxStorage } from './MailboxStorage'
-
-/**
- * Memory-based storage for DevMailbox (Default).
- */
-export class MemoryMailboxStorage implements MailboxStorage {
-  private entries: MailboxEntry[] = []
-
-  async all(): Promise<MailboxEntry[]> {
-    return [...this.entries]
-  }
-
-  async push(entry: MailboxEntry): Promise<void> {
-    this.entries.unshift(entry)
-  }
-
-  async trim(max: number): Promise<void> {
-    if (this.entries.length > max) {
-      this.entries = this.entries.slice(0, max)
-    }
-  }
-
-  async clear(): Promise<void> {
-    this.entries = []
-  }
-
-  async delete(id: string): Promise<boolean> {
-    const index = this.entries.findIndex((e) => e.id === id)
-    if (index !== -1) {
-      this.entries.splice(index, 1)
-      return true
-    }
-    return false
-  }
-}

package/src/dev/ui/mailbox.ts

@@ -1,77 +0,0 @@
-import type { MailboxEntry } from '../DevMailbox'
-import { layout } from './shared'
-
-function formatAddress(addr: { name?: string; address: string }): string {
-  return addr.name ? `${addr.name} <${addr.address}>` : addr.address
-}
-
-function timeAgo(date: Date): string {
-  const seconds = Math.floor((Date.now() - date.getTime()) / 1000)
-  if (seconds < 60) {
-    return 'Just now'
-  }
-  const minutes = Math.floor(seconds / 60)
-  if (minutes < 60) {
-    return `${minutes}m ago`
-  }
-  const hours = Math.floor(minutes / 60)
-  if (hours < 24) {
-    return `${hours}h ago`
-  }
-  return date.toLocaleDateString()
-}
-
-/**
- * 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 function getMailboxHtml(entries: MailboxEntry[], prefix: string): string {
-  const list =
-    entries.length === 0
-      ? '<div class="empty">No emails found in mailbox.</div>'
-      : entries
-          .map(
-            (entry) => `
-      <a href="${prefix}/${entry.id}" class="list-item">
-        <div class="meta">
-          <span class="from">${formatAddress(entry.envelope.from || { address: 'Unknown' })}</span>
-          <span>${timeAgo(entry.sentAt)}</span>
-        </div>
-        <div class="subject">
-          ${entry.envelope.priority === 'high' ? '<span class="badge badge-high">High</span> ' : ''}
-          ${entry.envelope.subject || '(No Subject)'}
-        </div>
-        <div class="meta" style="margin-top: 4px;">
-           To: ${entry.envelope.to?.map((t: any) => t.address).join(', ')}
-        </div>
-      </a>
-    `
-          )
-          .join('')
-
-  const content = `
-    <div class="header">
-      <div class="title">📬 Gravito Mailbox</div>
-      ${entries.length > 0 ? `<button onclick="clearAll()" class="btn btn-danger">Clear All</button>` : ''}
-    </div>
-    
-    <div class="card">
-      ${list}
-    </div>
-
-    <script>
-      async function clearAll() {
-        if (!confirm('Clear all emails?')) return;
-        await fetch('${prefix}', { method: 'DELETE' });
-        window.location.reload();
-      }
-    </script>
-  `
-
-  return layout('Inbox', content)
-}

package/src/dev/ui/preview.ts

@@ -1,103 +0,0 @@
-import type { MailboxEntry } from '../DevMailbox'
-import { layout } from './shared'
-
-/**
- * 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 function getPreviewHtml(entry: MailboxEntry, prefix: string): string {
-  const from = entry.envelope.from
-    ? `${entry.envelope.from.name || ''} <${entry.envelope.from.address}>`
-    : 'Unknown'
-  const to = entry.envelope.to?.map((t: any) => t.address).join(', ') || 'Unknown'
-
-  const content = `
-    <div class="header">
-      <div class="title">
-        <a href="${prefix}" class="btn">← Back</a>
-        <span style="margin-left: 10px">Email Preview</span>
-      </div>
-      <button onclick="deleteEmail('${entry.id}')" class="btn btn-danger">Delete</button>
-    </div>
-
-    <div class="card" style="margin-bottom: 20px; padding: 20px;">
-      <div style="font-size: 18px; font-weight: bold; margin-bottom: 10px;">${entry.envelope.subject || '(No Subject)'}</div>
-      <div class="meta" style="margin-bottom: 5px;">From: ${from}</div>
-      <div class="meta" style="margin-bottom: 5px;">To: ${to}</div>
-      ${
-        entry.envelope.cc
-          ? `<div class="meta" style="margin-bottom: 5px;">CC: ${entry.envelope.cc.map((t: any) => t.address).join(', ')}</div>`
-          : ''
-      }
-      ${
-        entry.envelope.bcc
-          ? `<div class="meta" style="margin-bottom: 5px;">BCC: ${entry.envelope.bcc.map((t: any) => t.address).join(', ')}</div>`
-          : ''
-      }
-      ${entry.envelope.priority ? `<div class="meta" style="margin-bottom: 5px;">Priority: ${entry.envelope.priority}</div>` : ''}
-      <div class="meta">Date: ${entry.sentAt.toLocaleString()}</div>
-      ${
-        entry.envelope.attachments && entry.envelope.attachments.length > 0
-          ? `
-        <div style="margin-top: 15px; border-top: 1px solid var(--border); padding-top: 10px;">
-          <div style="font-size: 14px; font-weight: bold; margin-bottom: 5px; color: var(--text-muted);">Attachments (${entry.envelope.attachments.length})</div>
-          <div style="display: flex; gap: 10px; flex-wrap: wrap;">
-            ${entry.envelope.attachments
-              .map(
-                (att: any) => `
-              <div style="background: var(--bg-dark); padding: 8px 12px; border-radius: 6px; border: 1px solid var(--border); display: flex; align-items: center; gap: 8px;">
-                <span style="font-size: 20px;">📎</span>
-                <div>
-                  <div style="font-size: 14px; font-weight: 500;">${att.filename || 'untitled'}</div>
-                  <div style="font-size: 12px; color: var(--text-muted);">${att.contentType || 'application/octet-stream'}</div>
-                </div>
-              </div>
-            `
-              )
-              .join('')}
-          </div>
-        </div>
-      `
-          : ''
-      }
-    </div>
-
-    <div style="margin-bottom: 10px;">
-      <button onclick="setView('html')" id="btn-html" class="btn btn-primary">HTML</button>
-      <button onclick="setView('text')" id="btn-text" class="btn">Text</button>
-      <button onclick="setView('raw')" id="btn-raw" class="btn">Raw JSON</button>
-      <a href="${prefix}/${entry.id}/html" target="_blank" class="btn">Open HTML ↗</a>
-    </div>
-
-    <div class="card" style="height: 600px; display: flex;">
-      <iframe id="preview-frame" src="${prefix}/${entry.id}/html" style="width: 100%; height: 100%; border: none;"></iframe>
-      <pre id="raw-view" style="display: none; padding: 20px; overflow: auto; width: 100%;">${JSON.stringify(entry, null, 2)}</pre>
-      <pre id="text-view" style="display: none; padding: 20px; overflow: auto; width: 100%; white-space: pre-wrap; font-family: monospace;">${entry.text || 'No text content'}</pre>
-    </div>
-
-    <script>
-      function setView(mode) {
-        document.getElementById('preview-frame').style.display = mode === 'html' ? 'block' : 'none';
-        document.getElementById('raw-view').style.display = mode === 'raw' ? 'block' : 'none';
-        document.getElementById('text-view').style.display = mode === 'text' ? 'block' : 'none';
-        
-        document.getElementById('btn-html').className = mode === 'html' ? 'btn btn-primary' : 'btn';
-        document.getElementById('btn-text').className = mode === 'text' ? 'btn btn-primary' : 'btn';
-        document.getElementById('btn-raw').className = mode === 'raw' ? 'btn btn-primary' : 'btn';
-      }
-
-      async function deleteEmail(id) {
-        if (!confirm('Delete this email?')) return;
-        await fetch('${prefix}/' + id, { method: 'DELETE' });
-        window.location.href = '${prefix}';
-      }
-    </script>
-  `
-
-  return layout(entry.envelope.subject || 'Preview', content)
-}

package/src/dev/ui/shared.ts

@@ -1,60 +0,0 @@
-/**
- * CSS styles for the development mail UI.
- * @internal
- */
-export const styles = `
-:root {
-  --primary: #6366f1;
-  --primary-dark: #4f46e5;
-  --bg-dark: #0f172a;
-  --bg-card: #1e293b;
-  --text: #f1f5f9;
-  --text-muted: #94a3b8;
-  --border: #334155;
-  --danger: #ef4444;
-}
-body { background: var(--bg-dark); color: var(--text); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; margin: 0; padding: 20px; }
-.container { max-width: 1000px; margin: 0 auto; }
-.header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px; }
-.title { font-size: 24px; font-weight: bold; display: flex; align-items: center; gap: 10px; }
-.card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
-.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; }
-.btn:hover { background: var(--bg-card-hover); }
-.btn-primary { background: var(--primary); color: white; }
-.btn-primary:hover { background: var(--primary-dark); }
-.btn-danger { background: var(--danger); color: white; }
-.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; }
-.list-item:last-child { border-bottom: none; }
-.list-item:hover { background: #334155; }
-.meta { display: flex; justify-content: space-between; font-size: 14px; color: var(--text-muted); }
-.subject { font-weight: 600; font-size: 16px; }
-.from { color: #cbd5e1; }
-.badge { background: #475569; padding: 2px 6px; border-radius: 4px; font-size: 12px; }
-.badge-high { background: #dc2626; color: white; }
-.empty { padding: 40px; text-align: center; color: var(--text-muted); }
-`
-
-/**
- * HTML layout wrapper for dev mail UI pages.
- *
- * @param title - Page title
- * @param content - HTML content to inject
- * @returns Complete HTML document
- *
- * @internal
- */
-export const layout = (title: string, content: string) => `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="utf-8">
-  <title>${title} - Gravito Mailbox</title>
-  <style>${styles}</style>
-</head>
-<body>
-  <div class="container">
-    ${content}
-  </div>
-</body>
-</html>
-`

package/src/errors.ts

@@ -1,69 +0,0 @@
-/**
- * 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 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 class MailTransportError extends 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,
-    public readonly code: MailErrorCode,
-    public readonly cause?: Error
-  ) {
-    super(message)
-    this.name = 'MailTransportError'
-
-    // Maintain proper stack trace in V8 environments
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, MailTransportError)
-    }
-  }
-}

package/src/events.ts

@@ -1,72 +0,0 @@
-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>