@gravito/signal 3.1.0 → 4.0.0

package/src/types.ts

@@ -1,309 +0,0 @@
-import type { GravitoContext } from '@gravito/core'
-import type { Transport } from './transports/Transport'
-
-/**
- * Interface for Webhook Drivers.
- */
-export interface WebhookDriver {
-  handle(c: GravitoContext): Promise<{ event: string; payload: any }[] | null>
-}
-
-/**
- * Transport interface for sending email messages.
- *
- * Defines the contract for different delivery mechanisms (SMTP, SES, etc.).
- */
-export type { Transport }
-
-/**
- * Representation of an email address with optional display name.
- *
- * Defines the structure for email addresses used throughout the mail system.
- * Supports both simple string addresses and formatted addresses with display names.
- *
- * @example
- * ```typescript
- * // Simple address
- * const addr1: Address = { address: 'user@example.com' }
- *
- * // Address with display name
- * const addr2: Address = {
- *   name: 'John Doe',
- *   address: 'john@example.com'
- * }
- * ```
- *
- * @see {@link Envelope} For the email envelope structure
- * @see {@link Message} For the complete message structure
- *
- * @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.
- *
- * Defines file attachments for email messages. Supports both regular attachments
- * and inline attachments (e.g., embedded images referenced via Content-ID).
- *
- * @example
- * ```typescript
- * // Regular file attachment
- * const attachment: Attachment = {
- *   filename: 'document.pdf',
- *   content: Buffer.from('...'),
- *   contentType: 'application/pdf'
- * }
- *
- * // Inline image attachment
- * const inlineImage: Attachment = {
- *   filename: 'logo.png',
- *   content: Buffer.from('...'),
- *   contentType: 'image/png',
- *   cid: 'logo@example.com' // Reference in HTML: <img src="cid:logo@example.com">
- * }
- * ```
- *
- * @see {@link Envelope} For adding attachments to emails
- *
- * @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. All fields are optional
- * at this stage and will be validated when converting to a Message.
- *
- * @example
- * ```typescript
- * const envelope: Envelope = {
- *   from: { name: 'App', address: 'noreply@app.com' },
- *   to: [{ address: 'user@example.com' }],
- *   subject: 'Welcome!',
- *   priority: 'high',
- *   replyTo: { address: 'support@app.com' }
- * }
- * ```
- *
- * @see {@link Mailable} For building envelopes fluently
- * @see {@link Message} For the validated, finalized message structure
- *
- * @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.
- * This structure is passed to Transport implementations for actual delivery.
- *
- * @example
- * ```typescript
- * const message: Message = {
- *   from: { name: 'App', address: 'noreply@app.com' },
- *   to: [{ address: 'user@example.com' }],
- *   subject: 'Welcome to our service',
- *   html: '<h1>Welcome!</h1><p>Thanks for joining.</p>',
- *   text: 'Welcome! Thanks for joining.',
- *   priority: 'normal',
- *   headers: { 'X-Custom-Header': 'value' }
- * }
- * ```
- *
- * @see {@link Envelope} For the construction phase structure
- * @see {@link Transport} For implementations that send messages
- *
- * @public
- * @since 3.0.0
- */
-export interface Message extends Envelope {
-  /** The mandatory sender's address. */
-  from: Address
-  /** At least one recipient is required. */
-  to: Address[]
-  /** Mandatory subject. */
-  subject: string
-  /** 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.
- *
- * Configures the mail service behavior, transport mechanism, development tools,
- * and internationalization support.
- *
- * @example
- * ```typescript
- * import { OrbitSignal, SmtpTransport } from '@gravito/signal'
- *
- * const config: MailConfig = {
- *   from: { name: 'My App', address: 'noreply@myapp.com' },
- *   transport: new SmtpTransport({
- *     host: 'smtp.mailtrap.io',
- *     port: 2525,
- *     auth: { user: 'user', pass: 'pass' }
- *   }),
- *   devMode: process.env.NODE_ENV === 'development',
- *   viewsDir: './src/emails',
- *   devUiPrefix: '/__mail',
- *   translator: (key, replace, locale) => i18n.t(key, { ...replace, locale })
- * }
- *
- * const mail = new OrbitSignal(config)
- * ```
- *
- * @see {@link OrbitSignal} For the mail service implementation
- * @see {@link Transport} For available transport options
- *
- * @public
- * @since 3.0.0
- */
-export interface MailConfig {
-  /**
-   * Default sender address used if not specified in the Mailable.
-   *
-   * @example
-   * ```typescript
-   * from: { name: 'My App', address: 'noreply@myapp.com' }
-   * ```
-   */
-  from?: Address
-
-  /**
-   * The transport mechanism used to send emails (e.g., SMTP, SES, Log).
-   *
-   * @example
-   * ```typescript
-   * import { SmtpTransport } from '@gravito/signal'
-   * transport: new SmtpTransport({ host: 'smtp.example.com', port: 587 })
-   * ```
-   */
-  transport?: Transport
-
-  /**
-   * Enable development mode.
-   * When true, emails are intercepted by the DevMailbox instead of being sent.
-   *
-   * @default false
-   * @example
-   * ```typescript
-   * devMode: process.env.NODE_ENV === 'development'
-   * ```
-   */
-  devMode?: boolean | undefined
-
-  /**
-   * Directory where email templates are located for use with OrbitPrism.
-   *
-   * @default "src/emails"
-   * @example
-   * ```typescript
-   * viewsDir: './resources/views/emails'
-   * ```
-   */
-  viewsDir?: string | undefined
-
-  /**
-   * URL prefix for the Mail Dev UI.
-   *
-   * @default "/__mail"
-   * @example
-   * ```typescript
-   * devUiPrefix: '/dev/mailbox'
-   * ```
-   */
-  devUiPrefix?: string | undefined
-
-  /**
-   * Whether to allow access to the Mail Dev UI in production environments.
-   *
-   * @default false
-   * @example
-   * ```typescript
-   * devUiAllowInProduction: process.env.ALLOW_MAIL_UI === 'true'
-   * ```
-   */
-  devUiAllowInProduction?: boolean | undefined
-
-  /**
-   * Authorization gate for the Mail Dev UI.
-   * Should return true to allow access to the UI.
-   *
-   * @example
-   * ```typescript
-   * devUiGate: async (ctx) => {
-   *   const user = await ctx.get('auth').user()
-   *   return user?.role === 'admin'
-   * }
-   * ```
-   */
-  devUiGate?: ((ctx: GravitoContext) => boolean | Promise<boolean>) | undefined
-
-  /**
-   * Translation function for internationalization within emails.
-   *
-   * @example
-   * ```typescript
-   * translator: (key, replace, locale) => {
-   *   return i18n.t(key, { ...replace, locale: locale || 'en' })
-   * }
-   * ```
-   */
-  translator?:
-    | ((key: string, replace?: Record<string, unknown>, locale?: string) => string)
-    | undefined
-
-  /**
-   * URL prefix for Webhook endpoints.
-   */
-  webhookPrefix?: string | undefined
-
-  /**
-   * Dictionary of registered webhook drivers.
-   */
-  webhookDrivers?: Record<string, WebhookDriver> | undefined
-}

package/src/utils/html.ts

@@ -1,43 +0,0 @@
-/**
- * HTML utility functions.
- *
- * Provides helper methods for processing and transforming HTML content,
- * primarily for generating plain text alternatives for emails.
- *
- * @module utils/html
- * @since 3.1.0
- */
-
-/**
- * Convert HTML content to plain text.
- *
- * Removes all HTML tags, styles, scripts, and normalizes whitespace.
- * This is essential for generating the `text` part of a multipart email
- * to ensure compatibility with mail clients that do not support HTML.
- *
- * @param html - Source HTML string to be stripped
- * @returns Plain text content with tags and entities removed
- *
- * @example
- * ```typescript
- * const text = stripHtml('<h1>Hello</h1><p>World</p>')
- * // Returns: 'Hello World'
- * ```
- *
- * @public
- * @since 3.1.0
- */
-export function stripHtml(html: string): string {
-  return html
-    .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '')
-    .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '')
-    .replace(/<[^>]+>/g, '')
-    .replace(/&nbsp;/g, ' ')
-    .replace(/&amp;/g, '&')
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/\s+/g, ' ')
-    .trim()
-}

