feat(payment, payment-stripe): Add Stripe module provider (#6311)

packages/types/src/modules-sdk/index.ts

@@ -11,6 +11,7 @@ import { Logger } from "../logger"
 export type Constructor<T> = new (...args: any[]) => T
 export * from "../common/medusa-container"
 export * from "./internal-module-service"
+export * from "./module-provider"
 
 export type LogLevel =
   | "query"
@@ -290,13 +291,3 @@ export interface IModuleService {
     onApplicationStart?: () => Promise<void>
   }
 }
-
-export type ModuleProviderExports = {
-  services: Constructor<any>[]
-}
-
-export type ModuleProvider = {
-  resolve: string | ModuleProviderExports
-  provider_name?: string
-  options: Record<string, unknown>
-}

packages/types/src/modules-sdk/module-provider.ts

@@ -0,0 +1,11 @@
+import { Constructor } from "./index"
+
+export type ModuleProviderExports = {
+  services: Constructor<any>[]
+}
+
+export type ModuleProvider = {
+  resolve: string | ModuleProviderExports
+  provider_name?: string
+  options: Record<string, unknown>
+}

packages/types/src/payment/common.ts

@@ -280,6 +280,23 @@ export interface PaymentDTO {
   payment_session?: PaymentSessionDTO
 }
 
+export interface FilterablePaymentProps
+  extends BaseFilterable<FilterablePaymentProps> {
+  id?: string | string[]
+
+  session_id?: string | string[] | OperatorMap<string>
+
+  customer_id?: string | string[] | OperatorMap<string>
+  cart_id?: string | string[] | OperatorMap<string>
+  order_id?: string | string[] | OperatorMap<string>
+  order_edit_id?: string | string[] | OperatorMap<string>
+
+  created_at?: OperatorMap<string>
+  updated_at?: OperatorMap<string>
+  captured_at?: OperatorMap<string>
+  canceled_at?: OperatorMap<string>
+}
+
 /**
  * The capture details.
  */

packages/types/src/payment/mutations.ts

@@ -188,7 +188,7 @@ export interface CreatePaymentSessionDTO {
   /**
    * The provider's context.
    */
-  providerContext: PaymentProviderContext
+  providerContext: Omit<PaymentProviderContext, "resource_id">
 }
 
 /**
@@ -218,3 +218,21 @@ export interface CreatePaymentProviderDTO {
    */
   is_enabled?: boolean
 }
+
+/**
+ * Webhook
+ */
+export interface ProviderWebhookPayload {
+  provider: string
+  payload: {
+    /**
+     * Parsed webhook body
+     */
+    data: Record<string, unknown>
+    /**
+     * Raw request body
+     */
+    rawData: string | Buffer
+    headers: Record<string, unknown>
+  }
+}

packages/types/src/payment/provider.ts

@@ -1,4 +1,33 @@
 import { PaymentSessionStatus } from "./common"
+import { CustomerDTO } from "../customer"
+import { AddressDTO } from "../address"
+import { ProviderWebhookPayload } from "./mutations"
+
+export type PaymentAddressDTO = Partial<AddressDTO>
+
+export type PaymentCustomerDTO = Partial<CustomerDTO>
+
+/**
+ * Normalized events from payment provider to internal payment module events.
+ */
+export enum PaymentActions {
+  /**
+   * Payment session has been authorized and there are available funds for capture.
+   */
+  AUTHORIZED = "authorized",
+  /**
+   * Payment was successful and the mount is captured.
+   */
+  SUCCESSFUL = "captured",
+  /**
+   * Payment failed.
+   */
+  FAILED = "failed",
+  /**
+   * Received an event that is not processable.
+   */
+  NOT_SUPPORTED = "not_supported",
+}
 
 /**
  * @interface
@@ -9,7 +38,7 @@ export type PaymentProviderContext = {
   /**
    * The payment's billing address.
    */
-  billing_address?: Record<string, unknown> | null // TODO: revisit types
+  billing_address?: PaymentAddressDTO
   /**
    * The customer's email.
    */
