@archipelagolab/lobi 1.0.0

package/src/matrix/actions/polls.ts

@@ -0,0 +1,109 @@
+import {
+  buildPollResponseContent,
+  isPollStartType,
+  parsePollStart,
+  type PollStartContent,
+} from "../poll-types.js";
+import { withResolvedRoomAction } from "./client.js";
+import type { MatrixActionClientOpts } from "./types.js";
+
+function normalizeOptionIndexes(indexes: number[]): number[] {
+  const normalized = indexes
+    .map((index) => Math.trunc(index))
+    .filter((index) => Number.isFinite(index) && index > 0);
+  return Array.from(new Set(normalized));
+}
+
+function normalizeOptionIds(optionIds: string[]): string[] {
+  return Array.from(
+    new Set(optionIds.map((optionId) => optionId.trim()).filter((optionId) => optionId.length > 0)),
+  );
+}
+
+function resolveSelectedAnswerIds(params: {
+  optionIds?: string[];
+  optionIndexes?: number[];
+  pollContent: PollStartContent;
+}): { answerIds: string[]; labels: string[]; maxSelections: number } {
+  const parsed = parsePollStart(params.pollContent);
+  if (!parsed) {
+    throw new Error("Matrix poll vote requires a valid poll start event.");
+  }
+
+  const selectedById = normalizeOptionIds(params.optionIds ?? []);
+  const selectedByIndex = normalizeOptionIndexes(params.optionIndexes ?? []).map((index) => {
+    const answer = parsed.answers[index - 1];
+    if (!answer) {
+      throw new Error(
+        `Matrix poll option index ${index} is out of range for a poll with ${parsed.answers.length} options.`,
+      );
+    }
+    return answer.id;
+  });
+
+  const answerIds = normalizeOptionIds([...selectedById, ...selectedByIndex]);
+  if (answerIds.length === 0) {
+    throw new Error("Matrix poll vote requires at least one poll option id or index.");
+  }
+  if (answerIds.length > parsed.maxSelections) {
+    throw new Error(
+      `Matrix poll allows at most ${parsed.maxSelections} selection${parsed.maxSelections === 1 ? "" : "s"}.`,
+    );
+  }
+
+  const answerMap = new Map(parsed.answers.map((answer) => [answer.id, answer.text] as const));
+  const labels = answerIds.map((answerId) => {
+    const label = answerMap.get(answerId);
+    if (!label) {
+      throw new Error(
+        `Matrix poll option id "${answerId}" is not valid for poll ${parsed.question}.`,
+      );
+    }
+    return label;
+  });
+
+  return {
+    answerIds,
+    labels,
+    maxSelections: parsed.maxSelections,
+  };
+}
+
+export async function voteMatrixPoll(
+  roomId: string,
+  pollId: string,
+  opts: MatrixActionClientOpts & {
+    optionId?: string;
+    optionIds?: string[];
+    optionIndex?: number;
+    optionIndexes?: number[];
+  } = {},
+) {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const pollEvent = await client.getEvent(resolvedRoom, pollId);
+    const eventType = typeof pollEvent.type === "string" ? pollEvent.type : "";
+    if (!isPollStartType(eventType)) {
+      throw new Error(`Event ${pollId} is not a Matrix poll start event.`);
+    }
+
+    const { answerIds, labels, maxSelections } = resolveSelectedAnswerIds({
+      optionIds: [...(opts.optionIds ?? []), ...(opts.optionId ? [opts.optionId] : [])],
+      optionIndexes: [
+        ...(opts.optionIndexes ?? []),
+        ...(opts.optionIndex !== undefined ? [opts.optionIndex] : []),
+      ],
+      pollContent: pollEvent.content as PollStartContent,
+    });
+
+    const content = buildPollResponseContent(pollId, answerIds);
+    const eventId = await client.sendEvent(resolvedRoom, "m.poll.response", content);
+    return {
+      eventId: eventId ?? null,
+      roomId: resolvedRoom,
+      pollId,
+      answerIds,
+      labels,
+      maxSelections,
+    };
+  });
+}

