@rolloutctrl/js-sdk 0.0.4 → 0.0.5

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { FeatureFlagEnvironment, Action, EvaluationContext, EvaluationResult } from '@rolloutctrl/evaluator';
 
 interface FlagConfig extends FeatureFlagEnvironment {
+    id: string;
     key: string;
 }
 interface Configuration {
@@ -22,12 +23,21 @@ interface StorageAdapter {
     set(configuration: Configuration): Promise<void>;
     clear(): Promise<void>;
 }
+type MetricType = 'FLAG_EVALUATION' | 'FLAG_ENABLED' | 'FLAG_DISABLED' | 'STRATEGY_MATCH' | 'VARIANT_EXPOSURE';
+interface MetricEvent {
+    featureFlagEnvironmentId: string;
+    featureFlagId: string;
+    type: MetricType;
+    strategyId?: string;
+    variantId?: string;
+}
 interface RolloutCtrlOptions {
     sdkKey: string;
     environment: string;
     apiUrl?: string;
     refreshInterval?: number;
     requestTimeout?: number;
+    enableMetrics?: boolean;
     bootstrap?: Configuration;
     storage?: StorageAdapter;
 }
@@ -43,6 +53,7 @@ declare class RolloutCtrlClient {
     private readonly repository;
     private readonly evaluatorManager;
     private readonly updateProvider;
+    private readonly metricsQueue;
     private readonly subscribers;
     private isInitialized;
     private readonly readyPromise;
@@ -61,6 +72,7 @@ declare class RolloutCtrlClient {
     isEnabled(flagKey: string, context?: EvaluationContext): boolean;
     evaluate(flagKey: string, context?: EvaluationContext): EvaluationResult;
     getVariant(flagKey: string, context?: EvaluationContext): VariantResult;
+    private trackEvaluation;
     can(actionKey: string, context?: EvaluationContext): boolean;
 }
 
@@ -130,4 +142,19 @@ declare class LocalStorageAdapter implements StorageAdapter {
     clear(): Promise<void>;
 }
 
-export { type Configuration, type ConfigurationRepository, type Evaluator, EvaluatorManager, type FlagConfig, HttpConfigurationRepository, LocalStorageAdapter, PollingUpdateProvider, RolloutCtrlClient, type RolloutCtrlOptions, SseUpdateProvider, type StorageAdapter, type UpdateProvider, type VariantResult, createEvaluator };
+declare class MetricsQueue {
+    private readonly apiUrl;
+    private readonly sdkKey;
+    private readonly requestTimeout;
+    private queue;
+    private flushTimer;
+    constructor(apiUrl: string, sdkKey: string, requestTimeout: number);
+    start(): void;
+    stop(): void;
+    push(event: MetricEvent): void;
+    flush(): Promise<void>;
+    private flushWithRetry;
+    private sendBatch;
+}
+
+export { type Configuration, type ConfigurationRepository, type Evaluator, EvaluatorManager, type FlagConfig, HttpConfigurationRepository, LocalStorageAdapter, type MetricEvent, type MetricType, MetricsQueue, PollingUpdateProvider, RolloutCtrlClient, type RolloutCtrlOptions, SseUpdateProvider, type StorageAdapter, type UpdateProvider, type VariantResult, createEvaluator };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { FeatureFlagEnvironment, Action, EvaluationContext, EvaluationResult } from '@rolloutctrl/evaluator';
 
 interface FlagConfig extends FeatureFlagEnvironment {
+    id: string;
     key: string;
 }
 interface Configuration {
@@ -22,12 +23,21 @@ interface StorageAdapter {
     set(configuration: Configuration): Promise<void>;
     clear(): Promise<void>;
 }
+type MetricType = 'FLAG_EVALUATION' | 'FLAG_ENABLED' | 'FLAG_DISABLED' | 'STRATEGY_MATCH' | 'VARIANT_EXPOSURE';
+interface MetricEvent {
+    featureFlagEnvironmentId: string;
+    featureFlagId: string;
+    type: MetricType;
+    strategyId?: string;
+    variantId?: string;
+}
 interface RolloutCtrlOptions {
     sdkKey: string;
     environment: string;
     apiUrl?: string;
     refreshInterval?: number;
     requestTimeout?: number;
+    enableMetrics?: boolean;
     bootstrap?: Configuration;
     storage?: StorageAdapter;
 }
@@ -43,6 +53,7 @@ declare class RolloutCtrlClient {
     private readonly repository;
     private readonly evaluatorManager;
     private readonly updateProvider;
+    private readonly metricsQueue;
     private readonly subscribers;
     private isInitialized;
     private readonly readyPromise;
@@ -61,6 +72,7 @@ declare class RolloutCtrlClient {
     isEnabled(flagKey: string, context?: EvaluationContext): boolean;
     evaluate(flagKey: string, context?: EvaluationContext): EvaluationResult;
     getVariant(flagKey: string, context?: EvaluationContext): VariantResult;
+    private trackEvaluation;
     can(actionKey: string, context?: EvaluationContext): boolean;
 }
 
@@ -130,4 +142,19 @@ declare class LocalStorageAdapter implements StorageAdapter {
     clear(): Promise<void>;
 }
 
-export { type Configuration, type ConfigurationRepository, type Evaluator, EvaluatorManager, type FlagConfig, HttpConfigurationRepository, LocalStorageAdapter, PollingUpdateProvider, RolloutCtrlClient, type RolloutCtrlOptions, SseUpdateProvider, type StorageAdapter, type UpdateProvider, type VariantResult, createEvaluator };
+declare class MetricsQueue {
+    private readonly apiUrl;
+    private readonly sdkKey;
+    private readonly requestTimeout;
+    private queue;
+    private flushTimer;
+    constructor(apiUrl: string, sdkKey: string, requestTimeout: number);
+    start(): void;
+    stop(): void;
+    push(event: MetricEvent): void;
+    flush(): Promise<void>;
+    private flushWithRetry;
+    private sendBatch;
+}
+
+export { type Configuration, type ConfigurationRepository, type Evaluator, EvaluatorManager, type FlagConfig, HttpConfigurationRepository, LocalStorageAdapter, type MetricEvent, type MetricType, MetricsQueue, PollingUpdateProvider, RolloutCtrlClient, type RolloutCtrlOptions, SseUpdateProvider, type StorageAdapter, type UpdateProvider, type VariantResult, createEvaluator };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   EvaluatorManager: () => EvaluatorManager,
   HttpConfigurationRepository: () => HttpConfigurationRepository,
   LocalStorageAdapter: () => LocalStorageAdapter,
+  MetricsQueue: () => MetricsQueue,
   PollingUpdateProvider: () => PollingUpdateProvider,
   RolloutCtrlClient: () => RolloutCtrlClient,
   SseUpdateProvider: () => SseUpdateProvider,
@@ -251,6 +252,74 @@ var SseUpdateProvider = class {
   }
 };
 
+// src/metrics.ts
+var FLUSH_INTERVAL_MS = 3e4;
+var FLUSH_BATCH_SIZE = 100;
+var MAX_RETRIES = 3;
+var MetricsQueue = class {
+  constructor(apiUrl, sdkKey, requestTimeout) {
+    this.apiUrl = apiUrl;
+    this.sdkKey = sdkKey;
+    this.requestTimeout = requestTimeout;
+    this.queue = [];
+    this.flushTimer = null;
+  }
+  start() {
+    this.flushTimer = setInterval(() => {
+      this.flush().catch(() => {
+      });
+    }, FLUSH_INTERVAL_MS);
+  }
+  stop() {
+    if (this.flushTimer !== null) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= FLUSH_BATCH_SIZE) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  async flush() {
+    await this.flushWithRetry(0);
+  }
+  async flushWithRetry(attempt) {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.queue.length);
+    try {
+      await this.sendBatch(batch);
+    } catch {
+      if (attempt < MAX_RETRIES) {
+        this.queue.unshift(...batch);
+        await this.flushWithRetry(attempt + 1);
+      }
+    }
+  }
+  async sendBatch(events) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.requestTimeout);
+    try {
+      const response = await fetch(`${this.apiUrl}/sdk/metrics`, {
+        method: "POST",
+        headers: {
+          "x-api-key": this.sdkKey,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ events }),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_API_URL = "https://rolloutctrl.io/api";
 var DEFAULT_REFRESH_INTERVAL = 3e4;
@@ -266,6 +335,7 @@ var RolloutCtrlClient = class {
     this.repository = new HttpConfigurationRepository(apiUrl, options.sdkKey, options.environment, requestTimeout);
     this.evaluatorManager = new EvaluatorManager();
     this.updateProvider = new PollingUpdateProvider(refreshInterval);
+    this.metricsQueue = options.enableMetrics ?? true ? new MetricsQueue(apiUrl, options.sdkKey, requestTimeout) : null;
     this.repository.subscribe((configuration) => {
       this.evaluatorManager.update(configuration);
       options.storage?.set(configuration).catch(() => {
@@ -302,6 +372,7 @@ var RolloutCtrlClient = class {
       this.updateProvider.start(() => {
         void this.repository.refresh();
       });
+      this.metricsQueue?.start();
       this.emitter.emit("ready");
       this.resolveReady();
     } catch (error) {
@@ -323,6 +394,10 @@ var RolloutCtrlClient = class {
   }
   async close() {
     this.updateProvider.stop();
+    if (this.metricsQueue) {
+      this.metricsQueue.stop();
+      await this.metricsQueue.flush();
+    }
     this.subscribers.clear();
     this.emitter.emit("shutdown");
     this.emitter.removeAllListeners();
@@ -343,13 +418,41 @@ var RolloutCtrlClient = class {
     return this.evaluatorManager.get();
   }
   isEnabled(flagKey, context) {
-    return this.getEvaluator().isEnabled(flagKey, context);
+    return this.evaluate(flagKey, context).enabled;
   }
   evaluate(flagKey, context) {
-    return this.getEvaluator().evaluate(flagKey, context);
+    const result = this.getEvaluator().evaluate(flagKey, context);
+    this.trackEvaluation(flagKey, result);
+    return result;
   }
   getVariant(flagKey, context) {
-    return this.getEvaluator().getVariant(flagKey, context);
+    return this.evaluate(flagKey, context).variant;
+  }
+  trackEvaluation(flagKey, result) {
+    if (!this.metricsQueue || !this.isInitialized) return;
+    try {
+      const config = this.repository.getConfiguration();
+      const flag = config.flags.find((f) => f.key === flagKey);
+      if (!flag) return;
+      let type;
+      if (result.variant) {
+        type = "VARIANT_EXPOSURE";
+      } else if (result.strategy) {
+        type = "STRATEGY_MATCH";
+      } else if (result.enabled) {
+        type = "FLAG_ENABLED";
+      } else {
+        type = "FLAG_DISABLED";
+      }
+      this.metricsQueue.push({
+        featureFlagId: flag.id,
+        featureFlagEnvironmentId: config.environmentId,
+        type,
+        strategyId: result.strategy?.id,
+        variantId: result.variant?.id
+      });
+    } catch {
+    }
   }
   can(actionKey, context) {
     return this.getEvaluator().can(actionKey, context);
@@ -389,6 +492,7 @@ var LocalStorageAdapter = class {
   EvaluatorManager,
   HttpConfigurationRepository,
   LocalStorageAdapter,
+  MetricsQueue,
   PollingUpdateProvider,
   RolloutCtrlClient,
   SseUpdateProvider,

package/dist/index.mjs

@@ -223,6 +223,74 @@ var SseUpdateProvider = class {
   }
 };
 
+// src/metrics.ts
+var FLUSH_INTERVAL_MS = 3e4;
+var FLUSH_BATCH_SIZE = 100;
+var MAX_RETRIES = 3;
+var MetricsQueue = class {
+  constructor(apiUrl, sdkKey, requestTimeout) {
+    this.apiUrl = apiUrl;
+    this.sdkKey = sdkKey;
+    this.requestTimeout = requestTimeout;
+    this.queue = [];
+    this.flushTimer = null;
+  }
+  start() {
+    this.flushTimer = setInterval(() => {
+      this.flush().catch(() => {
+      });
+    }, FLUSH_INTERVAL_MS);
+  }
+  stop() {
+    if (this.flushTimer !== null) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= FLUSH_BATCH_SIZE) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  async flush() {
+    await this.flushWithRetry(0);
+  }
+  async flushWithRetry(attempt) {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.queue.length);
+    try {
+      await this.sendBatch(batch);
+    } catch {
+      if (attempt < MAX_RETRIES) {
+        this.queue.unshift(...batch);
+        await this.flushWithRetry(attempt + 1);
+      }
+    }
+  }
+  async sendBatch(events) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.requestTimeout);
+    try {
+      const response = await fetch(`${this.apiUrl}/sdk/metrics`, {
+        method: "POST",
+        headers: {
+          "x-api-key": this.sdkKey,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ events }),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_API_URL = "https://rolloutctrl.io/api";
 var DEFAULT_REFRESH_INTERVAL = 3e4;
@@ -238,6 +306,7 @@ var RolloutCtrlClient = class {
     this.repository = new HttpConfigurationRepository(apiUrl, options.sdkKey, options.environment, requestTimeout);
     this.evaluatorManager = new EvaluatorManager();
     this.updateProvider = new PollingUpdateProvider(refreshInterval);
+    this.metricsQueue = options.enableMetrics ?? true ? new MetricsQueue(apiUrl, options.sdkKey, requestTimeout) : null;
     this.repository.subscribe((configuration) => {
       this.evaluatorManager.update(configuration);
       options.storage?.set(configuration).catch(() => {
@@ -274,6 +343,7 @@ var RolloutCtrlClient = class {
       this.updateProvider.start(() => {
         void this.repository.refresh();
       });
+      this.metricsQueue?.start();
       this.emitter.emit("ready");
       this.resolveReady();
     } catch (error) {
@@ -295,6 +365,10 @@ var RolloutCtrlClient = class {
   }
   async close() {
     this.updateProvider.stop();
+    if (this.metricsQueue) {
+      this.metricsQueue.stop();
+      await this.metricsQueue.flush();
+    }
     this.subscribers.clear();
     this.emitter.emit("shutdown");
     this.emitter.removeAllListeners();
@@ -315,13 +389,41 @@ var RolloutCtrlClient = class {
     return this.evaluatorManager.get();
   }
   isEnabled(flagKey, context) {
-    return this.getEvaluator().isEnabled(flagKey, context);
+    return this.evaluate(flagKey, context).enabled;
   }
   evaluate(flagKey, context) {
-    return this.getEvaluator().evaluate(flagKey, context);
+    const result = this.getEvaluator().evaluate(flagKey, context);
+    this.trackEvaluation(flagKey, result);
+    return result;
   }
   getVariant(flagKey, context) {
-    return this.getEvaluator().getVariant(flagKey, context);
+    return this.evaluate(flagKey, context).variant;
+  }
+  trackEvaluation(flagKey, result) {
+    if (!this.metricsQueue || !this.isInitialized) return;
+    try {
+      const config = this.repository.getConfiguration();
+      const flag = config.flags.find((f) => f.key === flagKey);
+      if (!flag) return;
+      let type;
+      if (result.variant) {
+        type = "VARIANT_EXPOSURE";
+      } else if (result.strategy) {
+        type = "STRATEGY_MATCH";
+      } else if (result.enabled) {
+        type = "FLAG_ENABLED";
+      } else {
+        type = "FLAG_DISABLED";
+      }
+      this.metricsQueue.push({
+        featureFlagId: flag.id,
+        featureFlagEnvironmentId: config.environmentId,
+        type,
+        strategyId: result.strategy?.id,
+        variantId: result.variant?.id
+      });
+    } catch {
+    }
   }
   can(actionKey, context) {
     return this.getEvaluator().can(actionKey, context);
@@ -360,6 +462,7 @@ export {
   EvaluatorManager,
   HttpConfigurationRepository,
   LocalStorageAdapter,
+  MetricsQueue,
   PollingUpdateProvider,
   RolloutCtrlClient,
   SseUpdateProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolloutctrl/js-sdk",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "RolloutCtrl JavaScript SDK for browser applications",
   "license": "MIT",
   "main": "./dist/index.js",