@commercetools/checkout-payments-processor-sdk 0.0.6

package/src/commercetools/helpers/currency.converter.ts

@@ -0,0 +1,102 @@
+const validateFractionDigit = (fractionDigit: number): void => {
+  if (!Number.isSafeInteger(fractionDigit)) {
+    throw new Error(
+      `The given fraction digit of "${fractionDigit}" is not a integer. Fraction digit must be an integer value.`,
+    );
+  }
+};
+
+const validateAmount = (amount: number): void => {
+  if (!Number.isSafeInteger(amount)) {
+    throw new Error(
+      `The given value of ${amount} is not a safe integer number`,
+    );
+  }
+};
+
+/**
+ * Applies the fraction digit to the given amount.
+ * Positive fraction digit moves the decimal to the right, negative to the left. (i.e. adding or removing zeros from either end)
+ *
+ * @example (10, -2) => 0.1
+ * @example (10, -1) => 1
+ * @example (10, 0) => 10
+ * @example (10, 1) => 100
+ * @example (10, 2) => 1000
+ * @example (12345, -3) => 12,345
+ * @example (12345, -2) => 123,45
+ * @example (12345, -1) => 1234,5
+ * @example (12345, 0) => 12345
+ * @example (12345, 1) => 123450
+ * @example (12345, 2) => 1234500
+ * @example (12345, 3) => 12345000
+ *
+ *
+ * @param amount Integer value to apply the fraction digit to
+ * @param fractionDigit The fraction digit to apply
+ * @throws an Error if the given fraction digit (either via mapping or directly) is not a integer value
+ */
+const convert = (amount: number, fractionDigit: number): number => {
+  validateFractionDigit(fractionDigit);
+  validateAmount(amount);
+
+  const result = amount * 10 ** fractionDigit;
+  const strResult = result.toFixed(Math.abs(fractionDigit));
+  return parseFloat(strResult);
+};
+
+type ConvertWithMappingOptions = {
+  /**
+   * A mapping where the key is the ISO 4217 currency code value and the value is the fraction digit (integer value) to apply.
+   */
+  mapping: Map<string, number>;
+  /**
+   * The amount to apply the fraction digit to
+   */
+  amount: number;
+  /**
+   * The currency code that belongs to this amount. This is used to lookup the value in the mapping to see if it needs to be overruled
+   */
+  currencyCode: string;
+  /**
+   * The fraction digit
+   */
+  fractionDigit?: number;
+};
+
+/**
+ * Applies the given fraction digit to the amount with the possibility to overrule the fraction digit via the supplied mapping.
+ *
+ * @param options The options to use with converting
+ *
+ * @function convert for more information how the fractionDigit is applied
+ *
+ * @returns The original value if neither the overruling fraction digit is found or no fraction digit is given, otherwise returns the converted value based on either the overruling fraction digit or fraction digit
+ *
+ * @throws an Error if the given fraction digit (either via mapping or directly) is not a integer value
+ */
+const convertWithMapping = (options: ConvertWithMappingOptions) => {
+  const {
+    amount,
+    currencyCode,
+    mapping,
+    fractionDigit: fractionDigits,
+  } = options;
+
+  const overrulingFractionDigits = mapping.get(currencyCode);
+
+  if (overrulingFractionDigits) {
+    validateFractionDigit(overrulingFractionDigits);
+    return convert(amount, overrulingFractionDigits);
+  }
+
+  if (fractionDigits) {
+    validateFractionDigit(fractionDigits);
+    return convert(amount, fractionDigits);
+  }
+
+  return amount;
+};
+
+export { convert, convertWithMapping };
+export type { ConvertWithMappingOptions };

package/src/commercetools/helpers/taxrate.converter.test.ts

