@gravito/signal 3.0.0 → 3.0.3

package/src/transports/SesTransport.ts

@@ -2,12 +2,40 @@ import { SESClient, SendRawEmailCommand } from '@aws-sdk/client-ses'
 import nodemailer from 'nodemailer'
 import type { Address, Message, Transport } from '../types'
 
+/**
+ * Configuration for AWS SES email transport.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface SesConfig {
+  /** AWS region (e.g., 'us-east-1') */
   region: string
+  /** AWS access key ID (optional, uses default credentials if not provided) */
   accessKeyId?: string
+  /** AWS secret access key (optional, uses default credentials if not provided) */
   secretAccessKey?: string
 }
 
+/**
+ * AWS SES (Simple Email Service) transport.
+ *
+ * Sends emails using Amazon SES with support for attachments,
+ * HTML/text content, and all standard email features.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SesTransport({
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+ * })
+ * await transport.send(message)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class SesTransport implements Transport {
   private transporter: nodemailer.Transporter
 

package/src/transports/SmtpTransport.ts

@@ -1,20 +1,58 @@
 import nodemailer from 'nodemailer'
 import type { Address, Message, Transport } from '../types'
 
+/**
+ * Configuration for SMTP email transport.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface SmtpConfig {
+  /** SMTP server hostname */
   host: string
+  /** SMTP server port (typically 25, 465, or 587) */
   port: number
+  /** Use TLS/SSL connection (true for port 465) */
   secure?: boolean
+  /** Authentication credentials */
   auth?: {
+    /** SMTP username */
     user: string
+    /** SMTP password */
     pass: string
   }
+  /** TLS options */
   tls?: {
+    /** Reject unauthorized certificates */
     rejectUnauthorized?: boolean
+    /** Cipher suite */
     ciphers?: string
   }
 }
 
+/**
+ * SMTP email transport.
+ *
+ * Sends emails using standard SMTP protocol with support for
+ * authentication, TLS/SSL, attachments, and all email features.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SmtpTransport({
+ *   host: 'smtp.gmail.com',
+ *   port: 587,
+ *   secure: false,
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password'
+ *   }
+ * })
+ * await transport.send(message)
+ * ```
+ *
+ * @since 3.0.0
+ * @public
+ */
 export class SmtpTransport implements Transport {
   private transporter: nodemailer.Transporter
 

package/src/transports/Transport.ts

@@ -1,8 +1,16 @@
 import type { Message } from '../types'
 
+/**
+ * Interface for email transport mechanisms (SMTP, SES, etc.).
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Transport {
   /**
-   * Send the given message
+   * Send the given message using the underlying transport.
+   *
+   * @param message - The finalized message to send.
    */
   send(message: Message): Promise<void>
 }

package/src/types.ts

@@ -2,79 +2,137 @@ import type { GravitoContext } from '@gravito/core'
 import type { Transport } from './transports/Transport'
 export type { Transport }
 
+/**
+ * Representation of an email address with optional display name.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Address {
+  /** The display name of the recipient/sender, e.g., "John Doe". */
   name?: string
+  /** The actual email address string. */
   address: string
 }
 
+/**
+ * Configuration for an email attachment.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Attachment {
+  /** The filename of the attachment. */
   filename: string
+  /** The content of the attachment as a string or Buffer. */
   content: string | Buffer // Buffer for Node.js
+  /** Optional MIME type of the content. */
   contentType?: string
+  /** Optional Content-ID for referencing within HTML content (inline images). */
   cid?: string // Content-ID for inline images
+  /** Optional content encoding. */
   encoding?: string
 }
 
+/**
+ * The envelope containing metadata for an email message.
+ *
+ * Used during the construction phase of a Mailable.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Envelope {
+  /** The sender's address. */
   from?: Address | undefined
+  /** Primary recipients. */
   to?: Address[] | undefined
