@layers/amba-react-native 4.2.0 → 4.2.1

package/dist/index.cjs

@@ -84,6 +84,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. */
@@ -100,6 +261,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 +280,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,14 +372,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;
@@ -195,9 +399,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 +1109,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 +1156,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 +2454,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 +2479,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 +2504,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 +2539,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 +2610,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 +2640,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 +2660,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 +2747,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.1";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
@@ -3101,9 +3358,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 +3401,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 +3485,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 +3511,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 +3593,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 +3608,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 +3626,10 @@ const Amba = {
 					await getOfflineQueue(s).enqueue({
 						kind: "track",
 						event,
-						properties,
+						properties: props,
 						telemetry: options?.telemetry,
-						occurredAt
+						occurredAt,
+						idempotencyKey
 					}, outboxTicket);
 					return;
 				}
@@ -3805,21 +4091,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 +4157,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 +4194,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 +4424,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;