@schematichq/schematic-react 1.2.16 → 1.2.17

package/README.md

@@ -136,6 +136,66 @@ 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`.*
 
+## Fallback Behavior
+
+The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).
+
+### Flag Check Fallbacks
+
+When flag checks cannot reach Schematic, they use fallback values in the following priority order:
+
+1. Callsite fallback - fallback values can be provided directly in the hook options
+2. Initialization defaults - fallback values configured via `flagCheckDefaults` or `flagValueDefaults` options when initializing the provider
+3. Default value - Returns `false` if no fallback is configured
+
+```tsx
+// Provide a fallback value at the callsite
+import { useSchematicFlag } from "@schematichq/schematic-react";
+
+const MyComponent = () => {
+    const isFeatureEnabled = useSchematicFlag("feature-flag", {
+        fallback: true,  // Used if API request fails
+    });
+
+    return isFeatureEnabled ? <Feature /> : <Fallback />;
+};
+
+// Or configure defaults at initialization
+import { SchematicProvider } from "@schematichq/schematic-react";
+
+ReactDOM.render(
+    <SchematicProvider
+        publishableKey="your-publishable-key"
+        flagValueDefaults={{
+            "feature-flag": true,  // Used if API request fails and no callsite fallback
+        }}
+        flagCheckDefaults={{
+            "another-flag": {
+                flag: "another-flag",
+                value: true,
+                reason: "Default value",
+            },
+        }}
+    >
+        <App />
+    </SchematicProvider>,
+    document.getElementById("root"),
+);
+```
+
+### Event Queueing and Retry
+
+When events (track, identify) cannot be sent due to network issues, they are automatically queued and retried:
+
+- Events are queued in memory (up to 100 events by default, configurable via `maxEventQueueSize`)
+- Failed events are retried with exponential backoff (up to 5 attempts by default, configurable via `maxEventRetries`)
+- Events are automatically flushed when the network connection is restored
+- Events queued when the page is hidden are sent when the page becomes visible
+
+### WebSocket Fallback
+
+In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as [outlined above](/#flag-check-fallbacks). The WebSocket will also automatically attempt to re-establish it's connection with Schematic using an exponential backoff. 
+
 ## React Native
 
 ### Handling app background/foreground
@@ -217,7 +277,6 @@ ReactDOM.render(
 
 Offline mode automatically enables debug mode to help with troubleshooting.
 
-
 ## License
 
 MIT

package/dist/schematic-react.cjs.js

@@ -799,7 +799,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.16";
+var version = "1.2.17";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -1013,8 +1013,8 @@ var Schematic = class {
   /**
    * Get value for a single flag.
    * In WebSocket mode, returns cached values if connection is active, otherwise establishes
-   * new connection and then returns the requestedvalue. Falls back to REST API if WebSocket
-   * connection fails.
+   * new connection and then returns the requested value. Falls back to preconfigured fallback
+   * values if WebSocket connection fails.
    * In REST mode, makes an API call for each check.
    */
   async checkFlag(options) {
@@ -1083,10 +1083,17 @@ var Schematic = class {
         await this.setContext(context);
       } catch (error) {
         console.warn(
-          "WebSocket connection failed, falling back to REST:",
+          "WebSocket connection failed, using fallback value:",
           error
         );
-        return this.fallbackToRest(key, context, fallback);
+        const errorResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "WebSocket connection failed",
+          error instanceof Error ? error.message : String(error)
+        );
+        this.submitFlagCheckEvent(key, errorResult, context);
+        return errorResult.value;
       }
       const contextVals = this.checks[contextStr] ?? {};
       const flagCheck = contextVals[key];
@@ -1189,53 +1196,6 @@ var Schematic = class {
     this.debug(`submitting flag check event:`, eventBody);
     return this.handleEvent("flag_check", EventBodyFlagCheckToJSON(eventBody));
   }
-  /**
-   * Helper method for falling back to REST API when WebSocket connection fails
-   */
-  async fallbackToRest(key, context, fallback) {
-    if (this.isOffline()) {
-      const resolvedFallback = this.resolveFallbackValue(key, fallback);
-      this.debug(`fallbackToRest offline result: ${key}`, {
-        value: resolvedFallback,
-        offlineMode: true
-      });
-      return resolvedFallback;
-    }
-    try {
-      const requestUrl = `${this.apiUrl}/flags/${key}/check`;
-      const response = await fetch(requestUrl, {
-        method: "POST",
-        headers: {
-          ...this.additionalHeaders ?? {},
-          "Content-Type": "application/json;charset=UTF-8",
-          "X-Schematic-Api-Key": this.apiKey
-        },
-        body: JSON.stringify(context)
-      });
-      if (!response.ok) {
-        throw new Error("Network response was not ok");
-      }
-      const responseJson = await response.json();
-      const data = CheckFlagResponseFromJSON(responseJson);
-      this.debug(`fallbackToRest result: ${key}`, data);
-      const result = CheckFlagReturnFromJSON(data.data);
-      if (typeof result.featureUsageEvent === "string") {
-        this.updateFeatureUsageEventMap(result);
-      }
-      this.submitFlagCheckEvent(key, result, context);
-      return result.value;
-    } catch (error) {
-      console.warn("REST API call failed, using fallback value:", error);
-      const errorResult = this.resolveFallbackCheckFlagReturn(
-        key,
-        fallback,
-        "API request failed (fallback)",
-        error instanceof Error ? error.message : String(error)
-      );
-      this.submitFlagCheckEvent(key, errorResult, context);
-      return errorResult.value;
-    }
-  }
   /**
    * Make an API call to fetch all flag values for a given context.
    * Recommended for use in REST mode only.
@@ -1989,7 +1949,10 @@ var Schematic = class {
           clearTimeout(timeoutId);
         }
         this.debug(`WebSocket connection ${connectionId} error:`, error);
-        reject(error);
+        const wrappedError = new Error(
+          "WebSocket connection failed during handshake"
+        );
+        reject(wrappedError);
       };
       webSocket.onclose = () => {
         if (timeoutId !== null) {
@@ -2036,6 +1999,20 @@ var Schematic = class {
           }
         };
         socket.addEventListener("message", messageHandler);
+        socket.addEventListener("close", (event) => {
+          if (!resolved) {
+            resolved = true;
+            if (event.code === 4001) {
+              reject(
+                new Error(
+                  `Authentication failed: ${event.reason !== "" ? event.reason : "Invalid API key"}`
+                )
+              );
+            } else {
+              reject(new Error("WebSocket connection closed unexpectedly"));
+            }
+          }
+        });
         this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
@@ -2202,7 +2179,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.16";
+var version2 = "1.2.17";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.esm.js

@@ -754,7 +754,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.16";
+var version = "1.2.17";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -968,8 +968,8 @@ var Schematic = class {
   /**
    * Get value for a single flag.
    * In WebSocket mode, returns cached values if connection is active, otherwise establishes
-   * new connection and then returns the requestedvalue. Falls back to REST API if WebSocket
-   * connection fails.
+   * new connection and then returns the requested value. Falls back to preconfigured fallback
+   * values if WebSocket connection fails.
    * In REST mode, makes an API call for each check.
    */
   async checkFlag(options) {
@@ -1038,10 +1038,17 @@ var Schematic = class {
         await this.setContext(context);
       } catch (error) {
         console.warn(
-          "WebSocket connection failed, falling back to REST:",
+          "WebSocket connection failed, using fallback value:",
           error
         );
-        return this.fallbackToRest(key, context, fallback);
+        const errorResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "WebSocket connection failed",
+          error instanceof Error ? error.message : String(error)
+        );
+        this.submitFlagCheckEvent(key, errorResult, context);
+        return errorResult.value;
       }
       const contextVals = this.checks[contextStr] ?? {};
       const flagCheck = contextVals[key];
@@ -1144,53 +1151,6 @@ var Schematic = class {
     this.debug(`submitting flag check event:`, eventBody);
     return this.handleEvent("flag_check", EventBodyFlagCheckToJSON(eventBody));
   }
-  /**
-   * Helper method for falling back to REST API when WebSocket connection fails
-   */
-  async fallbackToRest(key, context, fallback) {
-    if (this.isOffline()) {
-      const resolvedFallback = this.resolveFallbackValue(key, fallback);
-      this.debug(`fallbackToRest offline result: ${key}`, {
-        value: resolvedFallback,
-        offlineMode: true
-      });
-      return resolvedFallback;
-    }
-    try {
-      const requestUrl = `${this.apiUrl}/flags/${key}/check`;
-      const response = await fetch(requestUrl, {
-        method: "POST",
-        headers: {
-          ...this.additionalHeaders ?? {},
-          "Content-Type": "application/json;charset=UTF-8",
-          "X-Schematic-Api-Key": this.apiKey
-        },
-        body: JSON.stringify(context)
-      });
-      if (!response.ok) {
-        throw new Error("Network response was not ok");
-      }
-      const responseJson = await response.json();
-      const data = CheckFlagResponseFromJSON(responseJson);
-      this.debug(`fallbackToRest result: ${key}`, data);
-      const result = CheckFlagReturnFromJSON(data.data);
-      if (typeof result.featureUsageEvent === "string") {
-        this.updateFeatureUsageEventMap(result);
-      }
-      this.submitFlagCheckEvent(key, result, context);
-      return result.value;
-    } catch (error) {
-      console.warn("REST API call failed, using fallback value:", error);
-      const errorResult = this.resolveFallbackCheckFlagReturn(
-        key,
-        fallback,
-        "API request failed (fallback)",
-        error instanceof Error ? error.message : String(error)
-      );
-      this.submitFlagCheckEvent(key, errorResult, context);
-      return errorResult.value;
-    }
-  }
   /**
    * Make an API call to fetch all flag values for a given context.
    * Recommended for use in REST mode only.
@@ -1944,7 +1904,10 @@ var Schematic = class {
           clearTimeout(timeoutId);
         }
         this.debug(`WebSocket connection ${connectionId} error:`, error);
-        reject(error);
+        const wrappedError = new Error(
+          "WebSocket connection failed during handshake"
+        );
+        reject(wrappedError);
       };
       webSocket.onclose = () => {
         if (timeoutId !== null) {
@@ -1991,6 +1954,20 @@ var Schematic = class {
           }
         };
         socket.addEventListener("message", messageHandler);
+        socket.addEventListener("close", (event) => {
+          if (!resolved) {
+            resolved = true;
+            if (event.code === 4001) {
+              reject(
+                new Error(
+                  `Authentication failed: ${event.reason !== "" ? event.reason : "Invalid API key"}`
+                )
+              );
+            } else {
+              reject(new Error("WebSocket connection closed unexpectedly"));
+            }
+          }
+        });
         this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
@@ -2157,7 +2134,7 @@ var notifyFlagValueListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.2.16";
+var version2 = "1.2.17";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schematichq/schematic-react",
-  "version": "1.2.16",
+  "version": "1.2.17",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -31,31 +31,31 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@schematichq/schematic-js": "^1.2.16"
+    "@schematichq/schematic-js": "^1.2.17"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@microsoft/api-extractor": "^7.55.0",
+    "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.56.3",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.1",
-    "@types/react": "^19.2.7",
-    "@vitest/browser": "^4.0.8",
-    "esbuild": "^0.27.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@vitest/browser": "^4.0.18",
+    "esbuild": "^0.27.3",
     "eslint": "^9.39.2",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
-    "globals": "^16.5.0",
-    "happy-dom": "^20.0.10",
+    "globals": "^17.3.0",
+    "happy-dom": "^20.6.1",
     "husky": "^9.1.7",
-    "jsdom": "^27.2.0",
-    "prettier": "^3.7.4",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "jsdom": "^28.0.0",
+    "prettier": "^3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.47.0",
-    "vitest": "^4.0.8"
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "react": ">=18"