@breadstone/archipel-platform-mailing 0.0.20 → 0.0.21

package/README.md

@@ -73,6 +73,30 @@ Set `MAIL_DELIVERY_STRATEGY` to one of: `smtp`, `postmark`, `resend`, `sendgrid`
 - **Attachment support**: Send file attachments with MIME-type validation and size limits (25 MB max)
 - **Header injection prevention**: Subject lines are automatically sanitized against SMTP header injection
 
+## Error Handling
+
+All delivery strategies throw a `MailDeliveryError` when email sending fails. This domain error wraps the underlying provider error and exposes structured metadata:
+
+```typescript
+import { MailDeliveryError } from '@breadstone/archipel-platform-mailing';
+
+try {
+  await mailService.send(options, content, true);
+} catch (error) {
+  if (error instanceof MailDeliveryError) {
+    console.error(error.provider); // 'postmark', 'smtp', 'resend', etc.
+    console.error(error.code); // 'MAIL_DELIVERY'
+    console.error(error.cause); // Original provider SDK error
+  }
+}
+```
+
+| Property   | Type      | Description                                     |
+| ---------- | --------- | ----------------------------------------------- |
+| `code`     | `string`  | Always `'MAIL_DELIVERY'`                        |
+| `provider` | `string`  | Provider that failed (`smtp`, `postmark`, etc.) |
+| `cause`    | `unknown` | Original error from the provider SDK            |
+
 ## Available Providers
 
 | Subpath                                          | Class                      | SDK              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-platform-mailing",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "Email delivery with strategy-based transport and template engines for NestJS applications.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -75,9 +75,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@breadstone/archipel-platform-blob-storage": "0.0.20",
-    "@breadstone/archipel-platform-configuration": "0.0.20",
-    "@breadstone/archipel-platform-core": "0.0.20",
+    "@breadstone/archipel-platform-blob-storage": "0.0.21",
+    "@breadstone/archipel-platform-configuration": "0.0.21",
+    "@breadstone/archipel-platform-core": "0.0.21",
     "form-data": "4.0.5",
     "nodemailer": "8.0.5",
     "tslib": "2.8.1"

package/src/errors/MailDeliveryError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Domain error thrown when email delivery fails.
+ *
+ * @public
+ */
+export declare class MailDeliveryError extends Error {
+    readonly code = "MAIL_DELIVERY";
+    readonly provider: string;
+    constructor(provider: string, message: string, cause?: unknown);
+}

package/src/errors/MailDeliveryError.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailDeliveryError = void 0;
+/**
+ * Domain error thrown when email delivery fails.
+ *
+ * @public
+ */
+class MailDeliveryError extends Error {
+    // #endregion
+    // #region Ctor
+    constructor(provider, message, cause) {
+        super(message, { cause });
+        // #region Fields
+        this.code = 'MAIL_DELIVERY';
+        this.name = 'MailDeliveryError';
+        this.provider = provider;
+    }
+}
+exports.MailDeliveryError = MailDeliveryError;
+//# sourceMappingURL=MailDeliveryError.js.map

package/src/errors/index.d.ts

@@ -0,0 +1 @@
+export { MailDeliveryError } from './MailDeliveryError';

package/src/errors/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailDeliveryError = void 0;
+var MailDeliveryError_1 = require("./MailDeliveryError");
+Object.defineProperty(exports, "MailDeliveryError", { enumerable: true, get: function () { return MailDeliveryError_1.MailDeliveryError; } });
+//# sourceMappingURL=index.js.map

package/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from './env';
+export * from './errors/MailDeliveryError';
 export * from './events';
 export * from './MailModule';
 export * from './MailTokens';

package/src/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./env"), exports);
+tslib_1.__exportStar(require("./errors/MailDeliveryError"), exports);
 tslib_1.__exportStar(require("./events"), exports);
 tslib_1.__exportStar(require("./MailModule"), exports);
 tslib_1.__exportStar(require("./MailTokens"), exports);

package/src/services/strategies/MailgunDeliveryStrategy.js

@@ -7,6 +7,7 @@ const common_1 = require("@nestjs/common");
 const form_data_1 = tslib_1.__importDefault(require("form-data"));
 const mailgun_js_1 = tslib_1.__importDefault(require("mailgun.js"));
 const env_1 = require("../../env");
