@gakr-gakr/matrix 0.1.0

package/src/matrix/account-config.ts

@@ -0,0 +1,175 @@
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-id";
+import {
+  listConfiguredAccountIds,
+  resolveMergedAccountConfig,
+  resolveNormalizedAccountEntry,
+} from "autobot/plugin-sdk/account-resolution-runtime";
+import { hasConfiguredSecretInput } from "autobot/plugin-sdk/secret-input-runtime";
+import type { CoreConfig, MatrixAccountConfig, MatrixConfig } from "../types.js";
+
+type MatrixRoomEntries = Record<string, NonNullable<MatrixConfig["groups"]>[string]>;
+
+export function resolveMatrixBaseConfig(cfg: CoreConfig): MatrixConfig {
+  return cfg.channels?.matrix ?? {};
+}
+
+function resolveMatrixAccountsMap(cfg: CoreConfig): Readonly<Record<string, MatrixAccountConfig>> {
+  const accounts = resolveMatrixBaseConfig(cfg).accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return {};
+  }
+  return accounts;
+}
+
+function selectInheritedMatrixRoomEntries(params: {
+  entries: MatrixRoomEntries | undefined;
+  accountId: string;
+}): MatrixRoomEntries | undefined {
+  const entries = params.entries;
+  if (!entries) {
+    return undefined;
+  }
+  const selected = Object.fromEntries(
+    Object.entries(entries).filter(([, value]) => {
+      const scopedAccount =
+        typeof value?.account === "string" ? normalizeAccountId(value.account) : undefined;
+      return scopedAccount === undefined || scopedAccount === params.accountId;
+    }),
+  ) as MatrixRoomEntries;
+  return Object.keys(selected).length > 0 ? selected : undefined;
+}
+
+function mergeMatrixRoomEntries(
+  inherited: MatrixRoomEntries | undefined,
+  accountEntries: MatrixRoomEntries | undefined,
+  hasAccountOverride: boolean,
+): MatrixRoomEntries | undefined {
+  if (!inherited && !accountEntries) {
+    return undefined;
+  }
+  if (hasAccountOverride && Object.keys(accountEntries ?? {}).length === 0) {
+    return undefined;
+  }
+  const merged: MatrixRoomEntries = {
+    ...inherited,
+  };
+  for (const [key, value] of Object.entries(accountEntries ?? {})) {
+    const inheritedValue = merged[key];
+    merged[key] =
+      inheritedValue && value
+        ? {
+            ...inheritedValue,
+            ...value,
+          }
+        : (value ?? inheritedValue);
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+export function listNormalizedMatrixAccountIds(cfg: CoreConfig): string[] {
+  return listConfiguredAccountIds({
+    accounts: resolveMatrixAccountsMap(cfg),
+    normalizeAccountId,
+  });
+}
+
+export function findMatrixAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+): MatrixAccountConfig | undefined {
+  return resolveNormalizedAccountEntry(
+    resolveMatrixAccountsMap(cfg),
+    accountId,
+    normalizeAccountId,
+  );
+}
+
+export function hasExplicitMatrixAccountConfig(cfg: CoreConfig, accountId: string): boolean {
+  const normalized = normalizeAccountId(accountId);
+  if (findMatrixAccountConfig(cfg, normalized)) {
+    return true;
+  }
+  if (normalized !== DEFAULT_ACCOUNT_ID) {
+    return false;
+  }
+  const matrix = resolveMatrixBaseConfig(cfg);
+  return (
+    typeof matrix.enabled === "boolean" ||
+    typeof matrix.name === "string" ||
+    typeof matrix.homeserver === "string" ||
+    typeof matrix.userId === "string" ||
+    hasConfiguredSecretInput(matrix.accessToken) ||
+    hasConfiguredSecretInput(matrix.password) ||
+    typeof matrix.deviceId === "string" ||
+    typeof matrix.deviceName === "string" ||
+    typeof matrix.avatarUrl === "string"
+  );
+}
+
+export function resolveMatrixAccountConfig(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): MatrixConfig {
+  const accountId = normalizeAccountId(params.accountId);
+  const base = resolveMatrixBaseConfig(params.cfg);
+  const merged = resolveMergedAccountConfig<MatrixConfig>({
+    channelConfig: base,
+    accounts: params.cfg.channels?.matrix?.accounts as
+      | Record<string, Partial<MatrixConfig>>
+      | undefined,
+    accountId,
+    normalizeAccountId,
+    nestedObjectKeys: ["dm", "actions", "execApprovals", "botLoopProtection"],
+  });
+  const accountConfig = findMatrixAccountConfig(params.cfg, accountId);
+  const groups = mergeMatrixRoomEntries(
+    selectInheritedMatrixRoomEntries({
+      entries: base.groups,
+      accountId,
+    }),
+    accountConfig?.groups,
+    Boolean(accountConfig && Object.hasOwn(accountConfig, "groups")),
+  );
+  const rooms = mergeMatrixRoomEntries(
+    selectInheritedMatrixRoomEntries({
+      entries: base.rooms,
+      accountId,
+    }),
+    accountConfig?.rooms,
+    Boolean(accountConfig && Object.hasOwn(accountConfig, "rooms")),
+  );
+  // Room maps need custom scoping, so keep the generic merge for all other fields.
+  const { groups: _ignoredGroups, rooms: _ignoredRooms, ...rest } = merged;
+  return {
+    ...rest,
+    ...(groups ? { groups } : {}),
+    ...(rooms ? { rooms } : {}),
+  };
+}
+
+export function resolveMatrixAccountAllowlistConfig(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+}): {
+  dmAllowFrom?: NonNullable<MatrixConfig["dm"]>["allowFrom"];
+  groupAllowFrom?: MatrixConfig["groupAllowFrom"];
+} {
+  const accountId = normalizeAccountId(params.accountId);
+  const base = resolveMatrixBaseConfig(params.cfg);
+  const accountConfig = findMatrixAccountConfig(params.cfg, accountId);
+  const accountDm = accountConfig?.dm;
+
+  let dmAllowFrom = base.dm?.allowFrom;
+  if (accountDm && Object.hasOwn(accountDm, "allowFrom")) {
+    dmAllowFrom = accountDm.allowFrom;
+  }
+
+  let groupAllowFrom = base.groupAllowFrom;
+  if (accountConfig && Object.hasOwn(accountConfig, "groupAllowFrom")) {
+    groupAllowFrom = accountConfig.groupAllowFrom;
+  }
+
+  return { dmAllowFrom, groupAllowFrom };
+}

