@appstrata/protocol 0.1.0

package/dist/messages.js

@@ -0,0 +1,141 @@
+/**
+ * Protocol message types from the AppStrata specification.
+ *
+ * Defines all message types used in the HELLO/READY/READY_ACK handshake
+ * and subsequent RPC and event communication.
+ */
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE GUARDS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Type guard to check if data is a valid protocol message.
+ *
+ * Validates the base structure: protocol identifier, version, and type.
+ */
+export function isProtocolMessage(data) {
+    if (typeof data !== "object" || data === null) {
+        return false;
+    }
+    const msg = data;
+    return (msg.protocol === "appstrata-protocol" &&
+        msg.version === "1.0" &&
+        typeof msg.type === "string" &&
+        typeof msg.timestamp === "number");
+}
+/**
+ * Type guard for HELLO message.
+ */
+export function isHelloMessage(msg) {
+    return msg.type === "HELLO";
+}
+/**
+ * Type guard for READY message.
+ */
+export function isReadyMessage(msg) {
+    return msg.type === "READY";
+}
+/**
+ * Type guard for READY_ACK message.
+ */
+export function isReadyAckMessage(msg) {
+    return msg.type === "READY_ACK";
+}
+/**
+ * Type guard for REQUEST message.
+ */
+export function isRequestMessage(msg) {
+    return msg.type === "REQUEST";
+}
+/**
+ * Type guard for RESPONSE message.
+ */
+export function isResponseMessage(msg) {
+    return msg.type === "RESPONSE";
+}
+/**
+ * Type guard for EVENT message.
+ */
+export function isEventMessage(msg) {
+    return msg.type === "EVENT";
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// UTILITY FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Generate a unique request ID (UUID v4).
+ *
+ * @returns Unique request identifier
+ */
+export function generateRequestId() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    // Fallback: manual UUID v4
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Convert wire format context to AppContext.
+ *
+ * Adds the hasCapability() method to the context.
+ *
+ * @param wireContext - Context from wire protocol
+ * @returns AppContext with hasCapability method
+ */
+export function wireContextToAppContext(wireContext) {
+    const capabilities = wireContext.capabilities || [];
+    let duration;
+    if (wireContext.duration === -1) {
+        duration = undefined;
+    }
+    else if (wireContext.duration === -2) {
+        duration = Infinity;
+    }
+    else {
+        duration = wireContext.duration;
+    }
+    return {
+        ...wireContext,
+        duration,
+        hasCapability: (capability) => capabilities.includes(capability)
+    };
+}
+/**
+ * Convert AppContext to wire format.
+ *
+ * Extracts capabilities array from hasCapability method.
+ *
+ * @param context - AppContext with hasCapability method
+ * @returns Wire format context with capabilities array
+ */
+export function appContextToWire(context) {
+    // Extract capabilities by checking hasCapability for known capabilities
+    const capabilities = [];
+    const knownCapabilities = ["storage", "proxy", "mediaCache", "static", "interaction"];
+    for (const cap of knownCapabilities) {
+        if (context.hasCapability(cap)) {
+            capabilities.push(cap);
+        }
+    }
+    // Convert duration: null/undefined -> -1, Infinity -> -2
+    let wireDuration;
+    if (context.duration == null) {
+        wireDuration = -1;
+    }
+    else if (context.duration === Infinity) {
+        wireDuration = -2;
+    }
+    else {
+        wireDuration = context.duration;
+    }
+    // Copy all properties except hasCapability, then add capabilities array
+    const { hasCapability, ...rest } = context;
+    return {
+        ...rest,
+        duration: wireDuration,
+        capabilities,
+    };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Long-polling client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives messages by long-polling a
+ * server endpoint. The server holds the request until messages are
+ * available or a timeout elapses.
+ */
+import type { Transport } from "../types.js";
+import type { HttpClientTransportOptions } from "./types.js";
+/**
+ * Create a long-polling client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives by polling.
+ *
+ * @param options - Transport configuration options
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * const transport = createHttpPollingTransport({
+ *   sendUrl: "https://player.example.com/api/send",
+ *   receiveUrl: "https://player.example.com/api/receive",
+ *   sessionId: "abc-123",
+ *   authToken: "secret-token"
+ * });
+ *
+ * transport.onMessage((msg) => console.log("Received:", msg));
+ * transport.send({ protocol: "appstrata-protocol", version: "1.0", timestamp: Date.now(), type: "HELLO" });
+ * ```
+ */
+export declare function createHttpPollingTransport(options: HttpClientTransportOptions): Transport;
+//# sourceMappingURL=client-polling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-polling.d.ts","sourceRoot":"","sources":["../../../src/transport/http/client-polling.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAiLzF"}

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

@@ -0,0 +1,181 @@
+/**
+ * Long-polling client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives messages by long-polling a
+ * server endpoint. The server holds the request until messages are
+ * available or a timeout elapses.
+ */
+import { createLogger } from "@appstrata/core";
+import { isProtocolMessage } from "../../messages.js";
+/**
+ * Create a long-polling client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives by polling.
+ *
+ * @param options - Transport configuration options
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * const transport = createHttpPollingTransport({
+ *   sendUrl: "https://player.example.com/api/send",
+ *   receiveUrl: "https://player.example.com/api/receive",
+ *   sessionId: "abc-123",
+ *   authToken: "secret-token"
+ * });
+ *
+ * transport.onMessage((msg) => console.log("Received:", msg));
+ * transport.send({ protocol: "appstrata-protocol", version: "1.0", timestamp: Date.now(), type: "HELLO" });
+ * ```
+ */
+export function createHttpPollingTransport(options) {
+    const { sendUrl, receiveUrl, sessionId, authToken, timeout = 30000, headers: customHeaders = {}, } = options;
+    const logger = createLogger("HttpPolling");
+    const handlers = new Set();
+    let closed = false;
+    let pollAbortController = null;
+    /**
+     * Build common headers for POST requests.
+     */
+    function buildHeaders() {
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Session-Id": sessionId,
+            ...customHeaders,
+        };
+        if (authToken) {
+            headers["Authorization"] = `Bearer ${authToken}`;
+        }
+        return headers;
+    }
+    /**
+     * Dispatch message to all handlers.
+     */
+    function dispatchMessage(message) {
+        for (const handler of [...handlers]) {
+            try {
+                handler(message);
+            }
+            catch (error) {
+                logger.error("Error in message handler", error);
+            }
+        }
+    }
+    /**
+     * Run a single poll cycle: fetch messages, dispatch, repeat.
+     */
+    async function pollLoop() {
+        while (!closed) {
+            try {
+                pollAbortController = new AbortController();
+                const pollUrl = new URL(receiveUrl);
+                pollUrl.searchParams.set("sessionId", sessionId);
+                if (authToken) {
+                    pollUrl.searchParams.set("token", authToken);
+                }
+                logger.debug(`Polling: ${pollUrl.toString()}`);
+                const response = await fetch(pollUrl.toString(), {
+                    method: "GET",
+                    headers: {
+                        Accept: "application/json",
+                        ...customHeaders,
+                        ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+                    },
+                    signal: pollAbortController.signal,
+                });
+                if (closed)
+                    break;
+                if (!response.ok) {
+                    logger.debug(`Poll failed: HTTP ${response.status}, retrying in 3s...`);
+                    await delay(3000, pollAbortController.signal);
+                    continue;
+                }
+                const data = await response.json();
+                // Server returns { messages: [...] }
+                const messages = Array.isArray(data?.messages) ? data.messages : [];
+                for (const msg of messages) {
+                    if (isProtocolMessage(msg)) {
+                        dispatchMessage(msg);
+                    }
+                }
+                // Immediately poll again (no delay — the server holds the request)
+            }
+            catch (error) {
+                if (closed)
+                    break;
+                const isAbort = error instanceof Error && error.name === "AbortError";
+                if (!isAbort) {
+                    logger.debug("Poll error, retrying in 3s...", error);
+                    // Re-use the same controller for the delay; if close() was
+                    // called while the fetch was in-flight the signal is already
+                    // aborted and delay() resolves immediately.
+                    if (pollAbortController) {
+                        await delay(3000, pollAbortController.signal);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Delay that resolves after `ms`, or immediately if `signal` is aborted.
+     * Used for retry backoff on poll errors. The signal comes from
+     * `pollAbortController`, so `close()` cancels any in-progress delay
+     * via the same `abort()` call that cancels the fetch.
+     */
+    function delay(ms, signal) {
+        if (signal.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            signal.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+    }
+    // Start polling immediately
+    pollLoop();
+    return {
+        send(message) {
+            if (closed) {
+                logger.debug("Cannot send message: transport is closed");
+                return;
+            }
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            fetch(sendUrl, {
+                method: "POST",
+                headers: buildHeaders(),
+                body: JSON.stringify(message),
+                signal: controller.signal,
+            })
+                .then((response) => {
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    logger.error(`Send failed: HTTP ${response.status}`);
+                }
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                if (error.name === "AbortError") {
+                    logger.error("Send request timed out");
+                }
+                else {
+                    logger.error("Send error", error);
+                }
+            });
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close() {
+            closed = true;
+            if (pollAbortController) {
+                pollAbortController.abort();
+                pollAbortController = null;
+            }
+            handlers.clear();
+        },
+    };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * SSE client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives messages via Server-Sent Events (SSE).
+ */
+import type { Transport } from "../types.js";
+import type { HttpClientTransportOptions } from "./types.js";
+/**
+ * Create an SSE-based client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives via SSE.
+ *
+ * @param options - Transport configuration options
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * const transport = createHttpSseTransport({
+ *   sendUrl: "https://player.example.com/api/send",
+ *   receiveUrl: "https://player.example.com/api/receive",
+ *   sessionId: "abc-123",
+ *   authToken: "secret-token"
+ * });
+ *
+ * transport.onMessage((msg) => console.log("Received:", msg));
+ * transport.send({ protocol: "appstrata-protocol", version: "1.0", timestamp: Date.now(), type: "HELLO" });
+ * ```
+ */
+export declare function createHttpSseTransport(options: HttpClientTransportOptions): Transport;
+//# sourceMappingURL=client-sse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-sse.d.ts","sourceRoot":"","sources":["../../../src/transport/http/client-sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAuJrF"}

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

@@ -0,0 +1,155 @@
+/**
+ * SSE client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives messages via Server-Sent Events (SSE).
+ */
+import { createLogger } from "@appstrata/core";
+import { isProtocolMessage } from "../../messages.js";
+/**
+ * Create an SSE-based client-side HTTP transport.
+ *
+ * Sends messages via HTTP POST, receives via SSE.
+ *
+ * @param options - Transport configuration options
+ * @returns Transport instance
+ *
+ * @example
+ * ```ts
+ * const transport = createHttpSseTransport({
+ *   sendUrl: "https://player.example.com/api/send",
+ *   receiveUrl: "https://player.example.com/api/receive",
+ *   sessionId: "abc-123",
+ *   authToken: "secret-token"
+ * });
+ *
+ * transport.onMessage((msg) => console.log("Received:", msg));
+ * transport.send({ protocol: "appstrata-protocol", version: "1.0", timestamp: Date.now(), type: "HELLO" });
+ * ```
+ */
+export function createHttpSseTransport(options) {
+    const { sendUrl, receiveUrl, sessionId, authToken, timeout = 30000, headers: customHeaders = {}, } = options;
+    const logger = createLogger("HttpSSE");
+    const handlers = new Set();
+    let eventSource = null;
+    let closed = false;
+    let reconnectTimer = null;
+    /**
+     * Build common headers for requests.
+     */
+    function buildHeaders() {
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Session-Id": sessionId,
+            ...customHeaders,
+        };
+        if (authToken) {
+            headers["Authorization"] = `Bearer ${authToken}`;
+        }
+        return headers;
+    }
+    /**
+     * Dispatch message to all handlers.
+     */
+    function dispatchMessage(message) {
+        for (const handler of [...handlers]) {
+            try {
+                handler(message);
+            }
+            catch (error) {
+                logger.error("Error in message handler", error);
+            }
+        }
+    }
+    /**
+     * Start SSE connection for receiving messages.
+     */
+    function startSSE() {
+        if (closed || eventSource)
+            return;
+        const eventsUrl = new URL(receiveUrl);
+        eventsUrl.searchParams.set("sessionId", sessionId);
+        // Note: EventSource doesn't support custom headers directly.
+        // For auth, we pass the token as a query param (or use cookies).
+        if (authToken) {
+            eventsUrl.searchParams.set("token", authToken);
+        }
+        logger.debug(`Connecting to SSE: ${eventsUrl.toString()}`);
+        eventSource = new EventSource(eventsUrl.toString());
+        eventSource.onopen = () => {
+            logger.debug(`SSE connected (session ${sessionId})`);
+        };
+        eventSource.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                if (isProtocolMessage(data)) {
+                    dispatchMessage(data);
+                }
+            }
+            catch (error) {
+                logger.error("Failed to parse SSE message", error);
+            }
+        };
+        eventSource.onerror = () => {
+            if (!closed && eventSource) {
+                logger.debug(`SSE disconnected (session ${sessionId}), reconnecting in 3s...`);
+                eventSource.close();
+                eventSource = null;
+                reconnectTimer = setTimeout(() => {
+                    reconnectTimer = null;
+                    if (!closed) {
+                        startSSE();
+                    }
+                }, 3000);
+            }
+        };
+    }
+    // Start SSE connection immediately
+    startSSE();
+    return {
+        send(message) {
+            if (closed) {
+                logger.debug("Cannot send message: transport is closed");
+                return;
+            }
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            fetch(sendUrl, {
+                method: "POST",
+                headers: buildHeaders(),
+                body: JSON.stringify(message),
+                signal: controller.signal,
+            })
+                .then((response) => {
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    logger.error(`Send failed: HTTP ${response.status}`);
+                }
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                if (error.name === "AbortError") {
+                    logger.error("Send request timed out");
+                }
+                else {
+                    logger.error("Send error", error);
+                }
+            });
+        },
+        onMessage(handler) {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close() {
+            closed = true;
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+            if (eventSource) {
+                eventSource.close();
+                eventSource = null;
+            }
+            handlers.clear();
+        },
+    };
+}

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

@@ -0,0 +1,63 @@
+/**
+ * HTTP host transport session manager.
+ *
+ * Manages multiple `HttpHostTransport` instances (one per client session).
+ * Uses inversion of control: the caller supplies a factory function that
+ * creates the concrete transport (SSE, long-polling, or any future variant).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createHttpHostTransportManager } from "./host-manager.js";
+ * import { createHttpSseHostTransport } from "./host-sse.js";
+ *
+ * const manager = createHttpHostTransportManager(
+ *   (sessionId) => createHttpSseHostTransport({ sessionId })
+ * );
+ *
+ * const transport = manager.getTransport("session-123");
+ * ```
+ */
+import type { ProtocolMessage } from "../../messages.js";
+import type { HttpHostTransport } from "./types.js";
+/**
+ * Factory function that creates an `HttpHostTransport` for a given session.
+ */
+export type HttpHostTransportFactory = (sessionId: string) => HttpHostTransport;
+/**
+ * Manages multiple HTTP host transports, one per client session.
+ *
+ * Useful for server implementations that handle multiple concurrent clients.
+ */
+export interface HttpHostTransportManager {
+    /**
+     * Get or create a transport for a session.
+     */
+    getTransport(sessionId: string): HttpHostTransport;
+    /**
+     * Check if a session exists.
+     */
+    hasSession(sessionId: string): boolean;
+    /**
+     * Close and remove a session.
+     */
+    closeSession(sessionId: string): void;
+    /**
+     * Register a handler for messages from any session.
+     */
+    onMessage(handler: (sessionId: string, message: ProtocolMessage) => void): () => void;
+    /**
+     * Close all sessions.
+     */
+    closeAll(): void;
+}
+/**
+ * Create a manager for multiple sessions.
+ *
+ * Uses the provided `factory` to create transports on demand.
+ * `getTransport(sessionId)` returns an existing transport or creates one.
+ *
+ * @param factory - Function that creates an HttpHostTransport for a session ID
+ */
+export declare function createHttpHostTransportManager(factory: HttpHostTransportFactory): HttpHostTransportManager;
+//# sourceMappingURL=host-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host-manager.d.ts","sourceRoot":"","sources":["../../../src/transport/http/host-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,iBAAiB,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAEnD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEtF;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,wBAAwB,GAChC,wBAAwB,CAoD1B"}

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

@@ -0,0 +1,74 @@
+/**
+ * HTTP host transport session manager.
+ *
+ * Manages multiple `HttpHostTransport` instances (one per client session).
+ * Uses inversion of control: the caller supplies a factory function that
+ * creates the concrete transport (SSE, long-polling, or any future variant).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createHttpHostTransportManager } from "./host-manager.js";
+ * import { createHttpSseHostTransport } from "./host-sse.js";
+ *
+ * const manager = createHttpHostTransportManager(
+ *   (sessionId) => createHttpSseHostTransport({ sessionId })
+ * );
+ *
+ * const transport = manager.getTransport("session-123");
+ * ```
+ */
+/**
+ * Create a manager for multiple sessions.
+ *
+ * Uses the provided `factory` to create transports on demand.
+ * `getTransport(sessionId)` returns an existing transport or creates one.
+ *
+ * @param factory - Function that creates an HttpHostTransport for a session ID
+ */
+export function createHttpHostTransportManager(factory) {
+    const transports = new Map();
+    const globalHandlers = new Set();
+    return {
+        getTransport(sessionId) {
+            let transport = transports.get(sessionId);
+            if (!transport) {
+                transport = factory(sessionId);
+                transports.set(sessionId, transport);
+                // Wire up global handlers
+                transport.onMessage((message) => {
+                    for (const handler of [...globalHandlers]) {
+                        try {
+                            handler(sessionId, message);
+                        }
+                        catch (error) {
+                            console.error(`[AppStrata Host] Error in global handler:`, error);
+                        }
+                    }
+                });
+            }
+            return transport;
+        },
+        hasSession(sessionId) {
+            return transports.has(sessionId);
+        },
+        closeSession(sessionId) {
+            const transport = transports.get(sessionId);
+            if (transport) {
+                transport.close();
+                transports.delete(sessionId);
+            }
+        },
+        onMessage(handler) {
+            globalHandlers.add(handler);
+            return () => globalHandlers.delete(handler);
+        },
+        closeAll() {
+            for (const transport of transports.values()) {
+                transport.close();
+            }
+            transports.clear();
+            globalHandlers.clear();
+        },
+    };
+}