better-supabase 0.13.0 → 0.15.0

package/dist/blocks/comments/index.d.ts

@@ -1,53 +1,271 @@
-import { j as CommentEventData, wt as Events } from "../../events-DhGgwqQA.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DBPhgF3W.js";
-import { s as BlockOf } from "../../define-block-MyM4lH42.js";
-import { C as mentionsIn, S as createComments, _ as CommentsOptions, a as CommentsSnapshot, b as activityListQuery, c as ActivityEntry, d as ActivitySinkOptions, f as ActivitySort, g as Comments, h as CommentEdit, i as CommentsControllerOptions, l as ActivityFacet, m as Comment, n as CommentsActions, o as createCommentsController, p as ActivitySource, r as CommentsController, s as ActivityDescription, t as CommentDraft, u as ActivityHistoryOptions, v as ListCommentsOptions, x as activitySink, y as NewComment } from "../../client-EQvEzUQg.js";
-//#region src/sql/subjects.d.ts
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { t as StandardSchemaV1 } from "../../standard-DBV730sF.js";
+import { r as FieldsOf } from "../../block-fields-BE7pInWZ.js";
+import { $ as RecordRef } from "../../types-DFdg_4yN.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { a as BlockTenantOptions, i as CursorPageOptions, r as BlockTemporalOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "../../block-hooks-DZN2w69m.js";
+import { N as CommentsSqlOptions } from "../../authorization-HZdJCaVm.js";
+import { t as Author } from "../../block-authors-DzXLUiIq.js";
+import { a as isFileAnchor, i as fileAnchor, n as FileAnchor, o as conversationTopic, r as FileAnchorAt, t as AnchorRegion } from "../../anchors-7F34QyHa.js";
+import { c as MessageEdit, l as MessageEdition, o as Message } from "../../messaging-C_Pr9tGx.js";
+import { Sn as EntitySchema, c as BlockOf, ln as RecordBindingWrite, mn as RecordRowInput, rn as RecordBinding } from "../../define-block-BVcLQ3DF.js";
+import { p as SubscriptionStatus } from "../../topic-CJrQZQaa.js";
+import { n as TopicPort } from "../../watch-topic-BcGfvZOE.js";
+import { n as Controller, t as AuthPort } from "../../controller-BrP0gn47.js";
+//#region src/blocks/comments/comments.d.ts
+interface CommentsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions, BlockTenantOptions {
+  /**
+   * A Standard Schema for the message extra columns
+   * (`blocks.messaging.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `create` and `edit`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Comments<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * The user ids (or mention groups) a comment mentions when the call passes no
+   * `mentionIds`, such as the mention nodes of a rich-text `document`. Default
+   * `mentionsIn(body)`.
+   */
+  readonly mentionsOf?: (comment: {
+    readonly body: string;
+    readonly document: unknown;
+  }) => readonly string[];
+}
 /**
- * One subject type a module's rows belong to (`options.subjects`): the table
- * its ids point at, and who may read it.
+ * A comment: a message in its record's conversation. `F` types the extra
+ * columns the `fields` schema describes.
  */
