asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: edits and fixes to commerce module docs (#7468)

Browse Source 
Apply edits and fixes to the commerce modules docs
This commit is contained in:
Shahed Nasser
2024-05-29 11:08:06 +00:00
committed by GitHub
parent 130de74d6d
commit 2c5ba408d4
160 changed files with 6400 additions and 3790 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
+7 -19
View File
@@ -12,7 +12,7 @@ In this document, you'll learn about how the Auth Provider is used in an authent
## How to Authenticate a User
To authenticate a user, you use the `authenticate` method of the Auth Module's main service (`IAuthModuleService`). For example:
To authenticate a user, you use the [authenticate method of the Auth Module's main service](/references/auth/authenticate) (`IAuthModuleService`). For example:
```ts
const data = await authModuleService.authenticate(
@@ -24,13 +24,7 @@ const data = await authModuleService.authenticate(
)
```
This method calls the `authenticate` method of the specified provider and returns its data.
<Note>
Learn about the parameters and return type of the `IAuthModuleService`'s `authenticate` method in [this reference](/references/auth/authenticate).
</Note>
This method calls the `authenticate` method of the provider specified in the first parameter and returns its data.
---
@@ -51,7 +45,7 @@ Then, the user is authenticated successfully, and their authentication details a
<Note>
Learn more about the `authIdentity` in [this guide](../persisting-auth-user/page.mdx#what-is-an-authuser).
Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for the expected fields in `authIdentity`.
</Note>
@@ -65,8 +59,8 @@ If the `authenticate` method returns the following object:
```ts
data = {
success: true,
location: "https://....",
success: true,
location: "https://....",
}
```
@@ -78,7 +72,7 @@ It means the authentication process requires the user to perform an action with
Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.
So, once the user performs the required action, the third-party service must redirect to an API route that uses the `validateCallback` method of the `IAuthModuleService`. The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
So, once the user performs the required action, the third-party service must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](/references/auth/validateCallback). The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
```ts
const data = await authModuleService.validateCallback(
@@ -90,13 +84,7 @@ const data = await authModuleService.validateCallback(
)
```
<Note>
Learn more about the parameters and return type of the `IAuthModuleService`'s `validateCallback` method in [this reference](/references/auth/validateCallback).
</Note>
If the authentication is successful, the auth provider’s `validateCallback` method returns the same data as the basic authentication:
If the authentication is successful, the `validateCallback` method returns the same data as the basic authentication:
```ts
data = {
www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx
+27 -18
View File
@@ -6,34 +6,43 @@ export const metadata = {
In this document, you’ll learn how the Auth Module handles authentication using providers.
## What's an Auth Provider?
## What's an Auth Provider Module?
An auth provider is a TypeScript or JavaScript class used to authenticate customers and users. Each provider implements the authentication logic based on its purpose.
An auth provider module handles authenticating customers and users, either using custom logic or by integrating a third-party service.
For example, the `emailpass` provider authenticates a user using their email and password, whereas the `google` provider authenticates users using their Google account.
For example, the EmailPass Auth Provider Module authenticates a user using their email and password, whereas the Google Auth Provider Module authenticates users using their Google account.
<Note type="check">
Support for the Google Auth Provider Module is coming soon.
</Note>
---
## The Auth Provider Class
## Configure Auth Provider Modules
An auth provider implements the `AbstractAuthModuleProvider` class imported from the `@medusajs/utils` package. The provider must implement the `authenticate` method that authenticates a user.
By default, admin users and customers can login with all installed auth provider moduless.
When you call the `authenticate` method of the Auth Module's main service (`IAuthModuleService`), the method resolves the specified provider and calls its `authenticate` method passing it the second parameter it received:
To limit the auth providers that used for admin users and customers, use the [authMethodsPerActor option](/references/medusa-config#http-authMethodsPerActor-1-3) in Medusa's configurations:
```ts
const data = await authModuleService.authenticate(
"emailpass",
// passed to auth provider
{
```js title="medusa-config.js"
module.exports = {
projectConfig: {
http: {
authMethodsPerActor: {
user: ["google"],
customer: ["emailpass"]
},
// ...
}
)
},
// ...
}
}
```
It also returns the same data returned by the auth provider.
---
<Note>
## How to Create an Auth Provider Module
Learn about the parameters and return type of the `IAuthModuleService`'s `authenticate` method in [this reference](/references/auth/authenticate).
</Note>
Refer to [this guide](/references/auth/provider) to learn how to create an auth provider module.
www/apps/resources/app/commerce-modules/auth/events/page.mdx
+6
View File
@@ -8,4 +8,10 @@ export const metadata = {
Find in this reference the list of events emitted by the Auth Module.
<Note type="soon">
Events are still in development, so this reference will change in the future.
</Note>
<EventsTable />
www/apps/resources/app/commerce-modules/auth/examples/page.mdx
+5 -5
View File
@@ -218,7 +218,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
---
## Create Auth User
## Create Auth Identity
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
@@ -275,7 +275,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
---
## List Auth Users
## List Auth Identities
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
@@ -322,7 +322,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
---
## Update an Auth User
## Update an Auth Identity
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
@@ -392,7 +392,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
---
## Delete an Auth User
## Delete an Auth Identity
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
@@ -448,4 +448,4 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
## More Examples
The [module interface reference](/references/auth) provides a reference to all the methods available for use with examples for each.
The [Auth Module's main service reference](/references/auth) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/auth/page.mdx
+27 -21
View File
@@ -8,13 +8,11 @@ export const metadata = {
The Auth Module is the `@medusajs/auth` NPM package that provides authentication-related features in your Medusa and Node.js applications.
---
## Features
### Authenticate Users
### Basic User Authentication
With the Auth Module, authenticate users using their credentials.
With the Auth Module, authenticate users using their email and password credentials.
```ts
const { success, authIdentity, error } =
@@ -71,25 +69,22 @@ const { success, authIdentity } =
## Configure Auth Module
After installing the `@medusajs/auth` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
To use the Auth Module, enable it in the `modules` object in `medusa-config.js`:
```js title="medusa-config.js"
const { Modules } = require("@medusajs/modules-sdk")
// ...
const modules = {
// ...
auth: {
resolve: "@medusajs/auth",
options: {
providers: [
// ...
],
},
},
[Modules.AUTH]: true,
}
```
### Module Options
{/* ### Module Options
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
Refer to [this documentation](./module-options/page.mdx) for details on the module's options. */}
---
@@ -103,9 +98,14 @@ For example:
<CodeTab label="API Route" value="api-route">
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import {
MedusaRequest,
MedusaResponse
} from "@medusajs/medusa"
import { IAuthModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
import {
ModuleRegistrationName
} from "@medusajs/modules-sdk"
export async function GET(
req: MedusaRequest,
@@ -126,7 +126,9 @@ For example:
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/medusa"
import { IAuthModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
import {
ModuleRegistrationName
} from "@medusajs/modules-sdk"
export default async function subscriberHandler({
container,
@@ -144,11 +146,15 @@ For example:
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/workflows-sdk"
import { IAuthModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
import {
ModuleRegistrationName
} from "@medusajs/modules-sdk"
const step1 = createStep("step-1", async (_, context) => {
const step1 = createStep(
"step-1",
async (_, { container }) => {
const authModuleService: IAuthModuleService =
context.container.resolve(
container.resolve(
ModuleRegistrationName.AUTH
)
const authIdentitys = await authModuleService.list()
www/apps/resources/app/commerce-modules/auth/persisting-auth-user/page.mdx
-58
View File
@@ -1,58 +0,0 @@
---
sidebar_label: "Persisting Auth User"
---
export const metadata = {
title: `Persisting Auth User Authentication`,
}
# {metadata.title}
In this document, you’ll learn what the `AuthIdentity` is and how to persist its authentication.
## What is an AuthIdentity?
As explained in the [Auth Provider](../auth-providers/page.mdx) guide, when a user or customer is authenticated, you receive an `authIdentity` object:
```ts
const { success, authIdentity } =
await authModuleService.authenticate("emailpass", {
// ...
})
```
The `authIdentity` object is a record of the `AuthIdentity` data model. It has details about the authenticated user or customer, such as their ID, email, and other details.
<Note>
Learn more about the `AuthIdentity`'s fields in [this reference](/references/auth/models/AuthIdentity).
</Note>
---
## Persisting Authentication
While the Auth Module provides the authentication functionality, it doesn’t provide the functionality to persist the authentication, as that depends on your application’s requirements.
For example, the Medusa application’s authentication route signs the `authIdentity` object into a JSON Web Token (JWT):
```ts
const {
success,
authIdentity,
} = await service.authenticate(auth_provider, authData)
// ...
const {
jwtSecret,
} = req.scope.resolve("configModule").projectConfig.http
const token = jwt.sign(authIdentity, jwtSecret)
```
Then, the token is passed in the header of subsequent requests in the Authorization Bearer header.
An authentication middleware verifies the token and attaches the associated `authIdentity`'s details to the `auth` property of the request object passed to the subsequent middlewares and route.
If the authentication middleware can’t verify the token, the user isn’t authenticated and they’re asked to login again.
www/apps/resources/app/commerce-modules/auth/user-creation/page.mdx
+3 -21
View File
@@ -3,32 +3,14 @@ sidebar_label: "User Creation"
---
export const metadata = {
title: `User Creation with Auth Module`,
title: `User Creation`,
}
# {metadata.title}
In this document, you’ll learn about the user-creation flow and how to use it with the User Module.
In this document, you’ll learn about creating a user with the User Module after authentication.
## Auth User Creation in Authentication Flow
In the [Auth Provider](../auth-providers/page.mdx) documentation, you learned about the authentication flows supported by the Auth Module. These flows are used when an `AuthIdentity` is already available for the specified authentication data, such as email/password credentials.
However, the `emailpass` and `google` providers support creating an `AuthIdentity` if none exists. If an email is provided that doesn’t have an `AuthIdentity` associated with it (checked via its `entity_id` field) for the specified provider (checked via its `provider` field), a new `AuthIdentity` is created for that email and provider.
![Diagram showcasing the AuthIdentity creation part of the authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711441638/Medusa%20Resources/auth-user-creation_gmahvl.jpg)
So, by default, your authentication flow supports both sign-in and sign-up flows.
<Note title="Tip">
This step actually occurs at different points of the authentication flow for each of the providers. For the `emailpass` provider, it occurs before checking that the password is correct. For the `google` provider, you must go through the full authentication flow to retrieve the user details, such as email, from Google.
</Note>
---
## Creating a User in the User Module
## Creating a User using the User Module
The User Module provides user and invite management functionalities. However, it doesn’t provide authentication functionalities or store any related data.