@liveblocks/node 1.7.1-pre1 → 1.8.0

package/dist/index.d.mts

@@ -88,6 +88,105 @@ 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;
@@ -220,7 +319,7 @@ declare type LiveblocksOptions = {
     secret: string;
 };
 declare type CreateSessionOptions = {
-    userInfo: unknown;
+    userInfo: IUserInfo;
 };
 declare type AuthResponse = {
     status: number;
@@ -234,6 +333,35 @@ declare type Identity = {
 declare type ThreadParticipants = {
     participantIds: string[];
 };
+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 = {
+    type: "room";
+    id: string;
+    metadata: RoomMetadata;
+    groupsAccesses: RoomAccesses;
+    usersAccesses: RoomAccesses;
+    defaultAccesses: RoomPermission;
+    lastConnectionAt?: Date;
+    createdAt?: Date;
+};
+declare type RoomUser<Info> = {
+    type: "user";
+    id: string | null;
+    connectionId: number;
+    info: Info;
+};
+declare type Schema = {
+    id: string;
+    name: string;
+    version: number;
+    body: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
 /**
  * Interact with the Liveblocks API from your Node.js backend.
  */
@@ -292,8 +420,194 @@ declare class Liveblocks {
      * `other.info` property.
      */
     identifyUser(identity: string | Identity, options?: {
-        userInfo: unknown;
+        userInfo: IUserInfo;
     }): 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.
+     * @param params.startingAfter (optional) A cursor used for pagination. You get the value from the response of the previous page.
+     * @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.
+     * @returns A list of rooms.
+     */
+    getRooms(params?: {
+        limit?: number;
+        startingAfter?: string;
+        metadata?: RoomMetadata;
+        userId?: string;
+        groupIds?: string[];
+    }): Promise<{
+        nextPage: string | null;
+        data: RoomInfo[];
+    }>;
+    /**
+     * Creates a new room with the given id.
+     * @param roomId The id of the room to create.
+     * @param params.defaultAccesses The default accesses for the room.
+     * @param params.groupAccesses (optional) The group accesses for the room. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+     * @param params.userAccesses (optional) The user accesses for the room. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+     * @param params.metadata (optional) The metadata for the room. Supports upto a maximum of 50 entries. Key length has a limit of 40 characters. Value length has a limit of 256 characters.
+     * @returns The created room.
+     */
+    createRoom(roomId: string, params: {
+        defaultAccesses: RoomPermission;
+        groupsAccesses?: RoomAccesses;
+        usersAccesses?: RoomAccesses;
+        metadata?: RoomMetadata;
+    }): Promise<RoomInfo>;
+    /**
+     * 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>;
+    /**
+     * 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.
+     * @param roomId The id of the room to update.
+     * @param params.defaultAccesses (optional) The default accesses for the room.
+     * @param params.groupAccesses (optional) The group accesses for the room. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+     * @param params.userAccesses (optional) The user accesses for the room. Can contain a maximum of 100 entries. Key length has a limit of 40 characters.
+     * @param params.metadata (optional) The metadata for the room. Supports upto a maximum of 50 entries. Key length has a limit of 40 characters. Value length has a limit of 256 characters.
+     * @returns The updated room.
+     */
+    updateRoom(roomId: string, params: {
+        defaultAccesses?: RoomPermission | null;
+        groupsAccesses?: Record<string, [
+            "room:write"
+        ] | ["room:read", "room:presence:write"] | null>;
+        usersAccesses?: Record<string, [
+            "room:write"
+        ] | ["room:read", "room:presence:write"] | null>;
+        metadata?: Record<string, string | string[] | null>;
+    }): Promise<RoomInfo>;
+    /**
+     * 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.
+     */
+    deleteRoom(roomId: string): Promise<void>;
+    /**
+     * Returns a list of users currently present in the requested room. For better performance, we recommand to call this endpoint every 10 seconds maximum. Duplicates can happen if a user is in the requested room with multiple browser tabs opened.
+     * @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>[]>;
+    /**
+     * 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>;
+    /**
+     * 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.
+     * These nodes show up in the output as objects with two properties:
+     *
+     * ```json
+     * {
+     *   "liveblocksType": "LiveObject",
+     *   "data": ...
+     * }
+     * ```
+     *
+     * If you’re not interested in this information, you can use the `format` parameter to get a more compact output.
+     *
+     * @param roomId The id of the room to get the storage from.
+     * @param format (optional) Set to return `plan-lson` representation by default. If set to `json`, the output will be formatted as a simplified JSON representation of the Storage tree.
+     * In that format, each LiveObject and LiveMap will be formatted as a simple JSON object, and each LiveList will be formatted as a simple JSON array. This is a lossy format because information about the original data structures is not retained, but it may be easier to work with.
+     */
+    getStorageDocument(roomId: string, format: "plain-lson"): Promise<PlainLsonObject>;
+    getStorageDocument(roomId: string): Promise<PlainLsonObject>;
+    getStorageDocument(roomId: string, format: "json"): Promise<JsonObject>;
+    /**
+     * 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.
+     *
+     * @param roomId The id of the room to initialize the storage from.
+     * @param document The document to initialize the storage with.
+     * @returns The initialized storage document. It is of the same format as the one passed in.
+     */
+    initializeStorageDocument(roomId: string, document: PlainLsonObject): Promise<PlainLsonObject>;
+    /**
+     * Deletes all of the room’s Storage data and disconnect all users from the room if there are any. Note that this does not delete the Yjs document in the room if one exists.
+     * @param roomId The id of the room to delete the storage from.
+     */
+    deleteStorageDocument(roomId: string): Promise<void>;
+    /**
+     * Returns a JSON representation of the room’s Yjs document.
+     * @param roomId The id of the room to get the Yjs document from.
+     * @param params.format (optional) If true, YText will return formatting.
+     * @param params.key (optional) If provided, returns only a single key’s value, e.g. doc.get(key).toJSON().
+     * @param params.type (optional) Used with key to override the inferred type, i.e. "ymap" will return doc.get(key, Y.Map).
+     * @returns A JSON representation of the room’s Yjs document.
+     */
+    getYjsDocument(roomId: string, params?: {
+        format?: boolean;
+        key?: string;
+        type?: string;
+    }): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    sendYjsBinaryUpdate(roomId: string, params: {
+        update: 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.
+     * @returns The room’s Yjs document encoded as a single binary update.
+     */
+    getYjsDocumentAsBinaryUpdate(roomId: 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
+     * @param body The exact allowed shape of data in the room. It is a multi-line string written in the [Liveblocks schema syntax](https://liveblocks.io/docs/platform/schema-validation/syntax).
+     * @returns The created schema.
+     */
+    createSchema(name: string, body: string): Promise<Schema>;
+    /**
+     * Returns a schema by its id.
+     * @param schemaId Id of the schema - this is the combination of the schema name and version of the schema to update. For example, `my-schema@1`.
+     * @returns The schema with the given id.
+     */
+    getSchema(schemaId: string): Promise<Schema>;
+    /**
+     * Updates the body for the schema. A schema can only be updated if it is not used by any room.
+     * @param schemaId Id of the schema - this is the combination of the schema name and version of the schema to update. For example, `my-schema@1`.
+     * @param body The exact allowed shape of data in the room. It is a multi-line string written in the [Liveblocks schema syntax](https://liveblocks.io/docs/platform/schema-validation/syntax).
+     * @returns The updated schema. The version of the schema will be incremented.
+     */
+    updateSchema(schemaId: string, body: string): Promise<Schema>;
+    /**
+     * Deletes a schema by its id. A schema can only be deleted if it is not used by any room.
+     * @param schemaId Id of the schema - this is the combination of the schema name and version of the schema to update. For example, `my-schema@1`.
+     */
+    deleteSchema(schemaId: string): Promise<void>;
+    /**
+     * Returns the schema attached to a room.
+     * @param roomId The id of the room to get the schema from.
+     * @returns
+     */
+    getSchemaByRoomId(roomId: string): Promise<Schema>;
+    /**
+     * Attaches a schema to a room, and instantly enables runtime schema validation for the room.
+     * If the current contents of the room’s Storage do not match the schema, attaching will fail and the error message will give details on why the schema failed to attach.
+     * @param roomId The id of the room to attach the schema to.
+     * @param schemaId Id of the schema - this is the combination of the schema name and version of the schema to update. For example, `my-schema@1`.
+     * @returns The schema id as JSON.
+     */
+    attachSchemaToRoom(roomId: string, schemaId: string): Promise<{
+        schema: string;
+    }>;
+    /**
+     * Detaches a schema from a room, and disables runtime schema validation for the room.
+     * @param roomId The id of the room to detach the schema from.
+     */
+    detachSchemaFromRoom(roomId: string): Promise<void>;
     /**
      * Gets all the threads in a room.
      *
@@ -302,7 +616,9 @@ declare class Liveblocks {
      */
     getThreads(params: {
         roomId: string;
-    }): Promise<ThreadData[]>;
+    }): Promise<{
+        data: ThreadData[];
+    }>;
     /**
      * Gets a thread.
      *
@@ -343,6 +659,96 @@ declare class Liveblocks {
     }): 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";
+    /**
+     * The elements used to customize the resulting string. Each element has
+     * priority over the defaults inherited from the `format` option.
+     */
+    elements?: Partial<StringifyCommentBodyElements<TUserMeta>>;
+    /**
+     * The separator used between paragraphs.
+     */
+    separator?: string;
+    /**
+     * A function that returns user info from user IDs.
+     */
+    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>;
+
 declare class WebhookHandler {
     private secretBuffer;
     private static secretPrefix;
@@ -581,4 +987,4 @@ declare type ThreadCreatedEvent = {
     };
 };
 
-export { CommentCreatedEvent, CommentDeletedEvent, CommentEditedEvent, CommentReactionAdded, CommentReactionRemoved, Liveblocks, LiveblocksOptions, RoomCreatedEvent, RoomDeletedEvent, StorageUpdatedEvent, ThreadCreatedEvent, ThreadMetadataUpdatedEvent, UserEnteredEvent, UserLeftEvent, WebhookEvent, WebhookHandler, WebhookRequest, authorize };
+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 };