@pithy-sh/support 0.1.2 → 0.1.4

package/dist/data/thread.d.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+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"}

package/dist/data/thread.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportAccountLinkSource, SupportChannel, SupportPriority, SupportSentiment, UNCATEGORIZED } from "./enums.js";
+import { z } from "zod";
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/data/thread.ts
+/**
+* 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.
+*/
+const SupportThread = z.object({
+	id: z.string().describe("UUID primary key. Text, not autoincrement, because a thread id reaches a dashboard and an enumerable inbox is an enumerable customer list."),
+	channel: SupportChannel.describe("How this conversation started — `email` at an inbound address, or `app` from a signed-in user. Never rewritten by a later message: the channel a thread opened on is what its account link's provenance follows from, and a thread that changed channel would change what its link means."),
+	inboxAddress: z.string().nullish().describe("The support address this thread arrived on, lowercased. Stored per thread so one Worker can serve several inboxes (support@, security@) and the dashboard can filter by which — and it is the address a reply comes back to. **Null on an `app` thread with no inbound address configured**, which is a supported deployment: a project can collect in-app feedback with no mail set up at all. Never null on an `email` thread, which by definition arrived at one."),
+	subject: z.string().describe("The subject of the message that opened the thread. Later replies never rewrite it — the thread keeps its name."),
+	fromAddress: z.string().describe("The sender's address, lowercased. The join key for the user link, the sender history, and the volume guard — so it is normalized on the way in, once. On an `app` thread it is the authenticated account's own email, read from the account rather than from anything the client sent, which is what lets a reply leave on the existing mail path with nothing new to configure."),
+	fromName: z.string().nullish().describe("The sender's display name from the `From` header, when they had one. Untrusted text; render it escaped."),
+	senderAuthenticated: SQLiteBoolean.describe("Whether the sender was proved to be who they claim. On an `email` thread that means the `From:` header was proved — DMARC passed, or SPF passed on an aligned domain — and **false does not mean forged**, it means unproven, which is the common case for a domain publishing no DMARC policy. On an `app` thread it is always true, and it is true for a stronger reason: there was no header to prove, because `requireAuth()` proved the session before the request reached a handler. It gates the customer link: an unproven sender is never decorated with somebody's real purchase history, because that is what turns a spoofed message into support-driven account takeover."),
+	userId: z.string().nullish().describe("The `pithy_auth_users.id` this sender resolves to, or null when the address belongs to nobody with an account — or when the sender was not authenticated, because an unproven `From:` must not resolve to a real customer. Derived on the mail path, so a customer who signs up later is linked by the next message rather than by a repair; on the app path it is the session's own user id and there is nothing to derive."),
+	accountLinkSource: SupportAccountLinkSource.nullish().describe("How `userId` was established, or null when there is no link. **The column that keeps a session-proven link from reading like a header-inferred one** — `senderAuthenticated` says whether to believe it, this says what was believed. A console rendering the two identically is the failure this exists to prevent, because the same operator action follows from very different evidence."),
+	declaredCategory: z.string().nullish().describe("**What the submitter said this is about** — a claim, made once, by the person writing. Null when nobody said: every `email` thread, and every `app` thread whose client offered no chooser. Written when the thread opens and **never afterwards**: not by a later message, and not by the classifier, which owns `category` and does not know this column exists. That separation is the whole point. A classification is recomputed on every retry, every manual reclassify, and every post-upgrade backfill — so a single column holding both facts loses whichever was written first, and the one an operator most needs is the *disagreement* between them: `declaredCategory: billing` beside `category: bug_report` says the customer thinks they were overcharged and the model thinks the app is broken, and no one column can say that. Validated against the effective taxonomy before it is stored, so this is never a client-writable vocabulary."),
+	category: z.string().describe("**What the classifier made of it** — the current answer, from this project's effective taxonomy, recomputed and never repaired. A plain string rather than an enum because the taxonomy is federated — the valid set is not known until an adopter composes the capability, so it is validated at the classification boundary instead of by the column. Distinct from `declaredCategory` above, which nothing here ever reads or writes."),
+	priority: SupportPriority.describe("The current priority — how fast this thread needs a human."),
+	sentiment: SupportSentiment.describe("The current sentiment — the churn signal."),
+	confidence: z.number().min(0).max(1).nullish().describe("The model's self-reported confidence in the current classification, 0..1. Null until a classification lands. Kept so a low-confidence inbox can be reviewed separately from a confident one."),
+	model: z.string().nullish().describe("The Workers AI model id that produced the current classification. Recorded so a reclassification pass after a model upgrade can tell which rows came from which model — the whole reason reclassification is possible at all."),
+	classifiedAt: SQLiteDate.nullish().describe("When the current classification was written; null until the Workflow has run."),
+	archived: SQLiteBoolean.describe("Done. One shared boolean, not per viewer, because if one person resolves a thread another should not still see it open. The mildest possible coordination state: no transitions to get wrong, nothing can be stuck, and unarchiving undoes a mistake instantly."),
+	archivedAt: SQLiteDate.nullish().describe("When the thread was last archived; null while it is open."),
+	archivedBy: z.string().nullish().describe("The control-plane subject that archived it. Recorded for the dashboard's convenience only — the answer to 'who marked this done' comes from the audit trail, which is why this is not an ownership column."),
+	messageCount: z.number().int().describe("How many messages the thread holds, inbound and outbound together."),
+	firstMessageAt: SQLiteDate.describe("When the thread opened — the receive time of its first message."),
+	lastMessageAt: SQLiteDate.describe("When the thread last moved. The inbox sorts on this, and it is the `receivedAt` half of every composite index and of the pagination cursor."),
+	createdAt: SQLiteDate.describe("When the thread row was created."),
+	updatedAt: SQLiteDate.describe("When the thread row was last written.")
+}).describe("One support conversation in `pithy_support_threads` — derived entirely from the mail below it.");
+/**
+* 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.
+*/
+const UNCLASSIFIED = {
+	category: UNCATEGORIZED,
+	priority: "normal",
+	sentiment: "neutral",
+	confidence: null,
+	model: null,
+	classifiedAt: null
+};
+//#endregion
+export { SupportThread, UNCLASSIFIED };

