chore(types): add TSDocs to the user module's types (#7549)

packages/core/types/src/user/common.ts

@@ -11,34 +11,42 @@ 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.
    */
@@ -56,39 +64,95 @@ export interface FilterableUserProps
    * Find users by name or email through this search term
    */
   q?: string
+
   /**
    * 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[]
 }
 
+/**
+ * The invite details.
+ */
 export interface InviteDTO {
+  /**
+   * The ID of the invite.
+   */
   id: string
+
+  /**
+   * The email of the invite.
+   */
   email: string
+
+  /**
+   * Whether the invite is accepted.
+   */
   accepted: boolean
+
+  /**
+   * The token of the invite.
+   */
   token: string
+
+  /**
+   * The invite's expiry date.
+   */
   expires_at: Date
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata: Record<string, unknown> | null
+
+  /**
+   * The invite's creation date.
+   */
   created_at: Date
+
+  /**
+   * The invite's update date.
+   */
   updated_at: Date
+
+  /**
+   * The invite's deletion date.
+   */
   deleted_at: Date | null
 }
 
+/**
+ * The filters to apply on the retrieved invites.
+ */
 export interface FilterableInviteProps
   extends BaseFilterable<FilterableInviteProps> {
+  /**
+   * The IDs to filter the invites by.
+   */
   id?: string | string[]
+
+  /**
+   * Filter the invites by their email.
+   */
   email?: string | string[]
+
+  /**
+   * Filter the invites by their expiry date.
+   */
   expires_at?: DateComparisonOperator
 }

packages/core/types/src/user/mutations.ts

@@ -6,18 +6,22 @@ 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.
    */
@@ -34,13 +38,33 @@ export interface UpdateUserDTO extends Partial<Omit<CreateUserDTO, "email">> {
   id: string
 }
 
