@liveblocks/node 1.8.1 → 1.8.3-oss1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { IUserInfo, Json, PlainLsonObject, JsonObject, ThreadData, BaseMetadata, CommentData, CommentBody, CommentUserReaction } from '@liveblocks/core';
+export { CommentBody, CommentBodyBlockElement, CommentBodyElement, CommentBodyInlineElement, CommentBodyLink, CommentBodyLinkElementArgs, CommentBodyMention, CommentBodyMentionElementArgs, CommentBodyParagraph, CommentBodyParagraphElementArgs, CommentBodyResolveUsersArgs, CommentBodyText, CommentBodyTextElementArgs, CommentData, CommentUserReaction, IUserInfo, Json, JsonArray, JsonObject, JsonScalar, Lson, LsonObject, PlainLsonObject, StringifyCommentBodyElements, StringifyCommentBodyOptions, ThreadData, User, getMentionedIdsFromCommentBody, stringifyCommentBody } from '@liveblocks/core';
 import { IncomingHttpHeaders } from 'http';
 
 /**
@@ -88,174 +90,6 @@ declare type AuthorizeResponse = {
  */
 declare function authorize(options: AuthorizeOptions): Promise<AuthorizeResponse>;
 
-/**
- * Represents an indefinitely deep arbitrary JSON data structure. There are
- * four types that make up the Json family:
- *
- * - Json         any legal JSON value
- * - JsonScalar   any legal JSON leaf value (no lists or objects)
- * - JsonArray    a JSON value whose outer type is an array
- * - JsonObject   a JSON value whose outer type is an object
- *
- */
-declare type Json = JsonScalar | JsonArray | JsonObject;
-declare type JsonScalar = string | number | boolean | null;
-declare type JsonArray = Json[];
-declare type JsonObject = {
-    [key: string]: Json | undefined;
-};
-
-/**
- * "Plain LSON" is a JSON-based format that's used when serializing Live structures
- * to send them over HTTP (e.g. in the API endpoint to let users upload their initial
- * Room storage, in the API endpoint to fetch a Room's storage, ...).
- *
- * In the client, you would typically create LSON values using:
- *
- *    new LiveObject({ x: 0, y: 0 })
- *
- * But over HTTP, this has to be serialized somehow. The "Plain LSON" format
- * is what's used in the POST /init-storage-new endpoint, to allow users to
- * control which parts of their data structure should be considered "Live"
- * objects, and which parts are "normal" objects.
- *
- * So if they have a structure like:
- *
- *    { x: 0, y: 0 }
- *
- * And want to make it a Live object, they can serialize it by wrapping it in
- * a special "annotation":
- *
- *    {
- *      "liveblocksType": "LiveObject",
- *      "data": { x: 0, y: 0 },
- *    }
- *
- * This "Plain LSON" data format defines exactly those wrappings.
- *
- * To summarize:
- *
- *   LSON value            |  Plain LSON equivalent
- *   ----------------------+----------------------------------------------
- *   42                    |  42
- *   [1, 2, 3]             |  [1, 2, 3]
- *   { x: 0, y: 0 }        |  { x: 0, y: 0 }
- *   ----------------------+----------------------------------------------
- *   new LiveList(...)     |  { liveblocksType: "LiveList",   data: ... }
- *   new LiveMap(...)      |  { liveblocksType: "LiveMap",    data: ... }
- *   new LiveObject(...)   |  { liveblocksType: "LiveObject", data: ... }
- *
- */
-
-declare type PlainLsonFields = Record<string, PlainLson>;
-declare type PlainLsonObject = {
-    liveblocksType: "LiveObject";
-    data: PlainLsonFields;
-};
-declare type PlainLsonMap = {
-    liveblocksType: "LiveMap";
-    data: PlainLsonFields;
-};
-declare type PlainLsonList = {
-    liveblocksType: "LiveList";
-    data: PlainLson[];
-};
-declare type PlainLson = PlainLsonObject | PlainLsonMap | PlainLsonList | Json;
-
-/**
- * Represents some constraints for user info. Basically read this as: "any JSON
- * object is fine, but _if_ it has a name field, it _must_ be a string."
- * (Ditto for avatar.)
- */
-declare type IUserInfo = {
-    [key: string]: Json | undefined;
-    name?: string;
-    avatar?: string;
-};
-/**
- * This type is used by clients to define the metadata for a user.
- */
-declare type BaseUserMeta = {
-    /**
-     * The id of the user that has been set in the authentication endpoint.
-     * Useful to get additional information about the connected user.
-     */
-    id?: string;
-    /**
-     * Additional user information that has been set in the authentication endpoint.
-     */
-    info?: IUserInfo;
-};
-
-declare type BaseMetadata = Record<string, string | boolean | number>;
-
-declare type CommentBodyBlockElement = CommentBodyParagraph;
-declare type CommentBodyInlineElement = CommentBodyText | CommentBodyMention | CommentBodyLink;
-declare type CommentBodyParagraph = {
-    type: "paragraph";
-    children: CommentBodyInlineElement[];
-};
-declare type CommentBodyMention = {
-    type: "mention";
-    id: string;
-};
-declare type CommentBodyLink = {
-    type: "link";
-    url: string;
-};
-declare type CommentBodyText = {
-    bold?: boolean;
-    italic?: boolean;
-    strikethrough?: boolean;
-    code?: boolean;
-    text: string;
-};
-declare type CommentBody = {
-    version: 1;
-    content: CommentBodyBlockElement[];
-};
-
-declare type CommentReactionUser = {
-    id: string;
-};
-declare type CommentReaction = {
-    emoji: string;
-    createdAt: string;
-    users: CommentReactionUser[];
-};
-/**
- * Represents a comment.
- */
-declare type CommentData = {
-    type: "comment";
-    id: string;
-    threadId: string;
-    roomId: string;
-    userId: string;
-    createdAt: string;
-    editedAt?: string;
-    reactions: CommentReaction[];
-} & ({
-    body: CommentBody;
-    deletedAt?: never;
-} | {
-    body?: never;
-    deletedAt: string;
-});
-
-/**
- * Represents a thread of comments.
- */
-declare type ThreadData<TThreadMetadata extends BaseMetadata = never> = {
-    type: "thread";
-    id: string;
-    roomId: string;
-    createdAt: string;
-    updatedAt?: string;
-    comments: CommentData[];
-    metadata: [TThreadMetadata] extends [never] ? Record<string, never> : TThreadMetadata;
-};
-
 declare const ALL_PERMISSIONS: readonly ["room:write", "room:read", "room:presence:write", "comments:write", "comments:read"];
 declare type Permission = (typeof ALL_PERMISSIONS)[number];
 /**
@@ -318,6 +152,9 @@ declare type LiveblocksOptions = {
      */
     secret: string;
 };
