chore(utils): update auth provider TSDocs + fix errors stopping references build (#9023)

- Updated the TSDocs of the auth provider - Update the Node version in the docs-util as the outdated version was causing TypeScript error - Add `@ts-ignore` for a line that was causing a typescript error. If there's a better fix here let me know
2024-09-09 16:53:33 +03:00
parent 423bae1d73
commit 4ffcc41fe7
12 changed files with 167 additions and 54 deletions
--- a/packages/core/utils/src/auth/abstract-auth-provider.ts
+++ b/packages/core/utils/src/auth/abstract-auth-provider.ts
@@ -118,6 +118,8 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *
   * The authentication happens either by directly authenticating or returning a redirect URL to continue
   * the authentication with a third party provider.
+   * 
+   * Related Read: [Learn about the different authentication flows in Medusa](https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route).
   *
   * @param {AuthenticationInput} data - The details of the authentication request.
   * @param {AuthIdentityProviderService} authIdentityProviderService - The service used to retrieve or
@@ -126,9 +128,6 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   * using this service.
   * @returns {Promise<AuthenticationResponse>} The authentication response.
   *
-   * @privateRemarks
-   * TODO add a link to the authentication flow document once it's public.
-   *
   * @example
   * For example, if your authentication provider doesn't require validating a callback:
   *
@@ -148,7 +147,7 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *   ): Promise<AuthenticationResponse> {
   *     const isAuthenticated = false
   *     // TODO perform custom logic to authenticate the user
-   *     // ...
+   *     // for example, verifying a password
   *
   *     if (!isAuthenticated) {
   *       // if the authentication didn't succeed, return
@@ -159,25 +158,11 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *       }
   *     }
   *
-   *     // authentication is successful, create an auth identity
-   *     // if doesn't exist
-   *     let authIdentity
-   *
-   *     try {
-   *       authIdentity = await authIdentityProviderService.retrieve({
-   *         entity_id: data.body.email, // email or some ID
-   *         provider: this.provider
-   *       })
-   *     } catch (e) {
-   *       // The auth identity doesn't exist so create it
-   *       authIdentity = await authIdentityProviderService.create({
-   *         entity_id: data.body.email, // email or some ID
-   *         provider: this.provider,
-   *         provider_metadata: {
-   *           // can include password or any other relevant information
-   *         }
-   *       })
-   *     }
+   *     // authentication is successful, retrieve the identity
+   *     const authIdentity = await authIdentityProviderService.retrieve({
+   *       entity_id: data.body.email, // email or some ID
+   *       provider: this.provider
+   *     })
   *
   *     return {
   *       success: true,
@@ -229,6 +214,70 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
    authIdentityProviderService: AuthIdentityProviderService
  ): Promise<AuthenticationResponse>

+  /**
+   * This method receives credentails to create a new auth identity. It performs any validation necessary
+   * before creating the auth identity.
+   * 
+   * For example, in the `emailpass` provider, this method ensures that the provided email doesn't exist
+   * before creating the auth identity.
+   * 
+   * This method is only used in a basic authentication flow, such as when using an email and password
+   * to register and authenticate a user.
+   * 
+   * Related Read: [Learn about the different authentication flows in Medusa](https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route).
+   * 
+   * @param {AuthenticationInput} data - The details of the authentication request. 
+   * @param {AuthIdentityProviderService} authIdentityProviderService - The service used to retrieve or
+   * create an auth identity. It has two methods: `create` to create an auth identity,
+   * and `retrieve` to retrieve an auth identity. When you authenticate the user, you can create an auth identity
+   * using this service.
+   * @returns The created authentication identity if no errors occur.
+   * 
+   * @example
+   * import {
+   *   AuthIdentityProviderService,
+   *   AuthenticationInput,
+   *   AuthenticationResponse
+   * } from "@medusajs/types"
+   * import { MedusaError } from "@medusajs/utils"
+   * // ...
+   *
+   * class MyAuthProviderService extends AbstractAuthModuleProvider {
+   *   // ...
+   *   async register(
+   *     data: AuthenticationInput,
+   *     authIdentityProviderService: AuthIdentityProviderService
+   *   ): Promise<AuthenticationResponse> {
+   *     try {
+   *       await authIdentityService.retrieve({
+   *         entity_id: data.body.email, // email or some ID
+   *       })
+   *     
+   *       return {
+   *         success: false,
+   *         error: "Identity with email already exists",
+   *       }
+   *     } catch (error) {
+   *       if (error.type === MedusaError.Types.NOT_FOUND) {
+   *         const createdAuthIdentity = await authIdentityProviderService.create({
+   *           entity_id: data.body.email, // email or some ID
+   *           provider: this.provider,
+   *           provider_metadata: {
+   *             // can include password or any other relevant information
+   *           }
+   *         })
+   *     
+   *         return {
+   *           success: true,
+   *           authIdentity: createdAuthIdentity,
+   *         }
+   *       }
+   *     
+   *       return { success: false, error: error.message }
+   *     }
+   *   }
+   * }
+   */
  register(
    data: AuthenticationInput,
    authIdentityProviderService: AuthIdentityProviderService
@@ -238,6 +287,49 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
    )
  }

