@layers/amba-react-native 4.0.6 → 4.0.8

package/dist/index.js

@@ -1,3 +1,10 @@
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function.");
+});
+
+//#endregion
 //#region src/async-storage-adapter.ts
 let cachedStorage = void 0;
 /**
@@ -41,6 +48,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}`;
@@ -53,15 +64,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);
 	}
 };
 
@@ -133,18 +144,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;
@@ -252,8 +269,23 @@ var IdentityStore = class IdentityStore {
 	sessionToken = null;
 	refreshToken = null;
 	expiresAt = null;
-	constructor(persistence, seed) {
+	/**
+	* Credentials an earlier SDK version left in the AsyncStorage record, with
+	* the user they belong to. They stay on disk until the vault holds the
+	* session, so a vault write that fails or is skipped (or a process killed
+	* between the two writes) never loses the only stored copy.
+	*/
+	plaintext;
+	/**
+	* Set while the vault could not be read. Writes are held back until a read
+	* succeeds, so a session this launch never loaded is not overwritten.
+	*/
+	vaultUnreadable;
+	constructor(persistence, seed, vault, plaintext, vaultUnreadable) {
 		this.persistence = persistence;
+		this.vault = vault;
+		this.plaintext = plaintext;
+		this.vaultUnreadable = vaultUnreadable;
 		this.anonymousId = seed.anonymous_id;
 		this.appUserId = seed.app_user_id;
 		this.sessionToken = seed.session_token;
@@ -261,13 +293,19 @@ var IdentityStore = class IdentityStore {
 		this.expiresAt = seed.expires_at;
 	}
 	/**
-	* Build a store, hydrating any prior identity from AsyncStorage.
-	* If no prior identity exists, a fresh `anonymous_id` is minted.
-	* Expired session tokens are dropped at hydration (the refresh token
-	* survives so callers can `auth.refresh()` to mint a new pair).
+	* Build a store, hydrating any prior identity from AsyncStorage and the
+	* credential vault. If no prior identity exists, a fresh `anonymous_id`
+	* is minted. Expired session tokens are dropped at hydration (the refresh
+	* token survives so callers can `auth.refresh()` to mint a new pair).
+	*
+	* With a vault, credentials an earlier SDK version left in the
+	* AsyncStorage record are used for this launch and moved into the vault;
+	* the AsyncStorage copy is removed once the vault write succeeds. A vault
+	* holding its own credentials wins over them.
 	*/
-	static async create(persistence) {
+	static async create(persistence, vault = null) {
 		const raw = await persistence.read(IDENTITY_KEY);
+		let recordPresent = false;
 		let seed;
 		if (raw) try {
 			const parsed = JSON.parse(raw);
@@ -278,16 +316,42 @@ var IdentityStore = class IdentityStore {
 				refresh_token: parsed.refresh_token ?? null,
 				expires_at: parsed.expires_at ?? null
 			};
+			recordPresent = typeof parsed.anonymous_id === "string";
 		} catch {
 			seed = freshSeed();
 		}
 		else seed = freshSeed();
+		const plaintext = vault && (seed.session_token !== null || seed.refresh_token !== null || seed.expires_at !== null) ? {
+			appUserId: seed.app_user_id,
+			slice: {
+				session_token: seed.session_token,
+				refresh_token: seed.refresh_token,
+				expires_at: seed.expires_at
+			}
+		} : null;
+		let vaultReadable = true;
+		if (vault) {
+			let fromVault = null;
+			try {
+				fromVault = await vault.read();
+			} catch {
+				vaultReadable = false;
+			}
+			const belongs = fromVault !== null && recordPresent && fromVault.anonymous_id === seed.anonymous_id;
+			if (fromVault && belongs) {
+				seed.session_token = fromVault.session_token;
+				seed.refresh_token = fromVault.refresh_token;
+				seed.expires_at = fromVault.expires_at;
+				if (fromVault.app_user_id != null) seed.app_user_id = fromVault.app_user_id;
+			}
+		}
+		if (vaultReadable && seed.session_token === null && seed.refresh_token === null) seed.app_user_id = null;
 		if (isExpired(seed.expires_at)) {
 			seed.session_token = null;
 			seed.expires_at = null;
 		}
-		const store = new IdentityStore(persistence, seed);
-		await store.flush();
+		const store = new IdentityStore(persistence, seed, vault, plaintext, !vaultReadable);
+		await store.flush({ hydrating: true });
 		return store;
 	}
 	snapshot() {
@@ -327,17 +391,64 @@ var IdentityStore = class IdentityStore {
 		this.refreshToken = null;
 		this.expiresAt = null;
 		if (rotateAnonymousId) this.anonymousId = uuidv4();
-		await this.flush();
+		await this.flush({ signingOut: true });
 	}
-	async flush() {
-		const payload = {
+	/**
+	* Persist the identity. `hydrating` marks the write that follows `create`:
+	* when the vault was unreadable and a retry now succeeds, the session it
+	* holds is adopted instead of overwritten. `signingOut` marks the write
+	* from `clearSession`: when the vault can't be emptied, the install moves
+	* to a new anonymous id so the entry left behind no longer belongs to it.
+	*/
+	async flush(opts) {
+		if (!this.vault) {
+			const payload = {
+				anonymous_id: this.anonymousId,
+				app_user_id: this.appUserId,
+				session_token: this.sessionToken,
+				refresh_token: this.refreshToken,
+				expires_at: this.expiresAt
+			};
+			await this.persistence.write(IDENTITY_KEY, JSON.stringify(payload));
+			return;
+		}
+		let saved = false;
+		if (this.vaultUnreadable) try {
+			const stored = await this.vault.read();
+			this.vaultUnreadable = false;
+			if (opts?.hydrating && stored && (stored.session_token !== null || stored.refresh_token !== null) && stored.anonymous_id === this.anonymousId) {
+				this.sessionToken = isExpired(stored.expires_at) ? null : stored.session_token;
+				this.refreshToken = stored.refresh_token;
+				this.expiresAt = isExpired(stored.expires_at) ? null : stored.expires_at;
+				if (stored.app_user_id != null) this.appUserId = stored.app_user_id;
+			}
+		} catch {}
+		if (!this.vaultUnreadable) try {
+			await this.vault.write({
+				session_token: this.sessionToken,
+				refresh_token: this.refreshToken,
+				expires_at: this.expiresAt,
+				anonymous_id: this.anonymousId,
+				app_user_id: this.appUserId
+			});
+			saved = true;
+		} catch (err) {
+			if (typeof console !== "undefined") console.warn("[amba] could not save the session to the secure store", err);
+		}
+		if (opts?.signingOut && !saved) {
+			this.anonymousId = uuidv4();
+			if (typeof console !== "undefined") console.warn("[amba] could not clear the secure store at sign-out; starting a new anonymous id so the stored session can't be restored");
+		}
+		const keep = !saved && this.plaintext !== null && this.refreshToken !== null && this.plaintext.appUserId === this.appUserId && this.plaintext.slice.refresh_token === this.refreshToken ? this.plaintext.slice : null;
+		const record = {
 			anonymous_id: this.anonymousId,
 			app_user_id: this.appUserId,
-			session_token: this.sessionToken,
-			refresh_token: this.refreshToken,
-			expires_at: this.expiresAt
+			session_token: keep?.session_token ?? null,
+			refresh_token: keep?.refresh_token ?? null,
+			expires_at: keep?.expires_at ?? null
 		};
-		await this.persistence.write(IDENTITY_KEY, JSON.stringify(payload));
+		await this.persistence.write(IDENTITY_KEY, JSON.stringify(record));
+		if (!keep) this.plaintext = null;
 	}
 };
 function freshSeed() {
@@ -350,9 +461,167 @@ function freshSeed() {
 	};
 }
 
+//#endregion
+//#region src/token-storage.ts
+const TOKEN_STORAGE_MODES = [
+	"secure",
+	"memory",
+	"asyncStorage"
+];
+function isEmpty(slice) {
+	return slice.session_token === null && slice.refresh_token === null && slice.expires_at === null;
+}
+/**
+* Memory-held credentials, keyed like the keystore entry. They last as long
+* as the JS runtime, so a second `Amba.configure()` (Fast Refresh, a
+* re-configure) keeps the session, and a relaunch starts signed out.
+*/
+const memorySlices = /* @__PURE__ */ new Map();
+/** Credentials held in this JS runtime only. */
+var MemoryTokenVault = class {
+	kind = "memory";
+	constructor(key) {
+		this.key = key;
+	}
+	async read() {
+		const slice = memorySlices.get(this.key);
+		return slice ? { ...slice } : null;
+	}
+	async write(slice) {
+		if (isEmpty(slice)) memorySlices.delete(this.key);
+		else memorySlices.set(this.key, { ...slice });
+	}
+};
+/**
+* Keystore key for a storage prefix. Kept to `[A-Za-z0-9_.-]` because some
+* secure stores (for example `expo-secure-store`) reject other characters.
+*/
+function secureTokenKey(prefix) {
+	return `${prefix.replace(/[^A-Za-z0-9_.-]/g, "_")}_session_tokens_v1`;
+}
+/** Credentials in a keystore-backed {@link SecureTokenStorage}. */
+var SecureTokenVault = class {
+	kind = "secure";
+	constructor(storage, key) {
+		this.storage = storage;
+		this.key = key;
+	}
+	async read() {
+		const raw = await this.storage.getItem(this.key);
+		if (!raw) return null;
+		try {
+			const parsed = JSON.parse(raw);
+			return {
+				session_token: parsed.session_token ?? null,
+				refresh_token: parsed.refresh_token ?? null,
+				expires_at: parsed.expires_at ?? null,
+				anonymous_id: parsed.anonymous_id ?? null,
+				app_user_id: parsed.app_user_id ?? null
+			};
+		} catch {
+			return null;
+		}
+	}
+	async write(slice) {
+		if (isEmpty(slice)) {
+			await this.storage.removeItem(this.key);
+			return;
+		}
+		await this.storage.setItem(this.key, JSON.stringify(slice));
+	}
+};
+function isKeychainLike(mod) {
+	const k = mod;
+	return typeof k === "object" && k !== null && typeof k.setGenericPassword === "function" && typeof k.getGenericPassword === "function" && typeof k.resetGenericPassword === "function";
+}
+/**
+* Adapt `react-native-keychain` to {@link SecureTokenStorage}. Items use the
+* `AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY` class on iOS: readable after the
+* first unlock (so background refreshes work) and left behind by backups
+* restored onto another device.
+*/
+function keychainStorage(keychain) {
+	const accessible = keychain.ACCESSIBLE?.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY;
+	return {
+		async getItem(key) {
+			const entry = await keychain.getGenericPassword({ service: key });
+			return entry ? entry.password : null;
+		},
+		async setItem(key, value) {
+			if (await keychain.setGenericPassword("amba", value, {
+				service: key,
+				...accessible !== void 0 ? { accessible } : {}
+			}) === false) throw new Error("react-native-keychain refused to store the session");
+		},
+		async removeItem(key) {
+			if (await keychain.resetGenericPassword({ service: key }) === false && await keychain.getGenericPassword({ service: key })) throw new Error("react-native-keychain could not remove the session");
+		}
+	};
+}
+let cachedKeychain;
+/**
+* Load `react-native-keychain` when the app has it installed. Resolves null
+* otherwise (module missing, or a build without its native half).
+*/
+async function loadKeychainStorage() {
+	if (cachedKeychain !== void 0) return cachedKeychain;
+	try {
+		const mod = await import("react-native-keychain");
+		const candidate = isKeychainLike(mod) ? mod : mod.default;
+		cachedKeychain = isKeychainLike(candidate) ? keychainStorage(candidate) : null;
+	} catch {
+		cachedKeychain = null;
+	}
+	return cachedKeychain;
+}
+let memoryFallbackWarned = false;
+/**
+* Pick the vault for `mode`. Resolves null for `"asyncStorage"`, which keeps
+* the credentials inside the AsyncStorage identity record.
+*/
+async function resolveTokenVault(mode, prefix, secureStorage) {
+	if (mode === "asyncStorage") return null;
+	const key = secureTokenKey(prefix);
+	if (mode === "memory") return new MemoryTokenVault(key);
+	const storage = secureStorage ?? await loadKeychainStorage();
+	if (storage) return new SecureTokenVault(storage, key);
+	if (!memoryFallbackWarned && typeof console !== "undefined") {
+		memoryFallbackWarned = true;
+		console.warn("[amba] No secure token store found, so the session is kept in memory and users sign in again after every launch. Install react-native-keychain (or pass `secureStorage` to Amba.configure) to keep sessions across launches in the Keychain/Keystore.");
+	}
+	return new MemoryTokenVault(key);
+}
+
+//#endregion
+//#region src/path-segment.ts
+/**
+* Encode one caller-supplied id, key, slug or name as a single URL path
+* segment. `encodeURIComponent` escapes `/`, `?` and `#`, so the value stays
+* inside its segment. `.` and `..` are refused because URL resolution treats
+* them as steps to another route, and the empty string is refused because it
+* collapses onto the parent route.
+*/
+function pathSegment(value) {
+	if (value === "" || value === "." || value === "..") throw new AmbaApiError("VALIDATION_ERROR", `path segment must not be ${value === "" ? "empty" : `'${value}'`}`);
+	return encodeURIComponent(value);
+}
+
 //#endregion
 //#region src/resilience.ts
 /**
+* Whether `op` belongs to `current`. An op queued under a user id matches only
+* that user id. An op queued before any session matches the same anonymous id,
+* so a guest's offline write lands once that guest's session starts. An op
+* with no recorded owner (queued by an SDK version before owners existed)
+* matches nobody.
+*/
+function outboxOwnerMatches(op, current) {
+	const owner = op.owner;
+	if (!owner) return false;
+	if (owner.appUserId) return owner.appUserId === current.appUserId;
+	return owner.anonymousId !== null && owner.anonymousId === current.anonymousId;
+}
+/**
 * Best-effort online probe. In a browser/RN runtime `navigator.onLine`
 * exists; under Node / SSR it doesn't, so we treat "unknown" as online
 * (the executor's own error handling then decides).
@@ -436,8 +705,18 @@ var OfflineQueue = class {
 	* SDK surface the loss (debug log) instead of silently discarding.
 	*/
 	onDropped;
+	/**
+	* The identity that is signed in right now. When set, enqueue stamps it on
+	* each op and flush/pending only touch ops it owns.
+	*/
+	currentOwner;
 	flushing = null;
 	/**
+	* Bumped by `purge()`. A replay that started before a purge sees the change
+	* and does not re-queue its op.
+	*/
+	purgeGeneration = 0;
+	/**
 	* Serializes every read-modify-write of the persisted outbox. Each mutation
 	* chains onto the previous one's promise, so concurrent `enqueue`s — and an
 	* `enqueue` racing the per-op removal inside `flush` — can never read a stale
@@ -460,6 +739,16 @@ var OfflineQueue = class {
 		this.executor = opts.executor;
 		this.storageKey = opts.storageKey ?? "offline_outbox";
 		this.onDropped = opts.onDropped;
+		this.currentOwner = opts.currentOwner;
+	}
+	/**
+	* The ops the current owner may see and replay. Without an owner source
+	* every op qualifies.
+	*/
+	visible(ops) {
+		if (!this.currentOwner) return ops;
+		const current = this.currentOwner();
+		return ops.filter((op) => outboxOwnerMatches(op, current));
 	}
 	/**
 	* Run `fn` exclusively against the persisted outbox: it chains after every
@@ -516,28 +805,55 @@ var OfflineQueue = class {
 	get isDisposed() {
 		return this.disposed;
 	}
-	/** Append an op to the durable outbox. Returns the persisted op. */
-	async enqueue(op) {
+	/**
+	* Capture the current owner and purge generation. Take it before a write's
+	* live attempt and pass it to {@link enqueue}.
+	*/
+	ticket() {
+		return {
+			owner: this.currentOwner?.(),
+			generation: this.purgeGeneration
+		};
+	}
+	/**
+	* Append an op to the durable outbox. Returns the persisted op. With a
+	* `ticket`, the op belongs to the ticket's owner, and the enqueue rejects
+	* (code `OFFLINE_QUEUE_PURGED`) when the queue was purged after the ticket
+	* was taken, which is what a sign-out during the live attempt does.
+	*/
+	async enqueue(op, ticket) {
 		if (this.disposed) throw new Error("amba offline queue was disposed (SDK reconfigured)");
+		const owner = op.owner ?? (ticket ? ticket.owner : this.currentOwner?.());
 		const full = {
 			...op,
+			...owner ? { owner: { ...owner } } : {},
 			idempotencyKey: op.idempotencyKey ?? newIdempotencyKey(),
 			enqueuedAt: (/* @__PURE__ */ new Date()).toISOString()
 		};
-		return this.mutate((ops) => ({
-			next: [...ops, full],
-			result: full
-		}), { rejectIfDisposed: true });
+		return this.mutate((ops) => {
+			if (ticket && ticket.generation !== this.purgeGeneration) {
+				const err = /* @__PURE__ */ new Error("amba offline queue was cleared by a sign-out while this write was in flight");
+				err.code = "OFFLINE_QUEUE_PURGED";
+				throw err;
+			}
+			return {
+				next: [...ops, full],
+				result: full
+			};
+		}, { rejectIfDisposed: true });
 	}
-	/** Number of ops awaiting replay. */
+	/** Number of the current owner's ops awaiting replay. */
 	async pendingCount() {
-		return (await this.load()).length;
+		return this.visible(await this.load()).length;
 	}
-	/** Snapshot the pending ops (a copy — mutating it does not affect the queue). */
+	/**
+	* Snapshot the current owner's pending ops (a copy — mutating it does not
+	* affect the queue). Ops queued by another user stay out of the list.
+	*/
 	async pending() {
-		return [...await this.load()];
+		return [...this.visible(await this.load())];
 	}
-	/** Drop every queued op without replaying. */
+	/** Drop every queued op, whoever queued it, without replaying. */
 	async clear() {
 		await this.mutate(() => ({
 			next: [],
@@ -545,10 +861,23 @@ var OfflineQueue = class {
 		}));
 	}
 	/**
-	* Replay the outbox in FIFO order. Each op is removed only after it
-	* succeeds; the first failure stops the flush and retains the remainder
-	* (so order is preserved and nothing is dropped mid-batch). Concurrent
-	* calls share one in-flight flush.
+	* Drop every queued op, including one whose replay is in flight right now:
+	* that op is not re-queued when its replay fails. The SDKs call this on
+	* sign-out so nothing the signed-out user queued survives on the device.
+	*/
+	async purge() {
+		this.purgeGeneration += 1;
+		await this.clear();
+	}
+	/**
+	* Replay the current owner's ops in FIFO order. Each op is removed only
+	* after it succeeds; the first failure stops the flush and retains the
+	* remainder (so order is preserved and nothing is dropped mid-batch). Ops
+	* another user queued stay held for that user. Ops that can never replay
+	* are dropped through `onDropped`: one with no recorded owner (code
+	* `OFFLINE_OWNER_UNKNOWN`), and one queued before any session under an
+	* anonymous id the install no longer has (code `OFFLINE_OWNER_GONE`).
+	* Concurrent calls share one in-flight flush.
 	*/
 	async flush() {
 		if (this.disposed) return {
@@ -567,8 +896,26 @@ var OfflineQueue = class {
 		let dropped = 0;
 		for (;;) {
 			if (this.disposed) break;
-			const head = (await this.load())[0];
+			const all = await this.load();
+			if (this.currentOwner) {
+				const current = this.currentOwner();
+				const orphan = all.find((o) => !o.owner || o.owner.appUserId === null && current.anonymousId !== null && o.owner.anonymousId !== current.anonymousId);
+				if (orphan) {
+					if (!await this.removeOp(orphan)) break;
+					dropped += 1;
+					this.reportDropped(orphan, orphan.owner ? {
+						code: "OFFLINE_OWNER_GONE",
+						message: "queued before sign-in under an anonymous id this install no longer has; not replayed"
+					} : {
+						code: "OFFLINE_OWNER_UNKNOWN",
+						message: "queued by an earlier SDK version without an owner; not replayed"
+					});
+					continue;
+				}
+			}
+			const head = this.visible(all)[0];
 			if (!head) break;
+			const generation = this.purgeGeneration;
 			let replayError = void 0;
 			let ok = false;
 			try {
@@ -580,32 +927,20 @@ var OfflineQueue = class {
 			if (!ok && !isDeterministicError(replayError)) {
 				await this.mutate((ops) => {
 					return {
-						next: ops.some((o) => o.idempotencyKey === head.idempotencyKey) ? ops : [head, ...ops],
+						next: !ops.some((o) => o.idempotencyKey === head.idempotencyKey) && generation === this.purgeGeneration ? [head, ...ops] : ops,
 						result: void 0
 					};
 				});
 				break;
 			}
-			if (!await this.mutate((ops) => {
-				const idx = ops.findIndex((o) => o.idempotencyKey === head.idempotencyKey);
-				if (idx === -1) return {
-					next: ops,
-					result: false
-				};
-				return {
-					next: ops.slice(0, idx).concat(ops.slice(idx + 1)),
-					result: true
-				};
-			})) break;
+			if (!await this.removeOp(head)) break;
 			if (ok) flushed += 1;
 			else {
 				dropped += 1;
-				try {
-					this.onDropped?.(head, replayError);
-				} catch {}
+				this.reportDropped(head, replayError);
 			}
 		}
-		const remaining = (await this.load()).length;
+		const remaining = this.visible(await this.load()).length;
 		return {
 			flushed,
 			dropped,
@@ -613,6 +948,29 @@ var OfflineQueue = class {
 		};
 	}
 	/**
+	* Remove exactly `op` (by idempotency key) under the lock. Robust against a
+	* concurrent enqueue having shifted the array. Resolves false when the op
+	* is already gone.
+	*/
+	removeOp(op) {
+		return this.mutate((ops) => {
+			const idx = ops.findIndex((o) => o.idempotencyKey === op.idempotencyKey);
+			if (idx === -1) return {
+				next: ops,
+				result: false
+			};
+			return {
+				next: ops.slice(0, idx).concat(ops.slice(idx + 1)),
+				result: true
+			};
+		});
+	}
+	reportDropped(op, err) {
+		try {
+			this.onDropped?.(op, err);
+		} catch {}
+	}
+	/**
 	* Install an auto-flush listener on the runtime's `online` event so the
 	* queue drains the moment connectivity returns. Idempotent — a second
 	* call is a no-op. Returns a detach function.
@@ -664,6 +1022,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
 /**
@@ -865,7 +1539,7 @@ var CollectionSubscription = class {
 		if (!this.ctx.authHeaders()) throw new Error("Amba.collection().subscribe() requires an authenticated session — call Amba.auth.signIn* first.");
 		const qs = Object.keys(this.filters).length > 0 ? `?where=${encodeURIComponent(JSON.stringify(this.filters))}` : "";
 		return openStream({
-			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/collections/${encodeURIComponent(this.name)}${qs}`,
+			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/collections/${pathSegment(this.name)}${qs}`,
 			authHeaders: this.ctx.authHeaders,
 			onChange: cb,
 			options,
@@ -889,7 +1563,7 @@ var ConversationSubscription = class {
 	subscribe(cb, options = {}) {
 		if (!this.ctx.authHeaders()) throw new Error("Amba.messaging.conversation().subscribe() requires an authenticated session — call Amba.auth.signIn* first.");
 		return openStream({
-			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/conversations/${encodeURIComponent(this.conversationId)}`,
+			url: `${resolveRealtimeBaseUrl(this.ctx.baseUrl)}/v1/client/realtime/conversations/${pathSegment(this.conversationId)}`,
 			authHeaders: this.ctx.authHeaders,
 			onChange: cb,
 			options,
@@ -1149,13 +1823,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.6";
+const SDK_VERSION = "4.0.8";
 /**
 * 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
@@ -1209,7 +1884,7 @@ function normalizeAuthProviderNames(value) {
 		try {
 			normalized = JSON.parse(trimmed);
 		} catch {
-			return [normalized];
+			return [trimmed];
 		}
 	}
 	if (!Array.isArray(normalized)) {
@@ -1271,6 +1946,7 @@ async function persistAuthResult(state_, result) {
 async function postAuth(state_, path, body) {
 	const result = normalizeAuthResult((await state_.http.post(path, body)).data);
 	await persistAuthResult(state_, result);
+	state_.eventQueue?.flush();
 	await notifyFromAuthResult(result);
 	return result;
 }
@@ -1388,24 +2064,53 @@ const P = {
 	deepLinks: "/v1/client/deep-links",
 	onboarding: "/v1/client/onboarding"
 };
+/**
+* Encode one caller-supplied id, key or name as a single URL path segment.
+* `encodeURIComponent` escapes `/`, `?` and `#`; `.` and `..` are refused
+* because URL resolution treats them as steps to another route, and the
+* empty string is refused because it collapses onto the parent route.
+*/
 function encodePathSegment(s) {
-	return encodeURIComponent(s);
+	return pathSegment(s);
+}
+function nonceField(options) {
+	const nonce = options?.nonce;
+	if (nonce === void 0) return {};
+	if (typeof nonce !== "string" || nonce.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "nonce must be a non-empty string");
+	return { nonce };
 }
 /**
-* 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;
+	if (s.functionsBaseUrl) return `${s.functionsBaseUrl.replace(/\/$/, "")}/${pathSegment(name)}`;
+	return `https://${await resolveFunctionsProjectId(s)}.${DEFAULT_FUNCTIONS_HOST}/${pathSegment(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
@@ -1460,6 +2165,10 @@ function getOfflineQueue(s) {
 		store: offlineStore(s),
 		storageKey: `offline_outbox:${s.projectId}`,
 		executor: (op) => replayOutboxOp(s, op),
+		currentOwner: () => ({
+			appUserId: s.identity.getSessionToken() || s.identity.getRefreshToken() ? s.identity.getAppUserId() : null,
+			anonymousId: s.identity.getAnonymousId()
+		}),
 		onDropped: (op, err) => {
 			if (typeof console !== "undefined") console.warn(`[amba] dropped un-replayable offline ${op.kind} (${op.collection ?? op.event ?? "?"}):`, err);
 		}
@@ -1482,9 +2191,24 @@ 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 persistence = new AsyncStoragePersistence(config.storagePrefix ?? "amba");
+		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 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 storagePrefix = config.storagePrefix ?? "amba";
+		const persistence = new AsyncStoragePersistence(storagePrefix);
+		if (config.events?.batching) await persistence.assertDurable();
 		await persistence.hydrate();
-		const identity = await IdentityStore.create(persistence);
+		const vault = await resolveTokenVault(tokenStorage, storagePrefix, secureStorage);
+		const identity = await IdentityStore.create(persistence, vault);
 		const baseUrl = (config.apiUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 		const sdkVersionHeader = `amba-sdk/${SDK_VERSION} ${`amba-react-native/${SDK_VERSION}`}`;
 		const http = new AmbaHttpClient({
@@ -1501,7 +2225,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,
@@ -1510,12 +2236,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();
 	},
@@ -1544,32 +2297,52 @@ 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;
+			const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
+			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
+					}, outboxTicket);
+					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();
@@ -1591,18 +2364,20 @@ const Amba = {
 				password
 			});
 		},
-		signInWithApple: async (identityToken) => {
+		signInWithApple: async (identityToken, options) => {
 			if (identityToken.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "identity_token must not be empty");
 			return postAuth(getState(), P.authSocial, {
 				provider: "apple",
-				id_token: identityToken
+				id_token: identityToken,
+				...nonceField(options)
 			});
 		},
-		signInWithGoogle: async (idToken) => {
+		signInWithGoogle: async (idToken, options) => {
 			if (idToken.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "id_token must not be empty");
 			return postAuth(getState(), P.authSocial, {
 				provider: "google",
-				id_token: idToken
+				id_token: idToken,
+				...nonceField(options)
 			});
 		},
 		requestEmailOtp: async (email) => {
@@ -1637,7 +2412,7 @@ const Amba = {
 			if (token.trim() === "") throw new AmbaApiError("VALIDATION_ERROR", "token must not be empty");
 			return postAuth(getState(), P.authMagicLinkVerify, { token });
 		},
-		linkAccount: async (provider, credential) => {
+		linkAccount: async (provider, credential, options) => {
 			const providerTrimmed = provider?.trim() ?? "";
 			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");
@@ -1647,7 +2422,8 @@ const Amba = {
 			return postAuth(s, P.authLink, {
 				provider: providerTrimmed,
 				token: credential,
-				session_token: sessionToken
+				session_token: sessionToken,
+				...nonceField(options)
 			});
 		},
 		linkSmsOtp: async (phone, code) => {
@@ -1706,6 +2482,12 @@ const Amba = {
 				if (typeof console !== "undefined") console.warn("[amba] signOut server call failed", err);
 			}
 			await s.identity.clearSession(rotateAnonymousId);
+			try {
+				await getOfflineQueue(s).purge();
+			} catch (err) {
+				if (typeof console !== "undefined") console.warn("[amba] signOut could not clear the offline outbox", err);
+			}
+			s.eventQueue?.flush();
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -1783,7 +2565,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: {
@@ -1811,6 +2602,7 @@ const Amba = {
 			const s = getState();
 			if (s.offlineEnabled) {
 				const idempotencyKey = (typeof row["idempotency_key"] === "string" ? row["idempotency_key"] : void 0) ?? newIdempotencyKey();
+				const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
 				try {
 					return (await s.http.post(`${P.collections}/${encodePathSegment(name)}`, {
 						...row,
@@ -1823,7 +2615,7 @@ const Amba = {
 							collection: name,
 							payload: row,
 							idempotencyKey
-						});
+						}, outboxTicket);
 						return {
 							...row,
 							_amba_pending: true
@@ -1836,40 +2628,46 @@ const Amba = {
 		},
 		update: async (name, id, set) => {
 			const s = getState();
-			if (s.offlineEnabled) try {
-				return (await s.http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
-			} catch (err) {
-				if (isOfflineError(err)) {
-					await getOfflineQueue(s).enqueue({
-						kind: "collection.update",
-						collection: name,
-						id,
-						payload: set
-					});
-					return {
-						id,
-						...set,
-						_amba_pending: true
-					};
+			if (s.offlineEnabled) {
+				const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
+				try {
+					return (await s.http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
+				} catch (err) {
+					if (isOfflineError(err)) {
+						await getOfflineQueue(s).enqueue({
+							kind: "collection.update",
+							collection: name,
+							id,
+							payload: set
+						}, outboxTicket);
+						return {
+							id,
+							...set,
+							_amba_pending: true
+						};
+					}
+					throw err;
 				}
-				throw err;
 			}
 			return (await s.http.patch(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`, { set })).data;
 		},
 		delete: async (name, id) => {
 			const s = getState();
-			if (s.offlineEnabled) try {
-				return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
-			} catch (err) {
-				if (isOfflineError(err)) {
-					await getOfflineQueue(s).enqueue({
-						kind: "collection.delete",
-						collection: name,
-						id
-					});
-					return { data: { deleted: true } };
+			if (s.offlineEnabled) {
+				const outboxTicket = s.offlineEnabled ? getOfflineQueue(s).ticket() : void 0;
+				try {
+					return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
+				} catch (err) {
+					if (isOfflineError(err)) {
+						await getOfflineQueue(s).enqueue({
+							kind: "collection.delete",
+							collection: name,
+							id
+						}, outboxTicket);
+						return { data: { deleted: true } };
+					}
+					throw err;
 				}
-				throw err;
 			}
 			return await s.http.delete(`${P.collections}/${encodePathSegment(name)}/${encodePathSegment(id)}`) ?? { data: { deleted: true } };
 		},
@@ -2418,10 +3216,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