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

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

@@ -0,0 +1,385 @@
+/**
+ * @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.
+ */
+/**
+ * The Resend send endpoint. Every outbound application email in Aglyn goes
+ * through here — invites, receipts, usage summaries, campaigns, staff alerts.
+ *
+ * Auth email (verification, password reset) is Firebase's job and does NOT
+ * come through this module.
+ */
+import { type EmailSendPriority } from './send-rate';
+import { type SendingIdentityAudience, type SendingIdentityVerdict } from './sending-domain';
+import { type MarketingSendContext } from './marketing-send';
+export declare const RESEND_SEND_ENDPOINT = "https://api.resend.com/emails";
+/** A Resend delivery tag, used for webhook attribution (AGL-268). */
+export interface EmailTag {
+    name: string;
+    value: string;
+}
+export interface SendEmailOptions {
+    /** One or more recipient addresses. */
+    to: string | string[];
+    subject: string;
+    /** Plain-text body. Supply at least one of `text` or `html`. */
+    text?: string;
+    /**
+     * HTML body. Supply at least one of `text` or `html`.
+     *
+     * Omitted, one is synthesized from `text` so the message always carries an
+     * HTML part — a text-only message has no anchors, so its links are inert in
+     * the inbox and Resend's click tracking has nothing to rewrite. See
+     * `text-email-html.ts`.
+     */
+    html?: string;
+    /** Extra MIME headers, e.g. `List-Unsubscribe`. */
+    headers?: Record<string, string>;
+    /** Delivery tags for the opens/clicks webhook. */
+    tags?: EmailTag[];
+    replyTo?: string | string[];
+    /**
+     * White-label display name for the sender (White-Label Phase 1). Replaces
+     * only the display name in front of the verified address — the address
+     * itself is never taken from the caller, so this cannot forge a different
+     * sender. Callers pass `resolveBrandingProfile(org).fromName` here so an
+     * agency's mail reads as their brand instead of "Aglyn".
+     */
+    fromName?: string;
+    /**
+     * The server-resolved sending identity for this message, from
+     * `resolveSendingIdentity`.
+     *
+     * Supplied, it decides the address and it may refuse the send outright —
+     * `fromName` is subordinate to it, because a verdict is the answer to "may
+     * this leave, and as whom" and a display name is not. Omitted, every
+     * existing caller keeps the behavior it had: the configured platform
+     * identity with an optional display name.
+     *
+     * Callers resolve it from the ORG DOCUMENT, never from request input. An
+     * address assembled from a request body is a `From:` override wearing a new
+     * name, and the invariant `applyFromName` exists to hold is that the
+     * address cannot move off a verified identity.
+     */
+    sendingIdentity?: SendingIdentityVerdict | null;
+    /**
+     * Whose mail this is — see {@link SendingIdentityAudience}.
+     *
+     * `tenant` says the message belongs to a SITE, and it makes the platform
+     * sender unreachable: a tenant message with no resolved identity is refused
+     * rather than sent from `aglyn.com`. Pair it with `sendingIdentity` from
+     * `hostSendingIdentity(hostId)` and the ordinary path is unchanged; the flag
+     * is what decides the behavior when that resolution is missing or refuses.
+     *
+     * Omitted, a send is platform mail and keeps the configured sender, because
+     * that is what the console's own senders are. `email-audience-coverage.spec`
+     * sweeps the tenant-owned trees so the omission cannot be an accident there.
+     */
+    audience?: SendingIdentityAudience;
+    /**
+     * Short label for logs, e.g. `'invite'` or `'usage-summary'`. Makes a
+     * failure in the runtime logs traceable to the feature that caused it.
+     *
+     * Since AGL-2407 it is also stamped as a Resend `context` TAG on every
+     * send — see `contextTag` below.
+     */
+    context?: string;
+    /**
+     * What the platform send-rate governor is allowed to do to this message
+     * (AGL-2409). Omitted, it is derived from `context`: `'campaign'` is a
+     * campaign and everything else is transactional, so no existing caller
+     * changes and the default is the one that can never be refused.
+     *
+     * Set it to `'bulk'` ONLY from a resumable sweep — a cron that leaves its
+     * subject unstamped and picks it up on the next run. A refusal for a bulk
+     * send means "not this hour", and a caller that cannot come back would turn
+     * that into a message nobody ever gets.
+     */
+    priority?: EmailSendPriority;
+    /**
+     * Declares this message as MARKETING mail for one site's audience — see
+     * `marketing-send.ts` for what that means and why it is one seam.
+     *
+     * Set it and the message gains, in one place, the three things marketing
+     * mail owes: the RFC 8058 unsubscribe header pair plus a visible opt-out
+     * link, a check against both suppression lists, and a ceiling on how much
+     * one person receives from one site.
+     *
+     * ONE RECIPIENT. An unsubscribe link is an HMAC over the address it belongs
+     * to, and a suppression verdict is about one person — so a marketing send
+     * addressed to a list would carry the wrong link for everybody after the
+     * first, and would ask the gate about one of them. Callers fan out.
+     */
+    marketing?: MarketingSendContext;
+}
+/**
+ * The `context` tag, attached to every send (AGL-2407).
+ *
+ * ## Why this is here and not at 37 call sites
+ *
+ * Until now `tags` were set by exactly one sender, `campaign-send.ts`, which
+ * stamps `hostId` and `campaignId` for the opens/clicks webhook. Everything
+ * else went out with NO tags at all, so a bounce on an invite, a password
+ * reset, a receipt or a usage summary reached the webhook carrying nothing to
+ * identify it, and was dropped.
+ *
+ * The obvious fix — thread an identifier through every call site — asks 37
+ * places to remember, which is the shape that produces the 38th that does
+ * not. But `context` is ALREADY threaded through 35 of the 37 for logging,
+ * 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
+ * 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
+ * nothing yields no tag rather than an invalid one.
+ */
+export declare function contextTag(context: string | undefined): EmailTag[];
+/**
+ * Why a send did not happen. `unconfigured` and `no-recipient` mean nothing
+ * was attempted; `rejected` and `network` mean Resend was called and failed;
+ * `rate-limited` is either, and says so in `status`.
+ *
+ * `rate-limited` (AGL-2409) and `frequency-capped` are the two a caller may
+ * reasonably retry unchanged — see {@link isDeferrableSendResult}, which is
+ * where that distinction is made once rather than at each sweep.
+ */
+export type SendEmailFailureReason = 'unconfigured' | 'no-recipient'
+/**
+ * Resend answered and would not take this message.
+ *
+ * Per-message and terminal: a malformed payload, an address the provider
+ * will not accept, a tag it rejected. A caller that retries it unchanged
+ * gets the same answer, so a batch settles the recipient rather than
+ * holding a slot open for them.
+ *
+ * A 429 is deliberately NOT this. See `rate-limited`.
+ */
+ | 'rejected' | 'network'
+/**
+ * A refusal that is about the RATE, not about this message — so the message
+ * is intact and a later attempt sends it.
+ *
+ * Two sources, which is why it is one value. The platform hourly governor
+ * refuses before the network and nothing is attempted (AGL-2409). Resend
+ * answers `429` on the wire when requests arrive faster than it accepts
+ * them, and `status` is 429 in that case.
+ *
+ * The provider arm reports here rather than as `rejected` because of what
+ * the two mean to a batch. A `rejected` recipient is settled and never
+ * addressed again, which is right for an address the provider will not take
+ * and wrong for every recipient a 429 touches: nothing about them was
+ * refused, the request was simply too soon. Classified as `rejected` a
+ * single rate-limited burst silently deletes the rest of a campaign's
+ * audience while the campaign reports itself complete — and the `sent`
+ * figure stays honest throughout, so no rate on the report can show it.
+ *
+ * The provider's quota errors — `daily_quota_exceeded`,
+ * `monthly_quota_exceeded` — are also 429 and also land here. That is the
+ * right answer for the same reason: none of them is a statement about the
+ * recipient, and all of them clear with time.
+ */
+ | 'rate-limited'
+/**
+ * The org selected a custom sending domain and that domain is not verified.
+ *
+ * Distinct from `unconfigured` because the two need opposite responses: an
+ * unconfigured deployment is the operator's to fix, while this is a
+ * customer's DNS that is not finished, and the customer is the only person
+ * who can finish it. `detail` carries the sentence naming the domain.
+ *
+ * This is the LAST line of defence, not the visible one. A caller that
+ * reaches it has already skipped the check its route should have made, and
+ * a refusal seen only here is a log line — which is the shape of the
+ * `USAGE_EMAIL_FROM` outage. `performCampaignSend` refuses first, with a
+ * `409`, so a person finds out.
+ */
+ | 'unverified-domain'
+/**
+ * A MARKETING send whose recipient is on a suppression list — they
+ * unsubscribed from this site, hard-bounced, or pressed "report spam".
+ *
+ * Terminal, and the only outcome here a caller must not retry: retrying is
+ * the behavior the suppression exists to stop. Distinct from `rejected`
+ * because nothing was attempted and nothing failed — this is the control
+ * working.
+ */
+ | 'suppressed'
+/**
+ * A MARKETING send refused because this person has already received their
+ * ceiling from this site inside the window.
+ *
+ * Retryable, unlike `suppressed`: the window rolls. A resumable sweep does
+ * not need to do anything about it — its next run asks again.
+ */
+ | 'frequency-capped'
+/**
+ * A MARKETING send refused because this site has been mailing this person
+ * for longer than the sunset window with nothing to show for it.
+ *
+ * TERMINAL for a sweep, and it sits with `suppressed` rather than with
+ * `frequency-capped` for a reason worth stating: the frequency window
+ * clears by the passage of time, so waiting works. A sunset clears when the
+ * PERSON engages, which more mail from us cannot cause — so a sweep that
+ * treated it as deferrable would re-read the same doomed row on every beat
+ * forever. Nothing about the recipient has been reduced; the next message
+ * after they open anything goes.
+ */
+ | 'unengaged';
+export type SendEmailResult = {
+    sent: true;
+    id: string | null;
+} | {
+    sent: false;
+    reason: SendEmailFailureReason;
+    /** HTTP status, when Resend answered. */
+    status?: number;
+    /** Resend's error body or the thrown message, trimmed for logs. */
+    detail?: string;
+    /**
+     * `rate-limited` only: the earliest instant a caller may try again —
+     * when the platform hourly window rolls, or what the provider's own
+     * `retry-after` asked for. A resumable sweep does not need to wait on
+     * it; its next scheduled run is the retry.
+     */
+    retryAtMs?: number;
+};
+/**
+ * The retry instant when the platform send-rate governor deferred this
+ * message, or `null` for every other outcome (AGL-2409).
+ *
+ * A FUNCTION rather than `result.reason === 'rate-limited'` at each call site,
+ * because `strictNullChecks` is OFF repo-wide and TypeScript will not narrow a
+ * boolean-literal discriminant without it: `if (result.sent) … else
+ * result.reason` does not compile, in every consumer, for a reason that has
+ * nothing to do with this union. One helper is also one place to change if the
+ * shape of a deferral ever moves.
+ */
+export declare function rateLimitedRetryAtMs(result: SendEmailResult | null | undefined): number | 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 declare function providerRetryAtMs(headers: {
+    get?: (name: string) => string | null;
+} | null | undefined, nowMs?: number): number;
+/**
+ * Why a send did not happen, or `null` when it did.
+ *
+ * The same accessor `rateLimitedRetryAtMs` is, generalized: `strictNullChecks`
+ * is OFF repo-wide, so TypeScript will not narrow the union on `result.sent`
+ * and reading `result.reason` at a call site does not compile.
+ */
+export declare function sendFailureReason(result: SendEmailResult | null | undefined): SendEmailFailureReason | null;
+/**
+ * Whether this outcome is worth coming back for.
+ *
+ * TRUE only for the two refusals a later attempt can pass: the platform hour
+ * rolls, and so does the marketing frequency window. Everything else is
+ * either a delivery that happened or a failure a retry repeats — a
+ * suppression most of all, since retrying is the exact behavior a suppression
+ * exists to stop, and a sunset for the same reason at one remove: it clears
+ * when the recipient engages, which no amount of further mail from us brings
+ * about.
+ *
+ * A resumable sweep uses this to decide whether to leave its subject
+ * unstamped. Stamping on a deferrable refusal discards a message; NOT
+ * stamping on a terminal one re-reads the same doomed row on every beat until
+ * it crowds out the work that could succeed. Both are silent, so the
+ * distinction lives here instead of at each sweep.
+ *
+ * A FUNCTION rather than `result.reason === …` at each call site, because
+ * `strictNullChecks` is OFF repo-wide and TypeScript will not narrow a
+ * boolean-literal discriminant without it — the same reason
+ * {@link rateLimitedRetryAtMs} beside it is one.
+ */
+export declare function isDeferrableSendResult(result: SendEmailResult | null | undefined): boolean;
+export interface EmailConfig {
+    apiKey: string | undefined;
+    from: string | undefined;
+}
+/**
+ * Reads the email environment.
+ *
+ * Deliberately read per call rather than captured at module load: these run
+ * in serverless handlers where the module may be evaluated during a build,
+ * long before the runtime env exists.
+ */
+export declare function getEmailConfig(): EmailConfig;
+/**
+ * True when both `RESEND_API_KEY` and `USAGE_EMAIL_FROM` are 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 declare function isEmailConfigured(): boolean;
+/**
+ * Applies a white-label display name to a configured sender while keeping
+ * its verified address (White-Label Phase 1). Accepts either a bare address
+ * (`noreply@aglyn.com`) or an RFC-5322 `Name <addr>` header and returns
+ * `"<fromName>" <addr>`. A blank name, or a value with no extractable
+ * address, yields the original `from` untouched — the sender identity is
+ * never dropped on the floor.
+ */
+export declare function applyFromName(from: string | undefined, fromName: string | undefined): string | undefined;
+/** 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 `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 declare function postResendEmail(apiKey: string, payload: ResendSendPayload, context?: string): Promise<Response>;
+/**
+ * Sends one email through Resend.
+ *
+ * **Never throws and never rejects.** Outbound mail is best-effort across
+ * every caller in this codebase — a checkout must not fail because a receipt
+ * bounced — so every outcome comes back as a `SendEmailResult` instead. The
+ * one thing callers must not do is ignore the result: `sent` is what tells
+ * the user whether a message actually went out (AGL-708).
+ *
+ * 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.
+ */
+export declare function sendEmail(options: SendEmailOptions): Promise<SendEmailResult>;
+export default sendEmail;