flagmint-js-sdk 2.0.0 → 2.2.1

package/dist/index.d.ts

@@ -12,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, stringHash, hashPercent, } from './sdk/core/config-sync';
+export type { SdkFlagConfig, SdkSegment, RulesState, RulesCacheSnapshot, ConfigSyncPayload, LeasePayload, FullConfigPayload, DeltaConfigPayload, DeltasCatchUpPayload, ApplyResult, AslHandshakeSuccess, } from './sdk/core/config-sync';

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

@@ -2,6 +2,7 @@ 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;
@@ -10,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.
@@ -29,8 +38,18 @@ 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;
-    /** Override the ASL handshake URL. Use with `sseEndpoint` for self-hosted gateways. */
+    /**
+     * 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;
@@ -71,10 +90,16 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     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;
@@ -90,6 +115,10 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     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.
@@ -151,12 +180,18 @@ 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.
@@ -176,6 +211,7 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     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>;
     /**
@@ -191,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
@@ -201,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>;
     /**
@@ -232,6 +267,15 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     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.
@@ -253,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/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';