@volley/vwr-loader 1.0.4 → 1.0.6

package/src/getEnvironment.test.ts

@@ -0,0 +1,457 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { type Environment, getEnvironment } from "./getEnvironment"
+
+describe("getEnvironment", () => {
+    const mockLogger = {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+    }
+
+    beforeEach(() => {
+        vi.clearAllMocks()
+        mockLogger.info.mockClear()
+        mockLogger.warn.mockClear()
+        mockLogger.error.mockClear()
+        // Clean up window properties
+        delete (window as any).Capacitor
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+        delete (window as any).Capacitor
+    })
+
+    describe("Fire TV - Native Environment Detection", () => {
+        it("should read environment from native BuildConfig for Fire TV", async () => {
+            // Setup Capacitor plugin mock
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "development",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result.environment).toBe("dev")
+            expect(result.source).toBe("native")
+            expect(mockLogger.info).toHaveBeenCalledWith(
+                expect.stringContaining(
+                    'Environment: "dev" (source: native BuildConfig.ENVIRONMENT="development")'
+                )
+            )
+        })
+
+        it("should map 'production' to 'prod'", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "production",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result.environment).toBe("prod")
+            expect(result.source).toBe("native")
+        })
+
+        it("should map 'staging' to 'staging'", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "staging",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result.environment).toBe("staging")
+            expect(result.source).toBe("native")
+        })
+
+        it("should handle native env already in vwr format (dev)", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "dev",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result.environment).toBe("dev")
+            expect(result.source).toBe("native")
+        })
+
+        it("should fallback to dev when native returns unknown value", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "unknown-env",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result.environment).toBe("dev")
+            expect(result.source).toBe("native")
+        })
+
+        it("should fallback to build-time when native plugin unavailable", async () => {
+            // No Capacitor plugin available
+            const result = await getEnvironment(
+                "FIRE_TV",
+                "staging",
+                mockLogger
+            )
+
+            expect(result.environment).toBe("staging")
+            expect(result.source).toBe("build-time")
+            expect(mockLogger.warn).toHaveBeenCalledWith(
+                expect.stringContaining(
+                    "Failed to read environment from native, falling back to build-time"
+                )
+            )
+        })
+
+        it("should fallback to build-time when native plugin throws error", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockRejectedValue(
+                                    new Error("Native plugin error")
+                                ),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment("FIRE_TV", "prod", mockLogger)
+
+            expect(result.environment).toBe("prod")
+            expect(result.source).toBe("build-time")
+            expect(mockLogger.error).toHaveBeenCalled()
+            expect(mockLogger.warn).toHaveBeenCalledWith(
+                expect.stringContaining("falling back to build-time")
+            )
+        })
+
+        it("should fallback to build-time when native returns empty", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result = await getEnvironment("FIRE_TV", "dev", mockLogger)
+
+            expect(result.environment).toBe("dev")
+            expect(result.source).toBe("build-time")
+            expect(mockLogger.error).toHaveBeenCalledWith(
+                expect.stringContaining(
+                    "DeviceInfo.getNativeShellAppEnvironment returned empty"
+                )
+            )
+        })
+
+        it("should fallback to default when both native and build-time fail", async () => {
+            // No Capacitor plugin, no build-time env
+            const result = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result.environment).toBe("dev")
+            expect(result.source).toBe("default")
+            expect(mockLogger.warn).toHaveBeenCalledWith(
+                expect.stringContaining(
+                    'Environment: "dev" (source: default fallback'
+                )
+            )
+        })
+
+        it("should be case-insensitive for Fire TV platform", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "production",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            const result1 = await getEnvironment(
+                "fire_tv",
+                undefined,
+                mockLogger
+            )
+            const result2 = await getEnvironment(
+                "FIRE_TV",
+                undefined,
+                mockLogger
+            )
+
+            expect(result1.environment).toBe("prod")
+            expect(result2.environment).toBe("prod")
+        })
+    })
+
+    describe("Non-Fire TV Platforms - Build-time Environment", () => {
+        const platforms = ["SAMSUNG_TV", "LG_TV", "MOBILE", "WEB"]
+
+        platforms.forEach((platform) => {
+            describe(`${platform}`, () => {
+                it("should use build-time environment when provided", async () => {
+                    const result = await getEnvironment(
+                        platform,
+                        "staging",
+                        mockLogger
+                    )
+
+                    expect(result.environment).toBe("staging")
+                    expect(result.source).toBe("build-time")
+                    expect(mockLogger.info).toHaveBeenCalledWith(
+                        expect.stringContaining(
+                            'Environment: "staging" (source: build-time CLI injection)'
+                        )
+                    )
+                })
+
+                it("should use build-time 'prod' environment", async () => {
+                    const result = await getEnvironment(
+                        platform,
+                        "prod",
+                        mockLogger
+                    )
+
+                    expect(result.environment).toBe("prod")
+                    expect(result.source).toBe("build-time")
+                })
+
+                it("should use build-time 'dev' environment", async () => {
+                    const result = await getEnvironment(
+                        platform,
+                        "dev",
+                        mockLogger
+                    )
+
+                    expect(result.environment).toBe("dev")
+                    expect(result.source).toBe("build-time")
+                })
+
+                it("should use build-time 'local' environment", async () => {
+                    const result = await getEnvironment(
+                        platform,
+                        "local",
+                        mockLogger
+                    )
+
+                    expect(result.environment).toBe("local")
+                    expect(result.source).toBe("build-time")
+                })
+
+                it("should fallback to default when build-time not provided", async () => {
+                    const result = await getEnvironment(
+                        platform,
+                        undefined,
+                        mockLogger
+                    )
+
+                    expect(result.environment).toBe("dev")
+                    expect(result.source).toBe("default")
+                    expect(mockLogger.warn).toHaveBeenCalledWith(
+                        expect.stringContaining(
+                            'Environment: "dev" (source: default fallback'
+                        )
+                    )
+                })
+
+                it("should fallback to default when build-time is invalid", async () => {
+                    const result = await getEnvironment(
+                        platform,
+                        "invalid-env",
+                        mockLogger
+                    )
+
+                    expect(result.environment).toBe("dev")
+                    expect(result.source).toBe("default")
+                })
+            })
+        })
+    })
+
+    describe("Environment Validation", () => {
+        it("should accept valid environments", async () => {
+            const validEnvs: Environment[] = [
+                "local",
+                "dev",
+                "qa",
+                "staging",
+                "prod",
+            ]
+
+            for (const env of validEnvs) {
+                const result = await getEnvironment("WEB", env, mockLogger)
+                expect(result.environment).toBe(env)
+                expect(result.source).toBe("build-time")
+            }
+        })
+
+        it("should reject invalid environments", async () => {
+            const invalidEnvs = [
+                "development",
+                "production",
+                "test",
+                "",
+                "random",
+            ]
+
+            for (const env of invalidEnvs) {
+                const result = await getEnvironment("WEB", env, mockLogger)
+                expect(result.environment).toBe("dev")
+                expect(result.source).toBe("default")
+            }
+        })
+    })
+
+    describe("Logging", () => {
+        it("should log native environment source", async () => {
+            Object.defineProperty(window, "Capacitor", {
+                value: {
+                    Plugins: {
+                        DeviceInfo: {
+                            getNativeShellAppEnvironment: vi
+                                .fn()
+                                .mockResolvedValue({
+                                    environment: "production",
+                                }),
+                        },
+                    },
+                },
+                writable: true,
+                configurable: true,
+            })
+
+            await getEnvironment("FIRE_TV", undefined, mockLogger)
+
+            expect(mockLogger.info).toHaveBeenCalledWith(
+                '[Shell] Environment: "prod" (source: native BuildConfig.ENVIRONMENT="production")'
+            )
+        })
+
+        it("should log build-time environment source", async () => {
+            await getEnvironment("SAMSUNG_TV", "staging", mockLogger)
+
+            expect(mockLogger.info).toHaveBeenCalledWith(
+                '[Shell] Environment: "staging" (source: build-time CLI injection)'
+            )
+        })
+
+        it("should warn when falling back to default", async () => {
+            await getEnvironment("LG_TV", undefined, mockLogger)
+
+            expect(mockLogger.warn).toHaveBeenCalledWith(
+                '[Shell] Environment: "dev" (source: default fallback - no native or build-time env found)'
+            )
+        })
+
+        it("should warn when native fails and falls back", async () => {
+            await getEnvironment("FIRE_TV", "prod", mockLogger)
+
+            expect(mockLogger.warn).toHaveBeenCalledWith(
+                "[Shell] Failed to read environment from native, falling back to build-time"
+            )
+        })
+    })
+})

