@better-apps/comments 0.0.0-stage → 0.0.0

package/dist/formats.d.ts

@@ -0,0 +1,26 @@
+import type { StandardSchemaV1 } from "better-apps";
+/**
+ * What a comment body is and how it's made safe. The server never depends on an editor: a format checks and sanitizes
+ * a body, and turns it into plain text and mentions, so search, emails and notifications work with any editor.
+ */
+export interface BodyFormat<Name extends string = string, Body = unknown> {
+    name: Name;
+    /** Checks a body's shape. */
+    schema: StandardSchemaV1<unknown, Body>;
+    /** Makes a checked body safe to store and show, such as by removing markup the format doesn't allow. */
+    sanitize?(body: Body): Body;
+    /**
+     * Plain text for search, emails and previews. Without `names`, mentions stay as tokens, so a removed user's name is
+     * never stored. With it, they become names, and users it can't name show as "Former user".
+     */
+    toText(body: Body, names?: (userId: string) => string | undefined): string;
+    /** The ids of the users the body mentions, each once, in order. */
+    mentions(body: Body): string[];
+}
+/** Declares a body format and keeps its name and body types for inference. */
+export declare function defineFormat<const Name extends string, Body>(format: BodyFormat<Name, Body>): BodyFormat<Name, Body>;
+/**
+ * Plain text with mention tokens such as `@[user:u_123]`, built with `mentionToken` from `@better-apps/mentions`. It
+ * holds no markup, so there's nothing to sanitize away.
+ */
+export declare const textFormat: BodyFormat<"text", string>;

package/dist/formats.js

