@flagix/js-sdk 1.1.0 → 1.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @flagix/js-sdk@1.1.0 build /home/runner/work/flagixx/flagixx/sdk/javascript
+> @flagix/js-sdk@1.3.0 build /home/runner/work/flagix/flagix/sdk/javascript
 > tsup src/index.ts --format cjs,esm --dts --clean
 
 CLI Building entry: src/index.ts
@@ -9,11 +9,11 @@
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-CJS dist/index.js 17.16 KB
-CJS ⚡️ Build success in 49ms
-ESM dist/index.mjs 15.47 KB
-ESM ⚡️ Build success in 49ms
+ESM dist/index.mjs 17.07 KB
+ESM ⚡️ Build success in 57ms
+CJS dist/index.js 18.75 KB
+CJS ⚡️ Build success in 58ms
 DTS Build start
-DTS ⚡️ Build success in 1843ms
-DTS dist/index.d.ts  2.30 KB
-DTS dist/index.d.mts 2.30 KB
+DTS ⚡️ Build success in 1849ms
+DTS dist/index.d.ts  2.41 KB
+DTS dist/index.d.mts 2.41 KB

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @flagix/js-sdk
 
+## 1.3.0
+
+### Minor Changes
+
+- 4e879d8: Improved SDK stability and lifecycle management. Added identify method for explicit user identity switching, fixed race conditions during initialization and SSE setup, and ensured feature flags gracefully fallback to 'off' variations when disabled. Fixed potential memory leaks in React hooks and added support for runtime API key changes.
+
+### Patch Changes
+
+- Updated dependencies [4e879d8]
+  - @flagix/evaluation-core@1.2.0
+
+## 1.2.0
+
+### Minor Changes
+
+- 70d02db: feat: implement reactive context synchronization
+
+  - Added 'context' prop to FlagixProvider for automatic SDK syncing.
+  - Updated setContext to trigger real-time updates for all flag listeners.
+  - Improved FlagixProvider stability to prevent unnecessary re-initializations.
+
 ## 1.1.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flagix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -40,6 +40,10 @@ declare const Flagix: {
      * @param contextOverrides Optional context.
      */
     track(eventName: string, properties?: Record<string, unknown>, contextOverrides?: EvaluationContext): void;
+    /**
+     * Replaces the global evaluation context.
+     */
+    identify(newContext: EvaluationContext): void;
     /**
      * Sets or updates the global evaluation context.
      * @param newContext New context attributes to merge or replace.

package/dist/index.d.ts

@@ -40,6 +40,10 @@ declare const Flagix: {
      * @param contextOverrides Optional context.
      */
     track(eventName: string, properties?: Record<string, unknown>, contextOverrides?: EvaluationContext): void;
+    /**
+     * Replaces the global evaluation context.
+     */
+    identify(newContext: EvaluationContext): void;
     /**
      * Sets or updates the global evaluation context.
      * @param newContext New context attributes to merge or replace.

package/dist/index.js

@@ -102,23 +102,27 @@ var FlagixClient = class {
     this.maxReconnectAttempts = Number.POSITIVE_INFINITY;
     this.baseReconnectDelay = 1e3;
     this.maxReconnectDelay = 3e4;
+    this.isConnectingSSE = false;
+    /**
+     * Subscribes a listener to a flag update event.
+     */
+    this.on = (event, listener) => {
+      this.emitter.on(event, listener);
+    };
+    /**
+     * Unsubscribes a listener from a flag update event.
+     */
+    this.off = (event, listener) => {
+      this.emitter.off(event, listener);
+    };
     this.apiKey = options.apiKey;
     this.apiBaseUrl = options.apiBaseUrl.replace(REMOVE_TRAILING_SLASH, "");
     this.context = options.initialContext || {};
     this.emitter = new FlagixEventEmitter();
     setLogLevel(options.logs?.level ?? "none");
   }
