@appstrata/protocol 0.1.0

package/dist/transport/postMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postMessage.d.ts","sourceRoot":"","sources":["../../src/transport/postMessage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;OAUG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,SAAS,CA4DX"}

package/dist/transport/postMessage.js

@@ -0,0 +1,94 @@
+/**
+ * PostMessage transport implementation.
+ *
+ * Unified transport for both host and app sides.
+ * Works for iframe and same-window scenarios.
+ */
+import { isProtocolMessage } from "../messages.js";
+/**
+ * Create a postMessage transport.
+ *
+ * Sends messages to the target window, receives messages from it.
+ * Automatically determines sensible origin defaults based on whether
+ * the target is the same window or a different window.
+ *
+ * @param options - Transport configuration
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * // Host-side: iframe app
+ * const iframe = document.getElementById("app-frame") as HTMLIFrameElement;
+ * const transport = createPostMessageTransport({
+ *   targetWindow: iframe.contentWindow!,
+ *   targetOrigin: "https://app.example.com"
+ * });
+ *
+ * // Host-side: same-window app
+ * const transport = createPostMessageTransport({
+ *   targetWindow: window,
+ * });
+ *
+ * // App-side: in iframe
+ * const transport = createPostMessageTransport({
+ *   targetWindow: window.parent,
+ *   targetOrigin: "https://player.example.com"
+ * });
+ *
+ * // App-side: same-window
+ * const transport = createPostMessageTransport({
+ *   targetWindow: window,
+ * });
+ * ```
+ */
+export function createPostMessageTransport(options) {
+    const { targetWindow, targetOrigin } = options;
+    const origin = targetOrigin ?? "*";
+    const handlers = new Set();
+    /**
+     * Handle incoming postMessage events.
+     */
+    const handleMessage = (event) => {
+        // Validate source (should be the target window)
+        if (event.source !== targetWindow) {
+            return; // Ignore messages not from target
+        }
+        // Validate origin if specified
+        if (origin !== "*" && event.origin !== origin) {
+            return; // Ignore messages from unexpected origins
+        }
+        // Validate message structure
+        const message = event.data;
+        if (!isProtocolMessage(message)) {
+            return; // Ignore non-protocol messages
+        }
+        // Dispatch to all handlers
+        // Snapshot the handler set to prevent handlers added during iteration from being called.
+        handlers.forEach((handler) => {
+            try {
+                handler(message);
+            }
+            catch (error) {
+                console.error("[AppStrata] Error in message handler:", error);
+            }
+        });
+    };
+    // Install listener
+    window.addEventListener("message", handleMessage);
+    return {
+        send(message) {
+            targetWindow.postMessage(message, origin);
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            // Return unsubscribe function
+            return () => {
+                handlers.delete(handler);
+            };
+        },
+        close() {
+            window.removeEventListener("message", handleMessage);
+            handlers.clear();
+        }
+    };
+}

package/dist/transport/relay.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Relay transport implementation.
+ *
+ * Bridges two transports together, forwarding messages between them.
+ * Commonly used to relay between a postMessage transport (app-side) and an HTTP transport (host-side).
+ *
+ * **Architecture:**
+ * ```
+ * [App] <--postMessage--> [RelayTransport] <--HTTP--> [Remote Host]
+ * ```
+ *
+ * **Use Cases:**
+ * - Relaying app messages to a server-side or native Player (written in any language)
+ * - Service worker proxying messages between local app and cloud host
+ * - Development/debugging proxy for inspecting protocol messages
+ */
+import type { Transport } from "./types.js";
+import type { ProtocolMessage } from "../messages.js";
+/**
+ * Options for creating a relay transport.
+ */
+export interface RelayTransportOptions {
+    /**
+     * Transport for communicating with the app (typically postMessage).
+     * Messages from the app will be forwarded to the host transport.
+     */
+    appTransport: Transport;
+    /**
+     * Transport for communicating with the host (typically HTTP).
+     * Messages from the host will be forwarded to the app transport.
+     */
+    hostTransport: Transport;
+    /**
+     * Optional message interceptor for debugging or transformation.
+     * Called for every message passing through the relay.
+     *
+     * @param message - The protocol message
+     * @param direction - Direction of the message flow
+     * @returns The message to forward (can be modified), or null to drop the message
+     */
+    onMessage?: (message: ProtocolMessage, direction: "app-to-host" | "host-to-app") => ProtocolMessage | null;
+}
+/**
+ * Extended Transport interface for relay transport.
+ *
+ * Provides additional methods for managing the relay lifecycle.
+ */
+export interface RelayTransport extends Transport {
+    /**
+     * Check if the relay is currently active.
+     */
+    isActive(): boolean;
+    /**
+     * Get statistics about messages relayed.
+     */
+    getStats(): {
+        appToHost: number;
+        hostToApp: number;
+        dropped: number;
+    };
+}
+/**
+ * Create a relay transport that bridges two transports together.
+ *
+ * The relay automatically starts forwarding messages between the two transports.
+ * Messages from the app transport are forwarded to the host transport, and vice versa.
+ *
+ * @param options - Relay configuration options
+ * @returns RelayTransport instance
+ *
+ * @example
+ * ```ts
+ * // Relay between iframe app and remote HTTP host
+ * const appTransport = createPostMessageTransport({
+ *   targetWindow: iframe.contentWindow!,
+ *   targetOrigin: "https://app.example.com"
+ * });
+ *
+ * const hostTransport = createHttpSseTransport({
+ *   sendUrl: "https://player.example.com/api/send",
+ *   receiveUrl: "https://player.example.com/api/receive",
+ *   sessionId: "abc-123",
+ *   authToken: "secret-token"
+ * });
+ *
+ * const relay = createRelayTransport({
+ *   appTransport,
+ *   hostTransport,
+ *   debug: true
+ * });
+ *
+ * // Relay automatically forwards messages in both directions
+ * // Close when done
+ * relay.close();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With message interceptor for debugging
+ * const relay = createRelayTransport({
+ *   appTransport,
+ *   hostTransport,
+ *   onMessage: (msg, direction) => {
+ *     console.log(`[Relay ${direction}]`, msg.type, msg);
+ *
+ *     // Transform or filter messages if needed
+ *     if (msg.type === "HELLO") {
+ *       // Augment HELLO message with relay info
+ *       return { ...msg, relayVersion: "1.0" };
+ *     }
+ *
+ *     return msg; // Forward as-is
+ *   }
+ * });
+ * ```
+ */
+export declare function createRelayTransport(options: RelayTransportOptions): RelayTransport;
+//# sourceMappingURL=relay.d.ts.map

