@aglyn/tenant-data-admin 1.0.0-beta.200 → 1.0.0-beta.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/tenant-data-admin",
-  "version": "1.0.0-beta.200",
+  "version": "1.0.0-beta.201",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,12 +25,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.200",
-    "@aglyn/shared-util-email": "1.0.0-beta.200",
-    "@aglyn/shared-util-fbserver": "1.0.0-beta.200",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.200",
-    "@aglyn/shared-util-http": "1.0.0-beta.200",
-    "@aglyn/shared-util-tools": "1.0.0-beta.200",
+    "@aglyn/aglyn": "1.0.0-beta.201",
+    "@aglyn/shared-util-email": "1.0.0-beta.201",
+    "@aglyn/shared-util-fbserver": "1.0.0-beta.201",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.201",
+    "@aglyn/shared-util-http": "1.0.0-beta.201",
+    "@aglyn/shared-util-tools": "1.0.0-beta.201",
     "@msgpack/msgpack": "^3.1.3",
     "@swc/helpers": "0.5.23",
     "sharp": "^0.35.3",
@@ -43,6 +43,7 @@
   },
   "sideEffects": [
     "./src/lib/server/client-error-report.*",
+    "./src/lib/server/email-deliverability.*",
     "./src/lib/server/email-marketing-gate.*",
     "./src/lib/server/email-send-rate.*"
   ],

package/src/lib/server/dns-probe.d.ts

@@ -51,3 +51,10 @@ export interface MxRecord {
 }
 /** MX records at `host`, exchanges lowercased and stripped of a trailing dot. */
 export declare function lookupMx(host: string): Promise<DnsLookupResult<MxRecord>>;
+/**
+ * Whether `host` has an address record, A or AAAA — the implicit MX a domain
+ * with no MX is still delivered to (RFC 5321 §5.1). `records` holds the
+ * addresses found; empty on a conclusive "none". Unanswered only when
+ * neither family could be asked.
+ */
+export declare function lookupAddress(host: string): Promise<DnsLookupResult<string>>;

package/src/lib/server/dns-probe.js

@@ -180,5 +180,57 @@
         }
     }
 }
+/**
+ * Whether `host` has an address record, A or AAAA — the implicit MX a domain
+ * with no MX is still delivered to (RFC 5321 §5.1). `records` holds the
+ * addresses found; empty on a conclusive "none". Unanswered only when
+ * neither family could be asked.
+ */ export async function lookupAddress(host) {
+    const ask = async (family)=>{
+        try {
+            const resolver = new CallbackResolver();
+            resolver.setServers(PUBLIC_DNS_RESOLVERS);
+            const records = await new Promise((resolve, reject)=>{
+                const done = (error, addresses)=>error ? reject(error) : resolve(addresses);
+                if (family === 4) resolver.resolve4(host, done);
+                else resolver.resolve6(host, done);
+            });
+            return {
+                answered: true,
+                records
+            };
+        } catch (error) {
+            const code = error == null ? void 0 : error.code;
+            if (isConclusiveDnsCode(code)) return {
+                answered: true,
+                records: []
+            };
+            try {
+                return {
+                    answered: true,
+                    records: family === 4 ? await dns.resolve4(host) : await dns.resolve6(host)
+                };
+            } catch (fallbackError) {
+                const fallbackCode = fallbackError == null ? void 0 : fallbackError.code;
+                if (isConclusiveDnsCode(fallbackCode)) return {
+                    answered: true,
+                    records: []
+                };
+                return {
+                    answered: false,
+                    records: []
+                };
+            }
+        }
+    };
+    const v4 = await ask(4);
+    if (v4.records.length) return v4;
+    const v6 = await ask(6);
+    if (v6.records.length) return v6;
+    return {
+        answered: v4.answered && v6.answered,
+        records: []
+    };
+}
 
 //# sourceMappingURL=dns-probe.js.map

