@layers/amba-web 4.0.9 → 4.0.11

package/dist/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;
@@ -1882,8 +2040,10 @@ const Amba = {
 				await initCore({ module_or_path: await readFile(fileURLToPath(wasmJsUrl)) });
 			} else await initCore();
 		}
+		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();
@@ -1908,6 +2068,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;
@@ -1940,6 +2102,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) {
@@ -1950,7 +2113,7 @@ const Amba = {
 						properties,
 						telemetry: options?.telemetry,
 						occurredAt: (/* @__PURE__ */ new Date()).toISOString()
-					});
+					}, outboxTicket);
 					return;
 				}
 				throw err;
@@ -2077,6 +2240,7 @@ const Amba = {
 			_currentSessionExpiresAt = null;
 			_currentUser = null;
 			writeIdentitySnapshot();
+			await purgeOfflineOutbox();
 			notifyAuthSubscribers(null);
 		},
 		refresh: async () => {
@@ -2152,6 +2316,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) {
@@ -2161,7 +2326,7 @@ const Amba = {
 							collection: name,
 							payload: row,
 							idempotencyKey
-						});
+						}, outboxTicket);
 						return {
 							...row,
 							_amba_pending: true
@@ -2173,39 +2338,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));
 		},
@@ -2348,7 +2519,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, {
@@ -2683,7 +2854,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.9";
+const SDK_VERSION = "4.0.11";
 
 //#endregion
 export { Amba, AmbaApiError, AmbaGroupScopedClient, CollectionSubscription, ConversationSubscription, GamificationSubscription, SDK_VERSION, getCoreWasm, withOptimistic };