@@ -0,0 +1,25 @@
+import { parseMentions, replaceMentions } from "@better-apps/mentions";
+/** Declares a body format and keeps its name and body types for inference. */
+export function defineFormat(format) {
+    return format;
+}
+const textSchema = {
+    "~standard": {
+        version: 1,
+        vendor: "better-apps",
+        validate: (value) => typeof value === "string" && value.trim() !== ""
+            ? { value }
+            : { issues: [{ message: "A text comment needs some text." }] }
+    }
+};
+/**
+ * Plain text with mention tokens such as `@[user:u_123]`, built with `mentionToken` from `@better-apps/mentions`. It
+ * holds no markup, so there's nothing to sanitize away.
+ */
+export const textFormat = defineFormat({
+    name: "text",
+    schema: textSchema,
+    sanitize: (body) => body.replace(/\r\n?/g, "\n").trim(),
+    toText: (body, names) => (names ? replaceMentions(body, names) : body),
+    mentions: parseMentions
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { limits } from "./content.js";
+export { CommentsError, type CommentsErrorCode } from "./errors.js";
+export { commentEvents, type CommentEventData, type CommentsEventData, type StoredAnchor, type ThreadDeletedData, type ThreadEventData, type ThreadMovedData } from "./events.js";
+export { comments, type CommentsFeature, type CountThreadsInput, type GetThreadInput, type ListThreadsInput, type SuggestMentionsInput, type ThreadCounts, type WriteResult } from "./feature.js";
+export { defineFormat, textFormat, type BodyFormat } from "./formats.js";
+export { commentMentions } from "./mentions.js";
+export type { BeforeHooks, CommentRules, CommentTarget, CommentsOptions, CommentsTypes, CreateThreadInput, EditCommentInput, HookArgs, ReplyInput, ThreadTarget, TypesOf, UpdateAnchorInput, UpdateThreadInput } from "./options.js";
+export type { ClientEvent, LiveViewer, ThreadPage, ThreadWithComments } from "./reads.js";
+export { commentModel, commentsSchema, threadModel, type AdditionalFields, type Comment, type CommentThread, type InferFields } from "./schema.js";
+export { commentSubjectTypes } from "./subjects.js";
+export { isUlid, ulid } from "./ulid.js";
+export type { UpkeepStep } from "./upkeep.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { limits } from "./content.js";
+export { CommentsError } from "./errors.js";
+export { commentEvents } from "./events.js";
+export { comments } from "./feature.js";
+export { defineFormat, textFormat } from "./formats.js";
+export { commentMentions } from "./mentions.js";
+export { commentModel, commentsSchema, threadModel } from "./schema.js";
+export { commentSubjectTypes } from "./subjects.js";
+export { isUlid, ulid } from "./ulid.js";

package/dist/inputs.d.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+export declare const inputs: {
+    listThreads: z.ZodObject<{
+        subjectType: z.ZodString;
+        subjectId: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>>;
+        anchorKind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        where: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        order: z.ZodOptional<z.ZodEnum<{
+            activity: "activity";
+            created: "created";
+        }>>;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    getThread: z.ZodObject<{
+        threadId: z.ZodString;
+        cursor: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    countThreads: z.ZodObject<{
+        subjectType: z.ZodString;
+        subjectIds: z.ZodArray<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>>;
+    }, z.core.$strip>;
+    createThread: z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        body: z.ZodUnknown;
+        id: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+        commentId: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+        subjectType: z.ZodString;
+        subjectId: z.ZodString;
+        visibility: z.ZodOptional<z.ZodString>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            kind: z.ZodString;
+            value: z.ZodUnknown;
+            version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+        metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        commentFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    reply: z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        body: z.ZodUnknown;
+        id: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+        threadId: z.ZodString;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    editComment: z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        body: z.ZodUnknown;
+        commentId: z.ZodString;
+    }, z.core.$strip>;
+    deleteComment: z.ZodObject<{
+        commentId: z.ZodString;
+    }, z.core.$strip>;
+    thread: z.ZodObject<{
+        threadId: z.ZodString;
+    }, z.core.$strip>;
+    updateThread: z.ZodObject<{
+        threadId: z.ZodString;
+        metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        visibility: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    updateAnchor: z.ZodObject<{
+        threadId: z.ZodString;
+        anchor: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodString;
+            value: z.ZodUnknown;
+            version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    suggestMentions: z.ZodUnion<readonly [z.ZodObject<{
+        threadId: z.ZodString;
+        query: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        subjectType: z.ZodString;
+        subjectId: z.ZodString;
+        query: z.ZodString;
+    }, z.core.$strip>]>;
+    removeSubject: z.ZodObject<{
+        subjectType: z.ZodString;
+        subjectId: z.ZodString;
+    }, z.core.$strip>;
+    moveSubject: z.ZodObject<{
+        subjectType: z.ZodString;
+        subjectId: z.ZodString;
+        toOrgId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    removeUser: z.ZodObject<{
+        userId: z.ZodString;
+    }, z.core.$strip>;
+    recountThreads: z.ZodUnion<readonly [z.ZodObject<{
+        threadIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        subjectType: z.ZodString;
+        subjectId: z.ZodString;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+};

package/dist/inputs.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { limits } from "./content.js";
+import { isUlid } from "./ulid.js";
+// Shapes only. Bodies, anchors, metadata and additional fields are checked by their format, anchor kind, schema or
+// field type once any hook has run.
+const newId = z.string().refine(isUlid, "Ids are ULIDs.");
+const rowId = z.string().min(1).max(64);
+const subjectType = z.string().min(1).max(64);
+const subjectId = z.string().min(1).max(255);
+const cursor = z.string().min(1).max(512);
+const record = z.record(z.string(), z.unknown());
+const anchor = z.object({ kind: z.string().min(1).max(64), value: z.unknown(), version: z.string().max(255).nullish() });
+const content = { format: z.string().min(1).max(64).optional(), body: z.unknown() };
+export const inputs = {
+    listThreads: z.object({
+        subjectType,
+        subjectId,
+        status: z.enum(["open", "resolved"]).optional(),
+        anchorKind: z.string().min(1).max(64).nullable().optional(),
+        where: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+        order: z.enum(["activity", "created"]).optional(),
+        cursor: cursor.optional(),
+        limit: z.number().int().min(1).max(limits.maxThreadsPerPage).optional()
+    }),
+    getThread: z.object({
+        threadId: rowId,
+        cursor: cursor.optional(),
+        limit: z.number().int().min(1).max(limits.maxCommentsPerPage).optional()
+    }),
+    countThreads: z.object({
+        subjectType,
+        subjectIds: z.array(subjectId).min(1).max(limits.subjectsPerCount),
+        status: z.enum(["open", "resolved"]).optional()
+    }),
+    createThread: z.object({
+        id: newId.optional(),
+        commentId: newId.optional(),
+        subjectType,
+        subjectId,
+        visibility: z.string().min(1).max(64).optional(),
+        anchor: anchor.nullish(),
+        metadata: record.nullish(),
+        fields: record.optional(),
+        commentFields: record.optional(),
+        ...content
+    }),
+    reply: z.object({ id: newId.optional(), threadId: rowId, fields: record.optional(), ...content }),
+    editComment: z.object({ commentId: rowId, ...content }),
+    deleteComment: z.object({ commentId: rowId }),
+    thread: z.object({ threadId: rowId }),
+    updateThread: z.object({
+        threadId: rowId,
+        metadata: record.nullish(),
+        visibility: z.string().min(1).max(64).optional(),
+        fields: record.optional()
+    }),
+    updateAnchor: z.object({ threadId: rowId, anchor: anchor.nullable() }),
+    suggestMentions: z.union([
+        z.object({ threadId: rowId, query: z.string().max(100) }),
+        z.object({ subjectType, subjectId, query: z.string().max(100) })
+    ]),
+    removeSubject: z.object({ subjectType, subjectId }),
+    moveSubject: z.object({ subjectType, subjectId, toOrgId: z.string().max(255).nullable() }),
+    removeUser: z.object({ userId: z.string().min(1).max(255) }),
+    recountThreads: z.union([
+        z.object({ threadIds: z.array(rowId).min(1).max(limits.maxThreadsPerPage) }),
+        z.object({ subjectType, subjectId, cursor: cursor.optional() })
+    ])
+};

package/dist/mentions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Records comments' mentions for the mentions feature, so each user can list where they were mentioned:
+ * `mentions({ sources: [commentMentions] })`. A mention's record is the comment, and its group the thread.
+ */
+export declare const commentMentions: import("@better-apps/mentions").MentionSource;

package/dist/mentions.js

@@ -0,0 +1,48 @@
+import { defineMentionSource, parseMentions } from "@better-apps/mentions";
+import { commentSubjectTypes } from "./subjects.js";
+const subjectType = commentSubjectTypes.comment;
+/**
+ * Records comments' mentions for the mentions feature, so each user can list where they were mentioned:
+ * `mentions({ sources: [commentMentions] })`. A mention's record is the comment, and its group the thread.
+ */
+export const commentMentions = defineMentionSource({
+    feature: "comments",
+    subjectTypes: [subjectType],
+    events: {
+        "comment.mentioned": (event) => {
+            const { userId, orgId, thread, comment } = event.data;
+            return {
+                add: [
+                    {
+                        userId,
+                        orgId: orgId === "" ? null : orgId,
+                        authorId: comment.authorType === "user" ? comment.authorId : null,
+                        subjectType,
+                        subjectId: comment.id,
+                        groupId: thread.id,
+                        excerpt: comment.bodyText
+                    }
+                ]
+            };
+        },
+        // Body text keeps mentions as tokens in every format, so it says who an edited comment still mentions.
+        "comment.edited": (event) => {
+            const { comment } = event.data;
+            return {
+                edit: [{ subjectType, subjectId: comment.id, keep: parseMentions(comment.bodyText), excerpt: comment.bodyText }]
+            };
+        },
+        "comment.deleted": (event) => {
+            const { comment } = event.data;
+            return { remove: [{ subjectType, subjectId: comment.id }] };
+        },
+        "thread.deleted": (event) => {
+            const { thread } = event.data;
+            return { removeGroups: [thread.id] };
+        },
+        "user.removed": (event) => {
+            const { userId } = event.data;
+            return { removeUsers: [userId] };
+        }
+    }
+});

package/dist/options.d.ts

@@ -0,0 +1,161 @@
+import type { AnchorKind } from "@better-apps/anchors";
+import type { Actor, Author, StandardSchemaV1, SubjectArgs } from "better-apps";
+import type { BodyFormat } from "./formats.js";
+import type { AdditionalFields, CommentThread, InferFields } from "./schema.js";
+type Check<Args> = (args: Args) => boolean | Promise<boolean>;
+/**
+ * How comments work on one subject type, such as `invoice`. Who can see a subject, and so its threads, comes from the
+ * app's subject type; these rules add who can comment, moderate and see restricted threads. Comments enforce them on
+ * every action.
+ */
+export interface CommentRules {
+    /** Whether the actor can create threads, reply, and resolve or reopen threads. */
+    canComment: Check<SubjectArgs>;
+    /** Whether the actor can delete any comment or thread, move any anchor and change a thread's visibility. Nobody, by default. */
+    canModerate?: Check<SubjectArgs> | undefined;
+    /** Extra visibilities, such as `staff`, each with a check saying who can see threads in it. */
+    visibility?: Readonly<Record<string, Check<SubjectArgs>>> | undefined;
+    /** A schema that lets clients write a thread's `metadata`. Without one, only server code writes it. */
+    metadata?: StandardSchemaV1<unknown, Record<string, unknown>> | undefined;
+    /** Whether a user can be mentioned in a thread. The default is whether they can view it. */
+    canMention?: Check<{
+        actor: Actor;
+        thread: CommentThread;
+    }> | undefined;
+}
+/** What every before hook receives. */
+export interface HookArgs<Input> {
+    /** The signed-in user, or `null` for server code that names an author. */
+    actor: Actor | null;
+    author: Author;
+    /** The thread the action targets, or `null` for `createThread`. */
+    thread: CommentThread | null;
+    input: Input;
+}
+type Hook<Input> = (args: HookArgs<Input>) => Input | Promise<Input>;
+/**
+ * Checks and changes before writes, keyed by action. A hook runs after the access check, so it only sees callers who
+ * may act. It returns the input, changed or not, or throws. It can't change the subject or thread the action targets.
+ */
+export interface BeforeHooks<Types extends CommentsTypes = CommentsTypes> {
+    createThread?: Hook<CreateThreadInput<Types>> | undefined;
+    reply?: Hook<ReplyInput<Types>> | undefined;
+    editComment?: Hook<EditCommentInput<Types>> | undefined;
+    deleteComment?: Hook<CommentTarget> | undefined;
+    resolveThread?: Hook<ThreadTarget> | undefined;
+    /** Also runs when a reply reopens a resolved thread, so a rule on reopening can't be skipped by replying. */
+    reopenThread?: Hook<ThreadTarget> | undefined;
+    updateThread?: Hook<UpdateThreadInput<Types>> | undefined;
+    updateAnchor?: Hook<UpdateAnchorInput<Types>> | undefined;
+    deleteThread?: Hook<ThreadTarget> | undefined;
+}
+/** How comments are set up in an app. */
+export interface CommentsOptions {
+    /**
+     * The subject types that can have comments, keyed by name, with who can comment on each. The app declares each one in
+     * its own `subjects`, with who can see it. Register at least one.
+     */
+    subjects: Readonly<Record<string, CommentRules>>;
+    /** Anchor kinds threads may use. Without any, threads are always on the whole subject. */
+    anchors?: readonly AnchorKind[] | undefined;
+    /** Body formats besides the built-in `text`. */
+    formats?: readonly BodyFormat[] | undefined;
+    hooks?: {
+        before?: BeforeHooks | undefined;
+    } | undefined;
+    additionalFields?: AdditionalFields | undefined;
+}
+/** The types an app's options give comments, for typed inputs and records. */
+export interface CommentsTypes {
+    subjectType: string;
+    visibility: string;
+    anchor: {
+        kind: string;
+        value: unknown;
+        version?: string | null | undefined;
+    };
+    content: {
+        format?: string | undefined;
+        body: unknown;
+    };
+    threadFields: Record<string, unknown>;
+    commentFields: Record<string, unknown>;
+}
+type VisibilityOf<Subject> = Subject extends {
+    visibility?: infer Visibility;
+} ? Visibility extends Readonly<Record<string, unknown>> ? keyof Visibility & string : never : never;
+type AnchorOf<Anchors> = Anchors extends readonly (infer Anchor)[] ? Anchor extends AnchorKind<infer Kind, infer Value> ? {
+    kind: Kind;
+    value: Value;
+    version?: string | null | undefined;
+} : never : never;
+type ContentOf<Formats> = {
+    format?: "text" | undefined;
+    body: string;
+} | (Formats extends readonly (infer Format)[] ? Format extends BodyFormat<infer Name, infer Body> ? {
+    format: Name;
+    body: Body;
+} : never : never);
+/** The types a set of options gives comments. */
+export interface TypesOf<Options extends CommentsOptions> {
+    subjectType: keyof Options["subjects"] & string;
+    visibility: "default" | {
+        [Name in keyof Options["subjects"]]: VisibilityOf<Options["subjects"][Name]>;
+    }[keyof Options["subjects"]];
+    anchor: AnchorOf<Options["anchors"]>;
+    content: ContentOf<Options["formats"]>;
+    threadFields: Options["additionalFields"] extends {
+        thread: infer Fields;
+    } ? InferFields<Fields> : Record<never, never>;
+    commentFields: Options["additionalFields"] extends {
+        comment: infer Fields;
+    } ? InferFields<Fields> : Record<never, never>;
+}
+/** A thread id, for actions on a thread. */
+export interface ThreadTarget {
+    threadId: string;
+}
+/** A comment id, for actions on a comment. */
+export interface CommentTarget {
+    commentId: string;
+}
+/** The input of `createThread`. */
+export type CreateThreadInput<Types extends CommentsTypes = CommentsTypes> = Types["content"] & {
+    /** The thread's ULID, so a retry can't create it twice. The server makes one when it's left out. */
+    id?: string | undefined;
+    /** The first comment's ULID. */
+    commentId?: string | undefined;
+    subjectType: Types["subjectType"];
+    subjectId: string;
+    visibility?: Types["visibility"] | undefined;
+    anchor?: Types["anchor"] | null | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+    fields?: Partial<Types["threadFields"]> | undefined;
+    commentFields?: Partial<Types["commentFields"]> | undefined;
+};
+/** The input of `reply`. */
+export type ReplyInput<Types extends CommentsTypes = CommentsTypes> = Types["content"] & {
+    /** The comment's ULID, so a retry can't create it twice. */
+    id?: string | undefined;
+    threadId: string;
+    fields?: Partial<Types["commentFields"]> | undefined;
+};
+/** The input of `editComment`. */
+export type EditCommentInput<Types extends CommentsTypes = CommentsTypes> = Types["content"] & {
+    commentId: string;
+};
+/** The input of `updateThread`. */
+export interface UpdateThreadInput<Types extends CommentsTypes = CommentsTypes> {
+    threadId: string;
+    metadata?: Record<string, unknown> | null | undefined;
+    /** Moderators only. */
+    visibility?: Types["visibility"] | undefined;
+    fields?: Partial<Types["threadFields"]> | undefined;
+}
+/** The input of `updateAnchor`. */
+export interface UpdateAnchorInput<Types extends CommentsTypes = CommentsTypes> {
+    threadId: string;
+    /** `null` moves the thread to the whole subject. */
+    anchor: Types["anchor"] | null;
+}
+export {};

package/dist/options.js

@@ -0,0 +1 @@
+export {};

package/dist/react.d.ts

@@ -0,0 +1,122 @@
+import type { BetterApp, IdentityUser } from "better-apps";
+import { type CommentsState, type ListOptions, type LoadState, type Subject } from "./client.js";
+import type { CommentsTypes } from "./options.js";
+import type { Comment, CommentThread } from "./schema.js";
+export * from "./client.js";
+/**
+ * The comments client for the nearest `BetterAppsProvider`. Each Better Apps client has one, so every hook shares one
+ * store, and so does code that called `createCommentsClient` with the same client, such as a router hydrating a server
+ * render's loads. Pass `typeof app` for the app's types.
+ */
+export declare function useComments<App = BetterApp>(): {
+    store: import("better-apps/client").Store<CommentsState<CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"], Comment & import("./client.js").AppCommentsTypes<App>["commentFields"]>>;
+    loadThreads(subject: Subject<import("./client.js").AppCommentsTypes<App>["subjectType"]>, options?: ListOptions): Promise<void>;
+    loadMoreThreads(subject: Subject<import("./client.js").AppCommentsTypes<App>["subjectType"]>, options?: ListOptions): Promise<void>;
+    loadThread(threadId: string): Promise<void>;
+    loadMoreComments(threadId: string): Promise<void>;
+    loadCounts(subjectType: import("./client.js").AppCommentsTypes<App>["subjectType"], subjectIds: readonly string[]): Promise<void>;
+    createThread(input: import("./options.js").CreateThreadInput<import("./client.js").AppCommentsTypes<App>>): Promise<{
+        thread: CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"];
+        comment: Comment & import("./client.js").AppCommentsTypes<App>["commentFields"];
+        droppedMentions: string[];
+    }>;
+    reply(input: import("./options.js").ReplyInput<import("./client.js").AppCommentsTypes<App>>): Promise<{
+        thread: CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"];
+        comment: Comment & import("./client.js").AppCommentsTypes<App>["commentFields"];
+        droppedMentions: string[];
+    }>;
+    editComment(input: import("./options.js").EditCommentInput<import("./client.js").AppCommentsTypes<App>>): Promise<{
+        comment: Comment & import("./client.js").AppCommentsTypes<App>["commentFields"];
+        droppedMentions: string[];
+    }>;
+    deleteComment(input: import("./options.js").CommentTarget): Promise<{
+        comment: Comment & import("./client.js").AppCommentsTypes<App>["commentFields"];
+        threadDeleted: boolean;
+    }>;
+    resolveThread: (input: import("./options.js").ThreadTarget) => Promise<CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"]>;
+    reopenThread: (input: import("./options.js").ThreadTarget) => Promise<CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"]>;
+    updateThread(input: import("./options.js").UpdateThreadInput<import("./client.js").AppCommentsTypes<App>>): Promise<CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"]>;
+    updateAnchor(input: import("./options.js").UpdateAnchorInput<import("./client.js").AppCommentsTypes<App>>): Promise<CommentThread & import("./client.js").AppCommentsTypes<App>["threadFields"]>;
+    deleteThread(input: import("./options.js").ThreadTarget): Promise<{
+        threadId: string;
+    }>;
+    suggestMentions(input: import("./feature.js").SuggestMentionsInput<import("./client.js").AppCommentsTypes<App>["subjectType"]>): Promise<IdentityUser[]>;
+    applyEvent(event: import("./reads.js").ClientEvent | import("better-apps/client").Serialized<import("./reads.js").ClientEvent>): void;
+    dehydrate(): import("./client.js").DehydratedComments;
+    reset(): void;
+    onReset(listener: () => void): () => void;
+    hydrate(snapshot: import("./client.js").DehydratedComments): void;
+};
+type ThreadOf<Types extends CommentsTypes> = CommentThread & Types["threadFields"];
+type MessageOf<Types extends CommentsTypes> = Comment & Types["commentFields"];
+/** A thread list as hooks return it. */
+export interface ThreadsResult<Thread> {
+    threads: Thread[];
+    state: LoadState;
+    error: Error | null;
+    hasMore: boolean;
+    loadMore(): Promise<void>;
+    refresh(): Promise<void>;
+    users: Readonly<Record<string, IdentityUser>>;
+}
+/** A subject's threads, loaded on first use. A list a server render already loaded isn't fetched again. */
+export declare function useThreads<Types extends CommentsTypes = CommentsTypes>(subject: Subject<Types["subjectType"]>, options?: ListOptions): ThreadsResult<ThreadOf<Types>>;
+/** A thread with its comments, oldest first, loaded on first use. */
+export declare function useThread<Types extends CommentsTypes = CommentsTypes>(threadId: string | null): {
+    thread: ThreadOf<Types> | undefined;
+    comments: MessageOf<Types>[];
+    state: LoadState;
+    error: Error | null;
+    hasMore: boolean;
+    loadMore: () => Promise<void>;
+    users: Readonly<Record<string, IdentityUser>>;
+    /** Whether a thread or comment is still waiting for the server. */
+    isPending: (id: string) => boolean;
+};
+/** Open and total thread counts for many records, such as badges in a table. Lists over 50 are split into calls. */
+export declare function useThreadCounts<Types extends CommentsTypes = CommentsTypes>(subjectType: Types["subjectType"], subjectIds: readonly string[]): Readonly<Record<string, {
+    open: number;
+    total: number;
+}>>;
+/** A write as hooks return it: `mutate` runs it, and the rest describes the latest run. */
+export interface Mutation<Input, Output> {
+    mutate(input: Input): Promise<Output>;
+    status: "idle" | "pending" | "success" | "error";
+    error: Error | null;
+    reset(): void;
+}
+/** Starts a thread, shown at once and rolled back if the server refuses it. */
+export declare const useCreateThread: () => Mutation<import("./options.js").CreateThreadInput<import("./options.js").TypesOf<import("./options.js").CommentsOptions>>, {
+    thread: CommentThread & Record<never, never>;
+    comment: Comment & Record<never, never>;
+    droppedMentions: string[];
+}>;
+/** Replies to a thread, reopening it if it was resolved. */
+export declare const useReply: () => Mutation<import("./options.js").ReplyInput<import("./options.js").TypesOf<import("./options.js").CommentsOptions>>, {
+    thread: CommentThread & Record<never, never>;
+    comment: Comment & Record<never, never>;
+    droppedMentions: string[];
+}>;
+export declare const useEditComment: () => Mutation<import("./options.js").EditCommentInput<import("./options.js").TypesOf<import("./options.js").CommentsOptions>>, {
+    comment: Comment & Record<never, never>;
+    droppedMentions: string[];
+}>;
+export declare const useDeleteComment: () => Mutation<import("./options.js").CommentTarget, {
+    comment: Comment & Record<never, never>;
+    threadDeleted: boolean;
+}>;
+export declare const useResolveThread: () => Mutation<import("./options.js").ThreadTarget, CommentThread & Record<never, never>>;
+export declare const useReopenThread: () => Mutation<import("./options.js").ThreadTarget, CommentThread & Record<never, never>>;
+export declare const useUpdateThread: () => Mutation<import("./options.js").UpdateThreadInput<import("./options.js").TypesOf<import("./options.js").CommentsOptions>>, CommentThread & Record<never, never>>;
+export declare const useUpdateAnchor: () => Mutation<import("./options.js").UpdateAnchorInput<import("./options.js").TypesOf<import("./options.js").CommentsOptions>>, CommentThread & Record<never, never>>;
+export declare const useDeleteThread: () => Mutation<import("./options.js").ThreadTarget, {
+    threadId: string;
+}>;
+/** Mention suggestions for a thread, or for a subject before its thread exists. `search` asks for a query's matches. */
+export declare function useSuggestMentions(target: {
+    threadId: string;
+} | Subject): {
+    suggestions: IdentityUser[];
+    error: Error | null;
+    search: (query: string) => Promise<IdentityUser[]>;
+};