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

package/dist/flagmint.umd.js

@@ -39095,7 +39095,7 @@ var __publicField = (obj, key, value) => {
       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";
@@ -39364,11 +39364,15 @@ var __publicField = (obj, key, value) => {
       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;
@@ -39380,6 +39384,10 @@ var __publicField = (obj, key, value) => {
     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.
      *
@@ -39423,16 +39431,57 @@ var __publicField = (obj, key, value) => {
     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(error) {
       if (this.role !== "leader" || !this.channel)
@@ -39446,11 +39495,34 @@ var __publicField = (obj, key, value) => {
       });
     }
     /**
-     * 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();
@@ -39493,10 +39565,15 @@ var __publicField = (obj, key, value) => {
         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();
     }
@@ -39593,7 +39670,16 @@ var __publicField = (obj, key, value) => {
         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,
@@ -39602,7 +39688,7 @@ var __publicField = (obj, key, value) => {
           }
           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;
@@ -39611,6 +39697,22 @@ var __publicField = (obj, key, value) => {
           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;
@@ -39623,7 +39725,7 @@ var __publicField = (obj, key, value) => {
           }
           break;
         case "context-request":
-          if (this.role !== "leader")
+          if (this.mode !== "evaluated" || this.role !== "leader")
             return;
           void this.handleContextRequest(message);
           break;
@@ -39708,6 +39810,31 @@ var __publicField = (obj, key, value) => {
         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.
@@ -41907,22 +42034,80 @@ var __publicField = (obj, key, value) => {
       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;
@@ -41975,7 +42160,8 @@ var __publicField = (obj, key, value) => {
       segments: /* @__PURE__ */ new Map(),
       ready: false,
       needsFullConfig: true,
-      piiWire: null
+      piiWire: null,
+      piiWireBroken: false
     };
   }
   function cloneState(state) {
@@ -41990,7 +42176,8 @@ var __publicField = (obj, key, value) => {
         piiAttributes: [...state.piiWire.piiAttributes],
         piiSalt: state.piiWire.piiSalt,
         piiValueEncoding: state.piiWire.piiValueEncoding
-      } : null
+      } : null,
+      piiWireBroken: state.piiWireBroken
     };
   }
   function segmentsFromRecord(record) {
@@ -42017,14 +42204,18 @@ var __publicField = (obj, key, value) => {
       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) {
@@ -42037,14 +42228,19 @@ var __publicField = (obj, key, value) => {
         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()) {
@@ -42064,8 +42260,8 @@ var __publicField = (obj, key, value) => {
             ...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
           }
         };
       }
@@ -42121,8 +42317,8 @@ var __publicField = (obj, key, value) => {
             ...current,
             version: action.toVersion,
             expiresAt: typeof action.expiresAt === "number" ? action.expiresAt : current.expiresAt,
-            ready: true,
-            needsFullConfig: false
+            ready: !current.piiWireBroken,
+            needsFullConfig: current.piiWireBroken
           }
         };
       }
@@ -42145,9 +42341,12 @@ var __publicField = (obj, key, value) => {
       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)
@@ -42231,7 +42430,9 @@ var __publicField = (obj, key, value) => {
           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()) {
@@ -42241,14 +42442,17 @@ var __publicField = (obj, key, value) => {
           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
       };
     }
   }
@@ -43168,11 +43372,11 @@ var __publicField = (obj, key, value) => {
       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();
@@ -43236,7 +43440,7 @@ var __publicField = (obj, key, value) => {
           return;
         }
         await this.setupTransport(options);
-        this.shareHub?.broadcastFlags(this.flags);
+        this.broadcastShareSnapshot();
         this.isInitialized = true;
         this.resolveReady();
       } catch (err) {
@@ -43276,19 +43480,26 @@ var __publicField = (obj, key, value) => {
      * @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 error = err instanceof Error ? err : new Error(String(err));
           logger.error("[FlagClient] Promotion to share leader failed:", error);
@@ -43297,7 +43508,12 @@ var __publicField = (obj, key, value) => {
       });
       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();
@@ -43306,8 +43522,15 @@ var __publicField = (obj, key, value) => {
       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;
@@ -43316,9 +43539,6 @@ var __publicField = (obj, key, value) => {
           }
         }
         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, {
@@ -43326,6 +43546,41 @@ var __publicField = (obj, key, value) => {
         });
       });
     }
+    /**
+     * 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.
@@ -43470,7 +43725,7 @@ var __publicField = (obj, key, value) => {
       }
       this.notifySubscribers();
       if (!fromShare) {
-        this.shareHub?.broadcastFlags(newFlags);
+        this.broadcastShareSnapshot();
       }
     }
     /**