docs: add missing methods in guides and references (#12495)
* initial * remove unused references
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
b2984f48f5
commit
b312a7e077
47 files changed
+48520
-54324
No files matched your search
@@ -11,6 +11,7 @@ import {
|
||||
Badge,
|
||||
Tooltip,
|
||||
CopyGeneratedSnippetButton,
|
||||
BadgesList,
|
||||
} from "docs-ui"
|
||||
import { CommerceModuleSections } from "../CommerceModuleSections"
|
||||
import { EventHeader } from "../EventHeader"
|
||||
@@ -31,6 +32,7 @@ const MDXComponents: MDXComponentsType = {
|
||||
},
|
||||
EventHeader,
|
||||
CopyGeneratedSnippetButton,
|
||||
BadgesList,
|
||||
}
|
||||
|
||||
export default MDXComponents
|
||||
+40
-40
@@ -104,6 +104,19 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
export default MyAuthProviderService
|
||||
```
|
||||
|
||||
### DISPLAY\_NAME
|
||||
|
||||
This property indicates the name used when displaying the provider on a frontend application.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
static DISPLAY_NAME = "My Auth"
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### identifier
|
||||
|
||||
Every auth provider must have an `identifier` static property. The provider's ID
|
||||
@@ -119,46 +132,6 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
}
|
||||
```
|
||||
|
||||
### DISPLAY\_NAME
|
||||
|
||||
This property indicates the name used when displaying the provider on a frontend application.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
static DISPLAY_NAME = "My Auth"
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### validateOptions
|
||||
|
||||
This method validates the options of the provider set in `medusa-config.ts`.
|
||||
Implementing this method is optional. It's useful if your provider requires custom validation.
|
||||
|
||||
If the options aren't valid, throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
static validateOptions(options: Record<any, any>) {
|
||||
if (!options.apiKey) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"API key is required in the provider's options."
|
||||
)
|
||||
}
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
|
||||
|
||||
### authenticate
|
||||
|
||||
This method authenticates the user.
|
||||
@@ -463,6 +436,33 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[AuthenticationResponse](../../../types/interfaces/types.AuthenticationResponse/page.mdx)>","optional":false,"defaultValue":"","description":"The authentication response.","expandable":false,"children":[{"name":"success","type":"`boolean`","description":"Whether the authentication was successful.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"authIdentity","type":"[AuthIdentityDTO](../../../auth/interfaces/auth.AuthIdentityDTO/page.mdx)","description":"The authenticated user's details.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the auth identity.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider_identities","type":"[ProviderIdentityDTO](../../../auth/interfaces/auth.ProviderIdentityDTO/page.mdx)[]","description":"The list of provider identities linked to the auth identity.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"app_metadata","type":"`Record<string, unknown>`","description":"Holds information related to the actor IDs tied to the auth identity.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"error","type":"`string`","description":"If an error occurs during the authentication process,\nwhether within the Auth Module or a third-party provider,\nthe error message is set in this field.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"location","type":"`string`","description":"The URL to redirect to for further authentication action\nwith a third-party provider. This takes precedence before\nthe `success` field.\n\nSo, after checking that authentication is successful,\nyou should check whether this field is defined and, if so, redirect to the\nspecified location.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateCallback"/>
|
||||
|
||||
### validateOptions
|
||||
|
||||
This method validates the options of the provider set in `medusa-config.ts`.
|
||||
Implementing this method is optional. It's useful if your provider requires custom validation.
|
||||
|
||||
If the options aren't valid, throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyAuthProviderService extends AbstractAuthModuleProvider {
|
||||
static validateOptions(options: Record<any, any>) {
|
||||
if (!options.apiKey) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"API key is required in the provider's options."
|
||||
)
|
||||
}
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
|
||||
|
||||
---
|
||||
|
||||
## 3. Create Module Provider Definition File
|
||||
|
||||
+20
-20
@@ -69,26 +69,6 @@ const data = await cacheModuleService.get("my-key")
|
||||
|
||||
___
|
||||
|
||||
## set
|
||||
|
||||
This method stores data in the cache.
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
await cacheModuleService.set("my-key", { product_id: "prod_123" }, 60)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"key","type":"`string`","description":"The key of the item to store.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`unknown`","description":"The data to store in the cache.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"ttl","type":"`number`","description":"The time-to-live (TTL) value in seconds. If not provided, the default TTL value is used. The default value is based on the used Cache Module.","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"This method stores data in the cache.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
|
||||
|
||||
___
|
||||
|
||||
## invalidate
|
||||
|
||||
This method removes an item from the cache.
|
||||
@@ -106,3 +86,23 @@ await cacheModuleService.invalidate("my-key")
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"This method removes an item from the cache.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="invalidate"/>
|
||||
|
||||
___
|
||||
|
||||
## set
|
||||
|
||||
This method stores data in the cache.
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
await cacheModuleService.set("my-key", { product_id: "prod_123" }, 60)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"key","type":"`string`","description":"The key of the item to store.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`unknown`","description":"The data to store in the cache.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"ttl","type":"`number`","description":"The time-to-live (TTL) value in seconds. If not provided, the default TTL value is used. The default value is based on the used Cache Module.","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"This method stores data in the cache.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
|
||||
+167
-129
@@ -113,31 +113,172 @@ class MyFileProviderService extends AbstractFileProviderService {
|
||||
}
|
||||
```
|
||||
|
||||
### validateOptions
|
||||
### delete
|
||||
|
||||
This method validates the options of the provider set in `medusa-config.ts`.
|
||||
Implementing this method is optional. It's useful if your provider requires custom validation.
|
||||
|
||||
If the options aren't valid, throw an error.
|
||||
This method deletes the file from storage. It's used when an admin user deletes a product image,
|
||||
or other custom file deletions.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
static validateOptions(options: Record<any, any>) {
|
||||
if (!options.apiKey) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"API key is required in the provider's options."
|
||||
)
|
||||
}
|
||||
// ...
|
||||
async delete(file: ProviderDeleteFileDTO): Promise<void> {
|
||||
// TODO logic to remove the file from storage
|
||||
// Use the `file.fileKey` to delete the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
this.client.delete(file.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
|
||||
<TypeList types={[{"name":"file","type":"[ProviderDeleteFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderDeleteFileDTO/page.mdx)","description":"The details of the file to delete.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key. When uploading a file, the\nreturned key is used here.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="delete"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the file is deleted.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="delete"/>
|
||||
|
||||
### getAsBuffer
|
||||
|
||||
This method retrieves an uploaded file as a buffer. This is useful when you want to
|
||||
process the entire file in memory or send it as a response.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getAsBuffer(file: ProviderDeleteFileDTO): Promise<Buffer> {
|
||||
// TODO logic to get the file as a buffer
|
||||
// Use the `file.fileKey` to get the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
this.client.getAsBuffer(file.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)","description":"The details of the file to get its buffer.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Buffer>","optional":false,"defaultValue":"","description":"The file's buffer.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
|
||||
### getDownloadStream
|
||||
|
||||
This method retrieves an uploaded file as a stream. This is useful when streaming
|
||||
a file to clients or you want to process the file in chunks.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getAsStream(file: ProviderDeleteFileDTO): Promise<Readable> {
|
||||
// TODO logic to get the file as a stream
|
||||
// Use the `file.fileKey` to get the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
this.client.getAsStream(file.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)","description":"The details of the file to get its stream.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Readable>","optional":false,"defaultValue":"","description":"The file's stream.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
### getPresignedDownloadUrl
|
||||
|
||||
This method is used to retrieve a download URL of the file. For some providers,
|
||||
such as S3, a presigned URL indicates a temporary URL to get access to a file.
|
||||
|
||||
If your provider doesn’t perform or offer a similar functionality, you can
|
||||
return the URL to download the file.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getPresignedDownloadUrl(
|
||||
fileData: ProviderGetFileDTO
|
||||
): Promise<string> {
|
||||
// TODO logic to get the presigned URL
|
||||
// Use the `file.fileKey` to delete the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
return this.client.getPresignedUrl(fileData.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)","description":"The details of the file to get its\npresigned URL.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPresignedDownloadUrl"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<string>","optional":false,"defaultValue":"","description":"The file's presigned URL.","expandable":false,"children":[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPresignedDownloadUrl"/>
|
||||
|
||||
### getPresignedUploadUrl
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used to get a presigned upload URL for a file. For some providers,
|
||||
such as S3, a presigned URL indicates a temporary URL to get upload a file.
|
||||
|
||||
If your provider doesn’t perform or offer a similar functionality, you don't have to
|
||||
implement this method. Instead, an error is thrown when the method is called.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getPresignedUploadUrl(
|
||||
fileData: ProviderGetPresignedUploadUrlDTO
|
||||
): Promise<ProviderFileResultDTO> {
|
||||
// TODO logic to get the presigned upload URL
|
||||
// for example:
|
||||
return this.client.getPresignedUploadUrl(fileData.filename, fileData.mimeType)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetPresignedUploadUrlDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetPresignedUploadUrlDTO/page.mdx)","description":"The details of the file to get a presigned upload URL for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"filename","type":"`string`","description":"The filename of the file to get a presigned upload URL for.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"mimeType","type":"`string`","description":"The mimetype of the file to get a presigned upload URL for.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"access","type":"[FileAccessPermission](../../../types/FileTypes/types/types.FileTypes.FileAccessPermission/page.mdx)","description":"The access level of the file to get a presigned upload URL for.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"expiresIn","type":"`number`","description":"The validity of the presigned upload URL in seconds.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPresignedUploadUrl"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[ProviderFileResultDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderFileResultDTO/page.mdx)>","optional":false,"defaultValue":"","description":"The presigned URL and file key to upload the file to","expandable":false,"children":[{"name":"url","type":"`string`","description":"The file's URL that users or systems\ncan use to access the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"key","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPresignedUploadUrl"/>
|
||||
|
||||
### upload
|
||||
|
||||
@@ -176,134 +317,31 @@ class MyFileProviderService extends AbstractFileProviderService {
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[ProviderFileResultDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderFileResultDTO/page.mdx)>","optional":false,"defaultValue":"","description":"The uploaded file's details.","expandable":false,"children":[{"name":"url","type":"`string`","description":"The file's URL that users or systems\ncan use to access the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"key","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="upload"/>
|
||||
|
||||
### delete
|
||||
### validateOptions
|
||||
|
||||
This method deletes the file from storage. It's used when an admin user deletes a product image,
|
||||
or other custom file deletions.
|
||||
This method validates the options of the provider set in `medusa-config.ts`.
|
||||
Implementing this method is optional. It's useful if your provider requires custom validation.
|
||||
|
||||
If the options aren't valid, throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async delete(file: ProviderDeleteFileDTO): Promise<void> {
|
||||
// TODO logic to remove the file from storage
|
||||
// Use the `file.fileKey` to delete the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
this.client.delete(file.fileKey)
|
||||
static validateOptions(options: Record<any, any>) {
|
||||
if (!options.apiKey) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"API key is required in the provider's options."
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"file","type":"[ProviderDeleteFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderDeleteFileDTO/page.mdx)","description":"The details of the file to delete.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key. When uploading a file, the\nreturned key is used here.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="delete"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the file is deleted.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="delete"/>
|
||||
|
||||
### getPresignedDownloadUrl
|
||||
|
||||
This method is used to retrieve a download URL of the file. For some providers,
|
||||
such as S3, a presigned URL indicates a temporary URL to get access to a file.
|
||||
|
||||
If your provider doesn’t perform or offer a similar functionality, you can
|
||||
return the URL to download the file.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getPresignedDownloadUrl(
|
||||
fileData: ProviderGetFileDTO
|
||||
): Promise<string> {
|
||||
// TODO logic to get the presigned URL
|
||||
// Use the `file.fileKey` to delete the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
return this.client.getPresignedUrl(fileData.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)","description":"The details of the file to get its\npresigned URL.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPresignedDownloadUrl"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<string>","optional":false,"defaultValue":"","description":"The file's presigned URL.","expandable":false,"children":[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPresignedDownloadUrl"/>
|
||||
|
||||
### getDownloadStream
|
||||
|
||||
This method retrieves an uploaded file as a stream. This is useful when streaming
|
||||
a file to clients or you want to process the file in chunks.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getAsStream(file: ProviderDeleteFileDTO): Promise<Readable> {
|
||||
// TODO logic to get the file as a stream
|
||||
// Use the `file.fileKey` to get the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
this.client.getAsStream(file.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)","description":"The details of the file to get its stream.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Readable>","optional":false,"defaultValue":"","description":"The file's stream.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
### getAsBuffer
|
||||
|
||||
This method retrieves an uploaded file as a buffer. This is useful when you want to
|
||||
process the entire file in memory or send it as a response.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFileProviderService extends AbstractFileProviderService {
|
||||
// ...
|
||||
async getAsBuffer(file: ProviderDeleteFileDTO): Promise<Buffer> {
|
||||
// TODO logic to get the file as a buffer
|
||||
// Use the `file.fileKey` to get the file, which is the identifier of the file
|
||||
// in the provider's storage.
|
||||
// for example:
|
||||
this.client.getAsBuffer(file.fileKey)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"fileData","type":"[ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)","description":"The details of the file to get its buffer.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"fileKey","type":"`string`","description":"The file's key allowing you to later\nidentify the file in the third-party\nsystem. For example, the S3 Module Provider\nreturns the file's key in S3, whereas the\nLocal File Module Provider returns the file's\npath.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Buffer>","optional":false,"defaultValue":"","description":"The file's buffer.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
|
||||
|
||||
---
|
||||
|
||||
|
||||
+116
-116
@@ -39,16 +39,6 @@ You can then use the File Module's service's methods in the step. The rest of th
|
||||
|
||||
---
|
||||
|
||||
## getProvider
|
||||
|
||||
Returns a reference to the file provider in use
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"upload","type":"(`file`: [ProviderUploadFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderUploadFileDTO/page.mdx)) => Promise<[ProviderFileResultDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderFileResultDTO/page.mdx)>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"delete","type":"(`fileData`: [ProviderDeleteFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderDeleteFileDTO/page.mdx)) => Promise<void>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getPresignedDownloadUrl","type":"(`fileData`: [ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)) => Promise<string>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getDownloadStream","type":"(`fileData`: [ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)) => Promise<Readable>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getAsBuffer","type":"(`fileData`: [ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)) => Promise<Buffer>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getPresignedUploadUrl","type":"(`fileData`: [ProviderGetPresignedUploadUrlDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetPresignedUploadUrlDTO/page.mdx)) => Promise<[ProviderFileResultDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderFileResultDTO/page.mdx)>","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getProvider"/>
|
||||
|
||||
___
|
||||
|
||||
## createFiles
|
||||
|
||||
### createFiles(data, sharedContext?): Promise<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)[]>
|
||||
@@ -97,6 +87,112 @@ const file = await fileModuleService.createFiles({
|
||||
|
||||
___
|
||||
|
||||
## deleteFiles
|
||||
|
||||
### deleteFiles(ids, sharedContext?): Promise<void>
|
||||
|
||||
This method deletes files by their IDs.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
await fileModuleService.deleteFiles(["file_123"])
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"ids","type":"`string`[]","description":"The IDs of the files.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the files are deleted successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
### deleteFiles(id, sharedContext?): Promise<void>
|
||||
|
||||
This method deletes a file by its ID.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
await fileModuleService.deleteFiles("file_123")
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the file is deleted successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
___
|
||||
|
||||
## getAsBuffer
|
||||
|
||||
This method retrieves a file by its ID and returns the file contents as a buffer. Under the hood, it will use the
|
||||
file provider that was used to upload the file to retrieve the buffer.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
const contents = await fileModuleService.getAsBuffer("file_123")
|
||||
contents.toString('utf-8')
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Buffer>","optional":false,"defaultValue":"","description":"A buffer of the file contents.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
|
||||
___
|
||||
|
||||
## getDownloadStream
|
||||
|
||||
This method retrieves a file by its ID and returns a stream to download the file. Under the hood, it will use the
|
||||
file provider that was used to upload the file to retrievethe stream.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
const stream = await fileModuleService.getDownloadStream("file_123")
|
||||
writeable.pipe(stream)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Readable>","optional":false,"defaultValue":"","description":"A readable stream of the file contents.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
___
|
||||
|
||||
## getProvider
|
||||
|
||||
Returns a reference to the file provider in use
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"upload","type":"(`file`: [ProviderUploadFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderUploadFileDTO/page.mdx)) => Promise<[ProviderFileResultDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderFileResultDTO/page.mdx)>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"delete","type":"(`fileData`: [ProviderDeleteFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderDeleteFileDTO/page.mdx)) => Promise<void>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getPresignedDownloadUrl","type":"(`fileData`: [ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)) => Promise<string>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getDownloadStream","type":"(`fileData`: [ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)) => Promise<Readable>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getAsBuffer","type":"(`fileData`: [ProviderGetFileDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetFileDTO/page.mdx)) => Promise<Buffer>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"getPresignedUploadUrl","type":"(`fileData`: [ProviderGetPresignedUploadUrlDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderGetPresignedUploadUrlDTO/page.mdx)) => Promise<[ProviderFileResultDTO](../../../types/FileTypes/interfaces/types.FileTypes.ProviderFileResultDTO/page.mdx)>","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getProvider"/>
|
||||
|
||||
___
|
||||
|
||||
## getUploadFileUrls
|
||||
|
||||
### getUploadFileUrls(data, sharedContext?): Promise<[UploadFileUrlDTO](../../../types/FileTypes/interfaces/types.FileTypes.UploadFileUrlDTO/page.mdx)>
|
||||
@@ -143,63 +239,23 @@ const [uploadInfo] = await fileModuleService.getUploadFileUrls([{
|
||||
|
||||
___
|
||||
|
||||
## deleteFiles
|
||||
## listAndCountFiles
|
||||
|
||||
### deleteFiles(ids, sharedContext?): Promise<void>
|
||||
|
||||
This method deletes files by their IDs.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
await fileModuleService.deleteFiles(["file_123"])
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"ids","type":"`string`[]","description":"The IDs of the files.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the files are deleted successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
### deleteFiles(id, sharedContext?): Promise<void>
|
||||
|
||||
This method deletes a file by its ID.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
await fileModuleService.deleteFiles("file_123")
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the file is deleted successfully.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteFiles"/>
|
||||
|
||||
___
|
||||
|
||||
## retrieveFile
|
||||
|
||||
This method retrieves a file with a downloadable URL by its ID.
|
||||
This method is used to retrieve a file by ID, similarly to `retrieve`. It doesn't retrieve multiple files, but it's added to support retrieving files with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query).
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
const file = await fileModuleService.retrieveFile("file_123")
|
||||
const [files] = await fileModuleService.listAndCountFiles({ id: "file_123" })
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"[FindConfig](../../../medusa/interfaces/medusa.FindConfig/page.mdx)<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)>","description":"The configurations determining how the file is retrieved. Its properties, such as `select` or `relations`, accept the\nattributes or relations associated with a file.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \\| `string` & `object`)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"`null` \\| `number`","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"`null` \\| `number`","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`string`[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[FindConfigOrder](../../../medusa/types/medusa.FindConfigOrder/page.mdx)","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`\nto sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"`boolean`","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\n`SoftDeletableEntity` class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"`Record<string, any>`","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indLine truncated
|
||||
<TypeList types={[{"name":"filters","type":"[FilterableFileProps](../../../types/FileTypes/interfaces/types.FileTypes.FilterableFileProps/page.mdx)","description":"The filters to apply on the retrieved files.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The file ID to filter by.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"config","type":"[FindConfig](../../../medusa/interfaces/medusa.FindConfig/page.mdx)<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)>","description":"The configurations determining how the files are retrieved. Its properties, such as `select` or `relations`, accept the\nattributes or relations associated with a file.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \\| `string` & `object`)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"`null` \\| `number`","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"`null` \\| `number`","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`string`[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[FindConfigOrder](../../../medusa/types/medusa.FindConfigOrder/page.mdx)","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`\nto sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"`boolean`","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\n`SoftDeletableEntity` class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"`Record<string, any>`","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandableLine truncated
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)>","optional":false,"defaultValue":"","description":"The retrieved file.","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the file. You can use this ID later to\nretrieve or delete the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"url","type":"`string`","description":"The URL of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrieveFile"/>
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)[], number]>","optional":false,"defaultValue":"","description":"The list of files and their count. In this case, it will have at most one file.","expandable":false,"children":[{"name":"FileDTO[]","type":"[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"number","type":"`number`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="listAndCountFiles"/>
|
||||
|
||||
___
|
||||
|
||||
@@ -223,76 +279,20 @@ const files = await fileModuleService.listFiles({ id: "file_123" })
|
||||
|
||||
___
|
||||
|
||||
## listAndCountFiles
|
||||
## retrieveFile
|
||||
|
||||
This method is used to retrieve a file by ID, similarly to `retrieve`. It doesn't retrieve multiple files, but it's added to support retrieving files with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query).
|
||||
This method retrieves a file with a downloadable URL by its ID.
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
const [files] = await fileModuleService.listAndCountFiles({ id: "file_123" })
|
||||
const file = await fileModuleService.retrieveFile("file_123")
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"filters","type":"[FilterableFileProps](../../../types/FileTypes/interfaces/types.FileTypes.FilterableFileProps/page.mdx)","description":"The filters to apply on the retrieved files.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The file ID to filter by.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"config","type":"[FindConfig](../../../medusa/interfaces/medusa.FindConfig/page.mdx)<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)>","description":"The configurations determining how the files are retrieved. Its properties, such as `select` or `relations`, accept the\nattributes or relations associated with a file.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \\| `string` & `object`)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"`null` \\| `number`","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"`null` \\| `number`","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`string`[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[FindConfigOrder](../../../medusa/types/medusa.FindConfigOrder/page.mdx)","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`\nto sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"`boolean`","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\n`SoftDeletableEntity` class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"`Record<string, any>`","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandableLine truncated
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"[FindConfig](../../../medusa/interfaces/medusa.FindConfig/page.mdx)<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)>","description":"The configurations determining how the file is retrieved. Its properties, such as `select` or `relations`, accept the\nattributes or relations associated with a file.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \\| `string` & `object`)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"`null` \\| `number`","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"`null` \\| `number`","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`string`[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[FindConfigOrder](../../../medusa/types/medusa.FindConfigOrder/page.mdx)","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`\nto sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"`boolean`","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\n`SoftDeletableEntity` class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"`Record<string, any>`","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indLine truncated
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)[], number]>","optional":false,"defaultValue":"","description":"The list of files and their count. In this case, it will have at most one file.","expandable":false,"children":[{"name":"FileDTO[]","type":"[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"number","type":"`number`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="listAndCountFiles"/>
|
||||
|
||||
___
|
||||
|
||||
## getDownloadStream
|
||||
|
||||
This method retrieves a file by its ID and returns a stream to download the file. Under the hood, it will use the
|
||||
file provider that was used to upload the file to retrievethe stream.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
const stream = await fileModuleService.getDownloadStream("file_123")
|
||||
writeable.pipe(stream)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Readable>","optional":false,"defaultValue":"","description":"A readable stream of the file contents.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getDownloadStream"/>
|
||||
|
||||
___
|
||||
|
||||
## getAsBuffer
|
||||
|
||||
This method retrieves a file by its ID and returns the file contents as a buffer. Under the hood, it will use the
|
||||
file provider that was used to upload the file to retrieve the buffer.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.8.0`.
|
||||
|
||||
:::
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
const contents = await fileModuleService.getAsBuffer("file_123")
|
||||
contents.toString('utf-8')
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"id","type":"`string`","description":"The ID of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<Buffer>","optional":false,"defaultValue":"","description":"A buffer of the file contents.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getAsBuffer"/>
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[FileDTO](../../../types/FileTypes/interfaces/types.FileTypes.FileDTO/page.mdx)>","optional":false,"defaultValue":"","description":"The retrieved file.","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the file. You can use this ID later to\nretrieve or delete the file.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"url","type":"`string`","description":"The URL of the file.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrieveFile"/>
|
||||
+182
-182
@@ -124,134 +124,6 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
}
|
||||
```
|
||||
|
||||
### getFulfillmentOptions
|
||||
|
||||
This method retrieves a list of fulfillment options that this provider supports. Admin users will then choose from these options when
|
||||
they're creating a shipping option. The chosen fulfillment option's object is then stored within the created shipping option's `data` property.
|
||||
The `data` property is useful to store data relevant for the third-party provider to later process the fulfillment.
|
||||
|
||||
This method is useful if your third-party provider allows you to retrieve support options, carriers, or services from an API. You can then
|
||||
retrieve those and return then in the method, allowing the admin user to choose from the services provided by the third-party provider.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import { FulfillmentOption } from "@medusajs/framework/types"
|
||||
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
|
||||
// assuming you have a client
|
||||
const services = await this.client.getServices()
|
||||
|
||||
return services.map((service) => ({
|
||||
id: service.service_id,
|
||||
name: service.name,
|
||||
service_code: service.code,
|
||||
// can add other relevant data for the provider to later process the shipping option.
|
||||
}))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[FulfillmentOption](../../../types/types/types.FulfillmentOption/page.mdx)[]>","optional":false,"defaultValue":"","description":"The list of fulfillment options. Each object in the array should have an `id` property unique to an item, and a `name` property\nthat's used to display the option in the admin.","expandable":false,"children":[{"name":"FulfillmentOption[]","type":"[FulfillmentOption](../../../types/types/types.FulfillmentOption/page.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The option's ID. This ID can be an ID in the third-party system relevant\nfor later processing of fulfillment.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_return","type":"`boolean`","description":"Whether the option can be used to return items.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getFulfillmentOptions"/>
|
||||
|
||||
### validateFulfillmentData
|
||||
|
||||
This method validates the `data` property of a shipping method and returns it. The returned data
|
||||
is stored in the shipping method's `data` property.
|
||||
|
||||
Your fulfillment provider can use the `data` property to store additional information useful for
|
||||
handling the fulfillment later. For example, you may store an ID from the third-party fulfillment
|
||||
system.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async validateFulfillmentData(
|
||||
optionData: any,
|
||||
data: any,
|
||||
context: any
|
||||
): Promise<any> {
|
||||
// assuming your client retrieves an ID from the
|
||||
// third-party service
|
||||
const externalId = await this.client.getId()
|
||||
|
||||
return {
|
||||
...data,
|
||||
externalId
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"optionData","type":"`Record<string, unknown>`","description":"The `data` property of the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"The `data` property of the shipping method.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[ValidateFulfillmentDataContext](../../../types/types/types.ValidateFulfillmentDataContext/page.mdx)","description":"Context details, such as context of the cart or customer.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"[CartDTO](../../../fulfillment/interfaces/fulfillment.CartDTO/page.mdx)[`\"id\"`]","description":"The cart's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_address","type":"[CartDTO](../../../fulfillment/interfaces/fulfillment.CartDTO/page.mdx)[`\"shipping_address\"`]","description":"The cart's shipping address.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"items","type":"[CartDTO](../../../fulfillment/interfaces/fulfillment.CartDTO/page.mdx)[`\"items\"`] & `object`","description":"The cart's items","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"variant","type":"`object`","description":"The item's variant.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"product","type":"`object`","description":"The item's product.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"from_location","type":"[StockLocationDTO](../../../types/StockLocationTypes/types/types.StockLocationTypes.StockLocationDTO/page.mdx)","description":"Details about the location that items are being shipped from.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"The name of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`Record<string, unknown>` \\| `null`","description":"Holds custom data in key-value pairs.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"address_id","type":"`string`","description":"The associated address's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"fulfillment_sets","type":"[FulfillmentSetDTO](../../../fulfillment/interfaces/fulfillment.FulfillmentSetDTO/page.mdx)[]","description":"Fulfillment sets for the location","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`string` \\| `Date`","description":"The creation date of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`string` \\| `Date`","description":"The update date of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`string` \\| `Date` \\| `null`","description":"The deletion date of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"address","type":"[StockLocationAddressDTO](../../../types/StockLocationTypes/types/types.StockLocationTypes.StockLocationAddressDTO/page.mdx)","description":"The address of the stock location.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateFulfillmentData"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"the data to store in the `data` property of the shipping method.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateFulfillmentData"/>
|
||||
|
||||
### validateOption
|
||||
|
||||
This method validates the `data` property of a shipping option when it's created.
|
||||
|
||||
The `data` property can hold useful information that's later added to the `data` attribute
|
||||
of shipping methods created from this option.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async validateOption(data: any): Promise<boolean> {
|
||||
return data.external_id !== undefined
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"`Record<string, unknown>`","description":"The data to validate.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOption"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<boolean>","optional":false,"defaultValue":"","description":"Whether the data is valid.","expandable":false,"children":[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOption"/>
|
||||
|
||||
### canCalculate
|
||||
|
||||
This method validates whether a shippin option's price can be calculated during checkout. It's executed when the admin user creates a shipping
|
||||
option of type `calculated`. If this method returns `false`, an error is thrown as the shipping option's price can't be calculated.
|
||||
|
||||
You can perform the checking using the third-party provider if applicable. The `data` parameter will hold the shipping option's `data` property, which
|
||||
includes the data of a fulfillment option returned by [getFulfillmentOptions](page.mdx#getfulfillmentoptions).
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
|
||||
// assuming you have a client
|
||||
return await this.client.hasRates(data.id)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[CreateShippingOptionDTO](../../../fulfillment/interfaces/fulfillment.CreateShippingOptionDTO/page.mdx)","description":"The `data` property of the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"name","type":"`string`","description":"The name of the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"price_type","type":"[ShippingOptionPriceType](../../../fulfillment/types/fulfillment.ShippingOptionPriceType/page.mdx)","description":"The type of the shipping option's price.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"service_zone_id","type":"`string`","description":"The associated service zone's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_profile_id","type":"`string`","description":"The associated shipping profile's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider_id","type":"`string`","description":"The associated provider's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"type","type":"Omit<[CreateShippingOptionTypeDTO](../../../fulfillment/interfaces/fulfillment.CreateShippingOptionTypeDTO/page.mdx), \"shipping_option_id\">","description":"The shipping option type associated with the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"label","type":"`string`","description":"The label of the shipping option type.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"description","type":"`string`","description":"The description of the shipping option type.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"`string`","description":"The code of the shipping option type.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"data","type":"`null` \\| `Record<string, unknown>`","description":"The data necessary for the associated fulfillment provider to process the shipping option\nand its associated fulfillments.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"rules","type":"Omit<[CreateShippingOptionRuleDTO](../../../fulfillment/interfaces/fulfillment.CreateShippingOptionRuleDTO/page.mdx), \"shipping_option_id\">[]","description":"The shipping option rules associated with the shipping option.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"attribute","type":"`string`","description":"The attribute of the shipping option rule.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"operator","type":"[RuleOperatorType](../../../fulfillment/types/fulfillment.RuleOperatorType/page.mdx)","description":"The operator of the shipping option rule.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"value","type":"`string` \\| `string`[]","description":"The value(s) of the shipping option rule.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="canCalculate"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<boolean>","optional":false,"defaultValue":"","description":"Whether the price can be calculated for the shipping option.","expandable":false,"children":[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="canCalculate"/>
|
||||
|
||||
### calculatePrice
|
||||
|
||||
This method calculates the price of a shipping method when it's created or its cart is refreshed.
|
||||
@@ -297,6 +169,63 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CalculatedShippingOptionPrice](../../../types/types/types.CalculatedShippingOptionPrice/page.mdx)>","optional":false,"defaultValue":"","description":"The calculated price's details.","expandable":false,"children":[{"name":"calculated_amount","type":"`number`","description":"The calculated price.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_calculated_price_tax_inclusive","type":"`boolean`","description":"Whether the calculated price includes taxes. If enabled, Medusa will\ninfer the taxes from the calculated price. If false, Medusa will\nadd taxes to the calculated price.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="calculatePrice"/>
|
||||
|
||||
### canCalculate
|
||||
|
||||
This method validates whether a shippin option's price can be calculated during checkout. It's executed when the admin user creates a shipping
|
||||
option of type `calculated`. If this method returns `false`, an error is thrown as the shipping option's price can't be calculated.
|
||||
|
||||
You can perform the checking using the third-party provider if applicable. The `data` parameter will hold the shipping option's `data` property, which
|
||||
includes the data of a fulfillment option returned by [getFulfillmentOptions](page.mdx#getfulfillmentoptions).
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async canCalculate(data: CreateShippingOptionDTO): Promise<boolean> {
|
||||
// assuming you have a client
|
||||
return await this.client.hasRates(data.id)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[CreateShippingOptionDTO](../../../fulfillment/interfaces/fulfillment.CreateShippingOptionDTO/page.mdx)","description":"The `data` property of the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"name","type":"`string`","description":"The name of the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"price_type","type":"[ShippingOptionPriceType](../../../fulfillment/types/fulfillment.ShippingOptionPriceType/page.mdx)","description":"The type of the shipping option's price.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"service_zone_id","type":"`string`","description":"The associated service zone's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_profile_id","type":"`string`","description":"The associated shipping profile's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider_id","type":"`string`","description":"The associated provider's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"type","type":"Omit<[CreateShippingOptionTypeDTO](../../../fulfillment/interfaces/fulfillment.CreateShippingOptionTypeDTO/page.mdx), \"shipping_option_id\">","description":"The shipping option type associated with the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"label","type":"`string`","description":"The label of the shipping option type.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"description","type":"`string`","description":"The description of the shipping option type.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"`string`","description":"The code of the shipping option type.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"data","type":"`null` \\| `Record<string, unknown>`","description":"The data necessary for the associated fulfillment provider to process the shipping option\nand its associated fulfillments.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"rules","type":"Omit<[CreateShippingOptionRuleDTO](../../../fulfillment/interfaces/fulfillment.CreateShippingOptionRuleDTO/page.mdx), \"shipping_option_id\">[]","description":"The shipping option rules associated with the shipping option.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"attribute","type":"`string`","description":"The attribute of the shipping option rule.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"operator","type":"[RuleOperatorType](../../../fulfillment/types/fulfillment.RuleOperatorType/page.mdx)","description":"The operator of the shipping option rule.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"value","type":"`string` \\| `string`[]","description":"The value(s) of the shipping option rule.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="canCalculate"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<boolean>","optional":false,"defaultValue":"","description":"Whether the price can be calculated for the shipping option.","expandable":false,"children":[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="canCalculate"/>
|
||||
|
||||
### cancelFulfillment
|
||||
|
||||
This method is used when a fulfillment is canceled. Use it to perform operations
|
||||
with the third-party fulfillment service.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async cancelFulfillment(data: Record<string, unknown>): Promise<any> {
|
||||
// assuming the client cancels a fulfillment
|
||||
// in the third-party service
|
||||
const { external_id } = data as {
|
||||
external_id: string
|
||||
}
|
||||
await this.client.cancel(external_id)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"`Record<string, unknown>`","description":"The fulfillment's `data` property.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="cancelFulfillment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"This method is used when a fulfillment is canceled. Use it to perform operations\nwith the third-party fulfillment service.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="cancelFulfillment"/>
|
||||
|
||||
### createFulfillment
|
||||
|
||||
This method is used when a fulfillment is created. If the method returns in the object a
|
||||
@@ -345,60 +274,6 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CreateFulfillmentResult](../../../types/types/types.CreateFulfillmentResult/page.mdx)>","optional":false,"defaultValue":"","description":"An object whose `data` property is stored in the fulfillment's `data` property.","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Additional fulfillment data from provider","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"labels","type":"`object`[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"tracking_number","type":"`string`","description":"The tracking number of the fulfillment label.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"tracking_url","type":"`string`","description":"The tracking URL of the fulfillment label.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"label_url","type":"`string`","description":"The label's URL.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="createFulfillment"/>
|
||||
|
||||
### cancelFulfillment
|
||||
|
||||
This method is used when a fulfillment is canceled. Use it to perform operations
|
||||
with the third-party fulfillment service.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async cancelFulfillment(data: Record<string, unknown>): Promise<any> {
|
||||
// assuming the client cancels a fulfillment
|
||||
// in the third-party service
|
||||
const { external_id } = data as {
|
||||
external_id: string
|
||||
}
|
||||
await this.client.cancel(external_id)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"`Record<string, unknown>`","description":"The fulfillment's `data` property.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="cancelFulfillment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"This method is used when a fulfillment is canceled. Use it to perform operations\nwith the third-party fulfillment service.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="cancelFulfillment"/>
|
||||
|
||||
### getFulfillmentDocuments
|
||||
|
||||
This method retrieves the documents of a fulfillment.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async getFulfillmentDocuments(data: any): Promise<never[]> {
|
||||
// assuming the client retrieves documents
|
||||
// from a third-party service
|
||||
return await this.client.documents(data)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"`Record<string, unknown>`","description":"The `data` property of the fulfillment.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<never[]>","optional":false,"defaultValue":"","description":"The fulfillment's documents.","expandable":false,"children":[{"name":"never[]","type":"`never`[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
### createReturnFulfillment
|
||||
|
||||
This method is used when a fulfillment is created for a return. If the method returns in the object a
|
||||
@@ -441,6 +316,66 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CreateFulfillmentResult](../../../types/types/types.CreateFulfillmentResult/page.mdx)>","optional":false,"defaultValue":"","description":"An object containing `data` which is stored in the fulfillment's `data` property and `labels` array which is used to create FulfillmentLabels.","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Additional fulfillment data from provider","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"labels","type":"`object`[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"tracking_number","type":"`string`","description":"The tracking number of the fulfillment label.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"tracking_url","type":"`string`","description":"The tracking URL of the fulfillment label.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"label_url","type":"`string`","description":"The label's URL.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="createReturnFulfillment"/>
|
||||
|
||||
### getFulfillmentDocuments
|
||||
|
||||
This method retrieves the documents of a fulfillment.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async getFulfillmentDocuments(data: any): Promise<never[]> {
|
||||
// assuming the client retrieves documents
|
||||
// from a third-party service
|
||||
return await this.client.documents(data)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"`Record<string, unknown>`","description":"The `data` property of the fulfillment.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<never[]>","optional":false,"defaultValue":"","description":"The fulfillment's documents.","expandable":false,"children":[{"name":"never[]","type":"`never`[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
### getFulfillmentOptions
|
||||
|
||||
This method retrieves a list of fulfillment options that this provider supports. Admin users will then choose from these options when
|
||||
they're creating a shipping option. The chosen fulfillment option's object is then stored within the created shipping option's `data` property.
|
||||
The `data` property is useful to store data relevant for the third-party provider to later process the fulfillment.
|
||||
|
||||
This method is useful if your third-party provider allows you to retrieve support options, carriers, or services from an API. You can then
|
||||
retrieve those and return then in the method, allowing the admin user to choose from the services provided by the third-party provider.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import { FulfillmentOption } from "@medusajs/framework/types"
|
||||
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async getFulfillmentOptions(): Promise<FulfillmentOption[]> {
|
||||
// assuming you have a client
|
||||
const services = await this.client.getServices()
|
||||
|
||||
return services.map((service) => ({
|
||||
id: service.service_id,
|
||||
name: service.name,
|
||||
service_code: service.code,
|
||||
// can add other relevant data for the provider to later process the shipping option.
|
||||
}))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[FulfillmentOption](../../../types/types/types.FulfillmentOption/page.mdx)[]>","optional":false,"defaultValue":"","description":"The list of fulfillment options. Each object in the array should have an `id` property unique to an item, and a `name` property\nthat's used to display the option in the admin.","expandable":false,"children":[{"name":"FulfillmentOption[]","type":"[FulfillmentOption](../../../types/types/types.FulfillmentOption/page.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The option's ID. This ID can be an ID in the third-party system relevant\nfor later processing of fulfillment.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_return","type":"`boolean`","description":"Whether the option can be used to return items.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getFulfillmentOptions"/>
|
||||
|
||||
### getReturnDocuments
|
||||
|
||||
This method retrieves documents for a return's fulfillment.
|
||||
@@ -522,6 +457,71 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"The fulfillment's documents.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrieveDocuments"/>
|
||||
|
||||
### validateFulfillmentData
|
||||
|
||||
This method validates the `data` property of a shipping method and returns it. The returned data
|
||||
is stored in the shipping method's `data` property.
|
||||
|
||||
Your fulfillment provider can use the `data` property to store additional information useful for
|
||||
handling the fulfillment later. For example, you may store an ID from the third-party fulfillment
|
||||
system.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async validateFulfillmentData(
|
||||
optionData: any,
|
||||
data: any,
|
||||
context: any
|
||||
): Promise<any> {
|
||||
// assuming your client retrieves an ID from the
|
||||
// third-party service
|
||||
const externalId = await this.client.getId()
|
||||
|
||||
return {
|
||||
...data,
|
||||
externalId
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"optionData","type":"`Record<string, unknown>`","description":"The `data` property of the shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"The `data` property of the shipping method.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[ValidateFulfillmentDataContext](../../../types/types/types.ValidateFulfillmentDataContext/page.mdx)","description":"Context details, such as context of the cart or customer.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"[CartDTO](../../../fulfillment/interfaces/fulfillment.CartDTO/page.mdx)[`\"id\"`]","description":"The cart's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_address","type":"[CartDTO](../../../fulfillment/interfaces/fulfillment.CartDTO/page.mdx)[`\"shipping_address\"`]","description":"The cart's shipping address.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"items","type":"[CartDTO](../../../fulfillment/interfaces/fulfillment.CartDTO/page.mdx)[`\"items\"`] & `object`","description":"The cart's items","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"variant","type":"`object`","description":"The item's variant.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"product","type":"`object`","description":"The item's product.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"from_location","type":"[StockLocationDTO](../../../types/StockLocationTypes/types/types.StockLocationTypes.StockLocationDTO/page.mdx)","description":"Details about the location that items are being shipped from.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"The name of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`Record<string, unknown>` \\| `null`","description":"Holds custom data in key-value pairs.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"address_id","type":"`string`","description":"The associated address's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"fulfillment_sets","type":"[FulfillmentSetDTO](../../../fulfillment/interfaces/fulfillment.FulfillmentSetDTO/page.mdx)[]","description":"Fulfillment sets for the location","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`string` \\| `Date`","description":"The creation date of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`string` \\| `Date`","description":"The update date of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`string` \\| `Date` \\| `null`","description":"The deletion date of the stock location.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"address","type":"[StockLocationAddressDTO](../../../types/StockLocationTypes/types/types.StockLocationTypes.StockLocationAddressDTO/page.mdx)","description":"The address of the stock location.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateFulfillmentData"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"the data to store in the `data` property of the shipping method.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateFulfillmentData"/>
|
||||
|
||||
### validateOption
|
||||
|
||||
This method validates the `data` property of a shipping option when it's created.
|
||||
|
||||
The `data` property can hold useful information that's later added to the `data` attribute
|
||||
of shipping methods created from this option.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
|
||||
// ...
|
||||
async validateOption(data: any): Promise<boolean> {
|
||||
return data.external_id !== undefined
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"`Record<string, unknown>`","description":"The data to validate.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOption"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<boolean>","optional":false,"defaultValue":"","description":"Whether the data is valid.","expandable":false,"children":[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOption"/>
|
||||
|
||||
---
|
||||
|
||||
## 3. Create Module Provider Definition File
|
||||
|
||||
@@ -39,6 +39,49 @@ You can then use the Locking Module's service's methods in the step. The rest of
|
||||
|
||||
---
|
||||
|
||||
## acquire
|
||||
|
||||
This method acquires a lock on the given keys. You can optionally pass a provider name to be used for locking.
|
||||
If no provider is passed, the default provider (in-memory or the provider configuerd in `medusa-config.ts`) will be used.
|
||||
|
||||
You can pass an owner for the lock, which limits who can extend or release the acquired lock. Then, if you use this method again
|
||||
passing the same owner, the lock's expiration time is extended with the value passed in the `expire` argument. Otherwise, if you pass a
|
||||
different owner, the method throws an error.
|
||||
|
||||
### Example
|
||||
|
||||
For example, to acquire a lock on a product with ID `prod_123` for a user with ID `user_123`:
|
||||
|
||||
```ts
|
||||
await lockingModuleService.acquire("prod_123", {
|
||||
ownerId: "user_123",
|
||||
expire: 60
|
||||
})
|
||||
```
|
||||
|
||||
In this example, you acquire a lock on the product with ID `prod_123` for the user with ID `user_123`. You extend the
|
||||
lock's expiration time by `60` seconds.
|
||||
|
||||
To specify the provider to use for locking, you can pass the provider name in the `args` argument:
|
||||
|
||||
```ts
|
||||
await lockingModuleService.acquire("prod_123", {
|
||||
ownerId: "user_123",
|
||||
expire: 60,
|
||||
provider: "lp_my-lock"
|
||||
})
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"keys","type":"`string` \\| `string`[]","description":"The keys to acquire the lock on.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"args","type":"`object`","description":"Additional arguments for acquiring the lock.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"ownerId","type":"`null` \\| `string`","description":"The owner ID for the lock. If specified, only the owner can release the lock or extend its expiration time.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"expire","type":"`number`","description":"The expiration time (in seconds) for the lock. If the lock is already acquired and the owner is the same, the expiration time is extended\nby the value passed. If not specified, the lock does not expire.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"provider","type":"`string`","description":"The provider name to use for locking. If no provider is passed, the default provider (in-memory or the provider configuerd in `medusa-config.ts`) will be used.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the lock is acquired.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
___
|
||||
|
||||
## execute
|
||||
|
||||
This method executes a giuven asynchronous job with a lock on the given keys. You can optionally pass a
|
||||
@@ -83,49 +126,6 @@ await lockingModuleService.execute("prod_123", async () => {
|
||||
|
||||
___
|
||||
|
||||
## acquire
|
||||
|
||||
This method acquires a lock on the given keys. You can optionally pass a provider name to be used for locking.
|
||||
If no provider is passed, the default provider (in-memory or the provider configuerd in `medusa-config.ts`) will be used.
|
||||
|
||||
You can pass an owner for the lock, which limits who can extend or release the acquired lock. Then, if you use this method again
|
||||
passing the same owner, the lock's expiration time is extended with the value passed in the `expire` argument. Otherwise, if you pass a
|
||||
different owner, the method throws an error.
|
||||
|
||||
### Example
|
||||
|
||||
For example, to acquire a lock on a product with ID `prod_123` for a user with ID `user_123`:
|
||||
|
||||
```ts
|
||||
await lockingModuleService.acquire("prod_123", {
|
||||
ownerId: "user_123",
|
||||
expire: 60
|
||||
})
|
||||
```
|
||||
|
||||
In this example, you acquire a lock on the product with ID `prod_123` for the user with ID `user_123`. You extend the
|
||||
lock's expiration time by `60` seconds.
|
||||
|
||||
To specify the provider to use for locking, you can pass the provider name in the `args` argument:
|
||||
|
||||
```ts
|
||||
await lockingModuleService.acquire("prod_123", {
|
||||
ownerId: "user_123",
|
||||
expire: 60,
|
||||
provider: "lp_my-lock"
|
||||
})
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"keys","type":"`string` \\| `string`[]","description":"The keys to acquire the lock on.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"args","type":"`object`","description":"Additional arguments for acquiring the lock.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"ownerId","type":"`null` \\| `string`","description":"The owner ID for the lock. If specified, only the owner can release the lock or extend its expiration time.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"expire","type":"`number`","description":"The expiration time (in seconds) for the lock. If the lock is already acquired and the owner is the same, the expiration time is extended\nby the value passed. If not specified, the lock does not expire.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"provider","type":"`string`","description":"The provider name to use for locking. If no provider is passed, the default provider (in-memory or the provider configuerd in `medusa-config.ts`) will be used.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the lock is acquired.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
___
|
||||
|
||||
## release
|
||||
|
||||
This method releases a lock on the given keys. You can optionally pass a provider name to be used for locking.
|
||||
|
||||
+79
-79
@@ -120,6 +120,85 @@ class MyLockingProviderService implements ILockingProvider {
|
||||
}
|
||||
```
|
||||
|
||||
### acquire
|
||||
|
||||
This method acquires a lock on the given keys. The Locking Module uses this method when you call its `acquire` method and your provider is the default provider,
|
||||
or you pass your provider's identifier to its `acquire` method.
|
||||
|
||||
In this method, you should only aquire the lock if the timeout hasn't passed. As explained in the [execute](page.mdx#execute) method's example,
|
||||
you can use a `cancellationToken` object to determine if the lock acquisition has timed out.
|
||||
|
||||
If the lock aquisition isn't canceled, you should aquire the lock, setting its expiry and owner. You should account for the following scenarios:
|
||||
|
||||
- The lock doesn't have an owner and you don't pass an owner, in which case the lock can be extended or released by anyone.
|
||||
- The lock doesn't have an owner or has the same owner that you pass, in which case you can extend the lock's expiration time and set the owner.
|
||||
- The lock has an owner, but you pass a different owner, in which case the method should throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
An example of how to implement the `acquire` method:
|
||||
|
||||
```ts
|
||||
type ResolvablePromise = {
|
||||
promise: Promise<any>
|
||||
resolve: () => void
|
||||
}
|
||||
|
||||
class MyLockingProviderService implements ILockingProvider {
|
||||
// ...
|
||||
async acquire(
|
||||
keys: string | string[],
|
||||
args?: {
|
||||
ownerId?: string | null
|
||||
expire?: number
|
||||
awaitQueue?: boolean
|
||||
}
|
||||
): Promise<void> {
|
||||
return this.acquire_(keys, args)
|
||||
}
|
||||
|
||||
async acquire_(
|
||||
keys: string | string[],
|
||||
args?: {
|
||||
ownerId?: string | null
|
||||
expire?: number
|
||||
awaitQueue?: boolean
|
||||
},
|
||||
cancellationToken?: { cancelled: boolean }
|
||||
): Promise<void> {
|
||||
keys = Array.isArray(keys) ? keys : [keys]
|
||||
const { ownerId, expire } = args ?? {}
|
||||
|
||||
for (const key of keys) {
|
||||
if (cancellationToken?.cancelled) {
|
||||
throw new Error("Timed-out acquiring lock.")
|
||||
}
|
||||
|
||||
// assuming your client has this method and it validates the owner and expiration
|
||||
const result = await this.client.acquireLock(key, ownerId, expire)
|
||||
|
||||
if (result !== 1) {
|
||||
throw new Error(`Failed to acquire lock for key "${key}"`)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, you add a private `acquire_` method that you use to acquire the lock. This method accepts an additional `cancellationToken` argument that you can use to determine if the lock acquisition has timed out.
|
||||
You can then use this method in other methods, such as the `execute` method.
|
||||
|
||||
In the `acquire_` method, you loop through the keys and try to acquire the lock on each key if the lock acquisition hasn't timed out. If the lock acquisition fails, you throw an error.
|
||||
This method assumes that the client you're integrating has a method called `acquireLock` that validates the owner and expiration time, and returns `1` if the lock is successfully acquired.
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"keys","type":"`string` \\| `string`[]","description":"The keys to acquire the lock on.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"args","type":"`object`","description":"Additional arguments for acquiring the lock.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"ownerId","type":"`null` \\| `string`","description":"The ID of the lock's owner. If specified, only the owner can release the lock or extend its expiration time.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"expire","type":"`number`","description":"The expiration time (in seconds) for the lock. If the lock is already acquired and the owner is the same, the expiration time is extended\nby the value passed. If not specified, the lock does not expire.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the lock is acquired.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
### execute
|
||||
|
||||
This method executes a given asynchronous job with a lock on the given keys. The Locking Module uses this method
|
||||
@@ -209,85 +288,6 @@ Finally, if the lock is acquired, you execute the job and release the lock after
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<T>","optional":false,"defaultValue":"","description":"The result of the job.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="execute"/>
|
||||
|
||||
### acquire
|
||||
|
||||
This method acquires a lock on the given keys. The Locking Module uses this method when you call its `acquire` method and your provider is the default provider,
|
||||
or you pass your provider's identifier to its `acquire` method.
|
||||
|
||||
In this method, you should only aquire the lock if the timeout hasn't passed. As explained in the [execute](page.mdx#execute) method's example,
|
||||
you can use a `cancellationToken` object to determine if the lock acquisition has timed out.
|
||||
|
||||
If the lock aquisition isn't canceled, you should aquire the lock, setting its expiry and owner. You should account for the following scenarios:
|
||||
|
||||
- The lock doesn't have an owner and you don't pass an owner, in which case the lock can be extended or released by anyone.
|
||||
- The lock doesn't have an owner or has the same owner that you pass, in which case you can extend the lock's expiration time and set the owner.
|
||||
- The lock has an owner, but you pass a different owner, in which case the method should throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
An example of how to implement the `acquire` method:
|
||||
|
||||
```ts
|
||||
type ResolvablePromise = {
|
||||
promise: Promise<any>
|
||||
resolve: () => void
|
||||
}
|
||||
|
||||
class MyLockingProviderService implements ILockingProvider {
|
||||
// ...
|
||||
async acquire(
|
||||
keys: string | string[],
|
||||
args?: {
|
||||
ownerId?: string | null
|
||||
expire?: number
|
||||
awaitQueue?: boolean
|
||||
}
|
||||
): Promise<void> {
|
||||
return this.acquire_(keys, args)
|
||||
}
|
||||
|
||||
async acquire_(
|
||||
keys: string | string[],
|
||||
args?: {
|
||||
ownerId?: string | null
|
||||
expire?: number
|
||||
awaitQueue?: boolean
|
||||
},
|
||||
cancellationToken?: { cancelled: boolean }
|
||||
): Promise<void> {
|
||||
keys = Array.isArray(keys) ? keys : [keys]
|
||||
const { ownerId, expire } = args ?? {}
|
||||
|
||||
for (const key of keys) {
|
||||
if (cancellationToken?.cancelled) {
|
||||
throw new Error("Timed-out acquiring lock.")
|
||||
}
|
||||
|
||||
// assuming your client has this method and it validates the owner and expiration
|
||||
const result = await this.client.acquireLock(key, ownerId, expire)
|
||||
|
||||
if (result !== 1) {
|
||||
throw new Error(`Failed to acquire lock for key "${key}"`)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, you add a private `acquire_` method that you use to acquire the lock. This method accepts an additional `cancellationToken` argument that you can use to determine if the lock acquisition has timed out.
|
||||
You can then use this method in other methods, such as the `execute` method.
|
||||
|
||||
In the `acquire_` method, you loop through the keys and try to acquire the lock on each key if the lock acquisition hasn't timed out. If the lock acquisition fails, you throw an error.
|
||||
This method assumes that the client you're integrating has a method called `acquireLock` that validates the owner and expiration time, and returns `1` if the lock is successfully acquired.
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"keys","type":"`string` \\| `string`[]","description":"The keys to acquire the lock on.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"args","type":"`object`","description":"Additional arguments for acquiring the lock.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"ownerId","type":"`null` \\| `string`","description":"The ID of the lock's owner. If specified, only the owner can release the lock or extend its expiration time.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"expire","type":"`number`","description":"The expiration time (in seconds) for the lock. If the lock is already acquired and the owner is the same, the expiration time is extended\nby the value passed. If not specified, the lock does not expire.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"`string`","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"`boolean`","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"`boolean`","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves when the lock is acquired.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="acquire"/>
|
||||
|
||||
### release
|
||||
|
||||
This method releases a lock on the given keys. The Locking Module uses this method when you call its `release` method and your provider is the default provider,
|
||||
|
||||
-7
@@ -1,7 +0,0 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# AdminOptions
|
||||
|
||||
Admin dashboard configurations.
|
||||
|
||||
<TypeList types={[{"name":"disable","type":"`boolean`","description":"Whether to disable the admin dashboard. If set to `true`, the admin dashboard is disabled,\nin both development and production environments. The default value is `false`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"path","type":"`/${string}`","description":"The path to the admin dashboard. The default value is `/app`.\n\nThe value cannot be one of the reserved paths:\n- `/admin`\n- `/store`\n- `/auth`\n- `/`\n\n:::note\n\nWhen using Docker, make sure that the root path of the Docker image doesn't path the admin's `path`. For example, if the Docker image's root path is `/app`, change\nthe value of the `path` configuration, as it's `/app` by default.\n\n:::","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"outDir","type":"`string`","description":"The directory where the admin build is outputted when you run the `build` command.\nThe default value is `./build`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"backendUrl","type":"`string`","description":"The URL of your Medusa application. Defaults to the browser origin. This is useful to set when running the admin on a separate domain.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"storefrontUrl","type":"`string`","description":"The URL of your Medusa storefront application. This URL is used as a prefix to some\nlinks in the admin that require performing actions in the storefront. For example,\nthis URL is used as a prefix to shareable payment links for orders with\noutstanding amounts.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"vite","type":"(`config`: `InlineConfig`) => `InlineConfig`","description":"Configure the Vite configuration for the admin dashboard. This function receives the default Vite configuration\nand returns the modified configuration. The default value is `undefined`.\n\nLearn about configurations you can pass to Vite in [Vite's documentation](https://vite.dev/config/).","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="AdminOptions"/>
|
||||
-574
@@ -1,574 +0,0 @@
|
||||
---
|
||||
slug: /references/medusa-config
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# Configure Medusa Backend
|
||||
|
||||
In this document, you’ll learn how to create a file service in the Medusa application and the methods you must implement in it.
|
||||
|
||||
The configurations for your Medusa application are set in `medusa-config.ts` located in the root of your Medusa project. The configurations include configurations for database, modules, and more.
|
||||
|
||||
:::note
|
||||
|
||||
Some Medusa configurations are set through environment variables, which you can find in [this documentation](https://docs.medusajs.com/learn/fundamentals/environment-variables#predefined-medusa-environment-variables).
|
||||
|
||||
:::
|
||||
|
||||
`medusa-config.ts` exports the value returned by the `defineConfig` utility function imported from `@medusajs/framework/utils`.
|
||||
|
||||
`defineConfig` accepts as a parameter an object with the following properties:
|
||||
|
||||
- [projectConfig](page.mdx#projectconfig) (required): An object that holds general configurations related to the Medusa application, such as database or CORS configurations.
|
||||
- [plugins](page.mdx#plugins): An array of strings or objects that hold the configurations of the plugins installed in the Medusa application.
|
||||
- [admin](page.mdx#admin): An object that holds admin-related configurations.
|
||||
- [modules](page.mdx#modules): An object that configures the Medusa application's modules.
|
||||
- [featureFlags](page.mdx#featureflags): An object that enables or disables features guarded by a feature flag.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
// ...
|
||||
},
|
||||
admin: {
|
||||
// ...
|
||||
},
|
||||
modules: {
|
||||
// ...
|
||||
},
|
||||
featureFlags: {
|
||||
// ...
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
It's highly recommended to store the values of configurations in environment variables, then reference them within `medusa-config.ts`.
|
||||
|
||||
During development, you can set your environment variables in the `.env` file at the root of your Medusa application project. In production,
|
||||
setting the environment variables depends on the hosting provider.
|
||||
|
||||
---
|
||||
|
||||
## projectConfig
|
||||
|
||||
This property holds essential configurations related to the Medusa application, such as database and CORS configurations.
|
||||
|
||||
### databaseName
|
||||
|
||||
The name of the database to connect to. If the name is specified in `databaseUrl`, then you don't have to use this configuration.
|
||||
|
||||
Make sure to create the PostgreSQL database before using it. You can check how to create a database in
|
||||
[PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
databaseName: process.env.DATABASE_NAME ||
|
||||
"medusa-store",
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### databaseUrl
|
||||
|
||||
The PostgreSQL connection URL of the database, which is of the following format:
|
||||
|
||||
```bash
|
||||
postgres://[user][:password]@[host][:port]/[dbname]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `[user]`: (required) your PostgreSQL username. If not specified, the system's username is used by default. The database user that you use must have create privileges. If you're using the `postgres` superuser, then it should have these privileges by default. Otherwise, make sure to grant your user create privileges. You can learn how to do that in [PostgreSQL's documentation](https://www.postgresql.org/docs/current/ddl-priv.html).
|
||||
- `[:password]`: an optional password for the user. When provided, make sure to put `:` before the password.
|
||||
- `[host]`: (required) your PostgreSQL host. When run locally, it should be `localhost`.
|
||||
- `[:port]`: an optional port that the PostgreSQL server is listening on. By default, it's `5432`. When provided, make sure to put `:` before the port.
|
||||
- `[dbname]`: (required) the name of the database.
|
||||
|
||||
You can learn more about the connection URL format in [PostgreSQL’s documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
|
||||
|
||||
#### Example
|
||||
|
||||
For example, set the following database URL in your environment variables:
|
||||
|
||||
```bash
|
||||
DATABASE_URL=postgres://postgres@localhost/medusa-store
|
||||
```
|
||||
|
||||
Then, use the value in `medusa-config.ts`:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
databaseUrl: process.env.DATABASE_URL,
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### databaseSchema
|
||||
|
||||
The database schema to connect to. This is not required to provide if you’re using the default schema, which is `public`.
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
databaseSchema: process.env.DATABASE_SCHEMA ||
|
||||
"custom",
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### databaseLogging
|
||||
|
||||
This configuration specifies whether database messages should be logged.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
databaseLogging: false
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### databaseDriverOptions
|
||||
|
||||
This configuration is used to pass additional options to the database connection. You can pass any configuration. For example, pass the
|
||||
`ssl` property that enables support for TLS/SSL connections.
|
||||
|
||||
This is useful for production databases, which can be supported by setting the `rejectUnauthorized` attribute of `ssl` object to `false`.
|
||||
During development, it’s recommended not to pass this option.
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to add to the end of the database URL `?ssl_mode=disable` as well when disabling `rejectUnauthorized`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
databaseDriverOptions: process.env.NODE_ENV !== "development" ?
|
||||
{ connection: { ssl: { rejectUnauthorized: false } } } : {}
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
#### Properties
|
||||
|
||||
<TypeList types={[{"name":"connection","type":"`object`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"ssl","type":"`boolean` \\| `ConnectionOptions`","description":"Configure support for TLS/SSL connection","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="databaseDriverOptions"/>
|
||||
|
||||
### redisUrl
|
||||
|
||||
This configuration specifies the connection URL to Redis to store the Medusa server's session.
|
||||
|
||||
:::note
|
||||
|
||||
You must first have Redis installed. You can refer to [Redis's installation guide](https://redis.io/docs/getting-started/installation/).
|
||||
|
||||
:::
|
||||
|
||||
The Redis connection URL has the following format:
|
||||
|
||||
```bash
|
||||
redis[s]://[[username][:password]@][host][:port][/db-number]
|
||||
```
|
||||
|
||||
For a local Redis installation, the connection URL should be `redis://localhost:6379` unless you’ve made any changes to the Redis configuration during installation.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
redisUrl: process.env.REDIS_URL ||
|
||||
"redis://localhost:6379",
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### redisPrefix
|
||||
|
||||
This configuration defines a prefix on all keys stored in Redis for the Medusa server's session. The default value is `sess:`.
|
||||
|
||||
If this configuration option is provided, it is prepended to `sess:`.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
redisPrefix: process.env.REDIS_URL || "medusa:",
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### redisOptions
|
||||
|
||||
This configuration defines options to pass ioredis for the Redis connection used to store the Medusa server's session. Refer to [ioredis’s RedisOptions documentation](https://redis.github.io/ioredis/index.html#RedisOptions)
|
||||
for the list of available options.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
redisOptions: {
|
||||
connectionName: process.env.REDIS_CONNECTION_NAME ||
|
||||
"medusa",
|
||||
}
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### sessionOptions
|
||||
|
||||
This configuration defines additional options to pass to [express-session](https://www.npmjs.com/package/express-session), which is used to store the Medusa server's session.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
sessionOptions: {
|
||||
name: process.env.SESSION_NAME || "custom",
|
||||
}
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### workerMode
|
||||
|
||||
Configure the application's worker mode.
|
||||
|
||||
Workers are processes running separately from the main application. They're useful for executing long-running or resource-heavy tasks in the background, such as importing products.
|
||||
|
||||
With a worker, these tasks are offloaded to a separate process. So, they won't affect the performance of the main application.
|
||||
|
||||
|
||||
|
||||
Medusa has three runtime modes:
|
||||
|
||||
- Use `shared` to run the application in a single process.
|
||||
- Use `worker` to run the a worker process only.
|
||||
- Use `server` to run the application server only.
|
||||
|
||||
In production, it's recommended to deploy two instances:
|
||||
|
||||
1. One having the `workerMode` configuration set to `server`.
|
||||
2. Another having the `workerMode` configuration set to `worker`.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
workerMode: process.env.WORKER_MODE || "shared"
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### http
|
||||
|
||||
This property configures the application's http-specific settings.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
http: {
|
||||
cookieSecret: "supersecret",
|
||||
compression: {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
#### Properties
|
||||
|
||||
<TypeList types={[{"name":"authCors","type":"`string`","description":"The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.\n\n`cors` is a string used to specify the accepted URLs or patterns for API Routes starting with `/auth`. It can either be one accepted origin, or a comma-separated list of accepted origins.\n\nEvery origin in that list must either be:\n\n1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash;\n2. Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([/~@;%#'])(.*?)\\1([gimsuy]*)$`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"storeCors","type":"`string`","description":"The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.\n\n`store_cors` is a string used to specify the accepted URLs or patterns for store API Routes. It can either be one accepted origin, or a comma-separated list of accepted origins.\n\nEvery origin in that list must either be:\n\n1. A URL. For example, `http://localhost:8000`. The URL must not end with a backslash;\n2. Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that the backend tests for is `^([/~@;%#'])(.*?)\\1([gimsuy]*)$`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"adminCors","type":"`string`","description":"The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.\n\n`admin_cors` is a string used to specify the accepted URLs or patterns for admin API Routes. It can either be one accepted origin, or a comma-separated list of accepted origins.\n\nEvery origin in that list must either be:\n\n1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash;\n2. Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that the backend tests for is `^([/~@;%#'])(.*?)\\1([gimsuy]*)$`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"jwtSecret","type":"`string`","description":"A random string used to create authentication tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.\n\nIn a development environment, if this option is not set the default secret is `supersecret`. However, in production, if this configuration is not set, an\nerror is thrown and the application crashes.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"jwtExpiresIn","type":"`string`","description":"The expiration time for the JWT token. Its format is based off the [ms package](https://github.com/vercel/ms).\n\nIf not provided, the default value is `24h`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"cookieSecret","type":"`string`","description":"A random string used to create cookie tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.\n\nIn a development environment, if this option is not set, the default secret is `supersecret`. However, in production, if this configuration is not set, an error is thrown and\nthe application crashes.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"compression","type":"[HttpCompressionOptions](../medusa_config.HttpCompressionOptions/page.mdx)","description":"Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there.\nHowever, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.\n\nIf you enable HTTP compression and you want to disable it for specific API Routes, you can pass in the request header `\"x-no-compression\": true`.\nLearn more in the [API Reference](https://docs.medusajs.com/api/store#http-compression).","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"enabled","type":"`boolean`","description":"Whether HTTP compression is enabled. By default, it's `false`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"level","type":"`number`","description":"The level of zlib compression to apply to responses. A higher level will result in better compression but will take longer to complete.\nA lower level will result in less compression but will be much faster. The default value is `6`.","optional":true,"defaultValue":"","expandable":false,"childLine truncated
|
||||
|
||||
___
|
||||
|
||||
## admin
|
||||
|
||||
This property holds configurations for the Medusa Admin dashboard.
|
||||
|
||||
### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
backendUrl: process.env.MEDUSA_BACKEND_URL ||
|
||||
"http://localhost:9000"
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### disable
|
||||
|
||||
Whether to disable the admin dashboard. If set to `true`, the admin dashboard is disabled,
|
||||
in both development and production environments. The default value is `false`.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
disable: process.env.ADMIN_DISABLED === "true" ||
|
||||
false
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### path
|
||||
|
||||
The path to the admin dashboard. The default value is `/app`.
|
||||
|
||||
The value cannot be one of the reserved paths:
|
||||
- `/admin`
|
||||
- `/store`
|
||||
- `/auth`
|
||||
- `/`
|
||||
|
||||
:::note
|
||||
|
||||
When using Docker, make sure that the root path of the Docker image doesn't path the admin's `path`. For example, if the Docker image's root path is `/app`, change
|
||||
the value of the `path` configuration, as it's `/app` by default.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
path: process.env.ADMIN_PATH || `/app`,
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### outDir
|
||||
|
||||
The directory where the admin build is outputted when you run the `build` command.
|
||||
The default value is `./build`.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
outDir: process.env.ADMIN_BUILD_DIR || `./build`,
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### backendUrl
|
||||
|
||||
The URL of your Medusa application. Defaults to the browser origin. This is useful to set when running the admin on a separate domain.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
backendUrl: process.env.MEDUSA_BACKEND_URL ||
|
||||
"http://localhost:9000"
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### storefrontUrl
|
||||
|
||||
The URL of your Medusa storefront application. This URL is used as a prefix to some
|
||||
links in the admin that require performing actions in the storefront. For example,
|
||||
this URL is used as a prefix to shareable payment links for orders with
|
||||
outstanding amounts.
|
||||
|
||||
#### Example
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
storefrontUrl: process.env.MEDUSA_STOREFRONT_URL ||
|
||||
"http://localhost:8000"
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### vite
|
||||
|
||||
Configure the Vite configuration for the admin dashboard. This function receives the default Vite configuration
|
||||
and returns the modified configuration. The default value is `undefined`.
|
||||
|
||||
Learn about configurations you can pass to Vite in [Vite's documentation](https://vite.dev/config/).
|
||||
|
||||
#### Example
|
||||
|
||||
For example, if you're using a third-party library that isn't ESM-compatible, add it to Vite's `optimizeDeps` configuration:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
admin: {
|
||||
vite: () => {
|
||||
return {
|
||||
optimizeDeps: {
|
||||
include: ["qs"],
|
||||
},
|
||||
};
|
||||
},
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
___
|
||||
|
||||
## plugins
|
||||
|
||||
On your Medusa server, you can use [Plugins](https://docs.medusajs.com/learn/fundamentals/plugins) to add re-usable Medusa customizations. Plugins
|
||||
can include modules, workflows, API Routes, and other customizations. Plugins are available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).
|
||||
|
||||
Aside from installing the plugin with NPM, you need to pass the plugin you installed into the `plugins` array defined in `medusa-config.ts`.
|
||||
|
||||
The items in the array can either be:
|
||||
|
||||
- A string, which is the name of the plugin's package as specified in the plugin's `package.json` file. You can pass a plugin as a string if it doesn’t require any options.
|
||||
- An object having the following properties:
|
||||
- `resolve`: The name of the plugin's package as specified in the plugin's `package.json` file.
|
||||
- `options`: An object that includes options to be passed to the modules within the plugin. Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/modules/options).
|
||||
|
||||
Learn how to create a plugin in [this documentation](https://docs.medusajs.com/learn/fundamentals/plugins/create).
|
||||
|
||||
### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
`medusa-my-plugin-1`,
|
||||
{
|
||||
resolve: `medusa-my-plugin`,
|
||||
options: {
|
||||
apiKey: process.env.MY_API_KEY ||
|
||||
`test`,
|
||||
},
|
||||
},
|
||||
// ...
|
||||
],
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### resolve
|
||||
|
||||
The name of the plugin's package as specified in the plugin's `package.json` file.
|
||||
|
||||
### options
|
||||
|
||||
An object that includes options to be passed to the modules within the plugin.
|
||||
Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/modules/options).
|
||||
|
||||
___
|
||||
|
||||
## modules
|
||||
|
||||
This property holds all custom modules installed in your Medusa application.
|
||||
|
||||
:::note
|
||||
|
||||
Medusa's Commerce Modules are configured by default, so only
|
||||
add them to this property if you're changing their configurations or adding providers to a module.
|
||||
|
||||
:::
|
||||
|
||||
`modules` is an array of objects, each holding a module's registration configurations. Each object has the following properties:
|
||||
|
||||
1. `resolve`: a string indicating the path to the module relative to `src`, or the module's NPM package name. For example, `./modules/my-module`.
|
||||
2. `options`: (optional) an object indicating the options to pass to the module.
|
||||
|
||||
### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
modules: [
|
||||
{
|
||||
resolve: "./modules/hello"
|
||||
}
|
||||
]
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
___
|
||||
|
||||
## featureFlags
|
||||
|
||||
Some features in the Medusa application are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability.
|
||||
|
||||
You can enable a feature in your application by enabling its feature flag. Feature flags are enabled through either environment
|
||||
variables or through this configuration property exported in `medusa-config.ts`.
|
||||
|
||||
The `featureFlags`'s value is an object. Its properties are the names of the feature flags, and their value is a boolean indicating whether the feature flag is enabled.
|
||||
|
||||
You can find available feature flags and their key name [here](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags).
|
||||
|
||||
### Example
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
featureFlags: {
|
||||
analytics: true,
|
||||
// ...
|
||||
}
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
After enabling a feature flag, make sure to run migrations as it may require making changes to the database.
|
||||
|
||||
:::
|
||||
-7
@@ -1,7 +0,0 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# HttpCompressionOptions
|
||||
|
||||
HTTP compression configurations.
|
||||
|
||||
<TypeList types={[{"name":"enabled","type":"`boolean`","description":"Whether HTTP compression is enabled. By default, it's `false`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"level","type":"`number`","description":"The level of zlib compression to apply to responses. A higher level will result in better compression but will take longer to complete.\nA lower level will result in less compression but will be much faster. The default value is `6`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"memLevel","type":"`number`","description":"How much memory should be allocated to the internal compression state. It's an integer in the range of 1 (minimum level) and 9 (maximum level).\nThe default value is `8`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"threshold","type":"`string` \\| `number`","description":"The minimum response body size that compression is applied on. Its value can be the number of bytes or any string accepted by the\n[bytes](https://www.npmjs.com/package/bytes) module. The default value is `1024`.","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="HttpCompressionOptions"/>
|
||||
-7
@@ -1,7 +0,0 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# ProjectConfigOptions
|
||||
|
||||
Essential configurations related to the Medusa application, such as database and CORS configurations.
|
||||
|
||||
<TypeList types={[{"name":"http","type":"`object`","description":"This property configures the application's http-specific settings.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"authCors","type":"`string`","description":"The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.\n\n`cors` is a string used to specify the accepted URLs or patterns for API Routes starting with `/auth`. It can either be one accepted origin, or a comma-separated list of accepted origins.\n\nEvery origin in that list must either be:\n\n1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash;\n2. Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that Medusa tests for is `^([/~@;%#'])(.*?)\\1([gimsuy]*)$`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"storeCors","type":"`string`","description":"The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.\n\n`store_cors` is a string used to specify the accepted URLs or patterns for store API Routes. It can either be one accepted origin, or a comma-separated list of accepted origins.\n\nEvery origin in that list must either be:\n\n1. A URL. For example, `http://localhost:8000`. The URL must not end with a backslash;\n2. Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that the backend tests for is `^([/~@;%#'])(.*?)\\1([gimsuy]*)$`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"adminCors","type":"`string`","description":"The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.\n\n`admin_cors` is a string used to specify the accepted URLs or patterns for admin API Routes. It can either be one accepted origin, or a comma-separated list of accepted origins.\n\nEvery origin in that list must either be:\n\n1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash;\n2. Or a regular expression pattern that can match more than one origin. For example, `.example.com`. The regex pattern that the backend tests for is `^([/~@;%#'])(.*?)\\1([gimsuy]*)$`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"jwtSecret","type":"`string`","description":"A random string used to create authentication tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.\n\nIn a development environment, if this option is not set the default secret is `supersecret`. However, in production, if this configuration is not set, an\nerror is thrown and the application crashes.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"jwtExpiresIn","type":"`string`","description":"The expiration time for the JWT token. Its format is based off the [ms package](https://github.com/vercel/ms).\n\nIf not provided, the default value is `24h`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"cookieSecret","type":"`string`","description":"A random string used to create cookie tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.\n\nIn a development environment, if this option is not set, the default secret is `supersecret`. However, in production, if this configuration is not set, an error is thrown and\nthe application crashes.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"compression","type":"[HttpCompressionOptions](../medusa_config.HttpCompressionOptions/page.mdx)","description":"Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there.\nHowever, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.\n\nIf you enable HTTP compression and you want to disable it for specific API Routes, you can pass in the request header `\"x-no-compression\": true`.\nLearn more in the [API Reference](https://docs.medusajs.com/api/store#http-compression).","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"enabled","type":"`boolean`","description":"Whether HTTP compression is enabled. By default, it's `false`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"level","type":"`number`","description":"The level of zlib compression to apply to responses. A higher level will result in better compression but will tLine truncated
|
||||
@@ -1,7 +0,0 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# PluginDetails
|
||||
|
||||
**PluginDetails**: `Object`
|
||||
|
||||
<TypeList types={[{"name":"resolve","type":"`string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"id","type":"`string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, unknown>`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"version","type":"`string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="PluginDetails"/>
|
||||
@@ -1,14 +0,0 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# medusa-config
|
||||
|
||||
## Interfaces
|
||||
|
||||
- [AdminOptions](../../medusa_config/interfaces/medusa_config.AdminOptions/page.mdx)
|
||||
- [ConfigModule](../../medusa_config/interfaces/medusa_config.ConfigModule/page.mdx)
|
||||
- [HttpCompressionOptions](../../medusa_config/interfaces/medusa_config.HttpCompressionOptions/page.mdx)
|
||||
- [ProjectConfigOptions](../../medusa_config/interfaces/medusa_config.ProjectConfigOptions/page.mdx)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
- [PluginDetails](../../medusa_config/types/medusa_config.PluginDetails/page.mdx)
|
||||
@@ -1,7 +0,0 @@
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# search
|
||||
|
||||
## Classes
|
||||
|
||||
- [AbstractSearchService](../../search/classes/search.AbstractSearchService/page.mdx)
|
||||
+49
-49
@@ -98,20 +98,22 @@ const notification = await notificationModuleService.createNotifications({
|
||||
|
||||
___
|
||||
|
||||
## retrieveNotification
|
||||
## listAndCountNotifications
|
||||
|
||||
This method is used to retrieve a notification by its ID
|
||||
This method is used to retrieve a paginated list of notifications along with the total count of available notifications satisfying the provided filters.
|
||||
|
||||
### Example
|
||||
|
||||
A simple example that retrieves a notification by its ID:
|
||||
To retrieve a list of notifications using their IDs:
|
||||
|
||||
```ts
|
||||
const notification =
|
||||
await notificationModuleService.retrieveNotification("noti_123")
|
||||
const [notifications, count] =
|
||||
await notificationModuleService.listAndCountNotifications({
|
||||
id: ["noti_123", "noti_321"],
|
||||
})
|
||||
```
|
||||
|
||||
To specify relations that should be retrieved:
|
||||
To specify relations that should be retrieved within the notifications:
|
||||
|
||||
:::note
|
||||
|
||||
@@ -121,21 +123,40 @@ from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/mod
|
||||
:::
|
||||
|
||||
```ts
|
||||
const notification = await notificationModuleService.retrieveNotification(
|
||||
"noti_123",
|
||||
{
|
||||
relations: ["provider"],
|
||||
}
|
||||
)
|
||||
const [notifications, count] =
|
||||
await notificationModuleService.listAndCountNotifications(
|
||||
{
|
||||
id: ["noti_123", "noti_321"],
|
||||
},
|
||||
{
|
||||
relations: ["provider"],
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
|
||||
|
||||
```ts
|
||||
const [notifications, count] =
|
||||
await notificationModuleService.listAndCountNotifications(
|
||||
{
|
||||
id: ["noti_123", "noti_321"],
|
||||
},
|
||||
{
|
||||
relations: ["provider"],
|
||||
take: 20,
|
||||
skip: 2,
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"notificationId","type":"`string`","description":"The ID of the notification to retrieve.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"[FindConfig](../../../medusa/interfaces/medusa.FindConfig/page.mdx)<[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)>","description":"The configurations determining how the notification is retrieved. Its properties, such as `select` or `relations`, accept the\nattributes or relations associated with a notification.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \\| `string` & `object`)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"`null` \\| `number`","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"`null` \\| `number`","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`string`[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[FindConfigOrder](../../../medusa/types/medusa.FindConfigOrder/page.mdx)","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`\nto sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"`boolean`","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\n`SoftDeletableEntity` class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"`Record<string, any>`","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"chilLine truncated
|
||||
<TypeList types={[{"name":"filters","type":"[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)","description":"The filters to apply on the retrieved notifications.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"$and","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)>)[]","description":"An array of filters to apply on the entity, where each item in the array is joined with an \"and\" condition.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"$and","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)>)[]","description":"An array of filters to apply on the entity, where each item in the array is joined with an \"and\" condition.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"$or","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)>)[]","description":"An array of filters to apply on the entity, where each item in the array is joined with an \"or\" condition.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"q","type":"`string`","description":"Search through the notifications' attributes, such as trigger types and recipients, using this search term.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"to","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the recipient of the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"channel","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the channel through which the notification is sent, such as 'email' or 'sms'","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"template","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the template name.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"trigger_type","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the trigger type.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_id","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the resource that was the trigger for the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_type","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"T* Filter based on the resource type that was the trigger for the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"receiver_id","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the customer ID.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"[OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string>","description":"Filters a notification based on when it was sent and created in the database","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"$or","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotifLine truncated
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)>","optional":false,"defaultValue":"","description":"The retrieved notification.","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the notification.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"to","type":"`string`","description":"The recipient of the notification. It can be email, phone number, or username, depending on the channel.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"channel","type":"`string`","description":"The channel through which the notification is sent, such as 'email' or 'sms'","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"template","type":"`string`","description":"The template name in the provider's system.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`null` \\| `Record<string, unknown>`","description":"The data that gets passed over to the provider for rendering the notification.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider_id","type":"`string`","description":"The ID of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider","type":"[NotificationProviderDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationProviderDTO/page.mdx)","description":"Information about the notification provider","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"handle","type":"`string`","description":"The handle of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"A user-friendly name of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"channels","type":"`string`[]","description":"The supported channels by the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"created_at","type":"`Date`","description":"The date and time the notification was created.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"status","type":"`\"pending\"` \\| `\"success\"` \\| `\"failure\"`","description":"The status of the notification","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"from","type":"`null` \\| `string`","description":"The sender of the notification. It can be email, phone number, or username, depending on the channel.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"attachments","type":"`null` \\| [Attachment](../../../types/NotificationTypes/interfaces/types.NotificationTypes.Attachment/page.mdx)[]","description":"Optional attachments for the notification.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"content","type":"`string`","description":"The content of the attachment, encoded as a base64 string.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"filename","type":"`string`","description":"The filename of the attachment.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"content_type","type":"`string`","description":"The MIME type of the attachment.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"disposition","type":"`string`","description":"The disposition of the attachment, For example, \"inline\" or \"attachment\".","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"id","type":"`string`","description":"The ID, if the attachment is meant to be referenced within the body of the message.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"trigger_type","type":"`null` \\| `string`","description":"The event name, the workflow, or anything else that can help to identify what triggered the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_id","type":"`null` \\| `string`","description":"The ID of the resource this notification is for, if applicable. Useful for displaying relevant information in the UI","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_type","type":"`null` \\| `string`","description":"The type of the resource this notification is for, if applicable, eg. \"order\"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"receiver_id","type":"`null` \\| `string`","description":"The ID of the customer this notification is for, if applicable.","optional":true,"defaultValue":"","expandable":false,"chLine truncated
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)[], number]>","optional":false,"defaultValue":"","description":"The list of notifications along with the total count.","expandable":false,"children":[{"name":"NotificationDTO[]","type":"[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"number","type":"`number`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="listAndCountNotifications"/>
|
||||
|
||||
___
|
||||
|
||||
@@ -198,22 +219,20 @@ const notifications = await notificationModuleService.listNotifications(
|
||||
|
||||
___
|
||||
|
||||
## listAndCountNotifications
|
||||
## retrieveNotification
|
||||
|
||||
This method is used to retrieve a paginated list of notifications along with the total count of available notifications satisfying the provided filters.
|
||||
This method is used to retrieve a notification by its ID
|
||||
|
||||
### Example
|
||||
|
||||
To retrieve a list of notifications using their IDs:
|
||||
A simple example that retrieves a notification by its ID:
|
||||
|
||||
```ts
|
||||
const [notifications, count] =
|
||||
await notificationModuleService.listAndCountNotifications({
|
||||
id: ["noti_123", "noti_321"],
|
||||
})
|
||||
const notification =
|
||||
await notificationModuleService.retrieveNotification("noti_123")
|
||||
```
|
||||
|
||||
To specify relations that should be retrieved within the notifications:
|
||||
To specify relations that should be retrieved:
|
||||
|
||||
:::note
|
||||
|
||||
@@ -223,37 +242,18 @@ from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/mod
|
||||
:::
|
||||
|
||||
```ts
|
||||
const [notifications, count] =
|
||||
await notificationModuleService.listAndCountNotifications(
|
||||
{
|
||||
id: ["noti_123", "noti_321"],
|
||||
},
|
||||
{
|
||||
relations: ["provider"],
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
|
||||
|
||||
```ts
|
||||
const [notifications, count] =
|
||||
await notificationModuleService.listAndCountNotifications(
|
||||
{
|
||||
id: ["noti_123", "noti_321"],
|
||||
},
|
||||
{
|
||||
relations: ["provider"],
|
||||
take: 20,
|
||||
skip: 2,
|
||||
}
|
||||
)
|
||||
const notification = await notificationModuleService.retrieveNotification(
|
||||
"noti_123",
|
||||
{
|
||||
relations: ["provider"],
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"filters","type":"[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)","description":"The filters to apply on the retrieved notifications.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"$and","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)>)[]","description":"An array of filters to apply on the entity, where each item in the array is joined with an \"and\" condition.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"$and","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)>)[]","description":"An array of filters to apply on the entity, where each item in the array is joined with an \"and\" condition.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"$or","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx)>)[]","description":"An array of filters to apply on the entity, where each item in the array is joined with an \"or\" condition.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"q","type":"`string`","description":"Search through the notifications' attributes, such as trigger types and recipients, using this search term.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"to","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the recipient of the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"channel","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the channel through which the notification is sent, such as 'email' or 'sms'","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"template","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the template name.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"trigger_type","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the trigger type.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_id","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the resource that was the trigger for the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_type","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"T* Filter based on the resource type that was the trigger for the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"receiver_id","type":"`string` \\| `string`[] \\| [OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string \\| string[]>","description":"Filter based on the customer ID.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"[OperatorMap](../../../types/DAL/types/types.DAL.OperatorMap/page.mdx)<string>","description":"Filters a notification based on when it was sent and created in the database","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"$or","type":"([FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotificationTypes.FilterableNotificationProps/page.mdx) \\| [BaseFilterable](../../../types/DAL/interfaces/types.DAL.BaseFilterable/page.mdx)<[FilterableNotificationProps](../../../types/NotificationTypes/interfaces/types.NotifLine truncated
|
||||
<TypeList types={[{"name":"notificationId","type":"`string`","description":"The ID of the notification to retrieve.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"[FindConfig](../../../medusa/interfaces/medusa.FindConfig/page.mdx)<[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)>","description":"The configurations determining how the notification is retrieved. Its properties, such as `select` or `relations`, accept the\nattributes or relations associated with a notification.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \\| `string` & `object`)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"`null` \\| `number`","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"`null` \\| `number`","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"`string`[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[FindConfigOrder](../../../medusa/types/medusa.FindConfigOrder/page.mdx)","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`\nto sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"`boolean`","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\n`SoftDeletableEntity` class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"`Record<string, any>`","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"[Context](../../../types/interfaces/types.Context/page.mdx)","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"`string`","description":"A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"`boolean`","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"`string`","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"`string`","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"[IMessageAggregator](../../../types/interfaces/types.IMessageAggregator/page.mdx)","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"`string`","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"chilLine truncated
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)[], number]>","optional":false,"defaultValue":"","description":"The list of notifications along with the total count.","expandable":false,"children":[{"name":"NotificationDTO[]","type":"[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"number","type":"`number`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="listAndCountNotifications"/>
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[NotificationDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationDTO/page.mdx)>","optional":false,"defaultValue":"","description":"The retrieved notification.","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the notification.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"to","type":"`string`","description":"The recipient of the notification. It can be email, phone number, or username, depending on the channel.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"channel","type":"`string`","description":"The channel through which the notification is sent, such as 'email' or 'sms'","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"template","type":"`string`","description":"The template name in the provider's system.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`null` \\| `Record<string, unknown>`","description":"The data that gets passed over to the provider for rendering the notification.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider_id","type":"`string`","description":"The ID of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"provider","type":"[NotificationProviderDTO](../../../types/NotificationTypes/interfaces/types.NotificationTypes.NotificationProviderDTO/page.mdx)","description":"Information about the notification provider","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"handle","type":"`string`","description":"The handle of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"A user-friendly name of the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"channels","type":"`string`[]","description":"The supported channels by the notification provider.","optional":false,"defaultValue":"","expandable":false,"children":[]}]},{"name":"created_at","type":"`Date`","description":"The date and time the notification was created.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"status","type":"`\"pending\"` \\| `\"success\"` \\| `\"failure\"`","description":"The status of the notification","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"from","type":"`null` \\| `string`","description":"The sender of the notification. It can be email, phone number, or username, depending on the channel.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"attachments","type":"`null` \\| [Attachment](../../../types/NotificationTypes/interfaces/types.NotificationTypes.Attachment/page.mdx)[]","description":"Optional attachments for the notification.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"content","type":"`string`","description":"The content of the attachment, encoded as a base64 string.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"filename","type":"`string`","description":"The filename of the attachment.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"content_type","type":"`string`","description":"The MIME type of the attachment.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"disposition","type":"`string`","description":"The disposition of the attachment, For example, \"inline\" or \"attachment\".","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"id","type":"`string`","description":"The ID, if the attachment is meant to be referenced within the body of the message.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"trigger_type","type":"`null` \\| `string`","description":"The event name, the workflow, or anything else that can help to identify what triggered the notification.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_id","type":"`null` \\| `string`","description":"The ID of the resource this notification is for, if applicable. Useful for displaying relevant information in the UI","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"resource_type","type":"`null` \\| `string`","description":"The type of the resource this notification is for, if applicable, eg. \"order\"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"receiver_id","type":"`null` \\| `string`","description":"The ID of the customer this notification is for, if applicable.","optional":true,"defaultValue":"","expandable":false,"chLine truncated
|
||||
+525
-223
@@ -144,75 +144,6 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
}
|
||||
```
|
||||
|
||||
### validateOptions
|
||||
|
||||
This method validates the options of the provider set in `medusa-config.ts`.
|
||||
Implementing this method is optional. It's useful if your provider requires custom validation.
|
||||
|
||||
If the options aren't valid, throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<Options> {
|
||||
static validateOptions(options: Record<any, any>) {
|
||||
if (!options.apiKey) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"API key is required in the provider's options."
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
|
||||
|
||||
### capturePayment
|
||||
|
||||
This method is used to capture a payment. The payment is captured in one of the following scenarios:
|
||||
|
||||
- The [authorizePayment](page.mdx#authorizepayment) method returns the status `captured`, which automatically executed this method after authorization.
|
||||
- The merchant requests to capture the payment after its associated payment session was authorized.
|
||||
- A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in [this guide](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events).
|
||||
|
||||
In this method, use the third-party provider to capture the payment.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
CapturePaymentInput,
|
||||
CapturePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async capturePayment(
|
||||
input: CapturePaymentInput
|
||||
): Promise<CapturePaymentOutput> {
|
||||
const externalId = input.data?.id
|
||||
|
||||
// assuming you have a client that captures the payment
|
||||
const newData = await this.client.capturePayment(externalId)
|
||||
return {data: newData}
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[CapturePaymentInput](../../../types/interfaces/types.CapturePaymentInput/page.mdx)","description":"The input to capture the payment. The `data` field should contain the data from the payment provider. when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="capturePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CapturePaymentOutput](../../../types/interfaces/types.CapturePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="capturePayment"/>
|
||||
|
||||
### authorizePayment
|
||||
|
||||
This method authorizes a payment session. When authorized successfully, a payment is created by the Payment
|
||||
@@ -300,54 +231,170 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CancelPaymentOutput](../../../types/interfaces/types.CancelPaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property, if any. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="cancelPayment"/>
|
||||
|
||||
### initiatePayment
|
||||
### capturePayment
|
||||
|
||||
This method is used when a payment session is created. It can be used to initiate the payment
|
||||
in the third-party session, before authorizing or capturing the payment later.
|
||||
This method is used to capture a payment. The payment is captured in one of the following scenarios:
|
||||
|
||||
- The [authorizePayment](page.mdx#authorizepayment) method returns the status `captured`, which automatically executed this method after authorization.
|
||||
- The merchant requests to capture the payment after its associated payment session was authorized.
|
||||
- A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in [this guide](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events).
|
||||
|
||||
In this method, use the third-party provider to capture the payment.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
InitiatePaymentInput,
|
||||
InitiatePaymentOutput,
|
||||
CapturePaymentInput,
|
||||
CapturePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async initiatePayment(
|
||||
input: InitiatePaymentInput
|
||||
): Promise<InitiatePaymentOutput> {
|
||||
const {
|
||||
amount,
|
||||
currency_code,
|
||||
context: customerDetails
|
||||
} = input
|
||||
async capturePayment(
|
||||
input: CapturePaymentInput
|
||||
): Promise<CapturePaymentOutput> {
|
||||
const externalId = input.data?.id
|
||||
|
||||
// assuming you have a client that initializes the payment
|
||||
const response = await this.client.init(
|
||||
amount, currency_code, customerDetails
|
||||
)
|
||||
|
||||
return {
|
||||
id: response.id,
|
||||
data: response,
|
||||
}
|
||||
// assuming you have a client that captures the payment
|
||||
const newData = await this.client.capturePayment(externalId)
|
||||
return {data: newData}
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[InitiatePaymentInput](../../../types/interfaces/types.InitiatePaymentInput/page.mdx)","description":"The input to create the payment session.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"[BigNumberInput](../../../types/types/types.BigNumberInput/page.mdx)","description":"The amount to be authorized.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The ISO 3 character currency code.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="initiatePayment"/>
|
||||
<TypeList types={[{"name":"input","type":"[CapturePaymentInput](../../../types/interfaces/types.CapturePaymentInput/page.mdx)","description":"The input to capture the payment. The `data` field should contain the data from the payment provider. when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="capturePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[InitiatePaymentOutput](../../../types/interfaces/types.InitiatePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="initiatePayment"/>
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CapturePaymentOutput](../../../types/interfaces/types.CapturePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="capturePayment"/>
|
||||
|
||||
### createAccountHolder
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used when creating an account holder in Medusa, allowing you to create
|
||||
the equivalent account in the third-party service. An account holder is useful to
|
||||
later save payment methods, such as credit cards, for a customer in the
|
||||
third-party payment provider using the [savePaymentMethod](../../../types/interfaces/types.IPaymentProvider/page.mdx#savepaymentmethod) method.
|
||||
|
||||
The returned data will be stored in the account holder created in Medusa. For example,
|
||||
the returned `id` property will be stored in the account holder's `external_id` property.
|
||||
|
||||
Medusa creates an account holder when a payment session initialized for a registered customer.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.5.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
import { MedusaError } from "@medusajs/framework/utils"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async createAccountHolder({ context, data }: CreateAccountHolderInput) {
|
||||
const { account_holder, customer } = context
|
||||
|
||||
if (account_holder?.data?.id) {
|
||||
return { id: account_holder.data.id as string }
|
||||
}
|
||||
|
||||
if (!customer) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"Missing customer data."
|
||||
)
|
||||
}
|
||||
|
||||
// assuming you have a client that creates the account holder
|
||||
const providerAccountHolder = await this.client.createAccountHolder({
|
||||
email: customer.email,
|
||||
...data
|
||||
})
|
||||
|
||||
return {
|
||||
id: providerAccountHolder.id,
|
||||
data: providerAccountHolder as unknown as Record<string, unknown>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[CreateAccountHolderInput](../../../types/interfaces/types.CreateAccountHolderInput/page.mdx)","description":"Input data including the details of the account holder to create.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"context","type":"Omit<[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx), \"customer\"> & `object`","description":"The context of creating the account holder.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="createAccountHolder"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[CreateAccountHolderOutput](../../../types/interfaces/types.CreateAccountHolderOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The result of creating the account holder. If an error occurs, throw it.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="createAccountHolder"/>
|
||||
|
||||
### deleteAccountHolder
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used when an account holder is deleted in Medusa, allowing you
|
||||
to also delete the equivalent account holder in the third-party service.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.5.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
import { MedusaError } from "@medusajs/framework/utils"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async deleteAccountHolder({ context }: DeleteAccountHolderInput) {
|
||||
const { account_holder } = context
|
||||
const accountHolderId = account_holder?.data?.id as string | undefined
|
||||
if (!accountHolderId) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"Missing account holder ID."
|
||||
)
|
||||
}
|
||||
|
||||
// assuming you have a client that deletes the account holder
|
||||
await this.client.deleteAccountHolder({
|
||||
id: accountHolderId
|
||||
})
|
||||
|
||||
return {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[DeleteAccountHolderInput](../../../types/interfaces/types.DeleteAccountHolderInput/page.mdx)","description":"Input data including the details of the account holder to delete.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"context","type":"Omit<[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx), \"account_holder\"> & `object`","description":"The context of deleting the account holder.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteAccountHolder"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[DeleteAccountHolderOutput](../../../types/interfaces/types.DeleteAccountHolderOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The result of deleting the account holder. If an error occurs, throw it.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteAccountHolder"/>
|
||||
|
||||
### deletePayment
|
||||
|
||||
@@ -438,135 +485,6 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[GetPaymentStatusOutput](../../../types/interfaces/types.GetPaymentStatusOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The payment session's status. It can also return additional `data` from the payment provider.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getPaymentStatus"/>
|
||||
|
||||
### refundPayment
|
||||
|
||||
This method refunds an amount of a payment previously captured.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
RefundPaymentInput,
|
||||
RefundPaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async refundPayment(
|
||||
input: RefundPaymentInput
|
||||
): Promise<RefundPaymentOutput> {
|
||||
const externalId = input.data?.id
|
||||
|
||||
// assuming you have a client that refunds the payment
|
||||
const newData = await this.client.refund(
|
||||
externalId,
|
||||
input.amount
|
||||
)
|
||||
|
||||
return {data: newData}
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[RefundPaymentInput](../../../types/interfaces/types.RefundPaymentInput/page.mdx)","description":"The input to refund the payment. The `data` field should contain the data from the payment provider. when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"[BigNumberInput](../../../types/types/types.BigNumberInput/page.mdx)","description":"The amount to refund.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="refundPayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[RefundPaymentOutput](../../../types/interfaces/types.RefundPaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property, or an error object.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="refundPayment"/>
|
||||
|
||||
### retrievePayment
|
||||
|
||||
Retrieves the payment's data from the third-party service.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
RetrievePaymentInput,
|
||||
RetrievePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async retrievePayment(
|
||||
input: RetrievePaymentInput
|
||||
): Promise<RetrievePaymentOutput> {
|
||||
const externalId = input.data?.id
|
||||
|
||||
// assuming you have a client that retrieves the payment
|
||||
return await this.client.retrieve(externalId)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[RetrievePaymentInput](../../../types/interfaces/types.RetrievePaymentInput/page.mdx)","description":"The input to retrieve the payment. The `data` field should contain the data from the payment provider when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrievePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[RetrievePaymentOutput](../../../types/interfaces/types.RetrievePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The payment's data as found in the the payment provider.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrievePayment"/>
|
||||
|
||||
### updatePayment
|
||||
|
||||
Update a payment in the third-party service that was previously initiated with the [initiatePayment](page.mdx#initiatepayment) method.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
UpdatePaymentInput,
|
||||
UpdatePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async updatePayment(
|
||||
input: UpdatePaymentInput
|
||||
): Promise<UpdatePaymentOutput> {
|
||||
const { amount, currency_code, context } = input
|
||||
const externalId = input.data?.id
|
||||
|
||||
// Validate context.customer
|
||||
if (!context || !context.customer) {
|
||||
throw new Error("Context must include a valid customer.");
|
||||
}
|
||||
|
||||
// assuming you have a client that updates the payment
|
||||
const response = await this.client.update(
|
||||
externalId,
|
||||
{
|
||||
amount,
|
||||
currency_code,
|
||||
context.customer
|
||||
}
|
||||
)
|
||||
|
||||
return response
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[UpdatePaymentInput](../../../types/interfaces/types.UpdatePaymentInput/page.mdx)","description":"The input to update the payment. The `data` field should contain the data from the payment provider. when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"[BigNumberInput](../../../types/types/types.BigNumberInput/page.mdx)","description":"The payment session's amount.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The ISO 3 character code of the payment session.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updatePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[UpdatePaymentOutput](../../../types/interfaces/types.UpdatePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updatePayment"/>
|
||||
|
||||
### getWebhookActionAndData
|
||||
|
||||
This method is executed when a webhook event is received from the third-party payment provider. Use it
|
||||
@@ -644,6 +562,390 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[WebhookActionResult](../../../types/interfaces/types.WebhookActionResult/page.mdx)>","optional":false,"defaultValue":"","description":"The webhook result. If the `action`'s value is `captured`, the payment is captured within Medusa as well.\nIf the `action`'s value is `authorized`, the associated payment session is authorized within Medusa.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getWebhookActionAndData"/>
|
||||
|
||||
### initiatePayment
|
||||
|
||||
This method is used when a payment session is created. It can be used to initiate the payment
|
||||
in the third-party session, before authorizing or capturing the payment later.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
InitiatePaymentInput,
|
||||
InitiatePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async initiatePayment(
|
||||
input: InitiatePaymentInput
|
||||
): Promise<InitiatePaymentOutput> {
|
||||
const {
|
||||
amount,
|
||||
currency_code,
|
||||
context: customerDetails
|
||||
} = input
|
||||
|
||||
// assuming you have a client that initializes the payment
|
||||
const response = await this.client.init(
|
||||
amount, currency_code, customerDetails
|
||||
)
|
||||
|
||||
return {
|
||||
id: response.id,
|
||||
data: response,
|
||||
}
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[InitiatePaymentInput](../../../types/interfaces/types.InitiatePaymentInput/page.mdx)","description":"The input to create the payment session.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"[BigNumberInput](../../../types/types/types.BigNumberInput/page.mdx)","description":"The amount to be authorized.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The ISO 3 character currency code.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="initiatePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[InitiatePaymentOutput](../../../types/interfaces/types.InitiatePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="initiatePayment"/>
|
||||
|
||||
### listPaymentMethods
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used to retrieve the list of saved payment methods for an account holder
|
||||
in the third-party payment provider. A payment provider that supports saving payment methods
|
||||
must implement this method.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.5.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
import { MedusaError } from "@medusajs/framework/utils"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async listPaymentMethods({ context }: ListPaymentMethodsInput) {
|
||||
const { account_holder } = context
|
||||
const accountHolderId = account_holder?.data?.id as string | undefined
|
||||
|
||||
if (!accountHolderId) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"Missing account holder ID."
|
||||
)
|
||||
}
|
||||
|
||||
// assuming you have a client that lists the payment methods
|
||||
const paymentMethods = await this.client.listPaymentMethods({
|
||||
customer_id: accountHolderId
|
||||
})
|
||||
|
||||
return paymentMethods.map((pm) => ({
|
||||
id: pm.id,
|
||||
data: pm as unknown as Record<string, unknown>
|
||||
}))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[ListPaymentMethodsInput](../../../types/interfaces/types.ListPaymentMethodsInput/page.mdx)","description":"Input data including the details of the account holder to list payment methods for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="listPaymentMethods"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[ListPaymentMethodsOutput](../../../types/interfaces/types.ListPaymentMethodsOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The list of payment methods saved for the account holder. If an error occurs, throw it.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="listPaymentMethods"/>
|
||||
|
||||
### refundPayment
|
||||
|
||||
This method refunds an amount of a payment previously captured.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
RefundPaymentInput,
|
||||
RefundPaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async refundPayment(
|
||||
input: RefundPaymentInput
|
||||
): Promise<RefundPaymentOutput> {
|
||||
const externalId = input.data?.id
|
||||
|
||||
// assuming you have a client that refunds the payment
|
||||
const newData = await this.client.refund(
|
||||
externalId,
|
||||
input.amount
|
||||
)
|
||||
|
||||
return {data: newData}
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[RefundPaymentInput](../../../types/interfaces/types.RefundPaymentInput/page.mdx)","description":"The input to refund the payment. The `data` field should contain the data from the payment provider. when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"[BigNumberInput](../../../types/types/types.BigNumberInput/page.mdx)","description":"The amount to refund.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="refundPayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[RefundPaymentOutput](../../../types/interfaces/types.RefundPaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property, or an error object.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="refundPayment"/>
|
||||
|
||||
### retrievePayment
|
||||
|
||||
Retrieves the payment's data from the third-party service.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
RetrievePaymentInput,
|
||||
RetrievePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async retrievePayment(
|
||||
input: RetrievePaymentInput
|
||||
): Promise<RetrievePaymentOutput> {
|
||||
const externalId = input.data?.id
|
||||
|
||||
// assuming you have a client that retrieves the payment
|
||||
return await this.client.retrieve(externalId)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[RetrievePaymentInput](../../../types/interfaces/types.RetrievePaymentInput/page.mdx)","description":"The input to retrieve the payment. The `data` field should contain the data from the payment provider when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrievePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[RetrievePaymentOutput](../../../types/interfaces/types.RetrievePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The payment's data as found in the the payment provider.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrievePayment"/>
|
||||
|
||||
### savePaymentMethod
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used to save a customer's payment method, such as a credit card, in the
|
||||
third-party payment provider. A payment provider that supports saving payment methods
|
||||
must implement this method.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.5.0`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
import { MedusaError } from "@medusajs/framework/utils"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async savePaymentMethod({ context, data }: SavePaymentMethodInput) { *
|
||||
const accountHolderId = context?.account_holder?.data?.id as
|
||||
| string
|
||||
| undefined
|
||||
|
||||
if (!accountHolderId) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"Missing account holder ID."
|
||||
)
|
||||
}
|
||||
|
||||
// assuming you have a client that saves the payment method
|
||||
const paymentMethod = await this.client.savePaymentMethod({
|
||||
customer_id: accountHolderId,
|
||||
...data
|
||||
})
|
||||
|
||||
return {
|
||||
id: paymentMethod.id,
|
||||
data: paymentMethod as unknown as Record<string, unknown>
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[SavePaymentMethodInput](../../../types/interfaces/types.SavePaymentMethodInput/page.mdx)","description":"The details of the payment method to save.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="savePaymentMethod"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[SavePaymentMethodOutput](../../../types/interfaces/types.SavePaymentMethodOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The result of saving the payment method. If an error occurs, throw it.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="savePaymentMethod"/>
|
||||
|
||||
### updateAccountHolder
|
||||
|
||||
<BadgesList badges={[
|
||||
{
|
||||
"variant": "neutral",
|
||||
"children": "optional"
|
||||
}
|
||||
]} className="mb-1" />
|
||||
|
||||
This method is used when updating an account holder in Medusa, allowing you to update
|
||||
the equivalent account in the third-party service.
|
||||
|
||||
The returned data will be stored in the account holder created in Medusa. For example,
|
||||
the returned `id` property will be stored in the account holder's `external_id` property.
|
||||
|
||||
:::note
|
||||
|
||||
This is only available after Medusa `v2.5.1`.
|
||||
|
||||
:::
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
import { MedusaError } from "@medusajs/framework/utils"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async updateAccountHolder({ context, data }: UpdateAccountHolderInput) {
|
||||
const { account_holder, customer } = context
|
||||
|
||||
if (!account_holder?.data?.id) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"Missing account holder ID."
|
||||
)
|
||||
}
|
||||
|
||||
// assuming you have a client that updates the account holder
|
||||
const providerAccountHolder = await this.client.updateAccountHolder({
|
||||
id: account_holder.data.id,
|
||||
...data
|
||||
})
|
||||
|
||||
return {
|
||||
id: providerAccountHolder.id,
|
||||
data: providerAccountHolder as unknown as Record<string, unknown>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"data","type":"[UpdateAccountHolderInput](../../../types/interfaces/types.UpdateAccountHolderInput/page.mdx)","description":"Input data including the details of the account holder to update.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx) & `object`","description":"The context of updating the account holder.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updateAccountHolder"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[UpdateAccountHolderOutput](../../../types/interfaces/types.UpdateAccountHolderOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The result of updating the account holder. If an error occurs, throw it.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updateAccountHolder"/>
|
||||
|
||||
### updatePayment
|
||||
|
||||
Update a payment in the third-party service that was previously initiated with the [initiatePayment](page.mdx#initiatepayment) method.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
// other imports...
|
||||
import {
|
||||
UpdatePaymentInput,
|
||||
UpdatePaymentOutput,
|
||||
} from "@medusajs/framework/types"
|
||||
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<
|
||||
Options
|
||||
> {
|
||||
async updatePayment(
|
||||
input: UpdatePaymentInput
|
||||
): Promise<UpdatePaymentOutput> {
|
||||
const { amount, currency_code, context } = input
|
||||
const externalId = input.data?.id
|
||||
|
||||
// Validate context.customer
|
||||
if (!context || !context.customer) {
|
||||
throw new Error("Context must include a valid customer.");
|
||||
}
|
||||
|
||||
// assuming you have a client that updates the payment
|
||||
const response = await this.client.update(
|
||||
externalId,
|
||||
{
|
||||
amount,
|
||||
currency_code,
|
||||
context.customer
|
||||
}
|
||||
)
|
||||
|
||||
return response
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"input","type":"[UpdatePaymentInput](../../../types/interfaces/types.UpdatePaymentInput/page.mdx)","description":"The input to update the payment. The `data` field should contain the data from the payment provider. when the payment was created.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"[BigNumberInput](../../../types/types/types.BigNumberInput/page.mdx)","description":"The payment session's amount.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The ISO 3 character code of the payment session.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`Record<string, unknown>`","description":"Data is a combination of the input from the user and what is stored in the database for the associated model.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[PaymentProviderContext](../../../types/interfaces/types.PaymentProviderContext/page.mdx)","description":"The context for this payment operation. The data is guaranteed to be validated and not directly provided by the user.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updatePayment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<[UpdatePaymentOutput](../../../types/interfaces/types.UpdatePaymentOutput/page.mdx)>","optional":false,"defaultValue":"","description":"The new data to store in the payment's `data` property. Throws in case of an error.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updatePayment"/>
|
||||
|
||||
### validateOptions
|
||||
|
||||
This method validates the options of the provider set in `medusa-config.ts`.
|
||||
Implementing this method is optional. It's useful if your provider requires custom validation.
|
||||
|
||||
If the options aren't valid, throw an error.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MyPaymentProviderService extends AbstractPaymentProvider<Options> {
|
||||
static validateOptions(options: Record<any, any>) {
|
||||
if (!options.apiKey) {
|
||||
throw new MedusaError(
|
||||
MedusaError.Types.INVALID_DATA,
|
||||
"API key is required in the provider's options."
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
|
||||
|
||||
---
|
||||
|
||||
## 3. Create Module Provider Definition File
|
||||
|
||||
@@ -1,426 +0,0 @@
|
||||
---
|
||||
slug: /references/search-service
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# How to Create a Search Service
|
||||
|
||||
In this document, you’ll learn how to create a search service in the Medusa backend and the methods you must implement in it.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
A search service must extend the `AbstractSearchService` class imported from the `@medusajs/framework/utils` package. If you don’t already have the package
|
||||
installed, run the following command to install it within your project:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/utils
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A search service class is in a TypeScript or JavaScript file created in the `src/services` directory. The class must extend the `AbstractSearchService` class imported
|
||||
from the `@medusajs/utils` package.
|
||||
|
||||
Based on services’ naming conventions, the file’s name should be the slug version of the search service’s name without `service`, and the class’s name should be the
|
||||
pascal case of the search service’s name following by `Service`.
|
||||
|
||||
For example, create the `MySearchService` class in the file `src/services/my-search.ts`:
|
||||
|
||||
```ts title="src/services/my-search.ts"
|
||||
import { AbstractSearchService } from "@medusajs/utils"
|
||||
|
||||
class MySearchService extends AbstractSearchService {
|
||||
isDefault = false
|
||||
|
||||
createIndex(indexName: string, options: Record<string, any>) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
getIndex(indexName: string) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
addDocuments(
|
||||
indexName: string,
|
||||
documents: Record<string, any>[],
|
||||
type: string
|
||||
) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
replaceDocuments(
|
||||
indexName: string,
|
||||
documents: Record<string, any>[],
|
||||
type: string
|
||||
) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
deleteDocument(
|
||||
indexName: string,
|
||||
document_id: string | number
|
||||
) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
deleteAllDocuments(indexName: string) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
search(
|
||||
indexName: string,
|
||||
query: string,
|
||||
options: Record<string, any>
|
||||
) {
|
||||
return {
|
||||
message: "test",
|
||||
}
|
||||
}
|
||||
updateSettings(
|
||||
indexName: string,
|
||||
settings: Record<string, any>
|
||||
) {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
export default MySearchService
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes About Class Methods
|
||||
|
||||
Although there are several helper methods in this class, the main methods used by the Medusa backend are `addDocuments`, `deleteDocument`, and `search`.
|
||||
The rest of the methods are provided in case you need them for custom use cases.
|
||||
|
||||
---
|
||||
|
||||
## constructor
|
||||
|
||||
You can use the `constructor` of your search service to access the different services in Medusa through dependency injection.
|
||||
|
||||
You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs,
|
||||
you can initialize it in the constructor and use it in other methods in the service.
|
||||
|
||||
Additionally, if you’re creating your search service as an external plugin to be installed on any Medusa backend and you want to access the options added for the plugin,
|
||||
you can access them in the constructor. The default constructor already sets the value of the class proeprty `options_` to the passed options.
|
||||
|
||||
### Example
|
||||
|
||||
```ts
|
||||
// ...
|
||||
import { ProductService } from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
productService: ProductService
|
||||
}
|
||||
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
protected readonly productService_: ProductService
|
||||
|
||||
constructor({ productService }: InjectedDependencies) {
|
||||
// @ts-expect-error prefer-rest-params
|
||||
super(...arguments)
|
||||
this.productService_ = productService
|
||||
|
||||
// you can also initialize a client that
|
||||
// communicates with a third-party service.
|
||||
this.client = new Client(options)
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
<TypeList types={[{"name":"cradle","type":"`any`","description":"An container cradle that allows you to access other resources, such as services, in your Medusa backend.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`any`","description":"If this search service is created in a plugin, the plugin's options are passed in this parameter.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="AbstractSearchService"/>
|
||||
|
||||
___
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"name":"isDefault","type":"`any`","description":"This property is used to pinpoint the default search service defined in the Medusa core. For custom search services, the `isDefault` property must be `false`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options_","type":"`Record<string, unknown>`","description":"If your search service is created in a plugin, the plugin's options will be available in this property.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="AbstractSearchService"/>
|
||||
|
||||
___
|
||||
|
||||
## Methods
|
||||
|
||||
### createIndex
|
||||
|
||||
This method is used to create an index in the search engine.
|
||||
|
||||
#### Example
|
||||
|
||||
An example implementation, assuming `client` would interact with a third-party service:
|
||||
|
||||
```ts title="src/services/my-search.ts"
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
createIndex(indexName: string, options: Record<string, any>) {
|
||||
return this.client_.initIndex(indexName)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Another example of how the [MeiliSearch plugin](https://docs.medusajs.com/plugins/search/meilisearch) uses the
|
||||
`options` parameter:
|
||||
|
||||
```ts
|
||||
class MeiliSearchService extends AbstractSearchService {
|
||||
// ...
|
||||
async createIndex(
|
||||
indexName: string,
|
||||
options: Record<string, unknown> = { primaryKey: "id" }
|
||||
) {
|
||||
return await this.client_.createIndex(indexName, options)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The name of the index to create.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`unknown`","description":"Any options that may be relevant to your search service. This parameter doesn't have\nany defined format as it depends on your custom implementation.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="createIndex"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"No required format of returned data, as it depends on your custom implementation.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="createIndex"/>
|
||||
|
||||
### getIndex
|
||||
|
||||
This method is used to retrieve an index’s results from the search engine.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
getIndex(indexName: string) {
|
||||
return this.client_.getIndex(indexName)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The name of the index","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getIndex"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"No required format of returned data, as it depends on your custom implementation.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getIndex"/>
|
||||
|
||||
### addDocuments
|
||||
|
||||
This method is used to add a document to an index in the search engine.
|
||||
|
||||
When the Medusa backend loads, it triggers indexing for all products available in the Medusa backend, which uses this method to add or update documents.
|
||||
It’s also used whenever a new product is added or a product is updated.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
async addDocuments(
|
||||
indexName: string,
|
||||
documents: Record<string, any>[],
|
||||
type: string
|
||||
) {
|
||||
return await this.client_
|
||||
.addDocuments(indexName, documents)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The name of the index to add the documents to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"documents","type":"`unknown`","description":"The list of documents to add. For example, an array of entities!Product | products.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"type","type":"`string`","description":"The type of documents being indexed. For example, `products`.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="addDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"The response of saving the documents in the search engine, but there’s no required format of the response.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="addDocuments"/>
|
||||
|
||||
### replaceDocuments
|
||||
|
||||
This method is used to replace existing documents in the search engine of an index with new documents.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
async replaceDocuments(
|
||||
indexName: string,
|
||||
documents: Record<string, any>[],
|
||||
type: string
|
||||
) {
|
||||
await this.client_
|
||||
.removeDocuments(indexName)
|
||||
return await this.client_
|
||||
.addDocuments(indexName, documents)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The name of the index that the documents belong to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"documents","type":"`unknown`","description":"The list of documents to index. For example, it can be an array of entities!Product | products.\nBased on your search engine implementation, the documents should include an identification key that allows replacing the existing documents.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"type","type":"`string`","description":"The type of documents being replaced. For example, `products`.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="replaceDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"The response of replacing the documents in the search engine, but there’s no required format of the response.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="replaceDocuments"/>
|
||||
|
||||
### deleteDocument
|
||||
|
||||
This method is used to delete a document from an index.
|
||||
|
||||
When a product is deleted in the Medusa backend, this method is used to delete the product from the search engine’s index.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
async deleteDocument(
|
||||
indexName: string,
|
||||
document_id: string | number
|
||||
) {
|
||||
return await this.client_
|
||||
.deleteDocument(indexName, document_id)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The name of the index that the document belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"document_id","type":"`string` \\| `number`","description":"The ID of the item indexed. For example, if the deleted item is a product, then this is\nthe ID of the product.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteDocument"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"The response of deleting the document in the search engine, but there’s no required format of the response.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteDocument"/>
|
||||
|
||||
### deleteAllDocuments
|
||||
|
||||
This method is used to delete all documents from an index.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
async deleteAllDocuments(indexName: string) {
|
||||
return await this.client_
|
||||
.deleteDocuments(indexName)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The index's name.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteAllDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"The response of deleting the documents of that index in the search engine, but there’s no required format of the response.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="deleteAllDocuments"/>
|
||||
|
||||
### search
|
||||
|
||||
This method is used to search through an index by a query.
|
||||
|
||||
In the Medusa backend, this method is used within the [Search Products API Route](https://docs.medusajs.com/api/store#products\_postproductssearch)
|
||||
to retrieve the search results. The API route's response type is an array of items, though the item's format is not defined as it depends on the
|
||||
data returned by this method.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
async search(
|
||||
indexName: string,
|
||||
query: string,
|
||||
options: Record<string, any>
|
||||
) {
|
||||
const hits = await this.client_
|
||||
.search(indexName, query)
|
||||
return {
|
||||
hits,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The index's name. In the case of the Search Products API Routes, its value is `products`.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"query","type":"`null` \\| `string`","description":"The search query to retrieve results for.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`unknown`","description":"Options that can configure the search process. The Search Products API route passes an object having the properties:\n\n- `paginationOptions`: An object having an `offset` and `limit` properties, which are passed in the API Route's body.\n- `filter`: Filters that are passed in the API Route's request body. Its format is unknown, so you can pass filters based on your search service.\n- `additionalOptions`: Any other parameters that may be passed in the request's body.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="search"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"The list of results. For example, an array of products.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="search"/>
|
||||
|
||||
### updateSettings
|
||||
|
||||
This method is used to update the settings of an index within the search service. This is useful if you want to update the index settings when the plugin options change.
|
||||
|
||||
For example, in the Algolia plugin, a loader, which runs when the Medusa backend loads, is used to update the settings of indices based on the plugin options.
|
||||
The loader uses this method to update the settings.
|
||||
|
||||
#### Example
|
||||
|
||||
```ts
|
||||
class MySearchService extends AbstractSearchService {
|
||||
// ...
|
||||
|
||||
async updateSettings(
|
||||
indexName: string,
|
||||
settings: Record<string, any>
|
||||
) {
|
||||
return await this.client_
|
||||
.updateSettings(indexName, settings)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<TypeList types={[{"name":"indexName","type":"`string`","description":"The index's name to update its settings.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"settings","type":"`unknown`","description":"The settings to update. Its format depends on your use case.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updateSettings"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<TypeList types={[{"name":"unknown","type":"`unknown`","optional":false,"defaultValue":"","description":"The response of updating the index in the search engine, but there’s no required format of the response.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="updateSettings"/>
|
||||
|
||||
---
|
||||
|
||||
## Test Implementation
|
||||
|
||||
:::note
|
||||
|
||||
If you created your search service in a plugin, refer to [this guide on how to test plugins](https://docs.medusajs.com/development/plugins/create#test-your-plugin).
|
||||
|
||||
:::
|
||||
|
||||
After finishing your search service implementation:
|
||||
|
||||
1\. Make sure you have an [event bus module](https://docs.medusajs.com/development/events/modules/redis) installed that triggers search indexing when the Medusa backend loads.
|
||||
|
||||
2\. Run the `build` command in the root of your Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
```
|
||||
|
||||
3\. Start the backend with the `develop` command:
|
||||
|
||||
```bash
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
4\. Try to search for products either using the [Search Products API Route](https://docs.medusajs.com/api/store#products_postproductssearch). The results returned by your search service's `search` method is returned in the `hits` response field.
|
||||
Reference in new issue
Block a user