@layers/amba-react-native 4.1.0 → 4.2.1

package/dist/index.js

@@ -90,6 +90,167 @@ var AmbaApiError = class extends Error {
 	}
 };
 
+//#endregion
+//#region src/request-deadline.ts
+/**
+* Request deadlines, shared by every JS SDK target (the same file ships in
+* `@layers/amba-web`, `@layers/amba-node` and `@layers/amba-react-native`).
+*
+* Every request the SDK sends runs under a deadline that covers sending it
+* and reading the whole response. When the deadline passes, the request is
+* aborted and fails with the SDK's retryable network error, so one request
+* can never hold an in-flight slot (the offline outbox flush, the lazy
+* anonymous sign-in, the session refresh, the event batch flush) for the
+* life of the process. Some runtimes never settle a fetch they gave up on:
+* Expo on Android drops a failed DNS lookup and the promise stays pending.
+* The deadline wins the race even then, because it rejects on its own timer
+* and then aborts the fetch for the runtime to clean up.
+*
+* Two bounds:
+*   - `requestTimeoutMs` (default 15 s): an ordinary API request.
+*   - `longRequestTimeoutMs` (default 5 min): work that legitimately runs
+*     longer. AI generation (`/v1/client/ai/*`), function invocations, and
+*     media uploads and downloads.
+* Both grow with the bytes a request moves (see `withTransferAllowance`), so
+* a large upload, download or event batch on a slow link has time to finish.
+* Realtime subscriptions are bounded until their stream opens; AI response
+* streams likewise until the response starts. Once open, a stream runs for
+* as long as the caller keeps it.
+*/
+/** Default deadline for one API request, in milliseconds. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
+/**
+* Default deadline for AI generation, function invocations and media
+* transfers, in milliseconds.
+*/
+const DEFAULT_LONG_REQUEST_TIMEOUT_MS = 3e5;
+/**
+* The slowest link a deadline makes room for, in bytes per second
+* (8 KiB/s, about 64 kbit/s). Each byte a request sends or receives beyond
+* the first {@link TRANSFER_BYTES_WITHIN_BASE} adds the time it takes at this
+* rate to the deadline.
+*/
+const MIN_TRANSFER_BYTES_PER_SECOND = 8 * 1024;
+/**
+* Bytes a request moves within its base deadline (64 KiB: 8 s at the
+* slowest rate). An ordinary API request stays at exactly
+* `requestTimeoutMs`; only larger bodies widen it.
+*/
+const TRANSFER_BYTES_WITHIN_BASE = 64 * 1024;
+/** The largest delay `setTimeout` honors (about 24.8 days). */
+const MAX_TIMEOUT_MS = 2147483647;
+/**
+* Read the deadlines from the configure options, applying the defaults.
+* Throws an `Error` naming the option when a value is not a positive number
+* of milliseconds.
+*/
+function resolveRequestDeadlines(options) {
+	return {
+		requestMs: readTimeout("Amba.configure: requestTimeoutMs", options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS),
+		longMs: readTimeout("Amba.configure: longRequestTimeoutMs", options.longRequestTimeoutMs, DEFAULT_LONG_REQUEST_TIMEOUT_MS)
+	};
+}
+/**
+* Validate one timeout value; `undefined` keeps `fallback`. `label` names the
+* option in the thrown `Error` (`Amba.configure: requestTimeoutMs`).
+*/
+function readTimeout(label, value, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > MAX_TIMEOUT_MS) throw new Error(`${label} must be a positive number of milliseconds, at most ${MAX_TIMEOUT_MS}`);
+	return value;
+}
+/** The text a deadline failure carries, e.g. `request timed out after 15000 ms`. */
+function timeoutMessage(timeoutMs) {
+	return `request timed out after ${timeoutMs} ms`;
+}
+/**
+* `timeoutMs` plus the time the bytes beyond the first
+* {@link TRANSFER_BYTES_WITHIN_BASE} take at
+* {@link MIN_TRANSFER_BYTES_PER_SECOND}, capped at the largest delay
+* `setTimeout` honors. Unknown sizes add nothing.
+*/
+function withTransferAllowance(timeoutMs, bytes) {
+	const beyond = typeof bytes === "number" && Number.isFinite(bytes) ? bytes - TRANSFER_BYTES_WITHIN_BASE : 0;
+	const extra = beyond > 0 ? Math.ceil(beyond / MIN_TRANSFER_BYTES_PER_SECOND * 1e3) : 0;
+	return Math.min(MAX_TIMEOUT_MS, timeoutMs + extra);
+}
+/**
+* The size of a request body in bytes: a string's UTF-8 length, a buffer's
+* byte length, a `Blob`'s size. `undefined` for no body or a body of unknown
+* size (a stream).
+*/
+function bodyByteLength(body) {
+	if (body === void 0 || body === null) return void 0;
+	if (typeof body === "string") return typeof TextEncoder !== "undefined" ? new TextEncoder().encode(body).length : body.length;
+	if (typeof ArrayBuffer !== "undefined") {
+		if (body instanceof ArrayBuffer) return body.byteLength;
+		if (ArrayBuffer.isView(body)) return body.byteLength;
+	}
+	const size = body.size;
+	return typeof size === "number" ? size : void 0;
+}
+/** A response's `Content-Length`, when it states one. */
+function contentLength(response) {
+	const raw = response.headers?.get?.("content-length");
+	if (!raw) return void 0;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 0 ? n : void 0;
+}
+/** The paths under the API base URL whose requests get the long deadline. */
+const LONG_API_PATH_PREFIXES = ["/v1/client/ai/"];
+/** Whether a request to API `path` (starting `/v1/...`) gets the long deadline. */
+function isLongApiPath(path) {
+	return LONG_API_PATH_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+/**
+* Race `work` against a timer of `ms`. When the timer fires first the race
+* rejects with `onTimeout(ms)`, then `controller` is aborted so the runtime
+* can release the connection. The rejection does not wait for `work`, so a
+* fetch the runtime never settles still releases its caller on time. The
+* timer is cleared as soon as either side settles.
+*/
+function raceDeadline(work, ms, controller, onTimeout) {
+	let timer;
+	const deadline = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			reject(onTimeout(ms));
+			try {
+				controller?.abort();
+			} catch {}
+		}, ms);
+	});
+	return Promise.race([work, deadline]).finally(() => {
+		clearTimeout(timer);
+	});
+}
+function newController() {
+	return typeof AbortController === "function" ? new AbortController() : void 0;
+}
+/**
+* Send a request and read its response under deadlines that grow with the
+* bytes involved. Sending, until `send` resolves with the response, gets
+* `timeoutMs` plus the allowance for the request body (and, with
+* `fetchBuffersBody`, for the expected response bytes). Reading,
+* `read(response)`, gets `timeoutMs` plus the allowance for the expected
+* response bytes, else the response's `Content-Length`. One `AbortSignal`
+* covers both phases, so a read past its deadline aborts the transfer too.
+* Past either deadline the promise rejects with `onTimeout(ms)`.
+*/
+async function exchange(timeoutMs, send, read, onTimeout, sizes = {}) {
+	const controller = newController();
+	const sendMs = withTransferAllowance(timeoutMs, (sizes.requestBytes ?? 0) + (sizes.fetchBuffersBody ? sizes.responseBytes ?? 0 : 0));
+	const response = await raceDeadline(send(controller?.signal), sendMs, controller, onTimeout);
+	const readMs = withTransferAllowance(timeoutMs, sizes.responseBytes ?? contentLength(response));
+	return raceDeadline(read(response), readMs, controller, onTimeout);
+}
+/** `init` with `signal` set, when there is one. */
+function withSignal(init, signal) {
+	return signal ? {
+		...init,
+		signal
+	} : init;
+}
+
 //#endregion
 //#region src/http-client.ts
 /** Default amba API endpoint. */
