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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { FlagClient } from './sdk/core/client';
 export type { FlagClientOptions } from './sdk/core/client';
 export type { CacheAdapter, FeatureFlags } from './sdk/core/helpers/types';
+export type { ApplicationEvent, ApplicationEventKind } from './sdk/core/helpers/applicationEvents';
 export * as syncCache from './sdk/core/helpers/cacheHelper';
 export * as asyncCache from './sdk/core/helpers/cacheHelper.async';
 export type { Transport } from './sdk/core/transports/Transport';
@@ -11,3 +12,5 @@ export { evaluateFlagValue } from './sdk/core/evaluation/evaluateFlagValue';
 export { evaluateRollout } from './sdk/core/evaluation/evaluateRollout';
 export { isInSegment } from './sdk/core/evaluation/isInSegment';
 export * from './sdk/core/evaluation/rolloutUtils';
+export { RulesStore, createEmptyRulesState, reduceRules, performAslHandshake, generateAslClientKeyPair, deriveAslMacKey, signConfigPayload, verifyConfigPayloadSignature, canonicalizeForSigning, isConfigPayloadExpired, evaluateSdkFlag, evaluateAllSdkFlags, coerceType, evaluateRule, evaluateFlagWithTargetingRules, applyRolloutStrategy, computeCurrentPercentage, defaultHash, flattenEvaluationContext, prepareContextForLocalEval, hashPiiValue, applyPiiHashToFlatContext, stringHash, hashPercent, } from './sdk/core/config-sync';
+export type { SdkFlagConfig, SdkSegment, RulesState, RulesCacheSnapshot, ConfigSyncPayload, LeasePayload, FullConfigPayload, DeltaConfigPayload, DeltasCatchUpPayload, ApplyResult, AslHandshakeSuccess, PiiWireOptions, } from './sdk/core/config-sync';

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

@@ -1,6 +1,8 @@
 import { CacheAdapter, FeatureFlags } from '../core/helpers/types';
 import type { Transport } from '../core/transports/Transport';
 import { FlagValue } from '../core/evaluation/types';
+import { type ConnectionShareOptions } from '../core/helpers/connectionShare';
+import { RulesStore } from '../core/config-sync';
 type TransportMode = 'auto' | 'long-polling' | 'sse';
 export interface FlagClientOptions<C extends Record<string, any> = Record<string, any>> {
     apiKey: string;
@@ -9,6 +11,14 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
     persistContext?: boolean;
     transport?: Transport<C, any>;
     transportMode?: TransportMode;
+    /**
+     * Enable SDK config-sync (local evaluation path).
+     * 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).
+     */
+    configSync?: boolean;
     /**
      * Called when a non-fatal but noteworthy error occurs during or after initialization.
      * The client always resolves ready() regardless — use this to show a degraded/fallback UI.
@@ -28,7 +38,19 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
     deferInitialization?: boolean;
     cacheAdapter?: CacheAdapter<C>;
     restEndpoint?: string;
+    /**
+     * SSE stream base (`…/evaluator/v2/flags`). Defaults to the stream host
+     * (`stream.flagmint.com` / `staging-stream…`). EventSource only — context
+     * POST uses the API host (see `flagsEndpoint` / `restEndpoint`).
+     */
     sseEndpoint?: string;
+    /**
+     * API base for `POST …/context` (`…/evaluator/v2/flags`). Defaults from
+     * `restEndpoint`. Override for self-hosted splits that do not match evaluate→v2/flags.
+     */
+    flagsEndpoint?: string;
+    /** Override the ASL handshake URL. Use with `sseEndpoint` / `restEndpoint` for self-hosted gateways. */
+    handshakeEndpoint?: string;
     debugLog?: boolean;
     env?: string;
     enableFlagmint: boolean;
@@ -37,6 +59,22 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
         version: string;
     };
     EventSourceImpl?: any;
