@pithy-sh/support 0.1.2 → 0.1.4

package/dist/http/handlers.js

@@ -0,0 +1,250 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportClassificationError, SupportNotFoundError } from "../error/errors.js";
+import { repliesForCategory } from "../reply/snippets.js";
+import { attachmentUrl } from "../attachment/store.js";
+import { SupportAuditActions } from "../audit/actions.js";
+import { resolveSenderContext, resolveSubmitterAccount, resolveSubmitterContext } from "../link/sender.js";
+import { sendReply } from "../reply/send.js";
+import { listOwnThreads, listThreads, readOwnThread, readThread, setArchived, setFlags } from "../store/threads.js";
+import { decodeBase64 } from "../submission/encoding.js";
+import { submitFeedback } from "../submission/submit.js";
+import { latestInboundMessageId } from "../workflows/classify.js";
+import { listedThreadView, messageView, myMessageView, myThreadView, senderView, threadView } from "./views.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/http/handlers.ts
+/** List the inbox. */
+async function listInbox(deps, query, viewer) {
+	const page = await listThreads(deps.db, {
+		archived: query.archived === "true",
+		category: query.category,
+		declaredCategory: query.declaredCategory,
+		priority: query.priority,
+		sentiment: query.sentiment,
+		channel: query.channel,
+		inbox: query.inbox,
+		q: query.q,
+		cursor: query.cursor,
+		limit: query.limit
+	}, {
+		fts: deps.fts,
+		viewer,
+		now: deps.now(),
+		log: deps.log
+	});
+	return {
+		threads: page.threads.map(listedThreadView),
+		nextCursor: page.nextCursor
+	};
+}
+/**
+* Present an attachment.
+*
+* The `storageKey` is **never** in the response. It is server-derived and opaque precisely so a
+* client cannot name an object or guess the one beside it, and echoing it back would hand that
+* capability away for no benefit — a client cannot use a key for anything except guessing.
+*/
+async function presentAttachments(deps, attachments) {
+	return Promise.all(attachments.map(async (attachment) => {
+		let url = null;
+		if (deps.store) try {
+			url = await attachmentUrl(deps.store, attachment.storageKey);
+		} catch (error) {
+			deps.log.warn("support attachment URL not signed", {
+				attachmentId: attachment.id,
+				error
+			});
+		}
+		return {
+			id: attachment.id,
+			filename: attachment.filename,
+			contentType: attachment.contentType,
+			size: attachment.size,
+			sha256: attachment.sha256,
+			inline: attachment.inline,
+			url
+		};
+	}));
+}
+/** Read one conversation in full. */
+async function readConversation(deps, threadId) {
+	const detail = await readThread(deps.db, threadId);
+	const [attachments, sender] = await Promise.all([presentAttachments(deps, detail.attachments), detail.thread.accountLinkSource === "session" && detail.thread.userId ? resolveSubmitterContext(deps.d1, detail.thread.userId, deps.now()) : resolveSenderContext(deps.d1, detail.thread.fromAddress, deps.now(), { authenticated: detail.thread.senderAuthenticated })]);
+	return {
+		thread: threadView(detail.thread),
+		messages: detail.messages.map(messageView),
+		attachments,
+		sender: senderView(sender),
+		replies: repliesForCategory(deps.snippets, detail.thread.category)
+	};
+}
+/** Mark a conversation done, or reopen it. */
+async function archiveConversation(deps, threadId, input, viewer) {
+	const thread = await setArchived(deps.db, threadId, input.archived, viewer, deps.now());
+	await deps.emit({
+		action: input.archived ? SupportAuditActions.threadArchived : SupportAuditActions.threadUnarchived,
+		outcome: "success",
+		actorType: "control-plane",
+		actorId: viewer,
+		resourceType: "support_thread",
+		resourceId: threadId,
+		metadata: { archived: input.archived }
+	});
+	return threadView(thread);
+}
+/** Answer the customer. */
+async function replyToConversation(deps, threadId, input, viewer) {
+	return sendReply({
+		db: deps.db,
+		config: deps.config,
+		enqueue: deps.enqueue,
+		fts: deps.fts,
+		emit: deps.emit,
+		log: deps.log,
+		newId: deps.newId,
+		now: deps.now
+	}, {
+		threadId,
+		body: input.body,
+		agentName: input.agentName,
+		viewer
+	});
+}
+/** Re-run the classifier over a conversation's latest inbound message. */
+async function reclassifyConversation(deps, threadId, viewer) {
+	const messageId = await latestInboundMessageId(deps.db, threadId);
+	if (!messageId) throw new SupportNotFoundError({
+		message: "That conversation has nothing to classify.",
+		detail: `thread ${threadId} has no inbound message`
+	});
+	if (!await deps.dispatchClassify(messageId)) throw new SupportClassificationError({
+		message: "Classification is not available on this deployment.",
+		action: "Run `pithy support provision` to deploy the classification worker, then retry.",
+		detail: `the SUPPORT_CLASSIFY workflow binding is absent, so no instance was started`
+	});
+	await deps.emit({
+		action: SupportAuditActions.threadReclassified,
+		outcome: "success",
+		actorType: "control-plane",
+		actorId: viewer,
+		resourceType: "support_thread",
+		resourceId: threadId,
+		metadata: { messageId }
+	});
+	return { messageId };
+}
+/** Set one viewer's private flags. */
+async function updateFlags(deps, threadId, input, viewer) {
+	await setFlags(deps.db, {
+		threadId,
+		viewer,
+		read: input.read,
+		snoozedUntil: input.snoozedUntil === void 0 ? void 0 : input.snoozedUntil ? new Date(input.snoozedUntil) : null,
+		newId: deps.newId,
+		now: deps.now()
+	});
+	return { ok: true };
+}
+/** The canned reply catalog. */
+function listReplies(deps, query) {
+	return repliesForCategory(deps.snippets, query.category ?? "");
+}
+/**
+* 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.
+*/
+async function submitFeedbackRequest(deps, input, userId) {
+	const bounds = deps.config.submission;
+	if (input.subject.length > bounds.maxSubjectChars) throw new ValidationError({
+		message: `A subject may be at most ${bounds.maxSubjectChars} characters.`,
+		action: "Shorten the subject and try again.",
+		detail: `submitted subject is ${input.subject.length} characters, over the ${bounds.maxSubjectChars} bound`
+	});
+	if (input.body.length > bounds.maxBodyChars) throw new ValidationError({
+		message: `A support request may be at most ${bounds.maxBodyChars} characters.`,
+		action: "Shorten the message and try again, or attach the detail as a file.",
+		detail: `submitted body is ${input.body.length} characters, over the ${bounds.maxBodyChars} bound`
+	});
+	if (input.attachments.length > bounds.attachments.maxCount) throw new ValidationError({
+		message: `A support request may carry at most ${bounds.attachments.maxCount} attachments.`,
+		action: `Send at most ${bounds.attachments.maxCount} files.`,
+		detail: `submission declared ${input.attachments.length} attachments, over the ${bounds.attachments.maxCount} bound`
+	});
+	const outcome = await submitFeedback({
+		db: deps.db,
+		config: deps.config,
+		categories: deps.categories,
+		bucket: deps.bucket,
+		fts: deps.fts,
+		resolveAccount: (id) => resolveSubmitterAccount(deps.d1, id),
+		dispatchClassify: deps.dispatchClassify,
+		emit: deps.emit,
+		log: deps.log,
+		newId: deps.newId,
+		now: deps.now
+	}, {
+		userId,
+		subject: input.subject,
+		body: input.body,
+		declaredCategory: input.declaredCategory,
+		threadId: input.threadId,
+		context: input.context,
+		attachments: input.attachments.map((attachment) => ({
+			filename: attachment.filename,
+			contentType: attachment.contentType,
+			bytes: decodeBase64(attachment.data, { maxBytes: bounds.attachments.maxBytes })
+		}))
+	});
+	return {
+		threadId: outcome.threadId,
+		messageId: outcome.messageId,
+		opened: outcome.newThread,
+		attachments: outcome.attachments
+	};
+}
+/** List the caller's own in-app conversations. */
+async function listMyThreads(deps, query, userId) {
+	const page = await listOwnThreads(deps.db, userId, {
+		cursor: query.cursor,
+		limit: query.limit
+	});
+	return {
+		threads: page.threads.map(myThreadView),
+		nextCursor: page.nextCursor
+	};
+}
+/**
+* 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.
+*/
+async function readMyThread(deps, threadId, userId) {
+	const detail = await readOwnThread(deps.db, threadId, userId);
+	const attachments = await presentAttachments(deps, detail.attachments);
+	const byMessage = /* @__PURE__ */ new Map();
+	for (const [index, attachment] of detail.attachments.entries()) {
+		const view = attachments[index];
+		if (!view) continue;
+		const bucket = byMessage.get(attachment.messageId);
+		if (bucket) bucket.push(view);
+		else byMessage.set(attachment.messageId, [view]);
+	}
+	return {
+		thread: myThreadView(detail.thread),
+		messages: detail.messages.map((message) => myMessageView(message, byMessage.get(message.id) ?? []))
+	};
+}
+//#endregion
+export { archiveConversation, listInbox, listMyThreads, listReplies, readConversation, readMyThread, reclassifyConversation, replyToConversation, submitFeedbackRequest, updateFlags };

