@schematichq/schematic-vue 0.1.0 → 1.2.16

package/dist/schematic-vue.esm.js

@@ -754,7 +754,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.6";
+var version = "1.2.16";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -776,6 +776,30 @@ var Schematic = class {
   checks = {};
   featureUsageEventMap = {};
   webSocketUrl = "wss://api.schematichq.com";
+  webSocketConnectionTimeout = 1e4;
+  webSocketReconnect = true;
+  webSocketMaxReconnectAttempts = 7;
+  // Max attempts after connection disrupted
+  webSocketMaxConnectionAttempts = 3;
+  // Max attempts for initial connection
+  webSocketInitialRetryDelay = 1e3;
+  webSocketMaxRetryDelay = 3e4;
+  wsReconnectAttempts = 0;
+  wsReconnectTimer = null;
+  wsIntentionalDisconnect = false;
+  currentWebSocket = null;
+  isConnecting = false;
+  maxEventQueueSize = 100;
+  // Prevent memory issues with very long network outages
+  maxEventRetries = 5;
+  // Maximum retry attempts for failed events
+  eventRetryInitialDelay = 1e3;
+  // Initial retry delay in ms
+  eventRetryMaxDelay = 3e4;
+  // Maximum retry delay in ms
+  retryTimer = null;
+  flagValueDefaults = {};
+  flagCheckDefaults = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -807,8 +831,13 @@ var Schematic = class {
     };
     if (options?.storage) {
       this.storage = options.storage;
-    } else if (typeof localStorage !== "undefined") {
-      this.storage = localStorage;
+    } else {
+      try {
+        if (typeof localStorage !== "undefined") {
+          this.storage = localStorage;
+        }
+      } catch {
+      }
     }
     if (options?.apiUrl !== void 0) {
       this.apiUrl = options.apiUrl;
@@ -819,11 +848,54 @@ var Schematic = class {
     if (options?.webSocketUrl !== void 0) {
       this.webSocketUrl = options.webSocketUrl;
     }
+    if (options?.webSocketConnectionTimeout !== void 0) {
+      this.webSocketConnectionTimeout = options.webSocketConnectionTimeout;
+    }
+    if (options?.webSocketReconnect !== void 0) {
+      this.webSocketReconnect = options.webSocketReconnect;
+    }
+    if (options?.webSocketMaxReconnectAttempts !== void 0) {
+      this.webSocketMaxReconnectAttempts = options.webSocketMaxReconnectAttempts;
+    }
+    if (options?.webSocketInitialRetryDelay !== void 0) {
+      this.webSocketInitialRetryDelay = options.webSocketInitialRetryDelay;
+    }
+    if (options?.webSocketMaxRetryDelay !== void 0) {
+      this.webSocketMaxRetryDelay = options.webSocketMaxRetryDelay;
+    }
+    if (options?.maxEventQueueSize !== void 0) {
+      this.maxEventQueueSize = options.maxEventQueueSize;
+    }
+    if (options?.maxEventRetries !== void 0) {
+      this.maxEventRetries = options.maxEventRetries;
+    }
+    if (options?.eventRetryInitialDelay !== void 0) {
+      this.eventRetryInitialDelay = options.eventRetryInitialDelay;
+    }
+    if (options?.eventRetryMaxDelay !== void 0) {
+      this.eventRetryMaxDelay = options.eventRetryMaxDelay;
+    }
+    if (options?.flagValueDefaults !== void 0) {
+      this.flagValueDefaults = options.flagValueDefaults;
+    }
+    if (options?.flagCheckDefaults !== void 0) {
+      this.flagCheckDefaults = options.flagCheckDefaults;
+    }
     if (typeof window !== "undefined" && window?.addEventListener) {
       window.addEventListener("beforeunload", () => {
         this.flushEventQueue();
         this.flushContextDependentEventQueue();
       });
+      if (this.useWebSocket) {
+        window.addEventListener("offline", () => {
+          this.debug("Browser went offline, closing WebSocket connection");
+          this.handleNetworkOffline();
+        });
+        window.addEventListener("online", () => {
+          this.debug("Browser came online, attempting to reconnect WebSocket");
+          this.handleNetworkOnline();
+        });
+      }
     }
     if (this.offlineEnabled) {
       this.debug(
@@ -833,6 +905,66 @@ var Schematic = class {
       this.debug("Initialized with debug mode enabled");
     }
   }
+  /**
+   * Resolve fallback value according to priority order:
+   * 1. Callsite fallback value (if provided)
+   * 2. Boolean value from flagCheckDefaults initialization option
+   * 3. Boolean value from flagValueDefaults initialization option
+   * 4. Default to false
+   */
+  resolveFallbackValue(key, callsiteFallback) {
+    if (callsiteFallback !== void 0) {
+      return callsiteFallback;
+    }
+    if (key in this.flagCheckDefaults) {
+      return this.flagCheckDefaults[key].value;
+    }
+    if (key in this.flagValueDefaults) {
+      return this.flagValueDefaults[key];
+    }
+    return false;
+  }
+  /**
+   * Resolve complete CheckFlagReturn object according to priority order:
+   * 1. Use callsite fallback for boolean value, construct CheckFlagReturn
+   * 2. Use flagCheckDefaults if available for this flag
+   * 3. Use flagValueDefaults if available for this flag, construct CheckFlagReturn
+   * 4. Default CheckFlagReturn with value: false
+   */
+  resolveFallbackCheckFlagReturn(key, callsiteFallback, reason = "Fallback value used", error) {
+    if (callsiteFallback !== void 0) {
+      return {
+        flag: key,
+        value: callsiteFallback,
+        reason,
+        error
+      };
+    }
+    if (key in this.flagCheckDefaults) {
+      const defaultReturn = this.flagCheckDefaults[key];
+      return {
+        ...defaultReturn,
+        flag: key,
+        // Ensure flag matches the requested key
+        reason: error !== void 0 ? reason : defaultReturn.reason,
+        error
+      };
+    }
+    if (key in this.flagValueDefaults) {
+      return {
+        flag: key,
+        value: this.flagValueDefaults[key],
+        reason,
+        error
+      };
+    }
+    return {
+      flag: key,
+      value: false,
+      reason,
+      error
+    };
+  }
   /**
    * Get value for a single flag.
    * In WebSocket mode, returns cached values if connection is active, otherwise establishes
@@ -841,16 +973,21 @@ var Schematic = class {
    * In REST mode, makes an API call for each check.
    */
   async checkFlag(options) {
-    const { fallback = false, key } = options;
+    const { fallback, key } = options;
     const context = options.context || this.context;
     const contextStr = contextString(context);
     this.debug(`checkFlag: ${key}`, { context, fallback });
     if (this.isOffline()) {
+      const resolvedFallbackResult = this.resolveFallbackCheckFlagReturn(
+        key,
+        fallback,
+        "Offline mode - using initialization defaults"
+      );
       this.debug(`checkFlag offline result: ${key}`, {
-        value: fallback,
+        value: resolvedFallbackResult.value,
         offlineMode: true
       });
-      return fallback;
+      return resolvedFallbackResult.value;
     }
     if (!this.useWebSocket) {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
@@ -877,15 +1014,15 @@ var Schematic = class {
         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)
-        };
+        console.warn("There was a problem with the fetch operation:", error);
+        const errorResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "API request failed",
+          error instanceof Error ? error.message : String(error)
+        );
         this.submitFlagCheckEvent(key, errorResult, context);
-        return fallback;
+        return errorResult.value;
       });
     }
     try {
@@ -895,12 +1032,12 @@ var Schematic = class {
         return existingVals[key].value;
       }
       if (this.isOffline()) {
-        return fallback;
+        return this.resolveFallbackValue(key, fallback);
       }
       try {
         await this.setContext(context);
       } catch (error) {
-        console.error(
+        console.warn(
           "WebSocket connection failed, falling back to REST:",
           error
         );
@@ -908,10 +1045,10 @@ var Schematic = class {
       }
       const contextVals = this.checks[contextStr] ?? {};
       const flagCheck = contextVals[key];
-      const result = flagCheck?.value ?? fallback;
+      const result = flagCheck?.value ?? this.resolveFallbackValue(key, fallback);
       this.debug(
         `checkFlag WebSocket result: ${key}`,
-        typeof flagCheck !== "undefined" ? flagCheck : { value: fallback, fallbackUsed: true }
+        typeof flagCheck !== "undefined" ? flagCheck : { value: result, fallbackUsed: true }
       );
       if (typeof flagCheck !== "undefined") {
         this.submitFlagCheckEvent(key, flagCheck, context);
@@ -919,14 +1056,14 @@ var Schematic = class {
       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)
-      };
+      const errorResult = this.resolveFallbackCheckFlagReturn(
+        key,
+        fallback,
+        "Unexpected error in flag check",
+        error instanceof Error ? error.message : String(error)
+      );
       this.submitFlagCheckEvent(key, errorResult, context);
-      return fallback;
+      return errorResult.value;
     }
   }
   /**
@@ -938,6 +1075,49 @@ var Schematic = class {
       console.log(`[Schematic] ${message}`, ...args);
     }
   }
+  /**
+   * Create a persistent message handler for websocket flag updates
+   */
+  createPersistentMessageHandler(context) {
+    return (event) => {
+      const message = JSON.parse(event.data);
+      this.debug(`WebSocket persistent message received:`, message);
+      if (!(contextString(context) in this.checks)) {
+        this.checks[contextString(context)] = {};
+      }
+      (message.flags ?? []).forEach((flag) => {
+        const flagCheck = CheckFlagReturnFromJSON(flag);
+        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) > 0 || (this.flagValueListeners[flag.flag]?.size ?? 0) > 0) {
+          this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
+        }
+        this.debug(`About to notify listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+        this.notifyFlagCheckListeners(flag.flag, flagCheck);
+        this.notifyFlagValueListeners(flag.flag, flagCheck.value);
+        this.debug(`Finished notifying listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+      });
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+    };
+  }
   /**
    * Helper function to check if client is in offline mode
    */
@@ -969,11 +1149,12 @@ var Schematic = class {
    */
   async fallbackToRest(key, context, fallback) {
     if (this.isOffline()) {
+      const resolvedFallback = this.resolveFallbackValue(key, fallback);
       this.debug(`fallbackToRest offline result: ${key}`, {
-        value: fallback,
+        value: resolvedFallback,
         offlineMode: true
       });
-      return fallback;
+      return resolvedFallback;
     }
     try {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
@@ -999,15 +1180,15 @@ var Schematic = class {
       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)
-      };
+      console.warn("REST API call failed, using fallback value:", error);
+      const errorResult = this.resolveFallbackCheckFlagReturn(
+        key,
+        fallback,
+        "API request failed (fallback)",
+        error instanceof Error ? error.message : String(error)
+      );
       this.submitFlagCheckEvent(key, errorResult, context);
-      return fallback;
+      return errorResult.value;
     }
   }
   /**
@@ -1048,7 +1229,7 @@ var Schematic = class {
         {}
       );
     }).catch((error) => {
-      console.error("There was a problem with the fetch operation:", error);
+      console.warn("There was a problem with the fetch operation:", error);
       return {};
     });
   };
@@ -1059,14 +1240,12 @@ var Schematic = class {
    */
   identify = (body) => {
     this.debug(`identify:`, body);
-    try {
-      this.setContext({
-        company: body.company?.keys,
-        user: body.keys
-      });
-    } catch (error) {
-      console.error("Error setting context:", error);
-    }
+    this.setContext({
+      company: body.company?.keys,
+      user: body.keys
+    }).catch((error) => {
+      console.warn("Error setting context:", error);
+    });
     return this.handleEvent("identify", body);
   };
   /**
@@ -1088,12 +1267,42 @@ var Schematic = class {
     try {
       this.setIsPending(true);
       if (!this.conn) {
-        this.conn = this.wsConnect();
+        if (this.isConnecting) {
+          this.debug(
+            `Connection already in progress, waiting for it to complete`
+          );
+          while (this.isConnecting && this.conn === null) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+          }
+          if (this.conn !== null) {
+            const socket2 = await this.conn;
+            await this.wsSendMessage(socket2, context);
+            return;
+          }
+        }
+        if (this.wsReconnectTimer !== null) {
+          this.debug(
+            `Cancelling scheduled reconnection, connecting immediately`
+          );
+          clearTimeout(this.wsReconnectTimer);
+          this.wsReconnectTimer = null;
+        }
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket2 = await this.conn;
+          this.isConnecting = false;
+          await this.wsSendMessage(socket2, context);
+          return;
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
+        }
       }
       const socket = await this.conn;
       await this.wsSendMessage(socket, context);
     } catch (error) {
-      console.error("Failed to establish WebSocket connection:", error);
+      console.warn("Failed to establish WebSocket connection:", error);
       throw error;
     }
   };
@@ -1217,11 +1426,57 @@ var Schematic = class {
       }
     }
   };
-  flushEventQueue = () => {
-    while (this.eventQueue.length > 0) {
-      const event = this.eventQueue.shift();
-      if (event) {
-        this.sendEvent(event);
+  startRetryTimer = () => {
+    if (this.retryTimer !== null) {
+      return;
+    }
+    this.retryTimer = setInterval(() => {
+      this.flushEventQueue().catch((error) => {
+        this.debug("Error in retry timer flush:", error);
+      });
+      if (this.eventQueue.length === 0) {
+        this.stopRetryTimer();
+      }
+    }, 5e3);
+    this.debug("Started retry timer");
+  };
+  stopRetryTimer = () => {
+    if (this.retryTimer !== null) {
+      clearInterval(this.retryTimer);
+      this.retryTimer = null;
+      this.debug("Stopped retry timer");
+    }
+  };
+  flushEventQueue = async () => {
+    if (this.eventQueue.length === 0) {
+      return;
+    }
+    const now = Date.now();
+    const readyEvents = [];
+    const notReadyEvents = [];
+    for (const event of this.eventQueue) {
+      if (event.next_retry_at === void 0 || event.next_retry_at <= now) {
+        readyEvents.push(event);
+      } else {
+        notReadyEvents.push(event);
+      }
+    }
+    if (readyEvents.length === 0) {
+      this.debug(
+        `No events ready for retry yet (${notReadyEvents.length} still in backoff)`
+      );
+      return;
+    }
+    this.debug(
+      `Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`
+    );
+    this.eventQueue = notReadyEvents;
+    for (const event of readyEvents) {
+      try {
+        await this.sendEvent(event);
+        this.debug(`Queued event sent successfully:`, event.type);
+      } catch (error) {
+        this.debug(`Failed to send queued event:`, error);
       }
     }
   };
@@ -1269,12 +1524,47 @@ var Schematic = class {
         },
         body: payload
       });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
       this.debug(`event sent:`, {
         status: response.status,
         statusText: response.statusText
       });
     } catch (error) {
-      console.error("Error sending Schematic event: ", error);
+      const retryCount = (event.retry_count ?? 0) + 1;
+      if (retryCount <= this.maxEventRetries) {
+        this.debug(
+          `Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`,
+          error
+        );
+        const baseDelay = this.eventRetryInitialDelay * Math.pow(2, retryCount - 1);
+        const jitterDelay = Math.min(baseDelay, this.eventRetryMaxDelay);
+        const nextRetryAt = Date.now() + jitterDelay;
+        const retryEvent = {
+          ...event,
+          retry_count: retryCount,
+          next_retry_at: nextRetryAt
+        };
+        if (this.eventQueue.length < this.maxEventQueueSize) {
+          this.eventQueue.push(retryEvent);
+          this.debug(
+            `Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`
+          );
+        } else {
+          this.debug(
+            `Event queue full (${this.maxEventQueueSize}), dropping oldest event`
+          );
+          this.eventQueue.shift();
+          this.eventQueue.push(retryEvent);
+        }
+        this.startRetryTimer();
+      } else {
+        this.debug(
+          `Event failed permanently after ${this.maxEventRetries} attempts, dropping:`,
+          error
+        );
+      }
     }
     return Promise.resolve();
   };
@@ -1285,6 +1575,130 @@ var Schematic = class {
   /**
    * Websocket management
    */
+  /**
+   * Force an immediate WebSocket reconnection.
+   * This is useful when the application returns from a background state (e.g., mobile app
+   * coming back to foreground) and wants to immediately re-establish the connection
+   * rather than waiting for the exponential backoff timer.
+   *
+   * This method will:
+   * - Cancel any pending reconnection timer
+   * - Reset the reconnection attempt counter
+   * - Close any existing connection
+   * - Immediately attempt to reconnect
+   * - Re-send the current context to get fresh flag values
+   *
+   * Use this when you need guaranteed fresh values (e.g., after an in-app purchase).
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.forceReconnect();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  forceReconnect = async () => {
+    return this.reconnect({ force: true });
+  };
+  /**
+   * Reconnect the WebSocket connection only if the current connection is unhealthy.
+   * This is useful when the application returns from a background state and wants to
+   * ensure a healthy connection exists, but doesn't need to force a reconnection if
+   * the connection is still active.
+   *
+   * This method will:
+   * - Check if an existing connection is healthy (readyState === OPEN)
+   * - If healthy, return immediately without reconnecting
+   * - If unhealthy, perform the same reconnection logic as forceReconnect()
+   *
+   * Use this when you want efficient reconnection that avoids unnecessary disconnects.
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect only if needed when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.reconnectIfNeeded();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  reconnectIfNeeded = async () => {
+    return this.reconnect({ force: false });
+  };
+  /**
+   * Internal method to handle reconnection logic for both forceReconnect and reconnectIfNeeded.
+   */
+  reconnect = async (options) => {
+    const { force } = options;
+    const methodName = force ? "forceReconnect" : "reconnectIfNeeded";
+    if (this.isOffline()) {
+      this.debug(`${methodName}: skipped (offline mode)`);
+      return Promise.resolve();
+    }
+    if (!force && this.conn !== null) {
+      try {
+        const existingSocket = await this.conn;
+        if (existingSocket.readyState === WebSocket.OPEN) {
+          this.debug(`${methodName}: connection is healthy, skipping`);
+          return Promise.resolve();
+        }
+      } catch {
+      }
+    }
+    this.debug(
+      `${methodName}: ${force ? "forcing immediate reconnection" : "reconnecting"}`
+    );
+    this.wsIntentionalDisconnect = false;
+    if (this.wsReconnectTimer !== null) {
+      this.debug(`${methodName}: cancelling pending reconnection timer`);
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    this.wsReconnectAttempts = 0;
+    if (this.conn !== null) {
+      this.debug(`${methodName}: closing existing connection`);
+      try {
+        const existingSocket = await this.conn;
+        if (this.currentWebSocket === existingSocket) {
+          this.currentWebSocket = null;
+        }
+        if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+          existingSocket.close();
+        }
+      } catch (error) {
+        this.debug(`${methodName}: error closing existing connection:`, error);
+      }
+      this.conn = null;
+      this.isConnecting = false;
+    }
+    if (this.context.company !== void 0 || this.context.user !== void 0) {
+      this.debug(`${methodName}: reconnecting with existing context`);
+      try {
+        this.isConnecting = true;
+        this.conn = this.wsConnect();
+        const socket = await this.conn;
+        this.isConnecting = false;
+        await this.wsSendMessage(socket, this.context, true);
+        this.debug(`${methodName}: reconnection successful`);
+      } catch (error) {
+        this.isConnecting = false;
+        this.debug(`${methodName}: reconnection failed:`, error);
+      }
+    } else {
+      this.debug(`${methodName}: no context set, skipping reconnection`);
+    }
+    return Promise.resolve();
+  };
   /**
    * If using websocket mode, close the connection when done.
    * In offline mode, this is a no-op.
@@ -1294,95 +1708,290 @@ var Schematic = class {
       this.debug("cleanup: skipped (offline mode)");
       return Promise.resolve();
     }
+    this.wsIntentionalDisconnect = true;
+    if (this.wsReconnectTimer !== null) {
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    this.stopRetryTimer();
     if (this.conn) {
       try {
         const socket = await this.conn;
+        if (this.currentWebSocket === socket) {
+          this.debug(`Cleaning up current websocket tracking`);
+          this.currentWebSocket = null;
+        }
         socket.close();
       } catch (error) {
-        console.error("Error during cleanup:", error);
+        console.warn("Error during cleanup:", error);
       } finally {
         this.conn = null;
+        this.currentWebSocket = null;
+        this.isConnecting = false;
       }
     }
   };
-  // Open a websocket connection
-  wsConnect = () => {
+  /**
+   * Calculate the delay for the next reconnection attempt using exponential backoff with jitter.
+   * This helps prevent dogpiling when the server recovers from an outage.
+   */
+  calculateReconnectDelay = () => {
+    const exponentialDelay = this.webSocketInitialRetryDelay * Math.pow(2, this.wsReconnectAttempts);
+    const cappedDelay = Math.min(exponentialDelay, this.webSocketMaxRetryDelay);
+    const jitter = Math.random() * cappedDelay * 0.5;
+    const totalDelay = cappedDelay + jitter;
+    this.debug(
+      `Reconnect delay calculated: ${totalDelay.toFixed(0)}ms (attempt ${this.wsReconnectAttempts + 1}/${this.webSocketMaxReconnectAttempts})`
+    );
+    return totalDelay;
+  };
+  /**
+   * Handle browser going offline
+   */
+  handleNetworkOffline = async () => {
+    if (this.conn !== null) {
+      try {
+        const socket = await this.conn;
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          socket.close();
+        }
+      } catch (error) {
+        this.debug("Error closing connection on offline:", error);
+      }
+      this.conn = null;
+    }
+    if (this.wsReconnectTimer !== null) {
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+  };
+  /**
+   * Handle browser coming back online
+   */
+  handleNetworkOnline = () => {
+    this.debug(
+      "Network online, attempting reconnection and flushing queued events"
+    );
+    this.wsReconnectAttempts = 0;
+    if (this.wsReconnectTimer !== null) {
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    this.flushEventQueue().catch((error) => {
+      this.debug("Error flushing event queue on network online:", error);
+    });
+    this.attemptReconnect();
+  };
+  /**
+   * Attempt to reconnect the WebSocket connection with exponential backoff.
+   * Called automatically when the connection closes unexpectedly.
+   */
+  attemptReconnect = () => {
+    if (this.wsReconnectAttempts >= this.webSocketMaxReconnectAttempts) {
+      this.debug(
+        `Maximum reconnection attempts (${this.webSocketMaxReconnectAttempts}) reached, giving up`
+      );
+      return;
+    }
+    if (this.wsReconnectTimer !== null) {
+      this.debug(
+        `Reconnection attempt already scheduled, ignoring duplicate request`
+      );
+      return;
+    }
+    const delay = this.calculateReconnectDelay();
+    this.debug(
+      `Scheduling reconnection attempt ${this.wsReconnectAttempts + 1}/${this.webSocketMaxReconnectAttempts} in ${delay.toFixed(0)}ms`
+    );
+    this.wsReconnectTimer = setTimeout(async () => {
+      this.wsReconnectTimer = null;
+      this.wsReconnectAttempts++;
+      this.debug(
+        `Attempting to reconnect (attempt ${this.wsReconnectAttempts}/${this.webSocketMaxReconnectAttempts})`
+      );
+      try {
+        if (this.conn !== null) {
+          this.debug(`Cleaning up existing connection before reconnection`);
+          try {
+            const existingSocket = await this.conn;
+            if (this.currentWebSocket === existingSocket) {
+              this.debug(`Existing websocket is current, will be replaced`);
+              this.currentWebSocket = null;
+            }
+            if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+              existingSocket.close();
+            }
+          } catch (error) {
+            this.debug(`Error cleaning up existing connection:`, error);
+          }
+          this.conn = null;
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket = await this.conn;
+          this.isConnecting = false;
+          this.debug(`Reconnection context check:`, {
+            hasCompany: this.context.company !== void 0,
+            hasUser: this.context.user !== void 0,
+            context: this.context
+          });
+          if (this.context.company !== void 0 || this.context.user !== void 0) {
+            this.debug(`Reconnected, force re-sending context`);
+            await this.wsSendMessage(socket, this.context, true);
+          } else {
+            this.debug(
+              `No context to re-send after reconnection - websocket ready for new context`
+            );
+            this.debug(
+              `Setting up tracking for reconnected websocket (no context to send)`
+            );
+            this.currentWebSocket = socket;
+          }
+          this.flushEventQueue().catch((error) => {
+            this.debug(
+              "Error flushing event queue after websocket reconnection:",
+              error
+            );
+          });
+          this.debug(`Reconnection successful`);
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
+        }
+      } catch (error) {
+        this.debug(`Reconnection attempt failed:`, error);
+      }
+    }, delay);
+  };
+  // Open a websocket connection with retry logic for timeouts
+  wsConnect = async () => {
     if (this.isOffline()) {
       this.debug("wsConnect: skipped (offline mode)");
-      return Promise.reject(
-        new Error("WebSocket connection skipped in offline mode")
-      );
+      throw new Error("WebSocket connection skipped in offline mode");
     }
+    let lastError = null;
+    const maxAttempts = this.webSocketMaxConnectionAttempts;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        const socket = await this.wsConnectOnce();
+        this.wsReconnectAttempts = 0;
+        return socket;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        const isTimeout = lastError.message === "WebSocket connection timeout";
+        if (!isTimeout) {
+          this.debug(
+            `WebSocket connection failed with non-timeout error, not retrying:`,
+            lastError.message
+          );
+          throw lastError;
+        }
+        if (attempt < maxAttempts - 1) {
+          const baseDelay = this.webSocketInitialRetryDelay * Math.pow(2, attempt);
+          const cappedDelay = Math.min(baseDelay, this.webSocketMaxRetryDelay);
+          const jitter = cappedDelay * 0.2 * Math.random();
+          const delay = cappedDelay + jitter;
+          this.debug(
+            `WebSocket connection timeout (attempt ${attempt + 1}/${maxAttempts}), retrying in ${delay.toFixed(0)}ms`
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        } else {
+          this.debug(
+            `WebSocket connection timeout (attempt ${attempt + 1}/${maxAttempts}), no more retries`
+          );
+        }
+      }
+    }
+    throw lastError ?? new Error("WebSocket connection failed");
+  };
+  // Single attempt to open a websocket connection (no retry logic)
+  wsConnectOnce = () => {
     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);
