wolves-js-client 1.0.4 → 1.0.5

package/dist/Store.d.ts

@@ -9,7 +9,16 @@ export type InitializeResponse = {
     has_updates: boolean;
     time: number;
 };
-export type DataSource = 'Network' | 'Cache' | 'NetworkNotModified' | 'NoValues';
+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;
@@ -23,6 +32,7 @@ export type DataAdapterResult = {
 export declare class Store {
     private values;
     private source;
+    private isInitialized;
     private sdkKey;
     private cacheLimit;
     private inMemoryCache;
@@ -60,7 +70,23 @@ export declare class Store {
      * Reset the store for a new user.
      */
     reset(): void;
-    getExperiment(name: string): ExperimentConfig | null;
+    /**
+     * 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;

package/dist/Store.js

@@ -8,13 +8,13 @@ const CACHE_LIMIT = 10;
 const MAX_CACHE_WRITE_ATTEMPTS = 8;
 const LAST_MODIFIED_KEY = 'wolves.last_modified_time';
 /**
- * Generate a hash for user identity to create unique cache keys.
+ * Generate a user identifier for cache keys.
+ * Only uses userID as the unique identifier.
  */
-function _getUserHash(user) {
-    if (!user)
+function _getUserIdentifier(user) {
+    if (!user || !user.userID)
         return 'anonymous';
-    const parts = [user.userID || '', user.email || ''];
-    return parts.join('|');
+    return user.userID;
 }
 /**
  * Store class that manages experiment configurations with caching support.
@@ -24,6 +24,7 @@ class Store {
     constructor(sdkKey = '') {
         this.values = null;
         this.source = 'NoValues';
+        this.isInitialized = false;
         this.cacheLimit = CACHE_LIMIT;
         this.inMemoryCache = new Map();
         this.sdkKey = sdkKey;
@@ -32,7 +33,7 @@ class Store {
      * Get the cache key for a specific user.
      */
     getCacheKey(user) {
-        const userHash = _getUserHash(user);
+        const userHash = _getUserIdentifier(user);
         return `${CACHE_KEY_PREFIX}.${this.sdkKey}.${userHash}`;
     }
     /**
@@ -109,7 +110,7 @@ class Store {
             source: 'Network',
             data: JSON.stringify(values),
             receivedAt: Date.now(),
-            fullUserHash: _getUserHash(user),
+            fullUserHash: _getUserIdentifier(user),
         };
         const cacheKey = this.getCacheKey(user);
         this.inMemoryCache.set(cacheKey, result);
@@ -164,12 +165,67 @@ class Store {
     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;

package/dist/WolvesClient.d.ts

@@ -1,5 +1,5 @@
 import { WolvesUser } from './WolvesUser';
-import { Store, DataSource } from './Store';
+import { DataSource } from './Store';
 import { Experiment } from './Types';
 export type LoadingStatus = 'Uninitialized' | 'Loading' | 'Ready';
 export type WolvesUpdateDetails = {
@@ -107,8 +107,4 @@ export declare class WolvesClient {
     logEvent(eventName: string, value?: string | number, metadata?: Record<string, string>): void;
     shutdown(): Promise<void>;
     private logExposure;
-    /**
-     * Get the underlying store (for testing purposes).
-     */
-    getStore(): Store;
 }

package/dist/WolvesClient.js

@@ -147,6 +147,7 @@ class WolvesClient {
             }
             // 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);
         });
     }
@@ -172,14 +173,17 @@ class WolvesClient {
                         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']);
             }
@@ -221,6 +225,7 @@ class WolvesClient {
         }
         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);
@@ -263,7 +268,7 @@ class WolvesClient {
     }
     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 : {},
@@ -278,8 +283,8 @@ class WolvesClient {
                 return val;
             }
         };
-        // Log exposure
-        this.logExposure(experimentName, config);
+        // Log exposure with reason
+        this.logExposure(experimentName, config, details);
         return experiment;
     }
     /**
@@ -289,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,
@@ -301,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) {
@@ -319,7 +324,7 @@ class WolvesClient {
             yield this.logger.stop();
         });
     }
-    logExposure(experimentName, experiment) {
+    logExposure(experimentName, experiment, details) {
         var _a, _b, _c;
         const exposureEvent = {
             eventName: 'exposure',
@@ -330,15 +335,10 @@ 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);
     }
-    /**
-     * Get the underlying store (for testing purposes).
-     */
-    getStore() {
-        return this.store;
-    }
 }
 exports.WolvesClient = WolvesClient;

package/dist/WolvesMetadata.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "1.0.4";
+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.4';
+exports.SDK_VERSION = '1.0.5';
 exports.SDK_TYPE = 'wolves-js-client';
 let metadata = {
     sdk_version: exports.SDK_VERSION,

package/package.json

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