@hexclave/js 1.0.125 → 1.0.126

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

@@ -11,7 +11,6 @@ import { deepPlainEquals, omit } from "@hexclave/shared/dist/utils/objects";
 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";
@@ -32,9 +31,10 @@ 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 { 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";
@@ -134,6 +134,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.`;
@@ -275,6 +278,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();
@@ -474,6 +479,10 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 				prepareRequest: async () => {}
 			});
 		}
+		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._urlOptions = resolvedOptions.urls ?? {};
@@ -497,22 +506,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();
@@ -1080,6 +1089,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");
@@ -1121,27 +1133,27 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 				throw new Error(`Invalid token store ${tokenStoreInit}`);
 		}
 	}
+	_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
@@ -1159,6 +1171,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);
@@ -1507,6 +1520,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,
@@ -2315,6 +2329,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;
+	}
 	_getTokenPartialUserFromSession(session, options) {
 		const accessToken = session.getAccessTokenIfNotExpiredYet(0, null);
 		if (!accessToken) return null;
@@ -2325,6 +2370,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,
@@ -2334,11 +2380,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,
@@ -2678,6 +2727,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,
@@ -2798,6 +2849,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,