+    /**
+     * Share one streaming connection across same-origin documents (tabs / iframes)
+     * that use the same API key. Defaults to true in browsers with BroadcastChannel,
+     * false in Node (cluster workers each keep their own stream).
+     *
+     * Followers do not handshake or open EventSource. They receive flags from the
+     * 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.
+     */
+    shareConnection?: boolean;
+    /**
+     * Test/runtime hooks for the share hub (channel, storage, timers).
+     * Omit in production.
+     */
+    share?: ConnectionShareOptions;
 }
 type FlagUpdateCallback<T> = (flags: FeatureFlags<T>) => void;
 export declare class FlagClient<T = unknown, C extends Record<string, any> = Record<string, any>> {
@@ -49,8 +87,19 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private cacheTTL;
     private transport;
     private restEndpoint;
+    private eventsEndpoint;
     private aslHandshakeUrl;
     private sseEndpoint;
+    /** API host base for POST /context (stream host may be SSE-only). */
+    private flagsApiEndpoint;
+    private eventQueue;
+    private eventFlushTimer;
+    /** Coalesced getFlag hits waiting for EVAL_REPORT_FLUSH_MS. */
+    private evaluationReportQueue;
+    private evaluationReportTimer;
+    /** null = server has not sent a map yet; send and let ingest drop. */
+    private analyticsByFlag;
+    private contextUpdateSeq;
     private readyPromise;
     private resolveReady;
     private rejectReady;
@@ -64,6 +113,12 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private initializationOptions?;
     private isInitialized;
     private subscribers;
+    private shareHub;
+    private shareConnection;
+    private configSync;
+    private rulesStore;
+    /** Avoid stacking reconnects when many getFlag calls hit an expired lease. */
+    private leaseRenewInFlight;
     /**
      * Creates a new FlagClient instance.
      * @param options - Configuration options for the client.
@@ -73,8 +128,14 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      * Initializes the client by loading cached flags and context, setting up the transport layer.
      */
     private initialize;
+    private bindTransport;
+    /**
+     * @returns true when this document is a follower and should skip opening a stream.
+     */
+    private joinConnectionShare;
+    private attachShareLeader;
     /**
-   * Creates and initializes the transport layer used to receive feature flag
+   * Creates and initializes the transport layer used to receive feature flags
    * updates from the Flagmint platform.
    *
    * This method performs the authentication handshake to obtain a fresh session
@@ -119,14 +180,38 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     subscribe(callback: FlagUpdateCallback<T>): () => void;
     /**
      * Get all flags.
+     * Config-sync: if the lease expired, fail-closed to defaults and reconnect.
      */
     getFlags(): FeatureFlags<T>;
     /**
      * Get a single flag value.
+     * When analytics is on for the flag, queues a debounced call-site evaluation
+     * report (dashboard Evaluations / unique users). Does not consume billing quota.
+     * Config-sync: expired lease → defaults only, then drop/reconnect (24h renew).
      */
     getFlag<K extends keyof FeatureFlags<T>>(key: K, fallback?: FeatureFlags<T>[K]): FeatureFlags<T>[K];
+    private queueEvaluationReport;
+    private flushEvaluationReports;
+    /**
+     * Report an application error that happened after this flag was served.
+     * Fire-and-forget: events are batched and never throw.
+     * No-ops when Analytics Tracking is off for that flag.
+     */
+    trackError(flagKey: string, error?: unknown, extra?: Record<string, unknown>): void;
+    /**
+     * Report a custom metric event attributed to the currently served variation.
+     * Fire-and-forget: events are batched and never throw.
+     * No-ops when Analytics Tracking is off for that flag.
+     */
+    track(flagKey: string, eventName: string, extra?: Record<string, unknown>): void;
+    /**
+     * Whether Analytics Tracking is on for this flag in the last streamed payload.
+     * `undefined` means the server has not sent a map yet (older API / long-polling).
+     */
+    isAnalyticsEnabled(flagKey: string): boolean | undefined;
     /**
      * Update the evaluation context.
+     * Config-sync: renews the lease stream first if expired (still evaluates locally).
      */
     updateContext(context: C): Promise<void>;
     /**
@@ -142,8 +227,8 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
    * become available (or until the specified timeout expires) before awaiting
    * completion of the underlying transport initialization.
    *
-   * This method guarantees that transport or connection failures are surfaced,
-   * even when feature flags have already been restored from cache.
+   * Transport and connection failures do not reject this promise. The client reports them through the `onError` option and resolves anyway, so the
+   * application can render a fallback or degraded UI.
    *
    * @param {number} [timeoutMs=3000] - The maximum amount of time, in
    * milliseconds, to wait for the initial feature flag payload before
@@ -152,8 +237,7 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
    * @returns {Promise<void>} A promise that resolves when the client is fully
    * initialized and ready to evaluate feature flags.
    *
-   * @throws {Error} If client initialization or the underlying transport fails,
-   * such as authentication, rate limiting, or connection errors.
+   *
    */
     ready(timeoutMs?: number): Promise<void>;
     /**
@@ -180,6 +264,18 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
    * flag payload is received or when the timeout expires, whichever occurs first.
    */
     private waitForFlags;
+    private updateAnalytics;
+    private queueApplicationEvent;
+    private flushApplicationEvents;
+    /**
+     * If a previously-ready config-sync lease just crossed expiresAt: fail-closed
+     * to defaults, persist, notify once, and reconnect for fullConfig.
+     * Bootstrapping or already-expired stores return without side effects so
+     * getFlag/getFlags cannot re-enter via subscriber updates.
+     *
+     * @param now Wall clock for expiry check
+     */
+    private ensureConfigSyncLeaseFresh;
     /**
      * Performs the initial authentication handshake with the Flagmint server
      * to obtain a fresh, single-use session identifier.
@@ -201,5 +297,17 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      * @throws {Error} If the handshake response does not contain a valid session ID.
      */
     private fetchFreshSessionId;
+    /** Config-sync rules store (null when `configSync` is false). */
+    getRulesStore(): RulesStore | null;
+    /**
+     * Restore rules from localCache before the stream opens.
+     * Fresh lease → reconnect with sinceVersion; expired → fullConfig.
+     */
+    private hydrateRulesFromCache;
+    /** Persist rules after a successful (or expiry/gap) apply so reconnect can catch up. */
+    private persistRulesSnapshot;
+    private handleConfigSyncEvent;
+    private evaluateFromRulesStore;
+    private analyticsMapFromRulesStore;
 }
 export {};

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

