@astralibx/email-rule-engine 12.0.1 → 12.2.0

package/dist/index.d.mts

@@ -192,6 +192,11 @@ interface BeforeSendParams {
         email: string;
         name: string;
     };
+    context: {
+        ruleId: string;
+        templateId: string;
+        runId: string;
+    };
 }
 interface BeforeSendResult {
     htmlBody: string;
@@ -258,27 +263,39 @@ interface EmailRuleEngineConfig {
         onRunStart?: (info: {
             rulesCount: number;
             triggeredBy: string;
+            runId: string;
         }) => void;
         onRuleStart?: (info: {
             ruleId: string;
             ruleName: string;
             matchedCount: number;
+            templateId: string;
+            runId: string;
         }) => void;
         onSend?: (info: {
             ruleId: string;
             ruleName: string;
             email: string;
             status: 'sent' | 'error' | 'skipped' | 'invalid' | 'throttled';
+            accountId: string;
+            templateId: string;
+            runId: string;
+            subjectIndex: number;
+            bodyIndex: number;
+            failureReason?: string;
         }) => void;
         onRuleComplete?: (info: {
             ruleId: string;
             ruleName: string;
             stats: RuleRunStats;
+            templateId: string;
+            runId: string;
         }) => void;
         onRunComplete?: (info: {
             duration: number;
             totalStats: RuleRunStats;
             perRuleStats: PerRuleStats[];
+            runId: string;
         }) => void;
         beforeSend?: (params: BeforeSendParams) => Promise<BeforeSendResult>;
     };

package/dist/index.d.ts

@@ -192,6 +192,11 @@ interface BeforeSendParams {
         email: string;
         name: string;
     };
+    context: {
+        ruleId: string;
+        templateId: string;
+        runId: string;
+    };
 }
 interface BeforeSendResult {
     htmlBody: string;
@@ -258,27 +263,39 @@ interface EmailRuleEngineConfig {
         onRunStart?: (info: {
             rulesCount: number;
             triggeredBy: string;
+            runId: string;
         }) => void;
         onRuleStart?: (info: {
             ruleId: string;
             ruleName: string;
             matchedCount: number;
+            templateId: string;
+            runId: string;
         }) => void;
         onSend?: (info: {
             ruleId: string;
             ruleName: string;
             email: string;
             status: 'sent' | 'error' | 'skipped' | 'invalid' | 'throttled';
+            accountId: string;
+            templateId: string;
+            runId: string;
+            subjectIndex: number;
+            bodyIndex: number;
+            failureReason?: string;
         }) => void;
         onRuleComplete?: (info: {
             ruleId: string;
             ruleName: string;
             stats: RuleRunStats;
+            templateId: string;
+            runId: string;
         }) => void;
         onRunComplete?: (info: {
             duration: number;
             totalStats: RuleRunStats;
             perRuleStats: PerRuleStats[];
+            runId: string;
         }) => void;
         beforeSend?: (params: BeforeSendParams) => Promise<BeforeSendResult>;
     };

package/dist/index.mjs

@@ -1014,7 +1014,7 @@ var RuleRunnerService = class {
         }
         return true;
       });
-      this.config.hooks?.onRunStart?.({ rulesCount: activeRules.length, triggeredBy });
+      this.config.hooks?.onRunStart?.({ rulesCount: activeRules.length, triggeredBy, runId });
       await this.updateRunProgress(runId, {
         progress: { rulesTotal: activeRules.length, rulesCompleted: 0, sent: 0, failed: 0, skipped: 0, invalid: 0 }
       });
@@ -1103,7 +1103,7 @@ var RuleRunnerService = class {
         status: runStatus
       });
       await this.updateRunProgress(runId, { status: runStatus, currentRule: "", elapsed: Date.now() - runStartTime });
-      this.config.hooks?.onRunComplete?.({ duration: Date.now() - runStartTime, totalStats, perRuleStats });
+      this.config.hooks?.onRunComplete?.({ duration: Date.now() - runStartTime, totalStats, perRuleStats, runId });
       this.logger.info("Rule run completed", {
         triggeredBy,
         rulesProcessed: activeRules.length,
@@ -1142,7 +1142,7 @@ var RuleRunnerService = class {
     stats.matched = emailsToProcess.length;
     const ruleId = rule._id.toString();
     const templateId = rule.templateId.toString();
-    this.config.hooks?.onRuleStart?.({ ruleId, ruleName: rule.name, matchedCount: emailsToProcess.length });
+    this.config.hooks?.onRuleStart?.({ ruleId, ruleName: rule.name, matchedCount: emailsToProcess.length, templateId, runId: runId || "" });
     if (emailsToProcess.length === 0) return stats;
     const identifierResults = await processInChunks(
       emailsToProcess,
@@ -1187,7 +1187,7 @@ var RuleRunnerService = class {
         const identifier = identifierMap.get(email);
         if (!identifier) {
           stats.skipped++;
-          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "invalid" });
+          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "invalid", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "invalid email" });
           continue;
         }
         const dedupKey = identifier.id;
@@ -1195,27 +1195,27 @@ var RuleRunnerService = class {
         if (lastSend) {
           if (rule.sendOnce && !rule.resendAfterDays) {
             stats.skipped++;
-            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "send once" });
             continue;
           }
           if (rule.resendAfterDays) {
             const daysSince = (Date.now() - new Date(lastSend.sentAt).getTime()) / MS_PER_DAY;
             if (daysSince < rule.resendAfterDays) {
               stats.skipped++;
-              this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+              this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "resend too soon" });
               continue;
             }
           } else {
             stats.skipped++;
-            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "send once" });
             continue;
           }
         }
