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

docs: revise commerce modules overview pages (#10738)

Browse Source 
* 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
2024-12-26 10:32:16 +02:00
committed by GitHub
parent c8f9938865
commit ebca8fed28
112 changed files with 9465 additions and 7731 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/auth/examples/page.mdx
-444
View File
@@ -1,444 +0,0 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Examples of the Auth Module`,
}
# {metadata.title}
In this guide, you’ll find common examples of how you can use the Auth Module in your application.
<Note>
You should only use the Auth Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## Authenticate User
<Note>
This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/jsonwebtoken) to create the authentication token.
</Note>
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts collapsibleLines="1-10" expandButtonLabel="Show Imports"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import {
IAuthModuleService,
AuthenticationInput,
} from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
import { MedusaError } from "@medusajs/framework/utils"
import jwt from "jsonwebtoken"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const authModuleService = req.scope.resolve(
Modules.AUTH
)
const { success, authIdentity, location, 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) {
throw new MedusaError(MedusaError.Types.UNAUTHORIZED, error)
}
if (location) {
res.json({ location })
return
}
const { jwtSecret } = req.scope.resolve("configModule").projectConfig.http
const token = jwt.sign(authIdentity, jwtSecret)
res.status(200).json({ token })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeAuthModule } from "@medusajs/medusa/auth"
export async function POST(request: Request) {
const authModuleService = await initializeAuthModule()
const url = new URL(request.url)
const { success, authIdentity, location, error } =
await authModuleService.authenticate("emailpass", {
url: request.url,
headers: Object.fromEntries(request.headers),
query: Object.fromEntries(url.searchParams),
body: await request.json(),
authScope: "admin",
protocol: url.protocol,
} as AuthenticationInput)
if (!success) {
throw new Error(error)
}
if (location) {
return NextResponse.json({ location })
}
const token = jwt.sign(authIdentity, "supersecret")
return NextResponse.json(
{
token,
},
{
status: 200,
}
)
}
```
</CodeTab>
</CodeTabs>
---
## Validate Callback
<Note>
This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/jsonwebtoken) to create the authentication token.
</Note>
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts collapsibleLines="1-10" expandButtonLabel="Show Imports"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import {
IAuthModuleService,
AuthenticationInput,
} from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
import { MedusaError } from "@medusajs/framework/utils"
import jwt from "jsonwebtoken"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const authModuleService = req.scope.resolve(
Modules.AUTH
)
const { success, authIdentity, error, successRedirectUrl } =
await authModuleService.validateCallback("google", {
url: req.url,
headers: req.headers,
query: req.query,
body: req.body,
authScope: "admin",
protocol: req.protocol,
} as AuthenticationInput)
if (!success) {
throw new MedusaError(MedusaError.Types.UNAUTHORIZED, error)
}
const { jwtSecret } = req.scope.resolve("configModule").projectConfig.http
const token = jwt.sign(authIdentity, jwtSecret)
if (successRedirectUrl) {
const url = new URL(successRedirectUrl!)
url.searchParams.append("auth_token", token)
return res.redirect(url.toString())
}
res.status(200).json({ token })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts collapsibleLines="1-7" expandButtonLabel="Show Imports"
import { NextResponse } from "next/server"
import { initialize as initializeAuthModule } from "@medusajs/medusa/auth"
export async function POST(request: Request) {
const authModuleService = await initializeAuthModule()
const url = new URL(request.url)
const { success, authIdentity, location, error } =
await authModuleService.authenticate("google", {
url: request.url,
headers: Object.fromEntries(request.headers),
query: Object.fromEntries(url.searchParams),
body: await request.json(),
authScope: "admin",
protocol: url.protocol,
} as AuthenticationInput)
if (!success) {
throw new Error(error)
}
const token = jwt.sign(authIdentity, "supersecret")
if (successRedirectUrl) {
const url = new URL(successRedirectUrl!)
url.searchParams.append("auth_token", token)
return NextResponse.redirect(url.toString())
}
return NextResponse.json(
{
token,
},
{
status: 200,
}
)
}
```
</CodeTab>
</CodeTabs>
---
## Create Auth Identity
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const authModuleService = req.scope.resolve(
Modules.AUTH
)
const authIdentity = await authModuleService.createAuthIdentities({
provider: "emailpass",
entity_id: "user@example.com",
scope: "admin",
})
res.json({ auth_identity: authIdentity })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeAuthModule } from "@medusajs/medusa/auth"
export async function POST(request: Request) {
const authModuleService = await initializeAuthModule()
const authIdentity = await authModuleService.createAuthIdentities({
provider: "emailpass",
entity_id: "user@example.com",
scope: "admin",
})
return NextResponse.json({
auth_identity: authIdentity,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Auth Identities
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const authModuleService = req.scope.resolve(
Modules.AUTH
)
res.json({
auth_identitys: await authModuleService.listAuthIdentities(),
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeAuthModule } from "@medusajs/medusa/auth"
export async function GET(request: Request) {
const authModuleService = await initializeAuthModule()
return NextResponse.json({
auth_identities: await authModuleService.listAuthIdentities(),
})
}
```
</CodeTab>
</CodeTabs>
---
## Update an Auth Identity
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const authModuleService = req.scope.resolve(
Modules.AUTH
)
const authIdentity = await authModuleService.updateAuthIdentites({
id: "authusr_123",
provider_metadata: {
test: true,
},
})
res.json({
auth_identity: authIdentity,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeAuthModule } from "@medusajs/medusa/auth"
type ContextType = {
params: {
id: string
}
}
export async function POST(request: Request, { params }: ContextType) {
const authModuleService = await initializeAuthModule()
const authIdentity = await authModuleService.updateAuthIdentites({
id: "authusr_123",
provider_metadata: {
test: true,
},
})
return NextResponse.json({
auth_identity: authIdentity,
})
}
```
</CodeTab>
</CodeTabs>
---
## Delete an Auth Identity
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function DELETE(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const authModuleService = req.scope.resolve(
Modules.AUTH
)
await authModuleService.deleteAuthIdentities(["authusr_123"])
res.status(200)
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeAuthModule } from "@medusajs/medusa/auth"
type ContextType = {
params: {
id: string
}
}
export async function DELETE(request: Request, { params }: ContextType) {
const authModuleService = await initializeAuthModule()
await authModuleService.deleteAuthIdentities(["authusr_123"])
}
```
</CodeTab>
</CodeTabs>
---
## More Examples
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
+116 -107
View File
@@ -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" />