@schematichq/schematic-react 1.4.1 → 1.5.0

package/dist/schematic-react.esm.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
@@ -565,19 +569,16 @@ for (let i = 0; i < 256; ++i) {
 function unsafeStringify(arr, offset = 0) {
   return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
 }
-var getRandomValues;
 var rnds8 = new Uint8Array(16);
 function rng() {
-  if (!getRandomValues) {
-    if (typeof crypto === "undefined" || !crypto.getRandomValues) {
-      throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");
-    }
-    getRandomValues = crypto.getRandomValues.bind(crypto);
+  return crypto.getRandomValues(rnds8);
+}
+function v4(options, buf, offset) {
+  if (!buf && !options && crypto.randomUUID) {
+    return crypto.randomUUID();
   }
-  return getRandomValues(rnds8);
+  return _v4(options, buf, offset);
 }
-var randomUUID = typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto);
-var native_default = { randomUUID };
 function _v4(options, buf, offset) {
   options = options || {};
   const rnds = options.random ?? options.rng?.() ?? rng();
@@ -598,12 +599,6 @@ function _v4(options, buf, offset) {
   }
   return unsafeStringify(rnds);
 }
-function v4(options, buf, offset) {
-  if (native_default.randomUUID && !buf && !options) {
-    return native_default.randomUUID();
-  }
-  return _v4(options, buf, offset);
-}
 var v4_default = v4;
 var import_polyfill = __toESM(require_browser_polyfill());
 function EntitlementValueTypeFromJSON(json) {
@@ -612,6 +607,18 @@ function EntitlementValueTypeFromJSON(json) {
 function EntitlementValueTypeFromJSONTyped(json, ignoreDiscriminator) {
   return json;
 }
+function MetricPeriodMonthResetFromJSON(json) {
+  return MetricPeriodMonthResetFromJSONTyped(json, false);
+}
+function MetricPeriodMonthResetFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
+function MetricPeriodFromJSON(json) {
+  return MetricPeriodFromJSONTyped(json, false);
+}
+function MetricPeriodFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
 function FeatureEntitlementFromJSON(json) {
   return FeatureEntitlementFromJSONTyped(json, false);
 }
@@ -621,21 +628,31 @@ function FeatureEntitlementFromJSONTyped(json, ignoreDiscriminator) {
   }
   return {
     allocation: json["allocation"] == null ? void 0 : json["allocation"],
+    consumptionRate: json["consumption_rate"] == null ? void 0 : json["consumption_rate"],
     creditId: json["credit_id"] == null ? void 0 : json["credit_id"],
     creditRemaining: json["credit_remaining"] == null ? void 0 : json["credit_remaining"],
+    creditReserved: json["credit_reserved"] == null ? void 0 : json["credit_reserved"],
+    creditSettled: json["credit_settled"] == null ? void 0 : json["credit_settled"],
     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"],
+    eventSubtype: json["event_subtype"] == null ? void 0 : json["event_subtype"],
     featureId: json["feature_id"],
     featureKey: json["feature_key"],
-    metricPeriod: json["metric_period"] == null ? void 0 : json["metric_period"],
+    metricPeriod: json["metric_period"] == null ? void 0 : MetricPeriodFromJSON(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"],
+    monthReset: json["month_reset"] == null ? void 0 : MetricPeriodMonthResetFromJSON(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 RuleTypeFromJSON(json) {
+  return RuleTypeFromJSONTyped(json, false);
+}
+function RuleTypeFromJSONTyped(json, ignoreDiscriminator) {
+  return json;
+}
 function CheckFlagResponseDataFromJSON(json) {
   return CheckFlagResponseDataFromJSONTyped(json, false);
 }
@@ -650,13 +667,13 @@ function CheckFlagResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     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"],
+    featureUsagePeriod: json["feature_usage_period"] == null ? void 0 : MetricPeriodFromJSON(json["feature_usage_period"]),
     featureUsageResetAt: json["feature_usage_reset_at"] == null ? void 0 : new Date(json["feature_usage_reset_at"]),
     flag: json["flag"],
     flagId: json["flag_id"] == null ? void 0 : json["flag_id"],
     reason: json["reason"],
     ruleId: json["rule_id"] == null ? void 0 : json["rule_id"],
-    ruleType: json["rule_type"] == null ? void 0 : json["rule_type"],
+    ruleType: json["rule_type"] == null ? void 0 : RuleTypeFromJSON(json["rule_type"]),
     userId: json["user_id"] == null ? void 0 : json["user_id"],
     value: json["value"]
   };
@@ -673,6 +690,268 @@ function CheckFlagResponseFromJSONTyped(json, ignoreDiscriminator) {
     params: json["params"]
   };
 }
+var BASE_PATH = "https://api.schematichq.com".replace(/\/+$/, "");
+var Configuration = class {
+  constructor(configuration = {}) {
+    this.configuration = configuration;
+  }
+  configuration;
+  set config(configuration) {
+    this.configuration = configuration;
+  }
+  get basePath() {
+    return this.configuration.basePath != null ? this.configuration.basePath : BASE_PATH;
+  }
+  get fetchApi() {
+    return this.configuration.fetchApi;
+  }
+  get middleware() {
+    return this.configuration.middleware || [];
+  }
+  get queryParamsStringify() {
+    return this.configuration.queryParamsStringify || querystring;
+  }
+  get username() {
+    return this.configuration.username;
+  }
+  get password() {
+    return this.configuration.password;
+  }
+  get apiKey() {
+    const apiKey = this.configuration.apiKey;
+    if (apiKey) {
+      return typeof apiKey === "function" ? apiKey : () => apiKey;
+    }
+    return void 0;
+  }
+  get accessToken() {
+    const accessToken = this.configuration.accessToken;
+    if (accessToken) {
+      return typeof accessToken === "function" ? accessToken : async () => accessToken;
+    }
+    return void 0;
+  }
+  get headers() {
+    return this.configuration.headers;
+  }
+  get credentials() {
+    return this.configuration.credentials;
+  }
+};
+var DefaultConfig = new Configuration();
+var BaseAPI = class _BaseAPI {
+  constructor(configuration = DefaultConfig) {
+    this.configuration = configuration;
+    this.middleware = configuration.middleware;
+  }
+  configuration;
+  static jsonRegex = new RegExp(
+    "^(:?application/json|[^;/ 	]+/[^;/ 	]+[+]json)[ 	]*(:?;.*)?$",
+    "i"
+  );
+  middleware;
+  withMiddleware(...middlewares) {
+    const next = this.clone();
+    next.middleware = next.middleware.concat(...middlewares);
+    return next;
+  }
+  withPreMiddleware(...preMiddlewares) {
+    const middlewares = preMiddlewares.map((pre) => ({ pre }));
+    return this.withMiddleware(...middlewares);
+  }
+  withPostMiddleware(...postMiddlewares) {
+    const middlewares = postMiddlewares.map((post) => ({ post }));
+    return this.withMiddleware(...middlewares);
+  }
+  /**
+   * Check if the given MIME is a JSON MIME.
+   * JSON MIME examples:
+   *   application/json
+   *   application/json; charset=UTF8
+   *   APPLICATION/JSON
+   *   application/vnd.company+json
+   * @param mime - MIME (Multipurpose Internet Mail Extensions)
+   * @return True if the given MIME is JSON, false otherwise.
+   */
+  isJsonMime(mime) {
+    if (!mime) {
+      return false;
+    }
+    return _BaseAPI.jsonRegex.test(mime);
+  }
+  async request(context, initOverrides) {
+    const { url, init } = await this.createFetchParams(context, initOverrides);
+    const response = await this.fetchApi(url, init);
+    if (response && response.status >= 200 && response.status < 300) {
+      return response;
+    }
+    throw new ResponseError(response, "Response returned an error code");
+  }
+  async createFetchParams(context, initOverrides) {
+    let url = this.configuration.basePath + context.path;
+    if (context.query !== void 0 && Object.keys(context.query).length !== 0) {
+      url += "?" + this.configuration.queryParamsStringify(context.query);
+    }
+    const headers = Object.assign(
+      {},
+      this.configuration.headers,
+      context.headers
+    );
+    Object.keys(headers).forEach(
+      (key) => headers[key] === void 0 ? delete headers[key] : {}
+    );
+    const initOverrideFn = typeof initOverrides === "function" ? initOverrides : async () => initOverrides;
+    const initParams = {
+      method: context.method,
+      headers,
+      body: context.body,
+      credentials: this.configuration.credentials
+    };
+    const overriddenInit = {
+      ...initParams,
+      ...await initOverrideFn({
+        init: initParams,
+        context
+      })
+    };
+    let body;
+    if (isFormData(overriddenInit.body) || overriddenInit.body instanceof URLSearchParams || isBlob(overriddenInit.body)) {
+      body = overriddenInit.body;
+    } else if (this.isJsonMime(headers["Content-Type"])) {
+      body = JSON.stringify(overriddenInit.body);
+    } else {
+      body = overriddenInit.body;
+    }
+    const init = {
+      ...overriddenInit,
+      body
+    };
+    return { url, init };
+  }
+  fetchApi = async (url, init) => {
+    let fetchParams = { url, init };
+    for (const middleware of this.middleware) {
+      if (middleware.pre) {
+        fetchParams = await middleware.pre({
+          fetch: this.fetchApi,
+          ...fetchParams
+        }) || fetchParams;
+      }
+    }
+    let response = void 0;
+    try {
+      response = await (this.configuration.fetchApi || fetch)(
+        fetchParams.url,
+        fetchParams.init
+      );
+    } catch (e) {
+      for (const middleware of this.middleware) {
+        if (middleware.onError) {
+          response = await middleware.onError({
+            fetch: this.fetchApi,
+            url: fetchParams.url,
+            init: fetchParams.init,
+            error: e,
+            response: response ? response.clone() : void 0
+          }) || response;
+        }
+      }
+      if (response === void 0) {
+        if (e instanceof Error) {
+          throw new FetchError(
+            e,
+            "The request failed and the interceptors did not return an alternative response"
+          );
+        } else {
+          throw e;
+        }
+      }
+    }
+    for (const middleware of this.middleware) {
+      if (middleware.post) {
+        response = await middleware.post({
+          fetch: this.fetchApi,
+          url: fetchParams.url,
+          init: fetchParams.init,
+          response: response.clone()
+        }) || response;
+      }
+    }
+    return response;
+  };
+  /**
+   * Create a shallow clone of `this` by constructing a new instance
+   * and then shallow cloning data members.
+   */
+  clone() {
+    const constructor = this.constructor;
+    const next = new constructor(this.configuration);
+    next.middleware = this.middleware.slice();
+    return next;
+  }
+};
+function isBlob(value) {
+  return typeof Blob !== "undefined" && value instanceof Blob;
+}
+function isFormData(value) {
+  return typeof FormData !== "undefined" && value instanceof FormData;
+}
+var ResponseError = class extends Error {
+  constructor(response, msg) {
+    super(msg);
+    this.response = response;
+  }
+  response;
+  name = "ResponseError";
+};
+var FetchError = class extends Error {
+  constructor(cause, msg) {
+    super(msg);
+    this.cause = cause;
+  }
+  cause;
+  name = "FetchError";
+};
+function querystring(params, prefix = "") {
+  return Object.keys(params).map((key) => querystringSingleKey(key, params[key], prefix)).filter((part) => part.length > 0).join("&");
+}
+function querystringSingleKey(key, value, keyPrefix = "") {
+  const fullKey = keyPrefix + (keyPrefix.length ? `[${key}]` : key);
+  if (value instanceof Array) {
+    const multiValue = value.map((singleValue) => encodeURIComponent(String(singleValue))).join(`&${encodeURIComponent(fullKey)}=`);
+    return `${encodeURIComponent(fullKey)}=${multiValue}`;
+  }
+  if (value instanceof Set) {
+    const valueAsArray = Array.from(value);
+    return querystringSingleKey(key, valueAsArray, keyPrefix);
+  }
+  if (value instanceof Date) {
+    return `${encodeURIComponent(fullKey)}=${encodeURIComponent(value.toISOString())}`;
+  }
+  if (value instanceof Object) {
+    return querystring(value, fullKey);
+  }
+  return `${encodeURIComponent(fullKey)}=${encodeURIComponent(String(value))}`;
+}
+function mapValues(data, fn) {
+  return Object.keys(data).reduce(
+    (acc, key) => ({ ...acc, [key]: fn(data[key]) }),
+    {}
+  );
+}
+function CompanyCreditBalanceFromJSON(json) {
+  return CompanyCreditBalanceFromJSONTyped(json, false);
+}
+function CompanyCreditBalanceFromJSONTyped(json, ignoreDiscriminator) {
+  if (json == null) {
+    return json;
+  }
+  return {
+    remaining: json["remaining"],
+    reserved: json["reserved"],
+    settled: json["settled"]
+  };
+}
 var TrialStatus = {
   Active: "active",
   Converted: "converted",
@@ -706,6 +985,7 @@ function CheckFlagsResponseDataFromJSONTyped(json, ignoreDiscriminator) {
     return json;
   }
   return {
+    creditBalances: json["credit_balances"] == null ? void 0 : mapValues(json["credit_balances"], CompanyCreditBalanceFromJSON),
     flags: json["flags"].map(CheckFlagResponseDataFromJSON),
     plan: json["plan"] == null ? void 0 : DatastreamCompanyPlanFromJSON(json["plan"])
   };
@@ -788,7 +1068,10 @@ var CheckFlagReturnFromJSON = (json) => {
   return {
     featureUsageExceeded,
     companyId: companyId == null ? void 0 : companyId,
+    creditId: entitlement?.creditId == null ? void 0 : entitlement.creditId,
     creditRemaining: entitlement?.creditRemaining == null ? void 0 : entitlement.creditRemaining,
+    creditReserved: entitlement?.creditReserved == null ? void 0 : entitlement.creditReserved,
+    creditSettled: entitlement?.creditSettled == null ? void 0 : entitlement.creditSettled,
     error: error == null ? void 0 : error,
     featureAllocation: resolvedAllocation == null ? void 0 : resolvedAllocation,
     featureUsage: resolvedUsage == null ? void 0 : resolvedUsage,
@@ -814,6 +1097,22 @@ var CheckPlanReturnFromJSON = (json) => {
     trialStatus: trialStatus == null ? void 0 : trialStatus
   };
 };
+var CreditBalancesFromJSON = (json) => {
+  if (json == null || typeof json !== "object") {
+    return {};
+  }
+  const balances = {};
+  for (const [creditId, raw] of Object.entries(json)) {
+    if (raw == null || typeof raw !== "object") continue;
+    const { remaining, reserved, settled } = CompanyCreditBalanceFromJSON(raw);
+    if (typeof remaining !== "number" || typeof reserved !== "number" || typeof settled !== "number") {
+      continue;
+    }
+    balances[creditId] = { remaining, reserved, settled };
+  }
+  return balances;
+};
+var cacheVersion = "bb56e75d";
 function contextString(context) {
   const sortedContext = Object.keys(context).reduce((acc, key) => {
     const sortedKeys = Object.keys(
@@ -828,8 +1127,12 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.4.0";
+var version = "1.5.0";
 var anonymousIdKey = "schematicId";
+var flagStateCachePrefix = "schematicCache";
+var flagStateCacheMaxContexts = 10;
+var flagStateCacheDefaultMaxAgeMs = 7 * 24 * 60 * 60 * 1e3;
+var emptyCreditBalances = Object.freeze({});
 var Schematic = class {
   additionalHeaders = {};
   apiKey;
@@ -846,11 +1149,17 @@ var Schematic = class {
   isPending = true;
   isPendingListeners = /* @__PURE__ */ new Set();
   planListeners = /* @__PURE__ */ new Set();
+  creditBalanceListeners = /* @__PURE__ */ new Set();
   storage;
+  persistFlagState = true;
+  flagStateCacheKey;
+  flagStateCacheMaxAgeMs = flagStateCacheDefaultMaxAgeMs;
+  cachedFlagState = null;
   useWebSocket = false;
   checks = {};
   featureUsageEventMap = {};
   planChecks = {};
+  creditBalances = {};
   webSocketUrl = "wss://api.schematichq.com";
   webSocketConnectionTimeout = 1e4;
   webSocketReconnect = true;
@@ -879,11 +1188,16 @@ var Schematic = class {
   fallbackCheckCache = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
+    this.flagStateCacheKey = `${flagStateCachePrefix}:${apiKey}`;
     this.eventQueue = [];
     this.contextDependentEventQueue = [];
     this.useWebSocket = options?.useWebSocket ?? false;
     this.debugEnabled = options?.debug ?? false;
     this.offlineEnabled = options?.offline ?? false;
+    this.persistFlagState = options?.persistFlagState ?? true;
+    if (typeof options?.flagStateCacheMaxAgeMs === "number" && options.flagStateCacheMaxAgeMs > 0) {
+      this.flagStateCacheMaxAgeMs = options.flagStateCacheMaxAgeMs;
+    }
     if (typeof window !== "undefined" && typeof window.location !== "undefined") {
       const params = new URLSearchParams(window.location.search);
       const debugParam = params.get("schematic_debug");
@@ -916,6 +1230,7 @@ var Schematic = class {
       } catch {
       }
     }
+    this.hydrateFlagStateFromCache();
     if (options?.apiUrl !== void 0) {
       this.apiUrl = options.apiUrl;
     }
@@ -1209,6 +1524,29 @@ var Schematic = class {
         });
         this.notifyPlanListeners(plan);
       }
+      if (message.credit_balances !== void 0 && message.credit_balances !== null) {
+        const contextStr = contextString(context);
+        const updates = CreditBalancesFromJSON(message.credit_balances);
+        const previous = this.creditBalances[contextStr] ?? {};
+        let changed = false;
+        const merged = { ...previous };
+        for (const [creditId, next] of Object.entries(updates)) {
+          const current = previous[creditId];
+          if (current === void 0 || current.remaining !== next.remaining || current.reserved !== next.reserved || current.settled !== next.settled) {
+            merged[creditId] = next;
+            changed = true;
+          }
+        }
+        if (changed) {
+          this.creditBalances[contextStr] = merged;
+          this.debug(
+            `WebSocket credit balance update received. Notifying listeners`,
+            { creditBalances: merged }
+          );
+          this.notifyCreditBalanceListeners(merged);
+        }
+      }
+      this.persistContextToCache(contextString(context));
       this.flushContextDependentEventQueue();
       this.setIsPending(false);
     };
@@ -1316,7 +1654,32 @@ var Schematic = class {
       return;
     }
     try {
-      this.setIsPending(true);
+      const newContextStr = contextString(context);
+      const cacheHit = this.hasCachedValuesForContext(newContextStr);
+      if (cacheHit) {
+        this.debug(
+          `setContext: cache hit for context, pre-resolving from cached values`
+        );
+        this.context = context;
+        this.flushContextDependentEventQueue();
+        this.setIsPending(false);
+        const cachedChecks = this.checks[newContextStr] ?? {};
+        for (const [flagKey, check] of Object.entries(cachedChecks)) {
+          if (check === void 0) continue;
+          this.notifyFlagCheckListeners(flagKey, check);
+          this.notifyFlagValueListeners(flagKey, check.value);
+        }
+        const cachedPlan = this.planChecks[newContextStr];
+        if (cachedPlan !== void 0) {
+          this.notifyPlanListeners(cachedPlan);
+        }
+        const cachedCreditBalances = this.creditBalances[newContextStr];
+        if (cachedCreditBalances !== void 0) {
+          this.notifyCreditBalanceListeners(cachedCreditBalances);
+        }
+      } else {
+        this.setIsPending(true);
+      }
       if (!this.conn) {
         if (this.isConnecting) {
           this.debug(
@@ -1327,7 +1690,7 @@ var Schematic = class {
           }
           if (this.conn !== null) {
             const socket2 = await this.conn;
-            await this.wsSendMessage(socket2, context);
+            await this.wsSendMessage(socket2, context, cacheHit);
             return;
           }
         }
@@ -1343,7 +1706,7 @@ var Schematic = class {
           this.conn = this.wsConnect();
           const socket2 = await this.conn;
           this.isConnecting = false;
-          await this.wsSendMessage(socket2, context);
+          await this.wsSendMessage(socket2, context, cacheHit);
           return;
         } catch (error) {
           this.isConnecting = false;
@@ -1351,7 +1714,7 @@ var Schematic = class {
         }
       }
       const socket = await this.conn;
-      await this.wsSendMessage(socket, context);
+      await this.wsSendMessage(socket, context, cacheHit);
     } catch (error) {
       console.warn("Failed to establish WebSocket connection:", error);
       this.context = context;
@@ -1411,10 +1774,12 @@ var Schematic = class {
       `Optimistically updating feature usage for event: ${eventName}`,
       { quantity }
     );
+    let dirty = false;
     Object.entries(flagsForEvent).forEach(([flagKey, check]) => {
       if (check === void 0) return;
       const updatedCheck = { ...check };
       if (typeof updatedCheck.featureUsage === "number") {
+        dirty = true;
         updatedCheck.featureUsage += quantity;
         if (typeof updatedCheck.featureAllocation === "number") {
           const wasExceeded = updatedCheck.featureUsageExceeded === true;
@@ -1444,6 +1809,9 @@ var Schematic = class {
         this.notifyFlagValueListeners(flagKey, updatedCheck.value);
       }
     });
+    if (dirty) {
+      this.persistContextToCache(contextString(this.context));
+    }
   };
   /**
    * Event processing
@@ -1546,6 +1914,206 @@ var Schematic = class {
     this.storage.setItem(anonymousIdKey, generatedAnonymousId);
     return generatedAnonymousId;
   };
+  hasCachedValuesForContext = (contextStr) => {
+    const cachedChecks = this.checks[contextStr];
+    if (cachedChecks !== void 0 && Object.keys(cachedChecks).length > 0) {
+      return true;
+    }
+    if (this.planChecks[contextStr] !== void 0) {
+      return true;
+    }
+    const cachedCreditBalances = this.creditBalances[contextStr];
+    return cachedCreditBalances !== void 0 && Object.keys(cachedCreditBalances).length > 0;
+  };
+  readFlagStateCache = () => {
+    if (!this.persistFlagState || this.storage === void 0) {
+      return null;
+    }
+    let raw;
+    try {
+      raw = this.storage.getItem(this.flagStateCacheKey);
+    } catch (error) {
+      this.debug("Failed to read flag state cache:", error);
+      return null;
+    }
+    if (raw === null || raw === void 0) {
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+    } catch (error) {
+      this.debug("Flag state cache is not valid JSON, ignoring:", error);
+      return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || parsed.version !== cacheVersion || typeof parsed.contexts !== "object" || parsed.contexts === null) {
+      this.debug(
+        `Flag state cache invalid or version mismatch (expected ${cacheVersion}), ignoring`,
+        {
+          parsedType: typeof parsed,
+          version: parsed?.version
+        }
+      );
+      return null;
+    }
+    return parsed;
+  };
+  reviveCachedCheck = (raw) => {
+    if (raw === null || typeof raw !== "object") return null;
+    const obj = raw;
+    if (typeof obj.flag !== "string" || typeof obj.value !== "boolean" || typeof obj.reason !== "string") {
+      return null;
+    }
+    const revived = { ...obj };
+    if (typeof revived.featureUsageResetAt === "string") {
+      const d = new Date(revived.featureUsageResetAt);
+      revived.featureUsageResetAt = isNaN(d.getTime()) ? void 0 : d;
+    }
+    return revived;
+  };
+  reviveCachedPlan = (raw) => {
+    if (raw === null || typeof raw !== "object") return null;
+    const obj = raw;
+    if (typeof obj.id !== "string" || typeof obj.name !== "string") {
+      return null;
+    }
+    const revived = { ...obj };
+    if (typeof revived.trialEndDate === "string") {
+      const d = new Date(revived.trialEndDate);
+      revived.trialEndDate = isNaN(d.getTime()) ? void 0 : d;
+    }
+    return revived;
+  };
+  reviveCachedCreditBalances = (raw) => {
+    if (raw === null || typeof raw !== "object") return null;
+    const revived = {};
+    for (const [creditId, value] of Object.entries(
+      raw
+    )) {
+      if (value === null || typeof value !== "object") continue;
+      const obj = value;
+      if (typeof obj.remaining !== "number" || typeof obj.reserved !== "number" || typeof obj.settled !== "number") {
+        continue;
+      }
+      revived[creditId] = {
+        remaining: obj.remaining,
+        reserved: obj.reserved,
+        settled: obj.settled
+      };
+    }
+    return Object.keys(revived).length > 0 ? revived : null;
+  };
+  hydrateFlagStateFromCache = () => {
+    const parsed = this.readFlagStateCache();
+    if (parsed === null) return;
+    const cutoff = Date.now() - this.flagStateCacheMaxAgeMs;
+    const fresh = {};
+    let contextsLoaded = 0;
+    let contextsExpired = 0;
+    for (const [contextStr, entry] of Object.entries(parsed.contexts)) {
+      if (entry === null || typeof entry !== "object") continue;
+      if (typeof entry.updatedAt !== "number") continue;
+      if (entry.updatedAt < cutoff) {
+        contextsExpired += 1;
+        continue;
+      }
+      const revivedChecks = {};
+      if (entry.checks !== null && typeof entry.checks === "object") {
+        for (const [flagKey, rawCheck] of Object.entries(entry.checks)) {
+          const revived = this.reviveCachedCheck(rawCheck);
+          if (revived === null || revived.flag !== flagKey) continue;
+          revivedChecks[flagKey] = revived;
+          if (typeof revived.featureUsageEvent === "string") {
+            this.updateFeatureUsageEventMap(revived);
+          }
+        }
+        if (Object.keys(revivedChecks).length > 0) {
+          this.checks[contextStr] = revivedChecks;
+        }
+      }
+      let revivedPlan;
+      if (entry.plan !== void 0 && entry.plan !== null) {
+        const p = this.reviveCachedPlan(entry.plan);
+        if (p !== null) {
+          revivedPlan = p;
+          this.planChecks[contextStr] = p;
+        }
+      }
+      let revivedCreditBalances;
+      if (entry.creditBalances !== void 0 && entry.creditBalances !== null) {
+        const balances = this.reviveCachedCreditBalances(entry.creditBalances);
+        if (balances !== null) {
+          revivedCreditBalances = balances;
+          this.creditBalances[contextStr] = balances;
+        }
+      }
+      fresh[contextStr] = {
+        checks: revivedChecks,
+        plan: revivedPlan,
+        creditBalances: revivedCreditBalances,
+        updatedAt: entry.updatedAt
+      };
+      contextsLoaded += 1;
+    }
+    this.cachedFlagState = { version: cacheVersion, contexts: fresh };
+    this.debug(
+      `Hydrated flag state cache: ${contextsLoaded} loaded, ${contextsExpired} expired`
+    );
+  };
+  persistContextToCache = (contextStr) => {
+    const checksForContext = this.checks[contextStr];
+    const planForContext = this.planChecks[contextStr];
+    const creditBalancesForContext = this.creditBalances[contextStr];
+    if (checksForContext === void 0 && planForContext === void 0 && creditBalancesForContext === void 0) {
+      return;
+    }
+    if (this.cachedFlagState === null) {
+      this.cachedFlagState = (this.persistFlagState ? this.readFlagStateCache() : null) ?? {
+        version: cacheVersion,
+        contexts: {}
+      };
+    }
+    const cleanChecks = {};
+    if (checksForContext !== void 0) {
+      for (const [flagKey, check] of Object.entries(checksForContext)) {
+        if (check !== void 0) cleanChecks[flagKey] = check;
+      }
+    }
+    this.cachedFlagState.contexts[contextStr] = {
+      checks: cleanChecks,
+      plan: planForContext,
+      creditBalances: creditBalancesForContext,
+      updatedAt: Date.now()
+    };
+    const entries = Object.entries(this.cachedFlagState.contexts);
+    if (entries.length > flagStateCacheMaxContexts) {
+      entries.sort((a, b) => b[1].updatedAt - a[1].updatedAt);
+      const survivors = entries.slice(0, flagStateCacheMaxContexts);
+      const survivorKeys = new Set(survivors.map(([k]) => k));
+      for (const key of Object.keys(this.checks)) {
+        if (!survivorKeys.has(key)) delete this.checks[key];
+      }
+      for (const key of Object.keys(this.planChecks)) {
+        if (!survivorKeys.has(key)) delete this.planChecks[key];
+      }
+      for (const key of Object.keys(this.creditBalances)) {
+        if (!survivorKeys.has(key)) delete this.creditBalances[key];
+      }
+      this.cachedFlagState = {
+        version: cacheVersion,
+        contexts: Object.fromEntries(survivors)
+      };
+    }
+    if (!this.persistFlagState || this.storage === void 0) return;
+    try {
+      this.storage.setItem(
+        this.flagStateCacheKey,
+        JSON.stringify(this.cachedFlagState)
+      );
+    } catch (error) {
+      this.debug("Failed to write flag state cache:", error);
+    }
+  };
   handleEvent = (eventType, eventBody) => {
     const event = {
       api_key: this.apiKey,
@@ -1806,6 +2374,9 @@ var Schematic = class {
     if (this.conn !== null) {
       try {
         const socket = await this.conn;
+        if (this.currentWebSocket === socket) {
+          this.currentWebSocket = null;
+        }
         if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
           socket.close();
         }
@@ -1971,6 +2542,7 @@ var Schematic = class {
       this.debug(`Creating WebSocket connection ${connectionId} to ${wsUrl}`);
       let timeoutId = null;
       let isResolved = false;
+      let didOpen = false;
       timeoutId = setTimeout(() => {
         if (!isResolved) {
           isResolved = true;
@@ -1984,6 +2556,7 @@ var Schematic = class {
       webSocket.onopen = () => {
         if (isResolved) return;
         isResolved = true;
+        didOpen = true;
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
@@ -2009,11 +2582,12 @@ var Schematic = class {
         }
         this.debug(`WebSocket connection ${connectionId} closed`);
         this.conn = null;
+        const wasCurrent = this.currentWebSocket === webSocket;
         if (this.currentWebSocket === webSocket) {
           this.currentWebSocket = null;
           this.isConnecting = false;
         }
-        if (!isResolved && !this.wsIntentionalDisconnect && this.webSocketReconnect) {
+        if (wasCurrent && didOpen && !this.wsIntentionalDisconnect && this.webSocketReconnect) {
           this.attemptReconnect();
         }
       };
@@ -2109,6 +2683,16 @@ var Schematic = class {
     const plan = this.planChecks[contextStr];
     return plan;
   };
+  /** Get the company's lease-aware credit balances for the current context, keyed by credit ID */
+  getCreditBalances = () => {
+    const contextStr = contextString(this.context);
+    return this.creditBalances[contextStr] ?? emptyCreditBalances;
+  };
+  /** Get the company's lease-aware balance for a single credit type in the current context */
+  getCreditBalance = (creditId) => {
+    const contextStr = contextString(this.context);
+    return this.creditBalances[contextStr]?.[creditId];
+  };
   // flag checks state
   getFlagCheck = (flagKey) => {
     const contextStr = contextString(this.context);
@@ -2168,6 +2752,13 @@ var Schematic = class {
       this.planListeners.delete(listener);
     };
   };
+  /** Register an event listener that will be notified with the company's credit balances (keyed by credit ID) whenever they change */
+  addCreditBalanceListener = (listener) => {
+    this.creditBalanceListeners.add(listener);
+    return () => {
+      this.creditBalanceListeners.delete(listener);
+    };
+  };
   notifyFlagCheckListeners = (flagKey, check) => {
     const listeners = this.flagCheckListeners?.[flagKey] ?? [];
     if (listeners.size > 0) {
@@ -2231,6 +2822,17 @@ var Schematic = class {
       });
     });
   };
+  notifyCreditBalanceListeners = (value) => {
+    const listeners = this.creditBalanceListeners ?? [];
+    if (listeners.size > 0) {
+      this.debug(`Notifying ${listeners.size} credit balance listeners`, {
+        value
+      });
+    }
+    listeners.forEach(
+      (listener) => notifyCreditBalanceListener(listener, value)
+    );
+  };
 };
 var notifyPendingListener = (listener, value) => {
   if (listener.length > 0) {
@@ -2260,12 +2862,19 @@ var notifyPlanListener = (listener, value) => {
     listener();
   }
 };
+var notifyCreditBalanceListener = (listener, value) => {
+  if (listener.length > 0) {
+    listener(value);
+  } else {
+    listener();
+  }
+};
 
 // src/context/schematic.tsx
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.4.1";
+var version2 = "1.5.0";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";
@@ -2408,6 +3017,34 @@ var useSchematicPlan = (opts) => {
   }, [client, fallbackPlan]);
   return useSyncExternalStore(subscribe, getSnapshot, () => fallbackPlan);
 };
+var useSchematicCreditBalance = (creditId, opts) => {
+  const client = useSchematicClient(opts);
+  const subscribe = useCallback(
+    (callback) => client.addCreditBalanceListener(callback),
+    [client]
+  );
+  const getSnapshot = useCallback(
+    () => client.getCreditBalance(creditId),
+    [client, creditId]
+  );
+  const balance = useSyncExternalStore(subscribe, getSnapshot, () => void 0);
+  const isPendingSubscribe = useCallback(
+    (callback) => client.addIsPendingListener(callback),
+    [client]
+  );
+  const isPending = useSyncExternalStore(
+    isPendingSubscribe,
+    () => client.getIsPending(),
+    () => true
+  );
+  return useMemo2(
+    () => ({
+      balance: balance?.settled ?? 0,
+      isLoading: balance === void 0 && isPending
+    }),
+    [balance, isPending]
+  );
+};
 var useSchematicIsPending = (opts) => {
   const client = useSchematicClient(opts);
   const subscribe = useCallback(
@@ -2425,6 +3062,7 @@ export {
   UsagePeriod,
   useSchematic,
   useSchematicContext,
+  useSchematicCreditBalance,
   useSchematicEntitlement,
   useSchematicEvents,
   useSchematicFlag,