@astralibx/email-rule-engine 6.0.0 → 7.0.0

package/README.md

@@ -102,21 +102,18 @@ The `createEmailRuleEngine(config)` factory accepts an `EmailRuleEngineConfig` o
 
 See [docs/configuration.md](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/configuration.md) for the full reference with examples.
 
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Configuration](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/configuration.md) | Full config reference -- db, redis, adapters, platforms, options, hooks, logger |
-| [Adapters](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/adapters.md) | All 6 adapters with type signatures and example implementations |
-| [Templates](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/templates.md) | Creating templates, MJML + Handlebars syntax, built-in helpers |
-| [Rules](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/rules.md) | Targeting conditions, operators, sendOnce/resend, dry runs |
-| [Throttling](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/throttling.md) | Per-user limits, global caps, bypass rules, tracking |
-| [API Routes](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/api-routes.md) | All REST endpoints with curl examples |
-| [Programmatic API](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/programmatic-api.md) | Using services directly -- runner, templateService, ruleService |
-| [Execution Flow](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/execution-flow.md) | Step-by-step runner flow and error behavior |
-| [Error Handling](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/error-handling.md) | All error classes with codes and when thrown |
-| [Constants](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/constants.md) | All exported constants and derived types |
-| [Migration v1 to v2](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/migration-v1-to-v2.md) | Breaking changes from v1 |
+## Getting Started Guide
+
+1. [Configuration](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/configuration.md) — Set up database, Redis, and options
+2. [Adapters](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/adapters.md) — Implement the 6 required adapter functions
+3. [Templates](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/templates.md) — Create email templates with MJML + Handlebars
+4. [Rules](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/rules.md) — Define targeting rules with conditions or explicit lists
+5. [Execution Flow](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/execution-flow.md) — Understand how the runner processes rules
+6. [Throttling](https://github.com/Hariprakash1997/astralib/blob/main/packages/email-rule-engine/docs/throttling.md) — Configure per-user send limits
+
+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)
+
+> **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.d.mts

@@ -295,6 +295,7 @@ interface EmailTemplate {
     textBody?: string;
     subjects: string[];
     bodies: string[];
+    preheaders?: string[];
     fields?: Record<string, string>;
     variables: string[];
     version: number;
@@ -312,6 +313,7 @@ interface CreateEmailTemplateInput {
     textBody?: string;
     subjects: string[];
     bodies: string[];
+    preheaders?: string[];
     fields?: Record<string, string>;
     variables?: string[];
 }
@@ -324,6 +326,7 @@ interface UpdateEmailTemplateInput {
     textBody?: string;
     subjects?: string[];
     bodies?: string[];
+    preheaders?: string[];
     fields?: Record<string, string>;
     variables?: string[];
     isActive?: boolean;
@@ -382,6 +385,7 @@ interface IEmailRuleSend {
     subject?: string;
     subjectIndex?: number;
     bodyIndex?: number;
+    preheaderIndex?: number;
     failureReason?: string;
 }
 type EmailRuleSendDocument = HydratedDocument<IEmailRuleSend>;
@@ -395,6 +399,7 @@ interface EmailRuleSendStatics {
         subject?: string;
         subjectIndex?: number;
         bodyIndex?: number;
+        preheaderIndex?: number;
         failureReason?: string;
     }): Promise<EmailRuleSendDocument>;
 }
