@pithy-sh/email 0.1.0

package/src/http/view.ts

@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { EmailJob } from "../data/emailJob";
+import type { EmailSuppression } from "../data/emailSuppression";
+import type { EmailJobDetail, EmailJobListItem, EmailSuppressionView } from "./responses";
+
+/**
+ * What a management client is allowed to see. Nothing in this package ever returns a raw row.
+ *
+ * ## `payload` is never projected. Anywhere.
+ *
+ * `EmailJob.payload` holds the template's input variables, and that is not merely "often PII" — it is
+ * the most sensitive column this capability owns. A `magicLink` job's payload contains the sign-in URL,
+ * an `otp` job's contains the code, an order confirmation's contains a name, an address, and what
+ * somebody bought. Projecting it on a read scope would turn "let the dashboard show me the email log"
+ * into "let the dashboard sign in as any user who requested a magic link recently", which is a full
+ * account takeover reachable from the least privileged credential this capability defines.
+ *
+ * There is no flag to turn it on and no field that carries a redacted version of it. An operator
+ * diagnosing a send needs to know *which template* ran and *what went wrong*, and both are projected.
+ * They do not need the variables, and the one case where they would — reproducing a render — is
+ * reachable from the adopter's own database, where the audit trail is not a substitute for authority.
+ *
+ * ## The list masks the recipient; the detail does not
+ *
+ * `toAddress` is personal data on its own. The list is the bulk surface — a hundred rows a request,
+ * paged, is precisely how a compromised credential turns a job log into a customer address book — so it
+ * carries a masked address: enough for an operator to recognize the row they are looking for, and
+ * useless for harvesting. The **detail** route returns the whole address, one job at a time, with an
+ * audit event naming that job.
+ *
+ * This is a bulk-harvest control, not anonymization, and it is not sold as one. `ad***@example.com`
+ * identifies a person to anyone who already knows them. What it does is raise the cost of taking the
+ * whole list from one request per hundred addresses to one request per address, each individually
+ * recorded — which is the difference between an incident nobody can reconstruct and one whose every
+ * step is in the trail. The precedent is the same one testers' `resend` and `remove` follow: return the
+ * id, not the address, and let the audit trail hold what the response does not.
+ *
+ * The **domain survives masking**, deliberately. It is the field an operator reads a deliverability
+ * problem off — every failure landing on one provider is the diagnosis — and it names an organization
+ * rather than a person.
+ *
+ * The suppression list is the deliberate exception: an address *is* the record there, so masking it
+ * would leave a list of blocks nobody could act on. That is exactly why reading it is its own scope.
+ *
+ * ## Structural on the list, rendered on the detail
+ *
+ * The line the list holds is not "less data" — it is *kind* of data. `template`, `category`, `mode`,
+ * `bounceType` and `locale` each name what a message was, and none of them carries a character of what
+ * it said or of who read it, so a hundred of them in one response is a hundred facts about this
+ * project rather than a hundred facts about people. `subject` is the other kind. It is rendered copy,
+ * it routinely names the recipient's own order or their own document, and it stays beside the whole
+ * address on the detail route, where the disclosure is one job at a time and the audit trail names it.
+ *
+ * `locale` earns the list on exactly that test. "Why is half this account getting English" is a
+ * question about a page of rows, and answering it through the detail route means a hundred audited
+ * disclosures of a hundred addresses to render one column.
+ */
+
+/**
+ * Mask a recipient for the list.
+ *
+ * Two characters of the local part survive, then the domain in full. Anything that does not parse as
+ * `local@domain` collapses to `***` rather than being echoed — a row whose address is malformed is
+ * usually a row whose address came from somewhere unexpected, and passing it through unchanged is how
+ * the one value the mask exists for escapes it.
+ */
+export function maskAddress(address: string): string {
+  const at = address.lastIndexOf("@");
+  if (at <= 0 || at === address.length - 1) return "***";
+  const local = address.slice(0, at);
+  const domain = address.slice(at + 1);
+  return `${local.slice(0, 2)}***@${domain}`;
+}
+
+/**
+ * ## The field lists live in `responses.ts`
+ *
+ * Every view type below is `z.output` of the Zod object there, so there is one declaration of what a
+ * client receives rather than an interface here and a hand-written mirror of it in every management
+ * client. A field added to one and not the other does not compile.
+ */
+
+/** Project one job for the list. */
+export function jobListView(job: EmailJob): EmailJobListItem {
+  return {
+    id: job.id,
+    recipient: maskAddress(job.toAddress),
+    template: job.template,
+    category: job.category,
+    locale: job.locale ?? null,
+    status: job.status,
+    mode: job.mode,
+    attempts: job.attempts,
+    campaignId: job.campaignId ?? null,
+    bounceType: job.bounceType ?? null,
+    failed: Boolean(job.error),
+    sendAt: job.sendAt.toISOString(),
+    createdAt: job.createdAt.toISOString(),
+    sentAt: job.sentAt ? job.sentAt.toISOString() : null,
+  };
+}
+
+/** Project one job in full. */
+export function jobDetailView(job: EmailJob): EmailJobDetail {
+  const { recipient: _masked, failed: _failed, ...common } = jobListView(job);
+  return {
+    ...common,
+    toAddress: job.toAddress,
+    subject: job.subject,
+    fromAddress: job.fromAddress,
+    fromName: job.fromName,
+    messageId: job.messageId ?? null,
+    error: job.error ?? null,
+    bounceCode: job.bounceCode ?? null,
+    timezone: job.timezone ?? null,
+    localTime: job.localTime ?? null,
+    openTracking: job.openTracking,
+    clickTracking: job.clickTracking,
+    updatedAt: job.updatedAt.toISOString(),
+  };
+}
+
+/** Project one suppression row, resolving `active` against `now`. */
+export function suppressionView(row: EmailSuppression, now: Date): EmailSuppressionView {
+  const expiresAt = row.expiresAt ?? null;
+  return {
+    id: row.id,
+    email: row.email,
+    reason: row.reason,
+    environment: row.environment ?? null,
+    jobId: row.jobId ?? null,
+    detail: row.detail ?? null,
+    createdAt: row.createdAt.toISOString(),
+    expiresAt: expiresAt ? expiresAt.toISOString() : null,
+    active: expiresAt === null || expiresAt.getTime() > now.getTime(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add email` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory plus the enqueue API and the types an app needs to send mail. Every
+ * other module is imported by deep path (`@pithy-sh/email/src/...`); this is the documented contract,
+ * not a barrel over the package.
+ */
+
+export { type CampaignStats, campaignStats } from "./analytics";
+export { type EmailCapability, type EmailConfigInput, email, isEmailCapability } from "./capability";
+export type { EmailKind, SuppressionReason } from "./data/enums";
+export type { EmailSuppressionDatabase } from "./data/tables";
+// The control-plane scopes, exported because they are the join key with what `pithy dashboard connect`
+// offers an adopter to grant. A doc or a tool naming one of these should read the constant, not retype
+// the string — a scope that differs by a character is a gate nothing ever satisfies.
+export {
+  EMAIL_CONTROL_PLANE_SCOPES,
+  EMAIL_JOBS_READ_SCOPE,
+  EMAIL_JOBS_RETRY_SCOPE,
+  EMAIL_SUPPRESSIONS_DELETE_SCOPE,
+  EMAIL_SUPPRESSIONS_READ_SCOPE,
+  EMAIL_SUPPRESSIONS_WRITE_SCOPE,
+} from "./http/guards";
+/**
+ * Has this template already gone to this person (pithy-sh/pithy#354).
+ *
+ * Exported for the same reason the suppression readers are: **it is the adopter's database**, and the
+ * alternative to publishing this read is every adopter querying `pithy_email_jobs` through the handle
+ * `emailDatabase(d1)` already hands them — a second definition of this capability's schema in somebody
+ * else's repository, drifting in whichever direction nobody is looking.
+ *
+ * A notice that must not repeat, and must be corrected if what it announced stops being true, is the
+ * caller this exists for. Do not answer it with a column of your own: a flag saying "we sent it" is a
+ * second answer to a question this table already holds the first of, and the two disagree the first time
+ * a send fails after the flag is written.
+ */
+export { type SentFilter, type SentLog, SentSummary, sentSince } from "./jobs/read";
+export { type EnqueueInput, type EnqueueResult, enqueueEmail } from "./send/enqueue";
+// How a Workflow sends mail (pithy-sh/pithy#356). A route holds the bound `enqueue` its `compose` hook
+// handed it; a durable step has no such hook, and this is the seam that gets it there without restating
+// the sending identity `pithy.config.ts` already resolved.
+export { composedEmail, enqueueFromEnv } from "./send/fromComposition";
+/**
+ * The suppression list, for the adopter who wants to look (pithy-sh/pithy#355).
+ *
+ * Nobody needs these to be protected — `enqueue` consults the list on its own and `runSend` refuses a
+ * blocked recipient regardless. They are here because **it is the adopter's database**: an operator
+ * un-suppressing an address a customer has fixed, a support screen explaining why a letter did not go,
+ * a report of who a notice could not reach. Pair them with `EmailCapability.suppressions(env)`, which
+ * hands back the handle without anybody naming a binding.
+ *
+ * `blockingSuppression` takes the message's kind, and the kind belongs to the template — read it with
+ * `templateKind`, never type a literal. A restated `"transactional"` is a claim about somebody else's
+ * template, and it is the claim that starts withholding invitations from people who unsubscribed from
+ * a newsletter.
+ */
+export {
+  blockingSuppression,
+  listSuppressions,
+  type SuppressionListFilter,
+  type SuppressionPage,
+  suppress,
+  suppressionBlocks,
+  unsuppress,
+} from "./send/suppression";
+export { listTemplates, templateKind } from "./templates/engine";
+// The one payload contract exported by name. Every other template is called by a capability in this
+// repo, which deep-imports; an operational notice is the template an *adopter* sends, about their own
+// infrastructure, and it is the one where getting the severity wrong should not wait for runtime.
+export { OperationalNoticePayload } from "./templates/registry";
+export { NoticeSeverity } from "./templates/severity";

package/src/jobs/read.ts

@@ -0,0 +1,273 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { decodeCursor, type PageCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { z } from "zod";
+import { EmailJob } from "../data/emailJob";
+import type { EmailJobStatus } from "../data/enums";
+import type { EmailDatabase } from "../data/tables";
+
+/**
+ * Reading the send log: the queries behind the two `email:jobs:read` routes, and `sentSince` below.
+ *
+ * The two are different questions and deliberately not one function. The routes serve an operator
+ * walking the log — every job, newest first, filtered by status, paged, and gated by a control-plane
+ * scope. `sentSince` answers a single question for the adopter's own code, in their own Worker, about a
+ * message they are about to send: has this one already gone out. It is not exposed over HTTP, because
+ * nothing calls it over HTTP — see its own note.
+ *
+ * **Keyset pagination, never offset.** `pithy_email_jobs` is written to on every single send, which
+ * makes it the worst possible table to page with `OFFSET`: a row inserted at the head while somebody is
+ * on page two pushes one row from page one down, so they see it twice and miss another by luck. The
+ * cursor names the last row's `(createdAt, id)` position, so the next page starts exactly where the
+ * previous ended whatever arrived in between. The helper is core's — one implementation, one decode,
+ * one definition of what a malformed cursor means.
+ *
+ * `createdAt` is the sort key rather than `sendAt`: a scheduled job's `sendAt` is a *future* time that a
+ * retry then moves, so ordering on it would shuffle rows around under a reader for reasons that have
+ * nothing to do with when anything happened. `createdAt` never moves.
+ *
+ * Rows are decoded through `EmailJob.parse` before they leave this module, so callers get Dates and
+ * booleans rather than ms-epochs and `0|1` — and a corrupt row fails here rather than three layers up.
+ */
+
+/** What the list filters and pages by. */
+export interface JobListFilter {
+  /** One lifecycle state, or every state when absent. */
+  status?: EmailJobStatus;
+  /** The previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped into range. */
+  limit?: number;
+}
+
+/** One page of the send log. */
+export interface JobPage {
+  /** The jobs, newest first. */
+  items: EmailJob[];
+  /** Where the next page starts, or null at the end of the list. */
+  nextCursor: string | null;
+}
+
+/**
+ * A cursor this table can actually resume from.
+ *
+ * `PageCursor.sort` is a union because Better Auth stores ISO text where Pithy's own tables store
+ * ms-epoch numbers, and comparing a string against an integer column in SQLite silently orders by
+ * something nobody meant. Jobs store a number, so anything else is treated exactly as a malformed
+ * cursor is: undefined, and the caller gets a first page.
+ */
+function jobCursor(raw: string | undefined): { sort: number; id: string } | undefined {
+  const cursor: PageCursor | undefined = decodeCursor(raw);
+  if (!cursor || typeof cursor.sort !== "number") return undefined;
+  return { sort: cursor.sort, id: String(cursor.id) };
+}
+
+/** One page of jobs, newest first, optionally filtered to one status. */
+export async function listJobs(db: EmailDatabase, filter: JobListFilter): Promise<JobPage> {
+  const limit = pageLimit(filter.limit);
+  const after = jobCursor(filter.cursor);
+
+  let query = db
+    .selectFrom("pithyEmailJobs")
+    .selectAll()
+    .orderBy("createdAt", "desc")
+    .orderBy("id", "desc")
+    // One more than asked for, so "is there another page" is answerable without a count query — which
+    // on a table holding every email a project ever sent is the difference between a page and a scan.
+    .limit(limit + 1);
+
+  if (filter.status) query = query.where("status", "=", filter.status);
+  if (after) {
+    query = query.where((eb) =>
+      eb.or([eb("createdAt", "<", after.sort), eb.and([eb("createdAt", "=", after.sort), eb("id", "<", after.id)])]),
+    );
+  }
+
+  const rows = await query.execute();
+  const jobs = rows.map((row) => EmailJob.parse(row));
+  return toPage(jobs, limit, (job) => ({ sort: job.createdAt.getTime(), id: job.id }));
+}
+
+/** One job by id, or undefined. The caller decides what a miss means. */
+export async function getJob(db: EmailDatabase, jobId: string): Promise<EmailJob | undefined> {
+  const row = await db.selectFrom("pithyEmailJobs").selectAll().where("id", "=", jobId).executeTakeFirst();
+  return row ? EmailJob.parse(row) : undefined;
+}
+
+/**
+ * ## `sentSince` — has this message already gone out
+ *
+ * The narrow read, for the caller deciding whether to send. A transactional notice that must not repeat,
+ * and must be *corrected* if the thing it announced stops being true, cannot be decided from a flag of
+ * the caller's own: a `cancellationNoticeSentAt` column is a second answer to a question this table
+ * already holds the first of, and the two disagree the first time a send fails after the flag is
+ * written. `pithy_email_jobs` is the record; this is the read over it, so nobody has to define its shape
+ * a second time in their own repository.
+ *
+ * ## Two axes, because a template is not always one message
+ *
+ * It was `(to, template)` alone, and that could not finish its only intended consumer (pithy-sh/pithy#382).
+ * Six account notices ride one `operationalNotice` to the same addresses, so the template id does not
+ * separate them; `correlation` is the enqueue-side discriminator that does. See {@link SentSubject} for
+ * why the two are a union and not three optional fields.
+ *
+ * **The direction of the failure is why this was worth a column.** The dashboard uses the answer
+ * *positively*: the correction letter goes out only when the letter it corrects already did. An
+ * under-report there sends nothing at all — it withholds the correction from somebody holding a letter
+ * that has stopped being true. That is silence, to the one person owed the message, and silence is the
+ * failure nobody finds in production.
+ *
+ * ## Four columns, and every other one is a deliberate no
+ *
+ * `SentSummary` is `EmailJob.pick(…)`, so the columns it carries are the columns it selects and a
+ * projection cannot leak one it never loaded. What is not on it:
+ *
+ * - **`toAddress`.** The caller passed the address in; handing it back means a read answering a question
+ *   about one person returns a copy of them in every row, and any log of the result is an address list.
+ * - **`payload`.** The sign-in link and the OTP. `view.ts` argues this at length and the argument is the
+ *   same here, except that this reader is reachable from ordinary application code rather than only from
+ *   a scoped credential, which makes it stronger rather than weaker.
+ * - **`subject`.** Rendered content, and the temptation is specific: it is the only per-row string that
+ *   distinguishes two messages sharing a template, so a caller needing that discrimination would match
+ *   on it. That match breaks on a copy edit, silently, in the direction of sending again. Discriminating
+ *   two notices was the enqueue side's problem and now has an enqueue-side answer — `correlation`
+ *   (#382) — rather than a rendered string exported to be string-matched.
+ * - **`messageId`, `error`, `bounceCode`.** The provider's own words. A provider error routinely embeds
+ *   the recipient, which is why the list view carries `failed` rather than the text.
+ *
+ * `status` rather than a boolean, because the statuses are the answer: a `failed` or `suppressed` row is
+ * an email nobody read, and a reader that collapsed the log to "yes" would treat it as one they did.
+ *
+ * ## Bounded, and it says when the bound bit
+ *
+ * The log is append-only and unbounded by nature, so the read is capped — and a cap that silently
+ * truncates is the failure mode, not the bound. `truncated` says the cap was reached, the same word
+ * `@pithy-sh/auth`'s bounded sub-lists use. A caller counting rows must read it; a caller asking only
+ * "did anything go out" may ignore it, because a truncated page is still a non-empty one.
+ */
+
+/**
+ * One job as the send-decision reader sees it: the handle, the outcome, and the two instants.
+ *
+ * Derived from `EmailJob` with `.pick()` rather than restated, so the codecs and the field descriptions
+ * come from the one table definition and a column added to the row does not silently appear here.
+ * Re-described because `.pick()` builds a new schema and the top-level description does not follow it.
+ */
+export const SentSummary = EmailJob.pick({ id: true, status: true, createdAt: true, sentAt: true }).describe(
+  "One previously enqueued message, as the caller deciding whether to send another one sees it. No recipient, no subject, no payload, no provider text — the id is the handle into the full record for anyone holding the scope to read it.",
+);
+export type SentSummary = z.output<typeof SentSummary>;
+
+/**
+ * Which messages are being asked about — one of the two indexed axes, and the type admits no third
+ * answer.
+ *
+ * **`(to, template)`** is the original question: has this template already gone to this person. It runs
+ * on `(recipientKey, template, createdAt)`.
+ *
+ * **`correlation`** is the question a template carrying more than one kind of message needs
+ * (pithy-sh/pithy#382): has *this thing* already been said. Six account notices ride one
+ * `operationalNotice` to the same addresses, so the template id cannot separate them and the address is
+ * a proxy for the account only while one person belongs to one account. It runs on
+ * `(correlation, createdAt)`.
+ *
+ * Written as a union rather than three optional fields because the shape a union forbids is the one that
+ * matters: a filter naming *neither* axis is an unbounded scan of every email the project ever queued,
+ * asked on the path that decides whether to send. It cannot be constructed. Both axes together is
+ * allowed and narrows further.
+ */
+export type SentSubject =
+  | {
+      /** The recipient. Matched under `normalizeAddress`, the same rule the row was keyed under. */
+      readonly to: string;
+      /** The template id, exactly. */
+      readonly template: string;
+      /** Optionally narrower still: which of this template's messages. */
+      readonly correlation?: string;
+    }
+  | {
+      /** What the message was about, exactly as the enqueue stated it. */
+      readonly correlation: string;
+      /** Optional here — the correlation already bounds the read. */
+      readonly to?: string;
+      /** Optional here — the correlation already bounds the read. */
+      readonly template?: string;
+    };
+
+/** What `sentSince` asks: a subject, a floor, and a bound. The bound is the only one clamped. */
+export type SentFilter = SentSubject & {
+  /**
+   * The earliest `createdAt` to consider, inclusive.
+   *
+   * Required, with no default. An unbounded question against an append-only send log is a table scan
+   * whose cost grows with the project's age, asked on the path that decides whether to send — and a
+   * default would be this module choosing how far back "already" reaches, which is the caller's
+   * decision and differs per notice.
+   */
+  readonly since: Date;
+  /** How many rows to return, clamped into range. The default is `DEFAULT_PAGE_SIZE`. */
+  readonly limit?: number;
+};
+
+/** What went out, and whether the bound cut the answer short. */
+export interface SentLog {
+  /** The matching jobs, newest first, at most the clamped limit. */
+  items: SentSummary[];
+  /** True when more rows matched than the limit allowed. A count taken off `items` is wrong when this is set. */
+  truncated: boolean;
+}
+
+/**
+ * Every job matching one subject since an instant, newest first.
+ *
+ * The subject is `(to, template)`, or a `correlation`, or both — see {@link SentSubject}. Neither is not
+ * a subject, and the type will not build one.
+ *
+ * **A row that will not parse throws.** It is tempting to skip it and carry on, and it is wrong here in
+ * a way it is not on a listing: this reader's answer decides whether a message goes out. A skipped row
+ * is reported as an email that never went, which means a duplicate send — or, where the caller is
+ * looking for who to send a *correction* to, a correction withheld from exactly the person owed one.
+ * Both failures are silent and neither is recoverable after the fact, so a row this schema cannot read
+ * stops the decision instead of quietly biasing it.
+ */
+export async function sentSince(db: EmailDatabase, filter: SentFilter): Promise<SentLog> {
+  const limit = pageLimit(filter.limit);
+  let query = db
+    .selectFrom("pithyEmailJobs")
+    .select(["id", "status", "createdAt", "sentAt"])
+    .where("createdAt", ">=", filter.since.getTime())
+    .orderBy("createdAt", "desc")
+    .orderBy("id", "desc")
+    // One more than asked for, so "was there more" is answerable without a second count query.
+    .limit(limit + 1);
+
+  // `recipientKey`, never `toAddress`: the row keeps what the caller typed and this is the column every
+  // comparison is against. The index is `(recipientKey, template, createdAt)`.
+  if (filter.to !== undefined) query = query.where("recipientKey", "=", normalizeAddress(filter.to));
+  if (filter.template !== undefined) query = query.where("template", "=", filter.template);
+  // The other indexed axis, `(correlation, createdAt)`. Compared exactly and never with `like`: a prefix
+  // match would make one caller's correlation the ancestor of another's by accident of spelling.
+  if (filter.correlation !== undefined) query = query.where("correlation", "=", filter.correlation);
+
+  const rows = await query.execute();
+
+  const items = rows.slice(0, limit).map((row) => {
+    const parsed = SentSummary.safeParse(row);
+    if (!parsed.success) {
+      throw new InternalError({
+        message: "The send log could not be read.",
+        action: "Inspect pithy_email_jobs for a row this deployment's schema cannot decode.",
+        // The row id only. The values that failed to parse are the row, and the row is somebody's mail.
+        detail: `pithy_email_jobs row '${String(row.id)}' does not satisfy EmailJob: ${parsed.error.issues
+          .map((issue) => `${issue.path.join(".")}: ${issue.code}`)
+          .join("; ")}`,
+      });
+    }
+    return parsed.data;
+  });
+
+  return { items, truncated: rows.length > limit };
+}