@pithy-sh/support 0.1.2 → 0.1.4

package/dist/inbound/ingest.js

@@ -0,0 +1,328 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportAttachment } from "../data/attachment.js";
+import { SupportMessage } from "../data/message.js";
+import { SupportThread, UNCLASSIFIED } from "../data/thread.js";
+import { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { attachmentKey, putAttachment, rawMessageKey, sha256Hex } from "../attachment/store.js";
+import { SupportAuditActions } from "../audit/actions.js";
+import { parentCandidates } from "../mime/threading.js";
+import { indexMessage } from "../store/search.js";
+import { truncateToBytes } from "../mime/truncate.js";
+import { MAX_TEXT_BODY, parseInbound } from "../mime/parse.js";
+import { checkRates, checkSize } from "./guard.js";
+import { htmlToText, sanitizeHtml } from "../mime/sanitize.js";
+import { senderAuthenticity } from "./authenticity.js";
+import { resolveInbox } from "./recipient.js";
+import { chunkRowsByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+//#region src/inbound/ingest.ts
+/** Record a refusal. Never throws — a guard decision must not become a 500. */
+async function auditRejection(deps, reason, detail, fromAddress) {
+	try {
+		await deps.emit({
+			action: SupportAuditActions.inboundRejected,
+			outcome: "denied",
+			severity: "warning",
+			actorType: "anonymous",
+			actorId: null,
+			resourceType: "support_inbox",
+			metadata: {
+				reason,
+				fromAddress: fromAddress ?? null
+			}
+		});
+		deps.log.warn("support inbound message refused", {
+			reason,
+			detail,
+			fromAddress: fromAddress ?? null
+		});
+	} catch (error) {
+		deps.log.warn("support inbound rejection audit dropped", {
+			reason,
+			detail,
+			error
+		});
+	}
+}
+/**
+* Find the thread a message continues, by walking its threading chain most-precise-first.
+*
+* The lookup goes through `pithy_support_messages.mime_message_id`, which is uniquely indexed — so
+* this is an index seek per candidate and the chain is bounded at 50 entries. It stops at the first
+* hit, which is why `parentCandidates` puts `In-Reply-To` ahead of a reversed `References`.
+*/
+async function findParentThread(db, parsed, inbox) {
+	const candidates = parentCandidates(parsed.inReplyTo, parsed.references);
+	if (candidates.length === 0) return void 0;
+	const parent = await db.selectFrom(SUPPORT_MESSAGES_TABLE).innerJoin(SUPPORT_THREADS_TABLE, `${SUPPORT_THREADS_TABLE}.id`, `${SUPPORT_MESSAGES_TABLE}.threadId`).select([`${SUPPORT_MESSAGES_TABLE}.threadId`, `${SUPPORT_MESSAGES_TABLE}.mimeMessageId`]).where(`${SUPPORT_MESSAGES_TABLE}.mimeMessageId`, "in", candidates).where(`${SUPPORT_THREADS_TABLE}.inboxAddress`, "=", inbox).execute();
+	if (parent.length === 0) return void 0;
+	const byId = new Map(parent.map((row) => [row.mimeMessageId, row.threadId]));
+	for (const candidate of candidates) {
+		const threadId = byId.get(candidate);
+		if (threadId !== void 0) return threadId;
+	}
+}
+/**
+* How many columns one `pithy_support_attachments` row binds. Derived from the schema rather than
+* written as a literal, so adding a column re-chunks instead of silently re-breaking the cap.
+*/
+const SUPPORT_ATTACHMENT_COLUMNS = Object.keys(SupportAttachment.shape).length;
+/** Store the attachments this config allows, and return the rows written. */
+async function storeAttachments(deps, parsed, threadId, messageId, now) {
+	const { attachments: bounds } = deps.config;
+	const bucket = deps.bucket;
+	if (!bounds.enabled || !bucket || parsed.attachments.length === 0) return 0;
+	const accepted = parsed.attachments.slice(0, bounds.maxCount);
+	if (parsed.attachments.length > accepted.length) deps.log.warn("support attachments truncated", {
+		threadId,
+		declared: parsed.attachments.length,
+		stored: accepted.length
+	});
+	const rows = [];
+	for (const attachment of accepted) {
+		if (attachment.bytes.byteLength > bounds.maxBytes) {
+			deps.log.warn("support attachment skipped, over the size bound", {
+				threadId,
+				bytes: attachment.bytes.byteLength,
+				maxBytes: bounds.maxBytes
+			});
+			continue;
+		}
+		const id = deps.newId();
+		const key = attachmentKey(threadId, id);
+		await putAttachment(bucket, key, attachment.bytes);
+		rows.push({
+			id,
+			messageId,
+			threadId,
+			filename: attachment.filename,
+			contentType: attachment.contentType,
+			size: attachment.bytes.byteLength,
+			sha256: await sha256Hex(attachment.bytes),
+			storageKey: key,
+			contentId: attachment.contentId ?? null,
+			inline: attachment.inline,
+			createdAt: now
+		});
+	}
+	const encoded = rows.map((row) => SupportAttachment.encode(row));
+	for (const chunk of chunkRowsByBoundParameters(encoded, SUPPORT_ATTACHMENT_COLUMNS)) await deps.db.insertInto(SUPPORT_ATTACHMENTS_TABLE).values(chunk).execute();
+	return rows.length;
+}
+/** Ingest one inbound message. */
+async function ingestInbound(deps, input) {
+	const now = deps.now();
+	const rawBytes = input.raw.byteLength;
+	const size = checkSize(deps.config.guard, rawBytes);
+	if (!size.accepted) {
+		await auditRejection(deps, size.reason, size.detail, void 0);
+		return {
+			handled: false,
+			reason: "rejected",
+			rejection: size.reason
+		};
+	}
+	const parsed = await parseInbound(input.raw, { expectedAuthservId: deps.config.guard.authservId });
+	const inbox = resolveInbox({
+		inboundAddresses: deps.config.inboundAddresses,
+		envelopeTo: input.envelopeTo,
+		headerRecipients: parsed.headerRecipients
+	});
+	if (inbox === void 0) return {
+		handled: false,
+		reason: "not_addressed"
+	};
+	const rates = await checkRates(deps.db, deps.config.guard, {
+		rawBytes,
+		fromAddress: parsed.fromAddress,
+		now
+	});
+	if (!rates.accepted) {
+		await auditRejection(deps, rates.reason, rates.detail, parsed.fromAddress);
+		return {
+			handled: false,
+			reason: "rejected",
+			rejection: rates.reason
+		};
+	}
+	if (parsed.messageId !== void 0) {
+		const existing = await deps.db.selectFrom(SUPPORT_MESSAGES_TABLE).select(["id", "threadId"]).where("mimeMessageId", "=", parsed.messageId).where("toAddress", "=", inbox).executeTakeFirst();
+		if (existing) {
+			deps.log.info("support message already stored, ignoring redelivery", { messageId: existing.id });
+			return {
+				handled: true,
+				duplicate: true,
+				threadId: existing.threadId,
+				messageId: existing.id
+			};
+		}
+	}
+	const html = parsed.html !== void 0 ? await sanitizeHtml(parsed.html) : void 0;
+	const derived = parsed.text.trim().length > 0 ? parsed.text : parsed.html !== void 0 ? await htmlToText(parsed.html) : "";
+	const text = truncateToBytes(derived, MAX_TEXT_BODY);
+	const authenticity = senderAuthenticity({
+		authResults: parsed.authResults,
+		fromAddress: parsed.fromAddress,
+		envelopeFrom: input.envelopeFrom,
+		trusted: deps.config.guard.trustAuthenticationResults
+	});
+	deps.log.info("support inbound authentication headers observed", {
+		seen: parsed.authHeadersSeen,
+		trusted: deps.config.guard.trustAuthenticationResults,
+		authenticated: authenticity.authenticated
+	});
+	const parentThreadId = await findParentThread(deps.db, parsed, inbox);
+	const threadId = parentThreadId ?? deps.newId();
+	const newThread = parentThreadId === void 0;
+	const messageId = deps.newId();
+	const subject = parsed.subject.length > 0 ? parsed.subject : "(no subject)";
+	let rawKey = null;
+	if (deps.bucket && deps.config.attachments.retainRaw) {
+		rawKey = rawMessageKey(threadId, messageId);
+		await deps.bucket.put(rawKey, input.raw, { httpMetadata: {
+			contentType: "application/octet-stream",
+			contentDisposition: "attachment"
+		} });
+	}
+	const message = {
+		id: messageId,
+		threadId,
+		direction: "inbound",
+		channel: "email",
+		submittedByUserId: null,
+		context: null,
+		mimeMessageId: parsed.messageId ?? null,
+		mimeInReplyTo: parsed.inReplyTo ?? null,
+		mimeReferences: parsed.references.length > 0 ? parsed.references : null,
+		fromAddress: parsed.fromAddress,
+		fromName: parsed.fromName ?? null,
+		toAddress: inbox,
+		subject,
+		textBody: text,
+		htmlBody: html ?? null,
+		emailJobId: null,
+		rawKey,
+		rawBytes,
+		receivedAt: now,
+		createdAt: now
+	};
+	try {
+		await deps.db.insertInto(SUPPORT_MESSAGES_TABLE).values(SupportMessage.encode(message)).execute();
+	} catch (error) {
+		const existing = parsed.messageId ? await deps.db.selectFrom(SUPPORT_MESSAGES_TABLE).select(["id", "threadId"]).where("mimeMessageId", "=", parsed.messageId).where("toAddress", "=", inbox).executeTakeFirst() : void 0;
+		if (existing) {
+			deps.log.info("support message stored concurrently, ignoring redelivery", { messageId: existing.id });
+			return {
+				handled: true,
+				duplicate: true,
+				threadId: existing.threadId,
+				messageId: existing.id
+			};
+		}
+		throw error;
+	}
+	try {
+		if (newThread) {
+			let userId = null;
+			try {
+				userId = await deps.linkSender(parsed.fromAddress);
+			} catch (error) {
+				deps.log.warn("support sender link failed", { error });
+			}
+			if (userId && !authenticity.authenticated) deps.log.info("support sender matched on an unverified From address", { method: authenticity.method });
+			const thread = {
+				id: threadId,
+				channel: "email",
+				inboxAddress: inbox,
+				subject,
+				fromAddress: parsed.fromAddress,
+				fromName: parsed.fromName ?? null,
+				senderAuthenticated: authenticity.authenticated,
+				userId,
+				accountLinkSource: userId ? "email_address" : null,
+				...UNCLASSIFIED,
+				archived: false,
+				archivedAt: null,
+				archivedBy: null,
+				messageCount: 1,
+				firstMessageAt: now,
+				lastMessageAt: now,
+				createdAt: now,
+				updatedAt: now
+			};
+			await deps.db.insertInto(SUPPORT_THREADS_TABLE).values(SupportThread.encode(thread)).execute();
+		} else {
+			let linkedNow = null;
+			if (authenticity.authenticated) {
+				if ((await deps.db.selectFrom("pithySupportThreads").select(["userId"]).where("id", "=", threadId).executeTakeFirst())?.userId == null) try {
+					linkedNow = await deps.linkSender(parsed.fromAddress);
+				} catch (error) {
+					deps.log.warn("support sender re-link failed", { error });
+				}
+			}
+			await deps.db.updateTable(SUPPORT_THREADS_TABLE).set((eb) => ({
+				...linkedNow ? {
+					userId: linkedNow,
+					senderAuthenticated: 1,
+					accountLinkSource: "email_address"
+				} : {},
+				messageCount: eb("messageCount", "+", 1),
+				lastMessageAt: now.getTime(),
+				updatedAt: now.getTime(),
+				archived: 0,
+				archivedAt: null,
+				archivedBy: null
+			})).where("id", "=", threadId).execute();
+		}
+	} catch (error) {
+		await deps.db.deleteFrom(SUPPORT_MESSAGES_TABLE).where("id", "=", messageId).execute().catch(() => {
+			deps.log.error("support message orphaned — thread write failed and the message could not be removed", {
+				messageId,
+				threadId
+			});
+		});
+		throw error;
+	}
+	if (deps.fts) try {
+		await indexMessage(deps.db, {
+			threadId,
+			messageId,
+			subject,
+			body: text
+		});
+	} catch (error) {
+		deps.log.warn("support message not indexed", {
+			messageId,
+			error
+		});
+	}
+	let attachments = 0;
+	try {
+		attachments = await storeAttachments(deps, parsed, threadId, messageId, now);
+	} catch (error) {
+		deps.log.warn("support attachments not stored", {
+			messageId,
+			error
+		});
+	}
+	const classifying = deps.config.ai.enabled && !parsed.autoSubmitted;
+	if (classifying) try {
+		await deps.dispatchClassify(messageId);
+	} catch (error) {
+		deps.log.warn("support classification dispatch failed", {
+			messageId,
+			error
+		});
+	}
+	return {
+		handled: true,
+		duplicate: false,
+		threadId,
+		messageId,
+		newThread,
+		attachments,
+		classifying
+	};
+}
+//#endregion
+export { ingestInbound };

package/dist/inbound/recipient.d.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * Resolve which configured inbox a message landed on, or `undefined` when none of them did.
+ *
+ * The returned address is stored on the thread, so a Worker serving `support@` and `security@` can
+ * keep the two apart in one table — and the value is the *configured* one rather than the envelope
+ * string, so a thread's inbox is always something that appears in `pithy.config.ts`.
+ */
+export declare function resolveInbox(options: {
+    /** The configured addresses, already normalized and lowercased. */
+    inboundAddresses: readonly string[];
+    /** The SMTP envelope recipient — `ForwardableEmailMessage.to`. The authority. */
+    envelopeTo: string | undefined;
+    /** `To`/`Cc`/`Delivered-To` from the parsed headers. Corroborating only. */
+    headerRecipients: readonly string[];
+}): string | undefined;
+//# sourceMappingURL=recipient.d.ts.map

package/dist/inbound/recipient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipient.d.ts","sourceRoot":"","sources":["../../src/inbound/recipient.ts"],"names":[],"mappings":"AAgCA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,mEAAmE;IACnE,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iFAAiF;IACjF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,GAAG,MAAM,GAAG,SAAS,CAoBrB"}

package/dist/inbound/recipient.js

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { parseAddress } from "@pithy-sh/core/src/address/address";
+//#region src/inbound/recipient.ts
+/**
+* Which inbound messages belong to this capability.
+*
+* A Worker has exactly one `email()` entry, and `createEntrypoint` fans every message to **every**
+* capability that declares a handler. So a Worker running both `@pithy-sh/email` and this one sees
+* each bounce twice and each support request twice, and the discrimination is each handler's own
+* job. Email's handler filters by content — it acts only on DSNs and ARF reports. This one filters
+* by **address**, because a support request looks like ordinary mail and there is nothing in its
+* body to key on.
+*
+* ## The envelope recipient is the authority; the headers are not
+*
+* `ForwardableEmailMessage.to` is the SMTP envelope recipient — the address Cloudflare's own routing
+* rule matched to deliver here. It is the only recipient that was proved rather than asserted.
+*
+* The `To:` and `Cc:` headers are neither. Anyone can put `To: support@yourdomain.com` on a message
+* addressed elsewhere, and BCC means a legitimate message frequently does not name its real
+* recipient at all. Trusting them would let a stranger inject threads into an inbox they were never
+* routed to — so they are used only as a fallback for the one case where the envelope is unusable,
+* and never to override it.
+*/
+/** Whether an address is one of the configured inbox addresses. Both sides are already normalized. */
+function claims(addresses, candidate) {
+	return candidate !== void 0 && addresses.includes(candidate);
+}
+/**
+* Resolve which configured inbox a message landed on, or `undefined` when none of them did.
+*
+* The returned address is stored on the thread, so a Worker serving `support@` and `security@` can
+* keep the two apart in one table — and the value is the *configured* one rather than the envelope
+* string, so a thread's inbox is always something that appears in `pithy.config.ts`.
+*/
+function resolveInbox(options) {
+	const { inboundAddresses } = options;
+	if (inboundAddresses.length === 0) return void 0;
+	const envelope = parseAddress(options.envelopeTo);
+	if (envelope !== void 0) return claims(inboundAddresses, envelope) ? envelope : void 0;
+	for (const candidate of options.headerRecipients) {
+		const normalized = parseAddress(candidate);
+		if (claims(inboundAddresses, normalized)) return normalized;
+	}
+}
+//#endregion
+export { resolveInbox };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The package entrypoint — the surface `pithy add support` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config and options types, the two federation helpers an adopter
+ * calls, the control-plane scopes, and the table schemas. Every other module is imported by deep path
+ * (`@pithy-sh/support/src/...`); this is the documented contract, not a barrel over the package.
+ */
+export { type SupportAuditAction, SupportAuditActions } from "./audit/actions";
+export { isSupportCapability, SUPPORT_MIGRATION_ORDER, type SupportCapability, type SupportOptions, support, } from "./capability";
+export { DEFAULT_CLASSIFY_MODEL, SupportAiConfig, SupportAttachmentsConfig, SupportConfig, type SupportConfigInput, SupportGuardConfig, SupportReplyConfig, SupportSearchConfig, } from "./config/config";
+export { SupportAttachment } from "./data/attachment";
+export { DEFAULT_SUPPORT_CATEGORIES, defineSupportCategories, type SupportCategories, } from "./data/categories";
+export { SupportClassification } from "./data/classification";
+export { SupportMessageDirection, SupportPriority, SupportSentiment, UNCATEGORIZED } from "./data/enums";
+export { SupportThreadFlag } from "./data/flag";
+export { SupportMessage } from "./data/message";
+export { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_SEARCH_TABLE, SUPPORT_THREADS_TABLE, type SupportDatabase, supportDatabase, } from "./data/tables";
+export { SupportThread } from "./data/thread";
+export { SUPPORT_CONTROL_PLANE_SCOPES, SUPPORT_THREADS_ARCHIVE_SCOPE, SUPPORT_THREADS_FLAG_SCOPE, SUPPORT_THREADS_READ_SCOPE, SUPPORT_THREADS_RECLASSIFY_SCOPE, SUPPORT_THREADS_REPLY_SCOPE, } from "./http/scopes";
+export { DEFAULT_SUPPORT_REPLIES, defineSupportReplies, SupportReplySnippet, type SupportReplySnippets, } from "./reply/snippets";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,wBAAwB,EACxB,aAAa,EACb,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,eAAe,EACpB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { DEFAULT_SUPPORT_REPLIES, SupportReplySnippet, defineSupportReplies } from "./reply/snippets.js";
+import { DEFAULT_CLASSIFY_MODEL, SupportAiConfig, SupportAttachmentsConfig, SupportConfig, SupportGuardConfig, SupportReplyConfig, SupportSearchConfig } from "./config/config.js";
+import { SupportMessageDirection, SupportPriority, SupportSentiment, UNCATEGORIZED } from "./data/enums.js";
+import { DEFAULT_SUPPORT_CATEGORIES, defineSupportCategories } from "./data/categories.js";
+import { SupportAttachment } from "./data/attachment.js";
+import { SupportClassification } from "./data/classification.js";
+import { SupportThreadFlag } from "./data/flag.js";
+import { SupportMessage } from "./data/message.js";
+import { SupportThread } from "./data/thread.js";
+import { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_SEARCH_TABLE, SUPPORT_THREADS_TABLE, supportDatabase } from "./data/tables.js";
+import { SupportAuditActions } from "./audit/actions.js";
+import { SUPPORT_CONTROL_PLANE_SCOPES, SUPPORT_THREADS_ARCHIVE_SCOPE, SUPPORT_THREADS_FLAG_SCOPE, SUPPORT_THREADS_READ_SCOPE, SUPPORT_THREADS_RECLASSIFY_SCOPE, SUPPORT_THREADS_REPLY_SCOPE } from "./http/scopes.js";
+import { SUPPORT_MIGRATION_ORDER, isSupportCapability, support } from "./capability.js";
+export { DEFAULT_CLASSIFY_MODEL, DEFAULT_SUPPORT_CATEGORIES, DEFAULT_SUPPORT_REPLIES, SUPPORT_ATTACHMENTS_TABLE, SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_CONTROL_PLANE_SCOPES, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_MIGRATION_ORDER, SUPPORT_SEARCH_TABLE, SUPPORT_THREADS_ARCHIVE_SCOPE, SUPPORT_THREADS_FLAG_SCOPE, SUPPORT_THREADS_READ_SCOPE, SUPPORT_THREADS_RECLASSIFY_SCOPE, SUPPORT_THREADS_REPLY_SCOPE, SUPPORT_THREADS_TABLE, SupportAiConfig, SupportAttachment, SupportAttachmentsConfig, SupportAuditActions, SupportClassification, SupportConfig, SupportGuardConfig, SupportMessage, SupportMessageDirection, SupportPriority, SupportReplyConfig, SupportReplySnippet, SupportSearchConfig, SupportSentiment, SupportThread, SupportThreadFlag, UNCATEGORIZED, defineSupportCategories, defineSupportReplies, isSupportCapability, support, supportDatabase };

package/dist/link/sender.d.ts

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database } from "@cloudflare/workers-types";
+import type { Entitlement } from "@pithy-sh/core/src/entitlement/entitlement";
+/**
+ * The link from an address in a `From` header to the customer the app already knows about.
+ *
+ * This is the feature the whole capability exists for. A support thread that arrives already knowing
+ * who the sender is, what they bought, on which rail, and whether their last renewal failed is a
+ * different object from a message in a mailbox — and every one of those facts is already in the
+ * adopter's own D1, one table over, unused.
+ *
+ * ## Guarded dynamic imports, not dependencies
+ *
+ * `@pithy-sh/auth` and `@pithy-sh/payments` are **optional** here (principle 4: depend on core seams,
+ * never on a sibling's internals), so both are reached the way `@pithy-sh/matchmaking` already
+ * reaches auth — a dynamic import inside a `try`, degrading to "no link" when the package is not
+ * installed. A support inbox in a project with no accounts and no payments is a perfectly reasonable
+ * thing to run, and it must not fail to start, or to store mail, because of what it cannot see.
+ *
+ * Every function here is **best-effort by contract**: it returns nothing rather than throwing, and
+ * the caller stores the message either way. Linkage is context, and context is never worth losing a
+ * customer's support request over.
+ *
+ * ## The billing half links people, and only people
+ *
+ * `@pithy-sh/payments` keys a purchase on a **subject pair** — a user or an organization, plus an id —
+ * and which of the two a project uses is its `billingSubject` config. Support cannot honor that choice.
+ * It starts from a `From:` header, resolves it to a *person*, and does its billing lookup at thread-read
+ * time, where there is no Hono `Context` to hand the adopter's subject resolver: the seam's whole job is
+ * to answer "which organization is *this caller* acting for", and a support thread has no caller.
+ *
+ * So this file reads `user`-subject rows, and {@link SUPPORT_BILLING_SCOPE} says so on every response.
+ * Under organization billing the panel is empty, and it must not be *silently* empty — the lookups below
+ * are guarded dynamic imports whose `catch` already returns `[]`, so an empty panel is indistinguishable
+ * between "bought nothing", "`@pithy-sh/payments` is not installed" and "billed to an organization".
+ * An operator reads the first of those and decides a refund on it. A declared scope is what turns the
+ * third case from a silence into a limitation somebody can see.
+ *
+ * **The scope constant used to be declared here, and is now `data/billingScope.ts` (Jim, 2026-08-21).**
+ * The old argument was that the query and the wire must read one value, which is right and unchanged —
+ * but `http/responses.ts` honoring it by importing from *this* file pulled the whole server data layer
+ * into a browser program, because that is what this file's imports are (#419). One value, in a module
+ * neither half owns.
+ */
+/** The account a sender resolves to, and what the app knows about them. */
+export interface SenderContext {
+    /**
+     * Whether the `From:` header was proved to belong to the sender. **Everything below is empty when
+     * this is false**, and a dashboard must render the sender as an unverified claim rather than as a
+     * customer — the whole value of this panel is that an operator trusts it, so it must not be
+     * populated from an address anybody could have written.
+     */
+    authenticated: boolean;
+    /** The linked `pithy_auth_users.id`, or null when this address belongs to nobody with an account. */
+    userId: string | null;
+    /** The account's display name, when auth is composed and the sender is known. */
+    name?: string;
+    /** Whether the account has verified this address. A useful signal beside an unverified claim in a header. */
+    emailVerified?: boolean;
+    /**
+     * Their purchase history, newest first — **individually billed purchases only**. Empty when payments
+     * is absent, when they have bought nothing, and when their billing is held by an organization this
+     * seam cannot resolve. `SenderContextView.billingScope` is what tells a console those apart.
+     */
+    purchases: readonly SenderPurchase[];
+    /**
+     * Their entitlements, lapsed ones included and marked inactive — a paywall wants to say when Pro
+     * ended. Same scope as {@link SenderContext.purchases}: `user` subjects, nothing organization-held.
+     */
+    entitlements: readonly Entitlement[];
+}
+/** One purchase, flattened to what a support console renders. */
+export interface SenderPurchase {
+    /** The purchase row id. */
+    id: string;
+    /** Which rail it went through — `apple`, `google`, or `stripe`. */
+    rail: string;
+    /** The Pithy product key. */
+    productId: string;
+    /** Its lifecycle state — `active`, `refunded`, `expired`, and so on. */
+    status: string;
+    /** Whether the purchase happened in the store's sandbox rather than production. */
+    environment: string;
+    /** When it was bought. */
+    purchasedAt: Date;
+    /** When it runs out; null for something owned forever. */
+    expiresAt: Date | null;
+    /** When it was refunded or revoked; null while it stands. */
+    revokedAt: Date | null;
+}
+/** How many purchases a thread view carries. Enough to see the pattern, bounded so a whale is not a slow page. */
+export declare const MAX_LINKED_PURCHASES = 25;
+/**
+ * Resolve a sender address to a user id.
+ *
+ * **Exact match on the normalized address, and deliberately no case-insensitive fallback.** The
+ * `email` column is indexed and unique, so this is one index seek; a `lower(email) = ?` fallback
+ * would be a full table scan, and it would run for *every unknown sender* — which on a public
+ * address means every piece of spam scanning the entire user table. Better Auth normalizes on its
+ * own signup path, so the exact match is the case that actually occurs; an address stored with
+ * capitals by some other route simply does not link, which costs a line of context rather than a
+ * customer's request.
+ */
+export declare function resolveSenderUserId(d1: D1Database, address: string): Promise<string | null>;
+/**
+ * The address an operator's reply to an app thread will be sent to, or null when the account carries
+ * nothing deliverable.
+ *
+ * Extracted rather than inlined because it is the one decision in {@link resolveSubmitterAccount} with
+ * a wrong answer available, and inlining it puts that decision behind a guarded dynamic import where
+ * no test can reach it.
+ *
+ * **`parseAddress` only, with no `normalizeAddress` fallback.** The fallback merely trims and
+ * lowercases, so it would hand back an address this capability's own parser had just refused — and
+ * this value becomes the thread's `fromAddress`, which `sendReply` enqueues an answer to. Returning
+ * null makes an unparseable account the same hard fault as a missing one, which is what the caller
+ * already does with it: refusing the submission beats accepting a report whose only reply address
+ * cannot be delivered to.
+ */
+export declare function submitterAddress(email: string | null | undefined): string | null;
+/**
+ * The account behind an authenticated submitter — resolved by id, never by an address.
+ *
+ * The inverse of {@link resolveSenderUserId}, and it exists because the in-app channel starts from the
+ * opposite end: a session names a user id, and what the thread needs is the address a reply will go
+ * back to. Deriving that from anything the client sent would hand a signed-in caller the ability to
+ * point a support conversation — and every operator reply on it — at somebody else's mailbox.
+ *
+ * Returns null when `@pithy-sh/auth` is absent or the account is gone. A submission whose account
+ * cannot be read is refused by the caller rather than stored with a guessed address: an app thread with
+ * no working reply address is a report nobody can answer.
+ */
+export declare function resolveSubmitterAccount(d1: D1Database, userId: string): Promise<{
+    email: string;
+    name?: string;
+    emailVerified?: boolean;
+} | null>;
+/**
+ * Everything the app already knows about a sender — read at thread-read time rather than stored.
+ *
+ * Derived, so it is always current: a customer who buys Pro an hour after writing in shows as
+ * entitled the next time the thread is opened, with nothing to backfill and nothing to invalidate.
+ * That is the same rule the classification follows, applied to the half of the model that lives in
+ * somebody else's tables.
+ */
+export declare function resolveSenderContext(d1: D1Database, address: string, now: Date, options: {
+    authenticated: boolean;
+}): Promise<SenderContext>;
+/**
+ * The customer context behind a **session-proven** link, resolved from the user id itself.
+ *
+ * An app thread already holds the id its session proved, so re-deriving it from the thread's address
+ * would be both a step backwards and a correctness bug: `resolveSenderUserId` matches the `email`
+ * column exactly, and an account stored with capitals by some other route would silently resolve to
+ * nobody — turning the one link that *is* certain into the one the console shows as unknown.
+ *
+ * Everything below the link degrades exactly as it does on the mail path: purchases and entitlements
+ * are guarded dynamic imports and come back empty when `@pithy-sh/payments` is absent.
+ */
+export declare function resolveSubmitterContext(d1: D1Database, userId: string, now: Date): Promise<SenderContext>;
+//# sourceMappingURL=sender.d.ts.map

package/dist/link/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../src/link/sender.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,qGAAqG;IACrG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6GAA6G;IAC7G,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC;;;OAGG;IACH,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;CACtC;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,WAAW,EAAE,IAAI,CAAC;IAClB,0DAA0D;IAC1D,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,6DAA6D;IAC7D,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,kHAAkH;AAClH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAEhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CAiB3E;AA4ED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,IAAI,EACT,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAI/G"}