mailery 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, c as MailTesterFeedback, d as Mailer, T as TemplateDoc, e as SuppressionScope, D as DeliveryWindow, F as FlowStep, f as SegmentFilter, P as Predicate } from './null-DDg3ojHe.js';
-export { g as AuditLogDoc, B as BroadcastDoc, h as BroadcastStatus, i as CircuitBreakerThresholds, j as Collections, k as ContactTagDoc, E as EventDoc, l as FlowDoc, m as FlowGoal, n as FlowRunDoc, o as FlowRunStatus, p as FlowVersionDoc, H as HealthDoc, q as HealthStatus, L as LeadDoc, r as MailerConfig, s as NullProvider, O as OutboxDoc, t as RESERVED_VAR_KEYS, u as RedisOptions, v as SegmentDefinition, w as SendDoc, x as SendStatus, y as SenderDomainConfig, z as SenderDomainRegistry, G as SenderDomainValidation, I as SubscriptionDoc, J as SubscriptionStatus, K as SuppressionDoc, Q as SuppressionReason, U as TemplateKind, V as TemplateVersionDoc, W as VarsAdapter, X as VarsResolveInfo, Y as WebhookEventDoc, Z as defineVars, _ as ensureIndexes, $ as getCollections, a0 as validateSenderDomain, a1 as varsJsonSchema } from './null-DDg3ojHe.js';
+import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, c as MailTesterFeedback, d as Mailer, T as TemplateDoc, F as FlowStep, e as Collections, f as FlowDoc, g as SuppressionScope, D as DeliveryWindow, h as SegmentFilter, P as Predicate } from './null-CDlseQxO.js';
+export { i as AuditLogDoc, B as BotFilterConfig, j as BroadcastDoc, k as BroadcastStatus, l as CircuitBreakerThresholds, m as ContactTagDoc, E as EventDoc, n as FlowGoal, o as FlowRunDoc, p as FlowRunStatus, q as FlowVersionDoc, H as HealthDoc, r as HealthStatus, L as LeadDoc, s as MailerConfig, t as NullProvider, O as OutboxDoc, u as RESERVED_VAR_KEYS, v as RedisOptions, w as SegmentDefinition, x as SendDoc, y as SendStatus, z as SenderDomainConfig, G as SenderDomainRegistry, I as SenderDomainValidation, J as SubscriptionDoc, K as SubscriptionStatus, Q as SuppressionDoc, U as SuppressionReason, V as TemplateKind, W as TemplateVersionDoc, X as VarsAdapter, Y as VarsResolveInfo, Z as WebhookEventDoc, _ as defineVars, $ as ensureIndexes, a0 as getCollections, a1 as validateSenderDomain, a2 as varsJsonSchema } from './null-CDlseQxO.js';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';
@@ -54,6 +54,67 @@ declare function sweepStrandedFlowRuns(ctx: RunnerContext): Promise<void>;
 
 declare function applyWebhookEvent(event: NormalizedEvent, ctx: RunnerContext): Promise<void>;
 
