@applicaster/zapp-react-native-utils 16.0.0-rc.12 → 16.0.0-rc.120

package/appUtils/playerManager/playerToolbox.ts

@@ -0,0 +1,157 @@
+import { registerXrayToolbox, XrayToolSpec } from "../../logger/xrayToolbox";
+import type { PlayerManager } from "./index";
+
+/**
+ * X-Ray `player.*` toolbox: lets an agent read and drive the active player without screenshots.
+ * Registered by the PlayerManager singleton itself, so it exists wherever players do. Skipped
+ * when the installed X-Ray plugin has no React toolbox API.
+ *
+ * How the player is shown (video modal mode, mini player) is navigation state: see `nav.*`.
+ */
+
+const toNumber = (value: unknown) =>
+  typeof value === "number" && Number.isFinite(value) ? value : null;
+
+const clamp = (value: number, max: number) => Math.min(Math.max(value, 0), max);
+
+/** The range a seek can reach: the DVR window on live, the content on VOD. */
+const requireSeekable = (player: {
+  getSeekableDuration: () => number | undefined;
+}) => {
+  const seekable = toNumber(player.getSeekableDuration());
+
+  if (!seekable) throw new Error("Seek is not supported");
+
+  return seekable;
+};
+
+const tools = (manager: PlayerManager): XrayToolSpec[] => {
+  const requirePlayer = () => {
+    const player = manager.getActivePlayer();
+
+    if (!player) throw new Error("No active player");
+
+    return player;
+  };
+
+  return [
+    {
+      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.",
+      handler: () => {
+        const player = manager.getActivePlayer();
+
+        if (!player) return { active: false, casting: manager.isCasting() };
+
+        const entry = player.getEntry();
+
+        return {
+          active: true,
+          playerId: player.playerId,
+          entry: entry ? { id: entry.id, title: entry.title } : null,
+          position: toNumber(player.getPosition()),
+          duration: toNumber(player.getDuration()),
+          // isPlaying() only means "not paused", which is also true before the stream starts.
+          playing: !!player.isReadyToPlay() && player.isPlaying(),
+          buffering: !!player.isBuffering(),
+          readyToPlay: !!player.isReadyToPlay(),
+          ad: player.isAd(),
+          live: !!player.isLive(),
+          muted: !!player.getIsMuted(),
+          role: player.playerRole,
+          casting: manager.isCasting(),
+        };
+      },
+    },
+    {
+      name: "play",
+      description: "Resume the active player.",
+      handler: () => {
+        requirePlayer().play();
+
+        return "OK";
+      },
+    },
+    {
+      name: "pause",
+      description: "Pause the active player.",
+      handler: () => {
+        requirePlayer().pause();
+
+        return "OK";
+      },
+    },
+    {
+      name: "seek",
+      description:
+        "Seek to an absolute position, as the player's console command does: seconds from the start, " +
+        "or from the end when negative. Clamped to the seekable range. Where it lands can differ: " +
+        "server-side ads snap back to the break before the target; read player.state afterwards.",
+      parameters: [
+        {
+          name: "position",
+          type: "number",
+          description:
+            "Seconds from the start; negative values count back from the end.",
+        },
+      ],
+      handler: ({ position }) => {
+        const player = requirePlayer();
+        const seconds = toNumber(position);
+
+        if (seconds === null) {
+          throw new Error("'position' must be a number of seconds");
+        }
+
+        const seekable = requireSeekable(player);
+
+        const target =
+          seconds >= 0
+            ? Math.min(seconds, seekable)
+            : clamp(seekable + seconds, seekable);
+
+        player.seekTo(target);
+
+        return { position: target };
+      },
+    },
+    {
+      name: "offset",
+      description:
+        "Seek relative to the current position, as the player's console command does: positive " +
+        "forward, negative back. Clamped to the seekable range.",
+      parameters: [
+        {
+          name: "seconds",
+          type: "number",
+          description: "Seconds to move: positive forward, negative back.",
+        },
+      ],
+      handler: ({ seconds }) => {
+        const player = requirePlayer();
+        const delta = toNumber(seconds);
+
+        if (delta === null) throw new Error("'seconds' must be a number");
+
+        if (delta === 0) throw new Error("Ignored zero relative seek");
+
+        const seekable = requireSeekable(player);
+        const from = toNumber(player.getContentPosition()) ?? 0;
+        const target = clamp(from + delta, seekable);
+
+        player.seekTo(target);
+
+        return { from, position: target };
+      },
+    },
+  ];
+};
+
+export const registerPlayerToolbox = (manager: PlayerManager) =>
+  registerXrayToolbox({
+    name: "player",
+    description: "Inspect and control the active player.",
+    tools: tools(manager),
+  });

