@pithy-sh/support 0.1.1 → 0.1.3

package/dist/data/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/data/enums.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,uCAAuC;AACvC,eAAO,MAAM,eAAe;;;;EAEoF,CAAC;AACjH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,uEAAuE;AACvE,eAAO,MAAM,gBAAgB;;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,oCAAoC;AACpC,eAAO,MAAM,uBAAuB;;;EAEwE,CAAC;AAC7G,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB;;;EAIlC,CAAC;AACJ,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,SAAS,CAAC"}

package/dist/data/enums.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+//#region src/data/enums.ts
+/**
+* The closed axes of the support model — the ones that are genuinely fixed, as opposed to the
+* taxonomy in `categories.ts`, which is federated because every app has its own vocabulary.
+*
+* Priority and sentiment are not federated on purpose. A category answers *what is this*, and that
+* question has as many answers as there are products. Priority answers *how fast*, and sentiment
+* answers *who is about to churn* — both are questions about the sender, not about the product, so a
+* fourth priority level or a fifth sentiment would describe the same reality with more words.
+*/
+/** How fast a thread needs a human. */
+const SupportPriority = z.enum([
+	"urgent",
+	"normal",
+	"low"
+]).describe("How fast this thread needs a human: `urgent` today, `normal` this week, `low` when there is time.");
+/** How the sender sounds. The churn signal, not a politeness score. */
+const SupportSentiment = z.enum([
+	"angry",
+	"frustrated",
+	"neutral",
+	"positive"
+]).describe("How the sender sounds — the churn signal. `angry` and `frustrated` are the ones worth sorting an inbox by.");
+/** Which way a message traveled. */
+const SupportMessageDirection = z.enum(["inbound", "outbound"]).describe("`inbound` arrived from the customer; `outbound` is a reply this Worker sent on the send path.");
+/**
+* How a message reached this inbox.
+*
+* Closed for the same reason priority is: a channel is a *transport this capability implements*, not a
+* vocabulary an adopter brings — there is no third answer a project could need that the code would not
+* also have to be taught to speak. It is the axis the two halves of the capability differ on, and the
+* differences are real rather than cosmetic: `email` arrives at a public address from an unauthenticated
+* `From:` header, and `app` arrives on a request whose session was already proved.
+*/
+const SupportChannel = z.enum(["email", "app"]).describe("How this arrived: `email` at a configured inbound address, or `app` from a signed-in user of the adopter's own app. The axis the console filters on, and the one the account link's provenance follows from.");
+/**
+* How a thread came to name an account — the provenance of `userId`, and the distinction
+* `inbound/authenticity.ts` spends two hundred lines earning.
+*
+* A `From:` header is an unauthenticated claim, so an email thread's link is a *match on an address
+* anybody could have written*. An in-app submission has no `From:` to spoof: `requireAuth()` proved
+* the session before the handler ran, so the link is the identity rather than a guess about it.
+*
+* **A console must not render the two the same way.** They differ in exactly the situation that
+* matters — deciding whether to act on somebody's billing history — and a single boolean cannot say
+* which one it is looking at. `senderAuthenticated` answers *may we believe this*, and this answers
+* *how did we come to believe it*; the second is what an operator needs when the first is false and
+* there is still a name on the thread.
+*/
+const SupportAccountLinkSource = z.enum(["session", "email_address"]).describe("How this thread's `userId` was established: `session` means an authenticated request proved it, `email_address` means it was matched from the address in a `From:` header. Never equivalent — one is the identity, the other is a lookup on a claim.");
+/**
+* The category every taxonomy carries, whatever else it declares, and the value a classification
+* falls back to.
+*
+* It exists so "the model was unsure" is a first-class answer rather than a guess. A text model will
+* always produce *a* label, and a plausible-sounding invented one silently poisons every filter
+* downstream — so an out-of-taxonomy answer lands here instead.
+*/
+const UNCATEGORIZED = "uncategorized";
+/**
+* The one other category key the code names directly, because a behavior hangs off it: a thread the
+* classifier calls spam is archived on sight when `guard.archiveSpam` is on.
+*
+* Naming it here rather than inline keeps the string in one place — an adopter may reword the
+* *description* the model reads, but the key is the join between the taxonomy and that behavior.
+*/
+const SPAM = "spam";
+//#endregion
+export { SPAM, SupportAccountLinkSource, SupportChannel, SupportMessageDirection, SupportPriority, SupportSentiment, UNCATEGORIZED };

