@archipelagolab/lobi 1.0.0

package/src/matrix/profile.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  isSupportedMatrixAvatarSource,
+  syncMatrixOwnProfile,
+  type MatrixProfileSyncResult,
+} from "./profile.js";
+
+function createClientStub() {
+  return {
+    getUserProfile: vi.fn(async () => ({})),
+    setDisplayName: vi.fn(async () => {}),
+    setAvatarUrl: vi.fn(async () => {}),
+    uploadContent: vi.fn(async () => "mxc://example/avatar"),
+  };
+}
+
+function expectNoUpdates(result: MatrixProfileSyncResult) {
+  expect(result.displayNameUpdated).toBe(false);
+  expect(result.avatarUpdated).toBe(false);
+}
+
+describe("matrix profile sync", () => {
+  it("skips when no desired profile values are provided", async () => {
+    const client = createClientStub();
+    const result = await syncMatrixOwnProfile({
+      client,
+      userId: "@bot:example.org",
+    });
+
+    expect(result.skipped).toBe(true);
+    expectNoUpdates(result);
+    expect(result.uploadedAvatarSource).toBeNull();
+    expect(client.setDisplayName).not.toHaveBeenCalled();
+    expect(client.setAvatarUrl).not.toHaveBeenCalled();
+  });
+
+  it("updates display name when desired name differs", async () => {
+    const client = createClientStub();
+    client.getUserProfile.mockResolvedValue({
+      displayname: "Old Name",
+      avatar_url: "mxc://example/existing",
+    });
+
+    const result = await syncMatrixOwnProfile({
+      client,
+      userId: "@bot:example.org",
+      displayName: "New Name",
+    });
+
+    expect(result.skipped).toBe(false);
+    expect(result.displayNameUpdated).toBe(true);
+    expect(result.avatarUpdated).toBe(false);
+    expect(result.uploadedAvatarSource).toBeNull();
+    expect(client.setDisplayName).toHaveBeenCalledWith("New Name");
+  });
+
+  it("does not update when name and avatar already match", async () => {
+    const client = createClientStub();
+    client.getUserProfile.mockResolvedValue({
+      displayname: "Bot",
+      avatar_url: "mxc://example/avatar",
+    });
+
+    const result = await syncMatrixOwnProfile({
+      client,
+      userId: "@bot:example.org",
+      displayName: "Bot",
+      avatarUrl: "mxc://example/avatar",
+    });
+
+    expect(result.skipped).toBe(false);
+    expectNoUpdates(result);
+    expect(client.setDisplayName).not.toHaveBeenCalled();
+    expect(client.setAvatarUrl).not.toHaveBeenCalled();
+  });
+
+  it("converts http avatar URL by uploading and then updates profile avatar", async () => {
+    const client = createClientStub();
+    client.getUserProfile.mockResolvedValue({
+      displayname: "Bot",
+      avatar_url: "mxc://example/old",
+    });
+    client.uploadContent.mockResolvedValue("mxc://example/new-avatar");
+    const loadAvatarFromUrl = vi.fn(async () => ({
+      buffer: Buffer.from("avatar-bytes"),
+      contentType: "image/png",
+      fileName: "avatar.png",
+    }));
+
+    const result = await syncMatrixOwnProfile({
+      client,
+      userId: "@bot:example.org",
+      avatarUrl: "https://cdn.example.org/avatar.png",
+      loadAvatarFromUrl,
+    });
+
+    expect(result.convertedAvatarFromHttp).toBe(true);
+    expect(result.uploadedAvatarSource).toBe("http");
+    expect(result.resolvedAvatarUrl).toBe("mxc://example/new-avatar");
+    expect(result.avatarUpdated).toBe(true);
+    expect(loadAvatarFromUrl).toHaveBeenCalledWith(
+      "https://cdn.example.org/avatar.png",
+      10 * 1024 * 1024,
+    );
+    expect(client.setAvatarUrl).toHaveBeenCalledWith("mxc://example/new-avatar");
+  });
+
+  it("uploads avatar media from a local path and then updates profile avatar", async () => {
+    const client = createClientStub();
+    client.getUserProfile.mockResolvedValue({
+      displayname: "Bot",
+      avatar_url: "mxc://example/old",
+    });
+    client.uploadContent.mockResolvedValue("mxc://example/path-avatar");
+    const loadAvatarFromPath = vi.fn(async () => ({
+      buffer: Buffer.from("avatar-bytes"),
+      contentType: "image/jpeg",
+      fileName: "avatar.jpg",
+    }));
+
+    const result = await syncMatrixOwnProfile({
+      client,
+      userId: "@bot:example.org",
+      avatarPath: "/tmp/avatar.jpg",
+      loadAvatarFromPath,
+    });
+
+    expect(result.convertedAvatarFromHttp).toBe(false);
+    expect(result.uploadedAvatarSource).toBe("path");
+    expect(result.resolvedAvatarUrl).toBe("mxc://example/path-avatar");
+    expect(result.avatarUpdated).toBe(true);
+    expect(loadAvatarFromPath).toHaveBeenCalledWith("/tmp/avatar.jpg", 10 * 1024 * 1024);
+    expect(client.setAvatarUrl).toHaveBeenCalledWith("mxc://example/path-avatar");
+  });
+
+  it("rejects unsupported avatar URL schemes", async () => {
+    const client = createClientStub();
+
+    await expect(
+      syncMatrixOwnProfile({
+        client,
+        userId: "@bot:example.org",
+        avatarUrl: "file:///tmp/avatar.png",
+      }),
+    ).rejects.toThrow("Matrix avatar URL must be an mxc:// URI or an http(s) URL.");
+  });
+
+  it("recognizes supported avatar sources", () => {
+    expect(isSupportedMatrixAvatarSource("mxc://example/avatar")).toBe(true);
+    expect(isSupportedMatrixAvatarSource("https://example.org/avatar.png")).toBe(true);
+    expect(isSupportedMatrixAvatarSource("http://example.org/avatar.png")).toBe(true);
+    expect(isSupportedMatrixAvatarSource("ftp://example.org/avatar.png")).toBe(false);
+  });
+});

