@w3streamdev/plugin-core 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,217 @@
+interface PluginInfraConfig {
+    /** Base URL of your @w3stream/plugin-server deployment */
+    serverURL: string;
+    /** Org-scoped API key for the plugin server */
+    apiKey: string;
+    /** Your RTK organization ID */
+    orgId: string;
+    /** Set to true in development — enables devURL override from server */
+    devMode?: boolean;
+}
+/** Shape returned by GET /v2/plugins/user */
+interface ServerPluginRecord {
+    id: string;
+    name: string;
+    description: string;
+    picture: string;
+    /** The custom self-hosted URL — this is the whole point */
+    baseURL: string;
+    organizationId: string;
+    published: boolean;
+    private: boolean;
+    staggered: boolean;
+    tags: string[];
+    type: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * @w3stream/plugin-core — StoreSyncManager
+ *
+ * Maintains in-memory store state per plugin and synchronizes updates
+ * across local iframes and remote peers via RTK data channel.
+ *
+ * Reference: PRD Section 4.7
+ */
+
+declare class StoreSyncManager {
+    private meeting;
+    /** pluginId → storeName → key → value */
+    private stores;
+    /** pluginId → viewId → W3PostMessageBridge */
+    private bridges;
+    constructor(meeting: unknown);
+    /**
+     * Register a bridge so store updates can be forwarded to its iframe.
+     */
+    registerBridge(pluginId: string, viewId: string, bridge: W3PostMessageBridge): void;
+    /**
+     * Unregister a bridge when the plugin view is removed.
+     */
+    unregisterBridge(pluginId: string, viewId: string): void;
+    /**
+     * Returns the current snapshot of a named store for a plugin.
+     */
+    getStoreSnapshot(pluginId: string, storeName: string): Record<string, unknown>;
+    /**
+     * 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: string, storeName: string, key: string, value: unknown, fromPeerId: string, originViewId?: string): void;
+    /**
+     * 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: string, storeName: string, key: string, value: unknown, fromPeerId: string): void;
+    /**
+     * Listen for incoming store updates from remote peers via RTK data channel.
+     * Call this once after constructing the StoreSyncManager.
+     */
+    listenForRemoteUpdates(): void;
+}
+
+/**
+ * @w3stream/plugin-core — W3PostMessageBridge (host side)
+ *
+ * Host-side mirror of the PostMessageTransport in @w3stream/plugin-sdk.
+ * Manages the full handshake lifecycle between the host page and plugin iframe.
+ *
+ * Sequence (per PRD Section 2.2 and 4.6):
+ * 1. new W3PostMessageBridge(plugin, iframe, viewId, meeting) — on addPluginView()
+ * 2. connect() — attach window.addEventListener('message', handleMessage)
+ * 3. Wait for 'PLUGIN_READY' from iframe
+ * 4. Send 'PLUGIN_INIT' with full meeting context
+ * 5. Plugin SDK resolves init() → fires 'ready' event
+ *
+ * Reference: PRD Section 4.6
+ */
+
+declare class W3PostMessageBridge {
+    private iframe;
+    private viewId;
+    private pluginId;
+    private plugin;
+    private meeting;
+    private storeSync;
+    private messageHandler;
+    private connected;
+    constructor(plugin: unknown, iframe: HTMLIFrameElement, viewId: string, meeting: unknown, storeSync?: StoreSyncManager);
+    connect(): void;
+    destroy(): void;
+    /** Send PLUGIN_DATA to the iframe */
+    send(eventName: string, data?: unknown): void;
+    /** Send PLUGIN_CLOSE to the iframe */
+    sendClose(): void;
+    /** Send a STORE_UPDATE to this iframe */
+    sendStoreUpdate(storeName: string, key: string, value: unknown, fromPeerId: string): void;
+    private handleMessage;
+    private sendInit;
+}
+
+/**
+ * @w3stream/plugin-core — W3PluginObject
+ *
+ * Factory function returning an RTKPlugin-compatible object that
+ * <rtk-plugins>, <rtk-plugin-main>, and <rtk-plugins-toggle> can use
+ * without modification.
+ *
+ * Reference: PRD Section 4.5
+ */
+
+interface W3PluginObject {
+    id: string;
+    name: string;
+    description: string;
+    picture: string;
+    baseURL: string;
+    organizationId: string;
+    published: boolean;
+    private: boolean;
+    staggered: boolean;
+    tags: string[];
+    type: string;
+    createdAt: Date;
+    updatedAt: Date;
+    config: unknown;
+    active: boolean;
+    enabledBy: string;
+    iframes: Map<string, HTMLIFrameElement>;
+    _bridges: Map<string, W3PostMessageBridge>;
+    activate: () => Promise<void>;
+    deactivate: () => Promise<void>;
+    activateForSelf: () => Promise<void>;
+    deactivateForSelf: () => void;
+    enable: () => Promise<void>;
+    disable: () => void;
+    addPluginView: (iframe: HTMLIFrameElement, viewId?: string) => void;
+    removePluginView: (viewId?: string) => void;
+    sendData: (payload: {
+        eventName: string;
+        data?: unknown;
+    }) => void;
+    sendIframeEvent: (message: unknown) => void;
+    on: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    off: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    once: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    emit: (event: string, ...args: unknown[]) => boolean;
+    addListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    removeListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    removeAllListeners: (event?: string) => W3PluginObject;
+    listeners: (event: string) => ((...args: unknown[]) => void)[];
+    listenerCount: (event: string) => number;
+    eventNames: () => (string | symbol)[];
+    setMaxListeners: (n: number) => W3PluginObject;
+    getMaxListeners: () => number;
+    rawListeners: (event: string) => ((...args: unknown[]) => void)[];
+    prependListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    prependOnceListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    telemetry: Record<string, unknown>;
+    logger: typeof console;
+}
+declare function createW3PluginObject(serverPlugin: ServerPluginRecord, meeting: unknown, _config: PluginInfraConfig, storeSync?: StoreSyncManager): W3PluginObject;
+
+/**
+ * @w3stream/plugin-core — PluginManager
+ *
+ * Fetches plugins from your plugin server, builds RTKPlugin-compatible objects,
+ * and patches the meeting object so <rtk-plugins>, <rtk-plugin-main>, and
+ * <rtk-plugins-toggle> work against your own infrastructure.
+ *
+ * Reference: PRD Section 4 — Package 3: @w3stream/plugin-core
+ */
+
+declare class PluginList {
+    private items;
+    private listeners;
+    toArray(): W3PluginObject[];
+    addListener(event: string, callback: (...args: unknown[]) => void): void;
+    removeListener(event: string, callback: (...args: unknown[]) => void): void;
+    _setItems(items: W3PluginObject[]): void;
+    _addItem(item: W3PluginObject): void;
+    _removeItem(id: string): void;
+}
+/**
+ * Patches meeting.plugins with a W3PluginManager backed by your plugin server.
+ *
+ * Steps:
+ * 1. Fetch plugin records from your server
+ * 2. Create RTKPlugin-compatible objects for each
+ * 3. Set up store sync manager for cross-peer store propagation
+ * 4. Replace meeting.plugins.all and meeting.plugins.active
+ * 5. Listen for activation/deactivation broadcasts from peers
+ */
+declare function patchMeeting(meeting: unknown, config: PluginInfraConfig): Promise<void>;
+/**
+ * Convenience wrapper: init the meeting AND patch it in one call.
+ *
+ * Usage:
+ *   const meeting = await initWithPlugins(rtkInitOptions, pluginConfig)
+ */
+declare function initWithPlugins(rtkInitOptions: Record<string, unknown>, pluginConfig: PluginInfraConfig): Promise<unknown>;
+
+export { type PluginInfraConfig, PluginList, type ServerPluginRecord, StoreSyncManager, type W3PluginObject, W3PostMessageBridge, createW3PluginObject, initWithPlugins, patchMeeting };

package/dist/index.d.ts

@@ -0,0 +1,217 @@
+interface PluginInfraConfig {
+    /** Base URL of your @w3stream/plugin-server deployment */
+    serverURL: string;
+    /** Org-scoped API key for the plugin server */
+    apiKey: string;
+    /** Your RTK organization ID */
+    orgId: string;
+    /** Set to true in development — enables devURL override from server */
+    devMode?: boolean;
+}
+/** Shape returned by GET /v2/plugins/user */
+interface ServerPluginRecord {
+    id: string;
+    name: string;
+    description: string;
+    picture: string;
+    /** The custom self-hosted URL — this is the whole point */
+    baseURL: string;
+    organizationId: string;
+    published: boolean;
+    private: boolean;
+    staggered: boolean;
+    tags: string[];
+    type: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * @w3stream/plugin-core — StoreSyncManager
+ *
+ * Maintains in-memory store state per plugin and synchronizes updates
+ * across local iframes and remote peers via RTK data channel.
+ *
+ * Reference: PRD Section 4.7
+ */
+
+declare class StoreSyncManager {
+    private meeting;
+    /** pluginId → storeName → key → value */
+    private stores;
+    /** pluginId → viewId → W3PostMessageBridge */
+    private bridges;
+    constructor(meeting: unknown);
+    /**
+     * Register a bridge so store updates can be forwarded to its iframe.
+     */
+    registerBridge(pluginId: string, viewId: string, bridge: W3PostMessageBridge): void;
+    /**
+     * Unregister a bridge when the plugin view is removed.
+     */
+    unregisterBridge(pluginId: string, viewId: string): void;
+    /**
+     * Returns the current snapshot of a named store for a plugin.
+     */
+    getStoreSnapshot(pluginId: string, storeName: string): Record<string, unknown>;
+    /**
+     * 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: string, storeName: string, key: string, value: unknown, fromPeerId: string, originViewId?: string): void;
+    /**
+     * 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: string, storeName: string, key: string, value: unknown, fromPeerId: string): void;
+    /**
+     * Listen for incoming store updates from remote peers via RTK data channel.
+     * Call this once after constructing the StoreSyncManager.
+     */
+    listenForRemoteUpdates(): void;
+}
+
+/**
+ * @w3stream/plugin-core — W3PostMessageBridge (host side)
+ *
+ * Host-side mirror of the PostMessageTransport in @w3stream/plugin-sdk.
+ * Manages the full handshake lifecycle between the host page and plugin iframe.
+ *
+ * Sequence (per PRD Section 2.2 and 4.6):
+ * 1. new W3PostMessageBridge(plugin, iframe, viewId, meeting) — on addPluginView()
+ * 2. connect() — attach window.addEventListener('message', handleMessage)
+ * 3. Wait for 'PLUGIN_READY' from iframe
+ * 4. Send 'PLUGIN_INIT' with full meeting context
+ * 5. Plugin SDK resolves init() → fires 'ready' event
+ *
+ * Reference: PRD Section 4.6
+ */
+
+declare class W3PostMessageBridge {
+    private iframe;
+    private viewId;
+    private pluginId;
+    private plugin;
+    private meeting;
+    private storeSync;
+    private messageHandler;
+    private connected;
+    constructor(plugin: unknown, iframe: HTMLIFrameElement, viewId: string, meeting: unknown, storeSync?: StoreSyncManager);
+    connect(): void;
+    destroy(): void;
+    /** Send PLUGIN_DATA to the iframe */
+    send(eventName: string, data?: unknown): void;
+    /** Send PLUGIN_CLOSE to the iframe */
+    sendClose(): void;
+    /** Send a STORE_UPDATE to this iframe */
+    sendStoreUpdate(storeName: string, key: string, value: unknown, fromPeerId: string): void;
+    private handleMessage;
+    private sendInit;
+}
+
+/**
+ * @w3stream/plugin-core — W3PluginObject
+ *
+ * Factory function returning an RTKPlugin-compatible object that
+ * <rtk-plugins>, <rtk-plugin-main>, and <rtk-plugins-toggle> can use
+ * without modification.
+ *
+ * Reference: PRD Section 4.5
+ */
+
+interface W3PluginObject {
+    id: string;
+    name: string;
+    description: string;
+    picture: string;
+    baseURL: string;
+    organizationId: string;
+    published: boolean;
+    private: boolean;
+    staggered: boolean;
+    tags: string[];
+    type: string;
+    createdAt: Date;
+    updatedAt: Date;
+    config: unknown;
+    active: boolean;
+    enabledBy: string;
+    iframes: Map<string, HTMLIFrameElement>;
+    _bridges: Map<string, W3PostMessageBridge>;
+    activate: () => Promise<void>;
+    deactivate: () => Promise<void>;
+    activateForSelf: () => Promise<void>;
+    deactivateForSelf: () => void;
+    enable: () => Promise<void>;
+    disable: () => void;
+    addPluginView: (iframe: HTMLIFrameElement, viewId?: string) => void;
+    removePluginView: (viewId?: string) => void;
+    sendData: (payload: {
+        eventName: string;
+        data?: unknown;
+    }) => void;
+    sendIframeEvent: (message: unknown) => void;
+    on: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    off: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    once: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    emit: (event: string, ...args: unknown[]) => boolean;
+    addListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    removeListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    removeAllListeners: (event?: string) => W3PluginObject;
+    listeners: (event: string) => ((...args: unknown[]) => void)[];
+    listenerCount: (event: string) => number;
+    eventNames: () => (string | symbol)[];
+    setMaxListeners: (n: number) => W3PluginObject;
+    getMaxListeners: () => number;
+    rawListeners: (event: string) => ((...args: unknown[]) => void)[];
+    prependListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    prependOnceListener: (event: string, cb: (...args: unknown[]) => void) => W3PluginObject;
+    telemetry: Record<string, unknown>;
+    logger: typeof console;
+}
+declare function createW3PluginObject(serverPlugin: ServerPluginRecord, meeting: unknown, _config: PluginInfraConfig, storeSync?: StoreSyncManager): W3PluginObject;
+
+/**
+ * @w3stream/plugin-core — PluginManager
+ *
+ * Fetches plugins from your plugin server, builds RTKPlugin-compatible objects,
+ * and patches the meeting object so <rtk-plugins>, <rtk-plugin-main>, and
+ * <rtk-plugins-toggle> work against your own infrastructure.
+ *
+ * Reference: PRD Section 4 — Package 3: @w3stream/plugin-core
+ */
+
+declare class PluginList {
+    private items;
+    private listeners;
+    toArray(): W3PluginObject[];
+    addListener(event: string, callback: (...args: unknown[]) => void): void;
+    removeListener(event: string, callback: (...args: unknown[]) => void): void;
+    _setItems(items: W3PluginObject[]): void;
+    _addItem(item: W3PluginObject): void;
+    _removeItem(id: string): void;
+}
+/**
+ * Patches meeting.plugins with a W3PluginManager backed by your plugin server.
+ *
+ * Steps:
+ * 1. Fetch plugin records from your server
+ * 2. Create RTKPlugin-compatible objects for each
+ * 3. Set up store sync manager for cross-peer store propagation
+ * 4. Replace meeting.plugins.all and meeting.plugins.active
+ * 5. Listen for activation/deactivation broadcasts from peers
+ */
+declare function patchMeeting(meeting: unknown, config: PluginInfraConfig): Promise<void>;
+/**
+ * Convenience wrapper: init the meeting AND patch it in one call.
+ *
+ * Usage:
+ *   const meeting = await initWithPlugins(rtkInitOptions, pluginConfig)
+ */
+declare function initWithPlugins(rtkInitOptions: Record<string, unknown>, pluginConfig: PluginInfraConfig): Promise<unknown>;
+
+export { type PluginInfraConfig, PluginList, type ServerPluginRecord, StoreSyncManager, type W3PluginObject, W3PostMessageBridge, createW3PluginObject, initWithPlugins, patchMeeting };