@adobe/spacecat-shared-utils 1.28.4 → 1.30.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-utils-v1.30.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.29.0...@adobe/spacecat-shared-utils-v1.30.0) (2025-02-06)
+
+
+### Features
+
+* adding more opportunities utils for forms ([#580](https://github.com/adobe/spacecat-shared/issues/580)) ([4cb7d5d](https://github.com/adobe/spacecat-shared/commit/4cb7d5d94ff887932809416b3cf918fc3b56a58d))
+
+# [@adobe/spacecat-shared-utils-v1.29.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.28.4...@adobe/spacecat-shared-utils-v1.29.0) (2025-02-03)
+
+
+### Features
+
+* add utility api for forms metrics ([#566](https://github.com/adobe/spacecat-shared/issues/566)) ([a7365b6](https://github.com/adobe/spacecat-shared/commit/a7365b6eaabf6178a7febd2f25a4083e60d0156b))
+
 # [@adobe/spacecat-shared-utils-v1.28.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.28.3...@adobe/spacecat-shared-utils-v1.28.4) (2025-02-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.28.4",
+  "version": "1.30.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "engines": {
@@ -39,7 +39,7 @@
     "chai": "5.1.2",
     "chai-as-promised": "8.0.1",
     "husky": "9.1.7",
-    "nock": "13.5.6",
+    "nock": "14.0.0",
     "sinon": "19.0.2",
     "sinon-chai": "4.0.0"
   },

package/src/formcalc.js

@@ -0,0 +1,196 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+const DAILY_PAGEVIEW_THRESHOLD = 200;
+const CR_THRESHOLD_RATIO = 0.2;
+const MOBILE = 'mobile';
+const DESKTOP = 'desktop';
+
+/**
+ * Aggregates the form vitals by device type.
+ *
+ * @param {*} formVitalsCollection - form vitals collection
+ * @returns {object} - aggregated form vitals by device type
+ */
+function aggregateFormVitalsByDevice(formVitalsCollection) {
+  const resultMap = new Map();
+
+  formVitalsCollection.forEach((item) => {
+    const {
+      url, formview = {}, formengagement = {}, pageview = {}, formsubmit = {},
+    } = item;
+
+    const totals = {
+      formview: { total: 0, desktop: 0, mobile: 0 },
+      formengagement: { total: 0, desktop: 0, mobile: 0 },
+      pageview: { total: 0, desktop: 0, mobile: 0 },
+      formsubmit: { total: 0, desktop: 0, mobile: 0 },
+    };
+
+    const calculateSums = (metric, initialTarget) => {
+      const updatedTarget = { ...initialTarget }; // Create a new object to store the updated totals
+      Object.entries(metric).forEach(([key, value]) => {
+        updatedTarget.total += value;
+        if (key.startsWith(DESKTOP)) {
+          updatedTarget.desktop += value;
+        } else if (key.startsWith(MOBILE)) {
+          updatedTarget.mobile += value;
+        }
+      });
+      return updatedTarget; // Return the updated target
+    };
+
+    totals.formview = calculateSums(formview, totals.formview);
+    totals.formengagement = calculateSums(formengagement, totals.formengagement);
+    totals.pageview = calculateSums(pageview, totals.pageview);
+    totals.formsubmit = calculateSums(formsubmit, totals.formsubmit);
+
+    resultMap.set(url, totals);
+  });
+
+  return resultMap;
+}
+
+function hasHighPageViews(interval, pageViews) {
+  return pageViews > DAILY_PAGEVIEW_THRESHOLD * interval;
+}
+
+function hasLowerConversionRate(formSubmit, formViews) {
+  return formSubmit / formViews < CR_THRESHOLD_RATIO;
+}
+
+function hasLowFormViews(pageViews, formViews) {
+  return formViews > 0 && (formViews / pageViews) < 0.7;
+}
+
+function hasHighPageViewLowFormCtr(ctaPageViews, ctaClicks, ctaPageTotalClicks, formPageViews) {
+  return ctaPageTotalClicks > 0
+      && (ctaClicks / ctaPageTotalClicks) < 0.4
+      && (formPageViews / ctaPageViews) < 0.1;
+}
+
+/**
+ * Returns the form urls with high form views and low conversion rate
+ *
+ * @param {*} formVitalsCollection - form vitals collection
+ * @returns {Array} - urls with high form views and low conversion rate
+ */
+export function getHighFormViewsLowConversionMetrics(formVitalsCollection, interval) {
+  const resultMap = aggregateFormVitalsByDevice(formVitalsCollection);
+  const urls = [];
+  resultMap.forEach((metrics, url) => {
+    const pageViews = metrics.pageview.total;
+    // Default to pageViews if formViews are not available
+    const formViews = metrics.formview.total || pageViews;
+    const formEngagement = metrics.formengagement.total;
+    const formSubmit = metrics.formsubmit.total || formEngagement;
+
+    if (hasHighPageViews(interval, pageViews) && hasLowerConversionRate(formSubmit, formViews)) {
+      urls.push({
+        url,
+        pageViews,
+        formViews,
+        formEngagement,
+        formSubmit,
+      });
+    }
+  });
+  return urls;
+}
+
+/**
+ * Returns the form urls with high page views and low form views
+ *
+ * @param resultMap
+ * @returns {*[]}
+ */
+export function getHighPageViewsLowFormViewsMetrics(formVitalsCollection, interval) {
+  const urls = [];
+  const resultMap = aggregateFormVitalsByDevice(formVitalsCollection);
+  resultMap.forEach((metrics, url) => {
+    const { total: pageViews } = metrics.pageview;
+    const { total: formViews } = metrics.formview;
+    const { total: formEngagement } = metrics.formengagement;
+
+    if (hasHighPageViews(interval, pageViews) && hasLowFormViews(pageViews, formViews)) {
+      urls.push({
+        url,
+        pageViews,
+        formViews,
+        formEngagement,
+      });
+    }
+  });
+  return urls;
+}
+
+/**
+ * Returns the form urls with high page views containing ctr and low form views
+ * @param formVitalsCollection
+ * @param formVitalsByDevice
+ * @returns {*[]}
+ */
+export function getHighPageViewsLowFormCtrMetrics(formVitalsCollection, interval) {
+  const urls = [];
+  const formVitalsByDevice = aggregateFormVitalsByDevice(formVitalsCollection);
+  formVitalsCollection.forEach((entry) => {
+    const { forminternalnavigation, pageview } = entry;
+    // Calculate `x`: sum of pageview for the URL with the highest sum
+    let x = 0;
+    let maxPageviewUrl = null;
+    if (forminternalnavigation) {
+      forminternalnavigation.forEach((nav) => {
+        if (nav.pageview) {
+          const pageviewSum = Object.values(nav.pageview).reduce((sum, val) => sum + val, 0);
+          if (pageviewSum > x) {
+            x = pageviewSum;
+            maxPageviewUrl = nav;
+          }
+        }
+      });
+    }
+
+    // Skip entry if no valid maxPageviewUrl is found
+    if (!maxPageviewUrl) return;
+
+    // Calculate `y`: find the CTA with the highest clicks and include the source
+    const y = maxPageviewUrl.CTAs.reduce((maxCta, cta) => {
+      if (cta.clicks > (maxCta.clicks || 0)) {
+        return cta;
+      }
+      return maxCta;
+    }, { clicks: 0, source: '' });
+
+    // Get `z`: totalClicksOnPage for the matched URL
+    const z = maxPageviewUrl.totalClicksOnPage || 0;
+    // Calculate `f`: sum of `pageview` for `formengagement`
+    const f = Object.values(pageview).reduce((sum, val) => sum + val, 0);
+
+    // Evaluate conditions and add URL to the result if all are met
+    if (hasHighPageViews(interval, x) && hasHighPageViewLowFormCtr(x, y.clicks, z, f)) {
+      const deviceData = formVitalsByDevice.get(entry.url);
+      if (deviceData != null) {
+        urls.push({
+          url: entry.url,
+          pageViews: deviceData.pageview.total,
+          formViews: deviceData.formview.total,
+          formEngagement: deviceData.formengagement.total,
+          CTA: {
+            url: maxPageviewUrl.url,
+            source: y.source,
+          },
+        });
+      }
+    }
+  });
+  return urls;
+}

package/src/index.d.ts

@@ -163,7 +163,32 @@ declare function replacePlaceholders(content: string, placeholders: object): str
  * or null if an error occurs.
  */
 declare function getPrompt(placeholders: object, filename: string, log: object):
-  Promise<string|null>;
+  Promise<string | null>;
+
+/**
+ * Retrieves the high-form-view-low-form-conversion metrics from the provided array of form vitals.
+ * @param {Object[]} formVitals - An array of form vitals.
+ * @param {number} interval - The interval in days.
+ * @returns {Object[]} - An array of high-form-view-low-form-conversion metrics.
+ */
+declare function getHighFormViewsLowConversionMetrics(formVitals: object[], interval: number):
+  object[];
+
+/**
+ * Retrieves the high-page-view-low-form-view metrics from the provided array of form vitals.
+ * @param {Object[]} formVitals - An array of form vitals.
+ * @returns {Object[]} - An array of high-page-view-low-form-view metrics.
+ */
+declare function getHighPageViewsLowFormViewsMetrics(formVitals: object[], interval: number):
+    object[];
+
+/**
+ * Retrieves the high-page-view-low-form-ctr metrics from the provided array of form vitals.
+ * @param {Object[]} formVitals - An array of form vitals.
+ * @returns {Object[]} - An array of high-page-view-low-form-ctr metrics.
+ */
+declare function getHighPageViewsLowFormCtrMetrics(formVitals: object[], interval: number):
+    object[];
 
 /**
  * Retrieves stored metrics from S3.
@@ -179,7 +204,7 @@ declare function getPrompt(placeholders: object, filename: string, log: object):
  * @returns {Promise<any|*[]>} - The stored metrics
  */
 export function getStoredMetrics(config: object, context: object):
-    Promise<Array<object>>;
+  Promise<Array<object>>;
 
 /**
  * Stores metrics in S3.
@@ -198,8 +223,8 @@ export function getStoredMetrics(config: object, context: object):
 export function storeMetrics(content: object, config: object, context: object): Promise<string>;
 
 export function s3Wrapper(fn: (request: object, context: object) => Promise<Response>):
-    (request: object, context: object) => Promise<Response>;
+  (request: object, context: object) => Promise<Response>;
 
-export function fetch(url: string|Request, options?: RequestOptions): Promise<Response>;
+export function fetch(url: string | Request, options?: RequestOptions): Promise<Response>;
 
-export function tracingFetch(url: string|Request, options?: RequestOptions): Promise<Response>;
+export function tracingFetch(url: string | Request, options?: RequestOptions): Promise<Response>;

package/src/index.js

@@ -61,3 +61,4 @@ export { s3Wrapper } from './s3.js';
 
 export { fetch } from './adobe-fetch.js';
 export { tracingFetch } from './tracing-fetch.js';
+export { getHighFormViewsLowConversionMetrics, getHighPageViewsLowFormViewsMetrics, getHighPageViewsLowFormCtrMetrics } from './formcalc.js';