package/src/matrix/actions/profile.test.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const loadWebMediaMock = vi.fn();
+const syncMatrixOwnProfileMock = vi.fn();
+const withResolvedActionClientMock = vi.fn();
+
+vi.mock("../../runtime.js", () => ({
+  getMatrixRuntime: () => ({
+    media: {
+      loadWebMedia: (...args: unknown[]) => loadWebMediaMock(...args),
+    },
+  }),
+}));
+
+vi.mock("../profile.js", () => ({
+  syncMatrixOwnProfile: (...args: unknown[]) => syncMatrixOwnProfileMock(...args),
+}));
+
+vi.mock("./client.js", () => ({
+  withResolvedActionClient: (...args: unknown[]) => withResolvedActionClientMock(...args),
+}));
+
+const { updateMatrixOwnProfile } = await import("./profile.js");
+
+describe("matrix profile actions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadWebMediaMock.mockResolvedValue({
+      buffer: Buffer.from("avatar"),
+      contentType: "image/png",
+      fileName: "avatar.png",
+    });
+    syncMatrixOwnProfileMock.mockResolvedValue({
+      skipped: false,
+      displayNameUpdated: true,
+      avatarUpdated: true,
+      resolvedAvatarUrl: "mxc://example/avatar",
+      convertedAvatarFromHttp: true,
+      uploadedAvatarSource: "http",
+    });
+  });
+
+  it("trims profile fields and persists through the action client wrapper", async () => {
+    withResolvedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({
+        getUserId: vi.fn(async () => "@bot:example.org"),
+      });
+    });
+
+    await updateMatrixOwnProfile({
+      accountId: "ops",
+      displayName: "  Ops Bot  ",
+      avatarUrl: "  mxc://example/avatar  ",
+      avatarPath: "  /tmp/avatar.png  ",
+    });
+
+    expect(withResolvedActionClientMock).toHaveBeenCalledWith(
+      {
+        accountId: "ops",
+        displayName: "  Ops Bot  ",
+        avatarUrl: "  mxc://example/avatar  ",
+        avatarPath: "  /tmp/avatar.png  ",
+      },
+      expect.any(Function),
+      "persist",
+    );
+    expect(syncMatrixOwnProfileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: "@bot:example.org",
+        displayName: "Ops Bot",
+        avatarUrl: "mxc://example/avatar",
+        avatarPath: "/tmp/avatar.png",
+      }),
+    );
+  });
+
+  it("bridges avatar loaders through Matrix runtime media helpers", async () => {
+    withResolvedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({
+        getUserId: vi.fn(async () => "@bot:example.org"),
+      });
+    });
+
+    await updateMatrixOwnProfile({
+      avatarUrl: "https://cdn.example.org/avatar.png",
+      avatarPath: "/tmp/avatar.png",
+    });
+
+    const call = syncMatrixOwnProfileMock.mock.calls[0]?.[0] as
+      | {
+          loadAvatarFromUrl: (url: string, maxBytes: number) => Promise<unknown>;
+          loadAvatarFromPath: (path: string, maxBytes: number) => Promise<unknown>;
+        }
+      | undefined;
+
+    if (!call) {
+      throw new Error("syncMatrixOwnProfile was not called");
+    }
+
+    await call.loadAvatarFromUrl("https://cdn.example.org/avatar.png", 123);
+    await call.loadAvatarFromPath("/tmp/avatar.png", 456);
+
+    expect(loadWebMediaMock).toHaveBeenNthCalledWith(1, "https://cdn.example.org/avatar.png", 123);
+    expect(loadWebMediaMock).toHaveBeenNthCalledWith(2, "/tmp/avatar.png", {
+      maxBytes: 456,
+      localRoots: undefined,
+    });
+  });
+});

