@gravito/signal 1.0.0-beta.1 → 1.0.1

package/src/Mailable.ts

@@ -13,6 +13,7 @@ export abstract class Mailable implements Queueable {
   protected renderer?: Renderer
   private rendererResolver?: () => Promise<Renderer>
   protected renderData: Record<string, unknown> = {}
+  protected config?: MailConfig
 
   // ===== Fluent API (Envelope Construction) =====
 
@@ -46,7 +47,7 @@ export abstract class Mailable implements Queueable {
     return this
   }
 
-  priority(level: 'high' | 'normal' | 'low'): this {
+  emailPriority(level: 'high' | 'normal' | 'low'): this {
     this.envelope.priority = level
     return this
   }
@@ -82,10 +83,17 @@ export abstract class Mailable implements Queueable {
    * Set the content using a React component.
    * Dynamically imports ReactRenderer to avoid hard dependency errors if React is not installed.
    */
-  react<P extends object>(component: ComponentType, props?: P): this {
+  react<P extends object>(
+    component: ComponentType,
+    props?: P,
+    deps?: {
+      createElement?: (...args: any[]) => any
+      renderToStaticMarkup?: (element: any) => string
+    }
+  ): this {
     this.rendererResolver = async () => {
       const { ReactRenderer } = await import('./renderers/ReactRenderer')
-      return new ReactRenderer(component, props)
+      return new ReactRenderer(component, props, deps)
     }
     return this
   }
@@ -94,10 +102,18 @@ export abstract class Mailable implements Queueable {
    * Set the content using a Vue component.
    * Dynamically imports VueRenderer to avoid hard dependency errors if Vue is not installed.
    */
-  vue<P extends object>(component: ComponentType, props?: P): this {
+  vue<P extends object>(
+    component: ComponentType,
+    props?: P,
+    deps?: {
+      createSSRApp?: (...args: any[]) => any
+      h?: (...args: any[]) => any
+      renderToString?: (app: any) => Promise<string>
+    }
+  ): this {
     this.rendererResolver = async () => {
       const { VueRenderer } = await import('./renderers/VueRenderer')
-      return new VueRenderer(component, props as any)
+      return new VueRenderer(component, props as any, deps)
     }
     return this
   }
@@ -114,6 +130,7 @@ export abstract class Mailable implements Queueable {
   queueName?: string
   connectionName?: string
   delaySeconds?: number
+  priority?: number | string
 
   onQueue(queue: string): this {
     this.queueName = queue
@@ -130,13 +147,29 @@ export abstract class Mailable implements Queueable {
     return this
   }
 
+  withPriority(priority: string | number): this {
+    this.priority = priority
+    return this
+  }
+
   /**
    * Queue the mailable for sending.
    */
   async queue(): Promise<void> {
-    // Avoid circular dependency by dynamically importing OrbitSignal
-    const { OrbitSignal } = await import('./OrbitSignal')
-    return OrbitSignal.getInstance().queue(this)
+    // We should ideally use the container to get the mail service
+    // But since Mailable might be used outside a core context, we'll try a safe approach.
+    try {
+      // biome-ignore lint/suspicious/noTsIgnore: Global access to app() helper from core
+      // @ts-ignore
+      const { app } = await import('@gravito/core')
+      const mail = app().container.make<any>('mail')
+      if (mail) {
+        return mail.queue(this)
+      }
+    } catch (_e) {
+      // Fallback if core is not available
+      console.warn('[Mailable] Could not auto-resolve mail service for queuing.')
+    }
   }
 
   // ===== I18n Support =====
@@ -178,6 +211,7 @@ export abstract class Mailable implements Queueable {
    */
   async buildEnvelope(configPromise: MailConfig | Promise<MailConfig>): Promise<Envelope> {
     const config = await Promise.resolve(configPromise)
+    this.config = config
 
     // Inject translator from config if available
     if (config.translator) {
@@ -188,8 +222,8 @@ export abstract class Mailable implements Queueable {
 
     // Ensure Renderer is initialized if using TemplateRenderer with config path
     if (this.renderer instanceof TemplateRenderer && config.viewsDir) {
-      // Here we could re-initialize TemplateRenderer if we had a setter for viewsDir
-      // For now, it defaults to process.cwd()/src/emails which is standard
+      // Re-initialize or update TemplateRenderer with the correct directory
+      this.renderer = new TemplateRenderer((this.renderer as any).template, config.viewsDir)
     }
 
     const envelope: Envelope = {

package/src/OrbitSignal.ts

@@ -1,4 +1,4 @@
-import type { GravitoOrbit, PlanetCore } from 'gravito-core'
+import type { GravitoOrbit, PlanetCore } from '@gravito/core'
 import { DevMailbox } from './dev/DevMailbox'
 import { DevServer } from './dev/DevServer'
 import type { Mailable } from './Mailable'
@@ -7,41 +7,12 @@ import { MemoryTransport } from './transports/MemoryTransport'
 import type { MailConfig, Message } from './types'
 
 export class OrbitSignal implements GravitoOrbit {
-  private static instance?: OrbitSignal
   private config: MailConfig
   private devMailbox?: DevMailbox
+  private core?: PlanetCore
 
   constructor(config: MailConfig = {}) {
     this.config = config
-    OrbitSignal.instance = this
-  }
-
-  /**
-   * Get the singleton instance of OrbitSignal
-   *
-   * @returns The singleton instance of OrbitSignal.
-   * @throws {Error} If OrbitSignal has not been initialized.
-   */
-  static getInstance(): OrbitSignal {
-    if (!OrbitSignal.instance) {
-      throw new Error('OrbitSignal has not been initialized. Call OrbitSignal.configure() first.')
-    }
-    return OrbitSignal.instance
-  }
-
-  /**
-   * Configure the OrbitSignal instance
-   *
-   * @param config - The mail configuration object.
-   * @returns A new instance of OrbitSignal.
-   */
-  static configure(config: MailConfig): OrbitSignal {
-    // Basic validation
-    if (!config.transport && !config.devMode) {
-      console.warn('[OrbitSignal] No transport provided, falling back to LogTransport')
-      config.transport = new LogTransport()
-    }
-    return new OrbitSignal(config)
   }
 
   /**
@@ -50,29 +21,33 @@ export class OrbitSignal implements GravitoOrbit {
    * @param core - The PlanetCore instance.
    */
   install(core: PlanetCore): void {
-    core.logger.info('[OrbitSignal] Initializing Mail Service (Exposed as: mail)')
+    this.core = core
+    core.logger.info('[OrbitSignal] Initializing Mail Service')
 
-    // Ensure transport exists (fallback to Log if not set)
+    // 1. Ensure transport exists (fallback to Log if not set)
     if (!this.config.transport && !this.config.devMode) {
       this.config.transport = new LogTransport()
     }
 
-    // In Dev Mode, override transport and setup Dev Server
+    // 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')
+      const devServer = new DevServer(this.devMailbox, this.config.devUiPrefix || '/__mail', {
+        allowInProduction: this.config.devUiAllowInProduction,
+        gate: this.config.devUiGate,
+      })
       devServer.register(core)
     }
 
-    // Inject mail service into context
+    // 3. Register in container
+    core.container.singleton('mail', () => this)
+
+    // 4. Inject mail service into context for easy access in routes
     core.adapter.use('*', async (c, next) => {
-      c.set('mail', {
-        send: (mailable: Mailable) => this.send(mailable),
-        queue: (mailable: Mailable) => this.queue(mailable),
-      })
+      c.set('mail', this)
       await next()
       return undefined
     })
@@ -116,38 +91,27 @@ export class OrbitSignal implements GravitoOrbit {
 
     // 4. Send via transport
     if (!this.config.transport) {
-      throw new Error(
-        '[OrbitSignal] No transport configured. Did you call configure() or register the orbit?'
-      )
+      throw new Error('[OrbitSignal] No transport configured. Did you call register the orbit?')
     }
     await this.config.transport.send(message)
   }
 
   /**
    * Queue a mailable instance
-   *
-   * Push a mailable into the queue for execution.
-   * Requires OrbitStream to be installed and available in the context.
-   *
-   * @param mailable - The mailable object to queue.
-   * @returns A promise that resolves when the job is pushed to the queue or sent immediately if no queue service is found.
    */
   async queue(mailable: Mailable): Promise<void> {
-    // Try to get queue service from context.
-    // If not available, send immediately (backward compatible).
-    const queue = (
-      this as unknown as { queueService?: { push: (job: unknown) => Promise<unknown> } }
-    ).queueService
-
-    if (queue) {
-      // Push via Queue system.
-      await queue.push(mailable)
-    } else {
-      // Fallback: send immediately (backward compatible).
-      console.warn(
-        '[OrbitSignal] Queue service not available, sending immediately. Install OrbitStream to enable queuing.'
-      )
-      await this.send(mailable)
+    try {
+      // 嘗試從容器獲取隊列服務 (OrbitStream)
+      const queue = this.core?.container.make<any>('queue')
+      if (queue) {
+        await queue.push(mailable)
+        return
+      }
+    } catch (_e) {
+      // 找不到隊列服務時，會拋出錯誤，我們捕捉並降級
     }
+
+    // Fallback: 直接發送
+    await this.send(mailable)
   }
 }

package/src/augmentation.ts

@@ -1,7 +1,7 @@
 export {}
 
 // Module augmentation for GravitoVariables (new abstraction)
-declare module 'gravito-core' {
+declare module '@gravito/core' {
   interface GravitoVariables {
     /** Mail service for sending emails */
     mail?: {

package/src/dev/DevServer.ts

@@ -1,104 +1,166 @@
-import type { PlanetCore } from 'gravito-core'
+import type { GravitoContext, PlanetCore } from '@gravito/core'
 import type { DevMailbox } from './DevMailbox'
 import { getMailboxHtml } from './ui/mailbox'
 import { getPreviewHtml } from './ui/preview'
 
+export type DevServerOptions = {
+  allowInProduction?: boolean
+  gate?: (c: GravitoContext) => boolean | Promise<boolean>
+}
+
 export class DevServer {
   constructor(
     private mailbox: DevMailbox,
-    private base = '/__mail'
+    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, (ctx) => {
-      const entries = this.mailbox.list()
-      return ctx.html(getMailboxHtml(entries, prefix))
-    })
+    router.get(
+      prefix,
+      wrap((ctx) => {
+        const entries = 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`, (ctx) => {
-      const id = ctx.req.param('id')
-      if (!id) {
-        return ctx.text('Bad Request', 400)
-      }
-
-      const entry = this.mailbox.get(id)
-      if (!entry) {
-        return ctx.text('Email not found', 404)
-      }
-      return ctx.html(getPreviewHtml(entry, prefix))
-    })
+    router.get(
+      `${prefix}/:id`,
+      wrap((ctx) => {
+        const id = ctx.req.param('id')
+        if (!id) {
+          return ctx.text('Bad Request', 400)
+        }
+
+        const entry = 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`, (ctx) => {
-      const id = ctx.req.param('id')
-      if (!id) {
-        return ctx.text('Bad Request', 400)
-      }
-
-      const entry = this.mailbox.get(id)
-      if (!entry) {
-        return ctx.text('Not found', 404)
-      }
-      return ctx.html(entry.html)
-    })
+    router.get(
+      `${prefix}/:id/html`,
+      wrap((ctx) => {
+        const id = ctx.req.param('id')
+        if (!id) {
+          return ctx.text('Bad Request', 400)
+        }
+
+        const entry = 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`, (ctx) => {
-      const id = ctx.req.param('id')
-      if (!id) {
-        return ctx.text('Bad Request', 400)
-      }
-
-      const entry = 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)
-    })
+    router.get(
+      `${prefix}/:id/text`,
+      wrap((ctx) => {
+        const id = ctx.req.param('id')
+        if (!id) {
+          return ctx.text('Bad Request', 400)
+        }
+
+        const entry = 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`, (ctx) => {
-      const id = ctx.req.param('id')
-      if (!id) {
-        return ctx.json({ error: 'Bad Request' }, 400)
-      }
-
-      const entry = this.mailbox.get(id)
-      if (!entry) {
-        return ctx.json({ error: 'Not found' }, 404)
-      }
-      return ctx.json(entry)
-    })
+    router.get(
+      `${prefix}/:id/raw`,
+      wrap((ctx) => {
+        const id = ctx.req.param('id')
+        if (!id) {
+          return ctx.json({ error: 'Bad Request' }, 400)
+        }
+
+        const entry = 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`, (ctx) => {
-      return ctx.text('Method not allowed', 405)
-    })
-
-    router.delete(`${prefix}/:id`, (ctx) => {
-      const id = ctx.req.param('id')
-      if (!id) {
-        return ctx.json({ success: false, error: 'Bad Request' }, 400)
-      }
-
-      const success = this.mailbox.delete(id)
-      return ctx.json({ success })
-    })
+    router.get(
+      `${prefix}/:id/delete`,
+      wrap((ctx) => {
+        return ctx.text('Method not allowed', 405)
+      })
+    )
+
+    router.delete(
+      `${prefix}/:id`,
+      wrap((ctx) => {
+        const id = ctx.req.param('id')
+        if (!id) {
+          return ctx.json({ success: false, error: 'Bad Request' }, 400)
+        }
+
+        const success = this.mailbox.delete(id)
+        return ctx.json({ success })
+      })
+    )
 
     // 7. API: Clear All
-    router.delete(prefix, (ctx) => {
-      this.mailbox.clear()
-      return ctx.json({ success: true })
-    })
+    router.delete(
+      prefix,
+      wrap((ctx) => {
+        this.mailbox.clear()
+        return ctx.json({ success: true })
+      })
+    )
 
     core.logger.info(`[OrbitSignal] Dev Mailbox available at ${prefix}`)
   }

package/src/dev/ui/preview.ts

@@ -20,7 +20,42 @@ export function getPreviewHtml(entry: MailboxEntry, prefix: string): string {
       <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) => t.address).join(', ')}</div>`
+          : ''
+      }
+      ${
+        entry.envelope.bcc
+          ? `<div class="meta" style="margin-bottom: 5px;">BCC: ${entry.envelope.bcc.map((t) => 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) => `
+              <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;">

package/src/dev/ui/shared.ts

@@ -34,6 +34,7 @@ export const layout = (title: string, content: string) => `
 <!DOCTYPE html>
 <html>
 <head>
+  <meta charset="utf-8">
   <title>${title} - Gravito Mailbox</title>
   <style>${styles}</style>
 </head>

package/src/renderers/ReactRenderer.ts

@@ -3,13 +3,18 @@ import type { Renderer, RenderResult } from './Renderer'
 export class ReactRenderer<P extends object = object> implements Renderer {
   constructor(
     private component: any, // Use any to avoid hard React dependency in types
-    private props?: P
+    private props?: P,
+    private deps: {
+      createElement?: (...args: any[]) => any
+      renderToStaticMarkup?: (element: any) => string
+    } = {}
   ) {}
 
   async render(data: Record<string, unknown>): Promise<RenderResult> {
     // Dynamic imports to avoid hard dependencies on react/react-dom
-    const { createElement } = await import('react')
-    const { renderToStaticMarkup } = await import('react-dom/server')
+    const createElement = this.deps.createElement ?? (await import('react')).createElement
+    const renderToStaticMarkup =
+      this.deps.renderToStaticMarkup ?? (await import('react-dom/server')).renderToStaticMarkup
 
     const mergedProps = { ...this.props, ...data } as P
 

package/src/renderers/VueRenderer.ts

@@ -3,13 +3,20 @@ import type { Renderer, RenderResult } from './Renderer'
 export class VueRenderer<P extends object = object> implements Renderer {
   constructor(
     private component: any, // Use any to avoid hard Vue dependency in types
-    private props?: P
+    private props?: P,
+    private deps: {
+      createSSRApp?: (...args: any[]) => any
+      h?: (...args: any[]) => any
+      renderToString?: (app: any) => Promise<string>
+    } = {}
   ) {}
 
   async render(data: Record<string, unknown>): Promise<RenderResult> {
     // Dynamic imports to avoid hard dependencies on vue/@vue/server-renderer
-    const { createSSRApp, h } = await import('vue')
-    const { renderToString } = await import('@vue/server-renderer')
+    const createSSRApp = this.deps.createSSRApp ?? (await import('vue')).createSSRApp
+    const h = this.deps.h ?? (await import('vue')).h
+    const renderToString =
+      this.deps.renderToString ?? (await import('@vue/server-renderer')).renderToString
 
     const mergedProps = { ...this.props, ...data }
 

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { GravitoContext } from '@gravito/core'
 import type { Transport } from './transports/Transport'
 export type { Transport }
 
@@ -62,6 +63,16 @@ export interface MailConfig {
    */
   devUiPrefix?: string | undefined
 
+  /**
+   * Allow Dev UI in production. Default: false.
+   */
+  devUiAllowInProduction?: boolean | undefined
+
+  /**
+   * Gate access to Dev UI (required in production unless allowInProduction is true).
+   */
+  devUiGate?: ((ctx: GravitoContext) => boolean | Promise<boolean>) | undefined
+
   /**
    * Translation function for i18n support
    */