@commercetools/connect-payments-sdk 0.25.1 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @commercetools/connect-payments-sdk
 
+## 0.27.0
+
+### Minor Changes
+
+- 9fe494b: feat(recurring-orders): added new recurring payment job service that allows connectors to create a recurring payment job instance in Checkout
+
+## 0.26.0
+
+### Minor Changes
+
+- d6a10eb: feat(cart): added a new method to the cart service to check whether the cart is a recurring cart
+
 ## 0.25.1
 
 ### Patch Changes

package/dist/commercetools/index.d.ts

@@ -5,8 +5,9 @@ export { AuthorizationService as CommercetoolsAuthorizationService } from './typ
 export { OrderService as CommercetoolsOrderService } from './types/order.type';
 export { PaymentMethodService as CommercetoolsPaymentMethodService } from './types/payment-method.type';
 export { CustomTypeService as CommercetoolsCustomTypeService } from './types/custom-type.type';
+export { RecurringPaymentJobService as CommercetoolsRecurringPaymentJobService, RecurringPaymentJobDraft, } from './types/recurring-payment-job.type';
 export * as CommercetoolsPaymentMethodTypes from './types/payment-method.type';
 export { CommercetoolsClient } from './types/api.type';
-export { CustomFieldsDraft, Cart, Order, OrderPagedQueryResponse, Payment, PaymentDraft, PaymentMethodInfoDraft, Money, LineItem, CustomLineItem, Address, Transaction, TransactionType, TransactionState, ShippingInfo, PaymentMethod, PaymentMethodPagedQueryResponse, PaymentMethodToken, PaymentMethodStatus, Type, TypeDraft, TypePagedQueryResponse, LocalizedString, } from '@commercetools/platform-sdk';
+export { CustomFields, CustomFieldsDraft, Cart, Order, OrderPagedQueryResponse, Payment, PaymentDraft, PaymentMethodInfoDraft, Money, LineItem, CustomLineItem, Address, Transaction, TransactionType, TransactionState, ShippingInfo, PaymentMethod, PaymentMethodPagedQueryResponse, PaymentMethodToken, PaymentMethodStatus, Type, TypeDraft, TypeUpdateAction, ProductTypeDraft, TypeAddFieldDefinitionAction, TypeRemoveFieldDefinitionAction, CustomerSetCustomFieldAction, CustomerSetCustomTypeAction, CustomerUpdateAction, TypePagedQueryResponse, LocalizedString, Customer, } from '@commercetools/platform-sdk';
 export * as CurrencyConverters from './helpers/currency.converter';
 export * as TaxRateConverter from './helpers/taxrate.converter';

package/dist/commercetools/services/ct-cart.service.d.ts

@@ -28,6 +28,7 @@ export declare class DefaultCartService implements CartService {
      */
     getNormalizedShipping(opts: GetNormalizedShipping): NormalizedShipping[];
     addPayment(opts: AddPayment): Promise<Cart>;
+    isRecurringCart(cart: Cart): boolean;
     private calculateTotalPaidAmount;
     private calculatePaymentAmount;
     private wasPaymentReverted;

package/dist/commercetools/services/ct-cart.service.js

@@ -170,6 +170,14 @@ class DefaultCartService {
         }
         throw err;
     }
