@gravito/signal 3.0.0 → 3.0.3

package/src/Mailable.ts

@@ -8,6 +8,27 @@ import type { Address, Attachment, Envelope, MailConfig } from './types'
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type ComponentType = any
 
+/**
+ * Base class for all mailable messages.
+ *
+ * Provides a fluent API for building email envelopes and rendering content
+ * using various engines (raw HTML, Prism templates, React, or Vue).
+ *
+ * @example
+ * ```typescript
+ * class WelcomeMail extends Mailable {
+ *   build() {
+ *     return this.subject('Welcome!')
+ *                .view('emails.welcome', { name: 'John' });
+ *   }
+ * }
+ *
+ * await new WelcomeMail().to('john@example.com').send();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 export abstract class Mailable implements Queueable {
   protected envelope: Partial<Envelope> = {}
   protected renderer?: Renderer
@@ -17,41 +38,81 @@ export abstract class Mailable implements Queueable {
 
   // ===== Fluent API (Envelope Construction) =====
 
+  /**
+   * Set the sender address for the email.
+   *
+   * @param address - Email address or Address object.
+   */
   from(address: string | Address): this {
     this.envelope.from = typeof address === 'string' ? { address } : address
     return this
   }
 
+  /**
+   * Set the primary recipient(s) for the email.
+   *
+   * @param address - Single address, address object, or array of either.
+   */
   to(address: string | Address | (string | Address)[]): this {
     this.envelope.to = this.normalizeAddressArray(address)
     return this
   }
 
+  /**
+   * Set the carbon copy (CC) recipient(s).
+   *
+   * @param address - Single address, address object, or array of either.
+   */
   cc(address: string | Address | (string | Address)[]): this {
     this.envelope.cc = this.normalizeAddressArray(address)
     return this
   }
 
+  /**
+   * Set the blind carbon copy (BCC) recipient(s).
+   *
+   * @param address - Single address, address object, or array of either.
+   */
   bcc(address: string | Address | (string | Address)[]): this {
     this.envelope.bcc = this.normalizeAddressArray(address)
     return this
   }
 
+  /**
+   * Set the reply-to address.
+   *
+   * @param address - Email address or Address object.
+   */
   replyTo(address: string | Address): this {
     this.envelope.replyTo = typeof address === 'string' ? { address } : address
     return this
   }
 
+  /**
+   * Set the subject line for the email.
+   *
+   * @param subject - The email subject.
+   */
   subject(subject: string): this {
     this.envelope.subject = subject
     return this
   }
 
+  /**
+   * Set the email priority.
+   *
+   * @param level - Priority level ('high', 'normal', or 'low').
+   */
   emailPriority(level: 'high' | 'normal' | 'low'): this {
     this.envelope.priority = level
     return this
   }
 
