@pithy-sh/email 0.1.0

package/src/send/runSend.ts

@@ -0,0 +1,320 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import type { DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import type { Updateable } from "kysely";
+import { EmailJob, SPENT_PAYLOAD } from "../data/emailJob";
+import type { EmailJobStatus, SuppressionReason } from "../data/enums";
+import type { EmailDatabase, EmailSuppressionDatabase, EmailTables } from "../data/tables";
+import { type RenderTracking, redactsPayloadOnDelivery, renderEmail, templateKind } from "../templates/engine";
+import { type EmailMessageLayers, emailTranslator, kitEmailLayers } from "../templates/messages";
+import type { EmailTheme } from "../templates/theme";
+import { classifySendError } from "./errorMapping";
+import { recordEvent } from "./events";
+import type { EmailSender } from "./sender";
+import { blockingSuppression, suppress } from "./suppression";
+
+/**
+ * Send one job — the body the send Workflow runs inside a durable step. Never called from a request
+ * handler. It loads the job, skips a suppressed recipient, renders (with tracking per the job's flags),
+ * sends through the binding, and records the outcome on the row plus an event. On a retryable failure
+ * it throws (the Workflow step retries with backoff) until `maxAttempts`, then marks the job failed.
+ *
+ * **Whether a suppression applies depends on the message.** The kind comes from the template, not from
+ * the job row and not from a caller, so a magic link is transactional by declaration and an unrelated
+ * unsubscribe cannot swallow it.
+ *
+ * **A delivered job's inputs are dropped here, and "delivered" is the only place they can be.** The
+ * payload of a magic link *is* the sign-in link, so a row that keeps it after the message is out is a
+ * second, permanent copy of a live credential in a table nobody thinks of as holding secrets — which is
+ * what made an adopter's digested invitation token worth nothing the moment it was mailed. The line is
+ * `sent`, and every other outcome keeps its payload on purpose: `failed` can be retried, `suppressed`
+ * can be unblocked, and a payload dropped before the last attempt is a message that cannot be resent —
+ * a worse failure than the one being fixed. `sent` is the one status a retry is *already* refused for,
+ * because the mail has gone to a real person, so nothing here can ever need those inputs again.
+ */
+
+/** The current signing key plus the valid version set, for minting tracking/unsubscribe links. */
+export interface SendSigning {
+  /** The current signing key value. */
+  key: string;
+  /** The current signing key version, recorded as the token `kid`. */
+  kid: string;
+}
+
+/** Everything a send needs that isn't on the job row. */
+export interface SendDeps {
+  /** The per-environment jobs/events database. */
+  db: EmailDatabase;
+  /** The global, shared suppression database — checked before every send, fed by bounces/complaints. */
+  suppressionDb: EmailSuppressionDatabase;
+  sender: EmailSender;
+  theme: EmailTheme;
+  /**
+   * Where the words for a locale come from.
+   *
+   * The host that runs this is a standalone Worker — nothing composes capabilities inside it — so it
+   * cannot be handed a composed project's layers the way the app worker's enqueue is. It reads the
+   * catalogs off its own env instead (`EMAIL_MESSAGES`) and turns them into this. Absent walks the
+   * kit's English, which is what a project that never opted into a second language gets.
+   */
+  layersFor?: EmailMessageLayers;
+  /** The public base URL for callback links. */
+  baseUrl: string;
+  /** The signing key for tracking/unsubscribe links. Absent disables tracking (and blocks marketing sends). */
+  signing?: SendSigning;
+  /** How long a tracked link stays valid. */
+  linkTtlDays: number;
+  /** The most attempts before a retryable failure becomes terminal. */
+  maxAttempts: number;
+  /** This worker's environment name, stamped on each send (X-Pithy-Env) so the single inbound worker can route. */
+  environment?: string;
+  /**
+   * When this pass began — **stable across a Workflow resume** (pithy-sh/pithy#327).
+   *
+   * Everything that dates the work reads this: `sentAt`, the redaction stamp, the events, and how long a
+   * tracked link stays valid. A driver body re-executes from the top on a resume, so a clock read there
+   * answers with the resume — and a batch that backed off overnight dated its remaining jobs, and the
+   * expiry of every link in them, a day late. `runSendBatch` journals this in a step so a resume reads
+   * back the instant the batch began.
+   *
+   * A link minted on the resumed half expires from the pass, not from the mint. Two people in one batch
+   * are promised the same window; which attempt happened to render their message is not something they
+   * can see and not something their link should depend on.
+   */
+  passStartedAt: Date;
+  /**
+   * "This job is being worked on, now" — **read fresh on every call**, and never journaled.
+   *
+   * This is not a stamp with a tidier name. `updatedAt` is the scheduler's only evidence that a `sending`
+   * job is alive: `runScheduler` claims and re-drives anything in `sending` older than `stuckMs`, on the
+   * assumption its dispatch died. Freeze it and a batch that resumes past that window reports the job it
+   * is actively retrying as stranded, so the next tick starts a second send Workflow against it — and
+   * `runSend` short-circuits only a job already `sent`, so both attempts render and both call `send`. One
+   * person, two emails. A sweep journaled the single `now` this replaced and was reverted for exactly
+   * that.
+   *
+   * The suppression liveness read takes it too, because "is this address blocked *right now*" is a
+   * present-tense question and an hour-old answer to it is simply wrong.
+   */
+  heartbeatAt: () => Date;
+}
+
+/** The outcome of a send attempt. */
+export interface SendOutcome {
+  jobId: string;
+  status: EmailJobStatus;
+  messageId?: string;
+  skipped?: boolean;
+  /**
+   * Why nothing was sent, when the recipient was on the suppression list.
+   *
+   * A skipped send has to be reported, not swallowed. Without this the caller sees an outcome that is
+   * not `failed` and the person sees an empty inbox, which is what made the whole class of bug invisible
+   * from both ends. "Suppressed" alone is not enough either — an operator deciding what to do next needs
+   * to know whether the address bounced, complained, or opted out.
+   */
+  suppressionReason?: SuppressionReason;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** A partial update to the jobs table, in its SQLite row shape. */
+type JobUpdate = Updateable<DatabaseSchema<EmailTables>["pithyEmailJobs"]>;
+
+/**
+ * Patch a job row by id, always bumping `updatedAt` — **on the heartbeat clock, not the pass instant.**
+ *
+ * Every write this function makes is also a statement that the job is still being worked on, because
+ * `updatedAt` is what the scheduler's `sending` re-drive reads. That is why the bump is here rather than
+ * at each call site: a patch that did not say "still alive" would be a patch that invited a second send
+ * Workflow. See {@link SendDeps.heartbeatAt}.
+ */
+async function patchJob(deps: SendDeps, jobId: string, patch: JobUpdate): Promise<void> {
+  await deps.db
+    .updateTable("pithyEmailJobs")
+    .set({ ...patch, updatedAt: SQLiteDate.encode(deps.heartbeatAt()) })
+    .where("id", "=", jobId)
+    .execute();
+}
+
+export async function runSend(deps: SendDeps, jobId: string): Promise<SendOutcome> {
+  const row = await deps.db.selectFrom("pithyEmailJobs").selectAll().where("id", "=", jobId).executeTakeFirst();
+  if (!row) throw new NotFoundError({ detail: `email job '${jobId}' not found` });
+  const job = EmailJob.parse(row);
+
+  // Idempotent: a job already sent or canceled is a no-op (a Workflow can re-run a step).
+  if (job.status === "sent") return { jobId, status: "sent", messageId: job.messageId ?? undefined };
+  if (job.status === "canceled") return { jobId, status: "canceled", skipped: true };
+
+  const recipient = normalizeAddress(job.toAddress);
+
+  // A job whose inputs were dropped cannot be re-rendered. Unreachable today — only a `sent` job is
+  // redacted and `sent` short-circuits two lines up — and it is here because the invariant is worth
+  // more executable than commented. It fails terminally rather than throwing: a throw would retry, and
+  // every attempt would render the same empty payload. What it prevents is the worse outcome, which is
+  // a real person receiving a magic-link email with no link in it.
+  if (job.payloadRedactedAt) {
+    await patchJob(deps, jobId, { status: "failed", error: "payload dropped after delivery" });
+    await recordEvent(
+      deps.db,
+      { jobId, recipient, type: "failed", detail: "payload already redacted" },
+      deps.passStartedAt,
+    );
+    return { jobId, status: "failed" };
+  }
+
+  // The template's own declaration, not `job.category` and not anything the enqueuing call site chose.
+  // Deriving it here means a template whose kind is corrected in a later release corrects the jobs
+  // already queued against it, and that a stored value can never drift from the template it names.
+  const kind = templateKind(job.template);
+  // The heartbeat clock: whether an address is blocked is a question about now, and a suppression that
+  // expired while this batch was backed off must not still be blocking.
+  const blocked = await blockingSuppression(deps.suppressionDb, recipient, deps.heartbeatAt(), kind);
+  if (blocked) {
+    await patchJob(deps, jobId, { status: "suppressed", error: `recipient suppressed: ${blocked}` });
+    await recordEvent(deps.db, { jobId, recipient, type: "suppressed", detail: blocked }, deps.passStartedAt);
+    return { jobId, status: "suppressed", skipped: true, suppressionReason: blocked };
+  }
+
+  // A marketing send needs a signing key for its unsubscribe link; without one it cannot render. This
+  // is a configuration fault, not a transient one, so fail **terminally** — return, don't throw. A
+  // throw would make the Workflow step retry, and since a `failed` row isn't short-circuited above it
+  // would re-enter and re-throw, burning the whole retry budget re-failing.
+  if (job.category === "marketing" && !deps.signing) {
+    await patchJob(deps, jobId, { status: "failed", error: "no signing key for marketing unsubscribe link" });
+    await recordEvent(deps.db, { jobId, recipient, type: "failed", detail: "no signing key" }, deps.passStartedAt);
+    return { jobId, status: "failed" };
+  }
+
+  const tracking: RenderTracking | undefined = deps.signing
+    ? {
+        baseUrl: deps.baseUrl,
+        jobId,
+        recipient,
+        campaignId: job.campaignId ?? undefined,
+        key: deps.signing.key,
+        kid: deps.signing.kid,
+        expiresAt: new Date(deps.passStartedAt.getTime() + deps.linkTtlDays * DAY_MS),
+        openTracking: job.openTracking,
+        clickTracking: job.clickTracking,
+      }
+    : undefined;
+
+  const attempts = job.attempts + 1;
+  await patchJob(deps, jobId, { status: "sending", attempts });
+
+  // The job's own locale, not a request's — there is no request here, which is exactly why the tag is
+  // on the row. This is the second of the two render sites, and the column is what makes it agree with
+  // the first: the subject stored at enqueue and the body composed now are one language by
+  // construction rather than by two call sites happening to choose alike.
+  const rendered = await renderEmail(
+    job.template,
+    job.payload,
+    deps.theme,
+    tracking,
+    emailTranslator(job.locale, deps.layersFor ?? kitEmailLayers),
+  );
+  // Stamp the origin job and environment so the single (production) inbound worker can attribute an
+  // async bounce/complaint back to where it came from. Suppression itself is global, so it applies
+  // regardless; these headers carry the per-job/per-env context the platform send response cannot.
+  const headers: Record<string, string> = { "X-Pithy-Job": jobId };
+  if (deps.environment) headers["X-Pithy-Env"] = deps.environment;
+  // Threading, when the job carries it. Both headers or neither: a client threads on `In-Reply-To`
+  // and falls back to `References`, so sending one without the other is how a conversation stays
+  // together in some mail clients and splits in others.
+  if (job.inReplyTo) headers["In-Reply-To"] = job.inReplyTo;
+  if (job.references) headers.References = job.references;
+  // One-click opt-out, and **only** where the body already offers one — `rendered.unsubscribeUrl` is
+  // present exactly for an elective template, so this cannot appear on a sign-in link. That restraint is
+  // the point: Gmail's and Yahoo's bulk-sender rules require one-click unsubscribe for *promotional*
+  // mail, and some clients surface the header as prominently as the message body. On a magic link it
+  // would publish a mechanism for disabling authentication, one tap from the mail the account depends on.
+  //
+  // Both headers together, per RFC 8058: `List-Unsubscribe-Post` is what tells a client the URL will
+  // honor a POST, and the callback accepts one for that reason. Sending it without a POST route would
+  // advertise an opt-out that silently does nothing.
+  if (rendered.unsubscribeUrl) {
+    headers["List-Unsubscribe"] = `<${rendered.unsubscribeUrl}>`;
+    headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+  }
+  const message = {
+    to: recipient,
+    from: { email: job.fromAddress, name: job.fromName },
+    ...(job.replyTo ? { replyTo: job.replyTo } : {}),
+    subject: rendered.subject,
+    html: rendered.html,
+    text: rendered.text,
+    headers,
+  };
+
+  try {
+    const result = await deps.sender.send(message);
+    // The status and the redaction are one write. Two statements would leave a window in which the row
+    // says `sent` and still holds the link, and the window would be exactly as long as whatever went
+    // wrong between them.
+    const spent = redactsPayloadOnDelivery(job.template);
+    await patchJob(deps, jobId, {
+      status: "sent",
+      sentAt: SQLiteDate.encode(deps.passStartedAt),
+      messageId: result.messageId ?? null,
+      // The subject that actually went out, which is not necessarily the one enqueue stored.
+      // `runSend` sends a *fresh* render rather than `job.subject`, so the column was only ever the
+      // enqueue's guess at it — and a template corrected, a theme renamed, or a catalog sentence
+      // retranslated between the queue and the send made the send log describe a message nobody
+      // received. An operator reading the row is reading the delivered subject now.
+      subject: rendered.subject,
+      error: null,
+      ...(spent ? { payload: SPENT_PAYLOAD, payloadRedactedAt: SQLiteDate.encode(deps.passStartedAt) } : {}),
+    });
+    await recordEvent(deps.db, { jobId, recipient, type: "sent", campaignId: job.campaignId }, deps.passStartedAt);
+
+    // Synchronous permanent bounces (batch/REST shape) feed suppression immediately.
+    for (const bounced of result.permanentBounces ?? []) {
+      await suppress(
+        deps.suppressionDb,
+        {
+          email: bounced,
+          reason: "hard_bounce",
+          jobId,
+          environment: deps.environment,
+          detail: "permanent bounce on send",
+        },
+        deps.passStartedAt,
+      );
+      await recordEvent(
+        deps.db,
+        { jobId, recipient: normalizeAddress(bounced), type: "bounce", detail: "permanent bounce on send" },
+        deps.passStartedAt,
+      );
+    }
+
+    return { jobId, status: "sent", messageId: result.messageId };
+  } catch (err) {
+    const classified = classifySendError(err);
+
+    if (classified.suppressed) {
+      await patchJob(deps, jobId, { status: "suppressed", error: classified.code, bounceCode: classified.code });
+      await suppress(
+        deps.suppressionDb,
+        { email: recipient, reason: "hard_bounce", jobId, environment: deps.environment, detail: classified.code },
+        deps.passStartedAt,
+      );
+      await recordEvent(deps.db, { jobId, recipient, type: "suppressed", detail: classified.code }, deps.passStartedAt);
+      return { jobId, status: "suppressed", skipped: true };
+    }
+
+    if (classified.retryable && attempts < deps.maxAttempts) {
+      // Persist the last error, then throw so the Workflow step retries with backoff (row stays `sending`).
+      await patchJob(deps, jobId, { error: classified.code });
+      throw classified.error;
+    }
+
+    await patchJob(deps, jobId, { status: "failed", error: classified.code });
+    await recordEvent(deps.db, { jobId, recipient, type: "failed", detail: classified.code }, deps.passStartedAt);
+    return { jobId, status: "failed" };
+  }
+}

package/src/send/sendAt.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeIanaTimezone } from "@pithy-sh/core/src/data/codecs";
+import { EmailInvalidPayloadError } from "../error/errors";
+
+/**
+ * Resolve a job's absolute send time from its mode. `immediate` is now; `scheduled` is the given
+ * absolute instant; `timezone` resolves a recipient-local time-of-day (e.g. `10:00`) in their IANA
+ * zone to the next absolute instant at or after now. The timezone math uses `Intl` only — no library —
+ * by measuring the zone's offset at a candidate instant and correcting for it.
+ */
+
+/** The offset (ms) of a timezone at a given UTC instant: zone wall-clock minus UTC. */
+function zoneOffsetMs(timezone: string, utcMs: number): number {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+  const parts = formatter.formatToParts(new Date(utcMs));
+  const get = (type: string): number => Number(parts.find((p) => p.type === type)?.value ?? "0");
+  // `hour` can come back as 24 at midnight in some engines; normalize to 0.
+  const hour = get("hour") % 24;
+  const asUtc = Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second"));
+  return asUtc - utcMs;
+}
+
+/** Parse `HH:MM` to `{ hour, minute }`, or throw `email/invalid_payload`. */
+function parseLocalTime(localTime: string): { hour: number; minute: number } {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(localTime.trim());
+  const hour = match ? Number(match[1]) : Number.NaN;
+  const minute = match ? Number(match[2]) : Number.NaN;
+  if (!match || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new EmailInvalidPayloadError({ detail: `invalid localTime '${localTime}' — expected HH:MM` });
+  }
+  return { hour, minute };
+}
+
+/**
+ * The next absolute instant when the wall clock reads `hour:minute` in `timezone`, at or after `now`.
+ * Computes the candidate for the zone-local date of `now`, advancing a day if it has already passed.
+ */
+export function resolveTimezoneSendAt(localTime: string, timezone: string, now: Date): Date {
+  const zone = normalizeIanaTimezone(timezone);
+  if (!zone) throw new EmailInvalidPayloadError({ detail: `invalid IANA timezone '${timezone}'` });
+  const { hour, minute } = parseLocalTime(localTime);
+
+  // The zone-local calendar date of `now`.
+  const dateParts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: zone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(now);
+  const part = (type: string): number => Number(dateParts.find((p) => p.type === type)?.value ?? "0");
+
+  const candidateFor = (dayOffset: number): Date => {
+    const guessUtc = Date.UTC(part("year"), part("month") - 1, part("day") + dayOffset, hour, minute);
+    // Correct the guess by the zone's offset at that instant so the wall clock lands on hour:minute.
+    // A single correction is wrong when the offset at the guess differs from the offset at the corrected
+    // instant (a DST boundary), so apply a second pass: if the offset there differs, re-correct from it.
+    // (In the spring-forward gap, where hour:minute doesn't exist, this settles on the post-transition
+    // instant rather than landing an hour off.)
+    const first = guessUtc - zoneOffsetMs(zone, guessUtc);
+    const secondOffset = zoneOffsetMs(zone, first);
+    return new Date(guessUtc - secondOffset);
+  };
+
+  const today = candidateFor(0);
+  return today.getTime() >= now.getTime() ? today : candidateFor(1);
+}

package/src/send/sender.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The minimal shape of the Cloudflare Email Service `send_email` binding this capability depends on.
+ * We type only what we use, structurally — the real binding (`env.EMAIL`) satisfies it, and tests
+ * inject a fake so send outcomes are deterministic. The binding sends both `html` and `text` and
+ * returns a `messageId`; it throws on failure with an `E_*` `.code` (mapped by `errorMapping`).
+ */
+
+/** An outbound message handed to the binding — html + text both, per deliverability best practice. */
+export interface EmailMessage {
+  /** The recipient address. */
+  to: string;
+  /** The sender — address plus display name. */
+  from: { email: string; name?: string };
+  /** Optional reply-to address. */
+  replyTo?: string;
+  /** The rendered subject line. */
+  subject: string;
+  /** The rendered HTML body. */
+  html: string;
+  /** The rendered plain-text body. */
+  text: string;
+  /** Optional whitelisted headers (e.g. `List-Unsubscribe`). */
+  headers?: Record<string, string>;
+}
+
+/**
+ * The send response. The Workers binding returns a `messageId`; the batch/REST shape additionally
+ * reports `delivered`/`permanentBounces`/`queued`. We capture all of it so synchronous permanent
+ * bounces can feed suppression immediately, and the `messageId` ties an asynchronous bounce back.
+ */
+export interface EmailSendResult {
+  messageId?: string;
+  delivered?: string[];
+  permanentBounces?: string[];
+  queued?: string[];
+}
+
+/** The send seam. `env.EMAIL` satisfies it; tests pass a fake. */
+export interface EmailSender {
+  send(message: EmailMessage): Promise<EmailSendResult>;
+}

package/src/send/senderBinding.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { resolveWorkflowBinding } from "@pithy-sh/core/src/workflow/dispatch";
+import type { SendWorkflowBinding } from "./enqueue";
+
+/**
+ * Where the send Workflow comes from — one answer, for the two call sites that need it.
+ *
+ * `email().enqueue` and the admin retry route both start a send, and both used to read
+ * `env.EMAIL_SENDER` straight off the request env. Under `pithy dev` that binding does not exist:
+ * it is a **cross-script** binding at `<project>-dev-email`, and no local script runs under that
+ * name, so every immediate send was born `undispatched` and the local loop was silent
+ * (pithy-sh/pithy#410). A module rather than a line in each place, because the day the two answers
+ * differ is the day one of them stops sending mail and nothing says so.
+ */
+
+/**
+ * What deciding the sender reads off the env, and nothing else.
+ *
+ * Three keys, not the whole enqueue env: `DB` and the suppression list are somebody else's question,
+ * and a narrower parameter is what lets the admin routes' own env shape pass without a cast.
+ */
+export interface EmailSenderEnv {
+  /** The bound send Workflow. Present in every deployed environment; absent under `pithy dev`. */
+  EMAIL_SENDER?: SendWorkflowBinding;
+  /**
+   * The environment this composition was stamped for — `pithy init` writes it into every Worker's
+   * `wrangler.jsonc`. Read only to refuse: a substitution happens in `dev` and nowhere else.
+   */
+  ENVIRONMENT?: string;
+  /**
+   * The local email host's address, written by `pithy dev` as a `--var`. Present only in `dev`, where
+   * it is what stands in for the cross-script binding no local script can provide.
+   */
+  EMAIL_ORIGIN?: string;
+}
+
+/**
+ * The Workflow that starts a send: the bound one, or — under `pithy dev` — a loopback dispatcher
+ * addressed at the local email host.
+ *
+ * The rules are core's ({@link resolveWorkflowBinding}) and are stated there. The one thing decided
+ * here is that email's host is the capability named `email`, which is what makes the var
+ * `EMAIL_ORIGIN`.
+ *
+ * **Absent still means absent.** A composition with no binding and no local host enqueues the row
+ * `undispatched` exactly as it did — this fills the seam, it never invents one.
+ */
+export function emailSenderBinding(env: EmailSenderEnv): SendWorkflowBinding | undefined {
+  // An interface is not assignable to an index signature, and core's resolver reads an env by name.
+  return resolveWorkflowBinding(env as unknown as Record<string, unknown>, {
+    binding: "EMAIL_SENDER",
+    capability: "email",
+  });
+}