mailery 0.7.0 → 0.8.0

package/dist/testing.d.cts

@@ -1,5 +1,6 @@
 import { Db } from 'mongodb';
-import { C as ContactAdapter, a as Contact, A as AdapterFilter, d as Mailer, s as NullProvider } from './null-B0rPgE5_.cjs';
+import { C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, N as NormalizedEvent, F as FlowStep, a2 as FlowTrigger, m as FlowGoal, U as TemplateKind, T as TemplateDoc, l as FlowDoc, D as DeliveryWindow, R as RunnerContext, d as Mailer, a3 as QueueDriverConfig } from './null-BCxlHRJ0.cjs';
+export { s as NullProvider } from './null-BCxlHRJ0.cjs';
 import 'zod';
 import 'handlebars';
 import 'ioredis';
@@ -29,36 +30,255 @@ declare class MemoryContactAdapter implements ContactAdapter {
     removeTags(externalId: string, tags: string[]): Promise<void>;
 }
 
+/**
+ * RecordingProvider — a `MailProvider` decorator that records every send and
+ * then delegates to whatever it wraps.
+ *
+ * This is what lets one test suite run against two very different backends.
+ * Wrapping `NullProvider` gives fast, offline, deterministic assertions;
+ * wrapping `SendGridProvider` makes the *same* assertions run against the real
+ * API, with real auth, real payload validation and (outside sandbox mode) real
+ * delivery. Tests assert on the recording either way, so nothing is duplicated
+ * between the two tiers.
+ *
+ *   const provider = new RecordingProvider(new NullProvider())
+ *   ...
+ *   expect(provider.sent[0]?.subject).toContain('Alice')     // SendArgs
+ *   expect(provider.records[0]?.result?.status).toBe('accepted')
+ *
+ * `sent` is deliberately a bare `SendArgs[]`, matching `NullProvider.sent`, so
+ * this drops in wherever the old harness provider was used. `records` carries
+ * the richer per-call detail (result, error, duration) that the live tier needs.
+ */
+
+interface SendRecord {
+    args: SendArgs;
+    /** Provider result, or null when the call threw. */
+    result: SendResult | null;
+    /** Error thrown by the wrapped provider, or null on success. */
+    error: Error | null;
+    /** Wall-clock ms the wrapped `send` took. Meaningful for the live tier. */
+    durationMs: number;
+    at: Date;
+}
+declare class RecordingProvider implements MailProvider {
+    readonly inner: MailProvider;
+    /** Every `SendArgs` handed to the provider, in call order. */
+    readonly sent: SendArgs[];
+    /** Same calls, with outcome attached. */
+    readonly records: SendRecord[];
+    constructor(inner: MailProvider);
+    get name(): string;
+    get sendRatePerSecond(): number | undefined;
+    send(args: SendArgs): Promise<SendResult>;
+    verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
+    parseWebhookEvents(payload: unknown, headers: Record<string, string>): NormalizedEvent[];
+    /** Last recorded send, or undefined. Sugar for the common single-send assertion. */
+    get last(): SendArgs | undefined;
+    /** All sends addressed to `email` (case-insensitive). */
+    toRecipient(email: string): SendArgs[];
+    reset(): void;
+}
+
+/**
+ * Document builders for tests. Hand-rolling a full `TemplateDoc` / `FlowDoc`
+ * literal is ~40 lines of noise per fixture; these fill every required field
+ * with a sane default so a test only states what it is actually asserting on.
+ *
+ *   await H.seedTemplate({ slug: 'welcome', subject: 'Hi {{contact.fields.firstName}}' })
+ *   await H.seedFlow({ slug: 'onboarding', eventName: 'Created', steps: [...] })
+ *
+ * `createdAt` defaults to a minute in the past: the event-trigger scan uses
+ * `lastTriggerScanAt ?? createdAt` as its watermark and only picks up events
+ * with `occurredAt > watermark`, so a flow created at the same instant as the
+ * event it should catch would never fire.
+ */
+
+interface TemplateSpec {
+    slug: string;
+    name?: string;
+    description?: string;
+    kind?: TemplateKind;
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string | null;
+    providerOverride?: string | null;
+    subject?: string;
+    preheader?: string;
+    /** MJML source — compiled to html + derived plain text. */
+    mjml?: string;
+    /** Pre-compiled HTML. Wins over `mjml`. */
+    html?: string;
+    /**
+     * Body copy wrapped in a minimal MJML document. The lazy path — use when the
+     * test cares about the rendered *content*, not the markup around it.
+     */
+    text?: string;
+    /** Explicit plain-text part. Omit to auto-derive from the HTML. */
+    plainText?: string;
+    variablesSchema?: TemplateDoc['variablesSchema'];
+    tags?: string[];
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    published?: boolean;
+    createdAt?: Date;
+}
+declare function buildTemplate(spec: TemplateSpec): Promise<TemplateDoc>;
+/** Minimal valid MJML document around a body string. */
+declare function wrapMjml(body: string): string;
+interface FlowSpec {
+    slug: string;
+    name?: string;
+    description?: string;
+    steps: FlowStep[];
+    /** Shorthand for an `event` trigger. Ignored when `trigger` is given. */
+    eventName?: string;
+    /** Re-entry policy for the shorthand trigger. Defaults to true (enter once). */
+    once?: boolean;
+    trigger?: FlowTrigger;
+    enabled?: boolean;
+    goal?: FlowGoal;
+    audience?: string;
+    version?: number;
+    createdAt?: Date;
+}
+declare function buildFlow(spec: FlowSpec): FlowDoc;
+declare const step: {
+    readonly send: (templateSlug: string, opts?: Omit<Extract<FlowStep, {
+        type: "send";
+    }>, "type" | "templateSlug">) => FlowStep;
+    readonly sendAt: (templateSlug: string, delivery: DeliveryWindow) => FlowStep;
+    readonly wait: (value: number, unit?: "minutes" | "hours" | "days" | "weeks") => FlowStep;
+    readonly tag: (addTags?: string[], removeTags?: string[]) => FlowStep;
+    readonly exit: (reason?: string) => FlowStep;
+    readonly fireEvent: (eventName: string, properties?: Record<string, unknown>) => FlowStep;
+};
+
+/**
+ * Deterministic runner driver.
+ *
+ * The test harness uses the `noop` queue driver: `queue.add()` throws nothing
+ * away quietly but nothing ever fires it either, so the runner only moves when
+ * a test tells it to. `drain` is that push — it alternates the trigger scan,
+ * the due-run sweep and send dispatch until the system is quiescent, which is
+ * what a real deployment converges to between ticks.
+ *
+ *   await H.mailer.fire('Created', 'u1')
+ *   await drain(H.mailer.getRunnerContext())
+ *   expect(H.provider.sent).toHaveLength(1)
+ *
+ * "Quiescent" means: no active flow_run whose `nextActionAt` has passed, and
+ * no queued send left to dispatch. Runs parked in a `wait` step or deferred by
+ * a delivery window are *expected* to remain — move the clock forward and
+ * drain again.
+ */
+
+interface DrainOptions {
+    /**
+     * Safety valve. Each round advances every due run by exactly one step, so a
+     * flow needs one round per step. Hitting the cap means the system did not
+     * converge — `settled` comes back false rather than throwing, so a test can
+     * assert on non-convergence deliberately.
+     */
+    maxRounds?: number;
+    /** Skip send dispatch to inspect `queued` send rows before they go out. */
+    dispatch?: boolean;
+    /**
+     * Let provider/render errors propagate. Off by default: `dispatchSend`
+     * rethrows so the real queue can retry, and a drain that unwound on the
+     * first failure could not assert on the failed send row it just wrote.
+     */
+    throwOnSendError?: boolean;
+}
+interface DrainResult {
+    rounds: number;
+    /** Sends passed to `dispatchSend`. Not all of them reached the provider. */
+    dispatched: number;
+    /** Errors thrown by `dispatchSend`, swallowed unless `throwOnSendError`. */
+    errors: Error[];
+    settled: boolean;
+}
+declare function drain(ctx: RunnerContext, opts?: DrainOptions): Promise<DrainResult>;
+/**
+ * Dispatch every currently-queued send, once. Use when a test drove the flow
+ * with `drain({ dispatch: false })` and wants to inspect the queued rows first.
+ */
+declare function dispatchQueued(ctx: RunnerContext): Promise<number>;
+
 /**
  * Test helpers — `import { ... } from 'mailery/testing'`.
  *
- *   const harness = await createTestMailer({ seedContacts: [...] })
- *   await harness.mailer.upsertSubscription({ externalId: 'u1', source: 'test' })
- *   await harness.mailer.fire('Created', 'u1')
- *   // drive the runner directly:
- *   const { runTick, processOneRunStep, dispatchSend } = await import('mailery')
- *   await runTick(harness.mailer.getRunnerContext())
- *   expect(harness.provider.sent.length).toBe(1)
- *   await harness.stop()
+ *   const H = await createTestMailer({
+ *     seedContacts: [{ externalId: 'u1', email: 'alice@example.com', tags: [], fields: {} }],
+ *   })
+ *   await H.seedContact({ externalId: 'u1', ... })          // adapter + subscription
+ *   await H.seedTemplate({ slug: 'welcome', subject: 'Hi {{contact.fields.firstName}}' })
+ *   await H.seedFlow({ slug: 'onboarding', eventName: 'Created', steps: [step.send('welcome')] })
+ *
+ *   H.mailer.registerEvent({ name: 'Created', dedupePolicy: 'once-per-contact' })
+ *   await H.mailer.fire('Created', 'u1')
+ *   await H.drain()                                          // run to quiescence
  *
- * Backed by mongodb-memory-server + ioredis-mock + NullProvider.
+ *   expect(H.provider.sent).toHaveLength(1)
+ *   await H.stop()
+ *
+ * Backed by mongodb-memory-server + the `noop` queue driver, so nothing runs in
+ * the background and every transition is something the test asked for. The
+ * provider is always wrapped in a `RecordingProvider`, which is what allows the
+ * same suite to run against `NullProvider` offline or against real SendGrid
+ * (`provider: 'sendgrid'`) without changing a single assertion.
  */
 