-interface Subject {
-  /** `schema.table`, or a table in `public`. */
-  readonly table: string;
-  /** Default `id`. */
-  readonly id?: string;
-  /**
-   * The id column's type, such as `uuid` or `bigint`. With it, the stored text
-   * id is cast to that type, so the lookup uses the subject table's primary
-   * key; without it the column is cast to text, which can't.
-   */
-  readonly idType?: string;
-  /**
-   * The subject's tenant column, default `organization_id`. `false` for a
-   * subject without a tenant (a user's own records), where the subject table's
-   * policies alone decide, in modules that allow it.
-   */
-  readonly tenant?: string | false;
-  /** A permission the caller also needs in the tenant, e.g. `projects.read`. */
-  readonly permission?: string;
-  /** Delete the module's rows for a subject when the subject row is deleted. */
-  readonly cascade?: boolean;
-  /** The module's own keys, such as a bucket per subject. */
-  readonly extra: Readonly<Record<string, unknown>>;
+interface Comment<F extends object = Record<never, never>> extends Message<F> {
+  /** The record the comment is on. */
+  readonly subject: RecordRef;
+  /** The work item `assign` turned it into, with the `tasks` block. */
+  readonly taskId: string | undefined;
 }
+interface NewComment<F extends object = Record<never, never>> {
+  /** Plain text; `@[Name](<user id>)` mentions a user. */
+  readonly body: string;
+  /** A rich-text document (any JSON); keep `body` as its plain text. */
+  readonly document?: unknown;
+  /**
+   * Where on the record the comment points, such as a text range or a field
+   * (any JSON), or a page, region or moment of a file (`fileAnchor`). Top-level
+   * comments only.
+   */
+  readonly anchor?: unknown;
+  /**
+   * User ids or mention groups (`options.mentionGroups`); default `mentionsOf`,
+   * or the ids `mentionsIn(body)` finds.
+   */
+  readonly mentionIds?: readonly string[];
+  /** A reply: with one level of threads, a reply to a reply joins the root. */
+  readonly parentId?: string;
+  /** Files the caller uploaded to the record's conversation (`attachments`). */
+  readonly attachmentIds?: readonly string[];
+  /** The extra columns to set, keyed by database name. */
+  readonly fields?: Partial<F>;
+}
+/** What `edit` takes. */
+type CommentEdit<F extends object = Record<never, never>> = MessageEdition<F>;
+/** What `assign` passes to the work item. */
+interface CommentAssignment {
+  /** Who works on it; nobody when left out. */
+  readonly assigneeId?: string;
+  /** Default the comment's first 120 characters. */
+  readonly title?: string;
+  /** Default the comment's body. */
+  readonly body?: string;
+  /** Other `create_work_item` attributes, such as `projectId` or `priority`. */
+  readonly attrs?: Readonly<Record<string, unknown>>;
+}
+interface ListCommentsOptions extends CursorPageOptions<Temporal.Instant> {
+  /** Comments sent after this instant, for polling a thread. */
+  readonly cursor?: Temporal.Instant;
+  /**
+   * The id of the last comment you have, next to `cursor`, so comments sent in
+   * the same instant as it aren't skipped.
+   */
+  readonly cursorId?: string;
+  /** Default 100, at most 500. */
+  readonly limit?: number;
+  /** Comments to skip, for page-number paging. */
+  readonly offset?: number;
+}
+/**
+ * `F` is the extra fields `options.fields` describes. Every method that takes a
+ * record acts in the block's `tenant`.
+ */
+interface Comments<F extends object = Record<never, never>> {
+  /** Posts a comment on `subject`, opening its conversation the first time. */
+  create(subject: RecordRef, comment: NewComment<F>): AsyncResult<Comment<F>>;
+  /** One comment, or `not_found` when the caller can't read it. */
+  get(id: string): AsyncResult<Comment<F>>;
+  /** The top-level comments anchored to a file (`fileAnchor`), oldest first. */
+  anchoredTo(attachmentId: string, options?: {
+    readonly limit?: number;
+  }): AsyncResult<Comment<F>[]>;
+  /** The author edits within `editWindow`; the old version is kept. */
+  edit(id: string, edit: CommentEdit<F>): AsyncResult<Comment<F>>;
+  /** Soft-deletes (the author, or a member with `comments.moderate`). */
+  remove(id: string): AsyncResult<boolean>;
+  /** Resolves a thread by its root comment, or opens it again. */
+  resolve(id: string, resolved?: boolean): AsyncResult<Comment<F>>;
+  /** Pins a comment to the top of its record, or unpins it. */
+  pin(id: string, pinned?: boolean): AsyncResult<Comment<F>>;
+  /** The earlier versions of an edited comment, newest first. */
+  edits(id: string): AsyncResult<readonly MessageEdit[]>;
+  /**
+   * Turns a comment into a work item (with the `tasks` block) and returns its
+   * id; assigning it again returns the same one.
+   */
+  assign(id: string, assignment?: CommentAssignment): AsyncResult<string>;
+  /**
+   * A record's comments and replies, oldest first, deleted ones as
+   * placeholders.
+   */
+  list(subject: RecordRef, options?: ListCommentsOptions): AsyncResult<readonly Comment<F>[]>;
+  /**
+   * How many comments each subject has that the caller can read, deleted ones
+   * left out, such as for a counter on each row of a list, keyed by
+   * `subjectKey(subject)` (`type:id`). Subjects without comments are 0.
+   */
+  counts(subjects: readonly RecordRef[]): AsyncResult<Readonly<Record<string, number>>>;
+  /**
+   * Copies a subject's thread to another subject in the tenant, keeping
+   * authors, times and replies; returns how many comments it copied. Needs a
+   * service-role transport.
+   */
+  copy(from: RecordRef, to: RecordRef): AsyncResult<number>;
+  /**
+   * The record's conversation id, for Realtime (`conversationTopic`) and for
+   * uploads to attach (`attachments` on subject `conversation`). `open` creates
+   * it before the first comment; without it, `undefined` until then.
+   */
+  conversation(subject: RecordRef, options?: {
+    readonly open?: boolean;
+  }): AsyncResult<string | undefined>;
+  /**
+   * Moves the caller's read marker on the record's comments forward; returns
+   * where it is, or `undefined` before the first comment.
+   */
+  markRead(subject: RecordRef, options?: {
+    readonly readAt?: Temporal.Instant;
+  }): AsyncResult<Temporal.Instant | undefined>;
+}
+/**
+ * The user ids mentioned in a body written as `@[Ada](user:<user id>)` or
+ * `@[Ada](<user id>)`, the markup mention inputs produce, in order and without
+ * repeats.
+ */
+export declare function mentionsIn(body: string): readonly string[];
+/** Comments over the messaging core, as the caller. */
+export declare function createComments<S extends StandardSchemaV1 | undefined = undefined>(options: CommentsOptions<S>): Comments<FieldsOf<S>>;
 //#endregion
-//#region src/sql/modules/comments.d.ts
-/** One commentable subject type: its table, and who may read it. */
-type CommentSubject = Omit<Subject, "extra">;
-//#endregion
-//#region src/blocks/comments/events.d.ts
-/** The events of the `comments` block: type to data. */
-type CommentsEvents = {
-  readonly "comment.created": CommentEventData;
-  readonly "comment.mentioned": CommentEventData;
-  readonly "comment.deleted": CommentEventData;
+//#region src/blocks/comments/record-binding.d.ts
+/** A pending write to a thread, for `useOptimistic`. */
+type CommentsOptimisticAction = {
+  readonly type: "add";
+  readonly comment: Comment;
+} | {
+  readonly type: "edit";
+  readonly id: string;
+  readonly body: string;
+} | {
+  readonly type: "remove";
+  readonly id: string;
+};
+/**
+ * The thread with a pending write applied: `add` appends (or replaces the
+ * comment with the same id), `edit` changes the body, `remove` takes it out.
+ */
+export declare function commentsOptimistic(state: readonly Comment[], action: CommentsOptimisticAction): readonly Comment[];
+/** The writes of the comments binding. */
+type CommentsWrites = {
+  /** Adds a comment to the record's thread. */
+  readonly add: RecordBindingWrite<Comments, NewComment, Comment>;
+  /** Removes one comment; its author or a moderator. */
+  readonly remove: RecordBindingWrite<Comments, RecordRowInput, boolean>;
 };
-/** The `comments` block's event types, for its manifest and `onBlockEvent`. */
-export declare const commentsEvents: Events<CommentsEvents>;
+/**
+ * A record's comment thread, oldest first. The messaging events make it stale:
+ * a record conversation's messages carry `conversationKind: "subject"`.
+ */
+export declare const commentsBinding: RecordBinding<Comments, readonly Comment[], ListCommentsOptions, CommentsOptimisticAction, CommentsWrites>;
 //#endregion
 //#region src/blocks/comments/manifest.d.ts
-/** The `comments` block's manifest (ADR 0029). */
-export declare const commentsBlock: BlockOf<"comments", typeof createComments, CommentsEvents>;
+/** The `comments` block's manifest (ADR 0029, ADR 0062). */
+export declare const commentsBlock: BlockOf<"comments", typeof createComments, Record<never, never>, Record<never, never>, never, typeof commentsBinding>;
+//#endregion
+//#region src/blocks/comments/client.d.ts
+interface CommentsControllerOptions {
+  readonly client: Pick<Comments, "list" | "get" | "create" | "edit" | "remove" | "resolve" | "pin" | "conversation">;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The subject whose thread to follow; the thread waits without one. */
+  readonly subject: RecordRef | null;
+  /**
+   * `blocks.messaging.options.topic`, default `messages`: the thread joins the
+   * record conversation's private topic and fetches the comment each ping
+   * names, with its thread's root for the reply count. `null` turns Realtime
+   * off, so the thread loads again after its own writes only.
+   */
+  readonly topic?: string | null;
+  /** The most comments to load, default 100, at most 500. */
+  readonly limit?: number;
+}
+interface CommentsSnapshot {
+  /**
+   * The thread, oldest first, deleted comments as placeholders; `undefined`
+   * until the first load.
+   */
+  readonly comments: readonly Comment[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+}
+/** A reply, a rich-text document, an anchor, mentions or files for `add`. */
+type CommentDraft = Omit<NewComment, "body">;
+interface CommentsActions {
+  /** Posts a comment on the subject; a failure is also kept in `error`. */
+  readonly add: (body: string, draft?: CommentDraft) => Promise<Result<Comment>>;
+  /** Edits one of the caller's comments. */
+  readonly edit: (id: string, edit: CommentEdit) => Promise<Result<Comment>>;
+  /** Soft-deletes a comment: it stays in the thread as a placeholder. */
+  readonly remove: (id: string) => Promise<Result<boolean>>;
+  /** Resolves a thread by its root comment, or opens it again. */
+  readonly resolve: (id: string, resolved?: boolean) => Promise<Result<Comment>>;
+  readonly pin: (id: string, pinned?: boolean) => Promise<Result<Comment>>;
+  readonly refresh: () => Promise<void>;
+}
+type CommentsController = Controller<CommentsSnapshot, CommentsActions>;
+/**
+ * One subject's comment thread for the signed-in user: loads it, keeps it
+ * current after its own writes, and fetches the one comment each ping on the
+ * record conversation's topic names (joined once the record has a
+ * conversation), so a busy thread never reloads whole.
+ */
+export declare function createCommentsController(options: CommentsControllerOptions): CommentsController;
+//#endregion
+//#region src/blocks/comments/schemas.d.ts
+/**
+ * What `create` takes after the subject. The body's length limit is
+ * `blocks.messaging.options.maxBodyLength`, so the SQL checks it.
+ */
+export declare const commentInputSchema: EntitySchema<NewComment>;
+/** What `edit` takes: a message edit. */
+export declare const commentChangeSchema: EntitySchema<CommentEdit>;
 //#endregion
-export { type ActivityDescription, type ActivityEntry, type ActivityFacet, type ActivityHistoryOptions, type ActivitySinkOptions, type ActivitySort, type ActivitySource, type BlockTransport, type Comment, type CommentDraft, type CommentEdit, type CommentSubject, type Comments, type CommentsActions, type CommentsController, type CommentsControllerOptions, type CommentsEvents, type CommentsOptions, type CommentsSnapshot, type ListCommentsOptions, type NewComment, activityListQuery, activitySink, createComments, createCommentsController, dbTransport, mentionsIn, rpcTransport, sqlTransport };
+export { type AnchorRegion, type Author, type BlockTransport, type Comment, type CommentAssignment, type CommentDraft, type CommentEdit, type Comments, type CommentsActions, type CommentsController, type CommentsControllerOptions, type CommentsOptimisticAction, type CommentsOptions, type CommentsSnapshot, type CommentsSqlOptions, type CommentsWrites, type FileAnchor, type FileAnchorAt, type ListCommentsOptions, type MessageEdit, type NewComment, conversationTopic, dbTransport, fileAnchor, isFileAnchor, rpcTransport, sqlTransport };