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

package/src/lib/email-delivery-events.js

@@ -1,4 +1,3 @@
-import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -20,13 +19,14 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * ## The seam
  *
  * A staff answer to "did they get the invite, and did they open it?" must not
- * be a question about Resend. Two things follow from that, and this module is
- * both of them:
+ * be a question about one sending vendor. Two things follow from that, and
+ * this module is both of them:
  *
  * 1. **The stored shape is ours.** Nothing downstream — the delivery log, the
  *    staff card, a future export — reads a provider's field names or its event
- *    strings. Swapping the sender changes exactly one function in this file
- *    and nothing else in the tree.
+ *    strings. A provider turns its own wire format into these types (its
+ *    `deliveryEvents` and `reads`, see `mail-provider.ts`), and swapping the
+ *    sender changes that provider and nothing else in the tree.
  * 2. **The history is ours.** The log is written into our own Firestore and
  *    read from there, never from the provider on render. A provider's list
  *    endpoint is a different shape per vendor, has its own retention window,
@@ -37,8 +37,8 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  *    provider. The event feed only knows mail sent after it was connected, so
  *    a log fed by events alone is empty for all existing history — which is
  *    precisely the mail a support question is about. The second half of this
- *    module (see THE READ SIDE OF THE SEAM below) imports that history
- *    through the same neutral vocabulary, once, into the same store.
+ *    module (see THE READ SIDE OF THE SEAM below) is the vocabulary that
+ *    history is imported through, once, into the same store.
  *
  * ## Pure on purpose
  *
@@ -46,14 +46,17 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * CLIENT components through this library's barrel, so anything reachable from
  * it that touched `firebase-admin` would drag the admin SDK into a browser
  * bundle. Normalisation is a pure function of a payload; the writing lives in
- * `@aglyn/tenant-data-admin/server/email-delivery-log`.
- *
- * The one `fetch` is `resendDeliveryHistorySource`, which is a function that
- * must be CALLED with a key to do anything — it holds no module state and is
- * unreachable from a client component, unlike an admin-SDK import, which
- * executes on load.
- */ import { readBounceText } from "./mail-bounce.js";
-/** Lifecycle states ordered worst-last, for {@link worstDeliveryStatus}. */ const STATUS_SEVERITY = {
+ * `@aglyn/tenant-data-admin/server/email-delivery-log`, and the reading
+ * of a provider's payloads in that provider.
+ */ /**
+ * The lifecycle of one message, in the order it normally happens.
+ *
+ * Chosen to be the intersection every ESP can report rather than the union of
+ * what any one of them does: a vendor with no equivalent for a state simply
+ * never produces it, and a vendor with a richer taxonomy folds into the
+ * nearest of these rather than widening the type. `delayed` is retryable and
+ * `failed` is not, which is the distinction a staffer actually needs.
+ */ /** Lifecycle states ordered worst-last, for {@link worstDeliveryStatus}. */ const STATUS_SEVERITY = {
     sent: 1,
     delivered: 2,
     opened: 3,
@@ -90,237 +93,5 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
     }
     return {};
 }
