diff --git a/packages/types/src/promotion/common/application-method.ts b/packages/types/src/promotion/common/application-method.ts index a8c2a55529..a3f6d66142 100644 --- a/packages/types/src/promotion/common/application-method.ts +++ b/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 { + /** + * 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[] } diff --git a/packages/types/src/promotion/common/campaign-budget.ts b/packages/types/src/promotion/common/campaign-budget.ts index 4f341a43cb..0840e98666 100644 --- a/packages/types/src/promotion/common/campaign-budget.ts +++ b/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 { + /** + * The IDs to filter the campaign budgets by. + */ id?: string[] + + /** + * Filters the campaign budgets by their type. + */ type?: string[] } diff --git a/packages/types/src/promotion/common/campaign.ts b/packages/types/src/promotion/common/campaign.ts index 9034c2c94e..dbd685a6af 100644 --- a/packages/types/src/promotion/common/campaign.ts +++ b/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 { + /** + * The IDs to filter the campaigns by. + */ id?: string[] + + /** + * Filters the campaigns by their campaign identifier. + */ campaign_identifier?: string[] } diff --git a/packages/types/src/promotion/common/compute-actions.ts b/packages/types/src/promotion/common/compute-actions.ts index 1384daa93f..bb8fc08597 100644 --- a/packages/types/src/promotion/common/compute-actions.ts +++ b/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 { + /** + * 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 { + /** + * 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 { + /** + * 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 { + /** + * 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 } diff --git a/packages/types/src/promotion/common/promotion-rule-value.ts b/packages/types/src/promotion/common/promotion-rule-value.ts index 7610202a77..fa7b7b79c9 100644 --- a/packages/types/src/promotion/common/promotion-rule-value.ts +++ b/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 { + /** + * The IDs to filter the promotion rule values by. + */ id?: string[] } diff --git a/packages/types/src/promotion/common/promotion-rule.ts b/packages/types/src/promotion/common/promotion-rule.ts index 4f978e51cb..86ec12b3c1 100644 --- a/packages/types/src/promotion/common/promotion-rule.ts +++ b/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 { + /** + * 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" diff --git a/packages/types/src/promotion/common/promotion.ts b/packages/types/src/promotion/common/promotion.ts index 8d248dab14..cd67cca670 100644 --- a/packages/types/src/promotion/common/promotion.ts +++ b/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 { + /** + * The IDs to filter the promotions by. + */ id?: string | string[] + + /** + * Filter promotions by their code. + */ code?: string | string[] | OperatorMap + + /** + * Filter promotions by the ID of their associated campaign budget. + */ budget_id?: string[] | OperatorMap + + /** + * Filter promotions by whether they're applied automatically. + */ is_automatic?: boolean + + /** + * Filter promotions by their type. + */ type?: PromotionTypeValues[] } diff --git a/packages/types/src/promotion/mutations.ts b/packages/types/src/promotion/mutations.ts index cef6b28b29..e5c8a0cb47 100644 --- a/packages/types/src/promotion/mutations.ts +++ b/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[] } +/** + * 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 + + /** + * The promotions of the campaign. + */ promotions?: Pick[] } diff --git a/packages/types/src/promotion/service.ts b/packages/types/src/promotion/service.ts index 5a9cfb5025..37855478ff 100644 --- a/packages/types/src/promotion/service.ts +++ b/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} 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 + /** + * 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} options - Any relevant options that may change how the actions are computed. + * @returns {Promise} 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 ): Promise + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} The updated promotions. + * + * @example + * const promotions = await promotionModuleService.update([ + * { + * id: "promo_123", + * is_automatic: true, + * }, + * ]) + */ update( data: UpdatePromotionDTO[], sharedContext?: Context ): Promise + /** + * 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} The updated promotion. + * + * @example + * const promotion = await promotionModuleService.update({ + * id: "promo_123", + * is_automatic: true, + * }) + */ update( data: UpdatePromotionDTO, sharedContext?: Context ): Promise + /** + * 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} 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} 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, sharedContext?: Context ): Promise + /** + * 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} 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, sharedContext?: Context ): Promise<[PromotionDTO[], number]> + /** + * This method retrieves a promotion by its ID. + * + * @param {string} id - The ID of the promotion. + * @param {FindConfig} 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} 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, sharedContext?: Context ): Promise + /** + * 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} Resolves when the promotions are deleted. + * + * @example + * await promotionModuleService.delete([ + * "promo_123", + * "promo_321", + * ]) + */ delete(ids: string[], sharedContext?: Context): Promise + + /** + * 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} Resolves when the promotion is deleted. + * + * @example + * await promotionModuleService.delete("promo_123") + */ delete(ids: string, sharedContext?: Context): Promise + /** + * This method soft deletes a promotion by its IDs. + * + * @param {string | string[]} promotionIds - The list of promotions to soft delete. + * @param {SoftDeleteReturn} 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>} 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( promotionIds: string | string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** + * This method restores soft deleted promotions by their IDs. + * + * @param {string | string[]} promotionIds - The promotions' IDs. + * @param {RestoreReturn} 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>} 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( promotionIds: string | string[], config?: RestoreReturn, sharedContext?: Context ): Promise | 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} 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 + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} 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 + /** + * 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} The updated campaigns. + * + * @example + * const campaigns = + * await promotionModuleService.updateCampaigns([ + * { + * id: "procamp_123", + * name: "Summer Sales", + * }, + * ]) + */ updateCampaigns( data: UpdateCampaignDTO[], sharedContext?: Context ): Promise + /** + * 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} The updated campaign. + * + * @example + * const campaigns = + * await promotionModuleService.updateCampaigns({ + * id: "procamp_123", + * name: "Summer Sales", + * }) + */ updateCampaigns( data: UpdateCampaignDTO, sharedContext?: Context ): Promise + /** + * 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} 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} 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, sharedContext?: Context ): Promise + /** + * 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} The updated promotion rules. + * + * @example + * const promotionRules = + * await promotionModuleService.updatePromotionRules([ + * { + * id: "prorul_123", + * description: "Only allow VIP customers", + * }, + * ]) + */ updatePromotionRules( data: UpdatePromotionRuleDTO[], sharedContext?: Context ): Promise + /** + * 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} 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} 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, sharedContext?: Context ): Promise + /** + * 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} 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, sharedContext?: Context ): Promise<[CampaignDTO[], number]> + /** + * This method retrieves a campaigns by its ID. + * + * @param {string} id - The ID of the campaigns. + * @param {FindConfig} 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} 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, sharedContext?: Context ): Promise + /** + * 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} Resolves when the campaigns are deleted successfully. + * + * @example + * await promotionModuleService.deleteCampaigns(["procamp_123"]) + */ deleteCampaigns(ids: string[], sharedContext?: Context): Promise + + /** + * 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} Resolves when the campaign is deleted successfully. + * + * @example + * await promotionModuleService.deleteCampaigns("procamp_123") + */ deleteCampaigns(ids: string, sharedContext?: Context): Promise + /** + * This method soft deletes campaigns by their IDs. + * + * @param {string | string[]} campaignIds - The IDs of the campaigns. + * @param {SoftDeleteReturn} 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>} 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( campaignIds: string | string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** + * This method restores soft deleted campaigns by their IDs. + * + * @param {string | string[]} campaignIds - The IDs of the campaigns + * @param {RestoreReturn} 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>} 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( campaignIds: string | string[], config?: RestoreReturn,