@paypal/checkout-components 5.0.291 → 5.0.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paypal/checkout-components",
-  "version": "5.0.291",
+  "version": "5.0.292",
   "description": "PayPal Checkout components, for integrating checkout products.",
   "main": "index.js",
   "scripts": {

package/src/api/api.js

@@ -0,0 +1,54 @@
+/* @flow */
+
+import { getPartnerAttributionID, getSessionID } from "@paypal/sdk-client/src";
+import { request } from "@krakenjs/belter/src";
+import { ZalgoPromise } from "@krakenjs/zalgo-promise/src";
+
+import { HEADERS } from "../constants/api";
+
+type RestAPIParams = {|
+  method?: string,
+  url: string,
+  data: Object,
+  accessToken: ?string,
+|};
+
+export function callRestAPI({
+  accessToken,
+  method,
+  url,
+  data,
+}: RestAPIParams): ZalgoPromise<Object> {
+  const partnerAttributionID = getPartnerAttributionID() || "";
+
+  if (!accessToken) {
+    throw new Error(`No access token passed to API request ${url}`);
+  }
+
+  const requestHeaders = {
+    [HEADERS.AUTHORIZATION]: `Bearer ${accessToken}`,
+    [HEADERS.CONTENT_TYPE]: `application/json`,
+    [HEADERS.PARTNER_ATTRIBUTION_ID]: partnerAttributionID,
+    [HEADERS.CLIENT_METADATA_ID]: getSessionID(),
+  };
+
+  return request({
+    method,
+    url,
+    headers: requestHeaders,
+    json: data,
+  }).then(({ status, body, headers: responseHeaders }) => {
+    if (status >= 300) {
+      const error = new Error(
+        `${url} returned status ${status}\n\n${JSON.stringify(body)}`
+      );
+
+      // $FlowFixMe
+      error.response = { status, headers: responseHeaders, body };
+
+      throw error;
+    }
+
+    return body;
+  });
+}

package/src/api/shopper-insights/component.jsx

@@ -0,0 +1,197 @@
+/* @flow */
+
+import {
+  getUserIDToken,
+  getPageType,
+  getClientToken,
+  getSDKToken,
+  getLogger,
+  getPayPalAPIDomain,
+  getCurrency,
+  getBuyerCountry,
+  getEnv,
+  getSessionState,
+  sendCountMetric,
+} from "@paypal/sdk-client/src";
+import { FPTI_KEY } from "@paypal/sdk-constants/src";
+import { ZalgoPromise } from "@krakenjs/zalgo-promise/src";
+import { stringifyError } from "@krakenjs/belter/src";
+
+import { callRestAPI } from "../api";
+import {
+  ELIGIBLE_PAYMENT_METHODS,
+  FPTI_TRANSITION,
+  SHOPPER_INSIGHTS_METRIC_NAME,
+  type MerchantPayloadData,
+} from "../../constants/api";
+
+import {
+  validateMerchantConfig,
+  validateMerchantPayload,
+  hasEmail,
+  hasPhoneNumber,
+} from "./validation";
+
+type RecommendedPaymentMethods = {|
+  isPayPalRecommended: boolean,
+  isVenmoRecommended: boolean,
+|};
+
+type getRecommendedPaymentMethodsRequestPayload = {|
+  customer: {|
+    country_code?: string,
+    email?: string,
+    phone?: {|
+      country_code: string,
+      national_number: string,
+    |},
+  |},
+  purchase_units: $ReadOnlyArray<{|
+    amount: {|
+      currency_code: string,
+    |},
+  |}>,
+  preferences: {|
+    include_account_details: boolean,
+  |},
+|};
+
+export type ShopperInsightsComponent = {|
+  getRecommendedPaymentMethods: (MerchantPayloadData) => ZalgoPromise<RecommendedPaymentMethods>,
+|};
+
+function createRecommendedPaymentMethodsRequestPayload(
+  merchantPayload: MerchantPayloadData
+): getRecommendedPaymentMethodsRequestPayload {
+  const isNonProdEnvironment = getEnv() !== "production";
+
+  return {
+    customer: {
+      ...(isNonProdEnvironment && {
+        country_code: getBuyerCountry() || "US",
+      }),
+      // $FlowIssue
+      ...(hasEmail(merchantPayload) && {
+        email: merchantPayload?.customer?.email,
+      }),
+      ...(hasPhoneNumber(merchantPayload) && {
+        phone: {
+          country_code: merchantPayload?.customer?.phone?.countryCode,
+          national_number: merchantPayload?.customer?.phone?.nationalNumber,
+        },
+      }),
+    },
+    purchase_units: [
+      {
+        amount: {
+          currency_code: getCurrency(),
+        },
+      },
+    ],
+    // getRecommendedPaymentMethods maps to include_account_details in the API
+    preferences: {
+      include_account_details: true,
+    },
+  };
+}
+
+function setShopperInsightsUsage() {
+  getSessionState((state) => {
+    return {
+      ...state,
+      shopperInsights: {
+        getRecommendedPaymentMethodsUsed: true,
+      },
+    };
+  });
+}
+
+export function getShopperInsightsComponent(): ShopperInsightsComponent {
+  const startTime = Date.now();
+
+  sendCountMetric({
+    name: SHOPPER_INSIGHTS_METRIC_NAME,
+    event: "init",
+    dimensions: {},
+  });
+
+  const sdkToken = getSDKToken();
+  const pageType = getPageType();
+  const clientToken = getClientToken();
+  const userIDToken = getUserIDToken();
+
+  getLogger().track({
+    [FPTI_KEY.TRANSITION]: FPTI_TRANSITION.SHOPPER_INSIGHTS_API_INIT,
+    [FPTI_KEY.EVENT_NAME]: FPTI_TRANSITION.SHOPPER_INSIGHTS_API_INIT,
+  });
+
+  validateMerchantConfig({ sdkToken, pageType, userIDToken, clientToken });
+
+  const shopperInsights = {
+    getRecommendedPaymentMethods: (merchantPayload) => {
+      validateMerchantPayload(merchantPayload);
+
+      const requestPayload =
+        createRecommendedPaymentMethodsRequestPayload(merchantPayload);
+
+      return callRestAPI({
+        method: "POST",
+        url: `${getPayPalAPIDomain()}/${ELIGIBLE_PAYMENT_METHODS}`,
+        data: requestPayload,
+        accessToken: sdkToken,
+      })
+        .then((body) => {
+          setShopperInsightsUsage();
+
+          const paypal = body?.eligible_methods?.paypal;
+          const venmo = body?.eligible_methods?.venmo;
+
+          const isPayPalRecommended =
+            (paypal?.eligible_in_paypal_network && paypal?.recommended) ||
+            false;
+          const isVenmoRecommended =
+            (venmo?.eligible_in_paypal_network && venmo?.recommended) || false;
+
+          getLogger().track({
+            [FPTI_KEY.TRANSITION]: FPTI_TRANSITION.SHOPPER_INSIGHTS_API_SUCCESS,
+            [FPTI_KEY.EVENT_NAME]: FPTI_TRANSITION.SHOPPER_INSIGHTS_API_SUCCESS,
+            [FPTI_KEY.RESPONSE_DURATION]: (Date.now() - startTime).toString(),
+          });
+
+          sendCountMetric({
+            name: SHOPPER_INSIGHTS_METRIC_NAME,
+            event: "success",
+            dimensions: {
+              isPayPalRecommended: String(isPayPalRecommended),
+              isVenmoRecommended: String(isVenmoRecommended),
+            },
+          });
+
+          return { isPayPalRecommended, isVenmoRecommended };
+        })
+        .catch((err) => {
+          sendCountMetric({
+            name: SHOPPER_INSIGHTS_METRIC_NAME,
+            event: "error",
+            dimensions: {
+              errorType: "api_error",
+            },
+          });
+
+          getLogger().track({
+            [FPTI_KEY.TRANSITION]: FPTI_TRANSITION.SHOPPER_INSIGHTS_API_ERROR,
+            [FPTI_KEY.EVENT_NAME]: FPTI_TRANSITION.SHOPPER_INSIGHTS_API_ERROR,
+            [FPTI_KEY.RESPONSE_DURATION]: (Date.now() - startTime).toString(),
+          });
+
+          getLogger().error("shopper_insights_api_error", {
+            err: stringifyError(err),
+          });
+
+          throw err;
+        });
+    },
+  };
+
+  return shopperInsights;
+}

package/src/api/shopper-insights/component.test.js

@@ -0,0 +1,282 @@
+/* @flow */
+import { ZalgoPromise } from "@krakenjs/zalgo-promise/src";
+import { getEnv, getBuyerCountry } from "@paypal/sdk-client/src";
+import { vi, describe, expect } from "vitest";
+
+import { callRestAPI } from "../api";
+
+import { getShopperInsightsComponent } from "./component";
+
+vi.mock("@paypal/sdk-client/src", () => {
+  return {
+    sendCountMetric: vi.fn(),
+    getSDKToken: vi.fn(() => "sdk-token"),
+    getPageType: vi.fn(() => "product-details"),
+    getClientToken: vi.fn(() => ""),
+    getUserIDToken: vi.fn(() => ""),
+    getEnv: vi.fn(() => "production"),
+    getCurrency: vi.fn(() => "USD"),
+    getBuyerCountry: vi.fn(() => "US"),
+    getPayPalAPIDomain: vi.fn(() => "https://api.paypal.com"),
+    getPartnerAttributionID: vi.fn(() => ""),
+    getSessionID: vi.fn(() => "sdk-session-ID-123"),
+    getSessionState: vi.fn(),
+    getLogger: vi.fn(() => ({ track: vi.fn(), error: vi.fn() })),
+  };
+});
+
+vi.mock("../api", async () => {
+  const actual = await vi.importActual("../api");
+  return {
+    ...actual,
+    callRestAPI: vi.fn(() =>
+      ZalgoPromise.resolve({
+        eligible_methods: {
+          paypal: {
+            can_be_vaulted: true,
+            eligible_in_paypal_network: true,
+            recommended: true,
+            recommended_priority: 1,
+          },
+          venmo: {
+            can_be_vaulted: true,
+            eligible_in_paypal_network: true,
+            recommended: false,
+          },
+        },
+      })
+    ),
+  };
+});
+
+describe("shopper insights component - getRecommendedPaymentMethods()", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("should get recommended payment methods using the shopper insights API", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    const recommendedPaymentMethods =
+      await shopperInsightsComponent.getRecommendedPaymentMethods({
+        customer: {
+          email: "email@test.com",
+          phone: {
+            countryCode: "1",
+            nationalNumber: "2345678901",
+          },
+        },
+      });
+
+    expect(callRestAPI).toHaveBeenCalled();
+    expect(recommendedPaymentMethods).toEqual({
+      isPayPalRecommended: true,
+      isVenmoRecommended: false,
+    });
+    expect.assertions(2);
+  });
+
+  test("catch errors from the API", async () => {
+    // $FlowFixMe
+    callRestAPI.mockImplementationOnce(() =>
+      ZalgoPromise.reject({
+        name: "ERROR",
+        message: "This is an API error",
+      })
+    );
+
+    const shopperInsightsComponent = getShopperInsightsComponent();
+
+    await expect(() =>
+      shopperInsightsComponent.getRecommendedPaymentMethods({
+        customer: {
+          email: "email@test.com",
+          phone: {
+            countryCode: "1",
+            nationalNumber: "2345678901",
+          },
+        },
+      })
+    ).rejects.toThrow("This is an API error");
+    expect(callRestAPI).toHaveBeenCalled();
+    expect.assertions(2);
+  });
+
+  test("create customer payload with email and phone number", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+        phone: {
+          countryCode: "1",
+          nationalNumber: "2345678901",
+        },
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          customer: expect.objectContaining({
+            email: "email@test.com",
+            phone: expect.objectContaining({
+              country_code: "1",
+              national_number: "2345678901",
+            }),
+          }),
+        }),
+      })
+    );
+  });
+
+  test("create customer payload with email only", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          customer: expect.objectContaining({
+            email: "email@test.com",
+          }),
+        }),
+      })
+    );
+  });
+
+  test("create customer payload with phone only", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+        phone: {
+          countryCode: "1",
+          nationalNumber: "2345678901",
+        },
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          customer: expect.objectContaining({
+            phone: expect.objectContaining({
+              country_code: "1",
+              national_number: "2345678901",
+            }),
+          }),
+        }),
+      })
+    );
+  });
+
+  test("should default purchase units with currency code in the customer payload", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          purchase_units: expect.arrayContaining([
+            expect.objectContaining({
+              amount: expect.objectContaining({
+                currency_code: "USD",
+              }),
+            }),
+          ]),
+        }),
+      })
+    );
+  });
+
+  test("should use the SDK buyer-country parameter if country code is not passed in a non-prod env", async () => {
+    // $FlowFixMe
+    getEnv.mockImplementationOnce(() => "stage");
+
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          customer: expect.objectContaining({
+            country_code: "US",
+          }),
+        }),
+      })
+    );
+  });
+
+  test("should default US country code if SDK buyer-country parameter not passed in a non-prod env", async () => {
+    // $FlowFixMe
+    getEnv.mockImplementationOnce(() => "stage");
+    // $FlowFixMe
+    getBuyerCountry.mockImplementationOnce(() => "");
+
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          customer: expect.objectContaining({
+            country_code: "US",
+          }),
+        }),
+      })
+    );
+  });
+
+  test("should not set country code in prod env in the customer payload", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          customer: expect.not.objectContaining({
+            country_code: expect.anything(),
+          }),
+        }),
+      })
+    );
+  });
+
+  test("should request recommended payment methods by setting account details in the payload", async () => {
+    const shopperInsightsComponent = getShopperInsightsComponent();
+    await shopperInsightsComponent.getRecommendedPaymentMethods({
+      customer: {
+        email: "email@test.com",
+      },
+    });
+
+    expect(callRestAPI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          preferences: expect.objectContaining({
+            include_account_details: true,
+          }),
+        }),
+      })
+    );
+  });
+});

