@adobe/mysticat-shared-seo-client 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/mysticat-shared-seo-client-v1.2.0](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.1.3...@adobe/mysticat-shared-seo-client-v1.2.0) (2026-04-10)
+
+### Features
+
+* **seo-client:** fan-out queries across markets using site region ([#1522](https://github.com/adobe/spacecat-shared/issues/1522)) ([8b2260c](https://github.com/adobe/spacecat-shared/commit/8b2260c6f49410a56c9d5fd7b37b2faf5ab36acb))
+
 ## [@adobe/mysticat-shared-seo-client-v1.1.3](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.1.2...@adobe/mysticat-shared-seo-client-v1.1.3) (2026-04-09)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/mysticat-shared-seo-client",
-  "version": "1.1.3",
+  "version": "1.2.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, todayISO, buildFilter,
+  parseCsvResponse, coerceValue, getLimit, toApiDate, fromApiDate, lastMonthISO, buildFilter,
   extractBrand, INTENT_CODES,
 } from './utils.js';
 
@@ -30,6 +30,30 @@ const MAX_PAID_KEYWORDS_FETCH = 10000;
 const RATE_LIMIT_BASE_DELAY_MS = 1000;
 const MAX_RETRIES = 4;
 
+/**
+ * Major SEO provider databases by search volume. Used as the default fan-out
+ * set for getTopPages to aggregate traffic across top global markets.
+ */
+export const BIG_MARKETS = ['us', 'in', 'jp', 'br', 'uk', 'de', 'fr', 'ph', 'ca', 'it', 'au', 'mx', 'id', 'es', 'pk', 'nl', 'bd', 'pl', 'my', 'kr', 'th', 'co', 'ru', 'tr', 'ar', 'za', 'pe', 'vn', 'tw', 'ae'];
+
+/**
+ * Returns the list of databases to query: BIG_MARKETS + site region if not already present.
+ * @param {string} [region] - ISO 3166-1 alpha-2 region code (e.g. 'CZ')
+ * @returns {string[]}
+ */
+export function getDatabases(region) {
+  const databases = [...BIG_MARKETS];
+  if (region) {
+    const db = region.toLowerCase();
+    if (!databases.includes(db)) {
+      databases.push(db);
+    }
+  }
+  return databases;
+}
+
+const FANOUT_BATCH_SIZE = 10;
+
 const STUB_RESPONSE = { result: {}, fullAuditRef: '' };
 
 export default class SeoClient {
@@ -65,6 +89,43 @@ export default class SeoClient {
     this.log = log;
   }
 
+  /**
+   * @private
+   * Fans out an async operation across items in batches, collects fulfilled
+   * results, and logs rejected ones. Each call to `fn(item)` already has
+   * per-request retry/backoff via sendRawRequest; this layer adds batching to
+   * respect rate limits and consistent error reporting for items that fail
+   * after all retries are exhausted.
+   *
+   * @param {string[]} items - Items to process (database codes, URLs, etc.)
+   * @param {function(string): Promise<T>} fn - Async operation per item
+   * @param {string} operation - Name for logging (e.g. 'getTopPages')
+   * @returns {Promise<Array<{key: string, value: T}>>} Fulfilled results
+   * @template T
+   */
+  async fanOut(items, fn, operation) {
+    const fulfilled = [];
+
+    for (let i = 0; i < items.length; i += FANOUT_BATCH_SIZE) {
+      const batch = items.slice(i, i + FANOUT_BATCH_SIZE);
+      // eslint-disable-next-line no-await-in-loop
+      const results = await Promise.allSettled(batch.map((item) => fn(item)));
+
+      for (let j = 0; j < results.length; j += 1) {
+        const key = batch[j];
+        const result = results[j];
+        if (result.status === 'fulfilled') {
+          fulfilled.push({ key, value: result.value });
+        } else {
+          /* c8 ignore next */
+          this.log.warn(`${operation}: ${key} failed — ${result.reason?.message || result.reason}`);
+        }
+      }
+    }
+
+    return fulfilled;
+  }
+
   /**
    * Internal method that executes the HTTP request and returns the raw CSV body.
    * Used by all endpoint methods for CSV parsing.
@@ -152,7 +213,11 @@ export default class SeoClient {
     return { result, fullAuditRef };
   }
 
-  async getTopPages(url, limit = 200) {
+  async getTopPages(url, opts = {}) {
+    if (typeof opts !== 'object' || opts === null) {
+      throw new Error('Second argument must be an options object, not a positional value');
+    }
+    const { limit = 200, region } = opts;
     if (!hasText(url)) {
       throw new Error(`Invalid URL: ${url}`);
     }
@@ -160,51 +225,70 @@ export default class SeoClient {
     const ep = ENDPOINTS.topPages;
     const epKw = ENDPOINTS.topPagesKeywords;
     const effectiveLimit = getLimit(limit, 2000);
+    const databases = getDatabases(region);
+
+    const dbResults = await this.fanOut(databases, async (db) => {
+      const commonParams = { domain: url, database: db };
+      const [{ body: pagesBody, fullAuditRef }, { body: kwBody }] = await Promise.all([
+        this.sendRawRequest({
+          type: ep.type,
+          ...commonParams,
+          display_limit: effectiveLimit,
+          export_columns: ep.columns,
+          display_filter: buildFilter([{
+            sign: '+', field: 'Tg', op: 'Gt', value: '0',
+          }]),
+          ...ep.defaultParams,
+        }, ep.path),
+        this.sendRawRequest({
+          type: epKw.type,
+          ...commonParams,
+          display_limit: effectiveLimit * 3,
+          export_columns: epKw.columns,
+          ...epKw.defaultParams,
+        }, epKw.path),
+      ]);
+      return {
+        pageRows: parseCsvResponse(pagesBody),
+        kwRows: parseCsvResponse(kwBody),
+        fullAuditRef,
+      };
+    }, 'getTopPages');
 
-    const commonParams = {
-      domain: url,
-      database: DEFAULT_DATABASE,
-    };
-
-    // Two calls required: the SEO data provider does not offer a top-keyword-per-page
-    // field in its page-level report. Sorting organic keywords by traffic and grouping
-    // by URL client-side is the recommended approach.
-    const [{ body: pagesBody, fullAuditRef }, { body: kwBody }] = await Promise.all([
-      this.sendRawRequest({
-        type: ep.type,
-        ...commonParams,
-        display_limit: effectiveLimit,
-        export_columns: ep.columns,
-        display_filter: buildFilter([{
-          sign: '+', field: 'Tg', op: 'Gt', value: '0',
-        }]),
-        ...ep.defaultParams,
-      }, ep.path),
-      this.sendRawRequest({
-        type: epKw.type,
-        ...commonParams,
-        display_limit: effectiveLimit * 3,
-        export_columns: epKw.columns,
-        ...epKw.defaultParams,
-      }, epKw.path),
-    ]);
-
-    const pageRows = parseCsvResponse(pagesBody);
-    const kwRows = parseCsvResponse(kwBody);
-
-    // Build keyword lookup: URL → top keyword (first occurrence = highest traffic)
+    // Merge pages: sum traffic across databases, keep first keyword per URL
+    const pageMap = new Map();
     const keywordMap = new Map();
-    for (const row of kwRows) {
-      if (!keywordMap.has(row.Ur)) {
-        keywordMap.set(row.Ur, row.Ph);
+    let fullAuditRef = '';
+
+    for (const { value } of dbResults) {
+      if (!fullAuditRef) {
+        fullAuditRef = value.fullAuditRef;
+      }
+
+      for (const row of value.kwRows) {
+        if (!keywordMap.has(row.Ur)) {
+          keywordMap.set(row.Ur, row.Ph);
+        }
+      }
+
+      for (const row of value.pageRows) {
+        const traffic = coerceValue(row.Tg, 'int') || 0;
+        const existing = pageMap.get(row.Ur);
+        if (existing) {
+          existing.sum_traffic += traffic;
+        } else {
+          pageMap.set(row.Ur, { url: row.Ur, sum_traffic: traffic });
+        }
       }
     }
 
-    const pages = pageRows.map((row) => ({
-      url: row.Ur,
-      sum_traffic: coerceValue(row.Tg, 'int'),
-      top_keyword: keywordMap.get(row.Ur) ?? null,
-    }));
+    const pages = [...pageMap.values()]
+      .map((page) => ({
+        ...page,
+        top_keyword: keywordMap.get(page.url) ?? null,
+      }))
+      .sort((a, b) => b.sum_traffic - a.sum_traffic)
+      .slice(0, effectiveLimit);
 
     return {
       result: { pages },
@@ -212,49 +296,54 @@ export default class SeoClient {
     };
   }
 
-  async getPaidPages(
-    url,
-    date = todayISO(),
-    limit = 200,
-    // Accepted for contract compatibility but not supported by this provider,
-    // which scopes by report type (domain/subdomain/subfolder/URL) instead.
-    // eslint-disable-next-line no-unused-vars
-    mode = 'prefix',
-  ) {
+  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;
     if (!hasText(url)) {
       throw new Error(`Invalid URL: ${url}`);
     }
 
     const ep = ENDPOINTS.paidPages;
     const effectiveLimit = getLimit(limit, 1000);
+    const databases = getDatabases(region);
 
     // Over-fetch keywords to aggregate into pages. A domain typically has more
     // keywords than pages, so we fetch a multiple of the requested limit.
     // Capped at MAX_PAID_KEYWORDS_FETCH to bound cost.
     const fetchLimit = Math.min(effectiveLimit * 10, MAX_PAID_KEYWORDS_FETCH);
 
-    const { body, fullAuditRef } = await this.sendRawRequest({
+    const dbResults = await this.fanOut(databases, (db) => this.sendRawRequest({
       type: ep.type,
       domain: url,
-      database: DEFAULT_DATABASE,
+      database: db,
       display_date: toApiDate(date),
       display_limit: fetchLimit,
       export_columns: ep.columns,
       ...ep.defaultParams,
-    }, ep.path);
-    const rows = parseCsvResponse(body);
+    }, ep.path), 'getPaidPages');
 
-    // Group keywords by URL
+    // Group keywords by URL across all databases
     const pageMap = new Map();
-    for (const row of rows) {
-      const pageUrl = row.Ur;
-      if (!pageMap.has(pageUrl)) {
-        pageMap.set(pageUrl, { url: pageUrl, keywords: [], totalTraffic: 0 });
+    let fullAuditRef = '';
+
+    for (const { key: db, value } of dbResults) {
+      if (!fullAuditRef) {
+        fullAuditRef = value.fullAuditRef;
+      }
+
+      const rows = parseCsvResponse(value.body);
+      for (const row of rows) {
+        const pageUrl = row.Ur;
+        if (!pageMap.has(pageUrl)) {
+          pageMap.set(pageUrl, { url: pageUrl, keywords: [], totalTraffic: 0 });
+        }
+        const page = pageMap.get(pageUrl);
+        const traffic = coerceValue(row.Tg, 'int') || 0;
+        page.totalTraffic += traffic;
+        page.keywords.push({ ...row, kwTraffic: traffic, db });
       }
-      const page = pageMap.get(pageUrl);
-      const traffic = coerceValue(row.Tg, 'int') || 0;
-      page.totalTraffic += traffic;
-      page.keywords.push({ ...row, kwTraffic: traffic });
     }
 
     // Transform to page-level aggregation, sorted by traffic desc
@@ -270,7 +359,7 @@ export default class SeoClient {
           url: page.url,
           top_keyword: topKw.Ph,
           top_keyword_best_position_title: topKw.Tt || null,
-          top_keyword_country: DEFAULT_DATABASE.toUpperCase(),
+          top_keyword_country: topKw.db.toUpperCase(),
           top_keyword_volume: coerceValue(topKw.Nq, 'int'),
           sum_traffic: page.totalTraffic,
           value: page.keywords.reduce(
@@ -288,37 +377,71 @@ export default class SeoClient {
     };
   }
 
-  async getMetrics(url, date = todayISO()) {
+  async getMetrics(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(), region } = opts;
     if (!hasText(url)) {
       throw new Error(`Invalid URL: ${url}`);
     }
 
     const ep = ENDPOINTS.metrics;
+    const databases = getDatabases(region);
 
-    const { body, fullAuditRef } = await this.sendRawRequest({
+    const dbResults = await this.fanOut(databases, (db) => this.sendRawRequest({
       type: ep.type,
       domain: url,
-      database: DEFAULT_DATABASE,
+      database: db,
       display_date: toApiDate(date),
       export_columns: ep.columns,
       ...ep.defaultParams,
-    }, ep.path);
-    const rows = parseCsvResponse(body);
-    const row = rows[0] || {};
+    }, ep.path), 'getMetrics');
+
+    const metrics = {
+      org_keywords: 0,
+      paid_keywords: 0,
+      org_keywords_1_3: 0,
+      org_traffic: 0,
+      org_cost: 0,
+      paid_traffic: 0,
+      paid_cost: 0,
+      paid_pages: null,
+    };
+    let fullAuditRef = '';
+    let hasData = false;
+
+    for (const { value } of dbResults) {
+      if (!fullAuditRef) {
+        fullAuditRef = value.fullAuditRef;
+      }
+
+      const rows = parseCsvResponse(value.body);
+      const row = rows[0];
+      if (row) {
+        hasData = true;
+        metrics.org_keywords += coerceValue(row.Or, 'int') || 0;
+        metrics.paid_keywords += coerceValue(row.Ad, 'int') || 0;
+        metrics.org_keywords_1_3 += coerceValue(row.X0, 'int') || 0;
+        metrics.org_traffic += coerceValue(row.Ot, 'int') || 0;
+        metrics.org_cost += Math.round((coerceValue(row.Oc, 'float') || 0) * 100);
+        metrics.paid_traffic += coerceValue(row.At, 'int') || 0;
+        metrics.paid_cost += Math.round((coerceValue(row.Ac, 'float') || 0) * 100);
+      }
+    }
+
+    if (!hasData) {
+      metrics.org_keywords = null;
+      metrics.paid_keywords = null;
+      metrics.org_keywords_1_3 = null;
+      metrics.org_traffic = null;
+      metrics.org_cost = 0;
+      metrics.paid_traffic = null;
+      metrics.paid_cost = 0;
+    }
 
     return {
-      result: {
-        metrics: {
-          org_keywords: coerceValue(row.Or, 'int'),
-          paid_keywords: coerceValue(row.Ad, 'int'),
-          org_keywords_1_3: coerceValue(row.X0, 'int'),
-          org_traffic: coerceValue(row.Ot, 'int'),
-          org_cost: Math.round((coerceValue(row.Oc, 'float') || 0) * 100),
-          paid_traffic: coerceValue(row.At, 'int'),
-          paid_cost: Math.round((coerceValue(row.Ac, 'float') || 0) * 100),
-          paid_pages: null,
-        },
-      },
+      result: { metrics },
       fullAuditRef,
     };
   }
@@ -329,41 +452,77 @@ export default class SeoClient {
    * The full history is fetched and filtered client-side because the provider's
    * history endpoint does not support date range parameters.
    * @param {string} url - The target domain
-   * @param {string} startDate - Start date in YYYY-MM-DD format
-   * @param {string} endDate - End date in YYYY-MM-DD format
+   * @param {object} options
+   * @param {string} options.startDate - Start date in YYYY-MM-DD format
+   * @param {string} options.endDate - End date in YYYY-MM-DD format
+   * @param {string} [options.region] - ISO 3166-1 alpha-2 region code
    * @returns {Promise<{result: {metrics: Array}, fullAuditRef: string}>}
    */
-  async getOrganicTraffic(url, startDate, endDate) {
+  async getOrganicTraffic(url, opts = {}) {
+    if (typeof opts !== 'object' || opts === null) {
+      throw new Error('Second argument must be an options object, not a positional value');
+    }
+    const { startDate, endDate, region } = opts;
     if (!hasText(url)) {
       throw new Error(`Invalid URL: ${url}`);
     }
+    if (!hasText(startDate) || !hasText(endDate)) {
+      throw new Error('startDate and endDate are required');
+    }
 
     const ep = ENDPOINTS.organicTraffic;
+    const databases = getDatabases(region);
 
-    const { body, fullAuditRef } = await this.sendRawRequest({
+    const dbResults = await this.fanOut(databases, (db) => this.sendRawRequest({
       type: ep.type,
       domain: url,
-      database: DEFAULT_DATABASE,
+      database: db,
       export_columns: ep.columns,
       ...ep.defaultParams,
-    }, ep.path);
-    const rows = parseCsvResponse(body);
+    }, ep.path), 'getOrganicTraffic');
 
-    // Convert API dates (YYYYMMDD) to ISO (YYYY-MM-DD) and filter to requested range
-    const filtered = rows
-      .map((row) => ({ ...row, isoDate: fromApiDate(row.Dt) }))
-      .filter((row) => row.isoDate && row.isoDate >= startDate && row.isoDate <= endDate);
+    // Group by date across all databases, sum numeric fields
+    const dateMap = new Map();
+    let fullAuditRef = '';
+
+    for (const { value } of dbResults) {
+      if (!fullAuditRef) {
+        fullAuditRef = value.fullAuditRef;
+      }
+
+      const rows = parseCsvResponse(value.body);
+      for (const row of rows) {
+        const isoDate = fromApiDate(row.Dt);
+        if (!isoDate || isoDate < startDate || isoDate > endDate) {
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        const existing = dateMap.get(isoDate);
+        if (existing) {
+          existing.org_traffic += coerceValue(row.Ot, 'int') || 0;
+          existing.paid_traffic += coerceValue(row.At, 'int') || 0;
+          existing.org_cost += Math.round((coerceValue(row.Oc, 'float') || 0) * 100);
+          /* c8 ignore next */
+          existing.paid_cost += Math.round((coerceValue(row.Ac, 'float') || 0) * 100);
+        } else {
+          /* c8 ignore next 6 - || 0 null-coercion branches */
+          dateMap.set(isoDate, {
+            date: `${isoDate}T00:00:00Z`,
+            org_traffic: coerceValue(row.Ot, 'int') || 0,
+            paid_traffic: coerceValue(row.At, 'int') || 0,
+            org_cost: Math.round((coerceValue(row.Oc, 'float') || 0) * 100),
+            paid_cost: Math.round((coerceValue(row.Ac, 'float') || 0) * 100),
+          });
+        }
+      }
+    }
+
+    const metrics = [...dateMap.values()]
+      .sort((a, b) => a.date.localeCompare(b.date));
 
     return {
-      result: {
-        metrics: filtered.map((row) => ({
-          date: `${row.isoDate}T00:00:00Z`,
-          org_traffic: coerceValue(row.Ot, 'int'),
-          paid_traffic: coerceValue(row.At, 'int'),
-          org_cost: Math.round((coerceValue(row.Oc, 'float') || 0) * 100),
-          paid_cost: Math.round((coerceValue(row.Ac, 'float') || 0) * 100),
-        })),
-      },
+      result: { metrics },
       fullAuditRef,
     };
   }
@@ -516,32 +675,21 @@ export default class SeoClient {
     }
 
     // Step 2: For each broken page, fetch the top backlink by authority score.
-    // Parallelized in batches to balance throughput and rate limits.
-    const BATCH_SIZE = 10;
     const brokenUrls = brokenPages.map((p) => p.source_url);
-    const allBacklinks = [];
+    const linkResults = await this.fanOut(brokenUrls, (brokenUrl) => this.sendRawRequest({
+      type: epLinks.type,
+      target: brokenUrl,
+      target_type: 'url',
+      export_columns: epLinks.columns,
+      display_limit: 1,
+      ...epLinks.defaultParams,
+    }, epLinks.path), 'getBrokenBacklinks');
 
-    for (let i = 0; i < brokenUrls.length; i += BATCH_SIZE) {
-      const batch = brokenUrls.slice(i, i + BATCH_SIZE);
-      // eslint-disable-next-line no-await-in-loop
-      const results = await Promise.allSettled(
-        batch.map((brokenUrl) => this.sendRawRequest({
-          type: epLinks.type,
-          target: brokenUrl,
-          target_type: 'url',
-          export_columns: epLinks.columns,
-          display_limit: 1,
-          ...epLinks.defaultParams,
-        }, epLinks.path)),
-      );
-
-      for (const result of results) {
-        if (result.status === 'fulfilled') {
-          const links = parseCsvResponse(result.value.body);
-          if (links.length > 0) {
-            allBacklinks.push(links[0]);
-          }
-        }
+    const allBacklinks = [];
+    for (const { value } of linkResults) {
+      const links = parseCsvResponse(value.body);
+      if (links.length > 0) {
+        allBacklinks.push(links[0]);
       }
     }
 
@@ -566,7 +714,7 @@ export default class SeoClient {
   }
 
   // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getMetricsByCountry(url, date = todayISO()) {
+  async getMetricsByCountry(url, date = lastMonthISO()) {
     return STUB_RESPONSE;
   }
 }

package/src/index.d.ts

@@ -41,14 +41,19 @@ export default class SeoClient {
   getBrokenBacklinks(url: string, limit?: number):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  getTopPages(url: string, limit?: number):
-      Promise<{ result: object, fullAuditRef: string }>;
+  getTopPages(url: string, options?: {
+    limit?: number,
+    region?: string,
+  }): Promise<{ result: object, fullAuditRef: string }>;
 
   getBacklinks(url: string, limit?: number):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  getOrganicTraffic(url: string, startDate: string, endDate: string):
-      Promise<{ result: object, fullAuditRef: string }>;
+  getOrganicTraffic(url: string, options?: {
+    startDate?: string,
+    endDate?: string,
+    region?: string,
+  }): Promise<{ result: object, fullAuditRef: string }>;
 
   getOrganicKeywords(
     url: string,
@@ -61,12 +66,16 @@ export default class SeoClient {
     }):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  getPaidPages(url: string, date?: string, limit?: number,
-    mode?: 'exact' | 'prefix' | 'domain' | 'subdomains'):
-      Promise<{ result: object, fullAuditRef: string }>;
+  getPaidPages(url: string, options?: {
+    date?: string,
+    limit?: number,
+    region?: string,
+  }): Promise<{ result: object, fullAuditRef: string }>;
 
-  getMetrics(url: string, date?: string):
-      Promise<{ result: object, fullAuditRef: string }>;
+  getMetrics(url: string, options?: {
+    date?: string,
+    region?: string,
+  }): Promise<{ result: object, fullAuditRef: string }>;
 
   getMetricsByCountry(url: string, date?: string):
       Promise<{ result: object, fullAuditRef: string }>;
@@ -78,6 +87,9 @@ export function getLimit(limit: number, upperLimit: number): number;
 export function toApiDate(date: string): string;
 export function fromApiDate(apiDate: string): string | null;
 export function todayISO(): string;
+export function lastMonthISO(): string;
+export function getDatabases(region?: string): string[];
+export const BIG_MARKETS: readonly string[];
 export function buildFilter(filters: Array<{sign: string, field: string, op: string, value: string}>): string;
 export function extractBrand(domain: string): string;
 export function buildQueryParams(defaults: object, overrides: object): object;

package/src/index.js

@@ -13,10 +13,11 @@
 import SeoClient from './client.js';
 
 export default SeoClient;
-export { fetch } from './client.js';
+export { fetch, BIG_MARKETS, getDatabases } from './client.js';
 export { ENDPOINTS } from './endpoints.js';
 export {
-  buildQueryParams, parseCsvResponse, coerceValue, getLimit, toApiDate, fromApiDate, todayISO,
+  buildQueryParams, parseCsvResponse, coerceValue, getLimit,
+  toApiDate, fromApiDate, todayISO, lastMonthISO,
   buildFilter, extractBrand, INTENT_CODES,
 } from './utils.js';
 

package/src/utils.js

@@ -168,6 +168,19 @@ export function todayISO() {
   return new Date().toISOString().split('T')[0];
 }
 
+/**
+ * Returns the 1st of the previous month as YYYY-MM-DD.
+ * The SEO provider publishes monthly snapshots with a delay, so the most
+ * recent available data is typically from the previous month.
+ * @returns {string}
+ */
+export function lastMonthISO() {
+  const now = new Date();
+  now.setUTCDate(1);
+  now.setUTCMonth(now.getUTCMonth() - 1);
+  return now.toISOString().split('T')[0];
+}
+
 /**
  * Converts a YYYYMMDD date string from the API to YYYY-MM-DD.
  * Returns null for invalid/missing inputs.