feat: Refresh payment collection + delete session (#6594)

### What
Add workflow for refreshing a payment collection. 

The idea is that on all cart updates, we want two things to happen (in the context of payments) 1. the currently active payment sessions should be destroyed, and 2. the payment collection should be updated with the new cart total.

We do this to ensure that we always collect the correct payment amount. 

From a customer perspective, this would mean that every time something on the cart is updated, the customer would need to enter their payment details anew. 

To me, this is a good tradeoff to avoid inconsistencies with payment collection.

Additionally, I updated the Payment Module interface with `upsert` and `updated` following our established convention.

### Note
This PR depends on a fix to the `remoteJoiner` that @carlos-r-l-rodrigues is working on.

Update: Fix merged in #6602 

Co-authored-by: Adrien de Peretti <25098370+adrien2p@users.noreply.github.com>

packages/types/src/payment/common.ts

@@ -114,7 +114,7 @@ export interface PaymentCollectionDTO {
   /**
    * Holds custom data in key-value pairs
    */
-  metadata?: Record<string, unknown> | null
+  metadata?: Record<string, unknown>
 
   /**
    * The status of the payment collection
@@ -417,6 +417,11 @@ export interface PaymentSessionDTO {
    */
   data: Record<string, unknown>
 
+  /**
+   * Payment session context
+   */
+  context?: Record<string, unknown>
+
   /**
    * The status of the payment session
    */

packages/types/src/payment/mutations.ts

@@ -1,4 +1,3 @@
-import { PaymentCollectionStatus } from "./common"
 import { PaymentProviderContext } from "./provider"
 
 /**
@@ -35,21 +34,24 @@ export interface UpdatePaymentCollectionDTO
    * The ID of the payment collection.
    */
   id: string
+}
 
-  /**
-   * The authorized amount of the payment collection.
-   */
-  authorized_amount?: number
+export interface UpsertPaymentCollectionDTO {
+  id?: string
+  region_id?: string
+  currency_code?: string
+  amount?: number
+  metadata?: Record<string, unknown>
+}
 
-  /**
-   * The refunded amount of the payment collection.
-   */
-  refunded_amount?: number
-
-  /**
-   * The status of the payment collection.
-   */
-  status?: PaymentCollectionStatus
+/**
+ * The attributes to update in the payment collection.
+ */
+export interface PaymentCollectionUpdatableFields {
+  region_id?: string
+  currency_code?: string
+  amount?: number
+  metadata?: Record<string, unknown>
 }
 
 /**

packages/types/src/payment/service.ts

@@ -20,10 +20,11 @@ import {
   CreatePaymentCollectionDTO,
   CreatePaymentSessionDTO,
   CreateRefundDTO,
+  PaymentCollectionUpdatableFields,
   ProviderWebhookPayload,
-  UpdatePaymentCollectionDTO,
   UpdatePaymentDTO,
   UpdatePaymentSessionDTO,
+  UpsertPaymentCollectionDTO,
 } from "./mutations"
 
 /**
@@ -164,33 +165,23 @@ export interface IPaymentModuleService extends IModuleService {
     sharedContext?: Context
   ): Promise<[PaymentCollectionDTO[], number]>
 
-  /**
-   * This method updates existing payment collections.
-   *
-   * @param {UpdatePaymentCollectionDTO[]} data - The attributes to update in payment collections.
-   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<PaymentCollectionDTO[]>} The updated payment collections.
-   *
-   * @example
-   * {example-code}
-   */
   updatePaymentCollections(
-    data: UpdatePaymentCollectionDTO[],
+    paymentCollectionId: string,
+    data: PaymentCollectionUpdatableFields,
+    sharedContext?: Context
+  ): Promise<PaymentCollectionDTO>
+  updatePaymentCollections(
+    selector: FilterablePaymentCollectionProps,
+    data: PaymentCollectionUpdatableFields,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO[]>
 
-  /**
-   * This method updates an existing payment collection.
-   *
-   * @param {UpdatePaymentCollectionDTO} data - The attributes to update in a payment collection.
-   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<PaymentCollectionDTO[]>} The updated payment collection.
-   *
-   * @example
-   * {example-code}
-   */
-  updatePaymentCollections(
-    data: UpdatePaymentCollectionDTO,
+  upsertPaymentCollections(
+    data: UpsertPaymentCollectionDTO[],
+    sharedContext?: Context
+  ): Promise<PaymentCollectionDTO[]>
+  upsertPaymentCollections(
+    data: UpsertPaymentCollectionDTO,
     sharedContext?: Context
   ): Promise<PaymentCollectionDTO>