@schematichq/schematic-react 1.2.4 → 1.2.6

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:
@@ -170,6 +178,7 @@ ReactDOM.render(
 
 Offline mode automatically enables debug mode to help with troubleshooting.
 
+
 ## License
 
 MIT

package/dist/schematic-react.cjs.js

@@ -72,20 +72,20 @@ var __toESM2 = (mod, isNodeMode, target) => (target = mod != null ? __create2(__
 var require_browser_polyfill = __commonJS({
   "node_modules/cross-fetch/dist/browser-polyfill.js"(exports) {
     (function(self2) {
-      var irrelevant = function(exports2) {
+      var irrelevant = (function(exports2) {
         var g = typeof globalThis !== "undefined" && globalThis || typeof self2 !== "undefined" && self2 || // eslint-disable-next-line no-undef
         typeof global !== "undefined" && global || {};
         var support = {
           searchParams: "URLSearchParams" in g,
           iterable: "Symbol" in g && "iterator" in Symbol,
-          blob: "FileReader" in g && "Blob" in g && function() {
+          blob: "FileReader" in g && "Blob" in g && (function() {
             try {
               new Blob();
               return true;
             } catch (e) {
               return false;
             }
-          }(),
+          })(),
           formData: "FormData" in g,
           arrayBuffer: "ArrayBuffer" in g
         };
@@ -387,12 +387,12 @@ var require_browser_polyfill = __commonJS({
           }
           this.method = normalizeMethod(options.method || this.method || "GET");
           this.mode = options.mode || this.mode || null;
-          this.signal = options.signal || this.signal || function() {
+          this.signal = options.signal || this.signal || (function() {
             if ("AbortController" in g) {
               var ctrl = new AbortController();
               return ctrl.signal;
             }
-          }();
+          })();
           this.referrer = null;
           if ((this.method === "GET" || this.method === "HEAD") && body) {
             throw new TypeError("Body not allowed for GET or HEAD requests");
@@ -599,7 +599,7 @@ var require_browser_polyfill = __commonJS({
         exports2.Response = Response;
         exports2.fetch = fetch2;
         return exports2;
-      }({});
+      })({});
     })(typeof self !== "undefined" ? self : exports);
   }
 });
@@ -623,10 +623,7 @@ function rng() {
 }
 var randomUUID = typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto);
 var native_default = { randomUUID };
-function v4(options, buf, offset) {
-  if (native_default.randomUUID && !buf && !options) {
-    return native_default.randomUUID();
-  }
+function _v4(options, buf, offset) {
   options = options || {};
   const rnds = options.random ?? options.rng?.() ?? rng();
   if (rnds.length < 16) {
@@ -646,6 +643,12 @@ function v4(options, buf, offset) {
   }
   return unsafeStringify(rnds);
 }
+function v4(options, buf, offset) {
+  if (native_default.randomUUID && !buf && !options) {
+    return native_default.randomUUID();
+  }
+  return _v4(options, buf, offset);
+}
 var v4_default = v4;
 var import_polyfill = __toESM2(require_browser_polyfill());
 function CheckFlagResponseDataFromJSON(json) {
@@ -660,6 +663,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"],
@@ -749,6 +753,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -768,6 +773,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,
@@ -793,7 +799,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.2";
+var version = "1.2.6";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -804,6 +810,7 @@ var Schematic = class {
   debugEnabled = false;
   offlineEnabled = false;
   eventQueue;
+  contextDependentEventQueue;
   eventUrl = "https://c.schematichq.com";
   flagCheckListeners = {};
   flagValueListeners = {};
@@ -812,10 +819,12 @@ var Schematic = class {
   storage;
   useWebSocket = false;
   checks = {};
+  featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
+    this.contextDependentEventQueue = [];
     this.useWebSocket = options?.useWebSocket ?? false;
     this.debugEnabled = options?.debug ?? false;
     this.offlineEnabled = options?.offline ?? false;
@@ -858,6 +867,7 @@ var Schematic = class {
     if (typeof window !== "undefined" && window?.addEventListener) {
       window.addEventListener("beforeunload", () => {
         this.flushEventQueue();
+        this.flushContextDependentEventQueue();
       });
     }
     if (this.offlineEnabled) {
@@ -906,6 +916,9 @@ var Schematic = class {
         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) => {
@@ -1025,6 +1038,9 @@ var Schematic = class {
       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) {
@@ -1108,14 +1124,12 @@ var Schematic = class {
    * In offline mode, this will just set the context locally without connecting.
    */
   setContext = async (context) => {
-    if (this.isOffline()) {
+    if (this.isOffline() || !this.useWebSocket) {
       this.context = context;
+      this.flushContextDependentEventQueue();
       this.setIsPending(false);
       return Promise.resolve();
     }
-    if (!this.useWebSocket) {
-      return Promise.resolve();
-    }
     try {
       this.setIsPending(true);
       if (!this.conn) {
@@ -1131,21 +1145,123 @@ 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;
+    const { company, user, event, traits, quantity = 1 } = body;
+    if (!this.hasContext(company, user)) {
+      this.debug(`track: queuing event "${event}" until context is available`);
+      const queuedEvent = {
+        api_key: this.apiKey,
+        body: {
+          company,
+          event,
+          traits: traits ?? {},
+          user,
+          quantity
+        },
+        sent_at: (/* @__PURE__ */ new Date()).toISOString(),
+        tracker_event_id: v4_default(),
+        tracker_user_id: this.getAnonymousId(),
+        type: "track"
+      };
+      this.contextDependentEventQueue.push(queuedEvent);
+      return Promise.resolve();
+    }
     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);
+      }
+    });
+  };
   /**
    * Event processing
    */
+  hasContext = (company, user) => {
+    const hasProvidedContext = company !== void 0 && company !== null && Object.keys(company).length > 0 || user !== void 0 && user !== null && Object.keys(user).length > 0;
+    const hasInstanceContext = this.context.company !== void 0 && this.context.company !== null && Object.keys(this.context.company).length > 0 || this.context.user !== void 0 && this.context.user !== null && Object.keys(this.context.user).length > 0;
+    return hasProvidedContext || hasInstanceContext;
+  };
+  flushContextDependentEventQueue = () => {
+    this.debug(
+      `flushing ${this.contextDependentEventQueue.length} context-dependent events`
+    );
+    while (this.contextDependentEventQueue.length > 0) {
+      const event = this.contextDependentEventQueue.shift();
+      if (event) {
+        if (event.type === "track" && typeof event.body === "object" && event.body !== null) {
+          const trackBody = event.body;
+          const updatedBody = {
+            ...trackBody,
+            company: trackBody.company ?? this.context.company,
+            user: trackBody.user ?? this.context.user
+          };
+          const updatedEvent = {
+            ...event,
+            body: updatedBody,
+            sent_at: (/* @__PURE__ */ new Date()).toISOString()
+            // Update timestamp to actual send time
+          };
+          this.sendEvent(updatedEvent);
+        } else {
+          this.sendEvent(event);
+        }
+      }
+    }
+  };
   flushEventQueue = () => {
     while (this.eventQueue.length > 0) {
       const event = this.eventQueue.shift();
@@ -1175,7 +1291,7 @@ var Schematic = class {
       tracker_user_id: this.getAnonymousId(),
       type: eventType
     };
-    if (document?.hidden) {
+    if (typeof document !== "undefined" && document?.hidden) {
       return this.storeEvent(event);
     } else {
       return this.sendEvent(event);
@@ -1285,18 +1401,26 @@ var Schematic = class {
           }
           (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);
           });
+          this.flushContextDependentEventQueue();
           this.setIsPending(false);
           if (!resolved) {
             resolved = true;
@@ -1383,8 +1507,26 @@ var Schematic = class {
         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) {
@@ -1422,7 +1564,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.4";
+var version2 = "1.2.6";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.d.ts

@@ -11,6 +11,7 @@ import { Schematic } from '@schematichq/schematic-js';
 import { SchematicContext } from '@schematichq/schematic-js';
 import * as SchematicJS from '@schematichq/schematic-js';
 import { SchematicOptions } from '@schematichq/schematic-js';
+import { StoragePersister } from '@schematichq/schematic-js';
 import { Traits } from '@schematichq/schematic-js';
 import { UsagePeriod } from '@schematichq/schematic-js';
 
@@ -62,6 +63,8 @@ declare type SchematicProviderPropsWithPublishableKey = BaseSchematicProviderPro
     publishableKey: string;
 };
 
+export { StoragePersister }
+
 export { Traits }
 
 export { UsagePeriod }

package/dist/schematic-react.esm.js

@@ -27,20 +27,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var require_browser_polyfill = __commonJS({
   "node_modules/cross-fetch/dist/browser-polyfill.js"(exports) {
     (function(self2) {
-      var irrelevant = function(exports2) {
+      var irrelevant = (function(exports2) {
         var g = typeof globalThis !== "undefined" && globalThis || typeof self2 !== "undefined" && self2 || // eslint-disable-next-line no-undef
         typeof global !== "undefined" && global || {};
         var support = {
           searchParams: "URLSearchParams" in g,
           iterable: "Symbol" in g && "iterator" in Symbol,
-          blob: "FileReader" in g && "Blob" in g && function() {
+          blob: "FileReader" in g && "Blob" in g && (function() {
             try {
               new Blob();
               return true;
             } catch (e) {
               return false;
             }
-          }(),
+          })(),
           formData: "FormData" in g,
           arrayBuffer: "ArrayBuffer" in g
         };
@@ -342,12 +342,12 @@ var require_browser_polyfill = __commonJS({
           }
           this.method = normalizeMethod(options.method || this.method || "GET");
           this.mode = options.mode || this.mode || null;
-          this.signal = options.signal || this.signal || function() {
+          this.signal = options.signal || this.signal || (function() {
             if ("AbortController" in g) {
               var ctrl = new AbortController();
               return ctrl.signal;
             }
-          }();
+          })();
           this.referrer = null;
           if ((this.method === "GET" || this.method === "HEAD") && body) {
             throw new TypeError("Body not allowed for GET or HEAD requests");
@@ -554,7 +554,7 @@ var require_browser_polyfill = __commonJS({
         exports2.Response = Response;
         exports2.fetch = fetch2;
         return exports2;
-      }({});
+      })({});
     })(typeof self !== "undefined" ? self : exports);
   }
 });
@@ -578,10 +578,7 @@ function rng() {
 }
 var randomUUID = typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto);
 var native_default = { randomUUID };
-function v4(options, buf, offset) {
-  if (native_default.randomUUID && !buf && !options) {
-    return native_default.randomUUID();
-  }
+function _v4(options, buf, offset) {
   options = options || {};
   const rnds = options.random ?? options.rng?.() ?? rng();
   if (rnds.length < 16) {
@@ -601,6 +598,12 @@ function v4(options, buf, offset) {
   }
   return unsafeStringify(rnds);
 }
+function v4(options, buf, offset) {
+  if (native_default.randomUUID && !buf && !options) {
+    return native_default.randomUUID();
+  }
+  return _v4(options, buf, offset);
+}
 var v4_default = v4;
 var import_polyfill = __toESM(require_browser_polyfill());
 function CheckFlagResponseDataFromJSON(json) {
@@ -615,6 +618,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"],
@@ -704,6 +708,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -723,6 +728,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,
@@ -748,7 +754,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.2";
+var version = "1.2.6";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -759,6 +765,7 @@ var Schematic = class {
   debugEnabled = false;
   offlineEnabled = false;
   eventQueue;
+  contextDependentEventQueue;
   eventUrl = "https://c.schematichq.com";
   flagCheckListeners = {};
   flagValueListeners = {};
@@ -767,10 +774,12 @@ var Schematic = class {
   storage;
   useWebSocket = false;
   checks = {};
+  featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
+    this.contextDependentEventQueue = [];
     this.useWebSocket = options?.useWebSocket ?? false;
     this.debugEnabled = options?.debug ?? false;
     this.offlineEnabled = options?.offline ?? false;
@@ -813,6 +822,7 @@ var Schematic = class {
     if (typeof window !== "undefined" && window?.addEventListener) {
       window.addEventListener("beforeunload", () => {
         this.flushEventQueue();
+        this.flushContextDependentEventQueue();
       });
     }
     if (this.offlineEnabled) {
@@ -861,6 +871,9 @@ var Schematic = class {
         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) => {
@@ -980,6 +993,9 @@ var Schematic = class {
       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) {
@@ -1063,14 +1079,12 @@ var Schematic = class {
    * In offline mode, this will just set the context locally without connecting.
    */
   setContext = async (context) => {
-    if (this.isOffline()) {
+    if (this.isOffline() || !this.useWebSocket) {
       this.context = context;
+      this.flushContextDependentEventQueue();
       this.setIsPending(false);
       return Promise.resolve();
     }
-    if (!this.useWebSocket) {
-      return Promise.resolve();
-    }
     try {
       this.setIsPending(true);
       if (!this.conn) {
@@ -1086,21 +1100,123 @@ 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;
+    const { company, user, event, traits, quantity = 1 } = body;
+    if (!this.hasContext(company, user)) {
+      this.debug(`track: queuing event "${event}" until context is available`);
+      const queuedEvent = {
+        api_key: this.apiKey,
+        body: {
+          company,
+          event,
+          traits: traits ?? {},
+          user,
+          quantity
+        },
+        sent_at: (/* @__PURE__ */ new Date()).toISOString(),
+        tracker_event_id: v4_default(),
+        tracker_user_id: this.getAnonymousId(),
+        type: "track"
+      };
+      this.contextDependentEventQueue.push(queuedEvent);
+      return Promise.resolve();
+    }
     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);
+      }
+    });
+  };
   /**
    * Event processing
    */
+  hasContext = (company, user) => {
+    const hasProvidedContext = company !== void 0 && company !== null && Object.keys(company).length > 0 || user !== void 0 && user !== null && Object.keys(user).length > 0;
+    const hasInstanceContext = this.context.company !== void 0 && this.context.company !== null && Object.keys(this.context.company).length > 0 || this.context.user !== void 0 && this.context.user !== null && Object.keys(this.context.user).length > 0;
+    return hasProvidedContext || hasInstanceContext;
+  };
+  flushContextDependentEventQueue = () => {
+    this.debug(
+      `flushing ${this.contextDependentEventQueue.length} context-dependent events`
+    );
+    while (this.contextDependentEventQueue.length > 0) {
+      const event = this.contextDependentEventQueue.shift();
+      if (event) {
+        if (event.type === "track" && typeof event.body === "object" && event.body !== null) {
+          const trackBody = event.body;
+          const updatedBody = {
+            ...trackBody,
+            company: trackBody.company ?? this.context.company,
+            user: trackBody.user ?? this.context.user
+          };
+          const updatedEvent = {
+            ...event,
+            body: updatedBody,
+            sent_at: (/* @__PURE__ */ new Date()).toISOString()
+            // Update timestamp to actual send time
+          };
+          this.sendEvent(updatedEvent);
+        } else {
+          this.sendEvent(event);
+        }
+      }
+    }
+  };
   flushEventQueue = () => {
     while (this.eventQueue.length > 0) {
       const event = this.eventQueue.shift();
@@ -1130,7 +1246,7 @@ var Schematic = class {
       tracker_user_id: this.getAnonymousId(),
       type: eventType
     };
-    if (document?.hidden) {
+    if (typeof document !== "undefined" && document?.hidden) {
       return this.storeEvent(event);
     } else {
       return this.sendEvent(event);
@@ -1240,18 +1356,26 @@ var Schematic = class {
           }
           (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);
           });
+          this.flushContextDependentEventQueue();
           this.setIsPending(false);
           if (!resolved) {
             resolved = true;
@@ -1338,8 +1462,26 @@ var Schematic = class {
         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) {
@@ -1377,7 +1519,7 @@ var notifyFlagValueListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.2.4";
+var version2 = "1.2.6";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schematichq/schematic-react",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -25,31 +25,39 @@
     "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"
+    "test:reactnative": "jest --config jest.config.reactnative.js",
+    "tsc": "npx tsc",
+    "prepare": "husky"
   },
   "dependencies": {
-    "@schematichq/schematic-js": "^1.2.2"
+    "@schematichq/schematic-js": "^1.2.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.49.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.25.0",
+    "@eslint/js": "^9.24.0",
+    "@microsoft/api-extractor": "^7.52.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.1.1",
+    "esbuild": "^0.25.2",
     "esbuild-jest": "^0.5.0",
-    "eslint": "^8.57.1",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-react": "^7.37.4",
-    "eslint-plugin-react-hooks": "^5.1.0",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "jest-esbuild": "^0.3.0",
+    "eslint": "^9.24.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jest": "^30.0.0",
+    "jest-environment-jsdom": "^30.0.0",
+    "jest-esbuild": "^0.4.0",
     "jest-fetch-mock": "^3.0.3",
-    "prettier": "^3.4.2",
-    "react": "^19.0.0",
-    "ts-jest": "^29.2.5",
-    "typescript": "^5.7.3"
+    "prettier": "^3.6.2",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.29.1"
   },
   "peerDependencies": {
     "react": ">=18"