@pithy-sh/support 0.1.2 → 0.1.4

package/dist/store/paging.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/store/paging.ts
+/**
+* The inbox page bounds, in the one module that has no reason to import anything (#430).
+*
+* `http/schemas.ts` bounds a caller's `limit` with the same number the reader clamps to, and it used to
+* read it out of `store/threads.ts` — the Kysely reader, which brings `kysely`, `kysely-d1` and
+* `@cloudflare/workers-types` with it. A request schema is a client's business: a management client
+* building a call must be able to compile the shape it may send, in a browser, with no Worker types in
+* reach. So the two numbers moved and the reader kept the query.
+*
+* **Both moved, not only the one the schema needs.** They are read together — a default clamped into a
+* maximum, on one line, in two queries — and a pair split across two modules is how the next person
+* picks the wrong one.
+*/
+/** How many threads a page holds by default. */
+const DEFAULT_PAGE_SIZE = 25;
+/** The most a caller may ask for in one page. */
+const MAX_PAGE_SIZE = 100;
+//#endregion
+export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE };

package/dist/store/search.d.ts

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type Expression, type SqlBool } from "kysely";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * 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.
+ */
+export declare function ftsQuery(term: string): string;
+/** Whether a term has anything searchable left after tokenizing. */
+export declare function isSearchable(term: string, fts: boolean): boolean;
+/**
+ * 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.
+ */
+export declare function searchPredicate(term: string, options: {
+    fts: boolean;
+}): Expression<SqlBool>;
+/**
+ * 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.
+ */
+export declare function indexMessage(db: SupportDatabase, entry: {
+    threadId: string;
+    messageId: string;
+    subject: string;
+    body: string;
+}): Promise<void>;
+/**
+ * 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.
+ */
+export declare function reindexThread(db: SupportDatabase, threadId: string): Promise<number>;
+/**
+ * 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.
+ */
+export declare function reindexAll(db: SupportDatabase, options?: {
+    pageSize?: number;
+    onProgress?: (indexed: number) => void;
+}): Promise<number>;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/store/search.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAO,MAAM,QAAQ,CAAC;AAC5D,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AA+B9E;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS7C;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,CAAC,OAAO,CAAC,CAkB5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,eAAe,EACnB,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5E,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAC1E,OAAO,CAAC,MAAM,CAAC,CA4CjB"}

package/dist/store/search.js

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