package/src/webhooks/SendGridWebhookDriver.ts

@@ -1,80 +0,0 @@
-import type { GravitoContext } from '@gravito/core'
-import type { WebhookDriver } from '../types'
-
-/**
- * Configuration for SendGrid Webhook Driver.
- */
-export interface SendGridWebhookConfig {
-  /**
-   * Public key or Verification Secret for signature validation.
-   * If provided, all requests will be validated.
-   */
-  publicKey?: string
-}
-
-/**
- * SendGrid Webhook Driver.
- *
- * Handles Event Webhooks from SendGrid (delivered, bounced, opened, clicked, etc.).
- *
- * @see https://docs.sendgrid.com/for-developers/tracking-events/event-webhook
- * @public
- * @since 1.1.0
- */
-export class SendGridWebhookDriver implements WebhookDriver {
-  constructor(private config: SendGridWebhookConfig = {}) {}
-
-  /**
-   * Handles the SendGrid webhook request.
-   */
-  async handle(c: GravitoContext): Promise<{ event: string; payload: any }[] | null> {
-    const body = await c.req.json()
-
-    // SendGrid events are usually sent as an array
-    const events = Array.isArray(body) ? body : [body]
-
-    if (this.config.publicKey) {
-      const signature = c.req.header('X-Twilio-Email-Event-Webhook-Signature')
-      const timestamp = c.req.header('X-Twilio-Email-Event-Webhook-Timestamp')
-
-      if (!signature || !timestamp) {
-        throw new Error('Missing SendGrid signature headers')
-      }
-
-      if (!this.verifySignature(JSON.stringify(body), signature, timestamp)) {
-        throw new Error('Invalid SendGrid signature')
-      }
-    }
-
-    if (events.length === 0) {
-      return null
-    }
-
-    return events.map((e) => ({
-      event: e.event,
-      payload: e,
-    }))
-  }
-
-  /**
-   * Verifies the SendGrid webhook signature.
-   *
-   * @param payload - Raw request body string.
-   * @param signature - Signature from X-Twilio-Email-Event-Webhook-Signature header.
-   * @param timestamp - Timestamp from X-Twilio-Email-Event-Webhook-Timestamp header.
-   * @returns True if signature is valid.
-   *
-   * @remarks
-   * Real SendGrid validation uses Elliptic Curve (ECDSA).
-   * This is a placeholder for the logic structure.
-   */
-  private verifySignature(_payload: string, _signature: string, _timestamp: string): boolean {
-    if (!this.config.publicKey) {
-      return true
-    }
-
-    // In a real implementation, you would use crypto.verify with the SendGrid public key.
-    // SendGrid uses ECDSA with SHA256.
-    return true // Placeholder: Actual implementation requires 'crypto' public key verification
-  }
-}

