@appstrata/player-lib 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# @appstrata/player-lib
+
+Player implementation library for AppStrata digital signage platform.
+
+## Overview
+
+This package provides helpers for platform vendors implementing AppStrata-compliant players. It handles the host side of the message protocol and provides a high-level API for hosting apps.
+
+## Installation
+
+> **Note:** This is a private npm package. Requires an npm access token — contact the AppStrata team to get one, then add it to your `~/.npmrc`:
+>
+> ```
+> //registry.npmjs.org/:_authToken=YOUR_TOKEN
+> ```
+
+```bash
+npm install @appstrata/player-lib
+```
+
+## Quick Start
+
+### Session scope
+
+`createAppHost` (and the underlying `MessageBridge`) are **single-session**: one instance covers one App page load, from the initial handshake through `fireStop()` / `destroy()`. When the App reloads (e.g. due to a config change), you **must** destroy the old host and create a new one:
+
+```typescript
+// App reloads → tear down old, create fresh
+host.destroy();
+host = createAppHost({ ... });
+```
+
+Reusing a host across reloads is not supported. The handshake state is not reset between sessions.
+
+### Using createAppHost (Recommended)
+
+The `createAppHost` helper is the easiest way to host an AppStrata app. It automatically handles:
+- Protocol handshake (HELLO/READY/READY_ACK)
+- Lifecycle event routing via the message bridge
+- RPC operations for capability APIs
+
+```typescript
+import { createAppHost } from "@appstrata/player-lib";
+
+// Create app host
+const host = createAppHost({
+  services: { storage, proxy },
+  target: iframe.contentWindow!,
+  targetOrigin: "*",
+  notifyComplete: () => { /* handle playback complete */ },
+  notifyNoContent: (options) => { /* handle no content */ },
+  notifyEstimatedEnd: (expectedFinishTime) => { /* handle estimation */ },
+  log: (level, msg, data) => console.log(`[${level}]`, msg, data),
+});
+
+// Fire lifecycle events as needed
+const context = buildAppContext();
+host.fireInit(context);
+host.fireShow();
+host.fireStart();
+// ... later ...
+host.fireHide();
+host.fireStop();
+
+// Update context
+host.updateContext(newContext);
+
+// Cleanup when done
+host.destroy();
+```
+
+### Using MessageBridge (Advanced)
+
+For advanced use cases, you can use `MessageBridge` directly from `@appstrata/protocol`:
+
+```typescript
+import { MessageBridge, createPostMessageTransport } from "@appstrata/protocol";
+
+const transport = createPostMessageTransport({
+  targetWindow: iframe.contentWindow!,
+  targetOrigin: "*",
+});
+
+const bridge = new MessageBridge({
+  transport,
+  player: myPlayer,
+  getContext: async () => buildAppContext(),
+});
+
+bridge.start();
+
+// Fire lifecycle events
+bridge.fireShow();
+bridge.fireStart();
+```
+
+## API Reference
+
+### createAppHost
+
+High-level helper for hosting an AppStrata app.
+
+**Options:**
+- `services: CapabilityServices` - Capability service implementations (storage, proxy, etc.)
+- `target: Window` - Target window (typically `iframe.contentWindow`)
+- `transport?: Transport` - Optional transport (auto-created from target/targetOrigin if not provided)
+- `targetOrigin?: string` - Target origin for the default transport (default: `"*"`)
+- `notifyComplete: () => void` - Callback when app signals playback complete
+- `notifyEstimatedEnd: (expectedFinishTime: number) => void` - Callback when app provides estimated finish time (Unix ms)
+- `notifyNoContent: (options?) => void` - Callback when app signals no content (`{ retryNotBefore?: number; reason?: string }`)
+- `log: (level, message, data?) => void` - Logging callback
+- `debug?: boolean` - Enable debug logging (default: `false`)
+- `retryInterval?: number` - READY retry interval in ms (default: `1000`)
+- `maxRetries?: number` - Max READY retries (default: `10`)
+
+**Returns:** `AppHost` with methods:
+- `fireInit(context)`: Initialize with AppContext
+- `fireShow()`: Fire show event
+- `fireStart()`: Fire start event
+- `fireHide()`: Fire hide event
+- `fireStop()`: Fire stop event
+- `updateContext(context)`: Update context
+- `destroy()`: Cleanup resources
+- `player`: Direct access to the underlying SignagePlayer
+
+## Protocol Details
+
+The library implements the AppStrata message protocol:
+
+1. **Handshake:**
+   - App sends HELLO (optional)
+   - Host sends READY with AppContext
+   - If no HELLO received, host retries READY until READY_ACK
+   - App sends READY_ACK
+
+2. **RPC:**
+   - App sends REQUEST
+   - Host routes to SignagePlayer capability methods
+   - Host sends RESPONSE
+
+3. **Events:**
+   - Host sends EVENT (show, start, hide, stop, contextChange)
+   - Events are queued if sent before READY_ACK, then flushed
+
+## License
+
+MIT

