@appstrata/protocol 0.1.0

package/dist/client/rpc.d.ts

@@ -0,0 +1,62 @@
+/**
+ * RPC (Request/Response) layer for capability operations.
+ *
+ * Handles sending requests and matching responses.
+ */
+import type { Transport } from "../transport/index.js";
+/**
+ * RPC client for sending requests to the host.
+ *
+ * Manages request/response correlation and timeouts.
+ */
+export declare class RpcClient {
+    private transport;
+    private pending;
+    private defaultTimeout;
+    private readyPromise;
+    private unsubscribe?;
+    /**
+     * Create an RPC client.
+     *
+     * @param transport - Transport for sending/receiving messages
+     * @param readyPromise - Promise that resolves when the handshake is complete.
+     *   Per spec §2.2, REQUESTs must not be sent before READY/READY_ACK.
+     * @param options - RPC options
+     */
+    constructor(transport: Transport, readyPromise: Promise<void>, options?: {
+        defaultTimeout?: number;
+    });
+    /**
+     * Send a notification (fire-and-forget request, no response expected).
+     *
+     * The REQUEST is sent without a `requestId`, signalling to the Host
+     * that no RESPONSE should be sent (spec §4.4).
+     *
+     * @param op - Operation name
+     * @param payload - Operation payload
+     */
+    notify(op: string, payload?: unknown): Promise<void>;
+    /**
+     * Send a request and wait for response.
+     *
+     * @param op - Operation name
+     * @param payload - Operation payload
+     * @param timeout - Request timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves with the result
+     *
+     * @example
+     * ```ts
+     * const result = await rpc.call("storage.get", { key: "myKey" });
+     * ```
+     */
+    call(op: string, payload?: unknown, timeout?: number): Promise<unknown>;
+    /**
+     * Handle response message.
+     */
+    private handleResponse;
+    /**
+     * Close the RPC client and cancel all pending requests.
+     */
+    close(): void;
+}
+//# sourceMappingURL=rpc.d.ts.map

package/dist/client/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../src/client/rpc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAavD;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,WAAW,CAAC,CAAa;IAEjC;;;;;;;OAOG;gBAED,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,EAC3B,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAO;IAc3C;;;;;;;;OAQG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1D;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgC7E;;OAEG;IACH,OAAO,CAAC,cAAc;IA2BtB;;OAEG;IACH,KAAK,IAAI,IAAI;CAiBd"}

package/dist/client/rpc.js

