mailery 0.17.1 → 0.19.0

package/dist/{null-DhkTG7mq.d.cts → null-DxTHQSrJ.d.cts}

@@ -32,17 +32,41 @@ interface AdapterFilter {
     createdAfter?: Date;
     createdBefore?: Date;
 }
+/**
+ * Order for `ContactAdapter.query`. `field` names a field on the host's
+ * contact record (for MongoContactAdapter, a document path such as
+ * `updatedAt`), not a key of the `Contact` projection. Ties break on the
+ * contact id, ascending, so the order is total and pagination is stable.
+ */
+interface AdapterSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
 interface ContactAdapter {
     getById(externalId: string): Promise<Contact | null>;
     getByEmail(email: string): Promise<Contact | null>;
     getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    /**
+     * One page of contacts matching `filter`. Without `opts.sort` the order is
+     * the adapter's own and must be stable across calls (MongoContactAdapter:
+     * by id). `opts.sort` is honoured only by adapters that declare
+     * `supportsSort: true`; mailery never passes it to one that does not.
+     */
     query(filter: AdapterFilter, opts: {
         limit: number;
         cursor?: string;
+        sort?: AdapterSort;
     }): Promise<{
         contacts: Contact[];
         nextCursor?: string;
     }>;
+    /**
+     * True when `query` honours `opts.sort` (with an opaque cursor that
+     * encodes the sort position). Optional: adapters written before 0.18 omit
+     * it, and a broadcast with an `order` is then refused at create time
+     * rather than silently sent in id order.
+     */
+    readonly supportsSort?: boolean;
     count(filter: AdapterFilter): Promise<number>;
     addTags?(externalId: string, tags: string[]): Promise<void>;
     removeTags?(externalId: string, tags: string[]): Promise<void>;
@@ -448,7 +472,13 @@ type QueueDriverConfig = {
  * server-shaped interfaces.
  */
 type SubscriptionStatus = 'subscribed' | 'pending_doi' | 'unsubscribed' | 'bounced' | 'complained';
-type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled';
+type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled'
+/**
+ * A broadcast send parked because its broadcast is paused (stop rule,
+ * circuit breaker, operator). Never dispatched while held; resuming the
+ * broadcast re-queues it.
+ */
+ | 'held';
 type TemplateKind = 'transactional' | 'marketing';
 /**
  * How a template's body goes on the wire.
@@ -466,7 +496,12 @@ type TemplateBodyFormat = 'multipart' | 'text_only';
 type SuppressionScope = 'all' | 'marketing' | 'transactional';
 type SuppressionReason = 'unsubscribed' | 'hard_bounce' | 'complaint' | 'manual' | 'list_cleaning' | 'gdpr_forget';
 type FlowRunStatus = 'active' | 'completed' | 'exited' | 'failed';
-type BroadcastStatus = 'draft' | 'scheduled' | 'sending' | 'sent' | 'cancelled' | 'failed';
+/**
+ * `paused` — dispatch stopped with the broadcast re-openable: a wave reached
+ * its `recipientCap`, a stop rule or the circuit breaker fired, or an
+ * operator paused it. `pauseReason` says which; `resume` re-opens it.
+ */
+type BroadcastStatus = 'draft' | 'scheduled' | 'sending' | 'paused' | 'sent' | 'cancelled' | 'failed';
 type HealthStatus = 'healthy' | 'degraded' | 'tripped';
 type FlowGoal = 'activation' | 'conversion' | 'retention' | 'reactivation' | 'transactional' | 'broadcast';
 
@@ -588,6 +623,15 @@ interface DnsblConfig {
     dedicatedIps?: string[];
     /** Hours between automatic runs. Default 24. Set to 0 to disable scheduled runs. */
     intervalHours?: number;
+    /**
+     * Spamhaus Data Query Service key (free at spamhaus.com for low volume).
+     * Spamhaus refuses queries that arrive through public or shared resolvers —
+     * Google, Cloudflare, and cloud VPC resolvers such as AWS's — answering
+     * 127.255.255.254 instead of a verdict. With a key, every `*.spamhaus.org`
+     * list is queried as `<key>.<zone>.dq.spamhaus.net`, which answers from
+     * anywhere. Rows and the UI keep the public list name; the key is never stored.
+     */
+    spamhausDqsKey?: string;
 }
 interface MailTesterConfig {
     /** API key from your Mail-Tester paid plan. */
@@ -678,6 +722,25 @@ interface CircuitBreakerThresholds {
     windowMinutes: number;
     minSendsBeforeEval: number;
 }
+/**
+ * Automatic stop rules for one broadcast. A breach pauses the broadcast
+ * (`pauseReason.code: 'stop_rule'`): no more enqueues, and its queued sends
+ * are held until an explicit resume. Rates are measured over the
+ * broadcast's sends with a known outcome (delivered or bounced) and only
+ * once `minSample` of them are in. A breach is `rate > threshold`.
+ */
+interface BroadcastStopRules {
+    /** Default true. */
+    enabled: boolean;
+    /** Hard bounces, % of outcomes. Default 2. */
+    hardBounceRatePct: number;
+    /** Complaints (spam reports), % of outcomes. Default 0.1. */
+    complaintRatePct: number;
+    /** Unsubscribes attributed to the broadcast, % of outcomes. Default 1. */
+    unsubscribeRatePct: number;
+    /** Outcomes required before any rule is evaluated. Default 100. */
+    minSample: number;
+}
 interface BotFilterConfig {
     /**
      * User agents matching this pattern are treated as automated. Applied to
@@ -840,6 +903,12 @@ interface MailerConfig {
     broadcastConfirmationThreshold?: number;
     broadcastEnqueueBatchSize?: number;
     broadcastEnqueueMaxWaiting?: number;
+    /**
+     * Defaults for every broadcast's automatic stop rules; a broadcast can
+     * override any of them (`stopRules` on create/patch/resume). See
+     * `BroadcastStopRules`.
+     */
+    broadcastStopRules?: Partial<BroadcastStopRules>;
     workerless?: boolean;
     tickIntervalSeconds?: number;
     sendConcurrency?: number;
@@ -884,16 +953,33 @@ interface MailerConfig {
     getAdminActor?: (req: any) => string;
     onCircuitBreakerTrip?: (info: {
         reason: string;
-        rates: Record<string, number>;
+        rates: Record<string, number | null>;
     }) => Promise<void> | void;
     onSendFailure?: (info: {
         send: any;
         error: Error;
     }) => Promise<void> | void;
+    /**
+     * Called when a broadcast is paused by a stop rule, the circuit breaker, a
+     * reached cap, or an operator. Alerting belongs here: a stop-rule pause
+     * waits for a human.
+     */
+    onBroadcastPaused?: (info: {
+        broadcastId: string;
+        slug: string;
+        reason: {
+            code: string;
+            message: string;
+            at: Date;
+            details?: Record<string, unknown>;
+        };
+        heldSends: number;
+    }) => Promise<void> | void;
     handlebarsHelpers?: Record<string, Handlebars.HelperDelegate>;
 }
 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;
+    broadcastStopRules: BroadcastStopRules;
 } & MailerConfig;
 
 /**
@@ -1168,6 +1254,12 @@ interface SendDoc {
     updatedAt: Date;
     sentAt: Date | null;
     deliveredAt: Date | null;
+    /**
+     * Broadcast sends: the moment the send was meant to go (scheduledAt, or
+     * the recipient-local slot). A held send is re-queued with the delay that
+     * remains until then.
+     */
+    notBefore?: Date | null;
 }
 interface SuppressionDoc {
     _id?: ObjectId;
@@ -1197,6 +1289,43 @@ interface BroadcastDoc {
     recipientCount: number | null;
     /** When true, dispatch fires each recipient at their local-timezone equivalent of `scheduledAt`. */
     respectRecipientTimezone?: boolean;
+    /**
+     * Native waves: the most send rows this broadcast may have. Dispatch stops
+     * enqueueing when the broadcast's send rows (every status, earlier waves
+     * included) reach it, and parks the broadcast in `paused` with
+     * `pauseReason.code === 'cap_reached'` if eligible recipients remain.
+     * Raising it and resuming sends the next slice. Null or absent: no cap.
+     */
+    recipientCap?: number | null;
+    /** Order recipients are taken in (host-side sort). Null or absent: the adapter's own order. */
+    order?: BroadcastOrder | null;
+    /** Set while `status === 'paused'`. */
+    pausedAt?: Date | null;
+    pauseReason?: BroadcastPauseReason | null;
+    /** Lease held by the one dispatcher allowed to enqueue for this broadcast. */
+    dispatchLeaseId?: string | null;
+    /** Bumped on every (re)start of dispatch; part of the dispatch job id. */
+    dispatchGeneration?: number;
+    /** Why dispatch set status 'failed'. */
+    failureReason?: string | null;
+    /** Per-broadcast overrides of `MailerConfig.broadcastStopRules`. */
+    stopRules?: Partial<{
+        enabled: boolean;
+        hardBounceRatePct: number;
+        complaintRatePct: number;
+        unsubscribeRatePct: number;
+        minSample: number;
+    }> | null;
+    /**
+     * First stop-rule breach seen after the broadcast had nothing left to
+     * hold (status 'sent', no queued sends) — recorded, since there was
+     * nothing to pause.
+     */
+    stopRuleBreach?: {
+        at: Date;
+        sample: number;
+        breaches: StopRuleBreach[];
+    } | null;
     stats: {
         sent: number;
         delivered: number;
@@ -1210,6 +1339,29 @@ interface BroadcastDoc {
     createdBy: string;
     updatedAt: Date;
 }
+interface BroadcastOrder {
+    /** A host field, e.g. `updatedAt` for "most recently active first" with `direction: 'desc'`. */
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface StopRuleBreach {
+    rule: 'hardBounceRatePct' | 'complaintRatePct' | 'unsubscribeRatePct';
+    count: number;
+    ratePct: number;
+    thresholdPct: number;
+}
+interface BroadcastPauseReason {
+    /**
+     * cap_reached     — the wave's recipientCap is spent; raise it and resume.
+     * stop_rule       — a per-broadcast bounce/complaint/unsubscribe threshold was crossed.
+     * circuit_breaker — the sender domain's marketing circuit breaker tripped.
+     * manual          — paused by an operator.
+     */
+    code: 'cap_reached' | 'stop_rule' | 'circuit_breaker' | 'manual';
+    message: string;
+    at: Date;
+    details?: Record<string, unknown>;
+}
 interface OutboxDoc {
     _id?: ObjectId;
     payload: {
@@ -1281,11 +1433,15 @@ interface HealthDoc {
         complained: number;
         failedToSend: number;
     };
+    /**
+     * Bounce/complaint rates are per send in the window; failureRate is failed
+     * attempts over all attempts. Null when the window has no denominator yet.
+     */
     rates: {
-        bounceRate: number;
-        hardBounceRate: number;
-        complaintRate: number;
-        failureRate: number;
+        bounceRate: number | null;
+        hardBounceRate: number | null;
+        complaintRate: number | null;
+        failureRate: number | null;
     };
     status: HealthStatus;
     trippedAt: Date | null;
@@ -1713,4 +1869,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-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 };
+export { type VarsResolveInfo 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 SendDoc as G, type HealthDoc as H, type SendStatus as I, type SenderDomainConfig as J, type SenderDomainRegistry as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SenderDomainValidation as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type SubscriptionDoc as U, type SubscriptionStatus as V, type SuppressionDoc as W, type SuppressionReason as X, type TemplateKind as Y, type TemplateVersionDoc as Z, type VarsAdapter as _, type Contact as a, type WebhookEventDoc as a0, defineVars as a1, ensureIndexes as a2, getCollections as a3, validateSenderDomain as a4, varsJsonSchema as a5, type FlowTrigger as a6, type QueueDriverConfig as a7, type AdapterSort as b, type SendResult as c, type MailTesterFeedback as d, Mailer as e, type Collections as f, type FlowDoc as g, type SuppressionScope as h, type SegmentFilter as i, type AuditLogDoc as j, type BroadcastDoc as k, type BroadcastOrder as l, type BroadcastPauseReason as m, type BroadcastStatus as n, type CircuitBreakerThresholds as o, type ContactTagDoc as p, type FlowGoal as q, type FlowRunDoc as r, type FlowRunStatus as s, type FlowVersionDoc as t, type HealthStatus as u, type MailerConfig as v, NullProvider as w, RESERVED_VAR_KEYS as x, type RedisOptions as y, type SegmentDefinition as z };

package/dist/{null-DhkTG7mq.d.ts → null-DxTHQSrJ.d.ts}

@@ -32,17 +32,41 @@ interface AdapterFilter {
     createdAfter?: Date;
     createdBefore?: Date;
 }
+/**
+ * Order for `ContactAdapter.query`. `field` names a field on the host's
+ * contact record (for MongoContactAdapter, a document path such as
+ * `updatedAt`), not a key of the `Contact` projection. Ties break on the
+ * contact id, ascending, so the order is total and pagination is stable.
+ */
+interface AdapterSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
 interface ContactAdapter {
     getById(externalId: string): Promise<Contact | null>;
     getByEmail(email: string): Promise<Contact | null>;
     getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    /**
+     * One page of contacts matching `filter`. Without `opts.sort` the order is
+     * the adapter's own and must be stable across calls (MongoContactAdapter:
+     * by id). `opts.sort` is honoured only by adapters that declare
+     * `supportsSort: true`; mailery never passes it to one that does not.
+     */
     query(filter: AdapterFilter, opts: {
         limit: number;
         cursor?: string;
+        sort?: AdapterSort;
     }): Promise<{
         contacts: Contact[];
         nextCursor?: string;
     }>;
+    /**
+     * True when `query` honours `opts.sort` (with an opaque cursor that
+     * encodes the sort position). Optional: adapters written before 0.18 omit
+     * it, and a broadcast with an `order` is then refused at create time
+     * rather than silently sent in id order.
+     */
+    readonly supportsSort?: boolean;
     count(filter: AdapterFilter): Promise<number>;
     addTags?(externalId: string, tags: string[]): Promise<void>;
     removeTags?(externalId: string, tags: string[]): Promise<void>;
@@ -448,7 +472,13 @@ type QueueDriverConfig = {
  * server-shaped interfaces.
  */
 type SubscriptionStatus = 'subscribed' | 'pending_doi' | 'unsubscribed' | 'bounced' | 'complained';
-type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled';
+type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled'
+/**
+ * A broadcast send parked because its broadcast is paused (stop rule,
+ * circuit breaker, operator). Never dispatched while held; resuming the
+ * broadcast re-queues it.
+ */
+ | 'held';
 type TemplateKind = 'transactional' | 'marketing';
 /**
  * How a template's body goes on the wire.
@@ -466,7 +496,12 @@ type TemplateBodyFormat = 'multipart' | 'text_only';
 type SuppressionScope = 'all' | 'marketing' | 'transactional';
 type SuppressionReason = 'unsubscribed' | 'hard_bounce' | 'complaint' | 'manual' | 'list_cleaning' | 'gdpr_forget';
 type FlowRunStatus = 'active' | 'completed' | 'exited' | 'failed';
-type BroadcastStatus = 'draft' | 'scheduled' | 'sending' | 'sent' | 'cancelled' | 'failed';
+/**
+ * `paused` — dispatch stopped with the broadcast re-openable: a wave reached
+ * its `recipientCap`, a stop rule or the circuit breaker fired, or an
+ * operator paused it. `pauseReason` says which; `resume` re-opens it.
+ */
+type BroadcastStatus = 'draft' | 'scheduled' | 'sending' | 'paused' | 'sent' | 'cancelled' | 'failed';
 type HealthStatus = 'healthy' | 'degraded' | 'tripped';
 type FlowGoal = 'activation' | 'conversion' | 'retention' | 'reactivation' | 'transactional' | 'broadcast';
 
@@ -588,6 +623,15 @@ interface DnsblConfig {
     dedicatedIps?: string[];
     /** Hours between automatic runs. Default 24. Set to 0 to disable scheduled runs. */
     intervalHours?: number;
+    /**
+     * Spamhaus Data Query Service key (free at spamhaus.com for low volume).
+     * Spamhaus refuses queries that arrive through public or shared resolvers —
+     * Google, Cloudflare, and cloud VPC resolvers such as AWS's — answering
+     * 127.255.255.254 instead of a verdict. With a key, every `*.spamhaus.org`
+     * list is queried as `<key>.<zone>.dq.spamhaus.net`, which answers from
+     * anywhere. Rows and the UI keep the public list name; the key is never stored.
+     */
+    spamhausDqsKey?: string;
 }
 interface MailTesterConfig {
     /** API key from your Mail-Tester paid plan. */
@@ -678,6 +722,25 @@ interface CircuitBreakerThresholds {
     windowMinutes: number;
     minSendsBeforeEval: number;
 }
+/**
+ * Automatic stop rules for one broadcast. A breach pauses the broadcast
+ * (`pauseReason.code: 'stop_rule'`): no more enqueues, and its queued sends
+ * are held until an explicit resume. Rates are measured over the
+ * broadcast's sends with a known outcome (delivered or bounced) and only
+ * once `minSample` of them are in. A breach is `rate > threshold`.
+ */
+interface BroadcastStopRules {
+    /** Default true. */
+    enabled: boolean;
+    /** Hard bounces, % of outcomes. Default 2. */
+    hardBounceRatePct: number;
+    /** Complaints (spam reports), % of outcomes. Default 0.1. */
+    complaintRatePct: number;
+    /** Unsubscribes attributed to the broadcast, % of outcomes. Default 1. */
+    unsubscribeRatePct: number;
+    /** Outcomes required before any rule is evaluated. Default 100. */
+    minSample: number;
+}
 interface BotFilterConfig {
     /**
      * User agents matching this pattern are treated as automated. Applied to
@@ -840,6 +903,12 @@ interface MailerConfig {
     broadcastConfirmationThreshold?: number;
     broadcastEnqueueBatchSize?: number;
     broadcastEnqueueMaxWaiting?: number;
+    /**
+     * Defaults for every broadcast's automatic stop rules; a broadcast can
+     * override any of them (`stopRules` on create/patch/resume). See
+     * `BroadcastStopRules`.
+     */
+    broadcastStopRules?: Partial<BroadcastStopRules>;
     workerless?: boolean;
     tickIntervalSeconds?: number;
     sendConcurrency?: number;
@@ -884,16 +953,33 @@ interface MailerConfig {
     getAdminActor?: (req: any) => string;
     onCircuitBreakerTrip?: (info: {
         reason: string;
-        rates: Record<string, number>;
+        rates: Record<string, number | null>;
     }) => Promise<void> | void;
     onSendFailure?: (info: {
         send: any;
         error: Error;
     }) => Promise<void> | void;
+    /**
+     * Called when a broadcast is paused by a stop rule, the circuit breaker, a
+     * reached cap, or an operator. Alerting belongs here: a stop-rule pause
+     * waits for a human.
+     */
+    onBroadcastPaused?: (info: {
+        broadcastId: string;
+        slug: string;
+        reason: {
+            code: string;
+            message: string;
+            at: Date;
+            details?: Record<string, unknown>;
+        };
+        heldSends: number;
+    }) => Promise<void> | void;
     handlebarsHelpers?: Record<string, Handlebars.HelperDelegate>;
 }
 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;
+    broadcastStopRules: BroadcastStopRules;
 } & MailerConfig;
 
 /**
@@ -1168,6 +1254,12 @@ interface SendDoc {
     updatedAt: Date;
     sentAt: Date | null;
     deliveredAt: Date | null;
+    /**
+     * Broadcast sends: the moment the send was meant to go (scheduledAt, or
+     * the recipient-local slot). A held send is re-queued with the delay that
+     * remains until then.
+     */
+    notBefore?: Date | null;
 }
 interface SuppressionDoc {
     _id?: ObjectId;
@@ -1197,6 +1289,43 @@ interface BroadcastDoc {
     recipientCount: number | null;
     /** When true, dispatch fires each recipient at their local-timezone equivalent of `scheduledAt`. */
     respectRecipientTimezone?: boolean;
+    /**
+     * Native waves: the most send rows this broadcast may have. Dispatch stops
+     * enqueueing when the broadcast's send rows (every status, earlier waves
+     * included) reach it, and parks the broadcast in `paused` with
+     * `pauseReason.code === 'cap_reached'` if eligible recipients remain.
+     * Raising it and resuming sends the next slice. Null or absent: no cap.
+     */
+    recipientCap?: number | null;
+    /** Order recipients are taken in (host-side sort). Null or absent: the adapter's own order. */
+    order?: BroadcastOrder | null;
+    /** Set while `status === 'paused'`. */
+    pausedAt?: Date | null;
+    pauseReason?: BroadcastPauseReason | null;
+    /** Lease held by the one dispatcher allowed to enqueue for this broadcast. */
+    dispatchLeaseId?: string | null;
+    /** Bumped on every (re)start of dispatch; part of the dispatch job id. */
+    dispatchGeneration?: number;
+    /** Why dispatch set status 'failed'. */
+    failureReason?: string | null;
+    /** Per-broadcast overrides of `MailerConfig.broadcastStopRules`. */
+    stopRules?: Partial<{
+        enabled: boolean;
+        hardBounceRatePct: number;
+        complaintRatePct: number;
+        unsubscribeRatePct: number;
+        minSample: number;
+    }> | null;
+    /**
+     * First stop-rule breach seen after the broadcast had nothing left to
+     * hold (status 'sent', no queued sends) — recorded, since there was
+     * nothing to pause.
+     */
+    stopRuleBreach?: {
+        at: Date;
+        sample: number;
+        breaches: StopRuleBreach[];
+    } | null;
     stats: {
         sent: number;
         delivered: number;
@@ -1210,6 +1339,29 @@ interface BroadcastDoc {
     createdBy: string;
     updatedAt: Date;
 }
+interface BroadcastOrder {
+    /** A host field, e.g. `updatedAt` for "most recently active first" with `direction: 'desc'`. */
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface StopRuleBreach {
+    rule: 'hardBounceRatePct' | 'complaintRatePct' | 'unsubscribeRatePct';
+    count: number;
+    ratePct: number;
+    thresholdPct: number;
+}
+interface BroadcastPauseReason {
+    /**
+     * cap_reached     — the wave's recipientCap is spent; raise it and resume.
+     * stop_rule       — a per-broadcast bounce/complaint/unsubscribe threshold was crossed.
+     * circuit_breaker — the sender domain's marketing circuit breaker tripped.
+     * manual          — paused by an operator.
+     */
+    code: 'cap_reached' | 'stop_rule' | 'circuit_breaker' | 'manual';
+    message: string;
+    at: Date;
+    details?: Record<string, unknown>;
+}
 interface OutboxDoc {
     _id?: ObjectId;
     payload: {
@@ -1281,11 +1433,15 @@ interface HealthDoc {
         complained: number;
         failedToSend: number;
     };
+    /**
+     * Bounce/complaint rates are per send in the window; failureRate is failed
+     * attempts over all attempts. Null when the window has no denominator yet.
+     */
     rates: {
-        bounceRate: number;
-        hardBounceRate: number;
-        complaintRate: number;
-        failureRate: number;
+        bounceRate: number | null;
+        hardBounceRate: number | null;
+        complaintRate: number | null;
+        failureRate: number | null;
     };
     status: HealthStatus;
     trippedAt: Date | null;
@@ -1713,4 +1869,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-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 };
+export { type VarsResolveInfo 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 SendDoc as G, type HealthDoc as H, type SendStatus as I, type SenderDomainConfig as J, type SenderDomainRegistry as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SenderDomainValidation as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type SubscriptionDoc as U, type SubscriptionStatus as V, type SuppressionDoc as W, type SuppressionReason as X, type TemplateKind as Y, type TemplateVersionDoc as Z, type VarsAdapter as _, type Contact as a, type WebhookEventDoc as a0, defineVars as a1, ensureIndexes as a2, getCollections as a3, validateSenderDomain as a4, varsJsonSchema as a5, type FlowTrigger as a6, type QueueDriverConfig as a7, type AdapterSort as b, type SendResult as c, type MailTesterFeedback as d, Mailer as e, type Collections as f, type FlowDoc as g, type SuppressionScope as h, type SegmentFilter as i, type AuditLogDoc as j, type BroadcastDoc as k, type BroadcastOrder as l, type BroadcastPauseReason as m, type BroadcastStatus as n, type CircuitBreakerThresholds as o, type ContactTagDoc as p, type FlowGoal as q, type FlowRunDoc as r, type FlowRunStatus as s, type FlowVersionDoc as t, type HealthStatus as u, type MailerConfig as v, NullProvider as w, RESERVED_VAR_KEYS as x, type RedisOptions as y, type SegmentDefinition as z };