@applicaster/zapp-react-native-utils 16.0.0-rc.121 → 16.0.0-rc.123

package/appUtils/playerManager/__tests__/playerDiagnostics.test.ts

@@ -0,0 +1,62 @@
+import { Player } from "../player";
+
+const entry = (id: string) => ({ id, title: id }) as unknown as ZappEntry;
+
+const makePlayer = () => {
+  const player = new Player({ playerId: "test-player" });
+  player.entry = entry("first");
+
+  return player;
+};
+
+describe("Player per-entry diagnostics", () => {
+  it("keeps the latest of onError and onVideoError, and clears it when a new entry loads", () => {
+    const player = makePlayer();
+    const second = { message: "second" };
+
+    player.onError({ message: "first" } as any);
+    player.onVideoError(second as any);
+
+    expect(player.lastError).toBe(second);
+
+    player.entry = entry("second");
+
+    expect(player.lastError).toBeNull();
+  });
+
+  it("reads the next entry without creating the overlay observer", () => {
+    const player = makePlayer();
+
+    expect(player.getPlayNextEntry()).toBeNull();
+
+    jest
+      .spyOn(player.getOverlayObservable(), "getPlayNextEntry")
+      .mockReturnValue(entry("next"));
+
+    expect(player.getPlayNextEntry()).toEqual(entry("next"));
+  });
+
+  it("keeps the content clock while a client-side ad plays", () => {
+    const player = makePlayer();
+
+    player.onVideoProgress({
+      currentTime: 300,
+      duration: 1800,
+      seekableDuration: 1800,
+    });
+
+    player.onAdBegin({});
+
+    player.onVideoProgress({
+      currentTime: 5,
+      duration: 15,
+      seekableDuration: 15,
+    });
+
+    expect(player.getPosition()).toBe(5);
+    expect(player.getDuration()).toBe(15);
+    expect(player.getContentPosition()).toBe(300);
+    expect(player.getContentDuration()).toBe(1800);
+    expect(player.getSeekableDuration()).toBe(1800);
+  });
+});

package/appUtils/playerManager/__tests__/playerToolbox.test.ts

@@ -18,6 +18,9 @@ const loadToolbox = () => {
 const player = (overrides = {}) => ({
   getSeekableDuration: () => 100,
   getContentPosition: () => 40,
+  isLive: () => false,
+  getPlayNextEntry: () => null,
+  playNextHandler: jest.fn(),
   seekTo: jest.fn(),
   ...overrides,
 });
@@ -30,7 +33,7 @@ const registeredTools = async (active) => {
   mockXray = { registerReactToolbox: mockRegister };
   await loadToolbox().registerPlayerToolbox(manager(active));
 
-  const { tools } = mockRegister.mock.calls[0][0];
+  const { tools } = mockRegister.mock.lastCall[0];
 
   return Object.fromEntries(tools.map((tool) => [tool.name, tool.handler]));
 };
@@ -87,6 +90,187 @@ describe("playerToolbox", () => {
     );
   });
 
