From 57bd38bb4b83bd5b8f2f95d54b06d19d7a5bc26b Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 10 Oct 2023 13:23:54 +0300 Subject: [PATCH] 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 | 45 + docs-util/packages/typedoc-config/pricing.js | 18 + .../packages/typedoc-config/tsconfig.json | 3 - .../src/render-utils.ts | 2 + .../src/resources/helpers/comments.ts | 8 +- .../src/resources/helpers/debug.ts | 7 + .../src/resources/helpers/signature-title.ts | 46 +- .../src/resources/helpers/title-level.ts | 29 +- .../src/resources/helpers/type.ts | 20 +- .../resources/partials/member.signature.hbs | 14 +- .../src/utils/reflection-formatter.ts | 14 +- packages/types/src/common/common.ts | 16 + packages/types/src/dal/index.ts | 9 + packages/types/src/pricing/common/currency.ts | 43 + .../types/src/pricing/common/money-amount.ts | 44 + .../types/src/pricing/common/price-rule.ts | 61 + .../common/price-set-money-amount-rules.ts | 39 + .../pricing/common/price-set-money-amount.ts | 10 + .../types/src/pricing/common/price-set.ts | 108 +- .../types/src/pricing/common/rule-type.ts | 39 + packages/types/src/pricing/service.ts | 2419 +++++++++++++++-- packages/types/src/shared-context.ts | 12 + 22 files changed, 2774 insertions(+), 232 deletions(-) create mode 100644 docs-util/packages/typedoc-config/pricing.js create mode 100644 docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/debug.ts diff --git a/.github/workflows/generate-references.yml b/.github/workflows/generate-references.yml index bca3d0b5a6..bd0b6e5859 100644 --- a/.github/workflows/generate-references.yml +++ b/.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" \ No newline at end of file diff --git a/docs-util/packages/typedoc-config/pricing.js b/docs-util/packages/typedoc-config/pricing.js new file mode 100644 index 0000000000..757524fed7 --- /dev/null +++ b/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", + }, + }, +}) diff --git a/docs-util/packages/typedoc-config/tsconfig.json b/docs-util/packages/typedoc-config/tsconfig.json index 4c545ff687..a76be3a3f6 100644 --- a/docs-util/packages/typedoc-config/tsconfig.json +++ b/docs-util/packages/typedoc-config/tsconfig.json @@ -1,7 +1,4 @@ { "extends": "../../tsconfig", - "compilerOptions": { - "outDir": "./dist" - }, "include": ["*.js"] } \ No newline at end of file diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts index 1ea653f6d4..ec39b35c06 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts +++ b/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() } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts index 8b80d6fb39..b1af6c89d6 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts +++ b/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 ? "" : "`**" diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/debug.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/debug.ts new file mode 100644 index 0000000000..700ca1927d --- /dev/null +++ b/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) + }) +} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts index 44bc160dd3..3892e160e8 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts +++ b/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" : "") } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/title-level.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/title-level.ts index a3f3e00f78..c33998b307 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/title-level.ts +++ b/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("") + } + ) } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type.ts index 3b160a7999..4d6ae4dc6d 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type.ts +++ b/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(", ")}\\>` ) } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature.hbs b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature.hbs index 7bb5718c54..b5ff6f2553 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature.hbs +++ b/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}} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts index e1f3a17011..c7d8cce3e9 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts +++ b/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")}` } } diff --git a/packages/types/src/common/common.ts b/packages/types/src/common/common.ts index 230fbb822a..094b4ebe2e 100644 --- a/packages/types/src/common/common.ts +++ b/packages/types/src/common/common.ts @@ -40,6 +40,22 @@ export type Writable = { | FindOperator } +/** + * @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 { select?: (keyof Entity | string)[] skip?: number diff --git a/packages/types/src/dal/index.ts b/packages/types/src/dal/index.ts index 7bb33ca9df..92f8da2702 100644 --- a/packages/types/src/dal/index.ts +++ b/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 { $and?: (T | BaseFilterable)[] $or?: (T | BaseFilterable)[] diff --git a/packages/types/src/pricing/common/currency.ts b/packages/types/src/pricing/common/currency.ts index 617abd5653..89acdb9a20 100644 --- a/packages/types/src/pricing/common/currency.ts +++ b/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 { code?: string[] diff --git a/packages/types/src/pricing/common/money-amount.ts b/packages/types/src/pricing/common/money-amount.ts index b63b24fb60..c233721cf8 100644 --- a/packages/types/src/pricing/common/money-amount.ts +++ b/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 { id?: string[] diff --git a/packages/types/src/pricing/common/price-rule.ts b/packages/types/src/pricing/common/price-rule.ts index 0d29a1a4dc..398fda2686 100644 --- a/packages/types/src/pricing/common/price-rule.ts +++ b/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 { id?: string[] diff --git a/packages/types/src/pricing/common/price-set-money-amount-rules.ts b/packages/types/src/pricing/common/price-set-money-amount-rules.ts index a315e61e71..451ffd9041 100644 --- a/packages/types/src/pricing/common/price-set-money-amount-rules.ts +++ b/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 { id?: string[] diff --git a/packages/types/src/pricing/common/price-set-money-amount.ts b/packages/types/src/pricing/common/price-set-money-amount.ts index d07b1ea9fe..e7877e8284 100644 --- a/packages/types/src/pricing/common/price-set-money-amount.ts +++ b/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 diff --git a/packages/types/src/pricing/common/price-set.ts b/packages/types/src/pricing/common/price-set.ts index 0bb48a7e69..8313ce09ea 100644 --- a/packages/types/src/pricing/common/price-set.ts +++ b/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 } +/** + * @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 +} + +/** + * @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 - })[] + 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 })[] + 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 { id?: string[] diff --git a/packages/types/src/pricing/common/rule-type.ts b/packages/types/src/pricing/common/rule-type.ts index 44619428c5..68aba6be4a 100644 --- a/packages/types/src/pricing/common/rule-type.ts +++ b/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 { id?: string[] diff --git a/packages/types/src/pricing/service.ts b/packages/types/src/pricing/service.ts index e3e35302ec..7b903145b4 100644 --- a/packages/types/src/pricing/service.ts +++ b/packages/types/src/pricing/service.ts @@ -36,16 +36,37 @@ import { ModuleJoinerConfig } from "../modules-sdk" import { Context } from "../shared-context" export interface IPricingModuleService { + /** + * @ignore + */ __joinerConfig(): ModuleJoinerConfig /** - * Calculates prices based on the provided filters and context. + * This method is used to calculate prices based on the provided filters and context. * - * @async - * @param {PricingFilters} filters - PriceSet filters - * @param {PricingContext=} context - Optional pricing context to select prices. - * @param {Context=} sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to the calculated prices. + * @param {PricingContext} filters - An object of type {@link PricingFilters} used to filter the price sets. + * @param {PricingContext} context - An object of type {@link PricingContext} to select prices. For example, the pricing context can specify the currency code to calculate prices in. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link CalculatedPriceSetDTO} which includes the calculated prices. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * async function calculatePrice (priceSetId: string, currencyCode: string) { + * const pricingService = await initializePricingModule() + * + * const price = await pricingService.calculatePrices( + * { id: [priceSetId] }, + * { + * context: { + * currency_code: currencyCode + * } + * } + * ) + * + * // do something with the price or return it + * } */ calculatePrices( filters: PricingFilters, @@ -54,13 +75,54 @@ export interface IPricingModuleService { ): Promise /** - * Retrieves a priceSet by its ID. + * This method is used to retrieves a price set by its ID. * - * @async - * @param {string} id - The ID of the priceSet to retrieve. - * @param {FindConfig=} config - Optional configuration for the retrieval. - * @param {Context=} sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to a PriceSetDTO. + * @param {string} id - A string indicating the ID of the price set to retrieve. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price set is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price set. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link PriceSetDTO} which is the retrieved price set. + * + * @example + * A simple example that retrieves a price set by its ID: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.retrieve( + * priceSetId + * ) + * + * // do something with the price set or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.retrieve( + * priceSetId, + * { + * relations: ["money_amounts"] + * } + * ) + * + * // do something with the price set or return it + * } + * ``` */ retrieve( id: string, @@ -69,13 +131,118 @@ export interface IPricingModuleService { ): Promise /** - * Lists price sets based on optional filters and configuration. + * This method is used to retrieve a paginated list of price sets based on optional filters and configuration. * - * @async - * @param {FilterablePriceSetProps=} filters - Optional filters to narrow down the list. - * @param {FindConfig=} config - Optional configuration. - * @param {Context=} sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to an array of PriceSetDTOs. + * @param {FilterablePriceSetProps} filters - An object of type {@link FilterablePriceSetProps} that is used to filter the retrieved price lists. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price sets are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price set. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetDTO}. + * + * @example + * + * To retrieve a list of price sets using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSets (priceSetIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.list( + * { + * id: priceSetIds + * }, + * ) + * + * // do something with the price sets or return them + * } + * ``` + * + * To specify relations that should be retrieved within the price sets: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSets (priceSetIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.list( + * { + * id: priceSetIds + * }, + * { + * relations: ["money_amounts"] + * } + * ) + * + * // do something with the price sets 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 retrievePriceSets (priceSetIds: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.list( + * { + * id: priceSetIds + * }, + * { + * relations: ["money_amounts"], + * skip, + * take + * } + * ) + * + * // do something with the price sets 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 retrievePriceSets (priceSetIds: string[], moneyAmountIds: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.list( + * { + * $and: [ + * { + * id: priceSetIds + * }, + * { + * money_amounts: { + * id: moneyAmountIds + * } + * } + * ] + * }, + * { + * relations: ["money_amounts"], + * skip, + * take + * } + * ) + * + * // do something with the price sets or return them + * } + * ``` */ list( filters?: FilterablePriceSetProps, @@ -84,11 +251,119 @@ export interface IPricingModuleService { ): Promise /** - * List priceSets and provide the total count. - * @param filters - Optional filters for listing. - * @param config - Optional configuration. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to an array of PriceSetDTOs and a count. + * This method is used to retrieve a paginated list of price sets along with the total count of available price sets satisfying the provided filters. + * + * @param {FilterablePriceSetProps} filters - An object of type {@link FilterablePriceSetProps} that is used to filter the retrieved price lists. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price sets are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price set. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[PriceSetDTO[], number]>} A promise that resolves to an array having two items, the first item is an array of objects of type {@link PriceSetDTO}, + * and the second item is a number indicating the total count. + * + * @example + * + * To retrieve a list of prices sets using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSets (priceSetIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const [priceSets, count] = await pricingService.listAndCount( + * { + * id: priceSetIds + * }, + * ) + * + * // do something with the price sets or return them + * } + * ``` + * + * To specify relations that should be retrieved within the price sets: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSets (priceSetIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const [priceSets, count] = await pricingService.listAndCount( + * { + * id: priceSetIds + * }, + * { + * relations: ["money_amounts"] + * } + * ) + * + * // do something with the price sets 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 retrievePriceSets (priceSetIds: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [priceSets, count] = await pricingService.listAndCount( + * { + * id: priceSetIds + * }, + * { + * relations: ["money_amounts"], + * skip, + * take + * } + * ) + * + * // do something with the price sets 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 retrievePriceSets (priceSetIds: string[], moneyAmountIds: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [priceSets, count] = await pricingService.listAndCount( + * { + * $and: [ + * { + * id: priceSetIds + * }, + * { + * money_amounts: { + * id: moneyAmountIds + * } + * } + * ] + * }, + * { + * relations: ["money_amounts"], + * skip, + * take + * } + * ) + * + * // do something with the price sets or return them + * } + * ``` */ listAndCount( filters?: FilterablePriceSetProps, @@ -97,18 +372,177 @@ export interface IPricingModuleService { ): Promise<[PriceSetDTO[], number]> /** - * Create a new priceSet. - * @param data - Data for creating a priceSet. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to the created PriceSetDTO. + * This method is used to create a new price set. + * + * @param {CreatePriceSetDTO} data - An object of type {@link CreatePriceSetDTO} that holds the attribute of the price set to create. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link PriceSetDTO}, which is the created price set. + * + * @example + * To create a default price set, don't pass any rules. For example: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createPriceSet () { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.create( + * { + * rules: [], + * prices: [ + * { + * amount: 500, + * currency_code: "USD", + * min_quantity: 0, + * max_quantity: 4, + * rules: {}, + * }, + * { + * amount: 400, + * currency_code: "USD", + * min_quantity: 5, + * max_quantity: 10, + * rules: {}, + * }, + * ], + * }, + * ) + * + * // do something with the price set or return it + * } + * ``` + * + * To create a price set and associate it with rule types: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createPriceSet () { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.create( + * { + * rules: [{ rule_attribute: "region_id" }, { rule_attribute: "city" }], + * prices: [ + * { + * amount: 300, + * currency_code: "EUR", + * rules: { + * region_id: "PL", + * city: "krakow" + * }, + * }, + * { + * amount: 400, + * currency_code: "EUR", + * rules: { + * region_id: "PL" + * }, + * }, + * { + * amount: 450, + * currency_code: "EUR", + * rules: { + * city: "krakow" + * }, + * } + * ], + * }, + * ) + * + * // do something with the price set or return it + * } + * ``` */ create(data: CreatePriceSetDTO, sharedContext?: Context): Promise /** - * Create multiple new priceSets. - * @param data - Array of data for creating priceSets. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to an array of created PriceSetDTOs. + * @overload + * + * This method is used to create multiple price sets. + * + * @param {CreatePriceSetDTO[]} data - An array of objects of type {@link CreatePriceSetDTO}, where each object holds the attribute of a price set to create. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetDTO}, which are the created price sets. + * + * @example + * To create price sets with a default price, don't pass any rules and make sure to pass the `currency_code` of the price. For example: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createPriceSets () { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.create([ + * { + * rules: [], + * prices: [ + * { + * amount: 500, + * currency_code: "USD", + * rules: {}, + * }, + * ], + * }, + * ]) + * + * // do something with the price sets or return them + * } + * ``` + * + * To create price sets and associate them with rule types: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createPriceSets () { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.create([ + * { + * rules: [{ rule_attribute: "region_id" }, { rule_attribute: "city" }], + * prices: [ + * { + * amount: 300, + * currency_code: "EUR", + * rules: { + * region_id: "PL", + * city: "krakow" + * }, + * }, + * { + * amount: 400, + * currency_code: "EUR", + * min_quantity: 0, + * max_quantity: 4, + * rules: { + * region_id: "PL" + * }, + * }, + * { + * amount: 450, + * currency_code: "EUR", + * rules: { + * city: "krakow" + * }, + * } + * ], + * }, + * ]) + * + * // do something with the price sets or return them + * } + * ``` */ create( data: CreatePriceSetDTO[], @@ -116,10 +550,15 @@ export interface IPricingModuleService { ): Promise /** - * Update existing priceSets. - * @param data - Array of data for updating priceSets. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to an array of updated PriceSetDTOs. + * @ignore + * @privateRemarks + * The update method shouldn't be documented at the moment + * + * This method is used to update existing price sets. + * + * @param {UpdatePriceSetDTO[]} data - An array of objects of type {@link UpdatePriceSetDTO}, each holding the data of the price sets to update. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetDTOs}, which are the updated price sets. */ update( data: UpdatePriceSetDTO[], @@ -127,10 +566,27 @@ export interface IPricingModuleService { ): Promise /** - * Remove rules from priceSet. - * @param data - Array of data for removing priceSet rules. - * @param sharedContext - Optional shared context. - * @returns A promise that resolves when rules are successfully removed. + * This method remove rules from a price set. + * + * @param {RemovePriceSetRulesDTO[]} data - An array of objects of type {@link RemovePriceSetRulesDTO}, each specfiying which rules to remove. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves when rules are successfully removed. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function removePriceSetRule (priceSetId: string, ruleAttributes: []) { + * const pricingService = await initializePricingModule() + * + * await pricingService.removeRules([ + * { + * id: priceSetId, + * rules: ruleAttributes + * }, + * ]) + * } */ removeRules( data: RemovePriceSetRulesDTO[], @@ -138,29 +594,182 @@ export interface IPricingModuleService { ): Promise /** - * Delete priceSets by their IDs. + * This method deletes price sets by their IDs. * - * @param ids - An array of IDs for priceSets to delete. - * @param sharedContext - Optional shared context. - * @returns A promise that resolves when the price sets are successfully deleted. + * @param {string[]} ids - An array of strings, each being the ID for a price set to delete. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves when the price sets are successfully deleted. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function removePriceSetRule (priceSetIds: string[]) { + * const pricingService = await initializePricingModule() + * + * await pricingService.delete(priceSetIds) + * } */ delete(ids: string[], sharedContext?: Context): Promise /** - * Add prices to a price set. + * This method adds prices to a price set. * - * @param data - Data for adding prices to a price set. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to the updated PriceSetDTO. + * @param {AddPricesDTO} data - An object of type {@link AddPricesDTO} that holds the data necessary to add the prices. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link PriceSetDTO}, which is the price set that the prices belong to. + * + * @example + * + * To add a default price to a price set, don't pass it any rules and make sure to pass it the `currency_code`: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function addPricesToPriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.addPrices({ + * priceSetId, + * prices: [ + * { + * amount: 500, + * currency_code: "USD", + * rules: {}, + * }, + * ], + * }) + * + * // do something with the price set or return it + * } + * ``` + * + * To add prices with rules: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function addPricesToPriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.addPrices({ + * priceSetId, + * prices: [ + * { + * amount: 300, + * currency_code: "EUR", + * rules: { + * region_id: "PL", + * city: "krakow" + * }, + * }, + * { + * amount: 400, + * currency_code: "EUR", + * min_quantity: 0, + * max_quantity: 4, + * rules: { + * region_id: "PL" + * }, + * }, + * { + * amount: 450, + * currency_code: "EUR", + * rules: { + * city: "krakow" + * }, + * } + * ], + * }) + * + * // do something with the price set or return it + * } + * ``` */ addPrices(data: AddPricesDTO, sharedContext?: Context): Promise /** - * Add prices to multiple price sets. + * This method adds prices to multiple price sets. * - * @param data - An array of data for adding prices to price sets. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to an array of updated PriceSetDTOs. + * @param {AddPricesDTO[]} data - An array of objects of type {@link AddPricesDTO}, each holding the data necessary to add the prices to the price set. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetDTO}, each being a price list that prices were added to. + * + * @example + * + * To add a default price to a price set, don't pass it any rules and make sure to pass it the `currency_code`: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function addPricesToPriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.addPrices([{ + * priceSetId, + * prices: [ + * { + * amount: 500, + * currency_code: "USD", + * rules: {}, + * }, + * ], + * }]) + * + * // do something with the price sets or return them + * } + * ``` + * + * To add prices with rules: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function addPricesToPriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.addPrices([{ + * priceSetId, + * prices: [ + * { + * amount: 300, + * currency_code: "EUR", + * rules: { + * region_id: "PL", + * city: "krakow" + * }, + * }, + * { + * amount: 400, + * currency_code: "EUR", + * min_quantity: 0, + * max_quantity: 4, + * rules: { + * region_id: "PL" + * }, + * }, + * { + * amount: 450, + * currency_code: "EUR", + * rules: { + * city: "krakow" + * }, + * } + * ], + * }]) + * + * // do something with the price sets or return them + * } + * ``` */ addPrices( data: AddPricesDTO[], @@ -168,30 +777,108 @@ export interface IPricingModuleService { ): Promise /** - * Add rules to a price set. + * This method adds rules to a price set. * - * @param data - Data for adding rules to a price set. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to the updated PriceSetDTO. + * @param {AddRulesDTO} data - An object of type {@link AddRulesDTO} that holds the necessary data to add rules to a price set. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link PriceSetDTO}, which is the price set that the rules belong to. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function addRulesToPriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSet = await pricingService.addRules({ + * priceSetId, + * rules: [{ + * attribute: "region_id" + * }] + * }) + * + * // do something with the price set or return it + * } */ addRules(data: AddRulesDTO, sharedContext?: Context): Promise /** - * Add rules to multiple price sets. + * This method adds rules to multiple price sets. * - * @param data - An array of data for adding rules to price sets. - * @param sharedContext - Optional shared context. - * @returns A promise resolving to an array of updated PriceSetDTOs. + * @param {AddRulesDTO[]} data - An array of objects of type {@link AddRulesDTO}, each holding the necessary data to add rules to a price set. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetDTO}, each being the price set that rules were added to. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function addRulesToPriceSet (priceSetId: string) { + * const pricingService = await initializePricingModule() + * + * const priceSets = await pricingService.addRules([{ + * priceSetId, + * rules: [{ + * attribute: "region_id" + * }] + * }]) + * + * // do something with the price sets or return them + * } */ addRules(data: AddRulesDTO[], sharedContext?: Context): Promise /** - * Retrieves a money amount by its ID. + * This method retrieves a money amount by its ID. * * @param {string} id - The ID of the money amount to retrieve. - * @param {FindConfig=} config - Optional configuration for the retrieval operation. - * @param sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to a MoneyAmountDTO. + * @param {FindConfig} config - + * An object of type {@link MoneyAmountDTO} used to configure how a money amount is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a money amount. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link MoneyAmountDTO} which is the retrieved money amount. + * + * @example + * To retrieve a money amount by its ID: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmount (moneyAmountId: string) { + * const pricingService = await initializePricingModule() + * + * const moneyAmount = await pricingService.retrieveMoneyAmount( + * moneyAmountId, + * ) + * + * // do something with the money amount or return it + * } + * ``` + * + * To retrieve relations along with the money amount: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmount (moneyAmountId: string) { + * const pricingService = await initializePricingModule() + * + * const moneyAmount = await pricingService.retrieveMoneyAmount( + * moneyAmountId, + * { + * relations: ["currency"] + * } + * ) + * + * // do something with the money amount or return it + * } + * ``` */ retrieveMoneyAmount( id: string, @@ -200,12 +887,116 @@ export interface IPricingModuleService { ): Promise /** - * Lists money amounts based on optional filters and configuration. + * This method is used to retrieve a paginated list of money amounts based on optional filters and configuration. * - * @param {FilterableMoneyAmountProps=} filters - Optional filters to narrow down the list. - * @param {FindConfig=} config - Optional configuration for the listing operation. - * @param sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to an array of MoneyAmountDTOs. + * @param {FilterableMoneyAmountProps} filters - An object of type {@link FilterableMoneyAmountProps} that is used to filter the retrieved money amounts. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the money amounts are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a money amount. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link MoneyAmountDTO}. + * + * @example + * + * To retrieve a list of money amounts using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmounts (moneyAmountIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const moneyAmounts = await pricingService.listMoneyAmounts( + * { + * id: moneyAmountIds + * } + * ) + * + * // do something with the money amounts or return them + * } + * ``` + * + * To specify relations that should be retrieved within the money amounts: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmounts (moneyAmountIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const moneyAmounts = await pricingService.listMoneyAmounts( + * { + * id: moneyAmountIds + * }, + * { + * relations: ["currency"] + * } + * ) + * + * // do something with the money amounts 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 retrieveMoneyAmounts (moneyAmountIds: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const moneyAmounts = await pricingService.listMoneyAmounts( + * { + * id: moneyAmountIds + * }, + * { + * relations: ["currency"], + * skip, + * take + * } + * ) + * + * // do something with the money amounts 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 retrieveMoneyAmounts (moneyAmountIds: string[], currencyCode: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const moneyAmounts = await pricingService.listMoneyAmounts( + * { + * $and: [ + * { + * id: moneyAmountIds + * }, + * { + * currency_code: currencyCode + * } + * ] + * }, + * { + * relations: ["currency"], + * skip, + * take + * } + * ) + * + * // do something with the money amounts or return them + * } + * ``` */ listMoneyAmounts( filters?: FilterableMoneyAmountProps, @@ -214,12 +1005,117 @@ export interface IPricingModuleService { ): Promise /** - * Lists money amounts based on optional filters and configuration and provides the total count. + * This method is used to retrieve a paginated list of money amounts along with the total count of available money amounts satisfying the provided filters. * - * @param {FilterableMoneyAmountProps=} filters - Optional filters to narrow down the list. - * @param {FindConfig=} config - Optional configuration for the listing operation. - * @param sharedContext - Optional shared context. - * @returns {Promise<[MoneyAmountDTO[], number]>} A promise that resolves to an array of MoneyAmountDTOs and the total count. + * @param {FilterableMoneyAmountProps} filters - An object of type {@link FilterableMoneyAmountProps} that is used to filter the retrieved money amounts. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the money amounts are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a money amount. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[MoneyAmountDTO[], number]>} A promise that resolves to an array having two items, the first item is an array of objects of type {@link MoneyAmountDTO}, + * and the second item is a number indicating the total count. + * + * @example + * + * To retrieve a list of money amounts using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmounts (moneyAmountIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const [moneyAmounts, count] = await pricingService.listAndCountMoneyAmounts( + * { + * id: moneyAmountIds + * } + * ) + * + * // do something with the money amounts or return them + * } + * ``` + * + * To specify relations that should be retrieved within the money amounts: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmounts (moneyAmountIds: string[]) { + * const pricingService = await initializePricingModule() + * + * const [moneyAmounts, count] = await pricingService.listAndCountMoneyAmounts( + * { + * id: moneyAmountIds + * }, + * { + * relations: ["currency"] + * } + * ) + * + * // do something with the money amounts 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 retrieveMoneyAmounts (moneyAmountIds: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [moneyAmounts, count] = await pricingService.listAndCountMoneyAmounts( + * { + * id: moneyAmountIds + * }, + * { + * relations: ["currency"], + * skip, + * take + * } + * ) + * + * // do something with the money amounts 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 retrieveMoneyAmounts (moneyAmountIds: string[], currencyCode: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [moneyAmounts, count] = await pricingService.listAndCountMoneyAmounts( + * { + * $and: [ + * { + * id: moneyAmountIds + * }, + * { + * currency_code: currencyCode + * } + * ] + * }, + * { + * relations: ["currency"], + * skip, + * take + * } + * ) + * + * // do something with the money amounts or return them + * } + * ``` */ listAndCountMoneyAmounts( filters?: FilterableMoneyAmountProps, @@ -228,11 +1124,35 @@ export interface IPricingModuleService { ): Promise<[MoneyAmountDTO[], number]> /** - * Creates new money amounts based on the provided data. + * This method creates money amounts. * - * @param {CreateMoneyAmountDTO[]} data - An array of data objects for creating money amounts. - * @param sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to an array of created MoneyAmountDTOs. + * @param {CreateMoneyAmountDTO[]} data - An array of objects of type {@link CreateMoneyAmountDTO} that holds the necessary data to create the money amount. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link MoneyAmountDTO}, each being a created money amount. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveMoneyAmounts () { + * const pricingService = await initializePricingModule() + * + * const moneyAmounts = await pricingService.createMoneyAmounts([ + * { + * amount: 500, + * currency_code: "USD", + * }, + * { + * amount: 400, + * currency_code: "USD", + * min_quantity: 0, + * max_quantity: 4 + * } + * ]) + * + * // do something with the money amounts or return them + * } */ createMoneyAmounts( data: CreateMoneyAmountDTO[], @@ -240,11 +1160,29 @@ export interface IPricingModuleService { ): Promise /** - * Updates existing money amounts based on the provided data. + * This method updates existing money amounts. * - * @param {UpdateMoneyAmountDTO[]} data - An array of data objects for updating money amounts. - * @param sharedContext - Optional shared context. - * @returns {Promise} A promise that resolves to an array of updated MoneyAmountDTOs. + * @param {UpdateMoneyAmountDTO[]} data - An array of objects of type {@link UpdateMoneyAmountDTO}, each holding data to update in a money amount. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link MoneyAmountDTO}, each being a updated money amount. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function updateMoneyAmounts (moneyAmountId: string, amount: number) { + * const pricingService = await initializePricingModule() + * + * const moneyAmounts = await pricingService.updateMoneyAmounts([ + * { + * id: moneyAmountId, + * amount + * } + * ]) + * + * // do something with the money amounts or return them + * } */ updateMoneyAmounts( data: UpdateMoneyAmountDTO[], @@ -252,21 +1190,76 @@ export interface IPricingModuleService { ): Promise /** - * Deletes money amounts by their IDs. + * This method deletes money amounts by their IDs. * - * @param {string[]} ids - An array of IDs for money amounts to delete. - * @param sharedContext - Optional shared context. + * @param {string[]} ids - An array of strings, each being the ID of a money amount to delete. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} A promise that resolves when the money amounts are successfully deleted. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function deleteMoneyAmounts (moneyAmountIds: string[]) { + * const pricingService = await initializePricingModule() + * + * await pricingService.deleteMoneyAmounts( + * moneyAmountIds + * ) + * } */ deleteMoneyAmounts(ids: string[], sharedContext?: Context): Promise /** - * Retrieves a currency by its code based on the provided configuration. + * This method retrieves a currency by its code and and optionally based on the provided configurations. * - * @param {string} code - The code of the currency to retrieve. - * @param {FindConfig} [config={}] - Optional configuration for retrieving the currency. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to the retrieved currency object. + * @param {string} code - A string indicating the code of the currency to retrieve. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the currency is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a currency. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link CurrencyDTO}. + * + * @example + * A simple example that retrieves a currency by its code: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveCurrency (code: string) { + * const pricingService = await initializePricingModule() + * + * const currency = await pricingService.retrieveCurrency( + * code + * ) + * + * // do something with the currency or return it + * } + * ``` + * + * To specify attributes that should be retrieved: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveCurrency (code: string) { + * const pricingService = await initializePricingModule() + * + * const currency = await pricingService.retrieveCurrency( + * code, + * { + * select: ["symbol_native"] + * } + * ) + * + * // do something with the currency or return it + * } + * ``` */ retrieveCurrency( code: string, @@ -275,12 +1268,84 @@ export interface IPricingModuleService { ): Promise /** - * Lists currencies based on the provided filters and configuration. + * This method is used to retrieve a paginated list of currencies based on optional filters and configuration. * - * @param {PricingTypes.FilterableCurrencyProps} [filters={}] - Optional filters to apply when listing currencies. - * @param {FindConfig} [config={}] - Optional configuration for listing currencies. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array containing the list of currency objects. + * @param {FilterableCurrencyProps} filters - An object of type {@link FilterableCurrencyProps} that is used to filter the retrieved currencies. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the currencies are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a currency. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link CurrencyDTO}. + * + * @example + * + * To retrieve a list of currencies using their codes: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveCurrencies (codes: string[]) { + * const pricingService = await initializePricingModule() + * + * const currencies = await pricingService.listCurrencies( + * { + * code: codes + * }, + * ) + * + * // do something with the currencies or return them + * } + * ``` + * + * To specify attributes that should be retrieved within the money amounts: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveCurrencies (codes: string[]) { + * const pricingService = await initializePricingModule() + * + * const currencies = await pricingService.listCurrencies( + * { + * code: codes + * }, + * { + * select: ["symbol_native"] + * } + * ) + * + * // do something with the currencies 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 retrieveCurrencies (codes: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const currencies = await pricingService.listCurrencies( + * { + * code: codes + * }, + * { + * select: ["symbol_native"], + * skip, + * take + * } + * ) + * + * // do something with the currencies or return them + * } + * ``` */ listCurrencies( filters?: FilterableCurrencyProps, @@ -289,12 +1354,85 @@ export interface IPricingModuleService { ): Promise /** - * Lists and counts currencies based on the provided filters and configuration. + * This method is used to retrieve a paginated list of currencies along with the total count of available currencies satisfying the provided filters. * - * @param {PricingTypes.FilterableCurrencyProps} [filters={}] - Optional filters to apply when listing currencies. - * @param {FindConfig} [config={}] - Optional configuration for listing currencies. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise<[PricingTypes.CurrencyDTO[], number]>} A Promise that resolves to an array containing the list of currency objects and the total count. + * @param {FilterableCurrencyProps} filters - An object of type {@link FilterableCurrencyProps} that is used to filter the retrieved currencies. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the currencies are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a currency. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[CurrencyDTO[], number]>} A promise that resolves to an array having two items, the first item is an array of objects of type {@link CurrencyDTO}, + * and the second item is a number indicating the total count. + * + * @example + * + * To retrieve a list of currencies using their codes: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveCurrencies (codes: string[]) { + * const pricingService = await initializePricingModule() + * + * const [currencies, count] = await pricingService.listAndCountCurrencies( + * { + * code: codes + * }, + * ) + * + * // do something with the currencies or return them + * } + * ``` + * + * To specify attributes that should be retrieved within the money amounts: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveCurrencies (codes: string[]) { + * const pricingService = await initializePricingModule() + * + * const [currencies, count] = await pricingService.listAndCountCurrencies( + * { + * code: codes + * }, + * { + * select: ["symbol_native"] + * } + * ) + * + * // do something with the currencies 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 retrieveCurrencies (codes: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [currencies, count] = await pricingService.listAndCountCurrencies( + * { + * code: codes + * }, + * { + * select: ["symbol_native"], + * skip, + * take + * } + * ) + * + * // do something with the currencies or return them + * } + * ``` */ listAndCountCurrencies( filters?: FilterableCurrencyProps, @@ -303,11 +1441,31 @@ export interface IPricingModuleService { ): Promise<[CurrencyDTO[], number]> /** - * Creates new currencies based on the provided data. + * This method is used to create new currencies. * - * @param {PricingTypes.CreateCurrencyDTO[]} data - An array of objects containing the data to create new currencies. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of newly created currency objects. + * @param {CreateCurrencyDTO[]} data - An array of objects of type {@link CreateCurrencyDTO}, each object holding the data of a currency to create. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link CurrencyDTO}, each object being a created currency. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createCurrencies () { + * const pricingService = await initializePricingModule() + * + * const currencies = await pricingService.createCurrencies([ + * { + * code: "USD", + * symbol: "$", + * symbol_native: "$", + * name: "US Dollar", + * } + * ]) + * + * // do something with the currencies or return them + * } */ createCurrencies( data: CreateCurrencyDTO[], @@ -315,11 +1473,29 @@ export interface IPricingModuleService { ): Promise /** - * Updates currencies with the provided data. + * This method is used to update existing currencies with the provided data. In each currency object, the currency code must be provided to identify which currency to update. * - * @param {PricingTypes.UpdateCurrencyDTO[]} data - An array of objects containing the data to update the currencies. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of updated currency objects. + * @param {UpdateCurrencyDTO[]} data - An array of objects of type {@link UpdateCurrencyDTO}, each object containing data to be updated in a currency. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link CurrencyDTO}, each object being an updated currency. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function updateCurrencies () { + * const pricingService = await initializePricingModule() + * + * const currencies = await pricingService.updateCurrencies([ + * { + * code: "USD", + * symbol: "$", + * } + * ]) + * + * // do something with the currencies or return them + * } */ updateCurrencies( data: UpdateCurrencyDTO[], @@ -327,11 +1503,23 @@ export interface IPricingModuleService { ): Promise /** - * Deletes currencies with the specified codes. + * This method is used to delete currencies based on their currency code. * - * @param {string[]} currencyCodes - An array of string codes representing the currencies to delete. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves once the currencies are deleted. + * @param {string[]} currencyCodes - An array of strings, each being a code of a currency to delete. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves once the currencies are deleted. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function deleteCurrencies () { + * const pricingService = await initializePricingModule() + * + * await pricingService.deleteCurrencies(["USD"]) + * + * } */ deleteCurrencies( currencyCodes: string[], @@ -339,12 +1527,49 @@ export interface IPricingModuleService { ): Promise /** - * Retrieves a rule type by its ID based on the provided configuration. + * This method is used to retrieve a rule type by its ID and and optionally based on the provided configurations. * * @param {string} id - The ID of the rule type to retrieve. - * @param {FindConfig} [config={}] - Optional configuration for retrieving the rule type. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to the retrieved rule type object. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the rule type is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a rule type. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link RuleTypeDTO}. + * + * @example + * A simple example that retrieves a rule type by its code: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveRuleType (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const ruleType = await pricingService.retrieveRuleType(ruleTypeId) + * + * // do something with the rule type or return it + * } + * ``` + * + * To specify attributes that should be retrieved: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveRuleType (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const ruleType = await pricingService.retrieveRuleType(ruleTypeId, { + * select: ["name"] + * }) + * + * // do something with the rule type or return it + * } + * ``` */ retrieveRuleType( code: string, @@ -353,12 +1578,111 @@ export interface IPricingModuleService { ): Promise /** - * Lists rule types based on the provided filters and configuration. + * This method is used to retrieve a paginated list of rule types based on optional filters and configuration. * - * @param {PricingTypes.FilterableRuleTypeProps} [filters={}] - Optional filters to apply when listing rule types. - * @param {FindConfig} [config={}] - Optional configuration for listing rule types. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array containing the list of rule type objects. + * @param {FilterableRuleTypeProps} filters - An object of type {@link FilterableRuleTypeProps} that is used to filter the retrieved rule types. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the rule types are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a rule type. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link RuleTypeDTO}. + * + * @example + * + * To retrieve a list of rule types using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveRuleTypes (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const ruleTypes = await pricingService.listRuleTypes({ + * id: [ + * ruleTypeId + * ] + * }) + * + * // do something with the rule types or return them + * } + * ``` + * + * To specify attributes that should be retrieved within the rule types: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveRuleTypes (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const ruleTypes = await pricingService.listRuleTypes({ + * id: [ + * ruleTypeId + * ] + * }, { + * select: ["name"] + * }) + * + * // do something with the rule types 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 retrieveRuleTypes (ruleTypeId: string, skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const ruleTypes = await pricingService.listRuleTypes({ + * id: [ + * ruleTypeId + * ] + * }, { + * select: ["name"], + * skip, + * take + * }) + * + * // do something with the rule types 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 retrieveRuleTypes (ruleTypeId: string[], name: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const ruleTypes = await pricingService.listRuleTypes({ + * $and: [ + * { + * id: ruleTypeId + * }, + * { + * name + * } + * ] + * }, { + * select: ["name"], + * skip, + * take + * }) + * + * // do something with the rule types or return them + * } + * ``` */ listRuleTypes( filters?: FilterableRuleTypeProps, @@ -367,12 +1691,112 @@ export interface IPricingModuleService { ): Promise /** - * Lists and counts rule types based on the provided filters and configuration. + * This method is used to retrieve a paginated list of rule types along with the total count of available rule types satisfying the provided filters. * - * @param {PricingTypes.FilterableRuleTypeProps} [filters={}] - Optional filters to apply when listing rule types. - * @param {FindConfig} [config={}] - Optional configuration for listing rule types. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise<[PricingTypes.RuleTypeDTO[], number]>} A Promise that resolves to an array containing the list of rule type objects and the total count. + * @param {FilterableRuleTypeProps} filters - An object of type {@link FilterableRuleTypeProps} that is used to filter the retrieved rule types. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the rule types are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a rule type. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[RuleTypeDTO[], number]>} A promise that resolves to an array having two items, the first item is an array of objects of type {@link RuleTypeDTO}, + * and the second item is a number indicating the total count. + * + * @example + * + * To retrieve a list of rule types using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveRuleTypes (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const [ruleTypes, count] = await pricingService.listAndCountRuleTypes({ + * id: [ + * ruleTypeId + * ] + * }) + * + * // do something with the rule types or return them + * } + * ``` + * + * To specify attributes that should be retrieved within the rule types: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrieveRuleTypes (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const [ruleTypes, count] = await pricingService.listAndCountRuleTypes({ + * id: [ + * ruleTypeId + * ] + * }, { + * select: ["name"] + * }) + * + * // do something with the rule types 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 retrieveRuleTypes (ruleTypeId: string, skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [ruleTypes, count] = await pricingService.listAndCountRuleTypes({ + * id: [ + * ruleTypeId + * ] + * }, { + * select: ["name"], + * skip, + * take + * }) + * + * // do something with the rule types 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 retrieveRuleTypes (ruleTypeId: string[], name: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [ruleTypes, count] = await pricingService.listAndCountRuleTypes({ + * $and: [ + * { + * id: ruleTypeId + * }, + * { + * name + * } + * ] + * }, { + * select: ["name"], + * skip, + * take + * }) + * + * // do something with the rule types or return them + * } + * ``` */ listAndCountRuleTypes( filters?: FilterableRuleTypeProps, @@ -381,11 +1805,29 @@ export interface IPricingModuleService { ): Promise<[RuleTypeDTO[], number]> /** - * Creates new rule types based on the provided data. + * This method is used to create new rule types. * - * @param {PricingTypes.CreateRuleTypeDTO[]} data - An array of objects containing the data to create new rule types. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of newly created rule type objects. + * @param {CreateRuleTypeDTO[]} data - An array of objects of type {@link CreateRuleTypeDTO}, each being the data to use to create a rule type. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link RuleTypeDTO}, each being a created rule type. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createRuleTypes () { + * const pricingService = await initializePricingModule() + * + * const ruleTypes = await pricingService.createRuleTypes([ + * { + * name: "Region", + * rule_attribute: "region_id" + * } + * ]) + * + * // do something with the rule types or return them + * } */ createRuleTypes( data: CreateRuleTypeDTO[], @@ -393,11 +1835,29 @@ export interface IPricingModuleService { ): Promise /** - * Updates rule types with the provided data. + * This method is used to update existing rule types with the provided data. * - * @param {PricingTypes.UpdateRuleTypeDTO[]} data - An array of objects containing the data to update the rule types. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of updated rule type objects. + * @param {UpdateRuleTypeDTO[]} data - An array of objects of type {@link UpdateRuleTypeDTO}, each object containing data to be updated in a rule type. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link RuleTypeDTO}, each being an updated rule type. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function updateRuleTypes (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * const ruleTypes = await pricingService.updateRuleTypes([ + * { + * id: ruleTypeId, + * name: "Region", + * } + * ]) + * + * // do something with the rule types or return them + * } */ updateRuleTypes( data: UpdateRuleTypeDTO[], @@ -405,21 +1865,69 @@ export interface IPricingModuleService { ): Promise /** - * Deletes rule types with the specified IDs. + * This method is used to delete rule types based on the provided IDs. * - * @param {string[]} ruleTypeIds - An array of string IDs representing the rule types to delete. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves once the rule types are deleted. + * @param {string[]} ruleTypeIds - An array of strings, each being the ID of a rule type to delete. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves once the rule types are deleted. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function deleteRuleTypes (ruleTypeId: string) { + * const pricingService = await initializePricingModule() + * + * await pricingService.deleteRuleTypes([ruleTypeId]) + * } */ deleteRuleTypes(ruleTypeIds: string[], sharedContext?: Context): Promise /** - * Retrieves a price set money amount rule by its ID based on the provided configuration. + * This method is used to a price set money amount rule by its ID based on the provided configuration. * - * @param {string} id - The ID of the price set money amount rule to retrieve. - * @param {FindConfig} [config={}] - Optional configuration for retrieving the price set money amount rule. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to the retrieved price set money amount rule object. + * @param {string} id - A string indicating the ID of the price set money amount rule to retrieve. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price set money amount rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price set money amount rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link PriceSetMoneyAmountRulesDTO}. + * + * @example + * A simple example that retrieves a price set money amount rule by its ID: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSetMoneyAmountRule (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRule = await pricingService.retrievePriceSetMoneyAmountRules(id) + * + * // do something with the price set money amount rule or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSetMoneyAmountRule (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRule = await pricingService.retrievePriceSetMoneyAmountRules(id, { + * relations: ["price_set_money_amount"] + * }) + * + * // do something with the price set money amount rule or return it + * } + * ``` */ retrievePriceSetMoneyAmountRules( id: string, @@ -428,12 +1936,106 @@ export interface IPricingModuleService { ): Promise /** - * Lists price set money amount rules based on the provided filters and configuration. + * This method is used to retrieve a paginated list of price set money amount rules based on optional filters and configuration. * - * @param {PricingTypes.FilterablePriceSetMoneyAmountRulesProps} [filters={}] - Optional filters to apply when listing price set money amount rules. - * @param {FindConfig} [config={}] - Optional configuration for listing price set money amount rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array containing the list of price set money amount rule objects. + * @param {FilterablePriceSetMoneyAmountRulesProps} filters - + * An object of type {@link FilterablePriceSetMoneyAmountRulesProps} that is used to filter the retrieved price set money amount rules. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price set money amount rules are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price set money amount rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetMoneyAmountRulesDTO}. + * + * @example + * + * To retrieve a list of price set money amount rules using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSetMoneyAmountRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRules = await pricingService.listPriceSetMoneyAmountRules({ + * id: [id] + * }) + * + * // do something with the price set money amount rules or return them + * } + * ``` + * + * To specify relations that should be retrieved within the price set money amount rules: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSetMoneyAmountRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRules = await pricingService.listPriceSetMoneyAmountRules({ + * id: [id] + * }, { + * relations: ["price_set_money_amount"] + * }) + * + * // do something with the price set money amount 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 retrievePriceSetMoneyAmountRules (id: string, skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRules = await pricingService.listPriceSetMoneyAmountRules({ + * id: [id] + * }, { + * relations: ["price_set_money_amount"], + * skip, + * take + * }) + * + * // do something with the price set money amount 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 retrievePriceSetMoneyAmountRules (ids: string[], ruleTypeId: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRules = await pricingService.listPriceSetMoneyAmountRules({ + * $and: [ + * { + * id: ids + * }, + * { + * rule_type_id: ruleTypeId + * } + * ] + * }, { + * relations: ["price_set_money_amount"], + * skip, + * take + * }) + * + * // do something with the price set money amount rules or return them + * } + * ``` */ listPriceSetMoneyAmountRules( filters?: FilterablePriceSetMoneyAmountRulesProps, @@ -442,12 +2044,108 @@ export interface IPricingModuleService { ): Promise /** - * Lists and counts price set money amount rules based on the provided filters and configuration. + * This method is used to retrieve a paginated list of price set money amount rules along with the total count of + * available price set money amount rules satisfying the provided filters. * - * @param {PricingTypes.FilterablePriceSetMoneyAmountRulesProps} [filters={}] - Optional filters to apply when listing price set money amount rules. - * @param {FindConfig} [config={}] - Optional configuration for listing price set money amount rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise<[PricingTypes.PriceSetMoneyAmountRulesDTO[], number]>} A Promise that resolves to an array containing the list of price set money amount rule objects and the total count. + * @param {FilterablePriceSetMoneyAmountRulesProps} filters - + * An object of type {@link FilterablePriceSetMoneyAmountRulesProps} that is used to filter the retrieved price set money amount rules. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price set money amount rules are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price set money amount rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[PriceSetMoneyAmountRulesDTO[], number]>} A promise that resolves to an array having two items, the first item is an array of objects of type {@link PriceSetMoneyAmountRulesDTO}, + * and the second item is a number indicating the total count. + * + * @example + * + * To retrieve a list of price set money amounts using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSetMoneyAmountRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const [priceSetMoneyAmountRules, count] = await pricingService.listAndCountPriceSetMoneyAmountRules({ + * id: [id] + * }) + * + * // do something with the price set money amount rules or return them + * } + * ``` + * + * To specify relations that should be retrieved within the price set money amount rules: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceSetMoneyAmountRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const [priceSetMoneyAmountRules, count] = await pricingService.listAndCountPriceSetMoneyAmountRules({ + * id: [id] + * }, { + * relations: ["price_set_money_amount"], + * }) + * + * // do something with the price set money amount 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 retrievePriceSetMoneyAmountRules (id: string, skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [priceSetMoneyAmountRules, count] = await pricingService.listAndCountPriceSetMoneyAmountRules({ + * id: [id] + * }, { + * relations: ["price_set_money_amount"], + * skip, + * take + * }) + * + * // do something with the price set money amount 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 retrievePriceSetMoneyAmountRules (ids: string[], ruleTypeId: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [priceSetMoneyAmountRules, count] = await pricingService.listAndCountPriceSetMoneyAmountRules({ + * $and: [ + * { + * id: ids + * }, + * { + * rule_type_id: ruleTypeId + * } + * ] + * }, { + * relations: ["price_set_money_amount"], + * skip, + * take + * }) + * + * // do something with the price set money amount rules or return them + * } + * ``` */ listAndCountPriceSetMoneyAmountRules( filters?: FilterablePriceSetMoneyAmountRulesProps, @@ -456,11 +2154,33 @@ export interface IPricingModuleService { ): Promise<[PriceSetMoneyAmountRulesDTO[], number]> /** - * Creates new price set money amount rules based on the provided data. + * This method is used to create new price set money amount rules. A price set money amount rule creates an association between a price set money amount and + * a rule type. * - * @param {PricingTypes.CreatePriceSetMoneyAmountRulesDTO[]} data - An array of objects containing the data to create new price set money amount rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of newly created price set money amount rule objects. + * @param {CreatePriceSetMoneyAmountRulesDTO[]} data - + * An array of objects of type {@link CreatePriceSetMoneyAmountRulesDTO}, each containing the data of a price set money amount rule to create. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetMoneyAmountRulesDTO}, each being + * a created price set money amount rule. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createPriceSetMoneyAmountRules (priceSetMoneyAmountId: string, ruleTypeId: string, value: string) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRules = await pricingService.createPriceSetMoneyAmountRules([ + * { + * price_set_money_amount: priceSetMoneyAmountId, + * rule_type: ruleTypeId, + * value + * } + * ]) + * + * // do something with the price set money amount rules or return them + * } */ createPriceSetMoneyAmountRules( data: CreatePriceSetMoneyAmountRulesDTO[], @@ -468,11 +2188,31 @@ export interface IPricingModuleService { ): Promise /** - * Updates price set money amount rules with the provided data. + * This method is used to update price set money amount rules, each with their provided data. * - * @param {PricingTypes.UpdatePriceSetMoneyAmountRulesDTO[]} data - An array of objects containing the data to update the price set money amount rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of updated price set money amount rule objects. + * @param {UpdatePriceSetMoneyAmountRulesDTO[]} data - + * An array of objects of type {@link UpdatePriceSetMoneyAmountRulesDTO}, each containing the data to update in a price set money amount rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceSetMoneyAmountRulesDTO}, each being the + * updated price set money amount rule. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function updatePriceSetMoneyAmountRules (id: string, value: string) { + * const pricingService = await initializePricingModule() + * + * const priceSetMoneyAmountRules = await pricingService.updatePriceSetMoneyAmountRules([ + * { + * id, + * value + * } + * ]) + * + * // do something with the price set money amount rules or return them + * } */ updatePriceSetMoneyAmountRules( data: UpdatePriceSetMoneyAmountRulesDTO[], @@ -480,11 +2220,22 @@ export interface IPricingModuleService { ): Promise /** - * Deletes price set money amount rules with the specified IDs. + * This method is used to delete price set money amount rules based on the specified IDs. * - * @param {string[]} ids - An array of string IDs representing the price set money amount rules to delete. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves once the price set money amount rules are deleted. + * @param {string[]} ids - An array of strings, each representing the ID of a price set money amount rule to delete. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves once the price set money amount rules are deleted. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function deletePriceSetMoneyAmountRule (id: string) { + * const pricingService = await initializePricingModule() + * + * await pricingService.deletePriceSetMoneyAmountRules([id]) + * } */ deletePriceSetMoneyAmountRules( ids: string[], @@ -492,12 +2243,49 @@ export interface IPricingModuleService { ): Promise /** - * Retrieves a price rule by its ID + * This method is used to retrieve a price rule by its ID. * * @param {string} id - The ID of the price rule to retrieve. - * @param {FindConfig} [config={}] - Optional configuration for retrieving the price rule. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to the retrieved price rule object. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an object of type {@link PriceRuleDTO}. + * + * @example + * A simple example that retrieves a price rule by its ID: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceRule (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceRule = await pricingService.retrievePriceRule(id) + * + * // do something with the price rule or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceRule (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceRule = await pricingService.retrievePriceRule(id, { + * relations: ["price_set"] + * }) + * + * // do something with the price rule or return it + * } + * ``` */ retrievePriceRule( id: string, @@ -506,12 +2294,106 @@ export interface IPricingModuleService { ): Promise /** - * Lists price rules based on the provided filters and configuration. + * This method is used to retrieve a paginated list of price rules based on optional filters and configuration. * - * @param {PricingTypes.FilterablePriceRuleProps} [filters={}] - Optional filters to apply when listing price rules. - * @param {FindConfig} [config={}] - Optional configuration for listing price rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array containing the list of price rule objects. + * @param {FilterablePriceRuleProps} filters - + * An object of type {@link FilterablePriceRuleProps} that is used to filter the retrieved price rules. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceRuleDTO}. + * + * @example + * + * To retrieve a list of price rules using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceRules = await pricingService.listPriceRules({ + * id: [id] + * }) + * + * // do something with the price rules or return them + * } + * ``` + * + * To specify relations that should be retrieved within the price rules: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const priceRules = await pricingService.listPriceRules({ + * id: [id], + * }, { + * relations: ["price_set"] + * }) + * + * // do something with the price 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 retrievePriceRules (id: string, skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const priceRules = await pricingService.listPriceRules({ + * id: [id], + * }, { + * relations: ["price_set"], + * skip, + * take + * }) + * + * // do something with the price 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 retrievePriceRules (ids: string[], name: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const priceRules = await pricingService.listPriceRules({ + * $and: [ + * { + * id: ids + * }, + * { + * name + * } + * ] + * }, { + * relations: ["price_set"], + * skip, + * take + * }) + * + * // do something with the price rules or return them + * } + * ``` */ listPriceRules( filters?: FilterablePriceRuleProps, @@ -520,12 +2402,106 @@ export interface IPricingModuleService { ): Promise /** - * Lists and counts price rules based on the provided filters and configuration. + * This method is used to retrieve a paginated list of price rules along with the total count of available price rules satisfying the provided filters. * - * @param {PricingTypes.FilterablePriceRuleProps} [filters={}] - Optional filters to apply when listing price rules. - * @param {FindConfig} [config={}] - Optional configuration for listing price rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise<[PricingTypes.PriceRuleDTO[], number]>} A Promise that resolves to an array containing the list of price rule objects and the total count. + * @param {FilterablePriceRuleProps} filters - + * An object of type {@link FilterablePriceRuleProps} that is used to filter the retrieved price rules. + * @param {FindConfig} config - + * An object of type {@link FindConfig} used to configure how the price rule is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a price rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceRuleDTO}. + * + * @example + * + * To retrieve a list of price rules using their IDs: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const [priceRules, count] = await pricingService.listAndCountPriceRules({ + * id: [id] + * }) + * + * // do something with the price rules or return them + * } + * ``` + * + * To specify relations that should be retrieved within the price rules: + * + * ```ts + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function retrievePriceRules (id: string) { + * const pricingService = await initializePricingModule() + * + * const [priceRules, count] = await pricingService.listAndCountPriceRules({ + * id: [id], + * }, { + * relations: ["price_set"] + * }) + * + * // do something with the price 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 retrievePriceRules (id: string, skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [priceRules, count] = await pricingService.listAndCountPriceRules({ + * id: [id], + * }, { + * relations: ["price_set"], + * skip, + * take + * }) + * + * // do something with the price 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 retrievePriceRules (ids: string[], name: string[], skip: number, take: number) { + * const pricingService = await initializePricingModule() + * + * const [priceRules, count] = await pricingService.listAndCountPriceRules({ + * $and: [ + * { + * id: ids + * }, + * { + * name + * } + * ] + * }, { + * relations: ["price_set"], + * skip, + * take + * }) + * + * // do something with the price rules or return them + * } + * ``` */ listAndCountPriceRules( filters?: FilterablePriceRuleProps, @@ -534,11 +2510,40 @@ export interface IPricingModuleService { ): Promise<[PriceRuleDTO[], number]> /** - * Creates new price rules based on the provided data. + * This method is used to create new price rules based on the provided data. * - * @param {PricingTypes.CreatePriceRuleDTO[]} data - An array of objects containing the data to create new price rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of newly created price rule objects. + * @param {CreatePriceRuleDTO[]} data - An array of objects of type {@link CreatePriceRuleDTO}, each containing the data necessary to create a price rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceRuleDTO}, each being a created price rule. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function createPriceRules ( + * id: string, + * priceSetId: string, + * ruleTypeId: string, + * value: string, + * priceSetMoneyAmountId: string, + * priceListId: string + * ) { + * const pricingService = await initializePricingModule() + * + * const priceRules = await pricingService.createPriceRules([ + * { + * id, + * price_set_id: priceSetId, + * rule_type_id: ruleTypeId, + * value, + * price_set_money_amount_id: priceSetMoneyAmountId, + * price_list_id: priceListId + * } + * ]) + * + * // do something with the price rules or return them + * } */ createPriceRules( data: CreatePriceRuleDTO[], @@ -546,11 +2551,32 @@ export interface IPricingModuleService { ): Promise /** - * Updates price rules with the provided data. + * This method is used to update price rules, each with their provided data. * - * @param {PricingTypes.UpdatePriceRuleDTO[]} data - An array of objects containing the data to update the price rules. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves to an array of updated price rule objects. + * @param {UpdatePriceRuleDTO[]} data - An array of objects of type {@link UpdatePriceRuleDTO}, each containing the data to update in a price rule. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves to an array of objects of type {@link PriceRuleDTO}, each being an updated price rule. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function updatePriceRules ( + * id: string, + * priceSetId: string, + * ) { + * const pricingService = await initializePricingModule() + * + * const priceRules = await pricingService.updatePriceRules([ + * { + * id, + * price_set_id: priceSetId, + * } + * ]) + * + * // do something with the price rules or return them + * } */ updatePriceRules( data: UpdatePriceRuleDTO[], @@ -558,11 +2584,24 @@ export interface IPricingModuleService { ): Promise /** - * Deletes price rules with the specified IDs. + * This method is used to delete price rules based on the specified IDs. * - * @param {string[]} priceRuleIds - An array of string IDs representing the price rules to delete. - * @param {Context} [sharedContext={}] - An optional shared MedusaContext object. - * @returns {Promise} A Promise that resolves once the price rules are deleted. + * @param {string[]} priceRuleIds - An array of strings, each being the ID of a price rule to delete. + * @param {Context} sharedContext - An object of type {@link Context} used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} A promise that resolves once the price rules are deleted. + * + * @example + * import { + * initialize as initializePricingModule, + * } from "@medusajs/pricing" + * + * async function deletePriceRules ( + * id: string, + * ) { + * const pricingService = await initializePricingModule() + * + * await pricingService.deletePriceRules([id]) + * } */ deletePriceRules( priceRuleIds: string[], diff --git a/packages/types/src/shared-context.ts b/packages/types/src/shared-context.ts index e86a6856af..a5d61fdcb5 100644 --- a/packages/types/src/shared-context.ts +++ b/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 = { transactionManager?: TManager manager?: TManager