mailery 0.14.0 → 0.16.0

package/dist/{null-DDg3ojHe.d.cts → null-CDlseQxO.d.cts}

@@ -661,6 +661,30 @@ interface CircuitBreakerThresholds {
     windowMinutes: number;
     minSendsBeforeEval: number;
 }
+interface BotFilterConfig {
+    /**
+     * User agents matching this pattern are treated as automated. Applied to
+     * recorded open and click user agents alike.
+     *
+     * Default: `/Mimecast|SafeLinks|proofpoint|HeadlessChrome|Googlebot|bingbot/i`
+     * (`DEFAULT_BOT_UA_RE`). Replace it to cover your own corporate scanners;
+     * extend rather than replace if you want to keep the built-ins.
+     */
+    userAgentPattern?: RegExp;
+    /**
+     * Opens recorded within this many milliseconds of the send being queued are
+     * treated as automated regardless of user agent — corporate scanners and
+     * gateway prefetchers fetch the pixel within seconds of delivery, and a
+     * human cannot.
+     *
+     * Default `0` — disabled. It is off by default because it is a heuristic
+     * with a real false-positive tail (a recipient already reading their inbox
+     * when the mail lands) and because enabling it silently changes the counts
+     * every existing flow branches on. `10000` (10s) is the value worth trying
+     * first if your open counts look implausible.
+     */
+    minOpenDelayMs?: number;
+}
 interface MailerConfig {
     db: Db;
     collectionPrefix?: string;
@@ -706,6 +730,40 @@ interface MailerConfig {
     requireDoubleOptIn?: boolean;
     unsubscribeTokenLifetimeDays?: number;
     transactionalRespectUnsubscribe?: boolean;
+    /**
+     * Absolute path to the pending-unsubscribe journal (INVARIANT 8).
+     *
+     * When `POST /m/unsub/:token` cannot reach Mongo, the opt-out is appended
+     * here as JSONL and replayed by the tick drain
+     * (`drainPendingUnsubscribes`). The file is created 0600 inside a 0700
+     * directory and opened `O_NOFOLLOW`.
+     *
+     * **There is no default, and that is deliberate.** The journal holds
+     * recipient email addresses in plaintext outside the database, and a library
+     * mounted into an unknown host cannot pick a directory that is at once
+     * writable, durable and private — which is how the previous default ended up
+     * being `/tmp` (world-writable, wiped on reboot, and never read back).
+     *
+     * With this unset the endpoint answers **503** when Mongo is unreachable,
+     * rather than promising an unsubscribe it has nowhere to record. Set it to a
+     * durable, private, node-local path to get the journal instead — e.g.
+     * `/var/lib/mailery/pending-unsubs.jsonl` (systemd: `StateDirectory=mailery`).
+     *
+     * Must not be on a shared network filesystem: claiming a batch relies on
+     * `rename` being atomic within the directory.
+     */
+    pendingUnsubsPath?: string;
+    /**
+     * How long `POST /m/unsub/:token` waits for the Mongo write before falling
+     * back to the journal. Default 5000ms.
+     *
+     * The tension is INVARIANT 8's own: the response must be fast (clients are
+     * impatient, providers retry) *and* must not claim an unsubscribe that was
+     * never recorded. A healthy write is sub-millisecond, so this budget is only
+     * ever spent during an outage, and spending it is what makes the difference
+     * between a truthful 200 and a lie.
+     */
+    unsubscribeWriteTimeoutMs?: number;
     /** Slug of the transactional template sent for DOI confirmation. Defaults to 'doi-confirmation'. */
     doiTemplateSlug?: string;
     /** How long the DOI token stays valid. Default 7 days. */
@@ -740,10 +798,18 @@ interface MailerConfig {
     mailTester?: MailTesterConfig;
     /**
      * DMARC RUA aggregate reports tell you who is sending mail that claims to
-     * be from your domain — both legitimate sources and spoofers. Operator
-     * uploads the report attachments (or POSTs them via SendGrid Inbound Parse
-     * to /admin/mailer/api/dmarc/upload). Mailery decompresses, parses, and
-     * surfaces alignment failures + unknown senders.
+     * be from your domain — both legitimate sources and spoofers. Mailery
+     * decompresses, parses, and surfaces alignment failures + unknown senders.
+     *
+     * Two ways in:
+     *   - the operator uploads attachments in the admin UI
+     *     (`POST /admin/mailer/api/dmarc/upload`, behind your admin guard)
+     *   - the inbound webhook, for SendGrid Inbound Parse and friends:
+     *     `createPublicRouter(mailer, { dmarcInbound: { secret } })`. Off unless
+     *     that secret is set. Do **not** point Inbound Parse at the admin
+     *     upload route — it sits behind the host's `requireAdmin` guard, which
+     *     Inbound Parse cannot satisfy. (Versions before 0.15 recommended
+     *     exactly that, and it never worked.)
      */
     dmarc?: DmarcConfig;
     broadcastConfirmationThreshold?: number;
@@ -761,6 +827,35 @@ interface MailerConfig {
     trackClicks?: boolean;
     storeTrackingIp?: boolean;
     storeRenderedBody?: boolean;
+    /**
+     * Reject `/m/open` and `/m/click` hits that carry no signature.
+     *
+     * Default `false` — grace mode. Newly rendered mail is always signed; this
+     * flag only decides what happens to the *unsigned* URLs sitting in mail that
+     * was already delivered. In grace mode they are still counted and each one is
+     * logged (`mailery: unsigned tracking URL accepted`) so the operator can watch
+     * the legacy rate fall to zero and then flip this to `true`.
+     *
+     * A signature that is *present but wrong* is always rejected, in both modes.
+     */
+    requireSignedTrackingUrls?: boolean;
+    /**
+     * How long a tracking URL stays valid, in days, measured from the send's
+     * `queuedAt`. Default `0` — never expires.
+     *
+     * Never-expire is the right default: an email sits in an inbox for years and
+     * a legitimate open six months later is real data, not an attack. The
+     * signature already proves the caller was handed the URL. Operators with a
+     * data-retention policy can set a window; because the deadline is derived
+     * from the send row rather than baked into the token, changing this value
+     * takes effect immediately for already-delivered mail and costs no URL bytes.
+     */
+    trackingUrlLifetimeDays?: number;
+    /**
+     * Tuning for `hasOpenedExcludingBots` / `hasClickedExcludingBots` /
+     * `openedAtLeastN` / `clickedAtLeastN`. See `BotFilterConfig`.
+     */
+    botFilter?: BotFilterConfig;
     getAdminActor?: (req: any) => string;
     onCircuitBreakerTrip?: (info: {
         reason: string;
@@ -772,7 +867,7 @@ interface MailerConfig {
     }) => Promise<void> | void;
     handlebarsHelpers?: Record<string, Handlebars.HelperDelegate>;
 }
-type ResolvedConfig = Required<Pick<MailerConfig, 'collectionPrefix' | 'requireDoubleOptIn' | 'unsubscribeTokenLifetimeDays' | 'transactionalRespectUnsubscribe' | 'doiTemplateSlug' | 'doiTokenLifetimeDays' | 'broadcastConfirmationThreshold' | 'broadcastEnqueueBatchSize' | 'broadcastEnqueueMaxWaiting' | 'workerless' | 'tickIntervalSeconds' | 'sendConcurrency' | 'sendRatePerSecond' | 'softBouncePromotionThreshold' | 'softBouncePromotionWindowDays' | 'webhookRetryAttempts' | 'sendRetryAttempts' | 'trackOpens' | 'trackClicks' | 'storeTrackingIp' | 'storeRenderedBody'>> & {
+type ResolvedConfig = Required<Pick<MailerConfig, 'collectionPrefix' | 'requireDoubleOptIn' | 'unsubscribeTokenLifetimeDays' | 'transactionalRespectUnsubscribe' | 'unsubscribeWriteTimeoutMs' | 'doiTemplateSlug' | 'doiTokenLifetimeDays' | 'broadcastConfirmationThreshold' | 'broadcastEnqueueBatchSize' | 'broadcastEnqueueMaxWaiting' | 'workerless' | 'tickIntervalSeconds' | 'sendConcurrency' | 'sendRatePerSecond' | 'softBouncePromotionThreshold' | 'softBouncePromotionWindowDays' | 'webhookRetryAttempts' | 'sendRetryAttempts' | 'trackOpens' | 'trackClicks' | 'storeTrackingIp' | 'storeRenderedBody' | 'requireSignedTrackingUrls' | 'trackingUrlLifetimeDays'>> & {
     circuitBreaker: CircuitBreakerThresholds;
 } & MailerConfig;
 
@@ -1017,6 +1112,19 @@ interface SendDoc {
     vars: Record<string, unknown>;
     openedAt: Date | null;
     openCount: number;
+    /**
+     * Per-open history, capped at the most recent `MAX_TRACKED_OPENS`. Exists so
+     * the bot filter (`hasOpenedExcludingBots`) has something to filter on —
+     * `openCount` alone cannot distinguish a scanner from a reader.
+     *
+     * `userAgent` is null when the requesting client sent no `User-Agent`, which
+     * is common for image fetches; see `predicate.ts` for how unknown is scored.
+     * Absent entirely on sends recorded before the field existed.
+     */
+    opens?: Array<{
+        openedAt: Date;
+        userAgent: string | null;
+    }>;
     firstClickAt: Date | null;
     clickCount: number;
     /** History of actual clicks (a linkId may appear multiple times). */
@@ -1024,6 +1132,7 @@ interface SendDoc {
         url: string;
         linkId: string;
         clickedAt: Date;
+        userAgent?: string | null;
     }>;
     unsubscribedAt: Date | null;
     complainedAt: Date | null;
@@ -1442,6 +1551,10 @@ declare class Mailer {
      *   MAILER_FROM_NAME / MAILER_FROM_EMAIL
      *   MAILER_DEFAULT_PROVIDER           — defaults to 'sendgrid' if SENDGRID_API_KEY is set
      *   MAILER_SENDGRID_API_KEY / MAILER_SENDGRID_WEBHOOK_KEY
+     *   MAILER_SENDGRID_WEBHOOK_TOLERANCE — signed-webhook replay window, seconds
+     *                                       (default 300; '0' disables the check).
+     *                                       Unparseable values fall back to the
+     *                                       default rather than disabling it.
      *   MAILER_HOST_USERS_COLLECTION (default 'users')
      *   MAILER_HOST_USERS_EMAIL_FIELD (default 'email')
      *   MAILER_HOST_USERS_ID_FIELD (default '_id')
@@ -1457,6 +1570,11 @@ declare class Mailer {
     fire(eventName: string, externalId: string, properties?: Record<string, unknown>, dedupeKey?: string): Promise<void>;
     fireFromSession(session: ClientSession, eventName: string, externalId: string, properties?: Record<string, unknown>, dedupeKey?: string): Promise<void>;
     upsertSubscription(input: UpsertSubscriptionInput): Promise<void>;
+    /**
+     * The writes live in `server/unsubscribe.ts` so the pending-unsubscribe
+     * drain (INVARIANT 8) replays a journaled opt-out through exactly this path
+     * without holding a `Mailer` instance.
+     */
     unsubscribe(email: string, opts: Omit<UnsubscribeInput, 'email'>): Promise<void>;
     suppress(email: string, opts: Omit<SuppressInput, 'email'>): Promise<void>;
     tag(externalId: string, tag: string): Promise<void>;
@@ -1533,9 +1651,21 @@ declare class NullProvider implements MailProvider {
     readonly sendRatePerSecond = 1000;
     readonly sent: SendArgs[];
     send(args: SendArgs): Promise<SendResult>;
+    /**
+     * Fails closed. This provider has no signing key, so it can never establish
+     * that an inbound payload is authentic — and a method whose entire job is to
+     * reject unauthenticated input must not answer "yes" by default. Returning
+     * `true` here would mean any unsigned body posted to the webhook route is
+     * accepted as genuine whenever the null provider is registered, which is
+     * exactly the dev/staging configuration where that is easiest to miss.
+     *
+     * Nothing is lost: `parseWebhookEvents()` returns `[]`, so there was never
+     * any inbound behaviour to preserve. To exercise the inbound half locally,
+     * use a provider that actually signs (see `test/README.md`).
+     */
     verifyWebhook(): Promise<boolean>;
     parseWebhookEvents(): NormalizedEvent[];
     reset(): void;
 }
 
-export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type FlowTrigger as a2, type QueueDriverConfig as a3, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };
+export { ensureIndexes as $, type AdapterFilter as A, type BotFilterConfig as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainRegistry as G, type HealthDoc as H, type SenderDomainValidation as I, type SubscriptionDoc as J, type SubscriptionStatus as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionDoc as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type SuppressionReason as U, type TemplateKind as V, type TemplateVersionDoc as W, type VarsAdapter as X, type VarsResolveInfo as Y, type WebhookEventDoc as Z, defineVars as _, type Contact as a, getCollections as a0, validateSenderDomain as a1, varsJsonSchema as a2, type FlowTrigger as a3, type QueueDriverConfig as a4, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type Collections as e, type FlowDoc as f, type SuppressionScope as g, type SegmentFilter as h, type AuditLogDoc as i, type BroadcastDoc as j, type BroadcastStatus as k, type CircuitBreakerThresholds as l, type ContactTagDoc as m, type FlowGoal as n, type FlowRunDoc as o, type FlowRunStatus as p, type FlowVersionDoc as q, type HealthStatus as r, type MailerConfig as s, NullProvider as t, RESERVED_VAR_KEYS as u, type RedisOptions as v, type SegmentDefinition as w, type SendDoc as x, type SendStatus as y, type SenderDomainConfig as z };

package/dist/{null-DDg3ojHe.d.ts → null-CDlseQxO.d.ts}

@@ -661,6 +661,30 @@ interface CircuitBreakerThresholds {
     windowMinutes: number;
     minSendsBeforeEval: number;
 }
+interface BotFilterConfig {
+    /**
+     * User agents matching this pattern are treated as automated. Applied to
+     * recorded open and click user agents alike.
+     *
+     * Default: `/Mimecast|SafeLinks|proofpoint|HeadlessChrome|Googlebot|bingbot/i`
+     * (`DEFAULT_BOT_UA_RE`). Replace it to cover your own corporate scanners;
+     * extend rather than replace if you want to keep the built-ins.
+     */
+    userAgentPattern?: RegExp;
+    /**
+     * Opens recorded within this many milliseconds of the send being queued are
+     * treated as automated regardless of user agent — corporate scanners and
+     * gateway prefetchers fetch the pixel within seconds of delivery, and a
+     * human cannot.
+     *
+     * Default `0` — disabled. It is off by default because it is a heuristic
+     * with a real false-positive tail (a recipient already reading their inbox
+     * when the mail lands) and because enabling it silently changes the counts
+     * every existing flow branches on. `10000` (10s) is the value worth trying
+     * first if your open counts look implausible.
+     */
+    minOpenDelayMs?: number;
+}
 interface MailerConfig {
     db: Db;
     collectionPrefix?: string;
@@ -706,6 +730,40 @@ interface MailerConfig {
     requireDoubleOptIn?: boolean;
     unsubscribeTokenLifetimeDays?: number;
     transactionalRespectUnsubscribe?: boolean;
+    /**
+     * Absolute path to the pending-unsubscribe journal (INVARIANT 8).
+     *
+     * When `POST /m/unsub/:token` cannot reach Mongo, the opt-out is appended
+     * here as JSONL and replayed by the tick drain
+     * (`drainPendingUnsubscribes`). The file is created 0600 inside a 0700
+     * directory and opened `O_NOFOLLOW`.
+     *
+     * **There is no default, and that is deliberate.** The journal holds
+     * recipient email addresses in plaintext outside the database, and a library
+     * mounted into an unknown host cannot pick a directory that is at once
+     * writable, durable and private — which is how the previous default ended up
+     * being `/tmp` (world-writable, wiped on reboot, and never read back).
+     *
+     * With this unset the endpoint answers **503** when Mongo is unreachable,
+     * rather than promising an unsubscribe it has nowhere to record. Set it to a
+     * durable, private, node-local path to get the journal instead — e.g.
+     * `/var/lib/mailery/pending-unsubs.jsonl` (systemd: `StateDirectory=mailery`).
+     *
+     * Must not be on a shared network filesystem: claiming a batch relies on
+     * `rename` being atomic within the directory.
+     */
+    pendingUnsubsPath?: string;
+    /**
+     * How long `POST /m/unsub/:token` waits for the Mongo write before falling
+     * back to the journal. Default 5000ms.
+     *
+     * The tension is INVARIANT 8's own: the response must be fast (clients are
+     * impatient, providers retry) *and* must not claim an unsubscribe that was
+     * never recorded. A healthy write is sub-millisecond, so this budget is only
+     * ever spent during an outage, and spending it is what makes the difference
+     * between a truthful 200 and a lie.
+     */
+    unsubscribeWriteTimeoutMs?: number;
     /** Slug of the transactional template sent for DOI confirmation. Defaults to 'doi-confirmation'. */
     doiTemplateSlug?: string;
     /** How long the DOI token stays valid. Default 7 days. */
@@ -740,10 +798,18 @@ interface MailerConfig {
     mailTester?: MailTesterConfig;
     /**
      * DMARC RUA aggregate reports tell you who is sending mail that claims to
-     * be from your domain — both legitimate sources and spoofers. Operator
-     * uploads the report attachments (or POSTs them via SendGrid Inbound Parse
-     * to /admin/mailer/api/dmarc/upload). Mailery decompresses, parses, and
-     * surfaces alignment failures + unknown senders.
+     * be from your domain — both legitimate sources and spoofers. Mailery
+     * decompresses, parses, and surfaces alignment failures + unknown senders.
+     *
+     * Two ways in:
+     *   - the operator uploads attachments in the admin UI
+     *     (`POST /admin/mailer/api/dmarc/upload`, behind your admin guard)
+     *   - the inbound webhook, for SendGrid Inbound Parse and friends:
+     *     `createPublicRouter(mailer, { dmarcInbound: { secret } })`. Off unless
+     *     that secret is set. Do **not** point Inbound Parse at the admin
+     *     upload route — it sits behind the host's `requireAdmin` guard, which
+     *     Inbound Parse cannot satisfy. (Versions before 0.15 recommended
+     *     exactly that, and it never worked.)
      */
     dmarc?: DmarcConfig;
     broadcastConfirmationThreshold?: number;
@@ -761,6 +827,35 @@ interface MailerConfig {
     trackClicks?: boolean;
     storeTrackingIp?: boolean;
     storeRenderedBody?: boolean;
+    /**
+     * Reject `/m/open` and `/m/click` hits that carry no signature.
+     *
+     * Default `false` — grace mode. Newly rendered mail is always signed; this
+     * flag only decides what happens to the *unsigned* URLs sitting in mail that
+     * was already delivered. In grace mode they are still counted and each one is
+     * logged (`mailery: unsigned tracking URL accepted`) so the operator can watch
+     * the legacy rate fall to zero and then flip this to `true`.
+     *
+     * A signature that is *present but wrong* is always rejected, in both modes.
+     */
+    requireSignedTrackingUrls?: boolean;
+    /**
+     * How long a tracking URL stays valid, in days, measured from the send's
+     * `queuedAt`. Default `0` — never expires.
+     *
+     * Never-expire is the right default: an email sits in an inbox for years and
+     * a legitimate open six months later is real data, not an attack. The
+     * signature already proves the caller was handed the URL. Operators with a
+     * data-retention policy can set a window; because the deadline is derived
+     * from the send row rather than baked into the token, changing this value
+     * takes effect immediately for already-delivered mail and costs no URL bytes.
+     */
+    trackingUrlLifetimeDays?: number;
+    /**
+     * Tuning for `hasOpenedExcludingBots` / `hasClickedExcludingBots` /
+     * `openedAtLeastN` / `clickedAtLeastN`. See `BotFilterConfig`.
+     */
+    botFilter?: BotFilterConfig;
     getAdminActor?: (req: any) => string;
     onCircuitBreakerTrip?: (info: {
         reason: string;
@@ -772,7 +867,7 @@ interface MailerConfig {
     }) => Promise<void> | void;
     handlebarsHelpers?: Record<string, Handlebars.HelperDelegate>;
 }
-type ResolvedConfig = Required<Pick<MailerConfig, 'collectionPrefix' | 'requireDoubleOptIn' | 'unsubscribeTokenLifetimeDays' | 'transactionalRespectUnsubscribe' | 'doiTemplateSlug' | 'doiTokenLifetimeDays' | 'broadcastConfirmationThreshold' | 'broadcastEnqueueBatchSize' | 'broadcastEnqueueMaxWaiting' | 'workerless' | 'tickIntervalSeconds' | 'sendConcurrency' | 'sendRatePerSecond' | 'softBouncePromotionThreshold' | 'softBouncePromotionWindowDays' | 'webhookRetryAttempts' | 'sendRetryAttempts' | 'trackOpens' | 'trackClicks' | 'storeTrackingIp' | 'storeRenderedBody'>> & {
+type ResolvedConfig = Required<Pick<MailerConfig, 'collectionPrefix' | 'requireDoubleOptIn' | 'unsubscribeTokenLifetimeDays' | 'transactionalRespectUnsubscribe' | 'unsubscribeWriteTimeoutMs' | 'doiTemplateSlug' | 'doiTokenLifetimeDays' | 'broadcastConfirmationThreshold' | 'broadcastEnqueueBatchSize' | 'broadcastEnqueueMaxWaiting' | 'workerless' | 'tickIntervalSeconds' | 'sendConcurrency' | 'sendRatePerSecond' | 'softBouncePromotionThreshold' | 'softBouncePromotionWindowDays' | 'webhookRetryAttempts' | 'sendRetryAttempts' | 'trackOpens' | 'trackClicks' | 'storeTrackingIp' | 'storeRenderedBody' | 'requireSignedTrackingUrls' | 'trackingUrlLifetimeDays'>> & {
     circuitBreaker: CircuitBreakerThresholds;
 } & MailerConfig;
 
@@ -1017,6 +1112,19 @@ interface SendDoc {
     vars: Record<string, unknown>;
     openedAt: Date | null;
     openCount: number;
+    /**
+     * Per-open history, capped at the most recent `MAX_TRACKED_OPENS`. Exists so
+     * the bot filter (`hasOpenedExcludingBots`) has something to filter on —
+     * `openCount` alone cannot distinguish a scanner from a reader.
+     *
+     * `userAgent` is null when the requesting client sent no `User-Agent`, which
+     * is common for image fetches; see `predicate.ts` for how unknown is scored.
+     * Absent entirely on sends recorded before the field existed.
+     */
+    opens?: Array<{
+        openedAt: Date;
+        userAgent: string | null;
+    }>;
     firstClickAt: Date | null;
     clickCount: number;
     /** History of actual clicks (a linkId may appear multiple times). */
@@ -1024,6 +1132,7 @@ interface SendDoc {
         url: string;
         linkId: string;
         clickedAt: Date;
+        userAgent?: string | null;
     }>;
     unsubscribedAt: Date | null;
     complainedAt: Date | null;
@@ -1442,6 +1551,10 @@ declare class Mailer {
      *   MAILER_FROM_NAME / MAILER_FROM_EMAIL
      *   MAILER_DEFAULT_PROVIDER           — defaults to 'sendgrid' if SENDGRID_API_KEY is set
      *   MAILER_SENDGRID_API_KEY / MAILER_SENDGRID_WEBHOOK_KEY
+     *   MAILER_SENDGRID_WEBHOOK_TOLERANCE — signed-webhook replay window, seconds
+     *                                       (default 300; '0' disables the check).
+     *                                       Unparseable values fall back to the
+     *                                       default rather than disabling it.
      *   MAILER_HOST_USERS_COLLECTION (default 'users')
      *   MAILER_HOST_USERS_EMAIL_FIELD (default 'email')
      *   MAILER_HOST_USERS_ID_FIELD (default '_id')
@@ -1457,6 +1570,11 @@ declare class Mailer {
     fire(eventName: string, externalId: string, properties?: Record<string, unknown>, dedupeKey?: string): Promise<void>;
     fireFromSession(session: ClientSession, eventName: string, externalId: string, properties?: Record<string, unknown>, dedupeKey?: string): Promise<void>;
     upsertSubscription(input: UpsertSubscriptionInput): Promise<void>;
+    /**
+     * The writes live in `server/unsubscribe.ts` so the pending-unsubscribe
+     * drain (INVARIANT 8) replays a journaled opt-out through exactly this path
+     * without holding a `Mailer` instance.
+     */
     unsubscribe(email: string, opts: Omit<UnsubscribeInput, 'email'>): Promise<void>;
     suppress(email: string, opts: Omit<SuppressInput, 'email'>): Promise<void>;
     tag(externalId: string, tag: string): Promise<void>;
@@ -1533,9 +1651,21 @@ declare class NullProvider implements MailProvider {
     readonly sendRatePerSecond = 1000;
     readonly sent: SendArgs[];
     send(args: SendArgs): Promise<SendResult>;
+    /**
+     * Fails closed. This provider has no signing key, so it can never establish
+     * that an inbound payload is authentic — and a method whose entire job is to
+     * reject unauthenticated input must not answer "yes" by default. Returning
+     * `true` here would mean any unsigned body posted to the webhook route is
+     * accepted as genuine whenever the null provider is registered, which is
+     * exactly the dev/staging configuration where that is easiest to miss.
+     *
+     * Nothing is lost: `parseWebhookEvents()` returns `[]`, so there was never
+     * any inbound behaviour to preserve. To exercise the inbound half locally,
+     * use a provider that actually signs (see `test/README.md`).
+     */
     verifyWebhook(): Promise<boolean>;
     parseWebhookEvents(): NormalizedEvent[];
     reset(): void;
 }
 
-export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type FlowTrigger as a2, type QueueDriverConfig as a3, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };
+export { ensureIndexes as $, type AdapterFilter as A, type BotFilterConfig as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainRegistry as G, type HealthDoc as H, type SenderDomainValidation as I, type SubscriptionDoc as J, type SubscriptionStatus as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionDoc as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type SuppressionReason as U, type TemplateKind as V, type TemplateVersionDoc as W, type VarsAdapter as X, type VarsResolveInfo as Y, type WebhookEventDoc as Z, defineVars as _, type Contact as a, getCollections as a0, validateSenderDomain as a1, varsJsonSchema as a2, type FlowTrigger as a3, type QueueDriverConfig as a4, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type Collections as e, type FlowDoc as f, type SuppressionScope as g, type SegmentFilter as h, type AuditLogDoc as i, type BroadcastDoc as j, type BroadcastStatus as k, type CircuitBreakerThresholds as l, type ContactTagDoc as m, type FlowGoal as n, type FlowRunDoc as o, type FlowRunStatus as p, type FlowVersionDoc as q, type HealthStatus as r, type MailerConfig as s, NullProvider as t, RESERVED_VAR_KEYS as u, type RedisOptions as v, type SegmentDefinition as w, type SendDoc as x, type SendStatus as y, type SenderDomainConfig as z };