mailery 0.12.0 → 0.13.0

package/dist/{null-CfzvqNEp.d.cts → null-DDg3ojHe.d.cts}

@@ -407,6 +407,20 @@ type QueueDriverConfig = {
     processEverySeconds?: number;
     lockLifetimeSeconds?: number;
     collectionName?: string;
+    /**
+     * Namespaces the jobs collection (`_mailerJobs_<prefix>`) so multiple
+     * mailery instances can share one Mongo database — the counterpart to
+     * the Bull driver's Redis key prefix, and read from the same
+     * `MAILER_QUEUE_PREFIX` env var. Ignored when `collectionName` is set.
+     * Letters, digits, '_' and '-' only.
+     */
+    prefix?: string;
+    /**
+     * Days to retain failed job documents before the driver sweeps them
+     * (default 7, matching the Bull driver's `removeOnFail` age). 0 disables
+     * the sweep. Succeeded jobs are removed on completion regardless.
+     */
+    failedJobRetentionDays?: number;
 } | {
     driver: 'noop';
 };
@@ -1420,7 +1434,8 @@ declare class Mailer {
      *   MAILER_MONGODB_URI                — Mongo connection string (required)
      *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
      *   MAILER_REDIS_URL                  — Redis connection URL (required)
-     *   MAILER_QUEUE_PREFIX               — Redis key prefix to namespace this instance (optional)
+     *   MAILER_QUEUE_PREFIX               — namespaces this instance (optional). Bull: Redis key
+     *                                       prefix. Agenda: jobs collection suffix.
      *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
      *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
      *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)

package/dist/{null-CfzvqNEp.d.ts → null-DDg3ojHe.d.ts}

@@ -407,6 +407,20 @@ type QueueDriverConfig = {
     processEverySeconds?: number;
     lockLifetimeSeconds?: number;
     collectionName?: string;
+    /**
+     * Namespaces the jobs collection (`_mailerJobs_<prefix>`) so multiple
+     * mailery instances can share one Mongo database — the counterpart to
+     * the Bull driver's Redis key prefix, and read from the same
+     * `MAILER_QUEUE_PREFIX` env var. Ignored when `collectionName` is set.
+     * Letters, digits, '_' and '-' only.
+     */
+    prefix?: string;
+    /**
+     * Days to retain failed job documents before the driver sweeps them
+     * (default 7, matching the Bull driver's `removeOnFail` age). 0 disables
+     * the sweep. Succeeded jobs are removed on completion regardless.
+     */
+    failedJobRetentionDays?: number;
 } | {
     driver: 'noop';
 };
@@ -1420,7 +1434,8 @@ declare class Mailer {
      *   MAILER_MONGODB_URI                — Mongo connection string (required)
      *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
      *   MAILER_REDIS_URL                  — Redis connection URL (required)
-     *   MAILER_QUEUE_PREFIX               — Redis key prefix to namespace this instance (optional)
+     *   MAILER_QUEUE_PREFIX               — namespaces this instance (optional). Bull: Redis key
+     *                                       prefix. Agenda: jobs collection suffix.
      *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
      *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
      *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)

package/dist/testing.cjs

@@ -14808,6 +14808,9 @@ var QUEUE_NAMES2 = {
   send: "mailer-send",
   webhook: "mailer-webhook"
 };
+var DEFAULT_COLLECTION = "_mailerJobs";
+var DEFAULT_FAILED_RETENTION_DAYS = 7;
+var FAILED_SWEEP_INTERVAL_MS = 60 * 60 * 1e3;
 var AgendaDriver = class _AgendaDriver {
   queues;
   agenda;
@@ -14825,7 +14828,7 @@ var AgendaDriver = class _AgendaDriver {
         "mailery: queue driver 'agenda' requires the 'agenda' and '@agendajs/mongo-backend' peer dependencies. Run `npm install agenda @agendajs/mongo-backend bottleneck`."
       );
     }
-    const collectionName = opts.collectionName ?? "_mailerJobs";
+    const collectionName = opts.collectionName ?? collectionFor(opts.prefix);
     const backend = new backendMod.MongoBackend({
       mongo: opts.db,
       collection: collectionName
@@ -14835,17 +14838,29 @@ var AgendaDriver = class _AgendaDriver {
       processEvery: `${opts.processEverySeconds ?? 5} seconds`,
       defaultLockLifetime: (opts.lockLifetimeSeconds ?? 10 * 60) * 1e3,
       maxConcurrency: 50,
-      defaultConcurrency: 5
+      defaultConcurrency: 5,
+      // Drop succeeded one-shot jobs instead of retaining them forever.
+      // Agenda guards this on `!nextRunAt`, so repeating jobs survive.
+      removeOnComplete: true
     });
-    return new _AgendaDriver(agenda, agendaMod, opts.db, collectionName);
+    const retentionDays = opts.failedJobRetentionDays ?? DEFAULT_FAILED_RETENTION_DAYS;
+    try {
+      await opts.db.collection(collectionName).createIndex({ failedAt: 1 }, { sparse: true });
+    } catch (err) {
+      console.error("mailery: could not index the Agenda jobs collection on failedAt", err);
+    }
+    return new _AgendaDriver(agenda, agendaMod, opts.db, collectionName, retentionDays);
   }
   db;
   collName;