@@ -0,0 +1,48 @@
+import { convertCoCoTaxPercentage } from '@/commercetools/helpers/taxrate.converter.js';
+
+describe('taxrate.converter.ts', () => {
+  test('should return 0 if no decimalTaxRate is provided', () => {
+    const got = convertCoCoTaxPercentage(undefined);
+
+    expect(got).toBe(0);
+  });
+
+  test('should throw an error if the decimalTaxRate is below 0', () => {
+    expect(() => convertCoCoTaxPercentage(-0.0001)).toThrow(
+      `The provided decimal tax rate of -0.0001 is invalid. Only allowed values between 0 and 1.0`,
+    );
+  });
+
+  test('should throw an error if the decimalTaxRate is above 1', () => {
+    expect(() => convertCoCoTaxPercentage(1.01)).toThrow(
+      `The provided decimal tax rate of 1.01 is invalid. Only allowed values between 0 and 1.0`,
+    );
+  });
+
+  test('should correctly convert a set of tax rates from CoCo', () => {
+    // [expectedValue, decimalTaxRate]
+    const cocoDefinedTaxRates = [
+      [100, 0.01], // 1%
+      [200, 0.02], // 2%
+      [1000, 0.1], // 10%
+      [1100, 0.11], // 11%
+      [2100, 0.21], // 21%
+      [770, 0.077], // 7.7%
+      [700, 0.07], // 7.0%
+      [475, 0.0475], // 4.75%
+      [550, 0.055], // 5.5%
+      [4891, 0.4891], // 48.91%
+      [1500, 0.15], // 15%
+      [0, 0], // 0%
+    ];
+
+    for (const testCase of cocoDefinedTaxRates) {
+      const expectedValue = testCase[0];
+      const decimalTaxRate = testCase[1];
+
+      const got = convertCoCoTaxPercentage(decimalTaxRate);
+
+      expect(got).toBe(expectedValue);
+    }
+  });
+});

package/src/commercetools/helpers/taxrate.converter.ts

@@ -0,0 +1,39 @@
+/**
+ * Convert the CoCo tax percentage, for example found on "lineItems", which ranges from 0-1 as floating point numbers to the minor units.
+ *
+ * @example CoCo taxRate of 0.21, normalized is 21%, in minor-units = 2100
+ * @example CoCo taxRate of 0.07, normalized is 7%, in minor-units = 700
+ * @example CoCo taxRate of 0.489, normalized is 48.9%, in minor-units = 4891
+ *
+ * @param decimalTaxRate the tax rate expressed in decimals between 0-1 as floating point numbers taken from the CoCo taxRate (see docs below).
+ *
+ * @throw "Error" if the provided value is not between 0 and 1;
+ *
+ * @returns 0 if undefined is provided
+ *
+ * @see https://docs.commercetools.com/api/projects/taxCategories#ctp:api:type:TaxRate
+ */
+const convertCoCoTaxPercentage = (
+  decimalTaxRate?: number, // decimal allowed value
+): number => {
+  if (!decimalTaxRate) {
+    return 0;
+  }
+
+  if (decimalTaxRate < 0 || decimalTaxRate > 1) {
+    throw new Error(
+      `The provided decimal tax rate of ${decimalTaxRate} is invalid. Only allowed values between 0 and 1.0`,
+    );
+  }
+
+  // First go from the range of 0 - 1 decimal value, to value expressed as a "normal" percentage. I.e. 0.15% from CoCo becomes 15.
+  const taxRateNormalized = decimalTaxRate * 10 ** 2;
+
+  // Apply conversion to make it a minor unit "minor-units" format. I.e. 15 becomes 1500.
+  const taxRateMinorUnitsFormat = taxRateNormalized * 10 ** 2;
+  const taxRateMinorUnit = taxRateMinorUnitsFormat.toFixed(0);
+
+  return parseInt(taxRateMinorUnit, 10);
+};
+
+export { convertCoCoTaxPercentage };

package/src/commercetools/index.ts

@@ -0,0 +1,22 @@
+// API Layer
+export * from '@/commercetools/api/base-api.js';
+export * from '@/commercetools/api/cart-api.js';
+export * from '@/commercetools/api/custom-type-api.js';
+export * from '@/commercetools/api/order-api.js';
+export * from '@/commercetools/api/payment-api.js';
+export * from '@/commercetools/api/payment-method-api.js';
+export * from '@/commercetools/api/root-api.js';
+// Errors
+export * from '@/commercetools/errors/ct-api.error.js';
+// Helpers
+export * from '@/commercetools/helpers/currency.converter.js';
+export * from '@/commercetools/helpers/taxrate.converter.js';
+// Services Layer
+export * from '@/commercetools/services/ct-cart.service.js';
+export * from '@/commercetools/services/ct-custom-type.service.js';
+export * from '@/commercetools/services/ct-order.service.js';
+export * from '@/commercetools/services/ct-payment.service.js';
+export * from '@/commercetools/services/ct-payment-method.service.js';
+
+// Predefined Custom Types
+export * from '@/commercetools/types/predefined-custom-types.type.js';