+/**
+ * The pending-unsubscribe drain — the second half of INVARIANT 8.
+ *
+ * `POST /m/unsub/:token` journals an opt-out to disk when Mongo is unreachable
+ * (`src/server/unsub-journal.ts`). This replays those entries. It runs from
+ * `runTick`, so it needs no scheduling of its own and inherits the tick's
+ * cadence (`tickIntervalSeconds`, default 60) and its per-runner error
+ * isolation. It is also exported so a host can run it from a script or a
+ * one-shot process.
+ *
+ * ## Where the drain runs, and why only here
+ *
+ * The tick, not a CLI command. `src/cli/` is a DNS/provider setup tool: it has
+ * no Mongo connection, no contact adapter and no config loader, so a
+ * `mailery drain-unsubs` command would have to invent a whole configuration
+ * story to reach the database. Every deployment that can journal an opt-out is
+ * by definition already running the library, and most run the tick;
+ * `drainPendingUnsubscribes` is exported for the ones that don't.
+ *
+ * ## Guarantees
+ *
+ * - **Idempotent.** Replay goes through `applyUnsubscribe`, whose suppression
+ *   write is a `$setOnInsert` upsert and whose subscription write is a `$set`
+ *   to a terminal state. Draining the same entry twice is indistinguishable
+ *   from draining it once.
+ * - **Nothing is lost to a crash.** A pass claims a batch by renaming the
+ *   journal aside; if it dies, the claim file stays on disk and a later pass
+ *   adopts it. Entries it could not apply are appended back to the live
+ *   journal *before* the claim is unlinked, so the failure window duplicates
+ *   rather than drops.
+ * - **Concurrency-safe.** Claiming and adopting are `rename`, which is atomic
+ *   within a directory. Two processes draining the same journal cannot both
+ *   own the same batch.
+ * - **Fails soft.** A Mongo write failure aborts the pass immediately — the
+ *   database being down is exactly why these entries exist, and hammering it
+ *   with the rest of the batch achieves nothing.
+ */
+
+interface DrainPendingUnsubsResult {
+    /** False when no `pendingUnsubsPath` is configured — the journal is opt-in. */
+    enabled: boolean;
+    applied: number;
+    /** Entries handed back to the journal for a later pass. */
+    deferred: number;
+    /** Lines that could never be applied (torn by a crash, or hand-edited). */
+    malformed: number;
+    /** Claim files processed, including ones adopted from a dead pass. */
+    batches: number;
+}
+interface DrainPendingUnsubsOptions {
+    /** Overrides `config.pendingUnsubsPath`. Mostly for tests. */
+    path?: string;
+    maxEntries?: number;
+    /** Structured sink for diagnostics. Defaults to `console`. */
+    log?: {
+        warn?: (fields: Record<string, unknown>, msg?: string) => void;
+        error?: (fields: Record<string, unknown>, msg?: string) => void;
+    };
+}
+declare function drainPendingUnsubscribes(ctx: RunnerContext, opts?: DrainPendingUnsubsOptions): Promise<DrainPendingUnsubsResult>;
+
 /**
  * MongoContactAdapter — reads contacts directly from the host's `users`
  * collection (read-mostly; optional narrow tag writes). Mailer never
@@ -109,6 +170,12 @@ declare class MongoContactAdapter implements ContactAdapter {
     private removeTagsImpl;
 }
 
+/**
+ * Per-provider tolerance option: seconds, or `0` / `false` to disable the
+ * freshness check entirely.
+ */
+type WebhookToleranceOption = number | false;
+
 /**
  * SendGridProvider — sends mail through @sendgrid/mail, verifies the Event
  * Webhook signature with the ECDSA public key configured in SendGrid, and
@@ -125,6 +192,16 @@ interface SendGridProviderOptions {
     apiKey: string;
     /** ECDSA public key (PEM) from SendGrid → Settings → Mail Settings → Signed Event Webhook. */
     webhookVerificationKey?: string;
+    /**
+     * Replay window for the signed webhook timestamp, in seconds.
+     * Defaults to 300 (5 minutes). A signed payload older — or more than this
+     * far in the future — than the window is rejected, so a captured request
+     * can't be replayed indefinitely.
+     *
+     * Set `0` or `false` to disable the check, for hosts whose proxy or queue
+     * legitimately delays webhook delivery past the window.
+     */
+    webhookToleranceSeconds?: WebhookToleranceOption;
     /** Send-rate cap per second (BullMQ group limiter consults this). */
     sendRatePerSecond?: number;
     /** Sandbox mode bypasses actual delivery — useful in dev/test. */
