@volley/vwr-loader 1.1.0 → 1.2.0

package/src/envDefaults.ts

@@ -13,6 +13,14 @@ const CONFIG_URL_DEFAULT = "https://vwr.volley.tv/config/"
 const CONFIG_FILE_DEFAULT = "vwrConfig.json"
 const VWR_URL_PATH_DEFAULT = "v1/latest/vwr.js"
 
+// Parse comma-separated env var, returning undefined if empty to allow fallback
+const parseTrustedOrigins = (
+    envVar: string | undefined
+): string[] | undefined => {
+    const parsed = envVar?.split(",").filter(Boolean)
+    return parsed?.length ? parsed : undefined
+}
+
 const prodConfig: EnvConfig = {
     hubUrl: "https://game-clients.volley.tv/hub",
     vwrUrl: `https://vwr.volley.tv/${VWR_URL_PATH_DEFAULT}`,
@@ -21,6 +29,7 @@ const prodConfig: EnvConfig = {
     platformApiUrl: "https://platform.volley-services.net",
     platformAuthApiUrl: "https://auth.volley.tv",
     amplitudeKey: "",
+    trustedOrigins: ["https://volley.tv", "https://vl.ly", "https://vly.gg"],
 }
 
 export const ENV_DEFAULTS: Record<string, EnvConfig> = {
@@ -37,9 +46,16 @@ export const ENV_DEFAULTS: Record<string, EnvConfig> = {
             import.meta.env.VITE_PLATFORM_AUTH_API_URL ||
             "https://auth-dev.volley.tv",
         amplitudeKey: "client-uJJVW3zKPC1G9kqPhUumLnZN6eaY42iQ",
-        trustedOrigins: import.meta.env.VITE_TRUSTED_ORIGINS?.split(",").filter(
-            Boolean
-        ),
+        trustedOrigins: parseTrustedOrigins(
+            import.meta.env.VITE_TRUSTED_ORIGINS
+        ) || [
+            "http://localhost:5173",
+            "http://localhost:5174",
+            "https://vl.ly",
+            "https://dev.vl.ly",
+            "https://staging.vl.ly",
+            "https://vly.gg",
+        ],
     },
     dev: {
         hubUrl: "https://game-clients-dev.volley.tv/hub",
@@ -49,6 +65,13 @@ export const ENV_DEFAULTS: Record<string, EnvConfig> = {
         platformApiUrl: "https://platform-dev.volley-services.net",
         platformAuthApiUrl: "https://auth-dev.volley.tv",
         amplitudeKey: "client-uJJVW3zKPC1G9kqPhUumLnZN6eaY42iQ",
+        trustedOrigins: [
+            "https://volley.tv",
+            "https://vl.ly",
+            "https://dev.vl.ly",
+            "https://staging.vl.ly",
+            "https://vly.gg",
+        ],
     },
     staging: {
         hubUrl: "https://game-clients-staging.volley.tv/hub",
@@ -58,6 +81,12 @@ export const ENV_DEFAULTS: Record<string, EnvConfig> = {
         platformApiUrl: "https://platform-staging.volley-services.net",
         platformAuthApiUrl: "https://auth-staging.volley.tv",
         amplitudeKey: "",
+        trustedOrigins: [
+            "https://volley.tv",
+            "https://vl.ly",
+            "https://staging.vl.ly",
+            "https://vly.gg",
+        ],
     },
     prod: prodConfig,
     production: prodConfig, // Alias for prod

package/src/errors/InitializationError.ts

@@ -0,0 +1,105 @@
+/**
+ * Reason codes for VWR loader initialization failures.
+ * Each code maps to a specific failure point in the init flow.
+ */
+export const InitializationErrorReason = {
+    // Environment variable errors
+    ENV_VARS_MISSING: "ENV_VARS_MISSING",
+    ENV_UNKNOWN: "ENV_UNKNOWN",
+
+    // Device/platform errors
+    DEVICE_ID_FAILED: "DEVICE_ID_FAILED",
+    SHELL_VERSION_FAILED: "SHELL_VERSION_FAILED",
+
+    // Feature flag errors
+    FLAG_DISABLED: "FLAG_DISABLED",
+    FLAG_FETCH_FAILED: "FLAG_FETCH_FAILED",
+
+    // Runtime config errors
+    CONFIG_FETCH_FAILED: "CONFIG_FETCH_FAILED",
+    CONFIG_INVALID: "CONFIG_INVALID",
+
+    // Module loading errors
+    MODULE_FETCH_FAILED: "MODULE_FETCH_FAILED",
+    MODULE_INVALID: "MODULE_INVALID",
+
+    // VWR init errors
+    INIT_FAILED: "INIT_FAILED",
+} as const
+
+export type InitializationErrorReason =
+    (typeof InitializationErrorReason)[keyof typeof InitializationErrorReason]
+
+/**
+ * Context for initialization errors - used for structured logging
+ * and Datadog dashboard creation.
+ */
+export interface InitializationErrorContext {
+    cause?: Error
+    [key: string]: unknown
+}
+
+/**
+ * Custom error for VWR loader initialization failures.
+ *
+ * Provides structured information for:
+ * - Error categorization (reason code)
+ * - RUM phase tracking
+ * - Datadog dashboard filtering
+ * - Original error chain preservation
+ *
+ * @example
+ * ```typescript
+ * throw new InitializationError(
+ *     InitializationErrorReason.DEVICE_ID_FAILED,
+ *     `Failed to retrieve device ID for platform: ${platform}`,
+ *     {
+ *         phase: "vwr-loader:device_id",
+ *         platform,
+ *     }
+ * );
+ * ```
+ */
+export class InitializationError extends Error {
+    public readonly name = "InitializationError"
+
+    constructor(
+        /** Structured reason code for categorization */
+        public readonly reason: InitializationErrorReason,
+        /** Human-readable error message */
+        public readonly message: string,
+        /** Context for logging and RUM tracking */
+        public readonly context: InitializationErrorContext = {}
+    ) {
+        super(message)
+
+        // Ensure proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, InitializationError.prototype)
+    }
+
+    /**
+     * Convert to a plain object for structured logging.
+     * Useful for Datadog Logs and JSON serialization.
+     */
+    toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            reason: this.reason,
+            message: this.message,
+            ...this.context,
+            cause: this.context.cause?.message,
+            stack: this.stack,
+        }
+    }
+
+    /**
+     * Get error context.
+     * Returns the context object.
+     */
+    getContext(): Record<string, unknown> {
+        return {
+            ...this.context,
+            reason: this.reason,
+        }
+    }
+}

package/src/errors/ensureError.ts

@@ -0,0 +1,6 @@
+export function ensureError(error: unknown): Error {
+    if (error instanceof Error) {
+        return error
+    }
+    return new Error(String(error ?? "Unknown error"))
+}

package/src/errors/index.ts

@@ -0,0 +1,16 @@
+export { ensureError } from "./ensureError"
+export type { InitializationErrorContext } from "./InitializationError"
+export {
+    InitializationError,
+    InitializationErrorReason,
+} from "./InitializationError"
+
+/**
+ * Type guard for VWR initialization errors.
+ * Checks error.name instead of instanceof to avoid runtime dependency on @volley/vwr.
+ */
+export function isVWRInitializationError(
+    error: unknown
+): error is Error & { name: "VWRInitializationError"; reason: string } {
+    return error instanceof Error && error.name === "VWRInitializationError"
+}

package/src/getDeviceId.test.ts

@@ -1,7 +1,10 @@
+import * as uuid from "uuid"
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 
 import { getDeviceId } from "./getDeviceId"
 
+vi.mock("uuid")
+
 describe("getDeviceId", () => {
     beforeEach(() => {
         vi.clearAllMocks()
@@ -247,11 +250,7 @@ describe("getDeviceId", () => {
 
         it("generates and stores new device ID when none exists", async () => {
             const mockUUID = "web-uuid-123"
-            Object.defineProperty(window.crypto, "randomUUID", {
-                value: vi.fn().mockReturnValue(mockUUID),
-                writable: true,
-                configurable: true,
-            })
+            vi.mocked(uuid.v4).mockReturnValue(mockUUID as any)
 
             const result = await getDeviceId("WEB")
 

package/src/getDeviceId.ts

@@ -1,4 +1,6 @@
-import { defaultLogger, type Logger } from "./logger"
+import { v4 as uuidv4 } from "uuid"
+
+import { logger } from "./logger"
 import type { LGDeviceIdResponse, MobileExtendedWindow } from "./types"
 
 /**
@@ -25,21 +27,18 @@ import type { LGDeviceIdResponse, MobileExtendedWindow } from "./types"
  * }
  * ```
  */
-export async function getDeviceId(
-    platform: string,
-    logger: Logger = defaultLogger
-): Promise<string | null> {
+export async function getDeviceId(platform: string): Promise<string | null> {
     const normalizedPlatform = platform.toUpperCase()
     switch (normalizedPlatform) {
         case "FIRE_TV":
-            return await getFireTVDeviceId(logger)
+            return await getFireTVDeviceId()
         case "SAMSUNG_TV":
-            return await getSamsungDeviceId(logger)
+            return await getSamsungDeviceId()
         case "LG_TV":
-            return await getLGDeviceId(logger)
+            return await getLGDeviceId()
         case "ANDROID_MOBILE":
         case "IOS_MOBILE":
-            return await getMobileDeviceId(logger)
+            return await getMobileDeviceId()
         case "WEB":
             return getLocalStorageDeviceId()
         default:
@@ -53,18 +52,20 @@ export async function getDeviceId(
  * Get or create device ID from localStorage (for Web platform)
  */
 function getLocalStorageDeviceId(): string {
-    let deviceId = localStorage.getItem("volley_device_id")
-    if (!deviceId) {
-        deviceId = crypto.randomUUID()
-        localStorage.setItem("volley_device_id", deviceId)
+    const existingDeviceId = localStorage.getItem("volley_device_id")
+    if (existingDeviceId) {
+        return existingDeviceId
     }
-    return deviceId
+
+    const newDeviceId = uuidv4()
+    localStorage.setItem("volley_device_id", newDeviceId)
+    return newDeviceId
 }
 
 /**
  * Attempt to get device ID from Capacitor DeviceInfo plugin (FireTV)
  */
-async function getFireTVDeviceId(logger: Logger): Promise<string | null> {
+async function getFireTVDeviceId(): Promise<string | null> {
     try {
         if (!window.Capacitor?.Plugins?.DeviceInfo?.getAndroidId) {
             return null
@@ -91,7 +92,7 @@ async function getFireTVDeviceId(logger: Logger): Promise<string | null> {
  * iOS exposes phoneDeviceId via window.iosAppContext
  * Android exposes phoneDeviceId via window.androidAppContext (also check window.top for iframes)
  */
-function getMobileDeviceId(logger: Logger): string | null {
+function getMobileDeviceId(): string | null {
     // Try iOS first
     const iosId = (window as MobileExtendedWindow).iosAppContext?.phoneDeviceId
     if (iosId && iosId.trim()) {
@@ -126,7 +127,7 @@ function getMobileDeviceId(logger: Logger): string | null {
 /**
  * Attempt to get device ID from Samsung TV webapis
  */
-async function getSamsungDeviceId(logger: Logger): Promise<string | null> {
+async function getSamsungDeviceId(): Promise<string | null> {
     try {
         if (!window.webapis?.productinfo?.getDuid) {
             return null
@@ -156,7 +157,7 @@ async function getSamsungDeviceId(logger: Logger): Promise<string | null> {
  */
 const LG_LUNA_SERVICE_TIMEOUT = 5000
 
-async function getLGDeviceId(logger: Logger): Promise<string | null> {
+async function getLGDeviceId(): Promise<string | null> {
     if (!window.webOS?.service?.request) {
         const message = "LG webOS service request not available"
         logger.error(message)

package/src/getEnvironment.test.ts

@@ -1,19 +1,21 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 
 import { type Environment, getEnvironment } from "./getEnvironment"
+import { logger } from "./logger"
 
-describe("getEnvironment", () => {
-    const mockLogger = {
+vi.mock("./logger", () => ({
+    logger: {
         info: vi.fn(),
         warn: vi.fn(),
         error: vi.fn(),
-    }
+        debug: vi.fn(),
+        child: vi.fn(),
+    },
+}))
 
+describe("getEnvironment", () => {
     beforeEach(() => {
         vi.clearAllMocks()
-        mockLogger.info.mockClear()
-        mockLogger.warn.mockClear()
-        mockLogger.error.mockClear()
         // Clean up window properties
         delete (window as any).Capacitor
     })
@@ -42,15 +44,11 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("dev")
             expect(result.source).toBe("native")
-            expect(mockLogger.info).toHaveBeenCalledWith(
+            expect(logger.info).toHaveBeenCalledWith(
                 expect.stringContaining(
                     'Environment: "dev" (source: native BuildConfig.ENVIRONMENT="development")'
                 )
@@ -74,11 +72,7 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("prod")
             expect(result.source).toBe("native")
@@ -101,11 +95,7 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("staging")
             expect(result.source).toBe("native")
@@ -128,11 +118,7 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("staging")
             expect(result.source).toBe("native")
@@ -155,11 +141,7 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("dev")
             expect(result.source).toBe("native")
@@ -182,11 +164,7 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("dev")
             expect(result.source).toBe("native")
@@ -194,15 +172,11 @@ describe("getEnvironment", () => {
 
         it("should fallback to build-time when native plugin unavailable", async () => {
             // No Capacitor plugin available
-            const result = await getEnvironment(
-                "FIRE_TV",
-                "staging",
-                mockLogger
-            )
+            const result = await getEnvironment("FIRE_TV", "staging")
 
             expect(result.environment).toBe("staging")
             expect(result.source).toBe("build-time")
-            expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect(logger.warn).toHaveBeenCalledWith(
                 expect.stringContaining(
                     "Failed to read environment from native, falling back to build-time"
                 )
@@ -226,12 +200,12 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment("FIRE_TV", "prod", mockLogger)
+            const result = await getEnvironment("FIRE_TV", "prod")
 
             expect(result.environment).toBe("prod")
             expect(result.source).toBe("build-time")
-            expect(mockLogger.error).toHaveBeenCalled()
-            expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect(logger.error).toHaveBeenCalled()
+            expect(logger.warn).toHaveBeenCalledWith(
                 expect.stringContaining("falling back to build-time")
             )
         })
@@ -253,11 +227,11 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result = await getEnvironment("FIRE_TV", "dev", mockLogger)
+            const result = await getEnvironment("FIRE_TV", "dev")
 
             expect(result.environment).toBe("dev")
             expect(result.source).toBe("build-time")
-            expect(mockLogger.error).toHaveBeenCalledWith(
+            expect(logger.error).toHaveBeenCalledWith(
                 expect.stringContaining(
                     "DeviceInfo.getNativeShellAppEnvironment returned empty"
                 )
@@ -266,15 +240,11 @@ describe("getEnvironment", () => {
 
         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
-            )
+            const result = await getEnvironment("FIRE_TV", undefined)
 
             expect(result.environment).toBe("dev")
             expect(result.source).toBe("default")
-            expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect(logger.warn).toHaveBeenCalledWith(
                 expect.stringContaining(
                     'Environment: "dev" (source: default fallback'
                 )
@@ -298,16 +268,8 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            const result1 = await getEnvironment(
-                "fire_tv",
-                undefined,
-                mockLogger
-            )
-            const result2 = await getEnvironment(
-                "FIRE_TV",
-                undefined,
-                mockLogger
-            )
+            const result1 = await getEnvironment("fire_tv", undefined)
+            const result2 = await getEnvironment("FIRE_TV", undefined)
 
             expect(result1.environment).toBe("prod")
             expect(result2.environment).toBe("prod")
@@ -320,15 +282,11 @@ describe("getEnvironment", () => {
         platforms.forEach((platform) => {
             describe(`${platform}`, () => {
                 it("should use build-time environment when provided", async () => {
-                    const result = await getEnvironment(
-                        platform,
-                        "staging",
-                        mockLogger
-                    )
+                    const result = await getEnvironment(platform, "staging")
 
                     expect(result.environment).toBe("staging")
                     expect(result.source).toBe("build-time")
-                    expect(mockLogger.info).toHaveBeenCalledWith(
+                    expect(logger.info).toHaveBeenCalledWith(
                         expect.stringContaining(
                             'Environment: "staging" (source: build-time CLI injection)'
                         )
@@ -336,48 +294,32 @@ describe("getEnvironment", () => {
                 })
 
                 it("should use build-time 'prod' environment", async () => {
-                    const result = await getEnvironment(
-                        platform,
-                        "prod",
-                        mockLogger
-                    )
+                    const result = await getEnvironment(platform, "prod")
 
                     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
-                    )
+                    const result = await getEnvironment(platform, "dev")
 
                     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
-                    )
+                    const result = await getEnvironment(platform, "local")
 
                     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
-                    )
+                    const result = await getEnvironment(platform, undefined)
 
                     expect(result.environment).toBe("dev")
                     expect(result.source).toBe("default")
-                    expect(mockLogger.warn).toHaveBeenCalledWith(
+                    expect(logger.warn).toHaveBeenCalledWith(
                         expect.stringContaining(
                             'Environment: "dev" (source: default fallback'
                         )
@@ -385,11 +327,7 @@ describe("getEnvironment", () => {
                 })
 
                 it("should fallback to default when build-time is invalid", async () => {
-                    const result = await getEnvironment(
-                        platform,
-                        "invalid-env",
-                        mockLogger
-                    )
+                    const result = await getEnvironment(platform, "invalid-env")
 
                     expect(result.environment).toBe("dev")
                     expect(result.source).toBe("default")
@@ -403,7 +341,7 @@ describe("getEnvironment", () => {
             const validEnvs: Environment[] = ["local", "dev", "staging", "prod"]
 
             for (const env of validEnvs) {
-                const result = await getEnvironment("WEB", env, mockLogger)
+                const result = await getEnvironment("WEB", env)
                 expect(result.environment).toBe(env)
                 expect(result.source).toBe("build-time")
             }
@@ -420,7 +358,7 @@ describe("getEnvironment", () => {
             ]
 
             for (const env of invalidEnvs) {
-                const result = await getEnvironment("WEB", env, mockLogger)
+                const result = await getEnvironment("WEB", env)
                 expect(result.environment).toBe("dev")
                 expect(result.source).toBe("default")
             }
@@ -445,33 +383,33 @@ describe("getEnvironment", () => {
                 configurable: true,
             })
 
-            await getEnvironment("FIRE_TV", undefined, mockLogger)
+            await getEnvironment("FIRE_TV", undefined)
 
-            expect(mockLogger.info).toHaveBeenCalledWith(
+            expect(logger.info).toHaveBeenCalledWith(
                 '[Shell] Environment: "prod" (source: native BuildConfig.ENVIRONMENT="production")'
             )
         })
 
         it("should log build-time environment source", async () => {
-            await getEnvironment("SAMSUNG_TV", "staging", mockLogger)
+            await getEnvironment("SAMSUNG_TV", "staging")
 
-            expect(mockLogger.info).toHaveBeenCalledWith(
+            expect(logger.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)
+            await getEnvironment("LG_TV", undefined)
 
-            expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect(logger.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)
+            await getEnvironment("FIRE_TV", "prod")
 
-            expect(mockLogger.warn).toHaveBeenCalledWith(
+            expect(logger.warn).toHaveBeenCalledWith(
                 "[Shell] Failed to read environment from native, falling back to build-time"
             )
         })

package/src/getEnvironment.ts

@@ -1,4 +1,4 @@
-import { defaultLogger, type Logger } from "./logger"
+import { logger } from "./logger"
 
 export type Environment = "local" | "dev" | "staging" | "prod"
 export type EnvironmentSource = "native" | "build-time" | "default"
@@ -26,14 +26,13 @@ export interface EnvironmentResult {
  */
 export async function getEnvironment(
     platform: string,
-    buildTimeEnv: string | undefined,
-    logger: Logger = defaultLogger
+    buildTimeEnv: string | undefined
 ): 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)
+        const nativeEnv = await getFireTVEnvironment()
         if (nativeEnv) {
             const mapped = mapNativeEnvironment(nativeEnv)
             logger.info(
@@ -72,7 +71,7 @@ export async function getEnvironment(
 /**
  * Read environment from Fire TV native shell via Capacitor plugin.
  */
-async function getFireTVEnvironment(logger: Logger): Promise<string | null> {
+async function getFireTVEnvironment(): Promise<string | null> {
     try {
         if (
             !window.Capacitor?.Plugins?.DeviceInfo?.getNativeShellAppEnvironment