@better-apps/comments 0.0.0-stage → 0.1.0

package/dist/react.js

@@ -0,0 +1,179 @@
+// React hooks over the comments store, with no UI: apps bring their own composer, thread list and pin styles.
+import { useBetterApps, useStore } from "@better-apps/react";
+import { BetterAppsClientError } from "better-apps/client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { countKey, createCommentsClient, listKey } from "./client.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 function useComments() {
+    return createCommentsClient(useBetterApps());
+}
+function useCommentsState(select, isEqual) {
+    const comments = useComments();
+    return useStore(comments.store, select, isEqual);
+}
+const sameItems = (a, b) => a.length === b.length && a.every((item, index) => Object.is(item, b[index]));
+/** A subject's threads, loaded on first use. A list a server render already loaded isn't fetched again. */
+export function useThreads(subject, options = {}) {
+    const comments = useComments();
+    const { subjectType, subjectId } = subject;
+    const { status, order } = options;
+    const key = listKey({ subjectType, subjectId }, { status, order });
+    const list = useCommentsState((state) => state.lists[key]);
+    const threads = useCommentsState((state) => (state.lists[key]?.ids ?? []).flatMap((id) => (state.threads[id] ? [state.threads[id]] : [])), sameItems);
+    const users = useCommentsState((state) => state.users);
+    const listState = list?.state;
+    useEffect(() => {
+        if (listState === undefined) {
+            comments.loadThreads({ subjectType, subjectId }, { status, order }).catch(() => undefined);
+        }
+    }, [comments, subjectType, subjectId, status, order, listState]);
+    const loadMore = useCallback(() => comments.loadMoreThreads({ subjectType, subjectId }, { status, order }), [comments, subjectType, subjectId, status, order]);
+    const refresh = useCallback(() => comments.loadThreads({ subjectType, subjectId }, { status, order }), [comments, subjectType, subjectId, status, order]);
+    return {
+        threads,
+        state: list?.state ?? "loading",
+        error: list?.error ?? null,
+        hasMore: Boolean(list?.cursor),
+        loadMore,
+        refresh,
+        users
+    };
+}
+/** A thread with its comments, oldest first, loaded on first use. */
+export function useThread(threadId) {
+    const comments = useComments();
+    const thread = useCommentsState((state) => (threadId ? state.threads[threadId] : undefined));
+    const loaded = useCommentsState((state) => (threadId ? state.threadComments[threadId] : undefined));
+    const messages = useCommentsState((state) => ((threadId && state.threadComments[threadId]?.ids) || []).flatMap((id) => state.comments[id] ? [state.comments[id]] : []), sameItems);
+    const users = useCommentsState((state) => state.users);
+    const pending = useCommentsState((state) => state.pending);
+    const loadedState = loaded?.state;
+    useEffect(() => {
+        if (threadId && loadedState === undefined) {
+            comments.loadThread(threadId).catch(() => undefined);
+        }
+    }, [comments, threadId, loadedState]);
+    const loadMore = useCallback(async () => {
+        if (threadId) {
+            await comments.loadMoreComments(threadId);
+        }
+    }, [comments, threadId]);
+    return {
+        thread,
+        comments: messages,
+        state: threadId ? (loaded?.state ?? "loading") : "idle",
+        error: loaded?.error ?? null,
+        hasMore: Boolean(loaded?.cursor),
+        loadMore,
+        users,
+        /** Whether a thread or comment is still waiting for the server. */
+        isPending: (id) => pending[id] === true
+    };
+}
+/** Open and total thread counts for many records, such as badges in a table. Lists over 50 are split into calls. */
+export function useThreadCounts(subjectType, subjectIds) {
+    const comments = useComments();
+    const idsKey = subjectIds.join("\u0000");
+    // Ids with no counts at all, not even loading ones. A reset empties the store, so its ids show up here again.
+    const missing = useCommentsState((state) => subjectIds.filter((subjectId) => !state.counts[countKey(subjectType, subjectId)]), sameItems);
+    const counts = useCommentsState((state) => Object.fromEntries(subjectIds.flatMap((subjectId) => {
+        const count = state.counts[countKey(subjectType, subjectId)];
+        return count?.state === "ready" ? [[subjectId, { open: count.open, total: count.total }]] : [];
+    })), (a, b) => JSON.stringify(a) === JSON.stringify(b));
+    const missingKey = missing.join("\u0000");
+    useEffect(() => {
+        if (missingKey !== "") {
+            comments.loadCounts(subjectType, missingKey.split("\u0000")).catch(() => undefined);
+        }
+    }, [comments, subjectType, idsKey, missingKey]);
+    // Counts that failed load again once when the list mounts or changes, rather than after every failure, so a failing
+    // server isn't asked in a loop.
+    useEffect(() => {
+        const state = comments.store.getSnapshot();
+        const ids = idsKey === "" ? [] : idsKey.split("\u0000");
+        const failed = ids.filter((subjectId) => state.counts[countKey(subjectType, subjectId)]?.state === "error");
+        if (failed.length > 0) {
+            comments.loadCounts(subjectType, failed).catch(() => undefined);
+        }
+    }, [comments, subjectType, idsKey]);
+    return counts;
+}
+function useMutation(run) {
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    // Only the latest run describes the mutation, so one that settles after a newer run or a reset changes nothing.
+    const latest = useRef(0);
+    const mutate = useCallback(async (input) => {
+        const current = ++latest.current;
+        setStatus("pending");
+        setError(null);
+        try {
+            const output = await run(input);
+            if (current === latest.current) {
+                setStatus("success");
+            }
+            return output;
+        }
+        catch (caught) {
+            if (current === latest.current) {
+                // A write the store's reset() cancelled belonged to the previous person, so it shows as never having run.
+                const cancelled = caught instanceof BetterAppsClientError && caught.code === "ABORTED";
+                setStatus(cancelled ? "idle" : "error");
+                setError(cancelled ? null : caught);
+            }
+            throw caught;
+        }
+    }, [run]);
+    const reset = useCallback(() => {
+        latest.current += 1;
+        setStatus("idle");
+        setError(null);
+    }, []);
+    return { mutate, status, error, reset };
+}
+function useAction(name) {
+    const comments = useComments();
+    const run = useCallback((input) => comments[name](input), [comments, name]);
+    return useMutation(run);
+}
+/** Starts a thread, shown at once and rolled back if the server refuses it. */
+export const useCreateThread = () => useAction("createThread");
+/** Replies to a thread, reopening it if it was resolved. */
+export const useReply = () => useAction("reply");
+export const useEditComment = () => useAction("editComment");
+export const useDeleteComment = () => useAction("deleteComment");
+export const useResolveThread = () => useAction("resolveThread");
+export const useReopenThread = () => useAction("reopenThread");
+export const useUpdateThread = () => useAction("updateThread");
+export const useUpdateAnchor = () => useAction("updateAnchor");
+export const useDeleteThread = () => useAction("deleteThread");
+/** Mention suggestions for a thread, or for a subject before its thread exists. `search` asks for a query's matches. */
+export function useSuggestMentions(target) {
+    const comments = useComments();
+    const [suggestions, setSuggestions] = useState([]);
+    const [error, setError] = useState(null);
+    const targetKey = JSON.stringify(target);
+    // Suggestions are what the signed-in person could see, so they go when the store is reset for someone else.
+    useEffect(() => comments.onReset(() => {
+        setSuggestions([]);
+        setError(null);
+    }), [comments]);
+    const search = useCallback(async (query) => {
+        try {
+            const found = await comments.suggestMentions({ ...JSON.parse(targetKey), query });
+            setSuggestions(found);
+            setError(null);
+            return found;
+        }
+        catch (caught) {
+            setError(caught);
+            return [];
+        }
+    }, [comments, targetKey]);
+    return { suggestions, error, search };
+}

