Forward initial session status to signed out object

Author: LauraBeatris

.changeset/tender-brooms-look.md

@@ -1,8 +1,10 @@
 ---
-'@clerk/nextjs': patch
+'@clerk/nextjs': minor
 ---
 
-Introduce `treatPendingAsSignedOut` to `auth`, `getAuth` and server-side control components
+Introduce `treatPendingAsSignedOut` option to `getAuth` and `auth` from `clerkMiddleware`
+
+By default, `treatPendingAsSignedOut` is set to `true`, which means pending sessions are treated as signed-out. You can set this option to `false` to treat pending sessions as authenticated.
 
 ```ts
 const { userId } = auth({ treatPendingAsSignedOut: false })

packages/backend/src/tokens/authObjects.ts

@@ -5,6 +5,7 @@ import type {
   JwtPayload,
   ServerGetToken,
   ServerGetTokenOptions,
+  SessionStatusClaim,
   SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
@@ -37,7 +38,7 @@ export type SignedInAuthObject = SharedSignedInAuthObjectProperties & {
 export type SignedOutAuthObject = {
   sessionClaims: null;
   sessionId: null;
-  sessionStatus: null;
+  sessionStatus: SessionStatusClaim | null;
   actor: null;
   userId: null;
   orgId: null;
@@ -113,11 +114,14 @@ export function signedInAuthObject(
 /**
  * @internal
  */
-export function signedOutAuthObject(debugData?: AuthObjectDebugData): SignedOutAuthObject {
+export function signedOutAuthObject(
+  debugData?: AuthObjectDebugData,
+  initialSessionStatus?: SessionStatusClaim,
+): SignedOutAuthObject {
   return {
     sessionClaims: null,
     sessionId: null,
-    sessionStatus: null,
+    sessionStatus: initialSessionStatus ?? null,
     userId: null,
     actor: null,
     orgId: null,

packages/backend/src/tokens/authStatus.ts

@@ -27,7 +27,9 @@ export type SignedInState = {
   afterSignInUrl: string;
   afterSignUpUrl: string;
   isSignedIn: true;
-  toAuth: (opts?: PendingSessionOptions) => SignedInAuthObject;
+  toAuth: <T extends PendingSessionOptions | undefined = undefined>(
+    opts?: T,
+  ) => T extends undefined ? SignedInAuthObject : SignedInAuthObject | SignedOutAuthObject;
   headers: Headers;
   token: string;
 };
@@ -102,7 +104,7 @@ export function signedIn(
     // @ts-expect-error Dynamically return `SignedOutAuthObject` based on options
     toAuth: ({ treatPendingAsSignedOut = true } = {}) => {
       if (treatPendingAsSignedOut && authObject.sessionStatus === 'pending') {
-        return signedOutAuthObject();
+        return signedOutAuthObject(undefined, authObject.sessionStatus);
       }
 
       return authObject;

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

@@ -2284,7 +2284,7 @@ describe('Clerk singleton', () => {
         await sut.load(mockedLoadOptions);
 
         await sut.setActive({ session: mockResource as any as PendingSessionResource });
-        await sut.__experimental_nextTask();
+        await sut.__experimental_navigateToTask();
 
         expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/tasks/add-organization');
       });
@@ -2328,7 +2328,7 @@ describe('Clerk singleton', () => {
         await sut.setActive({ session: mockSession as any as ActiveSessionResource });
 
         const redirectUrlComplete = '/welcome-to-app';
-        await sut.__experimental_nextTask({ redirectUrlComplete });
+        await sut.__experimental_navigateToTask({ redirectUrlComplete });
 
         console.log(mockNavigate.mock.calls);
 

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

@@ -1199,7 +1199,7 @@ export class Clerk implements ClerkInterface {
     this.#emit();
   };
 
-  public __experimental_nextTask = async ({ redirectUrlComplete }: NextTaskParams = {}): Promise<void> => {
+  public __experimental_navigateToTask = async ({ redirectUrlComplete }: NextTaskParams = {}): Promise<void> => {
     const session = await this.session?.reload();
     if (!session || !this.environment) {
       return;

packages/clerk-js/src/ui/components/SessionTasks/index.tsx

@@ -21,7 +21,7 @@ const SessionTasksStart = withCardStateProvider(() => {
   useEffect(() => {
     // Simulates additional latency to avoid a abrupt UI transition when navigating to the next task
     const timeoutId = setTimeout(() => {
-      void clerk.__experimental_nextTask({ redirectUrlComplete });
+      void clerk.__experimental_navigateToTask({ redirectUrlComplete });
     }, 500);
     return () => clearTimeout(timeoutId);
   }, [navigate, clerk, redirectUrlComplete]);
@@ -80,7 +80,7 @@ export function SessionTask(): JSX.Element {
   }, [clerk, navigate, redirectUrlComplete]);
 
   const nextTask = useCallback(
-    () => clerk.__experimental_nextTask({ redirectUrlComplete }),
+    () => clerk.__experimental_navigateToTask({ redirectUrlComplete }),
     [clerk, redirectUrlComplete],
   );
 

packages/nextjs/src/server/createGetAuth.ts

@@ -53,7 +53,7 @@ export const createAsyncGetAuth = ({
 /**
  * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
  * that required dynamic imports (using `require` would not work).
- * It powers the synchronous top-level api `getAuh()`.
+ * It powers the synchronous top-level api `getAuth()`.
  */
 export const createSyncGetAuth = ({
   debugLoggerName,

packages/nextjs/src/server/data/getAuthDataFromRequest.ts

@@ -59,7 +59,7 @@ export function getAuthDataFromRequest(
   }
 
   if (treatPendingAsSignedOut && authObject.sessionStatus === 'pending') {
-    authObject = signedOutAuthObject(options);
+    authObject = signedOutAuthObject(options, authObject.sessionStatus);
   }
 
   return authObject;

packages/react/src/isomorphicClerk.ts

@@ -702,9 +702,9 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
   };
 
-  __experimental_nextTask = async (params?: NextTaskParams): Promise<void> => {
+  __experimental_navigateToTask = async (params?: NextTaskParams): Promise<void> => {
     if (this.clerkjs) {
-      return this.clerkjs.__experimental_nextTask(params);
+      return this.clerkjs.__experimental_navigateToTask(params);
     } else {
       return Promise.reject();
     }

packages/types/src/clerk.ts

@@ -715,7 +715,7 @@ export interface Clerk {
    * If all tasks are complete, it navigates to the provided completion URL.
    * @experimental
    */
-  __experimental_nextTask: (params?: NextTaskParams) => Promise<void>;
+  __experimental_navigateToTask: (params?: NextTaskParams) => Promise<void>;
 
   /**
    * This is an optional function.