@gravito/signal 3.0.4 → 3.1.2

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/{src/utils/html.ts → dist/utils/html.d.ts}

@@ -7,7 +7,6 @@
  * @module utils/html
  * @since 3.1.0
  */
-
 /**
  * Convert HTML content to plain text.
  *
@@ -27,17 +26,4 @@
  * @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()
-}
+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/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@gravito/signal",
-  "version": "3.0.4",
+  "sideEffects": false,
+  "version": "3.1.2",
   "description": "Powerful email framework for Gravito applications with Dev UI and multi-renderer support.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --external @gravito/core --external @gravito/stream --external @gravito/prism",
+    "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
     "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
@@ -14,6 +23,10 @@
     "test:unit": "bun test tests/ --timeout=10000",
     "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "keywords": [
     "gravito",
     "mail",
@@ -29,8 +42,8 @@
     "nodemailer": "^7.0.11"
   },
   "peerDependencies": {
-    "@gravito/core": "^1.6.1",
-    "@gravito/stream": "^2.0.2",
+    "@gravito/core": "^2.0.0",
+    "@gravito/stream": "^2.1.0",
     "@gravito/prism": "^3.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -51,14 +64,13 @@
     }
   },
   "devDependencies": {
-    "@gravito/prism": "^3.1.1",
-    "@gravito/stream": "^2.0.2",
+    "@gravito/prism": "workspace:*",
+    "@gravito/stream": "workspace:*",
     "@types/nodemailer": "^6.4.14",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vue/server-renderer": "^3.0.0",
-    "@gravito/core": "^1.6.1",
-    "tsup": "8.5.1",
+    "@gravito/core": "workspace:*",
     "typescript": "^5.9.3",
     "vue": "^3.0.0",
     "bun-types": "latest"

package/CHANGELOG.md

@@ -1,74 +0,0 @@
-# @gravito/signal
-
-## 3.0.4
-
-### Patch Changes
-
-- Convert all workspace:\* dependencies to version numbers for npm publishing
-
-  - Fixed 144 workspace:\* dependencies across 58 packages
-  - Ensures all packages work properly when installed from npm
-  - Resolves issues with bunx and npm installation of CLI tools
-  - All internal dependencies now use explicit version constraints
-
-- Updated dependencies
-  - @gravito/core@1.6.1
-  - @gravito/prism@3.1.1
-  - @gravito/stream@2.0.2
-
-## 3.0.3
-
-### Patch Changes
-
-- Updated dependencies [6234dab]
-  - @gravito/prism@3.0.2
-
-## 3.0.2
-
-### Patch Changes
-
-- Updated dependencies [905588f]
-  - @gravito/stream@2.0.1
-
-## 3.0.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @gravito/core@1.2.1
-  - @gravito/stream@1.0.3
-  - @gravito/prism@3.0.1
-
-## 3.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @gravito/core@1.2.0
-  - @gravito/prism@3.0.0
-  - @gravito/stream@1.0.2
-
-## 2.0.0
-
-### Patch Changes
-
-- Updated dependencies
-- Updated dependencies
-  - @gravito/core@1.1.0
-  - @gravito/prism@2.0.0
-  - @gravito/stream@1.0.1
-
-## 1.0.1
-
-### Patch Changes
-
-- Refactored all scaffold generators (Enterprise MVC, Clean Architecture, Action Domain, DDD) to adopt the Service Provider pattern and a modern 4-step bootstrap lifecycle. Fixed a missing mock in @gravito/signal tests.
-
-## 1.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @gravito/core@1.0.0
-  - @gravito/stream@1.0.0
-  - @gravito/prism@1.0.0