package/dist/http/resolve.d.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { objectStore } from "@pithy-sh/storage/src/object/store";
+import type { Context } from "hono";
+import type { SupportWiring } from "../capability";
+import type { HandlerDeps } from "./handlers";
+/**
+ * Turning a Worker env into the dependencies the handlers take.
+ *
+ * The pattern every capability uses: nothing below `resolve.ts` ever reads a binding off `env`, so
+ * the handlers, the store, the reply path, and the ingest orchestration are all testable by handing
+ * them objects. This is the one file that knows what `env.DB` is called.
+ */
+/** The bindings support reads. */
+export interface SupportEnv extends SecretsStoreEnv {
+    /** The app database every support table lives in. */
+    DB: D1Database;
+    /** Attachment and raw-message bytes. Optional — an inbox with attachments off never touches it. */
+    SUPPORT_BUCKET?: R2Bucket;
+}
+/** Read the `DB` binding, or fail loudly rather than as a silent undefined three layers down. */
+export declare function resolveDb(env: Record<string, unknown>): D1Database;
+/**
+ * Start a classification.
+ *
+ * Dispatched through the registry rather than by reaching for the binding directly, so the params
+ * are validated at the call site and a missing binding degrades to a logged skip — which is the
+ * whole reason the job is declared `optional`. A project that has not run `pithy support provision`
+ * still receives mail; its threads simply stay `uncategorized`.
+ */
+export declare function makeClassifyDispatcher(env: Record<string, unknown>, log: Logger): (messageId: string) => Promise<boolean>;
+/**
+ * Build the object store attachment URLs are signed through.
+ *
+ * Returns undefined rather than throwing when the bucket is unbound: a deployment with attachments
+ * off has no bucket by design, and a thread view must still render. Credentials resolve lazily
+ * inside the seam, so this costs nothing until something is actually signed.
+ */
+export declare function resolveStore(env: SupportEnv): ReturnType<typeof objectStore> | undefined;
+/** Build the per-request handler dependencies. */
+export declare function makeResolveDeps(wiring: SupportWiring): (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/http/resolve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AAEH,kCAAkC;AAClC,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,qDAAqD;IACrD,EAAE,EAAE,UAAU,CAAC;IACf,mGAAmG;IACnG,cAAc,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAED,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAUlE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,GACV,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAUzC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,SAAS,CAGxF;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CA2BzG"}

package/dist/http/resolve.js

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { supportDatabase } from "../data/tables.js";
+import { SUPPORT_R2_SECRET } from "../secret/registry.js";
+import { supportWorkflowRegistry, supportWorkflows } from "../workflows/specs.js";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { objectStore } from "@pithy-sh/storage/src/object/store";
+//#region src/http/resolve.ts
+/** Read the `DB` binding, or fail loudly rather than as a silent undefined three layers down. */
+function resolveDb(env) {
+	const binding = env.DB;
+	if (!binding) throw new InternalError({
+		message: "The support database binding is missing.",
+		action: "Add the `DB` D1 binding to this Worker's wrangler.jsonc, then redeploy.",
+		detail: "D1 binding \"DB\" is not present on the worker env"
+	});
+	return binding;
+}
+/**
+* Start a classification.
+*
+* Dispatched through the registry rather than by reaching for the binding directly, so the params
+* are validated at the call site and a missing binding degrades to a logged skip — which is the
+* whole reason the job is declared `optional`. A project that has not run `pithy support provision`
+* still receives mail; its threads simply stay `uncategorized`.
+*/
+function makeClassifyDispatcher(env, log) {
+	return async (messageId) => {
+		const { triggerWorkflow } = await import("@pithy-sh/core/src/workflow/dispatch");
+		await triggerWorkflow(env, supportWorkflowRegistry, "support/classify", { messageId }, log);
+		return env[supportWorkflows.classify.binding] != null;
+	};
+}
+/**
+* Build the object store attachment URLs are signed through.
+*
+* Returns undefined rather than throwing when the bucket is unbound: a deployment with attachments
+* off has no bucket by design, and a thread view must still render. Credentials resolve lazily
+* inside the seam, so this costs nothing until something is actually signed.
+*/
+function resolveStore(env) {
+	if (!env.SUPPORT_BUCKET) return void 0;
+	return objectStore({
+		bucket: env.SUPPORT_BUCKET,
+		env,
+		secretName: SUPPORT_R2_SECRET
+	});
+}
+/** Build the per-request handler dependencies. */
+function makeResolveDeps(wiring) {
+	return async (c) => {
+		const env = c.env;
+		const d1 = resolveDb(env);
+		const log = c.var.log.child("support");
+		return {
+			db: supportDatabase(d1),
+			d1,
+			config: wiring.config,
+			categories: wiring.categories,
+			snippets: wiring.snippets,
+			fts: wiring.config.search.fts,
+			bucket: env.SUPPORT_BUCKET,
+			store: resolveStore(env),
+			enqueue: wiring.enqueueEmail ? (input) => wiring.enqueueEmail?.(env, input) : void 0,
+			dispatchClassify: makeClassifyDispatcher(env, log),
+			emit: c.var.emit,
+			log,
+			newId: () => crypto.randomUUID(),
+			now: () => /* @__PURE__ */ new Date()
+		};
+	};
+}
+//#endregion
+export { makeClassifyDispatcher, makeResolveDeps, resolveDb, resolveStore };