@layers/amba-web 4.0.10 → 4.0.11

package/dist-rn/index.d.ts

@@ -38,6 +38,26 @@ interface AmbaConfig {
   debug?: boolean;
   /** Override the localStorage key prefix. Defaults to `"amba"`. */
   storagePrefix?: string;
+  /**
+   * Where the SDK keeps the signed-in session between page loads.
+   *
+   * - `"local"` (default): the session token, refresh token, user id and
+   *   anonymous id are saved in `localStorage`, so a reload or a new tab
+   *   stays signed in. Any script running on your origin can read
+   *   `localStorage`, so a cross-site scripting bug in the page can copy the
+   *   refresh token (valid for 90 days) and keep using the session after the
+   *   tab closes.
+   * - `"memory"`: none of that identity is written to storage; it lives in
+   *   this page's memory and ends with it. A script injected later finds no
+   *   stored token to copy. Every reload or new tab starts signed out with a
+   *   new anonymous identity, so users sign in again each visit. Configuring
+   *   with `"memory"` also removes an identity an earlier `"local"`
+   *   configuration saved for this project.
+   *
+   * Queued offline writes (`Amba.offline`) stay in `localStorage` in both
+   * modes.
+   */
+  sessionPersistence?: SessionPersistence;
   /**
    * Advanced: explicit URL or RequestInfo for the @layers/amba-core WASM file.
    * Browser bundlers should not need this; the browser entry supplies a
@@ -50,6 +70,8 @@ interface AmbaConfig {
    */
   wasmModule?: Response | BufferSource | WebAssembly.Module;
 }
