mailery 0.5.1 → 0.8.0

package/dist/index.js

@@ -1,7 +1,7 @@
+import { z } from 'zod';
 import { ObjectId } from 'mongodb';
 import crypto2 from 'crypto';
 import sgMail from '@sendgrid/mail';
-import { z } from 'zod';
 import IORedis from 'ioredis';
 import Handlebars from 'handlebars';
 import { convert } from 'html-to-text';
@@ -31,6 +31,55 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// 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 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, {
@@ -344,6 +393,12 @@ var tagInputSchema = z.object({
   externalId: externalIdSchema,
   tag: z.string().min(1).max(128)
 });
+var abortFlowInputSchema = z.object({
+  flowSlug: slugSchema,
+  externalId: externalIdSchema,
+  reason: z.string().min(1).max(200).optional()
+});
+var abortAllFlowsInputSchema = abortFlowInputSchema.omit({ flowSlug: true });
 var sendOneOffInputSchema = z.object({
   templateSlug: slugSchema,
   externalId: externalIdSchema,
@@ -373,7 +428,13 @@ var flowStepSchema = z.lazy(
       type: z.literal("send"),
       templateSlug: slugSchema,
       providerOverride: z.string().optional(),
-      vars: z.record(z.string(), z.unknown()).optional()
+      vars: z.record(z.string(), z.unknown()).optional(),
+      delivery: z.object({
+        weekdaysOnly: z.boolean().optional(),
+        timeOfDay: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:mm").optional(),
+        useContactTimezone: z.boolean().optional(),
+        timezone: z.string().optional()
+      }).optional()
     }),
     z.object({
       type: z.literal("tag"),
@@ -1163,6 +1224,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,
@@ -1260,6 +1322,105 @@ function effectiveLowerBound(ctx, opts) {
   }
   return null;
 }
+
+// src/server/runner/delivery-window.ts
+var TIME_OF_DAY_GRACE_MS = 60 * 6e4;
+function computeDeliveryTime(now, window, contactTimezone) {
+  const tz = pickTimezone(window, contactTimezone);
+  let candidate = now;
+  if (window.timeOfDay) {
+    const [hh, mm] = window.timeOfDay.split(":").map(Number);
+    const local = localParts(candidate, tz);
+    const todaySlot = utcFromLocal(local.y, local.mo, local.d, hh, mm, tz);
+    if (candidate.getTime() < todaySlot.getTime()) {
+      candidate = todaySlot;
+    } else if (candidate.getTime() - todaySlot.getTime() > TIME_OF_DAY_GRACE_MS) {
+      const next = addLocalDays(local, 1);
+      candidate = utcFromLocal(next.y, next.mo, next.d, hh, mm, tz);
+    }
+  }
+  if (window.weekdaysOnly) {
+    for (let guard = 0; guard < 3; guard++) {
+      const local = localParts(candidate, tz);
+      if (local.weekday !== "Sat" && local.weekday !== "Sun") break;
+      const shift = local.weekday === "Sat" ? 2 : 1;
+      const moved = addLocalDays(local, shift);
+      candidate = utcFromLocal(moved.y, moved.mo, moved.d, local.hh, local.mi, tz);
+    }
+  }
+  return candidate;
+}
+function pickTimezone(window, contactTimezone) {
+  const candidates = [
+    window.useContactTimezone ? contactTimezone : void 0,
+    window.timezone,
+    "UTC"
+  ];
+  for (const tz of candidates) {
+    if (tz && isValidTimezone(tz)) return tz;
+  }
+  return "UTC";
+}
+var validatedZones = /* @__PURE__ */ new Map();
+function isValidTimezone(tz) {
+  const cached = validatedZones.get(tz);
+  if (cached !== void 0) return cached;
+  let ok = true;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+  } catch {
+    ok = false;
+  }
+  validatedZones.set(tz, ok);
+  return ok;
+}
+var partFormatters = /* @__PURE__ */ new Map();
+function formatterFor(tz) {
+  let f = partFormatters.get(tz);
+  if (!f) {
+    f = new Intl.DateTimeFormat("en-US", {
+      timeZone: tz,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      weekday: "short",
+      hour12: false
+    });
+    partFormatters.set(tz, f);
+  }
+  return f;
+}
+function localParts(date, tz) {
+  const parts = {};
+  for (const p of formatterFor(tz).formatToParts(date)) parts[p.type] = p.value;
+  return {
+    y: Number(parts.year),
+    mo: Number(parts.month),
+    d: Number(parts.day),
+    hh: Number(parts.hour) % 24,
+    // Intl emits '24' for midnight in some locales
+    mi: Number(parts.minute),
+    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(mjml, { validationLevel: "soft", minify: false });
   const plainText = derivePlaintext(out.html);
@@ -1383,6 +1544,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"],
@@ -1701,13 +1865,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,
@@ -1734,6 +1914,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,
@@ -1743,10 +1927,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(
@@ -1783,7 +1964,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(
@@ -1792,8 +1973,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
   };
@@ -1878,8 +2061,15 @@ async function processOneRunStep(runId, ctx) {
       return handleCondition(run, step, contact, ctx);
     case "branch":
       return handleBranch(run, step, contact, ctx);
-    case "send":
+    case "send": {
+      if (step.delivery) {
+        const deliverAt = computeDeliveryTime(/* @__PURE__ */ new Date(), step.delivery, contact.timezone);
+        if (deliverAt.getTime() > Date.now() + 3e4) {
+          return deferSendForWindow(run, deliverAt, ctx);
+        }
+      }
       return handleSend(run, step, contact, flow, ctx);
+    }
     case "tag":
       return handleTag(run, step, ctx);
     case "fire_event":
@@ -2030,6 +2220,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(
@@ -3554,6 +3772,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,
@@ -3633,6 +3852,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);
@@ -3848,6 +4071,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.
@@ -4050,6 +4339,7 @@ var Mailer = class _Mailer {
 
 // src/server/index.ts
 init_mongo();
+init_vars();
 
 // src/server/providers/null.ts
 var counter = 0;
@@ -4188,6 +4478,18 @@ ${input.plainText}`);
       hint: "Front-load the important words so the truncated preview still makes sense."
     });
   }
+  if (config.varsJsonSchema) {
+    const sources = [input.subject, input.preheader, input.mjml, JSON.stringify(input.editorJson ?? null)];
+    const unknown = findUnknownVariables(sources.join("\n"), config.varsJsonSchema);
+    if (unknown.length > 0) {
+      issues.push({
+        rule: "unknown_variable",
+        severity: "warning",
+        message: `Template references variable(s) not in the vars schema: ${unknown.join(", ")}.`,
+        hint: "These render as empty strings. Check for typos, or add the key to your varsAdapter schema. Paths inside {{#each}}/{{#with}} blocks are relative and not checked."
+      });
+    }
+  }
   const linkCount = countMatches(input.html, /<a\s[^>]*\bhref\s*=/gi);
   if (linkCount > 10) {
     issues.push({
@@ -4250,6 +4552,60 @@ function findSpamSignals(text) {
   if (/!{3,}/.test(text)) out.add('excessive "!!!"');
   return Array.from(out);
 }
+var BUILTIN_VAR_ROOTS = /* @__PURE__ */ new Set([
+  "contact",
+  "vars",
+  "event",
+  "unsubscribeUrl",
+  "viewInBrowserUrl",
+  "preferenceCenterUrl",
+  "senderAddress",
+  "this"
+]);
+var PATH_TOKEN = /^@?[A-Za-z_][\w$]*(\.[A-Za-z_][\w$]*)*$/;
+function findUnknownVariables(source, schema) {
+  const hasBlockScopes = /\{\{[#^]\s*(each|with)\b/.test(source);
+  const unknown = /* @__PURE__ */ new Set();
+  const re = /\{\{\{?\s*([^{}]+?)\s*\}?\}\}/g;
+  let m;
+  while (m = re.exec(source)) {
+    const expr = m[1].trim();
+    if (!expr || /^[#^/>!]/.test(expr) || expr === "else") continue;
+    if (expr.includes("(")) continue;
+    const parts = expr.split(/\s+/);
+    const candidates = parts.length > 1 ? parts.slice(1) : parts;
+    for (const raw of candidates) {
+      if (!PATH_TOKEN.test(raw)) continue;
+      if (raw.startsWith("@")) continue;
+      const segments = raw.split(".");
+      if (BUILTIN_VAR_ROOTS.has(segments[0])) continue;
+      if (hasBlockScopes && segments.length === 1) continue;
+      if (!schemaHasPath(schema, segments)) unknown.add(raw);
+    }
+  }
+  return Array.from(unknown);
+}
+function schemaHasPath(node, segments) {
+  if (segments.length === 0) return true;
+  if (!node || typeof node !== "object") return true;
+  const n = node;
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (Array.isArray(n[key])) {
+      return n[key].some((branch) => schemaHasPath(branch, segments));
+    }
+  }
+  if (Array.isArray(n.type) && n.type.includes("object") && !n.properties) return true;
+  if (n.type === "array") {
+    if (segments[0] === "length") return true;
+    return schemaHasPath(n.items, segments);
+  }
+  const props = n.properties;
+  if (!props || typeof props !== "object") return true;
+  const [head, ...rest] = segments;
+  if (head in props) return schemaHasPath(props[head], rest);
+  if (n.additionalProperties === void 0 || n.additionalProperties === false) return false;
+  return true;
+}
 function isAllCaps(subject) {
   const letters = subject.replace(/[^a-zA-Z]/g, "");
   if (letters.length < 5) return false;
@@ -4257,6 +4613,9 @@ function isAllCaps(subject) {
   return upper / letters.length > 0.5;
 }
 
+// src/server/api/admin.ts
+init_vars();
+
 // src/server/api/setup-status.ts
 async function runSetupChecks(mailer) {
   const checks = [];
@@ -4695,7 +5054,7 @@ async function checkPostalAddress(mailer) {
     label: "CAN-SPAM postal address",
     severity: "warn",
     message: `${marketingCount} published marketing template${marketingCount === 1 ? "" : "s"} but senderAddress is unset`,
-    hint: "CAN-SPAM requires a postal address in marketing emails. Set `senderAddress` in your Mailer config and reference it via `{{senderAddress}}` in your templates."
+    hint: "CAN-SPAM requires a postal address in marketing emails. Set `senderAddress` in your Mailer config and reference the `{{senderAddress}}` render variable in your templates."
   };
 }
 async function checkDoiTemplate(mailer) {
@@ -4989,19 +5348,30 @@ async function persistScore(ctx, input) {
 }
 async function evaluateMailTesterGate(ctx, input) {
   const cfg = ctx.config.mailTester;
-  if (!cfg?.apiKey) return { allowed: true, reason: null, score: null };
+  if (!cfg?.apiKey) return { allowed: true, reason: null, score: null, code: null };
   const minScore = cfg.minScore ?? 8;
   const key = mailTesterContentKey(input);
   const cached = await findCachedScore(ctx, key);
-  if (!cached) return { allowed: true, reason: null, score: null };
+  if (!cached) {
+    if (cfg.requireScore) {
+      return {
+        allowed: false,
+        reason: "No Mail-Tester score for this exact content. Run a deliverability check before publishing.",
+        score: null,
+        code: "no_score"
+      };
+    }
+    return { allowed: true, reason: null, score: null, code: null };
+  }
   if (cached.score < minScore) {
     return {
       allowed: false,
       reason: `Mail-Tester score ${cached.score.toFixed(1)} is below minimum ${minScore.toFixed(1)}`,
-      score: cached
+      score: cached,
+      code: "low_score"
     };
   }
-  return { allowed: true, reason: null, score: cached };
+  return { allowed: true, reason: null, score: cached, code: null };
 }
 
 // src/server/api/admin.ts
@@ -5036,12 +5406,19 @@ function createAdminRouter(mailer, opts = {}) {
 function apiRouter(mailer, opts = {}) {
   const r = Router();
   const c = mailer.collections;
+  const varsSchema = mailer.config.varsAdapter ? varsJsonSchema(mailer.config.varsAdapter) : null;
   function getMailTesterClient() {
     if (opts.mailTesterClient) return opts.mailTesterClient;
     const cfg = mailer.config.mailTester;
     if (!cfg?.apiKey) return null;
     return createMailTesterClient(cfg);
   }
+  r.get(
+    "/vars-schema",
+    asyncHandler(async (_req, res) => {
+      res.json({ schema: varsSchema, builtins: RESERVED_VAR_KEYS });
+    })
+  );
   r.get(
     "/me",
     asyncHandler(async (req, res) => {
@@ -5988,6 +6365,7 @@ function apiRouter(mailer, opts = {}) {
       res.json({
         configured,
         minScore: cfg?.minScore ?? 8,
+        requireScore: !!cfg?.requireScore,
         cacheHours: cfg?.cacheHours ?? 24,
         score: cached
       });
@@ -6128,9 +6506,11 @@ function apiRouter(mailer, opts = {}) {
           compileFailed: true
         });
       }
+      if (!html && typeof tpl.body?.html === "string") html = tpl.body.html;
+      if (!plainText && typeof tpl.body?.plainText === "string") plainText = tpl.body.plainText;
       const lint = lintTemplate(
         { subject, preheader, mjml, editorJson, html, plainText, kind, fromEmail },
-        { senderDomains: mailer.config.senderDomains }
+        { senderDomains: mailer.config.senderDomains, varsJsonSchema: varsSchema }
       );
       res.json({ ...lint, compileFailed: false });
     })
@@ -6181,7 +6561,7 @@ function apiRouter(mailer, opts = {}) {
           kind: tpl.kind,
           fromEmail: tpl.fromEmail
         },
-        { senderDomains: mailer.config.senderDomains }
+        { senderDomains: mailer.config.senderDomains, varsJsonSchema: varsSchema }
       );
       if (lint.errors.length > 0) {
         return res.status(422).json({
@@ -6200,9 +6580,10 @@ function apiRouter(mailer, opts = {}) {
         if (!gate.allowed) {
           return res.status(422).json({
             error: "mail_tester_blocked",
+            code: gate.code,
             message: gate.reason,
             score: gate.score,
-            hint: "Re-run the deliverability check after fixing the feedback, or POST `bypassMailTester: true` to publish anyway."
+            hint: gate.code === "no_score" ? "POST to `/templates/:slug/mail-tester-check`, poll `/mail-tester-result`, then publish \u2014 or POST `bypassMailTester: true` to publish anyway." : "Re-run the deliverability check after fixing the feedback, or POST `bypassMailTester: true` to publish anyway."
           });
         }
       }
@@ -6273,40 +6654,93 @@ function apiRouter(mailer, opts = {}) {
         html = tpl.body.html;
         plainText = tpl.body.plainText;
       }
-      const sampleContact = req.body?.sampleContact ?? {
-        externalId: "preview-contact",
-        email: "preview@example.com",
-        tags: [],
-        fields: { firstName: "Alex" }
-      };
+      let contact;
+      const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : null;
+      if (contactId) {
+        const found = await mailer.adapter.getById(contactId);
+        if (!found) return res.status(404).json({ error: "contact_not_found", contactId });
+        contact = found;
+      } else {
+        contact = req.body?.sampleContact ?? {
+          externalId: "preview-contact",
+          email: "preview@example.com",
+          tags: [],
+          fields: { firstName: "Alex" }
+        };
+      }
+      const eventProperties = req.body?.eventProperties && typeof req.body.eventProperties === "object" ? req.body.eventProperties : void 0;
+      let resolved = {};
+      try {
+        resolved = await resolveVars(mailer.config.varsAdapter, contact, {
+          reason: "preview",
+          templateSlug: tpl.slug,
+          eventProperties
+        });
+      } catch (err) {
+        return res.status(502).json({
+          error: "vars_resolve_failed",
+          message: `varsAdapter.resolve threw: ${String(err?.message ?? err)}`
+        });
+      }
       const renderCtx = {
-        contact: sampleContact,
+        ...resolved,
+        contact,
         vars: req.body?.vars ?? {},
+        event: eventProperties ?? {},
         unsubscribeUrl: `${mailer.config.publicUrl}/m/unsub/preview`,
         senderAddress: mailer.config.senderAddress
       };
       const previewTpl = { ...tpl, body: { ...tpl.body, html, plainText } };
       const rendered = await renderTemplate(previewTpl, renderCtx, { helpers: mailer.config.handlebarsHelpers });
-      return res.json({ subject: rendered.subject, preheader: rendered.preheader, html: rendered.html, plainText: rendered.plainText });
+      return res.json({
+        subject: rendered.subject,
+        preheader: rendered.preheader,
+        html: rendered.html,
+        plainText: rendered.plainText,
+        contact: { externalId: contact.externalId, email: contact.email }
+      });
     })
   );
   r.post(
     "/templates/:slug/send-test",
     asyncHandler(async (req, res) => {
-      const { to, sampleData } = req.body ?? {};
+      const { to, sampleData, contactId, eventProperties } = req.body ?? {};
       if (!to) return res.status(400).json({ error: "to_required" });
       const tpl = await c.templates.findOne({ slug: req.params.slug });
       if (!tpl) return res.status(404).json({ error: "not_found" });
-      const contact = sampleData?.contact ?? {
-        externalId: "test-recipient",
-        email: to,
-        tags: [],
-        fields: { firstName: "Test" }
-      };
-      contact.email = to;
+      let contact;
+      if (typeof contactId === "string" && contactId) {
+        const found = await mailer.adapter.getById(contactId);
+        if (!found) return res.status(404).json({ error: "contact_not_found", contactId });
+        contact = { ...found, email: to };
+      } else {
+        contact = sampleData?.contact ?? {
+          externalId: "test-recipient",
+          email: to,
+          tags: [],
+          fields: { firstName: "Test" }
+        };
+        contact.email = to;
+      }
+      const evProps = eventProperties && typeof eventProperties === "object" ? eventProperties : void 0;
+      let resolved = {};
+      try {
+        resolved = await resolveVars(mailer.config.varsAdapter, contact, {
+          reason: "test",
+          templateSlug: tpl.slug,
+          eventProperties: evProps
+        });
+      } catch (err) {
+        return res.status(502).json({
+          error: "vars_resolve_failed",
+          message: `varsAdapter.resolve threw: ${String(err?.message ?? err)}`
+        });
+      }
       const renderCtx = {
+        ...resolved,
         contact,
         vars: sampleData?.vars ?? {},
+        event: evProps ?? {},
         unsubscribeUrl: `${mailer.config.publicUrl}/m/unsub/test`,
         senderAddress: mailer.config.senderAddress
       };
@@ -6957,8 +7391,8 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.8.0";
 
-export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, validateSenderDomain, verifyUnsubscribeToken };
+export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, RESERVED_VAR_KEYS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, defineVars, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, validateSenderDomain, varsJsonSchema, verifyUnsubscribeToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map