diff --git a/packages/types/src/store/common/store.ts b/packages/types/src/store/common/store.ts index d255dd6c42..56594f9828 100644 --- a/packages/types/src/store/common/store.ts +++ b/packages/types/src/store/common/store.ts @@ -1,19 +1,72 @@ import { BaseFilterable } from "../../dal" +/** + * The store details. + */ export interface StoreDTO { + /** + * The ID of the store. + */ id: string + + /** + * The name of the store. + */ name: string + + /** + * The supported currency codes of the store. + */ supported_currency_codes: string[] + + /** + * The default currency code of the store. + */ default_currency_code?: string + + /** + * The associated default sales channel's ID. + */ default_sales_channel_id?: string + + /** + * The associated default region's ID. + */ default_region_id?: string + + /** + * The associated default location's ID. + */ default_location_id?: string + + /** + * Holds custom data in key-value pairs. + */ metadata: Record | null + + /** + * The created at of the store. + */ created_at: string + + /** + * The updated at of the store. + */ updated_at: string } + +/** + * The filters to apply on the retrieved stores. + */ export interface FilterableStoreProps extends BaseFilterable { + /** + * The IDs to filter the stores by. + */ id?: string | string[] + + /** + * Filter stores by their names. + */ name?: string | string[] } diff --git a/packages/types/src/store/mutations/store.ts b/packages/types/src/store/mutations/store.ts index e7ea565819..364cdaf777 100644 --- a/packages/types/src/store/mutations/store.ts +++ b/packages/types/src/store/mutations/store.ts @@ -1,30 +1,124 @@ +/** + * The store to be created. + */ export interface CreateStoreDTO { + /** + * The name of the store. + */ name?: string + + /** + * The supported currency codes of the store. + */ supported_currency_codes?: string[] + + /** + * The default currency code of the store. + */ default_currency_code?: string + + /** + * The associated default sales channel's ID. + */ default_sales_channel_id?: string + + /** + * The associated default region's ID. + */ default_region_id?: string + + /** + * The associated default location's ID. + */ default_location_id?: string + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record } +/** + * The attributes in the store to be created or updated. + */ export interface UpsertStoreDTO { + /** + * The ID of the store. + */ id?: string + + /** + * The name of the store. + */ name?: string + + /** + * The supported currency codes of the store. + */ supported_currency_codes?: string[] + + /** + * The default currency code of the store. + */ default_currency_code?: string + + /** + * The associated default sales channel's ID. + */ default_sales_channel_id?: string + + /** + * The associated default region's ID. + */ default_region_id?: string + + /** + * The associated default location's ID. + */ default_location_id?: string + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record } +/** + * The attributes to update in the store. + */ export interface UpdateStoreDTO { + /** + * The name of the store. + */ name?: string + + /** + * The supported currency codes of the store. + */ supported_currency_codes?: string[] + + /** + * The default currency code of the store. + */ default_currency_code?: string + + /** + * The associated default sales channel's ID. + */ default_sales_channel_id?: string + + /** + * The associated default region's ID. + */ default_region_id?: string + + /** + * The associated default location's ID. + */ default_location_id?: string + + /** + * Holds custom data in key-value pairs. + */ metadata?: Record } diff --git a/packages/types/src/store/service.ts b/packages/types/src/store/service.ts index c7212c9d0d..bb2e8b50d8 100644 --- a/packages/types/src/store/service.ts +++ b/packages/types/src/store/service.ts @@ -6,7 +6,7 @@ import { FilterableStoreProps, StoreDTO } from "./common" import { CreateStoreDTO, UpdateStoreDTO, UpsertStoreDTO } from "./mutations" /** - * The main service interface for the store module. + * The main service interface for the Store Module. */ export interface IStoreModuleService extends IModuleService { /** @@ -17,7 +17,18 @@ export interface IStoreModuleService extends IModuleService { * @returns {Promise} The created stores. * * @example - * {example-code} + * const stores = await storeModuleService.create([ + * { + * name: "Acme", + * supported_currency_codes: ["usd", "eur"], + * default_currency_code: "usd", + * }, + * { + * name: "Acme 2", + * supported_currency_codes: ["usd"], + * default_currency_code: "usd", + * }, + * ]) */ create(data: CreateStoreDTO[], sharedContext?: Context): Promise @@ -29,39 +40,63 @@ export interface IStoreModuleService extends IModuleService { * @returns {Promise} The created store. * * @example - * {example-code} + * const store = await storeModuleService.create({ + * name: "Acme", + * supported_currency_codes: ["usd", "eur"], + * default_currency_code: "usd", + * }) */ create(data: CreateStoreDTO, sharedContext?: Context): Promise /** - * This method updates existing stores, or creates new ones if they don't exist. + * This method updates or creates stores if they don't exist. * - * @param {UpsertStoreDTO[]} data - The attributes to update or create in each store. - * @returns {Promise} The updated and created stores. + * @param {UpsertStoreDTO[]} data - The attributes in the stores to be created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created or updated stores. * * @example - * {example-code} + * const stores = await storeModuleService.upsert([ + * { + * id: "store_123", + * name: "Acme", + * }, + * { + * name: "Acme 2", + * supported_currency_codes: ["usd"], + * default_currency_code: "usd", + * }, + * ]) */ upsert(data: UpsertStoreDTO[], sharedContext?: Context): Promise /** - * This method updates an existing store, or creates a new one if it doesn't exist. + * This method updates or creates a store if it doesn't exist. * - * @param {UpsertStoreDTO} data - The attributes to update or create for the store. - * @returns {Promise} The updated or created store. + * @param {UpsertStoreDTO} data - The attributes in the store to be created or updated. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The created or updated store. * * @example - * {example-code} + * const store = await storeModuleService.upsert({ + * id: "store_123", + * name: "Acme", + * }) */ upsert(data: UpsertStoreDTO, sharedContext?: Context): Promise /** * This method updates an existing store. * - * @param {string} id - The store's ID. - * @param {UpdateStoreDTO} data - The details to update in the store. + * @param {string} id - The ID of the store. + * @param {UpdateStoreDTO} data - The attributes to update in the store. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated store. + * + * @example + * const store = await storeModuleService.update("store_123", { + * name: "Acme", + * }) */ update( id: string, @@ -70,15 +105,22 @@ export interface IStoreModuleService extends IModuleService { ): Promise /** - * This method updates existing stores. + * This method updates existing stores matching the specified filters. * - * @param {FilterableStoreProps} selector - The filters to specify which stores should be updated. - * @param {UpdateStoreDTO} data - The details to update in the stores. + * @param {FilterableStoreProps} selector - The filters specifying which stores to update. + * @param {UpdateStoreDTO} data - The attributes to update in the store. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated stores. * * @example - * {example-code} + * const store = await storeModuleService.update( + * { + * name: ["Acme"], + * }, + * { + * default_currency_code: "usd", + * } + * ) */ update( selector: FilterableStoreProps, @@ -89,12 +131,12 @@ export interface IStoreModuleService extends IModuleService { /** * This method deletes stores by their IDs. * - * @param {string[]} ids - The list of IDs of stores to delete. + * @param {string[]} ids - The IDs of the stores. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the stores are deleted. + * @returns {Promise} Resolves when the stores are deleted successfully. * * @example - * {example-code} + * await storeModuleService.delete(["store_123", "store_321"]) */ delete(ids: string[], sharedContext?: Context): Promise @@ -103,36 +145,24 @@ export interface IStoreModuleService extends IModuleService { * * @param {string} id - The ID of the store. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the store is deleted. + * @returns {Promise} Resolves when the store is deleted successfully. * * @example - * {example-code} + * await storeModuleService.delete("store_123") */ delete(id: string, sharedContext?: Context): Promise /** * This method retrieves a store by its ID. * - * @param {string} id - The ID of the retrieve. + * @param {string} id - The ID of the store. * @param {FindConfig} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a store. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The retrieved store. * * @example - * A simple example that retrieves a {type name} by its ID: - * - * ```ts - * {example-code} - * ``` - * - * To specify relations that should be retrieved: - * - * ```ts - * {example-code} - * ``` - * - * + * const store = await storeModuleService.retrieve("store_123") */ retrieve( id: string, @@ -143,32 +173,34 @@ export interface IStoreModuleService extends IModuleService { /** * This method retrieves a paginated list of stores based on optional filters and configuration. * - * @param {FilterableStoreProps} filters - The filters to apply on the retrieved store. + * @param {FilterableStoreProps} filters - The filters to apply on the retrieved stores. * @param {FindConfig} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a store. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The list of stores. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of stores using their IDs: * * ```ts - * {example-code} + * const stores = await storeModuleService.list({ + * id: ["store_123", "store_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * 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 - * {example-code} + * const stores = await storeModuleService.list( + * { + * id: ["store_123", "store_321"], + * }, + * { + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: - * - * ```ts - * {example-code} - * ``` - * - * */ list( filters?: FilterableStoreProps, @@ -179,32 +211,36 @@ export interface IStoreModuleService extends IModuleService { /** * This method retrieves a paginated list of stores along with the total count of available stores satisfying the provided filters. * - * @param {FilterableStoreProps} filters - The filters to apply on the retrieved store. + * @param {FilterableStoreProps} filters - The filters to apply on the retrieved stores. * @param {FindConfig} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a store. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise<[StoreDTO[], number]>} The list of stores along with their total count. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of stores using their IDs: * * ```ts - * {example-code} + * const [stores, count] = await storeModuleService.listAndCount( + * { + * id: ["store_123", "store_321"], + * } + * ) * ``` * - * To specify relations that should be retrieved within the {type name}: + * 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 - * {example-code} + * const [stores, count] = await storeModuleService.listAndCount( + * { + * id: ["store_123", "store_321"], + * }, + * { + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: - * - * ```ts - * {example-code} - * ``` - * - * */ listAndCount( filters?: FilterableStoreProps, @@ -213,15 +249,19 @@ export interface IStoreModuleService extends IModuleService { ): Promise<[StoreDTO[], number]> /** - * This method soft deletes stores by their IDs. + * This method soft deletes a store by its IDs. * - * @param {string[]} storeIds - The list of IDs of stores to soft delete. + * @param {string[]} storeIds - The IDs of the stores. * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise>} Resolves successfully when the stores are soft-deleted. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. * * @example - * {example-code} + * await storeModuleService.softDelete([ + * "store_123", + * "store_321", + * ]) */ softDelete( storeIds: string[], @@ -230,19 +270,17 @@ export interface IStoreModuleService extends IModuleService { ): Promise | void> /** - * This method restores soft deleted stores by their IDs. + * This method restores a soft deleted store by its IDs. * - * @param {string[]} storeIds - The list of IDs of stores to restore. - * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the stores. You can pass to its `returnLinkableKeys` - * property any of the stores's relation attribute names, such as `currency`. + * @param {string[]} storeIds - The IDs of the stores. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the store. You can pass to its `returnLinkableKeys` + * property any of the store's relation attribute names. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise>} An object that includes the IDs of related records that were restored, such as the ID of associated currency. - * The object's keys are the ID attribute names of the stores entity's relations, such as `currency_code`, - * and its value is an array of strings, each being the ID of the record associated with the store through this relation, - * such as the IDs of associated currency. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. * * @example - * {example-code} + * await storeModuleService.restore(["store_123", "store_321"]) */ restore( storeIds: string[],