package/src/matrix/accounts.ts

@@ -0,0 +1,194 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { hasConfiguredSecretInput } from "autobot/plugin-sdk/secret-input-runtime";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import {
+  resolveConfiguredMatrixAccountIds,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "../account-selection.js";
+import { resolveMatrixAccountStringValues } from "../auth-precedence.js";
+import type { CoreConfig, MatrixConfig } from "../types.js";
+import {
+  findMatrixAccountConfig,
+  resolveMatrixAccountConfig,
+  resolveMatrixBaseConfig,
+} from "./account-config.js";
+import { resolveGlobalMatrixEnvConfig, resolveScopedMatrixEnvConfig } from "./client/env-auth.js";
+import { credentialsMatchConfig, loadMatrixCredentials } from "./credentials-read.js";
+
+export type ResolvedMatrixAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  configured: boolean;
+  homeserver?: string;
+  userId?: string;
+  config: MatrixConfig;
+};
+
+function clean(value: unknown): string {
+  return normalizeOptionalString(value) ?? "";
+}
+
+function resolveMatrixAccountAuthView(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  env: NodeJS.ProcessEnv;
+}): {
+  homeserver: string;
+  userId: string;
+  accessToken?: string;
+  password?: string;
+} {
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const matrix = resolveMatrixBaseConfig(params.cfg);
+  const account = findMatrixAccountConfig(params.cfg, normalizedAccountId) ?? {};
+  const resolvedStrings = resolveMatrixAccountStringValues({
+    accountId: normalizedAccountId,
+    account: {
+      homeserver: clean(account.homeserver),
+      userId: clean(account.userId),
+      accessToken: typeof account.accessToken === "string" ? clean(account.accessToken) : "",
+      password: typeof account.password === "string" ? clean(account.password) : "",
+      deviceId: clean(account.deviceId),
+      deviceName: clean(account.deviceName),
+    },
+    scopedEnv: resolveScopedMatrixEnvConfig(normalizedAccountId, params.env),
+    channel: {
+      homeserver: clean(matrix.homeserver),
+      userId: clean(matrix.userId),
+      accessToken: typeof matrix.accessToken === "string" ? clean(matrix.accessToken) : "",
+      password: typeof matrix.password === "string" ? clean(matrix.password) : "",
+      deviceId: clean(matrix.deviceId),
+      deviceName: clean(matrix.deviceName),
+    },
+    globalEnv: resolveGlobalMatrixEnvConfig(params.env),
+  });
+  return {
+    homeserver: resolvedStrings.homeserver,
+    userId: resolvedStrings.userId,
+    accessToken: resolvedStrings.accessToken || undefined,
+    password: resolvedStrings.password || undefined,
+  };
+}
+
+function resolveMatrixAccountUserId(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  env?: NodeJS.ProcessEnv;
+}): string | null {
+  const env = params.env ?? process.env;
+  const authView = resolveMatrixAccountAuthView({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    env,
+  });
+  const configuredUserId = authView.userId.trim();
+  if (configuredUserId) {
+    return configuredUserId;
+  }
+
+  const stored = loadMatrixCredentials(env, params.accountId);
+  if (!stored) {
+    return null;
+  }
+  if (authView.homeserver && stored.homeserver !== authView.homeserver) {
+    return null;
+  }
+  if (authView.accessToken && stored.accessToken !== authView.accessToken) {
+    return null;
+  }
+  return stored.userId.trim() || null;
+}
+
+export function listMatrixAccountIds(cfg: CoreConfig): string[] {
+  const ids = resolveConfiguredMatrixAccountIds(cfg, process.env);
+  return ids.length > 0 ? ids : [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultMatrixAccountId(cfg: CoreConfig): string {
+  return normalizeAccountId(resolveMatrixDefaultOrOnlyAccountId(cfg));
+}
+
+export function resolveConfiguredMatrixBotUserIds(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): Set<string> {
+  const env = params.env ?? process.env;
+  const currentAccountId = normalizeAccountId(params.accountId);
+  const accountIds = new Set(resolveConfiguredMatrixAccountIds(params.cfg, env));
+  if (resolveMatrixAccount({ cfg: params.cfg, accountId: DEFAULT_ACCOUNT_ID, env }).configured) {
+    accountIds.add(DEFAULT_ACCOUNT_ID);
+  }
+  const ids = new Set<string>();
+
+  for (const accountId of accountIds) {
+    if (normalizeAccountId(accountId) === currentAccountId) {
+      continue;
+    }
+    if (!resolveMatrixAccount({ cfg: params.cfg, accountId, env }).configured) {
+      continue;
+    }
+    const userId = resolveMatrixAccountUserId({
+      cfg: params.cfg,
+      accountId,
+      env,
+    });
+    if (userId) {
+      ids.add(userId);
+    }
+  }
+
+  return ids;
+}
+
+export function resolveMatrixAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): ResolvedMatrixAccount {
+  const env = params.env ?? process.env;
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultMatrixAccountId(params.cfg),
+  );
+  const matrixBase = resolveMatrixBaseConfig(params.cfg);
+  const base = resolveMatrixAccountConfig({ cfg: params.cfg, accountId, env });
+  const explicitAuthConfig =
+    accountId === DEFAULT_ACCOUNT_ID
+      ? base
+      : (findMatrixAccountConfig(params.cfg, accountId) ?? {});
+  const enabled = base.enabled !== false && matrixBase.enabled !== false;
+
+  const authView = resolveMatrixAccountAuthView({
+    cfg: params.cfg,
+    accountId,
+    env,
+  });
+  const hasHomeserver = Boolean(authView.homeserver);
+  const hasUserId = Boolean(authView.userId);
+  const hasAccessToken =
+    Boolean(authView.accessToken) || hasConfiguredSecretInput(explicitAuthConfig.accessToken);
+  const hasPassword = Boolean(authView.password);
+  const hasPasswordAuth =
+    hasUserId && (hasPassword || hasConfiguredSecretInput(explicitAuthConfig.password));
+  const stored = loadMatrixCredentials(env, accountId);
+  const hasStored =
+    stored && authView.homeserver
+      ? credentialsMatchConfig(stored, {
+          homeserver: authView.homeserver,
+          userId: authView.userId || "",
+        })
+      : false;
+  const configured = hasHomeserver && (hasAccessToken || hasPasswordAuth || hasStored);
+  return {
+    accountId,
+    enabled,
+    name: normalizeOptionalString(base.name),
+    configured,
+    homeserver: authView.homeserver || undefined,
+    userId: authView.userId || undefined,
+    config: base,
+  };
+}
+
+export { resolveMatrixAccountConfig } from "./account-config.js";

