diff --git a/.github/workflows/generate-references.yml b/.github/workflows/generate-references.yml index bd0b6e5859..8675faca3f 100644 --- a/.github/workflows/generate-references.yml +++ b/.github/workflows/generate-references.yml @@ -237,4 +237,49 @@ jobs: labels: "type: chore" add-paths: www/apps/docs/content/references/pricing/** branch: "docs/generate-pricing" + branch-suffix: "timestamp" + product: + 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 Product Module Reference + run: yarn generate:references product + working-directory: docs-utils/packages/scripts + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v4 + with: + commit-message: "chore(docs): Generated Product Module Reference (automated)" + base: "develop" + title: "chore(docs): Generated Product Module Reference" + labels: "type: chore" + add-paths: www/apps/docs/content/references/product/** + branch: "docs/generate-product" 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 index e2c890aec6..3df1dbe1bd 100644 --- a/docs-util/packages/typedoc-config/pricing.js +++ b/docs-util/packages/typedoc-config/pricing.js @@ -52,14 +52,4 @@ module.exports = modulesConfig({ }, }, ], - extraOptions: { - // frontmatterData: { - // displayed_sidebar: "modules", - // badge: { - // variant: "orange", - // text: "Beta", - // }, - // // hide_table_of_contents: true, - // }, - }, }) diff --git a/docs-util/packages/typedoc-config/product.js b/docs-util/packages/typedoc-config/product.js new file mode 100644 index 0000000000..3393f8106c --- /dev/null +++ b/docs-util/packages/typedoc-config/product.js @@ -0,0 +1,55 @@ +/* eslint-disable @typescript-eslint/no-var-requires */ +const modulesConfig = require("./modules") + +module.exports = modulesConfig({ + entryPointPath: "packages/types/src/product/service.ts", + outPath: "www/apps/docs/content/references/product", + moduleName: "Product Module Reference", + documentsToFormat: [ + { + pattern: "IProductModuleService.md", + additionalFormatting: { + reflectionDescription: + "This section of the documentation provides a reference to the `IProductModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Product Module.", + frontmatterData: { + displayed_sidebar: "productReference", + badge: { + variant: "orange", + text: "Beta", + }, + slug: "/references/product", + }, + }, + }, + { + pattern: "IProductModuleService/methods", + additionalFormatting: { + reflectionDescription: + "This documentation provides a reference to the {{alias}} {{kind}}. This belongs to the Product Module.", + frontmatterData: { + displayed_sidebar: "productReference", + badge: { + variant: "orange", + text: "Beta", + }, + slug: "/references/product/{{alias}}", + sidebar_label: "{{alias}}", + }, + reflectionTitle: { + kind: false, + typeParameters: false, + suffix: "- Product Module Reference", + }, + }, + }, + { + pattern: "*", + useDefaults: true, + additionalFormatting: { + frontmatterData: { + displayed_sidebar: "productReference", + }, + }, + }, + ], +}) 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 a327cecc22..322c8ee1bd 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 @@ -1,6 +1,7 @@ import { Comment, DeclarationReflection, + ReflectionKind, ProjectReflection, ReflectionType, SomeType, @@ -36,8 +37,13 @@ export function reflectionListFormatter( const prefix = `${Array(level - 1) .fill("\t") .join("")}-` - let item = `${prefix} \`${reflection.name}\`: ` + let item = `${prefix} \`${reflection.name}\`` const defaultValue = getDefaultValue(reflection) + const comments = getComments(reflection) + + if (defaultValue || reflection.flags.isOptional || comments) { + item += ": " + } if (defaultValue || reflection.flags.isOptional) { item += `(${reflection.flags.isOptional ? "optional" : ""}${ @@ -45,8 +51,6 @@ export function reflectionListFormatter( }${defaultValue ? `default: ${defaultValue}` : ""}) ` } - const comments = getComments(reflection) - if (comments) { item += stripLineBreaks(Handlebars.helpers.comments(comments)) } @@ -58,17 +62,18 @@ export function reflectionListFormatter( ? reflection.children : getTypeChildren(reflection.type!, reflection.project) const itemChildren: string[] = [] + let itemChildrenKind: ReflectionKind | null = null children?.forEach((childItem) => { + if (!itemChildrenKind) { + itemChildrenKind = childItem.kind + } itemChildren.push(reflectionListFormatter(childItem, level + 1)) }) 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 += ` ${ - reflection.type?.type === "array" - ? "Its items accept the following properties" - : "It accepts the following properties" - }:\n${itemChildren.join("\n")}` + item += ` ${getItemExpandText( + reflection.type?.type, + itemChildrenKind + )}:\n${itemChildren.join("\n")}` } } @@ -223,6 +228,24 @@ export function getComments( return parameter.comment } +// TODO we should add check for more types as necessary +function getItemExpandText( + reflectionType?: string, + childrenKind?: ReflectionKind | null +): string { + switch (childrenKind) { + case ReflectionKind.EnumMember: + return "It can be one of the following values" + } + + switch (reflectionType) { + case "array": + return "Its items accept the following properties" + default: + return "It accepts the following properties" + } +} + export function getTypeChildren( reflectionType: SomeType, project: ProjectReflection diff --git a/packages/types/src/dal/repository-service.ts b/packages/types/src/dal/repository-service.ts index f8d3e5f174..52f1dbe09d 100644 --- a/packages/types/src/dal/repository-service.ts +++ b/packages/types/src/dal/repository-service.ts @@ -79,10 +79,24 @@ export interface TreeRepositoryService delete(id: string, context?: Context): Promise } +/** + * @interface + * + * An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * + * @prop returnLinkableKeys - An array of strings, each being the ID attribute names of the entity's relations. + */ export type SoftDeleteReturn = { returnLinkableKeys?: TReturnableLinkableKeys[] } +/** + * @interface + * + * An object that is used to specify an entity's related entities that should be restored when the main entity is restored. + * + * @prop returnLinkableKeys - An array of strings, each being the ID attribute names of the entity's relations. + */ export type RestoreReturn = { returnLinkableKeys?: TReturnableLinkableKeys[] } diff --git a/packages/types/src/product/common.ts b/packages/types/src/product/common.ts index aa9a02875b..279cecfb9d 100644 --- a/packages/types/src/product/common.ts +++ b/packages/types/src/product/common.ts @@ -1,6 +1,9 @@ import { BaseFilterable } from "../dal" import { OperatorMap } from "../dal/utils" +/** + * @enum + */ export enum ProductStatus { DRAFT = "draft", PROPOSED = "proposed", @@ -9,10 +12,39 @@ export enum ProductStatus { } /** - * DTO in and out of the module (module API) + * @interface + * + * A product's data. + * @prop id - The ID of the product. + * @prop title - The title of the product. + * @prop handle - The handle of the product. The handle can be used to create slug URL paths. It can possibly be `null`. + * @prop subtitle - The subttle of the product. It can possibly be `null`. + * @prop description - The description of the product. It can possibly be `null`. + * @prop is_giftcard - Whether the product is a gift card. + * @prop status - The status of the product. Its value can be one of the values of the enum {@link ProductStatus}. + * @prop thumbnail - The URL of the product's thumbnail. It can possibly be `null`. + * @prop weight - The weight of the product. It can possibly be `null`. + * @prop length - The length of the product. It can possibly be `null`. + * @prop height - The height of the product. It can possibly be `null`. + * @prop origin_country - The origin country of the product. It can possibly be `null`. + * @prop hs_code - The HS Code of the product. It can possibly be `null`. + * @prop mid_code - The MID Code of the product. It can possibly be `null`. + * @prop material - The material of the product. It can possibly be `null`. + * @prop collection - The associated product collection. It may only be available if the `collection` relation is expanded. + * @prop categories -The associated product categories. It may only be available if the `categories` relation is expanded. + * @prop type - The associated product type. It may only be available if the `type` relation is expanded. + * @prop tags - The associated product tags. It may only be available if the `tags` relation is expanded. + * @prop variants - The associated product variants. It may only be available if the `variants` relation is expanded. + * @prop options - The associated product options. It may only be available if the `options` relation is expanded. + * @prop images - The associated product images. It may only be available if the `images` relation is expanded. + * @prop discountable - Whether the product can be discounted. + * @prop external_id - + * The ID of the product in an external system. This is useful if you're integrating the product with a third-party service and want to maintain + * a reference to the ID in the integrated service. + * @prop created_at - When the product was created. + * @prop updated_at - When the product was updated. + * @prop deleted_at - When the product was deleted. */ - -// TODO: This DTO should represent the product, when used in config we should use Partial, it means that some props like handle should be updated to not be optional export interface ProductDTO { id: string title: string @@ -45,6 +77,37 @@ export interface ProductDTO { metadata?: Record } +/** + * @interface + * + * A product variant's data. + * + * @prop id - The ID of the product variant. + * @prop title - The tile of the product variant. + * @prop sku - The SKU of the product variant. It can possibly be `null`. + * @prop barcode - The barcode of the product variant. It can possibly be `null`. + * @prop ean - The EAN of the product variant. It can possibly be `null`. + * @prop upc - The UPC of the product variant. It can possibly be `null`. + * @prop inventory_quantity - The inventory quantiy of the product variant. + * @prop allow_backorder - Whether the product variant can be ordered when it's out of stock. + * @prop manage_inventory - Whether the product variant's inventory should be managed by the core system. + * @prop hs_code - The HS Code of the product variant. It can possibly be `null`. + * @prop origin_country - The origin country of the product variant. It can possibly be `null`. + * @prop mid_code - The MID Code of the product variant. It can possibly be `null`. + * @prop material - The material of the product variant. It can possibly be `null`. + * @prop weight - The weight of the product variant. It can possibly be `null`. + * @prop length - The length of the product variant. It can possibly be `null`. + * @prop height - The height of the product variant. It can possibly be `null`. + * @prop width - The width of the product variant. It can possibly be `null`. + * @prop options - The associated product options. It may only be available if the `options` relation is expanded. + * @prop metadata - Holds custom data in key-value pairs. + * @prop product - The associated product. It may only be available if the `product` relation is expanded. + * @prop product_id - The ID of the associated product. + * @prop variant_rank - The ranking of the variant among other variants associated with the product. It can possibly be `null`. + * @prop created_at - When the product variant was created. + * @prop updated_at - When the product variant was updated. + * @prop deleted_at - When the product variant was deleted. + */ export interface ProductVariantDTO { id: string title: string @@ -73,6 +136,23 @@ export interface ProductVariantDTO { deleted_at: string | Date } +/** + * @interface + * + * A product category's data. + * + * @prop id - The ID of the product category. + * @prop name - The name of the product category. + * @prop description - The description of the product category. + * @prop handle - The handle of the product category. The handle can be used to create slug URL paths. + * @prop is_active - Whether the product category is active. + * @prop is_internal - Whether the product category is internal. This can be used to only show the product category to admins and hide it from customers. + * @prop rank - The ranking of the product category among sibling categories. + * @prop parent_category - The associated parent category. It may only be available if the `parent_category` relation is expanded. + * @prop category_children - The associated child categories. It may only be available if the `category_children` relation is expanded. + * @prop created_at - When the product category was created. + * @prop updated_at - When the product category was updated. + */ export interface ProductCategoryDTO { id: string name: string @@ -87,6 +167,19 @@ export interface ProductCategoryDTO { updated_at: string | Date } +/** + * @interface + * + * A product category to create. + * + * @prop name - The product category's name. + * @prop handle - The product category's handle. + * @prop is_active - Whether the product category is active. + * @prop is_internal - Whether the product category is internal. This can be used to only show the product category to admins and hide it from customers. + * @prop rank - The ranking of the category among sibling categories. + * @prop parent_category_id - The ID of the parent product category, if it has any. It may also be `null`. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface CreateProductCategoryDTO { name: string handle?: string @@ -97,6 +190,19 @@ export interface CreateProductCategoryDTO { metadata?: Record } +/** + * @interface + * + * The data to update in a product category. + * + * @prop name - The name of the product category. + * @prop handle - The handle of the product category. + * @prop is_active - Whether the product category is active. + * @prop is_internal - Whether the product category is internal. This can be used to only show the product category to admins and hide it from customers. + * @prop rank - The ranking of the category among sibling categories. + * @prop parent_category_id - The ID of the parent product category, if it has any. It may also be `null`. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface UpdateProductCategoryDTO { name?: string handle?: string @@ -107,6 +213,16 @@ export interface UpdateProductCategoryDTO { metadata?: Record } +/** + * @interface + * + * A product tag's data. + * + * @prop id - The ID of the product tag. + * @prop value - The value of the product tag. + * @prop metadata - Holds custom data in key-value pairs. + * @prop products - The associated products. It may only be available if the `products` relation is expanded. + */ export interface ProductTagDTO { id: string value: string @@ -114,6 +230,18 @@ export interface ProductTagDTO { products?: ProductDTO[] } +/** + * @interface + * + * A product collection's data. + * + * @prop id - The ID of the product collection. + * @prop title - The title of the product collection. + * @prop handle - The handle of the product collection. The handle can be used to create slug URL paths. + * @prop metadata - Holds custom data in key-value pairs. + * @prop deleted_at - When the product collection was deleted. + * @prop products - The associated products. It may only be available if the `products` relation is expanded. + */ export interface ProductCollectionDTO { id: string title: string @@ -123,6 +251,16 @@ export interface ProductCollectionDTO { products?: ProductDTO[] } +/** + * @interface + * + * A product type's data. + * + * @prop id - The ID of the product type. + * @prop value - The value of the product type. + * @prop metadata - Holds custom data in key-value pairs. + * @prop deleted_at - When the product type was deleted. + */ export interface ProductTypeDTO { id: string value: string @@ -130,6 +268,19 @@ export interface ProductTypeDTO { deleted_at?: string | Date } +/** + * @interface + * + * A product option's data. + * + * @prop id - The ID of the product option. + * @prop title - The title of the product option. + * @prop product - The associated product. It may only be available if the `product` relation is expanded. + * @prop values - The associated product option values. It may only be available if the `values` relation is expanded. + * @prop metadata - Holds custom data in key-value pairs. + * @prop deleted_at - When the product option was deleted. + * + */ export interface ProductOptionDTO { id: string title: string @@ -139,6 +290,16 @@ export interface ProductOptionDTO { deleted_at?: string | Date } +/** + * @interface + * + * The product image's data. + * + * @prop id - The ID of the product image. + * @prop url - The URL of the product image. + * @prop metadata - Holds custom data in key-value pairs. + * @prop deleted_at - When the product image was deleted. + */ export interface ProductImageDTO { id: string url: string @@ -146,6 +307,18 @@ export interface ProductImageDTO { deleted_at?: string | Date } +/** + * @interface + * + * The product option value's data. + * + * @prop id - The ID of the product option value. + * @prop value - The value of the product option value. + * @prop option - The associated product option. It may only be available if the `option` relation is expanded. + * @prop variant - The associated product variant. It may only be available if the `variant` relation is expanded. + * @prop metadata - Holds custom data in key-value pairs. + * @prop deleted_at - When the product option value was deleted. + */ export interface ProductOptionValueDTO { id: string value: string @@ -156,7 +329,16 @@ export interface ProductOptionValueDTO { } /** - * Filters/Config (module API input filters and config) + * @interface + * + * The filters to apply on retrieved products. + * + * @prop q - Search through the products' attributes, such as titles and descriptions, using this search term. + * @prop handle - The handles to filter products by. + * @prop id - The IDs to filter products by. + * @prop tags - Filters on a product's tags. + * @prop categories - Filters on a product's categories. + * @prop collection_id - Filters a product by its associated collections. */ export interface FilterableProductProps extends BaseFilterable { @@ -173,18 +355,43 @@ export interface FilterableProductProps collection_id?: string | string[] | OperatorMap } +/** + * @interface + * + * The filters to apply on retrieved product tags. + * + * @prop id - The IDs to filter product tags by. + * @prop value - The value to filter product tags by. + */ export interface FilterableProductTagProps extends BaseFilterable { id?: string | string[] value?: string } +/** + * @interface + * + * The filters to apply on retrieved product types. + * + * @prop id - The IDs to filter product types by. + * @prop value - The value to filter product types by. + */ export interface FilterableProductTypeProps extends BaseFilterable { id?: string | string[] value?: string } +/** + * @interface + * + * The filters to apply on retrieved product options. + * + * @prop id - The IDs to filter product options by. + * @prop title - The titles to filter product options by. + * @prop product_id - Filter the product options by their associated products' IDs. + */ export interface FilterableProductOptionProps extends BaseFilterable { id?: string | string[] @@ -192,6 +399,14 @@ export interface FilterableProductOptionProps product_id?: string | string[] } +/** + * @interface + * + * The filters to apply on retrieved product collections. + * + * @prop id - The IDs to filter product collections by. + * @prop title - The title to filter product collections by. + */ export interface FilterableProductCollectionProps extends BaseFilterable { id?: string | string[] @@ -199,6 +414,16 @@ export interface FilterableProductCollectionProps title?: string } +/** + * @interface + * + * The filters to apply on retrieved product variants. + * + * @prop id - The IDs to filter product variants by. + * @prop sku - The SKUs to filter product variants by. + * @prop product_id - Filter the product variants by their associated products' IDs. + * @prop options - Filter product variants by their associated options. + */ export interface FilterableProductVariantProps extends BaseFilterable { id?: string | string[] @@ -207,6 +432,19 @@ export interface FilterableProductVariantProps options?: { id?: string[] } } +/** + * @interface + * + * The filters to apply on retrieved product categories. + * + * @prop id - The IDs to filter product categories by. + * @prop name - The names to filter product categories by. + * @prop parent_category_id - Filter product categories by their parent category's ID. + * @prop handle - The handles to filter product categories by. + * @prop is_active - Filter product categories by whether they're active. + * @prop is_internal - Filter product categories by whether they're internal. + * @prop include_descendants_tree - Whether to include children of retrieved product categories. + */ export interface FilterableProductCategoryProps extends BaseFilterable { id?: string | string[] @@ -219,9 +457,15 @@ export interface FilterableProductCategoryProps } /** - * Write DTO (module API input) + * @interface + * + * A product collection to create. + * + * @prop title - The product collection's title. + * @prop handle - The product collection's handle. If not provided, the value of this attribute is set to the slug version of the title. + * @prop products - The products to associate with the collection. + * @prop metadata - Holds custom data in key-value pairs. */ - export interface CreateProductCollectionDTO { title: string handle?: string @@ -229,6 +473,18 @@ export interface CreateProductCollectionDTO { metadata?: Record } +/** + * @interface + * + * The data to update in a product collection. The `id` is used to identify which product collection to update. + * + * @prop id - The ID of the product collection to update. + * @prop value - The value of the product collection. + * @prop title - The title of the product collection. + * @prop handle - The handle of the product collection. + * @prop product_ids - The IDs of the products to associate with the product collection. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface UpdateProductCollectionDTO { id: string value?: string @@ -238,6 +494,15 @@ export interface UpdateProductCollectionDTO { metadata?: Record } +/** + * @interface + * + * A product type to create. + * + * @prop id - The product type's ID. + * @prop value - The product type's value. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface CreateProductTypeDTO { id?: string value: string @@ -249,12 +514,28 @@ export interface UpsertProductTypeDTO { value: string } +/** + * @interface + * + * The data to update in a product type. The `id` is used to identify which product type to update. + * + * @prop id - The ID of the product type to update. + * @prop value - The new value of the product type. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface UpdateProductTypeDTO { id: string value?: string metadata?: Record } +/** + * @interface + * + * A product tag to create. + * + * @prop value - The value of the product tag. + */ export interface CreateProductTagDTO { value: string } @@ -264,11 +545,28 @@ export interface UpsertProductTagDTO { value: string } +/** + * + * @interface + * + * The data to update in a product tag. The `id` is used to identify which product tag to update. + * + * @prop id - The ID of the product tag to update. + * @prop value - The value of the product tag. + */ export interface UpdateProductTagDTO { id: string value?: string } +/** + * @interface + * + * A product option to create. + * + * @prop title - The product option's title. + * @prop product_id - The ID of the associated product. + */ export interface CreateProductOptionDTO { title: string product_id?: string @@ -280,10 +578,41 @@ export interface UpdateProductOptionDTO { product_id?: string } +/** + * @interface + * + * A product variant option to create. + * + * @prop value - The value of a product variant option. + */ export interface CreateProductVariantOptionDTO { value: string } +/** + * @interface + * + * A product variant to create. + * + * @prop title - The tile of the product variant. + * @prop sku - The SKU of the product variant. + * @prop barcode - The barcode of the product variant. + * @prop ean - The EAN of the product variant. + * @prop upc - The UPC of the product variant. + * @prop allow_backorder - Whether the product variant can be ordered when it's out of stock. + * @prop inventory_quantity - The inventory quantiy of the product variant. + * @prop manage_inventory - Whether the product variant's inventory should be managed by the core system. + * @prop hs_code - The HS Code of the product variant. + * @prop origin_country - The origin country of the product variant. + * @prop mid_code - The MID Code of the product variant. + * @prop material - The material of the product variant. + * @prop weight - The weight of the product variant. + * @prop length - The length of the product variant. + * @prop height - The height of the product variant. + * @prop width - The width of the product variant. + * @prop options - The product variant options to create and associate with the product variant. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface CreateProductVariantDTO { title: string sku?: string @@ -305,6 +634,31 @@ export interface CreateProductVariantDTO { metadata?: Record } +/** + * @interface + * + * The data to update in a product variant. The `id` is used to identify which product variant to update. + * + * @prop id - The ID of the product variant to update. + * @prop title - The tile of the product variant. + * @prop sku - The SKU of the product variant. + * @prop barcode - The barcode of the product variant. + * @prop ean - The EAN of the product variant. + * @prop upc - The UPC of the product variant. + * @prop allow_backorder - Whether the product variant can be ordered when it's out of stock. + * @prop inventory_quantity - The inventory quantiy of the product variant. + * @prop manage_inventory - Whether the product variant's inventory should be managed by the core system. + * @prop hs_code - The HS Code of the product variant. + * @prop origin_country - The origin country of the product variant. + * @prop mid_code - The MID Code of the product variant. + * @prop material - The material of the product variant. + * @prop weight - The weight of the product variant. + * @prop length - The length of the product variant. + * @prop height - The height of the product variant. + * @prop width - The width of the product variant. + * @prop options - The product variant options to create and associate with the product variant. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface UpdateProductVariantDTO { id: string title?: string @@ -327,6 +681,41 @@ export interface UpdateProductVariantDTO { metadata?: Record } +/** + * @interface + * + * A product to create. + * + * @prop title - The title of the product. + * @prop subtitle - The subttle of the product. + * @prop description - The description of the product. + * @prop is_giftcard - Whether the product is a gift card. + * @prop discountable - Whether the product can be discounted. + * @prop images - + * The product's images. If an array of strings is supplied, each string will be a URL and a `ProductImage` will be created + * and associated with the product. If an array of objects is supplied, you can pass along the ID of an existing `ProductImage`. + * @prop thumbnail - The URL of the product's thumbnail. + * @prop handle - + * The handle of the product. The handle can be used to create slug URL paths. + * If not supplied, the value of the `handle` attribute of the product is set to the slug version of the `title` attribute. + * @prop status - The status of the product. Its value can be one of the values of the enum {@link ProductStatus}. + * @prop type - The product type to create and associate with the product. + * @prop type_id - The product type to be associated with the product. + * @prop collection_id - The product collection to be associated with the product. + * @prop tags - The product tags to be created and associated with the product. + * @prop categories - The product categories to associate with the product. + * @prop options - The product options to be created and associated with the product. + * @prop variants - The product variants to be created and associated with the product. + * @prop width - The width of the product. + * @prop height - The height of the product. + * @prop length - The length of the product. + * @prop weight - The weight of the product. + * @prop origin_country - The origin country of the product. + * @prop hs_code - The HS Code of the product. + * @prop material - The material of the product. + * @prop mid_code - The MID Code of the product. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface CreateProductDTO { title: string subtitle?: string @@ -355,6 +744,43 @@ export interface CreateProductDTO { metadata?: Record } +/** + * @interface + * + * The data to update in a product. The `id` is used to identify which product to update. + * + * @prop id - The ID of the product to update. + * @prop title - The title of the product. + * @prop subtitle - The subttle of the product. + * @prop description - The description of the product. + * @prop is_giftcard - Whether the product is a gift card. + * @prop discountable - Whether the product can be discounted. + * @prop images - + * The product's images. If an array of strings is supplied, each string will be a URL and a `ProductImage` will be created + * and associated with the product. If an array of objects is supplied, you can pass along the ID of an existing `ProductImage`. + * @prop thumbnail - The URL of the product's thumbnail. + * @prop handle - + * The handle of the product. The handle can be used to create slug URL paths. + * If not supplied, the value of the `handle` attribute of the product is set to the slug version of the `title` attribute. + * @prop status - The status of the product. Its value can be one of the values of the enum {@link ProductStatus}. + * @prop type - The product type to create and associate with the product. + * @prop type_id - The product type to be associated with the product. + * @prop collection_id - The product collection to be associated with the product. + * @prop tags - The product tags to be created and associated with the product. + * @prop categories - The product categories to associate with the product. + * @prop options - The product options to be created and associated with the product. + * @prop variants - + * The product variants to be created and associated with the product. You can also update existing product variants associated with the product. + * @prop width - The width of the product. + * @prop height - The height of the product. + * @prop length - The length of the product. + * @prop weight - The weight of the product. + * @prop origin_country - The origin country of the product. + * @prop hs_code - The HS Code of the product. + * @prop material - The material of the product. + * @prop mid_code - The MID Code of the product. + * @prop metadata - Holds custom data in key-value pairs. + */ export interface UpdateProductDTO { id: string title?: string diff --git a/packages/types/src/product/service.ts b/packages/types/src/product/service.ts index d0d51b448e..0aec405192 100644 --- a/packages/types/src/product/service.ts +++ b/packages/types/src/product/service.ts @@ -33,219 +33,2401 @@ import { ModuleJoinerConfig } from "../modules-sdk" import { Context } from "../shared-context" export interface IProductModuleService { + /** + * @ignore + */ __joinerConfig(): ModuleJoinerConfig + /** + * This method is used to retrieve a product by its ID + * + * @param {string} productId - The ID of the product to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product. + * + * @example + * A simple example that retrieves a product by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProduct (id: string) { + * const productModule = await initializeProductModule() + * + * const product = await productModule.retrieve(id) + * + * // do something with the product 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( productId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of price sets based on optional filters and configuration. + * + * @param {FilterableProductProps} filters - The filters to apply on the retrieved products. + * @param {FindConfig} config - + * The configurations determining how the products are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of products. + * + * @example + * To retrieve a list of products using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const products = await productModule.list({ + * id: ids + * }) + * + * // do something with the products or return them + * } + * ``` + * + * To specify relations that should be retrieved within the products: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const products = await productModule.list({ + * id: ids + * }, { + * relations: ["categories"] + * }) + * + * // do something with the products 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const products = await productModule.list({ + * id: ids + * }, { + * relations: ["categories"], + * skip, + * take + * }) + * + * // do something with the products 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[], title: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const products = await productModule.list({ + * $and: [ + * { + * id: ids + * }, + * { + * q: title + * } + * ] + * }, { + * relations: ["categories"], + * skip, + * take + * }) + * + * // do something with the products or return them + * } + * ``` + */ list( filters?: FilterableProductProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of products along with the total count of available products satisfying the provided filters. + * + * @param {FilterableProductProps} filters - The filters to apply on the retrieved products. + * @param {FindConfig} config - + * The configurations determining how the products are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of products along with the total count. + * + * @example + * To retrieve a list of products using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [products, count] = await productModule.listAndCount({ + * id: ids + * }) + * + * // do something with the products or return them + * } + * ``` + * + * To specify relations that should be retrieved within the products: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [products, count] = await productModule.listAndCount({ + * id: ids + * }, { + * relations: ["categories"] + * }) + * + * // do something with the products 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [products, count] = await productModule.listAndCount({ + * id: ids + * }, { + * relations: ["categories"], + * skip, + * take + * }) + * + * // do something with the products 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProducts (ids: string[], title: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [products, count] = await productModule.listAndCount({ + * $and: [ + * { + * id: ids + * }, + * { + * q: title + * } + * ] + * }, { + * relations: ["categories"], + * skip, + * take + * }) + * + * // do something with the products or return them + * } + * ``` + */ listAndCount( filters?: FilterableProductProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductDTO[], number]> + /** + * This method is used to retrieve a tag by its ID. + * + * @param {string} tagId - The ID of the tag to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product tag is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product tag. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product tag. + * + * @example + * A simple example that retrieves a product tag by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagId: string) { + * const productModule = await initializeProductModule() + * + * const productTag = await productModule.retrieveTag(tagId) + * + * // do something with the product tag or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagId: string) { + * const productModule = await initializeProductModule() + * + * const productTag = await productModule.retrieveTag(tagId, { + * relations: ["products"] + * }) + * + * // do something with the product tag or return it + * } + * ``` + */ retrieveTag( tagId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of tags based on optional filters and configuration. + * + * @param {FilterableProductTagProps} filters - The filters applied on the retrieved product tags. + * @param {FindConfig} config - + * The configurations determining how the product tags are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product tag. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product tags. + * + * @example + * To retrieve a list of product tags using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[]) { + * const productModule = await initializeProductModule() + * + * const productTags = await productModule.listTags({ + * id: tagIds + * }) + * + * // do something with the product tags or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product tags: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[]) { + * const productModule = await initializeProductModule() + * + * const productTags = await productModule.listTags({ + * id: tagIds + * }, { + * relations: ["products"] + * }) + * + * // do something with the product tags 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const productTags = await productModule.listTags({ + * id: tagIds + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product tags 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[], value: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const productTags = await productModule.listTags({ + * $and: [ + * { + * id: tagIds + * }, + * { + * value + * } + * ] + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product tags or return them + * } + * ``` + */ listTags( filters?: FilterableProductTagProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product tags along with the total count of available product tags satisfying the provided filters. + * + * @param {FilterableProductTagProps} filters - The filters applied on the retrieved product tags. + * @param {FindConfig} config - + * The configurations determining how the product tags are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product tag. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ProductTagDTO[], number]>} The list of product tags along with the total count. + * + * @example + * To retrieve a list of product tags using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[]) { + * const productModule = await initializeProductModule() + * + * const [productTags, count] = await productModule.listAndCountTags({ + * id: tagIds + * }) + * + * // do something with the product tags or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product tags: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[]) { + * const productModule = await initializeProductModule() + * + * const [productTags, count] = await productModule.listAndCountTags({ + * id: tagIds + * }, { + * relations: ["products"] + * }) + * + * // do something with the product tags 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [productTags, count] = await productModule.listAndCountTags({ + * id: tagIds + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product tags 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTag (tagIds: string[], value: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [productTags, count] = await productModule.listAndCountTags({ + * $and: [ + * { + * id: tagIds + * }, + * { + * value + * } + * ] + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product tags or return them + * } + * ``` + */ listAndCountTags( filters?: FilterableProductTagProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductTagDTO[], number]> + /** + * This method is used to create product tags. + * + * @param {CreateProductTagDTO[]} data - The product tags to create. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product tags. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function createProductTags (values: string[]) { + * const productModule = await initializeProductModule() + * + * const productTags = await productModule.createTags( + * values.map((value) => ({ + * value + * })) + * ) + * + * // do something with the product tags or return them + * } + */ createTags( data: CreateProductTagDTO[], sharedContext?: Context ): Promise + /** + * This method is used to update existing product tags. + * + * @param {UpdateProductTagDTO[]} data - The product tags to be updated, each having the attributes that should be updated in a product tag. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of updated product tags. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function updateProductTag (id: string, value: string) { + * const productModule = await initializeProductModule() + * + * const productTags = await productModule.updateTags([ + * { + * id, + * value + * } + * ]) + * + * // do something with the product tags or return them + * } + */ updateTags( data: UpdateProductTagDTO[], sharedContext?: Context ): Promise + /** + * This method is used to delete product tags by their ID. + * + * @param {string[]} productTagIds - The IDs of the product tags to be deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the product tags are successfully deleted. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteProductTags (ids: string[]) { + * const productModule = await initializeProductModule() + * + * await productModule.deleteTags(ids) + * + * } + */ deleteTags(productTagIds: string[], sharedContext?: Context): Promise + /** + * This method is used to retrieve a product type by its ID. + * + * @param {string} typeId - The ID of the product type to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product type is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product type. + * + * @example + * A simple example that retrieves a product type by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductType (id: string) { + * const productModule = await initializeProductModule() + * + * const productType = await productModule.retrieveType(id) + * + * // do something with the product type or return it + * } + * ``` + * + * To specify attributes that should be retrieved: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductType (id: string) { + * const productModule = await initializeProductModule() + * + * const productType = await productModule.retrieveType(id, { + * select: ["value"] + * }) + * + * // do something with the product type or return it + * } + * ``` + */ retrieveType( typeId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product types based on optional filters and configuration. + * + * @param {FilterableProductTypeProps} filters - The filters to apply on the retrieved product types. + * @param {FindConfig} config - + * The configurations determining how the product types are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product types. + * + * @example + * To retrieve a list of product types using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const productTypes = await productModule.listTypes({ + * id: ids + * }) + * + * // do something with the product types or return them + * } + * ``` + * + * To specify attributes that should be retrieved within the product types: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const productTypes = await productModule.listTypes({ + * id: ids + * }, { + * select: ["value"] + * }) + * + * // do something with the product 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const productTypes = await productModule.listTypes({ + * id: ids + * }, { + * select: ["value"], + * skip, + * take + * }) + * + * // do something with the product 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[], value: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const productTypes = await productModule.listTypes({ + * $and: [ + * { + * id: ids + * }, + * { + * value + * } + * ] + * }, { + * select: ["value"], + * skip, + * take + * }) + * + * // do something with the product types or return them + * } + * ``` + */ listTypes( filters?: FilterableProductTypeProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product types along with the total count of available product types satisfying the provided filters. + * + * @param {FilterableProductTypeProps} filters - The filters to be applied on the retrieved product type. + * @param {FindConfig} config - + * The configurations determining how the product types are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ProductTypeDTO[], number]>} The list of product types along with their total count. + * + * @example + * To retrieve a list of product types using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [productTypes, count] = await productModule.listAndCountTypes({ + * id: ids + * }) + * + * // do something with the product types or return them + * } + * ``` + * + * To specify attributes that should be retrieved within the product types: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [productTypes, count] = await productModule.listAndCountTypes({ + * id: ids + * }, { + * select: ["value"] + * }) + * + * // do something with the product 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [productTypes, count] = await productModule.listAndCountTypes({ + * id: ids + * }, { + * select: ["value"], + * skip, + * take + * }) + * + * // do something with the product 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductTypes (ids: string[], value: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [productTypes, count] = await productModule.listAndCountTypes({ + * $and: [ + * { + * id: ids + * }, + * { + * value + * } + * ] + * }, { + * select: ["value"], + * skip, + * take + * }) + * + * // do something with the product types or return them + * } + * ``` + */ listAndCountTypes( filters?: FilterableProductTypeProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductTypeDTO[], number]> + /** + * This method is used to create a product type. + * + * @param {CreateProductTypeDTO[]} data - The product types to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @return {Promise} The list of created product types. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function createProductType (value: string) { + * const productModule = await initializeProductModule() + * + * const productTypes = await productModule.createTypes([ + * { + * value + * } + * ]) + * + * // do something with the product types or return them + * } + */ createTypes( data: CreateProductTypeDTO[], sharedContext?: Context ): Promise + /** + * This method is used to update a product type + * + * @param {UpdateProductTypeDTO[]} data - The product types to be updated, each having the attributes that should be updated in the product type. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of updated product types. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function updateProductType (id: string, value: string) { + * const productModule = await initializeProductModule() + * + * const productTypes = await productModule.updateTypes([ + * { + * id, + * value + * } + * ]) + * + * // do something with the product types or return them + * } + */ updateTypes( data: UpdateProductTypeDTO[], sharedContext?: Context ): Promise + /** + * This method is used to delete a product type. + * + * @param {string[]} productTypeIds - The IDs of the product types to be deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the product types are successfully deleted. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteProductTypes (ids: string[]) { + * const productModule = await initializeProductModule() + * + * await productModule.deleteTypes(ids) + * } + */ deleteTypes(productTypeIds: string[], sharedContext?: Context): Promise + /** + * This method is used to retrieve a product option by its ID. + * + * @param {string} optionId - The ID of the product option to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product option is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product option. + * + * @example + * A simple example that retrieves a product option by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOption (id: string) { + * const productModule = await initializeProductModule() + * + * const productOption = await productModule.retrieveOption(id) + * + * // do something with the product option or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOption (id: string) { + * const productModule = await initializeProductModule() + * + * const productOption = await productModule.retrieveOption(id, { + * relations: ["product"] + * }) + * + * // do something with the product option or return it + * } + * ``` + */ retrieveOption( optionId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product options based on optional filters and configuration. + * + * @param {FilterableProductOptionProps} filters - The filters applied on the retrieved product options. + * @param {FindConfig} config - + * The configurations determining how the product options are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product options. + * + * @example + * To retrieve a list of product options using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const productOptions = await productModule.listOptions({ + * id: ids + * }) + * + * // do something with the product options or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product types: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const productOptions = await productModule.listOptions({ + * id: ids + * }, { + * relations: ["product"] + * }) + * + * // do something with the product options 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const productOptions = await productModule.listOptions({ + * id: ids + * }, { + * relations: ["product"], + * skip, + * take + * }) + * + * // do something with the product options 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[], title: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const productOptions = await productModule.listOptions({ + * $and: [ + * { + * id: ids + * }, + * { + * title + * } + * ] + * }, { + * relations: ["product"], + * skip, + * take + * }) + * + * // do something with the product options or return them + * } + * ``` + */ listOptions( filters?: FilterableProductOptionProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product options along with the total count of available product options satisfying the provided filters. + * + * @param {FilterableProductOptionProps} filters - The filters applied on the retrieved product options. + * @param {FindConfig} config - + * The configurations determining how the product options are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ProductOptionDTO[], number]>} The list of product options along with the total count. + * + * @example + * To retrieve a list of product options using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [productOptions, count] = await productModule.listAndCountOptions({ + * id: ids + * }) + * + * // do something with the product options or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product types: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [productOptions, count] = await productModule.listAndCountOptions({ + * id: ids + * }, { + * relations: ["product"] + * }) + * + * // do something with the product options 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [productOptions, count] = await productModule.listAndCountOptions({ + * id: ids + * }, { + * relations: ["product"], + * skip, + * take + * }) + * + * // do something with the product options 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductOptions (ids: string[], title: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [productOptions, count] = await productModule.listAndCountOptions({ + * $and: [ + * { + * id: ids + * }, + * { + * title + * } + * ] + * }, { + * relations: ["product"], + * skip, + * take + * }) + * + * // do something with the product options or return them + * } + * ``` + */ listAndCountOptions( filters?: FilterableProductOptionProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductOptionDTO[], number]> + /** + * This method is used to create product options. + * + * @param {CreateProductOptionDTO[]} data - The product options to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {ProductOptionDTO[]} The list of created product options. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function createProductOption (title: string, productId: string) { + * const productModule = await initializeProductModule() + * + * const productOptions = await productModule.createOptions([ + * { + * title, + * product_id: productId + * } + * ]) + * + * // do something with the product options or return them + * } + */ createOptions( data: CreateProductOptionDTO[], sharedContext?: Context ): Promise + /** + * This method is used to update existing product options. + * + * @param {UpdateProductOptionDTO[]} data - The product options to be updated, each holding the attributes that should be updated in the product option. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {ProductOptionDTO[]} The list of updated product options. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function updateProductOption (id: string, title: string) { + * const productModule = await initializeProductModule() + * + * const productOptions = await productModule.updateOptions([ + * { + * id, + * title + * } + * ]) + * + * // do something with the product options or return them + * } + */ updateOptions( data: UpdateProductOptionDTO[], sharedContext?: Context ): Promise + /** + * This method is used to delete a product option. + * + * @param {string[]} productOptionIds - The IDs of the product options to delete. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the product options are successfully deleted. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteProductOptions (ids: string[]) { + * const productModule = await initializeProductModule() + * + * await productModule.deleteOptions(ids) + * } + */ deleteOptions( productOptionIds: string[], sharedContext?: Context ): Promise + /** + * This method is used to retrieve a product variant by its ID. + * + * @param {string} productVariantId - The ID of the product variant to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product variant is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product variant. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product variant. + * + * @example + * A simple example that retrieves a product variant by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariant (id: string) { + * const productModule = await initializeProductModule() + * + * const variant = await productModule.retrieveVariant(id) + * + * // do something with the product variant or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariant (id: string) { + * const productModule = await initializeProductModule() + * + * const variant = await productModule.retrieveVariant(id, { + * relations: ["options"] + * }) + * + * // do something with the product variant or return it + * } + * ``` + */ retrieveVariant( productVariantId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product variants based on optional filters and configuration. + * + * @param {FilterableProductVariantProps} filters - The filters applied on the retrieved product variants. + * @param {FindConfig} config - + * The configurations determining how the product variants are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product variant. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product variants. + * + * @example + * To retrieve a list of product variants using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const variants = await productModule.listVariants({ + * id: ids + * }) + * + * // do something with the product variants or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product variants: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const variants = await productModule.listVariants({ + * id: ids + * }, { + * relations: ["options"] + * }) + * + * // do something with the product variants 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const variants = await productModule.listVariants({ + * id: ids + * }, { + * relations: ["options"], + * skip, + * take + * }) + * + * // do something with the product variants 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[], sku: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const variants = await productModule.listVariants({ + * $and: [ + * { + * id: ids + * }, + * { + * sku + * } + * ] + * }, { + * relations: ["options"], + * skip, + * take + * }) + * + * // do something with the product variants or return them + * } + * ``` + */ listVariants( filters?: FilterableProductVariantProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product variants along with the total count of available product variants satisfying the provided filters. + * + * @param {FilterableProductVariantProps} filters - The filters applied on the retrieved product variants. + * @param {FindConfig} config - + * The configurations determining how the product variants are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product variant. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ProductVariantDTO[], number]>} The list of product variants along with their total count. + * + * @example + * To retrieve a list of product variants using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [variants, count] = await productModule.listAndCountVariants({ + * id: ids + * }) + * + * // do something with the product variants or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product variants: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [variants, count] = await productModule.listAndCountVariants({ + * id: ids + * }, { + * relations: ["options"] + * }) + * + * // do something with the product variants 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [variants, count] = await productModule.listAndCountVariants({ + * id: ids + * }, { + * relations: ["options"], + * skip, + * take + * }) + * + * // do something with the product variants 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveProductVariants (ids: string[], sku: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [variants, count] = await productModule.listAndCountVariants({ + * $and: [ + * { + * id: ids + * }, + * { + * sku + * } + * ] + * }, { + * relations: ["options"], + * skip, + * take + * }) + * + * // do something with the product variants or return them + * } + * ``` + */ listAndCountVariants( filters?: FilterableProductVariantProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductVariantDTO[], number]> + /** + * This method is used to retrieve a product collection by its ID. + * + * @param {string} productCollectionId - The ID of the product collection to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product collection is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product collection. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product collection. + * + * @example + * A simple example that retrieves a product collection by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollection (id: string) { + * const productModule = await initializeProductModule() + * + * const collection = await productModule.retrieveCollection(id) + * + * // do something with the product collection or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollection (id: string) { + * const productModule = await initializeProductModule() + * + * const collection = await productModule.retrieveCollection(id, { + * relations: ["products"] + * }) + * + * // do something with the product collection or return it + * } + * ``` + */ retrieveCollection( productCollectionId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product collections based on optional filters and configuration. + * + * @param {FilterableProductCollectionProps} filters - The filters applied on the retrieved product collections. + * @param {FindConfig} config - + * The configurations determining how the product collections are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product collection. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product collections. + * + * @example + * To retrieve a list of product collections using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const collections = await productModule.listCollections({ + * id: ids + * }) + * + * // do something with the product collections or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product collections: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const collections = await productModule.listCollections({ + * id: ids + * }, { + * relations: ["products"] + * }) + * + * // do something with the product collections 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const collections = await productModule.listCollections({ + * id: ids + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product collections 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[], title: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const collections = await productModule.listCollections({ + * $and: [ + * { + * id: ids + * }, + * { + * title + * } + * ] + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product collections or return them + * } + * ``` + */ listCollections( filters?: FilterableProductCollectionProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product collections along with the total count of available product collections satisfying the provided filters. + * + * @param {FilterableProductCollectionProps} filters - The filters applied on the retrieved product collections. + * @param {FindConfig} config - + * The configurations determining how the product collections are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product collection. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ProductCollectionDTO[], number]>} The list of product collections along with the total count. + * + * @example + * To retrieve a list of product collections using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [collections, count] = await productModule.listAndCountCollections({ + * id: ids + * }) + * + * // do something with the product collections or return them + * } + * ``` + * + * To specify relations that should be retrieved within the product collections: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [collections, count] = await productModule.listAndCountCollections({ + * id: ids + * }, { + * relations: ["products"] + * }) + * + * // do something with the product collections 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [collections, count] = await productModule.listAndCountCollections({ + * id: ids + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product collections 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCollections (ids: string[], title: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [collections, count] = await productModule.listAndCountCollections({ + * $and: [ + * { + * id: ids + * }, + * { + * title + * } + * ] + * }, { + * relations: ["products"], + * skip, + * take + * }) + * + * // do something with the product collections or return them + * } + * ``` + */ listAndCountCollections( filters?: FilterableProductCollectionProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductCollectionDTO[], number]> + /** + * This method is used to create product collections. + * + * @param {CreateProductCollectionDTO[]} data - The product collections to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of created product collections. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function createCollection (title: string) { + * const productModule = await initializeProductModule() + * + * const collections = await productModule.createCollections([ + * { + * title + * } + * ]) + * + * // do something with the product collections or return them + * } + * + */ createCollections( data: CreateProductCollectionDTO[], sharedContext?: Context ): Promise + /** + * This method is used to update existing product collections. + * + * @param {UpdateProductCollectionDTO[]} data - The product collections to be updated, each holding the attributes that should be updated in the product collection. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of updated product collections. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function updateCollection (id: string, title: string) { + * const productModule = await initializeProductModule() + * + * const collections = await productModule.updateCollections([ + * { + * id, + * title + * } + * ]) + * + * // do something with the product collections or return them + * } + * + */ updateCollections( data: UpdateProductCollectionDTO[], sharedContext?: Context ): Promise + /** + * This method is used to delete collections by their ID. + * + * @param {string[]} productCollectionIds - The IDs of the product collections to be updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the product options are successfully deleted. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteCollection (ids: string[]) { + * const productModule = await initializeProductModule() + * + * await productModule.deleteCollections(ids) + * } + * + */ deleteCollections( productCollectionIds: string[], sharedContext?: Context ): Promise + /** + * This method is used to retrieve a product category by its ID. + * + * @param {string} productCategoryId - The ID of the product category to retrieve. + * @param {FindConfig} config - + * The configurations determining how the product category is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product category. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The retrieved product category. + * + * @example + * A simple example that retrieves a product category by its ID: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategory (id: string) { + * const productModule = await initializeProductModule() + * + * const category = await productModule.retrieveCategory(id) + * + * // do something with the product category or return it + * } + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategory (id: string) { + * const productModule = await initializeProductModule() + * + * const category = await productModule.retrieveCategory(id, { + * relations: ["parent_category"] + * }) + * + * // do something with the product category or return it + * } + * ``` + */ retrieveCategory( productCategoryId: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product categories based on optional filters and configuration. + * + * @param {FilterableProductCategoryProps} filters - The filters to be applied on the retrieved product categories. + * @param {FindConfig} config - + * The configurations determining how the product categories are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product category. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of product categories. + * + * @example + * To retrieve a list of product categories using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const categories = await productModule.listCategories({ + * id: ids + * }) + * + * // do something with the product category or return it + * } + * ``` + * + * To specify relations that should be retrieved within the product categories: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const categories = await productModule.listCategories({ + * id: ids + * }, { + * relations: ["parent_category"] + * }) + * + * // do something with the product category or return it + * } + * ``` + * + * 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const categories = await productModule.listCategories({ + * id: ids + * }, { + * relations: ["parent_category"], + * skip, + * take + * }) + * + * // do something with the product category or return it + * } + * ``` + * + * 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[], name: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const categories = await productModule.listCategories({ + * $or: [ + * { + * id: ids + * }, + * { + * name + * } + * ] + * }, { + * relations: ["parent_category"], + * skip, + * take + * }) + * + * // do something with the product category or return it + * } + * ``` + */ listCategories( filters?: FilterableProductCategoryProps, config?: FindConfig, sharedContext?: Context ): Promise + /** + * This method is used to retrieve a paginated list of product categories along with the total count of available product categories satisfying the provided filters. + * + * @param {FilterableProductCategoryProps} filters - The filters to apply on the retrieved product categories. + * @param {FindConfig} config - + * The configurations determining how the product categories are retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a product category. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise<[ProductCategoryDTO[], number]>} The list of product categories along with their total count. + * + * @example + * To retrieve a list of product categories using their IDs: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [categories, count] = await productModule.listAndCountCategories({ + * id: ids + * }) + * + * // do something with the product category or return it + * } + * ``` + * + * To specify relations that should be retrieved within the product categories: + * + * ```ts + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const [categories, count] = await productModule.listAndCountCategories({ + * id: ids + * }, { + * relations: ["parent_category"] + * }) + * + * // do something with the product category or return it + * } + * ``` + * + * 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[], skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [categories, count] = await productModule.listAndCountCategories({ + * id: ids + * }, { + * relations: ["parent_category"], + * skip, + * take + * }) + * + * // do something with the product category or return it + * } + * ``` + * + * 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 initializeProductModule, + * } from "@medusajs/product" + * + * async function retrieveCategories (ids: string[], name: string, skip: number, take: number) { + * const productModule = await initializeProductModule() + * + * const [categories, count] = await productModule.listAndCountCategories({ + * $or: [ + * { + * id: ids + * }, + * { + * name + * } + * ] + * }, { + * relations: ["parent_category"], + * skip, + * take + * }) + * + * // do something with the product category or return it + * } + * ``` + */ listAndCountCategories( filters?: FilterableProductCategoryProps, config?: FindConfig, sharedContext?: Context ): Promise<[ProductCategoryDTO[], number]> + /** + * This method is used to create a product category. + * + * @param {CreateProductCategoryDTO} data - The product category to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created product category. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function createCategory (name: string, parent_category_id: string | null) { + * const productModule = await initializeProductModule() + * + * const category = await productModule.createCategory({ + * name, + * parent_category_id + * }) + * + * // do something with the product category or return it + * } + * + */ createCategory( data: CreateProductCategoryDTO, sharedContext?: Context ): Promise + /** + * This method is used to update a product category by its ID. + * + * @param {string} categoryId - The ID of the product category to update. + * @param {UpdateProductCategoryDTO} data - The attributes to update in th product category. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated product category. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function updateCategory (id: string, name: string) { + * const productModule = await initializeProductModule() + * + * const category = await productModule.updateCategory(id, { + * name, + * }) + * + * // do something with the product category or return it + * } + */ updateCategory( categoryId: string, data: UpdateProductCategoryDTO, sharedContext?: Context ): Promise + /** + * This method is used to delete a product category by its ID. + * + * @param {string} categoryId - The ID of the product category to delete. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the product category is successfully deleted. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteCategory (id: string) { + * const productModule = await initializeProductModule() + * + * await productModule.deleteCategory(id) + * } + */ deleteCategory(categoryId: string, sharedContext?: Context): Promise + /** + * This method is used to create a product. + * + * @param {CreateProductDTO[]} data - The products to be created. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of created products. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function createProduct (title: string) { + * const productModule = await initializeProductModule() + * + * const products = await productModule.create([ + * { + * title + * } + * ]) + * + * // do something with the products or return them + * } + */ create( data: CreateProductDTO[], sharedContext?: Context ): Promise + /** + * This method is used to update a product. + * + * @param {UpdateProductDTO[]} data - The products to be updated, each holding the attributes that should be updated in the product. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The list of updated products. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function updateProduct (id: string, title: string) { + * const productModule = await initializeProductModule() + * + * const products = await productModule.update([ + * { + * id, + * title + * } + * ]) + * + * // do something with the products or return them + * } + */ update( data: UpdateProductDTO[], sharedContext?: Context ): Promise + /** + * This method is used to delete products. Unlike the {@link softDelete} method, this method will completely remove the products and they can no longer be accessed or retrieved. + * + * @param {string[]} productIds - The IDs of the products to be deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} Resolves when the products are successfully deleted. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * await productModule.delete(ids) + * } + */ delete(productIds: string[], sharedContext?: Context): Promise + /** + * This method is used to delete products. Unlike the {@link delete} method, this method won't completely remove the product. It can still be accessed or retrieved using methods like {@link retrieve} if you pass the `withDeleted` property to the `config` object parameter. + * + * The soft-deleted products can be restored using the {@link restore} method. + * + * @param {string[]} productIds - The IDs of the products to soft-delete. + * @param {SoftDeleteReturn} config - + * Configurations determining which relations to soft delete along with the each of the products. You can pass to its `returnLinkableKeys` + * property any of the product's relation attribute names, such as `variant_id`. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise | void>} + * An object that includes the IDs of related records that were also soft deleted, such as the ID of associated product variants. The object's keys are the ID attribute names of the product entity's relations, such as `variant_id`, and its value is an array of strings, each being the ID of a record associated with the product through this relation, such as the IDs of associated product variants. + * + * If there are no related records, the promise resolved to `void`. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function deleteProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const cascadedEntities = await productModule.softDelete(ids) + * + * // do something with the returned cascaded entity IDs or return them + * } + */ softDelete( productIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** + * This method is used to restore products which were deleted using the {@link softDelete} method. + * + * @param {string[]} productIds - The IDs of the products to restore. + * @param {RestoreReturn} config - + * Configurations determining which relations to restore along with the each of the products. You can pass to its `returnLinkableKeys` + * property any of the product's relation attribute names, such as `variant_id`. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise | void>} + * An object that includes the IDs of related records that were restored, such as the ID of associated product variants. The object's keys are the ID attribute names of the product entity's relations, such as `variant_id`, and its value is an array of strings, each being the ID of the record associated with the product through this relation, such as the IDs of associated product variants. + * + * If there are no related records that were restored, the promise resolved to `void`. + * + * @example + * import { + * initialize as initializeProductModule, + * } from "@medusajs/product" + * + * async function restoreProducts (ids: string[]) { + * const productModule = await initializeProductModule() + * + * const cascadedEntities = await productModule.restore(ids, { + * returnLinkableKeys: ["variant_id"] + * }) + * + * // do something with the returned cascaded entity IDs or return them + * } + */ restore( productIds: string[], config?: RestoreReturn,