wolves-js-client 1.0.3 → 1.0.5

package/dist/EventLogger.d.ts

@@ -8,6 +8,7 @@ export declare class EventLogger {
     constructor(network: Network);
     enqueue(event: WolvesEvent): void;
     flush(): Promise<void>;
-    private start;
+    start(): void;
+    reset(): void;
     stop(): Promise<void>;
 }

package/dist/EventLogger.js

@@ -58,6 +58,9 @@ class EventLogger {
             this.flush();
         }, DEFAULT_FLUSH_INTERVAL_MS);
     }
+    reset() {
+        this.queue = [];
+    }
     stop() {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.flushIntervalId) {

package/dist/StorageProvider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Interface for storage providers that can persist data.
+ * Supports both synchronous and asynchronous storage implementations.
+ */
+export interface StorageProvider {
+    isReady: () => boolean;
+    isReadyResolver: () => Promise<void> | null;
+    getProviderName: () => string;
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+    getAllKeys: () => readonly string[];
+}
+interface StorageProviderManagement {
+    _setProvider: (newProvider: StorageProvider) => void;
+    _setDisabled: (isDisabled: boolean) => void;
+}
+/**
+ * Global storage singleton that automatically chooses between localStorage (browser)
+ * and in-memory storage (Node.js or when localStorage is unavailable).
+ */
+export declare const Storage: StorageProvider & StorageProviderManagement;
+/**
+ * Helper to get a parsed object from storage.
+ */
+export declare function _getObjectFromStorage<T>(key: string): T | null;
+/**
+ * Helper to set an object in storage as JSON string.
+ */
+export declare function _setObjectInStorage(key: string, obj: unknown): void;
+/**
+ * Clear the in-memory store (useful for testing).
+ */
+export declare function _clearInMemoryStore(): void;
+export {};

package/dist/StorageProvider.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Storage = void 0;
+exports._getObjectFromStorage = _getObjectFromStorage;
+exports._setObjectInStorage = _setObjectInStorage;
+exports._clearInMemoryStore = _clearInMemoryStore;
+const Log_1 = require("./Log");
+const inMemoryStore = {};
+/**
+ * In-memory storage provider for non-browser environments or when localStorage is unavailable.
+ */
+const _inMemoryProvider = {
+    isReady: () => true,
+    isReadyResolver: () => null,
+    getProviderName: () => 'InMemory',
+    getItem: (key) => inMemoryStore[key] ? inMemoryStore[key] : null,
+    setItem: (key, value) => {
+        inMemoryStore[key] = value;
+    },
+    removeItem: (key) => {
+        delete inMemoryStore[key];
+    },
+    getAllKeys: () => Object.keys(inMemoryStore),
+};
+/**
+ * Helper function to safely get window object.
+ */
+function _getWindowSafe() {
+    try {
+        if (typeof window !== 'undefined') {
+            return window;
+        }
+    }
+    catch (_a) {
+        // window is not defined (Node.js environment)
+    }
+    return null;
+}
+/**
+ * Try to create a localStorage provider if available.
+ */
+let _localStorageProvider = null;
+try {
+    const win = _getWindowSafe();
+    if (win &&
+        win.localStorage &&
+        typeof win.localStorage.getItem === 'function') {
+        _localStorageProvider = {
+            isReady: () => true,
+            isReadyResolver: () => null,
+            getProviderName: () => 'LocalStorage',
+            getItem: (key) => win.localStorage.getItem(key),
+            setItem: (key, value) => win.localStorage.setItem(key, value),
+            removeItem: (key) => win.localStorage.removeItem(key),
+            getAllKeys: () => Object.keys(win.localStorage),
+        };
+    }
+}
+catch (_a) {
+    Log_1.Log.warn('Failed to setup localStorage provider');
+}
+let _main = _localStorageProvider !== null && _localStorageProvider !== void 0 ? _localStorageProvider : _inMemoryProvider;
+let _current = _main;
+/**
+ * Helper function that falls back to in-memory storage on SecurityError.
+ */
+function _inMemoryBreaker(action) {
+    try {
+        return action();
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'SecurityError') {
+            exports.Storage._setProvider(_inMemoryProvider);
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Global storage singleton that automatically chooses between localStorage (browser)
+ * and in-memory storage (Node.js or when localStorage is unavailable).
+ */
+exports.Storage = {
+    isReady: () => _current.isReady(),
+    isReadyResolver: () => _current.isReadyResolver(),
+    getProviderName: () => _current.getProviderName(),
+    getItem: (key) => _inMemoryBreaker(() => _current.getItem(key)),
+    setItem: (key, value) => _inMemoryBreaker(() => _current.setItem(key, value)),
+    removeItem: (key) => _current.removeItem(key),
+    getAllKeys: () => _current.getAllKeys(),
+    // StorageProviderManagement
+    _setProvider: (newProvider) => {
+        _main = newProvider;
+        _current = newProvider;
+    },
+    _setDisabled: (isDisabled) => {
+        if (isDisabled) {
+            _current = _inMemoryProvider;
+        }
+        else {
+            _current = _main;
+        }
+    },
+};
+/**
+ * Helper to get a parsed object from storage.
+ */
+function _getObjectFromStorage(key) {
+    const value = exports.Storage.getItem(key);
+    try {
+        return JSON.parse(value !== null && value !== void 0 ? value : 'null');
+    }
+    catch (_a) {
+        Log_1.Log.error(`Failed to parse value for key "${key}"`);
+        return null;
+    }
+}
+/**
+ * Helper to set an object in storage as JSON string.
+ */
+function _setObjectInStorage(key, obj) {
+    exports.Storage.setItem(key, JSON.stringify(obj));
+}
+/**
+ * Clear the in-memory store (useful for testing).
+ */
+function _clearInMemoryStore() {
+    for (const key of Object.keys(inMemoryStore)) {
+        delete inMemoryStore[key];
+    }
+}

package/dist/Store.d.ts

@@ -1,3 +1,4 @@
+import { WolvesUser } from './WolvesUser';
 export type ExperimentConfig = {
     value: Record<string, any>;
     experiment_id?: string;
@@ -8,11 +9,89 @@ export type InitializeResponse = {
     has_updates: boolean;
     time: number;
 };
+export type DataSource = 'Network' | 'Cache' | 'NetworkNotModified' | 'NoValues' | 'Uninitialized';
+export type EvaluationDetails = {
+    source: DataSource;
+    reason: string;
+    isRecognized: boolean;
+};
+export type ExperimentEvaluation = {
+    config: ExperimentConfig | null;
+    details: EvaluationDetails;
+};
+export type DataAdapterResult = {
+    source: DataSource;
+    data: string;
+    receivedAt: number;
+    fullUserHash?: string;
+};
+/**
+ * Store class that manages experiment configurations with caching support.
+ * Supports localStorage in browser environments and in-memory storage elsewhere.
+ */
 export declare class Store {
     private values;
-    constructor();
-    setValues(values: InitializeResponse): void;
-    getExperiment(name: string): ExperimentConfig | null;
+    private source;
+    private isInitialized;
+    private sdkKey;
+    private cacheLimit;
+    private inMemoryCache;
+    constructor(sdkKey?: string);
+    /**
+     * Get the cache key for a specific user.
+     */
+    getCacheKey(user?: WolvesUser): string;
+    /**
+     * Load cached data synchronously.
+     * First checks in-memory cache, then persistent storage.
+     */
+    getDataSync(user?: WolvesUser): DataAdapterResult | null;
+    /**
+     * Load from persistent storage cache.
+     */
+    private _loadFromCache;
+    /**
+     * Set values from a data adapter result.
+     */
+    setValuesFromResult(result: DataAdapterResult | null, user?: WolvesUser): boolean;
+    /**
+     * Set values directly from an InitializeResponse (legacy method).
+     */
+    setValues(values: InitializeResponse, user?: WolvesUser): void;
+    /**
+     * Write to persistent cache with eviction support.
+     */
+    private _writeToCache;
+    /**
+     * Run cache eviction to stay within limits.
+     */
+    private _runCacheEviction;
+    /**
+     * Reset the store for a new user.
+     */
+    reset(): void;
+    /**
+     * Mark the store as initialized.
+     */
+    finalize(): void;
+    /**
+     * Get experiment with evaluation details including reason.
+     * Following Statsig SDK pattern for exposure reasons:
+     * - Uninitialized: API called before initialize
+     * - NoValues: No data available
+     * - Network:Recognized / Network:Unrecognized
+     * - Cache:Recognized / Cache:Unrecognized
+     */
+    getExperiment(name: string): ExperimentEvaluation;
+    /**
+     * Get the base source for building reason string.
+     */
+    private _getBaseSource;
     getValues(): InitializeResponse | null;
+    getSource(): DataSource;
     getLastUpdateTime(): number | undefined;
+    /**
+     * Clear in-memory cache (useful for testing).
+     */
+    clearInMemoryCache(): void;
 }

package/dist/Store.js

@@ -1,25 +1,247 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Store = void 0;
+const StorageProvider_1 = require("./StorageProvider");
+const Log_1 = require("./Log");
+const CACHE_KEY_PREFIX = 'wolves.cache';
+const CACHE_LIMIT = 10;
+const MAX_CACHE_WRITE_ATTEMPTS = 8;
+const LAST_MODIFIED_KEY = 'wolves.last_modified_time';
+/**
+ * Generate a user identifier for cache keys.
+ * Only uses userID as the unique identifier.
+ */
+function _getUserIdentifier(user) {
+    if (!user || !user.userID)
+        return 'anonymous';
+    return user.userID;
+}
+/**
+ * Store class that manages experiment configurations with caching support.
+ * Supports localStorage in browser environments and in-memory storage elsewhere.
+ */
 class Store {
-    constructor() {
+    constructor(sdkKey = '') {
         this.values = null;
+        this.source = 'NoValues';
+        this.isInitialized = false;
+        this.cacheLimit = CACHE_LIMIT;
+        this.inMemoryCache = new Map();
+        this.sdkKey = sdkKey;
+    }
+    /**
+     * Get the cache key for a specific user.
+     */
+    getCacheKey(user) {
+        const userHash = _getUserIdentifier(user);
+        return `${CACHE_KEY_PREFIX}.${this.sdkKey}.${userHash}`;
+    }
+    /**
+     * Load cached data synchronously.
+     * First checks in-memory cache, then persistent storage.
+     */
+    getDataSync(user) {
+        const cacheKey = this.getCacheKey(user);
+        // Check in-memory cache first
+        const inMemResult = this.inMemoryCache.get(cacheKey);
+        if (inMemResult) {
+            return inMemResult;
+        }
+        // Check persistent storage
+        const cached = this._loadFromCache(cacheKey);
+        if (cached) {
+            this.inMemoryCache.set(cacheKey, cached);
+            return cached;
+        }
+        return null;
+    }
+    /**
+     * Load from persistent storage cache.
+     */
+    _loadFromCache(cacheKey) {
+        const cache = StorageProvider_1.Storage.getItem(cacheKey);
+        if (cache == null) {
+            return null;
+        }
+        try {
+            const result = JSON.parse(cache);
+            if (result && result.source) {
+                return Object.assign(Object.assign({}, result), { source: 'Cache' });
+            }
+        }
+        catch (_a) {
+            Log_1.Log.error(`Failed to parse cached value for key "${cacheKey}"`);
+        }
+        return null;
+    }
+    /**
+     * Set values from a data adapter result.
+     */
+    setValuesFromResult(result, user) {
+        if (!result || !result.data) {
+            return false;
+        }
+        try {
+            const parsed = JSON.parse(result.data);
+            this.values = parsed;
+            this.source = result.source;
+            // Update caches
+            const cacheKey = this.getCacheKey(user);
+            this.inMemoryCache.set(cacheKey, result);
+            // Persist to storage if it's from network
+            if (result.source === 'Network' || result.source === 'NetworkNotModified') {
+                this._writeToCache(cacheKey, result);
+            }
+            return true;
+        }
+        catch (_a) {
+            Log_1.Log.error('Failed to parse data adapter result');
+            return false;
+        }
     }
-    setValues(values) {
+    /**
+     * Set values directly from an InitializeResponse (legacy method).
+     */
+    setValues(values, user) {
         this.values = values;
+        this.source = 'Network';
+        // Create and cache the result
+        const result = {
+            source: 'Network',
+            data: JSON.stringify(values),
+            receivedAt: Date.now(),
+            fullUserHash: _getUserIdentifier(user),
+        };
+        const cacheKey = this.getCacheKey(user);
+        this.inMemoryCache.set(cacheKey, result);
+        this._writeToCache(cacheKey, result);
     }
+    /**
+     * Write to persistent cache with eviction support.
+     */
+    _writeToCache(cacheKey, result) {
+        const resultString = JSON.stringify(result);
+        for (let i = 0; i < MAX_CACHE_WRITE_ATTEMPTS; i++) {
+            try {
+                StorageProvider_1.Storage.setItem(cacheKey, resultString);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof Error) ||
+                    !(error.toString().includes('QuotaExceededError') ||
+                        error.toString().includes('QUOTA_EXCEEDED_ERR')) ||
+                    this.cacheLimit <= 1) {
+                    Log_1.Log.warn('Failed to write to cache', error);
+                    return;
+                }
+                this.cacheLimit = Math.ceil(this.cacheLimit / 2);
+                this._runCacheEviction(cacheKey, this.cacheLimit - 1);
+            }
+        }
+        this._runCacheEviction(cacheKey);
+    }
+    /**
+     * Run cache eviction to stay within limits.
+     */
+    _runCacheEviction(cacheKey, limit = this.cacheLimit) {
+        var _a;
+        const lastModifiedTimeMap = (_a = (0, StorageProvider_1._getObjectFromStorage)(LAST_MODIFIED_KEY)) !== null && _a !== void 0 ? _a : {};
+        lastModifiedTimeMap[cacheKey] = Date.now();
+        const keys = Object.keys(lastModifiedTimeMap);
+        if (keys.length > limit) {
+            // Sort by time and remove oldest
+            const sortedKeys = keys.sort((a, b) => lastModifiedTimeMap[a] - lastModifiedTimeMap[b]);
+            const keysToEvict = sortedKeys.slice(0, keys.length - limit);
+            for (const evictKey of keysToEvict) {
+                delete lastModifiedTimeMap[evictKey];
+                StorageProvider_1.Storage.removeItem(evictKey);
+            }
+        }
+        (0, StorageProvider_1._setObjectInStorage)(LAST_MODIFIED_KEY, lastModifiedTimeMap);
+    }
+    /**
+     * Reset the store for a new user.
+     */
+    reset() {
+        this.values = null;
+        this.source = 'NoValues';
+        this.isInitialized = false;
+    }
+    /**
+     * Mark the store as initialized.
+     */
+    finalize() {
+        this.isInitialized = true;
+    }
+    /**
+     * Get experiment with evaluation details including reason.
+     * Following Statsig SDK pattern for exposure reasons:
+     * - Uninitialized: API called before initialize
+     * - NoValues: No data available
+     * - Network:Recognized / Network:Unrecognized
+     * - Cache:Recognized / Cache:Unrecognized
+     */
     getExperiment(name) {
+        // Check if uninitialized
+        if (!this.isInitialized) {
+            return {
+                config: null,
+                details: {
+                    source: 'Uninitialized',
+                    reason: 'Uninitialized',
+                    isRecognized: false,
+                },
+            };
+        }
+        // Check if no values
         if (!this.values || !this.values.dynamic_configs) {
-            return null;
+            return {
+                config: null,
+                details: {
+                    source: this.source,
+                    reason: 'NoValues',
+                    isRecognized: false,
+                },
+            };
         }
-        return this.values.dynamic_configs[name] || null;
+        const config = this.values.dynamic_configs[name] || null;
+        const isRecognized = config !== null;
+        const baseSource = this._getBaseSource();
+        const subreason = isRecognized ? 'Recognized' : 'Unrecognized';
+        const reason = `${baseSource}:${subreason}`;
+        return {
+            config,
+            details: {
+                source: this.source,
+                reason,
+                isRecognized,
+            },
+        };
+    }
+    /**
+     * Get the base source for building reason string.
+     */
+    _getBaseSource() {
+        if (this.source === 'NetworkNotModified') {
+            return 'Network';
+        }
+        return this.source;
     }
     getValues() {
         return this.values;
     }
+    getSource() {
+        return this.source;
+    }
     getLastUpdateTime() {
         var _a;
         return (_a = this.values) === null || _a === void 0 ? void 0 : _a.time;
     }
+    /**
+     * Clear in-memory cache (useful for testing).
+     */
+    clearInMemoryCache() {
+        this.inMemoryCache.clear();
+    }
 }
 exports.Store = Store;

package/dist/Types.d.ts

@@ -1,8 +1,4 @@
 import { WolvesUser } from './WolvesUser';
-export type WolvesUpdateDetails = {
-    success: boolean;
-    errorMessage?: string;
-};
 export type WolvesEvent = {
     eventName: string;
     value?: string | number;

package/dist/WolvesClient.d.ts

@@ -1,17 +1,102 @@
 import { WolvesUser } from './WolvesUser';
-import { Experiment, WolvesUpdateDetails } from './Types';
+import { DataSource } from './Store';
+import { Experiment } from './Types';
+export type LoadingStatus = 'Uninitialized' | 'Loading' | 'Ready';
+export type WolvesUpdateDetails = {
+    success: boolean;
+    source: DataSource;
+    duration: number;
+    error: Error | null;
+    warnings: string[];
+};
+export type SyncUpdateOptions = {
+    disableBackgroundCacheRefresh?: boolean;
+};
+export type AsyncUpdateOptions = {
+    timeoutMs?: number;
+};
 export declare class WolvesClient {
     private sdkKey;
     private user;
     private network;
     private store;
     private logger;
-    private initialized;
+    private loadingStatus;
+    private initializePromise;
     constructor(sdkKey: string, user: WolvesUser);
-    initializeAsync(): Promise<WolvesUpdateDetails>;
-    initializeSync(): WolvesUpdateDetails;
-    updateUserAsync(user: WolvesUser): Promise<WolvesUpdateDetails>;
-    updateUserSync(user: WolvesUser): WolvesUpdateDetails;
+    /**
+     * Returns the current loading status of the client.
+     */
+    getLoadingStatus(): LoadingStatus;
+    /**
+     * Initializes the WolvesClient asynchronously by first using cached values
+     * and then updating to the latest values from the network.
+     *
+     * @param options - Optional settings including timeout
+     * @returns Promise that resolves once initialized with latest values or timeout is hit
+     */
+    initializeAsync(options?: AsyncUpdateOptions): Promise<WolvesUpdateDetails>;
+    /**
+     * Internal implementation of async initialization.
+     */
+    private _initializeAsyncImpl;
+    /**
+     * Initializes the WolvesClient synchronously using cached values.
+     * After initialization, cache values are updated in the background for future use.
+     * This is useful for quickly starting with last-known-good configurations while
+     * refreshing data in the background.
+     *
+     * Aligned with Statsig SDK behavior:
+     * - If no cached values exist, returns with NoCachedValues warning
+     * - Triggers background network fetch to update cache for next session
+     *
+     * @param options - Optional settings
+     * @returns Update details including success status and any warnings
+     */
+    initializeSync(options?: SyncUpdateOptions): WolvesUpdateDetails;
+    /**
+     * Asynchronously updates the user by first using cached values and then fetching
+     * the latest values from the network.
+     *
+     * @param user - The new user to switch to
+     * @param options - Optional settings including timeout
+     * @returns Promise that resolves once updated with latest values or timeout is hit
+     */
+    updateUserAsync(user: WolvesUser, options?: AsyncUpdateOptions): Promise<WolvesUpdateDetails>;
+    /**
+     * Internal implementation of async user update.
+     */
+    private _updateUserAsyncImpl;
+    /**
+     * Fetch from network and update the store.
+     */
+    private _fetchAndUpdateFromNetwork;
+    /**
+     * Synchronously updates the user in the client and switches to cached values.
+     * After the initial switch to cached values, updates values in the background.
+     *
+     * Aligned with Statsig SDK behavior:
+     * - Immediately returns with cached values if available
+     * - If no cached values exist, returns with NoCachedValues warning
+     * - Triggers background network fetch (unless disableBackgroundCacheRefresh is true)
+     *
+     * @param user - The new user to switch to
+     * @param options - Optional settings
+     * @returns Update details including success status and any warnings
+     */
+    updateUserSync(user: WolvesUser, options?: SyncUpdateOptions): WolvesUpdateDetails;
+    /**
+     * Internal implementation of sync user update.
+     */
+    private _updateUserSyncImpl;
+    /**
+     * Run a background update to refresh the cache.
+     */
+    private _runBackgroundUpdate;
+    /**
+     * Reset the store and logger for a new user.
+     */
+    private _resetForUser;
     getExperiment(experimentName: string): Experiment;
     /**
      * Test-only method to manually trigger an exposure event with a specified group.

package/dist/WolvesClient.js

@@ -13,64 +13,262 @@ exports.WolvesClient = void 0;
 const Network_1 = require("./Network");
 const Store_1 = require("./Store");
 const EventLogger_1 = require("./EventLogger");
+const StorageProvider_1 = require("./StorageProvider");
+const Log_1 = require("./Log");
+/**
+ * Creates a WolvesUpdateDetails result object.
+ */
+function createUpdateDetails(success, source, duration, error, warnings = []) {
+    return { success, source, duration, error, warnings };
+}
 class WolvesClient {
     constructor(sdkKey, user) {
-        this.initialized = false;
+        this.loadingStatus = 'Uninitialized';
+        this.initializePromise = null;
         this.sdkKey = sdkKey;
         this.user = user;
         this.network = new Network_1.Network(sdkKey);
-        this.store = new Store_1.Store();
+        this.store = new Store_1.Store(sdkKey);
         this.logger = new EventLogger_1.EventLogger(this.network);
     }
-    initializeAsync() {
+    /**
+     * Returns the current loading status of the client.
+     */
+    getLoadingStatus() {
+        return this.loadingStatus;
+    }
+    /**
+     * Initializes the WolvesClient asynchronously by first using cached values
+     * and then updating to the latest values from the network.
+     *
+     * @param options - Optional settings including timeout
+     * @returns Promise that resolves once initialized with latest values or timeout is hit
+     */
+    initializeAsync(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const config = yield this.network.fetchConfig(this.user, this.store.getLastUpdateTime());
-            if (config) {
-                this.store.setValues(config);
-                this.initialized = true;
-                return { success: true };
+            if (this.initializePromise) {
+                return this.initializePromise;
             }
-            return { success: false, errorMessage: 'Failed to fetch config' };
+            this.initializePromise = this._initializeAsyncImpl(options);
+            return this.initializePromise;
         });
     }
-    initializeSync() {
-        // In a real implementation, this might load from local storage or cache.
-        // For this minimal implementation, we trigger a background fetch.
-        this.network.fetchConfig(this.user, this.store.getLastUpdateTime()).then((config) => {
-            if (config) {
-                this.store.setValues(config);
+    /**
+     * Internal implementation of async initialization.
+     */
+    _initializeAsyncImpl(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!StorageProvider_1.Storage.isReady()) {
+                const resolver = StorageProvider_1.Storage.isReadyResolver();
+                if (resolver) {
+                    yield resolver;
+                }
             }
+            this.logger.start();
+            return this.updateUserAsync(this.user, options);
         });
-        this.initialized = true;
-        return { success: true };
     }
-    updateUserAsync(user) {
+    /**
+     * Initializes the WolvesClient synchronously using cached values.
+     * After initialization, cache values are updated in the background for future use.
+     * This is useful for quickly starting with last-known-good configurations while
+     * refreshing data in the background.
+     *
+     * Aligned with Statsig SDK behavior:
+     * - If no cached values exist, returns with NoCachedValues warning
+     * - Triggers background network fetch to update cache for next session
+     *
+     * @param options - Optional settings
+     * @returns Update details including success status and any warnings
+     */
+    initializeSync(options) {
+        if (this.loadingStatus !== 'Uninitialized') {
+            return createUpdateDetails(true, this.store.getSource(), -1, null, ['MultipleInitializations']);
+        }
+        this.logger.start();
+        return this.updateUserSync(this.user, options);
+    }
+    /**
+     * Asynchronously updates the user by first using cached values and then fetching
+     * the latest values from the network.
+     *
+     * @param user - The new user to switch to
+     * @param options - Optional settings including timeout
+     * @returns Promise that resolves once updated with latest values or timeout is hit
+     */
+    updateUserAsync(user, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            this.user = user;
-            this.store = new Store_1.Store(); // Reset store for new user
-            const config = yield this.network.fetchConfig(this.user);
-            if (config) {
-                this.store.setValues(config);
-                return { success: true };
+            const startTime = performance.now();
+            try {
+                return yield this._updateUserAsyncImpl(user, options, startTime);
+            }
+            catch (e) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                return createUpdateDetails(false, this.store.getSource(), performance.now() - startTime, err);
             }
-            return { success: false, errorMessage: 'Failed to fetch config' };
         });
     }
-    updateUserSync(user) {
-        this.user = user;
-        this.store = new Store_1.Store(); // Reset store for new user
-        // In a real implementation, this might load from local storage or cache.
-        // For this minimal implementation, we trigger a background fetch.
-        this.network.fetchConfig(this.user).then((config) => {
+    /**
+     * Internal implementation of async user update.
+     */
+    _updateUserAsyncImpl(user, options, startTime) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._resetForUser(user);
+            const initiator = this.user;
+            const warnings = [];
+            // First, try to load from cache
+            let cachedResult = this.store.getDataSync(user);
+            if (cachedResult) {
+                this.store.setValuesFromResult(cachedResult, user);
+            }
+            else {
+                warnings.push('NoCachedValues');
+            }
+            this.loadingStatus = 'Loading';
+            // Fetch from network
+            const ops = [
+                this._fetchAndUpdateFromNetwork(user, cachedResult, startTime, warnings)
+            ];
+            if (options === null || options === void 0 ? void 0 : options.timeoutMs) {
+                ops.push(new Promise((resolve) => {
+                    setTimeout(() => {
+                        Log_1.Log.debug('Fetching latest value timed out');
+                        resolve(null);
+                    }, options.timeoutMs);
+                }));
+            }
+            const result = yield Promise.race(ops);
+            // Check if user changed during update
+            if (initiator !== this.user) {
+                return createUpdateDetails(false, this.store.getSource(), performance.now() - startTime, new Error('User changed during update'), warnings);
+            }
+            if (result) {
+                return result;
+            }
+            // Timeout case - return with cached values
+            this.loadingStatus = 'Ready';
+            this.store.finalize();
+            return createUpdateDetails(cachedResult != null, this.store.getSource(), performance.now() - startTime, cachedResult ? null : new Error('Timeout waiting for network'), warnings);
+        });
+    }
+    /**
+     * Fetch from network and update the store.
+     */
+    _fetchAndUpdateFromNetwork(user, cachedResult, startTime, warnings) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const config = yield this.network.fetchConfig(user, this.store.getLastUpdateTime());
+                if (config) {
+                    if (config.has_updates === true || config.has_updates === undefined) {
+                        const networkResult = {
+                            source: 'Network',
+                            data: JSON.stringify(config),
+                            receivedAt: Date.now(),
+                        };
+                        this.store.setValuesFromResult(networkResult, user);
+                    }
+                    else if (cachedResult && config.has_updates === false) {
+                        // No updates, but we have cached values - mark as NetworkNotModified
+                        const notModifiedResult = Object.assign(Object.assign({}, cachedResult), { source: 'NetworkNotModified' });
+                        this.store.setValuesFromResult(notModifiedResult, user);
+                    }
+                    this.loadingStatus = 'Ready';
+                    this.store.finalize();
+                    return createUpdateDetails(true, this.store.getSource(), performance.now() - startTime, null, warnings);
+                }
+                // Network fetch failed
+                this.loadingStatus = 'Ready';
+                this.store.finalize();
+                return createUpdateDetails(cachedResult != null, this.store.getSource(), performance.now() - startTime, cachedResult ? null : new Error('Failed to fetch config from network'), [...warnings, 'NetworkFetchFailed']);
+            }
+            catch (e) {
+                this.loadingStatus = 'Ready';
+                this.store.finalize();
+                const err = e instanceof Error ? e : new Error(String(e));
+                return createUpdateDetails(cachedResult != null, this.store.getSource(), performance.now() - startTime, cachedResult ? null : err, [...warnings, 'NetworkFetchFailed']);
+            }
+        });
+    }
+    /**
+     * Synchronously updates the user in the client and switches to cached values.
+     * After the initial switch to cached values, updates values in the background.
+     *
+     * Aligned with Statsig SDK behavior:
+     * - Immediately returns with cached values if available
+     * - If no cached values exist, returns with NoCachedValues warning
+     * - Triggers background network fetch (unless disableBackgroundCacheRefresh is true)
+     *
+     * @param user - The new user to switch to
+     * @param options - Optional settings
+     * @returns Update details including success status and any warnings
+     */
+    updateUserSync(user, options) {
+        const startTime = performance.now();
+        try {
+            return this._updateUserSyncImpl(user, options, startTime);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            return createUpdateDetails(false, this.store.getSource(), performance.now() - startTime, err);
+        }
+    }
+    /**
+     * Internal implementation of sync user update.
+     */
+    _updateUserSyncImpl(user, options, startTime) {
+        const warnings = [];
+        this._resetForUser(user);
+        // Load from cache synchronously
+        const cachedResult = this.store.getDataSync(user);
+        if (cachedResult == null) {
+            warnings.push('NoCachedValues');
+        }
+        this.store.setValuesFromResult(cachedResult, user);
+        this.loadingStatus = 'Ready';
+        this.store.finalize();
+        // Trigger background refresh unless disabled
+        if (options === null || options === void 0 ? void 0 : options.disableBackgroundCacheRefresh) {
+            return createUpdateDetails(true, this.store.getSource(), performance.now() - startTime, null, warnings);
+        }
+        this._runBackgroundUpdate(user, cachedResult);
+        return createUpdateDetails(true, this.store.getSource(), performance.now() - startTime, null, warnings);
+    }
+    /**
+     * Run a background update to refresh the cache.
+     */
+    _runBackgroundUpdate(user, cachedResult) {
+        this.network.fetchConfig(user, this.store.getLastUpdateTime())
+            .then((config) => {
             if (config) {
-                this.store.setValues(config);
+                if (config.has_updates === true || config.has_updates === undefined) {
+                    const networkResult = {
+                        source: 'Network',
+                        data: JSON.stringify(config),
+                        receivedAt: Date.now(),
+                    };
+                    this.store.setValuesFromResult(networkResult, user);
+                }
+                else if (cachedResult && config.has_updates === false) {
+                    const notModifiedResult = Object.assign(Object.assign({}, cachedResult), { source: 'NetworkNotModified' });
+                    this.store.setValuesFromResult(notModifiedResult, user);
+                }
             }
+        })
+            .catch((err) => {
+            Log_1.Log.error('Background update failed', err);
         });
-        return { success: true };
+    }
+    /**
+     * Reset the store and logger for a new user.
+     */
+    _resetForUser(user) {
+        this.logger.reset();
+        this.store.reset();
+        this.user = user;
     }
     getExperiment(experimentName) {
         var _a, _b, _c;
-        const config = this.store.getExperiment(experimentName);
+        const { config, details } = this.store.getExperiment(experimentName);
         const experiment = {
             name: experimentName,
             value: (_a = config === null || config === void 0 ? void 0 : config.value) !== null && _a !== void 0 ? _a : {},
@@ -85,8 +283,8 @@ class WolvesClient {
                 return val;
             }
         };
-        // Log exposure
-        this.logExposure(experimentName, config);
+        // Log exposure with reason
+        this.logExposure(experimentName, config, details);
         return experiment;
     }
     /**
@@ -96,7 +294,7 @@ class WolvesClient {
      */
     getExperimentForTest(experimentName, groupName) {
         var _a;
-        const config = this.store.getExperiment(experimentName);
+        const { config, details } = this.store.getExperiment(experimentName);
         const experimentId = (_a = config === null || config === void 0 ? void 0 : config.experiment_id) !== null && _a !== void 0 ? _a : '';
         const experiment = {
             name: experimentName,
@@ -108,7 +306,7 @@ class WolvesClient {
             }
         };
         // Log exposure with the specified group and experiment ID from store
-        this.logExposure(experimentName, { group: groupName, experiment_id: experimentId, value: {} });
+        this.logExposure(experimentName, { group: groupName, experiment_id: experimentId, value: {} }, details);
         return experiment;
     }
     logEvent(eventName, value, metadata) {
@@ -126,7 +324,7 @@ class WolvesClient {
             yield this.logger.stop();
         });
     }
-    logExposure(experimentName, experiment) {
+    logExposure(experimentName, experiment, details) {
         var _a, _b, _c;
         const exposureEvent = {
             eventName: 'exposure',
@@ -137,6 +335,7 @@ class WolvesClient {
                 experiment_id: (_a = experiment === null || experiment === void 0 ? void 0 : experiment.experiment_id) !== null && _a !== void 0 ? _a : '',
                 group: (_b = experiment === null || experiment === void 0 ? void 0 : experiment.group) !== null && _b !== void 0 ? _b : '',
                 value: JSON.stringify((_c = experiment === null || experiment === void 0 ? void 0 : experiment.value) !== null && _c !== void 0 ? _c : {}),
+                reason: details.reason,
             },
         };
         this.logger.enqueue(exposureEvent);

package/dist/WolvesMetadata.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "1.0.3";
+export declare const SDK_VERSION = "1.0.5";
 export declare const SDK_TYPE = "wolves-js-client";
 export type WolvesMetadata = {
     readonly [key: string]: string | undefined | null;

package/dist/WolvesMetadata.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WolvesMetadataProvider = exports.SDK_TYPE = exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = '1.0.3';
+exports.SDK_VERSION = '1.0.5';
 exports.SDK_TYPE = 'wolves-js-client';
 let metadata = {
     sdk_version: exports.SDK_VERSION,

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export { WolvesClient } from './WolvesClient';
+export type { WolvesUpdateDetails, SyncUpdateOptions, AsyncUpdateOptions, LoadingStatus } from './WolvesClient';
 export { WolvesUser } from './WolvesUser';
 export { Experiment } from './Types';
 export { Log, LogLevel } from './Log';
 export { SDK_VERSION, SDK_TYPE, WolvesMetadataProvider } from './WolvesMetadata';
 export type { WolvesMetadata } from './WolvesMetadata';
+export { Storage } from './StorageProvider';
+export type { StorageProvider } from './StorageProvider';
+export type { DataSource, DataAdapterResult } from './Store';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WolvesMetadataProvider = exports.SDK_TYPE = exports.SDK_VERSION = exports.LogLevel = exports.Log = exports.WolvesClient = void 0;
+exports.Storage = exports.WolvesMetadataProvider = exports.SDK_TYPE = exports.SDK_VERSION = exports.LogLevel = exports.Log = exports.WolvesClient = void 0;
 var WolvesClient_1 = require("./WolvesClient");
 Object.defineProperty(exports, "WolvesClient", { enumerable: true, get: function () { return WolvesClient_1.WolvesClient; } });
 var Log_1 = require("./Log");
@@ -10,3 +10,5 @@ var WolvesMetadata_1 = require("./WolvesMetadata");
 Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return WolvesMetadata_1.SDK_VERSION; } });
 Object.defineProperty(exports, "SDK_TYPE", { enumerable: true, get: function () { return WolvesMetadata_1.SDK_TYPE; } });
 Object.defineProperty(exports, "WolvesMetadataProvider", { enumerable: true, get: function () { return WolvesMetadata_1.WolvesMetadataProvider; } });
+var StorageProvider_1 = require("./StorageProvider");
+Object.defineProperty(exports, "Storage", { enumerable: true, get: function () { return StorageProvider_1.Storage; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolves-js-client",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A Wolves JavaScript Client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/DeviceInfo.d.ts

@@ -1,22 +0,0 @@
-/**
- * DeviceInfo - Collects device and environment information for event metadata
- * Aligns with Statsig SDK's approach: sends raw user_agent for server-side parsing
- *
- * Note: Browser/OS parsing is done server-side from user_agent, not client-side
- */
-export type DeviceInfoData = {
-    user_agent: string;
-    locale: string;
-    screen_width: number | null;
-    screen_height: number | null;
-    viewport_width: number | null;
-    viewport_height: number | null;
-    timezone: string;
-    timezone_offset: number | null;
-};
-export declare function getDeviceInfo(): DeviceInfoData;
-/**
- * Get device info as a flat record suitable for event metadata
- * Only includes non-null values
- */
-export declare function getDeviceInfoForMetadata(): Record<string, string | number>;

package/dist/DeviceInfo.js

@@ -1,98 +0,0 @@
-"use strict";
-/**
- * DeviceInfo - Collects device and environment information for event metadata
- * Aligns with Statsig SDK's approach: sends raw user_agent for server-side parsing
- *
- * Note: Browser/OS parsing is done server-side from user_agent, not client-side
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDeviceInfo = getDeviceInfo;
-exports.getDeviceInfoForMetadata = getDeviceInfoForMetadata;
-function getWindowSafe() {
-    if (typeof window !== 'undefined') {
-        return window;
-    }
-    return null;
-}
-function getNavigatorSafe() {
-    var _a;
-    const win = getWindowSafe();
-    return (_a = win === null || win === void 0 ? void 0 : win.navigator) !== null && _a !== void 0 ? _a : null;
-}
-function getSafeTimezone() {
-    try {
-        return Intl.DateTimeFormat().resolvedOptions().timeZone || '';
-    }
-    catch (_a) {
-        return '';
-    }
-}
-function getSafeTimezoneOffset() {
-    try {
-        return new Date().getTimezoneOffset();
-    }
-    catch (_a) {
-        return null;
-    }
-}
-let cachedDeviceInfo = null;
-function getDeviceInfo() {
-    var _a, _b, _c, _d, _e, _f;
-    // Return cached info if available
-    if (cachedDeviceInfo) {
-        return cachedDeviceInfo;
-    }
-    const win = getWindowSafe();
-    const nav = getNavigatorSafe();
-    if (!win || !nav) {
-        // Return empty values for server-side or non-browser environments
-        return {
-            user_agent: '',
-            locale: '',
-            screen_width: null,
-            screen_height: null,
-            viewport_width: null,
-            viewport_height: null,
-            timezone: '',
-            timezone_offset: null,
-        };
-    }
-    const userAgent = nav.userAgent || '';
-    cachedDeviceInfo = {
-        // Send raw user_agent - server will parse browser/os info
-        user_agent: userAgent.length > 500 ? userAgent.substring(0, 500) : userAgent,
-        locale: nav.language || '',
-        screen_width: (_b = (_a = win.screen) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : null,
-        screen_height: (_d = (_c = win.screen) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : null,
-        viewport_width: (_e = win.innerWidth) !== null && _e !== void 0 ? _e : null,
-        viewport_height: (_f = win.innerHeight) !== null && _f !== void 0 ? _f : null,
-        timezone: getSafeTimezone(),
-        timezone_offset: getSafeTimezoneOffset(),
-    };
-    return cachedDeviceInfo;
-}
-/**
- * Get device info as a flat record suitable for event metadata
- * Only includes non-null values
- */
-function getDeviceInfoForMetadata() {
-    const info = getDeviceInfo();
-    const result = {};
-    if (info.user_agent)
-        result['user_agent'] = info.user_agent;
-    if (info.locale)
-        result['locale'] = info.locale;
-    if (info.screen_width !== null)
-        result['screen_width'] = info.screen_width;
-    if (info.screen_height !== null)
-        result['screen_height'] = info.screen_height;
-    if (info.viewport_width !== null)
-        result['viewport_width'] = info.viewport_width;
-    if (info.viewport_height !== null)
-        result['viewport_height'] = info.viewport_height;
-    if (info.timezone)
-        result['timezone'] = info.timezone;
-    if (info.timezone_offset !== null)
-        result['timezone_offset'] = info.timezone_offset;
-    return result;
-}

package/dist/StatsigClient.d.ts

@@ -1,15 +0,0 @@
-import { StatsigUser } from './StatsigUser';
-import { Experiment, StatsigUpdateDetails } from './Types';
-export declare class StatsigClient {
-    private sdkKey;
-    private user;
-    private network;
-    private store;
-    private initialized;
-    constructor(sdkKey: string, user: StatsigUser);
-    initializeAsync(): Promise<StatsigUpdateDetails>;
-    initializeSync(): StatsigUpdateDetails;
-    getExperiment(experimentName: string): Experiment;
-    logEvent(eventName: string, value?: string | number, metadata?: Record<string, string>): void;
-    private logExposure;
-}

package/dist/StatsigClient.js

@@ -1,92 +0,0 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.StatsigClient = void 0;
-const Network_1 = require("./Network");
-const Store_1 = require("./Store");
-class StatsigClient {
-    constructor(sdkKey, user) {
-        this.initialized = false;
-        this.sdkKey = sdkKey;
-        this.user = user;
-        this.network = new Network_1.Network(sdkKey);
-        this.store = new Store_1.Store();
-    }
-    initializeAsync() {
-        return __awaiter(this, void 0, void 0, function* () {
-            const config = yield this.network.fetchConfig(this.user);
-            if (config) {
-                this.store.setValues(config);
-                this.initialized = true;
-                return { success: true };
-            }
-            return { success: false, errorMessage: 'Failed to fetch config' };
-        });
-    }
-    initializeSync() {
-        // In a real implementation, this might load from local storage or cache.
-        // For this minimal implementation, we trigger a background fetch.
-        this.network.fetchConfig(this.user).then((config) => {
-            if (config) {
-                this.store.setValues(config);
-            }
-        });
-        this.initialized = true;
-        return { success: true };
-    }
-    getExperiment(experimentName) {
-        var _a, _b, _c;
-        const config = this.store.getExperiment(experimentName);
-        const experiment = {
-            name: experimentName,
-            value: (_a = config === null || config === void 0 ? void 0 : config.value) !== null && _a !== void 0 ? _a : {},
-            ruleID: (_b = config === null || config === void 0 ? void 0 : config.rule_id) !== null && _b !== void 0 ? _b : '',
-            groupName: (_c = config === null || config === void 0 ? void 0 : config.group) !== null && _c !== void 0 ? _c : null,
-            get: (key, defaultValue) => {
-                var _a;
-                const val = (_a = config === null || config === void 0 ? void 0 : config.value) === null || _a === void 0 ? void 0 : _a[key];
-                if (val === undefined || val === null) {
-                    return defaultValue;
-                }
-                return val;
-            }
-        };
-        // Log exposure
-        this.logExposure(experimentName, config);
-        return experiment;
-    }
-    logEvent(eventName, value, metadata) {
-        const event = {
-            eventName,
-            value,
-            metadata,
-            user: this.user,
-            time: Date.now(),
-        };
-        this.network.sendEvents([event]);
-    }
-    logExposure(experimentName, experiment) {
-        var _a, _b, _c;
-        const exposureEvent = {
-            eventName: 'statsig::exposure',
-            user: this.user,
-            time: Date.now(),
-            metadata: {
-                config: experimentName,
-                ruleID: (_a = experiment === null || experiment === void 0 ? void 0 : experiment.rule_id) !== null && _a !== void 0 ? _a : '',
-                group: (_b = experiment === null || experiment === void 0 ? void 0 : experiment.group) !== null && _b !== void 0 ? _b : '',
-                value: JSON.stringify((_c = experiment === null || experiment === void 0 ? void 0 : experiment.value) !== null && _c !== void 0 ? _c : {}),
-            },
-        };
-        this.network.sendEvents([exposureEvent]);
-    }
-}
-exports.StatsigClient = StatsigClient;

package/dist/StatsigUser.d.ts

@@ -1,6 +0,0 @@
-export type StatsigUser = {
-    userID?: string;
-    email?: string;
-    ip?: string;
-    custom?: Record<string, string | number | boolean | Array<string>>;
-};

package/dist/StatsigUser.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });