From 6b86b1d5314ee3adaf2717ce86d0ef7936065366 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 30 May 2024 18:04:44 +0300 Subject: [PATCH] chore(types): add TSDocs to the user module's types (#7549) --- packages/core/types/src/user/common.ts | 64 ++++ packages/core/types/src/user/mutations.ts | 24 ++ packages/core/types/src/user/service.ts | 358 +++++++++++++++--- .../src/utils/filter-files.ts | 2 +- 4 files changed, 393 insertions(+), 55 deletions(-) diff --git a/packages/core/types/src/user/common.ts b/packages/core/types/src/user/common.ts index efd2e7f4e6..1fa9dddce4 100644 --- a/packages/core/types/src/user/common.ts +++ b/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 | 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 | 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 { + /** + * 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 } diff --git a/packages/core/types/src/user/mutations.ts b/packages/core/types/src/user/mutations.ts index 747bbcdc26..8ed48ab3c5 100644 --- a/packages/core/types/src/user/mutations.ts +++ b/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> { 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 | null } +/** + * The attributes to update in the invite. + */ export interface UpdateInviteDTO extends Partial> { + /** + * The ID of the invite. + */ id: string } diff --git a/packages/core/types/src/user/service.ts b/packages/core/types/src/user/service.ts index 38eccf8b15..242068d24c 100644 --- a/packages/core/types/src/user/service.ts +++ b/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} The associated invite's details. + * @returns {Promise} The token's invite. + * + * @example + * const invite = await userModuleService.validateInviteToken( + * "eyJhbG..." + * ) */ validateInviteToken( token: string, sharedContext?: Context ): Promise + /** + * 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} 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} 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} 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} - * ``` - * - * + * const user = await userModuleService.retrieve("user_123") */ 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} 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} 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 /** - * 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} 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} 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 @@ -154,19 +172,30 @@ export interface IUserModuleService extends IModuleService { * @returns {Promise} The created user. * * @example - * {example-code} + * const user = await userModuleService.create({ + * email: "john@doe.com" + * }) */ create(data: CreateUserDTO, sharedContext?: Context): Promise /** * 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} 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 @@ -178,80 +207,301 @@ export interface IUserModuleService extends IModuleService { * @returns {Promise} The updated user. * * @example - * {example-code} + * const user = await userModuleService.update({ + * id: "user_123", + * first_name: "John" + * }) */ update(data: UpdateUserDTO, sharedContext?: Context): Promise /** * 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} Resolves when the users are deleted. + * @returns {Promise} Resolves when the users are deleted successfully. * * @example - * {example-code} + * await userModuleService.delete([ + * "user_123", "user_321" + * ]) */ delete(ids: string[], sharedContext?: Context): Promise + /** + * This method soft deletes a user by its IDs. + * + * @param {string[]} userIds - The IDs of users to soft-delete + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} 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( userIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** + * This method restores soft deleted users by their IDs. + * + * @param {string[]} userIds - The IDs of users to restore. + * @param {RestoreReturn} 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>} 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( userIds: string[], config?: RestoreReturn, sharedContext?: Context ): Promise | void> + /** + * This method retrieves an invite by its ID. + * + * @param {string} id - The ID of the invite. + * @param {FindConfig} 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} The retrieved invite. + * + * @example + * const invite = await userModuleService.retrieveInvite( + * "invite_123" + * ) + */ retrieveInvite( id: string, config?: FindConfig, sharedContext?: Context ): Promise + /** + * 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} 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} 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, sharedContext?: Context ): Promise + /** + * 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} 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, 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} The created invites. + * + * @example + * const invites = await userModuleService.createInvites([ + * { + * email: "john@doe.com" + * }, + * { + * email: "john2@doe.com" + * } + * ]) + */ createInvites( data: CreateInviteDTO[], sharedContext?: Context ): Promise + /** + * 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} The created invite. + * + * @example + * const invite = await userModuleService.createInvites({ + * email: "john@doe.com" + * }) + */ createInvites( data: CreateInviteDTO, sharedContext?: Context ): Promise + /** + * 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} 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 + /** + * 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} The updated invite. + * + * @example + * const invite = await userModuleService.updateInvites({ + * id: "invite_123", + * accepted: true + * }) + */ updateInvites( data: UpdateInviteDTO, sharedContext?: Context ): Promise + /** + * 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} Resolves when the invites are deleted successfully. + * + * @example + * await userModuleService.deleteInvites([ + * "invite_123", "invite_321" + * ]) + */ deleteInvites(ids: string[], sharedContext?: Context): Promise + /** + * This method soft deletes invites by their IDs. + * + * @param {string[]} inviteIds - The IDs of the invites to soft-delete. + * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} 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( inviteIds: string[], config?: SoftDeleteReturn, sharedContext?: Context ): Promise | void> + /** + * This method restores soft deleted invites by their IDs. + * + * @param {string[]} inviteIds - The IDs of invites to restore. + * @param {RestoreReturn} 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>} 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( inviteIds: string[], config?: RestoreReturn, diff --git a/www/utils/packages/docblock-generator/src/utils/filter-files.ts b/www/utils/packages/docblock-generator/src/utils/filter-files.ts index 70e4946f41..1c4bf71f9b 100644 --- a/www/utils/packages/docblock-generator/src/utils/filter-files.ts +++ b/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, }