@@ -134,6 +211,8 @@ declare class SendGridProvider implements MailProvider {
     private readonly opts;
     readonly name = "sendgrid";
     readonly sendRatePerSecond: number;
+    /** Resolved replay window in seconds; `0` means the check is disabled. */
+    readonly webhookToleranceSeconds: number;
     constructor(opts: SendGridProviderOptions);
     send(args: SendArgs): Promise<SendResult>;
     verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
@@ -192,29 +271,60 @@ interface AdminRouterOptions {
     mailTesterClient?: MailTesterClient;
 }
 declare function createAdminRouter(mailer: Mailer, opts?: AdminRouterOptions): Router;
+/**
+ * The JSON API alone, without the SPA shell or the static assets. Exported
+ * so `createAgentRouter` can offer the same endpoints under bearer-token
+ * auth; hosts mounting the SPA should keep using `createAdminRouter`.
+ *
+ * Expects `(req as any).actor` to be set by whatever sits in front of it.
+ */
+declare function createAdminApiRouter(mailer: Mailer, opts?: AdminRouterOptions): Router;
 
 /**
- * Public router — endpoints that must be reachable by email clients and
- * provider webhooks. Mount under your tracking base path (default `/m`).
+ * Async handler wrapper for the *public* router.
  *
- *   app.use('/m', createPublicRouter(mailer))
+ * The admin router's `asyncHandler` (`api/admin.ts`) is a plain `.catch(next)`,
+ * which is right there: every admin handler computes first and responds last, so
+ * a rejection always arrives before any header is written and Express can turn
+ * it into a clean JSON 500.
  *
- * Routes:
- *   GET  /open/:sendId.png         — open pixel (records open, returns 1×1 PNG)
- *   GET  /click/:sendId/:linkId    — click redirect (records click, 302 → target)
- *   GET  /unsub/:token             — confirmation page (one-click POST link)
- *   POST /unsub/:token             — RFC 8058 one-click unsubscribe
- *   POST /webhooks/:provider       — inbound provider event webhook
+ * The public router cannot use that. `/open`, `/click` and `/webhooks` respond
+ * *first* and do their work after — never make a mail client or a provider
+ * wait on our database. By the time those handlers can reject,
+ * `res.headersSent` is already true, and forwarding post-headers makes Express
+ * destroy the socket underneath a response the client has already been
+ * promised.
+ *
+ * (`POST /unsub` used to be in that list. It now awaits its write before
+ * answering, because a response sent first can only ever report success —
+ * see INVARIANT 8 and the route's own comment. It still needs this wrapper for
+ * the pre-headers branch.)
+ *
+ * So this is a log-and-swallow wrapper, ported from featureboard's
+ * `src/server/routes/wrap.js`, with one deliberate difference: featureboard
+ * forwards with `next(err)` on the `headersSent` branch, and here that branch
+ * only logs. See issue #5 — every public route is unauthenticated, and the
+ * failure mode being fixed is precisely "a rejected promise in a public route
+ * takes down the host process".
  */
 
-interface PublicRouterOptions {
+/**
+ * Minimal structured-logger shape, compatible with pino/bunyan-style loggers
+ * (`logger.error(fields, message)`). Every method is optional, so `{}` is a
+ * valid silent logger and a bare `console` is not accidentally accepted with
+ * mismatched argument order.
+ */
+interface RouteLogger {
+    error?: (fields: Record<string, unknown>, msg?: string) => void;
+    warn?: (fields: Record<string, unknown>, msg?: string) => void;
     /**
-     * Path on disk where unsubscribe events fall back to when Mongo is degraded.
-     * Defaults to /tmp/mailery-pending-unsubs.jsonl.
+     * Routine, high-volume telemetry — currently only "an unsigned (pre-signing)
+     * tracking URL was accepted in grace mode", which is one line per legacy open
+     * and is not a fault. Kept off `warn` deliberately so it can be routed or
+     * dropped separately from things that are.
      */
-    pendingUnsubsPath?: string;
+    info?: (fields: Record<string, unknown>, msg?: string) => void;
 }
-declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions): Router;
 
 /**
  * Template render pipeline.
@@ -295,6 +405,16 @@ interface TrackingOptions {
     trackClicks: boolean;
     /** URL that must NOT be rewritten (e.g. the resolved unsubscribe URL). */
     preserveUrls?: string[];
+    /**
+     * HMAC key for tracking-URL signatures — pass `config.unsubscribeSecret`.
+     *
+     * When set, every generated `/m/open` and `/m/click` URL carries a truncated
+     * HMAC so it cannot be forged or enumerated from a neighbouring ObjectId.
+     * When omitted the legacy unsigned shape is emitted; that path exists for
+     * preview/test renders that never reach the tracking endpoints, not as a
+     * supported production mode.
+     */
+    signingSecret?: string;
 }
 interface TrackingResult {
     html: string;
@@ -305,12 +425,481 @@ interface TrackingResult {
     }>;
 }
 /**
- * Rewrite `<a href>` in `html` to /m/click/<sendId>/<linkId>?... and append an
- * open pixel. Returns the modified HTML plus the link map to persist on the
- * send document.
+ * Rewrite `<a href>` in `html` to /m/click/<sendId>/<linkId>/<sig> and append
+ * an open pixel at /m/open/<sendId>.<sig>.png. Returns the modified HTML plus
+ * the link map to persist on the send document.
+ *
+ * The `<sig>` components are 12-character truncated HMACs (see
+ * `signTrackingToken`) and are present whenever `opts.signingSecret` is set.
+ * Without them a Mongo ObjectId is the only thing standing between an attacker
+ * and a forged open — and ObjectIds are a timestamp plus a per-process counter,
+ * so one received email hands out its neighbours.
  */
 declare function applyTracking(html: string, opts: TrackingOptions): TrackingResult;
 
