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

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 {};