package/src/lib/server/dns-probe.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dns-probe.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * One DNS lookup, pinned to public resolvers, that can say \"I do not know\".\n *\n * The same shape appeared independently in `/api/domains/verify` (AGL-734) and\n * in `sso-provisioning.ts` (AGL-1210), and a third copy was about to be\n * written for sending domains. It is here once instead.\n *\n * ## Why the resolvers are pinned\n *\n * The runtime's default resolver is not a neutral observer. A stale zone once\n * made the hosting platform's own resolver return NXDOMAIN for records every\n * public resolver could see, which reads as \"the customer deleted their\n * record\" and is indistinguishable from the real thing. Asking a public\n * resolver first, and falling back to the runtime's only when the pinned ones\n * are unreachable, keeps a genuine \"no such record\" answer conclusive.\n *\n * ## Why there are three outcomes and not two\n *\n * A boolean cannot tell \"the record is gone\" from \"nobody answered\", and the\n * difference decides whether a customer's working configuration gets marked\n * broken during someone else's outage. `NXDOMAIN`/`ENOTFOUND`/`ENODATA` are\n * ANSWERS — that name has no such record — and stay conclusive. Anything else,\n * from both the pinned resolvers and the fallback, is `unreachable`, and a\n * caller must treat it as evidence of nothing in either direction.\n */\n\nimport { promises as dns, Resolver as CallbackResolver } from 'dns'\n\n/** Resolvers asked before the runtime's own. */\nexport const PUBLIC_DNS_RESOLVERS = ['1.1.1.1', '8.8.8.8']\n\n/** Whether a resolver error code is an answer rather than a failure to get one. */\nexport function isConclusiveDnsCode(code: string | undefined): boolean {\n  return code === 'ENOTFOUND' || code === 'ENODATA' || code === 'NXDOMAIN'\n}\n\nexport interface DnsLookupResult<T> {\n  /**\n   * True when the lookup got an answer, including the answer \"there is\n   * nothing here\". False only when nobody answered.\n   */\n  answered: boolean\n  /** Empty on a conclusive miss and on an unreachable lookup alike. */\n  records: T[]\n}\n\n/**\n * TXT records at `host`, each joined from its chunks and trimmed.\n *\n * A TXT answer arrives as an array of string CHUNKS per record, because DNS\n * splits strings longer than 255 bytes. Comparing without joining means a long\n * value — every DKIM public key, for instance — can never match.\n */\nexport async function lookupTxt(host: string): Promise<DnsLookupResult<string>> {\n  const flatten = (records: string[][]) =>\n    records.map((chunks) => chunks.join('').trim())\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<string[][]>((resolve, reject) => {\n      resolver.resolveTxt(host, (error, addresses) =>\n        error ? reject(error) : resolve(addresses),\n      )\n    })\n    return { answered: true, records: flatten(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return { answered: true, records: flatten(await dns.resolveTxt(host)) }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\n/**\n * CAA records at `host`, as `<flags> <tag> \"<value>\"` strings.\n *\n * NOT walked up the tree. The caller asks about one exact name, because the\n * question this exists for is \"does THIS name publish a policy of its own\",\n * and a walk would answer a different one — a parent's policy is inherited by\n * resolution, not by publication, and reporting the parent's records as the\n * child's would say a name restricts issuance when it publishes nothing.\n */\nexport async function lookupCaa(host: string): Promise<DnsLookupResult<string>> {\n  const normalize = (records: unknown[]) =>\n    records\n      .map((entry) => {\n        const row = entry as { critical?: number; issue?: string; issuewild?: string; iodef?: string }\n        const tag = row?.issue !== undefined\n          ? 'issue'\n          : row?.issuewild !== undefined\n            ? 'issuewild'\n            : row?.iodef !== undefined\n              ? 'iodef'\n              : ''\n        if (!tag) return ''\n        const value = String(\n          row.issue ?? row.issuewild ?? row.iodef ?? '',\n        ).trim()\n        return `${Number(row?.critical) || 0} ${tag} \"${value}\"`\n      })\n      .filter(Boolean)\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<unknown[]>((resolve, reject) => {\n      resolver.resolveCaa(host, (error, addresses) =>\n        error ? reject(error) : resolve(addresses as unknown[]),\n      )\n    })\n    return { answered: true, records: normalize(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return {\n        answered: true,\n        records: normalize((await dns.resolveCaa(host)) as unknown[]),\n      }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\nexport interface MxRecord {\n  exchange: string\n  priority: number\n}\n\n/** MX records at `host`, exchanges lowercased and stripped of a trailing dot. */\nexport async function lookupMx(host: string): Promise<DnsLookupResult<MxRecord>> {\n  const normalize = (records: { exchange: string; priority: number }[]) =>\n    records.map((entry) => ({\n      exchange: String(entry?.exchange ?? '')\n        .trim()\n        .toLowerCase()\n        .replace(/\\.$/, ''),\n      priority: Number(entry?.priority) || 0,\n    }))\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<{ exchange: string; priority: number }[]>(\n      (resolve, reject) => {\n        resolver.resolveMx(host, (error, addresses) =>\n          error ? reject(error) : resolve(addresses),\n        )\n      },\n    )\n    return { answered: true, records: normalize(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return { answered: true, records: normalize(await dns.resolveMx(host)) }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n"],"names":["promises","dns","Resolver","CallbackResolver","PUBLIC_DNS_RESOLVERS","isConclusiveDnsCode","code","lookupTxt","host","flatten","records","map","chunks","join","trim","resolver","setServers","Promise","resolve","reject","resolveTxt","error","addresses","answered","fallbackError","fallbackCode","lookupCaa","normalize","entry","row","tag","issue","undefined","issuewild","iodef","value","String","Number","critical","filter","Boolean","resolveCaa","lookupMx","exchange","toLowerCase","replace","priority","resolveMx"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dns-probe.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * One DNS lookup, pinned to public resolvers, that can say \"I do not know\".\n *\n * The same shape appeared independently in `/api/domains/verify` (AGL-734) and\n * in `sso-provisioning.ts` (AGL-1210), and a third copy was about to be\n * written for sending domains. It is here once instead.\n *\n * ## Why the resolvers are pinned\n *\n * The runtime's default resolver is not a neutral observer. A stale zone once\n * made the hosting platform's own resolver return NXDOMAIN for records every\n * public resolver could see, which reads as \"the customer deleted their\n * record\" and is indistinguishable from the real thing. Asking a public\n * resolver first, and falling back to the runtime's only when the pinned ones\n * are unreachable, keeps a genuine \"no such record\" answer conclusive.\n *\n * ## Why there are three outcomes and not two\n *\n * A boolean cannot tell \"the record is gone\" from \"nobody answered\", and the\n * difference decides whether a customer's working configuration gets marked\n * broken during someone else's outage. `NXDOMAIN`/`ENOTFOUND`/`ENODATA` are\n * ANSWERS — that name has no such record — and stay conclusive. Anything else,\n * from both the pinned resolvers and the fallback, is `unreachable`, and a\n * caller must treat it as evidence of nothing in either direction.\n */\n\nimport { promises as dns, Resolver as CallbackResolver } from 'dns'\n\n/** Resolvers asked before the runtime's own. */\nexport const PUBLIC_DNS_RESOLVERS = ['1.1.1.1', '8.8.8.8']\n\n/** Whether a resolver error code is an answer rather than a failure to get one. */\nexport function isConclusiveDnsCode(code: string | undefined): boolean {\n  return code === 'ENOTFOUND' || code === 'ENODATA' || code === 'NXDOMAIN'\n}\n\nexport interface DnsLookupResult<T> {\n  /**\n   * True when the lookup got an answer, including the answer \"there is\n   * nothing here\". False only when nobody answered.\n   */\n  answered: boolean\n  /** Empty on a conclusive miss and on an unreachable lookup alike. */\n  records: T[]\n}\n\n/**\n * TXT records at `host`, each joined from its chunks and trimmed.\n *\n * A TXT answer arrives as an array of string CHUNKS per record, because DNS\n * splits strings longer than 255 bytes. Comparing without joining means a long\n * value — every DKIM public key, for instance — can never match.\n */\nexport async function lookupTxt(host: string): Promise<DnsLookupResult<string>> {\n  const flatten = (records: string[][]) =>\n    records.map((chunks) => chunks.join('').trim())\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<string[][]>((resolve, reject) => {\n      resolver.resolveTxt(host, (error, addresses) =>\n        error ? reject(error) : resolve(addresses),\n      )\n    })\n    return { answered: true, records: flatten(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return { answered: true, records: flatten(await dns.resolveTxt(host)) }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\n/**\n * CAA records at `host`, as `<flags> <tag> \"<value>\"` strings.\n *\n * NOT walked up the tree. The caller asks about one exact name, because the\n * question this exists for is \"does THIS name publish a policy of its own\",\n * and a walk would answer a different one — a parent's policy is inherited by\n * resolution, not by publication, and reporting the parent's records as the\n * child's would say a name restricts issuance when it publishes nothing.\n */\nexport async function lookupCaa(host: string): Promise<DnsLookupResult<string>> {\n  const normalize = (records: unknown[]) =>\n    records\n      .map((entry) => {\n        const row = entry as { critical?: number; issue?: string; issuewild?: string; iodef?: string }\n        const tag = row?.issue !== undefined\n          ? 'issue'\n          : row?.issuewild !== undefined\n            ? 'issuewild'\n            : row?.iodef !== undefined\n              ? 'iodef'\n              : ''\n        if (!tag) return ''\n        const value = String(\n          row.issue ?? row.issuewild ?? row.iodef ?? '',\n        ).trim()\n        return `${Number(row?.critical) || 0} ${tag} \"${value}\"`\n      })\n      .filter(Boolean)\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<unknown[]>((resolve, reject) => {\n      resolver.resolveCaa(host, (error, addresses) =>\n        error ? reject(error) : resolve(addresses as unknown[]),\n      )\n    })\n    return { answered: true, records: normalize(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return {\n        answered: true,\n        records: normalize((await dns.resolveCaa(host)) as unknown[]),\n      }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\nexport interface MxRecord {\n  exchange: string\n  priority: number\n}\n\n/** MX records at `host`, exchanges lowercased and stripped of a trailing dot. */\nexport async function lookupMx(host: string): Promise<DnsLookupResult<MxRecord>> {\n  const normalize = (records: { exchange: string; priority: number }[]) =>\n    records.map((entry) => ({\n      exchange: String(entry?.exchange ?? '')\n        .trim()\n        .toLowerCase()\n        .replace(/\\.$/, ''),\n      priority: Number(entry?.priority) || 0,\n    }))\n\n  try {\n    const resolver = new CallbackResolver()\n    resolver.setServers(PUBLIC_DNS_RESOLVERS)\n    const records = await new Promise<{ exchange: string; priority: number }[]>(\n      (resolve, reject) => {\n        resolver.resolveMx(host, (error, addresses) =>\n          error ? reject(error) : resolve(addresses),\n        )\n      },\n    )\n    return { answered: true, records: normalize(records) }\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code\n    if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n    try {\n      return { answered: true, records: normalize(await dns.resolveMx(host)) }\n    } catch (fallbackError) {\n      const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n      return { answered: false, records: [] }\n    }\n  }\n}\n\n/**\n * Whether `host` has an address record, A or AAAA — the implicit MX a domain\n * with no MX is still delivered to (RFC 5321 §5.1). `records` holds the\n * addresses found; empty on a conclusive \"none\". Unanswered only when\n * neither family could be asked.\n */\nexport async function lookupAddress(host: string): Promise<DnsLookupResult<string>> {\n  const ask = async (family: 4 | 6): Promise<DnsLookupResult<string>> => {\n    try {\n      const resolver = new CallbackResolver()\n      resolver.setServers(PUBLIC_DNS_RESOLVERS)\n      const records = await new Promise<string[]>((resolve, reject) => {\n        const done = (error: NodeJS.ErrnoException | null, addresses: string[]) =>\n          error ? reject(error) : resolve(addresses)\n        if (family === 4) resolver.resolve4(host, done)\n        else resolver.resolve6(host, done)\n      })\n      return { answered: true, records }\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException)?.code\n      if (isConclusiveDnsCode(code)) return { answered: true, records: [] }\n      try {\n        return {\n          answered: true,\n          records: family === 4 ? await dns.resolve4(host) : await dns.resolve6(host),\n        }\n      } catch (fallbackError) {\n        const fallbackCode = (fallbackError as NodeJS.ErrnoException)?.code\n        if (isConclusiveDnsCode(fallbackCode)) return { answered: true, records: [] }\n        return { answered: false, records: [] }\n      }\n    }\n  }\n  const v4 = await ask(4)\n  if (v4.records.length) return v4\n  const v6 = await ask(6)\n  if (v6.records.length) return v6\n  return { answered: v4.answered && v6.answered, records: [] }\n}\n"],"names":["promises","dns","Resolver","CallbackResolver","PUBLIC_DNS_RESOLVERS","isConclusiveDnsCode","code","lookupTxt","host","flatten","records","map","chunks","join","trim","resolver","setServers","Promise","resolve","reject","resolveTxt","error","addresses","answered","fallbackError","fallbackCode","lookupCaa","normalize","entry","row","tag","issue","undefined","issuewild","iodef","value","String","Number","critical","filter","Boolean","resolveCaa","lookupMx","exchange","toLowerCase","replace","priority","resolveMx","lookupAddress","ask","family","done","resolve4","resolve6","v4","length","v6"],"mappings":"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"}

