mailery 0.17.1 → 0.18.0

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, F as FlowStep, e as Collections, f as FlowDoc, g as SuppressionScope, D as DeliveryWindow, h as SegmentFilter, P as Predicate } from './null-DhkTG7mq.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-DhkTG7mq.cjs';
+import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, b as AdapterSort, M as MailProvider, S as SendArgs, c as SendResult, d as MailTesterFeedback, e as Mailer, T as TemplateDoc, F as FlowStep, f as Collections, g as FlowDoc, h as SuppressionScope, D as DeliveryWindow, i as SegmentFilter, P as Predicate } from './null-BFipn5tF.cjs';
+export { j as AuditLogDoc, B as BotFilterConfig, k as BroadcastDoc, l as BroadcastOrder, m as BroadcastPauseReason, n as BroadcastStatus, o as CircuitBreakerThresholds, p as ContactTagDoc, E as EventDoc, q as FlowGoal, r as FlowRunDoc, s as FlowRunStatus, t as FlowVersionDoc, H as HealthDoc, u as HealthStatus, L as LeadDoc, v as MailerConfig, w as NullProvider, O as OutboxDoc, x as RESERVED_VAR_KEYS, y as RedisOptions, z as SegmentDefinition, G as SendDoc, I as SendStatus, J as SenderDomainConfig, K as SenderDomainRegistry, Q as SenderDomainValidation, U as SubscriptionDoc, V as SubscriptionStatus, W as SuppressionDoc, X as SuppressionReason, Y as TemplateKind, Z as TemplateVersionDoc, _ as VarsAdapter, $ as VarsResolveInfo, a0 as WebhookEventDoc, a1 as defineVars, a2 as ensureIndexes, a3 as getCollections, a4 as validateSenderDomain, a5 as varsJsonSchema } from './null-BFipn5tF.cjs';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';
@@ -153,14 +153,34 @@ declare class MongoContactAdapter implements ContactAdapter {
     getById(externalId: string): Promise<Contact | null>;
     getByEmail(email: string): Promise<Contact | null>;
     getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    /** `query` honours `opts.sort` — see `querySorted`. */
+    readonly supportsSort = true;
     query(filter: AdapterFilter, opts: {
         limit: number;
         cursor?: string;
+        sort?: AdapterSort;
     }): Promise<{
         contacts: Contact[];
         nextCursor?: string;
     }>;
     count(filter: AdapterFilter): Promise<number>;
+    /**
+     * Keyset pagination in (sort.field, idField) order. The cursor encodes the
+     * last row's sort value and id, and the next page is every row strictly
+     * after that position. Mongo sorts a null or missing value lowest, so
+     * `desc` puts contacts without the field last and `asc` puts them first;
+     * the position predicate follows the same rule, so they are neither
+     * skipped nor repeated.
+     *
+     * The field should hold one BSON type (or be absent): range operators only
+     * compare within a type. A value that moves while a pass is paging (a
+     * contact whose `updatedAt` changes mid-dispatch) can be seen twice or not
+     * at all in that pass; broadcast dispatch tolerates both (the per-recipient
+     * dedupe key stops a second send, and a later pass picks up a skipped one).
+     * Index `{ <field>: -1, <idField>: 1 }` on a large collection.
+     */
+    private querySorted;
+    private afterPosition;
     addTags?: (externalId: string, tags: string[]) => Promise<void>;
     removeTags?: (externalId: string, tags: string[]) => Promise<void>;
     private idFilter;
@@ -914,16 +934,20 @@ declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions):
  * HMAC-signed tokens for unsubscribe + preference-center URLs.
  *
  * Format:  base64url(payload) '.' base64url(hmac)
- *   payload  = JSON.stringify({ e: email, s: scope, x: expiresAtMs })
+ *   payload  = JSON.stringify({ e: email, s: scope, x: expiresAtMs, i?: sendId })
  *   hmac     = HMAC-SHA256(secret, payload)
  *
- * Tokens expire because long-lived signed URLs are a liability.
+ * Tokens expire because long-lived signed URLs are a liability. `i` (0.18+)
+ * names the send the link was rendered into, so an unsubscribe can be
+ * attributed to it; tokens without it verify exactly as before.
  */
 
 interface UnsubscribeTokenPayload {
     email: string;
     scope: SuppressionScope;
     expiresAt: Date;
+    /** The send the link was rendered into (24 hex chars). Optional. */
+    sendId?: string;
 }
 declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
 declare function verifyUnsubscribeToken(token: string, secret: string, now?: Date): UnsubscribeTokenPayload | null;
@@ -1063,4 +1087,4 @@ declare const DEDUPE_POLICIES: readonly DedupePolicyOption[];
  */
 declare const VERSION: string;
 
