@featureflip/edge 0.0.0-stage → 2.14.0

package/dist/js-sdk/src/core/evaluator.d.ts

@@ -0,0 +1,37 @@
+import { ConditionDto, ConditionGroupDto, ConditionLogic, EvaluationContext, EvaluationDetail, FlagDto, ServeConfigDto, SegmentDto } from './types.js';
+export declare const MAX_PREREQUISITE_DEPTH = 10;
+/**
+ * Compute deterministic bucket (0-99) for a value.
+ * Uses MD5 hashing for consistency with Python and C# SDKs.
+ * Formula: readUInt32LE(md5(salt:value).slice(0, 4)) % 100
+ */
+export declare function computeBucket(salt: string, value: string, md5: (input: string) => Uint8Array): number;
+declare function evaluateCondition(condition: ConditionDto, context: EvaluationContext): boolean;
+declare function evaluateConditions(conditions: ConditionDto[], logic: ConditionLogic, context: EvaluationContext): boolean;
+declare function evaluateConditionGroups(groups: ConditionGroupDto[], context: EvaluationContext): boolean;
+declare function resolveServe(serve: ServeConfigDto, context: EvaluationContext, md5: (input: string) => Uint8Array): string;
+export interface EvaluatorDeps {
+    md5: (input: string) => Uint8Array;
+    getSegment?: (key: string) => SegmentDto | undefined;
+}
+/**
+ * Evaluate a flag against a context. Pure function, no I/O.
+ *
+ * @param flag      The flag to evaluate.
+ * @param context   The evaluation context.
+ * @param deps      Evaluator dependencies (md5, getSegment).
+ * @param allFlags  Map of all flags in the environment, keyed by flag key.
+ *                  Required for prerequisite resolution; pass `{}` if the flag
+ *                  has no prerequisites.
+ */
+export declare function evaluate(flag: FlagDto, context: EvaluationContext, deps: EvaluatorDeps, allFlags?: Record<string, FlagDto>): EvaluationDetail;
+/**
+ * Evaluate a flag, sharing a memoisation map with other concurrent
+ * evaluations (e.g. a batch "evaluate all" pass).
+ *
+ * Use this when evaluating multiple flags in one sweep so that shared
+ * prerequisite flags are only evaluated once.
+ */
+export declare function evaluateWithSharedMemo(flag: FlagDto, context: EvaluationContext, deps: EvaluatorDeps, allFlags: Record<string, FlagDto>, memo: Map<string, EvaluationDetail>): EvaluationDetail;
+export { evaluateCondition, evaluateConditions, evaluateConditionGroups, resolveServe, };
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/js-sdk/src/core/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,OAAO,EACP,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,sBAAsB,KAAK,CAAC;AASzC;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,GACjC,MAAM,CAUR;AAokBD,iBAAS,iBAAiB,CACxB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAkDT;AAED,iBAAS,kBAAkB,CACzB,UAAU,EAAE,YAAY,EAAE,EAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAOT;AAED,iBAAS,uBAAuB,CAC9B,MAAM,EAAE,iBAAiB,EAAE,EAC3B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAOT;AAED,iBAAS,YAAY,CACnB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,GACjC,MAAM,CA6CR;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,CAAC;IACnC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,aAAa,EACnB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,gBAAgB,CAGlB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAClC,gBAAgB,CAElB;AA6ID,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,GACb,CAAC"}

package/dist/js-sdk/src/core/events.d.ts

