@flipswitch-io/sdk 0.1.4 → 0.1.6

package/dist/index.mjs

@@ -9,26 +9,37 @@ import { OFREPWebProvider } from "@openfeature/ofrep-web-provider";
 var MIN_RETRY_DELAY = 1e3;
 var MAX_RETRY_DELAY = 3e4;
 var SseClient = class {
-  constructor(baseUrl, apiKey, onFlagChange, onStatusChange, telemetryHeaders) {
+  constructor(baseUrl, apiKey, onFlagChange, onStatusChange, telemetryHeaders, enableVisibilityHandling = true) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.onFlagChange = onFlagChange;
     this.onStatusChange = onStatusChange;
     this.telemetryHeaders = telemetryHeaders;
+    this.enableVisibilityHandling = enableVisibilityHandling;
     this.eventSource = null;
     this.retryDelay = MIN_RETRY_DELAY;
     this.reconnectTimeout = null;
     this.closed = false;
+    this.paused = false;
     this.status = "disconnected";
+    this.visibilityHandler = null;
+    this.abortController = null;
   }
   /**
    * Start the SSE connection.
    */
   connect() {
-    if (this.closed) return;
+    if (this.closed || this.paused) return;
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+    this.abortController = new AbortController();
     if (this.eventSource) {
       this.eventSource.close();
     }
+    if (this.enableVisibilityHandling) {
+      this.setupVisibilityHandling();
+    }
     this.updateStatus("connecting");
     const url = `${this.baseUrl}/api/v1/flags/events`;
     try {
@@ -38,11 +49,62 @@ var SseClient = class {
         this.connectWithPolyfill(url);
       }
     } catch (error) {
-      console.error("[Flipswitch] Failed to establish SSE connection:", error);
+      console.warn("[Flipswitch] Failed to establish SSE connection:", error);
       this.updateStatus("error");
       this.scheduleReconnect();
     }
   }
+  /**
+   * Setup visibility API handling.
+   * Disconnects when tab is hidden, reconnects when visible.
+   */
+  setupVisibilityHandling() {
+    if (typeof document === "undefined" || this.visibilityHandler) return;
+    this.visibilityHandler = () => {
+      if (document.hidden) {
+        this.pause();
+      } else {
+        this.resume();
+      }
+    };
+    document.addEventListener("visibilitychange", this.visibilityHandler);
+  }
+  /**
+   * Pause the SSE connection (used by visibility API).
+   * Different from close() - can be resumed.
+   */
+  pause() {
+    if (this.paused || this.closed) return;
+    this.paused = true;
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.updateStatus("disconnected");
+  }
+  /**
+   * Resume the SSE connection after being paused.
+   */
+  resume() {
+    if (!this.paused || this.closed) return;
+    this.paused = false;
+    this.retryDelay = MIN_RETRY_DELAY;
+    this.connect();
+  }
+  /**
+   * Check if the connection is paused.
+   */
+  isPaused() {
+    return this.paused;
+  }
   /**
    * Connect using fetch-based SSE (supports custom headers).
    */
@@ -56,7 +118,8 @@ var SseClient = class {
       };
       const response = await fetch(url, {
         method: "GET",
-        headers
+        headers,
+        signal: this.abortController?.signal
       });
       if (!response.ok) {
         throw new Error(`SSE connection failed: ${response.status}`);
@@ -97,14 +160,14 @@ var SseClient = class {
       };
       processStream().catch((error) => {
         if (!this.closed) {
-          console.error("[Flipswitch] SSE stream error:", error);
+          console.warn("[Flipswitch] SSE stream error:", error);
           this.updateStatus("error");
           this.scheduleReconnect();
         }
       });
     } catch (error) {
       if (!this.closed) {
-        console.error("[Flipswitch] SSE connection error:", error);
+        console.warn("[Flipswitch] SSE connection error:", error);
         this.updateStatus("error");
         this.scheduleReconnect();
       }
@@ -124,13 +187,34 @@ var SseClient = class {
     if (eventType === "heartbeat") {
       return;
     }
-    if (eventType === "flag-change") {
-      try {
-        const event = JSON.parse(data);
+    try {
+      if (eventType === "flag-updated") {
+        const parsed = JSON.parse(data);
+        const event = {
+          flagKey: parsed.flagKey,
+          timestamp: parsed.timestamp
+        };
         this.onFlagChange(event);
-      } catch (error) {
-        console.error("[Flipswitch] Failed to parse flag-change event:", error);
+      } else if (eventType === "config-updated") {
+        const parsed = JSON.parse(data);
+        const event = {
+          flagKey: null,
+          // null indicates all flags should be refreshed
+          timestamp: parsed.timestamp
+        };
+        this.onFlagChange(event);
+      } else if (eventType === "api-key-rotated") {
+        const parsed = JSON.parse(data);
+        if (!parsed.validUntil) {
+          console.info("[Flipswitch] API key rotation was aborted");
+        } else {
+          console.warn(
+            `[Flipswitch] API key was rotated. Current key valid until: ${parsed.validUntil}`
+          );
+        }
       }
+    } catch (error) {
+      console.error(`[Flipswitch] Failed to parse ${eventType} event:`, error);
     }
   }
   /**
@@ -167,6 +251,14 @@ var SseClient = class {
   close() {
     this.closed = true;
     this.updateStatus("disconnected");
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
     if (this.reconnectTimeout) {
       clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
@@ -178,9 +270,202 @@ var SseClient = class {
   }
 };
 
+// src/browser-cache.ts
+var CACHE_PREFIX = "flipswitch:flags:";
+var CACHE_META_KEY = "flipswitch:cache-meta";
+var BrowserCache = class {
+  constructor() {
+    this.cacheVersion = 1;
+    this.storage = this.getStorage();
+  }
+  /**
+   * Get storage instance if available.
+   */
+  getStorage() {
+    if (typeof window === "undefined") return null;
+    try {
+      const testKey = "__flipswitch_test__";
+      window.localStorage.setItem(testKey, "test");
+      window.localStorage.removeItem(testKey);
+      return window.localStorage;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Check if browser cache is available.
+   */
+  isAvailable() {
+    return this.storage !== null;
+  }
+  /**
+   * Get a cached flag value.
+   */
+  get(flagKey) {
+    if (!this.storage) return null;
+    try {
+      const key = CACHE_PREFIX + flagKey;
+      const item = this.storage.getItem(key);
+      if (!item) return null;
+      const cached = JSON.parse(item);
+      return cached;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Set a cached flag value.
+   */
+  set(flagKey, value, variant, reason) {
+    if (!this.storage) return;
+    try {
+      const key = CACHE_PREFIX + flagKey;
+      const cached = {
+        value,
+        timestamp: Date.now(),
+        variant,
+        reason
+      };
+      this.storage.setItem(key, JSON.stringify(cached));
+      this.updateMeta();
+    } catch {
+    }
+  }
+  /**
+   * Set multiple cached flag values at once.
+   */
+  setAll(flags) {
+    if (!this.storage) return;
+    try {
+      for (const flag of flags) {
+        const cacheKey = CACHE_PREFIX + flag.key;
+        const cached = {
+          value: flag.value,
+          timestamp: Date.now(),
+          variant: flag.variant,
+          reason: flag.reason
+        };
+        this.storage.setItem(cacheKey, JSON.stringify(cached));
+      }
+      this.updateMeta();
+    } catch {
+    }
+  }
+  /**
+   * Get all cached flags.
+   */
+  getAll() {
+    const result = /* @__PURE__ */ new Map();
+    if (!this.storage) return result;
+    try {
+      for (let i = 0; i < this.storage.length; i++) {
+        const key = this.storage.key(i);
+        if (key?.startsWith(CACHE_PREFIX)) {
+          const flagKey = key.slice(CACHE_PREFIX.length);
+          const item = this.storage.getItem(key);
+          if (item) {
+            const cached = JSON.parse(item);
+            result.set(flagKey, cached);
+          }
+        }
+      }
+    } catch {
+    }
+    return result;
+  }
+  /**
+   * Invalidate a specific flag or all flags.
+   */
+  invalidate(flagKey) {
+    if (!this.storage) return;
+    try {
+      if (flagKey) {
+        this.storage.removeItem(CACHE_PREFIX + flagKey);
+      } else {
+        const keysToRemove = [];
+        for (let i = 0; i < this.storage.length; i++) {
+          const key = this.storage.key(i);
+          if (key?.startsWith(CACHE_PREFIX)) {
+            keysToRemove.push(key);
+          }
+        }
+        for (const key of keysToRemove) {
+          this.storage.removeItem(key);
+        }
+      }
+      this.updateMeta();
+    } catch {
+    }
+  }
+  /**
+   * Update cache metadata.
+   */
+  updateMeta() {
+    if (!this.storage) return;
+    try {
+      const meta = {
+        lastUpdated: Date.now(),
+        version: this.cacheVersion
+      };
+      this.storage.setItem(CACHE_META_KEY, JSON.stringify(meta));
+    } catch {
+    }
+  }
+  /**
+   * Get cache metadata.
+   */
+  getMeta() {
+    if (!this.storage) return null;
+    try {
+      const item = this.storage.getItem(CACHE_META_KEY);
+      if (!item) return null;
+      return JSON.parse(item);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get the age of a cached flag in milliseconds.
+   */
+  getAge(flagKey) {
+    const cached = this.get(flagKey);
+    if (!cached) return null;
+    return Date.now() - cached.timestamp;
+  }
+  /**
+   * Check if a cached flag is stale based on max age.
+   */
+  isStale(flagKey, maxAgeMs) {
+    const age = this.getAge(flagKey);
+    if (age === null) return true;
+    return age > maxAgeMs;
+  }
+  /**
+   * Clear all Flipswitch data from localStorage.
+   */
+  clear() {
+    if (!this.storage) return;
+    try {
+      const keysToRemove = [];
+      for (let i = 0; i < this.storage.length; i++) {
+        const key = this.storage.key(i);
+        if (key?.startsWith("flipswitch:")) {
+          keysToRemove.push(key);
+        }
+      }
+      for (const key of keysToRemove) {
+        this.storage.removeItem(key);
+      }
+    } catch {
+    }
+  }
+};
+
 // src/provider.ts
 var DEFAULT_BASE_URL = "https://api.flipswitch.io";
-var SDK_VERSION = "0.1.1";
+var SDK_VERSION = "0.1.2";
+var DEFAULT_POLLING_INTERVAL = 3e4;
+var DEFAULT_MAX_SSE_RETRIES = 5;
 var FlipswitchProvider = class {
   constructor(options, eventHandlers) {
     this.metadata = {
@@ -191,23 +476,41 @@ var FlipswitchProvider = class {
     this._status = ClientProviderStatus.NOT_READY;
     this.eventHandlers = /* @__PURE__ */ new Map();
     this.userEventHandlers = {};
+    this.pollingTimer = null;
+    this.sseRetryCount = 0;
+    this.isPollingFallbackActive = false;
+    this.onlineHandler = null;
+    this.offlineHandler = null;
+    this._isOnline = true;
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.apiKey = options.apiKey;
     this.enableRealtime = options.enableRealtime ?? true;
-    this.enableTelemetry = options.enableTelemetry ?? true;
     this.fetchImpl = options.fetchImplementation ?? (typeof window !== "undefined" ? fetch.bind(window) : fetch);
     this.userEventHandlers = eventHandlers ?? {};
-    const headers = [["X-API-Key", this.apiKey]];
-    if (this.enableTelemetry) {
-      headers.push(["X-Flipswitch-SDK", this.getTelemetrySdkHeader()]);
-      headers.push(["X-Flipswitch-Runtime", this.getTelemetryRuntimeHeader()]);
-      headers.push(["X-Flipswitch-OS", this.getTelemetryOsHeader()]);
-      headers.push(["X-Flipswitch-Features", this.getTelemetryFeaturesHeader()]);
+    const isBrowser = typeof window !== "undefined";
+    this.enableVisibilityHandling = options.enableVisibilityHandling ?? isBrowser;
+    this.offlineMode = options.offlineMode ?? isBrowser;
+    this.enablePollingFallback = options.enablePollingFallback ?? true;
+    this.pollingInterval = options.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    this.maxSseRetries = options.maxSseRetries ?? DEFAULT_MAX_SSE_RETRIES;
+    const persistCache = options.persistCache ?? isBrowser;
+    this.browserCache = persistCache ? new BrowserCache() : null;
+    if (typeof navigator !== "undefined") {
+      this._isOnline = navigator.onLine;
     }
+    const headers = [
+      ["X-API-Key", this.apiKey],
+      ["X-Flipswitch-SDK", this.getTelemetrySdkHeader()],
+      ["X-Flipswitch-Runtime", this.getTelemetryRuntimeHeader()],
+      ["X-Flipswitch-OS", this.getTelemetryOsHeader()],
+      ["X-Flipswitch-Features", this.getTelemetryFeaturesHeader()]
+    ];
     this.ofrepProvider = new OFREPWebProvider({
       baseUrl: this.baseUrl,
       fetchImplementation: this.fetchImpl,
-      headers
+      headers,
+      pollInterval: 0
+      // Disable polling - SSE handles real-time updates
     });
   }
   getTelemetrySdkHeader() {
@@ -261,7 +564,6 @@ var FlipswitchProvider = class {
     return `sse=${this.enableRealtime}`;
   }
   getTelemetryHeaders() {
-    if (!this.enableTelemetry) return {};
     return {
       "X-Flipswitch-SDK": this.getTelemetrySdkHeader(),
       "X-Flipswitch-Runtime": this.getTelemetryRuntimeHeader(),
@@ -278,6 +580,13 @@ var FlipswitchProvider = class {
    */
   async initialize(context) {
     this._status = ClientProviderStatus.NOT_READY;
+    this.setupOfflineHandling();
+    if (!this._isOnline && this.offlineMode) {
+      console.warn("[Flipswitch] Starting in offline mode - using cached flag values");
+      this._status = ClientProviderStatus.STALE;
+      this.emit(ClientProviderEvents.Stale);
+      return;
+    }
     try {
       await this.ofrepProvider.initialize(context);
     } catch (error) {
@@ -312,15 +621,107 @@ var FlipswitchProvider = class {
     this._status = ClientProviderStatus.READY;
     this.emit(ClientProviderEvents.Ready);
   }
+  /**
+   * Setup online/offline event handling.
+   */
+  setupOfflineHandling() {
+    if (typeof window === "undefined" || !this.offlineMode) return;
+    this.onlineHandler = () => {
+      this._isOnline = true;
+      console.info("[Flipswitch] Connection restored - refreshing flags");
+      if (this.enableRealtime && this.sseClient) {
+        this.sseClient.resume();
+      }
+      this.refreshFlags();
+    };
+    this.offlineHandler = () => {
+      this._isOnline = false;
+      console.warn("[Flipswitch] Connection lost - serving cached values");
+      if (this.sseClient) {
+        this.sseClient.pause();
+      }
+      this.stopPolling();
+      if (this._status !== ClientProviderStatus.STALE) {
+        this._status = ClientProviderStatus.STALE;
+        this.emit(ClientProviderEvents.Stale);
+      }
+    };
+    window.addEventListener("online", this.onlineHandler);
+    window.addEventListener("offline", this.offlineHandler);
+  }
+  /**
+   * Refresh flags from the server.
+   */
+  async refreshFlags() {
+    try {
+      await this.ofrepProvider.onContextChange?.({}, {});
+      if (this._status === ClientProviderStatus.STALE) {
+        this._status = ClientProviderStatus.READY;
+        this.emit(ClientProviderEvents.Ready);
+      }
+      this.emit(ClientProviderEvents.ConfigurationChanged);
+    } catch (error) {
+      console.warn("[Flipswitch] Failed to refresh flags:", error);
+    }
+  }
   /**
    * Called when the provider is shut down.
    */
   async onClose() {
     this.sseClient?.close();
     this.sseClient = null;
+    this.stopPolling();
+    if (typeof window !== "undefined") {
+      if (this.onlineHandler) {
+        window.removeEventListener("online", this.onlineHandler);
+        this.onlineHandler = null;
+      }
+      if (this.offlineHandler) {
+        window.removeEventListener("offline", this.offlineHandler);
+        this.offlineHandler = null;
+      }
+    }
     await this.ofrepProvider.onClose?.();
     this._status = ClientProviderStatus.NOT_READY;
   }
+  /**
+   * Stop the polling fallback.
+   */
+  stopPolling() {
+    if (this.pollingTimer) {
+      clearInterval(this.pollingTimer);
+      this.pollingTimer = null;
+      this.isPollingFallbackActive = false;
+    }
+  }
+  /**
+   * Start polling fallback when SSE fails.
+   */
+  startPollingFallback() {
+    if (this.isPollingFallbackActive || !this.enablePollingFallback) return;
+    console.info(`[Flipswitch] Starting polling fallback (interval: ${this.pollingInterval}ms)`);
+    this.isPollingFallbackActive = true;
+    this.pollingTimer = setInterval(async () => {
+      if (!this._isOnline) return;
+      try {
+        await this.refreshFlags();
+      } catch (error) {
+        console.warn("[Flipswitch] Polling refresh failed:", error);
+      }
+    }, this.pollingInterval);
+  }
+  /**
+   * Check if the provider is currently online.
+   */
+  isOnline() {
+    return this._isOnline;
+  }
+  /**
+   * Check if polling fallback is active.
+   */
+  isPollingActive() {
+    return this.isPollingFallbackActive;
+  }
   /**
    * Start the SSE connection for real-time updates.
    */
@@ -335,14 +736,27 @@ var FlipswitchProvider = class {
       (status) => {
         this.userEventHandlers.onConnectionStatusChange?.(status);
         if (status === "error") {
+          this.sseRetryCount++;
+          if (this.sseRetryCount >= this.maxSseRetries && this.enablePollingFallback) {
+            console.warn(`[Flipswitch] SSE failed after ${this.sseRetryCount} retries - falling back to polling`);
+            this.startPollingFallback();
+          }
           this._status = ClientProviderStatus.STALE;
           this.emit(ClientProviderEvents.Stale);
-        } else if (status === "connected" && this._status === ClientProviderStatus.STALE) {
-          this._status = ClientProviderStatus.READY;
-          this.emit(ClientProviderEvents.Ready);
+        } else if (status === "connected") {
+          this.sseRetryCount = 0;
+          if (this.isPollingFallbackActive) {
+            console.info("[Flipswitch] SSE reconnected - stopping polling fallback");
+            this.stopPolling();
+          }
+          if (this._status === ClientProviderStatus.STALE) {
+            this._status = ClientProviderStatus.READY;
+            this.emit(ClientProviderEvents.Ready);
+          }
         }
       },
-      telemetryHeaders
+      telemetryHeaders,
+      this.enableVisibilityHandling
     );
     this.sseClient.connect();
   }
@@ -350,9 +764,6 @@ var FlipswitchProvider = class {
    * Get telemetry headers as a map.
    */
   getTelemetryHeadersMap() {
-    if (!this.enableTelemetry) {
-      return void 0;
-    }
     return {
       "X-Flipswitch-SDK": this.getTelemetrySdkHeader(),
       "X-Flipswitch-Runtime": this.getTelemetryRuntimeHeader(),
@@ -362,10 +773,22 @@ var FlipswitchProvider = class {
   }
   /**
    * Handle a flag change event from SSE.
-   * Emits PROVIDER_CONFIGURATION_CHANGED to trigger re-evaluation.
+   * Triggers OFREP cache refresh, updates browser cache, and emits PROVIDER_CONFIGURATION_CHANGED.
    */
-  handleFlagChange(event) {
+  async handleFlagChange(event) {
     this.userEventHandlers.onFlagChange?.(event);
+    if (this.browserCache) {
+      if (event.flagKey) {
+        this.browserCache.invalidate(event.flagKey);
+      } else {
+        this.browserCache.invalidate();
+      }
+    }
+    try {
+      await this.ofrepProvider.onContextChange?.({}, {});
+    } catch (error) {
+      console.warn("[Flipswitch] Failed to refresh flags after SSE event:", error);
+    }
     this.emit(ClientProviderEvents.ConfigurationChanged);
   }
   /**
@@ -614,6 +1037,7 @@ var FlagCache = class {
   }
 };
 export {
+  BrowserCache,
   FlagCache,
   FlipswitchProvider,
   SseClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flipswitch-io/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Flipswitch SDK with real-time SSE support for OpenFeature",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -56,7 +56,7 @@
     "@openfeature/ofrep-provider": "^0.2.2",
     "@openfeature/server-sdk": "^1.17.0",
     "@openfeature/web-sdk": "^1.7.2",
-    "@types/node": "^20.11.0",
+    "@types/node": "^24.0.0",
     "eslint": "^9.0.0",
     "tsup": "^8.0.1",
     "tsx": "^4.7.0",