Abstract route paths resolution

Introduces a resourse class for tasks in order to resolve paths strings, avoiding placing that logic in the main `Clerk` interface which is more developer facing

All methods are appended with `__internal` as it's not intented for public usage even by custom flows

Author: LauraBeatris

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

@@ -934,7 +934,7 @@ export class Clerk implements ClerkInterface {
           eventBus.dispatch(events.InternalComponentNavigate, resolveNavigation),
         );
       } else {
-        await this.navigate(this.internal__buildSessionTaskUrl());
+        await this.navigate(newSession?.__internal_buildSessionTaskUrl(this.#options, this.environment));
       }
     }
 
@@ -949,9 +949,7 @@ export class Clerk implements ClerkInterface {
         'Use the `redirectUrl` property instead. Example `Clerk.setActive({redirectUrl:"/"})`',
       );
       beforeUnloadTracker?.startTracking();
-
       this.#setTransitiveState();
-
       await beforeEmit(newSession);
       beforeUnloadTracker?.stopTracking();
     }
@@ -1157,24 +1155,6 @@ export class Clerk implements ClerkInterface {
     return this.buildUrlWithAuth(this.environment.displayConfig.organizationProfileUrl);
   }
 
-  // pass this to the session object as internal
-  public internal__buildSessionTaskUrl(): string {
-    const [currentTask] = this.session?.tasks ?? [];
-
-    if (!currentTask || !this.environment || !this.environment.displayConfig) {
-      return '';
-    }
-
-    const signInUrl = this.#options['signInUrl'] || this.environment.displayConfig.signInUrl;
-    const signUpUrl = this.#options['signUpUrl'] || this.environment.displayConfig.signUpUrl;
-    const isReferrerSignUpUrl = window.location.href.startsWith(signUpUrl);
-
-    return buildURL(
-      { base: isReferrerSignUpUrl ? signUpUrl : signInUrl, hashPath: '/add-organization' },
-      { stringify: true },
-    );
-  }
-
   #redirectToSatellite = async (): Promise<unknown> => {
     if (!inBrowser()) {
       return;

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

@@ -1,4 +1,4 @@
-import type { SignUpModes } from '@clerk/types';
+import type { SessionTaskKey, SignUpModes } from '@clerk/types';
 
 // TODO: Do we still have a use for this or can we simply preserve all params?
 export const PRESERVED_QUERYSTRING_PARAMS = [
@@ -48,5 +48,10 @@ export const SIGN_UP_MODES: Record<string, SignUpModes> = {
   WAITLIST: 'waitlist',
 };
 
+export const SESSION_TASK_ROUTE_PATH_BY_KEY: Record<SessionTaskKey, string> = {
+  org: 'add-organization',
+};
+export const SESSION_TASK_ROUTE_PATHS = Object.values(SESSION_TASK_ROUTE_PATH_BY_KEY);
+
 // This is the currently supported version of the Frontend API
 export const SUPPORTED_FAPI_VERSION = '2024-10-01';

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

@@ -4,15 +4,16 @@ import { retry } from '@clerk/shared/retry';
 import type {
   ActJWTClaim,
   CheckAuthorization,
+  ClerkOptions,
   EmailCodeConfig,
+  EnvironmentResource,
   GetToken,
   GetTokenOptions,
   PhoneCodeConfig,
   SessionJSON,
   SessionJSONSnapshot,
   SessionResource,
   SessionStatus,
-  SessionTask,
   SessionVerificationJSON,
   SessionVerificationResource,
   SessionVerifyAttemptFirstFactorParams,
@@ -24,11 +25,13 @@ import type {
   UserResource,
 } from '@clerk/types';
 
+import { buildURL, inBrowser } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
 import { clerkInvalidStrategy } from '../errors';
 import { eventBus, events } from '../events';
 import { SessionTokenCache } from '../tokenCache';
 import { BaseResource, PublicUserData, Token, User } from './internal';
+import { SessionTask } from './SessionTask';
 import { SessionVerification } from './SessionVerification';
 
 export class Session extends BaseResource implements SessionResource {
@@ -226,7 +229,7 @@ export class Session extends BaseResource implements SessionResource {
     this.createdAt = unixEpochToDate(data.created_at);
     this.updatedAt = unixEpochToDate(data.updated_at);
     this.user = new User(data.user);
-    this.tasks = data.tasks;
+    this.tasks = data.tasks?.map(task => new SessionTask(task)) ?? [];
 
     if (data.public_user_data) {
       this.publicUserData = new PublicUserData(data.public_user_data);
@@ -303,4 +306,21 @@ export class Session extends BaseResource implements SessionResource {
       return token.getRawString() || null;
     });
   }
+
+  public __internal_buildSessionTaskUrl(options: ClerkOptions, environment?: EnvironmentResource | null): string {
+    const [currentTask] = this.tasks ?? [];
+
+    if (!currentTask || !environment || !inBrowser()) {
+      return '';
+    }
+
+    const signInUrl = options['signInUrl'] || environment.displayConfig.signInUrl;
+    const signUpUrl = options['signUpUrl'] || environment.displayConfig.signUpUrl;
+    const isReferrerSignUpUrl = window.location.href.startsWith(signUpUrl);
+
+    return buildURL(
+      { base: isReferrerSignUpUrl ? signUpUrl : signInUrl, hashPath: currentTask.__internal_getNavigationPath() },
+      { stringify: true },
+    );
+  }
 }

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

@@ -0,0 +1,36 @@
+import type { SessionTaskJSON, SessionTaskJSONSnapshot, SessionTaskKey, SessionTaskResource } from '@clerk/types';
+
+export const SESSION_TASK_PATHS = ['add-organization'] as const;
+type SessionTaskPath = (typeof SESSION_TASK_PATHS)[number];
+
+export const SESSION_TASK_PATH_BY_KEY: Record<SessionTaskKey, SessionTaskPath> = {
+  org: 'add-organization',
+} as const;
+
+export class SessionTask implements SessionTaskResource {
+  key!: SessionTaskKey;
+
+  constructor(data: SessionTaskJSON | SessionTaskJSONSnapshot) {
+    this.fromJSON(data);
+  }
+
+  protected fromJSON(data: SessionTaskJSON | SessionTaskJSONSnapshot): this {
+    if (!data) {
+      return this;
+    }
+
+    this.key = data.key;
+
+    return this;
+  }
+
+  public __internal_toSnapshot(): SessionTaskJSONSnapshot {
+    return {
+      key: this.key,
+    };
+  }
+
+  public __internal_getNavigationPath(): `/${SessionTaskPath}` {
+    return `/${SESSION_TASK_PATH_BY_KEY[this.key]}`;
+  }
+}

packages/clerk-js/src/ui/common/withRedirect.tsx

@@ -30,9 +30,6 @@ export function withRedirect<P extends AvailableComponentProps>(
 
     const hasTaskAndSingleSessionMode = !!clerk.session?.tasks && environment?.authConfig.singleSessionMode;
     const shouldRedirect = hasTaskAndSingleSessionMode ? false : condition(clerk, environment, options);
-    const redirectUrlWithDefault = hasTaskAndSingleSessionMode
-      ? () => clerk.internal__buildSessionTaskUrl()
-      : redirectUrl;
 
     React.useEffect(() => {
       if (shouldRedirect) {
@@ -41,7 +38,7 @@ export function withRedirect<P extends AvailableComponentProps>(
         }
         // TODO: Fix this properly
         // eslint-disable-next-line @typescript-eslint/no-floating-promises
-        navigate(redirectUrlWithDefault({ clerk, environment, options }));
+        navigate(redirectUrl({ clerk, environment, options }));
       }
     }, []);
 

packages/clerk-js/src/ui/components/SessionTask/SessionTask.tsx

@@ -1,5 +1,5 @@
 import { useSessionContext } from '@clerk/shared/react/index';
-import type { SessionTask } from '@clerk/types';
+import type { SessionTaskKey } from '@clerk/types';
 import { type ComponentType } from 'react';
 
 import { OrganizationListContext } from '../../contexts';
@@ -8,7 +8,7 @@ import { OrganizationList } from '../OrganizationList';
 /**
  * @internal
  */
-const SessionTaskRegistry: Record<SessionTask['key'], ComponentType> = {
+const SessionTaskRegistry: Record<SessionTaskKey, ComponentType> = {
   org: () => (
     // TODO - Hide personal workspace within organization list context based on environment
     <OrganizationListContext.Provider value={{ componentName: 'OrganizationList', hidePersonal: true }}>
@@ -20,7 +20,7 @@ const SessionTaskRegistry: Record<SessionTask['key'], ComponentType> = {
 /**
  * @internal
  */
-export function Task(): React.ReactNode {
+export function SessionTask(): React.ReactNode {
   const session = useSessionContext();
   const [currentTask] = session?.tasks ?? [];
 

packages/clerk-js/src/ui/components/SignIn/SignIn.tsx

@@ -2,6 +2,7 @@ import { useClerk } from '@clerk/shared/react';
 import type { SignInModalProps, SignInProps } from '@clerk/types';
 import React from 'react';
 
+import { SESSION_TASK_ROUTE_PATHS } from '../../../core/constants';
 import { normalizeRoutingOptions } from '../../../utils/normalizeRoutingOptions';
 import { SignInEmailLinkFlowComplete, SignUpEmailLinkFlowComplete } from '../../common/EmailLinkCompleteFlowCard';
 import type { SignUpContextType } from '../../contexts';
@@ -14,7 +15,7 @@ import {
 } from '../../contexts';
 import { Flow } from '../../customizables';
 import { Route, Switch, VIRTUAL_ROUTER_BASE_PATH } from '../../router';
-import { Task } from '../SessionTask/SessionTask';
+import { SessionTask } from '../SessionTask/SessionTask';
 import { SignUpContinue } from '../SignUp/SignUpContinue';
 import { SignUpSSOCallback } from '../SignUp/SignUpSSOCallback';
 import { SignUpStart } from '../SignUp/SignUpStart';
@@ -77,10 +78,14 @@ function SignInRoutes(): JSX.Element {
             redirectUrl='../factor-two'
           />
         </Route>
-        {/* Make it type safe based on the possible route paths / introduce abstraction */}
-        <Route path='add-organization'>
-          <Task />
-        </Route>
+        {SESSION_TASK_ROUTE_PATHS.map(path => (
+          <Route
+            path={path}
+            key={path}
+          >
+            <SessionTask />
+          </Route>
+        ))}
         {signInContext.isCombinedFlow && (
           <Route path='create'>
             <Route

packages/types/src/clerk.ts

@@ -476,8 +476,6 @@ export interface Clerk {
    */
   buildWaitlistUrl(opts?: { initialValues?: Record<string, string> }): string;
 
-  internal__buildSessionTaskUrl(): string;
-
   /**
    *
    * Redirects to the provided url after decorating it with the auth token for development instances.

packages/types/src/json.ts

@@ -12,7 +12,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { SamlIdpSlug } from './saml';
-import type { SessionStatus, SessionTask } from './session';
+import type { SessionStatus, SessionTaskKey } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
 import type { SignInFirstFactor, SignInJSON, SignInSecondFactor } from './signIn';
 import type { SignUpField, SignUpIdentificationField, SignUpStatus } from './signUp';
@@ -101,6 +101,10 @@ export interface SignUpJSON extends ClerkResourceJSON {
   verifications: SignUpVerificationsJSON | null;
 }
 
+export interface SessionTaskJSON {
+  key: SessionTaskKey;
+}
+
 export interface SessionJSON extends ClerkResourceJSON {
   object: 'session';
   id: string;
@@ -117,7 +121,7 @@ export interface SessionJSON extends ClerkResourceJSON {
   last_active_token: TokenJSON;
   last_active_organization_id: string | null;
   actor: ActJWTClaim | null;
-  tasks: Array<SessionTask> | null;
+  tasks: Array<SessionTaskJSON> | null;
   user: UserJSON;
   public_user_data: PublicUserDataJSON;
   created_at: number;

packages/types/src/session.ts

@@ -1,3 +1,6 @@
+import type { ClerkOptions } from 'clerk';
+import type { EnvironmentResource } from 'environment';
+
 import type {
   BackupCodeAttempt,
   EmailCodeAttempt,
@@ -103,7 +106,7 @@ export interface SessionResource extends ClerkResource {
   lastActiveOrganizationId: string | null;
   lastActiveAt: Date;
   actor: ActJWTClaim | null;
-  tasks: Array<SessionTask> | null;
+  tasks: Array<SessionTaskResource> | null;
   user: UserResource | null;
   publicUserData: PublicUserData;
   end: () => Promise<SessionResource>;
@@ -129,6 +132,7 @@ export interface SessionResource extends ClerkResource {
     params: SessionVerifyAttemptSecondFactorParams,
   ) => Promise<SessionVerificationResource>;
   __internal_toSnapshot: () => SessionJSONSnapshot;
+  __internal_buildSessionTaskUrl: (options: ClerkOptions, environment?: EnvironmentResource | null) => string;
 }
 
 /**
@@ -196,8 +200,10 @@ export interface PublicUserData {
   userId?: string;
 }
 
-export interface SessionTask {
-  key: 'org';
+export type SessionTaskKey = 'org';
+
+export interface SessionTaskResource {
+  key: SessionTaskKey;
 }
 
 export type GetTokenOptions = {

packages/types/src/snapshots.ts

@@ -18,6 +18,7 @@ import type {
   SamlAccountConnectionJSON,
   SamlAccountJSON,
   SessionJSON,
+  SessionTaskJSON,
   SignUpJSON,
   SignUpVerificationJSON,
   SignUpVerificationsJSON,
@@ -93,6 +94,8 @@ export type SessionJSONSnapshot = Override<
   }
 >;
 
+export type SessionTaskJSONSnapshot = SessionTaskJSON;
+
 export type SignUpJSONSnapshot = Override<
   Nullable<SignUpJSON, 'status'>,
   {