mailery 0.7.0 → 0.8.0

package/dist/{null-B0rPgE5_.d.cts → null-BCxlHRJ0.d.cts}

@@ -527,6 +527,14 @@ interface MailTesterConfig {
     apiKey: string;
     /** Minimum score (0-10) below which publish is blocked. Default 8.0. */
     minScore?: number;
+    /**
+     * When true, publishing content that has no cached score is blocked too —
+     * the operator must run a deliverability check for that exact content first.
+     * Default false, which only blocks content already known to score below
+     * `minScore`; in that mode any edit (even whitespace) changes the content
+     * key, misses the cache, and publishes freely.
+     */
+    requireScore?: boolean;
     /**
      * How long a successful score remains cached for the same content. Default 24.
      * Re-publishing the same body within the window does not burn a credit.
@@ -1469,4 +1477,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };
+export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type FlowTrigger as a2, type QueueDriverConfig as a3, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };

package/dist/{null-B0rPgE5_.d.ts → null-BCxlHRJ0.d.ts}

@@ -527,6 +527,14 @@ interface MailTesterConfig {
     apiKey: string;
     /** Minimum score (0-10) below which publish is blocked. Default 8.0. */
     minScore?: number;
+    /**
+     * When true, publishing content that has no cached score is blocked too —
+     * the operator must run a deliverability check for that exact content first.
+     * Default false, which only blocks content already known to score below
+     * `minScore`; in that mode any edit (even whitespace) changes the content
+     * key, misses the cache, and publishes freely.
+     */
+    requireScore?: boolean;
     /**
      * How long a successful score remains cached for the same content. Default 24.
      * Re-publishing the same body within the window does not burn a credit.
@@ -1469,4 +1477,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };
+export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type FlowTrigger as a2, type QueueDriverConfig as a3, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };

package/dist/testing.cjs

@@ -504,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) {
@@ -532,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;
@@ -669,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) {
@@ -7092,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);
@@ -15485,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}`;
@@ -15500,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 });
@@ -15538,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(
@@ -15627,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,
@@ -15636,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(
@@ -15751,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;
   }
@@ -15766,34 +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);
+      return handleBranch(run, step2, contact, ctx);
     case "send": {
-      if (step.delivery) {
-        const deliverAt = computeDeliveryTime(/* @__PURE__ */ new Date(), step.delivery, contact.timezone);
+      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, step, contact, flow, 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 },
@@ -15818,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 },
@@ -15859,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) {
@@ -15882,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()
@@ -15896,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 {
@@ -17852,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()));
@@ -17861,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",
@@ -17875,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