flagmint-js-sdk 1.2.26 → 2.2.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@ 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';
 export { LongPollingTransport } from './sdk/core/transports/LongPollingTransport';
-export { WebSocketTransport } from './sdk/core/transports/WebsocketTransport';
+export { SseTransport } from './sdk/core/transports/SSETransport';
 export type { FlagValue, EvaluationContext, Segment, Rollout, VariantRollout, VariantOption } from './sdk/core/evaluation/types';
 export { evaluateFlagValue } from './sdk/core/evaluation/evaluateFlagValue';
 export { evaluateRollout } from './sdk/core/evaluation/evaluateRollout';

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

@@ -1,7 +1,7 @@
 import { CacheAdapter, FeatureFlags } from '../core/helpers/types';
 import type { Transport } from '../core/transports/Transport';
 import { FlagValue } from '../core/evaluation/types';
-type TransportMode = 'auto' | 'websocket' | 'long-polling';
+type TransportMode = 'auto' | 'long-polling' | 'sse';
 export interface FlagClientOptions<C extends Record<string, any> = Record<string, any>> {
     apiKey: string;
     context?: C;
@@ -28,10 +28,15 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
     deferInitialization?: boolean;
     cacheAdapter?: CacheAdapter<C>;
     restEndpoint?: string;
-    wsEndpoint?: string;
+    sseEndpoint?: string;
     debugLog?: boolean;
     env?: string;
     enableFlagmint: boolean;
+    wrapperInfo?: {
+        name: string;
+        version: string;
+    };
+    EventSourceImpl?: any;
 }
 type FlagUpdateCallback<T> = (flags: FeatureFlags<T>) => void;
 export declare class FlagClient<T = unknown, C extends Record<string, any> = Record<string, any>> {
@@ -44,7 +49,8 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private cacheTTL;
     private transport;
     private restEndpoint;
-    private wsEndpoint;
+    private aslHandshakeUrl;
+    private sseEndpoint;
     private readyPromise;
     private resolveReady;
     private rejectReady;
@@ -68,8 +74,33 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      */
     private initialize;
     /**
-     * Sets up the transport layer for the client.
-     */
+   * Creates and initializes the transport layer used to receive feature flag
+   * updates from the Flagmint platform.
+   *
+   * This method performs the authentication handshake to obtain a fresh session
+   * identifier, selects the appropriate transport based on the configured
+   * transport mode, and initializes it before attaching the internal flag update
+   * listener.
+   *
+   * When operating in `auto` mode, the client attempts to establish a
+   * Server-Sent Events (SSE) connection first. If SSE initialization fails,
+   * it automatically falls back to the long-polling transport to maintain
+   * feature flag delivery.
+   *
+   * Once the transport is ready, any available initial flags are immediately
+   * synchronized into the client state before future updates are received
+   * through the transport's notification callbacks.
+   *
+   * @param {FlagClientOptions<C>} options - The client configuration used to
+   * authenticate the handshake request and determine which transport strategy
+   * to initialize.
+   *
+   * @returns {Promise<void>} A promise that resolves once the selected transport
+   * has been initialized and wired into the FlagClient.
+   *
+   * @throws {Error} If the authentication handshake fails, the session identifier
+   * cannot be obtained, or the configured transport fails to initialize.
+   */
     private setupTransport;
     /**
      * Updates flags and notifies all subscribers.
@@ -103,15 +134,72 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      */
     destroy(): void;
     /**
-     * Wait for the client to be ready.
-     * Resolves when: flags are available AND initialization succeeded.
-     * Rejects if: initialization/connection fails (even if cached flags exist).
-     */
+   * Waits until the FlagClient is fully initialized and ready for feature flag
+   * evaluation.
+   *
+   * If deferred initialization is enabled, this method will first perform the
+   * initial client setup. It then waits for the first feature flag payload to
+   * 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.
+   *
+   * @param {number} [timeoutMs=3000] - The maximum amount of time, in
+   * milliseconds, to wait for the initial feature flag payload before
+   * continuing initialization.
+   *
+   * @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>;
     /**
      * Evaluate flags locally (for preview mode).
      */
     private evaluateLocally;
+    /**
+   * Waits until the client receives its first non-empty feature flag payload,
+   * or until the specified timeout elapses.
+   *
+   * This method subscribes to flag updates and resolves as soon as at least one
+   * feature flag is available. If no flags are received within the allotted
+   * timeout, the promise still resolves, allowing the SDK to continue
+   * initialization using default or cached values instead of blocking
+   * indefinitely.
+   *
+   * The internal subscription is automatically removed when either condition
+   * is met to prevent memory leaks.
+   *
+   * @param {number} timeoutMs - The maximum amount of time, in milliseconds,
+   * to wait for the initial feature flag payload before resolving.
+   *
+   * @returns {Promise<void>} A promise that resolves when the first non-empty
+   * flag payload is received or when the timeout expires, whichever occurs first.
+   */
     private waitForFlags;
+    /**
+     * Performs the initial authentication handshake with the Flagmint server
+     * to obtain a fresh, single-use session identifier.
+     *
+     * The returned session ID is used by streaming transports (SSE/WebSocket)
+     * to establish an authenticated real-time connection. Session identifiers
+     * are intentionally short-lived and should not be reused across new
+     * streaming connections.
+     *
+     * @param {string} apiKey - The Flagmint API key used to authenticate the
+     * handshake request.
+     *
+     * @returns {Promise<string>} A promise that resolves with a newly issued
+     * session identifier.
+     *
+     * @throws {Error} If the API credentials are invalid (`ERR_AUTH`).
+     * @throws {Error} If the client has exceeded its rate limit (`ERR_RATE_LIMITED`).
+     * @throws {Error} If the handshake endpoint returns an unexpected HTTP error.
+     * @throws {Error} If the handshake response does not contain a valid session ID.
+     */
+    private fetchFreshSessionId;
 }
 export {};

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

