chore(core-flows,modules-sdk): add TSDocs to helper steps (#8355)

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 }) => {

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 }) => {

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) => {

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 }) => {

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<string, any>
+  /**
+   * 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 }) => {

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<string, string | string[]>
 }
 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