+  describe("state", () => {
+    const playing = (overrides = {}, entry: any = { id: "e1", title: "T" }) =>
+      player({
+        playerId: "p1",
+        playerRole: "Primary",
+        getEntry: () => entry,
+        getPosition: () => 40,
+        getDuration: () => 100,
+        getContentDuration: () => 100,
+        isReadyToPlay: () => true,
+        isPlaying: () => true,
+        isBuffering: () => false,
+        isAd: () => false,
+        isLive: () => false,
+        getIsMuted: () => false,
+        ...overrides,
+      });
+
+    const state = async (overrides = {}, entry?: any) =>
+      (await registeredTools(playing(overrides, entry))).state();
+
+    it("reports inactive when nothing plays", async () => {
+      expect((await registeredTools(null)).state()).toEqual({
+        active: false,
+        casting: false,
+      });
+    });
+
+    it("keeps the existing fields and adds the content clock for a VOD", async () => {
+      expect(await state()).toEqual({
+        active: true,
+        playerId: "p1",
+        entry: { id: "e1", title: "T" },
+        position: 40,
+        duration: 100,
+        playing: true,
+        buffering: false,
+        readyToPlay: true,
+        ad: false,
+        live: false,
+        muted: false,
+        role: "Primary",
+        plugin: null,
+        engine: null,
+        casting: false,
+        seekableDuration: 100,
+        contentPosition: 40,
+        contentDuration: 100,
+        drm: null,
+        lastError: null,
+        next: null,
+      });
+    });
+
+    it("reports the content's clock next to the ad's during a client-side ad", async () => {
+      const result = await state({
+        isAd: () => true,
+        getPosition: () => 5,
+        getDuration: () => 15,
+        getContentPosition: () => 300,
+        getContentDuration: () => 1800,
+      });
+
+      expect(result).toMatchObject({
+        ad: true,
+        position: 5,
+        duration: 15,
+        contentPosition: 300,
+        contentDuration: 1800,
+      });
+    });
+
+    it("reports non-finite numbers as null", async () => {
+      expect(
+        await state({
+          getSeekableDuration: () => NaN,
+          getContentPosition: () => null,
+          getContentDuration: () => Infinity,
+        })
+      ).toMatchObject({
+        seekableDuration: null,
+        contentPosition: null,
+        contentDuration: null,
+      });
+    });
+
+    it("reports the player plugin and its web engine", async () => {
+      expect(
+        await state({
+          playerPluginId: "QuickBrickPlayerPlugin",
+          engine: "hls.js",
+        })
+      ).toMatchObject({ plugin: "QuickBrickPlayerPlugin", engine: "hls.js" });
+    });
+
+    it("lists the entry's DRM key systems, or null", async () => {
+      const drm = { widevine: { license_url: "w" }, playready: {} };
+
+      expect((await state({}, { id: "e", extensions: { drm } })).drm).toEqual([
+        "widevine",
+        "playready",
+      ]);
+
+      expect((await state({}, { id: "e", extensions: { drm: {} } })).drm).toBe(
+        null
+      );
+
+      expect((await state({}, { id: "e", extensions: {} })).drm).toBe(null);
+      expect((await state({}, null)).drm).toBe(null);
+    });
+
+    it("reports no last error as null", async () => {
+      expect((await state({ lastError: null })).lastError).toBeNull();
+    });
+  });
+
+  describe("play next", () => {
+    const nextEntry = { id: "n1", title: "Next", extensions: {} };
+
+    const stateWith = async (overrides) =>
+      (
+        await registeredTools(
+          player({
+            getEntry: () => null,
+            getPosition: () => 0,
+            getDuration: () => 0,
+            getContentDuration: () => 0,
+            isReadyToPlay: () => true,
+            isPlaying: () => true,
+            isBuffering: () => false,
+            isAd: () => false,
+            getIsMuted: () => false,
+            ...overrides,
+          })
+        )
+      ).state();
+
+    it("reports the entry Play Next would play", async () => {
+      expect(
+        (await stateWith({ getPlayNextEntry: () => nextEntry })).next
+      ).toEqual({ id: "n1", title: "Next" });
+    });
+
+    it("reports no next entry as null", async () => {
+      expect((await stateWith({})).next).toBeNull();
+    });
+
+    it("plays the next entry through the player's Play Next action", async () => {
+      const active = player({ getPlayNextEntry: () => nextEntry });
+      const tools = await registeredTools(active);
+
+      expect(tools.next()).toEqual({ id: "n1", title: "Next" });
+      expect(active.playNextHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it("fails without a next entry", async () => {
+      const active = player();
+      const tools = await registeredTools(active);
+
+      expect(() => tools.next()).toThrow("No next item");
+      expect(active.playNextHandler).not.toHaveBeenCalled();
+    });
+
+    it("fails when no Play Next action is registered", async () => {
+      const tools = await registeredTools(
+        player({
+          getPlayNextEntry: () => nextEntry,
+          playNextHandler: null,
+        })
+      );
+
+      expect(() => tools.next()).toThrow("No next item");
+    });
+
+    it("fails without an active player", async () => {
+      const tools = await registeredTools(null);
+
+      expect(() => tools.next()).toThrow("No active player");
+    });
+  });
+
   it("refuses to seek a stream that is not seekable", async () => {
     const tools = await registeredTools(
       player({ getSeekableDuration: () => 0 })

package/appUtils/playerManager/player.ts

@@ -76,6 +76,12 @@ export class Player {
   private overlaysObserver?: OverlaysObserver | null;
   private entryObservable?: BehaviorSubject<ZappEntry> | null;
   private contentSubject?: BehaviorSubject<PlayerContent> | null;
+  // Read by the X-Ray `player` toolbox: the last onError/onVideoError of the current entry,
+  // and the Play Next action of the PlayerContainer showing this player.
+  public lastError: unknown = null;
+  public playNextHandler: (() => void) | null = null;
+  // The web engine the default player picked (hls.js, dash.js, shaka, video.js); null elsewhere.
+  public engine: string | null = null;
 
   protected listeners: {
     [key: string]: QuickBrickPlayer.SharedPlayerCallBacks;
@@ -89,6 +95,7 @@ export class Player {
 
   set entry(newEntry: ZappEntry | null) {
     this._entry = newEntry;
+    this.lastError = null;
     // The live entry is scoped to the entry it overlays - see
     // `OverlaysObserver.clearLiveEntry`. No-op when there is no observer,
     // which is every non-live player.
@@ -271,6 +278,10 @@ export class Player {
 
   getEntry = (): ZappEntry | null => this.entry;
 
+  /** The entry Play Next would play now; null without one. Never creates the overlay observer. */
+  getPlayNextEntry = (): ZappEntry | null =>
+    this.overlaysObserver?.getPlayNextEntry() ?? null;
+
   logState = (text, additionalParams = {}) => {
     const isSeeking = this.playerState.seekPosition !== null;
 
@@ -492,6 +503,8 @@ export class Player {
   };
 
   onVideoError = (error: Error) => {
+    this.lastError = error;
+
     this.invokeListenersUpdate({
       callbackName: SharedPlayerCallBacksKeys.OnVideoError,
       event: error,
@@ -499,6 +512,8 @@ export class Player {
   };
 
   onError = (error: Error) => {
+    this.lastError = error;
+
     this.invokeListenersUpdate({
       callbackName: SharedPlayerCallBacksKeys.OnError,
       event: error,

package/appUtils/playerManager/playerToolbox.ts

@@ -14,6 +14,12 @@ const toNumber = (value: unknown) =>
 
 const clamp = (value: number, max: number) => Math.min(Math.max(value, 0), max);
 
+/** Key systems the entry declares (widevine, playready, fairplay...). */
+const drmKeySystems = (drm: unknown) =>
+  drm && typeof drm === "object" && Object.keys(drm).length
+    ? Object.keys(drm)
+    : null;
+
 /** The range a seek can reach: the DVR window on live, the content on VOD. */
 const requireSeekable = (player: {
   getSeekableDuration: () => number | undefined;
@@ -38,14 +44,21 @@ const tools = (manager: PlayerManager): XrayToolSpec[] => {
     {
       name: "state",
       description:
-        "The active player: entry, position and duration in seconds, playing/buffering/ad/live/muted, " +
-        "role (Primary, Cell, Chromecast) and casting. active: false when nothing plays.",
+        "The active player: entry, position and duration in seconds (the ad's while an ad plays), " +
+        "playing/buffering/ad/live/muted, role (Primary, Cell, Chromecast) and casting; in seconds, " +
+        "seekableDuration and contentPosition/contentDuration (the content's, even during ads); " +
+        "drm key systems, lastError {message} and next {id, title}, each null when absent; " +
+        "plugin (player plugin id) and engine (the default player's web engine, else null). " +
+        "active: false when nothing plays.",
       handler: () => {
         const player = manager.getActivePlayer();
 
         if (!player) return { active: false, casting: manager.isCasting() };
 
         const entry = player.getEntry();
+        const seekableDuration = toNumber(player.getSeekableDuration());
+        const next = player.getPlayNextEntry();
+        const error: any = player.lastError;
 
         return {
           active: true,
@@ -61,7 +74,18 @@ const tools = (manager: PlayerManager): XrayToolSpec[] => {
           live: !!player.isLive(),
           muted: !!player.getIsMuted(),
           role: player.playerRole,
+          plugin: player.playerPluginId ?? null,
+          engine: player.engine ?? null,
           casting: manager.isCasting(),
+          seekableDuration,
+          contentPosition: toNumber(player.getContentPosition()),
+          contentDuration: toNumber(player.getContentDuration()),
+          drm: drmKeySystems(entry?.extensions?.drm),
+          lastError:
+            error == null
+              ? null
+              : { message: String(error?.message ?? error?.error ?? error) },
+          next: next ? { id: next.id, title: next.title } : null,
         };
       },
     },
@@ -83,6 +107,21 @@ const tools = (manager: PlayerManager): XrayToolSpec[] => {
         return "OK";
       },
     },
+    {
+      name: "next",
+      description:
+        "Play the next item, as the Play Next overlay does. Fails when there is none.",
+      handler: () => {
+        const player = requirePlayer();
+        const next = player.getPlayNextEntry();
+
+        if (!next || !player.playNextHandler) throw new Error("No next item");
+
+        player.playNextHandler();
+
+        return { id: next.id, title: next.title };
+      },
+    },
     {
       name: "seek",
       description:

package/manifestUtils/keys.js

@@ -484,7 +484,7 @@ const MOBILE_ACTION_BUTTON_FIELDS = [
       { text: "share", value: "native_share_action" },
       { text: "downloads", value: "offline-content-button" },
       { text: "trailer", value: "trailer_action" },
-      { text: "mute/unmute", value: "mute_unmute" },
+      { text: "mute/unmute", value: "mute_unmute_action" },
     ],
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-rc.121",
+  "version": "16.0.0-rc.123",
   "description": "Applicaster Zapp React Native utilities package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,7 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-rc.121",
+    "@applicaster/applicaster-types": "16.0.0-rc.123",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",
@@ -36,6 +36,7 @@
     "prop-types": "^15.0.0"
   },
   "peerDependencies": {
+    "@applicaster/quick-brick-assets": "*",
     "@applicaster/zapp-pipes-v2-client": "*",
     "@react-native-community/netinfo": "*",
     "react": "*",

package/quickBrickAssets/__tests__/index.test.ts

@@ -0,0 +1,18 @@
+// The Jest stand-in for @applicaster/quick-brick-assets maps each existing key to itself
+import { getQuickBrickAsset } from "..";
+
+describe("getQuickBrickAsset", () => {
+  it("returns the asset for a plugin identifier and path", () => {
+    expect(
+      getQuickBrickAsset("mute_unmute_action", "action/flavour_1/mute.png")
+    ).toBe("mute_unmute_action/action/flavour_1/mute.png");
+  });
+
+  it("rejects unknown paths and plugin identifiers at compile time", () => {
+    // @ts-expect-error - no such file in mute_unmute_action
+    getQuickBrickAsset("mute_unmute_action", "action/flavour_9/mute.png");
+
+    // @ts-expect-error - no assets folder for this plugin
+    getQuickBrickAsset("unknown_plugin", "action/flavour_1/mute.png");
+  });
+});

package/quickBrickAssets/index.ts

@@ -0,0 +1,35 @@
+import assets from "@applicaster/quick-brick-assets";
+import type {
+  QuickBrickAssetKey,
+  QuickBrickAssetSource,
+} from "@applicaster/quick-brick-assets";
+
+export type { QuickBrickAssetKey, QuickBrickAssetSource };
+
+type PluginOf<K> = K extends `${infer Plugin}/${string}` ? Plugin : never;
+
+type PathOf<K, Plugin extends string> = K extends `${Plugin}/${infer Path}`
+  ? Path
+  : never;
+
+/** Plugin identifiers that have a folder in `@applicaster/quick-brick-assets`. */
+export type QuickBrickAssetPlugin = PluginOf<QuickBrickAssetKey>;
+
+/** Asset paths inside the given plugin's folder. */
+export type QuickBrickAssetPath<Plugin extends QuickBrickAssetPlugin> = PathOf<
+  QuickBrickAssetKey,
+  Plugin
+>;
+
+/**
+ * Looks up an asset of `@applicaster/quick-brick-assets` by plugin identifier
+ * and path relative to the plugin folder, e.g.
+ * `getQuickBrickAsset("mute_unmute_action", "action/flavour_1/mute.png")`.
+ * Both arguments are checked against the package's files at compile time.
+ * Density variants (`@2x` / `@3x`) are not supported.
+ */
+export const getQuickBrickAsset = <Plugin extends QuickBrickAssetPlugin>(
+  pluginIdentifier: Plugin,
+  assetPath: QuickBrickAssetPath<Plugin>
+): QuickBrickAssetSource =>
+  assets[`${pluginIdentifier}/${assetPath}` as QuickBrickAssetKey];

package/reactHooks/actions/index.ts

@@ -21,17 +21,45 @@ type ActionContexts<T = unknown> = {
 };
 
 /**
- * React Hook to subscribe to the custom action context
+ * A value that changes whenever a provider is added to or removed from
+ * `uiActionsRegistry`.
+ *
+ * Providers can register after the UI that wants them has rendered - the audio
+ * player registers playback speed only once its controller has state, and
+ * plugin-backed actions are bridged in from an effect. Put this in the
+ * dependency list of anything that resolves actions, so the list is re-read
+ * instead of being frozen at first paint.
+ */
+export function useRegistryRevision(): number {
+  const [revision, setRevision] = useState(0);
+
+  useEffect(
+    () =>
+      uiActionsRegistry.subscribe(() => setRevision((current) => current + 1)),
+    []
+  );
+
+  return revision;
+}
+
+/**
+ * Resolves a legacy action context or falls back to the UI action registry.
  * @param {*} plugId - subscribes to the context of that action plugin
  * @return {*} - global action provider context or context for specific action plugin
  */
 export function useActions<T = unknown>(plugId: string): any {
   const [logged, setLogged] = useState(false);
   const context = useContext<ActionContexts<T>>(ActionsContext);
+  useRegistryRevision();
+
   const actionContext = context?.actions?.[plugId]?.module?.context;
 
   if (plugId) {
     if (!actionContext) {
+      const registeredAction = uiActionsRegistry.getAction(plugId);
+
+      if (registeredAction) return registeredAction;
+
       if (!logged) {
         logger.warning({
           message: `useActions: Couldn't find an action for ${plugId} plugin`,
@@ -139,25 +167,3 @@ export function useEntryActionState(
 
   return { state, invokeAction };
 }
-
-/**
- * A value that changes whenever a provider is added to or removed from
- * `uiActionsRegistry`.
- *
- * Providers can register after the UI that wants them has rendered - the audio
- * player registers playback speed only once its controller has state, and
- * plugin-backed actions are bridged in from an effect. Put this in the
- * dependency list of anything that resolves actions, so the list is re-read
- * instead of being frozen at first paint.
- */
-export function useRegistryRevision(): number {
-  const [revision, setRevision] = useState(0);
-
-  useEffect(
-    () =>
-      uiActionsRegistry.subscribe(() => setRevision((current) => current + 1)),
-    []
-  );
-
-  return revision;
-}