@pithy-sh/support 0.1.0

package/src/reply/send.ts

@@ -0,0 +1,322 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import { SupportAuditActions } from "../audit/actions";
+import type { SupportConfig } from "../config/config";
+import { SupportMessage } from "../data/message";
+import { SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE, type SupportDatabase } from "../data/tables";
+import { SupportNotFoundError, SupportReplyFailedError } from "../error/errors";
+import { buildReferencesHeader, replySubject } from "../mime/threading";
+import { indexMessage } from "../store/search";
+
+/**
+ * Sending a reply — through `@pithy-sh/email`'s durable send path, never directly.
+ *
+ * ## Why the reply is composed here and not in the dashboard
+ *
+ * Three things have to be true of an answer, and a dashboard can guarantee none of them. It has to
+ * leave from the adopter's domain carrying the adopter's DKIM, so it is not filtered as a forgery.
+ * It has to be durable and retryable, which is what the email capability's job row and Workflow buy.
+ * And it has to set `In-Reply-To` and `References` correctly — which only the Worker can do, because
+ * only the Worker holds the thread's chain. Implemented dashboard-side, threading breaks in the
+ * customer's mail client and every conversation fragments into one message per answer.
+ *
+ * So the dashboard POSTs a body. That is the entire contract, and it is why the reply route is small.
+ *
+ * ## The sent Message-ID is not ours to know
+ *
+ * Cloudflare assigns the real `Message-ID` at send time and does not tell the enqueuer, so the
+ * outbound row stores `emailJobId` and leaves `mimeMessageId` null. Threading back still works, and
+ * this is the part worth being clear about: when the customer replies, their `References` carries the
+ * whole ancestry — including the *inbound* ids this capability stored itself — so `parentCandidates`
+ * finds the thread through one of those even though it has never seen the id of its own reply.
+ *
+ * ## Storing the answer and sending it are two steps, and one of them is optional
+ *
+ * Everything above describes mail. An `app` thread has a second destination that already exists:
+ * `readOwnThread` hands the submitter every message on their own conversation, outbound ones
+ * included, so an answer stored and never sent is an answer they will read next time they open it.
+ *
+ * That is the whole shape of in-app delivery — the outbound row, the thread counters and the audit
+ * event are written exactly as they are for mail, and only the `enqueue` is skipped. It is taken in
+ * two situations, and they are different in kind:
+ *
+ * - **The adopter chose it.** `reply.deliverInApp` on a project whose mail works perfectly well.
+ *   Email Routing takes over a zone's MX, so a project already running mail on that domain cannot
+ *   receive support replies without disturbing everything else on it — and a fallback conditioned on
+ *   mail being *impossible* is unreachable by exactly the adopter who most wants this.
+ * - **There is nothing to send with.** No address a reply could come back to, or no email capability
+ *   composed at all. Storing the answer beats refusing it, because the person can still read it.
+ *
+ * An `email` thread never takes it. Its sender has no read-back — there is no session, only an
+ * address — so an answer stored there is one nobody would ever see, and a missing reply address on a
+ * mail thread stays the misconfiguration it always was.
+ *
+ * **The two are never rendered the same.** "Sent by email" and "waiting in the app" are different
+ * promises about when somebody will read the answer, and `ReplyResult` is a union rather than an
+ * object with an optional `jobId` so that a console has to say which one it is showing.
+ */
+
+/** What a reply needs, all injectable. */
+export interface ReplyDeps {
+  /** The support tables. */
+  db: SupportDatabase;
+  /** The resolved config. */
+  config: SupportConfig;
+  /**
+   * The email capability's `enqueue`, already bound to the request env. Support never assembles the
+   * send infrastructure — it hands over a recipient, a template id, and a payload.
+   *
+   * **Optional, because a project can compose support without composing email.** Absent, an `app`
+   * thread is answered in the app rather than refused, and only a mail thread has nothing left to
+   * try. The refusal is raised here rather than by the caller so that the one place that knows
+   * whether mail is needed is the one that asks for it.
+   */
+  enqueue?: (input: {
+    to: string;
+    template: string;
+    payload: unknown;
+    replyTo?: string;
+    /** The language to write the shell in — the reporter's, taken off their submission context. */
+    locale?: string;
+    inReplyTo?: string;
+    references?: string;
+  }) => Promise<{ jobId: string }>;
+  /** Whether the full-text index is in use. */
+  fts: boolean;
+  /** The audit seam. */
+  emit: AuditEmit;
+  /** The request logger. */
+  log: Logger;
+  /** Generate a row id. */
+  newId: () => string;
+  /** Now. */
+  now: () => Date;
+}
+
+/** What the operator is sending. */
+export interface ReplyInput {
+  /** The thread being answered. */
+  threadId: string;
+  /** The reply text, as a human wrote and edited it. */
+  body: string;
+  /** Who is answering, signed at the bottom. Optional. */
+  agentName?: string;
+  /** The verified control-plane subject sending it — the audit actor. */
+  viewer: string;
+}
+
+/**
+ * What the reply produced, discriminated on the channel it was delivered over.
+ *
+ * A union rather than one object with an optional `jobId`, because the two outcomes are different
+ * promises about when the customer reads the answer — and an optional field is exactly what lets a
+ * console render "sent" over both of them.
+ */
+export type ReplyResult =
+  | {
+      /** Handed to the email capability's durable send path. */
+      channel: "email";
+      /** The outbound `pithy_support_messages.id`. */
+      messageId: string;
+      /** The `pithy_email_jobs.id` the send was enqueued as. */
+      jobId: string;
+    }
+  | {
+      /** Stored for the submitter to read in the app. No mail was sent, and there is no job. */
+      channel: "app";
+      /** The outbound `pithy_support_messages.id`. */
+      messageId: string;
+    };
+
+/** Send a reply on a thread. */
+export async function sendReply(deps: ReplyDeps, input: ReplyInput): Promise<ReplyResult> {
+  if (!deps.config.reply.enabled) {
+    throw new SupportReplyFailedError({
+      message: "Replying is disabled on this deployment.",
+      action: "Set `reply.enabled` on the support capability in pithy.config.ts, then redeploy.",
+      detail: "support config has reply.enabled = false",
+    });
+  }
+
+  const thread = await deps.db
+    .selectFrom(SUPPORT_THREADS_TABLE)
+    .select(["id", "channel", "subject", "fromAddress", "fromName", "inboxAddress", "messageCount"])
+    .where("id", "=", input.threadId)
+    .executeTakeFirst();
+  if (!thread) throw new SupportNotFoundError({ detail: `no support thread ${input.threadId}` });
+
+  // The parent is the newest *inbound* message: the customer's last word is what an answer answers,
+  // and threading against our own previous reply would chain the conversation to a message whose
+  // real id we never learned.
+  const parent = await deps.db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select(["mimeMessageId", "mimeReferences", "context"])
+    .where("threadId", "=", input.threadId)
+    .where("direction", "=", "inbound")
+    .orderBy("receivedAt", "desc")
+    // Tiebroken on id: two messages can share a millisecond (a redelivery burst, or a fixed clock in
+    // a test), and without it "the latest inbound message" is whichever the database felt like —
+    // so a reclassify or a reply could thread against the wrong parent.
+    .orderBy("id", "desc")
+    .limit(1)
+    .executeTakeFirst();
+
+  /**
+   * The language to answer in: the one the reporter's app was rendering in when they wrote.
+   *
+   * **The customer's, never the agent's.** A reply is composed inside an operator's request, and that
+   * request's negotiated locale is the operator's — so reading `c.var.t` here would answer a Spanish
+   * customer in whatever language the support console happens to be open in. The submission context is
+   * the only thing on this thread that says something about the *reader*, and it is already collected
+   * because a locale-shaped bug is only reproducible in the reporter's locale.
+   *
+   * It moves the shell and not the letter. `supportReply`'s words are the adopter's — a human wrote
+   * them, and a catalog cannot translate a sentence it has never seen — so what follows this tag is the
+   * document's `lang` and `dir` and the footer. That is the honest half, and it is the half that decides
+   * whether an Arabic reply lays out right-to-left.
+   *
+   * Absent on every mail-path message, which is most of them, and absent renders as it always has.
+   */
+  const parentContext = SupportMessage.shape.context.safeParse(parent?.context);
+  const replyLocale = parentContext.success ? (parentContext.data?.locale ?? undefined) : undefined;
+
+  const parentReferences = SupportMessage.shape.mimeReferences.safeParse(parent?.mimeReferences);
+  const chain = parentReferences.success && Array.isArray(parentReferences.data) ? parentReferences.data : [];
+  const references = buildReferencesHeader(chain, parent?.mimeMessageId ?? undefined);
+  const subject = replySubject(thread.subject);
+  const now = deps.now();
+
+  // The customer's answer has to come back to an address this inbox actually claims, or the
+  // conversation ends at the reply. Defaulting to the inbox the thread arrived on is right for every
+  // deployment that has not deliberately configured otherwise.
+  //
+  // **Both can be absent, and only on an `app` thread**: a project collecting in-app feedback with no
+  // mail configured has no address a thread arrived at and none to answer from.
+  const replyTo = deps.config.reply.replyToAddress ?? thread.inboxAddress;
+  const enqueue = deps.enqueue;
+
+  // The one decision in this function. An `app` thread has a second destination — the submitter's own
+  // read-back — so it takes in-app delivery whenever the adopter asked for it, and whenever there is
+  // nothing to send with. An `email` thread has only the one, so a missing address there is still a
+  // misconfiguration to fail on rather than an answer to file where its reader cannot reach it.
+  const deliverable = enqueue !== undefined && replyTo !== null && replyTo !== undefined;
+  const inApp = thread.channel === "app" && (deps.config.reply.deliverInApp || !deliverable);
+
+  // One branch, so that refusing and sending are the same decision. Split into a guard block and a
+  // send block they could drift apart, and the drift would be a reply silently stored on a thread
+  // whose reader has no way to see it.
+  let jobId: string | null = null;
+  if (!inApp) {
+    if (!enqueue) {
+      throw new SupportReplyFailedError({
+        message: "This deployment cannot send mail.",
+        action: "Add the email capability (`pithy add email`) and provision it, then retry.",
+        detail: `thread ${input.threadId} needs a mailed reply and no email capability is composed`,
+      });
+    }
+    if (!replyTo) {
+      // Reachable only on a mail thread now. Refused rather than sent from whatever the email
+      // capability defaults to — a reply the customer cannot answer is worse than a refusal an
+      // operator can read, because it looks like the conversation continued.
+      throw new SupportReplyFailedError({
+        message: "This deployment has no address a reply can come back to.",
+        action: "Set `inboundAddresses` or `reply.replyToAddress` on the support capability, then retry.",
+        detail: `thread ${input.threadId} has no inboxAddress and no reply.replyToAddress is configured`,
+      });
+    }
+    try {
+      const enqueued = await enqueue({
+        to: thread.fromAddress,
+        template: "supportReply",
+        payload: { subject, body: input.body, ...(input.agentName ? { agentName: input.agentName } : {}) },
+        replyTo,
+        locale: replyLocale,
+        inReplyTo: parent?.mimeMessageId ? `<${parent.mimeMessageId}>` : undefined,
+        references: references.length > 0 ? references : undefined,
+      });
+      jobId = enqueued.jobId;
+    } catch (cause) {
+      throw new SupportReplyFailedError({ detail: `enqueue failed for thread ${input.threadId}` }, { cause });
+    }
+  }
+
+  // The outbound row goes in after the enqueue succeeded, so the thread never shows a reply that was
+  // never accepted for sending.
+  const messageId = deps.newId();
+  const message: SupportMessage = {
+    id: messageId,
+    threadId: input.threadId,
+    direction: "outbound",
+    // How the answer actually traveled, which is the whole reason this column is per message rather
+    // than only per thread: one `app` thread can hold a reply that was mailed and a reply that was
+    // stored, and those are different promises about when the person reads them.
+    channel: inApp ? "app" : "email",
+    submittedByUserId: null,
+    context: null,
+    mimeMessageId: null,
+    mimeInReplyTo: parent?.mimeMessageId ?? null,
+    mimeReferences: chain.length > 0 ? chain : null,
+    // No envelope on an in-app answer. `replyTo` may even be set — a project that chose in-app
+    // delivery can have perfectly good mail — but writing it here would claim a send that did not
+    // happen.
+    fromAddress: inApp ? null : replyTo,
+    fromName: null,
+    toAddress: inApp ? null : thread.fromAddress,
+    subject,
+    textBody: input.body,
+    htmlBody: null,
+    emailJobId: jobId,
+    rawKey: null,
+    rawBytes: null,
+    receivedAt: now,
+    createdAt: now,
+  };
+  await deps.db.insertInto(SUPPORT_MESSAGES_TABLE).values(SupportMessage.encode(message)).execute();
+
+  if (deps.fts) {
+    try {
+      await indexMessage(deps.db, { threadId: input.threadId, messageId, subject, body: input.body });
+    } catch (error) {
+      // A search miss, never a lost reply. `reindexThread` is the repair.
+      deps.log.warn("support reply not indexed", { messageId, error });
+    }
+  }
+
+  await deps.db
+    .updateTable(SUPPORT_THREADS_TABLE)
+    .set((eb) => ({
+      messageCount: eb("messageCount", "+", 1),
+      lastMessageAt: now.getTime(),
+      updatedAt: now.getTime(),
+    }))
+    .where("id", "=", input.threadId)
+    .execute();
+
+  // Audited because it leaves under the adopter's domain and their DKIM: to the recipient it is
+  // indistinguishable from the founder writing it, so who actually sent it is a security-relevant
+  // fact with no other record. The body is never in the metadata — the trail is long-lived and
+  // queryable, and a support reply is somebody's private correspondence.
+  //
+  // The same event on both paths, carrying the channel it went out on. A job id it does not have is
+  // the one thing an in-app answer cannot record, and `channel` is what makes its absence readable
+  // rather than a gap.
+  await deps.emit({
+    action: SupportAuditActions.replySent,
+    outcome: "success",
+    actorType: "control-plane",
+    actorId: input.viewer,
+    resourceType: "support_thread",
+    resourceId: input.threadId,
+    metadata: {
+      channel: message.channel,
+      messageId,
+      threaded: Boolean(parent?.mimeMessageId),
+      ...(jobId === null ? {} : { jobId }),
+    },
+  });
+
+  return jobId === null ? { channel: "app", messageId } : { channel: "email", messageId, jobId };
+}

