@omniretail/omniflags-core 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# @omniretail/omniflags-core
+
+JavaScript/TypeScript SDK for OmniFlags.
+
+## Installation
+
+```bash
+npm install @omniretail/omniflags-core
+```
+
+## Quick start
+
+```ts
+import { OmniFlagsClient } from "@omniretail/omniflags-core";
+
+const client = new OmniFlagsClient({ sdkKey: "your-sdk-key" });
+
+await client.waitForReady();
+
+const enabled = client.isEnabled("store.dark-mode");
+const theme   = client.getString("store.theme", "light");
+```
+
+## Configuration
+
+```ts
+const client = new OmniFlagsClient({
+  sdkKey: "your-sdk-key",   // required
+  hooks:  [loggingHook],    // optional evaluation hooks
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `sdkKey` | `string` | **Required.** SDK key from the OmniFlags dashboard. |
+| `hooks` | `Hook[]` | Lifecycle hooks called before/after each evaluation. |
+
+## Evaluation
+
+Flag keys are namespaced by project: `{projectKey}.{flagKey}`.
+
+```ts
+// Boolean
+client.isEnabled("store.show-banner");
+client.isEnabled("store.show-banner", { customerId: "cust-123" }); // with context
+
+// Typed value methods
+client.getBoolean("store.dark-mode", false);
+client.getString("store.theme", "light");
+client.getNumber("store.max-items", 10);
+
+// Generic — useful when the type is only known at runtime
+client.getValue<{ color: string }>("store.config", defaultConfig);
+
+// Full evaluation result (variant, reason, rule matched)
+const result = client.getVariant("store.show-banner");
+// result.value, result.variant, result.reason, result.ruleId, result.errorCode
+```
+
+## Context
+
+Pass context per evaluation call — customer, business, branch, country, etc. There is no persistent context state on the client.
+
+```ts
+const ctx = {
+  customerId:       request.customerId,
+  agentId:          request.agentId,
+  businessId:       request.businessId,
+  businessBranchId: request.businessBranchId,
+};
+
+client.isEnabled("store.show-banner", ctx);
+client.getString("store.theme", "light", ctx);
+```
+
+## Loading state
+
+```ts
+const state = client.loadingState;
+// state.isFetching  — a network request is in flight
+// state.isLoading   — no flags have been loaded yet (first fetch pending)
+// state.origin      — "NONE" | "CACHE" | "SERVER"
+// state.error       — last fetch error, or null
+```
+
+Subscribe to changes:
+
+```ts
+const unsub = client.on("PROVIDER_LOADING_STATE_CHANGED", () => {
+  console.log(client.loadingState);
+});
+
+unsub(); // remove the listener
+```
+
+## Status & lifecycle
+
+```ts
+client.status;               // "not_ready" | "ready" | "stale" | "error"
+await client.waitForReady(); // resolves after the first fetch or cache hit
+await client.shutdown();     // stop polling and flush metrics
+```
+
+The SDK polls for flag updates automatically on a server-driven interval (default: 5 minutes).
+
+## Events
+
+```ts
+const unsub = client.on("PROVIDER_CONFIGURATION_CHANGED", () => {
+  // flags updated
+});
+
+unsub(); // remove the listener
+```
+
+| Event | When |
+|-------|------|
+| `PROVIDER_READY` | First snapshot loaded |
+| `PROVIDER_STALE` | Fetch failed but cached flags are available |
+| `PROVIDER_ERROR` | Fetch failed and no cache |
+| `PROVIDER_CONFIGURATION_CHANGED` | Flags updated by a background poll |
+| `PROVIDER_LOADING_STATE_CHANGED` | Loading state changed |
+
+## Hooks
+
+```ts
+import type { Hook } from "@omniretail/omniflags-core";
+
+const loggingHook: Hook = {
+  after(flagKey, result) {
+    console.log(`[flag] ${flagKey} → ${result.variant} (${result.reason})`);
+  },
+};
+
+const client = new OmniFlagsClient({ sdkKey: "your-sdk-key", hooks: [loggingHook] });
+
+// Or add after construction
+client.addHook(loggingHook);
+```
+
+## Metrics
+
+Flag evaluations are tracked and flushed to OmniFlags automatically. The flush interval and batch size are driven by the server — no configuration needed.

package/dist/bucket.d.ts

@@ -0,0 +1,23 @@
+/**
+ * FNV-1a (32-bit) deterministic bucketing.
+ *
+ * Canonical input: `{flagKey}|{environmentKey}|{targetingKey}|{salt}`
+ * Result range: [1, 100_000]
+ */
+/** Compute FNV-1a 32-bit hash of a UTF-8 string */
+export declare function fnv1a32(input: string): number;
+/**
+ * Compute the deterministic bucket for a flag + targeting key combination.
+ * @returns bucket in range [1, 100_000]
+ * @throws BucketError with code MISSING_TARGETING_KEY if targetingKey is empty
+ */
+export declare function computeBucket(flagKey: string, environmentKey: string, targetingKey: string, salt?: string): number;
+/** Resolve rollout variant from bucket value and weighted partitions */
+export declare function resolveRolloutVariant(bucket: number, rollout: {
+    variant: string;
+    weight: number;
+}[]): string;
+export declare class BucketError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}

package/dist/bucket.js

@@ -0,0 +1,50 @@
+/**
+ * FNV-1a (32-bit) deterministic bucketing.
+ *
+ * Canonical input: `{flagKey}|{environmentKey}|{targetingKey}|{salt}`
+ * Result range: [1, 100_000]
+ */
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/** Compute FNV-1a 32-bit hash of a UTF-8 string */
+export function fnv1a32(input) {
+    let hash = FNV_OFFSET_BASIS;
+    const bytes = new TextEncoder().encode(input);
+    for (const byte of bytes) {
+        hash ^= byte;
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash >>> 0;
+}
+/**
+ * Compute the deterministic bucket for a flag + targeting key combination.
+ * @returns bucket in range [1, 100_000]
+ * @throws BucketError with code MISSING_TARGETING_KEY if targetingKey is empty
+ */
+export function computeBucket(flagKey, environmentKey, targetingKey, salt = "v1") {
+    if (!targetingKey) {
+        throw new BucketError("MISSING_TARGETING_KEY");
+    }
+    const input = `${flagKey}|${environmentKey}|${targetingKey}|${salt}`;
+    return (fnv1a32(input) % 100_000) + 1;
+}
+/** Resolve rollout variant from bucket value and weighted partitions */
+export function resolveRolloutVariant(bucket, rollout) {
+    let cumulative = 0;
+    for (const split of rollout) {
+        cumulative += split.weight;
+        if (bucket <= cumulative) {
+            return split.variant;
+        }
+    }
+    return rollout[rollout.length - 1].variant;
+}
+export class BucketError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "BucketError";
+    }
+}
+//# sourceMappingURL=bucket.js.map

package/dist/bucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.js","sourceRoot":"","sources":["../src/bucket.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,gBAAgB,GAAG,UAAU,CAAC;AACpC,MAAM,SAAS,GAAG,UAAU,CAAC;AAE7B,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,IAAI,GAAG,gBAAgB,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,IAAI,CAAC;QACb,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,cAAsB,EACtB,YAAoB,EACpB,IAAI,GAAG,IAAI;IAEX,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,WAAW,CAAC,uBAAuB,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,OAAO,IAAI,cAAc,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;IACrE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,OAA8C;IAE9C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,MAAM,IAAI,UAAU,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7C,CAAC;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IACR;IAA5B,YAA4B,IAAY;QACtC,KAAK,CAAC,IAAI,CAAC,CAAC;QADc,SAAI,GAAJ,IAAI,CAAQ;QAEtC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/cache.d.ts

@@ -0,0 +1,12 @@
+import type { CacheAdapter } from "./types.js";
+export declare class LocalStorageCache implements CacheAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+export declare class MemoryCache implements CacheAdapter {
+    private store;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}

package/dist/cache.js

@@ -0,0 +1,30 @@
+const PREFIX = "omniflags:snapshot:";
+export class LocalStorageCache {
+    async get(key) {
+        try {
+            return globalThis.localStorage.getItem(PREFIX + key);
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(key, value) {
+        try {
+            globalThis.localStorage.setItem(PREFIX + key, value);
+        }
+        catch { /* full or unavailable */ }
+    }
+    async remove(key) {
+        try {
+            globalThis.localStorage.removeItem(PREFIX + key);
+        }
+        catch { /* ignore */ }
+    }
+}
+export class MemoryCache {
+    store = new Map();
+    async get(key) { return this.store.get(key) ?? null; }
+    async set(key, value) { this.store.set(key, value); }
+    async remove(key) { this.store.delete(key); }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,qBAAqB,CAAC;AAErC,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,IAAI,CAAC;YAAC,OAAO,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,IAAI,CAAC;QAAC,CAAC;IACtF,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QAClC,IAAI,CAAC;YAAC,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;IACnG,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC;YAAC,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClF,CAAC;CACF;AAED,MAAM,OAAO,WAAW;IACd,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,CAAC,GAAG,CAAC,GAAW,IAA4B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IACtF,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,IAAmB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACpF,KAAK,CAAC,MAAM,CAAC,GAAW,IAAmB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrE"}

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import type { CacheAdapter, EvaluationContext, EvaluationResult, Hook, LoadingState, OmniFlagsOptions, ProviderEvent, ProviderStatus } from "./types.js";
+export declare class OmniFlagsClient {
+    private flags;
+    private hooks;
+    private provider;
+    private cache?;
+    private readonly sdkKey;
+    private pollingTimer;
+    private _status;
+    private _readyPromise;
+    private _resolveReady;
+    private metrics?;
+    private eventHandlers;
+    private _isFetching;
+    private _origin;
+    private _fetchError;
+    private envKey;
+    private pollingIntervalMs;
+    constructor(opts: OmniFlagsOptions, cache?: CacheAdapter);
+    get status(): ProviderStatus;
+    get loadingState(): LoadingState;
+    waitForReady(): Promise<void>;
+    /** Trigger an immediate poll without waiting for the next scheduled interval. */
+    refresh(): void;
+    shutdown(): Promise<void>;
+    isEnabled(flagKey: string, context?: EvaluationContext, defaultValue?: boolean): boolean;
+    getValue<T = unknown>(flagKey: string, context?: EvaluationContext, defaultValue?: T): T;
+    getVariant(flagKey: string, context?: EvaluationContext): EvaluationResult;
+    getBoolean(flagKey: string, defaultValue: boolean, context?: EvaluationContext): boolean;
+    getString(flagKey: string, defaultValue: string, context?: EvaluationContext): string;
+    getNumber(flagKey: string, defaultValue: number, context?: EvaluationContext): number;
+    getObject<T = Record<string, unknown>>(flagKey: string, defaultValue: T, context?: EvaluationContext): T;
+    getBooleanDetail(flagKey: string, defaultValue: boolean, context?: EvaluationContext): EvaluationResult<boolean>;
+    getStringDetail(flagKey: string, defaultValue: string, context?: EvaluationContext): EvaluationResult<string>;
+    addHook(hook: Hook): void;
+    on(event: ProviderEvent, handler: () => void): () => void;
+    private evaluateSync;
+    private applySnapshot;
+    private init;
+    private startPolling;
+    private stopPolling;
+    private poll;
+    private loadFromCache;
+    private saveToCache;
+    private emitEvent;
+}

package/dist/client.js

@@ -0,0 +1,265 @@
+import { PermanentProviderError } from "./types.js";
+import { evaluate } from "./evaluator.js";
+import { HttpProvider } from "./http-provider.js";
+import { MetricsReporter } from "./metrics.js";
+import { LocalStorageCache } from "./cache.js";
+export class OmniFlagsClient {
+    flags = new Map();
+    hooks = [];
+    provider;
+    cache;
+    sdkKey;
+    pollingTimer = null;
+    _status = "not_ready";
+    _readyPromise;
+    _resolveReady;
+    metrics;
+    eventHandlers = new Map();
+    // Loading state
+    _isFetching = false;
+    _origin = "NONE";
+    _fetchError = null;
+    // Derived from the first snapshot — not required from the caller
+    envKey = "";
+    pollingIntervalMs = 30_000; // overwritten by server on first fetch
+    constructor(opts, cache) {
+        if (opts.sdkKey.startsWith("sk_")) {
+            throw new Error("OmniFlags: server-side SDK keys (sk_) cannot be used in client-side SDKs. " +
+                "Create a client key (pk_) for use in browser and mobile applications.");
+        }
+        this.sdkKey = opts.sdkKey;
+        this.cache = cache ?? new LocalStorageCache();
+        this.hooks = opts.hooks ?? [];
+        this.provider = opts.provider ?? new HttpProvider();
+        this._readyPromise = new Promise((resolve) => { this._resolveReady = resolve; });
+        void this.init();
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────────
+    get status() { return this._status; }
+    get loadingState() {
+        return {
+            isFetching: this._isFetching,
+            isLoading: this._origin === "NONE",
+            origin: this._origin,
+            error: this._fetchError,
+        };
+    }
+    waitForReady() { return this._readyPromise; }
+    /** Trigger an immediate poll without waiting for the next scheduled interval. */
+    refresh() { void this.poll(); }
+    async shutdown() {
+        this.stopPolling();
+        await this.metrics?.shutdown();
+        await this.provider.shutdown?.();
+    }
+    // ── Typed Evaluation ───────────────────────────────────────────────────
+    isEnabled(flagKey, context, defaultValue = false) {
+        return this.evaluateSync(flagKey, "boolean", defaultValue, context).value;
+    }
+    getValue(flagKey, context, defaultValue) {
+        const flag = this.flags.get(flagKey);
+        const type = flag?.type ?? "string";
+        return this.evaluateSync(flagKey, type, defaultValue, context).value;
+    }
+    getVariant(flagKey, context) {
+        const flag = this.flags.get(flagKey);
+        const type = flag?.type ?? "boolean";
+        return this.evaluateSync(flagKey, type, null, context);
+    }
+    getBoolean(flagKey, defaultValue, context) {
+        return this.evaluateSync(flagKey, "boolean", defaultValue, context).value;
+    }
+    getString(flagKey, defaultValue, context) {
+        return this.evaluateSync(flagKey, "string", defaultValue, context).value;
+    }
+    getNumber(flagKey, defaultValue, context) {
+        return this.evaluateSync(flagKey, "number", defaultValue, context).value;
+    }
+    getObject(flagKey, defaultValue, context) {
+        return this.evaluateSync(flagKey, "json", defaultValue, context).value;
+    }
+    getBooleanDetail(flagKey, defaultValue, context) {
+        return this.evaluateSync(flagKey, "boolean", defaultValue, context);
+    }
+    getStringDetail(flagKey, defaultValue, context) {
+        return this.evaluateSync(flagKey, "string", defaultValue, context);
+    }
+    // ── Hooks & Events ─────────────────────────────────────────────────────
+    addHook(hook) { this.hooks.push(hook); }
+    on(event, handler) {
+        if (!this.eventHandlers.has(event))
+            this.eventHandlers.set(event, new Set());
+        this.eventHandlers.get(event).add(handler);
+        return () => { this.eventHandlers.get(event)?.delete(handler); };
+    }
+    // ── Internal ───────────────────────────────────────────────────────────
+    evaluateSync(flagKey, expectedType, callerDefault, invocationContext) {
+        if (this._status === "not_ready") {
+            return { value: callerDefault, variant: null, reason: "ERROR", ruleId: null, errorCode: "PROVIDER_NOT_READY" };
+        }
+        const ctx = invocationContext ?? {};
+        for (const h of this.hooks) {
+            try {
+                h.before?.(flagKey, ctx);
+            }
+            catch { /* swallow */ }
+        }
+        try {
+            const flag = this.flags.get(flagKey);
+            const result = evaluate(flag, flagKey, expectedType, callerDefault, ctx, this.envKey);
+            if (result.variant)
+                this.metrics?.track(flagKey, result.variant);
+            for (const h of this.hooks) {
+                try {
+                    h.after?.(flagKey, result);
+                }
+                catch { /* swallow */ }
+            }
+            return result;
+        }
+        catch (err) {
+            for (const h of this.hooks) {
+                try {
+                    h.error?.(flagKey, err);
+                }
+                catch { /* swallow */ }
+            }
+            return { value: callerDefault, variant: null, reason: "ERROR", ruleId: null, errorCode: "UNKNOWN" };
+        }
+    }
+    applySnapshot(snapshot) {
+        // Derive envKey and polling interval from the server response
+        if (snapshot.envKey)
+            this.envKey = snapshot.envKey;
+        if (snapshot.pollingIntervalMs > 0)
+            this.pollingIntervalMs = snapshot.pollingIntervalMs;
+        const m = new Map();
+        for (const f of snapshot.flags)
+            m.set(f.key, f);
+        this.flags = m;
+        // Wire up metrics once we know envKey (first snapshot)
+        if (!this.metrics && this.envKey) {
+            this.metrics = new MetricsReporter(this.sdkKey, this.envKey);
+        }
+        // Apply server-driven metrics config on every snapshot
+        if (snapshot.metricsFlushIntervalMs > 0 && snapshot.metricsMaxBatchSize > 0) {
+            this.metrics?.updateConfig(snapshot.metricsFlushIntervalMs, snapshot.metricsMaxBatchSize);
+        }
+    }
+    // ── Init & Polling ─────────────────────────────────────────────────────
+    async init() {
+        await this.loadFromCache();
+        this._isFetching = true;
+        this.emitEvent("PROVIDER_LOADING_STATE_CHANGED");
+        try {
+            const snapshot = await this.provider.initialize(this.sdkKey);
+            if (snapshot) {
+                this.applySnapshot(snapshot);
+                await this.saveToCache(snapshot);
+            }
+            this._origin = "SERVER";
+            this._fetchError = null;
+            this._status = "ready";
+            this._resolveReady();
+            this.emitEvent("PROVIDER_READY");
+        }
+        catch (err) {
+            this._fetchError = err instanceof Error ? err : new Error(String(err));
+            if (this.flags.size > 0) {
+                this._status = "stale";
+                this._resolveReady();
+                this.emitEvent("PROVIDER_STALE");
+            }
+            else {
+                this._status = "error";
+                this._resolveReady();
+                this.emitEvent("PROVIDER_ERROR");
+            }
+        }
+        finally {
+            this._isFetching = false;
+            this.emitEvent("PROVIDER_LOADING_STATE_CHANGED");
+        }
+        this.startPolling();
+        this.metrics?.start();
+    }
+    startPolling() {
+        if (this.pollingTimer)
+            return;
+        // Use server-driven interval, re-schedule if interval changes after next fetch
+        const scheduleNext = () => {
+            this.pollingTimer = setTimeout(() => void this.poll().then(scheduleNext), this.pollingIntervalMs);
+        };
+        scheduleNext();
+    }
+    stopPolling() {
+        if (this.pollingTimer) {
+            clearTimeout(this.pollingTimer);
+            this.pollingTimer = null;
+        }
+    }
+    async poll() {
+        this._isFetching = true;
+        this.emitEvent("PROVIDER_LOADING_STATE_CHANGED");
+        try {
+            const snap = await this.provider.refresh?.(this.sdkKey);
+            if (snap) {
+                this.applySnapshot(snap);
+                await this.saveToCache(snap);
+                this._origin = "SERVER";
+                this._fetchError = null;
+                this._status = "ready";
+                this.emitEvent("PROVIDER_CONFIGURATION_CHANGED");
+            }
+        }
+        catch (err) {
+            this._fetchError = err instanceof Error ? err : new Error(String(err));
+            if (err instanceof PermanentProviderError) {
+                this.stopPolling();
+                this._status = "error";
+                this.emitEvent("PROVIDER_ERROR");
+                return;
+            }
+            if (this._status === "ready") {
+                this._status = "stale";
+                this.emitEvent("PROVIDER_STALE");
+            }
+        }
+        finally {
+            this._isFetching = false;
+            this.emitEvent("PROVIDER_LOADING_STATE_CHANGED");
+        }
+    }
+    async loadFromCache() {
+        if (!this.cache)
+            return;
+        try {
+            // Cache key is sdkKey — each key maps to exactly one environment
+            const raw = await this.cache.get(this.sdkKey);
+            if (raw) {
+                this.applySnapshot(JSON.parse(raw));
+                this._origin = "CACHE";
+            }
+        }
+        catch { /* corrupt cache */ }
+    }
+    async saveToCache(snapshot) {
+        if (!this.cache)
+            return;
+        try {
+            await this.cache.set(this.sdkKey, JSON.stringify(snapshot));
+        }
+        catch { /* non-fatal */ }
+    }
+    emitEvent(event) {
+        const handlers = this.eventHandlers.get(event);
+        if (handlers)
+            for (const h of handlers) {
+                try {
+                    h();
+                }
+                catch { /* swallow */ }
+            }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+import type { EvaluationContext } from "./types.js";
+/**
+ * Merge contexts with precedence: global < client < invocation.
+ * Higher precedence overwrites lower on key collision.
+ */
+export declare function mergeContexts(...contexts: (EvaluationContext | undefined)[]): EvaluationContext;
+/**
+ * Resolve a dot-path attribute from the evaluation context.
+ * e.g. "user.plan" resolves ctx.user.plan if nested.
+ */
+export declare function resolveAttribute(ctx: EvaluationContext, attribute: string): unknown;

package/dist/context.js

@@ -0,0 +1,31 @@
+/**
+ * Merge contexts with precedence: global < client < invocation.
+ * Higher precedence overwrites lower on key collision.
+ */
+export function mergeContexts(...contexts) {
+    const result = {};
+    for (const ctx of contexts) {
+        if (ctx) {
+            Object.assign(result, ctx);
+        }
+    }
+    return result;
+}
+/**
+ * Resolve a dot-path attribute from the evaluation context.
+ * e.g. "user.plan" resolves ctx.user.plan if nested.
+ */
+export function resolveAttribute(ctx, attribute) {
+    if (attribute in ctx) {
+        return ctx[attribute];
+    }
+    const parts = attribute.split(".");
+    let current = ctx;
+    for (const part of parts) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAG,QAA2C;IAE9C,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAsB,EAAE,SAAiB;IACxE,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;QACrB,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,OAAO,GAAY,GAAG,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACrE,OAAO,GAAI,OAAmC,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/evaluator.d.ts

@@ -0,0 +1,6 @@
+import type { EvaluationContext, EvaluationResult, FlagConfig, FlagType } from "./types.js";
+/**
+ * Core evaluation engine implementing evaluation-spec v2 §5.
+ * All SDKs must produce identical results for identical inputs.
+ */
+export declare function evaluate(flag: FlagConfig | undefined, _flagKey: string, expectedType: FlagType, callerDefault: unknown, context: EvaluationContext, envKey: string): EvaluationResult;