-        if (!this.checkThrottle(rule, dedupKey, email, throttleMap, throttleConfig, stats)) continue;
+        if (!this.checkThrottle(rule, dedupKey, email, throttleMap, throttleConfig, stats, templateId, runId)) continue;
         const agentSelection = await this.config.adapters.selectAgent(identifier.id, { ruleId, templateId });
         if (!agentSelection) {
           stats.skipped++;
-          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "no account available" });
           continue;
         }
         const user = { _id: identifier.id, email };
@@ -1253,6 +1253,11 @@ var RuleRunnerService = class {
                 id: dedupKey,
                 email,
                 name: ""
+              },
+              context: {
+                ruleId,
+                templateId,
+                runId: runId || ""
               }
             });
             finalHtml = modified.htmlBody;
@@ -1261,7 +1266,7 @@ var RuleRunnerService = class {
           } catch (hookErr) {
             this.logger.error(`beforeSend hook failed for email ${email}: ${hookErr.message}`);
             stats.errorCount++;
-            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error" });
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error", accountId: agentSelection.accountId, templateId, runId: runId || "", subjectIndex: si, bodyIndex: bi, failureReason: hookErr.message });
             continue;
           }
         }
@@ -1289,7 +1294,7 @@ var RuleRunnerService = class {
           lastSentDate: /* @__PURE__ */ new Date()
         });
         stats.sent++;
-        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "sent" });
+        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "sent", accountId: agentSelection.accountId, templateId, runId: runId || "", subjectIndex: si, bodyIndex: bi });
         totalProcessed++;
         if (runId && totalProcessed % 10 === 0) {
           await this.updateRunSendProgress(runId, stats);
@@ -1304,7 +1309,7 @@ var RuleRunnerService = class {
         }
       } catch (err) {
         stats.errorCount++;
-        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error" });
+        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: err.message || "unknown error" });
         this.logger.error(`Rule "${rule.name}" failed for identifier ${email}`, { error: err });
       }
     }
@@ -1327,7 +1332,7 @@ var RuleRunnerService = class {
         this.logger.info(`Rule '${rule.name}' auto-disabled \u2014 all identifiers processed`);
       }
     }
-    this.config.hooks?.onRuleComplete?.({ ruleId, ruleName: rule.name, stats });
+    this.config.hooks?.onRuleComplete?.({ ruleId, ruleName: rule.name, stats, templateId, runId: runId || "" });
     return stats;
   }
   async executeQueryMode(rule, template, throttleMap, throttleConfig, stats, runId) {
@@ -1340,7 +1345,7 @@ var RuleRunnerService = class {
       return stats;
     }
     stats.matched = users.length;
-    this.config.hooks?.onRuleStart?.({ ruleId: rule._id.toString(), ruleName: rule.name, matchedCount: users.length });
+    this.config.hooks?.onRuleStart?.({ ruleId: rule._id.toString(), ruleName: rule.name, matchedCount: users.length, templateId: rule.templateId.toString(), runId: runId || "" });
     if (users.length === 0) return stats;
     const userIds = users.map((u) => u._id?.toString()).filter(Boolean);
     const emails = users.map((u) => u.email).filter(Boolean);
@@ -1389,40 +1394,40 @@ var RuleRunnerService = class {
         const email = user.email;
         if (!userId || !email) {
           stats.skipped++;
-          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email: email || "unknown", status: "invalid" });
+          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email: email || "unknown", status: "invalid", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "invalid email" });
           continue;
         }
         const lastSend = sendMap.get(userId);
         if (lastSend) {
           if (rule.sendOnce && !rule.resendAfterDays) {
             stats.skipped++;
-            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "send once" });
             continue;
           }
           if (rule.resendAfterDays) {
             const daysSince = (Date.now() - new Date(lastSend.sentAt).getTime()) / MS_PER_DAY;
             if (daysSince < rule.resendAfterDays) {
               stats.skipped++;
-              this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+              this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "resend too soon" });
               continue;
             }
           } else {
             stats.skipped++;
-            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "send once" });
             continue;
           }
         }
         const identifier = identifierMap.get(email.toLowerCase().trim());
         if (!identifier) {
           stats.skipped++;
-          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "invalid" });
+          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "invalid", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "invalid email" });
           continue;
         }
