diff --git a/docs/content/modules/users/admin/manage-invites.mdx b/docs/content/modules/users/admin/manage-invites.mdx new file mode 100644 index 0000000000..7512e63156 --- /dev/null +++ b/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): + + + + +```ts +medusa.admin.invites.list() +.then(({ invites }) => { + console.log(invites.length) +}) +``` + + + + +```tsx +import { useAdminInvites } from "medusa-react" + +const Invites = () => { + const { invites, isLoading } = useAdminInvites() + + return ( +
+ {isLoading && Loading...} + {invites && !invites.length && No Invites} + {invites && invites.length > 0 && ( +
    + {invites.map((invite) => ( +
  • {invite.user_email}
    • + ))} +
+ )} +
+ ) +} + +export default Invites +``` + + + + +```ts +fetch(`/admin/invites`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ invites }) => { + console.log(invites.length) +}) +``` + + + + +```bash +curl -L -X GET '/admin/invites' \ +-H 'Authorization: Bearer ' +``` + + + + +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): + + + + +```ts +medusa.admin.invites.create({ + user: "user@example.com", + role: "admin", +}) +.then(() => { + // successful +}) +``` + + + + +```tsx +import { useAdminCreateInvite } from "medusa-react" + +const CreateInvite = () => { + const createInvite = useAdminCreateInvite() + // ... + + const handleCreate = () => { + createInvite.mutate({ + user: "user@example.com", + role: "admin", + }) + } + + // ... +} + +export default CreateInvite +``` + + + + +```ts +fetch(`/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 +}) +``` + + + + +```bash +curl -L -X POST '/admin/invites' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "user": "user@example.com", + "role": "admin" +}' +``` + + + + +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): + + + + +```ts +medusa.admin.invites.accept({ + token, + user: { + first_name: "Brigitte", + last_name: "Collier", + password: "supersecret", + }, +}) +.then(() => { + // successful +}) +``` + + + + +```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 +``` + + + + +```ts +fetch(`/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 +}) +``` + + + + +```bash +curl -L -X POST '/admin/invites/accept' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "token": "", + "user": { + "first_name": "Brigitte", + "last_name": "Collier", + "password": "supersecret" + } +}' +``` + + + + +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): + + + + +```ts +medusa.admin.invites.resend(inviteId) +.then(() => { + // successful +}) +``` + + + + +```tsx +import { useAdminResendInvite } from "medusa-react" + +const ResendInvite = () => { + const resendInvite = useAdminResendInvite(inviteId) + // ... + + const handleResend = () => { + resendInvite.mutate() + } + + // ... +} + +export default ResendInvite +``` + + + + +```ts +fetch(`/admin/invites/${inviteId}/resend`, { + credentials: "include", + method: "POST", +}) +.then((response) => response.json()) +.then(() => { + // successful +}) +``` + + + + +```bash +curl -L -X POST '/admin/invites//resend' \ +-H 'Authorization: Bearer ' +``` + + + + +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): + + + + +```ts +medusa.admin.invites.delete(inviteId) +.then(({ id, object, deleted }) => { + console.log(id) +}) +``` + + + + +```tsx +import { useAdminDeleteInvite } from "medusa-react" + +const DeleteInvite = () => { + const deleteInvite = useAdminDeleteInvite(inviteId) + // ... + + const handleDelete = () => { + deleteInvite.mutate() + } + + // ... +} + +export default DeleteInvite +``` + + + + +```ts +fetch(`/admin/invites/${inviteId}`, { + credentials: "include", + method: "DELETE", +}) +.then((response) => response.json()) +.then(({ id, object, deleted }) => { + console.log(id) +}) +``` + + + + +```bash +curl -L -X DELETE '/admin/invites/' \ +-H 'Authorization: Bearer ' +``` + + + + +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) diff --git a/docs/content/modules/users/admin/manage-profile.mdx b/docs/content/modules/users/admin/manage-profile.mdx index d8ba2b5205..e62db03234 100644 --- a/docs/content/modules/users/admin/manage-profile.mdx +++ b/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. diff --git a/docs/content/modules/users/admin/manage-users.mdx b/docs/content/modules/users/admin/manage-users.mdx index 28e28a5492..ec6eba7e53 100644 --- a/docs/content/modules/users/admin/manage-users.mdx +++ b/docs/content/modules/users/admin/manage-users.mdx @@ -352,7 +352,7 @@ curl -L -X DELETE '/admin/users/' \ 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`. diff --git a/docs/content/modules/users/overview.mdx b/docs/content/modules/users/overview.mdx index 0156741501..0348d28daa 100644 --- a/docs/content/modules/users/overview.mdx +++ b/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