@schematichq/schematic-react 1.2.9 → 1.2.12

package/README.md

@@ -136,6 +136,43 @@ const MyComponent = () => {
 
 *Note: `useSchematicIsPending` is checking if entitlement data has been loaded, typically via `identify`. It should, therefore, be used to wrap flag and entitlement checks, but never the initial call to `identify`.*
 
+## React Native
+
+### Handling app background/foreground
+
+When a React Native app is backgrounded for an extended period, the WebSocket connection may be closed by the OS. When the app returns to the foreground, the connection will automatically reconnect, but this happens on an exponential backoff timer which may cause a delay before fresh flag values are available.
+
+For cases where you need immediate flag updates when returning to the foreground (e.g., after an in-app purchase), you can use one of these methods to re-establish the connection:
+
+- `forceReconnect()`: Always closes and re-establishes the WebSocket connection, guaranteeing fresh values
+- `reconnectIfNeeded()`: Only reconnects if the current connection is unhealthy (more efficient for frequent foreground events)
+
+```tsx
+import { useSchematic } from "@schematichq/schematic-react";
+import { useEffect } from "react";
+import { AppState } from "react-native";
+
+const SchematicAppStateHandler = () => {
+    const { client } = useSchematic();
+
+    useEffect(() => {
+        const subscription = AppState.addEventListener("change", (state) => {
+            if (state === "active") {
+                // Use forceReconnect() for guaranteed fresh values
+                client.forceReconnect();
+                // Or use reconnectIfNeeded() to skip if connection is healthy
+                // client.reconnectIfNeeded();
+            }
+        });
+        return () => subscription.remove();
+    }, [client]);
+
+    return null;
+};
+```
+
+Render this inside your `SchematicProvider`.
+
 ## Troubleshooting
 
 For debugging and development, Schematic supports two special modes:

package/dist/schematic-react.cjs.js

@@ -799,7 +799,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.9";
+var version = "1.2.12";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -829,6 +829,8 @@ var Schematic = class {
   wsReconnectAttempts = 0;
   wsReconnectTimer = null;
   wsIntentionalDisconnect = false;
+  currentWebSocket = null;
+  isConnecting = false;
   maxEventQueueSize = 100;
   // Prevent memory issues with very long network outages
   maxEventRetries = 5;
@@ -1106,6 +1108,49 @@ var Schematic = class {
       console.log(`[Schematic] ${message}`, ...args);
     }
   }
+  /**
+   * Create a persistent message handler for websocket flag updates
+   */
+  createPersistentMessageHandler(context) {
+    return (event) => {
+      const message = JSON.parse(event.data);
+      this.debug(`WebSocket persistent message received:`, message);
+      if (!(contextString(context) in this.checks)) {
+        this.checks[contextString(context)] = {};
+      }
+      (message.flags ?? []).forEach((flag) => {
+        const flagCheck = CheckFlagReturnFromJSON(flag);
+        const contextStr = contextString(context);
+        if (this.checks[contextStr] === void 0) {
+          this.checks[contextStr] = {};
+        }
+        this.checks[contextStr][flagCheck.flag] = flagCheck;
+        this.debug(`WebSocket flag update:`, {
+          flag: flagCheck.flag,
+          value: flagCheck.value,
+          flagCheck
+        });
+        if (typeof flagCheck.featureUsageEvent === "string") {
+          this.updateFeatureUsageEventMap(flagCheck);
+        }
+        if ((this.flagCheckListeners[flag.flag]?.size ?? 0) > 0 || (this.flagValueListeners[flag.flag]?.size ?? 0) > 0) {
+          this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
+        }
+        this.debug(`About to notify listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+        this.notifyFlagCheckListeners(flag.flag, flagCheck);
+        this.notifyFlagValueListeners(flag.flag, flagCheck.value);
+        this.debug(`Finished notifying listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+      });
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+    };
+  }
   /**
    * Helper function to check if client is in offline mode
    */
@@ -1257,6 +1302,19 @@ var Schematic = class {
     try {
       this.setIsPending(true);
       if (!this.conn) {
+        if (this.isConnecting) {
+          this.debug(
+            `Connection already in progress, waiting for it to complete`
+          );
+          while (this.isConnecting && this.conn === null) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+          }
+          if (this.conn !== null) {
+            const socket2 = await this.conn;
+            await this.wsSendMessage(socket2, context);
+            return;
+          }
+        }
         if (this.wsReconnectTimer !== null) {
           this.debug(
             `Cancelling scheduled reconnection, connecting immediately`
@@ -1264,7 +1322,17 @@ var Schematic = class {
           clearTimeout(this.wsReconnectTimer);
           this.wsReconnectTimer = null;
         }
-        this.conn = this.wsConnect();
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket2 = await this.conn;
+          this.isConnecting = false;
+          await this.wsSendMessage(socket2, context);
+          return;
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
+        }
       }
       const socket = await this.conn;
       await this.wsSendMessage(socket, context);
@@ -1429,10 +1497,14 @@ var Schematic = class {
       }
     }
     if (readyEvents.length === 0) {
-      this.debug(`No events ready for retry yet (${notReadyEvents.length} still in backoff)`);
+      this.debug(
+        `No events ready for retry yet (${notReadyEvents.length} still in backoff)`
+      );
       return;
     }
-    this.debug(`Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`);
+    this.debug(
+      `Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`
+    );
     this.eventQueue = notReadyEvents;
     for (const event of readyEvents) {
       try {
@@ -1497,7 +1569,10 @@ var Schematic = class {
     } catch (error) {
       const retryCount = (event.retry_count ?? 0) + 1;
       if (retryCount <= this.maxEventRetries) {
-        this.debug(`Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`, error);
+        this.debug(
+          `Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`,
+          error
+        );
         const baseDelay = this.eventRetryInitialDelay * Math.pow(2, retryCount - 1);
         const jitterDelay = Math.min(baseDelay, this.eventRetryMaxDelay);
         const nextRetryAt = Date.now() + jitterDelay;
@@ -1508,15 +1583,22 @@ var Schematic = class {
         };
         if (this.eventQueue.length < this.maxEventQueueSize) {
           this.eventQueue.push(retryEvent);
-          this.debug(`Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`);
+          this.debug(
+            `Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`
+          );
         } else {
-          this.debug(`Event queue full (${this.maxEventQueueSize}), dropping oldest event`);
+          this.debug(
+            `Event queue full (${this.maxEventQueueSize}), dropping oldest event`
+          );
           this.eventQueue.shift();
           this.eventQueue.push(retryEvent);
         }
         this.startRetryTimer();
       } else {
-        this.debug(`Event failed permanently after ${this.maxEventRetries} attempts, dropping:`, error);
+        this.debug(
+          `Event failed permanently after ${this.maxEventRetries} attempts, dropping:`,
+          error
+        );
       }
     }
     return Promise.resolve();
@@ -1528,6 +1610,130 @@ var Schematic = class {
   /**
    * Websocket management
    */
+  /**
+   * Force an immediate WebSocket reconnection.
+   * This is useful when the application returns from a background state (e.g., mobile app
+   * coming back to foreground) and wants to immediately re-establish the connection
+   * rather than waiting for the exponential backoff timer.
+   *
+   * This method will:
+   * - Cancel any pending reconnection timer
+   * - Reset the reconnection attempt counter
+   * - Close any existing connection
+   * - Immediately attempt to reconnect
+   * - Re-send the current context to get fresh flag values
+   *
+   * Use this when you need guaranteed fresh values (e.g., after an in-app purchase).
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.forceReconnect();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  forceReconnect = async () => {
+    return this.reconnect({ force: true });
+  };
+  /**
+   * Reconnect the WebSocket connection only if the current connection is unhealthy.
+   * This is useful when the application returns from a background state and wants to
+   * ensure a healthy connection exists, but doesn't need to force a reconnection if
+   * the connection is still active.
+   *
+   * This method will:
+   * - Check if an existing connection is healthy (readyState === OPEN)
+   * - If healthy, return immediately without reconnecting
+   * - If unhealthy, perform the same reconnection logic as forceReconnect()
+   *
+   * Use this when you want efficient reconnection that avoids unnecessary disconnects.
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect only if needed when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.reconnectIfNeeded();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  reconnectIfNeeded = async () => {
+    return this.reconnect({ force: false });
+  };
+  /**
+   * Internal method to handle reconnection logic for both forceReconnect and reconnectIfNeeded.
+   */
+  reconnect = async (options) => {
+    const { force } = options;
+    const methodName = force ? "forceReconnect" : "reconnectIfNeeded";
+    if (this.isOffline()) {
+      this.debug(`${methodName}: skipped (offline mode)`);
+      return Promise.resolve();
+    }
+    if (!force && this.conn !== null) {
+      try {
+        const existingSocket = await this.conn;
+        if (existingSocket.readyState === WebSocket.OPEN) {
+          this.debug(`${methodName}: connection is healthy, skipping`);
+          return Promise.resolve();
+        }
+      } catch {
+      }
+    }
+    this.debug(
+      `${methodName}: ${force ? "forcing immediate reconnection" : "reconnecting"}`
+    );
+    this.wsIntentionalDisconnect = false;
+    if (this.wsReconnectTimer !== null) {
+      this.debug(`${methodName}: cancelling pending reconnection timer`);
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    this.wsReconnectAttempts = 0;
+    if (this.conn !== null) {
+      this.debug(`${methodName}: closing existing connection`);
+      try {
+        const existingSocket = await this.conn;
+        if (this.currentWebSocket === existingSocket) {
+          this.currentWebSocket = null;
+        }
+        if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+          existingSocket.close();
+        }
+      } catch (error) {
+        this.debug(`${methodName}: error closing existing connection:`, error);
+      }
+      this.conn = null;
+      this.isConnecting = false;
+    }
+    if (this.context.company !== void 0 || this.context.user !== void 0) {
+      this.debug(`${methodName}: reconnecting with existing context`);
+      try {
+        this.isConnecting = true;
+        this.conn = this.wsConnect();
+        const socket = await this.conn;
+        this.isConnecting = false;
+        await this.wsSendMessage(socket, this.context, true);
+        this.debug(`${methodName}: reconnection successful`);
+      } catch (error) {
+        this.isConnecting = false;
+        this.debug(`${methodName}: reconnection failed:`, error);
+      }
+    } else {
+      this.debug(`${methodName}: no context set, skipping reconnection`);
+    }
+    return Promise.resolve();
+  };
   /**
    * If using websocket mode, close the connection when done.
    * In offline mode, this is a no-op.
@@ -1546,11 +1752,17 @@ var Schematic = class {
     if (this.conn) {
       try {
         const socket = await this.conn;
+        if (this.currentWebSocket === socket) {
+          this.debug(`Cleaning up current websocket tracking`);
+          this.currentWebSocket = null;
+        }
         socket.close();
       } catch (error) {
         console.error("Error during cleanup:", error);
       } finally {
         this.conn = null;
+        this.currentWebSocket = null;
+        this.isConnecting = false;
       }
     }
   };
@@ -1575,7 +1787,9 @@ var Schematic = class {
     if (this.conn !== null) {
       try {
         const socket = await this.conn;
-        socket.close();
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          socket.close();
+        }
       } catch (error) {
         this.debug("Error closing connection on offline:", error);
       }
@@ -1590,7 +1804,9 @@ var Schematic = class {
    * Handle browser coming back online
    */
   handleNetworkOnline = () => {
-    this.debug("Network online, attempting reconnection and flushing queued events");
+    this.debug(
+      "Network online, attempting reconnection and flushing queued events"
+    );
     this.wsReconnectAttempts = 0;
     if (this.wsReconnectTimer !== null) {
       clearTimeout(this.wsReconnectTimer);
@@ -1613,7 +1829,10 @@ var Schematic = class {
       return;
     }
     if (this.wsReconnectTimer !== null) {
-      clearTimeout(this.wsReconnectTimer);
+      this.debug(
+        `Reconnection attempt already scheduled, ignoring duplicate request`
+      );
+      return;
     }
     const delay = this.calculateReconnectDelay();
     this.debug(
@@ -1626,23 +1845,57 @@ var Schematic = class {
         `Attempting to reconnect (attempt ${this.wsReconnectAttempts}/${this.webSocketMaxReconnectAttempts})`
       );
       try {
-        this.conn = this.wsConnect();
-        const socket = await this.conn;
-        this.debug(`Reconnection context check:`, {
-          hasCompany: this.context.company !== void 0,
-          hasUser: this.context.user !== void 0,
-          context: this.context
-        });
-        if (this.context.company !== void 0 || this.context.user !== void 0) {
-          this.debug(`Reconnected, force re-sending context`);
-          await this.wsSendContextAfterReconnection(socket, this.context);
-        } else {
-          this.debug(`No context to re-send after reconnection - websocket ready for new context`);
+        if (this.conn !== null) {
+          this.debug(`Cleaning up existing connection before reconnection`);
+          try {
+            const existingSocket = await this.conn;
+            if (this.currentWebSocket === existingSocket) {
+              this.debug(`Existing websocket is current, will be replaced`);
+              this.currentWebSocket = null;
+            }
+            if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+              existingSocket.close();
+            }
+          } catch (error) {
+            this.debug(`Error cleaning up existing connection:`, error);
+          }
+          this.conn = null;
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket = await this.conn;
+          this.isConnecting = false;
+          this.debug(`Reconnection context check:`, {
+            hasCompany: this.context.company !== void 0,
+            hasUser: this.context.user !== void 0,
+            context: this.context
+          });
+          if (this.context.company !== void 0 || this.context.user !== void 0) {
+            this.debug(`Reconnected, force re-sending context`);
+            await this.wsSendMessage(socket, this.context, true);
+          } else {
+            this.debug(
+              `No context to re-send after reconnection - websocket ready for new context`
+            );
+            this.debug(
+              `Setting up tracking for reconnected websocket (no context to send)`
+            );
+            this.currentWebSocket = socket;
+          }
+          this.flushEventQueue().catch((error) => {
+            this.debug(
+              "Error flushing event queue after websocket reconnection:",
+              error
+            );
+          });
+          this.debug(`Reconnection successful`);
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
         }
-        this.flushEventQueue().catch((error) => {
-          this.debug("Error flushing event queue after websocket reconnection:", error);
-        });
-        this.debug(`Reconnection successful`);
       } catch (error) {
         this.debug(`Reconnection attempt failed:`, error);
       }
@@ -1660,6 +1913,8 @@ var Schematic = class {
       const wsUrl = `${this.webSocketUrl}/flags/bootstrap?apiKey=${this.apiKey}`;
       this.debug(`connecting to WebSocket:`, wsUrl);
       const webSocket = new WebSocket(wsUrl);
+      const connectionId = Math.random().toString(36).substring(7);
+      this.debug(`Creating WebSocket connection ${connectionId} to ${wsUrl}`);
       let timeoutId = null;
       let isResolved = false;
       timeoutId = setTimeout(() => {
@@ -1678,7 +1933,7 @@ var Schematic = class {
         }
         this.wsReconnectAttempts = 0;
         this.wsIntentionalDisconnect = false;
-        this.debug(`WebSocket connection opened`);
+        this.debug(`WebSocket connection ${connectionId} opened successfully`);
         resolve(webSocket);
       };
       webSocket.onerror = (error) => {
@@ -1686,7 +1941,7 @@ var Schematic = class {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        this.debug(`WebSocket connection error:`, error);
+        this.debug(`WebSocket connection ${connectionId} error:`, error);
         reject(error);
       };
       webSocket.onclose = () => {
@@ -1694,121 +1949,48 @@ var Schematic = class {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        this.debug(`WebSocket connection closed`);
+        this.debug(`WebSocket connection ${connectionId} closed`);
         this.conn = null;
+        if (this.currentWebSocket === webSocket) {
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
         if (!this.wsIntentionalDisconnect && this.webSocketReconnect) {
           this.attemptReconnect();
         }
       };
     });
   };
-  // Send a message on the websocket after reconnection, forcing the send even if context appears unchanged
-  // because the server has lost all state and needs the initial context
-  wsSendContextAfterReconnection = (socket, context) => {
-    if (this.isOffline()) {
-      this.debug("wsSendContextAfterReconnection: skipped (offline mode)");
-      this.setIsPending(false);
-      return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-      this.debug(`WebSocket force sending context after reconnection:`, context);
-      this.context = context;
-      const sendMessage = () => {
-        let resolved = false;
-        const messageHandler = (event) => {
-          const message = JSON.parse(event.data);
-          this.debug(`WebSocket message received after reconnection:`, message);
-          if (!(contextString(context) in this.checks)) {
-            this.checks[contextString(context)] = {};
-          }
-          (message.flags ?? []).forEach((flag) => {
-            const flagCheck = CheckFlagReturnFromJSON(flag);
-            const contextStr = contextString(context);
-            if (this.checks[contextStr] === void 0) {
-              this.checks[contextStr] = {};
-            }
-            this.checks[contextStr][flagCheck.flag] = flagCheck;
-          });
-          this.useWebSocket = true;
-          socket.removeEventListener("message", messageHandler);
-          if (!resolved) {
-            resolved = true;
-            resolve(this.setIsPending(false));
-          }
-        };
-        socket.addEventListener("message", messageHandler);
-        const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
-        const messagePayload = {
-          apiKey: this.apiKey,
-          clientVersion,
-          data: context
-        };
-        this.debug(`WebSocket sending forced message after reconnection:`, messagePayload);
-        socket.send(JSON.stringify(messagePayload));
-      };
-      if (socket.readyState === WebSocket.OPEN) {
-        this.debug(`WebSocket already open, sending forced message after reconnection`);
-        sendMessage();
-      } else {
-        socket.addEventListener("open", () => {
-          this.debug(`WebSocket opened, sending forced message after reconnection`);
-          sendMessage();
-        });
-      }
-    });
-  };
   // Send a message on the websocket indicating interest in a particular evaluation context
   // and wait for the initial set of flag values to be returned
-  wsSendMessage = (socket, context) => {
+  wsSendMessage = (socket, context, forceContextSend = false) => {
     if (this.isOffline()) {
       this.debug("wsSendMessage: skipped (offline mode)");
       this.setIsPending(false);
       return Promise.resolve();
     }
     return new Promise((resolve, reject) => {
-      if (contextString(context) == contextString(this.context)) {
+      if (!forceContextSend && contextString(context) == contextString(this.context)) {
         this.debug(`WebSocket context unchanged, skipping update`);
         return resolve(this.setIsPending(false));
       }
-      this.debug(`WebSocket context updated:`, context);
+      this.debug(
+        forceContextSend ? `WebSocket force sending context (reconnection):` : `WebSocket context updated:`,
+        context
+      );
       this.context = context;
       const sendMessage = () => {
         let resolved = false;
+        const persistentMessageHandler = this.createPersistentMessageHandler(context);
         const messageHandler = (event) => {
-          const message = JSON.parse(event.data);
-          this.debug(`WebSocket message received:`, message);
-          if (!(contextString(context) in this.checks)) {
-            this.checks[contextString(context)] = {};
-          }
-          (message.flags ?? []).forEach((flag) => {
-            const flagCheck = CheckFlagReturnFromJSON(flag);
-            const contextStr = contextString(context);
-            if (this.checks[contextStr] === void 0) {
-              this.checks[contextStr] = {};
-            }
-            this.checks[contextStr][flagCheck.flag] = flagCheck;
-            this.debug(`WebSocket flag update:`, {
-              flag: flagCheck.flag,
-              value: flagCheck.value,
-              flagCheck
-            });
-            if (typeof flagCheck.featureUsageEvent === "string") {
-              this.updateFeatureUsageEventMap(flagCheck);
-            }
-            if (this.flagCheckListeners[flag.flag]?.size > 0 || this.flagValueListeners[flag.flag]?.size > 0) {
-              this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
-            }
-            this.notifyFlagCheckListeners(flag.flag, flagCheck);
-            this.notifyFlagValueListeners(flag.flag, flagCheck.value);
-          });
-          this.flushContextDependentEventQueue();
-          this.setIsPending(false);
+          persistentMessageHandler(event);
           if (!resolved) {
             resolved = true;
             resolve();
           }
         };
         socket.addEventListener("message", messageHandler);
+        this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
           apiKey: this.apiKey,
@@ -1916,7 +2098,17 @@ var Schematic = class {
         { value }
       );
     }
-    listeners.forEach((listener) => notifyFlagValueListener(listener, value));
+    listeners.forEach((listener, index) => {
+      this.debug(`Calling listener ${index} for flag ${flagKey}`, {
+        flagKey,
+        value
+      });
+      notifyFlagValueListener(listener, value);
+      this.debug(`Listener ${index} for flag ${flagKey} completed`, {
+        flagKey,
+        value
+      });
+    });
   };
 };
 var notifyPendingListener = (listener, value) => {
@@ -1945,7 +2137,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.9";
+var version2 = "1.2.12";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -1960,7 +2152,7 @@ var SchematicProvider = ({
 }) => {
   const initialOptsRef = (0, import_react.useRef)({
     publishableKey,
-    useWebSocket: clientOpts.useWebSocket ?? true,
+    useWebSocket: true,
     additionalHeaders: {
       "X-Schematic-Client-Version": `schematic-react@${version2}`
     },

package/dist/schematic-react.d.ts

@@ -15,7 +15,7 @@ import { StoragePersister } from '@schematichq/schematic-js';
 import { Traits } from '@schematichq/schematic-js';
 import { UsagePeriod } from '@schematichq/schematic-js';
 
-declare type BaseSchematicProviderProps = Omit<SchematicJS.SchematicOptions, "client" | "publishableKey"> & {
+declare type BaseSchematicProviderProps = Omit<SchematicJS.SchematicOptions, "client" | "publishableKey" | "useWebSocket"> & {
     children: React_2.ReactNode;
 };
 

package/dist/schematic-react.esm.js

@@ -754,7 +754,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.9";
+var version = "1.2.12";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -784,6 +784,8 @@ var Schematic = class {
   wsReconnectAttempts = 0;
   wsReconnectTimer = null;
   wsIntentionalDisconnect = false;
+  currentWebSocket = null;
+  isConnecting = false;
   maxEventQueueSize = 100;
   // Prevent memory issues with very long network outages
   maxEventRetries = 5;
@@ -1061,6 +1063,49 @@ var Schematic = class {
       console.log(`[Schematic] ${message}`, ...args);
     }
   }
+  /**
+   * Create a persistent message handler for websocket flag updates
+   */
+  createPersistentMessageHandler(context) {
+    return (event) => {
+      const message = JSON.parse(event.data);
+      this.debug(`WebSocket persistent message received:`, message);
+      if (!(contextString(context) in this.checks)) {
+        this.checks[contextString(context)] = {};
+      }
+      (message.flags ?? []).forEach((flag) => {
+        const flagCheck = CheckFlagReturnFromJSON(flag);
+        const contextStr = contextString(context);
+        if (this.checks[contextStr] === void 0) {
+          this.checks[contextStr] = {};
+        }
+        this.checks[contextStr][flagCheck.flag] = flagCheck;
+        this.debug(`WebSocket flag update:`, {
+          flag: flagCheck.flag,
+          value: flagCheck.value,
+          flagCheck
+        });
+        if (typeof flagCheck.featureUsageEvent === "string") {
+          this.updateFeatureUsageEventMap(flagCheck);
+        }
+        if ((this.flagCheckListeners[flag.flag]?.size ?? 0) > 0 || (this.flagValueListeners[flag.flag]?.size ?? 0) > 0) {
+          this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
+        }
+        this.debug(`About to notify listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+        this.notifyFlagCheckListeners(flag.flag, flagCheck);
+        this.notifyFlagValueListeners(flag.flag, flagCheck.value);
+        this.debug(`Finished notifying listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+      });
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+    };
+  }
   /**
    * Helper function to check if client is in offline mode
    */
@@ -1212,6 +1257,19 @@ var Schematic = class {
     try {
       this.setIsPending(true);
       if (!this.conn) {
+        if (this.isConnecting) {
+          this.debug(
+            `Connection already in progress, waiting for it to complete`
+          );
+          while (this.isConnecting && this.conn === null) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+          }
+          if (this.conn !== null) {
+            const socket2 = await this.conn;
+            await this.wsSendMessage(socket2, context);
+            return;
+          }
+        }
         if (this.wsReconnectTimer !== null) {
           this.debug(
             `Cancelling scheduled reconnection, connecting immediately`
@@ -1219,7 +1277,17 @@ var Schematic = class {
           clearTimeout(this.wsReconnectTimer);
           this.wsReconnectTimer = null;
         }
-        this.conn = this.wsConnect();
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket2 = await this.conn;
+          this.isConnecting = false;
+          await this.wsSendMessage(socket2, context);
+          return;
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
+        }
       }
       const socket = await this.conn;
       await this.wsSendMessage(socket, context);
@@ -1384,10 +1452,14 @@ var Schematic = class {
       }
     }
     if (readyEvents.length === 0) {
-      this.debug(`No events ready for retry yet (${notReadyEvents.length} still in backoff)`);
+      this.debug(
+        `No events ready for retry yet (${notReadyEvents.length} still in backoff)`
+      );
       return;
     }
-    this.debug(`Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`);
+    this.debug(
+      `Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`
+    );
     this.eventQueue = notReadyEvents;
     for (const event of readyEvents) {
       try {
@@ -1452,7 +1524,10 @@ var Schematic = class {
     } catch (error) {
       const retryCount = (event.retry_count ?? 0) + 1;
       if (retryCount <= this.maxEventRetries) {
-        this.debug(`Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`, error);
+        this.debug(
+          `Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`,
+          error
+        );
         const baseDelay = this.eventRetryInitialDelay * Math.pow(2, retryCount - 1);
         const jitterDelay = Math.min(baseDelay, this.eventRetryMaxDelay);
         const nextRetryAt = Date.now() + jitterDelay;
@@ -1463,15 +1538,22 @@ var Schematic = class {
         };
         if (this.eventQueue.length < this.maxEventQueueSize) {
           this.eventQueue.push(retryEvent);
-          this.debug(`Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`);
+          this.debug(
+            `Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`
+          );
         } else {
-          this.debug(`Event queue full (${this.maxEventQueueSize}), dropping oldest event`);
+          this.debug(
+            `Event queue full (${this.maxEventQueueSize}), dropping oldest event`
+          );
           this.eventQueue.shift();
           this.eventQueue.push(retryEvent);
         }
         this.startRetryTimer();
       } else {
-        this.debug(`Event failed permanently after ${this.maxEventRetries} attempts, dropping:`, error);
+        this.debug(
+          `Event failed permanently after ${this.maxEventRetries} attempts, dropping:`,
+          error
+        );
       }
     }
     return Promise.resolve();
@@ -1483,6 +1565,130 @@ var Schematic = class {
   /**
    * Websocket management
    */
+  /**
+   * Force an immediate WebSocket reconnection.
+   * This is useful when the application returns from a background state (e.g., mobile app
+   * coming back to foreground) and wants to immediately re-establish the connection
+   * rather than waiting for the exponential backoff timer.
+   *
+   * This method will:
+   * - Cancel any pending reconnection timer
+   * - Reset the reconnection attempt counter
+   * - Close any existing connection
+   * - Immediately attempt to reconnect
+   * - Re-send the current context to get fresh flag values
+   *
+   * Use this when you need guaranteed fresh values (e.g., after an in-app purchase).
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.forceReconnect();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  forceReconnect = async () => {
+    return this.reconnect({ force: true });
+  };
+  /**
+   * Reconnect the WebSocket connection only if the current connection is unhealthy.
+   * This is useful when the application returns from a background state and wants to
+   * ensure a healthy connection exists, but doesn't need to force a reconnection if
+   * the connection is still active.
+   *
+   * This method will:
+   * - Check if an existing connection is healthy (readyState === OPEN)
+   * - If healthy, return immediately without reconnecting
+   * - If unhealthy, perform the same reconnection logic as forceReconnect()
+   *
+   * Use this when you want efficient reconnection that avoids unnecessary disconnects.
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect only if needed when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.reconnectIfNeeded();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  reconnectIfNeeded = async () => {
+    return this.reconnect({ force: false });
+  };
+  /**
+   * Internal method to handle reconnection logic for both forceReconnect and reconnectIfNeeded.
+   */
+  reconnect = async (options) => {
+    const { force } = options;
+    const methodName = force ? "forceReconnect" : "reconnectIfNeeded";
+    if (this.isOffline()) {
+      this.debug(`${methodName}: skipped (offline mode)`);
+      return Promise.resolve();
+    }
+    if (!force && this.conn !== null) {
+      try {
+        const existingSocket = await this.conn;
+        if (existingSocket.readyState === WebSocket.OPEN) {
+          this.debug(`${methodName}: connection is healthy, skipping`);
+          return Promise.resolve();
+        }
+      } catch {
+      }
+    }
+    this.debug(
+      `${methodName}: ${force ? "forcing immediate reconnection" : "reconnecting"}`
+    );
+    this.wsIntentionalDisconnect = false;
+    if (this.wsReconnectTimer !== null) {
+      this.debug(`${methodName}: cancelling pending reconnection timer`);
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    this.wsReconnectAttempts = 0;
+    if (this.conn !== null) {
+      this.debug(`${methodName}: closing existing connection`);
+      try {
+        const existingSocket = await this.conn;
+        if (this.currentWebSocket === existingSocket) {
+          this.currentWebSocket = null;
+        }
+        if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+          existingSocket.close();
+        }
+      } catch (error) {
+        this.debug(`${methodName}: error closing existing connection:`, error);
+      }
+      this.conn = null;
+      this.isConnecting = false;
+    }
+    if (this.context.company !== void 0 || this.context.user !== void 0) {
+      this.debug(`${methodName}: reconnecting with existing context`);
+      try {
+        this.isConnecting = true;
+        this.conn = this.wsConnect();
+        const socket = await this.conn;
+        this.isConnecting = false;
+        await this.wsSendMessage(socket, this.context, true);
+        this.debug(`${methodName}: reconnection successful`);
+      } catch (error) {
+        this.isConnecting = false;
+        this.debug(`${methodName}: reconnection failed:`, error);
+      }
+    } else {
+      this.debug(`${methodName}: no context set, skipping reconnection`);
+    }
+    return Promise.resolve();
+  };
   /**
    * If using websocket mode, close the connection when done.
    * In offline mode, this is a no-op.
@@ -1501,11 +1707,17 @@ var Schematic = class {
     if (this.conn) {
       try {
         const socket = await this.conn;
+        if (this.currentWebSocket === socket) {
+          this.debug(`Cleaning up current websocket tracking`);
+          this.currentWebSocket = null;
+        }
         socket.close();
       } catch (error) {
         console.error("Error during cleanup:", error);
       } finally {
         this.conn = null;
+        this.currentWebSocket = null;
+        this.isConnecting = false;
       }
     }
   };
@@ -1530,7 +1742,9 @@ var Schematic = class {
     if (this.conn !== null) {
       try {
         const socket = await this.conn;
-        socket.close();
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          socket.close();
+        }
       } catch (error) {
         this.debug("Error closing connection on offline:", error);
       }
@@ -1545,7 +1759,9 @@ var Schematic = class {
    * Handle browser coming back online
    */
   handleNetworkOnline = () => {
-    this.debug("Network online, attempting reconnection and flushing queued events");
+    this.debug(
+      "Network online, attempting reconnection and flushing queued events"
+    );
     this.wsReconnectAttempts = 0;
     if (this.wsReconnectTimer !== null) {
       clearTimeout(this.wsReconnectTimer);
@@ -1568,7 +1784,10 @@ var Schematic = class {
       return;
     }
     if (this.wsReconnectTimer !== null) {
-      clearTimeout(this.wsReconnectTimer);
+      this.debug(
+        `Reconnection attempt already scheduled, ignoring duplicate request`
+      );
+      return;
     }
     const delay = this.calculateReconnectDelay();
     this.debug(
@@ -1581,23 +1800,57 @@ var Schematic = class {
         `Attempting to reconnect (attempt ${this.wsReconnectAttempts}/${this.webSocketMaxReconnectAttempts})`
       );
       try {
-        this.conn = this.wsConnect();
-        const socket = await this.conn;
-        this.debug(`Reconnection context check:`, {
-          hasCompany: this.context.company !== void 0,
-          hasUser: this.context.user !== void 0,
-          context: this.context
-        });
-        if (this.context.company !== void 0 || this.context.user !== void 0) {
-          this.debug(`Reconnected, force re-sending context`);
-          await this.wsSendContextAfterReconnection(socket, this.context);
-        } else {
-          this.debug(`No context to re-send after reconnection - websocket ready for new context`);
+        if (this.conn !== null) {
+          this.debug(`Cleaning up existing connection before reconnection`);
+          try {
+            const existingSocket = await this.conn;
+            if (this.currentWebSocket === existingSocket) {
+              this.debug(`Existing websocket is current, will be replaced`);
+              this.currentWebSocket = null;
+            }
+            if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+              existingSocket.close();
+            }
+          } catch (error) {
+            this.debug(`Error cleaning up existing connection:`, error);
+          }
+          this.conn = null;
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket = await this.conn;
+          this.isConnecting = false;
+          this.debug(`Reconnection context check:`, {
+            hasCompany: this.context.company !== void 0,
+            hasUser: this.context.user !== void 0,
+            context: this.context
+          });
+          if (this.context.company !== void 0 || this.context.user !== void 0) {
+            this.debug(`Reconnected, force re-sending context`);
+            await this.wsSendMessage(socket, this.context, true);
+          } else {
+            this.debug(
+              `No context to re-send after reconnection - websocket ready for new context`
+            );
+            this.debug(
+              `Setting up tracking for reconnected websocket (no context to send)`
+            );
+            this.currentWebSocket = socket;
+          }
+          this.flushEventQueue().catch((error) => {
+            this.debug(
+              "Error flushing event queue after websocket reconnection:",
+              error
+            );
+          });
+          this.debug(`Reconnection successful`);
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
         }
-        this.flushEventQueue().catch((error) => {
-          this.debug("Error flushing event queue after websocket reconnection:", error);
-        });
-        this.debug(`Reconnection successful`);
       } catch (error) {
         this.debug(`Reconnection attempt failed:`, error);
       }
@@ -1615,6 +1868,8 @@ var Schematic = class {
       const wsUrl = `${this.webSocketUrl}/flags/bootstrap?apiKey=${this.apiKey}`;
       this.debug(`connecting to WebSocket:`, wsUrl);
       const webSocket = new WebSocket(wsUrl);
+      const connectionId = Math.random().toString(36).substring(7);
+      this.debug(`Creating WebSocket connection ${connectionId} to ${wsUrl}`);
       let timeoutId = null;
       let isResolved = false;
       timeoutId = setTimeout(() => {
@@ -1633,7 +1888,7 @@ var Schematic = class {
         }
         this.wsReconnectAttempts = 0;
         this.wsIntentionalDisconnect = false;
-        this.debug(`WebSocket connection opened`);
+        this.debug(`WebSocket connection ${connectionId} opened successfully`);
         resolve(webSocket);
       };
       webSocket.onerror = (error) => {
@@ -1641,7 +1896,7 @@ var Schematic = class {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        this.debug(`WebSocket connection error:`, error);
+        this.debug(`WebSocket connection ${connectionId} error:`, error);
         reject(error);
       };
       webSocket.onclose = () => {
@@ -1649,121 +1904,48 @@ var Schematic = class {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        this.debug(`WebSocket connection closed`);
+        this.debug(`WebSocket connection ${connectionId} closed`);
         this.conn = null;
+        if (this.currentWebSocket === webSocket) {
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
         if (!this.wsIntentionalDisconnect && this.webSocketReconnect) {
           this.attemptReconnect();
         }
       };
     });
   };
-  // Send a message on the websocket after reconnection, forcing the send even if context appears unchanged
-  // because the server has lost all state and needs the initial context
-  wsSendContextAfterReconnection = (socket, context) => {
-    if (this.isOffline()) {
-      this.debug("wsSendContextAfterReconnection: skipped (offline mode)");
-      this.setIsPending(false);
-      return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-      this.debug(`WebSocket force sending context after reconnection:`, context);
-      this.context = context;
-      const sendMessage = () => {
-        let resolved = false;
-        const messageHandler = (event) => {
-          const message = JSON.parse(event.data);
-          this.debug(`WebSocket message received after reconnection:`, message);
-          if (!(contextString(context) in this.checks)) {
-            this.checks[contextString(context)] = {};
-          }
-          (message.flags ?? []).forEach((flag) => {
-            const flagCheck = CheckFlagReturnFromJSON(flag);
-            const contextStr = contextString(context);
-            if (this.checks[contextStr] === void 0) {
-              this.checks[contextStr] = {};
-            }
-            this.checks[contextStr][flagCheck.flag] = flagCheck;
-          });
-          this.useWebSocket = true;
-          socket.removeEventListener("message", messageHandler);
-          if (!resolved) {
-            resolved = true;
-            resolve(this.setIsPending(false));
-          }
-        };
-        socket.addEventListener("message", messageHandler);
-        const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
-        const messagePayload = {
-          apiKey: this.apiKey,
-          clientVersion,
-          data: context
-        };
-        this.debug(`WebSocket sending forced message after reconnection:`, messagePayload);
-        socket.send(JSON.stringify(messagePayload));
-      };
-      if (socket.readyState === WebSocket.OPEN) {
-        this.debug(`WebSocket already open, sending forced message after reconnection`);
-        sendMessage();
-      } else {
-        socket.addEventListener("open", () => {
-          this.debug(`WebSocket opened, sending forced message after reconnection`);
-          sendMessage();
-        });
-      }
-    });
-  };
   // Send a message on the websocket indicating interest in a particular evaluation context
   // and wait for the initial set of flag values to be returned
-  wsSendMessage = (socket, context) => {
+  wsSendMessage = (socket, context, forceContextSend = false) => {
     if (this.isOffline()) {
       this.debug("wsSendMessage: skipped (offline mode)");
       this.setIsPending(false);
       return Promise.resolve();
     }
     return new Promise((resolve, reject) => {
-      if (contextString(context) == contextString(this.context)) {
+      if (!forceContextSend && contextString(context) == contextString(this.context)) {
         this.debug(`WebSocket context unchanged, skipping update`);
         return resolve(this.setIsPending(false));
       }
-      this.debug(`WebSocket context updated:`, context);
+      this.debug(
+        forceContextSend ? `WebSocket force sending context (reconnection):` : `WebSocket context updated:`,
+        context
+      );
       this.context = context;
       const sendMessage = () => {
         let resolved = false;
+        const persistentMessageHandler = this.createPersistentMessageHandler(context);
         const messageHandler = (event) => {
-          const message = JSON.parse(event.data);
-          this.debug(`WebSocket message received:`, message);
-          if (!(contextString(context) in this.checks)) {
-            this.checks[contextString(context)] = {};
-          }
-          (message.flags ?? []).forEach((flag) => {
-            const flagCheck = CheckFlagReturnFromJSON(flag);
-            const contextStr = contextString(context);
-            if (this.checks[contextStr] === void 0) {
-              this.checks[contextStr] = {};
-            }
-            this.checks[contextStr][flagCheck.flag] = flagCheck;
-            this.debug(`WebSocket flag update:`, {
-              flag: flagCheck.flag,
-              value: flagCheck.value,
-              flagCheck
-            });
-            if (typeof flagCheck.featureUsageEvent === "string") {
-              this.updateFeatureUsageEventMap(flagCheck);
-            }
-            if (this.flagCheckListeners[flag.flag]?.size > 0 || this.flagValueListeners[flag.flag]?.size > 0) {
-              this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
-            }
-            this.notifyFlagCheckListeners(flag.flag, flagCheck);
-            this.notifyFlagValueListeners(flag.flag, flagCheck.value);
-          });
-          this.flushContextDependentEventQueue();
-          this.setIsPending(false);
+          persistentMessageHandler(event);
           if (!resolved) {
             resolved = true;
             resolve();
           }
         };
         socket.addEventListener("message", messageHandler);
+        this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
           apiKey: this.apiKey,
@@ -1871,7 +2053,17 @@ var Schematic = class {
         { value }
       );
     }
-    listeners.forEach((listener) => notifyFlagValueListener(listener, value));
+    listeners.forEach((listener, index) => {
+      this.debug(`Calling listener ${index} for flag ${flagKey}`, {
+        flagKey,
+        value
+      });
+      notifyFlagValueListener(listener, value);
+      this.debug(`Listener ${index} for flag ${flagKey} completed`, {
+        flagKey,
+        value
+      });
+    });
   };
 };
 var notifyPendingListener = (listener, value) => {
@@ -1900,7 +2092,7 @@ var notifyFlagValueListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.2.9";
+var version2 = "1.2.12";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";
@@ -1915,7 +2107,7 @@ var SchematicProvider = ({
 }) => {
   const initialOptsRef = useRef({
     publishableKey,
-    useWebSocket: clientOpts.useWebSocket ?? true,
+    useWebSocket: true,
     additionalHeaders: {
       "X-Schematic-Client-Version": `schematic-react@${version2}`
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schematichq/schematic-react",
-  "version": "1.2.9",
+  "version": "1.2.12",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -31,7 +31,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@schematichq/schematic-js": "^1.2.9"
+    "@schematichq/schematic-js": "^1.2.12"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",