+    isRecurringCart(cart) {
+        if (!cart.customerId)
+            return false;
+        const cartOrigin = cart.origin === 'RecurringOrder';
+        const hasRecurringLineItems = cart.lineItems?.some((item) => item.recurrenceInfo) ?? false;
+        const hasRecurringCustomLineItems = cart.customLineItems?.some((item) => item.recurrenceInfo) ?? false;
+        return cartOrigin || hasRecurringLineItems || hasRecurringCustomLineItems;
+    }
     async calculateTotalPaidAmount(cart) {
         if (!cart.paymentInfo || cart.paymentInfo.payments.length === 0) {
             return 0;

package/dist/commercetools/services/ct-recurring-payment-job.service.d.ts

@@ -0,0 +1,55 @@
+import { Logger } from '../..';
+import { RecurringPaymentJob, RecurringPaymentJobDraft, RecurringPaymentJobService } from '../types/recurring-payment-job.type';
+import { DefaultCartService } from './ct-cart.service';
+/**
+ * Default implementation of the RecurringPaymentJobService interface.
+ */
+export declare class DefaultRecurringPaymentJobService implements RecurringPaymentJobService {
+    private ctCartService;
+    private checkoutUrl;
+    private projectKey;
+    private logger;
+    constructor(opts: {
+        ctCartService: DefaultCartService;
+        checkoutUrl: string;
+        projectKey: string;
+        logger: Logger;
+    });
+    /**
+     * Creates a recurring payment job only if applicable (i.e., when the cart is configured for recurring payments).
+     *
+     * This method abstracts the business logic of determining whether a recurring payment job should be created.
+     * The caller doesn't need to validate the cart - the method handles it internally.
+     *
+     * The method performs the following operations:
+     * 1. Retrieves the cart associated with the origin payment
+     * 2. Checks if the cart is configured for recurring payments
+     * 3. If yes, creates the recurring payment job via the checkout API
+     * 4. If no, returns null without creating anything
+     *
+     * @param draft - The draft object containing the origin payment and payment method references
+     * @returns The created recurring payment job if the cart supports recurring payments,
+     *          or null if it doesn't or if an error occurs
+     *
+     * @example
+     * ```typescript
+     * // Caller doesn't need to check if cart is recurring - method handles it
+     * const job = await service.createRecurringPaymentJobIfApplicable({
+     *   originPayment: { id: 'payment-123', typeId: 'payment' },
+     *   paymentMethod: { id: 'method-456', typeId: 'payment-method' }
+     * });
+     *
+     * if (job) {
+     *   // Job was created because cart is recurring
+     * } else {
+     *   // Cart is not recurring or an error occurred
+     * }
+     * ```
+     */
+    createRecurringPaymentJobIfApplicable(draft: RecurringPaymentJobDraft): Promise<RecurringPaymentJob | null>;
+    /**
+     * Internal method that performs the HTTP request to create a recurring payment job.
+     */
+    private internalCreateRecurringPaymentJob;
+    private safeParseErrorResponse;
+}

package/dist/commercetools/services/ct-recurring-payment-job.service.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultRecurringPaymentJobService = void 0;
+const errorx_1 = require("../../errorx/errorx");
+/**
+ * Default implementation of the RecurringPaymentJobService interface.
+ */
+class DefaultRecurringPaymentJobService {
+    ctCartService;
+    checkoutUrl;
+    projectKey;
+    logger;
+    constructor(opts) {
+        this.ctCartService = opts.ctCartService;
+        this.checkoutUrl = opts.checkoutUrl;
+        this.projectKey = opts.projectKey;
+        this.logger = opts.logger;
+    }
+    /**
+     * Creates a recurring payment job only if applicable (i.e., when the cart is configured for recurring payments).
+     *
+     * This method abstracts the business logic of determining whether a recurring payment job should be created.
+     * The caller doesn't need to validate the cart - the method handles it internally.
+     *
+     * The method performs the following operations:
+     * 1. Retrieves the cart associated with the origin payment
+     * 2. Checks if the cart is configured for recurring payments
+     * 3. If yes, creates the recurring payment job via the checkout API
+     * 4. If no, returns null without creating anything
+     *
+     * @param draft - The draft object containing the origin payment and payment method references
+     * @returns The created recurring payment job if the cart supports recurring payments,
+     *          or null if it doesn't or if an error occurs
+     *
+     * @example
+     * ```typescript
+     * // Caller doesn't need to check if cart is recurring - method handles it
+     * const job = await service.createRecurringPaymentJobIfApplicable({
+     *   originPayment: { id: 'payment-123', typeId: 'payment' },
+     *   paymentMethod: { id: 'method-456', typeId: 'payment-method' }
+     * });
+     *
+     * if (job) {
+     *   // Job was created because cart is recurring
+     * } else {
+     *   // Cart is not recurring or an error occurred
+     * }
+     * ```
+     */
+    async createRecurringPaymentJobIfApplicable(draft) {
+        try {
+            const cart = await this.ctCartService.getCartByPaymentId({ paymentId: draft.originPayment.id });
+            if (!this.ctCartService.isRecurringCart(cart)) {
+                this.logger.info({ originPaymentId: draft.originPayment.id }, 'Cart is not recurring. Skipping recurring payment job creation');
+                return null;
+            }
+            this.logger.info({ draft }, 'Creating new recurring payment job');
+            const recurringPaymentJob = await this.internalCreateRecurringPaymentJob(draft);
+            this.logger.info({ recurringPaymentJobId: recurringPaymentJob.id }, 'Created new recurring payment job');
+            return recurringPaymentJob;
+        }
+        catch (error) {
+            this.logger.error({ error, draft }, 'Error creating recurring payment job');
+            return null;
+        }
+    }
+    /**
+     * Internal method that performs the HTTP request to create a recurring payment job.
+     */
+    async internalCreateRecurringPaymentJob(draft) {
+        const url = `${this.checkoutUrl}/${this.projectKey}/recurring-payment-jobs`;
+        const payload = {
+            ...draft,
+            status: {
+                state: 'Initial',
+            },
+        };
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const errorBody = await this.safeParseErrorResponse(response);
+            throw new errorx_1.ErrorGeneral('Could not create recurring payment job', {
+                privateFields: {
+                    status: response.status,
+                    statusText: response.statusText,
+                    errorBody,
+                },
+            });
+        }
+        return (await response.json());
+    }
+    async safeParseErrorResponse(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return response.statusText;
+        }
+    }
+}
+exports.DefaultRecurringPaymentJobService = DefaultRecurringPaymentJobService;

package/dist/commercetools/types/cart.type.d.ts

@@ -55,4 +55,11 @@ export interface CartService {
      */
     getPlannedPaymentAmount(opts: GetPaymentAmount): Promise<PaymentAmount>;
     addPayment(opts: AddPayment): Promise<Cart>;
+    /**
+     * Checks if the given cart contains items configured for recurring orders.
+     *
+     * @param cart - The cart to check
+     * @returns true if the cart contains recurring items, false otherwise
+     */
+    isRecurringCart(cart: Cart): boolean;
 }