package/src/reply/snippets.ts

@@ -0,0 +1,167 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { SupportInvalidCategoryError } from "../error/errors";
+
+/**
+ * Canned replies — starting points a human picks in the dashboard, edits, and sends.
+ *
+ * ## What these are, and what they are not
+ *
+ * A snippet is **body text**, not an email template. The rendering shell — the adopter's theme, the
+ * HTML and plain-text pair, the threading headers — is the single `supportReply` template in
+ * `@pithy-sh/email`. Adding a second email template per canned reply would put the adopter's
+ * wording in a precompiled Handlebars file that only a release can change, which is exactly backwards
+ * for text somebody wants to reword on a Tuesday.
+ *
+ * So the Worker serves a catalog and **never renders it**. The dashboard shows the list, the operator
+ * picks one, edits it, and posts the finished body to the reply route — which is why the placeholder
+ * tokens below are substituted client-side and this package owns no template engine. A support reply
+ * is a letter a person sent; the machine's only job is to hand them a better blank page.
+ *
+ * ## Federated, like the taxonomy
+ *
+ * Pithy ships a small set keyed to the default categories, and an adopter adds their own with
+ * {@link defineSupportReplies} — the same shape `defineSupportCategories` uses, for the same reason.
+ * A snippet tagged with a category is offered first on a thread the classifier put in that category,
+ * which is the one place the classification does work for a human rather than for a filter.
+ *
+ * The shipped wording is deliberately plain and slightly incomplete: every one of them has a blank
+ * an operator has to fill. A canned reply that could be sent without reading it is how a support
+ * inbox starts insulting people.
+ */
+
+/** The shape a snippet key must take: lowercase `snake_case`, so it is a stable id in a dashboard. */
+const SNIPPET_KEY = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+
+/** How long a snippet body may be. Long enough for a real answer; bounded because it ships in a manifest. */
+const MAX_BODY = 2000;
+
+/**
+ * The tokens a dashboard substitutes before sending. Documented here because they are a contract
+ * between this catalog and whatever renders it, and deliberately few: a placeholder language is a
+ * template engine, and a template engine over untrusted context is a rendering vulnerability.
+ */
+export const SNIPPET_TOKENS = {
+  /** The sender's display name, or their address when the app knows no name. */
+  name: "{{name}}",
+  /** The thread's subject. */
+  subject: "{{subject}}",
+} as const;
+
+/** One canned reply. */
+export const SupportReplySnippet = z
+  .object({
+    label: z
+      .string()
+      .min(1)
+      .max(80)
+      .describe("What the dashboard shows in the picker, e.g. `Refund issued`. A verb phrase, not a category name."),
+    category: z
+      .string()
+      .optional()
+      .describe(
+        "The category this snippet is offered first for. Optional — a snippet with no category is always offered, which is right for the general-purpose ones.",
+      ),
+    body: z
+      .string()
+      .min(1)
+      .max(MAX_BODY)
+      .describe(
+        "The starting text, with `{{name}}` and `{{subject}}` substituted by the dashboard before sending. Written to be edited: every shipped one leaves a blank a human has to fill.",
+      ),
+  })
+  .describe("One canned reply — a starting point a human picks, edits, and sends.");
+export type SupportReplySnippet = z.infer<typeof SupportReplySnippet>;
+
+/** A snippet catalog: key → the snippet. */
+export type SupportReplySnippets = Record<string, SupportReplySnippet>;
+
+/**
+ * The set Pithy ships, keyed to the default categories.
+ *
+ * Six, not sixteen. A picker long enough to need scrolling is one nobody reads, and the ones below
+ * are the replies a solo developer actually writes over and over.
+ */
+export const DEFAULT_SUPPORT_REPLIES = {
+  refund_issued: {
+    label: "Refund issued",
+    category: "billing",
+    body: "Hi {{name}},\n\nI've refunded this — you should see it back on your original payment method within ___ working days.\n\nSorry for the trouble.\n",
+  },
+  billing_explained: {
+    label: "Explain a charge",
+    category: "billing",
+    body: "Hi {{name}},\n\nThat charge is ___. It covers ___.\n\nIf that isn't what you expected, tell me and I'll sort it out.\n",
+  },
+  sign_in_help: {
+    label: "Sign-in help",
+    category: "account_access",
+    body: "Hi {{name}},\n\nI've had a look — ___.\n\nTry signing in again and let me know if it still doesn't work. If the email isn't arriving, check your spam folder, and tell me which address you're using so I can confirm it matches the account.\n",
+  },
+  bug_acknowledged: {
+    label: "Bug acknowledged",
+    category: "bug_report",
+    body: "Hi {{name}},\n\nThanks for reporting this — I've reproduced it and it's a real bug. ___.\n\nI'll follow up here once it's fixed.\n",
+  },
+  feature_noted: {
+    label: "Feature request noted",
+    category: "feature_request",
+    body: "Hi {{name}},\n\nThanks — that's a good idea and I've written it down. I can't promise a date, but ___.\n\nIf you can tell me a bit about how you'd use it, that genuinely helps me prioritize.\n",
+  },
+  need_more_detail: {
+    label: "Ask for more detail",
+    body: "Hi {{name}},\n\nHappy to help with this. Could you tell me ___?\n\nA screenshot or the exact wording of any error would speed this up a lot.\n",
+  },
+} as const satisfies SupportReplySnippets;
+
+/**
+ * Declare an adopter's own canned replies, validated at author time.
+ *
+ * The same shape and the same reasoning as `defineSupportCategories`: a malformed key is a picker
+ * entry that silently never matches, and it should fail where the constant is written.
+ */
+export function defineSupportReplies<const T extends SupportReplySnippets>(snippets: T): T {
+  for (const [key, snippet] of Object.entries(snippets)) {
+    if (!SNIPPET_KEY.test(key)) {
+      throw new SupportInvalidCategoryError({
+        message: `Invalid support reply key: ${key}`,
+        action: "Use a lowercase snake_case key, e.g. `refund_issued`.",
+        detail: `key ${JSON.stringify(key)} does not match ${SNIPPET_KEY}`,
+      });
+    }
+    const parsed = SupportReplySnippet.safeParse(snippet);
+    if (!parsed.success) {
+      throw new SupportInvalidCategoryError({
+        message: `Invalid support reply "${key}".`,
+        action: "Give it a label and a body, and keep the body under 2000 characters.",
+        detail: parsed.error.message,
+      });
+    }
+  }
+  return snippets;
+}
+
+/** The effective catalog: the shipped set, plus the adopter's, theirs winning on a key collision. */
+export function resolveReplies(extra: SupportReplySnippets = {}): SupportReplySnippets {
+  return { ...DEFAULT_SUPPORT_REPLIES, ...defineSupportReplies(extra) };
+}
+
+/**
+ * The catalog as a dashboard consumes it: the snippets for this thread's category first, then the
+ * uncategorized general-purpose ones, then everything else.
+ *
+ * Ordering rather than filtering, deliberately. A classifier that put a refund request in
+ * `bug_report` would otherwise hide the refund snippets from the one person who can tell it was
+ * wrong — the model orders the list, it never restricts it.
+ */
+export function repliesForCategory(
+  snippets: SupportReplySnippets,
+  category: string,
+): Array<SupportReplySnippet & { key: string }> {
+  const entries = Object.entries(snippets).map(([key, snippet]) => ({ key, ...snippet }));
+  const rank = (snippet: SupportReplySnippet): number =>
+    snippet.category === category ? 0 : snippet.category === undefined ? 1 : 2;
+  return entries.sort((a, b) => rank(a) - rank(b) || a.key.localeCompare(b.key));
+}

package/src/secret/registry.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { r2CredentialsRegistry } from "@pithy-sh/storage/src/secret/registry";
+
+/**
+ * The secrets support reads — exactly one, and it is not support's own shape.
+ *
+ * Attachment bytes are written through the R2 binding and served as short-lived signed URLs, and
+ * signing needs an S3 key pair. Rather than declare another credential shape, support declares the
+ * *same* one `@pithy-sh/storage` owns, under its own name, through storage's factory. That is what
+ * lets support point the `ObjectStore` seam at `SUPPORT_BUCKET` while inheriting none of storage's
+ * tables, routes, or key policy — the same arrangement `@pithy-sh/media` already has.
+ *
+ * One factory rather than two hand-written declarations is also what keeps the name safe as a join
+ * key: `aggregateSecretRegistries` allows a name declared twice only when every axis agrees, and two
+ * hand-written copies drift where one factory cannot.
+ */
+
+/** The name support's R2 credential bundle is stored and resolved under, per environment. */
+export const SUPPORT_R2_SECRET = "support-r2-credentials";
+
+/** The support capability's secret-registry slice — aggregated into the shared accessor at startup. */
+export const supportSecretsRegistry = r2CredentialsRegistry(SUPPORT_R2_SECRET);