chore(utils): update tsdocs for provider identifiers (#9656)

packages/core/utils/src/auth/abstract-auth-provider.ts

@@ -13,13 +13,6 @@ import {
  *
  * If you're creating a client or establishing a connection with a third-party service, do it in the constructor.
  *
- * In the constructor, you must pass to the parent constructor two parameters:
- *
- * 1. The first one is an empty object.
- * 2. The second is an object having two properties:
- *    - `provider`: The ID of the provider. For example, `emailpass`.
- *    - `displayName`: The label or displayable name of the provider. For example, `Email and Password Authentication`.
- *
  * #### Example
  *
  * ```ts
@@ -35,6 +28,7 @@ import {
  * }
  *
  * class MyAuthProviderService extends AbstractAuthModuleProvider {
+ *   static identifier = "my-auth"
  *   protected logger_: Logger
  *   protected options_: Options
  *   // assuming you're initializing a client
@@ -44,13 +38,7 @@ import {
  *     { logger }: InjectedDependencies,
  *     options: Options
  *   ) {
- *     super(
- *       {},
- *       {
- *         provider: "my-auth",
- *         displayName: "My Custom Authentication"
- *       }
- *     )
+ *     super(...arguments)
  *
  *     this.logger_ = logger
  *     this.options_ = options
@@ -67,11 +55,26 @@ import {
  */
 export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   /**
-   * @ignore
+   * Every auth provider must have an `identifier` static property. The provider's ID
+   * will be stored as `au_{identifier}_{id}`, where `{id}` is the provider's `id` 
+   * property in the `medusa-config.ts`.
+   * 
+   * @example
+   * class MyAuthProviderService extends AbstractAuthModuleProvider {
+   *   static identifier = "my-auth"
+   *   // ...
+   * }
    */
   static identifier: string
   /**
-   * @ignore
+   * This property indicates the name used when displaying the provider on a frontend application.
+   * 
+   * @example
+   * class MyAuthProviderService extends AbstractAuthModuleProvider {
+   *   static DISPLAY_NAME = "My Auth"
+   *   // ...
+   * }
+   * 
    */
   static DISPLAY_NAME: string
 
@@ -103,8 +106,25 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   }
 
   /**
-   * Override this static method in order for the loader to validate the options provided to the module provider.
-   * @param options
+   * This method validates the options of the provider set in `medusa-config.ts`.
+   * Implementing this method is optional. It's useful if your provider requires custom validation.
+   * 
+   * If the options aren't valid, throw an error.
+   * 
+   * @param options - The provider's options.
+   * 
+   * @example
+   * class MyAuthProviderService extends AbstractAuthModuleProvider {
+   *   static validateOptions(options: Record<any, any>) {
+   *     if (!options.apiKey) {
+   *       throw new MedusaError(
+   *         MedusaError.Types.INVALID_DATA,
+   *         "API key is required in the provider's options."
+   *       )
+   *     }
+   *   }
+   *   // ...
+   * }
    */
   static validateOptions(options: Record<any, any>): void | never {}