@kodelyth/matrix 2026.5.42 → 2026.6.1

package/src/matrix/client-bootstrap.ts

@@ -1,173 +0,0 @@
-import { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
-import type { CoreConfig } from "../types.js";
-import { getActiveMatrixClient } from "./active-client.js";
-import { isBunRuntime } from "./client/runtime.js";
-import type { MatrixClient } from "./sdk.js";
-
-type ResolvedRuntimeMatrixClient = {
-  client: MatrixClient;
-  stopOnDone: boolean;
-  cleanup?: (mode: ResolvedRuntimeMatrixClientStopMode) => Promise<void>;
-};
-
-type MatrixRuntimeClientReadiness = "none" | "prepared" | "started";
-type ResolvedRuntimeMatrixClientStopMode = "stop" | "persist" | "discard";
-
-type MatrixResolvedClientHook = (
-  client: MatrixClient,
-  context: { preparedByDefault: boolean },
-) => Promise<void> | void;
-
-type MatrixSharedClientRuntimeDeps = Pick<
-  typeof import("./client.js"),
-  "acquireSharedMatrixClient" | "resolveMatrixAuthContext"
-> &
-  Pick<typeof import("./client/shared.js"), "releaseSharedClientInstance">;
-
-let matrixSharedClientRuntimeDepsPromise: Promise<MatrixSharedClientRuntimeDeps> | undefined;
-
-async function loadMatrixSharedClientRuntimeDeps(): Promise<MatrixSharedClientRuntimeDeps> {
-  matrixSharedClientRuntimeDepsPromise ??= Promise.all([
-    import("./client.js"),
-    import("./client/shared.js"),
-  ]).then(([clientModule, sharedModule]) => ({
-    acquireSharedMatrixClient: clientModule.acquireSharedMatrixClient,
-    resolveMatrixAuthContext: clientModule.resolveMatrixAuthContext,
-    releaseSharedClientInstance: sharedModule.releaseSharedClientInstance,
-  }));
-  return await matrixSharedClientRuntimeDepsPromise;
-}
-
-async function ensureResolvedClientReadiness(params: {
-  client: MatrixClient;
-  readiness?: MatrixRuntimeClientReadiness;
-  preparedByDefault: boolean;
-}): Promise<void> {
-  if (params.readiness === "started") {
-    await params.client.start();
-    return;
-  }
-  if (params.readiness === "prepared" || (!params.readiness && params.preparedByDefault)) {
-    await params.client.prepareForOneOff();
-  }
-}
-
-function ensureMatrixNodeRuntime() {
-  if (isBunRuntime()) {
-    throw new Error("Matrix support requires Node (bun runtime not supported)");
-  }
-}
-
-async function resolveRuntimeMatrixClient(opts: {
-  client?: MatrixClient;
-  cfg?: CoreConfig;
-  timeoutMs?: number;
-  accountId?: string | null;
-  onResolved?: MatrixResolvedClientHook;
-}): Promise<ResolvedRuntimeMatrixClient> {
-  ensureMatrixNodeRuntime();
-  if (opts.client) {
-    await opts.onResolved?.(opts.client, { preparedByDefault: false });
-    return { client: opts.client, stopOnDone: false };
-  }
-
-  if (!opts.cfg) {
-    throw new Error(
-      "Matrix runtime client requires a resolved runtime config. Load and resolve config at the command or gateway boundary, then pass cfg through the runtime path.",
-    );
-  }
-  const cfg = requireRuntimeConfig(opts.cfg, "Matrix runtime client") as CoreConfig;
-  const { acquireSharedMatrixClient, releaseSharedClientInstance, resolveMatrixAuthContext } =
-    await loadMatrixSharedClientRuntimeDeps();
-  const authContext = resolveMatrixAuthContext({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const active = getActiveMatrixClient(authContext.accountId);
-  if (active) {
-    await opts.onResolved?.(active, { preparedByDefault: false });
-    return { client: active, stopOnDone: false };
-  }
-  const client = await acquireSharedMatrixClient({
-    cfg,
-    timeoutMs: opts.timeoutMs,
-    accountId: authContext.accountId,
-    startClient: false,
-  });
-  try {
-    await opts.onResolved?.(client, { preparedByDefault: true });
-  } catch (err) {
-    await releaseSharedClientInstance(client, "stop");
-    throw err;
-  }
-  return {
-    client,
-    stopOnDone: true,
-    cleanup: async (mode) => {
-      await releaseSharedClientInstance(client, mode);
-    },
-  };
-}
-
-export async function resolveRuntimeMatrixClientWithReadiness(opts: {
-  client?: MatrixClient;
-  cfg?: CoreConfig;
-  timeoutMs?: number;
-  accountId?: string | null;
-  readiness?: MatrixRuntimeClientReadiness;
-}): Promise<ResolvedRuntimeMatrixClient> {
-  return await resolveRuntimeMatrixClient({
-    client: opts.client,
-    cfg: opts.cfg,
-    timeoutMs: opts.timeoutMs,
-    accountId: opts.accountId,
-    onResolved: async (client, context) => {
-      await ensureResolvedClientReadiness({
-        client,
-        readiness: opts.readiness,
-        preparedByDefault: context.preparedByDefault,
-      });
-    },
-  });
-}
-
-export async function stopResolvedRuntimeMatrixClient(
-  resolved: ResolvedRuntimeMatrixClient,
-  mode: ResolvedRuntimeMatrixClientStopMode = "stop",
-): Promise<void> {
-  if (!resolved.stopOnDone) {
-    return;
-  }
-  if (resolved.cleanup) {
-    await resolved.cleanup(mode);
-    return;
-  }
-  if (mode === "persist") {
-    await resolved.client.stopAndPersist();
-    return;
-  }
-  if (mode === "discard") {
-    resolved.client.stopWithoutPersist();
-    return;
-  }
-  resolved.client.stop();
-}
-
-export async function withResolvedRuntimeMatrixClient<T>(
-  opts: {
-    client?: MatrixClient;
-    cfg?: CoreConfig;
-    timeoutMs?: number;
-    accountId?: string | null;
-    readiness?: MatrixRuntimeClientReadiness;
-  },
-  run: (client: MatrixClient) => Promise<T>,
-  stopMode: ResolvedRuntimeMatrixClientStopMode = "stop",
-): Promise<T> {
-  const resolved = await resolveRuntimeMatrixClientWithReadiness(opts);
-  try {
-    return await run(resolved.client);
-  } finally {
-    await stopResolvedRuntimeMatrixClient(resolved, stopMode);
-  }
-}

package/src/matrix/client.ts

@@ -1,23 +0,0 @@
-export type { MatrixAuth } from "./client/types.js";
-export { isBunRuntime } from "./client/runtime.js";
-export { getMatrixScopedEnvVarNames } from "../env-vars.js";
-export {
-  backfillMatrixAuthDeviceIdAfterStartup,
-  hasReadyMatrixEnvAuth,
-  resolveMatrixEnvAuthReadiness,
-  resolveMatrixConfigForAccount,
-  resolveScopedMatrixEnvConfig,
-  resolveMatrixAuth,
-  resolveMatrixAuthContext,
-  resolveValidatedMatrixHomeserverUrl,
-  validateMatrixHomeserverUrl,
-} from "./client/config.js";
-export { createMatrixClient } from "./client/create-client.js";
-export {
-  acquireSharedMatrixClient,
-  removeSharedClientInstance,
-  releaseSharedClientInstance,
-  resolveSharedMatrixClient,
-  stopSharedClientForAccount,
-  stopSharedClientInstance,
-} from "./client/shared.js";

package/src/matrix/config-paths.ts

@@ -1,31 +0,0 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
-import type { CoreConfig } from "../types.js";
-
-export function shouldStoreMatrixAccountAtTopLevel(cfg: CoreConfig, accountId: string): boolean {
-  const normalizedAccountId = normalizeAccountId(accountId);
-  if (normalizedAccountId !== DEFAULT_ACCOUNT_ID) {
-    return false;
-  }
-  const accounts = cfg.channels?.matrix?.accounts;
-  return !accounts || Object.keys(accounts).length === 0;
-}
-
-export function resolveMatrixConfigPath(cfg: CoreConfig, accountId: string): string {
-  const normalizedAccountId = normalizeAccountId(accountId);
-  if (shouldStoreMatrixAccountAtTopLevel(cfg, normalizedAccountId)) {
-    return "channels.matrix";
-  }
-  return `channels.matrix.accounts.${normalizedAccountId}`;
-}
-
-export function resolveMatrixConfigFieldPath(
-  cfg: CoreConfig,
-  accountId: string,
-  fieldPath: string,
-): string {
-  const suffix = fieldPath.trim().replace(/^\.+/, "");
-  if (!suffix) {
-    return resolveMatrixConfigPath(cfg, accountId);
-  }
-  return `${resolveMatrixConfigPath(cfg, accountId)}.${suffix}`;
-}

package/src/matrix/config-update.ts

@@ -1,292 +0,0 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
-import { coerceSecretRef } from "klaw/plugin-sdk/secret-ref-runtime";
-import { normalizeSecretInputString } from "klaw/plugin-sdk/setup";
-import type { CoreConfig, MatrixConfig } from "../types.js";
-import { findMatrixAccountConfig } from "./account-config.js";
-import {
-  resolveMatrixConfigPath as resolveMatrixConfigPathBase,
-  shouldStoreMatrixAccountAtTopLevel,
-} from "./config-paths.js";
-
-export {
-  resolveMatrixConfigFieldPath,
-  shouldStoreMatrixAccountAtTopLevel,
-} from "./config-paths.js";
-export const resolveMatrixConfigPath = resolveMatrixConfigPathBase;
-
-export type MatrixAccountPatch = {
-  name?: string | null;
-  enabled?: boolean;
-  homeserver?: string | null;
-  allowPrivateNetwork?: boolean | null;
-  proxy?: string | null;
-  userId?: string | null;
-  accessToken?: MatrixConfig["accessToken"] | null;
-  password?: MatrixConfig["password"] | null;
-  deviceId?: string | null;
-  deviceName?: string | null;
-  avatarUrl?: string | null;
-  encryption?: boolean | null;
-  initialSyncLimit?: number | null;
-  allowBots?: MatrixConfig["allowBots"] | null;
-  autoJoin?: MatrixConfig["autoJoin"] | null;
-  autoJoinAllowlist?: MatrixConfig["autoJoinAllowlist"] | null;
-  dm?: MatrixConfig["dm"] | null;
-  groupPolicy?: MatrixConfig["groupPolicy"] | null;
-  groupAllowFrom?: MatrixConfig["groupAllowFrom"] | null;
-  groups?: MatrixConfig["groups"] | null;
-  rooms?: MatrixConfig["rooms"] | null;
-};
-
-function applyNullableStringField(
-  target: Record<string, unknown>,
-  key: keyof MatrixAccountPatch,
-  value: string | null | undefined,
-): void {
-  if (value === undefined) {
-    return;
-  }
-  if (value === null) {
-    delete target[key];
-    return;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    delete target[key];
-    return;
-  }
-  target[key] = trimmed;
-}
-
-function applyNullableSecretInputField(
-  target: Record<string, unknown>,
-  key: "accessToken" | "password",
-  value: MatrixConfig["accessToken"] | null | undefined,
-  defaults?: NonNullable<CoreConfig["secrets"]>["defaults"],
-): void {
-  if (value === undefined) {
-    return;
-  }
-  if (value === null) {
-    delete target[key];
-    return;
-  }
-  if (typeof value === "string") {
-    const normalized = normalizeSecretInputString(value);
-    if (normalized) {
-      target[key] = normalized;
-    } else {
-      delete target[key];
-    }
-    return;
-  }
-
-  const ref = coerceSecretRef(value, defaults);
-  if (!ref) {
-    throw new Error(`Invalid Matrix ${key} SecretInput.`);
-  }
-  target[key] = ref;
-}
-
-function cloneMatrixDmConfig(dm: MatrixConfig["dm"]): MatrixConfig["dm"] {
-  if (!dm) {
-    return dm;
-  }
-  return {
-    ...dm,
-    ...(dm.allowFrom ? { allowFrom: [...dm.allowFrom] } : {}),
-  };
-}
-
-function cloneMatrixRoomMap(rooms: MatrixConfig["groups"]): MatrixConfig["groups"] {
-  if (!rooms) {
-    return rooms;
-  }
-  const clonedRoomEntries: Array<[string, NonNullable<MatrixConfig["groups"]>[string]]> = [];
-  for (const [roomId, roomCfg] of Object.entries(rooms)) {
-    clonedRoomEntries.push([roomId, roomCfg ? { ...roomCfg } : roomCfg]);
-  }
-  return Object.fromEntries(clonedRoomEntries);
-}
-
-function applyNullableArrayField(
-  target: Record<string, unknown>,
-  key: keyof MatrixAccountPatch,
-  value: Array<string | number> | null | undefined,
-): void {
-  if (value === undefined) {
-    return;
-  }
-  if (value === null) {
-    delete target[key];
-    return;
-  }
-  target[key] = [...value];
-}
-
-export function updateMatrixAccountConfig(
-  cfg: CoreConfig,
-  accountId: string,
-  patch: MatrixAccountPatch,
-): CoreConfig {
-  const matrix = cfg.channels?.matrix ?? {};
-  const normalizedAccountId = normalizeAccountId(accountId);
-  const existingAccount = (findMatrixAccountConfig(cfg, normalizedAccountId) ??
-    (normalizedAccountId === DEFAULT_ACCOUNT_ID ? matrix : {})) as MatrixConfig;
-  const nextAccount: Record<string, unknown> = { ...existingAccount };
-
-  if (patch.name !== undefined) {
-    if (patch.name === null) {
-      delete nextAccount.name;
-    } else {
-      const trimmed = patch.name.trim();
-      if (trimmed) {
-        nextAccount.name = trimmed;
-      } else {
-        delete nextAccount.name;
-      }
-    }
-  }
-  if (typeof patch.enabled === "boolean") {
-    nextAccount.enabled = patch.enabled;
-  } else if (typeof nextAccount.enabled !== "boolean") {
-    nextAccount.enabled = true;
-  }
-
-  applyNullableStringField(nextAccount, "homeserver", patch.homeserver);
-  applyNullableStringField(nextAccount, "proxy", patch.proxy);
-  applyNullableStringField(nextAccount, "userId", patch.userId);
-  applyNullableSecretInputField(
-    nextAccount,
-    "accessToken",
-    patch.accessToken,
-    cfg.secrets?.defaults,
-  );
-  applyNullableSecretInputField(nextAccount, "password", patch.password, cfg.secrets?.defaults);
-  applyNullableStringField(nextAccount, "deviceId", patch.deviceId);
-  applyNullableStringField(nextAccount, "deviceName", patch.deviceName);
-  applyNullableStringField(nextAccount, "avatarUrl", patch.avatarUrl);
-
-  if (patch.allowPrivateNetwork !== undefined) {
-    const nextNetwork =
-      nextAccount.network && typeof nextAccount.network === "object"
-        ? { ...(nextAccount.network as Record<string, unknown>) }
-        : {};
-    if (patch.allowPrivateNetwork === null) {
-      delete nextNetwork.dangerouslyAllowPrivateNetwork;
-    } else {
-      nextNetwork.dangerouslyAllowPrivateNetwork = patch.allowPrivateNetwork;
-    }
-    if (Object.keys(nextNetwork).length > 0) {
-      nextAccount.network = nextNetwork;
-    } else {
-      delete nextAccount.network;
-    }
-  }
-
-  if (patch.initialSyncLimit !== undefined) {
-    if (patch.initialSyncLimit === null) {
-      delete nextAccount.initialSyncLimit;
-    } else {
-      nextAccount.initialSyncLimit = Math.max(0, Math.floor(patch.initialSyncLimit));
-    }
-  }
-
-  if (patch.encryption !== undefined) {
-    if (patch.encryption === null) {
-      delete nextAccount.encryption;
-    } else {
-      nextAccount.encryption = patch.encryption;
-    }
-  }
-  if (patch.allowBots !== undefined) {
-    if (patch.allowBots === null) {
-      delete nextAccount.allowBots;
-    } else {
-      nextAccount.allowBots = patch.allowBots;
-    }
-  }
-  if (patch.autoJoin !== undefined) {
-    if (patch.autoJoin === null) {
-      delete nextAccount.autoJoin;
-    } else {
-      nextAccount.autoJoin = patch.autoJoin;
-    }
-  }
-  applyNullableArrayField(nextAccount, "autoJoinAllowlist", patch.autoJoinAllowlist);
-  if (patch.dm !== undefined) {
-    if (patch.dm === null) {
-      delete nextAccount.dm;
-    } else {
-      nextAccount.dm = cloneMatrixDmConfig({
-        ...(nextAccount.dm as MatrixConfig["dm"] | undefined),
-        ...patch.dm,
-      });
-    }
-  }
-  if (patch.groupPolicy !== undefined) {
-    if (patch.groupPolicy === null) {
-      delete nextAccount.groupPolicy;
-    } else {
-      nextAccount.groupPolicy = patch.groupPolicy;
-    }
-  }
-  applyNullableArrayField(nextAccount, "groupAllowFrom", patch.groupAllowFrom);
-  if (patch.groups !== undefined) {
-    if (patch.groups === null) {
-      delete nextAccount.groups;
-    } else {
-      nextAccount.groups = cloneMatrixRoomMap(patch.groups);
-    }
-  }
-  if (patch.rooms !== undefined) {
-    if (patch.rooms === null) {
-      delete nextAccount.rooms;
-    } else {
-      nextAccount.rooms = cloneMatrixRoomMap(patch.rooms);
-    }
-  }
-
-  const nextAccounts = Object.fromEntries(
-    Object.entries(matrix.accounts ?? {}).filter(
-      ([rawAccountId]) =>
-        rawAccountId === normalizedAccountId ||
-        normalizeAccountId(rawAccountId) !== normalizedAccountId,
-    ),
-  );
-
-  if (shouldStoreMatrixAccountAtTopLevel(cfg, normalizedAccountId)) {
-    const { accounts: _ignoredAccounts, defaultAccount } = matrix;
-    const {
-      accounts: _ignoredNextAccounts,
-      defaultAccount: _ignoredNextDefaultAccount,
-      ...topLevelAccount
-    } = nextAccount;
-    return {
-      ...cfg,
-      channels: {
-        ...cfg.channels,
-        matrix: {
-          ...(defaultAccount ? { defaultAccount } : {}),
-          enabled: true,
-          ...topLevelAccount,
-        },
-      },
-    };
-  }
-
-  return {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      matrix: {
-        ...matrix,
-        enabled: true,
-        accounts: {
-          ...nextAccounts,
-          [normalizedAccountId]: nextAccount as MatrixConfig,
-        },
-      },
-    },
-  };
-}