+/** `AmbaConfig.sessionPersistence` values. */
+type SessionPersistence = "local" | "memory";
 type SocialProvider = "apple" | "google";
 type PushPlatform = "apns" | "fcm" | "web";
 interface User {
@@ -1244,6 +1266,10 @@ interface AiStreamOptions {
  *   - On reconnect (`online` event) the outbox is flushed in FIFO order;
  *     each op is removed only after it succeeds, so a mid-flush failure
  *     leaves the remainder intact for the next attempt.
+ *   - Each op records its owner (the user id and anonymous id live when it
+ *     was queued). A flush replays only the current owner's ops and holds
+ *     the rest until that owner signs back in; `pending()` lists only the
+ *     current owner's ops. The SDKs clear the whole outbox on sign-out.
  */
 /**
  * Minimal durable key/value contract the outbox persists through. Both the
@@ -1255,6 +1281,14 @@ interface KvStore {
   set(key: string, value: string): Promise<void> | void;
   delete(key: string): Promise<void> | void;
 }
+/**
+ * The identity a queued op belongs to: the signed-in user id (null before any
+ * session) and the install's anonymous id, both captured at enqueue.
+ */
+interface OutboxOwner {
+  appUserId: string | null;
+  anonymousId: string | null;
+}
 /** The kinds of mutation the outbox can durably replay. */
 type OutboxOpKind = "collection.insert" | "collection.update" | "collection.delete" | "track";
 /**
@@ -1288,6 +1322,11 @@ interface OutboxOp {
    * session user at replay time — the events route has no body-id channel.)
    */
   occurredAt?: string;
+  /**
+   * Who queued the op. Stamped at enqueue when the queue has a `currentOwner`
+   * source; a flush replays the op only while the same owner is signed in.
+   */
+  owner?: OutboxOwner;
   enqueuedAt: string;
 }
 /** Result of a {@link OfflineQueue.flush}. */
@@ -1659,8 +1698,12 @@ declare const Amba: {
      * password)`. Requires an active session — throws `UNAUTHORIZED`
      * otherwise.
      *
-     * @returns the updated user record (with `email` set and
-     *   `email_verified = true`).
+     * The address stays unverified (`email_verified = false`) until the
+     * inbox is proven, unless this user had already verified the same
+     * address. `linkEmailOtp` with the same address from this session
+     * verifies it and keeps the password.
+     *
+     * @returns the updated user record (with `email` set).
      */
     linkEmailPassword: (email: string, password: string) => Promise<User>;
     /**
@@ -2511,7 +2554,7 @@ declare function getCoreWasm(): AmbaCoreWasm;
  * `verify-sdk-version-coherence` GH action gates every publish on the
  * pair agreeing (and matching the `web-v<X.Y.Z>` tag when tag-triggered).
  */
-declare const SDK_VERSION = "4.0.10";
+declare const SDK_VERSION = "4.0.11";
 //#endregion
-export { Achievement, AchievementProgress, AiContentBlock, AiImageInput, AiMessage, AiMessageRequest, AiMessageResponse, type AiStreamDelta, type AiStreamDone, type AiStreamEvent, type AiStreamOptions, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AmbaGroupScopedClient, AndFilter, AppSession, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationParticipant, ConversationSubscription, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DeleteManyResult, DiagnosticsEnvironment, EntitlementPeriodType, EntitlementStore, EventExplainResult, ExplainMatchedRule, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, type FlushResult, Friendship, FriendshipState, type GamificationChange, type GamificationKind, GamificationSubscription, Group, GroupCreate, GroupMember, GroupUpdate, IncludeClause, InventoryItem, InvokeOptions, type KvStore, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, LocalNotificationHandle, LocalNotificationTrigger, type LocalNotificationsNamespace, MarkReadResult, MediaAsset, MediaCatalog, MediaCatalogItem, MediaListResponse, Message, type MessageChange, MessageType, NearestOptions, NearestResponse, NotFilter, Offering, OfferingPackage, OfferingProduct, OfferingsResult, OnboardingStatus, OrFilter, OrderBy, type OutboxOp, type OutboxOpKind, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, RestoreResult, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, ScheduleLocalNotificationInput, ScheduledLocalNotification, SendMessageRequest, Session, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, TransactionOp, TransactionOpResult, type Unsubscribe, UpsertOptions, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm, withOptimistic };
+export { Achievement, AchievementProgress, AiContentBlock, AiImageInput, AiMessage, AiMessageRequest, AiMessageResponse, type AiStreamDelta, type AiStreamDone, type AiStreamEvent, type AiStreamOptions, AiUsage, Amba, AmbaApiError, type AmbaApiErrorCode, AmbaConfig, AmbaGroupScopedClient, AndFilter, AppSession, AuthResult, CatalogItem, Challenge, ChallengeProgress, CollectionSubscription, ConditionFilter, ConfigBundle, ConsumeRequest, ContentItem, Conversation, ConversationParticipant, ConversationSubscription, ConversationType, CreateConversationRequest, CurrencyBalance, CurrencyTransaction, DeepLink, DeepLinkCreate, DeleteManyResult, DiagnosticsEnvironment, EntitlementPeriodType, EntitlementStore, EventExplainResult, ExplainMatchedRule, FeedItem, FeedResponse, Filter, FilterValue, FindOptions, FindResponse, FlagAssignment, type FlushResult, Friendship, FriendshipState, type GamificationChange, type GamificationKind, GamificationSubscription, Group, GroupCreate, GroupMember, GroupUpdate, IncludeClause, InventoryItem, InvokeOptions, type KvStore, Leaderboard, LeaderboardEntry, LeagueCohort, LeagueCohortMember, LeagueCohortView, LeagueMembership, LeagueTier, LinkedIdentifier, ListMessagesOptions, LocalNotificationHandle, LocalNotificationTrigger, type LocalNotificationsNamespace, MarkReadResult, MediaAsset, MediaCatalog, MediaCatalogItem, MediaListResponse, Message, type MessageChange, MessageType, NearestOptions, NearestResponse, NotFilter, Offering, OfferingPackage, OfferingProduct, OfferingsResult, OnboardingStatus, OrFilter, OrderBy, type OutboxOp, type OutboxOpKind, PingResult, PresignData, PullChangesCursor, PullChangesResult, PurchaseOption, PurchaseRequest, PurchaseResult, PushChangesResult, PushPlatform, PushToken, type RealtimeChange, ReferralClaim, ReferralCode, Report, ReportRequest, RestoreResult, Review, ReviewCreate, ReviewUpdate, Role, type RowChangeOp, SDK_VERSION, ScheduleLocalNotificationInput, ScheduledLocalNotification, SendMessageRequest, Session, SessionPersistence, SocialProvider, Store, Streak, type SubscribeOptions, SyncChange, SyncConflict, TransactionOp, TransactionOpResult, type Unsubscribe, UpsertOptions, User, UserEntitlement, XpBalance, XpTransaction, getCoreWasm, withOptimistic };
 //# sourceMappingURL=index.d.ts.map

package/dist-rn/index.js

@@ -192,6 +192,20 @@ function toAmbaApiError(err) {
 	return new AmbaApiError("UNKNOWN_ERROR", String(err));
 }
 
+//#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/realtime.ts
 const INITIAL_BACKOFF_MS = 500;
@@ -231,7 +245,7 @@ var CollectionSubscription = class {
 		if (!this.ctx.authHeaders()) throw new Error("Amba.collection().subscribe() requires an authenticated session — call Amba.auth.signIn*/verify* 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
@@ -352,7 +366,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*/verify* 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
@@ -675,6 +689,19 @@ async function* invokeAiStream(args) {
 //#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).
@@ -758,8 +785,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
@@ -782,6 +819,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
@@ -838,28 +885,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: [],
@@ -867,10 +941,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 {
@@ -889,8 +976,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 {
@@ -902,32 +1007,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,
@@ -935,6 +1028,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.
@@ -1388,6 +1504,13 @@ let _currentSessionExpiresAt = null;
 let _currentUser = null;
 const BROWSER_IDENTITY_VERSION = 1;
 const DEFAULT_SESSION_TTL_MS = 3600 * 1e3;
+/**
+* `AmbaConfig.sessionPersistence` for the current configuration. In
+* `"memory"` mode no identity snapshot (tokens, user id, anonymous id) is read
+* from or written to `localStorage`.
+*/
+let _sessionPersistence = "local";
+const SESSION_PERSISTENCE_MODES = ["local", "memory"];
 function identityStorageKey(projectId) {
 	return `identity:v${BROWSER_IDENTITY_VERSION}:project:${encodeURIComponent(projectId)}`;
 }
@@ -1427,8 +1550,26 @@ function readPersistedIdentity(persistence, projectId) {
 		return null;
 	}
 }
+/**
+* The identity the current core holds, for a `"memory"` re-configure of the
+* same project: the new core starts from it, so a second `configure()` in the
+* same page keeps the session.
+*/
+function liveIdentity(projectId) {
+	if (!coreInstance || _configuredProjectId !== projectId) return null;
+	return {
+		version: BROWSER_IDENTITY_VERSION,
+		project_id: projectId,
+		anonymous_id: coreInstance.anonymousId(),
+		app_user_id: coreInstance.appUserId() ?? null,
+		session_token: _currentSessionToken,
+		refresh_token: _currentRefreshToken,
+		expires_at: _currentSessionExpiresAt,
+		user: _currentUser
+	};
+}
 function writeIdentitySnapshot() {
-	if (!_persistence?.available || !_configuredProjectId || !coreInstance) return;
+	if (_sessionPersistence === "memory" || !_persistence?.available || !_configuredProjectId || !coreInstance) return;
 	const snapshot = {
 		version: BROWSER_IDENTITY_VERSION,
 		project_id: _configuredProjectId,
@@ -1582,12 +1723,29 @@ function getOfflineQueue() {
 		store: offlineStore(),
 		storageKey: `offline_outbox:${_configuredProjectId ?? "default"}`,
 		executor: replayOutboxOp,
+		currentOwner: () => ({
+			appUserId: _currentSessionToken || _currentRefreshToken ? coreInstance?.appUserId() ?? null : null,
+			anonymousId: coreInstance?.anonymousId() ?? null
+		}),
 		onDropped: (op, err) => {
 			if (typeof console !== "undefined") console.warn(`[amba] dropped un-replayable offline ${op.kind} (${op.collection ?? op.event ?? "?"}):`, err);
 		}
 	});
 	return _offlineQueue;
 }
+/**
+* Empty the offline outbox on sign-out, including writes queued on earlier
+* page loads, so nothing the signed-out user queued replays under the next
+* session.
+*/
+async function purgeOfflineOutbox() {
+	if (!_persistence) return;
+	try {
+		await getOfflineQueue().purge();
+	} catch (err) {
+		if (typeof console !== "undefined") console.warn("[amba] signOut could not clear the offline outbox", err);
+	}
+}
 async function insertDirect(name, row) {
 	return await coreCall((c) => c.collectionsInsert(name, encodeJson(row)));
 }
@@ -1711,8 +1869,8 @@ function buildAiStreamRequest(path, request) {
 * resolved default-host id is cached for subsequent invokes.
 */
 async function resolveFunctionUrl(name) {
-	if (_configuredFunctionsBaseUrl) return `${_configuredFunctionsBaseUrl.replace(/\/$/, "")}/${encodeURIComponent(name)}`;
-	return `https://${await resolveFunctionsProjectId()}.${DEFAULT_FUNCTIONS_HOST}/${encodeURIComponent(name)}`;
+	if (_configuredFunctionsBaseUrl) return `${_configuredFunctionsBaseUrl.replace(/\/$/, "")}/${pathSegment(name)}`;
+	return `https://${await resolveFunctionsProjectId()}.${DEFAULT_FUNCTIONS_HOST}/${pathSegment(name)}`;
 }
 async function resolveFunctionsProjectId() {
 	if (_resolvedFunctionsProjectId) return _resolvedFunctionsProjectId;
@@ -1871,8 +2029,10 @@ const Amba = {
 			if (explicitWasmInput !== void 0) await initCore({ module_or_path: explicitWasmInput });
 			else await initCore(); // Hermes-stripped Node-init block (DX-15) — see scripts/build-rn.mjs
 		}
+		const sessionPersistence = config.sessionPersistence ?? "local";
+		if (!SESSION_PERSISTENCE_MODES.includes(sessionPersistence)) throw new AmbaApiError("INVALID_CONFIG", "Amba.configure: sessionPersistence must be \"local\" or \"memory\"");
 		const persistence = new LocalStoragePersistence(config.storagePrefix ?? "amba");
-		const restoredIdentity = readPersistedIdentity(persistence, config.projectId);
+		const restoredIdentity = sessionPersistence === "memory" ? liveIdentity(config.projectId) : readPersistedIdentity(persistence, config.projectId);
 		let nextCore;
 		try {
 			const { wasmClass } = await getCoreRuntime();
@@ -1897,6 +2057,8 @@ const Amba = {
 		}
 		await teardownOffline();
 		_persistence = persistence;
+		_sessionPersistence = sessionPersistence;
+		if (sessionPersistence === "memory") persistence.delete(identityStorageKey(config.projectId));
 		coreInstance = nextCore;
 		_configuredProjectId = config.projectId;
 		_configuredApiUrl = config.apiUrl ?? DEFAULT_API_URL;
@@ -1929,6 +2091,7 @@ const Amba = {
 	},
 	events: {
 		track: async (event, properties, options) => {
+			const outboxTicket = _offlineEnabled ? getOfflineQueue().ticket() : void 0;
 			try {
 				await coreCall((c) => c.track(event, properties ? encodeJson(properties) : void 0, options?.telemetry));
 			} catch (err) {
@@ -1939,7 +2102,7 @@ const Amba = {
 						properties,
 						telemetry: options?.telemetry,
 						occurredAt: (/* @__PURE__ */ new Date()).toISOString()
-					});
+					}, outboxTicket);
 					return;
 				}
 				throw err;
@@ -2066,6 +2229,7 @@ const Amba = {
 			_currentSessionExpiresAt = null;
 			_currentUser = null;
 			writeIdentitySnapshot();
+			await purgeOfflineOutbox();
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -2141,6 +2305,7 @@ const Amba = {
 					...row,
 					idempotency_key: idempotencyKey
 				};
+				const outboxTicket = _offlineEnabled ? getOfflineQueue().ticket() : void 0;
 				try {
 					return await coreCall((c) => c.collectionsInsert(name, encodeJson(wireRow)));
 				} catch (err) {
@@ -2150,7 +2315,7 @@ const Amba = {
 							collection: name,
 							payload: row,
 							idempotencyKey
-						});
+						}, outboxTicket);
 						return {
 							...row,
 							_amba_pending: true
@@ -2162,39 +2327,45 @@ const Amba = {
 			return await coreCall((c) => c.collectionsInsert(name, encodeJson(row)));
 		},
 		update: async (name, id, set) => {
-			if (_offlineEnabled) try {
-				return await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set)));
-			} catch (err) {
-				if (isOfflineError(err)) {
-					await getOfflineQueue().enqueue({
-						kind: "collection.update",
-						collection: name,
-						id,
-						payload: set
-					});
-					return {
-						id,
-						...set,
-						_amba_pending: true
-					};
+			if (_offlineEnabled) {
+				const outboxTicket = _offlineEnabled ? getOfflineQueue().ticket() : void 0;
+				try {
+					return await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set)));
+				} catch (err) {
+					if (isOfflineError(err)) {
+						await getOfflineQueue().enqueue({
+							kind: "collection.update",
+							collection: name,
+							id,
+							payload: set
+						}, outboxTicket);
+						return {
+							id,
+							...set,
+							_amba_pending: true
+						};
+					}
+					throw err;
 				}
