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

package/src/lib/email-health.js

@@ -15,42 +15,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ import { getEmailConfig } from "./send-email.js";
-/**
- * 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 const RESEND_DOMAINS_ENDPOINT = 'https://api.resend.com/domains';
-/**
- * Resend error names that mean the key itself was not accepted, as opposed to
- * a key that authenticated and merely lacks read scope. Matched by NAME, not
- * status: `401` and `403` each cover both meanings.
- */ const REFUSED_KEY_ERRORS = new Set([
-    'missing_api_key',
-    'validation_error',
-    'suspended_api_key'
-]);
-/**
- * Resend error names that mean the key authenticated and was then denied this
- * particular read. A sending-scoped key — the shape Aglyn provisions — always
- * lands here, and reaching this answer at all required Resend to recognize
- * the credential, which is exactly what the probe is asking.
- */ const AUTHENTICATED_BUT_UNSCOPED_ERRORS = new Set([
-    'restricted_api_key',
-    'invalid_permission'
-]);
-/** The `name` Resend puts on an error body, or `''` for anything else. */ function resendErrorName(body) {
-    try {
-        const parsed = JSON.parse(body);
-        return typeof (parsed == null ? void 0 : parsed.name) === 'string' ? parsed.name : '';
-    } catch (unused) {
-        return '';
-    }
-}
+import { mailProvider, mailProviderProblem, mailProviderReads } from "./mail-providers.js";
 /**
  * Describes the email configuration without revealing the API key.
  *
@@ -58,83 +23,50 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * otherwise only answerable by emailing a real person and waiting.
  */ export function describeEmailConfig() {
     var _ref, _ref1;
-    const { apiKey, from } = getEmailConfig();
+    const { provider, missingSettings, from } = getEmailConfig();
     const match = from == null ? void 0 : from.match(/<([^>]+)>/);
     const address = ((_ref = (_ref1 = match == null ? void 0 : match[1]) != null ? _ref1 : from) != null ? _ref : '').trim();
     const domain = address.includes('@') ? address.split('@').pop() : null;
     return {
-        configured: Boolean(apiKey && from),
-        hasApiKey: Boolean(apiKey),
+        configured: !missingSettings.length && Boolean(from),
+        provider,
+        missingSettings,
+        providerProblem: mailProviderProblem(),
+        hasApiKey: !missingSettings.length,
         hasFrom: Boolean(from),
         from: from != null ? from : null,
         fromDomain: domain
     };
 }
 /**
- * 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 async function checkEmailCredentials() {
-    const { apiKey } = getEmailConfig();
-    if (!apiKey) return {
+ */ export async function checkEmailCredentials(provider = mailProvider()) {
+    const problem = mailProviderProblem(provider);
+    if (problem) return {
+        status: 'unconfigured',
+        detail: problem
+    };
+    if (provider.missingSettings().length) return {
         status: 'unconfigured'
     };
-    try {
-        const response = await fetch(RESEND_DOMAINS_ENDPOINT, {
-            method: 'GET',
-            headers: {
-                Authorization: `Bearer ${apiKey}`
-            }
-        });
-        const detail = (await response.text().catch(()=>'')).slice(0, 300);
-        if (response.status >= 200 && response.status < 300) {
-            return {
-                status: 'ok',
-                probeStatus: response.status
-            };
-        }
-        if (response.status === 401 || response.status === 403) {
-            const name = resendErrorName(detail);
-            if (AUTHENTICATED_BUT_UNSCOPED_ERRORS.has(name)) {
-                return {
-                    status: 'ok',
-                    probeStatus: response.status
-                };
-            }
-            if (REFUSED_KEY_ERRORS.has(name)) {
-                return {
-                    status: 'invalid-key',
-                    probeStatus: response.status,
-                    detail
-                };
-            }
-        }
+    if (!provider.checkCredentials) {
         return {
             status: 'unknown',
-            probeStatus: response.status,
-            detail
+            detail: `The "${provider.id}" mail provider has no credential probe; a test ` + 'send is the way to know it delivers.'
         };
+    }
+    try {
+        return await provider.checkCredentials();
     } catch (error) {
         var _ref;
         return {
@@ -152,19 +84,19 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * 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
  * own domain and has no pool to be degraded.
  */ export async function checkSharedSendingPool(options) {
-    var _options_readApiKey;
+    var _options_provider;
     const pool = options.pool.filter(Boolean);
     if (!pool.length) {
         return {
@@ -174,50 +106,22 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
             untracked: []
         };
     }
-    const key = String((_options_readApiKey = options.readApiKey) != null ? _options_readApiKey : '').trim();
-    if (!key) {
+    const reads = mailProviderReads((_options_provider = options.provider) != null ? _options_provider : mailProvider());
+    const unmet = reads.unmet();
+    if (unmet) {
         return {
             status: 'unreadable',
             domains: [],
             unusable: [],
             untracked: [],
-            detail: 'RESEND_READ_API_KEY is not set, so the shared pool cannot be ' + 'inspected. The sending key has no read permission and would report ' + 'an authorization error rather than the state of the domains.'
+            detail: `${unmet} The shared pool cannot be inspected without it.`
         };
     }
     try {
-        var _options_endpoint, _ref;
-        const response = await fetch((_options_endpoint = options.endpoint) != null ? _options_endpoint : RESEND_DOMAINS_ENDPOINT, {
-            method: 'GET',
-            headers: {
-                Authorization: `Bearer ${key}`
-            }
-        });
-        if (response.status < 200 || response.status >= 300) {
-            return {
-                status: 'unreadable',
-                domains: [],
-                unusable: [],
-                untracked: [],
-                detail: `The provider answered ${response.status} to the domain read.`
-            };
-        }
-        const payload = await response.json().catch(()=>null);
-        /**
-     * A tri-state, and the third state matters: a listing that does not carry
-     * the field must not be reported as the field being false. Off is a fault
-     * somebody should fix; unknown is a question this probe could not ask.
-     */ const flag = (value)=>typeof value === 'boolean' ? value : null;
-        const byName = new Map();
-        for (const row of (_ref = payload == null ? void 0 : payload.data) != null ? _ref : []){
-            var _ref1, _ref2;
-            const name = String((_ref1 = row == null ? void 0 : row.name) != null ? _ref1 : '').toLowerCase();
-            if (!name) continue;
-            byName.set(name, {
-                status: String((_ref2 = row == null ? void 0 : row.status) != null ? _ref2 : 'unknown'),
-                click: flag(row == null ? void 0 : row.click_tracking),
-                open: flag(row == null ? void 0 : row.open_tracking)
-            });
-        }
+        const byName = new Map((await reads.sendingDomains()).map((row)=>[
+                row.name.toLowerCase(),
+                row
+            ]));
         const domains = pool.map((domain)=>{
             var _ref, _ref1, _ref2;
             const row = byName.get(domain.toLowerCase());
@@ -225,8 +129,8 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
                 domain,
                 status: (_ref = row == null ? void 0 : row.status) != null ? _ref : 'absent',
                 present: row !== undefined,
-                clickTracking: (_ref1 = row == null ? void 0 : row.click) != null ? _ref1 : null,
-                openTracking: (_ref2 = row == null ? void 0 : row.open) != null ? _ref2 : null
+                clickTracking: (_ref1 = row == null ? void 0 : row.clickTracking) != null ? _ref1 : null,
+                openTracking: (_ref2 = row == null ? void 0 : row.openTracking) != null ? _ref2 : null
             };
         });
         const unusable = domains.filter((entry)=>entry.status !== 'verified').map((entry)=>entry.domain);
@@ -250,13 +154,13 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
             detail: `Click tracking is off for ${untracked.join(', ')}. Mail from ` + 'these domains delivers normally and reports a click rate of ' + 'exactly 0%, because the provider rewrites links only on a ' + 'domain that has a verified tracking subdomain.'
         } : {});
     } catch (error) {
-        var _ref3;
+        var _ref;
         return {
             status: 'unreadable',
             domains: [],
             unusable: [],
             untracked: [],
-            detail: String((_ref3 = error == null ? void 0 : error.message) != null ? _ref3 : error).slice(0, 300)
+            detail: String((_ref = error == null ? void 0 : error.message) != null ? _ref : error).slice(0, 300)
         };
     }
 }

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/email-health.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\nimport { getEmailConfig } from './send-email'\n\n/**\n * Where the credential probe asks its question.\n *\n * Deliberately NOT the send endpoint. A probe aimed at `/emails` is a send\n * attempt however empty its body is: it consumes an API call, and Resend\n * records it in the account's logs as a `422` on `POST /emails` with no\n * recipient, no subject and nothing identifying the caller — a line an\n * operator reading that dashboard has to treat as failed mail. A domain read\n * cannot create a message and cannot be mistaken for one.\n */\nexport const RESEND_DOMAINS_ENDPOINT = 'https://api.resend.com/domains'\n\n/**\n * Resend error names that mean the key itself was not accepted, as opposed to\n * a key that authenticated and merely lacks read scope. Matched by NAME, not\n * status: `401` and `403` each cover both meanings.\n */\nconst REFUSED_KEY_ERRORS = new Set([\n  'missing_api_key',\n  'validation_error',\n  'suspended_api_key',\n])\n\n/**\n * Resend error names that mean the key authenticated and was then denied this\n * particular read. A sending-scoped key — the shape Aglyn provisions — always\n * lands here, and reaching this answer at all required Resend to recognize\n * the credential, which is exactly what the probe is asking.\n */\nconst AUTHENTICATED_BUT_UNSCOPED_ERRORS = new Set([\n  'restricted_api_key',\n  'invalid_permission',\n])\n\n/** The `name` Resend puts on an error body, or `''` for anything else. */\nfunction resendErrorName(body: string): string {\n  try {\n    const parsed = JSON.parse(body) as { name?: unknown }\n    return typeof parsed?.name === 'string' ? parsed.name : ''\n  } catch {\n    return ''\n  }\n}\n\nexport interface EmailConfigReport {\n  /** Both env vars present — mail will at least be attempted. */\n  configured: boolean\n  hasApiKey: boolean\n  hasFrom: boolean\n  /**\n   * The configured sender, e.g. `Aglyn <noreply@aglyn.com>`. Not a secret —\n   * it appears in the headers of every message we send.\n   */\n  from: string | null\n  /** Domain part of the sender, which is what must be verified in Resend. */\n  fromDomain: string | null\n}\n\n/**\n * Describes the email configuration without revealing the API key.\n *\n * Answers \"is this environment able to send mail?\" — the question that is\n * otherwise only answerable by emailing a real person and waiting.\n */\nexport function describeEmailConfig(): EmailConfigReport {\n  const { apiKey, from } = getEmailConfig()\n  const match = from?.match(/<([^>]+)>/)\n  const address = (match?.[1] ?? from ?? '').trim()\n  const domain = address.includes('@') ? address.split('@').pop()! : null\n  return {\n    configured: Boolean(apiKey && from),\n    hasApiKey: Boolean(apiKey),\n    hasFrom: Boolean(from),\n    from: from ?? null,\n    fromDomain: domain,\n  }\n}\n\nexport type EmailCredentialStatus =\n  | 'ok'\n  | 'unconfigured'\n  | 'invalid-key'\n  | 'unknown'\n\nexport interface EmailCredentialReport {\n  status: EmailCredentialStatus\n  /** HTTP status Resend answered the probe with, when it answered. */\n  probeStatus?: number\n  detail?: string\n}\n\n/**\n * Checks whether `RESEND_API_KEY` is actually accepted by Resend — without\n * sending anything to anybody, and without leaving anything behind that reads\n * as failed mail.\n *\n * How: a `GET` of the domains collection. The question is only ever \"does\n * Resend recognize this credential\", so the probe reads the ERROR NAME rather\n * than the status, because `401` and `403` each carry both meanings:\n *\n * - `2xx` — the key is accepted and has read scope → `ok`\n * - `restricted_api_key` / `invalid_permission` — Resend authenticated the\n *   key and then denied it this read. A sending-scoped key, which is what\n *   Aglyn provisions, always answers this way, and getting the answer proves\n *   the credential works → `ok`\n * - `missing_api_key` / `validation_error` / `suspended_api_key` — the key\n *   itself was refused → `invalid-key`\n * - anything else → `unknown`\n *\n * An unrecognized rejection is `unknown`, never `invalid-key`: this feeds a\n * staff diagnostics screen whose whole value is that a red line means\n * something, and a shape we have not seen before is not evidence that a\n * working key is broken.\n *\n * It cannot confirm that *domain verification* has completed — only a real\n * send does that.\n */\nexport async function checkEmailCredentials(): Promise<EmailCredentialReport> {\n  const { apiKey } = getEmailConfig()\n  if (!apiKey) return { status: 'unconfigured' }\n\n  try {\n    const response = await fetch(RESEND_DOMAINS_ENDPOINT, {\n      method: 'GET',\n      headers: { Authorization: `Bearer ${apiKey}` },\n    })\n    const detail = (await response.text().catch(() => '')).slice(0, 300)\n\n    if (response.status >= 200 && response.status < 300) {\n      return { status: 'ok', probeStatus: response.status }\n    }\n    if (response.status === 401 || response.status === 403) {\n      const name = resendErrorName(detail)\n      if (AUTHENTICATED_BUT_UNSCOPED_ERRORS.has(name)) {\n        return { status: 'ok', probeStatus: response.status }\n      }\n      if (REFUSED_KEY_ERRORS.has(name)) {\n        return { status: 'invalid-key', probeStatus: response.status, detail }\n      }\n    }\n    return { status: 'unknown', probeStatus: response.status, detail }\n  } catch (error) {\n    return {\n      status: 'unknown',\n      detail: String((error as Error)?.message ?? error).slice(0, 300),\n    }\n  }\n}\n\n/** One pool member, as the provider reports it. */\nexport interface SharedPoolDomainReport {\n  domain: string\n  /** `verified` when the provider will accept mail on it. */\n  status: string\n  /** False when the provider has never heard of it. */\n  present: boolean\n  /**\n   * Whether the provider will rewrite links on this domain to measure clicks.\n   *\n   * Reported because the symptom of it being off is INVISIBLE. A provider\n   * counts a click by rewriting every `<a href>` to a tracking host, so a\n   * domain without one produces a click rate of exactly 0% — which reads on a\n   * dashboard as an audience that does not click, not as a domain that cannot\n   * count. The last time this was wrong nobody found it by looking at the\n   * numbers; it was found by reading a delivered message's source.\n   *\n   * `null` when the provider's listing does not say, so \"it did not tell us\"\n   * is never reported as \"it is off\".\n   */\n  clickTracking: boolean | null\n  /** The same, for the open pixel. */\n  openTracking: boolean | null\n}\n\nexport type SharedPoolStatus =\n  /** No platform pool applies to this deployment. */\n  | 'not-applicable'\n  /** No read credential, so the pool cannot be inspected. */\n  | 'unreadable'\n  | 'ok'\n  | 'degraded'\n\nexport interface SharedPoolReport {\n  status: SharedPoolStatus\n  domains: SharedPoolDomainReport[]\n  /** Members the provider will not accept mail on right now. */\n  unusable: string[]\n  /**\n   * Members that will carry mail but cannot measure a click on it.\n   *\n   * Reported APART from {@link unusable} because the two are different\n   * severities and conflating them would be wrong in both directions: a\n   * member here is delivering perfectly, and a member in `unusable` is not\n   * delivering at all. This one does not degrade the pool — see\n   * {@link SharedPoolReport.status} — it is a measurement fault, and stopping\n   * mail over it would be the control causing the outage.\n   */\n  untracked: string[]\n  detail?: string\n}\n\n/**\n * Whether the shared platform pool can actually carry mail.\n *\n * The pool is the delivery floor: a site with no domain of its own sends its\n * receipts, password resets and booking confirmations from a member of it. So\n * a degraded pool is not a warning about a future problem, it is every such\n * site's transactional mail already failing — which is why the caller treats\n * this as a blocker rather than a note.\n *\n * Read with `RESEND_READ_API_KEY`, deliberately, and never with the sending\n * key. A sending-scoped key has no read permission, so asking it about domains\n * yields an authorization error that says nothing about the domains — which is\n * exactly how a pool the key could not send from reported healthy. Without a\n * read key this answers `unreadable`, which is the honest answer and not a\n * pass: the caller must not treat \"I could not look\" as \"I looked and it was\n * fine\".\n *\n * `not-applicable` covers the self-host shape. The pool is a property of the\n * Aglyn platform; an operator running their own deployment sends from their\n * own domain and has no pool to be degraded.\n */\nexport async function checkSharedSendingPool(options: {\n  pool: string[]\n  readApiKey?: string\n  endpoint?: string\n}): Promise<SharedPoolReport> {\n  const pool = options.pool.filter(Boolean)\n  if (!pool.length) {\n    return {\n      status: 'not-applicable',\n      domains: [],\n      unusable: [],\n      untracked: [],\n    }\n  }\n\n  const key = String(options.readApiKey ?? '').trim()\n  if (!key) {\n    return {\n      status: 'unreadable',\n      domains: [],\n      unusable: [],\n      untracked: [],\n      detail:\n        'RESEND_READ_API_KEY is not set, so the shared pool cannot be ' +\n        'inspected. The sending key has no read permission and would report ' +\n        'an authorization error rather than the state of the domains.',\n    }\n  }\n\n  try {\n    const response = await fetch(options.endpoint ?? RESEND_DOMAINS_ENDPOINT, {\n      method: 'GET',\n      headers: { Authorization: `Bearer ${key}` },\n    })\n    if (response.status < 200 || response.status >= 300) {\n      return {\n        status: 'unreadable',\n        domains: [],\n        unusable: [],\n        untracked: [],\n        detail: `The provider answered ${response.status} to the domain read.`,\n      }\n    }\n    const payload = (await response.json().catch(() => null)) as\n      | {\n          data?: Array<{\n            name?: unknown\n            status?: unknown\n            click_tracking?: unknown\n            open_tracking?: unknown\n          }>\n        }\n      | null\n    /**\n     * A tri-state, and the third state matters: a listing that does not carry\n     * the field must not be reported as the field being false. Off is a fault\n     * somebody should fix; unknown is a question this probe could not ask.\n     */\n    const flag = (value: unknown): boolean | null =>\n      typeof value === 'boolean' ? value : null\n    const byName = new Map<\n      string,\n      { status: string; click: boolean | null; open: boolean | null }\n    >()\n    for (const row of payload?.data ?? []) {\n      const name = String(row?.name ?? '').toLowerCase()\n      if (!name) continue\n      byName.set(name, {\n        status: String(row?.status ?? 'unknown'),\n        click: flag(row?.click_tracking),\n        open: flag(row?.open_tracking),\n      })\n    }\n    const domains = pool.map((domain) => {\n      const row = byName.get(domain.toLowerCase())\n      return {\n        domain,\n        status: row?.status ?? 'absent',\n        present: row !== undefined,\n        clickTracking: row?.click ?? null,\n        openTracking: row?.open ?? null,\n      }\n    })\n    const unusable = domains\n      .filter((entry) => entry.status !== 'verified')\n      .map((entry) => entry.domain)\n    /*\n     * Only a definite `false` counts. A member the provider did not describe\n     * is already reported by `present`, and listing it here as well would\n     * send an operator to fix a setting they cannot see.\n     */\n    const untracked = domains\n      .filter((entry) => entry.clickTracking === false)\n      .map((entry) => entry.domain)\n    return {\n      /*\n       * `untracked` deliberately does NOT degrade the pool. `degraded` is\n       * read as \"transactional mail is failing right now\" and is treated as a\n       * blocker; a domain that delivers but does not count clicks is neither.\n       * Folding the two together would either raise a false alarm about\n       * delivery or teach an operator to ignore the real one.\n       */\n      status: unusable.length ? 'degraded' : 'ok',\n      domains,\n      unusable,\n      untracked,\n      ...(untracked.length\n        ? {\n            detail:\n              `Click tracking is off for ${untracked.join(', ')}. Mail from ` +\n              'these domains delivers normally and reports a click rate of ' +\n              'exactly 0%, because the provider rewrites links only on a ' +\n              'domain that has a verified tracking subdomain.',\n          }\n        : {}),\n    }\n  } catch (error) {\n    return {\n      status: 'unreadable',\n      domains: [],\n      unusable: [],\n      untracked: [],\n      detail: String((error as Error)?.message ?? error).slice(0, 300),\n    }\n  }\n}\n"],"names":["getEmailConfig","RESEND_DOMAINS_ENDPOINT","REFUSED_KEY_ERRORS","Set","AUTHENTICATED_BUT_UNSCOPED_ERRORS","resendErrorName","body","parsed","JSON","parse","name","describeEmailConfig","match","apiKey","from","address","trim","domain","includes","split","pop","configured","Boolean","hasApiKey","hasFrom","fromDomain","checkEmailCredentials","status","response","fetch","method","headers","Authorization","detail","text","catch","slice","probeStatus","has","error","String","message","checkSharedSendingPool","options","pool","filter","length","domains","unusable","untracked","key","readApiKey","endpoint","payload","json","flag","value","byName","Map","row","data","toLowerCase","set","click","click_tracking","open","open_tracking","map","get","present","undefined","clickTracking","openTracking","entry","join"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/email-health.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\nimport { getEmailConfig } from './send-email'\nimport type { MailProvider } from './mail-provider'\nimport {\n  mailProvider,\n  mailProviderProblem,\n  mailProviderReads,\n} from './mail-providers'\n\nexport interface EmailConfigReport {\n  /** The provider has its settings and a sender is set — mail will at least be attempted. */\n  configured: boolean\n  /** The id of the provider mail is handed to — see `mail-providers.ts`. */\n  provider: string\n  /** Settings that provider still needs before it can send, as an operator names them. */\n  missingSettings: string[]\n  /**\n   * Set when the operator chose a provider this process does not have: why\n   * no mail is sent. Not the same as a missing key — see `mailProviderProblem`.\n   */\n  providerProblem: string | null\n  /** The provider has what it needs to send. */\n  hasApiKey: boolean\n  hasFrom: boolean\n  /**\n   * The configured sender, e.g. `Aglyn <noreply@aglyn.com>`. Not a secret —\n   * it appears in the headers of every message we send.\n   */\n  from: string | null\n  /** Domain part of the sender, which is what must be verified with the provider. */\n  fromDomain: string | null\n}\n\n/**\n * Describes the email configuration without revealing the API key.\n *\n * Answers \"is this environment able to send mail?\" — the question that is\n * otherwise only answerable by emailing a real person and waiting.\n */\nexport function describeEmailConfig(): EmailConfigReport {\n  const { provider, missingSettings, from } = getEmailConfig()\n  const match = from?.match(/<([^>]+)>/)\n  const address = (match?.[1] ?? from ?? '').trim()\n  const domain = address.includes('@') ? address.split('@').pop()! : null\n  return {\n    configured: !missingSettings.length && Boolean(from),\n    provider,\n    missingSettings,\n    providerProblem: mailProviderProblem(),\n    hasApiKey: !missingSettings.length,\n    hasFrom: Boolean(from),\n    from: from ?? null,\n    fromDomain: domain,\n  }\n}\n\nexport type EmailCredentialStatus =\n  | 'ok'\n  | 'unconfigured'\n  | 'invalid-key'\n  | 'unknown'\n\nexport interface EmailCredentialReport {\n  status: EmailCredentialStatus\n  /** HTTP status the provider answered the probe with, when it answered. */\n  probeStatus?: number\n  detail?: string\n}\n\n/**\n * Whether the provider accepts this deployment's credential — asked without\n * sending anything to anybody, and without leaving anything behind that\n * reads as failed mail. How it asks is the provider's own (see its\n * `checkCredentials`).\n *\n * An answer this cannot get is `unknown`, never `invalid-key`: this feeds a\n * staff diagnostics screen whose whole value is that a red line means\n * something. A provider with no probe is `unknown` for the same reason.\n *\n * It cannot confirm that *domain verification* has completed — only a real\n * send does that.\n */\nexport async function checkEmailCredentials(\n  provider: MailProvider = mailProvider(),\n): Promise<EmailCredentialReport> {\n  const problem = mailProviderProblem(provider)\n  if (problem) return { status: 'unconfigured', detail: problem }\n  if (provider.missingSettings().length) return { status: 'unconfigured' }\n  if (!provider.checkCredentials) {\n    return {\n      status: 'unknown',\n      detail:\n        `The \"${provider.id}\" mail provider has no credential probe; a test ` +\n        'send is the way to know it delivers.',\n    }\n  }\n  try {\n    return await provider.checkCredentials()\n  } catch (error) {\n    return {\n      status: 'unknown',\n      detail: String((error as Error)?.message ?? error).slice(0, 300),\n    }\n  }\n}\n\n/** One pool member, as the provider reports it. */\nexport interface SharedPoolDomainReport {\n  domain: string\n  /** `verified` when the provider will accept mail on it. */\n  status: string\n  /** False when the provider has never heard of it. */\n  present: boolean\n  /**\n   * Whether the provider will rewrite links on this domain to measure clicks.\n   *\n   * Reported because the symptom of it being off is INVISIBLE. A provider\n   * counts a click by rewriting every `<a href>` to a tracking host, so a\n   * domain without one produces a click rate of exactly 0% — which reads on a\n   * dashboard as an audience that does not click, not as a domain that cannot\n   * count. The last time this was wrong nobody found it by looking at the\n   * numbers; it was found by reading a delivered message's source.\n   *\n   * `null` when the provider's listing does not say, so \"it did not tell us\"\n   * is never reported as \"it is off\".\n   */\n  clickTracking: boolean | null\n  /** The same, for the open pixel. */\n  openTracking: boolean | null\n}\n\nexport type SharedPoolStatus =\n  /** No platform pool applies to this deployment. */\n  | 'not-applicable'\n  /** No read credential, so the pool cannot be inspected. */\n  | 'unreadable'\n  | 'ok'\n  | 'degraded'\n\nexport interface SharedPoolReport {\n  status: SharedPoolStatus\n  domains: SharedPoolDomainReport[]\n  /** Members the provider will not accept mail on right now. */\n  unusable: string[]\n  /**\n   * Members that will carry mail but cannot measure a click on it.\n   *\n   * Reported APART from {@link unusable} because the two are different\n   * severities and conflating them would be wrong in both directions: a\n   * member here is delivering perfectly, and a member in `unusable` is not\n   * delivering at all. This one does not degrade the pool — see\n   * {@link SharedPoolReport.status} — it is a measurement fault, and stopping\n   * mail over it would be the control causing the outage.\n   */\n  untracked: string[]\n  detail?: string\n}\n\n/**\n * Whether the shared platform pool can actually carry mail.\n *\n * The pool is the delivery floor: a site with no domain of its own sends its\n * receipts, password resets and booking confirmations from a member of it. So\n * a degraded pool is not a warning about a future problem, it is every such\n * site's transactional mail already failing — which is why the caller treats\n * this as a blocker rather than a note.\n *\n * Read through the provider's READS, deliberately, and never with the\n * sending credential. A sending-scoped key has no read permission, so asking\n * it about domains yields an authorization error that says nothing about the\n * domains — which is exactly how a pool the key could not send from reported\n * healthy. A provider that cannot read answers `unreadable`, which is the\n * honest answer and not a pass: the caller must not treat \"I could not look\"\n * as \"I looked and it was fine\".\n *\n * `not-applicable` covers the self-host shape. The pool is a property of the\n * Aglyn platform; an operator running their own deployment sends from their\n * own domain and has no pool to be degraded.\n */\nexport async function checkSharedSendingPool(options: {\n  pool: string[]\n  /** The provider to ask; the deployment's own by default. */\n  provider?: MailProvider\n}): Promise<SharedPoolReport> {\n  const pool = options.pool.filter(Boolean)\n  if (!pool.length) {\n    return {\n      status: 'not-applicable',\n      domains: [],\n      unusable: [],\n      untracked: [],\n    }\n  }\n\n  const reads = mailProviderReads(options.provider ?? mailProvider())\n  const unmet = reads.unmet()\n  if (unmet) {\n    return {\n      status: 'unreadable',\n      domains: [],\n      unusable: [],\n      untracked: [],\n      detail: `${unmet} The shared pool cannot be inspected without it.`,\n    }\n  }\n\n  try {\n    const byName = new Map(\n      (await reads.sendingDomains()).map((row) => [row.name.toLowerCase(), row]),\n    )\n    const domains = pool.map((domain) => {\n      const row = byName.get(domain.toLowerCase())\n      return {\n        domain,\n        status: row?.status ?? 'absent',\n        present: row !== undefined,\n        clickTracking: row?.clickTracking ?? null,\n        openTracking: row?.openTracking ?? null,\n      }\n    })\n    const unusable = domains\n      .filter((entry) => entry.status !== 'verified')\n      .map((entry) => entry.domain)\n    /*\n     * Only a definite `false` counts. A member the provider did not describe\n     * is already reported by `present`, and listing it here as well would\n     * send an operator to fix a setting they cannot see.\n     */\n    const untracked = domains\n      .filter((entry) => entry.clickTracking === false)\n      .map((entry) => entry.domain)\n    return {\n      /*\n       * `untracked` deliberately does NOT degrade the pool. `degraded` is\n       * read as \"transactional mail is failing right now\" and is treated as a\n       * blocker; a domain that delivers but does not count clicks is neither.\n       * Folding the two together would either raise a false alarm about\n       * delivery or teach an operator to ignore the real one.\n       */\n      status: unusable.length ? 'degraded' : 'ok',\n      domains,\n      unusable,\n      untracked,\n      ...(untracked.length\n        ? {\n            detail:\n              `Click tracking is off for ${untracked.join(', ')}. Mail from ` +\n              'these domains delivers normally and reports a click rate of ' +\n              'exactly 0%, because the provider rewrites links only on a ' +\n              'domain that has a verified tracking subdomain.',\n          }\n        : {}),\n    }\n  } catch (error) {\n    return {\n      status: 'unreadable',\n      domains: [],\n      unusable: [],\n      untracked: [],\n      detail: String((error as Error)?.message ?? error).slice(0, 300),\n    }\n  }\n}\n"],"names":["getEmailConfig","mailProvider","mailProviderProblem","mailProviderReads","describeEmailConfig","match","provider","missingSettings","from","address","trim","domain","includes","split","pop","configured","length","Boolean","providerProblem","hasApiKey","hasFrom","fromDomain","checkEmailCredentials","problem","status","detail","checkCredentials","id","error","String","message","slice","checkSharedSendingPool","options","pool","filter","domains","unusable","untracked","reads","unmet","byName","Map","sendingDomains","map","row","name","toLowerCase","get","present","undefined","clickTracking","openTracking","entry","join"],"mappings":"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"}

