@kodelyth/matrix 2026.5.39 → 2026.5.42

package/src/matrix/profile.ts

@@ -0,0 +1,184 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "klaw/plugin-sdk/string-coerce-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.ts

@@ -0,0 +1,147 @@
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+
+export const MATRIX_ANNOTATION_RELATION_TYPE = "m.annotation";
+export const MATRIX_REACTION_EVENT_TYPE = "m.reaction";
+
+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[];
+};
+
+type MatrixReactionAnnotation = {
+  key: string;
+  eventId?: string;
+};
+
+type MatrixReactionEventLike = {
+  content?: unknown;
+  sender?: string | null;
+  event_id?: string | null;
+};
+
+function normalizeMatrixReactionMessageId(messageId: string): string {
+  const normalized = messageId.trim();
+  if (!normalized) {
+    throw new Error("Matrix reaction requires a messageId");
+  }
+  return normalized;
+}
+
+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 `/_matrix/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,
+  };
+}
+
+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;
+}