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

package/README.md

@@ -6,34 +6,71 @@
 
     npm install @aglyn/shared-util-email@beta
 
-One place that sends outbound **application** email, via
-[Resend](https://resend.com).
+One place that sends outbound **application** email, through a mail provider
+the deployment chooses: [Resend](https://resend.com) by default, or the
+operator's own sender behind a webhook.
 
-Before this library the same ~30 lines of `fetch('https://api.resend.com/emails')`
-were copy-pasted across 10 files, each reading the env vars itself and each
-handling failure a little differently. Consolidating them means the provider,
-the sender identity, and the failure semantics change in one place.
+Before this library the same ~30 lines of a vendor `fetch` were copy-pasted
+across 10 files, each reading the env vars itself and each handling failure a
+little differently. Consolidating them means the provider, the sender
+identity, and the failure semantics change in one place.
 
 ## What is and is not in scope
 
 | Mail | Sent by | Here? |
 | --- | --- | --- |
-| Invites, receipts, usage summaries, campaigns, staff alerts | Resend | ✅ |
+| Invites, receipts, usage summaries, campaigns, staff alerts | the mail provider | ✅ |
 | Verification, password reset | Firebase Auth | ❌ |
 | Inbound mail to `@aglyn.com` mailboxes | Google Workspace | ❌ |
 
 ## Configuration
 
-Two env vars, read at call time:
+The sender, and the settings of the provider that carries the mail, read at
+call time:
 
 ```
-RESEND_API_KEY=re_xxxxxxxx
 USAGE_EMAIL_FROM="Aglyn <noreply@aglyn.com>"
+RESEND_API_KEY=re_xxxxxxxx             # the default provider
+# or, for your own sender:
+AGLYN_MAIL_WEBHOOK_URL=https://relay.internal/send
+AGLYN_MAIL_WEBHOOK_TOKEN=…
 ```
 
-**Both** are required. With either missing, `sendEmail()` warns and returns
-`{ sent: false, reason: 'unconfigured' }` — it does not throw, so local and
-preview environments run fine without a Resend account.
+Both the sender and the provider's settings are required. With either
+missing, `sendEmail()` warns and returns `{ sent: false, reason:
+'unconfigured' }` — it does not throw, so local and preview environments run
+fine without a mail provider.
+
+## The mail provider
+
+`sendEmail()` decides whether, as whom and to whom a message leaves —
+suppression, the send-rate governor, the phishing screen, the sending
+identity, the unsubscribe footer. A `MailProvider` (`mail-provider.ts`) only
+carries the finished message, and answers the platform's other questions
+about mail in the platform's own vocabulary: whether its credential works,
+what a delivery webhook said, what a received message contained, what the
+account already sent.
+
+`mail-providers.ts` picks the deployment's provider:
+
+- `AGLYN_MAIL_PROVIDER` names one — `resend`, `webhook`, or an id a plugin or
+  fork registered with `registerMailProvider()`.
+- Unset, the first built-in with its settings wins: `resend` when
+  `RESEND_API_KEY` is set, `webhook` when only `AGLYN_MAIL_WEBHOOK_URL` is,
+  otherwise `resend`, unconfigured.
+- A name that is neither built in nor registered is **refused**: every send
+  is skipped with an error naming it, and nothing falls back to another
+  vendor.
+
+The built-ins are compiled into this library rather than registered by a
+plugin because this is the transactional rail: it must send from every server
+process with or without a plugin loaded, and a registration that did not
+happen would look exactly like mail that is switched off.
+
+The rest of the platform asks through `normalizeDeliveryEvents()`,
+`readInboundMailEvent()` and `mailProviderReads()`, never through a provider
+by name. `mail-provider-resend.ts` is the only module that knows Resend's
+wire format, and `mail-provider-webhook.ts` documents the webhook's.
 
 Setup and DNS are documented in [`docs/EMAIL_SETUP.md`](../../../../docs/EMAIL_SETUP.md).
 
@@ -66,7 +103,8 @@ correct, since the point of `USAGE_EMAIL_FROM` is one verified identity).
 
 ### The transport boundary
 
-`postResendEmail()` is the only function that POSTs to Resend's send endpoint,
+`postResendEmail()` (in `mail-provider-resend.ts`) is the only function that
+POSTs to Resend's send endpoint,
 and it **throws** on a payload with no `to` rather than putting it on the wire.
 Such a payload cannot become a message; Resend answers `422
 missing_required_field`, which costs an API call and then sits in the vendor
@@ -112,12 +150,13 @@ import { isEmailConfigured, describeEmailConfig, checkEmailCredentials }
   from '@aglyn/shared-util-email'
 ```
 
-- `isEmailConfigured()` — both vars present. Use it to answer `501` from a
-  route instead of pretending to have sent.
-- `describeEmailConfig()` — env presence plus the sender and its domain, with
-  the API key never included.
-- `checkEmailCredentials()` — asks Resend whether the key is accepted
-  **without sending anything**, by `GET`ting the domains collection and
+- `isEmailConfigured()` — the provider has its settings and a sender is set.
+  Use it to answer `501` from a route instead of pretending to have sent.
+- `describeEmailConfig()` — which provider, which of its settings are
+  missing, plus the sender and its domain, with no credential ever included.
+- `checkEmailCredentials()` — asks the provider whether its credential is
+  accepted **without sending anything**. A provider with no probe answers
+  `unknown`. Resend's probe `GET`s the domains collection and
   reading the error NAME rather than the status. A `2xx`, or a
   `restricted_api_key`/`invalid_permission` rejection (what a sending-scoped
   key gets, and it can only be reached once Resend has authenticated the key),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-util-email",
-  "version": "1.0.0-beta.218",
+  "version": "1.0.0-beta.220",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,8 +25,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.218",
-    "@aglyn/shared-util-http": "1.0.0-beta.218",
+    "@aglyn/shared-data-enums": "1.0.0-beta.220",
+    "@aglyn/shared-util-http": "1.0.0-beta.220",
     "@msgpack/msgpack": "^3.1.3",
     "@swc/helpers": "0.5.23"
   },

package/src/index.d.ts

@@ -15,6 +15,8 @@
  * limitations under the License.
  */
 export * from './lib/send-email';
+export * from './lib/mail-provider';
+export * from './lib/mail-providers';
 export * from './lib/send-rate';
 export * from './lib/sender-reputation';
 export * from './lib/send-ceilings';

package/src/index.js

@@ -14,6 +14,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ export * from "./lib/send-email.js";
+// Who carries the mail (AGL-3080): the provider contract, and the selection
+// of the deployment's provider from the built-ins and any a plugin
+// registered. The providers themselves are imported by their own paths —
+// `@aglyn/shared-util-email/mail-provider-resend`, `…/mail-provider-webhook`
+// — because nothing outside the seam should name one.
+export * from "./lib/mail-provider.js";
+export * from "./lib/mail-providers.js";
 export * from "./lib/send-rate.js";
 export * from "./lib/sender-reputation.js";
 export * from "./lib/send-ceilings.js";
@@ -32,7 +39,8 @@ export * from "./lib/marketing-send.js";
 // The List-Unsubscribe setting sequences and campaigns share (AGL-3307).
 export * from "./lib/list-unsubscribe.js";
 export * from "./lib/email-delivery-events.js";
-// The received-mail reader the CRM's capture route files from (AGL-2657).
+// Received mail in the platform's vocabulary, which the CRM's capture route
+// files from (AGL-2657); the provider reads it.
 // Its neighbor `./lib/svix-signature` is deliberately NOT re-exported here:
 // it holds a `crypto` HMAC, and this barrel is reached from the browser
 // through `@aglyn/shared-ui-email-campaigns`, so a webhook imports it by its

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/shared/util/email/src/index.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\nexport * from './lib/send-email'\nexport * from './lib/send-rate'\nexport * from './lib/sender-reputation'\nexport * from './lib/send-ceilings'\nexport * from './lib/sending-domain'\nexport * from './lib/tracking-host'\nexport * from './lib/sending-mailbox'\nexport * from './lib/host-sender'\nexport * from './lib/platform-sending-domain'\nexport * from './lib/email-health'\nexport * from './lib/system-email-catalog'\nexport * from './lib/tenant-email-catalog'\nexport * from './lib/host-email-render'\nexport * from './lib/email-render'\nexport * from './lib/text-email-html'\nexport * from './lib/marketing-send'\n// The List-Unsubscribe setting sequences and campaigns share (AGL-3307).\nexport * from './lib/list-unsubscribe'\nexport * from './lib/email-delivery-events'\n// The received-mail reader the CRM's capture route files from (AGL-2657).\n// Its neighbor `./lib/svix-signature` is deliberately NOT re-exported here:\n// it holds a `crypto` HMAC, and this barrel is reached from the browser\n// through `@aglyn/shared-ui-email-campaigns`, so a webhook imports it by its\n// own path — `@aglyn/shared-util-email/svix-signature`.\nexport * from './lib/received-email'\nexport * from './lib/email-revenue-window'\n// Exported so the console drift guard can pin it against @aglyn/aglyn.\nexport * from './lib/email-media-src'\n// Same arrangement, same reason (AGL-1223): a copy of `decodeStoredNodes`\n// this scope:shared lib may not import, pinned by `email-nodes-drift.spec.ts`.\nexport * from './lib/stored-email-nodes'\nexport * from './lib/email-merge'\n// The deliverability engine every send path asks (AGL-3328): the gateway an\n// MX names and its ledger, the bounce reader, and the address verdicts. Pure\n// — the DNS lookup and the store are injected by `@aglyn/tenant-data-admin`,\n// so nothing here reaches `node:dns` from the browser.\nexport * from './lib/mail-gateway'\nexport * from './lib/mail-bounce'\nexport * from './lib/email-deliverability'\n// The sender's side of the same engine (AGL-3328): SPF, DKIM and DMARC for\n// the domain mail leaves from, and whether they align. Pure as well; the\n// lookups are `@aglyn/tenant-data-admin`'s.\nexport * from './lib/sender-readiness'\n// The outbound phishing screen a young workspace's campaigns and automated\n// email pass (AGL-3356). Pure; the hold it leads to is `tenant-data-admin`'s.\nexport * from './lib/outbound-phishing-screen'\n// The send seam's gate for that screen — the store a hold writes is injected\n// by `@aglyn/tenant-data-admin`, like the governor's.\nexport * from './lib/outbound-screen-gate'\n// The same screen read over a published page (AGL-3356): lookalike links and\n// embeds, author-defined credential fields, a brand's call to action.\nexport * from './lib/hosted-page-screen'\n// The site's theme palette as plain data (AGL-3370), so a palette token an\n// author picked resolves in mail. Built without MUI; `shared-ui-theme`'s\n// parity spec holds it equal to the theme.\nexport * from './lib/email-palette'\nexport * from './lib/email-design-chrome'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,cAAc,sBAAkB;AAChC,cAAc,qBAAiB;AAC/B,cAAc,6BAAyB;AACvC,cAAc,yBAAqB;AACnC,cAAc,0BAAsB;AACpC,cAAc,yBAAqB;AACnC,cAAc,2BAAuB;AACrC,cAAc,uBAAmB;AACjC,cAAc,mCAA+B;AAC7C,cAAc,wBAAoB;AAClC,cAAc,gCAA4B;AAC1C,cAAc,gCAA4B;AAC1C,cAAc,6BAAyB;AACvC,cAAc,wBAAoB;AAClC,cAAc,2BAAuB;AACrC,cAAc,0BAAsB;AACpC,yEAAyE;AACzE,cAAc,4BAAwB;AACtC,cAAc,iCAA6B;AAC3C,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,6EAA6E;AAC7E,wDAAwD;AACxD,cAAc,0BAAsB;AACpC,cAAc,gCAA4B;AAC1C,uEAAuE;AACvE,cAAc,2BAAuB;AACrC,0EAA0E;AAC1E,+EAA+E;AAC/E,cAAc,8BAA0B;AACxC,cAAc,uBAAmB;AACjC,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,uDAAuD;AACvD,cAAc,wBAAoB;AAClC,cAAc,uBAAmB;AACjC,cAAc,gCAA4B;AAC1C,2EAA2E;AAC3E,yEAAyE;AACzE,4CAA4C;AAC5C,cAAc,4BAAwB;AACtC,2EAA2E;AAC3E,8EAA8E;AAC9E,cAAc,oCAAgC;AAC9C,6EAA6E;AAC7E,sDAAsD;AACtD,cAAc,gCAA4B;AAC1C,6EAA6E;AAC7E,sEAAsE;AACtE,cAAc,8BAA0B;AACxC,2EAA2E;AAC3E,yEAAyE;AACzE,2CAA2C;AAC3C,cAAc,yBAAqB;AACnC,cAAc,+BAA2B"}
+{"version":3,"sources":["../../../../../../libs/shared/util/email/src/index.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\nexport * from './lib/send-email'\n// Who carries the mail (AGL-3080): the provider contract, and the selection\n// of the deployment's provider from the built-ins and any a plugin\n// registered. The providers themselves are imported by their own paths —\n// `@aglyn/shared-util-email/mail-provider-resend`, `…/mail-provider-webhook`\n// — because nothing outside the seam should name one.\nexport * from './lib/mail-provider'\nexport * from './lib/mail-providers'\nexport * from './lib/send-rate'\nexport * from './lib/sender-reputation'\nexport * from './lib/send-ceilings'\nexport * from './lib/sending-domain'\nexport * from './lib/tracking-host'\nexport * from './lib/sending-mailbox'\nexport * from './lib/host-sender'\nexport * from './lib/platform-sending-domain'\nexport * from './lib/email-health'\nexport * from './lib/system-email-catalog'\nexport * from './lib/tenant-email-catalog'\nexport * from './lib/host-email-render'\nexport * from './lib/email-render'\nexport * from './lib/text-email-html'\nexport * from './lib/marketing-send'\n// The List-Unsubscribe setting sequences and campaigns share (AGL-3307).\nexport * from './lib/list-unsubscribe'\nexport * from './lib/email-delivery-events'\n// Received mail in the platform's vocabulary, which the CRM's capture route\n// files from (AGL-2657); the provider reads it.\n// Its neighbor `./lib/svix-signature` is deliberately NOT re-exported here:\n// it holds a `crypto` HMAC, and this barrel is reached from the browser\n// through `@aglyn/shared-ui-email-campaigns`, so a webhook imports it by its\n// own path — `@aglyn/shared-util-email/svix-signature`.\nexport * from './lib/received-email'\nexport * from './lib/email-revenue-window'\n// Exported so the console drift guard can pin it against @aglyn/aglyn.\nexport * from './lib/email-media-src'\n// Same arrangement, same reason (AGL-1223): a copy of `decodeStoredNodes`\n// this scope:shared lib may not import, pinned by `email-nodes-drift.spec.ts`.\nexport * from './lib/stored-email-nodes'\nexport * from './lib/email-merge'\n// The deliverability engine every send path asks (AGL-3328): the gateway an\n// MX names and its ledger, the bounce reader, and the address verdicts. Pure\n// — the DNS lookup and the store are injected by `@aglyn/tenant-data-admin`,\n// so nothing here reaches `node:dns` from the browser.\nexport * from './lib/mail-gateway'\nexport * from './lib/mail-bounce'\nexport * from './lib/email-deliverability'\n// The sender's side of the same engine (AGL-3328): SPF, DKIM and DMARC for\n// the domain mail leaves from, and whether they align. Pure as well; the\n// lookups are `@aglyn/tenant-data-admin`'s.\nexport * from './lib/sender-readiness'\n// The outbound phishing screen a young workspace's campaigns and automated\n// email pass (AGL-3356). Pure; the hold it leads to is `tenant-data-admin`'s.\nexport * from './lib/outbound-phishing-screen'\n// The send seam's gate for that screen — the store a hold writes is injected\n// by `@aglyn/tenant-data-admin`, like the governor's.\nexport * from './lib/outbound-screen-gate'\n// The same screen read over a published page (AGL-3356): lookalike links and\n// embeds, author-defined credential fields, a brand's call to action.\nexport * from './lib/hosted-page-screen'\n// The site's theme palette as plain data (AGL-3370), so a palette token an\n// author picked resolves in mail. Built without MUI; `shared-ui-theme`'s\n// parity spec holds it equal to the theme.\nexport * from './lib/email-palette'\nexport * from './lib/email-design-chrome'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,cAAc,sBAAkB;AAChC,4EAA4E;AAC5E,mEAAmE;AACnE,yEAAyE;AACzE,6EAA6E;AAC7E,sDAAsD;AACtD,cAAc,yBAAqB;AACnC,cAAc,0BAAsB;AACpC,cAAc,qBAAiB;AAC/B,cAAc,6BAAyB;AACvC,cAAc,yBAAqB;AACnC,cAAc,0BAAsB;AACpC,cAAc,yBAAqB;AACnC,cAAc,2BAAuB;AACrC,cAAc,uBAAmB;AACjC,cAAc,mCAA+B;AAC7C,cAAc,wBAAoB;AAClC,cAAc,gCAA4B;AAC1C,cAAc,gCAA4B;AAC1C,cAAc,6BAAyB;AACvC,cAAc,wBAAoB;AAClC,cAAc,2BAAuB;AACrC,cAAc,0BAAsB;AACpC,yEAAyE;AACzE,cAAc,4BAAwB;AACtC,cAAc,iCAA6B;AAC3C,4EAA4E;AAC5E,gDAAgD;AAChD,4EAA4E;AAC5E,wEAAwE;AACxE,6EAA6E;AAC7E,wDAAwD;AACxD,cAAc,0BAAsB;AACpC,cAAc,gCAA4B;AAC1C,uEAAuE;AACvE,cAAc,2BAAuB;AACrC,0EAA0E;AAC1E,+EAA+E;AAC/E,cAAc,8BAA0B;AACxC,cAAc,uBAAmB;AACjC,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,uDAAuD;AACvD,cAAc,wBAAoB;AAClC,cAAc,uBAAmB;AACjC,cAAc,gCAA4B;AAC1C,2EAA2E;AAC3E,yEAAyE;AACzE,4CAA4C;AAC5C,cAAc,4BAAwB;AACtC,2EAA2E;AAC3E,8EAA8E;AAC9E,cAAc,oCAAgC;AAC9C,6EAA6E;AAC7E,sDAAsD;AACtD,cAAc,gCAA4B;AAC1C,6EAA6E;AAC7E,sEAAsE;AACtE,cAAc,8BAA0B;AACxC,2EAA2E;AAC3E,yEAAyE;AACzE,2CAA2C;AAC3C,cAAc,yBAAqB;AACnC,cAAc,+BAA2B"}

package/src/lib/email-delivery-events.d.ts

@@ -14,6 +14,42 @@
  * 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 one sending vendor. Two things follow from that, and
+ * this module is both of them:
+ *
+ * 1. **The stored shape is ours.** Nothing downstream — the delivery log, the
+ *    staff card, a future export — reads a provider's field names or its event
+ *    strings. A provider turns its own wire format into these types (its
+ *    `deliveryEvents` and `reads`, see `mail-provider.ts`), and swapping the
+ *    sender changes that provider and nothing else in the tree.
+ * 2. **The history is ours.** The log is written into our own Firestore and
+ *    read from there, never from the provider on render. A provider's list
+ *    endpoint is a different shape per vendor, has its own retention window,
+ *    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) is the vocabulary that
+ *    history is imported through, 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`, and the reading
+ * of a provider's payloads in that provider.
+ */
 /**
  * The lifecycle of one message, in the order it normally happens.
  *
@@ -34,7 +70,7 @@ export interface EmailDeliveryEvent {
     type: EmailDeliveryEventType;
     /** When the PROVIDER says it happened, falling back to receipt time. */
     at: number;
-    /** Slug of the sending provider, e.g. `'resend'`. */
+    /** Slug of the sending provider — the `id` of the provider that carried it. */
     provider: string;
     /** The provider's id for the message. Our per-message document key. */
     providerMessageId: string;
@@ -80,23 +116,6 @@ export declare function bareSenderAddress(value: unknown): string | null;
 export declare function worstDeliveryStatus(current: EmailDeliveryEventType | null | undefined, next: EmailDeliveryEventType): EmailDeliveryEventType;
 /** Tags arrive as an array of `{name, value}` or a plain map — accept both. */
 export declare function normalizeEventTags(raw: unknown): Record<string, string>;
-/**
- * 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 declare function normalizeResendDeliveryEvents(payload: unknown, receivedAtMs: number): EmailDeliveryEvent[];
 /** One message as the provider currently reports it, in our vocabulary. */
 export interface EmailDeliverySnapshot {
     provider: string;
@@ -108,18 +127,6 @@ export interface EmailDeliverySnapshot {
     /** Furthest state the provider reports. Never richer than the event feed. */
     status: EmailDeliveryEventType;
 }
-/**
- * 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[];
 /** One page of provider history, in our vocabulary. */
 export interface EmailDeliveryHistoryPage {
     snapshots: EmailDeliverySnapshot[];
@@ -131,25 +138,15 @@ export interface EmailDeliveryHistoryPage {
  *
  * The shape a second provider would implement. Cursor-based rather than
  * offset- or date-based because that is the lowest common denominator, and
- * NOT filtered by recipient: Resend's list endpoint has no recipient
- * parameter, so filtering is the caller's job and the import is a sweep
- * rather than a per-person lookup. That is the right shape regardless — a
- * staff page must not fan out to a third party on render.
+ * NOT filtered by recipient: a provider's list endpoint need not take one,
+ * so filtering is the caller's job and the import is a sweep rather than a
+ * per-person lookup. That is the right shape regardless — a staff page must
+ * not fan out to a third party on render.
  */
 export type EmailDeliveryHistorySource = (options: {
     cursor?: string | null;
     limit?: number;
 }) => Promise<EmailDeliveryHistoryPage>;
-/** Resend's 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 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 declare function resendDeliveryHistorySource(apiKey: string): EmailDeliveryHistorySource;
 /** One message's content and envelope, in our vocabulary. */
 export interface EmailDeliveryMessage {
     provider: string;
@@ -169,7 +166,3 @@ export interface EmailDeliveryMessage {
 }
 /** A single message by id. The shape a second provider would implement. */
 export type EmailDeliveryMessageSource = (providerMessageId: string) => Promise<EmailDeliveryMessage | null>;
-/** Resend's `GET /emails/:id` payload, in our vocabulary. */
-export declare function normalizeResendMessage(raw: unknown): EmailDeliveryMessage | null;
-/** Resend's single-message endpoint. Needs the same full-access key. */
-export declare function resendDeliveryMessageSource(apiKey: string): EmailDeliveryMessageSource;

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

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