@layers/amba-react-native 4.0.5 → 4.0.7

package/dist/index.cjs

@@ -42,6 +42,10 @@ var AsyncStoragePersistence = class {
 	constructor(prefix) {
 		this.prefix = prefix;
 	}
+	/** Batching promises durable enqueue, so memory-only fallback is invalid. */
+	async assertDurable() {
+		if (!await getStorage()) throw new Error("Amba event batching requires @react-native-async-storage/async-storage");
+	}
 	async hydrate() {}
 	async read(key) {
 		const fullKey = `${this.prefix}:${key}`;
@@ -54,15 +58,15 @@ var AsyncStoragePersistence = class {
 	}
 	async write(key, value) {
 		const fullKey = `${this.prefix}:${key}`;
-		this.memoryCache.set(fullKey, value);
 		const storage = await getStorage();
 		if (storage) await storage.setItem(fullKey, value);
+		this.memoryCache.set(fullKey, value);
 	}
 	async delete(key) {
 		const fullKey = `${this.prefix}:${key}`;
-		this.memoryCache.delete(fullKey);
 		const storage = await getStorage();
 		if (storage) await storage.removeItem(fullKey);
+		this.memoryCache.delete(fullKey);
 	}
 };
 
@@ -134,18 +138,24 @@ var AmbaHttpClient = class {
 	async post(path, body, query) {
 		return this.request("POST", path, body, query);
 	}
+	/** Send a queued event with the session captured for its original user. */
+	async postWithSession(path, body, sessionToken) {
+		return this.request("POST", path, body, void 0, sessionToken);
+	}
 	async patch(path, body) {
 		return this.request("PATCH", path, body);
 	}
 	async delete(path) {
 		return this.request("DELETE", path);
 	}
-	async request(method, path, body, query) {
-		if (this.ensureSession && !this.identity.getSessionToken()) await this.ensureSession(path);
+	async request(method, path, body, query, sessionToken) {
+		if (this.ensureSession && !sessionToken && !this.identity.getSessionToken()) await this.ensureSession(path);
 		const url = this.url(path, query);
+		const headers = this.buildHeaders();
+		if (sessionToken) headers.Authorization = `Bearer ${sessionToken}`;
 		const init = {
 			method,
-			headers: this.buildHeaders(),
+			headers,
 			body: body === void 0 ? void 0 : JSON.stringify(body ?? {})
 		};
 		let response;
@@ -665,6 +675,322 @@ async function withOptimistic(spec) {
 	}
 }
 
+//#endregion
+//#region src/event-batch-queue.ts
+const MAX_BYTES = 512 * 1024;
+const HELD_TTL_MS = 720 * 60 * 60 * 1e3;
+const COALESCE_MS = 250;
+function byteLength(s) {
+	if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(s).length;
+	return encodeURIComponent(s).replace(/%[A-Fa-f0-9]{2}|./g, "x").length;
+}
+function wire(e) {
+	return {
+		event: e.event,
+		properties: e.properties,
+		timestamp: e.timestamp,
+		telemetry: e.telemetry,
+		idempotency_key: e.idempotency_key
+	};
+}
+function safeDrop(cb, e, reason, code) {
+	try {
+		cb?.({
+			idempotencyKey: e.idempotency_key,
+			event: e.event,
+			userId: e.userId,
+			reason,
+			code
+		});
+	} catch {}
+}
+/** Durable queue owned by one configured project and storage prefix. */
+var EventBatchQueue = class {
+	events = [];
+	pending = [];
+	writeTimer = null;
+	flushTimer = null;
+	retryTimer = null;
+	serialized = Promise.resolve();
+	inFlight = null;
+	disposed = false;
+	online = null;
+	batchingEnabled = true;
+	failures = 0;
+	clearingUsers = /* @__PURE__ */ new Set();
+	constructor(store, storageKey, options, identity, postBatch, postSingle) {
+		this.store = store;
+		this.storageKey = storageKey;
+		this.options = options;
+		this.identity = identity;
+		this.postBatch = postBatch;
+		this.postSingle = postSingle;
+	}
+	async start() {
+		const raw = await this.store.get(this.storageKey);
+		if (raw) try {
+			const parsed = JSON.parse(raw);
+			this.events = Array.isArray(parsed) ? parsed : [];
+		} catch {
+			this.events = [];
+		}
+		await this.expireHeld();
+		if (this.events.length) this.flush();
+	}
+	exclusive(work) {
+		const run = this.serialized.then(work);
+		this.serialized = run.catch(() => void 0);
+		return run;
+	}
+	async save() {
+		if (this.events.length) await this.store.set(this.storageKey, JSON.stringify(this.events));
+		else await this.store.delete(this.storageKey);
+	}
+	enqueue(event, properties, telemetry) {
+		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error("Amba event queue disposed"));
+		const id = this.identity();
+		const item = {
+			event,
+			properties,
+			telemetry,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			idempotency_key: newIdempotencyKey(),
+			userId: id.sessionToken ? id.userId : null,
+			anonymousId: id.anonymousId
+		};
+		if (!event.trim()) return Promise.reject(/* @__PURE__ */ new Error("event name must be non-empty"));
+		if (byteLength(JSON.stringify({ events: [wire(item)] })) > MAX_BYTES) {
+			safeDrop(this.options.onDrop, item, "oversized");
+			return Promise.reject(/* @__PURE__ */ new Error("event exceeds 512 KB batch limit"));
+		}
+		return new Promise((resolve, reject) => {
+			this.pending.push({
+				event: item,
+				resolve,
+				reject
+			});
+			if (!this.writeTimer) this.writeTimer = setTimeout(() => {
+				this.persistPending();
+			}, COALESCE_MS);
+		});
+	}
+	async persistPending() {
+		if (this.writeTimer) clearTimeout(this.writeTimer);
+		this.writeTimer = null;
+		const batch = this.pending.splice(0);
+		if (!batch.length) return;
+		try {
+			let evictedKeys = /* @__PURE__ */ new Set();
+			await this.exclusive(async () => {
+				const before = this.events;
+				this.events = [...this.events, ...batch.map((p) => p.event)];
+				const evicted = [];
+				while (this.events.length > this.options.maxQueue) {
+					const idx = this.events.findIndex((e) => e.telemetry);
+					if (idx < 0) break;
+					evicted.push(this.events[idx]);
+					this.events.splice(idx, 1);
+				}
+				try {
+					await this.save();
+				} catch (err) {
+					this.events = before;
+					throw err;
+				}
+				evictedKeys = new Set(evicted.map((e) => e.idempotency_key));
+				for (const e of evicted) safeDrop(this.options.onDrop, e, "telemetry_evicted");
+			});
+			for (const p of batch) if (evictedKeys.has(p.event.idempotency_key)) p.reject(/* @__PURE__ */ new Error("event evicted before durable enqueue"));
+			else p.resolve();
+			this.schedule();
+			if (this.online !== false && this.events.length >= this.options.batchSize) this.flush();
+		} catch (err) {
+			for (const p of batch) p.reject(err);
+		}
+	}
+	setOnline(value) {
+		const wasOnline = this.online;
+		this.online = value;
+		if (!value) {
+			this.cancelTimers();
+			return;
+		}
+		this.schedule();
+		if (wasOnline !== true) this.flush();
+	}
+	setBatchingEnabled(enabled) {
+		this.batchingEnabled = enabled;
+		if (this.online !== false) this.flush();
+	}
+	get isBatchingEnabled() {
+		return this.batchingEnabled;
+	}
+	async pendingCount(userId) {
+		await this.persistPending();
+		return this.events.filter((e) => userId === void 0 || e.userId === userId).length;
+	}
+	async clear(userId) {
+		this.clearingUsers.add(userId);
+		try {
+			await this.inFlight?.catch(() => void 0);
+			await this.persistPending();
+			await this.exclusive(async () => {
+				const prior = this.events;
+				const id = this.identity();
+				this.events = this.events.filter((e) => e.userId !== userId && !(id.userId === userId && e.userId === null && e.anonymousId === id.anonymousId));
+				try {
+					await this.save();
+				} catch (err) {
+					this.events = prior;
+					throw err;
+				}
+			});
+		} finally {
+			this.clearingUsers.delete(userId);
+			this.schedule();
+		}
+	}
+	async expireHeld() {
+		const current = this.identity();
+		await this.exclusive(async () => {
+			const now = Date.now();
+			const dropped = [];
+			const next = [];
+			for (const e of this.events) {
+				if (e.userId && e.userId !== current.userId || !e.userId && e.anonymousId !== current.anonymousId) {
+					e.heldAt ??= new Date(now).toISOString();
+					if (now - Date.parse(e.heldAt) >= HELD_TTL_MS) {
+						dropped.push(e);
+						continue;
+					}
+				} else e.heldAt = void 0;
+				next.push(e);
+			}
+			this.events = next;
+			await this.save();
+			for (const e of dropped) safeDrop(this.options.onDrop, e, "held_expired");
+		});
+	}
+	cancelTimers() {
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		if (this.retryTimer) clearTimeout(this.retryTimer);
+		this.flushTimer = this.retryTimer = null;
+	}
+	schedule() {
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		this.flushTimer = null;
+		if (this.disposed || this.online !== true || this.failures > 0 || this.options.flushIntervalMs === 0) return;
+		const id = this.identity();
+		if (!id.sessionToken || !id.userId) return;
+		const eligible = this.events.filter((e) => e.userId === id.userId || e.userId === null && e.anonymousId === id.anonymousId);
+		if (!eligible.length) return;
+		const oldest = Math.min(...eligible.map((e) => Date.parse(e.timestamp)));
+		const wait = Math.max(0, oldest + this.options.flushIntervalMs - Date.now());
+		this.flushTimer = setTimeout(() => {
+			this.flush();
+		}, wait);
+	}
+	retry() {
+		this.failures += 1;
+		if (this.retryTimer) clearTimeout(this.retryTimer);
+		if (this.online !== true) return;
+		const delay$1 = Math.min(6e4, 1e3 * 2 ** Math.min(this.failures - 1, 6));
+		this.retryTimer = setTimeout(() => {
+			this.flush();
+		}, delay$1);
+	}
+	async flush() {
+		if (this.inFlight) return this.inFlight;
+		this.inFlight = this.runFlush().finally(() => {
+			this.inFlight = null;
+		});
+		return this.inFlight;
+	}
+	async runFlush() {
+		await this.persistPending();
+		if (this.disposed || this.online === false) return {
+			sent: 0,
+			rejected: 0,
+			remaining: this.events.length
+		};
+		await this.expireHeld();
+		const id = this.identity();
+		if (!id.sessionToken || !id.userId) return {
+			sent: 0,
+			rejected: 0,
+			remaining: this.events.length
+		};
+		let sent = 0;
+		let rejected = 0;
+		for (;;) {
+			if (this.disposed || this.online === false || this.clearingUsers.has(id.userId) || this.identity().userId !== id.userId) break;
+			const eligible = this.events.filter((e) => e.userId === id.userId || e.userId === null && e.anonymousId === id.anonymousId);
+			if (!eligible.length) break;
+			const selected = [];
+			for (const e of eligible) {
+				if (selected.length >= this.options.batchSize) break;
+				const candidate = [...selected, e];
+				if (byteLength(JSON.stringify({ events: candidate.map(wire) })) > MAX_BYTES) break;
+				selected.push(e);
+			}
+			if (!selected.length) break;
+			await this.exclusive(async () => {
+				for (const e of selected) if (e.userId === null) e.userId = id.userId;
+				await this.save();
+			});
+			if (this.clearingUsers.has(id.userId) || this.identity().userId !== id.userId) break;
+			try {
+				const ack = this.batchingEnabled ? await this.postBatch({ events: selected.map(wire) }, id.sessionToken) : { data: {
+					accepted: [],
+					rejected: []
+				} };
+				if (!this.batchingEnabled) for (const e of selected) {
+					await this.postSingle(wire(e), id.sessionToken);
+					ack.data.accepted.push({
+						idempotency_key: e.idempotency_key,
+						status: "inserted"
+					});
+				}
+				const accepted = new Set(ack.data.accepted.map((a) => a.idempotency_key));
+				const drops = new Map(ack.data.rejected.map((r) => [r.idempotency_key, r.code]));
+				const known = new Set(selected.map((e) => e.idempotency_key));
+				if ([...accepted, ...drops.keys()].some((k) => !known.has(k))) throw new Error("event batch returned unknown key");
+				if (accepted.size + drops.size !== selected.length) throw new Error("event batch omitted acknowledgments");
+				await this.exclusive(async () => {
+					const prior = this.events;
+					this.events = this.events.filter((e) => !accepted.has(e.idempotency_key) && !drops.has(e.idempotency_key));
+					try {
+						await this.save();
+					} catch (err) {
+						this.events = prior;
+						throw err;
+					}
+				});
+				sent += accepted.size;
+				rejected += drops.size;
+				for (const e of selected) if (drops.has(e.idempotency_key)) safeDrop(this.options.onDrop, e, "server_rejected", drops.get(e.idempotency_key));
+				this.failures = 0;
+			} catch {
+				this.retry();
+				break;
+			}
+		}
+		this.schedule();
+		return {
+			sent,
+			rejected,
+			remaining: this.events.length
+		};
+	}
+	async dispose() {
+		this.disposed = true;
+		this.cancelTimers();
+		await this.persistPending();
+		await this.inFlight?.catch(() => void 0);
+		await this.serialized;
+	}
+};
+
 //#endregion
 //#region src/push-rotation.ts
 /**
@@ -1150,13 +1476,14 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.0.5";
+const SDK_VERSION = "4.0.7";
 /**
 * Default host that serves deployed functions. `Amba.functions.invoke(name)`
 * targets `https://<projectId>.<DEFAULT_FUNCTIONS_HOST>/<name>` unless a
 * `functionsBaseUrl` override is configured.
 */
 const DEFAULT_FUNCTIONS_HOST = "fn.amba.host";
+const PROJECT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 let state = null;
 /**
 * Monotonic token identifying the current offline activation. Bumped on every
@@ -1202,6 +1529,58 @@ function notifyAuthSubscribers(session) {
 		if (typeof console !== "undefined") console.error("[amba] onAuthStateChange callback threw", err);
 	}
 }
+function normalizeAuthProviderNames(value) {
+	let normalized = value;
+	if (typeof normalized === "string") {
+		const trimmed = normalized.trim();
+		if (trimmed === "") return [];
+		try {
+			normalized = JSON.parse(trimmed);
+		} catch {
+			return [trimmed];
+		}
+	}
+	if (!Array.isArray(normalized)) {
+		if (normalized && typeof normalized === "object") {
+			const provider = normalized.provider;
+			return typeof provider === "string" ? [provider] : [];
+		}
+		return [];
+	}
+	return normalized.map((entry) => {
+		if (typeof entry === "string") {
+			const trimmed = entry.trim();
+			if (trimmed === "") return null;
+			try {
+				const parsed = JSON.parse(trimmed);
+				if (parsed && typeof parsed === "object") {
+					const provider = parsed.provider;
+					return typeof provider === "string" ? provider : null;
+				}
+			} catch {
+				return entry;
+			}
+			return entry;
+		}
+		if (entry && typeof entry === "object") {
+			const provider = entry.provider;
+			return typeof provider === "string" ? provider : null;
+		}
+		return null;
+	}).filter((provider) => provider !== null);
+}
+function normalizeUserAuthProviders(user) {
+	return {
+		...user,
+		auth_providers: normalizeAuthProviderNames(user.auth_providers)
+	};
+}
+function normalizeAuthResult(result) {
+	return {
+		...result,
+		user: normalizeUserAuthProviders(result.user)
+	};
+}
 async function notifyFromAuthResult(result) {
 	notifyAuthSubscribers(snapshotSession(result.user));
 }
@@ -1218,8 +1597,9 @@ async function persistAuthResult(state_, result) {
 	});
 }
 async function postAuth(state_, path, body) {
-	const result = (await state_.http.post(path, body)).data;
+	const result = normalizeAuthResult((await state_.http.post(path, body)).data);
 	await persistAuthResult(state_, result);
+	state_.eventQueue?.flush();
 	await notifyFromAuthResult(result);
 	return result;
 }
@@ -1250,7 +1630,7 @@ async function ensureAnonymousSession(state_) {
 * Existing session tokens stay untouched.
 */
 async function postUserNoRotate(state_, path, body) {
-	return (await state_.http.post(path, body)).data.user;
+	return normalizeUserAuthProviders((await state_.http.post(path, body)).data.user);
 }
 async function unlinkProvider(provider) {
 	const s = getState();
@@ -1341,20 +1721,37 @@ function encodePathSegment(s) {
 	return encodeURIComponent(s);
 }
 /**
-* Resolve the full invocation URL for a deployed function. With
-* `functionsBaseUrl` configured we POST to `<base>/<name>` verbatim;
-* otherwise we resolve the server-side project id once (via
-* `diagnostics.ping`, cached) and target
-* `https://<projectId>.fn.amba.host/<name>`.
+* Resolve the full invocation URL for a deployed function. Resolution checks
+* `functionsBaseUrl` first, then uses a UUID-shaped configured project id
+* directly, and finally falls back to a deduped `diagnostics.ping` for the
+* authoritative server-side project id. The resolved default-host id is
+* cached for subsequent invokes.
 */
 async function resolveFunctionUrl(s, name) {
 	if (s.functionsBaseUrl) return `${s.functionsBaseUrl.replace(/\/$/, "")}/${encodeURIComponent(name)}`;
-	if (!s.resolvedFunctionsProjectId) {
-		const ping = await Amba.diagnostics.ping();
-		if (!ping.ok || !ping.server_project_id) throw new AmbaApiError("FUNCTIONS_HOST_UNRESOLVED", "Could not resolve the functions host for this project. Pass `functionsBaseUrl` to Amba.configure() to invoke functions explicitly.", ping);
-		s.resolvedFunctionsProjectId = ping.server_project_id;
+	return `https://${await resolveFunctionsProjectId(s)}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+}
+async function resolveFunctionsProjectId(s) {
+	if (s.resolvedFunctionsProjectId) return s.resolvedFunctionsProjectId;
+	if (PROJECT_ID_PATTERN.test(s.projectId)) {
+		s.resolvedFunctionsProjectId = s.projectId.toLowerCase();
+		return s.resolvedFunctionsProjectId;
 	}
-	return `https://${s.resolvedFunctionsProjectId}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+	if (!s.functionsProjectIdInflight) {
+		const resolution = (async () => {
+			const ping = await Amba.diagnostics.ping();
+			if (!ping.ok || !ping.server_project_id) throw new AmbaApiError("FUNCTIONS_HOST_UNRESOLVED", "Could not resolve the functions host for this project. Pass `functionsBaseUrl` to Amba.configure() to invoke functions explicitly.", ping);
+			s.resolvedFunctionsProjectId = ping.server_project_id;
+			return ping.server_project_id;
+		})();
+		s.functionsProjectIdInflight = resolution;
+		resolution.then(() => {
+			if (s.functionsProjectIdInflight === resolution) s.functionsProjectIdInflight = null;
+		}, () => {
+			if (s.functionsProjectIdInflight === resolution) s.functionsProjectIdInflight = null;
+		});
+	}
+	return s.functionsProjectIdInflight;
 }
 /**
 * Bridge the AsyncStorage-backed persistence to the {@link KvStore} the
@@ -1431,7 +1828,16 @@ const Amba = {
 	configure: async (config) => {
 		if (!config.projectId || config.projectId.trim() === "") throw new Error("Amba.configure: projectId is required");
 		if (!config.clientKey || config.clientKey.trim() === "") throw new Error("Amba.configure: clientKey is required");
+		const batchSize = config.events?.batchSize ?? 100;
+		const flushIntervalMs = config.events?.flushIntervalMs ?? 6e4;
+		const maxQueue = config.events?.maxQueue ?? 1e4;
+		if (config.events?.batching) {
+			if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 500) throw new Error("Amba.configure: events.batchSize must be 1–500");
+			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 persistence = new AsyncStoragePersistence(config.storagePrefix ?? "amba");
+		if (config.events?.batching) await persistence.assertDurable();
 		await persistence.hydrate();
 		const identity = await IdentityStore.create(persistence);
 		const baseUrl = (config.apiUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
@@ -1450,7 +1856,9 @@ const Amba = {
 		const prior = state;
 		_offlineEnableToken += 1;
 		if (prior?.offlineQueue) await prior.offlineQueue.dispose();
-		state = {
+		prior?.detachEventAppState?.();
+		if (prior?.eventQueue) await prior.eventQueue.dispose();
+		const nextState = {
 			http,
 			identity,
 			debug: config.debug ?? false,
@@ -1459,12 +1867,39 @@ const Amba = {
 			baseUrl,
 			functionsBaseUrl: config.functionsBaseUrl ?? null,
 			resolvedFunctionsProjectId: null,
+			functionsProjectIdInflight: null,
 			persistence,
 			offlineEnabled: false,
-			offlineQueue: null
+			offlineQueue: null,
+			eventQueue: null
 		};
+		state = nextState;
+		if (config.events?.batching) {
+			const queue = new EventBatchQueue(offlineStore(nextState), `event_outbox:${nextState.projectId}`, {
+				batchSize,
+				flushIntervalMs,
+				maxQueue,
+				onDrop: config.events.onDrop
+			}, () => ({
+				userId: nextState.identity.getAppUserId(),
+				anonymousId: nextState.identity.getAnonymousId(),
+				sessionToken: nextState.identity.getSessionToken()
+			}), (body, token) => nextState.http.postWithSession("/v1/client/events/batch", body, token), (body, token) => nextState.http.postWithSession(P.events, body, token));
+			nextState.eventQueue = queue;
+			await queue.start();
+			try {
+				const { AppState } = require("react-native");
+				const sub = AppState.addEventListener("change", (status) => {
+					if (status === "background") queue.flush();
+				});
+				nextState.detachEventAppState = () => sub.remove();
+			} catch {}
+		}
+		if (!nextState.functionsBaseUrl && !PROJECT_ID_PATTERN.test(nextState.projectId)) resolveFunctionsProjectId(nextState).catch(() => {});
 	},
 	_reset: () => {
+		state?.detachEventAppState?.();
+		state?.eventQueue?.dispose();
 		state = null;
 		authSubscribers.clear();
 	},
@@ -1493,32 +1928,51 @@ const Amba = {
 			authHeaders: realtimeAuthHeaders
 		});
 	},
-	events: { track: async (event, properties, options) => {
-		const s = getState();
-		const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
-		const body = {
-			event,
-			properties: properties ?? void 0,
-			anonymous_id: s.identity.getAnonymousId(),
-			timestamp: occurredAt
-		};
-		if (options?.telemetry) body["telemetry"] = true;
-		try {
-			await s.http.post(P.events, body);
-		} catch (err) {
-			if (s.offlineEnabled && isOfflineError(err)) {
-				await getOfflineQueue(s).enqueue({
-					kind: "track",
-					event,
-					properties,
-					telemetry: options?.telemetry,
-					occurredAt
-				});
-				return;
+	events: {
+		track: async (event, properties, options) => {
+			const s = getState();
+			if (s.eventQueue && !options?.immediate) return s.eventQueue.enqueue(event, properties, options?.telemetry === true);
+			const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
+			const body = {
+				event,
+				properties: properties ?? void 0,
+				anonymous_id: s.identity.getAnonymousId(),
+				timestamp: occurredAt
+			};
+			if (options?.telemetry) body["telemetry"] = true;
+			try {
+				await s.http.post(P.events, body);
+			} catch (err) {
+				if (s.offlineEnabled && isOfflineError(err)) {
+					await getOfflineQueue(s).enqueue({
+						kind: "track",
+						event,
+						properties,
+						telemetry: options?.telemetry,
+						occurredAt
+					});
+					return;
+				}
+				throw err;
 			}
-			throw err;
+		},
+		flush: async () => getState().eventQueue?.flush() ?? {
+			sent: 0,
+			rejected: 0,
+			remaining: 0
+		},
+		pendingCount: async (userId) => getState().eventQueue?.pendingCount(userId) ?? 0,
+		clear: async ({ userId }) => {
+			if (!userId) throw new Error("Amba.events.clear: userId is required");
+			await getState().eventQueue?.clear(userId);
+		},
+		setOnline: (online) => {
+			getState().eventQueue?.setOnline(online);
+		},
+		setBatchingEnabled: (enabled) => {
+			getState().eventQueue?.setBatchingEnabled(enabled);
 		}
-	} },
+	},
 	auth: {
 		signInAnonymously: async () => {
 			const s = getState();
@@ -1655,6 +2109,7 @@ const Amba = {
 				if (typeof console !== "undefined") console.warn("[amba] signOut server call failed", err);
 			}
 			await s.identity.clearSession(rotateAnonymousId);
+			s.eventQueue?.flush();
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -1666,12 +2121,12 @@ const Amba = {
 		me: async () => {
 			const s = getState();
 			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
-			return (await s.http.get(P.authMe)).data;
+			return normalizeUserAuthProviders((await s.http.get(P.authMe)).data);
 		},
 		getSession: async () => {
 			const s = getState();
 			if (!s.identity.isAuthenticated()) return null;
-			return snapshotSession((await s.http.get(P.authMe)).data);
+			return snapshotSession(normalizeUserAuthProviders((await s.http.get(P.authMe)).data));
 		},
 		getAnonymousId: async () => {
 			return getState().identity.getAnonymousId();
@@ -1688,7 +2143,7 @@ const Amba = {
 			const s = getState();
 			if (!s.identity.getSessionToken()) throw new AmbaApiError("UNAUTHORIZED", "no active session — call signIn* first");
 			const path = userId === void 0 || userId === null || userId === "" ? P.usersMe : `${P.users}/${encodePathSegment(userId)}`;
-			return (await s.http.get(path)).data;
+			return normalizeUserAuthProviders((await s.http.get(path)).data);
 		},
 		update: ((arg1, arg2) => {
 			const s = getState();
@@ -1696,7 +2151,7 @@ const Amba = {
 			const isById = typeof arg1 === "string";
 			const patch = isById ? arg2 ?? {} : arg1;
 			const path = isById ? `${P.users}/${encodePathSegment(arg1)}` : `${P.users}/me`;
-			return s.http.patch(path, patch).then((env) => env.data);
+			return s.http.patch(path, patch).then((env) => normalizeUserAuthProviders(env.data));
 		})
 	},
 	sessions: {
@@ -1732,7 +2187,16 @@ const Amba = {
 		isEnabled: () => getState().offlineEnabled,
 		pendingCount: async () => getOfflineQueue(getState()).pendingCount(),
 		pending: async () => getOfflineQueue(getState()).pending(),
-		flush: async () => getOfflineQueue(getState()).flush(),
+		flush: async () => {
+			const s = getState();
+			const result = s.offlineEnabled ? await getOfflineQueue(s).flush() : {
+				flushed: 0,
+				dropped: 0,
+				remaining: s.offlineQueue ? await s.offlineQueue.pendingCount() : 0
+			};
+			await s.eventQueue?.flush();
+			return result;
+		},
 		clear: async () => getOfflineQueue(getState()).clear()
 	},
 	collections: {
@@ -2367,10 +2831,7 @@ const Amba = {
 		complete: async () => {
 			return (await getState().http.post(`${P.onboarding}/complete`, {})).data;
 		}
-	},
-	dev: { resetSandbox: async () => {
-		return (await getState().http.post("/v1/client/dev/reset-sandbox", {})).data;
-	} }
+	}
 };
 
 //#endregion