@layers/amba-react-native 4.0.7 → 4.0.8

package/dist/index.cjs

@@ -263,8 +263,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;
@@ -272,13 +287,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);
@@ -289,16 +310,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() {
@@ -338,17 +385,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() {
@@ -361,9 +455,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).
@@ -447,8 +699,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
@@ -471,6 +733,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
@@ -527,28 +799,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: [],
@@ -556,10 +855,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 {
@@ -578,8 +890,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 {
@@ -591,32 +921,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,
@@ -624,6 +942,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.
@@ -1192,7 +1533,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,
@@ -1216,7 +1557,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,
@@ -1476,7 +1817,7 @@ function delay(ms) {
 //#endregion
 //#region src/index.ts
 /** SDK semver — burned in at build time. Bump alongside package.json. */
-const SDK_VERSION = "4.0.7";
+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
@@ -1717,8 +2058,20 @@ 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. Resolution checks
@@ -1728,8 +2081,8 @@ function encodePathSegment(s) {
 * cached for subsequent invokes.
 */
 async function resolveFunctionUrl(s, name) {
-	if (s.functionsBaseUrl) return `${s.functionsBaseUrl.replace(/\/$/, "")}/${encodeURIComponent(name)}`;
-	return `https://${await resolveFunctionsProjectId(s)}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+	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;
@@ -1806,6 +2159,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);
 		}
@@ -1836,10 +2193,16 @@ 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 persistence = new AsyncStoragePersistence(config.storagePrefix ?? "amba");
+		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({
@@ -1940,6 +2303,7 @@ const Amba = {
 				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) {
@@ -1950,7 +2314,7 @@ const Amba = {
 						properties,
 						telemetry: options?.telemetry,
 						occurredAt
-					});
+					}, outboxTicket);
 					return;
 				}
 				throw err;
@@ -1994,18 +2358,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) => {
@@ -2040,7 +2406,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");
@@ -2050,7 +2416,8 @@ const Amba = {
 			return postAuth(s, P.authLink, {
 				provider: providerTrimmed,
 				token: credential,
-				session_token: sessionToken
+				session_token: sessionToken,
+				...nonceField(options)
 			});
 		},
 		linkSmsOtp: async (phone, code) => {
@@ -2109,6 +2476,11 @@ 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);
 		},
@@ -2224,6 +2596,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,
@@ -2236,7 +2609,7 @@ const Amba = {
 							collection: name,
 							payload: row,
 							idempotencyKey
-						});
+						}, outboxTicket);
 						return {
 							...row,
 							_amba_pending: true
@@ -2249,40 +2622,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 } };
 		},