@aglyn/shared-util-email 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/mail-providers.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @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.
+ */
+/**
+ * WHICH PROVIDER CARRIES THIS DEPLOYMENT'S MAIL.
+ *
+ * | provider  | for                                                          |
+ * |-----------|--------------------------------------------------------------|
+ * | `resend`  | Aglyn's own deployment, and anyone with a Resend account      |
+ * | `webhook` | anything else — the operator's own relay, SMTP, SES, Postmark |
+ * | any other | a provider a plugin or a fork registered under that id        |
+ *
+ * `AGLYN_MAIL_PROVIDER` picks one. Unset, the first built-in that has its
+ * settings wins, in the order above — so a deployment that already had
+ * `RESEND_API_KEY` keeps Resend however else it is configured, and a
+ * self-hosted one that set only `AGLYN_MAIL_WEBHOOK_URL` gets its own relay
+ * with no other setting. With neither, it is Resend, unconfigured, and every
+ * send is skipped with a log line naming the setting — the behavior an
+ * install without mail has always had.
+ *
+ * ## Why the built-ins are compiled in, and not registered by a plugin
+ *
+ * This is the transactional rail: password resets, invitations, receipts,
+ * billing notices and operator alerts, sent from every server process with
+ * or without any plugin loaded. A provider a plugin registered at boot is a
+ * provider that can be absent — a boot whose declarations threw part-way, a
+ * route bundle that evaluates the registry apart from boot's — and an absent
+ * provider is indistinguishable from an unconfigured one: every send skipped
+ * as if mail were simply off, nothing red. Selecting among providers that
+ * are part of this library has no such state. Registration is kept for what
+ * cannot be compiled in, and is only ever consulted when the operator named
+ * the provider.
+ *
+ * ## An explicit choice never becomes another vendor
+ *
+ * A value naming no built-in and no registered provider is REFUSED — every
+ * send skipped with an error naming the value — rather than falling back to
+ * detection. Falling back would hand an operator's mail, recipients and
+ * bodies included, to a vendor they did not choose, because a plugin failed
+ * to load or a name was misspelled.
+ */
+import { type MailInboundEvent, type MailProvider, type MailProviderReads } from './mail-provider';
+import type { EmailDeliveryEvent } from './email-delivery-events';
+/** The setting that names the provider. */
+export declare const MAIL_PROVIDER_SETTING = "AGLYN_MAIL_PROVIDER";
+type Env = Record<string, string | undefined>;
+/** The ids no registration may take. */
+export declare function builtInMailProviderIds(): string[];
+/**
+ * Registers a provider under its `id`, for a deployment that names it in
+ * `AGLYN_MAIL_PROVIDER`. The same provider object again is a no-op; a
+ * different one under a taken id throws naming it, because two providers
+ * answering to one name would split an account's mail between them. A
+ * built-in id throws too: the platform's default carrier is not something a
+ * plugin can replace by registering.
+ */
+export declare function registerMailProvider(provider: MailProvider): void;
+/** Forgets every registration — for specs. */
+export declare function resetMailProvidersForTests(): void;
+/**
+ * The provider this deployment's mail is handed to. Never `null`: an
+ * unconfigured provider reports what it is missing, and a provider the
+ * operator named that this process lacks is a stand-in that refuses (see
+ * {@link mailProviderProblem}). Read per call, so a spec — or a runtime
+ * whose environment arrives after module load — sees its current settings.
+ */
+export declare function mailProvider(env?: Env): MailProvider;
+/**
+ * A sentence saying the operator's chosen provider is not available in this
+ * process, or `null` when it is (or none was chosen). Printed as an ERROR
+ * wherever a skipped send is reported, because unlike an absent key it is
+ * not a deployment that simply has no mail: somebody chose a provider and
+ * this process cannot find it.
+ */
+export declare function mailProviderProblem(provider?: MailProvider): string | null;
+/** One delivery-webhook payload as events, one per recipient; `[]` for anything else. */
+export declare function normalizeDeliveryEvents(payload: unknown, receivedAtMs: number, provider?: MailProvider): EmailDeliveryEvent[];
+/** A received-mail notification, or `null` for any other payload. */
+export declare function readInboundMailEvent(payload: unknown, provider?: MailProvider): MailInboundEvent | null;
+/**
+ * The provider's reads of its own account. A provider without any answers
+ * with reads whose `unmet` says so, so a route handles "cannot read" the
+ * same way whichever the reason.
+ */
+export declare function mailProviderReads(provider?: MailProvider): MailProviderReads;
+export {};

