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

package/dist/sdk/core/client.d.ts

@@ -16,7 +16,8 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
      * Performs X25519 ECDH on ASL handshake and derives a session MAC key used
      * to verify signed `lease` / `fullConfig` / `delta` payloads.
      * Default false — keeps the legacy evaluated-flags stream.
-     * When true, `shareConnection` defaults to false (rules are not shared across tabs yet).
+     * When true and `shareConnection` is on, tabs share **rules** only (one SSE);
+     * each document keeps its own context and evaluates locally.
      */
     configSync?: boolean;
     /**
@@ -68,6 +69,8 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
      * leader and forward updateContext() to it. Do not enable this when two clients
      * must evaluate different contexts at the same time on one page, or when the
      * origin hosts untrusted documents that should not steer or read this stream.
+     *
+     * With `configSync`, sharing uses rules-only mode (not evaluated maps / context RPC).
      */
     shareConnection?: boolean;
     /**
@@ -133,7 +136,20 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      * @returns true when this document is a follower and should skip opening a stream.
      */
     private joinConnectionShare;
+    /**
+     * Leader: wire context RPC for evaluated share only.
+     * Rules share never forwards follower context onto the stream.
+     */
     private attachShareLeader;
+    /**
+     * Follower hooks for rules-only share: hydrate rules locally and evaluate
+     * with this document's context (never the leader's).
+     */
+    private attachRulesShareFollower;
+    /**
+     * Leader: push the right snapshot type to followers after flags/rules change.
+     */
+    private broadcastShareSnapshot;
     /**
    * Creates and initializes the transport layer used to receive feature flags
    * updates from the Flagmint platform.

package/dist/sdk/core/config-sync/index.d.ts

@@ -7,7 +7,7 @@ export type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullC
 export { performAslHandshake } from './handshake';
 export type { AslHandshakeSuccess } from './handshake';
 export { evaluateSdkFlag, evaluateAllSdkFlags, coerceType, prepareContextForEvaluator, prepareContextForLocalEval, mapToRecord, } from './evaluateSdkFlag';
-export { PII_VALUE_ENCODING, normalizePiiString, hashPiiValue, isPiiAttribute, payloadHasExplicitPiiFields, piiWireOptionsFromPayload, resolvePiiWireForDelta, applyPiiHashToFlatContext, } from './piiHash';
+export { PII_VALUE_ENCODING, normalizePiiString, hashPiiValue, isPiiAttribute, payloadHasExplicitPiiFields, hasExplicitInvalidPiiEncoding, hasMalformedPiiAttributes, payloadRequiresUsablePiiWire, isExplicitPiiRequirementCleared, piiAttributeKeysFromPayload, piiWireOptionsFromPayload, isPiiWireBroken, resolvePiiWireForDelta, applyPiiHashToFlatContext, } from './piiHash';
 export type { PiiWireOptions, ApplyPiiHashMode } from './piiHash';
 export { evaluateRule, evaluateKillSwitch, evaluateOnVariation, evaluateFlagWithTargetingRules, applyRolloutStrategy, applyPercentageRollout, applyVariantRollout, applyGradualRollout, computeCurrentPercentage, defaultHash, getContextAttribute, } from './flagEvaluator';
 export type { ExpectedFlagType, FlagEvaluationResult, Condition, TargetingRule, Rollout, Variation, Segment, EvaluationDeps, } from './flagEvaluator';

package/dist/sdk/core/config-sync/piiHash.d.ts

@@ -53,6 +53,40 @@ export type PiiWirePayloadFields = {
  * @param payload Signed fullConfig / delta fields
  */
 export declare function payloadHasExplicitPiiFields(payload: PiiWirePayloadFields | null | undefined): boolean;
+/**
+ * String attribute keys listed on a PII wire payload (ignores non-strings).
+ *
+ * @param payload Signed fullConfig / delta fields
+ */
+export declare function piiAttributeKeysFromPayload(payload: PiiWirePayloadFields | null | undefined): string[];
+/**
+ * True when `piiAttributes` is present but not a clean list of non-empty strings.
+ * e.g. `[null]`, `['']`, or a non-array — must not count as "remove all PII".
+ *
+ * @param payload Signed fullConfig / delta fields
+ */
+export declare function hasMalformedPiiAttributes(payload: PiiWirePayloadFields | null | undefined): boolean;
+/**
+ * True when `piiValueEncoding` is present but is not usable `hmac-v1`.
+ * Distinguishes omitted encoding (OK — default hmac-v1) from e.g. `123` / `hmac-v2`.
+ *
+ * @param payload Signed fullConfig / delta fields
+ */
+export declare function hasExplicitInvalidPiiEncoding(payload: PiiWirePayloadFields | null | undefined): boolean;
+/**
+ * True when the payload claims PII hashing is in play and the client must have
+ * usable salt + `hmac-v1` encoding (otherwise local eval must fail closed).
+ *
+ * @param payload Signed fullConfig / delta fields
+ */
+export declare function payloadRequiresUsablePiiWire(payload: PiiWirePayloadFields | null | undefined): boolean;
+/**
+ * True when the payload explicitly clears the PII attribute list.
+ * Only a literal empty array `[]` counts — `[null]` / `['']` are malformed, not removal.
+ *
+ * @param payload Signed fullConfig / delta fields
+ */
+export declare function isExplicitPiiRequirementCleared(payload: PiiWirePayloadFields | null | undefined): boolean;
 /**
  * Parse PII wire options from a config-sync payload body.
  *
@@ -60,6 +94,18 @@ export declare function payloadHasExplicitPiiFields(payload: PiiWirePayloadField
  * @returns Options when salt + encoding are usable; otherwise null
  */
 export declare function piiWireOptionsFromPayload(payload: PiiWirePayloadFields | null | undefined): PiiWireOptions | null;