package/dist/transport/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../src/transport/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,YAAY,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,aAAa,EAAE,SAAS,CAAC;IAEzB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CACV,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,aAAa,GAAG,aAAa,KACrC,eAAe,GAAG,IAAI,CAAC;CAE7B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC;IAEpB;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAmKnF"}

package/dist/transport/relay.js

@@ -0,0 +1,216 @@
+/**
+ * Relay transport implementation.
+ *
+ * Bridges two transports together, forwarding messages between them.
+ * Commonly used to relay between a postMessage transport (app-side) and an HTTP transport (host-side).
+ *
+ * **Architecture:**
+ * ```
+ * [App] <--postMessage--> [RelayTransport] <--HTTP--> [Remote Host]
+ * ```
+ *
+ * **Use Cases:**
+ * - Relaying app messages to a server-side or native Player (written in any language)
+ * - Service worker proxying messages between local app and cloud host
+ * - Development/debugging proxy for inspecting protocol messages
+ */
+import { createLogger } from "@appstrata/core";
+/**
+ * Create a relay transport that bridges two transports together.
+ *
+ * The relay automatically starts forwarding messages between the two transports.
+ * Messages from the app transport are forwarded to the host transport, and vice versa.
+ *
+ * @param options - Relay configuration options
+ * @returns RelayTransport instance
+ *
+ * @example
+ * ```ts
+ * // Relay between iframe app and remote HTTP host
+ * const appTransport = createPostMessageTransport({
+ *   targetWindow: iframe.contentWindow!,
+ *   targetOrigin: "https://app.example.com"
+ * });
+ *
+ * const hostTransport = createHttpSseTransport({
+ *   sendUrl: "https://player.example.com/api/send",
+ *   receiveUrl: "https://player.example.com/api/receive",
+ *   sessionId: "abc-123",
+ *   authToken: "secret-token"
+ * });
+ *
+ * const relay = createRelayTransport({
+ *   appTransport,
+ *   hostTransport,
+ *   debug: true
+ * });
+ *
+ * // Relay automatically forwards messages in both directions
+ * // Close when done
+ * relay.close();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With message interceptor for debugging
+ * const relay = createRelayTransport({
+ *   appTransport,
+ *   hostTransport,
+ *   onMessage: (msg, direction) => {
+ *     console.log(`[Relay ${direction}]`, msg.type, msg);
+ *
+ *     // Transform or filter messages if needed
+ *     if (msg.type === "HELLO") {
+ *       // Augment HELLO message with relay info
+ *       return { ...msg, relayVersion: "1.0" };
+ *     }
+ *
+ *     return msg; // Forward as-is
+ *   }
+ * });
+ * ```
+ */
+export function createRelayTransport(options) {
+    const { appTransport, hostTransport, onMessage: messageInterceptor, } = options;
+    const logger = createLogger("Relay");
+    let closed = false;
+    const stats = {
+        appToHost: 0,
+        hostToApp: 0,
+        dropped: 0
+    };
+    /**
+     * Handle message from app, forward to host.
+     */
+    function handleAppMessage(message) {
+        if (closed)
+            return;
+        logger.debug(`App → Host: ${message.type}`, message);
+        // Apply interceptor if provided
+        let messageToSend = message;
+        if (messageInterceptor) {
+            try {
+                const result = messageInterceptor(message, "app-to-host");
+                if (result === null) {
+                    logger.debug("Message dropped by interceptor");
+                    stats.dropped++;
+                    return;
+                }
+                messageToSend = result;
+            }
+            catch (error) {
+                logger.error("Error in message interceptor", error);
+                // Forward original message on error
+            }
+        }
+        // Forward to host
+        try {
+            hostTransport.send(messageToSend);
+            stats.appToHost++;
+        }
+        catch (error) {
+            logger.error("Error forwarding to host", error);
+        }
+    }
+    /**
+     * Handle message from host, forward to app.
+     */
+    function handleHostMessage(message) {
+        if (closed)
+            return;
+        logger.debug(`Host → App: ${message.type}`, message);
+        // Apply interceptor if provided
+        let messageToSend = message;
+        if (messageInterceptor) {
+            try {
+                const result = messageInterceptor(message, "host-to-app");
+                if (result === null) {
+                    logger.debug("Message dropped by interceptor");
+                    stats.dropped++;
+                    return;
+                }
+                messageToSend = result;
+            }
+            catch (error) {
+                logger.error("Error in message interceptor", error);
+                // Forward original message on error
+            }
+        }
+        // Forward to app
+        try {
+            appTransport.send(messageToSend);
+            stats.hostToApp++;
+        }
+        catch (error) {
+            logger.error("Error forwarding to app", error);
+        }
+    }
+    // Set up bidirectional forwarding
+    const unsubscribeApp = appTransport.onMessage(handleAppMessage);
+    const unsubscribeHost = hostTransport.onMessage(handleHostMessage);
+    logger.debug("Relay started");
+    return {
+        // Standard Transport interface
+        // Note: The relay itself doesn't have direct handlers, it just forwards
+        // If you need to intercept messages, use the messageInterceptor option
+        send(message) {
+            // When someone calls send() on the relay directly, we need to decide where to send it.
+            // By convention, we send to the host (assuming the caller is the app).
+            if (closed) {
+                logger.warn("Cannot send: relay is closed");
+                return;
+            }
+            logger.debug(`Direct send → Host: ${message.type}`, message);
+            try {
+                hostTransport.send(message);
+                stats.appToHost++;
+            }
+            catch (error) {
+                logger.error("Error sending to host", error);
+            }
+        },
+        onMessage(handler) {
+            // For the relay to act as a transport itself, we need to support onMessage.
+            // We'll register handlers on BOTH transports and call the handler for all messages.
+            if (closed) {
+                return () => { }; // No-op if already closed
+            }
+            const unsubApp = appTransport.onMessage(handler);
+            const unsubHost = hostTransport.onMessage(handler);
+            return () => {
+                unsubApp();
+                unsubHost();
+            };
+        },
+        close() {
+            if (closed)
+                return;
+            logger.debug("Relay closing");
+            closed = true;
+            // Unsubscribe from both transports
+            unsubscribeApp();
+            unsubscribeHost();
+            // Close both underlying transports
+            try {
+                appTransport.close();
+            }
+            catch (error) {
+                logger.error("Error closing app transport", error);
+            }
+            try {
+                hostTransport.close();
+            }
+            catch (error) {
+                logger.error("Error closing host transport", error);
+            }
+            logger.debug("Relay closed", stats);
+        },
+        // Relay-specific extensions
+        isActive() {
+            return !closed;
+        },
+        getStats() {
+            return { ...stats };
+        }
+    };
+}