package/src/matrix/actions/profile.ts

@@ -0,0 +1,37 @@
+import { getMatrixRuntime } from "../../runtime.js";
+import { syncMatrixOwnProfile, type MatrixProfileSyncResult } from "../profile.js";
+import { withResolvedActionClient } from "./client.js";
+import type { MatrixActionClientOpts } from "./types.js";
+
+export async function updateMatrixOwnProfile(
+  opts: MatrixActionClientOpts & {
+    displayName?: string;
+    avatarUrl?: string;
+    avatarPath?: string;
+  } = {},
+): Promise<MatrixProfileSyncResult> {
+  const displayName = opts.displayName?.trim();
+  const avatarUrl = opts.avatarUrl?.trim();
+  const avatarPath = opts.avatarPath?.trim();
+  const runtime = getMatrixRuntime();
+  return await withResolvedActionClient(
+    opts,
+    async (client) => {
+      const userId = await client.getUserId();
+      return await syncMatrixOwnProfile({
+        client,
+        userId,
+        displayName: displayName || undefined,
+        avatarUrl: avatarUrl || undefined,
+        avatarPath: avatarPath || undefined,
+        loadAvatarFromUrl: async (url, maxBytes) => await runtime.media.loadWebMedia(url, maxBytes),
+        loadAvatarFromPath: async (path, maxBytes) =>
+          await runtime.media.loadWebMedia(path, {
+            maxBytes,
+            localRoots: opts.mediaLocalRoots,
+          }),
+      });
+    },
+    "persist",
+  );
+}

package/src/matrix/actions/reactions.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it, vi } from "vitest";
+import type { MatrixClient } from "../sdk.js";
+import { listMatrixReactions, removeMatrixReactions } from "./reactions.js";
+
+function createReactionsClient(params: {
+  chunk: Array<{
+    event_id?: string;
+    sender?: string;
+    key?: string;
+  }>;
+  userId?: string | null;
+}) {
+  const doRequest = vi.fn(async (_method: string, _path: string, _query: unknown) => ({
+    chunk: params.chunk.map((item) => ({
+      event_id: item.event_id ?? "",
+      sender: item.sender ?? "",
+      content: item.key
+        ? {
+            "m.relates_to": {
+              rel_type: "m.annotation",
+              event_id: "$target",
+              key: item.key,
+            },
+          }
+        : {},
+    })),
+  }));
+  const getUserId = vi.fn(async () => params.userId ?? null);
+  const redactEvent = vi.fn(async () => undefined);
+
+  return {
+    client: {
+      doRequest,
+      getUserId,
+      redactEvent,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    doRequest,
+    redactEvent,
+  };
+}
+
+describe("matrix reaction actions", () => {
+  it("aggregates reactions by key and unique sender", async () => {
+    const { client, doRequest } = createReactionsClient({
+      chunk: [
+        { event_id: "$1", sender: "@alice:example.org", key: "👍" },
+        { event_id: "$2", sender: "@bob:example.org", key: "👍" },
+        { event_id: "$3", sender: "@alice:example.org", key: "👎" },
+        { event_id: "$4", sender: "@bot:example.org" },
+      ],
+      userId: "@bot:example.org",
+    });
+
+    const result = await listMatrixReactions("!room:example.org", "$msg", { client, limit: 2.9 });
+
+    expect(doRequest).toHaveBeenCalledWith(
+      "GET",
+      expect.stringContaining("/rooms/!room%3Aexample.org/relations/%24msg/"),
+      expect.objectContaining({ limit: 2 }),
+    );
+    expect(result).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          key: "👍",
+          count: 2,
+          users: expect.arrayContaining(["@alice:example.org", "@bob:example.org"]),
+        }),
+        expect.objectContaining({
+          key: "👎",
+          count: 1,
+          users: ["@alice:example.org"],
+        }),
+      ]),
+    );
+  });
+
+  it("removes only current-user reactions matching emoji filter", async () => {
+    const { client, redactEvent } = createReactionsClient({
+      chunk: [
+        { event_id: "$1", sender: "@me:example.org", key: "👍" },
+        { event_id: "$2", sender: "@me:example.org", key: "👎" },
+        { event_id: "$3", sender: "@other:example.org", key: "👍" },
+      ],
+      userId: "@me:example.org",
+    });
+
+    const result = await removeMatrixReactions("!room:example.org", "$msg", {
+      client,
+      emoji: "👍",
+    });
+
+    expect(result).toEqual({ removed: 1 });
+    expect(redactEvent).toHaveBeenCalledTimes(1);
+    expect(redactEvent).toHaveBeenCalledWith("!room:example.org", "$1");
+  });
+
+  it("returns removed=0 when current user id is unavailable", async () => {
+    const { client, redactEvent } = createReactionsClient({
+      chunk: [{ event_id: "$1", sender: "@me:example.org", key: "👍" }],
+      userId: null,
+    });
+
+    const result = await removeMatrixReactions("!room:example.org", "$msg", { client });
+
+    expect(result).toEqual({ removed: 0 });
+    expect(redactEvent).not.toHaveBeenCalled();
+  });
+
+  it("returns an empty list when the relations response is malformed", async () => {
+    const doRequest = vi.fn(async () => ({ chunk: null }));
+    const client = {
+      doRequest,
+      getUserId: vi.fn(async () => "@me:example.org"),
+      redactEvent: vi.fn(async () => undefined),
+      stop: vi.fn(),
+    } as unknown as MatrixClient;
+
+    const result = await listMatrixReactions("!room:example.org", "$msg", { client });
+
+    expect(result).toEqual([]);
+  });
+
+  it("rejects blank message ids before querying Matrix relations", async () => {
+    const { client, doRequest } = createReactionsClient({
+      chunk: [],
+      userId: "@me:example.org",
+    });
+
+    await expect(listMatrixReactions("!room:example.org", "   ", { client })).rejects.toThrow(
+      "messageId",
+    );
+    expect(doRequest).not.toHaveBeenCalled();
+  });
+});

