From d345496dbc1f1517c74dd119ad034bcc119ff0f1 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 5 Apr 2024 13:01:08 +0300 Subject: [PATCH] chore: added tsdocs for the Auth Module (#6863) --- packages/types/src/auth/common/auth-user.ts | 37 ++-- packages/types/src/auth/common/provider.ts | 43 ++-- packages/types/src/auth/service.ts | 214 +++++++++++++------- 3 files changed, 187 insertions(+), 107 deletions(-) diff --git a/packages/types/src/auth/common/auth-user.ts b/packages/types/src/auth/common/auth-user.ts index 1d563e726a..1382811f48 100644 --- a/packages/types/src/auth/common/auth-user.ts +++ b/packages/types/src/auth/common/auth-user.ts @@ -12,32 +12,34 @@ export type AuthUserDTO = { id: string /** - * The provider of the auth user. + * The ID of the provider used to authenticate the user. */ provider: string /** - * The associated providers entity's ID. + * The user's identifier. For example, when using the `emailpass` + * provider, the `entity_id` would be the user's email. */ entity_id: string /** - * The scope of the auth user. + * The scope of the auth user. For example, + * `admin` or `store`. */ scope: string /** - * The provider metadata of the auth user. + * Holds custom data related to the provider in key-value pairs. */ provider_metadata?: Record /** - * The user metadata of the auth user. + * Holds custom data related to the user in key-value pairs. */ user_metadata: Record /** - * The app metadata of the auth user. + * Holds custom data related to the third-party app in key-value pairs. */ app_metadata: Record } @@ -54,32 +56,35 @@ export type CreateAuthUserDTO = { id?: string /** - * The provider of the auth user. + * The ID of the provider used to authenticate + * the user. */ provider: string /** - * The associated entity's ID. + * The user's identifier. For example, when using the `emailpass` + * provider, the `entity_id` would be the user's email. */ entity_id: string /** - * The scope of the auth user. + * The scope of the auth user. For example, + * `admin` or `store`. */ scope: string /** - * The provider metadata of the auth user. + * Holds custom data related to the provider in key-value pairs. */ provider_metadata?: Record /** - * The user metadata of the auth user. + * Holds custom data related to the user in key-value pairs. */ user_metadata?: Record /** - * The app metadata of the auth user. + * Holds custom data related to the third-party app in key-value pairs. */ app_metadata?: Record } @@ -96,17 +101,17 @@ export type UpdateAuthUserDTO = { id: string /** - * The provider metadata of the auth user. + * Holds custom data related to the provider in key-value pairs. */ provider_metadata?: Record /** - * The user metadata of the auth user. + * Holds custom data related to the user in key-value pairs. */ user_metadata?: Record /** - * The app metadata of the auth user. + * Holds custom data related to the third-party app in key-value pairs. */ app_metadata?: Record } @@ -122,7 +127,7 @@ export interface FilterableAuthUserProps id?: string[] /** - * Filter the auth auth user by the associated provider(s). + * Filter the auth users by the ID of their auth provider. */ provider?: string[] | string } diff --git a/packages/types/src/auth/common/provider.ts b/packages/types/src/auth/common/provider.ts index 7dccb6db44..724d2814e5 100644 --- a/packages/types/src/auth/common/provider.ts +++ b/packages/types/src/auth/common/provider.ts @@ -10,23 +10,34 @@ export type AuthenticationResponse = { success: boolean /** - * The authenticated user's details. The details shape - * depends on the used provider ID. + * The authenticated user's details. */ authUser?: any /** - * The error message, if an error occurs. + * If an error occurs during the authentication process, + * whether within the Auth Module or a third-party provider, + * the error message is set in this field. */ error?: string /** - * Redirect location. Location takes precedence over success. + * The URL to redirect to for further authentication action + * with a third-party provider. This takes precedence before + * the `success` field. + * + * So, after checking that authentication is successful, + * you should check whether this field is defined and, if so, redirect to the + * specified location. */ location?: string /** - * Redirect url for successful authentication. + * Some authentication providers support redirecting to a specified URL on + * success. In those cases, the URL to redirect to is set in this field. + * + * So, if `success` is true, there's no `location` set, and this field + * is set, you can redirect to this URL. */ successRedirectUrl?: string } @@ -34,16 +45,17 @@ export type AuthenticationResponse = { /** * @interface * - * Provider configuration for the Medusa auth module. + * The configurations of the `providers` option + * passed to the Auth Module. */ export type AuthModuleProviderConfig = { /** - * Provider name + * The provider's name. */ name: string /** - * Scope configurations for the provider + * The scopes configuration of that provider. */ scopes: Record } @@ -51,18 +63,19 @@ export type AuthModuleProviderConfig = { /** * @interface * - * Configuration of a single provider scope + * The scope configurations of an auth provider. */ export type AuthProviderScope = Record /** * @interface * - * Input for authentication and callback validation methods. + * The data passed to the auth provider when authenticating a user + * or validating a callback. */ export type AuthenticationInput = { /** - * url of incoming authentication request. + * URL of the incoming authentication request. */ url: string @@ -72,22 +85,22 @@ export type AuthenticationInput = { headers: Record /** - * Query params of incoming authentication request. + * Query params of the incoming authentication request. */ query: Record /** - * Body of incoming authentication request. + * Body of the incoming authentication request. */ body: Record /** - * Scope for authentication request. + * Scope for the authentication request. */ authScope: string /** - * Protocol of incoming authentication request (For example, `https`). + * Protocol of the incoming authentication request (For example, `https`). */ protocol: string } diff --git a/packages/types/src/auth/service.ts b/packages/types/src/auth/service.ts index 1871875f31..e250a536af 100644 --- a/packages/types/src/auth/service.ts +++ b/packages/types/src/auth/service.ts @@ -6,7 +6,6 @@ import { FilterableAuthUserProps, UpdateAuthUserDTO, } from "./common" - import { Context } from "../shared-context" import { FindConfig } from "../common" import { IModuleService } from "../modules-sdk" @@ -17,19 +16,37 @@ import { IModuleService } from "../modules-sdk" export type JWTGenerationOptions = { expiresIn?: string | number } + /** - * The main service interface for the authentication module. + * The main service interface for the Auth Module. */ export interface IAuthModuleService extends IModuleService { /** - * This method is the first invoked method of the authentication flow. It handles the incoming authentication request. + * This method is used to authenticate a user using a provider. The `authenticate` method of the + * underlying provider is called, passing it the `providerData` parameter as a parameter. The method + * returns the data returned by the provider. * - * @param {string} provider - The provider to use for authentication. - * @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider - * @returns {Promise} The authentication's result. + * Refer to [this guide](https://docs.medusajs.com/experimental/auth/auth-flows) to learn more about the authentication flows. + * + * @param {string} provider - The ID of the provider to authenticate the user with. + * @param {AuthenticationInput} providerData - The data to pass to the provider to authenticate the user. + * @returns {Promise} The details of the authentication result. * * @example - * {example-code} + * The following example is in the context of an API route, where + * `req` is an instance of the `MedusaRequest` object: + * + * ```ts + * const { success, authUser, location, error } = + * await authModuleService.authenticate("emailpass", { + * url: req.url, + * headers: req.headers, + * query: req.query, + * body: req.body, + * authScope: "admin", + * protocol: req.protocol, + * } as AuthenticationInput) + * ``` */ authenticate( provider: string, @@ -37,14 +54,38 @@ export interface IAuthModuleService extends IModuleService { ): Promise /** - * This method handles the callback from an authentication provider when an authentication has been initialized and the user is redirected. + * When authenticating users with a third-party provider, such as Google, the user performs an + * action to finish the authentication, such as enter their credentials in Google's sign-in + * form. * - * @param {string} provider - The provider to use for callback validation. - * @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider - * @returns {Promise} The authentication's result. + * In those cases, you must create an API route or endpoint that's called by the third-party + * provider when the user finishes performing the required action. + * + * In that API route, you can call this method to validate the third-party provider's + * callback and authenticate the user. + * + * Learn more about this authentication flow in [this guide](https://docs.medusajs.com/experimental/auth/auth-flows#authentication-with-third-party-service). + * + * @param {string} provider - The ID of the provider to use to validate the callback. + * @param {AuthenticationInput} providerData - The data to pass to the provider to validate the callback. + * @returns {Promise} The details of the authentication result. * * @example - * {example-code} + * The following example is in the context of an API route, where + * `req` is an instance of the `MedusaRequest` object: + * + * ```ts + * const { success, authUser, error, successRedirectUrl } = + * await authModuleService.validateCallback("google", { + * url: req.url, + * headers: req.headers, + * query: req.query, + * body: req.body, + * authScope: "admin", + * protocol: req.protocol, + * } as AuthenticationInput) + * ``` + * */ validateCallback( provider: string, @@ -52,28 +93,16 @@ export interface IAuthModuleService extends IModuleService { ): Promise /** - * This method retrieves the user by its ID. + * This method retrieves an auth user by its ID. * - * @param {string} id - The ID of the retrieve. + * @param {string} id - The ID of the auth user. * @param {FindConfig} 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} The retrieved user. + * @returns {Promise} The retrieved auth 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 authUser = await authModuleService.retrieve("authusr_1") */ retrieve( id: string, @@ -82,34 +111,36 @@ export interface IAuthModuleService extends IModuleService { ): Promise /** - * This method retrieves a paginated list of users based on optional filters and configuration. + * This method retrieves a paginated list of auth users based on optional filters and configuration. * - * @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth user. + * @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth users. * @param {FindConfig} 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} The list of users. + * @returns {Promise} The list of auth users. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of auth users using their IDs: * * ```ts - * {example-code} + * const authUsers = await authModuleService.list({ + * id: ["authusr_123", "authusr_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 authUsers = await authModuleService.list( + * { + * id: ["authusr_123", "authusr_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?: FilterableAuthUserProps, @@ -118,34 +149,38 @@ export interface IAuthModuleService 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 auth users along with the total count of available auth users satisfying the provided filters. * - * @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth user. + * @param {FilterableAuthUserProps} filters - The filters to apply on the retrieved auth users. * @param {FindConfig} 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. + * @returns {Promise<[AuthUserDTO[], number]>} The list of auth users along with their total count. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of auth users using their IDs: * * ```ts - * {example-code} + * const [authUsers, count] = + * await authModuleService.listAndCount({ + * id: ["authusr_123", "authusr_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 [authUsers, count] = + * await authModuleService.listAndCount( + * { + * id: ["authusr_123", "authusr_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?: FilterableAuthUserProps, @@ -154,14 +189,25 @@ export interface IAuthModuleService extends IModuleService { ): Promise<[AuthUserDTO[], number]> /** - * This method creates users + * This method creates auth users. * - * @param {CreateAuthUserDTO[]} data - The auth user to be created. + * @param {CreateAuthUserDTO[]} data - The auth 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} The created users. + * @returns {Promise} The created auth users. * * @example - * {example-code} + * const authUsers = await authModuleService.create([ + * { + * provider: "emailpass", + * entity_id: "user@example.com", + * scope: "admin", + * }, + * { + * provider: "google", + * entity_id: "user@gmail.com", + * scope: "email profile", + * }, + * ]) */ create( data: CreateAuthUserDTO[], @@ -169,26 +215,37 @@ export interface IAuthModuleService extends IModuleService { ): Promise /** - * This method creates a user + * This method creates an auth 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} The created user. + * @returns {Promise} The created auth user. * * @example - * {example-code} + * const authUser = await authModuleService.create({ + * provider: "emailpass", + * entity_id: "user@example.com", + * scope: "admin", + * }) */ create(data: CreateAuthUserDTO, sharedContext?: Context): Promise /** - * This method updates existing users. + * This method updates existing auths. * - * @param {UpdateAuthUserDTO[]} data - The attributes to update in the auth user. + * @param {UpdateAuthUserDTO[]} data - The attributes to update in the auth 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. + * @returns {Promise} The updated auths. * * @example - * {example-code} + * const authUsers = await authModuleService.update([ + * { + * id: "authusr_123", + * app_metadata: { + * test: true, + * }, + * }, + * ]) */ update( data: UpdateAuthUserDTO[], @@ -196,26 +253,31 @@ export interface IAuthModuleService extends IModuleService { ): Promise /** - * This method updates existing user. + * This method updates an existing auth. * * @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} The updated user. + * @returns {Promise} The updated auth. * * @example - * {example-code} + * const authUser = await authModuleService.update({ + * id: "authusr_123", + * app_metadata: { + * test: true, + * }, + * }) */ update(data: UpdateAuthUserDTO, sharedContext?: Context): Promise /** - * This method deletes users by their IDs. + * This method deletes a auth by its ID. * - * @param {string[]} ids - The list of IDs of users to delete. + * @param {string[]} ids - The IDs of the auth. * @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 {summary} * * @example - * {example-code} + * await authModuleService.delete(["authusr_123", "authusr_321"]) */ delete(ids: string[], sharedContext?: Context): Promise }