package/dist/error/errors.d.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+/**
+ * `@pithy-sh/support` throw sugar. The `support/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/media` and
+ * `@pithy-sh/payments`. Runtime code in this package throws one of these, never a plain `new Error`.
+ *
+ * **Keep the public `message` free of anything the sender wrote.** This capability's entire input is
+ * attacker-controlled mail, so an error that echoed a subject line back would turn the error channel
+ * into a reflection surface. Sender text goes in `detail`, which the HTTP codec strips.
+ */
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface SupportErrorArgs {
+    /** Override the public, safe-to-expose message. */
+    message?: string;
+    /** A remediation hint (CLI action line). */
+    action?: string;
+    /** Internal context for logs + audit. Never serialized to clients. */
+    detail?: string;
+    /**
+     * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+     * unlike `action` and `detail` — these cross the boundary with `message`.
+     */
+    params?: MessageParams;
+}
+/** A requested thread, message, or attachment does not exist. */
+export declare class SupportNotFoundError extends PithyError {
+    constructor(args?: SupportErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** A category key or its description failed validation at author time. */
+export declare class SupportInvalidCategoryError extends PithyError {
+    constructor(args?: SupportErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** An inbound message could not be parsed, or carried nothing this capability can store. */
+export declare class SupportUnparseableMessageError extends PithyError {
+    constructor(args?: SupportErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** An inbound message was refused by the volume or size guard before anything was persisted. */
+export declare class SupportRejectedError extends PithyError {
+    constructor(args?: SupportErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** The AI classification step failed, or the binding it needs is absent. */
+export declare class SupportClassificationError extends PithyError {
+    constructor(args?: SupportErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** A reply could not be enqueued — the email capability is absent, or it refused the job. */
+export declare class SupportReplyFailedError extends PithyError {
+    constructor(args?: SupportErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/error/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;;;;;;;;GASG;AAEH,uFAAuF;AACvF,UAAU,gBAAgB;IACxB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,iEAAiE;AACjE,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,YAAY,IAAI,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYrE;CACF;AAED,0EAA0E;AAC1E,qBAAa,2BAA4B,SAAQ,UAAU;IACzD,YAAY,IAAI,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYrE;CACF;AAED,4FAA4F;AAC5F,qBAAa,8BAA+B,SAAQ,UAAU;IAC5D,YAAY,IAAI,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYrE;CACF;AAED,gGAAgG;AAChG,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,YAAY,IAAI,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYrE;CACF;AAED,4EAA4E;AAC5E,qBAAa,0BAA2B,SAAQ,UAAU;IACxD,YAAY,IAAI,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYrE;CACF;AAED,6FAA6F;AAC7F,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,YAAY,IAAI,GAAE,gBAAqB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYrE;CACF"}

package/dist/error/errors.js

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/error/errors.ts
+/** A requested thread, message, or attachment does not exist. */
+var SupportNotFoundError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "support/not_found",
+			status: 404,
+			message: args.message ?? "That support thread does not exist.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** A category key or its description failed validation at author time. */
+var SupportInvalidCategoryError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "support/invalid_category",
+			status: 400,
+			message: args.message ?? "That support category is not valid.",
+			action: args.action ?? "Use a lowercase snake_case key with one instructional sentence describing it.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** An inbound message could not be parsed, or carried nothing this capability can store. */
+var SupportUnparseableMessageError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "support/unparseable_message",
+			status: 400,
+			message: args.message ?? "That message could not be read as email.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** An inbound message was refused by the volume or size guard before anything was persisted. */
+var SupportRejectedError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "support/rejected",
+			status: 429,
+			message: args.message ?? "That message was refused by the inbound guard.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** The AI classification step failed, or the binding it needs is absent. */
+var SupportClassificationError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "support/classification_failed",
+			status: 500,
+			message: args.message ?? "Support classification could not complete.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** A reply could not be enqueued — the email capability is absent, or it refused the job. */
+var SupportReplyFailedError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "support/reply_failed",
+			status: 502,
+			message: args.message ?? "That reply could not be sent.",
+			action: args.action ?? "Add the email capability and provision it, then retry.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+//#endregion
+export { SupportClassificationError, SupportInvalidCategoryError, SupportNotFoundError, SupportRejectedError, SupportReplyFailedError, SupportUnparseableMessageError };

package/dist/http/guards.d.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { MiddlewareHandler } from "hono";
+/**
+ * Support's identity gates: the copied `requireAuth()` its in-app submission routes wear, and the
+ * control-plane gate its management routes take from core's seam.
+ *
+ * **The scope constants moved to `./scopes`** (#315). A management client reads them to render what a
+ * connection may do, and it reads them in a browser — so they cannot live in a module that imports
+ * Hono middleware and `PithyHonoEnv`. The gates stayed here; the names they demand are next door, and
+ * the routes import both.
+ *
+ * ## Two surfaces, and the split is the whole shape of this file
+ *
+ * **The management surface is `control-plane` and default-denied.** It reads and acts on every
+ * customer's private correspondence, so it answers to a credential the adopter issued and to nothing
+ * else. The seam's gate is imported from core rather than copied — core is a hard dependency of every
+ * capability, so importing its gate cannot leave a deployment without one, and with the seam
+ * uncomposed `requireControlPlane` raises `controlplane/not_connected` rather than passing.
+ *
+ * **The submission surface is `bearer`/`session` and is the adopter's own signed-in user.** It exists
+ * because a product with a logged-in user, a session, and a support console should not have to ask
+ * that user to open their mail client — and because the hardest problem on the mail path, proving a
+ * `From:` header, does not exist on a request whose session was already proved.
+ *
+ * **`requireAuth()` never appears on a management route, and `requireControlPlane` never appears on a
+ * submission route.** They are not two strengths of the same gate. A management client holds no
+ * session and owns no account row — core leaves `c.var.auth` null for one deliberately — so stacking
+ * them would deny every legitimate call on both surfaces, permanently, with no credential able to fix
+ * it. What each route may *see* follows from which gate it wears: an operator reads a thread with its
+ * classification and its sender's purchases, and a submitter reads their own words back and nothing
+ * else.
+ */
+/**
+ * Require an authenticated caller — core's `AuthContext` seam, and the gate on every in-app route.
+ *
+ * **Copied from `@pithy-sh/auth`, not imported, and the duplication is deliberate.** Importing it would
+ * make auth a hard dependency, and *a package that imports its authorization from another package
+ * fails open when that package is absent*. Depending on the core seam instead means `c.var.auth` is
+ * simply null with no auth capability composed, and every submission route denies. Failing closed is
+ * not a side effect of the copy; it is the reason for it — and on this capability the thing behind the
+ * gate is somebody's support history.
+ */
+export declare function requireAuth(): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/http/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAU7D"}

package/dist/http/guards.js

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/http/guards.ts
+/**
+* Support's identity gates: the copied `requireAuth()` its in-app submission routes wear, and the
+* control-plane gate its management routes take from core's seam.
+*
+* **The scope constants moved to `./scopes`** (#315). A management client reads them to render what a
+* connection may do, and it reads them in a browser — so they cannot live in a module that imports
+* Hono middleware and `PithyHonoEnv`. The gates stayed here; the names they demand are next door, and
+* the routes import both.
+*
+* ## Two surfaces, and the split is the whole shape of this file
+*
+* **The management surface is `control-plane` and default-denied.** It reads and acts on every
+* customer's private correspondence, so it answers to a credential the adopter issued and to nothing
+* else. The seam's gate is imported from core rather than copied — core is a hard dependency of every
+* capability, so importing its gate cannot leave a deployment without one, and with the seam
+* uncomposed `requireControlPlane` raises `controlplane/not_connected` rather than passing.
+*
+* **The submission surface is `bearer`/`session` and is the adopter's own signed-in user.** It exists
+* because a product with a logged-in user, a session, and a support console should not have to ask
+* that user to open their mail client — and because the hardest problem on the mail path, proving a
+* `From:` header, does not exist on a request whose session was already proved.
+*
+* **`requireAuth()` never appears on a management route, and `requireControlPlane` never appears on a
+* submission route.** They are not two strengths of the same gate. A management client holds no
+* session and owns no account row — core leaves `c.var.auth` null for one deliberately — so stacking
+* them would deny every legitimate call on both surfaces, permanently, with no credential able to fix
+* it. What each route may *see* follows from which gate it wears: an operator reads a thread with its
+* classification and its sender's purchases, and a submitter reads their own words back and nothing
+* else.
+*/
+/**
+* Require an authenticated caller — core's `AuthContext` seam, and the gate on every in-app route.
+*
+* **Copied from `@pithy-sh/auth`, not imported, and the duplication is deliberate.** Importing it would
+* make auth a hard dependency, and *a package that imports its authorization from another package
+* fails open when that package is absent*. Depending on the core seam instead means `c.var.auth` is
+* simply null with no auth capability composed, and every submission route denies. Failing closed is
+* not a side effect of the copy; it is the reason for it — and on this capability the thing behind the
+* gate is somebody's support history.
+*/
+function requireAuth() {
+	return async (c, next) => {
+		if (!c.var.auth) throw new UnauthorizedError({
+			message: "Authentication required.",
+			action: "Sign in and retry with a valid session or bearer token."
+		});
+		await next();
+	};
+}
+//#endregion
+export { requireAuth };

package/dist/http/handlers.d.ts

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { ObjectStore } from "@pithy-sh/storage/src/object/store";
+import type { SupportConfig } from "../config/config";
+import type { SupportCategories } from "../data/categories";
+import type { SupportDatabase } from "../data/tables";
+import { sendReply } from "../reply/send";
+import type { SupportReplySnippets } from "../reply/snippets";
+import type { SupportFlagsResponse, SupportMyThreadResponse, SupportMyThreadsResponse, SupportReclassifiedResponse, SupportReplySentResponse, SupportReplyView, SupportSubmissionResponse, SupportThreadResponse, SupportThreadsResponse, SupportThreadView } from "./responses";
+import type { ArchiveThreadInput, FlagsInput, ListThreadsQuery, MyThreadsQuery, RepliesQuery, ReplyInput, SubmitFeedbackInput } from "./schemas";
+/**
+ * The support handlers — every one of them behind the `control-plane` gate, and every one of them
+ * taking already-validated values.
+ *
+ * Nothing here reads raw request input: the route line carries the contract and the handler takes
+ * typed arguments, which is what lets these be tested without a request at all.
+ */
+/** Everything the handlers need, resolved per request. */
+export interface HandlerDeps {
+    /** The support tables. */
+    db: SupportDatabase;
+    /** The raw `DB` binding — the linkage reads sibling capabilities' tables through it. */
+    d1: D1Database;
+    /** The resolved config. */
+    config: SupportConfig;
+    /** The effective taxonomy. */
+    categories: SupportCategories;
+    /** The effective canned-reply catalog. */
+    snippets: SupportReplySnippets;
+    /** Whether the FTS5 index is composed. */
+    fts: boolean;
+    /** The attachment bucket, when one is bound. */
+    bucket?: R2Bucket;
+    /** The object store attachment URLs are signed through, when credentials are available. */
+    store?: ObjectStore;
+    /** The email capability's env-bound `enqueue`, when email is composed. */
+    enqueue?: Parameters<typeof sendReply>[0]["enqueue"];
+    /** Start a classification for a message. Resolves to whether an instance actually started. */
+    dispatchClassify: (messageId: string) => Promise<boolean>;
+    /** The audit seam. */
+    emit: AuditEmit;
+    /** The request logger. */
+    log: Logger;
+    /** Generate a row id. */
+    newId: () => string;
+    /** Now. */
+    now: () => Date;
+}
+/** List the inbox. */
+export declare function listInbox(deps: HandlerDeps, query: ListThreadsQuery, viewer: string): Promise<SupportThreadsResponse>;
+/** Read one conversation in full. */
+export declare function readConversation(deps: HandlerDeps, threadId: string): Promise<SupportThreadResponse>;
+/** Mark a conversation done, or reopen it. */
+export declare function archiveConversation(deps: HandlerDeps, threadId: string, input: ArchiveThreadInput, viewer: string): Promise<SupportThreadView>;
+/** Answer the customer. */
+export declare function replyToConversation(deps: HandlerDeps, threadId: string, input: ReplyInput, viewer: string): Promise<SupportReplySentResponse>;
+/** Re-run the classifier over a conversation's latest inbound message. */
+export declare function reclassifyConversation(deps: HandlerDeps, threadId: string, viewer: string): Promise<SupportReclassifiedResponse>;
+/** Set one viewer's private flags. */
+export declare function updateFlags(deps: HandlerDeps, threadId: string, input: FlagsInput, viewer: string): Promise<SupportFlagsResponse>;
+/** The canned reply catalog. */
+export declare function listReplies(deps: HandlerDeps, query: RepliesQuery): SupportReplyView[];
+/**
+ * Take an in-app support request from a signed-in user.
+ *
+ * `userId` is a parameter rather than something read out of `input`, and that is the contract this
+ * whole channel rests on: it comes from `c.var.auth`, which `requireAuth()` filled before the route's
+ * validator ran. Nothing in the submitted body names an account, and the schema has no field that
+ * could.
+ *
+ * The configured length bounds are applied here rather than in the schema, for the reason
+ * `schemas.ts` states: a request schema is built once at module load and the adopter's numbers are
+ * resolved per project. This is config-backed resolution, which belongs in a handler — the same rule
+ * that keeps `board()` and `currency()` lookups out of a param schema.
+ */
+export declare function submitFeedbackRequest(deps: HandlerDeps, input: SubmitFeedbackInput, userId: string): Promise<SupportSubmissionResponse>;
+/** List the caller's own in-app conversations. */
+export declare function listMyThreads(deps: HandlerDeps, query: MyThreadsQuery, userId: string): Promise<SupportMyThreadsResponse>;
+/**
+ * Read one of the caller's own conversations.
+ *
+ * The scoping is `readOwnThread`'s `where`, so a thread belonging to somebody else raises the same
+ * `support/not_found` as one that never existed. The projection is `myThreadView`/`myMessageView`,
+ * built from scratch rather than by omitting fields from the operator's — see `views.ts` for why that
+ * distinction is the security boundary rather than a style preference.
+ */
+export declare function readMyThread(deps: HandlerDeps, threadId: string, userId: string): Promise<SupportMyThreadResponse>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/http/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/http/handlers.ts"],"names":[],"mappings":"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"}