package/src/api/shopper-insights/interface.js

@@ -0,0 +1,13 @@
+/* @flow */
+
+import type { LazyProtectedExport } from "../../types";
+import { protectedExport } from "../../lib";
+
+import {
+  getShopperInsightsComponent,
+  type ShopperInsightsComponent,
+} from "./component";
+
+export const ShopperInsights: LazyProtectedExport<ShopperInsightsComponent> = {
+  __get__: () => protectedExport(getShopperInsightsComponent()),
+};

package/src/api/shopper-insights/validation.js

@@ -0,0 +1,137 @@
+/* @flow */
+
+import { sendCountMetric } from "@paypal/sdk-client/src";
+
+import {
+  SHOPPER_INSIGHTS_METRIC_NAME,
+  type MerchantPayloadData,
+} from "../../constants/api";
+import { ValidationError } from "../../lib";
+
+type MerchantConfigParams = {|
+  sdkToken: ?string,
+  pageType: ?string,
+  userIDToken: ?string,
+  clientToken: ?string,
+|};
+
+export function validateMerchantConfig({
+  sdkToken,
+  pageType,
+  userIDToken,
+  clientToken,
+}: MerchantConfigParams) {
+  if (!sdkToken) {
+    sendCountMetric({
+      name: SHOPPER_INSIGHTS_METRIC_NAME,
+      event: "error",
+      dimensions: {
+        errorType: "merchant_configuration_validation_error",
+        validationDetails: "sdk_token_not_present",
+      },
+    });
+
+    throw new ValidationError(
+      `script data attribute sdk-client-token is required but was not passed`
+    );
+  }
+
+  if (!pageType) {
+    sendCountMetric({
+      name: SHOPPER_INSIGHTS_METRIC_NAME,
+      event: "error",
+      dimensions: {
+        errorType: "merchant_configuration_validation_error",
+        validationDetails: "page_type_not_present",
+      },
+    });
+
+    throw new ValidationError(
+      `script data attribute page-type is required but was not passed`
+    );
+  }
+
+  if (userIDToken) {
+    sendCountMetric({
+      name: SHOPPER_INSIGHTS_METRIC_NAME,
+      event: "error",
+      dimensions: {
+        errorType: "merchant_configuration_validation_error",
+        validationDetails: "sdk_token_and_id_token_present",
+      },
+    });
+
+    throw new ValidationError(
+      `use script data attribute sdk-client-token instead of user-id-token`
+    );
+  }
+
+  // Client token has widely adopted integrations in the SDK that we do not want
+  // to support anymore. For now, we will be only enforcing a warning. We should
+  // expand on this warning with upgrade guides when we have them.
+  if (clientToken) {
+    // eslint-disable-next-line no-console
+    console.warn(`script data attribute client-token is not recommended`);
+  }
+}
+
+export const hasEmail = (merchantPayload: MerchantPayloadData): boolean => {
+  return Boolean(merchantPayload?.customer?.email);
+};
+
+export const hasPhoneNumber = (
+  merchantPayload: MerchantPayloadData
+): boolean => {
+  return Boolean(
+    merchantPayload?.customer?.phone?.countryCode &&
+      merchantPayload?.customer?.phone?.nationalNumber
+  );
+};
+
+const isValidEmailFormat = (email: string): boolean => {
+  const emailRegex = /^.+@.+$/;
+  return email.length < 320 && emailRegex.test(email);
+};
+
+const isValidPhoneNumberFormat = (phoneNumber: string): boolean => {
+  const phoneNumberRegex = /\d{5,}/;
+  return phoneNumberRegex.test(phoneNumber);
+};
+
+export function validateMerchantPayload(merchantPayload: MerchantPayloadData) {
+  if (
+    typeof merchantPayload !== "object" ||
+    Object.keys(merchantPayload).length === 0 ||
+    !Object.keys(merchantPayload).includes("customer")
+  ) {
+    throw new ValidationError(
+      `Expected shopper information to be passed into customer object`
+    );
+  }
+
+  const hasEmailOrPhoneNumber =
+    hasEmail(merchantPayload) || hasPhoneNumber(merchantPayload);
+  if (!hasEmailOrPhoneNumber) {
+    throw new ValidationError(
+      `Expected shopper information to include an email or phone number`
+    );
+  }
+
+  const merchantPayloadEmail = merchantPayload?.customer?.email || "";
+  if (hasEmail(merchantPayload) && !isValidEmailFormat(merchantPayloadEmail)) {
+    throw new ValidationError(
+      `Expected shopper information to include a valid email format`
+    );
+  }
+
+  const merchantPhonePayload = merchantPayload?.customer?.phone || {};
+  const nationalNumber = merchantPhonePayload?.nationalNumber || "";
+  if (
+    hasPhoneNumber(merchantPayload) &&
+    !isValidPhoneNumberFormat(nationalNumber)
+  ) {
+    throw new ValidationError(
+      `Expected shopper information to a valid phone number format`
+    );
+  }
+}