@pithy-sh/support 0.1.1 → 0.1.3

package/dist/store/search.js

@@ -0,0 +1,160 @@
+import { SUPPORT_MESSAGES_TABLE } from "../data/tables.js";
+import { sql } from "kysely";
+//#region src/store/search.ts
+/**
+* Text search over the inbox — two backends behind one predicate.
+*
+* **`LIKE` is the default and FTS5 is the opt-in**, which is the opposite of what it looks like it
+* should be. The reason is in `store/searchIndex.ts`: an FTS5 virtual table anywhere in a D1
+* database makes `wrangler d1 export` refuse to dump *the whole database*, so turning it on by
+* default would quietly cost every adopter their backup story for tables that have nothing to do
+* with support. `LIKE` is an unindexed scan and is completely adequate for an inbox measured in
+* thousands of messages, which is what this capability is for.
+*
+* Both paths return a **predicate over `pithy_support_threads`**, not a list of ids, so search
+* composes with the category/archived filters and — crucially — with cursor pagination. Returning
+* ids would mean either capping the match set (silent truncation, which reads as "that is all there
+* is") or paginating twice over.
+*
+* Either way this is keyword search, deliberately. People search a support inbox for a word they
+* remember — an order number, an error string, a surname — not for a concept. `@pithy-sh/vector` is
+* there for anyone who wants meaning-matching, and it is the nicer demo and the wrong default: it
+* cannot find `ORD-40912`.
+*/
+/** The longest search term accepted. Bounded because it becomes a scan predicate. */
+const MAX_TERM = 200;
+/** Escape the `LIKE` wildcards so a term containing `%` matches a literal `%`. */
+function escapeLike(term) {
+	return term.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+/**
+* Turn a user's words into an FTS5 MATCH expression.
+*
+* Every token is quoted and the whole thing is ANDed. Quoting is what stops FTS5's own query syntax
+* from leaking through: a bare `NOT`, `OR`, `*` or `(` is an operator to FTS5, so a customer whose
+* surname is a keyword — or anyone deliberately probing — would otherwise change the shape of the
+* query rather than search for a word. This is the same "input is data, never syntax" rule the rest
+* of the package applies to model output and to HTML.
+*/
+function ftsQuery(term) {
+	return term.slice(0, MAX_TERM).split(/[^\p{L}\p{N}_-]+/u).filter((token) => token.length > 0).slice(0, 16).map((token) => `"${token.replace(/"/g, "\"\"")}"`).join(" AND ");
+}
+/** Whether a term has anything searchable left after tokenizing. */
+function isSearchable(term, fts) {
+	return fts ? ftsQuery(term).length > 0 : term.trim().length > 0;
+}
+/**
+* A predicate matching threads whose messages contain `term`.
+*
+* Correlated on the thread id so it drops into a `where` beside every other filter. The subquery is
+* `exists`, so it stops at the first matching message rather than counting them.
+*/
+function searchPredicate(term, options) {
+	if (options.fts) return sql`exists (
+      select 1 from pithy_support_search
+      where pithy_support_search.thread_id = pithy_support_threads.id
+        and pithy_support_search match ${ftsQuery(term)}
+    )`;
+	const pattern = `%${escapeLike(term.slice(0, MAX_TERM))}%`;
+	return sql`exists (
+    select 1 from pithy_support_messages m
+    where m.thread_id = pithy_support_threads.id
+      and (m.subject like ${pattern} escape '\\' or m.text_body like ${pattern} escape '\\')
+  )`;
+}
+/**
+* Add a message to the full-text index, replacing any row already there for it.
+*
+* **Remove-then-insert, not a bare insert** — the same shape the CMS `syncFts` uses, and for the
+* reason application-managed indexes always need it: an FTS5 table has no primary key and no unique
+* constraint to lean on, so a second call for the same message would silently add a second copy and
+* the thread would start appearing twice in its own search results. Making the write idempotent means
+* a retry, a reindex, and a first index are all the same operation, which is the property every other
+* write path in this repo is built on.
+*
+* Best-effort by contract: a failed index write must never lose a customer's message, so the caller
+* logs and carries on — the row is still there, still readable, still repairable by
+* {@link reindexThread}, and only missing from one search box.
+*/
+async function indexMessage(db, entry) {
+	await sql`delete from pithy_support_search where message_id = ${entry.messageId}`.execute(db);
+	await sql`
+    insert into pithy_support_search(thread_id, message_id, subject, body)
+    values (${entry.threadId}, ${entry.messageId}, ${entry.subject}, ${entry.body})
+  `.execute(db);
+}
+/**
+* Rebuild the index for one thread — delete its rows, then re-add every message.
+*
+* The repair path for the failure mode application-side indexing has and triggers would not: a
+* message stored while the index write failed. Also what a reindex after a tokenizer change runs.
+*/
+async function reindexThread(db, threadId) {
+	await sql`delete from pithy_support_search where thread_id = ${threadId}`.execute(db);
+	const messages = await db.selectFrom(SUPPORT_MESSAGES_TABLE).select([
+		"id",
+		"threadId",
+		"subject",
+		"textBody"
+	]).where("threadId", "=", threadId).execute();
+	for (const message of messages) await indexMessage(db, {
+		threadId: message.threadId,
+		messageId: message.id,
+		subject: message.subject,
+		body: message.textBody
+	});
+	return messages.length;
+}
+/**
+* Rebuild the whole index from the messages table, in pages.
+*
+* **Creating the index is not the same as populating it**, and that gap is the one failure a search
+* box must not have: an adopter who turns `search.fts` on after mail already exists gets an empty
+* virtual table, and because the table now *exists* the `LIKE` fallback never fires — so the inbox
+* answers "no matches" for a term that is demonstrably in the body. Silently returning nothing is
+* worse than returning slowly, so provisioning backfills immediately after it creates.
+*
+* Paged on `(receivedAt, id)` rather than an offset, for the same reason the inbox is: rows arriving
+* during a long backfill would shift an offset underneath it and skip messages.
+*/
+async function reindexAll(db, options = {}) {
+	const pageSize = options.pageSize ?? 200;
+	await sql`delete from pithy_support_search`.execute(db);
+	let cursor;
+	let indexed = 0;
+	for (;;) {
+		let page = db.selectFrom(SUPPORT_MESSAGES_TABLE).select([
+			"id",
+			"threadId",
+			"subject",
+			"textBody",
+			"receivedAt"
+		]).orderBy("receivedAt", "asc").orderBy("id", "asc").limit(pageSize);
+		if (cursor) {
+			const at = cursor.receivedAt;
+			const id = cursor.id;
+			page = page.where((eb) => eb.or([eb("receivedAt", ">", at), eb.and([eb("receivedAt", "=", at), eb("id", ">", id)])]));
+		}
+		const rows = await page.execute();
+		if (rows.length === 0) break;
+		for (const row of rows) {
+			await indexMessage(db, {
+				threadId: row.threadId,
+				messageId: row.id,
+				subject: row.subject,
+				body: row.textBody
+			});
+			indexed += 1;
+		}
+		options.onProgress?.(indexed);
+		const last = rows[rows.length - 1];
+		if (!last || rows.length < pageSize) break;
+		cursor = {
+			receivedAt: Number(last.receivedAt),
+			id: last.id
+		};
+	}
+	return indexed;
+}
+//#endregion
+export { ftsQuery, indexMessage, isSearchable, reindexAll, reindexThread, searchPredicate };

package/dist/store/searchIndex.d.ts

@@ -0,0 +1,53 @@
+import { type Kysely } from "kysely";
+import type { SupportDatabase } from "../data/tables";
+/**
+ * The FTS5 index's lifecycle — created and dropped by `pithy support provision`, **not by a
+ * migration**.
+ *
+ * ## Why this is not a migration
+ *
+ * Because it holds no data. Every row in it is derived from `pithy_support_messages`, and
+ * `reindexThread` rebuilds it from there at any time — so dropping it loses a search box for as long
+ * as it takes to rebuild, and nothing else. That is the line: a migration is for schema whose loss
+ * loses data, and this is a provisioned resource like the R2 bucket and the routing rule, which
+ * support already creates the same way.
+ *
+ * Making it a migration was the mistake, and the failure was specific rather than theoretical.
+ * Composing it conditionally on `search.fts` meant turning the flag **off** removed an
+ * already-applied migration from the set, and Kysely reads a previously-executed migration that has
+ * vanished as corruption:
+ *
+ *     corrupted migrations: previously executed migration 1200_support_0002_search is missing
+ *
+ * Every capability's migrations for a database compose into one provider, so that throw blocked
+ * `pithy migrate` for auth, payments, and email too — a whole-database outage from one capability's
+ * config flag, fixable only by knowing to roll back first. Out of the ledger, there is nothing to
+ * corrupt and toggling either way is just a re-provision.
+ *
+ * Both statements are idempotent, so provisioning stays safe to re-run — the property every other
+ * step of `pithy support provision` already has.
+ */
+/** The virtual table's name. Snake_case because nothing translates it — every statement here is hand-written. */
+export declare const SEARCH_TABLE = "pithy_support_search";
+/**
+ * Create the full-text index if it is not already there.
+ *
+ * A standalone (not external-content) FTS5 table. External content would store the text once rather
+ * than twice, but it requires the indexed column names to exist verbatim on the content table, and
+ * ours is `text_body` rather than `body`. Duplicating is the honest trade for an index that cannot
+ * desynchronize on a column rename.
+ *
+ * `thread_id` and `message_id` are UNINDEXED: they are carried so a match resolves straight to a
+ * conversation and so one message's rows can be replaced, and tokenizing a UUID would only add noise
+ * to every query.
+ */
+export declare function createSearchIndex(db: SupportDatabase | Kysely<unknown>): Promise<void>;
+/**
+ * Drop the full-text index if it is there.
+ *
+ * Safe by construction: the index is derived, so this costs a rebuild rather than a restore. It is
+ * what `pithy support provision` runs when `search.fts` goes back to false — and the reason turning
+ * the feature off is now a one-command operation instead of a migration rollback.
+ */
+export declare function dropSearchIndex(db: SupportDatabase | Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=searchIndex.d.ts.map

package/dist/store/searchIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchIndex.d.ts","sourceRoot":"","sources":["../../src/store/searchIndex.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,iHAAiH;AACjH,eAAO,MAAM,YAAY,yBAAyB,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5F;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1F"}

package/dist/store/searchIndex.js

@@ -0,0 +1,66 @@
+import { sql } from "kysely";
+//#region src/store/searchIndex.ts
+/**
+* The FTS5 index's lifecycle — created and dropped by `pithy support provision`, **not by a
+* migration**.
+*
+* ## Why this is not a migration
+*
+* Because it holds no data. Every row in it is derived from `pithy_support_messages`, and
+* `reindexThread` rebuilds it from there at any time — so dropping it loses a search box for as long
+* as it takes to rebuild, and nothing else. That is the line: a migration is for schema whose loss
+* loses data, and this is a provisioned resource like the R2 bucket and the routing rule, which
+* support already creates the same way.
+*
+* Making it a migration was the mistake, and the failure was specific rather than theoretical.
+* Composing it conditionally on `search.fts` meant turning the flag **off** removed an
+* already-applied migration from the set, and Kysely reads a previously-executed migration that has
+* vanished as corruption:
+*
+*     corrupted migrations: previously executed migration 1200_support_0002_search is missing
+*
+* Every capability's migrations for a database compose into one provider, so that throw blocked
+* `pithy migrate` for auth, payments, and email too — a whole-database outage from one capability's
+* config flag, fixable only by knowing to roll back first. Out of the ledger, there is nothing to
+* corrupt and toggling either way is just a re-provision.
+*
+* Both statements are idempotent, so provisioning stays safe to re-run — the property every other
+* step of `pithy support provision` already has.
+*/
+/** The virtual table's name. Snake_case because nothing translates it — every statement here is hand-written. */
+const SEARCH_TABLE = "pithy_support_search";
+/**
+* Create the full-text index if it is not already there.
+*
+* A standalone (not external-content) FTS5 table. External content would store the text once rather
+* than twice, but it requires the indexed column names to exist verbatim on the content table, and
+* ours is `text_body` rather than `body`. Duplicating is the honest trade for an index that cannot
+* desynchronize on a column rename.
+*
+* `thread_id` and `message_id` are UNINDEXED: they are carried so a match resolves straight to a
+* conversation and so one message's rows can be replaced, and tokenizing a UUID would only add noise
+* to every query.
+*/
+async function createSearchIndex(db) {
+	await sql`
+    create virtual table if not exists pithy_support_search using fts5(
+      thread_id unindexed,
+      message_id unindexed,
+      subject,
+      body,
+      tokenize = 'unicode61 remove_diacritics 2'
+    )
+  `.execute(db);
+}
+/**
+* Drop the full-text index if it is there.
+*
+* Safe by construction: the index is derived, so this costs a rebuild rather than a restore. It is
+* what `pithy support provision` runs when `search.fts` goes back to false — and the reason turning
+* the feature off is now a one-command operation instead of a migration rollback.
+*/
+async function dropSearchIndex(db) {
+	await sql`drop table if exists pithy_support_search`.execute(db);
+}
+//#endregion
+export { SEARCH_TABLE, createSearchIndex, dropSearchIndex };

package/dist/store/threads.d.ts

@@ -0,0 +1,147 @@
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import { SupportAttachment } from "../data/attachment";
+import type { SupportChannel, SupportPriority, SupportSentiment } from "../data/enums";
+import { SupportMessage } from "../data/message";
+import { type SupportDatabase } from "../data/tables";
+import { SupportThread } from "../data/thread";
+/**
+ * The inbox query — the one read this whole data model was shaped around.
+ *
+ * ## Cursor pagination, never offset
+ *
+ * `OFFSET` is wrong here for a reason specific to an inbox: rows are inserted at the *front* of the
+ * order the list is sorted by, so every message that arrives while somebody is reading shifts every
+ * subsequent page down by one. The reader sees a thread twice and misses another, and the misses are
+ * silent. A cursor on `(lastMessageAt, id)` describes a position in the data rather than a count of
+ * rows skipped, so new mail arriving above it changes nothing about what comes next.
+ *
+ * `id` is in the cursor because `lastMessageAt` is not unique — two messages landing in the same
+ * millisecond is unlikely and a page boundary landing between them is exactly where it would show up
+ * as a dropped row.
+ */
+/** An opaque position in the inbox ordering. */
+export interface ThreadCursor {
+    /** The `lastMessageAt` of the last thread on the previous page, as ms-epoch. */
+    lastMessageAt: number;
+    /** That thread's id — the tiebreak that makes the position exact. */
+    id: string;
+}
+/**
+ * Encode a cursor for the wire.
+ *
+ * Base64url over JSON, and **opaque by intent rather than by obscurity**: the point is that a client
+ * cannot construct one by hand and therefore cannot come to depend on its shape, so the ordering can
+ * change later without breaking every caller. It is not a secret — it holds a timestamp and an id
+ * the caller was just given.
+ */
+export declare function encodeCursor(cursor: ThreadCursor): string;
+/** Decode a cursor. Returns undefined for anything malformed — a bad cursor is a first page, not a 500. */
+export declare function decodeCursor(value: string | undefined): ThreadCursor | undefined;
+/** What a caller may filter the inbox by. */
+export interface ListThreadsQuery {
+    /** Open threads, done threads, or both. Defaults to open. */
+    archived?: boolean;
+    /** One category key from the effective taxonomy — what the classifier decided. */
+    category?: string;
+    /** One category key from the effective taxonomy — what the submitter said. A different question. */
+    declaredCategory?: string;
+    /** One priority. */
+    priority?: SupportPriority;
+    /** One sentiment. */
+    sentiment?: SupportSentiment;
+    /** One channel — mail, or what signed-in users filed from inside the app. */
+    channel?: SupportChannel;
+    /** Which inbox address, for a Worker serving more than one. */
+    inbox?: string;
+    /** Free text over subjects and bodies. */
+    q?: string;
+    /** Where to resume from. */
+    cursor?: string;
+    /** How many to return. */
+    limit?: number;
+}
+/** A thread as the inbox lists it — the row, plus this viewer's own private state. */
+export interface ListedThread extends SupportThread {
+    /** Whether this viewer has read it. False when they have no flag row, which is the common case. */
+    read: boolean;
+    /** When this viewer's snooze expires, or null. */
+    snoozedUntil: Date | null;
+}
+/** One page of the inbox. */
+export interface ThreadPage {
+    /** The threads, newest first. */
+    threads: ListedThread[];
+    /** The cursor for the next page, or null when this was the last one. */
+    nextCursor: string | null;
+}
+/**
+ * List threads, as one viewer sees them.
+ *
+ * The viewer is a parameter rather than an afterthought because the per-viewer flags are **read
+ * here**: a snooze that was stored and never consulted is a button that does nothing, and `read` that
+ * is never projected is a column a dashboard cannot render. Both are left-joined, so a thread with no
+ * flag row for this viewer — the overwhelming majority — still appears, unread and unsnoozed.
+ */
+export declare function listThreads(db: SupportDatabase, query: ListThreadsQuery, options: {
+    fts: boolean;
+    viewer: string;
+    now: Date;
+    log?: Logger;
+}): Promise<ThreadPage>;
+/** A thread with everything a reading pane shows. */
+export interface ThreadDetail {
+    /** The thread row. */
+    thread: SupportThread;
+    /** Its messages, oldest first — a conversation reads downward. */
+    messages: SupportMessage[];
+    /** Its attachments, across every message. */
+    attachments: SupportAttachment[];
+}
+/** Read one thread in full. Throws `support/not_found` when it does not exist. */
+export declare function readThread(db: SupportDatabase, threadId: string): Promise<ThreadDetail>;
+/**
+ * List one account's own in-app conversations.
+ *
+ * **Two conditions on the `where`, and the second is not redundant.** `userId` alone would also return
+ * every *email* thread this capability linked to the account — and that link was matched against an
+ * address in a header nobody proved, so it names an account the sender merely claimed to be. Serving
+ * those to whoever currently holds the address would turn the mail path's known weakness into a read
+ * primitive, which is precisely the trade this channel exists to avoid making.
+ *
+ * Archived threads are included, unlike the operator inbox. An inbox hides done threads because it is a
+ * work queue; a person looking at their own requests is looking for the one that was answered.
+ */
+export declare function listOwnThreads(db: SupportDatabase, userId: string, query: {
+    cursor?: string;
+    limit?: number;
+}): Promise<{
+    threads: SupportThread[];
+    nextCursor: string | null;
+}>;
+/**
+ * Read one of an account's own in-app conversations.
+ *
+ * **A 404 for somebody else's thread, never a 403.** The two are the same answer on purpose: a 403
+ * confirms the id names a real conversation, and on an inbox of other people's correspondence that
+ * confirmation is itself the disclosure. The scoping is in the `where`, not in a check after the read,
+ * so there is no version of this that fetches the row first and forgets to compare.
+ */
+export declare function readOwnThread(db: SupportDatabase, threadId: string, userId: string): Promise<ThreadDetail>;
+/**
+ * Mark a thread done, or reopen it.
+ *
+ * The one shared piece of state in the model, and the write is unconditional rather than a
+ * compare-and-set: archiving something already archived is not a conflict, it is the same outcome,
+ * and a support console that threw on a double-click would be worse than one that did nothing.
+ */
+export declare function setArchived(db: SupportDatabase, threadId: string, archived: boolean, viewer: string, now: Date): Promise<SupportThread>;
+/** Set one viewer's private flags on a thread. Upserts on `(threadId, viewer)`. */
+export declare function setFlags(db: SupportDatabase, options: {
+    threadId: string;
+    viewer: string;
+    read?: boolean;
+    snoozedUntil?: Date | null;
+    newId: () => string;
+    now: Date;
+}): Promise<void>;
+//# sourceMappingURL=threads.d.ts.map

package/dist/store/threads.d.ts.map

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

package/dist/store/threads.js

@@ -0,0 +1,197 @@
+import { SupportNotFoundError } from "../error/errors.js";
+import { SupportAttachment } from "../data/attachment.js";
+import { SupportMessage } from "../data/message.js";
+import { SupportThread } from "../data/thread.js";
+import { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { isSearchable, searchPredicate } from "./search.js";
+import "./paging.js";
+import { sql } from "kysely";
+//#region src/store/threads.ts
+/**
+* Encode a cursor for the wire.
+*
+* Base64url over JSON, and **opaque by intent rather than by obscurity**: the point is that a client
+* cannot construct one by hand and therefore cannot come to depend on its shape, so the ordering can
+* change later without breaking every caller. It is not a secret — it holds a timestamp and an id
+* the caller was just given.
+*/
+function encodeCursor(cursor) {
+	return btoa(JSON.stringify(cursor)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decode a cursor. Returns undefined for anything malformed — a bad cursor is a first page, not a 500. */
+function decodeCursor(value) {
+	if (!value) return void 0;
+	try {
+		const json = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+		const parsed = JSON.parse(json);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const { lastMessageAt, id } = parsed;
+		if (typeof lastMessageAt !== "number" || typeof id !== "string") return void 0;
+		return {
+			lastMessageAt,
+			id
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* List threads, as one viewer sees them.
+*
+* The viewer is a parameter rather than an afterthought because the per-viewer flags are **read
+* here**: a snooze that was stored and never consulted is a button that does nothing, and `read` that
+* is never projected is a column a dashboard cannot render. Both are left-joined, so a thread with no
+* flag row for this viewer — the overwhelming majority — still appears, unread and unsnoozed.
+*/
+async function listThreads(db, query, options) {
+	try {
+		return await runListThreads(db, query, options);
+	} catch (error) {
+		if (options.fts && isMissingSearchTable(error)) {
+			options.log?.warn("support FTS index is configured but absent — falling back to a LIKE scan", { action: "Run `pithy support provision` to create and backfill it, or set `search.fts: false`." });
+			return runListThreads(db, query, {
+				...options,
+				fts: false
+			});
+		}
+		throw error;
+	}
+}
+/** Whether an error is SQLite saying the full-text index does not exist. */
+function isMissingSearchTable(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("no such table") && message.includes("pithy_support_search");
+}
+/** The listing itself, for one chosen search backend. */
+async function runListThreads(db, query, options) {
+	const limit = Math.min(Math.max(query.limit ?? 25, 1), 100);
+	const cursor = decodeCursor(query.cursor);
+	let builder = db.selectFrom(SUPPORT_THREADS_TABLE).leftJoin(SUPPORT_FLAGS_TABLE, (join) => join.onRef(`${SUPPORT_FLAGS_TABLE}.threadId`, "=", `${SUPPORT_THREADS_TABLE}.id`).on(`${SUPPORT_FLAGS_TABLE}.viewer`, "=", options.viewer)).selectAll(SUPPORT_THREADS_TABLE).select([`${SUPPORT_FLAGS_TABLE}.read as viewerRead`, `${SUPPORT_FLAGS_TABLE}.snoozedUntil as viewerSnoozedUntil`]).where((eb) => eb.or([eb(`${SUPPORT_FLAGS_TABLE}.snoozedUntil`, "is", null), eb(`${SUPPORT_FLAGS_TABLE}.snoozedUntil`, "<=", options.now.getTime())])).where(`${SUPPORT_THREADS_TABLE}.archived`, "=", query.archived === true ? 1 : 0);
+	if (query.category !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.category`, "=", query.category);
+	if (query.declaredCategory !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.declaredCategory`, "=", query.declaredCategory);
+	if (query.priority !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.priority`, "=", query.priority);
+	if (query.sentiment !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.sentiment`, "=", query.sentiment);
+	if (query.channel !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.channel`, "=", query.channel);
+	if (query.inbox !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.inboxAddress`, "=", query.inbox);
+	if (query.q !== void 0) {
+		if (isSearchable(query.q, options.fts)) builder = builder.where(searchPredicate(query.q, options));
+		else builder = builder.where(sql`1 = 0`);
+	}
+	if (cursor) builder = builder.where((eb) => eb.or([eb(`${SUPPORT_THREADS_TABLE}.lastMessageAt`, "<", cursor.lastMessageAt), eb.and([eb(`${SUPPORT_THREADS_TABLE}.lastMessageAt`, "=", cursor.lastMessageAt), eb(`${SUPPORT_THREADS_TABLE}.id`, "<", cursor.id)])]));
+	const rows = await builder.orderBy(`${SUPPORT_THREADS_TABLE}.lastMessageAt`, "desc").orderBy(`${SUPPORT_THREADS_TABLE}.id`, "desc").limit(limit + 1).execute();
+	const page = rows.slice(0, limit).map((row) => ({
+		...SupportThread.parse(row),
+		read: row.viewerRead === 1,
+		snoozedUntil: row.viewerSnoozedUntil == null ? null : new Date(Number(row.viewerSnoozedUntil))
+	}));
+	const last = page[page.length - 1];
+	return {
+		threads: page,
+		nextCursor: rows.length > limit && last ? encodeCursor({
+			lastMessageAt: last.lastMessageAt.getTime(),
+			id: last.id
+		}) : null
+	};
+}
+/** Read one thread in full. Throws `support/not_found` when it does not exist. */
+async function readThread(db, threadId) {
+	const row = await db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("id", "=", threadId).executeTakeFirst();
+	if (!row) throw new SupportNotFoundError({ detail: `no support thread ${threadId}` });
+	const [messages, attachments] = await Promise.all([db.selectFrom(SUPPORT_MESSAGES_TABLE).selectAll().where("threadId", "=", threadId).orderBy("receivedAt", "asc").orderBy("id", "asc").execute(), db.selectFrom(SUPPORT_ATTACHMENTS_TABLE).selectAll().where("threadId", "=", threadId).execute()]);
+	return {
+		thread: SupportThread.parse(row),
+		messages: messages.map((message) => SupportMessage.parse(message)),
+		attachments: attachments.map((attachment) => SupportAttachment.parse(attachment))
+	};
+}
+/**
+* List one account's own in-app conversations.
+*
+* **Two conditions on the `where`, and the second is not redundant.** `userId` alone would also return
+* every *email* thread this capability linked to the account — and that link was matched against an
+* address in a header nobody proved, so it names an account the sender merely claimed to be. Serving
+* those to whoever currently holds the address would turn the mail path's known weakness into a read
+* primitive, which is precisely the trade this channel exists to avoid making.
+*
+* Archived threads are included, unlike the operator inbox. An inbox hides done threads because it is a
+* work queue; a person looking at their own requests is looking for the one that was answered.
+*/
+async function listOwnThreads(db, userId, query) {
+	const limit = Math.min(Math.max(query.limit ?? 25, 1), 100);
+	const cursor = decodeCursor(query.cursor);
+	let builder = db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("userId", "=", userId).where("channel", "=", "app");
+	if (cursor) builder = builder.where((eb) => eb.or([eb("lastMessageAt", "<", cursor.lastMessageAt), eb.and([eb("lastMessageAt", "=", cursor.lastMessageAt), eb("id", "<", cursor.id)])]));
+	const rows = await builder.orderBy("lastMessageAt", "desc").orderBy("id", "desc").limit(limit + 1).execute();
+	const page = rows.slice(0, limit).map((row) => SupportThread.parse(row));
+	const last = page[page.length - 1];
+	return {
+		threads: page,
+		nextCursor: rows.length > limit && last ? encodeCursor({
+			lastMessageAt: last.lastMessageAt.getTime(),
+			id: last.id
+		}) : null
+	};
+}
+/**
+* Read one of an account's own in-app conversations.
+*
+* **A 404 for somebody else's thread, never a 403.** The two are the same answer on purpose: a 403
+* confirms the id names a real conversation, and on an inbox of other people's correspondence that
+* confirmation is itself the disclosure. The scoping is in the `where`, not in a check after the read,
+* so there is no version of this that fetches the row first and forgets to compare.
+*/
+async function readOwnThread(db, threadId, userId) {
+	const row = await db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("id", "=", threadId).where("userId", "=", userId).where("channel", "=", "app").executeTakeFirst();
+	if (!row) throw new SupportNotFoundError({ detail: `no app thread ${threadId} owned by ${userId}` });
+	const [messages, attachments] = await Promise.all([db.selectFrom(SUPPORT_MESSAGES_TABLE).selectAll().where("threadId", "=", threadId).orderBy("receivedAt", "asc").orderBy("id", "asc").execute(), db.selectFrom(SUPPORT_ATTACHMENTS_TABLE).selectAll().where("threadId", "=", threadId).execute()]);
+	return {
+		thread: SupportThread.parse(row),
+		messages: messages.map((message) => SupportMessage.parse(message)),
+		attachments: attachments.map((attachment) => SupportAttachment.parse(attachment))
+	};
+}
+/**
+* Mark a thread done, or reopen it.
+*
+* The one shared piece of state in the model, and the write is unconditional rather than a
+* compare-and-set: archiving something already archived is not a conflict, it is the same outcome,
+* and a support console that threw on a double-click would be worse than one that did nothing.
+*/
+async function setArchived(db, threadId, archived, viewer, now) {
+	const existing = await db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("id", "=", threadId).executeTakeFirst();
+	if (!existing) throw new SupportNotFoundError({ detail: `no support thread ${threadId}` });
+	await db.updateTable(SUPPORT_THREADS_TABLE).set({
+		archived: archived ? 1 : 0,
+		archivedAt: archived ? now.getTime() : null,
+		archivedBy: archived ? viewer : null,
+		updatedAt: now.getTime()
+	}).where("id", "=", threadId).execute();
+	return SupportThread.parse({
+		...existing,
+		archived: archived ? 1 : 0,
+		archivedAt: archived ? now.getTime() : null,
+		archivedBy: archived ? viewer : null,
+		updatedAt: now.getTime()
+	});
+}
+/** Set one viewer's private flags on a thread. Upserts on `(threadId, viewer)`. */
+async function setFlags(db, options) {
+	if (!await db.selectFrom("pithySupportThreads").select(["id"]).where("id", "=", options.threadId).executeTakeFirst()) throw new SupportNotFoundError({ detail: `no support thread ${options.threadId}` });
+	const read = options.read === void 0 ? void 0 : options.read ? 1 : 0;
+	const snoozed = options.snoozedUntil === void 0 ? void 0 : options.snoozedUntil?.getTime() ?? null;
+	await db.insertInto(SUPPORT_FLAGS_TABLE).values({
+		id: options.newId(),
+		threadId: options.threadId,
+		viewer: options.viewer,
+		read: read ?? 0,
+		snoozedUntil: snoozed ?? null,
+		createdAt: options.now.getTime(),
+		updatedAt: options.now.getTime()
+	}).onConflict((oc) => oc.columns(["threadId", "viewer"]).doUpdateSet((eb) => ({
+		read: read === void 0 ? eb.ref(`${SUPPORT_FLAGS_TABLE}.read`) : read,
+		snoozedUntil: snoozed === void 0 ? eb.ref(`${SUPPORT_FLAGS_TABLE}.snoozedUntil`) : snoozed,
+		updatedAt: options.now.getTime()
+	}))).execute();
+}
+//#endregion
+export { decodeCursor, encodeCursor, listOwnThreads, listThreads, readOwnThread, readThread, setArchived, setFlags };

package/dist/submission/encoding.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The largest base64 string worth decoding, derived from a decoded-byte bound.
+ *
+ * Checked **before** decoding, not after. `atob` materialises the whole result, so a client that sends
+ * fifty megabytes of base64 has already been allocated fifty megabytes of Worker memory by the time a
+ * post-hoc size check could refuse it — and the request that does that is the one an attacker sends.
+ * A little slack for padding and any whitespace a client's encoder inserted.
+ */
+export declare function maxEncodedLength(maxBytes: number): number;
+/**
+ * Decode one base64 attachment payload.
+ *
+ * Accepts the URL-safe alphabet too: a client that reached for `base64url` because its platform's
+ * default encoder produces it has not made a mistake worth a 400, and the two differ by two
+ * characters. Anything that is not base64 at all is a `validation/invalid_input`, which is what the
+ * route's own validator would have raised had the string been checkable there.
+ */
+export declare function decodeBase64(value: string, options: {
+    maxBytes: number;
+}): Uint8Array;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/submission/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/submission/encoding.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA2BrF"}