-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 };
+export { AdapterFilter, AdapterSort, 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 };

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, F as FlowStep, e as Collections, f as FlowDoc, g as SuppressionScope, D as DeliveryWindow, h as SegmentFilter, P as Predicate } from './null-DhkTG7mq.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-DhkTG7mq.js';
+import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, b as AdapterSort, M as MailProvider, S as SendArgs, c as SendResult, d as MailTesterFeedback, e as Mailer, T as TemplateDoc, F as FlowStep, f as Collections, g as FlowDoc, h as SuppressionScope, D as DeliveryWindow, i as SegmentFilter, P as Predicate } from './null-BFipn5tF.js';
+export { j as AuditLogDoc, B as BotFilterConfig, k as BroadcastDoc, l as BroadcastOrder, m as BroadcastPauseReason, n as BroadcastStatus, o as CircuitBreakerThresholds, p as ContactTagDoc, E as EventDoc, q as FlowGoal, r as FlowRunDoc, s as FlowRunStatus, t as FlowVersionDoc, H as HealthDoc, u as HealthStatus, L as LeadDoc, v as MailerConfig, w as NullProvider, O as OutboxDoc, x as RESERVED_VAR_KEYS, y as RedisOptions, z as SegmentDefinition, G as SendDoc, I as SendStatus, J as SenderDomainConfig, K as SenderDomainRegistry, Q as SenderDomainValidation, U as SubscriptionDoc, V as SubscriptionStatus, W as SuppressionDoc, X as SuppressionReason, Y as TemplateKind, Z as TemplateVersionDoc, _ as VarsAdapter, $ as VarsResolveInfo, a0 as WebhookEventDoc, a1 as defineVars, a2 as ensureIndexes, a3 as getCollections, a4 as validateSenderDomain, a5 as varsJsonSchema } from './null-BFipn5tF.js';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';
@@ -153,14 +153,34 @@ declare class MongoContactAdapter implements ContactAdapter {
     getById(externalId: string): Promise<Contact | null>;
     getByEmail(email: string): Promise<Contact | null>;
     getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    /** `query` honours `opts.sort` — see `querySorted`. */
+    readonly supportsSort = true;
     query(filter: AdapterFilter, opts: {
         limit: number;
         cursor?: string;
+        sort?: AdapterSort;
     }): Promise<{
         contacts: Contact[];
         nextCursor?: string;
     }>;
     count(filter: AdapterFilter): Promise<number>;
+    /**
+     * Keyset pagination in (sort.field, idField) order. The cursor encodes the
+     * last row's sort value and id, and the next page is every row strictly
+     * after that position. Mongo sorts a null or missing value lowest, so
+     * `desc` puts contacts without the field last and `asc` puts them first;
+     * the position predicate follows the same rule, so they are neither
+     * skipped nor repeated.
+     *
+     * The field should hold one BSON type (or be absent): range operators only
+     * compare within a type. A value that moves while a pass is paging (a
+     * contact whose `updatedAt` changes mid-dispatch) can be seen twice or not
+     * at all in that pass; broadcast dispatch tolerates both (the per-recipient
+     * dedupe key stops a second send, and a later pass picks up a skipped one).
+     * Index `{ <field>: -1, <idField>: 1 }` on a large collection.
+     */
+    private querySorted;
+    private afterPosition;
     addTags?: (externalId: string, tags: string[]) => Promise<void>;
     removeTags?: (externalId: string, tags: string[]) => Promise<void>;
     private idFilter;
@@ -914,16 +934,20 @@ declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions):
  * HMAC-signed tokens for unsubscribe + preference-center URLs.
  *
  * Format:  base64url(payload) '.' base64url(hmac)
- *   payload  = JSON.stringify({ e: email, s: scope, x: expiresAtMs })
+ *   payload  = JSON.stringify({ e: email, s: scope, x: expiresAtMs, i?: sendId })
  *   hmac     = HMAC-SHA256(secret, payload)
  *
- * Tokens expire because long-lived signed URLs are a liability.
+ * Tokens expire because long-lived signed URLs are a liability. `i` (0.18+)
+ * names the send the link was rendered into, so an unsubscribe can be
+ * attributed to it; tokens without it verify exactly as before.
  */
 
 interface UnsubscribeTokenPayload {
     email: string;
     scope: SuppressionScope;
     expiresAt: Date;
+    /** The send the link was rendered into (24 hex chars). Optional. */
+    sendId?: string;
 }
 declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
 declare function verifyUnsubscribeToken(token: string, secret: string, now?: Date): UnsubscribeTokenPayload | null;
@@ -1063,4 +1087,4 @@ declare const DEDUPE_POLICIES: readonly DedupePolicyOption[];
  */
 declare const VERSION: string;
 
-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 };
+export { AdapterFilter, AdapterSort, 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 };