@@ -0,0 +1,138 @@
+/**
+ * RPC (Request/Response) layer for capability operations.
+ *
+ * Handles sending requests and matching responses.
+ */
+import { generateRequestId, isResponseMessage } from "../messages.js";
+/**
+ * RPC client for sending requests to the host.
+ *
+ * Manages request/response correlation and timeouts.
+ */
+export class RpcClient {
+    /**
+     * Create an RPC client.
+     *
+     * @param transport - Transport for sending/receiving messages
+     * @param readyPromise - Promise that resolves when the handshake is complete.
+     *   Per spec §2.2, REQUESTs must not be sent before READY/READY_ACK.
+     * @param options - RPC options
+     */
+    constructor(transport, readyPromise, options = {}) {
+        this.pending = new Map();
+        this.transport = transport;
+        this.readyPromise = readyPromise;
+        this.defaultTimeout = options.defaultTimeout ?? 30000; // 30 seconds default
+        // Listen for responses
+        this.unsubscribe = transport.onMessage((msg) => {
+            if (isResponseMessage(msg)) {
+                this.handleResponse(msg);
+            }
+        });
+    }
+    /**
+     * Send a notification (fire-and-forget request, no response expected).
+     *
+     * The REQUEST is sent without a `requestId`, signalling to the Host
+     * that no RESPONSE should be sent (spec §4.4).
+     *
+     * @param op - Operation name
+     * @param payload - Operation payload
+     */
+    async notify(op, payload) {
+        await this.readyPromise;
+        const request = {
+            protocol: "appstrata-protocol",
+            version: "1.0",
+            type: "REQUEST",
+            timestamp: Date.now(),
+            op,
+            payload
+        };
+        this.transport.send(request);
+    }
+    /**
+     * Send a request and wait for response.
+     *
+     * @param op - Operation name
+     * @param payload - Operation payload
+     * @param timeout - Request timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves with the result
+     *
+     * @example
+     * ```ts
+     * const result = await rpc.call("storage.get", { key: "myKey" });
+     * ```
+     */
+    async call(op, payload, timeout) {
+        // Spec §2.2: Apps MUST NOT send REQUEST messages until handshake is complete
+        await this.readyPromise;
+        const requestId = generateRequestId();
+        const timeoutMs = timeout ?? this.defaultTimeout;
+        return new Promise((resolve, reject) => {
+            // Set up timeout
+            const timeoutId = setTimeout(() => {
+                this.pending.delete(requestId);
+                reject(new Error(`RPC timeout after ${timeoutMs}ms for operation: ${op}`));
+            }, timeoutMs);
+            // Store pending request
+            this.pending.set(requestId, { resolve, reject, timeoutId });
+            // Send request
+            const request = {
+                protocol: "appstrata-protocol",
+                version: "1.0",
+                type: "REQUEST",
+                timestamp: Date.now(),
+                requestId,
+                op,
+                payload
+            };
+            this.transport.send(request);
+        });
+    }
+    /**
+     * Handle response message.
+     */
+    handleResponse(msg) {
+        const pending = this.pending.get(msg.requestId);
+        if (!pending) {
+            // No pending request for this response (maybe already timed out)
+            console.warn("[AppStrata] Received response for unknown request:", msg.requestId);
+            return;
+        }
+        // Clear timeout
+        if (pending.timeoutId) {
+            clearTimeout(pending.timeoutId);
+        }
+        // Remove from pending
+        this.pending.delete(msg.requestId);
+        // Resolve or reject
+        if (msg.ok) {
+            pending.resolve(msg.result);
+        }
+        else {
+            const error = new Error(msg.error?.message || "RPC call failed");
+            error.code = msg.error?.code;
+            error.details = msg.error?.details;
+            pending.reject(error);
+        }
+    }
+    /**
+     * Close the RPC client and cancel all pending requests.
+     */
+    close() {
+        // Unsubscribe from transport
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = undefined;
+        }
+        // Cancel all pending requests
+        for (const [, pending] of this.pending) {
+            if (pending.timeoutId) {
+                clearTimeout(pending.timeoutId);
+            }
+            pending.reject(new Error("RPC client closed"));
+        }
+        this.pending.clear();
+    }
+}

package/dist/host/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Host-side protocol implementation.
+ */
+export * from "./message-bridge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,qBAAqB,CAAC"}

package/dist/host/index.js

@@ -0,0 +1,4 @@
+/**
+ * Host-side protocol implementation.
+ */
+export * from "./message-bridge.js";

package/dist/host/message-bridge.d.ts