+/**
+ * Which provider the harness sends through.
+ *  - `'null'`      — in-memory, offline, the default.
+ *  - `'sendgrid'`  — the real API. Needs `SENDGRID_API_KEY`. Sandbox mode
+ *                    unless `MAILERY_LIVE_E2E=deliver`, so the default costs
+ *                    nothing and delivers nothing while still proving that
+ *                    SendGrid accepts the payload.
+ *  - a `MailProvider` instance — anything else you want to record around.
+ */
+type ProviderSpec = 'null' | 'sendgrid' | MailProvider;
 interface TestMailerOptions {
     adapter?: ContactAdapter;
     seedContacts?: Contact[];
-    provider?: NullProvider;
+    provider?: ProviderSpec;
+    /**
+     * Queue driver. Defaults to `noop`, which is what makes the fast matrix
+     * deterministic — nothing runs until a test calls `drain()`. The live tier
+     * passes a real `bull` config to exercise job delays, retries and the send
+     * rate limiter, and must then also set `startWorkers`.
+     */
+    queue?: QueueDriverConfig;
+    /** Call `mailer.startWorkers()` after init. Requires a non-noop `queue`. */
+    startWorkers?: boolean;
     /** Override Mailer config (excluding required fields the harness fills in). */
     config?: Partial<Omit<Parameters<typeof Mailer.init>[0], 'db' | 'adapter' | 'queue' | 'providers' | 'defaultProvider'>>;
 }