package/appUtils/playerManager/usePlayerContent.tsx

@@ -0,0 +1,43 @@
+import * as React from "react";
+import { Player, PlayerContent } from "./player";
+import { usePlayer } from "./usePlayer";
+
+const EMPTY_CONTENT: PlayerContent = {
+  title: null,
+  summary: null,
+  imageUrl: null,
+};
+
+/**
+ * Subscribes to the player's resolved Title/Subtitle, the same way
+ * `usePlayerState` subscribes to playback state. Modeled on that hook
+ * deliberately: one React bridge pattern for everything the manager publishes.
+ *
+ * Passing no `playerId` uses the active player, which is the right default -
+ * only one player instance is live at a time. `usePlayer` additionally swaps
+ * to the casting receiver while casting, so this follows cast handover
+ * automatically.
+ */
+export const usePlayerContent = (playerId?: string): PlayerContent => {
+  const player: Player = usePlayer(playerId);
+
+  const [content, setContent] = React.useState<PlayerContent>(
+    () => player?.getContent() ?? EMPTY_CONTENT
+  );
+
+  React.useEffect(() => {
+    if (!player) {
+      setContent(EMPTY_CONTENT);
+
+      return;
+    }
+
+    const subscription = player
+      .getContentObservable()
+      .subscribe((next) => setContent(next));
+
+    return () => subscription.unsubscribe();
+  }, [player]);
+
+  return content;
+};

package/appUtils/playerManager/usePlayerControllerSetup.tsx

@@ -3,11 +3,12 @@ import { useConfiguration } from "../../reactHooks/useConfiguration";
 import { useEffect } from "react";
 import { playerManager } from "./index";
 import { useValidatePlayerConfig } from "../../playerUtils/useValidatePlayerConfig";
-import { PlayerRole } from "./conts";
+import { PlayerRole } from "./const";
 import { isAppleTV } from "@applicaster/zapp-react-native-ui-components/Helpers/Platform";
 import { TVSeekController } from "../../reactHooks/player/TVSeekControlller/TVSeekController";
 import { KeyInputHandler } from "../keyInputHandler/KeyInputHandler";
 import { isTV } from "../../reactUtils";