package/src/matrix/actions/reactions.ts

@@ -0,0 +1,59 @@
+import {
+  buildMatrixReactionRelationsPath,
+  selectOwnMatrixReactionEventIds,
+  summarizeMatrixReactionEvents,
+} from "../reaction-common.js";
+import { withResolvedRoomAction } from "./client.js";
+import { resolveMatrixActionLimit } from "./limits.js";
+import {
+  type MatrixActionClientOpts,
+  type MatrixRawEvent,
+  type MatrixReactionSummary,
+} from "./types.js";
+
+type ActionClient = NonNullable<MatrixActionClientOpts["client"]>;
+
+async function listMatrixReactionEvents(
+  client: ActionClient,
+  roomId: string,
+  messageId: string,
+  limit: number,
+): Promise<MatrixRawEvent[]> {
+  const res = (await client.doRequest("GET", buildMatrixReactionRelationsPath(roomId, messageId), {
+    dir: "b",
+    limit,
+  })) as { chunk?: MatrixRawEvent[] };
+  return Array.isArray(res.chunk) ? res.chunk : [];
+}
+
+export async function listMatrixReactions(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { limit?: number } = {},
+): Promise<MatrixReactionSummary[]> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const limit = resolveMatrixActionLimit(opts.limit, 100);
+    const chunk = await listMatrixReactionEvents(client, resolvedRoom, messageId, limit);
+    return summarizeMatrixReactionEvents(chunk);
+  });
+}
+
+export async function removeMatrixReactions(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { emoji?: string } = {},
+): Promise<{ removed: number }> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const chunk = await listMatrixReactionEvents(client, resolvedRoom, messageId, 200);
+    const userId = await client.getUserId();
+    if (!userId) {
+      return { removed: 0 };
+    }
+    const toRemove = selectOwnMatrixReactionEventIds(chunk, userId, opts.emoji);
+    if (toRemove.length === 0) {
+      return { removed: 0 };
+    }
+    await Promise.all(toRemove.map((id) => client.redactEvent(resolvedRoom, id)));
+    return { removed: toRemove.length };
+  });
+}

