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

package/src/cache/SquareScreenCache.ts

@@ -1,154 +0,0 @@
-import { openDB, deleteDB } from "idb";
-import { Playlist, SquareScreenCacheProvider } from "../core/types";
-
-const DEFAULT_DB_NAME = "square-screen-cache";
-const DEFAULT_CACHE_NAME = "square-screen-cache";
-
-/**
- * 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`.
- */
-export class SquareScreenCache implements SquareScreenCacheProvider {
-  private readonly dbName: string;
-  private readonly cacheName: string;
-  /** Tracks the blob URL created for each media URL so it is reused across calls. */
-  private readonly objectUrls = new Map<string, string>();
-
-  /**
-   * @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 = DEFAULT_DB_NAME,
-    cacheName = DEFAULT_CACHE_NAME,
-  }: { dbName?: string; cacheName?: string } = {}) {
-    this.dbName = dbName;
-    this.cacheName = cacheName;
-  }
-
-  /** Opens (or lazily creates) the IndexedDB database with the `playlists` object store. */
-  private openDB() {
-    return openDB(this.dbName, 1, {
-      upgrade(db) {
-        if (!db.objectStoreNames.contains("playlists")) {
-          db.createObjectStore("playlists", { keyPath: "uuid" });
-        }
-      },
-    });
-  }
-
-  /**
-   * 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).
-   */
-  async getPlaylist(uuid: string, allowStale = false): Promise<Playlist | null> {
-    const db = await this.openDB();
-    const record = await db.get("playlists", uuid);
-    if (!record) return null;
-    if (!allowStale && Date.now() - record.cachedAt > record._ttl) return null;
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- strip cache metadata before return
-    const { _ttl, ...playlist } = record;
-    return playlist as Playlist;
-  }
-
-  /**
-   * 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.
-   */
-  async savePlaylist(playlist: Playlist, ttlMs: number): Promise<void> {
-    const db = await this.openDB();
-    await db.put("playlists", { ...playlist, cachedAt: Date.now(), _ttl: ttlMs });
-  }
-
-  /**
-   * 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.
-   */
-  async getMediaUrl(url: string): Promise<string | null> {
-    const existing = this.objectUrls.get(url);
-    if (existing) return existing;
-
-    const cache = await caches.open(this.cacheName);
-    const response = await cache.match(url);
-    if (!response) return null;
-
-    const blob = await response.blob();
-    const objectUrl = URL.createObjectURL(blob);
-    this.objectUrls.set(url, objectUrl);
-    return objectUrl;
-  }
-
-  /**
-   * 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.
-   */
-  async saveMedia(url: string, blob: Blob): Promise<string> {
-    const cache = await caches.open(this.cacheName);
-    await cache.put(url, new Response(blob));
-    const objectUrl = URL.createObjectURL(blob);
-    this.objectUrls.set(url, objectUrl);
-    return objectUrl;
-  }
-
-  /**
-   * 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.
-   */
-  async clear(): Promise<void> {
-    for (const url of this.objectUrls.values()) URL.revokeObjectURL(url);
-    this.objectUrls.clear();
-    const db = await this.openDB();
-    db.close();
-    await deleteDB(this.dbName);
-    const cache = await caches.open(this.cacheName);
-    const keys = await cache.keys();
-    await Promise.all(keys.map((req) => cache.delete(req)));
-  }
-}

package/src/constants.ts

@@ -1,9 +0,0 @@
-/**
- * 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).
- */
-export const SQUARESCREEN_API_BASE_URL =
-  "https://square-screen-api-development-f7zuxa.laravel.cloud/api/v1";

package/src/core/types.ts