@@ -3,6 +3,7 @@
  * using the ported `flagEvaluator` (spec = utils/flag-evaluator.ts).
  */
 import { type FlagEvaluationResult } from './flagEvaluator';
+import { type PiiWireOptions } from './piiHash';
 import type { SdkFlagConfig, SdkSegment } from './types';
 /** ES2018-safe Map → record (avoids Object.fromEntries / ES2019 lib). */
 export declare function mapToRecord<V>(map: Map<string, V>): Record<string, V>;
@@ -16,11 +17,33 @@ export declare function mapToRecord<V>(map: Map<string, V>): Record<string, V>;
  *   and organization is not dropped.
  */
 export declare function prepareContextForEvaluator(context: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Flatten prepared context, then hash PII fields so they match hashed rule
+ * values on the config-sync wire (FF-EU Phase B / SDK Phase C).
+ *
+ * @param context Evaluation or flat context
+ * @param pii PII wire options from the rules store (null/undefined = no-op)
+ */
+export declare function prepareContextForLocalEval(context: Record<string, unknown> | null | undefined, pii?: PiiWireOptions | null): Record<string, unknown>;
 /**
  * Evaluate one SdkFlagConfig against context (server RuleEngine order).
+ *
+ * @param flag Compiled flag config
+ * @param context Evaluation context (plaintext PII is hashed when `pii` is set)
+ * @param segments Segment map for segment rules
+ * @param pii Optional PII wire options from the signed config
+ */
+export declare function evaluateSdkFlag(flag: SdkFlagConfig, context: Record<string, unknown>, segments: Map<string, SdkSegment> | Record<string, SdkSegment>, pii?: PiiWireOptions | null): FlagEvaluationResult;
+/**
+ * Evaluate every flag in a map/list against one context.
+ *
+ * @param flags Flag configs
+ * @param context Shared evaluation context
+ * @param segments Segment map
+ * @param options Fail-closed and PII wire options
  */
-export declare function evaluateSdkFlag(flag: SdkFlagConfig, context: Record<string, unknown>, segments: Map<string, SdkSegment> | Record<string, SdkSegment>): FlagEvaluationResult;
 export declare function evaluateAllSdkFlags<T = unknown>(flags: Map<string, SdkFlagConfig> | SdkFlagConfig[], context: Record<string, unknown>, segments: Map<string, SdkSegment> | Record<string, SdkSegment>, options?: {
     failClosedDefaultsOnly?: boolean;
+    pii?: PiiWireOptions | null;
 }): Record<string, T>;
 export { coerceType } from './flagEvaluator';

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

@@ -3,10 +3,12 @@ export type { AslClientKeyPair, AslDerivedMac } from './aslEcdh';
 export { canonicalizeForSigning, isConfigPayloadExpired, signConfigPayload, verifyConfigPayloadSignature, } from './signPayload';
 export { RulesStore, createEmptyRulesState, reduceRules, } from './rulesStore';
 export type { ApplyResult, RulesState } from './rulesStore';
-export type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, RulesCacheSnapshot, SdkFlagConfig, SdkSegment, SignableConfigBody, } from './types';
+export type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, PiiWireMetadata, RulesCacheSnapshot, SdkFlagConfig, SdkSegment, SignableConfigBody, } from './types';
 export { performAslHandshake } from './handshake';
 export type { AslHandshakeSuccess } from './handshake';