package/src/getEnvironment.ts

@@ -0,0 +1,140 @@
+import { defaultLogger, type Logger } from "./logger"
+
+export type Environment = "local" | "dev" | "qa" | "staging" | "prod"
+export type EnvironmentSource = "native" | "build-time" | "default"
+
+export interface EnvironmentResult {
+    environment: Environment
+    source: EnvironmentSource
+}
+
+/**
+ * Get the environment for the current platform.
+ *
+ * Precedence:
+ * 1. Native shell (Fire TV only) - reads from BuildConfig.ENVIRONMENT
+ * 2. Build-time injection (VITE_ENVIRONMENT) - CLI override
+ * 3. Default fallback ("dev")
+ *
+ * This ensures production APKs cannot accidentally run dev VWR,
+ * since the native Android build variant determines the environment.
+ *
+ * @param platform - Platform identifier ('FIRE_TV', 'SAMSUNG_TV', 'LG_TV', 'MOBILE', 'WEB')
+ * @param buildTimeEnv - Optional build-time injected environment (from CLI)
+ * @param logger - Optional logger for reporting
+ * @returns Environment result with source information for logging
+ */
+export async function getEnvironment(
+    platform: string,
+    buildTimeEnv: string | undefined,
+    logger: Logger = defaultLogger
+): Promise<EnvironmentResult> {
+    const normalizedPlatform = platform.toUpperCase()
+
+    // For Fire TV, try to read from native first (safest - prevents env mismatch)
+    if (normalizedPlatform === "FIRE_TV") {
+        const nativeEnv = await getFireTVEnvironment(logger)
+        if (nativeEnv) {
+            const mapped = mapNativeEnvironment(nativeEnv)
+            logger.info(
+                `[Shell] Environment: "${mapped}" (source: native BuildConfig.ENVIRONMENT="${nativeEnv}")`
+            )
+            return { environment: mapped, source: "native" }
+        }
+        // Fall through to build-time if native fails
+        logger.warn(
+            "[Shell] Failed to read environment from native, falling back to build-time"
+        )
+    }
+
+    // Build-time injection (CLI --env flag)
+    if (buildTimeEnv) {
+        const normalizedBuildTimeEnv = buildTimeEnv.toLowerCase()
+        if (isValidEnvironment(normalizedBuildTimeEnv)) {
+            logger.info(
+                `[Shell] Environment: "${normalizedBuildTimeEnv}" (source: build-time CLI injection)`
+            )
+            return {
+                environment: normalizedBuildTimeEnv as Environment,
+                source: "build-time",
+            }
+        }
+    }
+
+    // Default fallback
+    const defaultEnv: Environment = "dev"
+    logger.warn(
+        `[Shell] Environment: "${defaultEnv}" (source: default fallback - no native or build-time env found)`
+    )
+    return { environment: defaultEnv, source: "default" }
+}
+
+/**
+ * Read environment from Fire TV native shell via Capacitor plugin.
+ */
+async function getFireTVEnvironment(logger: Logger): Promise<string | null> {
+    try {
+        if (
+            !window.Capacitor?.Plugins?.DeviceInfo?.getNativeShellAppEnvironment
+        ) {
+            logger.warn(
+                "[Shell] DeviceInfo.getNativeShellAppEnvironment not available"
+            )
+            return null
+        }
+
+        const result =
+            await window.Capacitor.Plugins.DeviceInfo.getNativeShellAppEnvironment()
+        if (result?.environment && result.environment.trim()) {
+            return result.environment
+        } else {
+            logger.error(
+                "[Shell] DeviceInfo.getNativeShellAppEnvironment returned empty"
+            )
+        }
+    } catch (error) {
+        logger.error(
+            "[Shell] DeviceInfo.getNativeShellAppEnvironment failed:",
+            { error }
+        )
+    }
+    return null
+}
+
+/**
+ * Map native Android BuildConfig.ENVIRONMENT values to vwr-loader environment names.
+ *
+ * Android BuildConfig values:
+ * - "development" (debug build)
+ * - "staging" (staging build)
+ * - "production" (release build)
+ *
+ * VWR environment names:
+ * - "dev"
+ * - "staging"
+ * - "prod"
+ */
+function mapNativeEnvironment(nativeEnv: string): Environment {
+    const normalized = nativeEnv.toLowerCase()
+    switch (normalized) {
+        case "development":
+            return "dev"
+        case "staging":
+            return "staging"
+        case "production":
+            return "prod"
+        default:
+            // If it's already in vwr format, use it
+            if (isValidEnvironment(normalized)) {
+                return normalized as Environment
+            }
+            return "dev"
+    }
+}
+
+function isValidEnvironment(env: string): boolean {
+    return ["local", "dev", "qa", "staging", "prod"].includes(env)
+}
+
+// Note: Window.Capacitor type is declared in getDeviceId.ts
+// We just need to add the getNativeShellAppEnvironment method type there

