add docs for presence, node api (liveblocks#3068)

jrowny · web-flow · commit e28c0de4d02c · 2026-02-17T14:34:22.000-08:00
diff --git a/docs/pages/api-reference/liveblocks-node.mdx b/docs/pages/api-reference/liveblocks-node.mdx
@@ -1157,6 +1157,37 @@ useEventListener(({ event, user, connectionId }) => {
 });
 ```
 
+#### Liveblocks.setPresence [#post-rooms-roomId-presence]
+
+Sets ephemeral presence for a user in a room without requiring a WebSocket
+connection. The presence data automatically expires after the specified TTL
+(time-to-live). This is useful for scenarios like showing an AI agent’s presence
+in a room. The presence is broadcast to all connected users in the room. This is
+a wrapper around the
+[Set Presence API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-presence)
+and returns no response on success.
+
+```ts
+await liveblocks.setPresence("my-room-id", {
+  userId: "agent-123",
+  data: {
+    status: "active",
+    cursor: { x: 100, y: 200 },
+  },
+  userInfo: {
+    name: "AI Assistant",
+    avatar: "https://example.com/avatar.png",
+  },
+  ttl: 60, // optional, 2–3599 seconds
+});
+```
+
+- **userId** (required): The ID of the user to set presence for.
+- **data** (required): Presence data as a JSON object.
+- **userInfo** (optional): Metadata about the user or agent
+- **ttl** (optional): Time-to-live in seconds (minimum 2, maximum 3599).
+  Defaults to 60. After this duration, the presence expires automatically.
+
 ### Groups
 
 Groups allow you to manage users for group mentions in comments and text
diff --git a/docs/references/v2.openapi.json b/docs/references/v2.openapi.json
@@ -757,6 +757,71 @@
         }
       }
     },
+    "/rooms/{roomId}/presence": {
+      "post": {
+        "summary": "Set ephemeral presence",
+        "description": "This endpoint sets ephemeral presence for a user in a room without requiring a WebSocket connection. The presence data will automatically expire after the specified TTL (time-to-live). This is useful for scenarios like showing an AI agent's presence in a room. The presence will be broadcast to all connected users in the room.",
+        "tags": ["Room"],
+        "operationId": "post-rooms-roomId-presence",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "name": "roomId",
+            "in": "path",
+            "required": true,
+            "description": "ID of the room"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SetPresence"
+              },
+              "examples": {
+                "example": {
+                  "value": {
+                    "userId": "agent-123",
+                    "data": {
+                      "status": "active",
+                      "cursor": {
+                        "x": 100,
+                        "y": 200
+                      }
+                    },
+                    "userInfo": {
+                      "name": "AI Assistant",
+                      "avatar": "https://example.org/images/agent123.jpg"
+                    },
+                    "ttl": 60
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "Success. Presence was set for the user in the room."
+          },
+          "401": {
+            "$ref": "#/components/responses/401"
+          },
+          "403": {
+            "$ref": "#/components/responses/403"
+          },
+          "404": {
+            "$ref": "#/components/responses/404"
+          },
+          "422": {
+            "$ref": "#/components/responses/422"
+          }
+        }
+      }
+    },
     "/rooms/{roomId}/broadcast_event": {
       "post": {
         "summary": "Broadcast event to a room",
@@ -8513,6 +8578,47 @@
           }
         },
         "required": ["message"]
+      },
+      "SetPresence": {
+        "title": "SetPresence",
+        "type": "object",
+        "properties": {
+          "userId": {
+            "type": "string",
+            "description": "ID of the user to set presence for"
+          },
+          "data": {
+            "type": "object",
+            "description": "Presence data as a JSON object"
+          },
+          "userInfo": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional name for the user or agent"
+              },
+              "avatar": {
+                "type": "string",
+                "description": "Optional avatar URL for the user"
+              },
+              "color": {
+                "type": "string",
+                "description": "Optional color for the user"
+              }
+            },
+            "required": [],
+            "description": "Metadata about the user or agent"
+          },
+          "ttl": {
+            "type": "integer",
+            "minimum": 2,
+            "maximum": 3599,
+            "description": "Time-to-live in seconds (minimum: 2, maximum: 3599). After this duration, the presence will automatically expire."
+          }
+        },
+        "required": ["userId", "data"]
       }
     },
     "securitySchemes": {
diff --git a/packages/liveblocks-node/src/__tests__/client.test.ts b/packages/liveblocks-node/src/__tests__/client.test.ts
@@ -118,6 +118,9 @@ describe("client", () => {
     }),
     http.get(`${DEFAULT_BASE_URL}/v2/rooms/:roomId/prewarm`, () => {
       return new HttpResponse(null, { status: 204 });
+    }),
+    http.post(`${DEFAULT_BASE_URL}/v2/rooms/:roomId/presence`, () => {
+      return new HttpResponse(null, { status: 204 });
     })
   );
 
@@ -627,6 +630,65 @@ describe("client", () => {
     });
   });
 
+  describe("set presence", () => {
+    test("should successfully set presence when receiving 204 response", async () => {
+      const client = new Liveblocks({ secret: "sk_xxx" });
+
+      await expect(
+        client.setPresence("room-123", {
+          userId: "agent-ai",
+          data: { status: "active", cursor: { x: 100, y: 200 } },
+          userInfo: {
+            name: "AI Assistant",
+            avatar: "https://example.com/avatar.png",
+          },
+          ttl: 60,
+        }),
+      ).resolves.toBeUndefined();
+    });
+
+    test("should handle optional ttl parameter", async () => {
+      const client = new Liveblocks({ secret: "sk_xxx" });
+
+      await expect(
+        client.setPresence("room-123", {
+          userId: "agent-ai",
+          data: { status: "active" },
+          userInfo: { name: "AI Assistant" },
+        }),
+      ).resolves.toBeUndefined();
+    });
+
+    test("should throw LiveblocksError on failure", async () => {
+      server.use(
+        http.post(`${DEFAULT_BASE_URL}/v2/rooms/:roomId/presence`, () => {
+          return HttpResponse.json(
+            { error: "INVALID_REQUEST", message: "Invalid presence data" },
+            { status: 422 },
+          );
+        }),
+      );
+
+      const client = new Liveblocks({ secret: "sk_xxx" });
+
+      try {
+        await client.setPresence("room-123", {
+          userId: "agent-ai",
+          data: { status: "active" },
+          userInfo: { name: "AI Assistant" },
+        });
+        expect(true).toBe(false);
+      } catch (err) {
+        expect(err instanceof LiveblocksError).toBe(true);
+        if (err instanceof LiveblocksError) {
+          expect(err.status).toBe(422);
+          expect(err.message).toBe("Invalid presence data");
+          expect(err.name).toBe("LiveblocksError");
+        }
+      }
+    });
+  });
+
   describe("edit comment", () => {
     test("should return the edited comment when editComment receives a successful response", async () => {
       const commentData = {
diff --git a/packages/liveblocks-node/src/client.ts b/packages/liveblocks-node/src/client.ts
@@ -634,6 +634,18 @@ export type RequestOptions = {
   signal?: AbortSignal;
 };
 
+export type SetPresenceOptions = {
+  userId: string;
+  data: JsonObject;
+  userInfo?: {
+    name?: string;
+    avatar?: string;
+    color?: string;
+    [key: string]: Json | undefined;
+  };
+  ttl?: number;
+};
+
 /**
  * Converts ISO-formatted date strings to Date instances on RoomDataPlain
  * values.
@@ -1219,6 +1231,38 @@ export class Liveblocks {
     }
   }
 
+  /**
+   * Sets ephemeral presence for a user in a room without requiring a WebSocket connection.
+   * The presence data will automatically expire after the specified TTL.
+   * This is useful for scenarios like showing an AI agent's presence in a room.
+   *
+   * @param roomId The id of the room to set presence in.
+   * @param params.userId The ID of the user to set presence for.
+   * @param params.data The presence data as a JSON object.
+   * @param params.userInfo (optional) Metadata about the user or agent
+   * @param params.ttl (optional) Time-to-live in seconds. If not specified, the default TTL is 60 seconds. (minimum: 2, maximum: 3599).
+   * @param options.signal (optional) An abort signal to cancel the request.
+   */
+  public async setPresence(
+    roomId: string,
+    params: SetPresenceOptions,
+    options?: RequestOptions
+  ): Promise<void> {
+    const res = await this.#post(
+      url`/v2/rooms/${roomId}/presence`,
+      {
+        userId: params.userId,
+        data: params.data,
+        userInfo: params.userInfo,
+        ttl: params.ttl,
+      },
+      options
+    );
+    if (!res.ok) {
+      throw await LiveblocksError.from(res);
+    }
+  }
+
   /* -------------------------------------------------------------------------------------------------
    * Storage
    * -----------------------------------------------------------------------------------------------*/
diff --git a/packages/liveblocks-node/src/index.ts b/packages/liveblocks-node/src/index.ts
@@ -29,6 +29,7 @@ export type {
   RoomPermission,
   RoomsQueryCriteria,
   RoomUser,
+  SetPresenceOptions,
   ThreadParticipants,
   UpdateAiCopilotOptions,
   UpdateRoomOptions,
