@layers/amba-react-native 4.2.0 → 4.2.2

package/dist/index.cjs

@@ -84,12 +84,200 @@ 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. */
 const DEFAULT_BASE_URL = "https://api.amba.dev";
-/** Server codes for a session token the server no longer accepts. */
-const SESSION_REFUSED_CODES = new Set(["SESSION_REVOKED", "INVALID_SESSION_TOKEN"]);
+/**
+* Server codes for a session token the server no longer accepts.
+* `INVALID_SESSION` is the code the auth routes that verify the session
+* themselves (`/identifiers`, `/link`, `/unlink`) answer with.
+*/
+const SESSION_REFUSED_CODES = new Set([
+	"SESSION_REVOKED",
+	"INVALID_SESSION_TOKEN",
+	"INVALID_SESSION"
+]);
+/** True for a server error that refused the session token a call sent. */
+function isSessionRefusedError(err) {
+	return err instanceof AmbaApiError && SESSION_REFUSED_CODES.has(err.code);
+}
+const AUTH_PATH_PREFIX = "/v1/client/auth/";
+/**
+* The auth routes that read the session from the `Authorization` header and
+* mint nothing: a refused session on them recovers like it does on any
+* other authenticated call. The other auth routes stay out of the
+* recovery: `/refresh` is the recovery itself, `/logout` ends the session,
+* the sign-in, sign-up, OTP and magic-link routes take credentials (a 401
+* there is a credential error), and `/link` and `/unlink` carry the session
+* in their body, so their callers recover and rebuild the body themselves.
+*/
+const SESSION_HEADER_AUTH_PATHS = new Set([`${AUTH_PATH_PREFIX}me`, `${AUTH_PATH_PREFIX}identifiers`]);
+/** Whether a refused session on `path` goes through `onSessionRefused`. */
+function recoversRefusedSession(path) {
+	return !path.startsWith(AUTH_PATH_PREFIX) || SESSION_HEADER_AUTH_PATHS.has(path);
+}
 var AmbaHttpClient = class {
 	apiKey;
 	baseUrl;
@@ -100,6 +288,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) {
@@ -113,7 +307,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) {
@@ -173,16 +399,21 @@ 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);
+			if (!resent && storedToken && this.onSessionRefused && recoversRefusedSession(path) && isSessionRefusedError(err) && await this.recoverSession(storedToken, storedUserId)) return this.request(method, path, body, query, void 0, true);
 			throw err;
 		}
 	}