package/src/loadVwr.ts

@@ -3,13 +3,17 @@ import type * as VWR from "@volley/vwr"
 import { fetchAmplitudeFlags } from "./amplitudeFlagFetcher"
 import { ENV_DEFAULTS } from "./envDefaults"
 import { getDeviceId } from "./getDeviceId"
+import { getEnvironment } from "./getEnvironment"
 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
+// VITE_ENVIRONMENT is optional for platforms that support native env reading (Fire TV)
+const BUILD_TIME_ENVIRONMENT = import.meta.env.VITE_ENVIRONMENT as
+    | string
+    | undefined
 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
@@ -28,15 +32,20 @@ export type { Logger }
  * this reduces startup latency from ~2-4s to ~500ms by skipping config fetches.
  *
  * Flow:
- * 1. Get deviceId, shellVersion (fast, local)
+ * 1. Get deviceId, shellVersion, environment (fast, local/native)
  * 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
  *
+ * Environment resolution:
+ * - Fire TV: reads from native BuildConfig.ENVIRONMENT (prevents env mismatch)
+ * - Other platforms: uses build-time injected VITE_ENVIRONMENT
+ * - Fallback: "dev"
+ *
  * @param logger - Optional logger, defaults to console
  */
 export const loadVwr = async (logger: Logger = defaultLogger) => {
-    if (!ENVIRONMENT || !PLATFORM || !CONFIG_URL || !CONFIG_FILE) {
+    if (!PLATFORM || !CONFIG_URL || !CONFIG_FILE) {
         throw new Error("[Shell] Build config not injected properly")
     }
 
@@ -48,6 +57,14 @@ export const loadVwr = async (logger: Logger = defaultLogger) => {
     }
     const shellVersion = await getShellVersion(PLATFORM, logger)
 
+    // Get environment from native (Fire TV) or build-time injection
+    // This ensures prod APKs cannot accidentally run dev VWR
+    const { environment: ENVIRONMENT } = await getEnvironment(
+        PLATFORM,
+        BUILD_TIME_ENVIRONMENT,
+        logger
+    )
+
     // Get amplitude key: injected at build time OR from envDefaults
     // Precedence: build-time injection > envDefaults
     let amplitudeKey = AMPLITUDE_KEY
@@ -68,7 +85,8 @@ export const loadVwr = async (logger: Logger = defaultLogger) => {
             apiKey: amplitudeKey,
             timeout: 2000,
         },
-        shellVersion
+        shellVersion,
+        logger
     )
 
     logger.info("[Shell] Flags fetched", { flags })

package/src/vwrConfig.test.ts

@@ -90,8 +90,8 @@ describe("vwrConfig", async () => {
             expect(config.hubUrl).toBe("https://game-clients.volley.tv/hub")
             expect(config.launchUrl).toBeUndefined() // Optional, not set by default
             expect(config.trustedDomains).toEqual([
-                "https://game-clients.volley.tv/hub",
-                "https://vwr.volley.tv/v1/latest/vwr.js",
+                "https://game-clients.volley.tv",
+                "https://vwr.volley.tv",
             ])
         })