+/**
+ * Agent router — the mailery surface for automation.
+ *
+ * Everything an operator does by hand in the admin SPA to take an email
+ * program from "deployed" to "safely on" — render a template as a real
+ * contact and check it, send it through the real pipeline and watch delivery,
+ * ask what a flow would do to a contact, walk a canary run step by step,
+ * gate and arm a flow — is reachable here as JSON, behind a bearer token,
+ * with no browser session. It is built for an AI agent or a CI job to drive,
+ * which shapes three things:
+ *
+ *   - Every answer is structured. A verification is a list of named checks
+ *     with pass/warn/fail, not a rendered page to squint at.
+ *   - Every operation that could touch a real person is guarded by the
+ *     `testContacts` pattern: test sends, event firing, run stepping and
+ *     resets only apply to contacts whose email matches it. A router with no
+ *     pattern configured refuses those routes outright rather than assuming.
+ *   - Nothing here can enable a flow without stamping its trigger watermark
+ *     (see runner/arm.ts), so an agent cannot replay a month of signups.
+ *
+ * Mount it beside the admin router, on a path the host's session middleware
+ * does not cover, and give it the same JSON body the SPA would:
+ *
+ *   app.use('/admin/mailer/agent', createAgentRouter(mailer, {
+ *     tokens: [{ token: process.env.MAILERY_AGENT_TOKEN!, actor: 'agent:claude' }],
+ *     testContacts: /^qa\+.*@example\.com$/i,
+ *   }))
+ *
+ * `GET /` describes every route so a client can discover the surface. The
+ * full admin JSON API (docs/reference/admin-api.md) is mounted under `/api`
+ * with the token's actor, so reads and existing operations need no second
+ * auth path.
+ */
+
+interface AgentToken {
+    /** The bearer token. At least 24 characters; generate it, never type it. */
+    token: string;
+    /** Audit actor recorded for everything done with this token, e.g. `agent:claude`. */
+    actor: string;
+}
+interface AgentRouterOptions {
+    /** Required. The router refuses to construct without at least one token. */
+    tokens: AgentToken[];
+    /**
+     * Which contacts may be test-sent to, stepped through flows, fired events
+     * for, or reset. A regular expression over the email address, or a
+     * predicate. Routes that need it answer 403 when it is not configured —
+     * the safe default for a surface an automated caller drives.
+     */
+    testContacts?: RegExp | ((email: string) => boolean);
+    /** Structured logger for failures. Defaults to console. */
+    logger?: RouteLogger;
+    /** Passed through to the admin JSON API (tests inject a stub). */
+    mailTesterClient?: AdminRouterOptions['mailTesterClient'];
+}
+declare const MIN_AGENT_TOKEN_LENGTH = 24;
+type Check = {
+    id: string;
+    status: 'pass' | 'warn' | 'fail';
+    detail?: unknown;
+};
+declare function createAgentRouter(mailer: Mailer, opts: AgentRouterOptions): Router;
+interface VerifyOptions {
+    eventProperties?: Record<string, unknown>;
+    vars?: Record<string, unknown>;
+    includeRendered?: boolean;
+    varsSchema?: Record<string, unknown> | null;
+}
+interface VerifyReport {
+    ok: boolean;
+    template: {
+        slug: string;
+        kind: TemplateDoc['kind'];
+        name: string;
+    };
+    contact: {
+        externalId: string;
+        email: string;
+    };
+    checks: Check[];
+    links: {
+        total: number;
+        sample: string[];
+    };
+    rendered: {
+        subject: string;
+        preheader: string;
+        htmlBytes: number;
+        textLength: number;
+        fromEmail: string;
+    } | {
+        subject: string;
+        preheader: string;
+        html: string;
+        plainText: string;
+        fromEmail: string;
+        fromName: string;
+        replyTo: string | null;
+    } | null;
+}
+declare function verifyTemplate(mailer: Mailer, tpl: TemplateDoc, contact: Contact, opts?: VerifyOptions): Promise<VerifyReport>;
+interface RenderForContactOptions {
+    reason: 'preview' | 'test';
+    eventProperties?: Record<string, unknown>;
+    vars?: Record<string, unknown>;
+}
+/**
+ * Render a published template for one real contact the way a send would:
+ * host vars resolved through the varsAdapter, the contact at the root, a
+ * genuinely signed unsubscribe URL. The one difference from a send is that
+ * no tracking is applied — nothing here is queued.
+ */
+declare function renderForContact(mailer: Mailer, tpl: TemplateDoc, contact: Contact, opts: RenderForContactOptions): Promise<{
+    rendered: RenderedTemplate;
+    resolved: Record<string, unknown>;
+    unsubscribeUrl: string;
+    /** The exact object the template was rendered against. */
+    context: Record<string, unknown>;
+}>;
+/**
+ * Every dotted path a Handlebars source references outside `#each`/`#with`
+ * blocks (whose paths are relative to the iterated item and cannot be
+ * resolved against the root context) and outside HTML comments. Helper
+ * names, literals, hash keys, `@data` variables and Handlebars comments are
+ * skipped.
+ */
+declare function referencedPaths(source: string, helperNames?: Iterable<string>): string[];
+
+/**
+ * Enabling a flow, done safely — and running it against test contacts only.
+ *
+ * The trigger scan starts from `flow.lastTriggerScanAt ?? flow.createdAt`
+ * (triggers.ts). A flow that has never been enabled has a null watermark, so a
+ * bare `enabled: true` replays every matching event since the flow document
+ * was created: every signup of the past month gets the welcome email in one
+ * tick, a week or more late. That is the single most dangerous write in the
+ * admin surface, and until 0.16 it was one click (publish, or resume).
+ *
+ * `armFlow` is the path that flips `enabled` on. It stamps the watermark
+ * (default: now) in the SAME update, reports how many events it is choosing
+ * to skip, and writes an audit row. `publish` and `resume` in the admin API
+ * go through `stampWatermarkIfNull` for the same guarantee.
+ *
+ * `gateFlow` publishes a canary version whose first step exits anyone
+ * without a tag, so the real runner can exercise the real steps in
+ * production against test contacts while every real contact enters and
+ * exits at step 0 with no send. `ungateFlow` restores the newest ungated
+ * version. Runs pin their version, so a contact mid-canary finishes on it.
+ */
+
+/** A typed failure the HTTP layer can map to a status code without guessing. */
+declare class FlowOperationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+interface ArmFlowOptions {
+    /** Audit actor, e.g. `agent:claude` or `human:jeff@example.com`. */
+    actor: string;
+    /**
+     * Watermark to stamp. Defaults to now, which means only events fired AFTER
+     * this call enter the flow. Pass an earlier instant only when you mean for
+     * the events after it to enter — the result says how many that is.
+     */
+    since?: Date;
+}
+interface ArmFlowResult {
+    slug: string;
+    version: number;
+    /** True when this call flipped `enabled` on. */
+    armed: boolean;
+    /** True when the flow was already enabled; nothing was written. */
+    alreadyEnabled: boolean;
+    /** The watermark now on the flow. */
+    watermark: Date | null;
+    eventName: string | null;
+    /** Events for the trigger name that fired before the watermark and will never enter. */
+    skippedEvents: number;
+    /**
+     * Events that WILL enter on the next tick: everything after the watermark,
+     * plus anything created inside the scanner's 30-second overlap window just
+     * before it.
+     */
+    pendingEvents: number;
+}
+/**
+ * Stamp `lastTriggerScanAt` when it is null. Used by every code path that
+ * turns `enabled` on so a first enable never replays history. A flow that
+ * has scanned before keeps its watermark: pausing and resuming deliberately
+ * lets the events fired during the pause enter.
+ */
+declare function stampWatermarkIfNull(collections: Collections, flow: FlowDoc, now?: Date): Promise<Date | null>;
+declare function armFlow(mailer: Mailer, slug: string, opts: ArmFlowOptions): Promise<ArmFlowResult>;
+/** The inverse: `enabled: false`. In-flight runs continue (that is what pause means). */
+declare function disarmFlow(mailer: Mailer, slug: string, actor: string): Promise<{
+    slug: string;
+    disarmed: boolean;
+}>;
+/**
+ * The gate step. `canaryGate` is a marker the runner ignores (it evaluates
+ * the condition like any other) and this module uses to recognise its own
+ * work when removing it.
+ */
+type CanaryGateStep = Extract<FlowStep, {
+    type: 'condition';
+}> & {
+    canaryGate: true;
+};
+declare function isCanaryGate(step: unknown): step is CanaryGateStep;
+interface GateFlowResult {
+    slug: string;
+    version: number;
+    tag: string;
+    enabled: boolean;
+}
+declare function gateFlow(mailer: Mailer, slug: string, opts: {
+    tag: string;
+    actor: string;
+}): Promise<GateFlowResult>;
+interface UngateFlowResult {
+    slug: string;
+    version: number;
+    /** The version whose steps were restored. */
+    restoredFrom: number;
+    enabled: boolean;
+}
+declare function ungateFlow(mailer: Mailer, slug: string, opts: {
+    actor: string;
+}): Promise<UngateFlowResult>;
+
+/**
+ * Flow simulation: "what would happen to this contact if the trigger fired
+ * now?" — answered by walking the published steps against the contact's real
+ * state (tags, fields, events, sends, subscription) with a virtual clock and
+ * WITHOUT writing anything.
+ *
+ * This is the dry run an operator wants before arming a flow: it shows the
+ * branch a contact takes, every gate's verdict, the sends and the wall-clock
+ * moment each would go out (waits and delivery windows applied), and where
+ * the run ends. It reads the same predicate evaluator the runner uses, so a
+ * gate that passes here passes in production — for the state as it is at the
+ * moment of the call. Events that would arrive during the run are of course
+ * not known, which is why `path[].at` is labelled a projection.
+ */
+
+interface SimulateOptions {
+    /** Virtual "now" the simulated run enters at. Defaults to the real now. */
+    at?: Date;
+    /** Properties of the simulated trigger event ({{event.*}}, triggerProperty* predicates). */
+    eventProperties?: Record<string, unknown>;
+    /** Steps to walk. Defaults to the flow's live steps. */
+    steps?: FlowStep[];
+}
+interface SimulatedStep {
+    /** Projected wall-clock moment the step is reached. */
+    at: Date;
+    stepIndex: number;
+    branchPath: Array<number | 'true' | 'false'>;
+    type: FlowStep['type'];
+    outcome: 'waited' | 'passed' | 'skipped_next' | 'exited' | 'branch_true' | 'branch_false' | 'send' | 'send_deferred' | 'tagged' | 'event_fired' | 'webhook' | 'completed';
+    detail?: Record<string, unknown>;
+}
+interface SimulationResult {
+    flow: {
+        slug: string;
+        version: number;
+        enabled: boolean;
+    };
+    contact: {
+        externalId: string;
+        email: string;
+    };
+    enteredAt: Date;
+    /** Whether the trigger scan would create a run at all, and why not. */
+    wouldEnter: {
+        ok: boolean;
+        reasons: string[];
+    };
+    path: SimulatedStep[];
+    sends: Array<{
+        templateSlug: string;
+        at: Date;
+        stepIndex: number;
+        branchPath: Array<number | 'true' | 'false'>;
+    }>;
+    terminal: {
+        kind: 'completed' | 'exited' | 'truncated';
+        reason: string;
+        at: Date;
+    };
+    /** Projected time from entry to the terminal step. */
+    durationMs: number;
+}
+declare function simulateFlow(flow: FlowDoc, contact: Contact, ctx: RunnerContext, opts?: SimulateOptions): Promise<SimulationResult>;
+
+/**
+ * Inbound DMARC aggregate-report webhook.
+ *
+ * DMARC RUA reports arrive as email. The usual way to turn that email into an
+ * HTTP request is SendGrid Inbound Parse, and until v0.15 the documented setup
+ * pointed Inbound Parse at `/admin/mailer/api/dmarc/upload` — a route behind
+ * the host's `requireAdmin` guard, which Inbound Parse cannot satisfy. So the
+ * documented setup either did not work, or worked because somebody removed the
+ * guard from an admin router. This route replaces that advice.
+ *
+ * ## Read this before enabling it
+ *
+ * **Inbound Parse does not sign its payloads.** The SendGrid *Event Webhook*
+ * does — see `providers/sendgrid.ts`, where signature verification and the
+ * replay window live — but Inbound Parse is a different product and offers no
+ * signature, no HMAC and no verifiable identity. There is nothing to verify.
+ *
+ * So this is, structurally, an unauthenticated file-accepting endpoint on a
+ * public router, and the design has to own that rather than dress it up:
+ *
+ * 1. **Off unless configured.** No `dmarcInbound.secret`, no route — not a
+ *    404 handler, no route registered at all. An endpoint like this appearing
+ *    on an upgrade because someone shipped a default would be indefensible.
+ * 2. **A shared secret, checked first.** The secret is compared with
+ *    `timingSafeEqual` before multer is allowed to read a single byte of the
+ *    body, so an unauthenticated caller cannot make us buffer 10MB.
+ * 3. **Hard size and count limits**, matching the admin upload's shape.
+ * 4. **A domain cross-check.** A report whose `<policy_published><domain>` is
+ *    not a domain this deployment sends from is rejected. If the secret leaks,
+ *    the attacker gets to inject rows about *your* domains, which is bounded
+ *    and visible, instead of arbitrary garbage.
+ * 5. **The existing parser.** `runner/dmarc.ts` already caps decompressed
+ *    bytes, validates declared-vs-actual sizes, checks compression ratio and
+ *    guards zip-slip. This route does not parse anything itself.
+ *
+ * ## Why a shared secret, and where it goes
+ *
+ * The three options that don't need a signature:
+ *
+ * - **Source IP allowlist.** Rejected as the primary control. SendGrid does
+ *   not publish a stable Inbound Parse egress range, and behind a proxy
+ *   `req.ip` is the proxy's address unless the host has set `trust proxy`
+ *   correctly — which this library cannot verify and must not assume. An
+ *   allowlist that silently matches the wrong address either locks out the
+ *   real sender or admits everyone. Put an allowlist in your ingress if you
+ *   want one; it is a good second layer and a bad only layer.
+ * - **Secret in the path.** Works, and is the fallback, but a URL path is
+ *   logged by every proxy, load balancer and access log between SendGrid and
+ *   you. Supported implicitly: nothing stops you making `path` unguessable.
+ * - **Secret in the `Authorization` header.** The default and the
+ *   recommendation. Inbound Parse cannot set custom headers, but its
+ *   destination URL accepts embedded basic-auth credentials
+ *   (`https://mailery:SECRET@example.com/m/inbound/dmarc`), which travel as an
+ *   `Authorization` header rather than in the request line. `Bearer` is
+ *   accepted too, for hosts forwarding from something other than SendGrid.
+ *
+ * A leaked secret gets an attacker exactly one capability: inserting DMARC
+ * report rows for domains you already send from. No mail is sent, no contact
+ * data is touched, nothing is deleted. Rotate it by changing the config value
+ * and the Inbound Parse destination URL.
+ */
+
+/** One attachment lifted off an inbound request by a `parseInbound` seam. */
+interface InboundAttachment {
+    filename: string;
+    buffer: Buffer;
+}
+/**
+ * Pull DMARC attachments out of a provider's inbound-email payload.
+ *
+ * The seam exists so Mailgun's and Postmark's inbound routes can be added
+ * without touching this route's auth, limits or ingest path. Only the SendGrid
+ * shape is implemented today.
+ */
+type InboundParser = (req: Request) => InboundAttachment[];
+interface DmarcInboundOptions {
+    /**
+     * Shared secret the caller must present. **Absent or empty → the route is
+     * not mounted at all.**
+     *
+     * Accepted as HTTP Basic (any username; the password is compared) or as
+     * `Authorization: Bearer <secret>`. Basic is the one to use with SendGrid
+     * Inbound Parse, since it can be embedded in the destination URL and so
+     * stays out of access logs.
+     */
+    secret?: string;
+    /** Sub-path on the public router. Default `/inbound/dmarc`. */
+    path?: string;
+    /** Per-file cap. Default 10MB, matching the admin upload. */
+    maxFileSizeBytes?: number;
+    /** Attachments accepted per request. Default 10. */
+    maxFiles?: number;
+    /**
+     * Domains whose reports are accepted. Defaults to every domain in
+     * `senderDomains` plus the `fromDefaults` / `transactionalFromDefaults`
+     * addresses. Reports for anything else are rejected.
+     *
+     * If none of those are configured there is nothing to check against, and the
+     * route mounts with the domain gate disabled and a warning — configure
+     * `senderDomains` to get it back.
+     */
+    allowedDomains?: string[];
+    /** Override the inbound payload shape. Defaults to SendGrid Inbound Parse. */
+    parseInbound?: InboundParser;
+}
+/**
+ * SendGrid Inbound Parse: `multipart/form-data` with the message's fields
+ * (`headers`, `from`, `subject`, `text`, ...) plus one file part per
+ * attachment, named `attachment1`, `attachment2`, and so on.
+ *
+ * Read through `multer.any()`, so the field names are not trusted — every file
+ * part is a candidate and the extension gate below decides.
+ */
+declare const sendgridInboundParser: InboundParser;
+
+/**
+ * Public router — endpoints that must be reachable by email clients and
+ * provider webhooks. Mount under your tracking base path (default `/m`).
+ *
+ *   app.use('/m', createPublicRouter(mailer))
+ *
+ * Routes:
+ *   GET  /open/:sendId.:sig.png        — open pixel (records open, returns 1×1 PNG)
+ *   GET  /click/:sendId/:linkId/:sig   — click redirect (records click, 302 → target)
+ *   GET  /unsub/:token                 — confirmation page (one-click POST link)
+ *   POST /unsub/:token                 — RFC 8058 one-click unsubscribe
+ *   POST /webhooks/:provider           — inbound provider event webhook
+ *   POST /inbound/dmarc                — inbound DMARC report (opt-in; see below)
+ *
+ * Every route here is unauthenticated by necessity — mail clients and provider
+ * webhook servers cannot present credentials. The one exception is
+ * `/inbound/dmarc`, which is **not mounted at all** unless a shared secret is
+ * configured; see `api/dmarc-inbound.ts`.
+ *
+ * `:sig` is a 12-character truncated HMAC issued by `applyTracking`. It is
+ * syntactically optional on both tracking routes so that mail delivered before
+ * signing existed keeps working — see `checkTrackingSignature`.
+ */
+
+interface PublicRouterOptions {
+    /**
+     * Overrides `MailerConfig.pendingUnsubsPath` for this router only.
+     *
+     * @deprecated Set `pendingUnsubsPath` in `MailerConfig` instead. The tick
+     * drain (`drainPendingUnsubscribes`) reads the *config* value, so a path set
+     * only here is written but never replayed — which is precisely the bug
+     * INVARIANT 8 was carrying. Setting it here without also setting it in
+     * config logs a warning at construction time.
+     */
+    pendingUnsubsPath?: string;
+    /**
+     * Structured logger for public-route failures, pino-style
+     * (`logger.error(fields, message)`).
+     *
+     * Defaults to a `console`-backed logger that reproduces the output this
+     * package emitted before the option existed. Pass `{}` to silence.
+     */
+    logger?: RouteLogger;
+    /**
+     * Inbound DMARC aggregate-report webhook (SendGrid Inbound Parse and
+     * friends). **Off unless `secret` is set** — see `api/dmarc-inbound.ts` for
+     * why an endpoint that accepts unsigned file uploads must never appear on an
+     * upgrade by itself.
+     */
+    dmarcInbound?: DmarcInboundOptions;
+}
+declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions): Router;
+
 /**
  * HMAC-signed tokens for unsubscribe + preference-center URLs.
  *
@@ -328,11 +917,71 @@ interface UnsubscribeTokenPayload {
 }
 declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
 declare function verifyUnsubscribeToken(token: string, secret: string, now?: Date): UnsubscribeTokenPayload | null;
+/**
+ * Scopes a tracking signature can be issued for. An allowlist, mirroring the
+ * `k: 'doi'` discriminator on the DOI token: the scope is part of the signed
+ * message, so an `/m/open` signature cannot be replayed as an `/m/click` one
+ * even for the same send.
+ */
+type TrackingScope = 'open' | 'click';
+/**
+ * Signature length in base64url characters. 12 chars = 72 bits of the
+ * HMAC-SHA256 digest.
+ *
+ * Truncation is deliberate. These signatures are embedded in every link of
+ * every email, and the pixel URL in particular is parsed by mail clients with
+ * their own length quirks, so bytes are not free. 72 bits is far beyond what an
+ * online forgery attack can reach: an attacker gets no oracle beyond "the open
+ * was counted", each guess is a live HTTP request, and there is no offline
+ * verification step. Nothing here is a bearer credential for anything except
+ * "this recipient was sent this mail".
+ */
+declare const TRACKING_SIG_LENGTH = 12;
+interface TrackingTokenParams {
+    sendId: string;
+    /** Present for `click` scope, absent for `open`. */
+    linkId?: string;
+}
+/**
+ * Sign a tracking URL. Returns `TRACKING_SIG_LENGTH` base64url characters.
+ *
+ * Keyed with `unsubscribeSecret` — the same secret the unsubscribe and DOI
+ * tokens use, so there is exactly one secret to provision
+ * (`MAILER_UNSUBSCRIBE_SECRET`) and one to rotate. The scope prefix keeps the
+ * key domains separate.
+ */
+declare function signTrackingToken(scope: TrackingScope, params: TrackingTokenParams, secret: string): string;
+/**
+ * Verify a tracking-URL signature in constant time.
+ *
+ * The length pre-check before `timingSafeEqual` is required, not defensive:
+ * `crypto.timingSafeEqual` throws on mismatched lengths, and a thrown
+ * verification is a rejection that leaks length through a different channel.
+ * Same shape as `verifyUnsubscribeToken`.
+ */
+declare function verifyTrackingToken(token: unknown, scope: TrackingScope, params: TrackingTokenParams, secret: string): boolean;
 /**
  * sha256 hex digest, used for storing email hashes (GDPR forget) and dedup helpers.
  */
 declare function sha256Hex(input: string): string;
 
