@schematichq/schematic-react 1.2.16 → 1.2.21

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

@@ -651,6 +651,36 @@ function v4(options, buf, offset) {
 }
 var v4_default = v4;
 var import_polyfill = __toESM2(require_browser_polyfill());
+function EntitlementValueTypeFromJSON(json) {
+  return EntitlementValueTypeFromJSONTyped(json, false);
+}
+function EntitlementValueTypeFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
+function FeatureEntitlementFromJSON(json) {
+  return FeatureEntitlementFromJSONTyped(json, false);
+}
+function FeatureEntitlementFromJSONTyped(json, ignoreDiscriminator) {
+  if (json == null) {
+    return json;
+  }
+  return {
+    allocation: json["allocation"] == null ? void 0 : json["allocation"],
+    creditId: json["credit_id"] == null ? void 0 : json["credit_id"],
+    creditRemaining: json["credit_remaining"] == null ? void 0 : json["credit_remaining"],
+    creditTotal: json["credit_total"] == null ? void 0 : json["credit_total"],
+    creditUsed: json["credit_used"] == null ? void 0 : json["credit_used"],
+    eventName: json["event_name"] == null ? void 0 : json["event_name"],
+    featureId: json["feature_id"],
+    featureKey: json["feature_key"],
+    metricPeriod: json["metric_period"] == null ? void 0 : json["metric_period"],
+    metricResetAt: json["metric_reset_at"] == null ? void 0 : new Date(json["metric_reset_at"]),
+    monthReset: json["month_reset"] == null ? void 0 : json["month_reset"],
+    softLimit: json["soft_limit"] == null ? void 0 : json["soft_limit"],
+    usage: json["usage"] == null ? void 0 : json["usage"],
+    valueType: EntitlementValueTypeFromJSON(json["value_type"])
+  };
+}
 function CheckFlagResponseDataFromJSON(json) {
   return CheckFlagResponseDataFromJSONTyped(json, false);
 }
