@commercetools/checkout-payments-processor-sdk 0.0.6

package/src/commercetools/types/api.type.ts

@@ -0,0 +1,162 @@
+import type {
+  ByProjectKeyRequestBuilder,
+  Cart,
+  CartPagedQueryResponse,
+  OrderPagedQueryResponse,
+  Payment,
+  PaymentDraft,
+  PaymentMethod,
+  PaymentMethodDraft,
+  PaymentMethodPagedQueryResponse,
+  PaymentMethodUpdateAction,
+  PaymentPagedQueryResponse,
+  PaymentUpdateAction,
+  Type,
+  TypeDraft,
+  TypePagedQueryResponse,
+} from '@commercetools/platform-sdk';
+
+export type CommercetoolsClient = ByProjectKeyRequestBuilder;
+export type CommercetoolsSessionClient = ByProjectKeyRequestBuilder;
+
+/**
+ * API Options
+ */
+export interface APIOpts {
+  client: CommercetoolsClient;
+}
+
+/**
+ * Update Resource
+ */
+export type UpdateResource = {
+  id: string;
+  version: number;
+};
+
+/**
+ * Add Payment
+ */
+export type AddPayment = {
+  resource: UpdateResource;
+  paymentId: string;
+};
+
+/**
+ * Update Payment
+ */
+export type UpdatePayment = {
+  resource: UpdateResource;
+  actions: PaymentUpdateAction[];
+};
+
+/**
+ * Oauth Token
+ */
+export type OauthToken = {
+  accessToken: string;
+  expiresIn: number;
+  tokenType: string;
+  scope: string;
+  refreshToken?: string;
+};
+
+/**
+ * Update Payment Method
+ */
+export type UpdatePaymentMethod = {
+  resource: UpdateResource;
+  actions: PaymentMethodUpdateAction[];
+};
+
+/**
+ * Find Payment Methods
+ */
+export type FindPaymentMethods = {
+  queryString: string;
+};
+
+/**
+ * Get Payment Method
+ */
+export type GetPaymentMethod = {
+  id: string;
+};
+
+/**
+ * Delete Payment Method
+ */
+export type DeletePaymentMethod = {
+  id: string;
+  version: number;
+};
+
+/**
+ * Check If Exists By Predicate
+ */
+export type CheckIfExistsByPredicate = {
+  queryString: string;
+};
+
+/**
+ * Authorization API
+ */
+export interface AuthorizationAPI {
+  getToken(): Promise<OauthToken>;
+}
+
+/**
+ * Cart API
+ */
+export interface CartAPI {
+  getCartById(id: string): Promise<Cart>;
+  find(queryPredicate: string): Promise<CartPagedQueryResponse>;
+  addPayment(opts: AddPayment): Promise<Cart>;
+}
+
+/**
+ * Payment API
+ */
+export interface PaymentAPI {
+  getPaymentById(id: string): Promise<Payment>;
+  find(queryPredicate: string): Promise<PaymentPagedQueryResponse>;
+  createPayment(paymentDraft: PaymentDraft): Promise<Payment>;
+  updatePayment(opts: UpdatePayment): Promise<Payment>;
+}
+
+/**
+ * Payment Method API
+ */
+export interface PaymentMethodAPI {
+  find(opts: FindPaymentMethods): Promise<PaymentMethodPagedQueryResponse>;
+  get(opts: GetPaymentMethod): Promise<PaymentMethod>;
+  create(draft: PaymentMethodDraft): Promise<PaymentMethod>;
+  update(opts: UpdatePaymentMethod): Promise<PaymentMethod>;
+  delete(opts: DeletePaymentMethod): Promise<PaymentMethod>;
+  checkIfExistsByPredicate(opts: CheckIfExistsByPredicate): Promise<boolean>;
+}
+
+/**
+ * Order API
+ */
+export interface OrderAPI {
+  find(queryPredicate: string): Promise<OrderPagedQueryResponse>;
+}
+
+export interface CustomTypeAPI {
+  getByKey(key: string): Promise<Type>;
+  find(queryPredicate: string): Promise<TypePagedQueryResponse>;
+  create(draft: TypeDraft): Promise<Type>;
+}
+
+/**
+ * Commercetools API is a collection of APIs that can be used to interact with the Commercetools platform.
+ * It gives advanced functionality to the Commercetools payment related .
+ */
+export interface CommercetoolsAPI {
+  cart: CartAPI;
+  payment: PaymentAPI;
+  order: OrderAPI;
+  paymentMethod: PaymentMethodAPI;
+  customType: CustomTypeAPI;
+}

package/src/commercetools/types/cart.type.ts

