@gravito/signal 3.0.3 → 3.1.0

package/dist/transports/SmtpTransport.d.ts

@@ -0,0 +1,124 @@
+import type { Message } from '../types';
+import { BaseTransport, type TransportOptions } from './BaseTransport';
+/**
+ * Configuration for SMTP email transport.
+ *
+ * Defines the connection parameters, authentication, and pooling settings for
+ * communicating with an SMTP server.
+ *
+ * @example
+ * ```typescript
+ * const config: SmtpConfig = {
+ *   host: 'smtp.mailtrap.io',
+ *   port: 2525,
+ *   auth: { user: 'username', pass: 'password' },
+ *   poolSize: 10
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface SmtpConfig extends TransportOptions {
+    /** SMTP server hostname or IP address. */
+    host: string;
+    /** SMTP server port (typically 25, 465, or 587). */
+    port: number;
+    /** Whether to use a secure TLS/SSL connection. Should be true for port 465. */
+    secure?: boolean;
+    /** Authentication credentials for the SMTP server. */
+    auth?: {
+        /** SMTP username. */
+        user: string;
+        /** SMTP password. */
+        pass: string;
+    };
+    /** TLS specific options for the connection. */
+    tls?: {
+        /** Whether to reject unauthorized certificates (useful for self-signed certs). */
+        rejectUnauthorized?: boolean;
+        /** Specific cipher suite to use for the connection. */
+        ciphers?: string;
+    };
+    /** Number of concurrent connections to maintain in the pool. */
+    poolSize?: number;
+    /** Maximum time in milliseconds a connection can remain idle before being closed. */
+    maxIdleTime?: number;
+}
+/**
+ * SMTP email transport with connection pooling and automatic retry.
+ *
+ * This transport uses the standard SMTP protocol to deliver emails. It leverages
+ * `nodemailer` for robust protocol implementation and includes built-in support
+ * for connection pooling to improve performance when sending multiple emails.
+ * It inherits automatic retry logic from `BaseTransport`.
+ *
+ * @example
+ * ```typescript
+ * import { SmtpTransport } from '@gravito/signal';
+ *
+ * const transport = new SmtpTransport({
+ *   host: 'smtp.example.com',
+ *   port: 587,
+ *   auth: { user: 'user', pass: 'pass' }
+ * });
+ *
+ * await transport.send(message);
+ * ```
+ *
+ * @public
+ */
+export declare class SmtpTransport extends BaseTransport {
+    private transporter;
+    /**
+     * Initializes the SMTP transport with the provided configuration.
+     *
+     * Sets up the underlying nodemailer transporter with connection pooling enabled.
+     *
+     * @param config - SMTP connection and retry configuration.
+     */
+    constructor(config: SmtpConfig);
+    /**
+     * Internal method to perform the actual SMTP delivery.
+     *
+     * Maps the generic `Message` object to the format expected by nodemailer.
+     *
+     * @param message - The message to deliver.
+     * @returns A promise that resolves when the SMTP server accepts the message.
+     * @throws {Error} If the SMTP server rejects the message or connection fails.
+     */
+    protected doSend(message: Message): Promise<void>;
+    /**
+     * Gracefully shuts down the transport and closes all pooled connections.
+     *
+     * This should be called during application shutdown to ensure no resources are leaked.
+     *
+     * @returns A promise that resolves when all connections are closed.
+     *
+     * @example
+     * ```typescript
+     * await transport.close();
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Verifies the SMTP connection and authentication.
+     *
+     * Useful for health checks or validating configuration during startup.
+     *
+     * @returns A promise that resolves to true if the connection is valid, false otherwise.
+     *
+     * @example
+     * ```typescript
+     * const isValid = await transport.verify();
+     * if (!isValid) throw new Error('SMTP configuration is invalid');
+     * ```
+     */
+    verify(): Promise<boolean>;
+    /**
+     * Formats an Address object into a standard RFC 822 string.
+     *
+     * @param addr - The address object to format.
+     * @returns A string in the format "Name <email@example.com>" or just "email@example.com".
+     */
+    private formatAddress;
+}

package/dist/transports/Transport.d.ts

