@astralibx/email-rule-engine 3.0.2 → 4.0.0

package/dist/index.mjs

@@ -3,7 +3,7 @@ import Handlebars from 'handlebars';
 import mjml2html from 'mjml';
 import { convert } from 'html-to-text';
 import { baseRedisSchema, baseDbSchema, loggerSchema, AlxError } from '@astralibx/core';
-import crypto from 'crypto';
+import crypto2 from 'crypto';
 import { Router } from 'express';
 import { z } from 'zod';
 
@@ -68,9 +68,9 @@ function createEmailTemplateSchema(platformValues, audienceValues, categoryValue
         required: true,
         ...platformValues ? { enum: platformValues } : {}
       },
-      subject: { type: String, required: true },
-      body: { type: String, required: true },
       textBody: String,
+      subjects: { type: [{ type: String }], required: true, validate: [(v) => v.length >= 1, "At least one subject is required"] },
+      bodies: { type: [{ type: String }], required: true, validate: [(v) => v.length >= 1, "At least one body is required"] },
       variables: [{ type: String }],
       version: { type: Number, default: 1 },
       isActive: { type: Boolean, default: true, index: true }
@@ -102,9 +102,9 @@ function createEmailTemplateSchema(platformValues, audienceValues, categoryValue
             category: input.category,
             audience: input.audience,
             platform: input.platform,
-            subject: input.subject,
-            body: input.body,
             textBody: input.textBody,
+            subjects: input.subjects,
+            bodies: input.bodies,
             variables: input.variables || [],
             version: 1,
             isActive: true
@@ -124,13 +124,14 @@ function createEmailRuleSchema(platformValues, audienceValues, collectionPrefix)
     value: { type: Schema.Types.Mixed }
   }, { _id: false });
   const RuleTargetSchema = new Schema({
-    role: { type: String, enum: audienceValues || Object.values(TEMPLATE_AUDIENCE), required: true },
+    mode: { type: String, enum: ["query", "list"], required: true },
+    role: { type: String, enum: audienceValues || Object.values(TEMPLATE_AUDIENCE) },
     platform: {
       type: String,
-      required: true,
       ...platformValues ? { enum: platformValues } : {}
     },
-    conditions: [RuleConditionSchema]
+    conditions: [RuleConditionSchema],
+    identifiers: [{ type: String }]
   }, { _id: false });
   const RuleRunStatsSchema = new Schema({
     matched: { type: Number, default: 0 },
@@ -207,6 +208,8 @@ function createEmailRuleSendSchema(collectionPrefix) {
       accountId: { type: String },
       senderName: { type: String },
       subject: { type: String },
+      subjectIndex: { type: Number },
+      bodyIndex: { type: Number },
       failureReason: { type: String }
     },
     {
@@ -259,7 +262,9 @@ function createEmailRuleRunLogSchema(collectionPrefix) {
   }, { _id: false });
   const schema = new Schema(
     {
+      runId: { type: String, index: true },
       runAt: { type: Date, required: true, default: () => /* @__PURE__ */ new Date() },
+      status: { type: String, enum: ["completed", "cancelled", "failed"], default: "completed" },
       triggeredBy: { type: String, enum: Object.values(RUN_TRIGGER), required: true },
       duration: { type: Number, required: true },
       rulesProcessed: { type: Number, required: true },
@@ -429,6 +434,16 @@ var TemplateRenderService = class {
     const textBodyFn = textBody ? Handlebars.compile(textBody, { strict: true }) : void 0;
     return { subjectFn, bodyFn, textBodyFn };
   }
+  compileBatchVariants(subjects, bodies, textBody) {
+    const subjectFns = subjects.map((s) => Handlebars.compile(s, { strict: true }));
+    const bodyFns = bodies.map((b) => {
+      const mjmlSource = wrapInMjml(b);
+      const htmlWithHandlebars = compileMjml(mjmlSource);
+      return Handlebars.compile(htmlWithHandlebars, { strict: true });
+    });
+    const textBodyFn = textBody ? Handlebars.compile(textBody, { strict: true }) : void 0;
+    return { subjectFns, bodyFns, textBodyFn };
+  }
   renderFromCompiled(compiled, data) {
     const subject = compiled.subjectFn(data);
     const html = compiled.bodyFn(data);
@@ -438,6 +453,9 @@ var TemplateRenderService = class {
   renderPreview(subject, body, data, textBody) {
     return this.renderSingle(subject, body, data, textBody);
   }
+  htmlToText(html) {
+    return htmlToPlainText(html);
+  }
   extractVariables(template) {
     const regex = /\{\{(?!#|\/|!|>)([^}]+)\}\}/g;
     const variables = /* @__PURE__ */ new Set();
@@ -533,9 +551,9 @@ var UPDATEABLE_FIELDS = /* @__PURE__ */ new Set([
   "category",
   "audience",
   "platform",
-  "subject",
-  "body",
   "textBody",
+  "subjects",
+  "bodies",
   "variables",
   "isActive"
 ]);
@@ -568,35 +586,49 @@ var TemplateService = class {
     if (existing) {
       throw new DuplicateSlugError(slug);
     }
-    const validation = this.renderService.validateTemplate(input.body);
-    if (!validation.valid) {
-      throw new TemplateSyntaxError(`Template validation failed: ${validation.errors.join("; ")}`, validation.errors);
+    const { subjects, bodies } = input;
+    if (subjects.length === 0) throw new TemplateSyntaxError("At least one subject is required", ["At least one subject is required"]);
+    if (bodies.length === 0) throw new TemplateSyntaxError("At least one body is required", ["At least one body is required"]);
+    for (const b of bodies) {
+      const validation = this.renderService.validateTemplate(b);
+      if (!validation.valid) {
+        throw new TemplateSyntaxError(`Template validation failed: ${validation.errors.join("; ")}`, validation.errors);
+      }
     }
-    const variables = input.variables || this.renderService.extractVariables(
-      `${input.subject} ${input.body} ${input.textBody || ""}`
-    );
+    const allContent = [...subjects, ...bodies, input.textBody || ""].join(" ");
+    const variables = input.variables || this.renderService.extractVariables(allContent);
     return this.EmailTemplate.createTemplate({
       ...input,
       slug,
+      subjects,
+      bodies,
       variables
     });
   }
   async update(id, input) {
     const template = await this.EmailTemplate.findById(id);
     if (!template) return null;
-    if (input.body) {
-      const validation = this.renderService.validateTemplate(input.body);
-      if (!validation.valid) {
-        throw new TemplateSyntaxError(`Template validation failed: ${validation.errors.join("; ")}`, validation.errors);
+    if (input.subjects && input.subjects.length === 0) {
+      throw new TemplateSyntaxError("At least one subject is required", ["At least one subject is required"]);
+    }
+    if (input.bodies && input.bodies.length === 0) {
+      throw new TemplateSyntaxError("At least one body is required", ["At least one body is required"]);
+    }
+    const bodiesToValidate = input.bodies || null;
+    if (bodiesToValidate) {
+      for (const b of bodiesToValidate) {
+        const validation = this.renderService.validateTemplate(b);
+        if (!validation.valid) {
+          throw new TemplateSyntaxError(`Template validation failed: ${validation.errors.join("; ")}`, validation.errors);
+        }
       }
     }
-    if (input.body || input.subject || input.textBody) {
-      const subject = input.subject ?? template.subject;
-      const body = input.body ?? template.body;
+    if (input.textBody || input.subjects || input.bodies) {
+      const subjects = input.subjects ?? template.subjects;
+      const bodies = input.bodies ?? template.bodies;
       const textBody = input.textBody ?? template.textBody;
-      input.variables = this.renderService.extractVariables(
-        `${subject} ${body} ${textBody || ""}`
-      );
+      const allContent = [...subjects, ...bodies, textBody || ""].join(" ");
+      input.variables = this.renderService.extractVariables(allContent);
     }
     const setFields = {};
     for (const [key, value] of Object.entries(input)) {
@@ -605,7 +637,7 @@ var TemplateService = class {
       }
     }
     const update = { $set: setFields };
-    if (input.body || input.subject || input.textBody) {
+    if (input.textBody || input.subjects || input.bodies) {
       update["$inc"] = { version: 1 };
     }
     return this.EmailTemplate.findByIdAndUpdate(
@@ -629,8 +661,8 @@ var TemplateService = class {
     const template = await this.EmailTemplate.findById(id);
     if (!template) return null;
     return this.renderService.renderPreview(
-      template.subject,
-      template.body,
+      template.subjects[0],
+      template.bodies[0],
       sampleData,
       template.textBody
     );
@@ -652,8 +684,8 @@ var TemplateService = class {
       return { success: false, error: "Template not found" };
     }
     const rendered = this.renderService.renderSingle(
-      template.subject,
-      template.body,
+      template.subjects[0],
+      template.bodies[0],
       sampleData,
       template.textBody
     );
@@ -672,6 +704,9 @@ var TemplateService = class {
 };
 
 // src/services/rule.service.ts
+function isQueryTarget(target) {
+  return !target.mode || target.mode === "query";
+}
 var UPDATEABLE_FIELDS2 = /* @__PURE__ */ new Set([
   "name",
   "description",
@@ -725,13 +760,22 @@ var RuleService = class {
     if (!template) {
       throw new TemplateNotFoundError(input.templateId);
     }
-    const compatError = validateRuleTemplateCompat(
-      input.target.role,
-      input.target.platform,
-      template
-    );
-    if (compatError) {
-      throw new RuleTemplateIncompatibleError(compatError);
+    if (isQueryTarget(input.target)) {
+      if (!input.target.role || !input.target.platform) {
+        throw new RuleTemplateIncompatibleError("target.role and target.platform are required for query mode, validation failed");
+      }
+      const compatError = validateRuleTemplateCompat(
+        input.target.role,
+        input.target.platform,
+        template
+      );
+      if (compatError) {
+        throw new RuleTemplateIncompatibleError(compatError);
+      }
+    } else {
+      if (!input.target.identifiers || input.target.identifiers.length === 0) {
+        throw new RuleTemplateIncompatibleError("target.identifiers must be a non-empty array for list mode, validation failed");
+      }
     }
     return this.EmailRule.createRule(input);
   }
@@ -739,14 +783,25 @@ var RuleService = class {
     const rule = await this.EmailRule.findById(id);
     if (!rule) return null;
     const templateId = input.templateId ?? rule.templateId.toString();
-    const targetRole = input.target?.role ?? rule.target.role;
-    const targetPlatform = input.target?.platform ?? rule.target.platform;
-    if (input.templateId || input.target) {
+    if (input.target) {
+      if (isQueryTarget(input.target)) {
+        if (!input.target.role || !input.target.platform) {
+          throw new RuleTemplateIncompatibleError("target.role and target.platform are required for query mode, validation failed");
+        }
+      } else {
+        if (!input.target.identifiers || input.target.identifiers.length === 0) {
+          throw new RuleTemplateIncompatibleError("target.identifiers must be a non-empty array for list mode, validation failed");
+        }
+      }
+    }
+    const effectiveTarget = input.target ?? rule.target;
+    if ((input.templateId || input.target) && isQueryTarget(effectiveTarget)) {
+      const qt = effectiveTarget;
       const template = await this.EmailTemplate.findById(templateId);
       if (!template) {
         throw new TemplateNotFoundError(templateId);
       }
-      const compatError = validateRuleTemplateCompat(targetRole, targetPlatform, template);
+      const compatError = validateRuleTemplateCompat(qt.role, qt.platform, template);
       if (compatError) {
         throw new RuleTemplateIncompatibleError(compatError);
       }
@@ -795,6 +850,11 @@ var RuleService = class {
     if (!rule) {
       throw new RuleNotFoundError(id);
     }
+    const target = rule.target;
+    if (target.mode === "list") {
+      const identifiers = target.identifiers || [];
+      return { matchedCount: identifiers.length, ruleId: id };
+    }
     const users = await this.config.adapters.queryUsers(rule.target, 5e4);
     return { matchedCount: users.length, ruleId: id };
   }
@@ -811,7 +871,7 @@ var RedisLock = class {
   }
   lockValue = "";
   async acquire() {
-    this.lockValue = crypto.randomUUID();
+    this.lockValue = crypto2.randomUUID();
     const result = await this.redis.set(this.lockKey, this.lockValue, "PX", this.ttlMs, "NX");
     return result === "OK";
   }
@@ -824,8 +884,6 @@ var RedisLock = class {
     }
   }
 };
-
-// src/services/rule-runner.service.ts
 var MS_PER_DAY = 864e5;
 var DEFAULT_LOCK_TTL_MS = 30 * 60 * 1e3;
 var IDENTIFIER_CHUNK_SIZE = 50;
@@ -854,11 +912,12 @@ var RuleRunnerService = class {
     this.EmailRuleRunLog = EmailRuleRunLog;
     this.EmailThrottleConfig = EmailThrottleConfig;
     this.config = config;
-    const keyPrefix = config.redis.keyPrefix || "";
+    this.keyPrefix = config.redis.keyPrefix || "";
+    this.redis = config.redis.connection;
     const lockTTL = config.options?.lockTTLMs || DEFAULT_LOCK_TTL_MS;
     this.lock = new RedisLock(
-      config.redis.connection,
-      `${keyPrefix}email-rule-runner:lock`,
+      this.redis,
+      `${this.keyPrefix}email-rule-runner:lock`,
       lockTTL,
       config.logger
     );
@@ -867,7 +926,11 @@ var RuleRunnerService = class {
   templateRenderer = new TemplateRenderService();
   lock;
   logger;
-  async runAllRules(triggeredBy = RUN_TRIGGER.Cron) {
+  redis;
+  keyPrefix;
+  async runAllRules(triggeredBy = RUN_TRIGGER.Cron, runId) {
+    if (!runId) runId = crypto2.randomUUID();
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     if (this.config.options?.sendWindow) {
       const { startHour, endHour, timezone } = this.config.options.sendWindow;
       const now = /* @__PURE__ */ new Date();
@@ -875,30 +938,45 @@ var RuleRunnerService = class {
       const currentHour = parseInt(formatter.format(now), 10);
       if (currentHour < startHour || currentHour >= endHour) {
         this.logger.info("Outside send window, skipping run", { currentHour, startHour, endHour, timezone });
-        return;
+        return { runId };
       }
     }
     const lockAcquired = await this.lock.acquire();
     if (!lockAcquired) {
       this.logger.warn("Rule runner already executing, skipping");
-      return;
+      return { runId };
     }
     const runStartTime = Date.now();
+    await this.updateRunProgress(runId, {
+      runId,
+      status: "running",
+      currentRule: "",
+      progress: { rulesTotal: 0, rulesCompleted: 0, sent: 0, failed: 0, skipped: 0, invalid: 0 },
+      startedAt,
+      elapsed: 0
+    });
+    let runStatus = "completed";
     try {
       const throttleConfig = await this.EmailThrottleConfig.getConfig();
       const activeRules = await this.EmailRule.findActive();
       this.config.hooks?.onRunStart?.({ rulesCount: activeRules.length, triggeredBy });
+      await this.updateRunProgress(runId, {
+        progress: { rulesTotal: activeRules.length, rulesCompleted: 0, sent: 0, failed: 0, skipped: 0, invalid: 0 }
+      });
       if (activeRules.length === 0) {
         this.logger.info("No active rules to process");
         await this.EmailRuleRunLog.create({
+          runId,
           runAt: /* @__PURE__ */ new Date(),
           triggeredBy,
           duration: Date.now() - runStartTime,
           rulesProcessed: 0,
           totalStats: { matched: 0, sent: 0, skipped: 0, skippedByThrottle: 0, errors: 0 },
-          perRuleStats: []
+          perRuleStats: [],
+          status: "completed"
         });
-        return;
+        await this.updateRunProgress(runId, { status: "completed", elapsed: Date.now() - runStartTime });
+        return { runId };
       }
       const templateIds = [...new Set(activeRules.map((r) => r.templateId.toString()))];
       const templates = await this.EmailTemplate.find({ _id: { $in: templateIds } }).lean();
@@ -911,13 +989,43 @@ var RuleRunnerService = class {
       }).lean();
       const throttleMap = this.buildThrottleMap(recentSends);
       const perRuleStats = [];
-      for (const rule of activeRules) {
-        const stats = await this.executeRule(rule, throttleMap, throttleConfig, templateMap);
+      let totalSent = 0;
+      let totalFailed = 0;
+      let totalSkipped = 0;
+      let totalInvalid = 0;
+      for (let ri = 0; ri < activeRules.length; ri++) {
+        const rule = activeRules[ri];
+        const cancelKey = `${this.keyPrefix}run:${runId}:cancel`;
+        const cancelled = await this.redis.exists(cancelKey);
+        if (cancelled) {
+          runStatus = "cancelled";
+          break;
+        }
+        await this.updateRunProgress(runId, {
+          currentRule: rule.name,
+          elapsed: Date.now() - runStartTime
+        });
+        const stats = await this.executeRule(rule, throttleMap, throttleConfig, templateMap, runId);
+        totalSent += stats.sent;
+        totalFailed += stats.errors;
+        totalSkipped += stats.skipped + stats.skippedByThrottle;
+        totalInvalid += stats.matched - stats.sent - stats.skipped - stats.skippedByThrottle - stats.errors;
         perRuleStats.push({
           ruleId: rule._id.toString(),
           ruleName: rule.name,
           ...stats
         });
+        await this.updateRunProgress(runId, {
+          progress: {
+            rulesTotal: activeRules.length,
+            rulesCompleted: ri + 1,
+            sent: totalSent,
+            failed: totalFailed,
+            skipped: totalSkipped,
+            invalid: totalInvalid < 0 ? 0 : totalInvalid
+          },
+          elapsed: Date.now() - runStartTime
+        });
       }
       const totalStats = perRuleStats.reduce(
         (acc, s) => ({
@@ -930,13 +1038,16 @@ var RuleRunnerService = class {
         { matched: 0, sent: 0, skipped: 0, skippedByThrottle: 0, errors: 0 }
       );
       await this.EmailRuleRunLog.create({
+        runId,
         runAt: /* @__PURE__ */ new Date(),
         triggeredBy,
         duration: Date.now() - runStartTime,
         rulesProcessed: activeRules.length,
         totalStats,
-        perRuleStats
+        perRuleStats,
+        status: runStatus
       });
+      await this.updateRunProgress(runId, { status: runStatus, currentRule: "", elapsed: Date.now() - runStartTime });
       this.config.hooks?.onRunComplete?.({ duration: Date.now() - runStartTime, totalStats, perRuleStats });
       this.logger.info("Rule run completed", {
         triggeredBy,
@@ -945,11 +1056,16 @@ var RuleRunnerService = class {
         totalSkipped: totalStats.skipped,
         duration: Date.now() - runStartTime
       });
+    } catch (err) {
+      runStatus = "failed";
+      await this.updateRunProgress(runId, { status: "failed", elapsed: Date.now() - runStartTime });
+      throw err;
     } finally {
       await this.lock.release();
     }
+    return { runId };
   }
-  async executeRule(rule, throttleMap, throttleConfig, templateMap) {
+  async executeRule(rule, throttleMap, throttleConfig, templateMap, runId) {
     const stats = { matched: 0, sent: 0, skipped: 0, skippedByThrottle: 0, errors: 0 };
     const template = templateMap?.get(rule.templateId.toString()) ?? await this.EmailTemplate.findById(rule.templateId);
     if (!template) {
@@ -957,6 +1073,182 @@ var RuleRunnerService = class {
       stats.errors = 1;
       return stats;
     }
+    const isListMode = rule.target?.mode === "list";
+    if (isListMode) {
+      return this.executeListMode(rule, template, throttleMap, throttleConfig, stats, runId);
+    }
+    return this.executeQueryMode(rule, template, throttleMap, throttleConfig, stats, runId);
+  }
+  async executeListMode(rule, template, throttleMap, throttleConfig, stats, runId) {
+    const rawIdentifiers = rule.target.identifiers || [];
+    const uniqueEmails = [...new Set(rawIdentifiers.map((e) => e.toLowerCase().trim()).filter(Boolean))];
+    const limit = rule.maxPerRun || this.config.options?.defaultMaxPerRun || 500;
+    const emailsToProcess = uniqueEmails.slice(0, limit);
+    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 });
+    if (emailsToProcess.length === 0) return stats;
+    const identifierResults = await processInChunks(
+      emailsToProcess,
+      async (email) => {
+        const result = await this.config.adapters.findIdentifier(email);
+        return result ? { email, ...result } : null;
+      },
+      IDENTIFIER_CHUNK_SIZE
+    );
+    const identifierMap = /* @__PURE__ */ new Map();
+    for (const result of identifierResults) {
+      if (result) {
+        identifierMap.set(result.email, { id: result.id, contactId: result.contactId });
+      }
+    }
+    const validEmails = emailsToProcess.filter((e) => identifierMap.has(e));
+    const identifierIds = validEmails.map((e) => identifierMap.get(e).id);
+    const allRuleSends = await this.EmailRuleSend.find({ ruleId: rule._id, userId: { $in: identifierIds } }).sort({ sentAt: -1 }).lean();
+    const sendMap = /* @__PURE__ */ new Map();
+    for (const send of allRuleSends) {
+      const uid = send.userId.toString();
+      if (!sendMap.has(uid)) {
+        sendMap.set(uid, send);
+      }
+    }
+    const compiledVariants = this.templateRenderer.compileBatchVariants(
+      template.subjects,
+      template.bodies,
+      template.textBody
+    );
+    let totalProcessed = 0;
+    for (let i = 0; i < emailsToProcess.length; i++) {
+      const email = emailsToProcess[i];
+      if (runId && i % 10 === 0) {
+        const cancelKey = `${this.keyPrefix}run:${runId}:cancel`;
+        const cancelled = await this.redis.exists(cancelKey);
+        if (cancelled) break;
+      }
+      try {
+        const identifier = identifierMap.get(email);
+        if (!identifier) {
+          stats.skipped++;
+          this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "invalid" });
+          continue;
+        }
+        const dedupKey = identifier.id;
+        const lastSend = sendMap.get(dedupKey);
+        if (lastSend) {
+          if (rule.sendOnce && !rule.resendAfterDays) {
+            stats.skipped++;
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+            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" });
+              continue;
+            }
+          } else {
+            stats.skipped++;
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "skipped" });
+            continue;
+          }
+        }
+        if (!this.checkThrottle(rule, dedupKey, email, throttleMap, throttleConfig, stats)) 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" });
+          continue;
+        }
+        const user = { _id: identifier.id, email };
+        const templateData = this.config.adapters.resolveData(user);
+        const si = Math.floor(Math.random() * compiledVariants.subjectFns.length);
+        const bi = Math.floor(Math.random() * compiledVariants.bodyFns.length);
+        const renderedSubject = compiledVariants.subjectFns[si](templateData);
+        const renderedHtml = compiledVariants.bodyFns[bi](templateData);
+        const renderedText = compiledVariants.textBodyFn ? compiledVariants.textBodyFn(templateData) : this.templateRenderer.htmlToText(renderedHtml);
+        let finalHtml = renderedHtml;
+        let finalText = renderedText;
+        let finalSubject = renderedSubject;
+        if (this.config.hooks?.beforeSend) {
+          try {
+            const modified = await this.config.hooks.beforeSend({
+              htmlBody: finalHtml,
+              textBody: finalText,
+              subject: finalSubject,
+              account: {
+                id: agentSelection.accountId,
+                email: agentSelection.email,
+                metadata: agentSelection.metadata
+              },
+              user: {
+                id: dedupKey,
+                email,
+                name: ""
+              }
+            });
+            finalHtml = modified.htmlBody;
+            finalText = modified.textBody;
+            finalSubject = modified.subject;
+          } catch (hookErr) {
+            this.logger.error(`beforeSend hook failed for email ${email}: ${hookErr.message}`);
+            stats.errors++;
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error" });
+            continue;
+          }
+        }
+        await this.config.adapters.sendEmail({
+          identifierId: identifier.id,
+          contactId: identifier.contactId,
+          accountId: agentSelection.accountId,
+          subject: finalSubject,
+          htmlBody: finalHtml,
+          textBody: finalText,
+          ruleId,
+          autoApprove: rule.autoApprove ?? true
+        });
+        await this.EmailRuleSend.logSend(
+          ruleId,
+          dedupKey,
+          identifier.id,
+          void 0,
+          { status: "sent", accountId: agentSelection.accountId, subject: finalSubject, subjectIndex: si, bodyIndex: bi }
+        );
+        const current = throttleMap.get(dedupKey) || { today: 0, thisWeek: 0, lastSentDate: null };
+        throttleMap.set(dedupKey, {
+          today: current.today + 1,
+          thisWeek: current.thisWeek + 1,
+          lastSentDate: /* @__PURE__ */ new Date()
+        });
+        stats.sent++;
+        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "sent" });
+        totalProcessed++;
+        if (runId && totalProcessed % 10 === 0) {
+          await this.updateRunSendProgress(runId, stats);
+        }
+        if (i < emailsToProcess.length - 1) {
+          const delayMs = this.config.options?.delayBetweenSendsMs || 0;
+          const jitterMs = this.config.options?.jitterMs || 0;
+          if (delayMs > 0 || jitterMs > 0) {
+            const totalDelay = delayMs + Math.floor(Math.random() * (jitterMs + 1));
+            if (totalDelay > 0) await new Promise((resolve) => setTimeout(resolve, totalDelay));
+          }
+        }
+      } catch (err) {
+        stats.errors++;
+        this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error" });
+        this.logger.error(`Rule "${rule.name}" failed for identifier ${email}`, { error: err });
+      }
+    }
+    await this.EmailRule.findByIdAndUpdate(rule._id, {
+      $set: { lastRunAt: /* @__PURE__ */ new Date(), lastRunStats: stats },
+      $inc: { totalSent: stats.sent, totalSkipped: stats.skipped }
+    });
+    this.config.hooks?.onRuleComplete?.({ ruleId, ruleName: rule.name, stats });
+    return stats;
+  }
+  async executeQueryMode(rule, template, throttleMap, throttleConfig, stats, runId) {
     let users;
     try {
       users = await this.config.adapters.queryUsers(rule.target, rule.maxPerRun || this.config.options?.defaultMaxPerRun || 500);
@@ -993,15 +1285,21 @@ var RuleRunnerService = class {
         identifierMap.set(result.email, { id: result.id, contactId: result.contactId });
       }
     }
-    const compiled = this.templateRenderer.compileBatch(
-      template.subject,
-      template.body,
+    const compiledVariants = this.templateRenderer.compileBatchVariants(
+      template.subjects,
+      template.bodies,
       template.textBody
     );
     const ruleId = rule._id.toString();
     const templateId = rule.templateId.toString();
+    let totalProcessed = 0;
     for (let i = 0; i < users.length; i++) {
       const user = users[i];
+      if (runId && i % 10 === 0) {
+        const cancelKey = `${this.keyPrefix}run:${runId}:cancel`;
+        const cancelled = await this.redis.exists(cancelKey);
+        if (cancelled) break;
+      }
       try {
         const userId = user._id?.toString();
         const email = user.email;
@@ -1044,14 +1342,48 @@ var RuleRunnerService = class {
           continue;
         }
         const templateData = this.config.adapters.resolveData(user);
-        const rendered = this.templateRenderer.renderFromCompiled(compiled, templateData);
+        const si = Math.floor(Math.random() * compiledVariants.subjectFns.length);
+        const bi = Math.floor(Math.random() * compiledVariants.bodyFns.length);
+        const renderedSubject = compiledVariants.subjectFns[si](templateData);
+        const renderedHtml = compiledVariants.bodyFns[bi](templateData);
+        const renderedText = compiledVariants.textBodyFn ? compiledVariants.textBodyFn(templateData) : this.templateRenderer.htmlToText(renderedHtml);
+        let finalHtml = renderedHtml;
+        let finalText = renderedText;
+        let finalSubject = renderedSubject;
+        if (this.config.hooks?.beforeSend) {
+          try {
+            const modified = await this.config.hooks.beforeSend({
+              htmlBody: finalHtml,
+              textBody: finalText,
+              subject: finalSubject,
+              account: {
+                id: agentSelection.accountId,
+                email: agentSelection.email,
+                metadata: agentSelection.metadata
+              },
+              user: {
+                id: String(userId),
+                email,
+                name: String(user.name || user.firstName || "")
+              }
+            });
+            finalHtml = modified.htmlBody;
+            finalText = modified.textBody;
+            finalSubject = modified.subject;
+          } catch (hookErr) {
+            this.logger.error(`beforeSend hook failed for email ${email}: ${hookErr.message}`);
+            stats.errors++;
+            this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "error" });
+            continue;
+          }
+        }
         await this.config.adapters.sendEmail({
           identifierId: identifier.id,
           contactId: identifier.contactId,
           accountId: agentSelection.accountId,
-          subject: rendered.subject,
-          htmlBody: rendered.html,
-          textBody: rendered.text,
+          subject: finalSubject,
+          htmlBody: finalHtml,
+          textBody: finalText,
           ruleId,
           autoApprove: rule.autoApprove ?? true
         });
@@ -1060,7 +1392,7 @@ var RuleRunnerService = class {
           userId,
           identifier.id,
           void 0,
-          { status: "sent", accountId: agentSelection.accountId, subject: rendered.subject }
+          { status: "sent", accountId: agentSelection.accountId, subject: finalSubject, subjectIndex: si, bodyIndex: bi }
         );
         const current = throttleMap.get(userId) || { today: 0, thisWeek: 0, lastSentDate: null };
         throttleMap.set(userId, {
@@ -1070,6 +1402,10 @@ var RuleRunnerService = class {
         });
         stats.sent++;
         this.config.hooks?.onSend?.({ ruleId, ruleName: rule.name, email, status: "sent" });
+        totalProcessed++;
+        if (runId && totalProcessed % 10 === 0) {
+          await this.updateRunSendProgress(runId, stats);
+        }
         if (i < users.length - 1) {
           const delayMs = this.config.options?.delayBetweenSendsMs || 0;
           const jitterMs = this.config.options?.jitterMs || 0;
@@ -1149,6 +1485,74 @@ var RuleRunnerService = class {
     todayStart.setHours(0, 0, 0, 0);
     return todayStart;
   }
+  async updateRunProgress(runId, data) {
+    const key = `${this.keyPrefix}run:${runId}:progress`;
+    const flat = [];
+    for (const [k, v] of Object.entries(data)) {
+      if (typeof v === "object" && v !== null) {
+        flat.push(k, JSON.stringify(v));
+      } else {
+        flat.push(k, String(v));
+      }
+    }
+    if (flat.length > 0) {
+      await this.redis.hset(key, ...flat);
+      await this.redis.expire(key, 3600);
+    }
+  }
+  async updateRunSendProgress(runId, stats) {
+    const key = `${this.keyPrefix}run:${runId}:progress`;
+    const existing = await this.redis.hget(key, "progress");
+    let progress = { rulesTotal: 0, rulesCompleted: 0, sent: 0, failed: 0, skipped: 0, invalid: 0 };
+    if (existing) {
+      try {
+        progress = JSON.parse(existing);
+      } catch {
+      }
+    }
+    progress.sent = stats.sent;
+    progress.failed = stats.errors;
+    progress.skipped = stats.skipped + stats.skippedByThrottle;
+    await this.redis.hset(key, "progress", JSON.stringify(progress));
+    await this.redis.expire(key, 3600);
+  }
+  async getStatus(runId) {
+    const key = `${this.keyPrefix}run:${runId}:progress`;
+    const data = await this.redis.hgetall(key);
+    if (!data || Object.keys(data).length === 0) return null;
+    let progress = { rulesTotal: 0, rulesCompleted: 0, sent: 0, failed: 0, skipped: 0, invalid: 0 };
+    if (data.progress) {
+      try {
+        progress = JSON.parse(data.progress);
+      } catch {
+      }
+    }
+    return {
+      runId: data.runId || runId,
+      status: data.status || "running",
+      currentRule: data.currentRule || "",
+      progress,
+      startedAt: data.startedAt || "",
+      elapsed: parseInt(data.elapsed || "0", 10)
+    };
+  }
+  async cancel(runId) {
+    const progressKey = `${this.keyPrefix}run:${runId}:progress`;
+    const exists = await this.redis.exists(progressKey);
+    if (!exists) return { ok: false };
+    const cancelKey = `${this.keyPrefix}run:${runId}:cancel`;
+    await this.redis.set(cancelKey, "1", "EX", 3600);
+    return { ok: true };
+  }
+  trigger(triggeredBy) {
+    const runId = crypto2.randomUUID();
+    this.runAllRules(triggeredBy || RUN_TRIGGER.Manual, runId).catch((err) => {
+      this.logger.error("Background rule run failed", { error: err, runId });
+      this.updateRunProgress(runId, { status: "failed" }).catch(() => {
+      });
+    });
+    return { runId };
+  }
   buildThrottleMap(recentSends) {
     const map = /* @__PURE__ */ new Map();
     const todayStart = this.getTodayStart();
@@ -1217,9 +1621,9 @@ function createTemplateController(templateService, options) {
   }
   async function create(req, res) {
     try {
-      const { name, subject, body, category, audience, platform } = req.body;
-      if (!name || !subject || !body || !category || !audience || !platform) {
-        return res.status(400).json({ success: false, error: "name, subject, body, category, audience, and platform are required" });
+      const { name, subjects, bodies, category, audience, platform } = req.body;
+      if (!name || !subjects || subjects.length === 0 || !bodies || bodies.length === 0 || !category || !audience || !platform) {
+        return res.status(400).json({ success: false, error: "name, subjects, bodies, category, audience, and platform are required" });
       }
       if (!isValidValue(validCategories, category)) {
         return res.status(400).json({ success: false, error: `Invalid category. Must be one of: ${validCategories.join(", ")}` });
@@ -1371,14 +1775,21 @@ function createRuleController(ruleService, options) {
       if (!name || !target || !templateId) {
         return res.status(400).json({ success: false, error: "name, target, and templateId are required" });
       }
-      if (!target.role || !isValidValue2(validAudiences, target.role)) {
-        return res.status(400).json({ success: false, error: `Invalid target.role. Must be one of: ${validAudiences.join(", ")}` });
-      }
-      if (platformValues && !platformValues.includes(target.platform)) {
-        return res.status(400).json({ success: false, error: `Invalid target.platform. Must be one of: ${platformValues.join(", ")}` });
-      }
-      if (!Array.isArray(target.conditions)) {
-        return res.status(400).json({ success: false, error: "target.conditions must be an array" });
+      const mode = target.mode || "query";
+      if (mode === "list") {
+        if (!Array.isArray(target.identifiers) || target.identifiers.length === 0) {
+          return res.status(400).json({ success: false, error: "target.identifiers must be a non-empty array for list mode" });
+        }
+      } else {
+        if (!target.role || !isValidValue2(validAudiences, target.role)) {
+          return res.status(400).json({ success: false, error: `Invalid target.role. Must be one of: ${validAudiences.join(", ")}` });
+        }
+        if (platformValues && !platformValues.includes(target.platform)) {
+          return res.status(400).json({ success: false, error: `Invalid target.platform. Must be one of: ${platformValues.join(", ")}` });
+        }
+        if (!Array.isArray(target.conditions)) {
+          return res.status(400).json({ success: false, error: "target.conditions must be an array" });
+        }
       }
       if (req.body.emailType && !isValidValue2(validEmailTypes, req.body.emailType)) {
         return res.status(400).json({ success: false, error: `Invalid emailType. Must be one of: ${validEmailTypes.join(", ")}` });
@@ -1393,14 +1804,23 @@ function createRuleController(ruleService, options) {
   async function update(req, res) {
     try {
       const { target, emailType } = req.body;
-      if (target?.role && !isValidValue2(validAudiences, target.role)) {
-        return res.status(400).json({ success: false, error: `Invalid target.role. Must be one of: ${validAudiences.join(", ")}` });
-      }
-      if (target?.platform && platformValues && !platformValues.includes(target.platform)) {
-        return res.status(400).json({ success: false, error: `Invalid target.platform. Must be one of: ${platformValues.join(", ")}` });
-      }
-      if (target?.conditions && !Array.isArray(target.conditions)) {
-        return res.status(400).json({ success: false, error: "target.conditions must be an array" });
+      if (target) {
+        const mode = target.mode || "query";
+        if (mode === "list") {
+          if (target.identifiers && (!Array.isArray(target.identifiers) || target.identifiers.length === 0)) {
+            return res.status(400).json({ success: false, error: "target.identifiers must be a non-empty array for list mode" });
+          }
+        } else {
+          if (target.role && !isValidValue2(validAudiences, target.role)) {
+            return res.status(400).json({ success: false, error: `Invalid target.role. Must be one of: ${validAudiences.join(", ")}` });
+          }
+          if (target.platform && platformValues && !platformValues.includes(target.platform)) {
+            return res.status(400).json({ success: false, error: `Invalid target.platform. Must be one of: ${platformValues.join(", ")}` });
+          }
+          if (target.conditions && !Array.isArray(target.conditions)) {
+            return res.status(400).json({ success: false, error: "target.conditions must be an array" });
+          }
+        }
       }
       if (emailType && !isValidValue2(validEmailTypes, emailType)) {
         return res.status(400).json({ success: false, error: `Invalid emailType. Must be one of: ${validEmailTypes.join(", ")}` });
@@ -1461,23 +1881,10 @@ function createRuleController(ruleService, options) {
   }
   return { list, getById, create, update, remove, toggleActive, dryRun, runHistory };
 }
-
-// src/controllers/runner.controller.ts
-var defaultLogger2 = {
-  info: () => {
-  },
-  warn: () => {
-  },
-  error: () => {
-  }
-};
 function createRunnerController(runnerService, EmailRuleRunLog, logger) {
-  const log = logger || defaultLogger2;
   async function triggerManualRun(_req, res) {
-    runnerService.runAllRules(RUN_TRIGGER.Manual).catch((err) => {
-      log.error("Manual rule run failed", { error: err });
-    });
-    res.json({ success: true, data: { message: "Rule run triggered" } });
+    const { runId } = runnerService.trigger(RUN_TRIGGER.Manual);
+    res.json({ success: true, data: { message: "Rule run triggered", runId } });
   }
   async function getLatestRun(_req, res) {
     try {
@@ -1488,7 +1895,33 @@ function createRunnerController(runnerService, EmailRuleRunLog, logger) {
       res.status(500).json({ success: false, error: message });
     }
   }
-  return { triggerManualRun, getLatestRun };
+  async function getStatusByRunId(req, res) {
+    try {
+      const status = await runnerService.getStatus(getParam(req, "runId"));
+      if (!status) {
+        res.status(404).json({ success: false, error: "Run not found" });
+        return;
+      }
+      res.json({ success: true, data: status });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      res.status(500).json({ success: false, error: message });
+    }
+  }
+  async function cancelRun(req, res) {
+    try {
+      const result = await runnerService.cancel(getParam(req, "runId"));
+      if (!result.ok) {
+        res.status(404).json({ success: false, error: "Run not found" });
+        return;
+      }
+      res.json({ success: true, data: { message: "Cancel requested" } });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      res.status(500).json({ success: false, error: message });
+    }
+  }
+  return { triggerManualRun, getLatestRun, getStatusByRunId, cancelRun };
 }
 
 // src/controllers/settings.controller.ts
@@ -1559,7 +1992,7 @@ function createRoutes(deps) {
     platforms: deps.platformValues,
     audiences: deps.audienceValues
   });
-  const runnerCtrl = createRunnerController(deps.runnerService, deps.EmailRuleRunLog, deps.logger);
+  const runnerCtrl = createRunnerController(deps.runnerService, deps.EmailRuleRunLog);
   const settingsCtrl = createSettingsController(deps.EmailThrottleConfig);
   const templateRouter = Router();
   templateRouter.get("/", templateCtrl.list);
@@ -1584,6 +2017,8 @@ function createRoutes(deps) {
   const runnerRouter = Router();
   runnerRouter.post("/", runnerCtrl.triggerManualRun);
   runnerRouter.get("/status", runnerCtrl.getLatestRun);
+  runnerRouter.get("/status/:runId", runnerCtrl.getStatusByRunId);
+  runnerRouter.post("/cancel/:runId", runnerCtrl.cancelRun);
   const settingsRouter = Router();
   settingsRouter.get("/throttle", settingsCtrl.getThrottleConfig);
   settingsRouter.patch("/throttle", settingsCtrl.updateThrottleConfig);