+      const connectionId = Math.random().toString(36).substring(7);
+      this.debug(`Creating WebSocket connection ${connectionId} to ${wsUrl}`);
+      let timeoutId = null;
+      let isResolved = false;
+      timeoutId = setTimeout(() => {
+        if (!isResolved) {
+          isResolved = true;
+          this.debug(
+            `WebSocket connection timeout after ${this.webSocketConnectionTimeout}ms`
+          );
+          webSocket.close();
+          reject(new Error("WebSocket connection timeout"));
+        }
+      }, this.webSocketConnectionTimeout);
       webSocket.onopen = () => {
-        this.debug(`WebSocket connection opened`);
+        if (isResolved) return;
+        isResolved = true;
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        this.wsIntentionalDisconnect = false;
+        this.debug(`WebSocket connection ${connectionId} opened successfully`);
         resolve(webSocket);
       };
       webSocket.onerror = (error) => {
-        this.debug(`WebSocket connection error:`, error);
+        if (isResolved) return;
+        isResolved = true;
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        this.debug(`WebSocket connection ${connectionId} error:`, error);
         reject(error);
       };
       webSocket.onclose = () => {
-        this.debug(`WebSocket connection closed`);
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        this.debug(`WebSocket connection ${connectionId} closed`);
         this.conn = null;
+        if (this.currentWebSocket === webSocket) {
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
+        if (!isResolved && !this.wsIntentionalDisconnect && this.webSocketReconnect) {
+          this.attemptReconnect();
+        }
       };
     });
   };
   // 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) => {
