chore: add TSDocs to the Payment Module (#6885)

2024-04-05 12:01:36 +02:00
parent d345496dbc
commit 4c374e3a14
6 changed files with 1035 additions and 173 deletions
@@ -10,27 +10,154 @@ import {
  WebhookActionResult
 } from "@medusajs/types"

+/**
+ * ## Overview
+ *
+ * A payment provider is used to handle and process payments, such as authorizing, capturing, and refund payments.
+ *
+ * Refer to [this guide](https://docs.medusajs.com/experimental/payment/payment-provider/) to learn more about payment providers.
+ * 
+ * Refer to [this guide](https://docs.medusajs.com/experimental/payment/payment-flow/) to learn more about the payment flow.
+ * 
+ * ---
+ * 
+ * ## How to Create a Payment Provider
+ * 
+ * A payment provider is a TypeScript or JavaScript class that extends the `AbstractPaymentProvider` class imported from `@medusajsa/utils`.
+ * 
+ * You can create the payment provider in a module or plugin, then pass that module/plugin in the Payment Module's `providers` option. You can also pass the path to the file
+ * that defines the provider if it's created in the Medusa application's codebase.
+ * 
+ * For example:
+ * 
+ * ```ts
+ * abstract class MyPayment extends AbstractPaymentProvider<MyConfigurations> {
+ *   // ...
+ * }
+ * ```
+ *
+ * ---
+ * 
+ * ## Configuration Type Parameter
+ * 
+ * The `AbstractPaymentProvider` class accepts an optional type parameter that defines the type of configuration that your payment provider expects.
+ * 
+ * For example:
+ * 
+ * ```ts
+ * interface MyConfigurations {
+ *   apiKey: string
+ * }
+ * 
+ * abstract class MyPayment extends AbstractPaymentProvider<MyConfigurations> {
+ *   // ...
+ * }
+ * ```
+ * 
+ * ---
+ *
+ * ## Identifier Property
+ *
+ * The `PaymentProvider` data model has 2 properties: `id` and `is_enabled`.
+ *
+ * ```ts
+ * class MyPaymentProvider extends AbstractPaymentProvider<MyConfigurations> {
+ *   static identifier = "my-payment"
+ *   // ...
+ * }
+ * ```
+ *
+ * ---
+ *
+ * ## PROVIDER Property
+ *
+ * The `PROVIDER` static property is used when registering the provider in the dependency container. Typically, it would have the
+ * same value as the `identifier` property.
+ *
+ * ```ts
+ * class MyPaymentProvider extends AbstractPaymentProvider<MyConfigurations> {
+ *   static PROVIDER = "my-payment"
+ *   // ...
+ * }
+ * ```
+ *
+ * ---
+ *
+ * ## PaymentProviderError
+ *
+ * Before diving into the methods of the Payment Provider, you'll notice that part of the expected return signature of these method includes `PaymentProviderError`.
+ *
+ * ```ts
+ * interface PaymentProviderError {
+ *   error: string
+ *   code?: string
+ *   detail?: any
+ * }
+ * ```
+ *
+ * While implementing the Payment Provider's methods, if you need to inform the Payment Module that an error occurred at a certain stage,
+ * return an object having the attributes defined in the `PaymentProviderError` interface.
+ *
+ * For example, the Stripe payment provider has the following method to create the error object, which is used within other methods:
+ *
+ * ```ts
+ * abstract class StripeBase extends AbstractPaymentProvider {
+ *   // ...
+ *   protected buildError(
+ *    message: string,
+ *    error: Stripe.StripeRawError | PaymentProviderError | Error
+ *  ): PaymentProviderError {
+ *    return {
+ *      error: message,
+ *      code: "code" in error ? error.code : "unknown",
+ *      detail: isPaymentProviderError(error)
+ *        ? `${error.error}${EOL}${error.detail ?? ""}`
+ *        : "detail" in error
+ *        ? error.detail
+ *        : error.message ?? "",
+ *    }
+ *  }
+ *
+ *   // used in other methods
+ *   async retrievePayment(
+ *     paymentSessionData: Record<string, unknown>
+ *   ): Promise<
+ *     PaymentProviderError |
+ *     PaymentProviderSessionResponse["session_data"]
+ *   > {
+ *     try {
+ *       // ...
+ *     } catch (e) {
+ *       return this.buildError(
+ *         "An error occurred in retrievePayment",
+ *         e
+ *       )
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ */
 export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
  implements IPaymentProvider
 {
  /**
-   * You can use the `constructor` of your Payment Provider to have access to different services in Medusa through [dependency injection](https://docs.medusajs.com/development/fundamentals/dependency-injection).
+   * You can use the `constructor` of your Payment Provider to have access to resources in your application through the [dependency container](https://docs.medusajs.com/development/fundamentals/dependency-injection).
   *
   * 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.
   *
-   * Additionally, if you’re creating your Payment Provider as an external plugin to be installed on any Medusa backend and you want to access the options added for the plugin,
-   * you can access it in the constructor. The options are passed as a second parameter.
+   * The payment provider also can access the configurations of the module or plugin it's created in as a second parameter.
   *
-   * @param {MedusaContainer} container - An instance of `MedusaContainer` that allows you to access other resources, such as services, in your Medusa backend through [dependency injection](https://docs.medusajs.com/development/fundamentals/dependency-injection)
-   * @param {Record<string, unknown>} config - If this payment processor is created in a plugin, the plugin's options are passed in this parameter.
+   * @param {MedusaContainer} container - An instance of `MedusaContainer` that allows you to access other resources in the [dependency container](https://docs.medusajs.com/development/fundamentals/dependency-injection)
+   * @param {Record<string, unknown>} config - If this provider processor is created in a module or plugin, their options are passed in this parameter.
   *
   * @example
   * ```ts
-   * class MyPaymentService extends AbstractPaymentProvider {
+   * class MyPaymentProvider extends AbstractPaymentProvider<MyConfigurations> {
   *   // ...
-   *   constructor(container, options) {
-   *     super(container)
+   *   constructor(container, config) {
+   *     super(container, config)
   *     // you can access options here
   *
   *     // you can also initialize a client that
@@ -59,13 +186,10 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
  }

  /**
-   * The `PaymentProvider` entity has 2 properties: `id` and `is_installed`. The `identifier` property in the payment provider service is used when the payment provider is added to the database.
-   *
-   * The value of this property is also used to reference the payment provider throughout Medusa.
-   * For example, it is used to [add a payment provider](https://docs.medusajs.com/api/admin#regions_postregionsregionpaymentproviders) to a region.
+   * The `PaymentProvider` data model has 2 properties: `id` and `is_enabled`.
   *
   * ```ts
-   * class MyPaymentService extends AbstractPaymentProvider {
+   * class MyPaymentProvider extends AbstractPaymentProvider<MyConfigurations> {
   *   static identifier = "my-payment"
   *   // ...
   * }
@@ -137,6 +261,9 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
  ): Promise<WebhookActionResult>
 }

+/**
+ * @ignore
+ */
 export function isPaymentProviderError(obj: any): obj is PaymentProviderError {
  return (
    obj &&