package/src/matrix/actions/room.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import type { MatrixClient } from "../sdk.js";
+import { getMatrixMemberInfo, getMatrixRoomInfo } from "./room.js";
+
+function createRoomClient() {
+  const getRoomStateEvent = vi.fn(async (_roomId: string, eventType: string) => {
+    switch (eventType) {
+      case "m.room.name":
+        return { name: "Ops Room" };
+      case "m.room.topic":
+        return { topic: "Incidents" };
+      case "m.room.canonical_alias":
+        return { alias: "#ops:example.org" };
+      default:
+        throw new Error(`unexpected state event ${eventType}`);
+    }
+  });
+  const getJoinedRoomMembers = vi.fn(async () => [
+    { user_id: "@alice:example.org" },
+    { user_id: "@bot:example.org" },
+  ]);
+  const getUserProfile = vi.fn(async () => ({
+    displayname: "Alice",
+    avatar_url: "mxc://example.org/alice",
+  }));
+
+  return {
+    client: {
+      getRoomStateEvent,
+      getJoinedRoomMembers,
+      getUserProfile,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    getRoomStateEvent,
+    getJoinedRoomMembers,
+    getUserProfile,
+  };
+}
+
+describe("matrix room actions", () => {
+  it("returns room details from the resolved Matrix room id", async () => {
+    const { client, getJoinedRoomMembers, getRoomStateEvent } = createRoomClient();
+
+    const result = await getMatrixRoomInfo("room:!ops:example.org", { client });
+
+    expect(getRoomStateEvent).toHaveBeenCalledWith("!ops:example.org", "m.room.name", "");
+    expect(getJoinedRoomMembers).toHaveBeenCalledWith("!ops:example.org");
+    expect(result).toEqual({
+      roomId: "!ops:example.org",
+      name: "Ops Room",
+      topic: "Incidents",
+      canonicalAlias: "#ops:example.org",
+      altAliases: [],
+      memberCount: 2,
+    });
+  });
+
+  it("resolves optional room ids when looking up member info", async () => {
+    const { client, getUserProfile } = createRoomClient();
+
+    const result = await getMatrixMemberInfo("@alice:example.org", {
+      client,
+      roomId: "room:!ops:example.org",
+    });
+
+    expect(getUserProfile).toHaveBeenCalledWith("@alice:example.org");
+    expect(result).toEqual({
+      userId: "@alice:example.org",
+      profile: {
+        displayName: "Alice",
+        avatarUrl: "mxc://example.org/alice",
+      },
+      membership: null,
+      powerLevel: null,
+      displayName: "Alice",
+      roomId: "!ops:example.org",
+    });
+  });
+});

package/src/matrix/actions/room.ts

@@ -0,0 +1,71 @@
+import { resolveMatrixRoomId } from "../send.js";
+import { withResolvedActionClient, withResolvedRoomAction } from "./client.js";
+import { EventType, type MatrixActionClientOpts } from "./types.js";
+
+export async function getMatrixMemberInfo(
+  userId: string,
+  opts: MatrixActionClientOpts & { roomId?: string } = {},
+) {
+  return await withResolvedActionClient(opts, async (client) => {
+    const roomId = opts.roomId ? await resolveMatrixRoomId(client, opts.roomId) : undefined;
+    const profile = await client.getUserProfile(userId);
+    // Membership and power levels are not included in profile calls; fetch state separately if needed.
+    return {
+      userId,
+      profile: {
+        displayName: profile?.displayname ?? null,
+        avatarUrl: profile?.avatar_url ?? null,
+      },
+      membership: null, // Would need separate room state query
+      powerLevel: null, // Would need separate power levels state query
+      displayName: profile?.displayname ?? null,
+      roomId: roomId ?? null,
+    };
+  });
+}
+
+export async function getMatrixRoomInfo(roomId: string, opts: MatrixActionClientOpts = {}) {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    let name: string | null = null;
+    let topic: string | null = null;
+    let canonicalAlias: string | null = null;
+    let memberCount: number | null = null;
+
+    try {
+      const nameState = await client.getRoomStateEvent(resolvedRoom, "m.room.name", "");
+      name = typeof nameState?.name === "string" ? nameState.name : null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const topicState = await client.getRoomStateEvent(resolvedRoom, EventType.RoomTopic, "");
+      topic = typeof topicState?.topic === "string" ? topicState.topic : null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const aliasState = await client.getRoomStateEvent(resolvedRoom, "m.room.canonical_alias", "");
+      canonicalAlias = typeof aliasState?.alias === "string" ? aliasState.alias : null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const members = await client.getJoinedRoomMembers(resolvedRoom);
+      memberCount = members.length;
+    } catch {
+      // ignore
+    }
+
+    return {
+      roomId: resolvedRoom,
+      name,
+      topic,
+      canonicalAlias,
+      altAliases: [], // Would need separate query
+      memberCount,
+    };
+  });
+}

