mailery 0.1.2 → 0.2.2

package/dist/index.js

@@ -2,7 +2,6 @@ import { ObjectId } from 'mongodb';
 import crypto2 from 'crypto';
 import sgMail from '@sendgrid/mail';
 import { z } from 'zod';
-import { Queue, Worker } from 'bullmq';
 import IORedis from 'ioredis';
 import Handlebars from 'handlebars';
 import { convert } from 'html-to-text';
@@ -568,7 +567,8 @@ async function ensureIndexes(db, prefix = "mailer_") {
       { key: { flowRunId: 1 }, sparse: true },
       { key: { broadcastId: 1 }, sparse: true },
       { key: { providerMessageId: 1 }, sparse: true },
-      { key: { status: 1, queuedAt: 1 } }
+      { key: { status: 1, queuedAt: 1 } },
+      { key: { status: 1, updatedAt: 1 } }
     ]),
     c.suppressions.createIndexes([
       { key: { email: 1, scope: 1 }, unique: true, partialFilterExpression: { email: { $type: "string" } } },
@@ -715,6 +715,104 @@ function verifyDoiToken(token, secret, now = /* @__PURE__ */ new Date()) {
   if (body.x < now.getTime()) return null;
   return { externalId: body.i, expiresAt: new Date(body.x) };
 }
+var QUEUE_NAMES = {
+  tick: "mailer-tick",
+  advance: "mailer-advance",
+  send: "mailer-send",
+  webhook: "mailer-webhook"
+};
+var BullDriver = class _BullDriver {
+  queues;
+  redis;
+  bullQueues;
+  workers = null;
+  bull;
+  static async create(redisConfig) {
+    let bull;
+    try {
+      bull = await import('bullmq');
+    } catch {
+      throw new Error(
+        "mailery: queue driver 'bull' requires the 'bullmq' peer dependency. Run `npm install bullmq ioredis`."
+      );
+    }
+    const redis = isRedisLike(redisConfig) ? redisConfig : connect(redisConfig);
+    return new _BullDriver(bull, redis);
+  }
+  constructor(bull, redis) {
+    this.bull = bull;
+    this.redis = redis;
+    const opts = { connection: redis };
+    this.bullQueues = {
+      tick: new bull.Queue(QUEUE_NAMES.tick, opts),
+      advance: new bull.Queue(QUEUE_NAMES.advance, opts),
+      send: new bull.Queue(QUEUE_NAMES.send, opts),
+      webhook: new bull.Queue(QUEUE_NAMES.webhook, opts)
+    };
+    this.queues = {
+      tick: adaptBullQueue(this.bullQueues.tick),
+      advance: adaptBullQueue(this.bullQueues.advance),
+      send: adaptBullQueue(this.bullQueues.send),
+      webhook: adaptBullQueue(this.bullQueues.webhook)
+    };
+  }
+  async scheduleRepeatingTick(intervalSeconds) {
+    await this.bullQueues.tick.upsertJobScheduler(
+      "mailer-tick-repeat",
+      { every: intervalSeconds * 1e3 },
+      { name: "tick", data: {} }
+    );
+  }
+  async startWorkers(opts) {
+    if (this.workers) return;
+    const base = { connection: this.redis };
+    const { Worker } = this.bull;
+    const tick = new Worker(
+      QUEUE_NAMES.tick,
+      async (job) => opts.handlers.tick(job.data),
+      { ...base, concurrency: 1 }
+    );
+    const advance = new Worker(
+      QUEUE_NAMES.advance,
+      async (job) => opts.handlers.advance(job.data),
+      { ...base, concurrency: 10 }
+    );
+    const send = new Worker(
+      QUEUE_NAMES.send,
+      async (job) => opts.handlers.send(job.data),
+      {
+        ...base,
+        concurrency: opts.concurrency.send,
+        limiter: opts.sendRateLimit ? { max: opts.sendRateLimit.max, duration: opts.sendRateLimit.durationMs } : void 0
+      }
+    );
+    const webhook = new Worker(
+      QUEUE_NAMES.webhook,
+      async (job) => opts.handlers.webhook(job.data),
+      { ...base, concurrency: 4 }
+    );
+    this.workers = { tick, advance, send, webhook };
+  }
+  async stopWorkers() {
+    if (!this.workers) return;
+    await Promise.all([
+      this.workers.tick.close(),
+      this.workers.advance.close(),
+      this.workers.send.close(),
+      this.workers.webhook.close()
+    ]);
+    this.workers = null;
+  }
+  async close() {
+    await this.stopWorkers();
+    await Promise.all([
+      this.bullQueues.tick.close(),
+      this.bullQueues.advance.close(),
+      this.bullQueues.send.close(),
+      this.bullQueues.webhook.close()
+    ]);
+  }
+};
 function adaptBullQueue(q) {
   return {
     add: (name, data, opts) => q.add(name, data, opts),
@@ -722,39 +820,16 @@ function adaptBullQueue(q) {
     close: () => q.close()
   };
 }
-function noopQueueAPI() {
-  return {
-    add: async () => void 0,
-    getWaitingCount: async () => 0,
-    close: async () => void 0
-  };
-}
-function noopQueues() {
-  return {
-    tick: noopQueueAPI(),
-    advance: noopQueueAPI(),
-    send: noopQueueAPI(),
-    webhook: noopQueueAPI()
-  };
-}
-function namespacedQueueNames(prefix) {
-  return {
-    tick: "mailer-tick",
-    advance: "mailer-advance",
-    send: "mailer-send",
-    webhook: "mailer-webhook"
-  };
+function isRedisLike(x) {
+  return !!x && typeof x === "object" && typeof x.get === "function" && typeof x.set === "function";
 }
-function makeRedis(opts) {
-  if (isRedisLike(opts)) return opts;
+function connect(opts) {
   const config = {
     maxRetriesPerRequest: null,
     // BullMQ requirement
     enableReadyCheck: false
   };
-  if (opts.url) {
-    return new IORedis(opts.url, config);
-  }
+  if (opts.url) return new IORedis(opts.url, config);
   return new IORedis({
     ...config,
     host: opts.host ?? "127.0.0.1",
@@ -765,69 +840,198 @@ function makeRedis(opts) {
     tls: opts.tls ? {} : void 0
   });
 }
-function isRedisLike(x) {
-  return !!x && typeof x === "object" && typeof x.get === "function" && typeof x.set === "function";
-}
-function createQueues(redis) {
-  const names = namespacedQueueNames();
-  const qOpts = { connection: redis };
-  const bullQueues = {
-    tick: new Queue(names.tick, qOpts),
-    advance: new Queue(names.advance, qOpts),
-    send: new Queue(names.send, qOpts),
-    webhook: new Queue(names.webhook, qOpts)
-  };
+
+// src/server/queues/agenda.ts
+var QUEUE_NAMES2 = {
+  tick: "mailer-tick",
+  advance: "mailer-advance",
+  send: "mailer-send",
+  webhook: "mailer-webhook"
+};
+var AgendaDriver = class _AgendaDriver {
+  queues;
+  agenda;
+  agendaMod;
+  sendLimiter = null;
+  started = false;
+  static async create(opts) {
+    let agendaMod;
+    let backendMod;
+    try {
+      agendaMod = await import('agenda');
+      backendMod = await import('@agendajs/mongo-backend');
+    } catch {
+      throw new Error(
+        "mailery: queue driver 'agenda' requires the 'agenda' and '@agendajs/mongo-backend' peer dependencies. Run `npm install agenda @agendajs/mongo-backend bottleneck`."
+      );
+    }
+    const backend = new backendMod.MongoBackend({
+      mongo: opts.db,
+      collection: opts.collectionName ?? "_mailerJobs"
+    });
+    const agenda = new agendaMod.Agenda({
+      backend,
+      processEvery: `${opts.processEverySeconds ?? 5} seconds`,
+      defaultLockLifetime: (opts.lockLifetimeSeconds ?? 10 * 60) * 1e3,
+      maxConcurrency: 50,
+      defaultConcurrency: 5
+    });
+    return new _AgendaDriver(agenda, agendaMod, opts.db);
+  }
+  db;
+  constructor(agenda, agendaMod, db) {
+    this.agenda = agenda;
+    this.agendaMod = agendaMod;
+    this.db = db;
+    this.queues = {
+      tick: this.makeQueueAPI(QUEUE_NAMES2.tick),
+      advance: this.makeQueueAPI(QUEUE_NAMES2.advance),
+      send: this.makeQueueAPI(QUEUE_NAMES2.send),
+      webhook: this.makeQueueAPI(QUEUE_NAMES2.webhook)
+    };
+  }
+  makeQueueAPI(name) {
+    return {
+      add: async (_jobName, data, opts) => {
+        const payload = { ...data };
+        if (opts?.jobId) {
+          payload.__jobId = opts.jobId;
+          if (await this.findPending(name, opts.jobId)) return;
+        }
+        const job = this.agenda.create(name, payload);
+        if (opts?.delay) job.schedule(new Date(Date.now() + opts.delay));
+        await job.save();
+      },
+      getWaitingCount: async () => {
+        return this.jobsCollection().countDocuments({
+          name,
+          $or: [{ lockedAt: null }, { lockedAt: { $exists: false } }],
+          nextRunAt: { $lte: /* @__PURE__ */ new Date() }
+        });
+      },
+      close: async () => {
+      }
+    };
+  }
+  /** Direct access to the Mongo collection Agenda persists jobs into. */
+  jobsCollection() {
+    return this.db.collection(this.collectionName());
+  }
+  collectionName() {
+    return "_mailerJobs";
+  }
+  async findPending(name, jobId) {
+    return this.jobsCollection().findOne({
+      name,
+      "data.__jobId": jobId,
+      $or: [{ lastFinishedAt: null }, { lastFinishedAt: { $exists: false } }]
+    });
+  }
+  async scheduleRepeatingTick(intervalSeconds) {
+    if (!this.started) {
+      this.agenda.define(QUEUE_NAMES2.tick, async () => {
+      }, { concurrency: 1 });
+      await this.agenda.start();
+      this.started = true;
+    }
+    await this.agenda.every(`${intervalSeconds} seconds`, QUEUE_NAMES2.tick);
+  }
+  async startWorkers(opts) {
+    const exp = this.agendaMod.backoffStrategies.exponential;
+    if (opts.sendRateLimit) {
+      try {
+        const Bottleneck = (await import('bottleneck')).default;
+        this.sendLimiter = new Bottleneck({
+          minTime: Math.ceil(opts.sendRateLimit.durationMs / opts.sendRateLimit.max),
+          maxConcurrent: opts.concurrency.send
+        });
+      } catch {
+        throw new Error(
+          "mailery: queue driver 'agenda' with sendRateLimit requires the 'bottleneck' peer dependency. Run `npm install bottleneck`."
+        );
+      }
+    }
+    const retryBackoff = exp({ delay: 6e4, maxRetries: Math.max(0, opts.retryAttempts - 1), factor: 2 });
+    this.agenda.define(QUEUE_NAMES2.tick, async (job) => {
+      await opts.handlers.tick(job.attrs.data);
+    }, { concurrency: 1 });
+    this.agenda.define(QUEUE_NAMES2.advance, async (job) => {
+      await opts.handlers.advance(job.attrs.data);
+    }, { concurrency: 10, backoff: retryBackoff });
+    this.agenda.define(QUEUE_NAMES2.send, async (job) => {
+      const data = job.attrs.data;
+      if (this.sendLimiter) {
+        await this.sendLimiter.schedule(() => opts.handlers.send(data));
+      } else {
+        await opts.handlers.send(data);
+      }
+    }, { concurrency: opts.concurrency.send, backoff: retryBackoff });
+    this.agenda.define(QUEUE_NAMES2.webhook, async (job) => {
+      await opts.handlers.webhook(job.attrs.data);
+    }, { concurrency: 4, backoff: retryBackoff });
+    if (!this.started) {
+      await this.agenda.start();
+      this.started = true;
+    }
+  }
+  async stopWorkers() {
+    if (!this.started) return;
+    await this.agenda.stop();
+    this.started = false;
+    if (this.sendLimiter) {
+      await this.sendLimiter.stop({ dropWaitingJobs: true }).catch(() => {
+      });
+      this.sendLimiter = null;
+    }
+  }
+  async close() {
+    await this.stopWorkers();
+  }
+};
+
+// src/server/queues/noop.ts
+function noopQueueAPI() {
   return {
-    queues: {
-      tick: adaptBullQueue(bullQueues.tick),
-      advance: adaptBullQueue(bullQueues.advance),
-      send: adaptBullQueue(bullQueues.send),
-      webhook: adaptBullQueue(bullQueues.webhook)
-    },
-    bullQueues
+    add: async () => void 0,
+    getWaitingCount: async () => 0,
+    close: async () => void 0
   };
 }
-async function scheduleTick(bullQueues, intervalSeconds) {
-  await bullQueues.tick.upsertJobScheduler(
-    "mailer-tick-repeat",
-    { every: intervalSeconds * 1e3 },
-    { name: "tick", data: {} }
-  );
-}
-function createWorkers(input) {
-  const names = namespacedQueueNames();
-  const base = { connection: input.redis };
-  const tick = new Worker(names.tick, async (job) => input.handlers.tick(job.data), {
-    ...base,
-    concurrency: 1
-    // single tick driver per worker process
-  });
-  const advance = new Worker(
-    names.advance,
-    async (job) => input.handlers.advance(job.data),
-    { ...base, concurrency: 10 }
-  );
-  const sendOpts = {
-    ...base,
-    concurrency: input.concurrency.send,
-    limiter: input.sendRateLimit ? { max: input.sendRateLimit.max, duration: input.sendRateLimit.durationMs } : void 0
+var NoopDriver = class {
+  queues = {
+    tick: noopQueueAPI(),
+    advance: noopQueueAPI(),
+    send: noopQueueAPI(),
+    webhook: noopQueueAPI()
   };
-  const send = new Worker(names.send, async (job) => input.handlers.send(job.data), sendOpts);
-  const webhook = new Worker(
-    names.webhook,
-    async (job) => input.handlers.webhook(job.data),
-    { ...base, concurrency: 4 }
-  );
-  return { tick, advance, send, webhook };
-}
-async function closeQueues(queues) {
-  await Promise.all([queues.tick.close(), queues.advance.close(), queues.send.close(), queues.webhook.close()]);
-}
-async function closeBullQueues(b) {
-  await Promise.all([b.tick.close(), b.advance.close(), b.send.close(), b.webhook.close()]);
-}
-async function closeWorkers(workers) {
-  await Promise.all([workers.tick.close(), workers.advance.close(), workers.send.close(), workers.webhook.close()]);
+  async scheduleRepeatingTick(_intervalSeconds) {
+  }
+  async startWorkers(_opts) {
+  }
+  async stopWorkers() {
+  }
+  async close() {
+  }
+};
+
+// src/server/queues/index.ts
+async function createQueueDriver(config, fallbackDb) {
+  switch (config.driver) {
+    case "bull":
+      return BullDriver.create(config.redis);
+    case "agenda":
+      return AgendaDriver.create({
+        db: config.db ?? fallbackDb,
+        processEverySeconds: config.processEverySeconds,
+        lockLifetimeSeconds: config.lockLifetimeSeconds,
+        collectionName: config.collectionName
+      });
+    case "noop":
+      return new NoopDriver();
+    default: {
+      throw new Error(`mailery: unknown queue driver`);
+    }
+  }
 }
 
 // src/server/runner/triggers.ts
@@ -1320,7 +1524,8 @@ async function dispatchSend(sendId, ctx) {
         status: "sending",
         fromName: rendered.fromName,
         fromEmail: rendered.fromEmail,
-        subject: rendered.subject
+        subject: rendered.subject,
+        updatedAt: /* @__PURE__ */ new Date()
       }
     }
   );
@@ -1394,6 +1599,7 @@ function buildRenderContext(contact, run, vars, ctx) {
   };
 }
 function newSendDoc(input) {
+  const now = /* @__PURE__ */ new Date();
   return {
     _id: input._id,
     dedupeKey: input.dedupeKey,
@@ -1424,7 +1630,8 @@ function newSendDoc(input) {
     clickedLinks: [],
     unsubscribedAt: null,
     complainedAt: null,
-    queuedAt: /* @__PURE__ */ new Date(),
+    queuedAt: now,
+    updatedAt: now,
     sentAt: null,
     deliveredAt: null
   };
@@ -1906,6 +2113,7 @@ async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, resp
     unsubscribedAt: null,
     complainedAt: null,
     queuedAt: /* @__PURE__ */ new Date(),
+    updatedAt: /* @__PURE__ */ new Date(),
     sentAt: null,
     deliveredAt: null
   };
@@ -1978,13 +2186,36 @@ async function promoteSoftBounces(ctx) {
 }
 
 // src/server/runner/tick.ts
+var STRANDED_SEND_THRESHOLD_MS = 5 * 60 * 1e3;
 async function runTick(ctx) {
+  await ctx.collections.health.updateOne(
+    { _id: "singleton" },
+    {
+      $set: { updatedAt: /* @__PURE__ */ new Date() },
+      $setOnInsert: {
+        _id: "singleton",
+        windowStartedAt: /* @__PURE__ */ new Date(),
+        windowDurationMs: ctx.config.circuitBreaker.windowMinutes * 60 * 1e3,
+        status: "healthy",
+        trippedAt: null,
+        trippedReason: null,
+        manuallyResumedAt: null,
+        counters: { sent: 0, delivered: 0, bounced: 0, hardBounced: 0, softBounced: 0, complained: 0, failedToSend: 0 },
+        rates: { bounceRate: 0, hardBounceRate: 0, complaintRate: 0, failureRate: 0 }
+      }
+    },
+    { upsert: true }
+  ).catch(() => {
+  });
   await processNewlyFiredEventTriggers(ctx).catch((err) => {
     console.error("mailery: triggers scan failed", err);
   });
   await sweepStrandedFlowRuns(ctx).catch((err) => {
     console.error("mailery: sweep failed", err);
   });
+  await sweepStrandedSends(ctx).catch((err) => {
+    console.error("mailery: stranded-send sweep failed", err);
+  });
   await drainOutbox(ctx).catch((err) => {
     console.error("mailery: outbox drain failed", err);
   });
@@ -1998,6 +2229,24 @@ async function runTick(ctx) {
     console.error("mailery: soft-bounce promotion failed", err);
   });
 }
+async function sweepStrandedSends(ctx) {
+  const cutoff = new Date(Date.now() - STRANDED_SEND_THRESHOLD_MS);
+  const cursor = ctx.collections.sends.find(
+    { status: "sending", updatedAt: { $lt: cutoff } },
+    { projection: { _id: 1 } }
+  ).limit(500);
+  for await (const row of cursor) {
+    const reset = await ctx.collections.sends.updateOne(
+      { _id: row._id, status: "sending", updatedAt: { $lt: cutoff } },
+      { $set: { status: "queued", updatedAt: /* @__PURE__ */ new Date() } }
+    );
+    if (reset.modifiedCount === 0) continue;
+    await ctx.queues.send.add("send", { sendId: String(row._id) }, {
+      attempts: ctx.config.sendRetryAttempts,
+      backoff: { type: "exponential", delay: 6e4 }
+    });
+  }
+}
 async function drainOutbox(ctx) {
   const batch = await ctx.collections.outbox.find({ status: "pending" }).sort({ enqueuedAt: 1 }).limit(200).toArray();
   for (const row of batch) {
@@ -2168,12 +2417,11 @@ var Mailer = class _Mailer {
   collections;
   adapter;
   providers;
-  redis;
   queues;
   config;
   events;
-  workers = null;
-  bullQueues;
+  queueDriver;
+  workersStarted = false;
   runnerContext;
   constructor(args) {
     this.config = args.config;
@@ -2181,9 +2429,8 @@ var Mailer = class _Mailer {
     this.collections = args.collections;
     this.adapter = args.adapter;
     this.providers = args.providers;
-    this.redis = args.redis;
-    this.queues = args.queues;
-    this.bullQueues = args.bullQueues;
+    this.queueDriver = args.queueDriver;
+    this.queues = args.queueDriver.queues;
     this.events = args.events;
     this.runnerContext = {
       db: this.db,
@@ -2248,10 +2495,12 @@ var Mailer = class _Mailer {
       throw new Error("Mailer.fromEnv: no provider configured (set MAILER_SENDGRID_API_KEY, ...)");
     }
     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" } : { driver: "bull", redis: { url: required("MAILER_REDIS_URL") } };
     return _Mailer.init({
       db,
       adapter,
-      redis: { url: required("MAILER_REDIS_URL") },
+      queue,
       providers,
       defaultProvider,
       publicUrl: required("MAILER_PUBLIC_URL"),
@@ -2267,19 +2516,9 @@ var Mailer = class _Mailer {
     }
     const collections = getCollections(config.db, config.collectionPrefix);
     await ensureIndexes(config.db, config.collectionPrefix);
-    let redis = null;
-    let queues;
-    let bullQueues = null;
-    if (config.redis === null) {
-      queues = noopQueues();
-    } else {
-      redis = makeRedis(config.redis);
-      const created = createQueues(redis);
-      queues = created.queues;
-      bullQueues = created.bullQueues;
-      if (!config.workerless) {
-        await scheduleTick(bullQueues, config.tickIntervalSeconds);
-      }
+    const queueDriver = await createQueueDriver(config.queue, config.db);
+    if (!config.workerless && config.queue.driver !== "noop") {
+      await queueDriver.scheduleRepeatingTick(config.tickIntervalSeconds);
     }
     return new _Mailer({
       config,
@@ -2287,9 +2526,7 @@ var Mailer = class _Mailer {
       collections,
       adapter: config.adapter,
       providers: config.providers,
-      redis,
-      queues,
-      bullQueues,
+      queueDriver,
       events: new EventRegistry()
     });
   }
@@ -2597,6 +2834,7 @@ var Mailer = class _Mailer {
       unsubscribedAt: null,
       complainedAt: null,
       queuedAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date(),
       sentAt: null,
       deliveredAt: null
     });
@@ -2628,14 +2866,16 @@ var Mailer = class _Mailer {
   // Workers
   // -------------------------------------------------------------------------
   async startWorkers() {
-    if (this.workers) return;
-    if (!this.redis) throw new Error("startWorkers requires a Redis connection (redis was null in config)");
+    if (this.workersStarted) return;
+    if (this.config.queue.driver === "noop") {
+      throw new Error("startWorkers requires a non-noop queue driver");
+    }
     const provider = this.providers[this.config.defaultProvider];
     const sendRate = provider?.sendRatePerSecond ?? this.config.sendRatePerSecond;
-    this.workers = createWorkers({
-      redis: this.redis,
+    await this.queueDriver.startWorkers({
       concurrency: { send: this.config.sendConcurrency },
       sendRateLimit: { max: sendRate, durationMs: 1e3 },
+      retryAttempts: this.config.sendRetryAttempts,
       handlers: {
         tick: async () => {
           await runTick(this.runnerContext);
@@ -2653,6 +2893,7 @@ var Mailer = class _Mailer {
         }
       }
     });
+    this.workersStarted = true;
   }
   /** Process unprocessed webhook events in mailer_webhook_events. */
   async processWebhookBacklog() {
@@ -2679,20 +2920,8 @@ var Mailer = class _Mailer {
     }
   }
   async stop() {
-    if (this.workers) {
-      await closeWorkers(this.workers);
-      this.workers = null;
-    }
-    if (this.bullQueues) {
-      await closeBullQueues(this.bullQueues);
-      this.bullQueues = null;
-    } else {
-      await closeQueues(this.queues);
-    }
-    if (this.redis) {
-      await this.redis.quit().catch(() => {
-      });
-    }
+    await this.queueDriver.close();
+    this.workersStarted = false;
   }
   /** Used internally by the admin router and tests; not part of the public API. */
   getRunnerContext() {
@@ -2700,6 +2929,43 @@ var Mailer = class _Mailer {
   }
 };
 
+// src/server/templates/sender-domain.ts
+function validateSenderDomain(fromEmail, templateKind, registry) {
+  if (!registry || Object.keys(registry).length === 0) return { ok: true };
+  const domain = extractDomain(fromEmail);
+  if (!domain) {
+    return {
+      ok: false,
+      code: "invalid_email",
+      reason: `invalid fromEmail "${fromEmail}" \u2014 expected "name@domain"`
+    };
+  }
+  const entry = registry[domain];
+  if (!entry) {
+    const known = Object.keys(registry).join(", ");
+    return {
+      ok: false,
+      code: "unregistered_domain",
+      reason: `sender domain "${domain}" is not declared in senderDomains (allowed: ${known})`
+    };
+  }
+  if (entry.kind === "both") return { ok: true };
+  if (entry.kind !== templateKind) {
+    return {
+      ok: false,
+      code: "wrong_kind",
+      reason: `sender domain "${domain}" is configured for ${entry.kind} email, but this template's kind is ${templateKind}`
+    };
+  }
+  return { ok: true };
+}
+function extractDomain(email) {
+  if (typeof email !== "string") return null;
+  const at = email.lastIndexOf("@");
+  if (at <= 0 || at === email.length - 1) return null;
+  return email.slice(at + 1).toLowerCase().trim();
+}
+
 // src/server/index.ts
 init_mongo();
 
@@ -2729,6 +2995,227 @@ var NullProvider = class {
 
 // src/server/index.ts
 init_sendgrid();
+
+// src/server/api/setup-status.ts
+async function runSetupChecks(mailer) {
+  const checks = [];
+  checks.push(await checkMongo(mailer));
+  checks.push(await checkQueue(mailer));
+  if (mailer.config.queue.driver !== "noop" && !mailer.config.workerless) {
+    checks.push(await checkWorkersHeartbeat(mailer));
+  }
+  checks.push(await checkCircuitBreaker(mailer));
+  checks.push(...checkFromDefaultsAgainstRegistry(mailer));
+  checks.push(...await checkPublishedTemplates(mailer));
+  checks.push(await checkPostalAddress(mailer));
+  checks.push(await checkDoiTemplate(mailer));
+  const overall = checks.some((c) => c.severity === "error") ? "error" : checks.some((c) => c.severity === "warn") ? "warn" : "ok";
+  return {
+    overall,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    checks
+  };
+}
+async function checkMongo(mailer) {
+  try {
+    await mailer.db.admin().ping();
+    return { name: "mongo", label: "MongoDB connection", severity: "ok", message: "reachable" };
+  } catch (err) {
+    return {
+      name: "mongo",
+      label: "MongoDB connection",
+      severity: "error",
+      message: `MongoDB ping failed: ${err?.message ?? err}`,
+      hint: "Mailery is configured against an unreachable Mongo. Sends, flow advancement, and admin reads will all fail."
+    };
+  }
+}
+async function checkQueue(mailer) {
+  const driver = mailer.config.queue.driver;
+  if (driver === "noop") {
+    return {
+      name: "queue",
+      label: "Queue driver",
+      severity: "ok",
+      message: "driver: noop (synchronous-only mode)"
+    };
+  }
+  try {
+    await mailer.queues.send.getWaitingCount();
+    return { name: "queue", label: "Queue driver", severity: "ok", message: `driver: ${driver}` };
+  } catch (err) {
+    return {
+      name: "queue",
+      label: "Queue driver",
+      severity: "error",
+      message: `${driver} queue is not responding: ${err?.message ?? err}`,
+      hint: driver === "bull" ? "Check Redis connectivity (queue.redis.url)." : "Check the @hokify/agenda + Mongo connection."
+    };
+  }
+}
+async function checkWorkersHeartbeat(mailer) {
+  const h = await mailer.collections.health.findOne({ _id: "singleton" });
+  const tickIntervalMs = mailer.config.tickIntervalSeconds * 1e3;
+  const staleAfterMs = Math.max(tickIntervalMs * 3, 3e4);
+  if (!h) {
+    return {
+      name: "workers_heartbeat",
+      label: "Background workers",
+      severity: "warn",
+      message: "no tick has run yet",
+      hint: "If your separate worker process is started, the heartbeat will appear within one tick interval. If you forgot to run `mailer.startWorkers()`, sends will sit queued indefinitely."
+    };
+  }
+  const ageMs = Date.now() - new Date(h.updatedAt).getTime();
+  if (ageMs > staleAfterMs) {
+    return {
+      name: "workers_heartbeat",
+      label: "Background workers",
+      severity: "error",
+      message: `last tick ${humanDuration(ageMs)} ago (expected within ${humanDuration(tickIntervalMs)})`,
+      hint: "Workers appear to be down. Sends and flow advancement are halted. Restart your worker process (`mailer.startWorkers()`)."
+    };
+  }
+  return {
+    name: "workers_heartbeat",
+    label: "Background workers",
+    severity: "ok",
+    message: `last tick ${humanDuration(ageMs)} ago`
+  };
+}
+async function checkCircuitBreaker(mailer) {
+  const h = await mailer.collections.health.findOne({ _id: "singleton" });
+  if (!h || h.status === "healthy") {
+    return { name: "circuit_breaker", label: "Circuit breaker", severity: "ok", message: "healthy" };
+  }
+  if (h.status === "degraded") {
+    return {
+      name: "circuit_breaker",
+      label: "Circuit breaker",
+      severity: "warn",
+      message: "degraded (high failure rate)",
+      hint: "Marketing sends still flow but failure rate is above the degraded threshold. Investigate provider errors before they escalate to tripped."
+    };
+  }
+  return {
+    name: "circuit_breaker",
+    label: "Circuit breaker",
+    severity: "error",
+    message: `tripped: ${h.trippedReason ?? "unknown reason"}`,
+    hint: "Marketing sends are held. Investigate the underlying bounce / complaint cause, then POST /api/health/resume."
+  };
+}
+function checkFromDefaultsAgainstRegistry(mailer) {
+  const registry = mailer.config.senderDomains;
+  if (!registry || Object.keys(registry).length === 0) return [];
+  const out = [];
+  const from = mailer.config.fromDefaults?.email;
+  const tx = mailer.config.transactionalFromDefaults?.email;
+  if (from) {
+    const r = validateSenderDomain(from, "marketing", registry);
+    if (!r.ok) {
+      out.push({
+        name: "from_defaults_marketing",
+        label: "fromDefaults vs senderDomains",
+        severity: "error",
+        message: r.reason,
+        hint: "New marketing templates that fall back to fromDefaults will fail to publish."
+      });
+    }
+  }
+  if (tx) {
+    const r = validateSenderDomain(tx, "transactional", registry);
+    if (!r.ok) {
+      out.push({
+        name: "transactional_from_defaults",
+        label: "transactionalFromDefaults vs senderDomains",
+        severity: "error",
+        message: r.reason,
+        hint: "New transactional templates that fall back to transactionalFromDefaults will fail to publish."
+      });
+    }
+  } else if (from) {
+    const r = validateSenderDomain(from, "transactional", registry);
+    if (!r.ok) {
+      out.push({
+        name: "transactional_fallback",
+        label: "Transactional fallback",
+        severity: "warn",
+        message: `transactionalFromDefaults is unset and fromDefaults (${from}) is invalid for transactional templates`,
+        hint: 'Set transactionalFromDefaults to a transactional-kind domain, or set senderDomains entry for the existing one to "both".'
+      });
+    }
+  }
+  return out;
+}
+async function checkPublishedTemplates(mailer) {
+  const registry = mailer.config.senderDomains;
+  if (!registry || Object.keys(registry).length === 0) return [];
+  const published = await mailer.collections.templates.find({ publishedAt: { $ne: null } }, { projection: { slug: 1, kind: 1, fromEmail: 1 } }).toArray();
+  const broken = [];
+  for (const tpl of published) {
+    const r = validateSenderDomain(tpl.fromEmail, tpl.kind, registry);
+    if (!r.ok) broken.push({ slug: tpl.slug, reason: r.reason });
+  }
+  if (broken.length === 0) return [];
+  const list = broken.slice(0, 5).map((b) => `${b.slug} (${b.reason})`).join("; ");
+  const more = broken.length > 5 ? ` \u2026and ${broken.length - 5} more` : "";
+  return [
+    {
+      name: "published_template_domains",
+      label: "Published templates",
+      severity: "error",
+      message: `${broken.length} published template${broken.length === 1 ? "" : "s"} use a fromEmail that no longer matches senderDomains: ${list}${more}`,
+      hint: "These templates will still send with their stored fromEmail until re-published. Edit each template and republish to surface the validation, or update senderDomains."
+    }
+  ];
+}
+async function checkPostalAddress(mailer) {
+  if (mailer.config.senderAddress) {
+    return { name: "postal_address", label: "CAN-SPAM postal address", severity: "ok", message: "set" };
+  }
+  const marketingCount = await mailer.collections.templates.countDocuments({
+    kind: "marketing",
+    publishedAt: { $ne: null }
+  });
+  if (marketingCount === 0) {
+    return { name: "postal_address", label: "CAN-SPAM postal address", severity: "ok", message: "no published marketing templates yet" };
+  }
+  return {
+    name: "postal_address",
+    label: "CAN-SPAM postal address",
+    severity: "warn",
+    message: `${marketingCount} published marketing template${marketingCount === 1 ? "" : "s"} but senderAddress is unset`,
+    hint: "CAN-SPAM requires a postal address in marketing emails. Set `senderAddress` in your Mailer config and reference it via `{{senderAddress}}` in your templates."
+  };
+}
+async function checkDoiTemplate(mailer) {
+  if (!mailer.config.requireDoubleOptIn) {
+    return { name: "doi_template", label: "DOI template", severity: "ok", message: "DOI not required" };
+  }
+  const tpl = await mailer.collections.templates.findOne({
+    slug: mailer.config.doiTemplateSlug,
+    publishedAt: { $ne: null }
+  });
+  if (tpl) {
+    return { name: "doi_template", label: "DOI template", severity: "ok", message: `template "${tpl.slug}" published` };
+  }
+  return {
+    name: "doi_template",
+    label: "DOI template",
+    severity: "error",
+    message: `requireDoubleOptIn is true but no published template with slug "${mailer.config.doiTemplateSlug}"`,
+    hint: "New subscriptions will silently fail to send confirmation emails. Create and publish a template with this slug, or unset requireDoubleOptIn."
+  };
+}
+function humanDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
+  return `${Math.round(ms / 36e5)}h`;
+}
+
+// src/server/api/admin.ts
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = path.dirname(__filename$1);
 function defaultSpaDir() {
@@ -2950,6 +3437,13 @@ function apiRouter(mailer) {
       res.json(rows);
     })
   );
+  r.get(
+    "/setup-status",
+    asyncHandler(async (_req, res) => {
+      const status = await runSetupChecks(mailer);
+      res.json(status);
+    })
+  );
   r.get(
     "/health",
     asyncHandler(async (_req, res) => {
@@ -3123,6 +3617,15 @@ function apiRouter(mailer) {
       if (kind !== "marketing" && kind !== "transactional") {
         return res.status(400).json({ error: "validation_failed", message: "kind must be marketing or transactional" });
       }
+      const resolvedFromEmail = fromEmail ?? (kind === "transactional" ? mailer.config.transactionalFromDefaults?.email : void 0) ?? mailer.config.fromDefaults?.email ?? "noreply@example.com";
+      const senderCheck = validateSenderDomain(resolvedFromEmail, kind, mailer.config.senderDomains);
+      if (!senderCheck.ok) {
+        return res.status(400).json({
+          error: "sender_domain_invalid",
+          code: senderCheck.code,
+          message: senderCheck.reason
+        });
+      }
       const now = /* @__PURE__ */ new Date();
       try {
         await c.templates.insertOne({
@@ -3130,8 +3633,8 @@ function apiRouter(mailer) {
           name,
           description: "",
           kind,
-          fromName: fromName ?? mailer.config.fromDefaults?.name ?? "Mailery",
-          fromEmail: fromEmail ?? mailer.config.fromDefaults?.email ?? "noreply@example.com",
+          fromName: fromName ?? (kind === "transactional" ? mailer.config.transactionalFromDefaults?.name : void 0) ?? mailer.config.fromDefaults?.name ?? "Mailery",
+          fromEmail: resolvedFromEmail,
           replyTo: null,
           providerOverride: null,
           subject: subject ?? `Untitled \u2014 ${name}`,
@@ -3189,6 +3692,18 @@ function apiRouter(mailer) {
       if (typeof fromEmail === "string") set.fromEmail = fromEmail;
       if (typeof replyTo === "string" || replyTo === null) set.replyTo = replyTo;
       if (kind === "marketing" || kind === "transactional") set.kind = kind;
+      if (typeof fromEmail === "string" || kind === "marketing" || kind === "transactional") {
+        const resultingKind = set.kind ?? tpl.kind;
+        const resultingFromEmail = set.fromEmail ?? tpl.fromEmail;
+        const senderCheck = validateSenderDomain(resultingFromEmail, resultingKind, mailer.config.senderDomains);
+        if (!senderCheck.ok) {
+          return res.status(400).json({
+            error: "sender_domain_invalid",
+            code: senderCheck.code,
+            message: senderCheck.reason
+          });
+        }
+      }
       if (typeof trackOpens === "boolean") set.trackOpens = trackOpens;
       if (typeof trackClicks === "boolean") set.trackClicks = trackClicks;
       await c.templates.updateOne({ _id: tpl._id }, { $set: set });
@@ -3207,6 +3722,14 @@ function apiRouter(mailer) {
       if (!tpl) return res.status(404).json({ error: "not_found" });
       const draft = tpl.draft;
       if (!draft) return res.status(400).json({ error: "no_draft" });
+      const senderCheck = validateSenderDomain(tpl.fromEmail, tpl.kind, mailer.config.senderDomains);
+      if (!senderCheck.ok) {
+        return res.status(400).json({
+          error: "sender_domain_invalid",
+          code: senderCheck.code,
+          message: senderCheck.reason
+        });
+      }
       let compiled;
       if (draft.editorJson) {
         compiled = await compileMailyTemplate(draft.editorJson);
@@ -3817,6 +4340,6 @@ var DEDUPE_POLICIES = [
 // src/server/index.ts
 var VERSION = "0.1.0";
 
-export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };
+export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, validateSenderDomain, verifyUnsubscribeToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map