refactor: move clerk mock mutation to util

Author: Saravana Kumar Rajendran

docs/docs/Integrations/clerk-token-refresh.md

@@ -0,0 +1,32 @@
+---
+title: Clerk Token Refresh Behavior
+slug: /clerk-token-refresh
+---
+
+This page summarizes how Langflow handles access token refreshes in different authentication modes and what state changes occur when using Clerk.
+
+## Refresh scenarios when Clerk authentication is disabled
+
+When `CLERK_AUTH_ENABLED` is `false`, Langflow relies on its internal authentication. Tokens are refreshed in these situations:
+
+1. **Protected routes** – the `ProtectedRoute` component periodically calls the `/refresh` endpoint using the `useRefreshAccessToken` hook.
+2. **API requests** – the API interceptor automatically triggers the same hook when a request fails with a `401` or `403` error.
+
+Both cases invoke the `useRefreshAccessToken` hook which posts to `/refresh` and updates the refresh token cookie.
+The default interval used by `ProtectedRoute` is defined by `LANGFLOW_ACCESS_TOKEN_EXPIRE_SECONDS` (54 minutes by default) or the value of the `ACCESS_TOKEN_EXPIRE_SECONDS` environment variable.
+
+## State updates when using Clerk
+
+When `CLERK_AUTH_ENABLED` is `true`, token refresh from the frontend is skipped. After signing in with Clerk, `ClerkAuthAdapter` logs the user in to the backend and calls `login()` from the authentication context, which updates several states:
+
+| State location | Value after Clerk token update |
+|----------------|--------------------------------|
+| `access_token_lf` cookie | Clerk session token |
+| `refresh_token_lf` cookie | Backend refresh token |
+| `auto_login_lf` cookie | `"login"` |
+| Local storage `access_token_lf` | Clerk session token |
+| `authStore.accessToken` | Clerk session token |
+| `authStore.isAuthenticated` | `true` |
+| `authContext.userData` | populated from `/users/whoami` |
+
+With Clerk enabled the periodic refresh is disabled and all further state changes rely on Clerk sessions.

src/frontend/src/controllers/API/queries/auth/use-post-refresh-access.ts

@@ -1,3 +1,5 @@
+import { IS_CLERK_AUTH } from "@/constants/clerk";
+import { mockClerkMutation } from "@/utils/mocks/mockMutationClerk";
 import { IS_AUTO_LOGIN, LANGFLOW_REFRESH_TOKEN } from "@/constants/constants";
 import useAuthStore from "@/stores/authStore";
 import { useMutationFunctionType } from "@/types/api";
@@ -20,6 +22,10 @@ export const useRefreshAccessToken: useMutationFunctionType<
   const cookies = new Cookies();
   const autoLogin = useAuthStore((state) => state.autoLogin);
 
+  if (IS_CLERK_AUTH) {
+    return mockClerkMutation;
+  }
+
   async function refreshAccess(): Promise<IRefreshAccessToken> {
     const res = await api.post<IRefreshAccessToken>(`${getURL("REFRESH")}`);
     cookies.set(LANGFLOW_REFRESH_TOKEN, res.data.refresh_token, { path: "/" });

src/frontend/src/utils/mocks/mockMutationClerk.ts

@@ -0,0 +1,13 @@
+export const mockClerkMutation = {
+  mutate: () => {},
+  mutateAsync: async () => undefined,
+  isError: false,
+  isIdle: true,
+  isPending: false,
+  isSuccess: true,
+  reset: () => {},
+  status: "success",
+  variables: undefined,
+  data: undefined,
+  error: null,
+} as any;