@commercetools/checkout-payments-processor-sdk 0.0.6

package/src/api/handlers/payment-intents.handler.test.ts

@@ -0,0 +1,475 @@
+import type { HandlerResponse } from '@api-types';
+import type { Payment } from '@commercetools/platform-sdk';
+import type { Logger } from '@logger-types';
+import { vi } from 'vitest';
+import {
+  PaymentIntentsHandler,
+  type PaymentIntentsOutgoingHttpHeaders,
+  type PaymentIntentsRequest,
+  type PaymentIntentsResponse,
+} from '@/api/handlers/payment-intents.handler.js';
+import { ErrorInvalidOperation } from '@/errorx/errorx.js';
+import type { CheckoutPaymentsProcessor } from '@/payment-processor.js';
+
+// Concrete implementation for testing the abstract class
+class TestPaymentIntentsHandler extends PaymentIntentsHandler {
+  public handleCancel = vi.fn();
+  public handleRefund = vi.fn();
+  public handleCapture = vi.fn();
+  public handleReverse = vi.fn();
+}
+
+describe('PaymentIntentsHandler', () => {
+  let handler: TestPaymentIntentsHandler;
+  let mockLogger: Logger;
+  let mockProcessor: CheckoutPaymentsProcessor;
+  let mockPayment: Payment;
+
+  const mockSuccessResponse: HandlerResponse<
+    PaymentIntentsResponse,
+    PaymentIntentsOutgoingHttpHeaders
+  > = {
+    status: 200,
+    body: { outcome: 'approved' },
+  };
+
+  beforeEach(() => {
+    mockLogger = {
+      error: vi.fn(),
+      info: vi.fn(),
+      debug: vi.fn(),
+      warn: vi.fn(),
+    } as unknown as Logger;
+
+    mockPayment = { id: 'payment-123' } as Payment;
+    mockProcessor = {
+      getPaymentService: () => ({
+        getPayment: vi.fn().mockResolvedValue(mockPayment),
+      }),
+    } as unknown as CheckoutPaymentsProcessor;
+
+    handler = new TestPaymentIntentsHandler({
+      logger: mockLogger,
+      processor: mockProcessor,
+    });
+
+    // Reset all mocks
+    handler.handleCancel.mockResolvedValue(mockSuccessResponse);
+    handler.handleRefund.mockResolvedValue(mockSuccessResponse);
+    handler.handleCapture.mockResolvedValue(mockSuccessResponse);
+    handler.handleReverse.mockResolvedValue(mockSuccessResponse);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Public methods', () => {
+    test('should return POST as HTTP method', () => {
+      expect(handler.method()).toBe('POST');
+    });
+
+    test('should return correct endpoint', () => {
+      expect(handler.endpoint()).toBe('/operations/payment-intents/:id');
+    });
+
+    test('should return correct auth configuration', () => {
+      const auth = handler.auth();
+      expect(auth).toEqual([
+        {
+          type: 'oauth2',
+          allowedScopes: ['manage_project', 'manage_checkout_payment_intents'],
+        },
+      ]);
+    });
+  });
+
+  describe('Handler method', () => {
+    describe('capturePayment action', () => {
+      test('should handle capture payment action successfully', async () => {
+        const captureRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'capturePayment',
+              amount: {
+                centAmount: 1000,
+                currencyCode: 'USD',
+              },
+            },
+          ],
+        };
+
+        const result = await handler.handler({
+          request: captureRequest,
+        });
+
+        const captureAction = captureRequest.actions[0] as Extract<
+          PaymentIntentsRequest['actions'][number],
+          { action: 'capturePayment' }
+        >;
+
+        expect(handler.handleCapture).toHaveBeenCalledWith({
+          payload: {
+            payment: mockPayment,
+            amount: captureAction.amount,
+            merchantReference: undefined,
+          },
+        });
+        expect(result).toEqual(mockSuccessResponse);
+      });
+    });
+
+    describe('refundPayment action', () => {
+      test('should handle refund payment action successfully', async () => {
+        const refundRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'refundPayment',
+              amount: {
+                centAmount: 500,
+                currencyCode: 'EUR',
+              },
+            },
+          ],
+        };
+
+        const result = await handler.handler({
+          request: refundRequest,
+        });
+
+        const refundAction = refundRequest.actions[0] as Extract<
+          PaymentIntentsRequest['actions'][number],
+          { action: 'refundPayment' }
+        >;
+
+        expect(handler.handleRefund).toHaveBeenCalledWith({
+          payload: {
+            payment: mockPayment,
+            amount: refundAction.amount,
+            merchantReference: undefined,
+          },
+        });
+        expect(result).toEqual(mockSuccessResponse);
+      });
+    });
+
+    describe('cancelPayment action', () => {
+      test('should handle cancel payment action successfully', async () => {
+        const cancelRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'cancelPayment',
+              merchantReference: 'ref-123',
+            },
+          ],
+        };
+
+        const result = await handler.handler({
+          request: cancelRequest,
+        });
+
+        expect(handler.handleCancel).toHaveBeenCalledWith({
+          payload: {
+            payment: mockPayment,
+            merchantReference: 'ref-123',
+          },
+        });
+        expect(result).toEqual(mockSuccessResponse);
+      });
+
+      test('should handle cancel payment action without merchantReference', async () => {
+        const cancelRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'cancelPayment',
+            },
+          ],
+        };
+
+        await handler.handler({
+          request: cancelRequest,
+        });
+
+        expect(handler.handleCancel).toHaveBeenCalledWith({
+          payload: {
+            payment: mockPayment,
+            merchantReference: undefined,
+          },
+        });
+      });
+    });
+
+    describe('reversePayment action', () => {
+      test('should handle reverse payment action successfully', async () => {
+        const reverseRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'reversePayment',
+              merchantReference: 'ref-456',
+            },
+          ],
+        };
+
+        const result = await handler.handler({
+          request: reverseRequest,
+        });
+
+        expect(handler.handleReverse).toHaveBeenCalledWith({
+          payload: {
+            payment: mockPayment,
+            merchantReference: 'ref-456',
+          },
+        });
+        expect(result).toEqual(mockSuccessResponse);
+      });
+
+      test('should handle reverse payment action without merchantReference', async () => {
+        const reverseRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'reversePayment',
+            },
+          ],
+        };
+
+        await handler.handler({
+          request: reverseRequest,
+        });
+
+        expect(handler.handleReverse).toHaveBeenCalledWith({
+          payload: {
+            payment: mockPayment,
+            merchantReference: undefined,
+          },
+        });
+      });
+    });
+
+    describe('Error handling', () => {
+      test('should throw ErrorInvalidOperation for unsupported action', async () => {
+        const invalidRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              // biome-ignore lint/suspicious/noExplicitAny: this is a test
+              action: 'unsupportedAction' as any,
+            },
+          ],
+        };
+
+        await expect(
+          handler.handler({
+            request: invalidRequest,
+          }),
+        ).rejects.toThrow(ErrorInvalidOperation);
+
+        expect(mockLogger.error).toHaveBeenCalledWith(
+          {},
+          'Operation not supported when modifying payment.',
+        );
+      });
+
+      test('should handle errors thrown by action handlers', async () => {
+        const captureRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'capturePayment',
+              amount: {
+                centAmount: 1000,
+                currencyCode: 'USD',
+              },
+            },
+          ],
+        };
+
+        const testError = new Error('Handler failed');
+        handler.handleCapture.mockRejectedValue(testError);
+
+        await expect(
+          handler.handler({
+            request: captureRequest,
+          }),
+        ).rejects.toThrow('Handler failed');
+      });
+    });
+
+    describe('Edge cases', () => {
+      test('should process only the first action when multiple actions are provided', async () => {
+        const multipleActionsRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'capturePayment',
+              amount: {
+                centAmount: 1000,
+                currencyCode: 'USD',
+              },
+            },
+            {
+              action: 'refundPayment',
+              amount: {
+                centAmount: 500,
+                currencyCode: 'USD',
+              },
+            },
+          ],
+        };
+
+        await handler.handler({
+          request: multipleActionsRequest,
+        });
+
+        expect(handler.handleCapture).toHaveBeenCalledTimes(1);
+        expect(handler.handleRefund).not.toHaveBeenCalled();
+        expect(handler.handleCancel).not.toHaveBeenCalled();
+        expect(handler.handleReverse).not.toHaveBeenCalled();
+      });
+
+      test('should handle different response outcomes', async () => {
+        const rejectedResponse: HandlerResponse<
+          PaymentIntentsResponse,
+          PaymentIntentsOutgoingHttpHeaders
+        > = {
+          status: 400,
+          body: { outcome: 'rejected' },
+        };
+
+        handler.handleCapture.mockResolvedValue(rejectedResponse);
+
+        const captureRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'capturePayment',
+              amount: {
+                centAmount: 1000,
+                currencyCode: 'USD',
+              },
+            },
+          ],
+        };
+
+        const result = await handler.handler({
+          request: captureRequest,
+        });
+
+        expect(result.body.outcome).toBe('rejected');
+        expect(result.status).toBe(400);
+      });
+
+      test('should handle received outcome', async () => {
+        const receivedResponse: HandlerResponse<
+          PaymentIntentsResponse,
+          PaymentIntentsOutgoingHttpHeaders
+        > = {
+          status: 202,
+          body: { outcome: 'received' },
+        };
+
+        handler.handleRefund.mockResolvedValue(receivedResponse);
+
+        const refundRequest: PaymentIntentsRequest = {
+          id: 'payment-123',
+          actions: [
+            {
+              action: 'refundPayment',
+              amount: {
+                centAmount: 300,
+                currencyCode: 'GBP',
+              },
+            },
+          ],
+        };
+
+        const result = await handler.handler({
+          request: refundRequest,
+        });
+
+        expect(result.body.outcome).toBe('received');
+        expect(result.status).toBe(202);
+      });
+    });
+  });
+
+  describe('Type safety', () => {
+    test('should enforce correct action type for handleCapture', () => {
+      const captureAction = {
+        action: 'capturePayment' as const,
+        amount: {
+          centAmount: 1000,
+          currencyCode: 'USD',
+        },
+      };
+
+      // This should compile without issues
+      expect(() => {
+        handler.handleCapture({
+          payload: {
+            payment: mockPayment,
+            amount: captureAction.amount,
+            merchantReference: undefined,
+          },
+        });
+      }).not.toThrow();
+    });
+
+    test('should enforce correct action type for handleRefund', () => {
+      const refundAction = {
+        action: 'refundPayment' as const,
+        amount: {
+          centAmount: 500,
+          currencyCode: 'EUR',
+        },
+      };
+
+      expect(() => {
+        handler.handleRefund({
+          payload: {
+            payment: mockPayment,
+            amount: refundAction.amount,
+            merchantReference: undefined,
+          },
+        });
+      }).not.toThrow();
+    });
+
+    test('should enforce correct action type for handleCancel', () => {
+      const cancelAction = {
+        action: 'cancelPayment' as const,
+        merchantReference: 'ref-123',
+      };
+
+      expect(() => {
+        handler.handleCancel({
+          payload: {
+            payment: mockPayment,
+            merchantReference: cancelAction.merchantReference,
+          },
+        });
+      }).not.toThrow();
+    });
+
+    test('should enforce correct action type for handleReverse', () => {
+      const reverseAction = {
+        action: 'reversePayment' as const,
+        merchantReference: 'ref-456',
+      };
+
+      expect(() => {
+        handler.handleReverse({
+          payload: {
+            payment: mockPayment,
+            merchantReference: reverseAction.merchantReference,
+          },
+        });
+      }).not.toThrow();
+    });
+  });
+});

