@volley/vwr-loader 1.0.0-alpha.1

package/src/getShellVersion.test.ts

@@ -0,0 +1,278 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { getShellVersion } from "./getShellVersion"
+
+describe("getShellVersion", () => {
+    const originalLocation = window.location
+
+    beforeEach(() => {
+        // Mock window.location
+        delete (window as any).location
+        window.location = {
+            ...originalLocation,
+            href: "http://localhost:3000/",
+        } as Location
+    })
+
+    afterEach(() => {
+        window.location = originalLocation
+        vi.restoreAllMocks()
+    })
+
+    describe("Samsung TV", () => {
+        afterEach(() => {
+            delete (window as any).tizen
+        })
+
+        it("returns version from Tizen Application API", async () => {
+            ;(window as any).tizen = {
+                application: {
+                    getAppInfo: vi.fn().mockReturnValue({ version: "1.2.3" }),
+                },
+            }
+
+            const version = await getShellVersion("SAMSUNG_TV")
+
+            expect(version).toBe("1.2.3")
+        })
+
+        it("returns unknown when tizen is not available", async () => {
+            const version = await getShellVersion("SAMSUNG_TV")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("returns unknown when version is missing from appInfo", async () => {
+            ;(window as any).tizen = {
+                application: {
+                    getAppInfo: vi.fn().mockReturnValue({}),
+                },
+            }
+
+            const version = await getShellVersion("SAMSUNG_TV")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("is case insensitive", async () => {
+            ;(window as any).tizen = {
+                application: {
+                    getAppInfo: vi.fn().mockReturnValue({ version: "2.0.0" }),
+                },
+            }
+
+            const version = await getShellVersion("samsung_tv")
+
+            expect(version).toBe("2.0.0")
+        })
+    })
+
+    describe("LG TV", () => {
+        afterEach(() => {
+            delete (window as any).webOS
+        })
+
+        it("returns version from webOS.fetchAppInfo", async () => {
+            ;(window as any).webOS = {
+                fetchAppInfo: vi.fn((callback) => {
+                    callback({ version: "3.4.5" })
+                }),
+            }
+
+            const version = await getShellVersion("LG_TV")
+
+            expect(version).toBe("3.4.5")
+        })
+
+        it("returns unknown when webOS is not available", async () => {
+            const version = await getShellVersion("LG_TV")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("returns unknown when fetchAppInfo returns no version", async () => {
+            ;(window as any).webOS = {
+                fetchAppInfo: vi.fn((callback) => {
+                    callback({})
+                }),
+            }
+
+            const version = await getShellVersion("LG_TV")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("returns unknown when fetchAppInfo callback receives undefined", async () => {
+            ;(window as any).webOS = {
+                fetchAppInfo: vi.fn((callback) => {
+                    callback(undefined)
+                }),
+            }
+
+            const version = await getShellVersion("LG_TV")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("is case insensitive", async () => {
+            ;(window as any).webOS = {
+                fetchAppInfo: vi.fn((callback) => {
+                    callback({ version: "4.0.0" })
+                }),
+            }
+
+            const version = await getShellVersion("lg_tv")
+
+            expect(version).toBe("4.0.0")
+        })
+    })
+
+    describe("FireTV", () => {
+        it("returns version from Capacitor DeviceInfo plugin", async () => {
+            const mockGetDeviceInfo = vi.fn().mockResolvedValue({
+                versionName: "5.6.7",
+            })
+
+            ;(window as any).Capacitor = {
+                Plugins: {
+                    DeviceInfo: {
+                        getDeviceInfo: mockGetDeviceInfo,
+                    },
+                },
+            }
+
+            const version = await getShellVersion("FIRE_TV")
+
+            expect(version).toBe("5.6.7")
+            expect(mockGetDeviceInfo).toHaveBeenCalled()
+
+            delete (window as any).Capacitor
+        })
+
+        it("returns unknown when Capacitor is not available", async () => {
+            const version = await getShellVersion("FIRE_TV")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("returns unknown when DeviceInfo plugin is not available", async () => {
+            ;(window as any).Capacitor = {
+                Plugins: {},
+            }
+
+            const version = await getShellVersion("FIRE_TV")
+
+            expect(version).toBe("unknown")
+
+            delete (window as any).Capacitor
+        })
+
+        it("returns unknown when getDeviceInfo is not available", async () => {
+            ;(window as any).Capacitor = {
+                Plugins: {
+                    DeviceInfo: {},
+                },
+            }
+
+            const version = await getShellVersion("FIRE_TV")
+
+            expect(version).toBe("unknown")
+
+            delete (window as any).Capacitor
+        })
+
+        it("returns unknown when versionName is missing", async () => {
+            const mockGetDeviceInfo = vi.fn().mockResolvedValue({})
+
+            ;(window as any).Capacitor = {
+                Plugins: {
+                    DeviceInfo: {
+                        getDeviceInfo: mockGetDeviceInfo,
+                    },
+                },
+            }
+
+            const version = await getShellVersion("FIRE_TV")
+
+            expect(version).toBe("unknown")
+
+            delete (window as any).Capacitor
+        })
+
+        it("is case insensitive", async () => {
+            const mockGetDeviceInfo = vi.fn().mockResolvedValue({
+                versionName: "6.0.0",
+            })
+
+            ;(window as any).Capacitor = {
+                Plugins: {
+                    DeviceInfo: {
+                        getDeviceInfo: mockGetDeviceInfo,
+                    },
+                },
+            }
+
+            const version = await getShellVersion("fire_tv")
+
+            expect(version).toBe("6.0.0")
+
+            delete (window as any).Capacitor
+        })
+    })
+
+    describe("Mobile", () => {
+        it("returns unknown (not yet implemented)", async () => {
+            const version = await getShellVersion("MOBILE")
+
+            expect(version).toBe("unknown")
+        })
+    })
+
+    describe("Web and Unknown Platforms", () => {
+        it("returns unknown for web platform", async () => {
+            const version = await getShellVersion("WEB")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("returns unknown for unknown platform", async () => {
+            const version = await getShellVersion("unknown-platform")
+
+            expect(version).toBe("unknown")
+        })
+
+        it("returns unknown for empty string", async () => {
+            const version = await getShellVersion("")
+
+            expect(version).toBe("unknown")
+        })
+    })
+
+    describe("Error Handling", () => {
+        it("returns unknown and logs warning on error", async () => {
+            const consoleWarnSpy = vi
+                .spyOn(console, "warn")
+                .mockImplementation(() => {})
+
+            // Force an error by making tizen.application.getAppInfo throw
+            ;(window as any).tizen = {
+                application: {
+                    getAppInfo: vi.fn(() => {
+                        throw new Error("Tizen API error")
+                    }),
+                },
+            }
+
+            const version = await getShellVersion("SAMSUNG_TV")
+
+            expect(version).toBe("unknown")
+            expect(consoleWarnSpy).toHaveBeenCalledWith(
+                "[Shell] Failed to get shell version:",
+                { error: expect.any(Error) }
+            )
+
+            consoleWarnSpy.mockRestore()
+            delete (window as any).tizen
+        })
+    })
+})

package/src/getShellVersion.ts

@@ -0,0 +1,114 @@
+import { defaultLogger, type Logger } from "./logger"
+
+/**
+ * Retrieve shell app version for different platforms.
+ *
+ * Platform-specific methods:
+ * - SAMSUNG_TV: Tizen Application API `tizen.application.getAppInfo().version`
+ * - LG_TV: webOS Application API `webOS.fetchAppInfo()`
+ * - FIRE_TV: Native bridge via Capacitor DeviceInfo plugin
+ * - ANDROID_MOBILE/IOS_MOBILE: Native bridge (future implementation)
+ * - WEB/Unknown: Returns 'unknown'
+ *
+ * @param platform - Platform identifier (SAMSUNG_TV, LG_TV, FIRE_TV, ANDROID_MOBILE, IOS_MOBILE, WEB)
+ * @param logger - Optional logger for warning reporting. Defaults to defaultLogger.
+ * @returns Shell version string or 'unknown' if not available
+ */
+export async function getShellVersion(
+    platform: string,
+    logger: Logger = defaultLogger
+): Promise<string> {
+    try {
+        const normalizedPlatform = platform.toUpperCase()
+
+        // Samsung TV: Get version from Tizen Application API
+        if (normalizedPlatform === "SAMSUNG_TV") {
+            if (typeof window !== "undefined" && (window as any).tizen) {
+                const tizen = (window as any).tizen
+                if (tizen.application?.getAppInfo) {
+                    const appInfo = tizen.application.getAppInfo()
+                    return appInfo?.version ?? "unknown"
+                }
+            }
+            return "unknown"
+        }
+
+        // LG TV: Get version from webOS API
+        // Note: webOS.fetchAppInfo(callback, path) takes a single callback and optional path.
+        // The callback receives the parsed appinfo.json or undefined on failure.
+        if (normalizedPlatform === "LG_TV") {
+            if (typeof window !== "undefined" && (window as any).webOS) {
+                const webOS = (window as any).webOS
+                if (webOS.fetchAppInfo) {
+                    return new Promise((resolve) => {
+                        webOS.fetchAppInfo((appInfo?: { version?: string }) => {
+                            resolve(appInfo?.version ?? "unknown")
+                        })
+                    })
+                }
+            }
+            return "unknown"
+        }
+
+        // FireTV: Get version from Capacitor DeviceInfo plugin
+        if (normalizedPlatform === "FIRE_TV") {
+            // Check if Capacitor is available
+            if (typeof window !== "undefined" && (window as any).Capacitor) {
+                const Capacitor = (window as any).Capacitor
+                const DeviceInfo = Capacitor.Plugins?.DeviceInfo
+
+                if (DeviceInfo?.getDeviceInfo) {
+                    const deviceInfo = await DeviceInfo.getDeviceInfo()
+                    return deviceInfo?.versionName ?? "unknown"
+                }
+            }
+            return "unknown"
+        }
+
+        // Mobile: Future implementation via native bridge
+        if (
+            normalizedPlatform === "ANDROID_MOBILE" ||
+            normalizedPlatform === "IOS_MOBILE" ||
+            normalizedPlatform === "MOBILE"
+        ) {
+            // TODO: Implement native bridge version retrieval when available
+            return "unknown"
+        }
+
+        // Web platform: Check for injected version at build time
+        if (normalizedPlatform === "WEB") {
+            if (
+                typeof import.meta.env !== "undefined" &&
+                import.meta.env.VITE_SHELL_VERSION
+            ) {
+                return import.meta.env.VITE_SHELL_VERSION
+            }
+        }
+
+        // Other unknown platforms
+        return "unknown"
+    } catch (error) {
+        const message = "[Shell] Failed to get shell version:"
+        logger.warn(message, { error })
+        return "unknown"
+    }
+}
+
+// Global type declarations for platform APIs
+declare global {
+    interface Window {
+        Capacitor?: {
+            Plugins?: {
+                DeviceInfo?: {
+                    getDeviceInfo(): Promise<{
+                        versionName?: string
+                        [key: string]: any
+                    }>
+                    [key: string]: any
+                }
+                [key: string]: any
+            }
+            [key: string]: any
+        }
+    }
+}

package/src/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Volley</title>
+        <style>
+            body {
+                margin: 0;
+                padding: 0;
+                background: #010020;
+            }
+            #loading {
+                color: #ffec37;
+                text-align: center;
+                padding-top: 40vh;
+                font-family: sans-serif;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="loading">Loading...</div>
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { AmplitudeConfig, FlagResult } from "./amplitudeFlagFetcher"
+export { fetchAmplitudeFlags } from "./amplitudeFlagFetcher"
+export { getDeviceId } from "./getDeviceId"
+export { getShellVersion } from "./getShellVersion"
+export type { Logger } from "./loadVwr"
+export { loadVwr } from "./loadVwr"
+export type { VWRConfig, VWRConfigRequest } from "./vwrConfig"
+export { getVWRConfig } from "./vwrConfig"

package/src/loadVwr.ts

@@ -0,0 +1,126 @@
+import { fetchAmplitudeFlags } from "./amplitudeFlagFetcher"
+import { ENV_DEFAULTS } from "./envDefaults"
+import { getDeviceId } from "./getDeviceId"
+import { getShellVersion } from "./getShellVersion"
+import { defaultLogger, type Logger } from "./logger"
+import type { VWRConfig, VWRConfigRequest } from "./vwrConfig"
+import { getVWRConfig, validateConfig } from "./vwrConfig"
+
+// Vite injects these at build time
+const ENVIRONMENT = import.meta.env.VITE_ENVIRONMENT
+const PLATFORM = import.meta.env.VITE_PLATFORM
+const CONFIG_URL = import.meta.env.VITE_CONFIG_URL
+const CONFIG_FILE = import.meta.env.VITE_CONFIG_FILE
+
+// AMPLITUDE_KEY can be optionally injected at build time (via build.ts script)
+// Falls back to envDefaults if not injected (e.g., vite.config.dev.ts)
+const AMPLITUDE_KEY = import.meta.env.VITE_AMPLITUDE_DEPLOYMENT_KEY
+
+export type { Logger }
+
+/**
+ * Load VWR runtime.
+ *
+ * Optimized flow: checks vwr-enabled flag FIRST using baked-in Amplitude key,
+ * before doing any config fetches. For flag-OFF users (100% at initial launch),
+ * this reduces startup latency from ~2-4s to ~500ms by skipping config fetches.
+ *
+ * Flow:
+ * 1. Get deviceId, shellVersion (fast, local)
+ * 2. Check vwr-enabled flag (single request, ~500ms)
+ * 3. If OFF → throw immediately (no config fetches)
+ * 4. If ON → fetch config, load VWR module, initialize
+ *
+ * @param logger - Optional logger, defaults to console
+ */
+export const loadVwr = async (logger: Logger = defaultLogger) => {
+    if (!ENVIRONMENT || !PLATFORM || !CONFIG_URL || !CONFIG_FILE) {
+        throw new Error("[Shell] Build config not injected properly")
+    }
+
+    const deviceId = await getDeviceId(PLATFORM, logger)
+    if (!deviceId) {
+        const message = `[Shell] Failed to retrieve device ID for platform: ${PLATFORM}`
+        logger.error(message)
+        throw new Error(message)
+    }
+    const shellVersion = await getShellVersion(PLATFORM, logger)
+
+    // Get amplitude key: injected at build time OR from envDefaults
+    // Precedence: build-time injection > envDefaults
+    let amplitudeKey = AMPLITUDE_KEY
+    if (!amplitudeKey) {
+        const envDefaults = ENV_DEFAULTS[ENVIRONMENT]
+        if (!envDefaults) {
+            throw new Error(`[Shell] Unknown environment: ${ENVIRONMENT}`)
+        }
+        amplitudeKey = envDefaults.amplitudeKey
+    }
+
+    // FAST PATH: Check flag first using amplitude key
+    // This avoids config fetches for flag-OFF users (majority at launch)
+    const flags = await fetchAmplitudeFlags(
+        deviceId,
+        PLATFORM,
+        {
+            apiKey: amplitudeKey,
+            timeout: 2000,
+        },
+        shellVersion
+    )
+
+    logger.info("[Shell] Flags fetched", { flags })
+
+    if (!flags["vwr-enabled"]) {
+        // Flag OFF: skip all config fetches, fail fast
+        throw new Error("[Shell] VWR not enabled via Amplitude flags")
+    }
+
+    // Flag ON: proceed with full config loading
+    logger.info("[Shell] VWR flag enabled, fetching config...")
+
+    const vwrConfigRequest: VWRConfigRequest = {
+        configUrl: CONFIG_URL,
+        configFile: CONFIG_FILE,
+        platform: PLATFORM,
+        deviceId: deviceId,
+        environment: ENVIRONMENT,
+        shellVersion: shellVersion,
+    }
+
+    const vwrConfig: VWRConfig = await getVWRConfig(vwrConfigRequest, logger)
+
+    if (!validateConfig(vwrConfig)) {
+        throw new Error("Invalid config, falling back to default hub")
+    }
+
+    logger.info("[Shell] VWR enabled, loading module", {
+        vwrUrl: vwrConfig.vwrUrl,
+    })
+    try {
+        const vwr = await import(/* @vite-ignore */ vwrConfig.vwrUrl)
+        logger.info("[Shell] VWR module loaded successfully")
+
+        if (typeof vwr.init !== "function") {
+            throw new Error("[Shell] VWR module missing init() function")
+        }
+
+        await vwr.init({
+            hubUrl: vwrConfig.hubUrl,
+            launchUrl: vwrConfig.launchUrl,
+            platform: PLATFORM,
+            deviceId,
+            environment: ENVIRONMENT,
+            trustedDomains: vwrConfig.trustedDomains,
+            nativeShellVersion: shellVersion,
+        })
+        logger.info("[Shell] VWR initialized successfully")
+    } catch (vwrError) {
+        logger.error("[Shell] VWR load failed", {
+            error:
+                vwrError instanceof Error ? vwrError.message : String(vwrError),
+            vwrUrl: vwrConfig.vwrUrl,
+        })
+        throw vwrError // Re-throw to outer catch for fallback
+    }
+}

package/src/logger.ts

@@ -0,0 +1,14 @@
+export interface Logger {
+    info: (message: string, context?: Record<string, unknown>) => void
+    warn: (message: string, context?: Record<string, unknown>) => void
+    error: (message: string, context?: Record<string, unknown>) => void
+}
+
+export const defaultLogger: Logger = {
+    info: (message, context) =>
+        context ? console.log(message, context) : console.log(message),
+    warn: (message, context) =>
+        context ? console.warn(message, context) : console.warn(message),
+    error: (message, context) =>
+        context ? console.error(message, context) : console.error(message),
+}

package/src/main.ts

@@ -0,0 +1,26 @@
+import { loadVwr } from "./loadVwr"
+
+const PLATFORM = import.meta.env.VITE_PLATFORM
+const HUB_URL = import.meta.env.VITE_HUB_URL
+
+async function init() {
+    try {
+        await loadVwr()
+    } catch (error) {
+        try {
+            console.error("[Shell] ⚠️  FALLBACK TO HUB - Init failed:", error)
+
+            if ((window as any).DD_LOGS) {
+                ;(window as any).DD_LOGS.logger.error("shell_init_failed", {
+                    error: (error as Error).message,
+                    platform: PLATFORM,
+                })
+            }
+        } finally {
+            //Fallback, can't trust config exists
+            window.location.href = HUB_URL
+        }
+    }
+}
+
+init()

package/src/vite-env.d.ts

@@ -0,0 +1,15 @@
+interface ImportMetaEnv {
+    readonly VITE_HUB_URL: string
+    readonly VITE_VWR_URL: string
+    readonly VITE_LAUNCH_URL: string
+    readonly VITE_AMPLITUDE_DEPLOYMENT_KEY: string
+    readonly VITE_ENVIRONMENT: string
+    readonly VITE_PLATFORM: string
+    readonly VITE_SHELL_VERSION: string
+    readonly VITE_CONFIG_URL: string
+    readonly VITE_CONFIG_FILE: string
+}
+
+interface ImportMeta {
+    readonly env: ImportMetaEnv
+}