ci: GitLab-Pipeline - build_embedded + manueller npm-Publish nach rohana (threadnet-call#1)

Registry-Entscheidung evidenzbasiert: das Package ist pnpm-Dependency von
ThreadNet-Webs apps/web, der Lockfile pinnt die Tarball-URL auf rohana -
Registry bleibt dort. Publish-Auth ueber CI-Variable GITEA_NPM_TOKEN statt
lokaler Klartext-.npmrc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sdk/README.md

@@ -0,0 +1,59 @@
+# SDK mode (EXPERIMENTAL)
+
+EC can be build in sdk mode. This will result in a compiled js file that can be imported in very simple webapps.
+
+It allows to use matrixRTC in combination with livekit without relying on element call.
+
+This is done by instantiating the call view model and exposing some useful behaviors (observables) and methods.
+
+This folder contains an example index.html file that showcases the sdk in use (hosted on localhost:8123 with a webserver allowing cors (for example `npx serve -l 81234 --cors`)) as a godot engine HTML export template.
+
+## Getting started
+
+To get started run
+
+```
+pnpm install
+pnpm build:sdk
+```
+
+in the repository root.
+
+It will create a `dist` folder containing the compiled js file.
+
+This file needs to be hosted. Locally (via `npx serve -l 81234 --cors`) or on a remote server.
+
+Now you just need to add the widget to element web via:
+
+```
+/addwidget http://localhost:3000?widgetId=$matrix_widget_id&perParticipantE2EE=true&userId=$matrix_user_id&deviceId=$org.matrix.msc3819.matrix_device_id&baseUrl=$org.matrix.msc4039.matrix_base_url&roomId=$matrix_room_id
+```
+
+## Widgets
+
+The sdk mode is particularly interesting to be used in widgets. In widgets you do not need to pay attention to matrix login/cs api ...
+To create a widget see the example `index.html` file in this folder. And add it to EW via:
+`/addwidget <widgetUrl>` (see **url parameters** for more details on `<widgetUrl>`)
+
+### url parameters
+
+The url parameters are needed to pass initial data to the widget. They will automatically be used
+by the matrixRTCSdk to start the postmessage widget api (communication between the client (e.g. Element Web) and the widget)
+
+```
+widgetId = $matrix_widget_id
+perParticipantE2EE = true
+userId = $matrix_user_id
+deviceId = $org.matrix.msc3819.matrix_device_id
+baseUrl = $org.matrix.msc4039.matrix_base_url
+```
+
+`parentUrl = // will be inserted automatically`
+
+Full template use as `<widgetUrl>`:
+
+```
+http://localhost:3000?widgetId=$matrix_widget_id&perParticipantE2EE=true&userId=$matrix_user_id&deviceId=$org.matrix.msc3819.matrix_device_id&baseUrl=$org.matrix.msc4039.matrix_base_url&roomId=$matrix_room_id
+```
+
+the `$` prefixed variables will be replaced by EW on widget instantiation. (e.g. `$matrix_user_id` -> `@user:example.com` (url encoding will also be applied automatically by EW) -> `%40user%3Aexample.com`)

sdk/helper.ts

@@ -0,0 +1,52 @@
+/*
+Copyright 2025 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * This file contains helper functions and types for the MatrixRTC SDK.
+ */
+
+import { logger as rootLogger } from "matrix-js-sdk/lib/logger";
+import { scan } from "rxjs";
+
+import { type WidgetHelpers } from "../src/widget";
+import { type LivekitRoomItem } from "../src/state/CallViewModel/CallViewModel";
+
+export const logger = rootLogger.getChild("[MatrixRTCSdk]");
+
+export const tryMakeSticky = (widget: WidgetHelpers): void => {
+  logger.info("try making sticky MatrixRTCSdk");
+  void widget.api
+    .setAlwaysOnScreen(true)
+    .then(() => {
+      logger.info("sticky MatrixRTCSdk");
+    })
+    .catch((error) => {
+      logger.error("failed to make sticky MatrixRTCSdk", error);
+    });
+};
+export const TEXT_LK_TOPIC = "matrixRTC";
+/**
+ * simple helper operator to combine the last emitted and the current emitted value of a rxjs observable
+ *
+ * I think there should be a builtin for this but i did not find it...
+ */
+export const currentAndPrev = scan<
+  LivekitRoomItem[],
+  {
+    prev: LivekitRoomItem[];
+    current: LivekitRoomItem[];
+  }
+>(
+  ({ current: lastCurrentVal }, items) => ({
+    prev: lastCurrentVal,
+    current: items,
+  }),
+  {
+    prev: [],
+    current: [],
+  },
+);

sdk/index.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<html>
+  <head>
+    <title>MatrixRTC Widget</title>
+    <meta charset="utf-8" />
+    <script type="module">
+      // TODO use the url where the matrixrtc-sdk.js file from dist is hosted
+      import { createMatrixRTCSdk } from "http://localhost:8123/matrixrtc-sdk.js";
+
+      try {
+        window.matrixRTCSdk = await createMatrixRTCSdk(
+          "com.github.toger5.rtc-application-type", // rtc application type
+        );
+        console.info("createMatrixRTCSdk was created!");
+      } catch (e) {
+        console.error("createMatrixRTCSdk", e);
+      }
+      const sdk = window.matrixRTCSdk;
+
+      console.info("matrixRTCSdk join ", sdk);
+      const connectionState = sdk.join();
+      console.info("matrixRTCSdk joined");
+
+      const div = document.getElementById("data");
+      div.innerHTML = "<h3>Data:</h3>";
+
+      sdk.data$.subscribe((data) => {
+        const child = document.createElement("p");
+        child.innerHTML = JSON.stringify(data);
+        div.appendChild(child);
+      });
+
+      sdk.members$.subscribe((memberObjects) => {
+        const div = document.getElementById("members");
+        div.innerHTML = "<h3>Members:</h3>";
+
+        // Create member list
+        const members = memberObjects.map((member) => member.membership.sender);
+        console.info("members changed", members);
+        for (const m of members) {
+          console.info("member", m);
+          const child = document.createElement("p");
+          child.innerHTML = m;
+          div.appendChild(child);
+        }
+      });
+
+      sdk.connected$.subscribe((connected) => {
+        console.info("connected changed", connected);
+        const div = document.getElementById("connect_status");
+        div.innerHTML = connected ? "Connected" : "Disconnected";
+      });
+    </script>
+  </head>
+  <body>
+    <div
+      style="position: absolute; top: 0; right: 0; background-color: #ffffff10"
+    >
+      <div id="connect_status"></div>
+      <button onclick="window.matrixRTCSdk.leave()">Leave</button>
+      <button onclick="window.matrixRTCSdk.sendData({ prop: 'Hello, world!' })">
+        Send Text
+      </button>
+      <div id="members"></div>
+      <div id="data"></div>
+    </div>
+  </body>
+</html>

sdk/main.ts

@@ -0,0 +1,368 @@
+/*
+Copyright 2025-2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * EXPERIMENTAL
+ *
+ * This file is the entrypoint for the sdk build of element call: `pnpm build:sdk`
+ * use in widgets.
+ * It exposes the `createMatrixRTCSdk` which creates the `MatrixRTCSdk` interface (see below) that
+ * can be used to join a rtc session and exchange realtime data.
+ * It takes care of all the tricky bits:
+ *  - sending delayed events
+ *  - finding the right sfu
+ *  - handling the media stream
+ *  - sending join/leave state or sticky events
+ *  - setting up encryption and scharing keys
+ */
+
+import {
+  combineLatest,
+  map,
+  type Observable,
+  of,
+  shareReplay,
+  Subject,
+  switchMap,
+  tap,
+} from "rxjs";
+import {
+  type CallMembership,
+  MatrixRTCSessionEvent,
+  MatrixRTCSessionManager,
+} from "matrix-js-sdk/lib/matrixrtc";
+import {
+  type Room as LivekitRoom,
+  type TextStreamReader,
+  type LocalParticipant,
+  type RemoteParticipant,
+} from "livekit-client";
+
+// TODO how can this get fixed? to just be part of `livekit-client`
+// Can this be done in the tsconfig.json
+import { type TextStreamInfo } from "../node_modules/livekit-client/dist/src/room/types";
+import { type Behavior, constant } from "../src/state/Behavior";
+import { createCallViewModel$ } from "../src/state/CallViewModel/CallViewModel";
+import { ObservableScope } from "../src/state/ObservableScope";
+import { getUrlParams } from "../src/UrlParams";
+import { MuteStates } from "../src/state/MuteStates";
+import { MediaDevices } from "../src/state/MediaDevices";
+import { E2eeType } from "../src/e2ee/e2eeType";
+import { currentAndPrev, logger, TEXT_LK_TOPIC, tryMakeSticky } from "./helper";
+import {
+  ElementWidgetActions,
+  widget as _widget,
+  initializeWidget,
+} from "../src/widget";
+import { type Connection } from "../src/state/CallViewModel/remoteMembers/Connection";
+
+interface MatrixRTCSdk {
+  /**
+   * observe connected$ to track the state.
+   * @returns
+   */
+  join: () => void;
+  /** @throws on leave errors */
+  leave: () => void;
+  /**
+   * Ends the rtc sdk. This will unsubscribe any event listeners. And end the associated scope.
+   * No updates can be received from the rtc sdk. The sdk cannot be restarted after.
+   * A new sdk needs to be created via createMatrixRTCSdk.
+   */
+  stop: () => void;
+  data$: Observable<{ rtcBackendIdentity: string; data: string }>;
+  /**
+   * flattened list of members
+   */
+  members$: Behavior<
+    {
+      connection: Connection | null;
+      membership: CallMembership;
+      participant: LocalParticipant | RemoteParticipant | null;
+    }[]
+  >;
+  /**
+   * flattened local members
+   */
+  localMember$: Behavior<{
+    connection: Connection | null;
+    membership: CallMembership;
+    participant: LocalParticipant | null;
+  } | null>;
+  /** Use the LocalMemberConnectionState returned from `join` for a more detailed connection state  */
+  connected$: Behavior<boolean>;
+  sendData?: (data: unknown) => Promise<void>;
+  sendRoomMessage?: (message: string) => Promise<void>;
+}
+
+export async function createMatrixRTCSdk(
+  application: string = "m.call",
+  id: string = "",
+  sticky: boolean = false,
+): Promise<MatrixRTCSdk> {
+  const scope = new ObservableScope();
+
+  // widget client
+  initializeWidget(application, true);
+  const widget = _widget;
+  if (!widget) throw Error("No widget. This webapp can only start as a widget");
+  const client = await widget.client;
+  logger.info("client created");
+
+  // url params
+  const { roomId } = getUrlParams();
+  if (roomId === null) throw Error("could not get roomId from url params");
+  const room = client.getRoom(roomId);
+  if (room === null) throw Error("could not get room from client");
+
+  // rtc session
+  const slot = { application, id };
+  const rtcSessionManager = new MatrixRTCSessionManager(logger, client, slot);
+  rtcSessionManager.start();
+  const rtcSession = rtcSessionManager.getRoomSession(room);
+
+  // media devices
+  const mediaDevices = new MediaDevices(scope);
+  const muteStates = new MuteStates(scope, mediaDevices, {
+    audioEnabled: false,
+    videoEnabled: false,
+  });
+
+  // call view model
+  const callViewModel = createCallViewModel$(
+    scope,
+    rtcSession,
+    room,
+    mediaDevices,
+    muteStates,
+    { encryptionSystem: { kind: E2eeType.PER_PARTICIPANT } },
+    of({}),
+    of({}),
+    constant({ supported: false, processor: undefined }),
+  );
+  logger.info("CallViewModelCreated");
+
+  // create data listener
+  const data$ = new Subject<{ rtcBackendIdentity: string; data: string }>();
+
+  const lkTextStreamHandlerFunction = async (
+    reader: TextStreamReader,
+    participantInfo: { identity: string },
+    livekitRoom: LivekitRoom,
+  ): Promise<void> => {
+    const info = reader.info;
+    logger.info(
+      `Received text stream from ${participantInfo.identity}\n` +
+        `  Topic: ${info.topic}\n` +
+        `  Timestamp: ${info.timestamp}\n` +
+        `  ID: ${info.id}\n` +
+        `  Size: ${info.size}`, // Optional, only available if the stream was sent with `sendText`
+    );
+
+    const participants = callViewModel.livekitRoomItems$.value.find(
+      (i) => i.livekitRoom === livekitRoom,
+    )?.participants;
+    if (participants && participants.includes(participantInfo.identity)) {
+      const text = await reader.readAll();
+      logger.info(`Received text: ${text}`);
+      data$.next({ rtcBackendIdentity: participantInfo.identity, data: text });
+    } else {
+      logger.warn(
+        "Received text from unknown participant",
+        participantInfo.identity,
+      );
+    }
+  };
+
+  const livekitRoomItemsSub = callViewModel.livekitRoomItems$
+    .pipe(
+      tap((beforecurrentAndPrev) => {
+        logger.info(
+          `LiveKit room items updated: ${beforecurrentAndPrev.length}`,
+          beforecurrentAndPrev,
+        );
+      }),
+      currentAndPrev,
+      tap((aftercurrentAndPrev) => {
+        logger.info(
+          `LiveKit room items updated: ${aftercurrentAndPrev.current.length}, ${aftercurrentAndPrev.prev.length}`,
+          aftercurrentAndPrev,
+        );
+      }),
+    )
+    .subscribe({
+      next: ({ prev, current }) => {
+        const prevRooms = prev.map((i) => i.livekitRoom);
+        const currentRooms = current.map((i) => i.livekitRoom);
+        const addedRooms = currentRooms.filter((r) => !prevRooms.includes(r));
+        const removedRooms = prevRooms.filter((r) => !currentRooms.includes(r));
+        addedRooms.forEach((r) => {
+          logger.info(`Registering text stream handler for room `);
+          r.registerTextStreamHandler(
+            TEXT_LK_TOPIC,
+            (reader, participantInfo) =>
+              void lkTextStreamHandlerFunction(reader, participantInfo, r),
+          );
+        });
+        removedRooms.forEach((r) => {
+          logger.info(`Unregistering text stream handler for room `);
+          r.unregisterTextStreamHandler(TEXT_LK_TOPIC);
+        });
+      },
+      complete: () => {
+        logger.info("Livekit room items subscription completed");
+        for (const item of callViewModel.livekitRoomItems$.value) {
+          logger.info("unregistering room item from room", item.url);
+          item.livekitRoom.unregisterTextStreamHandler(TEXT_LK_TOPIC);
+        }
+      },
+    });
+
+  // create sendData function
+  const sendFn: Behavior<(data: string) => Promise<TextStreamInfo>> =
+    scope.behavior(
+      callViewModel.localMatrixLivekitMember$.pipe(
+        switchMap((m) => {
+          if (!m)
+            return of((data: string): never => {
+              throw Error("local membership not yet ready.");
+            });
+          return m.participant.value$.pipe(
+            map((p) => {
+              if (p === null) {
+                return (data: string): never => {
+                  throw Error("local participant not yet ready to send data.");
+                };
+              } else {
+                return async (data: string): Promise<TextStreamInfo> =>
+                  p.sendText(data, { topic: TEXT_LK_TOPIC });
+              }
+            }),
+          );
+        }),
+      ),
+    );
+
+  const sendData = async (data: unknown): Promise<void> => {
+    const dataString = JSON.stringify(data);
+    logger.info("try sending: ", dataString);
+    try {
+      await Promise.resolve();
+      const info = await sendFn.value(dataString);
+      logger.info(`Sent text with stream ID: ${info.id}`);
+    } catch (e) {
+      logger.error("failed sending: ", dataString, e);
+    }
+  };
+
+  const sendRoomMessage = async (message: string): Promise<void> => {
+    const messageString = JSON.stringify(message);
+    logger.info("try sending to room: ", messageString);
+    try {
+      await client.sendTextMessage(room.roomId, message);
+    } catch (e) {
+      logger.error("failed sending to room: ", messageString, e);
+    }
+  };
+
+  // after hangup gets called
+  const leaveSubs = callViewModel.leave$.subscribe(() => {
+    const scheduleWidgetCloseOnLeave = async (): Promise<void> => {
+      const leaveResolver = Promise.withResolvers<void>();
+      logger.info("waiting for RTC leave");
+      rtcSession.on(MatrixRTCSessionEvent.JoinStateChanged, (isJoined) => {
+        logger.info("received RTC join update: ", isJoined);
+        if (!isJoined) leaveResolver.resolve();
+      });
+      await leaveResolver.promise;
+      logger.info("send Unstick");
+      await widget.api
+        .setAlwaysOnScreen(false)
+        .catch((e) =>
+          logger.error(
+            "Failed to set call widget `alwaysOnScreen` to false",
+            e,
+          ),
+        );
+      logger.info("send Close");
+      await widget.api.transport
+        .send(ElementWidgetActions.Close, {})
+        .catch((e) => logger.error("Failed to send close action", e));
+    };
+
+    // schedule close first and then leave (scope.end)
+    void scheduleWidgetCloseOnLeave();
+  });
+
+  logger.info("createMatrixRTCSdk done");
+
+  return {
+    join: (): void => {
+      // first lets try making the widget sticky
+      if (sticky) tryMakeSticky(widget);
+      callViewModel.join();
+    },
+    leave: (): void => {
+      callViewModel.leave();
+    },
+    stop: (): void => {
+      leaveSubs.unsubscribe();
+      livekitRoomItemsSub.unsubscribe();
+      scope.end();
+    },
+    data$,
+    localMember$: scope.behavior(
+      callViewModel.localMatrixLivekitMember$.pipe(
+        tap((member) =>
+          logger.info("localMatrixLivekitMember$ next: ", member),
+        ),
+        switchMap((member) => {
+          if (member === null) return of(null);
+          return combineLatest([
+            member.connection$,
+            member.membership$,
+            member.participant.value$,
+          ]).pipe(
+            map(([connection, membership, participant]) => ({
+              connection,
+              membership,
+              participant,
+            })),
+          );
+        }),
+        tap((member) => logger.info("localMember$ next: ", member)),
+      ),
+    ),
+    connected$: callViewModel.connected$,
+    members$: scope.behavior(
+      callViewModel.matrixLivekitMembers$.pipe(
+        switchMap((members) => {
+          const listOfMemberObservables = members.map((member) =>
+            combineLatest([
+              member.connection$,
+              member.membership$,
+              member.participant.value$,
+            ]).pipe(
+              map(([connection, membership, participant]) => ({
+                connection,
+                membership,
+                participant,
+              })),
+              // using shareReplay instead of a Behavior here because the behavior would need
+              // a tricky scope.end() setup.
+              shareReplay({ bufferSize: 1, refCount: true }),
+            ),
+          );
+          return combineLatest(listOfMemberObservables);
+        }),
+      ),
+      [],
+    ),
+    sendData,
+    sendRoomMessage,
+  };
+}