flagmint-js-sdk 2.2.2 → 2.2.3-rc-2

package/dist/flagmint.es.js

@@ -39091,7 +39091,7 @@ class SseTransport {
     this.connectPromise = new Promise((resolve, reject) => {
       this.connectResolve = resolve;
       this.connectReject = reject;
-      const sdkVersion = "2.2.2";
+      const sdkVersion = "2.2.3-rc-2";
       const platform2 = typeof window !== "undefined" ? "browser" : "nodejs";
       const wrapperName = this.configOptions?.wrapper?.name || "native-js";
       const wrapperVersion = this.configOptions?.wrapper?.version || "none";
@@ -39360,11 +39360,15 @@ class ConnectionShareHub {
     this.watchId = null;
     this.closed = false;
     this.latestFlags = null;
+    this.latestRules = null;
     this.flagsWaiters = [];
+    this.rulesWaiters = [];
     this.flagsTimeouts = [];
+    this.rulesTimeouts = [];
     this.contextWaiters = /* @__PURE__ */ new Map();
-    this.lockKey = `flagmint_share_lock:${apiKey}`;
-    this.channelName = `flagmint-share:${apiKey}`;
+    this.mode = options.mode ?? "evaluated";
+    this.lockKey = this.mode === "rules" ? `flagmint_share_rules_lock:${apiKey}` : `flagmint_share_lock:${apiKey}`;
+    this.channelName = this.mode === "rules" ? `flagmint-share-rules:${apiKey}` : `flagmint-share:${apiKey}`;
     this.now = options.now ?? (() => Date.now());
     this.storage = options.storage ?? (typeof localStorage !== "undefined" ? localStorage : null);
     this.channelFactory = options.channelFactory;
@@ -39376,6 +39380,10 @@ class ConnectionShareHub {
   get currentRole() {
     return this.role;
   }
+  /** `evaluated` (server eval) or `rules` (config sync). */
+  get shareMode() {
+    return this.mode;
+  }
   /**
    * Join the share group: compete for the lock, subscribe to the channel.
    *
@@ -39419,16 +39427,57 @@ class ConnectionShareHub {
   setLeaderContextHandler(handler) {
     this.leaderContextHandler = handler;
   }
+  /**
+   * Rules-mode follower: hydrate local rules from the leader snapshot and
+   * return flags evaluated for **this** document's context.
+   *
+   * @param handler Apply snapshot + local eval → flag map
+   */
+  setFollowerRulesApply(handler) {
+    this.followerRulesApply = handler;
+  }
+  /**
+   * Rules-mode follower: re-evaluate after local `updateContext` (no RPC).
+   *
+   * @param handler Context → flag map using this tab's rules store
+   */
+  setFollowerLocalEval(handler) {
+    this.followerLocalEval = handler;
+  }
   /**
    * Leader-only: publish the current evaluated flags to all followers.
-   * No-op on followers (avoids echo loops).
+   * No-op on followers (avoids echo loops). Evaluated mode only.
+   *
+   * @param flags Evaluated flag map from the leader stream
    */
   broadcastFlags(flags) {
+    if (this.mode !== "evaluated")
+      return;
     if (this.role !== "leader" || !this.channel)
       return;
     this.latestFlags = flags;
     this.post({ type: "flags", memberId: this.memberId, flags });
   }
+  /**
+   * Leader-only (rules mode): publish a verified rules snapshot.
+   * Followers hydrate and evaluate with their own context.
+   *
+   * @param snapshot Rules store snapshot (MAC already verified on the leader)
+   * @param analytics Optional per-flag analytics map from rules
+   */
+  broadcastRules(snapshot, analytics) {
+    if (this.mode !== "rules")
+      return;
+    if (this.role !== "leader" || !this.channel)
+      return;
+    this.latestRules = { snapshot, analytics };
+    this.post({
+      type: "rules",
+      memberId: this.memberId,
+      snapshot,
+      analytics
+    });
+  }
   /** Leader-only: mirror a transport `onError` (auth, quota) to followers. */
   broadcastError(error2) {
     if (this.role !== "leader" || !this.channel)
@@ -39442,11 +39491,34 @@ class ConnectionShareHub {
     });
   }
   /**
-   * Transport used by follower FlagClients. `init` waits for the leader
-   * snapshot; `fetchFlags` RPCs `updateContext` through the leader.
+   * Transport used by follower FlagClients.
+   * - Evaluated: `init` waits for flags; `fetchFlags` RPCs through the leader.
+   * - Rules: `init` waits for a rules snapshot; `fetchFlags` evaluates locally.
    * `destroy` is a no-op — {@link ConnectionShareHub.destroy} owns teardown.
    */
   createFollowerTransport() {
+    if (this.mode === "rules") {
+      return {
+        init: async () => {
+          const payload = await this.waitForRules();
+          const flags = this.followerRulesApply?.(payload) ?? {};
+          this.followerFlagsCallback?.(flags);
+        },
+        fetchFlags: async (context) => {
+          if (!this.followerLocalEval) {
+            throw new Error("Rules-share follower has no local eval handler.");
+          }
+          return this.followerLocalEval(context);
+        },
+        destroy: () => void 0,
+        onFlagsUpdated: (callback) => {
+          this.followerFlagsCallback = callback;
+        },
+        onError: (callback) => {
+          this.followerErrorCallback = callback;
+        }
+      };
+    }
     return {
       init: async () => {
         const flags = await this.waitForFlags();
@@ -39489,10 +39561,15 @@ class ConnectionShareHub {
       setTimeout(() => channel.close(), 0);
     }
     this.flagsWaiters = [];
+    this.rulesWaiters = [];
     this.flagsTimeouts.splice(0).forEach(({ timeoutId, reject }) => {
       clearTimeout(timeoutId);
       reject(new Error("Connection share hub closed."));
     });
+    this.rulesTimeouts.splice(0).forEach(({ timeoutId, reject }) => {
+      clearTimeout(timeoutId);
+      reject(new Error("Connection share hub closed."));
+    });
     this.contextWaiters.forEach(({ reject }) => reject(new Error("Connection share hub closed.")));
     this.contextWaiters.clear();
   }
@@ -39589,7 +39666,16 @@ class ConnectionShareHub {
       return;
     switch (message.type) {
       case "hello":
-        if (this.role === "leader" && this.latestFlags) {
+        if (this.role !== "leader")
+          break;
+        if (this.mode === "rules" && this.latestRules) {
+          this.post({
+            type: "rules",
+            memberId: this.memberId,
+            snapshot: this.latestRules.snapshot,
+            analytics: this.latestRules.analytics
+          });
+        } else if (this.mode === "evaluated" && this.latestFlags) {
           this.post({
             type: "flags",
             memberId: this.memberId,
@@ -39598,7 +39684,7 @@ class ConnectionShareHub {
         }
         break;
       case "flags":
-        if (this.role === "leader")
+        if (this.mode !== "evaluated" || this.role === "leader")
           return;
         if (!message.flags || typeof message.flags !== "object" || Array.isArray(message.flags)) {
           return;
@@ -39607,6 +39693,22 @@ class ConnectionShareHub {
         this.flagsWaiters.splice(0).forEach((resolve) => resolve(message.flags));
         this.followerFlagsCallback?.(message.flags);
         break;
+      case "rules":
+        if (this.mode !== "rules" || this.role === "leader")
+          return;
+        if (!message.snapshot || typeof message.snapshot !== "object")
+          return;
+        {
+          const payload = {
+            snapshot: message.snapshot,
+            analytics: message.analytics
+          };
+          this.latestRules = payload;
+          this.rulesWaiters.splice(0).forEach((resolve) => resolve(payload));
+          const flags = this.followerRulesApply?.(payload) ?? {};
+          this.followerFlagsCallback?.(flags);
+        }
+        break;
       case "error":
         if (this.role === "leader")
           return;
@@ -39619,7 +39721,7 @@ class ConnectionShareHub {
         }
         break;
       case "context-request":
-        if (this.role !== "leader")
+        if (this.mode !== "evaluated" || this.role !== "leader")
           return;
         void this.handleContextRequest(message);
         break;
@@ -39704,6 +39806,31 @@ class ConnectionShareHub {
       this.flagsTimeouts.push({ timeoutId, reject });
     });
   }
+  /**
+   * Block until the leader has sent a `rules` snapshot, or {@link FOLLOWER_WAIT_MS}.
+   *
+   * @returns Latest rules payload from the leader
+   */
+  waitForRules() {
+    if (this.latestRules)
+      return Promise.resolve(this.latestRules);
+    if (this.closed)
+      return Promise.reject(new Error("Connection share hub closed."));
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.rulesWaiters = this.rulesWaiters.filter((waiter) => waiter !== onRules);
+        this.rulesTimeouts = this.rulesTimeouts.filter((entry) => entry.timeoutId !== timeoutId);
+        reject(new Error("Timed out waiting for shared rules snapshot from the leader."));
+      }, FOLLOWER_WAIT_MS);
+      const onRules = (payload) => {
+        clearTimeout(timeoutId);
+        this.rulesTimeouts = this.rulesTimeouts.filter((entry) => entry.timeoutId !== timeoutId);
+        resolve(payload);
+      };
+      this.rulesWaiters.push(onRules);
+      this.rulesTimeouts.push({ timeoutId, reject });
+    });
+  }
   /**
    * Follower `fetchFlags`: ask the leader to POST `/context` and wait for
    * `context-result`. Leaders run the handler locally.
@@ -41903,22 +42030,80 @@ function payloadHasExplicitPiiFields(payload) {
     return false;
   return payload.piiSalt !== void 0 || payload.piiAttributes !== void 0 || payload.piiValueEncoding !== void 0;
 }
+function piiAttributeKeysFromPayload(payload) {
+  if (!payload || !Array.isArray(payload.piiAttributes))
+    return [];
+  return payload.piiAttributes.filter((k) => typeof k === "string" && k.length > 0);
+}
+function hasMalformedPiiAttributes(payload) {
+  if (!payload || payload.piiAttributes === void 0)
+    return false;
+  if (!Array.isArray(payload.piiAttributes))
+    return true;
+  return payload.piiAttributes.some(
+    (entry) => typeof entry !== "string" || entry.length === 0
+  );
+}
+function hasExplicitInvalidPiiEncoding(payload) {
+  if (!payload || payload.piiValueEncoding === void 0)
+    return false;
+  return payload.piiValueEncoding !== PII_VALUE_ENCODING;
+}
+function payloadRequiresUsablePiiWire(payload) {
+  if (!payload)
+    return false;
+  if (hasExplicitInvalidPiiEncoding(payload))
+    return true;
+  if (hasMalformedPiiAttributes(payload))
+    return true;
+  if (piiAttributeKeysFromPayload(payload).length > 0)
+    return true;
+  return false;
+}
+function isExplicitPiiRequirementCleared(payload) {
+  if (!payload || payload.piiAttributes === void 0)
+    return false;
+  if (!Array.isArray(payload.piiAttributes))
+    return false;
+  if (payload.piiAttributes.length !== 0)
+    return false;
+  if (hasExplicitInvalidPiiEncoding(payload))
+    return false;
+  return true;
+}
 function piiWireOptionsFromPayload(payload) {
   if (!payload)
     return null;
+  if (hasExplicitInvalidPiiEncoding(payload))
+    return null;
+  if (hasMalformedPiiAttributes(payload))
+    return null;
   const salt = typeof payload.piiSalt === "string" ? payload.piiSalt : "";
   if (!salt)
     return null;
-  const encoding = typeof payload.piiValueEncoding === "string" ? payload.piiValueEncoding : PII_VALUE_ENCODING;
-  if (encoding !== PII_VALUE_ENCODING)
-    return null;
-  const attrs = Array.isArray(payload.piiAttributes) ? payload.piiAttributes.filter((k) => typeof k === "string") : [];
+  const attrs = piiAttributeKeysFromPayload(payload);
   return {
     piiAttributes: attrs,
     piiSalt: salt,
     piiValueEncoding: PII_VALUE_ENCODING
   };
 }
+function isPiiWireBroken(payload, resolved, previousPriorHadPiiAttrs = false) {
+  if (hasExplicitInvalidPiiEncoding(payload) || hasMalformedPiiAttributes(payload)) {
+    return true;
+  }
+  if (resolved) {
+    return false;
+  }
+  if (isExplicitPiiRequirementCleared(payload))
+    return false;
+  if (payloadRequiresUsablePiiWire(payload))
+    return true;
+  if (previousPriorHadPiiAttrs && payloadHasExplicitPiiFields(payload)) {
+    return true;
+  }
+  return false;
+}
 function resolvePiiWireForDelta(previous, action) {
   if (!payloadHasExplicitPiiFields(action)) {
     return previous;
@@ -41971,7 +42156,8 @@ function createEmptyRulesState() {
     segments: /* @__PURE__ */ new Map(),
     ready: false,
     needsFullConfig: true,
-    piiWire: null
+    piiWire: null,
+    piiWireBroken: false
   };
 }
 function cloneState(state) {
@@ -41986,7 +42172,8 @@ function cloneState(state) {
       piiAttributes: [...state.piiWire.piiAttributes],
       piiSalt: state.piiWire.piiSalt,
       piiValueEncoding: state.piiWire.piiValueEncoding
-    } : null
+    } : null,
+    piiWireBroken: state.piiWireBroken
   };
 }
 function segmentsFromRecord(record) {
@@ -42013,14 +42200,18 @@ function hydrateFromFull(action) {
     if (flag?.key)
       flags.set(flag.key, flag);
   }
+  const piiWire = piiWireOptionsFromPayload(action);
+  const piiWireBroken = isPiiWireBroken(action, piiWire, false);
   return {
     version: action.version,
     expiresAt: action.expiresAt,
     flags,
     segments: segmentsFromRecord(action.segments),
-    ready: true,
-    needsFullConfig: false,
-    piiWire: piiWireOptionsFromPayload(action)
+    // Usable rules, but PII metadata must be valid when hashing is required.
+    ready: !piiWireBroken,
+    needsFullConfig: piiWireBroken,
+    piiWire,
+    piiWireBroken
   };
 }
 function applyPatch(state, action) {
@@ -42033,14 +42224,19 @@ function applyPatch(state, action) {
       flags.set(flag.key, flag);
   }
   const nextPii = resolvePiiWireForDelta(state.piiWire, action);
+  const priorHadPiiAttrs = (state.piiWire?.piiAttributes.length ?? 0) > 0 || state.piiWireBroken;
+  const computedBroken = isPiiWireBroken(action, nextPii, priorHadPiiAttrs);
+  const recoveredWithRequiredAttrs = !!nextPii && nextPii.piiAttributes.length > 0;
+  const piiWireBroken = isExplicitPiiRequirementCleared(action) ? false : recoveredWithRequiredAttrs ? false : computedBroken || state.piiWireBroken;
   return {
     version: action.toVersion,
     expiresAt: typeof action.expiresAt === "number" ? action.expiresAt : state.expiresAt,
     flags,
     segments: applySegmentUpserts(state.segments, action.segments),
-    ready: true,
-    needsFullConfig: false,
-    piiWire: nextPii
+    ready: !piiWireBroken,
+    needsFullConfig: piiWireBroken,
+    piiWire: nextPii,
+    piiWireBroken
   };
 }
 function reduceRules(state, action, now = Date.now()) {
@@ -42060,8 +42256,8 @@ function reduceRules(state, action, now = Date.now()) {
           ...cloneState(state),
           version: state.version,
           expiresAt: action.expiresAt,
-          ready: true,
-          needsFullConfig: state.flags.size === 0 || versionMismatch ? true : state.needsFullConfig
+          ready: !state.piiWireBroken,
+          needsFullConfig: state.piiWireBroken || state.flags.size === 0 || versionMismatch ? true : state.needsFullConfig
         }
       };
     }
@@ -42117,8 +42313,8 @@ function reduceRules(state, action, now = Date.now()) {
           ...current,
           version: action.toVersion,
           expiresAt: typeof action.expiresAt === "number" ? action.expiresAt : current.expiresAt,
-          ready: true,
-          needsFullConfig: false
+          ready: !current.piiWireBroken,
+          needsFullConfig: current.piiWireBroken
         }
       };
     }
@@ -42141,9 +42337,12 @@ class RulesStore {
     return this.state;
   }
   /**
-   * Fail-closed readiness: lease not expired and store marked ready.
+   * Fail-closed readiness: lease not expired, store marked ready, and PII
+   * wire metadata usable when hashing is required.
    */
   isReady(now = Date.now()) {
+    if (this.state.piiWireBroken)
+      return false;
     if (!this.state.ready)
       return false;
     if (!this.state.expiresAt)
@@ -42227,7 +42426,9 @@ class RulesStore {
         piiAttributes: [...pii.piiAttributes],
         piiSalt: pii.piiSalt,
         piiValueEncoding: pii.piiValueEncoding
-      } : {}
+      } : {},
+      // Persist fail-closed even when piiWire is null (unusable salt/encoding).
+      ...this.state.piiWireBroken ? { piiWireBroken: true } : {}
     };
   }
   hydrateFromSnapshot(snapshot, now = Date.now()) {
@@ -42237,14 +42438,17 @@ class RulesStore {
         flags.set(flag.key, flag);
     }
     const expired = isConfigPayloadExpired(snapshot.expiresAt, now);
+    const piiWire = piiWireOptionsFromPayload(snapshot);
+    const piiWireBroken = snapshot.piiWireBroken === true || isPiiWireBroken(snapshot, piiWire, false);
     this.state = {
       version: snapshot.version,
       expiresAt: snapshot.expiresAt,
       flags,
       segments: segmentsFromRecord(snapshot.segments),
-      ready: !expired && flags.size > 0,
-      needsFullConfig: expired || flags.size === 0,
-      piiWire: piiWireOptionsFromPayload(snapshot)
+      ready: !expired && flags.size > 0 && !piiWireBroken,
+      needsFullConfig: expired || flags.size === 0 || piiWireBroken,
+      piiWire,
+      piiWireBroken
     };
   }
 }