package/src/matrix/actions/client.ts

@@ -0,0 +1,31 @@
+import { withResolvedRuntimeMatrixClient } from "../client-bootstrap.js";
+import { resolveMatrixRoomId } from "../send.js";
+import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
+
+type MatrixActionClientStopMode = "stop" | "persist" | "discard";
+
+export async function withResolvedActionClient<T>(
+  opts: MatrixActionClientOpts,
+  run: (client: MatrixActionClient["client"]) => Promise<T>,
+  mode: MatrixActionClientStopMode = "stop",
+): Promise<T> {
+  return await withResolvedRuntimeMatrixClient(opts, run, mode);
+}
+
+export async function withStartedActionClient<T>(
+  opts: MatrixActionClientOpts,
+  run: (client: MatrixActionClient["client"]) => Promise<T>,
+): Promise<T> {
+  return await withResolvedActionClient({ ...opts, readiness: "started" }, run, "persist");
+}
+
+export async function withResolvedRoomAction<T>(
+  roomId: string,
+  opts: MatrixActionClientOpts,
+  run: (client: MatrixActionClient["client"], resolvedRoom: string) => Promise<T>,
+): Promise<T> {
+  return await withResolvedActionClient(opts, async (client) => {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    return await run(client, resolvedRoom);
+  });
+}