+interface SeedContactOptions {
+    /** Also create a `subscribed` subscription row. Default true. */
+    subscribe?: boolean;
+    source?: string;
+}
 interface TestMailerHarness {
     mailer: Mailer;
     db: Db;
-    provider: NullProvider;
+    /** Recording wrapper around the configured provider. */
+    provider: RecordingProvider;
     adapter: ContactAdapter;
     memoryAdapter: MemoryContactAdapter | null;
+    /** The runner context, for passing to `runTick` / `processOneRunStep` / `drain`. */
+    ctx: RunnerContext;
+    /** Insert a contact into the adapter and (by default) subscribe it. */
+    seedContact: (contact: Contact, opts?: SeedContactOptions) => Promise<Contact>;
+    /** Build + insert a published template. Returns the doc, `_id` included. */
+    seedTemplate: (spec: TemplateSpec) => Promise<TemplateDoc>;
+    /** Build + insert a published flow. Returns the doc, `_id` included. */
+    seedFlow: (spec: FlowSpec) => Promise<FlowDoc>;
+    /** Run the runner to quiescence. See `drive.ts`. */
+    drain: (opts?: DrainOptions) => Promise<DrainResult>;
     stop: () => Promise<void>;
 }
 declare function createTestMailer(opts?: TestMailerOptions): Promise<TestMailerHarness>;
 