+  /** Carbon copy recipients. */
   cc?: Address[] | undefined
+  /** Blind carbon copy recipients. */
   bcc?: Address[] | undefined
+  /** Reply-to address. */
   replyTo?: Address | undefined
+  /** Email subject line. */
   subject?: string | undefined
+  /** Importance level of the email. */
   priority?: 'high' | 'normal' | 'low' | undefined
+  /** List of file attachments. */
   attachments?: Attachment[] | undefined
 }
 
+/**
+ * A fully finalized email message ready to be sent by a transport.
+ *
+ * Requires mandatory fields that were optional in the Envelope.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Message extends Envelope {
-  from: Address // From is required in finalized message
-  to: Address[] // To is required in finalized message
+  /** The mandatory sender's address. */
+  from: Address
+  /** At least one recipient is required. */
+  to: Address[]
+  /** Mandatory subject. */
   subject: string
-  html: string // The rendered HTML content
-  text?: string // The rendered plain text content
+  /** The rendered HTML body content. */
+  html: string
+  /** Optional rendered plain text body content. */
+  text?: string
+  /** Custom SMTP headers. */
   headers?: Record<string, string>
 }
 
+/**
+ * Global configuration options for OrbitSignal and Mailable instances.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface MailConfig {
   /**
-   * Default sender address
+   * Default sender address used if not specified in the Mailable.
    */
   from?: Address
 
   /**
-   * The transport mechanism used to send emails
+   * The transport mechanism used to send emails (e.g., SMTP, SES, Log).
    */
   transport?: Transport
 
   /**
-   * Enable development mode (intercepts emails)
+   * Enable development mode.
+   * When true, emails are intercepted by the DevMailbox instead of being sent.
    */
   devMode?: boolean | undefined
 
   /**
-   * Directory where email templates are located (for OrbitPrism)
+   * Directory where email templates are located for use with OrbitPrism.
    * Default: src/emails
    */
   viewsDir?: string | undefined
 
   /**
-   * URL prefix for Dev UI
+   * URL prefix for the Mail Dev UI.
    * Default: /__mail
    */
   devUiPrefix?: string | undefined
 
   /**
-   * Allow Dev UI in production. Default: false.
+   * Whether to allow access to the Mail Dev UI in production environments.
+   * @default false
    */
   devUiAllowInProduction?: boolean | undefined
 
   /**
-   * Gate access to Dev UI (required in production unless allowInProduction is true).
+   * Authorization gate for the Mail Dev UI.
+   * Should return true to allow access to the UI.
    */
   devUiGate?: ((ctx: GravitoContext) => boolean | Promise<boolean>) | undefined
 
   /**
-   * Translation function for i18n support
+   * Translation function for internationalization within emails.
    */
   translator?:
     | ((key: string, replace?: Record<string, unknown>, locale?: string) => string)

package/tests/mailable-extra.test.ts

@@ -1,61 +1,68 @@
-import { describe, expect, it, mock } from 'bun:test'
-import { DevMailbox } from '../src/dev/DevMailbox'
+import { describe, expect, it } from 'bun:test'
 import { Mailable } from '../src/Mailable'
-import { OrbitSignal } from '../src/OrbitSignal'
-import { MemoryTransport } from '../src/transports/MemoryTransport'
 
