@steve31415/baselib 3.50.0 → 3.51.0

package/dist/email.d.ts

@@ -36,10 +36,25 @@ export interface EmailDeps {
     fetchImpl?: typeof fetch;
     /** Merged into every log line so callers can attribute the send. */
     context?: Record<string, unknown>;
+    /** Whole-request deadline (connect, response and body), default
+     *  `DEFAULT_EMAIL_TIMEOUT_MS`. A timed-out send is an ordinary failure,
+     *  but Resend may have accepted it and delivered the email: retry with
+     *  the same `idempotencyKey` to be safe. */
+    timeoutMs?: number;
+    /** Sent as Resend's `Idempotency-Key` HTTP request header (not an email
+     *  header — those are `EmailMessage.headers`). Up to 256 characters; for
+     *  24 hours a retry with the same key and the same message returns the
+     *  original send's id without sending again. Derive it from what makes
+     *  the email unique (e.g. `digest:<user>:<date>`), never from the
+     *  attempt. See the header of this file for the verified semantics. */
+    idempotencyKey?: string;
 }
+export declare const DEFAULT_EMAIL_TIMEOUT_MS = 30000;
 /**
  * Send one email through Resend. Never throws: every failure is an ERROR
  * log (with enough of the message to redo the send by hand) and an
- * `{ ok: false, error }` result the caller surfaces where it matters.
+ * `{ ok: false, error }` result the caller surfaces where it matters. That
+ * includes a timeout (`deps.timeoutMs`), after which the email may
+ * nevertheless have been delivered.
  */
 export declare function sendEmail(msg: EmailMessage, deps: EmailDeps): Promise<SendEmailResult>;

package/dist/email.js

@@ -14,22 +14,38 @@
 // about external systems"): `POST https://api.resend.com/emails` with
 // `{from, to: [to], subject, text?, html?}` answers 200 `{id}`; failures are
 // 4xx/5xx with a JSON body.
+//
+// Idempotency (verified 2026-11-02 against
+// https://resend.com/docs/dashboard/emails/idempotency-keys and a live probe
+// to the `delivered@resend.dev` test sink): the HTTP request header
+// `Idempotency-Key`, 1–256 characters, kept 24 hours. A repeat with the same
+// key and the same body sends nothing and answers 200 with the original
+// `{id}`, so a replayed send is an ordinary success here. A repeat with a
+// different body is 409 `invalid_idempotent_request`; one that arrives while
+// the first is still in flight is 409 `concurrent_idempotent_requests`
+// (retry later); a key over 256 characters is 400 `invalid_idempotency_key`.
+// All three are failures: none confirms that this message was accepted.
 import { serializeError, truncate } from './log-core.js';
 export const RESEND_API_URL = 'https://api.resend.com/emails';
+export const DEFAULT_EMAIL_TIMEOUT_MS = 30_000;
 /**
  * Send one email through Resend. Never throws: every failure is an ERROR
  * log (with enough of the message to redo the send by hand) and an
- * `{ ok: false, error }` result the caller surfaces where it matters.
+ * `{ ok: false, error }` result the caller surfaces where it matters. That
+ * includes a timeout (`deps.timeoutMs`), after which the email may
+ * nevertheless have been delivered.
  */
 export async function sendEmail(msg, deps) {
     const { logger } = deps;
     const fetchImpl = deps.fetchImpl ?? fetch;
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_EMAIL_TIMEOUT_MS;
     const base = {
         to: msg.to,
         subject: truncate(msg.subject, 200),
         textLength: msg.text?.length ?? 0,
         htmlLength: msg.html?.length ?? 0,
         attachmentCount: msg.attachments?.length ?? 0,
+        ...(deps.idempotencyKey !== undefined ? { idempotencyKey: deps.idempotencyKey } : {}),
         ...deps.context,
     };
     const preview = { text: truncate(msg.text ?? '', 500), html: truncate(msg.html ?? '', 500) };
@@ -47,7 +63,12 @@ export async function sendEmail(msg, deps) {
     try {
         const res = await fetchImpl(RESEND_API_URL, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deps.apiKey}` },
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${deps.apiKey}`,
+                ...(deps.idempotencyKey !== undefined ? { 'Idempotency-Key': deps.idempotencyKey } : {}),
+            },
+            signal: AbortSignal.timeout(timeoutMs),
             body: JSON.stringify({
                 from: msg.from,
                 to: [msg.to],
@@ -85,7 +106,13 @@ export async function sendEmail(msg, deps) {
     }
     catch (err) {
         const elapsedMs = Date.now() - start;
-        logger.error('email_send_error', { ...base, error: serializeError(err), elapsedMs, ...preview });
-        return { ok: false, error: `Network error: ${err instanceof Error ? err.message : String(err)}` };
+        const timedOut = err instanceof Error && err.name === 'TimeoutError';
+        logger.error('email_send_error', { ...base, error: serializeError(err), timedOut, timeoutMs, elapsedMs, ...preview });
+        return {
+            ok: false,
+            error: timedOut
+                ? `Timed out after ${timeoutMs} ms waiting for Resend; the email may still have been delivered`
+                : `Network error: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.50.0",
+  "version": "3.51.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",