@glivion/square-screen-js-sdk 0.1.0

package/src/network/apiTypes.ts

@@ -0,0 +1,89 @@
+/**
+ * Raw API response types — internal to the network layer.
+ *
+ * These mirror exactly what the server sends, including snake_case field names.
+ * Nothing in this file is exported from the SDK's public surface.
+ * Use the mapper functions in mappers.ts to convert these to core types.
+ */
+
+/** Raw emergency object as returned inside the emergency response envelope. */
+export interface ApiEmergency {
+  id: number;
+  uuid: string;
+  company_id: number;
+  title: string;
+  message: string;
+  background_color: string;
+  text_color: string;
+  target_scope: string;
+  is_active: boolean;
+  started_at: string;
+  ended_at?: string;
+}
+
+/** Top-level shape of the GET /screen/emergency response. */
+export interface ApiEmergencyResponse {
+  emergency: ApiEmergency | null;
+}
+
+/** Raw playlist item as returned by the API. */
+export interface ApiPlaylistItem {
+  uuid: string;
+  name: string;
+  type: string;
+  url: string;
+  duration_seconds: number;
+  width?: number;
+  height?: number;
+  transition?: string;
+  title?: string;
+  thumbnail?: string;
+}
+
+/**
+ * Raw playback strategy as returned by the API when a playlist is active.
+ * When no playlist is scheduled the API returns an empty array — use
+ * Array.isArray() to detect that case before treating this as a strategy.
+ */
+export interface ApiPlaybackStrategy {
+  loop: boolean;
+  shuffle: boolean;
+  preload_count?: number;
+}
+
+/** Raw schedule metadata attached to a playlist response. */
+export interface ApiSchedule {
+  uuid: string;
+  name: string;
+  priority: number;
+}
+
+/** Raw playlist container metadata attached to a playlist response. */
+export interface ApiPlaylistMeta {
+  uuid: string;
+  name: string;
+}
+
+/** Top-level shape of the GET /screen/now-playing response. */
+export interface ApiPlaylistResponse {
+  items: ApiPlaylistItem[];
+  /** Empty array when no playlist is scheduled — not a real strategy object. */
+  strategy: ApiPlaybackStrategy | [];
+  schedule?: ApiSchedule;
+  playlist?: ApiPlaylistMeta;
+}
+
+/** Top-level shape of the POST /screen/heartbeat response. */
+export interface ApiHeartbeatAck {
+  received: boolean;
+}
+
+/** Top-level shape of the POST /screen/heartbeat request. */
+export interface ApiHeartbeatPayload {
+  cpu_usage?: number;
+  memory_usage?: number;
+  disk_usage?: number;
+  temperature?: number;
+  os_version?: string;
+  app_version: string;
+}

package/src/network/mappers.ts