package/src/lib/mail-providers.js

@@ -0,0 +1,182 @@
+/**
+ * @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.
+ */ /**
+ * WHICH PROVIDER CARRIES THIS DEPLOYMENT'S MAIL.
+ *
+ * | provider  | for                                                          |
+ * |-----------|--------------------------------------------------------------|
+ * | `resend`  | Aglyn's own deployment, and anyone with a Resend account      |
+ * | `webhook` | anything else — the operator's own relay, SMTP, SES, Postmark |
+ * | any other | a provider a plugin or a fork registered under that id        |
+ *
+ * `AGLYN_MAIL_PROVIDER` picks one. Unset, the first built-in that has its
+ * settings wins, in the order above — so a deployment that already had
+ * `RESEND_API_KEY` keeps Resend however else it is configured, and a
+ * self-hosted one that set only `AGLYN_MAIL_WEBHOOK_URL` gets its own relay
+ * with no other setting. With neither, it is Resend, unconfigured, and every
+ * send is skipped with a log line naming the setting — the behavior an
+ * install without mail has always had.
+ *
+ * ## Why the built-ins are compiled in, and not registered by a plugin
+ *
+ * This is the transactional rail: password resets, invitations, receipts,
+ * billing notices and operator alerts, sent from every server process with
+ * or without any plugin loaded. A provider a plugin registered at boot is a
+ * provider that can be absent — a boot whose declarations threw part-way, a
+ * route bundle that evaluates the registry apart from boot's — and an absent
+ * provider is indistinguishable from an unconfigured one: every send skipped
+ * as if mail were simply off, nothing red. Selecting among providers that
+ * are part of this library has no such state. Registration is kept for what
+ * cannot be compiled in, and is only ever consulted when the operator named
+ * the provider.
+ *
+ * ## An explicit choice never becomes another vendor
+ *
+ * A value naming no built-in and no registered provider is REFUSED — every
+ * send skipped with an error naming the value — rather than falling back to
+ * detection. Falling back would hand an operator's mail, recipients and
+ * bodies included, to a vendor they did not choose, because a plugin failed
+ * to load or a name was misspelled.
+ */ import { resendMailProvider } from "./mail-provider-resend.js";
+import { webhookMailProvider } from "./mail-provider-webhook.js";
+/** The setting that names the provider. */ export const MAIL_PROVIDER_SETTING = 'AGLYN_MAIL_PROVIDER';
+/** The built-in providers, in the order detection tries them. */ function builtInMailProviders(env) {
+    return [
+        resendMailProvider(env),
+        webhookMailProvider(env)
+    ];
+}
+/** The ids no registration may take. */ export function builtInMailProviderIds() {
+    return builtInMailProviders({}).map((provider)=>provider.id);
+}
+/*==========================================
+ * PROVIDERS A PLUGIN OR A FORK SUPPLIES.
+ *
+ * The slots live on `globalThis` under a registered symbol: a Next server
+ * evaluates a module once for boot and again inside a route's bundle, and a
+ * module-level map would give the route an empty copy of what boot filled.
+ *=========================================*/ const REGISTRY_KEY = Symbol.for('aglyn.mail-providers');
+function registered() {
+    const slots = globalThis;
+    if (!slots[REGISTRY_KEY]) slots[REGISTRY_KEY] = new Map();
+    return slots[REGISTRY_KEY];
+}
+/**
+ * Registers a provider under its `id`, for a deployment that names it in
+ * `AGLYN_MAIL_PROVIDER`. The same provider object again is a no-op; a
+ * different one under a taken id throws naming it, because two providers
+ * answering to one name would split an account's mail between them. A
+ * built-in id throws too: the platform's default carrier is not something a
+ * plugin can replace by registering.
+ */ export function registerMailProvider(provider) {
+    var _ref;
+    const id = String((_ref = provider == null ? void 0 : provider.id) != null ? _ref : '').trim().toLowerCase();
+    if (!id) throw new Error('a mail provider needs an id');
+    if (builtInMailProviderIds().includes(id)) {
+        throw new Error(`"${id}" is a built-in mail provider and cannot be registered`);
+    }
+    const slots = registered();
+    const existing = slots.get(id);
+    if (existing && existing !== provider) {
+        throw new Error(`a different mail provider is already registered as "${id}"`);
+    }
+    slots.set(id, provider);
+}
+/** Forgets every registration — for specs. */ export function resetMailProvidersForTests() {
+    registered().clear();
+}
+/*==========================================
+ * SELECTION.
+ *=========================================*/ /** Why each provider that cannot be used cannot, keyed by the stand-in {@link mailProvider} returned. */ const UNAVAILABLE = new WeakMap();
+/**
+ * The stand-in for a provider the operator named and this process does not
+ * have. It sends nothing and says why in everything that reads it.
+ */ function unavailableMailProvider(id) {
+    const problem = `${MAIL_PROVIDER_SETTING} is "${id}", which is not a built-in mail ` + `provider (${builtInMailProviderIds().join(', ')}) and was not registered ` + 'in this process, so no mail is sent.';
+    const provider = {
+        id,
+        missingSettings: ()=>[
+                MAIL_PROVIDER_SETTING
+            ],
+        send: async ()=>{
+            throw new Error(problem);
+        }
+    };
+    UNAVAILABLE.set(provider, problem);
+    return provider;
+}
+/**
+ * The provider this deployment's mail is handed to. Never `null`: an
+ * unconfigured provider reports what it is missing, and a provider the
+ * operator named that this process lacks is a stand-in that refuses (see
+ * {@link mailProviderProblem}). Read per call, so a spec — or a runtime
+ * whose environment arrives after module load — sees its current settings.
+ */ export function mailProvider(env = process.env) {
+    var _env_MAIL_PROVIDER_SETTING, _ref, _builtIns_find;
+    const requested = String((_env_MAIL_PROVIDER_SETTING = env[MAIL_PROVIDER_SETTING]) != null ? _env_MAIL_PROVIDER_SETTING : '').trim().toLowerCase();
+    const builtIns = builtInMailProviders(env);
+    if (!requested) {
+        var _builtIns_find1;
+        return (_builtIns_find1 = builtIns.find((provider)=>!provider.missingSettings().length)) != null ? _builtIns_find1 : builtIns[0];
+    }
+    return (_ref = (_builtIns_find = builtIns.find((provider)=>provider.id === requested)) != null ? _builtIns_find : registered().get(requested)) != null ? _ref : unavailableMailProvider(requested);
+}
+/**
+ * A sentence saying the operator's chosen provider is not available in this
+ * process, or `null` when it is (or none was chosen). Printed as an ERROR
+ * wherever a skipped send is reported, because unlike an absent key it is
+ * not a deployment that simply has no mail: somebody chose a provider and
+ * this process cannot find it.
+ */ export function mailProviderProblem(provider = mailProvider()) {
+    var _UNAVAILABLE_get;
+    return (_UNAVAILABLE_get = UNAVAILABLE.get(provider)) != null ? _UNAVAILABLE_get : null;
+}
+/*==========================================
+ * WHAT THE REST OF THE PLATFORM ASKS.
+ *
+ * Each question in the platform's own vocabulary, answered by whichever
+ * provider this deployment uses. A provider that cannot answer one gives the
+ * empty answer — no events, no inbound message, reads that say they cannot
+ * be made — never a guess.
+ *=========================================*/ /** One delivery-webhook payload as events, one per recipient; `[]` for anything else. */ export function normalizeDeliveryEvents(payload, receivedAtMs, provider = mailProvider()) {
+    var _ref;
+    return (_ref = provider.deliveryEvents == null ? void 0 : provider.deliveryEvents.call(provider, payload, receivedAtMs)) != null ? _ref : [];
+}
+/** A received-mail notification, or `null` for any other payload. */ export function readInboundMailEvent(payload, provider = mailProvider()) {
+    var _ref;
+    return (_ref = provider.inboundEvent == null ? void 0 : provider.inboundEvent.call(provider, payload)) != null ? _ref : null;
+}
+/**
+ * The provider's reads of its own account. A provider without any answers
+ * with reads whose `unmet` says so, so a route handles "cannot read" the
+ * same way whichever the reason.
+ */ export function mailProviderReads(provider = mailProvider()) {
+    var _mailProviderProblem;
+    if (provider.reads) return provider.reads;
+    const reason = (_mailProviderProblem = mailProviderProblem(provider)) != null ? _mailProviderProblem : `The "${provider.id}" mail provider cannot read mail it sent or received.`;
+    const refuse = async ()=>{
+        throw new Error(reason);
+    };
+    return {
+        unmet: ()=>reason,
+        history: refuse,
+        message: refuse,
+        received: refuse,
+        sendingDomains: refuse
+    };
+}
+
+//# sourceMappingURL=mail-providers.js.map

