mailery 0.15.0 → 0.16.1

package/dist/index.cjs

@@ -286,8 +286,36 @@ var init_webhook_tolerance = __esm({
 // src/server/providers/sendgrid.ts
 var sendgrid_exports = {};
 __export(sendgrid_exports, {
-  SendGridProvider: () => exports.SendGridProvider
+  SendGridProvider: () => exports.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__default.default.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;
@@ -326,24 +354,29 @@ function mapEventType(sgEvent) {
       return null;
   }
 }
-var SG_SIG_HEADER, SG_TS_HEADER; exports.SendGridProvider = void 0;
+var SG_SIG_HEADER, SG_TS_HEADER, PEM_HEADER, PEM_FOOTER; exports.SendGridProvider = void 0;
 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-----";
     exports.SendGridProvider = class {
       constructor(opts) {
         this.opts = opts;
         sgMail__default.default.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,
@@ -375,7 +408,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;
@@ -383,7 +416,7 @@ var init_sendgrid = __esm({
         try {
           const verifier = crypto2__default.default.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;
         }
@@ -6180,13 +6213,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__default.default.join(spaDir, "index.html"));
   });
   return router;
 }
-function apiRouter(mailer, opts = {}) {
+function createAdminApiRouter(mailer, opts = {}) {
   const r = express.Router();
   const c = mailer.collections;
   const varsSchema = mailer.config.varsAdapter ? varsJsonSchema(mailer.config.varsAdapter) : null;
@@ -6383,7 +6416,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",
@@ -6964,6 +7001,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({
@@ -6980,11 +7018,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 } : {}
           }
         }
       );
@@ -6992,9 +7033,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(
@@ -7865,7 +7906,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 mongodb.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 = express.Router();
+  router.use(express__default.default.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__default.default.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 mongodb.ObjectId(sendId), mailer.getRunnerContext());
+      }
+      const send = await c.sends.findOne({ _id: new mongodb.ObjectId(sendId) });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.send",
+        resource: { collection: "mailer_sends", id: new mongodb.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 (!mongodb.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 mongodb.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 (!mongodb.ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const send = await c.sends.findOne({ _id: new mongodb.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 (!mongodb.ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new mongodb.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 (!mongodb.ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new mongodb.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 (!mongodb.ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new mongodb.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 (exports.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__default.default.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__default.default.createHash("sha256").update(m[1] ?? "").digest();
+    const match = hashed.find((h) => crypto2__default.default.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;
@@ -8577,45 +9956,59 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION = "0.15.0" ;
+var VERSION2 = "0.16.1" ;
 
 exports.DEDUPE_POLICIES = DEDUPE_POLICIES;
 exports.DEFAULT_BOT_UA_RE = DEFAULT_BOT_UA_RE;
 exports.FLOW_STEP_KINDS = FLOW_STEP_KINDS;
+exports.FlowOperationError = FlowOperationError;
+exports.MIN_AGENT_TOKEN_LENGTH = MIN_AGENT_TOKEN_LENGTH;
 exports.Mailer = Mailer;
 exports.NullProvider = NullProvider;
 exports.PREDICATE_KINDS = PREDICATE_KINDS;
 exports.SEGMENT_FILTER_KINDS = SEGMENT_FILTER_KINDS;
 exports.TRACKING_SIG_LENGTH = TRACKING_SIG_LENGTH;
-exports.VERSION = VERSION;
+exports.VERSION = VERSION2;
 exports.applyTracking = applyTracking;
 exports.applyWebhookEvent = applyWebhookEvent;
+exports.armFlow = armFlow;
 exports.compileMailyTemplate = compileMailyTemplate;
 exports.compileTemplate = compileTemplate;
 exports.computeDeliveryTime = computeDeliveryTime;
+exports.createAdminApiRouter = createAdminApiRouter;
 exports.createAdminRouter = createAdminRouter;
+exports.createAgentRouter = createAgentRouter;
 exports.createPublicRouter = createPublicRouter;
 exports.defaultFlowStep = defaultFlowStep;
 exports.defaultPredicate = defaultPredicate;
 exports.defaultSegmentFilter = defaultSegmentFilter;
 exports.defineVars = defineVars;
 exports.derivePlaintext = derivePlaintext;
+exports.disarmFlow = disarmFlow;
 exports.dispatchSend = dispatchSend;
 exports.drainPendingUnsubscribes = drainPendingUnsubscribes;
 exports.ensureIndexes = ensureIndexes;
+exports.gateFlow = gateFlow;
 exports.getCollections = getCollections;
+exports.isCanaryGate = isCanaryGate;
 exports.predicateKind = predicateKind;
 exports.processNewlyFiredEventTriggers = processNewlyFiredEventTriggers;
 exports.processOneRunStep = processOneRunStep;
+exports.referencedPaths = referencedPaths;
+exports.renderForContact = renderForContact;
 exports.renderTemplate = renderTemplate;
 exports.runTick = runTick;
 exports.sendgridInboundParser = sendgridInboundParser;
 exports.sha256Hex = sha256Hex;
 exports.signTrackingToken = signTrackingToken;
 exports.signUnsubscribeToken = signUnsubscribeToken;
+exports.simulateFlow = simulateFlow;
+exports.stampWatermarkIfNull = stampWatermarkIfNull;
 exports.sweepStrandedFlowRuns = sweepStrandedFlowRuns;
+exports.ungateFlow = ungateFlow;
 exports.validateSenderDomain = validateSenderDomain;
 exports.varsJsonSchema = varsJsonSchema;
+exports.verifyTemplate = verifyTemplate;
 exports.verifyTrackingToken = verifyTrackingToken;
 exports.verifyUnsubscribeToken = verifyUnsubscribeToken;
 //# sourceMappingURL=index.cjs.map