package/dist/data/flag.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * One viewer's private view of one thread, in `pithy_support_thread_flags`.
+ *
+ * The other deliberate exception to "no coordination state", and the milder of the two. `archived` is
+ * shared because done means done; these are **per viewer** because nobody coordinates around them —
+ * whether Ada has read a thread says nothing about whether Grace has, and two people marking the same
+ * thread read is not a conflict. Keeping them in their own table rather than as columns on the thread
+ * is what makes that structural instead of a convention.
+ *
+ * `viewer` is the control-plane subject — the management client's identity, not a Pithy user. There
+ * is no user table behind it and there does not need to be: the value is opaque, and a connection
+ * that goes away simply leaves rows nothing reads.
+ */
+export declare const SupportThreadFlag: z.ZodObject<{
+    id: z.ZodString;
+    threadId: z.ZodString;
+    viewer: z.ZodString;
+    read: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+    snoozedUntil: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
+    createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    updatedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type SupportThreadFlag = z.output<typeof SupportThreadFlag>;
+//# sourceMappingURL=flag.d.ts.map

package/dist/data/flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag.d.ts","sourceRoot":"","sources":["../../src/data/flag.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAgB0E,CAAC;AACzG,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/data/flag.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/data/flag.ts
+/**
+* One viewer's private view of one thread, in `pithy_support_thread_flags`.
+*
+* The other deliberate exception to "no coordination state", and the milder of the two. `archived` is
+* shared because done means done; these are **per viewer** because nobody coordinates around them —
+* whether Ada has read a thread says nothing about whether Grace has, and two people marking the same
+* thread read is not a conflict. Keeping them in their own table rather than as columns on the thread
+* is what makes that structural instead of a convention.
+*
+* `viewer` is the control-plane subject — the management client's identity, not a Pithy user. There
+* is no user table behind it and there does not need to be: the value is opaque, and a connection
+* that goes away simply leaves rows nothing reads.
+*/
+const SupportThreadFlag = z.object({
+	id: z.string().describe("UUID primary key."),
+	threadId: z.string().describe("The `pithy_support_threads.id` these flags apply to."),
+	viewer: z.string().describe("The control-plane subject whose view this is. Unique together with `threadId`, so a viewer has exactly one row per thread and marking read twice is an upsert rather than a second row."),
+	read: SQLiteBoolean.describe("Whether this viewer has read the thread."),
+	snoozedUntil: SQLiteDate.nullish().describe("Hide the thread from this viewer's inbox until this moment. Null means not snoozed. A time rather than a boolean, so a snooze expires on its own and nothing has to sweep."),
+	createdAt: SQLiteDate.describe("When the flag row was created."),
+	updatedAt: SQLiteDate.describe("When the flag row was last written.")
+}).describe("One viewer's read/snooze state for one thread — private, uncoordinated, and safe to lose.");
+//#endregion
+export { SupportThreadFlag };

package/dist/data/message.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/**
+ * What the app knows about the moment a report was written, and the user did not have to type.
+ *
+ * A bug report without the screen, the build, and the environment is a round trip — the first reply is
+ * always "which version, and where were you?". The app already holds all three, so asking a human to
+ * retype them is the kind of friction this channel exists to remove.
+ *
+ * **It is a closed object, and unknown keys are refused rather than stripped.** This is a capability,
+ * not a telemetry pipe: the risk of an open bag is that an adopter passes their whole client state
+ * through it and quietly lands a customer's data in a support inbox that a console renders and an
+ * operator reads. A closed set means a field that is not here cannot be posted by accident, and a
+ * refusal says so at the boundary rather than silently dropping what somebody believed they sent.
+ * Every field is bounded, because every one of them is a string a client chose.
+ */
+export declare const SupportSubmissionContext: z.ZodObject<{
+    screen: z.ZodOptional<z.ZodString>;
+    appVersion: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SupportSubmissionContext = z.output<typeof SupportSubmissionContext>;
+/** The `References` header, split into ids. A JSON column so the chain stays a list rather than a string to re-split. */
+export declare const SupportReferenceIds: z.ZodArray<z.ZodString>;
+export type SupportReferenceIds = z.output<typeof SupportReferenceIds>;
+/**
+ * One message in `pithy_support_messages` — inbound mail as it arrived, or a reply as it went out.
+ *
+ * **The raw MIME is kept immutable in R2 and never rewritten.** `textBody`/`htmlBody` are a derived,
+ * sanitized rendering of it, so a parser bug, a sanitizer change, or a reclassification pass can all
+ * be re-run from the bytes that actually arrived. Storing only the parsed form would make the parse a
+ * one-way decision taken at the worst possible moment — inside an `email()` handler with a CPU budget.
+ *
+ * `mimeMessageId` carries a **unique index**, and that is the idempotency anchor: Email Routing can
+ * deliver the same message twice, and the second delivery must be a no-op rather than a duplicate.
+ * SQLite permits repeated `NULL`s in a unique index, so a message that arrived without a `Message-ID`
+ * (rare, and always a sign of something hand-rolled) still stores instead of colliding.
+ */
+export declare const SupportMessage: z.ZodObject<{
+    id: z.ZodString;
+    threadId: z.ZodString;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    channel: z.ZodEnum<{
+        app: "app";
+        email: "email";
+    }>;
+    submittedByUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        screen: z.ZodOptional<z.ZodString>;
+        appVersion: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>, z.ZodObject<{
+        screen: z.ZodOptional<z.ZodString>;
+        appVersion: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    mimeMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mimeInReplyTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mimeReferences: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodArray<z.ZodString>>>>;
+    fromAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fromName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    toAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    subject: z.ZodString;
+    textBody: z.ZodString;
+    htmlBody: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    emailJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    rawKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    rawBytes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    receivedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type SupportMessage = z.output<typeof SupportMessage>;
+//# sourceMappingURL=message.d.ts.map

package/dist/data/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/data/message.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB;;;;;;kBA2DlC,CAAC;AACJ,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,yHAAyH;AACzH,eAAO,MAAM,mBAAmB,yBAEoF,CAAC;AACrH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwHvB,CAAC;AACL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/data/message.js

@@ -0,0 +1,84 @@
+import { SupportChannel, SupportMessageDirection } from "./enums.js";
+import { z } from "zod";
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+//#region src/data/message.ts
+/**
+* What the app knows about the moment a report was written, and the user did not have to type.
+*
+* A bug report without the screen, the build, and the environment is a round trip — the first reply is
+* always "which version, and where were you?". The app already holds all three, so asking a human to
+* retype them is the kind of friction this channel exists to remove.
+*
+* **It is a closed object, and unknown keys are refused rather than stripped.** This is a capability,
+* not a telemetry pipe: the risk of an open bag is that an adopter passes their whole client state
+* through it and quietly lands a customer's data in a support inbox that a console renders and an
+* operator reads. A closed set means a field that is not here cannot be posted by accident, and a
+* refusal says so at the boundary rather than silently dropping what somebody believed they sent.
+* Every field is bounded, because every one of them is a string a client chose.
+*/
+const SupportSubmissionContext = z.object({
+	screen: z.string().min(1).max(120).optional().describe("Where in the app they were — a route, a screen name, whatever the app calls it. The single most useful field, because it turns 'the button does nothing' into a place to look."),
+	appVersion: z.string().min(1).max(64).optional().describe("The build the report came from. Answers 'is this already fixed' without a round trip, which is the whole reason a bug report asks for it."),
+	platform: z.string().min(1).max(64).optional().describe("The client the app is running as — `ios`, `android`, `web`, or whatever the adopter's own build calls itself. Free text rather than an enum: the set of clients is the adopter's, not this capability's."),
+	environment: z.string().min(1).max(32).optional().describe("Which environment the client was pointed at. A report from staging read as production is a bug hunted in the wrong database, and the client is the only thing that knows."),
+	locale: z.string().min(1).max(32).optional().describe("The locale the app was rendering in. Carried because a whole class of reports — a date a day out, a currency in the wrong place, text that overflows — is only reproducible in the reporter's locale. Not validated as a tag here: see `enqueueEmail`, which normalizes it before it reaches a column that is.")
+}).strict().describe("The bounded context an app supplies with a submission, so a bug report arrives with the facts its first reply would otherwise have to ask for.");
+/** The `References` header, split into ids. A JSON column so the chain stays a list rather than a string to re-split. */
+const SupportReferenceIds = z.array(z.string().describe("One RFC 5322 message id from the `References` chain, without its angle brackets.")).describe("The `References` chain, oldest first — the thread's ancestry as the sender's mail client recorded it.");
+/**
+* One message in `pithy_support_messages` — inbound mail as it arrived, or a reply as it went out.
+*
+* **The raw MIME is kept immutable in R2 and never rewritten.** `textBody`/`htmlBody` are a derived,
+* sanitized rendering of it, so a parser bug, a sanitizer change, or a reclassification pass can all
+* be re-run from the bytes that actually arrived. Storing only the parsed form would make the parse a
+* one-way decision taken at the worst possible moment — inside an `email()` handler with a CPU budget.
+*
+* `mimeMessageId` carries a **unique index**, and that is the idempotency anchor: Email Routing can
+* deliver the same message twice, and the second delivery must be a no-op rather than a duplicate.
+* SQLite permits repeated `NULL`s in a unique index, so a message that arrived without a `Message-ID`
+* (rare, and always a sign of something hand-rolled) still stores instead of colliding.
+*/
+const SupportMessage = z.object({
+	id: z.string().describe("UUID primary key for this message row — Pithy's id, not the sender's."),
+	threadId: z.string().describe("The `pithy_support_threads.id` this message belongs to."),
+	direction: SupportMessageDirection.describe("Which way this message traveled."),
+	channel: SupportChannel.describe("How this message traveled, which on an outbound row is **how the answer was delivered**: `email` means it was handed to `@pithy-sh/email`'s durable send path, `app` means it was stored for the submitter to read in the app and no mail was sent. Per message rather than only per thread, because the two genuinely differ — one `app` thread can hold an answer that was mailed and an answer that was not, and those are different promises about when somebody will read them."),
+	submittedByUserId: z.string().nullish().describe("The authenticated `pithy_auth_users.id` that posted this message from inside the app. Null on every mail-path message and on every outbound reply. Taken from the request's session and **never** from anything the client sent — it is the identity, so it is also what the per-account submission bound counts."),
+	context: sqliteJson(SupportSubmissionContext).nullish().describe("The bounded context the app supplied — screen, build, platform, environment, locale. Null on every mail-path message, and on an app submission that declared none."),
+	mimeMessageId: z.string().nullish().describe("The RFC 5322 `Message-ID`, without angle brackets. Uniquely indexed, so a redelivered message is dropped rather than duplicated. Null when the sender omitted one."),
+	mimeInReplyTo: z.string().nullish().describe("The `In-Reply-To` id, without angle brackets — the direct parent. The first key threading tries, because it names exactly one message."),
+	mimeReferences: sqliteJson(SupportReferenceIds).nullish().describe("The `References` chain as a JSON column. Threading falls back to it when `In-Reply-To` names nothing we hold, which is what keeps a conversation together across a client that rewrites the subject."),
+	fromAddress: z.string().nullish().describe("The address this message was sent from, lowercased. **Null exactly on an answer delivered in the app**, which left no envelope — there is no address a reply that was never mailed came from, and putting the deployment's own address there would claim a send that did not happen. Never null on anything that traveled by mail, and never present on anything that did not. Checked on the object, both ways, so it is a rule rather than a note."),
+	fromName: z.string().nullish().describe("The sender's display name. Untrusted text; render it escaped."),
+	toAddress: z.string().nullish().describe("The address this message was addressed to, lowercased. **Null on an app submission to a project with no inbound address configured** — there was no envelope, and inventing one would put a string nothing can deliver to into the column the idempotency index keys on. Never null on a mail-path message."),
+	subject: z.string().describe("This message's own subject line, which may differ from the thread's."),
+	textBody: z.string().describe("The plain-text body, or a text rendering of an HTML-only message. Always present, because the classifier reads this and a model should never be handed markup."),
+	htmlBody: z.string().nullish().describe("The HTML body **after sanitization** — scripts, event handlers, styles, frames, and remote-loading attributes removed. Null when the message carried no HTML. The raw original is still in R2 if the sanitizer ever needs re-running."),
+	emailJobId: z.string().nullish().describe("The `pithy_email_jobs.id` this message was enqueued as. **Present exactly when `direction` is `outbound` and `channel` is `email`**, and null everywhere else — it is the join to the job, never the way to ask whether an answer went out. That question is `channel`'s, because a null here would otherwise mean both 'this arrived' and 'this was delivered in the app', and a client would have to consult `direction` to tell them apart. It is the *job* id rather than the sent `Message-ID` deliberately: Cloudflare assigns the real id at send time and never tells the enqueuer, so a column claiming to hold it would be null exactly when somebody needed it."),
+	rawKey: z.string().nullish().describe("The R2 object key holding the immutable raw MIME. Null only when the bucket binding was absent at ingest, which is a degraded mode rather than a normal one."),
+	rawBytes: z.number().int().nullish().describe("The raw message's size in bytes, as received."),
+	receivedAt: SQLiteDate.describe("When this Worker received the message — our clock, never the sender's `Date` header, which is attacker-controlled and would let anyone place themselves at the top of an inbox."),
+	createdAt: SQLiteDate.describe("When the message row was written.")
+}).describe("One message in `pithy_support_messages` — the derived rendering of mail whose raw form lives in R2.").check((ctx) => {
+	const row = ctx.value;
+	const mailed = row.direction === "outbound" && row.channel === "email";
+	if ((row.emailJobId !== null && row.emailJobId !== void 0) === mailed) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["emailJobId"],
+		message: mailed ? "An outbound `email` message must carry the `emailJobId` it was enqueued as. The row is written after the enqueue is accepted, so one without a job id is a reply nothing was ever asked to send." : "Only an outbound `email` message carries an `emailJobId`. An answer delivered in the app was never enqueued, and an inbound message was never sent — a job id on either makes the column mean something other than the job it names."
+	});
+}).check((ctx) => {
+	const row = ctx.value;
+	const inApp = row.direction === "outbound" && row.channel === "app";
+	if ((row.fromAddress !== null && row.fromAddress !== void 0) === !inApp) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["fromAddress"],
+		message: inApp ? "An answer delivered in the app has no `fromAddress`. It left no envelope, so an address there names a send that did not happen." : "Everything but an answer delivered in the app carries the `fromAddress` it came from or went out as. Without one there is no address to reply to."
+	});
+});
+//#endregion
+export { SupportMessage, SupportReferenceIds, SupportSubmissionContext };

