flagmint-js-sdk 2.0.0 → 2.2.1

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

@@ -0,0 +1,60 @@
+import type { ConfigSyncPayload, DeltaConfigPayload, DeltasCatchUpPayload, FullConfigPayload, LeasePayload, RulesCacheSnapshot, SdkFlagConfig, SdkSegment } from './types';
+export type RulesState = {
+    version: number;
+    expiresAt: number;
+    flags: Map<string, SdkFlagConfig>;
+    segments: Map<string, SdkSegment>;
+    /** false when lease expired offline — fail closed (defaults only). */
+    ready: boolean;
+    /** Set when a delta's fromVersion does not match — reconnect with fullConfig. */
+    needsFullConfig: boolean;
+};
+export type ApplyResult = {
+    ok: true;
+    state: RulesState;
+} | {
+    ok: false;
+    reason: 'bad_signature' | 'version_gap' | 'stale' | 'expired' | 'invalid_payload';
+    state: RulesState;
+};
+export declare function createEmptyRulesState(): RulesState;
+/**
+ * Pure reducer for config-sync actions (signatures already verified).
+ */
+export declare function reduceRules(state: RulesState, action: ConfigSyncPayload, now?: number): ApplyResult;
+/**
+ * In-memory rules store: verify MAC → reduce → optional localCache snapshot.
+ */
+export declare class RulesStore {
+    private state;
+    private macKey;
+    constructor(macKey?: Uint8Array | null, initial?: RulesState);
+    setMacKey(macKey: Uint8Array | null): void;
+    getMacKey(): Uint8Array | null;
+    getState(): RulesState;
+    /**
+     * 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;
+    /**
+     * Fail-closed default for a flag key (last-known `default_value` only).
+     */
+    getFailClosedDefault(key: string): unknown;
+    wantsFullConfig(now?: number): boolean;
+    sinceVersion(now?: number): number | undefined;
+    /**
+     * Verify signature with the session MAC key, then apply the reducer.
+     */
+    applySigned(payload: ConfigSyncPayload, now?: number): ApplyResult;
+    /** Apply without MAC (unit tests / already-verified payloads). */
+    applyTrusted(payload: ConfigSyncPayload, now?: number): ApplyResult;
+    toSnapshot(): RulesCacheSnapshot;
+    hydrateFromSnapshot(snapshot: RulesCacheSnapshot, now?: number): void;
+}
+export type { LeasePayload, FullConfigPayload, DeltaConfigPayload, DeltasCatchUpPayload };

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

@@ -0,0 +1,17 @@
+import type { SignableConfigBody } from './types';
+/**
+ * Stable JSON for HMAC: sort object keys recursively so field order cannot
+ * invalidate signatures across language runtimes.
+ * Must match FF-EU `canonicalizeForSigning`.
+ */
+export declare function canonicalizeForSigning(value: unknown): string;
+/**
+ * HMAC-SHA256 hex digest over the payload with `signature` omitted.
+ */
+export declare function signConfigPayload(body: SignableConfigBody, secret: Uint8Array | string): string;
+/**
+ * Verify HMAC-SHA256 hex `signature` on a config-sync payload.
+ * Prefer the ASL ECDH-derived session MAC key.
+ */
+export declare function verifyConfigPayloadSignature(body: SignableConfigBody, secret: Uint8Array | string): boolean;
+export declare function isConfigPayloadExpired(expiresAt: number, now?: number): boolean;

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

@@ -0,0 +1,7 @@
+/**
+ * djb2 variant matching npm `string-hash` (and Go `evaluate.StringHash`).
+ * Iterates right-to-left with XOR — required for rollout bucket parity.
+ */
+export declare function stringHash(input: string): number;
+/** Stable bucket in [0, 99] for percentage / variant rollouts. */
+export declare function hashPercent(input: string): number;

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

