@adobe/spacecat-shared-rum-api-client 2.20.2 → 2.21.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-rum-api-client-v2.21.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.20.2...@adobe/spacecat-shared-rum-api-client-v2.21.0) (2025-02-11)
+
+
+### Features
+
+* **rum-api-client:** admin key support ([#590](https://github.com/adobe/spacecat-shared/issues/590)) ([0213fa3](https://github.com/adobe/spacecat-shared/commit/0213fa3697cfc006c9edb5038a10ecc896cb6b6e))
+
 # [@adobe/spacecat-shared-rum-api-client-v2.20.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-rum-api-client-v2.20.1...@adobe/spacecat-shared-rum-api-client-v2.20.2) (2025-02-08)
 
 

package/README.md

@@ -12,18 +12,22 @@ npm install @adobe/spacecat-shared-rum-api-client
 
 ## Usage
 
-#### Creating and instance from Helix UniversalContext
+#### Creating an instance from Helix UniversalContext
 
 ```js
-const context = {}; // Your AWS Lambda context object
+// The context must include an 'env' property so that the client can use RUM_ADMIN_KEY if needed.
+const context = { env: process.env };
 const rumApiClient = RUMAPIClient.createFrom(context);
-
 ```
 
-#### From constructor
+#### Using the constructor
 
 ```js
-const rumApiClient = new RUMAPIClient();
+// Optionally, pass a configuration and a logger objects to the constructor.
+// If you want the client to automatically fetch the domainkey for a domain,
+// provide the admin key as 'rumAdminKey'. If omitted, you must provide the domainkey
+// in the query options.
+const rumApiClient = new RUMAPIClient({ rumAdminKey: '<admin-key>' }, logger);
 ```
 
 ### Running a query
@@ -31,25 +35,38 @@ const rumApiClient = new RUMAPIClient();
 ```js
 const opts = {
   domain: 'www.aem.live',
+  // Either provide the domainkey directly...
   domainkey: '<domain-key>',
+  // ...or omit it to let the client auto-fetch it if an admin key is configured.
   granularity: 'hourly',
   interval: 10
-}
+};
 
 const result = await rumApiClient.query('cwv', opts);
-console.log(`Query result: ${result}`)
+console.log(`Query result: ${result}`);
 ```
 
-**Note**: all queries must be lowercase
+**Note**: All query names must be lowercase.
 
 ### Query Options: the 'opts' object
 
-| option      | required | default | remarks             |
-|-------------|----------|---------|---------------------|
-| domain      | yes      |         |                     |
-| domainkey   | yes      |         |                     |
-| interval    | no       | 7       | days in integer     |
-| granularity | no       | daily   | 'daily' or 'hourly' |
+| Option      | Required | Default | Remarks                                                  |
+|-------------|----------|---------|----------------------------------------------------------|
+| domain      | yes      |         | The domain for which to fetch data.                      |
+| domainkey   | no       |         | Provide directly or omit to auto-fetch using `RUM_ADMIN_KEY`. |
+| interval    | no       | 7       | Interval in days (integer).                              |
+| granularity | no       | daily   | 'daily' or 'hourly'.                                     |
+
+
+### Retrieving and Caching the Domainkey
+
+You can also retrieve the domainkey for a given domain directly using the new `retrieveDomainkey` method.
+This method will fetch the domainkey using the admin key (if necessary) and cache it for subsequent calls.
+
+```js
+const domainKey = await rumApiClient.retrieveDomainkey('www.example.com');
+console.log(`Domain key: ${domainKey}`);
+```
 
 ## Available queries
 

package/package.json

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

package/src/index.d.ts

@@ -13,52 +13,85 @@
 import { UniversalContext } from '@adobe/helix-universal';
 
 export interface RUMAPIOptions {
-    domain: string;
-    domainkey: string;
-    interval?: number;
-    granularity?: 'hourly' | 'daily';
-    groupedURLs?: Array<{
-      name: string;
-      pattern: string;
-    }>;
+  /** The domain for which to fetch data. */
+  domain: string;
+
+  /**
+   * The domain key. If not provided, the client will attempt to auto-fetch the domainkey
+   * using the admin key (if configured). Fetched domainkeys are cached for subsequent calls.
+   */
+  domainkey?: string;
+
+  /**
+   * Interval in days.
+   * @default 7
+   */
+  interval?: number;
+
+  /**
+   * Granularity can be 'hourly' or 'daily'.
+   * @default 'daily'
+   */
+  granularity?: 'hourly' | 'daily';
+
+  groupedURLs?: Array<{
+    name: string;
+    pattern: string;
+  }>;
 }
 
 export default class RUMAPIClient {
   /**
    * Static factory method to create an instance of RUMAPIClient.
-   * @param {UniversalContext} context - An object containing the AWS Lambda context information
+   *
+   * @param {UniversalContext} context - An object containing the HelixUniversal context.
+   * The context must include an `env` property that can optionally include a `RUM_ADMIN_KEY`.
    * @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.
+   * @remarks This method creates a new instance from a HelixUniversal context and
+   * caches it on the context.
    */
   static createFrom(context: UniversalContext): RUMAPIClient;
 
   /**
    * Constructor for creating an instance of RUMAPIClient.
+   *
+   * @param options Optional configuration. If you want the client to auto-fetch the domainkey,
+   * provide the admin key as `rumAdminKey`.
+   * @param log Optional logger, defaults to `console`.
    */
-  constructor();
+  constructor(options?: { rumAdminKey?: string }, log?: Console);
 
   /**
-   * 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.
+   * Asynchronous method to run a query against the RUM Bundler API.
+   *
+   * @param query - Name of the query to run.
+   * @param opts - A object containing options for the query. Either provide a `domainkey`
+   *               here or configure an admin key so that the client can fetch it automatically.
    * @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>;
+  query(query: string, opts: RUMAPIOptions): Promise<object>;
 
   /**
-   * Asynchronous method to run multiple queries against the data fetched from RUM Bundler API.
+   * Asynchronous method to run multiple queries against the data fetched from the 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.
+   * @param queries - An array of query names to execute.
+   * @param opts - Optional object containing options for the queries.
+   * @returns 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>;
+
+  /**
+   * Retrieves the domainkey for the given domain. If the domainkey was already fetched,
+   * the cached value is returned.
+   *
+   * @param domain - The domain for which to retrieve the domainkey.
+   * @returns A Promise resolving to the domainkey string.
    */
-  queryMulti(queries: string[], opts?: RUMAPIOptions): Promise<object>;
+  retrieveDomainkey(domain: string): Promise<string>;
 }

package/src/index.js

@@ -9,7 +9,7 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import { hasText } from '@adobe/spacecat-shared-utils';
+import { hasText, fetch } from '@adobe/spacecat-shared-utils';
 import { fetchBundles } from './common/rum-bundler-client.js';
 import notfound from './functions/404.js';
 import notfoundInternalLinks from './functions/404-internal-links.js';
@@ -23,6 +23,9 @@ 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';
 
+// exported for tests
+export const RUM_BUNDLER_API_HOST = 'https://bundles.aem.page';
+
 const HANDLERS = {
   404: notfound,
   '404-internal-links': notfoundInternalLinks,
@@ -47,17 +50,65 @@ function sanitize(opts) {
 
 export default class RUMAPIClient {
   static createFrom(context) {
-    const { log = console } = context;
+    const { env, log = console } = context;
+    const { RUM_ADMIN_KEY: rumAdminKey } = env;
 
     if (context.rumApiClient) return context.rumApiClient;
 
-    const client = new RUMAPIClient(log);
+    const client = new RUMAPIClient({ rumAdminKey }, log);
     context.rumApiClient = client;
     return client;
   }
 
-  constructor(log) {
+  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
@@ -66,8 +117,11 @@ export default class RUMAPIClient {
     if (!handler) throw new Error(`Unknown query ${query}`);
 
     try {
+      const domainkey = await this._getDomainkey(opts);
+
       const bundles = await fetchBundles({
         ...opts,
+        domainkey,
         checkpoints,
       }, this.log);
 
@@ -96,9 +150,12 @@ export default class RUMAPIClient {
     }
 
     try {
+      const domainkey = await this._getDomainkey(opts);
+
       // Fetch bundles with deduplicated checkpoints
       const bundles = await fetchBundles({
         ...opts,
+        domainkey,
         checkpoints: [...allCheckpoints],
       }, this.log);