API Reference - @liveblocks/node

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
export async function POST(request: Request) {  /**   * Implement your own security here.   *   * It's your responsibility to ensure that the caller of this endpoint   * is a valid user by validating the cookies or authentication headers   * and that it has access to the requested room.   */
  // Get the current user from your database  const user = __getUserFromDB__(request);
  // Start an auth session inside your endpoint  const session = liveblocks.prepareSession(    user.id,    { userInfo: user.metadata } // Optional  );
  // Implement your own security, and give the user access to the room  const { room } = await request.json();  if (room && __shouldUserHaveAccess__(user, room)) {    session.allow(room, session.FULL_ACCESS);  }
  // Retrieve a token from the Liveblocks servers and pass it to the  // requesting client  const { body, status } = await session.authorize();  return new Response(body, { status });}

const { body, status } = await liveblocks.identifyUser(  {    userId: "marie@example.com", // Required, user ID from your DB    groupIds: ["marketing", "engineering"],  },
  // Optional  {    userInfo: {      name: "Marie",      avatar: "https://example.com/avatar/marie.jpg",    },  });
return new Response(body, { status });

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
export default async function auth(req, res) {  /**   * Implement your own security here.   *   * It's your responsibility to ensure that the caller of this endpoint   * is a valid user by validating the cookies or authentication headers   * and that it has access to the requested room.   */
  // Get the current user from your database  const user = __getUserFromDB__(req);
  // Create an ID token for the user  const { body, status } = await liveblocks.identifyUser(    {      userId: user.id,    },    {      userInfo: {        name: user.fullName,        color: user.favoriteColor,      },    }  );
  return new Response(body, { status });}

const { data: rooms, nextCursor } = await liveblocks.getRooms();
// A list of rooms// [{ type: "room", id: "my-room-id", ... }, ...]console.log(rooms);
// A pagination cursor used for retrieving the next page of results with `startingAfter`// "L3YyL3Jvb21z..."console.log(nextCursor);

const { data: rooms, nextCursor } = await liveblocks.getRooms({  // Optional, the amount of rooms to load, between 1 and 100, defaults to 20  limit: 20,
  // Optional, filter for rooms that allow entry to group ID(s) in `groupsAccesses`  groupIds: ["engineering", "design"],
  // Optional, filter for rooms that allow entry to a user's ID in `usersAccesses`  userId: "my-user-id",
  // Optional, use advanced filtering  query: {    // Optional, filter for rooms with an ID that starts with specific string    roomId: {      startsWith: "liveblocks:",    },    // Optional, filter for rooms with custom metadata in `metadata`    metadata: {      roomType: "whiteboard",    },  },
  // Optional, cursor used for pagination, use `nextCursor` from the previous page's response  startingAfter: "L3YyL3Jvb21z...",});

import { RoomData } from "@liveblocks/node";
// An array of pages, each containing a list of retrieved roomsconst pages: RoomData[][] = [];
// Holds the pagination cursor for the next set of roomslet startingAfter;
// Call to get the next page of roomsasync function getNextPage() {  const { data, nextCursor } = await liveblocks.getRooms({ startingAfter });  pages.push(data);  startingAfter = nextCursor;}

const roomsIterator = liveblocks.iterRooms();
for await (const room of roomsIterator) {  // { type: "room", id: "my-room-id", metadata: {...}, ... }  console.log(room);}

const roomsIterator = await liveblocks.iterRooms({  // Optional, filter for rooms that allow entry to group ID(s) in `groupsAccesses`  groupIds: ["engineering", "design"],
  // Optional, filter for rooms that allow entry to a user's ID in `usersAccesses`  userId: "my-user-id",
  // Optional, use advanced filtering  query: {    // Optional, filter for rooms with an ID that starts with specific string    roomId: {      startsWith: "liveblocks:",    },    // Optional, filter for rooms with custom metadata in `metadata`    metadata: {      roomType: "whiteboard",    },  },});
for await (const room of roomsIterator) {  // { type: "room", id: "my-room-id", metadata: {...}, ... }  console.log(room);}

const room = await liveblocks.createRoom("my-room-id", {  defaultAccesses: ["room:write"],});
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

const room = await liveblocks.createRoom("my-room-id", {  // The default room permissions. `[]` for private, `["room:write"]` for public.  defaultAccesses: [],
  // Optional, the room's group ID permissions  groupsAccesses: {    design: ["room:write"],    engineering: ["room:presence:write", "room:read"],  },
  // Optional, the room's user ID permissions  usersAccesses: {    "my-user-id": ["room:write"],  },
  // Optional, custom metadata to attach to the room  metadata: {    myRoomType: "whiteboard",  },});

const room = await liveblocks.getRoom("my-room-id");
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

const room = await liveblocks.getOrCreateRoom("my-room-id", {  defaultAccesses: ["room:write"],});
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

const room = await liveblocks.getOrCreateRoom("my-room-id", {  // The default room permissions. `[]` for private, `["room:write"]` for public.  defaultAccesses: [],
  // Optional, the room's group ID permissions  groupsAccesses: {    design: ["room:write"],    engineering: ["room:presence:write", "room:read"],  },
  // Optional, the room's user ID permissions  usersAccesses: {    "my-user-id": ["room:write"],  },
  // Optional, custom metadata to attach to the room  metadata: {    myRoomType: "whiteboard",  },});

const room = await liveblocks.updateRoom("my-room-id", {  // The metadata or permissions you're updating  // ...});
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

const room = await liveblocks.updateRoom("my-room-id", {  // Optional, update the default room permissions. `[]` for private, `["room:write"]` for public.  defaultAccesses: [],
  // Optional, update the room's group ID permissions  groupsAccesses: {    design: ["room:write"],    engineering: ["room:presence:write", "room:read"],  },
  // Optional, update the room's user ID permissions  usersAccesses: {    "my-user-id": ["room:write"],  },
  // Optional, custom metadata to update on the room  metadata: {    myRoomType: "whiteboard",  },});

const room = await liveblocks.upsertRoom("my-room-id", {  // These fields will get updated when the room exists, or will be created  update: {    metadata: { color: "red" },  },  // These fields will only be set when the room will get created  create: {    defaultAccesses: ["room:write"],  },});
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

const room = await liveblocks.upsertRoom("my-room-id", {  update: {    // The default room permissions. `[]` for private, `["room:write"]` for public.    defaultAccesses: [],
    // Optional, the room's group ID permissions    groupsAccesses: {      design: ["room:write"],      engineering: ["room:presence:write", "room:read"],    },
    // Optional, the room's user ID permissions    usersAccesses: {      "my-user-id": ["room:write"],    },
    // Optional, custom metadata to attach to the room    metadata: {      myRoomType: "whiteboard",    },  },});

const room = await liveblocks.updateRoomId({  roomId: "my-room-id",  newRoomId: "new-room-id",});
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

const activeUsers = await liveblocks.getActiveUsers("my-room-id");
// { data: [{ type: "user", id: "my-user-id", ... }, ...] }console.log(activeUsers);

const customEvent = {  type: "EMOJI",  emoji: "🔥",};
await liveblocks.broadcastEvent("my-room-id", customEvent);

// Retrieve LSON Storage dataconst storage = await liveblocks.getStorageDocument("my-room-id", "plain-lson");
// If this were your Storage type...declare global {  interface Liveblocks {    Storage: {      names: LiveList<string>;    };  }}
// {//   liveblocksType: "LiveObject",//   data: {//     names: {//       liveblocksType: "LiveList",//       data: ["Olivier", "Nimesh"],//     }//   }// }console.log(storage);

// Retrieve JSON Storage dataconst storage = await liveblocks.getStorageDocument("my-room-id", "json");
// If this were your Storage type...declare global {  interface Liveblocks {    Storage: {      names: LiveList<string>;    };  }}
// {//   names: ["Olivier", "Nimesh"]// }console.log(storage);

// Create a new roomconst room = await liveblocks.createRoom("my-room-id", {  defaultAccesses: ["room:write"],});
// Initialize Storageconst storage = await liveblocks.initializeStorageDocument("my-room-id", {  // Your LSON Storage value  // ...});

import { toPlainLson, LiveList, LiveObject } from "@liveblocks/client";
// Create a new roomconst room = await liveblocks.createRoom("my-room-id", {  defaultAccesses: ["room:write"],});
// If this were your Storage type...declare global {  interface Liveblocks {    Storage: {      names: LiveList<string>;    };  }}
// Create the initial conflict-free dataconst initialStorage: LiveObject<Liveblocks["Storage"]> = new LiveObject({  names: new LiveList(["Olivier", "Nimesh"]),});
// Convert to LSON and create Storageconst storage = await liveblocks.initializeStorageDocument(  "my-room-id",  toPlainLson(initialStorage));

// Create a new roomconst room = await liveblocks.createRoom("my-room-id", {  defaultAccesses: ["room:write"],});
// If this were your Storage type...declare global {  interface Liveblocks {    Storage: {      names: LiveList<string>;    };  }}
// Create this Storage and add names to the LiveListconst storage = await liveblocks.initializeStorageDocument("my-room-id", {  liveblocksType: "LiveObject",  data: {    names: {      liveblocksType: "LiveList",      data: ["Olivier", "Nimesh"],    },  },});

// Mutate a single roomawait liveblocks.mutateStorage(  "my-room-id",
  ({ root }) => {    root.get("list").push("item3");  });

// Mutate a single roomawait liveblocks.mutateStorage(  "my-room-id",
  async ({ root }) => {    // These changes happen immediately    const animals = root.get("animals");    animals.clear();    animals.push("Thinking...");
    await thinkForAWhile();
    // These changes happen after `await` has run    animals.clear();    animals.push("🐶");    animals.push("🦘");  });

// Mutate a number of roomsawait liveblocks.massMutateStorage(  {},
  // Callback runs on every selected room  ({ room, root }) => {    // { type: "room", id: "my-room-id", metadata: {...}, ... }    console.log(room);
    root.get("animals").push("🦍");  });

// Mutate a number of roomsawait liveblocks.massMutateStorage(  {    // Optional, filter for rooms that allow entry to group ID(s) in `groupsAccesses`    groupIds: ["engineering", "design"],
    // Optional, filter for rooms that allow entry to a user's ID in `usersAccesses`    userId: "my-user-id",
    // Optional, use advanced filtering    query: {      // Optional, filter for rooms with an ID that starts with specific string      roomId: {        startsWith: "liveblocks:",      },      // Optional, filter for rooms with custom metadata in `metadata`      metadata: {        roomType: "whiteboard",      },    },  },
  ({ room, root }) => {    // { type: "room", id: "my-room-id", metadata: {...}, ... }    console.log(room);
    root.get("animals").push("🦍");  },
  // Optional  {    concurrency: 10, // Optional, process at most 10 rooms simultaneously    signal, // Optional, provide an abort signal to cancel mutations mid-way  });

const yjsDocument = await liveblocks.getYjsDocument("my-room-id");
// { yourYText: "...", yourYArray: [...], ... }console.log(yjsDocument);

const yjsDocument = await liveblocks.getYjsDocument("my-room-id", {  // Optional, if true, `yText` values will return formatting  format: true,
  // Optional, return a single key's value, e.g. `yDoc.get("my-key-id").toJson()`  key: "my-key-id",
  // Optional, override the inferred `key` type, e.g. "ymap" for `doc.get(key, Y.Map)`  type: "ymap",});

import * as Y from "yjs";
// Create a Yjs documentconst yDoc = new Y.Doc();
// Create your data structures and make your update// If you're using a text editor, you need to match its formatconst yText = yDoc.getText("text");yText.insert(0, "Hello world");
// Encode the document state as an updateconst update = Y.encodeStateAsUpdate(yDoc);
// Send update to Liveblocksawait liveblocks.sendYjsBinaryUpdate("my-room-id", update);

await liveblocks.sendYjsBinaryUpdate("my-room-id", update, {  // Optional, update a subdocument instead. guid is its unique identifier  guid: "c4a755...",});

// Create new roomconst room = await liveblocks.createRoom("my-room-id");
// Set initial Yjs document valueawait liveblocks.sendYjsBinaryUpdate("my-room-id", state);

const binaryYjsUpdate =  await liveblocks.getYjsDocumentAsBinaryUpdate("my-room-id");

const binaryYjsUpdate = await liveblocks.getYjsDocumentAsBinaryUpdate(  "my-room-id",  {    // Optional, return a subdocument instead. guid is its unique identifier    guid: "c4a755...",  });

const schemaBody = `  type Storage {    names: LiveList<string>  }`;
const schema = await liveblocks.createSchema("my-schema-name", schemaBody);
// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }console.log(schema);

const updatedBody = `  type Storage {    names: LiveMap<string, string>  }`;
const schema = await liveblocks.getSchema("my-schema-name@1", updatedBody);
// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }console.log(schema);

const schema = await liveblocks.updateSchema("my-schema-name@1");
// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }console.log(schema);

const schema = await liveblocks.getSchemaByRoomId("my-room-id");
// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }console.log(schema);

const schema = await liveblocks.attachSchemaToRoom(  "my-room-id",  "my-schema-name@1");
// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }console.log(schema);

const { data: threads } = await liveblocks.getThreads({  roomId: "my-room-id",});
// [{ type: "thread", id: "th_d75sF3...", ... }, ...]console.log(threads);

const { data: threads } = await liveblocks.getThreads({  roomId: "my-room-id",
  // Optional, use advanced filtering  query: {    // Optional, filter based on resolved status    resolved: false,    // Optional, filter for metadata values    metadata: {      status: "open",      pinned: true,      priority: 3,
      // You can match the start of a metadata string      organization: {        startsWith: "liveblocks:",      },    },  },});

const thread = await liveblocks.createThread({  roomId: "my-room-id",
  data: {    comment: {      userId: "florent@example.com",      body: {        version: 1,        content: [          /* The comment's body text goes here, see below */        ],      },    },  },});
// { type: "thread", id: "th_d75sF3...", ... }console.log(thread);

const thread = await liveblocks.createThread({  roomId: "my-room-id",
  data: {    // Optional, custom metadata properties    metadata: {      color: "blue",      page: 3,      pinned: true,    },
    // Data for the first comment in the thread    comment: {      // The ID of the user that created the comment      userId: "florent@example.com",
      // Optional, when the comment was created.      createdAt: new Date(),
      // The comment's body, uses the `CommentBody` type      body: {        version: 1,        content: [          /* The comment's body text goes here, see above */        ],      },    },  },});
// { type: "thread", id: "th_d75sF3...", ... }console.log(thread);

const thread = await liveblocks.getThread({  roomId: "my-room-id",  threadId: "th_d75sF3...",});
// { type: "thread", id: "th_d75sF3...", ... }console.log(thread);

const { participantIds } = await liveblocks.getThreadParticipants({  roomId: "my-room-id",  threadId: "th_d75sF3...",});
// ["chris@example.com", "nimesh@example.com", ...]console.log(participantIds);

const editedMetadata = await liveblocks.editThreadMetadata({  roomId: "my-room-id",  threadId: "th_d75sF3...",
  data: {    metadata: {      color: "yellow",    },    userId: "marc@example.com",    updatedAt: new Date(), // Optional  },});
// { color: "yellow", page: 3, pinned: true }console.log(editedMetadata);

const editedMetadata = await liveblocks.editThreadMetadata({  roomId: "my-room-id",  threadId: "th_d75sF3...",
  data: {    // Custom metadata    metadata: {      // Metadata can be a string, number, or boolean      title: "My thread title",      page: 3,      pinned: true,
      // Remove metadata with null      color: null,    },
    // The ID of the user that updated the metadata    userId: "marc@example.com",
    // Optional, the time the user updated the metadata    updatedAt: new Date(),  },});
// { title: "My thread title", page: 3, pinned: true }console.log(editedMetadata);

const thread = await liveblocks.markThreadAsResolved({  roomId: "my-room-id",  threadId: "th_d75sF3...",  data: {    userId: "steven@example.com",  },});
// { type: "thread", id: "th_d75sF3...", ... }console.log(thread);

const thread = await liveblocks.markThreadAsUnresolved({  roomId: "my-room-id",  threadId: "th_d75sF3...",  data: {    userId: "steven@example.com",  },});
// { type: "thread", id: "th_d75sF3...", ... }console.log(thread);