@schematichq/schematic-react 1.2.10 → 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.10";
+var version = "1.2.12";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -1610,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.
@@ -2013,7 +2137,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.10";
+var version2 = "1.2.12";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -2028,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.10";
+var version = "1.2.12";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -1565,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.
@@ -1968,7 +2092,7 @@ var notifyFlagValueListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.2.10";
+var version2 = "1.2.12";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";
@@ -1983,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.10",
+  "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.10"
+    "@schematichq/schematic-js": "^1.2.12"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",