package/src/lib/mail-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/mail-providers.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 * WHICH PROVIDER CARRIES THIS DEPLOYMENT'S MAIL.\n *\n * | provider  | for                                                          |\n * |-----------|--------------------------------------------------------------|\n * | `resend`  | Aglyn's own deployment, and anyone with a Resend account      |\n * | `webhook` | anything else — the operator's own relay, SMTP, SES, Postmark |\n * | any other | a provider a plugin or a fork registered under that id        |\n *\n * `AGLYN_MAIL_PROVIDER` picks one. Unset, the first built-in that has its\n * settings wins, in the order above — so a deployment that already had\n * `RESEND_API_KEY` keeps Resend however else it is configured, and a\n * self-hosted one that set only `AGLYN_MAIL_WEBHOOK_URL` gets its own relay\n * with no other setting. With neither, it is Resend, unconfigured, and every\n * send is skipped with a log line naming the setting — the behavior an\n * install without mail has always had.\n *\n * ## Why the built-ins are compiled in, and not registered by a plugin\n *\n * This is the transactional rail: password resets, invitations, receipts,\n * billing notices and operator alerts, sent from every server process with\n * or without any plugin loaded. A provider a plugin registered at boot is a\n * provider that can be absent — a boot whose declarations threw part-way, a\n * route bundle that evaluates the registry apart from boot's — and an absent\n * provider is indistinguishable from an unconfigured one: every send skipped\n * as if mail were simply off, nothing red. Selecting among providers that\n * are part of this library has no such state. Registration is kept for what\n * cannot be compiled in, and is only ever consulted when the operator named\n * the provider.\n *\n * ## An explicit choice never becomes another vendor\n *\n * A value naming no built-in and no registered provider is REFUSED — every\n * send skipped with an error naming the value — rather than falling back to\n * detection. Falling back would hand an operator's mail, recipients and\n * bodies included, to a vendor they did not choose, because a plugin failed\n * to load or a name was misspelled.\n */\n\nimport {\n  type MailInboundEvent,\n  type MailProvider,\n  type MailProviderReads,\n} from './mail-provider'\nimport { resendMailProvider } from './mail-provider-resend'\nimport { webhookMailProvider } from './mail-provider-webhook'\nimport type { EmailDeliveryEvent } from './email-delivery-events'\n\n/** The setting that names the provider. */\nexport const MAIL_PROVIDER_SETTING = 'AGLYN_MAIL_PROVIDER'\n\ntype Env = Record<string, string | undefined>\n\n/** The built-in providers, in the order detection tries them. */\nfunction builtInMailProviders(env: Env): MailProvider[] {\n  return [resendMailProvider(env), webhookMailProvider(env)]\n}\n\n/** The ids no registration may take. */\nexport function builtInMailProviderIds(): string[] {\n  return builtInMailProviders({}).map((provider) => provider.id)\n}\n\n/*==========================================\n * PROVIDERS A PLUGIN OR A FORK SUPPLIES.\n *\n * The slots live on `globalThis` under a registered symbol: a Next server\n * evaluates a module once for boot and again inside a route's bundle, and a\n * module-level map would give the route an empty copy of what boot filled.\n *=========================================*/\n\nconst REGISTRY_KEY = Symbol.for('aglyn.mail-providers')\n\nfunction registered(): Map<string, MailProvider> {\n  const slots = globalThis as { [REGISTRY_KEY]?: Map<string, MailProvider> }\n  if (!slots[REGISTRY_KEY]) slots[REGISTRY_KEY] = new Map()\n  return slots[REGISTRY_KEY] as Map<string, MailProvider>\n}\n\n/**\n * Registers a provider under its `id`, for a deployment that names it in\n * `AGLYN_MAIL_PROVIDER`. The same provider object again is a no-op; a\n * different one under a taken id throws naming it, because two providers\n * answering to one name would split an account's mail between them. A\n * built-in id throws too: the platform's default carrier is not something a\n * plugin can replace by registering.\n */\nexport function registerMailProvider(provider: MailProvider): void {\n  const id = String(provider?.id ?? '').trim().toLowerCase()\n  if (!id) throw new Error('a mail provider needs an id')\n  if (builtInMailProviderIds().includes(id)) {\n    throw new Error(`\"${id}\" is a built-in mail provider and cannot be registered`)\n  }\n  const slots = registered()\n  const existing = slots.get(id)\n  if (existing && existing !== provider) {\n    throw new Error(`a different mail provider is already registered as \"${id}\"`)\n  }\n  slots.set(id, provider)\n}\n\n/** Forgets every registration — for specs. */\nexport function resetMailProvidersForTests(): void {\n  registered().clear()\n}\n\n/*==========================================\n * SELECTION.\n *=========================================*/\n\n/** Why each provider that cannot be used cannot, keyed by the stand-in {@link mailProvider} returned. */\nconst UNAVAILABLE = new WeakMap<MailProvider, string>()\n\n/**\n * The stand-in for a provider the operator named and this process does not\n * have. It sends nothing and says why in everything that reads it.\n */\nfunction unavailableMailProvider(id: string): MailProvider {\n  const problem =\n    `${MAIL_PROVIDER_SETTING} is \"${id}\", which is not a built-in mail ` +\n    `provider (${builtInMailProviderIds().join(', ')}) and was not registered ` +\n    'in this process, so no mail is sent.'\n  const provider: MailProvider = {\n    id,\n    missingSettings: () => [MAIL_PROVIDER_SETTING],\n    send: async () => {\n      throw new Error(problem)\n    },\n  }\n  UNAVAILABLE.set(provider, problem)\n  return provider\n}\n\n/**\n * The provider this deployment's mail is handed to. Never `null`: an\n * unconfigured provider reports what it is missing, and a provider the\n * operator named that this process lacks is a stand-in that refuses (see\n * {@link mailProviderProblem}). Read per call, so a spec — or a runtime\n * whose environment arrives after module load — sees its current settings.\n */\nexport function mailProvider(env: Env = process.env as Env): MailProvider {\n  const requested = String(env[MAIL_PROVIDER_SETTING] ?? '').trim().toLowerCase()\n  const builtIns = builtInMailProviders(env)\n  if (!requested) {\n    return builtIns.find((provider) => !provider.missingSettings().length) ?? builtIns[0]\n  }\n  return (\n    builtIns.find((provider) => provider.id === requested) ??\n    registered().get(requested) ??\n    unavailableMailProvider(requested)\n  )\n}\n\n/**\n * A sentence saying the operator's chosen provider is not available in this\n * process, or `null` when it is (or none was chosen). Printed as an ERROR\n * wherever a skipped send is reported, because unlike an absent key it is\n * not a deployment that simply has no mail: somebody chose a provider and\n * this process cannot find it.\n */\nexport function mailProviderProblem(provider: MailProvider = mailProvider()): string | null {\n  return UNAVAILABLE.get(provider) ?? null\n}\n\n/*==========================================\n * WHAT THE REST OF THE PLATFORM ASKS.\n *\n * Each question in the platform's own vocabulary, answered by whichever\n * provider this deployment uses. A provider that cannot answer one gives the\n * empty answer — no events, no inbound message, reads that say they cannot\n * be made — never a guess.\n *=========================================*/\n\n/** One delivery-webhook payload as events, one per recipient; `[]` for anything else. */\nexport function normalizeDeliveryEvents(\n  payload: unknown,\n  receivedAtMs: number,\n  provider: MailProvider = mailProvider(),\n): EmailDeliveryEvent[] {\n  return provider.deliveryEvents?.(payload, receivedAtMs) ?? []\n}\n\n/** A received-mail notification, or `null` for any other payload. */\nexport function readInboundMailEvent(\n  payload: unknown,\n  provider: MailProvider = mailProvider(),\n): MailInboundEvent | null {\n  return provider.inboundEvent?.(payload) ?? null\n}\n\n/**\n * The provider's reads of its own account. A provider without any answers\n * with reads whose `unmet` says so, so a route handles \"cannot read\" the\n * same way whichever the reason.\n */\nexport function mailProviderReads(\n  provider: MailProvider = mailProvider(),\n): MailProviderReads {\n  if (provider.reads) return provider.reads\n  const reason =\n    mailProviderProblem(provider) ??\n    `The \"${provider.id}\" mail provider cannot read mail it sent or received.`\n  const refuse = async (): Promise<never> => {\n    throw new Error(reason)\n  }\n  return {\n    unmet: () => reason,\n    history: refuse,\n    message: refuse,\n    received: refuse,\n    sendingDomains: refuse,\n  }\n}\n"],"names":["resendMailProvider","webhookMailProvider","MAIL_PROVIDER_SETTING","builtInMailProviders","env","builtInMailProviderIds","map","provider","id","REGISTRY_KEY","Symbol","for","registered","slots","globalThis","Map","registerMailProvider","String","trim","toLowerCase","Error","includes","existing","get","set","resetMailProvidersForTests","clear","UNAVAILABLE","WeakMap","unavailableMailProvider","problem","join","missingSettings","send","mailProvider","process","builtIns","requested","find","length","mailProviderProblem","normalizeDeliveryEvents","payload","receivedAtMs","deliveryEvents","readInboundMailEvent","inboundEvent","mailProviderReads","reads","reason","refuse","unmet","history","message","received","sendingDomains"],"mappings":"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"}

