@aglyn/shared-util-email 1.0.0-beta.143

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

@@ -0,0 +1,310 @@
+/**
+ * @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.
+ */ /**
+ * WHAT HAPPENED TO A MESSAGE, IN OUR OWN VOCABULARY.
+ *
+ * ## 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:
+ *
+ * 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.
+ * 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,
+ *    and disappears entirely with the account; a record we keep survives the
+ *    migration that the seam exists to make possible.
+ *
+ *    That is a rule about the READ PATH, not a rule against ever reading the
+ *    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.
+ *
+ * ## Pure on purpose
+ *
+ * No Firestore and no admin SDK. `system-email-catalog` is imported by console
+ * 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.
+ */ /**
+ * 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,
+    clicked: 4,
+    delayed: 5,
+    complained: 6,
+    bounced: 7,
+    failed: 8
+};
+/** The later of two statuses on the lifecycle, worst winning a tie. */ export function worstDeliveryStatus(current, next) {
+    if (!current) return next;
+    return STATUS_SEVERITY[next] >= STATUS_SEVERITY[current] ? next : current;
+}
+/** Tags arrive as an array of `{name, value}` or a plain map — accept both. */ export function normalizeEventTags(raw) {
+    if (Array.isArray(raw)) {
+        const map = {};
+        for (const tag of raw){
+            var _tag_value;
+            if (tag == null ? void 0 : tag.name) map[String(tag.name)] = String((_tag_value = tag.value) != null ? _tag_value : '');
+        }
+        return map;
+    }
+    if (raw && typeof raw === 'object') {
+        return Object.fromEntries(Object.entries(raw).map(([key, value])=>[
+                key,
+                String(value != null ? value : '')
+            ]));
+    }
+    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;
+    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);
+    return recipients.map((to)=>{
+        var _ref, _ref1, _ref2;
+        var _data_click, _data_bounce, _data_bounce1, _data_failed;
+        return {
+            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
+        };
+    });
+}
+/**
+ * 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

@@ -0,0 +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\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\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\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  }))\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":["STATUS_SEVERITY","sent","delivered","opened","clicked","delayed","complained","bounced","failed","worstDeliveryStatus","current","next","normalizeEventTags","raw","Array","isArray","map","tag","name","String","value","Object","fromEntries","entries","key","eventTimeMs","Number","isFinite","parsed","Date","parse","normalizeBounceType","lowered","trim","toLowerCase","RESEND_EVENT_TYPES","normalizeResendDeliveryEvents","payload","receivedAtMs","event","data","type","providerMessageId","email_id","id","recipients","to","address","filter","includes","length","at","click","timestamp","open","created_at","subject","tags","provider","context","link","bounceType","bounce","detail","message","reason","RESEND_LAST_EVENTS","delivery_delayed","canceled","queued","scheduled","normalizeResendSentEmails","record","sentAt","status","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","from","replyTo","reply_to","html","resendDeliveryMessageSource","encodeURIComponent"],"mappings":"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"}

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

@@ -0,0 +1,154 @@
+/**
+ * @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.
+ */
+/**
+ * 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";
+export interface EmailConfigReport {
+    /** Both env vars present — mail will at least be attempted. */
+    configured: boolean;
+    hasApiKey: boolean;
+    hasFrom: boolean;
+    /**
+     * The configured sender, e.g. `Aglyn <noreply@aglyn.com>`. Not a secret —
+     * 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. */
+    fromDomain: string | null;
+}
+/**
+ * Describes the email configuration without revealing the API key.
+ *
+ * Answers "is this environment able to send mail?" — the question that is
+ * otherwise only answerable by emailing a real person and waiting.
+ */
+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. */
+    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`
+ *
+ * An unrecognized rejection 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.
+ *
+ * It cannot confirm that *domain verification* has completed — only a real
+ * send does that.
+ */
+export declare function checkEmailCredentials(): Promise<EmailCredentialReport>;
+/** One pool member, as the provider reports it. */
+export interface SharedPoolDomainReport {
+    domain: string;
+    /** `verified` when the provider will accept mail on it. */
+    status: string;
+    /** False when the provider has never heard of it. */
+    present: boolean;
+    /**
+     * Whether the provider will rewrite links on this domain to measure clicks.
+     *
+     * Reported because the symptom of it being off is INVISIBLE. A provider
+     * counts a click by rewriting every `<a href>` to a tracking host, so a
+     * domain without one produces a click rate of exactly 0% — which reads on a
+     * dashboard as an audience that does not click, not as a domain that cannot
+     * count. The last time this was wrong nobody found it by looking at the
+     * numbers; it was found by reading a delivered message's source.
+     *
+     * `null` when the provider's listing does not say, so "it did not tell us"
+     * is never reported as "it is off".
+     */
+    clickTracking: boolean | null;
+    /** The same, for the open pixel. */
+    openTracking: boolean | null;
+}
+export type SharedPoolStatus = 
+/** No platform pool applies to this deployment. */
+'not-applicable'
+/** No read credential, so the pool cannot be inspected. */
+ | 'unreadable' | 'ok' | 'degraded';
+export interface SharedPoolReport {
+    status: SharedPoolStatus;
+    domains: SharedPoolDomainReport[];
+    /** Members the provider will not accept mail on right now. */
+    unusable: string[];
+    /**
+     * Members that will carry mail but cannot measure a click on it.
+     *
+     * Reported APART from {@link unusable} because the two are different
+     * severities and conflating them would be wrong in both directions: a
+     * member here is delivering perfectly, and a member in `unusable` is not
+     * delivering at all. This one does not degrade the pool — see
+     * {@link SharedPoolReport.status} — it is a measurement fault, and stopping
+     * mail over it would be the control causing the outage.
+     */
+    untracked: string[];
+    detail?: string;
+}
+/**
+ * Whether the shared platform pool can actually carry mail.
+ *
+ * The pool is the delivery floor: a site with no domain of its own sends its
+ * receipts, password resets and booking confirmations from a member of it. So
+ * a degraded pool is not a warning about a future problem, it is every such
+ * 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".
+ *
+ * `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
+ * own domain and has no pool to be degraded.
+ */
+export declare function checkSharedSendingPool(options: {
+    pool: string[];
+    readApiKey?: string;
+    endpoint?: string;
+}): Promise<SharedPoolReport>;