From 6190decd8294967e934f68699262fcf9656fd429 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Israel=20Ortu=C3=B1o?= <ai.ortuno@gmail.com>
Date: Mon, 23 Oct 2023 15:15:14 +0200
Subject: [PATCH] feat: add set and clear token methods (#554)

---
 .../2.session-access-and-management.md        | 75 +++++++++++++++++++
 src/runtime/composables/local/useAuthState.ts | 16 +++-
 2 files changed, 89 insertions(+), 2 deletions(-)

diff --git a/docs/content/v0.6/3.application-side/2.session-access-and-management.md b/docs/content/v0.6/3.application-side/2.session-access-and-management.md
index 302bfa1c..18bbe2b1 100644
--- a/docs/content/v0.6/3.application-side/2.session-access-and-management.md
+++ b/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()
+```
+::
\ No newline at end of file
diff --git a/src/runtime/composables/local/useAuthState.ts b/src/runtime/composables/local/useAuthState.ts
index 06ab54ec..b12f6b6d 100644
--- a/src/runtime/composables/local/useAuthState.ts
+++ b/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,6 +31,14 @@ 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
@@ -36,7 +46,9 @@ export const useAuthState = (): UseAuthStateReturn => {
 
   return {
     ...commonAuthState,
-    ...schemeSpecificState
+    ...schemeSpecificState,
+    setToken,
+    clearToken
   }
 }
 export default useAuthState