@adobe/mysticat-shared-seo-client 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/mysticat-shared-seo-client-v1.3.0](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.2.3...@adobe/mysticat-shared-seo-client-v1.3.0) (2026-04-28)
+
+### Features
+
+* **seo-client:** return keywords[] array from getPaidPages() ([#1564](https://github.com/adobe/spacecat-shared/issues/1564)) ([71be968](https://github.com/adobe/spacecat-shared/commit/71be968ac133fc3c0d547d70e9663fcf2fe90437))
+
+## [@adobe/mysticat-shared-seo-client-v1.2.3](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.2.2...@adobe/mysticat-shared-seo-client-v1.2.3) (2026-04-15)
+
+### Bug Fixes
+
+* **seo-client:** omit display_date to avoid 5x historical pricing ([#1537](https://github.com/adobe/spacecat-shared/issues/1537)) ([4ffc683](https://github.com/adobe/spacecat-shared/commit/4ffc683db492d10414c2bc5c23804ec42d88b2c5))
+
 ## [@adobe/mysticat-shared-seo-client-v1.2.2](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.2.1...@adobe/mysticat-shared-seo-client-v1.2.2) (2026-04-14)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/mysticat-shared-seo-client",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Shared modules of the SpaceCat Services - SEO Client",
   "type": "module",
   "engines": {

package/src/client.js

@@ -15,7 +15,7 @@ import { context as h2, h1 } from '@adobe/fetch';
 
 import { ENDPOINTS } from './endpoints.js';
 import {
-  parseCsvResponse, coerceValue, getLimit, toApiDate, fromApiDate, lastMonthISO, buildFilter,
+  parseCsvResponse, coerceValue, getLimit, toApiDate, fromApiDate, buildFilter,
   extractBrand, INTENT_CODES,
 } from './utils.js';
 
@@ -340,11 +340,28 @@ export default class SeoClient {
     };
   }
 
+  /**
+   * Fetch paid (PPC) pages and their keyword data from Semrush.
+   *
+   * Per-keyword CPC is returned as float dollars (e.g., 3.95) with null for unknown.
+   * This deliberately differs from getOrganicKeywords() which returns CPC as integer
+   * cents (e.g., 395) with 0 for unknown. The float-dollars convention was chosen for
+   * the keywords[] array because downstream consumers (import-worker, Mystique) expect
+   * dollars and the per-keyword CPC should not go through the cents round-trip used by
+   * the aggregate `value` field.
+   *
+   * @param {string} url - Domain to query
+   * @param {Object} [opts] - Options
+   * @param {string} [opts.date] - Report date
+   * @param {number} [opts.limit=200] - Max pages to return
+   * @param {string} [opts.region] - Limit to specific region
+   * @returns {Promise<{result: {pages: Array}, fullAuditRef: string}>}
+   */
   async getPaidPages(url, opts = {}) {
     if (typeof opts !== 'object' || opts === null) {
       throw new Error('Second argument must be an options object, not a positional value');
     }
-    const { date = lastMonthISO(), limit = 200, region } = opts;
+    const { date, limit = 200, region } = opts;
     if (!hasText(url)) {
       throw new Error(`Invalid URL: ${url}`);
     }
@@ -358,15 +375,23 @@ export default class SeoClient {
     // Capped at MAX_PAID_KEYWORDS_FETCH to bound cost.
     const fetchLimit = Math.min(effectiveLimit * 10, MAX_PAID_KEYWORDS_FETCH);
 
-    const dbResults = await this.fanOut(databases, (db) => this.sendRawRequest({
-      type: ep.type,
-      domain: url,
-      database: db,
-      display_date: toApiDate(date),
-      display_limit: fetchLimit,
-      export_columns: ep.columns,
-      ...ep.defaultParams,
-    }, ep.path), 'getPaidPages');
+    const dbResults = await this.fanOut(databases, (db) => {
+      const params = {
+        type: ep.type,
+        domain: url,
+        database: db,
+        display_limit: fetchLimit,
+        export_columns: ep.columns,
+        ...ep.defaultParams,
+      };
+      // Omitting display_date returns the provider's latest snapshot at live pricing
+      // (5x cheaper). The returned data may differ slightly from a pinned monthly
+      // snapshot, which is acceptable for our use case.
+      if (date) {
+        params.display_date = toApiDate(date);
+      }
+      return this.sendRawRequest(params, ep.path);
+    }, 'getPaidPages');
 
     // Group keywords by URL across all databases
     const pageMap = new Map();
@@ -412,6 +437,15 @@ export default class SeoClient {
             ),
             0,
           ),
+          keywords: page.keywords.map((kw) => ({
+            keyword: kw.Ph,
+            traffic: kw.kwTraffic,
+            cpc: coerceValue(kw.Cp, 'float') ?? null,
+            serp_title: kw.Tt || null,
+            position: coerceValue(kw.Po, 'int') ?? null,
+            volume: coerceValue(kw.Nq, 'int') ?? null,
+            country: kw.db.toUpperCase(),
+          })),
         };
       });
 
@@ -425,7 +459,7 @@ export default class SeoClient {
     if (typeof opts !== 'object' || opts === null) {
       throw new Error('Second argument must be an options object, not a positional value');
     }
-    const { date = lastMonthISO(), region } = opts;
+    const { date, region } = opts;
     if (!hasText(url)) {
       throw new Error(`Invalid URL: ${url}`);
     }
@@ -433,14 +467,22 @@ export default class SeoClient {
     const ep = ENDPOINTS.metrics;
     const databases = getDatabases(region);
 
-    const dbResults = await this.fanOut(databases, (db) => this.sendRawRequest({
-      type: ep.type,
-      domain: url,
-      database: db,
-      display_date: toApiDate(date),
-      export_columns: ep.columns,
-      ...ep.defaultParams,
-    }, ep.path), 'getMetrics');
+    const dbResults = await this.fanOut(databases, (db) => {
+      const params = {
+        type: ep.type,
+        domain: url,
+        database: db,
+        export_columns: ep.columns,
+        ...ep.defaultParams,
+      };
+      // Omitting display_date returns the provider's latest snapshot at live pricing
+      // (5x cheaper). The returned data may differ slightly from a pinned monthly
+      // snapshot, which is acceptable for our use case.
+      if (date) {
+        params.display_date = toApiDate(date);
+      }
+      return this.sendRawRequest(params, ep.path);
+    }, 'getMetrics');
 
     const metrics = {
       org_keywords: 0,
@@ -758,7 +800,7 @@ export default class SeoClient {
   }
 
   // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getMetricsByCountry(url, date = lastMonthISO()) {
+  async getMetricsByCountry(url, date) {
     return STUB_RESPONSE;
   }
 }