@better-apps/comments 0.0.0-stage → 0.0.0

package/dist/content.js

@@ -0,0 +1,136 @@
+import { CommentsError } from "./errors.js";
+/** Size and count limits. Queries that pass lists of ids stay under D1's 100 bound parameters. */
+export const limits = {
+    bodyBytes: 16 * 1024,
+    anchorBytes: 4 * 1024,
+    metadataBytes: 4 * 1024,
+    mentions: 20,
+    threadsPerPage: 20,
+    maxThreadsPerPage: 50,
+    commentsPerPage: 50,
+    maxCommentsPerPage: 100,
+    subjectsPerCount: 50,
+    suggestions: 10
+};
+const encoder = new TextEncoder();
+/** The size of a value as JSON, in UTF-8 bytes. */
+export function jsonBytes(value) {
+    return encoder.encode(JSON.stringify(value) ?? "").length;
+}
+/** JSON with object keys sorted, so equal values compare equal however they were built. */
+export function stableJson(value) {
+    return JSON.stringify(value, (_, inner) => inner && typeof inner === "object" && !Array.isArray(inner)
+        ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : 1)))
+        : inner);
+}
+async function check(schema, value, what) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues) {
+        throw new CommentsError("INVALID_INPUT", `The ${what} isn't valid.`, { issues: result.issues });
+    }
+    return result.value;
+}
+function capped(value, bytes, what) {
+    if (jsonBytes(value) > bytes) {
+        throw new CommentsError("LIMIT_EXCEEDED", `The ${what} is over ${bytes / 1024} KB.`);
+    }
+}
+/** Checks, sanitizes and measures a body in a registered format. */
+export async function checkContent(formats, formatName, body) {
+    const name = formatName ?? "text";
+    const format = formats.get(name);
+    if (!format) {
+        throw new CommentsError("INVALID_INPUT", `Comments aren't set up for the "${name}" body format.`);
+    }
+    const checked = await check(format.schema, body, "comment body");
+    const sanitized = format.sanitize ? format.sanitize(checked) : checked;
+    capped(sanitized, limits.bodyBytes, "comment");
+    const mentions = format.mentions(sanitized);
+    if (mentions.length > limits.mentions) {
+        throw new CommentsError("LIMIT_EXCEEDED", `A comment can mention at most ${limits.mentions} people.`);
+    }
+    return { format: name, body: sanitized, bodyText: format.toText(sanitized), mentions };
+}
+/** Checks an anchor against its registered kind. `null` puts the thread on the whole subject. */
+export async function checkAnchor(anchors, anchor) {
+    if (!anchor) {
+        return { anchorKind: null, anchor: null, anchorVersion: null };
+    }
+    const kind = anchors.get(anchor.kind);
+    if (!kind) {
+        throw new CommentsError("INVALID_INPUT", `Comments aren't set up for the "${anchor.kind}" anchor kind.`);
+    }
+    const value = await check(kind.schema, anchor.value, "anchor");
+    capped(value, limits.anchorBytes, "anchor");
+    return { anchorKind: kind.kind, anchor: value, anchorVersion: anchor.version ?? null };
+}
+/** Checks metadata against a subject type's schema, when it has one, and its size. */
+export async function checkMetadata(schema, metadata) {
+    if (metadata === null) {
+        return null;
+    }
+    const checked = schema ? await check(schema, metadata, "metadata") : metadata;
+    capped(checked, limits.metadataBytes, "metadata");
+    return checked;
+}
+function fieldValue(name, field, value) {
+    const invalid = () => new CommentsError("INVALID_INPUT", `The "${name}" field isn't valid.`);
+    if (value === null) {
+        if (field.required === false) {
+            return null;
+        }
+        throw invalid();
+    }
+    const { type } = field;
+    if (Array.isArray(type)) {
+        if (typeof value === "string" && type.includes(value)) {
+            return value;
+        }
+        throw invalid();
+    }
+    switch (type) {
+        case "string":
+        case "number":
+        case "boolean":
+            if (typeof value === type && (type !== "number" || Number.isFinite(value))) {
+                return value;
+            }
+            throw invalid();
+        case "date": {
+            // JSON carries dates as strings.
+            if (value instanceof Date || typeof value === "string") {
+                const date = new Date(value);
+                if (!Number.isNaN(date.getTime())) {
+                    return date;
+                }
+            }
+            throw invalid();
+        }
+        case "string[]":
+        case "number[]": {
+            const item = type === "string[]" ? "string" : "number";
+            if (Array.isArray(value) && value.every((entry) => typeof entry === item)) {
+                return value;
+            }
+            throw invalid();
+        }
+        default:
+            capped(value, limits.metadataBytes, `"${name}" field`);
+            return value;
+    }
+}
+/** Checks values for an app's additional fields. Fields it didn't declare are refused. */
+export function checkFields(declared, values) {
+    const checked = {};
+    for (const [name, value] of Object.entries(values ?? {})) {
+        if (value === undefined) {
+            continue;
+        }
+        const field = Object.hasOwn(declared, name) ? declared[name] : undefined;
+        if (!field) {
+            throw new CommentsError("INVALID_INPUT", `There's no "${name}" field.`);
+        }
+        checked[name] = fieldValue(name, field, value);
+    }
+    return checked;
+}

