playkit-sdk 1.2.8-beta.1 → 1.2.8-beta.3

package/dist/playkit-sdk.cjs.js

@@ -1,5 +1,5 @@
 /**
- * playkit-sdk v1.2.8-beta.1
+ * playkit-sdk v1.2.8-beta.3
  * PlayKit SDK for JavaScript
  * @license SEE LICENSE IN LICENSE
  */
@@ -107,33 +107,607 @@ function npcActionToTool(action) {
     };
 }
 
+/**
+ * PlayKit SDK Logger Module
+ *
+ * Provides a configurable logging system that allows:
+ * - Controlling whether logs are sent to console
+ * - Configuring where logs are sent
+ * - Allowing external packages to hook into PlayKit logs
+ * - Ensuring PlayKit output doesn't go directly to console
+ */
+/**
+ * Log level enumeration
+ * Lower values = higher priority
+ */
+exports.LogLevel = void 0;
+(function (LogLevel) {
+    /** Disable all logging */
+    LogLevel[LogLevel["NONE"] = 0] = "NONE";
+    /** Error level - only errors */
+    LogLevel[LogLevel["ERROR"] = 1] = "ERROR";
+    /** Warn level - warnings and errors */
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    /** Info level - info, warnings, and errors */
+    LogLevel[LogLevel["INFO"] = 3] = "INFO";
+    /** Debug level - all logs */
+    LogLevel[LogLevel["DEBUG"] = 4] = "DEBUG";
+})(exports.LogLevel || (exports.LogLevel = {}));
+/**
+ * PlayKit Logger
+ *
+ * Features:
+ * - Multiple log levels (debug, info, warn, error)
+ * - Configurable log output destinations
+ * - Allows external code to register handlers to receive logs
+ * - Can completely disable console output
+ *
+ * @example
+ * ```typescript
+ * import { Logger, LogLevel } from 'playkit-sdk';
+ *
+ * // Get a logger for your module
+ * const logger = Logger.getLogger('MyModule');
+ *
+ * // Log messages
+ * logger.debug('Debug message');
+ * logger.info('Info message');
+ * logger.warn('Warning message');
+ * logger.error('Error message', error);
+ * ```
+ */
+class Logger {
+    constructor(source) {
+        this.source = source;
+    }
+    // ===== Static configuration methods =====
+    /**
+     * Get or create a Logger instance for the specified source
+     * @param source The source/module identifier
+     * @returns Logger instance
+     */
+    static getLogger(source) {
+        if (!Logger.instances.has(source)) {
+            Logger.instances.set(source, new Logger(source));
+        }
+        return Logger.instances.get(source);
+    }
+    /**
+     * Set the global log level
+     * @param level The log level to set
+     */
+    static setGlobalLevel(level) {
+        Logger.globalLevel = level;
+    }
+    /**
+     * Get the current global log level
+     * @returns The current global log level
+     */
+    static getGlobalLevel() {
+        return Logger.globalLevel;
+    }
+    /**
+     * Enable or disable console output
+     * @param enabled Whether to enable console output
+     */
+    static setConsoleEnabled(enabled) {
+        Logger.consoleEnabled = enabled;
+    }
+    /**
+     * Check if console output is enabled
+     * @returns Whether console output is enabled
+     */
+    static isConsoleEnabled() {
+        return Logger.consoleEnabled;
+    }
+    /**
+     * Add a log handler
+     * @param handler The handler to add
+     */
+    static addHandler(handler) {
+        if (!Logger.handlers.includes(handler)) {
+            Logger.handlers.push(handler);
+        }
+    }
+    /**
+     * Remove a log handler
+     * @param handler The handler to remove
+     * @returns Whether the handler was found and removed
+     */
+    static removeHandler(handler) {
+        const index = Logger.handlers.indexOf(handler);
+        if (index !== -1) {
+            Logger.handlers.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all log handlers
+     */
+    static clearHandlers() {
+        Logger.handlers = [];
+    }
+    /**
+     * Get all registered handlers
+     * @returns Array of registered handlers
+     */
+    static getHandlers() {
+        return Logger.handlers;
+    }
+    /**
+     * Configure the logging system (convenience method)
+     * @param config Log configuration
+     */
+    static configure(config) {
+        if (config.level !== undefined) {
+            Logger.setGlobalLevel(config.level);
+        }
+        if (config.consoleEnabled !== undefined) {
+            Logger.setConsoleEnabled(config.consoleEnabled);
+        }
+        if (config.handlers) {
+            Logger.clearHandlers();
+            config.handlers.forEach((h) => Logger.addHandler(h));
+        }
+    }
+    /**
+     * Reset the logger to default state
+     * Useful for testing
+     */
+    static reset() {
+        Logger.globalLevel = exports.LogLevel.WARN;
+        Logger.consoleEnabled = true;
+        Logger.handlers = [];
+        Logger.instances.clear();
+    }
+    // ===== Instance methods =====
+    /**
+     * Set the log level for this Logger instance
+     * Set to undefined to use the global level
+     * @param level The log level or undefined
+     */
+    setLevel(level) {
+        this.localLevel = level;
+    }
+    /**
+     * Get the effective log level for this Logger
+     * @returns The effective log level
+     */
+    getEffectiveLevel() {
+        var _a;
+        return (_a = this.localLevel) !== null && _a !== void 0 ? _a : Logger.globalLevel;
+    }
+    /**
+     * Log a debug message
+     * @param message The message to log
+     * @param data Additional data to log
+     */
+    debug(message, ...data) {
+        this.log(exports.LogLevel.DEBUG, 'debug', message, data);
+    }
+    /**
+     * Log an info message
+     * @param message The message to log
+     * @param data Additional data to log
+     */
+    info(message, ...data) {
+        this.log(exports.LogLevel.INFO, 'info', message, data);
+    }
+    /**
+     * Log a warning message
+     * @param message The message to log
+     * @param data Additional data to log
+     */
+    warn(message, ...data) {
+        this.log(exports.LogLevel.WARN, 'warn', message, data);
+    }
+    /**
+     * Log an error message
+     * @param message The message to log
+     * @param data Additional data to log
+     */
+    error(message, ...data) {
+        this.log(exports.LogLevel.ERROR, 'error', message, data);
+    }
+    /**
+     * Internal log method
+     */
+    log(level, levelName, message, data) {
+        const effectiveLevel = this.getEffectiveLevel();
+        // Check log level
+        if (level > effectiveLevel) {
+            return;
+        }
+        const entry = {
+            level,
+            levelName,
+            source: this.source,
+            message,
+            data: data.length > 0 ? data : undefined,
+            timestamp: new Date(),
+        };
+        // Output to console
+        if (Logger.consoleEnabled) {
+            this.logToConsole(entry);
+        }
+        // Call all handlers
+        for (const handler of Logger.handlers) {
+            try {
+                handler.handle(entry);
+            }
+            catch (e) {
+                // Prevent handler errors from affecting the logging system
+                if (Logger.consoleEnabled) {
+                    console.error('[Logger] Handler error:', e);
+                }
+            }
+        }
+    }
+    /**
+     * Output to console
+     */
+    logToConsole(entry) {
+        const prefix = `[${entry.source}]`;
+        const args = entry.data ? [prefix, entry.message, ...entry.data] : [prefix, entry.message];
+        switch (entry.levelName) {
+            case 'debug':
+                console.log(...args);
+                break;
+            case 'info':
+                console.info(...args);
+                break;
+            case 'warn':
+                console.warn(...args);
+                break;
+            case 'error':
+                console.error(...args);
+                break;
+        }
+    }
+}
+Logger.globalLevel = exports.LogLevel.WARN;
+Logger.handlers = [];
+Logger.consoleEnabled = true;
+Logger.instances = new Map();
+/**
+ * Buffer log handler
+ * Stores logs in memory for later retrieval
+ */
+class BufferLogHandler {
+    constructor(maxSize = 1000) {
+        this.buffer = [];
+        this.maxSize = maxSize;
+    }
+    handle(entry) {
+        this.buffer.push(entry);
+        // Remove oldest logs when exceeding max size
+        while (this.buffer.length > this.maxSize) {
+            this.buffer.shift();
+        }
+    }
+    /**
+     * Get all buffered logs
+     * @returns Array of log entries
+     */
+    getEntries() {
+        return this.buffer;
+    }
+    /**
+     * Clear the buffer
+     */
+    clear() {
+        this.buffer = [];
+    }
+    /**
+     * Get logs by level
+     * @param level The log level to filter by
+     * @returns Array of matching log entries
+     */
+    getEntriesByLevel(level) {
+        return this.buffer.filter((e) => e.level === level);
+    }
+    /**
+     * Get logs by source
+     * @param source The source to filter by
+     * @returns Array of matching log entries
+     */
+    getEntriesBySource(source) {
+        return this.buffer.filter((e) => e.source === source);
+    }
+}
+/**
+ * Callback log handler
+ * Allows handling logs via a callback function
+ */
+class CallbackLogHandler {
+    constructor(callback) {
+        this.callback = callback;
+    }
+    handle(entry) {
+        this.callback(entry);
+    }
+}
+
+/**
+ * Cross-platform storage abstraction layer
+ * Provides a unified interface for storage operations that works in both
+ * browser and Node.js environments.
+ */
+/**
+ * Browser storage implementation using localStorage
+ */
+class BrowserStorage {
+    getItem(key) {
+        return localStorage.getItem(key);
+    }
+    setItem(key, value) {
+        localStorage.setItem(key, value);
+    }
+    removeItem(key) {
+        localStorage.removeItem(key);
+    }
+    keys() {
+        return Object.keys(localStorage);
+    }
+}
+/**
+ * In-memory storage implementation for server/Node.js environments
+ */
+class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+    }
+    getItem(key) {
+        var _a;
+        return (_a = this.store.get(key)) !== null && _a !== void 0 ? _a : null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+    keys() {
+        return Array.from(this.store.keys());
+    }
+    /**
+     * Clear all items from memory storage
+     */
+    clear() {
+        this.store.clear();
+    }
+}
+/**
+ * Check if localStorage is available in the current environment
+ */
+function isLocalStorageAvailable() {
+    if (typeof localStorage === 'undefined') {
+        return false;
+    }
+    try {
+        const testKey = '__playkit_storage_test__';
+        localStorage.setItem(testKey, 'test');
+        localStorage.removeItem(testKey);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Create a storage instance based on the environment or mode
+ * @param mode - SDK mode ('browser' | 'server')
+ * @param customStorage - Optional custom storage implementation
+ */
+function createStorage(mode = 'browser', customStorage) {
+    // Use custom storage if provided
+    if (customStorage) {
+        return customStorage;
+    }
+    // Server mode always uses memory storage
+    if (mode === 'server') {
+        return new MemoryStorage();
+    }
+    // Browser mode - use localStorage if available, otherwise memory
+    if (isLocalStorageAvailable()) {
+        return new BrowserStorage();
+    }
+    return new MemoryStorage();
+}
+
+/**
+ * Cross-platform cryptographic utilities
+ * Provides unified crypto operations that work in both browser and Node.js environments.
+ */
+/**
+ * Check if we're running in a Node.js environment
+ */
+function isNodeEnvironment() {
+    return typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null;
+}
+/**
+ * Get random bytes - works in both browser and Node.js
+ * @param length - Number of random bytes to generate
+ * @returns Uint8Array of random bytes
+ */
+function getRandomBytes(length) {
+    if (isNodeEnvironment()) {
+        // Node.js environment
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const nodeCrypto = require('crypto');
+        return new Uint8Array(nodeCrypto.randomBytes(length));
+    }
+    else if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        // Browser environment
+        const array = new Uint8Array(length);
+        crypto.getRandomValues(array);
+        return array;
+    }
+    else {
+        throw new Error('No secure random number generator available');
+    }
+}
+/**
+ * Compute SHA-256 hash - works in both browser and Node.js
+ * @param data - Data to hash (Uint8Array or string)
+ * @returns Promise resolving to hash as Uint8Array
+ */
+async function sha256(data) {
+    const inputData = typeof data === 'string' ? textEncode(data) : data;
+    if (isNodeEnvironment()) {
+        // Node.js environment
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const nodeCrypto = require('crypto');
+        const hash = nodeCrypto.createHash('sha256').update(Buffer.from(inputData)).digest();
+        return new Uint8Array(hash);
+    }
+    else if (typeof crypto !== 'undefined' && crypto.subtle) {
+        // Browser environment
+        const hashBuffer = await crypto.subtle.digest('SHA-256', inputData);
+        return new Uint8Array(hashBuffer);
+    }
+    else {
+        throw new Error('No SHA-256 implementation available');
+    }
+}
+/**
+ * Base64 encode binary data - works in both browser and Node.js
+ * @param data - Data to encode (Uint8Array or ArrayBuffer)
+ * @returns Base64 encoded string
+ */
+function base64Encode(data) {
+    const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+    if (isNodeEnvironment()) {
+        // Node.js environment
+        return Buffer.from(bytes).toString('base64');
+    }
+    else if (typeof btoa !== 'undefined') {
+        // Browser environment
+        let binary = '';
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary);
+    }
+    else {
+        throw new Error('No Base64 encoder available');
+    }
+}
+/**
+ * Base64 decode string - works in both browser and Node.js
+ * @param base64 - Base64 encoded string
+ * @returns Decoded data as Uint8Array
+ */
+function base64Decode(base64) {
+    if (isNodeEnvironment()) {
+        // Node.js environment
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    else if (typeof atob !== 'undefined') {
+        // Browser environment
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+    else {
+        throw new Error('No Base64 decoder available');
+    }
+}
+/**
+ * Base64 URL encode - safe for URLs (no +, /, or = characters)
+ * @param data - Data to encode (Uint8Array)
+ * @returns URL-safe Base64 encoded string
+ */
+function base64URLEncode(data) {
+    const base64 = base64Encode(data);
+    return base64
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+}
+/**
+ * Encode text to UTF-8 bytes - works in both browser and Node.js
+ * @param text - Text to encode
+ * @returns UTF-8 encoded bytes as Uint8Array
+ */
+function textEncode(text) {
+    if (typeof TextEncoder !== 'undefined') {
+        // Browser or modern Node.js
+        return new TextEncoder().encode(text);
+    }
+    else if (isNodeEnvironment()) {
+        // Older Node.js
+        return new Uint8Array(Buffer.from(text, 'utf-8'));
+    }
+    else {
+        throw new Error('No text encoder available');
+    }
+}
+/**
+ * Decode UTF-8 bytes to text - works in both browser and Node.js
+ * @param data - UTF-8 encoded bytes (Uint8Array or ArrayBuffer)
+ * @returns Decoded text string
+ */
+function textDecode(data) {
+    const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+    if (typeof TextDecoder !== 'undefined') {
+        // Browser or modern Node.js
+        return new TextDecoder().decode(bytes);
+    }
+    else if (isNodeEnvironment()) {
+        // Older Node.js
+        return Buffer.from(bytes).toString('utf-8');
+    }
+    else {
+        throw new Error('No text decoder available');
+    }
+}
+/**
+ * Check if Web Crypto API is available
+ * @returns true if Web Crypto subtle API is available
+ */
+function isWebCryptoAvailable() {
+    return typeof crypto !== 'undefined' &&
+        crypto.subtle != null;
+}
+
 /**
  * Token storage with encryption using Web Crypto API
- * Stores tokens in localStorage with AES-128-GCM encryption
+ * Stores tokens with AES-128-GCM encryption when available
+ * Works in both browser (localStorage) and server (memory) environments
  */
 const STORAGE_KEY_PREFIX = 'playkit_';
 const ENCRYPTION_KEY_NAME = 'playkit_encryption_key';
 class TokenStorage {
-    constructor() {
+    constructor(options = {}) {
         this.encryptionKey = null;
+        this.logger = Logger.getLogger('TokenStorage');
+        this.storage = options.storage || createStorage(options.mode || 'browser');
     }
     /**
      * Initialize the encryption key
      */
     async initialize() {
-        if (typeof window === 'undefined' || !window.crypto || !window.crypto.subtle) {
-            console.warn('Web Crypto API not available, encryption disabled');
+        // Skip encryption if Web Crypto API is not available
+        if (!isWebCryptoAvailable()) {
+            this.logger.warn('Web Crypto API not available, encryption disabled');
             return;
         }
         // Try to load existing key or generate new one
-        const storedKey = localStorage.getItem(ENCRYPTION_KEY_NAME);
+        const storedKey = this.storage.getItem(ENCRYPTION_KEY_NAME);
         if (storedKey) {
             try {
                 const keyData = this.base64ToArrayBuffer(storedKey);
                 this.encryptionKey = await crypto.subtle.importKey('raw', keyData, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
             }
             catch (error) {
-                console.warn('Failed to import encryption key, generating new one', error);
+                this.logger.warn('Failed to import encryption key, generating new one', error);
                 await this.generateNewKey();
             }
         }
@@ -145,24 +719,24 @@ class TokenStorage {
      * Generate a new encryption key
      */
     async generateNewKey() {
-        if (!crypto.subtle)
+        if (!isWebCryptoAvailable())
             return;
         this.encryptionKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 128 }, true, ['encrypt', 'decrypt']);
         // Store the key
         const exported = await crypto.subtle.exportKey('raw', this.encryptionKey);
-        localStorage.setItem(ENCRYPTION_KEY_NAME, this.arrayBufferToBase64(exported));
+        this.storage.setItem(ENCRYPTION_KEY_NAME, this.arrayBufferToBase64(exported));
     }
     /**
      * Encrypt data
      */
     async encrypt(data) {
-        if (!this.encryptionKey || !crypto.subtle) {
+        if (!this.encryptionKey || !isWebCryptoAvailable()) {
             // Fallback to plain storage if encryption unavailable
             return data;
         }
-        const iv = crypto.getRandomValues(new Uint8Array(12));
-        const encoded = new TextEncoder().encode(data);
-        const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, this.encryptionKey, encoded);
+        const iv = getRandomBytes(12);
+        const encoded = textEncode(data);
+        const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, this.encryptionKey, encoded);
         // Combine IV and encrypted data
         const combined = new Uint8Array(iv.length + encrypted.byteLength);
         combined.set(iv, 0);
@@ -173,7 +747,7 @@ class TokenStorage {
      * Decrypt data
      */
     async decrypt(encryptedData) {
-        if (!this.encryptionKey || !crypto.subtle) {
+        if (!this.encryptionKey || !isWebCryptoAvailable()) {
             // Data not encrypted
             return encryptedData;
         }
@@ -182,10 +756,10 @@ class TokenStorage {
             const iv = combined.slice(0, 12);
             const encrypted = combined.slice(12);
             const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, this.encryptionKey, encrypted);
-            return new TextDecoder().decode(decrypted);
+            return textDecode(decrypted);
         }
         catch (error) {
-            console.error('Decryption failed', error);
+            this.logger.error('Decryption failed', error);
             return encryptedData; // Return original if decryption fails
         }
     }
@@ -196,14 +770,14 @@ class TokenStorage {
         const key = `${STORAGE_KEY_PREFIX}${gameId}_auth`;
         const data = JSON.stringify(authState);
         const encrypted = await this.encrypt(data);
-        localStorage.setItem(key, encrypted);
+        this.storage.setItem(key, encrypted);
     }
     /**
      * Load auth state
      */
     async loadAuthState(gameId) {
         const key = `${STORAGE_KEY_PREFIX}${gameId}_auth`;
-        const encrypted = localStorage.getItem(key);
+        const encrypted = this.storage.getItem(key);
         if (!encrypted)
             return null;
         try {
@@ -211,7 +785,7 @@ class TokenStorage {
             return JSON.parse(decrypted);
         }
         catch (error) {
-            console.error('Failed to load auth state', error);
+            this.logger.error('Failed to load auth state', error);
             return null;
         }
     }
@@ -220,39 +794,38 @@ class TokenStorage {
      */
     clearAuthState(gameId) {
         const key = `${STORAGE_KEY_PREFIX}${gameId}_auth`;
-        localStorage.removeItem(key);
+        this.storage.removeItem(key);
     }
     /**
      * Clear all PlayKit data
      */
     clearAll() {
-        Object.keys(localStorage).forEach((key) => {
+        const keys = this.storage.keys();
+        keys.forEach((key) => {
             if (key.startsWith(STORAGE_KEY_PREFIX)) {
-                localStorage.removeItem(key);
+                this.storage.removeItem(key);
             }
         });
     }
+    /**
+     * Get the underlying storage instance
+     */
+    getStorage() {
+        return this.storage;
+    }
     /**
      * Utility: ArrayBuffer to Base64
      */
     arrayBufferToBase64(buffer) {
-        const bytes = new Uint8Array(buffer);
-        let binary = '';
-        for (let i = 0; i < bytes.byteLength; i++) {
-            binary += String.fromCharCode(bytes[i]);
-        }
-        return btoa(binary);
+        return base64Encode(new Uint8Array(buffer));
     }
     /**
      * Utility: Base64 to ArrayBuffer
      */
     base64ToArrayBuffer(base64) {
-        const binary = atob(base64);
-        const bytes = new Uint8Array(binary.length);
-        for (let i = 0; i < binary.length; i++) {
-            bytes[i] = binary.charCodeAt(i);
-        }
-        return bytes.buffer;
+        const decoded = base64Decode(base64);
+        // Copy to a new ArrayBuffer to ensure proper type
+        return decoded.buffer.slice(decoded.byteOffset, decoded.byteOffset + decoded.byteLength);
     }
 }
 
@@ -1211,6 +1784,7 @@ class DeviceAuthFlowManager extends EventEmitter {
         this.aborted = false;
         this.currentLanguage = 'en';
         this.currentModal = null;
+        this.logger = Logger.getLogger('DeviceAuth');
         this.baseURL = baseURL;
         this.gameId = gameId;
     }
@@ -1219,27 +1793,16 @@ class DeviceAuthFlowManager extends EventEmitter {
      * @private
      */
     generateCodeVerifier() {
-        const array = new Uint8Array(32);
-        crypto.getRandomValues(array);
-        return this.base64URLEncode(array);
+        const array = getRandomBytes(32);
+        return base64URLEncode(array);
     }
     /**
      * Generate PKCE code challenge from verifier
      * @private
      */
     async generateCodeChallenge(verifier) {
-        const encoder = new TextEncoder();
-        const data = encoder.encode(verifier);
-        const hash = await crypto.subtle.digest('SHA-256', data);
-        return this.base64URLEncode(new Uint8Array(hash));
-    }
-    /**
-     * Base64 URL encode
-     * @private
-     */
-    base64URLEncode(buffer) {
-        const base64 = btoa(String.fromCharCode(...buffer));
-        return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+        const hash = await sha256(verifier);
+        return base64URLEncode(hash);
     }
     /**
      * Detect browser language and return matching translation key
@@ -1486,7 +2049,7 @@ class DeviceAuthFlowManager extends EventEmitter {
         }
         else {
             // In Node.js, we can't open browser by default
-            console.log('Please open this URL in your browser:', url);
+            this.logger.info('Please open this URL in your browser:', url);
         }
     }
     /**
@@ -1646,7 +2209,7 @@ class DeviceAuthFlowManager extends EventEmitter {
                 }
                 catch (err) {
                     // Network error, retry after interval
-                    console.warn('[DeviceAuth] Poll network error, retrying...', err);
+                    this.logger.warn('Poll network error, retrying...', err);
                     this.pollTimeoutId = setTimeout(poll, this.pollInterval);
                 }
             };
@@ -1814,7 +2377,7 @@ class DeviceAuthFlowManager extends EventEmitter {
                 }
                 catch (err) {
                     // Network error, retry after interval
-                    console.warn('[DeviceAuth] Poll network error, retrying...', err);
+                    this.logger.warn('Poll network error, retrying...', err);
                     this.pollTimeoutId = setTimeout(poll, pollIntervalMs);
                 }
             };
@@ -1831,13 +2394,18 @@ class DeviceAuthFlowManager extends EventEmitter {
 // @ts-ignore - replaced at build time
 const DEFAULT_BASE_URL$5 = "https://api.playkit.ai";
 const JWT_EXCHANGE_ENDPOINT = '/api/external/exchange-jwt';
+const TOKEN_REFRESH_ENDPOINT = '/api/auth/refresh';
 class AuthManager extends EventEmitter {
     constructor(config) {
         super();
         this.authFlowManager = null;
         this.deviceAuthFlowManager = null;
+        this.logger = Logger.getLogger('AuthManager');
         this.config = config;
-        this.storage = new TokenStorage();
+        // Create TokenStorage with appropriate mode for server vs browser environment
+        this.storage = new TokenStorage({
+            mode: config.mode === 'server' ? 'server' : 'browser',
+        });
         this.baseURL = config.baseURL || DEFAULT_BASE_URL$5;
         this.authState = {
             isAuthenticated: false,
@@ -1878,6 +2446,21 @@ class AuthManager extends EventEmitter {
                 this.emit('authenticated', this.authState);
                 return;
             }
+            // Token expired, but check if we can refresh (browser mode only)
+            if (this.config.mode !== 'server' &&
+                savedState.refreshToken &&
+                (!savedState.refreshExpiresAt || Date.now() < savedState.refreshExpiresAt)) {
+                this.logger.debug('Access token expired, attempting refresh');
+                this.authState = savedState; // Load state with refresh token
+                try {
+                    await this.refreshToken();
+                    return; // Successfully refreshed
+                }
+                catch (error) {
+                    this.logger.warn('Token refresh failed during initialization', error);
+                    // Continue to re-authentication
+                }
+            }
         }
         // Check if player JWT was provided
         if (this.config.playerJWT) {
@@ -1917,7 +2500,7 @@ class AuthManager extends EventEmitter {
         }
         // Deprecation warning for headless auth
         if (authMethod === 'headless') {
-            console.warn('[PlayKit] "headless" authentication is deprecated and will be removed in v2.0. ' +
+            this.logger.warn('"headless" authentication is deprecated and will be removed in v2.0. ' +
                 'Please migrate to "device" authentication.');
         }
         try {
@@ -1927,12 +2510,14 @@ class AuthManager extends EventEmitter {
                 const result = await this.deviceAuthFlowManager.startFlow({
                     scope: 'player:play',
                 });
-                // Update auth state with the player token
+                // Update auth state with the player token and refresh token
                 this.authState = {
                     isAuthenticated: true,
                     token: result.access_token,
                     tokenType: 'player',
                     expiresAt: Date.now() + result.expires_in * 1000,
+                    refreshToken: result.refresh_token,
+                    refreshExpiresAt: Date.now() + result.refresh_expires_in * 1000,
                 };
                 // Save to storage
                 await this.storage.saveAuthState(this.config.gameId, this.authState);
@@ -2031,6 +2616,58 @@ class AuthManager extends EventEmitter {
             return false;
         return Date.now() >= this.authState.expiresAt;
     }
+    /**
+     * Check if token is about to expire (within threshold)
+     * @param thresholdMs - Threshold in milliseconds (default: 5 minutes)
+     */
+    isTokenExpiringSoon(thresholdMs = 5 * 60 * 1000) {
+        if (!this.authState.expiresAt)
+            return false;
+        return Date.now() >= this.authState.expiresAt - thresholdMs;
+    }
+    /**
+     * Ensure the access token is valid, refreshing if needed (browser mode only).
+     * Call this before making API requests to automatically handle token refresh.
+     *
+     * In server mode, this method does nothing (tokens should be managed externally).
+     *
+     * @param thresholdMs - Refresh if token expires within this time (default: 5 minutes)
+     * @returns Promise that resolves when token is valid
+     * @throws PlayKitError if token cannot be refreshed and is expired
+     */
+    async ensureValidToken(thresholdMs = 5 * 60 * 1000) {
+        // Skip auto-refresh in server mode
+        if (this.config.mode === 'server') {
+            return;
+        }
+        // Skip if not authenticated
+        if (!this.authState.isAuthenticated || !this.authState.token) {
+            return;
+        }
+        // Check if token needs refresh
+        if (!this.isTokenExpiringSoon(thresholdMs)) {
+            return; // Token is still valid
+        }
+        // Try to refresh if possible
+        if (this.canRefresh()) {
+            this.logger.debug('Token expiring soon, refreshing automatically');
+            try {
+                await this.refreshToken();
+            }
+            catch (error) {
+                this.logger.warn('Auto-refresh failed', error);
+                // If refresh fails and token is already expired, throw
+                if (this.isTokenExpired()) {
+                    throw error;
+                }
+                // Otherwise, continue with potentially expired token
+            }
+        }
+        else if (this.isTokenExpired()) {
+            // Token expired and cannot refresh
+            throw new PlayKitError('Access token has expired and no refresh token is available', 'TOKEN_EXPIRED');
+        }
+    }
     /**
      * Logout and clear authentication
      */
@@ -2072,12 +2709,14 @@ class AuthManager extends EventEmitter {
         try {
             this.deviceAuthFlowManager = new DeviceAuthFlowManager(this.baseURL, this.config.gameId);
             const result = await this.deviceAuthFlowManager.startFlow(options);
-            // Update auth state with the token
+            // Update auth state with the token and refresh token
             this.authState = {
                 isAuthenticated: true,
                 token: result.access_token,
                 tokenType: result.scope === 'developer:full' ? 'developer' : 'player',
                 expiresAt: Date.now() + result.expires_in * 1000,
+                refreshToken: result.refresh_token,
+                refreshExpiresAt: Date.now() + result.refresh_expires_in * 1000,
             };
             // Save to storage
             await this.storage.saveAuthState(this.config.gameId, this.authState);
@@ -2140,12 +2779,14 @@ class AuthManager extends EventEmitter {
         }
         try {
             const result = await this.deviceAuthFlowManager.pollForToken(sessionId, codeVerifier, options);
-            // Update auth state with the token
+            // Update auth state with the token and refresh token
             this.authState = {
                 isAuthenticated: true,
                 token: result.access_token,
                 tokenType: result.scope === 'developer:full' ? 'developer' : 'player',
                 expiresAt: Date.now() + result.expires_in * 1000,
+                refreshToken: result.refresh_token,
+                refreshExpiresAt: Date.now() + result.refresh_expires_in * 1000,
             };
             // Save to storage
             await this.storage.saveAuthState(this.config.gameId, this.authState);
@@ -2158,6 +2799,91 @@ class AuthManager extends EventEmitter {
             this.deviceAuthFlowManager = null;
         }
     }
+    /**
+     * Check if the current session can be refreshed
+     * @returns true if a valid refresh token exists and has not expired
+     */
+    canRefresh() {
+        if (!this.authState.refreshToken)
+            return false;
+        if (!this.authState.refreshExpiresAt)
+            return true; // No expiry info, assume valid
+        return Date.now() < this.authState.refreshExpiresAt;
+    }
+    /**
+     * Refresh the access token using the stored refresh token
+     *
+     * @returns Promise resolving to TokenRefreshResult with new tokens
+     * @throws PlayKitError if no refresh token is available or refresh fails
+     *
+     * @example
+     * ```ts
+     * if (sdk.isTokenExpired() && authManager.canRefresh()) {
+     *   const result = await authManager.refreshToken();
+     *   console.log('New token expires in:', result.expiresIn, 'seconds');
+     * }
+     * ```
+     */
+    async refreshToken() {
+        if (!this.authState.refreshToken) {
+            throw new PlayKitError('No refresh token available. Please re-authenticate.', 'NO_REFRESH_TOKEN');
+        }
+        if (this.authState.refreshExpiresAt && Date.now() >= this.authState.refreshExpiresAt) {
+            throw new PlayKitError('Refresh token has expired. Please re-authenticate.', 'REFRESH_TOKEN_EXPIRED');
+        }
+        try {
+            this.logger.debug('Refreshing access token');
+            const response = await fetch(`${this.baseURL}${TOKEN_REFRESH_ENDPOINT}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    refresh_token: this.authState.refreshToken,
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error_description: 'Token refresh failed' }));
+                // If refresh token is invalid, clear auth state
+                if (response.status === 401) {
+                    this.logger.warn('Refresh token invalid, clearing auth state');
+                    await this.logout();
+                    throw new PlayKitError(error.error_description || 'Refresh token is invalid or expired', 'REFRESH_TOKEN_INVALID', response.status);
+                }
+                throw new PlayKitError(error.error_description || 'Token refresh failed', error.error || 'REFRESH_FAILED', response.status);
+            }
+            const data = await response.json();
+            // Update auth state with new tokens
+            this.authState = {
+                isAuthenticated: true,
+                token: data.access_token,
+                tokenType: data.scope === 'developer:full' ? 'developer' : 'player',
+                expiresAt: Date.now() + data.expires_in * 1000,
+                refreshToken: data.refresh_token,
+                refreshExpiresAt: Date.now() + data.refresh_expires_in * 1000,
+            };
+            // Save to storage
+            await this.storage.saveAuthState(this.config.gameId, this.authState);
+            this.logger.info('Access token refreshed successfully');
+            this.emit('authenticated', this.authState);
+            this.emit('token_refreshed', this.authState);
+            return {
+                accessToken: data.access_token,
+                tokenType: data.token_type,
+                expiresIn: data.expires_in,
+                refreshToken: data.refresh_token,
+                refreshExpiresIn: data.refresh_expires_in,
+                scope: data.scope,
+            };
+        }
+        catch (error) {
+            if (error instanceof PlayKitError) {
+                throw error;
+            }
+            this.logger.error('Token refresh failed', error);
+            throw new PlayKitError('Token refresh failed due to network error', 'REFRESH_NETWORK_ERROR');
+        }
+    }
 }
 
 /**
@@ -2229,6 +2955,10 @@ class RechargeManager extends EventEmitter {
      * Detect user's preferred language
      */
     detectLanguage() {
+        // Return default language if navigator is not available (server environment)
+        if (typeof navigator === 'undefined') {
+            return 'en';
+        }
         const browserLang = navigator.language.toLowerCase();
         if (browserLang.startsWith('zh-tw') || browserLang.startsWith('zh-hk')) {
             return 'zh-TW';
@@ -2701,6 +3431,7 @@ class PlayerClient extends EventEmitter {
         this.playerInfo = null;
         this.rechargeManager = null;
         this.balanceCheckInterval = null;
+        this.logger = Logger.getLogger('PlayerClient');
         this.authManager = authManager;
         this.baseURL = config.baseURL || DEFAULT_BASE_URL$4;
         this.gameId = config.gameId;
@@ -2877,7 +3608,7 @@ class PlayerClient extends EventEmitter {
         var _a;
         this.initializeRechargeManager();
         if (!this.rechargeManager) {
-            console.warn('RechargeManager not initialized. Cannot show modal.');
+            this.logger.warn('RechargeManager not initialized. Cannot show modal.');
             return;
         }
         const balance = (_a = this.playerInfo) === null || _a === void 0 ? void 0 : _a.credits;
@@ -2892,7 +3623,7 @@ class PlayerClient extends EventEmitter {
     openRechargeWindow() {
         this.initializeRechargeManager();
         if (!this.rechargeManager) {
-            console.warn('RechargeManager not initialized. Cannot open recharge window.');
+            this.logger.warn('RechargeManager not initialized. Cannot open recharge window.');
             return;
         }
         this.rechargeManager.openRechargeWindow();
@@ -2927,7 +3658,7 @@ class PlayerClient extends EventEmitter {
             }
             catch (error) {
                 // Silently fail periodic checks to avoid spamming errors
-                console.debug('Failed to check balance:', error);
+                this.logger.debug('Failed to check balance:', error);
             }
         }, interval);
     }
@@ -2952,7 +3683,7 @@ class PlayerClient extends EventEmitter {
         }
         catch (error) {
             // Silently fail to avoid disrupting the main flow
-            console.debug('Failed to check balance after API call:', error);
+            this.logger.debug('Failed to check balance after API call:', error);
         }
     }
     /**
@@ -3006,6 +3737,8 @@ class ChatProvider {
      */
     async chatCompletion(chatConfig) {
         var _a;
+        // Ensure token is valid, auto-refresh if needed (browser mode only)
+        await this.authManager.ensureValidToken();
         const token = this.authManager.getToken();
         if (!token) {
             throw new PlayKitError('Not authenticated', 'NOT_AUTHENTICATED');
@@ -3063,6 +3796,8 @@ class ChatProvider {
      */
     async chatCompletionStream(chatConfig) {
         var _a;
+        // Ensure token is valid, auto-refresh if needed (browser mode only)
+        await this.authManager.ensureValidToken();
         const token = this.authManager.getToken();
         if (!token) {
             throw new PlayKitError('Not authenticated', 'NOT_AUTHENTICATED');
@@ -3251,6 +3986,8 @@ class ChatProvider {
      */
     async generateStructured(schemaName, prompt, model, temperature, schema, schemaDescription) {
         var _a;
+        // Ensure token is valid, auto-refresh if needed (browser mode only)
+        await this.authManager.ensureValidToken();
         const token = this.authManager.getToken();
         if (!token) {
             throw new PlayKitError('Not authenticated', 'NOT_AUTHENTICATED');
@@ -3340,6 +4077,8 @@ class ImageProvider {
      * Generate one or more images
      */
     async generateImages(imageConfig) {
+        // Ensure token is valid, auto-refresh if needed (browser mode only)
+        await this.authManager.ensureValidToken();
         const token = this.authManager.getToken();
         if (!token) {
             throw new PlayKitError('Not authenticated', 'NOT_AUTHENTICATED');
@@ -3451,6 +4190,8 @@ class TranscriptionProvider {
      * Transcribe audio to text
      */
     async transcribe(transcriptionConfig) {
+        // Ensure token is valid, auto-refresh if needed (browser mode only)
+        await this.authManager.ensureValidToken();
         const token = this.authManager.getToken();
         if (!token) {
             throw new PlayKitError('Not authenticated', 'NOT_AUTHENTICATED');
@@ -3575,13 +4316,25 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
  * Server-Sent Events (SSE) stream parser
  * Handles parsing of streaming text responses
  */
+/**
+ * Create a cross-platform text decoder
+ */
+function createDecoder() {
+    if (typeof TextDecoder !== 'undefined') {
+        return new TextDecoder();
+    }
+    // Fallback for environments without TextDecoder
+    return {
+        decode: (data, _options) => textDecode(data),
+    };
+}
 class StreamParser {
     /**
      * Parse SSE stream using ReadableStream
      */
     static parseStream(reader) {
         return __asyncGenerator(this, arguments, function* parseStream_1() {
-            const decoder = new TextDecoder();
+            const decoder = createDecoder();
             let buffer = '';
             try {
                 while (true) {
@@ -4155,6 +4908,7 @@ class NPCClient extends EventEmitter {
         var _a, _b, _c;
         super();
         this._isTalking = false;
+        this.logger = Logger.getLogger('NPCClient');
         this.chatClient = chatClient;
         // Support both characterDesign and legacy systemPrompt
         this.characterDesign = (config === null || config === void 0 ? void 0 : config.characterDesign) || (config === null || config === void 0 ? void 0 : config.systemPrompt) || 'You are a helpful assistant.';
@@ -4192,7 +4946,7 @@ class NPCClient extends EventEmitter {
      * This method is kept for backwards compatibility.
      */
     setSystemPrompt(prompt) {
-        console.warn('[NPCClient] setSystemPrompt is deprecated. Use setCharacterDesign instead.');
+        this.logger.warn('setSystemPrompt is deprecated. Use setCharacterDesign instead.');
         this.setCharacterDesign(prompt);
     }
     /**
@@ -4211,7 +4965,7 @@ class NPCClient extends EventEmitter {
      */
     setMemory(memoryName, memoryContent) {
         if (!memoryName) {
-            console.warn('[NPCClient] Memory name cannot be empty');
+            this.logger.warn('Memory name cannot be empty');
             return;
         }
         if (!memoryContent) {
@@ -4287,7 +5041,7 @@ class NPCClient extends EventEmitter {
         var _a;
         const predictionNum = count !== null && count !== void 0 ? count : this.predictionCount;
         if (this.history.length < 2) {
-            console.log('[NPCClient] Not enough conversation history to generate predictions');
+            this.logger.info('Not enough conversation history to generate predictions');
             return [];
         }
         try {
@@ -4296,7 +5050,7 @@ class NPCClient extends EventEmitter {
                 .reverse()
                 .find(m => m.role === 'assistant')) === null || _a === void 0 ? void 0 : _a.content;
             if (!lastNpcMessage) {
-                console.log('[NPCClient] No NPC message found to generate predictions from');
+                this.logger.info('No NPC message found to generate predictions from');
                 return [];
             }
             // Build recent history (last 6 non-system messages)
@@ -4328,7 +5082,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
                 model: this.fastModel,
             });
             if (!result.content) {
-                console.warn('[NPCClient] Failed to generate predictions: empty response');
+                this.logger.warn('Failed to generate predictions: empty response');
                 return [];
             }
             // Parse JSON response
@@ -4339,7 +5093,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
             return predictions;
         }
         catch (error) {
-            console.error('[NPCClient] Error generating predictions:', error);
+            this.logger.error('Error generating predictions:', error);
             return [];
         }
     }
@@ -4352,7 +5106,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
             const startIndex = response.indexOf('[');
             const endIndex = response.lastIndexOf(']');
             if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
-                console.warn('[NPCClient] Could not find JSON array in prediction response');
+                this.logger.warn('Could not find JSON array in prediction response');
                 return this.extractPredictionsFromText(response, expectedCount);
             }
             const jsonArray = response.substring(startIndex, endIndex + 1);
@@ -4365,7 +5119,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
             return [];
         }
         catch (error) {
-            console.warn('[NPCClient] Failed to parse predictions JSON:', error);
+            this.logger.warn('Failed to parse predictions JSON:', error);
             return this.extractPredictionsFromText(response, expectedCount);
         }
     }
@@ -4409,7 +5163,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
             return;
         // Fire and forget - don't block the main response
         this.generateReplyPredictions().catch(err => {
-            console.error('[NPCClient] Background prediction generation failed:', err);
+            this.logger.error('Background prediction generation failed:', err);
         });
     }
     // ===== Main API - Talk Methods =====
@@ -4491,7 +5245,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
      * @deprecated Use talkWithActions instead for NPC decision-making with actions
      */
     async talkStructured(message, schemaName) {
-        console.warn('[NPCClient] talkStructured is deprecated. Use talkWithActions instead for NPC decision-making with actions.');
+        this.logger.warn('talkStructured is deprecated. Use talkWithActions instead for NPC decision-making with actions.');
         // Add user message to history
         const userMessage = { role: 'user', content: message };
         this.history.push(userMessage);
@@ -4762,7 +5516,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
      */
     appendChatMessage(role, content) {
         if (!role || !content) {
-            console.warn('[NPCClient] Role and content cannot be empty');
+            this.logger.warn('Role and content cannot be empty');
             return;
         }
         this.appendMessage({ role: role, content });
@@ -4813,7 +5567,7 @@ Output ONLY a JSON array of ${predictionNum} strings, nothing else:
             return true;
         }
         catch (error) {
-            console.error('[NPCClient] Failed to load history:', error);
+            this.logger.error('Failed to load history:', error);
             return false;
         }
     }
@@ -4839,6 +5593,7 @@ class AIContextManager extends EventEmitter {
         this.npcStates = new Map();
         this.autoCompactTimer = null;
         this.chatClientFactory = null;
+        this.logger = Logger.getLogger('AIContextManager');
         this.config = {
             enableAutoCompact: (_a = config === null || config === void 0 ? void 0 : config.enableAutoCompact) !== null && _a !== void 0 ? _a : false,
             autoCompactMinMessages: (_b = config === null || config === void 0 ? void 0 : config.autoCompactMinMessages) !== null && _b !== void 0 ? _b : 20,
@@ -5005,21 +5760,21 @@ class AIContextManager extends EventEmitter {
      */
     async compactConversation(npc) {
         if (!npc) {
-            console.warn('[AIContextManager] Cannot compact: NPC is null');
+            this.logger.warn('Cannot compact: NPC is null');
             return false;
         }
         if (!this.chatClientFactory) {
-            console.error('[AIContextManager] Cannot compact: No chat client factory set. Call setChatClientFactory() first.');
+            this.logger.error('Cannot compact: No chat client factory set. Call setChatClientFactory() first.');
             return false;
         }
         const history = npc.getHistory();
         const nonSystemMessages = history.filter(m => m.role !== 'system');
         if (nonSystemMessages.length < 2) {
-            console.log('[AIContextManager] Skipping compaction: not enough messages');
+            this.logger.info('Skipping compaction: not enough messages');
             return false;
         }
         try {
-            console.log(`[AIContextManager] Starting compaction (${nonSystemMessages.length} messages)`);
+            this.logger.info(`Starting compaction (${nonSystemMessages.length} messages)`);
             // Build conversation text for summarization
             const conversationText = nonSystemMessages
                 .map(m => `${m.role}: ${m.content}`)
@@ -5044,7 +5799,7 @@ ${conversationText}`;
             });
             if (!result.content) {
                 const error = 'Empty response from summarization';
-                console.error(`[AIContextManager] Compaction failed: ${error}`);
+                this.logger.error(`Compaction failed: ${error}`);
                 this.emit('compactionFailed', npc, error);
                 return false;
             }
@@ -5057,13 +5812,13 @@ ${conversationText}`;
                 state.isCompacted = true;
                 state.compactionCount++;
             }
-            console.log(`[AIContextManager] Compaction completed. Summary: ${result.content.substring(0, 100)}...`);
+            this.logger.info(`Compaction completed. Summary: ${result.content.substring(0, 100)}...`);
             this.emit('npcCompacted', npc);
             return true;
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            console.error(`[AIContextManager] Compaction error: ${errorMessage}`);
+            this.logger.error(`Compaction error: ${errorMessage}`);
             this.emit('compactionFailed', npc, errorMessage);
             return false;
         }
@@ -5077,7 +5832,7 @@ ${conversationText}`;
         if (eligibleNpcs.length === 0) {
             return 0;
         }
-        console.log(`[AIContextManager] Compacting ${eligibleNpcs.length} eligible NPCs`);
+        this.logger.info(`Compacting ${eligibleNpcs.length} eligible NPCs`);
         let successCount = 0;
         for (const npc of eligibleNpcs) {
             const success = await this.compactConversation(npc);
@@ -5117,7 +5872,7 @@ ${conversationText}`;
         for (const npc of eligibleNpcs) {
             // Fire and forget - don't block
             this.compactConversation(npc).catch(err => {
-                console.error('[AIContextManager] Auto-compact error:', err);
+                this.logger.error('Auto-compact error:', err);
             });
         }
     }
@@ -5164,6 +5919,7 @@ const defaultContextManager = AIContextManager.getInstance();
 class SchemaLibrary {
     constructor(initialSchemas) {
         this.schemas = new Map();
+        this.logger = Logger.getLogger('SchemaLibrary');
         if (initialSchemas) {
             for (const entry of initialSchemas) {
                 this.addSchema(entry);
@@ -5183,7 +5939,7 @@ class SchemaLibrary {
             throw new Error(`[SchemaLibrary] Schema '${entry.name}' must have a schema definition`);
         }
         if (this.schemas.has(entry.name)) {
-            console.warn(`[SchemaLibrary] Schema '${entry.name}' already exists, overwriting`);
+            this.logger.warn(`Schema '${entry.name}' already exists, overwriting`);
         }
         // Validate JSON schema structure
         if (!this.isValidSchema(entry.schema)) {
@@ -5351,6 +6107,9 @@ class PlayKitSDK extends EventEmitter {
         this.initialized = false;
         this.devTokenIndicator = null;
         this.config = Object.assign({ defaultChatModel: 'gpt-4o-mini', defaultImageModel: 'dall-e-3', debug: false }, config);
+        // Initialize logging system
+        this.initializeLogging(this.config);
+        this.logger = Logger.getLogger('PlayKitSDK');
         // Initialize managers and providers
         this.authManager = new AuthManager(this.config);
         this.playerClient = new PlayerClient(this.authManager, this.config, this.config.recharge);
@@ -5370,21 +6129,19 @@ class PlayKitSDK extends EventEmitter {
         // Forward authentication events
         this.authManager.on('authenticated', (authState) => {
             this.emit('authenticated', authState);
-            if (this.config.debug) {
-                console.log('[PlayKitSDK] Authenticated', authState);
-            }
+            this.logger.debug('Authenticated', authState);
         });
         this.authManager.on('unauthenticated', () => {
             this.emit('unauthenticated');
-            if (this.config.debug) {
-                console.log('[PlayKitSDK] Not authenticated');
-            }
+            this.logger.debug('Not authenticated');
         });
         this.authManager.on('error', (error) => {
             this.emit('error', error);
-            if (this.config.debug) {
-                console.error('[PlayKitSDK] Auth error', error);
-            }
+            this.logger.error('Auth error', error);
+        });
+        this.authManager.on('token_refreshed', (authState) => {
+            this.emit('token_refreshed', authState);
+            this.logger.debug('Token refreshed', authState);
         });
         // Forward recharge events
         this.playerClient.on('recharge_opened', () => this.emit('recharge_opened'));
@@ -5402,9 +6159,7 @@ class PlayKitSDK extends EventEmitter {
      */
     async initialize() {
         if (this.initialized) {
-            if (this.config.debug) {
-                console.warn('[PlayKitSDK] Already initialized');
-            }
+            this.logger.warn('Already initialized');
             return;
         }
         try {
@@ -5418,28 +6173,20 @@ class PlayKitSDK extends EventEmitter {
             if (this.authManager.isAuthenticated()) {
                 try {
                     await this.playerClient.getPlayerInfo();
-                    if (this.config.debug) {
-                        console.log('[PlayKitSDK] Token validated and user info fetched');
-                    }
+                    this.logger.debug('Token validated and user info fetched');
                 }
                 catch (error) {
                     // If token is invalid, logout and restart auth flow
-                    if (this.config.debug) {
-                        console.error('[PlayKitSDK] Token validation failed:', error);
-                    }
+                    this.logger.error('Token validation failed:', error);
                     await this.authManager.logout();
                     // Auto-restart login flow in browser environment
                     if (typeof window !== 'undefined') {
-                        if (this.config.debug) {
-                            console.log('[PlayKitSDK] Restarting authentication flow...');
-                        }
+                        this.logger.debug('Restarting authentication flow...');
                         const authMethod = this.config.authMethod || 'device';
                         await this.authManager.startAuthFlow(authMethod);
                         // Retry getting player info after re-authentication
                         await this.playerClient.getPlayerInfo();
-                        if (this.config.debug) {
-                            console.log('[PlayKitSDK] Re-authentication successful, token validated');
-                        }
+                        this.logger.debug('Re-authentication successful, token validated');
                     }
                     else {
                         throw new Error('Token validation failed: ' + (error instanceof Error ? error.message : String(error)));
@@ -5447,9 +6194,7 @@ class PlayKitSDK extends EventEmitter {
                 }
             }
             this.emit('ready');
-            if (this.config.debug) {
-                console.log('[PlayKitSDK] Initialized successfully');
-            }
+            this.logger.debug('Initialized successfully');
         }
         catch (error) {
             this.emit('error', error);
@@ -5512,15 +6257,11 @@ class PlayKitSDK extends EventEmitter {
         // Verify token validity and fetch user info
         try {
             await this.playerClient.getPlayerInfo();
-            if (this.config.debug) {
-                console.log('[PlayKitSDK] Login successful, token validated and user info fetched');
-            }
+            this.logger.debug('Login successful, token validated and user info fetched');
         }
         catch (error) {
             // If token is invalid, logout and re-throw error
-            if (this.config.debug) {
-                console.error('[PlayKitSDK] Token validation failed after login:', error);
-            }
+            this.logger.error('Token validation failed after login:', error);
             await this.authManager.logout();
             throw new Error('Token validation failed: ' + (error instanceof Error ? error.message : String(error)));
         }
@@ -5628,9 +6369,38 @@ class PlayKitSDK extends EventEmitter {
     }
     /**
      * Enable or disable debug mode
+     * @deprecated Use configureLogging() instead
      */
     setDebug(enabled) {
         this.config.debug = enabled;
+        Logger.setGlobalLevel(enabled ? exports.LogLevel.DEBUG : exports.LogLevel.WARN);
+    }
+    /**
+     * Configure the logging system
+     * @param config Logging configuration
+     */
+    configureLogging(config) {
+        Logger.configure(config);
+    }
+    /**
+     * Get a logger instance for external use
+     * @param source The source/module identifier
+     */
+    static getLogger(source) {
+        return Logger.getLogger(source);
+    }
+    /**
+     * Initialize logging system based on config
+     */
+    initializeLogging(config) {
+        // Handle legacy debug option for backwards compatibility
+        if (config.debug !== undefined && config.logging === undefined) {
+            Logger.setGlobalLevel(config.debug ? exports.LogLevel.DEBUG : exports.LogLevel.WARN);
+        }
+        // Apply new logging config
+        if (config.logging) {
+            Logger.configure(config.logging);
+        }
     }
     /**
      * Show insufficient balance modal
@@ -5720,6 +6490,45 @@ class PlayKitSDK extends EventEmitter {
     cancelLogin() {
         this.authManager.cancelDeviceAuthFlow();
     }
+    // ============================================================
+    // Token Refresh Methods
+    // ============================================================
+    /**
+     * Check if the current token is expired
+     */
+    isTokenExpired() {
+        return this.authManager.isTokenExpired();
+    }
+    /**
+     * Check if the access token can be refreshed
+     * @returns true if a valid refresh token exists
+     */
+    canRefreshToken() {
+        return this.authManager.canRefresh();
+    }
+    /**
+     * Manually refresh the access token using the stored refresh token.
+     *
+     * Note: In browser mode, token refresh is handled automatically before API calls.
+     * This method is useful for:
+     * - Proactively refreshing tokens before they expire
+     * - Server-side applications managing their own token lifecycle
+     *
+     * @returns Promise resolving to TokenRefreshResult with new tokens
+     * @throws PlayKitError if no refresh token is available or refresh fails
+     *
+     * @example
+     * ```ts
+     * // Manual refresh before a long operation
+     * if (sdk.isTokenExpired() && sdk.canRefreshToken()) {
+     *   const result = await sdk.refreshToken();
+     *   console.log('Token refreshed, expires in:', result.expiresIn, 'seconds');
+     * }
+     * ```
+     */
+    async refreshToken() {
+        return this.authManager.refreshToken();
+    }
 }
 
 /**
@@ -5868,9 +6677,14 @@ const defaultTokenValidator = new TokenValidator();
 exports.AIContextManager = AIContextManager;
 exports.AuthFlowManager = AuthFlowManager;
 exports.AuthManager = AuthManager;
+exports.BrowserStorage = BrowserStorage;
+exports.BufferLogHandler = BufferLogHandler;
+exports.CallbackLogHandler = CallbackLogHandler;
 exports.ChatClient = ChatClient;
 exports.DeviceAuthFlowManager = DeviceAuthFlowManager;
 exports.ImageClient = ImageClient;
+exports.Logger = Logger;
+exports.MemoryStorage = MemoryStorage;
 exports.NPCClient = NPCClient;
 exports.PlayKitSDK = PlayKitSDK;
 exports.PlayerClient = PlayerClient;
@@ -5881,9 +6695,11 @@ exports.TokenStorage = TokenStorage;
 exports.TokenValidator = TokenValidator;
 exports.TranscriptionClient = TranscriptionClient;
 exports.createMultimodalMessage = createMultimodalMessage;
+exports.createStorage = createStorage;
 exports.createTextMessage = createTextMessage;
 exports.default = PlayKitSDK;
 exports.defaultContextManager = defaultContextManager;
 exports.defaultSchemaLibrary = defaultSchemaLibrary;
 exports.defaultTokenValidator = defaultTokenValidator;
+exports.isLocalStorageAvailable = isLocalStorageAvailable;
 //# sourceMappingURL=playkit-sdk.cjs.js.map