@layers/amba-react-native 4.1.0 → 4.2.0

package/dist/index.cjs

@@ -1818,6 +1818,296 @@ 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
 /**
@@ -2200,7 +2490,7 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.1.0";
+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
@@ -2244,6 +2534,62 @@ const authSubscribers = /* @__PURE__ */ new Set();
 * 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 {
@@ -2866,6 +3212,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();
@@ -2873,6 +3221,8 @@ 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,
@@ -2906,6 +3256,11 @@ const Amba = {
 			resolvedFunctionsProjectId: null,
 			functionsProjectIdInflight: null,
 			persistence,
+			remoteValues,
+			refreshedFor: {
+				config: null,
+				flags: null
+			},
 			offlineEnabled: false,
 			offlineQueue: null,
 			eventQueue: null
@@ -3156,7 +3511,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) {
@@ -3537,54 +3895,69 @@ 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) => {