package/dist/data/tables.d.ts

@@ -0,0 +1,160 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import { type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+/**
+ * The support tables. Keys are camelCase; `CamelCasePlugin` snake-cases them to the `pithy_support_*`
+ * SQL, so query code in this package never types the prefix and never types an underscore.
+ */
+/** Conversations. `pithy_support_threads`. */
+export declare const SUPPORT_THREADS_TABLE = "pithySupportThreads";
+/** Messages, inbound and outbound. `pithy_support_messages`. */
+export declare const SUPPORT_MESSAGES_TABLE = "pithySupportMessages";
+/** Attachment metadata. `pithy_support_attachments`. */
+export declare const SUPPORT_ATTACHMENTS_TABLE = "pithySupportAttachments";
+/** Append-only classification history. `pithy_support_classifications`. */
+export declare const SUPPORT_CLASSIFICATIONS_TABLE = "pithySupportClassifications";
+/** Per-viewer read/snooze state. `pithy_support_thread_flags`. */
+export declare const SUPPORT_FLAGS_TABLE = "pithySupportThreadFlags";
+/**
+ * The FTS5 full-text index. Not a Kysely table and deliberately not in {@link supportTables}: it is a
+ * virtual table with no Zod schema and no rows of its own worth typing, reached through raw `sql`
+ * from `store/search.ts` alone.
+ *
+ * Named in snake_case because nothing translates it — `CamelCasePlugin` rewrites identifiers Kysely
+ * builds, and every statement touching this one is written by hand.
+ */
+export declare const SUPPORT_SEARCH_TABLE = "pithy_support_search";
+/** The table map the capability contributes to the app database. */
+export declare const supportTables: {
+    pithySupportThreads: z.ZodObject<{
+        id: z.ZodString;
+        channel: z.ZodEnum<{
+            app: "app";
+            email: "email";
+        }>;
+        inboxAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        subject: z.ZodString;
+        fromAddress: z.ZodString;
+        fromName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        senderAuthenticated: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        accountLinkSource: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            email_address: "email_address";
+            session: "session";
+        }>>>;
+        declaredCategory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        category: z.ZodString;
+        priority: z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            urgent: "urgent";
+        }>;
+        sentiment: z.ZodEnum<{
+            angry: "angry";
+            frustrated: "frustrated";
+            neutral: "neutral";
+            positive: "positive";
+        }>;
+        confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        classifiedAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
+        archived: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+        archivedAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
+        archivedBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        messageCount: z.ZodNumber;
+        firstMessageAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+        lastMessageAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+        createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+        updatedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    }, z.core.$strip>;
+    pithySupportMessages: z.ZodObject<{
+        id: z.ZodString;
+        threadId: z.ZodString;
+        direction: z.ZodEnum<{
+            inbound: "inbound";
+            outbound: "outbound";
+        }>;
+        channel: z.ZodEnum<{
+            app: "app";
+            email: "email";
+        }>;
+        submittedByUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        context: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            screen: z.ZodOptional<z.ZodString>;
+            appVersion: z.ZodOptional<z.ZodString>;
+            platform: z.ZodOptional<z.ZodString>;
+            environment: z.ZodOptional<z.ZodString>;
+            locale: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>, z.ZodObject<{
+            screen: z.ZodOptional<z.ZodString>;
+            appVersion: z.ZodOptional<z.ZodString>;
+            platform: z.ZodOptional<z.ZodString>;
+            environment: z.ZodOptional<z.ZodString>;
+            locale: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>>;
+        mimeMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mimeInReplyTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mimeReferences: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodArray<z.ZodString>>>>;
+        fromAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fromName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        toAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        subject: z.ZodString;
+        textBody: z.ZodString;
+        htmlBody: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        emailJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        rawKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        rawBytes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        receivedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+        createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    }, z.core.$strip>;
+    pithySupportAttachments: z.ZodObject<{
+        id: z.ZodString;
+        messageId: z.ZodString;
+        threadId: z.ZodString;
+        filename: z.ZodString;
+        contentType: z.ZodString;
+        size: z.ZodNumber;
+        sha256: z.ZodString;
+        storageKey: z.ZodString;
+        contentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        inline: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+        createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    }, z.core.$strip>;
+    pithySupportClassifications: z.ZodObject<{
+        id: z.ZodString;
+        threadId: z.ZodString;
+        messageId: z.ZodString;
+        category: z.ZodString;
+        priority: z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            urgent: "urgent";
+        }>;
+        sentiment: z.ZodEnum<{
+            angry: "angry";
+            frustrated: "frustrated";
+            neutral: "neutral";
+            positive: "positive";
+        }>;
+        confidence: z.ZodNumber;
+        model: z.ZodString;
+        createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    }, z.core.$strip>;
+    pithySupportThreadFlags: z.ZodObject<{
+        id: z.ZodString;
+        threadId: z.ZodString;
+        viewer: z.ZodString;
+        read: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+        snoozedUntil: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
+        createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+        updatedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    }, z.core.$strip>;
+};
+/** The support tables, as a type. */
+export type SupportTables = typeof supportTables;
+/** The typed Kysely view over the support tables. Carries `CamelCasePlugin`. */
+export type SupportDatabase = Kysely<DatabaseSchema<SupportTables>>;
+/** Build the support database from a `DB` binding. */
+export declare function supportDatabase(d1: D1Database): SupportDatabase;
+//# sourceMappingURL=tables.d.ts.map

