@liveblocks/node 1.19.0-test1 → 2.0.0-alpha2

package/dist/index.d.mts

@@ -1,95 +1,7 @@
-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 { BaseUserMeta, PlainLsonObject, JsonObject, QueryMetadata, ThreadData, CommentData, CommentBody, Patchable, CommentUserReaction, InboxNotificationData, RoomNotificationSettings, ActivityData, LsonObject, ToImmutable, DU, BaseMetadata, DE, DM, DS } from '@liveblocks/core';
+export { CommentBody, CommentBodyBlockElement, CommentBodyElement, CommentBodyInlineElement, CommentBodyLink, CommentBodyLinkElementArgs, CommentBodyMention, CommentBodyMentionElementArgs, CommentBodyParagraph, CommentBodyParagraphElementArgs, CommentBodyText, CommentBodyTextElementArgs, CommentData, CommentUserReaction, IUserInfo, Json, JsonArray, JsonObject, JsonScalar, Lson, LsonObject, PlainLsonObject, ResolveUsersArgs, StringifyCommentBodyElements, StringifyCommentBodyOptions, ThreadData, User, getMentionedIdsFromCommentBody, stringifyCommentBody } from '@liveblocks/core';
 import { IncomingHttpHeaders } from 'http';
 
-/**
- * TODO Officially mark as DEPRECATED, point to migration guide.
- */
-declare type AuthorizeOptions = {
-    /**
-     * The secret API key for your Liveblocks account. You can find it on
-     * https://liveblocks.io/dashboard/apikeys
-     */
-    secret: string;
-    /**
-     * The room ID for which to authorize the user. This will authorize the user
-     * to enter the Liveblocks room.
-     */
-    room: string;
-    /**
-     * Associates a user ID to the session that is being authorized. The user ID
-     * is typically set to the user ID from your own database.
-     *
-     * It can also be used to generate a token that gives access to a private
-     * room where the userId is configured in the room accesses.
-     *
-     * This user ID will be used as the unique identifier to compute your
-     * Liveblocks account's Monthly Active Users.
-     */
-    userId: string;
-    /**
-     * Arbitrary metadata associated to this user session.
-     *
-     * You can use it to store a small amount of static metadata for a user
-     * session. It is public information, that will be visible to other users in
-     * the same room, like name, avatar URL, etc.
-     *
-     * It's only suitable for static info that won't change during a session. If
-     * you want to store dynamic metadata on a user session, don't keep that in
-     * the session token, but use Presence instead.
-     *
-     * Can't exceed 1KB when serialized as JSON.
-     */
-    userInfo?: unknown;
-    /**
-     * Tell Liveblocks which group IDs this user belongs to. This will authorize
-     * the user session to access private rooms that have at least one of these
-     * group IDs listed in their room access configuration.
-     *
-     * See https://liveblocks.io/docs/guides/managing-rooms-users-permissions#permissions
-     * for how to configure your room's permissions to use this feature.
-     */
-    groupIds?: string[];
-};
-/**
- * TODO Officially mark as DEPRECATED, point to migration guide.
- */
-declare type AuthorizeResponse = {
-    status: number;
-    body: string;
-    error?: Error;
-};
-/**
- * @deprecated Since 1.2, we’re deprecating single-room tokens in favor of
- * either access tokens or ID tokens. Single-room tokens are still supported,
- * but support for them will be dropped in the future. Please refer to our
- * Upgrade Guide to learn how to adopt the new-style authorization, see
- * https://liveblocks.io/docs/platform/upgrading/1.2
- *
- * Tells Liveblocks that a user should be allowed access to a room, which user
- * this session is for, and what metadata to associate with the user (like
- * name, avatar, etc.)
- *
- * @example
- * export default async function auth(req, res) {
- *
- * // Implement your own security here.
- *
- * const room = req.body.room;
- * const response = await authorize({
- *   room,
- *   secret,
- *   userId: "123",
- *   userInfo: {    // Optional
- *     name: "Ada Lovelace"
- *   },
- *   groupIds: ["group1"] // Optional
- * });
- * return res.status(response.status).end(response.body);
- * }
- */
-declare function authorize(options: AuthorizeOptions): Promise<AuthorizeResponse>;
-
 declare const ALL_PERMISSIONS: readonly ["room:write", "room:read", "room:presence:write", "comments:write", "comments:read"];
 declare type Permission = (typeof ALL_PERMISSIONS)[number];
 /**
@@ -145,6 +57,7 @@ declare class Session {
  * @liveblocks/core has browser-specific code.
  */
 
