@glivion/square-screen-js-sdk 0.1.0 → 1.0.1

package/src/network/apiTypes.ts

@@ -1,89 +0,0 @@
-/**
- * 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

@@ -1,106 +0,0 @@
-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

@@ -1,414 +0,0 @@
-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);
-  }
-}