-        if (!this.checkThrottle(rule, userId, email, throttleMap, throttleConfig, stats)) continue;
+        if (!this.checkThrottle(rule, userId, email, throttleMap, throttleConfig, stats, templateId, runId)) continue;
         const agentSelection = await this.config.adapters.selectAgent(identifier.id, { ruleId, templateId });
         if (!agentSelection) {
           stats.skipped++;
-          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "no account available" });
           continue;
         }
         const resolvedData = this.config.adapters.resolveData(user);
@@ -1459,6 +1464,11 @@ var RuleRunnerService = class {
                 id: String(userId),
                 email,
                 name: String(user.name || user.firstName || "")
+              },
+              context: {
+                ruleId,
+                templateId,
+                runId: runId || ""
               }
             });
             finalHtml = modified.htmlBody;
@@ -1467,7 +1477,7 @@ var RuleRunnerService = class {
           } catch (hookErr) {
             this.logger.error(`beforeSend hook failed for email ${email}: ${hookErr.message}`);
             stats.errorCount++;
-            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error" });
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error", accountId: agentSelection.accountId, templateId, runId: runId || "", subjectIndex: si, bodyIndex: bi, failureReason: hookErr.message });
             continue;
           }
         }
@@ -1495,7 +1505,7 @@ var RuleRunnerService = class {
           lastSentDate: /* @__PURE__ */ new Date()
         });
         stats.sent++;
-        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "sent" });
+        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "sent", accountId: agentSelection.accountId, templateId, runId: runId || "", subjectIndex: si, bodyIndex: bi });
         totalProcessed++;
         if (runId && totalProcessed % 10 === 0) {
           await this.updateRunSendProgress(runId, stats);
@@ -1510,7 +1520,7 @@ var RuleRunnerService = class {
         }
       } catch (err) {
         stats.errorCount++;
-        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email: user.email || "unknown", status: "error" });
+        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email: user.email || "unknown", status: "error", accountId: "", templateId, runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: err.message || "unknown error" });
         this.logger.error(`Rule "${rule.name}" failed for user ${user._id?.toString()}`, { error: err });
       }
     }
@@ -1518,27 +1528,27 @@ var RuleRunnerService = class {
       $set: { lastRunAt: /* @__PURE__ */ new Date(), lastRunStats: stats },
       $inc: { totalSent: stats.sent, totalSkipped: stats.skipped }
     });
-    this.config.hooks?.onRuleComplete?.({ ruleId, ruleName: rule.name, stats });
+    this.config.hooks?.onRuleComplete?.({ ruleId, ruleName: rule.name, stats, templateId, runId: runId || "" });
     return stats;
   }
-  checkThrottle(rule, userId, email, throttleMap, config, stats) {
+  checkThrottle(rule, userId, email, throttleMap, config, stats, templateId, runId) {
     if (rule.emailType === EMAIL_TYPE.Transactional || rule.bypassThrottle) return true;
     const userThrottle = throttleMap.get(userId) || { today: 0, thisWeek: 0, lastSentDate: null };
     if (userThrottle.today >= config.maxPerUserPerDay) {
       stats.skippedByThrottle++;
-      this.config.hooks?.onSend?.({ ruleId: rule._id.toString(), ruleName: rule.name, email, status: "throttled" });
+      this.config.hooks?.onSend?.({ ruleId: rule._id.toString(), ruleName: rule.name, email, status: "throttled", accountId: "", templateId: templateId || "", runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "daily throttle limit" });
       return false;
     }
     if (userThrottle.thisWeek >= config.maxPerUserPerWeek) {
       stats.skippedByThrottle++;
-      this.config.hooks?.onSend?.({ ruleId: rule._id.toString(), ruleName: rule.name, email, status: "throttled" });
+      this.config.hooks?.onSend?.({ ruleId: rule._id.toString(), ruleName: rule.name, email, status: "throttled", accountId: "", templateId: templateId || "", runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "weekly throttle limit" });
       return false;
     }
     if (userThrottle.lastSentDate) {
       const daysSinceLastSend = (Date.now() - userThrottle.lastSentDate.getTime()) / MS_PER_DAY;
       if (daysSinceLastSend < config.minGapDays) {
         stats.skippedByThrottle++;
-        this.config.hooks?.onSend?.({ ruleId: rule._id.toString(), ruleName: rule.name, email, status: "throttled" });
+        this.config.hooks?.onSend?.({ ruleId: rule._id.toString(), ruleName: rule.name, email, status: "throttled", accountId: "", templateId: templateId || "", runId: runId || "", subjectIndex: -1, bodyIndex: -1, failureReason: "min gap days" });
         return false;
       }
     }