flagmint-js-sdk 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 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';

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

@@ -1,7 +1,6 @@
 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';
 type TransportMode = 'auto' | 'long-polling' | 'sse';
 export interface FlagClientOptions<C extends Record<string, any> = Record<string, any>> {
     apiKey: string;
@@ -30,8 +29,6 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
     cacheAdapter?: CacheAdapter<C>;
     restEndpoint?: string;
     sseEndpoint?: string;
-    /** Override the ASL handshake URL. Use with `sseEndpoint` for self-hosted gateways. */
-    handshakeEndpoint?: string;
     debugLog?: boolean;
     env?: string;
     enableFlagmint: boolean;
@@ -40,22 +37,6 @@ 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>> {
@@ -68,13 +49,8 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private cacheTTL;
     private transport;
     private restEndpoint;
-    private eventsEndpoint;
     private aslHandshakeUrl;
     private sseEndpoint;
-    private eventQueue;
-    private eventFlushTimer;
-    /** null = server has not sent a map yet; send and let ingest drop. */
-    private analyticsByFlag;
     private readyPromise;
     private resolveReady;
     private rejectReady;
@@ -88,8 +64,6 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private initializationOptions?;
     private isInitialized;
     private subscribers;
-    private shareHub;
-    private shareConnection;
     /**
      * Creates a new FlagClient instance.
      * @param options - Configuration options for the client.
@@ -99,14 +73,8 @@ 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 flags
+   * 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
@@ -157,23 +125,6 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      * Get a single flag value.
      */
     getFlag<K extends keyof FeatureFlags<T>>(key: K, fallback?: FeatureFlags<T>[K]): FeatureFlags<T>[K];
-    /**
-     * 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.
      */
@@ -229,9 +180,6 @@ 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;
     /**
      * Performs the initial authentication handshake with the Flagmint server
      * to obtain a fresh, single-use session identifier.

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';

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

@@ -0,0 +1,56 @@
+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;
+    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 };