@@ -660,6 +690,7 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
   }
   return {
     companyId: json["company_id"] == null ? void 0 : json["company_id"],
+    entitlement: json["entitlement"] == null ? void 0 : FeatureEntitlementFromJSON(json["entitlement"]),
     error: json["error"] == null ? void 0 : json["error"],
     featureAllocation: json["feature_allocation"] == null ? void 0 : json["feature_allocation"],
     featureUsage: json["feature_usage"] == null ? void 0 : json["feature_usage"],
@@ -799,7 +830,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.16";
+var version = "1.2.21";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -845,6 +876,7 @@ var Schematic = class {
   retryTimer = null;
   flagValueDefaults = {};
   flagCheckDefaults = {};
+  fallbackCheckCache = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -1013,8 +1045,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 +1115,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];
@@ -1097,6 +1136,13 @@ var Schematic = class {
       );
       if (typeof flagCheck !== "undefined") {
         this.submitFlagCheckEvent(key, flagCheck, context);
+      } else {
+        const fallbackResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "No flag values available"
+        );
+        this.submitFlagCheckEvent(key, fallbackResult, context);
       }
       return result;
     } catch (error) {
@@ -1189,53 +1235,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.
@@ -1309,6 +1308,9 @@ var Schematic = class {
       this.setIsPending(false);
       return Promise.resolve();
     }
+    if (contextString(context) === contextString(this.context) && this.conn !== null && !this.isPending) {
+      return;
+    }
     try {
       this.setIsPending(true);
       if (!this.conn) {
@@ -1348,7 +1350,10 @@ var Schematic = class {
       await this.wsSendMessage(socket, context);
     } catch (error) {
       console.warn("Failed to establish WebSocket connection:", error);
-      throw error;
+      this.context = context;
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+      this.attemptReconnect();
     }
   };
   /**
@@ -1989,7 +1994,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 +2044,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 = {
@@ -2072,6 +2094,7 @@ var Schematic = class {
     };
   };
   setIsPending = (isPending) => {
+    if (this.isPending === isPending) return;
     this.isPending = isPending;
     this.isPendingListeners.forEach(
       (listener) => notifyPendingListener(listener, isPending)
@@ -2086,11 +2109,14 @@ var Schematic = class {
       return check;
     }
     if (flagKey in this.flagCheckDefaults || flagKey in this.flagValueDefaults) {
-      return this.resolveFallbackCheckFlagReturn(
-        flagKey,
-        void 0,
-        "Default value used"
-      );
+      if (!(flagKey in this.fallbackCheckCache)) {
+        this.fallbackCheckCache[flagKey] = this.resolveFallbackCheckFlagReturn(
+          flagKey,
+          void 0,
+          "Default value used"
+        );
+      }
+      return this.fallbackCheckCache[flagKey];
     }
     return void 0;
   };
@@ -2202,7 +2228,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.16";
+var version2 = "1.2.21";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.esm.js

@@ -606,6 +606,36 @@ function v4(options, buf, offset) {
 }
 var v4_default = v4;
 var import_polyfill = __toESM(require_browser_polyfill());
+function EntitlementValueTypeFromJSON(json) {
+  return EntitlementValueTypeFromJSONTyped(json, false);
+}
+function EntitlementValueTypeFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
+function FeatureEntitlementFromJSON(json) {
+  return FeatureEntitlementFromJSONTyped(json, false);
+}
+function FeatureEntitlementFromJSONTyped(json, ignoreDiscriminator) {
+  if (json == null) {
+    return json;
+  }
+  return {
+    allocation: json["allocation"] == null ? void 0 : json["allocation"],
+    creditId: json["credit_id"] == null ? void 0 : json["credit_id"],
+    creditRemaining: json["credit_remaining"] == null ? void 0 : json["credit_remaining"],
+    creditTotal: json["credit_total"] == null ? void 0 : json["credit_total"],
+    creditUsed: json["credit_used"] == null ? void 0 : json["credit_used"],
+    eventName: json["event_name"] == null ? void 0 : json["event_name"],
+    featureId: json["feature_id"],
+    featureKey: json["feature_key"],
+    metricPeriod: json["metric_period"] == null ? void 0 : json["metric_period"],
+    metricResetAt: json["metric_reset_at"] == null ? void 0 : new Date(json["metric_reset_at"]),
+    monthReset: json["month_reset"] == null ? void 0 : json["month_reset"],
+    softLimit: json["soft_limit"] == null ? void 0 : json["soft_limit"],
+    usage: json["usage"] == null ? void 0 : json["usage"],
+    valueType: EntitlementValueTypeFromJSON(json["value_type"])
+  };
+}
 function CheckFlagResponseDataFromJSON(json) {
   return CheckFlagResponseDataFromJSONTyped(json, false);
 }
@@ -615,6 +645,7 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
   }
   return {
     companyId: json["company_id"] == null ? void 0 : json["company_id"],
+    entitlement: json["entitlement"] == null ? void 0 : FeatureEntitlementFromJSON(json["entitlement"]),
     error: json["error"] == null ? void 0 : json["error"],
     featureAllocation: json["feature_allocation"] == null ? void 0 : json["feature_allocation"],
     featureUsage: json["feature_usage"] == null ? void 0 : json["feature_usage"],
@@ -754,7 +785,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.16";
+var version = "1.2.21";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -800,6 +831,7 @@ var Schematic = class {
   retryTimer = null;
   flagValueDefaults = {};
   flagCheckDefaults = {};
+  fallbackCheckCache = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -968,8 +1000,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 +1070,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];
@@ -1052,6 +1091,13 @@ var Schematic = class {
       );
       if (typeof flagCheck !== "undefined") {
         this.submitFlagCheckEvent(key, flagCheck, context);
+      } else {
+        const fallbackResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "No flag values available"
+        );
+        this.submitFlagCheckEvent(key, fallbackResult, context);
       }
       return result;
     } catch (error) {
@@ -1144,53 +1190,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.
@@ -1264,6 +1263,9 @@ var Schematic = class {
       this.setIsPending(false);
       return Promise.resolve();
     }
+    if (contextString(context) === contextString(this.context) && this.conn !== null && !this.isPending) {
+      return;
+    }
     try {
       this.setIsPending(true);
       if (!this.conn) {
@@ -1303,7 +1305,10 @@ var Schematic = class {
       await this.wsSendMessage(socket, context);
     } catch (error) {
       console.warn("Failed to establish WebSocket connection:", error);
-      throw error;
+      this.context = context;
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+      this.attemptReconnect();
     }
   };
   /**
@@ -1944,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) {
@@ -1991,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 = {
@@ -2027,6 +2049,7 @@ var Schematic = class {
     };
   };
   setIsPending = (isPending) => {
+    if (this.isPending === isPending) return;
     this.isPending = isPending;
     this.isPendingListeners.forEach(
       (listener) => notifyPendingListener(listener, isPending)
@@ -2041,11 +2064,14 @@ var Schematic = class {
       return check;
     }
     if (flagKey in this.flagCheckDefaults || flagKey in this.flagValueDefaults) {
-      return this.resolveFallbackCheckFlagReturn(
-        flagKey,
-        void 0,
-        "Default value used"
-      );
+      if (!(flagKey in this.fallbackCheckCache)) {
+        this.fallbackCheckCache[flagKey] = this.resolveFallbackCheckFlagReturn(
+          flagKey,
+          void 0,
+          "Default value used"
+        );
+      }
+      return this.fallbackCheckCache[flagKey];
     }
     return void 0;
   };
@@ -2157,7 +2183,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.21";
 
 // 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.21",
   "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.21"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@microsoft/api-extractor": "^7.55.0",
+    "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.57.6",
     "@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",
-    "eslint": "^9.39.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@vitest/browser": "^4.0.18",
+    "esbuild": "^0.27.3",
+    "eslint": "^10.0.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.4.0",
+    "happy-dom": "^20.8.3",
     "husky": "^9.1.7",
-    "jsdom": "^27.2.0",
-    "prettier": "^3.7.4",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "jsdom": "^28.1.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.56.1",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "react": ">=18"