package/src/webhooks/SesWebhookDriver.ts

@@ -1,44 +0,0 @@
-import type { GravitoContext } from '@gravito/core'
-import type { WebhookDriver } from '../types'
-
-/**
- * AWS SES Webhook Driver.
- *
- * Handles SES Notifications via Amazon SNS (Complaints, Bounces, Deliveries).
- *
- * @see https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity-using-notifications.html
- * @public
- * @since 1.1.0
- */
-export class SesWebhookDriver implements WebhookDriver {
-  /**
-   * Handles the AWS SES/SNS webhook request.
-   *
-   * @param c - The Gravito request context.
-   * @returns Array of processed events or null if ignored.
-   */
-  async handle(c: GravitoContext): Promise<{ event: string; payload: any }[] | null> {
-    const body = (await c.req.json()) as any
-
-    // Handle SNS Subscription Confirmation
-    if (body.Type === 'SubscriptionConfirmation') {
-      // In production, you would visit body.SubscribeURL to confirm
-      return [{ event: 'sns:subscription', payload: body }]
-    }
-
-    // Handle SNS Notifications
-    if (body.Type === 'Notification') {
-      const message = typeof body.Message === 'string' ? JSON.parse(body.Message) : body.Message
-      const eventType = message.notificationType?.toLowerCase() || 'unknown'
-
-      return [
-        {
-          event: eventType,
-          payload: message,
-        },
-      ]
-    }
-
-    return null
-  }
-}

