@schematichq/schematic-vue 0.1.0 → 1.4.0

package/dist/schematic-vue.cjs.js

@@ -30,7 +30,8 @@ __export(index_exports, {
   useSchematicEntitlement: () => useSchematicEntitlement,
   useSchematicEvents: () => useSchematicEvents,
   useSchematicFlag: () => useSchematicFlag,
-  useSchematicIsPending: () => useSchematicIsPending
+  useSchematicIsPending: () => useSchematicIsPending,
+  useSchematicPlan: () => useSchematicPlan
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -642,6 +643,36 @@ function v4(options, buf, offset) {
 }
 var v4_default = v4;
 var import_polyfill = __toESM(require_browser_polyfill());
+function EntitlementValueTypeFromJSON(json) {
+  return EntitlementValueTypeFromJSONTyped(json, false);
+}
+function EntitlementValueTypeFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
+function FeatureEntitlementFromJSON(json) {
+  return FeatureEntitlementFromJSONTyped(json, false);
+}
+function FeatureEntitlementFromJSONTyped(json, ignoreDiscriminator) {
+  if (json == null) {
+    return json;
+  }
+  return {
+    allocation: json["allocation"] == null ? void 0 : json["allocation"],
+    creditId: json["credit_id"] == null ? void 0 : json["credit_id"],
+    creditRemaining: json["credit_remaining"] == null ? void 0 : json["credit_remaining"],
+    creditTotal: json["credit_total"] == null ? void 0 : json["credit_total"],
+    creditUsed: json["credit_used"] == null ? void 0 : json["credit_used"],
+    eventName: json["event_name"] == null ? void 0 : json["event_name"],
+    featureId: json["feature_id"],
+    featureKey: json["feature_key"],
+    metricPeriod: json["metric_period"] == null ? void 0 : json["metric_period"],
+    metricResetAt: json["metric_reset_at"] == null ? void 0 : new Date(json["metric_reset_at"]),
+    monthReset: json["month_reset"] == null ? void 0 : json["month_reset"],
+    softLimit: json["soft_limit"] == null ? void 0 : json["soft_limit"],
+    usage: json["usage"] == null ? void 0 : json["usage"],
+    valueType: EntitlementValueTypeFromJSON(json["value_type"])
+  };
+}
 function CheckFlagResponseDataFromJSON(json) {
   return CheckFlagResponseDataFromJSONTyped(json, false);
 }
@@ -651,6 +682,7 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
   }
   return {
     companyId: json["company_id"] == null ? void 0 : json["company_id"],
+    entitlement: json["entitlement"] == null ? void 0 : FeatureEntitlementFromJSON(json["entitlement"]),
     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"],
@@ -666,26 +698,6 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     value: json["value"]
   };
 }
-function EventBodyFlagCheckToJSON(json) {
-  return EventBodyFlagCheckToJSONTyped(json, false);
-}
-function EventBodyFlagCheckToJSONTyped(value, ignoreDiscriminator = false) {
-  if (value == null) {
-    return value;
-  }
-  return {
-    company_id: value["companyId"],
-    error: value["error"],
-    flag_id: value["flagId"],
-    flag_key: value["flagKey"],
-    reason: value["reason"],
-    req_company: value["reqCompany"],
-    req_user: value["reqUser"],
-    rule_id: value["ruleId"],
-    user_id: value["userId"],
-    value: value["value"]
-  };
-}
 function CheckFlagResponseFromJSON(json) {
   return CheckFlagResponseFromJSONTyped(json, false);
 }
@@ -698,6 +710,26 @@ function CheckFlagResponseFromJSONTyped(json, ignoreDiscriminator) {
     params: json["params"]
   };
 }