@@ -23,17 +52,17 @@ export type PaymentProviderContext = {
    */
   amount: number
   /**
-   * The ID of the resource the payment is associated with. For example, the cart's ID.
+   * The ID of the resource the payment is associated with i.e. the ID of the PaymentSession in Medusa
    */
   resource_id: string
   /**
    * The customer associated with this payment.
    */
-  customer?: Record<string, unknown> // TODO: type
+  customer?: PaymentCustomerDTO
   /**
    * The context.
    */
-  context: Record<string, unknown>
+  context: { payment_description?: string } & Record<string, unknown>
   /**
    * If the payment session hasn't been created or initiated yet, it'll be an empty object.
    * If the payment session exists, it'll be the value of the payment session's `data` field.
@@ -88,6 +117,20 @@ export interface PaymentProviderError {
   detail?: any
 }
 
+export type WebhookActionData = {
+  resource_id: string
+  amount: number
+}
+
+export type WebhookActionResult =
+  | {
+      action: PaymentActions.NOT_SUPPORTED
+    }
+  | {
+      action: PaymentActions
+      data: WebhookActionData
+    }
+
 export interface IPaymentProvider {
   /**
    * @ignore
@@ -209,4 +252,15 @@ export interface IPaymentProvider {
   getPaymentStatus(
     paymentSessionData: Record<string, unknown>
   ): Promise<PaymentSessionStatus>
+
+  /**
+   * The method is called when å webhook call for this particular provider is received.
+   *
+   * The method is responsible for normalizing the received event and provide
+   *
+   * @param data - object containing provider id and data from the provider
+   */
+  getWebhookActionAndData(
+    data: ProviderWebhookPayload["payload"]
+  ): Promise<WebhookActionResult>
 }

packages/types/src/payment/service.ts

@@ -1,22 +1,23 @@
+import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 import { Context } from "../shared-context"
-import {
-  CreateCaptureDTO,
-  CreatePaymentCollectionDTO,
-  CreatePaymentDTO,
-  CreatePaymentSessionDTO,
-  CreateRefundDTO,
-  UpdatePaymentCollectionDTO,
-  UpdatePaymentDTO,
-  UpdatePaymentSessionDTO,
-} from "./mutations"
 import {
   FilterablePaymentCollectionProps,
+  FilterablePaymentProps,
   PaymentCollectionDTO,
   PaymentDTO,
   PaymentSessionDTO,
 } from "./common"
-import { FindConfig } from "../common"
+import {
+  CreateCaptureDTO,
+  CreatePaymentCollectionDTO,
+  CreatePaymentSessionDTO,
+  CreateRefundDTO,
+  ProviderWebhookPayload,
+  UpdatePaymentCollectionDTO,
+  UpdatePaymentDTO,
+  UpdatePaymentSessionDTO,
+} from "./mutations"
 
 /**
  * The main service interface for the payment module.
@@ -311,6 +312,24 @@ export interface IPaymentModuleService extends IModuleService {
 
   /* ********** PAYMENT ********** */
 
+  /**
+   * This method retrieves a paginated list of payments based on optional filters and configuration.
+   *
+   * @param {FilterablePaymentProps} filters - The filters to apply on the retrieved payment.
+   * @param {FindConfig<PaymentDTO>} config - The configurations determining how the payment is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a payment.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<PaymentDTO[]>} A list of payment.
+   *
+   * @example
+   * {example-code}
+   */
+  listPayments(
+    filters?: FilterablePaymentProps,
+    config?: FindConfig<PaymentDTO>,
+    sharedContext?: Context
+  ): Promise<PaymentDTO[]>
+
   /**
    * This method updates an existing payment.
    *
@@ -375,4 +394,21 @@ export interface IPaymentModuleService extends IModuleService {
    * {example-code}
    */
   createProvidersOnLoad(): Promise<void>
+
+  /* ********** HOOKS ********** */
+
+  processEvent(data: ProviderWebhookPayload): Promise<void>
+}
+
+export interface PaymentModuleOptions {
+  /**
+   * The delay in milliseconds before processing the webhook event.
+   * @defaultValue 5000
+   */
+  webhook_delay?: number
+  /**
+   * The number of times to retry the webhook event processing in case of an error.
+   * @defaultValue 3
+   */
+  webhook_retries?: number
 }