@kodelyth/matrix 2026.5.42 → 2026.6.1

package/src/matrix/account-config.ts

@@ -1,175 +0,0 @@
-import { normalizeAccountId } from "klaw/plugin-sdk/account-id";
-import { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/account-id";
-import {
-  listConfiguredAccountIds,
-  resolveMergedAccountConfig,
-  resolveNormalizedAccountEntry,
-} from "klaw/plugin-sdk/account-resolution-runtime";
-import { hasConfiguredSecretInput } from "klaw/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

@@ -1,194 +0,0 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
-import { hasConfiguredSecretInput } from "klaw/plugin-sdk/secret-input-runtime";
-import { normalizeOptionalString } from "klaw/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

@@ -1,31 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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.staleKlawDevices.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

@@ -1,6 +0,0 @@
-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

@@ -1,129 +0,0 @@
-import { normalizeOptionalString } from "klaw/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

@@ -1,63 +0,0 @@
-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 };
-  });
-}