flagmint-js-sdk 2.2.2-rc.0 → 2.2.3-rc.0

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

@@ -7,8 +7,8 @@ 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, piiWireOptionsFromPayload, applyPiiHashToFlatContext, } from './piiHash';
-export type { PiiWireOptions } 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';
 export { flattenContext, flattenEvaluationContext } from './flattenContext';

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

@@ -8,6 +8,14 @@ export type PiiWireOptions = {
     piiSalt: string;
     piiValueEncoding?: typeof PII_VALUE_ENCODING | string;
 };
+/**
+ * Extra apply options. Prefer plaintext context; only set `alreadyHashed`
+ * when callers intentionally supply wire digests (do not infer from hex shape).
+ */
+export type ApplyPiiHashMode = {
+    /** When true, leave PII string fields unchanged (caller supplied digests). */
+    alreadyHashed?: boolean;
+};
 /**
  * Normalize a string before PII hashing (trim + lowercase).
  * Must match FF-EU `normalizePiiString`.
@@ -31,23 +39,95 @@ export declare function hashPiiValue(value: string, salt: string): string;
  * @param piiAttributes Keys from signed config
  */
 export declare function isPiiAttribute(attribute: string | undefined | null, piiAttributes: readonly string[]): boolean;
+/** Payload fields that carry PII wire metadata. */
+export type PiiWirePayloadFields = {
+    piiAttributes?: unknown;
+    piiSalt?: unknown;
+    piiValueEncoding?: unknown;
+};
+/**
+ * Whether a payload explicitly includes any PII wire field (vs omitting all).
+ * Used so deltas that omit PII metadata keep the previous options, while
+ * deltas that send unusable fields clear them.
+ *
+ * @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.
  *
  * @param payload Signed fullConfig / delta fields
  * @returns Options when salt + encoding are usable; otherwise null
  */
-export declare function piiWireOptionsFromPayload(payload: {
-    piiAttributes?: unknown;
-    piiSalt?: unknown;
-    piiValueEncoding?: unknown;
-} | null | undefined): PiiWireOptions | 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`.
+ *
+ * FF-EU `piiMetadata` always emits the full triple (or nothing). Merge is
+ * defensive so a salt-only / attrs-only delta cannot wipe the other fields.
+ * Explicit empty salt or unknown encoding still clears to null.
+ *
+ * @param previous Current store options
+ * @param action Delta (or similar) payload fields
+ */
+export declare function resolvePiiWireForDelta(previous: PiiWireOptions | null, action: PiiWirePayloadFields | null | undefined): PiiWireOptions | null;
 /**
  * Hash PII string fields on a flat evaluation context so they match hashed
  * rule values on the wire.
  *
+ * Always hashes plaintext strings (including values that look like 64-char hex).
+ * Pass `{ alreadyHashed: true }` only when the caller already supplied digests.
+ *
  * @param context Flat context map (after prepare / flatten)
  * @param options PII options from the rules store
+ * @param mode Optional apply mode (`alreadyHashed` skips hashing)
  * @returns New context object with PII strings hashed (or the input if no-op)
  */
-export declare function applyPiiHashToFlatContext(context: Record<string, unknown>, options: PiiWireOptions | null | undefined): Record<string, unknown>;
+export declare function applyPiiHashToFlatContext(context: Record<string, unknown>, options: PiiWireOptions | null | undefined, mode?: ApplyPiiHashMode): Record<string, unknown>;

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/cacheHelper.d.ts

@@ -8,6 +8,13 @@ export interface StorageAdapter {
 export declare function setCacheStorage(customStorage: StorageAdapter): void;
 export declare function loadCachedFlags<T>(apiKey: string, ttl: number): FeatureFlags<T> | null;
 export declare function saveCachedFlags<T>(apiKey: string, data: FeatureFlags<T>): void;
+/**
+ * Drop the evaluated-flag localCache entry for an API key.
+ * Used when config-sync is on so a prior tab’s answers cannot poison another tab.
+ *
+ * @param apiKey SDK API key used as the storage key suffix
+ */
+export declare function clearCachedFlags(apiKey: string): void;
 export declare function loadCachedContext<C>(apiKey: string): C | null;
 export declare function saveCachedContext<C>(apiKey: string, context: C): void;
 /** Config-sync rules localCache — no wall-clock TTL; lease `expiresAt` gates reuse. */

package/package.json

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