asyavee/medusa-store
1
0 Fork 0
Code Issues Pull Requests Actions 3 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 authored and GitHub committed 2024-12-26 10:32:16 +02:00
1 parent c8f9938865
commit ebca8fed28
112 files changed
+9465 -7731
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/apps/resources/app/commerce-modules/user/examples/page.mdx
-384
View File
@@ -1,384 +0,0 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Examples of the User Module`,
}
# {metadata.title}
In this guide, you’ll find common examples of how you can use the User Module in your application.
<Note>
You should only use the User Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## Create a User
<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 userModuleService = req.scope.resolve(
Modules.USER
)
const user = await userModuleService.createUsers({
email: "user@example.com",
first_name: "John",
last_name: "Smith",
})
res.json({ user })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function POST(request: Request) {
const userModuleService = await initializeUserModule()
const user = await userModuleService.createUsers({
email: "user@example.com",
first_name: "John",
last_name: "Smith",
})
return NextResponse.json({
user,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Users
<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 userModuleService = req.scope.resolve(
Modules.USER
)
res.json({
users: await userModuleService.listUsers(),
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function GET(request: Request) {
const userModuleService = await initializeUserModule()
return NextResponse.json({
users: await userModuleService.listUsers(),
})
}
```
</CodeTab>
</CodeTabs>
---
## Update a User
<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 userModuleService = req.scope.resolve(
Modules.USER
)
const user = await userModuleService.updateUsers({
id: "user_123",
last_name: "Smith",
})
res.json({ user })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function POST(request: Request) {
const userModuleService = await initializeUserModule()
const user = await userModuleService.updateUsers({
id: "user_123",
last_name: "Smith",
})
return NextResponse.json({
user,
})
}
```
</CodeTab>
</CodeTabs>
---
## Delete a User
<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 userModuleService = req.scope.resolve(
Modules.USER
)
await userModuleService.deleteUsers(["user_123"])
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function DELETE(request: Request) {
const userModuleService = await initializeUserModule()
await userModuleService.deleteUsers(["user_123"])
}
```
</CodeTab>
</CodeTabs>
---
## Invite User
<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 userModuleService = req.scope.resolve(
Modules.USER
)
const invite = await userModuleService.createInvites({
email: "user2@example.com",
})
res.json({
invite,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function POST(request: Request, { params }: ContextType) {
const userModuleService = await initializeUserModule()
const invite = await userModuleService.createInvites({
email: "user2@example.com",
})
return NextResponse.json({
invite,
})
}
```
</CodeTab>
</CodeTabs>
---
## Accept Invite
<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 userModuleService = req.scope.resolve(
Modules.USER
)
const invite = await userModuleService.validateInviteToken("secret_123")
const user = await userModuleService.createUsers({
email: invite.email,
metadata: invite.metadata,
})
await userModuleService.updateInvites({
id: invite.id,
accepted: true,
})
res.json({
user,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function POST(request: Request, { params }: ContextType) {
const userModuleService = await initializeUserModule()
const invite = await userModuleService.validateInviteToken("secret_123")
const user = await userModuleService.createUsers({
email: invite.email,
metadata: invite.metadata,
})
await userModuleService.updateInvites({
id: invite.id,
accepted: true,
})
return NextResponse.json({
user,
})
}
```
</CodeTab>
</CodeTabs>
---
## Refresh Invite
<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 userModuleService = req.scope.resolve(
Modules.USER
)
const invites = await userModuleService.refreshInviteTokens(["invite_123"])
res.json({
invite: invites[0],
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeUserModule } from "@medusajs/medusa/user"
export async function POST(request: Request, { params }: ContextType) {
const userModuleService = await initializeUserModule()
const invites = await userModuleService.refreshInviteTokens(["invite_123"])
return NextResponse.json({
invite: invites[0],
})
}
```
</CodeTab>
</CodeTabs>
---
## More Examples
The [User Module's main service reference](/references/user) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/user/page.mdx
+121 -62
View File
@@ -6,101 +6,160 @@ export const metadata = {
# {metadata.title}
The User Module provides user-related features in your Medusa and Node.js applications.
In this section of the documentation, you will find resources to learn more about the User Module and how to use it in your application.
Medusa has user related features available out-of-the-box through the User 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 User Module.
<Note>
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
</Note>
## User Features
- [User Management](./user-creation-flows/page.mdx): Store and manage users in your store.
- [Invite Users](./user-creation-flows/page.mdx#invite-users): Invite users to join your store and manage those invites.
---
## How to Use User Module's Service
You can use the User Module's main service by resolving from the Medusa container the resource `Modules.USER`.
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 = [
["12", "Modules.USER", "Resolve the module in a step."]
]
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
```ts title="src/workflows/create-user.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const userModuleService = container.resolve(
Modules.USER
)
const createUserStep = createStep(
"create-user",
async ({}, { container }) => {
const userModuleService = container.resolve(Modules.USER)
const users = await userModuleService.listUsers()
})
const user = await userModuleService.createUsers({
email: "user@example.com",
first_name: "John",
last_name: "Smith",
})
return new StepResponse({ user }, user.id)
},
async (userId, { container }) => {
if (!userId) {
return
}
const userModuleService = container.resolve(Modules.USER)
await userModuleService.deleteUsers([userId])
}
)
export const createUserWorkflow = createWorkflow(
"create-user",
() => {
const { user } = createUserStep()
return new WorkflowResponse({
user,
})
}
)
```
</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"
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { createUserWorkflow } from "../../workflows/create-user"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const userModuleService = req.scope.resolve(
Modules.USER
)
) {
const { result } = await createUserWorkflow(req.scope)
.run()
res.json({
users: await userModuleService.listUsers(),
})
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { createUserWorkflow } from "../workflows/create-user"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await createUserWorkflow(container)
.run()
export default async function subscriberHandler({ container }: SubscriberArgs) {
const userModuleService = container.resolve(
Modules.USER
)
console.log(result)
}
const users = await userModuleService.listUsers()
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { createUserWorkflow } from "../workflows/create-user"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await createUserWorkflow(container)
.run()
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
---
## Features
### User Management
Manage and store your users through Create, Read, Update, and Delete (CRUD) operations:
```ts
const user = await userModuleService.createUsers({
email: "user@example.com",
first_name: "John",
last_name: "Smith",
})
```
### Invite Users
Invite users to join your store and manage those invites, with expiry and revalidation features.
```ts
const invite = await userModuleService.createInvites({
email: "user2@example.com",
})
// refresh token later
await userModuleService.refreshInviteTokens([invite.id])
```
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
---
## Configure User Module
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
The User Module accepts options for further configurations. Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
---
<CommerceModuleSections name="User" />