-  /**
-   * Subscribes a listener to a flag update event.
-   */
-  on(event, listener) {
-    this.emitter.on(event, listener);
-  }
-  /**
-   * Unsubscribes a listener from a flag update event.
-   */
-  off(event, listener) {
-    this.emitter.off(event, listener);
+  getApiKey() {
+    return this.apiKey;
   }
   /**
    * Fetches all flag configurations from the API, populates the local cache,
@@ -164,6 +168,14 @@ var FlagixClient = class {
     }
     return result?.value ?? null;
   }
+  /**
+   * Replaces the global evaluation context.
+   */
+  identify(newContext) {
+    this.context = newContext;
+    log("info", "[Flagix SDK] Context replaced");
+    this.refreshAllFlags();
+  }
   /**
    * Sets or updates the global evaluation context.
    * @param newContext New context attributes to merge or replace.
@@ -174,6 +186,15 @@ var FlagixClient = class {
       "info",
       "[Flagix SDK] Context updated. Evaluations will use the new context."
     );
+    this.refreshAllFlags();
+  }
+  /**
+   * Helper to refresh all flags by emitting update events for each cached flag.
+   */
+  refreshAllFlags() {
+    for (const flagKey of this.localCache.keys()) {
+      this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
+    }
   }
   async fetchInitialConfig() {
     const url = `${this.apiBaseUrl}/api/flag-config/all`;
@@ -201,6 +222,9 @@ var FlagixClient = class {
     }
   }
   async setupSSEListener() {
+    if (this.isConnectingSSE) {
+      return;
+    }
     if (this.sseConnection) {
       try {
         this.sseConnection.close();
@@ -213,71 +237,83 @@ var FlagixClient = class {
       }
       this.sseConnection = null;
     }
+    this.isConnectingSSE = true;
     const url = `${this.apiBaseUrl}/api/sse/stream`;
-    const source = await createEventSource(url, this.apiKey);
-    if (!source) {
-      log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
-      this.scheduleReconnect();
-      return;
-    }
-    this.sseConnection = source;
-    source.onopen = () => {
-      this.reconnectAttempts = 0;
-      this.isReconnecting = false;
-      if (this.reconnectTimeoutId) {
-        clearTimeout(this.reconnectTimeoutId);
-        this.reconnectTimeoutId = null;
+    try {
+      const source = await createEventSource(url, this.apiKey);
+      if (!source) {
+        log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
+        this.scheduleReconnect();
+        return;
       }
-      if (this.hasEstablishedConnection && this.isInitialized) {
-        log(
-          "info",
-          "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
-        );
-        this.fetchInitialConfig().catch((error) => {
+      if (!this.isInitialized && !this.isReconnecting) {
+        source.close();
+        return;
+      }
+      this.sseConnection = source;
+      source.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.isReconnecting = false;
+        if (this.reconnectTimeoutId) {
+          clearTimeout(this.reconnectTimeoutId);
+          this.reconnectTimeoutId = null;
+        }
+        if (this.hasEstablishedConnection && this.isInitialized) {
+          log(
+            "info",
+            "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
+          );
+          this.fetchInitialConfig().catch((error) => {
+            log(
+              "error",
+              "[Flagix SDK] Failed to refresh cache after reconnection",
+              error
+            );
+          });
+        } else {
+          this.hasEstablishedConnection = true;
+        }
+        log("info", "[Flagix SDK] SSE connection established.");
+      };
+      source.onerror = (error) => {
+        const eventSource = error.target;
+        const readyState = eventSource?.readyState;
+        if (readyState === 2) {
+          log(
+            "warn",
+            "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
+          );
+          this.handleReconnect();
+        } else if (readyState === 0) {
           log(
-            "error",
-            "[Flagix SDK] Failed to refresh cache after reconnection",
+            "warn",
+            "[Flagix SDK] SSE connection error (connecting state)",
             error
           );
-        });
-      } else {
-        this.hasEstablishedConnection = true;
-      }
-      log("info", "[Flagix SDK] SSE connection established.");
-    };
-    source.onerror = (error) => {
-      const eventSource = error.target;
-      const readyState = eventSource?.readyState;
-      if (readyState === 2) {
-        log(
-          "warn",
-          "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
-        );
-        this.handleReconnect();
-      } else if (readyState === 0) {
-        log(
-          "warn",
-          "[Flagix SDK] SSE connection error (connecting state)",
-          error
-        );
-      } else {
-        log("error", "[Flagix SDK] SSE error", error);
-        this.handleReconnect();
-      }
-    };
-    source.addEventListener("connected", () => {
-      log("info", "[Flagix SDK] SSE connection confirmed by server.");
-    });
-    source.addEventListener(EVENT_TO_LISTEN, (event) => {
-      try {
-        const data = JSON.parse(event.data);
-        const { flagKey, type } = data;
-        log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
-        this.fetchSingleFlagConfig(flagKey, type);
-      } catch (error) {
-        log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
-      }
-    });
+        } else {
+          log("error", "[Flagix SDK] SSE error", error);
+          this.handleReconnect();
+        }
+      };
+      source.addEventListener("connected", () => {
+        log("info", "[Flagix SDK] SSE connection confirmed by server.");
+      });
+      source.addEventListener(EVENT_TO_LISTEN, (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          const { flagKey, type } = data;
+          log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
+          this.fetchSingleFlagConfig(flagKey, type);
+        } catch (error) {
+          log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
+        }
+      });
+    } catch (error) {
+      log("error", "[Flagix SDK] Failed during SSE setup", error);
+      this.handleReconnect();
+    } finally {
+      this.isConnectingSSE = false;
+    }
   }
   handleReconnect() {
     if (this.isReconnecting || !this.isInitialized) {
@@ -319,7 +355,7 @@ var FlagixClient = class {
   }
   async fetchSingleFlagConfig(flagKey, type) {
     const url = `${this.apiBaseUrl}/api/flag-config/${flagKey}`;
-    if (type === "FLAG_DELETED" || type === "RULE_DELETED") {
+    if (type === "FLAG_DELETED") {
       this.localCache.delete(flagKey);
       log("info", `[Flagix SDK] Flag ${flagKey} deleted from cache.`);
       this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
@@ -457,24 +493,37 @@ var Flagix = {
    */
   async initialize(options) {
     if (clientInstance) {
-      log("warn", "Flagix SDK already initialized. Ignoring subsequent call.");
-      return;
+      if (clientInstance.getApiKey() === options.apiKey) {
+        if (clientInstance.getIsInitialized()) {
+          return;
+        }
+        if (isInitializing && initializationPromise) {
+          return initializationPromise;
+        }
+      } else {
+        log(
+          "info",
+          "[Flagix SDK] API Key change detected. Resetting client..."
+        );
+        this.close();
+      }
     }
     if (isInitializing && initializationPromise) {
       return initializationPromise;
     }
     isInitializing = true;
-    try {
-      clientInstance = new FlagixClient(options);
-      initializationPromise = clientInstance.initialize();
-      await initializationPromise;
-    } catch (error) {
-      log("error", "Flagix SDK failed during initialization:", error);
-      throw error;
-    } finally {
-      isInitializing = false;
-      initializationPromise = null;
-    }
+    initializationPromise = (async () => {
+      try {
+        clientInstance = new FlagixClient(options);
+        await clientInstance.initialize();
+      } catch (error) {
+        clientInstance = null;
+        throw error;
+      } finally {
+        isInitializing = false;
+      }
+    })();
+    return await initializationPromise;
   },
   /**
    * Evaluates a flag based on the local cache and current context.
@@ -507,6 +556,16 @@ var Flagix = {
     }
     clientInstance.track(eventName, properties, contextOverrides);
   },
+  /**
+   * Replaces the global evaluation context.
+   */
+  identify(newContext) {
+    if (!clientInstance) {
+      log("error", "Flagix SDK not initialized.");
+      return;
+    }
+    clientInstance.identify(newContext);
+  },
   /**
    * Sets or updates the global evaluation context.
    * @param newContext New context attributes to merge or replace.
@@ -525,6 +584,8 @@ var Flagix = {
     if (clientInstance) {
       clientInstance.close();
       clientInstance = null;
+      initializationPromise = null;
+      isInitializing = false;
     }
   },
   /**

package/dist/index.mjs

@@ -66,23 +66,27 @@ var FlagixClient = class {
     this.maxReconnectAttempts = Number.POSITIVE_INFINITY;
     this.baseReconnectDelay = 1e3;
     this.maxReconnectDelay = 3e4;
+    this.isConnectingSSE = false;
+    /**
+     * Subscribes a listener to a flag update event.
+     */
+    this.on = (event, listener) => {
+      this.emitter.on(event, listener);
+    };
+    /**
+     * Unsubscribes a listener from a flag update event.
+     */
+    this.off = (event, listener) => {
+      this.emitter.off(event, listener);
+    };
     this.apiKey = options.apiKey;
     this.apiBaseUrl = options.apiBaseUrl.replace(REMOVE_TRAILING_SLASH, "");
     this.context = options.initialContext || {};
     this.emitter = new FlagixEventEmitter();
     setLogLevel(options.logs?.level ?? "none");
   }
-  /**
-   * Subscribes a listener to a flag update event.
-   */
-  on(event, listener) {
-    this.emitter.on(event, listener);
-  }
-  /**
-   * Unsubscribes a listener from a flag update event.
-   */
-  off(event, listener) {
-    this.emitter.off(event, listener);
+  getApiKey() {
+    return this.apiKey;
   }
   /**
    * Fetches all flag configurations from the API, populates the local cache,
@@ -128,6 +132,14 @@ var FlagixClient = class {
     }
     return result?.value ?? null;
   }
+  /**
+   * Replaces the global evaluation context.
+   */
+  identify(newContext) {
+    this.context = newContext;
+    log("info", "[Flagix SDK] Context replaced");
+    this.refreshAllFlags();
+  }
   /**
    * Sets or updates the global evaluation context.
    * @param newContext New context attributes to merge or replace.
@@ -138,6 +150,15 @@ var FlagixClient = class {
       "info",
       "[Flagix SDK] Context updated. Evaluations will use the new context."
     );
+    this.refreshAllFlags();
+  }
+  /**
+   * Helper to refresh all flags by emitting update events for each cached flag.
+   */
+  refreshAllFlags() {
+    for (const flagKey of this.localCache.keys()) {
+      this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
+    }
   }
   async fetchInitialConfig() {
     const url = `${this.apiBaseUrl}/api/flag-config/all`;
@@ -165,6 +186,9 @@ var FlagixClient = class {
     }
   }
   async setupSSEListener() {
+    if (this.isConnectingSSE) {
+      return;
+    }
     if (this.sseConnection) {
       try {
         this.sseConnection.close();
@@ -177,71 +201,83 @@ var FlagixClient = class {
       }
       this.sseConnection = null;
     }
+    this.isConnectingSSE = true;
     const url = `${this.apiBaseUrl}/api/sse/stream`;
-    const source = await createEventSource(url, this.apiKey);
-    if (!source) {
-      log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
-      this.scheduleReconnect();
-      return;
-    }
-    this.sseConnection = source;
-    source.onopen = () => {
-      this.reconnectAttempts = 0;
-      this.isReconnecting = false;
-      if (this.reconnectTimeoutId) {
-        clearTimeout(this.reconnectTimeoutId);
-        this.reconnectTimeoutId = null;
+    try {
+      const source = await createEventSource(url, this.apiKey);
+      if (!source) {
+        log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
+        this.scheduleReconnect();
+        return;
       }
-      if (this.hasEstablishedConnection && this.isInitialized) {
-        log(
-          "info",
-          "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
-        );
-        this.fetchInitialConfig().catch((error) => {
+      if (!this.isInitialized && !this.isReconnecting) {
+        source.close();
+        return;
+      }
+      this.sseConnection = source;
+      source.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.isReconnecting = false;
+        if (this.reconnectTimeoutId) {
+          clearTimeout(this.reconnectTimeoutId);
+          this.reconnectTimeoutId = null;
+        }
+        if (this.hasEstablishedConnection && this.isInitialized) {
+          log(
+            "info",
+            "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
+          );
+          this.fetchInitialConfig().catch((error) => {
+            log(
+              "error",
+              "[Flagix SDK] Failed to refresh cache after reconnection",
+              error
+            );
+          });
+        } else {
+          this.hasEstablishedConnection = true;
+        }
+        log("info", "[Flagix SDK] SSE connection established.");
+      };
+      source.onerror = (error) => {
+        const eventSource = error.target;
+        const readyState = eventSource?.readyState;
+        if (readyState === 2) {
+          log(
+            "warn",
+            "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
+          );
+          this.handleReconnect();
+        } else if (readyState === 0) {
           log(
-            "error",
-            "[Flagix SDK] Failed to refresh cache after reconnection",
+            "warn",
+            "[Flagix SDK] SSE connection error (connecting state)",
             error
           );
-        });
-      } else {
-        this.hasEstablishedConnection = true;
-      }
-      log("info", "[Flagix SDK] SSE connection established.");
-    };
-    source.onerror = (error) => {
-      const eventSource = error.target;
-      const readyState = eventSource?.readyState;
-      if (readyState === 2) {
-        log(
-          "warn",
-          "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
-        );
-        this.handleReconnect();
-      } else if (readyState === 0) {
-        log(
-          "warn",
-          "[Flagix SDK] SSE connection error (connecting state)",
-          error
-        );
-      } else {
-        log("error", "[Flagix SDK] SSE error", error);
-        this.handleReconnect();
-      }
-    };
-    source.addEventListener("connected", () => {
-      log("info", "[Flagix SDK] SSE connection confirmed by server.");
-    });
-    source.addEventListener(EVENT_TO_LISTEN, (event) => {
-      try {
-        const data = JSON.parse(event.data);
-        const { flagKey, type } = data;
-        log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
-        this.fetchSingleFlagConfig(flagKey, type);
-      } catch (error) {
-        log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
-      }
-    });
+        } else {
+          log("error", "[Flagix SDK] SSE error", error);
+          this.handleReconnect();
+        }
+      };
+      source.addEventListener("connected", () => {
+        log("info", "[Flagix SDK] SSE connection confirmed by server.");
+      });
+      source.addEventListener(EVENT_TO_LISTEN, (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          const { flagKey, type } = data;
+          log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
+          this.fetchSingleFlagConfig(flagKey, type);
+        } catch (error) {
+          log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
+        }
+      });
+    } catch (error) {
+      log("error", "[Flagix SDK] Failed during SSE setup", error);
+      this.handleReconnect();
+    } finally {
+      this.isConnectingSSE = false;
+    }
   }
   handleReconnect() {
     if (this.isReconnecting || !this.isInitialized) {
@@ -283,7 +319,7 @@ var FlagixClient = class {
   }
   async fetchSingleFlagConfig(flagKey, type) {
     const url = `${this.apiBaseUrl}/api/flag-config/${flagKey}`;
-    if (type === "FLAG_DELETED" || type === "RULE_DELETED") {
+    if (type === "FLAG_DELETED") {
       this.localCache.delete(flagKey);
       log("info", `[Flagix SDK] Flag ${flagKey} deleted from cache.`);
       this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
@@ -421,24 +457,37 @@ var Flagix = {
    */
   async initialize(options) {
     if (clientInstance) {
-      log("warn", "Flagix SDK already initialized. Ignoring subsequent call.");
-      return;
+      if (clientInstance.getApiKey() === options.apiKey) {
+        if (clientInstance.getIsInitialized()) {
+          return;
+        }
+        if (isInitializing && initializationPromise) {
+          return initializationPromise;
+        }
+      } else {
+        log(
+          "info",
+          "[Flagix SDK] API Key change detected. Resetting client..."
+        );
+        this.close();
+      }
     }
     if (isInitializing && initializationPromise) {
       return initializationPromise;
     }
     isInitializing = true;
-    try {
-      clientInstance = new FlagixClient(options);
-      initializationPromise = clientInstance.initialize();
-      await initializationPromise;
-    } catch (error) {
-      log("error", "Flagix SDK failed during initialization:", error);
-      throw error;
-    } finally {
-      isInitializing = false;
-      initializationPromise = null;
-    }
+    initializationPromise = (async () => {
+      try {
+        clientInstance = new FlagixClient(options);
+        await clientInstance.initialize();
+      } catch (error) {
+        clientInstance = null;
+        throw error;
+      } finally {
+        isInitializing = false;
+      }
+    })();
+    return await initializationPromise;
   },
   /**
    * Evaluates a flag based on the local cache and current context.
@@ -471,6 +520,16 @@ var Flagix = {
     }
     clientInstance.track(eventName, properties, contextOverrides);
   },
+  /**
+   * Replaces the global evaluation context.
+   */
+  identify(newContext) {
+    if (!clientInstance) {
+      log("error", "Flagix SDK not initialized.");
+      return;
+    }
+    clientInstance.identify(newContext);
+  },
   /**
    * Sets or updates the global evaluation context.
    * @param newContext New context attributes to merge or replace.
@@ -489,6 +548,8 @@ var Flagix = {
     if (clientInstance) {
       clientInstance.close();
       clientInstance = null;
+      initializationPromise = null;
+      isInitializing = false;
     }
   },
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flagix/js-sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Flagix Javascript SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -30,7 +30,7 @@
   "dependencies": {
     "eventemitter3": "^5.0.1",
     "eventsource": "^4.1.0",
-    "@flagix/evaluation-core": "^1.1.0"
+    "@flagix/evaluation-core": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/client.ts

@@ -37,6 +37,7 @@ export class FlagixClient {
   private readonly maxReconnectAttempts = Number.POSITIVE_INFINITY;
   private readonly baseReconnectDelay = 1000;
   private readonly maxReconnectDelay = 30_000;
+  private isConnectingSSE = false;
 
   constructor(options: FlagixClientOptions) {
     this.apiKey = options.apiKey;
@@ -49,21 +50,25 @@ export class FlagixClient {
   /**
    * Subscribes a listener to a flag update event.
    */
-  on(
+  on = (
     event: typeof FLAG_UPDATE_EVENT,
     listener: (flagKey: string) => void
-  ): void {
+  ) => {
     this.emitter.on(event, listener);
-  }
+  };
 
   /**
    * Unsubscribes a listener from a flag update event.
    */
-  off(
+  off = (
     event: typeof FLAG_UPDATE_EVENT,
     listener: (flagKey: string) => void
-  ): void {
+  ) => {
     this.emitter.off(event, listener);
+  };
+
+  getApiKey(): string {
+    return this.apiKey;
   }
 
   /**
@@ -125,6 +130,15 @@ export class FlagixClient {
     return (result?.value as T) ?? null;
   }
 
+  /**
+   * Replaces the global evaluation context.
+   */
+  identify(newContext: EvaluationContext): void {
+    this.context = newContext;
+    log("info", "[Flagix SDK] Context replaced");
+    this.refreshAllFlags();
+  }
+
   /**
    * Sets or updates the global evaluation context.
    * @param newContext New context attributes to merge or replace.
@@ -135,6 +149,16 @@ export class FlagixClient {
       "info",
       "[Flagix SDK] Context updated. Evaluations will use the new context."
     );
+    this.refreshAllFlags();
+  }
+
+  /**
+   * Helper to refresh all flags by emitting update events for each cached flag.
+   */
+  private refreshAllFlags(): void {
+    for (const flagKey of this.localCache.keys()) {
+      this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
+    }
   }
 
   private async fetchInitialConfig(): Promise<void> {
@@ -168,6 +192,10 @@ export class FlagixClient {
   }
 
   private async setupSSEListener(): Promise<void> {
+    if (this.isConnectingSSE) {
+      return;
+    }
+
     if (this.sseConnection) {
       try {
         this.sseConnection.close();
@@ -181,89 +209,102 @@ export class FlagixClient {
       this.sseConnection = null;
     }
 
+    this.isConnectingSSE = true;
     const url = `${this.apiBaseUrl}/api/sse/stream`;
 
-    const source = await createEventSource(url, this.apiKey);
-    if (!source) {
-      log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
-      this.scheduleReconnect();
-      return;
-    }
-
-    this.sseConnection = source;
-
-    source.onopen = () => {
-      this.reconnectAttempts = 0;
-      this.isReconnecting = false;
-      if (this.reconnectTimeoutId) {
-        clearTimeout(this.reconnectTimeoutId);
-        this.reconnectTimeoutId = null;
+    try {
+      const source = await createEventSource(url, this.apiKey);
+      if (!source) {
+        log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
+        this.scheduleReconnect();
+        return;
       }
 
-      // If this is a reconnection and not the first connection, refresh the cache
-      // this ensures we have the latest flag values that may have changed while disconnected
-      if (this.hasEstablishedConnection && this.isInitialized) {
-        log(
-          "info",
-          "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
-        );
-        this.fetchInitialConfig().catch((error) => {
-          log(
-            "error",
-            "[Flagix SDK] Failed to refresh cache after reconnection",
-            error
-          );
-        });
-      } else {
-        this.hasEstablishedConnection = true;
+      if (!this.isInitialized && !this.isReconnecting) {
+        source.close();
+        return;
       }
 
-      log("info", "[Flagix SDK] SSE connection established.");
-    };
+      this.sseConnection = source;
 
-    source.onerror = (error) => {
-      const eventSource = error.target as EventSource;
-      const readyState = eventSource?.readyState;
+      source.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.isReconnecting = false;
+        if (this.reconnectTimeoutId) {
+          clearTimeout(this.reconnectTimeoutId);
+          this.reconnectTimeoutId = null;
+        }
 
-      // EventSource.readyState: 0 = CONNECTING, 1 = OPEN, 2 = CLOSED
-      if (readyState === 2) {
-        log(
-          "warn",
-          "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
-        );
-        this.handleReconnect();
-      } else if (readyState === 0) {
-        log(
-          "warn",
-          "[Flagix SDK] SSE connection error (connecting state)",
-          error
-        );
-      } else {
-        log("error", "[Flagix SDK] SSE error", error);
-        this.handleReconnect();
-      }
-    };
-
-    // Listen for the "connected" event from the server
-    source.addEventListener("connected", () => {
-      log("info", "[Flagix SDK] SSE connection confirmed by server.");
-    });
+        // If this is a reconnection and not the first connection, refresh the cache
+        // this ensures we have the latest flag values that may have changed while disconnected
+        if (this.hasEstablishedConnection && this.isInitialized) {
+          log(
+            "info",
+            "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
+          );
+          this.fetchInitialConfig().catch((error) => {
+            log(
+              "error",
+              "[Flagix SDK] Failed to refresh cache after reconnection",
+              error
+            );
+          });
+        } else {
+          this.hasEstablishedConnection = true;
+        }
+
+        log("info", "[Flagix SDK] SSE connection established.");
+      };
+
+      source.onerror = (error) => {
+        const eventSource = error.target as EventSource;
+        const readyState = eventSource?.readyState;
+
+        // EventSource.readyState: 0 = CONNECTING, 1 = OPEN, 2 = CLOSED
+        if (readyState === 2) {
+          log(
+            "warn",
+            "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
+          );
+          this.handleReconnect();
+        } else if (readyState === 0) {
+          log(
+            "warn",
+            "[Flagix SDK] SSE connection error (connecting state)",
+            error
+          );
+        } else {
+          log("error", "[Flagix SDK] SSE error", error);
+          this.handleReconnect();
+        }
+      };
+
+      // Listen for the "connected" event from the server
+      source.addEventListener("connected", () => {
+        log("info", "[Flagix SDK] SSE connection confirmed by server.");
+      });
 
-    source.addEventListener(EVENT_TO_LISTEN, (event) => {
-      try {
-        const data = JSON.parse(event.data);
-        const { flagKey, type } = data as {
-          flagKey: string;
-          type: FlagUpdateType;
-        };
+      source.addEventListener(EVENT_TO_LISTEN, (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          const { flagKey, type } = data as {
+            flagKey: string;
+            type: FlagUpdateType;
+          };
 
-        log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
+          log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
 
-        this.fetchSingleFlagConfig(flagKey, type);
-      } catch (error) {
-        log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
-      }
-    });
+          this.fetchSingleFlagConfig(flagKey, type);
+        } catch (error) {
+          log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
+        }
+      });
+    } catch (error) {
+      log("error", "[Flagix SDK] Failed during SSE setup", error);
+      this.handleReconnect();
+    } finally {
+      this.isConnectingSSE = false;
+    }
   }
 
   private handleReconnect(): void {
@@ -320,7 +361,7 @@ export class FlagixClient {
   ): Promise<void> {
     const url = `${this.apiBaseUrl}/api/flag-config/${flagKey}`;
 
-    if (type === "FLAG_DELETED" || type === "RULE_DELETED") {
+    if (type === "FLAG_DELETED") {
       this.localCache.delete(flagKey);
       log("info", `[Flagix SDK] Flag ${flagKey} deleted from cache.`);
       this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);

package/src/index.ts

@@ -17,9 +17,24 @@ export const Flagix = {
    * Initializes the Flagix SDK, fetches all flags, and sets up an SSE connection.
    */
   async initialize(options: FlagixClientOptions): Promise<void> {
+    // this check ensures that we are able to watch for api key changes and re-initialize accordingly
+    // this ensures we dont use stale clients across different api keys
     if (clientInstance) {
-      log("warn", "Flagix SDK already initialized. Ignoring subsequent call.");
-      return;
+      if (clientInstance.getApiKey() === options.apiKey) {
+        if (clientInstance.getIsInitialized()) {
+          return;
+        }
+
+        if (isInitializing && initializationPromise) {
+          return initializationPromise;
+        }
+      } else {
+        log(
+          "info",
+          "[Flagix SDK] API Key change detected. Resetting client..."
+        );
+        this.close();
+      }
     }
 
     if (isInitializing && initializationPromise) {
@@ -28,17 +43,19 @@ export const Flagix = {
 
     isInitializing = true;
 
-    try {
-      clientInstance = new FlagixClient(options);
-      initializationPromise = clientInstance.initialize();
-      await initializationPromise;
-    } catch (error) {
-      log("error", "Flagix SDK failed during initialization:", error);
-      throw error;
-    } finally {
-      isInitializing = false;
-      initializationPromise = null;
-    }
+    initializationPromise = (async () => {
+      try {
+        clientInstance = new FlagixClient(options);
+        await clientInstance.initialize();
+      } catch (error) {
+        clientInstance = null;
+        throw error;
+      } finally {
+        isInitializing = false;
+      }
+    })();
+
+    return await initializationPromise;
   },
 
   /**
@@ -82,6 +99,17 @@ export const Flagix = {
     clientInstance.track(eventName, properties, contextOverrides);
   },
 
+  /**
+   * Replaces the global evaluation context.
+   */
+  identify(newContext: EvaluationContext): void {
+    if (!clientInstance) {
+      log("error", "Flagix SDK not initialized.");
+      return;
+    }
+    clientInstance.identify(newContext);
+  },
+
   /**
    * Sets or updates the global evaluation context.
    * @param newContext New context attributes to merge or replace.
@@ -101,6 +129,8 @@ export const Flagix = {
     if (clientInstance) {
       clientInstance.close();
       clientInstance = null;
+      initializationPromise = null;
+      isInitializing = false;
     }
   },