+declare type Nullable<T> = {
+    [P in keyof T]: T[P] | null;
+};
 declare type CreateSessionOptions = {
     userInfo: IUserInfo;
 };
@@ -492,7 +329,9 @@ declare class Liveblocks {
      * @param roomId The id of the room to get the users from.
      * @returns A list of users currently present in the requested room.
      */
-    getActiveUsers<T = unknown>(roomId: string): Promise<RoomUser<T>[]>;
+    getActiveUsers<T = unknown>(roomId: string): Promise<{
+        data: RoomUser<T>[];
+    }>;
     /**
      * Boadcasts an event to a room without having to connect to it via the client from @liveblocks/client. The connectionId passed to event listeners is -1 when using this API.
      * @param roomId The id of the room to broadcast the event to.
@@ -626,10 +465,10 @@ declare class Liveblocks {
      * @param params.threadId The thread ID.
      * @returns A thread.
      */
-    getThread(params: {
+    getThread<TThreadMetadata extends BaseMetadata = never>(params: {
         roomId: string;
         threadId: string;
-    }): Promise<ThreadData>;
+    }): Promise<ThreadData<TThreadMetadata>>;
     /**
      * Gets a thread's participants.
      *
@@ -657,97 +496,133 @@ declare class Liveblocks {
         threadId: string;
         commentId: string;
     }): Promise<CommentData>;
-}
-
-declare type PromiseOrNot<T> = T | Promise<T>;
-declare type CommentBodyResolveUsersArgs = {
     /**
-     * The ID of the users to resolve.
-     */
-    userIds: string[];
-};
-declare type CommentBodyParagraphElementArgs = {
-    /**
-     * The paragraph element.
-     */
-    element: CommentBodyParagraph;
-    /**
-     * The text content of the paragraph.
-     */
-    children: string;
-};
-declare type CommentBodyTextElementArgs = {
-    /**
-     * The text element.
-     */
-    element: CommentBodyText;
-};
-declare type CommentBodyLinkElementArgs = {
-    /**
-     * The link element.
-     */
-    element: CommentBodyLink;
-    /**
-     * The absolute URL of the link.
-     */
-    href: string;
-};
-declare type CommentBodyMentionElementArgs<TUserMeta extends BaseUserMeta = BaseUserMeta> = {
-    /**
-     * The mention element.
-     */
-    element: CommentBodyMention;
-    /**
-     * The mention's user info, if the `resolvedUsers` option was provided.
-     */
-    user?: TUserMeta["info"];
-};
-declare type StringifyCommentBodyElements<TUserMeta extends BaseUserMeta = BaseUserMeta> = {
-    /**
-     * The element used to display paragraphs.
-     */
-    paragraph: (args: CommentBodyParagraphElementArgs, index: number) => string;
-    /**
-     * The element used to display text elements.
-     */
-    text: (args: CommentBodyTextElementArgs, index: number) => string;
-    /**
-     * The element used to display links.
-     */
-    link: (args: CommentBodyLinkElementArgs, index: number) => string;
-    /**
-     * The element used to display mentions.
-     */
-    mention: (args: CommentBodyMentionElementArgs<TUserMeta>, index: number) => string;
-};
-declare type StringifyCommentBodyOptions<TUserMeta extends BaseUserMeta = BaseUserMeta> = {
-    /**
-     * Which format to convert the comment to.
-     */
-    format?: "plain" | "html" | "markdown";
+     * Creates a comment.
+     *
+     * @param params.roomId The room ID to create the comment in.
+     * @param params.threadId The thread ID to create the comment in.
+     * @param params.data.userId The user ID of the user who is set to create the comment.
+     * @param params.data.createdAt (optional) The date the comment is set to be created.
+     * @param params.data.body The body of the comment.
+     * @returns The created comment.
+     */
+    createComment(params: {
+        roomId: string;
+        threadId: string;
+        data: {
+            userId: string;
+            createdAt?: Date;
+            body: CommentBody;
+        };
+    }): Promise<CommentData>;
     /**
-     * The elements used to customize the resulting string. Each element has
-     * priority over the defaults inherited from the `format` option.
+     * Edits a comment.
+     * @param params.roomId The room ID to edit the comment in.
+     * @param params.threadId The thread ID to edit the comment in.
+     * @param params.commentId The comment ID to edit.
+     * @param params.data.body The body of the comment.
+     * @param params.data.editedAt (optional) The date the comment was edited.
+     * @returns The edited comment.
      */
-    elements?: Partial<StringifyCommentBodyElements<TUserMeta>>;
+    editComment(params: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+        data: {
+            body: CommentBody;
+            editedAt?: Date;
+        };
+    }): Promise<CommentData>;
     /**
-     * The separator used between paragraphs.
+     * Deletes a comment. Deletes a comment. If there are no remaining comments in the thread, the thread is also deleted.
+     * @param params.roomId The room ID to delete the comment in.
+     * @param params.threadId The thread ID to delete the comment in.
+     * @param params.commentId The comment ID to delete.
      */