package/dist/app-host.d.ts

@@ -0,0 +1,161 @@
+/**
+ * AppHost - Host-side player controller.
+ *
+ * Encapsulates the SignagePlayer and player-side state such as the current AppContext and
+ * registeredlifecycle handlers.
+ * Provides fire methods for Players to trigger lifecycle events.
+ */
+import { type SignagePlayer, type AppContext, type LogLevel, type StorageApi, type ProxyApi, type MediaCacheApi, type StaticApi } from "@appstrata/core";
+import type { Transport } from "@appstrata/protocol";
+/**
+ * Capability services that can be provided to the host.
+ */
+export interface CapabilityServices {
+    storage?: StorageApi;
+    proxy?: ProxyApi;
+    mediaCache?: MediaCacheApi;
+    static?: StaticApi;
+}
+/**
+ * AppHost interface - Host-side player controller.
+ *
+ * **Single-session:** one `AppHost` instance covers one App page load. The
+ * handshake state is not reset between sessions. When the App reloads (e.g.
+ * the iframe navigates), call `destroy()` on the old host and create a new
+ * instance for the incoming session. Reusing an `AppHost` across sessions is
+ * not supported and will result in protocol errors (duplicate / stale READY).
+ *
+ * > Future versions may introduce multi-session support.
+ */
+export interface AppHost {
+    /**
+     * Direct access to the underlying SignagePlayer interface.
+     *
+     * This property is primarily useful for testing and debugging.
+     */
+    readonly player: SignagePlayer;
+    /**
+     * Fire init lifecycle event with the given AppContext.
+     */
+    fireInit(context: AppContext): void;
+    /**
+     * Fire show lifecycle event (app is about to become visible).
+     */
+    fireShow(): void;
+    /**
+     * Fire start lifecycle event (app is visible and should start playback).
+     */
+    fireStart(): void;
+    /**
+     * Fire hide lifecycle event (app is about to be hidden).
+     */
+    fireHide(): void;
+    /**
+     * Fire stop lifecycle event (app is hidden and should stop playback).
+     */
+    fireStop(): void;
+    /**
+     * Fire context change event with the given context.
+     * Should only be called after fireInit() has been called.
+     */
+    updateContext(context: AppContext): void;
+    /**
+     * Hot-swap capability services at runtime.
+     * Updates the player's service references and rebuilds the internal
+     * capabilities array so that subsequent RPC calls route correctly.
+     * This is useful for development players that need to hot-swap services at runtime.
+     */
+    updateServices(services: CapabilityServices): void;
+    /**
+     * Cleanup resources.
+     */
+    destroy(): void;
+}
+/**
+ * Options for creating an AppHost.
+ */
+export interface CreateAppHostOptions {
+    /**
+     * Capability service implementations.
+     */
+    services: CapabilityServices;
+    /**
+     * Transport to use. If not provided, a postMessage transport
+     * will be created by default based on the target window and target origin.
+     */
+    transport?: Transport;
+    /**
+     * Target window to use when creating the default transport.
+     */
+    target: Window;
+    /**
+     * Target origin to use when creating the default transport.
+     * @default "*"
+     */
+    targetOrigin?: string;
+    /**
+     * Retry interval in milliseconds for sending READY messages.
+     * @default 1000 (1 second)
+     */
+    retryInterval?: number;
+    /**
+     * Maximum number of retries for sending READY messages.
+     * @default 10
+     */
+    maxRetries?: number;
+    /**
+     * Called when the app signals it has finished playback.
+     * Vendors MUST provide their own implementation.
+     */
+    notifyComplete: () => void;
+    /**
+     * Called when the app provides an estimated finish time.
+     * Vendors MUST provide their own implementation.
+     *
+     * @param expectedFinishTime - Absolute epoch timestamp in ms (already
+     *   converted from the app-facing totalDuration/finishTime by the SDK)
+     */
+    notifyEstimatedEnd: (expectedFinishTime: number) => void;
+    /**
+     * Called when the app signals it has no content to display.
+     * Vendors MUST provide their own implementation.
+     *
+     * @param options - Optional retry and reason info
+     * @param options.retryNotBefore - Earliest time to retry (epoch timestamp in ms)
+     * @param options.reason - Human-readable reason
+     */
+    notifyNoContent: (options?: {
+        retryNotBefore?: number;
+        reason?: string;
+    }) => void;
+    /**
+     * Implementation for logging.
+     * Vendors MUST provide their own implementation.
+     *
+     * @param level - Log level
+     * @param message - Log message
+     * @param data - Optional data to log
+     */
+    log: (level: LogLevel, message: string, data?: unknown) => void;
+}
+/**
+ * Create an AppHost for managing an app instance.
+ *
+ * @example
+ * ```typescript
+ * const host = createAppHost({
+ *   services: { storage, proxy },
+ *   target: iframe.contentWindow!,
+ *   notifyComplete: () => { ... },
+ *   log: (level, msg) => console.log(msg),
+ * });
+ *
+ * // Fire lifecycle events with AppContext
+ * const appContext = buildContextFromVendor(vendorContext);
+ * host.fireInit(appContext);
+ * host.fireShow();
+ * host.fireStart();
+ * ```
+ */
+export declare function createAppHost(options: CreateAppHostOptions): AppHost;
+//# sourceMappingURL=app-host.d.ts.map