package/src/matrix/actions/devices.ts

@@ -0,0 +1,34 @@
+import { summarizeMatrixDeviceHealth } from "../device-health.js";
+import { withResolvedActionClient } from "./client.js";
+import type { MatrixActionClientOpts } from "./types.js";
+
+export async function listMatrixOwnDevices(opts: MatrixActionClientOpts = {}) {
+  return await withResolvedActionClient(opts, async (client) => await client.listOwnDevices());
+}
+
+export async function pruneMatrixStaleGatewayDevices(opts: MatrixActionClientOpts = {}) {
+  return await withResolvedActionClient(opts, async (client) => {
+    const devices = await client.listOwnDevices();
+    const health = summarizeMatrixDeviceHealth(devices);
+    const staleGatewayDeviceIds = health.staleAutoBotDevices.map((device) => device.deviceId);
+    const deleted =
+      staleGatewayDeviceIds.length > 0
+        ? await client.deleteOwnDevices(staleGatewayDeviceIds)
+        : {
+            currentDeviceId: devices.find((device) => device.current)?.deviceId ?? null,
+            deletedDeviceIds: [] as string[],
+            remainingDevices: devices,
+          };
+    return {
+      before: devices,
+      staleGatewayDeviceIds,
+      ...deleted,
+    };
+  });
+}
+
+export async function getMatrixDeviceHealth(opts: MatrixActionClientOpts = {}) {
+  return await withResolvedActionClient(opts, async (client) =>
+    summarizeMatrixDeviceHealth(await client.listOwnDevices()),
+  );
+}

package/src/matrix/actions/limits.ts

@@ -0,0 +1,6 @@
+export function resolveMatrixActionLimit(raw: unknown, fallback: number): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(raw));
+}

package/src/matrix/actions/messages.ts

