@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/api-client.test.ts

@@ -0,0 +1,827 @@
+import { describe, expect, it, vi } from "vitest";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { ClawlingApiError } from "./api-types.ts";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("clawchat-plugin-openclaw api-client", () => {
+  it("getMyProfile sends GET /me with bearer token and unwraps data", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { user_id: "u1", display_name: "Alice" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+
+    const profile = await client.getMyProfile();
+
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "https://api.example.com/v1/users/me",
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          authorization: "Bearer tk",
+          // Global X-Device-Id is sent on every request, not just connect.
+          "x-device-id": "clawchat-plugin-openclaw",
+        }),
+      }),
+    );
+    expect(profile).toEqual({ user_id: "u1", display_name: "Alice" });
+  });
+
+  it("getUserInfo url-encodes the userId", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        jsonResponse({ code: 0, message: "ok", data: { user_id: "u/2", display_name: "Bob" } }),
+      );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.getUserInfo("u/2");
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/u%2F2");
+  });
+
+  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: { agent: { user_id: "agt/1", owner_id: "owner", type: "agent" } },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+
+    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 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",
+        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",
+      });
+      expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+      expect(result.agent.nickname).toBe("OpenClaw Bot");
+    });
+
+    it("updateAgentBehavior patches current agent behavior through /v1/agents/me/behavior", async () => {
+      const fetchImpl = vi.fn().mockResolvedValue(
+        jsonResponse({
+          code: 0,
+          message: "ok",
+          data: {
+            agent: {
+              id: "agt/1",
+              owner_id: "owner",
+              user_id: "agent-user",
+              behavior: "Act clearly.",
+            },
+          },
+        }),
+      );
+      const client = createOpenclawClawlingApiClient({
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        fetchImpl,
+      });
+
+      const result = await client.updateAgentBehavior("Act clearly.");
+
+      expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/agents/me/behavior");
+      const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+      expect(init.method).toBe("PATCH");
+      expect(JSON.parse(init.body as string)).toEqual({ behavior: "Act clearly." });
+      expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+      expect(result.agent.behavior).toBe("Act clearly.");
+    });
+
+    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 () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { users: [{ id: "u1", nickname: "Alice", type: "user" }] },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.searchUsers({ q: "alice", limit: 20 });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/users/search?q=alice&limit=20",
+    );
+    expect(result.users[0]!.nickname).toBe("Alice");
+  });
+
+  it("listMoments sends before + limit as query string", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { moments: [{ id: 122, author_id: "u1", created_at: "2026-05-15T00:00:00Z" }] },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.listMoments({ before: 123, limit: 30 });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/moments?before=123&limit=30",
+    );
+  });
+
+  it("createMoment POSTs text and image URLs", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { moment: { id: 1, author_id: "u1", text: "hello", created_at: "now" } },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.createMoment({ text: "hello", images: ["https://cdn/a.png"] });
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/moments");
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      text: "hello",
+      images: ["https://cdn/a.png"],
+    });
+  });
+
+  it("deleteMoment sends DELETE /moments/{id}", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ code: 0, message: "ok", data: { ok: true } }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.deleteMoment(123);
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/moments/123");
+    expect((fetchImpl.mock.calls[0]![1] as RequestInit).method).toBe("DELETE");
+  });
+
+  it("toggleMomentReaction POSTs emoji body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { reactions: [{ emoji: "👍", count: 1, mine: true }] },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.toggleMomentReaction({ momentId: 123, emoji: "👍" });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/moments/123/reactions",
+    );
+    expect(JSON.parse((fetchImpl.mock.calls[0]![1] as RequestInit).body as string)).toEqual({
+      emoji: "👍",
+    });
+  });
+
+  it("createMomentComment and replyMomentComment POST expected bodies", async () => {
+    const fetchImpl = vi.fn().mockImplementation(() =>
+      Promise.resolve(
+        jsonResponse({
+          code: 0,
+          message: "ok",
+          data: { comment: { id: 456, author_id: "u1", text: "nice", created_at: "now" } },
+        }),
+      ),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.createMomentComment({ momentId: 123, text: "nice" });
+    await client.replyMomentComment({ momentId: 123, replyToCommentId: 456, text: "yes" });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/moments/123/comments",
+    );
+    expect(JSON.parse((fetchImpl.mock.calls[0]![1] as RequestInit).body as string)).toEqual({
+      text: "nice",
+    });
+    expect(JSON.parse((fetchImpl.mock.calls[1]![1] as RequestInit).body as string)).toEqual({
+      text: "yes",
+      reply_to_comment_id: 456,
+    });
+  });
+
+  it("deleteMomentComment sends DELETE /moments/{id}/comments/{cid}", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ code: 0, message: "ok", data: { ok: true } }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.deleteMomentComment({ momentId: 123, commentId: 456 });
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      "https://api.example.com/v1/moments/123/comments/456",
+    );
+    expect((fetchImpl.mock.calls[0]![1] as RequestInit).method).toBe("DELETE");
+  });
+
+  it("updateMyProfile sends PATCH /me with JSON body without requiring configured userId", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { user_id: "u1", display_name: "Alice2" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.updateMyProfile({ display_name: "Alice2" });
+    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({ display_name: "Alice2" });
+    expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+  });
+
+  it("updateMyProfile forwards bio in the JSON body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { user_id: "u1", bio: "hello there" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      userId: "agent-1",
+      fetchImpl,
+    });
+    await client.updateMyProfile({ bio: "hello there" });
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(JSON.parse(init.body as string)).toEqual({ bio: "hello there" });
+  });
+
+  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,
+    });
+    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 () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { kind: "image", url: "https://cdn/x.png", name: "x.png", size: 12, mime: "image/png" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.uploadMedia({
+      buffer: Buffer.from("hi-bytes-12!"),
+      filename: "x.png",
+      mime: "image/png",
+    });
+    // uploadMedia intentionally targets `/media/upload` WITHOUT the `/v1`
+    // prefix — the upstream mount is unversioned.
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/media/upload");
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("POST");
+    expect(init.body).toBeInstanceOf(FormData);
+    const fd = init.body as FormData;
+    const file = fd.get("file") as File;
+    expect(file).toBeInstanceOf(File);
+    expect(file.name).toBe("x.png");
+    expect(file.type).toBe("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 () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        message: "ok",
+        data: { url: "https://cdn/avatars/a.png", size: 99, mime: "image/png" },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.uploadAvatar({
+      buffer: Buffer.from("avatar-bytes-12"),
+      filename: "avatar.png",
+      mime: "image/png",
+    });
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/files/upload-url");
+    const init = fetchImpl.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("POST");
+    expect(init.body).toBeInstanceOf(FormData);
+    const fd = init.body as FormData;
+    const file = fd.get("file") as File;
+    expect(file).toBeInstanceOf(File);
+    expect(file.name).toBe("avatar.png");
+    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("clawchat-plugin-openclaw");
+    expect(result).not.toHaveProperty("kind");
+    expect(result).not.toHaveProperty("name");
+    expect(result).toEqual({ url: "https://cdn/avatars/a.png", size: 99, mime: "image/png" });
+  });
+
+  it("agentsConnect POSTs /agents/connect with { code, platform, type } body", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        code: 0,
+        msg: "ok",
+        data: {
+          agent: {
+            id: "ag-1",
+            owner_id: "owner-1",
+            user_id: "agent-1",
+            type: "bot",
+            nickname: "Bot",
+            avatar_url: "",
+            bio: "",
+            visibility: "public",
+            status: "active",
+            platform: "openclaw",
+            created_at: "2026-04-17T00:00:00Z",
+          },
+          access_token: "tk-access",
+          refresh_token: "tk-refresh",
+        },
+      }),
+    );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    const result = await client.agentsConnect({
+      code: "INV-1",
+      platform: "openclaw",
+      type: "bot",
+    });
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "https://api.example.com/v1/agents/connect",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          authorization: "Bearer tk",
+          "content-type": "application/json",
+          // Fixed device id — pins the issued credentials to this plugin.
+          "x-device-id": "clawchat-plugin-openclaw",
+        }),
+        body: JSON.stringify({ code: "INV-1", platform: "openclaw", type: "bot" }),
+      }),
+    );
+    expect(result.agent.user_id).toBe("agent-1");
+    expect(result.access_token).toBe("tk-access");
+    expect(result.refresh_token).toBe("tk-refresh");
+  });
+
+  it("agentsConnect rejects empty invite code / platform / type locally", async () => {
+    const fetchImpl = vi.fn();
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(
+      client.agentsConnect({ code: "   ", platform: "openclaw", type: "bot" }),
+    ).rejects.toMatchObject({ kind: "validation" });
+    await expect(
+      client.agentsConnect({ code: "INV", platform: "", type: "bot" }),
+    ).rejects.toMatchObject({ kind: "validation" });
+    await expect(
+      client.agentsConnect({ code: "INV", platform: "openclaw", type: "" }),
+    ).rejects.toMatchObject({ kind: "validation" });
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("throws ClawlingApiError(api) on code !== 0", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ code: 4001, message: "user not found", data: null }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getUserInfo("missing")).rejects.toMatchObject({
+      kind: "api",
+      message: "user not found",
+      meta: expect.objectContaining({ code: 4001 }),
+    });
+  });
+
+  it("throws ClawlingApiError(auth) on 401", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(new Response("unauthorized", { status: 401 }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getMyProfile()).rejects.toMatchObject({
+      kind: "auth",
+      meta: expect.objectContaining({ status: 401 }),
+    });
+  });
+
+  it("throws ClawlingApiError(transport) on 500", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(new Response("internal error", { status: 500 }));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getMyProfile()).rejects.toMatchObject({
+      kind: "transport",
+      meta: expect.objectContaining({ status: 500 }),
+    });
+  });
+
+  it("throws ClawlingApiError(transport) when fetch itself rejects", async () => {
+    const fetchImpl = vi.fn().mockRejectedValue(new Error("ENETDOWN"));
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com",
+      token: "tk",
+      fetchImpl,
+    });
+    await expect(client.getMyProfile()).rejects.toMatchObject({
+      kind: "transport",
+      message: expect.stringContaining("ENETDOWN"),
+    });
+  });
+
+  it("strips trailing slash from baseUrl", async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        jsonResponse({ code: 0, message: "ok", data: { user_id: "u1", display_name: "A" } }),
+      );
+    const client = createOpenclawClawlingApiClient({
+      baseUrl: "https://api.example.com/",
+      token: "tk",
+      fetchImpl,
+    });
+    await client.getMyProfile();
+    expect(fetchImpl.mock.calls[0]![0]).toBe("https://api.example.com/v1/users/me");
+  });
+
+  it("rejects baseUrl without http(s) scheme", () => {
+    expect(() =>
+      createOpenclawClawlingApiClient({
+        baseUrl: "ftp://wrong.example.com",
+        token: "tk",
+      }),
+    ).toThrow(ClawlingApiError);
+  });
+});