package/dist/app-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-host.d.ts","sourceRoot":"","sources":["../src/app-host.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EAEf,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAUrD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAEpC;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;OAEG;IACH,SAAS,IAAI,IAAI,CAAC;IAElB;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAEzC;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAEnD;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,EAAE,kBAAkB,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,cAAc,EAAE,MAAM,IAAI,CAAC;IAE3B;;;;;;OAMG;IACH,kBAAkB,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzD;;;;;;;OAOG;IACH,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAElF;;;;;;;OAOG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACjE;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CA6NT"}

package/dist/app-host.js

@@ -0,0 +1,219 @@
+/**
+ * AppHost - Host-side player controller.
+ *
+ * Encapsulates the SignagePlayer and player-side state such as the current AppContext and
+ * registeredlifecycle handlers.
+ * Provides fire methods for Players to trigger lifecycle events.
+ */
+import { LifecyclePhase, createLogger, } from "@appstrata/core";
+const logger = createLogger("AppHost");
+import { MessageBridge, createPostMessageTransport, } from "@appstrata/protocol";
+// ═══════════════════════════════════════════════════════════════════════════
+// IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Create an AppHost for managing an app instance.
+ *
+ * @example
+ * ```typescript
+ * const host = createAppHost({
+ *   services: { storage, proxy },
+ *   target: iframe.contentWindow!,
+ *   notifyComplete: () => { ... },
+ *   log: (level, msg) => console.log(msg),
+ * });
+ *
+ * // Fire lifecycle events with AppContext
+ * const appContext = buildContextFromVendor(vendorContext);
+ * host.fireInit(appContext);
+ * host.fireShow();
+ * host.fireStart();
+ * ```
+ */
+export function createAppHost(options) {
+    const { services, transport, target, targetOrigin = "*", retryInterval, maxRetries, notifyComplete, notifyEstimatedEnd, notifyNoContent, log, } = options;
+    // ═══════════════════════════════════════════════════════════════════════
+    // Internal state
+    // ═══════════════════════════════════════════════════════════════════════
+    let context = null;
+    let resolveReady;
+    const readyPromise = new Promise((r) => { resolveReady = r; });
+    // Lifecycle handlers (arrays for predictable ordering)
+    const handlers = {
+        onInit: [],
+        onShow: [],
+        onStart: [],
+        onHide: [],
+        onStop: [],
+        onContextChange: [],
+    };
+    // Determine capabilities from services
+    const capabilities = [];
+    if (services.storage)
+        capabilities.push("storage");
+    if (services.proxy)
+        capabilities.push("proxy");
+    if (services.mediaCache)
+        capabilities.push("mediaCache");
+    if (services.static)
+        capabilities.push("static");
+    // ═══════════════════════════════════════════════════════════════════════
+    // SignagePlayer (apps interface) - used by MessageBridge for RPC routing
+    // ═══════════════════════════════════════════════════════════════════════
+    const player = {
+        apiVersion: "1.0.0",
+        lifecyclePhase: LifecyclePhase.None,
+        async getContext() {
+            await readyPromise;
+            return context;
+        },
+        async hasCapability(cap) {
+            return capabilities.includes(cap);
+        },
+        onInit(handler) {
+            if (context)
+                handler(context); // Late subscriber
+            handlers.onInit.push(handler);
+        },
+        onShow(handler) { handlers.onShow.push(handler); },
+        onStart(handler) { handlers.onStart.push(handler); },
+        onHide(handler) { handlers.onHide.push(handler); },
+        onStop(handler) { handlers.onStop.push(handler); },
+        onContextChange(handler) { handlers.onContextChange.push(handler); },
+        notifyComplete() {
+            notifyComplete();
+        },
+        notifyEstimatedEnd(options) {
+            notifyEstimatedEnd(options?.expectedFinishTime ?? options);
+        },
+        notifyNoContent(options) {
+            notifyNoContent(options);
+        },
+        storage: services.storage,
+        proxy: services.proxy,
+        mediaCache: services.mediaCache,
+        static: services.static,
+        log(level, message, data) {
+            log(level, message, data);
+        },
+    };
+    // ═══════════════════════════════════════════════════════════════════════
+    // Message bridge setup
+    // ═══════════════════════════════════════════════════════════════════════
+    const ownsTransport = !transport;
+    const transportToUse = transport ?? createPostMessageTransport({
+        targetWindow: target,
+        targetOrigin: targetOrigin,
+    });
+    const bridge = new MessageBridge({
+        transport: transportToUse,
+        getContext: player.getContext, // we could probably drop this, since we are passing the player to the bridge
+        player,
+        ...(retryInterval !== undefined && { retryInterval }), // keep default values if not provided
+        ...(maxRetries !== undefined && { maxRetries }), // keep default values if not provided
+    });
+    // Forward lifecycle events through the message bridge
+    handlers.onShow.push(() => bridge.fireShow());
+    handlers.onStart.push(() => bridge.fireStart());
+    handlers.onHide.push(() => bridge.fireHide());
+    handlers.onStop.push(() => bridge.fireStop());
+    handlers.onContextChange.push((ctx) => bridge.fireContextChange(ctx));
+    // This will send a proactive READY 
+    // as soon as the context is available.
+    bridge.start();
+    logger.info("AppHost created, message bridge started");
+    // ═══════════════════════════════════════════════════════════════════════
+    // Helper functions for safe handler execution
+    // ═══════════════════════════════════════════════════════════════════════
+    /**
+     * Safely execute lifecycle handlers.
+     * Catches and logs errors to prevent one handler from breaking the chain.
+     */
+    function fireLifecycleHandlers(handlerArray) {
+        for (const handler of handlerArray) {
+            try {
+                handler();
+            }
+            catch (error) {
+                logger.error("Error in lifecycle handler", error);
+            }
+        }
+    }
+    function setPhase(phase) {
+        player.lifecyclePhase = phase;
+    }
+    /**
+     * Safely execute context handlers.
+     * Catches and logs errors to prevent one handler from breaking the chain.
+     */
+    function fireContextHandlers(handlerArray, ctx) {
+        for (const handler of handlerArray) {
+            try {
+                handler(ctx);
+            }
+            catch (error) {
+                logger.error("Error in context handler", error);
+            }
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // AppHost interface
+    // ═══════════════════════════════════════════════════════════════════════
+    return {
+        player,
+        fireInit(appContext) {
+            context = appContext;
+            setPhase(LifecyclePhase.Init);
+            resolveReady();
+            fireContextHandlers(handlers.onInit, context);
+        },
+        fireShow() {
+            setPhase(LifecyclePhase.Show);
+            fireLifecycleHandlers(handlers.onShow);
+        },
+        fireStart() {
+            setPhase(LifecyclePhase.Start);
+            fireLifecycleHandlers(handlers.onStart);
+        },
+        fireHide() {
+            setPhase(LifecyclePhase.Hide);
+            fireLifecycleHandlers(handlers.onHide);
+        },
+        fireStop() {
+            setPhase(LifecyclePhase.Stop);
+            fireLifecycleHandlers(handlers.onStop);
+        },
+        updateContext(appContext) {
+            if (!context) {
+                throw new Error("Cannot update context before context is initialized");
+            }
+            context = appContext;
+            fireContextHandlers(handlers.onContextChange, context);
+        },
+        updateServices(newServices) {
+            player.storage = newServices.storage;
+            player.proxy = newServices.proxy;
+            player.mediaCache = newServices.mediaCache;
+            player.static = newServices.static;
+            capabilities.length = 0;
+            if (newServices.storage)
+                capabilities.push("storage");
+            if (newServices.proxy)
+                capabilities.push("proxy");
+            if (newServices.mediaCache)
+                capabilities.push("mediaCache");
+            if (newServices.static)
+                capabilities.push("static");
+        },
+        destroy() {
+            bridge.destroy();
+            // Close the transport only if we created it internally.
+            // When the caller passes their own transport, they own its lifecycle.
+            if (ownsTransport) {
+                transportToUse.close();
+            }
+            // remove all registered lifecycle handlers
+            Object.values(handlers).forEach((arr) => (arr.length = 0));
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @appstrata/player-lib - Player implementation library
+ *
+ * Provides the createAppHost() function for platform vendors implementing
+ * AppStrata-compliant players. Creates an AppHost instance.
+ *
+ * @packageDocumentation
+ */
+export * from "@appstrata/protocol";
+export type { AppHost, CreateAppHostOptions, CapabilityServices } from "./app-host.js";
+export { createAppHost } from "./app-host.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,cAAc,qBAAqB,CAAC;AAGpC,YAAY,EAAE,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @appstrata/player-lib - Player implementation library
+ *
+ * Provides the createAppHost() function for platform vendors implementing
+ * AppStrata-compliant players. Creates an AppHost instance.
+ *
+ * @packageDocumentation
+ */
+// Re-export everything from protocol for convenience
+export * from "@appstrata/protocol";
+export { createAppHost } from "./app-host.js";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@appstrata/player-lib",
+  "version": "0.1.0",
+  "description": "AppStrata Player Library - Helpers for platform vendors implementing compliant players",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "digital-signage",
+    "appstrata",
+    "player",
+    "cms"
+  ],
+  "author": "AppStrata",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@appstrata/core": "0.1.0",
+    "@appstrata/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.11",
+    "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"
+  }
+}