chore: generated tsdocs (#6352)

Generated TSDocs for the past release.

Note: I haven't updated examples as the examples are for modules without a public reference yet, so the examples can wait.

packages/types/src/auth/common/auth-user.ts

@@ -1,34 +1,128 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ *
+ * The auth user details.
+ */
 export type AuthUserDTO = {
+  /**
+   * The ID of the auth user.
+   */
   id: string
+
+  /**
+   * The provider of the auth user.
+   */
   provider: string
+
+  /**
+   * The associated providers entity's ID.
+   */
   entity_id: string
+
+  /**
+   * The scope of the auth user.
+   */
   scope: string
+
+  /**
+   * The provider metadata of the auth user.
+   */
   provider_metadata?: Record<string, unknown>
+
+  /**
+   * The user metadata of the auth user.
+   */
   user_metadata: Record<string, unknown>
+
+  /**
+   * The app metadata of the auth user.
+   */
   app_metadata: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * The auth user to be created.
+ */
 export type CreateAuthUserDTO = {
+  /**
+   * The ID of the auth user.
+   */
   id?: string
+
+  /**
+   * The provider of the auth user.
+   */
   provider: string
+
+  /**
+   * The associated entity's ID.
+   */
   entity_id: string
+
+  /**
+   * The scope of the auth user.
+   */
   scope: string
+
+  /**
+   * The provider metadata of the auth user.
+   */
   provider_metadata?: Record<string, unknown>
+
+  /**
+   * The user metadata of the auth user.
+   */
   user_metadata?: Record<string, unknown>
+
+  /**
+   * The app metadata of the auth user.
+   */
   app_metadata?: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * The attributes to update in the auth user.
+ */
 export type UpdateAuthUserDTO = {
+  /**
+   * The ID of the auth user.
+   */
   id: string
+
+  /**
+   * The provider metadata of the auth user.
+   */
   provider_metadata?: Record<string, unknown>
+
+  /**
+   * The user metadata of the auth user.
+   */
   user_metadata?: Record<string, unknown>
+
+  /**
+   * The app metadata of the auth user.
+   */
   app_metadata?: Record<string, unknown>
 }
 
+/**
+ * The filters to apply on the retrieved auth user.
+ */
 export interface FilterableAuthUserProps
   extends BaseFilterable<FilterableAuthUserProps> {
+  /**
+   * The IDs to filter the auth user by.
+   */
   id?: string[]
+
+  /**
+   * Filter the auth auth user by the associated provider(s).
+   */
   provider?: string[] | string
 }

packages/types/src/auth/common/provider.ts

@@ -1,22 +1,88 @@
+/**
+ * @interface
+ *
+ * The details of the authentication response.
+ */
 export type AuthenticationResponse = {
+  /**
+   * Whether the authentication was successful.
+   */
   success: boolean
+
+  /**
+   * The authenticated user's details. The details shape
+   * depends on the used provider ID.
+   */
   authUser?: any
+
+  /**
+   * The error message, if an error occurs.
+   */
   error?: string
+
+  /**
+   * Redirect location. Location takes precedence over success.
+   */
   location?: string
 }
 
+/**
+ * @interface
+ *
+ * Provider configuration for the Medusa auth module.
+ */
 export type AuthModuleProviderConfig = {
+  /**
+   * Provider name
+   */
   name: string
+
+  /**
+   * Scope configurations for the provider
+   */
   scopes: Record<string, AuthProviderScope>
 }
 
+/**
+ * @interface
+ *
+ * Configuration of a single provider scope
+ */
 export type AuthProviderScope = Record<string, unknown>
 
+/**
+ * @interface
+ *
+ * Input for authentication and callback validation methods.
+ */
 export type AuthenticationInput = {
+  /**
+   * url of incoming authentication request.
+   */
   url: string
+
+  /**
+   * Headers of incoming authentication request.
+   */
   headers: Record<string, string>
+
+  /**
+   *  Query params of incoming authentication request.
+   */
   query: Record<string, string>
+
+  /**
+   * Body of incoming authentication request.
+   */
   body: Record<string, string>
+
+  /**
+   * Scope for authentication request.
+   */
   authScope: string
+
+  /**
+   * Protocol of incoming authentication request (For example, `https`).
+   */
   protocol: string
 }

packages/types/src/auth/service.ts

@@ -11,52 +11,211 @@ import { Context } from "../shared-context"
 import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 
+/**
+ * @ignore
+ */
 export type JWTGenerationOptions = {
   expiresIn?: string | number
 }
-
+/**
+ * The main service interface for the authentication module.
+ */
 export interface IAuthModuleService extends IModuleService {
+  /**
+   * This method is the first invoked method of the authentication flow. It handles the incoming authentication request.
+   *
+   * @param {string} provider - The provider to use for authentication.
+   * @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider
+   * @returns {Promise<AuthenticationResponse>} The authentication's result.
+   *
+   * @example
+   * {example-code}
+   */
   authenticate(
     provider: string,
     providerData: AuthenticationInput
   ): Promise<AuthenticationResponse>
 
+  /**
+   * This method handles the callback from an authentication provider when an authentication has been initialized and the user is redirected.
+   *
+   * @param {string} provider - The provider to use for callback validation.
+   * @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider
+   * @returns {Promise<AuthenticationResponse>} The authentication's result.
+   *
+   * @example
+   * {example-code}
+   */
   validateCallback(
     provider: string,
     providerData: AuthenticationInput
   ): Promise<AuthenticationResponse>
 
+  /**
+   * This method retrieves the user by its ID.
+   *
+   * @param {string} id - The ID of the retrieve.
+   * @param {FindConfig<AuthUserDTO>} config - The configurations determining how the auth user is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a auth user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<AuthUserDTO>} The retrieved user.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieve(
     id: string,
     config?: FindConfig<AuthUserDTO>,
     sharedContext?: Context
   ): Promise<AuthUserDTO>
 
+  /**
+   * This method retrieves a paginated list of users based on optional filters and configuration.
+   *
+   * @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth user.
+   * @param {FindConfig<AuthUserDTO>} config - The configurations determining how the auth user is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a auth user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<AuthUserDTO[]>} The list of users.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableAuthUserProps,
     config?: FindConfig<AuthUserDTO>,
     sharedContext?: Context
   ): Promise<AuthUserDTO[]>
 
+  /**
+   * This method retrieves a paginated list of user along with the total count of available users satisfying the provided filters.
+   *
+   * @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth user.
+   * @param {FindConfig<AuthUserDTO>} config - The configurations determining how the auth user is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a auth user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[AuthUserDTO[], number]>} The list of users along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableAuthUserProps,
     config?: FindConfig<AuthUserDTO>,
     sharedContext?: Context
   ): Promise<[AuthUserDTO[], number]>
 
+  /**
+   * This method creates users
+   *
+   * @param {CreateAuthUserDTO[]} data - The auth user to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<AuthUserDTO[]>} The created users.
+   *
+   * @example
+   * {example-code}
+   */
   create(
     data: CreateAuthUserDTO[],
     sharedContext?: Context
   ): Promise<AuthUserDTO[]>
 
+  /**
+   * This method creates a user
+   *
+   * @param {CreateAuthUserDTO} data - The auth user to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<AuthUserDTO>} The created user.
+   *
+   * @example
+   * {example-code}
+   */
   create(data: CreateAuthUserDTO, sharedContext?: Context): Promise<AuthUserDTO>
 
+  /**
+   * This method updates existing users.
+   *
+   * @param {UpdateAuthUserDTO[]} data - The attributes to update in the auth user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<AuthUserDTO[]>} The updated users.
+   *
+   * @example
+   * {example-code}
+   */
   update(
     data: UpdateAuthUserDTO[],
     sharedContext?: Context
   ): Promise<AuthUserDTO[]>
 
+  /**
+   * This method updates existing user.
+   *
+   * @param {UpdateAuthUserDTO} data - The attributes to update in the auth user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<AuthUserDTO>} The updated user.
+   *
+   * @example
+   * {example-code}
+   */
   update(data: UpdateAuthUserDTO, sharedContext?: Context): Promise<AuthUserDTO>
 
+  /**
+   * This method deletes users by their IDs.
+   *
+   * @param {string[]} ids - The list of IDs of users to delete.
+   * @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 users are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   delete(ids: string[], sharedContext?: Context): Promise<void>
 }

packages/types/src/authentication/common/provider.ts

@@ -1,22 +0,0 @@
-export type AuthenticationResponse = {
-  success: boolean
-  authUser?: any
-  error?: string
-  location?: string
-}
-
-export type AuthModuleProviderConfig = {
-  name: string
-  scopes: Record<string, AuthProviderScope>
-}
-
-export type AuthProviderScope = Record<string, string>
-
-export type AuthenticationInput = {
-  connection: { encrypted: boolean }
-  url: string
-  headers: Record<string, string>
-  query: Record<string, string>
-  body: Record<string, string>
-  scope: string
-}

packages/types/src/common/common.ts

@@ -14,24 +14,49 @@ import { FindOptionsRelations } from "typeorm/find-options/FindOptionsRelations"
  * Utility type used to remove some optional attributes (coming from K) from a type T
  */
 export type WithRequiredProperty<T, K extends keyof T> = T & {
-  // -? removes 'optional' from a property
   [Property in K]-?: T[Property]
 }
 
+/**
+ * @ignore
+ */
 export type PartialPick<T, K extends keyof T> = {
   [P in K]?: T[P]
 }
 
+/**
+ * Representing a table in the database.
+ */
 export interface BaseEntity {
+  /**
+   * The ID of an entity's record.
+   */
   id: string
+
+  /**
+   * The date an entity's record was created.
+   */
   created_at: Date
+
+  /**
+   * The date an entity's record was updated.
+   */
   updated_at: Date
 }
 
+/**
+ * Representing a deletable entity.
+ */
 export interface SoftDeletableEntity extends BaseEntity {
+  /**
+   * The date an entity's record was deleted.
+   */
   deleted_at: Date | null
 }
 
+/**
+ * @ignore
+ */
 export type Writable<T> = {
   -readonly [key in keyof T]:
     | T[key]
@@ -51,23 +76,30 @@ export interface FindConfig<Entity> {
    * An array of strings, each being attribute names of the entity to retrieve in the result.
    */
   select?: (keyof Entity | string)[]
+
   /**
    * A number indicating the number of records to skip before retrieving the results.
    */
   skip?: number | null | undefined
+
   /**
    * A number indicating the number of records to return in the result.
    */
   take?: number | null | undefined
+
   /**
    * An array of strings, each being relation names of the entity to retrieve in the result.
    */
   relations?: string[]
+
   /**
    * An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC`
    * to sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.
    */
-  order?: { [K: string]: "ASC" | "DESC" }
+  order?: {
+    [K: string]: "ASC" | "DESC"
+  }
+
   /**
    * A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the
    * `SoftDeletableEntity` class.
@@ -75,6 +107,9 @@ export interface FindConfig<Entity> {
   withDeleted?: boolean
 }
 
+/**
+ * @ignore
+ */
 export type ExtendedFindConfig<TEntity> = (
   | Omit<FindOneOptions<TEntity>, "where" | "relations" | "select">
   | Omit<FindManyOptions<TEntity>, "where" | "relations" | "select">
@@ -87,11 +122,23 @@ export type ExtendedFindConfig<TEntity> = (
   take?: number
 }
 
-export type QuerySelector<TEntity> = Selector<TEntity> & { q?: string }
+/**
+ * @ignore
+ */
+export type QuerySelector<TEntity> = Selector<TEntity> & {
+  q?: string
+}
+
+/**
+ * @ignore
+ */
 export type TreeQuerySelector<TEntity> = QuerySelector<TEntity> & {
   include_descendants_tree?: boolean
 }
 
+/**
+ * @ignore
+ */
 export type Selector<TEntity> = {
   [key in keyof TEntity]?:
     | TEntity[key]
@@ -102,6 +149,9 @@ export type Selector<TEntity> = {
     | FindOperator<TEntity[key][] | string | string[]>
 }
 
+/**
+ * @ignore
+ */
 export type TotalField =
   | "shipping_total"
   | "discount_total"
@@ -113,6 +163,9 @@ export type TotalField =
   | "gift_card_total"
   | "gift_card_tax_total"
 
+/**
+ * @ignore
+ */
 export interface CustomFindOptions<TModel, InKeys extends keyof TModel> {
   select?: FindManyOptions<TModel>["select"]
   where?: FindManyOptions<TModel>["where"] & {
@@ -123,6 +176,9 @@ export interface CustomFindOptions<TModel, InKeys extends keyof TModel> {
   take?: number
 }
 
+/**
+ * @ignore
+ */
 export type QueryConfig<TEntity extends BaseEntity> = {
   defaultFields?: (keyof TEntity | string)[]
   defaultRelations?: string[]
@@ -132,17 +188,57 @@ export type QueryConfig<TEntity extends BaseEntity> = {
   isList?: boolean
 }
 
+/**
+ * @interface
+ *
+ * Fields that can be passed in the query parameters of a request.
+ */
 export type RequestQueryFields = {
+  /**
+   * Comma-separated relations that should be expanded in the returned data.
+   */
   expand?: string
+
+  /**
+   * Comma-separated fields that should be included in the returned data.
+   */
   fields?: string
+
+  /**
+   * The number of items to skip when retrieving a list.
+   */
   offset?: number
+
+  /**
+   * Limit the number of items returned in the list.
+   */
   limit?: number
+
+  /**
+   * Field to sort items in the list by.
+   */
   order?: string
 }
 
+/**
+ * @interface
+ *
+ * Fields included in the response if it's paginated.
+ */
 export type PaginatedResponse = {
+  /**
+   * The limit applied on the retrieved items.
+   */
   limit: number
+
+  /**
+   * The number of items skipped before retrieving the list of items.
+   */
   offset: number
+
+  /**
+   * The total count of items.
+   */
   count: number
 }
 
@@ -154,83 +250,269 @@ export type DeleteResponse = {
    * The ID of the item that was deleted.
    */
   id: string
+
   /**
    * The type of the item that was deleted.
    */
   object: string
+
   /**
    * Whether the item was deleted successfully.
    */
   deleted: boolean
 }
 
+/**
+ * Requests that don't accept any query parameters can use this type.
+ */
 export interface EmptyQueryParams {}
 
 // TODO: Build a tree repository options from this
 export interface RepositoryTransformOptions {}
 
+/**
+ * Fields used to apply flexible filters on dates.
+ */
 export interface DateComparisonOperator {
+  /**
+   * The filtered date must be less than this value.
+   */
   lt?: Date
+
+  /**
+   * The filtered date must be greater than this value.
+   */
   gt?: Date
+
+  /**
+   * The filtered date must be greater than or equal to this value.
+   */
   gte?: Date
+
+  /**
+   * The filtered date must be less than or equal to this value.
+   */
   lte?: Date
 }
 
+/**
+ * Fields used to apply flexible filters on strings.
+ */
 export interface StringComparisonOperator {
+  /**
+   * The filtered string must be less than this value.
+   */
   lt?: string
+
+  /**
+   * The filtered string must be greater than this value.
+   */
   gt?: string
+
+  /**
+   * The filtered string must be greater than or equal to this value.
+   */
   gte?: string
+
+  /**
+   * The filtered string must be less than or equal to this value.
+   */
   lte?: string
+
+  /**
+   * The filtered string must contain this value.
+   */
   contains?: string
+
+  /**
+   * The filtered string must start with this value.
+   */
   starts_with?: string
+
+  /**
+   * The filtered string must end with this value.
+   */
   ends_with?: string
 }
 
+/**
+ * Fields used to apply flexible filters on numbers.
+ */
 export interface NumericalComparisonOperator {
+  /**
+   * The filtered number must be less than this value.
+   */
   lt?: number
+
+  /**
+   * The filtered number must be greater than this value.
+   */
   gt?: number
+
+  /**
+   * The filtered number must be greater than or equal to this value.
+   */
   gte?: number
+
+  /**
+   * The filtered number must be less than or equal to this value.
+   */
   lte?: number
 }
 
+/**
+ * Address fields used when creating/updating an address.
+ */
 export interface AddressPayload {
+  /**
+   * First name
+   */
   first_name?: string
+
+  /**
+   * Last name
+   */
   last_name?: string
+
+  /**
+   * Phone Number
+   */
   phone?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
+
+  /**
+   * Company
+   */
   company?: string
+
+  /**
+   * Address line 1
+   */
   address_1?: string
+
+  /**
+   * Address line 2
+   */
   address_2?: string
+
+  /**
+   * City
+   */
   city?: string
+
+  /**
+   * The 2 character ISO code of the country in lower case
+   */
   country_code?: string
+
+  /**
+   * Province
+   */
   province?: string
+
+  /**
+   * Postal Code
+   */
   postal_code?: string
 }
 
+/**
+ * Address fields used when creating an address.
+ */
 export interface AddressCreatePayload {
+  /**
+   * First name
+   */
   first_name: string
+
+  /**
+   * Last name
+   */
   last_name: string
+
+  /**
+   * Phone Number
+   */
   phone: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata: object
+
+  /**
+   * Company
+   */
   company: string
+
+  /**
+   * Address line 1
+   */
   address_1: string
+
+  /**
+   * Address line 2
+   */
   address_2: string
+
+  /**
+   * City
+   */
   city: string
+
+  /**
+   * The 2 character ISO code of the country in lower case
+   */
   country_code: string
+
+  /**
+   * Province
+   */
   province: string
+
+  /**
+   * Postal Code
+   */
   postal_code: string
 }
 
+/**
+ * Parameters that can be used to configure how data is retrieved.
+ */
 export interface FindParams {
+  /**
+   * Comma-separated relations that should be expanded in the returned data.
+   */
   expand?: string
+
+  /**
+   *Comma-separated fields that should be included in the returned data.
+   */
   fields?: string
 }
 
+/**
+ * Parameters that can be used to configure how a list of data is paginated.
+ */
 export interface FindPaginationParams {
+  /**
+   * The number of items to skip when retrieving a list.
+   */
   offset?: number
+
+  /**
+   * Limit the number of items returned in the list.
+   */
   limit?: number
 }
 
+/**
+ * @ignore
+ */
 export type Pluralize<Singular extends string> = Singular extends `${infer R}y`
   ? `${R}ies`
   : Singular extends `${infer R}es`

packages/types/src/customer/common.ts

@@ -2,152 +2,634 @@ import { AddressDTO } from "../address"
 import { BaseFilterable } from "../dal"
 import { OperatorMap } from "../dal/utils"
 
+/**
+ * The customer address details.
+ */
 export interface CustomerAddressDTO {
+  /**
+   * The ID of the customer address.
+   */
   id: string
+
+  /**
+   * The address name of the customer address.
+   */
   address_name?: string
+
+  /**
+   * Whether the customer address is default shipping.
+   */
   is_default_shipping: boolean
+
+  /**
+   * Whether the customer address is default billing.
+   */
   is_default_billing: boolean
+
+  /**
+   * The associated customer's ID.
+   */
   customer_id: string
+
+  /**
+   * The company of the customer address.
+   */
   company?: string
+
+  /**
+   * The first name of the customer address.
+   */
   first_name?: string
+
+  /**
+   * The last name of the customer address.
+   */
   last_name?: string
+
+  /**
+   * The address 1 of the customer address.
+   */
   address_1?: string
+
+  /**
+   * The address 2 of the customer address.
+   */
   address_2?: string
+
+  /**
+   * The city of the customer address.
+   */
   city?: string
+
+  /**
+   * The country code of the customer address.
+   */
   country_code?: string
+
+  /**
+   * The province of the customer address.
+   */
   province?: string
+
+  /**
+   * The postal code of the customer address.
+   */
   postal_code?: string
+
+  /**
+   * The phone of the customer address.
+   */
   phone?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
+
+  /**
+   * The created at of the customer address.
+   */
   created_at: string
+
+  /**
+   * The updated at of the customer address.
+   */
   updated_at: string
 }
 
+/**
+ * The filters to apply on the retrieved customer address.
+ */
 export interface FilterableCustomerAddressProps
   extends BaseFilterable<FilterableCustomerAddressProps> {
+  /**
+   * The IDs to filter the customer address by.
+   */
   id?: string | string[]
+
+  /**
+   * Filter addresses by name.
+   */
   address_name?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by whether they're the default for shipping.
+   */
   is_default_shipping?: boolean | OperatorMap<boolean>
+
+  /**
+   * Filter addresses by whether they're the default for billing.
+   */
   is_default_billing?: boolean | OperatorMap<boolean>
+
+  /**
+   * Filter addresses by the associated customer's ID.
+   */
   customer_id?: string | string[]
+
+  /**
+   * Filter addresses by the associated customer.
+   */
   customer?: FilterableCustomerProps | string | string[]
+
+  /**
+   * Filter addresses by company.
+   */
   company?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by first name.
+   */
   first_name?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by last name.
+   */
   last_name?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by first address line.
+   */
   address_1?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by second address line.
+   */
   address_2?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by city.
+   */
   city?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by country code.
+   */
   country_code?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by province.
+   */
   province?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by postal code.
+   */
   postal_code?: string | OperatorMap<string>
+
+  /**
+   * Filter addresses by phone number.
+   */
   phone?: string | OperatorMap<string>
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | OperatorMap<Record<string, unknown>>
+
+  /**
+   * Filter addresses by created date.
+   */
   created_at?: OperatorMap<string>
+
+  /**
+   * Filter addresses by updated date.
+   */
   updated_at?: OperatorMap<string>
 }
 
+/**
+ * The filters to apply on the retrieved customer group.
+ */
 export interface FilterableCustomerGroupProps
   extends BaseFilterable<FilterableCustomerGroupProps> {
+  /**
+   * The IDs to filter the customer group by.
+   */
   id?: string | string[]
+
+  /**
+   * Filter customer groups by name.
+   */
   name?: string | OperatorMap<string>
+
+  /**
+   * Filter customer groups by associated customers.
+   */
   customers?: FilterableCustomerProps | string | string[]
+
+  /**
+   * Filter customer groups by their `created_by` attribute.
+   */
   created_by?: string | string[] | null
+
+  /**
+   * Filter customer groups by created date.
+   */
   created_at?: OperatorMap<string>
+
+  /**
+   * Filter customer groups by updated date.
+   */
   updated_at?: OperatorMap<string>
 }
 
+/**
+ * The filters to apply on the retrieved customer group's customers.
+ */
 export interface FilterableCustomerGroupCustomerProps
   extends BaseFilterable<FilterableCustomerGroupCustomerProps> {
+  /**
+   * The IDs to filter the customer group's customer relation.
+   */
   id?: string | string[]
+
+  /**
+   * Filter by customer ID(s).
+   */
   customer_id?: string | string[]
+
+  /**
+   * Filter by customer group ID(s).
+   */
   customer_group_id?: string | string[]
+
+  /**
+   * Filter by customer IDs or filterable customer attributes.
+   */
   customer?: FilterableCustomerProps | string | string[]
+
+  /**
+   * Filter by customer group IDs or filterable group attributes.
+   */
   group?: FilterableCustomerGroupProps | string | string[]
+
+  /**
+   * Filter by the group's `created_by` attribute.
+   */
   created_by?: string | string[] | null
+
+  /**
+   * Filter by created date.
+   */
   created_at?: OperatorMap<string>
+
+  /**
+   * Filter by updated date.
+   */
   updated_at?: OperatorMap<string>
 }
 
+/**
+ * The filters to apply on the retrieved customer.
+ */
 export interface FilterableCustomerProps
   extends BaseFilterable<FilterableCustomerProps> {
+  /**
+   * The IDs to filter the customer by.
+   */
   id?: string | string[]
+
+  /**
+   * Filter by email.
+   */
   email?: string | string[] | OperatorMap<string>
+
+  /**
+   * Filter by associated customer group.
+   */
   groups?: FilterableCustomerGroupProps | string | string[]
+
+  /**
+   * Filter by the associated default billing address's ID.
+   */
   default_billing_address_id?: string | string[] | null
+
+  /**
+   * Filter by the associated default shipping address's ID.
+   */
   default_shipping_address_id?: string | string[] | null
+
+  /**
+   * Filter by company name.
+   */
   company_name?: string | string[] | OperatorMap<string> | null
+
+  /**
+   * Filter by first name.
+   */
   first_name?: string | string[] | OperatorMap<string> | null
+
+  /**
+   * Filter by last name.
+   */
   last_name?: string | string[] | OperatorMap<string> | null
+
+  /**
+   * Filter by whether the customer has an account.
+   */
   has_account?: boolean | OperatorMap<boolean>
+  /**
+   * Filter by the `created_by` attribute.
+   */
   created_by?: string | string[] | null
+
+  /**
+   * Filter by created date.
+   */
   created_at?: OperatorMap<string>
+
+  /**
+   * Filter by updated date.
+   */
   updated_at?: OperatorMap<string>
 }
 
+/**
+ * The customer group details.
+ */
 export interface CustomerGroupDTO {
+  /**
+   * The ID of the customer group.
+   */
   id: string
+
+  /**
+   * The name of the customer group.
+   */
   name: string
+
+  /**
+   * The customers of the customer group.
+   */
   customers?: Partial<CustomerDTO>[]
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
+
+  /**
+   * Who created the customer group.
+   */
   created_by?: string | null
+
+  /**
+   * The deletion date of the customer group.
+   */
   deleted_at?: Date | string | null
+
+  /**
+   * The creation date of the customer group.
+   */
   created_at?: Date | string
+
+  /**
+   * The update date of the customer group.
+   */
   updated_at?: Date | string
 }
 
+/**
+ * The details of a group's customer.
+ */
 export interface CustomerGroupCustomerDTO {
+  /**
+   * The ID of the relation.
+   */
   id: string
+
+  /**
+   * The customer's ID.
+   */
   customer_id: string
+
+  /**
+   * The customer group's ID.
+   */
   customer_group_id: string
+
+  /**
+   * The customer's details.
+   */
   customer?: Partial<CustomerDTO>
+
+  /**
+   * The group's details.
+   */
   group?: Partial<CustomerGroupDTO>
+
+  /**
+   * Who the relation was created by.
+   */
   created_by?: string | null
+
+  /**
+   * The creation date of the customer group customer.
+   */
   created_at?: Date | string
+
+  /**
+   * The update date of the customer group customer.
+   */
   updated_at?: Date | string
 }
 
+/**
+ * The customer details.
+ */
 export interface CustomerDTO {
+  /**
+   * The ID of the customer.
+   */
   id: string
+
+  /**
+   * The email of the customer.
+   */
   email: string
+
+  /**
+   * The associated default billing address's ID.
+   */
   default_billing_address_id?: string | null
+
+  /**
+   * The associated default shipping address's ID.
+   */
   default_shipping_address_id?: string | null
+
+  /**
+   * The company name of the customer.
+   */
   company_name?: string | null
+
+  /**
+   * The first name of the customer.
+   */
   first_name?: string | null
+
+  /**
+   * The last name of the customer.
+   */
   last_name?: string | null
+
+  /**
+   * The addresses of the customer.
+   */
   addresses?: CustomerAddressDTO[]
+
+  /**
+   * The phone of the customer.
+   */
   phone?: string | null
-  groups?: { id: string }[]
+
+  /**
+   * The groups of the customer.
+   */
+  groups?: {
+    /**
+     * The ID of the group.
+     */
+    id: string
+  }[]
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
+
+  /**
+   * Who created the customer.
+   */
   created_by?: string | null
+
+  /**
+   * The deletion date of the customer.
+   */
   deleted_at?: Date | string | null
+
+  /**
+   * The creation date of the customer.
+   */
   created_at?: Date | string
+
+  /**
+   * The update date of the customer.
+   */
   updated_at?: Date | string
 }
 
+/**
+ * @interface
+ *
+ * The details of a customer and customer group pair.
+ */
 export type GroupCustomerPair = {
+  /**
+   * The customer's ID.
+   */
   customer_id: string
+
+  /**
+   * The customer group's ID.
+   */
   customer_group_id: string
 }
 
+/**
+ * @interface
+ *
+ * The legacy customer details.
+ */
 export type legacy_CustomerDTO = {
+  /**
+   * The ID of the customer.
+   */
   id: string
+
+  /**
+   * The email of the customer.
+   */
   email: string
+
+  /**
+   * The associated billing address's ID.
+   */
   billing_address_id?: string | null
+
+  /**
+   * The associated shipping address's ID.
+   */
   shipping_address_id?: string | null
+
+  /**
+   * The first name of the customer.
+   */
   first_name?: string | null
+
+  /**
+   * The last name of the customer.
+   */
   last_name?: string | null
+
+  /**
+   * The billing address of the customer.
+   */
   billing_address?: AddressDTO
+
+  /**
+   * The shipping address of the customer.
+   */
   shipping_address?: AddressDTO
+
+  /**
+   * The phone of the customer.
+   */
   phone?: string | null
+
+  /**
+   * Whether the customer has account.
+   */
   has_account: boolean
+
+  /**
+   * The groups of the customer.
+   */
   groups?: {
+    /**
+     * The ID of the customer group.
+     */
     id: string
   }[]
+
+  /**
+   * The orders of the customer.
+   */
   orders: {
+    /**
+     * The ID of the order.
+     */
     id: string
   }[]
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
+
+  /**
+   * The deletion date of the customer.
+   */
   deleted_at?: Date | string
+
+  /**
+   * The creation date of the customer.
+   */
   created_at?: Date | string
+
+  /**
+   * The update date of the legacy_ customer.
+   */
   updated_at?: Date | string
 }

packages/types/src/customer/mutations.ts

@@ -1,101 +1,384 @@
+/**
+ * The customer address to be created.
+ */
 export interface CreateCustomerAddressDTO {
+  /**
+   * The address's name.
+   */
   address_name?: string
+
+  /**
+   * Whether the address is default shipping.
+   */
   is_default_shipping?: boolean
+
+  /**
+   * Whether the address is the default for billing.
+   */
   is_default_billing?: boolean
+
+  /**
+   * The associated customer's ID.
+   */
   customer_id: string
+
+  /**
+   * The company.
+   */
   company?: string
+
+  /**
+   * The first name.
+   */
   first_name?: string
+
+  /**
+   * The last name.
+   */
   last_name?: string
+
+  /**
+   * The address 1.
+   */
   address_1?: string
+
+  /**
+   * The address 2.
+   */
   address_2?: string
+
+  /**
+   * The city.
+   */
   city?: string
+
+  /**
+   * The country code.
+   */
   country_code?: string
+
+  /**
+   * The province.
+   */
   province?: string
+
+  /**
+   * The postal code.
+   */
   postal_code?: string
+
+  /**
+   * The phone.
+   */
   phone?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The attributes to update in the customer's address.
+ */
 export interface UpdateCustomerAddressDTO {
+  /**
+   * The ID of the address.
+   */
   id?: string
+
+  /**
+   * The address's name.
+   */
   address_name?: string
+
+  /**
+   * Whether the address is the default for shipping.
+   */
   is_default_shipping?: boolean
+
+  /**
+   * Whether the address is the default for billing.
+   */
   is_default_billing?: boolean
+
+  /**
+   * The associated customer's ID.
+   */
   customer_id?: string
+
+  /**
+   * The company.
+   */
   company?: string
+
+  /**
+   * The first name.
+   */
   first_name?: string
+
+  /**
+   * The last name.
+   */
   last_name?: string
+
+  /**
+   * The address 1.
+   */
   address_1?: string
+
+  /**
+   * The address 2.
+   */
   address_2?: string
+
+  /**
+   * The city.
+   */
   city?: string
+
+  /**
+   * The country code.
+   */
   country_code?: string
+
+  /**
+   * The province.
+   */
   province?: string
+
+  /**
+   * The postal code.
+   */
   postal_code?: string
+
+  /**
+   * The phone.
+   */
   phone?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The customer to be created.
+ */
 export interface CreateCustomerDTO {
+  /**
+   * The company name of the customer.
+   */
   company_name?: string
+
+  /**
+   * The first name of the customer.
+   */
   first_name?: string
+
+  /**
+   * The last name of the customer.
+   */
   last_name?: string
+
+  /**
+   * The email of the customer.
+   */
   email?: string
+
+  /**
+   * The phone of the customer.
+   */
   phone?: string
+
+  /**
+   * Who created the customer.
+   */
   created_by?: string
+
+  /**
+   * The addresses of the customer.
+   */
   addresses?: Omit<CreateCustomerAddressDTO, "customer_id">[]
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The attributes to update in the customer.
+ */
 export interface UpdateCustomerDTO {
+  /**
+   * The ID of the customer.
+   */
   id: string
+
+  /**
+   * The company name of the customer.
+   */
   company_name?: string | null
+
+  /**
+   * The first name of the customer.
+   */
   first_name?: string | null
+
+  /**
+   * The last name of the customer.
+   */
   last_name?: string | null
+
+  /**
+   * The email of the customer.
+   */
   email?: string | null
+
+  /**
+   * The phone of the customer.
+   */
   phone?: string | null
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The updatable fields of a customer.
+ */
 export interface CustomerUpdatableFields {
+  /**
+   * The company name of the customer.
+   */
   company_name?: string | null
+
+  /**
+   * The first name of the customer.
+   */
   first_name?: string | null
+
+  /**
+   * The last name of the customer.
+   */
   last_name?: string | null
+
+  /**
+   * The email of the customer.
+   */
   email?: string | null
+
+  /**
+   * The phone of the customer.
+   */
   phone?: string | null
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The customer group to be created.
+ */
 export interface CreateCustomerGroupDTO {
+  /**
+   * The name of the customer group.
+   */
   name: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
+
+  /**
+   * Who the customer group.
+   */
   created_by?: string
 }
 
+/**
+ * The updatable fields of a customer group.
+ */
 export interface CustomerGroupUpdatableFields {
+  /**
+   * The name of the customer group.
+   */
   name?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The attributes to update in the customer group.
+ */
 export interface UpdateCustomerGroupDTO {
+  /**
+   * The ID of the customer group.
+   */
   id?: string
+
+  /**
+   * The name of the customer group.
+   */
   name?: string
+
+  /**
+   * The IDs of associated customers.
+   */
   customer_ids?: string[]
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The customer group to be created.
+ */
 export interface CreateCustomerGroupDTO {
+  /**
+   * The name of the customer group.
+   */
   name: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
+
+  /**
+   * Who created the customer group.
+   */
   created_by?: string
 }
 
-export interface CustomerGroupUpdatableFileds {
+/**
-  name?: string
+ * The attributes to update in the customer group.
-  metadata?: Record<string, unknown> | null
+ */
-}
-
 export interface UpdateCustomerGroupDTO {
+  /**
+   * The ID of the customer group.
+   */
   id?: string
+
+  /**
+   * The name of the customer group.
+   */
   name?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }

packages/types/src/customer/service.ts

@@ -22,203 +22,827 @@ import {
   UpdateCustomerAddressDTO,
 } from "./mutations"
 
+/**
+ * The main service interface for the customer module.
+ */
 export interface ICustomerModuleService extends IModuleService {
+  /**
+   * This method retrieves a customer by its ID.
+   *
+   * @param {string} customerId - The customer's ID.
+   * @param {FindConfig<CustomerDTO>} config - The configurations determining how the customer is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO>} The retrieved customer.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieve(
     customerId: string,
     config?: FindConfig<CustomerDTO>,
     sharedContext?: Context
   ): Promise<CustomerDTO>
 
+  /**
+   * This method creates customers
+   *
+   * @param {CreateCustomerDTO[]} data - The customers to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO[]>} The created customers.
+   *
+   * @example
+   * {example-code}
+   */
   create(
     data: CreateCustomerDTO[],
     sharedContext?: Context
   ): Promise<CustomerDTO[]>
+
+  /**
+   * This method creates customer
+   *
+   * @param {CreateCustomerDTO} data - The customer to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO>} The created customer.
+   *
+   * @example
+   * {example-code}
+   */
   create(data: CreateCustomerDTO, sharedContext?: Context): Promise<CustomerDTO>
 
+  /**
+   * This method updates existing customer.
+   *
+   * @param {string} customerId - The customer's ID.
+   * @param {CustomerUpdatableFields} data - The details to update in the customer.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO>} The updated customer.
+   *
+   * @example
+   * {example-code}
+   */
   update(
     customerId: string,
     data: CustomerUpdatableFields,
     sharedContext?: Context
   ): Promise<CustomerDTO>
+
+  /**
+   * This method updates existing customers.
+   *
+   * @param {string[]} customerIds - The list of customer ID's to update.
+   * @param {CustomerUpdatableFields} data - The details to update in the customers.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO[]>} The updated customers.
+   *
+   * @example
+   * {example-code}
+   */
   update(
     customerIds: string[],
     data: CustomerUpdatableFields,
     sharedContext?: Context
   ): Promise<CustomerDTO[]>
+
+  /**
+   * This method updates existing customers. Updated customers are selected based on the filters provided in the `selector` parameter.
+   *
+   * @param {FilterableCustomerProps} selector - The filters to specify which customers should be updated.
+   * @param {CustomerUpdatableFields} data - The details to update in the customers.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO[]>} The updated customers.
+   *
+   * @example
+   * {example-code}
+   */
   update(
     selector: FilterableCustomerProps,
     data: CustomerUpdatableFields,
     sharedContext?: Context
   ): Promise<CustomerDTO[]>
 
+  /**
+   * This method deletes a customer by its ID.
+   *
+   * @param {string} customerId - The customer's ID.
+   * @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 customer is deleted successfully.
+   *
+   * @example
+   * {example-code}
+   */
   delete(customerId: string, sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes customers by their IDs.
+   *
+   * @param {string[]} customerIds - The list of IDs of customers to delete.
+   * @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 customers are deleted successfully.
+   *
+   * @example
+   * {example-code}
+   */
   delete(customerIds: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes customers matching the specified filters in the `selector` parameter.
+   *
+   * @param {FilterableCustomerProps} selector - The filters to specify which customers should be deleted.
+   * @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 customers are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   delete(
     selector: FilterableCustomerProps,
     sharedContext?: Context
   ): Promise<void>
 
-  // TODO should be pluralized
+  /**
+   * This method creates customer groups.
+   *
+   * @param {CreateCustomerGroupDTO[]} data - The details of the customer groups to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO[]>} The created customer groups.
+   *
+   *
+   * @privateRemarks
+   * TODO should be pluralized
+   */
   createCustomerGroup(
     data: CreateCustomerGroupDTO[],
     sharedContext?: Context
   ): Promise<CustomerGroupDTO[]>
 
-  // TODO should be pluralized
+  /**
+   * This method creates a customer group.
+   *
+   * @param {CreateCustomerGroupDTO} data - The details of the customer group to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO>} The created customer group.
+   *
+   * @privateRemarks
+   * TODO should be pluralized
+   */
   createCustomerGroup(
     data: CreateCustomerGroupDTO,
     sharedContext?: Context
   ): Promise<CustomerGroupDTO>
 
+  /**
+   * This method retrieves a customer group by its ID.
+   *
+   * @param {string} groupId - The group's ID.
+   * @param {FindConfig<CustomerGroupDTO>} config - The configurations determining how the customer group is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer group.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO>} The retrieved customer group(s).
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieveCustomerGroup(
     groupId: string,
     config?: FindConfig<CustomerGroupDTO>,
     sharedContext?: Context
   ): Promise<CustomerGroupDTO>
 
+  /**
+   * This method updates existing customer group.
+   *
+   * @param {string} groupId - The group's ID.
+   * @param {CustomerGroupUpdatableFields} data - The details to update in the customer group.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO>} The updated customer group.
+   *
+   * @example
+   * {example-code}
+   */
   updateCustomerGroups(
     groupId: string,
     data: CustomerGroupUpdatableFields,
     sharedContext?: Context
   ): Promise<CustomerGroupDTO>
 
+  /**
+   * This method updates existing customer groups.
+   *
+   * @param {string[]} groupIds - The list of customer groups IDs to update.
+   * @param {CustomerGroupUpdatableFields} data - The details to update in the customer groups.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO[]>} The updated customer groups.
+   *
+   * @example
+   * {example-code}
+   */
   updateCustomerGroups(
     groupIds: string[],
     data: CustomerGroupUpdatableFields,
     sharedContext?: Context
   ): Promise<CustomerGroupDTO[]>
 
+  /**
+   * This method updates existing customer groups. Updated groups are selected based on the filters provided in the `selector` parameter.
+   *
+   * @param {FilterableCustomerGroupProps} selector - The filters to specify which groups should be updated.
+   * @param {CustomerGroupUpdatableFields} data - The details to update in the customer groups.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO[]>} The updated customer groups.
+   *
+   * @example
+   * {example-code}
+   */
   updateCustomerGroups(
     selector: FilterableCustomerGroupProps,
     data: CustomerGroupUpdatableFields,
     sharedContext?: Context
   ): Promise<CustomerGroupDTO[]>
 
+  /**
+   * This method deletes a customer group by its ID.
+   *
+   * @param {string} groupId - The group's ID.
+   * @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 customer group is deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deleteCustomerGroups(groupId: string, sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes customer groups by their ID.
+   *
+   * @param {string[]} groupIds - The list of IDs of customer groups to delete.
+   * @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 customer groups are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deleteCustomerGroups(
     groupIds: string[],
     sharedContext?: Context
   ): Promise<void>
+
+  /**
+   * This method deletes customer groups matching the specified filters in the `selector` parameter.
+   *
+   * @param {FilterableCustomerGroupProps} selector - The filters to specify which groups should be deleted.
+   * @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 customer groups are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deleteCustomerGroups(
     selector: FilterableCustomerGroupProps,
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method adds customers to a group.
+   *
+   * @param {GroupCustomerPair} groupCustomerPair - The details of the customer and the group it should be added to.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<{ id: string; }>} The ID of the relation between the customer and the group.
+   *
+   * @example
+   * {example-code}
+   */
   addCustomerToGroup(
     groupCustomerPair: GroupCustomerPair,
     sharedContext?: Context
-  ): Promise<{ id: string }>
+  ): Promise<{
+    /**
+     * The ID of the relation between the customer and the group.
+     */
+    id: string
+  }>
 
+  /**
+   * This method adds customers to groups.
+   *
+   * @param {GroupCustomerPair[]} groupCustomerPairs - A list of customer-group pairs, where each item in the list indicates the customer and what
+   * group it should be added to.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<{ id: string; }[]>} The list of IDs of the relations created between the customers and the groups.
+   *
+   * @example
+   * {example-code}
+   */
   addCustomerToGroup(
     groupCustomerPairs: GroupCustomerPair[],
     sharedContext?: Context
-  ): Promise<{ id: string }[]>
+  ): Promise<
+    {
+      /**
+       * The ID of the relation between the customer and the group.
+       */
+      id: string
+    }[]
+  >
 
-  // TODO should be pluralized
+  /**
+   * This method removes a customer from a group.
+   *
+   * @param {GroupCustomerPair} groupCustomerPair - The details of the customer and which group to remove it from.
+   * @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 customer is removed from the group successfully.
+   *
+   * @privateRemarks
+   * TODO should be pluralized
+   */
   removeCustomerFromGroup(
     groupCustomerPair: GroupCustomerPair,
     sharedContext?: Context
   ): Promise<void>
 
-  // TODO should be pluralized
+  /**
+   * This method removes customers from groups.
+   *
+   * @param {GroupCustomerPair[]} groupCustomerPairs - A list of customer-group pairs, where each item in the list indicates the customer and what
+   * group it should be removed from.
+   * @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 customers are removed from the groups successfully.
+   *
+   * @privateRemarks
+   * TODO should be pluralized
+   */
   removeCustomerFromGroup(
     groupCustomerPairs: GroupCustomerPair[],
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method adds addresses to a customer.
+   *
+   * @param {CreateCustomerAddressDTO[]} addresses - The customer addresses to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerAddressDTO[]>} The created customer addresses.
+   *
+   * @example
+   * {example-code}
+   */
   addAddresses(
     addresses: CreateCustomerAddressDTO[],
     sharedContext?: Context
   ): Promise<CustomerAddressDTO[]>
+
+  /**
+   * This method adds an address to a customer
+   *
+   * @param {CreateCustomerAddressDTO} address - The customer address to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerAddressDTO>} The created customer address.
+   *
+   * @example
+   * {example-code}
+   */
   addAddresses(
     address: CreateCustomerAddressDTO,
     sharedContext?: Context
   ): Promise<CustomerAddressDTO>
 
+  /**
+   * This method updates an existing address by its ID.
+   *
+   * @param {string} addressId - The address's ID.
+   * @param {UpdateCustomerAddressDTO} data - The attributes to update in the customer address.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerAddressDTO>} The updated addresses.
+   *
+   * @example
+   * {example-code}
+   */
   updateAddresses(
     addressId: string,
     data: UpdateCustomerAddressDTO,
     sharedContext?: Context
   ): Promise<CustomerAddressDTO>
+
+  /**
+   * This method updates existing addresses.
+   *
+   * @param {string[]} addressIds - The list of IDs of addresses to update.
+   * @param {UpdateCustomerAddressDTO} data - The attributes to update in each customer address.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerAddressDTO[]>} The updated customer addresses.
+   *
+   * @example
+   * {example-code}
+   */
   updateAddresses(
     addressIds: string[],
     data: UpdateCustomerAddressDTO,
     sharedContext?: Context
   ): Promise<CustomerAddressDTO[]>
 
+  /**
+   * This method updates addresses matching the specified filters in the `selector` parameter.
+   *
+   * @param {FilterableCustomerAddressProps} selector - The filters to specify which addresses should be updated.
+   * @param {UpdateCustomerAddressDTO} data - The attributes to update in each customer address.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerAddressDTO[]>} The updated customer addresses.
+   *
+   * @example
+   * {example-code}
+   */
   updateAddresses(
     selector: FilterableCustomerAddressProps,
     data: UpdateCustomerAddressDTO,
     sharedContext?: Context
   ): Promise<CustomerAddressDTO[]>
 
+  /**
+   * This method deletes an address by its ID.
+   *
+   * @param {string} addressId - The address's ID.
+   * @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 address is deleted successfully.
+   *
+   * @example
+   * {example-code}
+   */
   deleteAddresses(addressId: string, sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes addresses by their IDs.
+   *
+   * @param {string[]} addressIds - The list of IDs of addresses to delete.
+   * @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 addresses are deleted successfully.
+   *
+   * @example
+   * {example-code}
+   */
   deleteAddresses(addressIds: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes addresses matching the specified filters in the `selector` parameter.
+   *
+   * @param {FilterableCustomerAddressProps} selector - The filters to specify which addresses should be deleted.
+   * @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 addresses are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deleteAddresses(
     selector: FilterableCustomerAddressProps,
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method retrieves a paginated list of addresses based on optional filters and configuration.
+   *
+   * @param {FilterableCustomerAddressProps} filters - The filters to apply on the retrieved customer address.
+   * @param {FindConfig<CustomerAddressDTO>} config - The configurations determining how the customer address is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer address.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerAddressDTO[]>} The list of addresses.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listAddresses(
     filters?: FilterableCustomerAddressProps,
     config?: FindConfig<CustomerAddressDTO>,
     sharedContext?: Context
   ): Promise<CustomerAddressDTO[]>
 
+  /**
+   * This method retrieves a paginated list of addresses along with the total count of available addresses satisfying the provided filters.
+   *
+   * @param {FilterableCustomerAddressProps} filters - The filters to apply on the retrieved customer address.
+   * @param {FindConfig<CustomerAddressDTO>} config - The configurations determining how the customer address is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer address.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[CustomerAddressDTO[], number]>} The list of addresses along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listAndCountAddresses(
     filters?: FilterableCustomerAddressProps,
     config?: FindConfig<CustomerAddressDTO>,
     sharedContext?: Context
   ): Promise<[CustomerAddressDTO[], number]>
 
+  /**
+   * This method retrieves a paginated list of customer group's customers based on optional filters and configuration.
+   *
+   * @param {FilterableCustomerGroupCustomerProps} filters - The filters to apply on the retrieved customer group customer.
+   * @param {FindConfig<CustomerGroupCustomerDTO>} config - The configurations determining how the customer group customer is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer group customer.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupCustomerDTO[]>} The list of customer group's customers.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listCustomerGroupCustomers(
     filters?: FilterableCustomerGroupCustomerProps,
     config?: FindConfig<CustomerGroupCustomerDTO>,
     sharedContext?: Context
   ): Promise<CustomerGroupCustomerDTO[]>
 
+  /**
+   * This method retrieves a paginated list of customers based on optional filters and configuration.
+   *
+   * @param {FilterableCustomerProps} filters - The filters to apply on the retrieved customer.
+   * @param {FindConfig<CustomerDTO>} config - The configurations determining how the customer is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerDTO[]>} The list of customers.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableCustomerProps,
     config?: FindConfig<CustomerDTO>,
     sharedContext?: Context
   ): Promise<CustomerDTO[]>
 
+  /**
+   * This method retrieves a paginated list of customers along with the total count of available customers satisfying the provided filters.
+   *
+   * @param {FilterableCustomerProps} filters - The filters to apply on the retrieved customer.
+   * @param {FindConfig<CustomerDTO>} config - The configurations determining how the customer is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[CustomerDTO[], number]>} The list of customers along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableCustomerProps,
     config?: FindConfig<CustomerDTO>,
     sharedContext?: Context
   ): Promise<[CustomerDTO[], number]>
 
+  /**
+   * This method retrieves a paginated list of customer groups based on optional filters and configuration.
+   *
+   * @param {FilterableCustomerGroupProps} filters - The filters to apply on the retrieved customer group.
+   * @param {FindConfig<CustomerGroupDTO>} config - The configurations determining how the customer group is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer group.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<CustomerGroupDTO[]>} The list of customer groups.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listCustomerGroups(
     filters?: FilterableCustomerGroupProps,
     config?: FindConfig<CustomerGroupDTO>,
     sharedContext?: Context
   ): Promise<CustomerGroupDTO[]>
 
+  /**
+   * This method retrieves a paginated list of customer groups along with the total count of available customer groups satisfying the provided filters.
+   *
+   * @param {FilterableCustomerGroupProps} filters - The filters to apply on the retrieved customer group.
+   * @param {FindConfig<CustomerGroupDTO>} config - The configurations determining how the customer group is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a customer group.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[CustomerGroupDTO[], number]>} The list of customer groups along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listAndCountCustomerGroups(
     filters?: FilterableCustomerGroupProps,
     config?: FindConfig<CustomerGroupDTO>,
     sharedContext?: Context
   ): Promise<[CustomerGroupDTO[], number]>
 
+  /**
+   * This method soft deletes customers by their IDs.
+   *
+   * @param {string[]} customerIds - The list of IDs of customers to soft delete.
+   * @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<TReturnableLinkableKeys, string[]>>} Resolves when the customers are deleted successfully.
+   *
+   * @example
+   * {example-code}
+   */
   softDelete<TReturnableLinkableKeys extends string = string>(
     customerIds: string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
 
+  /**
+   * This method restores soft deleted customers by their IDs.
+   *
+   * @param {string[]} customerIds - The list of IDs of customers to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the customers. You can pass to its `returnLinkableKeys`
+   * property any of the customer's relation attribute names, such as `addresses`.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored, such as the ID of associated address.
+   * The object's keys are the ID attribute names of the customer entity's relations,
+   * and its value is an array of strings, each being the ID of the record associated with the customer through this relation,
+   * such as the IDs of associated addresses.
+   *
+   * @example
+   * {example-code}
+   */
   restore<TReturnableLinkableKeys extends string = string>(
     customerIds: string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
 
+  /**
+   * This method soft deletes customer groups by their IDs.
+   *
+   * @param {string[]} groupIds - The list of IDs of customer groups to soft delete.
+   * @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<TReturnableLinkableKeys, string[]>>} Resolves whe the customer groups are soft-deleted successfully.
+   *
+   * @example
+   * {example-code}
+   */
   softDeleteCustomerGroups<TReturnableLinkableKeys extends string = string>(
     groupIds: string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
 
+  /**
+   * This method restores soft deleted customer groups by their IDs.
+   *
+   * @param {string[]} groupIds - The list of IDs of customer groups to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the customer group. You can pass to its `returnLinkableKeys`
+   * property any of the customer group's relation attribute names, such as `customers`.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored, such as the ID of associated customer.
+   * The object's keys are the ID attribute names of the customer group entity's relations,
+   * and its value is an array of strings, each being the ID of the record associated with the customer through this relation,
+   * such as the IDs of associated customer.
+   *
+   * @example
+   * {example-code}
+   */
   restoreCustomerGroups<TReturnableLinkableKeys extends string = string>(
     groupIds: string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,

packages/types/src/dal/index.ts

@@ -12,24 +12,61 @@ export interface BaseFilterable<T> {
    * An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.
    */
   $and?: (T | BaseFilterable<T>)[]
+
   /**
    * An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.
    */
   $or?: (T | BaseFilterable<T>)[]
 }
 
+/**
+ * The options to apply when retrieving an item.
+ */
 export interface OptionsQuery<T, P extends string = never> {
+  /**
+   * Relations to populate in the retrieved items.
+   */
   populate?: string[]
+  /**
+   * Fields to sort-order items by.
+   */
   orderBy?: Order<T> | Order<T>[]
+  /**
+   * Limit the number of items retrieved in the list.
+   */
   limit?: number
+  /**
+   * The number of items to skip before the retrieved items in the list.
+   */
   offset?: number
+  /**
+   * The fields to include in each of the items.
+   */
   fields?: string[]
+  /**
+   * Group results by a field or set of fields.
+   */
   groupBy?: string | string[]
+  /**
+   * Filters to apply on the retrieved items.
+   */
   filters?: Dictionary<boolean | Dictionary> | string[] | boolean
 }
 
+/**
+ * @interface
+ *
+ * An object used to specify filters and options on a list of items.
+ */
 export type FindOptions<T = any> = {
+  /**
+   * The filters to apply on the items.
+   */
   where: FilterQuery<T> & BaseFilterable<FilterQuery<T>>
+
+  /**
+   * The options to apply when retrieving the items.
+   */
   options?: OptionsQuery<T, any>
 }
 

packages/types/src/inventory/service.ts

@@ -17,6 +17,9 @@ import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 import { SharedContext } from "../shared-context"
 
+/**
+ * The main service interface for the inventory module.
+ */
 export interface IInventoryService extends IModuleService {
   /**
    * This method is used to retrieve a paginated list of inventory items along with the total count of available inventory items satisfying the provided filters.

packages/types/src/payment/common.ts

@@ -2,7 +2,6 @@ import { BaseFilterable } from "../dal"
 import { OperatorMap } from "../dal/utils"
 
 /* ********** PAYMENT COLLECTION ********** */
-
 /**
  * @enum
  *
@@ -13,18 +12,22 @@ export enum PaymentCollectionStatus {
    * The payment collection isn't paid.
    */
   NOT_PAID = "not_paid",
+
   /**
    * The payment collection is awaiting payment.
    */
   AWAITING = "awaiting",
+
   /**
    * The payment collection is authorized.
    */
   AUTHORIZED = "authorized",
+
   /**
    * Some of the payments in the payment collection are authorized.
    */
   PARTIALLY_AUTHORIZED = "partially_authorized",
+
   /**
    * The payment collection is canceled.
    */
@@ -59,6 +62,9 @@ export enum PaymentSessionStatus {
   CANCELED = "canceled",
 }
 
+/**
+ * The payment collection details.
+ */
 export interface PaymentCollectionDTO {
   /**
    * The ID of the Payment Collection
@@ -69,6 +75,7 @@ export interface PaymentCollectionDTO {
    * The currency of the payments/sessions associated with payment collection
    */
   currency_code: string
+
   /**
    * The id of the region
    */
@@ -136,18 +143,33 @@ export interface PaymentCollectionDTO {
   payments?: PaymentDTO[]
 }
 
+/**
+ * The filters to apply on the retrieved payment collection.
+ */
 export interface FilterablePaymentCollectionProps
   extends BaseFilterable<PaymentCollectionDTO> {
+  /**
+   * The IDs to filter the payment collection by.
+   */
   id?: string | string[]
 
+  /**
+   * Filter by associated region's ID.
+   */
   region_id?: string | string[] | OperatorMap<string>
 
+  /**
+   * Filter payment collections by created date.
+   */
   created_at?: OperatorMap<string>
+
+  /**
+   * Filter payment collections by updated date.
+   */
   updated_at?: OperatorMap<string>
 }
 
 /* ********** PAYMENT ********** */
-
 export interface PaymentDTO {
   /**
    * The ID of the Payment
@@ -159,6 +181,9 @@ export interface PaymentDTO {
    */
   amount: number
 
+  /**
+   * The authorized amount of the payment.
+   */
   authorized_amount?: number
 
   /**
@@ -171,9 +196,24 @@ export interface PaymentDTO {
    */
   provider_id: string
 
+  /**
+   * The associated cart's ID.
+   */
   cart_id?: string
+
+  /**
+   * The associated order's ID.
+   */
   order_id?: string
+
+  /**
+   * The associated order edit's ID.
+   */
   order_edit_id?: string
+
+  /**
+   * The associated customer's ID.
+   */
   customer_id?: string
 
   /**
@@ -240,6 +280,9 @@ export interface PaymentDTO {
   payment_session?: PaymentSessionDTO
 }
 
+/**
+ * The capture details.
+ */
 export interface CaptureDTO {
   /**
    * The ID of the Capture
@@ -251,13 +294,25 @@ export interface CaptureDTO {
    */
   amount: number
 
+  /**
+   * The creation date of the capture.
+   */
   created_at: Date
 
+  /**
+   * Who the capture was created by.
+   */
   created_by?: string
 
+  /**
+   * The associated payment.
+   */
   payment: PaymentDTO
 }
 
+/**
+ * The refund details.
+ */
 export interface RefundDTO {
   /**
    * The ID of the Refund
@@ -269,15 +324,23 @@ export interface RefundDTO {
    */
   amount: number
 
+  /**
+   * The creation date of the refund.
+   */
   created_at: Date
 
+  /**
+   * Who created the refund.
+   */
   created_by?: string
 
+  /**
+   * The associated payment.
+   */
   payment: PaymentDTO
 }
 
 /* ********** PAYMENT ********** */
-
 export interface PaymentSessionDTO {
   /**
    * The ID of the Payment Session
@@ -327,7 +390,17 @@ export interface PaymentSessionDTO {
   payment?: PaymentDTO
 }
 
+/**
+ * The payment provider details.
+ */
 export interface PaymentProviderDTO {
+  /**
+   * The ID of the payment provider.
+   */
   id: string
+
+  /**
+   * Whether the payment provider is enabled.
+   */
   is_enabled: string
 }

packages/types/src/payment/mutations.ts

@@ -2,86 +2,219 @@ import { PaymentCollectionStatus } from "./common"
 import { PaymentProviderContext } from "./provider"
 
 /**
- * Payment Collection
+ * The payment collection to be created.
  */
 export interface CreatePaymentCollectionDTO {
+  /**
+   * The associated region's ID.
+   */
   region_id: string
+
+  /**
+   * The currency code of the payment collection.
+   */
   currency_code: string
+
+  /**
+   * The amount of the payment collection.
+   */
   amount: number
 
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The attributes to update in the payment collection.
+ */
 export interface UpdatePaymentCollectionDTO
   extends Partial<CreatePaymentCollectionDTO> {
+  /**
+   * The ID of the payment collection.
+   */
   id: string
 
+  /**
+   * The authorized amount of the payment collection.
+   */
   authorized_amount?: number
+
+  /**
+   * The refunded amount of the payment collection.
+   */
   refunded_amount?: number
+
+  /**
+   * The status of the payment collection.
+   */
   status?: PaymentCollectionStatus
 }
 
 /**
- * Payment
+ * The payment to be created.
  */
-
 export interface CreatePaymentDTO {
+  /**
+   * The amount of the payment.
+   */
   amount: number
 
+  /**
+   * The currency code of the payment.
+   */
   currency_code: string
+
+  /**
+   * The associated provider's ID.
+   */
   provider_id: string
+
+  /**
+   * The data of the payment.
+   */
   data: Record<string, unknown>
 
+  /**
+   * The associated payment session's ID.
+   */
   payment_session_id: string
+
+  /**
+   * The associated payment collection's ID.
+   */
   payment_collection_id: string
 
+  /**
+   * The associated cart's ID.
+   */
   cart_id?: string
+
+  /**
+   * The associated order's ID.
+   */
   order_id?: string
+
+  /**
+   * The associated order edit's ID.
+   */
   order_edit_id?: string
+
+  /**
+   * The associated customer's ID.
+   */
   customer_id?: string
 }
 
+/**
+ * The attributes to update in the payment.
+ */
 export interface UpdatePaymentDTO {
+  /**
+   * The ID of the payment.
+   */
   id: string
 
+  /**
+   * The associated cart's ID.
+   */
   cart_id?: string
+
+  /**
+   * The associated order's ID.
+   */
   order_id?: string
+
+  /**
+   * The associated order edit's ID.
+   */
   order_edit_id?: string
+
+  /**
+   * The associated customer's ID.
+   */
   customer_id?: string
 }
 
+/**
+ * The capture to be created.
+ */
 export interface CreateCaptureDTO {
+  /**
+   * The amount of the capture.
+   */
   amount: number
+
+  /**
+   * The associated payment's ID.
+   */
   payment_id: string
 
+  /**
+   * The captured by of the capture.
+   */
   captured_by?: string
 }
 
+/**
+ * The refund to be created.
+ */
 export interface CreateRefundDTO {
+  /**
+   * The amount of the refund.
+   */
   amount: number
+
+  /**
+   * The associated payment's ID.
+   */
   payment_id: string
 
+  /**
+   * The created by of the refund.
+   */
   created_by?: string
 }
 
 /**
- * Payment Session
+ * The payment session to be created.
  */
-
 export interface CreatePaymentSessionDTO {
+  /**
+   * The provider's ID.
+   */
   provider_id: string
-  providerContext: PaymentProviderContext
+  /**
-}
+   * The provider's context.
-
+   */
-export interface UpdatePaymentSessionDTO {
-  id: string
   providerContext: PaymentProviderContext
 }
 
 /**
- * Payment Provider
+ * The attributes to update in a payment session.
+ */
+export interface UpdatePaymentSessionDTO {
+  /**
+   * The payment session's ID.
+   */
+  id: string
+  /**
+   * The payment session's context.
+   */
+  providerContext: PaymentProviderContext
+}
+
+/**
+ * The payment provider to be created.
  */
 export interface CreatePaymentProviderDTO {
+  /**
+   * The provider's ID.
+   */
   id: string
+  /**
+   * Whether the provider is enabled.
+   */
   is_enabled?: boolean
 }

packages/types/src/payment/service.ts

@@ -18,58 +18,229 @@ import {
 } from "./common"
 import { FindConfig } from "../common"
 
+/**
+ * The main service interface for the payment module.
+ */
 export interface IPaymentModuleService extends IModuleService {
   /* ********** PAYMENT COLLECTION ********** */
 
+  /**
+   * This method creates payment collections.
+   *
+   * @param {CreatePaymentCollectionDTO[]} data - The payment collections to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO[]>} The created payment collections.
+   *
+   * @example
+   * {example-code}
+   */
   createPaymentCollections(
     data: CreatePaymentCollectionDTO[],
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO[]>
+
+  /**
+   * This method creates a payment collection.
+   *
+   * @param {CreatePaymentCollectionDTO} data - The payment collection to create.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO>} The created payment collection.
+   *
+   * @example
+   * {example-code}
+   */
   createPaymentCollections(
     data: CreatePaymentCollectionDTO,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO>
 
+  /**
+   * This method retrieves a payment collection by its ID.
+   *
+   * @param {string} paymentCollectionId - The payment collection's ID.
+   * @param {FindConfig<PaymentCollectionDTO>} config - The configurations determining how the payment collection is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a payment collection.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO>} The retrieved payment collection.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrievePaymentCollection(
     paymentCollectionId: string,
     config?: FindConfig<PaymentCollectionDTO>,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO>
 
+  /**
+   * This method retrieves a paginated list of payment collections based on optional filters and configuration.
+   *
+   * @param {FilterablePaymentCollectionProps} filters - The filters to apply on the retrieved payment collection.
+   * @param {FindConfig<PaymentCollectionDTO>} config - The configurations determining how the payment collection is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a payment collection.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO[]>} The list of payment collections.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listPaymentCollections(
     filters?: FilterablePaymentCollectionProps,
     config?: FindConfig<PaymentCollectionDTO>,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO[]>
 
+  /**
+   * This method retrieves a paginated list of payment collections along with the total count of available payment collections satisfying the provided filters.
+   *
+   * @param {FilterablePaymentCollectionProps} filters - The filters to apply on the retrieved payment collection.
+   * @param {FindConfig<PaymentCollectionDTO>} config - The configurations determining how the payment collection is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a payment collection.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[PaymentCollectionDTO[], number]>} The list of payment collections along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listAndCountPaymentCollections(
     filters?: FilterablePaymentCollectionProps,
     config?: FindConfig<PaymentCollectionDTO>,
     sharedContext?: Context
   ): Promise<[PaymentCollectionDTO[], number]>
 
+  /**
+   * This method updates existing payment collections.
+   *
+   * @param {UpdatePaymentCollectionDTO[]} data - The attributes to update in payment collections.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO[]>} The updated payment collections.
+   *
+   * @example
+   * {example-code}
+   */
   updatePaymentCollections(
     data: UpdatePaymentCollectionDTO[],
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO[]>
+
+  /**
+   * This method updates an existing payment collection.
+   *
+   * @param {UpdatePaymentCollectionDTO} data - The attributes to update in a payment collection.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO[]>} The updated payment collection.
+   *
+   * @example
+   * {example-code}
+   */
   updatePaymentCollections(
     data: UpdatePaymentCollectionDTO,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO>
 
+  /**
+   * This method deletes a payment collection by its ID.
+   *
+   * @param {string[]} paymentCollectionId - The payment collection's ID.
+   * @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 payment collection is deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deletePaymentCollections(
     paymentCollectionId: string[],
     sharedContext?: Context
   ): Promise<void>
+
+  /**
+   * This method deletes a payment collection by its ID.
+   *
+   * @param {string} paymentCollectionId - The payment collection's ID.
+   * @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 payment collection is deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deletePaymentCollections(
     paymentCollectionId: string,
     sharedContext?: Context
   ): Promise<void>
 
+  /**
+   * This method completes a payment collection.
+   *
+   * @param {string} paymentCollectionId - The payment collection's ID.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO>} The payment collection's details.
+   *
+   * @example
+   * {example-code}
+   */
   completePaymentCollections(
     paymentCollectionId: string,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO>
+
+  /**
+   * This method completes payment collections.
+   *
+   * @param {string[]} paymentCollectionId - The payment collections' IDs.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO[]>} The payment collections' details.
+   *
+   * @example
+   * {example-code}
+   */
   completePaymentCollections(
     paymentCollectionId: string[],
     sharedContext?: Context
@@ -77,19 +248,61 @@ export interface IPaymentModuleService extends IModuleService {
 
   /* ********** PAYMENT SESSION ********** */
 
+  /**
+   * This method creates a payment session for a payment collection.
+   *
+   * @param {string} paymentCollectionId - The ID of the payment collection to create the session for.
+   * @param {CreatePaymentSessionDTO} data - The details of the payment session.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentCollectionDTO>} The payment collection's details.
+   *
+   * @example
+   * {example-code}
+   */
   createPaymentSession(
     paymentCollectionId: string,
     data: CreatePaymentSessionDTO,
     sharedContext?: Context
   ): Promise<PaymentSessionDTO>
 
+  /**
+   * This method updates a payment session.
+   *
+   * @param {UpdatePaymentSessionDTO} data - The attributes to update in the payment session.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentSessionDTO>} The payment session's details.
+   *
+   * @example
+   * {example-code}
+   */
   updatePaymentSession(
     data: UpdatePaymentSessionDTO,
     sharedContext?: Context
   ): Promise<PaymentSessionDTO>
 
+  /**
+   * This method deletes a payment session.
+   *
+   * @param {string} id - The ID of the payment session.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void>} Resolves whent the payment session is deleted.
+   *
+   * @example
+   * {example-code}
+   */
   deletePaymentSession(id: string, sharedContext?: Context): Promise<void>
 
+  /**
+   * This method authorizes a payment session.
+   *
+   * @param {string} id - The payment session's ID.
+   * @param {Record<string, unknown>} context - The associated payment provider's context.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentDTO>} The details of the payment created from the authorized payment session.
+   *
+   * @example
+   * {example-code}
+   */
   authorizePaymentSession(
     id: string,
     context: Record<string, unknown>,
@@ -98,22 +311,68 @@ export interface IPaymentModuleService extends IModuleService {
 
   /* ********** PAYMENT ********** */
 
+  /**
+   * This method updates an existing payment.
+   *
+   * @param {UpdatePaymentDTO} data - The attributes to update in the payment.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentDTO>} The updated payment.
+   *
+   * @example
+   * {example-code}
+   */
   updatePayment(
     data: UpdatePaymentDTO,
     sharedContext?: Context
   ): Promise<PaymentDTO>
 
+  /**
+   * This method captures a payment.
+   *
+   * @param {CreateCaptureDTO} data - The payment capture to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentDTO>} The payment's details.
+   *
+   * @example
+   * {example-code}
+   */
   capturePayment(
     data: CreateCaptureDTO,
     sharedContext?: Context
   ): Promise<PaymentDTO>
 
+  /**
+   * This method refunds a payment.
+   *
+   * @param {CreateRefundDTO} data - The refund to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentDTO>} The payment's details.
+   *
+   * @example
+   * {example-code}
+   */
   refundPayment(
     data: CreateRefundDTO,
     sharedContext?: Context
   ): Promise<PaymentDTO>
 
+  /**
+   * This method cancels a payment
+   *
+   * @param {string} paymentId - The payment's ID.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentDTO>} The payment's details.
+   *
+   * @example
+   * {example-code}
+   */
   cancelPayment(paymentId: string, sharedContext?: Context): Promise<PaymentDTO>
 
+  /**
+   * This method creates providers on load.
+   *
+   * @example
+   * {example-code}
+   */
   createProvidersOnLoad(): Promise<void>
 }

packages/types/src/pricing/service.ts

@@ -49,6 +49,9 @@ import { RestoreReturn, SoftDeleteReturn } from "../dal"
 import { IModuleService } from "../modules-sdk"
 import { Context } from "../shared-context"
 
+/**
+ * The main service interface for the pricing module.
+ */
 export interface IPricingModuleService extends IModuleService {
   /**
    * This method is used to calculate prices based on the provided filters and context.

packages/types/src/product/service.ts

@@ -34,6 +34,9 @@ import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 import { Context } from "../shared-context"
 
+/**
+ * The main service interface for the product module.
+ */
 export interface IProductModuleService extends IModuleService {
   /**
    * This method is used to retrieve a product by its ID

packages/types/src/region/common.ts

@@ -1,66 +1,227 @@
 import { BaseFilterable, OperatorMap } from "../dal"
 
+/**
+ * The region details.
+ */
 export interface RegionDTO {
+  /**
+   * The ID of the region.
+   */
   id: string
+
+  /**
+   * The name of the region.
+   */
   name: string
+
+  /**
+   * The currency code of the region.
+   */
   currency_code: string
+
+  /**
+   * The associated region currency.
+   */
   currency: RegionCurrencyDTO
+
+  /**
+   * The countries of the region.
+   */
   countries: CountryDTO[]
   metadata?: Record<string, any>
   created_at: string
   updated_at: string
 }
 
+/**
+ * The country details.
+ */
 export interface CountryDTO {
+  /**
+   * The ID of the country.
+   */
   id: string
+
+  /**
+   * The ISO 2 code of the country.
+   */
   iso_2: string
+
+  /**
+   * The ISO 3 code of the country.
+   */
   iso_3: string
+
+  /**
+   * The country's code number.
+   */
   num_code: number
+
+  /**
+   * The name of the country.
+   */
   name: string
+
+  /**
+   * The display name of the country.
+   */
   display_name: string
 }
 
+/**
+ * The filters to apply on the retrieved regions.
+ */
 export interface FilterableRegionProps
   extends BaseFilterable<FilterableRegionProps> {
+  /**
+   * The IDs to filter the regions by.
+   */
   id?: string[] | string
+  /**
+   * Filter regions by their name.
+   */
   name?: string | OperatorMap<string>
+  /**
+   * Filter regions by their currency code.
+   */
   currency_code?: string | OperatorMap<string>
+  /**
+   * Filter regions by their metadata.
+   */
   metadata?: Record<string, unknown> | OperatorMap<Record<string, unknown>>
+  /**
+   * Filter regions by their creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Filter regions by their update date.
+   */
   updated_at?: OperatorMap<string>
 }
 
+/**
+ * The details of a region's country.
+ */
 export interface RegionCountryDTO {
+  /**
+   * The ID of the country.
+   */
   id: string
+
+  /**
+   * The ISO 2 code of the country.
+   */
   iso_2: string
+
+  /**
+   * The ISO 3 code of the country.
+   */
   iso_3: string
+
+  /**
+   * The code number of the country.
+   */
   num_code: number
+
+  /**
+   * The name of the country.
+   */
   name: string
+
+  /**
+   * The display name of the country.
+   */
   display_name: string
 }
 
+/**
+ * The details of a region's currency
+ */
 export interface RegionCurrencyDTO {
+  /**
+   * The code of the currency.
+   */
   code: string
+
+  /**
+   * The symbol of the currency.
+   */
   symbol: string
+
+  /**
+   * The name of the currency.
+   */
   name: string
+
+  /**
+   * The symbol native of the currency.
+   */
   symbol_native: string
 }
 
+/**
+ * The filters to apply on the retrieved region's currencies.
+ */
 export interface FilterableRegionCurrencyProps
   extends BaseFilterable<FilterableRegionCurrencyProps> {
+  /**
+   * The IDs to filter the currencies by.
+   */
   id?: string[] | string
+
+  /**
+   * Filter currencies by their code.
+   */
   code?: string[] | string
+
+  /**
+   * Filter currencies by their symbol.
+   */
   symbol?: string[] | string
+
+  /**
+   * Filter currencies by their name.
+   */
   name?: string[] | string
+
+  /**
+   * Filter currencies by their native symbol.
+   */
   symbol_native?: string[] | string
 }
 
+/**
+ * The filters to apply on the retrieved region's countries.
+ */
 export interface FilterableRegionCountryProps
   extends BaseFilterable<FilterableRegionCountryProps> {
+  /**
+   * The IDs to filter the countries by.
+   */
   id?: string[] | string
+
+  /**
+   * Filter countries by their ISO 2 code.
+   */
   iso_2?: string[] | string
+
+  /**
+   * Filter countries by their ISO 3 code.
+   */
   iso_3?: string[] | string
+
+  /**
+   * Filter countries by their code number.
+   */
   num_code?: number[] | string
+
+  /**
+   * Filter countries by their name.
+   */
   name?: string[] | string
+
+  /**
+   * Filter countries by their display name.
+   */
   display_name?: string[] | string
 }

packages/types/src/region/mutations.ts

@@ -1,21 +1,71 @@
+import { RegionCurrencyDTO } from "./common"
+
+/**
+ * The region to be created.
+ */
 export interface CreateRegionDTO {
+  /**
+   * The name of the region.
+   */
   name: string
+  /**
+   * The currency code of the region.
+   */
   currency_code: string
+  /**
+   * The region's countries.
+   */
   countries?: string[]
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The attributes to update in the region.
+ */
 export interface UpdateRegionDTO {
+  /**
+   * The ID of the region.
+   */
   id: string
+  /**
+   * The name of the region.
+   */
   name?: string
+  /**
+   * The currency code of the region.
+   */
   currency_code?: string
+  /**
+   * The region's countries.
+   */
   countries?: string[]
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The updatable fields of a region.
+ */
 export interface UpdatableRegionFields {
+  /**
+   * The name of the region.
+   */
   name?: string
+  /**
+   * The currency code of the region.
+   */
   currency_code?: string
+  /**
+   * The region's countries.
+   */
   countries?: string[]
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }

packages/types/src/region/service.ts

@@ -16,90 +16,452 @@ import {
   UpdateRegionDTO,
 } from "./mutations"
 
+/**
+ * The main service interface for the region module.
+ */
 export interface IRegionModuleService extends IModuleService {
+  /**
+   * This method creates regions.
+   *
+   * @param {CreateRegionDTO[]} data - The regions to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionDTO[]>} The created regions.
+   *
+   * @example
+   * {example-code}
+   */
   create(data: CreateRegionDTO[], sharedContext?: Context): Promise<RegionDTO[]>
+
+  /**
+   * This method creates a region.
+   *
+   * @param {CreateRegionDTO} data - The region to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionDTO>} The created region.
+   *
+   * @example
+   * {example-code}
+   */
   create(data: CreateRegionDTO, sharedContext?: Context): Promise<RegionDTO>
 
+  /**
+   * This method updates existing regions.
+   *
+   * @param {UpdateRegionDTO[]} data - The attributes to update in each region.
+   * @returns {Promise<RegionDTO[]>} The updated regions.
+   *
+   * @example
+   * {example-code}
+   */
   update(data: UpdateRegionDTO[]): Promise<RegionDTO[]>
+
+  /**
+   * This method updates existing regions.
+   *
+   * @param {FilterableRegionProps} selector - The filters to specify which regions should be updated.
+   * @param {UpdatableRegionFields} data - The details to update in the regions.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionDTO[]>} The updated regions.
+   *
+   * @example
+   * {example-code}
+   */
   update(
     selector: FilterableRegionProps,
     data: UpdatableRegionFields,
     sharedContext?: Context
   ): Promise<RegionDTO[]>
+
+  /**
+   * This method updates an existing region.
+   *
+   * @param {string} regionId - The region's ID.
+   * @param {UpdatableRegionFields} data - The details to update in the regions.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionDTO>} The updated region.
+   */
   update(
     regionId: string,
     data: UpdatableRegionFields,
     sharedContext?: Context
   ): Promise<RegionDTO>
 
+  /**
+   * This method deletes regions by their IDs.
+   *
+   * @param {string[]} ids - The list of IDs of regions to delete.
+   * @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 regions are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   delete(ids: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes a region by its ID.
+   *
+   * @param {string} id - The ID of the region.
+   * @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 region is deleted.
+   *
+   * @example
+   * {example-code}
+   */
   delete(id: string, sharedContext?: Context): Promise<void>
 
+  /**
+   * This method retrieves a region by its ID.
+   *
+   * @param {string} id - The ID of the retrieve.
+   * @param {FindConfig<RegionDTO>} config - The configurations determining how the region is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionDTO>} The retrieved region.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieve(
     id: string,
     config?: FindConfig<RegionDTO>,
     sharedContext?: Context
   ): Promise<RegionDTO>
 
+  /**
+   * This method retrieves a paginated list of regions based on optional filters and configuration.
+   *
+   * @param {FilterableRegionProps} filters - The filters to apply on the retrieved region.
+   * @param {FindConfig<RegionDTO>} config - The configurations determining how the region is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionDTO[]>} The list of regions.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableRegionProps,
     config?: FindConfig<RegionDTO>,
     sharedContext?: Context
   ): Promise<RegionDTO[]>
 
+  /**
+   * This method retrieves a paginated list of regions along with the total count of available regions satisfying the provided filters.
+   *
+   * @param {FilterableRegionProps} filters - The filters to apply on the retrieved region.
+   * @param {FindConfig<RegionDTO>} config - The configurations determining how the region is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[RegionDTO[], number]>} The list of regions along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableRegionProps,
     config?: FindConfig<RegionDTO>,
     sharedContext?: Context
   ): Promise<[RegionDTO[], number]>
 
+  /**
+   * This method retrieves a country by its ID.
+   *
+   * @param {string} countryId - The country's ID.
+   * @param {FindConfig<RegionCountryDTO>} config - The configurations determining how the region country is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region country.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionCountryDTO>} The retrieved country.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieveCountry(
     countryId: string,
     config?: FindConfig<RegionCountryDTO>,
     sharedContext?: Context
   ): Promise<RegionCountryDTO>
 
+  /**
+   * This method retrieves a paginated list of countries based on optional filters and configuration.
+   *
+   * @param {FilterableRegionCountryProps} filters - The filters to apply on the retrieved region country.
+   * @param {FindConfig<RegionCountryDTO>} config - The configurations determining how the region country is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region country.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionCountryDTO[]>} The list of countries.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listCountries(
     filters?: FilterableRegionCountryProps,
     config?: FindConfig<RegionCountryDTO>,
     sharedContext?: Context
   ): Promise<RegionCountryDTO[]>
 
+  /**
+   * This method retrieves a currency by its ID.
+   *
+   * @param {string} currencyId - The currency's ID.
+   * @param {FindConfig<RegionCountryDTO>} config - The configurations determining how the region country is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region country.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionCurrencyDTO>} The retrieved currency.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieveCurrency(
     currencyId: string,
     config?: FindConfig<RegionCountryDTO>,
     sharedContext?: Context
   ): Promise<RegionCurrencyDTO>
 
+  /**
+   * This method retrieves a paginated list of countries along with the total count of available countries satisfying the provided filters.
+   *
+   * @param {FilterableRegionCountryProps} filters - The filters to apply on the retrieved region country.
+   * @param {FindConfig<RegionCountryDTO>} config - The configurations determining how the region country is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region country.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[RegionCountryDTO[], number]>} The list of countries along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listAndCountCountries(
     filters?: FilterableRegionCountryProps,
     config?: FindConfig<RegionCountryDTO>,
     sharedContext?: Context
   ): Promise<[RegionCountryDTO[], number]>
 
+  /**
+   * This method retrieves a paginated list of currencies based on optional filters and configuration.
+   *
+   * @param {FilterableRegionCurrencyProps} filters - The filters to apply on the retrieved region currency.
+   * @param {FindConfig<RegionCurrencyDTO>} config - The configurations determining how the region currency is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region currency.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<RegionCurrencyDTO[]>} The list of currencies.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listCurrencies(
     filters?: FilterableRegionCurrencyProps,
     config?: FindConfig<RegionCurrencyDTO>,
     sharedContext?: Context
   ): Promise<RegionCurrencyDTO[]>
 
+  /**
+   * This method retrieves a paginated list of currencies along with the total count of available currencies satisfying the provided filters.
+   *
+   * @param {FilterableRegionCurrencyProps} filters - The filters to apply on the retrieved region currency.
+   * @param {FindConfig<RegionCurrencyDTO>} config - The configurations determining how the region currency is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a region currency.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[RegionCurrencyDTO[], number]>} The list of currencies along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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}
+   * ```
+   *
+   *
+   */
   listAndCountCurrencies(
     filters?: FilterableRegionCurrencyProps,
     config?: FindConfig<RegionCurrencyDTO>,
     sharedContext?: Context
   ): Promise<[RegionCurrencyDTO[], number]>
 
+  /**
+   * This method soft deletes regions by their IDs.
+   *
+   * @param {string[]} regionIds - The list of IDs of regions to soft delete.
+   * @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 successfully when the regions are soft-deleted.
+   *
+   * @example
+   * {example-code}
+   */
   softDelete<TReturnableLinkableKeys extends string = string>(
     regionIds: string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
 
+  /**
+   * This method restores soft deleted regions by their IDs.
+   *
+   * @param {string[]} regionIds - The list of IDs of regions to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the regions. You can pass to its `returnLinkableKeys`
+   * property any of the regions's relation attribute names, such as `currency`.
+   * @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, such as the ID of associated currency.
+   * The object's keys are the ID attribute names of the regions 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 region through this relation,
+   * such as the IDs of associated currency.
+   *
+   * @example
+   * {example-code}
+   */
   restore<TReturnableLinkableKeys extends string = string>(
     regionIds: string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
 
+  /**
+   * This method creates default countries and currencies.
+   *
+   * @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 default countries and currencies are created.
+   *
+   * @example
+   * {example-code}
+   */
   createDefaultCountriesAndCurrencies(sharedContext?: Context): Promise<void>
 }

packages/types/src/region__legacy/common.ts

@@ -1,11 +1,51 @@
+/**
+ * @interface
+ *
+ * The details of a legacy region.
+ */
 export type RegionDTO__legacy = {
+  /**
+   * The name of the region.
+   */
   name: string
+
+  /**
+   * The currency code of the region.
+   */
   currency_code: string
+
+  /**
+   * The tax rate of the region.
+   */
   tax_rate?: number
+
+  /**
+   * The tax code of the region.
+   */
   tax_code?: string | null
+
+  /**
+   * Whether gift cards in the region are taxable.
+   */
   gift_cards_taxable?: boolean
+
+  /**
+   * Whether taxes should be calculated automatically in the region.
+   */
   automatic_taxes?: boolean
+
+  /**
+   * The associated tax provider's ID.
+   */
   tax_provider_id?: string | null
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
+
+  /**
+   * Whether prices include taxes in the region.
+   */
   includes_tax?: boolean
 }

packages/types/src/sales-channel/common.ts

@@ -1,23 +1,77 @@
 import { BaseFilterable } from "../dal"
 
+/**
+ * The sales channel location details.
+ */
 export interface SalesChannelLocationDTO {
+  /**
+   * The associated sales channel's ID.
+   */
   sales_channel_id: string
+
+  /**
+   * The associated location's ID.
+   */
   location_id: string
+
+  /**
+   * The associated sales channel.
+   */
   sales_channel: SalesChannelDTO
 }
 
+/**
+ * The sales channel details.
+ */
 export interface SalesChannelDTO {
+  /**
+   * The ID of the sales channel.
+   */
   id: string
+
+  /**
+   * The name of the sales channel.
+   */
   name: string
+
+  /**
+   * The description of the sales channel.
+   */
   description: string | null
+
+  /**
+   * Whether the sales channel is disabled.
+   */
   is_disabled: boolean
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata: Record<string, unknown> | null
+
+  /**
+   * The locations of the sales channel.
+   */
   locations?: SalesChannelLocationDTO[]
 }
 
+/**
+ * The filters to apply on the retrieved sales channel.
+ */
 export interface FilterableSalesChannelProps
   extends BaseFilterable<FilterableSalesChannelProps> {
+  /**
+   * The IDs to filter the sales channel by.
+   */
   id?: string[]
+
+  /**
+   * Filter sales channels by their names.
+   */
   name?: string[]
+
+  /**
+   * Filter sales channels by whether they're disabled.
+   */
   is_disabled?: boolean
 }

packages/types/src/sales-channel/mutations.ts

@@ -1,12 +1,44 @@
+/**
+ * The sales channel to be created.
+ */
 export interface CreateSalesChannelDTO {
+  /**
+   * The name of the sales channel.
+   */
   name: string
+
+  /**
+   * The description of the sales channel.
+   */
   description?: string
+
+  /**
+   * Whether the sales channel is disabled.
+   */
   is_disabled?: boolean
 }
 
+/**
+ * The attributes to update in the sales channel.
+ */
 export interface UpdateSalesChannelDTO {
+  /**
+   * The ID of the sales channel.
+   */
   id: string
+
+  /**
+   * The name of the sales channel.
+   */
   name?: string
+
+  /**
+   * The description of the sales channel.
+   */
   description?: string
+
+  /**
+   * Whether the sales channel is disabled.
+   */
   is_disabled?: boolean
 }

packages/types/src/sales-channel/service.ts

@@ -5,52 +5,227 @@ import { Context } from "../shared-context"
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
 import { CreateSalesChannelDTO, UpdateSalesChannelDTO } from "./mutations"
 
+/**
+ * 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 {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}
+   */
   create(
     data: CreateSalesChannelDTO[],
     sharedContext?: Context
   ): Promise<SalesChannelDTO[]>
+
+  /**
+   * This method creates a sales channel.
+   *
+   * @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.
+   *
+   * @example
+   * {example-code}
+   */
   create(
     data: CreateSalesChannelDTO,
     sharedContext?: Context
   ): Promise<SalesChannelDTO>
 
+  /**
+   * This method updates existing sales channels.
+   *
+   * @param {UpdateSalesChannelDTO[]} data - The attributes to update in each 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
+   * {example-code}
+   */
   update(
     data: UpdateSalesChannelDTO[],
     sharedContext?: Context
   ): Promise<SalesChannelDTO[]>
+
+  /**
+   * This method updates an existing sales channel.
+   *
+   * @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
+   * {example-code}
+   */
   update(
     data: UpdateSalesChannelDTO,
     sharedContext?: Context
   ): Promise<SalesChannelDTO>
 
+  /**
+   * This method deletes sales channels by their IDs.
+   *
+   * @param {string[]} ids - The list of IDs of sales channels to delete.
+   * @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.
+   *
+   * @example
+   * {example-code}
+   */
   delete(ids: string[], sharedContext?: Context): Promise<void>
+
+  /**
+   * This method deletes a sales channel by its ID.
+   *
+   * @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.
+   *
+   * @example
+   * {example-code}
+   */
   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 {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.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieve(
     id: string,
     config?: FindConfig<SalesChannelDTO>,
     sharedContext?: Context
   ): Promise<SalesChannelDTO>
 
+  /**
+   * 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 {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:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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,
     config?: FindConfig<SalesChannelDTO>,
     sharedContext?: Context
   ): Promise<SalesChannelDTO[]>
 
+  /**
+   * 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 {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:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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,
     config?: FindConfig<SalesChannelDTO>,
     sharedContext?: Context
   ): Promise<[SalesChannelDTO[], number]>
 
+  /**
+   * This method soft deletes sales channels by their IDs.
+   *
+   * @param {string[]} salesChannelIds - The list of IDs of sales channels to soft delete.
+   * @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.
+   *
+   * @example
+   * {example-code}
+   */
   softDelete<TReturnableLinkableKeys extends string = string>(
     salesChannelIds: string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
 
+  /**
+   * This method restores soft deleted sales channels by their IDs.
+   *
+   * @param {string[]} salesChannelIds - The list of IDs of sales channels to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} 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 {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,
+   * 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}
+   */
   restore<TReturnableLinkableKeys extends string = string>(
     salesChannelIds: string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,

packages/types/src/stock-location/common.ts

@@ -65,18 +65,69 @@ import { StringComparisonOperator } from "../common/common"
  *     example: {car: "white"}
  */
 export type StockLocationAddressDTO = {
+  /**
+   * The ID of the stock location address.
+   */
   id?: string
+
+  /**
+   * The address 1 of the stock location address.
+   */
   address_1: string
+
+  /**
+   * The address 2 of the stock location address.
+   */
   address_2?: string | null
+
+  /**
+   * The company of the stock location address.
+   */
   company?: string | null
+
+  /**
+   * The country code of the stock location address.
+   */
   country_code: string
+
+  /**
+   * The city of the stock location address.
+   */
   city?: string | null
+
+  /**
+   * The phone of the stock location address.
+   */
   phone?: string | null
+
+  /**
+   * The postal code of the stock location address.
+   */
   postal_code?: string | null
+
+  /**
+   * The province of the stock location address.
+   */
   province?: string | null
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
+
+  /**
+   * The creation date of the stock location address.
+   */
   created_at: string | Date
+
+  /**
+   * The update date of the stock location address.
+   */
   updated_at: string | Date
+
+  /**
+   * The deletion date of the stock location address.
+   */
   deleted_at: string | Date | null
 }
 
@@ -127,13 +178,44 @@ export type StockLocationAddressDTO = {
  *     format: date-time
  */
 export type StockLocationDTO = {
+  /**
+   * The ID of the stock location.
+   */
   id: string
+
+  /**
+   * The name of the stock location.
+   */
   name: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata: Record<string, unknown> | null
+
+  /**
+   * The associated address's ID.
+   */
   address_id: string
+
+  /**
+   * The address of the stock location.
+   */
   address?: StockLocationAddressDTO
+
+  /**
+   * The creation date of the stock location.
+   */
   created_at: string | Date
+
+  /**
+   * The update date of the stock location.
+   */
   updated_at: string | Date
+
+  /**
+   * The deletion date of the stock location.
+   */
   deleted_at: string | Date | null
 }
 
@@ -148,6 +230,9 @@ export type StockLocationDTO = {
  *         $ref: "#/components/schemas/SalesChannel"
  */
 export type StockLocationExpandedDTO = StockLocationDTO & {
+  /**
+   * The list of sales channels.
+   */
   sales_channels?: any[] // TODO: SalesChannel type
 }
 
@@ -161,10 +246,12 @@ export type FilterableStockLocationProps = {
    * Search parameter for stock location names
    */
   q?: string
+
   /**
    * The IDs to filter stock locations by.
    */
   id?: string | string[]
+
   /**
    * The names to filter stock locations by.
    */
@@ -214,13 +301,44 @@ export type FilterableStockLocationProps = {
  *     example: {car: "white"}
  */
 export type StockLocationAddressInput = {
+  /**
+   * The first line of the stock location address.
+   */
   address_1: string
+
+  /**
+   * The second line of the stock location address.
+   */
   address_2?: string
+
+  /**
+   * The country code of the stock location address.
+   */
   country_code: string
+
+  /**
+   * The city of the stock location address.
+   */
   city?: string
+
+  /**
+   * The phone of the stock location address.
+   */
   phone?: string
+
+  /**
+   * The province of the stock location address.
+   */
   province?: string
+
+  /**
+   * The postal code of the stock location address.
+   */
   postal_code?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
@@ -249,9 +367,24 @@ export type StockLocationAddressInput = {
  *     example: {car: "white"}
  */
 export type CreateStockLocationInput = {
+  /**
+   * The name of the stock location.
+   */
   name: string
+
+  /**
+   * The associated address's ID.
+   */
   address_id?: string
+
+  /**
+   * The associated address.
+   */
   address?: string | StockLocationAddressInput
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }
 
@@ -278,8 +411,23 @@ export type CreateStockLocationInput = {
  *     example: {car: "white"}
  */
 export type UpdateStockLocationInput = {
+  /**
+   * The name of the stock location.
+   */
   name?: string
+
+  /**
+   * The associated address's ID.
+   */
   address_id?: string
+
+  /**
+   * The associated address's details.
+   */
   address?: StockLocationAddressInput
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown>
 }

packages/types/src/stock-location/service.ts

@@ -9,6 +9,9 @@ import { FindConfig } from "../common/common"
 import { IModuleService } from "../modules-sdk"
 import { SharedContext } from "../shared-context"
 
+/**
+ * The main service interface for the stock location's module.
+ */
 export interface IStockLocationService extends IModuleService {
   /**
    * This method is used to retrieve a paginated list of stock locations based on optional filters and configuration.

packages/types/src/user/common.ts

@@ -1,23 +1,72 @@
 import { DateComparisonOperator } from "../common"
 import { BaseFilterable } from "../dal"
 
+/**
+ * @interface
+ *
+ * The user details.
+ */
 export interface UserDTO {
+  /**
+   * The ID of the user.
+   */
   id: string
+  /**
+   * The email of the user.
+   */
   email: string
+  /**
+   * The first name of the user.
+   */
   first_name: string | null
+  /**
+   * The last name of the user.
+   */
   last_name: string | null
+  /**
+   * The avatar URL of the user.
+   */
   avatar_url: string | null
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The creation date of the user.
+   */
   created_at: Date
+  /**
+   * The updated date of the user.
+   */
   updated_at: Date
+  /**
+   * The deletion date of the user.
+   */
   deleted_at: Date | null
 }
 
+/**
+ * @interface
+ *
+ * The filters to apply on the retrieved user.
+ */
 export interface FilterableUserProps
   extends BaseFilterable<FilterableUserProps> {
+  /**
+   * The IDs to filter users by.
+   */
   id?: string | string[]
+  /**
+   * Filter users by their email.
+   */
   email?: string | string[]
+  /**
+   * Filter users by their first name.
+   */
   first_name?: string | string[]
+  /**
+   * Filter users by their last name.
+   */
   last_name?: string | string[]
 }
 

packages/types/src/user/mutations.ts

@@ -1,12 +1,36 @@
+/**
+ * The user to be created.
+ */
 export interface CreateUserDTO {
+  /**
+   * The email of the user.
+   */
   email: string
+  /**
+   * The first name of the user.
+   */
   first_name?: string | null
+  /**
+   * The last name of the user.
+   */
   last_name?: string | null
+  /**
+   * The avatar URL of the user.
+   */
   avatar_url?: string | null
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The attributes to update in the user.
+ */
 export interface UpdateUserDTO extends Partial<Omit<CreateUserDTO, "email">> {
+  /**
+   * The ID of the user.
+   */
   id: string
 }
 

packages/types/src/user/service.ts

@@ -11,38 +11,182 @@ import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
 
+/**
+ * The main service interface for the user module.
+ */
 export interface IUserModuleService extends IModuleService {
+  /**
+   * This method validates an invite token.
+   *
+   * @param {string} token - The token to validate.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO>} The associated invite's details.
+   */
   validateInviteToken(
     token: string,
     sharedContext?: Context
   ): Promise<InviteDTO>
 
+  /**
+   * This method retrieves a user by its ID.
+   *
+   * @param {string} id - The ID of the retrieve.
+   * @param {FindConfig<UserDTO>} config - The configurations determining how the user is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<UserDTO>} The retrieved user.
+   *
+   * @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}
+   * ```
+   *
+   *
+   */
   retrieve(
     id: string,
     config?: FindConfig<UserDTO>,
     sharedContext?: Context
   ): Promise<UserDTO>
 
+  /**
+   * This method retrieves a paginated list of users based on optional filters and configuration.
+   *
+   * @param {FilterableUserProps} filters - The filters to apply on the retrieved user.
+   * @param {FindConfig<UserDTO>} config - The configurations determining how the user is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<UserDTO[]>} The list of users.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableUserProps,
     config?: FindConfig<UserDTO>,
     sharedContext?: Context
   ): Promise<UserDTO[]>
 
+  /**
+   * This method retrieves a paginated list of user along with the total count of available users satisfying the provided filters.
+   *
+   * @param {FilterableUserProps} filters - The filters to apply on the retrieved user.
+   * @param {FindConfig<UserDTO>} config - The configurations determining how the user is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[UserDTO[], number]>} The list of users along with their total count.
+   *
+   * @example
+   * To retrieve a list of {type name} using their IDs:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * To specify relations that should be retrieved within the {type name}:
+   *
+   * ```ts
+   * {example-code}
+   * ```
+   *
+   * 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?: FilterableUserProps,
     config?: FindConfig<UserDTO>,
     sharedContext?: Context
   ): Promise<[UserDTO[], number]>
 
+  /**
+   * This method creates users.
+   *
+   * @param {CreateUserDTO[]} data - The users to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<UserDTO[]>} The created users.
+   *
+   * @example
+   * {example-code}
+   */
   create(data: CreateUserDTO[], sharedContext?: Context): Promise<UserDTO[]>
 
+  /**
+   * This method creates a user.
+   *
+   * @param {CreateUserDTO} data - The user to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<UserDTO>} The created user.
+   *
+   * @example
+   * {example-code}
+   */
   create(data: CreateUserDTO, sharedContext?: Context): Promise<UserDTO>
 
+  /**
+   * This method updates existing users.
+   *
+   * @param {UpdateUserDTO[]} data - The attributes to update in each user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<UserDTO[]>} The updated users.
+   *
+   * @example
+   * {example-code}
+   */
   update(data: UpdateUserDTO[], sharedContext?: Context): Promise<UserDTO[]>
 
+  /**
+   * This method updates an existing user.
+   *
+   * @param {UpdateUserDTO} data - The attributes to update in the user.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<UserDTO>} The updated user.
+   *
+   * @example
+   * {example-code}
+   */
   update(data: UpdateUserDTO, sharedContext?: Context): Promise<UserDTO>
 
+  /**
+   * This method deletes users by their IDs.
+   *
+   * @param {string[]} ids - The list of IDs of users to delete.
+   * @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 users are deleted.
+   *
+   * @example
+   * {example-code}
+   */
   delete(ids: string[], sharedContext?: Context): Promise<void>
 
   softDelete<TReturnableLinkableKeys extends string = string>(