@newbase-clawchat/openclaw-clawchat 2026.5.12-2 → 2026.5.12-21

package/src/api-client.test.ts

@@ -55,12 +55,28 @@ describe("openclaw-clawchat api-client", () => {
     expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/u%2F2");
   });
 
-  it("listFriends sends page + pageSize as query string", async () => {
+  it("getUserProfile aliases GET /v1/users/{id}", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({ code: 0, message: "ok", data: { id: "u/2", nickname: "Bob" } }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+
+    const profile = await client.getUserProfile("u/2");
+
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/u%2F2");
+    expect(profile).toEqual({ id: "u/2", nickname: "Bob" });
+  });
+
+  it("getAgentDetail calls GET /v1/agents/{agent_id}", async () => {
     const fetchImpl = vi.fn().mockResolvedValue(
       jsonResponse({
         code: 0,
         message: "ok",
-        data: { items: [], page: 2, pageSize: 50 },
+        data: { agent: { user_id: "agt/1", owner_id: "owner", type: "agent" } },
       }),
     );
     const client = createOpenclawClawlingApiClient({
@@ -68,10 +84,221 @@ describe("openclaw-clawchat api-client", () => {
       token: "tk",
       fetchImpl,
     });
-    await client.listFriends({ page: 2, pageSize: 50 });
-    expect(fetchImpl.mock.calls[0]![0]).toBe(
-      "https://api.example.com/v1/friends?page=2&pageSize=50",
+
+    await client.getAgentDetail("agt/1");
+
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/agents/agt%2F1");
+  });
+
+  describe("metadata REST helpers", () => {
+    it("patchAgent sends only nickname/avatar_url/bio/behavior to PATCH /v1/agents/{agent_id}", async () => {
+      const fetchImpl = vi.fn().mockResolvedValue(
+        jsonResponse({
+          code: 0,
+          message: "ok",
+          data: {
+            agent: {
+              id: "agt/1",
+              owner_id: "owner",
+              user_id: "agent-user",
+              type: "bot",
+              nickname: "OpenClaw Bot",
+              avatar_url: "https://cdn/agent.png",
+              bio: "metadata bio",
+              visibility: "public",
+              status: "active",
+              platform: "openclaw",
+              created_at: "2026-05-24T00:00:00Z",
+            },
+          },
+        }),
+      );
+      const client = createOpenclawClawlingApiClient({
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        fetchImpl,
+      });
+
+      const result = await client.patchAgent("agt/1", {
+        nickname: "OpenClaw Bot",
+        avatar_url: "https://cdn/agent.png",
+        bio: "metadata bio",
+        behavior: "do not forward",
+        filePath: "owner.md",
+      } as never);
+
+      expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/agents/agt%2F1");
+      const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+      expect(init.method).toBe("PATCH");
+      expect(JSON.parse(init.body as string)).toEqual({
+        nickname: "OpenClaw Bot",
+        avatar_url: "https://cdn/agent.png",
+        bio: "metadata bio",
+        behavior: "do not forward",
+      });
+      expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+      expect(result.agent.nickname).toBe("OpenClaw Bot");
+    });
+
+    it("patchConversation sends only title/description to PATCH /v1/conversations/{id}", async () => {
+      const fetchImpl = vi.fn().mockResolvedValue(
+        jsonResponse({
+          code: 0,
+          message: "ok",
+          data: {
+            conversation: {
+              id: "cnv/1",
+              type: "group",
+              title: "Metadata Team",
+              description: "Group metadata",
+              creator_id: "usr_creator",
+              created_at: "2026-05-20T00:00:00Z",
+              updated_at: "2026-05-24T00:00:00Z",
+              participants: [],
+            },
+          },
+        }),
+      );
+      const client = createOpenclawClawlingApiClient({
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        fetchImpl,
+      });
+
+      const result = await client.patchConversation("cnv/1", {
+        title: "Metadata Team",
+        description: "Group metadata",
+        filePath: "groups/cnv_1.md",
+      } as never);
+
+      expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/conversations/cnv%2F1");
+      const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+      expect(init.method).toBe("PATCH");
+      expect(JSON.parse(init.body as string)).toEqual({
+        title: "Metadata Team",
+        description: "Group metadata",
+      });
+      expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+      expect(result.conversation.description).toBe("Group metadata");
+    });
+
+    it("metadata user updates still use updateMyProfile with PATCH /v1/users/me", async () => {
+      const fetchImpl = vi.fn().mockResolvedValue(
+        jsonResponse({
+          code: 0,
+          message: "ok",
+          data: { id: "usr_1", nickname: "Alice", avatar_url: "https://cdn/a.png", bio: "hello" },
+        }),
+      );
+      const client = createOpenclawClawlingApiClient({
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        fetchImpl,
+      });
+
+      await client.updateMyProfile({
+        nickname: "Alice",
+        avatar_url: "https://cdn/a.png",
+        bio: "hello",
+      });
+
+      expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/me");
+      const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+      expect(init.method).toBe("PATCH");
+      expect(JSON.parse(init.body as string)).toEqual({
+        nickname: "Alice",
+        avatar_url: "https://cdn/a.png",
+        bio: "hello",
+      });
+    });
+
+    it("metadata getConversation preserves participants for caller mapping", async () => {
+      const participants = [
+        {
+          conversation_id: "cnv_1",
+          user_id: "usr_1",
+          role: "owner",
+          joined_at: "2026-05-20T00:00:00Z",
+          user: { id: "usr_1", nickname: "Alice", avatar_url: "https://cdn/a.png" },
+        },
+        {
+          conversation_id: "cnv_1",
+          user_id: "usr_2",
+          role: "member",
+          joined_at: "2026-05-21T00:00:00Z",
+          user: { id: "usr_2", nickname: "Bob", avatar_url: "https://cdn/b.png" },
+        },
+      ];
+      const fetchImpl = vi.fn().mockResolvedValue(
+        jsonResponse({
+          code: 0,
+          message: "ok",
+          data: {
+            conversation: {
+              id: "cnv_1",
+              type: "group",
+              title: "Team",
+              creator_id: "usr_1",
+              created_at: "2026-05-20T00:00:00Z",
+              updated_at: "2026-05-24T00:00:00Z",
+              participants,
+            },
+          },
+        }),
+      );
+      const client = createOpenclawClawlingApiClient({
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        fetchImpl,
+      });
+
+      const result = await client.getConversation("cnv_1");
+
+      expect(result.conversation.participants).toEqual(participants);
+    });
+
+    it("metadata patch helpers reject blank ids and empty allowed patches before sending", async () => {
+      const fetchImpl = vi.fn();
+      const client = createOpenclawClawlingApiClient({
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        fetchImpl,
+      });
+
+      await expect(client.patchAgent("   ", { nickname: "Bot" })).rejects.toMatchObject({
+        kind: "validation",
+      });
+      await expect(client.patchAgent("agt_1", {})).rejects.toMatchObject({
+        kind: "validation",
+      });
+      await expect(client.patchConversation("", { title: "Team" })).rejects.toMatchObject({
+        kind: "validation",
+      });
+      await expect(
+        client.patchConversation("cnv_1", { filePath: "groups/cnv_1.md" } as never),
+      ).rejects.toMatchObject({
+        kind: "validation",
+      });
+      expect(fetchImpl).not.toHaveBeenCalled();
+    });
+  });
+
+  it("listFriends uses the friendships endpoint", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { friends: [{ id: "u1", nickname: "Alice", type: "user" }] },
+      }),
     );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.listFriends();
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/friendships");
+    expect(result).toEqual({ friends: [{ id: "u1", nickname: "Alice", type: "user" }] });
   });
 
   it("searchUsers sends q + limit as query string", async () => {
@@ -217,7 +444,7 @@ describe("openclaw-clawchat api-client", () => {
     expect((fetchImpl.mock.calls[0]![1] as RequestInit).method).toBe("DELETE");
   });
 
-  it("updateMyProfile sends PATCH /me with JSON body", async () => {
+  it("updateMyProfile sends PATCH /me with JSON body without requiring configured userId", async () => {
     const fetchImpl = vi.fn().mockResolvedValue(
       jsonResponse({
         code: 0,
@@ -228,7 +455,6 @@ describe("openclaw-clawchat api-client", () => {
     const client = createOpenclawClawlingApiClient({
       baseUrl: "https://api.example.com",
       token: "tk",
-      userId: "agent-1",
       fetchImpl,
     });
     await client.updateMyProfile({ display_name: "Alice2" });
@@ -258,18 +484,91 @@ describe("openclaw-clawchat api-client", () => {
     expect(JSON.parse(init.body as string)).toEqual({ bio: "hello there" });
   });
 
-  it("updateMyProfile throws validation error when userId is not configured", async () => {
-    const fetchImpl = vi.fn();
+  it("listConversations sends before + limit as query string", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: {
+          conversations: [
+            {
+              id: "cnv_1",
+              type: "direct",
+              title: "Alice",
+              created_at: "2026-05-20T00:00:00Z",
+              updated_at: "2026-05-20T00:01:00Z",
+              peer: { id: "usr_1", type: "user", nickname: "Alice", avatar_url: "https://cdn/a.png" },
+            },
+          ],
+          next_before: "cursor-2",
+        },
+      }),
+    );
     const client = createOpenclawClawlingApiClient({
       baseUrl: "https://api.example.com",
       token: "tk",
-      // userId intentionally omitted
       fetchImpl,
     });
-    await expect(client.updateMyProfile({ display_name: "x" })).rejects.toMatchObject({
-      kind: "validation",
+    const result = await client.listConversations({ before: "cursor-1", limit: 10 });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/conversations?before=cursor-1&limit=10",
+    );
+    expect(result.conversations[0]!.id).toBe("cnv_1");
+    expect(result.conversations[0]!.created_at).toBe("2026-05-20T00:00:00Z");
+    expect(result.conversations[0]!.peer.nickname).toBe("Alice");
+    expect(result.next_before).toBe("cursor-2");
+  });
+
+  it("getConversation sends GET /v1/conversations/{id}", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: {
+          conversation: {
+            id: "cnv_1",
+            type: "group",
+            title: "Team",
+            creator_id: "usr_creator",
+            created_at: "2026-05-20T00:00:00Z",
+            updated_at: "2026-05-20T00:01:00Z",
+            participants: [
+              {
+                conversation_id: "cnv_1",
+                user_id: "usr_1",
+                role: "owner",
+                joined_at: "2026-05-20T00:00:00Z",
+              },
+            ],
+          },
+        },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
     });
-    expect(fetchImpl).not.toHaveBeenCalled();
+    const result = await client.getConversation("cnv_1");
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/conversations/cnv_1");
+    expect(result.conversation.title).toBe("Team");
+    expect(result.conversation.creator_id).toBe("usr_creator");
+    expect(result.conversation.participants[0]!.user_id).toBe("usr_1");
+  });
+
+  it("does not expose conversation admin mutation methods", () => {
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl: vi.fn(),
+    });
+    expect(client).not.toHaveProperty("createConversation");
+    expect(client).not.toHaveProperty("updateConversation");
+    expect(client).not.toHaveProperty("leaveConversation");
+    expect(client).not.toHaveProperty("dissolveConversation");
+    expect(client).not.toHaveProperty("addConversationUsers");
+    expect(client).not.toHaveProperty("removeConversationUsers");
+    expect(client).not.toHaveProperty("listConversationUsers");
   });
 
   it("uploadMedia POSTs multipart with field name 'file'", async () => {
@@ -277,7 +576,7 @@ describe("openclaw-clawchat api-client", () => {
       jsonResponse({
         code: 0,
         message: "ok",
-        data: { url: "https://cdn/x.png", size: 12, mime: "image/png" },
+        data: { kind: "image", url: "https://cdn/x.png", name: "x.png", size: 12, mime: "image/png" },
       }),
     );
     const client = createOpenclawClawlingApiClient({
@@ -301,7 +600,51 @@ describe("openclaw-clawchat api-client", () => {
     expect(file).toBeInstanceOf(File);
     expect(file.name).toBe("x.png");
     expect(file.type).toBe("image/png");
-    expect(result).toEqual({ url: "https://cdn/x.png", size: 12, mime: "image/png" });
+    expect(result).toEqual({ kind: "image", url: "https://cdn/x.png", name: "x.png", size: 12, mime: "image/png" });
+  });
+
+  it.each([
+    ["kind", { url: "https://cdn/x.png", name: "x.png", size: 12, mime: "image/png" }],
+    ["url", { kind: "image", name: "x.png", size: 12, mime: "image/png" }],
+    ["name", { kind: "image", url: "https://cdn/x.png", size: 12, mime: "image/png" }],
+    ["mime", { kind: "image", url: "https://cdn/x.png", name: "x.png", size: 12 }],
+    ["size", { kind: "image", url: "https://cdn/x.png", name: "x.png", mime: "image/png" }],
+  ])("uploadMedia treats missing %s in response data as protocol error", async (_field, data) => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({ code: 0, message: "ok", data }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(
+      client.uploadMedia({
+        buffer: Buffer.from("hi-bytes-12!"),
+        filename: "x.png",
+        mime: "image/png",
+      }),
+    ).rejects.toMatchObject({ kind: "api" });
+  });
+
+  it("uploadMedia treats unsupported kind in response data as protocol error", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { kind: "bogus", url: "https://cdn/x.png", name: "x.png", size: 12, mime: "image/png" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(
+      client.uploadMedia({
+        buffer: Buffer.from("hi-bytes-12!"),
+        filename: "x.png",
+        mime: "image/png",
+      }),
+    ).rejects.toMatchObject({ kind: "api" });
   });
 
   it("uploadAvatar POSTs multipart to /v1/files/upload-url", async () => {
@@ -333,6 +676,8 @@ describe("openclaw-clawchat api-client", () => {
     expect(file.type).toBe("image/png");
     // X-Device-Id is present on avatar uploads too.
     expect((init.headers as Record<string, string>)["x-device-id"]).toBe("openclaw-clawchat");
+    expect(result).not.toHaveProperty("kind");
+    expect(result).not.toHaveProperty("name");
     expect(result).toEqual({ url: "https://cdn/avatars/a.png", size: 99, mime: "image/png" });
   });
 

package/src/api-client.ts

@@ -1,6 +1,12 @@
 import {
   ClawlingApiError,
+  type AgentMetadataPatch,
+  type AgentProfile,
   type AgentConnectResult,
+  type AvatarUploadResult,
+  type ConversationDetails,
+  type ConversationListResult,
+  type ConversationMetadataPatch,
   type FriendList,
   type MomentComment,
   type MomentReaction,
@@ -14,11 +20,7 @@ import { CHANNEL_ID } from "./config.ts";
 export interface ApiClientOptions {
   baseUrl: string;
   token: string;
-  /**
-   * Logged-in agent's `user_id`. Required for `updateMyProfile`, which
-   * targets `/v1/agents/{userId}`. Safe to omit for unauthenticated /
-   * pre-login calls (e.g. `agentsConnect`).
-   */
+  /** Logged-in agent's `user_id`, used by WebSocket setup but not REST `/me` calls. */
   userId?: string;
   /** Test override only. Defaults to global `fetch`. */
   fetchImpl?: typeof fetch;
@@ -26,8 +28,12 @@ export interface ApiClientOptions {
 
 export interface OpenclawClawlingApiClient {
   getMyProfile(): Promise<Profile>;
+  getAgentProfile(agentId: string): Promise<{ agent: AgentProfile }>;
+  getAgentDetail(agentId: string): Promise<{ agent: AgentProfile }>;
+  patchAgent(agentId: string, patch: AgentMetadataPatch): Promise<{ agent: AgentProfile }>;
   getUserInfo(userId: string): Promise<Profile>;
-  listFriends(params: { page?: number; pageSize?: number }): Promise<FriendList>;
+  getUserProfile(userId: string): Promise<Profile>;
+  listFriends(): Promise<FriendList>;
   searchUsers(params: { q?: string; limit?: number }): Promise<{ users: UserSearchHit[] }>;
   listMoments(params: { before?: number; limit?: number }): Promise<{ moments: MomentView[] }>;
   createMoment(body: { text?: string; images?: string[] }): Promise<{ moment: MomentView }>;
@@ -46,6 +52,12 @@ export interface OpenclawClawlingApiClient {
     text: string;
   }): Promise<{ comment: MomentComment }>;
   deleteMomentComment(params: { momentId: number; commentId: number }): Promise<{ ok: boolean }>;
+  listConversations(params: { before?: string; limit?: number }): Promise<ConversationListResult>;
+  getConversation(conversationId: string): Promise<{ conversation: ConversationDetails }>;
+  patchConversation(
+    conversationId: string,
+    patch: ConversationMetadataPatch,
+  ): Promise<{ conversation: ConversationDetails }>;
   updateMyProfile(patch: { nickname?: string; avatar_url?: string; bio?: string }): Promise<Profile>;
   uploadMedia(params: { buffer: Buffer; filename: string; mime?: string }): Promise<UploadResult>;
   /**
@@ -61,15 +73,14 @@ export interface OpenclawClawlingApiClient {
     type: string;
   }): Promise<AgentConnectResult>;
   /**
-   * Upload an avatar image via `POST /v1/files/upload-url`. Returns the
-   * same `UploadResult` shape as `uploadMedia` — the resulting `url` is
-   * what you then pass to `updateMyProfile({ avatar: url })`.
+   * Upload an avatar image via `POST /v1/files/upload-url`. The resulting
+   * `url` is what you then pass to `updateMyProfile({ avatar_url: url })`.
    */
   uploadAvatar(params: {
     buffer: Buffer;
     filename: string;
     mime?: string;
-  }): Promise<UploadResult>;
+  }): Promise<AvatarUploadResult>;
 }
 
 export function createOpenclawClawlingApiClient(opts: ApiClientOptions): OpenclawClawlingApiClient {
@@ -173,6 +184,50 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
     return await readEnvelope<T>(res, path);
   }
 
+  function parseUploadResult(data: unknown, path: string): UploadResult {
+    const obj = data as Partial<UploadResult> | null;
+    const validKind =
+      obj?.kind === "image" || obj?.kind === "file" || obj?.kind === "audio" || obj?.kind === "video";
+    if (
+      !obj ||
+      !validKind ||
+      typeof obj.url !== "string" ||
+      typeof obj.name !== "string" ||
+      typeof obj.mime !== "string" ||
+      typeof obj.size !== "number"
+    ) {
+      throw new ClawlingApiError(
+        "api",
+        "invalid upload response: missing required media fields",
+        { path },
+      );
+    }
+    return obj as UploadResult;
+  }
+
+  function assertNonBlankId(value: string, label: string): void {
+    if (!value.trim()) {
+      throw new ClawlingApiError("validation", `${label} is required`);
+    }
+  }
+
+  function pickPatch<T extends object>(
+    patch: Record<string, unknown>,
+    keys: readonly (keyof T & string)[],
+    label: string,
+  ): T {
+    const body: Record<string, unknown> = {};
+    for (const key of keys) {
+      if (Object.prototype.hasOwnProperty.call(patch, key) && patch[key] !== undefined) {
+        body[key] = patch[key];
+      }
+    }
+    if (Object.keys(body).length === 0) {
+      throw new ClawlingApiError("validation", `${label} patch must include at least one mutable field`);
+    }
+    return body as T;
+  }
+
   // All JSON API endpoints live under `/v1/...`. Media upload is the one
   // intentional exception — the upstream server mounts it at `/media/upload`
   // without the version prefix.
@@ -180,15 +235,32 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
     async getMyProfile(): Promise<Profile> {
       return await call<Profile>("GET", "/v1/users/me");
     },
+    async getAgentProfile(agentId: string): Promise<{ agent: AgentProfile }> {
+      return await call<{ agent: AgentProfile }>("GET", `/v1/agents/${encodeURIComponent(agentId)}`);
+    },
+    async getAgentDetail(agentId: string): Promise<{ agent: AgentProfile }> {
+      return await call<{ agent: AgentProfile }>("GET", `/v1/agents/${encodeURIComponent(agentId)}`);
+    },
+    async patchAgent(agentId: string, patch: AgentMetadataPatch): Promise<{ agent: AgentProfile }> {
+      assertNonBlankId(agentId, "patchAgent: agentId");
+      const body = pickPatch<AgentMetadataPatch>(
+        patch as Record<string, unknown>,
+        ["nickname", "avatar_url", "bio", "behavior"],
+        "patchAgent",
+      );
+      return await call<{ agent: AgentProfile }>("PATCH", `/v1/agents/${encodeURIComponent(agentId)}`, {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json" },
+      });
+    },
     async getUserInfo(userId: string): Promise<Profile> {
       return await call<Profile>("GET", `/v1/users/${encodeURIComponent(userId)}`);
     },
-    async listFriends(params): Promise<FriendList> {
-      const sp = new URLSearchParams();
-      if (typeof params.page === "number") sp.set("page", String(params.page));
-      if (typeof params.pageSize === "number") sp.set("pageSize", String(params.pageSize));
-      const q = sp.toString();
-      return await call<FriendList>("GET", q ? `/v1/friends?${q}` : "/v1/friends");
+    async getUserProfile(userId: string): Promise<Profile> {
+      return await call<Profile>("GET", `/v1/users/${encodeURIComponent(userId)}`);
+    },
+    async listFriends(): Promise<FriendList> {
+      return await call<FriendList>("GET", "/v1/friendships");
     },
     async searchUsers(params): Promise<{ users: UserSearchHit[] }> {
       const sp = new URLSearchParams();
@@ -255,13 +327,42 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments/${encodeURIComponent(String(params.commentId))}`,
       );
     },
+    async listConversations(params): Promise<ConversationListResult> {
+      const sp = new URLSearchParams();
+      if (typeof params.before === "string") sp.set("before", params.before);
+      if (typeof params.limit === "number") sp.set("limit", String(params.limit));
+      const q = sp.toString();
+      return await call<ConversationListResult>(
+        "GET",
+        q ? `/v1/conversations?${q}` : "/v1/conversations",
+      );
+    },
+    async getConversation(conversationId): Promise<{ conversation: ConversationDetails }> {
+      return await call<{ conversation: ConversationDetails }>(
+        "GET",
+        `/v1/conversations/${encodeURIComponent(conversationId)}`,
+      );
+    },
+    async patchConversation(
+      conversationId: string,
+      patch: ConversationMetadataPatch,
+    ): Promise<{ conversation: ConversationDetails }> {
+      assertNonBlankId(conversationId, "patchConversation: conversationId");
+      const body = pickPatch<ConversationMetadataPatch>(
+        patch as Record<string, unknown>,
+        ["title", "description"],
+        "patchConversation",
+      );
+      return await call<{ conversation: ConversationDetails }>(
+        "PATCH",
+        `/v1/conversations/${encodeURIComponent(conversationId)}`,
+        {
+          body: JSON.stringify(body),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
     async updateMyProfile(patch): Promise<Profile> {
-      if (!opts.userId?.trim()) {
-        throw new ClawlingApiError(
-          "validation",
-          "updateMyProfile: userId is required to target /v1/agents/{userId}",
-        );
-      }
       return await call<Profile>(
         "PATCH",
         `/v1/users/me`,
@@ -300,9 +401,10 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       });
       const fd = new FormData();
       fd.set("file", file);
-      return await call<UploadResult>("POST", "/media/upload", { body: fd });
+      const data = await call<unknown>("POST", "/media/upload", { body: fd });
+      return parseUploadResult(data, "/media/upload");
     },
-    async uploadAvatar(params): Promise<UploadResult> {
+    async uploadAvatar(params): Promise<AvatarUploadResult> {
       const blob = new Blob([new Uint8Array(params.buffer)], {
         type: params.mime ?? "application/octet-stream",
       });
@@ -311,7 +413,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       });
       const fd = new FormData();
       fd.set("file", file);
-      return await call<UploadResult>("POST", "/v1/files/upload-url", { body: fd });
+      return await call<AvatarUploadResult>("POST", "/v1/files/upload-url", { body: fd });
     },
   };
 }

package/src/api-types.test-d.ts

@@ -0,0 +1,12 @@
+import type { ConversationListItem } from "./api-types.ts";
+
+const listItemWithSoftDeletedPeer: ConversationListItem = {
+  id: "cnv_1",
+  type: "direct",
+  title: "Deleted peer",
+  created_at: "2026-05-20T00:00:00Z",
+  updated_at: "2026-05-20T00:01:00Z",
+  peer: null,
+};
+
+void listItemWithSoftDeletedPeer;