-/** Epoch ms from an ISO string or a number, or `null` when unreadable. */ function eventTimeMs(value) {
-    if (typeof value === 'number' && Number.isFinite(value)) return value;
-    const parsed = Date.parse(String(value != null ? value : ''));
-    return Number.isFinite(parsed) ? parsed : null;
-}
-function normalizeBounceType(value) {
-    const lowered = String(value != null ? value : '').trim().toLowerCase();
-    if (lowered === 'permanent') return 'permanent';
-    if (lowered === 'transient') return 'transient';
-    return lowered ? 'undetermined' : null;
-}
-/** The Resend event names we understand, mapped onto ours. */ const RESEND_EVENT_TYPES = {
-    'email.sent': 'sent',
-    'email.delivered': 'delivered',
-    'email.delivery_delayed': 'delayed',
-    'email.opened': 'opened',
-    'email.clicked': 'clicked',
-    'email.bounced': 'bounced',
-    'email.complained': 'complained',
-    'email.failed': 'failed'
-};
-/**
- * Turns one Resend webhook payload into zero or more of our events — **the
- * only function in the tree that knows Resend's wire format.**
- *
- * One event per recipient, not per message: a send addressed to three people
- * produces one webhook, and a staff view keyed on a person has to be able to
- * find it under each of them.
- *
- * Returns an empty array for anything unrecognised — a contact or domain
- * event, an inbound `email.received`, a type added after this was written.
- * Silence rather than a throw, because a webhook handler that 500s on an
- * unfamiliar event teaches the provider to retry it forever.
- *
- * @param payload The parsed webhook body.
- * @param receivedAtMs Fallback timestamp for a payload that carries none.
- */ export function normalizeResendDeliveryEvents(payload, receivedAtMs) {
-    var _event_type, _event_data, _ref, _data_email_id, _ref1, _ref2, _ref3, _eventTimeMs, _data_subject;
-    var _data_click, _data_open, _data_bounce, _data_bounce1, _data_bounce2, _data_bounce3, _data_bounce4;
-    const event = payload != null ? payload : {};
-    const type = RESEND_EVENT_TYPES[String((_event_type = event.type) != null ? _event_type : '')];
-    if (!type) return [];
-    const data = (_event_data = event.data) != null ? _event_data : {};
-    const providerMessageId = String((_ref = (_data_email_id = data.email_id) != null ? _data_email_id : data.id) != null ? _ref : '').trim();
-    if (!providerMessageId) return [];
-    const recipients = (Array.isArray(data.to) ? data.to : [
-        data.to
-    ]).map((address)=>String(address != null ? address : '').trim().toLowerCase()).filter((address)=>address.includes('@'));
-    if (!recipients.length) return [];
-    // The per-state timestamp when the provider gives one, because an open
-    // three days after the send is the whole point of recording an open.
-    const at = (_ref1 = (_ref2 = (_ref3 = (_eventTimeMs = eventTimeMs((_data_click = data.click) == null ? void 0 : _data_click.timestamp)) != null ? _eventTimeMs : eventTimeMs((_data_open = data.open) == null ? void 0 : _data_open.timestamp)) != null ? _ref3 : eventTimeMs(event.created_at)) != null ? _ref2 : eventTimeMs(data.created_at)) != null ? _ref1 : receivedAtMs;
-    const subject = String((_data_subject = data.subject) != null ? _data_subject : '').trim() || null;
-    const tags = normalizeEventTags(data.tags);
-    const from = bareSenderAddress(data.from);
-    // The provider folds a DSN's fields into one sentence; the structured
-    // ones are read first where a payload carries them.
-    const bounceText = type === 'bounced' ? readBounceText([
-        (_data_bounce = data.bounce) == null ? void 0 : _data_bounce.diagnosticCode,
-        (_data_bounce1 = data.bounce) == null ? void 0 : _data_bounce1.diagnostic_code,
-        (_data_bounce2 = data.bounce) == null ? void 0 : _data_bounce2.remoteMta,
-        (_data_bounce3 = data.bounce) == null ? void 0 : _data_bounce3.remote_mta,
-        (_data_bounce4 = data.bounce) == null ? void 0 : _data_bounce4.message
-    ].filter((part)=>typeof part === 'string' && part.trim()).join(' ')) : null;
-    return recipients.map((to)=>{
-        var _ref, _ref1, _ref2;
-        var _data_click, _data_bounce, _data_bounce1, _data_failed;
-        return _extends({
-            type,
-            at,
-            provider: 'resend',
-            providerMessageId,
-            to,
-            subject,
-            context: tags['context'] || null,
-            tags,
-            link: type === 'clicked' ? String((_ref = (_data_click = data.click) == null ? void 0 : _data_click.link) != null ? _ref : '') || null : null,
-            bounceType: type === 'bounced' ? normalizeBounceType((_data_bounce = data.bounce) == null ? void 0 : _data_bounce.type) : null,
-            detail: String((_ref1 = (_ref2 = (_data_bounce1 = data.bounce) == null ? void 0 : _data_bounce1.message) != null ? _ref2 : (_data_failed = data.failed) == null ? void 0 : _data_failed.reason) != null ? _ref1 : '').trim() || null
-        }, from ? {
-            from
-        } : {}, (bounceText == null ? void 0 : bounceText.status) ? {
-            bounceStatus: bounceText.status
-        } : {}, (bounceText == null ? void 0 : bounceText.remoteMta) ? {
-            remoteMta: bounceText.remoteMta
-        } : {});
-    });
-}
-/**
- * A provider's `last_event` string, mapped onto our lifecycle.
- *
- * Deliberately the bare state names rather than the `email.*` event names:
- * the list endpoint reports `"delivered"`, the webhook reports
- * `"email.delivered"`, and they are two different vocabularies for one
- * concept. Both are accepted here so a provider that unifies them later
- * needs no change.
- */ const RESEND_LAST_EVENTS = {
-    sent: 'sent',
-    delivered: 'delivered',
-    delivery_delayed: 'delayed',
-    opened: 'opened',
-    clicked: 'clicked',
-    bounced: 'bounced',
-    complained: 'complained',
-    failed: 'failed',
-    canceled: 'failed',
-    queued: 'sent',
-    scheduled: 'sent'
-};
-/**
- * Turns one entry from Resend's `GET /emails` list into zero or more
- * snapshots — one per recipient, for the same reason the event adapter fans
- * out: the staff view is keyed on a person.
- *
- * An unrecognised `last_event` falls back to `sent` rather than being
- * dropped. The message demonstrably exists and was addressed to somebody, and
- * "we sent this and cannot characterise what happened next" is a far more
- * useful row than no row — which is the state that sent a staffer to the
- * vendor dashboard in the first place.
- */ export function normalizeResendSentEmails(raw) {
-    var _record_id, _record_created_at, _RESEND_LAST_EVENTS_String_trim_toLowerCase, _record_last_event;
-    const record = raw != null ? raw : {};
-    const providerMessageId = String((_record_id = record.id) != null ? _record_id : '').trim();
-    if (!providerMessageId) return [];
-    const recipients = (Array.isArray(record.to) ? record.to : [
-        record.to
-    ]).map((address)=>String(address != null ? address : '').trim().toLowerCase()).filter((address)=>address.includes('@'));
-    if (!recipients.length) return [];
-    const parsed = Date.parse(String((_record_created_at = record.created_at) != null ? _record_created_at : ''));
-    const sentAt = Number.isFinite(parsed) ? parsed : 0;
-    // A snapshot with no timestamp cannot be ordered, and the log's read drops
-    // any document missing its sort key — so it is refused rather than written
-    // somewhere nothing will look for it.
-    if (!sentAt) return [];
-    const status = (_RESEND_LAST_EVENTS_String_trim_toLowerCase = RESEND_LAST_EVENTS[String((_record_last_event = record.last_event) != null ? _record_last_event : '').trim().toLowerCase()]) != null ? _RESEND_LAST_EVENTS_String_trim_toLowerCase : 'sent';
-    return recipients.map((to)=>{
-        var _record_subject;
-        return {
-            provider: 'resend',
-            providerMessageId,
-            to,
-            subject: String((_record_subject = record.subject) != null ? _record_subject : '').trim() || null,
-            sentAt,
-            status
-        };
-    });
-}
-/** Resend's list endpoint. Paginates with `after=<id>`; caps at 100. */ export const RESEND_EMAILS_ENDPOINT = 'https://api.resend.com/emails';
-/**
- * {@link EmailDeliveryHistorySource} for Resend.
- *
- * Needs a FULL-ACCESS key: a sending-scoped key answers every read on this
- * endpoint with `401 restricted_api_key`, which is the correct posture for
- * the key that sends mail and the reason this takes its own.
- */ export function resendDeliveryHistorySource(apiKey) {
-    return async ({ cursor, limit } = {})=>{
-        var _ref;
-        var _entries_;
-        const params = new URLSearchParams({
-            limit: String(Math.min(Math.max(1, limit != null ? limit : 100), 100))
-        });
-        if (cursor) params.set('after', cursor);
-        const response = await fetch(`${RESEND_EMAILS_ENDPOINT}?${params}`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`
-            }
-        });
-        if (!response.ok) {
-            const detail = await response.text().catch(()=>'');
-            throw new Error(`email history read failed: HTTP ${response.status} ${detail.slice(0, 200)}`);
-        }
-        const body = await response.json();
-        const entries = Array.isArray(body == null ? void 0 : body.data) ? body.data : [];
-        const snapshots = entries.flatMap((entry)=>normalizeResendSentEmails(entry));
-        // The cursor is the LAST RAW entry's id, not the last snapshot's: a page
-        // whose final entry fanned out to zero snapshots (no recipient, no
-        // timestamp) would otherwise rewind the cursor to an earlier message and
-        // loop over the same page forever.
-        const lastId = String((_ref = (_entries_ = entries[entries.length - 1]) == null ? void 0 : _entries_.id) != null ? _ref : '').trim();
-        return {
-            snapshots,
-            nextCursor: (body == null ? void 0 : body.has_more) && lastId ? lastId : null
-        };
-    };
-}
-function addressList(raw) {
-    return (Array.isArray(raw) ? raw : raw == null ? [] : [
-        raw
-    ]).map((address)=>String(address != null ? address : '').trim()).filter(Boolean);
-}
-/** Resend's `GET /emails/:id` payload, in our vocabulary. */ export function normalizeResendMessage(raw) {
-    var _record_id, _record_created_at, _record_from, _record_subject, _RESEND_LAST_EVENTS_String_trim_toLowerCase, _record_last_event;
-    const record = raw != null ? raw : {};
-    const providerMessageId = String((_record_id = record.id) != null ? _record_id : '').trim();
-    if (!providerMessageId) return null;
-    const parsed = Date.parse(String((_record_created_at = record.created_at) != null ? _record_created_at : ''));
-    return {
-        provider: 'resend',
-        providerMessageId,
-        to: addressList(record.to),
-        cc: addressList(record.cc),
-        bcc: addressList(record.bcc),
-        from: String((_record_from = record.from) != null ? _record_from : '').trim() || null,
-        replyTo: addressList(record.reply_to).length ? addressList(record.reply_to) : null,
-        subject: String((_record_subject = record.subject) != null ? _record_subject : '').trim() || null,
-        // Empty string is NOT null here, and the difference is the point: a
-        // message that went out text-only really does have an empty HTML part,
-        // and a reader has to be able to tell that from "we could not fetch it".
-        html: typeof record.html === 'string' ? record.html : null,
-        text: typeof record.text === 'string' ? record.text : null,
-        sentAt: Number.isFinite(parsed) ? parsed : null,
-        status: (_RESEND_LAST_EVENTS_String_trim_toLowerCase = RESEND_LAST_EVENTS[String((_record_last_event = record.last_event) != null ? _record_last_event : '').trim().toLowerCase()]) != null ? _RESEND_LAST_EVENTS_String_trim_toLowerCase : null
-    };
-}
-/** Resend's single-message endpoint. Needs the same full-access key. */ export function resendDeliveryMessageSource(apiKey) {
-    return async (providerMessageId)=>{
-        const response = await fetch(`${RESEND_EMAILS_ENDPOINT}/${encodeURIComponent(providerMessageId)}`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`
-            }
-        });
-        // A message the provider has aged out is a 404, and that is an ANSWER —
-        // "we know this was sent and the body is gone" — not a failure to report
-        // as an error the staffer must act on.
-        if (response.status === 404) return null;
-        if (!response.ok) {
-            const detail = await response.text().catch(()=>'');
-            throw new Error(`message read failed: HTTP ${response.status} ${detail.slice(0, 200)}`);
-        }
-        return normalizeResendMessage(await response.json());
-    };
-}
 
 //# sourceMappingURL=email-delivery-events.js.map

