mailery 0.0.0 → 0.1.0

package/dist/null-7gnz1V98.d.ts

@@ -0,0 +1,959 @@
+import { Db, ObjectId, Collection, ClientSession } from 'mongodb';
+import IORedis from 'ioredis';
+import { z } from 'zod';
+import Handlebars from 'handlebars';
+
+/**
+ * Shared types — used by both server and client. Stub placeholders for Phase 0.
+ * Full shapes live in plans/02-data-model.md.
+ */
+interface Contact {
+    externalId: string;
+    email: string;
+    tags: string[];
+    fields: Record<string, unknown>;
+    timezone?: string;
+    locale?: string;
+}
+interface AdapterFilter {
+    emailIn?: string[];
+    externalIdIn?: string[];
+    fieldEquals?: {
+        field: string;
+        value: unknown;
+    };
+    fieldIn?: {
+        field: string;
+        values: unknown[];
+    };
+    fieldExists?: string;
+    hasTag?: string;
+    hasTagIn?: string[];
+    createdAfter?: Date;
+    createdBefore?: Date;
+}
+interface ContactAdapter {
+    getById(externalId: string): Promise<Contact | null>;
+    getByEmail(email: string): Promise<Contact | null>;
+    getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    query(filter: AdapterFilter, opts: {
+        limit: number;
+        cursor?: string;
+    }): Promise<{
+        contacts: Contact[];
+        nextCursor?: string;
+    }>;
+    count(filter: AdapterFilter): Promise<number>;
+    addTags?(externalId: string, tags: string[]): Promise<void>;
+    removeTags?(externalId: string, tags: string[]): Promise<void>;
+}
+type FlowStep = {
+    type: 'wait';
+    value: number;
+    unit: 'minutes' | 'hours' | 'days' | 'weeks';
+} | {
+    type: 'condition';
+    test: Predicate;
+    ifFalse: 'continue' | 'exit';
+} | {
+    type: 'branch';
+    test: Predicate;
+    ifTrueSteps: FlowStep[];
+    ifFalseSteps: FlowStep[];
+} | {
+    type: 'send';
+    templateSlug: string;
+    providerOverride?: string;
+    vars?: Record<string, unknown>;
+} | {
+    type: 'tag';
+    addTags?: string[];
+    removeTags?: string[];
+} | {
+    type: 'fire_event';
+    eventName: string;
+    properties?: Record<string, unknown>;
+} | {
+    type: 'webhook';
+    url: string;
+    method?: 'POST' | 'PUT';
+    payload?: Record<string, unknown>;
+    failureMode?: 'soft' | 'fail_run';
+} | {
+    type: 'exit';
+    reason?: string;
+};
+type Predicate = {
+    hasTag: string;
+} | {
+    notHasTag: string;
+} | {
+    fieldEquals: {
+        field: string;
+        value: unknown;
+    };
+} | {
+    fieldExists: string;
+} | {
+    hasFiredEvent: string;
+    sinceFlowStart?: boolean;
+    withinDays?: number;
+} | {
+    notHasFiredEvent: string;
+    withinDays?: number;
+} | {
+    subscriptionStatus: 'subscribed' | 'unsubscribed' | 'pending_doi' | 'bounced' | 'complained';
+} | {
+    hasOpened: {
+        templateSlug?: string;
+        sinceFlowStart?: boolean;
+        withinDays?: number;
+    };
+} | {
+    hasClicked: {
+        templateSlug?: string;
+        sinceFlowStart?: boolean;
+        withinDays?: number;
+    };
+} | {
+    hasOpenedExcludingBots: {
+        templateSlug?: string;
+        sinceFlowStart?: boolean;
+        withinDays?: number;
+    };
+} | {
+    hasClickedExcludingBots: {
+        templateSlug?: string;
+        sinceFlowStart?: boolean;
+        withinDays?: number;
+    };
+} | {
+    openedAtLeastN: {
+        count: number;
+        withinDays: number;
+    };
+} | {
+    clickedAtLeastN: {
+        count: number;
+        withinDays: number;
+    };
+} | {
+    all: Predicate[];
+} | {
+    any: Predicate[];
+} | {
+    not: Predicate;
+};
+interface SegmentDefinition {
+    filters: SegmentFilter[];
+}
+type SegmentFilter = {
+    kind: 'fieldEquals';
+    field: string;
+    value: unknown;
+} | {
+    kind: 'fieldIn';
+    field: string;
+    values: unknown[];
+} | {
+    kind: 'fieldExists';
+    field: string;
+} | {
+    kind: 'hasTag';
+    tag: string;
+} | {
+    kind: 'notHasTag';
+    tag: string;
+} | {
+    kind: 'subscriptionStatus';
+    equals: 'subscribed' | 'unsubscribed' | 'pending_doi' | 'bounced' | 'complained';
+} | {
+    kind: 'firedEvent';
+    eventName: string;
+    withinDays?: number;
+} | {
+    kind: 'notFiredEvent';
+    eventName: string;
+    withinDays?: number;
+} | {
+    kind: 'subscribedAfter';
+    date: Date;
+} | {
+    kind: 'subscribedBefore';
+    date: Date;
+} | {
+    kind: 'opened';
+    templateSlug?: string;
+    withinDays?: number;
+} | {
+    kind: 'notOpened';
+    templateSlug?: string;
+    withinDays?: number;
+} | {
+    kind: 'any';
+    filters: SegmentFilter[];
+} | {
+    kind: 'not';
+    filter: SegmentFilter;
+};
+interface SendArgs {
+    to: string;
+    fromName: string;
+    fromEmail: string;
+    replyTo?: string;
+    subject: string;
+    html: string;
+    text: string;
+    headers?: Record<string, string>;
+    messageMeta?: Record<string, string>;
+}
+interface SendResult {
+    providerId: string;
+    status: 'accepted' | 'rejected';
+    raw?: unknown;
+}
+interface NormalizedEvent {
+    type: 'delivered' | 'open' | 'click' | 'bounce' | 'complaint' | 'unsubscribe' | 'spam_report';
+    providerEventId: string;
+    providerMessageId: string;
+    email: string;
+    occurredAt: Date;
+    details: {
+        bounceType?: 'hard' | 'soft';
+        bounceReason?: string;
+        clickedUrl?: string;
+        userAgent?: string;
+        ipAddress?: string;
+    };
+}
+interface MailProvider {
+    readonly name: string;
+    /** Per-provider send rate cap (per second). Used by the send-queue rate limiter. */
+    readonly sendRatePerSecond?: number;
+    send(args: SendArgs): Promise<SendResult>;
+    verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
+    parseWebhookEvents(payload: unknown, headers: Record<string, string>): NormalizedEvent[];
+}
+
+/**
+ * Zod schemas for runtime validation at write boundaries — public API entry
+ * points (fire, upsertSubscription, suppress, sendOneOff, scheduleBroadcast)
+ * and REST handler bodies.
+ *
+ * Domain TypeScript types live in `./types.ts`; these schemas overlap with
+ * those types deliberately so we get both compile-time and runtime checking
+ * at the surfaces that need it.
+ */
+
+declare const registerEventSchema: z.ZodObject<{
+    name: z.ZodString;
+    dedupePolicy: z.ZodEnum<{
+        "once-per-contact": "once-per-contact";
+        "once-per-day": "once-per-day";
+        "every-time": "every-time";
+    }>;
+}, z.core.$strip>;
+type RegisterEventInput = z.infer<typeof registerEventSchema>;
+declare const upsertSubscriptionSchema: z.ZodObject<{
+    externalId: z.ZodString;
+    source: z.ZodString;
+    consentTimestamp: z.ZodOptional<z.ZodDate>;
+    consentIp: z.ZodOptional<z.ZodString>;
+    consentUserAgent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UpsertSubscriptionInput = z.infer<typeof upsertSubscriptionSchema>;
+declare const unsubscribeInputSchema: z.ZodObject<{
+    email: z.ZodString;
+    scope: z.ZodEnum<{
+        all: "all";
+        marketing: "marketing";
+        transactional: "transactional";
+    }>;
+    reason: z.ZodDefault<z.ZodEnum<{
+        complaint: "complaint";
+        user_request: "user_request";
+        hard_bounce: "hard_bounce";
+        manual: "manual";
+        gdpr_forget: "gdpr_forget";
+        list_cleaning: "list_cleaning";
+    }>>;
+    source: z.ZodDefault<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UnsubscribeInput = z.infer<typeof unsubscribeInputSchema>;
+declare const suppressInputSchema: z.ZodObject<{
+    email: z.ZodString;
+    scope: z.ZodEnum<{
+        all: "all";
+        marketing: "marketing";
+        transactional: "transactional";
+    }>;
+    reason: z.ZodEnum<{
+        unsubscribed: "unsubscribed";
+        complaint: "complaint";
+        hard_bounce: "hard_bounce";
+        manual: "manual";
+        gdpr_forget: "gdpr_forget";
+        list_cleaning: "list_cleaning";
+    }>;
+    source: z.ZodDefault<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodDate>;
+}, z.core.$strip>;
+type SuppressInput = z.infer<typeof suppressInputSchema>;
+declare const sendOneOffInputSchema: z.ZodObject<{
+    templateSlug: z.ZodString;
+    externalId: z.ZodString;
+    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    providerOverride: z.ZodOptional<z.ZodString>;
+    dedupeKey: z.ZodString;
+}, z.core.$strip>;
+type SendOneOffInput = z.infer<typeof sendOneOffInputSchema>;
+
+/**
+ * Mailer configuration shape. Required + optional surfaces with sane defaults.
+ */
+
+interface RedisOptions {
+    host?: string;
+    port?: number;
+    password?: string;
+    url?: string;
+    db?: number;
+    username?: string;
+    tls?: boolean;
+}
+interface CircuitBreakerThresholds {
+    /** Trip when last-hour hard-bounce rate >= this percent (e.g. 2 = 2%). */
+    hardBounceRatePctTrip: number;
+    complaintRatePctTrip: number;
+    combinedBounceRatePctTrip: number;
+    failedToSendRatePctDegrade: number;
+    windowMinutes: number;
+    minSendsBeforeEval: number;
+}
+interface MailerConfig {
+    db: Db;
+    collectionPrefix?: string;
+    adapter: ContactAdapter;
+    /**
+     * Connection options, a pre-built ioredis instance, or `null` to opt out of
+     * BullMQ entirely (synchronous-only mode — used by tests).
+     */
+    redis: RedisOptions | IORedis | null;
+    providers: Record<string, MailProvider>;
+    defaultProvider: string;
+    defaultTransactionalProvider?: string;
+    publicUrl: string;
+    unsubscribeSecret: string;
+    senderAddress?: string;
+    fromDefaults?: {
+        name: string;
+        email: string;
+    };
+    transactionalFromDefaults?: {
+        name: string;
+        email: string;
+    };
+    requireDoubleOptIn?: boolean;
+    unsubscribeTokenLifetimeDays?: number;
+    transactionalRespectUnsubscribe?: boolean;
+    /** 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. */
+    doiTokenLifetimeDays?: number;
+    circuitBreaker?: Partial<CircuitBreakerThresholds>;
+    broadcastConfirmationThreshold?: number;
+    broadcastEnqueueBatchSize?: number;
+    broadcastEnqueueMaxWaiting?: number;
+    workerless?: boolean;
+    tickIntervalSeconds?: number;
+    sendConcurrency?: number;
+    sendRatePerSecond?: number;
+    softBouncePromotionThreshold?: number;
+    softBouncePromotionWindowDays?: number;
+    webhookRetryAttempts?: number;
+    sendRetryAttempts?: number;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    storeTrackingIp?: boolean;
+    storeRenderedBody?: boolean;
+    getAdminActor?: (req: any) => string;
+    onCircuitBreakerTrip?: (info: {
+        reason: string;
+        rates: Record<string, number>;
+    }) => Promise<void> | void;
+    onSendFailure?: (info: {
+        send: any;
+        error: Error;
+    }) => 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'>> & {
+    circuitBreaker: CircuitBreakerThresholds;
+} & MailerConfig;
+
+/**
+ * Shared enums — string-literal unions for status fields and other discriminators.
+ * Kept separate from types.ts so the client can import these without pulling in
+ * server-shaped interfaces.
+ */
+type SubscriptionStatus = 'subscribed' | 'pending_doi' | 'unsubscribed' | 'bounced' | 'complained';
+type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed';
+type TemplateKind = 'transactional' | 'marketing';
+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';
+type HealthStatus = 'healthy' | 'degraded' | 'tripped';
+type FlowGoal = 'activation' | 'conversion' | 'retention' | 'reactivation' | 'transactional' | 'broadcast';
+
+/**
+ * Mongo collection helpers + indexes for every mailer-owned collection.
+ *
+ * The single source of truth for `mailer_*` schemas lives in
+ * `plans/02-data-model.md`. The TS interfaces here track that doc.
+ *
+ *   const collections = getCollections(db)
+ *   await ensureIndexes(db)
+ *   await collections.events.insertOne({ ... })
+ */
+
+interface SubscriptionDoc {
+    _id?: ObjectId;
+    externalId: string;
+    status: SubscriptionStatus;
+    subscribedAt: Date | null;
+    unsubscribedAt: Date | null;
+    unsubscribeReason: string | null;
+    doiTokenHash: string | null;
+    doiRequestedAt: Date | null;
+    doiConfirmedAt: Date | null;
+    doiIp: string | null;
+    doiUserAgent: string | null;
+    source: string;
+    emailAtSubscribe: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface LeadDoc {
+    _id?: ObjectId;
+    email: string;
+    source: string;
+    capturedFields: Record<string, unknown>;
+    status: 'lead' | 'promoted' | 'rejected';
+    promotedToExternalId: string | null;
+    promotedAt: Date | null;
+    consentedAt: Date | null;
+    consentIp: string | null;
+    unsubscribedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface EventDoc {
+    _id?: ObjectId;
+    externalId: string;
+    name: string;
+    properties: Record<string, unknown>;
+    dedupeKey: string;
+    occurredAt: Date;
+    createdAt: Date;
+}
+interface FlowTrigger {
+    type: 'event' | 'segment_enter' | 'cron';
+    eventName?: string;
+    segmentDefinition?: SegmentDefinition;
+    cronExpression?: string;
+    once: boolean;
+}
+interface FlowDraft {
+    steps: FlowStep[];
+    notes: string;
+    lastModifiedBy: string;
+    lastModifiedAt: Date;
+}
+interface FlowDoc {
+    _id?: ObjectId;
+    slug: string;
+    name: string;
+    description: string;
+    trigger: FlowTrigger;
+    enabled: boolean;
+    steps: FlowStep[];
+    version: number;
+    draft: FlowDraft | null;
+    goal: FlowGoal;
+    audience: string;
+    expectedVolumePerWeek: number | null;
+    stats: {
+        activeRuns: number;
+        completedRuns: number;
+        sendsTotal: number;
+        sendsLast7Days: number;
+    };
+    lastTriggerScanAt: Date | null;
+    publishedAt: Date | null;
+    publishedBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface FlowVersionDoc {
+    _id?: ObjectId;
+    flowId: ObjectId;
+    version: number;
+    steps: FlowStep[];
+    trigger: FlowTrigger;
+    publishedAt: Date;
+    publishedBy: string;
+}
+interface FlowRunHistoryEntry {
+    stepIndex: number;
+    action: 'entered' | 'wait_started' | 'wait_completed' | 'condition_evaluated' | 'branch_taken' | 'sent' | 'send_skipped' | 'tagged' | 'event_fired' | 'webhook_called' | 'exited' | 'failed';
+    at: Date;
+    details?: Record<string, unknown>;
+}
+interface FlowRunDoc {
+    _id?: ObjectId;
+    externalId: string;
+    flowId: ObjectId;
+    flowSlug: string;
+    flowVersion: number;
+    emailAtEntry: string;
+    enteredAt: Date;
+    status: FlowRunStatus;
+    currentStepIndex: number;
+    currentBranchPath: Array<number | 'true' | 'false'>;
+    nextActionAt: Date;
+    attemptsForCurrentStep: number;
+    history: FlowRunHistoryEntry[];
+    exitedAt: Date | null;
+    exitReason: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface TemplateDraft {
+    subject: string;
+    preheader: string;
+    /** MJML source (when template is authored as MJML). Empty string if Maily-authored. */
+    mjml: string;
+    /** Maily editor JSON (when template is authored via the WYSIWYG editor). null otherwise. */
+    editorJson: Record<string, unknown> | null;
+    notes: string;
+    lastModifiedBy: string;
+    lastModifiedAt: Date;
+}
+interface TemplateDoc {
+    _id?: ObjectId;
+    slug: string;
+    name: string;
+    description: string;
+    kind: TemplateKind;
+    fromName: string;
+    fromEmail: string;
+    replyTo: string | null;
+    providerOverride: string | null;
+    subject: string;
+    preheader: string;
+    body: {
+        /** MJML source (set when published from MJML). */
+        mjml: string;
+        /** Maily editor JSON (set when published from the WYSIWYG editor). null otherwise. */
+        editorJson: Record<string, unknown> | null;
+        html: string;
+        plainText: string;
+        compiledAt: Date | null;
+    };
+    variablesSchema: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'date' | 'url';
+        required: boolean;
+        description?: string;
+        defaultValue?: unknown;
+    }>;
+    draft: TemplateDraft | null;
+    tags: string[];
+    trackOpens: boolean;
+    trackClicks: boolean;
+    stats: {
+        sent: number;
+        delivered: number;
+        opened: number;
+        clicked: number;
+        bounced: number;
+        complained: number;
+        unsubscribed: number;
+        lastSentAt: Date | null;
+    };
+    publishedAt: Date | null;
+    publishedBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface TemplateVersionDoc {
+    _id?: ObjectId;
+    templateId: ObjectId;
+    version: number;
+    mjml: string;
+    html: string;
+    plainText: string;
+    subject: string;
+    preheader: string;
+    publishedAt: Date;
+    publishedBy: string;
+}
+interface SendDoc {
+    _id?: ObjectId;
+    dedupeKey: string;
+    externalId: string;
+    emailAtSend: string;
+    templateId: ObjectId;
+    templateSlug: string;
+    flowRunId: ObjectId | null;
+    broadcastId: ObjectId | null;
+    manualSendBy: string | null;
+    kind: TemplateKind;
+    provider: string;
+    providerMessageId: string | null;
+    fromName: string;
+    fromEmail: string;
+    subject: string;
+    bodyHash: string;
+    status: SendStatus;
+    errorMessage: string | null;
+    bounceType: 'hard' | 'soft' | null;
+    bounceReason: string | null;
+    /** Pre-send map: every rewritten link's linkId → original URL. Lookup target on click. */
+    links: Array<{
+        linkId: string;
+        url: string;
+    }>;
+    /** Render-time vars from the flow step or one-off send. Re-applied at dispatch. */
+    vars: Record<string, unknown>;
+    openedAt: Date | null;
+    openCount: number;
+    firstClickAt: Date | null;
+    clickCount: number;
+    /** History of actual clicks (a linkId may appear multiple times). */
+    clickedLinks: Array<{
+        url: string;
+        linkId: string;
+        clickedAt: Date;
+    }>;
+    unsubscribedAt: Date | null;
+    complainedAt: Date | null;
+    queuedAt: Date;
+    sentAt: Date | null;
+    deliveredAt: Date | null;
+}
+interface SuppressionDoc {
+    _id?: ObjectId;
+    email: string | null;
+    emailHash: string;
+    scope: SuppressionScope;
+    reason: SuppressionReason;
+    source: string;
+    notes: string | null;
+    addedAt: Date;
+    expiresAt: Date | null;
+}
+interface BroadcastDoc {
+    _id?: ObjectId;
+    slug: string;
+    name: string;
+    templateSlug: string;
+    segmentDefinition: SegmentDefinition;
+    status: BroadcastStatus;
+    scheduledAt: Date | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    confirmationRequired: boolean;
+    confirmedCount: number | null;
+    confirmedAt: Date | null;
+    confirmedBy: string | null;
+    recipientCount: number | null;
+    /** When true, dispatch fires each recipient at their local-timezone equivalent of `scheduledAt`. */
+    respectRecipientTimezone?: boolean;
+    stats: {
+        sent: number;
+        delivered: number;
+        opened: number;
+        clicked: number;
+        bounced: number;
+        complained: number;
+        unsubscribed: number;
+    };
+    createdAt: Date;
+    createdBy: string;
+    updatedAt: Date;
+}
+interface OutboxDoc {
+    _id?: ObjectId;
+    payload: {
+        type: 'event' | 'upsert_subscription' | 'unsubscribe';
+        data: Record<string, unknown>;
+        dedupeKey: string;
+    };
+    status: 'pending' | 'processed' | 'failed' | 'duplicate';
+    attempts: number;
+    lastAttemptAt: Date | null;
+    lastError: string | null;
+    enqueuedAt: Date;
+    processedAt: Date | null;
+}
+interface AuditLogDoc {
+    _id?: ObjectId;
+    actor: string;
+    action: string;
+    resource: {
+        collection: string;
+        id?: ObjectId | string;
+        slug?: string;
+    };
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+    diffSummary: string | null;
+    ip: string | null;
+    userAgent: string | null;
+    requestId: string | null;
+    occurredAt: Date;
+}
+interface WebhookEventDoc {
+    _id?: ObjectId;
+    provider: string;
+    providerEventId: string;
+    eventType: string;
+    normalizedType: 'delivered' | 'open' | 'click' | 'bounce' | 'complaint' | 'unsubscribe' | 'spam_report';
+    providerMessageId: string;
+    email: string;
+    occurredAt: Date;
+    receivedAt: Date;
+    processed: boolean;
+    raw: unknown;
+}
+interface HealthDoc {
+    _id: 'singleton';
+    windowStartedAt: Date;
+    windowDurationMs: number;
+    counters: {
+        sent: number;
+        delivered: number;
+        bounced: number;
+        hardBounced: number;
+        softBounced: number;
+        complained: number;
+        failedToSend: number;
+    };
+    rates: {
+        bounceRate: number;
+        hardBounceRate: number;
+        complaintRate: number;
+        failureRate: number;
+    };
+    status: HealthStatus;
+    trippedAt: Date | null;
+    trippedReason: string | null;
+    manuallyResumedAt: Date | null;
+    updatedAt: Date;
+}
+interface ContactTagDoc {
+    _id?: ObjectId;
+    externalId: string;
+    tag: string;
+    appliedBy: 'flow' | 'admin' | 'script' | 'import';
+    appliedAt: Date;
+}
+interface Collections {
+    subscriptions: Collection<SubscriptionDoc>;
+    leads: Collection<LeadDoc>;
+    events: Collection<EventDoc>;
+    flows: Collection<FlowDoc>;
+    flowVersions: Collection<FlowVersionDoc>;
+    flowRuns: Collection<FlowRunDoc>;
+    templates: Collection<TemplateDoc>;
+    templateVersions: Collection<TemplateVersionDoc>;
+    sends: Collection<SendDoc>;
+    suppressions: Collection<SuppressionDoc>;
+    broadcasts: Collection<BroadcastDoc>;
+    outbox: Collection<OutboxDoc>;
+    auditLog: Collection<AuditLogDoc>;
+    webhookEvents: Collection<WebhookEventDoc>;
+    health: Collection<HealthDoc>;
+    contactTags: Collection<ContactTagDoc>;
+}
+declare function getCollections(db: Db, prefix?: string): Collections;
+declare function ensureIndexes(db: Db, prefix?: string): Promise<void>;
+
+/**
+ * Event registry + dedupe-key policy. INVARIANT 1: every `mailer_events` row
+ * has a unique dedupeKey. Callers either pass one or `mailer.registerEvent`
+ * declares a policy and we derive it.
+ */
+type DedupePolicy = 'once-per-contact' | 'once-per-day' | 'every-time';
+interface EventRegistration {
+    name: string;
+    dedupePolicy: DedupePolicy;
+}
+declare class EventRegistry {
+    private readonly policies;
+    register(reg: EventRegistration): void;
+    has(name: string): boolean;
+    policy(name: string): DedupePolicy | undefined;
+    /**
+     * Derive a dedupeKey for an event call. Returns null when no policy is
+     * registered AND no key was passed — caller should throw.
+     */
+    deriveKey(name: string, externalId: string, passedKey: string | undefined, now: Date): string | null;
+}
+
+/**
+ * BullMQ wiring: four queues + the corresponding worker factories.
+ *
+ *  mailer:tick      → recovery sweep + event-trigger scan + scheduled broadcasts + outbox drain
+ *  mailer:advance   → per-flow_run wakeup at nextActionAt (delayed jobs)
+ *  mailer:send      → provider dispatch for a single send row
+ *  mailer:webhook   → async normalization + apply of inbound provider events
+ *
+ * The Mailer class instantiates queues at init() and workers at startWorkers().
+ * Job handlers themselves live in `runner/` and `api/webhook-processor.ts`.
+ */
+
+/**
+ * Minimal queue surface the runner depends on. Production wraps BullMQ; tests
+ * can supply a no-op implementation.
+ */
+interface QueueAPI {
+    add(name: string, data: unknown, opts?: {
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: 'exponential';
+            delay: number;
+        };
+        jobId?: string;
+    }): Promise<unknown>;
+    getWaitingCount(): Promise<number>;
+    close(): Promise<void>;
+}
+interface Queues {
+    tick: QueueAPI;
+    advance: QueueAPI;
+    send: QueueAPI;
+    webhook: QueueAPI;
+}
+
+/**
+ * Runner context + public entry points. The shared context object is passed
+ * to every handler so the runner stays a pure function over (state, action).
+ */
+
+interface RunnerContext {
+    db: Db;
+    collections: Collections;
+    adapter: ContactAdapter;
+    providers: Record<string, MailProvider>;
+    queues: Queues;
+    config: ResolvedConfig;
+    handlebarsHelpers?: Record<string, Handlebars.HelperDelegate>;
+}
+
+/**
+ * Mailer — public facade. Hosts call `Mailer.init(config)` and get an object
+ * exposing the public API (fire, upsertSubscription, unsubscribe, ...) plus
+ * mountable Express routers.
+ *
+ * See plans/10-public-api.md for the surface.
+ */
+
+declare class Mailer {
+    readonly db: Db;
+    readonly collections: Collections;
+    readonly adapter: ContactAdapter;
+    readonly providers: Record<string, MailProvider>;
+    readonly redis: IORedis | null;
+    readonly queues: Queues;
+    readonly config: ResolvedConfig;
+    readonly events: EventRegistry;
+    private workers;
+    private bullQueues;
+    private runnerContext;
+    private constructor();
+    /**
+     * Construct a Mailer from environment variables. Reads:
+     *
+     *   MAILER_MONGODB_URI                — Mongo connection string (required)
+     *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
+     *   MAILER_REDIS_URL                  — Redis connection URL (required)
+     *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
+     *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
+     *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)
+     *   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_HOST_USERS_COLLECTION (default 'users')
+     *   MAILER_HOST_USERS_EMAIL_FIELD (default 'email')
+     *   MAILER_HOST_USERS_ID_FIELD (default '_id')
+     *   MAILER_HOST_USERS_TAGS_FIELD
+     *   MAILER_HOST_USERS_TAGS_WRITABLE — '1' or 'true' to enable
+     *
+     * For anything beyond this (custom toContact, custom providers, hooks),
+     * use the programmatic init.
+     */
+    static fromEnv(): Promise<Mailer>;
+    static init(input: MailerConfig): Promise<Mailer>;
+    registerEvent(reg: RegisterEventInput): void;
+    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>;
+    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>;
+    untag(externalId: string, tag: string): Promise<void>;
+    /**
+     * GDPR right-to-erasure. Hard-deletes the contact's PII and leaves a hashed
+     * suppression row to block re-import. INVARIANT 9.
+     */
+    forget(externalId: string): Promise<void>;
+    /** GDPR data export. JSON-serializable. */
+    exportContactData(externalId: string): Promise<Record<string, unknown>>;
+    sendOneOff(input: SendOneOffInput): Promise<{
+        sendId: string;
+    }>;
+    audit(entry: {
+        actor: string;
+        action: string;
+        resource: {
+            collection: string;
+            id?: string | ObjectId;
+            slug?: string;
+        };
+        before?: Record<string, unknown> | null;
+        after?: Record<string, unknown> | null;
+        diffSummary?: string;
+        ip?: string;
+        userAgent?: string;
+        requestId?: string;
+    }): Promise<void>;
+    startWorkers(): Promise<void>;
+    /** Process unprocessed webhook events in mailer_webhook_events. */
+    private processWebhookBacklog;
+    stop(): Promise<void>;
+    /** Used internally by the admin router and tests; not part of the public API. */
+    getRunnerContext(): RunnerContext;
+}
+
+/**
+ * NullProvider — in-memory provider for tests and dev. Records every send
+ * without dispatching anything. Inspect `.sent` to assert what would have
+ * been delivered.
+ */
+
+declare class NullProvider implements MailProvider {
+    readonly name = "null";
+    readonly sendRatePerSecond = 1000;
+    readonly sent: SendArgs[];
+    send(args: SendArgs): Promise<SendResult>;
+    verifyWebhook(): Promise<boolean>;
+    parseWebhookEvents(): NormalizedEvent[];
+    reset(): void;
+}
+
+export { type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type TemplateVersionDoc as D, type EventDoc as E, type FlowDoc as F, ensureIndexes as G, type HealthDoc as H, getCollections as I, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type RedisOptions as R, type SendArgs as S, type TemplateDoc as T, type WebhookEventDoc as W, type Contact as a, type SendResult as b, Mailer as c, type SuppressionScope as d, type AuditLogDoc as e, type BroadcastStatus as f, type CircuitBreakerThresholds as g, type Collections as h, type ContactTagDoc as i, type FlowGoal as j, type FlowRunDoc as k, type FlowRunStatus as l, type FlowStep as m, type FlowVersionDoc as n, type HealthStatus as o, type MailerConfig as p, NullProvider as q, type SegmentDefinition as r, type SegmentFilter as s, type SendDoc as t, type SendStatus as u, type SubscriptionDoc as v, type SubscriptionStatus as w, type SuppressionDoc as x, type SuppressionReason as y, type TemplateKind as z };