docs: revise commerce modules overview pages (#10738)
* revise API Key Module overview * revise auth module * support ref sidebar items * remove examples * revise cart module * revise currency * revise customer module * revise fulfillment module * revise inventory module * revise order module * revise payment * revise pricing module * revise product module * revise promotion module * revise region module * revise sales channel module * revise stock location module * revise store module * revise tax module * revise user module * lint content + fix snippets
This commit is contained in:
Shahed Nasser
@@ -1,4 +1,4 @@
|
||||
import { CodeTabs, CodeTab } from "docs-ui"
|
||||
import { CodeTabs, CodeTab, ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Auth Module`,
|
||||
@@ -6,132 +6,141 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Auth Module provides authentication-related features in your Medusa and Node.js applications.
|
||||
In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.
|
||||
|
||||
## How to Use Auth Module's Service
|
||||
Medusa has auth related features available out-of-the-box through the Auth Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Auth Module.
|
||||
|
||||
Use the Auth Module's main service by resolving from the Medusa container the resource `Modules.AUTH`.
|
||||
<Note>
|
||||
|
||||
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
|
||||
|
||||
</Note>
|
||||
|
||||
## Auth Features
|
||||
|
||||
- [Basic User Authentication](./authentication-route/page.mdx#1-basic-authentication-flow): Authenticate users using their email and password credentials.
|
||||
- [Third-Party and Social Authentication](./authentication-route/page.mdx#2-third-party-service-authenticate-flow): Authenticate users using third-party services and social platforms, such as [Google](./auth-providers/google/page.mdx) and [GitHub](./auth-providers/github/page.mdx).
|
||||
- [Authenticate Custom Actor Types](./create-actor-type/page.mdx): Create custom user or actor types, such as managers, authenticate them in your application, and guard routes based on the custom user types.
|
||||
- [Custom Authentication Providers](/references/auth/provider): Integrate third-party services with custom authentication providors.
|
||||
|
||||
---
|
||||
|
||||
## How to Use the Auth Module
|
||||
|
||||
In your Medusa application, you build flows around commerce modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
|
||||
|
||||
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
|
||||
|
||||
For example:
|
||||
|
||||
<CodeTabs groupId="resource-type">
|
||||
<CodeTab label="Workflow Step" value="workflow-step">
|
||||
export const highlights = [
|
||||
["18", "Modules.AUTH", "Resolve the module in a step."]
|
||||
]
|
||||
|
||||
```ts title="src/workflows/hello-world/step1.ts"
|
||||
import { createStep } from "@medusajs/framework/workflows-sdk"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
```ts title="src/workflows/authenticate-user.ts" highlights={highlights}
|
||||
import {
|
||||
createWorkflow,
|
||||
WorkflowResponse,
|
||||
createStep,
|
||||
StepResponse,
|
||||
} from "@medusajs/framework/workflows-sdk"
|
||||
import { Modules, MedusaError } from "@medusajs/framework/utils"
|
||||
import { MedusaRequest } from "@medusajs/framework/http"
|
||||
import { AuthenticationInput } from "@medusajs/framework/types"
|
||||
|
||||
const step1 = createStep("step-1", async (_, { container }) => {
|
||||
const authModuleService = container.resolve(
|
||||
Modules.AUTH
|
||||
)
|
||||
const authIdentitys = await authModuleService.listAuthIdentities()
|
||||
})
|
||||
type Input = {
|
||||
req: MedusaRequest
|
||||
}
|
||||
|
||||
const authenticateUserStep = createStep(
|
||||
"authenticate-user",
|
||||
async ({ req }: Input, { container }) => {
|
||||
const authModuleService = container.resolve(Modules.AUTH)
|
||||
|
||||
const { success, authIdentity, error } = await authModuleService
|
||||
.authenticate(
|
||||
"emailpass",
|
||||
{
|
||||
url: req.url,
|
||||
headers: req.headers,
|
||||
query: req.query,
|
||||
body: req.body,
|
||||
authScope: "admin", // or custom actor type
|
||||
protocol: req.protocol,
|
||||
} as AuthenticationInput
|
||||
)
|
||||
|
||||
if (!success) {
|
||||
// incorrect authentication details
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.UNAUTHORIZED,
|
||||
error || "Incorrect authentication details"
|
||||
)
|
||||
}
|
||||
|
||||
return new StepResponse({ authIdentity }, authIdentity?.id)
|
||||
},
|
||||
async (authIdentityId, { container }) => {
|
||||
if (!authIdentityId) {
|
||||
return
|
||||
}
|
||||
|
||||
const authModuleService = container.resolve(Modules.AUTH)
|
||||
|
||||
await authModuleService.deleteAuthIdentities([authIdentityId])
|
||||
}
|
||||
)
|
||||
|
||||
export const authenticateUserWorkflow = createWorkflow(
|
||||
"authenticate-user",
|
||||
(input: Input) => {
|
||||
const { authIdentity } = authenticateUserStep(input)
|
||||
|
||||
return new WorkflowResponse({
|
||||
authIdentity,
|
||||
})
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="API Route" value="api-route">
|
||||
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
|
||||
|
||||
```ts title="src/api/store/custom/route.ts"
|
||||
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
```ts title="API Route" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
|
||||
import type {
|
||||
MedusaRequest,
|
||||
MedusaResponse,
|
||||
} from "@medusajs/framework/http"
|
||||
import { authenticateUserWorkflow } from "../../workflows/authenticate-user"
|
||||
|
||||
export async function GET(
|
||||
req: MedusaRequest,
|
||||
res: MedusaResponse
|
||||
): Promise<void> {
|
||||
const authModuleService = req.scope.resolve(
|
||||
Modules.AUTH
|
||||
)
|
||||
) {
|
||||
const { result } = await authenticateUserWorkflow(req.scope)
|
||||
.run({
|
||||
req,
|
||||
})
|
||||
|
||||
res.json({
|
||||
authIdentitys: await authModuleService.listAuthIdentities(),
|
||||
})
|
||||
res.send(result)
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="Subscriber" value="subscribers">
|
||||
|
||||
```ts title="src/subscribers/custom-handler.ts"
|
||||
import { SubscriberArgs } from "@medusajs/framework"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
|
||||
export default async function subscriberHandler({ container }: SubscriberArgs) {
|
||||
const authModuleService = container.resolve(
|
||||
Modules.AUTH
|
||||
)
|
||||
|
||||
const authIdentitys = await authModuleService.listAuthIdentities()
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
</CodeTabs>
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Basic User Authentication
|
||||
|
||||
Authenticate users using their email and password credentials.
|
||||
|
||||
```ts
|
||||
const { success, authIdentity, error } = await authModuleService.authenticate(
|
||||
"emailpass",
|
||||
{
|
||||
url: req.url,
|
||||
headers: req.headers,
|
||||
query: req.query,
|
||||
body: req.body,
|
||||
authScope: "admin",
|
||||
protocol: req.protocol,
|
||||
} as AuthenticationInput
|
||||
)
|
||||
|
||||
if (!success) {
|
||||
// incorrect authentication details
|
||||
throw new Error(error)
|
||||
}
|
||||
```
|
||||
|
||||
### Third-Party and Social Authentication
|
||||
|
||||
The Auth Module supports a variety of authentication methods, such as authenticating with third-party services and social platforms.
|
||||
|
||||
```ts
|
||||
// in authentication API route
|
||||
const { success, authIdentity, location } =
|
||||
await authModuleService.authenticate("google", {
|
||||
url: req.url,
|
||||
headers: req.headers,
|
||||
query: req.query,
|
||||
body: req.body,
|
||||
authScope: "admin",
|
||||
protocol: req.protocol,
|
||||
} as AuthenticationInput)
|
||||
|
||||
if (location) {
|
||||
return res.json({ location })
|
||||
}
|
||||
|
||||
// in callback API route
|
||||
const { success, authIdentity } = await authModuleService.validateCallback(
|
||||
"google",
|
||||
{
|
||||
url: req.url,
|
||||
headers: req.headers,
|
||||
query: req.query,
|
||||
body: req.body,
|
||||
authScope: "admin",
|
||||
protocol: req.protocol,
|
||||
} as AuthenticationInput
|
||||
)
|
||||
```
|
||||
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
|
||||
|
||||
---
|
||||
|
||||
## Configure Auth Module
|
||||
|
||||
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
|
||||
The Auth Module accepts options for further configurations. Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
|
||||
|
||||
---
|
||||
|
||||
## Providers
|
||||
|
||||
Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.
|
||||
|
||||
<ChildDocs showItems={["Providers"]} hideTitle />
|
||||
|
||||
---
|
||||
|
||||
<CommerceModuleSections name="Auth" />
|
||||
Reference in New Issue
Block a user