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

@@ -42,6 +42,9 @@ export interface UpdateSalesChannelDTO {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * 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
 

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<SalesChannelDTO[]>} 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<SalesChannelDTO>} The created a sales channel.
+   * @returns {Promise<SalesChannelDTO>} The created sales channel.
    *
    * @example
-   * {example-code}
+   * const salesChannel = await salesChannelModuleService.create({
+   *   name: "B2B",
+   * })
    */
   create(
     data: CreateSalesChannelDTO,
     sharedContext?: Context
   ): Promise<SalesChannelDTO>
 
+  /**
+   * 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<SalesChannelDTO>} 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<SalesChannelDTO>
+
+  /**
+   * 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<SalesChannelDTO[]>} 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<SalesChannelDTO[]>
 
+  /**
+   * 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<SalesChannelDTO>} The created or updated sales channel.
+   *
+   * @example
+   * const salesChannel = await salesChannelModuleService.upsert({
+   *   name: "B2B",
+   * })
+   */
   upsert(
     data: UpsertSalesChannelDTO,
     sharedContext?: Context
   ): Promise<SalesChannelDTO>
+
+  /**
+   * 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<SalesChannelDTO[]>} 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<SalesChannelDTO[]>
 
   /**
-   * 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<void>} Resolves when the sales channels are deleted.
+   * @returns {Promise<void>} Resolves when the sales channels are deleted successfully.
    *
    * @example
-   * {example-code}
+   * await salesChannelModuleService.delete(["sc_123", "sc_321"])
    */
   delete(ids: string[], sharedContext?: Context): Promise<void>
 
@@ -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<void>} Resolves when the sales channel is deleted.
+   * @returns {Promise<void>} Resolves when the sales channel is deleted successfully.
    *
    * @example
-   * {example-code}
+   * await salesChannelModuleService.delete("sc_123")
    */
   delete(id: string, sharedContext?: Context): Promise<void>
 
   /**
    * 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<SalesChannelDTO>} 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>} The retrieved sales channels.
+   * @returns {Promise<SalesChannelDTO>} The retrieved sales channel.
    *
    * @example
-   * A simple example that retrieves a {type name} by its ID:
+   * const salesChannel =
-   *
+   *   await salesChannelModuleService.retrieve("sc_123")
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   * To specify relations that should be retrieved:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   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<SalesChannelDTO>} 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[]>} 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<SalesChannelDTO>} 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<TReturnableLinkableKeys>} 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<void | Record<string, string[]>>} Resolves when the sales channels are soft deleted.
+   * @returns {Promise<void | Record<string, string[]>>} 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<TReturnableLinkableKeys extends string = string>(
     salesChannelIds: string[],
@@ -203,18 +275,17 @@ export interface ISalesChannelModuleService extends IModuleService {
   ): Promise<Record<string, string[]> | 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 {string[]} salesChannelIds - The list of {summary}
-   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the sales channels. You can pass to its `returnLinkableKeys`
+   * @param {RestoreReturn<TReturnableLinkableKeys>} 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 channels's relation attribute names.
+   * 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<void | Record<string, string[]>>} 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,
+   * If there are no related records restored, the promise resolves to `void`.
-   * and its value is an array of strings, each being the ID of the record associated with the sales channel through this relation.
    *
    * @example
-   * {example-code}
+   * await salesChannelModuleService.restore(["sc_123", "sc_321"])
    */
   restore<TReturnableLinkableKeys extends string = string>(
     salesChannelIds: string[],