@flagix/js-sdk 1.2.0 → 1.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @flagix/js-sdk@1.2.0 build /home/runner/work/flagix/flagix/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
-ESM dist/index.mjs 15.58 KB
-ESM ⚡️ Build success in 46ms
-CJS dist/index.js 17.27 KB
-CJS ⚡️ Build success in 46ms
+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 2398ms
-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,16 @@
 # @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

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,12 @@ 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);
     }
@@ -204,6 +222,9 @@ var FlagixClient = class {
     }
   }
   async setupSSEListener() {
+    if (this.isConnectingSSE) {
+      return;
+    }
     if (this.sseConnection) {
       try {
         this.sseConnection.close();
@@ -216,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(
-            "error",
-            "[Flagix SDK] Failed to refresh cache after reconnection",
+            "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(
+            "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) {
@@ -322,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);
@@ -460,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.
@@ -510,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.
@@ -528,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,12 @@ 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);
     }
@@ -168,6 +186,9 @@ var FlagixClient = class {
     }
   }
   async setupSSEListener() {
+    if (this.isConnectingSSE) {
+      return;
+    }
     if (this.sseConnection) {
       try {
         this.sseConnection.close();
@@ -180,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(
-            "error",
-            "[Flagix SDK] Failed to refresh cache after reconnection",
+            "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(
+            "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) {
@@ -286,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);
@@ -424,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.
@@ -474,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.
@@ -492,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.2.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,7 +149,13 @@ 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);
     }
@@ -172,6 +192,10 @@ export class FlagixClient {
   }
 
   private async setupSSEListener(): Promise<void> {
+    if (this.isConnectingSSE) {
+      return;
+    }
+
     if (this.sseConnection) {
       try {
         this.sseConnection.close();
@@ -185,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.");
-    };
-
-    source.onerror = (error) => {
-      const eventSource = error.target as EventSource;
-      const readyState = eventSource?.readyState;
+      this.sseConnection = source;
 
-      // 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();
-      }
-    };
+      source.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.isReconnecting = false;
+        if (this.reconnectTimeoutId) {
+          clearTimeout(this.reconnectTimeoutId);
+          this.reconnectTimeoutId = null;
+        }
 
-    // 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 {
@@ -324,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;
     }
   },