@aglyn/shared-util-email 1.0.0-beta.200 → 1.0.0-beta.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-util-email",
-  "version": "1.0.0-beta.200",
+  "version": "1.0.0-beta.201",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,8 +25,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.200",
-    "@aglyn/shared-util-http": "1.0.0-beta.200",
+    "@aglyn/shared-data-enums": "1.0.0-beta.201",
+    "@aglyn/shared-util-http": "1.0.0-beta.201",
     "@msgpack/msgpack": "^3.1.3",
     "@swc/helpers": "0.5.23"
   },

package/src/index.d.ts

@@ -37,3 +37,9 @@ export * from './lib/email-revenue-window';
 export * from './lib/email-media-src';
 export * from './lib/stored-email-nodes';
 export * from './lib/email-merge';
+export * from './lib/mail-gateway';
+export * from './lib/mail-bounce';
+export * from './lib/email-deliverability';
+export * from './lib/outbound-phishing-screen';
+export * from './lib/outbound-screen-gate';
+export * from './lib/hosted-page-screen';

package/src/index.js

@@ -45,5 +45,21 @@ export * from "./lib/email-media-src.js";
 // this scope:shared lib may not import, pinned by `email-nodes-drift.spec.ts`.
 export * from "./lib/stored-email-nodes.js";
 export * from "./lib/email-merge.js";