+/**
+ * Predicate evaluator. Resolves all Predicate variants from `shared/types.ts`
+ * against a Contact (host-side fields/tags) + mailer state (events, sends,
+ * subscription).
+ *
+ * Network calls hit Mongo. Cache the Contact at the call site if you evaluate
+ * many predicates in a row.
+ */
+
+/**
+ * User agents treated as automated unless the host overrides
+ * `botFilter.userAgentPattern`. Deliberately short: these are the scanners that
+ * announce themselves. Anything that impersonates a browser is not catchable
+ * from the UA string and is out of scope here — see INVARIANT 7.
+ */
+declare const DEFAULT_BOT_UA_RE: RegExp;
+
 /**
  * Delivery-window math. Pure — no I/O, no Date.now(); callers pass `now`.
  *
@@ -404,4 +1053,4 @@ declare const DEDUPE_POLICIES: readonly DedupePolicyOption[];
  */
 declare const VERSION: string;
 
-export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, DEDUPE_POLICIES, type DedupePolicyOption, DeliveryWindow, FLOW_STEP_KINDS, FlowStep, type FlowStepKindOption, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, PREDICATE_KINDS, Predicate, type PredicateKind, type PredicateKindOption, type PublicRouterOptions, SEGMENT_FILTER_KINDS, SegmentFilter, type SegmentFilterKind, type SegmentFilterKindOption, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };
+export { AdapterFilter, type AdminRouterOptions, type AgentRouterOptions, type AgentToken, type ArmFlowOptions, type ArmFlowResult, Collections, Contact, ContactAdapter, DEDUPE_POLICIES, DEFAULT_BOT_UA_RE, type DedupePolicyOption, DeliveryWindow, type DmarcInboundOptions, type DrainPendingUnsubsOptions, type DrainPendingUnsubsResult, FLOW_STEP_KINDS, FlowDoc, FlowOperationError, FlowStep, type FlowStepKindOption, type GateFlowResult, type InboundAttachment, type InboundParser, MIN_AGENT_TOKEN_LENGTH, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, PREDICATE_KINDS, Predicate, type PredicateKind, type PredicateKindOption, type PublicRouterOptions, type RouteLogger, SEGMENT_FILTER_KINDS, SegmentFilter, type SegmentFilterKind, type SegmentFilterKindOption, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, type SimulateOptions, type SimulatedStep, type SimulationResult, SuppressionScope, TRACKING_SIG_LENGTH, TemplateDoc, type TrackingScope, type TrackingTokenParams, type UngateFlowResult, VERSION, type VerifyOptions, type VerifyReport, applyTracking, applyWebhookEvent, armFlow, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminApiRouter, createAdminRouter, createAgentRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, disarmFlow, dispatchSend, drainPendingUnsubscribes, gateFlow, isCanaryGate, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, referencedPaths, renderForContact, renderTemplate, runTick, sendgridInboundParser, sha256Hex, signTrackingToken, signUnsubscribeToken, simulateFlow, stampWatermarkIfNull, sweepStrandedFlowRuns, ungateFlow, verifyTemplate, verifyTrackingToken, verifyUnsubscribeToken };