feat(core): Split setActive into selectSession and selectOrganization

.changeset/split-setactive-into-select-methods.md

@@ -0,0 +1,92 @@
+---
+'@clerk/clerk-js': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nextjs': major
+'@clerk/vue': major
+'@clerk/expo': major
+'@clerk/ui': major
+'@clerk/testing': major
+---
+
+Replace `setActive` with purpose-specific methods: `selectSession` and `selectOrganization`
+
+## Breaking Changes
+
+### `setActive` Removed from Public API
+
+The `setActive` method has been removed from the Clerk object and all hooks. Use the new purpose-specific methods instead:
+
+- `clerk.selectSession(session, options?)` - For session selection
+- `clerk.selectOrganization(organization, options?)` - For organization selection
+
+### Hook Return Types
+
+The following hooks no longer return `setActive`:
+
+- `useSignIn()` - now returns `selectSession` instead of `setActive`
+- `useSignUp()` - now returns `selectSession` instead of `setActive`
+- `useSessionList()` - now returns `selectSession` instead of `setActive`
+- `useOrganizationList()` - now returns `selectOrganization` instead of `setActive`
+
+### Migration
+
+**Before:**
+```tsx
+const { setActive } = useSignIn();
+await setActive({ session: createdSessionId });
+
+const { setActive } = useOrganizationList();
+await setActive({ organization: org });
+```
+
+**After:**
+```tsx
+const { selectSession } = useSignIn();
+await selectSession(createdSessionId);
+
+const { selectOrganization } = useOrganizationList();
+await selectOrganization(org);
+```
+
+### New Methods on Clerk Object
+
+Two new methods are available on the Clerk object:
+
+- `clerk.selectSession(session, options?)` - For session selection (sign-in, sign-up, multi-session switching)
+- `clerk.selectOrganization(organization, options?)` - For organization selection (org switching, personal workspace)
+
+### Options
+
+Both methods accept an options object:
+
+```tsx
+// selectSession options
+await selectSession(session, {
+  redirectUrl?: string;
+  navigate?: ({ session }) => void | Promise<void>;
+});
+
+// selectOrganization options
+await selectOrganization(organization, {
+  redirectUrl?: string;
+  navigate?: ({ session, organization }) => void | Promise<void>;
+});
+```
+
+### Expo Hooks
+
+The `StartGoogleAuthenticationFlowReturnType` and `StartAppleAuthenticationFlowReturnType` types now return `selectSession` instead of `setActive`.
+
+### Internal Window Hooks (Next.js)
+
+The internal window hooks have been renamed:
+- `__internal_onBeforeSetActive` → `__internal_onBeforeSelectSession`
+- `__internal_onAfterSetActive` → `__internal_onAfterSelectSession`
+
+### Types Removed
+
+The following types have been removed from the public API:
+- `SetActive`
+- `SetActiveParams`
+- `SetActiveNavigate` (use `SelectSessionNavigate` instead)

packages/clerk-js/src/core/clerk.ts

