From 1fc2d3af9a8fa6bb05ff4179115437b9184d4001 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Thu, 14 Nov 2024 17:24:20 -0800
Subject: [PATCH 1/2] feat(vue): Add more client helpers

---
 docs/references/vue/use-organization.mdx | 113 +++++++++++++++++++++++
 docs/references/vue/use-session-list.mdx |  77 +++++++++++++++
 docs/references/vue/use-session.mdx      |  55 +++++++++++
 docs/references/vue/use-sign-up.mdx      |  86 +++++++++++++++++
 4 files changed, 331 insertions(+)
 create mode 100644 docs/references/vue/use-organization.mdx
 create mode 100644 docs/references/vue/use-session-list.mdx
 create mode 100644 docs/references/vue/use-session.mdx
 create mode 100644 docs/references/vue/use-sign-up.mdx

diff --git a/docs/references/vue/use-organization.mdx b/docs/references/vue/use-organization.mdx
new file mode 100644
index 0000000000..46c8149e8a
--- /dev/null
+++ b/docs/references/vue/use-organization.mdx
@@ -0,0 +1,113 @@
+---
+title: '`useOrganization()`'
+description: Clerk's useOrganization() composable retrieves attributes of the currently active organization.
+---
+
+The `useOrganization()` composable is used to retrieve attributes of the currently active organization.
+
+## `useOrganization()` returns
+
+<Properties>
+  - `isLoaded`
+  - `boolean`
+
+  A boolean that is set to `false` until Clerk loads and initializes.
+
+  ---
+
+  - `organization`
+  - [`Organization`](/docs/references/javascript/organization/organization)
+
+  The currently active organization.
+
+  ---
+
+  - `membership`
+  - [`OrganizationMembership`](/docs/references/javascript/organization-membership)
+
+  The current organization membership.
+</Properties>
+
+## How to use the `useOrganization()` composable
+
+The following example shows how to use the `useOrganization()` composable to access the current active [`Organization`](/docs/references/javascript/organization/organization) object.
+
+```vue {{ filename: 'home.vue' }}
+<script setup>
+import { useOrganization } from '@clerk/vue'
+
+const { organization, isLoaded } = useOrganization()
+</script>
+
+<template>
+  <div v-if="isLoaded">
+    <p>This current organization is {{ organization.name }}</p>
+  </div>
+
+  <div v-else>
+    <p>Loading...</p>
+  </div>
+</template>
+```
+
+## Paginating data
+
+The following example demonstrates how to implement pagination for organization memberships. The `memberships` attribute will be populated with the first page of the organization's memberships. When the "Previous page" or "Next page" button is clicked, the `fetchMemberships` function will be called to fetch the previous or next page of memberships.
+
+You can implement this pattern to any Clerk function that returns a [`ClerkPaginatedResponse`](/docs/references/javascript/types/clerk-paginated-response#clerk-paginated-response) object.
+
+```vue {{ filename: 'member-list.vue' }}
+<script setup>
+import { ref, watchEffect } from 'vue'
+import { useOrganization } from '@clerk/vue'
+
+const memberships = ref([])
+const currentPage = ref(1)
+const { organization, isLoading } = useOrganization()
+
+const pageSize = 10
+
+async function fetchMemberships() {
+  if (!organization.value) {
+    return
+  }
+
+  const { data } = await organization.value.getMemberships({
+    initialPage: currentPage.value,
+    pageSize: 5,
+  })
+  memberships.value = data
+}
+
+watchEffect(() => {
+  if (!organization.value) {
+    return
+  }
+
+  fetchMemberships()
+})
+
+const fetchPrevious = () => currentPage.value--
+const fetchNext = () => currentPage.value++
+</script>
+
+<template>
+  <div v-if="isLoading">
+    <h2>Organization members</h2>
+    <ul>
+      <li v-for="membership in memberships" :key="membership.id">
+        {{ membership.publicUserData.firstName }} {{ membership.publicUserData.lastName }} &lt;{{
+          membership.publicUserData.identifier
+        }}&gt; :: {{ membership.role }}
+      </li>
+    </ul>
+    <div>
+      <button :disabled="currentPage === 1" @click="fetchPrevious">Previous</button>
+      <button @click="fetchNext">Next</button>
+    </div>
+  </div>
+  <div v-else>
+    <p>Loading...</p>
+  </div>
+</template>
+```
diff --git a/docs/references/vue/use-session-list.mdx b/docs/references/vue/use-session-list.mdx
new file mode 100644
index 0000000000..dfa2a6cb30
--- /dev/null
+++ b/docs/references/vue/use-session-list.mdx
@@ -0,0 +1,77 @@
+---
+title: '`useSessionList()`'
+description: Clerk's useSessionList() composable retrieves a list of sessions that have been registered on the client device.
+---
+
+The `useSessionList()` composable returns an array of [`Session`](/docs/references/javascript/session) objects that have been registered on the client device.
+
+## `useSessionList()` returns
+
+<Properties>
+  - `isLoaded`
+  - `boolean`
+
+  A boolean that is set to `false` until Clerk loads and initializes.
+
+  ---
+
+  - `setActive()`
+  - <code>(params: [SetActiveParams](#set-active-params)) => Promise\<void></code>
+
+  A function that sets the active session and/or organization.
+
+  ---
+
+  - `sessions`
+  - <code>[Session](/docs/references/javascript/session)\[]</code>
+
+  A list of sessions that have been registered on the client device.
+</Properties>
+
+### `SetActiveParams`
+
+<Properties>
+  - `session`
+  - <code>[Session](/docs/references/javascript/session) | string | null</code>
+
+  The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted.
+
+  ---
+
+  - `organization`
+  - <code>[Organization](/docs/references/javascript/organization/organization) | string | null</code>
+
+  The organization resource or organization ID/slug (string version) to be set as active in the current session. If `null`, the currently active organization is removed as active.
+
+  ---
+
+  - `beforeEmit?`
+  - `(session?: Session | null) => void | Promise<any>`
+
+  Callback run just before the active session and/or organization is set to the passed object. Can be used to composable up for pre-navigation actions.
+</Properties>
+
+## How to use the `useSessionList()` composable
+
+The following example demonstrates how to use the `useSessionList()` composable to retrieve a list of sessions that have been registered on the client device. The `isLoaded` property is used to handle the loading state, and the `sessions` property is used to display the number of times the user has visited the page.
+
+```vue {{ filename: 'home.vue' }}
+<script setup>
+import { useSessionList } from '@clerk/vue'
+
+const { isLoaded, sessions } = useSessionList()
+</script>
+
+<template>
+  <div v-if="!isLoaded">
+    <!-- handle loading state -->
+  </div>
+
+  <div v-else>
+    <p>
+      Welcome back. You have been here
+      {{ sessions.length }} times before.
+    </p>
+  </div>
+</template>
+```
diff --git a/docs/references/vue/use-session.mdx b/docs/references/vue/use-session.mdx
new file mode 100644
index 0000000000..ff5dd57c64
--- /dev/null
+++ b/docs/references/vue/use-session.mdx
@@ -0,0 +1,55 @@
+---
+title: '`useSession()`'
+description: Clerk's useSession() composable provides access to the the current user Session object, as well as helpers to set the active session.
+---
+
+The `useSession()` composable provides access to the current user's [`Session`](/docs/references/javascript/session) object, as well as helpers for setting the active session.
+
+## `useSession()` returns
+
+<Properties>
+  - `isLoaded`
+  - `boolean`
+
+  A boolean that is set to `false` until Clerk loads and initializes.
+
+  ---
+
+  - `isSignedIn`
+  - `boolean`
+
+  A boolean that is set to `true` if the user is signed in.
+
+  ---
+
+  - `session`
+  - [`Session`](/docs/references/javascript/session)
+
+  Holds the current active session for the user.
+</Properties>
+
+## How to use the `useSession()` composable
+
+The following example demonstrates how to use the `useSession()` composable to access the `SignIn` object, which has the `lastActiveAt` property on it. The `lastActiveAt` property is used to display the last active time of the current session to the user.
+
+```vue {{ filename: 'home.vue' }}
+<script setup>
+import { useSession } from '@clerk/vue'
+
+const { isLoaded, session, isSignedIn } = useSession()
+</script>
+
+<template>
+  <div v-if="!isLoaded">
+    <!-- Add logic to handle loading state -->
+  </div>
+
+  <div v-else-if="!isSignedIn">
+    <!-- Add logic to handle not signed in state -->
+  </div>
+
+  <div v-else>
+    <p>This session has been active since {{ session.lastActiveAt.toLocaleString() }}</p>
+  </div>
+</template>
+```
diff --git a/docs/references/vue/use-sign-up.mdx b/docs/references/vue/use-sign-up.mdx
new file mode 100644
index 0000000000..1e18da96f8
--- /dev/null
+++ b/docs/references/vue/use-sign-up.mdx
@@ -0,0 +1,86 @@
+---
+title: '`useSignUp()`'
+description: Clerk's useSignUp() composable gives you access to the SignUp object, which allows you to check the current state of a sign-up.
+---
+
+The `useSignUp()` composable gives you access to the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up. This is also useful for creating a [custom sign-up flow.](#create-a-custom-sign-up-flow-with-use-sign-up)
+
+## `useSignUp()` returns
+
+<Properties>
+  - `isLoaded`
+  - `boolean`
+
+  A boolean that is set to `false` until Clerk loads and initializes.
+
+  ---
+
+  - `setActive()`
+  - <code>(params: [SetActiveParams](#set-active-params)) => Promise\<void></code>
+
+  A function that sets the active session.
+
+  ---
+
+  - `signUp`
+  - [`SignUp`](/docs/references/javascript/sign-up/sign-up)
+
+  An object that contains the current sign-up attempt status and methods to create a new sign-up attempt.
+</Properties>
+
+### `SetActiveParams`
+
+<Properties>
+  - `session`
+  - <code>[Session](/docs/references/javascript/session) | string | null</code>
+
+  The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted.
+
+  ---
+
+  - `organization`
+  - <code>[Organization](/docs/references/javascript/organization/organization) | string | null</code>
+
+  The organization resource or organization ID/slug (string version) to be set as active in the current session. If `null`, the currently active organization is removed as active.
+
+  ---
+
+  - `beforeEmit?`
+  - `(session?: Session | null) => void | Promise<any>`
+
+  Callback run just before the active session and/or organization is set to the passed object. Can be used to composable up for pre-navigation actions.
+</Properties>
+
+## How to use the `useSignUp()` composable
+
+### Check the current state of a sign-up with `useSignUp()`
+
+Use the `useSignUp()` composable to access the `SignUp` object and check the current state of a sign-up.
+
+```vue {{ filename: 'sign-up-step.vue' }}
+<script setup>
+import { useSignUp } from '@clerk/vue'
+
+const { isLoaded, signUp } = useSignUp()
+</script>
+
+<template>
+  <div v-if="!isLoaded">
+    <!-- Add logic to handle loading state -->
+  </div>
+
+  <div v-else>The current sign-up attempt status is {{ signUp.status }}.</div>
+</template>
+```
+
+The `status` property of the `SignUp` object can be one of the following values:
+
+| Values | Description |
+| - | - |
+| `complete` | The user has been created and custom flow can proceed to `setActive()` to create session. |
+| `abandoned` | The sign-up attempt will be abandoned if it was started more than 24 hours previously. |
+| `missing_requirements` | A requirement from the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) settings is missing. For example, in the Clerk Dashboard, the Password setting is required but a password was not provided in the custom flow. |
+
+### Create a custom sign-up flow with `useSignUp()`
+
+The `useSignUp()` composable can also be used to build fully custom sign-up flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-up flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignUp()` composable to create custom flows, check out the [custom flow guides](/docs/custom-flows/overview).

From ee99fc746482b3763edb9c78478825ca935f2a15 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Thu, 14 Nov 2024 19:05:31 -0800
Subject: [PATCH 2/2] fix return types

---
 docs/references/vue/use-organization.mdx | 6 +++---
 docs/references/vue/use-session-list.mdx | 6 +++---
 docs/references/vue/use-session.mdx      | 6 +++---
 docs/references/vue/use-sign-up.mdx      | 6 +++---
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/references/vue/use-organization.mdx b/docs/references/vue/use-organization.mdx
index 46c8149e8a..f140864629 100644
--- a/docs/references/vue/use-organization.mdx
+++ b/docs/references/vue/use-organization.mdx
@@ -9,21 +9,21 @@ The `useOrganization()` composable is used to retrieve attributes of the current
 
 <Properties>
   - `isLoaded`
-  - `boolean`
+  - `Ref<boolean>`
 
   A boolean that is set to `false` until Clerk loads and initializes.
 
   ---
 
   - `organization`
-  - [`Organization`](/docs/references/javascript/organization/organization)
+  - <code>Ref\<[Organization](/docs/references/javascript/organization/organization)></code>
 
   The currently active organization.
 
   ---
 
   - `membership`
-  - [`OrganizationMembership`](/docs/references/javascript/organization-membership)
+  - <code>Ref\<[OrganizationMembership](/docs/references/javascript/organization-membership)></code>
 
   The current organization membership.
 </Properties>
diff --git a/docs/references/vue/use-session-list.mdx b/docs/references/vue/use-session-list.mdx
index dfa2a6cb30..5e302ca1ec 100644
--- a/docs/references/vue/use-session-list.mdx
+++ b/docs/references/vue/use-session-list.mdx
@@ -9,21 +9,21 @@ The `useSessionList()` composable returns an array of [`Session`](/docs/referenc
 
 <Properties>
   - `isLoaded`
-  - `boolean`
+  - `Ref<boolean>`
 
   A boolean that is set to `false` until Clerk loads and initializes.
 
   ---
 
   - `setActive()`
-  - <code>(params: [SetActiveParams](#set-active-params)) => Promise\<void></code>
+  - <code>Ref\<(params: [SetActiveParams](#set-active-params)) => Promise\<void>></code>
 
   A function that sets the active session and/or organization.
 
   ---
 
   - `sessions`
-  - <code>[Session](/docs/references/javascript/session)\[]</code>
+  - <code>Ref\<[Session](/docs/references/javascript/session)></code>
 
   A list of sessions that have been registered on the client device.
 </Properties>
diff --git a/docs/references/vue/use-session.mdx b/docs/references/vue/use-session.mdx
index ff5dd57c64..c51cc4e1f1 100644
--- a/docs/references/vue/use-session.mdx
+++ b/docs/references/vue/use-session.mdx
@@ -9,21 +9,21 @@ The `useSession()` composable provides access to the current user's [`Session`](
 
 <Properties>
   - `isLoaded`
-  - `boolean`
+  - `Ref<boolean>`
 
   A boolean that is set to `false` until Clerk loads and initializes.
 
   ---
 
   - `isSignedIn`
-  - `boolean`
+  - `Ref<boolean>`
 
   A boolean that is set to `true` if the user is signed in.
 
   ---
 
   - `session`
-  - [`Session`](/docs/references/javascript/session)
+  - <code>Ref\<[Session](/docs/references/javascript/session)></code>
 
   Holds the current active session for the user.
 </Properties>
diff --git a/docs/references/vue/use-sign-up.mdx b/docs/references/vue/use-sign-up.mdx
index 1e18da96f8..612a13dc06 100644
--- a/docs/references/vue/use-sign-up.mdx
+++ b/docs/references/vue/use-sign-up.mdx
@@ -9,21 +9,21 @@ The `useSignUp()` composable gives you access to the [`SignUp`](/docs/references
 
 <Properties>
   - `isLoaded`
-  - `boolean`
+  - `Ref<boolean>`
 
   A boolean that is set to `false` until Clerk loads and initializes.
 
   ---
 
   - `setActive()`
-  - <code>(params: [SetActiveParams](#set-active-params)) => Promise\<void></code>
+  - <code>Ref\<(params: [SetActiveParams](#set-active-params)) => Promise\<void>></code>
 
   A function that sets the active session.
 
   ---
 
   - `signUp`
-  - [`SignUp`](/docs/references/javascript/sign-up/sign-up)
+  - <code>Ref\<[SignUp](/docs/references/javascript/sign-up/sign-up)></code>
 
   An object that contains the current sign-up attempt status and methods to create a new sign-up attempt.
 </Properties>