package/src/lib/mail-provider-resend.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @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.
+ */
+/**
+ * RESEND, as one {@link MailProvider} — the only module in the platform that
+ * knows Resend's endpoints, payloads, event names and error names.
+ *
+ * It is the provider a deployment gets when it names none, which is how
+ * every deployment that set `RESEND_API_KEY` before the contract existed
+ * keeps sending exactly as it did. Two credentials, on purpose:
+ *
+ * - `RESEND_API_KEY` sends. It is provisioned sending-scoped, so a leaked
+ *   copy cannot enumerate everyone the platform ever wrote to.
+ * - `RESEND_READ_API_KEY` is full-access and only ever reads: history, one
+ *   message's body, received mail and the account's sending domains. A
+ *   sending-scoped key answers every such read `401 restricted_api_key`.
+ *
+ * Pure but for the `fetch` calls, each inside a function that must be called
+ * to do anything, so a client component that reaches this module through the
+ * library's barrel executes nothing on load.
+ */
+import { type EmailDeliveryEvent, type EmailDeliveryHistorySource, type EmailDeliveryMessage, type EmailDeliveryMessageSource, type EmailDeliverySnapshot } from './email-delivery-events';
+import type { EmailCredentialReport } from './email-health';
+import { type MailInboundEvent, type MailProvider, type MailProviderMessage, type MailSendingDomain } from './mail-provider';
+import type { ReceivedEmail, ReceivedEmailSource } from './received-email';
+/** The slug stored on every delivery record this provider produces. */
+export declare const RESEND_PROVIDER_ID = "resend";
+/** The sending key's environment variable. */
+export declare const RESEND_SEND_KEY_SETTING = "RESEND_API_KEY";
+/** The full-access read key's environment variable. */
+export declare const RESEND_READ_KEY_SETTING = "RESEND_READ_API_KEY";
+type Env = Record<string, string | undefined>;
+/** The send endpoint. */
+export declare const RESEND_SEND_ENDPOINT = "https://api.resend.com/emails";
+/** A Resend send payload in the provider's own wire shape. */
+export interface ResendSendPayload {
+    to?: unknown;
+    from?: unknown;
+    subject?: unknown;
+    [field: string]: unknown;
+}
+/**
+ * The one place that POSTs to Resend's send endpoint, and the last thing
+ * standing between a payload and the network.
+ *
+ * A payload carrying no recipient cannot become a message. Resend answers it
+ * `422 missing_required_field`, which costs an API call and then shows up in
+ * the vendor dashboard as a red line indistinguishable from mail that
+ * genuinely failed to deliver — carrying no subject, no recipient and nothing
+ * naming the code that produced it. Diagnosing that means reading a log
+ * outside the deployment and guessing. So the refusal happens here, before
+ * the fetch, and names the caller's `context`.
+ *
+ * It throws rather than returning a result: this is a programming error,
+ * not a delivery outcome. `sendEmail` filters recipients well before it
+ * reaches this call, so nothing on the ordinary path can trip it. The guard
+ * exists because `RESEND_SEND_ENDPOINT` is exported and any module can
+ * therefore reach the send endpoint on its own, bypassing every check
+ * `sendEmail` owns.
+ */
+export declare function postResendEmail(apiKey: string, payload: ResendSendPayload, context?: string): Promise<Response>;
+/** One message as Resend's send endpoint takes it. */
+export declare function resendSendPayload(message: MailProviderMessage): ResendSendPayload;
+/**
+ * Where the credential probe and the domain read ask their questions.
+ *
+ * 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";
+/**
+ * Whether the sending key is accepted — 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 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.
+ */
+export declare function checkResendCredentials(apiKey: string): Promise<EmailCredentialReport>;
+/**
+ * Every sending domain on the account, with its verification and tracking
+ * state. Throws with the status when Resend does not answer 2xx, so a caller
+ * never reads "I could not look" as "there is nothing there".
+ */
+export declare function readResendSendingDomains(apiKey: string, endpoint?: string): Promise<MailSendingDomain[]>;
+/**
+ * Turns one Resend webhook payload into zero or more of our events.
+ *
+ * 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 declare function normalizeResendDeliveryEvents(payload: unknown, receivedAtMs: number): EmailDeliveryEvent[];
+/**
+ * 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 declare function normalizeResendSentEmails(raw: unknown): EmailDeliverySnapshot[];
+/** The list endpoint. Paginates with `after=<id>`; caps at 100. */
+export declare const RESEND_EMAILS_ENDPOINT = "https://api.resend.com/emails";
+/**
+ * {@link EmailDeliveryHistorySource} for Resend. Needs the full-access key.
+ *
+ * The list endpoint takes `limit`, `after` and `before` and no recipient
+ * filter, which is why the source is a cursor-paged sweep.
+ */
+export declare function resendDeliveryHistorySource(apiKey: string): EmailDeliveryHistorySource;
+/** Resend's `GET /emails/:id` payload, in our vocabulary. */
+export declare function normalizeResendMessage(raw: unknown): EmailDeliveryMessage | null;
+/** Resend's single-message endpoint. Needs the full-access key. */
+export declare function resendDeliveryMessageSource(apiKey: string): EmailDeliveryMessageSource;
+/** The webhook event type a received message arrives as. */
+export declare const RESEND_RECEIVED_EVENT = "email.received";
+/** `GET {endpoint}/{id}` — one received message with its text and headers. */
+export declare const RESEND_RECEIVING_ENDPOINT = "https://api.resend.com/emails/receiving";
+/**
+ * The provider's id of the message an `email.received` event announces,
+ * or `null` for any other event — including a malformed one, which is
+ * acknowledged and dropped rather than retried forever.
+ */
+export declare function resendReceivedEventId(event: unknown): string | null;
+/**
+ * Every recipient the event names — To, Cc, Bcc and the addresses the
+ * message was received for — so a route can find what it is looking for in
+ * the metadata before it spends a read on the body.
+ */
+export declare function resendReceivedEventRecipients(event: unknown): string[];
+/**
+ * One received message as the receiving API answers it, in the neutral
+ * shape. `null` for a payload with no id, which is not a message.
+ */
+export declare function normalizeResendReceivedEmail(raw: unknown, nowMs?: number): ReceivedEmail | null;
+/**
+ * {@link ReceivedEmailSource} for Resend. Needs the full-access key. A `404`
+ * is `null` — the message expired or never existed — and anything else
+ * throws with the status, so the caller decides whether the provider should
+ * retry.
+ */
+export declare function resendReceivedEmailSource(apiKey: string, fetchImpl?: typeof fetch): ReceivedEmailSource;
+/** A received-mail notification, or `null` for any other event. */
+export declare function resendInboundEvent(event: unknown): MailInboundEvent | null;
+/**
+ * Resend as a {@link MailProvider}, reading its two keys from `env` at each
+ * call — never at module load, because these run in serverless handlers
+ * whose module may be evaluated during a build, long before the runtime
+ * environment exists.
+ */
+export declare function resendMailProvider(env?: Env): MailProvider;
+export {};