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

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-rum-api-client",
-  "version": "2.42.0",
+  "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/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 };
+}