docs: added manage invites documentation (#4001)

* docs: added manage invites documentation

* eslint fixes

* fixed indentation

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

@@ -0,0 +1,455 @@
+---
+description: 'Learn how to manage invites using the admin API. This includes listing, creating, accepting, resending, and deleting invites.'
+addHowToData: true
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Manage Invites
+
+In this document, you’ll learn how to manage invites using the admin API.
+
+## Overview
+
+You can use the invites admin API to manage and perform functionalities related to invites.
+
+### Scenario
+
+You want to add or use the following admin functionalities:
+
+- List invites
+- Create an invite
+- Accept an invite
+- Resend an invite
+- Delete an invite
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+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, among other methods.
+
+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
+
+Except for the Accept Invite endpoint, you must be an authenticated admin user before following along with the steps in the tutorial.
+
+You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+
+---
+
+## List Invites
+
+You can list invites by sending a request to the [List Invite endpoint](/api/admin#tag/Invites/operation/GetInvites):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.invites.list()
+.then(({ invites }) => {
+  console.log(invites.length)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminInvites } from "medusa-react"
+
+const Invites = () => {
+  const { invites, isLoading } = useAdminInvites()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {invites && !invites.length && <span>No Invites</span>}
+      {invites && invites.length > 0 && (
+        <ul>
+          {invites.map((invite) => (
+            <li key={invite.id}>{invite.user_email}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+export default Invites
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/invites`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ invites }) => {
+  console.log(invites.length)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X GET '<BACKEND_URL>/admin/invites' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint does not accept any parameters.
+
+The request returns an array of invite endpoints.
+
+---
+
+## Create Invite
+
+You can create an invite by sending a request to the [Create Invite endpoint](/api/admin#tag/Invites/operation/PostInvites):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.invites.create({
+  user: "user@example.com",
+  role: "admin",
+})
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminCreateInvite } from "medusa-react"
+
+const CreateInvite = () => {
+  const createInvite = useAdminCreateInvite()
+  // ...
+
+  const handleCreate = () => {
+    createInvite.mutate({
+      user: "user@example.com",
+      role: "admin",
+    })
+  }
+
+  // ...
+}
+
+export default CreateInvite
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/invites`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    user: "user@example.com",
+    role: "admin",
+  }),
+})
+.then((response) => response.json())
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/invites' \
+-H 'Authorization: Bearer <API_TOKEN>' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+    "user": "user@example.com",
+    "role": "admin"
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the following body parameters:
+
+- `user`: a string indicating the email of the user.
+- `role`: a string indicating the role of the user. Its values can be `admin`, `member`, and `developer`.
+
+The request does not return any data. If the invite was created successfully, the status code of the response will be `200`.
+
+---
+
+## Accept an Invite
+
+A logged-out user can accept an invite, which would create a user for that user.
+
+You can accept an invite by sending a request to the [Accept Invite endpoint](/api/admin#tag/Invites/operation/PostInvitesInviteAccept):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.invites.accept({
+  token,
+  user: {
+    first_name: "Brigitte",
+    last_name: "Collier",
+    password: "supersecret",
+  },
+})
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminAcceptInvite } from "medusa-react"
+
+const AcceptInvite = () => {
+  const acceptInvite = useAdminAcceptInvite()
+  // ...
+
+  const handleAccept = () => {
+    acceptInvite.mutate({
+      token,
+      user: {
+        first_name: "Brigitte",
+        last_name: "Collier",
+        password: "supersecret",
+      },
+    })
+  }
+
+  // ...
+}
+
+export default AcceptInvite
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/invites/accept`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    token,
+    user: {
+      first_name: "Brigitte",
+      last_name: "Collier",
+      password: "supersecret",
+    },
+  }),
+})
+.then((response) => response.json())
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/invites/accept' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+    "token": "<TOKEN>",
+    "user": {
+      "first_name": "Brigitte",
+      "last_name": "Collier",
+      "password": "supersecret"
+    }
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the following request body parameters:
+
+- `token`: a string indicating the invitation’s token.
+- `user`: an object that has the following properties:
+    - `first_name`: a string indicating the first name of the user.
+    - `last_name`: a string indicating the last name of the user.
+    - `password`: a string indicating the user’s password.
+
+The request does not return any data. If the invite was accepted successfully, the status code of the response will be `200`.
+
+---
+
+## Resend an Invite
+
+You can resend an invite if it’s not accepted yet. To resend an invite, send a request to the [Resend Invite endpoint](/api/admin#tag/Invites/operation/PostInvitesInviteResend):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.invites.resend(inviteId)
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminResendInvite } from "medusa-react"
+
+const ResendInvite = () => {
+  const resendInvite = useAdminResendInvite(inviteId)
+  // ...
+
+  const handleResend = () => {
+    resendInvite.mutate()
+  }
+
+  // ...
+}
+
+export default ResendInvite
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/invites/${inviteId}/resend`, {
+  credentials: "include",
+  method: "POST",
+})
+.then((response) => response.json())
+.then(() => {
+  // successful
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/invites/<INVITE_ID>/resend' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the invite ID as a path parameter.
+
+The request does not return any data. If the invite was resent successfully, the status code of the response will be `200`.
+
+---
+
+## Delete an Invite
+
+You can delete an invite by sending a request to the [Delete Invite endpoint](/api/admin#tag/Invites/operation/DeleteInvitesInvite):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.invites.delete(inviteId)
+.then(({ id, object, deleted }) => {
+  console.log(id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminDeleteInvite } from "medusa-react"
+
+const DeleteInvite = () => {
+  const deleteInvite = useAdminDeleteInvite(inviteId)
+  // ...
+
+  const handleDelete = () => {
+    deleteInvite.mutate()
+  }
+
+  // ...
+}
+
+export default DeleteInvite
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/invites/${inviteId}`, {
+  credentials: "include",
+  method: "DELETE",
+})
+.then((response) => response.json())
+.then(({ id, object, deleted }) => {
+  console.log(id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X DELETE '<BACKEND_URL>/admin/invites/<INVITE_ID>' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the invite ID as a path parameter.
+
+It deletes the invite and returns the following fields:
+
+- `id`: The ID of the deleted invite.
+- `object`: The type of object that was deleted. In this case, the value will be `invite`.
+- `deleted`: A boolean value indicating whether the invite was deleted.
+
+---
+
+## See Also
+
+- [How to implement user profiles](./manage-profile.mdx)
+- [How to manage users](./manage-users.mdx)

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

@@ -6,7 +6,7 @@ addHowToData: true
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# How to Manage a User’s Profile
+# How to Implement User Profiles
 
 In this document, you’ll learn how to implement user profile management features using the admin APIs.
 

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

@@ -352,7 +352,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/users/<USER_ID>' \
 
 This endpoint requires the user ID as a path parameter.
 
-This request requires the user ID as a path parameter. It deletes the user and returns the following fields:
+It deletes the user and returns the following fields:
 
 - `id`: The ID of the deleted user.
 - `object`: The type of object that was deleted. In this case, the value will be `user`.

docs/content/modules/users/overview.mdx

@@ -46,10 +46,10 @@ Admins can also manage their profile details.
   {
     type: 'link',
     href: '/modules/users/admin/manage-profile',
-    label: 'Admin: Manage Profile',
+    label: 'Admin: Implement Profiles',
     customProps: {
       icon: Icons['academic-cap-solid'],
-      description: 'Learn how to manage a user profile using Admin APIs.',
+      description: 'Learn how to implement user profiles using Admin APIs.',
     }
   },
   {
@@ -74,12 +74,11 @@ Admins can invite users to join their team. Invites can be resent, accepted, or
 <DocCardList colSize={4} items={[
   {
     type: 'link',
-    href: '#',
+    href: '/modules/users/admin/manage-invites',
     label: 'Admin: Manage Invites',
     customProps: {
       icon: Icons['academic-cap-solid'],
       description: 'Learn how to manage invites using Admin APIs.',
-      isSoon: true
     }
   },
   {

docs/content/modules/users/users.md

@@ -72,4 +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)
+- [How to implement user profiles](./admin/manage-profile.mdx)

www/docs/sidebars.js

@@ -1192,7 +1192,7 @@ module.exports = {
         {
           type: "doc",
           id: "modules/users/admin/manage-profile",
-          label: "Admin: Manage Profile",
+          label: "Admin: Implement Profiles",
         },
         {
           type: "doc",
@@ -1200,12 +1200,9 @@ module.exports = {
           label: "Admin: Manage Users",
         },
         {
-          type: "link",
-          href: "#",
+          type: "doc",
+          id: "modules/users/admin/manage-invites",
           label: "Admin: Manage Invites",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
       ],
     },