-export { MemoryContactAdapter, NullProvider, type TestMailerHarness, type TestMailerOptions, createTestMailer };
+export { type DrainOptions, type DrainResult, type FlowSpec, MemoryContactAdapter, type ProviderSpec, RecordingProvider, type SeedContactOptions, type SendRecord, type TemplateSpec, type TestMailerHarness, type TestMailerOptions, buildFlow, buildTemplate, createTestMailer, dispatchQueued, drain, step, wrapMjml };

package/dist/testing.d.ts

@@ -1,5 +1,6 @@
 import { Db } from 'mongodb';
-import { C as ContactAdapter, a as Contact, A as AdapterFilter, d as Mailer, s as NullProvider } from './null-B0rPgE5_.js';
+import { C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, N as NormalizedEvent, F as FlowStep, a2 as FlowTrigger, m as FlowGoal, U as TemplateKind, T as TemplateDoc, l as FlowDoc, D as DeliveryWindow, R as RunnerContext, d as Mailer, a3 as QueueDriverConfig } from './null-BCxlHRJ0.js';
+export { s as NullProvider } from './null-BCxlHRJ0.js';
 import 'zod';
 import 'handlebars';
 import 'ioredis';
@@ -29,36 +30,255 @@ declare class MemoryContactAdapter implements ContactAdapter {
     removeTags(externalId: string, tags: string[]): Promise<void>;
 }
 