+// The deliverability engine every send path asks (AGL-3328): the gateway an
+// MX names and its ledger, the bounce reader, and the address verdicts. Pure
+// — the DNS lookup and the store are injected by `@aglyn/tenant-data-admin`,
+// so nothing here reaches `node:dns` from the browser.
+export * from "./lib/mail-gateway.js";
+export * from "./lib/mail-bounce.js";
+export * from "./lib/email-deliverability.js";
+// The outbound phishing screen a young workspace's campaigns and automated
+// email pass (AGL-3356). Pure; the hold it leads to is `tenant-data-admin`'s.
+export * from "./lib/outbound-phishing-screen.js";
+// The send seam's gate for that screen — the store a hold writes is injected
+// by `@aglyn/tenant-data-admin`, like the governor's.
+export * from "./lib/outbound-screen-gate.js";
+// The same screen read over a published page (AGL-3356): lookalike links and
+// embeds, author-defined credential fields, a brand's call to action.
+export * from "./lib/hosted-page-screen.js";
 
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/shared/util/email/src/index.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\nexport * from './lib/send-email'\nexport * from './lib/send-rate'\nexport * from './lib/sender-reputation'\nexport * from './lib/send-ceilings'\nexport * from './lib/sending-domain'\nexport * from './lib/tracking-host'\nexport * from './lib/sending-mailbox'\nexport * from './lib/host-sender'\nexport * from './lib/platform-sending-domain'\nexport * from './lib/email-health'\nexport * from './lib/system-email-catalog'\nexport * from './lib/tenant-email-catalog'\nexport * from './lib/host-email-render'\nexport * from './lib/email-render'\nexport * from './lib/text-email-html'\nexport * from './lib/marketing-send'\n// The List-Unsubscribe setting sequences and campaigns share (AGL-3307).\nexport * from './lib/list-unsubscribe'\nexport * from './lib/email-delivery-events'\n// The received-mail reader the CRM's capture route files from (AGL-2657).\n// Its neighbor `./lib/svix-signature` is deliberately NOT re-exported here:\n// it holds a `crypto` HMAC, and this barrel is reached from the browser\n// through `@aglyn/shared-ui-email-campaigns`, so a webhook imports it by its\n// own path — `@aglyn/shared-util-email/svix-signature`.\nexport * from './lib/received-email'\nexport * from './lib/email-revenue-window'\n// Exported so the console drift guard can pin it against @aglyn/aglyn.\nexport * from './lib/email-media-src'\n// Same arrangement, same reason (AGL-1223): a copy of `decodeStoredNodes`\n// this scope:shared lib may not import, pinned by `email-nodes-drift.spec.ts`.\nexport * from './lib/stored-email-nodes'\nexport * from './lib/email-merge'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,cAAc,sBAAkB;AAChC,cAAc,qBAAiB;AAC/B,cAAc,6BAAyB;AACvC,cAAc,yBAAqB;AACnC,cAAc,0BAAsB;AACpC,cAAc,yBAAqB;AACnC,cAAc,2BAAuB;AACrC,cAAc,uBAAmB;AACjC,cAAc,mCAA+B;AAC7C,cAAc,wBAAoB;AAClC,cAAc,gCAA4B;AAC1C,cAAc,gCAA4B;AAC1C,cAAc,6BAAyB;AACvC,cAAc,wBAAoB;AAClC,cAAc,2BAAuB;AACrC,cAAc,0BAAsB;AACpC,yEAAyE;AACzE,cAAc,4BAAwB;AACtC,cAAc,iCAA6B;AAC3C,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,6EAA6E;AAC7E,wDAAwD;AACxD,cAAc,0BAAsB;AACpC,cAAc,gCAA4B;AAC1C,uEAAuE;AACvE,cAAc,2BAAuB;AACrC,0EAA0E;AAC1E,+EAA+E;AAC/E,cAAc,8BAA0B;AACxC,cAAc,uBAAmB"}
+{"version":3,"sources":["../../../../../../libs/shared/util/email/src/index.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\nexport * from './lib/send-email'\nexport * from './lib/send-rate'\nexport * from './lib/sender-reputation'\nexport * from './lib/send-ceilings'\nexport * from './lib/sending-domain'\nexport * from './lib/tracking-host'\nexport * from './lib/sending-mailbox'\nexport * from './lib/host-sender'\nexport * from './lib/platform-sending-domain'\nexport * from './lib/email-health'\nexport * from './lib/system-email-catalog'\nexport * from './lib/tenant-email-catalog'\nexport * from './lib/host-email-render'\nexport * from './lib/email-render'\nexport * from './lib/text-email-html'\nexport * from './lib/marketing-send'\n// The List-Unsubscribe setting sequences and campaigns share (AGL-3307).\nexport * from './lib/list-unsubscribe'\nexport * from './lib/email-delivery-events'\n// The received-mail reader the CRM's capture route files from (AGL-2657).\n// Its neighbor `./lib/svix-signature` is deliberately NOT re-exported here:\n// it holds a `crypto` HMAC, and this barrel is reached from the browser\n// through `@aglyn/shared-ui-email-campaigns`, so a webhook imports it by its\n// own path — `@aglyn/shared-util-email/svix-signature`.\nexport * from './lib/received-email'\nexport * from './lib/email-revenue-window'\n// Exported so the console drift guard can pin it against @aglyn/aglyn.\nexport * from './lib/email-media-src'\n// Same arrangement, same reason (AGL-1223): a copy of `decodeStoredNodes`\n// this scope:shared lib may not import, pinned by `email-nodes-drift.spec.ts`.\nexport * from './lib/stored-email-nodes'\nexport * from './lib/email-merge'\n// The deliverability engine every send path asks (AGL-3328): the gateway an\n// MX names and its ledger, the bounce reader, and the address verdicts. Pure\n// — the DNS lookup and the store are injected by `@aglyn/tenant-data-admin`,\n// so nothing here reaches `node:dns` from the browser.\nexport * from './lib/mail-gateway'\nexport * from './lib/mail-bounce'\nexport * from './lib/email-deliverability'\n// The outbound phishing screen a young workspace's campaigns and automated\n// email pass (AGL-3356). Pure; the hold it leads to is `tenant-data-admin`'s.\nexport * from './lib/outbound-phishing-screen'\n// The send seam's gate for that screen — the store a hold writes is injected\n// by `@aglyn/tenant-data-admin`, like the governor's.\nexport * from './lib/outbound-screen-gate'\n// The same screen read over a published page (AGL-3356): lookalike links and\n// embeds, author-defined credential fields, a brand's call to action.\nexport * from './lib/hosted-page-screen'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,cAAc,sBAAkB;AAChC,cAAc,qBAAiB;AAC/B,cAAc,6BAAyB;AACvC,cAAc,yBAAqB;AACnC,cAAc,0BAAsB;AACpC,cAAc,yBAAqB;AACnC,cAAc,2BAAuB;AACrC,cAAc,uBAAmB;AACjC,cAAc,mCAA+B;AAC7C,cAAc,wBAAoB;AAClC,cAAc,gCAA4B;AAC1C,cAAc,gCAA4B;AAC1C,cAAc,6BAAyB;AACvC,cAAc,wBAAoB;AAClC,cAAc,2BAAuB;AACrC,cAAc,0BAAsB;AACpC,yEAAyE;AACzE,cAAc,4BAAwB;AACtC,cAAc,iCAA6B;AAC3C,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,6EAA6E;AAC7E,wDAAwD;AACxD,cAAc,0BAAsB;AACpC,cAAc,gCAA4B;AAC1C,uEAAuE;AACvE,cAAc,2BAAuB;AACrC,0EAA0E;AAC1E,+EAA+E;AAC/E,cAAc,8BAA0B;AACxC,cAAc,uBAAmB;AACjC,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,uDAAuD;AACvD,cAAc,wBAAoB;AAClC,cAAc,uBAAmB;AACjC,cAAc,gCAA4B;AAC1C,2EAA2E;AAC3E,8EAA8E;AAC9E,cAAc,oCAAgC;AAC9C,6EAA6E;AAC7E,sDAAsD;AACtD,cAAc,gCAA4B;AAC1C,6EAA6E;AAC7E,sEAAsE;AACtE,cAAc,8BAA0B"}

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

@@ -0,0 +1,200 @@
+/**
+ * @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 MailGateway, type MailGatewayStanding } from './mail-gateway';
+/** An address as the checks read it: trimmed and lowercased, or `null` when it is not one. */
+export declare function normalizeDeliverabilityEmail(value: unknown): string | null;
+/** Whether a value is a domain with at least two labels and a non-numeric top level. */
+export declare function isDeliverabilityDomain(value: unknown): boolean;
+/** The domain of an address, lowercased, or `null` for a value that is not one. */
+export declare function emailAddressDomain(email: unknown): string | null;
+/** Whether an address is a role mailbox (`info@`, `sales@`), read before any `+tag`. */
+export declare function isRoleEmailAddress(email: unknown): boolean;
+/** Whether a domain is a disposable-mailbox provider. */
+export declare function isDisposableEmailDomain(domain: unknown): boolean;
+/**
+ * The provider a domain most likely meant, or `null` — a SUGGESTION a
+ * surface may offer, never a correction applied: `gmial.com` may be a real
+ * domain somebody owns, and changing an address a person typed is sending
+ * their mail to someone else.
+ */
+export declare function suggestEmailDomain(domain: unknown): string | null;
+/** One MX record as a resolver answers it. */
+export interface MailMxRecord {
+    exchange: string;
+    priority: number;
+}
+/**
+ * The DNS the checks read, handed in by the server layer.
+ *
+ * `resolveMx` resolves the domain's MX records. A domain that publishes
+ * none resolves `[]` or rejects with a `code` of `ENOTFOUND`, `ENODATA` or
+ * `NXDOMAIN` — Node's own convention — and any other rejection is a
+ * resolver that could not answer, which the checks read as "unknown" and
+ * never as "no MX".
+ *
+ * `resolveAddress`, when given, answers whether the domain has an address
+ * record (A or AAAA): the implicit MX a domain with no MX is still
+ * delivered to. Omitted, a domain with no MX reads as `no_mx`.
+ */
+export interface MailDnsResolver {
+    resolveMx(domain: string): Promise<ReadonlyArray<MailMxRecord>>;
+    resolveAddress?(domain: string): Promise<boolean>;
+}
+/**
+ * What a domain's DNS says about receiving mail.
+ *
+ * - `mx` — it publishes MX records.
+ * - `implicit_mx` — no MX, but an address record, which RFC 5321 §5.1 still
+ *   delivers to. Deliverable; warned, because it is usually a domain whose
+ *   mail was never set up.
+ * - `null_mx` — RFC 7505's `MX 0 .`: the domain says outright it takes no mail.
+ * - `no_mx` — no MX and no address record: nothing to deliver to.
+ */
+export type MailDomainStatus = 'mx' | 'implicit_mx' | 'null_mx' | 'no_mx';
+/** One domain's answer, as the platform cache stores it. */
+export interface MailDomainIntel {
+    domain: string;
+    status: MailDomainStatus;
+    /** The MX exchanges, lowest preference first; empty for every status but `mx`. */
+    mx: string[];
+    gateway: MailGateway;
+    /** When the domain was looked up; trusted for {@link mailDomainIntelTtlMs}. */
+    resolvedAtMs: number;
+}
+export declare const MAIL_DOMAIN_STATUSES: readonly MailDomainStatus[];
+/** Whether a status means the domain takes no mail. */
+export declare function mailDomainRefusesMail(status: MailDomainStatus | null | undefined): boolean;
+/** How long an answer is trusted: a week for a domain that takes mail, a day for one that does not. */
+export declare function mailDomainIntelTtlMs(status: MailDomainStatus): number;
+/** Whether a cached answer is still trusted at `nowMs`. */
+export declare function isMailDomainIntelFresh(intel: MailDomainIntel | null | undefined, nowMs: number): boolean;
+/** Whether a resolver rejection is an answer ("no such record") rather than a failure to get one. */
+export declare function isNoRecordDnsError(error: unknown): boolean;
+/** A stored answer in its model shape, or `null` for no document or an unreadable one. */
+export declare function readStoredMailDomainIntel(id: string, data: Record<string, unknown> | null | undefined): MailDomainIntel | null;
+/**
+ * A domain's mail setup, looked up — see {@link MailDomainStatus}. Rejects
+ * when the resolver could not answer, and the caller decides what a missing
+ * answer means; every path here reads it as "unknown" and sends.
+ */
+export declare function resolveMailDomain(resolver: MailDnsResolver, domain: string, nowMs: number): Promise<MailDomainIntel>;
+/**
+ * Who a message is for, which decides what may stop it — see the module
+ * note. `transactional` is mail the recipient asked for; `bulk` is a
+ * campaign, a workflow's marketing step, a sweep; `cold` is a sequence to
+ * somebody who has not written to the sender.
+ */
+export type EmailSendPurpose = 'transactional' | 'bulk' | 'cold';
+export type EmailDeliverabilityCode = 'invalid_syntax' | 'no_mx' | 'null_mx' | 'implicit_mx' | 'typo_domain' | 'disposable_domain' | 'role_address' | 'gateway_held';
+export type EmailDeliverabilitySeverity = 'refuse' | 'hold' | 'warn';
+export interface EmailDeliverabilityFinding {
+    code: EmailDeliverabilityCode;
+    severity: EmailDeliverabilitySeverity;
+    /** A sentence a surface shows as is. */
+    message: string;
+    /** `typo_domain` only: the address with the suggested domain. Never applied for the person. */
+    suggestion?: string;
+}
+/**
+ * What the checks conclude, worst first: `refused` (never sent), `held`
+ * (bulk and cold mail wait for a person), `deliverable` (nothing stops it,
+ * warnings or not), `unchecked` (the MX could not be read, so nothing is
+ * known — and nothing is stopped).
+ */
+export type EmailDeliverabilityOutcome = 'refused' | 'held' | 'deliverable' | 'unchecked';
+export interface EmailDeliverabilityVerdict {
+    /** The address, normalized, or `null` when it is not one. */
+    email: string | null;
+    domain: string | null;
+    outcome: EmailDeliverabilityOutcome;
+    findings: EmailDeliverabilityFinding[];
+    intel: MailDomainIntel | null;
+    gateway: MailGatewayStanding | null;
+}
+export interface EmailDeliverabilityInput {
+    email: unknown;
+    purpose: EmailSendPurpose;
+    /** The domain's MX answer; `null` or absent when it could not be read. */
+    intel?: MailDomainIntel | null;
+    /** The gateway's standing with the sending domain, when the caller read the ledger. */
+    gateway?: MailGatewayStanding | null;
+    /**
+     * The domain is a public mailbox provider (`gmail.com`), which is never
+     * refused for its MX. The list lives with the CRM's, so the caller asks.
+     */
+    publicMailbox?: boolean;
+    /** A person already released the gateway hold for this address. */
+    holdReleased?: boolean;
+}
+/** The whole verdict for one address — see the module note. */
+export declare function assessEmailDeliverability(input: EmailDeliverabilityInput): EmailDeliverabilityVerdict;
+/** The finding that decided a refusal or a hold, or `null` when nothing stops the address. */
+export declare function decidingDeliverabilityFinding(verdict: EmailDeliverabilityVerdict): EmailDeliverabilityFinding | null;
+/**
+ * What a bulk send's review says about the addresses the checks took out,
+ * or `null` when they took out nobody: "3 recipients excluded: no mail
+ * server · 2 behind a gateway that refused this sender".
+ */
+export declare function deliverabilityExclusionSummary(counts: {
+    noMailServer?: number | null;
+    gatewayHeld?: number | null;
+}): string | null;
+/** What `sendEmail` asks before a message leaves. */
+export interface EmailDeliverabilityPreflightRequest {
+    /** The recipients, normalized and lowercased. */
+    recipients: string[];
+    purpose: EmailSendPurpose;
+    /** The domain the message leaves from, or `null` when it could not be read. */
+    sendingDomain: string | null;
+    /**
+     * Whose reputation the sending domain is: a site's own verified domain
+     * (`custom`), the pooled tenant identity (`shared`), or Aglyn's own
+     * (`platform`). The last two are learned at platform level, where a block
+     * hurts every tenant.
+     */
+    sendingSource: 'custom' | 'shared' | 'platform';
+    context?: string;
+    hostId?: string | null;
+}
+export interface EmailDeliverabilityPreflightVerdict {
+    /** Recipients whose domain takes no mail. Never sent, whatever the purpose. */
+    refused: Array<{
+        email: string;
+        code: EmailDeliverabilityCode;
+        reason: string;
+    }>;
+    /** Recipients behind a gateway that refused this sender twice. Bulk and cold mail only. */
+    held: Array<{
+        email: string;
+        gateway: MailGateway;
+        reason: string;
+    }>;
+}
+export type EmailDeliverabilityPreflight = (request: EmailDeliverabilityPreflightRequest) => Promise<EmailDeliverabilityPreflightVerdict>;
+/** Installs the durable preflight. Called once, from `@aglyn/tenant-data-admin`. */
+export declare function setEmailDeliverabilityPreflight(preflight: EmailDeliverabilityPreflight | null): void;
+/** The installed preflight, or `null` when nothing has been installed. */
+export declare function getEmailDeliverabilityPreflight(): EmailDeliverabilityPreflight | null;
+/** Test seam: forget any installed preflight. */
+export declare function resetEmailDeliverabilityPreflightForTests(): void;
+/**
+ * How long `sendEmail` waits for the preflight before sending anyway. A
+ * cold lookup is one DNS round trip and one document read; a preflight
+ * slower than this is an outage on the control, and a control outage must
+ * not become a mail outage.
+ */
+export declare const EMAIL_DELIVERABILITY_PREFLIGHT_TIMEOUT_MS = 2500;