-export { evaluateSdkFlag, evaluateAllSdkFlags, coerceType, prepareContextForEvaluator, mapToRecord, } from './evaluateSdkFlag';
+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 { 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

@@ -0,0 +1,53 @@
+/** Must match FF-EU `PII_VALUE_ENCODING`. */
+export declare const PII_VALUE_ENCODING: "hmac-v1";
+/**
+ * Client PII wire options from signed `fullConfig` / `delta`.
+ */
+export type PiiWireOptions = {
+    piiAttributes: string[];
+    piiSalt: string;
+    piiValueEncoding?: typeof PII_VALUE_ENCODING | string;
+};
+/**
+ * Normalize a string before PII hashing (trim + lowercase).
+ * Must match FF-EU `normalizePiiString`.
+ *
+ * @param value Raw attribute value
+ */
+export declare function normalizePiiString(value: string): string;
+/**
+ * HMAC-SHA256 hex digest of a normalized PII string.
+ * Must match FF-EU `hashPiiValue`.
+ *
+ * @param value Plaintext value
+ * @param salt Client-visible salt from the signed config
+ */
+export declare function hashPiiValue(value: string, salt: string): string;
+/**
+ * Whether a context / rule attribute key is PII.
+ * Matches bare keys (`email`) and kind-prefixed forms (`user.email`).
+ *
+ * @param attribute Attribute key from context or rule
+ * @param piiAttributes Keys from signed config
+ */
+export declare function isPiiAttribute(attribute: string | undefined | null, piiAttributes: readonly string[]): 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;
+/**
+ * Hash PII string fields on a flat evaluation context so they match hashed
+ * rule values on the wire.
+ *
+ * @param context Flat context map (after prepare / flatten)
+ * @param options PII options from the rules store
+ * @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>;

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

@@ -1,3 +1,4 @@
+import { type PiiWireOptions } from './piiHash';
 import type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, RulesCacheSnapshot, SdkFlagConfig, SdkSegment } from './types';
 export type RulesState = {
     version: number;
@@ -8,6 +9,8 @@ export type RulesState = {
     ready: boolean;
     /** Set when a delta's fromVersion does not match — reconnect with fullConfig. */
     needsFullConfig: boolean;
+    /** PII hash options from the last fullConfig/delta (null when absent). */
+    piiWire: PiiWireOptions | null;
 };
 export type ApplyResult = {
     ok: true;
@@ -36,6 +39,10 @@ export declare class RulesStore {
      * Fail-closed readiness: lease not expired and store marked ready.
      */
     isReady(now?: number): boolean;
+    /**
+     * Mark the store fail-closed after wall-clock lease expiry.
+     * Next reconnect must request fullConfig (or a fresh lease + catch-up).
+     */
     markExpired(): void;
     getFlag(key: string): SdkFlagConfig | undefined;
     /**

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

@@ -33,6 +33,12 @@ export type LeasePayload = {
     expiresAt: number;
     signature: string;
 };
+/** PII hashing metadata on client-bound config (FF-EU Phase B). */
+export type PiiWireMetadata = {
+    piiAttributes?: string[];
+    piiSalt?: string;
+    piiValueEncoding?: string;
+};
 export type FullConfigPayload = {
     type: 'fullConfig';
     version: number;
@@ -42,7 +48,7 @@ export type FullConfigPayload = {
     segments: Record<string, SdkSegment>;
     warnings?: string[];
     signature: string;
-};
+} & PiiWireMetadata;
 export type DeltaConfigPayload = {
     type: 'delta';
     fromVersion: number;
@@ -53,7 +59,7 @@ export type DeltaConfigPayload = {
     deletes: string[];
     segments: Record<string, SdkSegment>;
     signature: string;
-};
+} & PiiWireMetadata;
 export type DeltasCatchUpPayload = {
     type: 'deltas';
     fromVersion: number;
@@ -69,4 +75,8 @@ export type RulesCacheSnapshot = {
     expiresAt: number;
     flags: SdkFlagConfig[];
     segments: Record<string, SdkSegment>;
+    /** PII wire options so offline hydrate still hashes context correctly. */
+    piiAttributes?: string[];
+    piiSalt?: string;
+    piiValueEncoding?: string;
 };

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

@@ -1,12 +1,16 @@
 export declare const MAX_EVENT_BATCH = 20;
 export declare const EVENT_FLUSH_MS = 2000;
-export type ApplicationEventKind = 'error' | 'custom';
+/** Debounce window for coalescing getFlag call-site evaluation reports. */
+export declare const EVAL_REPORT_FLUSH_MS = 2000;
+export type ApplicationEventKind = 'error' | 'custom' | 'evaluation';
 export interface ApplicationEvent {
     flagKey: string;
     kind: ApplicationEventKind;
     eventName?: string;
     variationValue?: unknown;
     userKey?: string;
+    /** Coalesced getFlag hits (evaluation kind only). */
+    count?: number;
     timestamp: string;
     extra?: Record<string, unknown>;
 }

package/dist/sdk/core/helpers/cacheHelper.async.d.ts

@@ -1,4 +1,5 @@
 import { FeatureFlags } from '../../core/helpers/types';
+import type { RulesCacheSnapshot } from '../../core/config-sync/types';
 export interface AsyncStorageAdapter {
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
@@ -9,3 +10,6 @@ export declare function loadCachedFlags<T>(apiKey: string, ttl: number): Promise
 export declare function saveCachedFlags<T>(apiKey: string, data: FeatureFlags<T>): Promise<void>;
 export declare function loadCachedContext<C>(apiKey: string): Promise<C | null>;
 export declare function saveCachedContext<C>(apiKey: string, context: C): Promise<void>;
+export declare function loadCachedRulesSnapshot(apiKey: string): Promise<RulesCacheSnapshot | null>;
+export declare function saveCachedRulesSnapshot(apiKey: string, snapshot: RulesCacheSnapshot): Promise<void>;
+export declare function clearCachedRulesSnapshot(apiKey: string): Promise<void>;

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

@@ -1,4 +1,5 @@
 import { FeatureFlags } from '../../core/helpers/types';
+import type { RulesCacheSnapshot } from '../../core/config-sync/types';
 export interface StorageAdapter {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
@@ -9,3 +10,7 @@ export declare function loadCachedFlags<T>(apiKey: string, ttl: number): Feature
 export declare function saveCachedFlags<T>(apiKey: string, data: FeatureFlags<T>): 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. */
+export declare function loadCachedRulesSnapshot(apiKey: string): RulesCacheSnapshot | null;
+export declare function saveCachedRulesSnapshot(apiKey: string, snapshot: RulesCacheSnapshot): void;
+export declare function clearCachedRulesSnapshot(apiKey: string): void;

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

@@ -1,7 +1,14 @@
+import type { RulesCacheSnapshot } from '../../core/config-sync/types';
 export type FeatureFlags<T = unknown> = Record<string, T>;
 export interface CacheAdapter<C extends Record<string, any> = any> {
     loadFlags(apiKey: string, ttl: number): Promise<FeatureFlags> | FeatureFlags | null;
     saveFlags(apiKey: string, data: FeatureFlags): Promise<void> | void;
     loadContext(apiKey: string): Promise<C | null> | C | null;
     saveContext(apiKey: string, ctx: C): Promise<void> | void;
+    /**
+     * Config-sync localCache (optional). When omitted, rules are not persisted
+     * across reloads — every boot is a cold start (`fullConfig=true`).
+     */
+    loadRulesSnapshot?(apiKey: string): Promise<RulesCacheSnapshot | null> | RulesCacheSnapshot | null;
+    saveRulesSnapshot?(apiKey: string, snapshot: RulesCacheSnapshot): Promise<void> | void;
 }

package/dist/sdk/core/transports/LongPollingTransport.d.ts

@@ -13,6 +13,7 @@ export declare class LongPollingTransport<C, T> implements Transport<C, T> {
     private backoffMultiplier;
     private pollTimeoutId;
     private onUpdateCallback?;
+    private onAnalyticsUpdatedCallback?;
     private currentContext;
     private currentFlags;
     private consecutiveErrors;
@@ -23,7 +24,11 @@ export declare class LongPollingTransport<C, T> implements Transport<C, T> {
     private poll;
     private applyBackoff;
     private flagsChanged;
-    fetchFlags(context: C): Promise<Record<string, T>>;
+    fetchFlags(context: C, options?: {
+        persist?: boolean;
+    }): Promise<Record<string, T>>;
+    private readQuotaPayload;
     onFlagsUpdated(callback: (flags: Record<string, T>) => void): void;
+    onAnalyticsUpdated(callback: (analytics: Record<string, boolean>) => void): void;
     destroy(): void;
 }

package/dist/sdk/core/transports/SSETransport.d.ts

@@ -106,6 +106,13 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     onAnalyticsUpdated(callback: (analytics: Record<string, boolean>) => void): void;
     onError(callback: (error: Error) => void): void;
     destroy(): void;
+    /**
+     * Drop the live stream and reconnect (fresh ASL ticket).
+     * Used when the config-sync lease expires so the next open can request fullConfig.
+     *
+     * @param reason Lifecycle reason for debug logs
+     */
+    requestReconnect(reason?: string): void;
     /**
      * Opt-in SSE lifecycle lines (`FlagClient` `debugLog: true`).
      * Example: `[SseTransport] disconnected connectionId=… upMs=900012 reason=network_error retryInMs=1500`

package/dist/sdk/core/transports/Transport.d.ts

@@ -1,7 +1,13 @@
 export interface Transport<C, T> {
     init(onUpdate?: (flags: Record<string, T>) => void): Promise<void>;
-    fetchFlags(context: C): Promise<Record<string, T>>;
+    fetchFlags(context: C, options?: {
+        persist?: boolean;
+    }): Promise<Record<string, T>>;
     destroy(): void;
+    /** Optional: drop + reconnect (SSE). Used for config-sync lease renewal. */
+    requestReconnect?(reason?: string): void;
     onFlagsUpdated?: (callback: (flags: Record<string, T>) => void) => void;
+    onAnalyticsUpdated?: (callback: (analytics: Record<string, boolean>) => void) => void;
     onContextUpdated?: (callback: (context: C) => void) => void;
+    onError?: (callback: (error: Error) => void) => void;
 }

package/package.json

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