package/dist/data/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAO7B;;;GAGG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAC3D,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAC7D,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AACnE,2EAA2E;AAC3E,eAAO,MAAM,6BAA6B,gCAAgC,CAAC;AAC3E,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,oEAAoE;AACpE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMa,CAAC;AAExC,qCAAqC;AACrC,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAEjD,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC;AAEpE,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,EAAE,EAAE,UAAU,GAAG,eAAe,CAE/D"}

package/dist/data/tables.js

@@ -0,0 +1,44 @@
+import { SupportAttachment } from "./attachment.js";
+import { SupportClassification } from "./classification.js";
+import { SupportThreadFlag } from "./flag.js";
+import { SupportMessage } from "./message.js";
+import { SupportThread } from "./thread.js";
+import { createDatabase } from "@pithy-sh/core/src/data/db";
+//#region src/data/tables.ts
+/**
+* The support tables. Keys are camelCase; `CamelCasePlugin` snake-cases them to the `pithy_support_*`
+* SQL, so query code in this package never types the prefix and never types an underscore.
+*/
+/** Conversations. `pithy_support_threads`. */
+const SUPPORT_THREADS_TABLE = "pithySupportThreads";
+/** Messages, inbound and outbound. `pithy_support_messages`. */
+const SUPPORT_MESSAGES_TABLE = "pithySupportMessages";
+/** Attachment metadata. `pithy_support_attachments`. */
+const SUPPORT_ATTACHMENTS_TABLE = "pithySupportAttachments";
+/** Append-only classification history. `pithy_support_classifications`. */
+const SUPPORT_CLASSIFICATIONS_TABLE = "pithySupportClassifications";
+/** Per-viewer read/snooze state. `pithy_support_thread_flags`. */
+const SUPPORT_FLAGS_TABLE = "pithySupportThreadFlags";
+/**
+* The FTS5 full-text index. Not a Kysely table and deliberately not in {@link supportTables}: it is a
+* virtual table with no Zod schema and no rows of its own worth typing, reached through raw `sql`
+* from `store/search.ts` alone.
+*
+* Named in snake_case because nothing translates it — `CamelCasePlugin` rewrites identifiers Kysely
+* builds, and every statement touching this one is written by hand.
+*/
+const SUPPORT_SEARCH_TABLE = "pithy_support_search";
+/** The table map the capability contributes to the app database. */
+const supportTables = {
+	[SUPPORT_THREADS_TABLE]: SupportThread,
+	[SUPPORT_MESSAGES_TABLE]: SupportMessage,
+	[SUPPORT_ATTACHMENTS_TABLE]: SupportAttachment,
+	[SUPPORT_CLASSIFICATIONS_TABLE]: SupportClassification,
+	[SUPPORT_FLAGS_TABLE]: SupportThreadFlag
+};
+/** Build the support database from a `DB` binding. */
+function supportDatabase(d1) {
+	return createDatabase(d1, supportTables);
+}
+//#endregion
+export { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_SEARCH_TABLE, SUPPORT_THREADS_TABLE, supportDatabase, supportTables };

