feat: add set and clear token methods (#554)

docs/content/v0.6/3.application-side/2.session-access-and-management.md

@@ -168,3 +168,78 @@ await signOut(credentials, { callbackUrl: '/protected' })
 await getSession(credentials, { callbackUrl: '/protected' })
 ```
 ::
+
+## `useAuthState` Composable
+
+The `useAuthState` composable is the underlying storage layer to access the session-state and data. Here's the main methods and properties you can use:
+
+::code-group
+```ts [authjs]
+const {
+  status,
+  loading,
+  data,
+  lastRefreshedAt
+} = useAuth()
+
+// Session status, either `unauthenticated`, `loading`, `authenticated`
+status.value
+
+// Whether any http request is still pending
+loading.value
+
+// Session data, either `undefined` (= authentication not attempted), `null` (= user unauthenticated), `loading` (= session loading in progress), see https://next-auth.js.org/getting-started/client#signout
+data.value
+
+// Time at which the session was last refreshed, either `undefined` if no refresh was attempted or a `Date`-object of the time the refresh happened
+lastRefreshedAt.value
+```
+```ts [local]
+const {
+  status,
+  loading,
+  data,
+  lastRefreshedAt,
+  token,
+  rawToken,
+  getToken,
+  clearToken
+} = useAuth()
+
+// Session status, either `unauthenticated`, `loading`, `authenticated`
+status.value
+
+// Whether any http request is still pending
+loading.value
+
+// Session data, either `undefined` (= authentication not attempted), `null` (= user unauthenticated), or session / user data your `getSession`-endpoint returns
+data.value
+
+// Time at which the session was last refreshed, either `undefined` if no refresh was attempted or a `Date`-object of the time the refresh happened
+lastRefreshedAt.value
+
+// The fetched token that can be used to authenticate future requests. E.g., a JWT-Bearer token like so: `Bearer eyDFSJKLDAJ0-3249PPRFK3P5234SDFL;AFKJlkjdsjd.dsjlajhasdji89034`
+token.value
+
+// Cookie that containes the raw fetched token string. This token won't contain any modification or prefixes like `Bearer` or any other.
+rawToken.value
+
+// Helper method to quickly set a new token (alias for rawToken.value = 'xxx')
+setToken('new token')
+
+// Helper method to quickly delete the token cookie (alias for rawToken.value = null)
+clearToken()
+```
+::
+
+::alert{type="warning"}
+(Only local provider) Note that you will have to manually call `getSession` from `useAuth` composable in order to refresh the new user state when using `setToken`, `clearToken` or manually updating `rawToken.value`:
+
+```ts
+const { getSession } = useAuth()
+const { setToken } = useAuthState()
+// ...
+setToken('...')
+await getSession()
+```
+::

src/runtime/composables/local/useAuthState.ts

@@ -9,7 +9,9 @@ import type { SessionData } from '#auth'
 
 interface UseAuthStateReturn extends CommonUseAuthStateReturn<SessionData> {
   token: ComputedRef<string | null>
-  rawToken: CookieRef<string | null>
+  rawToken: CookieRef<string | null>,
+  setToken: (newToken: string | null) => void
+  clearToken: () => void
 }
 
 export const useAuthState = (): UseAuthStateReturn => {
@@ -29,14 +31,24 @@ export const useAuthState = (): UseAuthStateReturn => {
     return config.token.type.length > 0 ? `${config.token.type} ${rawToken.value}` : rawToken.value
   })
 
+  const setToken = (newToken: string | null) => {
+    rawToken.value = newToken
+  }
+
+  const clearToken = () => {
+    setToken(null)
+  }
+
   const schemeSpecificState = {
     token,
     rawToken
   }
 
   return {
     ...commonAuthState,
-    ...schemeSpecificState
+    ...schemeSpecificState,
+    setToken,
+    clearToken
   }
 }
 export default useAuthState