@@ -106,6 +267,12 @@ var AmbaHttpClient = class {
 	deviceOs;
 	identity;
 	fetchImpl;
+	/** The `fetchImpl` option, when one was passed (`send` resolves fetch per call otherwise). */
+	injectedFetch;
+	/** Deadline for an API request, in milliseconds. */
+	requestTimeoutMs;
+	/** Deadline for AI generation, function invocations and media transfers. */
+	longRequestTimeoutMs;
 	ensureSession;
 	onSessionRefused;
 	constructor(opts) {
@@ -119,7 +286,39 @@ var AmbaHttpClient = class {
 		this.identity = opts.identity;
 		this.ensureSession = opts.ensureSession;
 		this.onSessionRefused = opts.onSessionRefused;
+		this.injectedFetch = opts.fetchImpl;
 		this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+		this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+		this.longRequestTimeoutMs = opts.longRequestTimeoutMs ?? DEFAULT_LONG_REQUEST_TIMEOUT_MS;
+	}
+	/**
+	* Send a request to an absolute URL outside the API's JSON envelope (a
+	* function invocation, a CDN download, the config route that reads the
+	* `ETag`) under a deadline. `read` takes what the caller needs from the
+	* response (the body as text, a `Blob`) and runs inside the same
+	* deadline, so a body that stops arriving fails too.
+	*
+	* A transport failure rejects with `NETWORK_ERROR` and the message
+	* `<label>: <cause>`; the deadline rejects with `NETWORK_ERROR` and
+	* `<label>: request timed out after <ms> ms`. `label` defaults to
+	* `Network error` and `timeoutMs` to the request deadline; the deadline
+	* widens with the request body and with `responseBytes`, the size the
+	* caller expects to download (see `exchange`). An `AmbaApiError` that
+	* `read` throws passes through unchanged.
+	*/
+	async send(url, init, read, opts = {}) {
+		const timeoutMs = opts.timeoutMs ?? this.requestTimeoutMs;
+		const label = opts.label ?? "Network error";
+		const fetchFn = this.injectedFetch ?? globalThis.fetch;
+		try {
+			return await exchange(timeoutMs, (signal) => fetchFn(url, withSignal(init, signal)), read, (ms) => timeoutError(label, ms), {
+				requestBytes: bodyByteLength(init.body),
+				responseBytes: opts.responseBytes,
+				fetchBuffersBody: true
+			});
+		} catch (err) {
+			throw asNetworkError(err, label);
+		}
 	}
 	/** Build the absolute URL for an API path, optionally with a query string. */
 	url(path, query) {
@@ -179,14 +378,19 @@ var AmbaHttpClient = class {
 			headers,
 			body: body === void 0 ? void 0 : JSON.stringify(body ?? {})
 		};
+		const timeoutMs = isLongApiPath(path) ? this.longRequestTimeoutMs : this.requestTimeoutMs;
 		let response;
+		let text;
 		try {
-			response = await this.fetchImpl(url, init);
+			({response, text} = await exchange(timeoutMs, (signal) => this.fetchImpl(url, withSignal(init, signal)), async (res) => ({
+				response: res,
+				text: res.status === 204 ? "" : await res.text()
+			}), (ms) => timeoutError("Network error", ms), { requestBytes: bodyByteLength(init.body) }));
 		} catch (err) {
-			throw new AmbaApiError("NETWORK_ERROR", `Network error: ${err instanceof Error ? err.message : typeof err === "string" ? err : "fetch failed"}`, err);
+			throw asNetworkError(err, "Network error");
 		}
 		try {
-			return await parseResponse(response);
+			return parseResponse(response, text);
 		} catch (err) {
 			if (!resent && storedToken && this.onSessionRefused && !path.startsWith("/v1/client/auth/") && err instanceof AmbaApiError && SESSION_REFUSED_CODES.has(err.code) && await this.recoverSession(storedToken, storedUserId)) return this.request(method, path, body, query, void 0, true);
 			throw err;
@@ -201,9 +405,21 @@ var AmbaHttpClient = class {
 		}
 	}
 };
-async function parseResponse(response) {
+/** The `NETWORK_ERROR` a passed deadline raises. */
+function timeoutError(label, timeoutMs) {
+	return new AmbaApiError("NETWORK_ERROR", `${label}: ${timeoutMessage(timeoutMs)}`, { timeoutMs });
+}
+/**
+* Wrap a transport failure as `NETWORK_ERROR` (`<label>: <cause>`). An
+* `AmbaApiError` (the deadline's own, or one a `send` reader throws) passes
+* through unchanged.
+*/
+function asNetworkError(err, label) {
+	if (err instanceof AmbaApiError) return err;
+	return new AmbaApiError("NETWORK_ERROR", `${label}: ${err instanceof Error ? err.message : typeof err === "string" ? err : "fetch failed"}`, err);
+}
+function parseResponse(response, text) {
 	if (response.status === 204) return null;
-	const text = await response.text();
 	const isJson = (response.headers.get("content-type") ?? "").includes("application/json");
 	if (!response.ok) throw mapHttpError(response, text, isJson);
 	if (text === "") return null;
@@ -899,7 +1115,16 @@ const DETERMINISTIC_ERROR_CODES = new Set([
 	"NOT_FOUND",
 	"CONFLICT",
 	"CONSENT_NOT_GRANTED",
-	"NOT_INITIALIZED"
+	"NOT_INITIALIZED",
+	"INVALID_JSON",
+	"INVALID_BODY",
+	"INVALID_EVENT",
+	"RESERVED_EVENT_NAME",
+	"INVALID_IDEMPOTENCY_KEY",
+	"INVALID_TIMESTAMP",
+	"INVALID_PROPERTIES",
+	"INVALID_TELEMETRY",
+	"IDEMPOTENCY_KEY_CONFLICT"
 ]);
 /**
 * Is this a deterministic server rejection — a coded error the server would
@@ -937,13 +1162,34 @@ function isOfflineError(err) {
 	if (typeof msg === "string" && /network (error|request failed)|failed to fetch|fetch failed|load failed/i.test(msg)) return true;
 	return !isOnline();
 }
-/** Generate a stable idempotency key for a queued op. */
+/**
+* Generate a stable idempotency key for a queued op: `amba_obx_` and a random
+* UUID. The server records event keys project-wide, so the UUID comes from
+* the runtime's secure random source: `crypto.randomUUID`, else
+* `crypto.getRandomValues` (Hermes has only the latter).
+*/
 function newIdempotencyKey() {
 	const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
 	if (c && typeof c.randomUUID === "function") return `amba_obx_${c.randomUUID()}`;
+	if (c && typeof c.getRandomValues === "function") {
+		const b = c.getRandomValues(new Uint8Array(16));
+		b[6] = b[6] & 15 | 64;
+		b[8] = b[8] & 63 | 128;
+		const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+		return `amba_obx_${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+	}
 	return `amba_obx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
 }
 /**
+* Whether a `track` with these properties can take the events route's keyed
+* path, which accepts a plain object or no properties. A JS caller can pass
+* something else (an array); such an event stays on the unkeyed path, which
+* stores it as it always has.
+*/
+function keyableProperties(properties) {
+	return properties === void 0 || properties === null || typeof properties === "object" && !Array.isArray(properties);
+}
+/**
 * Durable, ordered, idempotent offline outbox. Opt-in via `Amba.offline`.
 * Single in-flight flush is enforced so concurrent reconnect signals don't
 * double-replay.
@@ -1824,6 +2070,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
 /**
@@ -1924,6 +2460,7 @@ var CollectionSubscription = class {
 		return openStream({
 			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/collections/${pathSegment(this.name)}${qs}`,
 			authHeaders: this.ctx.authHeaders,
+			connectTimeoutMs: this.ctx.connectTimeoutMs,
 			onChange: cb,
 			options,
 			parse: parseRowChangeFrame
@@ -1948,6 +2485,7 @@ var ConversationSubscription = class {
 		return openStream({
 			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/conversations/${pathSegment(this.conversationId)}`,
 			authHeaders: this.ctx.authHeaders,
+			connectTimeoutMs: this.ctx.connectTimeoutMs,
 			onChange: cb,
 			options,
 			parse: parseRowChangeFrame
@@ -1972,6 +2510,7 @@ var GamificationSubscription = class {
 		return openStream({
 			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/gamification`,
 			authHeaders: this.ctx.authHeaders,
+			connectTimeoutMs: this.ctx.connectTimeoutMs,
 			onChange: cb,
 			options,
 			parse: parseGamificationFrame
@@ -2006,6 +2545,7 @@ function openStream(args) {
 					closeActive = connectOnce({
 						url: args.url,
 						headers,
+						connectTimeoutMs: args.connectTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
 						onFrame: (frame) => {
 							const ev = args.parse(frame);
 							if (ev !== null) args.onChange(ev);
@@ -2076,8 +2616,13 @@ function connectXhr(args, XHR) {
 	xhr.open("GET", args.url, true);
 	for (const [k, v] of Object.entries(args.headers)) xhr.setRequestHeader(k, v);
 	xhr.setRequestHeader("Accept", "text/event-stream");
+	const connectTimer = setTimeout(() => {
+		if (aborted || xhr.readyState >= 2) return;
+		args.onError(/* @__PURE__ */ new Error(`realtime connection timed out after ${args.connectTimeoutMs} ms`));
+	}, args.connectTimeoutMs);
 	xhr.onreadystatechange = () => {
 		if (aborted) return;
+		if (xhr.readyState >= 2) clearTimeout(connectTimer);
 		if (xhr.readyState === 3) {
 			if (xhr.status >= 400) return;
 			drain();
@@ -2101,10 +2646,12 @@ function connectXhr(args, XHR) {
 	try {
 		xhr.send();
 	} catch (err) {
+		clearTimeout(connectTimer);
 		args.onError(err);
 	}
 	return () => {
 		aborted = true;
+		clearTimeout(connectTimer);
 		try {
 			xhr.abort();
 		} catch {}
@@ -2119,14 +2666,14 @@ function connectFetchStream(args) {
 	let aborted = false;
 	(async () => {
 		try {
-			const resp = await fetch(args.url, {
+			const resp = await raceDeadline(fetch(args.url, {
 				method: "GET",
 				headers: {
 					...args.headers,
 					Accept: "text/event-stream"
 				},
 				signal: controller.signal
-			});
+			}), args.connectTimeoutMs, controller, (ms) => /* @__PURE__ */ new Error(`realtime connection timed out after ${ms} ms`));
 			if (!resp.ok || !resp.body) throw new Error(`realtime connect failed: HTTP ${resp.status}`);
 			const reader = resp.body.getReader();
 			const decoder = new TextDecoder();
@@ -2206,7 +2753,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.1";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -2250,6 +2797,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 {
@@ -2761,9 +3364,28 @@ function offlineStore(s) {
 	};
 }
 /**
+* Whether a live `track` (outbox on) carries its idempotency key:
+* engagement events whose properties the keyed path takes. Telemetry stays
+* on the unkeyed hot path, which writes no idempotency record and answers a
+* failed telemetry insert with 200; its replays from the outbox are keyed.
+*/
+function keyedLiveTrack(properties, telemetry) {
+	return telemetry !== true && keyableProperties(properties);
+}
+/**
+* A JSON copy of `properties`: exactly what a request body serializes, and
+* immune to the app changing the object after `track()` returns.
+*/
+function snapshotProperties(properties) {
+	if (properties === void 0 || properties === null) return void 0;
+	const text = JSON.stringify(properties);
+	return text === void 0 ? void 0 : JSON.parse(text);
+}
+/**
 * Replay one queued mutation against the live API, forwarding the op's
-* idempotency key on collection inserts so a write that landed before the
-* connection dropped is never double-applied (API migration 056).
+* idempotency key on collection inserts and tracked events so a write that
+* landed before the connection dropped is never double-applied (API
+* migration 056 for collections, `client_event_idempotency` for events).
 */
 async function replayOutboxOp(s, op) {
 	switch (op.kind) {
@@ -2785,8 +3407,9 @@ async function replayOutboxOp(s, op) {
 					event: op.event,
 					properties: op.properties ?? void 0,
 					anonymous_id: s.identity.getAnonymousId(),
-					timestamp: op.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-					...op.telemetry ? { telemetry: true } : {}
+					timestamp: op.occurredAt ?? op.enqueuedAt,
+					...op.telemetry ? { telemetry: true } : {},
+					...keyableProperties(op.properties) ? { idempotency_key: op.idempotencyKey } : {}
 				});
 			} catch (err) {
 				const code = err?.code;
@@ -2868,10 +3491,13 @@ const Amba = {
 			if (!Number.isInteger(flushIntervalMs) || flushIntervalMs < 0) throw new Error("Amba.configure: events.flushIntervalMs must be a non-negative integer");
 			if (!Number.isInteger(maxQueue) || maxQueue < 1) throw new Error("Amba.configure: events.maxQueue must be positive");
 		}
+		const deadlines = resolveRequestDeadlines(config);
 		const tokenStorage = config.tokenStorage ?? "secure";
 		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();
@@ -2879,6 +3505,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,
@@ -2889,6 +3517,8 @@ const Amba = {
 			deviceRegion: detectDeviceRegion(),
 			deviceOs: detectDeviceOs(),
 			identity,
+			requestTimeoutMs: deadlines.requestMs,
+			longRequestTimeoutMs: deadlines.longMs,
 			ensureSession: config.autoAnonymousSession === false ? void 0 : async (path) => {
 				if (pathSkipsLazySession(path)) return;
 				await ensureAnonymousSession(getState());
@@ -2912,6 +3542,11 @@ const Amba = {
 			resolvedFunctionsProjectId: null,
 			functionsProjectIdInflight: null,
 			persistence,
+			remoteValues,
+			refreshedFor: {
+				config: null,
+				flags: null
+			},
 			offlineEnabled: false,
 			offlineQueue: null,
 			eventQueue: null
@@ -2964,12 +3599,14 @@ const Amba = {
 	},
 	collection: (name) => new CollectionSubscription({
 		baseUrl: getState().baseUrl,
-		authHeaders: realtimeAuthHeaders
+		authHeaders: realtimeAuthHeaders,
+		connectTimeoutMs: getState().http.requestTimeoutMs
 	}, name),
 	get gamification() {
 		return new GamificationSubscription({
 			baseUrl: getState().baseUrl,
-			authHeaders: realtimeAuthHeaders
+			authHeaders: realtimeAuthHeaders,
+			connectTimeoutMs: getState().http.requestTimeoutMs
 		});
 	},
 	events: {
@@ -2977,13 +3614,16 @@ const Amba = {
 			const s = getState();
 			if (s.eventQueue && !options?.immediate) return s.eventQueue.enqueue(event, properties, options?.telemetry === true);
 			const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
+			const props = s.offlineEnabled ? snapshotProperties(properties) : properties;
 			const body = {
 				event,
-				properties: properties ?? void 0,
+				properties: props ?? void 0,
 				anonymous_id: s.identity.getAnonymousId(),
 				timestamp: occurredAt
 			};
 			if (options?.telemetry) body["telemetry"] = true;
+			const idempotencyKey = s.offlineEnabled ? newIdempotencyKey() : void 0;
+			if (idempotencyKey && keyedLiveTrack(props, options?.telemetry)) body["idempotency_key"] = idempotencyKey;
 			const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
 			try {
 				await s.http.post(P.events, body);
@@ -2992,9 +3632,10 @@ const Amba = {
 					await getOfflineQueue(s).enqueue({
 						kind: "track",
 						event,
-						properties,
+						properties: props,
 						telemetry: options?.telemetry,
-						occurredAt
+						occurredAt,
+						idempotencyKey
 					}, outboxTicket);
 					return;
 				}
@@ -3162,7 +3803,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) {
@@ -3453,21 +4097,25 @@ const Amba = {
 			await getState().http.delete(`${P.storage}/${encodePathSegment(assetId)}`);
 		},
 		download: async (assetId) => {
-			const assetEnv = await getState().http.get(`${P.storage}/${encodePathSegment(assetId)}`);
+			const s = getState();
+			const assetEnv = await s.http.get(`${P.storage}/${encodePathSegment(assetId)}`);
 			const cdnUrl = assetEnv.data.url ?? assetEnv.data.storage_url ?? "";
 			if (!cdnUrl) throw new AmbaApiError("NOT_FOUND", "asset has no resolvable CDN url");
-			let response;
-			try {
-				response = await (globalThis.fetch ?? fetch)(cdnUrl, { method: "GET" });
-			} catch (err) {
-				throw new AmbaApiError("NETWORK_ERROR", `Network error: ${err instanceof Error ? err.message : String(err)}`, err);
-			}
-			if (!response.ok) {
-				const text = await response.text();
-				const ct = response.headers.get("content-type") ?? "";
-				throw mapHttpError(response, text, ct.includes("application/json"));
-			}
-			return response.blob();
+			const sizeBytes = assetEnv.data.size_bytes;
+			const { response, blob, text } = await s.http.send(cdnUrl, { method: "GET" }, async (res) => res.ok ? {
+				response: res,
+				blob: await res.blob(),
+				text: ""
+			} : {
+				response: res,
+				blob: null,
+				text: await res.text()
+			}, {
+				timeoutMs: s.http.longRequestTimeoutMs,
+				responseBytes: typeof sizeBytes === "number" ? sizeBytes : void 0
+			});
+			if (!blob) throw mapHttpError(response, text, (response.headers.get("content-type") ?? "").includes("application/json"));
+			return blob;
 		}
 	},
 	push: {
@@ -3515,27 +4163,30 @@ const Amba = {
 	functions: { invoke: async (name, body, options) => {
 		const s = getState();
 		if (!name || name.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.functions.invoke: a function name is required.");
+		let timeoutMs;
+		try {
+			timeoutMs = readTimeout("Amba.functions.invoke: timeoutMs", options?.timeoutMs, s.http.longRequestTimeoutMs);
+		} catch (err) {
+			throw new AmbaApiError("INVALID_ARGUMENT", err.message);
+		}
 		const url = await resolveFunctionUrl(s, name);
 		const method = options?.method ?? "POST";
 		const headers = s.http.buildHeaders(options?.headers);
 		let requestBody;
 		if (body !== void 0 && method !== "GET") requestBody = JSON.stringify(body);
 		else delete headers["Content-Type"];
-		let response;
-		try {
-			response = await (globalThis.fetch ?? fetch)(url, {
-				method,
-				headers,
-				body: requestBody
-			});
-		} catch (err) {
-			throw new AmbaApiError("NETWORK_ERROR", `Amba.functions.invoke("${name}") 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"));
-		}
+		const { response, text } = await s.http.send(url, {
+			method,
+			headers,
+			body: requestBody
+		}, async (res) => ({
+			response: res,
+			text: await res.text()
+		}), {
+			timeoutMs,
+			label: `Amba.functions.invoke("${name}") network error`
+		});
+		if (!response.ok) throw mapHttpError(response, text, (response.headers.get("content-type") ?? "").includes("application/json"));
 		if (!text) return void 0;
 		try {
 			return JSON.parse(text);
@@ -3543,54 +4194,63 @@ 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, {
+	config: {
+		fetch: async () => {
+			const s = getState();
+			const ticket = s.remoteValues.ticket();
+			const url = s.http.url(P.config);
+			const headers = s.http.buildHeaders();
+			const { response, text } = await s.http.send(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 ?? {}
-		};
-	} },
+			}, async (res) => ({
+				response: res,
+				text: await res.text()
+			}));
+			if (!response.ok) throw mapHttpError(response, text, (response.headers.get("content-type") ?? "").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) => {
@@ -3770,7 +4430,8 @@ const Amba = {
 	messaging: {
 		conversation: (conversationId) => new ConversationSubscription({
 			baseUrl: getState().baseUrl,
-			authHeaders: realtimeAuthHeaders
+			authHeaders: realtimeAuthHeaders,
+			connectTimeoutMs: getState().http.requestTimeoutMs
 		}, conversationId),
 		createConversation: async (request) => {
 			return (await getState().http.post(`${P.messaging}/conversations`, request)).data;