@better-apps/comments 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Craswell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# @better-apps/comments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Comment threads on any record an app owns, such as an invoice, a ticket or a preview deploy, optionally pinned to a spot
+inside it. Comments store only the record's type and id; the app's subject types say who can see it, and the rules here
+who can comment. Every write is one atomic batch through
+[`@better-apps/database-drizzle`](../../adapters/database-drizzle/README.md), on Cloudflare D1 as on any other SQL
+database.
+
+## Usage
+
+```ts
+import { elementAnchor } from "@better-apps/anchors"
+import { comments, CommentsError } from "@better-apps/comments"
+import { createBetterApps } from "better-apps"
+
+export const app = createBetterApps({
+  database,
+  identity,
+  subjects: {
+    invoice: {
+      getOrgId: ({ subjectId }) => invoices.orgOf(subjectId),
+      canView: ({ actor, subjectId }) => invoices.canRead(actor, subjectId)
+    }
+  },
+  features: [
+    comments({
+      subjects: {
+        invoice: {
+          canComment: ({ actor, subjectId }) => invoices.canEdit(actor, subjectId),
+          canModerate: ({ actor }) => actor.roles.includes("admin"),
+          visibility: { staff: ({ actor }) => actor.roles.includes("staff") }
+        }
+      },
+      anchors: [elementAnchor()],
+      hooks: {
+        before: {
+          resolveThread: ({ actor, thread, input }) => {
+            if (thread?.createdBy !== actor?.userId) {
+              throw new CommentsError("FORBIDDEN", "Only the thread's creator can resolve it.")
+            }
+            return input
+          }
+        }
+      }
+    })
+  ]
+})
+
+const { thread } = await app.api.comments.createThread(
+  { subjectType: "invoice", subjectId: "inv_42", body: "Is this total right?" },
+  { request }
+)
+```
+
+Browsers call the same actions through `app.handler`, at `POST /api/apps/comments/<action>`. Run `better-apps generate`
+to add the `commentThread` and `comment` tables to your schema.
+
+## Actions
+
+- Reads: `listThreads` (by last activity or creation, 20 a page), `getThread` (comments oldest first, 50 a page),
+  `countThreads` (open and total for up to 50 records in one grouped query) and `suggestMentions`.
+- Writes: `createThread`, `reply`, `editComment`, `deleteComment`, `resolveThread`, `reopenThread`, `updateThread`,
+  `updateAnchor` and `deleteThread`.
+- Server only, through `app.api.comments`: `removeSubject`, `moveSubject`, `removeUser` and `recountThreads` for upkeep,
+  `canViewThread` for other features' recipient checks, and `toClientEvent` and `toClientEvents` for live updates.
+
+Reads return the users they name, from the identity adapter's `getUsers`. Users it can't find are left out, so show them
+as "Former user".
+
+## Access
+
+- The app declares each subject type in `createBetterApps`, with `canView`, `getOrgId` and `publicRead` (see
+  [Subjects](../../core/better-apps/README.md#subjects)). Comments add `canComment` for each, and optionally
+  `canModerate`, extra visibilities such as `staff`, a `metadata` schema and `canMention`.
+- One rule decides whether someone can see a thread: its organization must be its subject's, the subject's `canView`
+  must pass, and the actor must pass the thread's visibility check. Reads, mentions and live updates all use it.
+- Threads and comments are subject types too, `comments.thread` and `comments.comment` (`commentSubjectTypes`), so other
+  features can attach to them. Whoever can see a thread can see it and its comments, except deleted comments, which
+  nobody can see as records any more.
+- `NOT_FOUND` means the caller can't see it, and `FORBIDDEN` that they can see it but can't do this. Signed-out callers
+  get `UNAUTHENTICATED`, except signed-out readers of public subjects, who get text with names and no user ids.
+- Reads count the [access grants](../../core/better-apps/README.md#access-grants) the request carries, such as a share
+  link to the subject: `listThreads`, `getThread` and `countThreads`. Someone the app's rules refuse then reads the
+  subject's default threads as a signed-out reader does, with names and no user ids. Writes never count a grant, so a
+  link never lets anyone comment, reply, resolve or delete. A grant to the subject reaches its default threads and their
+  comments as `comments.thread` and `comments.comment` subjects too, so their reactions show.
+- Server code that passes neither an actor nor a request is trusted, so it skips access checks. It still needs an author
+  to write: a user, or an external or system author with a name and an optional id.
+- Before hooks run after the access check, keyed by action. They may change the input, but not the subject or thread. A
+  hook that throws a `CommentsError` returns its code; any other error returns `REJECTED_BY_HOOK`.
+
+## Writes
+
+- Ids are ULIDs a client may generate. Repeating a write with the same ids, author and content returns what the first
+  attempt wrote. Reusing your own id for different content is a `CONFLICT`, and an id someone else's row holds is
+  `INVALID_INPUT`.
+- `commentCount` and `lastActivityAt` change in the same batch as the comments they describe, so they're always exact.
+- Deleting a comment clears its text and keeps its place. Deleting a thread's last comment deletes the thread.
+- Replying to a resolved thread reopens it, running the `reopenThread` hook too.
+- Bodies are capped at 16 KB, anchors and metadata at 4 KB, and mentions at 20 per comment. Mentioned users who can't
+  view the thread aren't notified; only moderators are told who was dropped.
+
+## Formats and anchors
+
+- The built-in `text` format is plain text with mention tokens such as `@[user:u_123]`, from
+  [`@better-apps/mentions`](../mentions/README.md) (`mentionToken(id)` builds one). A literal `@[` is written `\@[`. Add
+  others with `defineFormat({ name, schema, sanitize, toText, mentions })`.
+- Anchors come from [`@better-apps/anchors`](../anchors/README.md). `elementAnchor()` pins threads to an element, found
+  with a selector that may use only ids, data attributes, tag names and structural positions. Add others with
+  `defineAnchor({ kind, schema })`.
+
+## Mentions
+
+Mention checks and suggestions come from `@better-apps/mentions`, so every feature that mentions people treats them the
+same. To let each user list the comments that mention them, add the mentions feature with comments as a source:
+
+```ts
+import { commentMentions, comments } from "@better-apps/comments"
+import { mentions } from "@better-apps/mentions"
+
+createBetterApps({
+  database,
+  identity,
+  subjects,
+  features: [comments(options), mentions({ sources: [commentMentions] })]
+})
+```
+
+Each mention's record is the comment, `comments.comment`, and its group the thread. Edits drop users a comment no longer
+mentions, and deleting a comment or thread removes its mentions.
+
+## In the browser
+
+`@better-apps/comments/client` keeps threads, comments, lists and counts in a framework-free store, and
+`@better-apps/comments/react` reads it with hooks. Neither has UI or an editor; apps bring their own composer and pin
+styles.
+
+```tsx
+import { useCreateThread, useThreads } from "@better-apps/comments/react"
+import { BetterAppsProvider } from "@better-apps/react"
+
+function InvoiceComments({ invoiceId }: { invoiceId: string }) {
+  const { threads, state } = useThreads({ subjectType: "invoice", subjectId: invoiceId })
+  const createThread = useCreateThread()
+  // Render the threads, and call createThread.mutate({ subjectType, subjectId, body }) from a form.
+}
+```
+
+- Writes are optimistic: the client makes each new thread's and comment's ULID, so a change shows at once under its
+  final id, and a retry can't duplicate it. A refused write is rolled back and rethrown with the server's code.
+  `isPending(id)` from `useThread` says which items are still waiting.
+- `applyEvent` takes events from `toClientEvent`, such as from a live updates feature, and ignores ones it has applied
+  and comments it already has. A thread that gets a new comment moves to the top of lists by activity.
+- `dehydrate()` and `hydrate(snapshot)` carry a server render's loads to the browser, so the first paint has threads.
+  Each Better Apps client has one store, so a router that hydrates `createCommentsClient(client)` and hooks under a
+  `BetterAppsProvider` with that client share it.
+- The store holds what the signed-in person could see. If someone else signs in without a page load, call `reset()` or
+  create a new Better Apps client, so they never see the previous person's threads. `reset()` also cancels calls still
+  under way, which reject with `ABORTED`; a mutation hook whose write was cancelled goes back to `idle`.
+- Hooks: `useThreads(subject, { status, order })`, `useThread(id)`, `useThreadCounts(subjectType, subjectIds)`, which
+  splits lists over 50, `useSuggestMentions`, and a mutation hook per write, from `useCreateThread()` to
+  `useDeleteThread()`, each with `mutate`, `status`, `error` and `reset`.
+- To place a pin, pass a thread to `useAnchorPosition` from `@better-apps/anchors/react`, or `resolveAnchor` from
+  `@better-apps/anchors/dom`.
+- Dates in core fields are `Date`s again in the store. Dates in additional fields stay ISO strings.
+
+## Events
+
+`thread.created`, `thread.updated`, `comment.created`, `comment.edited` and `comment.deleted` (both with the previous
+body), `comment.mentioned` (one per mention), `thread.resolved`, `thread.reopened`, `thread.anchorUpdated` (with the
+previous anchor), `thread.deleted`, `thread.moved`, `subject.moved`, `subject.removed` and `user.removed`. They're
+written to the core's outbox in the same batch as the change and delivered at least once. They stay on the server;
+`toClientEvent({ event, viewer, request? })` turns one into what a viewer's browser may see. With the viewer's request,
+grants it carries count as they do for reads. `toClientEvents({ event, viewers })` does the same for many viewers, each
+`{ actor, request? }`, in order, with their access checked together, so each granting feature answers for all of them in
+one call.
+
+`thread.deleted` and `thread.moved` list the thread's `commentIds`, so features attached to its comments, such as
+reactions, can clean up or move along. `removeSubject` emits `thread.deleted` for each thread it deletes, and
+`moveSubject` emits `thread.moved`, with `fromOrgId`, for each thread it moves.

package/dist/access.d.ts

@@ -0,0 +1,66 @@
+import type { Actor, SubjectArgs, SubjectRef, Subjects } from "better-apps";
+import type { CommentRules } from "./options.js";
+import type { CommentThread } from "./schema.js";
+/** What a caller may do with a subject's threads in one visibility. */
+export interface Access {
+    view: boolean;
+    comment: boolean;
+    moderate: boolean;
+    /** Whether the caller is signed out and the subject isn't public, so signing in might help. */
+    signInMayHelp: boolean;
+    /**
+     * Whether only a grant the request carries, such as a share link, lets the caller see the threads. Such a caller sees
+     * them as a signed-out reader does, and can't comment.
+     */
+    granted: boolean;
+}
+/** Who a call acts as. Server code that names no actor is trusted, so access checks pass. */
+export interface Caller {
+    actor: Actor | null;
+    trusted: boolean;
+}
+/** Access that allows nothing. */
+export declare const nothing: Access;
+/** The comment rules registered for a subject type, or `INVALID_INPUT`. */
+export declare function subjectOf(rules: Readonly<Record<string, CommentRules>>, subjectType: string): CommentRules;
+/** The organization that owns a subject, or `""` when the app has none. */
+export declare function orgOf(subjects: Subjects, caller: Caller, ref: SubjectRef): Promise<string>;
+/** Whether a visibility is `default` or one the subject type declares. */
+export declare function isDeclaredVisibility(rules: CommentRules, visibility: string): boolean;
+/** The visibilities an actor can see on a subject, `default` first. */
+export declare function visibleTo(rules: CommentRules, args: SubjectArgs): Promise<string[]>;
+/**
+ * What a caller may do with the threads of a subject in one visibility. Reads pass the request, so a grant it carries,
+ * such as a share link, lets the caller read the subject's default threads; writes leave it out.
+ */
+export declare function accessTo(rules: CommentRules, subjects: Subjects, caller: Caller, ref: SubjectRef, visibility: string, request?: Request | null): Promise<Access>;
+/** Refuses a read the caller can't make: `UNAUTHENTICATED` when signing in might help, else `NOT_FOUND`. */
+export declare function requireView(access: Access): void;
+/** How someone sees a thread: by the app's rules, only through a grant their request carries, or not at all. */
+export type ThreadView = "rules" | "granted" | null;
+/**
+ * The one rule for whether people can see threads: a thread's organization must be its subject's current one, the
+ * viewer must be able to see the subject, and must pass the thread's visibility check. Reads, mentions, notifications
+ * and live updates all use it. Each subject's `canViewMany` runs once.
+ */
+export declare function canViewThreads(rules: Readonly<Record<string, CommentRules>>, subjects: Subjects, pairs: readonly {
+    actor: Actor | null;
+    thread: CommentThread;
+}[]): Promise<boolean[]>;
+/**
+ * How each viewer sees a thread, by the rule `canViewThreads` applies. A pair with the viewer's request may also see a
+ * default thread through a grant it carries, such as a share link to its subject, asked once for the threads the
+ * app's rules refuse. Only reads about the person who made the request pass it.
+ */
+export declare function viewThreads(rules: Readonly<Record<string, CommentRules>>, subjects: Subjects, pairs: readonly {
+    actor: Actor | null;
+    thread: CommentThread;
+    request?: Request | null | undefined;
+}[]): Promise<ThreadView[]>;
+/** Whether someone can see a thread, by the rule `canViewThreads` applies. */
+export declare function canViewThread(rules: Readonly<Record<string, CommentRules>>, subjects: Subjects, actor: Actor | null, thread: CommentThread): Promise<boolean>;
+/**
+ * Which of several actors may be mentioned in a thread: `canMention` when the subject type has it, else whether they
+ * can view the thread, checked with one `canViewMany` call.
+ */
+export declare function mentionable(rules: Readonly<Record<string, CommentRules>>, subjects: Subjects, actors: readonly Actor[], thread: CommentThread): Promise<Actor[]>;

package/dist/access.js

@@ -0,0 +1,186 @@
+import { CommentsError } from "./errors.js";
+const everything = { view: true, comment: true, moderate: true, signInMayHelp: false, granted: false };
+/** Access that allows nothing. */
+export const nothing = { view: false, comment: false, moderate: false, signInMayHelp: false, granted: false };
+/** Access that lets the caller read a subject's default threads through a grant, and nothing more. */
+const grantedView = { ...nothing, view: true, granted: true };
+/** The comment rules registered for a subject type, or `INVALID_INPUT`. */
+export function subjectOf(rules, subjectType) {
+    if (!Object.hasOwn(rules, subjectType)) {
+        throw new CommentsError("INVALID_INPUT", `Comments aren't set up for the "${subjectType}" subject type.`);
+    }
+    return rules[subjectType];
+}
+/** The organization that owns a subject, or `""` when the app has none. */
+export async function orgOf(subjects, caller, ref) {
+    return (await subjects.getOrgId(ref, caller.actor)) ?? "";
+}
+/** Whether a visibility is `default` or one the subject type declares. */
+export function isDeclaredVisibility(rules, visibility) {
+    return visibility === "default" || (rules.visibility !== undefined && Object.hasOwn(rules.visibility, visibility));
+}
+/** The visibilities an actor can see on a subject, `default` first. */
+export async function visibleTo(rules, args) {
+    const declared = Object.entries(rules.visibility ?? {});
+    const passed = await Promise.all(declared.map(async ([, check]) => check(args)));
+    return ["default", ...declared.flatMap(([name], index) => (passed[index] ? [name] : []))];
+}
+/**
+ * What a caller may do with the threads of a subject in one visibility. Reads pass the request, so a grant it carries,
+ * such as a share link, lets the caller read the subject's default threads; writes leave it out.
+ */
+export async function accessTo(rules, subjects, caller, ref, visibility, request) {
+    const access = await accessByRules(rules, subjects, caller, ref, visibility);
+    if (access.view || !request || visibility !== "default") {
+        return access;
+    }
+    return (await subjects.canView(caller.actor, ref, { request })) ? grantedView : access;
+}
+async function accessByRules(rules, subjects, caller, ref, visibility) {
+    if (caller.trusted) {
+        return everything;
+    }
+    const { actor } = caller;
+    if (!actor) {
+        const isPublic = await subjects.isPublic(ref);
+        return { ...nothing, view: isPublic && visibility === "default", signInMayHelp: !isPublic };
+    }
+    const args = { actor, ...ref };
+    const check = visibility === "default" ? undefined : rules.visibility?.[visibility];
+    const [view, visible] = await Promise.all([
+        subjects.canView(actor, ref),
+        check ? check(args) : visibility === "default"
+    ]);
+    if (!view || !visible) {
+        return nothing;
+    }
+    const [comment, moderate] = await Promise.all([rules.canComment(args), rules.canModerate?.(args) ?? false]);
+    return { view: true, comment, moderate, signInMayHelp: false, granted: false };
+}
+/** Refuses a read the caller can't make: `UNAUTHENTICATED` when signing in might help, else `NOT_FOUND`. */
+export function requireView(access) {
+    if (!access.view) {
+        throw access.signInMayHelp
+            ? new CommentsError("UNAUTHENTICATED", "Sign in to see these comments.")
+            : new CommentsError("NOT_FOUND", "That thread doesn't exist, or you can't see it.");
+    }
+}
+/**
+ * The one rule for whether people can see threads: a thread's organization must be its subject's current one, the
+ * viewer must be able to see the subject, and must pass the thread's visibility check. Reads, mentions, notifications
+ * and live updates all use it. Each subject's `canViewMany` runs once.
+ */
+export async function canViewThreads(rules, subjects, pairs) {
+    return (await viewThreads(rules, subjects, pairs)).map((view) => view !== null);
+}
+/**
+ * How each viewer sees a thread, by the rule `canViewThreads` applies. A pair with the viewer's request may also see a
+ * default thread through a grant it carries, such as a share link to its subject, asked once for the threads the
+ * app's rules refuse. Only reads about the person who made the request pass it.
+ */
+export async function viewThreads(rules, subjects, pairs) {
+    const placed = await inPlace(rules, subjects, pairs);
+    const allowed = await viewThreadsByRules(rules, subjects, pairs, placed);
+    const views = allowed.map((seen) => (seen ? "rules" : null));
+    const candidates = pairs.flatMap(({ thread, request }, index) => !allowed[index] && request && placed[index] && thread.visibility === "default" ? [index] : []);
+    const granted = await canViewDistinct(subjects, candidates.map((index) => {
+        const { actor, thread, request } = pairs[index];
+        return { actor, subjectType: thread.subjectType, subjectId: thread.subjectId, request };
+    }));
+    for (const [position, index] of candidates.entries()) {
+        if (granted[position]) {
+            views[index] = "granted";
+        }
+    }
+    return views;
+}
+/**
+ * Whether each thread is on a subject type comments are set up for, and in its subject's current organization, with
+ * one organization lookup per subject type for the threads' distinct subjects.
+ */
+async function inPlace(rules, subjects, pairs) {
+    // Threads on a subject type comments are no longer set up for can't be seen.
+    const known = pairs.map(({ thread }) => Object.hasOwn(rules, thread.subjectType) && subjects.has(thread.subjectType));
+    const keyOf = ({ subjectType, subjectId }) => JSON.stringify([subjectType, subjectId]);
+    const refs = new Map();
+    for (const [index, { thread }] of pairs.entries()) {
+        if (known[index]) {
+            refs.set(keyOf(thread), { subjectType: thread.subjectType, subjectId: thread.subjectId });
+        }
+    }
+    const signedIn = pairs.find(({ actor }) => actor !== null)?.actor ?? null;
+    const found = await subjects.getOrgIds([...refs.values()], signedIn);
+    const orgs = new Map([...refs.keys()].map((key, index) => [key, found[index] ?? ""]));
+    return pairs.map(({ thread }, index) => known[index] === true && orgs.get(keyOf(thread)) === thread.orgId);
+}
+/**
+ * `canViewMany` for checks that may repeat, such as one per comment on the same record, asking about each distinct
+ * actor, subject and request once.
+ */
+async function canViewDistinct(subjects, checks) {
+    if (checks.length === 0) {
+        return [];
+    }
+    const ids = new Map();
+    const idOf = (value) => {
+        if (!value) {
+            return null;
+        }
+        if (!ids.has(value)) {
+            ids.set(value, ids.size);
+        }
+        return ids.get(value) ?? null;
+    };
+    const distinct = new Map();
+    const keys = checks.map((check) => {
+        const key = JSON.stringify([idOf(check.actor), idOf(check.request), check.subjectType, check.subjectId]);
+        distinct.set(key, check);
+        return key;
+    });
+    const answers = await subjects.canViewMany([...distinct.values()]);
+    const byKey = new Map([...distinct.keys()].map((key, index) => [key, answers[index] === true]));
+    return keys.map((key) => byKey.get(key) === true);
+}
+async function viewThreadsByRules(rules, subjects, pairs, placed) {
+    const candidates = pairs.flatMap((_, index) => (placed[index] ? [index] : []));
+    const viewers = await canViewDistinct(subjects, candidates.map((index) => {
+        const { actor, thread } = pairs[index];
+        return { actor, subjectType: thread.subjectType, subjectId: thread.subjectId };
+    }));
+    const allowed = pairs.map(() => false);
+    await Promise.all(candidates.map(async (index, position) => {
+        const { actor, thread } = pairs[index];
+        if (!viewers[position]) {
+            return;
+        }
+        if (thread.visibility === "default") {
+            allowed[index] = true;
+            return;
+        }
+        const declared = rules[thread.subjectType]?.visibility ?? {};
+        const check = Object.hasOwn(declared, thread.visibility) ? declared[thread.visibility] : undefined;
+        allowed[index] =
+            actor !== null &&
+                check !== undefined &&
+                Boolean(await check({ actor, subjectType: thread.subjectType, subjectId: thread.subjectId }));
+    }));
+    return allowed;
+}
+/** Whether someone can see a thread, by the rule `canViewThreads` applies. */
+export async function canViewThread(rules, subjects, actor, thread) {
+    const [allowed] = await canViewThreads(rules, subjects, [{ actor, thread }]);
+    return allowed === true;
+}
+/**
+ * Which of several actors may be mentioned in a thread: `canMention` when the subject type has it, else whether they
+ * can view the thread, checked with one `canViewMany` call.
+ */
+export async function mentionable(rules, subjects, actors, thread) {
+    const { canMention } = subjectOf(rules, thread.subjectType);
+    if (canMention) {
+        const allowed = await Promise.all(actors.map(async (actor) => canMention({ actor, thread })));
+        return actors.filter((_, index) => allowed[index]);
+    }
+    const allowed = await canViewThreads(rules, subjects, actors.map((actor) => ({ actor, thread })));
+    return actors.filter((_, index) => allowed[index]);
+}

package/dist/client.d.ts

@@ -0,0 +1,140 @@
+import type { BetterApp, IdentityUser } from "better-apps";
+import { type BetterAppsClient, type CallOptions, type Serialized, type Store } from "better-apps/client";
+import type { SuggestMentionsInput, ThreadCounts } from "./feature.js";
+import type { CommentTarget, CommentsOptions, CommentsTypes, CreateThreadInput, EditCommentInput, ReplyInput, ThreadTarget, TypesOf, UpdateAnchorInput, UpdateThreadInput } from "./options.js";
+import type { ClientEvent } from "./reads.js";
+import type { Comment, CommentThread } from "./schema.js";
+export { textFormat } from "./formats.js";
+export { isUlid, ulid } from "./ulid.js";
+type CommentsFeatureOf<App> = App extends BetterApp<infer Features> ? Extract<Features[number], {
+    id: "comments";
+}> : never;
+/** The comments types of an app, from `typeof app`. */
+export type AppCommentsTypes<App> = CommentsFeatureOf<App> extends {
+    options: infer Options extends CommentsOptions;
+} ? TypesOf<Options> : CommentsTypes;
+/** Which record a list of threads is about. */
+export interface Subject<SubjectType extends string = string> {
+    subjectType: SubjectType;
+    subjectId: string;
+}
+/** How a list of threads is filtered and ordered. */
+export interface ListOptions {
+    status?: "open" | "resolved" | undefined;
+    order?: "activity" | "created" | undefined;
+}
+/** Where a load stands. `error` holds the client error when it failed. */
+export type LoadState = "idle" | "loading" | "ready" | "error";
+/** A loaded list of a subject's threads, as ids into `threads`. */
+export interface ThreadList {
+    subjectType: string;
+    subjectId: string;
+    status: "open" | "resolved" | null;
+    order: "activity" | "created";
+    ids: string[];
+    cursor: string | null;
+    state: LoadState;
+    error: Error | null;
+}
+/** A thread's loaded comments, oldest first, as ids into `comments`. */
+export interface ThreadComments {
+    ids: string[];
+    cursor: string | null;
+    state: LoadState;
+    error: Error | null;
+}
+/** Everything the store holds. Dates are `Date`s again, except in additional fields. */
+export interface CommentsState<Thread = CommentThread, Message = Comment> {
+    threads: Readonly<Record<string, Thread>>;
+    comments: Readonly<Record<string, Message>>;
+    threadComments: Readonly<Record<string, ThreadComments>>;
+    lists: Readonly<Record<string, ThreadList>>;
+    counts: Readonly<Record<string, ThreadCounts & {
+        state: LoadState;
+    }>>;
+    /** Names and avatars by user id, from reads. */
+    users: Readonly<Record<string, IdentityUser>>;
+    /** Ids of threads and comments written here and not yet confirmed by the server. */
+    pending: Readonly<Record<string, true>>;
+}
+/** A store snapshot as JSON carries it, for server rendering. */
+export type DehydratedComments = Serialized<CommentsState>;
+/** Keys a list by its subject and options. */
+export declare function listKey(subject: Subject, options?: ListOptions): string;
+/** Keys a subject's counts. */
+export declare function countKey(subjectType: string, subjectId: string): string;
+/** The comments client: a store plus the actions that fill it. */
+export type CommentsClient<Types extends CommentsTypes = CommentsTypes> = ReturnType<typeof createCommentsClientFor<Types>>;
+/**
+ * Creates the comments store for a Better Apps client. Pass `typeof app` as the client's type to get the app's subject
+ * types, anchors, formats and additional fields. Each Better Apps client has one store, so calling this again with the
+ * same client, as `useComments` does, returns the store already made, with whatever a server render hydrated into it.
+ *
+ * The store holds what the signed-in person could see. When someone else signs in without a page load, call `reset()`
+ * or create a new Better Apps client, so they never see the previous person's threads.
+ */
+export declare function createCommentsClient<App = BetterApp>(client: BetterAppsClient<App>): CommentsClient<AppCommentsTypes<App>>;
+declare function createCommentsClientFor<Types extends CommentsTypes>(call: (feature: string, action: string, input: unknown, options: CallOptions) => Promise<unknown>): {
+    store: Store<CommentsState<CommentThread & Types["threadFields"], Comment & Types["commentFields"]>>;
+    /** Loads the first page of a subject's threads. */
+    loadThreads(subject: Subject<Types["subjectType"]>, options?: ListOptions): Promise<void>;
+    /** Loads the next page of a list loaded with `loadThreads`. */
+    loadMoreThreads(subject: Subject<Types["subjectType"]>, options?: ListOptions): Promise<void>;
+    /** Loads a thread and the first page of its comments. */
+    loadThread(threadId: string): Promise<void>;
+    /** Loads the next page of a thread's comments. */
+    loadMoreComments(threadId: string): Promise<void>;
+    /** Loads open and total counts for many subjects, 50 per call. */
+    loadCounts(subjectType: Types["subjectType"], subjectIds: readonly string[]): Promise<void>;
+    /** Starts a thread. It shows at once under its final id, and is rolled back if the server refuses it. */
+    createThread(input: CreateThreadInput<Types>): Promise<{
+        thread: CommentThread & Types["threadFields"];
+        comment: Comment & Types["commentFields"];
+        droppedMentions: string[];
+    }>;
+    /** Replies to a thread, reopening it if it was resolved. */
+    reply(input: ReplyInput<Types>): Promise<{
+        thread: CommentThread & Types["threadFields"];
+        comment: Comment & Types["commentFields"];
+        droppedMentions: string[];
+    }>;
+    editComment(input: EditCommentInput<Types>): Promise<{
+        comment: Comment & Types["commentFields"];
+        droppedMentions: string[];
+    }>;
+    deleteComment(input: CommentTarget): Promise<{
+        comment: Comment & Types["commentFields"];
+        threadDeleted: boolean;
+    }>;
+    resolveThread: (input: ThreadTarget) => Promise<CommentThread & Types["threadFields"]>;
+    reopenThread: (input: ThreadTarget) => Promise<CommentThread & Types["threadFields"]>;
+    updateThread(input: UpdateThreadInput<Types>): Promise<CommentThread & Types["threadFields"]>;
+    updateAnchor(input: UpdateAnchorInput<Types>): Promise<CommentThread & Types["threadFields"]>;
+    deleteThread(input: ThreadTarget): Promise<{
+        threadId: string;
+    }>;
+    /**
+     * Suggests users to mention in a thread, or on a subject before its thread exists. A search that a `reset()`
+     * overtakes suggests nobody, since it ran as the previous person.
+     */
+    suggestMentions(input: SuggestMentionsInput<Types["subjectType"]>): Promise<IdentityUser[]>;
+    /**
+     * Applies a live update from `toClientEvent`. Events it has already applied, and comments it already has, are
+     * ignored, so an event that arrives before the server's own answer doesn't duplicate a comment.
+     */
+    applyEvent(event: ClientEvent | Serialized<ClientEvent>): void;
+    /** The store's state as JSON can carry it, to send a server render's loads to the browser. */
+    dehydrate(): DehydratedComments;
+    /**
+     * Empties the store, such as when the signed-in person changes without a page load. Lists and threads that are on
+     * screen load again for the new person. Calls still under way are cancelled and reject with an `ABORTED` error.
+     */
+    reset(): void;
+    /**
+     * Calls `listener` after each `reset()`, such as to clear state kept outside the store that the previous person could
+     * see. Returns a function that stops it.
+     */
+    onReset(listener: () => void): () => void;
+    /** Merges a snapshot from `dehydrate`, such as one a server render loaded. */
+    hydrate(snapshot: DehydratedComments): void;
+};