asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Shahed Nasser
2024-04-05 13:06:35 +03:00
committed by GitHub
parent 0a8718f0c5
commit bde80a8371
9 changed files with 1559 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
packages/types/src/promotion/common/application-method.ts
View File

@@ -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[]
}

41
packages/types/src/promotion/common/campaign-budget.ts
View File

@@ -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[]
}

44
packages/types/src/promotion/common/campaign.ts
View File

@@ -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[]
}

156
packages/types/src/promotion/common/compute-actions.ts
View File

@@ -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
}

32
packages/types/src/promotion/common/promotion-rule-value.ts
View File

@@ -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[]
}

88
packages/types/src/promotion/common/promotion-rule.ts
View File

@@ -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"

121
packages/types/src/promotion/common/promotion.ts
View File

@@ -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[]
}

104
packages/types/src/promotion/mutations.ts
View File

@@ -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">[]
}

788
packages/types/src/promotion/service.ts
View File

@@ -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>,