wolves-js-client 1.0.4 → 1.0.6

package/dist/DeviceInfo.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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

@@ -0,0 +1,98 @@
+"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/Network.d.ts

@@ -1,10 +1,12 @@
 import { WolvesUser } from './WolvesUser';
 export declare const API_LOCAL = "http://localhost:8000/api";
 export declare const API_DEV = "https://wolves-nova-dev.azurewebsites.net/api";
+export declare const API_PROD = "https://wolves-nova.azurewebsites.net/api";
+export type ApiEnvironment = 'local' | 'dev' | 'prod';
 export declare class Network {
     private sdkKey;
     private api;
-    constructor(sdkKey: string, api?: string);
+    constructor(sdkKey: string, apiEnv?: ApiEnvironment);
     fetchConfig(user: WolvesUser, sinceTime?: number, retries?: number, backoff?: number): Promise<any>;
     sendEvents(events: any[], retries?: number, backoff?: number): Promise<void>;
 }

package/dist/Network.js

@@ -9,17 +9,30 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Network = exports.API_DEV = exports.API_LOCAL = void 0;
+exports.Network = exports.API_PROD = exports.API_DEV = exports.API_LOCAL = void 0;
 const Log_1 = require("./Log");
 const WolvesMetadata_1 = require("./WolvesMetadata");
 const RETRYABLE_CODES = [408, 500, 502, 503, 504, 522, 524, 599];
-// API endpoints - switch between local and production
+// API endpoints
 exports.API_LOCAL = 'http://localhost:8000/api';
 exports.API_DEV = 'https://wolves-nova-dev.azurewebsites.net/api';
+exports.API_PROD = 'https://wolves-nova.azurewebsites.net/api';
+const API_ENDPOINTS = {
+    local: exports.API_LOCAL,
+    dev: exports.API_DEV,
+    prod: exports.API_PROD,
+};
+const VALID_ENVIRONMENTS = ['local', 'dev', 'prod'];
+function validateAndGetEndpoint(apiEnv) {
+    if (!VALID_ENVIRONMENTS.includes(apiEnv)) {
+        throw new Error(`Invalid apiEnv: "${apiEnv}". Must be one of: ${VALID_ENVIRONMENTS.join(', ')}`);
+    }
+    return API_ENDPOINTS[apiEnv];
+}
 class Network {
-    constructor(sdkKey, api = exports.API_DEV) {
+    constructor(sdkKey, apiEnv = 'prod') {
         this.sdkKey = sdkKey;
-        this.api = api;
+        this.api = validateAndGetEndpoint(apiEnv);
     }
     fetchConfig(user_1, sinceTime_1) {
         return __awaiter(this, arguments, void 0, function* (user, sinceTime, retries = 2, backoff = 1000) {

package/dist/StatsigClient.d.ts

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,92 @@
+"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

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

package/dist/StatsigUser.js

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

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 = {
@@ -23,7 +23,7 @@ export declare class WolvesClient {
     private logger;
     private loadingStatus;
     private initializePromise;
-    constructor(sdkKey: string, user: WolvesUser);
+    constructor(sdkKey: string, user: WolvesUser, apiEnv?: string);
     /**
      * Returns the current loading status of the client.
      */
@@ -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

@@ -22,12 +22,12 @@ function createUpdateDetails(success, source, duration, error, warnings = []) {
     return { success, source, duration, error, warnings };
 }
 class WolvesClient {
-    constructor(sdkKey, user) {
+    constructor(sdkKey, user, apiEnv = 'prod') {
         this.loadingStatus = 'Uninitialized';
         this.initializePromise = null;
         this.sdkKey = sdkKey;
         this.user = user;
-        this.network = new Network_1.Network(sdkKey);
+        this.network = new Network_1.Network(sdkKey, apiEnv);
         this.store = new Store_1.Store(sdkKey);
         this.logger = new EventLogger_1.EventLogger(this.network);
     }
@@ -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.6";
 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.6';
 exports.SDK_TYPE = 'wolves-js-client';
 let metadata = {
     sdk_version: exports.SDK_VERSION,

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export type { WolvesMetadata } from './WolvesMetadata';
 export { Storage } from './StorageProvider';
 export type { StorageProvider } from './StorageProvider';
 export type { DataSource, DataAdapterResult } from './Store';
+export type { ApiEnvironment } from './Network';

package/package.json

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