+declare type ToSimplifiedJson<S extends LsonObject> = LsonObject extends S ? JsonObject : ToImmutable<S>;
 declare type LiveblocksOptions = {
     /**
      * The Liveblocks secret key. Must start with "sk_".
@@ -152,11 +65,11 @@ declare type LiveblocksOptions = {
      */
     secret: string;
 };
-declare type Nullable<T> = {
-    [P in keyof T]: T[P] | null;
+declare type CreateSessionOptions<U extends BaseUserMeta = DU> = {
+    userInfo: U["info"];
 };
-declare type CreateSessionOptions = {
-    userInfo: IUserInfo;
+declare type IdentifyUserOptions<U extends BaseUserMeta = DU> = {
+    userInfo: U["info"];
 };
 declare type AuthResponse = {
     status: number;
@@ -170,26 +83,41 @@ declare type Identity = {
 declare type ThreadParticipants = {
     participantIds: string[];
 };
+declare type CreateThreadOptions<M extends BaseMetadata> = {
+    roomId: string;
+    data: {
+        comment: {
+            userId: string;
+            createdAt?: Date;
+            body: CommentBody;
+        };
+    } & (Record<string, never> extends M ? {
+        metadata?: M;
+    } : {
+        metadata: M;
+    });
+};
 declare type RoomPermission = [] | ["room:write"] | ["room:read", "room:presence:write"];
 declare type RoomAccesses = Record<string, [
     "room:write"
 ] | ["room:read", "room:presence:write"]>;
 declare type RoomMetadata = Record<string, string | string[]>;
-declare type RoomInfo = {
+declare type QueryRoomMetadata = Record<string, string>;
+declare type RoomData = {
     type: "room";
     id: string;
-    metadata: RoomMetadata;
-    groupsAccesses: RoomAccesses;
-    usersAccesses: RoomAccesses;
-    defaultAccesses: RoomPermission;
+    createdAt: Date;
     lastConnectionAt?: Date;
-    createdAt?: Date;
+    defaultAccesses: RoomPermission;
+    usersAccesses: RoomAccesses;
+    groupsAccesses: RoomAccesses;
+    metadata: RoomMetadata;
 };
-declare type RoomUser<Info> = {
+declare type RoomUser<U extends BaseUserMeta> = {
     type: "user";
     id: string | null;
     connectionId: number;
-    info: Info;
+    info: U["info"];
 };
 declare type Schema = {
     id: string;
@@ -199,6 +127,10 @@ declare type Schema = {
     createdAt: Date;
     updatedAt: Date;
 };
+declare type E = DE;
+declare type M = DM;
+declare type S = DS;
+declare type U = DU;
 /**
  * Interact with the Liveblocks API from your Node.js backend.
  */
@@ -223,7 +155,7 @@ declare class Liveblocks {
      * `other.info` property.
      *
      */
-    prepareSession(userId: string, options?: CreateSessionOptions): Session;
+    prepareSession(userId: string, options?: CreateSessionOptions<U>): Session;
     /**
      * Call this to authenticate the user as an actor you want to allow to use
      * Liveblocks.
@@ -256,9 +188,7 @@ declare class Liveblocks {
      * add here will be visible to all other clients in the room, through the
      * `other.info` property.
      */
-    identifyUser(identity: string | Identity, options?: {
-        userInfo: IUserInfo;
-    }): Promise<AuthResponse>;
+    identifyUser(identity: string | Identity, options?: IdentifyUserOptions<U>): Promise<AuthResponse>;
     /**
      * Returns a list of your rooms. The rooms are returned sorted by creation date, from newest to oldest. You can filter rooms by metadata, users accesses and groups accesses.
      * @param params.limit (optional) A limit on the number of rooms to be returned. The limit can range between 1 and 100, and defaults to 20.
@@ -266,17 +196,51 @@ declare class Liveblocks {
      * @param params.userId (optional) A filter on users accesses.
      * @param params.metadata (optional) A filter on metadata. Multiple metadata keys can be used to filter rooms.
      * @param params.groupIds (optional) A filter on groups accesses. Multiple groups can be used.
+     * @param params.query (optional) A query to filter rooms by. It is based on our query language. You can filter by metadata and room ID.
      * @returns A list of rooms.
      */
     getRooms(params?: {
         limit?: number;
         startingAfter?: string;
-        metadata?: RoomMetadata;
+        /**
+         * @deprecated Use `query` property instead. Support for the `metadata`
+         * field will be removed in a future version.
+         */
+        metadata?: QueryRoomMetadata;
         userId?: string;
         groupIds?: string[];
+        /**
+         * The query to filter rooms by. It is based on our query language.
+         * @example
+         * ```
+         * {
+         *   query: 'metadata["status"]:"open" AND roomId^"liveblocks:"'
+         * }
+         * ```
+         * @example
+         * ```
+         * {
+         *   query: {
+         *     metadata: {
+         *       status: "open",
+         *     },
+         *     roomId: {
+         *       startsWith: "liveblocks:"
+         *     }
+         *   }
+         * }
+         * ```
+         */
+        query?: string | {
+            metadata?: QueryRoomMetadata;
+            roomId?: {
+                startsWith: string;
+            };
+        };
     }): Promise<{
         nextPage: string | null;
-        data: RoomInfo[];
+        nextCursor: string | null;
+        data: RoomData[];
     }>;
     /**
      * Creates a new room with the given id.
@@ -292,13 +256,13 @@ declare class Liveblocks {
         groupsAccesses?: RoomAccesses;
         usersAccesses?: RoomAccesses;
         metadata?: RoomMetadata;
-    }): Promise<RoomInfo>;
+    }): Promise<RoomData>;
     /**
      * Returns a room with the given id.
      * @param roomId The id of the room to return.
      * @returns The room with the given id.
      */
-    getRoom(roomId: string): Promise<RoomInfo>;
+    getRoom(roomId: string): Promise<RoomData>;
     /**
      * Updates specific properties of a room. It’s not necessary to provide the entire room’s information.
      * Setting a property to `null` means to delete this property.
@@ -318,7 +282,7 @@ declare class Liveblocks {
             "room:write"
         ] | ["room:read", "room:presence:write"] | null>;
         metadata?: Record<string, string | string[] | null>;
-    }): Promise<RoomInfo>;
+    }): Promise<RoomData>;
     /**
      * Deletes a room with the given id. A deleted room is no longer accessible from the API or the dashboard and it cannot be restored.
      * @param roomId The id of the room to delete.
@@ -329,15 +293,15 @@ 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<{
-        data: RoomUser<T>[];
+    getActiveUsers(roomId: string): Promise<{
+        data: RoomUser<U>[];
     }>;
     /**
      * 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.
      * @param message The message to broadcast. It can be any JSON serializable value.
      */
-    broadcastEvent(roomId: string, message: Json): Promise<void>;
+    broadcastEvent(roomId: string, message: E): Promise<void>;
     /**
      * Returns the contents of the room’s Storage tree.
      * The default outputted format is called “plain LSON”, which includes information on the Live data structures in the tree.
@@ -358,7 +322,7 @@ declare class Liveblocks {
      */
     getStorageDocument(roomId: string, format: "plain-lson"): Promise<PlainLsonObject>;
     getStorageDocument(roomId: string): Promise<PlainLsonObject>;
-    getStorageDocument(roomId: string, format: "json"): Promise<JsonObject>;
+    getStorageDocument(roomId: string, format: "json"): Promise<ToSimplifiedJson<S>>;
     /**
      * Initializes a room’s Storage. The room must already exist and have an empty Storage.
      * Calling this endpoint will disconnect all users from the room if there are any.
@@ -389,18 +353,22 @@ declare class Liveblocks {
     /**
      * Send a Yjs binary update to the room’s Yjs document. You can use this endpoint to initialize Yjs data for the room or to update the room’s Yjs document.
      * @param roomId The id of the room to send the Yjs binary update to.
-     * @param params The Yjs binary update to send. Read the [Yjs documentation](https://docs.yjs.dev/api/document-updates) to learn how to create a binary update.
+     * @param update The Yjs update to send. Typically the result of calling `Yjs.encodeStateAsUpdate(doc)`. Read the [Yjs documentation](https://docs.yjs.dev/api/document-updates) to learn how to create a binary update.
+     * @param params.guid (optional) If provided, the binary update will be applied to the Yjs subdocument with the given guid. If not provided, the binary update will be applied to the root Yjs document.
      */
-    sendYjsBinaryUpdate(roomId: string, params: {
-        update: string;
+    sendYjsBinaryUpdate(roomId: string, update: Uint8Array, params?: {
+        guid?: string;
     }): Promise<void>;
     /**
      * Returns the room’s Yjs document encoded as a single binary update. This can be used by Y.applyUpdate(responseBody) to get a copy of the document in your backend.
      * See [Yjs documentation](https://docs.yjs.dev/api/document-updates) for more information on working with updates.
      * @param roomId The id of the room to get the Yjs document from.
+     * @param params.guid (optional) If provided, returns the binary update of the Yjs subdocument with the given guid. If not provided, returns the binary update of the root Yjs document.
      * @returns The room’s Yjs document encoded as a single binary update.
      */
-    getYjsDocumentAsBinaryUpdate(roomId: string): Promise<ArrayBuffer>;
+    getYjsDocumentAsBinaryUpdate(roomId: string, params?: {
+        guid?: string;
+    }): Promise<ArrayBuffer>;
     /**
      * Creates a new schema which can be referenced later to enforce a room’s Storage data structure.
      * @param name The name used to reference the schema. Must be a non-empty string with less than 65 characters and only contain lowercase letters, numbers and dashes
@@ -451,12 +419,41 @@ declare class Liveblocks {
      * Gets all the threads in a room.
      *
      * @param params.roomId The room ID to get the threads from.
+     * @param params.query The query to filter threads by. It is based on our query language and can filter by metadata.
      * @returns A list of threads.
      */
     getThreads(params: {
         roomId: string;
+        /**
+         * The query to filter threads by. It is based on our query language.
+         *
+         * @example
+         * ```
+         * {
+         *   query: "metadata['organization']^'liveblocks:' AND metadata['status']:'open' AND metadata['resolved']:false AND metadata['priority']:3"
+         * }
+         * ```
+         * @example
+         * ```
+         * {
+         *   query: {
+         *     metadata: {
+         *       status: "open",
+         *       resolved: false,
+         *       priority: 3,
+         *       organization: {
+         *         startsWith: "liveblocks:"
+         *       }
+         *     }
+         *   }
+         * }
+         * ```
+         */
+        query?: string | {
+            metadata?: Partial<QueryMetadata<M>>;
+        };
     }): Promise<{
-        data: ThreadData[];
+        data: ThreadData<M>[];
     }>;
     /**
      * Gets a thread.
@@ -465,10 +462,10 @@ declare class Liveblocks {
      * @param params.threadId The thread ID.
      * @returns A thread.
      */
-    getThread<TThreadMetadata extends BaseMetadata = never>(params: {
+    getThread(params: {
         roomId: string;
         threadId: string;
-    }): Promise<ThreadData<TThreadMetadata>>;
+    }): Promise<ThreadData<M>>;
     /**
      * Gets a thread's participants.
      *
@@ -554,17 +551,7 @@ declare class Liveblocks {
      * @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.
      */
-    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>>;
+    createThread(params: CreateThreadOptions<M>): Promise<ThreadData<M>>;
     /**
      * Updates the metadata of the specified thread in a room.
      * @param params.roomId The room ID to update the thread in.
@@ -574,15 +561,15 @@ declare class Liveblocks {
      * @param params.data.updatedAt (optional) The date the thread is set to be updated.
      * @returns The updated thread.
      */
-    editThreadMetadata<TThreadMetadata extends BaseMetadata = never>(params: {
+    editThreadMetadata(params: {
         roomId: string;
         threadId: string;
         data: {
-            metadata: Nullable<BaseMetadata>;
+            metadata: Patchable<M>;
             userId: string;
             updatedAt?: Date;
         };
-    }): Promise<TThreadMetadata>;
+    }): Promise<M>;
     /**
      * Adds a new comment reaction to a comment.
      * @param params.roomId The room ID to add the comment reaction in.
@@ -622,6 +609,64 @@ declare class Liveblocks {
             removedAt?: Date;
         };
     }): Promise<void>;
+    /**
+     * Returns the inbox notifications for a user.
+     * @param params.userId The user ID to get the inbox notifications from.
+     * @param params.inboxNotificationId The ID of the inbox notification to get.
+     */
+    getInboxNotification(params: {
+        userId: string;
+        inboxNotificationId: string;
+    }): Promise<InboxNotificationData>;
+    /**
+     * Gets the user's room notification settings.
+     * @param params.userId The user ID to get the room notifications from.
+     * @param params.roomId The room ID to get the room notification settings from.
+     */
+    getRoomNotificationSettings(params: {
+        userId: string;
+        roomId: string;
+    }): Promise<RoomNotificationSettings>;
+    /**
+     * Updates the user's room notification settings.
+     * @param params.userId The user ID to update the room notification settings for.
+     * @param params.roomId The room ID to update the room notification settings for.
+     * @param params.data The new room notification settings for the user.
+     */
+    updateRoomNotificationSettings(params: {
+        userId: string;
+        roomId: string;
+        data: RoomNotificationSettings;
+    }): Promise<RoomNotificationSettings>;
+    /**
+     * Delete the user's room notification settings.
+     * @param params.userId The user ID to delete the room notification settings from.
+     * @param params.roomId The room ID to delete the room notification settings from.
+     */
+    deleteRoomNotificationSettings(params: {
+        userId: string;
+        roomId: string;
+    }): Promise<void>;
+    /**
+     * Update a room ID.
+     * @param params.roomId The current ID of the room.
+     * @param params.newRoomId The new room ID.
+     */
+    updateRoomId(params: {
+        currentRoomId: string;
+        newRoomId: string;
+    }): Promise<RoomData>;
+    triggerInboxNotification(params: {
+        userId: string;
+        kind: `$${string}`;
+        roomId?: string;
+        subjectId: string;
+        activityData: ActivityData;
+    }): Promise<void>;
+}
+declare class LiveblocksError extends Error {
+    status: number;
+    constructor(status: number, message?: string);
 }
 
 declare class WebhookHandler {
@@ -680,7 +725,7 @@ declare type WebhookRequest = {
      */
     rawBody: string;
 };
-declare type WebhookEvent = StorageUpdatedEvent | UserEnteredEvent | UserLeftEvent | RoomCreatedEvent | RoomDeletedEvent | CommentCreatedEvent | CommentEditedEvent | CommentDeletedEvent | CommentReactionAdded | CommentReactionRemoved | ThreadMetadataUpdatedEvent | ThreadCreatedEvent | YDocUpdatedEvent;
+declare type WebhookEvent = StorageUpdatedEvent | UserEnteredEvent | UserLeftEvent | RoomCreatedEvent | RoomDeletedEvent | CommentCreatedEvent | CommentEditedEvent | CommentDeletedEvent | CommentReactionAdded | CommentReactionRemoved | ThreadMetadataUpdatedEvent | NotificationEvent | ThreadCreatedEvent | YDocUpdatedEvent;
 declare type StorageUpdatedEvent = {
     type: "storageUpdated";
     data: {
@@ -831,6 +876,11 @@ declare type YDocUpdatedEvent = {
     data: {
         projectId: string;
         roomId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        updatedAt: string;
     };
 };
 declare type ThreadMetadataUpdatedEvent = {
@@ -861,5 +911,65 @@ declare type ThreadCreatedEvent = {
         createdBy: string;
     };
 };
+declare type ThreadNotificationEvent = {
+    type: "notification";
+    data: {
+        channel: "email";
+        kind: "thread";
+        projectId: string;
+        roomId: string;
+        userId: string;
+        threadId: string;
+        inboxNotificationId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        createdAt: string;
+    };
+};
+declare type TextMentionNotificationEvent = {
+    type: "notification";
+    data: {
+        channel: "email";
+        kind: "textMention";
+        projectId: string;
+        roomId: string;
+        userId: string;
+        mentionId: string;
+        inboxNotificationId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        createdAt: string;
+    };
+};
+declare type CustomKind = `$${string}`;
+declare type CustomNotificationEvent = {
+    type: "notification";
+    data: {
+        channel: "email";
+        kind: CustomKind;
+        projectId: string;
+        roomId: string | null;
+        userId: string;
+        subjectId: string;
+        inboxNotificationId: string;
+        /**
+         * ISO 8601 datestring
+         * @example "2021-03-01T12:00:00.000Z"
+         */
+        createdAt: string;
+    };
+};
+declare type NotificationEvent = ThreadNotificationEvent | TextMentionNotificationEvent | CustomNotificationEvent;
+
+/**
+ * @deprecated RoomInfo was renamed to RoomData, to avoid
+ * confusion with the globally augmentable RoomInfo type. This
+ * alias will be removed in a future version.
+ */
+declare type RoomInfo = RoomData;
 
-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 };
+export { type CommentCreatedEvent, type CommentDeletedEvent, type CommentEditedEvent, type CommentReactionAdded, type CommentReactionRemoved, Liveblocks, LiveblocksError, type LiveblocksOptions, type NotificationEvent, type RoomAccesses, type RoomCreatedEvent, type RoomData, 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 };