@@ -625,10 +630,11 @@ declare class TemplateRenderService {
     constructor();
     renderSingle(subject: string, body: string, data: Record<string, unknown>, textBody?: string): RenderResult;
     compileBatch(subject: string, body: string, textBody?: string): CompiledTemplate;
-    compileBatchVariants(subjects: string[], bodies: string[], textBody?: string): {
+    compileBatchVariants(subjects: string[], bodies: string[], textBody?: string, preheaders?: string[]): {
         subjectFns: HandlebarsTemplateDelegate[];
         bodyFns: HandlebarsTemplateDelegate[];
         textBodyFn?: HandlebarsTemplateDelegate;
+        preheaderFns?: HandlebarsTemplateDelegate[];
     };
     renderFromCompiled(compiled: CompiledTemplate, data: Record<string, unknown>): RenderResult;
     renderPreview(subject: string, body: string, data: Record<string, unknown>, textBody?: string): RenderResult;

package/dist/index.d.ts

@@ -295,6 +295,7 @@ interface EmailTemplate {
     textBody?: string;
     subjects: string[];
     bodies: string[];
+    preheaders?: string[];
     fields?: Record<string, string>;
     variables: string[];
     version: number;
@@ -312,6 +313,7 @@ interface CreateEmailTemplateInput {
     textBody?: string;
     subjects: string[];
     bodies: string[];
+    preheaders?: string[];
     fields?: Record<string, string>;
     variables?: string[];
 }
@@ -324,6 +326,7 @@ interface UpdateEmailTemplateInput {
     textBody?: string;
     subjects?: string[];
     bodies?: string[];
+    preheaders?: string[];
     fields?: Record<string, string>;
     variables?: string[];
     isActive?: boolean;
@@ -382,6 +385,7 @@ interface IEmailRuleSend {
     subject?: string;
     subjectIndex?: number;
     bodyIndex?: number;
+    preheaderIndex?: number;
     failureReason?: string;
 }
 type EmailRuleSendDocument = HydratedDocument<IEmailRuleSend>;
@@ -395,6 +399,7 @@ interface EmailRuleSendStatics {
         subject?: string;
         subjectIndex?: number;
         bodyIndex?: number;
+        preheaderIndex?: number;
         failureReason?: string;
     }): Promise<EmailRuleSendDocument>;
 }
@@ -625,10 +630,11 @@ declare class TemplateRenderService {
     constructor();
     renderSingle(subject: string, body: string, data: Record<string, unknown>, textBody?: string): RenderResult;
     compileBatch(subject: string, body: string, textBody?: string): CompiledTemplate;
-    compileBatchVariants(subjects: string[], bodies: string[], textBody?: string): {
+    compileBatchVariants(subjects: string[], bodies: string[], textBody?: string, preheaders?: string[]): {
         subjectFns: HandlebarsTemplateDelegate[];
         bodyFns: HandlebarsTemplateDelegate[];
         textBodyFn?: HandlebarsTemplateDelegate;
+        preheaderFns?: HandlebarsTemplateDelegate[];
     };
     renderFromCompiled(compiled: CompiledTemplate, data: Record<string, unknown>): RenderResult;
     renderPreview(subject: string, body: string, data: Record<string, unknown>, textBody?: string): RenderResult;

package/dist/index.js

@@ -79,7 +79,18 @@ function createEmailTemplateSchema(platformValues, audienceValues, categoryValue
       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"] },
-      fields: { type: mongoose.Schema.Types.Mixed, default: {} },
+      preheaders: [{ type: String }],
+      fields: {
+        type: mongoose.Schema.Types.Mixed,
+        default: {},
+        validate: {
+          validator: (v) => {
+            if (!v || typeof v !== "object") return true;
+            return Object.values(v).every((val) => typeof val === "string");
+          },
+          message: "All field values must be strings"
+        }
+      },
       variables: [{ type: String }],
       version: { type: Number, default: 1 },
       isActive: { type: Boolean, default: true, index: true }
@@ -114,6 +125,7 @@ function createEmailTemplateSchema(platformValues, audienceValues, categoryValue
             textBody: input.textBody,
             subjects: input.subjects,
             bodies: input.bodies,
+            preheaders: input.preheaders || [],
             fields: input.fields || {},
             variables: input.variables || [],
             version: 1,
@@ -224,6 +236,7 @@ function createEmailRuleSendSchema(collectionPrefix) {
       subject: { type: String },
       subjectIndex: { type: Number },
       bodyIndex: { type: Number },
+      preheaderIndex: { type: Number },
       failureReason: { type: String }
     },
     {
@@ -448,7 +461,7 @@ var TemplateRenderService = class {
     const textBodyFn = textBody ? Handlebars__default.default.compile(textBody, { strict: true }) : void 0;
     return { subjectFn, bodyFn, textBodyFn };
   }
-  compileBatchVariants(subjects, bodies, textBody) {
+  compileBatchVariants(subjects, bodies, textBody, preheaders) {
     const subjectFns = subjects.map((s) => Handlebars__default.default.compile(s, { strict: true }));
     const bodyFns = bodies.map((b) => {
       const mjmlSource = wrapInMjml(b);
@@ -456,7 +469,8 @@ var TemplateRenderService = class {
       return Handlebars__default.default.compile(htmlWithHandlebars, { strict: true });
     });
     const textBodyFn = textBody ? Handlebars__default.default.compile(textBody, { strict: true }) : void 0;
-    return { subjectFns, bodyFns, textBodyFn };
+    const preheaderFns = preheaders && preheaders.length > 0 ? preheaders.map((p) => Handlebars__default.default.compile(p, { strict: true })) : void 0;
+    return { subjectFns, bodyFns, textBodyFn, preheaderFns };
   }
   renderFromCompiled(compiled, data) {
     const subject = compiled.subjectFn(data);
@@ -568,6 +582,7 @@ var UPDATEABLE_FIELDS = /* @__PURE__ */ new Set([
   "textBody",
   "subjects",
   "bodies",
+  "preheaders",
   "variables",
   "isActive",
   "fields"
@@ -610,7 +625,7 @@ var TemplateService = class {
         throw new TemplateSyntaxError(`Template validation failed: ${validation.errors.join("; ")}`, validation.errors);
       }
     }
-    const allContent = [...subjects, ...bodies, input.textBody || ""].join(" ");
+    const allContent = [...subjects, ...bodies, ...input.preheaders || [], input.textBody || ""].join(" ");
     const variables = input.variables || this.renderService.extractVariables(allContent);
     return this.EmailTemplate.createTemplate({
       ...input,
@@ -638,11 +653,12 @@ var TemplateService = class {
         }
       }
     }
-    if (input.textBody || input.subjects || input.bodies) {
+    if (input.textBody || input.subjects || input.bodies || input.preheaders) {
       const subjects = input.subjects ?? template.subjects;
       const bodies = input.bodies ?? template.bodies;
+      const preheaders = input.preheaders ?? template.preheaders ?? [];
       const textBody = input.textBody ?? template.textBody;
-      const allContent = [...subjects, ...bodies, textBody || ""].join(" ");
+      const allContent = [...subjects, ...bodies, ...preheaders, textBody || ""].join(" ");
       input.variables = this.renderService.extractVariables(allContent);
     }
     const setFields = {};
@@ -652,7 +668,7 @@ var TemplateService = class {
       }
     }
     const update = { $set: setFields };
-    if (input.textBody || input.subjects || input.bodies) {
+    if (input.textBody || input.subjects || input.bodies || input.preheaders) {
       update["$inc"] = { version: 1 };
     }
     return this.EmailTemplate.findByIdAndUpdate(
@@ -904,6 +920,21 @@ var RedisLock = class {
 var MS_PER_DAY = 864e5;
 var DEFAULT_LOCK_TTL_MS = 30 * 60 * 1e3;
 var IDENTIFIER_CHUNK_SIZE = 50;
+function getLocalDate(date, timezone) {
+  if (!timezone) return date;
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  }).formatToParts(date);
+  const get = (type) => parts.find((p) => p.type === type)?.value || "0";
+  return /* @__PURE__ */ new Date(`${get("year")}-${get("month")}-${get("day")}T${get("hour")}:${get("minute")}:${get("second")}`);
+}
 async function processInChunks(items, fn, chunkSize) {
   const results = [];
   for (let i = 0; i < items.length; i += chunkSize) {
@@ -977,9 +1008,18 @@ var RuleRunnerService = class {
       const throttleConfig = await this.EmailThrottleConfig.getConfig();
       const allActiveRules = await this.EmailRule.findActive();
       const now = /* @__PURE__ */ new Date();
+      const tz = this.config.options?.sendWindow?.timezone;
       const activeRules = allActiveRules.filter((rule) => {
-        if (rule.validFrom && now < new Date(rule.validFrom)) return false;
-        if (rule.validTill && now > new Date(rule.validTill)) return false;
+        if (rule.validFrom) {
+          const localNow = getLocalDate(now, tz);
+          const localValidFrom = getLocalDate(new Date(rule.validFrom), tz);
+          if (localNow < localValidFrom) return false;
+        }
+        if (rule.validTill) {
+          const localNow = getLocalDate(now, tz);
+          const localValidTill = getLocalDate(new Date(rule.validTill), tz);
+          if (localNow > localValidTill) return false;
+        }
         return true;
       });
       this.config.hooks?.onRunStart?.({ rulesCount: activeRules.length, triggeredBy });
@@ -1136,10 +1176,12 @@ var RuleRunnerService = class {
         sendMap.set(uid, send);
       }
     }
+    const preheaders = template.preheaders || [];
     const compiledVariants = this.templateRenderer.compileBatchVariants(
       template.subjects,
       template.bodies,
-      template.textBody
+      template.textBody,
+      preheaders
     );
     let totalProcessed = 0;
     for (let i = 0; i < emailsToProcess.length; i++) {
@@ -1195,6 +1237,15 @@ var RuleRunnerService = class {
         let finalHtml = renderedHtml;
         let finalText = renderedText;
         let finalSubject = renderedSubject;
+        let pi;
+        if (compiledVariants.preheaderFns && compiledVariants.preheaderFns.length > 0) {
+          pi = Math.floor(Math.random() * compiledVariants.preheaderFns.length);
+          const renderedPreheader = compiledVariants.preheaderFns[pi](templateData);
+          if (renderedPreheader) {
+            const preheaderHtml = `<div style="display:none;font-size:1px;color:#ffffff;line-height:1px;max-height:0px;max-width:0px;opacity:0;overflow:hidden;">${renderedPreheader}</div>`;
+            finalHtml = finalHtml.replace(/(<body[^>]*>)/i, `$1${preheaderHtml}`);
+          }
+        }
         if (this.config.hooks?.beforeSend) {
           try {
             const modified = await this.config.hooks.beforeSend({
@@ -1237,7 +1288,7 @@ var RuleRunnerService = class {
           dedupKey,
           identifier.id,
           void 0,
-          { status: "sent", accountId: agentSelection.accountId, subject: finalSubject, subjectIndex: si, bodyIndex: bi }
+          { status: "sent", accountId: agentSelection.accountId, subject: finalSubject, subjectIndex: si, bodyIndex: bi, preheaderIndex: pi }
         );
         const current = throttleMap.get(dedupKey) || { today: 0, thisWeek: 0, lastSentDate: null };
         throttleMap.set(dedupKey, {
@@ -1270,24 +1321,16 @@ var RuleRunnerService = class {
       $inc: { totalSent: stats.sent, totalSkipped: stats.skipped }
     });
     if (rule.sendOnce) {
-      const allIdentifiers = rule.target.identifiers;
+      const allIdentifiers = rule.target.identifiers || [];
+      const totalIdentifiers = new Set(allIdentifiers.map((e) => e.toLowerCase().trim()).filter(Boolean)).size;
       const sends = await this.EmailRuleSend.find({
         ruleId: rule._id
       }).lean();
       const sentOrProcessedIds = new Set(
         sends.filter((s) => s.status !== "throttled").map((s) => String(s.userId || s.emailIdentifierId))
       );
-      let pendingCount = 0;
-      for (const email of allIdentifiers) {
-        const identifier = identifierMap.get(email.toLowerCase().trim());
-        if (!identifier) continue;
-        if (!sentOrProcessedIds.has(String(identifier.id))) {
-          pendingCount++;
-        }
-      }
       const throttledCount = sends.filter((s) => s.status === "throttled").length;
-      pendingCount += throttledCount;
-      if (pendingCount === 0) {
+      if (sentOrProcessedIds.size >= totalIdentifiers && throttledCount === 0) {
         await this.EmailRule.findByIdAndUpdate(rule._id, { $set: { isActive: false } });
         this.logger.info(`Rule '${rule.name}' auto-disabled \u2014 all identifiers processed`);
       }
@@ -1332,10 +1375,12 @@ var RuleRunnerService = class {
         identifierMap.set(result.email, { id: result.id, contactId: result.contactId });
       }
     }
+    const preheadersQ = template.preheaders || [];
     const compiledVariants = this.templateRenderer.compileBatchVariants(
       template.subjects,
       template.bodies,
-      template.textBody
+      template.textBody,
+      preheadersQ
     );
     const ruleId = rule._id.toString();
     const templateId = rule.templateId.toString();
@@ -1398,6 +1443,15 @@ var RuleRunnerService = class {
         let finalHtml = renderedHtml;
         let finalText = renderedText;
         let finalSubject = renderedSubject;
+        let pi;
+        if (compiledVariants.preheaderFns && compiledVariants.preheaderFns.length > 0) {
+          pi = Math.floor(Math.random() * compiledVariants.preheaderFns.length);
+          const renderedPreheader = compiledVariants.preheaderFns[pi](templateData);
+          if (renderedPreheader) {
+            const preheaderHtml = `<div style="display:none;font-size:1px;color:#ffffff;line-height:1px;max-height:0px;max-width:0px;opacity:0;overflow:hidden;">${renderedPreheader}</div>`;
+            finalHtml = finalHtml.replace(/(<body[^>]*>)/i, `$1${preheaderHtml}`);
+          }
+        }
         if (this.config.hooks?.beforeSend) {
           try {
             const modified = await this.config.hooks.beforeSend({
@@ -1440,7 +1494,7 @@ var RuleRunnerService = class {
           userId,
           identifier.id,
           void 0,
-          { status: "sent", accountId: agentSelection.accountId, subject: finalSubject, subjectIndex: si, bodyIndex: bi }
+          { status: "sent", accountId: agentSelection.accountId, subject: finalSubject, subjectIndex: si, bodyIndex: bi, preheaderIndex: pi }
         );
         const current = throttleMap.get(userId) || { today: 0, thisWeek: 0, lastSentDate: null };
         throttleMap.set(userId, {
@@ -1669,7 +1723,7 @@ function createTemplateController(templateService, options) {
   }
   async function create(req, res) {
     try {
-      const { name, subjects, bodies, category, audience, platform } = req.body;
+      const { name, subjects, bodies, category, audience, platform, preheaders } = 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" });
       }