mailery 0.5.1 → 0.8.0

package/dist/testing.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
+var zod = require('zod');
 var mongodb = require('mongodb');
 var crypto2 = require('crypto');
 var sgMail = require('@sendgrid/mail');
-var zod = require('zod');
 var IORedis = require('ioredis');
 var Handlebars = require('handlebars');
 var htmlToText = require('html-to-text');
@@ -63,6 +63,55 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/server/adapters/vars.ts
+var vars_exports = {};
+__export(vars_exports, {
+  RESERVED_VAR_KEYS: () => RESERVED_VAR_KEYS,
+  assertNoReservedVarKeys: () => assertNoReservedVarKeys,
+  defineVars: () => defineVars,
+  resolveVars: () => resolveVars,
+  varsJsonSchema: () => varsJsonSchema
+});
+function defineVars(adapter) {
+  return adapter;
+}
+function assertNoReservedVarKeys(adapter) {
+  const json = varsJsonSchema(adapter);
+  const props = json && typeof json === "object" ? json.properties : void 0;
+  if (!props) return;
+  const clashes = RESERVED_VAR_KEYS.filter((k) => k in props);
+  if (clashes.length > 0) {
+    throw new Error(
+      `varsAdapter schema declares reserved key(s): ${clashes.join(", ")}. These names are provided by mailery itself \u2014 rename them in your schema.`
+    );
+  }
+}
+function varsJsonSchema(adapter) {
+  return zod.z.toJSONSchema(adapter.schema, { io: "output" });
+}
+async function resolveVars(adapter, contact, info) {
+  if (!adapter) return {};
+  const resolved = await adapter.resolve(contact, info);
+  if (!resolved || typeof resolved !== "object") return {};
+  const out = { ...resolved };
+  for (const k of RESERVED_VAR_KEYS) delete out[k];
+  return out;
+}
+var RESERVED_VAR_KEYS;
+var init_vars = __esm({
+  "src/server/adapters/vars.ts"() {
+    RESERVED_VAR_KEYS = [
+      "contact",
+      "vars",
+      "event",
+      "unsubscribeUrl",
+      "viewInBrowserUrl",
+      "preferenceCenterUrl",
+      "senderAddress"
+    ];
+  }
+});
+
 // src/server/adapters/mongo.ts
 var mongo_exports = {};
 __export(mongo_exports, {
@@ -455,22 +504,22 @@ function __awaiter(thisArg, _arguments, P, generator) {
   return new (P || (P = Promise))(function(resolve, reject) {
     function fulfilled(value) {
       try {
-        step(generator.next(value));
+        step2(generator.next(value));
       } catch (e) {
         reject(e);
       }
     }
     function rejected(value) {
       try {
-        step(generator["throw"](value));
+        step2(generator["throw"](value));
       } catch (e) {
         reject(e);
       }
     }
-    function step(result) {
+    function step2(result) {
       result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
-    step((generator = generator.apply(thisArg, _arguments || [])).next());
+    step2((generator = generator.apply(thisArg, _arguments || [])).next());
   });
 }
 function __generator(thisArg, body) {
@@ -483,10 +532,10 @@ function __generator(thisArg, body) {
   }), g;
   function verb(n) {
     return function(v) {
-      return step([n, v]);
+      return step2([n, v]);
     };
   }
-  function step(op) {
+  function step2(op) {
     if (f) throw new TypeError("Generator is already executing.");
     while (g && (g = 0, op[0] && (_ = 0)), _) try {
       if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
@@ -620,12 +669,12 @@ function __asyncGenerator(thisArg, _arguments, generator) {
   }
   function resume(n, v) {
     try {
-      step(g[n](v));
+      step2(g[n](v));
     } catch (e) {
       settle(q[0][3], e);
     }
   }
-  function step(r) {
+  function step2(r) {
     r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r);
   }
   function fulfill(value) {
@@ -3005,19 +3054,19 @@ var require_range = __commonJS({
     var replaceCaret = (comp, options2) => {
       debug("caret", comp, options2);
       const r = options2.loose ? re[t.CARETLOOSE] : re[t.CARET];
-      const z2 = options2.includePrerelease ? "-0" : "";
+      const z3 = options2.includePrerelease ? "-0" : "";
       return comp.replace(r, (_, M, m, p, pr) => {
         debug("caret", comp, _, M, m, p, pr);
         let ret;
         if (isX(M)) {
           ret = "";
         } else if (isX(m)) {
-          ret = `>=${M}.0.0${z2} <${+M + 1}.0.0-0`;
+          ret = `>=${M}.0.0${z3} <${+M + 1}.0.0-0`;
         } else if (isX(p)) {
           if (M === "0") {
-            ret = `>=${M}.${m}.0${z2} <${M}.${+m + 1}.0-0`;
+            ret = `>=${M}.${m}.0${z3} <${M}.${+m + 1}.0-0`;
           } else {
-            ret = `>=${M}.${m}.0${z2} <${+M + 1}.0.0-0`;
+            ret = `>=${M}.${m}.0${z3} <${+M + 1}.0.0-0`;
           }
         } else if (pr) {
           debug("replaceCaret pr", pr);
@@ -3034,9 +3083,9 @@ var require_range = __commonJS({
           debug("no pr");
           if (M === "0") {
             if (m === "0") {
-              ret = `>=${M}.${m}.${p}${z2} <${M}.${m}.${+p + 1}-0`;
+              ret = `>=${M}.${m}.${p}${z3} <${M}.${m}.${+p + 1}-0`;
             } else {
-              ret = `>=${M}.${m}.${p}${z2} <${M}.${+m + 1}.0-0`;
+              ret = `>=${M}.${m}.${p}${z3} <${M}.${+m + 1}.0-0`;
             }
           } else {
             ret = `>=${M}.${m}.${p} <${+M + 1}.0.0-0`;
@@ -7043,9 +7092,9 @@ var require_pack = __commonJS({
         this.push(headers.encode(newHeader));
       }
       _doDrain() {
-        const drain = this._drain;
+        const drain2 = this._drain;
         this._drain = noop;
-        drain();
+        drain2();
       }
       _predestroy() {
         const err = getStreamError(this);
@@ -14156,6 +14205,12 @@ var tagInputSchema = zod.z.object({
   externalId: externalIdSchema,
   tag: zod.z.string().min(1).max(128)
 });
+var abortFlowInputSchema = zod.z.object({
+  flowSlug: slugSchema,
+  externalId: externalIdSchema,
+  reason: zod.z.string().min(1).max(200).optional()
+});
+var abortAllFlowsInputSchema = abortFlowInputSchema.omit({ flowSlug: true });
 var sendOneOffInputSchema = zod.z.object({
   templateSlug: slugSchema,
   externalId: externalIdSchema,
@@ -14185,7 +14240,13 @@ var flowStepSchema = zod.z.lazy(
       type: zod.z.literal("send"),
       templateSlug: slugSchema,
       providerOverride: zod.z.string().optional(),
-      vars: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+      vars: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+      delivery: zod.z.object({
+        weekdaysOnly: zod.z.boolean().optional(),
+        timeOfDay: zod.z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:mm").optional(),
+        useContactTimezone: zod.z.boolean().optional(),
+        timezone: zod.z.string().optional()
+      }).optional()
     }),
     zod.z.object({
       type: zod.z.literal("tag"),
@@ -14920,6 +14981,7 @@ async function tryEnterFlow(flow, event, ctx) {
     flowSlug: flow.slug,
     flowVersion: flow.version,
     emailAtEntry: sub.emailAtSubscribe,
+    triggerEvent: { name: event.name, properties: event.properties ?? {}, occurredAt: event.occurredAt },
     enteredAt: /* @__PURE__ */ new Date(),
     status: "active",
     currentStepIndex: 0,
@@ -15017,6 +15079,105 @@ function effectiveLowerBound(ctx, opts) {
   }
   return null;
 }
+
+// src/server/runner/delivery-window.ts
+var TIME_OF_DAY_GRACE_MS = 60 * 6e4;
+function computeDeliveryTime(now, window2, contactTimezone) {
+  const tz = pickTimezone(window2, contactTimezone);
+  let candidate = now;
+  if (window2.timeOfDay) {
+    const [hh, mm] = window2.timeOfDay.split(":").map(Number);
+    const local = localParts(candidate, tz);
+    const todaySlot = utcFromLocal(local.y, local.mo, local.d, hh, mm, tz);
+    if (candidate.getTime() < todaySlot.getTime()) {
+      candidate = todaySlot;
+    } else if (candidate.getTime() - todaySlot.getTime() > TIME_OF_DAY_GRACE_MS) {
+      const next = addLocalDays(local, 1);
+      candidate = utcFromLocal(next.y, next.mo, next.d, hh, mm, tz);
+    }
+  }
+  if (window2.weekdaysOnly) {
+    for (let guard = 0; guard < 3; guard++) {
+      const local = localParts(candidate, tz);
+      if (local.weekday !== "Sat" && local.weekday !== "Sun") break;
+      const shift = local.weekday === "Sat" ? 2 : 1;
+      const moved = addLocalDays(local, shift);
+      candidate = utcFromLocal(moved.y, moved.mo, moved.d, local.hh, local.mi, tz);
+    }
+  }
+  return candidate;
+}
+function pickTimezone(window2, contactTimezone) {
+  const candidates = [
+    window2.useContactTimezone ? contactTimezone : void 0,
+    window2.timezone,
+    "UTC"
+  ];
+  for (const tz of candidates) {
+    if (tz && isValidTimezone(tz)) return tz;
+  }
+  return "UTC";
+}
+var validatedZones = /* @__PURE__ */ new Map();
+function isValidTimezone(tz) {
+  const cached = validatedZones.get(tz);
+  if (cached !== void 0) return cached;
+  let ok = true;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+  } catch {
+    ok = false;
+  }
+  validatedZones.set(tz, ok);
+  return ok;
+}
+var partFormatters = /* @__PURE__ */ new Map();
+function formatterFor(tz) {
+  let f = partFormatters.get(tz);
+  if (!f) {
+    f = new Intl.DateTimeFormat("en-US", {
+      timeZone: tz,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      weekday: "short",
+      hour12: false
+    });
+    partFormatters.set(tz, f);
+  }
+  return f;
+}
+function localParts(date, tz) {
+  const parts = {};
+  for (const p of formatterFor(tz).formatToParts(date)) parts[p.type] = p.value;
+  return {
+    y: Number(parts.year),
+    mo: Number(parts.month),
+    d: Number(parts.day),
+    hh: Number(parts.hour) % 24,
+    // Intl emits '24' for midnight in some locales
+    mi: Number(parts.minute),
+    ss: Number(parts.second),
+    weekday: parts.weekday
+  };
+}
+function utcFromLocal(y, mo, d, hh, mi, tz) {
+  let ts = Date.UTC(y, mo - 1, d, hh, mi, 0);
+  for (let i = 0; i < 2; i++) {
+    const p = localParts(new Date(ts), tz);
+    const asUtc = Date.UTC(p.y, p.mo - 1, p.d, p.hh, p.mi, p.ss);
+    const offset = asUtc - ts;
+    ts = Date.UTC(y, mo - 1, d, hh, mi, 0) - offset;
+  }
+  return new Date(ts);
+}
+function addLocalDays(p, days) {
+  const dt = new Date(Date.UTC(p.y, p.mo - 1, p.d + days));
+  return { y: dt.getUTCFullYear(), mo: dt.getUTCMonth() + 1, d: dt.getUTCDate() };
+}
 async function compileTemplate(mjml) {
   const out = await mjml2html__default.default(mjml, { validationLevel: "soft", minify: false });
   const plainText = derivePlaintext(out.html);
@@ -15134,6 +15295,9 @@ function makeHandlebars(extra) {
   return hb;
 }
 
+// src/server/runner/send.ts
+init_vars();
+
 // src/server/runner/suppression.ts
 var SCOPES_BY_KIND = {
   marketing: ["all", "marketing"],
@@ -15321,10 +15485,10 @@ async function getBucketStatus(ctx, fromEmail, kind) {
 }
 
 // src/server/runner/send.ts
-async function handleSend(run, step, contact, flow, ctx) {
-  const template = await ctx.collections.templates.findOne({ slug: step.templateSlug });
+async function handleSend(run, step2, contact, flow, ctx) {
+  const template = await ctx.collections.templates.findOne({ slug: step2.templateSlug });
   if (!template) {
-    await failFlowRun(run, `template not found: ${step.templateSlug}`, ctx);
+    await failFlowRun(run, `template not found: ${step2.templateSlug}`, ctx);
     return;
   }
   const dedupeKey = `flowrun:${run._id}:step${run.currentStepIndex}`;
@@ -15336,8 +15500,8 @@ async function handleSend(run, step, contact, flow, ctx) {
     });
     return;
   }
-  const providerName = pickProviderName(step.providerOverride, template, ctx);
-  const renderCtx = buildRenderContext(contact, run, step.vars ?? {}, ctx);
+  const providerName = pickProviderName(step2.providerOverride, template, ctx);
+  const renderCtx = buildRenderContext(contact, run, step2.vars ?? {}, ctx);
   let rendered;
   try {
     rendered = await renderTemplate(template, renderCtx, { helpers: ctx.handlebarsHelpers });
@@ -15374,7 +15538,7 @@ async function handleSend(run, step, contact, flow, ctx) {
       bodyHash: sha256(rendered.html),
       status: "queued",
       renderedFrom: rendered.fromName ? { name: rendered.fromName, email: rendered.fromEmail } : void 0,
-      vars: step.vars ?? {}
+      vars: step2.vars ?? {}
     })
   );
   await ctx.queues.send.add(
@@ -15414,13 +15578,29 @@ async function dispatchSend(sendId, ctx) {
     return;
   }
   const run = send.flowRunId ? await ctx.collections.flowRuns.findOne({ _id: send.flowRunId }) : null;
-  const renderCtx = buildRenderContext(
-    contact,
-    run,
-    send.vars ?? {},
-    ctx
-  );
-  const rendered = await renderTemplate(template, renderCtx, { helpers: ctx.handlebarsHelpers });
+  if (run && run.status === "exited" && run.exitReason?.startsWith("aborted_by_host")) {
+    await ctx.collections.sends.updateOne(
+      { _id: send._id },
+      { $set: { status: "cancelled", errorMessage: `cancelled: ${run.exitReason}`, updatedAt: /* @__PURE__ */ new Date() } }
+    );
+    return;
+  }
+  let renderCtx;
+  let rendered;
+  try {
+    const resolved = await resolveVars(ctx.varsAdapter, contact, {
+      reason: "send",
+      templateSlug: template.slug,
+      flowSlug: run?.flowSlug,
+      eventName: run?.triggerEvent?.name,
+      eventProperties: run?.triggerEvent?.properties
+    });
+    renderCtx = buildRenderContext(contact, run, send.vars ?? {}, ctx, resolved);
+    rendered = await renderTemplate(template, renderCtx, { helpers: ctx.handlebarsHelpers });
+  } catch (err) {
+    await markFailed(send._id, `render error: ${String(err?.message ?? err)}`, ctx);
+    throw err;
+  }
   const tracking = applyTracking(rendered.html, {
     sendId: String(send._id),
     publicUrl: ctx.config.publicUrl,
@@ -15447,6 +15627,10 @@ async function dispatchSend(sendId, ctx) {
     await markFailed(send._id, `provider_unknown: ${send.provider}`, ctx);
     return;
   }
+  const headers = send.kind === "marketing" ? {
+    "List-Unsubscribe": `<${renderCtx.unsubscribeUrl}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  } : {};
   try {
     const result = await provider.send({
       to: send.emailAtSend,
@@ -15456,10 +15640,7 @@ async function dispatchSend(sendId, ctx) {
       subject: rendered.subject,
       html: tracking.html,
       text: rendered.plainText,
-      headers: {
-        "List-Unsubscribe": `<${renderCtx.unsubscribeUrl}>`,
-        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
-      },
+      headers,
       messageMeta: { sendId: String(send._id) }
     });
     await ctx.collections.sends.updateOne(
@@ -15496,7 +15677,7 @@ function pickProviderName(stepOverride, tpl, ctx) {
   }
   return ctx.config.defaultProvider;
 }
-function buildRenderContext(contact, run, vars, ctx) {
+function buildRenderContext(contact, run, vars, ctx, resolved = {}) {
   const scope = "marketing";
   const expiresAt = new Date(Date.now() + ctx.config.unsubscribeTokenLifetimeDays * 24 * 60 * 60 * 1e3);
   const token = signUnsubscribeToken(
@@ -15505,8 +15686,10 @@ function buildRenderContext(contact, run, vars, ctx) {
   );
   const unsubscribeUrl = `${ctx.config.publicUrl}/m/unsub/${token}`;
   return {
+    ...resolved,
     contact,
     vars,
+    event: run?.triggerEvent?.properties ?? {},
     unsubscribeUrl,
     senderAddress: ctx.config.senderAddress
   };
@@ -15569,8 +15752,8 @@ async function processOneRunStep(runId, ctx) {
     return;
   }
   const steps = await loadStepsForRun(run, flow, ctx);
-  const step = locateStep(steps, run.currentStepIndex, run.currentBranchPath);
-  if (!step) {
+  const step2 = locateStep(steps, run.currentStepIndex, run.currentBranchPath);
+  if (!step2) {
     await completeFlowRun(run, "completed", ctx);
     return;
   }
@@ -15584,27 +15767,34 @@ async function processOneRunStep(runId, ctx) {
     await exitFlowRun(run, sub.status, ctx);
     return;
   }
-  switch (step.type) {
+  switch (step2.type) {
     case "wait":
-      return handleWait(run, step, ctx);
+      return handleWait(run, step2, ctx);
     case "condition":
-      return handleCondition(run, step, contact, ctx);
+      return handleCondition(run, step2, contact, ctx);
     case "branch":
-      return handleBranch(run, step, contact, ctx);
-    case "send":
-      return handleSend(run, step, contact, flow, ctx);
+      return handleBranch(run, step2, contact, ctx);
+    case "send": {
+      if (step2.delivery) {
+        const deliverAt = computeDeliveryTime(/* @__PURE__ */ new Date(), step2.delivery, contact.timezone);
+        if (deliverAt.getTime() > Date.now() + 3e4) {
+          return deferSendForWindow(run, deliverAt, ctx);
+        }
+      }
+      return handleSend(run, step2, contact, flow, ctx);
+    }
     case "tag":
-      return handleTag(run, step, ctx);
+      return handleTag(run, step2, ctx);
     case "fire_event":
-      return handleFireEvent(run, step, ctx);
+      return handleFireEvent(run, step2, ctx);
     case "webhook":
-      return handleWebhookStep(run, step, ctx);
+      return handleWebhookStep(run, step2, ctx);
     case "exit":
-      return exitFlowRun(run, step.reason ?? "exit_step", ctx);
+      return exitFlowRun(run, step2.reason ?? "exit_step", ctx);
   }
 }
-async function handleWait(run, step, ctx) {
-  const ms = unitToMs(step.value, step.unit);
+async function handleWait(run, step2, ctx) {
+  const ms = unitToMs(step2.value, step2.unit);
   const nextAt = new Date(Date.now() + ms);
   const updated = await ctx.collections.flowRuns.findOneAndUpdate(
     { _id: run._id, currentStepIndex: run.currentStepIndex },
@@ -15629,22 +15819,22 @@ async function handleWait(run, step, ctx) {
     { delay: ms, jobId: `advance:${run._id}:${run.currentStepIndex + 1}` }
   );
 }
-async function handleCondition(run, step, contact, ctx) {
+async function handleCondition(run, step2, contact, ctx) {
   if (!contact) return;
-  const result = await evaluatePredicate(step.test, { contact, run, collections: ctx.collections });
+  const result = await evaluatePredicate(step2.test, { contact, run, collections: ctx.collections });
   if (result) {
     await advanceStep(run, ctx, { action: "condition_evaluated", details: { result: true } });
     return;
   }
-  if (step.ifFalse === "continue") {
+  if (step2.ifFalse === "continue") {
     await advanceStep(run, ctx, { action: "condition_evaluated", details: { result: false, skipped: 1 } }, { stepInc: 2 });
     return;
   }
   await exitFlowRun(run, "condition_false", ctx);
 }
-async function handleBranch(run, step, contact, ctx) {
+async function handleBranch(run, step2, contact, ctx) {
   if (!contact) return;
-  const result = await evaluatePredicate(step.test, { contact, run, collections: ctx.collections });
+  const result = await evaluatePredicate(step2.test, { contact, run, collections: ctx.collections });
   const newPath = [...run.currentBranchPath, run.currentStepIndex, result ? "true" : "false", 0];
   const updated = await ctx.collections.flowRuns.findOneAndUpdate(
     { _id: run._id, currentStepIndex: run.currentStepIndex },
@@ -15670,9 +15860,9 @@ async function handleBranch(run, step, contact, ctx) {
   if (!updated) return;
   await ctx.queues.advance.add("advance", { flowRunId: String(run._id) });
 }
-async function handleTag(run, step, ctx) {
-  const adds = step.addTags ?? [];
-  const removes = step.removeTags ?? [];
+async function handleTag(run, step2, ctx) {
+  const adds = step2.addTags ?? [];
+  const removes = step2.removeTags ?? [];
   if (ctx.adapter.addTags && adds.length > 0) {
     await ctx.adapter.addTags(run.externalId, adds);
   } else if (adds.length > 0) {
@@ -15693,13 +15883,13 @@ async function handleTag(run, step, ctx) {
   }
   await advanceStep(run, ctx, { action: "tagged", details: { addTags: adds, removeTags: removes } });
 }
-async function handleFireEvent(run, step, ctx) {
-  const dedupeKey = `flowrun:${run._id}:step${run.currentStepIndex}:${step.eventName}`;
+async function handleFireEvent(run, step2, ctx) {
+  const dedupeKey = `flowrun:${run._id}:step${run.currentStepIndex}:${step2.eventName}`;
   try {
     await ctx.collections.events.insertOne({
       externalId: run.externalId,
-      name: step.eventName,
-      properties: step.properties ?? {},
+      name: step2.eventName,
+      properties: step2.properties ?? {},
       dedupeKey,
       occurredAt: /* @__PURE__ */ new Date(),
       createdAt: /* @__PURE__ */ new Date()
@@ -15707,27 +15897,27 @@ async function handleFireEvent(run, step, ctx) {
   } catch (err) {
     if (err?.code !== 11e3) throw err;
   }
-  await advanceStep(run, ctx, { action: "event_fired", details: { name: step.eventName } });
+  await advanceStep(run, ctx, { action: "event_fired", details: { name: step2.eventName } });
 }
-async function handleWebhookStep(run, step, ctx) {
+async function handleWebhookStep(run, step2, ctx) {
   try {
-    const res = await fetch(step.url, {
-      method: step.method ?? "POST",
+    const res = await fetch(step2.url, {
+      method: step2.method ?? "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(step.payload ?? { externalId: run.externalId, flowRunId: String(run._id) }),
+      body: JSON.stringify(step2.payload ?? { externalId: run.externalId, flowRunId: String(run._id) }),
       signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) throw new Error(`webhook step returned ${res.status}`);
-    await advanceStep(run, ctx, { action: "webhook_called", details: { url: step.url, status: res.status } });
+    await advanceStep(run, ctx, { action: "webhook_called", details: { url: step2.url, status: res.status } });
   } catch (err) {
     const attempts = (run.attemptsForCurrentStep ?? 0) + 1;
     if (attempts >= ctx.config.webhookRetryAttempts) {
-      if (step.failureMode === "fail_run") {
+      if (step2.failureMode === "fail_run") {
         await failFlowRun(run, `webhook failed: ${err?.message}`, ctx);
       } else {
         await advanceStep(run, ctx, {
           action: "webhook_called",
-          details: { url: step.url, error: err?.message, exhausted: true }
+          details: { url: step2.url, error: err?.message, exhausted: true }
         });
       }
     } else {
@@ -15743,6 +15933,34 @@ async function handleWebhookStep(run, step, ctx) {
     }
   }
 }
+async function deferSendForWindow(run, deliverAt, ctx) {
+  const updated = await ctx.collections.flowRuns.findOneAndUpdate(
+    // Only write once per deferral — if nextActionAt already points at (or
+    // past) the slot, another worker/tick got here first.
+    { _id: run._id, currentStepIndex: run.currentStepIndex, nextActionAt: { $lt: deliverAt } },
+    {
+      $set: { nextActionAt: deliverAt, updatedAt: /* @__PURE__ */ new Date() },
+      $push: {
+        history: {
+          stepIndex: run.currentStepIndex,
+          action: "send_deferred",
+          at: /* @__PURE__ */ new Date(),
+          details: { until: deliverAt }
+        }
+      }
+    },
+    { returnDocument: "after" }
+  );
+  if (!updated) return;
+  await ctx.queues.advance.add(
+    "advance",
+    { flowRunId: String(run._id) },
+    {
+      delay: Math.max(0, deliverAt.getTime() - Date.now()),
+      jobId: `advance:${run._id}:${run.currentStepIndex}:window:${deliverAt.getTime()}`
+    }
+  );
+}
 async function advanceStep(run, ctx, log, opts = {}) {
   const stepInc = opts.stepInc ?? 1;
   const updated = await ctx.collections.flowRuns.findOneAndUpdate(
@@ -16995,6 +17213,7 @@ var Mailer = class _Mailer {
       db: this.db,
       collections: this.collections,
       adapter: this.adapter,
+      varsAdapter: this.config.varsAdapter,
       providers: this.providers,
       queues: this.queues,
       config: this.config,
@@ -17074,6 +17293,10 @@ var Mailer = class _Mailer {
     if (!config.providers[config.defaultProvider]) {
       throw new Error(`defaultProvider "${config.defaultProvider}" not in providers map`);
     }
+    if (config.varsAdapter) {
+      const { assertNoReservedVarKeys: assertNoReservedVarKeys2 } = await Promise.resolve().then(() => (init_vars(), vars_exports));
+      assertNoReservedVarKeys2(config.varsAdapter);
+    }
     const collections = getCollections(config.db, config.collectionPrefix);
     await ensureIndexes(config.db, config.collectionPrefix);
     const queueDriver = await createQueueDriver(config.queue, config.db);
@@ -17289,6 +17512,72 @@ var Mailer = class _Mailer {
       await this.collections.contactTags.deleteOne({ externalId: parsed.externalId, tag: parsed.tag });
     }
   }
+  // -------------------------------------------------------------------------
+  // Flow abort
+  // -------------------------------------------------------------------------
+  /**
+   * Abort every active run of one flow for a contact, immediately. Runs parked
+   * in a `wait` exit too — their delayed wake-up jobs find the run exited and
+   * no-op. Also cancels any of the flow's emails still sitting in the send
+   * queue for this contact (queued or awaiting retry), so an abort means no
+   * further mail, not just no further steps.
+   *
+   * No-op (returns zero counts) when nothing is active. Safe to call from the
+   * same handler that processes the business event ("user upgraded").
+   */
+  async abortFlow(flowSlug, externalId, opts = {}) {
+    const parsed = abortFlowInputSchema.parse({ flowSlug, externalId, reason: opts.reason });
+    const flow = await this.collections.flows.findOne(
+      { slug: parsed.flowSlug },
+      { projection: { _id: 1 } }
+    );
+    if (!flow) throw new Error(`abortFlow: unknown flow slug "${parsed.flowSlug}"`);
+    const result = await this.abortActiveRuns(
+      { externalId: parsed.externalId, flowId: flow._id },
+      parsed.reason ? `aborted_by_host:${parsed.reason}` : "aborted_by_host"
+    );
+    if (result.abortedRuns > 0 || result.cancelledSends > 0) {
+      await this.audit({
+        actor: "host",
+        action: "flow.abort",
+        resource: { collection: "mailer_flow_runs", slug: parsed.flowSlug },
+        diffSummary: `abortFlow slug=${parsed.flowSlug} externalId=${parsed.externalId} runs=${result.abortedRuns} sends=${result.cancelledSends}${parsed.reason ? ` reason=${parsed.reason}` : ""}`
+      });
+    }
+    return result;
+  }
+  /**
+   * Abort every active flow run for a contact across all flows. Same semantics
+   * as `abortFlow` — for "stop everything" events (account deleted, churned).
+   */
+  async abortAllFlows(externalId, opts = {}) {
+    const parsed = abortAllFlowsInputSchema.parse({ externalId, reason: opts.reason });
+    const result = await this.abortActiveRuns(
+      { externalId: parsed.externalId },
+      parsed.reason ? `aborted_by_host:${parsed.reason}` : "aborted_by_host"
+    );
+    if (result.abortedRuns > 0 || result.cancelledSends > 0) {
+      await this.audit({
+        actor: "host",
+        action: "flow.abort_all",
+        resource: { collection: "mailer_flow_runs" },
+        diffSummary: `abortAllFlows externalId=${parsed.externalId} runs=${result.abortedRuns} sends=${result.cancelledSends}${parsed.reason ? ` reason=${parsed.reason}` : ""}`
+      });
+    }
+    return result;
+  }
+  async abortActiveRuns(filter, exitReason) {
+    const runs = await this.collections.flowRuns.find({ ...filter, status: "active" }).toArray();
+    if (runs.length === 0) return { abortedRuns: 0, cancelledSends: 0 };
+    for (const run of runs) {
+      await exitFlowRun(run, exitReason, this.runnerContext);
+    }
+    const cancelled = await this.collections.sends.updateMany(
+      { flowRunId: { $in: runs.map((r) => r._id) }, status: { $in: ["queued", "failed"] } },
+      { $set: { status: "cancelled", errorMessage: `cancelled: ${exitReason}`, updatedAt: /* @__PURE__ */ new Date() } }
+    );
+    return { abortedRuns: runs.length, cancelledSends: cancelled.modifiedCount };
+  }
   /**
    * GDPR right-to-erasure. Hard-deletes the contact's PII and leaves a hashed
    * suppression row to block re-import. INVARIANT 9.
@@ -17564,6 +17853,207 @@ function matches(c, f) {
   return true;
 }
 
+// src/testing/recording-provider.ts
+var RecordingProvider = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  inner;
+  /** Every `SendArgs` handed to the provider, in call order. */
+  sent = [];
+  /** Same calls, with outcome attached. */
+  records = [];
+  get name() {
+    return this.inner.name;
+  }
+  get sendRatePerSecond() {
+    return this.inner.sendRatePerSecond;
+  }
+  async send(args) {
+    this.sent.push(args);
+    const record = { args, result: null, error: null, durationMs: 0, at: /* @__PURE__ */ new Date() };
+    this.records.push(record);
+    const startedAt = Date.now();
+    try {
+      const result = await this.inner.send(args);
+      record.result = result;
+      return result;
+    } catch (err) {
+      record.error = err instanceof Error ? err : new Error(String(err));
+      throw err;
+    } finally {
+      record.durationMs = Date.now() - startedAt;
+    }
+  }
+  async verifyWebhook(rawBody, headers) {
+    return this.inner.verifyWebhook(rawBody, headers);
+  }
+  parseWebhookEvents(payload, headers) {
+    return this.inner.parseWebhookEvents(payload, headers);
+  }
+  /** Last recorded send, or undefined. Sugar for the common single-send assertion. */
+  get last() {
+    return this.sent[this.sent.length - 1];
+  }
+  /** All sends addressed to `email` (case-insensitive). */
+  toRecipient(email) {
+    const lower = email.toLowerCase();
+    return this.sent.filter((s) => s.to.toLowerCase() === lower);
+  }
+  reset() {
+    this.sent.length = 0;
+    this.records.length = 0;
+  }
+};
+
+// src/testing/builders.ts
+var BACKDATE_MS = 6e4;
+async function buildTemplate(spec) {
+  const now = /* @__PURE__ */ new Date();
+  const createdAt = spec.createdAt ?? new Date(now.getTime() - BACKDATE_MS);
+  let mjml = "";
+  let html;
+  if (spec.html) {
+    html = spec.html;
+  } else {
+    mjml = spec.mjml ?? wrapMjml(spec.text ?? "Hello {{contact.fields.firstName}}");
+    const compiled = await compileTemplate(mjml);
+    html = compiled.html;
+  }
+  const plainText = spec.plainText ?? derivePlaintext(html);
+  return {
+    slug: spec.slug,
+    name: spec.name ?? spec.slug,
+    description: spec.description ?? "",
+    kind: spec.kind ?? "marketing",
+    fromName: spec.fromName ?? "Test",
+    fromEmail: spec.fromEmail ?? "hello@example.com",
+    replyTo: spec.replyTo ?? null,
+    providerOverride: spec.providerOverride ?? null,
+    subject: spec.subject ?? "Test subject",
+    preheader: spec.preheader ?? "",
+    body: { mjml, editorJson: null, html, plainText, compiledAt: createdAt },
+    variablesSchema: spec.variablesSchema ?? {},
+    draft: null,
+    tags: spec.tags ?? [],
+    trackOpens: spec.trackOpens ?? false,
+    trackClicks: spec.trackClicks ?? false,
+    stats: {
+      sent: 0,
+      delivered: 0,
+      opened: 0,
+      clicked: 0,
+      bounced: 0,
+      complained: 0,
+      unsubscribed: 0,
+      lastSentAt: null
+    },
+    publishedAt: spec.published === false ? null : createdAt,
+    publishedBy: spec.published === false ? null : "test",
+    createdAt,
+    updatedAt: createdAt
+  };
+}
+function wrapMjml(body) {
+  return `<mjml><mj-body><mj-section><mj-column><mj-text>${body}</mj-text></mj-column></mj-section></mj-body></mjml>`;
+}
+function buildFlow(spec) {
+  const now = /* @__PURE__ */ new Date();
+  const createdAt = spec.createdAt ?? new Date(now.getTime() - BACKDATE_MS);
+  const trigger = spec.trigger ?? {
+    type: "event",
+    eventName: spec.eventName ?? `${spec.slug}:trigger`,
+    once: spec.once ?? true
+  };
+  return {
+    slug: spec.slug,
+    name: spec.name ?? spec.slug,
+    description: spec.description ?? "",
+    trigger,
+    enabled: spec.enabled ?? true,
+    steps: spec.steps,
+    version: spec.version ?? 1,
+    draft: null,
+    goal: spec.goal ?? "activation",
+    audience: spec.audience ?? "test",
+    expectedVolumePerWeek: null,
+    stats: { activeRuns: 0, completedRuns: 0, sendsTotal: 0, sendsLast7Days: 0 },
+    lastTriggerScanAt: null,
+    publishedAt: createdAt,
+    publishedBy: "test",
+    createdAt,
+    updatedAt: createdAt
+  };
+}
+var step = {
+  send(templateSlug, opts = {}) {
+    return { type: "send", templateSlug, ...opts };
+  },
+  sendAt(templateSlug, delivery) {
+    return { type: "send", templateSlug, delivery };
+  },
+  wait(value, unit = "minutes") {
+    return { type: "wait", value, unit };
+  },
+  tag(addTags, removeTags) {
+    return { type: "tag", addTags, removeTags };
+  },
+  exit(reason) {
+    return { type: "exit", reason };
+  },
+  fireEvent(eventName, properties) {
+    return { type: "fire_event", eventName, properties };
+  }
+};
+
+// src/testing/drive.ts
+async function drain(ctx, opts = {}) {
+  const maxRounds = opts.maxRounds ?? 100;
+  const shouldDispatch = opts.dispatch !== false;
+  const attempted = /* @__PURE__ */ new Set();
+  const errors = [];
+  let dispatched = 0;
+  let rounds = 0;
+  while (rounds < maxRounds) {
+    rounds++;
+    await processNewlyFiredEventTriggers(ctx);
+    await sweepStrandedFlowRuns(ctx);
+    let didWork = false;
+    if (shouldDispatch) {
+      const queued = await ctx.collections.sends.find({ status: "queued" }, { projection: { _id: 1 } }).toArray();
+      for (const row of queued) {
+        const id = String(row._id);
+        if (attempted.has(id)) continue;
+        attempted.add(id);
+        didWork = true;
+        dispatched++;
+        try {
+          await dispatchSend(row._id, ctx);
+        } catch (err) {
+          errors.push(err instanceof Error ? err : new Error(String(err)));
+          if (opts.throwOnSendError) throw err;
+        }
+      }
+    }
+    const due = await ctx.collections.flowRuns.countDocuments({
+      status: "active",
+      nextActionAt: { $lte: /* @__PURE__ */ new Date() }
+    });
+    if (!didWork && due === 0) {
+      return { rounds, dispatched, errors, settled: true };
+    }
+  }
+  return { rounds, dispatched, errors, settled: false };
+}
+async function dispatchQueued(ctx) {
+  const queued = await ctx.collections.sends.find({ status: "queued" }, { projection: { _id: 1 } }).toArray();
+  for (const row of queued) {
+    await dispatchSend(row._id, ctx).catch(() => {
+    });
+  }
+  return queued.length;
+}
+
 // src/testing/index.ts
 async function createTestMailer(opts = {}) {
   const { MongoMemoryServer } = await Promise.resolve().then(() => __toESM(require_mongodb_memory_server()));
@@ -17573,13 +18063,13 @@ async function createTestMailer(opts = {}) {
   const db = client.db("mailery-test");
   const memoryAdapter = opts.adapter ? null : new MemoryContactAdapter(opts.seedContacts ?? []);
   const adapter = opts.adapter ?? memoryAdapter;
-  const provider = opts.provider ?? new NullProvider();
+  const provider = new RecordingProvider(await resolveProvider(opts.provider ?? "null"));
   const mailer = await Mailer.init({
     db,
     adapter,
-    queue: { driver: "noop" },
-    providers: { null: provider },
-    defaultProvider: "null",
+    queue: opts.queue ?? { driver: "noop" },
+    providers: { [provider.name]: provider },
+    defaultProvider: provider.name,
     publicUrl: "http://localhost:3000",
     unsubscribeSecret: "test-unsub-secret-32-bytes-or-more-please",
     senderAddress: "1 Test St, Brooklyn NY 11201",
@@ -17587,19 +18077,81 @@ async function createTestMailer(opts = {}) {
     workerless: true,
     ...opts.config ?? {}
   });
-  const stop = async () => {
-    await mailer.stop().catch(() => {
-    });
-    await client.close().catch(() => {
-    });
-    await mongo.stop().catch(() => {
-    });
+  if (opts.startWorkers) await mailer.startWorkers();
+  const ctx = mailer.getRunnerContext();
+  const harness = {
+    mailer,
+    db,
+    provider,
+    adapter,
+    memoryAdapter,
+    ctx,
+    async seedContact(contact, seedOpts = {}) {
+      if (!memoryAdapter) {
+        throw new Error("seedContact requires the built-in MemoryContactAdapter \u2014 you passed a custom `adapter`.");
+      }
+      memoryAdapter.upsert(contact);
+      if (seedOpts.subscribe !== false) {
+        await mailer.upsertSubscription({
+          externalId: contact.externalId,
+          source: seedOpts.source ?? "test"
+        });
+      }
+      return contact;
+    },
+    async seedTemplate(spec) {
+      const doc = await buildTemplate(spec);
+      const res = await ctx.collections.templates.insertOne(doc);
+      doc._id = res.insertedId;
+      return doc;
+    },
+    async seedFlow(spec) {
+      const doc = buildFlow(spec);
+      const res = await ctx.collections.flows.insertOne(doc);
+      doc._id = res.insertedId;
+      return doc;
+    },
+    drain(drainOpts) {
+      return drain(ctx, drainOpts);
+    },
+    stop: async () => {
+      await mailer.stop().catch(() => {
+      });
+      await client.close().catch(() => {
+      });
+      await mongo.stop().catch(() => {
+      });
+    }
   };
-  return { mailer, db, provider, adapter, memoryAdapter, stop };
+  return harness;
+}
+async function resolveProvider(spec) {
+  if (typeof spec !== "string") return spec;
+  if (spec === "null") return new NullProvider();
+  const apiKey = process.env.SENDGRID_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "createTestMailer({ provider: 'sendgrid' }) requires SENDGRID_API_KEY. Live tests should gate on it before constructing the harness."
+    );
+  }
+  const { SendGridProvider: SendGridProvider2 } = await Promise.resolve().then(() => (init_sendgrid(), sendgrid_exports));
+  return new SendGridProvider2({
+    apiKey,
+    // Sandbox unless explicitly told to deliver: SendGrid still authenticates
+    // and validates the payload, it just never puts anything in an inbox.
+    sandbox: process.env.MAILERY_LIVE_E2E !== "deliver"
+  });
 }
 
 exports.MemoryContactAdapter = MemoryContactAdapter;
 exports.NullProvider = NullProvider;
+exports.RecordingProvider = RecordingProvider;
+exports.buildFlow = buildFlow;
+exports.buildTemplate = buildTemplate;
 exports.createTestMailer = createTestMailer;
+exports.dispatchQueued = dispatchQueued;
+exports.drain = drain;
+exports.step = step;
+exports.wrapMjml = wrapMjml;
 //# sourceMappingURL=testing.cjs.map
 //# sourceMappingURL=testing.cjs.map