-				throw err;
 			}
 			return await coreCall((c) => c.collectionsUpdate(name, id, encodeJson(set)));
 		},
 		delete: async (name, id) => {
-			if (_offlineEnabled) try {
-				return await coreCall((c) => c.collectionsDelete(name, id));
-			} catch (err) {
-				if (isOfflineError(err)) {
-					await getOfflineQueue().enqueue({
-						kind: "collection.delete",
-						collection: name,
-						id
-					});
-					return { data: { deleted: true } };
+			if (_offlineEnabled) {
+				const outboxTicket = _offlineEnabled ? getOfflineQueue().ticket() : void 0;
+				try {
+					return await coreCall((c) => c.collectionsDelete(name, id));
+				} catch (err) {
+					if (isOfflineError(err)) {
+						await getOfflineQueue().enqueue({
+							kind: "collection.delete",
+							collection: name,
+							id
+						}, outboxTicket);
+						return { data: { deleted: true } };
+					}
+					throw err;
 				}
-				throw err;
 			}
 			return await coreCall((c) => c.collectionsDelete(name, id));
 		},
@@ -2337,7 +2508,7 @@ const Amba = {
 	media: { catalog: async (slug) => {
 		if (!_configuredClientKey) throw new AmbaApiError("NOT_INITIALIZED", "amba SDK not configured. Call Amba.configure({ projectId, clientKey }) before reading a media catalog.");
 		if (!slug || slug.trim() === "") throw new AmbaApiError("INVALID_ARGUMENT", "Amba.media.catalog: a catalog slug is required.");
-		const url = `${_configuredApiUrl.replace(/\/$/, "")}/v1/client/media/catalogs/${encodeURIComponent(slug)}`;
+		const url = `${_configuredApiUrl.replace(/\/$/, "")}/v1/client/media/catalogs/${pathSegment(slug)}`;
 		let resp;
 		try {
 			resp = await fetch(url, {
@@ -2672,7 +2843,7 @@ function getCoreWasm() {
 * `verify-sdk-version-coherence` GH action gates every publish on the
 * pair agreeing (and matching the `web-v<X.Y.Z>` tag when tag-triggered).
 */
-const SDK_VERSION = "4.0.10";
+const SDK_VERSION = "4.0.11";
 
 //#endregion
 export { Amba, AmbaApiError, AmbaGroupScopedClient, CollectionSubscription, ConversationSubscription, GamificationSubscription, SDK_VERSION, getCoreWasm, withOptimistic };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba-web",
-  "version": "4.0.10",
+  "version": "4.0.11",
   "description": "amba SDK for browser apps — full SDK 4.0 surface (34 modules: auth + magic link, users, sessions, sync, collections + vector search, storage + list/delete/download, push, entitlements, flags, config, deep links, onboarding, content, messaging, friends, groups, feeds, reviews, moderation, roles, referrals, achievements, xp, streaks, challenges, leaderboards, leagues, currencies, inventory, stores, catalog, ai, diagnostics).",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@layers/amba-core": "^4.0.10"
+    "@layers/amba-core": "^4.0.11"
   },
   "devDependencies": {
     "@types/node": "^22.13.14",