@@ -0,0 +1,77 @@
+import { SdkEventDto, RecordEventsRequest } from './types.js';
+export interface EventSender {
+    sendEvents(request: RecordEventsRequest): Promise<void>;
+}
+/**
+ * Upper bound on buffered events.
+ *
+ * Only reachable once the events endpoint fails for long enough that re-queued
+ * batches pile up. Past the bound the OLDEST events are shed, which caps memory
+ * and keeps the freshest analytics — and means a long outage sheds the stale
+ * re-queued batches rather than starving new events.
+ */
+export declare const DEFAULT_MAX_QUEUE_SIZE = 10000;
+/**
+ * Raised when the events endpoint answers with a non-success status.
+ *
+ * `fetch` does not reject on an HTTP error status, so without an explicit check
+ * a 503 was indistinguishable from success and the batch was discarded as
+ * "sent" — no log, no counter, nothing (#2456).
+ */
+export declare class EventSendError extends Error {
+    readonly status: number;
+    constructor(status: number);
+    /**
+     * Whether the same batch could succeed if sent again: any 5xx (the production
+     * edge answers this endpoint with a 503 at a low constant rate) and 429, where
+     * the server is explicitly asking the caller to come back later.
+     */
+    get retryable(): boolean;
+}
+export declare class EventProcessor {
+    private readonly sender;
+    private readonly flushInterval;
+    private readonly options;
+    private queue;
+    private flushTimer;
+    private closed;
+    private flushPromise;
+    private readonly flushBatchSize;
+    private readonly maxQueueSize;
+    /**
+     * Epoch ms before which the batch-size trigger must not start another flush.
+     *
+     * A re-queued batch leaves the queue at or above `flushBatchSize`, so without this
+     * gate every subsequent `enqueue` would start another flush — turning a failing
+     * endpoint into one request per event, which is worse for the server than the
+     * dropping it replaces. The interval timer is the retry vehicle; this only
+     * suppresses the size trigger between its ticks. (Concurrent starts are already
+     * coalesced by `flushPromise`; this handles the gap AFTER a failed flush settles.)
+     */
+    private nextAutoFlushAt;
+    /**
+     * @param options.flushOnFullBatch Default true: `enqueue` starts a flush once a
+     *   batch is full. A host where only an awaited or `waitUntil`-held promise is
+     *   guaranteed to finish (the edge SDK) turns it off, so no send is ever
+     *   started that nobody waits on; its explicit `flush()` still sends in
+     *   batches of `flushBatchSize`.
+     * @param options.maxBatchesPerFlush Default unlimited: one `flush()` drains the
+     *   queue. A host with a per-invocation subrequest budget (the edge SDK) caps
+     *   the POSTs one flush may make; whatever is left waits for a later flush.
+     */
+    constructor(sender: EventSender, flushInterval: number, flushBatchSize: number, maxQueueSize?: number, options?: {
+        flushOnFullBatch?: boolean;
+        maxBatchesPerFlush?: number;
+    });
+    /** Events waiting to be sent, not counting a batch currently in flight. */
+    get size(): number;
+    start(): void;
+    enqueue(event: SdkEventDto): void;
+    flush(): Promise<void>;
+    /** Returns a batch that failed to send to the front of the queue. */
+    private requeue;
+    /** Sheds oldest-first until the queue fits the bound. */
+    private trimToBound;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/js-sdk/src/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;IAKnC;;;;OAIG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAsCD,qBAAa,cAAc;IAgCvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAG9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAnC1B,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe,CAAK;IAE5B;;;;;;;;;OASG;gBAEgB,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,MAAM,EACtC,cAAc,EAAE,MAAM,EACtB,YAAY,GAAE,MAA+B,EAC5B,OAAO,GAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAO;IAU5F,2EAA2E;IAC3E,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAa3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC5B,qEAAqE;IACrE,OAAO,CAAC,OAAO;IAOf,yDAAyD;IACzD,OAAO,CAAC,WAAW;IASb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAY7B"}

package/dist/js-sdk/src/core/identity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The token every request carries so the Evaluation API can count SDK usage by
+ * name and version (#4144, contract in #4138). The version is inlined from
+ * package.json at build time (see globals.d.ts), never written here (#2141).
+ */
+export declare const SDK_TOKEN: string;
+/**
+ * The SDK token followed by each wrapper token, in order. A wrapper that is not a
+ * valid product token is dropped with a warning: identity metadata must never stop
+ * the client starting. Filtered defensively because JS callers bypass the types.
+ */
+export declare function buildIdentity(wrappers: readonly unknown[] | undefined): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/js-sdk/src/core/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/identity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAsC,CAAC;AAK7D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,MAAM,CAY9E"}

package/dist/js-sdk/src/core/resolve-detail.d.ts

@@ -0,0 +1,42 @@
+import { EvaluationContext, EvaluationDetail, FlagDto, SegmentDto } from './types.js';
+/**
+ * The runtime type a typed accessor requires of the value a flag serves, as
+ * reported by `typeof`. Used to detect a type-mismatched read (#2281), which
+ * TypeScript cannot catch on its own: its type parameters are erased, so
+ * `boolVariation` would otherwise hand back whatever the flag actually served.
+ */
+export type ExpectedValueType = 'boolean' | 'string' | 'number';
+/** What `resolveDetail` needs from its host: hashing, segment lookup, an error hook. */
+export interface ResolveDeps {
+    md5(input: string): Uint8Array;
+    getSegment(key: string): SegmentDto | undefined;
+    /**
+     * Told about an evaluation that threw, before it degrades to the default with
+     * reason `Error`. Optional: the JS core has never surfaced these and does not
+     * pass it; the edge SDK logs them.
+     */
+    onError?(err: unknown): void;
+}
+/**
+ * Turn a flag lookup into the `EvaluationDetail` a variation call returns: the
+ * evaluator's result plus every degradation the SDK applies on top of it. Pure,
+ * never throws, records nothing — the caller owns analytics and inspectors.
+ *
+ * Shared by `SharedFeatureflipCore.variationDetail` and `@featureflip/edge`, so
+ * the two cannot drift on what a missing flag, a malformed config or a
+ * type-mismatched read resolves to.
+ *
+ * @internal Not exported from any public entry point.
+ *
+ * @param expected The `typeof` result the caller's typed accessor requires, or
+ *   undefined for the generic/JSON accessors. Those take no runtime type — a
+ *   TypeScript type parameter is erased — so there is nothing to check them
+ *   against and they are left unchecked.
+ * @param allFlags Every flag, for prerequisite lookups, or a function returning
+ *   them. A function is called inside the guard, so a store that throws while
+ *   building the map degrades to `Error` like any other evaluation failure.
+ * @param memo A memo shared across a batch of evaluations (e.g. a bootstrap
+ *   sweep) so shared prerequisites are evaluated once. Omit for a single read.
+ */
+export declare function resolveDetail<T>(flag: FlagDto | undefined, context: EvaluationContext, defaultValue: T, deps: ResolveDeps, allFlags: Record<string, FlagDto> | (() => Record<string, FlagDto>), expected?: ExpectedValueType, memo?: Map<string, EvaluationDetail>): EvaluationDetail<T>;
+//# sourceMappingURL=resolve-detail.d.ts.map

package/dist/js-sdk/src/core/resolve-detail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-detail.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/resolve-detail.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAEhB,OAAO,EACP,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhE,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;IAC/B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,CAAC,EACf,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnE,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACnC,gBAAgB,CAAC,CAAC,CAAC,CAqDrB"}

package/dist/js-sdk/src/core/shared-core.d.ts

@@ -0,0 +1,170 @@
+import { FeatureflipConfig, ResolvedConfig } from '../config.js';
+import { ExpectedValueType } from './resolve-detail.js';
+import { EvaluationContext, EvaluationDetail, FlagDto, FlagUpdateListener } from './types.js';
+import { Platform } from '../platform/types.js';
+/**
+ * Resolve the built-in user id for an analytics event from either the
+ * canonical `user_id` field or its `userId` camelCase alias — mirroring the
+ * two-way alias the evaluator applies for rollout bucketing. Without this the
+ * event's `userId` is silently null whenever a caller passes a `userId`-keyed
+ * context (a documented-valid shape), leaving analytics unattributed.
+ */
+export declare function resolveEventUserId(context: EvaluationContext): string | undefined;
+export type { ExpectedValueType } from './resolve-detail.js';
+/**
+ * Internal shared core owning all expensive resources of a FeatureflipClient:
+ * platform, HTTP fetches, event processor, SSE connection, polling timer.
+ *
+ * Refcounted: multiple FeatureflipClient handles can share one core, and the
+ * real shutdown runs only when the last handle is disposed. Constructed either
+ * by the static factory in `client.ts` or directly by `createForTesting`.
+ *
+ * JS is single-threaded, so the refcount is a plain number — no atomic
+ * primitives or locking required.
+ *
+ * @internal
+ */
+export declare class SharedFeatureflipCore {
+    readonly config: ResolvedConfig;
+    private readonly store;
+    private readonly events;
+    private readonly platform;
+    private readonly inspectors;
+    /** `featureflip-js/<version>` plus wrapper tokens, built once (#4144). */
+    private readonly identity;
+    private readonly updateListeners;
+    private initialized;
+    private initPromise;
+    private eventSource;
+    private pollTimer;
+    private closed;
+    private streamRetryCount;
+    private streamRetryTimer;
+    /**
+     * True between arming the polling fallback and the next delivered `sync`. Gates
+     * the reap so a poller the caller configured (`streaming: false`) is never
+     * mistaken for one this SDK armed to cover an outage.
+     */
+    private pollingIsStreamFallback;
+    /** Number of outstanding handles (including the one returned by the factory). */
+    private refCount;
+    /** Set by the factory after inserting into the owning map so Shutdown can remove itself. */
+    private owningMap;
+    private owningKey;
+    constructor(config: FeatureflipConfig, platform: Platform);
+    /**
+     * Test-only constructor. Bypasses network: accepts pre-populated flag DTOs
+     * and marks the core as initialized. Used by FeatureflipClient.forTesting.
+     */
+    static createForTesting(flags: FlagDto[]): SharedFeatureflipCore;
+    /** Ref count for diagnostics (test-only). */
+    get debugRefCount(): number;
+    /** Whether the core's shared shutdown has already run (refcount reached zero). */
+    get isShutDown(): boolean;
+    get isInitialized(): boolean;
+    /**
+     * Atomically increments the refcount if the core is still alive.
+     * Returns false if the core has already shut down — caller must construct a new one.
+     */
+    tryAcquire(): boolean;
+    /**
+     * Decrements the refcount. When it reaches zero, runs the real shutdown
+     * exactly once. Over-release is a no-op — the guard prevents re-entry.
+     */
+    release(): Promise<void>;
+    /**
+     * Called by the factory after successfully inserting this core into the
+     * owning map so Shutdown can remove itself from the map.
+     */
+    setOwningMap(map: Map<string, SharedFeatureflipCore>, key: string): void;
+    /**
+     * Subscribe to flag-configuration updates. Returns an unsubscribe function.
+     * Listeners live on the shared core, so they fire for updates regardless of
+     * which handle triggered them; handles remove their own on close.
+     */
+    onUpdate(listener: FlagUpdateListener): () => void;
+    offUpdate(listener: FlagUpdateListener): void;
+    /**
+     * Fire the registered update listeners. A throwing listener is isolated: it
+     * neither breaks the data-source callback nor stops the remaining listeners.
+     */
+    private notifyUpdateListeners;
+    /** Wait for the core to finish loading initial flag data. */
+    waitForInitialization(): Promise<void>;
+    /**
+     * @param expected The `typeof` result the caller's typed accessor requires, or
+     *   undefined for the generic/JSON accessors. Those take no runtime type — a
+     *   TypeScript type parameter is erased — so there is nothing to check them
+     *   against and they are left unchecked.
+     */
+    variationDetail<T>(key: string, context: EvaluationContext, defaultValue: T, expected?: ExpectedValueType): EvaluationDetail<T>;
+    evaluateFlag<T>(key: string, context: EvaluationContext, defaultValue: T, expected?: ExpectedValueType): T;
+    track(eventKey: string, context: EvaluationContext, metadata?: Record<string, unknown>): void;
+    identify(context: EvaluationContext): void;
+    flush(): Promise<void>;
+    /**
+     * Runs the real shutdown exactly once. Closes the SSE connection, clears
+     * timers, flushes events, and removes the entry from the owning map.
+     * Safe to call more than once — subsequent calls are no-ops.
+     */
+    private shutdown;
+    private initialize;
+    private fetchFlags;
+    /**
+     * Apply a validated snapshot, minus any entity carrying an enum value this build
+     * cannot evaluate (#2402).
+     *
+     * Split from the two call sites rather than inlined at each so polling and streaming
+     * cannot drift — treating the two transports as one payload shape is exactly what
+     * #2279 taught, and a guard applied to only one of them is the same bug with a
+     * narrower trigger.
+     */
+    private applySnapshot;
+    private startDataSource;
+    private startStreaming;
+    /**
+     * Capped exponential reconnect backoff, jittered to [d/2, d] at every level.
+     *
+     * The jitter is load-bearing on the FIRST reconnect, not only the escalating
+     * ones: these drops are fleet-wide — one edge event severs every stream at once
+     * (#2457) — so every client re-enters here at the same failure count together,
+     * and a constant there republishes the drop's own synchronisation as a reconnect
+     * spike one delay later (#2508). Unbounded retrying (#3071) makes that permanent
+     * rather than one-off, which is why this SDK can no longer be the fleet's one
+     * un-jittered backoff. The band's lower bound is strictly positive, so a clean
+     * sever still cannot busy-loop.
+     */
+    private streamReconnectDelay;
+    /**
+     * Retires a polling fallback armed to cover an SSE outage, leaving a poller the
+     * caller asked for (`streaming: false`) alone.
+     */
+    private stopStreamFallbackPolling;
+    private startPolling;
+    /**
+     * Emit a diagnostic for a wire-contract violation, and only for that.
+     *
+     * Network and JSON-syntax failures are deliberately left silent: they self-heal on
+     * the next poll or reconnect, and warning on each would flood the console of any
+     * client that is briefly offline. A MalformedPayloadError means the server and SDK
+     * disagree about the shape of the data — that never self-heals and must be visible
+     * ("never swallow silently", packages/CLAUDE.md).
+     */
+    private warnIfMalformed;
+    private fetchSingleFlag;
+    /**
+     * Fire the registered evaluation inspectors. Called once per variation call
+     * on every exit path of variationDetail. A throwing inspector is isolated:
+     * it neither breaks evaluation nor stops the remaining inspectors.
+     */
+    private notifyInspectors;
+    private recordEvaluation;
+    private headers;
+}
+/**
+ * Structural comparison of resolved configs. Used to warn when a later
+ * `get()` call passes options that meaningfully differ from the cached
+ * instance's options. sdkKey is excluded (it's the cache key itself).
+ */
+export declare function resolvedConfigsEqual(a: ResolvedConfig, b: ResolvedConfig): boolean;
+//# sourceMappingURL=shared-core.d.ts.map

package/dist/js-sdk/src/core/shared-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-core.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/shared-core.ts"],"names":[],"mappings":"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"}

package/dist/js-sdk/src/core/store.d.ts

@@ -0,0 +1,94 @@
+import { FlagDto, SegmentDto } from './types.js';
+/**
+ * Called with the keys of every flag affected by a single store mutation.
+ * Batched: one call per mutation, not one per key, so a poll that changes 40
+ * flags notifies once. Never called with an empty array.
+ */
+export type FlagChangeListener = (keys: string[]) => void;
+export declare class FlagStore {
+    private flags;
+    private segments;
+    private listeners;
+    private version;
+    /**
+     * Whether a snapshot has been loaded. The first `init` establishes the
+     * baseline rather than reporting every flag as changed — a cold load is not
+     * a configuration change.
+     */
+    private hasSnapshot;
+    getFlag(key: string): FlagDto | undefined;
+    getSegment(key: string): SegmentDto | undefined;
+    getAllFlags(): FlagDto[];
+    getVersion(): number;
+    /**
+     * Replace the whole snapshot. Used by the initial fetch, every poll tick, and
+     * the SSE `sync` event, so it diffs against the previous snapshot and reports
+     * only what actually changed — notifying every flag on every poll would make
+     * the public update hook useless.
+     */
+    init(flags: FlagDto[], segments: SegmentDto[], version: number): void;
+    /**
+     * Apply a single flag delta (SSE `flag.created` / `flag.updated`).
+     *
+     * Rejects only a *strictly older* config. Equal versions must be applied:
+     * the wire version is second-granular, so two edits to one flag inside the
+     * same wall-clock second carry an identical version, and treating equal as
+     * stale discarded the second edit outright. With streaming on (the default)
+     * polling is disabled, so no later snapshot corrected it and the store
+     * evaluated against the pre-edit config until an SSE `sync` or reconnect.
+     *
+     * Re-applying an identical config is harmless; dropping a real one is not.
+     */
+    upsert(flag: FlagDto): void;
+    delete(key: string): void;
+    /**
+     * `key` plus every flag transitively depending on it via a prerequisite.
+     *
+     * The single-key delta paths (SSE `flag.created` / `flag.updated` /
+     * `flag.deleted`) need the same fan-out as a full snapshot diff: the event
+     * names one flag, but each of its dependents changes evaluated value too.
+     *
+     * Reads the post-mutation store, so an upserted flag is included, and a
+     * deleted flag's dependents — which still carry the now-dangling
+     * prerequisite row — remain reachable.
+     */
+    private withPrerequisiteDependents;
+    onChange(listener: FlagChangeListener): () => void;
+    /**
+     * Keys of the flags affected by replacing the current snapshot with the given
+     * one. A flag counts as affected when it is added, removed, its own config
+     * changed, one of the segments its rules reference changed, or one of the
+     * flags it names as a prerequisite changed — the latter two alter evaluation
+     * outcomes without touching the flag's own config, so without them an SSE
+     * `segment.updated` (which refetches the whole snapshot) would report nothing
+     * and a toggled prerequisite would never reach its dependents.
+     *
+     * Compares config content, not `version`. The wire version is deliberately
+     * second-granular — eval-api divides its internal epoch-millisecond version
+     * by 1000 because published SDKs declare 32-bit version fields — so it is not
+     * a sufficient change signal here. Two edits to one flag inside the same
+     * wall-clock second carry an identical version, and if a snapshot boundary
+     * falls between them the later config lands in the store while a version-only
+     * diff reports nothing changed, leaving a consumer that caches per key stale
+     * until the next unrelated edit (#2088). `upsert` has no such problem — an SSE
+     * delta is its own signal — so only full snapshots need this.
+     *
+     * Serializing covers every field automatically, so a field added to a DTO is
+     * included without anyone remembering to extend a comparison. Bounded by one
+     * pass over a snapshot the caller just parsed off the wire.
+     *
+     * It is key-order sensitive. Snapshot-to-snapshot that is safe — both sides
+     * come from the same batch endpoint. It is *not* guaranteed when `previous`
+     * was written by `upsert` from the single-flag endpoint, which could order or
+     * project its keys differently; the first poll after a delta would then report
+     * that key as changed. Harmless and self-limiting — the map is replaced with
+     * the batch DTO, so it cannot repeat — and it fails toward a redundant
+     * notification rather than a missed one, which is the direction this whole
+     * diff is trying to protect.
+     *
+     * Must be called before the maps are replaced.
+     */
+    private diffSnapshot;
+    private notifyListeners;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/js-sdk/src/core/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAE1D,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,OAAO,CAAK;IAEpB;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,WAAW,IAAI,OAAO,EAAE;IAIxB,UAAU,IAAI,MAAM;IAIpB;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IA2BrE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAS3B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAMlC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAQlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,YAAY;IAsDpB,OAAO,CAAC,eAAe;CASxB"}

package/dist/js-sdk/src/core/types.d.ts

@@ -0,0 +1,128 @@
+export type FlagType = 'Boolean' | 'String' | 'Number' | 'Json';
+export type ServeType = 'Fixed' | 'Rollout';
+export type ConditionLogic = 'And' | 'Or';
+export type SdkEventType = 'Evaluation' | 'Impression' | 'Identify' | 'Custom';
+export type EvaluationReason = 'RuleMatch' | 'Fallthrough' | 'FlagDisabled' | 'FlagNotFound' | 'PrerequisiteFailed' | 'Error';
+export type ConditionOperator = 'Equals' | 'NotEquals' | 'In' | 'NotIn' | 'Contains' | 'NotContains' | 'StartsWith' | 'EndsWith' | 'MatchesRegex' | 'GreaterThan' | 'GreaterThanOrEqual' | 'LessThan' | 'LessThanOrEqual' | 'Before' | 'After' | 'SemverEquals' | 'SemverGreaterThan' | 'SemverGreaterThanOrEqual' | 'SemverLessThan' | 'SemverLessThanOrEqual';
+export interface VariationDto {
+    key: string;
+    value: unknown;
+}
+export interface ConditionDto {
+    attribute: string;
+    operator: ConditionOperator;
+    values: string[];
+    negate: boolean;
+}
+export interface WeightedVariationDto {
+    key: string;
+    weight: number;
+}
+export interface ServeConfigDto {
+    type: ServeType;
+    variation?: string;
+    bucketBy?: string;
+    salt?: string;
+    variations?: WeightedVariationDto[];
+}
+export interface ConditionGroupDto {
+    operator: ConditionLogic;
+    conditions: ConditionDto[];
+}
+export interface RuleDto {
+    id: string;
+    priority: number;
+    conditionGroups: ConditionGroupDto[];
+    serve: ServeConfigDto;
+    segmentKey?: string;
+}
+export interface Prerequisite {
+    prerequisiteFlagKey: string;
+    expectedVariationKey: string;
+}
+export interface FlagDto {
+    key: string;
+    version: number;
+    type: FlagType;
+    enabled: boolean;
+    variations: VariationDto[];
+    rules: RuleDto[];
+    fallthrough: ServeConfigDto;
+    offVariation: string;
+    prerequisites?: Prerequisite[];
+    /**
+     * Whether the flag may be exposed to client-side code. Absent on payloads from
+     * servers that predate the field; treat absent as not visible.
+     */
+    clientSideVisible?: boolean;
+}
+export interface SegmentDto {
+    key: string;
+    version: number;
+    conditions: ConditionDto[];
+    conditionLogic: ConditionLogic;
+}
+export interface GetFlagsResponse {
+    environment: string;
+    version: number;
+    flags: FlagDto[];
+    segments: SegmentDto[];
+}
+export interface EvaluationDetail<T = unknown> {
+    value: T;
+    variationKey?: string;
+    reason: EvaluationReason;
+    ruleId?: string;
+    prerequisiteKey?: string;
+}
+export type EvaluationContext = Record<string, unknown>;
+/**
+ * The object passed to each registered evaluation inspector. Fired once per
+ * variation call, synchronously, during evaluation. `context` is a shallow copy
+ * of the caller's context — treat it as read-only. Optional fields are set only
+ * for their corresponding reason (`ruleId` on `RuleMatch`, `prerequisiteKey` on
+ * `PrerequisiteFailed`).
+ */
+export interface EvaluationEvent {
+    flagKey: string;
+    context: EvaluationContext;
+    value: unknown;
+    variationKey?: string;
+    reason: EvaluationReason;
+    ruleId?: string;
+    prerequisiteKey?: string;
+    timestamp: string;
+}
+/** An in-process observer invoked on every flag evaluation. Return value ignored. */
+export type EvaluationInspector = (event: EvaluationEvent) => void;
+/** Events a client can be subscribed to via `on`/`off`. */
+export type FeatureflipEvent = 'update';
+/**
+ * Called when flag configuration changes after the initial load, with the keys
+ * of the affected flags. Batched: one call per update, however many flags it
+ * touched. Never called with an empty array, and never for the initial load.
+ *
+ * A flag is reported when it is added, removed, its definition changed, or a
+ * segment its rules reference changed. Return value ignored.
+ */
+export type FlagUpdateListener = (keys: string[]) => void;
+export interface SdkEventDto {
+    type: SdkEventType;
+    flagKey: string;
+    userId?: string;
+    variation?: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+    prerequisiteKey?: string;
+}
+export interface RecordEventsRequest {
+    events: SdkEventDto[];
+}
+export interface StreamFlagUpdatedEvent {
+    key: string;
+    version: number;
+}
+export interface StreamPingEvent {
+    timestamp: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/js-sdk/src/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/js-sdk/src/core/unevaluable.d.ts

@@ -0,0 +1,28 @@
+import { FlagDto, GetFlagsResponse, SegmentDto } from './types.js';
+/**
+ * Why this flag cannot be evaluated, or `null` if it can.
+ *
+ * Returns a human-readable reason rather than a boolean so the caller's diagnostic can
+ * name the field and the value actually received — the one detail an operator
+ * debugging a vanished flag needs.
+ */
+export declare function unevaluableFlagReason(flag: FlagDto): string | null;
+/** Why this segment cannot be evaluated, or `null` if it can. */
+export declare function unevaluableSegmentReason(segment: SegmentDto): string | null;
+export interface DroppedEntity {
+    kind: 'flag' | 'segment';
+    key: string;
+    reason: string;
+}
+export interface FilteredSnapshot {
+    flags: FlagDto[];
+    segments: SegmentDto[];
+    dropped: DroppedEntity[];
+}
+/**
+ * Split a validated snapshot into the entities this SDK can evaluate and the ones it
+ * cannot. Never throws: an unknown enum name is a forward-compatibility event, not a
+ * contract violation, and the healthy remainder must still apply.
+ */
+export declare function dropUnevaluableEntities(data: GetFlagsResponse): FilteredSnapshot;
+//# sourceMappingURL=unevaluable.d.ts.map

package/dist/js-sdk/src/core/unevaluable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unevaluable.d.ts","sourceRoot":"","sources":["../../../../../js-sdk/src/core/unevaluable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAChB,UAAU,EAEX,MAAM,YAAY,CAAC;AAqDpB;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBlE;AAED,iEAAiE;AACjE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAK3E;AASD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAgBhF"}