package/tests/DevMailbox.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'bun:test'
-import { DevMailbox } from '../src/dev/DevMailbox'
-import type { Message } from '../src/types'
-
-describe('DevMailbox', () => {
-  const mockMessage: Message = {
-    from: { address: 'from@example.com' },
-    to: [{ address: 'to@example.com' }],
-    subject: 'Test Subject',
-    html: '<h1>Hello</h1>',
-  }
-
-  it('should respect the default maximum entries (50)', async () => {
-    const mailbox = new DevMailbox()
-
-    // Add 60 messages
-    for (let i = 0; i < 60; i++) {
-      await mailbox.add({ ...mockMessage, subject: `Test ${i}` })
-    }
-
-    const list = await mailbox.list()
-    expect(list.length).toBe(50)
-    // Should keep the newest (Test 59)
-    expect(list[0].envelope.subject).toBe('Test 59')
-    // Should have removed Test 0-9, list[49] should be Test 10
-    expect(list[49].envelope.subject).toBe('Test 10')
-  })
-
-  it('should respect custom maximum entries via constructor', async () => {
-    const mailbox = new DevMailbox(10)
-
-    for (let i = 0; i < 15; i++) {
-      await mailbox.add(mockMessage)
-    }
-
-    const list = await mailbox.list()
-    expect(list.length).toBe(10)
-  })
-
-  it('should respect setMaxEntries and trim existing entries', async () => {
-    const mailbox = new DevMailbox(20)
-
-    for (let i = 0; i < 20; i++) {
-      await mailbox.add({ ...mockMessage, subject: `Test ${i}` })
-    }
-
-    expect((await mailbox.list()).length).toBe(20)
-
-    await mailbox.setMaxEntries(5)
-    const list = await mailbox.list()
-    expect(list.length).toBe(5)
-    expect(list[0].envelope.subject).toBe('Test 19')
-  })
-})

package/tests/FileMailboxStorage.test.ts

@@ -1,56 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdir, rm } from 'node:fs/promises'
-import { join } from 'node:path'
-import { DevMailbox } from '../src/dev/DevMailbox'
-import { FileMailboxStorage } from '../src/dev/storage/FileMailboxStorage'
-import type { Message } from '../src/types'
-
-describe('FileMailboxStorage Persistence', () => {
-  const testDir = join(import.meta.dir, 'tmp-mailbox')
-  const mockMessage: Message = {
-    from: { address: 'from@example.com' },
-    to: [{ address: 'to@example.com' }],
-    subject: 'Persistent Subject',
-    html: '<h1>Hello</h1>',
-  }
-
-  beforeEach(async () => {
-    await mkdir(testDir, { recursive: true })
-  })
-
-  afterEach(async () => {
-    await rm(testDir, { recursive: true, force: true })
-  })
-
-  it('should persist messages to disk and survive re-instantiation', async () => {
-    const storage1 = new FileMailboxStorage(testDir)
-    const mailbox1 = new DevMailbox(10, storage1)
-
-    await mailbox1.add({ ...mockMessage, subject: 'First Message' })
-    await mailbox1.add({ ...mockMessage, subject: 'Second Message' })
-
-    const list1 = await mailbox1.list()
-    expect(list1.length).toBe(2)
-
-    // Simulate server restart by creating new instance with same dir
-    const storage2 = new FileMailboxStorage(testDir)
-    const mailbox2 = new DevMailbox(10, storage2)
-
-    const list2 = await mailbox2.list()
-    expect(list2.length).toBe(2)
-    expect(list2[0].envelope.subject).toBe('Second Message')
-  })
-
-  it('should trim files according to max entries', async () => {
-    const storage = new FileMailboxStorage(testDir)
-    const mailbox = new DevMailbox(3, storage)
-
-    for (let i = 0; i < 5; i++) {
-      await mailbox.add({ ...mockMessage, subject: `Msg ${i}` })
-    }
-
-    const list = await mailbox.list()
-    expect(list.length).toBe(3)
-    expect(list[0].envelope.subject).toBe('Msg 4')
-  })
-})

