@appstrata/protocol 0.1.0

package/dist/transport/http/host-polling.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Long-polling host-side HTTP transport.
+ *
+ * Bridges the AppStrata Transport interface to an HTTP server using
+ * long polling for the server→client channel.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const transport = createHttpPollingHostTransport({ sessionId: "abc" });
+ *
+ * // When a POST arrives with a message from the client:
+ * transport.handleIncomingMessage(req.body);
+ *
+ * // When a poll request arrives (GET /poll):
+ * const messages = await transport.handlePollRequest(30_000);
+ * if (messages === null) {
+ *   res.status(409).json({ error: "Poll already active" });
+ * } else {
+ *   res.json({ messages });
+ * }
+ *
+ * // Pass the transport to an AppHost or MessageBridge — done.
+ * ```
+ *
+ * ## Lifecycles
+ *
+ * - **Transport**: one per session, long-lived.
+ * - **Poll requests**: each one blocks until messages are available or
+ *   the timeout elapses, then returns all pending messages.
+ * - **POST requests**: stateless. Each one delivers a single inbound message.
+ */
+import type { ProtocolMessage } from "../../messages.js";
+import type { HttpHostTransport, HttpHostTransportOptions } from "./types.js";
+/**
+ * Long-polling-specific host transport interface.
+ *
+ * Extends the base `HttpHostTransport` with `handlePollRequest`, which
+ * the HTTP server calls when a client polls for new messages.
+ */
+export interface HttpPollingHostTransport extends HttpHostTransport {
+    /**
+     * Handle a poll request from the client.
+     *
+     * Returns all pending messages immediately if any are queued.
+     * Otherwise blocks until at least one message arrives or `timeoutMs`
+     * elapses, whichever comes first.
+     *
+     * Returns `null` if a poll is already in progress for this transport.
+     * The HTTP layer should map this to a 409 Conflict response — two
+     * concurrent polls for the same session is a client bug.
+     *
+     * @param timeoutMs - Maximum time to wait for messages (default 30 000 ms)
+     * @returns Array of pending protocol messages (may be empty on timeout),
+     *          or `null` if another poll is already active
+     */
+    handlePollRequest(timeoutMs?: number): Promise<ProtocolMessage[] | null>;
+}
+/**
+ * Create a long-polling-based host-side HTTP transport for a single session.
+ *
+ * See module-level doc for lifecycle and wiring instructions.
+ */
+export declare function createHttpPollingHostTransport(options: HttpHostTransportOptions): HttpPollingHostTransport;
+//# sourceMappingURL=host-polling.d.ts.map

package/dist/transport/http/host-polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-polling.d.ts","sourceRoot":"","sources":["../../../src/transport/http/host-polling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;CAC1E;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,wBAAwB,GAChC,wBAAwB,CA+H1B"}

package/dist/transport/http/host-polling.js

@@ -0,0 +1,143 @@
+/**
+ * Long-polling host-side HTTP transport.
+ *
+ * Bridges the AppStrata Transport interface to an HTTP server using
+ * long polling for the server→client channel.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const transport = createHttpPollingHostTransport({ sessionId: "abc" });
+ *
+ * // When a POST arrives with a message from the client:
+ * transport.handleIncomingMessage(req.body);
+ *
+ * // When a poll request arrives (GET /poll):
+ * const messages = await transport.handlePollRequest(30_000);
+ * if (messages === null) {
+ *   res.status(409).json({ error: "Poll already active" });
+ * } else {
+ *   res.json({ messages });
+ * }
+ *
+ * // Pass the transport to an AppHost or MessageBridge — done.
+ * ```
+ *
+ * ## Lifecycles
+ *
+ * - **Transport**: one per session, long-lived.
+ * - **Poll requests**: each one blocks until messages are available or
+ *   the timeout elapses, then returns all pending messages.
+ * - **POST requests**: stateless. Each one delivers a single inbound message.
+ */
+import { isProtocolMessage } from "../../messages.js";
+/**
+ * Create a long-polling-based host-side HTTP transport for a single session.
+ *
+ * See module-level doc for lifecycle and wiring instructions.
+ */
+export function createHttpPollingHostTransport(options) {
+    const { sessionId } = options;
+    const handlers = new Set();
+    let closed = false;
+    // Queue outbound messages for the next poll request
+    const pendingMessages = [];
+    const MAX_PENDING = 100;
+    // Resolver for the single currently-waiting poll request (if any).
+    // Only one poll should be active per transport at a time — the client
+    // sends a poll, waits for the response, then immediately re-polls.
+    let activePollResolver = null;
+    /**
+     * Dispatch message to all handlers.
+     */
+    function dispatchMessage(message) {
+        for (const handler of [...handlers]) {
+            try {
+                handler(message);
+            }
+            catch (error) {
+                console.error(`[AppStrata Host] Error in message handler (session ${sessionId}):`, error);
+            }
+        }
+    }
+    /**
+     * Queue a message and wake the waiting poll request if one exists.
+     */
+    function queueMessage(message) {
+        pendingMessages.push(message);
+        if (pendingMessages.length > MAX_PENDING) {
+            pendingMessages.shift(); // Remove oldest
+        }
+        // If a poll request is waiting, resolve it immediately
+        if (activePollResolver) {
+            const messages = pendingMessages.splice(0);
+            const resolve = activePollResolver;
+            activePollResolver = null;
+            resolve(messages);
+        }
+    }
+    return {
+        // Standard Transport interface
+        send(message) {
+            if (closed) {
+                console.warn(`[AppStrata Host] Cannot send: transport closed (session ${sessionId})`);
+                return;
+            }
+            queueMessage(message);
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close() {
+            closed = true;
+            handlers.clear();
+            pendingMessages.length = 0;
+            // Resolve the waiting poll request (if any) with an empty array
+            if (activePollResolver) {
+                const resolve = activePollResolver;
+                activePollResolver = null;
+                resolve([]);
+            }
+        },
+        // HTTP-specific extensions
+        handleIncomingMessage(message) {
+            if (closed)
+                return;
+            if (!isProtocolMessage(message)) {
+                console.warn(`[AppStrata Host] Invalid message received (session ${sessionId})`);
+                return;
+            }
+            dispatchMessage(message);
+        },
+        handlePollRequest(timeoutMs = 30000) {
+            if (closed) {
+                return Promise.resolve([]);
+            }
+            // Reject concurrent polls — only one should be active at a time.
+            // Two concurrent polls means either a client bug or a session
+            // collision; the HTTP layer should return 409 Conflict.
+            if (activePollResolver) {
+                return Promise.resolve(null);
+            }
+            // If there are already pending messages, return them immediately
+            if (pendingMessages.length > 0) {
+                const messages = pendingMessages.splice(0);
+                return Promise.resolve(messages);
+            }
+            // Wait for messages or timeout
+            return new Promise((resolve) => {
+                activePollResolver = (messages) => {
+                    clearTimeout(timer);
+                    resolve(messages);
+                };
+                const timer = setTimeout(() => {
+                    activePollResolver = null;
+                    // Drain whatever has accumulated (likely empty)
+                    const messages = pendingMessages.splice(0);
+                    resolve(messages);
+                }, timeoutMs);
+            });
+        },
+    };
+}

package/dist/transport/http/host-sse.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SSE host-side HTTP transport.
+ *
+ * Bridges the AppStrata Transport interface to an HTTP server using
+ * Server-Sent Events for the server→client channel.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const transport = createHttpSseHostTransport({ sessionId: "abc" });
+ *
+ * // When a POST arrives with a message from the client:
+ * transport.handleIncomingMessage(req.body);
+ *
+ * // When an SSE connection opens:
+ * const cleanup = transport.setSseWriter((data) => res.write(data));
+ * req.on("close", cleanup);
+ *
+ * // Pass the transport to an AppHost or MessageBridge — done.
+ * ```
+ *
+ * ## Lifecycles
+ *
+ * - **Transport**: one per session, long-lived. Survives SSE disconnects.
+ * - **SSE connection**: comes and goes. Messages queue while disconnected,
+ *   flush automatically when `setSseWriter()` is called again.
+ * - **POST requests**: stateless. Each one delivers a single inbound message.
+ */
+import type { HttpHostTransport, HttpHostTransportOptions } from "./types.js";
+/**
+ * SSE-specific host transport interface.
+ *
+ * Extends the base `HttpHostTransport` with methods to wire up an SSE
+ * response stream for pushing messages to the client.
+ */
+export interface HttpSseHostTransport extends HttpHostTransport {
+    /**
+     * Set the SSE writer function for sending messages to the client.
+     * Call this when an SSE connection is established.
+     *
+     * @param writer - Function that writes data to the SSE response stream
+     * @returns Cleanup function to call when SSE connection closes
+     */
+    setSseWriter(writer: (data: string) => void): () => void;
+    /**
+     * Check if an SSE connection is active.
+     */
+    hasSseConnection(): boolean;
+}
+/**
+ * Create an SSE-based host-side HTTP transport for a single session.
+ *
+ * See module-level doc for lifecycle and wiring instructions.
+ */
+export declare function createHttpSseHostTransport(options: HttpHostTransportOptions): HttpSseHostTransport;
+//# sourceMappingURL=host-sse.d.ts.map

package/dist/transport/http/host-sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-sse.d.ts","sourceRoot":"","sources":["../../../src/transport/http/host-sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEzD;;OAEG;IACH,gBAAgB,IAAI,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,wBAAwB,GAAG,oBAAoB,CA8HlG"}

package/dist/transport/http/host-sse.js

@@ -0,0 +1,149 @@
+/**
+ * SSE host-side HTTP transport.
+ *
+ * Bridges the AppStrata Transport interface to an HTTP server using
+ * Server-Sent Events for the server→client channel.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const transport = createHttpSseHostTransport({ sessionId: "abc" });
+ *
+ * // When a POST arrives with a message from the client:
+ * transport.handleIncomingMessage(req.body);
+ *
+ * // When an SSE connection opens:
+ * const cleanup = transport.setSseWriter((data) => res.write(data));
+ * req.on("close", cleanup);
+ *
+ * // Pass the transport to an AppHost or MessageBridge — done.
+ * ```
+ *
+ * ## Lifecycles
+ *
+ * - **Transport**: one per session, long-lived. Survives SSE disconnects.
+ * - **SSE connection**: comes and goes. Messages queue while disconnected,
+ *   flush automatically when `setSseWriter()` is called again.
+ * - **POST requests**: stateless. Each one delivers a single inbound message.
+ */
+import { isProtocolMessage } from "../../messages.js";
+/**
+ * Create an SSE-based host-side HTTP transport for a single session.
+ *
+ * See module-level doc for lifecycle and wiring instructions.
+ */
+export function createHttpSseHostTransport(options) {
+    const { sessionId } = options;
+    const handlers = new Set();
+    let sseWriter = null;
+    let closed = false;
+    // Queue messages when no SSE connection is available
+    const pendingMessages = [];
+    const MAX_PENDING = 100;
+    /**
+     * Dispatch message to all handlers.
+     */
+    function dispatchMessage(message) {
+        for (const handler of [...handlers]) {
+            try {
+                handler(message);
+            }
+            catch (error) {
+                console.error(`[AppStrata Host] Error in message handler (session ${sessionId}):`, error);
+            }
+        }
+    }
+    /**
+     * Send message via SSE or queue it.
+     */
+    function sendToClient(message) {
+        if (sseWriter) {
+            const data = `data: ${JSON.stringify(message)}\n\n`;
+            try {
+                sseWriter(data);
+            }
+            catch (error) {
+                console.error(`[AppStrata Host] Error writing to SSE (session ${sessionId}):`, error);
+                queueMessage(message);
+            }
+        }
+        else {
+            queueMessage(message);
+        }
+    }
+    /**
+     * Queue a message for later delivery.
+     */
+    function queueMessage(message) {
+        pendingMessages.push(message);
+        if (pendingMessages.length > MAX_PENDING) {
+            pendingMessages.shift(); // Remove oldest
+        }
+    }
+    /**
+     * Flush pending messages to SSE.
+     */
+    function flushPending() {
+        if (!sseWriter)
+            return;
+        while (pendingMessages.length > 0) {
+            const message = pendingMessages.shift();
+            const data = `data: ${JSON.stringify(message)}\n\n`;
+            try {
+                sseWriter(data);
+            }
+            catch (error) {
+                // Put it back and stop flushing
+                pendingMessages.unshift(message);
+                break;
+            }
+        }
+    }
+    return {
+        // Standard Transport interface
+        send(message) {
+            if (closed) {
+                console.warn(`[AppStrata Host] Cannot send: transport closed (session ${sessionId})`);
+                return;
+            }
+            sendToClient(message);
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close() {
+            closed = true;
+            sseWriter = null;
+            handlers.clear();
+            pendingMessages.length = 0;
+        },
+        // HTTP-specific extensions
+        handleIncomingMessage(message) {
+            if (closed)
+                return;
+            if (!isProtocolMessage(message)) {
+                console.warn(`[AppStrata Host] Invalid message received (session ${sessionId})`);
+                return;
+            }
+            dispatchMessage(message);
+        },
+        setSseWriter(writer) {
+            if (closed) {
+                return () => { }; // No-op cleanup
+            }
+            sseWriter = writer;
+            // Flush any pending messages
+            flushPending();
+            // Return cleanup function
+            return () => {
+                if (sseWriter === writer) {
+                    sseWriter = null;
+                }
+            };
+        },
+        hasSseConnection() {
+            return sseWriter !== null;
+        },
+    };
+}

package/dist/transport/http/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * HTTP transport implementations for AppStrata.
+ *
+ * Provides both SSE and long-polling variants for client and host sides,
+ * plus a generic session manager.
+ */
+export * from "./types.js";
+export * from "./host-sse.js";
+export * from "./host-polling.js";
+export * from "./host-manager.js";
+export * from "./client-sse.js";
+export * from "./client-polling.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/transport/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transport/http/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/transport/http/index.js

@@ -0,0 +1,12 @@
+/**
+ * HTTP transport implementations for AppStrata.
+ *
+ * Provides both SSE and long-polling variants for client and host sides,
+ * plus a generic session manager.
+ */
+export * from "./types.js";
+export * from "./host-sse.js";
+export * from "./host-polling.js";
+export * from "./host-manager.js";
+export * from "./client-sse.js";
+export * from "./client-polling.js";

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

@@ -0,0 +1,73 @@
+/**
+ * Shared types for HTTP transport implementations.
+ *
+ * Defines the base `HttpHostTransport` interface that both SSE and
+ * long-polling host transports extend, plus common option types used
+ * by client transports.
+ */
+import type { Transport } from "../types.js";
+import type { ProtocolMessage } from "../../messages.js";
+/**
+ * Base interface for HTTP host transports.
+ *
+ * Extends the generic `Transport` with `handleIncomingMessage`, which the
+ * HTTP server's POST handler calls to feed client messages into the
+ * transport layer.  Concrete variants (SSE, long-polling) extend this
+ * with their own server→client delivery mechanism.
+ */
+export interface HttpHostTransport extends Transport {
+    /**
+     * Handle an incoming message from the client (called by HTTP POST handler).
+     * This triggers the `onMessage` handlers.
+     *
+     * @param message - The protocol message received via HTTP POST
+     */
+    handleIncomingMessage(message: ProtocolMessage): void;
+}
+/**
+ * Options shared by all host transport factories.
+ */
+export interface HttpHostTransportOptions {
+    /**
+     * Session ID for this transport instance.
+     */
+    sessionId: string;
+}
+/**
+ * Common options shared by all HTTP client transports.
+ */
+export interface HttpClientTransportOptions {
+    /**
+     * URL for sending messages (HTTP POST).
+     * The session ID will be sent as `X-Session-Id` header.
+     */
+    sendUrl: string;
+    /**
+     * URL for receiving messages from the server.
+     * - SSE transport: EventSource endpoint
+     * - Polling transport: long-poll endpoint
+     *
+     * The session ID will be appended as `?sessionId=...` query parameter.
+     */
+    receiveUrl: string;
+    /**
+     * Session ID to include in requests.
+     * Used by the host to correlate messages with the correct app instance.
+     */
+    sessionId: string;
+    /**
+     * Optional authentication token.
+     * If provided, will be sent as `Authorization: Bearer ${token}`.
+     */
+    authToken?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom headers to include in all requests.
+     */
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/transport/http/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;;;;OAKG;IACH,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAElC"}

package/dist/transport/http/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for HTTP transport implementations.
+ *
+ * Defines the base `HttpHostTransport` interface that both SSE and
+ * long-polling host transports extend, plus common option types used
+ * by client transports.
+ */
+export {};

package/dist/transport/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Transport layer for AppStrata Digital Signage SDK.
+ *
+ * Provides transport implementations for both App and Host sides.
+ */
+export * from "./types.js";
+export * from "./postMessage.js";
+export * from "./http/index.js";
+export * from "./relay.js";
+import type { Transport } from "./types.js";
+/**
+ * Create the prescribed App-side transport per spec section 5.2.
+ *
+ * Always uses `window.parent.postMessage()` as the send primitive.
+ *
+ * @param hostOrigin - The host origin from URL params.
+ *   If provided, used as targetOrigin for postMessage and for validating
+ *   incoming message origins. If omitted, defaults to '*' (same-party
+ *   origin profile per spec).
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * // Same-party origin (no hostOrigin param)
+ * const transport = createAppTransport();
+ *
+ * // Third-party origin (hostOrigin from URL)
+ * const params = new URLSearchParams(window.location.search);
+ * const transport = createAppTransport(params.get("hostOrigin") ?? undefined);
+ * ```
+ */
+export declare function createAppTransport(hostWindow?: Window, hostOrigin?: string): Transport;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAKtF"}

package/dist/transport/index.js

@@ -0,0 +1,37 @@
+/**
+ * Transport layer for AppStrata Digital Signage SDK.
+ *
+ * Provides transport implementations for both App and Host sides.
+ */
+export * from "./types.js";
+export * from "./postMessage.js";
+export * from "./http/index.js";
+export * from "./relay.js";
+import { createPostMessageTransport } from "./postMessage.js";
+/**
+ * Create the prescribed App-side transport per spec section 5.2.
+ *
+ * Always uses `window.parent.postMessage()` as the send primitive.
+ *
+ * @param hostOrigin - The host origin from URL params.
+ *   If provided, used as targetOrigin for postMessage and for validating
+ *   incoming message origins. If omitted, defaults to '*' (same-party
+ *   origin profile per spec).
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * // Same-party origin (no hostOrigin param)
+ * const transport = createAppTransport();
+ *
+ * // Third-party origin (hostOrigin from URL)
+ * const params = new URLSearchParams(window.location.search);
+ * const transport = createAppTransport(params.get("hostOrigin") ?? undefined);
+ * ```
+ */
+export function createAppTransport(hostWindow, hostOrigin) {
+    return createPostMessageTransport({
+        targetWindow: hostWindow ?? window.parent,
+        targetOrigin: hostOrigin ?? "*",
+    });
+}

package/dist/transport/postMessage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PostMessage transport implementation.
+ *
+ * Unified transport for both host and app sides.
+ * Works for iframe and same-window scenarios.
+ */
+import type { Transport } from "./types.js";
+/**
+ * Options for creating a postMessage transport.
+ */
+export interface PostMessageTransportOptions {
+    /**
+     * The target window to communicate with.
+     *
+     * Host-side:
+     * - For iframe apps: iframe.contentWindow
+     * - For same-window apps: window
+     *
+     * App-side:
+     * - For iframe apps: window.parent
+     * - For same-window apps: window
+     */
+    targetWindow: Window;
+    /**
+     * Origin to use for postMessage security.
+     *
+     * @default
+     * - For same-window (targetWindow === window): window.location.origin
+     * - For cross-window (targetWindow !== window): "*"
+     */
+    targetOrigin?: string;
+}
+/**
+ * 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 declare function createPostMessageTransport(options: PostMessageTransportOptions): Transport;
+//# sourceMappingURL=postMessage.d.ts.map