package/src/lib/email-delivery-events.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/email-delivery-events.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 * WHAT HAPPENED TO A MESSAGE, IN OUR OWN VOCABULARY.\n *\n * ## The seam\n *\n * A staff answer to \"did they get the invite, and did they open it?\" must not\n * be a question about Resend. Two things follow from that, and this module is\n * both of them:\n *\n * 1. **The stored shape is ours.** Nothing downstream — the delivery log, the\n *    staff card, a future export — reads a provider's field names or its event\n *    strings. Swapping the sender changes exactly one function in this file\n *    and nothing else in the tree.\n * 2. **The history is ours.** The log is written into our own Firestore and\n *    read from there, never from the provider on render. A provider's list\n *    endpoint is a different shape per vendor, has its own retention window,\n *    and disappears entirely with the account; a record we keep survives the\n *    migration that the seam exists to make possible.\n *\n *    That is a rule about the READ PATH, not a rule against ever reading the\n *    provider. The event feed only knows mail sent after it was connected, so\n *    a log fed by events alone is empty for all existing history — which is\n *    precisely the mail a support question is about. The second half of this\n *    module (see THE READ SIDE OF THE SEAM below) imports that history\n *    through the same neutral vocabulary, once, into the same store.\n *\n * ## Pure on purpose\n *\n * No Firestore and no admin SDK. `system-email-catalog` is imported by console\n * CLIENT components through this library's barrel, so anything reachable from\n * it that touched `firebase-admin` would drag the admin SDK into a browser\n * bundle. Normalisation is a pure function of a payload; the writing lives in\n * `@aglyn/tenant-data-admin/server/email-delivery-log`.\n *\n * The one `fetch` is `resendDeliveryHistorySource`, which is a function that\n * must be CALLED with a key to do anything — it holds no module state and is\n * unreachable from a client component, unlike an admin-SDK import, which\n * executes on load.\n */\n\nimport { readBounceText } from './mail-bounce'\n\n/**\n * The lifecycle of one message, in the order it normally happens.\n *\n * Chosen to be the intersection every ESP can report rather than the union of\n * what any one of them does: a vendor with no equivalent for a state simply\n * never produces it, and a vendor with a richer taxonomy folds into the\n * nearest of these rather than widening the type. `delayed` is retryable and\n * `failed` is not, which is the distinction a staffer actually needs.\n */\nexport type EmailDeliveryEventType =\n  | 'sent'\n  | 'delivered'\n  | 'delayed'\n  | 'opened'\n  | 'clicked'\n  | 'bounced'\n  | 'complained'\n  | 'failed'\n\n/** Lifecycle states ordered worst-last, for {@link worstDeliveryStatus}. */\nconst STATUS_SEVERITY: Record<EmailDeliveryEventType, number> = {\n  sent: 1,\n  delivered: 2,\n  opened: 3,\n  clicked: 4,\n  delayed: 5,\n  complained: 6,\n  bounced: 7,\n  failed: 8,\n}\n\n/**\n * One normalized delivery event.\n *\n * `at` is epoch milliseconds rather than a Firestore timestamp so this type\n * stays usable in a browser, in a test, and in whatever writes it next.\n */\nexport interface EmailDeliveryEvent {\n  type: EmailDeliveryEventType\n  /** When the PROVIDER says it happened, falling back to receipt time. */\n  at: number\n  /** Slug of the sending provider, e.g. `'resend'`. */\n  provider: string\n  /** The provider's id for the message. Our per-message document key. */\n  providerMessageId: string\n  /** Recipient, lowercased. One address per record even on a multi-recipient send. */\n  to: string\n  subject: string | null\n  /**\n   * The sender label `sendEmail` stamps on every message (`'invite'`,\n   * `'password-reset'`, `'campaign'`, …). This is what makes the staff view\n   * legible: without it a row says only that *an* email was sent.\n   */\n  context: string | null\n  /** Everything else the send was tagged with, e.g. `hostId`, `campaignId`. */\n  tags: Record<string, string>\n  /** `clicked` only: the destination the recipient followed. */\n  link: string | null\n  /**\n   * `bounced` only: whether the mailbox is gone (`permanent`) or the failure\n   * was temporary. Lowercased, because providers disagree on capitalisation\n   * and a staff filter must not depend on which one is in use.\n   */\n  bounceType: 'permanent' | 'transient' | 'undetermined' | null\n  /** Provider-supplied explanation, for the states that carry one. */\n  detail: string | null\n  /**\n   * The bare sender address, lowercased: the domain it names is the sending\n   * domain a gateway's verdict is filed against (AGL-3328). Absent from\n   * events normalized before it existed, and `null` when the provider sent\n   * none.\n   */\n  from?: string | null\n  /**\n   * `bounced` only: the enhanced status code (`5.7.1`) and the receiving\n   * server the provider's bounce message names, read by `readBounceText` —\n   * what a Gmail DSN hands over as `Status` and `Remote-MTA` (AGL-3328).\n   */\n  bounceStatus?: string | null\n  remoteMta?: string | null\n}\n\n/** The bare address of a `From:` value (`\"Acme\" <hi@acme.com>` → `hi@acme.com`), lowercased. */\nexport function bareSenderAddress(value: unknown): string | null {\n  const raw = String(value ?? '').trim()\n  const angle = raw.match(/<([^>]+)>/)\n  const address = (angle ? angle[1] : raw).trim().toLowerCase()\n  return /^[^\\s@<>]+@[^\\s@<>]+\\.[^\\s@<>]+$/.test(address) ? address : null\n}\n\n/** The later of two statuses on the lifecycle, worst winning a tie. */\nexport function worstDeliveryStatus(\n  current: EmailDeliveryEventType | null | undefined,\n  next: EmailDeliveryEventType,\n): EmailDeliveryEventType {\n  if (!current) return next\n  return STATUS_SEVERITY[next] >= STATUS_SEVERITY[current] ? next : current\n}\n\n/** Tags arrive as an array of `{name, value}` or a plain map — accept both. */\nexport function normalizeEventTags(raw: unknown): Record<string, string> {\n  if (Array.isArray(raw)) {\n    const map: Record<string, string> = {}\n    for (const tag of raw) {\n      if (tag?.name) map[String(tag.name)] = String(tag.value ?? '')\n    }\n    return map\n  }\n  if (raw && typeof raw === 'object') {\n    return Object.fromEntries(\n      Object.entries(raw as Record<string, unknown>).map(([key, value]) => [\n        key,\n        String(value ?? ''),\n      ]),\n    )\n  }\n  return {}\n}\n\n/** Epoch ms from an ISO string or a number, or `null` when unreadable. */\nfunction eventTimeMs(value: unknown): number | null {\n  if (typeof value === 'number' && Number.isFinite(value)) return value\n  const parsed = Date.parse(String(value ?? ''))\n  return Number.isFinite(parsed) ? parsed : null\n}\n\nfunction normalizeBounceType(\n  value: unknown,\n): EmailDeliveryEvent['bounceType'] {\n  const lowered = String(value ?? '')\n    .trim()\n    .toLowerCase()\n  if (lowered === 'permanent') return 'permanent'\n  if (lowered === 'transient') return 'transient'\n  return lowered ? 'undetermined' : null\n}\n\n/** The Resend event names we understand, mapped onto ours. */\nconst RESEND_EVENT_TYPES: Record<string, EmailDeliveryEventType> = {\n  'email.sent': 'sent',\n  'email.delivered': 'delivered',\n  'email.delivery_delayed': 'delayed',\n  'email.opened': 'opened',\n  'email.clicked': 'clicked',\n  'email.bounced': 'bounced',\n  'email.complained': 'complained',\n  'email.failed': 'failed',\n}\n\n/**\n * Turns one Resend webhook payload into zero or more of our events — **the\n * only function in the tree that knows Resend's wire format.**\n *\n * One event per recipient, not per message: a send addressed to three people\n * produces one webhook, and a staff view keyed on a person has to be able to\n * find it under each of them.\n *\n * Returns an empty array for anything unrecognised — a contact or domain\n * event, an inbound `email.received`, a type added after this was written.\n * Silence rather than a throw, because a webhook handler that 500s on an\n * unfamiliar event teaches the provider to retry it forever.\n *\n * @param payload The parsed webhook body.\n * @param receivedAtMs Fallback timestamp for a payload that carries none.\n */\nexport function normalizeResendDeliveryEvents(\n  payload: unknown,\n  receivedAtMs: number,\n): EmailDeliveryEvent[] {\n  const event = (payload ?? {}) as Record<string, any>\n  const type = RESEND_EVENT_TYPES[String(event.type ?? '')]\n  if (!type) return []\n\n  const data = (event.data ?? {}) as Record<string, any>\n  const providerMessageId = String(data.email_id ?? data.id ?? '').trim()\n  if (!providerMessageId) return []\n\n  const recipients = (Array.isArray(data.to) ? data.to : [data.to])\n    .map((address: unknown) => String(address ?? '').trim().toLowerCase())\n    .filter((address: string) => address.includes('@'))\n  if (!recipients.length) return []\n\n  // The per-state timestamp when the provider gives one, because an open\n  // three days after the send is the whole point of recording an open.\n  const at =\n    eventTimeMs(data.click?.timestamp) ??\n    eventTimeMs(data.open?.timestamp) ??\n    eventTimeMs(event.created_at) ??\n    eventTimeMs(data.created_at) ??\n    receivedAtMs\n\n  const subject = String(data.subject ?? '').trim() || null\n  const tags = normalizeEventTags(data.tags)\n  const from = bareSenderAddress(data.from)\n  // The provider folds a DSN's fields into one sentence; the structured\n  // ones are read first where a payload carries them.\n  const bounceText =\n    type === 'bounced'\n      ? readBounceText(\n          [data.bounce?.diagnosticCode, data.bounce?.diagnostic_code, data.bounce?.remoteMta, data.bounce?.remote_mta, data.bounce?.message]\n            .filter((part: unknown) => typeof part === 'string' && part.trim())\n            .join(' '),\n        )\n      : null\n\n  return recipients.map((to: string) => ({\n    type,\n    at,\n    provider: 'resend',\n    providerMessageId,\n    to,\n    subject,\n    context: tags['context'] || null,\n    tags,\n    link: type === 'clicked' ? String(data.click?.link ?? '') || null : null,\n    bounceType: type === 'bounced' ? normalizeBounceType(data.bounce?.type) : null,\n    detail:\n      String(data.bounce?.message ?? data.failed?.reason ?? '').trim() || null,\n    ...(from ? { from } : {}),\n    ...(bounceText?.status ? { bounceStatus: bounceText.status } : {}),\n    ...(bounceText?.remoteMta ? { remoteMta: bounceText.remoteMta } : {}),\n  }))\n}\n\n/*==========================================\n * THE READ SIDE OF THE SEAM.\n *\n * The event feed above only ever knows about mail sent AFTER it was\n * connected. That is correct for the steady state and useless for the\n * question the staff card exists to answer, which is asked about mail that\n * has already gone out — so a delivery log fed only by events is empty\n * exactly when somebody needs it.\n *\n * A provider also holds the history, and reading it is not lock-in as long as\n * it happens through an interface. {@link EmailDeliverySnapshot} is that\n * interface: one message as the provider currently sees it, in our\n * vocabulary. `normalizeResendSentEmails` is the Resend implementation and\n * the second (and last) function in the tree that knows Resend's wire format.\n *\n * WHAT A SNAPSHOT DELIBERATELY DOES NOT CARRY\n *\n * Open and click COUNTS. Resend's list endpoint reports a single\n * `last_event` per message and no engagement detail, so a snapshot can say\n * \"this was opened at least once\" and can never say \"three times\". The\n * writer therefore treats a snapshot as a floor, never as truth that\n * overwrites what the event feed recorded — see `recordEmailDeliverySnapshot`.\n *=========================================*/\n\n/** One message as the provider currently reports it, in our vocabulary. */\nexport interface EmailDeliverySnapshot {\n  provider: string\n  providerMessageId: string\n  to: string\n  subject: string | null\n  /** Epoch ms the provider says the message was created. */\n  sentAt: number\n  /** Furthest state the provider reports. Never richer than the event feed. */\n  status: EmailDeliveryEventType\n}\n\n/**\n * A provider's `last_event` string, mapped onto our lifecycle.\n *\n * Deliberately the bare state names rather than the `email.*` event names:\n * the list endpoint reports `\"delivered\"`, the webhook reports\n * `\"email.delivered\"`, and they are two different vocabularies for one\n * concept. Both are accepted here so a provider that unifies them later\n * needs no change.\n */\nconst RESEND_LAST_EVENTS: Record<string, EmailDeliveryEventType> = {\n  sent: 'sent',\n  delivered: 'delivered',\n  delivery_delayed: 'delayed',\n  opened: 'opened',\n  clicked: 'clicked',\n  bounced: 'bounced',\n  complained: 'complained',\n  failed: 'failed',\n  canceled: 'failed',\n  queued: 'sent',\n  scheduled: 'sent',\n}\n\n/**\n * Turns one entry from Resend's `GET /emails` list into zero or more\n * snapshots — one per recipient, for the same reason the event adapter fans\n * out: the staff view is keyed on a person.\n *\n * An unrecognised `last_event` falls back to `sent` rather than being\n * dropped. The message demonstrably exists and was addressed to somebody, and\n * \"we sent this and cannot characterise what happened next\" is a far more\n * useful row than no row — which is the state that sent a staffer to the\n * vendor dashboard in the first place.\n */\nexport function normalizeResendSentEmails(\n  raw: unknown,\n): EmailDeliverySnapshot[] {\n  const record = (raw ?? {}) as Record<string, any>\n  const providerMessageId = String(record.id ?? '').trim()\n  if (!providerMessageId) return []\n\n  const recipients = (Array.isArray(record.to) ? record.to : [record.to])\n    .map((address: unknown) => String(address ?? '').trim().toLowerCase())\n    .filter((address: string) => address.includes('@'))\n  if (!recipients.length) return []\n\n  const parsed = Date.parse(String(record.created_at ?? ''))\n  const sentAt = Number.isFinite(parsed) ? parsed : 0\n  // A snapshot with no timestamp cannot be ordered, and the log's read drops\n  // any document missing its sort key — so it is refused rather than written\n  // somewhere nothing will look for it.\n  if (!sentAt) return []\n\n  const status =\n    RESEND_LAST_EVENTS[\n      String(record.last_event ?? '')\n        .trim()\n        .toLowerCase()\n    ] ?? 'sent'\n\n  return recipients.map((to: string) => ({\n    provider: 'resend',\n    providerMessageId,\n    to,\n    subject: String(record.subject ?? '').trim() || null,\n    sentAt,\n    status,\n  }))\n}\n\n/** One page of provider history, in our vocabulary. */\nexport interface EmailDeliveryHistoryPage {\n  snapshots: EmailDeliverySnapshot[]\n  /** Cursor for the next page, or null at the end. */\n  nextCursor: string | null\n}\n\n/**\n * Reads one page of already-sent mail from a provider.\n *\n * The shape a second provider would implement. Cursor-based rather than\n * offset- or date-based because that is the lowest common denominator, and\n * NOT filtered by recipient: Resend's list endpoint has no recipient\n * parameter, so filtering is the caller's job and the import is a sweep\n * rather than a per-person lookup. That is the right shape regardless — a\n * staff page must not fan out to a third party on render.\n */\nexport type EmailDeliveryHistorySource = (options: {\n  cursor?: string | null\n  limit?: number\n}) => Promise<EmailDeliveryHistoryPage>\n\n/** Resend's list endpoint. Paginates with `after=<id>`; caps at 100. */\nexport const RESEND_EMAILS_ENDPOINT = 'https://api.resend.com/emails'\n\n/**\n * {@link EmailDeliveryHistorySource} for Resend.\n *\n * Needs a FULL-ACCESS key: a sending-scoped key answers every read on this\n * endpoint with `401 restricted_api_key`, which is the correct posture for\n * the key that sends mail and the reason this takes its own.\n */\nexport function resendDeliveryHistorySource(\n  apiKey: string,\n): EmailDeliveryHistorySource {\n  return async ({ cursor, limit } = {}) => {\n    const params = new URLSearchParams({\n      limit: String(Math.min(Math.max(1, limit ?? 100), 100)),\n    })\n    if (cursor) params.set('after', cursor)\n    const response = await fetch(`${RESEND_EMAILS_ENDPOINT}?${params}`, {\n      headers: { Authorization: `Bearer ${apiKey}` },\n    })\n    if (!response.ok) {\n      const detail = await response.text().catch(() => '')\n      throw new Error(\n        `email history read failed: HTTP ${response.status} ${detail.slice(0, 200)}`,\n      )\n    }\n    const body = (await response.json()) as {\n      data?: unknown[]\n      has_more?: boolean\n    }\n    const entries = Array.isArray(body?.data) ? body.data : []\n    const snapshots = entries.flatMap((entry) => normalizeResendSentEmails(entry))\n    // The cursor is the LAST RAW entry's id, not the last snapshot's: a page\n    // whose final entry fanned out to zero snapshots (no recipient, no\n    // timestamp) would otherwise rewind the cursor to an earlier message and\n    // loop over the same page forever.\n    const lastId = String(\n      (entries[entries.length - 1] as { id?: unknown })?.id ?? '',\n    ).trim()\n    return {\n      snapshots,\n      nextCursor: body?.has_more && lastId ? lastId : null,\n    }\n  }\n}\n\n/*==========================================\n * ONE MESSAGE, RENDERED.\n *\n * The log records what HAPPENED to a message; it does not keep the message.\n * Storing every body would put an unbounded copy of every email we have ever\n * sent — including reset links and receipts — into our own database, to\n * duplicate something the provider already holds.\n *\n * So a body is fetched when a staffer explicitly opens one row. That is a\n * deliberate single lookup, not the per-render fan-out the read path refuses:\n * one message, on one click, by id.\n *=========================================*/\n\n/** One message's content and envelope, in our vocabulary. */\nexport interface EmailDeliveryMessage {\n  provider: string\n  providerMessageId: string\n  to: string[]\n  cc: string[]\n  bcc: string[]\n  from: string | null\n  replyTo: string[] | null\n  subject: string | null\n  /** The HTML part, or null when the message was sent as text only. */\n  html: string | null\n  /** The plain-text part, or null. */\n  text: string | null\n  sentAt: number | null\n  status: EmailDeliveryEventType | null\n}\n\n/** A single message by id. The shape a second provider would implement. */\nexport type EmailDeliveryMessageSource = (\n  providerMessageId: string,\n) => Promise<EmailDeliveryMessage | null>\n\nfunction addressList(raw: unknown): string[] {\n  return (Array.isArray(raw) ? raw : raw == null ? [] : [raw])\n    .map((address) => String(address ?? '').trim())\n    .filter(Boolean)\n}\n\n/** Resend's `GET /emails/:id` payload, in our vocabulary. */\nexport function normalizeResendMessage(raw: unknown): EmailDeliveryMessage | null {\n  const record = (raw ?? {}) as Record<string, any>\n  const providerMessageId = String(record.id ?? '').trim()\n  if (!providerMessageId) return null\n  const parsed = Date.parse(String(record.created_at ?? ''))\n  return {\n    provider: 'resend',\n    providerMessageId,\n    to: addressList(record.to),\n    cc: addressList(record.cc),\n    bcc: addressList(record.bcc),\n    from: String(record.from ?? '').trim() || null,\n    replyTo: addressList(record.reply_to).length\n      ? addressList(record.reply_to)\n      : null,\n    subject: String(record.subject ?? '').trim() || null,\n    // Empty string is NOT null here, and the difference is the point: a\n    // message that went out text-only really does have an empty HTML part,\n    // and a reader has to be able to tell that from \"we could not fetch it\".\n    html: typeof record.html === 'string' ? record.html : null,\n    text: typeof record.text === 'string' ? record.text : null,\n    sentAt: Number.isFinite(parsed) ? parsed : null,\n    status:\n      RESEND_LAST_EVENTS[\n        String(record.last_event ?? '')\n          .trim()\n          .toLowerCase()\n      ] ?? null,\n  }\n}\n\n/** Resend's single-message endpoint. Needs the same full-access key. */\nexport function resendDeliveryMessageSource(\n  apiKey: string,\n): EmailDeliveryMessageSource {\n  return async (providerMessageId: string) => {\n    const response = await fetch(\n      `${RESEND_EMAILS_ENDPOINT}/${encodeURIComponent(providerMessageId)}`,\n      { headers: { Authorization: `Bearer ${apiKey}` } },\n    )\n    // A message the provider has aged out is a 404, and that is an ANSWER —\n    // \"we know this was sent and the body is gone\" — not a failure to report\n    // as an error the staffer must act on.\n    if (response.status === 404) return null\n    if (!response.ok) {\n      const detail = await response.text().catch(() => '')\n      throw new Error(\n        `message read failed: HTTP ${response.status} ${detail.slice(0, 200)}`,\n      )\n    }\n    return normalizeResendMessage(await response.json())\n  }\n}\n"],"names":["readBounceText","STATUS_SEVERITY","sent","delivered","opened","clicked","delayed","complained","bounced","failed","bareSenderAddress","value","raw","String","trim","angle","match","address","toLowerCase","test","worstDeliveryStatus","current","next","normalizeEventTags","Array","isArray","map","tag","name","Object","fromEntries","entries","key","eventTimeMs","Number","isFinite","parsed","Date","parse","normalizeBounceType","lowered","RESEND_EVENT_TYPES","normalizeResendDeliveryEvents","payload","receivedAtMs","event","data","type","providerMessageId","email_id","id","recipients","to","filter","includes","length","at","click","timestamp","open","created_at","subject","tags","from","bounceText","bounce","diagnosticCode","diagnostic_code","remoteMta","remote_mta","message","part","join","provider","context","link","bounceType","detail","reason","status","bounceStatus","RESEND_LAST_EVENTS","delivery_delayed","canceled","queued","scheduled","normalizeResendSentEmails","record","sentAt","last_event","RESEND_EMAILS_ENDPOINT","resendDeliveryHistorySource","apiKey","cursor","limit","params","URLSearchParams","Math","min","max","set","response","fetch","headers","Authorization","ok","text","catch","Error","slice","body","json","snapshots","flatMap","entry","lastId","nextCursor","has_more","addressList","Boolean","normalizeResendMessage","cc","bcc","replyTo","reply_to","html","resendDeliveryMessageSource","encodeURIComponent"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/email-delivery-events.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 * WHAT HAPPENED TO A MESSAGE, IN OUR OWN VOCABULARY.\n *\n * ## The seam\n *\n * A staff answer to \"did they get the invite, and did they open it?\" must not\n * be a question about one sending vendor. Two things follow from that, and\n * this module is both of them:\n *\n * 1. **The stored shape is ours.** Nothing downstream — the delivery log, the\n *    staff card, a future export — reads a provider's field names or its event\n *    strings. A provider turns its own wire format into these types (its\n *    `deliveryEvents` and `reads`, see `mail-provider.ts`), and swapping the\n *    sender changes that provider and nothing else in the tree.\n * 2. **The history is ours.** The log is written into our own Firestore and\n *    read from there, never from the provider on render. A provider's list\n *    endpoint is a different shape per vendor, has its own retention window,\n *    and disappears entirely with the account; a record we keep survives the\n *    migration that the seam exists to make possible.\n *\n *    That is a rule about the READ PATH, not a rule against ever reading the\n *    provider. The event feed only knows mail sent after it was connected, so\n *    a log fed by events alone is empty for all existing history — which is\n *    precisely the mail a support question is about. The second half of this\n *    module (see THE READ SIDE OF THE SEAM below) is the vocabulary that\n *    history is imported through, once, into the same store.\n *\n * ## Pure on purpose\n *\n * No Firestore and no admin SDK. `system-email-catalog` is imported by console\n * CLIENT components through this library's barrel, so anything reachable from\n * it that touched `firebase-admin` would drag the admin SDK into a browser\n * bundle. Normalisation is a pure function of a payload; the writing lives in\n * `@aglyn/tenant-data-admin/server/email-delivery-log`, and the reading\n * of a provider's payloads in that provider.\n */\n\n/**\n * The lifecycle of one message, in the order it normally happens.\n *\n * Chosen to be the intersection every ESP can report rather than the union of\n * what any one of them does: a vendor with no equivalent for a state simply\n * never produces it, and a vendor with a richer taxonomy folds into the\n * nearest of these rather than widening the type. `delayed` is retryable and\n * `failed` is not, which is the distinction a staffer actually needs.\n */\nexport type EmailDeliveryEventType =\n  | 'sent'\n  | 'delivered'\n  | 'delayed'\n  | 'opened'\n  | 'clicked'\n  | 'bounced'\n  | 'complained'\n  | 'failed'\n\n/** Lifecycle states ordered worst-last, for {@link worstDeliveryStatus}. */\nconst STATUS_SEVERITY: Record<EmailDeliveryEventType, number> = {\n  sent: 1,\n  delivered: 2,\n  opened: 3,\n  clicked: 4,\n  delayed: 5,\n  complained: 6,\n  bounced: 7,\n  failed: 8,\n}\n\n/**\n * One normalized delivery event.\n *\n * `at` is epoch milliseconds rather than a Firestore timestamp so this type\n * stays usable in a browser, in a test, and in whatever writes it next.\n */\nexport interface EmailDeliveryEvent {\n  type: EmailDeliveryEventType\n  /** When the PROVIDER says it happened, falling back to receipt time. */\n  at: number\n  /** Slug of the sending provider — the `id` of the provider that carried it. */\n  provider: string\n  /** The provider's id for the message. Our per-message document key. */\n  providerMessageId: string\n  /** Recipient, lowercased. One address per record even on a multi-recipient send. */\n  to: string\n  subject: string | null\n  /**\n   * The sender label `sendEmail` stamps on every message (`'invite'`,\n   * `'password-reset'`, `'campaign'`, …). This is what makes the staff view\n   * legible: without it a row says only that *an* email was sent.\n   */\n  context: string | null\n  /** Everything else the send was tagged with, e.g. `hostId`, `campaignId`. */\n  tags: Record<string, string>\n  /** `clicked` only: the destination the recipient followed. */\n  link: string | null\n  /**\n   * `bounced` only: whether the mailbox is gone (`permanent`) or the failure\n   * was temporary. Lowercased, because providers disagree on capitalisation\n   * and a staff filter must not depend on which one is in use.\n   */\n  bounceType: 'permanent' | 'transient' | 'undetermined' | null\n  /** Provider-supplied explanation, for the states that carry one. */\n  detail: string | null\n  /**\n   * The bare sender address, lowercased: the domain it names is the sending\n   * domain a gateway's verdict is filed against (AGL-3328). Absent from\n   * events normalized before it existed, and `null` when the provider sent\n   * none.\n   */\n  from?: string | null\n  /**\n   * `bounced` only: the enhanced status code (`5.7.1`) and the receiving\n   * server the provider's bounce message names, read by `readBounceText` —\n   * what a Gmail DSN hands over as `Status` and `Remote-MTA` (AGL-3328).\n   */\n  bounceStatus?: string | null\n  remoteMta?: string | null\n}\n\n/** The bare address of a `From:` value (`\"Acme\" <hi@acme.com>` → `hi@acme.com`), lowercased. */\nexport function bareSenderAddress(value: unknown): string | null {\n  const raw = String(value ?? '').trim()\n  const angle = raw.match(/<([^>]+)>/)\n  const address = (angle ? angle[1] : raw).trim().toLowerCase()\n  return /^[^\\s@<>]+@[^\\s@<>]+\\.[^\\s@<>]+$/.test(address) ? address : null\n}\n\n/** The later of two statuses on the lifecycle, worst winning a tie. */\nexport function worstDeliveryStatus(\n  current: EmailDeliveryEventType | null | undefined,\n  next: EmailDeliveryEventType,\n): EmailDeliveryEventType {\n  if (!current) return next\n  return STATUS_SEVERITY[next] >= STATUS_SEVERITY[current] ? next : current\n}\n\n/** Tags arrive as an array of `{name, value}` or a plain map — accept both. */\nexport function normalizeEventTags(raw: unknown): Record<string, string> {\n  if (Array.isArray(raw)) {\n    const map: Record<string, string> = {}\n    for (const tag of raw) {\n      if (tag?.name) map[String(tag.name)] = String(tag.value ?? '')\n    }\n    return map\n  }\n  if (raw && typeof raw === 'object') {\n    return Object.fromEntries(\n      Object.entries(raw as Record<string, unknown>).map(([key, value]) => [\n        key,\n        String(value ?? ''),\n      ]),\n    )\n  }\n  return {}\n}\n\n/*==========================================\n * THE READ SIDE OF THE SEAM.\n *\n * The event feed above only ever knows about mail sent AFTER it was\n * connected. That is correct for the steady state and useless for the\n * question the staff card exists to answer, which is asked about mail that\n * has already gone out — so a delivery log fed only by events is empty\n * exactly when somebody needs it.\n *\n * A provider also holds the history, and reading it is not lock-in as long as\n * it happens through an interface. {@link EmailDeliverySnapshot} is that\n * interface: one message as the provider currently sees it, in our\n * vocabulary, read through the provider's `reads.history`.\n *\n * WHAT A SNAPSHOT DELIBERATELY DOES NOT CARRY\n *\n * Open and click COUNTS. A provider's list typically reports one latest\n * state per message and no engagement detail, so a snapshot can say \"this\n * was opened at least once\" and can never say \"three times\". The writer\n * therefore treats a snapshot as a floor, never as truth that overwrites\n * what the event feed recorded — see `recordEmailDeliverySnapshot`.\n *=========================================*/\n\n/** One message as the provider currently reports it, in our vocabulary. */\nexport interface EmailDeliverySnapshot {\n  provider: string\n  providerMessageId: string\n  to: string\n  subject: string | null\n  /** Epoch ms the provider says the message was created. */\n  sentAt: number\n  /** Furthest state the provider reports. Never richer than the event feed. */\n  status: EmailDeliveryEventType\n}\n\n/** One page of provider history, in our vocabulary. */\nexport interface EmailDeliveryHistoryPage {\n  snapshots: EmailDeliverySnapshot[]\n  /** Cursor for the next page, or null at the end. */\n  nextCursor: string | null\n}\n\n/**\n * Reads one page of already-sent mail from a provider.\n *\n * The shape a second provider would implement. Cursor-based rather than\n * offset- or date-based because that is the lowest common denominator, and\n * NOT filtered by recipient: a provider's list endpoint need not take one,\n * so filtering is the caller's job and the import is a sweep rather than a\n * per-person lookup. That is the right shape regardless — a staff page must\n * not fan out to a third party on render.\n */\nexport type EmailDeliveryHistorySource = (options: {\n  cursor?: string | null\n  limit?: number\n}) => Promise<EmailDeliveryHistoryPage>\n\n/*==========================================\n * ONE MESSAGE, RENDERED.\n *\n * The log records what HAPPENED to a message; it does not keep the message.\n * Storing every body would put an unbounded copy of every email we have ever\n * sent — including reset links and receipts — into our own database, to\n * duplicate something the provider already holds.\n *\n * So a body is fetched when a staffer explicitly opens one row. That is a\n * deliberate single lookup, not the per-render fan-out the read path refuses:\n * one message, on one click, by id.\n *=========================================*/\n\n/** One message's content and envelope, in our vocabulary. */\nexport interface EmailDeliveryMessage {\n  provider: string\n  providerMessageId: string\n  to: string[]\n  cc: string[]\n  bcc: string[]\n  from: string | null\n  replyTo: string[] | null\n  subject: string | null\n  /** The HTML part, or null when the message was sent as text only. */\n  html: string | null\n  /** The plain-text part, or null. */\n  text: string | null\n  sentAt: number | null\n  status: EmailDeliveryEventType | null\n}\n\n/** A single message by id. The shape a second provider would implement. */\nexport type EmailDeliveryMessageSource = (\n  providerMessageId: string,\n) => Promise<EmailDeliveryMessage | null>\n"],"names":["STATUS_SEVERITY","sent","delivered","opened","clicked","delayed","complained","bounced","failed","bareSenderAddress","value","raw","String","trim","angle","match","address","toLowerCase","test","worstDeliveryStatus","current","next","normalizeEventTags","Array","isArray","map","tag","name","Object","fromEntries","entries","key"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCC,GAED;;;;;;;;CAQC,GAWD,0EAA0E,GAC1E,MAAMA,kBAA0D;IAC9DC,MAAM;IACNC,WAAW;IACXC,QAAQ;IACRC,SAAS;IACTC,SAAS;IACTC,YAAY;IACZC,SAAS;IACTC,QAAQ;AACV;AAqDA,8FAA8F,GAC9F,OAAO,SAASC,kBAAkBC,KAAc;IAC9C,MAAMC,MAAMC,OAAOF,gBAAAA,QAAS,IAAIG,IAAI;IACpC,MAAMC,QAAQH,IAAII,KAAK,CAAC;IACxB,MAAMC,UAAU,AAACF,CAAAA,QAAQA,KAAK,CAAC,EAAE,GAAGH,GAAE,EAAGE,IAAI,GAAGI,WAAW;IAC3D,OAAO,mCAAmCC,IAAI,CAACF,WAAWA,UAAU;AACtE;AAEA,qEAAqE,GACrE,OAAO,SAASG,oBACdC,OAAkD,EAClDC,IAA4B;IAE5B,IAAI,CAACD,SAAS,OAAOC;IACrB,OAAOrB,eAAe,CAACqB,KAAK,IAAIrB,eAAe,CAACoB,QAAQ,GAAGC,OAAOD;AACpE;AAEA,6EAA6E,GAC7E,OAAO,SAASE,mBAAmBX,GAAY;IAC7C,IAAIY,MAAMC,OAAO,CAACb,MAAM;QACtB,MAAMc,MAA8B,CAAC;QACrC,KAAK,MAAMC,OAAOf,IAAK;gBACyBe;YAA9C,IAAIA,uBAAAA,IAAKC,IAAI,EAAEF,GAAG,CAACb,OAAOc,IAAIC,IAAI,EAAE,GAAGf,QAAOc,aAAAA,IAAIhB,KAAK,YAATgB,aAAa;QAC7D;QACA,OAAOD;IACT;IACA,IAAId,OAAO,OAAOA,QAAQ,UAAU;QAClC,OAAOiB,OAAOC,WAAW,CACvBD,OAAOE,OAAO,CAACnB,KAAgCc,GAAG,CAAC,CAAC,CAACM,KAAKrB,MAAM,GAAK;gBACnEqB;gBACAnB,OAAOF,gBAAAA,QAAS;aACjB;IAEL;IACA,OAAO,CAAC;AACV"}

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

