feat(clerk-js): send touch intent with session updates

.changeset/warm-touch-intent.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Add optional `intent` parameter to `session.touch()` to indicate why the touch was triggered (focus, session switch, or org switch). This enables the backend to skip expensive client piggybacking for focus-only touches.

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

@@ -207,7 +207,7 @@
         const sut = new Clerk(productionPublishableKey);
         await sut.load();
         await sut.setActive({ session: mockSession as any as ActiveSessionResource });
-        expect(mockSession.touch).toHaveBeenCalled();
+        expect(mockSession.touch).toHaveBeenCalledWith({ intent: 'select_session' });
       });
 
       describe('with `touchSession` set to false', () => {
@@ -218,7 +218,7 @@
           const sut = new Clerk(productionPublishableKey);
           await sut.load({ touchSession: false });
           await sut.setActive({ session: mockSession as any as ActiveSessionResource });
-          expect(mockSession.touch).toHaveBeenCalled();
+          expect(mockSession.touch).toHaveBeenCalledWith({ intent: 'select_session' });
         });
       });
 
@@ -233,7 +233,7 @@
         const sut = new Clerk(productionPublishableKey);
         await sut.load();
         await sut.setActive({ session: mockSession as any as ActiveSessionResource });
-        expect(mockSession.touch).toHaveBeenCalled();
+        expect(mockSession.touch).toHaveBeenCalledWith({ intent: 'select_session' });
       });
 
       it('sets __session and __client_uat cookie before calling __internal_onBeforeSetActive', async () => {
@@ -280,7 +280,7 @@
         await sut.setActive({ organization: 'some-org-slug' });
 
         await waitFor(() => {
-          expect(mockSession2.touch).toHaveBeenCalled();
+          expect(mockSession2.touch).toHaveBeenCalledWith({ intent: 'select_org' });
           expect(mockSession2.getToken).toHaveBeenCalled();
           expect((mockSession2 as any as ActiveSessionResource)?.lastActiveOrganizationId).toEqual('org_id');
           expect(sut.session).toMatchObject(mockSession2);
@@ -363,7 +363,7 @@
         const sut = new Clerk(productionPublishableKey);
         await sut.load();
         await sut.setActive({ session: mockSession as any as PendingSessionResource, navigate });
-        expect(mockSession.__internal_touch).toHaveBeenCalled();
+        expect(mockSession.__internal_touch).toHaveBeenCalledWith({ intent: 'select_session' });
         expect(navigate).toHaveBeenCalled();
       });
 
@@ -2192,7 +2192,7 @@
       sut.setActive = mockSetActive;
 
       const redirectUrl = '/2fa';
       sut.handleEmailLinkVerification({ redirectUrl });
 
       await waitFor(() => {
         expect(mockSetActive).not.toHaveBeenCalled();
@@ -2252,7 +2252,7 @@
       sut.setActive = mockSetActive;
 
       const redirectUrl = '/next-up';
       sut.handleEmailLinkVerification({ redirectUrl });
 
       await waitFor(() => {
         expect(mockSetActive).not.toHaveBeenCalled();

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

@@ -101,6 +101,7 @@
   Resources,
   SDKMetadata,
   SessionResource,
+  SessionTouchParams,
   SetActiveParams,
   SignedInSessionResource,
   SignInProps,
@@ -1579,6 +1580,7 @@
         newSession?.currentTask &&
         this.#options.taskUrls?.[newSession?.currentTask.key];
       const shouldNavigate = !!(redirectUrl || taskUrl || setActiveNavigate);
+      const touchIntent: SessionTouchParams['intent'] = shouldSwitchOrganization ? 'select_org' : 'select_session';
 
       //1. setLastActiveSession to passed user session (add a param).
       //   Note that this will also update the session's active organization
@@ -1599,7 +1601,7 @@
         if (shouldNavigate && newSession) {
           try {
             // __internal_touch does not call updateClient automatically
-            updatedClient = await newSession.__internal_touch();
+            updatedClient = await newSession.__internal_touch({ intent: touchIntent });
             if (updatedClient) {
               // We call updateClient manually, but without letting it emit
               // It's important that the setTransitiveState call happens somewhat
@@ -1615,7 +1617,7 @@
             }
           }
         } else {
-          await this.#touchCurrentSession(newSession);
+          await this.#touchCurrentSession(newSession, touchIntent);
         }
         // If we do have the updatedClient, read from that, otherwise getSessionFromClient
         // will fallback to this.client. This makes no difference now, but will if we
@@ -2081,14 +2083,14 @@
     return;
   };
 
   public redirectToAfterSignIn = async (): Promise<unknown> => {
     if (inBrowser()) {
       return this.navigate(this.buildAfterSignInUrl());
     }
     return;
   };
 
   public redirectToAfterSignUp = async (): Promise<unknown> => {
     if (inBrowser()) {
       return this.navigate(this.buildAfterSignUpUrl());
     }
@@ -3150,7 +3152,7 @@
       this.#touchThrottledUntil = Date.now() + 5_000;
 
       if (this.#options.touchSession) {
-        void this.#touchCurrentSession(this.session);
+        void this.#touchCurrentSession(this.session, 'focus');
       }
     });
 
@@ -3181,12 +3183,15 @@
   };
 
   // TODO: Be more conservative about touches. Throttle, don't touch when only one user, etc
-  #touchCurrentSession = async (session?: SignedInSessionResource | null): Promise<void> => {
+  #touchCurrentSession = async (
+    session?: SignedInSessionResource | null,
+    intent: SessionTouchParams['intent'] = 'focus',
+  ): Promise<void> => {
     if (!session) {
       return Promise.resolve();
     }
 
-    await session.touch().catch(e => {
+    await session.touch({ intent }).catch(e => {
       if (isUnauthenticatedError(e)) {
         void this.handleUnauthenticated();
       } else {

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

@@ -29,6 +29,7 @@ import type {
   SessionResource,
   SessionStatus,
   SessionTask,
+  SessionTouchParams,
   SessionVerificationJSON,
   SessionVerificationResource,
   SessionVerifyAttemptFirstFactorParams,
@@ -103,14 +104,16 @@ export class Session extends BaseResource implements SessionResource {
   };
 
   private _touchPost = async (
-    { skipUpdateClient }: { skipUpdateClient: boolean } = { skipUpdateClient: false },
+    { intent, skipUpdateClient }: { intent?: SessionTouchParams['intent']; skipUpdateClient: boolean } = {
+      skipUpdateClient: false,
+    },
   ): Promise<FapiResponseJSON<SessionJSON> | null> => {
     const json = await BaseResource._fetch<SessionJSON>(
       {
         method: 'POST',
         path: this.path('touch'),
         // any is how we type the body in the BaseMutateParams as well
-        body: { active_organization_id: this.lastActiveOrganizationId } as any,
+        body: { active_organization_id: this.lastActiveOrganizationId, intent } as any,
       },
       { skipUpdateClient },
     );
@@ -121,8 +124,8 @@ export class Session extends BaseResource implements SessionResource {
     return json;
   };
 
-  touch = async (): Promise<SessionResource> => {
-    await this._touchPost();
+  touch = async ({ intent }: SessionTouchParams = {}): Promise<SessionResource> => {
+    await this._touchPost({ intent, skipUpdateClient: false });
 
     // _touchPost() will have updated `this` in-place
     // The post has potentially changed the session state, and so we need to ensure we emit the updated token that comes back in the response. This avoids potential issues where the session cookie is out of sync with the current session state.
@@ -143,8 +146,8 @@ export class Session extends BaseResource implements SessionResource {
    *
    * @internal
    */
-  __internal_touch = async (): Promise<ClientResource | undefined> => {
-    const json = await this._touchPost({ skipUpdateClient: true });
+  __internal_touch = async ({ intent }: SessionTouchParams = {}): Promise<ClientResource | undefined> => {
+    const json = await this._touchPost({ intent, skipUpdateClient: true });
     return getClientResourceFromPayload(json);
   };
 

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

@@ -798,6 +798,37 @@ describe('Session', () => {
         token: session.lastActiveToken,
       });
     });
+
+    it('passes touch intent in the request body', async () => {
+      const sessionData = {
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: 'org_123',
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON;
+      const session = new Session(sessionData);
+
+      const requestSpy = BaseResource.clerk.getFapiClient().request as Mock;
+      requestSpy.mockResolvedValue({
+        payload: { response: sessionData },
+        status: 200,
+      });
+
+      await session.touch({ intent: 'focus' });
+
+      expect(requestSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: { active_organization_id: 'org_123', intent: 'focus' },
+          method: 'POST',
+          path: '/client/sessions/session_1/touch',
+        }),
+        expect.anything(),
+      );
+    });
   });
 
   describe('__internal_touch()', () => {
@@ -902,6 +933,27 @@ describe('Session', () => {
 
       expect(session.lastActiveOrganizationId).toBe('org_456');
     });
+
+    it('passes touch intent in the request body', async () => {
+      const session = new Session(mockSessionData);
+      const requestSpy = BaseResource.clerk.getFapiClient().request as Mock;
+
+      requestSpy.mockResolvedValue({
+        payload: { response: mockSessionData },
+        status: 200,
+      });
+
+      await session.__internal_touch({ intent: 'select_session' });
+
+      expect(requestSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: { active_organization_id: 'org_123', intent: 'select_session' },
+          method: 'POST',
+          path: '/client/sessions/session_1/touch',
+        }),
+        expect.anything(),
+      );
+    });
   });
 
   describe('isAuthorized()', () => {

packages/shared/src/types/session.ts

@@ -240,7 +240,7 @@ export interface SessionResource extends ClerkResource {
    */
   end: () => Promise<SessionResource>;
   remove: () => Promise<SessionResource>;
-  touch: () => Promise<SessionResource>;
+  touch: (params?: SessionTouchParams) => Promise<SessionResource>;
   getToken: GetToken;
   checkAuthorization: CheckAuthorization;
   clearCache: () => void;
@@ -262,7 +262,7 @@ export interface SessionResource extends ClerkResource {
   ) => Promise<SessionVerificationResource>;
   verifyWithPasskey: () => Promise<SessionVerificationResource>;
   __internal_toSnapshot: () => SessionJSONSnapshot;
-  __internal_touch: () => Promise<ClientResource | undefined>;
+  __internal_touch: (params?: SessionTouchParams) => Promise<ClientResource | undefined>;
 }
 
 /**
@@ -322,6 +322,12 @@ export type SessionStatus =
   | 'revoked'
   | 'pending';
 
+export type SessionTouchIntent = 'focus' | 'select_session' | 'select_org';
+
+export type SessionTouchParams = {
+  intent?: SessionTouchIntent;
+};
+
 export interface PublicUserData {
   firstName: string | null;
   lastName: string | null;