@layers/amba-react-native 4.0.14 → 4.2.0

package/dist/index.js

@@ -101,6 +101,9 @@ var AmbaHttpClient = class {
 	baseUrl;
 	sdkPlatform;
 	sdkVersionHeader;
+	appVersion;
+	deviceRegion;
+	deviceOs;
 	identity;
 	fetchImpl;
 	ensureSession;
@@ -110,6 +113,9 @@ var AmbaHttpClient = class {
 		this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
 		this.sdkPlatform = opts.sdkPlatform;
 		this.sdkVersionHeader = opts.sdkVersionHeader;
+		this.appVersion = opts.appVersion;
+		this.deviceRegion = opts.deviceRegion;
+		this.deviceOs = opts.deviceOs;
 		this.identity = opts.identity;
 		this.ensureSession = opts.ensureSession;
 		this.onSessionRefused = opts.onSessionRefused;
@@ -138,6 +144,9 @@ var AmbaHttpClient = class {
 			Accept: "application/json",
 			...extra
 		};
+		if (this.appVersion) h["X-App-Version"] = this.appVersion;
+		if (this.deviceRegion) h["X-Device-Region"] = this.deviceRegion;
+		if (this.deviceOs) h["X-Device-OS"] = this.deviceOs;
 		const tok = this.identity.getSessionToken();
 		if (tok) h.Authorization = `Bearer ${tok}`;
 		return h;
@@ -1763,6 +1772,407 @@ const notifications = {
 	}
 };
 
+//#endregion
+//#region src/experiment-reporter.ts
+/** Keys remembered before the oldest are forgotten (bounds memory). */
+const DEFAULT_MAX_REPORTED = 1e4;
+var ExperimentAssignmentReporter = class {
+	listeners = /* @__PURE__ */ new Set();
+	reported = /* @__PURE__ */ new Set();
+	constructor(maxReported = DEFAULT_MAX_REPORTED) {
+		this.maxReported = maxReported;
+	}
+	/** Add a listener. Returns a function that removes it. */
+	subscribe(listener) {
+		if (typeof listener !== "function") throw new TypeError("onExperimentAssigned expects a function");
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/**
+	* Call the listeners for `assignment` when this user has not reported this
+	* experiment yet in the session. Returns `assignment` unchanged.
+	*/
+	report(assignment) {
+		if (this.listeners.size === 0) return assignment;
+		const id = `${assignment.bucketingId}\u0000${assignment.experimentKey}`;
+		if (this.reported.has(id)) {
+			this.reported.delete(id);
+			this.reported.add(id);
+			return assignment;
+		}
+		this.reported.add(id);
+		if (this.reported.size > this.maxReported) {
+			const oldest = this.reported.values().next().value;
+			if (oldest !== void 0) this.reported.delete(oldest);
+		}
+		for (const listener of Array.from(this.listeners)) try {
+			const result = listener({ ...assignment });
+			if (result && typeof result.then === "function") result.then(void 0, logListenerError);
+		} catch (err) {
+			logListenerError(err);
+		}
+		return assignment;
+	}
+	/** Start a new session: every experiment reports again. */
+	reset() {
+		this.reported.clear();
+	}
+};
+function logListenerError(err) {
+	console.warn("[amba] onExperimentAssigned listener threw", err);
+}
+
+//#endregion
+//#region src/remote-values.ts
+/** Prefix of the per-project AsyncStorage record key. */
+const CACHE_KEY_PREFIX = "amba_rc_v1_";
+/** Slot for values evaluated without a signed-in user. */
+const ANON_SLOT = "anon";
+/** Most user slots one project record keeps. */
+const MAX_SLOTS = 5;
+const TWO_32 = 4294967296;
+/**
+* 64-bit FNV-1a over the string's UTF-16 code units (low byte, then high
+* byte), as 16 hex digits. Computed in two 32-bit halves: some React Native
+* engines (JavaScriptCore on older Android builds) have no BigInt.
+*/
+function fnv1a64Hex(text) {
+	let hi = 3421674724;
+	let lo = 2216829733;
+	const step = (byte) => {
+		lo = (lo ^ byte) >>> 0;
+		const low = lo * 435;
+		const carry = Math.floor(low / TWO_32);
+		const high = hi * 435 + carry + (lo << 8 >>> 0);
+		lo = low % TWO_32;
+		hi = high % TWO_32;
+	};
+	for (let i = 0; i < text.length; i++) {
+		const unit = text.charCodeAt(i);
+		step(unit & 255);
+		step(unit >>> 8);
+	}
+	return hi.toString(16).padStart(8, "0") + lo.toString(16).padStart(8, "0");
+}
+/** The record key for a project: a hash of the base URL and client key. */
+function recordKey(baseUrl, clientKey) {
+	return `${CACHE_KEY_PREFIX}${fnv1a64Hex(`${baseUrl.replace(/\/+$/, "")}\n${clientKey}`)}`;
+}
+/** The slot key for an identity: `u` + a hash of the user id, or `anon`. */
+function slotKey(appUserId) {
+	return appUserId ? `u${fnv1a64Hex(appUserId)}` : ANON_SLOT;
+}
+/**
+* The user a config response was evaluated for, from its `ETag`:
+* `"<version>:<app user id>:<segments>"` for a signed-in caller, `"<version>"`
+* for every other one (no session, or an expired or revoked token, which the
+* server answers with each key's default value). `undefined` without an
+* `ETag`; `null` for an evaluation for nobody.
+*/
+function etagEvaluatedFor(etag) {
+	if (!etag) return void 0;
+	const parts = etag.trim().replace(/^W\//, "").replace(/^"|"$/g, "").split(":");
+	return parts.length > 1 && parts[1] ? parts[1] : null;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validSlot(raw) {
+	if (!isPlainObject(raw)) return null;
+	const slot = { saved_at: typeof raw["saved_at"] === "number" ? raw["saved_at"] : 0 };
+	const config = raw["config"];
+	if (isPlainObject(config) && isPlainObject(config["values"])) slot.config = {
+		version: typeof config["version"] === "string" ? config["version"] : null,
+		values: config["values"]
+	};
+	const flags = raw["flags"];
+	if (Array.isArray(flags)) slot.flags = flags.filter((f) => isPlainObject(f) && typeof f["name"] === "string" && typeof f["enabled"] === "boolean");
+	return slot.config || slot.flags ? slot : null;
+}
+function upsert(list, flag) {
+	const i = list.findIndex((f) => f.name === flag.name);
+	if (i >= 0) list[i] = flag;
+	else list.push(flag);
+}
+var RemoteValuesCache = class {
+	record = {
+		v: 1,
+		slots: {}
+	};
+	/** The slot key the held values were resolved for. */
+	viewFor = null;
+	config = null;
+	flags = null;
+	/** Bumped by every sign-out; an older ticket's response is not cached. */
+	generation = 0;
+	writes = Promise.resolve();
+	constructor(store, key, defaults, currentUser) {
+		this.store = store;
+		this.key = key;
+		this.defaults = defaults;
+		this.currentUser = currentUser;
+	}
+	/** Read the project's record from storage. `configure()` awaits it. */
+	async load() {
+		let raw = null;
+		try {
+			raw = await this.store.read(this.key);
+		} catch {
+			return;
+		}
+		if (!raw) return;
+		try {
+			const parsed = JSON.parse(raw);
+			const slots = {};
+			if (isPlainObject(parsed) && isPlainObject(parsed["slots"])) for (const [k, v] of Object.entries(parsed["slots"])) {
+				const slot = validSlot(v);
+				if (slot) slots[k] = slot;
+			}
+			this.record = {
+				v: 1,
+				slots
+			};
+		} catch {
+			this.record = {
+				v: 1,
+				slots: {}
+			};
+			this.persist();
+		}
+	}
+	/** Take a ticket for a request about to be sent for the current user. */
+	ticket() {
+		return {
+			generation: this.generation,
+			requestedFor: this.currentUser()
+		};
+	}
+	/** The value for config `key` (fetched, cached, then default); `undefined` when none. */
+	configValue(key) {
+		this.ensureView();
+		const values = this.config?.values;
+		if (values && Object.prototype.hasOwnProperty.call(values, key)) {
+			const v = values[key];
+			if (v !== null && v !== void 0) return v;
+		}
+		return this.defaultFor(key);
+	}
+	/** The held assignment for flag `key`, or `null`. */
+	flag(key) {
+		this.ensureView();
+		return this.flags?.find((f) => f.name === key) ?? null;
+	}
+	/** Whether flag `key` is on: the held assignment, then a boolean default. */
+	flagEnabled(key) {
+		const flag = this.flag(key);
+		if (flag) return flag.enabled;
+		const d = this.defaultFor(key);
+		return typeof d === "boolean" ? d : void 0;
+	}
+	/**
+	* Hold and persist a fetched bundle; returns it. A bundle the server
+	* evaluated for nobody although the request carried a user (an expired or
+	* revoked session) goes to the `anon` slot and leaves the user's values
+	* alone; one evaluated for another user is not cached.
+	*/
+	storeConfig(ticket, bundle, etag) {
+		if (!isPlainObject(bundle.values)) return bundle;
+		const evaluatedFor = etagEvaluatedFor(etag);
+		let target;
+		if (ticket.requestedFor && evaluatedFor === null) target = ANON_SLOT;
+		else if (typeof evaluatedFor === "string" && evaluatedFor !== ticket.requestedFor) return bundle;
+		this.write(ticket, target, (slot, held) => {
+			slot.config = bundle;
+			if (held) this.config = bundle;
+		});
+		return bundle;
+	}
+	/** Hold and persist a fetched flag list (it replaces the held one). */
+	storeFlags(ticket, flags) {
+		this.write(ticket, void 0, (slot, held) => {
+			slot.flags = [...flags];
+			if (held) this.flags = [...flags];
+		});
+		return flags;
+	}
+	/** Hold and persist one flag from a single-flag lookup; returns it. */
+	upsertFlag(ticket, flag) {
+		this.write(ticket, void 0, (slot, held) => {
+			this.adoptHeldFlags(slot, held);
+			slot.flags = slot.flags ?? [];
+			upsert(slot.flags, flag);
+			if (held) {
+				this.flags = this.flags ?? [];
+				upsert(this.flags, flag);
+			}
+		});
+		return flag;
+	}
+	/** Drop flag `key` after a single-flag lookup found it off or unknown. */
+	removeFlag(ticket, key) {
+		this.write(ticket, void 0, (slot, held) => {
+			this.adoptHeldFlags(slot, held);
+			if (slot.flags) slot.flags = slot.flags.filter((f) => f.name !== key);
+			if (held && this.flags) this.flags = this.flags.filter((f) => f.name !== key);
+		});
+	}
+	/**
+	* Sign-out: delete the signed-out user's slot and drop the held values;
+	* later lookups serve the `anon` slot, then the defaults.
+	*/
+	clearForSignOut(signedOutUser) {
+		this.generation += 1;
+		this.config = null;
+		this.flags = null;
+		this.viewFor = null;
+		if (!signedOutUser) return;
+		const doomed = slotKey(signedOutUser);
+		if (this.record.slots[doomed]) {
+			delete this.record.slots[doomed];
+			this.persist();
+		}
+	}
+	/** Resolves when every write so far reached storage. */
+	flushed() {
+		return this.writes;
+	}
+	/**
+	* Before a single-flag change to the current user's slot: when the slot
+	* holds no flag list and the served list is the signed-out one, the
+	* user's slot starts from that list, so after a relaunch the user reads
+	* the same flags the change was made on.
+	*/
+	adoptHeldFlags(slot, held) {
+		if (held && !slot.flags && this.flags) slot.flags = [...this.flags];
+	}
+	defaultFor(key) {
+		if (!Object.prototype.hasOwnProperty.call(this.defaults, key)) return void 0;
+		const v = this.defaults[key];
+		return v === null ? void 0 : v;
+	}
+	/**
+	* `held` is `true` when the slot written is the one the current identity
+	* reads, so the served values change with it.
+	*/
+	write(ticket, targetOverride, apply) {
+		const current = slotKey(this.currentUser());
+		if (ticket.generation !== this.generation || slotKey(ticket.requestedFor) !== current) return;
+		this.ensureView();
+		const target = targetOverride ?? current;
+		const existing = this.record.slots[target];
+		const slot = existing ? {
+			saved_at: existing.saved_at,
+			...existing.config ? { config: existing.config } : {},
+			...existing.flags ? { flags: [...existing.flags] } : {}
+		} : { saved_at: 0 };
+		apply(slot, target === current);
+		if (!slot.config && !slot.flags) {
+			if (!existing) return;
+			delete this.record.slots[target];
+		} else {
+			slot.saved_at = Date.now();
+			this.record.slots[target] = slot;
+			this.prune(target);
+		}
+		this.persist();
+		if (target !== current) this.viewFor = null;
+	}
+	/** Serve the current identity's own slot, the `anon` slot for the rest. */
+	ensureView() {
+		const current = slotKey(this.currentUser());
+		if (this.viewFor === current) return;
+		const own = this.record.slots[current];
+		const anon = current === ANON_SLOT ? void 0 : this.record.slots[ANON_SLOT];
+		const config = own?.config ?? anon?.config;
+		const flags = own?.flags ?? anon?.flags;
+		this.config = config ?? null;
+		this.flags = flags ? [...flags] : null;
+		this.viewFor = current;
+	}
+	/**
+	* Keep the MAX_SLOTS most recently written user slots; `keep` and the
+	* signed-out slot (read before sign-in and for every user's gaps) stay.
+	*/
+	prune(keep) {
+		const keys = Object.keys(this.record.slots).filter((k) => k !== ANON_SLOT);
+		while (keys.length > MAX_SLOTS) {
+			let oldest = null;
+			for (const k of keys) {
+				if (k === keep) continue;
+				if (oldest === null || this.record.slots[k].saved_at < this.record.slots[oldest].saved_at) oldest = k;
+			}
+			if (oldest === null) break;
+			delete this.record.slots[oldest];
+			keys.splice(keys.indexOf(oldest), 1);
+		}
+	}
+	persist() {
+		const text = Object.keys(this.record.slots).length === 0 ? null : JSON.stringify(this.record);
+		this.writes = this.writes.then(() => text === null ? this.store.delete(this.key) : this.store.write(this.key, text)).catch(() => {});
+	}
+};
+
+//#endregion
+//#region src/client-info.ts
+/**
+* Values for the `X-App-Version`, `X-Device-Region` and `X-Device-OS`
+* request headers. Each is omitted when unknown, so every helper here
+* returns `undefined` for a value the header can't carry as-is.
+*/
+/** Longest `X-App-Version` value sent (matches the core's limit). */
+const MAX_APP_VERSION_LENGTH = 64;
+/**
+* An app version for `X-App-Version`: the text before the first whitespace
+* (`"2.3.1 (45)"` sends `2.3.1`), which must start with an ASCII letter or
+* digit, hold only letters, digits and `.` `_` `+` `-`, and be at most
+* {@link MAX_APP_VERSION_LENGTH} characters: the shape the API records for
+* segment targeting. Anything else returns `undefined`.
+*/
+function normalizeAppVersion(raw) {
+	if (typeof raw !== "string") return void 0;
+	const v = raw.trim().split(/\s+/)[0] ?? "";
+	if (v.length === 0 || v.length > MAX_APP_VERSION_LENGTH) return void 0;
+	return /^[0-9A-Za-z][0-9A-Za-z._+-]*$/.test(v) ? v : void 0;
+}
+/**
+* The region subtag of a BCP 47 locale tag (`en-US` → `US`, `zh-Hant-TW` →
+* `TW`, POSIX `fr_FR.UTF-8` → `FR`, iOS `en_US@rg=gbzzzz` → `US`),
+* uppercased. Returns `undefined` when the tag carries no two-letter region
+* (`en`, `es-419`, `sr-Latn`).
+*/
+function regionFromLocale(tag) {
+	if (typeof tag !== "string" || tag.length === 0) return void 0;
+	const parts = tag.split(/[.@]/)[0].split(/[-_]/);
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.length === 1) break;
+		if (/^[A-Za-z]{2}$/.test(part)) return part.toUpperCase();
+	}
+}
+const DEVICE_OS_VALUES = [
+	"ios",
+	"android",
+	"web",
+	"macos",
+	"windows",
+	"linux",
+	"other"
+];
+/**
+* Map a platform OS name (React Native's `Platform.OS`, for example) to an
+* `X-Device-OS` value. Listed names pass through lowercased; any other
+* non-empty name is a known-but-unlisted OS and maps to `"other"`. Empty or
+* missing returns `undefined`.
+*/
+function deviceOsFromPlatform(os) {
+	if (typeof os !== "string") return void 0;
+	const v = os.trim().toLowerCase();
+	if (v.length === 0) return void 0;
+	return DEVICE_OS_VALUES.includes(v) ? v : "other";
+}
+
 //#endregion
 //#region src/realtime.ts
 const INITIAL_BACKOFF_MS = 500;
@@ -2086,7 +2496,7 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.0.14";
+const SDK_VERSION = "4.2.0";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -2123,6 +2533,69 @@ function realtimeAuthHeaders() {
 	};
 }
 const authSubscribers = /* @__PURE__ */ new Set();
+/**
+* `Amba.onExperimentAssigned` listeners. `experiments.getVariant` reports
+* each result here; the reporter calls the listeners once per experiment per
+* user session. A sign-out (any auth change to no session) and `configure`
+* start a new session.
+*/
+const experimentReporter = new ExperimentAssignmentReporter();
+/**
+* `configDefaults` from the latest `configure()` call, recorded before
+* configure reads the AsyncStorage cache. `config.getCached` and
+* `flags.isEnabled` serve them on a first render that runs while
+* `configure()` is still in flight.
+*/
+let _pendingConfigDefaults = null;
+/** Validate `AmbaConfig.configDefaults`: absent, or a plain object. */
+function readConfigDefaults(value) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value !== "object" || Array.isArray(value)) throw new AmbaApiError("INVALID_CONFIG", "Amba.configure: configDefaults must be an object of config key to value");
+	return value;
+}
+/** The pending `configDefaults` entry for `key`, ignoring inherited properties. */
+function pendingDefault(key) {
+	const defaults = _pendingConfigDefaults;
+	if (!defaults || !Object.prototype.hasOwnProperty.call(defaults, key)) return;
+	const value = defaults[key];
+	return value === null ? void 0 : value;
+}
+/** `"array"` for arrays, else `typeof` — the JSON kind of a value. */
+function jsonKind(value) {
+	return Array.isArray(value) ? "array" : typeof value;
+}
+function configGetCached(key, defaultValue) {
+	if (state) refreshOnFirstRead(state, "config");
+	const raw = state ? state.remoteValues.configValue(key) : pendingDefault(key);
+	if (raw === void 0 || raw === null) return defaultValue;
+	if (defaultValue !== void 0 && defaultValue !== null && jsonKind(raw) !== jsonKind(defaultValue)) return defaultValue;
+	return raw;
+}
+/** `Amba.flags.isEnabled`. */
+function flagsIsEnabled(key, defaultValue = false) {
+	if (state) refreshOnFirstRead(state, "flags");
+	const held = state ? state.remoteValues.flagEnabled(key) : pendingDefault(key);
+	return typeof held === "boolean" ? held : defaultValue;
+}
+/** `Amba.flags.getCached`. */
+function flagsGetCached(key) {
+	if (!state) return null;
+	refreshOnFirstRead(state, "flags");
+	return state.remoteValues.flag(key);
+}
+/**
+* The first on-device read of config (or flags) for each identity after
+* `configure()` starts one background fetch that replaces the cached values:
+* once at launch, and once more after a sign-in or sign-out changes who is
+* reading. Apps that never read cached values make no extra request. A
+* failure (offline) leaves the cached values in place.
+*/
+function refreshOnFirstRead(s, kind) {
+	const identity = s.identity.getAppUserId() ?? "";
+	if (s.refreshedFor[kind] === identity) return;
+	s.refreshedFor[kind] = identity;
+	Promise.resolve().then(() => kind === "config" ? Amba.config.fetch() : Amba.flags.fetch()).catch(() => {});
+}
 function snapshotSession(user) {
 	if (!user) return null;
 	return {
@@ -2133,6 +2606,7 @@ function snapshotSession(user) {
 	};
 }
 function notifyAuthSubscribers(session) {
+	if (session === null) experimentReporter.reset();
 	for (const cb of authSubscribers) try {
 		cb(session);
 	} catch (err) {
@@ -2549,6 +3023,7 @@ const P = {
 	aiAnthropic: "/v1/client/ai/anthropic/messages",
 	config: "/v1/client/config",
 	flags: "/v1/client/flags",
+	experiments: "/v1/client/experiments",
 	diagnosticsPing: "/v1/client/diagnostics/ping",
 	achievements: "/v1/client/achievements",
 	challenges: "/v1/client/challenges",
@@ -2692,6 +3167,39 @@ async function deleteDirect(s, name, id) {
 	return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
 }
 /**
+* The device OS for `X-Device-OS` from React Native's `Platform.OS`
+* (`ios`, `android`, `web` for react-native-web, `macos`, `windows`).
+* `undefined` outside React Native (Node, tests).
+*/
+function detectDeviceOs() {
+	try {
+		const os = require("react-native").Platform?.OS;
+		return deviceOsFromPlatform(typeof os === "string" ? os : void 0);
+	} catch {
+		return;
+	}
+}
+/**
+* The device locale's region for `X-Device-Region`: the iOS region setting
+* (`AppleLocale`) or Android's locale, falling back to the JS runtime's
+* default locale. `undefined` when none carries a two-letter region.
+*/
+function detectDeviceRegion() {
+	try {
+		const rn = require("react-native");
+		const ios = (rn.NativeModules?.["SettingsManager"])?.settings;
+		const android = rn.NativeModules?.["I18nManager"];
+		const tag = ios?.AppleLocale ?? android?.localeIdentifier;
+		const region = regionFromLocale(typeof tag === "string" ? tag : void 0);
+		if (region) return region;
+	} catch {}
+	try {
+		return regionFromLocale(Intl.DateTimeFormat().resolvedOptions().locale);
+	} catch {
+		return;
+	}
+}
+/**
 * Top-level SDK namespace for React Native.
 */
 const Amba = {
@@ -2710,6 +3218,8 @@ const Amba = {
 		if (!TOKEN_STORAGE_MODES.includes(tokenStorage)) throw new Error("Amba.configure: tokenStorage must be \"secure\", \"memory\" or \"asyncStorage\"");
 		const secureStorage = config.secureStorage;
 		if (secureStorage !== void 0 && (typeof secureStorage?.getItem !== "function" || typeof secureStorage?.setItem !== "function" || typeof secureStorage?.removeItem !== "function")) throw new Error("Amba.configure: secureStorage must provide getItem, setItem and removeItem");
+		const configDefaults = readConfigDefaults(config.configDefaults);
+		_pendingConfigDefaults = configDefaults;
 		const storagePrefix = config.storagePrefix ?? "amba";
 		const persistence = new AsyncStoragePersistence(storagePrefix);
 		if (config.events?.batching) await persistence.assertDurable();
@@ -2717,12 +3227,17 @@ const Amba = {
 		const vault = await resolveTokenVault(tokenStorage, storagePrefix, secureStorage);
 		const identity = await IdentityStore.create(persistence, vault);
 		const baseUrl = (config.apiUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+		const remoteValues = new RemoteValuesCache(persistence, recordKey(baseUrl, config.clientKey), configDefaults ?? {}, () => identity.getAppUserId());
+		await remoteValues.load();
 		const sdkVersionHeader = `amba-sdk/${SDK_VERSION} ${`amba-react-native/${SDK_VERSION}`}`;
 		const http = new AmbaHttpClient({
 			apiKey: config.clientKey,
 			baseUrl,
 			sdkPlatform: "react-native",
 			sdkVersionHeader,
+			appVersion: normalizeAppVersion(config.appVersion),
+			deviceRegion: detectDeviceRegion(),
+			deviceOs: detectDeviceOs(),
 			identity,
 			ensureSession: config.autoAnonymousSession === false ? void 0 : async (path) => {
 				if (pathSkipsLazySession(path)) return;
@@ -2735,6 +3250,7 @@ const Amba = {
 		if (prior?.offlineQueue) await prior.offlineQueue.dispose();
 		prior?.detachEventAppState?.();
 		if (prior?.eventQueue) await prior.eventQueue.dispose();
+		experimentReporter.reset();
 		const nextState = {
 			http,
 			identity,
@@ -2746,6 +3262,11 @@ const Amba = {
 			resolvedFunctionsProjectId: null,
 			functionsProjectIdInflight: null,
 			persistence,
+			remoteValues,
+			refreshedFor: {
+				config: null,
+				flags: null
+			},
 			offlineEnabled: false,
 			offlineQueue: null,
 			eventQueue: null
@@ -2996,7 +3517,10 @@ const Amba = {
 			} catch (err) {
 				if (typeof console !== "undefined") console.warn("[amba] signOut server call failed", err);
 			}
+			const signedOutUser = s.identity.getAppUserId();
 			await s.identity.clearSession(rotateAnonymousId);
+			s.remoteValues.clearForSignOut(signedOutUser);
+			await s.remoteValues.flushed();
 			try {
 				await getOfflineQueue(s).purge();
 			} catch (err) {
@@ -3377,55 +3901,86 @@ const Amba = {
 			return text;
 		}
 	} },
-	config: { fetch: async () => {
-		const s = getState();
-		const url = s.http.url(P.config);
-		const headers = s.http.buildHeaders();
-		let response;
-		try {
-			response = await (globalThis.fetch ?? fetch)(url, {
-				method: "GET",
-				headers
-			});
-		} catch (err) {
-			throw new AmbaApiError("NETWORK_ERROR", `Network error: ${err instanceof Error ? err.message : String(err)}`, err);
-		}
-		const text = await response.text();
-		if (!response.ok) {
-			const ct = response.headers.get("content-type") ?? "";
-			throw mapHttpError(response, text, ct.includes("application/json"));
-		}
-		let parsed = {};
-		if (text) try {
-			parsed = JSON.parse(text);
-		} catch {
-			parsed = {};
-		}
-		const etag = response.headers.get("etag");
-		let version = null;
-		if (etag) {
-			const cleaned = etag.replace(/^"|"$/g, "");
-			const m = cleaned.match(/^(v\d+)/);
-			version = m ? m[1] ?? null : cleaned || null;
-		}
-		return {
-			version,
-			values: parsed.data ?? {}
-		};
-	} },
+	config: {
+		fetch: async () => {
+			const s = getState();
+			const ticket = s.remoteValues.ticket();
+			const url = s.http.url(P.config);
+			const headers = s.http.buildHeaders();
+			let response;
+			try {
+				response = await (globalThis.fetch ?? fetch)(url, {
+					method: "GET",
+					headers
+				});
+			} catch (err) {
+				throw new AmbaApiError("NETWORK_ERROR", `Network error: ${err instanceof Error ? err.message : String(err)}`, err);
+			}
+			const text = await response.text();
+			if (!response.ok) {
+				const ct = response.headers.get("content-type") ?? "";
+				throw mapHttpError(response, text, ct.includes("application/json"));
+			}
+			let parsed = {};
+			if (text) try {
+				parsed = JSON.parse(text);
+			} catch {
+				parsed = {};
+			}
+			const etag = response.headers.get("etag");
+			let version = null;
+			if (etag) {
+				const cleaned = etag.replace(/^"|"$/g, "");
+				const m = cleaned.match(/^(v\d+)/);
+				version = m ? m[1] ?? null : cleaned || null;
+			}
+			return s.remoteValues.storeConfig(ticket, {
+				version,
+				values: parsed.data ?? {}
+			}, etag);
+		},
+		getCached: configGetCached
+	},
 	flags: {
 		fetch: async () => {
-			return (await getState().http.get(P.flags)).data;
+			const s = getState();
+			const ticket = s.remoteValues.ticket();
+			const env = await s.http.get(P.flags);
+			return s.remoteValues.storeFlags(ticket, env.data);
 		},
 		get: async (key) => {
+			const s = getState();
+			const ticket = s.remoteValues.ticket();
 			try {
-				return (await getState().http.get(`${P.flags}/${encodePathSegment(key)}`)).data;
+				const env = await s.http.get(`${P.flags}/${encodePathSegment(key)}`);
+				return s.remoteValues.upsertFlag(ticket, env.data);
 			} catch (err) {
-				if (err instanceof AmbaApiError && err.code === "NOT_FOUND") return null;
+				if (err instanceof AmbaApiError && err.code === "NOT_FOUND") {
+					s.remoteValues.removeFlag(ticket, key);
+					return null;
+				}
 				throw err;
 			}
+		},
+		getCached: flagsGetCached,
+		isEnabled: flagsIsEnabled
+	},
+	experiments: {
+		getVariant: async (key) => {
+			const s = getState();
+			const userBefore = s.identity.getAppUserId();
+			const env = await s.http.get(`${P.experiments}/${encodePathSegment(key)}/assignment`);
+			return experimentReporter.report({
+				experimentKey: env.data.experiment_key,
+				variant: env.data.variant,
+				bucketingId: userBefore ?? s.identity.getAppUserId() ?? ""
+			});
+		},
+		trackExposure: async (key) => {
+			await getState().http.post(`${P.experiments}/${encodePathSegment(key)}/exposure`, {});
 		}
 	},
+	onExperimentAssigned: (listener) => experimentReporter.subscribe(listener),
 	diagnostics: { ping: async () => {
 		return await getState().http.post(P.diagnosticsPing, {});
 	} },