@liveblocks/core 2.3.0 → 2.4.0

package/dist/index.d.mts

@@ -1715,68 +1715,177 @@ declare type SubscribeFn<P extends JsonObject, _TStorage extends LsonObject, U e
      * });
      */
     (type: "storage-status", listener: Callback<StorageStatus>): () => void;
+    (type: "comments", listener: Callback<CommentsEventServerMsg>): () => void;
 };
 declare type GetThreadsOptions<M extends BaseMetadata> = {
     query?: {
         resolved?: boolean;
         metadata?: Partial<QueryMetadata<M>>;
     };
-    since?: Date;
 };
 declare type CommentsApi<M extends BaseMetadata> = {
+    /**
+     * Returns the threads within the current room and their associated inbox notifications.
+     * It also returns the request date that can be used for subsequent polling.
+     *
+     * @example
+     * const {
+     *   threads,
+     *   inboxNotifications,
+     *   requestedAt
+     * } = await room.getThreads({ query: { resolved: false }});
+     */
     getThreads(options?: GetThreadsOptions<M>): Promise<{
         threads: ThreadData<M>[];
         inboxNotifications: InboxNotificationData[];
-        deletedThreads: ThreadDeleteInfo[];
-        deletedInboxNotifications: InboxNotificationDeleteInfo[];
-        meta: {
-            requestedAt: Date;
-        };
+        requestedAt: Date;
     }>;
-    getThread(options: {
-        threadId: string;
+    /**
+     * Returns the updated and deleted threads and their associated inbox notifications since the requested date.
+     *
+     * @example
+     * const result = await room.getThreads();
+     * // ... //
+     * await room.getThreadsSince({ since: result.requestedAt });
+     */
+    getThreadsSince(options: {
+        since: Date;
     }): Promise<{
-        thread: ThreadData<M>;
+        threads: {
+            updated: ThreadData<M>[];
+            deleted: ThreadDeleteInfo[];
+        };
+        inboxNotifications: {
+            updated: InboxNotificationData[];
+            deleted: InboxNotificationDeleteInfo[];
+        };
+        requestedAt: Date;
+    }>;
+    /**
+     * Returns a thread and the associated inbox notification if it exists.
+     *
+     * @example
+     * const { thread, inboxNotification } = await room.getThread("th_xxx");
+     */
+    getThread(threadId: string): Promise<{
+        thread?: ThreadData<M>;
         inboxNotification?: InboxNotificationData;
-    } | undefined>;
+    }>;
+    /**
+     * Creates a thread.
+     *
+     * @example
+     * const thread = await room.createThread({
+     *   body: {
+     *     version: 1,
+     *     content: [{ type: "paragraph", children: [{ text: "Hello" }] }],
+     *   },
+     * })
+     */
     createThread(options: {
-        threadId: string;
-        commentId: string;
+        threadId?: string;
+        commentId?: string;
         metadata: M | undefined;
         body: CommentBody;
     }): Promise<ThreadData<M>>;
-    deleteThread(options: {
-        threadId: string;
-    }): Promise<void>;
+    /**
+     * Deletes a thread.
+     *
+     * @example
+     * await room.deleteThread("th_xxx");
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Edits a thread's metadata.
+     * To delete an existing metadata property, set its value to `null`.
+     *
+     * @example
+     * await room.editThreadMetadata({ threadId: "th_xxx", metadata: { x: 100, y: 100 } })
+     */
     editThreadMetadata(options: {
         metadata: Patchable<M>;
         threadId: string;
     }): Promise<M>;
-    markThreadAsResolved(options: {
-        threadId: string;
-    }): Promise<void>;
-    markThreadAsUnresolved(options: {
-        threadId: string;
-    }): Promise<void>;
+    /**
+     * Marks a thread as resolved.
+     *
+     * @example
+     * await room.markThreadAsResolved("th_xxx");
+     */
+    markThreadAsResolved(threadId: string): Promise<void>;
+    /**
+     * Marks a thread as unresolved.
+     *
+     * @example
+     * await room.markThreadAsUnresolved("th_xxx");
+     */
+    markThreadAsUnresolved(threadId: string): Promise<void>;
+    /**
+     * Creates a comment.
+     *
+     * @example
+     * await room.createComment({
+     *   threadId: "th_xxx",
+     *   body: {
+     *     version: 1,
+     *     content: [{ type: "paragraph", children: [{ text: "Hello" }] }],
+     *   },
+     * });
+     */
     createComment(options: {
         threadId: string;
-        commentId: string;
+        commentId?: string;
         body: CommentBody;
     }): Promise<CommentData>;
+    /**
+     * Edits a comment.
+     *
+     * @example
+     * await room.editComment({
+     *   threadId: "th_xxx",
+     *   commentId: "cm_xxx"
+     *   body: {
+     *     version: 1,
+     *     content: [{ type: "paragraph", children: [{ text: "Hello" }] }],
+     *   },
+     * });
+     */
     editComment(options: {
         threadId: string;
         commentId: string;
         body: CommentBody;
     }): Promise<CommentData>;
+    /**
+     * Deletes a comment.
+     * If it is the last non-deleted comment, the thread also gets deleted.
+     *
+     * @example
+     * await room.deleteComment({
+     *   threadId: "th_xxx",
+     *   commentId: "cm_xxx"
+     * });
+     */
     deleteComment(options: {
         threadId: string;
         commentId: string;
     }): Promise<void>;
+    /**
+     * Adds a reaction from a comment for the current user.
+     *
+     * @example
+     * await room.addReaction({ threadId: "th_xxx", commentId: "cm_xxx", emoji: "👍" })
+     */
     addReaction(options: {
         threadId: string;
         commentId: string;
         emoji: string;
     }): Promise<CommentUserReaction>;
+    /**
+     * Removes a reaction from a comment.
+     *
+     * @example
+     * await room.removeReaction({ threadId: "th_xxx", commentId: "cm_xxx", emoji: "👍" })
+     */
     removeReaction(options: {
         threadId: string;
         commentId: string;
@@ -1797,7 +1906,7 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
      * of Liveblocks, NEVER USE ANY OF THESE DIRECTLY, because bad things
      * will probably happen if you do.
      */
-    readonly [kInternal]: PrivateRoomApi<M>;
+    readonly [kInternal]: PrivateRoomApi;
     /**
      * The id of the room.
      */
@@ -1991,7 +2100,25 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
      * connection. If the room is not connected yet, initiate it.
      */
     reconnect(): void;
-};
+    /**
+     * Gets the user's notification settings for the current room.
+     *
+     * @example
+     * const settings = await room.getNotificationSettings();
+     */
+    getNotificationSettings(): Promise<RoomNotificationSettings>;
+    /**
+     * Updates the user's notification settings for the current room.
+     *
+     * @example
+     * await room.updateNotificationSettings({ threads: "replies_and_mentions" });
+     */
+    updateNotificationSettings(settings: Partial<RoomNotificationSettings>): Promise<RoomNotificationSettings>;
+    /**
+     * Internal use only. Signature might change in the future.
+     */
+    markInboxNotificationAsRead(notificationId: string): Promise<void>;
+} & CommentsApi<M>;
 /**
  * @private
  *
@@ -2000,7 +2127,7 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
  * Liveblocks, NEVER USE ANY OF THESE METHODS DIRECTLY, because bad things
  * will probably happen if you do.
  */
-declare type PrivateRoomApi<M extends BaseMetadata> = {
+declare type PrivateRoomApi = {
     presenceBuffer: Json | undefined;
     undoStack: readonly (readonly Readonly<HistoryOp<JsonObject>>[])[];
     nodeCount: number;
@@ -2013,12 +2140,6 @@ declare type PrivateRoomApi<M extends BaseMetadata> = {
         explicitClose(event: IWebSocketCloseEvent): void;
         rawSend(data: string): void;
     };
-    comments: CommentsApi<M>;
-    notifications: {
-        getRoomNotificationSettings(): Promise<RoomNotificationSettings>;
-        updateRoomNotificationSettings(settings: Partial<RoomNotificationSettings>): Promise<RoomNotificationSettings>;
-        markInboxNotificationAsRead(notificationId: string): Promise<void>;
-    };
 };
 declare type HistoryOp<P extends JsonObject> = Op | {
     readonly type: "presence";
@@ -2093,11 +2214,6 @@ declare type Store<T> = {
  */
 declare type NoInfr<A> = [A][A extends any ? 0 : never];
 
-declare type GetInboxNotificationsOptions = {
-    limit?: number;
-    since?: Date;
-};
-
 declare type OptimisticUpdate<M extends BaseMetadata> = CreateThreadOptimisticUpdate<M> | DeleteThreadOptimisticUpdate | EditThreadMetadataOptimisticUpdate<M> | MarkThreadAsResolvedOptimisticUpdate | MarkThreadAsUnresolvedOptimisticUpdate | CreateCommentOptimisticUpdate | EditCommentOptimisticUpdate | DeleteCommentOptimisticUpdate | AddReactionOptimisticUpdate | RemoveReactionOptimisticUpdate | MarkInboxNotificationAsReadOptimisticUpdate | MarkAllInboxNotificationsAsReadOptimisticUpdate | DeleteInboxNotificationOptimisticUpdate | DeleteAllInboxNotificationsOptimisticUpdate | UpdateNotificationSettingsOptimisticUpdate;
 declare type CreateThreadOptimisticUpdate<M extends BaseMetadata> = {
     type: "create-thread";
@@ -2293,8 +2409,7 @@ declare type EnterOptions<P extends JsonObject = DP, S extends LsonObject = DS>
  * of Liveblocks, NEVER USE ANY OF THESE DIRECTLY, because bad things
  * will probably happen if you do.
  */
-declare type PrivateClientApi<U extends BaseUserMeta, M extends BaseMetadata> = {
-    readonly notifications: NotificationsApi<M>;
+declare type PrivateClientApi<U extends BaseUserMeta> = {
     readonly currentUserIdStore: Store<string | null>;
     readonly resolveMentionSuggestions: ClientOptions<U>["resolveMentionSuggestions"];
     readonly cacheStore: CacheStore<BaseMetadata>;
@@ -2303,19 +2418,77 @@ declare type PrivateClientApi<U extends BaseUserMeta, M extends BaseMetadata> =
     readonly getRoomIds: () => string[];
 };
 declare type NotificationsApi<M extends BaseMetadata> = {
-    getInboxNotifications(options?: GetInboxNotificationsOptions): Promise<{
+    /**
+     * Gets the current user inbox notifications and their associated threads.
+     * It also returns the request date that can be used for subsequent polling.
+     *
+     * @example
+     * const {
+     *   inboxNotifications,
+     *   threads,
+     *   requestedAt
+     * } = await client.getInboxNotifications();
+     */
+    getInboxNotifications(): Promise<{
         inboxNotifications: InboxNotificationData[];
         threads: ThreadData<M>[];
-        deletedThreads: ThreadDeleteInfo[];
-        deletedInboxNotifications: InboxNotificationDeleteInfo[];
-        meta: {
-            requestedAt: Date;
+        requestedAt: Date;
+    }>;
+    /**
+     * Gets the updated and deleted inbox notifications and their associated threads since the requested date.
+     *
+     * @example
+     * const result = await client.getInboxNotifications();
+     * // ... //
+     * await client.getInboxNotificationsSince({ since: result.requestedAt }});
+     */
+    getInboxNotificationsSince(options: {
+        since: Date;
+    }): Promise<{
+        inboxNotifications: {
+            updated: InboxNotificationData[];
+            deleted: InboxNotificationDeleteInfo[];
+        };
+        threads: {
+            updated: ThreadData<M>[];
+            deleted: ThreadDeleteInfo[];
         };
+        requestedAt: Date;
     }>;
+    /**
+     * Gets the number of unread inbox notifications for the current user.
+     *
+     * @example
+     * const count = await client.getUnreadInboxNotificationsCount();
+     */
     getUnreadInboxNotificationsCount(): Promise<number>;
+    /**
+     * Marks all inbox notifications as read.
+     *
+     * @example
+     * await client.markAllInboxNotificationsAsRead();
+     */
     markAllInboxNotificationsAsRead(): Promise<void>;
+    /**
+     * Marks an inbox notification as read.
+     *
+     * @example
+     * await client.markInboxNotificationAsRead("in_xxx");
+     */
     markInboxNotificationAsRead(inboxNotificationId: string): Promise<void>;
+    /**
+     * Deletes all inbox notifications for the current user.
+     *
+     * @example
+     * await client.deleteAllInboxNotifications();
+     */
     deleteAllInboxNotifications(): Promise<void>;
+    /**
+     * Deletes an inbox notification for the current user.
+     *
+     * @example
+     * await client.deleteInboxNotification("in_xxx");
+     */
     deleteInboxNotification(inboxNotificationId: string): Promise<void>;
 };
 /**
@@ -2325,7 +2498,7 @@ declare type NotificationsApi<M extends BaseMetadata> = {
  * narrower.
  */
 declare type OpaqueClient = Client<BaseUserMeta>;
-declare type Client<U extends BaseUserMeta = DU> = {
+declare type Client<U extends BaseUserMeta = DU, M extends BaseMetadata = DM> = {
     /**
      * Gets a room. Returns null if {@link Client.enter} has not been called previously.
      *
@@ -2358,8 +2531,8 @@ declare type Client<U extends BaseUserMeta = DU> = {
      * of Liveblocks, NEVER USE ANY OF THESE DIRECTLY, because bad things
      * will probably happen if you do.
      */
-    readonly [kInternal]: PrivateClientApi<U, BaseMetadata>;
-};
+    readonly [kInternal]: PrivateClientApi<U>;
+} & NotificationsApi<M>;
 declare type AuthEndpoint = string | ((room?: string) => Promise<CustomAuthenticationResult>);
 /**
  * The authentication endpoint that is called to ensure that the current user has access to a room.
@@ -2598,6 +2771,10 @@ declare function assert(condition: boolean, errmsg: string): asserts condition;
  */
 declare function nn<T>(value: T, errmsg?: string): NonNullable<T>;
 
+declare function createThreadId(): string;
+declare function createCommentId(): string;
+declare function createInboxNotificationId(): string;
+
 /**
  * Displays a deprecation warning in the dev console. Only in dev mode, and
  * only once per message/key. In production, this is a no-op.
@@ -2643,6 +2820,8 @@ declare namespace fancyConsole {
  */
 declare const freeze: typeof Object.freeze;
 
+declare const nanoid: (t?: number) => string;
+
 /**
  * Converts an object to a query string
  * Example:
@@ -2934,4 +3113,4 @@ declare type EnsureJson<T> = T extends Json ? T : T extends Array<infer I> ? (En
     [K in keyof T as EnsureJson<T[K]> extends never ? never : K]: EnsureJson<T[K]>;
 };
 
-export { type AckOp, type ActivityData, type AsyncResult, type AsyncResultWithDataField, type BaseActivitiesData, type BaseAuthResult, type BaseMetadata, type BaseRoomInfo, type BaseUserMeta, type Brand, type BroadcastEventClientMsg, type BroadcastOptions, type BroadcastedEventServerMsg, type CacheState, type CacheStore, type Client, type ClientMsg, ClientMsgCode, type ClientOptions, type CommentBody, type CommentBodyBlockElement, type CommentBodyElement, type CommentBodyInlineElement, type CommentBodyLink, type CommentBodyLinkElementArgs, type CommentBodyMention, type CommentBodyMentionElementArgs, type CommentBodyParagraph, type CommentBodyParagraphElementArgs, type CommentBodyText, type CommentBodyTextElementArgs, type CommentData, type CommentDataPlain, type CommentReaction, type CommentUserReaction, type CommentUserReactionPlain, CommentsApiError, type CommentsEventServerMsg, CrdtType, type CreateListOp, type CreateMapOp, type CreateObjectOp, type CreateOp, type CreateRegisterOp, type CustomAuthenticationResult, type DAD, type DE, type DM, type DP, type DRI, type DS, type DU, type Delegates, type DeleteCrdtOp, type DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, type EnsureJson, type EnterOptions, type EventSource, type FetchStorageClientMsg, type FetchYDocClientMsg, type GetThreadsOptions, type History, type IUserInfo, type IWebSocket, type IWebSocketCloseEvent, type IWebSocketEvent, type IWebSocketInstance, type IWebSocketMessageEvent, type IdTuple, type Immutable, type InboxNotificationCustomData, type InboxNotificationCustomDataPlain, type InboxNotificationData, type InboxNotificationDataPlain, type InboxNotificationDeleteInfo, type InboxNotificationTextMentionData, type InboxNotificationTextMentionDataPlain, type InboxNotificationThreadData, type InboxNotificationThreadDataPlain, type InitialDocumentStateServerMsg, type Json, type JsonArray, type JsonObject, type JsonScalar, type KDAD, LiveList, type LiveListUpdate, LiveMap, type LiveMapUpdate, type LiveNode, LiveObject, type LiveObjectUpdate, type LiveStructure, LiveblocksError, type LostConnectionEvent, type Lson, type LsonObject, type NoInfr, type NodeMap, NotificationsApiError, type Op, OpCode, type OpaqueClient, type OpaqueRoom, type OptionalPromise, type OptionalTupleUnless, type OthersEvent, type ParentToChildNodeMap, type PartialUnless, type Patchable, type PlainLson, type PlainLsonFields, type PlainLsonList, type PlainLsonMap, type PlainLsonObject, type PrivateClientApi, type PrivateRoomApi, type QueryMetadata, type RejectedStorageOpServerMsg, type Resolve, type ResolveMentionSuggestionsArgs, type ResolveRoomsInfoArgs, type ResolveUsersArgs, type Room, type RoomEventMessage, type RoomNotificationSettings, type RoomStateServerMsg, type SerializedChild, type SerializedCrdt, type SerializedList, type SerializedMap, type SerializedObject, type SerializedRegister, type SerializedRootObject, type ServerMsg, ServerMsgCode, type SetParentKeyOp, type Status, type StorageStatus, type StorageUpdate, type Store, type StringifyCommentBodyElements, type StringifyCommentBodyOptions, type ThreadData, type ThreadDataPlain, type ThreadDeleteInfo, type ToImmutable, type ToJson, type UnsubscribeCallback, type UpdateObjectOp, type UpdatePresenceClientMsg, type UpdatePresenceServerMsg, type UpdateStorageClientMsg, type UpdateStorageServerMsg, type UpdateYDocClientMsg, type User, type UserJoinServerMsg, type UserLeftServerMsg, WebsocketCloseCodes, type YDocUpdateServerMsg, ackOp, addReaction, applyOptimisticUpdates, asPos, assert, assertNever, b64decode, cloneLson, fancyConsole as console, convertToCommentData, convertToCommentUserReaction, convertToInboxNotificationData, convertToThreadData, createClient, deleteComment, deprecate, deprecateIf, detectDupes, errorIf, freeze, getMentionedIdsFromCommentBody, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isLiveNode, isPlainObject, isRootCrdt, kInternal, legacy_patchImmutableObject, lsonToJson, makeEventSource, makePoller, makePosition, memoizeOnSuccess, nn, objectToQuery, patchLiveObjectKey, raise, removeReaction, shallow, stringify, stringifyCommentBody, throwUsageError, toPlainLson, tryParseJson, upsertComment, wait, withTimeout };
+export { type AckOp, type ActivityData, type AsyncResult, type AsyncResultWithDataField, type BaseActivitiesData, type BaseAuthResult, type BaseMetadata, type BaseRoomInfo, type BaseUserMeta, type Brand, type BroadcastEventClientMsg, type BroadcastOptions, type BroadcastedEventServerMsg, type CacheState, type CacheStore, type Client, type ClientMsg, ClientMsgCode, type ClientOptions, type CommentBody, type CommentBodyBlockElement, type CommentBodyElement, type CommentBodyInlineElement, type CommentBodyLink, type CommentBodyLinkElementArgs, type CommentBodyMention, type CommentBodyMentionElementArgs, type CommentBodyParagraph, type CommentBodyParagraphElementArgs, type CommentBodyText, type CommentBodyTextElementArgs, type CommentData, type CommentDataPlain, type CommentReaction, type CommentUserReaction, type CommentUserReactionPlain, CommentsApiError, type CommentsEventServerMsg, CrdtType, type CreateListOp, type CreateMapOp, type CreateObjectOp, type CreateOp, type CreateRegisterOp, type CustomAuthenticationResult, type DAD, type DE, type DM, type DP, type DRI, type DS, type DU, type Delegates, type DeleteCrdtOp, type DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, type EnsureJson, type EnterOptions, type EventSource, type FetchStorageClientMsg, type FetchYDocClientMsg, type GetThreadsOptions, type History, type IUserInfo, type IWebSocket, type IWebSocketCloseEvent, type IWebSocketEvent, type IWebSocketInstance, type IWebSocketMessageEvent, type IdTuple, type Immutable, type InboxNotificationCustomData, type InboxNotificationCustomDataPlain, type InboxNotificationData, type InboxNotificationDataPlain, type InboxNotificationDeleteInfo, type InboxNotificationTextMentionData, type InboxNotificationTextMentionDataPlain, type InboxNotificationThreadData, type InboxNotificationThreadDataPlain, type InitialDocumentStateServerMsg, type Json, type JsonArray, type JsonObject, type JsonScalar, type KDAD, LiveList, type LiveListUpdate, LiveMap, type LiveMapUpdate, type LiveNode, LiveObject, type LiveObjectUpdate, type LiveStructure, LiveblocksError, type LostConnectionEvent, type Lson, type LsonObject, type NoInfr, type NodeMap, NotificationsApiError, type Op, OpCode, type OpaqueClient, type OpaqueRoom, type OptionalPromise, type OptionalTupleUnless, type OthersEvent, type ParentToChildNodeMap, type PartialUnless, type Patchable, type PlainLson, type PlainLsonFields, type PlainLsonList, type PlainLsonMap, type PlainLsonObject, type PrivateClientApi, type PrivateRoomApi, type QueryMetadata, type RejectedStorageOpServerMsg, type Resolve, type ResolveMentionSuggestionsArgs, type ResolveRoomsInfoArgs, type ResolveUsersArgs, type Room, type RoomEventMessage, type RoomNotificationSettings, type RoomStateServerMsg, type SerializedChild, type SerializedCrdt, type SerializedList, type SerializedMap, type SerializedObject, type SerializedRegister, type SerializedRootObject, type ServerMsg, ServerMsgCode, type SetParentKeyOp, type Status, type StorageStatus, type StorageUpdate, type Store, type StringifyCommentBodyElements, type StringifyCommentBodyOptions, type ThreadData, type ThreadDataPlain, type ThreadDeleteInfo, type ToImmutable, type ToJson, type UnsubscribeCallback, type UpdateObjectOp, type UpdatePresenceClientMsg, type UpdatePresenceServerMsg, type UpdateStorageClientMsg, type UpdateStorageServerMsg, type UpdateYDocClientMsg, type User, type UserJoinServerMsg, type UserLeftServerMsg, WebsocketCloseCodes, type YDocUpdateServerMsg, ackOp, addReaction, applyOptimisticUpdates, asPos, assert, assertNever, b64decode, cloneLson, fancyConsole as console, convertToCommentData, convertToCommentUserReaction, convertToInboxNotificationData, convertToThreadData, createClient, createCommentId, createInboxNotificationId, createThreadId, deleteComment, deprecate, deprecateIf, detectDupes, errorIf, freeze, getMentionedIdsFromCommentBody, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isLiveNode, isPlainObject, isRootCrdt, kInternal, legacy_patchImmutableObject, lsonToJson, makeEventSource, makePoller, makePosition, memoizeOnSuccess, nanoid, nn, objectToQuery, patchLiveObjectKey, raise, removeReaction, shallow, stringify, stringifyCommentBody, throwUsageError, toPlainLson, tryParseJson, upsertComment, wait, withTimeout };