@w3streamdev/plugin-core 1.0.0

package/dist/index.mjs

@@ -0,0 +1,571 @@
+// src/plugin-object.ts
+import { EventEmitter } from "eventemitter3";
+
+// src/postmessage-bridge.ts
+var PROTOCOL_NAMESPACE = "_w3stream";
+var W3PostMessageBridge = class {
+  constructor(plugin, iframe, viewId, meeting, storeSync) {
+    this.messageHandler = null;
+    this.connected = false;
+    this.plugin = plugin;
+    this.iframe = iframe;
+    this.viewId = viewId;
+    this.pluginId = plugin.id;
+    this.meeting = meeting;
+    this.storeSync = storeSync;
+  }
+  connect() {
+    if (this.connected) return;
+    this.connected = true;
+    this.messageHandler = this.handleMessage.bind(this);
+    window.addEventListener("message", this.messageHandler);
+  }
+  destroy() {
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+    this.connected = false;
+  }
+  /** Send PLUGIN_DATA to the iframe */
+  send(eventName, data) {
+    this.iframe.contentWindow?.postMessage(
+      {
+        type: "PLUGIN_DATA",
+        pluginId: this.pluginId,
+        viewId: this.viewId,
+        eventName,
+        data,
+        [PROTOCOL_NAMESPACE]: true
+      },
+      "*"
+    );
+  }
+  /** Send PLUGIN_CLOSE to the iframe */
+  sendClose() {
+    this.iframe.contentWindow?.postMessage(
+      {
+        type: "PLUGIN_CLOSE",
+        pluginId: this.pluginId,
+        viewId: this.viewId,
+        [PROTOCOL_NAMESPACE]: true
+      },
+      "*"
+    );
+  }
+  /** Send a STORE_UPDATE to this iframe */
+  sendStoreUpdate(storeName, key, value, fromPeerId) {
+    this.iframe.contentWindow?.postMessage(
+      {
+        type: "STORE_UPDATE",
+        pluginId: this.pluginId,
+        storeName,
+        key,
+        value,
+        fromPeerId,
+        [PROTOCOL_NAMESPACE]: true
+      },
+      "*"
+    );
+  }
+  handleMessage(event) {
+    const msg = event.data;
+    if (!msg || msg[PROTOCOL_NAMESPACE] !== true) return;
+    if (msg["pluginId"] !== this.pluginId) return;
+    if (event.source !== this.iframe.contentWindow) return;
+    switch (msg["type"]) {
+      case "PLUGIN_READY":
+        this.sendInit();
+        break;
+      case "PLUGIN_EVENT": {
+        const eventName = msg["eventName"];
+        const data = msg["data"];
+        this.plugin.emit(eventName, data);
+        break;
+      }
+      case "STORE_POPULATE": {
+        const storeName = msg["storeName"];
+        if (this.storeSync) {
+          const snapshot = this.storeSync.getStoreSnapshot(
+            this.pluginId,
+            storeName
+          );
+          this.iframe.contentWindow?.postMessage(
+            {
+              type: "STORE_DATA",
+              pluginId: this.pluginId,
+              storeName,
+              data: snapshot,
+              [PROTOCOL_NAMESPACE]: true
+            },
+            "*"
+          );
+        }
+        break;
+      }
+      case "STORE_UPDATE": {
+        const storeName = msg["storeName"];
+        const key = msg["key"];
+        const value = msg["value"];
+        const selfPeerId = this.meeting.self?.id ?? "";
+        if (this.storeSync) {
+          this.storeSync.applyUpdate(
+            this.pluginId,
+            storeName,
+            key,
+            value,
+            selfPeerId,
+            this.viewId
+            // origin viewId to avoid echo
+          );
+        }
+        break;
+      }
+    }
+  }
+  sendInit() {
+    const m = this.meeting;
+    const participants = m.participants?.joined?.toArray?.() ?? m.participants?.active?.toArray?.() ?? [];
+    const peers = participants.map((p) => ({
+      id: p.id ?? "",
+      name: p.name ?? "",
+      picture: p.picture,
+      isHost: false,
+      customParticipantId: p.customParticipantId
+    }));
+    const initMsg = {
+      type: "PLUGIN_INIT",
+      pluginId: this.pluginId,
+      viewId: this.viewId,
+      authToken: m.__authToken ?? "",
+      meetingId: m.meta?.meetingId ?? "",
+      selfPeerId: m.self?.id ?? "",
+      selfName: m.self?.name ?? "",
+      enabledBy: this.plugin.enabledBy,
+      roomName: m.meta?.roomName ?? m.meta?.meetingTitle ?? "",
+      peers,
+      [PROTOCOL_NAMESPACE]: true
+    };
+    this.iframe.contentWindow?.postMessage(initMsg, "*");
+    this.plugin.emit("ready", { viewId: this.viewId });
+  }
+};
+
+// src/plugin-object.ts
+var W3_PLUGIN_ACTIVATE = "W3_PLUGIN_ACTIVATE";
+var W3_PLUGIN_DEACTIVATE = "W3_PLUGIN_DEACTIVATE";
+function createW3PluginObject(serverPlugin, meeting, _config, storeSync) {
+  const emitter = new EventEmitter();
+  const m = meeting;
+  const bridges = /* @__PURE__ */ new Map();
+  const iframes = /* @__PURE__ */ new Map();
+  const plugin = {
+    // Static fields from server
+    id: serverPlugin.id,
+    name: serverPlugin.name,
+    description: serverPlugin.description,
+    picture: serverPlugin.picture,
+    baseURL: serverPlugin.baseURL,
+    organizationId: serverPlugin.organizationId,
+    published: serverPlugin.published,
+    private: serverPlugin.private,
+    staggered: serverPlugin.staggered,
+    tags: serverPlugin.tags,
+    type: serverPlugin.type,
+    createdAt: new Date(serverPlugin.createdAt),
+    updatedAt: new Date(serverPlugin.updatedAt),
+    config: void 0,
+    // Runtime state
+    active: false,
+    enabledBy: "",
+    iframes,
+    _bridges: bridges,
+    // ── activate() — broadcast to all peers via RTK data channel ──
+    activate: async () => {
+      plugin.active = true;
+      plugin.enabledBy = m.self?.id ?? "";
+      m.participants?.broadcastMessage?.(W3_PLUGIN_ACTIVATE, {
+        pluginId: serverPlugin.id,
+        enabledBy: plugin.enabledBy
+      });
+      emitter.emit("enabled");
+    },
+    // ── deactivate() — broadcast to all peers ──
+    deactivate: async () => {
+      plugin.active = false;
+      for (const [viewId, bridge] of bridges) {
+        bridge.sendClose();
+        bridge.destroy();
+        storeSync?.unregisterBridge(serverPlugin.id, viewId);
+      }
+      bridges.clear();
+      iframes.clear();
+      m.participants?.broadcastMessage?.(W3_PLUGIN_DEACTIVATE, {
+        pluginId: serverPlugin.id
+      });
+      emitter.emit("closed");
+    },
+    // ── activateForSelf() — local only (staggered plugins) ──
+    activateForSelf: async () => {
+      plugin.active = true;
+      plugin.enabledBy = m.self?.id ?? "";
+      emitter.emit("enabled");
+    },
+    deactivateForSelf: () => {
+      plugin.active = false;
+      for (const [viewId, bridge] of bridges) {
+        bridge.sendClose();
+        bridge.destroy();
+        storeSync?.unregisterBridge(serverPlugin.id, viewId);
+      }
+      bridges.clear();
+      iframes.clear();
+      emitter.emit("closed");
+    },
+    // Deprecated aliases
+    enable: async () => plugin.activateForSelf(),
+    disable: () => plugin.deactivateForSelf(),
+    // ── addPluginView() — creates a W3PostMessageBridge ──
+    addPluginView: (iframe, viewId = "plugin-main") => {
+      if (bridges.has(viewId)) {
+        bridges.get(viewId).destroy();
+        storeSync?.unregisterBridge(serverPlugin.id, viewId);
+      }
+      iframes.set(viewId, iframe);
+      const bridge = new W3PostMessageBridge(
+        plugin,
+        iframe,
+        viewId,
+        meeting,
+        storeSync
+      );
+      bridges.set(viewId, bridge);
+      if (storeSync) {
+        storeSync.registerBridge(serverPlugin.id, viewId, bridge);
+      }
+      bridge.connect();
+    },
+    // ── removePluginView() ──
+    removePluginView: (viewId = "plugin-main") => {
+      const bridge = bridges.get(viewId);
+      if (bridge) {
+        bridge.destroy();
+        bridges.delete(viewId);
+        storeSync?.unregisterBridge(serverPlugin.id, viewId);
+      }
+      iframes.delete(viewId);
+    },
+    // ── sendData() — sends PLUGIN_DATA to all registered iframes ──
+    sendData: (payload) => {
+      for (const bridge of bridges.values()) {
+        bridge.send(payload.eventName, payload.data);
+      }
+    },
+    sendIframeEvent: (message) => {
+      const msg = message;
+      if (msg.eventName) {
+        plugin.sendData({ eventName: msg.eventName, data: msg.data });
+      }
+    },
+    // ── EventEmitter delegation ──
+    on: (event, cb) => {
+      emitter.on(event, cb);
+      return plugin;
+    },
+    off: (event, cb) => {
+      emitter.off(event, cb);
+      return plugin;
+    },
+    once: (event, cb) => {
+      emitter.once(event, cb);
+      return plugin;
+    },
+    emit: (event, ...args) => emitter.emit(event, ...args),
+    addListener: (event, cb) => {
+      emitter.on(event, cb);
+      return plugin;
+    },
+    removeListener: (event, cb) => {
+      emitter.off(event, cb);
+      return plugin;
+    },
+    removeAllListeners: (event) => {
+      if (event) emitter.removeAllListeners(event);
+      else emitter.removeAllListeners();
+      return plugin;
+    },
+    listeners: (event) => emitter.listeners(event),
+    listenerCount: (event) => emitter.listenerCount(event),
+    eventNames: () => emitter.eventNames(),
+    setMaxListeners: (_n) => plugin,
+    getMaxListeners: () => 10,
+    rawListeners: (event) => emitter.listeners(event),
+    prependListener: (event, cb) => {
+      emitter.on(event, cb);
+      return plugin;
+    },
+    prependOnceListener: (event, cb) => {
+      emitter.once(event, cb);
+      return plugin;
+    },
+    // No-op telemetry
+    telemetry: {},
+    logger: console
+  };
+  return plugin;
+}
+
+// src/store-sync.ts
+var W3_STORE_UPDATE = "W3_STORE_UPDATE";
+var StoreSyncManager = class {
+  constructor(meeting) {
+    /** pluginId → storeName → key → value */
+    this.stores = /* @__PURE__ */ new Map();
+    /** pluginId → viewId → W3PostMessageBridge */
+    this.bridges = /* @__PURE__ */ new Map();
+    this.meeting = meeting;
+  }
+  /**
+   * Register a bridge so store updates can be forwarded to its iframe.
+   */
+  registerBridge(pluginId, viewId, bridge) {
+    if (!this.bridges.has(pluginId)) this.bridges.set(pluginId, /* @__PURE__ */ new Map());
+    this.bridges.get(pluginId).set(viewId, bridge);
+  }
+  /**
+   * Unregister a bridge when the plugin view is removed.
+   */
+  unregisterBridge(pluginId, viewId) {
+    this.bridges.get(pluginId)?.delete(viewId);
+  }
+  /**
+   * Returns the current snapshot of a named store for a plugin.
+   */
+  getStoreSnapshot(pluginId, storeName) {
+    const pluginStores = this.stores.get(pluginId);
+    if (!pluginStores) return {};
+    const store = pluginStores.get(storeName);
+    if (!store) return {};
+    return Object.fromEntries(store.entries());
+  }
+  /**
+   * Apply a store update from a local iframe:
+   * 1. Update the in-memory store
+   * 2. Forward to all other local iframes for this plugin (excluding origin)
+   * 3. Broadcast to all remote peers via RTK data channel
+   */
+  applyUpdate(pluginId, storeName, key, value, fromPeerId, originViewId) {
+    if (!this.stores.has(pluginId)) this.stores.set(pluginId, /* @__PURE__ */ new Map());
+    const pluginStores = this.stores.get(pluginId);
+    if (!pluginStores.has(storeName)) pluginStores.set(storeName, /* @__PURE__ */ new Map());
+    pluginStores.get(storeName).set(key, value);
+    const pluginBridges = this.bridges.get(pluginId);
+    if (pluginBridges) {
+      for (const [viewId, bridge] of pluginBridges) {
+        if (viewId === originViewId) continue;
+        bridge.sendStoreUpdate(storeName, key, value, fromPeerId);
+      }
+    }
+    this.meeting.participants?.broadcastMessage?.(W3_STORE_UPDATE, {
+      pluginId,
+      storeName,
+      key,
+      value,
+      fromPeerId
+    });
+  }
+  /**
+   * Apply a store update received from a remote peer:
+   * 1. Update the in-memory store
+   * 2. Forward to all local iframes for this plugin
+   * (No re-broadcast — the sender already broadcast to all peers)
+   */
+  applyRemoteUpdate(pluginId, storeName, key, value, fromPeerId) {
+    if (!this.stores.has(pluginId)) this.stores.set(pluginId, /* @__PURE__ */ new Map());
+    const pluginStores = this.stores.get(pluginId);
+    if (!pluginStores.has(storeName)) pluginStores.set(storeName, /* @__PURE__ */ new Map());
+    pluginStores.get(storeName).set(key, value);
+    const pluginBridges = this.bridges.get(pluginId);
+    if (pluginBridges) {
+      for (const bridge of pluginBridges.values()) {
+        bridge.sendStoreUpdate(storeName, key, value, fromPeerId);
+      }
+    }
+  }
+  /**
+   * Listen for incoming store updates from remote peers via RTK data channel.
+   * Call this once after constructing the StoreSyncManager.
+   */
+  listenForRemoteUpdates() {
+    const participants = this.meeting.participants;
+    if (!participants?.on) return;
+    const handler = (...args) => {
+      let data;
+      if (args.length >= 2) {
+        data = args[1];
+      } else if (args.length === 1) {
+        data = args[0];
+      }
+      if (!data) return;
+      const payload = data["payload"] ?? data;
+      const type = data["type"] ?? payload["type"];
+      if (type !== W3_STORE_UPDATE) return;
+      const update = payload;
+      this.applyRemoteUpdate(
+        update.pluginId,
+        update.storeName,
+        update.key,
+        update.value,
+        update.fromPeerId
+      );
+    };
+    participants.on("broadcastedMessage", handler);
+    participants.on("dataMessage", handler);
+  }
+};
+
+// src/plugin-manager.ts
+var PluginList = class {
+  constructor() {
+    this.items = [];
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  toArray() {
+    return [...this.items];
+  }
+  addListener(event, callback) {
+    if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+    this.listeners.get(event).add(callback);
+  }
+  removeListener(event, callback) {
+    this.listeners.get(event)?.delete(callback);
+  }
+  _setItems(items) {
+    this.items = items;
+    this.listeners.get("stateUpdate")?.forEach((cb) => cb());
+  }
+  _addItem(item) {
+    this.items.push(item);
+    this.listeners.get("stateUpdate")?.forEach((cb) => cb());
+  }
+  _removeItem(id) {
+    this.items = this.items.filter((p) => p.id !== id);
+    this.listeners.get("stateUpdate")?.forEach((cb) => cb());
+  }
+};
+async function fetchPluginsFromServer(config) {
+  const res = await fetch(`${config.serverURL}/v2/plugins/user`, {
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      "Content-Type": "application/json",
+      ...config.devMode ? { "X-Dev-Mode": "true" } : {}
+    }
+  });
+  if (!res.ok) {
+    throw new Error(
+      `[plugin-core] Failed to fetch plugins: ${res.status} ${res.statusText}`
+    );
+  }
+  const json = await res.json();
+  return json.data;
+}
+async function patchMeeting(meeting, config) {
+  const m = meeting;
+  const serverPlugins = await fetchPluginsFromServer(config);
+  const storeSync = new StoreSyncManager(meeting);
+  storeSync.listenForRemoteUpdates();
+  const pluginObjects = serverPlugins.map(
+    (record) => createW3PluginObject(record, meeting, config, storeSync)
+  );
+  const all = new PluginList();
+  all._setItems(pluginObjects);
+  const active = new PluginList();
+  const pluginsProxy = {
+    all,
+    active
+  };
+  Object.defineProperty(m, "plugins", {
+    value: pluginsProxy,
+    writable: true,
+    configurable: true
+  });
+  if (m.participants?.on) {
+    const handleBroadcast = (...args) => {
+      let data;
+      if (args.length >= 2) {
+        data = args[1];
+      } else if (args.length === 1) {
+        data = args[0];
+      }
+      if (!data) return;
+      const payload = data["payload"] ?? data;
+      const type = data["type"] ?? payload["type"];
+      const pluginId = payload["pluginId"];
+      if (!pluginId) return;
+      const plugin = pluginObjects.find((p) => p.id === pluginId);
+      if (!plugin) return;
+      if (type === W3_PLUGIN_ACTIVATE) {
+        plugin.active = true;
+        plugin.enabledBy = payload["enabledBy"] ?? "";
+        plugin.emit("enabled");
+        if (!active.toArray().find((p) => p.id === pluginId)) {
+          active._addItem(plugin);
+        }
+      } else if (type === W3_PLUGIN_DEACTIVATE) {
+        plugin.active = false;
+        plugin.emit("closed");
+        active._removeItem(pluginId);
+      }
+    };
+    m.participants.on("broadcastedMessage", handleBroadcast);
+    m.participants.on("dataMessage", handleBroadcast);
+  }
+  for (const plugin of pluginObjects) {
+    const originalActivate = plugin.activate;
+    plugin.activate = async () => {
+      await originalActivate();
+      if (!active.toArray().find((p) => p.id === plugin.id)) {
+        active._addItem(plugin);
+      }
+    };
+    const originalDeactivate = plugin.deactivate;
+    plugin.deactivate = async () => {
+      await originalDeactivate();
+      active._removeItem(plugin.id);
+    };
+    const originalActivateForSelf = plugin.activateForSelf;
+    plugin.activateForSelf = async () => {
+      await originalActivateForSelf();
+      if (!active.toArray().find((p) => p.id === plugin.id)) {
+        active._addItem(plugin);
+      }
+    };
+    const originalDeactivateForSelf = plugin.deactivateForSelf;
+    plugin.deactivateForSelf = () => {
+      originalDeactivateForSelf();
+      active._removeItem(plugin.id);
+    };
+  }
+}
+async function initWithPlugins(rtkInitOptions, pluginConfig) {
+  let RealtimeKitClient;
+  try {
+    const rtk = await import("@cloudflare/realtimekit");
+    RealtimeKitClient = rtk.default ?? rtk;
+  } catch {
+    throw new Error(
+      "[plugin-core] @cloudflare/realtimekit must be installed to use initWithPlugins(). Install it or use patchMeeting() directly after initializing the meeting."
+    );
+  }
+  const meeting = await RealtimeKitClient.init(rtkInitOptions);
+  await patchMeeting(meeting, pluginConfig);
+  return meeting;
+}
+export {
+  PluginList,
+  StoreSyncManager,
+  W3PostMessageBridge,
+  createW3PluginObject,
+  initWithPlugins,
+  patchMeeting
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@w3streamdev/plugin-core",
+  "version": "1.0.0",
+  "description": "Host-side patch layer — wires @cloudflare/realtimekit into your plugin infrastructure",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@cloudflare/realtimekit": ">=0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/realtimekit": { "optional": false }
+  },
+  "dependencies": {
+    "eventemitter3": "^5.0.1"
+  },
+  "devDependencies": {
+    "@cloudflare/realtimekit": "latest",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "license": "MIT"
+}