+/**
+ * RecordingProvider — a `MailProvider` decorator that records every send and
+ * then delegates to whatever it wraps.
+ *
+ * This is what lets one test suite run against two very different backends.
+ * Wrapping `NullProvider` gives fast, offline, deterministic assertions;
+ * wrapping `SendGridProvider` makes the *same* assertions run against the real
+ * API, with real auth, real payload validation and (outside sandbox mode) real
+ * delivery. Tests assert on the recording either way, so nothing is duplicated
+ * between the two tiers.
+ *
+ *   const provider = new RecordingProvider(new NullProvider())
+ *   ...
+ *   expect(provider.sent[0]?.subject).toContain('Alice')     // SendArgs
+ *   expect(provider.records[0]?.result?.status).toBe('accepted')
+ *
+ * `sent` is deliberately a bare `SendArgs[]`, matching `NullProvider.sent`, so
+ * this drops in wherever the old harness provider was used. `records` carries
+ * the richer per-call detail (result, error, duration) that the live tier needs.
+ */
+
+interface SendRecord {
+    args: SendArgs;
+    /** Provider result, or null when the call threw. */
+    result: SendResult | null;
+    /** Error thrown by the wrapped provider, or null on success. */
+    error: Error | null;
+    /** Wall-clock ms the wrapped `send` took. Meaningful for the live tier. */
+    durationMs: number;
+    at: Date;
+}
+declare class RecordingProvider implements MailProvider {
+    readonly inner: MailProvider;
+    /** Every `SendArgs` handed to the provider, in call order. */
+    readonly sent: SendArgs[];
+    /** Same calls, with outcome attached. */
+    readonly records: SendRecord[];
+    constructor(inner: MailProvider);
+    get name(): string;
+    get sendRatePerSecond(): number | undefined;
+    send(args: SendArgs): Promise<SendResult>;
+    verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
+    parseWebhookEvents(payload: unknown, headers: Record<string, string>): NormalizedEvent[];
+    /** Last recorded send, or undefined. Sugar for the common single-send assertion. */
+    get last(): SendArgs | undefined;
+    /** All sends addressed to `email` (case-insensitive). */
+    toRecipient(email: string): SendArgs[];
+    reset(): void;
+}
+
+/**
+ * Document builders for tests. Hand-rolling a full `TemplateDoc` / `FlowDoc`
+ * literal is ~40 lines of noise per fixture; these fill every required field
+ * with a sane default so a test only states what it is actually asserting on.
+ *
+ *   await H.seedTemplate({ slug: 'welcome', subject: 'Hi {{contact.fields.firstName}}' })
+ *   await H.seedFlow({ slug: 'onboarding', eventName: 'Created', steps: [...] })
+ *
+ * `createdAt` defaults to a minute in the past: the event-trigger scan uses
+ * `lastTriggerScanAt ?? createdAt` as its watermark and only picks up events
+ * with `occurredAt > watermark`, so a flow created at the same instant as the
+ * event it should catch would never fire.
+ */
+
+interface TemplateSpec {
+    slug: string;
+    name?: string;
+    description?: string;
+    kind?: TemplateKind;
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string | null;
+    providerOverride?: string | null;
+    subject?: string;
+    preheader?: string;
+    /** MJML source — compiled to html + derived plain text. */
+    mjml?: string;
+    /** Pre-compiled HTML. Wins over `mjml`. */
+    html?: string;
+    /**
+     * Body copy wrapped in a minimal MJML document. The lazy path — use when the
+     * test cares about the rendered *content*, not the markup around it.
+     */
+    text?: string;
+    /** Explicit plain-text part. Omit to auto-derive from the HTML. */
+    plainText?: string;
+    variablesSchema?: TemplateDoc['variablesSchema'];
+    tags?: string[];
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    published?: boolean;
+    createdAt?: Date;
+}
+declare function buildTemplate(spec: TemplateSpec): Promise<TemplateDoc>;
+/** Minimal valid MJML document around a body string. */
+declare function wrapMjml(body: string): string;
+interface FlowSpec {
+    slug: string;
+    name?: string;
+    description?: string;
+    steps: FlowStep[];
+    /** Shorthand for an `event` trigger. Ignored when `trigger` is given. */
+    eventName?: string;
+    /** Re-entry policy for the shorthand trigger. Defaults to true (enter once). */
+    once?: boolean;
+    trigger?: FlowTrigger;
+    enabled?: boolean;
+    goal?: FlowGoal;
+    audience?: string;
+    version?: number;
+    createdAt?: Date;
+}
+declare function buildFlow(spec: FlowSpec): FlowDoc;
+declare const step: {
+    readonly send: (templateSlug: string, opts?: Omit<Extract<FlowStep, {
+        type: "send";
+    }>, "type" | "templateSlug">) => FlowStep;
+    readonly sendAt: (templateSlug: string, delivery: DeliveryWindow) => FlowStep;
+    readonly wait: (value: number, unit?: "minutes" | "hours" | "days" | "weeks") => FlowStep;
+    readonly tag: (addTags?: string[], removeTags?: string[]) => FlowStep;
+    readonly exit: (reason?: string) => FlowStep;
+    readonly fireEvent: (eventName: string, properties?: Record<string, unknown>) => FlowStep;
+};
+
+/**
+ * Deterministic runner driver.
+ *
+ * The test harness uses the `noop` queue driver: `queue.add()` throws nothing
+ * away quietly but nothing ever fires it either, so the runner only moves when
+ * a test tells it to. `drain` is that push — it alternates the trigger scan,
+ * the due-run sweep and send dispatch until the system is quiescent, which is
+ * what a real deployment converges to between ticks.
+ *
+ *   await H.mailer.fire('Created', 'u1')
+ *   await drain(H.mailer.getRunnerContext())
+ *   expect(H.provider.sent).toHaveLength(1)
+ *
+ * "Quiescent" means: no active flow_run whose `nextActionAt` has passed, and
+ * no queued send left to dispatch. Runs parked in a `wait` step or deferred by
+ * a delivery window are *expected* to remain — move the clock forward and
+ * drain again.
+ */
+
+interface DrainOptions {
+    /**
+     * Safety valve. Each round advances every due run by exactly one step, so a
+     * flow needs one round per step. Hitting the cap means the system did not
+     * converge — `settled` comes back false rather than throwing, so a test can
+     * assert on non-convergence deliberately.
+     */
+    maxRounds?: number;
+    /** Skip send dispatch to inspect `queued` send rows before they go out. */
+    dispatch?: boolean;
+    /**
+     * Let provider/render errors propagate. Off by default: `dispatchSend`
+     * rethrows so the real queue can retry, and a drain that unwound on the
+     * first failure could not assert on the failed send row it just wrote.
+     */
+    throwOnSendError?: boolean;
+}
+interface DrainResult {
+    rounds: number;
+    /** Sends passed to `dispatchSend`. Not all of them reached the provider. */
+    dispatched: number;
+    /** Errors thrown by `dispatchSend`, swallowed unless `throwOnSendError`. */
+    errors: Error[];
+    settled: boolean;
+}
+declare function drain(ctx: RunnerContext, opts?: DrainOptions): Promise<DrainResult>;
+/**
+ * Dispatch every currently-queued send, once. Use when a test drove the flow
+ * with `drain({ dispatch: false })` and wants to inspect the queued rows first.
+ */
+declare function dispatchQueued(ctx: RunnerContext): Promise<number>;
+
 /**
  * Test helpers — `import { ... } from 'mailery/testing'`.
  *
- *   const harness = await createTestMailer({ seedContacts: [...] })
- *   await harness.mailer.upsertSubscription({ externalId: 'u1', source: 'test' })
- *   await harness.mailer.fire('Created', 'u1')
- *   // drive the runner directly:
- *   const { runTick, processOneRunStep, dispatchSend } = await import('mailery')
- *   await runTick(harness.mailer.getRunnerContext())
- *   expect(harness.provider.sent.length).toBe(1)
- *   await harness.stop()
+ *   const H = await createTestMailer({
+ *     seedContacts: [{ externalId: 'u1', email: 'alice@example.com', tags: [], fields: {} }],
+ *   })
+ *   await H.seedContact({ externalId: 'u1', ... })          // adapter + subscription
+ *   await H.seedTemplate({ slug: 'welcome', subject: 'Hi {{contact.fields.firstName}}' })
+ *   await H.seedFlow({ slug: 'onboarding', eventName: 'Created', steps: [step.send('welcome')] })
+ *
+ *   H.mailer.registerEvent({ name: 'Created', dedupePolicy: 'once-per-contact' })
+ *   await H.mailer.fire('Created', 'u1')
+ *   await H.drain()                                          // run to quiescence
  *
- * Backed by mongodb-memory-server + ioredis-mock + NullProvider.
+ *   expect(H.provider.sent).toHaveLength(1)
+ *   await H.stop()
+ *
+ * Backed by mongodb-memory-server + the `noop` queue driver, so nothing runs in
+ * the background and every transition is something the test asked for. The
+ * provider is always wrapped in a `RecordingProvider`, which is what allows the
+ * same suite to run against `NullProvider` offline or against real SendGrid
+ * (`provider: 'sendgrid'`) without changing a single assertion.
  */
 