@@ -0,0 +1,44 @@
+import type { Message } from '../types';
+/**
+ * Interface for email transport mechanisms.
+ *
+ * Transports are responsible for the final delivery of an email message to its destination,
+ * whether it's a real SMTP server, a cloud service like AWS SES, or a local log for development.
+ * This abstraction allows the core mail service to remain agnostic of the delivery method.
+ *
+ * @example
+ * ```typescript
+ * class CustomTransport implements Transport {
+ *   async send(message: Message): Promise<void> {
+ *     // Implementation logic to deliver the message
+ *     console.log(`Sending email to ${message.to[0].address}`);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface Transport {
+    /**
+     * Send the given message using the underlying transport mechanism.
+     *
+     * This method handles the actual communication with the delivery service.
+     * Implementations should handle connection management and protocol-specific logic.
+     *
+     * @param message - The finalized message object containing recipients, subject, and content.
+     * @returns A promise that resolves when the message has been successfully handed off to the transport.
+     * @throws {MailTransportError} If the delivery fails after all internal retry attempts.
+     *
+     * @example
+     * ```typescript
+     * const transport: Transport = new LogTransport();
+     * await transport.send({
+     *   from: { address: 'sender@example.com' },
+     *   to: [{ address: 'receiver@example.com' }],
+     *   subject: 'Hello',
+     *   html: '<p>World</p>'
+     * });
+     * ```
+     */
+    send(message: Message): Promise<void>;
+}

package/dist/types.d.ts

@@ -0,0 +1,294 @@
+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;
+    /** Optional MIME type of the content. */
+    contentType?: string;
+    /** Optional Content-ID for referencing within HTML content (inline images). */
+    cid?: string;
+    /** 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/dist/utils/html.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare function stripHtml(html: string): string;

package/dist/webhooks/SendGridWebhookDriver.d.ts

@@ -0,0 +1,45 @@
+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 declare class SendGridWebhookDriver implements WebhookDriver {
+    private config;
+    constructor(config?: SendGridWebhookConfig);
+    /**
+     * Handles the SendGrid webhook request.
+     */
+    handle(c: GravitoContext): Promise<{
+        event: string;
+        payload: any;
+    }[] | null>;
+    /**
+     * 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;
+}

package/dist/webhooks/SesWebhookDriver.d.ts

@@ -0,0 +1,23 @@
+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 declare 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.
+     */
+    handle(c: GravitoContext): Promise<{
+        event: string;
+        payload: any;
+    }[] | null>;
+}

package/doc/ADVANCED_RENDERING.md

@@ -0,0 +1,71 @@
+# Advanced Email Rendering Guide
+
+`@gravito/signal` provides a powerful rendering engine that allows you to build complex, responsive, and type-safe emails using modern frontend frameworks.
+
+## 1. Component-Based Emails (React & Vue)
+
+Instead of traditional HTML templates, you can use React or Vue components to design your emails. This enables component reuse and strong typing.
+
+### React with MJML
+For truly responsive emails across all clients, we recommend using **MJML** components within React:
+
+```tsx
+import { Mailable } from '@gravito/signal'
+import { WelcomeTemplate } from './templates/WelcomeTemplate'
+
+export class WelcomeEmail extends Mailable {
+  build() {
+    return this
+      .subject('Welcome to Gravito!')
+      .react(WelcomeTemplate, { name: 'User' })
+  }
+}
+
+// WelcomeTemplate.tsx (using MJML style)
+export const WelcomeTemplate = ({ name }: { name: string }) => (
+  <mj-body>
+    <mj-section>
+      <mj-column>
+        <mj-text font-size="20px">Hello {name}!</mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+)
+```
+
+## 2. Localization (I18n) Integration
+
+`OrbitSignal` integrates with Gravito's translation system to provide localized email content.
+
+```typescript
+export class OrderConfirmation extends Mailable {
+  build() {
+    // The subject and view will be translated based on the current locale
+    return this
+      .subject(this.t('emails.order_confirmed'))
+      .view('emails/orders', { id: this.order.id })
+  }
+}
+```
+
+## 3. Dynamic Styles and Assets
+
+Manage assets and styles dynamically to ensure your emails look great on all devices.
+
+- **Inlining Styles**: All CSS used in your templates is automatically inlined during the rendering phase.
+- **Image Assets**: Use the `asset()` helper to generate full URLs for images hosted in your public directory or a CDN.
+
+## 4. Testing Your Renderers
+
+Test your mailable's rendering without sending any emails:
+
+```typescript
+import { WelcomeEmail } from './mailables/WelcomeEmail'
+
+it('should render the correct HTML', async () => {
+  const mailable = new WelcomeEmail({ name: 'Carl' })
+  const content = await mailable.renderContent()
+  
+  expect(content.html).toContain('Hello Carl!')
+})
+```