docs: added how to manage user profile guide (#3997)

docs/content/modules/users/admin/manage-profile.mdx

@@ -0,0 +1,522 @@
+---
+description: 'Learn how to implement user profile management features using the admin APIs. This includes user authentication, updating the profile, and reseting the password.'
+addHowToData: true
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Manage a User’s Profile
+
+In this document, you’ll learn how to implement user profile management features using the admin APIs.
+
+## Overview
+
+The user’s admin APIs allow you to retrieve and perform admin functionalities on users.
+
+### Scenario
+
+You want to add or use the following admin functionalities:
+
+- User authentication, meaning user log in and log out.
+- Manage profile, including retrieving profile details and updating profile.
+- Reset password
+
+---
+
+## Prerequisites
+
+It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, JavaScript’s Fetch API, or cURL.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration).
+
+### Medusa React
+
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
+
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
+
+### Authenticated Admin User
+
+Aside from the User Login and Reset Password steps, other endpoints require you to be an authenticated admin user.
+
+You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+
+---
+
+## User Authentication
+
+### User Login
+
+You can log in a user by sending a request to the [User Login endpoint](/api/admin#tag/Auth/operation/PostAuth):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.auth.createSession({
+  email: "user@example.com",
+  password: "supersecret",
+})
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminLogin } from "medusa-react"
+
+const Login = () => {
+  const adminLogin = useAdminLogin()
+  // ...
+
+  const handleLogin = () => {
+    adminLogin.mutate({
+      email: "user@example.com",
+      password: "supersecret",
+    })
+  }
+
+  // ...
+}
+
+export default Login
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/auth`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    email: "user@example.com",
+    password: "supersecret",
+  }),
+})
+.then((response) => response.json())
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/auth' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "user@example.com",
+  "password": "supersecret"
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the following request body parameters:
+
+- `email`:  a string indicating the user’s email.
+- `password`: a string indicating the user’s password.
+
+The request returns the logged-in user as an object.
+
+### User Logout
+
+You can log out a user by sending a request to the [User Logout endpoint](/api/admin#tag/Auth/operation/DeleteAuth):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.auth.deleteSession()
+.then(() => {
+  // logged out successfully
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminDeleteSession } from "medusa-react"
+
+const Logout = () => {
+  const adminLogout = useAdminDeleteSession()
+  // ...
+
+  const handleLogout = () => {
+    adminLogout.mutate()
+  }
+
+  // ...
+}
+
+export default Logout
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/auth`, {
+  credentials: "include",
+  method: "DELETE",
+})
+.then((response) => response.json())
+.then(() => {
+  // logged out successfully
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X DELETE '<BACKEND_URL>/admin/auth' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+The endpoint does not require any path or query parameters.
+
+The request does not return any data. The response code will be `200` for successful log out.
+
+---
+
+## Retrieve User Profile Details
+
+You can retrieve the current user’s details for their profile by sending a request to the [Get Current User endpoint](/api/admin#tag/Auth/operation/GetAuth):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.auth.getSession()
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminGetSession } from "medusa-react"
+
+const Profile = () => {
+  const { user, isLoading } = useAdminGetSession()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {user && <span>{user.email}</span>}
+    </div>
+  )
+}
+
+export default Profile
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/auth`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X GET '<BACKEND_URL>/admin/auth' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint does not require any parameters.
+
+The request returns the current user as an object.
+
+---
+
+## Update User’s Profile Details
+
+You can update a user’s details in their profile by sending a request to the [Update User endpoint](/api/admin#tag/Users/operation/PostUsersUser):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.users.update(userId, {
+  first_name: "Marcellus",
+})
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import {
+  useAdminDeleteSession,
+  useAdminUpdateUser,
+} from "medusa-react"
+
+const Profile = () => {
+  const updateUser = useAdminUpdateUser(userId)
+  // ...
+
+  const handleUpdate = () => {
+    updateUser.mutate({
+      first_name: "Marcellus",
+    })
+  }
+
+  // ...
+}
+
+export default Profile
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/users/${userId}`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    first_name: "Marcellus",
+  }),
+})
+.then((response) => response.json())
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/users/<USER_ID>' \
+-H 'Authorization: Bearer <API_TOKEN>' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "first_name": "Marcellus"
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the ID of the user as a path parameter.
+
+In the request body, you can pass any of the user’s fields that you want to update as a parameter. In the example above, you pass the `first_name` parameter to update the user’s first name. You can refer to the [API reference](/api/admin#tag/Users/operation/PostUsersUser) to learn about other available parameters.
+
+The request returns the updated user as an object.
+
+---
+
+## Reset Password
+
+This section explains how you can reset the password of a user if they forgot their password.
+
+### Step 1: Request Password Reset
+
+The first step is to request a password reset. This would create in the Medusa backend a reset password token, which you typically would use in an email sent to the user. The email would include a link that allows the user to enter a new password, and the link would accept a token query parameter to be used in step 2.
+
+:::note
+
+Sending the password reset email is not handled by default in the Medusa backend. You can either use the SendGrid plugin which handles it, or manually subscribe to the `user.password_reset` event and send the email.
+
+:::
+
+You can request a password reset by sending a request to the [Request Password Reset endpoint](/api/admin#tag/Users/operation/PostUsersUserPasswordToken):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.users.sendResetPasswordToken({
+  email: "user@example.com",
+})
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminSendResetPasswordToken } from "medusa-react"
+
+const Login = () => {
+  const requestPasswordReset = useAdminSendResetPasswordToken()
+  // ...
+
+  const handleResetPassword = () => {
+    requestPasswordReset.mutate({
+      email: "user@example.com",
+    })
+  }
+
+  // ...
+}
+
+export default Login
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/users/password-token`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    email: "user@example.com",
+  }),
+})
+.then((response) => response.json())
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/users/password-token' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "user@example.com"
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the `email` parameter in the request body, which is the email of the user requesting to reset their password.
+
+The request does not return any data. The response code will be `204` if the request was processed successfully.
+
+### Step 2: Reset Password
+
+After the user resets their password and, typically, receives an email with a link to reset their password, they should enter their new password. The new password, along with the token passed to this page are used to reset the password on the Medusa backend.
+
+You can reset the password by sending a request to the [Reset Password endpoint](/api/admin#tag/Users/operation/PostUsersUserPassword):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.users.resetPassword({
+  token: "supersecrettoken",
+  password: "supersecret",
+})
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminResetPassword } from "medusa-react"
+
+const ResetPassword = () => {
+  const resetPassword = useAdminResetPassword()
+  // ...
+
+  const handleResetPassword = () => {
+    resetPassword.mutate({
+      token: "supersecrettoken",
+      password: "supersecret",
+    })
+  }
+
+  // ...
+}
+
+export default ResetPassword
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/users/reset-password`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    token: "supersecrettoken",
+    password: "supersecret",
+  }),
+})
+.then((response) => response.json())
+.then(({ user }) => {
+  console.log(user.id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/users/reset-password' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "token": "supersecrettoken",
+  "password": "supersecret"
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the following request body parameters:
+
+- `token`: a string indicating the password reset token.
+- `password`: a string indicating the new password for the user.
+
+You can also optionally pass the `email` parameter in the request body.
+
+The request returns the user as an object, and the user is automatically logged in.

docs/content/modules/users/backend/send-invite.md

@@ -1,5 +1,5 @@
 ---
-description: "Users are admins that can manage the ecommerce store’s data and operations. Learn about the available features and guides."
+description: "Learn how to send an invitation email to an invited user. This guide uses SendGrid as an example."
 addHowToData: true
 ---
 

docs/content/modules/users/overview.mdx

@@ -46,12 +46,11 @@ Admins can also manage their profile details.
   },
   {
     type: 'link',
-    href: '#',
+    href: '/modules/users/admin/manage-profile',
     label: 'Admin: Manage Profile',
     customProps: {
       icon: Icons['academic-cap-solid'],
       description: 'Learn how to manage a user profile using Admin APIs.',
-      isSoon: true
     }
   },
   {

docs/content/modules/users/users.md

@@ -72,3 +72,4 @@ If an invitation is expired, an existing user can resend the invite either using
 ## See Also
 
 - [How to send an invitation email](./backend/send-invite.md)
+- [How to manage a user's profile](./admin/manage-profile.mdx)

packages/medusa/src/api/routes/admin/auth/create-session.ts

@@ -32,7 +32,8 @@ import { validator } from "../../../../utils/validator"
  *       medusa.admin.auth.createSession({
  *         email: 'user@example.com',
  *         password: 'supersecret'
- *       }).then((({ user }) => {
+ *       })
+ *       .then(({ user }) => {
  *         console.log(user.id);
  *       });
  *   - lang: Shell

www/docs/sidebars.js

@@ -1175,7 +1175,7 @@ module.exports = {
         {
           type: "doc",
           id: "modules/users/users",
-          label: "Users",
+          label: "Users and Invites",
         },
         {
           type: "html",
@@ -1190,12 +1190,9 @@ module.exports = {
           label: "Backend: Send Invite",
         },
         {
-          type: "link",
-          href: "#",
+          type: "doc",
+          id: "modules/users/admin/manage-profile",
           label: "Admin: Manage Profile",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
         {
           type: "link",