@@ -14,20 +14,20 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/**
- * Where the credential probe asks its question.
- *
- * Deliberately NOT the send endpoint. A probe aimed at `/emails` is a send
- * attempt however empty its body is: it consumes an API call, and Resend
- * records it in the account's logs as a `422` on `POST /emails` with no
- * recipient, no subject and nothing identifying the caller — a line an
- * operator reading that dashboard has to treat as failed mail. A domain read
- * cannot create a message and cannot be mistaken for one.
- */
-export declare const RESEND_DOMAINS_ENDPOINT = "https://api.resend.com/domains";
+import type { MailProvider } from './mail-provider';
 export interface EmailConfigReport {
-    /** Both env vars present — mail will at least be attempted. */
+    /** The provider has its settings and a sender is set — mail will at least be attempted. */
     configured: boolean;
+    /** The id of the provider mail is handed to — see `mail-providers.ts`. */
+    provider: string;
+    /** Settings that provider still needs before it can send, as an operator names them. */
+    missingSettings: string[];
+    /**
+     * Set when the operator chose a provider this process does not have: why
+     * no mail is sent. Not the same as a missing key — see `mailProviderProblem`.
+     */
+    providerProblem: string | null;
+    /** The provider has what it needs to send. */
     hasApiKey: boolean;
     hasFrom: boolean;
     /**
@@ -35,7 +35,7 @@ export interface EmailConfigReport {
      * it appears in the headers of every message we send.
      */
     from: string | null;
-    /** Domain part of the sender, which is what must be verified in Resend. */
+    /** Domain part of the sender, which is what must be verified with the provider. */
     fromDomain: string | null;
 }
 /**
@@ -48,37 +48,24 @@ export declare function describeEmailConfig(): EmailConfigReport;
 export type EmailCredentialStatus = 'ok' | 'unconfigured' | 'invalid-key' | 'unknown';
 export interface EmailCredentialReport {
     status: EmailCredentialStatus;
-    /** HTTP status Resend answered the probe with, when it answered. */
+    /** HTTP status the provider answered the probe with, when it answered. */
     probeStatus?: number;
     detail?: string;
 }
 /**
- * Checks whether `RESEND_API_KEY` is actually accepted by Resend — without
- * sending anything to anybody, and without leaving anything behind that reads
- * as failed mail.
- *
- * How: a `GET` of the domains collection. The question is only ever "does
- * Resend recognize this credential", so the probe reads the ERROR NAME rather
- * than the status, because `401` and `403` each carry both meanings:
- *
- * - `2xx` — the key is accepted and has read scope → `ok`
- * - `restricted_api_key` / `invalid_permission` — Resend authenticated the
- *   key and then denied it this read. A sending-scoped key, which is what
- *   Aglyn provisions, always answers this way, and getting the answer proves
- *   the credential works → `ok`
- * - `missing_api_key` / `validation_error` / `suspended_api_key` — the key
- *   itself was refused → `invalid-key`
- * - anything else → `unknown`
+ * Whether the provider accepts this deployment's credential — asked without
+ * sending anything to anybody, and without leaving anything behind that
+ * reads as failed mail. How it asks is the provider's own (see its
+ * `checkCredentials`).
  *
- * An unrecognized rejection is `unknown`, never `invalid-key`: this feeds a
+ * An answer this cannot get is `unknown`, never `invalid-key`: this feeds a
  * staff diagnostics screen whose whole value is that a red line means
- * something, and a shape we have not seen before is not evidence that a
- * working key is broken.
+ * something. A provider with no probe is `unknown` for the same reason.
  *
  * It cannot confirm that *domain verification* has completed — only a real
  * send does that.
  */