-    separator?: string;
+    deleteComment(params: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
     /**
-     * A function that returns user info from user IDs.
+     * Creates a new thread. The thread will be created with the specified comment as its first comment.
+     * If the thread already exists, a `LiveblocksError` will be thrown with status code 409.
+     * @param params.roomId The room ID to create the thread in.
+     * @param params.thread.metadata (optional) The metadata for the thread. Supports upto a maximum of 10 entries. Value must be a string, boolean or number
+     * @param params.thread.comment.userId The user ID of the user who created the comment.
+     * @param params.thread.comment.createdAt (optional) The date the comment was created.
+     * @param params.thread.comment.body The body of the comment.
+     * @returns The created thread. The thread will be created with the specified comment as its first comment.
      */
-    resolveUsers?: (args: CommentBodyResolveUsersArgs) => PromiseOrNot<(TUserMeta["info"] | undefined)[] | undefined>;
-};
-/**
- * Get an array of each user's ID that has been mentioned in a `CommentBody`.
- */
-declare function getMentionedIdsFromCommentBody(body: CommentBody): string[];
-/**
- * Convert a `CommentBody` into either a plain string,
- * Markdown, HTML, or a custom format.
- */
-declare function stringifyCommentBody<TUserMeta extends BaseUserMeta = BaseUserMeta>(body: CommentBody, options?: StringifyCommentBodyOptions<TUserMeta>): Promise<string>;
+    createThread<TThreadMetadata extends BaseMetadata = never>(params: {
+        roomId: string;
+        data: {
+            metadata?: [TThreadMetadata] extends [never] ? Record<string, never> : TThreadMetadata;
+            comment: {
+                userId: string;
+                createdAt?: Date;
+                body: CommentBody;
+            };
+        };
+    }): Promise<ThreadData<TThreadMetadata>>;
+    /**
+     * Updates the metadata of the specified thread in a room.
+     * @param params.roomId The room ID to update the thread in.
+     * @param params.threadId The thread ID to update.
+     * @param params.data.metadata The metadata for the thread. Value must be a string, boolean or number
+     * @param params.data.userId The user ID of the user who updated the thread.
+     * @param params.data.updatedAt (optional) The date the thread is set to be updated.
+     * @returns The updated thread.
+     */
+    editThreadMetadata<TThreadMetadata extends BaseMetadata = never>(params: {
+        roomId: string;
+        threadId: string;
+        data: {
+            metadata: Nullable<BaseMetadata>;
+            userId: string;
+            updatedAt?: Date;
+        };
+    }): Promise<TThreadMetadata>;
+    /**
+     * Adds a new comment reaction to a comment.
+     * @param params.roomId The room ID to add the comment reaction in.
+     * @param params.threadId The thread ID to add the comment reaction in.
+     * @param params.commentId The comment ID to add the reaction in.
+     * @param params.data.emoji The (emoji) reaction to add.
+     * @param params.data.userId The user ID of the user associated with the reaction.
+     * @param params.data.createdAt (optional) The date the reaction is set to be created.
+     * @returns The created comment reaction.
+     */
+    addCommentReaction(params: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+        data: {
+            emoji: string;
+            userId: string;
+            createdAt?: Date;
+        };
+    }): Promise<CommentUserReaction>;
+    /**
+     * Removes a reaction from a comment.
+     * @param params.roomId The room ID to remove the comment reaction from.
+     * @param params.threadId The thread ID to remove the comment reaction from.
+     * @param params.commentId The comment ID to remove the reaction from.
+     * @param params.data.emoji The (emoji) reaction to remove.
+     * @param params.data.userId The user ID of the user associated with the reaction.
+     * @param params.data.removedAt (optional) The date the reaction is set to be removed.
+     */
+    removeCommentReaction(params: {
+        roomId: string;
+        threadId: string;
+        commentId: string;
+        data: {
+            emoji: string;
+            userId: string;
+            removedAt?: Date;
+        };
+    }): Promise<void>;
+}
 
 declare class WebhookHandler {
     private secretBuffer;
@@ -987,4 +862,4 @@ declare type ThreadCreatedEvent = {
     };
 };
 