package/src/matrix/profile.ts

@@ -0,0 +1,184 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
+import type { MatrixClient } from "./sdk.js";
+
+export const MATRIX_PROFILE_AVATAR_MAX_BYTES = 10 * 1024 * 1024;
+
+type MatrixProfileClient = Pick<
+  MatrixClient,
+  "getUserProfile" | "setDisplayName" | "setAvatarUrl" | "uploadContent"
+>;
+
+type MatrixProfileLoadResult = {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+};
+
+export type MatrixProfileSyncResult = {
+  skipped: boolean;
+  displayNameUpdated: boolean;
+  avatarUpdated: boolean;
+  resolvedAvatarUrl: string | null;
+  uploadedAvatarSource: "http" | "path" | null;
+  convertedAvatarFromHttp: boolean;
+};
+
+export function isMatrixMxcUri(value: string): boolean {
+  return normalizeLowercaseStringOrEmpty(normalizeOptionalString(value)).startsWith("mxc://");
+}
+
+export function isMatrixHttpAvatarUri(value: string): boolean {
+  const normalized = normalizeLowercaseStringOrEmpty(normalizeOptionalString(value));
+  return normalized.startsWith("https://") || normalized.startsWith("http://");
+}
+
+export function isSupportedMatrixAvatarSource(value: string): boolean {
+  return isMatrixMxcUri(value) || isMatrixHttpAvatarUri(value);
+}
+
+async function uploadAvatarMedia(params: {
+  client: MatrixProfileClient;
+  avatarSource: string;
+  avatarMaxBytes: number;
+  loadAvatar: (source: string, maxBytes: number) => Promise<MatrixProfileLoadResult>;
+}): Promise<string> {
+  const media = await params.loadAvatar(params.avatarSource, params.avatarMaxBytes);
+  return await params.client.uploadContent(
+    media.buffer,
+    media.contentType,
+    media.fileName || "avatar",
+  );
+}
+
+async function resolveAvatarUrl(params: {
+  client: MatrixProfileClient;
+  avatarUrl: string | null;
+  avatarPath?: string | null;
+  avatarMaxBytes: number;
+  loadAvatarFromUrl?: (url: string, maxBytes: number) => Promise<MatrixProfileLoadResult>;
+  loadAvatarFromPath?: (path: string, maxBytes: number) => Promise<MatrixProfileLoadResult>;
+}): Promise<{
+  resolvedAvatarUrl: string | null;
+  uploadedAvatarSource: "http" | "path" | null;
+  convertedAvatarFromHttp: boolean;
+}> {
+  const avatarPath = normalizeOptionalString(params.avatarPath) ?? null;
+  if (avatarPath) {
+    if (!params.loadAvatarFromPath) {
+      throw new Error("Matrix avatar path upload requires a media loader.");
+    }
+    return {
+      resolvedAvatarUrl: await uploadAvatarMedia({
+        client: params.client,
+        avatarSource: avatarPath,
+        avatarMaxBytes: params.avatarMaxBytes,
+        loadAvatar: params.loadAvatarFromPath,
+      }),
+      uploadedAvatarSource: "path",
+      convertedAvatarFromHttp: false,
+    };
+  }
+
+  const avatarUrl = normalizeOptionalString(params.avatarUrl) ?? null;
+  if (!avatarUrl) {
+    return {
+      resolvedAvatarUrl: null,
+      uploadedAvatarSource: null,
+      convertedAvatarFromHttp: false,
+    };
+  }
+
+  if (isMatrixMxcUri(avatarUrl)) {
+    return {
+      resolvedAvatarUrl: avatarUrl,
+      uploadedAvatarSource: null,
+      convertedAvatarFromHttp: false,
+    };
+  }
+
+  if (!isMatrixHttpAvatarUri(avatarUrl)) {
+    throw new Error("Matrix avatar URL must be an mxc:// URI or an http(s) URL.");
+  }
+
+  if (!params.loadAvatarFromUrl) {
+    throw new Error("Matrix avatar URL conversion requires a media loader.");
+  }
+
+  return {
+    resolvedAvatarUrl: await uploadAvatarMedia({
+      client: params.client,
+      avatarSource: avatarUrl,
+      avatarMaxBytes: params.avatarMaxBytes,
+      loadAvatar: params.loadAvatarFromUrl,
+    }),
+    uploadedAvatarSource: "http",
+    convertedAvatarFromHttp: true,
+  };
+}
+
+export async function syncMatrixOwnProfile(params: {
+  client: MatrixProfileClient;
+  userId: string;
+  displayName?: string | null;
+  avatarUrl?: string | null;
+  avatarPath?: string | null;
+  avatarMaxBytes?: number;
+  loadAvatarFromUrl?: (url: string, maxBytes: number) => Promise<MatrixProfileLoadResult>;
+  loadAvatarFromPath?: (path: string, maxBytes: number) => Promise<MatrixProfileLoadResult>;
+}): Promise<MatrixProfileSyncResult> {
+  const desiredDisplayName = normalizeOptionalString(params.displayName) ?? null;
+  const avatar = await resolveAvatarUrl({
+    client: params.client,
+    avatarUrl: params.avatarUrl ?? null,
+    avatarPath: params.avatarPath ?? null,
+    avatarMaxBytes: params.avatarMaxBytes ?? MATRIX_PROFILE_AVATAR_MAX_BYTES,
+    loadAvatarFromUrl: params.loadAvatarFromUrl,
+    loadAvatarFromPath: params.loadAvatarFromPath,
+  });
+  const desiredAvatarUrl = avatar.resolvedAvatarUrl;
+
+  if (!desiredDisplayName && !desiredAvatarUrl) {
+    return {
+      skipped: true,
+      displayNameUpdated: false,
+      avatarUpdated: false,
+      resolvedAvatarUrl: null,
+      uploadedAvatarSource: avatar.uploadedAvatarSource,
+      convertedAvatarFromHttp: avatar.convertedAvatarFromHttp,
+    };
+  }
+
+  let currentDisplayName: string | undefined;
+  let currentAvatarUrl: string | undefined;
+  try {
+    const currentProfile = await params.client.getUserProfile(params.userId);
+    currentDisplayName = normalizeOptionalString(currentProfile.displayname);
+    currentAvatarUrl = normalizeOptionalString(currentProfile.avatar_url);
+  } catch {
+    // If profile fetch fails, attempt writes directly.
+  }
+
+  let displayNameUpdated = false;
+  let avatarUpdated = false;
+
+  if (desiredDisplayName && currentDisplayName !== desiredDisplayName) {
+    await params.client.setDisplayName(desiredDisplayName);
+    displayNameUpdated = true;
+  }
+  if (desiredAvatarUrl && currentAvatarUrl !== desiredAvatarUrl) {
+    await params.client.setAvatarUrl(desiredAvatarUrl);
+    avatarUpdated = true;
+  }
+
+  return {
+    skipped: false,
+    displayNameUpdated,
+    avatarUpdated,
+    resolvedAvatarUrl: desiredAvatarUrl,
+    uploadedAvatarSource: avatar.uploadedAvatarSource,
+    convertedAvatarFromHttp: avatar.convertedAvatarFromHttp,
+  };
+}