@@ -0,0 +1,129 @@
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { fetchMatrixPollMessageSummary, resolveMatrixPollRootEventId } from "../poll-summary.js";
+import { isPollEventType } from "../poll-types.js";
+import { editMessageMatrix, sendMessageMatrix } from "../send.js";
+import { withResolvedRoomAction } from "./client.js";
+import { resolveMatrixActionLimit } from "./limits.js";
+import { summarizeMatrixRawEvent } from "./summary.js";
+import {
+  EventType,
+  type MatrixActionClientOpts,
+  type MatrixMessageSummary,
+  type MatrixRawEvent,
+} from "./types.js";
+
+export async function sendMatrixMessage(
+  to: string,
+  content: string | undefined,
+  opts: MatrixActionClientOpts & {
+    mediaUrl?: string;
+    replyToId?: string;
+    threadId?: string;
+    audioAsVoice?: boolean;
+  } = {},
+) {
+  if (!opts.cfg) {
+    throw new Error("Matrix message actions require a resolved runtime config.");
+  }
+  return await sendMessageMatrix(to, content, {
+    cfg: opts.cfg,
+    mediaUrl: opts.mediaUrl,
+    mediaLocalRoots: opts.mediaLocalRoots,
+    replyToId: opts.replyToId,
+    threadId: opts.threadId,
+    audioAsVoice: opts.audioAsVoice,
+    accountId: opts.accountId ?? undefined,
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function editMatrixMessage(
+  roomId: string,
+  messageId: string,
+  content: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  if (!opts.cfg) {
+    throw new Error("Matrix message actions require a resolved runtime config.");
+  }
+  const trimmed = content.trim();
+  if (!trimmed) {
+    throw new Error("Matrix edit requires content");
+  }
+  const eventId = await editMessageMatrix(roomId, messageId, trimmed, {
+    cfg: opts.cfg,
+    accountId: opts.accountId ?? undefined,
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+  return { eventId: eventId || null };
+}
+
+export async function deleteMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { reason?: string } = {},
+) {
+  await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    await client.redactEvent(resolvedRoom, messageId, opts.reason);
+  });
+}
+
+export async function readMatrixMessages(
+  roomId: string,
+  opts: MatrixActionClientOpts & {
+    limit?: number;
+    before?: string;
+    after?: string;
+  } = {},
+): Promise<{
+  messages: MatrixMessageSummary[];
+  nextBatch?: string | null;
+  prevBatch?: string | null;
+}> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const limit = resolveMatrixActionLimit(opts.limit, 20);
+    const token = normalizeOptionalString(opts.before) ?? normalizeOptionalString(opts.after);
+    const dir = opts.after ? "f" : "b";
+    // Room history is queried via the low-level endpoint for compatibility.
+    const res = (await client.doRequest(
+      "GET",
+      `/_matrix/client/v3/rooms/${encodeURIComponent(resolvedRoom)}/messages`,
+      {
+        dir,
+        limit,
+        from: token,
+      },
+    )) as { chunk: MatrixRawEvent[]; start?: string; end?: string };
+    const hydratedChunk = await client.hydrateEvents(resolvedRoom, res.chunk);
+    const seenPollRoots = new Set<string>();
+    const messages: MatrixMessageSummary[] = [];
+    for (const event of hydratedChunk) {
+      if (event.unsigned?.redacted_because) {
+        continue;
+      }
+      if (event.type === EventType.RoomMessage) {
+        messages.push(summarizeMatrixRawEvent(event));
+        continue;
+      }
+      if (!isPollEventType(event.type)) {
+        continue;
+      }
+      const pollRootId = resolveMatrixPollRootEventId(event);
+      if (!pollRootId || seenPollRoots.has(pollRootId)) {
+        continue;
+      }
+      seenPollRoots.add(pollRootId);
+      const pollSummary = await fetchMatrixPollMessageSummary(client, resolvedRoom, event);
+      if (pollSummary) {
+        messages.push(pollSummary);
+      }
+    }
+    return {
+      messages,
+      nextBatch: res.end ?? null,
+      prevBatch: res.start ?? null,
+    };
+  });
+}

package/src/matrix/actions/pins.ts

@@ -0,0 +1,63 @@
+import { withResolvedRoomAction } from "./client.js";
+import { fetchEventSummary, readPinnedEvents } from "./summary.js";
+import {
+  EventType,
+  type MatrixActionClientOpts,
+  type MatrixMessageSummary,
+  type RoomPinnedEventsEventContent,
+} from "./types.js";
+
+async function updateMatrixPins(
+  roomId: string,
+  opts: MatrixActionClientOpts,
+  update: (current: string[]) => string[],
+): Promise<{ pinned: string[] }> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const current = await readPinnedEvents(client, resolvedRoom);
+    const next = update(current);
+    const payload: RoomPinnedEventsEventContent = { pinned: next };
+    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
+    return { pinned: next };
+  });
+}
+
+export async function pinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  return await updateMatrixPins(roomId, opts, (current) =>
+    current.includes(messageId) ? current : [...current, messageId],
+  );
+}
+
+export async function unpinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  return await updateMatrixPins(roomId, opts, (current) =>
+    current.filter((id) => id !== messageId),
+  );
+}
+
+export async function listMatrixPins(
+  roomId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[]; events: MatrixMessageSummary[] }> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const pinned = await readPinnedEvents(client, resolvedRoom);
+    const events = (
+      await Promise.all(
+        pinned.map(async (eventId) => {
+          try {
+            return await fetchEventSummary(client, resolvedRoom, eventId);
+          } catch {
+            return null;
+          }
+        }),
+      )
+    ).filter((event): event is MatrixMessageSummary => Boolean(event));
+    return { pinned, events };
+  });
+}