@@ -97,6 +97,8 @@ import type {
   RedirectOptions,
   Resources,
   SDKMetadata,
+  SelectOrganizationOptions,
+  SelectSessionOptions,
   SessionResource,
   SetActiveParams,
   SignedInSessionResource,
@@ -297,7 +299,7 @@ export class Clerk implements ClerkInterface {
   public __internal_isWebAuthnAutofillSupported: (() => Promise<boolean>) | undefined;
   public __internal_isWebAuthnPlatformAuthenticatorSupported: (() => Promise<boolean>) | undefined;
 
-  public __internal_setActiveInProgress = false;
+  public __internal_selectSessionInProgress = false;
 
   get publishableKey(): string {
     return this.#publishableKey;
@@ -583,13 +585,13 @@ export class Clerk implements ClerkInterface {
     }
 
     const onBeforeSetActive: SetActiveHook =
-      typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
-        ? window.__internal_onBeforeSetActive
+      typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+        ? window.__internal_onBeforeSelectSession
         : noop;
 
     const onAfterSetActive: SetActiveHook =
-      typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
-        ? window.__internal_onAfterSetActive
+      typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+        ? window.__internal_onAfterSelectSession
         : noop;
 
     const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
@@ -1446,7 +1448,7 @@ export class Clerk implements ClerkInterface {
   public setActive = async (params: SetActiveParams): Promise<void> => {
     const { organization, redirectUrl, navigate: setActiveNavigate } = params;
     let { session } = params;
-    this.__internal_setActiveInProgress = true;
+    this.__internal_selectSessionInProgress = true;
     debugLogger.debug(
       'setActive() start',
       {
@@ -1476,13 +1478,13 @@ export class Clerk implements ClerkInterface {
       }
 
       const onBeforeSetActive: SetActiveHook =
-        typeof window !== 'undefined' && typeof window.__internal_onBeforeSetActive === 'function'
-          ? window.__internal_onBeforeSetActive
+        typeof window !== 'undefined' && typeof window.__internal_onBeforeSelectSession === 'function'
+          ? window.__internal_onBeforeSelectSession
           : noop;
 
       const onAfterSetActive: SetActiveHook =
-        typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
-          ? window.__internal_onAfterSetActive
+        typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+          ? window.__internal_onAfterSelectSession
           : noop;
 
       let newSession = session === undefined ? this.session : session;
@@ -1605,10 +1607,79 @@ export class Clerk implements ClerkInterface {
         await onAfterSetActive();
       }
     } finally {
-      this.__internal_setActiveInProgress = false;
+      this.__internal_selectSessionInProgress = false;
     }
   };
 
+  /**
+   * Select a session to make active.
+   *
+   * Use this method after sign-in or sign-up to activate the created session,
+   * or to switch between sessions in a multi-session application.
+   *
+   * Pass `null` to sign out and clear the active session.
+   */
+  public selectSession = async (
+    session: SignedInSessionResource | string | null,
+    options?: SelectSessionOptions,
+  ): Promise<void> => {
+    const { navigate, redirectUrl } = options ?? {};
+
+    // Convert navigate callback to setActive format if provided
+    const setActiveNavigate = navigate
+      ? async ({ session: s }: { session: SessionResource }) => {
+          const result = await navigate({ session: s });
+          if (typeof result === 'string') {
+            await this.navigate(result);
+          }
+        }
+      : undefined;
+
+    return this.setActive({
+      session,
+      navigate: setActiveNavigate,
+      redirectUrl,
+    });
+  };
+
+  /**
+   * Select an organization to make active within the current session.
+   *
+   * Use this method to switch between organizations or to select a personal workspace.
+   *
+   * Pass `null` to switch to the personal workspace (no active organization).
+   */
+  public selectOrganization = async (
+    organization: OrganizationResource | string | null,
+    options?: SelectOrganizationOptions,
+  ): Promise<void> => {
+    const { navigate, redirectUrl } = options ?? {};
+
+    // Convert navigate callback to setActive format if provided
+    const setActiveNavigate = navigate
+      ? async ({ session }: { session: SessionResource }) => {
+          // Resolve the organization for the callback
+          const org =
+            organization === null
+              ? null
+              : typeof organization === 'string'
+                ? (this.organization ?? null)
+                : organization;
+
+          const result = await navigate({ session, organization: org });
+          if (typeof result === 'string') {
+            await this.navigate(result);
+          }
+        }
+      : undefined;
+
+    return this.setActive({
+      organization,
+      navigate: setActiveNavigate,
+      redirectUrl,
+    });
+  };
+
   public addListener = (listener: ListenerCallback): UnsubscribeCallback => {
     listener = memoizeListenerCallback(listener);
     this.#listeners.push(listener);
@@ -2596,8 +2667,8 @@ export class Clerk implements ClerkInterface {
       const hasTransitionedToPendingStatus = this.session.status === 'active' && session?.status === 'pending';
       if (hasTransitionedToPendingStatus) {
         const onAfterSetActive: SetActiveHook =
-          typeof window !== 'undefined' && typeof window.__internal_onAfterSetActive === 'function'
-            ? window.__internal_onAfterSetActive
+          typeof window !== 'undefined' && typeof window.__internal_onAfterSelectSession === 'function'
+            ? window.__internal_onAfterSelectSession
             : noop;
 
         // Execute hooks to update server authentication context and trigger

packages/clerk-js/src/core/resources/BillingCheckout.ts

@@ -204,7 +204,7 @@ export class CheckoutFlow implements CheckoutFlowResourceNonStrict {
         throw new Error('Clerk: `confirm()` must be called before `finalize()`');
       }
 
-      await BillingCheckout.clerk.setActive({ session: BillingCheckout.clerk.session?.id, navigate });
+      await BillingCheckout.clerk.selectSession(BillingCheckout.clerk.session?.id ?? null, { navigate });
     });
   }
 

packages/clerk-js/src/core/resources/SignIn.ts

@@ -1243,7 +1243,7 @@ class SignInFuture implements SignInFutureResource {
       }
 
       this.#hasBeenFinalized = true;
-      await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+      await SignIn.clerk.selectSession(this.#resource.createdSessionId, { navigate });
     });
   }
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -972,7 +972,7 @@ class SignUpFuture implements SignUpFutureResource {
       }
 
       this.#hasBeenFinalized = true;
-      await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
+      await SignUp.clerk.selectSession(this.#resource.createdSessionId, { navigate });
     });
   }
 }