-export { CommentBodyLinkElementArgs, CommentBodyMentionElementArgs, CommentBodyParagraphElementArgs, CommentBodyResolveUsersArgs, CommentBodyTextElementArgs, CommentCreatedEvent, CommentData, CommentDeletedEvent, CommentEditedEvent, CommentReactionAdded, CommentReactionRemoved, IUserInfo, Json, JsonObject, Liveblocks, LiveblocksOptions, PlainLsonObject, RoomAccesses, RoomCreatedEvent, RoomDeletedEvent, RoomInfo, RoomPermission, RoomUser, Schema, StorageUpdatedEvent, StringifyCommentBodyElements, StringifyCommentBodyOptions, ThreadCreatedEvent, ThreadData, ThreadMetadataUpdatedEvent, ThreadParticipants, UserEnteredEvent, UserLeftEvent, WebhookEvent, WebhookHandler, WebhookRequest, authorize, getMentionedIdsFromCommentBody, stringifyCommentBody };
+export { type CommentCreatedEvent, type CommentDeletedEvent, type CommentEditedEvent, type CommentReactionAdded, type CommentReactionRemoved, Liveblocks, type LiveblocksOptions, type RoomAccesses, type RoomCreatedEvent, type RoomDeletedEvent, type RoomInfo, type RoomPermission, type RoomUser, type Schema, type StorageUpdatedEvent, type ThreadCreatedEvent, type ThreadMetadataUpdatedEvent, type ThreadParticipants, type UserEnteredEvent, type UserLeftEvent, type WebhookEvent, WebhookHandler, type WebhookRequest, authorize };