@aglyn/shared-util-email 1.0.0-beta.217 → 1.0.0-beta.219

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/received-email.d.ts

@@ -17,23 +17,14 @@
 /**
  * RECEIVED MAIL, in the platform's own vocabulary (AGL-2657).
  *
- * Resend announces a received message as an `email.received` webhook that
- * carries only its metadata — who it was from and to, its subject, its
- * `Message-ID` — and the message itself is read afterwards from the
- * receiving API by the id the event named. This module is the one place
- * that reads that wire format: the event's shape, the API's shape, and the
- * neutral {@link ReceivedEmail} everything downstream works with. A second
- * provider is a second normalizer here and nothing else, which is the
- * arrangement `email-delivery-events.ts` has for the sending side.
- *
- * Pure but for {@link resendReceivedEmailSource}, which is a function that
- * must be CALLED with a key to do anything, so a client component that
- * reached this module through the barrel would execute nothing on load.
+ * A provider that receives mail announces each message with a notification
+ * that carries its metadata, and the message itself is read afterwards by
+ * the id the notification named. Both halves are the provider's to read —
+ * its `inboundEvent` and `reads.received` (see `mail-provider.ts`) — and
+ * both answer in the neutral {@link ReceivedEmail} everything downstream
+ * works with, so a route that files received mail never reads a vendor's
+ * payload.
  */