-export declare function checkEmailCredentials(): Promise<EmailCredentialReport>;
+export declare function checkEmailCredentials(provider?: MailProvider): Promise<EmailCredentialReport>;
 /** One pool member, as the provider reports it. */
 export interface SharedPoolDomainReport {
     domain: string;
@@ -135,13 +122,13 @@ export interface SharedPoolReport {
  * site's transactional mail already failing — which is why the caller treats
  * this as a blocker rather than a note.
  *
- * Read with `RESEND_READ_API_KEY`, deliberately, and never with the sending
- * key. A sending-scoped key has no read permission, so asking it about domains
- * yields an authorization error that says nothing about the domains — which is
- * exactly how a pool the key could not send from reported healthy. Without a
- * read key this answers `unreadable`, which is the honest answer and not a
- * pass: the caller must not treat "I could not look" as "I looked and it was
- * fine".
+ * Read through the provider's READS, deliberately, and never with the
+ * sending credential. A sending-scoped key has no read permission, so asking
+ * it about domains yields an authorization error that says nothing about the
+ * domains — which is exactly how a pool the key could not send from reported
+ * healthy. A provider that cannot read answers `unreadable`, which is the
+ * honest answer and not a pass: the caller must not treat "I could not look"
+ * as "I looked and it was fine".
  *
  * `not-applicable` covers the self-host shape. The pool is a property of the
  * Aglyn platform; an operator running their own deployment sends from their
@@ -149,6 +136,6 @@ export interface SharedPoolReport {
  */
 export declare function checkSharedSendingPool(options: {
     pool: string[];
-    readApiKey?: string;
-    endpoint?: string;
+    /** The provider to ask; the deployment's own by default. */
+    provider?: MailProvider;
 }): Promise<SharedPoolReport>;