package/dist/cursor.d.ts

@@ -0,0 +1,7 @@
+/** Encodes the position after a row. */
+export declare function encodeCursor(time: Date, id: string): string;
+/** Decodes a cursor from `encodeCursor`, or refuses it as `INVALID_INPUT`. */
+export declare function decodeCursor(cursor: string): {
+    time: Date;
+    id: string;
+};

package/dist/cursor.js

@@ -0,0 +1,23 @@
+import { CommentsError } from "./errors.js";
+// A page cursor holds the last row's sort time and id, so rows that share a time are never skipped or repeated.
+/** Encodes the position after a row. */
+export function encodeCursor(time, id) {
+    return btoa(JSON.stringify([time.toISOString(), id]))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** Decodes a cursor from `encodeCursor`, or refuses it as `INVALID_INPUT`. */
+export function decodeCursor(cursor) {
+    try {
+        const [time, id] = JSON.parse(atob(cursor.replace(/-/g, "+").replace(/_/g, "/")));
+        const date = new Date(String(time));
+        if (typeof time === "string" && typeof id === "string" && !Number.isNaN(date.getTime())) {
+            return { time: date, id };
+        }
+    }
+    catch {
+        // Reported below.
+    }
+    throw new CommentsError("INVALID_INPUT", "That page cursor isn't valid.");
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import { BetterAppsError, type StandardSchemaIssue } from "better-apps";
+/** The codes comments answer with. The client uses them to roll back optimistic changes. */
+export type CommentsErrorCode = "UNAUTHENTICATED" | "NOT_FOUND" | "FORBIDDEN" | "INVALID_INPUT" | "LIMIT_EXCEEDED" | "RATE_LIMITED" | "CONFLICT" | "REJECTED_BY_HOOK";
+/**
+ * An error comments return on purpose. A before hook throws one to refuse a write with its code, such as `FORBIDDEN` or
+ * `RATE_LIMITED`; any other error from a hook becomes `REJECTED_BY_HOOK`.
+ */
+export declare class CommentsError extends BetterAppsError {
+    readonly code: CommentsErrorCode;
+    constructor(code: CommentsErrorCode, message?: string, options?: {
+        issues?: readonly StandardSchemaIssue[] | undefined;
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+import { BetterAppsError } from "better-apps";
+/**
+ * An error comments return on purpose. A before hook throws one to refuse a write with its code, such as `FORBIDDEN` or
+ * `RATE_LIMITED`; any other error from a hook becomes `REJECTED_BY_HOOK`.
+ */
+export class CommentsError extends BetterAppsError {
+    constructor(code, message = code, options = {}) {
+        super(code, message, options);
+        this.name = "CommentsError";
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,74 @@
+import type { Comment, CommentThread } from "./schema.js";
+/** What every thread event carries, so a subscriber never needs to query back. */
+export interface ThreadEventData {
+    subjectType: string;
+    subjectId: string;
+    orgId: string;
+    /** The thread after the change, or as it was before it was deleted. */
+    thread: CommentThread;
+}
+/** A thread event about one comment. */
+export interface CommentEventData extends ThreadEventData {
+    comment: Comment;
+}
+/** A deleted thread, with the comments that went with it, so features attached to them can clean up. */
+export interface ThreadDeletedData extends ThreadEventData {
+    commentIds: string[];
+}
+/** A thread that moved to another organization with its record, and its comments that moved with it. */
+export interface ThreadMovedData extends ThreadDeletedData {
+    fromOrgId: string;
+}
+/** A thread's anchor, as `thread.anchorUpdated` reports the previous one. */
+export interface StoredAnchor {
+    kind: string;
+    value: unknown;
+    version: string | null;
+}
+/**
+ * The events comments emit. They stay on the server, because they can hold previous bodies and threads in restricted
+ * visibilities; browsers get them only through `toClientEvent`.
+ */
+export declare const commentEvents: {
+    "thread.created": import("better-apps").EventDefinition<CommentEventData>;
+    "thread.updated": import("better-apps").EventDefinition<ThreadEventData & {
+        previous: Partial<CommentThread>;
+    }>;
+    "comment.created": import("better-apps").EventDefinition<CommentEventData>;
+    "comment.edited": import("better-apps").EventDefinition<CommentEventData & {
+        previousFormat: string;
+        previousBody: unknown;
+    }>;
+    "comment.deleted": import("better-apps").EventDefinition<CommentEventData & {
+        previousBody: unknown;
+        previousText: string;
+    }>;
+    "comment.mentioned": import("better-apps").EventDefinition<CommentEventData & {
+        userId: string;
+    }>;
+    "thread.resolved": import("better-apps").EventDefinition<ThreadEventData>;
+    "thread.reopened": import("better-apps").EventDefinition<ThreadEventData>;
+    "thread.anchorUpdated": import("better-apps").EventDefinition<ThreadEventData & {
+        previousAnchor: StoredAnchor | null;
+    }>;
+    "thread.deleted": import("better-apps").EventDefinition<ThreadDeletedData>;
+    "thread.moved": import("better-apps").EventDefinition<ThreadMovedData>;
+    "subject.moved": import("better-apps").EventDefinition<{
+        subjectType: string;
+        subjectId: string;
+        toOrgId: string;
+    }>;
+    "subject.removed": import("better-apps").EventDefinition<{
+        subjectType: string;
+        subjectId: string;
+    }>;
+    "user.removed": import("better-apps").EventDefinition<{
+        userId: string;
+    }>;
+};
+/** The data of each comments event, by type. */
+export type CommentsEventData = {
+    [Type in keyof typeof commentEvents]: (typeof commentEvents)[Type] extends {
+        "~data"?: infer Data;
+    } ? NonNullable<Data> : never;
+};

package/dist/events.js

@@ -0,0 +1,21 @@
+import { defineEvent } from "better-apps";
+/**
+ * The events comments emit. They stay on the server, because they can hold previous bodies and threads in restricted
+ * visibilities; browsers get them only through `toClientEvent`.
+ */
+export const commentEvents = {
+    "thread.created": defineEvent(),
+    "thread.updated": defineEvent(),
+    "comment.created": defineEvent(),
+    "comment.edited": defineEvent(),
+    "comment.deleted": defineEvent(),
+    "comment.mentioned": defineEvent(),
+    "thread.resolved": defineEvent(),
+    "thread.reopened": defineEvent(),
+    "thread.anchorUpdated": defineEvent(),
+    "thread.deleted": defineEvent(),
+    "thread.moved": defineEvent(),
+    "subject.moved": defineEvent(),
+    "subject.removed": defineEvent(),
+    "user.removed": defineEvent()
+};

package/dist/feature.d.ts

@@ -0,0 +1,270 @@
+import type { AnchorKind } from "@better-apps/anchors";
+import { type Actor, type BetterAppsEvent, type IdentityUser, type StandardSchemaV1 } from "better-apps";
+import type { CommentTarget, CommentsOptions, CreateThreadInput, EditCommentInput, ReplyInput, ThreadTarget, TypesOf, UpdateAnchorInput, UpdateThreadInput } from "./options.js";
+import { type ClientEvent, type LiveViewer, type ThreadPage, type ThreadWithComments } from "./reads.js";
+import { type Comment, type CommentThread } from "./schema.js";
+import { type UpkeepStep } from "./upkeep.js";
+/** The input of `listThreads`. */
+export interface ListThreadsInput<SubjectType extends string = string, AnchorKindName extends string = string> {
+    subjectType: SubjectType;
+    subjectId: string;
+    status?: "open" | "resolved" | undefined;
+    /** `null` lists threads on the whole subject. */
+    anchorKind?: AnchorKindName | null | undefined;
+    /** Equality filters on additional fields declared with `index: true`. */
+    where?: Record<string, string | number | boolean | null> | undefined;
+    /** `activity`, the default, puts the most recently active first; `created` the newest. */
+    order?: "activity" | "created" | undefined;
+    cursor?: string | undefined;
+    /** 20 by default, at most 50. */
+    limit?: number | undefined;
+}
+/** The input of `getThread`. */
+export interface GetThreadInput {
+    threadId: string;
+    cursor?: string | undefined;
+    /** 50 by default, at most 100. */
+    limit?: number | undefined;
+}
+/** The input of `countThreads`. */
+export interface CountThreadsInput<SubjectType extends string = string> {
+    subjectType: SubjectType;
+    /** Up to 50. */
+    subjectIds: readonly string[];
+    status?: "open" | "resolved" | undefined;
+}
+/** Open and total threads on a subject, counting only visibilities the caller can see. */
+export interface ThreadCounts {
+    open: number;
+    total: number;
+}
+/** The input of `suggestMentions`: a thread, or a subject for a thread not created yet. */
+export type SuggestMentionsInput<SubjectType extends string = string> = {
+    threadId: string;
+    query: string;
+} | {
+    subjectType: SubjectType;
+    subjectId: string;
+    query: string;
+};
+/** What `createThread` and `reply` return. */
+export interface WriteResult<Thread, Message> {
+    thread: Thread;
+    comment: Message;
+    /** Mentions that won't notify anyone because those users can't view the thread. Only moderators get the list. */
+    droppedMentions: string[];
+}
+/**
+ * Comment threads on records the app owns, optionally pinned to a spot inside them. Set up at least one of the app's
+ * subject types; anchor kinds, body formats, before hooks and additional fields are optional. Threads and comments are
+ * subject types too, `comments.thread` and `comments.comment`, so other features can attach to them.
+ */
+export declare function comments<const Options extends CommentsOptions>(options: Options): {
+    readonly id: "comments";
+    readonly schema: import("better-apps").FeatureSchema;
+    readonly events: {
+        "thread.created": import("better-apps").EventDefinition<import("./events.js").CommentEventData>;
+        "thread.updated": import("better-apps").EventDefinition<import("./events.js").ThreadEventData & {
+            previous: Partial<CommentThread>;
+        }>;
+        "comment.created": import("better-apps").EventDefinition<import("./events.js").CommentEventData>;
+        "comment.edited": import("better-apps").EventDefinition<import("./events.js").CommentEventData & {
+            previousFormat: string;
+            previousBody: unknown;
+        }>;
+        "comment.deleted": import("better-apps").EventDefinition<import("./events.js").CommentEventData & {
+            previousBody: unknown;
+            previousText: string;
+        }>;
+        "comment.mentioned": import("better-apps").EventDefinition<import("./events.js").CommentEventData & {
+            userId: string;
+        }>;
+        "thread.resolved": import("better-apps").EventDefinition<import("./events.js").ThreadEventData>;
+        "thread.reopened": import("better-apps").EventDefinition<import("./events.js").ThreadEventData>;
+        "thread.anchorUpdated": import("better-apps").EventDefinition<import("./events.js").ThreadEventData & {
+            previousAnchor: import("./events.js").StoredAnchor | null;
+        }>;
+        "thread.deleted": import("better-apps").EventDefinition<import("./events.js").ThreadDeletedData>;
+        "thread.moved": import("better-apps").EventDefinition<import("./events.js").ThreadMovedData>;
+        "subject.moved": import("better-apps").EventDefinition<{
+            subjectType: string;
+            subjectId: string;
+            toOrgId: string;
+        }>;
+        "subject.removed": import("better-apps").EventDefinition<{
+            subjectType: string;
+            subjectId: string;
+        }>;
+        "user.removed": import("better-apps").EventDefinition<{
+            userId: string;
+        }>;
+    };
+    readonly subjects: Record<string, import("better-apps").SubjectDefinition>;
+    readonly grants: import("better-apps").SubjectGrants;
+    readonly usesSubjects: string[];
+    readonly options: Options;
+    readonly actions: {
+        listThreads: import("better-apps").ActionDefinition<StandardSchemaV1<ListThreadsInput<keyof Options["subjects"] & string, (Options["anchors"] extends infer T ? T extends Options["anchors"] ? T extends readonly (infer Anchor)[] ? Anchor extends AnchorKind<infer Kind extends string, infer Value> ? {
+            kind: Kind;
+            value: Value;
+            version?: string | null | undefined;
+        } : never : never : never : never)["kind"]>, ListThreadsInput<keyof Options["subjects"] & string, (Options["anchors"] extends infer T ? T extends Options["anchors"] ? T extends readonly (infer Anchor)[] ? Anchor extends AnchorKind<infer Kind extends string, infer Value> ? {
+            kind: Kind;
+            value: Value;
+            version?: string | null | undefined;
+        } : never : never : never : never)["kind"]>>, ThreadPage<CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>)>> & {
+            serverOnly?: false | undefined;
+        };
+        getThread: import("better-apps").ActionDefinition<StandardSchemaV1<GetThreadInput, GetThreadInput>, ThreadWithComments<CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>), Comment & (Options["additionalFields"] extends {
+            comment: infer Fields_1;
+        } ? import("./schema.js").InferFields<Fields_1> : Record<never, never>)>> & {
+            serverOnly?: false | undefined;
+        };
+        countThreads: import("better-apps").ActionDefinition<StandardSchemaV1<CountThreadsInput<keyof Options["subjects"] & string>, CountThreadsInput<keyof Options["subjects"] & string>>, Record<string, ThreadCounts>> & {
+            serverOnly?: false | undefined;
+        };
+        createThread: import("better-apps").ActionDefinition<StandardSchemaV1<CreateThreadInput<TypesOf<Options>>, CreateThreadInput<TypesOf<Options>>>, WriteResult<CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>), Comment & (Options["additionalFields"] extends {
+            comment: infer Fields_1;
+        } ? import("./schema.js").InferFields<Fields_1> : Record<never, never>)>> & {
+            serverOnly?: false | undefined;
+        };
+        reply: import("better-apps").ActionDefinition<StandardSchemaV1<ReplyInput<TypesOf<Options>>, ReplyInput<TypesOf<Options>>>, WriteResult<CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>), Comment & (Options["additionalFields"] extends {
+            comment: infer Fields_1;
+        } ? import("./schema.js").InferFields<Fields_1> : Record<never, never>)>> & {
+            serverOnly?: false | undefined;
+        };
+        editComment: import("better-apps").ActionDefinition<StandardSchemaV1<EditCommentInput<TypesOf<Options>>, EditCommentInput<TypesOf<Options>>>, {
+            comment: Comment & (Options["additionalFields"] extends {
+                comment: infer Fields_1;
+            } ? import("./schema.js").InferFields<Fields_1> : Record<never, never>);
+            droppedMentions: string[];
+        }> & {
+            serverOnly?: false | undefined;
+        };
+        deleteComment: import("better-apps").ActionDefinition<StandardSchemaV1<CommentTarget, CommentTarget>, {
+            comment: Comment & (Options["additionalFields"] extends {
+                comment: infer Fields_1;
+            } ? import("./schema.js").InferFields<Fields_1> : Record<never, never>);
+            threadDeleted: boolean;
+        }> & {
+            serverOnly?: false | undefined;
+        };
+        resolveThread: import("better-apps").ActionDefinition<StandardSchemaV1<ThreadTarget, ThreadTarget>, CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>)> & {
+            serverOnly?: false | undefined;
+        };
+        reopenThread: import("better-apps").ActionDefinition<StandardSchemaV1<ThreadTarget, ThreadTarget>, CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>)> & {
+            serverOnly?: false | undefined;
+        };
+        updateThread: import("better-apps").ActionDefinition<StandardSchemaV1<UpdateThreadInput<TypesOf<Options>>, UpdateThreadInput<TypesOf<Options>>>, CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>)> & {
+            serverOnly?: false | undefined;
+        };
+        updateAnchor: import("better-apps").ActionDefinition<StandardSchemaV1<UpdateAnchorInput<TypesOf<Options>>, UpdateAnchorInput<TypesOf<Options>>>, CommentThread & (Options["additionalFields"] extends {
+            thread: infer Fields;
+        } ? import("./schema.js").InferFields<Fields> : Record<never, never>)> & {
+            serverOnly?: false | undefined;
+        };
+        deleteThread: import("better-apps").ActionDefinition<StandardSchemaV1<ThreadTarget, ThreadTarget>, {
+            threadId: string;
+        }> & {
+            serverOnly?: false | undefined;
+        };
+        suggestMentions: import("better-apps").ActionDefinition<StandardSchemaV1<SuggestMentionsInput<keyof Options["subjects"] & string>, SuggestMentionsInput<keyof Options["subjects"] & string>>, IdentityUser[]> & {
+            serverOnly?: false | undefined;
+        };
+        removeSubject: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            subjectType: keyof Options["subjects"] & string;
+            subjectId: string;
+        }, {
+            subjectType: keyof Options["subjects"] & string;
+            subjectId: string;
+        }>, UpkeepStep> & {
+            serverOnly?: true | undefined;
+        };
+        moveSubject: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            subjectType: keyof Options["subjects"] & string;
+            subjectId: string;
+            toOrgId: string | null;
+        }, {
+            subjectType: keyof Options["subjects"] & string;
+            subjectId: string;
+            toOrgId: string | null;
+        }>, UpkeepStep> & {
+            serverOnly?: true | undefined;
+        };
+        removeUser: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            userId: string;
+        }, {
+            userId: string;
+        }>, UpkeepStep> & {
+            serverOnly?: true | undefined;
+        };
+        recountThreads: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            threadIds: readonly string[];
+        } | {
+            subjectType: keyof Options["subjects"] & string;
+            subjectId: string;
+            cursor?: string;
+        }, {
+            threadIds: readonly string[];
+        } | {
+            subjectType: keyof Options["subjects"] & string;
+            subjectId: string;
+            cursor?: string;
+        }>, UpkeepStep & {
+            cursor: string | null;
+        }> & {
+            serverOnly?: true | undefined;
+        };
+        canViewThread: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            actor: Actor | null;
+            threadId: string;
+        } | {
+            actor: Actor | null;
+            thread: CommentThread;
+        }, {
+            actor: Actor | null;
+            threadId: string;
+        } | {
+            actor: Actor | null;
+            thread: CommentThread;
+        }>, boolean> & {
+            serverOnly?: true | undefined;
+        };
+        toClientEvent: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            event: BetterAppsEvent;
+            viewer: Actor | null;
+            request?: Request | null | undefined;
+        }, {
+            event: BetterAppsEvent;
+            viewer: Actor | null;
+            request?: Request | null | undefined;
+        }>, ClientEvent | null> & {
+            serverOnly?: true | undefined;
+        };
+        toClientEvents: import("better-apps").ActionDefinition<StandardSchemaV1<{
+            event: BetterAppsEvent;
+            viewers: readonly LiveViewer[];
+        }, {
+            event: BetterAppsEvent;
+            viewers: readonly LiveViewer[];
+        }>, (ClientEvent | null)[]> & {
+            serverOnly?: true | undefined;
+        };
+    };
+};
+/** The comments feature as `comments()` returns it. */
+export type CommentsFeature<Options extends CommentsOptions = CommentsOptions> = ReturnType<typeof comments<Options>>;

