@hexclave/next 1.0.123 → 1.0.126

package/dist/esm/lib/hexclave-app/apps/implementations/client-app-impl.init-analytics.test.js

@@ -0,0 +1,66 @@
+import { KnownErrors } from "@hexclave/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { HexclaveClientApp } from "../interfaces/client-app.js";
+//#region src/lib/hexclave-app/apps/implementations/client-app-impl.init-analytics.test.ts
+const baseOptions = {
+	baseUrl: "http://localhost:12345",
+	projectId: "00000000-0000-4000-8000-000000000000",
+	publishableClientKey: "stack-pk-test",
+	tokenStore: "memory",
+	redirectMethod: "none",
+	noAutomaticPrefetch: true
+};
+const analyticsAppDisabledMessage = "initAnalytics() was called, but the Analytics app is not enabled on this Hexclave project";
+function simulateAnalyticsUploadResult(app, result) {
+	const handler = Reflect.get(app, "_handleAnalyticsUploadResult");
+	if (typeof handler !== "function") throw new Error("Expected HexclaveClientApp to have a _handleAnalyticsUploadResult method");
+	handler.call(app, result);
+}
+describe("HexclaveClientApp.initAnalytics", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+	it("does not throw when analytics are configured", () => {
+		const app = new HexclaveClientApp(baseOptions);
+		expect(() => app.initAnalytics()).not.toThrow();
+	});
+	it("throws when analytics are disabled with the analytics option", () => {
+		const app = new HexclaveClientApp({
+			...baseOptions,
+			analytics: { enabled: false }
+		});
+		expect(() => app.initAnalytics()).toThrow("`analytics.enabled` constructor option is set to false");
+	});
+	it("does not throw when only session replays are disabled", () => {
+		const app = new HexclaveClientApp({
+			...baseOptions,
+			analytics: { replays: { enabled: false } }
+		});
+		expect(() => app.initAnalytics()).not.toThrow();
+	});
+	it("reports an error when the backend rejects uploads after initAnalytics() was called", () => {
+		const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+		const app = new HexclaveClientApp(baseOptions);
+		app.initAnalytics();
+		simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));
+		simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));
+		expect(consoleError.mock.calls.filter((args) => args.some((arg) => String(arg).includes(analyticsAppDisabledMessage)))).toHaveLength(1);
+	});
+	it("throws from initAnalytics() when the backend already rejected uploads before it was called", () => {
+		const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+		const app = new HexclaveClientApp(baseOptions);
+		simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));
+		expect(consoleError.mock.calls.some((args) => args.some((arg) => String(arg).includes(analyticsAppDisabledMessage)))).toBe(false);
+		expect(() => app.initAnalytics()).toThrow(analyticsAppDisabledMessage);
+	});
+	it("ignores upload failures unrelated to the Analytics app being disabled", () => {
+		const app = new HexclaveClientApp(baseOptions);
+		simulateAnalyticsUploadResult(app, Result.error(/* @__PURE__ */ new Error("network error")));
+		expect(() => app.initAnalytics()).not.toThrow();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=client-app-impl.init-analytics.test.js.map

package/dist/esm/lib/hexclave-app/apps/implementations/client-app-impl.init-analytics.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-app-impl.init-analytics.test.js","names":[],"sources":["../../../../../../src/lib/hexclave-app/apps/implementations/client-app-impl.init-analytics.test.ts"],"sourcesContent":["\n//===========================================\n// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template\n//===========================================\nimport { KnownErrors } from \"@hexclave/shared\";\nimport { Result } from \"@hexclave/shared/dist/utils/results\";\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { HexclaveClientApp, HexclaveClientAppConstructorOptions } from \"../interfaces/client-app\";\n\nconst baseOptions = {\n  baseUrl: \"http://localhost:12345\",\n  projectId: \"00000000-0000-4000-8000-000000000000\",\n  publishableClientKey: \"stack-pk-test\",\n  tokenStore: \"memory\",\n  redirectMethod: \"none\",\n  noAutomaticPrefetch: true,\n} satisfies HexclaveClientAppConstructorOptions<true, string>;\n\nconst analyticsAppDisabledMessage = \"initAnalytics() was called, but the Analytics app is not enabled on this Hexclave project\";\n\n// The backend's AnalyticsNotEnabled rejection only reaches the client through the event tracker's and session\n// recorder's upload callbacks, which only exist in a browser; this simulates such a rejection arriving.\nfunction simulateAnalyticsUploadResult(app: HexclaveClientApp, result: Result<Response, Error>) {\n  const handler: unknown = Reflect.get(app, \"_handleAnalyticsUploadResult\");\n  if (typeof handler !== \"function\") {\n    throw new Error(\"Expected HexclaveClientApp to have a _handleAnalyticsUploadResult method\");\n  }\n  handler.call(app, result);\n}\n\ndescribe(\"HexclaveClientApp.initAnalytics\", () => {\n  afterEach(() => {\n    vi.restoreAllMocks();\n  });\n\n  it(\"does not throw when analytics are configured\", () => {\n    const app = new HexclaveClientApp(baseOptions);\n    expect(() => app.initAnalytics()).not.toThrow();\n  });\n\n  it(\"throws when analytics are disabled with the analytics option\", () => {\n    const app = new HexclaveClientApp({ ...baseOptions, analytics: { enabled: false } });\n    expect(() => app.initAnalytics()).toThrow(\"`analytics.enabled` constructor option is set to false\");\n  });\n\n  it(\"does not throw when only session replays are disabled\", () => {\n    const app = new HexclaveClientApp({ ...baseOptions, analytics: { replays: { enabled: false } } });\n    expect(() => app.initAnalytics()).not.toThrow();\n  });\n\n  it(\"reports an error when the backend rejects uploads after initAnalytics() was called\", () => {\n    const consoleError = vi.spyOn(console, \"error\").mockImplementation(() => {});\n    const app = new HexclaveClientApp(baseOptions);\n    app.initAnalytics();\n\n    simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));\n    // Repeated rejections must not report the error again.\n    simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));\n\n    const reports = consoleError.mock.calls.filter((args) => args.some((arg) => String(arg).includes(analyticsAppDisabledMessage)));\n    expect(reports).toHaveLength(1);\n  });\n\n  it(\"throws from initAnalytics() when the backend already rejected uploads before it was called\", () => {\n    const consoleError = vi.spyOn(console, \"error\").mockImplementation(() => {});\n    const app = new HexclaveClientApp(baseOptions);\n\n    simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));\n    expect(consoleError.mock.calls.some((args) => args.some((arg) => String(arg).includes(analyticsAppDisabledMessage)))).toBe(false);\n\n    expect(() => app.initAnalytics()).toThrow(analyticsAppDisabledMessage);\n  });\n\n  it(\"ignores upload failures unrelated to the Analytics app being disabled\", () => {\n    const app = new HexclaveClientApp(baseOptions);\n    simulateAnalyticsUploadResult(app, Result.error(new Error(\"network error\")));\n    expect(() => app.initAnalytics()).not.toThrow();\n  });\n});\n"],"mappings":";;;;;AASA,MAAM,cAAc;CAClB,SAAS;CACT,WAAW;CACX,sBAAsB;CACtB,YAAY;CACZ,gBAAgB;CAChB,qBAAqB;AACvB;AAEA,MAAM,8BAA8B;AAIpC,SAAS,8BAA8B,KAAwB,QAAiC;CAC9F,MAAM,UAAmB,QAAQ,IAAI,KAAK,8BAA8B;CACxE,IAAI,OAAO,YAAY,YACrB,MAAM,IAAI,MAAM,0EAA0E;CAE5F,QAAQ,KAAK,KAAK,MAAM;AAC1B;AAEA,SAAS,yCAAyC;CAChD,gBAAgB;EACd,GAAG,gBAAgB;CACrB,CAAC;CAED,GAAG,sDAAsD;EACvD,MAAM,MAAM,IAAI,kBAAkB,WAAW;EAC7C,aAAa,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,QAAQ;CAChD,CAAC;CAED,GAAG,sEAAsE;EACvE,MAAM,MAAM,IAAI,kBAAkB;GAAE,GAAG;GAAa,WAAW,EAAE,SAAS,MAAM;EAAE,CAAC;EACnF,aAAa,IAAI,cAAc,CAAC,CAAC,CAAC,QAAQ,wDAAwD;CACpG,CAAC;CAED,GAAG,+DAA+D;EAChE,MAAM,MAAM,IAAI,kBAAkB;GAAE,GAAG;GAAa,WAAW,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE;EAAE,CAAC;EAChG,aAAa,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,QAAQ;CAChD,CAAC;CAED,GAAG,4FAA4F;EAC7F,MAAM,eAAe,GAAG,MAAM,SAAS,OAAO,CAAC,CAAC,yBAAyB,CAAC,CAAC;EAC3E,MAAM,MAAM,IAAI,kBAAkB,WAAW;EAC7C,IAAI,cAAc;EAElB,8BAA8B,KAAK,OAAO,MAAM,IAAI,YAAY,oBAAoB,CAAC,CAAC;EAEtF,8BAA8B,KAAK,OAAO,MAAM,IAAI,YAAY,oBAAoB,CAAC,CAAC;EAGtF,OADgB,aAAa,KAAK,MAAM,QAAQ,SAAS,KAAK,MAAM,QAAQ,OAAO,GAAG,CAAC,CAAC,SAAS,2BAA2B,CAAC,CAChH,CAAC,CAAC,CAAC,aAAa,CAAC;CAChC,CAAC;CAED,GAAG,oGAAoG;EACrG,MAAM,eAAe,GAAG,MAAM,SAAS,OAAO,CAAC,CAAC,yBAAyB,CAAC,CAAC;EAC3E,MAAM,MAAM,IAAI,kBAAkB,WAAW;EAE7C,8BAA8B,KAAK,OAAO,MAAM,IAAI,YAAY,oBAAoB,CAAC,CAAC;EACtF,OAAO,aAAa,KAAK,MAAM,MAAM,SAAS,KAAK,MAAM,QAAQ,OAAO,GAAG,CAAC,CAAC,SAAS,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK;EAEhI,aAAa,IAAI,cAAc,CAAC,CAAC,CAAC,QAAQ,2BAA2B;CACvE,CAAC;CAED,GAAG,+EAA+E;EAChF,MAAM,MAAM,IAAI,kBAAkB,WAAW;EAC7C,8BAA8B,KAAK,OAAO,sBAAM,IAAI,MAAM,eAAe,CAAC,CAAC;EAC3E,aAAa,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,QAAQ;CAChD,CAAC;AACH,CAAC"}

package/dist/esm/lib/hexclave-app/apps/implementations/client-app-impl.js

@@ -14,7 +14,6 @@ import { getTrustedParentDomain, validateRedirectUrl } from "@hexclave/shared/di
 import { decodeBase32, decodeBase64, encodeBase32, encodeBase64 } from "@hexclave/shared/dist/utils/bytes";
 import { hexclaveAppInternalsSymbol } from "../../common.js";
 import { adminProjectCreateOptionsToCrud } from "../../projects/index.js";
-import { InternalSession } from "@hexclave/shared/dist/sessions";
 import { Store } from "@hexclave/shared/dist/utils/stores";
 import { crossDomainAuthQueryParams, getCrossDomainHandoffParamsFromCurrentUrl, planRedirectToHandler } from "./redirect-page-urls.js";
 import { BROWSER_ACTION_QUERY_PARAM } from "@hexclave/shared/dist/utils/browser-action-snippets";
@@ -37,10 +36,11 @@ import { teamCreateOptionsToCrud, teamUpdateOptionsToCrud } from "../../teams/in
 import { buildCliAuthConfirmUrl, getHostedHandlerUrl, isHostedHandlerUrlForProject, resolveHandlerUrls } from "../../url-targets.js";
 import { userUpdateOptionsToCrud, withUserDestructureGuard } from "../../users/index.js";
 import { EventTracker } from "./event-tracker.js";
+import { ExternalTokenStoreSessionAdapter, isExternalTokenStore } from "./external-token-store-session-adapter.js";
 import { augmentUrlWithPersistedRedirectBackState, getRawAfterAuthReturnTo, saveRedirectBackStateFromUrl } from "./redirect-back-state.js";
 import { recordRedirectAndThrowIfLoopDetected } from "./redirect-loop-breaker.js";
 import { subscribeSessionRefresh } from "./session-refresh-subscription.js";
-import { SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions } from "./session-replay.js";
+import { SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions, isAnalyticsNotEnabledError } from "./session-replay.js";
 import { mountClickmapOverlay } from "../../../../clickmap/index.js";
 import { mountDevTool } from "../../../../dev-tool/index.js";
 import { mountPushedConfigErrorOverlay } from "../../../../pushed-config-error-overlay/index.js";
@@ -145,6 +145,9 @@ function throwSetupError(error) {
 	showSetupErrorOverlay(error);
 	throw error;
 }
+function createAnalyticsAppDisabledOnProjectError() {
+	return /* @__PURE__ */ new Error("initAnalytics() was called, but the Analytics app is not enabled on this Hexclave project, so the backend rejects all analytics uploads. Enable the Analytics app in the Hexclave dashboard (or in hexclave.config.ts), or remove the initAnalytics() call if this is intentional.");
+}
 function getRedirectHelperInstruction(handlerName) {
 	if (handlerName === "handler") return "Use a page-specific redirect helper such as app.redirectToSignIn() instead.";
 	return `Use app.${`redirectTo${handlerName.slice(0, 1).toUpperCase()}${handlerName.slice(1)}`}() instead.`;
@@ -305,6 +308,8 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		this._uniqueIdentifier = void 0;
 		this._sessionRecorder = null;
 		this._eventTracker = null;
+		this._initAnalyticsCalled = false;
+		this._analyticsAppDisabledOnProject = false;
 		this._pendingSignOut = null;
 		this.__DEMO_ENABLE_SLIGHT_FETCH_DELAY = false;
 		this._ownedAdminApps = new DependenciesMap();
@@ -511,6 +516,10 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 				}
 			});
 		}
