@schematichq/schematic-react 1.2.3 → 1.2.5

package/README.md

@@ -53,6 +53,8 @@ const MyComponent = () => {
 };
 ```
 
+To learn more about identifying companies with the `keys` map, see [key management in Schematic public docs](https://docs.schematichq.com/developer_resources/key_management).
+
 ### Tracking usage
 
 Once you've set the context with `identify`, you can track events:
@@ -71,6 +73,12 @@ const MyComponent = () => {
 };
 ```
 
+If you want to record large numbers of the same event at once, or perhaps measure usage in terms of a unit like tokens or memory, you can optionally specify a quantity for your event:
+
+```tsx
+track({ event: "query", quantity: 10 });
+```
+
 ### Checking flags
 
 To check a flag, you can use the `useSchematicFlag` hook:
@@ -126,6 +134,51 @@ 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

@@ -660,6 +660,7 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     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"],
+    featureUsageEvent: json["feature_usage_event"] == null ? void 0 : json["feature_usage_event"],
     featureUsagePeriod: json["feature_usage_period"] == null ? void 0 : json["feature_usage_period"],
     featureUsageResetAt: json["feature_usage_reset_at"] == null ? void 0 : new Date(json["feature_usage_reset_at"]),
     flag: json["flag"],
@@ -671,6 +672,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);
 }
@@ -729,6 +750,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -748,6 +770,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error: error == null ? void 0 : error,
     featureAllocation: featureAllocation == null ? void 0 : featureAllocation,
     featureUsage: featureUsage == null ? void 0 : featureUsage,
+    featureUsageEvent: featureUsageEvent === null ? void 0 : featureUsageEvent,
     featureUsagePeriod: featureUsagePeriod == null ? void 0 : featureUsagePeriod,
     featureUsageResetAt: featureUsageResetAt == null ? void 0 : featureUsageResetAt,
     flag,