package/src/lib/outbound-phishing-screen.d.ts

@@ -58,9 +58,22 @@ export interface PhishingScreenBrand {
 }
 export declare const PHISHING_SCREEN_BRANDS: readonly PhishingScreenBrand[];
 /**
- * Account-action and credential phrasing — the half of a lure that asks the
- * reader to DO something with an account. Only ever counted beside a brand
- * AND a foreign link; alone, several of these are ordinary transactional copy.
+ * Account and credential phrasing: the lure that asks the reader to DO
+ * something with an account — verify it, confirm it, sign in to it.
+ */
+export declare const ACCOUNT_LURE_PATTERNS: readonly RegExp[];
+/**
+ * Document-share phrasing (AGL-3447): the lure that says a file is waiting
+ * behind a secure door — "Secure Document Access Portal", "Continue to
+ * Document", "shared a file with you", "encrypted message". The credential
+ * harvest is on the far side of the button, so these are the words the page
+ * or the mail itself carries.
+ */
+export declare const DOCUMENT_SHARE_LURE_PATTERNS: readonly RegExp[];
+/**
+ * Every lure — the half of the three-part lure that asks the reader to act.
+ * Only ever counted beside a brand AND a foreign link; alone, several of
+ * these are ordinary transactional copy.
  */
 export declare const PHISHING_LURE_PATTERNS: readonly RegExp[];
 /** A signal the screen found. */
