chore: added and improved TSDoc of pricing module (#5335)

* adjusted tsdoc of methods and types in pricing module

* finished adding tsdocs

* small fixes

* remove reference files

* added github action

* fix typo in outPath

* Update packages/types/src/shared-context.ts

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

* fix sharedContext description

* changed branch name of action

* added ignore for is_dynamic

* added private remark

---------

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

.github/workflows/generate-references.yml

@@ -192,4 +192,49 @@ jobs:
           labels: "type: chore"
           add-paths: www/apps/docs/content/references/js-client/**
           branch: "docs/generate-js-client"
+          branch-suffix: "timestamp"
+  pricing:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v3
+        with:
+          node-version: "16.20.2"
+          cache: "yarn"
+
+      - name: Install dependencies
+        uses: ./.github/actions/cache-deps
+        with:
+          extension: reference
+
+      - name: Build Packages
+        run: yarn build
+
+      - name: Install Workspace dependencies
+        run: yarn install
+        working-directory: docs-utils
+
+      - name: Generate Pricing Module Reference
+        run: yarn generate:references pricing
+        working-directory: docs-utils/packages/scripts
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: "chore(docs): Generated Pricing Module Reference (automated)"
+          base: "develop"
+          title: "chore(docs): Generated Pricing Module Reference"
+          labels: "type: chore"
+          add-paths: www/apps/docs/content/references/pricing/**
+          branch: "docs/generate-pricing"
           branch-suffix: "timestamp"

docs-util/packages/typedoc-config/pricing.js

@@ -0,0 +1,18 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const modulesConfig = require("./modules")
+
+module.exports = modulesConfig({
+  entryPointPath: "packages/types/src/pricing/service.ts",
+  outPath: "www/apps/docs/content/references/pricing",
+  moduleName: "Pricing Module Reference",
+  documentsToFormat: ["IPricingModuleService"],
+  additionalFormatting: {
+    reflectionDescription:
+      "This document provides a reference to the `IPricingModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Pricing Module.",
+  },
+  extraOptions: {
+    frontmatterData: {
+      displayed_sidebar: "modules",
+    },
+  },
+})

docs-util/packages/typedoc-config/tsconfig.json

@@ -1,7 +1,4 @@
 {
   "extends": "../../tsconfig",
-  "compilerOptions": {
-    "outDir": "./dist"
-  },
   "include": ["*.js"]
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -34,6 +34,7 @@ import typeParameterListHelper from "./resources/helpers/type-parameter-list"
 import typeParameterHelper from "./resources/helpers/type-parameter"
 import parameterListHelper from "./resources/helpers/parameter-list"
 import parameterHelper from "./resources/helpers/parameter"
+import debugHelper from "./resources/helpers/debug"
 import { MarkdownTheme } from "./theme"
 
 const TEMPLATE_PATH = path.join(__dirname, "resources", "templates")
@@ -96,4 +97,5 @@ export function registerHelpers(theme: MarkdownTheme) {
   typeParameterHelper(theme)
   parameterListHelper()
   parameterHelper(theme)
+  debugHelper()
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts

@@ -10,7 +10,8 @@ export default function (theme: MarkdownTheme) {
       comment: Comment,
       showSummary = true,
       showTags = true,
-      commentLevel = 4
+      commentLevel = 4,
+      parent = null
     ) {
       const { showCommentsAsHeader } = theme.getFormattingOptionsForLocation()
       const md: string[] = []
@@ -27,7 +28,10 @@ export default function (theme: MarkdownTheme) {
         const tags = filteredTags.map((tag) => {
           return `${
             showCommentsAsHeader
-              ? `${Handlebars.helpers.titleLevel(commentLevel)} `
+              ? `${Handlebars.helpers.titleLevel.call(
+                  parent || comment,
+                  commentLevel
+                )} `
               : "**`"
           }${camelToTitleCase(tag.tag.substring(1))}${
             showCommentsAsHeader ? "" : "`**"

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/debug.ts

@@ -0,0 +1,7 @@
+import * as Handlebars from "handlebars"
+
+export default function () {
+  Handlebars.registerHelper("debug", function (...data: unknown[]) {
+    console.log(...data)
+  })
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts

@@ -11,6 +11,14 @@ export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "signatureTitle",
     function (this: SignatureReflection, accessor?: string, standalone = true) {
+      const { sections, expandMembers = false } =
+        theme.getFormattingOptionsForLocation()
+      if (sections && sections.member_signature_title === false) {
+        // only show title if there are more than one signatures
+        if (!this.parent.signatures || this.parent.signatures?.length <= 1) {
+          return ""
+        }
+      }
       const md: string[] = []
 
       if (standalone && !theme.hideMembersSymbol) {
@@ -18,26 +26,52 @@ export default function (theme: MarkdownTheme) {
       }
 
       if (this.parent && this.parent.flags?.length > 0) {
-        md.push(this.parent.flags.map((flag) => `\`${flag}\``).join(" ") + " ")
+        md.push(
+          this.parent.flags
+            .map(
+              (flag) =>
+                `${!expandMembers ? "`" : ""}${flag}${
+                  !expandMembers ? "`" : ""
+                }`
+            )
+            .join(" ") + " "
+        )
       }
 
       if (accessor) {
-        md.push(`\`${accessor}\` **${this.name}**`)
+        md.push(
+          `${!expandMembers ? "`" : ""}${accessor}${
+            !expandMembers ? "`" : ""
+          } ${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
+            this.name
+          }${!expandMembers ? "**" : ""}`
+        )
       } else if (this.name !== "__call" && this.name !== "__type") {
-        md.push(`**${this.name}**`)
+        md.push(
+          `${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
+            this.name
+          }${!expandMembers ? "**" : ""}`
+        )
       }
 
       if (this.typeParameters) {
         md.push(
           `<${this.typeParameters
-            .map((typeParameter) => `\`${typeParameter.name}\``)
+            .map(
+              (typeParameter) =>
+                `${!expandMembers ? "`" : ""}${typeParameter.name}${
+                  !expandMembers ? "`" : ""
+                }`
+            )
             .join(", ")}\\>`
         )
       }
-      md.push(`(${getParameters(this.parameters)})`)
+      md.push(`(${getParameters(this.parameters, !expandMembers)})`)
 
       if (this.type && !this.parent?.kindOf(ReflectionKind.Constructor)) {
-        md.push(`: ${Handlebars.helpers.type.call(this.type, "object")}`)
+        md.push(
+          `: ${Handlebars.helpers.type.call(this.type, "none", !expandMembers)}`
+        )
       }
       return md.join("") + (standalone ? "\n" : "")
     }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/title-level.ts

@@ -1,12 +1,31 @@
 import { MarkdownTheme } from "../../theme"
 import * as Handlebars from "handlebars"
+import { SignatureReflection, Reflection } from "typedoc"
 
 export default function (theme: MarkdownTheme) {
-  Handlebars.registerHelper("titleLevel", function (originalLevel = 3): string {
-    const { expandMembers } = theme.getFormattingOptionsForLocation()
+  Handlebars.registerHelper(
+    "titleLevel",
+    function (this: Reflection, originalLevel = 3): string {
+      const { expandMembers, sections } =
+        theme.getFormattingOptionsForLocation()
 
-    const level = expandMembers ? originalLevel - 1 : originalLevel
+      let isSignatureChild = false
+      if (
+        sections &&
+        sections.member_signature_title === false &&
+        (this instanceof SignatureReflection || this.variant === "signature")
+      ) {
+        // only show title if there are more than one signatures
+        isSignatureChild =
+          this.parent !== undefined &&
+          "signatures" in this.parent &&
+          (this.parent.signatures as SignatureReflection[]).length > 1
+      }
 
-    return Array(level).fill("#").join("")
-  })
+      const level =
+        expandMembers && !isSignatureChild ? originalLevel - 1 : originalLevel
+
+      return Array(level).fill("#").join("")
+    }
+  )
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type.ts

@@ -196,21 +196,27 @@ export function getReferenceType(model: ReferenceType, emphasis: boolean) {
 
     if (model.reflection?.url) {
       reflection.push(
-        `[${`\`${model.reflection.name}\``}](${Handlebars.helpers.relativeURL(
-          model.reflection.url
-        )})`
+        emphasis
+          ? `[${`\`${model.reflection.name}\``}](${Handlebars.helpers.relativeURL(
+              model.reflection.url
+            )})`
+          : model.reflection.name
       )
     } else {
       reflection.push(
-        model.externalUrl
-          ? `[${`\`${model.name}\``}]( ${model.externalUrl} )`
-          : `\`${model.name}\``
+        emphasis
+          ? model.externalUrl
+            ? `[${`\`${model.name}\``}]( ${model.externalUrl} )`
+            : `\`${model.name}\``
+          : model.name
       )
     }
     if (model.typeArguments && model.typeArguments.length > 0) {
       reflection.push(
         `<${model.typeArguments
-          .map((typeArgument) => Handlebars.helpers.type.call(typeArgument))
+          .map((typeArgument) =>
+            Handlebars.helpers.type.call(typeArgument, "none", emphasis)
+          )
           .join(", ")}\\>`
       )
     }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature.hbs

@@ -1,9 +1,5 @@
-{{#if (sectionEnabled "member_signature_title")}}
-
 {{{signatureTitle accessor}}}
 
-{{/if}}
-
 {{#if (sectionEnabled "member_signature_comment")}}
 
 {{#with comment}}
@@ -38,11 +34,11 @@
 
 {{#if showSources}}
 
-{{titleLevel 4}} Parameters
+{{{titleLevel 4}}} Parameters
 
 {{else}}
 
-{{titleLevel 5}} Parameters
+{{{titleLevel 5}}} Parameters
 
 {{/if}}
 
@@ -62,11 +58,11 @@
 
 {{#if showSources}}
 
-{{titleLevel 4}} Returns
+{{{titleLevel 4}}} Returns
 
 {{else}}
 
-{{titleLevel 5}} Returns
+{{{titleLevel 5}}} Returns
 
 {{/if}}
 
@@ -128,7 +124,7 @@
 
 {{#if hasVisibleComponent}}
 
-{{{comments this false true 4}}}
+{{{comments this false true 4 ..}}}
 
 {{/if}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts

@@ -28,9 +28,9 @@ export default function reflectionFomatter(
     const itemChildren: string[] = []
     comments.summary.forEach((commentSummary) => {
       if ("target" in commentSummary) {
-        const reflection = commentSummary.target as DeclarationReflection
-        if (reflection.children && level + 1 < MAX_LEVEL) {
-          reflection.children.forEach((childItem) => {
+        const targetReflection = commentSummary.target as DeclarationReflection
+        if (targetReflection.children && level + 1 <= MAX_LEVEL) {
+          targetReflection.children.forEach((childItem) => {
             itemChildren.push(reflectionFomatter(childItem, level + 1))
           })
         }
@@ -39,9 +39,11 @@ export default function reflectionFomatter(
     if (itemChildren.length) {
       // TODO maybe we should check the type of the reflection and replace
       // `properties` with the text that makes sense for the type.
-      item += ` It accepts the following properties:\n${itemChildren.join(
-        "\n"
-      )}`
+      item += ` ${
+        reflection.type?.type === "array"
+          ? "Its items accept the following properties"
+          : "It accepts the following properties"
+      }:\n${itemChildren.join("\n")}`
     }
   }
 

packages/types/src/common/common.ts

@@ -40,6 +40,22 @@ export type Writable<T> = {
     | FindOperator<string[]>
 }
 
+/**
+ * @interface
+ * 
+ * An object that is used to configure how an entity is retrieved from the database. It accepts as a typed parameter an `Entity` class, 
+ * which provides correct typing of field names in its properties.
+ * 
+ * @prop select - An array of strings, each being attribute names of the entity to retrieve in the result.
+ * @prop skip - A number indicating the number of records to skip before retrieving the results.
+ * @prop take - A number indicating the number of records to return in the result.
+ * @prop relations - An array of strings, each being relation names of the entity to retrieve in the result.
+ * @prop order - 
+ * An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC` 
+ * to sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.
+ * @prop withDeleted - A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the
+ * `SoftDeletableEntity` class.
+ */
 export interface FindConfig<Entity> {
   select?: (keyof Entity | string)[]
   skip?: number

packages/types/src/dal/index.ts

@@ -1,6 +1,15 @@
 import { Dictionary, FilterQuery, Order } from "./utils"
 
 export { FilterQuery } from "./utils"
+
+/**
+ * @interface
+ * 
+ * An object used to allow specifying flexible queries with and/or conditions.
+ * 
+ * @prop $and - An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.
+ * @prop $or - An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.
+ */
 export interface BaseFilterable<T> {
   $and?: (T | BaseFilterable<T>)[]
   $or?: (T | BaseFilterable<T>)[]

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

@@ -1,5 +1,17 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ * 
+ * An object representing a currency.
+ * 
+ * @prop code - a string indicating the code of the currency.
+ * @prop symbol - a string indicating the symbol of the currency.
+ * @prop symbol_native - 
+ * a string indicating the symbol of the currecy in its native form.
+ * This is typically the symbol used when displaying a price.
+ * @prop name - a string indicating the name of the currency.
+ */
 export interface CurrencyDTO {
   code: string
   symbol?: string
@@ -7,6 +19,18 @@ export interface CurrencyDTO {
   name?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds data to create a currency.
+ * 
+ * @prop code - a string indicating the code of the currency.
+ * @prop symbol - a string indicating the symbol of the currency.
+ * @prop symbol_native - 
+ * a string indicating the symbol of the currecy in its native form.
+ * This is typically the symbol used when displaying a price.
+ * @prop name - a string indicating the name of the currency.
+ */
 export interface CreateCurrencyDTO {
   code: string
   symbol: string
@@ -14,6 +38,18 @@ export interface CreateCurrencyDTO {
   name: string
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds data to update a currency. The currency code must be provided to identify which currency to update.
+ * 
+ * @prop code - a string indicating the code of the currency to update.
+ * @prop symbol - a string indicating the symbol of the currency.
+ * @prop symbol_native - 
+ * a string indicating the symbol of the currecy in its native form.
+ * This is typically the symbol used when displaying a price.
+ * @prop name - a string indicating the name of the currency.
+ */
 export interface UpdateCurrencyDTO {
   code: string
   symbol?: string
@@ -21,6 +57,13 @@ export interface UpdateCurrencyDTO {
   name?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter retrieved currencies.
+ * 
+ * @prop code - an array of strings, each being a currency code to filter the currencies.
+ */
 export interface FilterableCurrencyProps
   extends BaseFilterable<FilterableCurrencyProps> {
   code?: string[]

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

@@ -1,6 +1,18 @@
 import { BaseFilterable } from "../../dal"
 import { CreateCurrencyDTO, CurrencyDTO } from "./currency"
 
+/**
+ * @interface
+ * 
+ * An object that holds prices, which typically belong to a price set.
+ * 
+ * @prop id - A string that indicates the ID of the money amount. A money amount represents a price.
+ * @prop currency_code - A string that indicates the currency code of this price.
+ * @prop currency - An object of type {@link CurrencyDTO} that holds the details of the price'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 - A number indicating the amount of this price.
+ * @prop min_quantity - A number that indicates the minimum quantity required to be purchased for this price to be applied.
+ * @prop max_quantity - A number that indicates the maximum quantity required to be purchased for this price to be applied.
+ */
 export interface MoneyAmountDTO {
   id: string
   currency_code?: string
@@ -10,6 +22,18 @@ export interface MoneyAmountDTO {
   max_quantity?: number
 }
 
+/**
+ *  * @interface
+ * 
+ * An object that holds data to create a money amount.
+ * 
+ * @prop id - A string that indicates the ID of the money amount.
+ * @prop currency_code - A string that indicates the currency code of this money amount.
+ * @prop currency - An object of type {@link CurrencyDTO} that holds the details of 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 - A number indicating the amount of this money amount.
+ * @prop min_quantity - A number that indicates the minimum quantity required to be purchased for this money amount to be applied.
+ * @prop max_quantity - A number that indicates the maximum quantity required to be purchased for this money amount to be applied.
+ */
 export interface CreateMoneyAmountDTO {
   id?: string
   currency_code: string
@@ -19,6 +43,18 @@ export interface CreateMoneyAmountDTO {
   max_quantity?: number
 }
 
+/**
+ *  * @interface
+ * 
+ * An object that holds data to update a money amount.
+ * 
+ * @prop id - A string that indicates the ID of the money amount to update.
+ * @prop currency_code - A string that indicates the currency code of the money amount.
+ * @prop currency - An object of type {@link CurrencyDTO} that holds the details of 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 - A number indicating the amount of this money amount.
+ * @prop min_quantity - A number that indicates the minimum quantity required to be purchased for this money amount to be applied.
+ * @prop max_quantity - A number that indicates the maximum quantity required to be purchased for this money amount to be applied.
+ */
 export interface UpdateMoneyAmountDTO {
   id: string
   currency_code?: string
@@ -27,6 +63,14 @@ export interface UpdateMoneyAmountDTO {
   max_quantity?: number
 }
 
+/**
+ * @interface
+ * 
+ * An object that can be used to filter money amounts.
+ * 
+ * @prop id - An array of strings, each being an ID to filter money amounts.
+ * @prop currency_code - A string or an array of strings, each being a currency code to filter money amounts.
+ */
 export interface FilterableMoneyAmountProps
   extends BaseFilterable<FilterableMoneyAmountProps> {
   id?: string[]

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

@@ -2,6 +2,22 @@ import { BaseFilterable } from "../../dal"
 import { PriceSetDTO } from "./price-set"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @interface
+ * 
+ * An object that represents a price rule.
+ * 
+ * @prop id - A string indicating the ID of the price rule.
+ * @prop price_set_id - A string indicating the ID of the associated price set.
+ * @prop price_set - An object of type {@link PriceSetDTO} that holds the data of the associated price set. It may only be available if the relation `price_set` is expanded.
+ * @prop rule_type_id - A string indicating the ID of the associated rule type.
+ * @prop rule_type - An object of type {@link RuleTypeDTO} that holds the data of the associated rule type. It may only be available if the relation `rule_type` is expanded.
+ * @prop is_dynamic - A boolean indicating whether the price rule is dynamic.
+ * @prop value - A string indicating the value of the price rule.
+ * @prop priority - A number indicating the priority of the price rule in comparison to other applicable price rules.
+ * @prop price_set_money_amount_id - A string indicating the ID of the associated price set money amount.
+ * @prop price_list_id - A string indicating the ID of the associated price list.
+ */
 export interface PriceRuleDTO {
   id: string
   price_set_id: string
@@ -15,6 +31,21 @@ export interface PriceRuleDTO {
   price_list_id: string
 }
 
+/**
+ * 
+ * @interface
+ * 
+ * An object used to specify the necessary data to create a price rule.
+ * 
+ * @prop id - A string indicating the ID of the price rule.
+ * @prop price_set_id - A string indicating the ID of the associated price set.
+ * @prop rule_type_id - A string indicating the ID of the associated rule type.
+ * @prop is_dynamic - A boolean indicating whether the price rule is dynamic.
+ * @prop value - A string indicating the value of the price rule.
+ * @prop priority - A number indicating the priority of the price rule in comparison to other applicable price rules.
+ * @prop price_set_money_amount_id - A string indicating the ID of the associated price set money amount.
+ * @prop price_list_id - A string indicating the ID of the associated price list.
+ */
 export interface CreatePriceRuleDTO {
   id: string
   price_set_id: string
@@ -26,10 +57,30 @@ export interface CreatePriceRuleDTO {
   price_list_id: string
 }
 
+/**
+ * 
+ * @interface
+ * 
+ * An object used to specify the necessary data to update a price rule.
+ * 
+ * @prop id - A string indicating the ID of the price rule to update.
+ * @prop price_set_id - A string indicating the ID of the associated price set.
+ * @prop rule_type_id - A string indicating the ID of the associated rule type.
+ * @prop value - A string indicating the value of the price rule.
+ * @prop priority - A number indicating the priority of the price rule in comparison to other applicable price rules.
+ * @prop price_set_money_amount_id - A string indicating the ID of the associated price set money amount.
+ * @prop price_list_id - A string indicating the ID of the associated price list.
+ */
 export interface UpdatePriceRuleDTO {
   id: string
   price_set_id?: string
   rule_type_id?: string
+  /** 
+   * @ignore
+   * @privateRemark
+   * 
+   * Behavior behind this property is not implemented yet.
+   */
   is_dynamic?: boolean
   value?: string
   priority?: number
@@ -37,6 +88,16 @@ export interface UpdatePriceRuleDTO {
   price_list_id?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter price rules when retrieving them.
+ * 
+ * @prop id - An array of strings, each indicating an ID to filter price rules.
+ * @prop name - An array of strings, each indicating a name to filter price rules.
+ * @prop price_set_id - An array of strings, each indicating a price set ID to filter price rules.
+ * @prop rule_type_id - An array of strings, each indicating a rule type ID to filter rule types.
+ */
 export interface FilterablePriceRuleProps
   extends BaseFilterable<FilterablePriceRuleProps> {
   id?: string[]

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

@@ -2,6 +2,16 @@ import { BaseFilterable } from "../../dal"
 import { PriceSetMoneyAmountDTO } from "./price-set-money-amount"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @interface
+ * 
+ * An object representing a price set money amount rule, which holds data related to the association between a price set money amount and a rule.
+ * 
+ * @prop id - A string indicating the ID of the price set money amount.
+ * @prop price_set_money_amount - an object of type {@link PriceSetMoneyAmountDTO} holding the data of the associated price set money amount.
+ * @prop rule_type - an object of type {@link RuleTypeDTO} holding the data of the associated rule type.
+ * @prop value - a string indicating the value of the price set money amount rule.
+ */
 export interface PriceSetMoneyAmountRulesDTO {
   id: string
   price_set_money_amount: PriceSetMoneyAmountDTO
@@ -9,12 +19,31 @@ export interface PriceSetMoneyAmountRulesDTO {
   value: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to create a price set money amount rule, which represents an association between a price set money amount and a rule type.
+ * 
+ * @prop price_set_money_amount - A string indicating the ID of a price set money amount.
+ * @prop rule_type - A string indicating the ID of a rule type.
+ * @prop value - A string indicating the value of the price set money amount rule.
+ */
 export interface CreatePriceSetMoneyAmountRulesDTO {
   price_set_money_amount: string
   rule_type: string
   value: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to update a price set money amount rule. The price set money amount rule is identified by the provided `id`.
+ * 
+ * @prop id - A string indicating the ID of the price set money amount rule to update.
+ * @prop price_set_money_amount - A string indicating the ID of a price set money amount.
+ * @prop rule_type - A string indicating the ID of a rule type.
+ * @prop value - A string indicating the value of the price set money amount rule.
+ */
 export interface UpdatePriceSetMoneyAmountRulesDTO {
   id: string
   price_set_money_amount?: string
@@ -22,6 +51,16 @@ export interface UpdatePriceSetMoneyAmountRulesDTO {
   value?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter price set money amount rules when listing them.
+ * 
+ * @prop id - An array of strings, each string indicating an ID to filter the price set money amount rules.
+ * @prop rule_type_id - An array of strings, each string indicating the ID of a rule type to filter the price set money amount rules.
+ * @prop price_set_money_amount_id - an array of strings, each string indicating the ID of a price set money amount to filter the price set money amount rules.
+ * @prop value - an array of strings, each string indicating a value to filter the price set money amount rules.
+ */
 export interface FilterablePriceSetMoneyAmountRulesProps
   extends BaseFilterable<FilterablePriceSetMoneyAmountRulesProps> {
   id?: string[]

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

@@ -1,6 +1,16 @@
 import { MoneyAmountDTO } from "./money-amount"
 import { PriceSetDTO } from "./price-set"
 
+/**
+ * @interface
+ * 
+ * An object representing a price set money amount, which holds the data related to the association between a price set and a money amount.
+ * 
+ * @prop id - a string indicating the ID of a price set money amount.
+ * @prop title - a string indicating the title of the price set money amount.
+ * @prop price_set - an object of type {@link PriceSetDTO} holding the data of the associated price set.
+ * @prop money_amount - an object of type {@link MoneyAmountDTO} holding the data of the associated money amount.
+ */
 export interface PriceSetMoneyAmountDTO {
   id: string
   title?: string

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

@@ -6,20 +6,61 @@ import {
 } from "./money-amount"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @interface
+ * 
+ * Used to specify 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.
+ * 
+ * @example
+ * 
+ * To calculate prices 
+ */
 export interface PricingContext {
   context?: Record<string, string | number>
 }
 
+/**
+ * @interface
+ * 
+ * Used to filter prices when calculating them.
+ * 
+ * @prop id - An array of strings, each being an ID of a price set.
+ */
 export interface PricingFilters {
   id: string[]
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds the details of a retrieved price set.
+ * 
+ * @prop id - A string indicating the ID of the price set.
+ * @prop money_amounts - An array of objects of type {@link MoneyAmountDTO}, which holds the prices that belong to this price set.
+ * @prop rule_types - An array of objects of type {@link RuleTypeDTO}, which holds the rule types applied on this price set.
+ * 
+ */
 export interface PriceSetDTO {
   id: string
   money_amounts?: MoneyAmountDTO[]
   rule_types?: RuleTypeDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds the details of a calculated price set.
+ * 
+ * @prop id - a string indicating the ID of the price set.
+ * @prop amount - a number indicating the calculated amount. It can possibly be `null` if there's no price set up for the provided context.
+ * @prop currency_code - a string indicating the currency code of the calculated price. It can possibly be `null`.
+ * @prop min_quantity - a number indicaitng 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 - a number indicaitng 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 {
   id: string
   amount: number | null
@@ -28,31 +69,90 @@ export interface CalculatedPriceSetDTO {
   max_quantity: number | null
 }
 
+/**
+ * @interface
+ * 
+ * An object used to specify the rules to add to a price set.
+ * 
+ * @prop priceSetId - A string indicating the ID of the price set to add the rules to.
+ * @prop rules - An array of objects, each object holds a property `attribute`, with its value being the `rule_attribute` of the rule to add to the price set.
+ */
 export interface AddRulesDTO {
   priceSetId: string
   rules: { attribute: string }[]
 }
 
+/**
+ * @interface
+ * 
+ * An object used to pass prices data when creating a price set.
+ * 
+ * @prop rules - An object whose keys are rule types' `rule_attribute` attribute, and values are the value of that rule associated with this price.
+ */
+export interface CreatePricesDTO extends CreateMoneyAmountDTO {
+  rules: Record<string, string>
+}
+
+/**
+ * @interface
+ * 
+ * An object used to specify prices to add to a price set.
+ * 
+ * @prop priceSetId - A string indicating the ID of the price set to add prices to.
+ * @prop prices - An array of objects of type {@link CreatePricesDTO}, each being a price to add to the price set.
+ */
 export interface AddPricesDTO {
   priceSetId: string
-  prices: (CreateMoneyAmountDTO & {
-    rules?: Record<string, string>
-  })[]
+  prices: CreatePricesDTO[]
 }
+
+/**
+ * @interface
+ * 
+ * An object of expected properties when removing a price set's rules.
+ * 
+ * @prop id - A string indicating the ID of the price set.
+ * @prop rules - An array of strings, each string is the `rule_attribute` of a rule you want to remove.
+ */
 export interface RemovePriceSetRulesDTO {
   id: string
   rules: string[]
 }
 
+/**
+ * @interface
+ * 
+ * An object of expected properties when creating a price set.
+ * 
+ * @prop rules - 
+ * An array of objects, each object accepts a property `rule_attribute`, whose value is a string indicating the `rule_attribute` value of a rule type. 
+ * This property is used to specify the rule types associated with the price set.
+ * @prop prices - An array of objects of type {@link CreatePricesDTO}, each being a price to associate with the price set.
+ */
 export interface CreatePriceSetDTO {
   rules?: { rule_attribute: string }[]
-  prices?: (CreateMoneyAmountDTO & { rules: Record<string, string> })[]
+  prices?: CreatePricesDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * An object of expected properties when updating a price set.
+ * 
+ * @prop id - A string indicating the ID of the price set to update.
+ */
 export interface UpdatePriceSetDTO {
   id: string
 }
 
+/**
+ * @interface
+ * 
+ * An object that can be used to specify filters on price sets.
+ * 
+ * @prop id - An array of strings, each being an ID to filter price sets.
+ * @prop money_amounts - An object of type {@link FilterableMoneyAmountProps} that is used to filter the price sets by their associated money amounts.
+ */
 export interface FilterablePriceSetProps
   extends BaseFilterable<FilterablePriceSetProps> {
   id?: string[]

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

@@ -1,5 +1,15 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ * 
+ * An object that holds the details of a rule type.
+ * 
+ * @prop id - A string indicating the ID of the rule type.
+ * @prop name - A string indicating the display name of the rule type.
+ * @prop rule_attribute - A string indicating a 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 - A number indicating 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 {
   id: string
   name: string
@@ -7,6 +17,16 @@ export interface RuleTypeDTO {
   default_priority: number
 }
 
+/**
+ * @interface
+ * 
+ * An object used when creating a rule type to specify its data.
+ * 
+ * @prop id - A string indicating the ID of the rule type.
+ * @prop name - A string indicating the display name of the rule type.
+ * @prop rule_attribute - A string indicating a 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 - A number indicating 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 {
   id?: string
   name: string
@@ -14,6 +34,16 @@ export interface CreateRuleTypeDTO {
   default_priority?: number
 }
 
+/**
+ * @interface
+ * 
+ * An object used when updating a rule type to specify the data to update.
+ * 
+ * @prop id - A string indicating the ID of the rule type to update.
+ * @prop name - A string indicating the display name of the rule type.
+ * @prop rule_attribute - A string indicating a 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 - A number indicating 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 {
   id: string
   name?: string
@@ -21,6 +51,15 @@ export interface UpdateRuleTypeDTO {
   default_priority?: number
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter retrieved rule types.
+ * 
+ * @prop id - an array of strings, each being an ID to filter rule types.
+ * @prop name - an array of strings, each being a name to filter rule types.
+ * @prop rule_attribute - an array of strings, each being a rule attribute to filter rule types.
+ */
 export interface FilterableRuleTypeProps
   extends BaseFilterable<FilterableRuleTypeProps> {
   id?: string[]

packages/types/src/shared-context.ts

@@ -5,6 +5,18 @@ export type SharedContext = {
   manager?: EntityManager
 }
 
+/**
+ * @internal The interface tag is used to ensure that the type is documented similar to interfaces.
+ * @interface
+ * 
+ * A shared context object that is used to share resources between the application and the module.
+ * 
+ * @prop transactionManager - An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.
+ * @prop manager - An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.
+ * @prop isolationLevel - A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.
+ * @prop enableNestedTransactions - a boolean value indicating whether nested transactions are enabled.
+ * @prop transactionId - a string indicating the ID of the current transaction.
+ */
 export type Context<TManager = unknown> = {
   transactionManager?: TManager
   manager?: TManager