@glivion/square-screen-js-sdk 0.1.0

package/.github/workflows/build-js-sdk.yml

@@ -0,0 +1,70 @@
+name: Build JS SDK
+
+on:
+  push:
+    branches: [ develop ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: ESLint
+        run: yarn lint
+
+      - name: Type check
+        run: yarn typecheck
+
+  test:
+    name: Test
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run tests
+        run: yarn test
+
+  build:
+    name: Build
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build
+        run: yarn build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

package/README.md

@@ -0,0 +1,463 @@
+# SquareScreen JS SDK
+
+A framework-agnostic JavaScript/TypeScript SDK for building SquareScreen digital signage players. It handles playlist fetching, local media caching, item advancement, background preloading, polling, heartbeats, and emergency alerts — all without touching the DOM.
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Architecture](#architecture)
+- [Player](#player)
+  - [Configuration](#configuration)
+  - [Events](#events)
+  - [Methods](#methods)
+- [Renderer (optional)](#renderer-optional)
+  - [Renderer configuration](#renderer-configuration)
+- [Cache layer](#cache-layer)
+  - [Custom cache provider](#custom-cache-provider)
+- [Framework integrations](#framework-integrations)
+  - [React](#react)
+  - [Vanilla JS](#vanilla-js)
+- [Mocking for development](#mocking-for-development)
+- [Example app](#example-app)
+
+---
+
+## Installation
+
+```bash
+npm install square-screen-js-sdk
+# or
+yarn add square-screen-js-sdk
+```
+
+---
+
+## Quick start
+
+```ts
+import { SquareScreenPlayer, SquareScreenRenderer } from "square-screen-js-sdk";
+
+const player = new SquareScreenPlayer({
+  deviceId: "your-device-uuid",
+  deviceToken: "your-device-token",
+  version: "1.0.0",
+});
+
+// Optional: attach the built-in renderer to a container element
+const renderer = new SquareScreenRenderer(
+  document.getElementById("screen"),
+  player,
+  { defaultTransition: "fade", transitionDuration: 500 },
+);
+renderer.mount();
+
+// Listen to player events
+player.addEventListener("itemchange", ({ detail }) => {
+  console.log("Now playing:", detail.item.name, `(${detail.index + 1}/${detail.total})`);
+});
+
+player.addEventListener("emergencyalert", ({ detail }) => {
+  if (detail.alert) console.warn("Emergency:", detail.alert.title);
+});
+
+player.addEventListener("statuschange", ({ detail }) => {
+  console.log("Status:", detail.status); // "connecting" | "online" | "offline"
+});
+
+await player.start();
+
+// Tear down
+player.stop();
+renderer.unmount();
+```
+
+---
+
+## Architecture
+
+The SDK is split into three independent layers:
+
+```
+┌─────────────────────────────────────────┐
+│            Your application             │
+└────────────────┬────────────────────────┘
+                 │ events / state
+┌────────────────▼────────────────────────┐
+│           SquareScreenPlayer            │  headless — no DOM
+│  · fetches & caches playlists           │
+│  · advances items by duration           │
+│  · background media preloading          │
+│  · polls for updates & emergency alerts │
+│  · heartbeat                            │
+└──────┬──────────────────┬───────────────┘
+       │                  │
+┌──────▼──────┐  ┌────────▼──────────────┐
+│ NetworkClient│  │    SquareScreenCache  │
+│  (fetch/API)│  │  IndexedDB + Cache API│
+└─────────────┘  └───────────────────────┘
+```
+
+The optional `SquareScreenRenderer` sits above your application and listens to `itemchange` events to manage `<img>` / `<video>` elements and CSS transitions. You can ignore it entirely and render with any framework.
+
+---
+
+## Player
+
+### Configuration
+
+All REST traffic uses the production API root bundled with the package (`SQUARESCREEN_API_BASE_URL`, currently `https://api.squarescreen.io/api/v1`). You cannot point the default client at another host; pass a custom `networkDataSource` only for tests, staging gateways, or non-standard deployments.
+
+```ts
+interface SquareScreenPlayerConfig {
+  /** Device UUID */
+  deviceId: string;
+  /** Device secret token — never expose this in client-side logs */
+  deviceToken: string;
+  /** SDK version string sent on every heartbeat */
+  version: string;
+  /** How long a cached playlist stays fresh in ms. Default: 5 minutes */
+  ttl?: number;
+  /** How often to poll for playlist updates in ms. Default: 30 seconds */
+  pollInterval?: number;
+  /** How often to poll for emergency alerts in ms. Default: 15 seconds */
+  emergencyPollInterval?: number;
+  /** How often to send a heartbeat in ms. Default: 60 seconds */
+  heartbeatInterval?: number;
+  /**
+   * Override the network layer with a custom implementation — useful for
+   * testing or mocking without a real API. When provided, deviceId and
+   * deviceToken are ignored for network calls.
+   */
+  networkDataSource?: NetworkDataSource;
+  /**
+   * Override the cache layer with a custom implementation. When omitted the
+   * default SquareScreenCache (IndexedDB + Cache API) is used.
+   */
+  cacheProvider?: SquareScreenCacheProvider;
+}
+```
+
+> **Note:** The constructor throws if `deviceId` or `deviceToken` is missing when no `networkDataSource` override is provided. With a mock or custom network layer, those credentials are not validated.
+
+### Events
+
+Use `addEventListener` / `removeEventListener` exactly like any DOM `EventTarget`. TypeScript users get full type inference on `event.detail`.
+
+| Event | Detail | When it fires |
+|---|---|---|
+| `itemchange` | `{ item: PlaylistItem, index: number, total: number }` | Current item advances |
+| `statuschange` | `{ status: DeviceStatus }` | Connectivity state changes (`"connecting"` → `"online"` / `"offline"`) |
+| `emergencyalert` | `{ alert: EmergencyAlert \| null }` | Alert becomes active, changes, or is cleared |
+| `playlistupdate` | `{ playlist: Playlist }` | Playlist is refreshed from the network or cache |
+
+```ts
+player.addEventListener("itemchange", ({ detail }) => {
+  const { item, index, total } = detail;
+  // item.url is a blob: URL if the media is cached locally,
+  // or the original HTTPS URL on first play (cached in the background).
+  // item.type is "image" | "video"
+  // item.duration is how long this item plays in seconds
+  // item.transition is "fade" | "slide" | "none"
+});
+```
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `start()` | Fetches the playlist, begins playback, starts polling and heartbeat. Returns a `Promise` that resolves once the first load attempt completes. |
+| `stop()` | Clears all timers and internal state. Call this when tearing down the player. |
+| `refreshPlaylist()` | Manually trigger a playlist refresh outside the normal poll cycle. |
+| `currentItem` | Getter — returns the currently playing `PlaylistItem`, or `null`. |
+
+---
+
+## Renderer (optional)
+
+`SquareScreenRenderer` is a vanilla JS DOM renderer that wires directly to a player instance. It is entirely optional — you can build your own rendering layer using the player's events.
+
+```ts
+import { SquareScreenRenderer } from "square-screen-js-sdk";
+
+const renderer = new SquareScreenRenderer(containerElement, player, options);
+renderer.mount();   // inject DOM and start listening
+renderer.unmount(); // remove DOM and stop listening
+```
+
+The renderer maintains two absolutely-positioned slot elements inside the container and alternates between them on each item change, enabling smooth cross-slot transitions.
+
+**What it handles:**
+- Creates and manages `<img>` and `<video>` elements
+- Waits for video `canplay` before transitioning (with a configurable timeout to prevent blocking on slow networks)
+- Sets `autoplay`, `muted`, `playsInline`, and `loop` on videos (required for browser autoplay policies and iOS)
+- Full-screen emergency alert overlay
+
+**What it does not handle:**
+- Emergency alert UI beyond the built-in overlay — listen to `"emergencyalert"` if you need custom presentation
+
+### Renderer configuration
+
+```ts
+interface SquareScreenRendererConfig {
+  /** Transition to use when an item has no transition set. Default: "none" */
+  defaultTransition?: "fade" | "slide" | "none";
+  /** Transition animation duration in ms. Default: 500 */
+  transitionDuration?: number;
+  /**
+   * Maximum ms to wait for a video to reach canplay before transitioning anyway.
+   * Prevents long stalls when media loads from a slow network on the first cycle.
+   * Default: 3000. Set to 0 to transition immediately without waiting.
+   */
+  canPlayTimeout?: number;
+}
+```
+
+---
+
+## Cache layer
+
+The cache layer is used internally by the player and requires no direct interaction in most cases.
+
+**How it works:**
+
+- **Playlist metadata** is stored in IndexedDB (via the `idb` library) with a per-record TTL. Each playlist is stored as a single document keyed by UUID; items are stored inline.
+- **Media blobs** are stored in the browser's Cache API, keyed by the original media URL. This is the same storage used by service workers, making future SW integration straightforward.
+- Once a blob is retrieved from the Cache API it is wrapped in a `URL.createObjectURL` handle that is kept in an in-memory map and reused on subsequent calls. All handles are revoked when `clear()` is called.
+
+**Media URL lifecycle:**
+
+On the **first cycle**, if a media file hasn't been downloaded yet, the player dispatches `itemchange` with the raw HTTPS URL immediately (no blocking). The file is downloaded in the background and stored in the Cache API. On every subsequent cycle the blob URL is used — transitions are instant.
+
+**Preloading:**
+
+Set `strategy.preloadCount` on the playlist to control how many upcoming items are pre-downloaded while the current item plays.
+
+```
+preloadCount: 1        →  always 1 item ahead
+preloadCount: 3        →  3 items ahead
+preloadCount: 0        →  disabled
+preloadCount: (absent) →  download entire playlist up front
+```
+
+**Offline fallback:**
+
+If the network is unavailable on start-up and the player has never loaded a playlist in the current session, it falls back to the last-known playlist UUID (stored in `localStorage`) and loads it from IndexedDB with `allowStale: true` — serving it even if its TTL has expired.
+
+### Custom cache provider
+
+Implement `SquareScreenCacheProvider` and pass it via `cacheProvider` to replace the default storage entirely:
+
+```ts
+import type { SquareScreenCacheProvider, Playlist } from "square-screen-js-sdk";
+
+const myCache: SquareScreenCacheProvider = {
+  async getPlaylist(uuid, allowStale) { /* ... */ return null; },
+  async savePlaylist(playlist, ttlMs) { /* ... */ },
+  async getMediaUrl(url) { /* ... */ return null; },
+  async saveMedia(url, blob) { /* ... */ return URL.createObjectURL(blob); },
+  async clear() { /* ... */ },
+};
+
+const player = new SquareScreenPlayer({ ..., cacheProvider: myCache });
+```
+
+---
+
+## Framework integrations
+
+### React
+
+Store named listener references so cleanup can call `removeEventListener` precisely — required for React StrictMode, which mounts effects twice.
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import {
+  SquareScreenPlayer,
+  SquareScreenRenderer,
+  type SquareScreenPlayerConfig,
+  type DeviceStatus,
+  type EmergencyAlert,
+  type PlaylistItem,
+} from "square-screen-js-sdk";
+
+function usePlayer(config: SquareScreenPlayerConfig | null) {
+  const playerRef = useRef<SquareScreenPlayer | null>(null);
+  const [state, setState] = useState({
+    status: "connecting" as DeviceStatus,
+    currentItem: null as PlaylistItem | null,
+    currentIndex: 0,
+    total: 0,
+    alert: null as EmergencyAlert | null,
+  });
+
+  useEffect(() => {
+    if (!config) return;
+    const player = new SquareScreenPlayer(config);
+    playerRef.current = player;
+
+    const onStatus: Parameters<typeof player.addEventListener<"statuschange">>[1] =
+      (e) => setState((s) => ({ ...s, status: e.detail.status }));
+
+    const onItem: Parameters<typeof player.addEventListener<"itemchange">>[1] =
+      (e) => setState((s) => ({
+        ...s,
+        currentItem: e.detail.item,
+        currentIndex: e.detail.index,
+        total: e.detail.total,
+      }));
+
+    const onAlert: Parameters<typeof player.addEventListener<"emergencyalert">>[1] =
+      (e) => setState((s) => ({ ...s, alert: e.detail.alert }));
+
+    player.addEventListener("statuschange", onStatus);
+    player.addEventListener("itemchange", onItem);
+    player.addEventListener("emergencyalert", onAlert);
+    player.start();
+
+    return () => {
+      player.removeEventListener("statuschange", onStatus);
+      player.removeEventListener("itemchange", onItem);
+      player.removeEventListener("emergencyalert", onAlert);
+      player.stop();
+      playerRef.current = null;
+    };
+  }, [config]);
+
+  return { player: playerRef.current, state };
+}
+
+// Renderer approach — SDK handles the DOM
+function RendererScreen({ config }: { config: SquareScreenPlayerConfig }) {
+  const { player } = usePlayer(config);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!player || !containerRef.current) return;
+    const renderer = new SquareScreenRenderer(containerRef.current, player, {
+      defaultTransition: "fade",
+      transitionDuration: 500,
+    });
+    renderer.mount();
+    return () => renderer.unmount();
+  }, [player]);
+
+  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
+}
+
+// Headless approach — you control the DOM
+function HeadlessScreen({ config }: { config: SquareScreenPlayerConfig }) {
+  const { state } = usePlayer(config);
+  const { currentItem } = state;
+  if (!currentItem) return null;
+  return currentItem.type === "video"
+    ? <video key={currentItem.uuid} src={currentItem.url} autoPlay muted playsInline loop />
+    : <img key={currentItem.uuid} src={currentItem.url} alt={currentItem.name} />;
+}
+```
+
+### Vanilla JS
+
+```js
+import { SquareScreenPlayer, SquareScreenRenderer } from "square-screen-js-sdk";
+
+const player = new SquareScreenPlayer({
+  deviceId: "device-uuid",
+  deviceToken: "device-token",
+  version: "1.0.0",
+  pollInterval: 30_000,
+});
+
+const renderer = new SquareScreenRenderer(
+  document.getElementById("screen"),
+  player,
+  { defaultTransition: "slide", transitionDuration: 400 },
+);
+renderer.mount();
+
+// Handle emergency alerts yourself
+player.addEventListener("emergencyalert", ({ detail }) => {
+  const ticker = document.getElementById("emergency-ticker");
+  if (detail.alert) {
+    ticker.textContent = `${detail.alert.title}: ${detail.alert.message}`;
+    ticker.hidden = false;
+  } else {
+    ticker.hidden = true;
+  }
+});
+
+await player.start();
+
+// Tear down when done
+player.stop();
+renderer.unmount();
+```
+
+---
+
+## Mocking for development
+
+Pass a `networkDataSource` to bypass the real API entirely:
+
+```ts
+import type { NetworkDataSource } from "square-screen-js-sdk";
+
+const mockDataSource: NetworkDataSource = {
+  fetchPlaylist: async () => ({
+    success: true,
+    data: {
+      uuid: "playlist-001",
+      cachedAt: Date.now(),
+      strategy: { loop: true, shuffle: false, preloadCount: 2 },
+      items: [
+        {
+          uuid: "item-001",
+          name: "Demo image",
+          type: "image",
+          url: "https://fastly.picsum.photos/id/10/2500/1667.jpg",
+          duration: 5,
+          transition: "fade",
+        },
+        {
+          uuid: "item-002",
+          name: "Demo video",
+          type: "video",
+          url: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
+          duration: 10,
+          transition: "slide",
+        },
+      ],
+    },
+  }),
+  fetchVideoPlaylist: async () => ({ success: false, error: { kind: "network", code: 0, message: "mock" } }),
+  fetchImagePlaylist: async () => ({ success: false, error: { kind: "network", code: 0, message: "mock" } }),
+  checkForEmergencyAlert: async () => ({ success: true, data: null }),
+  healthCheck: async () => ({ success: true, data: { received: true } }),
+  reportPlaybackEvent: async () => ({ success: true, data: { recorded: true } }),
+};
+
+const player = new SquareScreenPlayer({
+  deviceId: "",
+  deviceToken: "",
+  version: "1.0.0",
+  networkDataSource: mockDataSource,
+});
+```
+
+---
+
+## Example app
+
+A React example app lives in [`examples/react-app`](./examples/react-app). It demonstrates both the renderer and headless approaches side by side, with a built-in mock data source and an emergency alert toggle.
+
+```bash
+cd examples/react-app
+npm install
+npm run dev
+```
+
+The **Renderer** tab uses `SquareScreenRenderer` attached to a div — transitions and media lifecycle are fully managed by the SDK.
+
+The **Headless** tab renders directly with React JSX, using `key={item.uuid}` on media elements to force remount when the item changes.

package/eslint.config.js

@@ -0,0 +1,3 @@
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(tseslint.configs.recommended);

package/examples/react-app/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

package/examples/react-app/eslint.config.js

@@ -0,0 +1,22 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      globals: globals.browser,
+    },
+  },
+])

package/examples/react-app/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>react-app</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>