diff --git a/packages/core/core-flows/src/common/steps/create-remote-links.ts b/packages/core/core-flows/src/common/steps/create-remote-links.ts index 0483c9a435..abd28f403a 100644 --- a/packages/core/core-flows/src/common/steps/create-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/create-remote-links.ts @@ -3,6 +3,36 @@ import { ContainerRegistrationKeys } from "@medusajs/utils" import { createStep, StepResponse } from "@medusajs/workflows-sdk" export const createLinksStepId = "create-remote-links" +/** + * This step creates remote links between two records of linked data models. + * + * Learn more in the [Remote Link documentation.](https://docs.medusajs.com/v2/advanced-development/modules/remote-link#create-link). + * + * @example + * import { + * createWorkflow + * } from "@medusajs/workflows-sdk" + * import { + * createRemoteLinkStep + * } from "@medusajs/core-flows" + * import { + * Modules + * } from "@medusajs/utils" + * + * const helloWorldWorkflow = createWorkflow( + * "hello-world", + * () => { + * createRemoteLinkStep([{ + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * }]) + * } + * ) + */ export const createRemoteLinkStep = createStep( createLinksStepId, async (data: LinkDefinition[], { container }) => { diff --git a/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts b/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts index 7650a4b7d9..1e5a08906b 100644 --- a/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/dismiss-remote-links.ts @@ -3,10 +3,40 @@ import { createStep, StepResponse } from "@medusajs/workflows-sdk" import { ContainerRegistrationKeys } from "@medusajs/utils" -type DismissRemoteLinksStepInput = LinkDefinition | LinkDefinition[] +export type DismissRemoteLinksStepInput = LinkDefinition | LinkDefinition[] // TODO: add ability for this step to restore links from only foreign keys export const dismissRemoteLinkStepId = "dismiss-remote-links" +/** + * This step removes remote links between two records of linked data models. + * + * Learn more in the [Remote Link documentation.](https://docs.medusajs.com/v2/advanced-development/modules/remote-link#dismiss-link). + * + * @example + * import { + * createWorkflow + * } from "@medusajs/workflows-sdk" + * import { + * dismissRemoteLinkStep + * } from "@medusajs/core-flows" + * import { + * Modules + * } from "@medusajs/utils" + * + * const helloWorldWorkflow = createWorkflow( + * "hello-world", + * () => { + * dismissRemoteLinkStep([{ + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * "helloModuleService": { + * my_custom_id: "mc_123", + * }, + * }]) + * } + * ) + */ export const dismissRemoteLinkStep = createStep( dismissRemoteLinkStepId, async (data: DismissRemoteLinksStepInput, { container }) => { diff --git a/packages/core/core-flows/src/common/steps/emit-event.ts b/packages/core/core-flows/src/common/steps/emit-event.ts index 53b518a32d..1ee3ddfb27 100644 --- a/packages/core/core-flows/src/common/steps/emit-event.ts +++ b/packages/core/core-flows/src/common/steps/emit-event.ts @@ -12,6 +12,9 @@ type Input = { } export const emitEventStepId = "emit-event-step" +/** + * @ignore + */ export const emitEventStep = createStep( emitEventStepId, async (input: Input, context) => { diff --git a/packages/core/core-flows/src/common/steps/remove-remote-links.ts b/packages/core/core-flows/src/common/steps/remove-remote-links.ts index 56cf16909e..081d264661 100644 --- a/packages/core/core-flows/src/common/steps/remove-remote-links.ts +++ b/packages/core/core-flows/src/common/steps/remove-remote-links.ts @@ -6,6 +6,33 @@ import { ContainerRegistrationKeys } from "@medusajs/utils" type RemoveRemoteLinksStepInput = DeleteEntityInput | DeleteEntityInput[] export const removeRemoteLinkStepId = "remove-remote-links" +/** + * This step deletes linked records of a record. + * + * Learn more in the [Remote Link documentation](https://docs.medusajs.com/v2/advanced-development/modules/remote-link#cascade-delete-linked-records) + * + * @example + * import { + * createWorkflow + * } from "@medusajs/workflows-sdk" + * import { + * removeRemoteLinkStep + * } from "@medusajs/core-flows" + * import { + * Modules + * } from "@medusajs/utils" + * + * const helloWorldWorkflow = createWorkflow( + * "hello-world", + * () => { + * removeRemoteLinkStep([{ + * [Modules.PRODUCT]: { + * product_id: "prod_123", + * }, + * }]) + * } + * ) + */ export const removeRemoteLinkStep = createStep( removeRemoteLinkStepId, async (data: RemoveRemoteLinksStepInput, { container }) => { diff --git a/packages/core/core-flows/src/common/steps/use-remote-query.ts b/packages/core/core-flows/src/common/steps/use-remote-query.ts index e933465609..65a8283e3e 100644 --- a/packages/core/core-flows/src/common/steps/use-remote-query.ts +++ b/packages/core/core-flows/src/common/steps/use-remote-query.ts @@ -4,23 +4,141 @@ import { } from "@medusajs/utils" import { createStep, StepResponse } from "@medusajs/workflows-sdk" -interface StepInput { +/** + * The remote query's details. + */ +export interface RemoteStepInput { + /** + * The fields to retrieve in the records. + */ fields: string[] + /** + * Filters, context variables, or pagination fields to apply when retrieving the records. + */ variables?: Record + /** + * Throw an error if a record isn't found matching an ID specified in the filters. + */ throw_if_key_not_found?: boolean + /** + * Throw an error if a specified relation isn't found. + */ throw_if_relation_not_found?: boolean | string[] + /** + * Whether to retrieve the records as an array. If disabled, only one record is retrieved as an object. + * + * @defaultValue true + */ list?: boolean } -interface EntryStepInput extends StepInput { +export interface EntryStepInput extends RemoteStepInput { + /** + * The name of the data model to retrieve its records. + */ entry_point: string } -interface ServiceStepInput extends StepInput { +export interface ServiceStepInput extends RemoteStepInput { + /** + * The name of the module's service. + */ service: string } export const useRemoteQueryStepId = "use-remote-query" +/** + * This step fetches data across modules using the remote query. + * + * Learn more in the [Remote Query documentation](https://docs.medusajs.com/v2/advanced-development/modules/remote-query). + * + * @example + * + * To retrieve a list of records of a data model: + * + * ```ts + * import { + * createWorkflow + * } from "@medusajs/workflows-sdk" + * import { + * useRemoteQueryStep + * } from "@medusajs/core-flows" + * + * const helloWorldWorkflow = createWorkflow( + * "hello-world", + * () => { + * const products = useRemoteQueryStep({ + * entry_point: "product", + * fields: [ + * "*", + * "variants.*" + * ] + * }) + * } + * ) + * ``` + * + * To retrieve a single item instead of a an array: + * + * ```ts + * import { + * createWorkflow + * } from "@medusajs/workflows-sdk" + * import { + * useRemoteQueryStep + * } from "@medusajs/core-flows" + * + * const helloWorldWorkflow = createWorkflow( + * "hello-world", + * () => { + * const product = useRemoteQueryStep({ + * entry_point: "product", + * fields: [ + * "*", + * "variants.*" + * ], + * variables: { + * filters: { + * id: "123" + * } + * }, + * list: false + * }) + * } + * ) + * ``` + * + * To throw an error if a record isn't found matching the specified ID: + * + * ```ts + * import { + * createWorkflow + * } from "@medusajs/workflows-sdk" + * import { + * useRemoteQueryStep + * } from "@medusajs/core-flows" + * + * const helloWorldWorkflow = createWorkflow( + * "hello-world", + * () => { + * const product = useRemoteQueryStep({ + * entry_point: "product", + * fields: [ + * "*", + * "variants.*" + * ], + * variables: { + * filters: { + * id: "123" + * } + * }, + * list: false, + * throw_if_key_not_found: true + * }) + * } + * ) + * ``` + */ export const useRemoteQueryStep = createStep( useRemoteQueryStepId, async (data: EntryStepInput | ServiceStepInput, { container }) => { diff --git a/packages/core/modules-sdk/src/remote-link.ts b/packages/core/modules-sdk/src/remote-link.ts index 69f5bc7680..ea8426935f 100644 --- a/packages/core/modules-sdk/src/remote-link.ts +++ b/packages/core/modules-sdk/src/remote-link.ts @@ -9,11 +9,22 @@ import { MedusaModule } from "./medusa-module" import { convertRecordsToLinkDefinition } from "./utils/convert-data-to-link-definition" import { linkingErrorMessage } from "./utils/linking-error" +/** + * The details of a data model's record whose linked records should be deleted. Usually used after the + * data model's record is deleted. + * + * The key is the data model's name. Its value is an object that has the ID of the data model's record. + */ export type DeleteEntityInput = { [moduleName: string | Modules]: Record } export type RestoreEntityInput = DeleteEntityInput +/** + * A link for two records of linked data models. + * + * The keys are the names of each module, and their value is an object that holds the ID of the linked data model's record. + */ export type LinkDefinition = { [moduleName: string]: { // TODO: changing this to any temporarily as the "data" attribute is not being picked up correctly