mailery 0.3.2 → 0.5.1

package/dist/{null-CGaNDDlQ.d.cts → null-BYB6v4Iv.d.cts}

@@ -430,6 +430,94 @@ interface RedisOptions {
     username?: string;
     tls?: boolean;
 }
+interface DnsblListSpec {
+    /** DNS suffix to query, e.g. `'dbl.spamhaus.org'`. */
+    host: string;
+    /** Display label for the UI, e.g. `'Spamhaus DBL'`. */
+    label: string;
+}
+interface DnsblConfig {
+    /** Domain block lists (DBLs) — queried as `<domain>.<host>`. */
+    domainLists?: DnsblListSpec[];
+    /** IP block lists — queried as `<reversed-octets>.<host>`. */
+    ipLists?: DnsblListSpec[];
+    /** Dedicated sending IPs to check. Most operators on shared ESPs leave empty. */
+    dedicatedIps?: string[];
+    /** Hours between automatic runs. Default 24. Set to 0 to disable scheduled runs. */
+    intervalHours?: number;
+}
+interface MailTesterConfig {
+    /** API key from your Mail-Tester paid plan. */
+    apiKey: string;
+    /** Minimum score (0-10) below which publish is blocked. Default 8.0. */
+    minScore?: number;
+    /**
+     * How long a successful score remains cached for the same content. Default 24.
+     * Re-publishing the same body within the window does not burn a credit.
+     */
+    cacheHours?: number;
+    /** API base URL. Defaults to `https://mail-tester.com/api`. Override for staging or alternate provider. */
+    baseUrl?: string;
+}
+interface DmarcSourceTag {
+    /** Source IP, e.g. `'149.72.45.10'`. */
+    ip: string;
+    /** Operator-provided label, e.g. `'SendGrid (transactional)'` or `'Hubspot'`. */
+    label: string;
+    /** When true, ignore failures from this source in the alignment-trend headline. */
+    ignored?: boolean;
+}
+interface DmarcConfig {
+    /**
+     * Operator-tagged sources. After RUA reports start arriving, the operator
+     * marks each source IP as known/legit (with a label) or rogue. Tagged
+     * sources are excluded from the headline failure count, surfacing only
+     * unknown senders.
+     */
+    knownSources?: DmarcSourceTag[];
+    /**
+     * How many days of failure rows to retain. Default 90. Older rows are
+     * trimmed by the daily tick to keep the collection bounded.
+     */
+    retentionDays?: number;
+}
+interface SndsConfig {
+    /**
+     * SNDS automated-access key. Obtained per-account from the SNDS portal at
+     * https://sendersupport.olc.protection.outlook.com/snds/ once each
+     * sending IP has been added and verified.
+     */
+    accessKey: string;
+    /**
+     * Optional IP filter — when set, only rows for these IPs are persisted.
+     * Useful when an SNDS account covers a wider IP pool than this mailery
+     * deployment uses. Defaults to keeping all rows the API returns.
+     */
+    ips?: string[];
+    /** Hours between automatic pulls. Default 24. Set to 0 to disable scheduled pulls. */
+    intervalHours?: number;
+}
+interface PostmasterConfig {
+    /** OAuth client ID from a Google Cloud project with Postmaster Tools API enabled. */
+    clientId: string;
+    clientSecret: string;
+    /**
+     * A refresh token obtained via the OAuth consent flow with scope
+     * `https://www.googleapis.com/auth/postmaster.readonly` for the user that
+     * verified the domain(s) in Postmaster Tools. See
+     * docs/guide/deliverability.md → "Google Postmaster Tools" for the
+     * one-time setup procedure.
+     */
+    refreshToken: string;
+    /**
+     * Domains to pull data for. When omitted, mailery uses every domain from the
+     * senderDomains registry plus the From defaults. Each must be verified in
+     * Postmaster Tools under the same Google account.
+     */
+    domains?: string[];
+    /** Hours between automatic pulls. Default 24. Set to 0 to disable scheduled pulls. */
+    intervalHours?: number;
+}
 interface CircuitBreakerThresholds {
     /** Trip when last-hour hard-bounce rate >= this percent (e.g. 2 = 2%). */
     hardBounceRatePctTrip: number;
@@ -481,6 +569,41 @@ interface MailerConfig {
     /** How long the DOI token stays valid. Default 7 days. */
     doiTokenLifetimeDays?: number;
     circuitBreaker?: Partial<CircuitBreakerThresholds>;
+    /**
+     * Daily DNS-based block-list checks on sender domains and (optionally) any
+     * dedicated sending IPs. Results surface in setup-status and on the Health
+     * screen. No external API needed — plain DNS lookups.
+     */
+    dnsbl?: DnsblConfig;
+    /**
+     * Pulls daily reputation tiers + spam ratio + auth pass rates from Google
+     * Postmaster Tools. Trips the (domain × marketing) circuit breaker when a
+     * domain falls to reputation `BAD`. Only meaningful at >100/day to Gmail.
+     */
+    postmaster?: PostmasterConfig;
+    /**
+     * Pulls daily Outlook/Hotmail/Live IP reputation from Microsoft's Smart
+     * Network Data Services. IP-level rather than domain-level — only useful
+     * if you send from a dedicated IP. Visibility-only: RED filter results
+     * surface as a setup-status error, no auto-trip.
+     */
+    snds?: SndsConfig;
+    /**
+     * Optional Mail-Tester integration. When set, the template editor exposes
+     * a "Run deliverability check" button that sends a copy of the rendered
+     * draft to a Mail-Tester address and polls for a score (0-10) covering
+     * SpamAssassin verdict, auth alignment, content red flags, and link
+     * reputation. Score < minScore blocks publish until re-run or overridden.
+     */
+    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.
+     */
+    dmarc?: DmarcConfig;
     broadcastConfirmationThreshold?: number;
     broadcastEnqueueBatchSize?: number;
     broadcastEnqueueMaxWaiting?: number;
@@ -834,8 +957,22 @@ interface WebhookEventDoc {
     processed: boolean;
     raw: unknown;
 }
+/**
+ * Health bucket. One doc per (senderDomain, kind) pair plus a single aggregate
+ * doc with _id='agg' that rolls up everything.
+ *
+ *   _id: 'agg'                              // cross-domain, cross-kind roll-up
+ *   _id: 'd:<senderDomain>|k:<kind>'        // per-bucket
+ *
+ * The aggregate is informational only — it never trips. Trips live on
+ * buckets so one subdomain tanking doesn't hold mail for the others.
+ */
 interface HealthDoc {
-    _id: 'singleton';
+    _id: string;
+    /** null on the aggregate doc, set on bucket docs. */
+    senderDomain: string | null;
+    /** null on the aggregate doc, set on bucket docs. */
+    kind: TemplateKind | null;
     windowStartedAt: Date;
     windowDurationMs: number;
     counters: {
@@ -859,6 +996,167 @@ interface HealthDoc {
     manuallyResumedAt: Date | null;
     updatedAt: Date;
 }
+type PostmasterReputation = 'HIGH' | 'MEDIUM' | 'LOW' | 'BAD' | 'REPUTATION_CATEGORY_UNSPECIFIED';
+/**
+ * One day's traffic stats for a domain from Google Postmaster Tools.
+ * Stored per (domain, date) so we can chart trends.
+ */
+interface PostmasterSnapshotDoc {
+    _id?: ObjectId;
+    domain: string;
+    /** Reporting date in YYYY-MM-DD per Postmaster's stat day. */
+    date: string;
+    domainReputation: PostmasterReputation | null;
+    ipReputations: Array<{
+        reputation: PostmasterReputation;
+        ipCount: number;
+    }> | null;
+    userReportedSpamRatio: number | null;
+    spfSuccessRatio: number | null;
+    dkimSuccessRatio: number | null;
+    dmarcSuccessRatio: number | null;
+    outboundEncryptionRatio: number | null;
+    inboundEncryptionRatio: number | null;
+    deliveryErrors: Array<{
+        errorType: string;
+        errorClass: string;
+        errorRatio: number;
+    }> | null;
+    spammyFeedbackLoops: Array<{
+        id: string;
+        spamRatio: number;
+    }> | null;
+    fetchedAt: Date;
+}
+interface MailTesterFeedback {
+    category: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+}
+/**
+ * Cached Mail-Tester deliverability score for a given (template content)
+ * fingerprint. Operators don't burn a credit re-running on identical
+ * content within cacheHours.
+ */
+interface MailTesterScoreDoc {
+    _id?: ObjectId;
+    templateSlug: string;
+    /** Hash of bodyHash + subject + fromEmail — the cache key. */
+    contentKey: string;
+    checkId: string;
+    score: number;
+    feedback: MailTesterFeedback[];
+    rawSummary: string | null;
+    fetchedAt: Date;
+    expiresAt: Date;
+}
+type DmarcPolicy = 'none' | 'quarantine' | 'reject';
+type DmarcAuthResult = 'pass' | 'fail' | 'softfail' | 'neutral' | 'temperror' | 'permerror' | 'none' | 'unknown';
+/**
+ * One DMARC RUA aggregate report. Receivers (Google, Yahoo, Microsoft, etc.)
+ * email one per day per sending domain. We store one DmarcReportDoc per
+ * incoming report, plus one DmarcFailureDoc per non-aligned record row.
+ */
+interface DmarcReportDoc {
+    _id?: ObjectId;
+    reportId: string;
+    /** Reporting org, e.g. 'google.com', 'enterprise.protection.outlook.com'. */
+    orgName: string;
+    /** Reporter contact email from <report_metadata>. */
+    email: string;
+    /** The domain we publish DMARC for, from <policy_published><domain>. */
+    domain: string;
+    policyP: DmarcPolicy;
+    /** % of mail subject to the policy (1-100). */
+    policyPct: number;
+    /** Activity window the report covers. */
+    rangeStart: Date;
+    rangeEnd: Date;
+    /** Sum of <count> across all records. */
+    totalMessages: number;
+    /** Messages that passed DMARC (DKIM aligned OR SPF aligned). */
+    passCount: number;
+    failCount: number;
+    receivedAt: Date;
+}
+/**
+ * One alignment-failing source × day. Composite key `(sourceIp, domain, day)`
+ * lets us roll up "this IP sent N misaligned messages over the past week."
+ * Failures from multiple reports for the same key get counted once per
+ * report (we de-dupe on reportId × sourceIp).
+ */
+interface DmarcFailureDoc {
+    _id?: ObjectId;
+    reportId: string;
+    domain: string;
+    sourceIp: string;
+    count: number;
+    headerFrom: string;
+    dkimResult: DmarcAuthResult;
+    spfResult: DmarcAuthResult;
+    dispositionApplied: 'none' | 'quarantine' | 'reject' | string;
+    /** YYYY-MM-DD bucket derived from the reporting window's mid-point. */
+    day: string;
+    receivedAt: Date;
+}
+/**
+ * Operator-set DMARC source tag. Created/updated/deleted from the admin UI
+ * so operators can mark "this IP is our SendGrid", "this is Hubspot", etc.
+ * Merged with `MailerConfig.dmarc.knownSources` at read time — the config
+ * version is read-only baseline, the collection is mutable runtime state.
+ */
+interface DmarcSourceTagDoc {
+    _id?: ObjectId;
+    ip: string;
+    label: string;
+    ignored: boolean;
+    setBy: string;
+    setAt: Date;
+}
+type SndsFilterResult = 'GREEN' | 'YELLOW' | 'RED' | 'UNKNOWN';
+/**
+ * One row from a Microsoft SNDS data export covering a single activity
+ * window for one sending IP. Stored unique per (ip, activityStart) so
+ * historical windows accumulate without re-writing.
+ */
+interface SndsSnapshotDoc {
+    _id?: ObjectId;
+    ip: string;
+    activityStart: Date;
+    activityEnd: Date;
+    rcptCommands: number;
+    dataCommands: number;
+    messageRecipients: number;
+    filterResult: SndsFilterResult;
+    /** 0-1 fraction. SNDS reports as "<0.1%", "0.1-0.3%", etc; we store the upper bound. null when unknown. */
+    complaintRate: number | null;
+    trapMessageCount: number;
+    sampleHelo: string | null;
+    sampleMailFrom: string | null;
+    fetchedAt: Date;
+}
+type DnsblResult = 'clean' | 'listed' | 'error';
+type DnsblTargetKind = 'domain' | 'ip';
+/**
+ * Latest DNSBL check result per (target, list). Replaced in-place on each run
+ * so the collection stays small. History (if needed later) lives in audit_log.
+ */
+interface DnsblCheckDoc {
+    _id?: ObjectId;
+    /** Domain (e.g. `mkt.example.com`) or dotted-quad IP (e.g. `203.0.113.5`). */
+    target: string;
+    targetKind: DnsblTargetKind;
+    /** DNS suffix queried (e.g. `dbl.spamhaus.org`). */
+    list: string;
+    /** Display label for the UI (e.g. `Spamhaus DBL`). */
+    listLabel: string;
+    result: DnsblResult;
+    /** A records returned by the lookup, when listed. */
+    returnCodes: string[];
+    /** When result is 'error', the message; otherwise null. */
+    errorMessage: string | null;
+    runAt: Date;
+}
 interface ContactTagDoc {
     _id?: ObjectId;
     externalId: string;
@@ -883,6 +1181,13 @@ interface Collections {
     webhookEvents: Collection<WebhookEventDoc>;
     health: Collection<HealthDoc>;
     contactTags: Collection<ContactTagDoc>;
+    dnsblChecks: Collection<DnsblCheckDoc>;
+    postmasterSnapshots: Collection<PostmasterSnapshotDoc>;
+    sndsSnapshots: Collection<SndsSnapshotDoc>;
+    dmarcReports: Collection<DmarcReportDoc>;
+    dmarcFailures: Collection<DmarcFailureDoc>;
+    dmarcSourceTags: Collection<DmarcSourceTagDoc>;
+    mailTesterScores: Collection<MailTesterScoreDoc>;
 }
 declare function getCollections(db: Db, prefix?: string): Collections;
 declare function ensureIndexes(db: Db, prefix?: string): Promise<void>;
@@ -902,6 +1207,7 @@ declare class EventRegistry {
     register(reg: EventRegistration): void;
     has(name: string): boolean;
     policy(name: string): DedupePolicy | undefined;
+    list(): EventRegistration[];
     /**
      * Derive a dedupeKey for an event call. Returns null when no policy is
      * registered AND no key was passed — caller should throw.
@@ -922,6 +1228,22 @@ interface RunnerContext {
     queues: Queues;
     config: ResolvedConfig;
     handlebarsHelpers?: Record<string, Handlebars.HelperDelegate>;
+    /**
+     * Optional audit-log writer. Available when the runner context is derived
+     * from a Mailer instance (Mailer.getRunnerContext()); absent in some
+     * lightweight test harnesses. Runner code that uses this must tolerate
+     * `undefined`.
+     */
+    audit?: (entry: {
+        actor: string;
+        action: string;
+        resource: {
+            collection: string;
+            id?: string;
+            slug?: string;
+        };
+        diffSummary?: string;
+    }) => Promise<void>;
 }
 
 /**
@@ -1024,4 +1346,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-export { type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type SubscriptionStatus as D, type EventDoc as E, type FlowStep as F, type SuppressionDoc as G, type HealthDoc as H, type SuppressionReason as I, type TemplateKind as J, type TemplateVersionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, ensureIndexes as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, getCollections as U, validateSenderDomain as V, type WebhookEventDoc as W, type Contact as a, type SendResult as b, Mailer as c, type SuppressionScope as d, type SegmentFilter as e, type AuditLogDoc as f, type BroadcastStatus as g, type CircuitBreakerThresholds as h, type Collections as i, type ContactTagDoc as j, type FlowDoc as k, type FlowGoal as l, type FlowRunDoc as m, type FlowRunStatus as n, type FlowVersionDoc as o, type HealthStatus as p, type MailerConfig as q, NullProvider as r, type RedisOptions as s, type SegmentDefinition as t, type SendDoc as u, type SendStatus as v, type SenderDomainConfig as w, type SenderDomainRegistry as x, type SenderDomainValidation as y, type SubscriptionDoc as z };
+export { type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type SubscriptionDoc as D, type EventDoc as E, type FlowStep as F, type SubscriptionStatus as G, type HealthDoc as H, type SuppressionDoc as I, type SuppressionReason as J, type TemplateKind as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type TemplateVersionDoc as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, ensureIndexes as U, getCollections as V, type WebhookEventDoc as W, validateSenderDomain as X, type Contact as a, 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, type RedisOptions as t, type SegmentDefinition as u, type SendDoc as v, type SendStatus as w, type SenderDomainConfig as x, type SenderDomainRegistry as y, type SenderDomainValidation as z };