@schoolpalm/message-bridge 0.1.0

package/AUTHORS

@@ -0,0 +1,7 @@
+# Authors
+
+This project is maintained by the SchoolPalm development team.
+
+## Contributors
+
+- Hassan Mugabo <cybarox@gmail.com> - Lead Developer

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mugabo Hassan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+
+# @schoolpalm/message-bridge
+
+[![npm version](https://badge.fury.io/js/%40schoolpalm%2Fmessage-bridge.svg)](https://badge.fury.io/js/%40schoolpalm%2Fmessage-bridge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+TypeScript SDK for message-based communication between SchoolPalm host and vendor modules.
+
+## Overview
+
+The `@schoolpalm/message-bridge` SDK provides a robust, type-safe way to establish bidirectional communication between a host web application and embedded modules (typically iframes) using the browser's `postMessage` API. This enables seamless integration of third-party modules into the SchoolPalm platform while maintaining security through origin restrictions.
+
+## Features
+
+- **Type-safe messaging**: Full TypeScript support with strongly typed message payloads
+- **Bidirectional communication**: Send messages from host to module and vice versa
+- **Security-focused**: Origin restrictions and structured message protocols
+- **Event-driven architecture**: Register listeners for specific message types
+- **Lightweight**: Minimal dependencies, focused on core functionality
+- **Well-tested**: Comprehensive test suite with Vitest
+
+## Installation
+
+```bash
+npm install @schoolpalm/message-bridge
+```
+
+## Quick Start
+
+### Host Application
+
+```typescript
+import { HostBridge, MessageType } from '@schoolpalm/message-bridge';
+
+// Create a bridge for an embedded iframe
+const iframe = document.getElementById('module-iframe') as HTMLIFrameElement;
+const hostBridge = new HostBridge(iframe, 'https://module.example.com');
+
+// Start a module with context
+hostBridge.sendModuleStart({
+  route: '/dashboard',
+  context: { userId: 123, permissions: ['read', 'write'] },
+  timestamp: Date.now()
+});
+
+// Listen for UI updates from the module
+hostBridge.on(MessageType.UI_UPDATE, (payload) => {
+  document.title = payload.title;
+  updateBreadcrumb(payload.breadcrumb);
+});
+
+// Listen for data requests
+hostBridge.on(MessageType.DATA_REQUEST, (payload) => {
+  // Handle data request and send response
+  const response = fetchData(payload.action, payload.payload);
+  hostBridge.send(MessageType.DATA_RESPONSE, {
+    requestId: payload.requestId,
+    status: 'success',
+    payload: response
+  });
+});
+```
+
+### Embedded Module
+
+```typescript
+import { ModuleBridge, MessageType } from '@schoolpalm/message-bridge';
+
+// Create a bridge for the module
+const moduleBridge = new ModuleBridge('https://host.example.com');
+
+// Send handshake when ready
+moduleBridge.sendHandshake({
+  version: '1.0.0',
+  timestamp: Date.now()
+});
+
+// Listen for module start
+moduleBridge.on(MessageType.MODULE_START, (payload) => {
+  navigateToRoute(payload.route);
+  initializeWithContext(payload.context);
+});
+
+// Update host UI
+moduleBridge.sendUIUpdate({
+  title: 'User Management',
+  breadcrumb: ['Home', 'Users', 'Management'],
+  theme: 'dark'
+});
+
+// Request data from host
+moduleBridge.send(MessageType.DATA_REQUEST, {
+  requestId: 'user-list-123',
+  action: 'getUsers',
+  payload: { page: 1, limit: 20 }
+});
+```
+
+## API Reference
+
+### Classes
+
+- **`BridgeBase`**: Abstract base class providing core messaging functionality
+- **`HostBridge`**: Host-side bridge for communicating with embedded modules
+- **`ModuleBridge`**: Module-side bridge for communicating with the host application
+
+### Message Types
+
+The SDK defines a comprehensive set of message types for different communication scenarios:
+
+- `HANDSHAKE_READY`: Module signals readiness to the host
+- `MODULE_START`: Host initializes a module with context
+- `UI_UPDATE`: Module updates host UI (title, breadcrumb, theme)
+- `DATA_REQUEST`: Module requests data from host
+- `DATA_RESPONSE`: Host responds to data requests
+- `ERROR`: Module reports errors to host
+- `MODULE_EXIT`: Host signals module to clean up and exit
+
+### Payload Schemas
+
+All message payloads are strongly typed TypeScript interfaces:
+
+- `HandshakeReadyPayload`
+- `ModuleStartPayload`
+- `UIUpdatePayload`
+- `DataRequestPayload`
+- `DataResponsePayload`
+- `ErrorPayload`
+- `ModuleExitPayload`
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Main entry point and exports
+├── bridgeBase.ts     # Base bridge class with core functionality
+├── hostBridge.ts     # Host-side bridge implementation
+├── moduleBridge.ts   # Module-side bridge implementation
+├── messageTypes.ts   # Message type enumerations
+├── payloadSchemas.ts # TypeScript interfaces for payloads
+└── __tests__/
+    └── bridge.test.ts # Test suite
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 16+
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd message-bridge
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the project
+npm run build
+
+# Lint code
+npm run lint
+```
+
+### Scripts
+
+- `npm run build`: Compile TypeScript to JavaScript
+- `npm run watch`: Watch mode for development
+- `npm run test`: Run test suite
+- `npm run test:watch`: Run tests in watch mode
+- `npm run lint`: Lint and fix code style issues
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Authors
+
+See the [AUTHORS](AUTHORS) file for a list of contributors.
+
+## Support
+
+For questions or support, please contact the SchoolPalm development team.

package/TODO.md

@@ -0,0 +1,13 @@
+# TODO: Project Documentation and Enhancement
+
+## Tasks
+- [x] Enhance README.md with detailed documentation
+- [x] Add doc comments to src/index.ts
+- [x] Add doc comments to src/bridgeBase.ts
+- [x] Add doc comments to src/hostBridge.ts
+- [x] Add doc comments to src/moduleBridge.ts
+- [x] Add doc comments to src/messageTypes.ts
+- [x] Add doc comments to src/payloadSchemas.ts
+- [x] Add doc comments to src/__tests__/bridge.test.ts
+- [x] Create AUTHORS file for npm package
+- [x] Verify LICENSE and package.json setup

package/dist/__tests__/bridge.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Test suite for the MessageBridge SDK.
+ * @module @schoolpalm/message-bridge/__tests__/bridge.test
+ */
+export {};
+//# sourceMappingURL=bridge.test.d.ts.map

package/dist/__tests__/bridge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bridge.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/bridge.test.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Test suite for the MessageBridge SDK.
+ * @module @schoolpalm/message-bridge/__tests__/bridge.test
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { HostBridge, ModuleBridge, MessageType } from '../index';
+/**
+ * Test suite for the MessageBridge SDK.
+ *
+ * This suite tests the core functionality of both HostBridge and ModuleBridge
+ * classes, including message sending, receiving, and event handling.
+ */
+describe('MessageBridge SDK', () => {
+    let iframeMock;
+    beforeEach(() => {
+        // Simulate an iframe with contentWindow
+        iframeMock = {
+            contentWindow: {
+                postMessage: vi.fn()
+            }
+        };
+        // Mock parent window for ModuleBridge
+        vi.stubGlobal('parent', {
+            postMessage: vi.fn()
+        });
+    });
+    // -----------------------
+    // HostBridge Tests
+    // -----------------------
+    /**
+     * Test that HostBridge sends module-start messages correctly.
+     */
+    it('HostBridge sends module-start correctly', () => {
+        const hostBridge = new HostBridge(iframeMock);
+        hostBridge.sendModuleStart({ route: '/users', context: {}, timestamp: Date.now() });
+        expect(iframeMock.contentWindow.postMessage).toHaveBeenCalledTimes(1);
+        const callArg = iframeMock.contentWindow.postMessage.mock.calls[0][0];
+        expect(callArg.type).toBe(MessageType.MODULE_START);
+        expect(callArg.payload.route).toBe('/users');
+    });
+    /**
+     * Test that HostBridge can register listeners and receive messages.
+     */
+    it('HostBridge can register and receive messages', () => {
+        const hostBridge = new HostBridge(iframeMock);
+        const callback = vi.fn();
+        hostBridge.on(MessageType.UI_UPDATE, callback);
+        // Simulate incoming postMessage from iframe
+        const event = new MessageEvent('message', {
+            data: {
+                type: MessageType.UI_UPDATE,
+                payload: { title: 'Test', breadcrumb: ['Home'] }
+            }
+        });
+        window.dispatchEvent(event);
+        expect(callback).toHaveBeenCalledTimes(1);
+        expect(callback.mock.calls[0][0].title).toBe('Test');
+    });
+    // -----------------------
+    // ModuleBridge Tests
+    // -----------------------
+    /**
+     * Test that ModuleBridge sends handshake messages correctly.
+     */
+    it('ModuleBridge sends handshake correctly', () => {
+        const moduleBridge = new ModuleBridge();
+        moduleBridge.sendHandshake({ version: '0.1.0', timestamp: Date.now() });
+        expect(window.parent.postMessage).toHaveBeenCalledTimes(1);
+        const callArg = window.parent.postMessage.mock.calls[0][0];
+        expect(callArg.type).toBe(MessageType.HANDSHAKE_READY);
+        expect(callArg.payload.version).toBe('0.1.0');
+    });
+    /**
+     * Test that ModuleBridge sends UI update messages.
+     */
+    it('ModuleBridge sends UI update', () => {
+        const moduleBridge = new ModuleBridge();
+        moduleBridge.sendUIUpdate({ title: 'Users', breadcrumb: ['Home', 'Users'] });
+        const callArg = window.parent.postMessage.mock.calls[0][0];
+        expect(callArg.type).toBe(MessageType.UI_UPDATE);
+        expect(callArg.payload.breadcrumb.length).toBe(2);
+    });
+});
+//# sourceMappingURL=bridge.test.js.map

package/dist/__tests__/bridge.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.test.js","sourceRoot":"","sources":["../../src/__tests__/bridge.test.ts"],"names":[],"mappings":"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"}

package/dist/bridgeBase.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Base bridge class for message-based communication.
+ * @module @schoolpalm/message-bridge/bridgeBase
+ */
+import { MessageType } from './messageTypes';
+import { MessagePayload } from './payloadSchemas';
+/**
+ * Type definition for message handler functions.
+ * @template T - The type of message payload this handler accepts.
+ */
+type MessageHandler<T extends MessagePayload> = (payload: T) => void;
+/**
+ * Base class for Host and Module bridges.
+ *
+ * This abstract base class provides the core functionality for message-based
+ * communication between windows using the postMessage API. It handles sending
+ * messages, registering listeners, and managing event listeners.
+ *
+ * @example
+ * ```typescript
+ * class CustomBridge extends BridgeBase {
+ *   constructor(targetWindow: Window) {
+ *     super(targetWindow, 'https://example.com');
+ *   }
+ *
+ *   // Add custom methods here
+ * }
+ * ```
+ */
+export declare class BridgeBase {
+    /** The target window to send messages to. */
+    protected targetWindow: Window;
+    /** The origin to restrict messages to. */
+    protected targetOrigin: string;
+    /** Map of message type to array of handler functions. */
+    private listeners;
+    /**
+     * Creates a new BridgeBase instance.
+     * @param targetWindow - The window to send messages to.
+     * @param targetOrigin - The origin to restrict messages to (default: '*').
+     */
+    constructor(targetWindow: Window, targetOrigin?: string);
+    /**
+     * Sends a message to the target window.
+     * @template T - The type of the message payload.
+     * @param type - The message type to send.
+     * @param payload - The payload data to send.
+     */
+    send<T extends MessagePayload>(type: MessageType, payload: T): void;
+    /**
+     * Registers a listener for a specific message type.
+     * @template T - The type of the message payload.
+     * @param type - The message type to listen for.
+     * @param callback - The function to call when a message of this type is received.
+     */
+    on<T extends MessagePayload>(type: MessageType, callback: MessageHandler<T>): void;
+    /**
+     * Internal message handler for incoming postMessage events.
+     * @private
+     * @param event - The message event received.
+     */
+    private _handleMessage;
+    /**
+     * Cleans up event listeners and resources.
+     * Call this method when the bridge is no longer needed.
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=bridgeBase.d.ts.map

package/dist/bridgeBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeBase.d.ts","sourceRoot":"","sources":["../src/bridgeBase.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;GAGG;AACH,KAAK,cAAc,CAAC,CAAC,SAAS,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU;IACrB,6CAA6C;IAC7C,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;IAC/B,0CAA0C;IAC1C,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,OAAO,CAAC,SAAS,CAAsD;IAEvE;;;;OAIG;gBACS,YAAY,EAAE,MAAM,EAAE,YAAY,GAAE,MAAY;IAM5D;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IAI5D;;;;;OAKG;IACH,EAAE,CAAC,CAAC,SAAS,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC;IAK3E;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO;CAIR"}

package/dist/bridgeBase.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Base bridge class for message-based communication.
+ * @module @schoolpalm/message-bridge/bridgeBase
+ */
+/**
+ * Base class for Host and Module bridges.
+ *
+ * This abstract base class provides the core functionality for message-based
+ * communication between windows using the postMessage API. It handles sending
+ * messages, registering listeners, and managing event listeners.
+ *
+ * @example
+ * ```typescript
+ * class CustomBridge extends BridgeBase {
+ *   constructor(targetWindow: Window) {
+ *     super(targetWindow, 'https://example.com');
+ *   }
+ *
+ *   // Add custom methods here
+ * }
+ * ```
+ */
+export class BridgeBase {
+    /**
+     * Creates a new BridgeBase instance.
+     * @param targetWindow - The window to send messages to.
+     * @param targetOrigin - The origin to restrict messages to (default: '*').
+     */
+    constructor(targetWindow, targetOrigin = '*') {
+        /** Map of message type to array of handler functions. */
+        this.listeners = new Map();
+        this.targetWindow = targetWindow;
+        this.targetOrigin = targetOrigin;
+        window.addEventListener('message', this._handleMessage.bind(this));
+    }
+    /**
+     * Sends a message to the target window.
+     * @template T - The type of the message payload.
+     * @param type - The message type to send.
+     * @param payload - The payload data to send.
+     */
+    send(type, payload) {
+        this.targetWindow.postMessage({ type, payload }, this.targetOrigin);
+    }
+    /**
+     * Registers a listener for a specific message type.
+     * @template T - The type of the message payload.
+     * @param type - The message type to listen for.
+     * @param callback - The function to call when a message of this type is received.
+     */
+    on(type, callback) {
+        if (!this.listeners.has(type))
+            this.listeners.set(type, []);
+        this.listeners.get(type)?.push(callback);
+    }
+    /**
+     * Internal message handler for incoming postMessage events.
+     * @private
+     * @param event - The message event received.
+     */
+    _handleMessage(event) {
+        const { type, payload } = event.data || {};
+        if (!type || !this.listeners.has(type))
+            return;
+        this.listeners.get(type)?.forEach(cb => cb(payload));
+    }
+    /**
+     * Cleans up event listeners and resources.
+     * Call this method when the bridge is no longer needed.
+     */
+    destroy() {
+        window.removeEventListener('message', this._handleMessage.bind(this));
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=bridgeBase.js.map

package/dist/bridgeBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeBase.js","sourceRoot":"","sources":["../src/bridgeBase.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,UAAU;IAQrB;;;;OAIG;IACH,YAAY,YAAoB,EAAE,eAAuB,GAAG;QAR5D,yDAAyD;QACjD,cAAS,GAA4C,IAAI,GAAG,EAAE,CAAC;QAQrE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAA2B,IAAiB,EAAE,OAAU;QAC1D,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACH,EAAE,CAA2B,IAAiB,EAAE,QAA2B;QACzE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,KAAmB;QACxC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3C,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QAC/C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/hostBridge.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Host-side bridge for communication with embedded modules.
+ * @module @schoolpalm/message-bridge/hostBridge
+ */
+import { BridgeBase } from './bridgeBase';
+import { ModuleStartPayload } from './payloadSchemas';
+/**
+ * Host-side bridge for communication with embedded modules.
+ *
+ * This class extends BridgeBase to provide host-specific functionality for
+ * communicating with modules embedded in iframes. It handles initialization
+ * and termination of modules.
+ *
+ * @example
+ * ```typescript
+ * const iframe = document.getElementById('module-iframe') as HTMLIFrameElement;
+ * const hostBridge = new HostBridge(iframe, 'https://module.example.com');
+ *
+ * // Start a module
+ * hostBridge.sendModuleStart({
+ *   route: '/dashboard',
+ *   context: { userId: 123 },
+ *   timestamp: Date.now()
+ * });
+ *
+ * // Listen for UI updates from the module
+ * hostBridge.on(MessageType.UI_UPDATE, (payload) => {
+ *   console.log('UI Update:', payload);
+ * });
+ * ```
+ */
+export declare class HostBridge extends BridgeBase {
+    /**
+     * Creates a new HostBridge instance.
+     * @param iframe - The iframe element containing the module.
+     * @param targetOrigin - The origin to restrict messages to (default: '*').
+     */
+    constructor(iframe: HTMLIFrameElement, targetOrigin?: string);
+    /**
+     * Sends a module-start message to the embedded module.
+     * This initializes the module with the provided route and context.
+     * @param payload - The module start payload containing route, context, and timestamp.
+     */
+    sendModuleStart(payload: ModuleStartPayload): void;
+    /**
+     * Sends a module-exit message to the embedded module.
+     * This signals the module to clean up and terminate.
+     * @param reason - Optional reason for the module exit.
+     */
+    sendModuleExit(reason?: string): void;
+}
+//# sourceMappingURL=hostBridge.d.ts.map

package/dist/hostBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostBridge.d.ts","sourceRoot":"","sources":["../src/hostBridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,UAAW,SAAQ,UAAU;IACxC;;;;OAIG;gBACS,MAAM,EAAE,iBAAiB,EAAE,YAAY,GAAE,MAAY;IAIjE;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,kBAAkB;IAI3C;;;;OAIG;IACH,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM;CAG/B"}

package/dist/hostBridge.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Host-side bridge for communication with embedded modules.
+ * @module @schoolpalm/message-bridge/hostBridge
+ */
+// src/hostBridge.ts
+import { BridgeBase } from './bridgeBase';
+import { MessageType } from './messageTypes';
+/**
+ * Host-side bridge for communication with embedded modules.
+ *
+ * This class extends BridgeBase to provide host-specific functionality for
+ * communicating with modules embedded in iframes. It handles initialization
+ * and termination of modules.
+ *
+ * @example
+ * ```typescript
+ * const iframe = document.getElementById('module-iframe') as HTMLIFrameElement;
+ * const hostBridge = new HostBridge(iframe, 'https://module.example.com');
+ *
+ * // Start a module
+ * hostBridge.sendModuleStart({
+ *   route: '/dashboard',
+ *   context: { userId: 123 },
+ *   timestamp: Date.now()
+ * });
+ *
+ * // Listen for UI updates from the module
+ * hostBridge.on(MessageType.UI_UPDATE, (payload) => {
+ *   console.log('UI Update:', payload);
+ * });
+ * ```
+ */
+export class HostBridge extends BridgeBase {
+    /**
+     * Creates a new HostBridge instance.
+     * @param iframe - The iframe element containing the module.
+     * @param targetOrigin - The origin to restrict messages to (default: '*').
+     */
+    constructor(iframe, targetOrigin = '*') {
+        super(iframe.contentWindow, targetOrigin);
+    }
+    /**
+     * Sends a module-start message to the embedded module.
+     * This initializes the module with the provided route and context.
+     * @param payload - The module start payload containing route, context, and timestamp.
+     */
+    sendModuleStart(payload) {
+        this.send(MessageType.MODULE_START, payload);
+    }
+    /**
+     * Sends a module-exit message to the embedded module.
+     * This signals the module to clean up and terminate.
+     * @param reason - Optional reason for the module exit.
+     */
+    sendModuleExit(reason) {
+        this.send(MessageType.MODULE_EXIT, { reason });
+    }
+}
+//# sourceMappingURL=hostBridge.js.map

package/dist/hostBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostBridge.js","sourceRoot":"","sources":["../src/hostBridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,oBAAoB;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxC;;;;OAIG;IACH,YAAY,MAAyB,EAAE,eAAuB,GAAG;QAC/D,KAAK,CAAC,MAAM,CAAC,aAAc,EAAE,YAAY,CAAC,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,OAA2B;QACzC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,MAAe;QAC5B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @packageDocumentation
+ * @module @schoolpalm/message-bridge
+ *
+ * TypeScript SDK for message-based communication between SchoolPalm host and vendor modules.
+ *
+ * This module exports the main classes and types for establishing communication
+ * between a host application and embedded modules using the postMessage API.
+ *
+ * @example
+ * ```typescript
+ * import { HostBridge, ModuleBridge, MessageType } from '@schoolpalm/message-bridge';
+ * ```
+ */
+export { BridgeBase } from './bridgeBase';
+export { HostBridge } from './hostBridge';
+export { ModuleBridge } from './moduleBridge';
+export { MessageType } from './messageTypes';
+export * from './payloadSchemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @packageDocumentation
+ * @module @schoolpalm/message-bridge
+ *
+ * TypeScript SDK for message-based communication between SchoolPalm host and vendor modules.
+ *
+ * This module exports the main classes and types for establishing communication
+ * between a host application and embedded modules using the postMessage API.
+ *
+ * @example
+ * ```typescript
+ * import { HostBridge, ModuleBridge, MessageType } from '@schoolpalm/message-bridge';
+ * ```
+ */
+export { BridgeBase } from './bridgeBase';
+export { HostBridge } from './hostBridge';
+export { ModuleBridge } from './moduleBridge';
+export { MessageType } from './messageTypes';
+export * from './payloadSchemas';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,cAAc,kBAAkB,CAAC"}