package/dist/commercetools/types/recurring-payment-job.type.d.ts

@@ -0,0 +1,34 @@
+export type RecurringPaymentJobDraft = {
+    originPayment: {
+        id: string;
+        typeId: string;
+    };
+    paymentMethod: {
+        id: string;
+        typeId: string;
+    };
+};
+export type RecurringPaymentJob = {
+    id: string;
+    version: number;
+    createdAt: string;
+    lastModifiedAt: string;
+    originPayment?: {
+        id: string;
+        typeId: string;
+    };
+    paymentMethod?: {
+        id: string;
+        typeId: string;
+    };
+    status: {
+        state: string;
+    };
+};
+export interface RecurringPaymentJobService {
+    /**
+     * Ensures a recurring payment job is created if the payment's cart is configured for recurring payments.
+     * Returns null if the cart is not configured for recurring payments or if an error occurs.
+     */
+    createRecurringPaymentJobIfApplicable(draft: RecurringPaymentJobDraft): Promise<RecurringPaymentJob | null>;
+}

package/dist/commercetools/types/recurring-payment-job.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { DefaultCartService } from './commercetools/services/ct-cart.service';
 import { DefaultOrderService } from './commercetools/services/ct-order.service';
 import { DefaultPaymentService } from './commercetools/services/ct-payment.service';
 import { DefaultPaymentMethodService } from './commercetools/services/ct-payment-method.service';
+import { DefaultRecurringPaymentJobService } from './commercetools/services/ct-recurring-payment-job.service';
 import { DefaultCustomTypeService } from './commercetools/services/ct-custom-type.service';
 import { Logger } from './logger';
 export * from './api';
@@ -17,6 +18,7 @@ export declare const setupPaymentSDK: (opts: {
     authUrl: string;
     apiUrl: string;
     sessionUrl: string;
+    checkoutUrl: string;
     jwksUrl: string;
     clientId: string;
     clientSecret: string;
@@ -33,6 +35,7 @@ export declare const setupPaymentSDK: (opts: {
     ctPaymentMethodService: DefaultPaymentMethodService;
     ctCustomTypeService: DefaultCustomTypeService;
     ctAuthorizationService: DefaultAuthorizationService;
+    ctRecurringPaymentJobService: DefaultRecurringPaymentJobService;
     contextProvider: RequestContextProvider;
     sessionHeaderAuthHookFn: SessionHeaderAuthenticationHook;
     sessionQueryParamAuthHookFn: SessionQueryParamAuthenticationHook;

package/dist/index.js

@@ -23,6 +23,7 @@ const ct_order_service_1 = require("./commercetools/services/ct-order.service");
 const ct_payment_service_1 = require("./commercetools/services/ct-payment.service");
 const ct_payment_method_service_1 = require("./commercetools/services/ct-payment-method.service");
 const ct_session_service_1 = require("./commercetools/services/ct-session.service");
+const ct_recurring_payment_job_service_1 = require("./commercetools/services/ct-recurring-payment-job.service");
 const ct_custom_type_service_1 = require("./commercetools/services/ct-custom-type.service");
 const base_decorator_1 = require("./fetch/decorators/base.decorator");
 const monitoring_decorator_1 = require("./fetch/decorators/monitoring.decorator");
@@ -69,6 +70,12 @@ const setupPaymentSDK = (opts) => {
     const ctPaymentService = new ct_payment_service_1.DefaultPaymentService({ ctAPI, logger });
     const ctPaymentMethodService = new ct_payment_method_service_1.DefaultPaymentMethodService({ ctAPI, logger });
     const ctCustomTypeService = new ct_custom_type_service_1.DefaultCustomTypeService({ ctAPI, logger });
+    const ctRecurringPaymentJobService = new ct_recurring_payment_job_service_1.DefaultRecurringPaymentJobService({
+        ctCartService,
+        checkoutUrl: opts.checkoutUrl,
+        projectKey: opts.projectKey,
+        logger,
+    });
     const oauth2Service = new security_1.DefaultOauth2Service({ logger });
     const jwtService = new security_1.DefaultJWTService({
         jwksUrl: opts.jwksUrl,
@@ -128,6 +135,7 @@ const setupPaymentSDK = (opts) => {
         apiUrl: opts.apiUrl,
         authUrl: opts.authUrl,
         sessionUrl: opts.sessionUrl,
+        checkoutUrl: opts.checkoutUrl,
         jwksUrl: opts.jwksUrl,
         jwtIssuer: opts.jwtIssuer,
         clientId: opts.clientId,
@@ -140,6 +148,7 @@ const setupPaymentSDK = (opts) => {
         ctPaymentMethodService,
         ctCustomTypeService,
         ctAuthorizationService,
+        ctRecurringPaymentJobService,
         contextProvider,
         sessionHeaderAuthHookFn,
         sessionQueryParamAuthHookFn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercetools/connect-payments-sdk",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "Payment SDK for commercetools payment connectors",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",