chore(core-flows,types): update TSDocs related to promotion workflows (#11014)

2025-01-17 13:01:11 +02:00
parent 7be47354e1
commit bae3ddcde0
21 changed files with 386 additions and 20 deletions
@@ -12,6 +12,13 @@ import {
 export const addCampaignPromotionsStepId = "add-campaign-promotions"
 /**
 * This step adds promotions to a campaign.
+ * 
+ * @example
+ * const data = addCampaignPromotionsStep({
+ *   id: "camp_123",
+ *   add: ["promo_123"],
+ *   remove: ["promo_321"],
+ * })
 */
 export const addCampaignPromotionsStep = createStep(
  addCampaignPromotionsStepId,
@@ -8,6 +8,22 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const addRulesToPromotionsStepId = "add-rules-to-promotions"
 /**
 * This step adds rules to a promotion.
+ * 
+ * @example
+ * const data = addRulesToPromotionsStep({
+ *   // import { RuleType } from "@medusajs/framework/utils"
+ *   rule_type: RuleType.RULES,
+ *   data: {
+ *     id: "promo_123",
+ *     rules: [
+ *       {
+ *         attribute: "customer_group",
+ *         operator: "eq",
+ *         values: "custgrp_123"
+ *       }
+ *     ]
+ *   }
+ * })
 */
 export const addRulesToPromotionsStep = createStep(
  addRulesToPromotionsStepId,
@@ -8,6 +8,14 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createCampaignsStepId = "create-campaigns"
 /**
 * This step cancels one or more campaigns.
+ * 
+ * @example
+ * const data = createCampaignsStep([
+ *   {
+ *     name: "Sale Campaign",
+ *     campaign_identifier: "GA-123456"
+ *   }
+ * ])
 */
 export const createCampaignsStep = createStep(
  createCampaignsStepId,
@@ -8,6 +8,19 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const createPromotionsStepId = "create-promotions"
 /**
 * This step creates one or more promotions.
+ * 
+ * @example
+ * const data = createPromotionsStep([
+ *   {
+ *     code: "10OFF",
+ *     type: "standard",
+ *     application_method: {
+ *       type: "percentage",
+ *       value: 10,
+ *       target_type: "items"
+ *     }
+ *   }
+ * ])
 */
 export const createPromotionsStep = createStep(
  createPromotionsStepId,
@@ -2,13 +2,18 @@ import { IPromotionModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"

+/**
+ * The IDs of the campaigns to delete.
+ */
+export type DeleteCampaignsStepInput = string[]
+
 export const deleteCampaignsStepId = "delete-campaigns"
 /**
 * This step deletes one or more campaigns.
 */
 export const deleteCampaignsStep = createStep(
  deleteCampaignsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteCampaignsStepInput, { container }) => {
    const promotionModule = container.resolve<IPromotionModuleService>(
      Modules.PROMOTION
    )
@@ -2,13 +2,18 @@ import { IPromotionModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"

+/**
+ * The IDs of the promotions to delete.
+ */
+export type DeletePromotionsStepInput = string[]
+
 export const deletePromotionsStepId = "delete-promotions"
 /**
 * This step deletes one or more promotions.
 */
 export const deletePromotionsStep = createStep(
  deletePromotionsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeletePromotionsStepInput, { container }) => {
    const promotionModule = container.resolve<IPromotionModuleService>(
      Modules.PROMOTION
    )
@@ -7,7 +7,7 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"

 export const registerUsageStepId = "register-usage"
 /**
- * This step registers usage for promotion campaigns
+ * This step registers usage for a promotion.
 */
 export const registerUsageStep = createStep(
  registerUsageStepId,
@@ -12,6 +12,14 @@ import {
 export const removeCampaignPromotionsStepId = "remove-campaign-promotions"
 /**
 * This step removes promotions from a campaigns.
+ * 
+ * @example
+ * const data = removeCampaignPromotionsStep([
+ *   {
+ *     id: "camp_123",
+ *     remove: ["promo_321"]
+ *   }
+ * ])
 */
 export const removeCampaignPromotionsStep = createStep(
  removeCampaignPromotionsStepId,
@@ -10,6 +10,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const removeRulesFromPromotionsStepId = "remove-rules-from-promotions"
 /**
 * This step removes rules from a promotion.
+ * 
+ * @example
+ * const data = removeRulesFromPromotionsStep({
+ *   rule_type: RuleType.RULES,
+ *   data: {
+ *     id: "promo_123",
+ *     rule_ids: ["prule_123"]
+ *   }
+ * })
 */
 export const removeRulesFromPromotionsStep = createStep(
  removeRulesFromPromotionsStepId,
@@ -12,6 +12,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updateCampaignsStepId = "update-campaigns"
 /**
 * This step updates one or more campaigns.
+ * 
+ * @example
+ * const data = updateCampaignsStep([{
+ *   id: "camp_123",
+ *   campaign_identifier: "GA-123456"
+ * }])
 */
 export const updateCampaignsStep = createStep(
  updateCampaignsStepId,
@@ -8,6 +8,16 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updatePromotionRulesStepId = "update-promotion-rules"
 /**
 * This step updates one or more promotion rules.
+ * 
+ * @example
+ * const data = updatePromotionRulesStep({
+ *   data: [
+ *     {
+ *       id: "prule_123",
+ *       attribute: "customer_group"
+ *     }
+ *   ]
+ * })
 */
 export const updatePromotionRulesStep = createStep(
  updatePromotionRulesStepId,
@@ -12,6 +12,14 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const updatePromotionsStepId = "update-promotions"
 /**
 * This step updates one or more promotions.
+ * 
+ * @example
+ * const data = updatePromotionsStep([
+ *   {
+ *     id: "promo_123",
+ *     code: "10OFF"
+ *   }
+ * ])
 */
 export const updatePromotionsStep = createStep(
  updatePromotionsStepId,
@@ -9,14 +9,41 @@ import {
  removeCampaignPromotionsStep,
 } from "../steps"

+/**
+ * The data to manage the promotions of a campaign.
+ * 
+ * @property id - The ID of the campaign to manage the promotions of.
+ * @property add - The IDs of the promotions to add to the campaign.
+ * @property remove - The IDs of the promotions to remove from the campaign.
+ */
+export type AddOrRemoveCampaignPromotionsWorkflowInput = LinkWorkflowInput
+
 export const addOrRemoveCampaignPromotionsWorkflowId =
  "add-or-remove-campaign-promotions"
 /**
- * This workflow adds or removes promotions from campaigns.
+ * This workflow manages the promotions of a campaign. It's used by the 
+ * [Manage Promotions Admin API Route](https://docs.medusajs.com/api/admin#campaigns_postcampaignsidpromotions).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * manage the promotions of a campaign within your custom flows.
+ * 
+ * @example
+ * const { result } = await addOrRemoveCampaignPromotionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "camp_123",
+ *     add: ["promo_123"],
+ *     remove: ["promo_321"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage the promotions of a campaign.
 */
 export const addOrRemoveCampaignPromotionsWorkflow = createWorkflow(
  addOrRemoveCampaignPromotionsWorkflowId,
-  (input: WorkflowData<LinkWorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<AddOrRemoveCampaignPromotionsWorkflowInput>): WorkflowData<void> => {
    parallelize(
      addCampaignPromotionsStep(input),
      removeCampaignPromotionsStep(input)
@@ -17,20 +17,75 @@ import { deletePromotionRulesWorkflowStep } from "../steps/delete-promotion-rule
 import { createPromotionRulesWorkflow } from "./create-promotion-rules"
 import { updatePromotionRulesWorkflow } from "./update-promotion-rules"

+/**
+ * The data to manage a promotion's rules.
+ * 
+ * @property id - The ID of the promotion to manage the rules of.
+ * @property rule_type - The type of rule to manage.
+ * @property create - The rules to create.
+ * @property update - The rules to update.
+ * @property delete - The IDs of the rules to delete.
+ */
+export type BatchPromotionRulesWorkflowInput = BatchWorkflowInput<
+  CreatePromotionRuleDTO,
+  UpdatePromotionRuleDTO
+> & {
+  id: string
+  rule_type: RuleType
+}
+
+/**
+ * The result of managing the promotion's rules.
+ * 
+ * @property created - The created rules.
+ * @property updated - The updated rules.
+ * @property deleted - The deleted rule IDs.
+ */
+export type BatchPromotionRulesWorkflowOutput = BatchWorkflowOutput<PromotionRuleDTO>
+
 export const batchPromotionRulesWorkflowId = "batch-promotion-rules"
 /**
- * This workflow creates, updates, or deletes promotion rules.
+ * This workflow manages a promotion's rules. It's used by the
+ * [Manage Promotion Rules Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidrulesbatch),
+ * [Manage Promotion Buy Rules Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidbuyrulesbatch),
+ * and [Manage Promotion Target Rules Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidtargetrulesbatch).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * manage promotion rules within your custom flows.
+ * 
+ * @example
+ * const { result } = await batchPromotionRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "promo_123",
+ *     // import { RuleType } from "@medusajs/framework/utils"
+ *     rule_type: RuleType.RULES,
+ *     create: [
+ *       {
+ *         attribute: "cusgrp_123",
+ *         operator: "eq",
+ *         values: ["cusgrp_123"],
+ *       }
+ *     ],
+ *     update: [
+ *       {
+ *         id: "prule_123",
+ *         attribute: "cusgrp_123"
+ *       }
+ *     ],
+ *     delete: ["prule_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage the rules of a promotion.
 */
 export const batchPromotionRulesWorkflow = createWorkflow(
  batchPromotionRulesWorkflowId,
  (
-    input: WorkflowData<
-      BatchWorkflowInput<CreatePromotionRuleDTO, UpdatePromotionRuleDTO> & {
-        id: string
-        rule_type: RuleType
-      }
-    >
-  ): WorkflowResponse<BatchWorkflowOutput<PromotionRuleDTO>> => {
+    input: WorkflowData<BatchPromotionRulesWorkflowInput>
+  ): WorkflowResponse<BatchPromotionRulesWorkflowOutput> => {
    const createInput = transform({ input }, (data) => ({
      rule_type: data.input.rule_type,
      data: { id: data.input.id, rules: data.input.create ?? [] },
@@ -11,7 +11,30 @@ import { addRulesToPromotionsStep } from "../steps"

 export const createPromotionRulesWorkflowId = "create-promotion-rules-workflow"
 /**
- * This workflow creates one or more promotion rules.
+ * This workflow creates one or more promotion rules. It's used by other workflows,
+ * such as {@link batchPromotionRulesWorkflow} that manages the rules of a promotion.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * create promotion rules within your custom flows.
+ * 
+ * @example
+ * const { result } = await createPromotionRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     // import { RuleType } from "@medusajs/framework/utils"
+ *     rule_type: RuleType.RULES,
+ *     data: {
+ *       id: "promo_123",
+ *       rules: [
+ *         {
+ *           attribute: "cusgrp_123",
+ *           operator: "eq",
+ *           values: ["cusgrp_123"],
+ *         }
+ *       ],
+ *     }
+ *   }
+ * })
 */
 export const createPromotionRulesWorkflow = createWorkflow(
  createPromotionRulesWorkflowId,
@@ -6,11 +6,35 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { deleteCampaignsStep } from "../steps"

-export type DeleteCampaignsWorkflowInput = { ids: string[] }
+/**
+ * The data to delete one or more campaigns.
+ */
+export type DeleteCampaignsWorkflowInput = { 
+  /**
+   * The IDs of the campaigns to delete.
+   */
+  ids: string[]
+}

 export const deleteCampaignsWorkflowId = "delete-campaigns"
 /**
- * This workflow deletes one or more campaigns.
+ * This workflow deletes one or more campaigns. It's used by the
+ * [Delete Campaign Admin API Route](https://docs.medusajs.com/api/admin#campaigns_deletecampaignsid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * delete campaigns within your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteCampaignsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["camp_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more campaigns.
 */
 export const deleteCampaignsWorkflow = createWorkflow(
  deleteCampaignsWorkflowId,
@@ -4,7 +4,27 @@ import { removeRulesFromPromotionsStep } from "../steps"

 export const deletePromotionRulesWorkflowId = "delete-promotion-rules-workflow"
 /**
- * This workflow deletes one or more promotion rules.
+ * This workflow deletes one or more promotion rules. It's used by other workflows,
+ * such as {@link batchPromotionRulesWorkflow} that manages the rules of a promotion.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * delete promotion rules within your custom flows.
+ * 
+ * @example
+ * const { result } = await deletePromotionRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     rule_type: RuleType.RULES,
+ *     data: {
+ *       id: "promo_123",
+ *       rule_ids: ["prule_123"]
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more promotion rules.
 */
 export const deletePromotionRulesWorkflow = createWorkflow(
  deletePromotionRulesWorkflowId,
@@ -6,11 +6,35 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { deletePromotionsStep } from "../steps"

-export type DeletePromotionsWorkflowInput = { ids: string[] }
+/**
+ * The data to delete one or more promotions.
+ */
+export type DeletePromotionsWorkflowInput = { 
+  /**
+   * The IDs of the promotions to delete.
+   */
+  ids: string[]
+}

 export const deletePromotionsWorkflowId = "delete-promotions"
 /**
- * This workflow deletes one or more promotions.
+ * This workflow deletes one or more promotions. It's used by the
+ * [Delete Promotions Admin API Route](https://docs.medusajs.com/api/admin#promotions_deletepromotionsid).
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * delete promotions within your custom flows.
+ * 
+ * @example
+ * const { result } = await deletePromotionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["promo_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more promotions.
 */
 export const deletePromotionsWorkflow = createWorkflow(
  deletePromotionsWorkflowId,
@@ -11,7 +11,28 @@ import { updatePromotionRulesStep } from "../steps"

 export const updatePromotionRulesWorkflowId = "update-promotion-rules-workflow"
 /**
- * This workflow updates one or more promotion rules.
+ * This workflow updates one or more promotion rules. It's used by other workflows,
+ * such as {@link batchPromotionRulesWorkflow} that manages the rules of a promotion.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you to
+ * update promotion rules within your custom flows.
+ * 
+ * @example
+ * const { result } = await updatePromotionRulesWorkflow(container)
+ * .run({
+ *   input: {
+ *     data: [
+ *       {
+ *         id: "prule_123",
+ *         attribute: "cusgrp_123",
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more promotion rules.
 */
 export const updatePromotionRulesWorkflow = createWorkflow(
  updatePromotionRulesWorkflowId,
@@ -11,9 +11,21 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { updatePromotionsStep } from "../steps"

+/**
+ * The data to update the status of one or more promotions.
+ */
 export type UpdatePromotionsStatusWorkflowInput = {
+  /**
+   * The promotions to update their status.
+   */
  promotionsData: {
+    /**
+     * The ID of the promotion.
+     */
    id: string
+    /**
+     * The new status of the promotion.
+     */
    status: PromotionStatusValues
  }[]
 } & AdditionalData
@@ -36,6 +48,35 @@ export const updatePromotionsValidationStep = createStep(
 )

 export const updatePromotionsStatusWorkflowId = "update-promotions-status"
+/**
+ * This workflow updates the status of one or more promotions.
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the updated promotions. For example, you can pass under `additional_data` custom data that
+ * allows you to create custom data models linked to the promotions.
+ * 
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to
+ * update the status of promotions within your custom flows.
+ * 
+ * @example
+ * const { result } = await updatePromotionsStatusWorkflow(container)
+ * .run({
+ *   input: {
+ *     promotionsData: {
+ *       id: "promo_123",
+ *       status: "active"
+ *     },
+ *     additional_data: {
+ *       external_id: "ext_123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update the status of one or more promotions.
+ * 
+ * @property hooks.promotionStatusUpdated - This hook is executed after the promotions' status is updated. You can consume this hook to perform custom actions on the updated promotions.
+ */
 export const updatePromotionsStatusWorkflow = createWorkflow(
  updatePromotionsStatusWorkflowId,
  (input: UpdatePromotionsStatusWorkflowInput) => {
@@ -4,22 +4,58 @@ import {
  UpdatePromotionRuleDTO,
 } from "./common"

+/**
+ * The data to create rules for a promotion.
+ */
 export type AddPromotionRulesWorkflowDTO = {
+  /**
+   * The type of rules to create.
+   */
  rule_type: PromotionRuleTypes
+  /**
+   * The data to create the rules.
+   */
  data: {
+    /**
+     * The ID of the promotion to create the rules for.
+     */
    id: string
+    /**
+     * The rules to create.
+     */
    rules: CreatePromotionRuleDTO[]
  }
 }

+/**
+ * The data to remove rules of a promotion.
+ */
 export type RemovePromotionRulesWorkflowDTO = {
+  /**
+   * The type of rules to remove.
+   */
  rule_type: PromotionRuleTypes
+  /**
+   * The data to remove the rules.
+   */
  data: {
+    /**
+     * The ID of the promotion to remove its rules.
+     */
    id: string
+    /**
+     * The IDs of the rules to remove.
+     */
    rule_ids: string[]
  }
 }

+/**
+ * The data to update promotion rules.
+ */
 export type UpdatePromotionRulesWorkflowDTO = {
+  /**
+   * The promotion rules to update.
+   */
  data: UpdatePromotionRuleDTO[]
 }