From 5e53b917f703d22286b235f13ee9cad166c16c40 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 27 Mar 2024 20:24:00 +0200 Subject: [PATCH] chore: add tsdocs for the Sales Channel Module (#6794) Add/update TSDocs to the Sales Channel Module's resources --- packages/types/src/sales-channel/mutations.ts | 6 +- packages/types/src/sales-channel/service.ts | 197 ++++++++++++------ 2 files changed, 139 insertions(+), 64 deletions(-) diff --git a/packages/types/src/sales-channel/mutations.ts b/packages/types/src/sales-channel/mutations.ts index 917e9f86a0..8f97641b34 100644 --- a/packages/types/src/sales-channel/mutations.ts +++ b/packages/types/src/sales-channel/mutations.ts @@ -42,6 +42,9 @@ export interface UpdateSalesChannelDTO { metadata?: Record } +/** + * The attributes in the sales channel to be created or updated. + */ export interface UpsertSalesChannelDTO { /** * The ID of the sales channel. @@ -49,7 +52,8 @@ export interface UpsertSalesChannelDTO { id?: string /** - * The name of the sales channel. + * The name of the sales channel. Required + * when creating a sales channel. */ name?: string diff --git a/packages/types/src/sales-channel/service.ts b/packages/types/src/sales-channel/service.ts index 2d1889cee8..509f048f9c 100644 --- a/packages/types/src/sales-channel/service.ts +++ b/packages/types/src/sales-channel/service.ts @@ -3,21 +3,29 @@ import { RestoreReturn, SoftDeleteReturn } from "../dal" import { IModuleService } from "../modules-sdk" import { Context } from "../shared-context" import { FilterableSalesChannelProps, SalesChannelDTO } from "./common" -import { CreateSalesChannelDTO, UpdateSalesChannelDTO, UpsertSalesChannelDTO } from "./mutations" +import { + CreateSalesChannelDTO, + UpdateSalesChannelDTO, + UpsertSalesChannelDTO, +} from "./mutations" /** - * The main service interface for the sales channel module. + * The main service interface for the Sales Channel Module. */ export interface ISalesChannelModuleService extends IModuleService { /** * This method creates sales channels. * - * @param {CreateSalesChannelDTO[]} data - The sales channel to be created. + * @param {CreateSalesChannelDTO[]} data - The sales channels 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 sales channels. * * @example - * {example-code} + * const salesChannels = await salesChannelModuleService.create([ + * { + * name: "B2B", + * }, + * ]) */ create( data: CreateSalesChannelDTO[], @@ -29,45 +37,113 @@ export interface ISalesChannelModuleService extends IModuleService { * * @param {CreateSalesChannelDTO} data - The sales channel 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 a sales channel. + * @returns {Promise} The created sales channel. * * @example - * {example-code} + * const salesChannel = await salesChannelModuleService.create({ + * name: "B2B", + * }) */ create( data: CreateSalesChannelDTO, sharedContext?: Context ): Promise + /** + * This method updates an existing sales channel. + * + * @param {string} channelId - The sales channel's ID. + * @param {UpdateSalesChannelDTO} data - The attributes to update in the sales channel. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated sales channel. + * + * @example + * const salesChannel = await salesChannelModuleService.update( + * "sc_123", + * { + * description: "Sales channel for B2B customers", + * } + * ) + */ update( channelId: string, data: UpdateSalesChannelDTO, sharedContext?: Context ): Promise + + /** + * This method updates existing sales channels matching the specified filters + * + * @param {FilterableSalesChannelProps} selector - The filters specifying which sales channels to update. + * @param {UpdateSalesChannelDTO} data - The attributes to update in the sales channel. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The updated sales channels. + * + * @example + * const salesChannels = await salesChannelModuleService.update( + * { + * name: "B2B", + * }, + * { + * description: "Sales channel for B2B customers", + * } + * ) + */ update( selector: FilterableSalesChannelProps, data: UpdateSalesChannelDTO, sharedContext?: Context ): Promise + /** + * This method updates or creates a sales channel if it doesn't exist. + * + * @param {UpsertSalesChannelDTO} data - The attributes in the sales channel 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 sales channel. + * + * @example + * const salesChannel = await salesChannelModuleService.upsert({ + * name: "B2B", + * }) + */ upsert( data: UpsertSalesChannelDTO, sharedContext?: Context ): Promise + + /** + * This method updates or creates sales channels if they don't exist. + * + * @param {UpsertSalesChannelDTO[]} data - The attributes in the sales channels 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 sales channels. + * + * @example + * const salesChannels = await salesChannelModuleService.upsert([ + * { + * name: "B2B", + * }, + * { + * id: "sc_123", + * description: "Sales channel for B2B customers", + * }, + * ]) + */ upsert( data: UpsertSalesChannelDTO[], sharedContext?: Context ): Promise /** - * This method deletes sales channels by their IDs. + * This method deletes sales channel by their IDs. * - * @param {string[]} ids - The list of IDs of sales channels to delete. + * @param {string[]} ids - The IDs of the sales channel. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the sales channels are deleted. + * @returns {Promise} Resolves when the sales channels are deleted successfully. * * @example - * {example-code} + * await salesChannelModuleService.delete(["sc_123", "sc_321"]) */ delete(ids: string[], sharedContext?: Context): Promise @@ -76,36 +152,25 @@ export interface ISalesChannelModuleService extends IModuleService { * * @param {string} id - The ID of the sales channel. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the sales channel is deleted. + * @returns {Promise} Resolves when the sales channel is deleted successfully. * * @example - * {example-code} + * await salesChannelModuleService.delete("sc_123") */ delete(id: string, sharedContext?: Context): Promise /** * This method retrieves a sales channel by its ID. * - * @param {string} id - The ID of the retrieve. + * @param {string} id - The ID of the sales channel. * @param {FindConfig} config - The configurations determining how the sales channel is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a sales channel. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The retrieved sales channels. + * @returns {Promise} The retrieved sales channel. * * @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 salesChannel = + * await salesChannelModuleService.retrieve("sc_123") */ retrieve( id: string, @@ -116,32 +181,34 @@ export interface ISalesChannelModuleService extends IModuleService { /** * This method retrieves a paginated list of sales channels based on optional filters and configuration. * - * @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channel. + * @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channels. * @param {FindConfig} config - The configurations determining how the sales channel is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a sales channel. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The list of sales channels. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of sales channels using their IDs: * * ```ts - * {example-code} + * const salesChannels = await salesChannelModuleService.list({ + * id: ["sc_123", "sc_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 salesChannels = await salesChannelModuleService.list( + * { + * id: ["sc_123", "sc_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?: FilterableSalesChannelProps, @@ -152,32 +219,36 @@ export interface ISalesChannelModuleService extends IModuleService { /** * This method retrieves a paginated list of sales channels along with the total count of available sales channels satisfying the provided filters. * - * @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channel. + * @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channels. * @param {FindConfig} config - The configurations determining how the sales channel is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a sales channel. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise<[SalesChannelDTO[], number]>} The list of sales channels along with their total count. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of sales channels using their IDs: * * ```ts - * {example-code} + * const [salesChannels, count] = + * await salesChannelModuleService.listAndCount({ + * id: ["sc_123", "sc_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 [salesChannels, count] = + * await salesChannelModuleService.listAndCount( + * { + * id: ["sc_123", "sc_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?: FilterableSalesChannelProps, @@ -188,13 +259,14 @@ export interface ISalesChannelModuleService extends IModuleService { /** * This method soft deletes sales channels by their IDs. * - * @param {string[]} salesChannelIds - The list of IDs of sales channels to soft delete. + * @param {string[]} salesChannelIds - The sales channels' ID. * @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 when the sales channels 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 salesChannelModuleService.delete(["sc_123", "sc_321"]) */ softDelete( salesChannelIds: string[], @@ -203,18 +275,17 @@ export interface ISalesChannelModuleService extends IModuleService { ): Promise | void> /** - * This method restores soft deleted sales channels by their IDs. + * This method restores a soft deleted sales channel by its IDs. * - * @param {string[]} salesChannelIds - The list of IDs of sales channels to restore. - * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the sales channels. You can pass to its `returnLinkableKeys` - * property any of the sales channels's relation attribute names. + * @param {string[]} salesChannelIds - The list of {summary} + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the sales channel. You can pass to its `returnLinkableKeys` + * property any of the sales channel'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. - * The object's keys are the ID attribute names of the sales channels entity's relations, - * and its value is an array of strings, each being the ID of the record associated with the sales channel through this relation. + * If there are no related records restored, the promise resolves to `void`. * * @example - * {example-code} + * await salesChannelModuleService.restore(["sc_123", "sc_321"]) */ restore( salesChannelIds: string[],