mailery 0.1.2 → 0.2.0

package/dist/{null-OzIqP7A8.d.cts → null-CWw3Gpbl.d.cts}

@@ -1,7 +1,7 @@
 import { Db, ObjectId, Collection, ClientSession } from 'mongodb';
-import IORedis from 'ioredis';
 import { z } from 'zod';
 import Handlebars from 'handlebars';
+import IORedis from 'ioredis';
 
 /**
  * Shared types — used by both server and client. Stub placeholders for Phase 0.
@@ -310,6 +310,61 @@ declare const sendOneOffInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 type SendOneOffInput = z.infer<typeof sendOneOffInputSchema>;
 
+/**
+ * Queue driver abstraction. Mailer talks to a `QueueDriver` whose only required
+ * vocabulary is "add a job to one of four named queues" and "spin up a worker
+ * per queue with these handlers." Concrete drivers (BullMQ, @hokify/agenda,
+ * noop) implement this surface.
+ *
+ * Mailery targets single-process deployments; drivers are not expected to
+ * coordinate state across processes. Rate-limit semantics are documented per
+ * driver below.
+ */
+
+/** Per-call options passed to `queue.add(name, data, opts)`. */
+interface AddOptions {
+    /** Defer execution by this many ms. */
+    delay?: number;
+    /** Max attempts including the initial run. Driver may apply per-define instead of per-add. */
+    attempts?: number;
+    /** Exponential backoff base delay (ms). Driver may apply per-define instead of per-add. */
+    backoff?: {
+        type: 'exponential';
+        delay: number;
+    };
+    /** Idempotency key: if a pending job with this id already exists for this queue, the add is a no-op. */
+    jobId?: string;
+}
+interface QueueAPI {
+    add(name: string, data: unknown, opts?: AddOptions): Promise<unknown>;
+    /** Approximate count of jobs eligible-but-not-running. Used by broadcast backpressure. */
+    getWaitingCount(): Promise<number>;
+    close(): Promise<void>;
+}
+interface Queues {
+    tick: QueueAPI;
+    advance: QueueAPI;
+    send: QueueAPI;
+    webhook: QueueAPI;
+}
+/**
+ * Driver selection at Mailer.init time. The driver and its connection are
+ * declared explicitly rather than inferred — this keeps the wiring obvious and
+ * lets hosts mix-and-match (e.g. Bull in prod, noop in tests).
+ */
+type QueueDriverConfig = {
+    driver: 'bull';
+    redis: RedisOptions | IORedis;
+} | {
+    driver: 'agenda';
+    db?: Db;
+    processEverySeconds?: number;
+    lockLifetimeSeconds?: number;
+    collectionName?: string;
+} | {
+    driver: 'noop';
+};
+
 /**
  * Mailer configuration shape. Required + optional surfaces with sane defaults.
  */
