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

chore: added TSDocs to product module service interface (#5341)

Browse Source 
* added tsdocs for product module service

* general fixes

* added generate github action

* fix typedoc configurations

* update comments

* change configurations

* address PR feedback
This commit is contained in:
Shahed Nasser
2023-10-18 19:41:53 +03:00
committed by GitHub
parent ffb0bbe4a7
commit 8d0a45ec14
7 changed files with 2761 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/types/src/dal/repository-service.ts
+14
View File
@@ -79,10 +79,24 @@ export interface TreeRepositoryService<T = any>
delete(id: string, context?: Context): Promise<void>
}
/**
* @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<TReturnableLinkableKeys = string> = {
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<TReturnableLinkableKeys = string> = {
returnLinkableKeys?: TReturnableLinkableKeys[]
}
packages/types/src/product/common.ts
+432 -6
View File
@@ -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<ProductDTO>, 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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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<FilterableProductProps> {
@@ -173,18 +355,43 @@ export interface FilterableProductProps
collection_id?: string | string[] | OperatorMap<string>
}
/**
* @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<FilterableProductTagProps> {
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<FilterableProductTypeProps> {
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<FilterableProductOptionProps> {
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<FilterableProductCollectionProps> {
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<FilterableProductVariantProps> {
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<FilterableProductCategoryProps> {
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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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<string, unknown>
}
/**
* @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
packages/types/src/product/service.ts
+2182
View File
File diff suppressed because it is too large Load Diff