package/src/matrix/actions/summary.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { summarizeMatrixRawEvent } from "./summary.js";
+
+describe("summarizeMatrixRawEvent", () => {
+  it("replaces bare media filenames with a media marker", () => {
+    const summary = summarizeMatrixRawEvent({
+      event_id: "$image",
+      sender: "@gum:matrix.example.org",
+      type: "m.room.message",
+      origin_server_ts: 123,
+      content: {
+        msgtype: "m.image",
+        body: "photo.jpg",
+      },
+    });
+
+    expect(summary).toMatchObject({
+      eventId: "$image",
+      msgtype: "m.image",
+      attachment: {
+        kind: "image",
+        filename: "photo.jpg",
+      },
+    });
+    expect(summary.body).toBeUndefined();
+  });
+
+  it("preserves captions while marking media summaries", () => {
+    const summary = summarizeMatrixRawEvent({
+      event_id: "$image",
+      sender: "@gum:matrix.example.org",
+      type: "m.room.message",
+      origin_server_ts: 123,
+      content: {
+        msgtype: "m.image",
+        body: "can you see this?",
+        filename: "photo.jpg",
+      },
+    });
+
+    expect(summary).toMatchObject({
+      body: "can you see this?",
+      attachment: {
+        kind: "image",
+        caption: "can you see this?",
+        filename: "photo.jpg",
+      },
+    });
+  });
+
+  it("does not treat a sentence ending in a file extension as a bare filename", () => {
+    const summary = summarizeMatrixRawEvent({
+      event_id: "$image",
+      sender: "@gum:matrix.example.org",
+      type: "m.room.message",
+      origin_server_ts: 123,
+      content: {
+        msgtype: "m.image",
+        body: "see image.png",
+      },
+    });
+
+    expect(summary).toMatchObject({
+      body: "see image.png",
+      attachment: {
+        kind: "image",
+        caption: "see image.png",
+      },
+    });
+  });
+
+  it("leaves text messages unchanged", () => {
+    const summary = summarizeMatrixRawEvent({
+      event_id: "$text",
+      sender: "@gum:matrix.example.org",
+      type: "m.room.message",
+      origin_server_ts: 123,
+      content: {
+        msgtype: "m.text",
+        body: "hello",
+      },
+    });
+
+    expect(summary.body).toBe("hello");
+    expect(summary.attachment).toBeUndefined();
+  });
+});