@volley/vwr-loader 1.5.0 → 1.7.0

package/src/loadVwr.ts

@@ -1,357 +0,0 @@
-import type { DatadogRum } from "@datadog/browser-rum"
-import type * as VWR from "@volley/vwr"
-
-import { fetchAmplitudeFlags, FlagFetchError } from "./amplitudeFlagFetcher"
-import { ENV_DEFAULTS } from "./envDefaults"
-import {
-    InitializationError,
-    InitializationErrorReason,
-    isVWRInitializationError,
-} from "./errors"
-import { getDeviceId } from "./getDeviceId"
-import { getEnvironment } from "./getEnvironment"
-import { getShellVersion } from "./getShellVersion"
-import { logger, setLogger } from "./logger"
-import type {
-    ConfigFetchAttempt,
-    VWRConfig,
-    VWRConfigRequest,
-    VWRConfigResult,
-} from "./vwrConfig"
-import { getVWRConfig, validateConfig } from "./vwrConfig"
-
-// Vite injects these at build time
-// 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
-
-// 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
-
-/**
- * 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, 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 legacy logger, defaults to console
- * @param observability - Optional observability config with @volley/logger and RUM client
- */
-export const loadVwr = async (rum?: DatadogRum) => {
-    const totalStartTime = performance.now()
-
-    try {
-        await initializeVwr(rum)
-
-        // Track successful VWR initialization
-        rum?.addAction("vwr:init:complete", {
-            outcome: "success",
-            duration_ms: performance.now() - totalStartTime,
-        })
-    } catch (error) {
-        // Track failed VWR initialization
-        rum?.addAction("vwr:init:complete", {
-            outcome: "failure",
-            duration_ms: performance.now() - totalStartTime,
-        })
-
-        // Track fallback with structured reason
-        let reason = "UNKNOWN_ERROR"
-        if (error instanceof InitializationError) {
-            reason = error.reason
-        } else if (isVWRInitializationError(error)) {
-            reason = error.reason
-        }
-        rum?.addAction("vwr:fallback", {
-            reason,
-            error_type: error instanceof Error ? error.name : "UnknownError",
-        })
-
-        throw error
-    }
-}
-
-async function initializeVwr(rum: DatadogRum | undefined) {
-    if (!PLATFORM || !CONFIG_URL || !CONFIG_FILE) {
-        throw new InitializationError(
-            InitializationErrorReason.ENV_VARS_MISSING,
-            "[Shell] Required environment variables not injected (PLATFORM, CONFIG_URL, or CONFIG_FILE)",
-            {
-                configUrl: CONFIG_URL,
-                configFile: CONFIG_FILE,
-            }
-        )
-    }
-
-    logger.info({ platform: PLATFORM }, "Starting VWR load")
-    rum?.setGlobalContextProperty("platform", PLATFORM)
-
-    const deviceId = await getDeviceId(PLATFORM)
-    if (!deviceId) {
-        throw new InitializationError(
-            InitializationErrorReason.DEVICE_ID_FAILED,
-            `[Shell] Failed to retrieve device ID for platform: ${PLATFORM}`
-        )
-    }
-
-    // Set logger with deviceId context
-    setLogger(logger.child({ deviceId }))
-
-    const shellVersion = await getShellVersion(PLATFORM)
-
-    if (!shellVersion) {
-        throw new InitializationError(
-            InitializationErrorReason.SHELL_VERSION_FAILED,
-            `[Shell] Failed to retrieve shell version for platform: ${PLATFORM}`
-        )
-    }
-
-    // Set logger with shellVersion context
-    setLogger(logger.child({ shellVersion }))
-
-    // 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
-    )
-
-    // 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 InitializationError(
-                InitializationErrorReason.ENV_UNKNOWN,
-                `[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)
-    let flags
-    try {
-        flags = await fetchAmplitudeFlags(
-            deviceId,
-            PLATFORM,
-            {
-                apiKey: amplitudeKey,
-                timeout: 2000,
-            },
-            shellVersion
-        )
-    } catch (error) {
-        if (error instanceof FlagFetchError) {
-            throw new InitializationError(
-                InitializationErrorReason.FLAG_FETCH_FAILED,
-                `[Shell] ${error.message}`,
-                {
-                    cause: error.cause,
-                }
-            )
-        }
-        throw error
-    }
-
-    logger.debug({ flags }, "Flags fetched")
-
-    // Set RUM context for flag result (enables filtering by flag outcome)
-    rum?.setGlobalContextProperty(
-        "flag_result",
-        flags["vwr-enabled"] ? "enabled" : "disabled"
-    )
-
-    if (!flags["vwr-enabled"]) {
-        // Flag OFF: skip all config fetches, fail fast
-        throw new InitializationError(
-            InitializationErrorReason.FLAG_DISABLED,
-            "[Shell] VWR not enabled via Amplitude flags"
-        )
-    }
-
-    // Flag ON: proceed with full config loading
-    logger.debug("VWR flag enabled, fetching config")
-
-    const vwrConfigRequest: VWRConfigRequest = {
-        configUrl: CONFIG_URL,
-        configFile: CONFIG_FILE,
-        platform: PLATFORM,
-        deviceId: deviceId,
-        environment: ENVIRONMENT,
-        shellVersion: shellVersion,
-    }
-
-    let vwrConfig: VWRConfig
-    let configSource: VWRConfigResult["source"]
-    let configAttempts: ConfigFetchAttempt[]
-    let configTotalDurationMs: number
-    try {
-        const result = await getVWRConfig(vwrConfigRequest, logger)
-        vwrConfig = result.config
-        configSource = result.source
-        configAttempts = result.attempts
-        configTotalDurationMs = result.total_duration_ms
-
-        // Set RUM context for config source (enables tracking config fallback rate)
-        rum?.setGlobalContextProperty("config_source", configSource)
-
-        // Track per-source fetch attempts for detailed analysis
-        for (const attempt of configAttempts) {
-            rum?.addAction("vwr:config:fetch_attempt", {
-                source: attempt.source,
-                success: attempt.success,
-                duration_ms: attempt.duration_ms,
-            })
-        }
-
-        // Track total config resolution (all sources fetched in parallel)
-        rum?.addAction("vwr:config:resolved", {
-            source: configSource,
-            total_duration_ms: configTotalDurationMs,
-        })
-
-        logger.debug(
-            {
-                source: configSource,
-                total_duration_ms: configTotalDurationMs,
-                attempts: configAttempts,
-            },
-            "Config fetched"
-        )
-    } catch (configError) {
-        throw new InitializationError(
-            InitializationErrorReason.CONFIG_FETCH_FAILED,
-            configError instanceof Error
-                ? configError.message
-                : "Config fetch failed",
-            {
-                cause: configError instanceof Error ? configError : undefined,
-                configUrl: CONFIG_URL,
-            }
-        )
-    }
-
-    if (!validateConfig(vwrConfig)) {
-        throw new InitializationError(
-            InitializationErrorReason.CONFIG_INVALID,
-            "[Shell] Invalid config (missing vwrUrl, hubUrl, or trustedDomains)",
-            {
-                config: JSON.stringify(vwrConfig),
-            }
-        )
-    }
-
-    logger.debug({ vwrUrl: vwrConfig.vwrUrl }, "Loading VWR module")
-
-    let vwr: typeof VWR
-    try {
-        vwr = (await import(/* @vite-ignore */ vwrConfig.vwrUrl)) as typeof VWR
-
-        logger.debug("VWR module loaded successfully")
-    } catch (fetchError) {
-        const err =
-            fetchError instanceof Error
-                ? fetchError
-                : new Error(String(fetchError))
-
-        throw new InitializationError(
-            InitializationErrorReason.MODULE_FETCH_FAILED,
-            `[Shell] Failed to fetch VWR module: ${err.message}`,
-            {
-                cause: err,
-                vwrUrl: vwrConfig.vwrUrl,
-            }
-        )
-    }
-
-    if (typeof vwr.init !== "function") {
-        throw new InitializationError(
-            InitializationErrorReason.MODULE_INVALID,
-            "[Shell] VWR module missing init() function",
-            {
-                vwrUrl: vwrConfig.vwrUrl,
-            }
-        )
-    }
-
-    // Build config source display string for VWR mode indicator
-    let configSourceDisplay: string
-    switch (configSource) {
-        case "device":
-            configSourceDisplay = `device (${deviceId})`
-            break
-        case "environment":
-            configSourceDisplay = `environment (${ENVIRONMENT})`
-            break
-        case "shellVersion":
-            configSourceDisplay = `shell-version (${ENVIRONMENT}/${PLATFORM}/${shellVersion})`
-            break
-        case "local":
-            configSourceDisplay = "local"
-            break
-        default:
-            configSourceDisplay = "defaults"
-            break
-    }
-
-    try {
-        await vwr.init(
-            {
-                hubUrl: vwrConfig.hubUrl,
-                launchUrl: vwrConfig.launchUrl,
-                platform: PLATFORM,
-                stage: ENVIRONMENT,
-                appVersion: shellVersion,
-                platformApiUrl: vwrConfig.platformApiUrl,
-                platformAuthApiUrl: vwrConfig.platformAuthApiUrl,
-                trustedOrigins: new Set(vwrConfig.trustedDomains),
-                nativeShellVersion: shellVersion,
-                configSource: configSourceDisplay,
-            },
-            logger,
-            rum
-        )
-    } catch (vwrError) {
-        // Re-throw InitializationErrors as-is (e.g., MODULE_INVALID)
-        if (vwrError instanceof InitializationError) {
-            throw vwrError
-        }
-
-        // Re-throw VWR errors directly - they already have structured info
-        if (isVWRInitializationError(vwrError)) {
-            throw vwrError
-        }
-
-        // Wrap other unknown errors as INIT_FAILED
-        const errorMessage =
-            vwrError instanceof Error ? vwrError.message : String(vwrError)
-
-        throw new InitializationError(
-            InitializationErrorReason.INIT_FAILED,
-            `[Shell] VWR initialization failed: ${errorMessage}`,
-            {
-                cause: vwrError instanceof Error ? vwrError : undefined,
-            }
-        )
-    }
-}

package/src/logger.ts

@@ -1,121 +0,0 @@
-import { datadogLogs } from "@datadog/browser-logs"
-import type { ILogger } from "@volley/logger"
-import { createLogger } from "@volley/logger"
-
-/**
- * Context type specifically for error logs.
- * Use this when calling logger.error() to include the Error object
- * for RUM Error Tracking (source maps, stack traces).
- *
- * @example
- * ```typescript
- * const context: ErrorLogContext = {
- *     error: someError,
- *     error_type: someError.name,
- *     // ... other context
- * }
- * logger.error(context, "Something went wrong")
- * ```
- */
-
-// Initialize Datadog Logs - forwardErrorsToLogs disabled since we handle errors manually
-datadogLogs.init({
-    clientToken: import.meta.env.VITE_DATADOG_CLIENT_TOKEN,
-    site: "datadoghq.com",
-    service: "vwr-loader",
-    env: import.meta.env.VITE_ENVIRONMENT,
-    version: import.meta.env.VITE_SHELL_VERSION,
-    forwardErrorsToLogs: true, // RUM picks up console errors automatically
-    sessionSampleRate: 100,
-})
-
-/**
- * Extract message and context from pino log object.
- * Removes internal pino fields (msg, level, time) and extracts error if present.
- */
-function parseLogObject(logObject: object) {
-    const obj = logObject as Record<string, unknown>
-    const msg = (obj.msg as string) || ""
-    const errorObj = obj.error instanceof Error ? obj.error : undefined
-
-    // Build context (exclude internal pino fields)
-    const {
-        msg: _msg,
-        level: _level,
-        time: _time,
-        error: _error,
-        ...context
-    } = obj
-
-    return { msg, context, errorObj }
-}
-
-/**
- * Write handler for non-error logs (trace, debug, info, warn).
- * Sends to console and Datadog Logs.
- */
-function writeLog(
-    logObject: object,
-    consoleMethod: "debug" | "info" | "warn",
-    datadogLevel: "debug" | "info" | "warn"
-) {
-    const { msg, context } = parseLogObject(logObject)
-
-    // Write to console for dev visibility
-    console[consoleMethod](msg, context)
-
-    // Send to Datadog Logs
-    datadogLogs.logger[datadogLevel](msg, context)
-}
-
-/**
- * Write handler for error logs (error, fatal).
- * Sends to console and Datadog Logs with Error object.
- *
- * NOTE: This is commented out because forwardErrorsToLogs: true in datadogLogs.init()
- * automatically forwards console.error calls to Datadog Logs. If forwardErrorsToLogs
- * were disabled, we would use this handler to manually send errors to Datadog.
- */
-// function writeError(logObject: object) {
-//     const { msg, context, errorObj } = parseLogObject(logObject)
-
-//     // Write to console for dev visibility (include error for stack trace)
-//     if (errorObj) {
-//         console.error(msg, context, errorObj)
-//     } else {
-//         console.error(msg, context)
-//     }
-
-//     // Send to Datadog Logs with Error object as 3rd arg
-//     datadogLogs.logger.error(msg, context, errorObj)
-// }
-
-export let logger: ILogger = createLogger({
-    type: "browser",
-    browser: {
-        asObject: true,
-        formatters: {
-            level(label: string) {
-                return { level: label }
-            },
-        },
-        // Separate write handlers per level for clarity
-        write: {
-            trace: (o: object) => writeLog(o, "debug", "debug"),
-            debug: (o: object) => writeLog(o, "debug", "debug"),
-            info: (o: object) => writeLog(o, "info", "info"),
-            warn: (o: object) => writeLog(o, "warn", "warn"),
-            // error and fatal logs are automatically forwarded to Datadog via forwardErrorsToLogs
-            // error: writeError,
-            // fatal: writeError,
-        },
-    },
-}).child({
-    service: "vwr-loader",
-    env: import.meta.env.VITE_ENVIRONMENT,
-    platform: import.meta.env.VITE_PLATFORM,
-})
-
-export function setLogger(_logger: ILogger) {
-    logger = _logger
-}

package/src/main.test.ts

@@ -1,157 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest"
-
-// Mock all dependencies before importing main
-vi.mock("./datadog", () => ({
-    initRumGlobal: vi.fn(() => ({
-        addAction: vi.fn(),
-        setGlobalContextProperty: vi.fn(),
-    })),
-}))
-
-vi.mock("./loadVwr", () => ({
-    loadVwr: vi.fn(),
-}))
-
-vi.mock("./logger", () => ({
-    logger: {
-        info: vi.fn(),
-        warn: vi.fn(),
-        error: vi.fn(),
-    },
-}))
-
-// Mock window.location
-const mockLocationHref = vi.fn()
-delete (window as any).location
-;(window as any).location = {
-    _href: "",
-    search: "",
-    set href(value: string) {
-        this._href = value
-        mockLocationHref(value)
-    },
-    get href() {
-        return this._href
-    },
-}
-
-import { InitializationError } from "./errors"
-import { loadVwr } from "./loadVwr"
-import { logger } from "./logger"
-
-const mockLoadVwr = vi.mocked(loadVwr)
-
-describe("main.ts fallback behavior", () => {
-    beforeEach(() => {
-        vi.resetAllMocks()
-        vi.resetModules()
-        mockLocationHref.mockClear()
-        ;(window.location as any)._href = ""
-        ;(window.location as any).search = ""
-
-        // Stub environment variables
-        vi.stubEnv("VITE_PLATFORM", "FIRE_TV")
-        vi.stubEnv("VITE_HUB_URL", "https://hub.example.com")
-        vi.stubEnv("VITE_ENVIRONMENT", "dev")
-    })
-
-    describe("when VWR initialization fails", () => {
-        it("falls back to Hub URL when no gameControllerUrl present", async () => {
-            mockLoadVwr.mockRejectedValue(
-                new InitializationError("FLAG_DISABLED", "VWR not enabled", {})
-            )
-
-            // Import and run main
-            await import("./main")
-
-            // Wait for async init to complete
-            await vi.waitFor(() => {
-                expect(mockLocationHref).toHaveBeenCalled()
-            })
-
-            expect(mockLocationHref).toHaveBeenCalledWith(
-                "https://hub.example.com/?volley_platform=FIRE_TV&version=unknown"
-            )
-            expect(logger.info).toHaveBeenCalledWith(
-                expect.objectContaining({
-                    PLATFORM: "FIRE_TV",
-                }),
-                "[Shell] No gameControllerUrl, redirecting to Hub"
-            )
-        })
-
-        it("falls back to gameControllerUrl when present", async () => {
-            mockLoadVwr.mockRejectedValue(
-                new InitializationError("FLAG_DISABLED", "VWR not enabled", {})
-            )
-            ;(window.location as any).search =
-                "?gameControllerUrl=https://vly.gg/game123"
-
-            await import("./main")
-
-            await vi.waitFor(() => {
-                expect(mockLocationHref).toHaveBeenCalled()
-            })
-
-            expect(mockLocationHref).toHaveBeenCalledWith(
-                "https://vly.gg/game123"
-            )
-            expect(logger.info).toHaveBeenCalledWith(
-                expect.objectContaining({
-                    gameControllerUrl: "https://vly.gg/game123",
-                }),
-                "[Shell] Using gameControllerUrl as fallback"
-            )
-        })
-
-        it("falls back to Hub URL when gameControllerUrl is empty", async () => {
-            mockLoadVwr.mockRejectedValue(
-                new InitializationError("FLAG_DISABLED", "VWR not enabled", {})
-            )
-            ;(window.location as any).search = "?gameControllerUrl="
-
-            await import("./main")
-
-            await vi.waitFor(() => {
-                expect(mockLocationHref).toHaveBeenCalled()
-            })
-
-            expect(mockLocationHref).toHaveBeenCalledWith(
-                "https://hub.example.com/?volley_platform=FIRE_TV&version=unknown"
-            )
-        })
-
-        it("falls back to Hub URL when gameControllerUrl is whitespace only", async () => {
-            mockLoadVwr.mockRejectedValue(
-                new InitializationError("FLAG_DISABLED", "VWR not enabled", {})
-            )
-            ;(window.location as any).search = "?gameControllerUrl=%20%20"
-
-            await import("./main")
-
-            await vi.waitFor(() => {
-                expect(mockLocationHref).toHaveBeenCalled()
-            })
-
-            expect(mockLocationHref).toHaveBeenCalledWith(
-                "https://hub.example.com/?volley_platform=FIRE_TV&version=unknown"
-            )
-        })
-
-        it("logs errors before fallback", async () => {
-            mockLoadVwr.mockRejectedValue(new Error("Init error"))
-
-            await import("./main")
-
-            await vi.waitFor(() => {
-                expect(logger.error).toHaveBeenCalled()
-            })
-
-            // Verify error was logged (exact format depends on error type)
-            expect(logger.error).toHaveBeenCalled()
-            expect(mockLocationHref).toHaveBeenCalledWith(
-                "https://hub.example.com/?volley_platform=FIRE_TV&version=unknown"
-            )
-        })
-    })
-})