mailery 0.15.0 → 0.16.1

package/dist/index.d.cts

@@ -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-CnhsvKvy.cjs';
-export { g as AuditLogDoc, B as BotFilterConfig, h as BroadcastDoc, i as BroadcastStatus, j as CircuitBreakerThresholds, k as Collections, l as ContactTagDoc, E as EventDoc, m as FlowDoc, 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-CnhsvKvy.cjs';
+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.cjs';
+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.cjs';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';
@@ -190,7 +190,15 @@ type WebhookToleranceOption = number | false;
 
 interface SendGridProviderOptions {
     apiKey: string;
-    /** ECDSA public key (PEM) from SendGrid → Settings → Mail Settings → Signed Event Webhook. */
+    /**
+     * ECDSA public key from SendGrid → Settings → Mail Settings → Signed Event
+     * Webhook. Either form SendGrid hands out is accepted: the single-line
+     * base64 string its dashboard shows and its API returns as `public_key`
+     * (what `mailery setup-sendgrid` prints), or the same key as a PEM block.
+     * A PEM whose newlines were escaped to `\n` for an .env line is unescaped.
+     * Anything that does not parse as a public key throws at construction —
+     * a key that silently verifies nothing is the failure this replaces.
+     */
     webhookVerificationKey?: string;
     /**
      * Replay window for the signed webhook timestamp, in seconds.
@@ -213,6 +221,8 @@ declare class SendGridProvider implements MailProvider {
     readonly sendRatePerSecond: number;
     /** Resolved replay window in seconds; `0` means the check is disabled. */
     readonly webhookToleranceSeconds: number;
+    /** The verification key as PEM, whatever shape it was configured in. */
+    private readonly verificationKeyPem;
     constructor(opts: SendGridProviderOptions);
     send(args: SendArgs): Promise<SendResult>;
     verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
@@ -271,6 +281,14 @@ 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;
 
 /**
  * Async handler wrapper for the *public* router.
@@ -318,6 +336,412 @@ interface RouteLogger {
     info?: (fields: Record<string, unknown>, msg?: string) => void;
 }
 
+/**
+ * Template render pipeline.
+ *
+ *  authorMjml + handlebarsContext
+ *     ↓ Handlebars render          → MJML with substituted vars
+ *     ↓ mjml-core compile          → HTML
+ *     ↓ html-to-text derive        → plain text alternative
+ *     ↓ applyTracking(sendId)      → tracked HTML with rewritten links + open pixel
+ *
+ * Subject and preheader run through Handlebars too. Plain text is auto-derived
+ * unless the template explicitly overrides it.
+ */
+
+interface CompileResult {
+    html: string;
+    plainText: string;
+    errors: Array<{
+        line?: number;
+        message: string;
+        tagName?: string;
+        formattedMessage?: string;
+    }>;
+}
+/** Compile MJML → HTML, then derive plain text. Called at template publish time. */
+declare function compileTemplate(mjml: string): Promise<CompileResult>;
+/**
+ * Compile Maily editor JSON (Tiptap-shape) → HTML via `@maily-to/render`, then
+ * derive plain text. Called at template publish time when the template was
+ * authored via the WYSIWYG editor.
+ */
+declare function compileMailyTemplate(content: unknown): Promise<CompileResult>;
+/** Auto-derive plain text from compiled HTML. */
+declare function derivePlaintext(html: string): string;
+interface RenderContext {
+    /**
+     * Host-resolved variables (varsAdapter) live at the context root, so a
+     * schema key `user` renders as `{{user.name}}`. Reserved keys below always
+     * win over resolved keys.
+     */
+    [resolvedVar: string]: unknown;
+    contact: Contact;
+    vars: Record<string, unknown>;
+    /** Properties of the event that triggered the flow run ({{event.*}}). Empty outside flow sends. */
+    event?: Record<string, unknown>;
+    /** URL the recipient hits to one-click unsubscribe. */
+    unsubscribeUrl: string;
+    /** URL to view this email in a browser (when implemented). */
+    viewInBrowserUrl?: string;
+    /** URL for the preference center (when implemented). */
+    preferenceCenterUrl?: string;
+    /** Configured sender postal address (CAN-SPAM). */
+    senderAddress?: string;
+}
+interface RenderedTemplate {
+    subject: string;
+    preheader: string;
+    html: string;
+    plainText: string;
+    fromName: string;
+    fromEmail: string;
+    replyTo: string | null;
+}
+interface RenderOptions {
+    /** Extra Handlebars helpers contributed by the host. */
+    helpers?: Record<string, Handlebars.HelperDelegate>;
+}
+/**
+ * Render a published template against a contact + vars context. Returns the
+ * substituted subject/preheader/html/plainText. Tracking is NOT applied here —
+ * that step needs the send id and runs separately via `applyTracking`.
+ */
+declare function renderTemplate(template: TemplateDoc, ctx: RenderContext, opts?: RenderOptions): Promise<RenderedTemplate>;
+interface TrackingOptions {
+    sendId: string;
+    publicUrl: string;
+    trackOpens: boolean;
+    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;
+    /** linkId → original URL map; persist on `mailer_sends.links` for click resolution. */
+    links: Array<{
+        linkId: string;
+        url: string;
+    }>;
+}
+/**
+ * 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.
  *
@@ -486,117 +910,6 @@ interface PublicRouterOptions {
 }
 declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions): Router;
 
-/**
- * Template render pipeline.
- *
- *  authorMjml + handlebarsContext
- *     ↓ Handlebars render          → MJML with substituted vars
- *     ↓ mjml-core compile          → HTML
- *     ↓ html-to-text derive        → plain text alternative
- *     ↓ applyTracking(sendId)      → tracked HTML with rewritten links + open pixel
- *
- * Subject and preheader run through Handlebars too. Plain text is auto-derived
- * unless the template explicitly overrides it.
- */
-
-interface CompileResult {
-    html: string;
-    plainText: string;
-    errors: Array<{
-        line?: number;
-        message: string;
-        tagName?: string;
-        formattedMessage?: string;
-    }>;
-}
-/** Compile MJML → HTML, then derive plain text. Called at template publish time. */
-declare function compileTemplate(mjml: string): Promise<CompileResult>;
-/**
- * Compile Maily editor JSON (Tiptap-shape) → HTML via `@maily-to/render`, then
- * derive plain text. Called at template publish time when the template was
- * authored via the WYSIWYG editor.
- */
-declare function compileMailyTemplate(content: unknown): Promise<CompileResult>;
-/** Auto-derive plain text from compiled HTML. */
-declare function derivePlaintext(html: string): string;
-interface RenderContext {
-    /**
-     * Host-resolved variables (varsAdapter) live at the context root, so a
-     * schema key `user` renders as `{{user.name}}`. Reserved keys below always
-     * win over resolved keys.
-     */
-    [resolvedVar: string]: unknown;
-    contact: Contact;
-    vars: Record<string, unknown>;
-    /** Properties of the event that triggered the flow run ({{event.*}}). Empty outside flow sends. */
-    event?: Record<string, unknown>;
-    /** URL the recipient hits to one-click unsubscribe. */
-    unsubscribeUrl: string;
-    /** URL to view this email in a browser (when implemented). */
-    viewInBrowserUrl?: string;
-    /** URL for the preference center (when implemented). */
-    preferenceCenterUrl?: string;
-    /** Configured sender postal address (CAN-SPAM). */
-    senderAddress?: string;
-}
-interface RenderedTemplate {
-    subject: string;
-    preheader: string;
-    html: string;
-    plainText: string;
-    fromName: string;
-    fromEmail: string;
-    replyTo: string | null;
-}
-interface RenderOptions {
-    /** Extra Handlebars helpers contributed by the host. */
-    helpers?: Record<string, Handlebars.HelperDelegate>;
-}
-/**
- * Render a published template against a contact + vars context. Returns the
- * substituted subject/preheader/html/plainText. Tracking is NOT applied here —
- * that step needs the send id and runs separately via `applyTracking`.
- */
-declare function renderTemplate(template: TemplateDoc, ctx: RenderContext, opts?: RenderOptions): Promise<RenderedTemplate>;
-interface TrackingOptions {
-    sendId: string;
-    publicUrl: string;
-    trackOpens: boolean;
-    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;
-    /** linkId → original URL map; persist on `mailer_sends.links` for click resolution. */
-    links: Array<{
-        linkId: string;
-        url: string;
-    }>;
-}
-/**
- * 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;
-
 /**
  * HMAC-signed tokens for unsubscribe + preference-center URLs.
  *
@@ -750,4 +1063,4 @@ declare const DEDUPE_POLICIES: readonly DedupePolicyOption[];
  */
 declare const VERSION: string;
 
-export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, DEDUPE_POLICIES, DEFAULT_BOT_UA_RE, type DedupePolicyOption, DeliveryWindow, type DmarcInboundOptions, type DrainPendingUnsubsOptions, type DrainPendingUnsubsResult, FLOW_STEP_KINDS, FlowStep, type FlowStepKindOption, type InboundAttachment, type InboundParser, 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, SuppressionScope, TRACKING_SIG_LENGTH, TemplateDoc, type TrackingScope, type TrackingTokenParams, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, drainPendingUnsubscribes, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sendgridInboundParser, sha256Hex, signTrackingToken, signUnsubscribeToken, sweepStrandedFlowRuns, verifyTrackingToken, 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 };