@@ -0,0 +1,72 @@
+/**
+ * Wire types for SSE config-sync (aligned with FF-EU `modules/evaluator/config-sync.ts`).
+ */
+export type SdkFlagConfig = {
+    key: string;
+    type: 'boolean' | 'string' | 'number' | 'json';
+    is_active: boolean;
+    default_value: unknown;
+    off_variation_id?: string | null;
+    targeting_rules: unknown[];
+    variations: Array<{
+        id: string;
+        value: unknown;
+        key?: string;
+        name?: string;
+    }>;
+    rollouts: Record<string, unknown>;
+    analytics_enabled: boolean;
+};
+export type SdkSegment = {
+    id: string;
+    rules: unknown[];
+    logical_op?: string;
+    force?: boolean;
+};
+export type SignableConfigBody = Record<string, unknown> & {
+    signature?: string;
+};
+export type LeasePayload = {
+    type: 'lease';
+    version: number;
+    serverNow: number;
+    expiresAt: number;
+    signature: string;
+};
+export type FullConfigPayload = {
+    type: 'fullConfig';
+    version: number;
+    compiledAt: number;
+    expiresAt: number;
+    flags: SdkFlagConfig[];
+    segments: Record<string, SdkSegment>;
+    warnings?: string[];
+    signature: string;
+};
+export type DeltaConfigPayload = {
+    type: 'delta';
+    fromVersion: number;
+    toVersion: number;
+    compiledAt: number;
+    expiresAt: number;
+    upserts: SdkFlagConfig[];
+    deletes: string[];
+    segments: Record<string, SdkSegment>;
+    signature: string;
+};
+export type DeltasCatchUpPayload = {
+    type: 'deltas';
+    fromVersion: number;
+    toVersion: number;
+    expiresAt: number;
+    items: DeltaConfigPayload[];
+    signature: string;
+};
+export type ConfigSyncPayload = LeasePayload | FullConfigPayload | DeltaConfigPayload | DeltasCatchUpPayload;
+/** Persisted cache for reconnect (`fullConfig` vs `sinceVersion`). */
+export type RulesCacheSnapshot = {
+    version: number;
+    expiresAt: number;
+    flags: SdkFlagConfig[];
+    segments: Record<string, SdkSegment>;
+};

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

@@ -1,16 +1,27 @@
 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>;
 }
 export declare function eventsUrlFromRestEndpoint(restEndpoint: string): string;
+/**
+ * API base for `POST …/context` (and similar) from the REST evaluate URL.
+ * Stream hosts may be SSE-only (`STREAM_HOSTS`); context must stay on the API host.
+ *
+ * `https://api…/evaluator/evaluate` → `https://api…/evaluator/v2/flags`
+ */
+export declare function flagsBaseFromRestEndpoint(restEndpoint: string): string;
 export declare function userKeyFromContext(context: Record<string, unknown> | undefined): string | undefined;
 export declare function extraFromError(error: unknown, extra?: Record<string, unknown>): Record<string, unknown> | undefined;
 /**

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

@@ -100,6 +100,7 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     private closed;
     private latestFlags;
     private flagsWaiters;
+    private flagsTimeouts;
     private contextWaiters;
     private onPromoteCallback?;
     private leaderContextHandler?;
@@ -167,6 +168,12 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     destroy(): void;
     private bindUnloadListener;
     private unbindUnloadListener;
+    /**
+     * JSON-clone then post. Native `BroadcastChannel` structured-clones the
+     * payload; Vue reactive Proxies and similar host objects throw
+     * `DataCloneError`. JSON.stringify can walk those Proxies.
+     */
+    private post;
     /** Open the BroadcastChannel for this API key, or a test factory channel. */
     private openChannel;
     /** Mark this member leader and start lock heartbeat + `alive` pings. */

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

@@ -0,0 +1,2 @@
+export declare const ERR_CONTEXT_NOT_CLONEABLE = "ERR_CONTEXT_NOT_CLONEABLE";
+export declare function toJsonCloneable<T>(value: T): T;

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

@@ -27,6 +27,7 @@ export declare class LongPollingTransport<C, T> implements Transport<C, 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

@@ -1,5 +1,5 @@
 import type { Transport } from './Transport';