@@ -43164,11 +43368,11 @@ class FlagClient {
     this.env = options.env;
     this.enableFlagmint = options.enableFlagmint ?? true;
     this.configSync = options.configSync ?? false;
-    this.shareConnection = options.shareConnection ?? (this.configSync ? false : isConnectionSharingAvailable());
+    logger.setup({ debugLog: options.debugLog });
+    this.shareConnection = options.shareConnection ?? isConnectionSharingAvailable();
     if (this.configSync) {
       this.rulesStore = new RulesStore();
     }
-    logger.setup({ debugLog: options.debugLog });
     if (this.previewMode && this.rawFlags && Object.keys(this.rawFlags).length > 0) {
       this.flags = this.evaluateLocally(this.rawFlags, this.context);
       this.readyPromise = Promise.resolve();
@@ -43232,7 +43436,7 @@ class FlagClient {
         return;
       }
       await this.setupTransport(options);
-      this.shareHub?.broadcastFlags(this.flags);
+      this.broadcastShareSnapshot();
       this.isInitialized = true;
       this.resolveReady();
     } catch (err) {
@@ -43272,19 +43476,26 @@ class FlagClient {
    * @returns true when this document is a follower and should skip opening a stream.
    */
   async joinConnectionShare(options) {
-    if (!this.shareConnection || options.transport) {
+    if (!this.shareConnection) {
+      return false;
+    }
+    if (options.transport && !options.share) {
       return false;
     }
     if (!options.share && !isConnectionSharingAvailable()) {
       return false;
     }
-    this.shareHub = new ConnectionShareHub(this.apiKey, options.share);
+    const shareMode = this.configSync ? "rules" : "evaluated";
+    this.shareHub = new ConnectionShareHub(this.apiKey, {
+      ...options.share,
+      mode: shareMode
+    });
     this.shareHub.onPromote(async () => {
       logger.log("[FlagClient] Share leader departed. Promoting this document to hold the stream.");
       try {
         await this.setupTransport(options);
         this.attachShareLeader();
-        this.shareHub?.broadcastFlags(this.flags);
+        this.broadcastShareSnapshot();
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error(String(err));
         logger.error("[FlagClient] Promotion to share leader failed:", error2);
@@ -43293,7 +43504,12 @@ class FlagClient {
     });
     const role = await this.shareHub.join();
     if (role === "follower") {
-      logger.log("[FlagClient] Following an existing Flagmint stream in another same-origin document.");
+      logger.log(
+        shareMode === "rules" ? "[FlagClient] Following shared config-sync rules from another same-origin document." : "[FlagClient] Following an existing Flagmint stream in another same-origin document."
+      );
+      if (shareMode === "rules") {
+        this.attachRulesShareFollower();
+      }
       this.transport = this.shareHub.createFollowerTransport();
       this.bindTransport(this.transport);
       await this.transport.init();
@@ -43302,8 +43518,15 @@ class FlagClient {
     this.attachShareLeader();
     return false;
   }
+  /**
+   * Leader: wire context RPC for evaluated share only.
+   * Rules share never forwards follower context onto the stream.
+   */
   attachShareLeader() {
-    this.shareHub?.setLeaderContextHandler(async (context, options) => {
+    if (!this.shareHub || this.shareHub.shareMode === "rules") {
+      return;
+    }
+    this.shareHub.setLeaderContextHandler(async (context, options) => {
       const mergedContext = toJsonCloneable({ ...this.context, ...context });
       if (options?.persist === true) {
         this.context = mergedContext;
@@ -43312,9 +43535,6 @@ class FlagClient {
         }
       }
       if (!this.transport || typeof this.transport.fetchFlags !== "function") {
-        if (this.configSync && this.rulesStore) {
-          return this.evaluateFromRulesStore(mergedContext);
-        }
         return this.flags;
       }
       return this.transport.fetchFlags(mergedContext, {
@@ -43322,6 +43542,41 @@ class FlagClient {
       });
     });
   }
+  /**
+   * Follower hooks for rules-only share: hydrate rules locally and evaluate
+   * with this document's context (never the leader's).
+   */
+  attachRulesShareFollower() {
+    if (!this.shareHub || !this.rulesStore)
+      return;
+    this.shareHub.setFollowerRulesApply((payload) => {
+      this.rulesStore.hydrateFromSnapshot(payload.snapshot);
+      if (payload.analytics) {
+        this.updateAnalytics(payload.analytics);
+      }
+      const flags = this.evaluateFromRulesStore();
+      this.updateFlags(flags, true);
+      return flags;
+    });
+    this.shareHub.setFollowerLocalEval((context) => {
+      return this.evaluateFromRulesStore(context);
+    });
+  }
+  /**
+   * Leader: push the right snapshot type to followers after flags/rules change.
+   */
+  broadcastShareSnapshot() {
+    if (!this.shareHub || this.shareHub.currentRole !== "leader")
+      return;
+    if (this.shareHub.shareMode === "rules" && this.rulesStore) {
+      const snapshot = this.rulesStore.toSnapshot();
+      if (snapshot.flags.length === 0)
+        return;
+      this.shareHub.broadcastRules(snapshot, this.analyticsMapFromRulesStore());
+      return;
+    }
+    this.shareHub.broadcastFlags(this.flags);
+  }
   /**
   * Creates and initializes the transport layer used to receive feature flags
   * updates from the Flagmint platform.
@@ -43466,7 +43721,7 @@ class FlagClient {
     }
     this.notifySubscribers();
     if (!fromShare) {
-      this.shareHub?.broadcastFlags(newFlags);
+      this.broadcastShareSnapshot();
     }
   }
   /**