@astralibx/email-rule-engine 12.1.0 → 12.3.0

package/README.md

@@ -113,6 +113,26 @@ See [docs/configuration.md](https://github.com/Hariprakash1997/astralib/blob/mai
 
 Reference: [API Routes](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/api-routes.md) | [Programmatic API](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/programmatic-api.md) | [Types](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/types.md) | [Constants](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/constants.md) | [Error Handling](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/error-handling.md)
 
+### Redis Key Prefix (Required for Multi-Project Deployments)
+
+> **WARNING:** If multiple projects share the same Redis server, you MUST set a unique `keyPrefix` per project. Without this, run locks, cancel flags, and progress keys will collide between projects.
+
+```typescript
+const engine = createEmailRuleEngine({
+  redis: {
+    connection: redis,
+    keyPrefix: 'myproject:', // REQUIRED if sharing Redis
+  },
+  // ...
+});
+```
+
+| Default | Risk |
+|---------|------|
+| `''` (empty) | Two projects share global keys like `email-rule-runner:lock` and `run:{id}:cancel` — Project A can cancel Project B's runs |
+
+**Always set a unique prefix** like `projectname:` when sharing Redis.
+
 > **Important:** Configure throttle settings before running rules. Default limits (1/day, 2/week) may be too restrictive. See [Throttling](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/throttling.md).
 
 ## License

package/dist/index.cjs

@@ -1022,7 +1022,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 }
       });
@@ -1111,7 +1111,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,
@@ -1150,7 +1150,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,
@@ -1195,7 +1195,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;
@@ -1203,27 +1203,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 };
@@ -1274,7 +1274,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;
           }
         }
@@ -1302,7 +1302,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);
@@ -1317,7 +1317,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 });
       }
     }
@@ -1340,7 +1340,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) {
@@ -1353,7 +1353,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);
@@ -1402,40 +1402,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);
@@ -1485,7 +1485,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;
           }
         }
@@ -1513,7 +1513,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);
@@ -1528,7 +1528,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 });
       }
     }
@@ -1536,27 +1536,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;
       }
     }