-export interface SseTransportConfig {
+export interface SseTransportConfig<C = unknown, T = unknown> {
     endpoint: string;
     apiKey: string;
     context: any;
@@ -8,6 +8,37 @@ export interface SseTransportConfig {
         version: string;
     };
     EventSourceImpl?: any;
+    /**
+     * When true, stream uses config-sync (`fullConfig` / `sinceVersion`) and
+     * listens for lease / fullConfig / delta / deltas instead of evaluated `flags`.
+     */
+    configSync?: boolean;
+    /** Build config-mode query params for each connect/reconnect. */
+    getConfigSyncParams?: () => {
+        wantFullConfig: boolean;
+        sinceVersion?: number;
+    };
+    /**
+     * Apply a signed config-sync payload (verify + reduce). Return whether the
+     * rules store is ready enough to publish evaluated flags.
+     */
+    onConfigSyncEvent?: (eventName: 'lease' | 'fullConfig' | 'delta' | 'deltas', payload: Record<string, unknown>) => {
+        publish: boolean;
+    };
+    /** Evaluate current rules store against the given (or last) context. */
+    getEvaluatedFlags?: (context: C) => Record<string, T>;
+    /** Analytics map from the rules store (flag key → analytics_enabled). */
+    getAnalyticsMap?: () => Record<string, boolean>;
+    /**
+     * When true (config sync), POST /context is fire-and-forget telemetry —
+     * flags are re-evaluated locally and returned immediately.
+     */
+    contextAsTelemetry?: boolean;
+    /**
+     * API base for `POST …/context` (defaults to `endpoint`). Use the API host
+     * when `endpoint` is a stream-only hostname.
+     */
+    contextEndpoint?: string;
 }
 /**
  * A Server-Sent Events (SSE) transport implementation responsible for
@@ -17,8 +48,9 @@ export interface SseTransportConfig {
  * Stream: `GET {endpoint}/stream?sessionId&context&sdkVersion&platform&wrapper*`
  *   emits `connected` then `flags`. Heartbeats are SSE comments (`: heartbeat`)
  *   and are not visible to EventSource — they only keep the TCP connection alive.
- * Context: `POST {endpoint}/context` with `x-api-key` returns 202 and the
+ * Context: `POST {contextEndpoint|endpoint}/context` with `x-api-key` returns 202 and the
  *   re-evaluated flags arrive on the existing stream after a 400ms debounce.
+ *   Prefer the API host when `endpoint` is stream-only (`STREAM_HOSTS`).
  *
  * @template C The shape of the evaluation context sent to the Flagmint server.
  * @template T The feature flag value type returned by the platform.
@@ -33,6 +65,7 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     private eventSource;
     private flags;
     private context;
+    private lastSentContext;
     private connectionId;
     private onFlagsUpdatedCallback?;
     private onAnalyticsUpdatedCallback?;
@@ -46,13 +79,20 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     private connectReject;
     private connectionListener?;
     private flagsListener?;
+    private leaseListener?;
+    private fullConfigListener?;
+    private deltaListener?;
+    private deltasListener?;
     private quotaListener?;
     private errorListener?;
     private reconnectTimeoutId;
     private reconnectAttempts;
     private terminalClose;
     private contextUpdateQueue;
-    constructor(endpoint: string, sessionId: string, initialContext: C, refreshTokenCallback?: (() => Promise<string>) | undefined, configOptions?: Partial<SseTransportConfig> | undefined);
+    /** Wall time when the current SSE `connected` event was received (debug lifecycle). */
+    private connectedAtMs;
+    constructor(endpoint: string, sessionId: string, initialContext: C, refreshTokenCallback?: (() => Promise<string>) | undefined, configOptions?: Partial<SseTransportConfig<C, T>> | undefined);
+    private get configSyncEnabled();
     init(): Promise<void>;
     /**
      * POST /v2/flags/context. FF-EU always returns 202 and pushes the next
@@ -66,10 +106,28 @@ 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`
+     */
+    private logLifecycle;
+    private logLifecycleConnected;
+    private logLifecycleDisconnected;
     private get apiKey();
+    /** Host for POST /context — API when stream host is SSE-only. */
+    private get contextBase();
     private applyFlags;
     private emitError;
     private performContextUpdate;
+    /** Fire-and-forget observed-context telemetry for config-sync mode. */
+    private postContextTelemetry;
     private safeReadJson;
     private quotaExtra;
     private handleQuotaPayload;
@@ -79,6 +137,7 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     private scheduleActiveReconnection;
     private createConnectionListener;
     private createFlagsListener;
+    private createConfigSyncListener;
     private createQuotaListener;
     /**
      * Named `error` events from FF-EU (`event: error`) after the stream is hijacked.

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

@@ -4,6 +4,8 @@ export interface Transport<C, T> {
         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;

package/package.json

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