@rolloutctrl/js-sdk 0.0.4 → 0.0.6

package/dist/index.d.mts

@@ -1,7 +1,9 @@
 import { FeatureFlagEnvironment, Action, EvaluationContext, EvaluationResult } from '@rolloutctrl/evaluator';
 
 interface FlagConfig extends FeatureFlagEnvironment {
+    id: string;
     key: string;
+    featureFlagEnvironmentId: string;
 }
 interface Configuration {
     projectId: string;
@@ -22,12 +24,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,8 +54,10 @@ declare class RolloutCtrlClient {
     private readonly repository;
     private readonly evaluatorManager;
     private readonly updateProvider;
+    private readonly metricsQueue;
     private readonly subscribers;
     private isInitialized;
+    private readonly trackedEvaluations;
     private readonly readyPromise;
     private resolveReady;
     private rejectReady;
@@ -61,6 +74,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 +144,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,7 +1,9 @@
 import { FeatureFlagEnvironment, Action, EvaluationContext, EvaluationResult } from '@rolloutctrl/evaluator';
 
 interface FlagConfig extends FeatureFlagEnvironment {
+    id: string;
     key: string;
+    featureFlagEnvironmentId: string;
 }
 interface Configuration {
     projectId: string;
@@ -22,12 +24,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,8 +54,10 @@ declare class RolloutCtrlClient {
     private readonly repository;
     private readonly evaluatorManager;
     private readonly updateProvider;
+    private readonly metricsQueue;
     private readonly subscribers;
     private isInitialized;
+    private readonly trackedEvaluations;
     private readonly readyPromise;
     private resolveReady;
     private rejectReady;
@@ -61,6 +74,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 +144,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,
@@ -171,7 +172,12 @@ var HttpConfigurationRepository = class {
     return this.normalizeConfiguration(raw);
   }
   normalizeConfiguration(raw) {
-    const flags = Array.isArray(raw.flags) ? raw.flags : Object.entries(raw.flags ?? {}).map(([key, value]) => ({ key, ...value }));
+    const flags = Array.isArray(raw.flags) ? raw.flags : Object.entries(raw.flags ?? {}).map(([key, value]) => ({
+      key,
+      ...value,
+      id: value._featureFlagId ?? value.id ?? "",
+      featureFlagEnvironmentId: value._featureFlagEnvironmentId ?? ""
+    }));
     const actions = Array.isArray(raw.actions) ? raw.actions : Object.values(raw.actions ?? {});
     return {
       projectId: raw.project?.id ?? raw.projectId ?? "",
@@ -251,6 +257,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;
@@ -260,14 +334,17 @@ var RolloutCtrlClient = class {
     this.emitter = new TinyEmitter();
     this.subscribers = /* @__PURE__ */ new Set();
     this.isInitialized = false;
+    this.trackedEvaluations = /* @__PURE__ */ new Map();
     const apiUrl = options.apiUrl ?? DEFAULT_API_URL;
     const refreshInterval = options.refreshInterval ?? DEFAULT_REFRESH_INTERVAL;
     const requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     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);
+      this.trackedEvaluations.clear();
       options.storage?.set(configuration).catch(() => {
       });
       if (this.isInitialized) {
@@ -302,6 +379,7 @@ var RolloutCtrlClient = class {
       this.updateProvider.start(() => {
         void this.repository.refresh();
       });
+      this.metricsQueue?.start();
       this.emitter.emit("ready");
       this.resolveReady();
     } catch (error) {
@@ -323,6 +401,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 +425,44 @@ 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";
+      }
+      const fingerprint = `${type}:${result.strategy?.id ?? ""}:${result.variant?.id ?? ""}`;
+      if (this.trackedEvaluations.get(flagKey) === fingerprint) return;
+      this.trackedEvaluations.set(flagKey, fingerprint);
+      this.metricsQueue.push({
+        featureFlagId: flag.id,
+        featureFlagEnvironmentId: flag.featureFlagEnvironmentId,
+        type,
+        strategyId: result.strategy?.id,
+        variantId: result.variant?.id
+      });
+    } catch {
+    }
   }
   can(actionKey, context) {
     return this.getEvaluator().can(actionKey, context);
@@ -389,6 +502,7 @@ var LocalStorageAdapter = class {
   EvaluatorManager,
   HttpConfigurationRepository,
   LocalStorageAdapter,
+  MetricsQueue,
   PollingUpdateProvider,
   RolloutCtrlClient,
   SseUpdateProvider,

package/dist/index.mjs

@@ -143,7 +143,12 @@ var HttpConfigurationRepository = class {
     return this.normalizeConfiguration(raw);
   }
   normalizeConfiguration(raw) {
-    const flags = Array.isArray(raw.flags) ? raw.flags : Object.entries(raw.flags ?? {}).map(([key, value]) => ({ key, ...value }));
+    const flags = Array.isArray(raw.flags) ? raw.flags : Object.entries(raw.flags ?? {}).map(([key, value]) => ({
+      key,
+      ...value,
+      id: value._featureFlagId ?? value.id ?? "",
+      featureFlagEnvironmentId: value._featureFlagEnvironmentId ?? ""
+    }));
     const actions = Array.isArray(raw.actions) ? raw.actions : Object.values(raw.actions ?? {});
     return {
       projectId: raw.project?.id ?? raw.projectId ?? "",
@@ -223,6 +228,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;
@@ -232,14 +305,17 @@ var RolloutCtrlClient = class {
     this.emitter = new TinyEmitter();
     this.subscribers = /* @__PURE__ */ new Set();
     this.isInitialized = false;
+    this.trackedEvaluations = /* @__PURE__ */ new Map();
     const apiUrl = options.apiUrl ?? DEFAULT_API_URL;
     const refreshInterval = options.refreshInterval ?? DEFAULT_REFRESH_INTERVAL;
     const requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     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);
+      this.trackedEvaluations.clear();
       options.storage?.set(configuration).catch(() => {
       });
       if (this.isInitialized) {
@@ -274,6 +350,7 @@ var RolloutCtrlClient = class {
       this.updateProvider.start(() => {
         void this.repository.refresh();
       });
+      this.metricsQueue?.start();
       this.emitter.emit("ready");
       this.resolveReady();
     } catch (error) {
@@ -295,6 +372,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 +396,44 @@ 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";
+      }
+      const fingerprint = `${type}:${result.strategy?.id ?? ""}:${result.variant?.id ?? ""}`;
+      if (this.trackedEvaluations.get(flagKey) === fingerprint) return;
+      this.trackedEvaluations.set(flagKey, fingerprint);
+      this.metricsQueue.push({
+        featureFlagId: flag.id,
+        featureFlagEnvironmentId: flag.featureFlagEnvironmentId,
+        type,
+        strategyId: result.strategy?.id,
+        variantId: result.variant?.id
+      });
+    } catch {
+    }
   }
   can(actionKey, context) {
     return this.getEvaluator().can(actionKey, context);
@@ -360,6 +472,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.6",
   "description": "RolloutCtrl JavaScript SDK for browser applications",
   "license": "MIT",
   "main": "./dist/index.js",