@steve31415/baselib 3.0.2 → 3.1.0

package/README.md

@@ -6,7 +6,7 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `~/migration/research/base-services-design.md` (step 5).
 
 Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
-`app-update`, and `llm`. Browser exports: `log-browser`, `rum`, `sync-browser`, and
+`app-update`, `llm`, and `email`. Browser exports: `log-browser`, `rum`, `sync-browser`, and
 `app-update-browser`.
 
 `sync` provides the Postgres event-log and server protocol primitives;
@@ -23,6 +23,10 @@ generic Yjs or service-worker coordinator.
 registry, automatic cross-provider failover, portable JSON-schema output.
 Usage guide: `~/plasticine-way/docs/LLM.md`.
 
+`email` is the fleet's transactional email path: `sendEmail` through Resend
+from a named `NAME@snewman.net` sender, no outbox — a failed send is an
+ERROR log (`~/plasticine-way/docs/SECURITY.md`, "Resend API key").
+
 Bins: `check-test-owners` — the fleet's structural test-coverage gate; every
 app runs it from `npm run verify`.
 

package/dist/email.d.ts

@@ -0,0 +1,34 @@
+import { type Logger } from './log-core.js';
+export declare const RESEND_API_URL = "https://api.resend.com/emails";
+/** An email to send. At least one of `text` / `html` must be present. */
+export interface EmailMessage {
+    /** RFC 5322 from address, e.g. `Watchdog <watchdog@snewman.net>`. */
+    from: string;
+    to: string;
+    subject: string;
+    text?: string;
+    html?: string;
+}
+export interface SendEmailResult {
+    ok: boolean;
+    /** Resend's message id, when the send succeeded and the response parsed. */
+    emailId?: string;
+    /** Human-readable failure description, present when `ok` is false. */
+    error?: string;
+}
+export interface EmailDeps {
+    /** Resend API key. Falsy means "email not configured": logged at ERROR with
+     *  the message, never sent. */
+    apiKey: string | undefined;
+    logger: Logger;
+    /** Defaults to the global `fetch`. Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    /** Merged into every log line so callers can attribute the send. */
+    context?: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export declare function sendEmail(msg: EmailMessage, deps: EmailDeps): Promise<SendEmailResult>;

package/dist/email.js

@@ -0,0 +1,80 @@
+// Transactional email through Resend — the fleet's one email path for
+// system-generated mail (Steve's ruling 2026-09-03, migration decision log):
+// named senders on the verified snewman.net domain (`Watchdog
+// <watchdog@snewman.net>`, `Lurch <steve@snewman.net>`, …), key from Secret
+// Manager `shared--resend-api-key`. Gmail via Mirror2's token broker stays
+// only for mail that is genuinely Steve-to-Steve (Digest2).
+//
+// Ported from the old-world package @steve31415/resend-mailer 1.0.0
+// (plasticine-apps/resend-mailer@5148649) minus its D1 outbox: the new-world
+// rule is no outbox — a failed send is an ERROR log carrying the message,
+// so the daily triage sees it and the send can be redone by hand. The
+// request shape and error handling are the package's, kept verbatim: they
+// ran against the live Resend API for months (TESTING.md, "Assumptions
+// 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.
+import { serializeError, truncate } from './log-core.js';
+export const RESEND_API_URL = 'https://api.resend.com/emails';
+/**
+ * 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.
+ */
+export async function sendEmail(msg, deps) {
+    const { logger } = deps;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const base = {
+        to: msg.to,
+        subject: truncate(msg.subject, 200),
+        textLength: msg.text?.length ?? 0,
+        htmlLength: msg.html?.length ?? 0,
+        ...deps.context,
+    };
+    const preview = { text: truncate(msg.text ?? '', 500), html: truncate(msg.html ?? '', 500) };
+    if (!msg.text && !msg.html) {
+        logger.error('email_rejected_no_body', base);
+        return { ok: false, error: 'sendEmail requires a non-empty `text` or `html` body' };
+    }
+    if (!deps.apiKey) {
+        // Nothing else will record what we failed to send: log the whole message.
+        logger.error('email_not_configured', { ...base, hasKey: false, ...preview });
+        return { ok: false, error: 'Email not configured: missing Resend API key' };
+    }
+    logger.info('email_sending', base);
+    const start = Date.now();
+    try {
+        const res = await fetchImpl(RESEND_API_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deps.apiKey}` },
+            body: JSON.stringify({
+                from: msg.from,
+                to: [msg.to],
+                subject: msg.subject,
+                ...(msg.text !== undefined ? { text: msg.text } : {}),
+                ...(msg.html !== undefined ? { html: msg.html } : {}),
+            }),
+        });
+        const elapsedMs = Date.now() - start;
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            const error = `Resend API ${res.status}: ${truncate(body, 500)}`;
+            logger.error('email_send_failed', { ...base, status: res.status, body: truncate(body, 500), elapsedMs, ...preview });
+            return { ok: false, error };
+        }
+        let emailId;
+        try {
+            emailId = JSON.parse(body).id;
+        }
+        catch {
+            // Non-JSON success body: unusual, but the send did succeed.
+        }
+        logger.info('email_sent', { ...base, status: res.status, emailId, elapsedMs });
+        return { ok: true, emailId };
+    }
+    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)}` };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,10 @@
     "./llm": {
       "types": "./dist/llm/index.d.ts",
       "default": "./dist/llm/index.js"
+    },
+    "./email": {
+      "types": "./dist/email.d.ts",
+      "default": "./dist/email.js"
     }
   },
   "bin": {