+function TrialStatusFromJSON(json) {
+  return TrialStatusFromJSONTyped(json, false);
+}
+function TrialStatusFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
+function DatastreamCompanyPlanFromJSON(json) {
+  return DatastreamCompanyPlanFromJSONTyped(json, false);
+}
+function DatastreamCompanyPlanFromJSONTyped(json, ignoreDiscriminator) {
+  if (json == null) {
+    return json;
+  }
+  return {
+    id: json["id"],
+    name: json["name"],
+    trialEndDate: json["trial_end_date"] == null ? void 0 : new Date(json["trial_end_date"]),
+    trialStatus: json["trial_status"] == null ? void 0 : TrialStatusFromJSON(json["trial_status"])
+  };
+}
 function CheckFlagsResponseDataFromJSON(json) {
   return CheckFlagsResponseDataFromJSONTyped(json, false);
 }
@@ -706,7 +738,8 @@ function CheckFlagsResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     return json;
   }
   return {
-    flags: json["flags"].map(CheckFlagResponseDataFromJSON)
+    flags: json["flags"].map(CheckFlagResponseDataFromJSON),
+    plan: json["plan"] == null ? void 0 : DatastreamCompanyPlanFromJSON(json["plan"])
   };
 }
 function CheckFlagsResponseFromJSON(json) {
@@ -721,6 +754,26 @@ function CheckFlagsResponseFromJSONTyped(json, ignoreDiscriminator) {
     params: json["params"]
   };
 }
