@volley/vwr-loader 1.4.0 → 1.6.0

package/src/exitHandler.test.ts

@@ -1,6 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 
-import { exitIfBackNavigation, setupLGBackButtonHandler } from "./exitHandler"
+import {
+    exitIfBackNavigation,
+    setupFireTVBackButtonHandler,
+    setupLGBackButtonHandler,
+} from "./exitHandler"
+import { logger } from "./logger"
 
 describe("exitHandler", () => {
     beforeEach(() => {
@@ -81,14 +86,247 @@ describe("exitHandler", () => {
             expect(() => exitIfBackNavigation("SAMSUNG_TV")).not.toThrow()
         })
 
-        it("should handle platforms without specific exit behavior", () => {
+        it("should exit Fire TV app when back_forward detected", () => {
             vi.spyOn(performance, "getEntriesByType").mockReturnValue([
                 { type: "back_forward" } as PerformanceNavigationTiming,
             ])
 
-            // Fire TV doesn't have platform-specific exit - just logs
+            const mockExitApp = vi.fn().mockResolvedValue(undefined)
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                },
+            }
+
+            exitIfBackNavigation("FIRE_TV")
+
+            expect(mockExitApp).toHaveBeenCalled()
+        })
+
+        it("should handle Fire TV without Capacitor gracefully", () => {
+            vi.spyOn(performance, "getEntriesByType").mockReturnValue([
+                { type: "back_forward" } as PerformanceNavigationTiming,
+            ])
+
+            window.Capacitor = undefined
+
             expect(() => exitIfBackNavigation("FIRE_TV")).not.toThrow()
         })
+
+        it("should log when Fire TV exit promise rejects", async () => {
+            vi.spyOn(performance, "getEntriesByType").mockReturnValue([
+                { type: "back_forward" } as PerformanceNavigationTiming,
+            ])
+
+            const mockExitApp = vi
+                .fn()
+                .mockRejectedValue(new Error("exit failed"))
+            const loggerErrorSpy = vi.spyOn(logger, "error")
+
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                },
+            }
+
+            exitIfBackNavigation("FIRE_TV")
+
+            await vi.waitFor(() => {
+                expect(loggerErrorSpy).toHaveBeenCalledWith(
+                    { error: expect.any(Error) },
+                    "[Shell] Failed to exit Fire TV app"
+                )
+            })
+        })
+    })
+
+    describe("setupFireTVBackButtonHandler", () => {
+        const ANDROID_BACK_KEYCODE = 4
+        type KeyDownListener = (event: { keyCode: number }) => void
+
+        it("should call Capacitor AppLifecycle.exitApp when InputHandler emits back keyDown", async () => {
+            const mockExitApp = vi.fn().mockResolvedValue(undefined)
+            const mockRemoveListener = vi.fn().mockResolvedValue(undefined)
+            let capturedListener: KeyDownListener | null = null
+            const mockAddListener = vi
+                .fn()
+                .mockImplementation(
+                    async (eventName: string, listener: KeyDownListener) => {
+                        if (eventName === "keyDown") {
+                            capturedListener = listener
+                        }
+
+                        return {
+                            remove: mockRemoveListener,
+                        }
+                    }
+                )
+
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                    InputHandler: {
+                        addListener: mockAddListener,
+                    },
+                },
+            }
+
+            const cleanup = setupFireTVBackButtonHandler()
+
+            await vi.waitFor(() => {
+                expect(mockAddListener).toHaveBeenCalledWith(
+                    "keyDown",
+                    expect.any(Function)
+                )
+            })
+
+            capturedListener?.({ keyCode: ANDROID_BACK_KEYCODE })
+
+            expect(mockExitApp).toHaveBeenCalled()
+
+            cleanup()
+        })
+
+        it("should handle missing Capacitor gracefully", () => {
+            window.Capacitor = undefined
+
+            const cleanup = setupFireTVBackButtonHandler()
+
+            expect(() => cleanup()).not.toThrow()
+            cleanup()
+        })
+
+        it("should not trigger when InputHandler emits non-back keyDown", async () => {
+            const mockExitApp = vi.fn().mockResolvedValue(undefined)
+            let capturedListener: KeyDownListener | null = null
+            const mockAddListener = vi
+                .fn()
+                .mockImplementation(
+                    async (eventName: string, listener: KeyDownListener) => {
+                        if (eventName === "keyDown") {
+                            capturedListener = listener
+                        }
+
+                        return {
+                            remove: vi.fn().mockResolvedValue(undefined),
+                        }
+                    }
+                )
+
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                    InputHandler: {
+                        addListener: mockAddListener,
+                    },
+                },
+            }
+
+            const cleanup = setupFireTVBackButtonHandler()
+
+            await vi.waitFor(() => {
+                expect(mockAddListener).toHaveBeenCalledWith(
+                    "keyDown",
+                    expect.any(Function)
+                )
+            })
+
+            capturedListener?.({ keyCode: 13 })
+
+            expect(mockExitApp).not.toHaveBeenCalled()
+
+            cleanup()
+        })
+
+        it("should remove InputHandler listener when cleanup is called", async () => {
+            const mockExitApp = vi.fn().mockResolvedValue(undefined)
+            const mockRemoveListener = vi.fn().mockResolvedValue(undefined)
+            const mockAddListener = vi.fn().mockResolvedValue({
+                remove: mockRemoveListener,
+            })
+
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                    InputHandler: {
+                        addListener: mockAddListener,
+                    },
+                },
+            }
+
+            const cleanup = setupFireTVBackButtonHandler()
+
+            await vi.waitFor(() => {
+                expect(mockAddListener).toHaveBeenCalledWith(
+                    "keyDown",
+                    expect.any(Function)
+                )
+            })
+
+            cleanup()
+
+            await vi.waitFor(() => {
+                expect(mockRemoveListener).toHaveBeenCalled()
+            })
+        })
+
+        it("should support InputHandler addListener returning a sync handle", async () => {
+            const mockExitApp = vi.fn().mockResolvedValue(undefined)
+            const mockRemoveListener = vi.fn().mockResolvedValue(undefined)
+            let capturedListener: KeyDownListener | null = null
+            const mockAddListener = vi
+                .fn()
+                .mockImplementation(
+                    (eventName: string, listener: KeyDownListener) => {
+                        if (eventName === "keyDown") {
+                            capturedListener = listener
+                        }
+
+                        return {
+                            remove: mockRemoveListener,
+                        }
+                    }
+                )
+
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                    InputHandler: {
+                        addListener: mockAddListener,
+                    },
+                },
+            }
+
+            const cleanup = setupFireTVBackButtonHandler()
+
+            expect(mockAddListener).toHaveBeenCalledWith(
+                "keyDown",
+                expect.any(Function)
+            )
+
+            capturedListener?.({ keyCode: ANDROID_BACK_KEYCODE })
+            expect(mockExitApp).toHaveBeenCalled()
+
+            cleanup()
+
+            await vi.waitFor(() => {
+                expect(mockRemoveListener).toHaveBeenCalled()
+            })
+        })
+
+        it("should handle missing InputHandler plugin gracefully", () => {
+            const mockExitApp = vi.fn().mockResolvedValue(undefined)
+            window.Capacitor = {
+                Plugins: {
+                    AppLifecycle: { exitApp: mockExitApp },
+                },
+            }
+
+            const cleanup = setupFireTVBackButtonHandler()
+
+            expect(mockExitApp).not.toHaveBeenCalled()
+            expect(() => cleanup()).not.toThrow()
+        })
     })
 
     describe("setupLGBackButtonHandler", () => {

package/src/exitHandler.ts

@@ -10,6 +10,9 @@ import { logger } from "./logger"
 /** LG webOS back button keycode */
 const LG_BACK_KEYCODE = 461
 
+/** Android back button keycode (used by Fire TV InputHandler plugin) */
+const ANDROID_BACK_KEYCODE = 4
+
 /**
  * Exit the app if the page was loaded via back/forward navigation.
  *
@@ -80,6 +83,86 @@ export function setupLGBackButtonHandler(): () => void {
     }
 }
 
+/**
+ * Set up Fire TV back button (keycode 4) handler.
+ *
+ * On Fire TV, the native shell intercepts the back button at the Activity
+ * level and forwards it to JavaScript via the InputHandler Capacitor plugin.
+ * During the vwr-loader loading phase, we subscribe directly to InputHandler
+ * keyDown events and call Capacitor AppLifecycle.exitApp().
+ *
+ * Once VWR loads successfully, call the returned cleanup function - VWR
+ * will take over back button handling.
+ *
+ * @returns Cleanup function to remove the listener
+ */
+export function setupFireTVBackButtonHandler(): () => void {
+    const inputHandler = window.Capacitor?.Plugins?.InputHandler
+
+    if (!inputHandler?.addListener) {
+        logger.warn("[Shell] Capacitor InputHandler plugin not available")
+        return () => {
+            logger.info("[Shell] Fire TV back button handler removed")
+        }
+    }
+
+    let listenerHandle: { remove: () => Promise<void> | void } | null = null
+    let isCleanedUp = false
+
+    const listenerRegistration = Promise.resolve(
+        inputHandler.addListener("keyDown", (event: { keyCode: number }) => {
+            if (event.keyCode === ANDROID_BACK_KEYCODE) {
+                logger.info("[Shell] Fire TV back button pressed, exiting app")
+                exitFireTVApp()
+            }
+        })
+    )
+        .then((handle: { remove: () => Promise<void> | void }) => {
+            listenerHandle = handle
+
+            if (isCleanedUp) {
+                return Promise.resolve(handle.remove()).catch(
+                    (error: unknown) => {
+                        logger.error(
+                            { error },
+                            "[Shell] Failed to remove Fire TV back button handler"
+                        )
+                    }
+                )
+            }
+
+            return undefined
+        })
+        .catch((error: unknown) => {
+            logger.error(
+                { error },
+                "[Shell] Failed to register Fire TV back button handler"
+            )
+        })
+
+    logger.info("[Shell] Fire TV back button handler registered")
+
+    return () => {
+        isCleanedUp = true
+
+        if (listenerHandle) {
+            void Promise.resolve(listenerHandle.remove()).catch(
+                (error: unknown) => {
+                    logger.error(
+                        { error },
+                        "[Shell] Failed to remove Fire TV back button handler"
+                    )
+                }
+            )
+            listenerHandle = null
+        } else {
+            void listenerRegistration
+        }
+
+        logger.info("[Shell] Fire TV back button handler removed")
+    }
+}
+
 /**
  * Exit the app using platform-specific methods.
  *
@@ -93,7 +176,10 @@ function exitApp(platform: Platform): void {
         case "LG_TV":
             exitLGAppViaBackNavigation()
             break
-        // Fire TV and mobile apps handle exit at the native layer
+        case "FIRE_TV":
+            exitFireTVApp()
+            break
+        // Mobile apps handle exit at the native layer
         // Web doesn't have a meaningful "exit" concept
         default:
             logger.info({ platform }, "[Shell] No platform-specific exit")
@@ -123,3 +209,25 @@ function exitLGAppViaBackNavigation(): void {
         logger.error({ error }, "[Shell] Failed to exit LG app")
     }
 }
+
+/**
+ * Exit Fire TV app via Capacitor AppLifecycle plugin.
+ */
+function exitFireTVApp(): void {
+    try {
+        if (window.Capacitor?.Plugins?.AppLifecycle?.exitApp) {
+            void window.Capacitor.Plugins.AppLifecycle.exitApp().catch(
+                (error: unknown) => {
+                    logger.error(
+                        { error },
+                        "[Shell] Failed to exit Fire TV app"
+                    )
+                }
+            )
+        } else {
+            logger.warn("[Shell] Capacitor AppLifecycle plugin not available")
+        }
+    } catch (error) {
+        logger.error({ error }, "[Shell] Failed to exit Fire TV app")
+    }
+}

package/src/getShellVersion.ts

@@ -1,5 +1,6 @@
+import type { MobileExtendedWindow } from "@volley/vwr/src/types"
+
 import { logger } from "./logger"
-import type { MobileExtendedWindow } from "./types"
 
 /**
  * Retrieve shell app version for different platforms.

package/src/index.ts

@@ -1,7 +1,7 @@
+export { getDeviceId } from "../../vwr/src/native/device-info/getDeviceId"
+export type { VWRConfig, VWRConfigRequest } from "../../vwr/src/vwrConfig"
+export { getVWRConfig } from "../../vwr/src/vwrConfig"
 export type { AmplitudeConfig, FlagResult } from "./amplitudeFlagFetcher"
 export { fetchAmplitudeFlags } from "./amplitudeFlagFetcher"
-export { getDeviceId } from "./getDeviceId"
 export { getShellVersion } from "./getShellVersion"
 export { loadVwr } from "./loadVwr"
-export type { VWRConfig, VWRConfigRequest } from "./vwrConfig"
-export { getVWRConfig } from "./vwrConfig"

package/src/loadVwr.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 
 // Mock all dependencies before importing loadVwr
-vi.mock("./getDeviceId", () => ({
+vi.mock("../../vwr/src/native/device-info/getDeviceId", () => ({
     getDeviceId: vi.fn(),
 }))
 
@@ -19,7 +19,7 @@ vi.mock("./amplitudeFlagFetcher", () => ({
     },
 }))
 
-vi.mock("./vwrConfig", () => ({
+vi.mock("../../vwr/src/vwrConfig", () => ({
     getVWRConfig: vi.fn(),
     validateConfig: vi.fn(),
 }))
@@ -29,11 +29,14 @@ vi.mock("./getEnvironment", () => ({
 }))
 
 // Import mocked modules
+
+import type { DatadogRum } from "@datadog/browser-rum"
+
+import { getDeviceId } from "../../vwr/src/native/device-info/getDeviceId"
+import { getVWRConfig, validateConfig } from "../../vwr/src/vwrConfig"
 import { fetchAmplitudeFlags } from "./amplitudeFlagFetcher"
-import { getDeviceId } from "./getDeviceId"
 import { getEnvironment } from "./getEnvironment"
 import { getShellVersion } from "./getShellVersion"
-import { getVWRConfig, validateConfig } from "./vwrConfig"
 
 const mockGetDeviceId = vi.mocked(getDeviceId)
 const mockGetShellVersion = vi.mocked(getShellVersion)
@@ -43,12 +46,18 @@ const mockGetVWRConfig = vi.mocked(getVWRConfig)
 const mockValidateConfig = vi.mocked(validateConfig)
 
 // Mock RUM object for tests
-const createMockRum = () => ({
-    addAction: vi.fn(),
-    addError: vi.fn(),
-    addTiming: vi.fn(),
-    setGlobalContextProperty: vi.fn(),
-})
+const createMockRum = () =>
+    ({
+        addAction: vi.fn(),
+        addError: vi.fn(),
+        addTiming: vi.fn(),
+        setGlobalContextProperty: vi.fn(),
+    }) as unknown as DatadogRum & {
+        addAction: ReturnType<typeof vi.fn>
+        addError: ReturnType<typeof vi.fn>
+        addTiming: ReturnType<typeof vi.fn>
+        setGlobalContextProperty: ReturnType<typeof vi.fn>
+    }
 
 describe("loadVwr", () => {
     beforeEach(() => {
@@ -71,6 +80,7 @@ describe("loadVwr", () => {
                 platformApiUrl: "https://platform.example.com",
                 platformAuthApiUrl: "https://auth.example.com",
                 trustedDomains: ["https://hub.example.com"],
+                trustedShellOrigins: [],
             },
             source: "environment",
             attempts: [],
@@ -321,6 +331,7 @@ describe("loadVwr", () => {
                     platformApiUrl: "https://platform.example.com",
                     platformAuthApiUrl: "https://auth.example.com",
                     trustedDomains: ["https://hub.example.com"],
+                    trustedShellOrigins: [],
                 },
                 source: "device",
                 attempts: [
@@ -391,4 +402,153 @@ describe("loadVwr", () => {
             )
         })
     })
+
+    describe("configSource display string", () => {
+        const mockVwrModulePath = "./__mocks__/vwrModule"
+
+        const setupWithConfigSource = (
+            source:
+                | "device"
+                | "shellVersion"
+                | "environment"
+                | "defaults"
+                | "local"
+        ) => {
+            mockGetVWRConfig.mockResolvedValue({
+                config: {
+                    vwrUrl: mockVwrModulePath,
+                    hubUrl: "https://hub.example.com",
+                    launchUrl: undefined,
+                    platformApiUrl: "https://platform.example.com",
+                    platformAuthApiUrl: "https://auth.example.com",
+                    trustedDomains: ["https://hub.example.com"],
+                    trustedShellOrigins: [],
+                },
+                source,
+                attempts: [],
+                total_duration_ms: 100,
+            })
+        }
+
+        beforeEach(async () => {
+            vi.stubEnv("VITE_ENVIRONMENT", "dev")
+            vi.stubEnv("VITE_PLATFORM", "FIRE_TV")
+            vi.stubEnv("VITE_CONFIG_URL", "https://config.example.com")
+            vi.stubEnv("VITE_CONFIG_FILE", "config.json")
+
+            // Reset the mock init function between tests
+            const vwrModule = await import("./__mocks__/vwrModule")
+            vwrModule.init.mockReset()
+        })
+
+        it('passes "device (<deviceId>)" for device config source', async () => {
+            setupWithConfigSource("device")
+
+            const { loadVwr } = await import("./loadVwr")
+            const mockRum = createMockRum()
+
+            try {
+                await loadVwr(mockRum)
+            } catch {
+                // May fail after init
+            }
+
+            const vwrModule = await import("./__mocks__/vwrModule")
+            expect(vwrModule.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    configSource: "device (test-device-id)",
+                }),
+                expect.anything(),
+                expect.anything()
+            )
+        })
+
+        it('passes "environment (<env>)" for environment config source', async () => {
+            setupWithConfigSource("environment")
+
+            const { loadVwr } = await import("./loadVwr")
+            const mockRum = createMockRum()
+
+            try {
+                await loadVwr(mockRum)
+            } catch {
+                // May fail after init
+            }
+
+            const vwrModule = await import("./__mocks__/vwrModule")
+            expect(vwrModule.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    configSource: "environment (dev)",
+                }),
+                expect.anything(),
+                expect.anything()
+            )
+        })
+
+        it('passes "shell-version (<env>/<platform>/<version>)" for shellVersion config source', async () => {
+            setupWithConfigSource("shellVersion")
+
+            const { loadVwr } = await import("./loadVwr")
+            const mockRum = createMockRum()
+
+            try {
+                await loadVwr(mockRum)
+            } catch {
+                // May fail after init
+            }
+
+            const vwrModule = await import("./__mocks__/vwrModule")
+            expect(vwrModule.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    configSource: "shell-version (dev/FIRE_TV/1.0.0)",
+                }),
+                expect.anything(),
+                expect.anything()
+            )
+        })
+
+        it('passes "local" for local config source', async () => {
+            setupWithConfigSource("local")
+
+            const { loadVwr } = await import("./loadVwr")
+            const mockRum = createMockRum()
+
+            try {
+                await loadVwr(mockRum)
+            } catch {
+                // May fail after init
+            }
+
+            const vwrModule = await import("./__mocks__/vwrModule")
+            expect(vwrModule.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    configSource: "local",
+                }),
+                expect.anything(),
+                expect.anything()
+            )
+        })
+
+        it('passes "defaults" for defaults config source', async () => {
+            setupWithConfigSource("defaults")
+
+            const { loadVwr } = await import("./loadVwr")
+            const mockRum = createMockRum()
+
+            try {
+                await loadVwr(mockRum)
+            } catch {
+                // May fail after init
+            }
+
+            const vwrModule = await import("./__mocks__/vwrModule")
+            expect(vwrModule.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    configSource: "defaults",
+                }),
+                expect.anything(),
+                expect.anything()
+            )
+        })
+    })
 })