package/tests/MjmlLayout.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, it } from 'bun:test'
-import { Mailable } from '../src/Mailable'
-
-class TestMailable extends Mailable {
-  build() {
-    return this
-  }
-}
-
-describe('Mailable MJML Layout', () => {
-  it('should wrap content with layout if provided', async () => {
-    const mailable = new TestMailable()
-    mailable.mjml('<mj-text>Hello</mj-text>', {
-      layout: '<mjml><mj-body>{{content}}</mj-body></mjml>',
-    })
-
-    // Access private renderer via cast to check final content
-    const content = await mailable.renderContent()
-    // The mock renderer would contain the final wrapped string
-    // Since we are using dynamic import in renderContent,
-    // it will actually try to load MjmlRenderer.
-    // We can verify the finalContent logic by checking the renderer state if possible
-    // or just let it render (mjml is installed)
-
-    expect(content.html).toContain('<div') // MJML rendered output
-    expect(content.html).toContain('Hello')
-  })
-})

package/tests/MjmlRenderer.test.ts

@@ -1,53 +0,0 @@
-import { describe, expect, it, mock } from 'bun:test'
-import { MjmlRenderer } from '../src/renderers/MjmlRenderer'
-
-describe('MjmlRenderer', () => {
-  const mjmlContent =
-    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>'
-
-  it('should render MJML to HTML', async () => {
-    // Mock mjml dependency
-    const mockMjml2Html = mock((content) => ({
-      html: `<html><body>${content}</body></html>`,
-      errors: [],
-    }))
-
-    const renderer = new MjmlRenderer(mjmlContent, {}, { mjml2html: mockMjml2Html })
-    const result = await renderer.render()
-
-    expect(result.html).toContain('<html><body>')
-    expect(result.html).toContain(mjmlContent)
-    expect(mockMjml2Html).toHaveBeenCalled()
-  })
-
-  it('should throw error if MJML has errors and validationLevel is strict', async () => {
-    const mockMjmlWithErrors = mock(() => ({
-      html: '',
-      errors: [{ formattedMessage: 'Line 1: Error' }],
-    }))
-
-    const renderer = new MjmlRenderer(
-      mjmlContent,
-      { validationLevel: 'strict' },
-      { mjml2html: mockMjmlWithErrors }
-    )
-
-    expect(renderer.render()).rejects.toThrow('MJML rendering failed')
-  })
-
-  it('should not throw error if MJML has errors and validationLevel is soft', async () => {
-    const mockMjmlWithErrors = mock(() => ({
-      html: 'partial html',
-      errors: [{ formattedMessage: 'Soft error' }],
-    }))
-
-    const renderer = new MjmlRenderer(
-      mjmlContent,
-      { validationLevel: 'soft' },
-      { mjml2html: mockMjmlWithErrors }
-    )
-
-    const result = await renderer.render()
-    expect(result.html).toBe('partial html')
-  })
-})