@astralibx/email-rule-engine 1.2.1 → 3.0.0

package/README.md

@@ -1,6 +1,9 @@
 # @astralibx/email-rule-engine
 
-Rule-based email automation engine with MJML + Handlebars templates, per-user throttling, and Redis distributed locking.
+[![npm version](https://img.shields.io/npm/v/@astralibx/email-rule-engine.svg)](https://www.npmjs.com/package/@astralibx/email-rule-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Rule-based email automation engine for Node.js. Define targeting rules with conditions, design responsive emails with MJML + Handlebars templates, and let the engine handle per-user throttling, send deduplication, distributed locking, and delivery scheduling. Ships with Express REST routes for admin UIs and a programmatic API for direct service access.
 
 ## Install
 
@@ -8,68 +11,112 @@ Rule-based email automation engine with MJML + Handlebars templates, per-user th
 npm install @astralibx/email-rule-engine
 ```
 
+**Peer dependencies:**
+
+| Peer Dependency | Version |
+|-----------------|---------|
+| `express` | `^4.18.0 \|\| ^5.0.0` |
+| `mongoose` | `^7.0.0 \|\| ^8.0.0` |
+| `ioredis` | `^5.0.0` |
+| `handlebars` | `^4.7.0` |
+| `mjml` | `^4.0.0` |
+| `html-to-text` | `^9.0.0` |
+
+```bash
+npm install express mongoose ioredis handlebars mjml html-to-text
+```
+
 ## Quick Start
 
 ```typescript
-import { createEmailRuleEngine } from '@astralibx/email-rule-engine';
+import express from 'express';
 import mongoose from 'mongoose';
 import Redis from 'ioredis';
+import { createEmailRuleEngine } from '@astralibx/email-rule-engine';
+
+const app = express();
+app.use(express.json());
+
+const dbConnection = mongoose.createConnection('mongodb://localhost/myapp');
+const redis = new Redis();
 
 const engine = createEmailRuleEngine({
-  db: { connection: mongoose.createConnection('mongodb://localhost/myapp') },
-  redis: { connection: new Redis() },
+  db: { connection: dbConnection },
+  redis: { connection: redis },
   adapters: {
-    queryUsers: async (target, limit) => db.collection('users').find({ role: target.role }).limit(limit).toArray(),
-    resolveData: (user) => ({ user: { name: user.name, email: user.email }, platform: { name: 'MyApp' } }),
-    sendEmail: async (params) => transporter.sendMail({ to: params.identifierId, subject: params.subject, html: params.htmlBody }),
+    queryUsers: async (target, limit) => {
+      return User.find({ role: target.role, platform: target.platform }).limit(limit).lean();
+    },
+    resolveData: (user) => ({
+      user: { name: user.name, email: user.email },
+      platform: { name: 'MyApp', domain: 'myapp.com' },
+    }),
+    sendEmail: async (params) => {
+      await transporter.sendMail({
+        to: params.identifierId,
+        subject: params.subject,
+        html: params.htmlBody,
+        text: params.textBody,
+      });
+    },
     selectAgent: async () => ({ accountId: 'default' }),
-    findIdentifier: async (email) => { const c = await Contacts.findOne({ email }); return c ? { id: c._id.toString(), contactId: c._id.toString() } : null; },
+    findIdentifier: async (email) => {
+      const contact = await Contact.findOne({ email });
+      return contact ? { id: contact._id.toString(), contactId: contact._id.toString() } : null;
+    },
   },
 });
 
+// Mount REST routes
 app.use('/api/email-rules', engine.routes);
-```
 
-## Features & Documentation
-
-| Feature | Description | Docs |
-|---------|-------------|------|
-| Adapters | Connect to your data, delivery, and accounts | [adapters.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/adapters.md) |
-| Templates | MJML + Handlebars responsive email templates | [templates.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/templates.md) |
-| Rules | Condition-based targeting and automation | [rules.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/rules.md) |
-| Throttling | Per-user daily/weekly rate limits | [throttling.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/throttling.md) |
-| Send Window | Time-based execution control | [send-window.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/send-window.md) |
-| Delivery Delays | Natural send spread with jitter | [delivery-delays.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/delivery-delays.md) |
-| Progress Hooks | Live execution tracking callbacks | [progress-hooks.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/progress-hooks.md) |
-| SMTP Pooling | Efficient email delivery patterns | [smtp-pooling.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/smtp-pooling.md) |
-| Account Rotation | Multi-account sending with quotas | [account-rotation.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/account-rotation.md) |
-| Email Validation | MX checks and domain validation | [email-validation.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/email-validation.md) |
-| Execution Flow | How the runner processes rules | [execution-flow.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/execution-flow.md) |
-| API Routes | REST endpoint reference | [api-routes.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/api-routes.md) |
-| Config Reference | Full configuration options | [config-reference.md](https://github.com/AstralibX/astralibx/blob/main/packages/email-rule-engine/docs/config-reference.md) |
-
-## Prerequisites
-
-| Dependency | Version | Purpose |
-|------------|---------|---------|
-| Node.js | >= 18 | Runtime |
-| MongoDB | >= 5.0 | Data storage (5 collections auto-created) |
-| Redis | >= 6.0 | Distributed locking |
-
-### Peer Dependencies
+// Trigger a run programmatically (e.g., from a cron job)
+// await engine.runner.runAllRules('cron');
 
-```bash
-npm install express mongoose ioredis handlebars mjml html-to-text
+app.listen(3000);
 ```
 
-| Package | Version | Purpose |
-|---------|---------|---------|
-| `express` | ^4.18 or ^5.0 | HTTP routes |
-| `mongoose` | ^7.0 or ^8.0 | MongoDB ODM |
-| `ioredis` | ^5.0 | Redis client |
-| `handlebars` | ^4.7 | Template variables |
-| `mjml` | ^4.0 | Responsive email HTML |
-| `html-to-text` | ^9.0 | Plain text fallback |
+The factory returns an `EmailRuleEngine` instance with:
+
+- `routes` -- Express Router with all CRUD and runner endpoints
+- `runner` -- `RuleRunnerService` for triggering runs programmatically
+- `templateService` -- `TemplateService` for CRUD and preview
+- `ruleService` -- `RuleService` for CRUD and dry runs
+- `models` -- Direct Mongoose model access (`EmailTemplate`, `EmailRule`, `EmailRuleSend`, `EmailRuleRunLog`, `EmailThrottleConfig`)
+
+## Configuration
+
+The `createEmailRuleEngine(config)` factory accepts an `EmailRuleEngineConfig` object validated at startup with Zod.
+
+| Section | Required | Description |
+|---------|----------|-------------|
+| `db` | Yes | Mongoose connection and optional collection prefix |
+| `redis` | Yes | ioredis connection for distributed locking |
+| `adapters` | Yes | 5 required + 1 optional function bridging your app to the engine |
+| `platforms` | No | Valid platform values for schema validation |
+| `audiences` | No | Valid audience/role values for schema validation |
+| `categories` | No | Valid template categories for schema validation |
+| `options` | No | Lock TTL, max per run, send window, delays |
+| `hooks` | No | Callbacks at key execution points |
+| `logger` | No | Logger with `info`, `warn`, `error` methods |
+
+See [docs/configuration.md](docs/configuration.md) for the full reference with examples.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Configuration](docs/configuration.md) | Full config reference -- db, redis, adapters, platforms, options, hooks, logger |
+| [Adapters](docs/adapters.md) | All 6 adapters with type signatures and example implementations |
+| [Templates](docs/templates.md) | Creating templates, MJML + Handlebars syntax, built-in helpers |
+| [Rules](docs/rules.md) | Targeting conditions, operators, sendOnce/resend, dry runs |
+| [Throttling](docs/throttling.md) | Per-user limits, global caps, bypass rules, tracking |
+| [API Routes](docs/api-routes.md) | All REST endpoints with curl examples |
+| [Programmatic API](docs/programmatic-api.md) | Using services directly -- runner, templateService, ruleService |
+| [Execution Flow](docs/execution-flow.md) | Step-by-step runner flow and error behavior |
+| [Error Handling](docs/error-handling.md) | All error classes with codes and when thrown |
+| [Constants](docs/constants.md) | All exported constants and derived types |
+| [Migration v1 to v2](docs/migration-v1-to-v2.md) | Breaking changes from v1 |
 
 ## License