chore: update tsdocs of pricing module (#5648)

* chore: update tsdocs of pricing module

* Update money-amount.ts

---------

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>

packages/types/src/pricing/common/currency.ts

@@ -4,17 +4,23 @@ import { BaseFilterable } from "../../dal"
  * @interface
  * 
  * A currency's data.
- * 
- * @prop code - The code of the currency.
- * @prop symbol - The symbol of the currency.
- * @prop symbol_native - 
- * The symbol of the currecy in its native form. This is typically the symbol used when displaying a price.
- * @prop name - The name of the currency.
  */
 export interface CurrencyDTO {
+  /**
+   * The code of the currency.
+   */
   code: string
+  /**
+   * The symbol of the currency.
+   */
   symbol?: string
+  /**
+   * The symbol of the currecy in its native form. This is typically the symbol used when displaying a price.
+   */
   symbol_native?: string
+  /**
+   * The name of the currency.
+   */
   name?: string
 }
 
@@ -22,17 +28,23 @@ export interface CurrencyDTO {
  * @interface
  * 
  * A currency to create.
- * 
- * @prop code - The code of the currency.
- * @prop symbol - The symbol of the currency.
- * @prop symbol_native - 
- * The symbol of the currecy in its native form. This is typically the symbol used when displaying a price.
- * @prop name - The name of the currency.
  */
 export interface CreateCurrencyDTO {
+  /**
+   * The code of the currency.
+   */
   code: string
+  /**
+   * The symbol of the currency.
+   */
   symbol: string
+  /**
+   * The symbol of the currecy in its native form. This is typically the symbol used when displaying a price.
+   */
   symbol_native: string
+  /**
+   * The name of the currency.
+   */
   name: string
 }
 
@@ -40,17 +52,23 @@ export interface CreateCurrencyDTO {
  * @interface
  * 
  * The data to update in a currency. The `code` is used to identify which currency to update.
- * 
- * @prop code - The code of the currency to update.
- * @prop symbol - The symbol of the currency.
- * @prop symbol_native - 
- * The symbol of the currecy in its native form. This is typically the symbol used when displaying a price.
- * @prop name - The name of the currency.
  */
 export interface UpdateCurrencyDTO {
+  /**
+   * The code of the currency to update.
+   */
   code: string
+  /**
+   * The symbol of the currency.
+   */
   symbol?: string
+  /**
+   * The symbol of the currecy in its native form. This is typically the symbol used when displaying a price.
+   */
   symbol_native?: string
+  /**
+   * The name of the currency.
+   */
   name?: string
 }
 
@@ -58,10 +76,11 @@ export interface UpdateCurrencyDTO {
  * @interface
  * 
  * Filters to apply on a currency.
- * 
- * @prop code - The codes to filter the currencies by.
  */
 export interface FilterableCurrencyProps
   extends BaseFilterable<FilterableCurrencyProps> {
+  /**
+   * The codes to filter the currencies by.
+   */
   code?: string[]
 }

packages/types/src/pricing/common/money-amount.ts

@@ -6,21 +6,39 @@ import { PriceSetMoneyAmountDTO } from "./price-set-money-amount";
  * @interface
  *
  * A money amount's data. A money amount represents a price.
- *
- * @prop id - The ID of the money amount.
- * @prop currency_code - The currency code of this money amount.
- * @prop currency - The money amount's currency. Since this is a relation, it will only be retrieved if it's passed to the `relations` array of the find-configuration options.
- * @prop amount - The price of this money amount.
- * @prop min_quantity - The minimum quantity required to be purchased for this price to be applied.
- * @prop max_quantity - The maximum quantity required to be purchased for this price to be applied.
  */
 export interface MoneyAmountDTO {
+  /**
+   * The ID of the money amount.
+   */
   id: string
+  /**
+   * The currency code of this money amount.
+   */
   currency_code?: string
+  /**
+   * The money amount's currency.
+   * 
+   * @expandable
+   */
   currency?: CurrencyDTO
+  /**
+   * The price of this money amount.
+   */
   amount?: number
+  /**
+   * The minimum quantity required to be purchased for this price to be applied.
+   */
   min_quantity?: number
+  /**
+   * The maximum quantity required to be purchased for this price to be applied.
+   */
   max_quantity?: number
+  /**
+   * The details of the relation between the money amount and its associated price set.
+   * 
+   * @expandable
+   */
   price_set_money_amount?: PriceSetMoneyAmountDTO
 }
 
@@ -28,40 +46,59 @@ export interface MoneyAmountDTO {
  * @interface
  *
  * The money amount to create.
- *
- * @prop id - The ID of the money amount.
- * @prop currency_code - The currency code of this money amount.
- * @prop currency - The currency of this money amount.
- * @prop amount - The amount of this money amount.
- * @prop min_quantity - The minimum quantity required to be purchased for this money amount to be applied.
- * @prop max_quantity - The maximum quantity required to be purchased for this money amount to be applied.
  */
 export interface CreateMoneyAmountDTO {
+  /**
+   * The ID of the money amount.
+   */
   id?: string
+  /**
+   * The currency code of this money amount.
+   */
   currency_code: string
+  /**
+   * The currency of this money amount.
+   */
   currency?: CreateCurrencyDTO
+  /**
+   * The amount of this money amount.
+   */
   amount: number
+  /**
+   * The minimum quantity required to be purchased for this money amount to be applied.
+   */
   min_quantity?: number | null
+  /**
+   * The maximum quantity required to be purchased for this money amount to be applied.
+   */
   max_quantity?: number | null
 }
 
 /**
- *  * @interface
+ * @interface
  *
  * The data to update in a money amount. The `id` is used to identify which money amount to update.
- *
- * @prop id - The ID of the money amount to update.
- * @prop currency_code - The code of the currency to associate with the money amount.
- * @prop currency - The currency to associte with the money amount.
- * @prop amount - The price of this money amount.
- * @prop min_quantity - The minimum quantity required to be purchased for this money amount to be applied.
- * @prop max_quantity - The maximum quantity required to be purchased for this money amount to be applied.
  */
 export interface UpdateMoneyAmountDTO {
+  /**
+   * The ID of the money amount to update.
+   */
   id: string
+  /**
+   * The code of the currency to associate with the money amount.
+   */
   currency_code?: string
+  /**
+   * The price of this money amount.
+   */
   amount?: number
+  /**
+   * The minimum quantity required to be purchased for this money amount to be applied.
+   */
   min_quantity?: number
+  /**
+   * The maximum quantity required to be purchased for this money amount to be applied.
+   */
   max_quantity?: number
 }
 
@@ -69,12 +106,15 @@ export interface UpdateMoneyAmountDTO {
  * @interface
  *
  * Filters to apply on a money amount.
- *
- * @prop id - IDs to filter money amounts by.
- * @prop currency_code - Currency codes to filter money amounts by.
  */
 export interface FilterableMoneyAmountProps
   extends BaseFilterable<FilterableMoneyAmountProps> {
+  /**
+   * IDs to filter money amounts by.
+   */
   id?: string[]
+  /**
+   * Currency codes to filter money amounts by.
+   */
   currency_code?: string | string[]
 }

packages/types/src/pricing/common/price-list.ts

@@ -4,72 +4,254 @@ import { BaseFilterable } from "../../dal"
 import { PriceSetMoneyAmountDTO } from "./price-set-money-amount"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @enum
+ * 
+ * The price list's status.
+ */
 export enum PriceListStatus {
+  /**
+   * The price list is enabled and its prices can be used.
+   */
   ACTIVE = "active",
+  /**
+   * The price list is disabled, meaning its prices can't be used yet.
+   */
   DRAFT = "draft",
 }
 
+/**
+ * @enum
+ * 
+ * The price list's type.
+ */
 export enum PriceListType {
+  /**
+   * The price list's prices are used for a sale.
+   */
   SALE = "sale",
+  /**
+   * The price list's prices override original prices. This affects the calculated price of associated price sets.
+   */
   OVERRIDE = "override",
 }
 
+/**
+ * @interface
+ * 
+ * A price list's details.
+ */
 export interface PriceListDTO {
+  /**
+   * The price list's ID.
+   */
   id: string
+  /**
+   * The price list's title.
+   */
   title?: string
+  /**
+   * The price list is enabled starting from this date.
+   */
   starts_at?: string | null
+  /**
+   * The price list's status.
+   */
   status?: PriceListStatus
+  /**
+   * The price list expires after this date.
+   */
   ends_at?: string | null
+  /**
+   * The number of rules associated with this price list.
+   */
   number_rules?: number
+  /**
+   * The associated price set money amounts.
+   * 
+   * @expandable
+   */
   price_set_money_amounts?: PriceSetMoneyAmountDTO[]
+  /**
+   * The associated money amounts.
+   * 
+   * @expandable
+   */
   money_amounts?: MoneyAmountDTO[]
+  /**
+   * The associated rule types.
+   * 
+   * @expandable
+   */
   rule_types?: RuleTypeDTO[]
+  /**
+   * The price set's rules.
+   * 
+   * @expandable
+   */
   rules?: PriceListRuleDTO[]
+  /**
+   * The price set's rules.
+   * 
+   * @privateRemarks
+   * Do we need both this and `rules`?
+   * 
+   * @expandable
+   */
   price_list_rules?: PriceListRuleDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * The prices associated with a price list.
+ */
 export interface PriceListPriceDTO extends CreateMoneyAmountDTO {
+  /**
+   * The ID of the associated price set.
+   */
   price_set_id: string
 }
 
+/**
+ * @interface
+ * 
+ * The price list's rules to be set. Each key of the object is a rule type's `rule_attribute`, and its value
+   * is the values of the rule.
+ */
 export interface CreatePriceListRules extends Record<string, string[]> {}
 
+/**
+ * @interface
+ * 
+ * The price list to create.
+ */
 export interface CreatePriceListDTO {
+  /**
+   * The price list's title.
+   */
   title: string
+  /**
+   * The price list's description.
+   */
   description: string
+  /**
+   * The price list is enabled starting from this date.
+   */
   starts_at?: string
+  /**
+   * The price list expires after this date.
+   */
   ends_at?: string
+  /**
+   * The price list's status.
+   */
   status?: PriceListStatus
+  /**
+   * The price list's type.
+   */
   type?: PriceListType
+  /**
+   * The number of rules associated with the price list.
+   */
   number_rules?: number
+  /**
+   * The rules to be created and associated with the price list.
+   */
   rules?: CreatePriceListRules
+  /**
+   * The prices associated with the price list.
+   */
   prices?: PriceListPriceDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * The attributes to update in a price list.
+ */
 export interface UpdatePriceListDTO {
+  /**
+   * The ID of the price list to update.
+   */
   id: string
+  /**
+   * The price list's title.
+   */
   title?: string
+  /**
+   * The price list is enabled starting from this date.
+   */
   starts_at?: string
+  /**
+   * The price list expires after this date.
+   */
   ends_at?: string
+  /**
+   * The price list's status.
+   */
   status?: PriceListStatus
+  /**
+   * The number of rules associated with the price list.
+   */
   number_rules?: number
+  /**
+   * The rules to be created and associated with the price list.
+   */
   rules?: CreatePriceListRules
 }
 
+/**
+ * @inteface
+ * 
+ * Filters to apply on price lists.
+ */
 export interface FilterablePriceListProps
   extends BaseFilterable<FilterablePriceListProps> {
+  /**
+   * The IDs to filter price lists by
+   */
   id?: string[]
+  /**
+   * The start dates to filter price lists by.
+   */
   starts_at?: string[]
+  /**
+   * The end dates to filter price lists by.
+   */
   ends_at?: string[]
+  /**
+   * The statuses to filter price lists by.
+   */
   status?: PriceListStatus[]
+  /**
+   * The number of rules to filter price lists by.
+   */
   number_rules?: number[]
 }
 
+/**
+ * @interface
+ * 
+ * Filters to apply on price list rules.
+ */
 export interface FilterablePriceListRuleProps
   extends BaseFilterable<FilterablePriceListRuleProps> {
+  /**
+   * The IDs to filter price list rules by.
+   */
   id?: string[]
+  /**
+   * The values to filter price list rules by.
+   */
   value?: string[]
+  /**
+   * Filter price list rules by the ID of their associated rule types.
+   */
   rule_type?: string[]
+  /**
+   * Filter price list rules by the ID of their associated price lists.
+   */
   price_list_id?: string[]
 }
 
@@ -80,32 +262,114 @@ export interface FilterablePriceListRuleValueProps
   price_list_rule_id?: string[]
 }
 
+/**
+ * @interface
+ * 
+ * The price list rule's details.
+ */
 export interface PriceListRuleDTO {
+  /**
+   * The price list rule's ID.
+   */
   id: string
+  /**
+   * The value of the rule.
+   * 
+   * @privateRemarks
+   * Shouldn't this be in PriceListRuleValueDTO only?
+   */
   value: string
+  /**
+   * The associated rule type.
+   * 
+   * @expandable
+   */
   rule_type: RuleTypeDTO
+  /**
+   * The associated price list.
+   * 
+   * @expandable
+   */
   price_list: PriceListDTO
+  /**
+   * The associated rule values.
+   * 
+   * @expandable
+   */
   price_list_rule_values?: PriceListRuleValueDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * The price list rule to create.
+ */
 export interface CreatePriceListRuleDTO {
+  /**
+   * The ID of a rule type to be associated with the price list rule.
+   */
   rule_type_id?: string
+  /**
+   * The ID of a rule type or the details of an existing rule type to be associated with the price list rule.
+   */
   rule_type?: string | RuleTypeDTO
+  /**
+   * The ID of a price list to be associated with the price list rule.
+   */
   price_list_id?: string
+  /**
+   * The ID of a price list or the details of an existing price list to be associated with the price list rule.
+   */
   price_list?: string | PriceListDTO
 }
 
+/**
+ * @interface
+ * 
+ * The attributes to update in a price list rule.
+ */
 export interface UpdatePriceListRuleDTO {
+  /**
+   * The ID of the price list rule to update.
+   */
   id: string
+  /**
+   * The ID of a price list to be associated with the price list rule.
+   */
   price_list_id?: string
+  /**
+   * The ID of a rule type to be associated with the price list rule.
+   */
   rule_type_id?: string
+  /**
+   * The ID of a price list to be associated with the price list rule.
+   */
   price_list?: string
+  /**
+   * The ID of a rule type or the details of an existing rule type to be associated with the price list rule.
+   */
   rule_type?: string
 }
 
+/**
+ * @interface
+ * 
+ * The price list rule value's details.
+ */
 export interface PriceListRuleValueDTO {
+  /**
+   * The price list rule value's ID.
+   */
   id: string
+  /**
+   * The rule's value.
+   */
   value: string
+  /**
+   * The associated price list rule.
+   * 
+   * @expandable
+   */
   price_list_rule: PriceListRuleDTO
 }
 
@@ -121,17 +385,51 @@ export interface UpdatePriceListRuleValueDTO {
   price_list_rule_id: string
 }
 
+/**
+ * @interface
+ * 
+ * The prices to be added to a price list.
+ */
 export interface AddPriceListPricesDTO {
+  /**
+   * The ID of the price list to add prices to.
+   */
   priceListId: string
+  /**
+   * The prices to add.
+   */
   prices: PriceListPriceDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * The rules to add to a price list.
+ */
 export interface SetPriceListRulesDTO {
+  /**
+   * The ID of the price list to add rules to.
+   */
   priceListId: string
+  /**
+   * The rules to add to the price list. Each key of the object is a rule type's `rule_attribute`, and its value
+   * is the value(s) of the rule.
+   */
   rules: Record<string, string | string[]>
 }
 
+/**
+ * @interface
+ * 
+ * The rules to remove from a price list.
+ */
 export interface RemovePriceListRulesDTO {
+  /**
+   * The ID of the price list to remove rules from.
+   */
   priceListId: string
+  /**
+   * The rules to remove from the price list. Each item being a rule type's `rule_attribute`.
+   */
   rules: string[]
 }

packages/types/src/pricing/common/price-rule.ts

@@ -6,33 +6,54 @@ import { RuleTypeDTO } from "./rule-type"
  * @interface
  * 
  * A price rule's data.
- * 
- * @prop id - The ID of the price rule.
- * @prop price_set_id - The ID of the associated price set.
- * @prop price_set - The associated price set. It may only be available if the relation `price_set` is expanded.
- * @prop rule_type_id - The ID of the associated rule type.
- * @prop rule_type - The associated rule type. It may only be available if the relation `rule_type` is expanded.
- * @prop value - The value of the price rule.
- * @prop priority - The priority of the price rule in comparison to other applicable price rules.
- * @prop price_set_money_amount_id - The ID of the associated price set money amount.
- * @prop price_list_id - The ID of the associated price list.
  */
 export interface PriceRuleDTO {
+  /**
+   * The ID of the price rule.
+   */
   id: string
+  /**
+   * The ID of the associated price set.
+   */
   price_set_id: string
+  /**
+   * The associated price set.
+   * 
+   * @expandable
+   */
   price_set: PriceSetDTO
+  /**
+   * The ID of the associated rule type.
+   */
   rule_type_id: string
+  /**
+   * The associated rule type.
+   * 
+   * @expandable
+   */
   rule_type: RuleTypeDTO
   /** 
    * @ignore
-   * @privateRemark
+   * @privateRemarks
    * 
    * Behavior behind this property is not implemented yet.
    */
   is_dynamic: boolean
+  /**
+   * The value of the price rule.
+   */
   value: string
+  /**
+   * The priority of the price rule in comparison to other applicable price rules.
+   */
   priority: number
+  /**
+   * The ID of the associated price set money amount.
+   */
   price_set_money_amount_id: string
+  /**
+   * The ID of the associated price list.
+   */
   price_list_id: string
 }
 
@@ -41,26 +62,30 @@ export interface PriceRuleDTO {
  * @interface
  * 
  * A price rule to create.
- * 
- * @prop id - The ID of the price rule.
- * @prop price_set_id - The ID of the associated price set.
- * @prop rule_type_id - The ID of the associated rule type.
- * @prop value - The value of the price rule.
- * @prop priority - The priority of the price rule in comparison to other applicable price rules.
- * @prop price_set_money_amount_id - The ID of the associated price set money amount.
- * @prop price_list_id - The ID of the associated price list.
  */
 export interface CreatePriceRuleDTO {
+  /**
+   * The ID of the price rule.
+   */
   id: string
+  /**
+   * The ID of the associated price set.
+   */
   price_set_id: string
+  /**
+   * The ID of the associated rule type.
+   */
   rule_type_id: string
   /** 
    * @ignore
-   * @privateRemark
+   * @privateRemarks
    * 
    * Behavior behind this property is not implemented yet.
    */
   is_dynamic?: boolean
+  /**
+   * The value of the price rule.
+   */
   value: string
   priority?: number
   price_set_money_amount_id: string
@@ -71,14 +96,6 @@ export interface CreatePriceRuleDTO {
  * @interface
  * 
  * The data to update in a price rule. The `id` is used to identify which money amount to update.
- * 
- * @prop id - The ID of the price rule to update.
- * @prop price_set_id - The ID of the associated price set.
- * @prop rule_type_id - The ID of the associated rule type.
- * @prop value - The value of the price rule.
- * @prop priority - The priority of the price rule in comparison to other applicable price rules.
- * @prop price_set_money_amount_id - The ID of the associated price set money amount.
- * @prop price_list_id - The ID of the associated price list.
  */
 export interface UpdatePriceRuleDTO {
   id: string
@@ -91,26 +108,45 @@ export interface UpdatePriceRuleDTO {
    * Behavior behind this property is not implemented yet.
    */
   is_dynamic?: boolean
+  /**
+   * The value of the price rule.
+   */
   value?: string
+  /**
+   * The priority of the price rule in comparison to other applicable price rules.
+   */
   priority?: number
+  /**
+   * The ID of the associated price set money amount.
+   */
   price_set_money_amount_id?: string
+  /**
+   * The ID of the associated price list.
+   */
   price_list_id?: string
 }
 
 /**
  * @interface
  * 
- * Filters to apply to price rules.
+ * Filters to apply on price rules.
- * 
- * @prop id - The IDs to filter price rules by.
- * @prop name - The names to filter price rules by.
- * @prop price_set_id - The IDs to filter the price rule's associated price set.
- * @prop rule_type_id - The IDs to filter the price rule's associated rule type.
  */
 export interface FilterablePriceRuleProps
   extends BaseFilterable<FilterablePriceRuleProps> {
+  /**
+   * The IDs to filter price rules by.
+   */
   id?: string[]
+  /**
+   * The names to filter price rules by.
+   */
   name?: string[]
+  /**
+   * The IDs to filter the price rule's associated price set.
+   */
   price_set_id?: string[]
+  /**
+   * The IDs to filter the price rule's associated rule type.
+   */
   rule_type_id?: string[]
 }

packages/types/src/pricing/common/price-set-money-amount-rules.ts

@@ -6,16 +6,27 @@ import { RuleTypeDTO } from "./rule-type"
  * @interface
  * 
  * A price set money amount rule's data.
- * 
- * @prop id - The ID of the price set money amount.
- * @prop price_set_money_amount - The associated price set money amount. It may only be available if the relation `price_set_money_amount` is expanded.
- * @prop rule_type - The associated rule type. It may only be available if the relation `rule_type` is expanded.
- * @prop value - The value of the price set money amount rule.
  */
 export interface PriceSetMoneyAmountRulesDTO {
+  /**
+   * The ID of the price set money amount.
+   */
   id: string
+  /**
+   * The associated price set money amount.
+   * 
+   * @expandable
+   */
   price_set_money_amount: PriceSetMoneyAmountDTO
+  /**
+   * The associated rule type.
+   * 
+   * @expandable
+   */
   rule_type: RuleTypeDTO
+  /**
+   * The value of the price set money amount rule.
+   */
   value: string
 }
 
@@ -23,14 +34,19 @@ export interface PriceSetMoneyAmountRulesDTO {
  * @interface
  * 
  * The price set money amount rule to create.
- * 
- * @prop price_set_money_amount - The ID of a price set money amount.
- * @prop rule_type - The ID of a rule type.
- * @prop value - The value of the price set money amount rule.
  */
 export interface CreatePriceSetMoneyAmountRulesDTO {
+  /**
+   * The ID of a price set money amount.
+   */
   price_set_money_amount: string
+  /**
+   * The ID of a rule type.
+   */
   rule_type: string
+  /**
+   * The value of the price set money amount rule.
+   */
   value: string
 }
 
@@ -38,16 +54,23 @@ export interface CreatePriceSetMoneyAmountRulesDTO {
  * @interface
  * 
  * The data to update in a price set money amount rule. The `id` is used to identify which money amount to update.
- * 
- * @prop id - The ID of the price set money amount rule to update.
- * @prop price_set_money_amount - The ID of a price set money amount.
- * @prop rule_type - The ID of a rule type.
- * @prop value - The value of the price set money amount rule.
  */
 export interface UpdatePriceSetMoneyAmountRulesDTO {
+  /**
+   * The ID of the price set money amount rule to update.
+   */
   id: string
+  /**
+   * The ID of a price set money amount.
+   */
   price_set_money_amount?: string
+  /**
+   * The ID of a rule type.
+   */
   rule_type?: string
+  /**
+   * The value of the price set money amount rule.
+   */
   value?: string
 }
 
@@ -55,16 +78,23 @@ export interface UpdatePriceSetMoneyAmountRulesDTO {
  * @interface
  * 
  * Filters to apply on price set money amount rules.
- * 
- * @prop id - The ID to filter price set money amount rules by.
- * @prop rule_type_id - The IDs to filter the price set money amount rule's associated rule type.
- * @prop price_set_money_amount_id - The IDs to filter the price set money amount rule's associated price set money amount.
- * @prop value - The value to filter price set money amount rules by.
  */
 export interface FilterablePriceSetMoneyAmountRulesProps
   extends BaseFilterable<FilterablePriceSetMoneyAmountRulesProps> {
+  /**
+   * The ID to filter price set money amount rules by.
+   */
   id?: string[]
+  /**
+   * The IDs to filter the price set money amount rule's associated rule type.
+   */
   rule_type_id?: string[]
+  /**
+   * The IDs to filter the price set money amount rule's associated price set money amount.
+   */
   price_set_money_amount_id?: string[]
+  /**
+   * The value to filter price set money amount rules by.
+   */
   value?: string[]
 }

packages/types/src/pricing/common/price-set-money-amount.ts

@@ -8,19 +8,43 @@ import { PriceSetDTO } from "./price-set"
  * @interface
  *
  * A price set money amount's data.
- *
- * @prop id - The ID of a price set money amount.
- * @prop title - The title of the price set money amount.
- * @prop price_set - The price set associated with the price set money amount. It may only be available if the relation `price_set` is expanded.
- * @prop money_amount - The money amount associated with the price set money amount. It may only be available if the relation `money_amount` is expanded.
  */
 export interface PriceSetMoneyAmountDTO {
+  /**
+   * The ID of a price set money amount.
+   */
   id: string
+  /**
+   * The title of the price set money amount.
+   */
   title?: string
+  /**
+   * The price set associated with the price set money amount.
+   * 
+   * @expandable
+   */
   price_set?: PriceSetDTO
+  /**
+   * The price list associated with the price set money amount.
+   * 
+   * @expandable
+   */
   price_list?: PriceListDTO
+  /**
+   * The ID of the associated price set.
+   */
   price_set_id?: string
+  /**
+   * The price rules associated with the price set money amount.
+   * 
+   * @expandable
+   */
   price_rules?: PriceRuleDTO[]
+  /**
+   * The money amount associated with the price set money amount.
+   * 
+   * @expandable
+   */
   money_amount?: MoneyAmountDTO
 }
 
@@ -42,13 +66,19 @@ export interface CreatePriceSetMoneyAmountDTO {
  * @interface
  *
  * Filters to apply on price set money amounts.
- *
- * @prop id - The IDs to filter the price set money amounts by.
- * @prop price_set_id - The IDs to filter the price set money amount's associated price set.
  */
 export interface FilterablePriceSetMoneyAmountProps
   extends BaseFilterable<FilterablePriceSetMoneyAmountProps> {
+  /**
+   * The IDs to filter the price set money amounts by.
+   */
   id?: string[]
+  /**
+   * The IDs to filter the price set money amount's associated price set.
+   */
   price_set_id?: string[]
+  /**
+   * The IDs to filter the price set money amount's associated price list.
+   */
   price_list_id?: string[]
 }

packages/types/src/pricing/common/price-set.ts

@@ -7,12 +7,12 @@ import { RuleTypeDTO } from "./rule-type";
  *
  * The context to calculate prices. For example, you can specify the currency code to calculate prices in.
  *
- * @prop context -
- * an object whose keys are the name of the context attribute. Its value can be a string or a number. For example, you can pass the `currency_code` property with its value being the currency code to calculate the price in.
- * Another example is passing the `quantity` property to calculate the price for that specified quantity, which finds a price set whose `min_quantity` and `max_quantity` conditions match the specified quantity.
- *
  */
 export interface PricingContext {
+  /**
+   * an object whose keys are the name of the context attribute. Its value can be a string or a number. For example, you can pass the `currency_code` property with its value being the currency code to calculate the price in.
+   * Another example is passing the `quantity` property to calculate the price for that specified quantity, which finds a price set whose `min_quantity` and `max_quantity` conditions match the specified quantity.
+   */
   context?: Record<string, string | number>
 }
 
@@ -20,10 +20,11 @@ export interface PricingContext {
  * @interface
  *
  * Filters to apply on prices.
- *
- * @prop id - IDs to filter prices.
  */
 export interface PricingFilters {
+  /**
+   * IDs to filter prices.
+   */
   id: string[]
 }
 
@@ -31,15 +32,19 @@ export interface PricingFilters {
  * @interface
  *
  * A price set's data.
- *
- * @prop id - The ID of the price set.
- * @prop money_amounts - The prices that belong to this price set.
- * @prop rule_types - The rule types applied on this price set.
- *
  */
 export interface PriceSetDTO {
+  /**
+   * The ID of the price set.
+   */
   id: string
+  /**
+   * The prices that belong to this price set.
+   */
   money_amounts?: MoneyAmountDTO[]
+  /**
+   * The rule types applied on this price set.
+   */
   rule_types?: RuleTypeDTO[]
 }
 
@@ -47,47 +52,129 @@ export interface PriceSetDTO {
  * @interface
  *
  * A calculated price set's data.
- *
+ * 
- * @prop id - The ID of the price set.
+ * @privateRemarks
- * @prop amount - The calculated amount. It can possibly be `null` if there's no price set up for the provided context.
+ * Do we still need this type? Shouldn't we use CalculatedPriceSet instead?
- * @prop currency_code - The currency code of the calculated price. It can possibly be `null`.
- * @prop min_quantity - The minimum quantity required to be purchased for this price to apply. It's set if the `quantity` property is provided in the context. Otherwise, its value will be `null`.
- * @prop max_quantity - The maximum quantity required to be purchased for this price to apply. It's set if the `quantity` property is provided in the context. Otherwise, its value will be `null`.
  */
 export interface CalculatedPriceSetDTO {
+  /**
+   * The ID of the money amount.
+   */
   id: string
+  /**
+   * The ID of the associated price set.
+   */
   price_set_id: string
+  /**
+   * The calculated amount. It can possibly be `null` if there's no price set up for the provided context.
+   */
   amount: string | null
+  /**
+   * The currency code of the calculated price. It can possibly be `null`.
+   */
   currency_code: string | null
+  /**
+   * The minimum quantity required to be purchased for this price to apply. It's set if the `quantity` property is provided in the context. Otherwise, its value will be `null`.
+   */
   min_quantity: string | null
+  /**
+   * The maximum quantity required to be purchased for this price to apply. It's set if the `quantity` property is provided in the context. Otherwise, its value will be `null`.
+   */
   max_quantity: string | null
+  /**
+   * The type of the associated price list, if any.
+   */
   price_list_type: string | null
+  /**
+   * The ID of the associated price list, if any.
+   */
   price_list_id: string | null
 }
 
+/**
+ * @interface
+ * 
+ * The calculated price for a specific price set and context.
+ */
 export interface CalculatedPriceSet {
+  /**
+   * The ID of the price set.
+   */
   id: string
+  /**
+   * Whether the calculated price is associated with a price list. During the calculation process, if no valid price list is found, 
+   * the calculated price is set to the original price, which doesn't belong to a price list. In that case, the value of this property is `false`.
+   */
   is_calculated_price_price_list?: boolean
+  /**
+   * The amount of the calculated price, or `null` if there isn't a calculated price.
+   */
   calculated_amount: number | null
 
+  /**
+   * Whether the original price is associated with a price list. During the calculation process, if the price list of the calculated price is of type override, 
+   * the original price will be the same as the calculated price. In that case, the value of this property is `true`.
+   */
   is_original_price_price_list?: boolean
+  /**
+   * The amount of the original price, or `null` if there isn't a calculated price.
+   */
   original_amount: number | null
 
+  /**
+   * The currency code of the calculated price, or null if there isn't a calculated price.
+   */
   currency_code: string | null
 
+  /**
+   * The details of the calculated price.
+   */
   calculated_price?: {
+    /**
+     * The ID of the money amount selected as the calculated price.
+     */
     money_amount_id: string | null
+    /**
+     * The ID of the associated price list, if any.
+     */
     price_list_id: string | null
+    /**
+     * The type of the associated price list, if any.
+     */
     price_list_type: string | null
+    /**
+     * The `min_quantity` field defined on a money amount.
+     */
     min_quantity: number | null
+    /**
+     * The `max_quantity` field defined on a money amount.
+     */
     max_quantity: number | null
   }
 
+  /**
+   * The details of the original price.
+   */
   original_price?: {
+    /**
+     * The ID of the money amount selected as the original price.
+     */
     money_amount_id: string | null
+    /**
+     * The ID of the associated price list, if any.
+     */
     price_list_id: string | null
+    /**
+     * The type of the associated price list, if any.
+     */
     price_list_type: string | null
+    /**
+     * The `min_quantity` field defined on a money amount.
+     */
     min_quantity: number | null
+    /**
+     * The `max_quantity` field defined on a money amount.
+     */
     max_quantity: number | null
   }
 }
@@ -96,23 +183,32 @@ export interface CalculatedPriceSet {
  * @interface
  *
  * The rules to add to a price set.
- *
- * @prop priceSetId - The ID of the price set to add the rules to.
- * @prop rules - The rules to add to a price set. The value of `attribute` is the value of the rule's `rule_attribute` attribute.
  */
 export interface AddRulesDTO {
+  /**
+   * The ID of the price set to add the rules to.
+   */
   priceSetId: string
-  rules: { attribute: string }[]
+  /**
+   * The rules to add to a price set.
+   */
+  rules: { 
+    /**
+     * The value of the rule's `rule_attribute` attribute.
+     */
+    attribute: string
+  }[]
 }
 
 /**
  * @interface
  *
  * The prices to create part of a price set.
- *
- * @prop rules - The rules to add to the price. The object's keys are rule types' `rule_attribute` attribute, and values are the value of that rule associated with this price.
  */
 export interface CreatePricesDTO extends CreateMoneyAmountDTO {
+  /**
+   * The rules to add to the price. The object's keys are rule types' `rule_attribute` attribute, and values are the value of that rule associated with this price.
+   */
   rules: Record<string, string>
 }
 
@@ -120,12 +216,15 @@ export interface CreatePricesDTO extends CreateMoneyAmountDTO {
  * @interface
  *
  * The prices to add to a price set.
- *
- * @prop priceSetId - The ID of the price set to add prices to.
- * @prop prices - The prices to add to the price set.
  */
 export interface AddPricesDTO {
+  /**
+   * The ID of the price set to add prices to.
+   */
   priceSetId: string
+  /**
+   * The prices to add to the price set.
+   */
   prices: CreatePricesDTO[]
 }
 
@@ -133,12 +232,15 @@ export interface AddPricesDTO {
  * @interface
  *
  * The rules to remove from a price set.
- *
- * @prop id - The ID of the price set.
- * @prop rules - The rules to remove. Each string is the `rule_attribute` of a rule to remove.
  */
 export interface RemovePriceSetRulesDTO {
+  /**
+   * The ID of the price set.
+   */
   id: string
+  /**
+   * The rules to remove. Each string is the `rule_attribute` of a rule to remove.
+   */
   rules: string[]
 }
 
@@ -146,12 +248,20 @@ export interface RemovePriceSetRulesDTO {
  * @interface
  *
  * A price set to create.
- *
- * @prop rules - The rules to associate with the price set. The value of `attribute` is the value of the rule's `rule_attribute` attribute.
- * @prop prices -The prices to create and add to this price set.
  */
 export interface CreatePriceSetDTO {
-  rules?: { rule_attribute: string }[]
+  /**
+   * The rules to associate with the price set.
+   */
+  rules?: { 
+    /**
+     * the value of the rule's `rule_attribute` attribute.
+     */
+    rule_attribute: string
+  }[]
+  /**
+   * The prices to create and add to this price set.
+   */
   prices?: CreatePricesDTO[]
 }
 
@@ -159,10 +269,11 @@ export interface CreatePriceSetDTO {
  * @interface
  *
  * The data to update in a price set. The `id` is used to identify which price set to update.
- *
- * @prop id - A string indicating the ID of the price set to update.
  */
 export interface UpdatePriceSetDTO {
+  /**
+   * A string indicating the ID of the price set to update.
+   */
   id: string
 }
 
@@ -170,12 +281,15 @@ export interface UpdatePriceSetDTO {
  * @interface
  *
  * Filters to apply on price sets.
- *
- * @prop id - IDs to filter price sets by.
- * @prop money_amounts - Filters to apply on a price set's associated money amounts.
  */
 export interface FilterablePriceSetProps
   extends BaseFilterable<FilterablePriceSetProps> {
+  /**
+   * IDs to filter price sets by.
+   */
   id?: string[]
+  /**
+   * Filters to apply on a price set's associated money amounts.
+   */
   money_amounts?: FilterableMoneyAmountProps
 }

packages/types/src/pricing/common/rule-type.ts

@@ -4,16 +4,25 @@ import { BaseFilterable } from "../../dal"
  * @interface
  * 
  * A rule type's data.
- * 
- * @prop id - The ID of the rule type.
- * @prop name - The display name of the rule type.
- * @prop rule_attribute - The unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
- * @prop default_priority - The priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
  */
 export interface RuleTypeDTO {
+  /**
+   * The ID of the rule type.
+   */
   id: string
+  /**
+   * The display name of the rule type.
+   */
   name: string
+  /**
+   * The unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of 
+   * the `calculatePrices` method to specify a rule for calculating the price.
+   */
   rule_attribute: string
+  /**
+   * The priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy 
+   * the provided context. The higher the value, the higher the priority of the rule type.
+   */
   default_priority: number
 }
 
@@ -21,16 +30,25 @@ export interface RuleTypeDTO {
  * @interface
  * 
  * The rule type to create.
- * 
- * @prop id - The ID of the rule type.
- * @prop name - The display name of the rule type.
- * @prop rule_attribute - The unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
- * @prop default_priority - The priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
  */
 export interface CreateRuleTypeDTO {
+  /**
+   * The ID of the rule type.
+   */
   id?: string
+  /**
+   * The display name of the rule type.
+   */
   name: string
+  /**
+   * The unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` 
+   * method to specify a rule for calculating the price.
+   */
   rule_attribute: string
+  /**
+   * The priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. 
+   * The higher the value, the higher the priority of the rule type.
+   */
   default_priority?: number
 }
 
@@ -38,16 +56,23 @@ export interface CreateRuleTypeDTO {
  * @interface
  * 
  * The data to update in a rule type. The `id` is used to identify which price set to update.
- * 
- * @prop id - The ID of the rule type to update.
- * @prop name - The display name of the rule type.
- * @prop rule_attribute - The unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
- * @prop default_priority - The priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
  */
 export interface UpdateRuleTypeDTO {
+  /**
+   * The ID of the rule type to update.
+   */
   id: string
+  /**
+   * The display name of the rule type.
+   */
   name?: string
+  /**
+   * The unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
+   */
   rule_attribute?: string
+  /**
+   * The priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
+   */
   default_priority?: number
 }
 
@@ -55,14 +80,19 @@ export interface UpdateRuleTypeDTO {
  * @interface
  * 
  * Filters to apply on rule types.
- * 
- * @prop id - The IDs to filter rule types by.
- * @prop name - The names to filter rule types by.
- * @prop rule_attribute - The rule attributes to filter rule types by.
  */
 export interface FilterableRuleTypeProps
   extends BaseFilterable<FilterableRuleTypeProps> {
+  /**
+   * The IDs to filter rule types by.
+   */
   id?: string[]
+  /**
+   * The names to filter rule types by.
+   */
   name?: string[]
+  /**
+   * The rule attributes to filter rule types by.
+   */
   rule_attribute?: string[]
 }

packages/types/src/pricing/service.ts

@@ -140,7 +140,7 @@ export interface IPricingModuleService {
   ): Promise<CalculatedPriceSetDTO>
 
   /**
-   * This method is used to retrieves a price set by its ID.
+   * This method is used to retrieve a price set by its ID.
    *
    * @param {string} id - The ID of the price set to retrieve.
    * @param {FindConfig<PriceSetDTO>} config -
@@ -2876,82 +2876,839 @@ export interface IPricingModuleService {
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method is used to retrieve a price list by its ID.
+   *
+   * @param {string} id - The ID of the price list to retrieve.
+   * @param {FindConfig<PriceListDTO>} config -
+   * The configurations determining how the price list is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO>} The retrieved price list.
+   *
+   * @example
+   * A simple example that retrieves a price list by its ID:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function retrievePriceList (priceListId: string) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceList = await pricingService.retrievePriceList(
+   *     priceListId
+   *   )
+   *
+   *   // do something with the price list or return it
+   * }
+   * ```
+   *
+   * To specify relations that should be retrieved:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function retrievePriceList (priceListId: string) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceList = await pricingService.retrievePriceList(
+   *     priceListId,
+   *     {
+   *       relations: ["price_set_money_amounts"]
+   *     }
+   *   )
+   *
+   *   // do something with the price list or return it
+   * }
+   * ```
+   */
   retrievePriceList(
     id: string,
     config?: FindConfig<PriceListDTO>,
     sharedContext?: Context
   ): Promise<PriceListDTO>
 
+  /**
+   * This method is used to retrieve a paginated list of price lists based on optional filters and configuration.
+   *
+   * @param {FilterablePriceListProps} filters - The filters to apply on the retrieved price lists.
+   * @param {FindConfig<PriceListDTO>} config -
+   * The configurations determining how the price lists are retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO[]>} The list of price lists.
+   *
+   * @example
+   *
+   * To retrieve a list of price lists using their IDs:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceLists (priceListIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceLists = await pricingService.listPriceLists(
+   *     {
+   *       id: priceListIds
+   *     },
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   *
+   * To specify relations that should be retrieved within the price lists:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceLists (priceListIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceLists = await pricingService.listPriceLists(
+   *     {
+   *       id: priceListIds
+   *     },
+   *     {
+   *       relations: ["price_set_money_amounts"]
+   *     }
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   *
+   * 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
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceLists (priceListIds: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceLists = await pricingService.listPriceLists(
+   *     {
+   *       id: priceListIds
+   *     },
+   *     {
+   *       relations: ["price_set_money_amounts"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   *
+   * You can also use the `$and` or `$or` properties of the `filter` parameter to use and/or conditions in your filters. For example:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceLists (priceListIds: string[], titles: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceLists = await pricingService.listPriceLists(
+   *     {
+   *       $and: [
+   *         {
+   *           id: priceListIds
+   *         },
+   *         {
+   *           title: titles
+   *         }
+   *       ]
+   *     },
+   *     {
+   *       relations: ["price_set_money_amounts"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   */
   listPriceLists(
     filters?: FilterablePriceListProps,
     config?: FindConfig<PriceListDTO>,
     sharedContext?: Context
   ): Promise<PriceListDTO[]>
 
+  /**
+   * This method is used to retrieve a paginated list of price lists along with the total count of available price lists satisfying the provided filters.
+   *
+   * @param {FilterablePriceListProps} filters - The filters to apply on the retrieved price lists.
+   * @param {FindConfig<PriceListDTO>} config -
+   * The configurations determining how the price lists are retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[PriceListDTO[], number]>} The list of price lists along with their total count.
+   *
+   * @example
+   *
+   * To retrieve a list of price lists using their IDs:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function retrievePriceLists (priceListIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceLists, count] = await pricingService.listPriceLists(
+   *     {
+   *       id: priceListIds
+   *     },
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   *
+   * To specify relations that should be retrieved within the price lists:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function retrievePriceLists (priceListIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceLists, count] = await pricingService.listPriceLists(
+   *     {
+   *       id: priceListIds
+   *     },
+   *     {
+   *       relations: ["price_set_money_amounts"]
+   *     }
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   *
+   * 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
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function retrievePriceLists (priceListIds: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceLists, count] = await pricingService.listPriceLists(
+   *     {
+   *       id: priceListIds
+   *     },
+   *     {
+   *       relations: ["price_set_money_amounts"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   *
+   * You can also use the `$and` or `$or` properties of the `filter` parameter to use and/or conditions in your filters. For example:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function retrievePriceLists (priceListIds: string[], titles: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceLists, count] = await pricingService.listPriceLists(
+   *     {
+   *       $and: [
+   *         {
+   *           id: priceListIds
+   *         },
+   *         {
+   *           title: titles
+   *         }
+   *       ]
+   *     },
+   *     {
+   *       relations: ["price_set_money_amounts"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price lists or return them
+   * }
+   * ```
+   */
   listAndCountPriceLists(
     filters?: FilterablePriceListProps,
     config?: FindConfig<PriceListDTO>,
     sharedContext?: Context
   ): Promise<[PriceListDTO[], number]>
 
+  /**
+   * This method is used to create price lists.
+   * 
+   * @param {CreatePriceListDTO[]} data - The details of each price list to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO[]>} The created price lists.
+   * 
+   * @example
+   * import { 
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function createPriceList (items: {
+   *   title: string
+   *   description: string
+   *   starts_at?: string
+   *   ends_at?: string
+   * }[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceList = await pricingService.createPriceLists(items)
+   * 
+   *   // do something with the price lists or return them
+   * }
+   */
   createPriceLists(
     data: CreatePriceListDTO[],
     sharedContext?: Context
   ): Promise<PriceListDTO[]>
 
+  /**
+   * This method is used to update price lists.
+   * 
+   * @param {UpdatePriceListDTO[]} data - The attributes to update in each price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO[]>} The updated price lists.
+   * 
+   * @example
+   * import { 
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function updatePriceLists (items: {
+   *   id: string
+   *   title: string
+   *   description: string
+   *   starts_at?: string
+   *   ends_at?: string
+   * }[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceList = await pricingService.updatePriceLists(items)
+   * 
+   *   // do something with the price lists or return them
+   * }
+   */
   updatePriceLists(
     data: UpdatePriceListDTO[],
     sharedContext?: Context
   ): Promise<PriceListDTO[]>
 
+  /**
+   * This method is used to delete price lists.
+   * 
+   * @param {string[]} priceListIds - The IDs of the price lists to delete.
+   * @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 price lists are deleted successfully.
+   * 
+   * @example
+   * import { 
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function deletePriceLists (ids: string[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   await pricingService.deletePriceLists(ids)
+   * }
+   */
   deletePriceLists(
     priceListIds: string[],
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method is used to retrieve a price list rule by its ID.
+   *
+   * @param {string} id - The ID of the price list rule to retrieve.
+   * @param {FindConfig<PriceListRuleDTO>} config -
+   * The configurations determining how the price list rule is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a price list rule.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListRuleDTO>} The retrieved price list rule.
+   *
+   * @example
+   * A simple example that retrieves a price list rule by its ID:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function retrievePriceListRule (priceListRuleId: string) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceListRule = await pricingService.retrievePriceListRule(
+   *     priceListRuleId
+   *   )
+   * 
+   *   // do something with the price list rule or return it
+   * }
+   * ```
+   *
+   * To specify relations that should be retrieved:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function retrievePriceListRule (priceListRuleId: string) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceListRule = await pricingService.retrievePriceListRule(
+   *     priceListRuleId,
+   *     {
+   *       relations: ["price_list"]
+   *     }
+   *   )
+   * 
+   *   // do something with the price list rule or return it
+   * }
+   * ```
+   */
   retrievePriceListRule(
     id: string,
     config?: FindConfig<PriceListRuleDTO>,
     sharedContext?: Context
   ): Promise<PriceListRuleDTO>
 
+  /**
+   * This method is used to retrieve a paginated list of price list rules based on optional filters and configuration.
+   *
+   * @param {FilterablePriceListRuleProps} filters - The filters to apply on the retrieved price list rules.
+   * @param {FindConfig<PriceListRuleDTO>} config -
+   * The configurations determining how the price list rules are retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a price list rule.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListRuleDTO[]>} The list of price list rules.
+   *
+   * @example
+   *
+   * To retrieve a list of price list vs using their IDs:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceListRules (priceListRuleIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceListRules = await pricingService.listPriceListRules(
+   *     {
+   *       id: priceListRuleIds
+   *     },
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   *
+   * To specify relations that should be retrieved within the price list rules:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceListRules (priceListRuleIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceListRules = await pricingService.listPriceListRules(
+   *     {
+   *       id: priceListRuleIds
+   *     },
+   *     {
+   *       relations: ["price_list_rule_values"]
+   *     }
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   *
+   * 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
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceListRules (priceListRuleIds: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceListRules = await pricingService.listPriceListRules(
+   *     {
+   *       id: priceListRuleIds
+   *     },
+   *     {
+   *       relations: ["price_list_rule_values"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   *
+   * You can also use the `$and` or `$or` properties of the `filter` parameter to use and/or conditions in your filters. For example:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listPriceListRules (priceListRuleIds: string[], ruleTypeIDs: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const priceListRules = await pricingService.listPriceListRules(
+   *     {
+   *       $and: [
+   *         {
+   *           id: priceListRuleIds
+   *         },
+   *         {
+   *           rule_types: ruleTypeIDs
+   *         }
+   *       ]
+   *     },
+   *     {
+   *       relations: ["price_list_rule_values"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   */
   listPriceListRules(
     filters?: FilterablePriceListRuleProps,
     config?: FindConfig<PriceListRuleDTO>,
     sharedContext?: Context
   ): Promise<PriceListRuleDTO[]>
 
+  /**
+   * This method is used to retrieve a paginated list of price list ruless along with the total count of available price list ruless satisfying the provided filters.
+   *
+   * @param {FilterablePriceListRuleProps} filters - The filters to apply on the retrieved price list rules.
+   * @param {FindConfig<PriceListRuleDTO>} config -
+   * The configurations determining how the price list rules are retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a price list rule.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[PriceListRuleDTO[], number]>} The list of price list rules along with their total count.
+   *
+   * @example
+   *
+   * To retrieve a list of price list vs using their IDs:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listAndCountPriceListRules (priceListRuleIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceListRules, count] = await pricingService.listAndCountPriceListRules(
+   *     {
+   *       id: priceListRuleIds
+   *     },
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   *
+   * To specify relations that should be retrieved within the price list rules:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listAndCountPriceListRules (priceListRuleIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceListRules, count] = await pricingService.listAndCountPriceListRules(
+   *     {
+   *       id: priceListRuleIds
+   *     },
+   *     {
+   *       relations: ["price_list_rule_values"]
+   *     }
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   *
+   * 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
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listAndCountPriceListRules (priceListRuleIds: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceListRules, count] = await pricingService.listAndCountPriceListRules(
+   *     {
+   *       id: priceListRuleIds
+   *     },
+   *     {
+   *       relations: ["price_list_rule_values"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   *
+   * You can also use the `$and` or `$or` properties of the `filter` parameter to use and/or conditions in your filters. For example:
+   *
+   * ```ts
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   *
+   * async function listAndCountPriceListRules (priceListRuleIds: string[], ruleTypeIDs: string[], skip: number, take: number) {
+   *   const pricingService = await initializePricingModule()
+   *
+   *   const [priceListRules, count] = await pricingService.listAndCountPriceListRules(
+   *     {
+   *       $and: [
+   *         {
+   *           id: priceListRuleIds
+   *         },
+   *         {
+   *           rule_types: ruleTypeIDs
+   *         }
+   *       ]
+   *     },
+   *     {
+   *       relations: ["price_list_rule_values"],
+   *       skip,
+   *       take
+   *     }
+   *   )
+   *
+   *   // do something with the price list rules or return them
+   * }
+   * ```
+   */
   listAndCountPriceListRules(
     filters?: FilterablePriceListRuleProps,
     config?: FindConfig<PriceListRuleDTO>,
     sharedContext?: Context
   ): Promise<[PriceListRuleDTO[], number]>
 
+  /**
+   * This method is used to create price list rules.
+   * 
+   * @param {CreatePriceListRuleDTO[]} data - The price list rules to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListRuleDTO[]>} The created price list rules.
+   * 
+   * @example
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function createPriceListRules (items: {
+   *   rule_type_id: string
+   *   price_list_id: string
+   * }[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceListRules = await pricingService.createPriceListRules(items)
+   * 
+   *   // do something with the price list rule or return them
+   * }
+   */
   createPriceListRules(
     data: CreatePriceListRuleDTO[],
     sharedContext?: Context
   ): Promise<PriceListRuleDTO[]>
 
+  /**
+   * This method is used to update price list rules.
+   * 
+   * @param {UpdatePriceListRuleDTO[]} data - The attributes to update for each price list rule.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListRuleDTO[]>} The updated price list rules.
+   * 
+   * @example
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function updatePriceListRules (items: {
+   *   id: string
+   *   rule_type_id?: string
+   *   price_list_id?: string
+   * }[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceListRules = await pricingService.updatePriceListRules(items)
+   * 
+   *   // do something with the price list rule or return them
+   * }
+   */
   updatePriceListRules(
     data: UpdatePriceListRuleDTO[],
     sharedContext?: Context
   ): Promise<PriceListRuleDTO[]>
 
+  /**
+   * This method is used to delete price list rules.
+   * 
+   * @param {string[]} priceListRuleIds - The IDs of the price list rules to delete.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves successfully when the price list rules are deleted.
+   * 
+   * @example
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function deletePriceListRules (priceListRuleIds: string[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   await pricingService.deletePriceListRules(priceListRuleIds)
+   * }
+   */
   deletePriceListRules(
     priceListRuleIds: string[],
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method is used to add prices to price lists.
+   * 
+   * @param {AddPriceListPricesDTO[]} data - The prices to add for each price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO[]>} The updated price lists.
+   * 
+   * @example
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function addPriceListPrices (items: {
+   *   priceListId: string,
+   *   prices: {
+   *     currency_code: string,
+   *     amount: number,
+   *     price_set_id: string
+   *   }[]
+   * }[]) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceLists = await pricingService.addPriceListPrices(items)
+   * 
+   *   // do something with the price lists or return them
+   * }
+   */
   addPriceListPrices(
     data: AddPriceListPricesDTO[],
     sharedContext?: Context
   ): Promise<PriceListDTO[]>
 
+  /**
+   * This method is used to set the rules of a price list.
+   * 
+   * @param {SetPriceListRulesDTO} data - The rules to set for a price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO>} The updated price lists.
+   * 
+   * @example
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function setPriceListRules (priceListId: string) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceList = await pricingService.setPriceListRules({
+   *     priceListId,
+   *     rules: {
+   *       region_id: "US"
+   *     }
+   *   })
+   * 
+   *   // do something with the price list or return it
+   * }
+   */
   setPriceListRules(
     data: SetPriceListRulesDTO,
     sharedContext?: Context
   ): Promise<PriceListDTO>
 
+  /**
+   * This method is used to remove rules from a price list.
+   * 
+   * @param {RemovePriceListRulesDTO} data - The rules to remove from a price list.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PriceListDTO>} The updated price lists.
+   * 
+   * @example
+   * import {
+   *   initialize as initializePricingModule,
+   * } from "@medusajs/pricing"
+   * 
+   * async function setPriceListRules (priceListId: string) {
+   *   const pricingService = await initializePricingModule()
+   * 
+   *   const priceList = await pricingService.removePriceListRules({
+   *     priceListId,
+   *     rules: ["region_id"]
+   *   })
+   * 
+   *   // do something with the price list or return it
+   * }
+   */
   removePriceListRules(
     data: RemovePriceListRulesDTO,
     sharedContext?: Context