package/dist/reads.d.ts

@@ -0,0 +1,54 @@
+import type { Actor, IdentityUser } from "better-apps";
+import { type Config, type Context } from "./runtime.js";
+import { type Comment, type CommentThread } from "./schema.js";
+/** A page of threads, with the users they name. */
+export interface ThreadPage<Thread = CommentThread> {
+    threads: Thread[];
+    /** The cursor for the next page, or `null` on the last one. */
+    cursor: string | null;
+    /** Names and avatars by user id. Users the identity adapter can't find are missing; show them as "Former user". */
+    users: Record<string, IdentityUser>;
+}
+/** A thread with a page of its comments, oldest first. */
+export interface ThreadWithComments<Thread = CommentThread, Message = Comment> {
+    thread: Thread;
+    comments: Message[];
+    cursor: string | null;
+    users: Record<string, IdentityUser>;
+}
+export declare function listThreads(config: Config, context: Context): Promise<ThreadPage>;
+export declare function getThread(config: Config, context: Context): Promise<ThreadWithComments>;
+export declare function countThreads(config: Config, context: Context): Promise<Record<string, {
+    open: number;
+    total: number;
+}>>;
+export declare function suggestMentions(config: Config, context: Context): Promise<IdentityUser[]>;
+/** Whether someone can see a thread, for other features' recipient checks, such as notifications. */
+export declare function canViewThread(config: Config, context: Context): Promise<boolean>;
+/** An event a browser may see, from `toClientEvent`. */
+export type ClientEvent = {
+    id: string;
+    type: "thread.created" | "comment.created" | "comment.edited" | "comment.deleted" | "comment.mentioned";
+    thread: CommentThread;
+    comment: Comment;
+} | {
+    id: string;
+    type: "thread.updated" | "thread.resolved" | "thread.reopened" | "thread.anchorUpdated" | "thread.deleted";
+    thread: CommentThread;
+};
+/** Someone a live updates feature sends events to, with the request they connected with. */
+export interface LiveViewer {
+    /** Who's connected: a signed-in user, or `null` for a signed-out visitor. */
+    actor: Actor | null;
+    /** Their request, so a grant it carries, such as a share link, counts as it does for reads. */
+    request?: Request | null | undefined;
+}
+/**
+ * Turns a server event into one a viewer's browser may see, for a live updates feature. It returns `null` when the
+ * viewer can't see the thread, and leaves out previous bodies and anchors. Threads and comments keep the fields reads
+ * return, so applying an event never blanks what a read showed. `comment.mentioned` only reaches the user it mentions.
+ * With the viewer's `request`, a grant it carries, such as a share link, counts as it does for reads.
+ */
+export declare function toClientEvent(config: Config, context: Context): Promise<ClientEvent | null>;
+/** `toClientEvent` for many viewers, in order, with their access checked together, such as by one grant call. */
+export declare function toClientEvents(config: Config, context: Context): Promise<(ClientEvent | null)[]>;