@@ -97,6 +110,54 @@ export type PhishingScreenSignal = {
     code: 'brand-action-page';
     brand: string;
     action: string;
+}
+/**
+ * The same, read over the page as a WHOLE (AGL-3447): a brand that is not
+ * the workspace's anywhere on a page that carries an account or
+ * document-share lure anywhere, or whose call to action leaves the site
+ * worded as one, and that links away (`hosted-page-screen.ts`). Soft.
+ */
+ | {
+    code: 'brand-lure-page';
+    brand: string;
+    lure: string;
+    host: string;
+}
+/**
+ * A published page's call to action — its only one, or one worded as an
+ * account or document action — sends visitors to a host that is not the
+ * site's, a listed brand's or a common link, on a page that carries an
+ * account or document-share lure (`hosted-page-screen.ts`, AGL-3447). No
+ * brand needed. Soft.
+ */
+ | {
+    code: 'offsite-action-page';
+    action: string;
+    lure: string;
+    host: string;
+}
+/**
+ * A site redirect whose path reads as an account or document-share lure
+ * sends visitors to such a host (`screenSiteRedirect`, AGL-3447). Soft.
+ */
+ | {
+    code: 'offsite-redirect';
+    source: string;
+    lure: string;
+    host: string;
+}
+/**
+ * Account or password phrasing beside a link elsewhere that carries the
+ * reader's own address (AGL-3453). STRONG when the address is the whole
+ * fragment (`#victim@example.com`), which only a landing page's script
+ * reads; soft when it is a query parameter or part of a longer fragment.
+ * The address itself is never stored.
+ */
+ | {
+    code: 'recipient-prefill-link';
+    host: string;
+    lure: string;
+    place: 'fragment' | 'parameter';
 };
 export interface PhishingScreenInput {
     subject?: string | null;
@@ -163,6 +224,21 @@ declare function isAnyOfficialDomain(registrable: string): boolean;
 export declare const MEDIA_EMBED_HOSTS: ReadonlySet<string>;
 /** The brand a host impersonates, or null. */
 export declare function lookalikeBrandForHost(host: string): PhishingScreenBrand | null;
+/**
+ * What a reader SEES in a body (AGL-3453): its text with the markup taken
+ * out, the way a mail client or a browser draws it.
+ *
+ * A kit splits every letter of a brand and a lure with a tag —
+ * `G<SPAN class=…>o<SPAN …>o…gle`, `P<SPAN …>a<SPAN …>s…word E<SPAN …>x…pired`
+ * — so the raw HTML never contains the word a reader reads. Tags are
+ * therefore removed with NO separator, which rejoins the letters; `<style>`,
+ * `<script>` and `<head>` are dropped with their contents; comments and
+ * zero-width characters are dropped; entities are decoded; whitespace is
+ * collapsed. A second reading that puts a space where a line or block
+ * breaks is added when it differs, so two words in two paragraphs are still
+ * two words. Links are NOT read from this: an href lives inside a tag.
+ */
+export declare function visibleTextOf(html: string | null | undefined): string;
 /** The hosts every link in the text points at, lowercased. */
 export declare function linkHostsIn(text: string): string[];
 /** Lowercased alphanumerics only, so "Wells-Fargo Advisors" contains `wellsfargo`. */
@@ -202,6 +278,7 @@ export declare const ACCOUNT_SUBDOMAIN_HOSTS: ReadonlySet<string>;
 export declare function phishingSignalTier(signal: {
     code: string;
     host?: string;
+    place?: string;
 }): PhishingSignalTier;
 /** Is a workspace of this age (days, `null` = unreadable) screened by the soft rules? */
 export declare function isYoungWorkspaceAge(ageDays: number | null | undefined): boolean;