@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/api-client.ts

@@ -0,0 +1,414 @@
+import {
+  ClawlingApiError,
+  type AgentMetadataPatch,
+  type AgentProfile,
+  type AgentConnectResult,
+  type AvatarUploadResult,
+  type ConversationDetails,
+  type ConversationMetadataPatch,
+  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`, used by WebSocket setup but not REST `/me` calls. */
+  userId?: string;
+  /** Test override only. Defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+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 }>;
+  updateAgentBehavior(behavior: string): Promise<{ agent: AgentProfile }>;
+  getUserInfo(userId: string): Promise<Profile>;
+  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 }>;
+  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 }>;
+  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>;
+  /**
+   * Exchange an invite code for an agent token.
+   * Request body shape: `{ code, platform, type }`.
+   */
+  agentsConnect(params: {
+    /** The invite code entered by the operator. */
+    code: string;
+    /** Platform the agent is attaching from (e.g. "openclaw"). */
+    platform: string;
+    /** Agent type tag (e.g. "bot"). */
+    type: string;
+  }): Promise<AgentConnectResult>;
+  /**
+   * 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<AvatarUploadResult>;
+}
+
+export function createOpenclawClawlingApiClient(opts: ApiClientOptions): OpenclawClawlingApiClient {
+  if (!/^https?:\/\//i.test(opts.baseUrl)) {
+    throw new ClawlingApiError(
+      "validation",
+      `clawchat-plugin-openclaw baseUrl must start with http:// or https:// (got "${opts.baseUrl}")`,
+    );
+  }
+  const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+
+  function url(path: string): string {
+    return `${baseUrl}${path}`;
+  }
+
+  function authHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    // `X-Device-Id` is sent on every request so the server can correlate
+    // activity back to this plugin instance. Callers may override via
+    // `extra` (e.g. tests) but the default is the channel id.
+    return {
+      authorization: `Bearer ${opts.token}`,
+      "x-device-id": CHANNEL_ID,
+      ...extra,
+    };
+  }
+
+  async function readEnvelope<T>(res: Response, path: string): Promise<T> {
+    if (res.status === 401 || res.status === 403) {
+      throw new ClawlingApiError("auth", `unauthorized (status ${res.status})`, {
+        status: res.status,
+        path,
+      });
+    }
+    if (!res.ok) {
+      const snippet = await res.text().catch(() => "");
+      throw new ClawlingApiError("transport", `http ${res.status} ${snippet.slice(0, 200)}`, {
+        status: res.status,
+        path,
+      });
+    }
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch (err) {
+      throw new ClawlingApiError(
+        "transport",
+        `non-JSON response: ${err instanceof Error ? err.message : String(err)}`,
+        { status: res.status, path },
+      );
+    }
+    // Unified envelope: `{ code: number, msg: string, data: T }`.
+    // `code === 0` means success; any other value is a business error whose
+    // `msg` is surfaced to callers and `code` is preserved on the error meta.
+    const env = parsed as { code?: unknown; msg?: unknown; message?: unknown; data?: T };
+    const code = typeof env.code === "number" ? env.code : Number.NaN;
+    const msg =
+      typeof env.msg === "string"
+        ? env.msg
+        : typeof env.message === "string"
+          ? env.message
+          : "";
+    if (!Number.isFinite(code)) {
+      throw new ClawlingApiError("transport", "invalid envelope: missing numeric `code`", {
+        status: res.status,
+        path,
+      });
+    }
+    if (code !== 0) {
+      throw new ClawlingApiError("api", msg || `code=${code}`, {
+        code,
+        status: res.status,
+        path,
+      });
+    }
+    return env.data as T;
+  }
+
+  async function call<T>(
+    method: string,
+    path: string,
+    init?: { body?: unknown; headers?: Record<string, string> },
+  ): Promise<T> {
+    let res: Response;
+    try {
+      const requestInit: RequestInit = {
+        method,
+        headers: authHeaders(init?.headers),
+      };
+      if (init?.body !== undefined) {
+        requestInit.body = init.body as BodyInit;
+      }
+      res = await fetchImpl(url(path), requestInit);
+    } catch (err) {
+      throw new ClawlingApiError(
+        "transport",
+        `fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        { path },
+      );
+    }
+    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.
+  return {
+    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"],
+        "patchAgent",
+      );
+      return await call<{ agent: AgentProfile }>("PATCH", `/v1/agents/${encodeURIComponent(agentId)}`, {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json" },
+      });
+    },
+    async updateAgentBehavior(behavior: string): Promise<{ agent: AgentProfile }> {
+      return await call<{ agent: AgentProfile }>("PATCH", "/v1/agents/me/behavior", {
+        body: JSON.stringify({ behavior }),
+        headers: { "content-type": "application/json" },
+      });
+    },
+    async getUserInfo(userId: string): Promise<Profile> {
+      return await call<Profile>("GET", `/v1/users/${encodeURIComponent(userId)}`);
+    },
+    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();
+      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<{ 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 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> {
+      return await call<Profile>(
+        "PATCH",
+        `/v1/users/me`,
+        {
+          body: JSON.stringify(patch),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
+    async agentsConnect({ code: inviteCode, platform, type }): Promise<AgentConnectResult> {
+      if (!inviteCode?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnect: inviteCode is required");
+      }
+      if (!platform?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnect: platform is required");
+      }
+      if (!type?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnect: type is required");
+      }
+      return await call<AgentConnectResult>("POST", "/v1/agents/connect", {
+        // `X-Device-Id` is added globally via `authHeaders` on every request.
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          code: inviteCode.trim(),
+          platform: platform.trim(),
+          type: type.trim(),
+        }),
+      });
+    },
+    async uploadMedia(params): Promise<UploadResult> {
+      const blob = new Blob([new Uint8Array(params.buffer)], {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const file = new File([blob], params.filename, {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const fd = new FormData();
+      fd.set("file", file);
+      const data = await call<unknown>("POST", "/media/upload", { body: fd });
+      return parseUploadResult(data, "/media/upload");
+    },
+    async uploadAvatar(params): Promise<AvatarUploadResult> {
+      const blob = new Blob([new Uint8Array(params.buffer)], {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const file = new File([blob], params.filename, {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const fd = new FormData();
+      fd.set("file", file);
+      return await call<AvatarUploadResult>("POST", "/v1/files/upload-url", { body: fd });
+    },
+  };
+}

package/src/api-types.ts

@@ -0,0 +1,146 @@
+/**
+ * Public-facing types for the Clawling Chat HTTP API.
+ *
+ * Field names mirror the upstream API (snake_case) so we don't lose
+ * fidelity on responses. Tool schemas accept camelCase externally and
+ * translate at the api-client boundary.
+ */
+
+export interface Profile {
+  id: string;
+  type?: string;
+  nickname?: string;
+  avatar_url?: string;
+  bio?: string;
+}
+
+export interface FriendList {
+  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 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 ConversationMetadataPatch {
+  title?: string;
+  description?: string;
+}
+
+export interface AgentProfile {
+  id: string;
+  owner_id: string;
+  user_id: string;
+  type: string;
+  nickname: string;
+  avatar_url: string;
+  bio: string;
+  behavior?: string;
+  visibility: string;
+  status: string;
+  platform: string;
+  created_at: string;
+}
+
+export interface AgentMetadataPatch {
+  nickname?: string;
+  avatar_url?: string;
+  bio?: 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
+ * streaming WebSocket. `access_token` is the bearer this agent uses for
+ * API + WebSocket auth; `agent.user_id` is the stable id the streaming
+ * protocol routes on.
+ */
+export interface AgentConnectResult {
+  agent: AgentProfile;
+  access_token: string;
+  refresh_token: string;
+  conversation?: AgentConnectConversation;
+}
+
+export type ClawlingApiErrorKind =
+  | "auth" // 401 / 403 — token bad or expired
+  | "api" // server-returned non-zero `code`
+  | "transport" // network failure / 5xx / non-JSON body
+  | "validation"; // local pre-check failure (e.g., file too large)
+
+export class ClawlingApiError extends Error {
+  constructor(
+    public readonly kind: ClawlingApiErrorKind,
+    message: string,
+    public readonly meta?: { code?: number; status?: number; path?: string },
+  ) {
+    super(message);
+    this.name = "ClawlingApiError";
+  }
+}