@schoolpalm/message-bridge 0.1.0

package/src/messageTypes.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Message type definitions for bridge communication.
+ * @module @schoolpalm/message-bridge/messageTypes
+ */
+
+// src/messageTypes.ts
+
+/**
+ * Enumeration of all allowed message types for Host ↔ Module communication.
+ *
+ * These message types define the protocol for communication between the host
+ * application and embedded modules. Each type indicates the direction and
+ * purpose of the message.
+ *
+ * @example
+ * ```typescript
+ * import { MessageType } from '@schoolpalm/message-bridge';
+ *
+ * // Listen for UI updates from modules
+ * bridge.on(MessageType.UI_UPDATE, (payload) => {
+ *   console.log('UI updated:', payload);
+ * });
+ * ```
+ */
+export enum MessageType {
+  /** Module → Host: Indicates the module is ready for communication. */
+  HANDSHAKE_READY = 'handshake:ready',
+  /** Host → Module: Signals the module to start with provided context. */
+  MODULE_START = 'module:start',
+  /** Module → Host: Updates the host UI (title, breadcrumb, theme). */
+  UI_UPDATE = 'ui:update',
+  /** Module → Host: Requests data from the host. */
+  DATA_REQUEST = 'data:request',
+  /** Host → Module: Responds to a data request. */
+  DATA_RESPONSE = 'data:response',
+  /** Module → Host: Reports an error to the host. */
+  ERROR = 'error',
+  /** Host → Module: Signals the module to exit and clean up. */
+  MODULE_EXIT = 'module:exit'
+}

package/src/moduleBridge.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Module-side bridge for communication with the host application.
+ * @module @schoolpalm/message-bridge/moduleBridge
+ */
+
+// src/moduleBridge.ts
+import { BridgeBase } from './bridgeBase';
+import { MessageType } from './messageTypes';
+import {
+  HandshakeReadyPayload,
+  UIUpdatePayload,
+  ErrorPayload
+} from './payloadSchemas';
+
+/**
+ * Module-side bridge for communication with the host application.
+ *
+ * This class extends BridgeBase to provide module-specific functionality for
+ * communicating with the parent host application. It handles handshake,
+ * UI updates, and error reporting from the embedded module.
+ *
+ * @example
+ * ```typescript
+ * const moduleBridge = new ModuleBridge('https://host.example.com');
+ *
+ * // Send handshake when module is ready
+ * moduleBridge.sendHandshake({
+ *   version: '1.0.0',
+ *   timestamp: Date.now()
+ * });
+ *
+ * // Update UI in the host
+ * moduleBridge.sendUIUpdate({
+ *   title: 'Dashboard',
+ *   breadcrumb: ['Home', 'Dashboard'],
+ *   theme: 'dark'
+ * });
+ *
+ * // Listen for module start from host
+ * moduleBridge.on(MessageType.MODULE_START, (payload) => {
+ *   console.log('Module started:', payload.route);
+ * });
+ * ```
+ */
+export class ModuleBridge extends BridgeBase {
+  /**
+   * Creates a new ModuleBridge instance.
+   * @param targetOrigin - The origin to restrict messages to (default: '*').
+   */
+  constructor(targetOrigin: string = '*') {
+    super(window.parent, targetOrigin);
+  }
+
+  /**
+   * Notifies the host application that the module is ready.
+   * This should be called after the module has initialized.
+   * @param payload - The handshake payload containing version and timestamp.
+   */
+  sendHandshake(payload: HandshakeReadyPayload) {
+    this.send(MessageType.HANDSHAKE_READY, payload);
+  }
+
+  /**
+   * Notifies the host application of UI updates.
+   * This includes changes to title, breadcrumb, and theme.
+   * @param payload - The UI update payload.
+   */
+  sendUIUpdate(payload: UIUpdatePayload) {
+    this.send(MessageType.UI_UPDATE, payload);
+  }
+
+  /**
+   * Notifies the host application of an error.
+   * @param payload - The error payload containing error details.
+   */
+  sendError(payload: ErrorPayload) {
+    this.send(MessageType.ERROR, payload);
+  }
+}

package/src/payloadSchemas.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Payload schema definitions for message-based communication.
+ * @module @schoolpalm/message-bridge/payloadSchemas
+ */
+
+// src/payloadSchemas.ts
+import { MessageType } from './messageTypes';
+
+/**
+ * Payload interfaces for each message type in the bridge communication protocol.
+ *
+ * These interfaces define the structure of data exchanged between host applications
+ * and embedded modules. Each payload corresponds to a specific message type and
+ * contains the necessary information for that communication scenario.
+ */
+
+/**
+ * Payload for handshake ready message.
+ * Sent by modules to indicate they are ready for communication.
+ */
+export interface HandshakeReadyPayload {
+  /** Version of the module or SDK */
+  version: string;
+  /** Timestamp when the handshake was initiated */
+  timestamp: number;
+}
+
+/**
+ * Payload for module start message.
+ * Sent by host to initialize a module with context.
+ */
+export interface ModuleStartPayload {
+  /** Route or path to navigate to in the module */
+  route: string;
+  /** Context data passed to the module (user info, permissions, etc.) */
+  context: Record<string, any>;
+  /** Timestamp when the module start was requested */
+  timestamp: number;
+}
+
+/**
+ * Payload for UI update message.
+ * Sent by modules to update the host application's UI.
+ */
+export interface UIUpdatePayload {
+  /** Title to display in the host UI */
+  title: string;
+  /** Breadcrumb navigation path */
+  breadcrumb: string[];
+  /** Optional theme to apply to the host UI */
+  theme?: string;
+}
+
+/**
+ * Payload for data request message.
+ * Sent by modules to request data from the host.
+ */
+export interface DataRequestPayload {
+  /** Unique identifier for tracking the request */
+  requestId: string;
+  /** Action or endpoint to request data from */
+  action: string;
+  /** Optional payload data for the request */
+  payload?: Record<string, any>;
+}
+
+/**
+ * Payload for data response message.
+ * Sent by host in response to data requests.
+ */
+export interface DataResponsePayload {
+  /** Unique identifier matching the original request */
+  requestId: string;
+  /** Status of the response */
+  status: 'success' | 'error';
+  /** Response data (present on success) */
+  payload?: any;
+}
+
+/**
+ * Payload for error message.
+ * Sent by modules to report errors to the host.
+ */
+export interface ErrorPayload {
+  /** Error code for categorization */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Optional additional error details */
+  details?: any;
+}
+
+/**
+ * Payload for module exit message.
+ * Sent by host to signal module termination.
+ */
+export interface ModuleExitPayload {
+  /** Optional reason for the module exit */
+  reason?: string;
+}
+
+/**
+ * Union type representing all possible message payloads.
+ *
+ * This type is used internally for type safety when handling messages
+ * of any type in the bridge classes.
+ */
+export type MessagePayload =
+  | HandshakeReadyPayload
+  | ModuleStartPayload
+  | UIUpdatePayload
+  | DataRequestPayload
+  | DataResponsePayload
+  | ErrorPayload
+  | ModuleExitPayload;

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom', 
+    globals: true,   
+  },
+});