-class DemoMail extends Mailable {
+class TestMailable extends Mailable {
   build() {
-    return this.from('from@example.com')
-      .to('to@example.com')
-      .cc('cc@example.com')
-      .bcc('bcc@example.com')
-      .replyTo('reply@example.com')
-      .subject('Hello')
-      .emailPriority('high')
-      .html('<p>Hello World</p>')
+    return this
   }
 }
 
-describe('Mailable', () => {
-  it('builds envelopes and renders content', async () => {
-    const mail = new DemoMail()
-    const envelope = await mail.buildEnvelope({
-      from: { address: 'default@example.com' },
-      translator: (key: string) => `t:${key}`,
-    })
-
-    expect(envelope.from?.address).toBe('from@example.com')
-    expect(envelope.cc?.[0]?.address).toBe('cc@example.com')
-    expect(envelope.bcc?.[0]?.address).toBe('bcc@example.com')
-    expect(envelope.replyTo?.address).toBe('reply@example.com')
-
-    const content = await mail.renderContent()
-    expect(content.html).toContain('<p>Hello World</p>')
-    expect(content.text).toBe('Hello World')
-    expect(mail.t('hello')).toBe('t:hello')
-  })
-
-  it('queues mailables via OrbitSignal', async () => {
-    const queueMock = mock(async () => {})
-    const orbit = new OrbitSignal({
-      transport: new MemoryTransport(new DevMailbox()),
-    })
-
-    // 模擬容器中的隊列服務
-    ;(orbit as any).core = {
-      container: {
-        make: (key: string) => {
-          if (key === 'queue') {
-            return { push: queueMock }
-          }
-          return null
-        },
-      },
-    }
-
-    const mail = new DemoMail()
-    await orbit.queue(mail)
-    expect(queueMock).toHaveBeenCalled()
+describe('Mailable Extras', () => {
+  it('should handle attachments', () => {
+    const mail = new TestMailable()
+    mail.attach({ filename: 'test.txt', content: 'hello' })
+    expect((mail as any).envelope.attachments).toHaveLength(1)
+    expect((mail as any).envelope.attachments[0].filename).toBe('test.txt')
+  })
+
+  it('should set view logic', () => {
+    const mail = new TestMailable()
+    mail.view('emails/welcome', { user: 'Carl' })
+    expect((mail as any).renderer).toBeDefined()
+    expect((mail as any).renderData.user).toBe('Carl')
+  })
+
+  it('should handle queue options', () => {
+    const mail = new TestMailable()
+    mail.onQueue('low').onConnection('redis').delay(60).withPriority('high')
+
+    expect(mail.queueName).toBe('low')
+    expect(mail.connectionName).toBe('redis')
+    expect(mail.delaySeconds).toBe(60)
+    expect(mail.priority).toBe('high')
+  })
+
+  it('should handle locale', () => {
+    const mail = new TestMailable()
+    mail.locale('zh-TW')
+    expect((mail as any).currentLocale).toBe('zh-TW')
+  })
+
+  it('should support i18n helper', () => {
+    const mail = new TestMailable()
+    mail.setTranslator((key) => key.toUpperCase())
+
+    expect(mail.t('hello')).toBe('HELLO')
+  })
+
+  it('should safely fail queue() if app not available', async () => {
+    const mail = new TestMailable()
+    // We are not mocking @gravito/core, so it should hit the catch block and log warning
+    // We just ensure it doesn't throw
+    await expect(mail.queue()).resolves.toBeUndefined()
+  })
+
+  it('should support React renderer builder', async () => {
+    const mail = new TestMailable()
+    // Mock import mechanics? Hard to test dynamic import in this unit test without mocking module system.
+    // Instead we test the builder method sets the resolver.
+    mail.react('MyComponent', { prop: 1 })
+    expect((mail as any).rendererResolver).toBeDefined()
+  })
+
+  it('should support Vue renderer builder', async () => {
+    const mail = new TestMailable()
+    mail.vue('MyComponent', { prop: 1 })
+    expect((mail as any).rendererResolver).toBeDefined()
   })
 })

package/src/augmentation.ts

@@ -1,13 +0,0 @@
-export {}
-
-// Module augmentation for GravitoVariables (new abstraction)
-declare module '@gravito/core' {
-  interface GravitoVariables {
-    /** Mail service for sending emails */
-    mail?: {
-      // Use any for params to break circularity in dts generation if any
-      send: (mailable: any) => Promise<void>
-      queue: (mailable: any) => Promise<void>
-    }
-  }
-}