+/**
+ * The invite to be created.
+ */
 export interface CreateInviteDTO {
+  /**
+   * The email of the invite.
+   */
   email: string
+
+  /**
+   * Whether the invite is accepted.
+   */
   accepted?: boolean
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * The attributes to update in the invite.
+ */
 export interface UpdateInviteDTO
   extends Partial<Omit<CreateInviteDTO, "email">> {
+  /**
+   * The ID of the invite.
+   */
   id: string
 }

packages/core/types/src/user/service.ts

@@ -6,27 +6,46 @@ import {
 } from "./mutations"
 import { FilterableUserProps, InviteDTO, UserDTO } from "./common"
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
-
 import { Context } from "../shared-context"
 import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 
 /**
- * The main service interface for the user module.
+ * The main service interface for the User Module.
  */
 export interface IUserModuleService extends IModuleService {
   /**
-   * This method validates an invite token.
+   * This method validates that a token belongs to an invite and returns that invite.
+   * 
+   * An error is thrown if the invite has expired or no invite matches the token.
    *
-   * @param {string} token - The token to validate.
+   * @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.
+   * @returns {Promise<InviteDTO>} The token's invite.
+   *
+   * @example
+   * const invite = await userModuleService.validateInviteToken(
+   *   "eyJhbG..."
+   * )
    */
   validateInviteToken(
     token: string,
     sharedContext?: Context
   ): Promise<InviteDTO>
 
+  /**
+   * This method updates the token and expiration date of invites.
+   *
+   * @param {string[]} inviteIds - The IDs of the invites to refresh.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO[]>} The updated invites.
+   *
+   * @example
+   * const invites = await userModuleService.refreshInviteTokens([
+   *   "invite_123",
+   *   "invite_321"
+   * ])
+   */
   refreshInviteTokens(
     inviteIds: string[],
     sharedContext?: Context
@@ -35,26 +54,14 @@ export interface IUserModuleService extends IModuleService {
   /**
    * This method retrieves a user by its ID.
    *
-   * @param {string} id - The ID of the retrieve.
+   * @param {string} id - The ID of the 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 retrieved user.
    *
    * @example
-   * A simple example that retrieves a {type name} by its ID:
+   * const user = await userModuleService.retrieve("user_123")
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   * To specify relations that should be retrieved:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   retrieve(
     id: string,
@@ -65,32 +72,34 @@ export interface IUserModuleService extends IModuleService {
   /**
    * 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 {FilterableUserProps} filters - The filters to apply on the retrieved users.
    * @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:
+   * To retrieve a list of users using their IDs:
    *
    * ```ts
-   * {example-code}
+   * const users = await userModuleService.list({
+   *   id: ["user_123", "user_321"]
+   * })
    * ```
    *
-   * To specify relations that should be retrieved within the {type name}:
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
    *
    * ```ts
-   * {example-code}
+   * const users = await userModuleService.list(
+   *   {
+   *     id: ["user_123", "user_321"]
+   *   },
+   *   {
+   *     take: 20,
+   *     skip: 2
+   *   }
+   * )
    * ```
-   *
-   * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   list(
     filters?: FilterableUserProps,
@@ -99,34 +108,36 @@ export interface IUserModuleService extends IModuleService {
   ): Promise<UserDTO[]>
 
   /**
-   * This method retrieves a paginated list of user along with the total count of available users satisfying the provided filters.
+   * This method retrieves a paginated list of users along with the total count of available users satisfying the provided filters.
    *
-   * @param {FilterableUserProps} filters - The filters to apply on the retrieved user.
+   * @param {FilterableUserProps} filters - The filters to apply on the retrieved users.
    * @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:
+   * To retrieve a list of users using their IDs:
    *
    * ```ts
-   * {example-code}
+   * const [users, count] = await userModuleService.listAndCount({
+   *   id: ["user_123", "user_321"]
+   * })
    * ```
    *
-   * To specify relations that should be retrieved within the {type name}:
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
    *
    * ```ts
-   * {example-code}
+   * const [users, count] = await userModuleService.listAndCount(
+   *   {
+   *     id: ["user_123", "user_321"]
+   *   },
+   *   {
+   *     take: 20,
+   *     skip: 2
+   *   }
+   * )
    * ```
-   *
-   * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   listAndCount(
     filters?: FilterableUserProps,
@@ -142,7 +153,14 @@ export interface IUserModuleService extends IModuleService {
    * @returns {Promise<UserDTO[]>} The created users.
    *
    * @example
-   * {example-code}
+   * const users = await userModuleService.create([
+   *   {
+   *     email: "john@doe.com"
+   *   },
+   *   {
+   *     email: "john2@doe.com"
+   *   }
+   * ])
    */
   create(data: CreateUserDTO[], sharedContext?: Context): Promise<UserDTO[]>
 
@@ -154,19 +172,30 @@ export interface IUserModuleService extends IModuleService {
    * @returns {Promise<UserDTO>} The created user.
    *
    * @example
-   * {example-code}
+   * const user = await userModuleService.create({
+   *   email: "john@doe.com"
+   * })
    */
   create(data: CreateUserDTO, sharedContext?: Context): Promise<UserDTO>
 
   /**
    * This method updates existing users.
    *
-   * @param {UpdateUserDTO[]} data - The attributes to update in each user.
+   * @param {UpdateUserDTO[]} data - The attributes to update in the users.
    * @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}
+   * const users = await userModuleService.update([
+   *   {
+   *     id: "user_123",
+   *     first_name: "John"
+   *   },
+   *   {
+   *     id: "user_321",
+   *     last_name: "Doe"
+   *   }
+   * ])
    */
   update(data: UpdateUserDTO[], sharedContext?: Context): Promise<UserDTO[]>
 
@@ -178,80 +207,301 @@ export interface IUserModuleService extends IModuleService {
    * @returns {Promise<UserDTO>} The updated user.
    *
    * @example
-   * {example-code}
+   * const user = await userModuleService.update({
+   *   id: "user_123",
+   *   first_name: "John"
+   * })
    */
   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 {string[]} ids - The IDs of the users.
    * @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.
+   * @returns {Promise<void>} Resolves when the users are deleted successfully.
    *
    * @example
-   * {example-code}
+   * await userModuleService.delete([
+   *   "user_123", "user_321"
+   * ])
    */
   delete(ids: string[], sharedContext?: Context): Promise<void>
 
+  /**
+   * This method soft deletes a user by its IDs.
+   *
+   * @param {string[]} userIds - The IDs of users 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[]>>} An object that includes the IDs of related records that were also soft deleted.
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await userModuleService.softDelete([
+   *   "user_123", "user_321"
+   * ])
+   */
   softDelete<TReturnableLinkableKeys extends string = string>(
     userIds: string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
 
+  /**
+   * This method restores soft deleted users by their IDs.
+   *
+   * @param {string[]} userIds - The IDs of users to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the users. You can pass to its `returnLinkableKeys`
+   * property any of the user'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<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored.
+   *
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await userModuleService.restore([
+   *   "user_123", "user_321"
+   * ])
+   */
   restore<TReturnableLinkableKeys extends string = string>(
     userIds: string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
 
+  /**
+   * This method retrieves an invite by its ID.
+   *
+   * @param {string} id - The ID of the invite.
+   * @param {FindConfig<InviteDTO>} config - The configurations determining how the invite is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a invite.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO>} The retrieved invite.
+   *
+   * @example
+   * const invite = await userModuleService.retrieveInvite(
+   *   "invite_123"
+   * )
+   */
   retrieveInvite(
     id: string,
     config?: FindConfig<InviteDTO>,
     sharedContext?: Context
   ): Promise<InviteDTO>
 
+  /**
+   * This method retrieves a paginated list of invites based on optional filters and configuration.
+   *
+   * @param {FilterableUserProps} filters - The filters to apply on the retrieved invites.
+   * @param {FindConfig<InviteDTO>} config - The configurations determining how the invite is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a invite.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO[]>} The list of invites.
+   *
+   * @example
+   * To retrieve a list of invites using their IDs:
+   *
+   * ```ts
+   * const invites = await userModuleService.listInvites({
+   *   id: ["invite_123", "invite_321"]
+   * })
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const invites = await userModuleService.listInvites(
+   *   {
+   *     id: ["invite_123", "invite_321"]
+   *   },
+   *   {
+   *     take: 20,
+   *     skip: 2
+   *   }
+   * )
+   * ```
+   */
   listInvites(
     filters?: FilterableUserProps,
     config?: FindConfig<InviteDTO>,
     sharedContext?: Context
   ): Promise<InviteDTO[]>
 
+  /**
+   * This method retrieves a paginated list of invites along with the total count of available invites satisfying the provided filters.
+   *
+   * @param {FilterableUserProps} filters - The filters to apply on the retrieved invites.
+   * @param {FindConfig<InviteDTO>} config - The configurations determining how the invite is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a invite.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<[InviteDTO[], number]>} The list of invites along with their total count.
+   *
+   * @example
+   * To retrieve a list of invites using their IDs:
+   *
+   * ```ts
+   * const [invites, count] = await userModuleService
+   *   .listAndCountInvites({
+   *     id: ["invite_123", "invite_321"]
+   *   })
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const [invites, count] = await userModuleService
+   *   .listAndCountInvites(
+   *     {
+   *       id: ["invite_123", "invite_321"]
+   *     },
+   *     {
+   *       take: 20,
+   *       skip: 2
+   *     }
+   *   )
+   * ```
+   */
   listAndCountInvites(
     filters?: FilterableUserProps,
     config?: FindConfig<InviteDTO>,
     sharedContext?: Context
   ): Promise<[InviteDTO[], number]>
 
+  /**
+   * This method creates invites.
+   *
+   * @param {CreateInviteDTO[]} data - The invites to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO[]>} The created invites.
+   *
+   * @example
+   * const invites = await userModuleService.createInvites([
+   *   {
+   *     email: "john@doe.com"
+   *   },
+   *   {
+   *     email: "john2@doe.com"
+   *   }
+   * ])
+   */
   createInvites(
     data: CreateInviteDTO[],
     sharedContext?: Context
   ): Promise<InviteDTO[]>
 
+  /**
+   * This method creates a invite.
+   *
+   * @param {CreateInviteDTO} data - The invite to be created.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO>} The created invite.
+   *
+   * @example
+   * const invite = await userModuleService.createInvites({
+   *   email: "john@doe.com"
+   * })
+   */
   createInvites(
     data: CreateInviteDTO,
     sharedContext?: Context
   ): Promise<InviteDTO>
 
+  /**
+   * This method updates existing invites.
+   *
+   * @param {UpdateInviteDTO[]} data - The attributes to update in the invites.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO[]>} The updated invites.
+   *
+   * @example
+   * const invites = await userModuleService.updateInvites([
+   *   {
+   *     id: "invite_123",
+   *     accepted: true
+   *   },
+   *   {
+   *     id: "invite_321",
+   *     metadata: {
+   *       test: true
+   *     }
+   *   }
+   * ])
+   */
   updateInvites(
     data: UpdateInviteDTO[],
     sharedContext?: Context
   ): Promise<InviteDTO[]>
 
+  /**
+   * This method updates an existing invite.
+   *
+   * @param {UpdateInviteDTO} data - The attributes to update in the invite.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<InviteDTO>} The updated invite.
+   *
+   * @example
+   * const invite = await userModuleService.updateInvites({
+   *   id: "invite_123",
+   *   accepted: true
+   * })
+   */
   updateInvites(
     data: UpdateInviteDTO,
     sharedContext?: Context
   ): Promise<InviteDTO>
 
+  /**
+   * This method deletes invites by their IDs.
+   *
+   * @param {string[]} ids - The IDs of the invites.
+   * @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 invites are deleted successfully.
+   *
+   * @example
+   * await userModuleService.deleteInvites([
+   *   "invite_123", "invite_321"
+   * ])
+   */
   deleteInvites(ids: string[], sharedContext?: Context): Promise<void>
 
+  /**
+   * This method soft deletes invites by their IDs.
+   *
+   * @param {string[]} inviteIds - The IDs of the invites 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[]>>} An object that includes the IDs of related records that were also soft deleted.
+   *
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await userModuleService.softDeleteInvites([
+   *   "invite_123", "invite_321"
+   * ])
+   */
   softDeleteInvites<TReturnableLinkableKeys extends string = string>(
     inviteIds: string[],
     config?: SoftDeleteReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<TReturnableLinkableKeys, string[]> | void>
 
+  /**
+   * This method restores soft deleted invites by their IDs.
+   *
+   * @param {string[]} inviteIds - The IDs of invites to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the invites. You can pass to its `returnLinkableKeys`
+   * property any of the invite'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<TReturnableLinkableKeys, string[]>>} An object that includes the IDs of related records that were restored.
+   *
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await userModuleService.restoreInvites([
+   *   "invite_123", "invite_321"
+   * ])
+   */
   restoreInvites<TReturnableLinkableKeys extends string = string>(
     inviteIds: string[],
     config?: RestoreReturn<TReturnableLinkableKeys>,

www/utils/packages/docblock-generator/src/utils/filter-files.ts

@@ -4,7 +4,7 @@ export default function (files: string[]): string[] {
   return files.filter((file) =>
     minimatch(
       file,
-      "**/packages/@(medusa|types|medusa-js|medusa-react)/src/**/*.@(ts|tsx|js|jsx)",
+      "**/packages/@(medusa|core/types|medusa-js|medusa-react)/src/**/*.@(ts|tsx|js|jsx)",
       {
         matchBase: true,
       }