asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 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/api-key/concepts/page.mdx
+29
View File
@@ -0,0 +1,29 @@
export const metadata = {
title: `API Key Concepts`,
}
# {metadata.title}
In this document, you’ll learn how about the different types of API keys, and their expiration and verification.
## API Key Types
There are two types of API keys:
- `publishable`: A public key used in client applications, such as a storefront.
- `secret`: A secret key used for authentication and verification purposes, such as an admin user’s authentication token or a password reset token.
The API key’s type is stored in the `type` field of the [ApiKey data model](/references/api-key/models/ApiKey).
---
## API Key Expiration
An API key expires when it’s revoked using the [revoke method of the module’s main service](/references/api-key/revoke).
The associated token is no longer usable or verifiable.
---
## Token Verification
To verify a token received as an input or in a request, use the [authenticate method of the module’s main service](/references/api-key/authenticate) which validates the token against all non-expired tokens.
www/apps/resources/app/commerce-modules/api-key/events/page.mdx
+6
View File
@@ -8,4 +8,10 @@ export const metadata = {
Find in this reference the list of events emitted by the API Key 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/api-key/examples/page.mdx
+37 -14
View File
@@ -120,19 +120,27 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import {
AuthenticatedMedusaRequest,
MedusaResponse
} from "@medusajs/medusa"
import { IApiKeyModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
import {
ModuleRegistrationName
} from "@medusajs/modules-sdk"
export async function POST(
request: MedusaRequest,
request: AuthenticatedMedusaRequest,
res: MedusaResponse
) {
const apiKeyModuleService: IApiKeyModuleService =
request.scope.resolve(ModuleRegistrationName.API_KEY)
const revokedKey = await apiKeyModuleService.revoke(
request.params.id
request.params.id,
{
revoked_by: request.auth_context.actor_id
}
)
res.json({
@@ -154,6 +162,7 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
type ContextType = {
params: {
id: string
user_id: string
}
}
@@ -163,7 +172,12 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
) {
const apiKeyModuleService = await initializeApiKeyModule()
const revokedKey = await apiKeyModuleService.revoke(params.id)
const revokedKey = await apiKeyModuleService.revoke(
params.id,
{
revoked_by: params.user_id
}
)
return NextResponse.json({
api_key: revokedKey,
@@ -176,7 +190,7 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
---
## Verify Token
## Verify or Authenticate Token
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
@@ -194,7 +208,7 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
request.scope.resolve(ModuleRegistrationName.API_KEY)
const authenticatedToken =
await apiKeyModuleService.authenticate(request.params.id)
await apiKeyModuleService.authenticate(request.params.token)
res.json({
is_authenticated: !!authenticatedToken,
@@ -214,7 +228,7 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
type ContextType = {
params: {
id: string
token: string
}
}
@@ -225,7 +239,7 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
const apiKeyModuleService = await initializeApiKeyModule()
const authenticatedToken =
await apiKeyModuleService.authenticate(request.params.id)
await apiKeyModuleService.authenticate(request.params.token)
return NextResponse.json({
is_authenticated: !!authenticatedToken,
@@ -244,19 +258,25 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import {
AuthenticatedMedusaRequest,
MedusaResponse
} from "@medusajs/medusa"
import { IApiKeyModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function POST(
request: MedusaRequest,
request: AuthenticatedMedusaRequest,
res: MedusaResponse
) {
const apiKeyModuleService: IApiKeyModuleService =
request.scope.resolve(ModuleRegistrationName.API_KEY)
const revokedKey = await apiKeyModuleService.revoke(
request.params.id
request.params.id,
{
revoked_by: request.auth_context.actor_id
}
)
const newKey = await apiKeyModuleService.create({
@@ -284,6 +304,7 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
type ContextType = {
params: {
id: string
user_id: string
}
}
@@ -293,7 +314,9 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
) {
const apiKeyModuleService = await initializeApiKeyModule()
const revokedKey = await apiKeyModuleService.revoke(params.id)
const revokedKey = await apiKeyModuleService.revoke(params.id, {
revoked_by: params.user_id
})
const newKey = await apiKeyModuleService.create({
title: revokedKey.title,
@@ -314,4 +337,4 @@ In this guide, you’ll find common examples of how you can use the API Key Modu
## More Examples
The [module interface reference](/references/api-key) provides a reference to all the methods available for use with examples for each.
The [API Key Module's main service reference](/references/api-key) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/api-key/page.mdx
+21 -14
View File
@@ -8,8 +8,6 @@ export const metadata = {
The API Key Module is the `@medusajs/api-key` NPM package that provides API-key-related features in your Medusa and Node.js applications.
---
## Features
### API Key Types and Management
@@ -54,7 +52,9 @@ if (!authenticatedToken) {
Revoke keys to disable their use permenantly.
```ts
const revokedKey = await apiKeyModuleService.revoke("apk_1")
const revokedKey = await apiKeyModuleService.revoke("apk_1", {
revoked_by: "user_123"
})
```
### Roll API Keys
@@ -62,7 +62,9 @@ const revokedKey = await apiKeyModuleService.revoke("apk_1")
Roll API keys by revoking a key then re-creating it.
```ts
const revokedKey = await apiKeyModuleService.revoke("apk_1")
const revokedKey = await apiKeyModuleService.revoke("apk_1", {
revoked_by: "user_123"
})
const newKey = await apiKeyModuleService.create({
title: revokedKey.title,
@@ -75,14 +77,16 @@ const newKey = await apiKeyModuleService.create({
## Configure API Key Module
After installing the `@medusajs/api-key` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
To use the API Key Module, enable it in the `modules` object in `medusa-config.js`:
```js title="medusa-config.js"
const { Modules } = require("@medusajs/modules-sdk")
// ...
const modules = {
// ...
apiKey: {
resolve: "@medusajs/api-key",
},
[Modules.API_KEY]: true,
}
```
@@ -141,12 +145,15 @@ For example:
import { IApiKeyModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
const step1 = createStep("step-1", async (_, context) => {
const apiKeyModuleService: IApiKeyModuleService =
context.container.resolve(
ModuleRegistrationName.API_KEY
)
const apiKeys = await apiKeyModuleService.list()
const step1 = createStep(
"step-1",
async (_, { container }) => {
const apiKeyModuleService: IApiKeyModuleService =
container.resolve(
ModuleRegistrationName.API_KEY
)
const apiKeys = await apiKeyModuleService.list()
})
```
www/apps/resources/app/commerce-modules/api-key/relations-to-other-modules/page.mdx
+3 -5
View File
@@ -4,15 +4,13 @@ export const metadata = {
# {metadata.title}
When Commerce Modules are used together in a Medusa application, the Medusa application handles building the relations between these modules.
This document showcases the relation between the API Key Module and other Commerce Modules.
This document showcases the link modules defined between the API Key Module and other commerce modules.
## Sales Channel Module
You can create a publishable API key and associate it with a sales channel. The Medusa application forms a relation between the `ApiKey` and the `SalesChannel` data models.
You can create a publishable API key and associate it with a sales channel. Medusa defines a link module that builds a relation between the `ApiKey` and the `SalesChannel` data models.
![A diagram showcasing an example of how resources from the API Key and Sales Channel modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1710170465/Medusa%20Resources/api-key-sales-channel_ylpl6t.jpg)
![A diagram showcasing an example of how data models from the API Key and Sales Channel modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709812064/Medusa%20Resources/sales-channel-api-key_zmqi2l.jpg)
This is useful to avoid passing the sales channel's ID as a parameter of every request, and instead pass the publishable API key in the header of any request to the Store API route.
www/apps/resources/app/commerce-modules/api-key/tokens/page.mdx
-50
View File
@@ -1,50 +0,0 @@
export const metadata = {
title: `API Key Tokens`,
}
# {metadata.title}
In this document, you’ll learn how the API Key module generates, revokes, and verifies tokens.
## API Key Types
There are two types of API keys:
- `publishable`: A public key used in client applications, such as a storefront.
- `secret`: A secret key used for authentication and verification purposes, such as an admin user’s authentication token or a password reset token.
The API key’s type is stored in the `type` field of the `ApiKey` data model.
---
## Publishable Token Generation
When you create a publishable API key, its token is generated using [the `randomBytes` method of Node.js’s crypto package](https://nodejs.org/docs/latest-v18.x/api/crypto.html#cryptorandombytessize-callback). The token is `32` characters long and is hex-encoded. It’s stored in the `token` field of the `ApiKey` data model.
---
## Secret Token Generation
When you create a secret API key, three tokens are generated:
- A token that’s `32` characters long and hex-encoded. It’s generated using the `randomBytes` method of Node.js’s crypto package.
- A salt token that’s `15` characters long and hex-encoded. It’s also generated using the `randomBytes` method.
- A hashed token is generated from the token and salt token using [the `scrypt` method of Node.js’s crypto package](https://nodejs.org/docs/latest-v18.x/api/crypto.html#x509tostring). It’s `64` characters long and hex-encoded.
The salt and hashed tokens are stored in the `ApiKey` data model’s `salt` and `token` fields, respectively.
---
## API Key Expiration
An API key expires when it’s revoked using the `revoke` method of the module’s main service. The method sets the API key’s `revoked_at` and `revoked_by` fields accordingly.
The associated token is no longer usable or verifiable.
---
## Token Verification
To verify a token received as an input or in a request, the `authenticate` method of the module’s main service goes through all non-expired API keys. It recalculates the hash token using the supplied token and the API key’s `salt` field.
If the calculated hashed token matches the one in the database, the token is considered verified.