@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/src/api-client.ts

@@ -1,20 +1,23 @@
 import {
   ClawlingApiError,
   type AgentConnectResult,
+  type AvatarUploadResult,
+  type ConversationDetails,
+  type ConversationListResult,
   type FriendList,
+  type MomentComment,
+  type MomentReaction,
+  type MomentView,
   type Profile,
   type UploadResult,
+  type UserSearchHit,
 } from "./api-types.ts";
 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;
@@ -23,7 +26,27 @@ export interface ApiClientOptions {
 export interface OpenclawClawlingApiClient {
   getMyProfile(): Promise<Profile>;
   getUserInfo(userId: string): Promise<Profile>;
-  listFriends(params: { page?: number; pageSize?: number }): Promise<FriendList>;
+  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 }>;
+  deleteMoment(momentId: number): Promise<{ ok: boolean }>;
+  toggleMomentReaction(params: {
+    momentId: number;
+    emoji: string;
+  }): Promise<{ reactions: MomentReaction[] }>;
+  createMomentComment(params: {
+    momentId: number;
+    text: string;
+  }): Promise<{ comment: MomentComment }>;
+  replyMomentComment(params: {
+    momentId: number;
+    replyToCommentId: number;
+    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 }>;
   updateMyProfile(patch: { nickname?: string; avatar_url?: string; bio?: string }): Promise<Profile>;
   uploadMedia(params: { buffer: Buffer; filename: string; mime?: string }): Promise<UploadResult>;
   /**
@@ -39,15 +62,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 {
@@ -151,6 +173,27 @@ 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;
+  }
+
   // 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.
@@ -161,20 +204,91 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
     async getUserInfo(userId: string): Promise<Profile> {
       return await call<Profile>("GET", `/v1/users/${encodeURIComponent(userId)}`);
     },
-    async listFriends(params): Promise<FriendList> {
+    async listFriends(): Promise<FriendList> {
+      return await call<FriendList>("GET", "/v1/friendships");
+    },
+    async searchUsers(params): Promise<{ users: UserSearchHit[] }> {
       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));
+      if (typeof params.q === "string") sp.set("q", params.q);
+      if (typeof params.limit === "number") sp.set("limit", String(params.limit));
       const q = sp.toString();
-      return await call<FriendList>("GET", q ? `/v1/friends?${q}` : "/v1/friends");
+      return await call<{ users: UserSearchHit[] }>(
+        "GET",
+        q ? `/v1/users/search?${q}` : "/v1/users/search",
+      );
+    },
+    async listMoments(params): Promise<{ moments: MomentView[] }> {
+      const sp = new URLSearchParams();
+      if (typeof params.before === "number") sp.set("before", String(params.before));
+      if (typeof params.limit === "number") sp.set("limit", String(params.limit));
+      const q = sp.toString();
+      return await call<{ moments: MomentView[] }>("GET", q ? `/v1/moments?${q}` : "/v1/moments");
+    },
+    async createMoment(body): Promise<{ moment: MomentView }> {
+      return await call<{ moment: MomentView }>("POST", "/v1/moments", {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json" },
+      });
+    },
+    async deleteMoment(momentId): Promise<{ ok: boolean }> {
+      return await call<{ ok: boolean }>("DELETE", `/v1/moments/${encodeURIComponent(String(momentId))}`);
+    },
+    async toggleMomentReaction(params): Promise<{ reactions: MomentReaction[] }> {
+      return await call<{ reactions: MomentReaction[] }>(
+        "POST",
+        `/v1/moments/${encodeURIComponent(String(params.momentId))}/reactions`,
+        {
+          body: JSON.stringify({ emoji: params.emoji }),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
+    async createMomentComment(params): Promise<{ comment: MomentComment }> {
+      return await call<{ comment: MomentComment }>(
+        "POST",
+        `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments`,
+        {
+          body: JSON.stringify({ text: params.text }),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
+    async replyMomentComment(params): Promise<{ comment: MomentComment }> {
+      return await call<{ comment: MomentComment }>(
+        "POST",
+        `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments`,
+        {
+          body: JSON.stringify({
+            text: params.text,
+            reply_to_comment_id: params.replyToCommentId,
+          }),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
+    async deleteMomentComment(params): Promise<{ ok: boolean }> {
+      return await call<{ ok: boolean }>(
+        "DELETE",
+        `/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 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`,
@@ -213,9 +327,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",
       });
@@ -224,7 +339,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;

package/src/api-types.ts

@@ -14,18 +14,99 @@ export interface Profile {
 }
 
 export interface FriendList {
-  items: Profile[];
-  total?: number;
-  page: number;
-  pageSize: number;
+  friends: Profile[];
+}
+
+export interface UserSearchHit {
+  avatar_url?: string;
+  id: string;
+  nickname?: string;
+  type?: string;
+}
+
+export interface MomentReaction {
+  count: number;
+  emoji: string;
+  mine: boolean;
+}
+
+export interface MomentComment {
+  author_id: string;
+  created_at: string;
+  id: number;
+  reply_to_author_id?: string;
+  reply_to_comment_id?: number;
+  text: string;
+}
+
+export interface MomentView {
+  author_id: string;
+  comments?: MomentComment[];
+  comments_total?: number;
+  created_at: string;
+  id: number;
+  images?: string[];
+  reactions?: MomentReaction[];
+  text?: string;
 }
 
 export interface UploadResult {
+  kind: "image" | "file" | "audio" | "video";
+  url: string;
+  name: string;
+  size: number;
+  mime: string;
+}
+
+export interface AvatarUploadResult {
   url: string;
   size: number;
   mime: string;
 }
 
+export interface ConversationPeerView {
+  id: string;
+  type: string;
+  nickname: string;
+  avatar_url: string;
+  [key: string]: unknown;
+}
+
+export interface ConversationListItem {
+  id: string;
+  type: string;
+  title: string;
+  created_at: string;
+  updated_at: string;
+  peer: ConversationPeerView | null;
+  [key: string]: unknown;
+}
+
+export interface ConversationParticipant {
+  conversation_id: string;
+  user_id: string;
+  role: string;
+  joined_at: string;
+  [key: string]: unknown;
+}
+
+export interface ConversationDetails {
+  id: string;
+  type: string;
+  title: string;
+  creator_id: string;
+  created_at: string;
+  updated_at: string;
+  participants: ConversationParticipant[];
+  [key: string]: unknown;
+}
+
+export interface ConversationListResult {
+  conversations: ConversationListItem[];
+  next_before?: string;
+  [key: string]: unknown;
+}
+
 export interface AgentProfile {
   id: string;
   owner_id: string;
@@ -40,6 +121,10 @@ export interface AgentProfile {
   created_at: string;
 }
 
+export interface AgentConnectConversation {
+  id: string;
+}
+
 /**
  * Response payload for `POST /v1/agents/connect` — the endpoint that exchanges
  * an invite code for the credentials this account uses to open the
@@ -51,6 +136,7 @@ export interface AgentConnectResult {
   agent: AgentProfile;
   access_token: string;
   refresh_token: string;
+  conversation?: AgentConnectConversation;
 }
 
 export type ClawlingApiErrorKind =

package/src/buffered-stream.test.ts

@@ -1,4 +1,4 @@
-import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import type { ClawlingChatClient } from "./ws-client.ts";
 import { describe, expect, it, vi } from "vitest";
 import { mergeStreamingText, openBufferedStreamingSession } from "./buffered-stream.ts";
 
@@ -46,7 +46,7 @@ describe("openBufferedStreamingSession", () => {
     openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 50,
       minChunkChars: 4,
@@ -62,7 +62,7 @@ describe("openBufferedStreamingSession", () => {
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 4,
@@ -86,7 +86,7 @@ describe("openBufferedStreamingSession", () => {
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 1,
@@ -111,7 +111,7 @@ describe("openBufferedStreamingSession", () => {
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 999,
@@ -138,7 +138,7 @@ describe("openBufferedStreamingSession", () => {
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 999,
@@ -150,12 +150,12 @@ describe("openBufferedStreamingSession", () => {
     expect(doneCount).toBe(1);
   });
 
-  it("fail() emits message.failed with reason and typing(false)", async () => {
+  it("fail() emits message.failed with StreamDonePayload shape and typing(false)", async () => {
     const { client, sent, typing } = mockClient();
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 999,
@@ -163,8 +163,10 @@ describe("openBufferedStreamingSession", () => {
     });
     await session.fail("boom");
     const failed = sent.find((s) => s.event === "message.failed")!;
-    expect(failed.payload.reason).toBe("boom");
-    expect(failed.payload.sequence).toBe(0);
+    expect(failed.payload).not.toHaveProperty("reason");
+    expect(failed.payload).not.toHaveProperty("sequence");
+    expect((failed.payload.streaming as { sequence: number }).sequence).toBe(0);
+    expect(failed.payload.fragments).toEqual([{ kind: "text", text: "boom" }]);
     expect(failed.payload).toHaveProperty("completed_at");
     expect(failed.payload).not.toHaveProperty("failed_at");
     expect(typing.at(-1)).toEqual(["u1", false]);
@@ -176,7 +178,7 @@ describe("openBufferedStreamingSession", () => {
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 1,
@@ -194,7 +196,7 @@ describe("openBufferedStreamingSession", () => {
     const session = openBufferedStreamingSession({
       client,
       to: { id: "u1", type: "direct" },
-      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      sender: { id: "a1", type: "direct", nick_name: "Bot" },
       messageId: "m1",
       flushIntervalMs: 60_000,
       minChunkChars: 1,

package/src/buffered-stream.ts

@@ -1,4 +1,4 @@
-import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import type { ClawlingChatClient } from "./ws-client.ts";
 import {
   emitStreamAdd,
   emitStreamCreated,