package/dist/transport/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transport layer types for AppStrata Digital Signage SDK
+ *
+ * The transport layer abstracts the underlying message delivery mechanism.
+ */
+import type { ProtocolMessage } from "../messages.js";
+/**
+ * Transport interface - abstracts message delivery mechanism.
+ *
+ */
+export interface Transport {
+    /**
+     * Send a protocol message to the host.
+     *
+     * @param message - Protocol message to send
+     */
+    send(message: ProtocolMessage): void;
+    /**
+     * Register a message handler.
+     *
+     * @param handler - Function to call when a message is received
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: (message: ProtocolMessage) => void): () => void;
+    /**
+     * Close the transport and clean up resources.
+     */
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transport/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEnE;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/transport/types.js

@@ -0,0 +1,6 @@
+/**
+ * Transport layer types for AppStrata Digital Signage SDK
+ *
+ * The transport layer abstracts the underlying message delivery mechanism.
+ */
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@appstrata/protocol",
+  "version": "0.1.0",
+  "description": "AppStrata protocol implementation - messages, transport, client and host",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./messages": {
+      "types": "./dist/messages.d.ts",
+      "import": "./dist/messages.js"
+    },
+    "./transport": {
+      "types": "./dist/transport/index.d.ts",
+      "import": "./dist/transport/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "import": "./dist/host/index.js"
+    }
+  },
+  "keywords": [
+    "digital-signage",
+    "appstrata",
+    "protocol"
+  ],
+  "author": "AppStrata",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@appstrata/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "dev": "tsc --build --watch",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
+  }
+}