@@ -195,9 +426,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;
@@ -893,7 +1136,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
@@ -931,13 +1183,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.
@@ -2208,6 +2481,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
@@ -2232,6 +2506,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
@@ -2256,6 +2531,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
@@ -2290,6 +2566,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);
@@ -2360,8 +2637,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();
@@ -2385,10 +2667,12 @@ function connectXhr(args, XHR) {
 	try {
 		xhr.send();
 	} catch (err) {
+		clearTimeout(connectTimer);
 		args.onError(err);
 	}
 	return () => {
 		aborted = true;
+		clearTimeout(connectTimer);
 		try {
 			xhr.abort();
 		} catch {}
@@ -2403,14 +2687,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();
@@ -2490,7 +2774,7 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.2.0";
+const SDK_VERSION = "4.2.2";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -2776,7 +3060,11 @@ function trackLink(state_, link) {
 }
 /**
 * After the server refused the stored session token on an authenticated
-* call (`SESSION_REVOKED`, `INVALID_SESSION_TOKEN`). True when a usable
+* call (`SESSION_REVOKED`, `INVALID_SESSION_TOKEN`, `INVALID_SESSION`). The
+* HTTP client runs it for calls that send the session in the
+* `Authorization` header, `/v1/client/auth/me` and `/identifiers`
+* included; `withBodySession` runs it for the link and unlink calls, which
+* send the session in their body. True when a usable
 * session for the user the call was sent for is stored afterwards, so the
 * call is sent once more as that user:
 *   - a link in flight on this device stores the pair it returns, which is
@@ -2810,6 +3098,40 @@ async function recoverRefusedSession(state_, usedToken, usedUserId) {
 	return usableForCaller(state_.identity.getSessionToken());
 }
 /**
+* Send an auth call that carries the stored session token in its body
+* (`/link`, `/unlink`). `send` builds the request from the token it is
+* given. When the server refuses that token, the session recovers through
+* `recoverRefusedSession` (one refresh shared with every other refused
+* call) and the call is sent once more with the recovered token; a second
+* refusal reaches the app. A link waits here outside `trackLink`: its own
+* failed attempt has already left `linksInflight` (the removal is the first
+* reaction on that promise), so recovery never waits on itself.
+*/
+async function withBodySession(state_, send) {
+	const usedToken = state_.identity.getSessionToken();
+	if (!usedToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
+	const usedUserId = state_.identity.getAppUserId();
+	try {
+		return await send(usedToken);
+	} catch (err) {
+		if (!isSessionRefusedError(err)) throw err;
+		if (!await recoverRefusedSession(state_, usedToken, usedUserId)) throw err;
+		const recovered = state_.identity.getSessionToken();
+		if (!recovered) throw err;
+		return send(recovered);
+	}
+}
+/**
+* Before a read of the current session (`me`, `getSession`,
+* `getCurrentIdentifiers`) while no session token is stored: wait for the
+* launch restore or sign-in in flight, so a check made at launch sees the
+* session it restores.
+*/
+async function settleSessionInFlight(state_) {
+	if (state_.identity.getSessionToken() || !state_.anonSignInInflight) return;
+	await state_.anonSignInInflight.catch(() => {});
+}
+/**
 * Continue the stored session with its refresh token. True when it did.
 * False when there is no refresh token, or the server rejected it: the
 * session is then cleared (the anonymous id rotates unless the session was
@@ -2920,7 +3242,10 @@ async function refreshSessionOnce(state_) {
 * account's rotated anonymous id is adopted.
 */
 function postLink(state_, body) {
-	return trackLink(state_, postLinkOnce(state_, body));
+	return withBodySession(state_, (sessionToken) => trackLink(state_, postLinkOnce(state_, {
+		...body,
+		session_token: sessionToken
+	})));
 }
 async function postLinkOnce(state_, body) {
 	const env = await state_.http.post(P.authLink, {
@@ -2956,12 +3281,10 @@ async function postUserNoRotate(state_, path, body) {
 }
 async function unlinkProvider(provider) {
 	const s = getState();
-	const sessionToken = s.identity.getSessionToken();
-	if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-	return postUserNoRotate(s, P.authUnlink, {
+	return withBodySession(s, (sessionToken) => postUserNoRotate(s, P.authUnlink, {
 		provider,
 		session_token: sessionToken
-	});
+	}));
 }
 function requireEmail(email) {
 	const trimmed = email.trim();
@@ -3101,9 +3424,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) {
@@ -3125,8 +3467,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;
@@ -3208,6 +3551,7 @@ 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;
@@ -3233,6 +3577,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());
@@ -3313,12 +3659,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: {
@@ -3326,13 +3674,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);
@@ -3341,9 +3692,10 @@ const Amba = {
 					await getOfflineQueue(s).enqueue({
 						kind: "track",
 						event,
-						properties,
+						properties: props,
 						telemetry: options?.telemetry,
-						occurredAt
+						occurredAt,
+						idempotencyKey
 					}, outboxTicket);
 					return;
 				}
@@ -3446,52 +3798,38 @@ const Amba = {
 			if (providerTrimmed === "") throw new AmbaApiError("VALIDATION_ERROR", "provider must not be empty");
 			if (typeof credential !== "string" || credential.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "credential must not be empty");
 			const s = getState();
-			const sessionToken = s.identity.getSessionToken();
-			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return trackLink(s, postAuth(s, P.authLink, {
+			return withBodySession(s, (sessionToken) => trackLink(s, postAuth(s, P.authLink, {
 				provider: providerTrimmed,
 				token: credential,
 				session_token: sessionToken,
 				...nonceField(options)
-			}));
+			})));
 		},
 		linkSmsOtp: async (phone, code) => {
 			requireE164Phone(phone);
 			requireOtpCode(code);
-			const s = getState();
-			const sessionToken = s.identity.getSessionToken();
-			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postLink(s, {
+			return postLink(getState(), {
 				provider: "sms_otp",
 				phone,
-				code,
-				session_token: sessionToken
+				code
 			});
 		},
 		linkEmailOtp: async (email, code) => {
 			requireEmail(email);
 			requireOtpCode(code);
-			const s = getState();
-			const sessionToken = s.identity.getSessionToken();
-			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postLink(s, {
+			return postLink(getState(), {
 				provider: "email_otp",
 				email,
-				code,
-				session_token: sessionToken
+				code
 			});
 		},
 		linkEmailPassword: async (email, password) => {
 			requireEmail(email);
 			requirePassword(password);
-			const s = getState();
-			const sessionToken = s.identity.getSessionToken();
-			if (!sessionToken) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return postLink(s, {
+			return postLink(getState(), {
 				provider: "email_password",
 				email,
-				password,
-				session_token: sessionToken
+				password
 			});
 		},
 		unlinkSmsOtp: async () => unlinkProvider("sms_otp"),
@@ -3500,6 +3838,7 @@ const Amba = {
 		unlinkGoogle: async () => unlinkProvider("google"),
 		getCurrentIdentifiers: async () => {
 			const s = getState();
+			await settleSessionInFlight(s);
 			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
 			return (await s.http.get(P.authIdentifiers)).data.identifiers;
 		},
@@ -3526,13 +3865,20 @@ const Amba = {
 		refresh: async () => refreshSession(getState()),
 		me: async () => {
 			const s = getState();
+			await settleSessionInFlight(s);
 			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
 			return normalizeUserAuthProviders((await s.http.get(P.authMe)).data);
 		},
 		getSession: async () => {
 			const s = getState();
+			await settleSessionInFlight(s);
 			if (!s.identity.isAuthenticated()) return null;
-			return snapshotSession(normalizeUserAuthProviders((await s.http.get(P.authMe)).data));
+			try {
+				return snapshotSession(normalizeUserAuthProviders((await s.http.get(P.authMe)).data));
+			} catch (err) {
+				if (isSessionRefusedError(err) && !s.identity.isAuthenticated()) return null;
+				throw err;
+			}
 		},
 		getAnonymousId: async () => {
 			return getState().identity.getAnonymousId();
@@ -3805,21 +4151,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: {
@@ -3867,27 +4217,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);
@@ -3901,20 +4254,14 @@ const Amba = {
 			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"));
-			}
+			const { response, text } = await s.http.send(url, {
+				method: "GET",
+				headers
+			}, 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);
@@ -4137,7 +4484,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;