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

package/dist/index.d.mts

@@ -0,0 +1,522 @@
+//#region src/constants.d.ts
+/**
+ * Production root URL for the SquareScreen REST API.
+ *
+ * {@link SquareScreenPlayer} uses this for all network requests. Integrators cannot
+ * override it via player configuration; supply a custom {@link NetworkDataSource}
+ * only if you must talk to a different host (e.g. tests or a private gateway).
+ */
+declare const SQUARESCREEN_API_BASE_URL = "https://square-screen-api-development-f7zuxa.laravel.cloud/api/v1";
+//#endregion
+//#region src/core/types.d.ts
+/** The type of media content in a playlist item. Matches the string values returned by the API. */
+type MediaType = "image" | "video";
+/** The transition animation to apply when moving between playlist items. */
+type TransitionType = "fade" | "slide" | "none";
+/** The current connectivity and sync state of the device. */
+type DeviceStatus = "connecting" | "online" | "offline" | "syncing";
+/** Playback strategy metadata returned alongside a playlist. */
+interface PlaybackStrategy {
+  loop: boolean;
+  shuffle: boolean;
+  /** Number of upcoming items to pre-download. 0 means no preloading. */
+  preloadCount?: number;
+}
+/** Schedule metadata associated with a playlist. */
+interface Schedule {
+  uuid: string;
+  name: string;
+  /** Higher value means higher priority when multiple schedules overlap. */
+  priority: number;
+}
+/** Metadata about the playlist container returned by the API. */
+interface PlaylistMeta {
+  uuid: string;
+  name: string;
+}
+/** A playlist returned from the API, representing everything the device should display. */
+interface Playlist {
+  uuid: string;
+  items: PlaylistItem[];
+  /** Present when the backend includes scheduling/playback hints. Not always populated. */
+  strategy?: PlaybackStrategy;
+  /** Metadata about the active schedule driving this playlist. */
+  schedule?: Schedule;
+  /** Metadata about the playlist container itself. */
+  playlistMeta?: PlaylistMeta;
+  /** Unix timestamp (ms) recording when this playlist was stored in the local cache. */
+  cachedAt: number;
+}
+/** A single piece of content within a playlist. */
+interface PlaylistItem {
+  uuid: string;
+  name: string;
+  type: MediaType;
+  /** URL of the media file to display. */
+  url: string;
+  /** How long to display this item, in seconds. */
+  duration: number;
+  /** Animation to use when transitioning away from this item. Defaults to none if absent. */
+  transition?: TransitionType;
+  /** Native width of the media in pixels. */
+  width?: number;
+  /** Native height of the media in pixels. */
+  height?: number;
+  /** Human-readable title. Present on some item types (e.g. video). */
+  title?: string;
+  /** Thumbnail URL for preloading previews. */
+  thumbnail?: string;
+}
+/** An active emergency broadcast targeting this device. */
+interface EmergencyAlert {
+  /** Server-assigned integer ID. */
+  id: number;
+  uuid: string;
+  /** ID of the company that issued the broadcast. */
+  companyId: number;
+  title: string;
+  message: string;
+  /** Hex color string for the alert background, e.g. "#FF0000". */
+  backgroundColor: string;
+  /** Hex color string for the alert text, e.g. "#FFFFFF". */
+  textColor: string;
+  /** The scope this broadcast targets, e.g. "all", "workspace", "group", or "device". */
+  targetScope: string;
+  /** Whether this broadcast is currently active. */
+  isActive: boolean;
+  /** ISO 8601 timestamp when the broadcast started. */
+  startedAt: string;
+  /** ISO 8601 timestamp when the broadcast ended, or undefined if still active. */
+  endedAt?: string;
+}
+/**
+ * Device health metrics sent to the server on each heartbeat.
+ * All hardware metrics are optional — not all browsers expose them.
+ */
+interface HeartbeatPayload {
+  cpuUsage?: number;
+  memoryUsage?: number;
+  diskUsage?: number;
+  temperature?: number;
+  osVersion?: string;
+  /** The version string of this SDK, included on every heartbeat. */
+  playerVersion: string;
+}
+/** Acknowledgement returned by the server after a successful heartbeat POST. */
+interface HeartbeatAck {
+  received: boolean;
+}
+/** Query parameters for filtering a playlist to video items only. */
+interface VideoPlaylistParams {
+  category?: string;
+  tags?: string[];
+  quality?: string;
+  limit?: number;
+}
+/** Query parameters for filtering a playlist to image items only. */
+interface ImagePlaylistParams {
+  category?: string;
+  tags?: string[];
+  limit?: number;
+}
+/** Playback event data sent to the server. */
+interface PlaybackEvent {
+  media_uuid: string;
+  playlist_uuid: string;
+  schedule_uuid: string;
+  started_at: string;
+  ended_at: string;
+  /** Actual number of seconds the item was displayed. */
+  duration_seconds: number;
+  /** Whether the item played to its full duration without interruption. */
+  completed: boolean;
+}
+/** An HTTP-level failure — the request reached the server but returned an error status. */
+interface NetworkError {
+  kind: "network";
+  code: number;
+  message: string;
+}
+/** The device credentials (ID or token) were rejected by the server. */
+interface AuthError {
+  kind: "auth";
+  message: string;
+}
+/** Reading from or writing to the local cache failed. */
+interface CacheError {
+  kind: "cache";
+  message: string;
+}
+/** The server response could not be parsed into the expected shape. */
+interface ParseError {
+  kind: "parse";
+  message: string;
+}
+/**
+ * Signals that an emergency broadcast is active.
+ * The caller should switch to displaying the EmergencyAlert instead of normal content.
+ */
+interface EmergencyOverrideActive {
+  kind: "emergency_override";
+}
+/**
+ * Every error the SDK can produce.
+ * Check the `kind` field to identify and handle each case.
+ */
+type SquareScreenError = NetworkError | AuthError | CacheError | ParseError | EmergencyOverrideActive;
+/**
+ * The return type for all SDK operations that can fail.
+ *
+ * Check `result.success` first — TypeScript will then narrow the type
+ * so that `result.data` is only accessible on success and `result.error`
+ * is only accessible on failure.
+ *
+ * @example
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error.kind);
+ * }
+ */
+type SquareScreenResult<T> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  error: SquareScreenError;
+};
+interface NetworkDataSource {
+  fetchPlaylist: () => Promise<SquareScreenResult<Playlist>>;
+  fetchVideoPlaylist: (params: VideoPlaylistParams) => Promise<SquareScreenResult<Playlist>>;
+  fetchImagePlaylist: (params: ImagePlaylistParams) => Promise<SquareScreenResult<Playlist>>;
+  /** Resolves to null when no emergency is active. */
+  checkForEmergencyAlert: () => Promise<SquareScreenResult<EmergencyAlert | null>>;
+  healthCheck: (payload: HeartbeatPayload) => Promise<SquareScreenResult<HeartbeatAck>>;
+  reportPlaybackEvent: (event: PlaybackEvent) => Promise<SquareScreenResult<{
+    recorded: boolean;
+  }>>;
+}
+/**
+ * Abstraction over local storage. The default implementation is `SquareScreenCache`
+ * (IndexedDB for playlist metadata + Cache API for media blobs). Pass a custom
+ * implementation via `SquareScreenPlayerConfig.cacheProvider` to integrate with
+ * an existing storage layer.
+ */
+interface SquareScreenCacheProvider {
+  /** Returns the cached playlist, or null if not found / TTL expired. Pass `allowStale` to bypass TTL for offline fallback. */
+  getPlaylist(uuid: string, allowStale?: boolean): Promise<Playlist | null>;
+  /** Persists a playlist. `ttlMs` controls how long it is considered fresh. */
+  savePlaylist(playlist: Playlist, ttlMs: number): Promise<void>;
+  /** Returns a blob URL for the cached media, or null if not yet downloaded. */
+  getMediaUrl(url: string): Promise<string | null>;
+  /** Downloads and stores the media blob, returns a blob URL for immediate use. */
+  saveMedia(url: string, blob: Blob): Promise<string>;
+  /** Wipes all cached data (playlist metadata and media blobs). */
+  clear(): Promise<void>;
+}
+//#endregion
+//#region src/player/SquareScreenPlayer.d.ts
+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. */
+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();
+ */
+declare class SquareScreenPlayer extends EventTarget {
+  private readonly network;
+  private readonly cache;
+  private readonly config;
+  private playlist;
+  private stopped;
+  private currentIndex;
+  private status;
+  private activeAlert;
+  private currentItemStartTime;
+  private itemTimer;
+  private playlistPollTimer;
+  private emergencyPollTimer;
+  private heartbeatTimer;
+  constructor(config: SquareScreenPlayerConfig);
+  /** The playlist item currently being displayed, or null if no playlist is loaded. */
+  get currentItem(): PlaylistItem | 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).
+   */
+  start(): Promise<void>;
+  /** Stops all timers and clears internal state. Call this when tearing down the player. */
+  stop(): void;
+  /**
+   * 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 loadPlaylist;
+  /**
+   * 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 applyPlaylist;
+  refreshPlaylist(): void;
+  /**
+   * 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 scheduleItem;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  /** Sends a proof-of-play event to the server. Fire-and-forget; failures are not surfaced. */
+  private reportPlaybackEvent;
+  /** Arms the playlist-refresh and emergency-alert polling intervals. */
+  private startPolling;
+  /** Arms the periodic heartbeat that keeps the device registration alive. */
+  private startHeartbeat;
+  /**
+   * 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 checkEmergencyAlert;
+  private setStatus;
+  private dispatch;
+  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;
+  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;
+}
+//#endregion
+//#region src/renderer/SquareScreenRenderer.d.ts
+interface SquareScreenRendererConfig {
+  /** Transition to use when an item doesn't specify one. Defaults to `"none"`. */
+  defaultTransition?: TransitionType;
+  /** Duration of transition animations in ms. Defaults to `500`. */
+  transitionDuration?: number;
+  /**
+   * Maximum ms to wait for a video to reach `canplay` before transitioning anyway.
+   * Keeps transitions on-time when media loads from a slow network.
+   * Defaults to `3000`. Set to `0` to transition immediately without waiting.
+   */
+  canPlayTimeout?: number;
+}
+/**
+ * Optional vanilla JS renderer that wires a {@link SquareScreenPlayer} to a DOM container.
+ * Handles `<img>` / `<video>` element lifecycle, autoplay, transitions, and emergency alerts.
+ *
+ * When an emergency alert is active it renders a full-screen overlay on top of all content.
+ * Normal playback resumes automatically once the alert is cleared.
+ *
+ * @example
+ * const player = new SquareScreenPlayer({ ... });
+ * const renderer = new SquareScreenRenderer(document.getElementById("screen"), player);
+ * renderer.mount();
+ * await player.start();
+ *
+ * // Tear down
+ * player.stop();
+ * renderer.unmount();
+ */
+declare class SquareScreenRenderer {
+  private readonly container;
+  private readonly player;
+  private readonly config;
+  private wrapper;
+  /** Two slots that alternate as current/next during transitions. */
+  private slots;
+  private activeSlot;
+  private alertOverlay;
+  private readonly onItemChange;
+  private readonly onEmergencyAlert;
+  constructor(container: HTMLElement, player: SquareScreenPlayer, config?: SquareScreenRendererConfig);
+  /** Injects the renderer DOM into the container and begins listening to the player. */
+  mount(): void;
+  /** Removes the renderer DOM and stops listening to the player. */
+  unmount(): void;
+  private buildDOM;
+  private createSlot;
+  private handleItemChange;
+  private handleEmergencyAlert;
+  private createImage;
+  private createVideo;
+  private waitForCanPlay;
+  private applyTransition;
+  private wait;
+}
+//#endregion
+//#region src/cache/SquareScreenCache.d.ts
+/**
+ * Default {@link SquareScreenCacheProvider} backed by IndexedDB (playlist metadata)
+ * and the Cache API (media blobs).
+ *
+ * **IndexedDB** — a single `playlists` object store holds one document per
+ * playlist UUID. A private `_ttl` field (milliseconds) is stored alongside the
+ * record and stripped before returning data to callers.
+ *
+ * **Cache API** — media files are stored under their original URL as the cache
+ * key, matching the same URL-keyed approach used by the Android SDK's
+ * `MediaFileCache`. 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 to avoid redundant allocations. All handles are revoked
+ * when {@link clear} is called.
+ *
+ * Integrators who need different storage behaviour (a service-worker cache,
+ * an in-memory store for tests, a custom database) should implement
+ * {@link SquareScreenCacheProvider} and pass it via
+ * `SquareScreenPlayerConfig.cacheProvider`.
+ */
+declare class SquareScreenCache implements SquareScreenCacheProvider {
+  private readonly dbName;
+  private readonly cacheName;
+  /** Tracks the blob URL created for each media URL so it is reused across calls. */
+  private readonly objectUrls;
+  /**
+   * @param dbName    Name of the IndexedDB database. Override in tests to isolate state.
+   * @param cacheName Name of the Cache API bucket. Override in tests to isolate state.
+   */
+  constructor({
+    dbName,
+    cacheName
+  }?: {
+    dbName?: string;
+    cacheName?: string;
+  });
+  /** Opens (or lazily creates) the IndexedDB database with the `playlists` object store. */
+  private openDB;
+  /**
+   * Returns the cached playlist for the given UUID, or `null` if:
+   * - nothing has been stored for that UUID, or
+   * - the record's age exceeds its TTL and `allowStale` is `false`.
+   *
+   * @param uuid       The playlist UUID to look up.
+   * @param allowStale When `true`, expired records are returned as-is (useful
+   *                   for serving a fallback when the network is unreachable).
+   */
+  getPlaylist(uuid: string, allowStale?: boolean): Promise<Playlist | null>;
+  /**
+   * Persists a playlist to IndexedDB, overwriting any previous record with the
+   * same UUID. `cachedAt` is set to the current wall-clock time so that TTL
+   * checks in {@link getPlaylist} have an accurate baseline.
+   *
+   * @param playlist The playlist to store. Items are persisted inline as part
+   *                 of the same document — no separate per-item records.
+   * @param ttlMs    How long (in milliseconds) the record is considered fresh.
+   *                 Passed through `SquareScreenPlayerConfig.ttl` by the player.
+   */
+  savePlaylist(playlist: Playlist, ttlMs: number): Promise<void>;
+  /**
+   * Returns a blob URL for the locally cached copy of `url`, or `null` if the
+   * media has not been downloaded yet.
+   *
+   * The blob URL is created once and stored in an in-memory map. Subsequent
+   * calls for the same `url` return the same handle without re-reading the
+   * Cache API, which avoids both I/O and unnecessary `URL.createObjectURL`
+   * allocations on long-running signage devices.
+   *
+   * @param url The original remote URL used as the Cache API key.
+   */
+  getMediaUrl(url: string): Promise<string | null>;
+  /**
+   * Stores `blob` in the Cache API under `url` and returns a blob URL for
+   * immediate use by the renderer.
+   *
+   * Called by the player after a successful `fetch()` so that subsequent
+   * {@link getMediaUrl} calls for the same URL skip the network entirely.
+   *
+   * @param url  The original remote URL — used as the Cache API key so that
+   *             {@link getMediaUrl} can retrieve the entry with a simple `match`.
+   * @param blob The downloaded media blob to persist.
+   * @returns    A blob URL that the renderer can set as `src` on an
+   *             `<img>` or `<video>` element.
+   */
+  saveMedia(url: string, blob: Blob): Promise<string>;
+  /**
+   * Wipes all cached data:
+   * - Revokes every outstanding blob URL to release the underlying Blob references.
+   * - Deletes the IndexedDB database entirely (recreated on next access).
+   * - Removes all entries from the Cache API bucket.
+   *
+   * Useful for a "factory reset" flow or in tests to guarantee a clean slate.
+   */
+  clear(): Promise<void>;
+}
+//#endregion
+export { type AuthError, type CacheError, type DeviceStatus, type EmergencyAlert, type EmergencyOverrideActive, type HeartbeatAck, type HeartbeatPayload, type ImagePlaylistParams, type MediaType, type NetworkDataSource, type NetworkError, type ParseError, type PlaybackEvent, type PlaybackStrategy, type PlayerEventMap, type Playlist, type PlaylistItem, type PlaylistMeta, SQUARESCREEN_API_BASE_URL, type Schedule, SquareScreenCache, type SquareScreenCacheProvider, type SquareScreenError, SquareScreenPlayer, type SquareScreenPlayerConfig, SquareScreenRenderer, type SquareScreenRendererConfig, type SquareScreenResult, type TransitionType, type VideoPlaylistParams };
+//# sourceMappingURL=index.d.mts.map