From 5ed5b45cce4330c464aea584171bfedd8d9d5364 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 1 Aug 2024 18:50:34 +0300 Subject: [PATCH] chore(utils, types): updated TSDocs of AbstractPaymentProvider (#8335) - Update the TSDocs of `AbstractPaymentProvider` - Remove old TSDocs of `IPaymentProvider` - Update the config that generates the payment module provider reference. Closes DOCS-781 --- packages/core/types/src/payment/provider.ts | 89 +-- .../src/payment/abstract-payment-provider.ts | 701 ++++++++++++++---- .../merger-custom-options/auth-provider.ts | 2 +- .../constants/merger-custom-options/file.ts | 2 +- .../fulfillment-provider.ts | 2 +- .../merger-custom-options/notification.ts | 2 +- .../merger-custom-options/payment-provider.ts | 72 ++ 7 files changed, 629 insertions(+), 241 deletions(-) diff --git a/packages/core/types/src/payment/provider.ts b/packages/core/types/src/payment/provider.ts index 9d17846cb2..bfeac41f11 100644 --- a/packages/core/types/src/payment/provider.ts +++ b/packages/core/types/src/payment/provider.ts @@ -218,135 +218,48 @@ export interface IPaymentProvider { /** * @ignore * - * Return a unique identifier to retrieve the payment plugin provider + * Return a unique identifier to retrieve the payment module provider */ getIdentifier(): string - /** - * This methods sends a request to the third-party provider to initialize the payment. It's called when the payment session is created. - * - * For example, in the Stripe provider, this method is used to create a Payment Intent for the customer. - * - * @param {CreatePaymentProviderSession} data - The data necessary to initiate the payment. - * @returns {Promise} Either the payment's data, which is stored in the `data` field - * of the payment session, or an error object. - */ initiatePayment( data: CreatePaymentProviderSession ): Promise - /** - * This method is used to update a payment associated with a session in the third-party provider. - * - * @param {UpdatePaymentProviderSession} context - The data related to the update. - * @returns {Promise} Either the payment's data or an error object. - */ updatePayment( context: UpdatePaymentProviderSession ): Promise - /** - * This method is called before a payment session is deleted. It's used to perform any actions necessary before the deletion. - * - * @param {Record} paymentSessionData - The `data` field of the Payment Session. - * @returns {Promise} Either an error object or an empty object. - */ deletePayment( paymentSessionData: Record ): Promise - /** - * This method is called when a payment session should be authorized. - * You can interact with a third-party provider and perform the necessary actions to authorize the payment. - * - * Refer to [this guide](https://docs.medusajs.com/experimental/payment/payment-flow/#3-authorize-payment-session) - * to learn more about how this fits into the payment flow and how to handle required actions. - * - * @param {Record} paymentSessionData - The `data` field of the payment session. - * @param {Record} context - The context of the authorization. - * @returns {Promise} The authorization details or an error object. If - * the authorization details are returned, the `data` and `status` field are set in the associated payment session. - */ authorizePayment( paymentSessionData: Record, context: Record ): Promise - /** - * This method is called when a payment should be captured. The payment is captured in one of the following scenarios: - * - * - The payment provider supports automatically capturing the payment after authorization. - * - The merchant requests to capture the payment after its associated payment session was authorized. - * - A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in [this guide](https://docs.medusajs.com/experimental/payment/webhook-events/) - * - * In this method, you can interact with the third-party provider and perform any actions necessary to capture the payment. - * - * @param {Record} paymentSessionData - The `data` field of the payment. - * @returns {Promise} Either an error object or a value that's stored in the `data` field of the payment. - */ capturePayment( paymentSessionData: Record ): Promise - /** - * This method is called when a payment should be refunded. This is typically triggered manually by the merchant. - * - * In this method, you can interact with the third-party provider and perform any actions necessary to refund the payment. - * - * @param {Record} paymentSessionData - The `data` field of a Payment. - * @param {BigNumberInput} refundAmount - The amount to refund. - * @returns {Promise} Either an error object or an object that's stored in the `data` field of the payment. - */ refundPayment( paymentSessionData: Record, refundAmount: BigNumberInput ): Promise - /** - * This method is used to provide a uniform way of retrieving the payment information from the third-party provider. - * - * For example, in Stripe’s payment provider this method is used to retrieve the payment intent details from Stripe. - * - * @param {Record} paymentSessionData - - * The `data` field of a payment session. Make sure to store in the `data` field any necessary data that would allow you to retrieve the payment data from the third-party provider. - * @returns {Promise} Either an error object or the payment's data retrieved from a third-party provider. - */ retrievePayment( paymentSessionData: Record ): Promise - /** - * This method is called when a payment is canceled. - * - * In this method, you can interact with the third-party provider and perform any actions necessary to cancel the payment. - * - * @param {Record} paymentSessionData - The `data` field of the payment. - * @returns {Promise} Either an error object or a value that's stored in the `data` field of the payment. - */ cancelPayment( paymentSessionData: Record ): Promise - /** - * This method is used to get the status of a payment or a payment session. - * - * @param {Record} paymentSessionData - - * The `data` field of a payment as a parameter. You can use this data to interact with the third-party provider to check the status of the payment if necessary. - * @returns {Promise} The status of the payment or payment session. - */ getPaymentStatus( paymentSessionData: Record ): Promise - /** - * The method is called when a webhook event is received for this provider. - * - * The method is responsible for normalizing the received event and inform the Payment Module of actions to perform, such as authorize or capture payment. - * - * Learn more about handling webhook events in [this guide](https://docs.medusajs.com/experimental/payment/webhook-events/) - * - * @param data - The webhook event's details. - */ getWebhookActionAndData( data: ProviderWebhookPayload["payload"] ): Promise diff --git a/packages/core/utils/src/payment/abstract-payment-provider.ts b/packages/core/utils/src/payment/abstract-payment-provider.ts index 31b43d9998..4543e78d7e 100644 --- a/packages/core/utils/src/payment/abstract-payment-provider.ts +++ b/packages/core/utils/src/payment/abstract-payment-provider.ts @@ -10,164 +10,63 @@ import { WebhookActionResult } from "@medusajs/types" -/** - * ## Overview - * - * A payment provider is used to handle and process payments, such as authorizing, capturing, and refund payments. - * - * :::note - * - * This guide is a work in progress. - * - * ::: - * - * --- - * - * ## 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 { - * // ... - * } - * ``` - * - * --- - * - * ## 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 { - * // ... - * } - * ``` - * - * --- - * - * ## Identifier Property - * - * The `PaymentProvider` data model has 2 properties: `id` and `is_enabled`. - * - * ```ts - * class MyPaymentProvider extends AbstractPaymentProvider { - * static identifier = "my-payment" - * // ... - * } - * ``` - * - * --- - * - * ## PROVIDER Property - * - * The `PROVIDER` static property is used when registering the provider in the module's container. Typically, it would have the - * same value as the `identifier` property. - * - * ```ts - * class MyPaymentProvider extends AbstractPaymentProvider { - * 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 - * ): Promise< - * PaymentProviderError | - * PaymentProviderSessionResponse["session_data"] - * > { - * try { - * // ... - * } catch (e) { - * return this.buildError( - * "An error occurred in retrievePayment", - * e - * ) - * } - * } - * } - * ``` - * - */ + export abstract class AbstractPaymentProvider> implements IPaymentProvider { /** - * You can use the `constructor` of your payment provider to have access to resources in your application through the module's container. + * 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 payment provider also can access the configurations of the module or plugin it's created in as a second parameter. + * The provider can also access the module's options as a second parameter. * - * @param {MedusaContainer} container - An instance of `MedusaContainer` that allows you to access other resources in the module's container. - * @param {Record} config - If this provider processor is created in a module or plugin, their options are passed in this parameter. + * @param {MedusaContainer} container - The module's container used to resolve resources. + * @param {Record} config - The options passed to the payment module provider. * * @example * ```ts - * class MyPaymentProvider extends AbstractPaymentProvider { - * // ... - * constructor(container, config) { - * super(container, config) - * // you can access options here - * - * // you can also initialize a client that - * // communicates with a third-party service. + * import { + * AbstractPaymentProvider + * } from "@medusajs/utils" + * import { Logger } from "@medusajs/types" + * + * type InjectedDependencies = { + * logger: Logger + * } + * + * type Options = { + * apiKey: string + * } + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * 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 * ``` */ protected constructor( @@ -188,10 +87,12 @@ export abstract class AbstractPaymentProvider> } /** - * The `PaymentProvider` data model has 2 properties: `id` and `is_enabled`. - * - * ```ts - * class MyPaymentProvider extends AbstractPaymentProvider { + * Each payment provider has a unique identifier defined in its class. + * + * @example + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { * static identifier = "my-payment" * // ... * } @@ -214,50 +115,552 @@ export abstract class AbstractPaymentProvider> return ctr.identifier } + /** + * This method is used to capture a payment. The payment is captured in one of the following scenarios: + * + * - The {@link authorizePayment} method returns the status `captured`, which automatically executed this method after authorization. + * - The merchant requests to capture the payment after its associated payment session was authorized. + * - A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in [this guide](https://docs.medusajs.com/v2/resources/commerce-modules/payment/webhook-events). + * + * In this method, use the third-party provider to capture the payment. + * + * @param paymentData - The `data` property of the payment. Make sure to store in it + * any helpful identification for your third-party integration. + * @returns The new data to store in the payment's `data` property, or an error object. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async capturePayment( + * paymentData: Record + * ): Promise { + * const externalId = paymentData.id + * + * try { + * const newData = await this.client.capturePayment(externalId) + * + * return { + * ...newData, + * id: externalId + * } + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract capturePayment( - paymentSessionData: Record + paymentData: Record ): Promise + /** + * This method authorizes a payment session. When authorized successfully, a payment is created by the Payment + * Module which can be later captured using the {@link capturePayment} method. + * + * Refer to [this guide](https://docs.medusajs.com/v2/resources/commerce-modules/payment/payment-flow#3-authorize-payment-session) + * to learn more about how this fits into the payment flow and how to handle required actions. + * + * To automatically capture the payment after authorization, return the status `captured`. + * + * @param paymentSessionData - The `data` property of the payment session. Make sure to store in it + * any helpful identification for your third-party integration. + * @param context - The context in which the payment is being authorized. For example, in checkout, + * the context has a `cart_id` property indicating the ID of the associated cart. + * @returns Either an object of the new data to store in the created payment's `data` property and the + * payment's status, or an error object. Make sure to set in `data` anything useful to later retrieve the session. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * PaymentSessionStatus + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async authorizePayment( + * paymentSessionData: Record, + * context: Record + * ): Promise< + * PaymentProviderError | { + * status: PaymentSessionStatus + * data: PaymentProviderSessionResponse["data"] + * } + * > { + * const externalId = paymentSessionData.id + * + * try { + * const paymentData = await this.client.authorizePayment(externalId) + * + * return { + * data: { + * ...paymentData, + * id: externalId + * }, + * status: "authorized" + * } + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract authorizePayment( paymentSessionData: Record, context: Record ): Promise< | PaymentProviderError | { + /** + * The new status of the payment. + */ status: PaymentSessionStatus + /** + * The data to store in the created payment's `data` property. + */ data: PaymentProviderSessionResponse["data"] } > + /** + * This method cancels a payment. + * + * @param paymentData - The `data` property of the payment. Make sure to store in it + * any helpful identification for your third-party integration. + * @returns An error object if an error occurs, or the data received from the integration. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async cancelPayment( + * paymentData: Record + * ): Promise { + * const externalId = paymentData.id + * + * try { + * const paymentData = await this.client.cancelPayment(externalId) + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract cancelPayment( - paymentSessionData: Record + paymentData: Record ): Promise + /** + * This method is used when a payment session is created. It can be used to initiate the payment + * in the third-party session, before authorizing or capturing the payment later. + * + * @param context - The details of the payment session and its context. + * @returns An object whose `data` property is set in the created payment session, or an error + * object. Make sure to set in `data` anything useful to later retrieve the session. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async initiatePayment( + * context: CreatePaymentProviderSession + * ): Promise { + * const { + * amount, + * currency_code, + * context: customerDetails + * } = context + * + * try { + * const response = await this.client.init( + * amount, currency_code, customerDetails + * ) + * + * return { + * ...response, + * data: { + * id: response.id + * } + * } + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract initiatePayment( context: CreatePaymentProviderSession ): Promise + /** + * This method is used when a payment session is deleted, which can only happen if it isn't authorized, yet. + * + * Use this to delete or cancel the payment in the third-party service. + * + * @param paymentSessionData - The `data` property of the payment session. Make sure to store in it + * any helpful identification for your third-party integration. + * @returns An error object or the response from the third-party service. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async deletePayment( + * paymentSessionData: Record + * ): Promise< + * PaymentProviderError | PaymentProviderSessionResponse["data"] + * > { + * const externalId = paymentSessionData.id + * + * try { + * await this.client.cancelPayment(externalId) + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract deletePayment( paymentSessionData: Record ): Promise + /** + * This method gets the status of a payment session based on the status in the third-party integration. + * + * @param paymentSessionData - The `data` property of the payment session. Make sure to store in it + * any helpful identification for your third-party integration. + * @returns The payment session's status. + * + * @example + * // other imports... + * import { + * PaymentSessionStatus + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async getPaymentStatus( + * paymentSessionData: Record + * ): Promise { + * const externalId = paymentSessionData.id + * + * try { + * const status = await this.client.getStatus(externalId) + * + * switch (status) { + * case "requires_capture": + * return "authorized" + * case "success": + * return "captured" + * case "canceled": + * return "canceled" + * default: + * return "pending" + * } + * } catch (e) { + * return "error" + * } + * } + * + * // ... + * } + */ abstract getPaymentStatus( paymentSessionData: Record ): Promise + /** + * This method refunds an amount of a payment previously captured. + * + * @param paymentData - The `data` property of the payment. Make sure to store in it + * any helpful identification for your third-party integration. + * @param refundAmount The amount to refund. + * @returns The new data to store in the payment's `data` property, or an error object. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async refundPayment( + * paymentData: Record, + * refundAmount: number + * ): Promise< + * PaymentProviderError | PaymentProviderSessionResponse["data"] + * > { + * const externalId = paymentData.id + * + * try { + * const newData = await this.client.refund( + * externalId, + * refundAmount + * ) + * + * return { + * ...newData, + * id: externalId + * } + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract refundPayment( - paymentSessionData: Record, + paymentData: Record, refundAmount: number ): Promise + /** + * Retrieves the payment's data from the third-party service. + * + * @param paymentSessionData - The `data` property of the payment. Make sure to store in it + * any helpful identification for your third-party integration. + * @returns An object to be stored in the payment's `data` property, or an error object. + * + * @example + * // other imports... + * import { + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async retrievePayment( + * paymentSessionData: Record + * ): Promise< + * PaymentProviderError | PaymentProviderSessionResponse["data"] + * > { + * const externalId = paymentSessionData.id + * + * try { + * return await this.client.retrieve(externalId) + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract retrievePayment( paymentSessionData: Record ): Promise + /** + * Update a payment in the third-party service that was previously initiated with the {@link initiatePayment} method. + * + * @param context - The details of the payment session and its context. + * @returns An object whose `data` property is set in the updated payment session, or an error + * object. Make sure to set in `data` anything useful to later retrieve the session. + * + * @example + * // other imports... + * import { + * UpdatePaymentProviderSession, + * PaymentProviderError, + * PaymentProviderSessionResponse, + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async updatePayment( + * context: UpdatePaymentProviderSession + * ): Promise { + * const { + * amount, + * currency_code, + * context: customerDetails, + * data + * } = context + * const externalId = data.id + * + * try { + * const response = await this.client.update( + * externalId, + * { + * amount, + * currency_code, + * customerDetails + * } + * ) + * + * return { + * ...response, + * data: { + * id: response.id + * } + * } + * } catch (e) { + * return { + * error: e, + * code: "unknown", + * detail: e + * } + * } + * } + * + * // ... + * } + */ abstract updatePayment( context: UpdatePaymentProviderSession ): Promise + /** + * This method is executed when a webhook event is received from the third-party payment provider. Use it + * to process the action of the payment provider. + * + * Learn more in [this documentation](https://docs.medusajs.com/v2/resources/commerce-modules/payment/webhook-events) + * + * @param data - The webhook event's data + * @returns The webhook result. If the `action`'s value is `captured`, the payment is captured within Medusa as well. + * If the `action`'s value is `authorized`, the associated payment session is authorized within Medusa. + * + * @example + * // other imports... + * import { + * BigNumber + * } from "@medusajs/utils" + * import { + * ProviderWebhookPayload, + * WebhookActionResult + * } from "@medusajs/types" + * + * + * class MyPaymentProviderService extends AbstractPaymentProvider< + * Options + * > { + * async getWebhookActionAndData( + * payload: ProviderWebhookPayload["payload"] + * ): Promise { + * const { + * data, + * rawData, + * headers + * } = payload + * + * try { + * switch(data.event_type) { + * case "authorized_amount": + * return { + * action: "authorized", + * data: { + * session_id: (data.metadata as Record).session_id, + * amount: new BigNumber(data.amount as number) + * } + * } + * case "success": + * return { + * action: "captured", + * data: { + * session_id: (data.metadata as Record).session_id, + * amount: new BigNumber(data.amount as number) + * } + * } + * default: + * return { + * action: "not_supported" + * } + * } + * } catch (e) { + * return { + * action: "failed", + * data: { + * session_id: (data.metadata as Record).session_id, + * amount: new BigNumber(data.amount as number) + * } + * } + * } + * } + * + * // ... + * } + */ abstract getWebhookActionAndData( data: ProviderWebhookPayload["payload"] ): Promise diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts index c9ab88957f..eb05da2a00 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts @@ -48,7 +48,7 @@ export default { This exports the module's definition, indicating that the \`MyAuthProviderService\` is the module's service.`, `## 4. Use Module -To use your Auth Provider Module, add it to the \`providers\` array of the Auth Module: +To use your Auth Module Provider, add it to the \`providers\` array of the Auth Module: \`\`\`js title="medusa-config.js" import { Modules } from "@medusajs/utils" diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts index 31f4b6f149..71d2afa488 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts @@ -48,7 +48,7 @@ export default { This exports the module's definition, indicating that the \`MyFileProviderService\` is the module's service.`, `## 4. Use Module -To use your File Provider Module, add it to the \`providers\` array of the File Module: +To use your File Module Provider, add it to the \`providers\` array of the File Module: diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts index 1bc3f75bd7..20821f2990 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts @@ -48,7 +48,7 @@ export default { This exports the module's definition, indicating that the \`MyFulfillmentProviderService\` is the module's service.`, `## 4. Use Module -To use your Fulfillment Provider Module, add it to the \`providers\` array of the Fulfillment Module: +To use your Fulfillment Module Provider, add it to the \`providers\` array of the Fulfillment Module: \`\`\`js title="medusa-config.js" import { Modules } from "@medusajs/utils" diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts index 4bd8d83401..531df09646 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts @@ -52,7 +52,7 @@ export default { This exports the module's definition, indicating that the \`MyNotificationProviderService\` is the module's service.`, `## 4. Use Module -To use your Notification Provider Module, add it to the \`providers\` array of the Notification Module: +To use your Notification Module Provider, add it to the \`providers\` array of the Notification Module: diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts index 64b4fa4fc7..496a0bd526 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts @@ -15,6 +15,78 @@ const paymentProviderOptions: FormattingOptionsType = { reflectionGroups: { Properties: false, }, + shouldIncrementAfterStartSections: true, + expandMembers: true, + startSections: [ + `## 1. Create Module Directory + +Start by creating a new directory for your module. For example, \`src/modules/my-payment\`.`, + `## 2. Create the Payment Provider Service + +Create the file \`src/modules/my-payment/service.ts\` that holds the module's main service. It must extend the \`AbstractPaymentProvider\` class imported from \`@medusajs/utils\`: + +\`\`\`ts title="src/modules/my-payment/service.ts" +import { AbstractPaymentProvider } from "@medusajs/utils" + +type Options = { + apiKey: string +} + +class MyPaymentProviderService extends AbstractPaymentProvider< + Options +> { + // TODO implement methods +} + +export default MyPaymentProviderService +\`\`\``, + ], + endSections: [ + `## 3. Create Module Definition File + +Create the file \`src/modules/my-payment/index.ts\` with the following content: + +\`\`\`ts title="src/modules/my-payment/index.ts" +import MyPaymentProviderService from "./service" + +export default { + services: [MyPaymentProviderService], +} +\`\`\` + +This exports the module's definition, indicating that the \`MyPaymentProviderService\` is the module's service.`, + `## 4. Use Module + +To use your Payment Module Provider, add it to the \`providers\` array of the Payment Module: + +\`\`\`js title="medusa-config.js" +import { Modules } from "@medusajs/utils" + +// ... + +module.exports = defineConfig({ + // ... + modules: { + [Modules.PAYMENT]: { + resolve: "@medusajs/payment", + options: { + providers: [ + { + resolve: "./modules/my-payment", + id: "my-payment", + options: { + // provider options... + apiKey: "..." + } + } + ] + } + } + } +}) +\`\`\` +`, + ], }, }