@liveblocks/node 1.8.1 → 1.9.0-example1

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 { CommentCreatedEvent, CommentDeletedEvent, CommentEditedEvent, CommentReactionAdded, CommentReactionRemoved, Liveblocks, LiveblocksOptions, RoomAccesses, RoomCreatedEvent, RoomDeletedEvent, RoomInfo, RoomPermission, RoomUser, Schema, StorageUpdatedEvent, ThreadCreatedEvent, ThreadMetadataUpdatedEvent, ThreadParticipants, UserEnteredEvent, UserLeftEvent, WebhookEvent, WebhookHandler, WebhookRequest, authorize };