package/dist/reads.js

@@ -0,0 +1,297 @@
+import { suggestMentions as suggestUsers } from "@better-apps/mentions";
+import { accessTo, canViewThread as canView, orgOf, requireView, subjectOf, viewThreads, visibleTo } from "./access.js";
+import { limits } from "./content.js";
+import { decodeCursor, encodeCursor } from "./cursor.js";
+import { CommentsError } from "./errors.js";
+import { callerOf, forbid, loadThread, lookupUsers, mentionScope, threadAccess } from "./runtime.js";
+import { commentModel, threadModel } from "./schema.js";
+/** Signed-out readers get no user ids or metadata. */
+function publicThread(thread) {
+    return { ...thread, createdBy: "", resolvedBy: null, metadata: null };
+}
+/** Signed-out readers get each comment as text with names filled in, and no user ids. */
+function publicComment(config, comment, users) {
+    const format = config.formats.get(comment.format);
+    const names = (userId) => users[userId]?.name ?? undefined;
+    const bodyText = comment.body === null || !format ? comment.bodyText : format.toText(comment.body, names);
+    const authorName = comment.authorType === "user" ? (users[comment.authorId]?.name ?? null) : comment.authorName;
+    return { ...comment, authorId: "", authorName, body: null, bodyText, metadata: null };
+}
+/** The users a page of comments names: user authors, and everyone mentioned. */
+function namedUsers(config, comments) {
+    return comments.flatMap((comment) => {
+        const format = config.formats.get(comment.format);
+        const mentioned = comment.body === null || !format ? [] : format.mentions(comment.body);
+        return comment.authorType === "user" ? [comment.authorId, ...mentioned] : mentioned;
+    });
+}
+function pageSize(requested, fallback) {
+    return requested ?? fallback;
+}
+export async function listThreads(config, context) {
+    const input = context.input;
+    const { subjectType, subjectId } = input;
+    const rules = subjectOf(config.subjects, subjectType);
+    const caller = callerOf(context);
+    const ref = { subjectType, subjectId };
+    const access = await accessTo(rules, context.subjects, caller, ref, "default", context.request);
+    let visibilities = ["default"];
+    if (caller.trusted) {
+        visibilities = ["default", ...Object.keys(rules.visibility ?? {})];
+    }
+    else if (caller.actor && access.view && !access.granted) {
+        visibilities = await visibleTo(rules, { actor: caller.actor, subjectType, subjectId });
+    }
+    requireView(access);
+    const orgId = await orgOf(context.subjects, caller, ref);
+    const where = [
+        { field: "orgId", value: orgId },
+        { field: "subjectType", value: subjectType },
+        { field: "subjectId", value: subjectId },
+        { field: "visibility", operator: "in", value: visibilities }
+    ];
+    if (input.status) {
+        where.push({ field: "status", value: input.status });
+    }
+    if (input.anchorKind !== undefined) {
+        where.push({ field: "anchorKind", value: input.anchorKind });
+    }
+    for (const [field, value] of Object.entries(input.where ?? {})) {
+        if (!Object.hasOwn(config.threadFields, field) || !config.threadFields[field]?.index) {
+            throw new CommentsError("INVALID_INPUT", `Threads can't be filtered by "${field}"; only indexed additional fields.`);
+        }
+        where.push({ field, value });
+    }
+    const orderField = input.order === "created" ? "createdAt" : "lastActivityAt";
+    const limit = pageSize(input.limit, limits.threadsPerPage);
+    const after = input.cursor === undefined ? undefined : decodeCursor(input.cursor);
+    const rows = await context.db.findMany({
+        model: threadModel,
+        where,
+        sortBy: [
+            { field: orderField, direction: "desc" },
+            { field: "id", direction: "desc" }
+        ],
+        after: after && { [orderField]: after.time, id: after.id },
+        limit: limit + 1
+    });
+    const threads = rows.slice(0, limit);
+    const last = threads.at(-1);
+    const cursor = rows.length > limit && last ? encodeCursor(last[orderField], last.id) : null;
+    // Someone who sees the threads only through a grant, such as a share link, sees them as a signed-out reader does.
+    if ((!caller.actor && !caller.trusted) || access.granted) {
+        return { threads: threads.map(publicThread), cursor, users: {} };
+    }
+    const users = await lookupUsers(context, threads.flatMap((thread) => [thread.createdBy, thread.resolvedBy ?? ""]));
+    return { threads, cursor, users };
+}
+export async function getThread(config, context) {
+    const input = context.input;
+    const thread = await loadThread(context, input.threadId);
+    const { caller, access } = await threadAccess(config, context, thread, context.request);
+    requireView(access);
+    const limit = pageSize(input.limit, limits.commentsPerPage);
+    const after = input.cursor === undefined ? undefined : decodeCursor(input.cursor);
+    const rows = await context.db.findMany({
+        model: commentModel,
+        where: [{ field: "threadId", value: thread.id }],
+        sortBy: [
+            { field: "createdAt", direction: "asc" },
+            { field: "id", direction: "asc" }
+        ],
+        after: after && { createdAt: after.time, id: after.id },
+        limit: limit + 1
+    });
+    const comments = rows.slice(0, limit);
+    const last = comments.at(-1);
+    const cursor = rows.length > limit && last ? encodeCursor(last.createdAt, last.id) : null;
+    const users = await lookupUsers(context, [thread.createdBy, thread.resolvedBy ?? "", ...namedUsers(config, comments)]);
+    if ((!caller.actor && !caller.trusted) || access.granted) {
+        return {
+            thread: publicThread(thread),
+            comments: comments.map((comment) => publicComment(config, comment, users)),
+            cursor,
+            users: {}
+        };
+    }
+    return { thread, comments, cursor, users };
+}
+export async function countThreads(config, context) {
+    const input = context.input;
+    const { subjectType } = input;
+    const rules = subjectOf(config.subjects, subjectType);
+    const caller = callerOf(context);
+    const subjectIds = [...new Set(input.subjectIds)];
+    const { actor } = caller;
+    let allowed = subjectIds.map(() => true);
+    // Subjects seen only through a grant the request carries, such as a share link, count their default threads.
+    const granted = new Set();
+    if (!caller.trusted) {
+        allowed = await context.subjects.canViewMany(subjectIds.map((subjectId) => ({ actor, subjectType, subjectId })));
+        const refused = subjectIds.filter((_, index) => !allowed[index]);
+        const { request } = context;
+        if (request && refused.length > 0) {
+            const reached = await context.subjects.canViewMany(refused.map((subjectId) => ({ actor, subjectType, subjectId, request })));
+            for (const [index, subjectId] of refused.entries()) {
+                if (reached[index]) {
+                    granted.add(subjectId);
+                }
+            }
+            allowed = subjectIds.map((subjectId, index) => allowed[index] === true || granted.has(subjectId));
+        }
+        if (!actor && !allowed.includes(true)) {
+            throw new CommentsError("UNAUTHENTICATED", "Sign in to see these comments.");
+        }
+    }
+    const viewable = subjectIds.filter((_, index) => allowed[index]);
+    const allVisibilities = ["default", ...Object.keys(rules.visibility ?? {})];
+    const visibleOn = async (subjectId) => {
+        if (caller.trusted) {
+            return allVisibilities;
+        }
+        return actor && !granted.has(subjectId) ? visibleTo(rules, { actor, subjectType, subjectId }) : ["default"];
+    };
+    const details = await Promise.all(viewable.map(async (subjectId) => ({
+        subjectId,
+        orgId: await orgOf(context.subjects, caller, { subjectType, subjectId }),
+        visible: new Set(await visibleOn(subjectId))
+    })));
+    const counts = {};
+    const bySubject = new Map(details.map((detail) => [detail.subjectId, detail]));
+    for (const detail of details) {
+        counts[detail.subjectId] = { open: 0, total: 0 };
+    }
+    if (viewable.length === 0) {
+        return counts;
+    }
+    const where = [
+        { field: "subjectType", value: subjectType },
+        { field: "subjectId", operator: "in", value: viewable }
+    ];
+    if (input.status) {
+        where.push({ field: "status", value: input.status });
+    }
+    const groups = await context.db.countGroups({
+        model: threadModel,
+        where,
+        groupBy: ["orgId", "subjectId", "visibility", "status"]
+    });
+    for (const { group, count } of groups) {
+        const detail = bySubject.get(String(group.subjectId));
+        const tally = counts[String(group.subjectId)];
+        if (detail && tally && group.orgId === detail.orgId && detail.visible.has(String(group.visibility))) {
+            tally.total += count;
+            tally.open += group.status === "open" ? count : 0;
+        }
+    }
+    return counts;
+}
+export async function suggestMentions(config, context) {
+    const input = context.input;
+    let thread;
+    if (input.threadId !== undefined) {
+        thread = await loadThread(context, input.threadId);
+    }
+    else {
+        const subjectType = input.subjectType;
+        const subjectId = input.subjectId;
+        subjectOf(config.subjects, subjectType);
+        const now = context.now;
+        // Suggestions for a new thread are checked as if it were a default thread on the subject.
+        thread = {
+            id: "",
+            orgId: await orgOf(context.subjects, callerOf(context), { subjectType, subjectId }),
+            subjectType,
+            subjectId,
+            visibility: "default",
+            anchorKind: null,
+            anchor: null,
+            anchorVersion: null,
+            status: "open",
+            resolvedAt: null,
+            resolvedBy: null,
+            createdBy: "",
+            createdAt: now,
+            lastActivityAt: now,
+            commentCount: 0,
+            metadata: null
+        };
+    }
+    const { access } = await threadAccess(config, context, thread);
+    requireView(access);
+    forbid(access.comment, "You can't comment here.");
+    return suggestUsers(mentionScope(config, context, thread), input.query, limits.suggestions);
+}
+/** Whether someone can see a thread, for other features' recipient checks, such as notifications. */
+export async function canViewThread(config, context) {
+    const input = context.input;
+    const thread = input.thread ??
+        (await context.db.findOne({
+            model: threadModel,
+            where: [{ field: "id", value: input.threadId ?? "" }]
+        }));
+    return thread ? canView(config.subjects, context.subjects, input.actor, thread) : false;
+}
+const commentEventTypes = new Set([
+    "thread.created",
+    "comment.created",
+    "comment.edited",
+    "comment.deleted",
+    "comment.mentioned"
+]);
+const threadEventTypes = new Set([
+    "thread.updated",
+    "thread.resolved",
+    "thread.reopened",
+    "thread.anchorUpdated",
+    "thread.deleted"
+]);
+/**
+ * Turns a server event into one a viewer's browser may see, for a live updates feature. It returns `null` when the
+ * viewer can't see the thread, and leaves out previous bodies and anchors. Threads and comments keep the fields reads
+ * return, so applying an event never blanks what a read showed. `comment.mentioned` only reaches the user it mentions.
+ * With the viewer's `request`, a grant it carries, such as a share link, counts as it does for reads.
+ */
+export async function toClientEvent(config, context) {
+    const { event, viewer, request } = context.input;
+    const [shown] = await clientEvents(config, context, event, [{ actor: viewer, request }]);
+    return shown ?? null;
+}
+/** `toClientEvent` for many viewers, in order, with their access checked together, such as by one grant call. */
+export async function toClientEvents(config, context) {
+    const { event, viewers } = context.input;
+    return clientEvents(config, context, event, viewers);
+}
+async function clientEvents(config, context, event, viewers) {
+    const none = viewers.map(() => null);
+    if (event.feature !== "comments" || (!commentEventTypes.has(event.type) && !threadEventTypes.has(event.type))) {
+        return none;
+    }
+    const data = event.data;
+    const reached = viewers.map(({ actor }) => event.type !== "comment.mentioned" || (actor !== null && actor.userId === data.userId));
+    const asked = viewers.flatMap((viewer, index) => (reached[index] ? [index] : []));
+    const views = await viewThreads(config.subjects, context.subjects, asked.map((index) => ({
+        actor: viewers[index]?.actor ?? null,
+        thread: data.thread,
+        request: viewers[index]?.request
+    })));
+    const viewOf = new Map(asked.map((index, position) => [index, views[position] ?? null]));
+    // Someone who sees the thread only through a grant sees it as a signed-out reader does.
+    const hiddenFor = (index) => viewers[index]?.actor === null || viewOf.get(index) === "granted";
+    let hiddenComment = data.comment;
+    if (data.comment && asked.some((index) => viewOf.get(index) && hiddenFor(index))) {
+        const users = await lookupUsers(context, namedUsers(config, [data.comment]));
+        hiddenComment = publicComment(config, data.comment, users);
+    }
+    return viewers.map((_, index) => {
+        if (!viewOf.get(index)) {
+            return null;
+        }
+        const hidden = hiddenFor(index);
+        const thread = hidden ? publicThread(data.thread) : data.thread;
+        const comment = hidden ? hiddenComment : data.comment;
+        return comment && commentEventTypes.has(event.type)
+            ? { id: event.id, type: event.type, thread, comment }
+            : { id: event.id, type: event.type, thread };
+    });
+}