+import { PlayerAnalyticsManager } from "../../analyticsUtils/PlayerAnalyticsManager";
 
 // TODO: Rename to ControllerType
 export const usePlayerControllerSetup = ({
@@ -68,6 +69,11 @@ export const usePlayerControllerSetup = ({
       return;
     }
 
+    // The analytics manager attaches its listener when a player registers, so it
+    // must exist first; on web the Player wrapper that also creates it renders
+    // only after the lazily loaded engine chunk, i.e. after registration.
+    PlayerAnalyticsManager.getInstance();
+
     playerManager.registerPlayer({
       id: playerId,
       playerController,

package/appUtils/playerManager/userLanguagePreference.ts

@@ -1,7 +1,7 @@
 import { localStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/LocalStorage";
 import { sessionStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage";
 import { createLogger, utilsLogger } from "../../logger";
-import { userPreferencesNamespace } from "./conts";
+import { userPreferencesNamespace } from "./const";
 
 export const preferredAudioLanguageStorageKey = "preferred_audio_language";
 

package/arrayUtils/__tests__/{anyThruthy.test.ts → anyTruthy.test.ts}

@@ -21,4 +21,12 @@ describe("anyTruthy", () => {
     expect(anyTruthy([true])).toBe(true);
     expect(anyTruthy([false])).toBe(false);
   });
+
+  it("should return true when the first value is true", () => {
+    expect(anyTruthy([true, false, false])).toBe(true);
+  });
+
+  it("should return true when only the last value is true", () => {
+    expect(anyTruthy([false, false, true])).toBe(true);
+  });
 });

package/arrayUtils/__tests__/arrayUtils.test.ts

@@ -28,6 +28,30 @@ describe("shiftArray", () => {
     expect(shiftArray(negativeOffset, array)).toMatchSnapshot();
     expect(shiftArray(2 * negativeOffset, array)).toMatchSnapshot();
   });
+
+  it("returns a new array and does not mutate the original", () => {
+    const original = ["a", "b", "c"];
+    const result = shiftArray(1, original);
+
+    expect(result).toEqual(["b", "c", "a"]);
+    expect(result).not.toBe(original);
+    expect(original).toEqual(["a", "b", "c"]);
+  });
+
+  it("returns an empty array when shifting an empty array", () => {
+    expect(shiftArray(1, [])).toEqual([]);
+    expect(shiftArray(-1, [])).toEqual([]);
+  });
+
+  it("returns the same order for a single-element array", () => {
+    expect(shiftArray(1, [1])).toEqual([1]);
+    expect(shiftArray(-1, [1])).toEqual([1]);
+  });
+
+  it("handles an offset equal to the array length", () => {
+    expect(shiftArray(4, array)).toEqual(array);
+    expect(shiftArray(-4, array)).toEqual(array);
+  });
 });
 
 describe("removeItemFromList", () => {
@@ -58,6 +82,38 @@ describe("removeItemFromList", () => {
       arrayOfObjects
     );
   });
+
+  it("returns the same reference when the item is not found", () => {
+    const list = [1, 2, 3];
+
+    expect(removeItemFromList(4, list)).toBe(list);
+  });
+
+  it("returns a new array when the item is removed", () => {
+    const list = [1, 2, 3];
+    const result = removeItemFromList(2, list);
+
+    expect(result).toEqual([1, 3]);
+    expect(result).not.toBe(list);
+    expect(list).toEqual([1, 2, 3]);
+  });
+
+  it("removes only the first occurrence of a duplicate item", () => {
+    expect(removeItemFromList(2, [1, 2, 2, 3])).toEqual([1, 2, 3]);
+  });
+
+  it("removes the first and last items", () => {
+    expect(removeItemFromList(1, [1, 2, 3])).toEqual([2, 3]);
+    expect(removeItemFromList(3, [1, 2, 3])).toEqual([1, 2]);
+  });
+
+  it("returns an empty list when removing from an empty list", () => {
+    expect(removeItemFromList(1, [])).toEqual([]);
+  });
+
+  it("returns an empty list when removing the only item", () => {
+    expect(removeItemFromList(1, [1])).toEqual([]);
+  });
 });
 
 describe("mapPromises", () => {
@@ -84,145 +140,146 @@ describe("mapPromises", () => {
     values.forEach((value) => {
       expect(promiseFn).toHaveBeenNthCalledWith(value, value, value - 1);
     });
-  });
 
-  describe("removeItemFromList", () => {
-    it("removes an item from a list", () => {
-      const arrayOfPrimitives = [1, 2, 3, 4];
-      expect(removeItemFromList(1, arrayOfPrimitives)).toEqual([2, 3, 4]);
+    expect.assertions(values.length + 1);
+  });
 
-      const arrayOfObjects = [
-        { prop: "value1" },
-        { prop: "value2" },
-        { prop: "value3" },
-      ];
+  it("resolves to an empty array for an empty input", async () => {
+    await expect(mapPromises(promiseFn, [])).resolves.toEqual([]);
+    expect(promiseFn).not.toHaveBeenCalled();
+  });
 
-      expect(removeItemFromList({ prop: "value2" }, arrayOfObjects)).toEqual([
-        { prop: "value1" },
-        { prop: "value3" },
-      ]);
-    });
+  it("rejects when any promise rejects", async () => {
+    const failingFn = jest.fn((num) =>
+      num === 2 ? Promise.reject(new Error("fail")) : Promise.resolve(num)
+    );
 
-    it("leaves the list as is if the item is not found", () => {
-      const arrayOfObjects = [
-        { prop: "value1" },
-        { prop: "value2" },
-        { prop: "value3" },
-      ];
+    await expect(mapPromises(failingFn, [1, 2, 3])).rejects.toThrow("fail");
+  });
+});
 
-      expect(removeItemFromList({ prop: "value4" }, arrayOfObjects)).toEqual(
-        arrayOfObjects
-      );
+describe("reducePromises", () => {
+  const promiseFn = jest.fn((current, previous, index, cb) => {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        resolve(previous + current);
+        cb?.(index);
+      }, 1);
     });
   });
 
-  describe("mapPromises", () => {
-    const promiseFn = jest.fn((num) => Promise.resolve(num + 1));
+  beforeEach(() => {
+    promiseFn.mockClear();
+  });
 
-    beforeEach(() => {
-      promiseFn.mockClear();
-    });
+  it("is a curried function; and returns the reduced promise values", async () => {
+    const promiseReducer = reducePromises(promiseFn);
 
-    it("is a curried function, and returns an array of resolved values", async () => {
-      const promiseMapper = mapPromises(promiseFn);
-      const values = [1, 2, 3];
+    const initialValue = 0;
+    const values = [1, 2, 3];
+    const sumOfValues = initialValue + values.reduce((a, b) => a + b, 0);
 
-      expect(typeof promiseMapper).toBe("function");
-      await expect(promiseMapper(values)).resolves.toEqual([2, 3, 4]);
-    });
+    expect(typeof promiseReducer).toBe("function");
 
-    it("calls all the promises immediately", () => {
-      const values = [1, 2, 3];
+    await expect(promiseReducer(initialValue, values)).resolves.toEqual(
+      sumOfValues
+    );
+  });
 
-      mapPromises(promiseFn, values);
-      expect(promiseFn).toHaveBeenCalledTimes(values.length);
+  it("calls promises one after the other", (done) => {
+    const values = [1, 2, 3];
+    const previousValues = [0, 1, 3];
+
+    reducePromises(
+      (current, previous, index) =>
+        promiseFn(current, previous, index, (index) => {
+          expect(promiseFn).toHaveBeenCalledTimes(index + 1);
+
+          expect(promiseFn).toHaveBeenNthCalledWith(
+            index + 1,
+            values[index],
+            previousValues[index],
+            index,
+            expect.any(Function)
+          );
+
+          if (index === 2) done();
+        }),
+      0,
+      values
+    );
 
-      values.forEach((value) => {
-        expect(promiseFn).toHaveBeenNthCalledWith(value, value, value - 1);
-      });
+    expect.assertions(values.length * 2);
+  });
 
-      expect.assertions(values.length + 1);
-    });
+  it("returns the initial value for an empty list", async () => {
+    await expect(reducePromises(promiseFn, 10, [])).resolves.toBe(10);
+    expect(promiseFn).not.toHaveBeenCalled();
   });
 
-  describe("reduce promises", () => {
-    const promiseFn = jest.fn((current, previous, index, cb) => {
-      return new Promise((resolve) => {
-        setTimeout(() => {
-          resolve(previous + current);
-          cb?.(index);
-        }, 1);
-      });
-    });
+  it("reduces a single-element list", async () => {
+    await expect(reducePromises(promiseFn, 5, [2])).resolves.toBe(7);
+  });
 
-    beforeEach(() => {
-      promiseFn.mockClear();
+  it("rejects when a promise rejects", async () => {
+    const failingFn = jest.fn(async (current, previous) => {
+      if (current === 2) throw new Error("reduce fail");
+
+      return previous + current;
     });
 
-    it("is a curried function; and returns the reduced promise values", async () => {
-      const promiseReducer = reducePromises(promiseFn);
+    await expect(reducePromises(failingFn, 0, [1, 2, 3])).rejects.toThrow(
+      "reduce fail"
+    );
+  });
+});
+
+describe("mapAndSplit", () => {
+  it("maps over a list of values and split it in chunks", () => {
+    const values = new Array(20).fill(0).map((_, i) => i);
+
+    const alphabet = Array.from(Array(26)).map((_, i) =>
+      String.fromCharCode(i + 65)
+    );
 
-      const initialValue = 0;
-      const values = [1, 2, 3];
-      const sumOfValues = initialValue + values.reduce((a, b) => a + b, 0);
+    const getLetterForInt = (num) => alphabet[num];
+    const chunkSize = 5;
 
-      expect(typeof promiseReducer).toBe("function");
+    const result = mapAndSplit<number, string>(
+      getLetterForInt,
+      chunkSize
+    )(values);
 
-      await expect(promiseReducer(initialValue, values)).resolves.toEqual(
-        sumOfValues
-      );
-    });
+    expect(result.length).toBe(values.length / chunkSize);
 
-    it("calls promises one after the other", (done) => {
-      const values = [1, 2, 3];
-      const previousValues = [0, 1, 3];
-
-      reducePromises(
-        (current, previous, index) =>
-          promiseFn(current, previous, index, (index) => {
-            expect(promiseFn).toHaveBeenCalledTimes(index + 1);
-
-            expect(promiseFn).toHaveBeenNthCalledWith(
-              index + 1,
-              values[index],
-              previousValues[index],
-              index,
-              expect.any(Function)
-            );
-
-            if (index === 2) done();
-          }),
-        0,
-        values
-      );
-
-      expect.assertions(values.length * 2);
+    result.forEach((chunk, chunkIndex) => {
+      chunk.forEach((value, index) => {
+        expect(value).toBe(alphabet[chunkIndex * chunkSize + index]);
+      });
     });
   });
 
-  describe("mapAndSplit", () => {
-    it("maps over a list of values and split it in chunks", () => {
-      const values = new Array(20).fill(0).map((_, i) => i);
+  it("is a curried function", () => {
+    const mapper = (n: number) => n * 2;
+    const splitBy2 = mapAndSplit(mapper, 2);
 
-      const alphabet = Array.from(Array(26)).map((_, i) =>
-        String.fromCharCode(i + 65)
-      );
+    expect(typeof splitBy2).toBe("function");
 
-      const getLetterForInt = (num) => alphabet[num];
-      const chunkSize = 5;
+    expect(splitBy2([1, 2, 3, 4])).toEqual([
+      [2, 4],
+      [6, 8],
+    ]);
+  });
 
-      const result = mapAndSplit<number, string>(
-        getLetterForInt,
-        chunkSize
-      )(values);
+  it("returns an empty list for an empty input", () => {
+    expect(mapAndSplit((n: number) => n, 2)([])).toEqual([]);
+  });
 
-      expect(result.length).toBe(values.length / chunkSize);
+  it("puts remaining items in a final smaller chunk", () => {
+    expect(mapAndSplit((n: number) => n, 2)([1, 2, 3])).toEqual([[1, 2], [3]]);
+  });
 
-      result.forEach((chunk, chunkIndex) => {
-        chunk.forEach((value, index) => {
-          expect(value).toBe(alphabet[chunkIndex * chunkSize + index]);
-        });
-      });
-    });
+  it("returns a single chunk when chunk size exceeds the list length", () => {
+    expect(mapAndSplit((n: number) => n * 10, 10)([1, 2])).toEqual([[10, 20]]);
   });
 });

package/arrayUtils/__tests__/isEmptyArray.test.ts

@@ -60,4 +60,15 @@ describe("isEmptyArray", () => {
 
     expect(isEmptyArray(value)).toBe(false);
   });
+
+  it("array with falsy values is not empty", () => {
+    expect(isEmptyArray([0])).toBe(false);
+    expect(isEmptyArray([false])).toBe(false);
+    expect(isEmptyArray([null])).toBe(false);
+    expect(isEmptyArray([undefined])).toBe(false);
+  });
+
+  it("nested empty array is not empty", () => {
+    expect(isEmptyArray([[]])).toBe(false);
+  });
 });

package/arrayUtils/__tests__/isFilledArray.test.ts

@@ -60,4 +60,16 @@ describe("isFilledArray", () => {
 
     expect(isFilledArray(value)).toBe(false);
   });
+
+  it("array with falsy values is filled", () => {
+    expect(isFilledArray([0])).toBe(true);
+    expect(isFilledArray([false])).toBe(true);
+    expect(isFilledArray([null])).toBe(true);
+    expect(isFilledArray([undefined])).toBe(true);
+    expect(isFilledArray([""])).toBe(true);
+  });
+
+  it("nested empty array is filled", () => {
+    expect(isFilledArray([[]])).toBe(true);
+  });
 });

package/arrayUtils/__tests__/isFirst.test.ts

@@ -0,0 +1,17 @@
+import { isFirst } from "..";
+
+describe("isFirst", () => {
+  it("returns true for index 0", () => {
+    expect(isFirst(0)).toBe(true);
+  });
+
+  it("returns false for positive indexes", () => {
+    expect(isFirst(1)).toBe(false);
+    expect(isFirst(10)).toBe(false);
+  });
+
+  it("returns true for negative indexes", () => {
+    expect(isFirst(-1)).toBe(true);
+    expect(isFirst(-100)).toBe(true);
+  });
+});

package/arrayUtils/__tests__/isIndexInRange.test.ts

@@ -56,4 +56,18 @@ describe("isIndexInRange", () => {
 
     expect(isIndexInRange(index, length)).toBe(false);
   });
+
+  it("single-element list", () => {
+    expect(isIndexInRange(0, 1)).toBe(true);
+    expect(isIndexInRange(1, 1)).toBe(false);
+  });
+
+  it("negative length is out of range", () => {
+    expect(isIndexInRange(0, -1)).toBe(false);
+    expect(isIndexInRange(0, -5)).toBe(false);
+  });
+
+  it("middle index is in range", () => {
+    expect(isIndexInRange(1, 3)).toBe(true);
+  });
 });

package/arrayUtils/__tests__/isLast.test.ts

@@ -0,0 +1,31 @@
+import { isLast } from "..";
+
+describe("isLast", () => {
+  it("returns true for the last index", () => {
+    expect(isLast(2, 3)).toBe(true);
+  });
+
+  it("returns false for indexes before the last", () => {
+    expect(isLast(0, 3)).toBe(false);
+    expect(isLast(1, 3)).toBe(false);
+  });
+
+  it("returns true for indexes at or past the last", () => {
+    expect(isLast(3, 3)).toBe(true);
+    expect(isLast(10, 3)).toBe(true);
+  });
+
+  it("returns true for a single-element list", () => {
+    expect(isLast(0, 1)).toBe(true);
+  });
+
+  it("treats empty length as last for indexes >= -1", () => {
+    expect(isLast(0, 0)).toBe(true);
+    expect(isLast(-1, 0)).toBe(true);
+    expect(isLast(-2, 0)).toBe(false);
+  });
+
+  it("returns false for negative indexes that are before length - 1", () => {
+    expect(isLast(-1, 3)).toBe(false);
+  });
+});