@schematichq/schematic-react 1.2.4 → 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:
@@ -170,6 +178,7 @@ ReactDOM.render(
 
 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"],
@@ -749,6 +750,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -768,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,
@@ -793,7 +796,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.2";
+var version = "1.2.3";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -812,6 +815,7 @@ var Schematic = class {
   storage;
   useWebSocket = false;
   checks = {};
+  featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
   constructor(apiKey, options) {
     this.apiKey = apiKey;
@@ -906,6 +910,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 +1032,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 +1118,11 @@ 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.setIsPending(false);
       return Promise.resolve();
     }
-    if (!this.useWebSocket) {
-      return Promise.resolve();
-    }
     try {
       this.setIsPending(true);
       if (!this.conn) {
@@ -1131,18 +1138,69 @@ 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;
     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
    */
@@ -1285,12 +1343,19 @@ 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);
             }
@@ -1383,8 +1448,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 +1505,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.4";
+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"],
@@ -704,6 +705,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -723,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,
@@ -748,7 +751,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.2";
+var version = "1.2.3";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -767,6 +770,7 @@ var Schematic = class {
   storage;
   useWebSocket = false;
   checks = {};
+  featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
   constructor(apiKey, options) {
     this.apiKey = apiKey;
@@ -861,6 +865,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 +987,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 +1073,11 @@ 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.setIsPending(false);
       return Promise.resolve();
     }
-    if (!this.useWebSocket) {
-      return Promise.resolve();
-    }
     try {
       this.setIsPending(true);
       if (!this.conn) {
@@ -1086,18 +1093,69 @@ 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;
     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
    */
@@ -1240,12 +1298,19 @@ 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);
             }
@@ -1338,8 +1403,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 +1460,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.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.4",
+  "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.2"
+    "@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.25.0",
+    "@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"