+/**
+ * Which provider the harness sends through.
+ *  - `'null'`      — in-memory, offline, the default.
+ *  - `'sendgrid'`  — the real API. Needs `SENDGRID_API_KEY`. Sandbox mode
+ *                    unless `MAILERY_LIVE_E2E=deliver`, so the default costs
+ *                    nothing and delivers nothing while still proving that
+ *                    SendGrid accepts the payload.
+ *  - a `MailProvider` instance — anything else you want to record around.
+ */
+type ProviderSpec = 'null' | 'sendgrid' | MailProvider;
 interface TestMailerOptions {
     adapter?: ContactAdapter;
     seedContacts?: Contact[];
-    provider?: NullProvider;
+    provider?: ProviderSpec;
+    /**
+     * Queue driver. Defaults to `noop`, which is what makes the fast matrix
+     * deterministic — nothing runs until a test calls `drain()`. The live tier
+     * passes a real `bull` config to exercise job delays, retries and the send
+     * rate limiter, and must then also set `startWorkers`.
+     */
+    queue?: QueueDriverConfig;
+    /** Call `mailer.startWorkers()` after init. Requires a non-noop `queue`. */
+    startWorkers?: boolean;
     /** Override Mailer config (excluding required fields the harness fills in). */
     config?: Partial<Omit<Parameters<typeof Mailer.init>[0], 'db' | 'adapter' | 'queue' | 'providers' | 'defaultProvider'>>;
 }