package/dist/runtime.d.ts

@@ -0,0 +1,52 @@
+import type { AnchorKind } from "@better-apps/anchors";
+import type { MentionScope } from "@better-apps/mentions";
+import { type ActionContext, type Author, type FieldAttribute, type IdentityUser, type StandardSchemaV1 } from "better-apps";
+import { type Access, type Caller } from "./access.js";
+import type { BodyFormat } from "./formats.js";
+import type { BeforeHooks, CommentRules, HookArgs } from "./options.js";
+import { type Comment, type CommentThread } from "./schema.js";
+/** The options, resolved once when the feature is created. */
+export interface Config {
+    subjects: Readonly<Record<string, CommentRules>>;
+    anchors: ReadonlyMap<string, AnchorKind>;
+    formats: ReadonlyMap<string, BodyFormat>;
+    hooks: BeforeHooks;
+    threadFields: Readonly<Record<string, FieldAttribute>>;
+    commentFields: Readonly<Record<string, FieldAttribute>>;
+}
+export type Context = ActionContext<unknown>;
+/**
+ * Who a call acts as. Server code that passes neither an actor nor a request is trusted, so its reads and writes skip
+ * access checks; server code acting for a request or an actor is checked as that user.
+ */
+export declare function callerOf(context: Context): Caller;
+/** The author of a write, or `UNAUTHENTICATED` without one. */
+export declare function requireAuthor(context: Context): Author;
+/** The id stored for an author: a user id, or the id server code gave an external or system author. */
+export declare function authorIdOf(author: Author): string;
+/** Whether an author wrote a comment. */
+export declare function wrote(author: Author, comment: Comment): boolean;
+/** A thread by id, or `NOT_FOUND`. */
+export declare function loadThread(context: Context, threadId: string): Promise<CommentThread>;
+/**
+ * What the caller may do with a thread. A thread outside its subject's current organization can't be seen. Reads pass
+ * the request, so a grant it carries counts; writes leave it out.
+ */
+export declare function threadAccess(config: Config, context: Context, thread: CommentThread, request?: Request | null): Promise<{
+    rules: CommentRules;
+    caller: Caller;
+    access: Access;
+}>;
+/** Refuses an action the caller can view but can't take. */
+export declare function forbid(allowed: boolean, message: string): void;
+/**
+ * Runs a before hook and checks what it returns with the action's schema. A `BetterAppsError`, such as a
+ * `CommentsError`, keeps its code; any other error becomes `REJECTED_BY_HOOK`.
+ */
+export declare function runHook<Input>(hook: ((args: HookArgs<Input>) => Input | Promise<Input>) | undefined, args: HookArgs<Input>, schema: StandardSchemaV1): Promise<Input>;
+/** Splits ids into lists of at most 90, under D1's limit of 100 bound parameters. */
+export declare function chunks<Item>(items: readonly Item[], size?: number): Item[][];
+/** Looks up users' names and avatars, keyed by id. Users the identity adapter can't find are left out. */
+export declare function lookupUsers(context: Context, ids: Iterable<string>): Promise<Record<string, IdentityUser>>;
+/** Where a thread's mentions are checked: its organization, and who may be mentioned there. */
+export declare function mentionScope(config: Config, context: Context, thread: CommentThread): MentionScope;