@@ -773,7 +796,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.1";
+var version = "1.2.3";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -781,6 +804,8 @@ var Schematic = class {
   apiUrl = "https://api.schematichq.com";
   conn = null;
   context = {};
+  debugEnabled = false;
+  offlineEnabled = false;
   eventQueue;
   eventUrl = "https://c.schematichq.com";
   flagCheckListeners = {};
@@ -790,11 +815,32 @@ var Schematic = class {
   storage;
   useWebSocket = false;
   checks = {};
+  featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
   constructor(apiKey, options) {
     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 +864,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 +883,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 +907,35 @@ 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);
+        if (typeof result.featureUsageEvent === "string") {
+          this.updateFeatureUsageEventMap(result);
+        }
+        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 +946,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 +1028,39 @@ 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);
+      if (typeof result.featureUsageEvent === "string") {
+        this.updateFeatureUsageEventMap(result);
+      }
+      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 +1078,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 +1097,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 +1115,12 @@ 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.useWebSocket) {
       this.context = context;
+      this.setIsPending(false);
       return Promise.resolve();
     }
     try {
@@ -977,14 +1138,67 @@ var Schematic = class {
   /**
    * Send a track event
    * Track usage for a company and/or user.
+   * Optimistically updates feature usage flags if tracking a featureUsageEvent.
    */
   track = (body) => {
-    const { company, user, event, traits } = body;
-    return this.handleEvent("track", {
+    const { company, user, event, traits, quantity = 1 } = body;
+    const trackData = {
       company: company ?? this.context.company,
       event,
       traits: traits ?? {},
-      user: user ?? this.context.user
+      user: user ?? this.context.user,
+      quantity
+    };
+    this.debug(`track:`, trackData);
+    if (event in this.featureUsageEventMap) {
+      this.optimisticallyUpdateFeatureUsage(event, quantity);
+    }
+    return this.handleEvent("track", trackData);
+  };
+  /**
+   * Optimistically update feature usage flags associated with a tracked event
+   * This updates flags in memory with updated usage counts and value/featureUsageExceeded flags
+   * before the network request completes
+   */
+  optimisticallyUpdateFeatureUsage = (eventName, quantity = 1) => {
+    const flagsForEvent = this.featureUsageEventMap[eventName];
+    if (flagsForEvent === void 0 || flagsForEvent === null) return;
+    this.debug(
+      `Optimistically updating feature usage for event: ${eventName}`,
+      { quantity }
+    );
+    Object.entries(flagsForEvent).forEach(([flagKey, check]) => {
+      if (check === void 0) return;
+      const updatedCheck = { ...check };
+      if (typeof updatedCheck.featureUsage === "number") {
+        updatedCheck.featureUsage += quantity;
+        if (typeof updatedCheck.featureAllocation === "number") {
+          const wasExceeded = updatedCheck.featureUsageExceeded === true;
+          const nowExceeded = updatedCheck.featureUsage >= updatedCheck.featureAllocation;
+          if (nowExceeded !== wasExceeded) {
+            updatedCheck.featureUsageExceeded = nowExceeded;
+            if (nowExceeded) {
+              updatedCheck.value = false;
+            }
+            this.debug(`Usage limit status changed for flag: ${flagKey}`, {
+              was: wasExceeded ? "exceeded" : "within limits",
+              now: nowExceeded ? "exceeded" : "within limits",
+              featureUsage: updatedCheck.featureUsage,
+              featureAllocation: updatedCheck.featureAllocation,
+              value: updatedCheck.value
+            });
+          }
+        }
+        if (this.featureUsageEventMap[eventName] !== void 0) {
+          this.featureUsageEventMap[eventName][flagKey] = updatedCheck;
+        }
+        const contextStr = contextString(this.context);
+        if (this.checks[contextStr] !== void 0 && this.checks[contextStr] !== null) {
+          this.checks[contextStr][flagKey] = updatedCheck;
+        }
+        this.notifyFlagCheckListeners(flagKey, updatedCheck);
+        this.notifyFlagValueListeners(flagKey, updatedCheck.value);
+      }
     });
   };
   /**
@@ -1028,8 +1242,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 +1256,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 +1274,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 +1294,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 +1321,44 @@ 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;
+            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);
           });
@@ -1108,19 +1369,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 +1442,40 @@ 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
+      );
+    }
+    if (typeof check.featureUsageEvent === "string") {
+      this.updateFeatureUsageEventMap(check);
+    }
     listeners.forEach((listener) => notifyFlagCheckListener(listener, check));
   };
+  /** Add or update a CheckFlagReturn in the featureUsageEventMap */
+  updateFeatureUsageEventMap = (check) => {
+    if (typeof check.featureUsageEvent !== "string") return;
+    const eventName = check.featureUsageEvent;
+    if (this.featureUsageEventMap[eventName] === void 0 || this.featureUsageEventMap[eventName] === null) {
+      this.featureUsageEventMap[eventName] = {};
+    }
+    if (this.featureUsageEventMap[eventName] !== void 0) {
+      this.featureUsageEventMap[eventName][check.flag] = check;
+    }
+    this.debug(
+      `Updated featureUsageEventMap for event: ${eventName}, flag: ${check.flag}`,
+      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 +1505,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.3";
+var version2 = "1.2.5";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.esm.js

@@ -615,6 +615,7 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     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"],
+    featureUsageEvent: json["feature_usage_event"] == null ? void 0 : json["feature_usage_event"],
     featureUsagePeriod: json["feature_usage_period"] == null ? void 0 : json["feature_usage_period"],
     featureUsageResetAt: json["feature_usage_reset_at"] == null ? void 0 : new Date(json["feature_usage_reset_at"]),
     flag: json["flag"],
@@ -626,6 +627,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);
 }
@@ -684,6 +705,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -703,6 +725,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error: error == null ? void 0 : error,
     featureAllocation: featureAllocation == null ? void 0 : featureAllocation,
     featureUsage: featureUsage == null ? void 0 : featureUsage,
+    featureUsageEvent: featureUsageEvent === null ? void 0 : featureUsageEvent,
     featureUsagePeriod: featureUsagePeriod == null ? void 0 : featureUsagePeriod,
     featureUsageResetAt: featureUsageResetAt == null ? void 0 : featureUsageResetAt,
     flag,
@@ -728,7 +751,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.1";
+var version = "1.2.3";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -736,6 +759,8 @@ var Schematic = class {
   apiUrl = "https://api.schematichq.com";
   conn = null;
   context = {};
+  debugEnabled = false;
+  offlineEnabled = false;
   eventQueue;
   eventUrl = "https://c.schematichq.com";
   flagCheckListeners = {};
@@ -745,11 +770,32 @@ var Schematic = class {
   storage;
   useWebSocket = false;
   checks = {};
+  featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
   constructor(apiKey, options) {
     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 +819,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 +838,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 +862,35 @@ 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);
+        if (typeof result.featureUsageEvent === "string") {
+          this.updateFeatureUsageEventMap(result);
+        }
+        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 +901,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 +983,39 @@ 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);
+      if (typeof result.featureUsageEvent === "string") {
+        this.updateFeatureUsageEventMap(result);
+      }
+      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 +1033,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 +1052,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 +1070,12 @@ 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.useWebSocket) {
       this.context = context;
+      this.setIsPending(false);
       return Promise.resolve();
     }
     try {
@@ -932,14 +1093,67 @@ var Schematic = class {
   /**
    * Send a track event
    * Track usage for a company and/or user.
+   * Optimistically updates feature usage flags if tracking a featureUsageEvent.
    */
   track = (body) => {
-    const { company, user, event, traits } = body;
-    return this.handleEvent("track", {
+    const { company, user, event, traits, quantity = 1 } = body;
+    const trackData = {
       company: company ?? this.context.company,
       event,
       traits: traits ?? {},
-      user: user ?? this.context.user
+      user: user ?? this.context.user,
+      quantity
+    };
+    this.debug(`track:`, trackData);
+    if (event in this.featureUsageEventMap) {
+      this.optimisticallyUpdateFeatureUsage(event, quantity);
+    }
+    return this.handleEvent("track", trackData);
+  };
+  /**
+   * Optimistically update feature usage flags associated with a tracked event
+   * This updates flags in memory with updated usage counts and value/featureUsageExceeded flags
+   * before the network request completes
+   */
+  optimisticallyUpdateFeatureUsage = (eventName, quantity = 1) => {
+    const flagsForEvent = this.featureUsageEventMap[eventName];
+    if (flagsForEvent === void 0 || flagsForEvent === null) return;
+    this.debug(
+      `Optimistically updating feature usage for event: ${eventName}`,
+      { quantity }
+    );
+    Object.entries(flagsForEvent).forEach(([flagKey, check]) => {
+      if (check === void 0) return;
+      const updatedCheck = { ...check };
+      if (typeof updatedCheck.featureUsage === "number") {
+        updatedCheck.featureUsage += quantity;
+        if (typeof updatedCheck.featureAllocation === "number") {
+          const wasExceeded = updatedCheck.featureUsageExceeded === true;
+          const nowExceeded = updatedCheck.featureUsage >= updatedCheck.featureAllocation;
+          if (nowExceeded !== wasExceeded) {
+            updatedCheck.featureUsageExceeded = nowExceeded;
+            if (nowExceeded) {
+              updatedCheck.value = false;
+            }
+            this.debug(`Usage limit status changed for flag: ${flagKey}`, {
+              was: wasExceeded ? "exceeded" : "within limits",
+              now: nowExceeded ? "exceeded" : "within limits",
+              featureUsage: updatedCheck.featureUsage,
+              featureAllocation: updatedCheck.featureAllocation,
+              value: updatedCheck.value
+            });
+          }
+        }
+        if (this.featureUsageEventMap[eventName] !== void 0) {
+          this.featureUsageEventMap[eventName][flagKey] = updatedCheck;
+        }
+        const contextStr = contextString(this.context);
+        if (this.checks[contextStr] !== void 0 && this.checks[contextStr] !== null) {
+          this.checks[contextStr][flagKey] = updatedCheck;
+        }
+        this.notifyFlagCheckListeners(flagKey, updatedCheck);
+        this.notifyFlagValueListeners(flagKey, updatedCheck.value);
+      }
     });
   };
   /**
@@ -983,8 +1197,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 +1211,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 +1229,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 +1249,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 +1276,44 @@ 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;
+            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);
           });
@@ -1063,19 +1324,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 +1397,40 @@ 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
+      );
+    }
+    if (typeof check.featureUsageEvent === "string") {
+      this.updateFeatureUsageEventMap(check);
+    }
     listeners.forEach((listener) => notifyFlagCheckListener(listener, check));
   };
+  /** Add or update a CheckFlagReturn in the featureUsageEventMap */
+  updateFeatureUsageEventMap = (check) => {
+    if (typeof check.featureUsageEvent !== "string") return;
+    const eventName = check.featureUsageEvent;
+    if (this.featureUsageEventMap[eventName] === void 0 || this.featureUsageEventMap[eventName] === null) {
+      this.featureUsageEventMap[eventName] = {};
+    }
+    if (this.featureUsageEventMap[eventName] !== void 0) {
+      this.featureUsageEventMap[eventName][check.flag] = check;
+    }
+    this.debug(
+      `Updated featureUsageEventMap for event: ${eventName}, flag: ${check.flag}`,
+      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 +1460,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.5";
 
 // 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.5",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -25,31 +25,34 @@
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --fix",
     "test": "jest --config jest.config.js",
-    "tsc": "npx tsc"
+    "tsc": "npx tsc",
+    "prepare": "husky"
   },
   "dependencies": {
-    "@schematichq/schematic-js": "^1.2.1"
+    "@schematichq/schematic-js": "^1.2.3"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.49.2",
+    "@eslint/js": "^9.24.0",
+    "@microsoft/api-extractor": "^7.52.2",
     "@types/jest": "^29.5.14",
-    "@types/react": "^19.0.8",
-    "@typescript-eslint/eslint-plugin": "^8.23.0",
-    "@typescript-eslint/parser": "^8.23.0",
-    "esbuild": "^0.24.2",
+    "@types/react": "^19.1.1",
+    "esbuild": "^0.25.2",
     "esbuild-jest": "^0.5.0",
-    "eslint": "^8.57.1",
+    "eslint": "^9.24.0",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.1.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-esbuild": "^0.3.0",
     "jest-fetch-mock": "^3.0.3",
     "prettier": "^3.4.2",
-    "react": "^19.0.0",
-    "ts-jest": "^29.2.5",
-    "typescript": "^5.7.3"
+    "react": "^19.1.0",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.29.1"
   },
   "peerDependencies": {
     "react": ">=18"