@@ -0,0 +1,106 @@
+import {
+  EmergencyAlert,
+  HeartbeatAck,
+  MediaType,
+  Playlist,
+  PlaylistItem,
+  PlaybackStrategy,
+  HeartbeatPayload,
+  TransitionType,
+} from "../core/types";
+import {
+  ApiEmergencyResponse,
+  ApiHeartbeatAck,
+  ApiHeartbeatPayload,
+  ApiPlaybackStrategy,
+  ApiPlaylistItem,
+  ApiPlaylistResponse,
+} from "./apiTypes";
+
+/** Maps a raw playlist item to the core PlaylistItem type. */
+export function mapPlaylistItem(raw: ApiPlaylistItem): PlaylistItem {
+  return {
+    uuid: raw.uuid,
+    name: raw.name,
+    type: raw.type as MediaType,
+    url: raw.url,
+    duration: raw.duration_seconds,
+    ...(raw.transition !== undefined && {
+      transition: raw.transition as TransitionType,
+    }),
+    ...(raw.width !== undefined && { width: raw.width }),
+    ...(raw.height !== undefined && { height: raw.height }),
+    ...(raw.title !== undefined && { title: raw.title }),
+    ...(raw.thumbnail !== undefined && { thumbnail: raw.thumbnail }),
+  };
+}
+
+/**
+ * Maps the raw strategy field to a PlaybackStrategy.
+ * Returns undefined when the API sends an empty array instead of a real object.
+ */
+export function mapPlaybackStrategy(
+  raw: ApiPlaybackStrategy | [],
+): PlaybackStrategy | undefined {
+  if (Array.isArray(raw)) return undefined;
+  return {
+    loop: raw.loop,
+    shuffle: raw.shuffle,
+    preloadCount: raw.preload_count ?? 0,
+  };
+}
+
+/** Maps a raw playlist response to the core Playlist type. */
+export function mapPlaylistResponse(raw: ApiPlaylistResponse): Playlist {
+  return {
+    uuid: raw.playlist!.uuid,
+    items: raw.items.map(mapPlaylistItem),
+    strategy: mapPlaybackStrategy(raw.strategy),
+    schedule: raw.schedule,
+    playlistMeta: raw.playlist,
+    cachedAt: Date.now(),
+  };
+}
+
+/**
+ * Maps a raw emergency response to an EmergencyAlert.
+ * Returns null when no emergency is active.
+ */
+export function mapEmergencyResponse(
+  raw: ApiEmergencyResponse,
+): EmergencyAlert | null {
+  if (raw.emergency === null) return null;
+  return {
+    id: raw.emergency.id,
+    uuid: raw.emergency.uuid,
+    companyId: raw.emergency.company_id,
+    title: raw.emergency.title,
+    message: raw.emergency.message,
+    backgroundColor: raw.emergency.background_color,
+    textColor: raw.emergency.text_color,
+    targetScope: raw.emergency.target_scope,
+    isActive: raw.emergency.is_active,
+    startedAt: raw.emergency.started_at,
+    ...(raw.emergency.ended_at !== undefined && {
+      endedAt: raw.emergency.ended_at,
+    }),
+  };
+}
+
+/** Maps a raw heartbeat acknowledgement to the core HeartbeatAck type. */
+export function mapHeartbeatAck(raw: ApiHeartbeatAck): HeartbeatAck {
+  return { received: raw.received };
+}
+
+export function mapHeartbeatPayload(
+  raw: HeartbeatPayload,
+): ApiHeartbeatPayload {
+  return {
+    cpu_usage: raw.cpuUsage,
+    memory_usage: raw.memoryUsage,
+    disk_usage: raw.diskUsage,
+    temperature: raw.temperature,
+    os_version: raw.osVersion,
+    app_version: raw.playerVersion,
+  };
+}

package/src/player/SquareScreenPlayer.ts