package/src/lib/server/email-deliverability.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type EmailDeliverabilityPreflightRequest, type EmailDeliverabilityPreflightVerdict, type EmailDeliverabilityVerdict, type EmailDeliveryEvent, type EmailSendPurpose, type MailDnsResolver, type MailDomainIntel, type MailGateway, type MailGatewayLedger, type MailGatewayOutcome, type MailGatewayStanding } from '@aglyn/shared-util-email';
+import type { EmailDeliveryEventOutcome } from './email-delivery-log';
+type Firestore = FirebaseFirestore.Firestore;
+/** The platform MX cache, keyed by recipient domain. */
+export declare const MAIL_DOMAINS_COLLECTION = "mailDomains";
+/** The gateway ledger, at the top level and under an organization — see the module note. */
+export declare const MAIL_GATEWAY_LEDGER_COLLECTION = "mailGatewayLedger";
+/**
+ * Where a ledger lives: `null` for the top level (a Resend sending domain),
+ * or the organization a connected mailbox belongs to.
+ */
+export type MailGatewayLedgerScope = {
+    orgId: string;
+} | null;
+/** What the reads and writes here need beside their input; every field defaults to the platform's. */
+export interface MailDeliverabilityDeps {
+    firestore?: Firestore;
+    resolver?: MailDnsResolver;
+    nowMs?: number;
+}
+/**
+ * The platform's resolver: the pinned public resolvers first, and — for the
+ * one answer that stops mail, "no MX" — the runtime's own as a second
+ * opinion that must agree. See the module note.
+ */
+export declare function platformMailDnsResolver(): MailDnsResolver;
+/** Test seam: forget everything remembered in this process. */
+export declare function resetMailDeliverabilityMemoryForTests(): void;
+/**
+ * Each domain's MX answer, keyed by domain: remembered, stored and fresh, or
+ * looked up and stored. `null` for a domain that could not be looked up and
+ * has no answer that may stand — see the module note.
+ */
+export declare function readMailDomains(domains: readonly string[], deps?: MailDeliverabilityDeps): Promise<Map<string, MailDomainIntel | null>>;
+/**
+ * Whether a block on this sending domain hurts every tenant — Aglyn's own
+ * domain or a shared pool member — which the staff console surfaces first.
+ */
+export declare function isSharedMailSendingDomain(domain: string | null | undefined): boolean;
+/** The ledger of each gateway named for one sending domain, keyed by gateway; `null` where none exists yet. */
+export declare function readMailGatewayLedgers(scope: MailGatewayLedgerScope, sendingDomain: string, gateways: readonly MailGateway[], deps?: MailDeliverabilityDeps): Promise<Map<MailGateway, MailGatewayLedger | null>>;
+/**
+ * Counts one outcome on a sending domain's ledger with a gateway. Never
+ * throws: the send or the bounce it records has already happened, and a
+ * lost count understates a gateway while a thrown one loses the step that
+ * called. A delivery past the day's cap costs no write at all.
+ */
+export declare function recordMailGatewayOutcome(scope: MailGatewayLedgerScope, input: {
+    sendingDomain: string;
+    gateway: MailGateway;
+    outcome: MailGatewayOutcome;
+    count?: number;
+    atMs: number;
+    /** A refusal's diagnostic, scrubbed here of addresses before it is kept. */
+    detail?: string | null;
+}, deps?: MailDeliverabilityDeps): Promise<void>;
+/** What a batch read needs to know about the mail being sent. */
+export interface MailDeliverabilityQuestion {
+    emails: readonly string[];
+    purpose: EmailSendPurpose;
+    /** The domain the mail leaves from; without one, no ledger is read and nothing is held. */
+    sendingDomain: string | null;
+    scope: MailGatewayLedgerScope;
+    /** Addresses a person already released the gateway hold for. */
+    holdReleased?: (email: string) => boolean;
+}
+/**
+ * The deliverability verdict for every address, keyed by the address as
+ * given: the MX answers read (and refreshed) above, joined to the sending
+ * domain's ledger with each gateway they name. A ledger that cannot be read
+ * reads as no history, which holds nothing.
+ */
+export declare function readMailDeliverability(question: MailDeliverabilityQuestion, deps?: MailDeliverabilityDeps): Promise<Map<string, EmailDeliverabilityVerdict>>;
+/** Whether a verdict refuses because the domain takes no mail — the refusal that suppresses. */
+export declare function isNoMailServerVerdict(verdict: EmailDeliverabilityVerdict | null | undefined): boolean;
+/** Whether a verdict holds bulk mail for its gateway. */
+export declare function isGatewayHeldVerdict(verdict: EmailDeliverabilityVerdict | null | undefined): boolean;
+/** A campaign's audience after the checks, with who was excluded and why. */
+export interface DeliverableRecipients {
+    deliverable: string[];
+    /** Addresses whose domain takes no mail. */
+    noMailServer: string[];
+    /** Addresses behind a gateway that refused this sending domain twice lately. */
+    gatewayHeld: string[];
+}
+/**
+ * A bulk audience with the addresses that would bounce, or that sit behind
+ * a gateway holding this sending domain, taken out — the count a campaign's
+ * review shows before Send, and the filter its batches run. Fails open: an
+ * error keeps everyone.
+ */
+export declare function filterDeliverableRecipients(input: {
+    emails: readonly string[];
+    sendingDomain: string | null;
+    purpose?: EmailSendPurpose;
+}, deps?: MailDeliverabilityDeps): Promise<DeliverableRecipients>;
+/**
+ * What `sendEmail` asks before a message leaves — see the seam in
+ * `@aglyn/shared-util-email`. Refuses every recipient whose domain takes no
+ * mail, and files the address on the platform suppression list with its own
+ * reason; holds bulk mail behind a gateway that refused this sending domain
+ * twice. The Resend path's ledger is keyed by the sending domain alone.
+ */
+export declare function runEmailDeliverabilityPreflight(request: EmailDeliverabilityPreflightRequest, deps?: MailDeliverabilityDeps): Promise<EmailDeliverabilityPreflightVerdict>;
+/**
+ * Puts the preflight on `sendEmail`'s path. **Called at module load**, from
+ * the bottom of this file, for the reason `installEmailSendGovernor` is.
+ * Idempotent; the closure holds no state of its own.
+ */
+export declare function installEmailDeliverabilityPreflight(): void;
+/**
+ * Counts what a Resend webhook reported on the sending domain's ledger: a
+ * delivery credits the gateway in front of the recipient, and a permanent
+ * bounce that reads as the gateway refusing the SENDER — not an unknown
+ * address — counts as a block, filed under the gateway the bounce names
+ * (its remote server, or its own words) or else the domain's MX. Only an
+ * event the delivery log saw for the first time counts, so a redelivered
+ * webhook counts nothing twice. Answers how many outcomes it recorded.
+ */
+export declare function recordDeliverabilityFromDeliveryEvents(events: readonly EmailDeliveryEvent[], outcomes: readonly EmailDeliveryEventOutcome[] | null, deps?: MailDeliverabilityDeps): Promise<number>;
+/** One row of the platform ledger as the staff console shows it. */
+export interface MailGatewayLedgerRow extends MailGatewayLedger {
+    id: string;
+    /** A pooled or platform sending domain: a block there hurts every tenant. */
+    shared: boolean;
+    standing: MailGatewayStanding;
+    /** Whether bulk mail from this domain into this gateway is held today. */
+    holds: boolean;
+}
+/** The platform ledger, most recently moved first. */
+export declare function listMailGatewayLedgers(options?: {
+    limit?: number;
+}, deps?: MailDeliverabilityDeps): Promise<MailGatewayLedgerRow[]>;
+export {};