@@ -0,0 +1,146 @@
+/**
+ * MessageBridge - Host-side message protocol bridge.
+ *
+ * Bridges communication between the player and app via the message protocol.
+ * Handles the HELLO/READY/READY_ACK handshake and subsequent RPC/event communication.
+ *
+ * Key responsibilities:
+ * - Listen for HELLO messages from apps
+ * - Send READY messages with AppContext
+ * - Retry READY until READY_ACK received (if HELLO not received)
+ * - Handle REQUEST messages and send RESPONSE
+ * - Fire lifecycle EVENT messages
+ */
+import { type AppContext, type SignagePlayer } from "@appstrata/core";
+import type { Transport } from "../transport/index.js";
+export interface MessageBridgeConfig {
+    /**
+     * Transport for sending/receiving messages.
+     */
+    transport: Transport;
+    /**
+     * SignagePlayer instance to delegate RPC calls to.
+     * RPC requests will be routed to the player's API methods.
+     */
+    player: SignagePlayer;
+    /**
+     * Must return the current AppContext.
+     * Called when READY needs to be sent.
+     */
+    getContext: () => Promise<AppContext>;
+    /**
+     * READY retry interval in milliseconds.
+     * @default 1000 (1 second)
+     */
+    retryInterval?: number;
+    /**
+     * Maximum number of READY retries.
+     * @default 10
+     */
+    maxRetries?: number;
+}
+/**
+ * MessageBridge - Host-side protocol bridge.
+ *
+ * **Single-session:** one `MessageBridge` instance covers one App page load.
+ * Once the handshake completes (`receivedReadyAck = true`), the bridge enters
+ * the ACTIVE state and does not reset. When the App reloads, the old bridge
+ * must be destroyed and a new one created.
+ *
+ * Bridges the player to apps via the message protocol.
+ *
+ * Usage:
+ * ```typescript
+ * const bridge = new MessageBridge({
+ *   transport: createPostMessageTransport({ targetWindow: iframe.contentWindow!, targetOrigin: "*" }),
+ *   player: myPlayer,
+ *   getContext: async () => buildAppContext(),
+ * });
+ *
+ * // Start the handshake (sends READY)
+ * bridge.start();
+ *
+ * // Send lifecycle events
+ * bridge.fireShow();
+ * bridge.fireStart();
+ * ```
+ */
+export declare class MessageBridge {
+    private config;
+    private transport;
+    private receivedHello;
+    private receivedReadyAck;
+    private helloRequestId?;
+    private retryTimer?;
+    private retryCount;
+    private started;
+    private unsubscribeFromTransport?;
+    private pendingEvents;
+    constructor(config: MessageBridgeConfig);
+    /**
+     * Start the bridge (send initial READY message).
+     */
+    start(): void;
+    /**
+     * Handle HELLO message from app.
+     */
+    private handleHello;
+    /**
+     * Handle READY_ACK message from app.
+     */
+    private handleReadyAck;
+    /**
+     * Flush pending events that were queued before READY_ACK.
+     */
+    private flushPendingEvents;
+    /**
+     * Handle REQUEST message from app.
+     */
+    private handleRequest;
+    /**
+     * Handle request by routing to player API.
+     */
+    private handlePlayerRequest;
+    /**
+     * Helper to check capability availability.
+     */
+    private requireCapability;
+    /**
+     * Send latest AppContext as READY message to app.
+     *
+     * Awaits the AppContext to be available.
+     * If proactive is true, and HELLO arrives by the time the context is available,
+     * no READY is sent.
+     *
+     * @param reason - The phase at which the READY message is being sent. Only used for logging.
+     */
+    private sendReady;
+    /**
+     * Schedule next retry for READY messages.
+     */
+    private scheduleNextRetry;
+    /**
+     * Cancel the next retry for READY messages.
+     */
+    private cancelNextRetry;
+    /**
+     * Send an EVENT message through the transport.
+     * If the handshake is not yet complete (READY_ACK not received), the event
+     * is queued and will be flushed when READY_ACK arrives.
+     */
+    private sendEventMessage;
+    fireShow(): void;
+    fireStart(): void;
+    fireHide(): void;
+    fireStop(): void;
+    fireContextChange(context: AppContext): void;
+    /**
+     * Cleanup.
+     *
+     * Unsubscribes from the transport but does NOT close it.
+     * The transport lifecycle is owned by whoever created it
+     * (e.g., the session manager), not by the bridge.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=message-bridge.d.ts.map

package/dist/host/message-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-bridge.d.ts","sourceRoot":"","sources":["../../src/host/message-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAmC,KAAK,UAAU,EAAE,KAAK,aAAa,EAA0B,MAAM,iBAAiB,CAAC;AAG/H,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAkBvD,MAAM,WAAW,mBAAmB;IAElC;;OAEG;IACH,SAAS,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,MAAM,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAEtC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA4E;IAC1F,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,cAAc,CAAC,CAAS;IAChC,OAAO,CAAC,UAAU,CAAC,CAAgC;IACnD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,wBAAwB,CAAC,CAAa;IAC9C,OAAO,CAAC,aAAa,CAAsB;gBAE/B,MAAM,EAAE,mBAAmB;IAqBvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACH,OAAO,CAAC,WAAW;IAoBnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;YACW,aAAa;IAsD3B;;OAEG;YACW,mBAAmB;IAoEjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;;;;;OAQG;YACW,SAAS;IAyBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAoBxB,QAAQ,IAAI,IAAI;IAIhB,SAAS,IAAI,IAAI;IAIjB,QAAQ,IAAI,IAAI;IAIhB,QAAQ,IAAI,IAAI;IAIhB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAK5C;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAUhB"}