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

package/src/lib/send-email.js

@@ -15,8 +15,11 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ /**
- * The Resend send endpoint. Every outbound application email in Aglyn goes
- * through here — invites, receipts, usage summaries, campaigns, staff alerts.
+ * The send seam. Every outbound application email in Aglyn goes through
+ * here — invites, receipts, usage summaries, campaigns, staff alerts — and
+ * everything that decides whether, as whom and to whom a message leaves is
+ * decided here. The provider that then carries it is chosen by
+ * `mail-providers.ts` and only carries it.
  *
  * Auth email (verification, password reset) is Firebase's job and does NOT
  * come through this module.
@@ -27,7 +30,8 @@ import { appendUnsubscribeHtml, appendUnsubscribeText, getMarketingSendGate, isM
 import { EMAIL_DELIVERABILITY_PREFLIGHT_TIMEOUT_MS, getEmailDeliverabilityPreflight } from "./email-deliverability.js";
 import { bareSenderAddress } from "./email-delivery-events.js";
 import { screenTenantMessage } from "./outbound-screen-gate.js";
-export const RESEND_SEND_ENDPOINT = 'https://api.resend.com/emails';
+import { providerRetryAtMs } from "./mail-provider.js";
+import { mailProvider, mailProviderProblem } from "./mail-providers.js";
 /**
  * The `context` tag, attached to every send (AGL-2407).
  *
@@ -45,8 +49,8 @@ export const RESEND_SEND_ENDPOINT = 'https://api.resend.com/emails';
  * and it is exactly the right value: it names the sender. So the tag is
  * derived here, once, and no caller changes.
  *
- * Resend tag values are restricted to ASCII letters, digits, `_` and `-`;
- * anything else is rejected and would fail the whole send. Every `context` in
+ * Providers restrict tag values — to ASCII letters, digits, `_` and `-` at
+ * the strictest — and one that rejects a value fails the whole send. Every `context` in
  * the tree is already a plain slug, but this is mail delivery — a value that
  * makes the send fail is far worse than a value that is sanitised — so the
  * label is normalised rather than trusted, and a context that sanitises to
@@ -76,42 +80,6 @@ export const RESEND_SEND_ENDPOINT = 'https://api.resend.com/emails';
     const retryAtMs = Number(failure.retryAtMs);
     return Number.isFinite(retryAtMs) ? retryAtMs : 0;
 }
-/**
- * How long to wait when the provider names no interval of its own.
- *
- * One second, because Resend's rate limit is counted per second — so a wait
- * of a whole window is the shortest one that is certain to have cleared it.
- */ const PROVIDER_RETRY_FALLBACK_MS = 1000;
-/**
- * The longest wait a provider header may ask for.
- *
- * A `retry-after` is read off the network and reaches a scheduler, so it is
- * clamped rather than trusted: a header of `86400` would park a campaign for
- * a day on one response nobody saw. An hour is past every documented window
- * and short enough that a wrong one costs a run rather than a day.
- */ const PROVIDER_RETRY_MAX_MS = 3600000;
-/** One header as whole seconds, or null when it is absent or unreadable. */ function headerSeconds(headers, name) {
-    var _headers_get;
-    const raw = headers == null ? void 0 : (_headers_get = headers.get) == null ? void 0 : _headers_get.call(headers, name);
-    // `Number(null)` and `Number('')` are both 0, which would read as "retry
-    // immediately" for a header that is not there at all.
-    if (raw === null || raw === undefined || String(raw).trim() === '') return null;
-    const seconds = Number(raw);
-    return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
-}
-/**
- * When the provider says a refused request may be repeated.
- *
- * Read from the two headers Resend documents beside a 429, both in whole
- * seconds: `retry-after` first because it is the direct answer to this
- * question, then `ratelimit-reset`, which names when the window rolls. A
- * response carrying neither falls back to one window.
- */ export function providerRetryAtMs(headers, nowMs = Date.now()) {
-    var _headerSeconds;
-    const seconds = (_headerSeconds = headerSeconds(headers, 'retry-after')) != null ? _headerSeconds : headerSeconds(headers, 'ratelimit-reset');
-    const waitMs = seconds === null ? PROVIDER_RETRY_FALLBACK_MS : Math.min(seconds * 1000, PROVIDER_RETRY_MAX_MS);
-    return nowMs + waitMs;
-}
 /**
  * Why a send did not happen, or `null` when it did.
  *
@@ -190,6 +158,31 @@ export const RESEND_SEND_ENDPOINT = 'https://api.resend.com/emails';
         if (timer) clearTimeout(timer);
     }
 }
+/**
+ * The display name a message leaves under (AGL-3442).
+ *
+ * A site's mail goes out under the site's own name — the business name its
+ * emails render as `{{host.businessName}}`, else its display name, else the
+ * org's branding default — which `hostSendingIdentity` resolves with the
+ * address from the host and org documents it already reads. That is decided
+ * here rather than at each sender because every site sender passes the org's
+ * branding default as `fromName`, and to a visitor that is the platform's or
+ * the agency's name rather than the business they dealt with. So the default
+ * is replaced, and only the default: a name of the caller's own, such as the
+ * person writing a CRM email, is still the name the message leaves under.
+ *
+ * Mail on any other identity — the platform's own, or a campaign's, which
+ * resolves its identity without a host stamp and records the name its
+ * composer chose — keeps the caller's `fromName` unchanged.
+ */ export function messageFromName(options) {
+    var _options_fromName, _ref, _ref1;
+    const given = String((_options_fromName = options.fromName) != null ? _options_fromName : '').trim();
+    const identity = options.sendingIdentity;
+    const siteName = String((_ref = identity == null ? void 0 : identity.fromName) != null ? _ref : '').trim();
+    if (!siteName) return given || undefined;
+    const brandDefault = String((_ref1 = identity == null ? void 0 : identity.brandFromName) != null ? _ref1 : '').trim();
+    return given && given !== brandDefault ? given : siteName;
+}
 /**
  * The send seam's half of the outbound phishing screen (AGL-3356): every
  * message a SITE sends whose identity carries the workspace
@@ -197,14 +190,16 @@ export const RESEND_SEND_ENDPOINT = 'https://api.resend.com/emails';
  * pure screen, its tiers, and the installed review store. `null` when the
  * message may go; fails open, as that function documents.
  */ export async function askOutboundScreen(options, label = 'email') {
-    var _options_fromName, _ref, _options_replyTo, _options_context, _options_releasedReviewId;
+    var _messageFromName, _ref, _options_replyTo, _options_context, _options_releasedReviewId;
     var _options_sendingIdentity, _options_sendingIdentity1;
     const workspace = (_options_sendingIdentity = options.sendingIdentity) == null ? void 0 : _options_sendingIdentity.workspace;
     if (options.audience !== 'tenant' || !(workspace == null ? void 0 : workspace.hostId)) return null;
     const refusal = await screenTenantMessage({
         workspace,
         subject: options.subject,
-        fromName: (_options_fromName = options.fromName) != null ? _options_fromName : null,
+        // The name the message actually leaves under, so a site named after
+        // somebody else's brand is screened on the `From:` line it would send.
+        fromName: (_messageFromName = messageFromName(options)) != null ? _messageFromName : null,
         // The resolved address, never anything the caller passed: the only
         // `From:` this message can leave on (AGL-3362).
         fromAddress: (_ref = (_options_sendingIdentity1 = options.sendingIdentity) == null ? void 0 : _options_sendingIdentity1.from) != null ? _ref : null,
@@ -233,20 +228,22 @@ export const RESEND_SEND_ENDPOINT = 'https://api.resend.com/emails';
  * in serverless handlers where the module may be evaluated during a build,
  * long before the runtime env exists.
  */ export function getEmailConfig() {
+    const provider = mailProvider();
     return {
-        apiKey: process.env.RESEND_API_KEY || undefined,
+        provider: provider.id,
+        missingSettings: provider.missingSettings(),
         from: process.env.USAGE_EMAIL_FROM || undefined
     };
 }
 /**
- * True when both `RESEND_API_KEY` and `USAGE_EMAIL_FROM` are present.
+ * True when the provider has its settings and `USAGE_EMAIL_FROM` is present.
  *
  * Callers that answer an HTTP request (rather than firing best-effort mail)
  * use this to return a 501 with an actionable message instead of pretending
  * to have sent something.
  */ export function isEmailConfigured() {
-    const { apiKey, from } = getEmailConfig();
-    return Boolean(apiKey && from);
+    const { missingSettings, from } = getEmailConfig();
+    return !missingSettings.length && Boolean(from);
 }
 /**
  * Applies a white-label display name to a configured sender while keeping
@@ -271,42 +268,7 @@ function normalizeRecipients(to) {
     return list.map((address)=>String(address != null ? address : '').trim()).filter((address)=>address.includes('@'));
 }
 /**
- * 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 `SendEmailResult`: 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 async function postResendEmail(apiKey, payload, context) {
-    const raw = payload == null ? void 0 : payload.to;
-    const recipients = (Array.isArray(raw) ? raw : raw == null ? [] : [
-        raw
-    ]).map((address)=>String(address != null ? address : '').trim()).filter(Boolean);
-    if (!recipients.length) {
-        throw new Error(`${context ? `${context} ` : ''}send refused before the network — a ` + 'Resend payload with no `to` field cannot become a message, and the ' + 'attempt would surface only as a 422 in the Resend dashboard');
-    }
-    return fetch(RESEND_SEND_ENDPOINT, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(payload)
-    });
-}
-/**
- * Sends one email through Resend.
+ * Sends one email through the deployment's mail provider.
  *
  * **Never throws and never rejects.** Outbound mail is best-effort across
  * every caller in this codebase — a checkout must not fail because a receipt
@@ -316,11 +278,12 @@ function normalizeRecipients(to) {
  *
  * When the env vars are missing this warns once per call and returns
  * `{ sent: false, reason: 'unconfigured' }` rather than failing, so local and
- * preview environments keep working without a Resend account.
+ * preview environments keep working without a mail provider.
  */ export async function sendEmail(options) {
     var _ref, _ref1, _ref2, _ref3, _ref4, _options_text;
     var _options_sendingIdentity, _options_sendingIdentity1, _options_marketing, _preflight_refused, _preflight_held, _options_marketing1, _options_marketing2, _options_headers;
-    const { apiKey, from: configuredFrom } = getEmailConfig();
+    const provider = mailProvider();
+    const configuredFrom = process.env.USAGE_EMAIL_FROM || undefined;
     const label = options.context ? `${options.context} email` : 'email';
     /*
    * THE SENDING-IDENTITY REFUSAL.
@@ -331,7 +294,7 @@ function normalizeRecipients(to) {
    * A governor is injectable and a route is skippable, so neither may be the
    * only thing standing between an unverified domain and a send.
    *
-   * Placed above the `apiKey`/`from` gate so a refusal cannot be reported as
+   * Placed above the provider/`from` gate so a refusal cannot be reported as
    * `unconfigured` — the two have different owners and different fixes.
    */ const identityRefusal = sendingIdentityRefusal(options.sendingIdentity);
     if (identityRefusal) {
@@ -374,9 +337,28 @@ function normalizeRecipients(to) {
             detail: 'This message belongs to a site and no sending identity was ' + 'resolved for it, so it was refused rather than sent from the ' + 'shared Aglyn address.'
         };
     }
-    const from = applyFromName(resolvedFrom != null ? resolvedFrom : configuredFrom, options.fromName);
-    if (!apiKey || !from) {
-        console.warn(`${label} skipped — set RESEND_API_KEY and USAGE_EMAIL_FROM to ` + 'deliver mail');
+    const from = applyFromName(resolvedFrom != null ? resolvedFrom : configuredFrom, messageFromName(options));
+    const missing = [
+        ...provider.missingSettings(),
+        ...from ? [] : [
+            'USAGE_EMAIL_FROM'
+        ]
+    ];
+    if (missing.length) {
+        /*
+     * An operator who chose a provider this process does not have is told
+     * so as an ERROR: that is not a deployment without mail, it is mail
+     * somebody set up going nowhere. See `mail-providers.ts`.
+     */ const problem = mailProviderProblem(provider);
+        if (problem) {
+            console.error(`${label} not sent — ${problem}`);
+            return {
+                sent: false,
+                reason: 'unconfigured',
+                detail: problem
+            };
+        }
+        console.warn(`${label} skipped — set ${missing.join(' and ')} to deliver mail`);
         return {
             sent: false,
             reason: 'unconfigured'
@@ -650,43 +632,51 @@ function normalizeRecipients(to) {
    */ const text = unsubscribeUrl ? appendUnsubscribeText((_options_text = options.text) != null ? _options_text : '', unsubscribeUrl) : options.text;
     const html = unsubscribeUrl ? options.html ? appendUnsubscribeHtml(options.html, unsubscribeUrl) : renderTextEmailHtml(text != null ? text : '', options.subject) : options.html;
     try {
-        var _ref7;
-        const response = await postResendEmail(apiKey, _extends({
+        var _options_headers1, _options_tags, _outcome_id;
+        // The HTML part, from the caller when it has one and otherwise
+        // synthesized from `text`. A message with no HTML part carries no
+        // anchors, so its links are not links in the inbox AND the provider has
+        // nothing to rewrite for click tracking — see `text-email-html.ts`. The
+        // caller always wins: this can only fill a gap, never override a
+        // designed template.
+        const body = html || renderTextEmailHtml(text != null ? text : '', options.subject);
+        // The caller's headers plus the RFC 8058 pair for a marketing send.
+        // Caller-first, so the campaign sender's own pair is the one that ships
+        // and a merchant-authored header is never silently replaced.
+        const headers = _extends({}, unsubscribeHeaders(oneClickUrl || unsubscribeUrl), (_options_headers1 = options.headers) != null ? _options_headers1 : {});
+        // The caller's tags plus the `context` tag (AGL-2407). Caller-first so a
+        // sender that stamps its own `context` keeps it: a tag list with two
+        // entries of one name is not a shape worth discovering in production,
+        // and the explicit one is the more specific.
+        const callerTags = (_options_tags = options.tags) != null ? _options_tags : [];
+        const tags = [
+            ...callerTags,
+            ...callerTags.some((tag)=>(tag == null ? void 0 : tag.name) === 'context') ? [] : contextTag(options.context)
+        ];
+        const outcome = await provider.send(_extends({
             from,
             to,
             subject: options.subject
         }, text ? {
             text
-        } : {}, (()=>{
-            const body = html || renderTextEmailHtml(text != null ? text : '', options.subject);
-            return body ? {
-                html: body
-            } : {};
-        })(), (()=>{
-            var _options_headers;
-            const headers = _extends({}, unsubscribeHeaders(oneClickUrl || unsubscribeUrl), (_options_headers = options.headers) != null ? _options_headers : {});
-            return Object.keys(headers).length ? {
-                headers
-            } : {};
-        })(), (()=>{
-            var _options_tags;
-            const caller = (_options_tags = options.tags) != null ? _options_tags : [];
-            const derived = caller.some((tag)=>(tag == null ? void 0 : tag.name) === 'context') ? [] : contextTag(options.context);
-            const tags = [
-                ...caller,
-                ...derived
-            ];
-            return tags.length ? {
-                tags
-            } : {};
-        })(), options.replyTo ? {
-            reply_to: options.replyTo
+        } : {}, body ? {
+            html: body
+        } : {}, Object.keys(headers).length ? {
+            headers
+        } : {}, tags.length ? {
+            tags
+        } : {}, options.replyTo ? {
+            replyTo: options.replyTo
         } : {}), options.context);
-        if (!response.ok) {
-            const detail = await response.text().catch(()=>'');
+        if (!outcome.accepted) {
+            var _refusal_detail;
+            // `strictNullChecks` is off repo-wide, so the union does not narrow on
+            // its boolean discriminant; the cast says what the branch already knows.
+            const refusal = outcome;
+            const detail = String((_refusal_detail = refusal.detail) != null ? _refusal_detail : '');
             /*
-       * A 429 IS NOT A STATEMENT ABOUT THIS RECIPIENT, so it does not report
-       * as one. See the `rate-limited` member of
+       * A REQUEST TO SLOW DOWN IS NOT A STATEMENT ABOUT THIS RECIPIENT, so it
+       * does not report as one. See the `rate-limited` member of
        * {@link SendEmailFailureReason} for why the distinction is load-bearing
        * rather than cosmetic — every caller in the tree already has a branch
        * for a deferral, and none of them has one for "rejected, but try this
@@ -695,37 +685,41 @@ function normalizeRecipients(to) {
        * A warning rather than an error: the provider asking for a slower pace
        * is a normal thing to be told, and logging it at the level a failed
        * delivery uses is what teaches an operator to skim past both.
-       */ if (response.status === 429) {
-                const retryAtMs = providerRetryAtMs(response.headers);
+       */ if (refusal.rateLimited) {
+                var _refusal_retryAtMs;
+                const retryAtMs = (_refusal_retryAtMs = refusal.retryAtMs) != null ? _refusal_retryAtMs : providerRetryAtMs(null);
                 console.warn(`${label} deferred — the provider is rate limiting; retry in ` + `${Math.max(0, Math.round((retryAtMs - Date.now()) / 1000))}s`);
-                return {
+                return _extends({
                     sent: false,
-                    reason: 'rate-limited',
-                    status: response.status,
+                    reason: 'rate-limited'
+                }, refusal.status !== undefined ? {
+                    status: refusal.status
+                } : {}, {
                     retryAtMs,
                     detail: detail.slice(0, 500)
-                };
+                });
             }
-            console.error(`${label} failed`, response.status, detail);
-            return {
+            console.error(`${label} failed`, refusal.status, detail);
+            return _extends({
                 sent: false,
-                reason: 'rejected',
-                status: response.status,
+                reason: 'rejected'
+            }, refusal.status !== undefined ? {
+                status: refusal.status
+            } : {}, {
                 detail: detail.slice(0, 500)
-            };
+            });
         }
-        const body = await response.json().catch(()=>null);
         return {
             sent: true,
-            id: (_ref7 = body == null ? void 0 : body.id) != null ? _ref7 : null
+            id: (_outcome_id = outcome.id) != null ? _outcome_id : null
         };
     } catch (error) {
-        var _ref8;
+        var _ref7;
         console.error(`${label} failed`, error);
         return {
             sent: false,
             reason: 'network',
-            detail: String((_ref8 = error == null ? void 0 : error.message) != null ? _ref8 : error).slice(0, 500)
+            detail: String((_ref7 = error == null ? void 0 : error.message) != null ? _ref7 : error).slice(0, 500)
         };
     }
 }