+interface SeedContactOptions {
+    /** Also create a `subscribed` subscription row. Default true. */
+    subscribe?: boolean;
+    source?: string;
+}
 interface TestMailerHarness {
     mailer: Mailer;
     db: Db;
-    provider: NullProvider;
+    /** Recording wrapper around the configured provider. */
+    provider: RecordingProvider;
     adapter: ContactAdapter;
     memoryAdapter: MemoryContactAdapter | null;
+    /** The runner context, for passing to `runTick` / `processOneRunStep` / `drain`. */
+    ctx: RunnerContext;
+    /** Insert a contact into the adapter and (by default) subscribe it. */
+    seedContact: (contact: Contact, opts?: SeedContactOptions) => Promise<Contact>;
+    /** Build + insert a published template. Returns the doc, `_id` included. */
+    seedTemplate: (spec: TemplateSpec) => Promise<TemplateDoc>;
+    /** Build + insert a published flow. Returns the doc, `_id` included. */
+    seedFlow: (spec: FlowSpec) => Promise<FlowDoc>;
+    /** Run the runner to quiescence. See `drive.ts`. */
+    drain: (opts?: DrainOptions) => Promise<DrainResult>;
     stop: () => Promise<void>;
 }
 declare function createTestMailer(opts?: TestMailerOptions): Promise<TestMailerHarness>;
 
-export { MemoryContactAdapter, NullProvider, type TestMailerHarness, type TestMailerOptions, createTestMailer };
+export { type DrainOptions, type DrainResult, type FlowSpec, MemoryContactAdapter, type ProviderSpec, RecordingProvider, type SeedContactOptions, type SendRecord, type TemplateSpec, type TestMailerHarness, type TestMailerOptions, buildFlow, buildTemplate, createTestMailer, dispatchQueued, drain, step, wrapMjml };