@adobe/spacecat-shared-rum-api-client 2.5.4 → 2.7.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-rum-api-client-v2.7.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.6.0...@adobe/spacecat-shared-rum-api-client-v2.7.0) (2024-08-06)
+
+
+### Features
+
+* add support for multiple experiments on the same page ([#309](https://github.com/adobe/spacecat-shared/issues/309)) ([8252e1a](https://github.com/adobe/spacecat-shared/commit/8252e1a74885a73db6193d24facf439b571e9523))
+
+# [@adobe/spacecat-shared-rum-api-client-v2.6.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.5.4...@adobe/spacecat-shared-rum-api-client-v2.6.0) (2024-08-02)
+
+
+### Features
+
+* multi-query support for rum-client ([#311](https://github.com/adobe/spacecat-shared/issues/311)) ([c3ac6a2](https://github.com/adobe/spacecat-shared/commit/c3ac6a20396874d0abffdcdcd50406e9718a426b))
+
 # [@adobe/spacecat-shared-rum-api-client-v2.5.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.5.3...@adobe/spacecat-shared-rum-api-client-v2.5.4) (2024-08-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.5.4",
+  "version": "2.7.0",
   "description": "Shared modules of the Spacecat Services - Rum API client",
   "type": "module",
   "main": "src/index.js",

package/src/common/rum-bundler-client.js

@@ -50,6 +50,109 @@ function getUrlChunks(urls, chunkSize) {
     .map((_, index) => urls.slice(index * chunkSize, (index + 1) * chunkSize));
 }
 
+/* c8 ignore start */
+/*
+ * throw-away code for a single customer who customized the experimentation engine
+ * this code will be removed once they start using the default exp engine
+ *
+ * this function fetches experiment manifests, then merges variants data into controls data
+ *
+ * ie:
+ *
+ * if the customer runs for an experiment where variants are as following:
+ *   control: /
+ *   challenger-1: /a1/
+ *   challenger-2: /a2/
+ *
+ * then data for the `/a1/` and `/a2` are counted towards `/`'s data
+ */
+async function mergeBundlesWithSameId(bundles) {
+  if (!bundles[0]?.url?.includes('bamboohr.com')) return bundles;
+  const prodBaseUrl = 'https://www.bamboohr.com/experiments/';
+  const previewBaseUrl = 'https://main--bamboohr-website--bamboohr.hlx.page/experiments/archive/';
+  const manifestUrls = [
+    ...new Set(bundles.flatMap((bundle) => bundle.events
+      .filter((e) => e.checkpoint === 'experiment')
+      .map((e) => e.source))),
+  ];
+  const manifestUrlPromises = manifestUrls.map(async (experiment) => {
+    try {
+      const response = await fetch(`${prodBaseUrl}${experiment}/manifest.json`);
+      if (!response.ok) {
+        throw new Error('manifest request failed');
+      }
+      const data = await response.json();
+      return { url: `${prodBaseUrl}${experiment}/manifest.json`, data };
+    } catch (error) {
+      try {
+        const previewUrlResponse = await fetch(`${previewBaseUrl}${experiment}/manifest.json`);
+        if (!previewUrlResponse.ok) {
+          throw new Error('manifest request failed');
+        }
+        const previewUrlData = await previewUrlResponse.json();
+        return { url: `${previewBaseUrl}${experiment}/manifest.json`, data: previewUrlData };
+      } catch (err) {
+        return { url: `${previewBaseUrl}${experiment}/manifest.json`, data: null };
+      }
+    }
+  });
+  const experiments = await Promise.all(manifestUrlPromises);
+  let hasSeenPages = false; // required for multi-page experiments
+  const variants = (await Promise.all(experiments.map((e) => e.data)))
+    .filter((json) => json && Object.keys(json).length > 0)
+    .flatMap((json) => json.experiences?.data ?? [])
+    .filter((data) => {
+      if (data.Name === 'Pages') {
+        hasSeenPages = true;
+      } else if (['Percentage Split', 'Label', 'Blocks'].includes(data.Name)) {
+        // reset the flag when we see the next experiment
+        hasSeenPages = false;
+      }
+      return data.Name === 'Pages' || (hasSeenPages && data.Name === '');
+    });
+
+  const mapping = variants.reduce((acc, cur) => {
+    Object.entries(cur)
+      .filter(([k]) => !['Name', 'Control'].includes(k))
+      .forEach(([, v]) => {
+        acc[new URL(v).pathname] = new URL(cur.Control).pathname;
+      });
+    return acc;
+  }, {});
+
+  const variantPaths = Object.keys(mapping);
+
+  const getControlPath = (url) => {
+    const path = new URL(url).pathname;
+    if (variantPaths.includes(path)) return mapping[path];
+    return path;
+  };
+
+  const byIdAndPath = bundles.reduce((acc, cur) => {
+    const controlPath = getControlPath(cur.url);
+    const key = `${cur.id}-${controlPath}`;
+    if (!acc[key]) acc[key] = [];
+    if (variantPaths.includes(new URL(cur.url).pathname)) {
+      // eslint-disable-next-line no-param-reassign
+      cur.url = new URL(controlPath, cur.url).href;
+    }
+    acc[key].push(cur);
+    return acc;
+  }, {});
+
+  const merged = Object.entries(byIdAndPath).flatMap(([, v]) => {
+    let value = v;
+    if (v.length > 1) {
+      v[0].events.push(...v.slice(1).flatMap((bundle) => bundle.events));
+      value = [v[0]];
+    }
+    return value;
+  });
+
+  return Object.values(merged);
+}
+/* c8 ignore end */
+
 async function fetchBundles(opts = {}) {
   const {
     domain,
@@ -84,7 +187,7 @@ async function fetchBundles(opts = {}) {
     const bundles = await Promise.all(responses.map((response) => response.json()));
     result.push(...bundles.flatMap((b) => b.rumBundles.map(filterBundles(checkpoints))));
   }
-  return result;
+  return mergeBundlesWithSameId(result);
 }
 
 export {

package/src/functions/experiment.js

@@ -73,41 +73,50 @@ function updateInferredStartAndEndDate(experimentObject, time) {
   }
 }
 
+function calculateMetrics(bundle) {
+  const metrics = {};
+  for (const checkpoint of METRIC_CHECKPOINTS) {
+    metrics[checkpoint] = {};
+  }
+  for (const event of bundle.events) {
+    if (METRIC_CHECKPOINTS.includes(event.checkpoint)) {
+      const { source, checkpoint } = event;
+      if (!metrics[checkpoint][source]) {
+        metrics[checkpoint][source] = bundle.weight;
+      } else {
+        metrics[checkpoint][source] += bundle.weight;
+      }
+    }
+  }
+  return metrics;
+}
+
 function handler(bundles) {
   const experimentInsights = {};
   for (const bundle of bundles) {
-    const experimentEvent = bundle.events?.find((e) => e.checkpoint === 'experiment');
-    if (experimentEvent) {
-      const { url, weight, time } = bundle;
+    const experimentEvents = bundle.events?.filter(
+      (e) => EXPERIMENT_CHECKPOINT.includes(e.checkpoint),
+    );
+    const { url, weight, time } = bundle;
+    const metrics = calculateMetrics(bundle);
+    for (const experimentEvent of experimentEvents) {
       if (!experimentInsights[url]) {
         experimentInsights[url] = [];
       }
       const experimentName = experimentEvent.source;
       const variantName = experimentEvent.target;
-      const experimentObject = getOrCreateExperimentObject(experimentInsights[url], experimentName);
+      const experimentObject = getOrCreateExperimentObject(
+        experimentInsights[url],
+        experimentName,
+      );
       const variantObject = getOrCreateVariantObject(experimentObject.variants, variantName);
       updateInferredStartAndEndDate(experimentObject, time);
       variantObject.views += weight;
-
-      const metrics = {};
-      for (const checkpoint of METRIC_CHECKPOINTS) {
-        metrics[checkpoint] = {};
-      }
-      for (const event of bundle.events) {
-        if (METRIC_CHECKPOINTS.includes(event.checkpoint)) {
-          const { source, checkpoint } = event;
-          if (!metrics[checkpoint][source]) {
-            metrics[checkpoint][source] = weight;
-          } else {
-            metrics[checkpoint][source] += weight;
-          }
-        }
-      }
       // combine metrics and variantObject, considering the interaction events
       // only once during the session
       for (const checkpoint of METRIC_CHECKPOINTS) {
         // eslint-disable-next-line no-restricted-syntax
-        for (const source in metrics[checkpoint]) {
+        for (const source in metrics?.[checkpoint]) {
           if (!variantObject[checkpoint][source]) {
             variantObject[checkpoint][source] = weight;
           } else {

package/src/functions/traffic-acquisition.js

@@ -11,7 +11,6 @@
  */
 
 import { classifyTrafficSource } from '../common/traffic.js';
-import { fetch } from '../utils.js';
 
 function extractHints(bundle) {
   const findEvent = (checkpoint, source = '') => bundle.events.find((e) => e.checkpoint === checkpoint && (!source || e.source === source)) || {};
@@ -48,81 +47,8 @@ function transformFormat(trafficSources) {
   }));
 }
 
-/* c8 ignore start */
-/*
- * throw-away code for a single customer who customized the experimentation engine
- * this code will be removed once they start using the default exp engine
- *
- * this function fetches experiment manifests, then merges variants data into controls data
- *
- * ie:
- *
- * if the customer runs for an experiment where variants are as following:
- *   control: /
- *   challenger-1: /a1/
- *   challenger-2: /a2/
- *
- * then data for the `/a1/` and `/a2` are counted towards `/`'s data
- */
-async function mergeBundlesWithSameId(bundles) {
-  if (!bundles[0]?.url.includes('bamboohr.com')) return bundles;
-  const manifestUrls = [
-    ...new Set(bundles.flatMap((bundle) => bundle.events
-      .filter((e) => e.checkpoint === 'experiment')
-      .map((e) => e.source))),
-  ].map((experiment) => fetch(`https://www.bamboohr.com/experiments/${experiment}/manifest.json`));
-
-  const experiments = await Promise.all(manifestUrls);
-  const variants = (await Promise.all(experiments.map((e) => e.json().catch(() => {}))))
-    .filter((json) => json && Object.keys(json).length > 0)
-    .flatMap((json) => json.experiences?.data ?? [])
-    .filter((data) => data.Name === 'Pages');
-
-  const mapping = variants.reduce((acc, cur) => {
-    Object.entries(cur)
-      .filter(([k]) => !['Name', 'Control'].includes(k))
-      .forEach(([, v]) => {
-        acc[new URL(v).pathname] = new URL(cur.Control).pathname;
-      });
-    return acc;
-  }, {});
-
-  const variantPaths = Object.keys(mapping);
-
-  const getControlPath = (url) => {
-    const path = new URL(url).pathname;
-    if (variantPaths.includes(path)) return mapping[path];
-    return path;
-  };
-
-  const byIdAndPath = bundles.reduce((acc, cur) => {
-    const controlPath = getControlPath(cur.url);
-    const key = `${cur.id}-${controlPath}`;
-    if (!acc[key]) acc[key] = [];
-    if (variantPaths.includes(new URL(cur.url).pathname)) {
-      // eslint-disable-next-line no-param-reassign
-      cur.url = new URL(controlPath, cur.url).href;
-    }
-    acc[key].push(cur);
-    return acc;
-  }, {});
-
-  const merged = Object.entries(byIdAndPath).flatMap(([, v]) => {
-    let value = v;
-    if (v.length > 1) {
-      v[0].events.push(...v.slice(1).flatMap((bundle) => bundle.events));
-      value = [v[0]];
-    }
-    return value;
-  });
-
-  return Object.values(merged);
-}
-/* c8 ignore end */
-
 async function handler(bundles) {
-  const merged = await mergeBundlesWithSameId(bundles);
-  const trafficSources = merged
+  const trafficSources = bundles
     .map(extractHints)
     .map((row) => {
       const {

package/src/index.d.ts

@@ -21,26 +21,40 @@ export interface RUMAPIOptions {
 
 export default class RUMAPIClient {
   /**
-     * Static factory method to create an instance of RUMAPIClient.
-     * @param {UniversalContext} context - An object containing the AWS Lambda context information
-     * @returns An instance of RUMAPIClient.
-     * @remarks This method is designed to create a new instance from an AWS Lambda context.
-     *   The created instance is stored in the Lambda context, and subsequent calls to
-     *   this method will return the singleton instance if previously created.
-     */
+   * Static factory method to create an instance of RUMAPIClient.
+   * @param {UniversalContext} context - An object containing the AWS Lambda context information
+   * @returns An instance of RUMAPIClient.
+   * @remarks This method is designed to create a new instance from an AWS Lambda context.
+   *   The created instance is stored in the Lambda context, and subsequent calls to
+   *   this method will return the singleton instance if previously created.
+   */
   static createFrom(context: UniversalContext): RUMAPIClient;
 
   /**
-     * Constructor for creating an instance of RUMAPIClient.
-     */
+   * Constructor for creating an instance of RUMAPIClient.
+   */
   constructor();
 
   /**
-     * Asynchronous method to run queries against RUM Bundler API.
-     * @param {string} query - Name of the query to run.
-     * @param {RUMAPIOptions} opts - A object containing options for query to run.
-     * @returns A Promise resolving to an object with the query results.
-     * @remarks See the README.md for the available queries.
-     */
+   * Asynchronous method to run queries against RUM Bundler API.
+   * @param {string} query - Name of the query to run.
+   * @param {RUMAPIOptions} opts - A object containing options for query to run.
+   * @returns A Promise resolving to an object with the query results.
+   * @remarks See the README.md for the available queries.
+   */
   query(query: string, opts?: RUMAPIOptions): Promise<object>;
+
+  /**
+   * Asynchronous method to run multiple queries against the data fetched from RUM Bundler API.
+   *
+   * This method makes a single call to the RUM Bundler API to fetch the raw data, then applies
+   * all the requested queries to this raw data. The results are returned in an object where each
+   * key corresponds to a query name and each value contains the result of that query.
+   *
+   * @param {string[]} queries - An array of query names to execute.
+   * @param {RUMAPIOptions} [opts] - Optional object containing options for the queries.
+   * @returns {Promise<object>} A Promise that resolves to an object where each key is the name
+   * of a query, and each value is the result of that query.
+   */
+  queryMulti(queries: string[], opts?: RUMAPIOptions): Promise<object[]>;
 }

package/src/index.js

@@ -49,4 +49,41 @@ export default class RUMAPIClient {
       throw new Error(`Query '${query}' failed. Opts: ${JSON.stringify(opts)}. Reason: ${e.message}`);
     }
   }
+
+  // eslint-disable-next-line class-methods-use-this
+  async queryMulti(queries, opts) {
+    const queryHandlers = [];
+    const allCheckpoints = new Set();
+
+    for (const query of queries) {
+      const { handler, checkpoints = [] } = HANDLERS[query] || {};
+
+      if (!handler) {
+        throw new Error(`Unknown query: ${query}`);
+      }
+
+      queryHandlers.push({ query, handler });
+      checkpoints.forEach((checkpoint) => allCheckpoints.add(checkpoint));
+    }
+
+    try {
+      // Fetch bundles with deduplicated checkpoints
+      const bundles = await fetchBundles({
+        ...opts,
+        checkpoints: [...allCheckpoints],
+      });
+
+      const results = {};
+
+      // Execute each query handler sequentially
+      for (const { query, handler } of queryHandlers) {
+        // eslint-disable-next-line no-await-in-loop
+        results[query] = await handler(bundles);
+      }
+
+      return results;
+    } catch (e) {
+      throw new Error(`Multi query failed. Queries: ${JSON.stringify(queries)}, Opts: ${JSON.stringify(opts)}. Reason: ${e.message}`);
+    }
+  }
 }