-/** The webhook event type a received message arrives as. */
-export declare const RESEND_RECEIVED_EVENT = "email.received";
-/** `GET {endpoint}/{id}` — one received message with its text and headers. */
-export declare const RESEND_RECEIVING_ENDPOINT = "https://api.resend.com/emails/receiving";
 /** One received message, provider-neutral. Addresses are as the headers spelled them. */
 export interface ReceivedEmail {
     /** The provider's id for the message — what a redelivered event repeats. */
@@ -54,33 +45,5 @@ export interface ReceivedEmail {
     /** When the provider received it, epoch ms; the read's clock when it said nothing usable. */
     receivedAtMs: number;
 }
-/**
- * The provider's id of the message an `email.received` event announces,
- * or `null` for any other event — including a malformed one, which is
- * acknowledged and dropped rather than retried forever.
- */
-export declare function resendReceivedEventId(event: unknown): string | null;
-/**
- * Every recipient the event names — To, Cc, Bcc and the addresses the
- * message was received for — so a route can find the capture token in the
- * metadata before it spends a read on the body.
- */
-export declare function resendReceivedEventRecipients(event: unknown): string[];
-/**
- * One received message as the receiving API answers it, in the neutral
- * shape. `null` for a payload with no id, which is not a message.
- */
-export declare function normalizeResendReceivedEmail(raw: unknown, nowMs?: number): ReceivedEmail | null;
 /** Reads one received message by the provider's id; `null` when it has none. */
 export type ReceivedEmailSource = (id: string) => Promise<ReceivedEmail | null>;
-/**
- * {@link ReceivedEmailSource} for Resend.
- *
- * Needs a FULL-ACCESS key: the sending-scoped `RESEND_API_KEY` answers
- * every read with `401 restricted_api_key`, which is the right posture for
- * the key that sends mail and the reason the console carries a separate
- * read key. A `404` is `null` — the message expired or never existed — and
- * anything else throws with the status, so the caller decides whether the
- * provider should retry.
- */
-export declare function resendReceivedEmailSource(apiKey: string, fetchImpl?: typeof fetch): ReceivedEmailSource;

package/src/lib/received-email.js

@@ -16,109 +16,13 @@
  */ /**
  * RECEIVED MAIL, in the platform's own vocabulary (AGL-2657).
  *
- * Resend announces a received message as an `email.received` webhook that
- * carries only its metadata — who it was from and to, its subject, its
- * `Message-ID` — and the message itself is read afterwards from the
- * receiving API by the id the event named. This module is the one place
- * that reads that wire format: the event's shape, the API's shape, and the
- * neutral {@link ReceivedEmail} everything downstream works with. A second
- * provider is a second normalizer here and nothing else, which is the
- * arrangement `email-delivery-events.ts` has for the sending side.
- *
- * Pure but for {@link resendReceivedEmailSource}, which is a function that
- * must be CALLED with a key to do anything, so a client component that
- * reached this module through the barrel would execute nothing on load.
- */ /** The webhook event type a received message arrives as. */ export const RESEND_RECEIVED_EVENT = 'email.received';
-/** `GET {endpoint}/{id}` — one received message with its text and headers. */ export const RESEND_RECEIVING_ENDPOINT = 'https://api.resend.com/emails/receiving';
-const list = (value)=>Array.isArray(value) ? value.map((entry)=>String(entry != null ? entry : '').trim()).filter((entry)=>entry !== '') : typeof value === 'string' && value.trim() ? [
-        value.trim()
-    ] : [];
-const text = (value)=>typeof value === 'string' ? value : '';
-/** A header by name, case-insensitively, off whatever map the provider sent. */ function header(headers, name) {
-    if (!headers || typeof headers !== 'object') return '';
-    const wanted = name.toLowerCase();
-    for (const [key, value] of Object.entries(headers)){
-        if (key.toLowerCase() === wanted) {
-            var _value_;
-            return Array.isArray(value) ? String((_value_ = value[0]) != null ? _value_ : '').trim() : String(value != null ? value : '').trim();
-        }
-    }
-    return '';
-}
-/**
- * The provider's id of the message an `email.received` event announces,
- * or `null` for any other event — including a malformed one, which is
- * acknowledged and dropped rather than retried forever.
- */ export function resendReceivedEventId(event) {
-    var _ref;
-    var _record_data;
-    const record = event;
-    if (!record || record.type !== RESEND_RECEIVED_EVENT) return null;
-    const id = String((_ref = (_record_data = record.data) == null ? void 0 : _record_data.email_id) != null ? _ref : '').trim();
-    return id || null;
-}
-/**
- * Every recipient the event names — To, Cc, Bcc and the addresses the
- * message was received for — so a route can find the capture token in the
- * metadata before it spends a read on the body.
- */ export function resendReceivedEventRecipients(event) {
-    var _ref;
-    const data = (_ref = event == null ? void 0 : event.data) != null ? _ref : {};
-    return [
-        ...list(data['to']),
-        ...list(data['cc']),
-        ...list(data['bcc']),
-        ...list(data['received_for'])
-    ];
-}
-/**
- * One received message as the receiving API answers it, in the neutral
- * shape. `null` for a payload with no id, which is not a message.
- */ export function normalizeResendReceivedEmail(raw, nowMs = Date.now()) {
-    var _record_id, _record_created_at, _record_message_id, _record_from, _record_subject;
-    const record = raw && typeof raw === 'object' ? raw : {};
-    const id = String((_record_id = record['id']) != null ? _record_id : '').trim();
-    if (!id) return null;
-    const headers = record['headers'];
-    const created = Date.parse(String((_record_created_at = record['created_at']) != null ? _record_created_at : ''));
-    return {
-        id,
-        messageId: String((_record_message_id = record['message_id']) != null ? _record_message_id : '').trim() || header(headers, 'message-id'),
-        inReplyTo: header(headers, 'in-reply-to'),
-        from: String((_record_from = record['from']) != null ? _record_from : '').trim(),
-        to: list(record['to']),
-        cc: list(record['cc']),
-        bcc: list(record['bcc']),
-        receivedFor: list(record['received_for']),
-        subject: String((_record_subject = record['subject']) != null ? _record_subject : '').trim(),
-        text: text(record['text']),
-        html: text(record['html']),
-        receivedAtMs: Number.isFinite(created) && created > 0 ? created : nowMs
-    };
-}
-/**
- * {@link ReceivedEmailSource} for Resend.
- *
- * Needs a FULL-ACCESS key: the sending-scoped `RESEND_API_KEY` answers
- * every read with `401 restricted_api_key`, which is the right posture for
- * the key that sends mail and the reason the console carries a separate
- * read key. A `404` is `null` — the message expired or never existed — and
- * anything else throws with the status, so the caller decides whether the
- * provider should retry.
- */ export function resendReceivedEmailSource(apiKey, fetchImpl = fetch) {
-    return async (id)=>{
-        const response = await fetchImpl(`${RESEND_RECEIVING_ENDPOINT}/${encodeURIComponent(id)}`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`
-            }
-        });
-        if (response.status === 404) return null;
-        if (!response.ok) {
-            const detail = await response.text().catch(()=>'');
-            throw new Error(`received email read failed: HTTP ${response.status} ${detail.slice(0, 200)}`);
-        }
-        return normalizeResendReceivedEmail(await response.json());
-    };
-}
+ * A provider that receives mail announces each message with a notification
+ * that carries its metadata, and the message itself is read afterwards by
+ * the id the notification named. Both halves are the provider's to read —
+ * its `inboundEvent` and `reads.received` (see `mail-provider.ts`) — and
+ * both answer in the neutral {@link ReceivedEmail} everything downstream
+ * works with, so a route that files received mail never reads a vendor's
+ * payload.
+ */ /** One received message, provider-neutral. Addresses are as the headers spelled them. */ /** Reads one received message by the provider's id; `null` when it has none. */ export { };
 
 //# sourceMappingURL=received-email.js.map

package/src/lib/received-email.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/received-email.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 * RECEIVED MAIL, in the platform's own vocabulary (AGL-2657).\n *\n * Resend announces a received message as an `email.received` webhook that\n * carries only its metadata — who it was from and to, its subject, its\n * `Message-ID` — and the message itself is read afterwards from the\n * receiving API by the id the event named. This module is the one place\n * that reads that wire format: the event's shape, the API's shape, and the\n * neutral {@link ReceivedEmail} everything downstream works with. A second\n * provider is a second normalizer here and nothing else, which is the\n * arrangement `email-delivery-events.ts` has for the sending side.\n *\n * Pure but for {@link resendReceivedEmailSource}, which is a function that\n * must be CALLED with a key to do anything, so a client component that\n * reached this module through the barrel would execute nothing on load.\n */\n\n/** The webhook event type a received message arrives as. */\nexport const RESEND_RECEIVED_EVENT = 'email.received'\n\n/** `GET {endpoint}/{id}` — one received message with its text and headers. */\nexport const RESEND_RECEIVING_ENDPOINT = 'https://api.resend.com/emails/receiving'\n\n/** One received message, provider-neutral. Addresses are as the headers spelled them. */\nexport interface ReceivedEmail {\n  /** The provider's id for the message — what a redelivered event repeats. */\n  id: string\n  /** The `Message-ID` header, angle brackets included, or `''`. */\n  messageId: string\n  /** The `In-Reply-To` header, or `''`. */\n  inReplyTo: string\n  from: string\n  to: string[]\n  cc: string[]\n  bcc: string[]\n  /** The addresses the provider received the message FOR — a forwarded alias's real target. */\n  receivedFor: string[]\n  subject: string\n  text: string\n  html: string\n  /** When the provider received it, epoch ms; the read's clock when it said nothing usable. */\n  receivedAtMs: number\n}\n\nconst list = (value: unknown): string[] =>\n  Array.isArray(value)\n    ? value.map((entry) => String(entry ?? '').trim()).filter((entry) => entry !== '')\n    : typeof value === 'string' && value.trim()\n      ? [value.trim()]\n      : []\n\nconst text = (value: unknown): string => (typeof value === 'string' ? value : '')\n\n/** A header by name, case-insensitively, off whatever map the provider sent. */\nfunction header(headers: unknown, name: string): string {\n  if (!headers || typeof headers !== 'object') return ''\n  const wanted = name.toLowerCase()\n  for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {\n    if (key.toLowerCase() === wanted) {\n      return Array.isArray(value) ? String(value[0] ?? '').trim() : String(value ?? '').trim()\n    }\n  }\n  return ''\n}\n\n/**\n * The provider's id of the message an `email.received` event announces,\n * or `null` for any other event — including a malformed one, which is\n * acknowledged and dropped rather than retried forever.\n */\nexport function resendReceivedEventId(event: unknown): string | null {\n  const record = event as { type?: unknown; data?: { email_id?: unknown } } | null\n  if (!record || record.type !== RESEND_RECEIVED_EVENT) return null\n  const id = String(record.data?.email_id ?? '').trim()\n  return id || null\n}\n\n/**\n * Every recipient the event names — To, Cc, Bcc and the addresses the\n * message was received for — so a route can find the capture token in the\n * metadata before it spends a read on the body.\n */\nexport function resendReceivedEventRecipients(event: unknown): string[] {\n  const data = (event as { data?: Record<string, unknown> } | null)?.data ?? {}\n  return [\n    ...list(data['to']),\n    ...list(data['cc']),\n    ...list(data['bcc']),\n    ...list(data['received_for']),\n  ]\n}\n\n/**\n * One received message as the receiving API answers it, in the neutral\n * shape. `null` for a payload with no id, which is not a message.\n */\nexport function normalizeResendReceivedEmail(\n  raw: unknown,\n  nowMs: number = Date.now(),\n): ReceivedEmail | null {\n  const record = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>\n  const id = String(record['id'] ?? '').trim()\n  if (!id) return null\n  const headers = record['headers']\n  const created = Date.parse(String(record['created_at'] ?? ''))\n  return {\n    id,\n    messageId: String(record['message_id'] ?? '').trim() || header(headers, 'message-id'),\n    inReplyTo: header(headers, 'in-reply-to'),\n    from: String(record['from'] ?? '').trim(),\n    to: list(record['to']),\n    cc: list(record['cc']),\n    bcc: list(record['bcc']),\n    receivedFor: list(record['received_for']),\n    subject: String(record['subject'] ?? '').trim(),\n    text: text(record['text']),\n    html: text(record['html']),\n    receivedAtMs: Number.isFinite(created) && created > 0 ? created : nowMs,\n  }\n}\n\n/** Reads one received message by the provider's id; `null` when it has none. */\nexport type ReceivedEmailSource = (id: string) => Promise<ReceivedEmail | null>\n\n/**\n * {@link ReceivedEmailSource} for Resend.\n *\n * Needs a FULL-ACCESS key: the sending-scoped `RESEND_API_KEY` answers\n * every read with `401 restricted_api_key`, which is the right posture for\n * the key that sends mail and the reason the console carries a separate\n * read key. A `404` is `null` — the message expired or never existed — and\n * anything else throws with the status, so the caller decides whether the\n * provider should retry.\n */\nexport function resendReceivedEmailSource(\n  apiKey: string,\n  fetchImpl: typeof fetch = fetch,\n): ReceivedEmailSource {\n  return async (id) => {\n    const response = await fetchImpl(\n      `${RESEND_RECEIVING_ENDPOINT}/${encodeURIComponent(id)}`,\n      { headers: { Authorization: `Bearer ${apiKey}` } },\n    )\n    if (response.status === 404) return null\n    if (!response.ok) {\n      const detail = await response.text().catch(() => '')\n      throw new Error(\n        `received email read failed: HTTP ${response.status} ${detail.slice(0, 200)}`,\n      )\n    }\n    return normalizeResendReceivedEmail(await response.json())\n  }\n}\n"],"names":["RESEND_RECEIVED_EVENT","RESEND_RECEIVING_ENDPOINT","list","value","Array","isArray","map","entry","String","trim","filter","text","header","headers","name","wanted","toLowerCase","key","Object","entries","resendReceivedEventId","event","record","type","id","data","email_id","resendReceivedEventRecipients","normalizeResendReceivedEmail","raw","nowMs","Date","now","created","parse","messageId","inReplyTo","from","to","cc","bcc","receivedFor","subject","html","receivedAtMs","Number","isFinite","resendReceivedEmailSource","apiKey","fetchImpl","fetch","response","encodeURIComponent","Authorization","status","ok","detail","catch","Error","slice","json"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;CAeC,GAED,0DAA0D,GAC1D,OAAO,MAAMA,wBAAwB,iBAAgB;AAErD,4EAA4E,GAC5E,OAAO,MAAMC,4BAA4B,0CAAyC;AAuBlF,MAAMC,OAAO,CAACC,QACZC,MAAMC,OAAO,CAACF,SACVA,MAAMG,GAAG,CAAC,CAACC,QAAUC,OAAOD,gBAAAA,QAAS,IAAIE,IAAI,IAAIC,MAAM,CAAC,CAACH,QAAUA,UAAU,MAC7E,OAAOJ,UAAU,YAAYA,MAAMM,IAAI,KACrC;QAACN,MAAMM,IAAI;KAAG,GACd,EAAE;AAEV,MAAME,OAAO,CAACR,QAA4B,OAAOA,UAAU,WAAWA,QAAQ;AAE9E,8EAA8E,GAC9E,SAASS,OAAOC,OAAgB,EAAEC,IAAY;IAC5C,IAAI,CAACD,WAAW,OAAOA,YAAY,UAAU,OAAO;IACpD,MAAME,SAASD,KAAKE,WAAW;IAC/B,KAAK,MAAM,CAACC,KAAKd,MAAM,IAAIe,OAAOC,OAAO,CAACN,SAAqC;QAC7E,IAAII,IAAID,WAAW,OAAOD,QAAQ;gBACKZ;YAArC,OAAOC,MAAMC,OAAO,CAACF,SAASK,QAAOL,UAAAA,KAAK,CAAC,EAAE,YAARA,UAAY,IAAIM,IAAI,KAAKD,OAAOL,gBAAAA,QAAS,IAAIM,IAAI;QACxF;IACF;IACA,OAAO;AACT;AAEA;;;;CAIC,GACD,OAAO,SAASW,sBAAsBC,KAAc;;QAGhCC;IAFlB,MAAMA,SAASD;IACf,IAAI,CAACC,UAAUA,OAAOC,IAAI,KAAKvB,uBAAuB,OAAO;IAC7D,MAAMwB,KAAKhB,gBAAOc,eAAAA,OAAOG,IAAI,qBAAXH,aAAaI,QAAQ,mBAAI,IAAIjB,IAAI;IACnD,OAAOe,MAAM;AACf;AAEA;;;;CAIC,GACD,OAAO,SAASG,8BAA8BN,KAAc;;IAC1D,MAAMI,eAAQJ,yBAAD,AAACA,MAAqDI,IAAI,mBAAI,CAAC;IAC5E,OAAO;WACFvB,KAAKuB,IAAI,CAAC,KAAK;WACfvB,KAAKuB,IAAI,CAAC,KAAK;WACfvB,KAAKuB,IAAI,CAAC,MAAM;WAChBvB,KAAKuB,IAAI,CAAC,eAAe;KAC7B;AACH;AAEA;;;CAGC,GACD,OAAO,SAASG,6BACdC,GAAY,EACZC,QAAgBC,KAAKC,GAAG,EAAE;QAGRV,YAGgBA,oBAGdA,oBAELA,cAKGA;IAdlB,MAAMA,SAAUO,OAAO,OAAOA,QAAQ,WAAWA,MAAM,CAAC;IACxD,MAAML,KAAKhB,QAAOc,aAAAA,MAAM,CAAC,KAAK,YAAZA,aAAgB,IAAIb,IAAI;IAC1C,IAAI,CAACe,IAAI,OAAO;IAChB,MAAMX,UAAUS,MAAM,CAAC,UAAU;IACjC,MAAMW,UAAUF,KAAKG,KAAK,CAAC1B,QAAOc,qBAAAA,MAAM,CAAC,aAAa,YAApBA,qBAAwB;IAC1D,OAAO;QACLE;QACAW,WAAW3B,QAAOc,qBAAAA,MAAM,CAAC,aAAa,YAApBA,qBAAwB,IAAIb,IAAI,MAAMG,OAAOC,SAAS;QACxEuB,WAAWxB,OAAOC,SAAS;QAC3BwB,MAAM7B,QAAOc,eAAAA,MAAM,CAAC,OAAO,YAAdA,eAAkB,IAAIb,IAAI;QACvC6B,IAAIpC,KAAKoB,MAAM,CAAC,KAAK;QACrBiB,IAAIrC,KAAKoB,MAAM,CAAC,KAAK;QACrBkB,KAAKtC,KAAKoB,MAAM,CAAC,MAAM;QACvBmB,aAAavC,KAAKoB,MAAM,CAAC,eAAe;QACxCoB,SAASlC,QAAOc,kBAAAA,MAAM,CAAC,UAAU,YAAjBA,kBAAqB,IAAIb,IAAI;QAC7CE,MAAMA,KAAKW,MAAM,CAAC,OAAO;QACzBqB,MAAMhC,KAAKW,MAAM,CAAC,OAAO;QACzBsB,cAAcC,OAAOC,QAAQ,CAACb,YAAYA,UAAU,IAAIA,UAAUH;IACpE;AACF;AAKA;;;;;;;;;CASC,GACD,OAAO,SAASiB,0BACdC,MAAc,EACdC,YAA0BC,KAAK;IAE/B,OAAO,OAAO1B;QACZ,MAAM2B,WAAW,MAAMF,UACrB,GAAGhD,0BAA0B,CAAC,EAAEmD,mBAAmB5B,KAAK,EACxD;YAAEX,SAAS;gBAAEwC,eAAe,CAAC,OAAO,EAAEL,QAAQ;YAAC;QAAE;QAEnD,IAAIG,SAASG,MAAM,KAAK,KAAK,OAAO;QACpC,IAAI,CAACH,SAASI,EAAE,EAAE;YAChB,MAAMC,SAAS,MAAML,SAASxC,IAAI,GAAG8C,KAAK,CAAC,IAAM;YACjD,MAAM,IAAIC,MACR,CAAC,iCAAiC,EAAEP,SAASG,MAAM,CAAC,CAAC,EAAEE,OAAOG,KAAK,CAAC,GAAG,MAAM;QAEjF;QACA,OAAO/B,6BAA6B,MAAMuB,SAASS,IAAI;IACzD;AACF"}
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/received-email.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 * RECEIVED MAIL, in the platform's own vocabulary (AGL-2657).\n *\n * A provider that receives mail announces each message with a notification\n * that carries its metadata, and the message itself is read afterwards by\n * the id the notification named. Both halves are the provider's to read —\n * its `inboundEvent` and `reads.received` (see `mail-provider.ts`) — and\n * both answer in the neutral {@link ReceivedEmail} everything downstream\n * works with, so a route that files received mail never reads a vendor's\n * payload.\n */\n\n/** One received message, provider-neutral. Addresses are as the headers spelled them. */\nexport interface ReceivedEmail {\n  /** The provider's id for the message — what a redelivered event repeats. */\n  id: string\n  /** The `Message-ID` header, angle brackets included, or `''`. */\n  messageId: string\n  /** The `In-Reply-To` header, or `''`. */\n  inReplyTo: string\n  from: string\n  to: string[]\n  cc: string[]\n  bcc: string[]\n  /** The addresses the provider received the message FOR — a forwarded alias's real target. */\n  receivedFor: string[]\n  subject: string\n  text: string\n  html: string\n  /** When the provider received it, epoch ms; the read's clock when it said nothing usable. */\n  receivedAtMs: number\n}\n\n/** Reads one received message by the provider's id; `null` when it has none. */\nexport type ReceivedEmailSource = (id: string) => Promise<ReceivedEmail | null>\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;CAUC,GAED,uFAAuF,GAqBvF,8EAA8E,GAC9E,WAA+E"}

package/src/lib/risk-notice-catalog.js

@@ -278,6 +278,12 @@ export const RISK_STAFF_ACTIONS = {
 const ASK_FOR_REVIEW = 'If you think this is a mistake, choose Request a review and tell us about it. A person reads every request.';
 const REVIEW_TIME = 'Reviews are usually answered within one business day. You will get a notice either way.';
 const CANNOT_SIGN_IN = 'If you cannot sign in, reply to this email or write to {{support.email}} with the reference {{reference}}.';
+/**
+ * How a locked ACCOUNT appeals (AGL-3420). It cannot sign in, so the way in
+ * is mail: a reply to the notice reaches support (the notice's Reply-To),
+ * and support answers from its own mailbox — which a ban does not refuse,
+ * because a ban refuses what the platform sends, not what a person does.
+ */ const APPEAL_BY_REPLY = 'If you believe this is a mistake, you can appeal: reply to this email, or write to {{support.email}} with the reference {{reference}}. Tell us anything that explains what happened. A person reviews every appeal and answers from that address.';
 /*
  * The catalog. Exhaustive by type: a kind added to RISK_EVENT_KINDS is a
  * compile error here until somebody writes what each audience is told.
@@ -1421,7 +1427,7 @@ const CANNOT_SIGN_IN = 'If you cannot sign in, reply to this email or write to {
             meaning: 'While it is locked: {{lock.affected}}',
             steps: [
                 'Read the message above; it says what we need from you.',
-                CANNOT_SIGN_IN
+                APPEAL_BY_REPLY
             ],
             actions: [
                 'contact-support'