mailery 0.7.0 → 0.8.1

package/dist/index.cjs

@@ -653,6 +653,7 @@ async function ensureIndexes(db, prefix = "mailer_") {
       { key: { dedupeKey: 1 }, unique: true },
       { key: { externalId: 1, occurredAt: -1 } },
       { key: { name: 1, occurredAt: -1 } },
+      { key: { name: 1, createdAt: 1 } },
       { key: { externalId: 1, name: 1 } }
     ]),
     c.flows.createIndexes([
@@ -663,7 +664,12 @@ async function ensureIndexes(db, prefix = "mailer_") {
     c.flowRuns.createIndexes([
       { key: { status: 1, nextActionAt: 1 } },
       { key: { externalId: 1, flowId: 1 } },
-      { key: { flowId: 1, status: 1 } }
+      { key: { flowId: 1, status: 1 } },
+      {
+        key: { flowId: 1, triggerDedupeKey: 1 },
+        unique: true,
+        partialFilterExpression: { triggerDedupeKey: { $type: "string" } }
+      }
     ]),
     c.templates.createIndexes([
       { key: { slug: 1 }, unique: true },
@@ -906,7 +912,13 @@ var BullDriver = class _BullDriver {
   constructor(bull, redis) {
     this.bull = bull;
     this.redis = redis;
-    const opts = { connection: redis };
+    const opts = {
+      connection: redis,
+      defaultJobOptions: {
+        removeOnComplete: { age: 24 * 3600, count: 1e3 },
+        removeOnFail: { age: 7 * 24 * 3600 }
+      }
+    };
     this.bullQueues = {
       tick: new bull.Queue(QUEUE_NAMES.tick, opts),
       advance: new bull.Queue(QUEUE_NAMES.advance, opts),
@@ -924,7 +936,11 @@ var BullDriver = class _BullDriver {
     await this.bullQueues.tick.upsertJobScheduler(
       "mailer-tick-repeat",
       { every: intervalSeconds * 1e3 },
-      { name: "tick", data: {} }
+      {
+        name: "tick",
+        data: {},
+        opts: { removeOnComplete: { count: 20 }, removeOnFail: { count: 50 } }
+      }
     );
   }
   async startWorkers(opts) {
@@ -1034,9 +1050,10 @@ 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 backend = new backendMod.MongoBackend({
       mongo: opts.db,
-      collection: opts.collectionName ?? "_mailerJobs"
+      collection: collectionName
     });
     const agenda = new agendaMod.Agenda({
       backend,
@@ -1045,13 +1062,15 @@ var AgendaDriver = class _AgendaDriver {
       maxConcurrency: 50,
       defaultConcurrency: 5
     });
-    return new _AgendaDriver(agenda, agendaMod, opts.db);
+    return new _AgendaDriver(agenda, agendaMod, opts.db, collectionName);
   }
   db;
-  constructor(agenda, agendaMod, db) {
+  collName;
+  constructor(agenda, agendaMod, db, collectionName) {
     this.agenda = agenda;
     this.agendaMod = agendaMod;
     this.db = db;
+    this.collName = collectionName;
     this.queues = {
       tick: this.makeQueueAPI(QUEUE_NAMES2.tick),
       advance: this.makeQueueAPI(QUEUE_NAMES2.advance),
@@ -1084,10 +1103,7 @@ var AgendaDriver = class _AgendaDriver {
   }
   /** Direct access to the Mongo collection Agenda persists jobs into. */
   jobsCollection() {
-    return this.db.collection(this.collectionName());
-  }
-  collectionName() {
-    return "_mailerJobs";
+    return this.db.collection(this.collName);
   }
   async findPending(name, jobId) {
     return this.jobsCollection().findOne({
@@ -1097,12 +1113,6 @@ var AgendaDriver = class _AgendaDriver {
     });
   }
   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) {
@@ -1205,6 +1215,7 @@ async function createQueueDriver(config, fallbackDb) {
 
 // src/server/runner/triggers.ts
 var BATCH_SIZE = 1e3;
+var SCAN_OVERLAP_MS = 3e4;
 async function processNewlyFiredEventTriggers(ctx) {
   const flows = await ctx.collections.flows.find({ enabled: true, "trigger.type": "event" }).toArray();
   for (const flow of flows) {
@@ -1215,16 +1226,19 @@ async function processFlowTriggers(flow, ctx) {
   const eventName = flow.trigger.eventName;
   if (!eventName) return;
   const since = flow.lastTriggerScanAt ?? flow.createdAt;
-  const events = await ctx.collections.events.find({ name: eventName, occurredAt: { $gt: since } }).sort({ occurredAt: 1 }).limit(BATCH_SIZE).toArray();
+  const scanFrom = new Date(since.getTime() - SCAN_OVERLAP_MS);
+  const events = await ctx.collections.events.find({ name: eventName, createdAt: { $gt: scanFrom } }).sort({ createdAt: 1 }).limit(BATCH_SIZE).toArray();
   if (events.length === 0) return;
   for (const event of events) {
     await tryEnterFlow(flow, event, ctx);
   }
-  const newestOccurredAt = events[events.length - 1].occurredAt;
-  await ctx.collections.flows.updateOne(
-    { _id: flow._id },
-    { $set: { lastTriggerScanAt: newestOccurredAt, updatedAt: /* @__PURE__ */ new Date() } }
-  );
+  const newestCreatedAt = events[events.length - 1].createdAt;
+  if (newestCreatedAt.getTime() > since.getTime()) {
+    await ctx.collections.flows.updateOne(
+      { _id: flow._id },
+      { $set: { lastTriggerScanAt: newestCreatedAt, updatedAt: /* @__PURE__ */ new Date() } }
+    );
+  }
 }
 async function tryEnterFlow(flow, event, ctx) {
   if (flow.trigger.once) {
@@ -1236,188 +1250,562 @@ async function tryEnterFlow(flow, event, ctx) {
   }
   const sub = await ctx.collections.subscriptions.findOne({ externalId: event.externalId });
   if (!sub || sub.status !== "subscribed") return;
-  const result = await ctx.collections.flowRuns.insertOne({
-    externalId: event.externalId,
-    flowId: flow._id,
-    flowSlug: flow.slug,
-    flowVersion: flow.version,
-    emailAtEntry: sub.emailAtSubscribe,
-    triggerEvent: { name: event.name, properties: event.properties ?? {}, occurredAt: event.occurredAt },
-    enteredAt: /* @__PURE__ */ new Date(),
-    status: "active",
-    currentStepIndex: 0,
-    currentBranchPath: [],
-    nextActionAt: /* @__PURE__ */ new Date(),
-    attemptsForCurrentStep: 0,
-    history: [{ stepIndex: -1, action: "entered", at: /* @__PURE__ */ new Date(), details: { eventDedupeKey: event.dedupeKey } }],
-    exitedAt: null,
-    exitReason: null,
-    createdAt: /* @__PURE__ */ new Date(),
-    updatedAt: /* @__PURE__ */ new Date()
-  });
+  let result;
+  try {
+    result = await ctx.collections.flowRuns.insertOne({
+      externalId: event.externalId,
+      flowId: flow._id,
+      flowSlug: flow.slug,
+      flowVersion: flow.version,
+      emailAtEntry: sub.emailAtSubscribe,
+      triggerEvent: { name: event.name, properties: event.properties ?? {}, occurredAt: event.occurredAt },
+      triggerDedupeKey: event.dedupeKey,
+      enteredAt: /* @__PURE__ */ new Date(),
+      status: "active",
+      currentStepIndex: 0,
+      currentBranchPath: [],
+      nextActionAt: /* @__PURE__ */ new Date(),
+      attemptsForCurrentStep: 0,
+      history: [{ stepIndex: -1, action: "entered", at: /* @__PURE__ */ new Date(), details: { eventDedupeKey: event.dedupeKey } }],
+      exitedAt: null,
+      exitReason: null,
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+  } catch (err) {
+    if (err?.code !== 11e3) throw err;
+    return;
+  }
   await ctx.queues.advance.add("advance", { flowRunId: String(result.insertedId) });
 }
 
-// src/server/runner/predicate.ts
-var BOT_UA_RE = /Mimecast|SafeLinks|proofpoint|HeadlessChrome|Googlebot|bingbot/i;
-async function evaluatePredicate(predicate, ctx) {
-  const p = predicate;
-  if ("hasTag" in p) return ctx.contact.tags.includes(p.hasTag);
-  if ("notHasTag" in p) return !ctx.contact.tags.includes(p.notHasTag);
-  if ("fieldEquals" in p) {
-    return ctx.contact.fields[p.fieldEquals.field] === p.fieldEquals.value;
-  }
-  if ("fieldExists" in p) {
-    return ctx.contact.fields[p.fieldExists] !== void 0;
-  }
-  if ("subscriptionStatus" in p) {
-    const sub = await ctx.collections.subscriptions.findOne({ externalId: ctx.contact.externalId });
-    return sub?.status === p.subscriptionStatus;
-  }
-  if ("hasFiredEvent" in p) {
-    return hasEvent(ctx, p.hasFiredEvent, { sinceFlowStart: p.sinceFlowStart, withinDays: p.withinDays });
-  }
-  if ("notHasFiredEvent" in p) {
-    return !await hasEvent(ctx, p.notHasFiredEvent, { withinDays: p.withinDays });
-  }
-  if ("hasOpened" in p) return await openOrClickCount(ctx, "opened", p.hasOpened, false) > 0;
-  if ("hasClicked" in p) return await openOrClickCount(ctx, "clicked", p.hasClicked, false) > 0;
-  if ("hasOpenedExcludingBots" in p) return await openOrClickCount(ctx, "opened", p.hasOpenedExcludingBots, true) > 0;
-  if ("hasClickedExcludingBots" in p) return await openOrClickCount(ctx, "clicked", p.hasClickedExcludingBots, true) > 0;
-  if ("openedAtLeastN" in p) return await openOrClickCount(ctx, "opened", p.openedAtLeastN, true) >= p.openedAtLeastN.count;
-  if ("clickedAtLeastN" in p) return await openOrClickCount(ctx, "clicked", p.clickedAtLeastN, true) >= p.clickedAtLeastN.count;
-  if ("all" in p) {
-    for (const sub of p.all) {
-      if (!await evaluatePredicate(sub, ctx)) return false;
-    }
-    return true;
-  }
-  if ("any" in p) {
-    for (const sub of p.any) {
-      if (await evaluatePredicate(sub, ctx)) return true;
-    }
-    return false;
-  }
-  if ("not" in p) {
-    return !await evaluatePredicate(p.not, ctx);
+// 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"`
+    };
   }
-  return false;
-}
-async function hasEvent(ctx, name, opts) {
-  const filter = { externalId: ctx.contact.externalId, name };
-  const lower = effectiveLowerBound(ctx, opts);
-  if (lower) filter.occurredAt = { $gt: lower };
-  const found = await ctx.collections.events.findOne(filter, { projection: { _id: 1 } });
-  return !!found;
-}
-async function openOrClickCount(ctx, kind, opts, excludeBots) {
-  const filter = { externalId: ctx.contact.externalId };
-  if (opts.templateSlug) filter.templateSlug = opts.templateSlug;
-  if (kind === "opened") filter.openedAt = { $ne: null };
-  if (kind === "clicked") filter.firstClickAt = { $ne: null };
-  const lower = effectiveLowerBound(ctx, opts);
-  if (lower) filter[kind === "opened" ? "openedAt" : "firstClickAt"] = { $gt: lower };
-  if (!excludeBots) {
-    return await ctx.collections.sends.countDocuments(filter);
+  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})`
+    };
   }
-  const docs = await ctx.collections.sends.find(filter).limit(1e3).toArray();
-  let n = 0;
-  for (const s of docs) {
-    if (kind === "opened") {
-      n++;
-      continue;
-    }
-    const hasHumanClick = s.clickedLinks?.some((c) => !c.userAgent || !BOT_UA_RE.test(c.userAgent));
-    if (hasHumanClick) n++;
+  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 n;
+  return { ok: true };
 }
-function effectiveLowerBound(ctx, opts) {
-  const now = ctx.now ?? /* @__PURE__ */ new Date();
-  if (opts.sinceFlowStart) return ctx.run.enteredAt;
-  if (opts.withinDays && opts.withinDays > 0) {
-    return new Date(now.getTime() - opts.withinDays * 24 * 60 * 60 * 1e3);
-  }
-  return null;
+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/runner/delivery-window.ts
-var TIME_OF_DAY_GRACE_MS = 60 * 6e4;
-function computeDeliveryTime(now, window, contactTimezone) {
-  const tz = pickTimezone(window, contactTimezone);
-  let candidate = now;
-  if (window.timeOfDay) {
-    const [hh, mm] = window.timeOfDay.split(":").map(Number);
-    const local = localParts(candidate, tz);
-    const todaySlot = utcFromLocal(local.y, local.mo, local.d, hh, mm, tz);
-    if (candidate.getTime() < todaySlot.getTime()) {
-      candidate = todaySlot;
-    } else if (candidate.getTime() - todaySlot.getTime() > TIME_OF_DAY_GRACE_MS) {
-      const next = addLocalDays(local, 1);
-      candidate = utcFromLocal(next.y, next.mo, next.d, hh, mm, tz);
-    }
-  }
-  if (window.weekdaysOnly) {
-    for (let guard = 0; guard < 3; guard++) {
-      const local = localParts(candidate, tz);
-      if (local.weekday !== "Sat" && local.weekday !== "Sun") break;
-      const shift = local.weekday === "Sat" ? 2 : 1;
-      const moved = addLocalDays(local, shift);
-      candidate = utcFromLocal(moved.y, moved.mo, moved.d, local.hh, local.mi, tz);
+// src/server/runner/health.ts
+var ZERO_COUNTERS = {
+  sent: 0,
+  delivered: 0,
+  bounced: 0,
+  hardBounced: 0,
+  softBounced: 0,
+  complained: 0,
+  failedToSend: 0
+};
+var ZERO_RATES = {
+  bounceRate: 0,
+  hardBounceRate: 0,
+  complaintRate: 0,
+  failureRate: 0
+};
+async function recordHealthCounter(ctx, counter2, dims, by = 1) {
+  const windowMs = ctx.config.circuitBreaker.windowMinutes * 60 * 1e3;
+  const writes = [];
+  writes.push(upsertCounter(ctx, HEALTH_AGG_ID, null, null, counter2, by, windowMs));
+  if (dims) {
+    const domain = dims.fromEmail ? extractDomain(dims.fromEmail) : null;
+    if (domain) {
+      const id = healthBucketId(domain, dims.kind);
+      writes.push(upsertCounter(ctx, id, domain, dims.kind, counter2, by, windowMs));
     }
   }
-  return candidate;
-}
-function pickTimezone(window, contactTimezone) {
-  const candidates = [
-    window.useContactTimezone ? contactTimezone : void 0,
-    window.timezone,
-    "UTC"
-  ];
-  for (const tz of candidates) {
-    if (tz && isValidTimezone(tz)) return tz;
-  }
-  return "UTC";
+  await Promise.all(writes);
 }
-var validatedZones = /* @__PURE__ */ new Map();
-function isValidTimezone(tz) {
-  const cached = validatedZones.get(tz);
-  if (cached !== void 0) return cached;
-  let ok = true;
-  try {
-    new Intl.DateTimeFormat("en-US", { timeZone: tz });
-  } catch {
-    ok = false;
-  }
-  validatedZones.set(tz, ok);
-  return ok;
+async function upsertCounter(ctx, _id, senderDomain, kind, counter2, by, windowMs) {
+  await ctx.collections.health.updateOne(
+    { _id },
+    {
+      $inc: { [`counters.${counter2}`]: by },
+      $setOnInsert: {
+        _id,
+        senderDomain,
+        kind,
+        windowStartedAt: /* @__PURE__ */ new Date(),
+        windowDurationMs: windowMs,
+        status: "healthy",
+        trippedAt: null,
+        trippedReason: null,
+        manuallyResumedAt: null,
+        rates: { ...ZERO_RATES }
+      },
+      $set: { updatedAt: /* @__PURE__ */ new Date() }
+    },
+    { upsert: true }
+  );
 }
-var partFormatters = /* @__PURE__ */ new Map();
-function formatterFor(tz) {
-  let f = partFormatters.get(tz);
-  if (!f) {
-    f = new Intl.DateTimeFormat("en-US", {
-      timeZone: tz,
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      weekday: "short",
-      hour12: false
-    });
-    partFormatters.set(tz, f);
+async function evaluateHealth(ctx) {
+  const cb = ctx.config.circuitBreaker;
+  const windowMs = cb.windowMinutes * 60 * 1e3;
+  const docs = await ctx.collections.health.find({}).toArray();
+  if (docs.length === 0) return;
+  const hasAgg = docs.some((d) => d._id === HEALTH_AGG_ID);
+  if (!hasAgg) {
+    await upsertCounter(ctx, HEALTH_AGG_ID, null, null, "sent", 0, windowMs);
   }
-  return f;
-}
-function localParts(date, tz) {
-  const parts = {};
-  for (const p of formatterFor(tz).formatToParts(date)) parts[p.type] = p.value;
-  return {
-    y: Number(parts.year),
-    mo: Number(parts.month),
-    d: Number(parts.day),
+  for (const doc of docs) {
+    const isAgg = doc._id === HEALTH_AGG_ID;
+    const windowAge = Date.now() - new Date(doc.windowStartedAt).getTime();
+    if (windowAge > windowMs && doc.status !== "tripped") {
+      await ctx.collections.health.updateOne(
+        { _id: doc._id },
+        {
+          $set: {
+            windowStartedAt: /* @__PURE__ */ new Date(),
+            windowDurationMs: windowMs,
+            counters: { ...ZERO_COUNTERS },
+            rates: { ...ZERO_RATES },
+            status: "healthy",
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        }
+      );
+      continue;
+    }
+    const c = doc.counters;
+    const total = c.sent || 1;
+    const rates = {
+      bounceRate: c.bounced / total,
+      hardBounceRate: c.hardBounced / total,
+      complaintRate: c.complained / total,
+      failureRate: c.failedToSend / total
+    };
+    await ctx.collections.health.updateOne(
+      { _id: doc._id },
+      { $set: { rates, updatedAt: /* @__PURE__ */ new Date() } }
+    );
+    if (isAgg) continue;
+    if (c.sent < cb.minSendsBeforeEval) continue;
+    if (doc.status === "tripped") continue;
+    let trippedReason = null;
+    if (rates.hardBounceRate * 100 >= cb.hardBounceRatePctTrip) {
+      trippedReason = `hard bounce rate ${(rates.hardBounceRate * 100).toFixed(2)}% >= ${cb.hardBounceRatePctTrip}%`;
+    } else if (rates.complaintRate * 100 >= cb.complaintRatePctTrip) {
+      trippedReason = `complaint rate ${(rates.complaintRate * 100).toFixed(2)}% >= ${cb.complaintRatePctTrip}%`;
+    } else if (rates.bounceRate * 100 >= cb.combinedBounceRatePctTrip) {
+      trippedReason = `combined bounce rate ${(rates.bounceRate * 100).toFixed(2)}% >= ${cb.combinedBounceRatePctTrip}%`;
+    }
+    if (trippedReason) {
+      const result = await ctx.collections.health.updateOne(
+        { _id: doc._id, status: { $in: ["healthy", "degraded"] } },
+        { $set: { status: "tripped", trippedAt: /* @__PURE__ */ new Date(), trippedReason, updatedAt: /* @__PURE__ */ new Date() } }
+      );
+      if (result.modifiedCount > 0) {
+        if (ctx.audit) {
+          try {
+            await ctx.audit({
+              actor: "system:circuit-breaker",
+              action: "health.trip",
+              resource: {
+                collection: "mailer_health",
+                id: String(doc._id),
+                slug: `${doc.senderDomain ?? "_unknown"}|${doc.kind}`
+              },
+              diffSummary: trippedReason
+            });
+          } catch {
+          }
+        }
+        if (ctx.config.onCircuitBreakerTrip) {
+          try {
+            await ctx.config.onCircuitBreakerTrip({
+              reason: `[${doc.senderDomain ?? "_unknown"} / ${doc.kind}] ${trippedReason}`,
+              rates
+            });
+          } catch {
+          }
+        }
+      }
+      continue;
+    }
+    if (rates.failureRate * 100 >= cb.failedToSendRatePctDegrade) {
+      if (doc.status !== "degraded") {
+        await ctx.collections.health.updateOne(
+          { _id: doc._id },
+          { $set: { status: "degraded", updatedAt: /* @__PURE__ */ new Date() } }
+        );
+      }
+    } else if (doc.status === "degraded") {
+      await ctx.collections.health.updateOne(
+        { _id: doc._id },
+        { $set: { status: "healthy", updatedAt: /* @__PURE__ */ new Date() } }
+      );
+    }
+  }
+}
+async function getBucketStatus(ctx, fromEmail, kind) {
+  const domain = fromEmail ? extractDomain(fromEmail) : null;
+  const id = healthBucketId(domain, kind);
+  return ctx.collections.health.findOne({ _id: id });
+}
+function effectiveOverallStatus(docs) {
+  const buckets = docs.filter((d) => typeof d._id === "string" && d._id.startsWith("d:"));
+  if (buckets.length === 0) {
+    return docs.length === 0 ? null : "healthy";
+  }
+  if (buckets.some((d) => d.status === "tripped")) return "tripped";
+  if (buckets.some((d) => d.status === "degraded")) return "degraded";
+  return "healthy";
+}
+
+// src/server/runner/webhook.ts
+function dimsFromSend(send) {
+  if (!send) return null;
+  return { fromEmail: send.fromEmail, kind: send.kind };
+}
+async function processWebhookBacklog(ctx, opts = {}) {
+  const filter = { processed: false };
+  if (opts.olderThanMs) {
+    filter.receivedAt = { $lt: new Date(Date.now() - opts.olderThanMs) };
+  }
+  const batch = await ctx.collections.webhookEvents.find(filter).limit(500).toArray();
+  for (const evt of batch) {
+    const claimed = await ctx.collections.webhookEvents.findOneAndUpdate(
+      { _id: evt._id, processed: false },
+      { $set: { processed: true } }
+    );
+    if (!claimed) continue;
+    try {
+      const normalized = evt.raw?.normalized;
+      const details = normalized?.details ?? {};
+      await applyWebhookEvent(
+        {
+          type: evt.normalizedType,
+          providerEventId: evt.providerEventId,
+          providerMessageId: evt.providerMessageId,
+          email: evt.email,
+          occurredAt: evt.occurredAt,
+          details
+        },
+        ctx
+      );
+    } catch (err) {
+      console.error("mailery: webhook apply failed", { id: String(evt._id), err });
+    }
+  }
+}
+async function applyWebhookEvent(event, ctx) {
+  const send = await ctx.collections.sends.findOne(
+    event.providerMessageId ? { $or: [{ providerMessageId: event.providerMessageId }, { emailAtSend: event.email }] } : { emailAtSend: event.email },
+    { sort: { queuedAt: -1 } }
+  );
+  switch (event.type) {
+    case "delivered":
+      if (send) {
+        await ctx.collections.sends.updateOne(
+          { _id: send._id },
+          { $set: { status: "delivered", deliveredAt: event.occurredAt } }
+        );
+      }
+      await recordHealthCounter(ctx, "delivered", dimsFromSend(send));
+      break;
+    case "open":
+      if (send) {
+        await ctx.collections.sends.updateOne(
+          { _id: send._id },
+          {
+            $set: {
+              openedAt: send.openedAt ?? event.occurredAt,
+              status: send.status === "sent" ? "delivered" : send.status
+            },
+            $inc: { openCount: 1 }
+          }
+        );
+      }
+      break;
+    case "click":
+      if (send) {
+        await ctx.collections.sends.updateOne(
+          { _id: send._id },
+          {
+            $set: { firstClickAt: send.firstClickAt ?? event.occurredAt },
+            $inc: { clickCount: 1 },
+            $push: {
+              clickedLinks: {
+                url: event.details.clickedUrl ?? "",
+                linkId: "",
+                clickedAt: event.occurredAt
+              }
+            }
+          }
+        );
+      }
+      break;
+    case "bounce": {
+      const bounceType = event.details.bounceType ?? "hard";
+      if (send) {
+        await ctx.collections.sends.updateOne(
+          { _id: send._id },
+          {
+            $set: {
+              status: "bounced",
+              bounceType,
+              bounceReason: event.details.bounceReason ?? null
+            }
+          }
+        );
+      }
+      if (bounceType === "hard") {
+        await suppressOnce(ctx, event.email, "hard_bounce", "all");
+        await ctx.collections.subscriptions.updateOne(
+          { emailAtSubscribe: event.email },
+          { $set: { status: "bounced", updatedAt: /* @__PURE__ */ new Date() } }
+        );
+      }
+      {
+        const dims = dimsFromSend(send);
+        await recordHealthCounter(ctx, "bounced", dims);
+        await recordHealthCounter(ctx, bounceType === "hard" ? "hardBounced" : "softBounced", dims);
+      }
+      break;
+    }
+    case "complaint":
+    case "spam_report":
+      if (send) {
+        await ctx.collections.sends.updateOne(
+          { _id: send._id },
+          { $set: { complainedAt: event.occurredAt, status: "complained" } }
+        );
+      }
+      await suppressOnce(ctx, event.email, "complaint", "all");
+      await ctx.collections.subscriptions.updateOne(
+        { emailAtSubscribe: event.email },
+        { $set: { status: "complained", updatedAt: /* @__PURE__ */ new Date() } }
+      );
+      await recordHealthCounter(ctx, "complained", dimsFromSend(send));
+      break;
+    case "unsubscribe":
+      if (send) {
+        await ctx.collections.sends.updateOne({ _id: send._id }, { $set: { unsubscribedAt: event.occurredAt } });
+      }
+      await suppressOnce(ctx, event.email, "unsubscribed", "marketing");
+      await ctx.collections.subscriptions.updateOne(
+        { emailAtSubscribe: event.email },
+        {
+          $set: {
+            status: "unsubscribed",
+            unsubscribedAt: event.occurredAt,
+            unsubscribeReason: "user_request",
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        }
+      );
+      break;
+  }
+}
+async function suppressOnce(ctx, email, reason, scope) {
+  const normalized = email.toLowerCase();
+  await ctx.collections.suppressions.updateOne(
+    { email: normalized, scope },
+    {
+      $setOnInsert: {
+        email: normalized,
+        emailHash: sha256Hex(normalized),
+        scope,
+        reason,
+        source: "provider_webhook",
+        notes: null,
+        addedAt: /* @__PURE__ */ new Date(),
+        expiresAt: null
+      }
+    },
+    { upsert: true }
+  );
+}
+
+// src/server/runner/predicate.ts
+var BOT_UA_RE = /Mimecast|SafeLinks|proofpoint|HeadlessChrome|Googlebot|bingbot/i;
+async function evaluatePredicate(predicate, ctx) {
+  const p = predicate;
+  if ("hasTag" in p) return ctx.contact.tags.includes(p.hasTag);
+  if ("notHasTag" in p) return !ctx.contact.tags.includes(p.notHasTag);
+  if ("fieldEquals" in p) {
+    return ctx.contact.fields[p.fieldEquals.field] === p.fieldEquals.value;
+  }
+  if ("fieldExists" in p) {
+    return ctx.contact.fields[p.fieldExists] !== void 0;
+  }
+  if ("subscriptionStatus" in p) {
+    const sub = await ctx.collections.subscriptions.findOne({ externalId: ctx.contact.externalId });
+    return sub?.status === p.subscriptionStatus;
+  }
+  if ("hasFiredEvent" in p) {
+    return hasEvent(ctx, p.hasFiredEvent, { sinceFlowStart: p.sinceFlowStart, withinDays: p.withinDays });
+  }
+  if ("notHasFiredEvent" in p) {
+    return !await hasEvent(ctx, p.notHasFiredEvent, { withinDays: p.withinDays });
+  }
+  if ("hasOpened" in p) return await openOrClickCount(ctx, "opened", p.hasOpened, false) > 0;
+  if ("hasClicked" in p) return await openOrClickCount(ctx, "clicked", p.hasClicked, false) > 0;
+  if ("hasOpenedExcludingBots" in p) return await openOrClickCount(ctx, "opened", p.hasOpenedExcludingBots, true) > 0;
+  if ("hasClickedExcludingBots" in p) return await openOrClickCount(ctx, "clicked", p.hasClickedExcludingBots, true) > 0;
+  if ("openedAtLeastN" in p) return await openOrClickCount(ctx, "opened", p.openedAtLeastN, true) >= p.openedAtLeastN.count;
+  if ("clickedAtLeastN" in p) return await openOrClickCount(ctx, "clicked", p.clickedAtLeastN, true) >= p.clickedAtLeastN.count;
+  if ("all" in p) {
+    for (const sub of p.all) {
+      if (!await evaluatePredicate(sub, ctx)) return false;
+    }
+    return true;
+  }
+  if ("any" in p) {
+    for (const sub of p.any) {
+      if (await evaluatePredicate(sub, ctx)) return true;
+    }
+    return false;
+  }
+  if ("not" in p) {
+    return !await evaluatePredicate(p.not, ctx);
+  }
+  return false;
+}
+async function hasEvent(ctx, name, opts) {
+  const filter = { externalId: ctx.contact.externalId, name };
+  const lower = effectiveLowerBound(ctx, opts);
+  if (lower) filter.occurredAt = { $gt: lower };
+  const found = await ctx.collections.events.findOne(filter, { projection: { _id: 1 } });
+  return !!found;
+}
+async function openOrClickCount(ctx, kind, opts, excludeBots) {
+  const filter = { externalId: ctx.contact.externalId };
+  if (opts.templateSlug) filter.templateSlug = opts.templateSlug;
+  if (kind === "opened") filter.openedAt = { $ne: null };
+  if (kind === "clicked") filter.firstClickAt = { $ne: null };
+  const lower = effectiveLowerBound(ctx, opts);
+  if (lower) filter[kind === "opened" ? "openedAt" : "firstClickAt"] = { $gt: lower };
+  if (!excludeBots) {
+    return await ctx.collections.sends.countDocuments(filter);
+  }
+  const docs = await ctx.collections.sends.find(filter).limit(1e3).toArray();
+  let n = 0;
+  for (const s of docs) {
+    if (kind === "opened") {
+      n++;
+      continue;
+    }
+    const hasHumanClick = s.clickedLinks?.some((c) => !c.userAgent || !BOT_UA_RE.test(c.userAgent));
+    if (hasHumanClick) n++;
+  }
+  return n;
+}
+function effectiveLowerBound(ctx, opts) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  if (opts.sinceFlowStart) return ctx.run.enteredAt;
+  if (opts.withinDays && opts.withinDays > 0) {
+    return new Date(now.getTime() - opts.withinDays * 24 * 60 * 60 * 1e3);
+  }
+  return null;
+}
+
+// src/server/runner/delivery-window.ts
+var TIME_OF_DAY_GRACE_MS = 60 * 6e4;
+function computeDeliveryTime(now, window, contactTimezone) {
+  const tz = pickTimezone(window, contactTimezone);
+  let candidate = now;
+  if (window.timeOfDay) {
+    const [hh, mm] = window.timeOfDay.split(":").map(Number);
+    const local = localParts(candidate, tz);
+    const todaySlot = utcFromLocal(local.y, local.mo, local.d, hh, mm, tz);
+    if (candidate.getTime() < todaySlot.getTime()) {
+      candidate = todaySlot;
+    } else if (candidate.getTime() - todaySlot.getTime() > TIME_OF_DAY_GRACE_MS) {
+      const next = addLocalDays(local, 1);
+      candidate = utcFromLocal(next.y, next.mo, next.d, hh, mm, tz);
+    }
+  }
+  if (window.weekdaysOnly) {
+    for (let guard = 0; guard < 3; guard++) {
+      const local = localParts(candidate, tz);
+      if (local.weekday !== "Sat" && local.weekday !== "Sun") break;
+      const shift = local.weekday === "Sat" ? 2 : 1;
+      const moved = addLocalDays(local, shift);
+      candidate = utcFromLocal(moved.y, moved.mo, moved.d, local.hh, local.mi, tz);
+    }
+  }
+  return candidate;
+}
+function pickTimezone(window, contactTimezone) {
+  const candidates = [
+    window.useContactTimezone ? contactTimezone : void 0,
+    window.timezone,
+    "UTC"
+  ];
+  for (const tz of candidates) {
+    if (tz && isValidTimezone(tz)) return tz;
+  }
+  return "UTC";
+}
+var validatedZones = /* @__PURE__ */ new Map();
+function isValidTimezone(tz) {
+  const cached = validatedZones.get(tz);
+  if (cached !== void 0) return cached;
+  let ok = true;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+  } catch {
+    ok = false;
+  }
+  validatedZones.set(tz, ok);
+  return ok;
+}
+var partFormatters = /* @__PURE__ */ new Map();
+function formatterFor(tz) {
+  let f = partFormatters.get(tz);
+  if (!f) {
+    f = new Intl.DateTimeFormat("en-US", {
+      timeZone: tz,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      weekday: "short",
+      hour12: false
+    });
+    partFormatters.set(tz, f);
+  }
+  return f;
+}
+function localParts(date, tz) {
+  const parts = {};
+  for (const p of formatterFor(tz).formatToParts(date)) parts[p.type] = p.value;
+  return {
+    y: Number(parts.year),
+    mo: Number(parts.month),
+    d: Number(parts.day),
     hh: Number(parts.hour) % 24,
     // Intl emits '24' for midnight in some locales
     mi: Number(parts.minute),
@@ -1487,7 +1875,8 @@ function applyTracking(html, opts) {
   const seen = /* @__PURE__ */ new Map();
   let out = html;
   if (opts.trackClicks) {
-    out = out.replace(/<a\b([^>]*?)\bhref=(["'])([^"']+)\2([^>]*)>/gi, (full, pre, _q, url, post) => {
+    out = out.replace(/<a\b([^>]*?)\bhref=(["'])([^"']+)\2([^>]*)>/gi, (full, pre, _q, rawUrl, post) => {
+      const url = decodeHtmlEntities(rawUrl);
       if (shouldSkipClickRewrite(url, preserve, full)) return full;
       let linkId = seen.get(url);
       if (!linkId) {
@@ -1519,6 +1908,29 @@ function shouldSkipClickRewrite(url, preserve, fullTag) {
   if (/data-mailer-notrack=["']true["']/.test(fullTag)) return true;
   return false;
 }
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0"
+};
+function decodeHtmlEntities(input) {
+  return input.replace(/&(#x[0-9a-f]+|#\d+|[a-z][a-z0-9]*);/gi, (match, body) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      if (!Number.isFinite(code) || code < 0 || code > 1114111) return match;
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return match;
+      }
+    }
+    const named = NAMED_ENTITIES[body.toLowerCase()];
+    return named ?? match;
+  });
+}
 function shortHash(input) {
   return crypto2__default.default.createHash("sha256").update(input).digest("hex").slice(0, 12);
 }
@@ -1531,262 +1943,60 @@ function makeHandlebars(extra) {
   hb.registerHelper("gte", (a, b) => a >= b);
   hb.registerHelper("lte", (a, b) => a <= b);
   hb.registerHelper("and", (...args) => args.slice(0, -1).every(Boolean));
-  hb.registerHelper("or", (...args) => args.slice(0, -1).some(Boolean));
-  hb.registerHelper("not", (a) => !a);
-  hb.registerHelper("formatDate", (value, fmt) => {
-    if (!value) return "";
-    const d = value instanceof Date ? value : new Date(String(value));
-    if (Number.isNaN(d.getTime())) return "";
-    if (fmt === "long") return d.toLocaleDateString("en-US", { dateStyle: "long" });
-    if (fmt === "short") return d.toLocaleDateString("en-US", { dateStyle: "short" });
-    return d.toISOString().slice(0, 10);
-  });
-  hb.registerHelper("formatNumber", (n) => {
-    const v = Number(n);
-    return Number.isFinite(v) ? v.toLocaleString("en-US") : "";
-  });
-  hb.registerHelper("formatCurrency", (cents, currency = "usd") => {
-    const v = Number(cents);
-    if (!Number.isFinite(v)) return "";
-    return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(v / 100);
-  });
-  hb.registerHelper(
-    "pluralize",
-    (n, one, many) => Number(n) === 1 ? one : many
-  );
-  if (extra) {
-    for (const [name, fn] of Object.entries(extra)) {
-      hb.registerHelper(name, fn);
-    }
-  }
-  return hb;
-}
-
-// src/server/runner/send.ts
-init_vars();
-
-// src/server/runner/suppression.ts
-var SCOPES_BY_KIND = {
-  marketing: ["all", "marketing"],
-  transactional: ["all", "transactional"]
-};
-async function isSuppressed(collections, email, kind) {
-  const normalized = email.toLowerCase();
-  const allowed = SCOPES_BY_KIND[kind];
-  const byEmail = await collections.suppressions.findOne({
-    email: normalized,
-    scope: { $in: allowed },
-    $or: [{ expiresAt: null }, { expiresAt: { $gt: /* @__PURE__ */ new Date() } }]
-  });
-  if (byEmail) return { suppressed: true, scope: byEmail.scope, reason: byEmail.reason };
-  const hashed = await collections.suppressions.findOne({
-    emailHash: sha256Hex(normalized),
-    scope: { $in: allowed }
-  });
-  if (hashed) return { suppressed: true, scope: hashed.scope, reason: hashed.reason };
-  return { suppressed: false };
-}
-
-// 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/runner/health.ts
-var ZERO_COUNTERS = {
-  sent: 0,
-  delivered: 0,
-  bounced: 0,
-  hardBounced: 0,
-  softBounced: 0,
-  complained: 0,
-  failedToSend: 0
-};
-var ZERO_RATES = {
-  bounceRate: 0,
-  hardBounceRate: 0,
-  complaintRate: 0,
-  failureRate: 0
-};
-async function recordHealthCounter(ctx, counter2, dims, by = 1) {
-  const windowMs = ctx.config.circuitBreaker.windowMinutes * 60 * 1e3;
-  const writes = [];
-  writes.push(upsertCounter(ctx, HEALTH_AGG_ID, null, null, counter2, by, windowMs));
-  if (dims) {
-    const domain = dims.fromEmail ? extractDomain(dims.fromEmail) : null;
-    if (domain) {
-      const id = healthBucketId(domain, dims.kind);
-      writes.push(upsertCounter(ctx, id, domain, dims.kind, counter2, by, windowMs));
-    }
-  }
-  await Promise.all(writes);
-}
-async function upsertCounter(ctx, _id, senderDomain, kind, counter2, by, windowMs) {
-  await ctx.collections.health.updateOne(
-    { _id },
-    {
-      $inc: { [`counters.${counter2}`]: by },
-      $setOnInsert: {
-        _id,
-        senderDomain,
-        kind,
-        windowStartedAt: /* @__PURE__ */ new Date(),
-        windowDurationMs: windowMs,
-        status: "healthy",
-        trippedAt: null,
-        trippedReason: null,
-        manuallyResumedAt: null,
-        rates: { ...ZERO_RATES }
-      },
-      $set: { updatedAt: /* @__PURE__ */ new Date() }
-    },
-    { upsert: true }
-  );
-}
-async function evaluateHealth(ctx) {
-  const cb = ctx.config.circuitBreaker;
-  const windowMs = cb.windowMinutes * 60 * 1e3;
-  const docs = await ctx.collections.health.find({}).toArray();
-  if (docs.length === 0) return;
-  const hasAgg = docs.some((d) => d._id === HEALTH_AGG_ID);
-  if (!hasAgg) {
-    await upsertCounter(ctx, HEALTH_AGG_ID, null, null, "sent", 0, windowMs);
-  }
-  for (const doc of docs) {
-    const isAgg = doc._id === HEALTH_AGG_ID;
-    const windowAge = Date.now() - new Date(doc.windowStartedAt).getTime();
-    if (windowAge > windowMs && doc.status !== "tripped") {
-      await ctx.collections.health.updateOne(
-        { _id: doc._id },
-        {
-          $set: {
-            windowStartedAt: /* @__PURE__ */ new Date(),
-            windowDurationMs: windowMs,
-            counters: { ...ZERO_COUNTERS },
-            rates: { ...ZERO_RATES },
-            status: "healthy",
-            updatedAt: /* @__PURE__ */ new Date()
-          }
-        }
-      );
-      continue;
-    }
-    const c = doc.counters;
-    const total = c.sent || 1;
-    const rates = {
-      bounceRate: c.bounced / total,
-      hardBounceRate: c.hardBounced / total,
-      complaintRate: c.complained / total,
-      failureRate: c.failedToSend / total
-    };
-    await ctx.collections.health.updateOne(
-      { _id: doc._id },
-      { $set: { rates, updatedAt: /* @__PURE__ */ new Date() } }
-    );
-    if (isAgg) continue;
-    if (c.sent < cb.minSendsBeforeEval) continue;
-    if (doc.status === "tripped") continue;
-    let trippedReason = null;
-    if (rates.hardBounceRate * 100 >= cb.hardBounceRatePctTrip) {
-      trippedReason = `hard bounce rate ${(rates.hardBounceRate * 100).toFixed(2)}% >= ${cb.hardBounceRatePctTrip}%`;
-    } else if (rates.complaintRate * 100 >= cb.complaintRatePctTrip) {
-      trippedReason = `complaint rate ${(rates.complaintRate * 100).toFixed(2)}% >= ${cb.complaintRatePctTrip}%`;
-    } else if (rates.bounceRate * 100 >= cb.combinedBounceRatePctTrip) {
-      trippedReason = `combined bounce rate ${(rates.bounceRate * 100).toFixed(2)}% >= ${cb.combinedBounceRatePctTrip}%`;
-    }
-    if (trippedReason) {
-      const result = await ctx.collections.health.updateOne(
-        { _id: doc._id, status: { $in: ["healthy", "degraded"] } },
-        { $set: { status: "tripped", trippedAt: /* @__PURE__ */ new Date(), trippedReason, updatedAt: /* @__PURE__ */ new Date() } }
-      );
-      if (result.modifiedCount > 0) {
-        if (ctx.audit) {
-          try {
-            await ctx.audit({
-              actor: "system:circuit-breaker",
-              action: "health.trip",
-              resource: {
-                collection: "mailer_health",
-                id: String(doc._id),
-                slug: `${doc.senderDomain ?? "_unknown"}|${doc.kind}`
-              },
-              diffSummary: trippedReason
-            });
-          } catch {
-          }
-        }
-        if (ctx.config.onCircuitBreakerTrip) {
-          try {
-            await ctx.config.onCircuitBreakerTrip({
-              reason: `[${doc.senderDomain ?? "_unknown"} / ${doc.kind}] ${trippedReason}`,
-              rates
-            });
-          } catch {
-          }
-        }
-      }
-      continue;
-    }
-    if (rates.failureRate * 100 >= cb.failedToSendRatePctDegrade) {
-      if (doc.status !== "degraded") {
-        await ctx.collections.health.updateOne(
-          { _id: doc._id },
-          { $set: { status: "degraded", updatedAt: /* @__PURE__ */ new Date() } }
-        );
-      }
-    } else if (doc.status === "degraded") {
-      await ctx.collections.health.updateOne(
-        { _id: doc._id },
-        { $set: { status: "healthy", updatedAt: /* @__PURE__ */ new Date() } }
-      );
+  hb.registerHelper("or", (...args) => args.slice(0, -1).some(Boolean));
+  hb.registerHelper("not", (a) => !a);
+  hb.registerHelper("formatDate", (value, fmt) => {
+    if (!value) return "";
+    const d = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(d.getTime())) return "";
+    if (fmt === "long") return d.toLocaleDateString("en-US", { dateStyle: "long" });
+    if (fmt === "short") return d.toLocaleDateString("en-US", { dateStyle: "short" });
+    return d.toISOString().slice(0, 10);
+  });
+  hb.registerHelper("formatNumber", (n) => {
+    const v = Number(n);
+    return Number.isFinite(v) ? v.toLocaleString("en-US") : "";
+  });
+  hb.registerHelper("formatCurrency", (cents, currency = "usd") => {
+    const v = Number(cents);
+    if (!Number.isFinite(v)) return "";
+    return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(v / 100);
+  });
+  hb.registerHelper(
+    "pluralize",
+    (n, one, many) => Number(n) === 1 ? one : many
+  );
+  if (extra) {
+    for (const [name, fn] of Object.entries(extra)) {
+      hb.registerHelper(name, fn);
     }
   }
+  return hb;
 }
-async function getBucketStatus(ctx, fromEmail, kind) {
-  const domain = fromEmail ? extractDomain(fromEmail) : null;
-  const id = healthBucketId(domain, kind);
-  return ctx.collections.health.findOne({ _id: id });
-}
-function effectiveOverallStatus(docs) {
-  const buckets = docs.filter((d) => typeof d._id === "string" && d._id.startsWith("d:"));
-  if (buckets.length === 0) {
-    return docs.length === 0 ? null : "healthy";
-  }
-  if (buckets.some((d) => d.status === "tripped")) return "tripped";
-  if (buckets.some((d) => d.status === "degraded")) return "degraded";
-  return "healthy";
+
+// src/server/runner/send.ts
+init_vars();
+
+// src/server/runner/suppression.ts
+var SCOPES_BY_KIND = {
+  marketing: ["all", "marketing"],
+  transactional: ["all", "transactional"]
+};
+async function isSuppressed(collections, email, kind) {
+  const normalized = email.toLowerCase();
+  const allowed = SCOPES_BY_KIND[kind];
+  const byEmail = await collections.suppressions.findOne({
+    email: normalized,
+    scope: { $in: allowed },
+    $or: [{ expiresAt: null }, { expiresAt: { $gt: /* @__PURE__ */ new Date() } }]
+  });
+  if (byEmail) return { suppressed: true, scope: byEmail.scope, reason: byEmail.reason };
+  const hashed = await collections.suppressions.findOne({
+    emailHash: sha256Hex(normalized),
+    scope: { $in: allowed }
+  });
+  if (hashed) return { suppressed: true, scope: hashed.scope, reason: hashed.reason };
+  return { suppressed: false };
 }
 
 // src/server/runner/send.ts
@@ -1854,9 +2064,11 @@ async function handleSend(run, step, contact, flow, ctx) {
   await advanceStep(run, ctx, { action: "sent", details: { dedupeKey, sendId: String(sendId) } });
 }
 async function dispatchSend(sendId, ctx) {
-  const send = await ctx.collections.sends.findOne({ _id: sendId });
+  const send = await ctx.collections.sends.findOneAndUpdate(
+    { _id: sendId, status: { $in: ["queued", "failed"] } },
+    { $set: { status: "sending", updatedAt: /* @__PURE__ */ new Date() } }
+  );
   if (!send) return;
-  if (send.status !== "queued" && send.status !== "failed") return;
   const template = await ctx.collections.templates.findOne({ _id: send.templateId });
   if (!template) {
     await markFailed(send._id, "template_missing", ctx);
@@ -1873,6 +2085,10 @@ async function dispatchSend(sendId, ctx) {
   if (send.kind === "marketing") {
     const bucket = await getBucketStatus(ctx, send.fromEmail, send.kind);
     if (bucket?.status === "tripped") {
+      await ctx.collections.sends.updateOne(
+        { _id: send._id },
+        { $set: { status: "queued", updatedAt: /* @__PURE__ */ new Date() } }
+      );
       await ctx.queues.send.add("send", { sendId: String(send._id) }, { delay: 6e4 });
       return;
     }
@@ -1932,6 +2148,10 @@ async function dispatchSend(sendId, ctx) {
     await markFailed(send._id, `provider_unknown: ${send.provider}`, ctx);
     return;
   }
+  const headers = send.kind === "marketing" ? {
+    "List-Unsubscribe": `<${renderCtx.unsubscribeUrl}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  } : {};
   try {
     const result = await provider.send({
       to: send.emailAtSend,
@@ -1941,10 +2161,7 @@ async function dispatchSend(sendId, ctx) {
       subject: rendered.subject,
       html: tracking.html,
       text: rendered.plainText,
-      headers: {
-        "List-Unsubscribe": `<${renderCtx.unsubscribeUrl}>`,
-        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
-      },
+      headers,
       messageMeta: { sendId: String(send._id) }
     });
     await ctx.collections.sends.updateOne(
@@ -2120,7 +2337,7 @@ async function handleWait(run, step, ctx) {
   await ctx.queues.advance.add(
     "advance",
     { flowRunId: String(run._id) },
-    { delay: ms, jobId: `advance:${run._id}:${run.currentStepIndex + 1}` }
+    { delay: ms, jobId: `advance:${run._id}:${branchKey(run)}:${run.currentStepIndex + 1}` }
   );
 }
 async function handleCondition(run, step, contact, ctx) {
@@ -2232,7 +2449,7 @@ async function handleWebhookStep(run, step, ctx) {
       await ctx.queues.advance.add(
         "advance",
         { flowRunId: String(run._id) },
-        { delay: 6e4, jobId: `advance:${run._id}:${run.currentStepIndex}:retry-${attempts}` }
+        { delay: 6e4, jobId: `advance:${run._id}:${branchKey(run)}:${run.currentStepIndex}:retry-${attempts}` }
       );
     }
   }
@@ -2261,7 +2478,7 @@ async function deferSendForWindow(run, deliverAt, ctx) {
     { flowRunId: String(run._id) },
     {
       delay: Math.max(0, deliverAt.getTime() - Date.now()),
-      jobId: `advance:${run._id}:${run.currentStepIndex}:window:${deliverAt.getTime()}`
+      jobId: `advance:${run._id}:${branchKey(run)}:${run.currentStepIndex}:window:${deliverAt.getTime()}`
     }
   );
 }
@@ -2316,13 +2533,16 @@ function locateStep(steps, currentStepIndex, branchPath) {
   let arr = steps;
   for (let i = 0; i < branchPath.length; i += 3) {
     const parentIndex = branchPath[i];
-    const branchKey = branchPath[i + 1];
+    const branchKey2 = branchPath[i + 1];
     const parent = arr[parentIndex];
     if (!parent || parent.type !== "branch") return null;
-    arr = branchKey === "true" ? parent.ifTrueSteps : parent.ifFalseSteps;
+    arr = branchKey2 === "true" ? parent.ifTrueSteps : parent.ifFalseSteps;
   }
   return arr[currentStepIndex] ?? null;
 }
+function branchKey(run) {
+  return run.currentBranchPath.join("_");
+}
 function unitToMs(value, unit) {
   const m = 6e4;
   switch (unit) {
@@ -2349,6 +2569,7 @@ async function sweepStrandedFlowRuns(ctx) {
     }
   }
 }
+var STALLED_BROADCAST_THRESHOLD_MS = 10 * 60 * 1e3;
 async function processScheduledBroadcasts(ctx) {
   const now = /* @__PURE__ */ new Date();
   const due = await ctx.collections.broadcasts.find({ status: "scheduled", scheduledAt: { $lte: now } }).toArray();
@@ -2359,15 +2580,49 @@ async function processScheduledBroadcasts(ctx) {
       { returnDocument: "after" }
     );
     if (!claimed) continue;
-    try {
-      await dispatchBroadcast(claimed, ctx);
-    } catch (err) {
-      console.error("mailery: broadcast dispatch failed", { id: String(b._id), err });
-      await ctx.collections.broadcasts.updateOne(
-        { _id: b._id },
-        { $set: { status: "failed", updatedAt: /* @__PURE__ */ new Date() } }
-      );
+    await startBroadcastDispatch(claimed, ctx);
+  }
+}
+async function startBroadcastDispatch(broadcast, ctx) {
+  if (ctx.config.queue.driver === "noop") {
+    await runBroadcastDispatch(broadcast, ctx);
+    return;
+  }
+  await ctx.queues.advance.add(
+    "advance",
+    { broadcastId: String(broadcast._id) },
+    {
+      attempts: 3,
+      backoff: { type: "exponential", delay: 6e4 },
+      jobId: `broadcast-dispatch:${broadcast._id}`
     }
+  );
+}
+async function dispatchBroadcastById(broadcastId, ctx) {
+  const broadcast = await ctx.collections.broadcasts.findOne({ _id: broadcastId, status: "sending" });
+  if (!broadcast) return;
+  await runBroadcastDispatch(broadcast, ctx);
+}
+async function resumeStalledBroadcasts(ctx) {
+  const cutoff = new Date(Date.now() - STALLED_BROADCAST_THRESHOLD_MS);
+  const stalled = await ctx.collections.broadcasts.find({ status: "sending", updatedAt: { $lt: cutoff } }).toArray();
+  for (const b of stalled) {
+    await ctx.collections.broadcasts.updateOne(
+      { _id: b._id },
+      { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+    );
+    await startBroadcastDispatch(b, ctx);
+  }
+}
+async function runBroadcastDispatch(broadcast, ctx) {
+  try {
+    await dispatchBroadcast(broadcast, ctx);
+  } catch (err) {
+    console.error("mailery: broadcast dispatch failed", { id: String(broadcast._id), err });
+    await ctx.collections.broadcasts.updateOne(
+      { _id: broadcast._id },
+      { $set: { status: "failed", updatedAt: /* @__PURE__ */ new Date() } }
+    );
   }
 }
 async function dispatchBroadcast(broadcast, ctx) {
@@ -2388,11 +2643,19 @@ async function dispatchBroadcast(broadcast, ctx) {
   const respectTimezone = broadcast.respectRecipientTimezone === true;
   const scheduledMs = broadcast.scheduledAt?.getTime() ?? Date.now();
   for (; ; ) {
+    await ctx.collections.broadcasts.updateOne(
+      { _id: broadcast._id },
+      { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+    );
     const page = await ctx.adapter.query(hostFilter, { limit: batchSize, cursor });
     if (page.contacts.length === 0) break;
     const eligible = await applyPostFilters(page.contacts, postFilters, ctx);
     if (eligible.length > 0) {
       while (await ctx.queues.send.getWaitingCount() > maxWaiting) {
+        await ctx.collections.broadcasts.updateOne(
+          { _id: broadcast._id },
+          { $set: { updatedAt: /* @__PURE__ */ new Date() } }
+        );
         await sleep(2e3);
       }
       const sendDocs = await Promise.all(
@@ -2515,7 +2778,8 @@ async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, resp
   const dedupeKey = `broadcast:${broadcast._id}:${contact.externalId}`;
   let delayMs = Math.max(0, scheduledMs - Date.now());
   if (respectTimezone && contact.timezone) {
-    delayMs = Math.max(0, perRecipientDelayMs(scheduledMs, contact.timezone));
+    const offsetMs = perRecipientOffsetMs(scheduledMs, contact.timezone);
+    delayMs = Math.max(0, scheduledMs + offsetMs - Date.now());
   }
   const doc = {
     _id: sendId,
@@ -2554,7 +2818,8 @@ async function buildSendDoc(broadcast, template, contact, ctx, scheduledMs, resp
   };
   return { doc, delayMs };
 }
-function perRecipientDelayMs(scheduledMs, timezone) {
+function perRecipientOffsetMs(scheduledMs, timezone) {
+  const DAY_MS2 = 24 * 60 * 60 * 1e3;
   try {
     const scheduled = new Date(scheduledMs);
     const utc = scheduled.toLocaleString("en-US", { timeZone: "UTC", hour12: false });
@@ -2567,7 +2832,7 @@ function perRecipientDelayMs(scheduledMs, timezone) {
     const utcMs = parse(utc);
     const localMs = parse(local);
     const offsetMs = utcMs - localMs;
-    return offsetMs;
+    return (offsetMs % DAY_MS2 + DAY_MS2) % DAY_MS2;
   } catch {
     return 0;
   }
@@ -3514,6 +3779,7 @@ function suggestPolicyProgression(input) {
 
 // src/server/runner/tick.ts
 var STRANDED_SEND_THRESHOLD_MS = 5 * 60 * 1e3;
+var STRANDED_WEBHOOK_THRESHOLD_MS = 5 * 60 * 1e3;
 async function runTick(ctx) {
   try {
     await ctx.collections.health.updateOne(
@@ -3554,12 +3820,18 @@ async function runTick(ctx) {
   await processScheduledBroadcasts2(ctx).catch((err) => {
     console.error("mailery: broadcast dispatch failed", err);
   });
+  await resumeStalledBroadcasts(ctx).catch((err) => {
+    console.error("mailery: stalled-broadcast resume failed", err);
+  });
   await evaluateHealth(ctx).catch((err) => {
     console.error("mailery: health evaluation failed", err);
   });
   await promoteSoftBounces(ctx).catch((err) => {
     console.error("mailery: soft-bounce promotion failed", err);
   });
+  await processWebhookBacklog(ctx, { olderThanMs: STRANDED_WEBHOOK_THRESHOLD_MS }).catch((err) => {
+    console.error("mailery: stranded-webhook drain failed", err);
+  });
   await Promise.all([
     runDnsblChecks(ctx).catch((err) => {
       console.error("mailery: dnsbl checks failed", err);
@@ -3630,140 +3902,6 @@ async function processScheduledBroadcasts2(ctx) {
   await processScheduledBroadcasts(ctx);
 }
 
-// src/server/runner/webhook.ts
-function dimsFromSend(send) {
-  if (!send) return null;
-  return { fromEmail: send.fromEmail, kind: send.kind };
-}
-async function applyWebhookEvent(event, ctx) {
-  const send = await ctx.collections.sends.findOne(
-    event.providerMessageId ? { $or: [{ providerMessageId: event.providerMessageId }, { emailAtSend: event.email }] } : { emailAtSend: event.email },
-    { sort: { queuedAt: -1 } }
-  );
-  switch (event.type) {
-    case "delivered":
-      if (send) {
-        await ctx.collections.sends.updateOne(
-          { _id: send._id },
-          { $set: { status: "delivered", deliveredAt: event.occurredAt } }
-        );
-      }
-      await recordHealthCounter(ctx, "delivered", dimsFromSend(send));
-      break;
-    case "open":
-      if (send) {
-        await ctx.collections.sends.updateOne(
-          { _id: send._id },
-          {
-            $set: {
-              openedAt: send.openedAt ?? event.occurredAt,
-              status: send.status === "sent" ? "delivered" : send.status
-            },
-            $inc: { openCount: 1 }
-          }
-        );
-      }
-      break;
-    case "click":
-      if (send) {
-        await ctx.collections.sends.updateOne(
-          { _id: send._id },
-          {
-            $set: { firstClickAt: send.firstClickAt ?? event.occurredAt },
-            $inc: { clickCount: 1 },
-            $push: {
-              clickedLinks: {
-                url: event.details.clickedUrl ?? "",
-                linkId: "",
-                clickedAt: event.occurredAt
-              }
-            }
-          }
-        );
-      }
-      break;
-    case "bounce": {
-      const bounceType = event.details.bounceType ?? "hard";
-      if (send) {
-        await ctx.collections.sends.updateOne(
-          { _id: send._id },
-          {
-            $set: {
-              status: "bounced",
-              bounceType,
-              bounceReason: event.details.bounceReason ?? null
-            }
-          }
-        );
-      }
-      if (bounceType === "hard") {
-        await suppressOnce(ctx, event.email, "hard_bounce", "all");
-        await ctx.collections.subscriptions.updateOne(
-          { emailAtSubscribe: event.email },
-          { $set: { status: "bounced", updatedAt: /* @__PURE__ */ new Date() } }
-        );
-      }
-      {
-        const dims = dimsFromSend(send);
-        await recordHealthCounter(ctx, "bounced", dims);
-        await recordHealthCounter(ctx, bounceType === "hard" ? "hardBounced" : "softBounced", dims);
-      }
-      break;
-    }
-    case "complaint":
-    case "spam_report":
-      if (send) {
-        await ctx.collections.sends.updateOne(
-          { _id: send._id },
-          { $set: { complainedAt: event.occurredAt, status: "complained" } }
-        );
-      }
-      await suppressOnce(ctx, event.email, "complaint", "all");
-      await ctx.collections.subscriptions.updateOne(
-        { emailAtSubscribe: event.email },
-        { $set: { status: "complained", updatedAt: /* @__PURE__ */ new Date() } }
-      );
-      await recordHealthCounter(ctx, "complained", dimsFromSend(send));
-      break;
-    case "unsubscribe":
-      if (send) {
-        await ctx.collections.sends.updateOne({ _id: send._id }, { $set: { unsubscribedAt: event.occurredAt } });
-      }
-      await suppressOnce(ctx, event.email, "unsubscribed", "marketing");
-      await ctx.collections.subscriptions.updateOne(
-        { emailAtSubscribe: event.email },
-        {
-          $set: {
-            status: "unsubscribed",
-            unsubscribedAt: event.occurredAt,
-            unsubscribeReason: "user_request",
-            updatedAt: /* @__PURE__ */ new Date()
-          }
-        }
-      );
-      break;
-  }
-}
-async function suppressOnce(ctx, email, reason, scope) {
-  const normalized = email.toLowerCase();
-  await ctx.collections.suppressions.updateOne(
-    { email: normalized, scope },
-    {
-      $setOnInsert: {
-        email: normalized,
-        emailHash: sha256Hex(normalized),
-        scope,
-        reason,
-        source: "provider_webhook",
-        notes: null,
-        addedAt: /* @__PURE__ */ new Date(),
-        expiresAt: null
-      }
-    },
-    { upsert: true }
-  );
-}
-
 // src/server/mailer.ts
 var Mailer = class _Mailer {
   db;
@@ -4228,41 +4366,48 @@ var Mailer = class _Mailer {
     if (existing) return { sendId: String(existing._id) };
     const providerName = parsed.providerOverride ?? template.providerOverride ?? (template.kind === "transactional" ? this.config.defaultTransactionalProvider : null) ?? this.config.defaultProvider;
     const sendId = new mongodb.ObjectId();
-    await this.collections.sends.insertOne({
-      _id: sendId,
-      dedupeKey,
-      externalId: parsed.externalId,
-      emailAtSend: contact.email,
-      templateId: template._id,
-      templateSlug: template.slug,
-      flowRunId: null,
-      broadcastId: null,
-      manualSendBy: "sendOneOff",
-      kind: template.kind,
-      provider: providerName,
-      providerMessageId: null,
-      fromName: template.fromName,
-      fromEmail: template.fromEmail,
-      subject: template.subject,
-      bodyHash: "",
-      status: "queued",
-      errorMessage: null,
-      bounceType: null,
-      bounceReason: null,
-      links: [],
-      vars: parsed.vars ?? {},
-      openedAt: null,
-      openCount: 0,
-      firstClickAt: null,
-      clickCount: 0,
-      clickedLinks: [],
-      unsubscribedAt: null,
-      complainedAt: null,
-      queuedAt: /* @__PURE__ */ new Date(),
-      updatedAt: /* @__PURE__ */ new Date(),
-      sentAt: null,
-      deliveredAt: null
-    });
+    try {
+      await this.collections.sends.insertOne({
+        _id: sendId,
+        dedupeKey,
+        externalId: parsed.externalId,
+        emailAtSend: contact.email,
+        templateId: template._id,
+        templateSlug: template.slug,
+        flowRunId: null,
+        broadcastId: null,
+        manualSendBy: "sendOneOff",
+        kind: template.kind,
+        provider: providerName,
+        providerMessageId: null,
+        fromName: template.fromName,
+        fromEmail: template.fromEmail,
+        subject: template.subject,
+        bodyHash: "",
+        status: "queued",
+        errorMessage: null,
+        bounceType: null,
+        bounceReason: null,
+        links: [],
+        vars: parsed.vars ?? {},
+        openedAt: null,
+        openCount: 0,
+        firstClickAt: null,
+        clickCount: 0,
+        clickedLinks: [],
+        unsubscribedAt: null,
+        complainedAt: null,
+        queuedAt: /* @__PURE__ */ new Date(),
+        updatedAt: /* @__PURE__ */ new Date(),
+        sentAt: null,
+        deliveredAt: null
+      });
+    } catch (err) {
+      if (err?.code !== 11e3) throw err;
+      const winner = await this.collections.sends.findOne({ dedupeKey });
+      if (winner) return { sendId: String(winner._id) };
+      throw err;
+    }
     await this.queues.send.add(
       "send",
       { sendId: String(sendId) },
@@ -4306,7 +4451,12 @@ var Mailer = class _Mailer {
           await runTick(this.runnerContext);
         },
         advance: async (data) => {
-          if (!mongodb.ObjectId.isValid(data.flowRunId)) return;
+          if (data.broadcastId) {
+            if (!mongodb.ObjectId.isValid(data.broadcastId)) return;
+            await dispatchBroadcastById(new mongodb.ObjectId(data.broadcastId), this.runnerContext);
+            return;
+          }
+          if (!data.flowRunId || !mongodb.ObjectId.isValid(data.flowRunId)) return;
           await processOneRunStep(new mongodb.ObjectId(data.flowRunId), this.runnerContext);
         },
         send: async (data) => {
@@ -4322,27 +4472,7 @@ var Mailer = class _Mailer {
   }
   /** Process unprocessed webhook events in mailer_webhook_events. */
   async processWebhookBacklog() {
-    const batch = await this.collections.webhookEvents.find({ processed: false }).limit(500).toArray();
-    for (const evt of batch) {
-      try {
-        const normalized = evt.raw?.normalized;
-        const details = normalized?.details ?? {};
-        await applyWebhookEvent(
-          {
-            type: evt.normalizedType,
-            providerEventId: evt.providerEventId,
-            providerMessageId: evt.providerMessageId,
-            email: evt.email,
-            occurredAt: evt.occurredAt,
-            details
-          },
-          this.runnerContext
-        );
-        await this.collections.webhookEvents.updateOne({ _id: evt._id }, { $set: { processed: true } });
-      } catch (err) {
-        console.error("mailery: webhook apply failed", { id: String(evt._id), err });
-      }
-    }
+    await processWebhookBacklog(this.runnerContext);
   }
   async stop() {
     await this.queueDriver.close();
@@ -5071,7 +5201,7 @@ async function checkPostalAddress(mailer) {
     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."
+    hint: "CAN-SPAM requires a postal address in marketing emails. Set `senderAddress` in your Mailer config and reference the `{{senderAddress}}` render variable in your templates."
   };
 }
 async function checkDoiTemplate(mailer) {
@@ -5365,19 +5495,30 @@ async function persistScore(ctx, input) {
 }
 async function evaluateMailTesterGate(ctx, input) {
   const cfg = ctx.config.mailTester;
-  if (!cfg?.apiKey) return { allowed: true, reason: null, score: null };
+  if (!cfg?.apiKey) return { allowed: true, reason: null, score: null, code: null };
   const minScore = cfg.minScore ?? 8;
   const key = mailTesterContentKey(input);
   const cached = await findCachedScore(ctx, key);
-  if (!cached) return { allowed: true, reason: null, score: null };
+  if (!cached) {
+    if (cfg.requireScore) {
+      return {
+        allowed: false,
+        reason: "No Mail-Tester score for this exact content. Run a deliverability check before publishing.",
+        score: null,
+        code: "no_score"
+      };
+    }
+    return { allowed: true, reason: null, score: null, code: null };
+  }
   if (cached.score < minScore) {
     return {
       allowed: false,
       reason: `Mail-Tester score ${cached.score.toFixed(1)} is below minimum ${minScore.toFixed(1)}`,
-      score: cached
+      score: cached,
+      code: "low_score"
     };
   }
-  return { allowed: true, reason: null, score: cached };
+  return { allowed: true, reason: null, score: cached, code: null };
 }
 
 // src/server/api/admin.ts
@@ -6371,6 +6512,7 @@ function apiRouter(mailer, opts = {}) {
       res.json({
         configured,
         minScore: cfg?.minScore ?? 8,
+        requireScore: !!cfg?.requireScore,
         cacheHours: cfg?.cacheHours ?? 24,
         score: cached
       });
@@ -6585,9 +6727,10 @@ function apiRouter(mailer, opts = {}) {
         if (!gate.allowed) {
           return res.status(422).json({
             error: "mail_tester_blocked",
+            code: gate.code,
             message: gate.reason,
             score: gate.score,
-            hint: "Re-run the deliverability check after fixing the feedback, or POST `bypassMailTester: true` to publish anyway."
+            hint: gate.code === "no_score" ? "POST to `/templates/:slug/mail-tester-check`, poll `/mail-tester-result`, then publish \u2014 or POST `bypassMailTester: true` to publish anyway." : "Re-run the deliverability check after fixing the feedback, or POST `bypassMailTester: true` to publish anyway."
           });
         }
       }
@@ -7395,7 +7538,7 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION = "0.7.0";
+var VERSION = "0.8.1";
 
 exports.DEDUPE_POLICIES = DEDUPE_POLICIES;
 exports.FLOW_STEP_KINDS = FLOW_STEP_KINDS;