@@ -1,251 +0,0 @@
-/** The type of media content in a playlist item. Matches the string values returned by the API. */
-export type MediaType = "image" | "video";
-
-/** The transition animation to apply when moving between playlist items. */
-export type TransitionType = "fade" | "slide" | "none";
-
-/** The current connectivity and sync state of the device. */
-export type DeviceStatus = "connecting" | "online" | "offline" | "syncing";
-
-/** Playback strategy metadata returned alongside a playlist. */
-export 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. */
-export 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. */
-export interface PlaylistMeta {
-  uuid: string;
-  name: string;
-}
-
-/** A playlist returned from the API, representing everything the device should display. */
-export 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. */
-export 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. */
-export 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.
- */
-export 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. */
-export interface HeartbeatAck {
-  received: boolean;
-}
-
-/** Query parameters for filtering a playlist to video items only. */
-export interface VideoPlaylistParams {
-  category?: string;
-  tags?: string[];
-  quality?: string;
-  limit?: number;
-}
-
-/** Query parameters for filtering a playlist to image items only. */
-export interface ImagePlaylistParams {
-  category?: string;
-  tags?: string[];
-  limit?: number;
-}
-
-/** Playback event data sent to the server. */
-export 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;
-}
-// ---------------------------------------------------------------------------
-// Error types
-// ---------------------------------------------------------------------------
-
-/** An HTTP-level failure — the request reached the server but returned an error status. */
-export interface NetworkError {
-  kind: "network";
-  code: number;
-  message: string;
-}
-
-/** The device credentials (ID or token) were rejected by the server. */
-export interface AuthError {
-  kind: "auth";
-  message: string;
-}
-
-/** Reading from or writing to the local cache failed. */
-export interface CacheError {
-  kind: "cache";
-  message: string;
-}
-
-/** The server response could not be parsed into the expected shape. */
-export 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.
- */
-export interface EmergencyOverrideActive {
-  kind: "emergency_override";
-}
-
-/**
- * Every error the SDK can produce.
- * Check the `kind` field to identify and handle each case.
- */
-export type SquareScreenError =
-  | NetworkError
-  | AuthError
-  | CacheError
-  | ParseError
-  | EmergencyOverrideActive;
-
-// ---------------------------------------------------------------------------
-// Result type
-// ---------------------------------------------------------------------------
-
-/**
- * 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);
- * }
- */
-export type SquareScreenResult<T> =
-  | { success: true; data: T }
-  | { success: false; error: SquareScreenError };
-
-// ---------------------------------------------------------------------------
-// Network interface
-// ---------------------------------------------------------------------------
-
-export 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 }>>;
-}
-
-// ---------------------------------------------------------------------------
-// Cache interface
-// ---------------------------------------------------------------------------
-
-/**
- * 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.
- */
-export 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>;
-}

package/src/env.d.ts

@@ -1,4 +0,0 @@
-declare module "*?raw" {
-  const content: string;
-  export default content;
-}

package/src/index.ts

@@ -1,34 +0,0 @@
-export { SQUARESCREEN_API_BASE_URL } from "./constants";
-export { SquareScreenPlayer } from "./player/SquareScreenPlayer";
-export type { SquareScreenPlayerConfig, PlayerEventMap } from "./player/SquareScreenPlayer";
-
-export { SquareScreenRenderer } from "./renderer/SquareScreenRenderer";
-export type { SquareScreenRendererConfig } from "./renderer/SquareScreenRenderer";
-
-export { SquareScreenCache } from "./cache/SquareScreenCache";
-
-export type {
-  Playlist,
-  PlaylistItem,
-  PlaybackStrategy,
-  Schedule,
-  PlaylistMeta,
-  MediaType,
-  TransitionType,
-  DeviceStatus,
-  EmergencyAlert,
-  HeartbeatPayload,
-  HeartbeatAck,
-  SquareScreenError,
-  SquareScreenResult,
-  NetworkError,
-  AuthError,
-  CacheError,
-  ParseError,
-  EmergencyOverrideActive,
-  NetworkDataSource,
-  SquareScreenCacheProvider,
-  VideoPlaylistParams,
-  ImagePlaylistParams,
-  PlaybackEvent,
-} from "./core/types";

package/src/network/NetworkClient.ts