package/dist/data/thread.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/**
+ * One conversation in `pithy_support_threads` — the row the inbox is a list of.
+ *
+ * **Everything on it is derived from immutable inbound mail.** The classification is recomputed, never
+ * repaired; the user link is a lookup, not a decision; the counters are facts about the messages
+ * below. There is no assignee and no status, because a status field is a state machine and a state
+ * machine attracts SLAs, escalation, and reporting — which is a ticketing product and explicitly not
+ * this. The two exceptions are deliberate and named: `archived` (one shared boolean meaning done) and
+ * the per-viewer flags, which live in their own table because nobody coordinates around them.
+ *
+ * The classification axes are **denormalized onto the thread** rather than joined from
+ * `pithy_support_classifications`. The whole dashboard interaction is "newest first, filtered by
+ * category and priority and archived", and that is a composite-index workload — a join to find the
+ * latest classification per thread would make the one query this table exists to serve the expensive
+ * one. The classification table keeps the history; this keeps the answer.
+ */
+export declare const SupportThread: z.ZodObject<{
+    id: z.ZodString;
+    channel: z.ZodEnum<{
+        app: "app";
+        email: "email";
+    }>;
+    inboxAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    subject: z.ZodString;
+    fromAddress: z.ZodString;
+    fromName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    senderAuthenticated: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+    userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    accountLinkSource: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        email_address: "email_address";
+        session: "session";
+    }>>>;
+    declaredCategory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category: z.ZodString;
+    priority: z.ZodEnum<{
+        low: "low";
+        normal: "normal";
+        urgent: "urgent";
+    }>;
+    sentiment: z.ZodEnum<{
+        angry: "angry";
+        frustrated: "frustrated";
+        neutral: "neutral";
+        positive: "positive";
+    }>;
+    confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    classifiedAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
+    archived: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+    archivedAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
+    archivedBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    messageCount: z.ZodNumber;
+    firstMessageAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    lastMessageAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    updatedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type SupportThread = z.output<typeof SupportThread>;
+/**
+ * What a brand-new thread's classification columns hold before the Workflow has run.
+ *
+ * **`declaredCategory` is deliberately not in here**, and the omission is load-bearing rather than an
+ * oversight. This object is the set of columns the classifier owns — `runClassification` overwrites
+ * every one of them on each run — so a submitter's claim listed among them would be erased by the
+ * first classification and by every retry after it. It is set beside this spread, from the submission,
+ * and nothing on the classification path names it.
+ */
+export declare const UNCLASSIFIED: {
+    readonly category: "uncategorized";
+    readonly priority: "normal";
+    readonly sentiment: "neutral";
+    readonly confidence: null;
+    readonly model: null;
+    readonly classifiedAt: null;
+};
+//# sourceMappingURL=thread.d.ts.map

package/dist/data/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/data/thread.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4FmF,CAAC;AAC9G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;uBAEb,QAAQ;wBACP,SAAS;;;;CAOrB,CAAC"}