package/dist/feature.js

@@ -0,0 +1,97 @@
+import { defineAction, defineFeature } from "better-apps";
+import { commentEvents } from "./events.js";
+import { textFormat } from "./formats.js";
+import { inputs } from "./inputs.js";
+import { canViewThread, countThreads, getThread, listThreads, suggestMentions, toClientEvent, toClientEvents } from "./reads.js";
+import { commentModel, commentsSchema, threadModel } from "./schema.js";
+import { commentGrants, commentSubjects } from "./subjects.js";
+import { moveSubject, recountThreads, removeSubject, removeUser } from "./upkeep.js";
+import { createThread, deleteComment, deleteThread, editComment, reopenThread, reply, resolveThread, updateAnchor, updateThread } from "./writes.js";
+const reserved = new Set([
+    ...Object.keys(commentsSchema()[threadModel]?.fields ?? {}),
+    ...Object.keys(commentsSchema()[commentModel]?.fields ?? {}),
+    "id"
+]);
+function resolve(options) {
+    if (Object.keys(options.subjects).length === 0) {
+        throw new Error("Comments need at least one subject type.");
+    }
+    const formats = new Map([[textFormat.name, textFormat]]);
+    for (const format of options.formats ?? []) {
+        if (formats.has(format.name)) {
+            throw new Error(`The "${format.name}" body format is registered twice.`);
+        }
+        formats.set(format.name, format);
+    }
+    const anchors = new Map();
+    for (const anchor of options.anchors ?? []) {
+        if (anchors.has(anchor.kind)) {
+            throw new Error(`The "${anchor.kind}" anchor kind is registered twice.`);
+        }
+        anchors.set(anchor.kind, anchor);
+    }
+    const threadFields = options.additionalFields?.thread ?? {};
+    const commentFields = options.additionalFields?.comment ?? {};
+    for (const name of [...Object.keys(threadFields), ...Object.keys(commentFields)]) {
+        if (reserved.has(name)) {
+            throw new Error(`"${name}" is a comments field, so it can't be an additional field.`);
+        }
+    }
+    return {
+        subjects: options.subjects,
+        anchors,
+        formats,
+        hooks: options.hooks?.before ?? {},
+        threadFields,
+        commentFields
+    };
+}
+const unchecked = () => ({
+    "~standard": { version: 1, vendor: "better-apps", validate: (value) => ({ value: value }) }
+});
+/**
+ * Comment threads on records the app owns, optionally pinned to a spot inside them. Set up at least one of the app's
+ * subject types; anchor kinds, body formats, before hooks and additional fields are optional. Threads and comments are
+ * subject types too, `comments.thread` and `comments.comment`, so other features can attach to them.
+ */
+export function comments(options) {
+    const config = resolve(options);
+    // `serverOnly` keeps its literal type, so the browser client leaves server-only actions out.
+    const action = (schema, run, serverOnly) => defineAction({
+        input: (schema ?? unchecked()),
+        serverOnly,
+        handler: async (context) => (await run(config, context))
+    });
+    const serverAction = (schema, run) => action(schema, run, true);
+    return defineFeature({
+        id: "comments",
+        schema: commentsSchema(options.additionalFields),
+        events: commentEvents,
+        subjects: commentSubjects(config),
+        grants: commentGrants(config),
+        usesSubjects: Object.keys(options.subjects),
+        options,
+        actions: {
+            listThreads: action(inputs.listThreads, listThreads),
+            getThread: action(inputs.getThread, getThread),
+            countThreads: action(inputs.countThreads, countThreads),
+            createThread: action(inputs.createThread, createThread),
+            reply: action(inputs.reply, reply),
+            editComment: action(inputs.editComment, editComment),
+            deleteComment: action(inputs.deleteComment, deleteComment),
+            resolveThread: action(inputs.thread, resolveThread),
+            reopenThread: action(inputs.thread, reopenThread),
+            updateThread: action(inputs.updateThread, updateThread),
+            updateAnchor: action(inputs.updateAnchor, updateAnchor),
+            deleteThread: action(inputs.thread, deleteThread),
+            suggestMentions: action(inputs.suggestMentions, suggestMentions),
+            removeSubject: serverAction(inputs.removeSubject, removeSubject),
+            moveSubject: serverAction(inputs.moveSubject, moveSubject),
+            removeUser: serverAction(inputs.removeUser, removeUser),
+            recountThreads: serverAction(inputs.recountThreads, recountThreads),
+            canViewThread: serverAction(null, canViewThread),
+            toClientEvent: serverAction(null, toClientEvent),
+            toClientEvents: serverAction(null, toClientEvents)
+        }
+    });
+}