@astralibx/email-rule-engine 3.0.2 → 5.0.0

package/README.md

@@ -59,7 +59,7 @@ const engine = createEmailRuleEngine({
         text: params.textBody,
       });
     },
-    selectAgent: async () => ({ accountId: 'default' }),
+    selectAgent: async () => ({ accountId: 'default', email: 'noreply@myapp.com', metadata: {} }),
     findIdentifier: async (email) => {
       const contact = await Contact.findOne({ email });
       return contact ? { id: contact._id.toString(), contactId: contact._id.toString() } : null;

package/dist/index.d.mts

@@ -68,11 +68,17 @@ interface RuleRunStats {
     skippedByThrottle: number;
     errors: number;
 }
-interface RuleTarget {
+interface QueryTarget {
+    mode: 'query';
     role: TemplateAudience;
     platform: string;
     conditions: RuleCondition[];
 }
+interface ListTarget {
+    mode: 'list';
+    identifiers: string[];
+}
+type RuleTarget = QueryTarget | ListTarget;
 interface EmailRule {
     _id: string;
     name: string;
@@ -163,11 +169,50 @@ interface SendEmailParams {
 }
 interface AgentSelection {
     accountId: string;
+    email: string;
+    metadata: Record<string, unknown>;
+}
+interface BeforeSendParams {
+    htmlBody: string;
+    textBody: string;
+    subject: string;
+    account: {
+        id: string;
+        email: string;
+        metadata: Record<string, unknown>;
+    };
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+}
+interface BeforeSendResult {
+    htmlBody: string;
+    textBody: string;
+    subject: string;
 }
 interface RecipientIdentifier {
     id: string;
     contactId: string;
 }
+interface RunProgress {
+    rulesTotal: number;
+    rulesCompleted: number;
+    sent: number;
+    failed: number;
+    skipped: number;
+    invalid: number;
+}
+type RunStatus = 'running' | 'completed' | 'cancelled' | 'failed';
+interface RunStatusResponse {
+    runId: string;
+    status: RunStatus;
+    currentRule: string;
+    progress: RunProgress;
+    startedAt: string;
+    elapsed: number;
+}
 interface EmailRuleEngineConfig {
     db: {
         connection: Connection;
@@ -229,6 +274,7 @@ interface EmailRuleEngineConfig {
             totalStats: RuleRunStats;
             perRuleStats: PerRuleStats[];
         }) => void;
+        beforeSend?: (params: BeforeSendParams) => Promise<BeforeSendResult>;
     };
 }
 
@@ -240,9 +286,9 @@ interface EmailTemplate {
     category: TemplateCategory;
     audience: TemplateAudience;
     platform: string;
-    subject: string;
-    body: string;
     textBody?: string;
+    subjects: string[];
+    bodies: string[];
     variables: string[];
     version: number;
     isActive: boolean;
@@ -256,9 +302,9 @@ interface CreateEmailTemplateInput {
     category: TemplateCategory;
     audience: TemplateAudience;
     platform: string;
-    subject: string;
-    body: string;
     textBody?: string;
+    subjects: string[];
+    bodies: string[];
     variables?: string[];
 }
 interface UpdateEmailTemplateInput {
@@ -267,9 +313,9 @@ interface UpdateEmailTemplateInput {
     category?: TemplateCategory;
     audience?: TemplateAudience;
     platform?: string;
-    subject?: string;
-    body?: string;
     textBody?: string;
+    subjects?: string[];
+    bodies?: string[];
     variables?: string[];
     isActive?: boolean;
 }
@@ -325,6 +371,8 @@ interface IEmailRuleSend {
     accountId?: string;
     senderName?: string;
     subject?: string;
+    subjectIndex?: number;
+    bodyIndex?: number;
     failureReason?: string;
 }
 type EmailRuleSendDocument = HydratedDocument<IEmailRuleSend>;
@@ -336,6 +384,8 @@ interface EmailRuleSendStatics {
         accountId?: string;
         senderName?: string;
         subject?: string;
+        subjectIndex?: number;
+        bodyIndex?: number;
         failureReason?: string;
     }): Promise<EmailRuleSendDocument>;
 }
@@ -351,10 +401,12 @@ declare function createEmailRuleSendSchema(collectionPrefix?: string): Schema<IE
 }>;
 
 interface IEmailRuleRunLog {
+    runId?: string;
     runAt: Date;
     triggeredBy: string;
     duration: number;
     rulesProcessed: number;
+    status?: string;
     totalStats: {
         matched: number;
         sent: number;
@@ -494,11 +546,26 @@ declare class RuleRunnerService {
     private templateRenderer;
     private lock;
     private logger;
+    private redis;
+    private keyPrefix;
     constructor(EmailRule: EmailRuleModel, EmailTemplate: EmailTemplateModel, EmailRuleSend: EmailRuleSendModel, EmailRuleRunLog: EmailRuleRunLogModel, EmailThrottleConfig: EmailThrottleConfigModel, config: EmailRuleEngineConfig);
-    runAllRules(triggeredBy?: RunTrigger): Promise<void>;
-    executeRule(rule: any, throttleMap: Map<string, UserThrottle>, throttleConfig: any, templateMap?: Map<string, any>): Promise<RuleRunStats>;
+    runAllRules(triggeredBy?: RunTrigger, runId?: string): Promise<{
+        runId: string;
+    }>;
+    executeRule(rule: any, throttleMap: Map<string, UserThrottle>, throttleConfig: any, templateMap?: Map<string, any>, runId?: string): Promise<RuleRunStats>;
+    private executeListMode;
+    private executeQueryMode;
     private checkThrottle;
     private getTodayStart;
+    private updateRunProgress;
+    private updateRunSendProgress;
+    getStatus(runId: string): Promise<RunStatusResponse | null>;
+    cancel(runId: string): Promise<{
+        ok: boolean;
+    }>;
+    trigger(triggeredBy?: RunTrigger): {
+        runId: string;
+    };
     buildThrottleMap(recentSends: any[]): Map<string, UserThrottle>;
 }
 
@@ -549,8 +616,14 @@ 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): {
+        subjectFns: HandlebarsTemplateDelegate[];
+        bodyFns: HandlebarsTemplateDelegate[];
+        textBodyFn?: HandlebarsTemplateDelegate;
+    };
     renderFromCompiled(compiled: CompiledTemplate, data: Record<string, unknown>): RenderResult;
     renderPreview(subject: string, body: string, data: Record<string, unknown>, textBody?: string): RenderResult;
+    htmlToText(html: string): string;
     extractVariables(template: string): string[];
     validateTemplate(body: string): {
         valid: boolean;
@@ -604,4 +677,4 @@ interface EmailRuleEngine {
  */
 declare function createEmailRuleEngine(config: EmailRuleEngineConfig): EmailRuleEngine;
 
-export { type AgentSelection, AlxEmailError, type CompiledTemplate, ConfigValidationError, type CreateEmailRuleInput, type CreateEmailTemplateInput, DuplicateSlugError, EMAIL_SEND_STATUS, EMAIL_TYPE, type EmailRule, type EmailRuleDocument, type EmailRuleEngine, type EmailRuleEngineConfig, type EmailRuleModel, type EmailRuleRunLog, type EmailRuleRunLogDocument, type EmailRuleRunLogModel, type EmailRuleRunLogStatics, type EmailRuleSend, type EmailRuleSendDocument, type EmailRuleSendModel, type EmailRuleSendStatics, type EmailRuleStatics, type EmailSendStatus, type EmailTemplate, type EmailTemplateDocument, type EmailTemplateModel, type EmailTemplateStatics, type EmailThrottleConfig, type EmailThrottleConfigDocument, type EmailThrottleConfigModel, type EmailThrottleConfigStatics, type EmailType, type IEmailRule, type IEmailRuleRunLog, type IEmailRuleSend, type IEmailTemplate, type IEmailThrottleConfig, LockAcquisitionError, type PerRuleStats, RULE_OPERATOR, RUN_TRIGGER, type RecipientIdentifier, RedisLock, type RenderResult, type RuleCondition, RuleNotFoundError, type RuleOperator, type RuleRunStats, RuleRunnerService, RuleService, type RuleTarget, RuleTemplateIncompatibleError, type RunTrigger, type SendEmailParams, TEMPLATE_AUDIENCE, TEMPLATE_CATEGORY, THROTTLE_WINDOW, type TemplateAudience, type TemplateCategory, TemplateNotFoundError, TemplateRenderService, TemplateService, TemplateSyntaxError, type ThrottleWindow, type UpdateEmailRuleInput, type UpdateEmailTemplateInput, type UpdateEmailThrottleConfigInput, createEmailRuleEngine, createEmailRuleRunLogSchema, createEmailRuleSchema, createEmailRuleSendSchema, createEmailTemplateSchema, createEmailThrottleConfigSchema, validateConfig };
+export { type AgentSelection, AlxEmailError, type BeforeSendParams, type BeforeSendResult, type CompiledTemplate, ConfigValidationError, type CreateEmailRuleInput, type CreateEmailTemplateInput, DuplicateSlugError, EMAIL_SEND_STATUS, EMAIL_TYPE, type EmailRule, type EmailRuleDocument, type EmailRuleEngine, type EmailRuleEngineConfig, type EmailRuleModel, type EmailRuleRunLog, type EmailRuleRunLogDocument, type EmailRuleRunLogModel, type EmailRuleRunLogStatics, type EmailRuleSend, type EmailRuleSendDocument, type EmailRuleSendModel, type EmailRuleSendStatics, type EmailRuleStatics, type EmailSendStatus, type EmailTemplate, type EmailTemplateDocument, type EmailTemplateModel, type EmailTemplateStatics, type EmailThrottleConfig, type EmailThrottleConfigDocument, type EmailThrottleConfigModel, type EmailThrottleConfigStatics, type EmailType, type IEmailRule, type IEmailRuleRunLog, type IEmailRuleSend, type IEmailTemplate, type IEmailThrottleConfig, type ListTarget, LockAcquisitionError, type PerRuleStats, type QueryTarget, RULE_OPERATOR, RUN_TRIGGER, type RecipientIdentifier, RedisLock, type RenderResult, type RuleCondition, RuleNotFoundError, type RuleOperator, type RuleRunStats, RuleRunnerService, RuleService, type RuleTarget, RuleTemplateIncompatibleError, type RunTrigger, type SendEmailParams, TEMPLATE_AUDIENCE, TEMPLATE_CATEGORY, THROTTLE_WINDOW, type TemplateAudience, type TemplateCategory, TemplateNotFoundError, TemplateRenderService, TemplateService, TemplateSyntaxError, type ThrottleWindow, type UpdateEmailRuleInput, type UpdateEmailTemplateInput, type UpdateEmailThrottleConfigInput, createEmailRuleEngine, createEmailRuleRunLogSchema, createEmailRuleSchema, createEmailRuleSendSchema, createEmailTemplateSchema, createEmailThrottleConfigSchema, validateConfig };

package/dist/index.d.ts

@@ -68,11 +68,17 @@ interface RuleRunStats {
     skippedByThrottle: number;
     errors: number;
 }
-interface RuleTarget {
+interface QueryTarget {
+    mode: 'query';
     role: TemplateAudience;
     platform: string;
     conditions: RuleCondition[];
 }
+interface ListTarget {
+    mode: 'list';
+    identifiers: string[];
+}
+type RuleTarget = QueryTarget | ListTarget;
 interface EmailRule {
     _id: string;
     name: string;
@@ -163,11 +169,50 @@ interface SendEmailParams {
 }
 interface AgentSelection {
     accountId: string;
+    email: string;
+    metadata: Record<string, unknown>;
+}
+interface BeforeSendParams {
+    htmlBody: string;
+    textBody: string;
+    subject: string;
+    account: {
+        id: string;
+        email: string;
+        metadata: Record<string, unknown>;
+    };
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+}
+interface BeforeSendResult {
+    htmlBody: string;
+    textBody: string;
+    subject: string;
 }
 interface RecipientIdentifier {
     id: string;
     contactId: string;
 }
+interface RunProgress {
+    rulesTotal: number;
+    rulesCompleted: number;
+    sent: number;
+    failed: number;
+    skipped: number;
+    invalid: number;
+}
+type RunStatus = 'running' | 'completed' | 'cancelled' | 'failed';
+interface RunStatusResponse {
+    runId: string;
+    status: RunStatus;
+    currentRule: string;
+    progress: RunProgress;
+    startedAt: string;
+    elapsed: number;
+}
 interface EmailRuleEngineConfig {
     db: {
         connection: Connection;
@@ -229,6 +274,7 @@ interface EmailRuleEngineConfig {
             totalStats: RuleRunStats;
             perRuleStats: PerRuleStats[];
         }) => void;
+        beforeSend?: (params: BeforeSendParams) => Promise<BeforeSendResult>;
     };
 }
 
@@ -240,9 +286,9 @@ interface EmailTemplate {
     category: TemplateCategory;
     audience: TemplateAudience;
     platform: string;
-    subject: string;
-    body: string;
     textBody?: string;
+    subjects: string[];
+    bodies: string[];
     variables: string[];
     version: number;
     isActive: boolean;
@@ -256,9 +302,9 @@ interface CreateEmailTemplateInput {
     category: TemplateCategory;
     audience: TemplateAudience;
     platform: string;
-    subject: string;
-    body: string;
     textBody?: string;
+    subjects: string[];
+    bodies: string[];
     variables?: string[];
 }
 interface UpdateEmailTemplateInput {
@@ -267,9 +313,9 @@ interface UpdateEmailTemplateInput {
     category?: TemplateCategory;
     audience?: TemplateAudience;
     platform?: string;
-    subject?: string;
-    body?: string;
     textBody?: string;
+    subjects?: string[];
+    bodies?: string[];
     variables?: string[];
     isActive?: boolean;
 }
@@ -325,6 +371,8 @@ interface IEmailRuleSend {
     accountId?: string;
     senderName?: string;
     subject?: string;
+    subjectIndex?: number;
+    bodyIndex?: number;
     failureReason?: string;
 }
 type EmailRuleSendDocument = HydratedDocument<IEmailRuleSend>;
@@ -336,6 +384,8 @@ interface EmailRuleSendStatics {
         accountId?: string;
         senderName?: string;
         subject?: string;
+        subjectIndex?: number;
+        bodyIndex?: number;
         failureReason?: string;
     }): Promise<EmailRuleSendDocument>;
 }
@@ -351,10 +401,12 @@ declare function createEmailRuleSendSchema(collectionPrefix?: string): Schema<IE
 }>;
 
 interface IEmailRuleRunLog {
+    runId?: string;
     runAt: Date;
     triggeredBy: string;
     duration: number;
     rulesProcessed: number;
+    status?: string;
     totalStats: {
         matched: number;
         sent: number;
@@ -494,11 +546,26 @@ declare class RuleRunnerService {
     private templateRenderer;
     private lock;
     private logger;
+    private redis;
+    private keyPrefix;
     constructor(EmailRule: EmailRuleModel, EmailTemplate: EmailTemplateModel, EmailRuleSend: EmailRuleSendModel, EmailRuleRunLog: EmailRuleRunLogModel, EmailThrottleConfig: EmailThrottleConfigModel, config: EmailRuleEngineConfig);
-    runAllRules(triggeredBy?: RunTrigger): Promise<void>;
-    executeRule(rule: any, throttleMap: Map<string, UserThrottle>, throttleConfig: any, templateMap?: Map<string, any>): Promise<RuleRunStats>;
+    runAllRules(triggeredBy?: RunTrigger, runId?: string): Promise<{
+        runId: string;
+    }>;
+    executeRule(rule: any, throttleMap: Map<string, UserThrottle>, throttleConfig: any, templateMap?: Map<string, any>, runId?: string): Promise<RuleRunStats>;
+    private executeListMode;
+    private executeQueryMode;
     private checkThrottle;
     private getTodayStart;
+    private updateRunProgress;
+    private updateRunSendProgress;
+    getStatus(runId: string): Promise<RunStatusResponse | null>;
+    cancel(runId: string): Promise<{
+        ok: boolean;
+    }>;
+    trigger(triggeredBy?: RunTrigger): {
+        runId: string;
+    };
     buildThrottleMap(recentSends: any[]): Map<string, UserThrottle>;
 }
 
@@ -549,8 +616,14 @@ 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): {
+        subjectFns: HandlebarsTemplateDelegate[];
+        bodyFns: HandlebarsTemplateDelegate[];
+        textBodyFn?: HandlebarsTemplateDelegate;
+    };
     renderFromCompiled(compiled: CompiledTemplate, data: Record<string, unknown>): RenderResult;
     renderPreview(subject: string, body: string, data: Record<string, unknown>, textBody?: string): RenderResult;
+    htmlToText(html: string): string;
     extractVariables(template: string): string[];
     validateTemplate(body: string): {
         valid: boolean;
@@ -604,4 +677,4 @@ interface EmailRuleEngine {
  */
 declare function createEmailRuleEngine(config: EmailRuleEngineConfig): EmailRuleEngine;
 
-export { type AgentSelection, AlxEmailError, type CompiledTemplate, ConfigValidationError, type CreateEmailRuleInput, type CreateEmailTemplateInput, DuplicateSlugError, EMAIL_SEND_STATUS, EMAIL_TYPE, type EmailRule, type EmailRuleDocument, type EmailRuleEngine, type EmailRuleEngineConfig, type EmailRuleModel, type EmailRuleRunLog, type EmailRuleRunLogDocument, type EmailRuleRunLogModel, type EmailRuleRunLogStatics, type EmailRuleSend, type EmailRuleSendDocument, type EmailRuleSendModel, type EmailRuleSendStatics, type EmailRuleStatics, type EmailSendStatus, type EmailTemplate, type EmailTemplateDocument, type EmailTemplateModel, type EmailTemplateStatics, type EmailThrottleConfig, type EmailThrottleConfigDocument, type EmailThrottleConfigModel, type EmailThrottleConfigStatics, type EmailType, type IEmailRule, type IEmailRuleRunLog, type IEmailRuleSend, type IEmailTemplate, type IEmailThrottleConfig, LockAcquisitionError, type PerRuleStats, RULE_OPERATOR, RUN_TRIGGER, type RecipientIdentifier, RedisLock, type RenderResult, type RuleCondition, RuleNotFoundError, type RuleOperator, type RuleRunStats, RuleRunnerService, RuleService, type RuleTarget, RuleTemplateIncompatibleError, type RunTrigger, type SendEmailParams, TEMPLATE_AUDIENCE, TEMPLATE_CATEGORY, THROTTLE_WINDOW, type TemplateAudience, type TemplateCategory, TemplateNotFoundError, TemplateRenderService, TemplateService, TemplateSyntaxError, type ThrottleWindow, type UpdateEmailRuleInput, type UpdateEmailTemplateInput, type UpdateEmailThrottleConfigInput, createEmailRuleEngine, createEmailRuleRunLogSchema, createEmailRuleSchema, createEmailRuleSendSchema, createEmailTemplateSchema, createEmailThrottleConfigSchema, validateConfig };
+export { type AgentSelection, AlxEmailError, type BeforeSendParams, type BeforeSendResult, type CompiledTemplate, ConfigValidationError, type CreateEmailRuleInput, type CreateEmailTemplateInput, DuplicateSlugError, EMAIL_SEND_STATUS, EMAIL_TYPE, type EmailRule, type EmailRuleDocument, type EmailRuleEngine, type EmailRuleEngineConfig, type EmailRuleModel, type EmailRuleRunLog, type EmailRuleRunLogDocument, type EmailRuleRunLogModel, type EmailRuleRunLogStatics, type EmailRuleSend, type EmailRuleSendDocument, type EmailRuleSendModel, type EmailRuleSendStatics, type EmailRuleStatics, type EmailSendStatus, type EmailTemplate, type EmailTemplateDocument, type EmailTemplateModel, type EmailTemplateStatics, type EmailThrottleConfig, type EmailThrottleConfigDocument, type EmailThrottleConfigModel, type EmailThrottleConfigStatics, type EmailType, type IEmailRule, type IEmailRuleRunLog, type IEmailRuleSend, type IEmailTemplate, type IEmailThrottleConfig, type ListTarget, LockAcquisitionError, type PerRuleStats, type QueryTarget, RULE_OPERATOR, RUN_TRIGGER, type RecipientIdentifier, RedisLock, type RenderResult, type RuleCondition, RuleNotFoundError, type RuleOperator, type RuleRunStats, RuleRunnerService, RuleService, type RuleTarget, RuleTemplateIncompatibleError, type RunTrigger, type SendEmailParams, TEMPLATE_AUDIENCE, TEMPLATE_CATEGORY, THROTTLE_WINDOW, type TemplateAudience, type TemplateCategory, TemplateNotFoundError, TemplateRenderService, TemplateService, TemplateSyntaxError, type ThrottleWindow, type UpdateEmailRuleInput, type UpdateEmailTemplateInput, type UpdateEmailThrottleConfigInput, createEmailRuleEngine, createEmailRuleRunLogSchema, createEmailRuleSchema, createEmailRuleSendSchema, createEmailTemplateSchema, createEmailThrottleConfigSchema, validateConfig };