@@ -1,234 +0,0 @@
-import {
-  EmergencyAlert,
-  HeartbeatAck,
-  HeartbeatPayload,
-  ImagePlaylistParams,
-  NetworkDataSource,
-  PlaybackEvent,
-  Playlist,
-  SquareScreenResult,
-  VideoPlaylistParams,
-} from "../core/types";
-import {
-  ApiEmergencyResponse,
-  ApiHeartbeatAck,
-  ApiPlaylistResponse,
-} from "./apiTypes";
-import {
-  mapEmergencyResponse,
-  mapHeartbeatAck,
-  mapPlaylistResponse,
-  mapHeartbeatPayload,
-} from "./mappers";
-
-/**
- * Handles all HTTP communication with the SquareScreen API.
- *
- * Implements {@link NetworkDataSource} and is the only class in the SDK
- * that calls `fetch` directly. Auth headers are injected automatically on
- * every request — callers never set them manually.
- *
- * This class is internal to the SDK. Consumers interact with it only through
- * the `NetworkDataSource` interface via the player module.
- */
-export class NetworkClient implements NetworkDataSource {
-  private readonly baseUrl: string;
-  private readonly deviceId: string;
-  private readonly deviceToken: string;
-
-  /**
-   * @param baseUrl     - Root URL of the SquareScreen API, e.g. `"https://api.squarescreen.io/api/v1"`.
-   * @param deviceId    - Unique identifier for this device.
-   * @param deviceToken - Secret token used to authenticate this device. Never log or expose this value.
-   */
-  constructor(baseUrl: string, deviceId: string, deviceToken: string) {
-    this.baseUrl = baseUrl;
-    this.deviceId = deviceId;
-    this.deviceToken = deviceToken;
-  }
-
-  /**
-   * Central fetch wrapper used by all public methods.
-   *
-   * Injects auth headers, separates HTTP errors from network failures,
-   * and isolates JSON parse errors — so callers always receive a
-   * {@link SquareScreenResult} and never an uncaught exception.
-   *
-   * Error mapping:
-   * - 401/403 → `AuthError`
-   * - Other non-2xx → `NetworkError`
-   * - JSON parse failure → `ParseError`
-   * - `fetch` throw (no internet, CORS, timeout) → `NetworkError` with code `0`
-   */
-  private async fetchWrapper<T>(
-    endpoint: string,
-    options: RequestInit,
-  ): Promise<SquareScreenResult<T>> {
-    try {
-      const response = await fetch(`${this.baseUrl}${endpoint}`, {
-        ...options,
-        headers: {
-          ...(options?.headers ?? {}),
-          "Content-Type": "application/json",
-          "X-Device-Id": this.deviceId,
-          "X-Device-Token": this.deviceToken,
-        },
-      });
-
-      if (!response.ok) {
-        if (response.status === 401) {
-          return {
-            success: false,
-            error: {
-              kind: "auth",
-              message: "Unauthorized",
-            },
-          };
-        }
-        if (response.status === 403) {
-          return {
-            success: false,
-            error: {
-              kind: "auth",
-              message: "Forbidden",
-            },
-          };
-        }
-        return {
-          success: false,
-          error: {
-            kind: "network",
-            code: response.status,
-            message: response.statusText || `HTTP error ${response.status}`,
-          },
-        };
-      }
-
-      try {
-        const data = (await response.json()) as T;
-        return { success: true, data };
-      } catch {
-        return {
-          success: false,
-          error: {
-            kind: "parse",
-            message: "Response could not be parsed as JSON",
-          },
-        };
-      }
-    } catch (err) {
-      return {
-        success: false,
-        error: {
-          kind: "network",
-          code: 0,
-          message:
-            err instanceof Error ? err.message : "Network request failed",
-        },
-      };
-    }
-  }
-
-  /** Fetches the full active playlist for this device. */
-  async fetchPlaylist(): Promise<SquareScreenResult<Playlist>> {
-    const result = await this.fetchWrapper<ApiPlaylistResponse>(
-      "/screen/now-playing",
-      { method: "GET" },
-    );
-    if (!result.success) return result;
-    return { success: true, data: mapPlaylistResponse(result.data) };
-  }
-
-  /** Fetches a playlist filtered to video items only. */
-  async fetchVideoPlaylist(
-    params: VideoPlaylistParams,
-  ): Promise<SquareScreenResult<Playlist>> {
-    const query = new URLSearchParams({
-      type: "video",
-      ...(params.category && { category: params.category }),
-      ...(params.quality && { quality: params.quality }),
-      ...(params.limit && { limit: String(params.limit) }),
-      ...(params.tags && { tags: params.tags.join(",") }),
-    });
-    const result = await this.fetchWrapper<ApiPlaylistResponse>(
-      `/screen/now-playing?${query}`,
-      { method: "GET" },
-    );
-    if (!result.success) return result;
-    return { success: true, data: mapPlaylistResponse(result.data) };
-  }
-
-  /** Fetches a playlist filtered to image items only. */
-  async fetchImagePlaylist(
-    params: ImagePlaylistParams,
-  ): Promise<SquareScreenResult<Playlist>> {
-    const query = new URLSearchParams({
-      type: "image",
-      ...(params.category && { category: params.category }),
-      ...(params.limit && { limit: String(params.limit) }),
-      ...(params.tags && { tags: params.tags.join(",") }),
-    });
-    const result = await this.fetchWrapper<ApiPlaylistResponse>(
-      `/screen/now-playing?${query}`,
-      { method: "GET" },
-    );
-    if (!result.success) return result;
-    return { success: true, data: mapPlaylistResponse(result.data) };
-  }
-
-  /**
-   * Checks whether an emergency broadcast is currently active for this device.
-   * Resolves to `null` when no emergency is active.
-   */
-  async checkForEmergencyAlert(): Promise<
-    SquareScreenResult<EmergencyAlert | null>
-  > {
-    const result = await this.fetchWrapper<ApiEmergencyResponse>(
-      "/screen/emergency",
-      { method: "GET" },
-    );
-    if (!result.success) return result;
-    return { success: true, data: mapEmergencyResponse(result.data) };
-  }
-
-  /**
-   * Posts device health metrics to the server.
-   * The payload is mapped to snake_case before sending to match the API's expected format.
-   *
-   * @param payload - Collected device metrics. Hardware fields are optional;
-   *                  `playerVersion` is always required.
-   */
-  async healthCheck(
-    payload: HeartbeatPayload,
-  ): Promise<SquareScreenResult<HeartbeatAck>> {
-    const result = await this.fetchWrapper<ApiHeartbeatAck>(
-      "/screen/heartbeat",
-      { method: "POST", body: JSON.stringify(mapHeartbeatPayload(payload)) },
-    );
-    if (!result.success) return result;
-    return { success: true, data: mapHeartbeatAck(result.data) };
-  }
-
-  /** Reports a playback event to the server.
-   * @param event - The playback event to report.
-   * @returns A result indicating whether the event was recorded successfully.
-   * @example
-   * const result = await networkClient.reportPlaybackEvent({
-   *   media_uuid: "mf-00000001-0000-0000-0000-000000000001",
-   *   playlist_uuid: "pl-00000001-0000-0000-0000-000000000001",
-   *   schedule_uuid: "sc-00000001-0000-0000-0000-000000000001",
-   *   started_at: "2026-04-28T07:05:00Z",
-   *   ended_at: "2026-04-28T07:05:10Z",
-   * });
-   */
-  async reportPlaybackEvent(
-    event: PlaybackEvent,
-  ): Promise<SquareScreenResult<{ recorded: boolean }>> {
-    const result = await this.fetchWrapper<{ recorded: boolean }>(
-      "/screen/playback",
-      { method: "POST", body: JSON.stringify(event) },
-    );
-    if (!result.success) return result;
-    return { success: true, data: { recorded: result.data.recorded } };
-  }
-}