chore: add TSDocs to the Promotion Module (#6793)

packages/types/src/promotion/common/application-method.ts

@@ -2,56 +2,241 @@ import { BaseFilterable } from "../../dal"
 import { PromotionDTO } from "./promotion"
 import { CreatePromotionRuleDTO, PromotionRuleDTO } from "./promotion-rule"
 
+/**
+ * @interface
+ *
+ * The application method's possible types.
+ */
 export type ApplicationMethodTypeValues = "fixed" | "percentage"
+
+/**
+ * @interface
+ *
+ * The application method's possible target types.
+ */
 export type ApplicationMethodTargetTypeValues =
   | "order"
   | "shipping_methods"
   | "items"
+
+/**
+ * @interface
+ *
+ * The application method's possible allocation values.
+ */
 export type ApplicationMethodAllocationValues = "each" | "across"
 
+/**
+ * The application method details.
+ */
 export interface ApplicationMethodDTO {
+  /**
+   * The ID of the application method.
+   */
   id: string
+
+  /**
+   * The type of the application method indicating how
+   * the associated promotion is applied.
+   */
   type?: ApplicationMethodTypeValues
+
+  /**
+   * The target type of the application method indicating
+   * whether the associated promotion is applied to the cart's items,
+   * shipping methods, or the whole order.
+   */
   target_type?: ApplicationMethodTargetTypeValues
+
+  /**
+   * The allocation value that indicates whether the associated promotion
+   * is applied on each item in a cart or split between the items in the cart.
+   */
   allocation?: ApplicationMethodAllocationValues
+
+  /**
+   * The discounted amount applied by the associated promotion based on the `type`.
+   */
   value?: number
+
+  /**
+   * The max quantity allowed in the cart for the associated promotion to be applied.
+   */
   max_quantity?: number | null
+
+  /**
+   * The minimum quantity required for a `buyget` promotion to be applied.
+   * For example, if the promotion is a "Buy 2 shirts get 1 free", the
+   * value of this attribute is `2`.
+   */
   buy_rules_min_quantity?: number | null
+
+  /**
+   * The quantity that results from matching the `buyget` promotion's condition.
+   * For example, if the promotion is a "Buy 2 shirts get 1 free", the value
+   * of this attribute is `1`.
+   */
   apply_to_quantity?: number | null
+
+  /**
+   * The promotion of the application method.
+   */
   promotion?: PromotionDTO | string
+
+  /**
+   * The target rules of the application method.
+   */
   target_rules?: PromotionRuleDTO[]
+
+  /**
+   * The buy rules of the application method.
+   */
   buy_rules?: PromotionRuleDTO[]
 }
 
+/**
+ * The application method to be created.
+ */
 export interface CreateApplicationMethodDTO {
+  /**
+   * The type of the application method indicating how
+   * the associated promotion is applied.
+   */
   type: ApplicationMethodTypeValues
+
+  /**
+   * The target type of the application method indicating
+   * whether the associated promotion is applied to the cart's items,
+   * shipping methods, or the whole order.
+   */
   target_type: ApplicationMethodTargetTypeValues
+
+  /**
+   * The allocation value that indicates whether the associated promotion
+   * is applied on each item in a cart or split between the items in the cart.
+   */
   allocation?: ApplicationMethodAllocationValues
+
+  /**
+   * The discounted amount applied by the associated promotion based on the `type`.
+   */
   value?: number
+
+  /**
+   * The max quantity allowed in the cart for the associated promotion to be applied.
+   */
   max_quantity?: number | null
+
+  /**
+   * The minimum quantity required for a `buyget` promotion to be applied.
+   * For example, if the promotion is a "Buy 2 shirts get 1 free", the
+   * value of this attribute is `2`.
+   */
   buy_rules_min_quantity?: number | null
+
+  /**
+   * The quantity that results from matching the `buyget` promotion's condition.
+   * For example, if the promotion is a "Buy 2 shirts get 1 free", the value
+   * of this attribute is `1`.
+   */
   apply_to_quantity?: number | null
+
+  /**
+   * The promotion of the application method.
+   */
   promotion?: PromotionDTO | string
+
+  /**
+   * The target rules of the application method.
+   */
   target_rules?: CreatePromotionRuleDTO[]
+
+  /**
+   * The buy rules of the application method.
+   */
   buy_rules?: CreatePromotionRuleDTO[]
 }
 
+/**
+ * The attributes to update in the application method.
+ */
 export interface UpdateApplicationMethodDTO {
+  /**
+   * The ID of the application method.
+   */
   id: string
+
+  /**
+   * The type of the application method indicating how
+   * the associated promotion is applied.
+   */
   type?: ApplicationMethodTypeValues
+
+  /**
+   * The target type of the application method indicating
+   * whether the associated promotion is applied to the cart's items,
+   * shipping methods, or the whole order.
+   */
   target_type?: ApplicationMethodTargetTypeValues
+
+  /**
+   * The allocation value that indicates whether the associated promotion
+   * is applied on each item in a cart or split between the items in the cart.
+   */
   allocation?: ApplicationMethodAllocationValues
+
+  /**
+   * The discounted amount applied by the associated promotion based on the `type`.
+   */
   value?: number
+
+  /**
+   * The max quantity allowed in the cart for the associated promotion to be applied.
+   */
   max_quantity?: number | null
+
+  /**
+   * The minimum quantity required for a `buyget` promotion to be applied.
+   * For example, if the promotion is a "Buy 2 shirts get 1 free", the
+   * value of this attribute is `2`.
+   */
   buy_rules_min_quantity?: number | null
+
+  /**
+   * The quantity that results from matching the `buyget` promotion's condition.
+   * For example, if the promotion is a "Buy 2 shirts get 1 free", the value
+   * of this attribute is `1`.
+   */
   apply_to_quantity?: number | null
+
+  /**
+   * The promotion of the application method.
+   */
   promotion?: PromotionDTO | string
 }
 
+/**
+ * The filters to apply on the retrieved application methods.
+ */
 export interface FilterableApplicationMethodProps
   extends BaseFilterable<FilterableApplicationMethodProps> {
+  /**
+   * The IDs to filter the application methods by.
+   */
   id?: string[]
+
+  /**
+   * Filter the application methods by their type.
+   */
   type?: ApplicationMethodTypeValues[]
+
+  /**
+   * Filter the application methods by their target type.
+   */
   target_type?: ApplicationMethodTargetTypeValues[]
+
+  /**
+   * Filter the application methods by their allocation value.
+   */
   allocation?: ApplicationMethodAllocationValues[]
 }

packages/types/src/promotion/common/campaign-budget.ts

@@ -1,16 +1,57 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ *
+ * The campaign budget's possible types.
+ */
 export type CampaignBudgetTypeValues = "spend" | "usage"
 
+/**
+ * The campaign budget details.
+ */
 export interface CampaignBudgetDTO {
+  /**
+   * The ID of the campaign budget.
+   */
   id: string
+
+  /**
+   * The type of the campaign budget:
+   *
+   * - `spend` indicates that the budget is limited by the amount discounted by the promotions in the associated campaign.
+   * - `usage` indicates that the budget is limited by the number of times the promotions of the associated campaign have been used.
+   *
+   */
   type?: CampaignBudgetTypeValues
+
+  /**
+   * The limit of the campaign budget.
+   */
   limit?: number | null
+
+  /**
+   * The usage from the campaign budget's limit:
+   *
+   * - If the budget's type is `spend`, the value of this attribute is the amount discounted so far by the promotions in the associated campaign.
+   * - If the budget's type is `usage`, the value of this attribute is the number of times the promotions of the associated campaign have been used so far.
+   *
+   */
   used?: number
 }
 
+/**
+ * The filters to apply on the retrieved campaign budgets.
+ */
 export interface FilterableCampaignBudgetProps
   extends BaseFilterable<FilterableCampaignBudgetProps> {
+  /**
+   * The IDs to filter the campaign budgets by.
+   */
   id?: string[]
+
+  /**
+   * Filters the campaign budgets by their type.
+   */
   type?: string[]
 }

packages/types/src/promotion/common/campaign.ts

@@ -1,19 +1,63 @@
 import { BaseFilterable } from "../../dal"
 import { CampaignBudgetDTO } from "./campaign-budget"
 
+/**
+ * The campaign details.
+ */
 export interface CampaignDTO {
+  /**
+   * The ID of the campaign.
+   */
   id: string
+
+  /**
+   * The name of the campaign.
+   */
   name?: string
+
+  /**
+   * The description of the campaign.
+   */
   description?: string
+
+  /**
+   * The currency of the campaign.
+   */
   currency?: string
+
+  /**
+   * The campaign identifier of the campaign.
+   */
   campaign_identifier?: string
+
+  /**
+   * The start date of the campaign.
+   */
   starts_at?: Date
+
+  /**
+   * The end date of the campaign.
+   */
   ends_at?: Date
+
+  /**
+   * The associated campaign budget.
+   */
   budget?: CampaignBudgetDTO
 }
 
+/**
+ * The filters to apply on the retrieved campaigns.
+ */
 export interface FilterableCampaignProps
   extends BaseFilterable<FilterableCampaignProps> {
+  /**
+   * The IDs to filter the campaigns by.
+   */
   id?: string[]
+
+  /**
+   * Filters the campaigns by their campaign identifier.
+   */
   campaign_identifier?: string[]
 }

packages/types/src/promotion/common/compute-actions.ts

@@ -1,3 +1,8 @@
+/**
+ * @interface
+ *
+ * A compute action informs you what adjustment must be made to a cart item or shipping method.
+ */
 export type ComputeActions =
   | AddItemAdjustmentAction
   | RemoveItemAdjustmentAction
@@ -5,67 +10,218 @@ export type ComputeActions =
   | RemoveShippingMethodAdjustment
   | CampaignBudgetExceededAction
 
+/**
+ * @interface
+ *
+ * These computed action types can affect a campaign's budget.
+ */
 export type UsageComputedActions =
   | AddShippingMethodAdjustment
   | AddItemAdjustmentAction
 
+/**
+ * This action indicates that the promotions within a campaign can no longer be used
+ * as the campaign budget has been exceeded.
+ */
 export interface CampaignBudgetExceededAction {
+  /**
+   * The type of action.
+   */
   action: "campaignBudgetExceeded"
+
+  /**
+   * The promotion's code.
+   */
   code: string
 }
 
+/**
+ * This action indicates that an adjustment must be made to an item. For example, removing $5 off its amount.
+ */
 export interface AddItemAdjustmentAction {
+  /**
+   * The type of action.
+   */
   action: "addItemAdjustment"
+
+  /**
+   * The associated item's ID.
+   */
   item_id: string
+
+  /**
+   * The amount to remove off the item's total.
+   */
   amount: number
+
+  /**
+   * The promotion's code.
+   */
   code: string
+
+  /**
+   * The promotion's description.
+   */
   description?: string
 }
 
+/**
+ * This action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount applied before.
+ */
 export interface RemoveItemAdjustmentAction {
+  /**
+   * The type of action.
+   */
   action: "removeItemAdjustment"
+
+  /**
+   * The associated adjustment's ID.
+   */
   adjustment_id: string
+
+  /**
+   * The promotion's description.
+   */
   description?: string
+
+  /**
+   * The promotion's code.
+   */
   code: string
 }
 
+/**
+ * This action indicates that an adjustment must be made on a shipping method. For example, make the shipping method free.
+ */
 export interface AddShippingMethodAdjustment {
+  /**
+   * The type of action.
+   */
   action: "addShippingMethodAdjustment"
+
+  /**
+   * The associated shipping method's ID.
+   */
   shipping_method_id: string
+
+  /**
+   * The amount to remove off the shipping method's total.
+   */
   amount: number
+
+  /**
+   * The promotion's code.
+   */
   code: string
+
+  /**
+   * The promotion's description.
+   */
   description?: string
 }
 
+/**
+ * This action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount applied before.
+ */
 export interface RemoveShippingMethodAdjustment {
+  /**
+   * The type of action
+   */
   action: "removeShippingMethodAdjustment"
+
+  /**
+   * The associated adjustment's ID.
+   */
   adjustment_id: string
+
+  /**
+   * The promotion's code.
+   */
   code: string
 }
 
+/**
+ * An action's adjustment line.
+ */
 export interface ComputeActionAdjustmentLine extends Record<string, unknown> {
+  /**
+   * The ID of the compute action's adjustment line.
+   */
   id: string
+
+  /**
+   * The promotion's code.
+   */
   code: string
 }
 
+/**
+ * A cart's line item passed in the context when computing actions.
+ */
 export interface ComputeActionItemLine extends Record<string, unknown> {
+  /**
+   * The ID of the item line.
+   */
   id: string
+
+  /**
+   * The quantity of the line item.
+   */
   quantity: number
+
+  /**
+   * The subtotal of the line item.
+   */
   subtotal: number
+
+  /**
+   * The adjustments applied before on the line item.
+   */
   adjustments?: ComputeActionAdjustmentLine[]
 }
 
+/**
+ * A cart's shipping method passed in the content when computing actions.
+ */
 export interface ComputeActionShippingLine extends Record<string, unknown> {
+  /**
+   * The ID of the shipping method.
+   */
   id: string
+
+  /**
+   * The subtotal of the shipping method.
+   */
   subtotal: number
+
+  /**
+   * The adjustments applied before on the shipping method.
+   */
   adjustments?: ComputeActionAdjustmentLine[]
 }
 
+/**
+ * The context provided when computing actions of promotions.
+ */
 export interface ComputeActionContext extends Record<string, unknown> {
+  /**
+   * The cart's line items.
+   */
   items?: ComputeActionItemLine[]
+
+  /**
+   * The cart's shipping methods.
+   */
   shipping_methods?: ComputeActionShippingLine[]
 }
 
+/**
+ * Options to configure how actions are computed.
+ */
 export interface ComputeActionOptions {
+  /**
+   * Whether to apply promotions having their `is_automatic` field enabled
+   * automatically. If not provided, the automatic promotions are applied.
+   */
   prevent_auto_promotions?: boolean
 }

packages/types/src/promotion/common/promotion-rule-value.ts

@@ -1,21 +1,53 @@
 import { BaseFilterable } from "../../dal"
 import { PromotionRuleDTO } from "./promotion-rule"
 
+/**
+ * The promotion rule value details.
+ */
 export interface PromotionRuleValueDTO {
+  /**
+   * The ID of the promotion rule value.
+   */
   id: string
+
+  /**
+   * The value of the promotion rule value.
+   */
   value?: string
 }
 
+/**
+ * The promotion rule value to be created.
+ */
 export interface CreatePromotionRuleValueDTO {
+  /**
+   * The value of the promotion rule value.
+   */
   value: string
+
+  /**
+   * The associated promotion rule.
+   */
   promotion_rule: PromotionRuleDTO
 }
 
+/**
+ * The attributes to update in the promotion rule value.
+ */
 export interface UpdatePromotionRuleValueDTO {
+  /**
+   * The ID of the promotion rule value.
+   */
   id: string
 }
 
+/**
+ * The filters to apply on the retrieved promotion rule values.
+ */
 export interface FilterablePromotionRuleValueProps
   extends BaseFilterable<FilterablePromotionRuleValueProps> {
+  /**
+   * The IDs to filter the promotion rule values by.
+   */
   id?: string[]
 }

packages/types/src/promotion/common/promotion-rule.ts

@@ -1,6 +1,11 @@
 import { BaseFilterable } from "../../dal"
 import { PromotionRuleValueDTO } from "./promotion-rule-value"
 
+/**
+ * @interface
+ *
+ * The possible operators to use in a promotion rule.
+ */
 export type PromotionRuleOperatorValues =
   | "gt"
   | "lt"
@@ -10,36 +15,119 @@ export type PromotionRuleOperatorValues =
   | "lte"
   | "gte"
 
+/**
+ * The promotion rule details.
+ */
 export interface PromotionRuleDTO {
+  /**
+   * The ID of the promotion rule.
+   */
   id: string
+
+  /**
+   * The description of the promotion rule.
+   */
   description?: string | null
+
+  /**
+   * The attribute of the promotion rule.
+   */
   attribute?: string
+
+  /**
+   * The operator of the promotion rule.
+   */
   operator?: PromotionRuleOperatorValues
+
+  /**
+   * The values of the promotion rule.
+   */
   values: PromotionRuleValueDTO[]
 }
 
+/**
+ * The promotion rule to be created.
+ */
 export interface CreatePromotionRuleDTO {
+  /**
+   * The description of the promotion rule.
+   */
   description?: string | null
+
+  /**
+   * The attribute of the promotion rule.
+   */
   attribute: string
+
+  /**
+   * The operator of the promotion rule.
+   */
   operator: PromotionRuleOperatorValues
+
+  /**
+   * The values of the promotion rule.
+   * When provided, `PromotionRuleValue` records are
+   * created and associated with the promotion rule.
+   */
   values: string[] | string
 }
 
+/**
+ * The attributes to update in the promotion rule.
+ */
 export interface UpdatePromotionRuleDTO {
+  /**
+   * The ID of the promotion rule.
+   */
   id: string
+
+  /**
+   * The description of the promotion rule.
+   */
   description?: string | null
+
+  /**
+   * The attribute of the promotion rule.
+   */
   attribute?: string
+
+  /**
+   * The operator of the promotion rule.
+   */
   operator?: PromotionRuleOperatorValues
+
+  /**
+   * The values of the promotion rule.
+   * When provided, `PromotionRuleValue` records are
+   * created and associated with the promotion rule.
+   */
   values?: string[] | string
 }
 
+/**
+ * The details required when removing a promotion rule.
+ */
 export interface RemovePromotionRuleDTO {
+  /**
+   * The ID of the promotion rule to remove.
+   */
   id: string
 }
 
+/**
+ * The filters to apply on the retrieved promotion rules.
+ */
 export interface FilterablePromotionRuleProps
   extends BaseFilterable<FilterablePromotionRuleProps> {
+  /**
+   * The IDs to filter the promotion rules by.
+   */
   id?: string[]
 }
 
+/**
+ * @interface
+ *
+ * The promotion rule's possible types.
+ */
 export type PromotionRuleTypes = "buy_rules" | "target_rules" | "rules"

packages/types/src/promotion/common/promotion.ts

@@ -8,42 +8,163 @@ import {
 import { CampaignDTO } from "./campaign"
 import { CreatePromotionRuleDTO, PromotionRuleDTO } from "./promotion-rule"
 
+/**
+ * @interface
+ *
+ * The promotion's possible types.
+ */
 export type PromotionTypeValues = "standard" | "buyget"
 
+/**
+ * The promotion details.
+ */
 export interface PromotionDTO {
+  /**
+   * The ID of the promotion.
+   */
   id: string
+
+  /**
+   * The code of the promotion.
+   */
   code?: string
+
+  /**
+   * The type of the promotion:
+   *
+   * - `standard` indicates that a promotion is a standard one applied with conditions.
+   * - `buyget` indicates that a promotion is a "Buy X get Y" promotion.
+   *
+   */
   type?: PromotionTypeValues
+
+  /**
+   * Whether the promotion is applied automatically.
+   */
   is_automatic?: boolean
+
+  /**
+   * The associated application method.
+   */
   application_method?: ApplicationMethodDTO
+
+  /**
+   * The rules of the promotion.
+   */
   rules?: PromotionRuleDTO[]
+
+  /**
+   * The associated campaign.
+   */
   campaign?: CampaignDTO
 }
 
+/**
+ * The promotion to be created.
+ */
 export interface CreatePromotionDTO {
+  /**
+   * The code of the promotion.
+   */
   code: string
+
+  /**
+   * The type of the promotion:
+   *
+   * - `standard` indicates that a promotion is a standard one applied with conditions.
+   * - `buyget` indicates that a promotion is a "Buy X get Y" promotion.
+   *
+   */
   type: PromotionTypeValues
+
+  /**
+   * Whether the promotion is applied automatically.
+   */
   is_automatic?: boolean
+
+  /**
+   * The associated application method.
+   */
   application_method?: CreateApplicationMethodDTO
+
+  /**
+   * The rules of the promotion.
+   */
   rules?: CreatePromotionRuleDTO[]
+
+  /**
+   * The associated campaign.
+   */
   campaign?: CreateCampaignDTO
+
+  /**
+   * The associated campaign's ID.
+   */
   campaign_id?: string
 }
 
+/**
+ * The attributes to update in the promotion.
+ */
 export interface UpdatePromotionDTO {
+  /**
+   * The ID of the promotion.
+   */
   id: string
+
+  /**
+   * Whether the promotion is applied automatically.
+   */
   is_automatic?: boolean
+
+  /**
+   * The code of the promotion.
+   */
   code?: string
+
+  /**
+   * The type of the promotion.
+   */
   type?: PromotionTypeValues
+
+  /**
+   * The associated application method.
+   */
   application_method?: UpdateApplicationMethodDTO
+
+  /**
+   * The associated campaign's ID.
+   */
   campaign_id?: string
 }
 
+/**
+ * The filters to apply on the retrieved promotions.
+ */
 export interface FilterablePromotionProps
   extends BaseFilterable<FilterablePromotionProps> {
+  /**
+   * The IDs to filter the promotions by.
+   */
   id?: string | string[]
+
+  /**
+   * Filter promotions by their code.
+   */
   code?: string | string[] | OperatorMap<string>
+
+  /**
+   * Filter promotions by the ID of their associated campaign budget.
+   */
   budget_id?: string[] | OperatorMap<string>
+
+  /**
+   * Filter promotions by whether they're applied automatically.
+   */
   is_automatic?: boolean
+
+  /**
+   * Filter promotions by their type.
+   */
   type?: PromotionTypeValues[]
 }

packages/types/src/promotion/mutations.ts

@@ -1,37 +1,141 @@
 import { CampaignBudgetTypeValues, PromotionDTO } from "./common"
 
+/**
+ * The campaign budget to be created.
+ */
 export interface CreateCampaignBudgetDTO {
+  /**
+   * The type of the campaign budget.
+   */
   type: CampaignBudgetTypeValues
+
+  /**
+   * The limit of the campaign budget.
+   */
   limit: number | null
+
+  /**
+   * How much is used of the campaign budget.
+   */
   used?: number
 }
 
+/**
+ * The attributes to update in the campaign budget.
+ */
 export interface UpdateCampaignBudgetDTO {
+  /**
+   * The ID of the campaign budget.
+   */
   id: string
+
+  /**
+   * The type of the campaign budget.
+   */
   type?: CampaignBudgetTypeValues
+
+  /**
+   * The limit of the campaign budget.
+   */
   limit?: number | null
+
+  /**
+   * How much is used of the campaign budget.
+   */
   used?: number
 }
 
+/**
+ * The campaign to be created.
+ */
 export interface CreateCampaignDTO {
+  /**
+   * The name of the campaign.
+   */
   name: string
+
+  /**
+   * The description of the campaign.
+   */
   description?: string
+
+  /**
+   * The currency of the campaign.
+   */
   currency?: string
+
+  /**
+   * The campaign identifier of the campaign.
+   */
   campaign_identifier: string
+
+  /**
+   * The start date of the campaign.
+   */
   starts_at: Date
+
+  /**
+   * The end date of the campaign.
+   */
   ends_at: Date
+
+  /**
+   * The associated campaign budget.
+   */
   budget?: CreateCampaignBudgetDTO
+
+  /**
+   * The promotions of the campaign.
+   */
   promotions?: Pick<PromotionDTO, "id">[]
 }
 
+/**
+ * The attributes to update in the campaign.
+ */
 export interface UpdateCampaignDTO {
+  /**
+   * The ID of the campaign.
+   */
   id: string
+
+  /**
+   * The name of the campaign.
+   */
   name?: string
+
+  /**
+   * The description of the campaign.
+   */
   description?: string
+
+  /**
+   * The currency of the campaign.
+   */
   currency?: string
+
+  /**
+   * The campaign identifier of the campaign.
+   */
   campaign_identifier?: string
+
+  /**
+   * The start date of the campaign.
+   */
   starts_at?: Date
+
+  /**
+   * The end date of the campaign.
+   */
   ends_at?: Date
+
+  /**
+   * The budget of the campaign.
+   */
   budget?: Omit<UpdateCampaignBudgetDTO, "id">
+
+  /**
+   * The promotions of the campaign.
+   */
   promotions?: Pick<PromotionDTO, "id">[]
 }

packages/types/src/promotion/service.ts

@@ -18,162 +18,950 @@ import {
 } from "./common"
 import { CreateCampaignDTO, UpdateCampaignDTO } from "./mutations"
 
+/**
+ * The main service interface for the Promotion Module.
+ */
 export interface IPromotionModuleService extends IModuleService {
+  /**
+   * This method adjusts the budget for each campaign associated with the promotions' specified computed actions.
+   * It adjusts the `used` property of a `CampaignBudget` to account for the adjustment amounts in the specified associated
+   * computed actions.
+   *
+   * @param {ComputeActions[]} computedActions - The computed actions to adjust their promotion's campaign budget.
+   * @returns {Promise<void>} Resolves when the campaign budgets have been adjusted successfully.
+   *
+   * @example
+   * await promotionModuleService.registerUsage([
+   *   {
+   *     action: "addItemAdjustment",
+   *     item_id: "cali_123",
+   *     amount: 50,
+   *     code: "50OFF",
+   *   },
+   *   {
+   *     action: "addShippingMethodAdjustment",
+   *     shipping_method_id: "casm_123",
+   *     amount: 5000,
+   *     code: "FREESHIPPING",
+   *   },
+   * ])
+   */
   registerUsage(computedActions: ComputeActions[]): Promise<void>
 
+  /**
+   * This method provides the actions to perform on a cart based on the specified promotions
+   * and context.
+   *
+   * @param {string[]} promotionCodesToApply - The promotion codes to be applied on the cart.
+   * @param {ComputeActionContext} applicationContext - The items and shipping methods of the cart.
+   * @param {Record<string, any>} options - Any relevant options that may change how the actions are computed.
+   * @returns {Promise<ComputeActions[]>} The list of computed actions to be applied on the cart.
+   *
+   * @example
+   * const actions = await promotionModuleService.computeActions(
+   *   ["50OFF"],
+   *   {
+   *     items: [
+   *       {
+   *         id: "cali_123",
+   *         quantity: 2,
+   *         subtotal: 1000,
+   *       },
+   *     ],
+   *     shipping_methods: [
+   *       {
+   *         id: "casm_123",
+   *         subtotal: 0,
+   *         adjustments: [
+   *           {
+   *             id: "adj_123",
+   *             code: "FREESHIPPING",
+   *           },
+   *         ],
+   *       },
+   *     ],
+   *   }
+   * )
+   */
   computeActions(
     promotionCodesToApply: string[],
     applicationContext: ComputeActionContext,
     options?: Record<string, any>
   ): Promise<ComputeActions[]>
 
+  /**
+   * This method creates promotions.
+   *
+   * @param {CreatePromotionDTO[]} data - The promotions to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionDTO[]>} The created promotions.
+   *
+   * @example
+   * const promotions = await promotionModuleService.create([
+   *   {
+   *     code: "50OFF",
+   *     type: "standard",
+   *     application_method: {
+   *       type: "percentage",
+   *       target_type: "items",
+   *       value: 50,
+   *     },
+   *   },
+   *   {
+   *     code: "FREESHIPPING",
+   *     type: "standard",
+   *     application_method: {
+   *       type: "percentage",
+   *       target_type: "shipping_methods",
+   *       value: 100,
+   *     },
+   *   },
+   *   {
+   *     code: "BUY2GET1",
+   *     type: "buyget",
+   *     application_method: {
+   *       type: "fixed",
+   *       target_type: "items",
+   *       buy_rules_min_quantity: 2,
+   *       apply_to_quantity: 1,
+   *       buy_rules: [
+   *         {
+   *           attribute: "SKU",
+   *           operator: "eq",
+   *           values: ["SHIRT"],
+   *         },
+   *       ],
+   *     },
+   *   },
+   * ])
+   */
   create(
     data: CreatePromotionDTO[],
     sharedContext?: Context
   ): Promise<PromotionDTO[]>
 
+  /**
+   * This method creates a promotion.
+   *
+   * @param {CreatePromotionDTO} data - The promotion to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionDTO>} The created promotion.
+   *
+   * @example
+   * const promotionA = await promotionModuleService.create({
+   *   code: "50OFF",
+   *   type: "standard",
+   *   application_method: {
+   *     type: "percentage",
+   *     target_type: "items",
+   *     value: 50,
+   *   },
+   * })
+   *
+   * const promotionB = await promotionModuleService.create({
+   *   code: "FREESHIPPING",
+   *   type: "standard",
+   *   application_method: {
+   *     type: "percentage",
+   *     target_type: "shipping_methods",
+   *     value: 100,
+   *   },
+   * })
+   *
+   * const promotionC = await promotionModuleService.create({
+   *   code: "BUY2GET1",
+   *   type: "buyget",
+   *   application_method: {
+   *     type: "fixed",
+   *     target_type: "items",
+   *     buy_rules_min_quantity: 2,
+   *     apply_to_quantity: 1,
+   *     buy_rules: [
+   *       {
+   *         attribute: "SKU",
+   *         operator: "eq",
+   *         values: ["SHIRT"],
+   *       },
+   *     ],
+   *   },
+   * })
+   */
   create(
     data: CreatePromotionDTO,
     sharedContext?: Context
   ): Promise<PromotionDTO>
 
+  /**
+   * This method updates existing promotions.
+   *
+   * @param {UpdatePromotionDTO[]} data - The attributes to update in the promotions.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionDTO[]>} The updated promotions.
+   *
+   * @example
+   * const promotions = await promotionModuleService.update([
+   *   {
+   *     id: "promo_123",
+   *     is_automatic: true,
+   *   },
+   * ])
+   */
   update(
     data: UpdatePromotionDTO[],
     sharedContext?: Context
   ): Promise<PromotionDTO[]>
 
+  /**
+   * This method updates an existing promotion.
+   *
+   * @param {UpdatePromotionDTO} data - The attributes to update in the promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionDTO>} The updated promotion.
+   *
+   * @example
+   * const promotion = await promotionModuleService.update({
+   *   id: "promo_123",
+   *   is_automatic: true,
+   * })
+   */
   update(
     data: UpdatePromotionDTO,
     sharedContext?: Context
   ): Promise<PromotionDTO>
 
+  /**
+   * This method retrieves a paginated list of promotions based on optional filters and configuration.
+   *
+   * @param {FilterablePromotionProps} filters - The filters to apply on the retrieved promotions.
+   * @param {FindConfig<PromotionDTO>} config - The configurations determining how the promotion is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionDTO[]>} The list of promotions.
+   *
+   * @example
+   * To retrieve a list of promotions using their IDs:
+   *
+   * ```ts
+   * const promotions = await promotionModuleService.list({
+   *   id: ["promo_123", "promo_321"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the promotions:
+   *
+   * ```ts
+   * const promotions = await promotionModuleService.list(
+   *   {
+   *     id: ["promo_123", "promo_321"],
+   *   },
+   *   {
+   *     relations: ["application_method"],
+   *   }
+   * )
+   * ```
+   *
+   * 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 promotions = await promotionModuleService.list(
+   *   {
+   *     id: ["promo_123", "promo_321"],
+   *   },
+   *   {
+   *     relations: ["application_method"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
+   */
   list(
     filters?: FilterablePromotionProps,
     config?: FindConfig<PromotionDTO>,
     sharedContext?: Context
   ): Promise<PromotionDTO[]>
 
+  /**
+   * This method retrieves a paginated list of promotions along with the total count of available promotions satisfying the provided filters.
+   *
+   * @param {FilterablePromotionProps} filters - The filters to apply on the retrieved promotions.
+   * @param {FindConfig<PromotionDTO>} config - The configurations determining how the promotion is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[PromotionDTO[], number]>} The list of promotions along with their total count.
+   *
+   * @example
+   * To retrieve a list of promotions using their IDs:
+   *
+   * ```ts
+   * const [promotions, count] =
+   *   await promotionModuleService.listAndCount({
+   *     id: ["promo_123", "promo_321"],
+   *   })
+   * ```
+   *
+   * To specify relations that should be retrieved within the promotions:
+   *
+   * ```ts
+   * const [promotions, count] =
+   *   await promotionModuleService.listAndCount(
+   *     {
+   *       id: ["promo_123", "promo_321"],
+   *     },
+   *     {
+   *       relations: ["application_method"],
+   *     }
+   *   )
+   * ```
+   *
+   * 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 [promotions, count] =
+   *   await promotionModuleService.listAndCount(
+   *     {
+   *       id: ["promo_123", "promo_321"],
+   *     },
+   *     {
+   *       relations: ["application_method"],
+   *       take: 20,
+   *       skip: 2,
+   *     }
+   *   )
+   * ```
+   */
   listAndCount(
     filters?: FilterablePromotionProps,
     config?: FindConfig<PromotionDTO>,
     sharedContext?: Context
   ): Promise<[PromotionDTO[], number]>
 
+  /**
+   * This method retrieves a promotion by its ID.
+   *
+   * @param {string} id - The ID of the promotion.
+   * @param {FindConfig<PromotionDTO>} config - The configurations determining how the promotion is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionDTO>} The retrieved promotion.
+   *
+   * @example
+   * A simple example that retrieves a promotion by its ID:
+   *
+   * ```ts
+   * const promotion =
+   *   await promotionModuleService.retrieve("promo_123")
+   * ```
+   *
+   * To specify relations that should be retrieved:
+   *
+   * ```ts
+   * const promotion = await promotionModuleService.retrieve(
+   *   "promo_123",
+   *   {
+   *     relations: ["application_method"],
+   *   }
+   * )
+   * ```
+   */
   retrieve(
     id: string,
     config?: FindConfig<PromotionDTO>,
     sharedContext?: Context
   ): Promise<PromotionDTO>
 
+  /**
+   * This method deletes promotions by their IDs.
+   *
+   * @param {string[]} ids - The IDs of the promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the promotions are deleted.
+   *
+   * @example
+   * await promotionModuleService.delete([
+   *   "promo_123",
+   *   "promo_321",
+   * ])
+   */
   delete(ids: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes a promotion by its ID.
+   *
+   * @param {string} ids - The IDs of the promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the promotion is deleted.
+   *
+   * @example
+   * await promotionModuleService.delete("promo_123")
+   */
   delete(ids: string, sharedContext?: Context): Promise<void>
 
+  /**
+   * This method soft deletes a promotion by its IDs.
+   *
+   * @param {string | string[]} promotionIds - The list of promotions to soft delete.
+   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated application method.
+   * The object's keys are the ID attribute names of the promotion entity's relations, such as `application_method_id`, and its value is an array of strings, each being the ID of a record associated
+   * with the promotion through this relation, such as the IDs of associated application method.
+   *
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await promotionModuleService.softDelete("promo_123")
+   */
   softDelete<TReturnableLinkableKeys extends string = string>(
     promotionIds: string | string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
 
+  /**
+   * This method restores soft deleted promotions by their IDs.
+   *
+   * @param {string | string[]} promotionIds - The promotions' IDs.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the promotion. You can pass to its `returnLinkableKeys`
+   * property any of the promotion's relation attribute names, such as `application_method_id`.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were restored, such as the ID of associated application method.
+   * The object's keys are the ID attribute names of the promotion entity's relations, such as `application_method_id`,
+   * and its value is an array of strings, each being the ID of the record associated with the promotion through this relation,
+   * such as the IDs of associated application method.
+   *
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await promotionModuleService.restore("promo_123")
+   */
   restore<TReturnableLinkableKeys extends string = string>(
     promotionIds: string | string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
 
+  /**
+   * This method adds promotion rules to a promotion.
+   *
+   * @param {string} promotionId - The promotion's ID.
+   * @param {CreatePromotionRuleDTO[]} rulesData - The promotion rules to be created and added to the promotion.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionRuleDTO[]>} The promotion rules created.
+   *
+   * @example
+   * const promotionRules =
+   *   await promotionModuleService.addPromotionRules(
+   *     "promo_123",
+   *     [
+   *       {
+   *         attribute: "customer_group_id",
+   *         operator: "in",
+   *         values: ["VIP", "VVIP"],
+   *       },
+   *     ]
+   *   )
+   */
   addPromotionRules(
     promotionId: string,
     rulesData: CreatePromotionRuleDTO[],
     sharedContext?: Context
   ): Promise<PromotionRuleDTO[]>
 
+  /**
+   * This method adds target promotion rules to a promotion's application method.
+   *
+   * @param {string} promotionId - The promotion's ID.
+   * @param {CreatePromotionRuleDTO[]} rulesData - The promotion rules to be created and added as target rules to the promotion's application method.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionRuleDTO[]>} The created promotion rules.
+   *
+   * @example
+   * const targetPromotionRules =
+   *   await promotionModuleService.addPromotionTargetRules(
+   *     "promo_123",
+   *     [
+   *       {
+   *         attribute: "SKU",
+   *         operator: "eq",
+   *         values: "SHIRT",
+   *       },
+   *     ]
+   *   )
+   */
   addPromotionTargetRules(
     promotionId: string,
     rulesData: CreatePromotionRuleDTO[],
     sharedContext?: Context
   ): Promise<PromotionRuleDTO[]>
 
+  /**
+   * This method adds buy promotion rules to a promotion's application method.
+   *
+   * @param {string} promotionId - The promotion's ID.
+   * @param {CreatePromotionRuleDTO[]} rulesData - The promotion rules to be created and added as buy rules to the promotion's applicatio method.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionRuleDTO[]>} The created promotion rules.
+   *
+   * @example
+   * const buyPromotionRules =
+   *   await promotionModuleService.addPromotionBuyRules(
+   *     "promo_123",
+   *     [
+   *       {
+   *         attribute: "SKU",
+   *         operator: "eq",
+   *         values: "SHIRT",
+   *       },
+   *     ]
+   *   )
+   */
   addPromotionBuyRules(
     promotionId: string,
     rulesData: CreatePromotionRuleDTO[],
     sharedContext?: Context
   ): Promise<PromotionRuleDTO[]>
 
+  /**
+   * This method removes promotion rules from a promotion.
+   *
+   * @param {string} promotionId - The promotion's ID.
+   * @param {string[]} ruleIds - The promotion rules' IDs.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the promotion rules are deleted successfully.
+   *
+   * @example
+   * await promotionModuleService.removePromotionRules(
+   *   "promo_123",
+   *   ["prorul_123", "prorul_321"]
+   * )
+   */
   removePromotionRules(
     promotionId: string,
     ruleIds: string[],
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method removes target promotion rules from a promotion's application method.
+   *
+   * @param {string} promotionId - The promotion's ID.
+   * @param {string[]} ruleIds - The target promotion rules' IDs.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the target promotion rules are deleted.
+   *
+   * @example
+   * await promotionModuleService.removePromotionTargetRules(
+   *   "promo_123",
+   *   ["prorul_123", "prorul_321"]
+   * )
+   */
   removePromotionTargetRules(
     promotionId: string,
     ruleIds: string[],
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method removes buy promotion rules from a promotion's application method.
+   *
+   * @param {string} promotionId - The promotion's ID.
+   * @param {string[]} ruleIds - The buy promotion rules' IDs.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the buy promotion rules are deleted.
+   *
+   * @example
+   * await promotionModuleService.removePromotionBuyRules(
+   *   "promo_123",
+   *   ["prorul_123", "prorul_321"]
+   * )
+   */
   removePromotionBuyRules(
     promotionId: string,
     ruleIds: string[],
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method creates a campaign.
+   *
+   * @param {CreateCampaignDTO} data - The campaign to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CampaignDTO>} The created campaign.
+   *
+   * @example
+   * const campaign = await promotionModuleService.createCampaigns(
+   *   {
+   *     name: "Summer discounts",
+   *     campaign_identifier: "G-123456",
+   *     starts_at: new Date("2025-06-01"),
+   *     ends_at: new Date("2025-09-01"),
+   *     budget: {
+   *       type: "usage",
+   *       limit: 10,
+   *     },
+   *   }
+   * )
+   */
   createCampaigns(
     data: CreateCampaignDTO,
     sharedContext?: Context
   ): Promise<CampaignDTO>
 
+  /**
+   * This method creates campaigns.
+   *
+   * @param {CreateCampaignDTO[]} data - The campaigns to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CampaignDTO[]>} The created campaigns.
+   *
+   * @example
+   * const campaigns =
+   *   await promotionModuleService.createCampaigns([
+   *     {
+   *       name: "Summer discounts",
+   *       campaign_identifier: "G-123456",
+   *       starts_at: new Date("2025-06-01"),
+   *       ends_at: new Date("2025-09-01"),
+   *       budget: {
+   *         type: "usage",
+   *         limit: 10,
+   *       },
+   *     },
+   *   ])
+   */
   createCampaigns(
     data: CreateCampaignDTO[],
     sharedContext?: Context
   ): Promise<CampaignDTO[]>
 
+  /**
+   * This method updates existing campaigns.
+   *
+   * @param {UpdateCampaignDTO[]} data - The attributes to update in the campaigns.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CampaignDTO[]>} The updated campaigns.
+   *
+   * @example
+   * const campaigns =
+   *   await promotionModuleService.updateCampaigns([
+   *     {
+   *       id: "procamp_123",
+   *       name: "Summer Sales",
+   *     },
+   *   ])
+   */
   updateCampaigns(
     data: UpdateCampaignDTO[],
     sharedContext?: Context
   ): Promise<CampaignDTO[]>
 
+  /**
+   * This method updates an existing campaign.
+   *
+   * @param {UpdateCampaignDTO} data - The attributes to update in the campaign.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CampaignDTO>} The updated campaign.
+   *
+   * @example
+   * const campaigns =
+   *   await promotionModuleService.updateCampaigns({
+   *     id: "procamp_123",
+   *     name: "Summer Sales",
+   *   })
+   */
   updateCampaigns(
     data: UpdateCampaignDTO,
     sharedContext?: Context
   ): Promise<CampaignDTO>
 
+  /**
+   * This method retrieves a paginated list of promotion rules based on optional filters and configuration.
+   *
+   * @param {FilterablePromotionRuleProps} filters - The filters to apply on the retrieved promotion rules.
+   * @param {FindConfig<PromotionRuleDTO>} config - The configurations determining how the promotion rule is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a promotion rule.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionRuleDTO[]>} The list of promotion rules.
+   *
+   * @example
+   * To retrieve a list of promotion rules using their IDs:
+   *
+   * ```ts
+   * const promotionRules =
+   *   await promotionModuleService.listPromotionRules({
+   *     id: ["prorul_123", "prorul_321"],
+   *   })
+   * ```
+   *
+   * To specify relations that should be retrieved within the promotion rules:
+   *
+   * ```ts
+   * const promotionRules =
+   *   await promotionModuleService.listPromotionRules(
+   *     {
+   *       id: ["prorul_123", "prorul_321"],
+   *     },
+   *     {
+   *       relations: ["promotions"],
+   *     }
+   *   )
+   * ```
+   *
+   * 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 promotionRules =
+   *   await promotionModuleService.listPromotionRules(
+   *     {
+   *       id: ["prorul_123", "prorul_321"],
+   *     },
+   *     {
+   *       relations: ["promotions"],
+   *       take: 20,
+   *       skip: 2,
+   *     }
+   *   )
+   * ```
+   */
   listPromotionRules(
     filters?: FilterablePromotionRuleProps,
     config?: FindConfig<PromotionRuleDTO>,
     sharedContext?: Context
   ): Promise<PromotionRuleDTO[]>
 
+  /**
+   * This method updates existing promotion rules.
+   *
+   * @param {UpdatePromotionRuleDTO[]} data - The attributes to update in the promotion rules.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PromotionRuleDTO[]>} The updated promotion rules.
+   *
+   * @example
+   * const promotionRules =
+   *   await promotionModuleService.updatePromotionRules([
+   *     {
+   *       id: "prorul_123",
+   *       description: "Only allow VIP customers",
+   *     },
+   *   ])
+   */
   updatePromotionRules(
     data: UpdatePromotionRuleDTO[],
     sharedContext?: Context
   ): Promise<PromotionRuleDTO[]>
 
+  /**
+   * This method retrieves a paginated list of campaigns based on optional filters and configuration.
+   *
+   * @param {FilterableCampaignProps} filters - The filters to apply on the retrieved campaigns.
+   * @param {FindConfig<CampaignDTO>} config - The configurations determining how the campaign is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a campaign.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CampaignDTO[]>} The list of campaigns.
+   *
+   * @example
+   * To retrieve a list of campaigns using their IDs:
+   *
+   * ```ts
+   * const campaigns = await promotionModuleService.listCampaigns({
+   *   id: ["procamp_123"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the campaigns:
+   *
+   * ```ts
+   * const campaigns = await promotionModuleService.listCampaigns(
+   *   {
+   *     id: ["procamp_123"],
+   *   },
+   *   {
+   *     relations: ["promotions"],
+   *   }
+   * )
+   * ```
+   *
+   * 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 campaigns = await promotionModuleService.listCampaigns(
+   *   {
+   *     id: ["procamp_123"],
+   *   },
+   *   {
+   *     relations: ["promotions"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
+   */
   listCampaigns(
     filters?: FilterableCampaignProps,
     config?: FindConfig<CampaignDTO>,
     sharedContext?: Context
   ): Promise<CampaignDTO[]>
 
+  /**
+   * This method retrieves a paginated list of campaigns along with the total count of available campaigns satisfying the provided filters.
+   *
+   * @param {FilterableCampaignProps} filters - The filters to apply on the retrieved campaigns.
+   * @param {FindConfig<CampaignDTO>} config - The configurations determining how the campaign is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a campaign.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[CampaignDTO[], number]>} The list of campaigns along with their total count.
+   *
+   * @example
+   * To retrieve a list of campaigns using their IDs:
+   *
+   * ```ts
+   * const [campaigns, count] =
+   *   await promotionModuleService.listAndCountCampaigns({
+   *     id: ["procamp_123"],
+   *   })
+   * ```
+   *
+   * To specify relations that should be retrieved within the campaigns:
+   *
+   * ```ts
+   * const [campaigns, count] =
+   *   await promotionModuleService.listAndCountCampaigns(
+   *     {
+   *       id: ["procamp_123"],
+   *     },
+   *     {
+   *       relations: ["promotions"],
+   *     }
+   *   )
+   * ```
+   *
+   * 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 [campaigns, count] =
+   *   await promotionModuleService.listAndCountCampaigns(
+   *     {
+   *       id: ["procamp_123"],
+   *     },
+   *     {
+   *       relations: ["promotions"],
+   *       take: 20,
+   *       skip: 2,
+   *     }
+   *   )
+   * ```
+   */
   listAndCountCampaigns(
     filters?: FilterableCampaignProps,
     config?: FindConfig<CampaignDTO>,
     sharedContext?: Context
   ): Promise<[CampaignDTO[], number]>
 
+  /**
+   * This method retrieves a campaigns by its ID.
+   *
+   * @param {string} id - The ID of the campaigns.
+   * @param {FindConfig<CampaignDTO>} config - The configurations determining how the campaign is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a campaign.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CampaignDTO>} The retrieved campaigns.
+   *
+   * @example
+   * A simple example that retrieves a promotion by its ID:
+   *
+   * ```ts
+   * const campaign =
+   *   await promotionModuleService.retrieveCampaign("procamp_123")
+   * ```
+   *
+   * To specify relations that should be retrieved:
+   *
+   * ```ts
+   * const campaign =
+   *   await promotionModuleService.retrieveCampaign(
+   *     "procamp_123",
+   *     {
+   *       relations: ["promotions"],
+   *     }
+   *   )
+   * ```
+   */
   retrieveCampaign(
     id: string,
     config?: FindConfig<CampaignDTO>,
     sharedContext?: Context
   ): Promise<CampaignDTO>
 
+  /**
+   * This method deletes campaigns by their IDs.
+   *
+   * @param {string[]} ids - The IDs of the campaigns.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the campaigns are deleted successfully.
+   *
+   * @example
+   * await promotionModuleService.deleteCampaigns(["procamp_123"])
+   */
   deleteCampaigns(ids: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes a campaign by its ID.
+   *
+   * @param {string} ids - The IDs of the campaign.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves when the campaign is deleted successfully.
+   *
+   * @example
+   * await promotionModuleService.deleteCampaigns("procamp_123")
+   */
   deleteCampaigns(ids: string, sharedContext?: Context): Promise<void>
 
+  /**
+   * This method soft deletes campaigns by their IDs.
+   *
+   * @param {string | string[]} campaignIds - The IDs of the campaigns.
+   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated campaign budget.
+   * The object's keys are the ID attribute names of the campaign entity's relations, such as `budget_id`, and its value is an array of strings, each being the ID of a record associated
+   * with the campaign through this relation, such as the IDs of associated campaign budget.
+   *
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await promotionModuleService.softDeleteCampaigns(
+   *   "procamp_123",
+   *   {
+   *     returnLinkableKeys: ["budget_id"],
+   *   }
+   * )
+   */
   softDeleteCampaigns<TReturnableLinkableKeys extends string = string>(
     campaignIds: string | string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
 
+  /**
+   * This method restores soft deleted campaigns by their IDs.
+   *
+   * @param {string | string[]} campaignIds - The IDs of the campaigns
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the campaigns. You can pass to its `returnLinkableKeys`
+   * property any of the campaign's relation attribute names, such as `budget_id`.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were restored, such as the ID of associated campaign budget.
+   * The object's keys are the ID attribute names of the campaign entity's relations, such as `budget_id`,
+   * and its value is an array of strings, each being the ID of the record associated with the campaign through this relation,
+   * such as the IDs of associated campaign budget.
+   *
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await promotionModuleService.restoreCampaigns("procamp_123", {
+   *   returnLinkableKeys: ["budget_id"],
+   * })
+   */
   restoreCampaigns<TReturnableLinkableKeys extends string = string>(
     campaignIds: string | string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,