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(
+ *     super(...arguments)
- *       {},
- *       {
- *         provider: "my-auth",
- *         displayName: "My Custom Authentication"
- *       }
- *     )
  *
  *     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.
+   * This method validates the options of the provider set in `medusa-config.ts`.
-   * @param options
+   * 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 {}
 

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

@@ -25,6 +25,7 @@ import { FileTypes, IFileProvider } from "@medusajs/types"
  * class MyFileProviderService extends AbstractFileProviderService {
  *   protected logger_: Logger
  *   protected options_: Options
+ *   static identifier = "my-file"
  *   // assuming you're initializing a client
  *   protected client
  *
@@ -47,13 +48,37 @@ import { FileTypes, IFileProvider } from "@medusajs/types"
  */
 export class AbstractFileProviderService implements IFileProvider {
   /**
-   * @ignore
+   * Each file provider has a unique ID used to identify it. The provider's ID
+   * will be stored as `fs_{identifier}_{id}`, where `{id}` is the provider's `id` 
+   * property in the `medusa-config.ts`.
+   * 
+   * @example
+   * class MyFileProviderService extends AbstractFileProviderService {
+   *   static identifier = "my-file"
+   *   // ...
+   * }
    */
   static identifier: string
 
   /**
-   * Override this static method in order for the loader to validate the options provided to the module provider.
+   * This method validates the options of the provider set in `medusa-config.ts`.
-   * @param options
+   * 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 MyFileProviderService extends AbstractFileProviderService {
+   *   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 {}
 

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

@@ -49,8 +49,24 @@ export class AbstractNotificationProviderService
   implements INotificationProvider
 {
   /**
-   * Override this static method in order for the loader to validate the options provided to the module provider.
+   * This method validates the options of the provider set in `medusa-config.ts`.
-   * @param options
+   * 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 MyNotificationProviderService extends AbstractNotificationProviderService {
+   *   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 {}
 

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

@@ -14,8 +14,24 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
   implements IPaymentProvider
 {
   /**
-   * Override this static method in order for the loader to validate the options provided to the module provider.
+   * This method validates the options of the provider set in `medusa-config.ts`.
-   * @param options
+   * 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 MyPaymentProviderService extends AbstractPaymentProvider<Options> {
+   *   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 {}
 
@@ -48,6 +64,7 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
    * class MyPaymentProviderService extends AbstractPaymentProvider<
    *   Options
    * > {
+   *   static identifier = "my-payment"
    *   protected logger_: Logger
    *   protected options_: Options
    *   // Assuming you're using a client to integrate
@@ -92,7 +109,9 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
   }
 
   /**
-   * Each payment provider has a unique identifier defined in its class.
+   * Each payment provider has a unique identifier defined in its class. The provider's ID
+   * will be stored as `pp_{identifier}_{id}`, where `{id}` is the provider's `id` 
+   * property in the `medusa-config.ts`.
    *
    * @example
    * class MyPaymentProviderService extends AbstractPaymentProvider<