@@ -0,0 +1,32 @@
+/** Must match FF-EU `utils/config-sync/asl-ecdh.ts`. */
+export declare const ASL_CLIENT_PUBLIC_KEY_HEX_LENGTH = 64;
+export declare const ASL_HKDF_INFO = "flagmint-asl-config-sync-mac-v1";
+export declare const ASL_KEY_AGREEMENT: "x25519-hkdf-sha256";
+export type AslClientKeyPair = {
+    /** Raw X25519 public key — 64 lowercase hex chars. */
+    publicKeyHex: string;
+    /** Keep private; never send on the wire. */
+    privateKey: Uint8Array;
+};
+export type AslDerivedMac = {
+    /** 32-byte session MAC key — never sent on the wire. */
+    configMacKey: Uint8Array;
+};
+/**
+ * Generate an ephemeral X25519 keypair for the ASL handshake ECDH.
+ */
+export declare function generateAslClientKeyPair(): AslClientKeyPair;
+export declare function parsePeerPublicKeyHex(hex: string): Uint8Array;
+/** HKDF salt from the handshake — public; must be even-length hex (FF-EU uses 16 bytes). */
+export declare function parseSaltHex(hex: string): Uint8Array;
+/**
+ * Client half of X25519 ECDH + HKDF.
+ * Derives the same MAC key as the server without transmitting the secret.
+ */
+export declare function deriveAslMacKey(input: {
+    privateKey: Uint8Array;
+    peerPublicKeyHex: string;
+    saltHex: string;
+}): AslDerivedMac;
+/** Zeroize a key buffer when the session ends (best-effort). */
+export declare function wipeKeyMaterial(key: Uint8Array | null | undefined): void;

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

@@ -0,0 +1,26 @@
+/**
+ * Top-level SdkFlagConfig evaluation — mirrors FF-EU RuleEngine.compileFlagToPredicate
+ * using the ported `flagEvaluator` (spec = utils/flag-evaluator.ts).
+ */
+import { type FlagEvaluationResult } from './flagEvaluator';
+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>;
+/**
+ * Prepare context for flag-evaluator.
+ *
+ * - Structured `kind` contexts pass through (evaluator flattens like the server).
+ * - Already-flat SSE maps pass through.
+ * - Nested SDK `{ user, organization, custom }` without `kind` →
+ *   `flattenEvaluationContext` (kind-prefixed) so multi-kind attrs do not collide
+ *   and organization is not dropped.
+ */
+export declare function prepareContextForEvaluator(context: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Evaluate one SdkFlagConfig against context (server RuleEngine order).
+ */
+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;
+}): Record<string, T>;
+export { coerceType } from './flagEvaluator';

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