package/src/matrix/reaction-common.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildMatrixReactionContent,
+  buildMatrixReactionRelationsPath,
+  extractMatrixReactionAnnotation,
+  selectOwnMatrixReactionEventIds,
+  summarizeMatrixReactionEvents,
+} from "./reaction-common.js";
+
+describe("matrix reaction helpers", () => {
+  it("builds trimmed reaction content and relation paths", () => {
+    expect(buildMatrixReactionContent(" $msg ", " 👍 ")).toEqual({
+      "m.relates_to": {
+        rel_type: "m.annotation",
+        event_id: "$msg",
+        key: "👍",
+      },
+    });
+    expect(buildMatrixReactionRelationsPath("!room:example.org", " $msg ")).toContain(
+      "/rooms/!room%3Aexample.org/relations/%24msg/m.annotation/m.reaction",
+    );
+  });
+
+  it("summarizes reactions by emoji and unique sender", () => {
+    expect(
+      summarizeMatrixReactionEvents([
+        { sender: "@alice:example.org", content: { "m.relates_to": { key: "👍" } } },
+        { sender: "@alice:example.org", content: { "m.relates_to": { key: "👍" } } },
+        { sender: "@bob:example.org", content: { "m.relates_to": { key: "👍" } } },
+        { sender: "@alice:example.org", content: { "m.relates_to": { key: "👎" } } },
+        { sender: "@ignored:example.org", content: {} },
+      ]),
+    ).toEqual([
+      {
+        key: "👍",
+        count: 3,
+        users: ["@alice:example.org", "@bob:example.org"],
+      },
+      {
+        key: "👎",
+        count: 1,
+        users: ["@alice:example.org"],
+      },
+    ]);
+  });
+
+  it("selects only matching reaction event ids for the current user", () => {
+    expect(
+      selectOwnMatrixReactionEventIds(
+        [
+          {
+            event_id: "$1",
+            sender: "@me:example.org",
+            content: { "m.relates_to": { key: "👍" } },
+          },
+          {
+            event_id: "$2",
+            sender: "@me:example.org",
+            content: { "m.relates_to": { key: "👎" } },
+          },
+          {
+            event_id: "$3",
+            sender: "@other:example.org",
+            content: { "m.relates_to": { key: "👍" } },
+          },
+        ],
+        "@me:example.org",
+        "👍",
+      ),
+    ).toEqual(["$1"]);
+  });
+
+  it("extracts annotations and ignores non-annotation relations", () => {
+    expect(
+      extractMatrixReactionAnnotation({
+        "m.relates_to": {
+          rel_type: "m.annotation",
+          event_id: " $msg ",
+          key: " 👍 ",
+        },
+      }),
+    ).toEqual({
+      eventId: "$msg",
+      key: "👍",
+    });
+    expect(
+      extractMatrixReactionAnnotation({
+        "m.relates_to": {
+          rel_type: "m.replace",
+          event_id: "$msg",
+          key: "👍",
+        },
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/matrix/reaction-common.ts

@@ -0,0 +1,147 @@
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+
+export const MATRIX_ANNOTATION_RELATION_TYPE = "m.annotation";
+export const MATRIX_REACTION_EVENT_TYPE = "m.reaction";
+
+export type MatrixReactionEventContent = {
+  "m.relates_to": {
+    rel_type: typeof MATRIX_ANNOTATION_RELATION_TYPE;
+    event_id: string;
+    key: string;
+  };
+};
+
+export type MatrixReactionSummary = {
+  key: string;
+  count: number;
+  users: string[];
+};
+
+export type MatrixReactionAnnotation = {
+  key: string;
+  eventId?: string;
+};
+
+type MatrixReactionEventLike = {
+  content?: unknown;
+  sender?: string | null;
+  event_id?: string | null;
+};
+
+export function normalizeMatrixReactionMessageId(messageId: string): string {
+  const normalized = messageId.trim();
+  if (!normalized) {
+    throw new Error("Matrix reaction requires a messageId");
+  }
+  return normalized;
+}
+
+export function normalizeMatrixReactionEmoji(emoji: string): string {
+  const normalized = emoji.trim();
+  if (!normalized) {
+    throw new Error("Matrix reaction requires an emoji");
+  }
+  return normalized;
+}
+
+export function buildMatrixReactionContent(
+  messageId: string,
+  emoji: string,
+): MatrixReactionEventContent {
+  return {
+    "m.relates_to": {
+      rel_type: MATRIX_ANNOTATION_RELATION_TYPE,
+      event_id: normalizeMatrixReactionMessageId(messageId),
+      key: normalizeMatrixReactionEmoji(emoji),
+    },
+  };
+}
+
+export function buildMatrixReactionRelationsPath(roomId: string, messageId: string): string {
+  return `/_lobi/client/v1/rooms/${encodeURIComponent(roomId)}/relations/${encodeURIComponent(normalizeMatrixReactionMessageId(messageId))}/${MATRIX_ANNOTATION_RELATION_TYPE}/${MATRIX_REACTION_EVENT_TYPE}`;
+}
+
+export function extractMatrixReactionAnnotation(
+  content: unknown,
+): MatrixReactionAnnotation | undefined {
+  if (!content || typeof content !== "object") {
+    return undefined;
+  }
+  const relatesTo = (
+    content as {
+      "m.relates_to"?: {
+        rel_type?: unknown;
+        event_id?: unknown;
+        key?: unknown;
+      };
+    }
+  )["m.relates_to"];
+  if (!relatesTo || typeof relatesTo !== "object") {
+    return undefined;
+  }
+  if (
+    typeof relatesTo.rel_type === "string" &&
+    relatesTo.rel_type !== MATRIX_ANNOTATION_RELATION_TYPE
+  ) {
+    return undefined;
+  }
+  const key = normalizeOptionalString(relatesTo.key) ?? "";
+  if (!key) {
+    return undefined;
+  }
+  const eventId = normalizeOptionalString(relatesTo.event_id) ?? "";
+  return {
+    key,
+    eventId: eventId || undefined,
+  };
+}
+
+export function extractMatrixReactionKey(content: unknown): string | undefined {
+  return extractMatrixReactionAnnotation(content)?.key;
+}
+
+export function summarizeMatrixReactionEvents(
+  events: Iterable<Pick<MatrixReactionEventLike, "content" | "sender">>,
+): MatrixReactionSummary[] {
+  const summaries = new Map<string, MatrixReactionSummary>();
+  for (const event of events) {
+    const key = extractMatrixReactionKey(event.content);
+    if (!key) {
+      continue;
+    }
+    const sender = normalizeOptionalString(event.sender) ?? "";
+    const entry = summaries.get(key) ?? { key, count: 0, users: [] };
+    entry.count += 1;
+    if (sender && !entry.users.includes(sender)) {
+      entry.users.push(sender);
+    }
+    summaries.set(key, entry);
+  }
+  return Array.from(summaries.values());
+}
+
+export function selectOwnMatrixReactionEventIds(
+  events: Iterable<Pick<MatrixReactionEventLike, "content" | "event_id" | "sender">>,
+  userId: string,
+  emoji?: string,
+): string[] {
+  const senderId = normalizeOptionalString(userId) ?? "";
+  if (!senderId) {
+    return [];
+  }
+  const targetEmoji = normalizeOptionalString(emoji);
+  const ids: string[] = [];
+  for (const event of events) {
+    if ((normalizeOptionalString(event.sender) ?? "") !== senderId) {
+      continue;
+    }
+    if (targetEmoji && extractMatrixReactionKey(event.content) !== targetEmoji) {
+      continue;
+    }
+    const eventId = normalizeOptionalString(event.event_id);
+    if (eventId) {
+      ids.push(eventId);
+    }
+  }
+  return ids;
+}