chore: fixes to tsdocs + docs-util related to providers

packages/core/types/src/notification/common.ts

@@ -20,7 +20,7 @@ export interface Attachment {
    */
   content_type?: string
   /**
-   * The disposition of the attachment, e.g., "inline" or "attachment".
+   * The disposition of the attachment, For example, "inline" or "attachment".
    */
   disposition?: string
   /**

packages/core/utils/src/fulfillment/provider.ts

@@ -20,7 +20,7 @@ import {
  *
  * #### Example
  *
- * ```ts
+ * ```ts title="src/modules/my-fulfillment/service.ts"
  * import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
  * import { Logger } from "@medusajs/framework/types"
  *
@@ -56,13 +56,11 @@ export class AbstractFulfillmentProviderService
   implements IFulfillmentProvider
 {
   /**
-   * The `identifier` property holds a unique identifier of the fulfillment module provider.
+   * Each fulfillment provider has a unique identifier defined in its class. The provider's ID
+   * will be stored as `fp_{identifier}_{id}`, where `{id}` is the provider's `id`
+   * property in the `medusa-config.ts`.
    *
-   * You can use the kebab-case name of the provider as its value.
-   *
-   * For example:
-   *
-   * ```ts
+   * @example
    * class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
    *   static identifier = "my-fulfillment"
    *

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

@@ -12,6 +12,9 @@ import {
 export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
   implements IPaymentProvider
 {
+  /**
+   * @ignore
+   */
   protected readonly container: Record<string, unknown>
   /**
    * This method validates the options of the provider set in `medusa-config.ts`.
@@ -44,7 +47,7 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
    * The provider can also access the module's options as a second parameter.
    *
    * @param {Record<string, unknown>} cradle - The module's container cradle used to resolve resources.
-   * @param {Record<string, unknown>} config - The options passed to the payment module provider.
+   * @param {Record<string, unknown>} config - The options passed to the Payment Module provider.
    *
    * @example
    * ```ts
@@ -93,6 +96,9 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
    */
   protected constructor(
     cradle: Record<string, unknown>,
+    /**
+     * @ignore
+     */
     protected readonly config: TConfig = {} as TConfig // eslint-disable-next-line @typescript-eslint/no-empty-function
   ) {
     this.container = cradle
@@ -122,7 +128,6 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
    *   static identifier = "my-payment"
    *   // ...
    * }
-   * ```
    */
   public static identifier: string
 

www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx

@@ -77,7 +77,33 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
 export default MyAuthProviderService
 ```
 
-### constructor
+### identifier
+
+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
+
+```ts
+class MyAuthProviderService extends AbstractAuthModuleProvider {
+  static identifier = "my-auth"
+  // ...
+}
+```
+
+### DISPLAY\_NAME
+
+This property indicates the name used when displaying the provider on a frontend application.
+
+#### Example
+
+```ts
+class MyAuthProviderService extends AbstractAuthModuleProvider {
+  static DISPLAY_NAME = "My Auth"
+  // ...
+}
+```
 
 ### validateOptions
 
@@ -441,17 +467,18 @@ This exports the module's definition, indicating that the `MyAuthProviderService
 To use your Auth Module Provider, add it to the `providers` array of the Auth Module in `medusa-config.ts`:
 
 ```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
 module.exports = defineConfig({
   // ...
   modules: [
     {
       resolve: "@medusajs/medusa/auth",
       options: {
         providers: [
+          // default provider
+          {
+            resolve: "@medusajs/medusa/auth-emailpass",
+            id: "emailpass",
+          },
           {
             resolve: "./src/modules/my-auth",
             id: "my-auth",

www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx

@@ -75,7 +75,20 @@ class MyFileProviderService extends AbstractFileProviderService {
 export default MyFileProviderService
 ```
 
-### constructor
+### identifier
+
+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
+
+```ts
+class MyFileProviderService extends AbstractFileProviderService {
+  static identifier = "my-file"
+  // ...
+}
+```
 
 ### validateOptions
 
@@ -229,17 +242,18 @@ The File Module accepts one provider only.
 </Note>
 
 ```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
 module.exports = defineConfig({
   // ...
   modules: [
     {
       resolve: "@medusajs/medusa/file",
       options: {
         providers: [
+          // default provider
+          {
+            resolve: "@medusajs/medusa/file-local",
+            id: "local",
+          },
           {
             resolve: "./src/modules/my-file",
             id: "my-file",

www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx

@@ -45,7 +45,7 @@ If you're creating a client or establishing a connection with a third-party serv
 
 #### Example
 
-```ts
+```ts title="src/modules/my-fulfillment/service.ts"
 import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
 import { Logger } from "@medusajs/framework/types"
 
@@ -77,7 +77,21 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
 export default MyFulfillmentProviderService
 ```
 
-### constructor
+### identifier
+
+Each fulfillment provider has a unique identifier defined in its class. The provider's ID
+will be stored as `fp_{identifier}_{id}`, where `{id}` is the provider's `id`
+property in the `medusa-config.ts`.
+
+#### Example
+
+```ts
+class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
+  static identifier = "my-fulfillment"
+
+  // ...
+}
+```
 
 ### getFulfillmentOptions
 
@@ -226,7 +240,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
 
 #### Returns
 
-<TypeList types={[{"name":"Promise","type":"Promise&#60;number&#62;","optional":false,"defaultValue":"","description":"The calculated price","expandable":false,"children":[{"name":"number","type":"`number`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="calculatePrice"/>
+<TypeList types={[{"name":"Promise","type":"Promise&#60;CalculatedShippingOptionPrice&#62;","optional":false,"defaultValue":"","description":"The calculated price","expandable":false,"children":[{"name":"CalculatedShippingOptionPrice","type":"`CalculatedShippingOptionPrice`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="calculatePrice"/>
 
 ### createFulfillment
 
@@ -473,17 +487,18 @@ This exports the module's definition, indicating that the `MyFulfillmentProvider
 To use your Fulfillment Module Provider, add it to the `providers` array of the Fulfillment Module in `medusa-config.ts`:
 
 ```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
 module.exports = defineConfig({
   // ...
   modules: [
     {
       resolve: "@medusajs/medusa/fulfillment",
       options: {
         providers: [
+          // default provider
+          {
+            resolve: "@medusajs/medusa/fulfillment-manual",
+            id: "manual",
+          },
           {
             resolve: "./src/modules/my-fulfillment",
             id: "my-fulfillment",

www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx

@@ -78,8 +78,6 @@ class MyNotificationProviderService extends AbstractNotificationProviderService
 export default MyNotificationProviderService
 ```
 
-### constructor
-
 ### validateOptions
 
 This method validates the options of the provider set in `medusa-config.ts`.
@@ -181,17 +179,22 @@ The Notification Module accepts one provider per channel.
 </Note>
 
 ```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
 module.exports = defineConfig({
   // ...
   modules: [
     {
       resolve: "@medusajs/medusa/notification",
       options: {
         providers: [
+          // default provider
+          {
+            resolve: "@medusajs/medusa/notification-local",
+            id: "local",
+            options: {
+              name: "Local Notification Provider",
+              channels: ["feed"],
+            },
+          },
           {
             resolve: "./src/modules/my-notification",
             id: "my-notification",

www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx

@@ -36,69 +36,23 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
 export default MyPaymentProviderService
 ```
 
-### Type parameters
+### identifier
 
-<TypeList types={[{"name":"TConfig","type":"`object`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="AbstractPaymentProvider"/>
-
-### constructor
-
-You can use the `constructor` of the provider's service to access resources in your module's container.
-
-You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs,
-you can initialize it in the constructor and use it in other methods in the service.
-
-The provider can also access the module's options as a second parameter.
+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
 
 ```ts
-import {
-  AbstractPaymentProvider
-} from "@medusajs/framework/utils"
-import { Logger } from "@medusajs/framework/types"
-
-type InjectedDependencies = {
-  logger: Logger
-}
-
-type Options = {
-  apiKey: string
-}
-
 class MyPaymentProviderService extends AbstractPaymentProvider<
   Options
 > {
   static identifier = "my-payment"
-  protected logger_: Logger
-  protected options_: Options
-  // Assuming you're using a client to integrate
-  // with a third-party service
-  protected client
-
-  constructor(
-    { logger }: InjectedDependencies,
-    options: Options
-  ) {
-    // @ts-ignore
-    super(...arguments)
-
-    this.logger_ = logger
-    this.options_ = options
-
-    // Assuming you're initializing a client
-    this.client = new Client(options)
-  }
-
   // ...
 }
-
-export default MyPaymentProviderService
 ```
 
-#### Parameters
-
-<TypeList types={[{"name":"cradle","type":"`Record<string, unknown>`","description":"The module's container cradle used to resolve resources.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"TConfig","description":"The options passed to the payment module provider.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="new AbstractPaymentProvider"/>
-
 ### validateOptions
 
 This method validates the options of the provider set in `medusa-config.ts`.
@@ -719,10 +673,6 @@ This exports the module's definition, indicating that the `MyPaymentProviderServ
 To use your Payment Module Provider, add it to the `providers` array of the Payment Module in `medusa-config.ts`:
 
 ```ts title="medusa-config.ts"
-import { Modules } from "@medusajs/framework/utils"
-
-// ...
-
 module.exports = defineConfig({
   // ...
   modules: [