@@ -0,0 +1,83 @@
+import type { Address, Cart, ShippingInfo } from '@commercetools/platform-sdk';
+import type {
+  ContextProvider,
+  RequestContextData,
+} from '@/api/context/types/request-context.type.js';
+import type {
+  AddPayment,
+  CommercetoolsAPI,
+} from '@/commercetools/types/api.type.js';
+import type { PaymentAmount } from '@/commercetools/types/payment.type.js';
+import type { Logger } from '@/logger/types/logger.type.js';
+
+export type GetCart = {
+  id: string;
+  version?: number;
+};
+
+export type GetPaymentAmount = {
+  cart: Cart;
+};
+
+export type GetOneShippingAddress = {
+  cart: Pick<Cart, 'shippingAddress' | 'shipping' | 'shippingMode'>;
+};
+
+export type GetNormalizedShipping = {
+  cart: Pick<
+    Cart,
+    'shippingInfo' | 'shipping' | 'shippingMode' | 'shippingAddress'
+  >;
+};
+
+export type NormalizedShipping = {
+  shippingAddress: Address;
+  shippingInfo: ShippingInfo;
+};
+
+export type ShippingAmounts = {
+  priceCentAmount: number;
+  taxRateAmount: number;
+  totalNetCentAmount: number;
+  totalGrossCentAmount: number;
+  totalTaxCentAmount: number;
+};
+
+export type CartServiceOptions = {
+  ctAPI: CommercetoolsAPI;
+  logger: Logger;
+  contextProvider: ContextProvider<RequestContextData>;
+};
+
+export type GetCartByPaymentIdRequest = {
+  paymentId: string;
+};
+
+/**
+ * Cart service interface exposes methods to interact with the commercetools platform API.
+ */
+export interface CartService {
+  getCartByPaymentId(opts: GetCartByPaymentIdRequest): Promise<Cart>;
+  getCart(opts: GetCart): Promise<Cart>;
+  /**
+   * Get payment amount for a cart. This method is used to calculate the payment amount for a cart.
+   * It takes into account existing successful payments.
+   * @param opts
+   */
+  getPaymentAmount(opts: GetPaymentAmount): Promise<PaymentAmount>;
+  /**
+   * Get payment amount for a cart. This method is used to calculate the payment amount for a cart.
+   * It takes into account existing successful payments and giftcards connectors.
+   * This method is specifically used for calculating the payment amount for a cart when a giftcard is applied and the payment session is created upfront.
+   * @param opts
+   */
+  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/src/commercetools/types/custom-type.type.ts

@@ -0,0 +1,21 @@
+import type {
+  Type,
+  TypeDraft,
+  TypePagedQueryResponse,
+} from '@commercetools/platform-sdk';
+
+export type GetCustomType = {
+  key: string;
+};
+
+export type FindCustomType = {
+  predicate: string;
+};
+
+export interface CustomTypeService {
+  getCustomType(opts: GetCustomType): Promise<Type>;
+  findCustomType(opts: FindCustomType): Promise<TypePagedQueryResponse>;
+  createCustomType(draft: TypeDraft): Promise<Type>;
+  createPredefinedInterfaceInteractionType(): Promise<Type>;
+  createPredefinedPaymentMethodsTypes(): Promise<Type[]>;
+}

package/src/commercetools/types/order.type.ts

@@ -0,0 +1,19 @@
+import type { Order } from '@commercetools/platform-sdk';
+import type { CommercetoolsAPI } from '@/commercetools/types/api.type.js';
+import type { Logger } from '@/logger/types/logger.type.js';
+
+export type OrderServiceOptions = {
+  ctAPI: CommercetoolsAPI;
+  logger: Logger;
+};
+
+export type GetOrderByPaymentIdRequest = {
+  paymentId: string;
+};
+
+/**
+ * Order service interface exposes methods to interact with the commercetools platform API.
+ */
+export interface OrderService {
+  getOrderByPaymentId(opts: GetOrderByPaymentIdRequest): Promise<Order>;
+}

package/src/commercetools/types/payment-method.type.ts

@@ -0,0 +1,130 @@
+import type {
+  PaymentMethod,
+  PaymentMethodPagedQueryResponse,
+  PaymentMethodUpdateAction,
+} from '@commercetools/platform-sdk';
+import type {
+  CommercetoolsAPI,
+  UpdateResource,
+} from '@/commercetools/types/api.type.js';
+import type { Logger } from '@/logger/types/logger.type.js';
+
+export type PaymentMethodServiceOptions = {
+  ctAPI: CommercetoolsAPI;
+  logger: Logger;
+};
+
+export type FindPaymentMethod = {
+  customerId: string;
+  paymentInterface: string;
+  interfaceAccount?: string;
+};
+
+export type GetPaymentMethodService = {
+  customerId: string;
+  id: string;
+  paymentInterface: string;
+  interfaceAccount?: string;
+};
+
+export type GetByTokenValuePaymentMethod = {
+  customerId: string;
+  tokenValue: string;
+  paymentInterface: string;
+  interfaceAccount?: string;
+};
+
+export type DoesTokenBelongToCustomer = {
+  customerId: string;
+  tokenValue: string;
+  paymentInterface: string;
+  interfaceAccount?: string;
+};
+
+export type DeletePaymentMethodService = {
+  customerId: string;
+  id: string;
+  version: number;
+};
+
+export type UpdatePaymentMethodService = {
+  customerId: string;
+  resource: UpdateResource;
+  actions: PaymentMethodUpdateAction[];
+};
+
+export type SavePaymentMethodDraft = {
+  customerId: string;
+  token: string;
+  paymentInterface: string;
+  interfaceAccount?: string;
+  method: string;
+};
+
+/**
+ * Payment methods service interface exposes methods to interact with the commercetools platform API.
+ */
+export interface PaymentMethodService {
+  /**
+   * Finds all of the payment-methods that match with the given parameters.
+   *
+   * @param opts the parameters to search by
+   *
+   * @returns a paged list of payment-methods
+   */
+  find(opts: FindPaymentMethod): Promise<PaymentMethodPagedQueryResponse>;
+
+  /**
+   * Returns a payment-method by the given ID which must belong to the given customerId.
+   *
+   * @param opts
+   *
+   * @returns the payment-method
+   */
+  get(opts: GetPaymentMethodService): Promise<PaymentMethod>;
+
+  /**
+   * Returns a payment-method by the given tokenValue which must belong to the given customerId and must be unique.
+   *
+   * @param opts
+   *
+   * @returns the payment-method
+   */
+  getByTokenValue(opts: GetByTokenValuePaymentMethod): Promise<PaymentMethod>;
+
+  /**
+   * Returns true if the given token belongs to the given customer for any payment-method.
+   *
+   * @param opts
+   *
+   * @returns true if the given token belongs to the customer for any payment method, false otherwise.
+   */
+  doesTokenBelongsToCustomer(opts: DoesTokenBelongToCustomer): Promise<boolean>;
+
+  /**
+   * Saves a new payment-method given the draft payload. The customer attribute is mandatory.
+   *
+   * @param opts the payment-method draft
+   *
+   * @returns the newly created payment-method
+   */
+  save(opts: SavePaymentMethodDraft): Promise<PaymentMethod>;
+
+  /**
+   * Updates an existing payment-method with the given list of update actions. The payment-method must belong to the given customerId.
+   *
+   * @param opts the list of update actions to apply
+   *
+   * @returns the updated payment-method
+   */
+  update(opts: UpdatePaymentMethodService): Promise<PaymentMethod>;
+
+  /**
+   * Deletes the given payment-method
+   *
+   * @param opts the payment-method to delete
+   *
+   * @returns returns the final state of the payment-method before it's deleted
+   */
+  delete(opts: DeletePaymentMethodService): Promise<PaymentMethod>;
+}

package/src/commercetools/types/payment.type.ts

@@ -0,0 +1,74 @@
+import type {
+  CustomFieldsDraft,
+  Money,
+  Payment,
+  PaymentDraft,
+  PaymentMethodInfoDraft,
+  TransactionState,
+  TransactionType,
+} from '@commercetools/platform-sdk';
+import type { CommercetoolsAPI } from '@/commercetools/types/api.type.js';
+import type { Logger } from '@/logger/types/logger.type.js';
+
+export type PaymentAmount = {
+  centAmount: number;
+  currencyCode: string;
+  fractionDigits: number;
+};
+
+export type PaymentServiceOptions = {
+  ctAPI: CommercetoolsAPI;
+  logger: Logger;
+};
+
+export type GetPayment = {
+  id: string;
+  version?: number;
+};
+
+export type FindPaymentsByInterfaceId = {
+  interfaceId: string;
+};
+
+export type PSPInteraction = {
+  request?: string;
+  response?: string;
+};
+
+export type TransactionData = {
+  type: TransactionType;
+  amount: Money;
+  interactionId?: string;
+  interfaceId?: string;
+  state: TransactionState;
+};
+
+export type UpdatePaymentInfo = {
+  id: string;
+  pspReference?: string;
+  pspInteractions?: CustomFieldsDraft[];
+  transaction?: TransactionData;
+  paymentMethod?: string;
+  paymentMethodInfo?: PaymentMethodInfoDraft;
+  customFields?: CustomFieldsDraft;
+  token?: string;
+};
+
+export type FindTransaction = {
+  payment: Payment;
+  transactionType: TransactionType;
+  states: TransactionState[];
+};
+
+/**
+ * Payment service interface exposes methods to interact with the commercetools platform API.
+ */
+export interface PaymentService {
+  getPayment(opts: GetPayment): Promise<Payment>;
+  findPaymentsByInterfaceId(
+    opts: FindPaymentsByInterfaceId,
+  ): Promise<Payment[]>;
+  hasTransactionInState(opts: FindTransaction): boolean;
+  createPayment(draft: PaymentDraft): Promise<Payment>;
+  updatePayment(opts: UpdatePaymentInfo): Promise<Payment>;
+}