@adobe/spacecat-shared-rum-api-client 2.36.4 → 2.37.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-rum-api-client-v2.37.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.36.5...@adobe/spacecat-shared-rum-api-client-v2.37.0) (2025-08-28)
+
+
+### Features
+
+* added metrics and graph data functions for optimization-report ([#919](https://github.com/adobe/spacecat-shared/issues/919)) ([29461b2](https://github.com/adobe/spacecat-shared/commit/29461b246b74423dcd39b0af4e1d140f1a3d3af1))
+
+# [@adobe/spacecat-shared-rum-api-client-v2.36.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.36.4...@adobe/spacecat-shared-rum-api-client-v2.36.5) (2025-08-25)
+
+
+### Bug Fixes
+
+* make max opportunities configurable ([#930](https://github.com/adobe/spacecat-shared/issues/930)) ([2b18c25](https://github.com/adobe/spacecat-shared/commit/2b18c25e8dc3303af0e1a09ebcbe830672368d13))
+
 # [@adobe/spacecat-shared-rum-api-client-v2.36.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.36.3...@adobe/spacecat-shared-rum-api-client-v2.36.4) (2025-08-15)
 
 

package/README.md

@@ -335,7 +335,13 @@ Calculates the amount of inorganic traffic and the bounce rate for each page. Id
 
 ### high-organic-low-ctr (Experimentation Opportunity)
 
-Calculates the amount of non-inorganic (earned and owned) traffic and the click-through rate for each page and vendor. Identifies pages with high non-inorganic traffic and low click-through rates, which can be targeted for future experimentation opportunities. An example payload is provided below:
+Calculates the amount of non-inorganic (earned and owned) traffic and the click-through rate for each page and vendor. Identifies pages with high non-inorganic traffic and low click-through rates, which can be targeted for future experimentation opportunities. 
+
+#### options supported
+- **maxOpportunities** - No. of maximum opportunities to return, defaults to 10
+
+
+An example payload is provided below:
 
 ```json
 [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.36.4",
+  "version": "2.37.0",
   "description": "Shared modules of the Spacecat Services - Rum API client",
   "type": "module",
   "engines": {
@@ -38,8 +38,8 @@
     "@adobe/fetch": "4.2.2",
     "@adobe/helix-shared-wrap": "2.0.2",
     "@adobe/helix-universal": "5.2.2",
-    "@adobe/spacecat-shared-utils": "1.26.4",
     "@adobe/rum-distiller": "1.17.0",
+    "@adobe/spacecat-shared-utils": "1.48.0",
     "aws4": "1.13.2",
     "urijs": "1.19.11"
   },

package/src/functions/opportunities/high-organic-low-ctr.js

@@ -14,7 +14,7 @@ import trafficAcquisition from '../traffic-acquisition.js';
 import { getCTRByUrlAndVendor, getSiteAvgCTR } from '../../common/aggregateFns.js';
 
 const VENDORS_TO_CONSIDER = 5;
-const MAX_OPPORTUNITIES = 10;
+const DEFAULT_MAX_OPPORTUNITIES = 10;
 
 const MAIN_TYPES = ['paid', 'earned', 'owned'];
 
@@ -133,13 +133,13 @@ function sortPagesByEarnedAndOverallTraffic(pages) {
   return percentiles.sort((a, b) => b.percentileScore - a.percentileScore);
 }
 
-function handler(bundles) {
+function handler(bundles, opts) {
   const trafficByUrl = trafficAcquisition.handler(bundles);
   const ctrByUrlAndVendor = getCTRByUrlAndVendor(bundles);
   const siteAvgCTR = getSiteAvgCTR(bundles);
   const pagesSortedByEarnedAndOverallTraffic = sortPagesByEarnedAndOverallTraffic(
     trafficByUrl,
-  ).slice(0, MAX_OPPORTUNITIES);
+  ).slice(0, opts?.maxOpportunities || DEFAULT_MAX_OPPORTUNITIES);
 
   return pagesSortedByEarnedAndOverallTraffic.map((traffic) => ({
     ...traffic,

package/src/functions/reports/optimization/graph.js

@@ -0,0 +1,97 @@
+/*
+ * 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.
+ */
+import {
+  filterBundles,
+  initializeDataChunks,
+  extractMetrics,
+  createTimeSeriesData,
+  calculateTotals,
+  validateDateRange,
+} from './utils.js';
+
+/**
+ * Process URL-specific data
+ * @param {Object} urlFacet - URL facet from DataChunks
+ * @returns {Object} URL-specific data with totals and time series
+ */
+function processUrlData(urlFacet) {
+  const urlBundles = urlFacet.entries;
+  const urlDataChunks = initializeDataChunks(urlBundles, { includeDateFacet: true });
+
+  return {
+    total: extractMetrics(urlFacet),
+    timeSeries: createTimeSeriesData(urlDataChunks.facets.date),
+  };
+}
+
+/**
+ * Process bundles into aggregated graph data
+ * @param {Object[]} bundles - Array of RUM bundles
+ * @returns {Object} Aggregated traffic data
+ */
+function processBundles(bundles) {
+  const dataChunks = initializeDataChunks(bundles, {
+    includeUrlFacet: true,
+    includeDateFacet: true,
+  });
+
+  // Process URL-specific data
+  const byUrl = {};
+  if (dataChunks.facets.url) {
+    dataChunks.facets.url.forEach((urlFacet) => {
+      byUrl[urlFacet.value] = processUrlData(urlFacet);
+    });
+  }
+
+  // Process overall traffic data
+  const trafficData = createTimeSeriesData(dataChunks.facets.date);
+
+  return { trafficData, byUrl };
+}
+
+/**
+ * Main handler function to generate graph data
+ * @param {Object[]} bundles - Array of RUM bundles
+ * @param {Object} opts - Options object
+ * @returns {Object}
+ */
+function handler(bundles, opts) {
+  if (!opts) {
+    return {
+      trafficData: [],
+      byUrl: {},
+      totals: {},
+      urlsFiltered: [],
+      granularity: 'DAILY',
+    };
+  }
+
+  const {
+    startTime, endTime, urls = [],
+  } = opts;
+
+  validateDateRange(startTime, endTime);
+
+  const filteredBundles = filterBundles(bundles, opts);
+  const result = processBundles(filteredBundles);
+
+  return {
+    ...result,
+    totals: calculateTotals(result.trafficData),
+    urlsFiltered: urls,
+    granularity: opts.granularity || 'DAILY',
+  };
+}
+
+export default {
+  handler,
+};

package/src/functions/reports/optimization/metrics.js

@@ -0,0 +1,30 @@
+/*
+ * 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.
+ */
+
+import { initializeDataChunks, calculateMetrics, filterBundles } from './utils.js';
+
+/**
+ * Handler for optimization reports metrics
+ * @param {Object[]} bundles - Array of RUM bundles
+ * @param {Object} opts - Options object
+ * @returns {Object} Calculated metrics
+ */
+function handler(bundles, opts) {
+  const options = opts || {};
+  const filteredBundles = filterBundles(bundles, options);
+  const dataChunks = initializeDataChunks(filteredBundles);
+  return calculateMetrics(dataChunks);
+}
+
+export default {
+  handler,
+};

package/src/functions/reports/optimization/utils.js

@@ -0,0 +1,201 @@
+/*
+ * 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.
+ */
+import { DataChunks, series, facets } from '@adobe/rum-distiller';
+import { computeConversionRate } from '@adobe/rum-distiller/utils.js';
+import { urlMatchesFilter } from '@adobe/spacecat-shared-utils';
+import { loadBundles } from '../../../utils.js';
+
+// Constants
+const METRIC_NAMES = ['organic', 'visits', 'pageViews', 'bounces', 'conversions', 'engagement'];
+const CONVERSION_SPEC = { checkpoint: ['click'] };
+
+/**
+ * Create date facet function for YYYY-MM-DD format
+ * @returns {Function} Date facet function
+ */
+function createDateFacet(bundle) {
+  const date = new Date(bundle.time);
+  return date.toISOString().split('T')[0];
+}
+
+/**
+ * Create conversion series function
+ * @param {DataChunks} dataChunks - DataChunks instance
+ * @returns {Function} Conversion series function
+ */
+function createConversionSeries(dataChunks) {
+  return (bundle) => (bundle
+    && dataChunks.hasConversion(bundle, CONVERSION_SPEC) ? bundle.weight : 0);
+}
+
+/**
+ * Initialize DataChunks with common configuration
+ * @param {Object[]} bundles - Array of RUM bundles
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.includeUrlFacet - Whether to include URL facet aggregation
+ * @param {boolean} options.includeDateFacet - Whether to include date facet aggregation
+ * @returns {DataChunks} Configured DataChunks instance
+ */
+export function initializeDataChunks(bundles, options = {}) {
+  const { includeUrlFacet = false, includeDateFacet = false } = options;
+
+  const dataChunks = new DataChunks();
+
+  // Handle null/undefined bundles
+  const validBundles = (!bundles || !Array.isArray(bundles)) ? [] : bundles;
+
+  // Filter out bundles with missing or invalid URLs
+  const processedBundles = validBundles.filter((bundle) => bundle && bundle.url);
+
+  loadBundles(processedBundles, dataChunks);
+
+  // Add checkpoint facet for conversion detection
+  dataChunks.addFacet('checkpoint', facets.checkpoint, 'every', 'none');
+
+  // Add URL facet if requested
+  if (includeUrlFacet) {
+    dataChunks.addFacet('url', facets.url, 'some', 'none');
+  }
+
+  // Add date facet if requested
+  if (includeDateFacet) {
+    dataChunks.addFacet('date', createDateFacet);
+  }
+
+  // Add metrics series
+  dataChunks.addSeries('pageViews', series.pageViews);
+  dataChunks.addSeries('engagement', series.engagement);
+  dataChunks.addSeries('bounces', series.bounces);
+  dataChunks.addSeries('organic', series.organic);
+  dataChunks.addSeries('visits', series.visits);
+  dataChunks.addSeries('conversions', createConversionSeries(dataChunks));
+
+  return dataChunks;
+}
+
+/**
+ * Extract metrics from a facet
+ * @param {Object} facet - DataChunks facet
+ * @returns {Object} Metrics object
+ */
+export function extractMetrics(facet) {
+  return METRIC_NAMES.reduce((acc, metric) => {
+    acc[metric] = facet.metrics[metric]?.sum || 0;
+    return acc;
+  }, {});
+}
+
+/**
+ * Create time series data from date facets
+ * @param {Object[]} dateFacets - Array of date facets
+ * @returns {Object[]} Sorted time series data
+ */
+export function createTimeSeriesData(dateFacets) {
+  return dateFacets
+    .map((facet) => ({
+      date: facet.value,
+      ...extractMetrics(facet),
+    }))
+    .sort((a, b) => new Date(a.date) - new Date(b.date));
+}
+
+/**
+ * Calculate metrics from a DataChunks instance
+ * @param {DataChunks} chunk - DataChunks instance
+ * @returns {Object} Calculated metrics
+ */
+export function calculateMetrics(chunk) {
+  const {
+    totals,
+  } = chunk;
+  return {
+    pageViews: { total: totals.pageViews?.sum || 0 },
+    visits: { total: totals.visits?.sum || 0 },
+    organicTraffic: { total: totals.organic?.sum || 0 },
+    bounces: {
+      total: totals.bounces?.sum || 0,
+      rate: computeConversionRate(totals.bounces?.sum || 0, totals.visits?.sum || 0) || 0,
+    },
+    engagement: {
+      total: totals.engagement?.sum || 0,
+      rate: computeConversionRate(totals.conversions?.sum || 0, totals.engagement?.sum || 0) || 0,
+    },
+    conversions: {
+      total: totals.conversions?.sum || 0,
+      rate: computeConversionRate(totals.conversions?.sum || 0, totals.pageViews?.sum || 0) || 0,
+    },
+  };
+}
+
+/**
+ * Calculate totals from time series data
+ * @param {Object[]} timeSeriesData - Array of time series data points
+ * @returns {Object} Totals object
+ */
+export function calculateTotals(timeSeriesData) {
+  return timeSeriesData.reduce((acc, data) => {
+    METRIC_NAMES.forEach((metric) => {
+      acc[metric] += (data[metric] || 0);
+    });
+    return acc;
+  }, METRIC_NAMES.reduce((acc, metric) => {
+    acc[metric] = 0;
+    return acc;
+  }, {}));
+}
+
+/**
+ * Filter bundles based on the outlierUrls and urls
+ * @param {Object[]} bundles - Array of RUM bundles
+ * @param {Object} opts - Options object
+ * @param {string[]} opts.outlierUrls - URLs to exclude
+ * @param {string[]} opts.urls - URLs to include
+ * @returns {Object[]} Filtered bundles
+ */
+export function filterBundles(bundles, opts) {
+  // Handle null/undefined opts
+  const options = opts || {};
+
+  const {
+    outlierUrls,
+    urls,
+  } = options;
+
+  if (!bundles || !Array.isArray(bundles)) {
+    return [];
+  }
+
+  // Filter bundles by outlier URLs if provided
+  let filteredBundles = bundles;
+  if (outlierUrls && outlierUrls.length > 0) {
+    filteredBundles = filteredBundles
+      .filter((item) => item && item.url && !urlMatchesFilter(item.url, outlierUrls));
+  }
+
+  // If urls filter is provided, keep only those URLs
+  if (urls && urls.length > 0) {
+    filteredBundles = filteredBundles
+      .filter((item) => item && item.url && urlMatchesFilter(item.url, urls));
+  }
+  return filteredBundles;
+}
+
+/**
+ * Validate date range
+ * @param {string} startTime
+ * @param {string} endTime
+ */
+export function validateDateRange(startTime, endTime) {
+  if (startTime && endTime && new Date(startTime) > new Date(endTime)) {
+    throw new Error('Start time must be before end time');
+  }
+}

package/src/index.js

@@ -25,6 +25,8 @@ import rageclick from './functions/opportunities/rageclick.js';
 import highInorganicHighBounceRate from './functions/opportunities/high-inorganic-high-bounce-rate.js';
 import highOrganicLowCtr from './functions/opportunities/high-organic-low-ctr.js';
 import trafficAnalysis from './functions/traffic-analysis.js';
+import optimizationReportMetrics from './functions/reports/optimization/metrics.js';
+import optimizationReportGraph from './functions/reports/optimization/graph.js';
 
 // exported for tests
 export const RUM_BUNDLER_API_HOST = 'https://bundles.aem.page';
@@ -44,6 +46,8 @@ const HANDLERS = {
   pageviews,
   trafficMetrics,
   'traffic-analysis': trafficAnalysis,
+  'optimization-report-metrics': optimizationReportMetrics,
+  'optimization-report-graph': optimizationReportGraph,
 };
 
 function sanitize(opts) {