+const MailDeliveryError_1 = require("../../errors/MailDeliveryError");
 const DeliveryStrategyBase_1 = require("./abstracts/DeliveryStrategyBase");
 // #endregion
 /**
@@ -54,14 +55,14 @@ class MailgunDeliveryStrategy extends DeliveryStrategyBase_1.DeliveryStrategyBas
                 ...(isHtml ? { html: content } : { text: content }),
             });
             const timeoutPromise = new Promise((_resolve, reject) => {
-                setTimeout(() => reject(new Error('Mailgun send timed out after 30000ms')), 30_000);
+                setTimeout(() => reject(new Error('Mailgun send timed out after 5000ms')), 5_000);
             });
             await Promise.race([sendPromise, timeoutPromise]);
             this._logger.log('Email sent successfully', 'Mail');
         }
         catch (error) {
             this._logger.error('Error sending email:', error);
-            throw error;
+            throw new MailDeliveryError_1.MailDeliveryError('mailgun', 'Failed to send email via Mailgun', error);
         }
     }
 }

package/src/services/strategies/PostmarkDeliveryStrategy.js

@@ -5,6 +5,7 @@ exports.PostmarkDeliveryStrategy = void 0;
 const common_1 = require("@nestjs/common");
 const postmark_1 = require("postmark");
 const env_1 = require("../../env");
+const MailDeliveryError_1 = require("../../errors/MailDeliveryError");
 const DeliveryStrategyBase_1 = require("./abstracts/DeliveryStrategyBase");
 // #endregion
 /**
@@ -47,14 +48,14 @@ class PostmarkDeliveryStrategy extends DeliveryStrategyBase_1.DeliveryStrategyBa
                 ...(isHtml ? { HtmlBody: content } : { TextBody: content }),
             });
             const timeoutPromise = new Promise((_resolve, reject) => {
-                setTimeout(() => reject(new Error('Postmark send timed out after 30000ms')), 30_000);
+                setTimeout(() => reject(new Error('Postmark send timed out after 5000ms')), 5_000);
             });
             await Promise.race([sendPromise, timeoutPromise]);
             this._logger.log('Email sent successfully', 'Mail');
         }
         catch (error) {
             this._logger.error('Error sending email:', error);
-            throw error;
+            throw new MailDeliveryError_1.MailDeliveryError('postmark', 'Failed to send email via Postmark', error);
         }
     }
 }

package/src/services/strategies/ResendDeliveryStrategy.js

@@ -5,6 +5,7 @@ exports.ResendDeliveryStrategy = void 0;
 const common_1 = require("@nestjs/common");
 const resend_1 = require("resend");
 const env_1 = require("../../env");
+const MailDeliveryError_1 = require("../../errors/MailDeliveryError");
 const DeliveryStrategyBase_1 = require("./abstracts/DeliveryStrategyBase");
 // #endregion
 /**
@@ -47,14 +48,14 @@ class ResendDeliveryStrategy extends DeliveryStrategyBase_1.DeliveryStrategyBase
                 ...(isHtml ? { html: content } : { text: content }),
             });
             const timeoutPromise = new Promise((_resolve, reject) => {
-                setTimeout(() => reject(new Error('Resend send timed out after 30000ms')), 30_000);
+                setTimeout(() => reject(new Error('Resend send timed out after 5000ms')), 5_000);
             });
             await Promise.race([sendPromise, timeoutPromise]);
             this._logger.log('Email sent successfully', 'Mail');
         }
         catch (error) {
             this._logger.error('Error sending email:', error);
-            throw error;
+            throw new MailDeliveryError_1.MailDeliveryError('resend', 'Failed to send email via Resend', error);
         }
     }
 }

package/src/services/strategies/SendGridDeliveryStrategy.js

@@ -6,6 +6,7 @@ const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
 const mail_1 = tslib_1.__importDefault(require("@sendgrid/mail"));
 const env_1 = require("../../env");
+const MailDeliveryError_1 = require("../../errors/MailDeliveryError");
 const DeliveryStrategyBase_1 = require("./abstracts/DeliveryStrategyBase");
 // #endregion
 /**
@@ -48,14 +49,14 @@ class SendGridDeliveryStrategy extends DeliveryStrategyBase_1.DeliveryStrategyBa
                 ...(isHtml ? { html: content } : { text: content }),
             });
             const timeoutPromise = new Promise((_resolve, reject) => {
-                setTimeout(() => reject(new Error('SendGrid send timed out after 30000ms')), 30_000);
+                setTimeout(() => reject(new Error('SendGrid send timed out after 5000ms')), 5_000);
             });
             await Promise.race([sendPromise, timeoutPromise]);
             this._logger.log('Email sent successfully', 'Mail');
         }
         catch (error) {
             this._logger.error('Error sending email:', error);
-            throw error;
+            throw new MailDeliveryError_1.MailDeliveryError('sendgrid', 'Failed to send email via SendGrid', error);
         }
     }
 }

package/src/services/strategies/SmtpDeliveryStrategy.js

@@ -5,6 +5,7 @@ exports.SmtpDeliveryStrategy = void 0;
 const common_1 = require("@nestjs/common");
 const nodemailer_1 = require("nodemailer");
 const env_1 = require("../../env");
+const MailDeliveryError_1 = require("../../errors/MailDeliveryError");
 const DeliveryStrategyBase_1 = require("./abstracts/DeliveryStrategyBase");
 // #endregion
 /**
@@ -56,14 +57,14 @@ class SmtpDeliveryStrategy extends DeliveryStrategyBase_1.DeliveryStrategyBase {
                 ...(isHtml ? { html: content } : { text: content }),
             });
             const timeoutPromise = new Promise((_resolve, reject) => {
-                setTimeout(() => reject(new Error('SMTP send timed out after 30000ms')), 30_000);
+                setTimeout(() => reject(new Error('SMTP send timed out after 5000ms')), 5_000);
             });
             await Promise.race([sendPromise, timeoutPromise]);
             this._logger.log('Email sent successfully', 'Mail');
         }
         catch (error) {
             this._logger.error('Error sending email:', error);
-            throw error;
+            throw new MailDeliveryError_1.MailDeliveryError('smtp', 'Failed to send email via SMTP', error);
         }
     }
 }