package/src/api/handlers/payment-intents.handler.ts

@@ -0,0 +1,169 @@
+import type {
+  AuthType,
+  BaseIncomingHttpHeaders,
+  BaseOutgoingHttpHeaders,
+  HandlerResponse,
+  RouteHandler,
+} from '@api-types';
+import type { Money, Payment } from '@commercetools/platform-sdk';
+import { ErrorInvalidOperation } from '@/errorx/errorx.js';
+import type { Logger } from '@/logger/types.js';
+import type { CheckoutPaymentsProcessor } from '@/payment-processor.js';
+
+type CapturePayment = {
+  action: 'capturePayment';
+  amount: Money;
+  merchantReference?: string;
+};
+
+type RefundPayment = {
+  action: 'refundPayment';
+  amount: Money;
+  merchantReference?: string;
+};
+
+type CancelPayment = {
+  action: 'cancelPayment';
+  merchantReference?: string;
+};
+
+type ReversePayment = {
+  action: 'reversePayment';
+  merchantReference?: string;
+};
+
+export type ModificationPayload = {
+  payment: Payment;
+  amount?: Money;
+  merchantReference?: string;
+};
+
+export type PaymentIntentsRequest = {
+  id: string;
+  actions: (CapturePayment | RefundPayment | CancelPayment | ReversePayment)[];
+};
+
+export type PaymentIntentsResponse = {
+  outcome: 'approved' | 'rejected' | 'received';
+};
+
+export type PaymentIntentsIncomingHttpHeaders = BaseIncomingHttpHeaders & {};
+export type PaymentIntentsOutgoingHttpHeaders = BaseOutgoingHttpHeaders & {};
+
+export abstract class PaymentIntentsHandler
+  implements
+    RouteHandler<
+      PaymentIntentsRequest,
+      PaymentIntentsResponse,
+      PaymentIntentsIncomingHttpHeaders,
+      PaymentIntentsOutgoingHttpHeaders
+    >
+{
+  public readonly logger: Logger;
+  public readonly processor: CheckoutPaymentsProcessor;
+  public constructor(opts: {
+    logger: Logger;
+    processor: CheckoutPaymentsProcessor;
+  }) {
+    this.logger = opts.logger;
+    this.processor = opts.processor;
+  }
+
+  public method() {
+    return 'POST';
+  }
+
+  public endpoint() {
+    return '/operations/payment-intents/:id';
+  }
+
+  public auth(): AuthType[] {
+    return [
+      {
+        type: 'oauth2',
+        allowedScopes: ['manage_project', 'manage_checkout_payment_intents'],
+      },
+    ];
+  }
+
+  public async handler(opts: {
+    request: PaymentIntentsRequest;
+  }): Promise<
+    HandlerResponse<PaymentIntentsResponse, PaymentIntentsOutgoingHttpHeaders>
+  > {
+    const actions = opts.request.actions;
+    const request = actions[0];
+
+    const payment = await this.processor.getPaymentService().getPayment({
+      id: opts.request.id,
+    });
+
+    switch (request.action) {
+      case 'cancelPayment': {
+        return await this.handleCancel({
+          payload: {
+            payment,
+            merchantReference: request.merchantReference,
+          },
+        });
+      }
+      case 'refundPayment': {
+        return await this.handleRefund({
+          payload: {
+            payment,
+            amount: request.amount,
+            merchantReference: request.merchantReference,
+          },
+        });
+      }
+      case 'capturePayment': {
+        return await this.handleCapture({
+          payload: {
+            payment,
+            amount: request.amount,
+            merchantReference: request.merchantReference,
+          },
+        });
+      }
+      case 'reversePayment': {
+        return await this.handleReverse({
+          payload: {
+            payment,
+            merchantReference: request.merchantReference,
+          },
+        });
+      }
+      default: {
+        this.logger.error(
+          {},
+          `Operation not supported when modifying payment.`,
+        );
+        throw new ErrorInvalidOperation(`Operation not supported.`);
+      }
+    }
+  }
+
+  public abstract handleCancel(opts: {
+    payload: ModificationPayload;
+  }): Promise<
+    HandlerResponse<PaymentIntentsResponse, PaymentIntentsOutgoingHttpHeaders>
+  >;
+
+  public abstract handleRefund(opts: {
+    payload: ModificationPayload;
+  }): Promise<
+    HandlerResponse<PaymentIntentsResponse, PaymentIntentsOutgoingHttpHeaders>
+  >;
+
+  public abstract handleCapture(opts: {
+    payload: ModificationPayload;
+  }): Promise<
+    HandlerResponse<PaymentIntentsResponse, PaymentIntentsOutgoingHttpHeaders>
+  >;
+
+  public abstract handleReverse(opts: {
+    payload: ModificationPayload;
+  }): Promise<
+    HandlerResponse<PaymentIntentsResponse, PaymentIntentsOutgoingHttpHeaders>
+  >;
+}