-  constructor(agenda, agendaMod, db, collectionName) {
+  failedRetentionDays;
+  sweepTimer = null;
+  constructor(agenda, agendaMod, db, collectionName, failedRetentionDays) {
     this.agenda = agenda;
     this.agendaMod = agendaMod;
     this.db = db;
     this.collName = collectionName;
+    this.failedRetentionDays = failedRetentionDays;
     this.queues = {
       tick: this.makeQueueAPI(QUEUE_NAMES2.tick),
       advance: this.makeQueueAPI(QUEUE_NAMES2.advance),
@@ -14926,9 +14941,45 @@ var AgendaDriver = class _AgendaDriver {
     if (!this.started) {
       await this.agenda.start();
       this.started = true;
+      this.startFailedJobSweep();
+    }
+  }
+  /**
+   * Agenda's auto-remove only fires on success, so failed documents would
+   * otherwise be retained forever. Runs once on worker start, then hourly.
+   */
+  startFailedJobSweep() {
+    if (this.failedRetentionDays <= 0 || this.sweepTimer) return;
+    void this.sweepFailedJobs();
+    this.sweepTimer = setInterval(() => void this.sweepFailedJobs(), FAILED_SWEEP_INTERVAL_MS);
+    this.sweepTimer.unref?.();
+  }
+  /** Delete failed, fully-retired job documents older than the retention window. */
+  async sweepFailedJobs() {
+    const cutoff = new Date(Date.now() - this.failedRetentionDays * 24 * 3600 * 1e3);
+    try {
+      const res = await this.jobsCollection().deleteMany({
+        failedAt: { $lt: cutoff },
+        // Never touch the repeating tick.
+        repeatInterval: { $in: [null, void 0] },
+        // Leave anything still scheduled for a retry, and anything a worker
+        // currently holds a lock on.
+        $and: [
+          { $or: [{ nextRunAt: null }, { nextRunAt: { $exists: false } }, { nextRunAt: { $lt: cutoff } }] },
+          { $or: [{ lockedAt: null }, { lockedAt: { $exists: false } }, { lockedAt: { $lt: cutoff } }] }
+        ]
+      });
+      return res.deletedCount ?? 0;
+    } catch (err) {
+      console.error("mailery: failed-job sweep failed", err);
+      return 0;
     }
   }
   async stopWorkers() {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
     if (!this.started) return;
     await this.agenda.stop();
     this.started = false;
@@ -14942,6 +14993,15 @@ var AgendaDriver = class _AgendaDriver {
     await this.stopWorkers();
   }
 };
+function collectionFor(prefix) {
+  if (!prefix) return DEFAULT_COLLECTION;
+  if (!/^[A-Za-z0-9_-]+$/.test(prefix)) {
+    throw new Error(
+      `mailery: queue prefix "${prefix}" must contain only letters, digits, '_' or '-' \u2014 it becomes part of a MongoDB collection name.`
+    );
+  }
+  return `${DEFAULT_COLLECTION}_${prefix}`;
+}
 
 // src/server/queues/noop.ts
 function noopQueueAPI() {
@@ -14978,7 +15038,9 @@ async function createQueueDriver(config, fallbackDb) {
         db: config.db ?? fallbackDb,
         processEverySeconds: config.processEverySeconds,
         lockLifetimeSeconds: config.lockLifetimeSeconds,
-        collectionName: config.collectionName
+        collectionName: config.collectionName,
+        prefix: config.prefix,
+        failedJobRetentionDays: config.failedJobRetentionDays
       });
     case "noop":
       return new NoopDriver();
@@ -17418,7 +17480,8 @@ var Mailer = class _Mailer {
    *   MAILER_MONGODB_URI                — Mongo connection string (required)
    *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
    *   MAILER_REDIS_URL                  — Redis connection URL (required)
-   *   MAILER_QUEUE_PREFIX               — Redis key prefix to namespace this instance (optional)
+   *   MAILER_QUEUE_PREFIX               — namespaces this instance (optional). Bull: Redis key
+   *                                       prefix. Agenda: jobs collection suffix.
    *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
    *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
    *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)
@@ -17467,7 +17530,7 @@ var Mailer = class _Mailer {
     }
     const defaultProvider = env.MAILER_DEFAULT_PROVIDER ?? Object.keys(providers)[0];
     const driverEnv = env.MAILER_QUEUE_DRIVER ?? "bull";
-    const queue = driverEnv === "agenda" ? { driver: "agenda" } : driverEnv === "noop" ? { driver: "noop" } : {
+    const queue = driverEnv === "agenda" ? { driver: "agenda", prefix: env.MAILER_QUEUE_PREFIX } : driverEnv === "noop" ? { driver: "noop" } : {
       driver: "bull",
       redis: { url: required("MAILER_REDIS_URL") },
       prefix: env.MAILER_QUEUE_PREFIX