packages/clerk-js/src/global.d.ts

@@ -15,8 +15,8 @@ const __BUILD_VARIANT_CHANNEL__: boolean;
 const __BUILD_VARIANT_CHIPS__: boolean;
 
 interface Window {
-  __internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-  __internal_onAfterSetActive: () => Promise<void> | void;
+  __internal_onBeforeSelectSession: (intent?: 'sign-out') => Promise<void> | void;
+  __internal_onAfterSelectSession: () => Promise<void> | void;
   // eslint-disable-next-line @typescript-eslint/consistent-type-imports
   __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
   /**

packages/clerk-js/src/test/mock-helpers.ts

@@ -99,7 +99,8 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
   });
 
   mockProp(clerkAny, 'navigate');
-  mockProp(clerkAny, 'setActive');
+  mockProp(clerkAny, 'selectSession');
+  mockProp(clerkAny, 'selectOrganization');
   mockProp(clerkAny, 'redirectWithAuth');
   mockProp(clerkAny, '__internal_navigateWithError');
   return clerkAny as DeepVitestMocked<LoadedClerk>;

packages/expo/src/hooks/useOAuth.ts

@@ -1,5 +1,5 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
-import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
+import type { OAuthStrategy, SelectSessionHook, SignInResource, SignUpResource } from '@clerk/shared/types';
 import * as AuthSession from 'expo-auth-session';
 import * as WebBrowser from 'expo-web-browser';
 
@@ -18,7 +18,7 @@ export type StartOAuthFlowParams = {
 
 export type StartOAuthFlowReturnType = {
   createdSessionId: string;
-  setActive?: SetActive;
+  selectSession?: SelectSessionHook;
   signIn?: SignInResource;
   signUp?: SignUpResource;
   authSessionResult?: WebBrowser.WebBrowserAuthSessionResult;
@@ -33,7 +33,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
     return errorThrower.throw('Missing oauth strategy');
   }
 
-  const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+  const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
   const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
   async function startOAuthFlow(startOAuthFlowParams?: StartOAuthFlowParams): Promise<StartOAuthFlowReturnType> {
@@ -42,7 +42,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
         createdSessionId: '',
         signIn,
         signUp,
-        setActive,
+        selectSession,
       };
     }
 
@@ -79,7 +79,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
       return {
         authSessionResult,
         createdSessionId: '',
-        setActive,
+        selectSession,
         signIn,
         signUp,
       };
@@ -108,7 +108,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
     return {
       authSessionResult,
       createdSessionId,
-      setActive,
+      selectSession,
       signIn,
       signUp,
     };

packages/expo/src/hooks/useSSO.ts

@@ -2,7 +2,7 @@ import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type {
   EnterpriseSSOStrategy,
   OAuthStrategy,
-  SetActive,
+  SelectSessionHook,
   SignInResource,
   SignUpResource,
 } from '@clerk/shared/types';
@@ -28,13 +28,13 @@ export type StartSSOFlowParams = {
 export type StartSSOFlowReturnType = {
   createdSessionId: string | null;
   authSessionResult: WebBrowser.WebBrowserAuthSessionResult | null;
-  setActive?: SetActive;
+  selectSession?: SelectSessionHook;
   signIn?: SignInResource;
   signUp?: SignUpResource;
 };
 
 export function useSSO() {
-  const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+  const { signIn, selectSession, isLoaded: isSignInLoaded } = useSignIn();
   const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
 
   async function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType> {
@@ -44,7 +44,7 @@ export function useSSO() {
         authSessionResult: null,
         signIn,
         signUp,
-        setActive,
+        selectSession,
       };
     }
 
@@ -81,7 +81,7 @@ export function useSSO() {
     if (authSessionResult.type !== 'success' || !authSessionResult.url) {
       return {
         createdSessionId: null,
-        setActive,
+        selectSession,
         signIn,
         signUp,
         authSessionResult,
@@ -102,7 +102,7 @@ export function useSSO() {
 
     return {
       createdSessionId: signUp.createdSessionId ?? signIn.createdSessionId,
-      setActive,
+      selectSession,
       signIn,
       signUp,
       authSessionResult,