+		this._externalTokenStoreSessionAdapter = new ExternalTokenStoreSessionAdapter((sessionOptions) => this._interface.createSession(sessionOptions), async (providerId, token) => {
+			const exchange = await this._interface.exchangeExternalAuthToken(providerId, token);
+			return Result.orThrow(exchange).accessToken;
+		});
 		this._tokenStoreInit = resolvedOptions.tokenStore;
 		this._redirectMethod = resolvedOptions.redirectMethod || (isBrowserLike() ? "window" : "none");
 		this._redirectMethod = resolvedOptions.redirectMethod || "nextjs";
@@ -535,22 +544,22 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 			})) return await this._getSession();
 			return (await this.getUser({ or: "anonymous" }))._internalSession;
 		};
-		const analyticsEnabled = this._analyticsOptions?.enabled !== false;
+		const recordsAnalytics = this._getAnalyticsDisabledReason() == null && isBrowserLike();
 		const sessionReplayOptions = getSessionReplayOptions(this._analyticsOptions);
-		if (analyticsEnabled && isBrowserLike() && this._hasPersistentTokenStore() && sessionReplayOptions.enabled) {
+		if (recordsAnalytics && sessionReplayOptions.enabled) {
 			this._sessionRecorder = new SessionRecorder({
 				projectId: this.projectId,
 				sendBatch: async (body, opts) => {
-					return await this._interface.sendSessionReplayBatch(body, await getAnalyticsSession(), opts);
+					return this._handleAnalyticsUploadResult(await this._interface.sendSessionReplayBatch(body, await getAnalyticsSession(), opts));
 				}
 			}, sessionReplayOptions);
 			this._sessionRecorder.start();
 		}
-		if (analyticsEnabled && isBrowserLike() && this._hasPersistentTokenStore()) {
+		if (recordsAnalytics) {
 			this._eventTracker = new EventTracker({
 				projectId: this.projectId,
 				sendBatch: async (body, opts) => {
-					return await this._interface.sendAnalyticsEventBatch(body, await getAnalyticsSession(), opts);
+					return this._handleAnalyticsUploadResult(await this._interface.sendAnalyticsEventBatch(body, await getAnalyticsSession(), opts));
 				}
 			});
 			this._eventTracker.start();
@@ -1125,6 +1134,9 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 			case "memory": return this._memoryTokenStore;
 			default:
 				if (tokenStoreInit === null) return createEmptyTokenStore();
+				else if (typeof tokenStoreInit === "object" && isExternalTokenStore(tokenStoreInit)) return this._externalTokenStoreSessionAdapter.getOrCreateTokenStore(tokenStoreInit, (store, previousSessionKey) => {
+					this._sessionsByTokenStoreAndSessionKey.get(store)?.get(previousSessionKey)?.suggestAccessTokenExpired();
+				});
 				else if (typeof tokenStoreInit === "object" && "headers" in tokenStoreInit) {
 					if (this._requestTokenStores.has(tokenStoreInit)) return this._requestTokenStores.get(tokenStoreInit);
 					const authorizationHeader = getHeaderValueFromRequestLikeHeaders(tokenStoreInit.headers, "authorization");
@@ -1171,27 +1183,27 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		const cookieHelper = createBrowserCookieHelper();
 		return this._getOrCreateTokenStore(cookieHelper, overrideTokenStoreInit);
 	}
+	_getSessionKeyForTokenStore(tokenStore, tokenObj) {
+		return this._externalTokenStoreSessionAdapter.getSessionKey(tokenStore, tokenObj);
+	}
 	/**
 	* @param overrideTokenObj The tokens to build the session for, if they haven't been written to the token store yet
 	*                         (so we can warm a sign-in's session before the token store publishes it).
 	*/
 	_getSessionFromTokenStore(tokenStore, overrideTokenObj) {
 		const tokenObj = overrideTokenObj ?? tokenStore.get();
-		const sessionKey = InternalSession.calculateSessionKey(tokenObj);
+		const sessionKey = this._getSessionKeyForTokenStore(tokenStore, tokenObj);
 		const existing = sessionKey ? this._sessionsByTokenStoreAndSessionKey.get(tokenStore)?.get(sessionKey) : null;
 		if (existing) return existing;
-		const session = this._interface.createSession({
-			refreshToken: tokenObj.refreshToken,
-			accessToken: tokenObj.accessToken
-		});
+		const session = this._externalTokenStoreSessionAdapter.createSessionForTokenStore(tokenStore, tokenObj, sessionKey);
 		session.onAccessTokenChange((newAccessToken) => {
-			tokenStore.update((old) => InternalSession.calculateSessionKey(old) === sessionKey ? {
+			tokenStore.update((old) => this._getSessionKeyForTokenStore(tokenStore, old) === sessionKey ? {
 				...old,
 				accessToken: newAccessToken?.token ?? null
 			} : old);
 		});
 		session.onInvalidate(() => {
-			tokenStore.update((old) => InternalSession.calculateSessionKey(old) === sessionKey ? {
+			tokenStore.update((old) => this._getSessionKeyForTokenStore(tokenStore, old) === sessionKey ? {
 				...old,
 				accessToken: null,
 				refreshToken: null
@@ -1222,6 +1234,7 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 	}
 	async _signInToAccountWithTokens(tokens) {
 		if (!("accessToken" in tokens) || !("refreshToken" in tokens)) throw new HexclaveAssertionError("Invalid tokens object; can't sign in with this", { tokens });
+		if (this.isExternalAuthApp()) throw new Error("This app authenticates through an external provider and cannot sign in with Hexclave tokens. Sign in through the provider instead.");
 		const attemptId = ++this._signInAttemptCounter;
 		const tokenStore = this._getOrCreateTokenStore(await this._createCookieHelper());
 		const session = this._getSessionFromTokenStore(tokenStore, tokens);
@@ -1615,6 +1628,7 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 			emailAuthEnabled: crud.auth_with_email,
 			otpAuthEnabled: crud.otp_auth_enabled,
 			oauthProviders: crud.oauth_providers,
+			externalAuthProviders: crud.external_auth_providers,
 			passkeyAuthEnabled: crud.passkey_auth_enabled,
 			isMultiFactorRequired: crud.requires_totp_mfa,
 			isAnonymous: crud.is_anonymous,
@@ -2577,6 +2591,37 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		}
 		return crud && this._currentUserFromCrud(crud, session);
 	}
+	isExternalAuthApp() {
+		return typeof this._tokenStoreInit === "object" && this._tokenStoreInit != null && isExternalTokenStore(this._tokenStoreInit);
+	}
+	initAnalytics() {
+		this._initAnalyticsCalled = true;
+		const disabledReason = this._getAnalyticsDisabledReason();
+		if (disabledReason != null) throw new Error(`initAnalytics() was called, but this Hexclave app will not record analytics because ${disabledReason}. Remove the initAnalytics() call if this is intentional.`);
+		if (this._analyticsAppDisabledOnProject) throw createAnalyticsAppDisabledOnProjectError();
+		if (isBrowserLike() && this._eventTracker == null) throw new HexclaveAssertionError("initAnalytics() was called in the browser and _getAnalyticsDisabledReason() returned null, but the constructor did not start the event tracker. The two must agree on when analytics are recorded.");
+	}
+	/**
+	* Returns why this app will never record analytics, or null if it records them whenever it runs in a browser. The
+	* constructor and initAnalytics() both use this, so that the conditions under which analytics start and the
+	* conditions under which initAnalytics() throws can't drift apart.
+	*
+	* Whether the Analytics app is enabled on the project is not part of this, as the client only learns that once the
+	* backend rejects an upload; see _handleAnalyticsUploadResult.
+	*/
+	_getAnalyticsDisabledReason() {
+		if (this._analyticsOptions?.enabled === false) return "the `analytics.enabled` constructor option is set to false";
+		if (this._options.automaticSideEffects === false) return "the `automaticSideEffects` constructor option is set to false, which also disables analytics";
+		if (!this._hasPersistentTokenStore()) return "the `tokenStore` constructor option is null; analytics require a persistent token store such as \"cookie\" (or \"nextjs-cookie\" in Next.js)";
+		return null;
+	}
+	_handleAnalyticsUploadResult(result) {
+		if (result.status === "error" && isAnalyticsNotEnabledError(result.error) && !this._analyticsAppDisabledOnProject) {
+			this._analyticsAppDisabledOnProject = true;
+			if (this._initAnalyticsCalled) captureError("initAnalytics", createAnalyticsAppDisabledOnProjectError());
+		}
+		return result;
+	}
 	useUser(options) {
 		if (options?.or === "anonymous" && options.includeRestricted === false) throw new Error("Cannot use { or: 'anonymous' } with { includeRestricted: false }. Anonymous users implicitly include restricted users.");
 		this._ensurePersistentTokenStore(options?.tokenStore);
@@ -2626,6 +2671,7 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 			primaryEmail: accessToken.payload.email,
 			displayName: accessToken.payload.name,
 			primaryEmailVerified: accessToken.payload.email_verified,
+			selectedTeamId: accessToken.payload.selected_team_id,
 			isAnonymous,
 			isMultiFactorRequired: accessToken.payload.requires_totp_mfa,
 			isRestricted: accessToken.payload.is_restricted,
@@ -2635,11 +2681,14 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 	async _getPartialUserFromConvex(ctx) {
 		const auth = await ctx.auth.getUserIdentity();
 		if (!auth) return null;
+		const selectedTeamId = auth.selected_team_id ?? null;
+		if (selectedTeamId !== null && typeof selectedTeamId !== "string") throw new HexclaveAssertionError("Expected the Convex selected_team_id claim to be a string or null.");
 		return {
 			id: auth.subject,
 			displayName: auth.name ?? null,
 			primaryEmail: auth.email ?? null,
 			primaryEmailVerified: auth.email_verified,
+			selectedTeamId,
 			isAnonymous: auth.is_anonymous,
 			isMultiFactorRequired: auth.requires_totp_mfa,
 			isRestricted: auth.is_restricted,
@@ -2990,6 +3039,8 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		const previousSignOut = this._pendingSignOut;
 		const signOutOperation = (async () => {
 			await previousSignOut;
+			const externalTokenStore = this._externalTokenStoreSessionAdapter.getExternalTokenStoreForSession(session);
+			if (externalTokenStore != null) throw new HexclaveAssertionError(`Cannot sign out an externally authenticated session through Hexclave. Sign out through the ${externalTokenStore.providerId} provider instead.`);
 			await this._interface.signOut(session);
 			if (options?.redirectUrl) await this._redirectTo({
 				url: options.redirectUrl,
@@ -3143,6 +3194,7 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		return {
 			toClientJson: () => {
 				if (typeof this._redirectMethod !== "string") throw new HexclaveAssertionError("Cannot serialize to JSON from an application with a non-string redirect method");
+				if (typeof this._tokenStoreInit === "object" && this._tokenStoreInit != null && isExternalTokenStore(this._tokenStoreInit)) throw new HexclaveAssertionError("Cannot serialize an app with an external token store because its callbacks are not serializable. Construct this app in the client runtime instead.");
 				const publishableClientKey = "publishableClientKey" in this._interface.options ? this._interface.options.publishableClientKey : void 0;
 				return {
 					baseUrl: this._options.baseUrl,