@bernierllc/email-sender 3.0.3 → 3.1.0

package/README.md

@@ -5,6 +5,7 @@ A core utility for basic email sending with provider-agnostic interface.
 ## Features
 
 - **Provider-Agnostic**: Support for multiple email providers (SMTP, SendGrid, SES, Mailgun, Postmark)
+- **Staging Email Safety**: Prevent accidental email sends in non-production environments
 - **TypeScript**: Full TypeScript support with strict typing
 - **Validation**: Comprehensive email and configuration validation
 - **Attachments**: Support for file attachments
@@ -280,6 +281,143 @@ interface EmailProviderConfig {
 }
 ```
 
+## Staging Email Safety
+
+Prevent accidental email sends in non-production environments by using the staging safety feature.
+
+### Staging with Whitelist (Block Non-Whitelisted)
+
+```typescript
+import { EmailSender } from '@bernierllc/email-sender';
+
+const emailSender = new EmailSender({
+  provider: 'smtp' as const,
+  host: 'smtp.example.com',
+  port: 587,
+  username: 'user',
+  password: 'pass',
+  fromEmail: 'sender@example.com',
+  stagingSafety: {
+    enabled: true,
+    environment: 'staging',
+    whitelist: ['test@example.com', 'admin@example.com', 'qa@example.com'],
+    blockNonWhitelisted: true,
+    logBlocked: true,
+  },
+});
+
+// This will send (whitelisted)
+await emailSender.sendEmail({
+  toEmail: 'test@example.com',
+  subject: 'Test Email',
+  htmlContent: '<p>This email will be sent</p>',
+});
+
+// This will be blocked (not whitelisted)
+const result = await emailSender.sendEmail({
+  toEmail: 'customer@example.com',
+  subject: 'Test Email',
+  htmlContent: '<p>This email will be blocked</p>',
+});
+console.log(result.success); // false
+console.log(result.errorMessage); // "Email blocked by safety manager: ..."
+```
+
+### Staging with Rewrite (Redirect to Test Email)
+
+```typescript
+const emailSender = new EmailSender({
+  provider: 'smtp' as const,
+  host: 'smtp.example.com',
+  port: 587,
+  username: 'user',
+  password: 'pass',
+  fromEmail: 'sender@example.com',
+  stagingSafety: {
+    enabled: true,
+    environment: 'staging',
+    whitelist: ['admin@example.com'], // Admin emails go through normally
+    rewriteTo: 'staging-test@example.com', // All other emails redirected here
+    blockNonWhitelisted: false,
+    logBlocked: true,
+  },
+});
+
+// This will be sent to staging-test@example.com instead
+await emailSender.sendEmail({
+  toEmail: 'customer@example.com',
+  subject: 'Test Email',
+  htmlContent: '<p>This will be sent to staging-test@example.com</p>',
+});
+```
+
+### Production (All Emails Allowed)
+
+```typescript
+const emailSender = new EmailSender({
+  provider: 'smtp' as const,
+  host: 'smtp.example.com',
+  port: 587,
+  username: 'user',
+  password: 'pass',
+  fromEmail: 'sender@example.com',
+  stagingSafety: {
+    enabled: true,
+    environment: 'production',
+    whitelist: [], // Not used in production
+    blockNonWhitelisted: false,
+    logBlocked: false,
+  },
+});
+
+// All emails are allowed in production
+await emailSender.sendEmail({
+  toEmail: 'customer@example.com',
+  subject: 'Production Email',
+  htmlContent: '<p>This email will be sent</p>',
+});
+```
+
+### Check Recipient Safety Before Sending
+
+```typescript
+const safetyResult = emailSender.checkRecipientSafety('test@example.com');
+console.log('Safety check result:', safetyResult);
+
+if (safetyResult && !safetyResult.allowed) {
+  console.log('Email would be blocked:', safetyResult.reason);
+}
+```
+
+### Dynamic Configuration Based on Environment
+
+```typescript
+const environment = process.env.NODE_ENV || 'development';
+
+const emailSender = new EmailSender({
+  provider: 'smtp' as const,
+  host: 'smtp.example.com',
+  port: 587,
+  username: 'user',
+  password: 'pass',
+  fromEmail: 'sender@example.com',
+  stagingSafety: {
+    enabled: environment !== 'production',
+    environment: environment as 'development' | 'staging' | 'production',
+    whitelist: environment === 'staging'
+      ? ['qa@example.com', 'test@example.com']
+      : [],
+    rewriteTo: environment === 'development' ? 'dev@example.com' : undefined,
+    blockNonWhitelisted: environment === 'staging',
+    logBlocked: true,
+  },
+});
+
+console.log('Current environment:', environment);
+console.log('Safety enabled:', emailSender.isSafetyEnabled());
+console.log('Safety config:', emailSender.getSafetyConfig());
+```
+
 ## Examples
 
 ### Send Email with Attachment

package/dist/core/email-safety-manager.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Email Safety Manager - Staging Email Safety
+ * Prevents accidental email sends in non-production environments
+ */
+import { StagingSafetyConfig, EmailSafetyResult } from '../types';
+export declare class EmailSafetyManager {
+    private config;
+    constructor(config: StagingSafetyConfig);
+    /**
+     * Check if a recipient is allowed to receive emails
+     */
+    checkRecipient(email: string): EmailSafetyResult;
+    /**
+     * Check if an email address is whitelisted
+     */
+    isWhitelisted(email: string): boolean;
+    /**
+     * Rewrite a recipient email address
+     */
+    rewriteRecipient(email: string): string;
+    /**
+     * Update the safety configuration
+     */
+    updateConfig(config: Partial<StagingSafetyConfig>): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): StagingSafetyConfig;
+}
+//# sourceMappingURL=email-safety-manager.d.ts.map

package/dist/core/email-safety-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-safety-manager.d.ts","sourceRoot":"","sources":["../../src/core/email-safety-manager.ts"],"names":[],"mappings":"AAQA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,EAAE,mBAAmB;IAIvC;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB;IAkEhD;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAOrC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOvC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAIxD;;OAEG;IACH,SAAS,IAAI,mBAAmB;CAGjC"}

package/dist/core/email-safety-manager.js

@@ -0,0 +1,106 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailSafetyManager = void 0;
+class EmailSafetyManager {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Check if a recipient is allowed to receive emails
+     */
+    checkRecipient(email) {
+        // If safety is disabled, allow all emails
+        if (!this.config.enabled) {
+            return {
+                allowed: true,
+                originalRecipient: email,
+                finalRecipient: email,
+                action: 'sent',
+            };
+        }
+        const normalizedEmail = email.toLowerCase().trim();
+        // In production, all emails are allowed
+        if (this.config.environment === 'production') {
+            return {
+                allowed: true,
+                originalRecipient: email,
+                finalRecipient: email,
+                action: 'sent',
+            };
+        }
+        // Check if email is whitelisted
+        const isWhitelisted = this.isWhitelisted(normalizedEmail);
+        if (isWhitelisted) {
+            return {
+                allowed: true,
+                originalRecipient: email,
+                finalRecipient: email,
+                action: 'sent',
+            };
+        }
+        // If rewrite is configured, rewrite the recipient
+        if (this.config.rewriteTo) {
+            return {
+                allowed: true,
+                originalRecipient: email,
+                finalRecipient: this.config.rewriteTo,
+                action: 'rewritten',
+                reason: 'Non-production environment with rewrite enabled',
+            };
+        }
+        // If blocking is enabled, block the email
+        if (this.config.blockNonWhitelisted) {
+            return {
+                allowed: false,
+                originalRecipient: email,
+                finalRecipient: email,
+                action: 'blocked',
+                reason: 'Non-whitelisted recipient in staging environment',
+            };
+        }
+        // Default: allow but log
+        return {
+            allowed: true,
+            originalRecipient: email,
+            finalRecipient: email,
+            action: 'sent',
+        };
+    }
+    /**
+     * Check if an email address is whitelisted
+     */
+    isWhitelisted(email) {
+        const normalizedEmail = email.toLowerCase().trim();
+        return this.config.whitelist.some((whitelisted) => whitelisted.toLowerCase().trim() === normalizedEmail);
+    }
+    /**
+     * Rewrite a recipient email address
+     */
+    rewriteRecipient(email) {
+        if (!this.config.rewriteTo) {
+            return email;
+        }
+        return this.config.rewriteTo;
+    }
+    /**
+     * Update the safety configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.EmailSafetyManager = EmailSafetyManager;
+//# sourceMappingURL=email-safety-manager.js.map

package/dist/core/email-safety-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-safety-manager.js","sourceRoot":"","sources":["../../src/core/email-safety-manager.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AASF,MAAa,kBAAkB;IAG7B,YAAY,MAA2B;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,KAAa;QAC1B,0CAA0C;QAC1C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,iBAAiB,EAAE,KAAK;gBACxB,cAAc,EAAE,KAAK;gBACrB,MAAM,EAAE,MAAM;aACf,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QAEnD,wCAAwC;QACxC,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,YAAY,EAAE,CAAC;YAC7C,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,iBAAiB,EAAE,KAAK;gBACxB,cAAc,EAAE,KAAK;gBACrB,MAAM,EAAE,MAAM;aACf,CAAC;QACJ,CAAC;QAED,gCAAgC;QAChC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QAE1D,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,iBAAiB,EAAE,KAAK;gBACxB,cAAc,EAAE,KAAK;gBACrB,MAAM,EAAE,MAAM;aACf,CAAC;QACJ,CAAC;QAED,kDAAkD;QAClD,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC1B,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,iBAAiB,EAAE,KAAK;gBACxB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBACrC,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,iDAAiD;aAC1D,CAAC;QACJ,CAAC;QAED,0CAA0C;QAC1C,IAAI,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;YACpC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,iBAAiB,EAAE,KAAK;gBACxB,cAAc,EAAE,KAAK;gBACrB,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,kDAAkD;aAC3D,CAAC;QACJ,CAAC;QAED,yBAAyB;QACzB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,iBAAiB,EAAE,KAAK;YACxB,cAAc,EAAE,KAAK;YACrB,MAAM,EAAE,MAAM;SACf,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,KAAa;QACzB,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAC/B,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,eAAe,CACtE,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,KAAa;QAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAoC;QAC/C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;CACF;AA7GD,gDA6GC"}

package/dist/core/email-sender.d.ts

@@ -2,18 +2,24 @@
  * Main EmailSender class for managing email providers
  */
 import { EmailProvider, EmailProviderConfig } from '../providers/base';
-import { EmailMessage, SendResult, DeliveryStatus, WebhookEvent, EmailProviderCapabilities, EmailValidationResult } from '../types';
+import { EmailMessage, SendResult, DeliveryStatus, WebhookEvent, EmailProviderCapabilities, EmailValidationResult, StagingSafetyConfig, EmailSafetyResult } from '../types';
+export interface EmailSenderConfig extends EmailProviderConfig {
+    stagingSafety?: StagingSafetyConfig;
+}
 export declare class EmailSender {
     private provider;
-    constructor(config: EmailProviderConfig);
+    private safetyManager?;
+    constructor(config: EmailSenderConfig);
     /**
      * Create the appropriate provider based on configuration
      */
     private createProvider;
     /**
-     * Send a single email
+     * Send a single email with optional safety checks
      */
-    sendEmail(email: EmailMessage): Promise<SendResult>;
+    sendEmail(email: EmailMessage, options?: {
+        bypassSafety?: boolean;
+    }): Promise<SendResult>;
     /**
      * Send multiple emails
      */
@@ -66,6 +72,18 @@ export declare class EmailSender {
     /**
      * Update provider configuration
      */
-    updateConfig(config: EmailProviderConfig): void;
+    updateConfig(config: EmailSenderConfig): void;
+    /**
+     * Check if a recipient would be allowed by the safety manager
+     */
+    checkRecipientSafety(email: string): EmailSafetyResult | null;
+    /**
+     * Get the current safety configuration
+     */
+    getSafetyConfig(): StagingSafetyConfig | null;
+    /**
+     * Check if staging safety is enabled
+     */
+    isSafetyEnabled(): boolean;
 }
 //# sourceMappingURL=email-sender.d.ts.map

package/dist/core/email-sender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email-sender.d.ts","sourceRoot":"","sources":["../../src/core/email-sender.ts"],"names":[],"mappings":"AAQA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAMvE,OAAO,EACL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,UAAU,CAAC;AAElB,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAgB;gBAEpB,MAAM,EAAE,mBAAmB;IAIvC;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAIzD;;OAEG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAI9D;;OAEG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI1E;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI9E;;OAEG;IACH,qBAAqB,IAAI,qBAAqB;IAI9C;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,eAAe,IAAI,yBAAyB;IAI5C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxC;;OAEG;IACH,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,qBAAqB;IAIhE;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC;IAOnB;;OAEG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC;IAOtB;;OAEG;IACH,WAAW,IAAI,aAAa;IAI5B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;CAGhD"}
+{"version":3,"file":"email-sender.d.ts","sourceRoot":"","sources":["../../src/core/email-sender.ts"],"names":[],"mappings":"AAQA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAOvE,OAAO,EACL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,yBAAyB,EACzB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,aAAa,CAAC,CAAqB;gBAE/B,MAAM,EAAE,iBAAiB;IASrC;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB/F;;OAEG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAI9D;;OAEG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI1E;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI9E;;OAEG;IACH,qBAAqB,IAAI,qBAAqB;IAI9C;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,eAAe,IAAI,yBAAyB;IAI5C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxC;;OAEG;IACH,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,qBAAqB;IAIhE;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC;IAOnB;;OAEG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC;IAOtB;;OAEG;IACH,WAAW,IAAI,aAAa;IAI5B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAa7C;;OAEG;IACH,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAO7D;;OAEG;IACH,eAAe,IAAI,mBAAmB,GAAG,IAAI;IAO7C;;OAEG;IACH,eAAe,IAAI,OAAO;CAG3B"}

package/dist/core/email-sender.js

@@ -13,9 +13,14 @@ const sendgrid_1 = require("../providers/sendgrid");
 const ses_1 = require("../providers/ses");
 const mailgun_1 = require("../providers/mailgun");
 const postmark_1 = require("../providers/postmark");
+const email_safety_manager_1 = require("./email-safety-manager");
 class EmailSender {
     constructor(config) {
         this.provider = this.createProvider(config);
+        // Initialize safety manager if configured
+        if (config.stagingSafety) {
+            this.safetyManager = new email_safety_manager_1.EmailSafetyManager(config.stagingSafety);
+        }
     }
     /**
      * Create the appropriate provider based on configuration
@@ -37,9 +42,24 @@ class EmailSender {
         }
     }
     /**
-     * Send a single email
+     * Send a single email with optional safety checks
      */
-    async sendEmail(email) {
+    async sendEmail(email, options) {
+        // Apply staging safety if enabled
+        if (this.safetyManager && !options?.bypassSafety) {
+            const safetyResult = this.safetyManager.checkRecipient(email.toEmail);
+            if (!safetyResult.allowed) {
+                return {
+                    success: false,
+                    errorMessage: `Email blocked by safety manager: ${safetyResult.reason}`,
+                    metadata: { safetyResult },
+                };
+            }
+            // Rewrite recipient if needed
+            if (safetyResult.action === 'rewritten') {
+                email = { ...email, toEmail: safetyResult.finalRecipient };
+            }
+        }
         return this.provider.sendEmail(email);
     }
     /**
@@ -119,6 +139,39 @@ class EmailSender {
      */
     updateConfig(config) {
         this.provider = this.createProvider(config);
+        // Update or initialize safety manager
+        if (config.stagingSafety) {
+            if (this.safetyManager) {
+                this.safetyManager.updateConfig(config.stagingSafety);
+            }
+            else {
+                this.safetyManager = new email_safety_manager_1.EmailSafetyManager(config.stagingSafety);
+            }
+        }
+    }
+    /**
+     * Check if a recipient would be allowed by the safety manager
+     */
+    checkRecipientSafety(email) {
+        if (!this.safetyManager) {
+            return null;
+        }
+        return this.safetyManager.checkRecipient(email);
+    }
+    /**
+     * Get the current safety configuration
+     */
+    getSafetyConfig() {
+        if (!this.safetyManager) {
+            return null;
+        }
+        return this.safetyManager.getConfig();
+    }
+    /**
+     * Check if staging safety is enabled
+     */
+    isSafetyEnabled() {
+        return this.safetyManager !== undefined;
     }
 }
 exports.EmailSender = EmailSender;

package/dist/core/email-sender.js.map

@@ -1 +1 @@
-{"version":3,"file":"email-sender.js","sourceRoot":"","sources":["../../src/core/email-sender.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"email-sender.js","sourceRoot":"","sources":["../../src/core/email-sender.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAOF,4CAAiD;AACjD,oDAAyD;AACzD,0CAA+C;AAC/C,kDAAuD;AACvD,oDAAyD;AACzD,iEAA4D;AAgB5D,MAAa,WAAW;IAItB,YAAY,MAAyB;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAE5C,0CAA0C;QAC1C,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACzB,IAAI,CAAC,aAAa,GAAG,IAAI,yCAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,MAA2B;QAChD,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;YACxB,KAAK,MAAM;gBACT,OAAO,IAAI,mBAAY,CAAC,MAAM,CAAC,CAAC;YAClC,KAAK,UAAU;gBACb,OAAO,IAAI,2BAAgB,CAAC,MAAM,CAAC,CAAC;YACtC,KAAK,KAAK;gBACR,OAAO,IAAI,iBAAW,CAAC,MAAa,CAAC,CAAC;YACxC,KAAK,SAAS;gBACZ,OAAO,IAAI,yBAAe,CAAC,MAAa,CAAC,CAAC;YAC5C,KAAK,UAAU;gBACb,OAAO,IAAI,2BAAgB,CAAC,MAAa,CAAC,CAAC;YAC7C;gBACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAmB,EAAE,OAAoC;QACvE,kCAAkC;QAClC,IAAI,IAAI,CAAC,aAAa,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;YACjD,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAEtE,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;gBAC1B,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,YAAY,EAAE,oCAAoC,YAAY,CAAC,MAAM,EAAE;oBACvE,QAAQ,EAAE,EAAE,YAAY,EAAE;iBAC3B,CAAC;YACJ,CAAC;YAED,8BAA8B;YAC9B,IAAI,YAAY,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBACxC,KAAK,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,cAAc,EAAE,CAAC;YAC7D,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,MAAsB;QACpC,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CAAC,SAAiB;QACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,OAAY,EAAE,SAAiB;QAClD,OAAO,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,qBAAqB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,qBAAqB,EAAE,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,oBAAoB,CAAC,KAAmB;QACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,YAKpB;QACC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CACrB,UAAkB,EAClB,OAAe,EACf,YAAiC,EACjC,MAAe;QAEf,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACpF,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAyB;QACpC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAE5C,sCAAsC;QACtC,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YACxD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,aAAa,GAAG,IAAI,yCAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,oBAAoB,CAAC,KAAa;QAChC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,eAAe;QACb,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC;IAC1C,CAAC;CACF;AAjMD,kCAiMC"}

package/dist/errors.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Email sender error classes with ES2022 Error.cause support
+ *
+ * These errors follow the error propagation standard defined in:
+ * plans/standards/error-propagation-standard.md
+ */
+/**
+ * Error codes for programmatic error handling
+ */
+export declare const EmailSenderErrorCode: {
+    readonly PROVIDER_ERROR: "PROVIDER_ERROR";
+    readonly PROVIDER_AUTH_ERROR: "PROVIDER_AUTH_ERROR";
+    readonly PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED";
+    readonly PROVIDER_UNAVAILABLE: "PROVIDER_UNAVAILABLE";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INVALID_EMAIL: "INVALID_EMAIL";
+    readonly INVALID_TEMPLATE: "INVALID_TEMPLATE";
+    readonly TEMPLATE_NOT_FOUND: "TEMPLATE_NOT_FOUND";
+    readonly TEMPLATE_UNAUTHORIZED: "TEMPLATE_UNAUTHORIZED";
+    readonly TEMPLATE_CONFLICT: "TEMPLATE_CONFLICT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    readonly SEND_ERROR: "SEND_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export type EmailSenderErrorCodeType = typeof EmailSenderErrorCode[keyof typeof EmailSenderErrorCode];
+/**
+ * Options for creating an EmailSenderError
+ */
+export interface EmailSenderErrorOptions {
+    /** The underlying error that caused this error */
+    cause?: Error;
+    /** Machine-readable error code for programmatic handling */
+    code?: EmailSenderErrorCodeType;
+    /** Additional context about the error */
+    context?: Record<string, unknown>;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** Suggested retry delay in milliseconds */
+    retryAfter?: number;
+}
+/**
+ * Base error class for all email sender errors
+ *
+ * Supports ES2022 Error.cause for error chaining.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sendGridClient.send(email);
+ * } catch (error) {
+ *   throw new EmailSenderError('Failed to send email via SendGrid', {
+ *     cause: error,
+ *     code: 'PROVIDER_ERROR',
+ *     context: { provider: 'sendgrid', to: email.to }
+ *   });
+ * }
+ * ```
+ */
+export declare class EmailSenderError extends Error {
+    readonly code: EmailSenderErrorCodeType;
+    readonly context: Record<string, unknown> | undefined;
+    readonly retryable: boolean;
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: EmailSenderErrorOptions);
+    /**
+     * Check if the error or any error in its cause chain is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get retry timing from this error or its cause chain
+     */
+    getRetryAfter(): number | undefined;
+}
+/**
+ * Error thrown when email validation fails
+ */
+export declare class EmailValidationError extends EmailSenderError {
+    constructor(message: string, options?: Omit<EmailSenderErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when a provider operation fails
+ */
+export declare class ProviderError extends EmailSenderError {
+    readonly statusCode: number | undefined;
+    readonly providerResponse: unknown;
+    constructor(message: string, options?: EmailSenderErrorOptions & {
+        statusCode?: number;
+        providerResponse?: unknown;
+    });
+}
+/**
+ * Error thrown when rate limited by a provider
+ */
+export declare class RateLimitError extends EmailSenderError {
+    constructor(message: string, options?: Omit<EmailSenderErrorOptions, 'code' | 'retryable'> & {
+        retryAfter?: number;
+    });
+}
+/**
+ * Error thrown when network communication fails
+ */
+export declare class NetworkError extends EmailSenderError {
+    constructor(message: string, options?: Omit<EmailSenderErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when a request times out
+ */
+export declare class TimeoutError extends EmailSenderError {
+    constructor(message: string, options?: Omit<EmailSenderErrorOptions, 'code'>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;CAwBvB,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,OAAO,oBAAoB,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAEtG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,wBAAwB,CAAC;IAChC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAiB9D;;OAEG;IACH,WAAW,IAAI,OAAO;IAetB;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,SAAS;CAcpC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;gBAC5C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC;CAI7E;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,gBAAgB;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;gBAGjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,uBAAuB,GAAG;QAClC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B;CAOJ;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,gBAAgB;gBAEhD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,GAAG,WAAW,CAAC,GAAG;QAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;CAaJ;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,gBAAgB;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC;CAQ7E;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,gBAAgB;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC;CAQ7E"}