@adobe/spacecat-shared-rum-api-client 2.41.1 → 2.43.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-rum-api-client-v2.43.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.42.0...@adobe/spacecat-shared-rum-api-client-v2.43.0) (2026-06-15)
+
+### Features
+
+* **rum-api-client:** add resolveRumDomainKey shared utility ([#1662](https://github.com/adobe/spacecat-shared/issues/1662)) ([c3249f0](https://github.com/adobe/spacecat-shared/commit/c3249f011727e9297b191bf6ca0a78d6f462942e))
+
+## [@adobe/spacecat-shared-rum-api-client-v2.42.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.41.1...@adobe/spacecat-shared-rum-api-client-v2.42.0) (2026-06-09)
+
+### Features
+
+* Add per-field engagement metrics for forms ([#1653](https://github.com/adobe/spacecat-shared/issues/1653)) ([b6dba5b](https://github.com/adobe/spacecat-shared/commit/b6dba5bd9abb623aecf2d3f5d8e1e36bf427a919))
+
 ## [@adobe/spacecat-shared-rum-api-client-v2.41.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.41.0...@adobe/spacecat-shared-rum-api-client-v2.41.1) (2026-05-29)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.41.1",
+  "version": "2.43.0",
   "description": "Shared modules of the Spacecat Services - Rum API client",
   "type": "module",
   "engines": {

package/src/client.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright 2024 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 { hasText, fetch } from '@adobe/spacecat-shared-utils';
+import { fetchBundles, createBundleStream } from './common/rum-bundler-client.js';
+import notfound from './functions/404.js';
+import notfoundInternalLinks from './functions/404-internal-links.js';
+import cwv from './functions/cwv.js';
+import formVitals from './functions/form-vitals.js';
+import experiment from './functions/experiment.js';
+import trafficAcquisition from './functions/traffic-acquisition.js';
+import totalMetrics from './functions/total-metrics.js';
+import variant from './functions/variant.js';
+import pageviews from './functions/pageviews.js';
+import trafficMetrics from './functions/traffic-metrics.js';
+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';
+import userEngagement from './functions/user-engagement.js';
+
+// exported for tests
+export const RUM_BUNDLER_API_HOST = 'https://bundles.aem.page';
+
+const HANDLERS = {
+  404: notfound,
+  '404-internal-links': notfoundInternalLinks,
+  cwv,
+  'form-vitals': formVitals,
+  experiment,
+  'traffic-acquisition': trafficAcquisition,
+  variant,
+  rageclick,
+  totalMetrics,
+  'high-inorganic-high-bounce-rate': highInorganicHighBounceRate,
+  'high-organic-low-ctr': highOrganicLowCtr,
+  pageviews,
+  trafficMetrics,
+  'traffic-analysis': trafficAnalysis,
+  'optimization-report-metrics': optimizationReportMetrics,
+  'optimization-report-graph': optimizationReportGraph,
+  'user-engagement': userEngagement,
+};
+
+function sanitize(opts) {
+  return {
+    ...opts,
+    /* c8 ignore next 1 */
+    ...(hasText(opts.domainkey) && { domainkey: `${opts.domainkey.slice(0, 3)}***` }),
+  };
+}
+
+export default class RUMAPIClient {
+  static createFrom(context) {
+    const { env, log = console } = context;
+    const { RUM_ADMIN_KEY: rumAdminKey } = env;
+
+    if (context.rumApiClient) {
+      return context.rumApiClient;
+    }
+
+    const client = new RUMAPIClient({ rumAdminKey }, log);
+    context.rumApiClient = client;
+    return client;
+  }
+
+  constructor({ rumAdminKey }, log) {
+    this.log = log;
+    this.rumAdminKey = rumAdminKey;
+    this.domainkeyCache = {};
+  }
+
+  async _exchangeDomainkey(domain) {
+    if (hasText(this.domainkeyCache[domain])) {
+      return this.domainkeyCache[domain];
+    }
+
+    const resp = await fetch(`${RUM_BUNDLER_API_HOST}/domainkey/${domain}`, {
+      headers: {
+        Authorization: `Bearer ${this.rumAdminKey}`,
+      },
+    });
+
+    if (!resp.ok) {
+      throw new Error(`Error during fetching domainkey for domain '${domain} using admin key. Status: ${resp.status}`);
+    }
+
+    try {
+      const json = await resp.json();
+      if (!hasText(json.domainkey)) {
+        throw new Error(`Unexpected response: ${JSON.stringify(json)}`);
+      }
+      this.domainkeyCache[domain] = json.domainkey;
+      return json.domainkey;
+    } catch (e) {
+      throw new Error(`Error during fetching domainkey for domain '${domain} using admin key. Error: ${e.message}`);
+    }
+  }
+
+  async _getDomainkey(opts) {
+    const { domain, domainkey } = opts;
+
+    if (!hasText(domainkey) && !hasText(this.rumAdminKey)) {
+      throw new Error('You need to provide a \'domainkey\' or set RUM_ADMIN_KEY env variable');
+    }
+
+    if (hasText(domainkey)) {
+      return domainkey;
+    }
+
+    return this._exchangeDomainkey(domain);
+  }
+
+  async retrieveDomainkey(domain) {
+    return this._exchangeDomainkey(domain);
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  async query(query, opts) {
+    const { handler, checkpoints } = HANDLERS[query] || {};
+    if (!handler) {
+      throw new Error(`Unknown query ${query}`);
+    }
+
+    try {
+      const domainkey = await this._getDomainkey(opts);
+      const bundles = await fetchBundles({
+        ...opts,
+        domainkey,
+        checkpoints,
+      }, this.log);
+
+      this.log.debug(`Query "${query}" fetched ${bundles.length} bundles`); // maybe even remove?
+      return handler(bundles, opts);
+    } catch (e) {
+      throw new Error(`Query '${query}' failed. Opts: ${JSON.stringify(sanitize(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 {
+      const domainkey = await this._getDomainkey(opts);
+
+      // Fetch bundles with deduplicated checkpoints
+      const bundles = await fetchBundles({
+        ...opts,
+        domainkey,
+        checkpoints: [...allCheckpoints],
+      }, this.log);
+
+      const results = {};
+      this.log.debug(`Multi query ${JSON.stringify(queries.join(', '))} fetched ${bundles.length} bundles`); // maybe even remove?
+
+      // Execute each query handler sequentially
+      for (const { query, handler } of queryHandlers) {
+        // eslint-disable-next-line no-await-in-loop
+        results[query] = await handler(bundles, opts);
+      }
+
+      return results;
+    } catch (e) {
+      throw new Error(`Multi query failed. Queries: ${JSON.stringify(queries)}, Opts: ${JSON.stringify(sanitize(opts))}. Reason: ${e.message}`);
+    }
+  }
+
+  async queryStream(query, opts) {
+    const { handler, checkpoints } = HANDLERS[query] || {};
+    if (!handler) {
+      throw new Error(`Unknown query ${query}`);
+    }
+
+    try {
+      const domainkey = await this._getDomainkey(opts);
+      return createBundleStream({
+        ...opts,
+        domainkey,
+        checkpoints,
+        handler,
+      }, this.log);
+    } catch (e) {
+      throw new Error(`Query stream '${query}' failed. Opts: ${JSON.stringify(sanitize(opts))}. Reason: ${e.message}`);
+    }
+  }
+}

package/src/functions/form-field-engagement.js

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2026 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.
+ */
+
+// Per-field form engagement helper. NOT a RUM query — invoked from form-vitals.js to
+// attach a `fieldEngagement` property to each form-vitals entry (like trafficacquisition).
+
+import { FORM_KEYWORDS_TO_FILTER, isFormSource } from '../utils.js';
+
+const average = (nums) => (nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : 0);
+
+const isSearchEvent = (event) => FORM_KEYWORDS_TO_FILTER.some(
+  (kw) => event.source?.toLowerCase().includes(kw) || event.target?.toLowerCase().includes(kw),
+);
+
+/**
+ * Average time (in seconds) spent on a field before the next interaction.
+ * Direct port of time_spent_in_seconds() from forms-analysis-automation:
+ * within each bundle, sort events by timeDelta; for every click/fill on this
+ * selector, take the gap to the next event; average the gaps and convert ms → s.
+ */
+function timeSpentInSeconds(urlBundles, selector) {
+  const deltaDiffs = [];
+  for (const bundle of urlBundles) {
+    const sortedEvents = [...bundle.events].sort((a, b) => a.timeDelta - b.timeDelta);
+    for (let i = 0; i < sortedEvents.length - 1; i += 1) {
+      const event = sortedEvents[i];
+      if ((event.checkpoint === 'click' || event.checkpoint === 'fill')
+        && event.source === selector) {
+        deltaDiffs.push(sortedEvents[i + 1].timeDelta - event.timeDelta);
+      }
+    }
+  }
+  return Math.round((average(deltaDiffs) / 1000) * 100) / 100;
+}
+
+/** Average absolute timeDelta of a field's click/fill events — used for output ordering. */
+function avgInteractionTime(urlBundles, selector) {
+  const times = [];
+  for (const bundle of urlBundles) {
+    for (const event of bundle.events) {
+      if ((event.checkpoint === 'click' || event.checkpoint === 'fill')
+        && event.source === selector && event.timeDelta != null) {
+        times.push(event.timeDelta);
+      }
+    }
+  }
+  return average(times);
+}
+
+/**
+ * Single-traversal collection of weighted click/fill counts per field selector.
+ * Returns a Map<source, { clicks, fills }> for all form-scoped field events.
+ */
+function getFieldMetrics(urlBundles, formSourceKey) {
+  const metricsMap = new Map();
+  for (const bundle of urlBundles) {
+    for (const event of bundle.events) {
+      if ((event.checkpoint === 'click' || event.checkpoint === 'fill')
+        && event.source && !isSearchEvent(event)
+        && isFormSource(formSourceKey, event.source)) {
+        if (!metricsMap.has(event.source)) {
+          metricsMap.set(event.source, { clicks: 0, fills: 0 });
+        }
+        const metrics = metricsMap.get(event.source);
+        if (event.checkpoint === 'click') {
+          metrics.clicks += bundle.weight;
+        } else {
+          metrics.fills += bundle.weight;
+        }
+      }
+    }
+  }
+  return metricsMap;
+}
+
+/**
+ * Computes per-field engagement for a single form on a page.
+ *
+ * @param {Array} urlBundles - RUM bundles already filtered to the form's page URL
+ * @param {string} formSourceKey - form key extracted from the form source (e.g. 'abc'
+ *   for 'form#abc'), or 'unknown'
+ * @returns {Array<{source: string, clicks: number, fills: number, avg_time_spend: number}>}
+ *   fields ordered by average absolute timeDelta (natural form interaction order)
+ */
+export function computeFieldEngagement(urlBundles, formSourceKey) {
+  const fieldMetrics = getFieldMetrics(urlBundles, formSourceKey);
+
+  return [...fieldMetrics.keys()]
+    .map((source) => ({
+      source,
+      clicks: fieldMetrics.get(source).clicks,
+      fills: fieldMetrics.get(source).fills,
+      avg_time_spend: timeSpentInSeconds(urlBundles, source),
+    }))
+    .sort((a, b) => avgInteractionTime(urlBundles, a.source)
+      - avgInteractionTime(urlBundles, b.source));
+}

package/src/functions/form-vitals.js

@@ -12,7 +12,10 @@
 
 import { DataChunks, facets } from '@adobe/rum-distiller';
 import trafficAcquisition from './traffic-acquisition.js';
-import { DELIMITER, generateKey, loadBundles } from '../utils.js';
+import { computeFieldEngagement } from './form-field-engagement.js';
+import {
+  DELIMITER, generateKey, loadBundles, isFormSource,
+} from '../utils.js';
 
 const METRICS = ['formview', 'formengagement', 'formsubmit'];
 const CHECKPOINTS = ['viewblock', 'click', 'fill', 'formsubmit', 'navigate', 'viewmedia', 'experiment'];
@@ -53,15 +56,6 @@ function filterEvents(bundles) {
   }));
 }
 
-function isFormSource(source, eventSource) {
-  const excludeSrc = ['form.', 'form#'];
-  if (source === 'unknown') {
-    return /\bform\b/.test(eventSource?.toLowerCase()) && !excludeSrc.some((exclude) => eventSource?.includes(exclude));
-  } else {
-    return eventSource?.includes(source);
-  }
-}
-
 const metricFns = {
   formview: (source) => (bundle) => {
     const formView = bundle.events.find((e) => e.checkpoint === 'viewblock' && isFormSource(source, e.source));
@@ -321,6 +315,13 @@ function handler(bundles) {
         iframeSrc,
       });
     }
+    // attach per-field engagement for this form (mirrors the trafficacquisition property)
+    const fieldMatch = formVitalCopy.formsource?.match(/form[#.]((?:\\[0-9a-fA-F]{1,6}\s?|\w|-)+)/);
+    const fieldFormSourceKey = fieldMatch ? fieldMatch[1] : 'unknown';
+    formVitalCopy.fieldEngagement = computeFieldEngagement(
+      bundles.filter((b) => b.url === formVitalCopy.url),
+      fieldFormSourceKey,
+    );
     return formVitalCopy;
   });
 

package/src/index.d.ts

@@ -50,6 +50,27 @@ export interface RUMAPIOptions {
   }>;
 }
 
+/**
+ * Result returned by resolveRumDomainKey.
+ */
+export interface RumDomainKeyResult {
+  /** True if a RUM domain key was found for any candidate domain. */
+  hasDomainKey: boolean;
+  /** True if the lookup was aborted due to the 3 s shared timeout. */
+  timedOut: boolean;
+}
+
+/**
+ * Checks whether a site has a RUM domain key by trying up to four candidate domains
+ * in priority order: overrideBaseURL, www.override, baseURL, www.base.
+ * Stops on the first successful lookup. The 3 s timeout is shared across all candidates.
+ *
+ * @param site - Site model instance (requires getId, getBaseURL, getConfig).
+ * @param context - Request/worker context (requires env and log).
+ * @returns { hasDomainKey, timedOut }
+ */
+export function resolveRumDomainKey(site: object, context: UniversalContext): Promise<RumDomainKeyResult>;
+
 export default class RUMAPIClient {
   /**
    * Static factory method to create an instance of RUMAPIClient.

package/src/index.js

@@ -9,201 +9,8 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import { hasText, fetch } from '@adobe/spacecat-shared-utils';
-import { fetchBundles, createBundleStream } from './common/rum-bundler-client.js';
-import notfound from './functions/404.js';
-import notfoundInternalLinks from './functions/404-internal-links.js';
-import cwv from './functions/cwv.js';
-import formVitals from './functions/form-vitals.js';
-import experiment from './functions/experiment.js';
-import trafficAcquisition from './functions/traffic-acquisition.js';
-import totalMetrics from './functions/total-metrics.js';
-import variant from './functions/variant.js';
-import pageviews from './functions/pageviews.js';
-import trafficMetrics from './functions/traffic-metrics.js';
-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';
-import userEngagement from './functions/user-engagement.js';
+import RUMAPIClient from './client.js';
 
-// exported for tests
-export const RUM_BUNDLER_API_HOST = 'https://bundles.aem.page';
-
-const HANDLERS = {
-  404: notfound,
-  '404-internal-links': notfoundInternalLinks,
-  cwv,
-  'form-vitals': formVitals,
-  experiment,
-  'traffic-acquisition': trafficAcquisition,
-  variant,
-  rageclick,
-  totalMetrics,
-  'high-inorganic-high-bounce-rate': highInorganicHighBounceRate,
-  'high-organic-low-ctr': highOrganicLowCtr,
-  pageviews,
-  trafficMetrics,
-  'traffic-analysis': trafficAnalysis,
-  'optimization-report-metrics': optimizationReportMetrics,
-  'optimization-report-graph': optimizationReportGraph,
-  'user-engagement': userEngagement,
-};
-
-function sanitize(opts) {
-  return {
-    ...opts,
-    /* c8 ignore next 1 */
-    ...(hasText(opts.domainkey) && { domainkey: `${opts.domainkey.slice(0, 3)}***` }),
-  };
-}
-
-export default class RUMAPIClient {
-  static createFrom(context) {
-    const { env, log = console } = context;
-    const { RUM_ADMIN_KEY: rumAdminKey } = env;
-
-    if (context.rumApiClient) {
-      return context.rumApiClient;
-    }
-
-    const client = new RUMAPIClient({ rumAdminKey }, log);
-    context.rumApiClient = client;
-    return client;
-  }
-
-  constructor({ rumAdminKey }, log) {
-    this.log = log;
-    this.rumAdminKey = rumAdminKey;
-    this.domainkeyCache = {};
-  }
-
-  async _exchangeDomainkey(domain) {
-    if (hasText(this.domainkeyCache[domain])) {
-      return this.domainkeyCache[domain];
-    }
-
-    const resp = await fetch(`${RUM_BUNDLER_API_HOST}/domainkey/${domain}`, {
-      headers: {
-        Authorization: `Bearer ${this.rumAdminKey}`,
-      },
-    });
-
-    if (!resp.ok) {
-      throw new Error(`Error during fetching domainkey for domain '${domain} using admin key. Status: ${resp.status}`);
-    }
-
-    try {
-      const json = await resp.json();
-      if (!hasText(json.domainkey)) {
-        throw new Error(`Unexpected response: ${JSON.stringify(json)}`);
-      }
-      this.domainkeyCache[domain] = json.domainkey;
-      return json.domainkey;
-    } catch (e) {
-      throw new Error(`Error during fetching domainkey for domain '${domain} using admin key. Error: ${e.message}`);
-    }
-  }
-
-  async _getDomainkey(opts) {
-    const { domain, domainkey } = opts;
-
-    if (!hasText(domainkey) && !hasText(this.rumAdminKey)) {
-      throw new Error('You need to provide a \'domainkey\' or set RUM_ADMIN_KEY env variable');
-    }
-
-    if (hasText(domainkey)) {
-      return domainkey;
-    }
-
-    return this._exchangeDomainkey(domain);
-  }
-
-  async retrieveDomainkey(domain) {
-    return this._exchangeDomainkey(domain);
-  }
-
-  // eslint-disable-next-line class-methods-use-this
-  async query(query, opts) {
-    const { handler, checkpoints } = HANDLERS[query] || {};
-    if (!handler) {
-      throw new Error(`Unknown query ${query}`);
-    }
-
-    try {
-      const domainkey = await this._getDomainkey(opts);
-      const bundles = await fetchBundles({
-        ...opts,
-        domainkey,
-        checkpoints,
-      }, this.log);
-
-      this.log.debug(`Query "${query}" fetched ${bundles.length} bundles`); // maybe even remove?
-      return handler(bundles, opts);
-    } catch (e) {
-      throw new Error(`Query '${query}' failed. Opts: ${JSON.stringify(sanitize(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 {
-      const domainkey = await this._getDomainkey(opts);
-
-      // Fetch bundles with deduplicated checkpoints
-      const bundles = await fetchBundles({
-        ...opts,
-        domainkey,
-        checkpoints: [...allCheckpoints],
-      }, this.log);
-
-      const results = {};
-      this.log.debug(`Multi query ${JSON.stringify(queries.join(', '))} fetched ${bundles.length} bundles`); // maybe even remove?
-
-      // Execute each query handler sequentially
-      for (const { query, handler } of queryHandlers) {
-        // eslint-disable-next-line no-await-in-loop
-        results[query] = await handler(bundles, opts);
-      }
-
-      return results;
-    } catch (e) {
-      throw new Error(`Multi query failed. Queries: ${JSON.stringify(queries)}, Opts: ${JSON.stringify(sanitize(opts))}. Reason: ${e.message}`);
-    }
-  }
-
-  async queryStream(query, opts) {
-    const { handler, checkpoints } = HANDLERS[query] || {};
-    if (!handler) {
-      throw new Error(`Unknown query ${query}`);
-    }
-
-    try {
-      const domainkey = await this._getDomainkey(opts);
-      return createBundleStream({
-        ...opts,
-        domainkey,
-        checkpoints,
-        handler,
-      }, this.log);
-    } catch (e) {
-      throw new Error(`Query stream '${query}' failed. Opts: ${JSON.stringify(sanitize(opts))}. Reason: ${e.message}`);
-    }
-  }
-}
+export default RUMAPIClient;
+export { RUM_BUNDLER_API_HOST } from './client.js';
+export { resolveRumDomainKey } from './rum-domain-key.js';

package/src/rum-domain-key.js

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2026 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 RUMAPIClient from './client.js';
+
+const RUM_CHECK_TIMEOUT_MS = 3000;
+
+/**
+ * Resolves whether a site has a RUM domain key by trying candidates in priority order:
+ *   1. overrideBaseURL hostname (from fetchConfig, when set)
+ *   2. www.{overrideHostname}
+ *   3. baseURL hostname
+ *   4. www.{baseHostname}
+ *
+ * Stops on the first successful lookup. The 3 s timeout is a shared budget across
+ * the full candidate loop, not a per-domain limit.
+ *
+ * @param {object} site - Site model instance (getBaseURL, getConfig, getId).
+ * @param {object} context - Request/worker context (env, log).
+ * @returns {Promise<{hasDomainKey: boolean, timedOut: boolean}>}
+ */
+export async function resolveRumDomainKey(site, context) {
+  const { log } = context;
+  const siteId = site.getId();
+
+  const siteConfig = site.getConfig();
+  const overrideBaseURL = siteConfig.getFetchConfig()?.overrideBaseURL;
+
+  let overrideHostname = null;
+  if (overrideBaseURL) {
+    try {
+      overrideHostname = new URL(overrideBaseURL).hostname;
+    } catch {
+      log.warn(`[rum-domain-key] Malformed overrideBaseURL for site ${siteId}: ${overrideBaseURL}, falling back to baseURL`);
+    }
+  }
+
+  let baseHostname;
+  try {
+    baseHostname = new URL(site.getBaseURL()).hostname;
+  } catch {
+    log.error(`[rum-domain-key] Malformed baseURL for site ${siteId}: ${site.getBaseURL()}, skipping`);
+    return { hasDomainKey: false, timedOut: false };
+  }
+
+  const withWww = (d) => (d && !d.startsWith('www.') ? `www.${d}` : null);
+
+  const domains = [...new Set([
+    overrideHostname,
+    withWww(overrideHostname),
+    baseHostname,
+    withWww(baseHostname),
+  ].filter(Boolean))];
+
+  let hasDomainKey = false;
+  let timeoutId;
+  let timedOut = false;
+  let cancelled = false;
+
+  const rumApiClient = RUMAPIClient.createFrom(context);
+
+  try {
+    await Promise.race([
+      (async () => {
+        for (const domain of domains) {
+          if (cancelled) {
+            break;
+          }
+          try {
+            // eslint-disable-next-line no-await-in-loop
+            await rumApiClient.retrieveDomainkey(domain);
+            hasDomainKey = true;
+            return;
+          } catch (e) {
+            log.info(`[rum-domain-key] RUM check failed for ${domain}: ${e.message}`);
+          }
+        }
+        if (!hasDomainKey) {
+          log.warn(`[rum-domain-key] No domain key found for site ${siteId} across all candidates: ${domains.join(', ')}`);
+        }
+      })(),
+      new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+          timedOut = true;
+          cancelled = true;
+          reject(new Error('RUM check timed out'));
+        }, RUM_CHECK_TIMEOUT_MS);
+      }),
+    ]);
+  } catch (e) {
+    if (timedOut) {
+      log.warn(`[rum-domain-key] RUM check timed out for site ${siteId} across: ${domains.join(', ')}`);
+    /* c8 ignore next 3 */
+    } else {
+      log.warn(`[rum-domain-key] Unexpected error during RUM check for site ${siteId}: ${e.message}`);
+    }
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  return { hasDomainKey, timedOut };
+}

package/src/utils.js

@@ -16,6 +16,21 @@ import { classifyTraffic } from './common/traffic.js';
 
 export const DELIMITER = '≡';
 
+export const FORM_KEYWORDS_TO_FILTER = ['search'];
+
+/**
+ * Checks whether a bundle event's source belongs to the given form source key.
+ * Shared between form-vitals.js and form-field-engagement.js.
+ */
+export function isFormSource(source, eventSource) {
+  const excludeSrc = ['form.', 'form#'];
+  if (source === 'unknown') {
+    return /\bform\b/.test(eventSource?.toLowerCase()) && !excludeSrc.some((exclude) => eventSource?.includes(exclude));
+  } else {
+    return eventSource?.includes(source);
+  }
+}
+
 export const generateKey = (...keys) => keys.join(DELIMITER);
 
 export const trafficSeriesFn = (memo, type) => (bundle) => {