@schematichq/schematic-js 1.2.1 → 1.2.3

package/dist/schematic.cjs.js

@@ -572,6 +572,7 @@ __export(index_exports, {
   CheckFlagResponseFromJSON: () => CheckFlagResponseFromJSON,
   CheckFlagReturnFromJSON: () => CheckFlagReturnFromJSON,
   CheckFlagsResponseFromJSON: () => CheckFlagsResponseFromJSON,
+  EventBodyFlagCheckToJSON: () => EventBodyFlagCheckToJSON,
   RuleType: () => RuleType,
   Schematic: () => Schematic,
   UsagePeriod: () => UsagePeriod
@@ -646,6 +647,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"],
@@ -658,6 +660,28 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
   };
 }
 
+// src/types/api/models/EventBodyFlagCheck.ts
+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"]
+  };
+}
+
 // src/types/api/models/CheckFlagResponse.ts
 function CheckFlagResponseFromJSON(json) {
   return CheckFlagResponseFromJSONTyped(json, false);
@@ -723,6 +747,7 @@ var CheckFlagReturnFromJSON = (json) => {
     error,
     featureAllocation,
     featureUsage,
+    featureUsageEvent,
     featureUsagePeriod,
     featureUsageResetAt,
     flag,
@@ -742,6 +767,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,
@@ -771,7 +797,7 @@ function contextString(context) {
 }
 
 // src/version.ts
-var version = "1.2.1";
+var version = "1.2.3";
 
 // src/index.ts
 var anonymousIdKey = "schematicId";
@@ -781,6 +807,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 +818,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 +867,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 +886,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 +910,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 +949,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 +1031,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 +1081,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 +1100,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 +1118,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 +1141,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 +1245,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 +1259,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 +1277,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 +1297,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 +1324,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 +1372,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 +1445,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));
   };
 };