+  /**
+   * This method is used to update an auth identity's details.
+   * 
+   * For example, the `emailpass` provider's implementation of this method updates a user's password.
+   * 
+   * @param data - Data relevant to identify the auth identity and what to update in it. For example,
+   * the `emailpass` provider expects in this object an `email` and `password` properties.
+   * @param authIdentityProviderService - The service used to retrieve or
+   * create an auth identity. It has two methods: `create` to create an auth identity,
+   * and `retrieve` to retrieve an auth identity. When you authenticate the user, you can create an auth identity
+   * using this service.
+   * @returns The updated authentication identity if no errors occur.
+   * 
+   * @example
+   * import {
+   *   AuthIdentityProviderService,
+   *   AuthenticationInput,
+   *   AuthenticationResponse
+   * } from "@medusajs/types"
+   * import { MedusaError } from "@medusajs/utils"
+   * // ...
+   *
+   * class MyAuthProviderService extends AbstractAuthModuleProvider {
+   *   // ...
+   *   async update(
+   *     data: Record<string, unknown>,
+   *     authIdentityProviderService: AuthIdentityProviderService
+   *   ): Promise<AuthenticationResponse> {
+   *     try {
+   *       const authIdentity = await authIdentityService.update(
+   *         data.email, // email or some ID used to identify the auth identity
+   *         {
+   *           user: data.user // example
+   *         }
+   *       )
+   *     
+   *       return { success: true, authIdentity }
+   *     } catch (error) {
+   *       return { success: false, error: error.message }
+   *     }
+   *   }
+   * }
+   */
  update(
    data: Record<string, unknown>,
    authIdentityProviderService: AuthIdentityProviderService
@@ -253,8 +345,19 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   * In an authentication flow that requires performing an action with a third-party service, such as login
   * with a social account, the {@link authenticate} method is called first.
   *
-   * Then, the third-party service redirects to the Medusa application's validate callback API route.
-   * That route uses this method to authenticate the user.
+   * Then, the third-party service redirects to a frontend URL passing it a `code` query parameter.
+   * The frontend should then send a request to the Medusa application's validate callback API route, passing it the code.
+   * That route uses this method to verify the callback's code.
+   * 
+   * If the callback is verified successfully, the provider creates an auth identity for the user, or updates the auth identity's user information.
+   * 
+   * In the auth identity, yuse the following properties to store additional data:
+   * 
+   * - `provider_metadata`: Store metadata useful for the provider, such as a password hash.
+   * - `user_metadata`: Store metadata of the user's details. For example, if the third-party service returns the user's information such as email
+   * or name, you store this data in this property.
+   * 
+   * Related Guide: [Learn about the different authentication flows in Medusa](https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route).
   *
   * @param {AuthenticationInput} data - The details of the authentication request.
   * @param {AuthIdentityProviderService} authIdentityProviderService - The service used to retrieve or
@@ -263,9 +366,6 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   * using this service.
   * @returns {Promise<AuthenticationResponse>} The authentication response.
   *
-   * @privateRemarks
-   * TODO add a link to the authentication flow document once it's public.
-   *
   * @example
   * import {
   *   AuthIdentityProviderService,
@@ -309,6 +409,9 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *         provider: this.provider,
   *         provider_metadata: {
   *           // can include password or any other relevant information
+   *         },
+   *         user_metadata: {
+   *           // can include data retrieved from the third-party service
   *         }
   *       })
   *     }