chore: added tsdocs for the Auth Module (#6863)

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<string, unknown>
 
   /**
-   * The user metadata of the auth user.
+   * Holds custom data related to the user in key-value pairs.
    */
   user_metadata: Record<string, unknown>
 
   /**
-   * The app metadata of the auth user.
+   * Holds custom data related to the third-party app in key-value pairs.
    */
   app_metadata: Record<string, unknown>
 }
@@ -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<string, unknown>
 
   /**
-   * The user metadata of the auth user.
+   * Holds custom data related to the user in key-value pairs.
    */
   user_metadata?: Record<string, unknown>
 
   /**
-   * The app metadata of the auth user.
+   * Holds custom data related to the third-party app in key-value pairs.
    */
   app_metadata?: Record<string, unknown>
 }
@@ -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<string, unknown>
 
   /**
-   * The user metadata of the auth user.
+   * Holds custom data related to the user in key-value pairs.
    */
   user_metadata?: Record<string, unknown>
 
   /**
-   * The app metadata of the auth user.
+   * Holds custom data related to the third-party app in key-value pairs.
    */
   app_metadata?: Record<string, unknown>
 }
@@ -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
 }

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

@@ -10,23 +10,34 @@ export type AuthenticationResponse = {
   success: boolean
 
   /**
-   * The authenticated user's details. The details shape
+   * The authenticated user's details.
-   * depends on the used provider ID.
    */
   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<string, AuthProviderScope>
 }
@@ -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<string, unknown>
 
 /**
  * @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<string, string>
 
   /**
-   *  Query params of incoming authentication request.
+   *  Query params of the incoming authentication request.
    */
   query: Record<string, string>
 
   /**
-   * Body of incoming authentication request.
+   * Body of the incoming authentication request.
    */
   body: Record<string, string>
 
   /**
-   * 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
 }

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.
+   * Refer to [this guide](https://docs.medusajs.com/experimental/auth/auth-flows) to learn more about the authentication flows.
-   * @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider
+   *
-   * @returns {Promise<AuthenticationResponse>} The authentication's result.
+   * @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<AuthenticationResponse>} 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<AuthenticationResponse>
 
   /**
-   * 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.
+   * In those cases, you must create an API route or endpoint that's called by the third-party
-   * @param {AuthenticationInput} providerData - The authentication data necessary to pass to the provider
+   * provider when the user finishes performing the required action.
-   * @returns {Promise<AuthenticationResponse>} The authentication's result.
+   *
+   * 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<AuthenticationResponse>} 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<AuthenticationResponse>
 
   /**
-   * 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<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.
+   * @returns {Promise<AuthUserDTO>} The retrieved auth user.
    *
    * @example
-   * A simple example that retrieves a {type name} by its ID:
+   * const authUser = await authModuleService.retrieve("authusr_1")
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   * To specify relations that should be retrieved:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   retrieve(
     id: string,
@@ -82,34 +111,36 @@ export interface IAuthModuleService extends IModuleService {
   ): Promise<AuthUserDTO>
 
   /**
-   * 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<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.
+   * @returns {Promise<AuthUserDTO[]>} 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<AuthUserDTO[]>
 
   /**
-   * 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<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.
+   * @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<AuthUserDTO[]>} The created users.
+   * @returns {Promise<AuthUserDTO[]>} 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<AuthUserDTO[]>
 
   /**
-   * 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<AuthUserDTO>} The created user.
+   * @returns {Promise<AuthUserDTO>} 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<AuthUserDTO>
 
   /**
-   * 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<AuthUserDTO[]>} The updated users.
+   * @returns {Promise<AuthUserDTO[]>} 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<AuthUserDTO[]>
 
   /**
-   * 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<AuthUserDTO>} The updated user.
+   * @returns {Promise<AuthUserDTO>} The updated auth.
    *
    * @example
-   * {example-code}
+   * const authUser = await authModuleService.update({
+   *   id: "authusr_123",
+   *   app_metadata: {
+   *     test: true,
+   *   },
+   * })
    */
   update(data: UpdateAuthUserDTO, sharedContext?: Context): Promise<AuthUserDTO>
 
   /**
-   * 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<void>} Resolves when the users are deleted.
+   * @returns {Promise<void>} Resolves when {summary}
    *
    * @example
-   * {example-code}
+   * await authModuleService.delete(["authusr_123", "authusr_321"])
    */
   delete(ids: string[], sharedContext?: Context): Promise<void>
 }