@schematichq/schematic-react 1.2.3 → 1.2.4

package/README.md

@@ -126,6 +126,50 @@ const MyComponent = () => {
 };
 ```
 
+## Troubleshooting
+
+For debugging and development, Schematic supports two special modes:
+
+### Debug Mode
+
+Enables console logging of all Schematic operations:
+
+```typescript
+// Enable at initialization
+import { SchematicProvider } from "@schematichq/schematic-react";
+
+ReactDOM.render(
+    <SchematicProvider publishableKey="your-publishable-key" debug={true}>
+        <App />
+    </SchematicProvider>,
+    document.getElementById("root"),
+);
+
+// Or via URL parameter
+// https://yoursite.com/?schematic_debug=true
+```
+
+### Offline Mode
+
+Prevents network requests and returns fallback values for all flag checks:
+
+```typescript
+// Enable at initialization
+import { SchematicProvider } from "@schematichq/schematic-react";
+
+ReactDOM.render(
+    <SchematicProvider publishableKey="your-publishable-key" offline={true}>
+        <App />
+    </SchematicProvider>,
+    document.getElementById("root"),
+);
+
+// Or via URL parameter
+// https://yoursite.com/?schematic_offline=true
+```
+
+Offline mode automatically enables debug mode to help with troubleshooting.
+
 ## License
 
 MIT

package/dist/schematic-react.cjs.js

@@ -671,6 +671,26 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     value: json["value"]
   };
 }
+function EventBodyFlagCheckToJSON(json) {
+  return EventBodyFlagCheckToJSONTyped(json, false);
+}
+function EventBodyFlagCheckToJSONTyped(value, ignoreDiscriminator = false) {
+  if (value == null) {
+    return value;
+  }
+  return {
+    company_id: value["companyId"],
+    error: value["error"],
+    flag_id: value["flagId"],
+    flag_key: value["flagKey"],
+    reason: value["reason"],
+    req_company: value["reqCompany"],
+    req_user: value["reqUser"],
+    rule_id: value["ruleId"],
+    user_id: value["userId"],
+    value: value["value"]
+  };
+}
 function CheckFlagResponseFromJSON(json) {
   return CheckFlagResponseFromJSONTyped(json, false);
 }
@@ -773,7 +793,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.1";
+var version = "1.2.2";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -781,6 +801,8 @@ var Schematic = class {
   apiUrl = "https://api.schematichq.com";
   conn = null;
   context = {};
+  debugEnabled = false;
+  offlineEnabled = false;
   eventQueue;
   eventUrl = "https://c.schematichq.com";
   flagCheckListeners = {};
@@ -795,6 +817,26 @@ var Schematic = class {
     this.apiKey = apiKey;
     this.eventQueue = [];
     this.useWebSocket = options?.useWebSocket ?? false;
+    this.debugEnabled = options?.debug ?? false;
+    this.offlineEnabled = options?.offline ?? false;
+    if (typeof window !== "undefined" && typeof window.location !== "undefined") {
+      const params = new URLSearchParams(window.location.search);
+      const debugParam = params.get("schematic_debug");
+      if (debugParam !== null && (debugParam === "" || debugParam === "true" || debugParam === "1")) {
+        this.debugEnabled = true;
+      }
+      const offlineParam = params.get("schematic_offline");
+      if (offlineParam !== null && (offlineParam === "" || offlineParam === "true" || offlineParam === "1")) {
+        this.offlineEnabled = true;
+        this.debugEnabled = true;
+      }
+    }
+    if (this.offlineEnabled && options?.debug !== false) {
+      this.debugEnabled = true;
+    }
+    if (this.offlineEnabled) {
+      this.setIsPending(false);
+    }
     this.additionalHeaders = {
       "X-Schematic-Client-Version": `schematic-js@${version}`,
       ...options?.additionalHeaders ?? {}
@@ -818,6 +860,13 @@ var Schematic = class {
         this.flushEventQueue();
       });
     }
+    if (this.offlineEnabled) {
+      this.debug(
+        "Initialized with offline mode enabled - no network requests will be made"
+      );
+    } else if (this.debugEnabled) {
+      this.debug("Initialized with debug mode enabled");
+    }
   }
   /**
    * Get value for a single flag.
@@ -830,6 +879,14 @@ var Schematic = class {
     const { fallback = false, key } = options;
     const context = options.context || this.context;
     const contextStr = contextString(context);
+    this.debug(`checkFlag: ${key}`, { context, fallback });
+    if (this.isOffline()) {
+      this.debug(`checkFlag offline result: ${key}`, {
+        value: fallback,
+        offlineMode: true
+      });
+      return fallback;
+    }
     if (!this.useWebSocket) {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
       return fetch(requestUrl, {
@@ -846,17 +903,32 @@ var Schematic = class {
         }
         return response.json();
       }).then((response) => {
-        return CheckFlagResponseFromJSON(response).data.value;
+        const parsedResponse = CheckFlagResponseFromJSON(response);
+        this.debug(`checkFlag result: ${key}`, parsedResponse);
+        const result = CheckFlagReturnFromJSON(parsedResponse.data);
+        this.submitFlagCheckEvent(key, result, context);
+        return result.value;
       }).catch((error) => {
         console.error("There was a problem with the fetch operation:", error);
+        const errorResult = {
+          flag: key,
+          value: fallback,
+          reason: "API request failed",
+          error: error instanceof Error ? error.message : String(error)
+        };
+        this.submitFlagCheckEvent(key, errorResult, context);
         return fallback;
       });
     }
     try {
       const existingVals = this.checks[contextStr];
-      if (this.conn && typeof existingVals !== "undefined" && typeof existingVals[key] !== "undefined") {
+      if (this.conn !== null && typeof existingVals !== "undefined" && typeof existingVals[key] !== "undefined") {
+        this.debug(`checkFlag cached result: ${key}`, existingVals[key]);
         return existingVals[key].value;
       }
+      if (this.isOffline()) {
+        return fallback;
+      }
       try {
         await this.setContext(context);
       } catch (error) {
@@ -867,16 +939,74 @@ var Schematic = class {
         return this.fallbackToRest(key, context, fallback);
       }
       const contextVals = this.checks[contextStr] ?? {};
-      return contextVals[key]?.value ?? fallback;
+      const flagCheck = contextVals[key];
+      const result = flagCheck?.value ?? fallback;
+      this.debug(
+        `checkFlag WebSocket result: ${key}`,
+        typeof flagCheck !== "undefined" ? flagCheck : { value: fallback, fallbackUsed: true }
+      );
+      if (typeof flagCheck !== "undefined") {
+        this.submitFlagCheckEvent(key, flagCheck, context);
+      }
+      return result;
     } catch (error) {
       console.error("Unexpected error in checkFlag:", error);
+      const errorResult = {
+        flag: key,
+        value: fallback,
+        reason: "Unexpected error in flag check",
+        error: error instanceof Error ? error.message : String(error)
+      };
+      this.submitFlagCheckEvent(key, errorResult, context);
       return fallback;
     }
   }
+  /**
+   * Helper function to log debug messages
+   * Only logs if debug mode is enabled
+   */
+  debug(message, ...args) {
+    if (this.debugEnabled) {
+      console.log(`[Schematic] ${message}`, ...args);
+    }
+  }
+  /**
+   * Helper function to check if client is in offline mode
+   */
+  isOffline() {
+    return this.offlineEnabled;
+  }
+  /**
+   * Submit a flag check event
+   * Records data about a flag check for analytics
+   */
+  submitFlagCheckEvent(flagKey, result, context) {
+    const eventBody = {
+      flagKey,
+      value: result.value,
+      reason: result.reason,
+      flagId: result.flagId,
+      ruleId: result.ruleId,
+      companyId: result.companyId,
+      userId: result.userId,
+      error: result.error,
+      reqCompany: context.company,
+      reqUser: context.user
+    };
+    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()) {
+      this.debug(`fallbackToRest offline result: ${key}`, {
+        value: fallback,
+        offlineMode: true
+      });
+      return fallback;
+    }
     try {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
       const response = await fetch(requestUrl, {
@@ -891,19 +1021,36 @@ var Schematic = class {
       if (!response.ok) {
         throw new Error("Network response was not ok");
       }
-      const data = CheckFlagResponseFromJSON(await response.json());
-      return data?.data?.value ?? false;
+      const responseJson = await response.json();
+      const data = CheckFlagResponseFromJSON(responseJson);
+      this.debug(`fallbackToRest result: ${key}`, data);
+      const result = CheckFlagReturnFromJSON(data.data);
+      this.submitFlagCheckEvent(key, result, context);
+      return result.value;
     } catch (error) {
       console.error("REST API call failed, using fallback value:", error);
+      const errorResult = {
+        flag: key,
+        value: fallback,
+        reason: "API request failed (fallback)",
+        error: error instanceof Error ? error.message : String(error)
+      };
+      this.submitFlagCheckEvent(key, errorResult, context);
       return fallback;
     }
   }
   /**
    * Make an API call to fetch all flag values for a given context.
    * Recommended for use in REST mode only.
+   * In offline mode, returns an empty object.
    */
   checkFlags = async (context) => {
     context = context || this.context;
+    this.debug(`checkFlags`, { context });
+    if (this.isOffline()) {
+      this.debug(`checkFlags offline result: returning empty object`);
+      return {};
+    }
     const requestUrl = `${this.apiUrl}/flags/check`;
     const requestBody = JSON.stringify(context);
     return fetch(requestUrl, {
@@ -921,6 +1068,7 @@ var Schematic = class {
       return response.json();
     }).then((responseJson) => {
       const resp = CheckFlagsResponseFromJSON(responseJson);
+      this.debug(`checkFlags result:`, resp);
       return (resp?.data?.flags ?? []).reduce(
         (accum, flag) => {
           accum[flag.flag] = flag.value;
@@ -939,6 +1087,7 @@ var Schematic = class {
    * send an identify event to the Schematic API which will upsert a user and company.
    */
   identify = (body) => {
+    this.debug(`identify:`, body);
     try {
       this.setContext({
         company: body.company?.keys,
@@ -956,10 +1105,15 @@ var Schematic = class {
    * 2. Send the context to the server
    * 3. Wait for initial flag values to be returned
    * The promise resolves when initial flag values are received.
+   * In offline mode, this will just set the context locally without connecting.
    */
   setContext = async (context) => {
-    if (!this.useWebSocket) {
+    if (this.isOffline()) {
       this.context = context;
+      this.setIsPending(false);
+      return Promise.resolve();
+    }
+    if (!this.useWebSocket) {
       return Promise.resolve();
     }
     try {
@@ -980,12 +1134,14 @@ var Schematic = class {
    */
   track = (body) => {
     const { company, user, event, traits } = body;
-    return this.handleEvent("track", {
+    const trackData = {
       company: company ?? this.context.company,
       event,
       traits: traits ?? {},
       user: user ?? this.context.user
-    });
+    };
+    this.debug(`track:`, trackData);
+    return this.handleEvent("track", trackData);
   };
   /**
    * Event processing
@@ -1028,8 +1184,13 @@ var Schematic = class {
   sendEvent = async (event) => {
     const captureUrl = `${this.eventUrl}/e`;
     const payload = JSON.stringify(event);
+    this.debug(`sending event:`, { url: captureUrl, event });
+    if (this.isOffline()) {
+      this.debug(`event not sent (offline mode):`, { event });
+      return Promise.resolve();
+    }
     try {
-      await fetch(captureUrl, {
+      const response = await fetch(captureUrl, {
         method: "POST",
         headers: {
           ...this.additionalHeaders ?? {},
@@ -1037,6 +1198,10 @@ var Schematic = class {
         },
         body: payload
       });
+      this.debug(`event sent:`, {
+        status: response.status,
+        statusText: response.statusText
+      });
     } catch (error) {
       console.error("Error sending Schematic event: ", error);
     }
@@ -1051,8 +1216,13 @@ var Schematic = class {
    */
   /**
    * If using websocket mode, close the connection when done.
+   * In offline mode, this is a no-op.
    */
   cleanup = async () => {
+    if (this.isOffline()) {
+      this.debug("cleanup: skipped (offline mode)");
+      return Promise.resolve();
+    }
     if (this.conn) {
       try {
         const socket = await this.conn;
@@ -1066,16 +1236,26 @@ var Schematic = class {
   };
   // Open a websocket connection
   wsConnect = () => {
+    if (this.isOffline()) {
+      this.debug("wsConnect: skipped (offline mode)");
+      return Promise.reject(
+        new Error("WebSocket connection skipped in offline mode")
+      );
+    }
     return new Promise((resolve, reject) => {
       const wsUrl = `${this.webSocketUrl}/flags/bootstrap?apiKey=${this.apiKey}`;
+      this.debug(`connecting to WebSocket:`, wsUrl);
       const webSocket = new WebSocket(wsUrl);
       webSocket.onopen = () => {
+        this.debug(`WebSocket connection opened`);
         resolve(webSocket);
       };
       webSocket.onerror = (error) => {
+        this.debug(`WebSocket connection error:`, error);
         reject(error);
       };
       webSocket.onclose = () => {
+        this.debug(`WebSocket connection closed`);
         this.conn = null;
       };
     });
@@ -1083,21 +1263,37 @@ var Schematic = class {
   // 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) => {
+    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)) {
+        this.debug(`WebSocket context unchanged, skipping update`);
         return resolve(this.setIsPending(false));
       }
+      this.debug(`WebSocket context updated:`, context);
       this.context = context;
       const sendMessage = () => {
         let resolved = false;
         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);
             this.checks[contextString(context)][flagCheck.flag] = flagCheck;
+            this.debug(`WebSocket flag update:`, {
+              flag: flagCheck.flag,
+              value: flagCheck.value,
+              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);
           });
@@ -1108,19 +1304,23 @@ var Schematic = class {
           }
         };
         socket.addEventListener("message", messageHandler);
-        socket.send(
-          JSON.stringify({
-            apiKey: this.apiKey,
-            clientVersion: `schematic-js@${version}`,
-            data: context
-          })
-        );
+        const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
+        const messagePayload = {
+          apiKey: this.apiKey,
+          clientVersion,
+          data: context
+        };
+        this.debug(`WebSocket sending message:`, messagePayload);
+        socket.send(JSON.stringify(messagePayload));
       };
       if (socket.readyState === WebSocket.OPEN) {
+        this.debug(`WebSocket already open, sending message`);
         sendMessage();
       } else if (socket.readyState === WebSocket.CONNECTING) {
+        this.debug(`WebSocket connecting, waiting for open to send message`);
         socket.addEventListener("open", sendMessage);
       } else {
+        this.debug(`WebSocket is closed, cannot send message`);
         reject("WebSocket is not open or connecting");
       }
     });
@@ -1177,10 +1377,22 @@ var Schematic = class {
   };
   notifyFlagCheckListeners = (flagKey, check) => {
     const listeners = this.flagCheckListeners?.[flagKey] ?? [];
+    if (listeners.size > 0) {
+      this.debug(
+        `Notifying ${listeners.size} flag check listeners for ${flagKey}`,
+        check
+      );
+    }
     listeners.forEach((listener) => notifyFlagCheckListener(listener, check));
   };
   notifyFlagValueListeners = (flagKey, value) => {
     const listeners = this.flagValueListeners?.[flagKey] ?? [];
+    if (listeners.size > 0) {
+      this.debug(
+        `Notifying ${listeners.size} flag value listeners for ${flagKey}`,
+        { value }
+      );
+    }
     listeners.forEach((listener) => notifyFlagValueListener(listener, value));
   };
 };
@@ -1210,7 +1422,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.3";
+var version2 = "1.2.4";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.esm.js

@@ -626,6 +626,26 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     value: json["value"]
   };
 }
+function EventBodyFlagCheckToJSON(json) {
+  return EventBodyFlagCheckToJSONTyped(json, false);
+}
+function EventBodyFlagCheckToJSONTyped(value, ignoreDiscriminator = false) {
+  if (value == null) {
+    return value;
+  }
+  return {
+    company_id: value["companyId"],
+    error: value["error"],
+    flag_id: value["flagId"],
+    flag_key: value["flagKey"],
+    reason: value["reason"],
+    req_company: value["reqCompany"],
+    req_user: value["reqUser"],
+    rule_id: value["ruleId"],
+    user_id: value["userId"],
+    value: value["value"]
+  };
+}
 function CheckFlagResponseFromJSON(json) {
   return CheckFlagResponseFromJSONTyped(json, false);
 }
@@ -728,7 +748,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.1";
+var version = "1.2.2";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -736,6 +756,8 @@ var Schematic = class {
   apiUrl = "https://api.schematichq.com";
   conn = null;
   context = {};
+  debugEnabled = false;
+  offlineEnabled = false;
   eventQueue;
   eventUrl = "https://c.schematichq.com";
   flagCheckListeners = {};
@@ -750,6 +772,26 @@ var Schematic = class {
     this.apiKey = apiKey;
     this.eventQueue = [];
     this.useWebSocket = options?.useWebSocket ?? false;
+    this.debugEnabled = options?.debug ?? false;
+    this.offlineEnabled = options?.offline ?? false;
+    if (typeof window !== "undefined" && typeof window.location !== "undefined") {
+      const params = new URLSearchParams(window.location.search);
+      const debugParam = params.get("schematic_debug");
+      if (debugParam !== null && (debugParam === "" || debugParam === "true" || debugParam === "1")) {
+        this.debugEnabled = true;
+      }
+      const offlineParam = params.get("schematic_offline");
+      if (offlineParam !== null && (offlineParam === "" || offlineParam === "true" || offlineParam === "1")) {
+        this.offlineEnabled = true;
+        this.debugEnabled = true;
+      }
+    }
+    if (this.offlineEnabled && options?.debug !== false) {
+      this.debugEnabled = true;
+    }
+    if (this.offlineEnabled) {
+      this.setIsPending(false);
+    }
     this.additionalHeaders = {
       "X-Schematic-Client-Version": `schematic-js@${version}`,
       ...options?.additionalHeaders ?? {}
@@ -773,6 +815,13 @@ var Schematic = class {
         this.flushEventQueue();
       });
     }
+    if (this.offlineEnabled) {
+      this.debug(
+        "Initialized with offline mode enabled - no network requests will be made"
+      );
+    } else if (this.debugEnabled) {
+      this.debug("Initialized with debug mode enabled");
+    }
   }
   /**
    * Get value for a single flag.
@@ -785,6 +834,14 @@ var Schematic = class {
     const { fallback = false, key } = options;
     const context = options.context || this.context;
     const contextStr = contextString(context);
+    this.debug(`checkFlag: ${key}`, { context, fallback });
+    if (this.isOffline()) {
+      this.debug(`checkFlag offline result: ${key}`, {
+        value: fallback,
+        offlineMode: true
+      });
+      return fallback;
+    }
     if (!this.useWebSocket) {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
       return fetch(requestUrl, {
@@ -801,17 +858,32 @@ var Schematic = class {
         }
         return response.json();
       }).then((response) => {
-        return CheckFlagResponseFromJSON(response).data.value;
+        const parsedResponse = CheckFlagResponseFromJSON(response);
+        this.debug(`checkFlag result: ${key}`, parsedResponse);
+        const result = CheckFlagReturnFromJSON(parsedResponse.data);
+        this.submitFlagCheckEvent(key, result, context);
+        return result.value;
       }).catch((error) => {
         console.error("There was a problem with the fetch operation:", error);
+        const errorResult = {
+          flag: key,
+          value: fallback,
+          reason: "API request failed",
+          error: error instanceof Error ? error.message : String(error)
+        };
+        this.submitFlagCheckEvent(key, errorResult, context);
         return fallback;
       });
     }
     try {
       const existingVals = this.checks[contextStr];
-      if (this.conn && typeof existingVals !== "undefined" && typeof existingVals[key] !== "undefined") {
+      if (this.conn !== null && typeof existingVals !== "undefined" && typeof existingVals[key] !== "undefined") {
+        this.debug(`checkFlag cached result: ${key}`, existingVals[key]);
         return existingVals[key].value;
       }
+      if (this.isOffline()) {
+        return fallback;
+      }
       try {
         await this.setContext(context);
       } catch (error) {
@@ -822,16 +894,74 @@ var Schematic = class {
         return this.fallbackToRest(key, context, fallback);
       }
       const contextVals = this.checks[contextStr] ?? {};
-      return contextVals[key]?.value ?? fallback;
+      const flagCheck = contextVals[key];
+      const result = flagCheck?.value ?? fallback;
+      this.debug(
+        `checkFlag WebSocket result: ${key}`,
+        typeof flagCheck !== "undefined" ? flagCheck : { value: fallback, fallbackUsed: true }
+      );
+      if (typeof flagCheck !== "undefined") {
+        this.submitFlagCheckEvent(key, flagCheck, context);
+      }
+      return result;
     } catch (error) {
       console.error("Unexpected error in checkFlag:", error);
+      const errorResult = {
+        flag: key,
+        value: fallback,
+        reason: "Unexpected error in flag check",
+        error: error instanceof Error ? error.message : String(error)
+      };
+      this.submitFlagCheckEvent(key, errorResult, context);
       return fallback;
     }
   }
+  /**
+   * Helper function to log debug messages
+   * Only logs if debug mode is enabled
+   */
+  debug(message, ...args) {
+    if (this.debugEnabled) {
+      console.log(`[Schematic] ${message}`, ...args);
+    }
+  }
+  /**
+   * Helper function to check if client is in offline mode
+   */
+  isOffline() {
+    return this.offlineEnabled;
+  }
+  /**
+   * Submit a flag check event
+   * Records data about a flag check for analytics
+   */
+  submitFlagCheckEvent(flagKey, result, context) {
+    const eventBody = {
+      flagKey,
+      value: result.value,
+      reason: result.reason,
+      flagId: result.flagId,
+      ruleId: result.ruleId,
+      companyId: result.companyId,
+      userId: result.userId,
+      error: result.error,
+      reqCompany: context.company,
+      reqUser: context.user
+    };
+    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()) {
+      this.debug(`fallbackToRest offline result: ${key}`, {
+        value: fallback,
+        offlineMode: true
+      });
+      return fallback;
+    }
     try {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
       const response = await fetch(requestUrl, {
@@ -846,19 +976,36 @@ var Schematic = class {
       if (!response.ok) {
         throw new Error("Network response was not ok");
       }
-      const data = CheckFlagResponseFromJSON(await response.json());
-      return data?.data?.value ?? false;
+      const responseJson = await response.json();
+      const data = CheckFlagResponseFromJSON(responseJson);
+      this.debug(`fallbackToRest result: ${key}`, data);
+      const result = CheckFlagReturnFromJSON(data.data);
+      this.submitFlagCheckEvent(key, result, context);
+      return result.value;
     } catch (error) {
       console.error("REST API call failed, using fallback value:", error);
+      const errorResult = {
+        flag: key,
+        value: fallback,
+        reason: "API request failed (fallback)",
+        error: error instanceof Error ? error.message : String(error)
+      };
+      this.submitFlagCheckEvent(key, errorResult, context);
       return fallback;
     }
   }
   /**
    * Make an API call to fetch all flag values for a given context.
    * Recommended for use in REST mode only.
+   * In offline mode, returns an empty object.
    */
   checkFlags = async (context) => {
     context = context || this.context;
+    this.debug(`checkFlags`, { context });
+    if (this.isOffline()) {
+      this.debug(`checkFlags offline result: returning empty object`);
+      return {};
+    }
     const requestUrl = `${this.apiUrl}/flags/check`;
     const requestBody = JSON.stringify(context);
     return fetch(requestUrl, {
@@ -876,6 +1023,7 @@ var Schematic = class {
       return response.json();
     }).then((responseJson) => {
       const resp = CheckFlagsResponseFromJSON(responseJson);
+      this.debug(`checkFlags result:`, resp);
       return (resp?.data?.flags ?? []).reduce(
         (accum, flag) => {
           accum[flag.flag] = flag.value;
@@ -894,6 +1042,7 @@ var Schematic = class {
    * send an identify event to the Schematic API which will upsert a user and company.
    */
   identify = (body) => {
+    this.debug(`identify:`, body);
     try {
       this.setContext({
         company: body.company?.keys,
@@ -911,10 +1060,15 @@ var Schematic = class {
    * 2. Send the context to the server
    * 3. Wait for initial flag values to be returned
    * The promise resolves when initial flag values are received.
+   * In offline mode, this will just set the context locally without connecting.
    */
   setContext = async (context) => {
-    if (!this.useWebSocket) {
+    if (this.isOffline()) {
       this.context = context;
+      this.setIsPending(false);
+      return Promise.resolve();
+    }
+    if (!this.useWebSocket) {
       return Promise.resolve();
     }
     try {
@@ -935,12 +1089,14 @@ var Schematic = class {
    */
   track = (body) => {
     const { company, user, event, traits } = body;
-    return this.handleEvent("track", {
+    const trackData = {
       company: company ?? this.context.company,
       event,
       traits: traits ?? {},
       user: user ?? this.context.user
-    });
+    };
+    this.debug(`track:`, trackData);
+    return this.handleEvent("track", trackData);
   };
   /**
    * Event processing
@@ -983,8 +1139,13 @@ var Schematic = class {
   sendEvent = async (event) => {
     const captureUrl = `${this.eventUrl}/e`;
     const payload = JSON.stringify(event);
+    this.debug(`sending event:`, { url: captureUrl, event });
+    if (this.isOffline()) {
+      this.debug(`event not sent (offline mode):`, { event });
+      return Promise.resolve();
+    }
     try {
-      await fetch(captureUrl, {
+      const response = await fetch(captureUrl, {
         method: "POST",
         headers: {
           ...this.additionalHeaders ?? {},
@@ -992,6 +1153,10 @@ var Schematic = class {
         },
         body: payload
       });
+      this.debug(`event sent:`, {
+        status: response.status,
+        statusText: response.statusText
+      });
     } catch (error) {
       console.error("Error sending Schematic event: ", error);
     }
@@ -1006,8 +1171,13 @@ var Schematic = class {
    */
   /**
    * If using websocket mode, close the connection when done.
+   * In offline mode, this is a no-op.
    */
   cleanup = async () => {
+    if (this.isOffline()) {
+      this.debug("cleanup: skipped (offline mode)");
+      return Promise.resolve();
+    }
     if (this.conn) {
       try {
         const socket = await this.conn;
@@ -1021,16 +1191,26 @@ var Schematic = class {
   };
   // Open a websocket connection
   wsConnect = () => {
+    if (this.isOffline()) {
+      this.debug("wsConnect: skipped (offline mode)");
+      return Promise.reject(
+        new Error("WebSocket connection skipped in offline mode")
+      );
+    }
     return new Promise((resolve, reject) => {
       const wsUrl = `${this.webSocketUrl}/flags/bootstrap?apiKey=${this.apiKey}`;
+      this.debug(`connecting to WebSocket:`, wsUrl);
       const webSocket = new WebSocket(wsUrl);
       webSocket.onopen = () => {
+        this.debug(`WebSocket connection opened`);
         resolve(webSocket);
       };
       webSocket.onerror = (error) => {
+        this.debug(`WebSocket connection error:`, error);
         reject(error);
       };
       webSocket.onclose = () => {
+        this.debug(`WebSocket connection closed`);
         this.conn = null;
       };
     });
@@ -1038,21 +1218,37 @@ var Schematic = class {
   // 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) => {
+    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)) {
+        this.debug(`WebSocket context unchanged, skipping update`);
         return resolve(this.setIsPending(false));
       }
+      this.debug(`WebSocket context updated:`, context);
       this.context = context;
       const sendMessage = () => {
         let resolved = false;
         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);
             this.checks[contextString(context)][flagCheck.flag] = flagCheck;
+            this.debug(`WebSocket flag update:`, {
+              flag: flagCheck.flag,
+              value: flagCheck.value,
+              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);
           });
@@ -1063,19 +1259,23 @@ var Schematic = class {
           }
         };
         socket.addEventListener("message", messageHandler);
-        socket.send(
-          JSON.stringify({
-            apiKey: this.apiKey,
-            clientVersion: `schematic-js@${version}`,
-            data: context
-          })
-        );
+        const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
+        const messagePayload = {
+          apiKey: this.apiKey,
+          clientVersion,
+          data: context
+        };
+        this.debug(`WebSocket sending message:`, messagePayload);
+        socket.send(JSON.stringify(messagePayload));
       };
       if (socket.readyState === WebSocket.OPEN) {
+        this.debug(`WebSocket already open, sending message`);
         sendMessage();
       } else if (socket.readyState === WebSocket.CONNECTING) {
+        this.debug(`WebSocket connecting, waiting for open to send message`);
         socket.addEventListener("open", sendMessage);
       } else {
+        this.debug(`WebSocket is closed, cannot send message`);
         reject("WebSocket is not open or connecting");
       }
     });
@@ -1132,10 +1332,22 @@ var Schematic = class {
   };
   notifyFlagCheckListeners = (flagKey, check) => {
     const listeners = this.flagCheckListeners?.[flagKey] ?? [];
+    if (listeners.size > 0) {
+      this.debug(
+        `Notifying ${listeners.size} flag check listeners for ${flagKey}`,
+        check
+      );
+    }
     listeners.forEach((listener) => notifyFlagCheckListener(listener, check));
   };
   notifyFlagValueListeners = (flagKey, value) => {
     const listeners = this.flagValueListeners?.[flagKey] ?? [];
+    if (listeners.size > 0) {
+      this.debug(
+        `Notifying ${listeners.size} flag value listeners for ${flagKey}`,
+        { value }
+      );
+    }
     listeners.forEach((listener) => notifyFlagValueListener(listener, value));
   };
 };
@@ -1165,7 +1377,7 @@ var notifyFlagValueListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.2.3";
+var version2 = "1.2.4";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schematichq/schematic-react",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -28,7 +28,7 @@
     "tsc": "npx tsc"
   },
   "dependencies": {
-    "@schematichq/schematic-js": "^1.2.1"
+    "@schematichq/schematic-js": "^1.2.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.49.2",
@@ -36,7 +36,7 @@
     "@types/react": "^19.0.8",
     "@typescript-eslint/eslint-plugin": "^8.23.0",
     "@typescript-eslint/parser": "^8.23.0",
-    "esbuild": "^0.24.2",
+    "esbuild": "^0.25.0",
     "esbuild-jest": "^0.5.0",
     "eslint": "^8.57.1",
     "eslint-plugin-import": "^2.31.0",