@@ -0,0 +1,373 @@
+export type ExpectedFlagType = 'boolean' | 'string' | 'number' | 'json';
+export type FlagEvaluationResult = boolean | string | number | Record<string, any>;
+export type FlatContext = Record<string, any>;
+export type Condition = {
+    attribute: string;
+    operator: string;
+    value?: unknown;
+};
+export type TargetingRule = {
+    id?: string;
+    kind: 'segment' | 'custom' | string;
+    order_index: number;
+    segment_id?: string | null;
+    conditions?: Condition[];
+    logical_op?: string;
+    variation_id?: string | null;
+    rollout_id?: string | null;
+};
+export type Variation = {
+    id: string;
+    value: unknown;
+    key?: string;
+    name?: string;
+    type?: string;
+    description?: string;
+    [key: string]: unknown;
+};
+export type Rollout = {
+    strategy: 'off';
+} | {
+    strategy: 'percentage';
+    percentage: number;
+    salt: string;
+} | {
+    strategy: 'variant';
+    salt: string;
+    variants: {
+        variation_id: string;
+        weight: number;
+    }[];
+} | {
+    strategy: 'gradual';
+    salt: string;
+    target_percentage: number;
+    increment: number;
+    interval_hours: number;
+    start_at?: string;
+} | {
+    strategy?: string;
+    [key: string]: any;
+};
+export type Segment = {
+    id?: string;
+    rules?: Condition[];
+    logical_op?: string;
+    force?: boolean;
+};
+export type EvaluationDeps = {
+    segmentsById?: Record<string, Segment>;
+    variationsById: Record<string, Variation>;
+    rolloutsById: Record<string, Rollout>;
+    getHashPercent?: (input: string) => number;
+};
+type LogicalOperatorType = 'AND' | 'OR' | 'NOT';
+type EvaluationContextT = Record<string, any>;
+type TVariation = Variation;
+/**
+ * Evaluate kill switch state.
+ *
+ * DESIGN PURPOSE: Immediate flag override without evaluating targeting/rollouts.
+ *
+ * Use cases:
+ *   - Emergency shutoff: Instantly disable a feature causing issues
+ *   - Override complex targeting: Kill switch takes precedence over all rules
+ *   - Safe defaults: Return configured "off" variation instead of arbitrary fallback
+ *
+ * HOW IT WORKS:
+ *   1. If flag is inactive (`is_active=false`) AND has `off_variation_id` configured:
+ *      - Return the off variation value (kill switch activated)
+ *   2. Otherwise:
+ *      - Return null (kill switch not active, proceed with normal evaluation)
+ *
+ * EVALUATION PRIORITY:
+ *   Kill switch is checked FIRST, before:
+ *   - Targeting rules
+ *   - Segments
+ *   - Rollouts
+ *   - Default values
+ *
+ * NOTE:
+ *   - If flag is inactive but no off_variation_id is configured, returns null
+ *     (caller should fall back to default value)
+ *   - Variations should be pre-validated; missing variation logs warning
+ *
+ * @param isActive - Flag's active state
+ * @param offVariationId - ID of the variation to serve when flag is off
+ * @param variationsById - Map of variation IDs to variations
+ * @param expectedType - Expected flag type for coercion
+ * @returns Off variation value if kill switch active, null otherwise
+ */
+export declare function evaluateKillSwitch(isActive: boolean, offVariationId: string | null | undefined, variationsById: Record<string, TVariation> | undefined, expectedType: ExpectedFlagType): FlagEvaluationResult | null;
+/**
+ * Evaluate "on" variation for boolean kill switches.
+ *
+ * DESIGN PURPOSE: Simple boolean kill switch "ON" state using variations.
+ *
+ * DESIGN DECISION: Boolean-only kill switches.
+ * Flagmint uses kill switches exclusively for boolean flags to maintain simplicity
+ * and semantic clarity. For multi-value feature management, use targeting rules
+ * or rollout strategies instead.
+ *
+ * Use cases:
+ *   - Boolean kill switch: Two variations (true/false), serve true when active
+ *   - Simple feature flags: No targeting complexity, just on/off states
+ *   - Emergency controls: Instant enable/disable without complex logic
+ *
+ * HOW IT WORKS:
+ *   1. For boolean flags: Find the variation with value=true
+ *   2. If found, return that variation's value
+ *   3. Otherwise, return null (caller should fall back to default value)
+ *
+ * WHEN TO USE:
+ *   - Flag is active (`is_active=true`)
+ *   - Flag type is boolean
+ *   - No targeting rules
+ *   - No rollouts
+ *   - Variations are defined
+ *
+ * NOTE:
+ *   - This is the complement to evaluateKillSwitch (OFF state)
+ *   - Only works for boolean flags (kill switches are boolean-only in Flagmint)
+ *   - For flags with targeting/rollouts, use evaluateFlagWithTargetingRules instead
+ *
+ * @param variationsById - Map of variation IDs to variations
+ * @param expectedType - Expected flag type (must be 'boolean' for kill switches)
+ * @returns Variation with value=true if found, null otherwise
+ */
+export declare function evaluateOnVariation(variationsById: Record<string, TVariation> | undefined, expectedType: ExpectedFlagType): FlagEvaluationResult | null;
+/**
+ * Resolve a targeting attribute against a flat context.
+ *
+ * SSE flattens with kind prefixes (`user.siteIds`); HTTP flatten leaves
+ * user fields bare (`siteIds`) and custom fields as `custom.siteids`.
+ * Dashboard custom attributes are stored as `custom.siteids`.
+ */
+export declare function getContextAttribute(context: FlatContext, attribute: string): unknown;
+export declare function evaluateRule(condition: Condition, context: FlatContext): boolean;
+/**
+ * Coerces the evaluated flag result into its expected type.
+ *
+ * This helps guarantee SDK and app stability by ensuring that even if the value
+ * is malformed or unexpected, the returned type will always match what's expected.
+ * For JSON types, validates that the value is actually an object to prevent data corruption.
+ *
+ * NOTE: We DO NOT throw here to avoid crashing consumers; instead we log + return safe defaults.
+ *
+ * @param value - The raw value from flag config or rollout logic.
+ * @param expectedType - The expected type ('boolean', 'string', 'number', 'json').
+ * @returns The value coerced into the expected type.
+ */
+export declare function coerceType(value: unknown, expectedType: ExpectedFlagType): FlagEvaluationResult;
+/**
+ * @version 1.1.0
+ * Evaluate flag with advanced targeting rules (segments + custom rules).
+ * Supports variations and rollouts.
+ * Order of operations:
+ *  1. Flatten context and validate (fail fast for invalid configuration).
+ *  2. Iterate through targeting rules in order_index order.
+ *  3. For each rule:
+ *     - Evaluate rule (segment or custom).
+ *    - If rule matches:
+ *      - If variation_id is set, return that variation's value.
+ *     - If rollout_id is set, apply that rollout strategy.
+ * 4. If no rules match, return fallback value.
+ * @remarks
+ * Context usage (raw vs flat):
+ * - `context` (raw EvaluationContextT):
+ *   - Contains identity information: kind, key, user, organization, user_id, etc.
+ *  - Used for stable rollout keys and identity-based operations.
+ *  - Use for:
+ *   - rollout validation (`validateFlagContext`)
+ *  - rollout hashing (`applyPercentageRollout`, `applyVariantRollout`)
+ * - `flatCtx` = `flattenContext(context)`:
+ *  - Used to make attribute matching easy (e.g., country, plan, user.country).
+ * - Strips identity semantics (kind, multi structure).
+ * - Use for:
+ * - `evaluateRule`
+ * - `evaluateTargeting` (rules + segments)
+ * @param input - Input parameters including fallback value, expected type, and context.
+ * @param targetingRules - Array of targeting rules to evaluate.
+ * @param deps - Dependencies including segments, variations, rollouts, and hashing function.
+ * @returns Evaluated flag value coerced to the expected type.
+ */
+export declare function evaluateFlagWithTargetingRules(input: {
+    fallbackValue: unknown;
+    expectedType: ExpectedFlagType;
+    context: EvaluationContextT;
+}, targetingRules: TargetingRule[], deps: EvaluationDeps): FlagEvaluationResult;
+/**
+ * Apply gradual (incremental) rollout strategy.
+ * Works for boolean flags only (same restriction as percentage rollout).
+ *
+ * DESIGN PURPOSE: Time-based progressive feature enablement.
+ *
+ * Use cases:
+ *   - Scheduled rollouts: Start at midnight, increase 10% every 6 hours
+ *   - Automated canary releases: Gradual increase with monitoring windows
+ *   - Risk mitigation: Slow rollout allows catching issues early
+ *
+ * HOW IT WORKS:
+ *   1. Computes current percentage based on elapsed time (computeCurrentPercentage)
+ *   2. If current percentage is 0%, returns fallback (feature off)
+ *   3. If current percentage >= 100%, returns true (feature fully on)
+ *   4. Otherwise, uses percentage rollout logic with current percentage
+ *   5. Hash bucketing ensures same user gets consistent experience across rollout
+ *
+ * COMPARISON TO OTHER ROLLOUTS:
+ *   - Percentage: Manual, static percentage set by operator
+ *   - Gradual: Automated, percentage increases over time
+ *   - Both use same hash bucketing (same user experience guarantee)
+ *
+ * WHY BOOLEAN-ONLY?
+ *   - Same rationale as percentage rollout (semantic clarity, simpler mental model)
+ *   - "Gradual" implies "progressively enabling", not "switching between variants"
+ *   - For multi-value gradual experiments, use variant rollout with manual updates
+ *
+ * NOTE:
+ *   - User bucketing is stable: once in, always in (until rollout completes)
+ *   - Current percentage changes over time, but hash bucket stays same
+ *   - Example: User in bucket 15 sees feature at 20% rollout, keeps it at 30%, 40%, etc.
+ */
+export declare function applyGradualRollout(expectedType: ExpectedFlagType, fallbackValue: unknown, rollout: Rollout, context: EvaluationContextT, getHashPercent?: EvaluationDeps['getHashPercent']): FlagEvaluationResult;
+/**
+ * Compute the current percentage for a gradual rollout based on elapsed time.
+ *
+ * DESIGN PURPOSE: Progressive feature rollout over time.
+ *
+ * Use cases:
+ *   - Gradually enable a feature: 5% → 10% → 15% → ... → 100% (starts at first increment)
+ *   - Controlled risk mitigation: Monitor metrics at each stage before continuing
+ *   - Automated rollout schedule: Set and forget, system handles incremental increases
+ *
+ * HOW IT WORKS:
+ *   1. If start_at is in the future, returns 0% (rollout hasn't started)
+ *   2. Once started, begins at 1× increment (not 0%) so traffic is live from hour 0
+ *   3. Calculates elapsed time since start_at
+ *   4. Each completed interval_hours period adds another increment%
+ *   5. Caps at target_percentage
+ *
+ * EXAMPLE (increment 10%, interval 24h):
+ *   start_at: 2025-01-01T00:00:00Z
+ *
+ *   Day 0 (2025-01-01): 10% (just started — first increment is live)
+ *   Day 1 (2025-01-02): 20% (1 full interval completed → 2 steps)
+ *   Day 2 (2025-01-03): 30% (2 full intervals → 3 steps)
+ *   ...
+ *   Day 9 (2025-01-10): 100% (reached target)
+ *   Day 10+: 100% (capped at target)
+ *
+ * @param rollout - Gradual rollout configuration
+ * @param now - Current timestamp (dayjs object or ISO string)
+ * @returns Current percentage (0-100) based on elapsed intervals
+ */
+export declare function computeCurrentPercentage(rollout: Rollout, now?: Date | string | number): number;
+/**
+ * Apply percentage (simple rollout) strategy.
+ *
+ * DESIGN DECISION: Percentage rollout is boolean-only.
+ *
+ * This enforces a clean separation of concerns:
+ *   - Percentage Rollout (boolean-only): Progressive feature enablement
+ *     Use case: Gradually enable a feature for 0%, 10%, 50%, 100% of users
+ *     Result: true (feature on) or fallback value (feature off)
+ *
+ *   - Variant Rollout (multivariate, any type): A/B testing and experiments
+ *     Use case: Test red vs blue button, experiment with algorithm variants
+ *     Result: One of N variants based on stable hash bucketing
+ *
+ * WHY BOOLEAN-ONLY?
+ *   1. Semantic clarity: "percentage" implies "on or off", not "variant A/B/C"
+ *   2. Prevents confusion: Users won't mistakenly apply percentage to multi-value flags
+ *   3. Simpler mental model: Competition convention
+ *   4. Fails safely: If someone tries percentage on string/number/json, warns + returns fallback
+ *
+ * IMPLEMENTATION:
+ *   - bucket < percentage → true (feature enabled)
+ *   - bucket >= percentage → fallback value (usually false, feature disabled)
+ *   - Hash is stable (same user always gets same bucket on same salt)
+ *
+ * NOTE:
+ *   For non-boolean flags needing multi-value rollout, use applyVariantRollout()
+ *   Example: { variants: [{ weight: 50, value: 'blue' }, { weight: 50, value: 'red' }] }
+ */
+export declare function applyPercentageRollout(expectedType: ExpectedFlagType, fallbackValue: unknown, rollout: {
+    percentage: number;
+    salt: string;
+}, context: EvaluationContextT, getHashPercent: (input: string) => number): FlagEvaluationResult;
+/**
+ * Apply variant (multivariate) rollout.
+ * Works for ANY flag type (boolean, string, number, json).
+ *
+ * DESIGN PURPOSE: Multi-value A/B testing and experiments.
+ *
+ * Use cases:
+ *   - Button color experiment: 50% red, 50% blue
+ *   - Algorithm variant testing: 33% algorithm-a, 33% algorithm-b, 34% algorithm-c
+ *   - Configuration experiments: Different JSON payloads for different user buckets
+ *   - Non-boolean feature variants: Gradual rollout with specific values (not just on/off)
+ *
+ * HOW IT WORKS:
+ *   1. Computes stable hash bucket (0-99) for user + salt
+ *   2. Iterates through variants by weight until bucket falls into range
+ *   3. Returns matched variant's value, coerced to expected flag type
+ *
+ * WEIGHT SEMANTICS:
+ *   - Each variant has a weight (0-100+)
+ *   - Weights are cumulative: bucket 0-49 → first, 50-99 → second
+ *   - At WRITE time: validateFlagContext() enforces sum(weights) === 100
+ *   - At READ time (defensive): If sum < 100, returns fallback; if sum > 100, truncates
+ *
+ * COMPARISON TO PERCENTAGE ROLLOUT:
+ *   - Percentage: Boolean-only, simple "on or off"
+ *   - Variant: Any type, complex "which variant?"
+ *   - Use percentage for feature flags, variant for experiments
+ *
+ * NOTE:
+ *   - Hash is stable per user (same user always matches same variant)
+ *   - Salt allows independent rollouts of same flag version
+ *   - Missing key (user_id or kind+key) returns fallback with warning
+ *   - Weights validated at config save time; evaluator is defensive safety net only
+ */
+export declare function applyVariantRollout(expectedType: ExpectedFlagType, fallbackValue: unknown, rollout: Extract<Rollout, {
+    strategy: "variant";
+}>, variantById: Record<string, TVariation>, context: EvaluationContextT, getHashPercent: (input: string) => number): FlagEvaluationResult;
+export declare function defaultHash(input: string): number;
+/**
+ * Applies the appropriate rollout strategy based on rollout configuration.
+ * Centralizes rollout logic and provides better error handling.
+ *
+ * @param rollout - Rollout configuration
+ * @param expectedType - Expected flag type
+ * @param fallbackValue - Fallback value if rollout fails
+ * @param variationsById - Map of variation IDs to variations
+ * @param context - Raw evaluation context (for hashing)
+ * @param getHashPercent - Hash function
+ * @param ruleId - Rule ID for logging
+ * @returns Evaluated flag value
+ */
+export declare function applyRolloutStrategy(rollout: Rollout, expectedType: ExpectedFlagType, fallbackValue: unknown, variationsById: Record<string, TVariation>, context: EvaluationContextT, getHashPercent: (input: string) => number, ruleId?: string): FlagEvaluationResult;
+/**
+ * Evaluates a custom rule against a flattened context.
+ *
+ * IMPROVEMENTS OVER ORIGINAL:
+ *   - Supports both AND and OR logical operators (previously only AND)
+ *   - Validates conditions array before evaluation
+ *   - Consistent behavior with segment evaluation
+ *   - Better error logging
+ *
+ * Evaluation logic:
+ *   1. If conditions is empty → never matches (consistent with segments)
+ *   2. If logical_op === "OR" → matches if ANY condition passes
+ *   3. Otherwise (AND or undefined) → matches if ALL conditions pass
+ *
+ * @param rule - Custom rule with conditions and optional logical operator
+ * @param context - Flattened evaluation context
+ * @returns true if rule matches, false otherwise
+ */
+export declare function evaluateCustomRule(rule: {
+    conditions: Condition[];
+    logical_op?: LogicalOperatorType;
+    id?: string;
+}, context: FlatContext): boolean;
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * Flatten evaluation context — intentional port of FF-EU `utils/context-flatten.ts`
+ * (without observed-context hashing helpers).
+ *
+ * Keep behavior identical to FF-EU:
+ * - `addKindLabel=false`: bare keys + `custom.*`
+ * - `addKindLabel=true`: `user.key`, `organization.plan`, … (evaluate / SSE path)
+ * - Nested `custom` always flattens to bare `custom.<key>` (never `user.custom.<key>`),
+ *   matching dashboard attribute keys and FF-EU `flattenCustom`.
+ * - `kind: 'multi'` only merges `user` + `organization`. Top-level `custom` is not in
+ *   FF-EU `MultiContext` (`additionalProperties: false`) and is ignored here too.
+ */
+export declare function flattenCustom(custom: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Flatten a structured EvaluationContext (`kind` present).
+ * Returns `{}` if `kind` is missing (callers should pass SSE-flat maps through).
+ *
+ * Same contract as FF-EU `flattenContext`.
+ */
+export declare function flattenContext(ctx: Record<string, any>, addKindLabel?: boolean): Record<string, any>;
+/**
+ * SDK convenience for non-schema shapes the client may build before eval:
+ * already-flat SSE maps, or nested `{ user, organization, custom }` without `kind`.
+ *
+ * Structured `kind: user | organization | multi` delegates to `flattenContext(..., true)`
+ * (FF-EU evaluate/SSE). Do not invent multi top-level `custom` handling here.
+ */
+export declare function flattenEvaluationContext(context: Record<string, unknown> | null | undefined): Record<string, unknown>;

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

@@ -0,0 +1,21 @@
+import { ASL_KEY_AGREEMENT } from './aslEcdh';
+export type AslHandshakeSuccess = {
+    sessionId: string;
+    /** Present when ECDH completed (`configSync` handshake). */
+    configMacKey?: Uint8Array;
+    serverPublicKey?: string;
+    salt?: string;
+    keyAgreement?: typeof ASL_KEY_AGREEMENT;
+};
+export type AslHandshakeErrorCode = 'ERR_AUTH' | 'ERR_RATE_LIMITED' | 'ERR_INTERNAL' | 'ERR_HANDSHAKE';
+/**
+ * POST /auth/asl-handshake.
+ * When `withEcdh` is true, sends `clientPublicKey` and derives the config-sync MAC key.
+ */
+export declare function performAslHandshake(input: {
+    handshakeUrl: string;
+    apiKey: string;
+    withEcdh?: boolean;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<AslHandshakeSuccess>;

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

@@ -0,0 +1,13 @@
+export { ASL_CLIENT_PUBLIC_KEY_HEX_LENGTH, ASL_HKDF_INFO, ASL_KEY_AGREEMENT, deriveAslMacKey, generateAslClientKeyPair, parsePeerPublicKeyHex, parseSaltHex, wipeKeyMaterial, } from './aslEcdh';
+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 { performAslHandshake } from './handshake';
+export type { AslHandshakeSuccess } from './handshake';
+export { evaluateSdkFlag, evaluateAllSdkFlags, coerceType, prepareContextForEvaluator, mapToRecord, } from './evaluateSdkFlag';
+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';
+export { stringHash, hashPercent } from './stringHash';