@applicaster/zapp-react-native-utils 16.0.0-alpha.4416921324 → 16.0.0-alpha.4548770949

package/appUtils/playerManager/playerFactory.ts

@@ -1,7 +1,7 @@
 import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
 import { findPluginByIdentifier } from "@applicaster/zapp-react-native-utils/pluginUtils";
 import { Player } from "./player";
-import { PlayerRole } from "./conts";
+import { PlayerRole } from "./const";
 
 type PlayerFactoryItem = {
   Component: any;

package/appUtils/playerManager/playerNative.ts

@@ -3,9 +3,10 @@ import { isEmptyOrNil } from "@applicaster/zapp-react-native-utils/cellUtils";
 import { createLogger, utilsLogger } from "../../logger";
 import { Player } from "./player";
 import { findNodeHandle } from "react-native";
-import { PlayerRole } from "./conts";
+import { PlayerRole } from "./const";
 import { toBooleanWithDefaultFalse } from "../../booleanUtils";
 import { RNPlayerManager } from "./nativePlayerManager";
+import { isApplePlatform } from "../../reactUtils";
 
 const logger = createLogger({
   category: "PlayerNativeController",
@@ -27,6 +28,7 @@ interface PlayerMethods {
   appStateChange?: (appState: string, previousAppState: string) => void;
   closeNativePlayer?: () => void;
   togglePlayPause?: () => void;
+  command?: (command: string, userInfo?: Record<string, any>) => void;
 }
 
 type PlayerComponent = ReactComponent<PlayerRefProps> & PlayerMethods;
@@ -52,6 +54,7 @@ const PlayerModuleFuncNames = {
   startSleepTimer: "startSleepTimer",
   cancelSleepTimer: "cancelSleepTimer",
   getSleepTimerEnd: "getSleepTimerEnd",
+  command: "command",
 };
 
 export class PlayerNative extends Player {
@@ -206,6 +209,25 @@ export class PlayerNative extends Player {
     }
   };
 
+  command = (command: string, userInfo?: Record<string, any>) => {
+    if (isApplePlatform()) {
+      const module = this.getPlayerModule();
+      module?.command?.(command, this.playerId, userInfo);
+
+      return true;
+    }
+
+    if (
+      !this.invokeNativeFunction(
+        PlayerModuleFuncNames.command,
+        command,
+        userInfo
+      )
+    ) {
+      this.currentPlayerComponent()?.command?.(command, userInfo);
+    }
+  };
+
   disableBufferAnimation = (): boolean => false;
 
   selectTrack = (
@@ -296,9 +318,11 @@ export class PlayerNative extends Player {
     }, listeners);
   };
 
-  isAudioItem = () =>
-    this.getEntry()?.content?.type?.includes?.("audio") ||
-    this.getEntry()?.type?.value === "audio";
+  isAudioItem = (): boolean =>
+    Boolean(
+      this.getEntry()?.content?.type?.includes?.("audio") ||
+        this.getEntry()?.type?.value?.includes?.("audio")
+    );
 
   isFullScreenSupported = (): boolean => {
     const config = this.getConfig();

package/appUtils/playerManager/playerNativeCommand.ts

@@ -1,14 +1,11 @@
 import { isApplePlatform } from "../../reactUtils";
 import { NativeModules } from "react-native";
 
-const NativePlayerModule = isApplePlatform()
-  ? NativeModules.PlayerModule
-  : NativeModules.QuickBrickDefaultPlayerModule;
-
 const PlayerNativeCommandTypes = {
   pause: "pause",
   clearPlayerData: "clearPlayerData",
   removeViewByNativeId: "removeViewByNativeId",
+  setPlayerControls: "setPlayerControls",
 };
 
 const PlayerNativeSendCommand = (
@@ -16,8 +13,8 @@ const PlayerNativeSendCommand = (
   playerId: string,
   userInfo?: Record<string, any>
 ) => {
-  if (playerId && command) {
-    NativePlayerModule?.command?.(command, playerId, userInfo);
+  if (isApplePlatform() && playerId && command) {
+    NativeModules.PlayerModule?.command?.(command, playerId, userInfo);
   }
 };
 

package/appUtils/playerManager/playerToolbox.ts

@@ -0,0 +1,196 @@
+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);
+
+/** 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;
+}) => {
+  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 (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,
+          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,
+          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,
+        };
+      },
+    },
+    {
+      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: "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:
+        "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__/reorderByIds.test.ts

@@ -0,0 +1,63 @@
+import { reorderByIds } from "../index";
+
+describe("reorderByIds", () => {
+  const items = [
+    { id: "1", title: "Track 1" },
+    { id: "2", title: "Track 2" },
+    { id: "3", title: "Track 3" },
+    { id: "4", title: "Track 4" },
+  ];
+
+  it("returns an empty array if items is empty or nullish", () => {
+    expect(reorderByIds([], ["1"])).toEqual([]);
+    expect(reorderByIds(null as any, ["1"])).toEqual([]);
+  });
+
+  it("returns a copy of items if orderedIds is empty or nullish", () => {
+    expect(reorderByIds(items, [])).toEqual(items);
+    expect(reorderByIds(items, null as any)).toEqual(items);
+  });
+
+  it("reorders items based on the provided orderedIds sequence", () => {
+    const result = reorderByIds(items, ["3", "1", "4", "2"]);
+
+    expect(result.map((i) => i.id)).toEqual(["3", "1", "4", "2"]);
+  });
+
+  it("replaces items in their original slots when reordering a subset", () => {
+    const result = reorderByIds(items, ["4", "2"]);
+
+    expect(result.map((i) => i.id)).toEqual(["1", "4", "3", "2"]);
+  });
+
+  it("ignores IDs in orderedIds that do not exist in items", () => {
+    const result = reorderByIds(items, ["unknown", "3", "99", "1"]);
+
+    expect(result.map((i) => i.id)).toEqual(["3", "2", "1", "4"]);
+  });
+
+  it("supports custom getId selector function", () => {
+    const customItems = [
+      { key: "a", name: "Alpha" },
+      { key: "b", name: "Beta" },
+      { key: "c", name: "Gamma" },
+    ];
+
+    const result = reorderByIds(customItems, ["c", "a"], (item) => item.key);
+
+    expect(result.map((i) => i.key)).toEqual(["c", "b", "a"]);
+  });
+
+  it("reorders duplicate items when using unique slot identifiers via getId", () => {
+    const duplicateItems = [
+      { id: "x", slot: "s1", name: "First X" },
+      { id: "y", slot: "s2", name: "Y" },
+      { id: "x", slot: "s3", name: "Second X" },
+    ];
+
+    const result = reorderByIds(duplicateItems, ["s3", "s1"], (i) => i.slot);
+
+    expect(result).toHaveLength(3);
+    expect(result.map((i) => i.name)).toEqual(["Second X", "Y", "First X"]);
+  });
+});

package/arrayUtils/index.ts

@@ -158,3 +158,65 @@ export const allTruthy = (xs: boolean[]) =>
 
 /** Returns `true` when at least one value in `xs` is truthy. */
 export const anyTruthy = (xs: boolean[]) => xs.some(Boolean);
+
+/**
+ * Reorders `items` based on an ordered array of IDs (`orderedIds`).
+ * Items whose IDs are in `orderedIds` appear first in that exact sequence.
+ * Any remaining items not present in `orderedIds` are appended at the end preserving their relative order.
+ */
+export function reorderByIds<T>(
+  items: T[],
+  orderedIds: string[],
+  getId: (item: T) => string = (item: any) => item?.id
+): T[] {
+  if (!items || items.length === 0) return [];
+  if (!orderedIds || orderedIds.length === 0) return [...items];
+
+  const itemMap = new Map<string, T>();
+
+  items.forEach((item) => {
+    const id = getId(item);
+
+    if (
+      id !== undefined &&
+      id !== null &&
+      id !== "" &&
+      !itemMap.has(String(id))
+    ) {
+      itemMap.set(String(id), item);
+    }
+  });
+
+  const reorderedSubset: T[] = [];
+  const orderedIdsSet = new Set<string>();
+
+  orderedIds.forEach((id) => {
+    const strId = String(id);
+    const item = itemMap.get(strId);
+
+    if (item && !orderedIdsSet.has(strId)) {
+      reorderedSubset.push(item);
+      orderedIdsSet.add(strId);
+    }
+  });
+
+  if (reorderedSubset.length === 0) return [...items];
+
+  let subsetIdx = 0;
+
+  return items.map((item) => {
+    const id = getId(item);
+
+    if (
+      id !== undefined &&
+      id !== null &&
+      id !== "" &&
+      orderedIdsSet.has(String(id)) &&
+      subsetIdx < reorderedSubset.length
+    ) {
+      return reorderedSubset[subsetIdx++];
+    }
+
+    return item;
+  });
+}

package/cellUtils/__tests__/getButtonsEnabled.test.ts

@@ -0,0 +1,28 @@
+import { getButtonsEnabled } from "..";
+
+describe("getButtonsEnabled", () => {
+  it("returns true when the buttons container is enabled", () => {
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: true })
+    ).toBe(true);
+
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: "true" })
+    ).toBe(true);
+  });
+
+  it("returns false when the buttons container is disabled", () => {
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: false })
+    ).toBe(false);
+
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: "false" })
+    ).toBe(false);
+  });
+
+  it("returns false when the key or styles are missing", () => {
+    expect(getButtonsEnabled({})).toBe(false);
+    expect(getButtonsEnabled(undefined)).toBe(false);
+  });
+});