@@ -0,0 +1,414 @@
+import { SQUARESCREEN_API_BASE_URL } from "../constants";
+import { NetworkClient } from "../network/NetworkClient";
+import {
+  DeviceStatus,
+  EmergencyAlert,
+  NetworkDataSource,
+  PlaybackEvent,
+  Playlist,
+  PlaylistItem,
+  SquareScreenCacheProvider,
+} from "../core/types";
+import { SquareScreenCache } from "../cache/SquareScreenCache";
+
+const LAST_PLAYLIST_KEY = "square-screen:last-playlist-uuid";
+
+export interface SquareScreenPlayerConfig {
+  /** Unique identifier for this device. */
+  deviceId: string;
+  /** Secret token used to authenticate this device. Never log or expose this value. */
+  deviceToken: string;
+  /** SDK version string sent on every heartbeat. */
+  version: string;
+  /** How long a cached playlist is considered fresh, in ms. Defaults to 5 minutes. */
+  ttl?: number;
+  /** How often to poll the API for playlist updates, in ms. Defaults to 30 seconds. */
+  pollInterval?: number;
+  /** How often to poll the API for emergency alerts, in ms. Defaults to 15 seconds. */
+  emergencyPollInterval?: number;
+  /** How often to send a heartbeat to the API, in ms. Defaults to 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. Otherwise requests go to the production API
+   * URL defined by {@link SQUARESCREEN_API_BASE_URL}.
+   */
+  networkDataSource?: NetworkDataSource;
+  /**
+   * Override the cache layer with a custom implementation. When omitted the default
+   * `SquareScreenCache` (IndexedDB + Cache API) is used. Pass your own implementation
+   * to integrate with an existing media storage layer.
+   */
+  cacheProvider?: SquareScreenCacheProvider;
+}
+
+/** Typed detail payloads for each player event. */
+export type PlayerEventMap = {
+  /** Fires when the current playlist item changes. */
+  itemchange: CustomEvent<{ item: PlaylistItem; index: number; total: number }>;
+  /** Fires when the device connectivity/sync status changes. */
+  statuschange: CustomEvent<{ status: DeviceStatus }>;
+  /** Fires when an emergency alert becomes active or is cleared. */
+  emergencyalert: CustomEvent<{ alert: EmergencyAlert | null }>;
+  /** Fires whenever the playlist is refreshed from the network or cache. */
+  playlistupdate: CustomEvent<{ playlist: Playlist }>;
+};
+
+/**
+ * Headless, framework-agnostic player that manages playlist fetching, caching,
+ * item advancement, preloading, polling, and emergency alerts.
+ *
+ * Extends `EventTarget` — use `addEventListener` / `removeEventListener` to
+ * react to player events. No DOM or rendering logic lives here.
+ *
+ * @example
+ * const player = new SquareScreenPlayer({ deviceId, deviceToken, version: "1.0.0" });
+ * player.addEventListener("itemchange", ({ detail }) => render(detail.item));
+ * player.addEventListener("emergencyalert", ({ detail }) => showAlert(detail.alert));
+ * await player.start();
+ */
+export class SquareScreenPlayer extends EventTarget {
+  private readonly network: NetworkDataSource;
+  private readonly cache: SquareScreenCacheProvider;
+  private readonly config: Required<
+    Omit<SquareScreenPlayerConfig, "networkDataSource" | "cacheProvider">
+  >;
+
+  private playlist: Playlist | null = null;
+  private stopped = false;
+  private currentIndex = 0;
+  private status: DeviceStatus = "connecting";
+  private activeAlert: EmergencyAlert | null = null;
+  private currentItemStartTime: number | null = null;
+
+  private itemTimer: ReturnType<typeof setTimeout> | null = null;
+  private playlistPollTimer: ReturnType<typeof setInterval> | null = null;
+  private emergencyPollTimer: ReturnType<typeof setInterval> | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: SquareScreenPlayerConfig) {
+    super();
+
+    if (!config.networkDataSource) {
+      if (!config.deviceId) throw new Error("SquareScreenPlayer: deviceId is required.");
+      if (!config.deviceToken) throw new Error("SquareScreenPlayer: deviceToken is required.");
+    }
+
+    this.network =
+      config.networkDataSource ??
+      new NetworkClient(SQUARESCREEN_API_BASE_URL, config.deviceId, config.deviceToken);
+
+    this.cache = config.cacheProvider ?? new SquareScreenCache();
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- omit injected deps from persisted config snapshot
+    const { networkDataSource: _n, cacheProvider: _c, ...rest } = config;
+    this.config = {
+      ttl: 5 * 60 * 1000,
+      pollInterval: 30_000,
+      emergencyPollInterval: 15_000,
+      heartbeatInterval: 60_000,
+      ...rest,
+    };
+  }
+
+  /** The playlist item currently being displayed, or null if no playlist is loaded. */
+  get currentItem(): PlaylistItem | null {
+    return this.playlist?.items[this.currentIndex] ?? null;
+  }
+
+  /**
+   * Starts the player: fetches the playlist, begins playback, and starts polling
+   * and heartbeat intervals. Safe to await — resolves once the first playlist load
+   * attempt completes (whether from network or cache fallback).
+   */
+  async start(): Promise<void> {
+    this.stopped = false;
+    this.setStatus("connecting");
+    await this.loadPlaylist();
+    await this.checkEmergencyAlert();
+    this.startPolling();
+    this.startHeartbeat();
+  }
+
+  /** Stops all timers and clears internal state. Call this when tearing down the player. */
+  stop(): void {
+    if (this.itemTimer) clearTimeout(this.itemTimer);
+    if (this.playlistPollTimer) clearInterval(this.playlistPollTimer);
+    if (this.emergencyPollTimer) clearInterval(this.emergencyPollTimer);
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.itemTimer = null;
+    this.playlistPollTimer = null;
+    this.emergencyPollTimer = null;
+    this.heartbeatTimer = null;
+    // Prevent in-flight loadPlaylist/applyPlaylist/scheduleItem continuations
+    // from dispatching events or setting new timers after teardown.
+    this.stopped = true;
+    this.playlist = null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Playlist loading
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Network-first playlist load. On success the playlist is saved to cache and
+   * applied if the UUID changed. On failure the player falls back to the last
+   * known playlist UUID stored in `localStorage`, loading it from cache with
+   * `allowStale = true` so it is served even after its TTL has expired.
+   */
+  private async loadPlaylist(): Promise<void> {
+    const result = await this.network.fetchPlaylist();
+
+    if (result.success) {
+      this.setStatus("online");
+      const playlist = result.data;
+      localStorage.setItem(LAST_PLAYLIST_KEY, playlist.uuid);
+      await this.cache.savePlaylist(playlist, this.config.ttl);
+
+      const isNewPlaylist = !this.playlist || this.playlist.uuid !== playlist.uuid;
+      if (isNewPlaylist) {
+        await this.applyPlaylist(playlist);
+      } else {
+        this.dispatch("playlistupdate", { playlist });
+      }
+    } else {
+      this.setStatus("offline");
+      if (!this.playlist) {
+        const lastUuid = localStorage.getItem(LAST_PLAYLIST_KEY);
+        if (lastUuid) {
+          const cached = await this.cache.getPlaylist(lastUuid, true);
+          if (cached) await this.applyPlaylist(cached);
+        }
+      }
+    }
+  }
+
+  /**
+   * Activates a playlist: optionally shuffles the items, resets the index to 0,
+   * emits `playlistupdate`, and kicks off the first `scheduleItem` call.
+   * Bails out immediately if `stop()` has been called.
+   */
+  private async applyPlaylist(playlist: Playlist): Promise<void> {
+    if (this.stopped) return;
+    const items = playlist.strategy?.shuffle
+      ? [...playlist.items].sort(() => Math.random() - 0.5)
+      : playlist.items;
+
+    this.playlist = { ...playlist, items };
+    this.currentIndex = 0;
+    this.dispatch("playlistupdate", { playlist: this.playlist });
+    this.scheduleItem();
+  }
+
+  refreshPlaylist(): void {
+    this.loadPlaylist();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Playback
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Emits `itemchange` immediately with either the cached blob URL or the raw
+   * HTTPS URL, then arms the advancement timer. Never blocks on a network fetch —
+   * if the media isn't cached yet the browser loads it directly while
+   * `preloadNext` / `downloadInBackground` cache it for the next cycle.
+   *
+   * Guards against `stop()` being called while awaiting the cache lookup.
+   */
+  private async scheduleItem(): Promise<void> {
+    if (this.itemTimer) clearTimeout(this.itemTimer);
+
+    const item = this.currentItem;
+    if (!item || !this.playlist) return;
+
+    this.currentItemStartTime = Date.now();
+
+    // Cache lookup only — never fetch inline so the timer isn't delayed.
+    const url = (await this.cache.getMediaUrl(item.url)) ?? item.url;
+    if (!this.playlist) return; // stopped while awaiting
+
+    this.dispatch("itemchange", {
+      item: { ...item, url },
+      index: this.currentIndex,
+      total: this.playlist.items.length,
+    });
+
+    // If the current item wasn't in cache, download it now for the next cycle.
+    if (url === item.url) this.downloadInBackground(item.url);
+    this.preloadNext();
+    const elapsed = Date.now() - this.currentItemStartTime!;
+    const remaining = Math.max(0, item.duration * 1000 - elapsed);
+    this.itemTimer = setTimeout(() => this.advance(), remaining);
+  }
+
+  /**
+   * Schedules background downloads for upcoming items while the current one
+   * is playing, so subsequent transitions can serve blob URLs immediately.
+   *
+   * - `preloadCount: 0` — disabled; nothing is downloaded.
+   * - `preloadCount: N` — downloads the next N items ahead (wraps at end).
+   * - `preloadCount` absent — downloads all items in the playlist up front.
+   */
+  private preloadNext(): void {
+    if (!this.playlist) return;
+    const preloadCount = this.playlist.strategy?.preloadCount;
+    if (preloadCount === 0) return;
+    const count = preloadCount ?? this.playlist.items.length;
+
+    for (let i = 1; i <= count; i++) {
+      const idx = (this.currentIndex + i) % this.playlist.items.length;
+      this.downloadInBackground(this.playlist.items[idx].url);
+    }
+  }
+
+  /**
+   * Fire-and-forget download. Checks the cache first; if the media is already
+   * present the call is a no-op. Errors are silently swallowed — a failed
+   * download is not fatal; the raw URL will be used until the next successful download.
+   */
+  private downloadInBackground(url: string): void {
+    this.cache
+      .getMediaUrl(url)
+      .then((cached) => {
+        if (cached || !this.playlist) return;
+        return fetch(url, { mode: "cors" })
+          .then((r) => (r.ok ? r.blob() : Promise.reject(new Error(`HTTP ${r.status}`))))
+          .then((blob) => this.cache.saveMedia(url, blob));
+      })
+      .catch(() => {});
+  }
+
+  /**
+   * Moves to the next item. Reports the completed playback event, then either
+   * wraps back to index 0 (when `loop` is true or absent) or halts when
+   * `loop: false` and the last item has finished.
+   */
+  private advance(): void {
+    if (!this.playlist) return;
+    const total = this.playlist.items.length;
+    const next = this.currentIndex + 1;
+
+    this.reportPlaybackEvent();
+
+    if (next >= total) {
+      if (this.playlist.strategy?.loop ?? true) {
+        this.currentIndex = 0;
+      } else {
+        return;
+      }
+    } else {
+      this.currentIndex = next;
+    }
+
+    this.scheduleItem();
+  }
+
+  /** Sends a proof-of-play event to the server. Fire-and-forget; failures are not surfaced. */
+  private async reportPlaybackEvent(): Promise<void> {
+    if (!this.currentItemStartTime) return;
+    if (!this.currentItem || !this.playlist) return;
+    const endedAt = Date.now();
+    const event: PlaybackEvent = {
+      media_uuid: this.currentItem.uuid,
+      playlist_uuid: this.playlist.uuid,
+      schedule_uuid: this.playlist.schedule?.uuid ?? "",
+      started_at: new Date(this.currentItemStartTime).toISOString(),
+      ended_at: new Date(endedAt).toISOString(),
+      duration_seconds: Math.round((endedAt - this.currentItemStartTime) / 1000),
+      completed: true,
+    };
+    this.network.reportPlaybackEvent(event);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Polling and heartbeat
+  // ---------------------------------------------------------------------------
+
+  /** Arms the playlist-refresh and emergency-alert polling intervals. */
+  private startPolling(): void {
+    this.playlistPollTimer = setInterval(
+      () => this.loadPlaylist(),
+      this.config.pollInterval,
+    );
+    this.emergencyPollTimer = setInterval(
+      () => this.checkEmergencyAlert(),
+      this.config.emergencyPollInterval,
+    );
+  }
+
+  /** Arms the periodic heartbeat that keeps the device registration alive. */
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(async () => {
+      await this.network.healthCheck({ playerVersion: this.config.version });
+    }, this.config.heartbeatInterval);
+  }
+
+  /**
+   * Polls the server for an active emergency alert. Emits `emergencyalert` only
+   * when the state actually changes (alert activated, cleared, or replaced by a
+   * different UUID) to avoid redundant re-renders on the consumer side.
+   */
+  private async checkEmergencyAlert(): Promise<void> {
+    const result = await this.network.checkForEmergencyAlert();
+    if (!result.success) return;
+
+    const incoming = result.data;
+    const wasActive = this.activeAlert !== null;
+    const isActive = incoming !== null;
+    const alertChanged = isActive && incoming!.uuid !== this.activeAlert?.uuid;
+
+    if (wasActive !== isActive || alertChanged) {
+      this.activeAlert = incoming;
+      this.dispatch("emergencyalert", { alert: incoming });
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  private setStatus(status: DeviceStatus): void {
+    if (this.status === status) return;
+    this.status = status;
+    this.dispatch("statuschange", { status });
+  }
+
+  private dispatch<K extends keyof PlayerEventMap>(
+    type: K,
+    detail: PlayerEventMap[K] extends CustomEvent<infer D> ? D : never,
+  ): void {
+    this.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+
+  addEventListener<K extends keyof PlayerEventMap>(
+    type: K,
+    listener: (event: PlayerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  addEventListener(type: string, listener: any, options?: any): void {
+    super.addEventListener(type, listener, options);
+  }
+
+  removeEventListener<K extends keyof PlayerEventMap>(
+    type: K,
+    listener: (event: PlayerEventMap[K]) => void,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  removeEventListener(type: string, listener: any, options?: any): void {
+    super.removeEventListener(type, listener, options);
+  }
+}