mailery 0.15.0 → 0.16.1

package/dist/index.js

@@ -268,8 +268,36 @@ var init_webhook_tolerance = __esm({
 // src/server/providers/sendgrid.ts
 var sendgrid_exports = {};
 __export(sendgrid_exports, {
-  SendGridProvider: () => SendGridProvider
+  SendGridProvider: () => SendGridProvider,
+  normalizeWebhookVerificationKey: () => normalizeWebhookVerificationKey
 });
+function normalizeWebhookVerificationKey(input) {
+  let key = String(input ?? "").trim().replace(/^["']|["']$/g, "");
+  if (key.includes("\\n")) key = key.replace(/\\n/g, "\n");
+  let pem;
+  if (key.includes(PEM_HEADER)) {
+    pem = key;
+  } else {
+    const b64 = key.replace(/\s+/g, "");
+    if (!b64 || !/^[A-Za-z0-9+/=]+$/.test(b64)) {
+      throw new Error(
+        "SendGridProvider: webhookVerificationKey is neither a PEM public key nor a base64 SPKI key. Copy the Verification Key from SendGrid \u2192 Settings \u2192 Mail Settings \u2192 Signed Event Webhook."
+      );
+    }
+    pem = `${PEM_HEADER}
+${b64.match(/.{1,64}/g).join("\n")}
+${PEM_FOOTER}
+`;
+  }
+  try {
+    crypto2.createPublicKey(pem);
+  } catch (err) {
+    throw new Error(
+      `SendGridProvider: webhookVerificationKey did not parse as a public key (${String(err?.message ?? err)}). Copy the Verification Key from SendGrid \u2192 Settings \u2192 Mail Settings \u2192 Signed Event Webhook.`
+    );
+  }
+  return pem;
+}
 function normalizeSendGridEvent(e) {
   const type = mapEventType(e.event);
   if (!type) return null;
@@ -308,24 +336,29 @@ function mapEventType(sgEvent) {
       return null;
   }
 }
-var SG_SIG_HEADER, SG_TS_HEADER, SendGridProvider;
+var SG_SIG_HEADER, SG_TS_HEADER, PEM_HEADER, PEM_FOOTER, SendGridProvider;
 var init_sendgrid = __esm({
   "src/server/providers/sendgrid.ts"() {
     init_webhook_tolerance();
     SG_SIG_HEADER = "x-twilio-email-event-webhook-signature";
     SG_TS_HEADER = "x-twilio-email-event-webhook-timestamp";
+    PEM_HEADER = "-----BEGIN PUBLIC KEY-----";
+    PEM_FOOTER = "-----END PUBLIC KEY-----";
     SendGridProvider = class {
       constructor(opts) {
         this.opts = opts;
         sgMail.setApiKey(opts.apiKey);
         this.sendRatePerSecond = opts.sendRatePerSecond ?? 10;
         this.webhookToleranceSeconds = resolveWebhookToleranceSeconds(opts.webhookToleranceSeconds);
+        this.verificationKeyPem = opts.webhookVerificationKey ? normalizeWebhookVerificationKey(opts.webhookVerificationKey) : null;
       }
       opts;
       name = "sendgrid";
       sendRatePerSecond;
       /** Resolved replay window in seconds; `0` means the check is disabled. */
       webhookToleranceSeconds;
+      /** The verification key as PEM, whatever shape it was configured in. */
+      verificationKeyPem;
       async send(args) {
         const msg = {
           to: args.to,
@@ -357,7 +390,7 @@ var init_sendgrid = __esm({
         };
       }
       async verifyWebhook(rawBody, headers) {
-        if (!this.opts.webhookVerificationKey) return false;
+        if (!this.verificationKeyPem) return false;
         const sig = headers[SG_SIG_HEADER];
         const ts = headers[SG_TS_HEADER];
         if (!sig || !ts) return false;
@@ -365,7 +398,7 @@ var init_sendgrid = __esm({
         try {
           const verifier = crypto2.createVerify("sha256");
           verifier.update(payload);
-          if (!verifier.verify(this.opts.webhookVerificationKey, sig, "base64")) return false;
+          if (!verifier.verify(this.verificationKeyPem, sig, "base64")) return false;
         } catch {
           return false;
         }
@@ -6162,13 +6195,13 @@ function createAdminRouter(mailer, opts = {}) {
     req.actor = getActor(req);
     next();
   });
-  router.use("/api", apiRouter(mailer, opts));
+  router.use("/api", createAdminApiRouter(mailer, opts));
   router.get(/.*/, (_req, res) => {
     res.sendFile(path.join(spaDir, "index.html"));
   });
   return router;
 }
-function apiRouter(mailer, opts = {}) {
+function createAdminApiRouter(mailer, opts = {}) {
   const r = Router();
   const c = mailer.collections;
   const varsSchema = mailer.config.varsAdapter ? varsJsonSchema(mailer.config.varsAdapter) : null;
@@ -6365,7 +6398,11 @@ function apiRouter(mailer, opts = {}) {
     asyncHandler(async (req, res) => {
       const before = await c.flows.findOne({ slug: req.params.slug });
       if (!before) return res.status(404).json({ error: "not_found" });
-      await c.flows.updateOne({ _id: before._id }, { $set: { enabled: true, updatedAt: /* @__PURE__ */ new Date() } });
+      const now = /* @__PURE__ */ new Date();
+      await c.flows.updateOne(
+        { _id: before._id },
+        { $set: { enabled: true, updatedAt: now, ...before.lastTriggerScanAt ? {} : { lastTriggerScanAt: now } } }
+      );
       await mailer.audit({
         actor: req.actor,
         action: "flow.resume",
@@ -6946,6 +6983,7 @@ function apiRouter(mailer, opts = {}) {
       if (!Array.isArray(draftSteps) || draftSteps.length === 0) {
         return res.status(400).json({ error: "empty_flow", message: "flow has no steps to publish" });
       }
+      const enable = req.body?.enable !== false;
       const nextVersion = (flow.version ?? 0) + 1;
       const now = /* @__PURE__ */ new Date();
       await c.flowVersions.insertOne({
@@ -6962,11 +7000,14 @@ function apiRouter(mailer, opts = {}) {
           $set: {
             steps: draftSteps,
             version: nextVersion,
-            enabled: true,
+            enabled: enable ? true : flow.enabled,
             draft: null,
             publishedAt: now,
             publishedBy: req.actor,
-            updatedAt: now
+            updatedAt: now,
+            // First enable: stamp the trigger watermark so the scan does not
+            // replay every event since the flow document was created.
+            ...enable && !flow.lastTriggerScanAt ? { lastTriggerScanAt: now } : {}
           }
         }
       );
@@ -6974,9 +7015,9 @@ function apiRouter(mailer, opts = {}) {
         actor: req.actor,
         action: "flow.publish",
         resource: { collection: "mailer_flows", id: flow._id, slug: flow.slug },
-        diffSummary: `Published v${nextVersion}`
+        diffSummary: `Published v${nextVersion}${enable ? "" : " (left disabled)"}`
       });
-      return res.json({ ok: true, version: nextVersion });
+      return res.json({ ok: true, version: nextVersion, enabled: enable ? true : flow.enabled });
     })
   );
   r.delete(
@@ -7847,7 +7888,1345 @@ function wrap(logger, handler) {
   };
 }
 
-// src/server/api/dmarc-inbound.ts
+// src/server/api/agent.ts
+init_vars();
+
+// src/server/runner/arm.ts
+var FlowOperationError = class extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "FlowOperationError";
+  }
+  code;
+  status;
+};
+async function stampWatermarkIfNull(collections, flow, now = /* @__PURE__ */ new Date()) {
+  if (flow.lastTriggerScanAt) return flow.lastTriggerScanAt;
+  await collections.flows.updateOne(
+    { _id: flow._id, lastTriggerScanAt: null },
+    { $set: { lastTriggerScanAt: now, updatedAt: now } }
+  );
+  return now;
+}
+async function armFlow(mailer, slug, opts) {
+  const c = mailer.collections;
+  const flow = await c.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  if (!Array.isArray(flow.steps) || flow.steps.length === 0) {
+    throw new FlowOperationError(
+      "no_live_steps",
+      `flow "${slug}" (v${flow.version}) has no published steps \u2014 publish it first; an empty flow completes every run instantly`,
+      409
+    );
+  }
+  const eventName = flow.trigger?.eventName ?? null;
+  const now = /* @__PURE__ */ new Date();
+  const watermark = opts.since ?? now;
+  if (flow.enabled) {
+    return {
+      slug,
+      version: flow.version,
+      armed: false,
+      alreadyEnabled: true,
+      watermark: flow.lastTriggerScanAt ?? null,
+      eventName,
+      skippedEvents: 0,
+      pendingEvents: 0
+    };
+  }
+  const previous = flow.lastTriggerScanAt ?? flow.createdAt;
+  const overlapFrom = new Date(watermark.getTime() - SCAN_OVERLAP_MS);
+  const [skippedEvents, pendingEvents] = eventName ? await Promise.all([
+    c.events.countDocuments({ name: eventName, createdAt: { $gt: previous, $lte: overlapFrom } }),
+    c.events.countDocuments({ name: eventName, createdAt: { $gt: overlapFrom } })
+  ]) : [0, 0];
+  const res = await c.flows.updateOne(
+    { _id: flow._id, enabled: false },
+    { $set: { enabled: true, lastTriggerScanAt: watermark, updatedAt: now } }
+  );
+  if (res.modifiedCount === 0) {
+    const again = await c.flows.findOne({ _id: flow._id });
+    return {
+      slug,
+      version: flow.version,
+      armed: false,
+      alreadyEnabled: !!again?.enabled,
+      watermark: again?.lastTriggerScanAt ?? null,
+      eventName,
+      skippedEvents: 0,
+      pendingEvents: 0
+    };
+  }
+  await mailer.audit({
+    actor: opts.actor,
+    action: "flow.arm",
+    resource: { collection: "mailer_flows", id: flow._id, slug },
+    diffSummary: `Enabled v${flow.version} with lastTriggerScanAt=${watermark.toISOString()} (skipped ${skippedEvents} earlier ${eventName ?? "trigger"} event(s), ${pendingEvents} pending)`
+  });
+  return {
+    slug,
+    version: flow.version,
+    armed: true,
+    alreadyEnabled: false,
+    watermark,
+    eventName,
+    skippedEvents,
+    pendingEvents
+  };
+}
+async function disarmFlow(mailer, slug, actor) {
+  const c = mailer.collections;
+  const flow = await c.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  if (!flow.enabled) return { slug, disarmed: false };
+  await c.flows.updateOne({ _id: flow._id }, { $set: { enabled: false, updatedAt: /* @__PURE__ */ new Date() } });
+  await mailer.audit({
+    actor,
+    action: "flow.pause",
+    resource: { collection: "mailer_flows", id: flow._id, slug },
+    diffSummary: "Disarmed (enabled: false); in-flight runs continue"
+  });
+  return { slug, disarmed: true };
+}
+function isCanaryGate(step) {
+  const s = step;
+  return !!s && s.type === "condition" && s.canaryGate === true;
+}
+function gateStep(tag) {
+  return { type: "condition", test: { hasTag: tag }, ifFalse: "exit", canaryGate: true };
+}
+async function publishVersion(mailer, flow, steps, actor, summary) {
+  const c = mailer.collections;
+  const nextVersion = (flow.version ?? 0) + 1;
+  const now = /* @__PURE__ */ new Date();
+  await c.flowVersions.insertOne({
+    flowId: flow._id,
+    version: nextVersion,
+    steps,
+    trigger: flow.trigger,
+    publishedAt: now,
+    publishedBy: actor
+  });
+  await c.flows.updateOne(
+    { _id: flow._id },
+    { $set: { steps, version: nextVersion, draft: null, publishedAt: now, publishedBy: actor, updatedAt: now } }
+  );
+  await mailer.audit({
+    actor,
+    action: "flow.publish",
+    resource: { collection: "mailer_flows", id: flow._id, slug: flow.slug },
+    diffSummary: `Published v${nextVersion}: ${summary}`
+  });
+  return { version: nextVersion };
+}
+async function gateFlow(mailer, slug, opts) {
+  const tag = String(opts.tag ?? "").trim();
+  if (!tag) throw new FlowOperationError("tag_required", "a canary tag is required");
+  const flow = await mailer.collections.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  const live = Array.isArray(flow.steps) ? flow.steps : [];
+  if (live.length === 0) {
+    throw new FlowOperationError("no_live_steps", `flow "${slug}" has no published steps to gate`, 409);
+  }
+  if (isCanaryGate(live[0])) {
+    throw new FlowOperationError(
+      "already_gated",
+      `flow "${slug}" v${flow.version} is already gated on "${live[0].test.hasTag}" \u2014 ungate first`,
+      409
+    );
+  }
+  await mailer.collections.flowVersions.updateOne(
+    { flowId: flow._id, version: flow.version },
+    {
+      $setOnInsert: {
+        flowId: flow._id,
+        version: flow.version,
+        steps: live,
+        trigger: flow.trigger,
+        publishedAt: flow.publishedAt ?? flow.updatedAt ?? /* @__PURE__ */ new Date(),
+        publishedBy: flow.publishedBy ?? "unknown"
+      }
+    },
+    { upsert: true }
+  );
+  const { version } = await publishVersion(
+    mailer,
+    flow,
+    [gateStep(tag), ...live],
+    opts.actor,
+    `canary gate on tag "${tag}"`
+  );
+  return { slug, version, tag, enabled: flow.enabled };
+}
+async function ungateFlow(mailer, slug, opts) {
+  const c = mailer.collections;
+  const flow = await c.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  const live = Array.isArray(flow.steps) ? flow.steps : [];
+  if (!isCanaryGate(live[0])) {
+    throw new FlowOperationError("not_gated", `flow "${slug}" v${flow.version} is not gated`, 409);
+  }
+  const versions = await c.flowVersions.find({ flowId: flow._id }).sort({ version: -1 }).toArray();
+  const clean = versions.find((v) => Array.isArray(v.steps) && v.steps.length > 0 && !isCanaryGate(v.steps[0]));
+  if (!clean) {
+    throw new FlowOperationError(
+      "no_ungated_version",
+      `flow "${slug}" has no ungated version in mailer_flow_versions to restore`,
+      409
+    );
+  }
+  const { version } = await publishVersion(
+    mailer,
+    flow,
+    clean.steps,
+    opts.actor,
+    `restored steps of v${clean.version} (canary gate removed)`
+  );
+  return { slug, version, restoredFrom: clean.version, enabled: flow.enabled };
+}
+var MAX_STEPS = 1e3;
+async function simulateFlow(flow, contact, ctx, opts = {}) {
+  const enteredAt = opts.at ?? /* @__PURE__ */ new Date();
+  const steps = opts.steps ?? flow.steps ?? [];
+  const eventName = flow.trigger?.eventName ?? "simulated";
+  const eventProperties = opts.eventProperties ?? {};
+  const reasons = [];
+  if (!flow.enabled) reasons.push("flow is disabled (enabled: false)");
+  const sub = await ctx.collections.subscriptions.findOne({ externalId: contact.externalId });
+  if (!sub) reasons.push("contact has no subscription row \u2014 the trigger scan requires one");
+  else if (sub.status !== "subscribed") reasons.push(`subscription status is "${sub.status}", not "subscribed"`);
+  if (flow.trigger?.once) {
+    const existing = await ctx.collections.flowRuns.findOne(
+      { externalId: contact.externalId, flowId: flow._id },
+      { projection: { _id: 1, status: 1 } }
+    );
+    if (existing) reasons.push(`trigger.once is true and the contact already has a run (${existing.status})`);
+  }
+  if (steps.length === 0) reasons.push("flow has no live steps \u2014 a run would complete immediately");
+  const run = {
+    _id: new ObjectId(),
+    externalId: contact.externalId,
+    flowId: flow._id,
+    flowSlug: flow.slug,
+    flowVersion: flow.version,
+    emailAtEntry: contact.email,
+    triggerEvent: { name: eventName, properties: eventProperties, occurredAt: enteredAt },
+    triggerDedupeKey: null,
+    enteredAt,
+    status: "active",
+    currentStepIndex: 0,
+    currentBranchPath: [],
+    nextActionAt: enteredAt,
+    attemptsForCurrentStep: 0,
+    history: [],
+    exitedAt: null,
+    exitReason: null,
+    createdAt: enteredAt,
+    updatedAt: enteredAt
+  };
+  const path3 = [];
+  const sends = [];
+  let list = steps;
+  let index = 0;
+  let branchPath = [];
+  let t = enteredAt;
+  let terminal = null;
+  const record = (type, outcome, detail) => {
+    path3.push({ at: t, stepIndex: index, branchPath: [...branchPath], type, outcome, ...detail ? { detail } : {} });
+  };
+  const predicateCtx = () => ({
+    contact,
+    run: { ...run, currentStepIndex: index, currentBranchPath: branchPath, nextActionAt: t },
+    collections: ctx.collections,
+    now: t,
+    botFilter: ctx.config.botFilter
+  });
+  for (let guard = 0; guard < MAX_STEPS && !terminal; guard += 1) {
+    const step = list[index];
+    if (!step) {
+      terminal = { kind: "completed", reason: "sequence_complete", at: t };
+      break;
+    }
+    switch (step.type) {
+      case "wait": {
+        const ms = unitToMs2(step.value, step.unit);
+        record("wait", "waited", { value: step.value, unit: step.unit, until: new Date(t.getTime() + ms) });
+        t = new Date(t.getTime() + ms);
+        index += 1;
+        break;
+      }
+      case "condition": {
+        const result = await evaluatePredicate(step.test, predicateCtx());
+        if (result) {
+          record("condition", "passed", { test: step.test, result });
+          index += 1;
+        } else if (step.ifFalse === "continue") {
+          record("condition", "skipped_next", { test: step.test, result });
+          index += 2;
+        } else {
+          record("condition", "exited", { test: step.test, result });
+          terminal = { kind: "exited", reason: "condition_false", at: t };
+        }
+        break;
+      }
+      case "branch": {
+        const result = await evaluatePredicate(step.test, predicateCtx());
+        record("branch", result ? "branch_true" : "branch_false", { test: step.test, result });
+        branchPath = [...branchPath, index, result ? "true" : "false", 0];
+        list = result ? step.ifTrueSteps : step.ifFalseSteps;
+        index = 0;
+        break;
+      }
+      case "send": {
+        let at = t;
+        if (step.delivery) {
+          at = computeDeliveryTime(t, step.delivery, contact.timezone);
+        }
+        if (at.getTime() > t.getTime() + 3e4) {
+          record("send", "send_deferred", { templateSlug: step.templateSlug, delivery: step.delivery, until: at });
+          t = at;
+        }
+        record("send", "send", { templateSlug: step.templateSlug });
+        sends.push({ templateSlug: step.templateSlug, at: t, stepIndex: index, branchPath: [...branchPath] });
+        index += 1;
+        break;
+      }
+      case "tag":
+        record("tag", "tagged", { addTags: step.addTags ?? [], removeTags: step.removeTags ?? [] });
+        index += 1;
+        break;
+      case "fire_event":
+        record("fire_event", "event_fired", { eventName: step.eventName });
+        index += 1;
+        break;
+      case "webhook":
+        record("webhook", "webhook", { url: step.url, method: step.method ?? "POST", note: "not called in simulation" });
+        index += 1;
+        break;
+      case "exit":
+        record("exit", "exited", { reason: step.reason ?? "exit_step" });
+        terminal = { kind: "exited", reason: step.reason ?? "exit_step", at: t };
+        break;
+    }
+  }
+  if (!terminal) terminal = { kind: "truncated", reason: `stopped after ${MAX_STEPS} steps`, at: t };
+  return {
+    flow: { slug: flow.slug, version: flow.version, enabled: flow.enabled },
+    contact: { externalId: contact.externalId, email: contact.email },
+    enteredAt,
+    wouldEnter: { ok: reasons.length === 0, reasons },
+    path: path3,
+    sends,
+    terminal,
+    durationMs: terminal.at.getTime() - enteredAt.getTime()
+  };
+}
+function unitToMs2(value, unit) {
+  const m = 6e4;
+  switch (unit) {
+    case "minutes":
+      return value * m;
+    case "hours":
+      return value * 60 * m;
+    case "days":
+      return value * 24 * 60 * m;
+    case "weeks":
+      return value * 7 * 24 * 60 * m;
+  }
+}
+
+// src/server/api/agent.ts
+var VERSION = "0.16.1" ;
+var MIN_AGENT_TOKEN_LENGTH = 24;
+function createAgentRouter(mailer, opts) {
+  if (!opts || !Array.isArray(opts.tokens) || opts.tokens.length === 0) {
+    throw new Error("createAgentRouter: at least one bearer token is required \u2014 the agent API is never open");
+  }
+  for (const t of opts.tokens) {
+    if (typeof t?.token !== "string" || t.token.length < MIN_AGENT_TOKEN_LENGTH) {
+      throw new Error(
+        `createAgentRouter: every token must be at least ${MIN_AGENT_TOKEN_LENGTH} characters (got ${t?.token?.length ?? 0})`
+      );
+    }
+    if (typeof t.actor !== "string" || !t.actor.trim()) {
+      throw new Error('createAgentRouter: every token needs an actor label, e.g. "agent:claude"');
+    }
+  }
+  const logger = opts.logger ?? consoleRouteLogger;
+  const isTestContact = testContactMatcher(opts.testContacts);
+  const c = mailer.collections;
+  const varsSchema = mailer.config.varsAdapter ? varsJsonSchema(mailer.config.varsAdapter) : null;
+  const router = Router();
+  router.use(express.json({ limit: "1mb" }));
+  router.use(bearerAuth(opts.tokens));
+  router.use("/api", createAdminApiRouter(mailer, { mailTesterClient: opts.mailTesterClient }));
+  const actorOf = (req) => String(req.actor);
+  function guardTestContact(res, contact) {
+    if (!isTestContact) {
+      res.status(403).json({
+        error: "test_contacts_not_configured",
+        message: "this route only acts on test contacts, and the router was constructed without a testContacts pattern"
+      });
+      return false;
+    }
+    if (!isTestContact(contact.email)) {
+      res.status(403).json({
+        error: "not_a_test_contact",
+        message: `${contact.email} does not match the testContacts pattern`,
+        externalId: contact.externalId
+      });
+      return false;
+    }
+    return true;
+  }
+  async function loadContact(res, externalId) {
+    const contact = await mailer.adapter.getById(externalId);
+    if (!contact) res.status(404).json({ error: "contact_not_found", externalId });
+    return contact;
+  }
+  async function loadTemplate(res, slug) {
+    const tpl = await c.templates.findOne({ slug });
+    if (!tpl) res.status(404).json({ error: "template_not_found", slug });
+    return tpl;
+  }
+  router.get("/", (req, res) => {
+    res.json({
+      service: "mailery-agent",
+      version: VERSION,
+      actor: actorOf(req),
+      testContactsConfigured: !!isTestContact,
+      docs: "https://jeffjassky.github.io/mailery/reference/agent-api",
+      endpoints: ENDPOINTS
+    });
+  });
+  router.post(
+    "/templates/:slug/verify",
+    wrap2(async (req, res) => {
+      const tpl = await loadTemplate(res, String(req.params.slug));
+      if (!tpl) return;
+      const contact = await contactForRender(req, res);
+      if (!contact) return;
+      const report = await verifyTemplate(mailer, tpl, contact, {
+        eventProperties: objectOrUndefined(req.body?.eventProperties),
+        vars: objectOrUndefined(req.body?.vars),
+        includeRendered: req.body?.includeRendered === true,
+        varsSchema
+      });
+      res.status(200).json(report);
+    })
+  );
+  router.post(
+    "/templates/verify-all",
+    wrap2(async (req, res) => {
+      const slugs = Array.isArray(req.body?.slugs) ? req.body.slugs.map(String) : null;
+      const contactIds = Array.isArray(req.body?.contactIds) ? req.body.contactIds.map(String) : [];
+      if (contactIds.length === 0) {
+        return res.status(400).json({ error: "validation_failed", message: "contactIds (non-empty array) is required" });
+      }
+      const templates = await c.templates.find(slugs ? { slug: { $in: slugs } } : {}).sort({ slug: 1 }).toArray();
+      const contacts = [];
+      for (const id of contactIds) {
+        const found = await mailer.adapter.getById(id);
+        if (!found) return res.status(404).json({ error: "contact_not_found", externalId: id });
+        contacts.push(found);
+      }
+      const results = [];
+      for (const tpl of templates) {
+        for (const contact of contacts) {
+          const report = await verifyTemplate(mailer, tpl, contact, {
+            eventProperties: objectOrUndefined(req.body?.eventProperties),
+            includeRendered: false,
+            varsSchema
+          });
+          results.push({
+            slug: tpl.slug,
+            contactId: contact.externalId,
+            ok: report.ok,
+            failed: report.checks.filter((k) => k.status === "fail").map((k) => k.id),
+            warned: report.checks.filter((k) => k.status === "warn").map((k) => k.id)
+          });
+        }
+      }
+      const failing = results.filter((r) => !r.ok);
+      res.json({
+        ok: failing.length === 0,
+        templates: templates.length,
+        contacts: contacts.length,
+        verified: results.length,
+        failing: failing.length,
+        results
+      });
+    })
+  );
+  router.post(
+    "/templates/:slug/render",
+    wrap2(async (req, res) => {
+      const tpl = await loadTemplate(res, String(req.params.slug));
+      if (!tpl) return;
+      const contact = await contactForRender(req, res);
+      if (!contact) return;
+      const out = await renderForContact(mailer, tpl, contact, {
+        reason: "preview",
+        eventProperties: objectOrUndefined(req.body?.eventProperties),
+        vars: objectOrUndefined(req.body?.vars)
+      });
+      res.json({
+        template: { slug: tpl.slug, kind: tpl.kind },
+        contact: { externalId: contact.externalId, email: contact.email },
+        subject: out.rendered.subject,
+        preheader: out.rendered.preheader,
+        fromName: out.rendered.fromName,
+        fromEmail: out.rendered.fromEmail,
+        replyTo: out.rendered.replyTo,
+        html: out.rendered.html,
+        plainText: out.rendered.plainText,
+        resolvedVars: out.resolved,
+        unsubscribeUrl: out.unsubscribeUrl
+      });
+    })
+  );
+  router.post(
+    "/templates/:slug/send",
+    wrap2(async (req, res) => {
+      const tpl = await loadTemplate(res, String(req.params.slug));
+      if (!tpl) return;
+      const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : "";
+      if (!contactId) return res.status(400).json({ error: "validation_failed", message: "contactId is required" });
+      const contact = await loadContact(res, contactId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      if (!tpl.body?.html && !tpl.body?.mjml) {
+        return res.status(409).json({ error: "not_published", message: "template has no published body" });
+      }
+      const dedupeKey = typeof req.body?.dedupeKey === "string" && req.body.dedupeKey ? String(req.body.dedupeKey) : `agent:${crypto2.randomUUID()}`;
+      const { sendId } = await mailer.sendOneOff({
+        templateSlug: tpl.slug,
+        externalId: contact.externalId,
+        dedupeKey,
+        vars: objectOrUndefined(req.body?.vars)
+      });
+      const dispatchNow = req.body?.dispatch !== "queue";
+      if (dispatchNow) {
+        await dispatchSend(new ObjectId(sendId), mailer.getRunnerContext());
+      }
+      const send = await c.sends.findOne({ _id: new ObjectId(sendId) });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.send",
+        resource: { collection: "mailer_sends", id: new ObjectId(sendId), slug: tpl.slug },
+        diffSummary: `to=${contact.email} dispatch=${dispatchNow ? "now" : "queue"} dedupeKey=${dedupeKey}`
+      });
+      res.status(201).json({ sendId, dedupeKey, dispatched: dispatchNow, send: send ? sendSummary(send) : null });
+    })
+  );
+  router.get(
+    "/sends/:id/wait",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const target = String(req.query.status ?? "delivered");
+      if (!WAIT_TARGETS.has(target)) {
+        return res.status(400).json({ error: "validation_failed", message: `status must be one of ${[...WAIT_TARGETS].join(", ")}` });
+      }
+      const timeoutMs = Math.max(0, Math.min(Number(req.query.timeoutMs ?? 3e4) || 0, 55e3));
+      const started = Date.now();
+      let send = null;
+      let reached = false;
+      for (; ; ) {
+        send = await c.sends.findOne({ _id: new ObjectId(id) });
+        if (!send) return res.status(404).json({ error: "not_found" });
+        reached = waitTargetReached(send, target);
+        if (reached || Date.now() - started >= timeoutMs) break;
+        await sleep2(1e3);
+      }
+      const webhookEvents = send.providerMessageId ? await c.webhookEvents.find({ providerMessageId: send.providerMessageId }).sort({ receivedAt: 1 }).limit(100).toArray() : [];
+      res.json({ reached, target, waitedMs: Date.now() - started, send: sendSummary(send), webhookEvents });
+    })
+  );
+  router.post(
+    "/sends/:id/dispatch",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const send = await c.sends.findOne({ _id: new ObjectId(id) });
+      if (!send) return res.status(404).json({ error: "not_found" });
+      const contact = await loadContact(res, send.externalId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      await dispatchSend(send._id, mailer.getRunnerContext());
+      const after = await c.sends.findOne({ _id: send._id });
+      res.json({ send: after ? sendSummary(after) : null });
+    })
+  );
+  router.post(
+    "/flows/:slug/simulate",
+    wrap2(async (req, res) => {
+      const flow = await c.flows.findOne({ slug: String(req.params.slug) });
+      if (!flow) return res.status(404).json({ error: "flow_not_found", slug: String(req.params.slug) });
+      const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : "";
+      if (!contactId) return res.status(400).json({ error: "validation_failed", message: "contactId is required" });
+      const contact = await loadContact(res, contactId);
+      if (!contact) return;
+      let at;
+      if (req.body?.at) {
+        at = new Date(String(req.body.at));
+        if (Number.isNaN(at.getTime())) return res.status(400).json({ error: "validation_failed", message: "at must be an ISO date" });
+      }
+      let steps = void 0;
+      if (req.body?.version !== void 0) {
+        const v = Number(req.body.version);
+        if (v !== flow.version) {
+          const snap = await c.flowVersions.findOne({ flowId: flow._id, version: v });
+          if (!snap) return res.status(404).json({ error: "version_not_found", version: v });
+          steps = snap.steps;
+        }
+      }
+      const result = await simulateFlow(flow, contact, mailer.getRunnerContext(), {
+        at,
+        eventProperties: objectOrUndefined(req.body?.eventProperties),
+        steps
+      });
+      res.json(result);
+    })
+  );
+  router.post(
+    "/flows/:slug/arm",
+    wrap2(async (req, res) => {
+      if (req.body?.confirm !== true) {
+        return res.status(400).json({
+          error: "confirm_required",
+          message: 'arming enables a flow for every future matching event; pass {"confirm": true}'
+        });
+      }
+      let since;
+      if (req.body?.since) {
+        since = new Date(String(req.body.since));
+        if (Number.isNaN(since.getTime())) return res.status(400).json({ error: "validation_failed", message: "since must be an ISO date" });
+      }
+      const result = await armFlow(mailer, String(req.params.slug), { actor: actorOf(req), since });
+      res.json(result);
+    })
+  );
+  router.post(
+    "/flows/:slug/disarm",
+    wrap2(async (req, res) => {
+      res.json(await disarmFlow(mailer, String(req.params.slug), actorOf(req)));
+    })
+  );
+  router.post(
+    "/flows/:slug/gate",
+    wrap2(async (req, res) => {
+      const tag = typeof req.body?.tag === "string" ? req.body.tag : "";
+      res.json(await gateFlow(mailer, String(req.params.slug), { tag, actor: actorOf(req) }));
+    })
+  );
+  router.post(
+    "/flows/:slug/ungate",
+    wrap2(async (req, res) => {
+      res.json(await ungateFlow(mailer, String(req.params.slug), { actor: actorOf(req) }));
+    })
+  );
+  router.get(
+    "/runs",
+    wrap2(async (req, res) => {
+      const filter = {};
+      if (typeof req.query.externalId === "string") filter.externalId = req.query.externalId;
+      if (typeof req.query.flowSlug === "string") filter.flowSlug = req.query.flowSlug;
+      if (typeof req.query.status === "string") filter.status = req.query.status;
+      const limit = Math.min(Math.max(Number(req.query.limit ?? 50) || 50, 1), 200);
+      const runs = await c.flowRuns.find(filter).sort({ enteredAt: -1 }).limit(limit).toArray();
+      res.json(runs.map(runSummary));
+    })
+  );
+  router.get(
+    "/runs/:id",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new ObjectId(id) });
+      if (!run) return res.status(404).json({ error: "not_found" });
+      const sends = await c.sends.find({ flowRunId: run._id }).sort({ queuedAt: 1 }).toArray();
+      res.json({ run, sends: sends.map(sendSummary) });
+    })
+  );
+  router.post(
+    "/runs/:id/advance",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new ObjectId(id) });
+      if (!run) return res.status(404).json({ error: "not_found" });
+      const contact = await loadContact(res, run.externalId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      if (run.status !== "active") {
+        return res.status(409).json({ error: "run_not_active", status: run.status, exitReason: run.exitReason });
+      }
+      const steps = Math.min(Math.max(Number(req.body?.steps ?? 1) || 1, 1), 50);
+      const dispatch = req.body?.dispatch !== false;
+      const ctx = mailer.getRunnerContext();
+      const startedAt = /* @__PURE__ */ new Date();
+      const historyBefore = run.history.length;
+      const actor = actorOf(req);
+      for (let i = 0; i < steps; i += 1) {
+        const advanced = await advanceOnce(run._id, ctx, actor, c);
+        if (!advanced) break;
+      }
+      const after = await c.flowRuns.findOne({ _id: run._id });
+      const newSends = await c.sends.find({ flowRunId: run._id, queuedAt: { $gte: startedAt } }).toArray();
+      if (dispatch) {
+        for (const s of newSends) {
+          if (s.status === "queued") await dispatchSend(s._id, ctx);
+        }
+      }
+      const sends = await c.sends.find({ flowRunId: run._id, queuedAt: { $gte: startedAt } }).toArray();
+      await mailer.audit({
+        actor,
+        action: "agent.run.advance",
+        resource: { collection: "mailer_flow_runs", id: run._id, slug: run.flowSlug },
+        diffSummary: `advanced ${steps} step(s) for ${contact.email}; ${sends.length} send(s) created`
+      });
+      res.json({
+        run: after ? runSummary(after) : null,
+        historyAdded: after ? after.history.slice(historyBefore) : [],
+        sends: sends.map(sendSummary)
+      });
+    })
+  );
+  router.post(
+    "/runs/:id/cancel",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new ObjectId(id) });
+      if (!run) return res.status(404).json({ error: "not_found" });
+      if (run.status !== "active") return res.status(409).json({ error: "run_not_active", status: run.status });
+      const actor = actorOf(req);
+      await exitFlowRun(run, `aborted_by_host:${actor}`, mailer.getRunnerContext());
+      const cancelled = await c.sends.updateMany(
+        { flowRunId: run._id, status: "queued" },
+        { $set: { status: "cancelled", errorMessage: `cancelled: aborted_by_host:${actor}`, updatedAt: /* @__PURE__ */ new Date() } }
+      );
+      await mailer.audit({
+        actor,
+        action: "agent.run.cancel",
+        resource: { collection: "mailer_flow_runs", id: run._id, slug: run.flowSlug },
+        diffSummary: `cancelled run for ${run.externalId}; ${cancelled.modifiedCount} queued send(s) cancelled`
+      });
+      const after = await c.flowRuns.findOne({ _id: run._id });
+      res.json({ run: after ? runSummary(after) : null, cancelledSends: cancelled.modifiedCount });
+    })
+  );
+  router.post(
+    "/events",
+    wrap2(async (req, res) => {
+      const name = typeof req.body?.name === "string" ? req.body.name : "";
+      const externalId = typeof req.body?.externalId === "string" ? req.body.externalId : "";
+      if (!name || !externalId) {
+        return res.status(400).json({ error: "validation_failed", message: "name and externalId are required" });
+      }
+      const contact = await loadContact(res, externalId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      const dedupeKey = typeof req.body?.dedupeKey === "string" && req.body.dedupeKey ? req.body.dedupeKey : void 0;
+      try {
+        await mailer.fire(name, externalId, objectOrUndefined(req.body?.properties) ?? {}, dedupeKey);
+      } catch (err) {
+        return res.status(400).json({ error: "fire_failed", message: String(err?.message ?? err) });
+      }
+      const latest = await c.events.findOne({ externalId, name }, { sort: { createdAt: -1 } });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.event.fire",
+        resource: { collection: "mailer_events", id: latest?._id },
+        diffSummary: `${name} for ${contact.email}${dedupeKey ? ` key=${dedupeKey}` : ""}`
+      });
+      res.status(201).json({ ok: true, event: latest });
+    })
+  );
+  router.get(
+    "/contacts/by-email/:email",
+    wrap2(async (req, res) => {
+      const contact = await mailer.adapter.getByEmail(String(req.params.email).toLowerCase());
+      if (!contact) return res.status(404).json({ error: "contact_not_found", email: req.params.email });
+      res.json(await contactDetail(contact));
+    })
+  );
+  router.get(
+    "/contacts/:externalId",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      res.json(await contactDetail(contact));
+    })
+  );
+  router.get(
+    "/contacts/:externalId/unsubscribe-url",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      res.json({ contact: { externalId: contact.externalId, email: contact.email }, unsubscribeUrl: unsubscribeUrlFor(mailer, contact.email) });
+    })
+  );
+  router.post(
+    "/contacts/:externalId/subscribe",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      await mailer.upsertSubscription({ externalId: contact.externalId, source: "agent" });
+      const sub = await c.subscriptions.findOne({ externalId: contact.externalId });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.contact.subscribe",
+        resource: { collection: "mailer_subscriptions", id: sub?._id },
+        diffSummary: contact.email
+      });
+      res.json({ subscription: sub });
+    })
+  );
+  router.post(
+    "/contacts/:externalId/unsubscribe",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      await mailer.unsubscribe(contact.email, { scope: "marketing", reason: "user_request", source: "agent" });
+      const sub = await c.subscriptions.findOne({ externalId: contact.externalId });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.contact.unsubscribe",
+        resource: { collection: "mailer_subscriptions", id: sub?._id },
+        diffSummary: contact.email
+      });
+      res.json({ subscription: sub });
+    })
+  );
+  router.post(
+    "/contacts/:externalId/reset",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      const b = req.body ?? {};
+      const eventFilter = { externalId: contact.externalId };
+      if (Array.isArray(b.events)) eventFilter.name = { $in: b.events.map(String) };
+      const doRuns = b.runs !== false;
+      const doSends = b.sends !== false;
+      const doEvents = b.events !== false;
+      const doSuppressions = b.suppressions !== false;
+      const doSubscribe = b.subscribe !== false;
+      const removed = { runs: 0, sends: 0, events: 0, suppressions: 0 };
+      if (doRuns) removed.runs = (await c.flowRuns.deleteMany({ externalId: contact.externalId })).deletedCount;
+      if (doSends) removed.sends = (await c.sends.deleteMany({ externalId: contact.externalId })).deletedCount;
+      if (doEvents) removed.events = (await c.events.deleteMany(eventFilter)).deletedCount;
+      if (doSuppressions) removed.suppressions = (await c.suppressions.deleteMany({ email: contact.email })).deletedCount;
+      if (doSubscribe) await mailer.upsertSubscription({ externalId: contact.externalId, source: "agent-reset" });
+      const subscription = await c.subscriptions.findOne({ externalId: contact.externalId });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.contact.reset",
+        resource: { collection: "mailer_subscriptions", id: subscription?._id },
+        diffSummary: `${contact.email}: removed ${removed.runs} run(s), ${removed.sends} send(s), ${removed.events} event(s), ${removed.suppressions} suppression(s)${doSubscribe ? "; resubscribed" : ""}`
+      });
+      res.json({ contact: { externalId: contact.externalId, email: contact.email }, removed, subscription });
+    })
+  );
+  router.post(
+    "/tick",
+    wrap2(async (_req, res) => {
+      const started = Date.now();
+      await runTick(mailer.getRunnerContext());
+      res.json({ ok: true, ms: Date.now() - started });
+    })
+  );
+  router.get(
+    "/webhooks/status",
+    wrap2(async (_req, res) => {
+      const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1e3);
+      const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1e3);
+      const [last, byType24h, total7d, unprocessed] = await Promise.all([
+        c.webhookEvents.findOne({}, { sort: { receivedAt: -1 }, projection: { receivedAt: 1, provider: 1, normalizedType: 1 } }),
+        c.webhookEvents.aggregate([{ $match: { receivedAt: { $gte: dayAgo } } }, { $group: { _id: "$normalizedType", n: { $sum: 1 } } }]).toArray(),
+        c.webhookEvents.countDocuments({ receivedAt: { $gte: weekAgo } }),
+        c.webhookEvents.countDocuments({ processed: false })
+      ]);
+      res.json({
+        providers: Object.keys(mailer.providers),
+        lastReceivedAt: last?.receivedAt ?? null,
+        lastProvider: last?.provider ?? null,
+        last24h: Object.fromEntries(byType24h.map((r) => [r._id, r.n])),
+        last7d: total7d,
+        unprocessed,
+        ingestPath: `${mailer.config.publicUrl}/m/webhooks/<provider>`
+      });
+    })
+  );
+  router.get(
+    "/status",
+    wrap2(async (_req, res) => {
+      const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1e3);
+      const [flows, templates, subscribed, suppressions, activeRuns, sends24h, webhooks24h, lastWebhook, healthDocs, setup] = await Promise.all([
+        c.flows.find({}, { projection: { slug: 1, enabled: 1, version: 1, lastTriggerScanAt: 1, steps: 1, trigger: 1 } }).sort({ slug: 1 }).toArray(),
+        c.templates.find({}, { projection: { slug: 1, kind: 1, publishedAt: 1, "body.html": 1, fromEmail: 1 } }).sort({ slug: 1 }).toArray(),
+        c.subscriptions.countDocuments({ status: "subscribed" }),
+        c.suppressions.estimatedDocumentCount(),
+        c.flowRuns.countDocuments({ status: "active" }),
+        c.sends.aggregate([{ $match: { queuedAt: { $gte: dayAgo } } }, { $group: { _id: "$status", n: { $sum: 1 } } }]).toArray(),
+        c.webhookEvents.countDocuments({ receivedAt: { $gte: dayAgo } }),
+        c.webhookEvents.findOne({}, { sort: { receivedAt: -1 }, projection: { receivedAt: 1 } }),
+        c.health.find({}).limit(500).toArray(),
+        runSetupChecks(mailer)
+      ]);
+      const activeByFlow = await c.flowRuns.aggregate([{ $match: { status: "active" } }, { $group: { _id: "$flowSlug", n: { $sum: 1 } } }]).toArray();
+      const activeMap = new Map(activeByFlow.map((r) => [r._id, r.n]));
+      res.json({
+        version: VERSION,
+        now: /* @__PURE__ */ new Date(),
+        testContactsConfigured: !!isTestContact,
+        setup,
+        health: { status: healthDocs.length ? effectiveOverallStatus(healthDocs) : null, aggregate: healthDocs.find((d) => d._id === HEALTH_AGG_ID) ?? null },
+        flows: flows.map((f) => ({
+          slug: f.slug,
+          enabled: f.enabled,
+          version: f.version,
+          lastTriggerScanAt: f.lastTriggerScanAt ?? null,
+          trigger: f.trigger,
+          liveSteps: Array.isArray(f.steps) ? f.steps.length : 0,
+          gated: Array.isArray(f.steps) && isCanaryGate(f.steps[0]) ? f.steps[0].test.hasTag : null,
+          activeRuns: activeMap.get(f.slug) ?? 0
+        })),
+        templates: templates.map((t) => ({
+          slug: t.slug,
+          kind: t.kind,
+          fromEmail: t.fromEmail,
+          published: !!(t.body && t.body.html),
+          publishedAt: t.publishedAt ?? null
+        })),
+        counts: {
+          subscribed,
+          suppressions,
+          activeRuns,
+          sendsLast24h: Object.fromEntries(sends24h.map((r) => [r._id, r.n])),
+          webhookEventsLast24h: webhooks24h,
+          lastWebhookAt: lastWebhook?.receivedAt ?? null
+        }
+      });
+    })
+  );
+  router.use((req, res) => {
+    res.status(404).json({ error: "not_found", message: `no agent route ${req.method} ${req.path}; GET / lists them` });
+  });
+  router.use((err, req, res, _next) => {
+    if (err instanceof FlowOperationError) {
+      return res.status(err.status).json({ error: err.code, message: err.message });
+    }
+    if (err?.name === "ZodError") {
+      return res.status(400).json({ error: "validation_failed", issues: err.issues });
+    }
+    logger.error?.({ err: String(err?.message ?? err), path: req.path, method: req.method }, "mailery agent: request failed");
+    if (res.headersSent) return;
+    res.status(500).json({ error: "internal", message: String(err?.message ?? err) });
+  });
+  return router;
+  async function contactForRender(req, res) {
+    const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : "";
+    if (contactId) return loadContact(res, contactId);
+    const sample = req.body?.sampleContact;
+    if (sample && typeof sample === "object" && typeof sample.email === "string") {
+      return {
+        externalId: String(sample.externalId ?? "sample-contact"),
+        email: sample.email,
+        tags: Array.isArray(sample.tags) ? sample.tags.map(String) : [],
+        fields: sample.fields && typeof sample.fields === "object" ? sample.fields : {},
+        timezone: typeof sample.timezone === "string" ? sample.timezone : void 0
+      };
+    }
+    res.status(400).json({ error: "validation_failed", message: "contactId (or a sampleContact with an email) is required" });
+    return null;
+  }
+  async function contactDetail(contact) {
+    const [subscription, recentEvents, recentSends, runs, suppressions] = await Promise.all([
+      c.subscriptions.findOne({ externalId: contact.externalId }),
+      c.events.find({ externalId: contact.externalId }).sort({ occurredAt: -1 }).limit(50).toArray(),
+      c.sends.find({ externalId: contact.externalId }).sort({ queuedAt: -1 }).limit(50).toArray(),
+      c.flowRuns.find({ externalId: contact.externalId }).sort({ enteredAt: -1 }).limit(50).toArray(),
+      c.suppressions.find({ email: contact.email }).toArray()
+    ]);
+    return {
+      contact,
+      isTestContact: isTestContact ? isTestContact(contact.email) : null,
+      subscription,
+      suppressions,
+      recentEvents,
+      recentSends: recentSends.map(sendSummary),
+      runs: runs.map(runSummary)
+    };
+  }
+}
+var PLACEHOLDER_RE = /\{\{[^{}]*\}\}|\{\{\{[^{}]*\}\}\}/g;
+var HREF_RE = /href\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+var GMAIL_CLIP_BYTES = 102 * 1024;
+async function verifyTemplate(mailer, tpl, contact, opts = {}) {
+  const checks = [];
+  const push = (id, status, detail) => checks.push(detail === void 0 ? { id, status } : { id, status, detail });
+  const base = {
+    template: { slug: tpl.slug, kind: tpl.kind, name: tpl.name },
+    contact: { externalId: contact.externalId, email: contact.email }
+  };
+  const finish = (rendered2, links2) => ({
+    ok: checks.every((k) => k.status !== "fail"),
+    ...base,
+    checks,
+    links: { total: links2.length, sample: links2.slice(0, 50) },
+    rendered: rendered2 ? opts.includeRendered ? {
+      subject: rendered2.subject,
+      preheader: rendered2.preheader,
+      html: rendered2.html,
+      plainText: rendered2.plainText,
+      fromEmail: rendered2.fromEmail,
+      fromName: rendered2.fromName,
+      replyTo: rendered2.replyTo
+    } : {
+      subject: rendered2.subject,
+      preheader: rendered2.preheader,
+      htmlBytes: Buffer.byteLength(rendered2.html, "utf8"),
+      textLength: rendered2.plainText.trim().length,
+      fromEmail: rendered2.fromEmail
+    } : null
+  });
+  if (!tpl.body?.html && !tpl.body?.mjml) {
+    push("published", "fail", "template has no published body (body.html and body.mjml are empty)");
+    return finish(null, []);
+  }
+  push("published", "pass", { publishedAt: tpl.publishedAt ?? null });
+  let out;
+  try {
+    out = await renderForContact(mailer, tpl, contact, {
+      reason: "test",
+      eventProperties: opts.eventProperties,
+      vars: opts.vars
+    });
+    push("vars_resolved", "pass", { keys: Object.keys(out.resolved) });
+    push("render", "pass");
+  } catch (err) {
+    const message = String(err?.message ?? err);
+    push(message.startsWith("varsAdapter") ? "vars_resolved" : "render", "fail", message);
+    return finish(null, []);
+  }
+  const { rendered, unsubscribeUrl } = out;
+  const leftovers = /* @__PURE__ */ new Set();
+  for (const part of [rendered.subject, rendered.preheader, rendered.html, rendered.plainText]) {
+    for (const m of part.matchAll(PLACEHOLDER_RE)) leftovers.add(m[0]);
+  }
+  push("unresolved_placeholders", leftovers.size ? "fail" : "pass", leftovers.size ? { placeholders: [...leftovers] } : void 0);
+  const referenced = referencedPaths(
+    [tpl.subject, tpl.preheader, tpl.body.html, tpl.body.plainText, tpl.body.mjml ?? ""].join("\n"),
+    Object.keys(mailer.config.handlebarsHelpers ?? {})
+  );
+  const missing = [];
+  const empty = [];
+  for (const path3 of referenced) {
+    const value = lookupPath(out.context, path3);
+    if (value === void 0) {
+      const root = path3.split(".")[0];
+      if (RESERVED_VAR_KEYS.includes(root)) empty.push(path3);
+      else missing.push(path3);
+    } else if (value === null || value === "") {
+      empty.push(path3);
+    }
+  }
+  push("unknown_variables", missing.length ? "fail" : "pass", { referenced: referenced.length, missing });
+  push("empty_variables", empty.length ? "warn" : "pass", { empty });
+  const links = extractLinks(rendered.html);
+  const invalid = links.filter((l) => !/^(https?:\/\/|mailto:|tel:)/i.test(l));
+  push("links_absolute", invalid.length ? "fail" : "pass", { total: links.length, invalid });
+  if (tpl.kind === "marketing") {
+    push("unsubscribe_link", rendered.html.includes(unsubscribeUrl) ? "pass" : "fail", {
+      hint: "a marketing template must reference {{unsubscribeUrl}} in its body"
+    });
+    if (mailer.config.senderAddress) {
+      push("sender_address", rendered.html.includes(mailer.config.senderAddress) ? "pass" : "fail", {
+        hint: "CAN-SPAM: reference {{senderAddress}} in the footer"
+      });
+    }
+  }
+  const text = rendered.plainText.trim();
+  push("plain_text", text.length === 0 ? "fail" : text.length < 40 ? "warn" : "pass", { length: text.length });
+  const subject = rendered.subject.trim();
+  push("subject", subject.length === 0 ? "fail" : subject.length > 78 ? "warn" : "pass", { length: subject.length });
+  if (mailer.config.senderDomains && Object.keys(mailer.config.senderDomains).length > 0) {
+    const v = validateSenderDomain(rendered.fromEmail, tpl.kind, mailer.config.senderDomains);
+    push("from_domain", v.ok ? "pass" : "fail", v.ok ? { fromEmail: rendered.fromEmail } : { fromEmail: rendered.fromEmail, code: v.code, reason: v.reason });
+  }
+  const bytes = Buffer.byteLength(rendered.html, "utf8");
+  push("html_size", bytes > GMAIL_CLIP_BYTES ? "warn" : "pass", { bytes, clipAt: GMAIL_CLIP_BYTES });
+  const lint = lintTemplate(
+    {
+      subject: tpl.subject,
+      preheader: tpl.preheader,
+      mjml: tpl.body.mjml ?? "",
+      editorJson: tpl.body.editorJson ?? void 0,
+      html: tpl.body.html,
+      plainText: tpl.body.plainText,
+      kind: tpl.kind,
+      fromEmail: tpl.fromEmail
+    },
+    { senderDomains: mailer.config.senderDomains, varsJsonSchema: opts.varsSchema ?? null }
+  );
+  push("lint", lint.errors.length ? "fail" : lint.warnings.length ? "warn" : "pass", {
+    errors: lint.errors.map((i) => ({ rule: i.rule, message: i.message })),
+    warnings: lint.warnings.map((i) => i.rule)
+  });
+  return finish(rendered, links);
+}
+async function renderForContact(mailer, tpl, contact, opts) {
+  let resolved;
+  try {
+    resolved = await resolveVars(mailer.config.varsAdapter, contact, {
+      reason: opts.reason,
+      templateSlug: tpl.slug,
+      eventProperties: opts.eventProperties
+    });
+  } catch (err) {
+    throw new Error(`varsAdapter.resolve threw: ${String(err?.message ?? err)}`);
+  }
+  const unsubscribeUrl = unsubscribeUrlFor(mailer, contact.email);
+  const context = {
+    ...resolved,
+    contact,
+    vars: opts.vars ?? {},
+    event: opts.eventProperties ?? {},
+    unsubscribeUrl,
+    senderAddress: mailer.config.senderAddress
+  };
+  const rendered = await renderTemplate(tpl, context, { helpers: mailer.config.handlebarsHelpers });
+  return { rendered, resolved, unsubscribeUrl, context };
+}
+function unsubscribeUrlFor(mailer, email) {
+  const expiresAt = new Date(Date.now() + mailer.config.unsubscribeTokenLifetimeDays * 24 * 60 * 60 * 1e3);
+  const token = signUnsubscribeToken({ email, scope: "marketing", expiresAt }, mailer.config.unsubscribeSecret);
+  return `${mailer.config.publicUrl}/m/unsub/${token}`;
+}
+function extractLinks(html) {
+  const out = [];
+  for (const m of html.matchAll(HREF_RE)) {
+    const href = (m[1] ?? m[2] ?? "").trim();
+    if (!href || href.startsWith("#")) continue;
+    out.push(href);
+  }
+  return out;
+}
+var BUILTIN_HELPERS = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "lt",
+  "gte",
+  "lte",
+  "and",
+  "or",
+  "not",
+  "formatDate",
+  "formatNumber",
+  "formatCurrency",
+  "pluralize",
+  "if",
+  "unless",
+  "each",
+  "with",
+  "else",
+  "lookup",
+  "log",
+  "this",
+  "true",
+  "false",
+  "null",
+  "undefined"
+]);
+var MUSTACHE_RE = /\{\{\{?([^{}]*)\}\}\}?/g;
+var BLOCK_SCOPE_RE = /\{\{#(each|with)\b[\s\S]*?\{\{\/\1\}\}/g;
+var HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+var PATH_RE = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
+function referencedPaths(source, helperNames = []) {
+  const helpers = /* @__PURE__ */ new Set([...BUILTIN_HELPERS, ...helperNames]);
+  const out = /* @__PURE__ */ new Set();
+  const scanned = source.replace(HTML_COMMENT_RE, "").replace(BLOCK_SCOPE_RE, "");
+  for (const m of scanned.matchAll(MUSTACHE_RE)) {
+    let expr = (m[1] ?? "").trim();
+    if (!expr || expr.startsWith("!")) continue;
+    expr = expr.replace(/^[#/^]\s*/, "").replace(/^else\b\s*/, "");
+    for (let tok of expr.split(/[\s()]+/)) {
+      if (!tok) continue;
+      const eq = tok.indexOf("=");
+      if (eq > 0) tok = tok.slice(eq + 1);
+      if (/^['"]/.test(tok) || /^-?\d/.test(tok)) continue;
+      if (tok.startsWith("@") || tok.startsWith("../") || tok.startsWith("this.")) continue;
+      if (helpers.has(tok) || !PATH_RE.test(tok)) continue;
+      out.add(tok);
+    }
+  }
+  return [...out];
+}
+function lookupPath(ctx, path3) {
+  let cur = ctx;
+  for (const part of path3.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function testContactMatcher(spec) {
+  if (!spec) return null;
+  if (spec instanceof RegExp) return (email) => spec.test(email);
+  if (typeof spec === "function") return (email) => !!spec(email);
+  return null;
+}
+function bearerAuth(tokens) {
+  const hashed = tokens.map((t) => ({ hash: crypto2.createHash("sha256").update(t.token).digest(), actor: t.actor }));
+  return (req, res, next) => {
+    const header = String(req.headers.authorization ?? "");
+    const m = /^Bearer\s+(\S+)\s*$/i.exec(header);
+    if (!m) {
+      return res.status(401).json({ error: "unauthorized", message: "send Authorization: Bearer <token>" });
+    }
+    const presented = crypto2.createHash("sha256").update(m[1] ?? "").digest();
+    const match = hashed.find((h) => crypto2.timingSafeEqual(h.hash, presented));
+    if (!match) return res.status(401).json({ error: "unauthorized", message: "unknown token" });
+    req.actor = match.actor;
+    next();
+  };
+}
+async function advanceOnce(runId, ctx, actor, c) {
+  for (let hop = 0; hop < 10; hop += 1) {
+    const run = await c.flowRuns.findOne({ _id: runId });
+    if (!run || run.status !== "active") return false;
+    if (run.nextActionAt && run.nextActionAt.getTime() > Date.now()) {
+      await c.flowRuns.updateOne(
+        { _id: runId, status: "active" },
+        {
+          $set: { nextActionAt: /* @__PURE__ */ new Date(), updatedAt: /* @__PURE__ */ new Date() },
+          $push: {
+            history: {
+              stepIndex: Math.max(0, run.currentStepIndex - 1),
+              action: "wait_completed",
+              at: /* @__PURE__ */ new Date(),
+              details: { forcedBy: actor, scheduledFor: run.nextActionAt }
+            }
+          }
+        }
+      );
+    }
+    const before = (await c.flowRuns.findOne({ _id: runId }))?.history.length ?? 0;
+    await processOneRunStep(runId, ctx);
+    const after = await c.flowRuns.findOne({ _id: runId });
+    if (!after) return false;
+    const last = after.history[after.history.length - 1];
+    const progressed = after.history.length > before;
+    if (progressed && last?.action === "wait_started" && after.status === "active") continue;
+    return after.status === "active" && progressed;
+  }
+  return false;
+}
+var WAIT_TARGETS = /* @__PURE__ */ new Set(["sent", "delivered", "opened", "clicked", "terminal"]);
+function waitTargetReached(send, target) {
+  switch (target) {
+    case "sent":
+      return send.status === "sent" || send.status === "delivered" || !!send.sentAt;
+    case "delivered":
+      return send.status === "delivered" || !!send.deliveredAt;
+    case "opened":
+      return !!send.openedAt;
+    case "clicked":
+      return !!send.firstClickAt;
+    case "terminal":
+      return ["delivered", "bounced", "failed", "suppressed", "cancelled", "complained"].includes(send.status);
+    default:
+      return false;
+  }
+}
+function sendSummary(s) {
+  return {
+    id: String(s._id),
+    templateSlug: s.templateSlug,
+    externalId: s.externalId,
+    email: s.emailAtSend,
+    kind: s.kind,
+    status: s.status,
+    provider: s.provider,
+    providerMessageId: s.providerMessageId,
+    subject: s.subject,
+    errorMessage: s.errorMessage,
+    flowRunId: s.flowRunId ? String(s.flowRunId) : null,
+    queuedAt: s.queuedAt,
+    sentAt: s.sentAt,
+    deliveredAt: s.deliveredAt,
+    openedAt: s.openedAt,
+    firstClickAt: s.firstClickAt,
+    bounceType: s.bounceType
+  };
+}
+function runSummary(r) {
+  return {
+    id: String(r._id),
+    flowSlug: r.flowSlug,
+    flowVersion: r.flowVersion,
+    externalId: r.externalId,
+    email: r.emailAtEntry,
+    status: r.status,
+    currentStepIndex: r.currentStepIndex,
+    currentBranchPath: r.currentBranchPath,
+    nextActionAt: r.nextActionAt,
+    enteredAt: r.enteredAt,
+    exitedAt: r.exitedAt,
+    exitReason: r.exitReason,
+    triggerEvent: r.triggerEvent ?? null,
+    history: r.history
+  };
+}
+function objectOrUndefined(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : void 0;
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function wrap2(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res)).catch(next);
+  };
+}
+var ENDPOINTS = [
+  { method: "GET", path: "/", summary: "This listing, the package version and the actor behind the token." },
+  { method: "*", path: "/api/*", summary: "The full admin JSON API (flows, templates, contacts, sends, health, setup-status, \u2026) with this token as the actor." },
+  { method: "POST", path: "/templates/:slug/verify", summary: "Render the published template as a contact ({contactId} or {sampleContact}) and run named checks: placeholders, links, unsubscribe, sender address, plain text, subject, from domain, size, lint. {includeRendered: true} returns the HTML." },
+  { method: "POST", path: "/templates/verify-all", summary: "Verify every template (or {slugs}) for each of {contactIds}; a matrix of pass/fail." },
+  { method: "POST", path: "/templates/:slug/render", summary: "Render for a contact and return subject, preheader, HTML, plain text, resolved vars and the signed unsubscribe URL." },
+  { method: "POST", path: "/templates/:slug/send", summary: 'A real send through the pipeline to a test contact ({contactId}); dispatched inline unless {dispatch: "queue"}. Returns the sendId.', testContactsOnly: true },
+  { method: "GET", path: "/sends/:id/wait?status=delivered&timeoutMs=30000", summary: "Long-poll a send until it reaches sent | delivered | opened | clicked | terminal, with its webhook events." },
+  { method: "POST", path: "/sends/:id/dispatch", summary: "Dispatch a queued send now (test contacts only).", testContactsOnly: true },
+  { method: "POST", path: "/flows/:slug/simulate", summary: "Dry-run the flow for {contactId} from {at} with {eventProperties}: the path taken, every gate verdict, projected send times, where it ends. Writes nothing." },
+  { method: "POST", path: "/flows/:slug/arm", summary: "Enable the flow for FUTURE events: stamps the trigger watermark ({since} or now) in the same write. Requires {confirm: true}." },
+  { method: "POST", path: "/flows/:slug/disarm", summary: "Disable the flow (pause). In-flight runs continue." },
+  { method: "POST", path: "/flows/:slug/gate", summary: "Publish a canary version whose first step exits anyone without {tag}." },
+  { method: "POST", path: "/flows/:slug/ungate", summary: "Restore the newest ungated version." },
+  { method: "GET", path: "/runs?externalId=&flowSlug=&status=&limit=", summary: "List flow runs." },
+  { method: "GET", path: "/runs/:id", summary: "One run with its history and sends." },
+  { method: "POST", path: "/runs/:id/advance", summary: "Walk a test contact's run forward now, skipping the wait in front of each of {steps} transitions; sends are dispatched inline.", testContactsOnly: true },
+  { method: "POST", path: "/runs/:id/cancel", summary: "Exit an active run and cancel its queued sends." },
+  { method: "POST", path: "/events", summary: "Fire {name} for a test contact {externalId} with {properties} and optional {dedupeKey}.", testContactsOnly: true },
+  { method: "GET", path: "/contacts/:externalId", summary: "Contact with subscription, suppressions, recent events, sends and runs." },
+  { method: "GET", path: "/contacts/by-email/:email", summary: "Same, looked up by email." },
+  { method: "GET", path: "/contacts/:externalId/unsubscribe-url", summary: "A signed one-click unsubscribe URL for a test contact, to exercise POST /m/unsub/:token.", testContactsOnly: true },
+  { method: "POST", path: "/contacts/:externalId/subscribe", summary: "Subscribe a test contact.", testContactsOnly: true },
+  { method: "POST", path: "/contacts/:externalId/unsubscribe", summary: "Unsubscribe a test contact (marketing scope).", testContactsOnly: true },
+  { method: "POST", path: "/contacts/:externalId/reset", summary: "Delete a test contact's runs, sends, events ({events: [names]} to narrow) and suppressions, then resubscribe. Each part can be turned off with false.", testContactsOnly: true },
+  { method: "POST", path: "/tick", summary: "Run the runner tick now (trigger scan, sweeps, outbox, webhook backlog)." },
+  { method: "GET", path: "/webhooks/status", summary: "Provider webhook ingest: last event received, counts by type (24h), unprocessed backlog." },
+  { method: "GET", path: "/status", summary: "One document with setup checks, health, every flow (enabled, version, watermark, gate, active runs), every template, and 24h counts." }
+];
 var ALLOWED_EXTENSIONS = [".zip", ".gz", ".xml"];
 var DEFAULT_PATH = "/inbound/dmarc";
 var DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
@@ -8559,8 +9938,8 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION = "0.15.0" ;
+var VERSION2 = "0.16.1" ;
 
-export { DEDUPE_POLICIES, DEFAULT_BOT_UA_RE, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, RESERVED_VAR_KEYS, SEGMENT_FILTER_KINDS, SendGridProvider, TRACKING_SIG_LENGTH, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, defineVars, derivePlaintext, dispatchSend, drainPendingUnsubscribes, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sendgridInboundParser, sha256Hex, signTrackingToken, signUnsubscribeToken, sweepStrandedFlowRuns, validateSenderDomain, varsJsonSchema, verifyTrackingToken, verifyUnsubscribeToken };
+export { DEDUPE_POLICIES, DEFAULT_BOT_UA_RE, FLOW_STEP_KINDS, FlowOperationError, MIN_AGENT_TOKEN_LENGTH, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, RESERVED_VAR_KEYS, SEGMENT_FILTER_KINDS, SendGridProvider, TRACKING_SIG_LENGTH, VERSION2 as VERSION, applyTracking, applyWebhookEvent, armFlow, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminApiRouter, createAdminRouter, createAgentRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, defineVars, derivePlaintext, disarmFlow, dispatchSend, drainPendingUnsubscribes, ensureIndexes, gateFlow, getCollections, isCanaryGate, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, referencedPaths, renderForContact, renderTemplate, runTick, sendgridInboundParser, sha256Hex, signTrackingToken, signUnsubscribeToken, simulateFlow, stampWatermarkIfNull, sweepStrandedFlowRuns, ungateFlow, validateSenderDomain, varsJsonSchema, verifyTemplate, verifyTrackingToken, verifyUnsubscribeToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map