+/**
+ * Whether resolved PII options are missing while the payload (or prior state)
+ * still requires hashing — local eval must use defaults only.
+ *
+ * Explicit `piiAttributes: []` (literal empty array) clears the requirement
+ * even if salt is empty — evaluation may proceed without hashing.
+ *
+ * @param payload Payload that was just applied (full or merged delta fields)
+ * @param resolved Result of {@link piiWireOptionsFromPayload} / delta resolve
+ * @param previousPriorHadPiiAttrs Whether the store previously had PII attribute keys
+ */
+export declare function isPiiWireBroken(payload: PiiWirePayloadFields | null | undefined, resolved: PiiWireOptions | null, previousPriorHadPiiAttrs?: boolean): boolean;
 /**
  * Resolve PII wire options for a delta: keep prior when all PII fields are
  * absent; otherwise parse after merging omitted fields from `previous`.

package/dist/sdk/core/config-sync/rulesStore.d.ts

@@ -11,6 +11,11 @@ export type RulesState = {
     needsFullConfig: boolean;
     /** PII hash options from the last fullConfig/delta (null when absent). */
     piiWire: PiiWireOptions | null;
+    /**
+     * True when hashed PII rules are expected but salt/encoding is unusable.
+     * Fail closed (defaults only) until a good fullConfig arrives.
+     */
+    piiWireBroken: boolean;
 };
 export type ApplyResult = {
     ok: true;
@@ -36,7 +41,8 @@ export declare class RulesStore {
     getMacKey(): Uint8Array | null;
     getState(): RulesState;
     /**
-     * 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?: number): boolean;
     /**

package/dist/sdk/core/config-sync/types.d.ts

@@ -79,4 +79,9 @@ export type RulesCacheSnapshot = {
     piiAttributes?: string[];
     piiSalt?: string;
     piiValueEncoding?: string;
+    /**
+     * When true, hydrate must stay fail-closed even if salt/attrs were omitted
+     * from the snapshot (broken wire with `piiWire === null`).
+     */
+    piiWireBroken?: boolean;
 };

package/dist/sdk/core/helpers/connectionShare.d.ts

@@ -8,34 +8,37 @@
  *
  * This hub elects a single **leader** per API key:
  *
- * - **Leader** holds the real transport (handshake + EventSource). It broadcasts
- *   flag snapshots and errors over {@link BroadcastChannel}.
- * - **Followers** skip handshake and EventSource. They apply the leader's flags
- *   and forward `updateContext()` to the leader, which runs it on the shared
- *   stream.
+ * - **Leader** holds the real transport (handshake + EventSource).
+ * - **Followers** skip handshake and EventSource.
  *
- * Leadership is stored in `localStorage` (`flagmint_share_lock:<apiKey>`) with a
- * short TTL and heartbeat. `destroy()` and a `pagehide` / `beforeunload` listener
- * post `bye` and release the lock so another member can take over immediately.
- * If the document is killed without those events, followers wait until the lock
- * TTL expires.
+ * Two modes (separate BroadcastChannel / lock keys so they never mix):
  *
- * Sharing is a **browser** feature. Node cluster workers each need their own
- * stream — {@link isConnectionSharingAvailable} is false there. Do not share
- * when two clients on one page must keep different evaluation contexts at the
- * same time; `/context` is per connection, so the last write wins.
+ * - **`evaluated`** (server eval, default): leader broadcasts evaluated flag
+ *   maps; followers forward `updateContext` onto the leader stream (last write
+ *   wins). Same behavior as before.
+ * - **`rules`** (config sync): leader broadcasts verified **rules snapshots**;
+ *   each tab keeps its own context and evaluates locally. Followers do **not**
+ *   forward context to the leader.
  *
- * Trust: `BroadcastChannel` and `localStorage` are same-origin. Any document
- * on this origin (including a third-party iframe you host there) can join the
- * group, POST a context through the leader's authenticated stream, and read
- * the flags broadcast back. That is expected among trusted siblings. If the
- * origin serves untrusted content, set `shareConnection: false`.
+ * Leadership is stored in `localStorage` with a short TTL and heartbeat.
+ * `destroy()` and a `pagehide` / `beforeunload` listener post `bye` and release
+ * the lock so another member can take over immediately.
+ *
+ * Trust: `BroadcastChannel` and `localStorage` are same-origin. If the origin
+ * serves untrusted content, set `shareConnection: false`.
  *
  * @module connectionShare
  */
 import type { Transport } from '../../core/transports/Transport';
+import type { RulesCacheSnapshot } from '../../core/config-sync/types';
 /** Role this document plays in the share group for a given API key. */
 export type ShareRole = 'leader' | 'follower';
+/**
+ * What the leader shares with followers.
+ * - `evaluated` — classic server-eval flag maps + context RPC
+ * - `rules` — config-sync rules snapshots; local eval per tab
+ */
+export type ConnectionShareMode = 'evaluated' | 'rules';
 /**
  * Persistence used for the leadership lock.
  * Defaults to `localStorage` so sibling iframes on the same origin can compete.
@@ -61,6 +64,11 @@ export interface ShareChannel {
  * `localStorage`, and `setInterval`.
  */
 export interface ConnectionShareOptions {
+    /**
+     * `evaluated` (default): server-eval share.
+     * `rules`: config-sync share — rules only, per-tab context.
+     */
+    mode?: ConnectionShareMode;
     /** Override `new BroadcastChannel(name)` (tests). */
     channelFactory?: (name: string) => ShareChannel;
     /** Override `localStorage` for the leadership lock (tests). */
@@ -99,11 +107,18 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     private watchId;
     private closed;
     private latestFlags;
+    private latestRules;
     private flagsWaiters;
+    private rulesWaiters;
     private flagsTimeouts;
+    private rulesTimeouts;
     private contextWaiters;
     private onPromoteCallback?;
     private leaderContextHandler?;
+    /** Rules mode: apply leader snapshot → return flags evaluated for this tab. */
+    private followerRulesApply?;
+    /** Rules mode: re-evaluate after local `updateContext` (no leader RPC). */
+    private followerLocalEval?;
     private followerFlagsCallback?;
     private followerErrorCallback?;
     private readonly now;
@@ -115,6 +130,7 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     private unloadHandler?;
     private readonly lockKey;
     private readonly channelName;
+    private readonly mode;
     /**
      * @param apiKey Share groups are keyed by API key. Distinct keys never share.
      * @param options Optional test doubles for channel, storage, and timers.
@@ -122,6 +138,8 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     constructor(apiKey: string, options?: ConnectionShareOptions);
     /** `leader` if this document holds the lock; otherwise `follower`. */
     get currentRole(): ShareRole;
+    /** `evaluated` (server eval) or `rules` (config sync). */
+    get shareMode(): ConnectionShareMode;
     /**
      * Join the share group: compete for the lock, subscribe to the channel.
      *
@@ -146,16 +164,43 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     setLeaderContextHandler(handler: (context: C, options?: {
         persist?: boolean;
     }) => Promise<Record<string, T>>): void;
+    /**
+     * 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: (payload: {
+        snapshot: RulesCacheSnapshot;
+        analytics?: Record<string, boolean>;
+    }) => Record<string, T>): void;
+    /**
+     * Rules-mode follower: re-evaluate after local `updateContext` (no RPC).
+     *
+     * @param handler Context → flag map using this tab's rules store
+     */
+    setFollowerLocalEval(handler: (context: C) => Record<string, T>): void;
     /**
      * 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: Record<string, T>): void;
+    /**
+     * 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: RulesCacheSnapshot, analytics?: Record<string, boolean>): void;
     /** Leader-only: mirror a transport `onError` (auth, quota) to followers. */
     broadcastError(error: Error): void;
     /**
-     * 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(): Transport<C, T>;
@@ -196,6 +241,12 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
      * Used by follower `init()`.
      */
     private waitForFlags;
+    /**
+     * Block until the leader has sent a `rules` snapshot, or {@link FOLLOWER_WAIT_MS}.
+     *
+     * @returns Latest rules payload from the leader
+     */
+    private waitForRules;
     /**
      * Follower `fetchFlags`: ask the leader to POST `/context` and wait for
      * `context-result`. Leaders run the handler locally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagmint-js-sdk",
-  "version": "2.2.2",
+  "version": "2.2.3-rc-2",
   "description": "Framework-agnostic JavaScript SDK for managing feature flags in Flagmint applications.",
   "author": "Flagmint Team",
   "license": "BSD 3-Clause",