@commercetools/checkout-payments-processor-sdk 0.0.6

package/src/commercetools/services/ct-payment.service.ts

@@ -0,0 +1,574 @@
+import { randomInt } from 'node:crypto';
+import type {
+  CustomFieldsDraft,
+  LocalizedString,
+  Payment,
+  PaymentAddInterfaceInteractionAction,
+  PaymentAddTransactionAction,
+  PaymentChangeTransactionInteractionIdAction,
+  PaymentChangeTransactionStateAction,
+  PaymentDraft,
+  PaymentSetCustomTypeAction,
+  PaymentSetInterfaceIdAction,
+  PaymentSetMethodInfoCustomTypeAction,
+  PaymentSetMethodInfoInterfaceAccountAction,
+  PaymentSetMethodInfoInterfaceAction,
+  PaymentSetMethodInfoMethodAction,
+  PaymentSetMethodInfoNameAction,
+  PaymentSetMethodInfoTokenAction,
+  PaymentUpdateAction,
+  Transaction,
+  TransactionDraft,
+  TransactionState,
+} from '@commercetools/platform-sdk';
+import type { Logger } from '@logger-types';
+import { CommercetoolsAPIError } from '@/commercetools/errors/ct-api.error.js';
+import type { CommercetoolsAPI } from '@/commercetools/types/api.type.js';
+import type {
+  FindPaymentsByInterfaceId,
+  FindTransaction,
+  GetPayment,
+  PaymentService,
+  PaymentServiceOptions,
+  TransactionData,
+  UpdatePaymentInfo,
+} from '@/commercetools/types/payment.type.js';
+
+/**
+ * This is the default implementation of the PaymentService interface.
+ */
+export class DefaultPaymentService implements PaymentService {
+  private ctAPI: CommercetoolsAPI;
+  private logger: Logger;
+
+  constructor(opts: PaymentServiceOptions) {
+    this.ctAPI = opts.ctAPI;
+    this.logger = opts.logger;
+  }
+
+  public async getPayment(opts: GetPayment): Promise<Payment> {
+    return await this.ctAPI.payment.getPaymentById(opts.id);
+  }
+
+  public async findPaymentsByInterfaceId(
+    opts: FindPaymentsByInterfaceId,
+  ): Promise<Payment[]> {
+    const predicate = `interfaceId="${opts.interfaceId}"`;
+    return (await this.ctAPI.payment.find(predicate)).results;
+  }
+
+  public async createPayment(draft: PaymentDraft): Promise<Payment> {
+    return await this.ctAPI.payment.createPayment(draft);
+  }
+
+  public async updatePayment(opts: UpdatePaymentInfo): Promise<Payment> {
+    const maxRetries = 3;
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      const payment = await this.getPayment({ id: opts.id });
+      const actions = this.consolidateUpdateActions(payment, opts);
+      this.logger.info(
+        {
+          paymentId: payment.id,
+          paymentVersion: payment.version,
+          actions,
+          attempt,
+        },
+        'Updating payment with actions',
+      );
+
+      if (actions.length === 0) {
+        this.logger.info(
+          { paymentId: payment.id, paymentVersion: payment.version, attempt },
+          'Update payment skipped, no actions to perform',
+        );
+        return payment;
+      }
+
+      try {
+        return await this.ctAPI.payment.updatePayment({
+          resource: {
+            id: payment.id,
+            version: payment.version,
+          },
+          actions,
+        });
+      } catch (e) {
+        lastError = e;
+
+        const isRetryableError =
+          e instanceof CommercetoolsAPIError &&
+          (e.httpErrorStatus === 409 ||
+            (e.httpErrorStatus === 400 &&
+              e.message.includes(
+                'already used without setting a payment interface',
+              )));
+
+        if (isRetryableError && attempt < maxRetries - 1) {
+          const delayMs = this.calculateExponentialBackoff(attempt);
+          this.logger.warn(
+            {
+              paymentId: payment.id,
+              paymentVersion: payment.version,
+              attempt,
+              delayMs,
+              err: e,
+            },
+            'Unable to update the payment, retrying',
+          );
+          await this.sleep(delayMs);
+          continue;
+        }
+
+        this.logger.error(
+          {
+            paymentId: payment.id,
+            paymentVersion: payment.version,
+            attempt,
+            err: e,
+          },
+          'Unable to update the payment, abort',
+        );
+        throw e;
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Calculates exponential backoff delay with jitter
+   * @param attempt - Current attempt number (0-based)
+   * @returns Delay in milliseconds
+   */
+  private calculateExponentialBackoff(attempt: number): number {
+    const baseDelayMs = 100;
+    const maxDelayMs = 2000;
+    const jitterMs = 100;
+
+    const exponentialDelay = baseDelayMs * 2 ** attempt;
+    const jitter = randomInt(0, jitterMs);
+    return Math.min(exponentialDelay + jitter, maxDelayMs);
+  }
+
+  /**
+   * Sleep for a specified duration
+   * @param ms - Duration in milliseconds
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  private consolidateUpdateActions(
+    payment: Payment,
+    updateInfo: UpdatePaymentInfo,
+  ): PaymentUpdateAction[] {
+    const actions: PaymentUpdateAction[] = [];
+
+    if (!payment.interfaceId && updateInfo.pspReference) {
+      actions.push(this.populateSetInterfaceIdAction(updateInfo.pspReference));
+    }
+
+    /**
+     * old way
+     */
+    if (!payment.paymentMethodInfo?.method && updateInfo.paymentMethod) {
+      actions.push(this.populateSetPaymentMethod(updateInfo.paymentMethod));
+    }
+
+    if (!payment.paymentMethodInfo?.token && updateInfo.token) {
+      actions.push(this.populateSetMethodInfoToken(updateInfo.token));
+    }
+
+    /**
+     * New way
+     */
+    if (
+      !payment.paymentMethodInfo?.method &&
+      updateInfo.paymentMethodInfo?.method
+    ) {
+      actions.push(
+        this.populateSetPaymentMethod(updateInfo.paymentMethodInfo.method),
+      );
+    }
+
+    if (
+      !payment.paymentMethodInfo?.token &&
+      updateInfo.paymentMethodInfo?.token?.value
+    ) {
+      actions.push(
+        this.populateSetMethodInfoToken(
+          updateInfo.paymentMethodInfo.token.value,
+        ),
+      );
+    }
+
+    if (
+      !payment.paymentMethodInfo?.name &&
+      updateInfo.paymentMethodInfo?.name
+    ) {
+      actions.push(
+        this.populateSetMethodInfoName(updateInfo.paymentMethodInfo.name),
+      );
+    }
+
+    if (
+      !payment.paymentMethodInfo?.paymentInterface &&
+      updateInfo.paymentMethodInfo?.paymentInterface
+    ) {
+      actions.push(
+        this.populateSetMethodInfoInterface(
+          updateInfo.paymentMethodInfo.paymentInterface,
+        ),
+      );
+    }
+
+    if (
+      !payment.paymentMethodInfo?.interfaceAccount &&
+      updateInfo.paymentMethodInfo?.interfaceAccount
+    ) {
+      actions.push(
+        this.populateSetMethodInfoInterfaceAccount(
+          updateInfo.paymentMethodInfo.interfaceAccount,
+        ),
+      );
+    }
+
+    if (updateInfo.paymentMethodInfo?.custom) {
+      actions.push(
+        this.populateSetMethodInfoCustomType(
+          updateInfo.paymentMethodInfo.custom,
+        ),
+      );
+    }
+
+    if (updateInfo.transaction) {
+      const transactionChanges = this.consolidateTransactionChanges(
+        payment,
+        updateInfo.transaction,
+      );
+      if (transactionChanges.length > 0) {
+        actions.push(...transactionChanges);
+      }
+    }
+
+    if (updateInfo.customFields) {
+      actions.push(this.populateSetCustomType(updateInfo.customFields));
+    }
+
+    if (updateInfo.pspInteractions && updateInfo.pspInteractions.length > 0) {
+      actions.push(
+        ...this.populateAddInterfaceInteractions(updateInfo.pspInteractions),
+      );
+    }
+
+    return actions;
+  }
+
+  private populateSetInterfaceIdAction(
+    interfaceId: string,
+  ): PaymentSetInterfaceIdAction {
+    return {
+      action: 'setInterfaceId',
+      interfaceId,
+    };
+  }
+
+  private populateChangeTransactionInteractionId(
+    txId: string,
+    interactionId: string,
+  ): PaymentChangeTransactionInteractionIdAction {
+    return {
+      action: 'changeTransactionInteractionId',
+      transactionId: txId,
+      interactionId,
+    };
+  }
+
+  private populateSetTransactionInterfaceId(
+    txId: string,
+    interfaceId: string,
+  ): PaymentUpdateAction {
+    return {
+      action: 'setTransactionInterfaceId',
+      transactionId: txId,
+      interfaceId,
+    } as unknown as PaymentUpdateAction; // TypeScript does not have this action in the SDK yet
+  }
+
+  private populateAddTransactionAction(
+    draft: TransactionDraft,
+  ): PaymentAddTransactionAction {
+    return {
+      action: 'addTransaction',
+      transaction: {
+        ...draft,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+
+  private populateChangeTransactionState(
+    txId: string,
+    state: TransactionState,
+  ): PaymentChangeTransactionStateAction {
+    return {
+      action: 'changeTransactionState',
+      transactionId: txId,
+      state,
+    };
+  }
+
+  private populateSetPaymentMethod(
+    paymentMethod: string,
+  ): PaymentSetMethodInfoMethodAction {
+    return {
+      action: 'setMethodInfoMethod',
+      method: paymentMethod,
+    };
+  }
+
+  private populateSetMethodInfoToken(
+    token: string,
+  ): PaymentSetMethodInfoTokenAction {
+    return {
+      action: 'setMethodInfoToken',
+      token: {
+        value: token,
+      },
+    };
+  }
+
+  private populateSetMethodInfoInterface(
+    paymentInterface: string,
+  ): PaymentSetMethodInfoInterfaceAction {
+    return {
+      action: 'setMethodInfoInterface',
+      interface: paymentInterface,
+    };
+  }
+
+  private populateSetMethodInfoName(
+    name: LocalizedString,
+  ): PaymentSetMethodInfoNameAction {
+    return {
+      action: 'setMethodInfoName',
+      name,
+    };
+  }
+
+  private populateSetMethodInfoInterfaceAccount(
+    interfaceAccount: string,
+  ): PaymentSetMethodInfoInterfaceAccountAction {
+    return {
+      action: 'setMethodInfoInterfaceAccount',
+      interfaceAccount,
+    };
+  }
+
+  private populateSetMethodInfoCustomType(
+    customType: CustomFieldsDraft,
+  ): PaymentSetMethodInfoCustomTypeAction {
+    return {
+      action: 'setMethodInfoCustomType',
+      ...customType,
+    };
+  }
+
+  private populateSetCustomType(
+    customFields: CustomFieldsDraft,
+  ): PaymentSetCustomTypeAction {
+    return {
+      action: 'setCustomType',
+      ...customFields,
+    };
+  }
+
+  private populateAddInterfaceInteractions(
+    pspInteractions: CustomFieldsDraft[],
+  ): PaymentAddInterfaceInteractionAction[] {
+    return pspInteractions.map((interaction) => {
+      return {
+        action: 'addInterfaceInteraction',
+        ...interaction,
+      };
+    });
+  }
+
+  public findMatchingTransactions(
+    payment: Payment,
+    transaction: TransactionData,
+  ): Transaction[] {
+    return payment.transactions.filter((tx: Transaction) => {
+      // Must match transaction type
+      if (tx.type !== transaction.type) {
+        return false;
+      }
+
+      // New transaction must have at least one PSP identifier. InteractionId is for retro compatibility.
+      if (!transaction.interactionId && !transaction.interfaceId) {
+        return false;
+      }
+
+      // Match by interactionId
+      if (
+        transaction.interactionId &&
+        tx.interactionId === transaction.interactionId
+      ) {
+        return true;
+      }
+
+      // Match by interfaceId
+      if (
+        transaction.interfaceId &&
+        tx.interfaceId === transaction.interfaceId
+      ) {
+        return true;
+      }
+
+      // Match Initial transactions missing at least one ID by amount
+      // This allows reusing an Initial transaction when we get a PSP response with an ID
+      const isInitialMissingIds =
+        tx.state === 'Initial' && (!tx.interactionId || !tx.interfaceId);
+      const hasMatchingAmount =
+        tx.amount.centAmount === transaction.amount.centAmount &&
+        tx.amount.currencyCode === transaction.amount.currencyCode;
+
+      return isInitialMissingIds && hasMatchingAmount;
+    });
+  }
+
+  public hasTransactionInState(opts: FindTransaction): boolean {
+    return opts.payment.transactions.some(
+      (tx: Transaction) =>
+        tx.type === opts.transactionType && opts.states.includes(tx.state),
+    );
+  }
+
+  public consolidateTransactionChanges(
+    payment: Payment,
+    newTransaction: TransactionData,
+  ): PaymentUpdateAction[] {
+    const actions: PaymentUpdateAction[] = [];
+
+    // Discard transactions in 'Initial' state without an interactionId as they provide no value
+    if (this.shouldDiscardTransaction(newTransaction)) {
+      return [];
+    }
+
+    // Find matching transactions in the payment
+    const matchingTxs = this.findMatchingTransactions(payment, newTransaction);
+
+    // Handle cases where no matching transactions are found
+    if (matchingTxs.length === 0) {
+      actions.push(this.populateAddTransactionAction(newTransaction));
+      return actions;
+    }
+
+    // Handle cases where exactly one matching transaction is found
+    if (matchingTxs.length === 1) {
+      const existingTx = matchingTxs[0];
+      this.handleTransactionUpdates(existingTx, newTransaction, actions);
+      return actions;
+    }
+
+    // Handle cases where multiple matching transactions are found
+    this.throwMultipleMatchingTransactionsError(
+      payment,
+      newTransaction,
+      matchingTxs,
+    );
+  }
+
+  private shouldDiscardTransaction(newTransaction: TransactionData): boolean {
+    return newTransaction.state === 'Initial' && !newTransaction.interactionId;
+  }
+
+  private handleTransactionUpdates(
+    existingTx: Transaction,
+    newTransaction: TransactionData,
+    actions: PaymentUpdateAction[],
+  ): void {
+    if (this.shouldUpdateTransactionState(existingTx, newTransaction)) {
+      actions.push(
+        this.populateChangeTransactionState(
+          existingTx.id,
+          newTransaction.state,
+        ),
+      );
+    }
+
+    if (this.shouldUpdateInteractionId(existingTx, newTransaction)) {
+      actions.push(
+        this.populateChangeTransactionInteractionId(
+          existingTx.id,
+          newTransaction.interactionId as string,
+        ),
+      );
+    }
+
+    if (this.shouldUpdateTransactionInterfaceId(existingTx, newTransaction)) {
+      actions.push(
+        this.populateSetTransactionInterfaceId(
+          existingTx.id,
+          newTransaction.interfaceId as string,
+        ),
+      );
+    }
+  }
+
+  private shouldUpdateTransactionState(
+    existingTx: Transaction,
+    newTransaction: TransactionData,
+  ): boolean {
+    const { state: currentState } = existingTx;
+    const { state: newState } = newTransaction;
+
+    // Define allowed state transitions
+    const allowedTransitions: Record<string, string[]> = {
+      Initial: ['Pending', 'Success', 'Failure'],
+      Pending: ['Success', 'Failure'],
+      Failure: ['Success'],
+      Success: ['Failure'],
+    };
+
+    return (
+      currentState !== newState &&
+      allowedTransitions[currentState]?.includes(newState)
+    );
+  }
+
+  private shouldUpdateTransactionInterfaceId(
+    existingTx: Transaction,
+    newTransaction: TransactionData,
+  ): boolean {
+    return !existingTx.interfaceId && !!newTransaction.interfaceId;
+  }
+
+  private shouldUpdateInteractionId(
+    existingTx: Transaction,
+    newTransaction: TransactionData,
+  ): boolean {
+    return !existingTx.interactionId && !!newTransaction.interactionId;
+  }
+
+  private throwMultipleMatchingTransactionsError(
+    payment: Payment,
+    newTransaction: TransactionData,
+    matchingTxs: Transaction[],
+  ): never {
+    this.logger.error(
+      {
+        paymentId: payment.id,
+        transaction: newTransaction,
+        matchingTransactions: matchingTxs,
+      },
+      'Multiple matching transactions found when consolidating payment changes',
+    );
+
+    throw new Error(
+      `Multiple matching transactions found for payment ${payment.id} and transaction ${JSON.stringify(newTransaction)}`,
+    );
+  }
+}