+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"]
+  };
+}
 var RuleType = /* @__PURE__ */ ((RuleType2) => {
   RuleType2["GLOBAL_OVERRIDE"] = "global_override";
   RuleType2["COMPANY_OVERRIDE"] = "company_override";
@@ -741,6 +794,7 @@ var UsagePeriod = /* @__PURE__ */ ((UsagePeriod2) => {
 var CheckFlagReturnFromJSON = (json) => {
   const {
     companyId,
+    entitlement,
     error,
     featureAllocation,
     featureUsage,
@@ -758,24 +812,40 @@ var CheckFlagReturnFromJSON = (json) => {
   const featureUsageExceeded = !value && // if flag is not false, then we haven't exceeded usage
   (ruleType == "company_override_usage_exceeded" || // if the rule type is one of these, then we have exceeded usage
   ruleType == "plan_entitlement_usage_exceeded");
+  const resolvedAllocation = entitlement?.allocation ?? featureAllocation;
+  const resolvedUsage = entitlement?.usage ?? featureUsage;
+  const resolvedEvent = entitlement?.eventName ?? featureUsageEvent;
+  const resolvedPeriod = entitlement?.metricPeriod ?? featureUsagePeriod;
+  const resolvedResetAt = entitlement?.metricResetAt ?? featureUsageResetAt;
   return {
     featureUsageExceeded,
     companyId: companyId == null ? void 0 : companyId,
+    creditRemaining: entitlement?.creditRemaining == null ? void 0 : entitlement.creditRemaining,
     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,
+    featureAllocation: resolvedAllocation == null ? void 0 : resolvedAllocation,
+    featureUsage: resolvedUsage == null ? void 0 : resolvedUsage,
+    featureUsageEvent: resolvedEvent == null ? void 0 : resolvedEvent,
+    featureUsagePeriod: resolvedPeriod == null ? void 0 : resolvedPeriod,
+    featureUsageResetAt: resolvedResetAt == null ? void 0 : resolvedResetAt,
     flag,
     flagId: flagId == null ? void 0 : flagId,
     reason,
     ruleId: ruleId == null ? void 0 : ruleId,
     ruleType: ruleType == null ? void 0 : ruleType,
+    softLimit: entitlement?.softLimit == null ? void 0 : entitlement.softLimit,
     userId: userId == null ? void 0 : userId,
     value
   };
 };
+var CheckPlanReturnFromJSON = (json) => {
+  const { id, name, trialEndDate, trialStatus } = DatastreamCompanyPlanFromJSON(json);
+  return {
+    id,
+    name,
+    trialEndDate: trialEndDate == null ? void 0 : trialEndDate,
+    trialStatus: trialStatus == null ? void 0 : trialStatus
+  };
+};
 function contextString(context) {
   const sortedContext = Object.keys(context).reduce((acc, key) => {
     const sortedKeys = Object.keys(
@@ -790,7 +860,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.6";
+var version = "1.4.0";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -807,11 +877,38 @@ var Schematic = class {
   flagValueListeners = {};
   isPending = true;
   isPendingListeners = /* @__PURE__ */ new Set();
+  planListeners = /* @__PURE__ */ new Set();
   storage;
   useWebSocket = false;
   checks = {};
   featureUsageEventMap = {};
+  planChecks = {};
   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 = {};
+  fallbackCheckCache = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -843,8 +940,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;
@@ -855,11 +957,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(
@@ -869,24 +1014,89 @@ 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
-   * new connection and then returns the requestedvalue. Falls back to REST API if WebSocket
-   * connection fails.
+   * new connection and then returns the requested value. Falls back to preconfigured fallback
+   * values if WebSocket connection fails.
    * 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`;
@@ -913,15 +1123,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 {
@@ -931,38 +1141,52 @@ 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(
-          "WebSocket connection failed, falling back to REST:",
+        console.warn(
+          "WebSocket connection failed, using fallback value:",
           error
         );
-        return this.fallbackToRest(key, context, fallback);
+        const errorResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "WebSocket connection failed",
+          error instanceof Error ? error.message : String(error)
+        );
+        this.submitFlagCheckEvent(key, errorResult, context);
+        return errorResult.value;
       }
       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);
+      } else {
+        const fallbackResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "No flag values available"
+        );
+        this.submitFlagCheckEvent(key, fallbackResult, 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)
-      };
+      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;
     }
   }
   /**
@@ -974,6 +1198,53 @@ 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;
+        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(
+          `WebSocket flag update received. Notifying listeners for ${flag.flag}`,
+          {
+            flag: flag.flag,
+            value: flagCheck.value,
+            flagCheck
+          }
+        );
+        this.notifyFlagCheckListeners(flag.flag, flagCheck);
+        this.notifyFlagValueListeners(flag.flag, flagCheck.value);
+      });
+      if (message.plan !== void 0 && message.plan !== null) {
+        const plan = CheckPlanReturnFromJSON(message.plan);
+        const contextStr = contextString(context);
+        this.planChecks[contextStr] = plan;
+        this.debug(`WebSocket plan update received. Notifying listeners`, {
+          plan
+        });
+        this.notifyPlanListeners(plan);
+      }
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+    };
+  }
   /**
    * Helper function to check if client is in offline mode
    */
@@ -1000,52 +1271,6 @@ var Schematic = class {
     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, {
-        method: "POST",
-        headers: {
-          ...this.additionalHeaders ?? {},
-          "Content-Type": "application/json;charset=UTF-8",
-          "X-Schematic-Api-Key": this.apiKey
-        },
-        body: JSON.stringify(context)
-      });
-      if (!response.ok) {
-        throw new Error("Network response was not ok");
-      }
-      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.
@@ -1084,7 +1309,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 {};
     });
   };
@@ -1095,14 +1320,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);
   };
   /**
@@ -1121,16 +1344,52 @@ var Schematic = class {
       this.setIsPending(false);
       return Promise.resolve();
     }
+    if (contextString(context) === contextString(this.context) && this.conn !== null && !this.isPending) {
+      return;
+    }
     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);
-      throw error;
+      console.warn("Failed to establish WebSocket connection:", error);
+      this.context = context;
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+      this.attemptReconnect();
     }
   };
   /**
@@ -1253,11 +1512,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);
       }
     }
   };
@@ -1305,12 +1610,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();
   };
@@ -1321,6 +1661,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.
@@ -1330,95 +1794,307 @@ 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);
-        reject(error);
+        if (isResolved) return;
+        isResolved = true;
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        this.debug(`WebSocket connection ${connectionId} error:`, error);
+        const wrappedError = new Error(
+          "WebSocket connection failed during handshake"
+        );
+        reject(wrappedError);
       };
       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);
+        socket.addEventListener("close", (event) => {
+          if (!resolved) {
+            resolved = true;
+            if (event.code === 4001) {
+              reject(
+                new Error(
+                  `Authentication failed: ${event.reason !== "" ? event.reason : "Invalid API key"}`
+                )
+              );
+            } else {
+              reject(new Error("WebSocket connection closed unexpectedly"));
+            }
+          }
+        });
+        this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
           apiKey: this.apiKey,
@@ -1454,21 +2130,49 @@ var Schematic = class {
     };
   };
   setIsPending = (isPending) => {
+    if (this.isPending === isPending) return;
     this.isPending = isPending;
     this.isPendingListeners.forEach(
       (listener) => notifyPendingListener(listener, isPending)
     );
   };
+  getPlan = () => {
+    const contextStr = contextString(this.context);
+    const plan = this.planChecks[contextStr];
+    return plan;
+  };
   // flag checks state
   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) {
+      if (!(flagKey in this.fallbackCheckCache)) {
+        this.fallbackCheckCache[flagKey] = this.resolveFallbackCheckFlagReturn(
+          flagKey,
+          void 0,
+          "Default value used"
+        );
+      }
+      return this.fallbackCheckCache[flagKey];
+    }
+    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,6 +2194,12 @@ var Schematic = class {
       this.flagCheckListeners[flagKey].delete(listener);
     };
   };
+  addPlanListener = (listener) => {
+    this.planListeners.add(listener);
+    return () => {
+      this.planListeners.delete(listener);
+    };
+  };
   notifyFlagCheckListeners = (flagKey, check) => {
     const listeners = this.flagCheckListeners?.[flagKey] ?? [];
     if (listeners.size > 0) {
@@ -1526,7 +2236,32 @@ 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
+      });
+    });
+  };
+  notifyPlanListeners = (value) => {
+    const listeners = this.planListeners ?? [];
+    if (listeners.size > 0) {
+      this.debug(`Notifying ${listeners.size} plan listeners`, { value });
+    }
+    listeners.forEach((listener, index) => {
+      this.debug(`Calling listener ${index} for plan`, {
+        value
+      });
+      notifyPlanListener(listener, value);
+      this.debug(`Listener ${index} for plan completed`, {
+        value
+      });
+    });
   };
 };
 var notifyPendingListener = (listener, value) => {
@@ -1550,12 +2285,19 @@ var notifyFlagValueListener = (listener, value) => {
     listener();
   }
 };
+var notifyPlanListener = (listener, value) => {
+  if (listener.length > 0) {
+    listener(value);
+  } else {
+    listener();
+  }
+};
 
 // src/context/schematic.ts
 var import_vue = require("vue");
 
 // src/version.ts
-var version2 = "0.1.0";
+var version2 = "1.4.0";
 
 // src/context/schematic.ts
 var SchematicSymbol = Symbol("schematic");
@@ -1671,6 +2413,23 @@ var useSchematicEntitlement = (key, opts) => {
     userId: (0, import_vue2.computed)(() => flagCheck.value.userId)
   };
 };
+var useSchematicPlan = (opts) => {
+  const client = useSchematicClient(opts);
+  const fallback = opts?.fallback;
+  const plan = (0, import_vue2.ref)(
+    client.getPlan() ?? fallback
+  );
+  let unsubscribe = null;
+  (0, import_vue2.onMounted)(() => {
+    unsubscribe = client.addPlanListener((value) => {
+      plan.value = value;
+    });
+  });
+  (0, import_vue2.onScopeDispose)(() => {
+    unsubscribe?.();
+  });
+  return plan;
+};
 var useSchematicIsPending = (opts) => {
   const client = useSchematicClient(opts);
   const isPending = (0, import_vue2.ref)(client.getIsPending());