+  wsSendMessage = (socket, context, forceContextSend = false) => {
     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)) {
+      if (!forceContextSend && contextString(context) == contextString(this.context)) {
         this.debug(`WebSocket context unchanged, skipping update`);
         return resolve(this.setIsPending(false));
       }
-      this.debug(`WebSocket context updated:`, context);
+      this.debug(
+        forceContextSend ? `WebSocket force sending context (reconnection):` : `WebSocket context updated:`,
+        context
+      );
       this.context = context;
       const sendMessage = () => {
         let resolved = false;
+        const persistentMessageHandler = this.createPersistentMessageHandler(context);
         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);
-            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);
+          persistentMessageHandler(event);
           if (!resolved) {
             resolved = true;
             resolve();
           }
         };
         socket.addEventListener("message", messageHandler);
+        this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
           apiKey: this.apiKey,
@@ -1427,12 +2036,31 @@ var Schematic = class {
   getFlagCheck = (flagKey) => {
     const contextStr = contextString(this.context);
     const checks = this.checks[contextStr] ?? {};
-    return checks[flagKey];
+    const check = checks[flagKey];
+    if (check !== void 0) {
+      return check;
+    }
+    if (flagKey in this.flagCheckDefaults || flagKey in this.flagValueDefaults) {
+      return this.resolveFallbackCheckFlagReturn(
+        flagKey,
+        void 0,
+        "Default value used"
+      );
+    }
+    return void 0;
   };
   // flagValues state
   getFlagValue = (flagKey) => {
-    const check = this.getFlagCheck(flagKey);
-    return check?.value;
+    const contextStr = contextString(this.context);
+    const checks = this.checks[contextStr] ?? {};
+    const check = checks[flagKey];
+    if (check?.value !== void 0) {
+      return check.value;
+    }
+    if (flagKey in this.flagCheckDefaults || flagKey in this.flagValueDefaults) {
+      return this.resolveFallbackValue(flagKey);
+    }
+    return void 0;
   };
   /** Register an event listener that will be notified with the boolean value for a given flag when this value changes */
   addFlagValueListener = (flagKey, listener) => {
@@ -1490,7 +2118,17 @@ var Schematic = class {
         { value }
       );
     }
-    listeners.forEach((listener) => notifyFlagValueListener(listener, value));
+    listeners.forEach((listener, index) => {
+      this.debug(`Calling listener ${index} for flag ${flagKey}`, {
+        flagKey,
+        value
+      });
+      notifyFlagValueListener(listener, value);
+      this.debug(`Listener ${index} for flag ${flagKey} completed`, {
+        flagKey,
+        value
+      });
+    });
   };
 };
 var notifyPendingListener = (listener, value) => {
@@ -1519,7 +2157,7 @@ var notifyFlagValueListener = (listener, value) => {
 import { inject, onScopeDispose } from "vue";
 
 // src/version.ts
-var version2 = "0.1.0";
+var version2 = "1.2.16";
 
 // src/context/schematic.ts
 var SchematicSymbol = Symbol("schematic");