chore(core-flows,types): improve TSDocs of product workflows (medusaj…

…s#10966)

packages/core/core-flows/src/product/steps/batch-link-products-collection.ts

@@ -8,7 +8,14 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 export const batchLinkProductsToCollectionStepId =
   "batch-link-products-to-collection"
 /**
- * This step creates links between product and collection records.
+ * This step manages the links between a collection and products.
+ * 
+ * @example
+ * const data = batchLinkProductsToCollectionStep({
+ *   id: "collection_123",
+ *   add: ["product_123"],
+ *   remove: ["product_321"]
+ * })
  */
 export const batchLinkProductsToCollectionStep = createStep(
   batchLinkProductsToCollectionStepId,

packages/core/core-flows/src/product/steps/batch-link-products-in-category.ts

@@ -8,7 +8,14 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 export const batchLinkProductsToCategoryStepId =
   "batch-link-products-to-category"
 /**
- * This step creates links between product and category records.
+ * This step manages the links between a category and products.
+ * 
+ * @example
+ * const data = batchLinkProductsToCategoryStep({
+ *   id: "pcat_123",
+ *   add: ["product_123"],
+ *   remove: ["product_321"]
+ * })
  */
 export const batchLinkProductsToCategoryStep = createStep(
   batchLinkProductsToCategoryStepId,

packages/core/core-flows/src/product/steps/create-product-options.ts

@@ -5,6 +5,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createProductOptionsStepId = "create-product-options"
 /**
  * This step creates one or more product options.
+ * 
+ * @example
+ * const data = createProductOptionsStep([{
+ *   title: "Size",
+ *   values: ["S", "M", "L"]
+ * }])
  */
 export const createProductOptionsStep = createStep(
   createProductOptionsStepId,

packages/core/core-flows/src/product/steps/create-product-variants.ts

@@ -5,6 +5,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createProductVariantsStepId = "create-product-variants"
 /**
  * This step creates one or more product variants.
+ * 
+ * @example
+ * const data = createProductVariantsStep([{
+ *   title: "Small Shirt",
+ *   options: {
+ *     Size: "S",
+ *   },
+ *   product_id: "prod_123",
+ * }])
  */
 export const createProductVariantsStep = createStep(
   createProductVariantsStepId,

packages/core/core-flows/src/product/steps/create-products.ts

@@ -5,6 +5,25 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createProductsStepId = "create-products"
 /**
  * This step creates one or more products.
+ * 
+ * @example
+ * const data = createProductsStep([{
+ *   title: "Shirt",
+ *   options: [
+ *     {
+ *       title: "Size",
+ *       values: ["S", "M", "L"]
+ *     }
+ *   ],
+ *   variants: [
+ *     {
+ *       title: "Small Shirt",
+ *       options: {
+ *         Size: "S"
+ *       }
+ *     }
+ *   ]
+ * }])
  */
 export const createProductsStep = createStep(
   createProductsStepId,

packages/core/core-flows/src/product/steps/create-variant-pricing-link.ts

@@ -1,16 +1,38 @@
 import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The links to create between variant and price set records.
+ */
 export type CreateVariantPricingLinkStepInput = {
+  /**
+   * The variant and price set record IDs to link.
+   */
   links: {
+    /**
+     * The variant's ID.
+     */
     variant_id: string
+    /**
+     * The price set's ID.
+     */
     price_set_id: string
   }[]
 }
 
 export const createVariantPricingLinkStepId = "create-variant-pricing-link"
 /**
  * This step creates links between variant and price set records.
+ * 
+ * @example
+ * const data = createVariantPricingLinkStep({
+ *   links: [
+ *     {
+ *       variant_id: "variant_123",
+ *       price_set_id: "pset_123"
+ *     }
+ *   ]
+ * })
  */
 export const createVariantPricingLinkStep = createStep(
   createVariantPricingLinkStepId,

packages/core/core-flows/src/product/steps/delete-collections.ts

@@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the collections to delete.
+ */
+export type DeleteCollectionsStepInput = string[]
+
 export const deleteCollectionsStepId = "delete-collections"
 /**
  * This step deletes one or more collections.
  */
 export const deleteCollectionsStep = createStep(
   deleteCollectionsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteCollectionsStepInput, { container }) => {
     const service = container.resolve<IProductModuleService>(Modules.PRODUCT)
 
     await service.softDeleteProductCollections(ids)

packages/core/core-flows/src/product/steps/delete-product-options.ts

@@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the product options to delete.
+ */
+export type DeleteProductOptionsStepInput = string[]
+
 export const deleteProductOptionsStepId = "delete-product-options"
 /**
  * This step deletes one or more product options.
  */
 export const deleteProductOptionsStep = createStep(
   deleteProductOptionsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteProductOptionsStepInput, { container }) => {
     const service = container.resolve<IProductModuleService>(Modules.PRODUCT)
 
     await service.softDeleteProductOptions(ids)

packages/core/core-flows/src/product/steps/delete-product-tags.ts

@@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the product tags to delete.
+ */
+export type DeleteProductTagsStepInput = string[]
+
 export const deleteProductTagsStepId = "delete-product-tags"
 /**
  * This step deletes one or more product tags.
  */
 export const deleteProductTagsStep = createStep(
   deleteProductTagsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteProductTagsStepInput, { container }) => {
     const service = container.resolve<IProductModuleService>(Modules.PRODUCT)
 
     await service.softDeleteProductTags(ids)

packages/core/core-flows/src/product/steps/delete-product-types.ts

@@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the product types to delete.
+ */
+export type DeleteProductTypesStepInput = string[]
+
 export const deleteProductTypesStepId = "delete-product-types"
 /**
  * This step deletes one or more product types.
  */
 export const deleteProductTypesStep = createStep(
   deleteProductTypesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteProductTypesStepInput, { container }) => {
     const service = container.resolve<IProductModuleService>(Modules.PRODUCT)
 
     await service.softDeleteProductTypes(ids)

packages/core/core-flows/src/product/steps/delete-product-variants.ts

@@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the product variants to delete.
+ */
+export type DeleteProductVariantsStepInput = string[]
+
 export const deleteProductVariantsStepId = "delete-product-variants"
 /**
  * This step deletes one or more product variants.
  */
 export const deleteProductVariantsStep = createStep(
   deleteProductVariantsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteProductVariantsStepInput, { container }) => {
     const service = container.resolve<IProductModuleService>(Modules.PRODUCT)
 
     await service.softDeleteProductVariants(ids)

packages/core/core-flows/src/product/steps/delete-products.ts

@@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the products to delete.
+ */
+export type DeleteProductsStepInput = string[]
+
 export const deleteProductsStepId = "delete-products"
 /**
  * This step deletes one or more products.
  */
 export const deleteProductsStep = createStep(
   deleteProductsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteProductsStepInput, { container }) => {
     const service = container.resolve<IProductModuleService>(Modules.PRODUCT)
 
     await service.softDeleteProducts(ids)

packages/core/core-flows/src/product/steps/generate-product-csv.ts

@@ -58,13 +58,42 @@ const csvSortFunction = (a: string, b: string) => {
   return a.localeCompare(b)
 }
 
+/**
+ * The products to export.
+ */
+export type GenerateProductCsvStepInput = HttpTypes.AdminProduct[]
+
+/**
+ * The export's details.
+ */
+export type GenerateProductCsvStepOutput = {
+  /**
+   * The ID of the generated file as returned by the [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file).
+   */
+  id: string
+  /**
+   * The name of the generated file as returned by the [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file).
+   */
+  filename: string
+}
+
 export const generateProductCsvStepId = "generate-product-csv"
 /**
- * This step generates a CSV file to be exported.
+ * This step generates a CSV file that exports products. The CSV
+ * file is created and stored using the registered [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file).
+ * 
+ * @example
+ * const { data: products } = useQueryGraphStep({
+ *   entity: "product",
+ *   fields: ["*", "variants.*", "collection.*", "categories.*"]
+ * })
+ * 
+ * // @ts-ignore
+ * const data = generateProductCsvStep(products)
  */
 export const generateProductCsvStep = createStep(
   generateProductCsvStepId,
-  async (products: HttpTypes.AdminProduct[], { container }) => {
+  async (products: GenerateProductCsvStepInput, { container }) => {
     const regionService = container.resolve<IRegionModuleService>(
       Modules.REGION
     )
@@ -88,7 +117,10 @@ export const generateProductCsvStep = createStep(
       content: csvContent,
     })
 
-    return new StepResponse({ id: file.id, filename }, file.id)
+    return new StepResponse(
+      { id: file.id, filename } as GenerateProductCsvStepOutput, 
+      file.id
+    )
   },
   async (fileId, { container }) => {
     if (!fileId) {

packages/core/core-flows/src/product/steps/get-all-products.ts

@@ -5,14 +5,44 @@ import {
 import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The configuration to retrieve the products.
+ */
 export type GetAllProductsStepInput = {
+  /**
+   * The fields to select. These fields will be passed to 
+   * [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), so you can
+   * pass product properties or any relation names, including custom links.
+   */
   select: string[]
+  /**
+   * The filters to select which products to retrieve.
+   */
   filter?: FilterableProductProps
 }
 
 export const getAllProductsStepId = "get-all-products"
 /**
- * This step retrieves all products.
+ * This step retrieves all products matching a set of filters.
+ * 
+ * @example
+ * To retrieve all products:
+ * 
+ * ```ts
+ * const data = getAllProductsStep({
+ *   select: ["*"],
+ * })
+ * ```
+ * 
+ * To retrieve all products matching a filter:
+ * 
+ * ```ts
+ * const data = getAllProductsStep({
+ *   select: ["*"],
+ *   filter: {
+ *     collection_id: "collection_123"
+ *   }
+ * })
  */
 export const getAllProductsStep = createStep(
   getAllProductsStepId,

packages/core/core-flows/src/product/steps/get-products.ts

@@ -2,13 +2,19 @@ import { IProductModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * Configurations to retrieve products.
+ */
 export type GetProductsStepInput = {
+  /**
+   * The IDs of the products to retrieve.
+   */
   ids?: string[]
 }
 
 export const getProductsStepId = "get-products"
 /**
- * This step retrieves products.
+ * This step retrieves products, with ability to filter by product IDs.
  */
 export const getProductsStep = createStep(
   getProductsStepId,