package/cellUtils/__tests__/getCellNavigationEnabled.test.ts

@@ -0,0 +1,36 @@
+import { getCellNavigationEnabled } from "..";
+
+describe("getCellNavigationEnabled", () => {
+  it("returns true when cell navigation is enabled", () => {
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: true,
+      })
+    ).toBe(true);
+
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: "true",
+      })
+    ).toBe(true);
+  });
+
+  it("returns false when cell navigation is disabled", () => {
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: false,
+      })
+    ).toBe(false);
+
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: "false",
+      })
+    ).toBe(false);
+  });
+
+  it("returns false when the key or styles are missing", () => {
+    expect(getCellNavigationEnabled({})).toBe(false);
+    expect(getCellNavigationEnabled(undefined)).toBe(false);
+  });
+});

package/cellUtils/__tests__/getIsCellNavigationEnabled.test.ts

@@ -0,0 +1,35 @@
+import { getIsCellNavigationEnabled } from "..";
+
+describe("getIsCellNavigationEnabled", () => {
+  it("is disabled when buttons are enabled and cell navigation is off", () => {
+    expect(
+      getIsCellNavigationEnabled({
+        mobile_buttons_container_buttons_enabled: true,
+        mobile_buttons_container_cell_navigation_enabled: false,
+      })
+    ).toBe(false);
+  });
+
+  it("is enabled when buttons and cell navigation are both on", () => {
+    expect(
+      getIsCellNavigationEnabled({
+        mobile_buttons_container_buttons_enabled: true,
+        mobile_buttons_container_cell_navigation_enabled: true,
+      })
+    ).toBe(true);
+  });
+
+  it("is enabled when buttons are disabled", () => {
+    expect(
+      getIsCellNavigationEnabled({
+        mobile_buttons_container_buttons_enabled: false,
+        mobile_buttons_container_cell_navigation_enabled: false,
+      })
+    ).toBe(true);
+  });
+
+  it("is enabled when the keys or styles are missing", () => {
+    expect(getIsCellNavigationEnabled({})).toBe(true);
+    expect(getIsCellNavigationEnabled(undefined)).toBe(true);
+  });
+});

package/cellUtils/__tests__/isCellNavigationEnabled.test.ts

@@ -0,0 +1,21 @@
+import { isCellNavigationEnabled } from "..";
+
+describe("isCellNavigationEnabled", () => {
+  it("is enabled when buttons are disabled, regardless of the toggle", () => {
+    expect(isCellNavigationEnabled(false, false)).toBe(true);
+    expect(isCellNavigationEnabled(false, true)).toBe(true);
+    expect(isCellNavigationEnabled(undefined, undefined)).toBe(true);
+    expect(isCellNavigationEnabled("false", false)).toBe(true);
+  });
+
+  it("is disabled when buttons are enabled and the toggle is off or missing", () => {
+    expect(isCellNavigationEnabled(true, false)).toBe(false);
+    expect(isCellNavigationEnabled(true, undefined)).toBe(false);
+    expect(isCellNavigationEnabled("true", "false")).toBe(false);
+  });
+
+  it("is enabled when buttons and the toggle are both enabled", () => {
+    expect(isCellNavigationEnabled(true, true)).toBe(true);
+    expect(isCellNavigationEnabled("true", "true")).toBe(true);
+  });
+});