@@ -337,10 +392,12 @@ interface MailerConfig {
     collectionPrefix?: string;
     adapter: ContactAdapter;
     /**
-     * Connection options, a pre-built ioredis instance, or `null` to opt out of
-     * BullMQ entirely (synchronous-only mode — used by tests).
+     * Queue driver selection. One of:
+     *   - `{ driver: 'bull', redis: ... }` — BullMQ (default for prod; requires Redis)
+     *   - `{ driver: 'agenda' }` — @hokify/agenda using this Mongo (no Redis required, single-process)
+     *   - `{ driver: 'noop' }` — no background workers (tests, synchronous-only hosts)
      */
-    redis: RedisOptions | IORedis | null;
+    queue: QueueDriverConfig;
     providers: Record<string, MailProvider>;
     defaultProvider: string;
     defaultTransactionalProvider?: string;
@@ -641,6 +698,8 @@ interface SendDoc {
     unsubscribedAt: Date | null;
     complainedAt: Date | null;
     queuedAt: Date;
+    /** Last time the row was mutated; used by the stranded-send sweep. */
+    updatedAt: Date;
     sentAt: Date | null;
     deliveredAt: Date | null;
 }
@@ -804,42 +863,6 @@ declare class EventRegistry {
     deriveKey(name: string, externalId: string, passedKey: string | undefined, now: Date): string | null;
 }
 
-/**
- * BullMQ wiring: four queues + the corresponding worker factories.
- *
- *  mailer:tick      → recovery sweep + event-trigger scan + scheduled broadcasts + outbox drain
- *  mailer:advance   → per-flow_run wakeup at nextActionAt (delayed jobs)
- *  mailer:send      → provider dispatch for a single send row
- *  mailer:webhook   → async normalization + apply of inbound provider events
- *
- * The Mailer class instantiates queues at init() and workers at startWorkers().
- * Job handlers themselves live in `runner/` and `api/webhook-processor.ts`.
- */
-
-/**
- * Minimal queue surface the runner depends on. Production wraps BullMQ; tests
- * can supply a no-op implementation.
- */
-interface QueueAPI {
-    add(name: string, data: unknown, opts?: {
-        delay?: number;
-        attempts?: number;
-        backoff?: {
-            type: 'exponential';
-            delay: number;
-        };
-        jobId?: string;
-    }): Promise<unknown>;
-    getWaitingCount(): Promise<number>;
-    close(): Promise<void>;
-}
-interface Queues {
-    tick: QueueAPI;
-    advance: QueueAPI;
-    send: QueueAPI;
-    webhook: QueueAPI;
-}
-
 /**
  * Runner context + public entry points. The shared context object is passed
  * to every handler so the runner stays a pure function over (state, action).
@@ -868,12 +891,11 @@ declare class Mailer {
     readonly collections: Collections;
     readonly adapter: ContactAdapter;
     readonly providers: Record<string, MailProvider>;
-    readonly redis: IORedis | null;
     readonly queues: Queues;
     readonly config: ResolvedConfig;
     readonly events: EventRegistry;
-    private workers;
-    private bullQueues;
+    private queueDriver;
+    private workersStarted;
     private runnerContext;
     private constructor();
     /**

package/dist/{null-OzIqP7A8.d.ts → null-CWw3Gpbl.d.ts}

@@ -1,7 +1,7 @@
 import { Db, ObjectId, Collection, ClientSession } from 'mongodb';
-import IORedis from 'ioredis';
 import { z } from 'zod';
 import Handlebars from 'handlebars';
+import IORedis from 'ioredis';
 
 /**
  * Shared types — used by both server and client. Stub placeholders for Phase 0.
@@ -310,6 +310,61 @@ declare const sendOneOffInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 type SendOneOffInput = z.infer<typeof sendOneOffInputSchema>;
 
+/**
+ * Queue driver abstraction. Mailer talks to a `QueueDriver` whose only required
+ * vocabulary is "add a job to one of four named queues" and "spin up a worker
+ * per queue with these handlers." Concrete drivers (BullMQ, @hokify/agenda,
+ * noop) implement this surface.
+ *
+ * Mailery targets single-process deployments; drivers are not expected to
+ * coordinate state across processes. Rate-limit semantics are documented per
+ * driver below.
+ */
+
+/** Per-call options passed to `queue.add(name, data, opts)`. */
+interface AddOptions {
+    /** Defer execution by this many ms. */
+    delay?: number;
+    /** Max attempts including the initial run. Driver may apply per-define instead of per-add. */
+    attempts?: number;
+    /** Exponential backoff base delay (ms). Driver may apply per-define instead of per-add. */
+    backoff?: {
+        type: 'exponential';
+        delay: number;
+    };
+    /** Idempotency key: if a pending job with this id already exists for this queue, the add is a no-op. */
+    jobId?: string;
+}
+interface QueueAPI {
+    add(name: string, data: unknown, opts?: AddOptions): Promise<unknown>;
+    /** Approximate count of jobs eligible-but-not-running. Used by broadcast backpressure. */
+    getWaitingCount(): Promise<number>;
+    close(): Promise<void>;
+}
+interface Queues {
+    tick: QueueAPI;
+    advance: QueueAPI;
+    send: QueueAPI;
+    webhook: QueueAPI;
+}
+/**
+ * Driver selection at Mailer.init time. The driver and its connection are
+ * declared explicitly rather than inferred — this keeps the wiring obvious and
+ * lets hosts mix-and-match (e.g. Bull in prod, noop in tests).
+ */
+type QueueDriverConfig = {
+    driver: 'bull';
+    redis: RedisOptions | IORedis;
+} | {
+    driver: 'agenda';
+    db?: Db;
+    processEverySeconds?: number;
+    lockLifetimeSeconds?: number;
+    collectionName?: string;
+} | {
+    driver: 'noop';
+};
+
 /**
  * Mailer configuration shape. Required + optional surfaces with sane defaults.
  */
@@ -337,10 +392,12 @@ interface MailerConfig {
     collectionPrefix?: string;
     adapter: ContactAdapter;
     /**
-     * Connection options, a pre-built ioredis instance, or `null` to opt out of
-     * BullMQ entirely (synchronous-only mode — used by tests).
+     * Queue driver selection. One of:
+     *   - `{ driver: 'bull', redis: ... }` — BullMQ (default for prod; requires Redis)
+     *   - `{ driver: 'agenda' }` — @hokify/agenda using this Mongo (no Redis required, single-process)
+     *   - `{ driver: 'noop' }` — no background workers (tests, synchronous-only hosts)
      */
-    redis: RedisOptions | IORedis | null;
+    queue: QueueDriverConfig;
     providers: Record<string, MailProvider>;
     defaultProvider: string;
     defaultTransactionalProvider?: string;
@@ -641,6 +698,8 @@ interface SendDoc {
     unsubscribedAt: Date | null;
     complainedAt: Date | null;
     queuedAt: Date;
+    /** Last time the row was mutated; used by the stranded-send sweep. */
+    updatedAt: Date;
     sentAt: Date | null;
     deliveredAt: Date | null;
 }
@@ -804,42 +863,6 @@ declare class EventRegistry {
     deriveKey(name: string, externalId: string, passedKey: string | undefined, now: Date): string | null;
 }
 
-/**
- * BullMQ wiring: four queues + the corresponding worker factories.
- *
- *  mailer:tick      → recovery sweep + event-trigger scan + scheduled broadcasts + outbox drain
- *  mailer:advance   → per-flow_run wakeup at nextActionAt (delayed jobs)
- *  mailer:send      → provider dispatch for a single send row
- *  mailer:webhook   → async normalization + apply of inbound provider events
- *
- * The Mailer class instantiates queues at init() and workers at startWorkers().
- * Job handlers themselves live in `runner/` and `api/webhook-processor.ts`.
- */
-
-/**
- * Minimal queue surface the runner depends on. Production wraps BullMQ; tests
- * can supply a no-op implementation.
- */
-interface QueueAPI {
-    add(name: string, data: unknown, opts?: {
-        delay?: number;
-        attempts?: number;
-        backoff?: {
-            type: 'exponential';
-            delay: number;
-        };
-        jobId?: string;
-    }): Promise<unknown>;
-    getWaitingCount(): Promise<number>;
-    close(): Promise<void>;
-}
-interface Queues {
-    tick: QueueAPI;
-    advance: QueueAPI;
-    send: QueueAPI;
-    webhook: QueueAPI;
-}
-
 /**
  * Runner context + public entry points. The shared context object is passed
  * to every handler so the runner stays a pure function over (state, action).
@@ -868,12 +891,11 @@ declare class Mailer {
     readonly collections: Collections;
     readonly adapter: ContactAdapter;
     readonly providers: Record<string, MailProvider>;
-    readonly redis: IORedis | null;
     readonly queues: Queues;
     readonly config: ResolvedConfig;
     readonly events: EventRegistry;
-    private workers;
-    private bullQueues;
+    private queueDriver;
+    private workersStarted;
     private runnerContext;
     private constructor();
     /**