+  /**
+   * Attach a file to the email.
+   *
+   * @param attachment - Attachment configuration object.
+   */
   attach(attachment: Attachment): this {
     this.envelope.attachments = this.envelope.attachments || []
     this.envelope.attachments.push(attachment)
@@ -62,6 +123,8 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Set the content using raw HTML string.
+   *
+   * @param content - The HTML content string.
    */
   html(content: string): this {
     this.renderer = new HtmlRenderer(content)
@@ -70,8 +133,9 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Set the content using an OrbitPrism template.
-   * @param template Template name (relative to viewsDir/emails)
-   * @param data Data to pass to the template
+   *
+   * @param template - Template name (relative to viewsDir/emails).
+   * @param data - Optional data to pass to the template.
    */
   view(template: string, data?: Record<string, unknown>): this {
     this.renderer = new TemplateRenderer(template, undefined) // Dir will be injected later if possible, or use default
@@ -82,6 +146,10 @@ 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.
+   *
+   * @param component - The React component to render.
+   * @param props - Optional props for the component.
+   * @param deps - Optional dependencies (React, ReactDOMServer) if not globally available.
    */
   react<P extends object>(
     component: ComponentType,
@@ -101,6 +169,10 @@ 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.
+   *
+   * @param component - The Vue component to render.
+   * @param props - Optional props for the component.
+   * @param deps - Optional dependencies (Vue, VueServerRenderer) if not globally available.
    */
   vue<P extends object>(
     component: ComponentType,
@@ -122,31 +194,48 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Setup the mailable. This is where you call from(), to(), view(), etc.
+   * This method must be implemented by concrete classes.
    */
   abstract build(): this
 
   // ===== Queueable Implementation =====
 
+  /** The name of the queue to push this mailable to. */
   queueName?: string
+  /** The connection name for the queue. */
   connectionName?: string
+  /** Delay in seconds before the message is sent. */
   delaySeconds?: number
+  /** Priority of the message in the queue. */
   priority?: number | string
 
+  /**
+   * Set the queue name for this mailable.
+   */
   onQueue(queue: string): this {
     this.queueName = queue
     return this
   }
 
+  /**
+   * Set the connection name for this mailable.
+   */
   onConnection(connection: string): this {
     this.connectionName = connection
     return this
   }
 
+  /**
+   * Set a delay for the queued mailable.
+   */
   delay(seconds: number): this {
     this.delaySeconds = seconds
     return this
   }
 
+  /**
+   * Set the priority for the queued mailable.
+   */
   withPriority(priority: string | number): this {
     this.priority = priority
     return this
@@ -154,6 +243,7 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Queue the mailable for sending.
+   * Attempts to resolve the mail service from the PlanetCore container.
    */
   async queue(): Promise<void> {
     // We should ideally use the container to get the mail service
@@ -179,6 +269,8 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Set the locale for the message.
+   *
+   * @param locale - Valid locale string (e.g., 'en', 'zh-TW').
    */
   locale(locale: string): this {
     this.currentLocale = locale
@@ -187,6 +279,7 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Internal: Set the translator function (called by OrbitSignal)
+   * @internal
    */
   setTranslator(
     translator: (key: string, replace?: Record<string, unknown>, locale?: string) => string
@@ -196,6 +289,10 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Translate a string using the configured translator.
+   *
+   * @param key - Translation key.
+   * @param replace - Interpolation variables.
+   * @returns Translated string or the key if translator is missing.
    */
   t(key: string, replace?: Record<string, unknown>): string {
     if (this.translator) {
@@ -208,6 +305,7 @@ export abstract class Mailable implements Queueable {
 
   /**
    * Compile the envelope based on config defaults and mailable settings.
+   * Called by OrbitSignal before rendering/sending.
    */
   async buildEnvelope(configPromise: MailConfig | Promise<MailConfig>): Promise<Envelope> {
     const config = await Promise.resolve(configPromise)
@@ -250,7 +348,8 @@ export abstract class Mailable implements Queueable {
   }
 
   /**
-   * execute the renderer
+   * Execute the renderer and produce HTML/Text content.
+   * @returns Object containing rendered html and optional text content.
    */
   async renderContent(): Promise<{ html: string; text?: string }> {
     // Resolve lazy renderer if needed

package/src/OrbitSignal.ts

@@ -1,4 +1,4 @@
-import type { GravitoOrbit, PlanetCore } from '@gravito/core'
+import type { GravitoContext, GravitoNext, GravitoOrbit, PlanetCore } from '@gravito/core'
 import { DevMailbox } from './dev/DevMailbox'
 import { DevServer } from './dev/DevServer'
 import type { Mailable } from './Mailable'
@@ -6,6 +6,37 @@ import { LogTransport } from './transports/LogTransport'
 import { MemoryTransport } from './transports/MemoryTransport'
 import type { MailConfig, Message } from './types'
 
+/**
+ * OrbitSignal - Mail service orbit for Gravito framework.
+ *
+ * Provides email sending capabilities with support for multiple transports,
+ * development mode with email preview UI, and queue integration.
+ *
+ * @example
+ * ```typescript
+ * import { OrbitSignal } from '@gravito/signal'
+ * import { SmtpTransport } from '@gravito/signal'
+ *
+ * const app = new Application({
+ *   orbits: [
+ *     new OrbitSignal({
+ *       transport: new SmtpTransport({
+ *         host: 'smtp.example.com',
+ *         port: 587,
+ *         auth: { user: 'user', pass: 'pass' }
+ *       }),
+ *       from: { name: 'App', email: 'noreply@example.com' }
+ *     })
+ *   ]
+ * })
+ *
+ * // In route handler
+ * await c.get('mail').send(new WelcomeEmail(user))
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class OrbitSignal implements GravitoOrbit {
   private config: MailConfig
   private devMailbox?: DevMailbox
@@ -43,10 +74,10 @@ export class OrbitSignal implements GravitoOrbit {
     }
 
     // 3. Register in container
-    core.container.singleton('mail', () => this)
+    core.container.instance('mail', this)
 
     // 4. Inject mail service into context for easy access in routes
-    core.adapter.use('*', async (c: any, next) => {
+    core.adapter.use('*', async (c: GravitoContext, next: GravitoNext) => {
       c.set('mail', this)
       return await next()
     })
@@ -54,10 +85,6 @@ export class OrbitSignal implements GravitoOrbit {
 
   /**
    * Send a mailable instance
-   *
-   * @param mailable - The mailable object to send.
-   * @returns A promise that resolves when the email is sent.
-   * @throws {Error} If the message is missing "from" or "to" addresses, or if no transport is configured.
    */
   async send(mailable: Mailable): Promise<void> {
     // 1. Build envelope and get configuration
@@ -114,3 +141,11 @@ export class OrbitSignal implements GravitoOrbit {
     await this.send(mailable)
   }
 }
+
+// Module augmentation for GravitoVariables
+declare module '@gravito/core' {
+  interface GravitoVariables {
+    /** Mail service for sending emails */
+    mail?: OrbitSignal
+  }
+}

package/src/dev/DevMailbox.ts

@@ -1,14 +1,40 @@
 import { randomUUID } from 'node:crypto'
 import type { Envelope, Message } from '../types'
 
+/**
+ * Represents a captured email in the development mailbox.
+ *
+ * @public
+ */
 export interface MailboxEntry {
+  /** Unique identifier for the email */
   id: string
+  /** Email envelope information (from, to, subject, etc.) */
   envelope: Envelope
+  /** HTML content of the email */
   html: string
+  /** Plain text content of the email (optional) */
   text?: string
+  /** Timestamp when the email was captured */
   sentAt: Date
 }
 
+/**
+ * In-memory mailbox for capturing emails during development.
+ *
+ * Stores up to 50 recent emails and provides methods to list,
+ * retrieve, and delete captured messages.
+ *
+ * @example
+ * ```typescript
+ * const mailbox = new DevMailbox()
+ * mailbox.add(message)
+ * const emails = mailbox.list()
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class DevMailbox {
   private entries: MailboxEntry[] = []
   private maxEntries = 50

package/src/dev/DevServer.ts

@@ -3,11 +3,36 @@ 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,

package/src/dev/ui/mailbox.ts

@@ -21,6 +21,15 @@ function timeAgo(date: Date): string {
   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

package/src/dev/ui/preview.ts

@@ -1,6 +1,15 @@
 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}>`

package/src/dev/ui/shared.ts

@@ -1,3 +1,7 @@
+/**
+ * CSS styles for the development mail UI.
+ * @internal
+ */
 export const styles = `
 :root {
   --primary: #6366f1;
@@ -30,6 +34,15 @@ body { background: var(--bg-dark); color: var(--text); font-family: -apple-syste
 .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>

package/src/index.ts

@@ -1,4 +1,4 @@
-import './augmentation'
+// import './augmentation'
 
 export type { Queueable } from '@gravito/stream'
 export { DevMailbox, type MailboxEntry } from './dev/DevMailbox'

package/src/renderers/HtmlRenderer.ts

@@ -1,5 +1,22 @@
 import type { Renderer, RenderResult } from './Renderer'
 
+/**
+ * Renderer for plain HTML content.
+ *
+ * Renders static HTML strings and automatically generates
+ * a plain text version by stripping HTML tags.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new HtmlRenderer('<h1>Hello</h1><p>World</p>')
+ * const { html, text } = await renderer.render()
+ * // html: '<h1>Hello</h1><p>World</p>'
+ * // text: 'Hello World'
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class HtmlRenderer implements Renderer {
   constructor(private content: string) {}
 
@@ -12,8 +29,8 @@ export class HtmlRenderer implements Renderer {
 
   private stripHtml(html: string): string {
     return html
-      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '') // Remove styles
-      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '') // Remove scripts
+      .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '') // Remove styles
+      .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '') // Remove scripts
       .replace(/<[^>]+>/g, '') // Remove tags
       .replace(/&nbsp;/g, ' ') // Replace non-breaking space
       .replace(/\s+/g, ' ') // Collapse whitespace

package/src/renderers/ReactRenderer.ts

@@ -1,5 +1,25 @@
 import type { Renderer, RenderResult } from './Renderer'
 
+/**
+ * Renderer for React component-based emails.
+ *
+ * Renders React components to static HTML for email delivery.
+ * Supports server-side rendering with optional dependency injection
+ * for testing.
+ *
+ * @example
+ * ```typescript
+ * import { WelcomeEmail } from './emails/WelcomeEmail'
+ *
+ * const renderer = new ReactRenderer(WelcomeEmail, { name: 'John' })
+ * const { html, text } = await renderer.render({ date: new Date() })
+ * ```
+ *
+ * @typeParam P - Props type for the React component
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class ReactRenderer<P extends object = object> implements Renderer {
   constructor(
     private component: any, // Use any to avoid hard React dependency in types
@@ -31,8 +51,8 @@ export class ReactRenderer<P extends object = object> implements Renderer {
 
   private stripHtml(html: string): string {
     return html
-      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
-      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+      .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '')
+      .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '')
       .replace(/<[^>]+>/g, '')
       .replace(/&nbsp;/g, ' ')
       .replace(/\s+/g, ' ')

package/src/renderers/Renderer.ts

@@ -1,11 +1,27 @@
+/**
+ * Result of a content rendering operation.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface RenderResult {
+  /** Rendered HTML string. */
   html: string
+  /** Optional rendered plain text string. */
   text?: string
 }
 
+/**
+ * Interface for email content renderers (HTML, Template, React, Vue).
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Renderer {
   /**
-   * Render the content into HTML and optionally plain text
+   * Render the content into HTML and optionally plain text.
+   *
+   * @param data - The data context for rendering.
    */
   render(data: Record<string, unknown>): Promise<RenderResult>
 }

package/src/renderers/TemplateRenderer.ts

@@ -1,5 +1,20 @@
 import type { Renderer, RenderResult } from './Renderer'
 
+/**
+ * Renderer for template-based emails using Gravito Prism.
+ *
+ * Renders email templates from the filesystem using the Prism
+ * template engine with support for data binding and layouts.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new TemplateRenderer('welcome', './src/emails')
+ * const { html, text } = await renderer.render({ name: 'John' })
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class TemplateRenderer implements Renderer {
   private template: string
   private viewsDir: string

package/src/renderers/VueRenderer.ts

@@ -1,5 +1,25 @@
 import type { Renderer, RenderResult } from './Renderer'
 
+/**
+ * Renderer for Vue component-based emails.
+ *
+ * Renders Vue 3 components to static HTML for email delivery
+ * using server-side rendering. Supports optional dependency
+ * injection for testing.
+ *
+ * @example
+ * ```typescript
+ * import { WelcomeEmail } from './emails/WelcomeEmail.vue'
+ *
+ * const renderer = new VueRenderer(WelcomeEmail, { name: 'John' })
+ * const { html, text } = await renderer.render({ date: new Date() })
+ * ```
+ *
+ * @typeParam P - Props type for the Vue component
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class VueRenderer<P extends object = object> implements Renderer {
   constructor(
     private component: any, // Use any to avoid hard Vue dependency in types
@@ -36,8 +56,8 @@ export class VueRenderer<P extends object = object> implements Renderer {
 
   private stripHtml(html: string): string {
     return html
-      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
-      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+      .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '')
+      .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '')
       .replace(/<[^>]+>/g, '')
       .replace(/&nbsp;/g, ' ')
       .replace(/\s+/g, ' ')

package/src/transports/LogTransport.ts

@@ -1,5 +1,21 @@
 import type { Message, Transport } from '../types'
 
+/**
+ * Log transport for development and testing.
+ *
+ * Logs email details to the console instead of sending them.
+ * Useful for debugging and local development.
+ *
+ * @example
+ * ```typescript
+ * const transport = new LogTransport()
+ * await transport.send(message)
+ * // Outputs email details to console
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class LogTransport implements Transport {
   async send(message: Message): Promise<void> {
     console.log('\n📧 [OrbitSignal] Email Sent (Simulated):')

package/src/transports/MemoryTransport.ts

@@ -1,6 +1,22 @@
 import type { DevMailbox } from '../dev/DevMailbox'
 import type { Message, Transport } from '../types'
 
+/**
+ * Memory transport for development mode.
+ *
+ * Captures emails to an in-memory mailbox instead of sending them.
+ * Used automatically when `devMode` is enabled in OrbitSignal.
+ *
+ * @example
+ * ```typescript
+ * const mailbox = new DevMailbox()
+ * const transport = new MemoryTransport(mailbox)
+ * await transport.send(message)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class MemoryTransport implements Transport {
   constructor(private mailbox: DevMailbox) {}