@adobe/mysticat-shared-seo-client 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/mysticat-shared-seo-client-v1.1.1](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.1.0...@adobe/mysticat-shared-seo-client-v1.1.1) (2026-04-06)
+
+### Bug Fixes
+
+* **deps:** update external major (major) ([#1087](https://github.com/adobe/spacecat-shared/issues/1087)) ([72e1ab6](https://github.com/adobe/spacecat-shared/commit/72e1ab65892120f94ba409d5ab10370947329188))
+
+## [@adobe/mysticat-shared-seo-client-v1.1.0](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.0.0...@adobe/mysticat-shared-seo-client-v1.1.0) (2026-04-01)
+
+### Features
+
+* **seo-client:** implement SEO data provider client ([#1493](https://github.com/adobe/spacecat-shared/issues/1493)) ([0b6e043](https://github.com/adobe/spacecat-shared/commit/0b6e043ac166bbdf9df6b70172e7fb7e87928170))
+
 ## @adobe/mysticat-shared-seo-client-v1.0.0 (2026-04-01)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/mysticat-shared-seo-client",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Shared modules of the SpaceCat Services - SEO Client",
   "type": "module",
   "engines": {
@@ -36,7 +36,8 @@
   "dependencies": {
     "@adobe/fetch": "4.2.3",
     "@adobe/helix-universal": "5.4.0",
-    "@adobe/spacecat-shared-utils": "1.81.1"
+    "@adobe/spacecat-shared-utils": "1.81.1",
+    "urijs": "1.19.11"
   },
   "devDependencies": {
     "chai": "6.2.2",
@@ -44,6 +45,6 @@
     "nock": "14.0.11",
     "sinon": "21.0.3",
     "sinon-chai": "4.0.1",
-    "typescript": "5.9.3"
+    "typescript": "6.0.2"
   }
 }

package/src/client.js

@@ -10,17 +10,35 @@
  * governing permissions and limitations under the License.
  */
 
-import { isValidUrl } from '@adobe/spacecat-shared-utils';
+import { hasText, isValidUrl, isArray } from '@adobe/spacecat-shared-utils';
 import { context as h2, h1 } from '@adobe/fetch';
 
+import { ENDPOINTS } from './endpoints.js';
+import {
+  parseCsvResponse, coerceValue, getLimit, toApiDate, fromApiDate, todayISO, buildFilter,
+  extractBrand, INTENT_CODES,
+} from './utils.js';
+
 /* c8 ignore next 3 */
 export const { fetch } = process.env.HELIX_FETCH_FORCE_HTTP1
   ? h1()
   : h2();
 
+const DEFAULT_DATABASE = 'us';
+const MAX_ERROR_BODY_LENGTH = 500;
+const MAX_PAID_KEYWORDS_FETCH = 10000;
+const RATE_LIMIT_BASE_DELAY_MS = 1000;
+const MAX_RETRIES = 4;
+
 const STUB_RESPONSE = { result: {}, fullAuditRef: '' };
 
 export default class SeoClient {
+  static delay(ms) {
+    return new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+
   static createFrom(context) {
     const { SEO_API_BASE_URL: apiBaseUrl, SEO_API_KEY: apiKey } = context.env;
     return new SeoClient({ apiBaseUrl, apiKey }, fetch, context.log);
@@ -33,6 +51,10 @@ export default class SeoClient {
       throw new Error(`Invalid SEO API Base URL: ${apiBaseUrl}`);
     }
 
+    if (!hasText(apiKey)) {
+      throw new Error('Missing SEO API key');
+    }
+
     if (typeof fetchAPI !== 'function') {
       throw Error('"fetchAPI" must be a function');
     }
@@ -43,43 +65,503 @@ export default class SeoClient {
     this.log = log;
   }
 
-  // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async sendRequest(endpoint, queryParams = {}) {
-    return STUB_RESPONSE;
+  /**
+   * Internal method that executes the HTTP request and returns the raw CSV body.
+   * Used by all endpoint methods for CSV parsing.
+   * @param {object} queryParams - Query parameters including type, domain, etc.
+   * @param {string} [apiPath=''] - Optional API path segment (e.g., 'analytics/v1/')
+   * @returns {Promise<{body: string, fullAuditRef: string}>}
+   */
+  async sendRawRequest(queryParams = {}, apiPath = '') {
+    const params = { ...queryParams, key: this.apiKey };
+
+    const queryString = Object.entries(params)
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+      .join('&');
+
+    const baseUrl = this.apiBaseUrl.replace(/\/$/, '');
+    const pathSegment = apiPath ? `/${apiPath.replace(/^\//, '')}` : '';
+    const requestUrl = `${baseUrl}${pathSegment}?${queryString}`;
+
+    // Mask the API key in the audit ref URL
+    const fullAuditRef = requestUrl.replace(
+      `key=${encodeURIComponent(this.apiKey)}`,
+      'key=REDACTED',
+    );
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+      this.log.debug(`SEO API request: ${fullAuditRef}${attempt > 0 ? ` (retry ${attempt})` : ''}`);
+      // eslint-disable-next-line no-await-in-loop
+      const response = await this.fetchAPI(requestUrl, { method: 'GET' });
+      // eslint-disable-next-line no-await-in-loop
+      const body = await response.text();
+
+      // SEO API returns HTTP 200 with "ERROR XX :: message" body on errors
+      if (body.startsWith('ERROR')) {
+        const isRateLimit = body.includes('LIMIT EXCEEDED');
+        if (isRateLimit && attempt < MAX_RETRIES) {
+          // Exponential backoff: 1s, 2s, 4s, 8s + random jitter 0-500ms
+          const retryDelay = (RATE_LIMIT_BASE_DELAY_MS * (2 ** attempt))
+            + Math.floor(Math.random() * 500);
+          this.log.warn(`SEO API rate limited, retrying in ${retryDelay}ms (attempt ${attempt + 1}/${MAX_RETRIES})`);
+          // eslint-disable-next-line no-await-in-loop
+          await SeoClient.delay(retryDelay);
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+        const prefix = isRateLimit && attempt >= MAX_RETRIES
+          ? `SEO API request failed after ${MAX_RETRIES} retries: `
+          : 'SEO API request failed: ';
+        const errorMessage = `${prefix}${body.slice(0, MAX_ERROR_BODY_LENGTH)}`;
+        this.log.error(errorMessage);
+        throw new Error(errorMessage);
+      }
+
+      if (!response.ok) {
+        const errorMessage = `SEO API request failed with status: ${response.status} - ${body.slice(0, MAX_ERROR_BODY_LENGTH)}`;
+        this.log.error(errorMessage);
+        throw new Error(errorMessage);
+      }
+
+      const rowCount = body.split('\n').length - 1;
+      this.log.info(`SEO API call: type=${queryParams.type || 'unknown'} domain=${queryParams.domain || queryParams.target || '-'} rows=${rowCount} path=${apiPath || '/'}`);
+
+      return { body, fullAuditRef };
+    }
+    /* c8 ignore next */
+    throw new Error('SEO API request failed: unexpected retry loop exit');
   }
 
-  // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getBrokenBacklinks(url, limit = 50) {
-    return STUB_RESPONSE;
+  /**
+   * Public method matching the old AhrefsAPIClient.sendRequest(endpoint, queryParams) signature.
+   * Sends a request and returns a parsed result object.
+   * @param {string} endpoint - API endpoint path (e.g., '/site-explorer/top-pages')
+   * @param {object} [queryParams={}] - Query parameters
+   * @returns {Promise<{result: object, fullAuditRef: string}>}
+   */
+  async sendRequest(endpoint, queryParams = {}) {
+    const { body, fullAuditRef } = await this.sendRawRequest(queryParams, endpoint);
+    const rows = parseCsvResponse(body);
+    const result = rows.length === 1 ? rows[0] : rows;
+
+    return { result, fullAuditRef };
   }
 
-  // eslint-disable-next-line no-unused-vars, class-methods-use-this
   async getTopPages(url, limit = 200) {
-    return STUB_RESPONSE;
+    if (!hasText(url)) {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+
+    const ep = ENDPOINTS.topPages;
+    const epKw = ENDPOINTS.topPagesKeywords;
+    const effectiveLimit = getLimit(limit, 2000);
+
+    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)
+    const keywordMap = new Map();
+    for (const row of kwRows) {
+      if (!keywordMap.has(row.Ur)) {
+        keywordMap.set(row.Ur, row.Ph);
+      }
+    }
+
+    const pages = pageRows.map((row) => ({
+      url: row.Ur,
+      sum_traffic: coerceValue(row.Tg, 'int'),
+      top_keyword: keywordMap.get(row.Ur) ?? null,
+    }));
+
+    return {
+      result: { pages },
+      fullAuditRef,
+    };
   }
 
-  // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getBacklinks(url, limit = 200) {
-    return STUB_RESPONSE;
+  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',
+  ) {
+    if (!hasText(url)) {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+
+    const ep = ENDPOINTS.paidPages;
+    const effectiveLimit = getLimit(limit, 1000);
+
+    // 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({
+      type: ep.type,
+      domain: url,
+      database: DEFAULT_DATABASE,
+      display_date: toApiDate(date),
+      display_limit: fetchLimit,
+      export_columns: ep.columns,
+      ...ep.defaultParams,
+    }, ep.path);
+    const rows = parseCsvResponse(body);
+
+    // Group keywords by URL
+    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 });
+      }
+      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
+    const pages = [...pageMap.values()]
+      .sort((a, b) => b.totalTraffic - a.totalTraffic)
+      .slice(0, effectiveLimit)
+      .map((page) => {
+        const topKw = page.keywords.reduce(
+          (best, kw) => (kw.kwTraffic > best.kwTraffic ? kw : best),
+          page.keywords[0],
+        );
+        return {
+          url: page.url,
+          top_keyword: topKw.Ph,
+          top_keyword_best_position_title: topKw.Tt || null,
+          top_keyword_country: DEFAULT_DATABASE.toUpperCase(),
+          top_keyword_volume: coerceValue(topKw.Nq, 'int'),
+          sum_traffic: page.totalTraffic,
+          value: page.keywords.reduce(
+            (sum, kw) => sum + Math.round(
+              (kw.kwTraffic || 0) * (coerceValue(kw.Cp, 'float') || 0) * 100,
+            ),
+            0,
+          ),
+        };
+      });
+
+    return {
+      result: { pages },
+      fullAuditRef,
+    };
   }
 
-  // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getOrganicKeywords(url, options = {}) {
-    return STUB_RESPONSE;
+  async getMetrics(url, date = todayISO()) {
+    if (!hasText(url)) {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+
+    const ep = ENDPOINTS.metrics;
+
+    const { body, fullAuditRef } = await this.sendRawRequest({
+      type: ep.type,
+      domain: url,
+      database: DEFAULT_DATABASE,
+      display_date: toApiDate(date),
+      export_columns: ep.columns,
+      ...ep.defaultParams,
+    }, ep.path);
+    const rows = parseCsvResponse(body);
+    const row = rows[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,
+        },
+      },
+      fullAuditRef,
+    };
   }
 
-  // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getPaidPages(url, date = new Date().toISOString().split('T')[0], limit = 200, mode = 'prefix') {
-    return STUB_RESPONSE;
+  /**
+   * Retrieves historical organic traffic metrics for a URL within a date range.
+   * Note: The SEO data provider returns monthly data points only (no weekly option).
+   * 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
+   * @returns {Promise<{result: {metrics: Array}, fullAuditRef: string}>}
+   */
+  async getOrganicTraffic(url, startDate, endDate) {
+    if (!hasText(url)) {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+
+    const ep = ENDPOINTS.organicTraffic;
+
+    const { body, fullAuditRef } = await this.sendRawRequest({
+      type: ep.type,
+      domain: url,
+      database: DEFAULT_DATABASE,
+      export_columns: ep.columns,
+      ...ep.defaultParams,
+    }, ep.path);
+    const rows = parseCsvResponse(body);
+
+    // 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);
+
+    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),
+        })),
+      },
+      fullAuditRef,
+    };
+  }
+
+  async getOrganicKeywords(url, {
+    country = DEFAULT_DATABASE,
+    keywordFilter = [],
+    limit = 10,
+    // Accepted for contract compatibility but not supported by this provider,
+    // which scopes by report type (domain/subdomain/subfolder/URL) instead.
+    mode = 'prefix',
+    excludeBranded = false,
+  } = {}) {
+    if (!hasText(url)) {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+    if (!hasText(country)) {
+      throw new Error(`Invalid country: ${country}`);
+    }
+    if (!isArray(keywordFilter)) {
+      throw new Error(`Invalid keyword filter: ${keywordFilter}`);
+    }
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new Error(`Invalid limit: ${limit}`);
+    }
+    if (!['prefix', 'exact'].includes(mode)) {
+      throw new Error(`Invalid mode: ${mode}`);
+    }
+
+    const ep = ENDPOINTS.organicKeywords;
+
+    // Over-fetch when excluding branded (client-side filter)
+    const fetchLimit = excludeBranded
+      ? getLimit(limit * 3, 300)
+      : getLimit(limit, 100);
+
+    const params = {
+      type: ep.type,
+      domain: url,
+      database: country,
+      display_limit: fetchLimit,
+      export_columns: ep.columns,
+      ...ep.defaultParams,
+    };
+
+    // Build keyword display_filter if keyword filters provided
+    if (keywordFilter.length > 0) {
+      params.display_filter = buildFilter(
+        keywordFilter.map((kw) => ({
+          sign: '+', field: 'Ph', op: 'Co', value: kw,
+        })),
+      );
+    }
+
+    this.log.debug(`Getting organic keywords for ${url} with country ${country}, mode ${mode}, limit ${limit}, excludeBranded ${excludeBranded}`);
+
+    const { body, fullAuditRef } = await this.sendRawRequest(params, ep.path);
+    const rows = parseCsvResponse(body);
+
+    // Client-side brand detection since the SEO data provider
+    // does not expose a branded keyword flag
+    const brand = extractBrand(url);
+
+    let keywords = rows.map((row) => {
+      const intents = row.In ? row.In.split(',').map(Number) : [];
+      return {
+        keyword: row.Ph,
+        keyword_country: country,
+        language: null,
+        sum_traffic: coerceValue(row.Tg, 'int'),
+        volume: coerceValue(row.Nq, 'int'),
+        best_position: coerceValue(row.Po, 'int'),
+        best_position_url: row.Ur,
+        cpc: Math.round((coerceValue(row.Cp, 'float') || 0) * 100),
+        last_update: row.Ts
+          ? new Date(parseInt(row.Ts, 10) * 1000).toISOString()
+          : null,
+        is_branded: brand.length > 1 && (row.Ph || '').toLowerCase().includes(brand),
+        is_navigational: intents.includes(INTENT_CODES.NAVIGATIONAL),
+        is_informational: intents.includes(INTENT_CODES.INFORMATIONAL),
+        is_commercial: intents.includes(INTENT_CODES.COMMERCIAL),
+        is_transactional: intents.includes(INTENT_CODES.TRANSACTIONAL),
+        serp_features: row.Fp || null,
+      };
+    });
+
+    if (excludeBranded) {
+      keywords = keywords.filter((kw) => !kw.is_branded);
+    }
+    keywords = keywords.slice(0, limit);
+
+    return {
+      result: { keywords },
+      fullAuditRef,
+    };
   }
 
+  /**
+   * Retrieves broken backlinks for a domain — links pointing to pages that return 404.
+   *
+   * The SEO data provider does not offer a single broken-backlinks endpoint (unlike the
+   * previous provider). This method uses a two-step approach:
+   *
+   * Step 1: Call `backlinks_pages` with a server-side 404 filter to discover which of
+   * the domain's pages are broken, sorted by referring domain count (highest first).
+   * This is a single API call.
+   *
+   * Step 2: For each broken page (up to `limit`), fetch the single highest-quality
+   * backlink (by authority score) using `backlinks` with `display_limit=1`. These calls
+   * are parallelized in batches of 10 to respect rate limits while minimizing latency.
+   *
+   * This approach maximizes broken page diversity — each result row represents a different
+   * broken page on the domain, paired with its best referring link. This matches the
+   * practical value of the old provider's single-call endpoint, where results typically
+   * surfaced many unique broken target URLs.
+   *
+   * Note on `traffic_domain` field: The previous provider returned estimated monthly
+   * organic traffic (0 to millions). This implementation maps it to the referring page's
+   * authority score (0-100). Relative ranking is preserved but absolute values differ.
+   *
+   * @param {string} url - The target domain
+   * @param {number} [limit=50] - Maximum results (default: 50, max: 100)
+   * @returns {Promise<{result: {backlinks: Array}, fullAuditRef: string}>}
+   */
+  async getBrokenBacklinks(url, limit = 50) {
+    if (!hasText(url)) {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+
+    const epPages = ENDPOINTS.brokenBacklinksPages;
+    const epLinks = ENDPOINTS.brokenBacklinks;
+    const effectiveLimit = getLimit(limit, 100);
+
+    // Step 1: Find broken (404) target pages, sorted by referring domains
+    const { body: pagesBody, fullAuditRef } = await this.sendRawRequest({
+      type: epPages.type,
+      target: url,
+      target_type: 'root_domain',
+      export_columns: epPages.columns,
+      display_limit: effectiveLimit,
+      display_filter: buildFilter([{
+        sign: '+', field: 'responsecode', op: 'Eq', value: '404',
+      }]),
+      ...epPages.defaultParams,
+    }, epPages.path);
+    const brokenPages = parseCsvResponse(pagesBody);
+
+    if (brokenPages.length === 0) {
+      return { result: { backlinks: [] }, fullAuditRef };
+    }
+
+    // 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 = [];
+
+    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 backlinks = allBacklinks.map((row) => ({
+      title: row.source_title || null,
+      url_from: row.source_url,
+      url_to: row.target_url,
+      traffic_domain: coerceValue(row.page_ascore, 'int'),
+    }));
+
+    return {
+      result: { backlinks },
+      fullAuditRef,
+    };
+  }
+
+  // --- Out of scope methods (stubs) ---
+
   // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getMetrics(url, date = new Date().toISOString().split('T')[0]) {
+  async getBacklinks(url, limit = 200) {
     return STUB_RESPONSE;
   }
 
   // eslint-disable-next-line no-unused-vars, class-methods-use-this
-  async getMetricsByCountry(url, date = new Date().toISOString().split('T')[0]) {
+  async getMetricsByCountry(url, date = todayISO()) {
     return STUB_RESPONSE;
   }
 }

package/src/endpoints.js

@@ -10,17 +10,73 @@
  * governing permissions and limitations under the License.
  */
 
+/**
+ * API path segments. Domain/overview reports use the root path,
+ * while backlinks reports require the /analytics/v1/ path.
+ */
+export const API_PATHS = {
+  root: '',
+  analytics: 'analytics/v1/',
+};
+
 /**
  * Endpoint definitions for the SEO API.
- * Each entry maps a method name to its API path and default query parameters.
- * Paths and params are stubs - to be populated when implementing API calls.
+ * Each entry maps a method name to its report type, columns, path, and default parameters.
  */
 export const ENDPOINTS = {
-  brokenBacklinks: { path: '', defaultParams: {} },
-  topPages: { path: '', defaultParams: {} },
-  backlinks: { path: '', defaultParams: {} },
-  organicKeywords: { path: '', defaultParams: {} },
-  paidPages: { path: '', defaultParams: {} },
-  metrics: { path: '', defaultParams: {} },
-  metricsByCountry: { path: '', defaultParams: {} },
+  topPages: {
+    type: 'domain_organic_unique',
+    path: API_PATHS.root,
+    columns: 'Ur,Tg',
+    defaultParams: { display_sort: 'tg_desc', export_escape: 1 },
+  },
+  topPagesKeywords: {
+    type: 'domain_organic',
+    path: API_PATHS.root,
+    columns: 'Ur,Ph,Tg',
+    defaultParams: { display_sort: 'tg_desc', export_escape: 1 },
+  },
+  paidPages: {
+    type: 'domain_adwords',
+    path: API_PATHS.root,
+    columns: 'Ph,Ur,Tg,Nq,Cp,Po,Tt',
+    defaultParams: { display_sort: 'tg_desc', export_escape: 1 },
+  },
+  metrics: {
+    type: 'domain_rank',
+    path: API_PATHS.root,
+    columns: 'Or,Ad,Ot,Oc,At,Ac,X0',
+    defaultParams: { export_escape: 1 },
+  },
+  organicTraffic: {
+    type: 'domain_rank_history',
+    path: API_PATHS.root,
+    columns: 'Dt,Ot,Oc,At,Ac',
+    defaultParams: { display_sort: 'dt_asc', export_escape: 1 },
+  },
+  organicKeywords: {
+    type: 'domain_organic',
+    path: API_PATHS.root,
+    columns: 'Ph,Po,Pp,Nq,Cp,Ur,Tg,Tr,Kd,Fp,Fk,Ts,In',
+    defaultParams: { display_sort: 'tg_desc', export_escape: 1 },
+  },
+  brokenBacklinksPages: {
+    type: 'backlinks_pages',
+    path: API_PATHS.analytics,
+    columns: 'source_url,response_code,backlinks_num,domains_num',
+    defaultParams: { display_sort: 'domainsnum_desc', export_escape: 1 },
+  },
+  brokenBacklinks: {
+    type: 'backlinks',
+    path: API_PATHS.analytics,
+    columns: 'source_title,source_url,target_url,page_ascore,external_num',
+    defaultParams: { display_sort: 'page_ascore_desc', export_escape: 1 },
+  },
+  // Out of scope — stubs
+  backlinks: {
+    type: '', path: '', columns: '', defaultParams: {},
+  },
+  metricsByCountry: {
+    type: '', path: '', columns: '', defaultParams: {},
+  },
 };

package/src/index.d.ts

@@ -13,67 +13,43 @@
 import { UniversalContext } from '@adobe/helix-universal';
 
 export interface SeoAPIOptions {
-    select: string;
-    where: string;
-    order_by: string;
-    date: string;
-    target: string;
-    limit: number;
-    mode: string;
-    output: string;
+    type: string;
+    domain?: string;
+    target?: string;
+    target_type?: string;
+    database?: string;
+    display_date?: string;
+    display_limit?: number;
+    display_sort?: string;
+    display_filter?: string;
+    export_columns?: string;
+    export_escape?: number;
+    key?: string;
 }
 
 export default class SeoClient {
-  /**
-   * Static factory method to create an instance of SeoClient.
-   * @param {UniversalContext} context - An object containing the AWS Lambda context information
-   * @returns An instance of SeoClient.
-   */
   static createFrom(context: UniversalContext): SeoClient;
 
-  /**
-   * Constructor for creating an instance of SeoClient.
-   * @param config
-   * @param fetchAPI
-   * @param log
-   */
-  constructor(config: object, fetchAPI, log?: Console);
-
-  /**
-   * Asynchronous method to send a request to the SEO API.
-   * @param endpoint
-   * @param queryParams
-   */
+  constructor(config: object, fetchAPI: Function, log?: Console);
+
   sendRequest(endpoint: string, queryParams?: SeoAPIOptions):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get broken backlinks.
-   * @param url
-   * @param limit
-   */
+  sendRawRequest(queryParams?: SeoAPIOptions, apiPath?: string):
+      Promise<{ body: string, fullAuditRef: string }>;
+
   getBrokenBacklinks(url: string, limit?: number):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get top pages.
-   * @param url
-   * @param limit
-   */
   getTopPages(url: string, limit?: number):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get backlinks.
-   * @param url
-   * @param limit
-   */
   getBacklinks(url: string, limit?: number):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get organic keywords.
-   */
+  getOrganicTraffic(url: string, startDate: string, endDate: string):
+      Promise<{ result: object, fullAuditRef: string }>;
+
   getOrganicKeywords(
     url: string,
     options?: {
@@ -85,30 +61,36 @@ export default class SeoClient {
     }):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get paid pages for a URL.
-   * @param url - The target URL
-   * @param date - Optional date in YYYY-MM-DD format, defaults to today
-   * @param limit - Maximum number of results to return (max: 1000)
-   * @param mode - Search mode
-   */
   getPaidPages(url: string, date?: string, limit?: number,
     mode?: 'exact' | 'prefix' | 'domain' | 'subdomains'):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get metrics for a URL.
-   * @param url - The target URL
-   * @param date - Optional date in YYYY-MM-DD format, defaults to today
-   */
   getMetrics(url: string, date?: string):
       Promise<{ result: object, fullAuditRef: string }>;
 
-  /**
-   * Asynchronous method to get metrics by country for a URL.
-   * @param url - The target URL
-   * @param date - Optional date in YYYY-MM-DD format, defaults to today
-   */
   getMetricsByCountry(url: string, date?: string):
       Promise<{ result: object, fullAuditRef: string }>;
 }
+
+export function parseCsvResponse(text: string): object[];
+export function coerceValue(value: string, type: 'int' | 'float' | 'string' | 'bool'): any;
+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 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;
+/** @deprecated Use parseCsvResponse instead. */
+export function parseResponse(response: any): any;
+
+export const INTENT_CODES: {
+  COMMERCIAL: 0,
+  INFORMATIONAL: 1,
+  NAVIGATIONAL: 2,
+  TRANSACTIONAL: 3,
+};
+export const ORGANIC_KEYWORDS_FIELDS: readonly string[];
+export const METRICS_BY_COUNTRY_FILTER_FIELDS: readonly string[];
+export const ENDPOINTS: Record<string, { type: string, path: string, columns: string, defaultParams: object }>;
+export function fetch(...args: any[]): Promise<Response>;

package/src/index.js

@@ -15,8 +15,41 @@ import SeoClient from './client.js';
 export default SeoClient;
 export { fetch } from './client.js';
 export { ENDPOINTS } from './endpoints.js';
-export { buildQueryParams, parseResponse } from './utils.js';
+export {
+  buildQueryParams, parseCsvResponse, coerceValue, getLimit, toApiDate, fromApiDate, todayISO,
+  buildFilter, extractBrand, INTENT_CODES,
+} from './utils.js';
 
-export const ORGANIC_KEYWORDS_FIELDS = /** @type {const} */ ([]);
+/** @deprecated Use parseCsvResponse instead. Kept for backward compatibility. */
+export function parseResponse(response) {
+  return response;
+}
 
-export const METRICS_BY_COUNTRY_FILTER_FIELDS = /** @type {const} */ ([]);
+export const ORGANIC_KEYWORDS_FIELDS = /** @type {const} */ ([
+  'keyword',
+  'keyword_country',
+  'language',
+  'sum_traffic',
+  'volume',
+  'best_position',
+  'best_position_url',
+  'cpc',
+  'last_update',
+  'is_branded',
+  'is_navigational',
+  'is_informational',
+  'is_commercial',
+  'is_transactional',
+  'serp_features',
+]);
+
+export const METRICS_BY_COUNTRY_FILTER_FIELDS = /** @type {const} */ ([
+  'org_keywords',
+  'paid_keywords',
+  'org_keywords_1_3',
+  'org_traffic',
+  'org_cost',
+  'paid_traffic',
+  'paid_cost',
+  'paid_pages',
+]);

package/src/utils.js

@@ -10,6 +10,207 @@
  * governing permissions and limitations under the License.
  */
 
+import URI from 'urijs';
+
+/**
+ * Maps SEO API response header names back to their column codes.
+ * The API returns full names in headers even when requested by code.
+ */
+const HEADER_TO_CODE = {
+  Domain: 'Dn',
+  Rank: 'Rk',
+  'Organic Keywords': 'Or',
+  'Organic Traffic': 'Ot',
+  'Organic Cost': 'Oc',
+  'Adwords Keywords': 'Ad',
+  'Adwords Traffic': 'At',
+  'Adwords Cost': 'Ac',
+  Date: 'Dt',
+  Keyword: 'Ph',
+  Position: 'Po',
+  'Previous Position': 'Pp',
+  'Search Volume': 'Nq',
+  CPC: 'Cp',
+  Url: 'Ur',
+  URL: 'Ur',
+  Traffic: 'Tg',
+  'Traffic (%)': 'Tr',
+  'Traffic Cost (%)': 'Tc',
+  Competition: 'Co',
+  'Number of Results': 'Nr',
+  Trends: 'Td',
+  'Keyword Difficulty': 'Kd',
+  'SERP Features': 'Fp',
+  'SERP Features by Position': 'Fp',
+  'Keywords SERP Features': 'Fk',
+  'SERP Features by Keyword': 'Fk',
+  Timestamp: 'Ts',
+  Intents: 'In',
+  Branded: 'Br',
+  Title: 'Tt',
+  Description: 'Ds',
+  'Visible Url': 'Vu',
+  'Number of Keywords': 'Pc',
+};
+
+/**
+ * Normalizes a CSV header to its column code.
+ * If already a known code or not in the map, returns as-is.
+ */
+function normalizeHeader(header) {
+  return HEADER_TO_CODE[header] || header;
+}
+
+/**
+ * Splits a CSV line by semicolons, respecting double-quoted fields.
+ * Handles semicolons inside quoted values (e.g., "Products; Services").
+ * @param {string} line
+ * @returns {string[]}
+ */
+function splitCsvLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (ch === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"';
+        i += 1;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (ch === ';' && !inQuotes) {
+      fields.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  fields.push(current);
+  return fields;
+}
+
+/**
+ * Parses semicolon-delimited CSV text into an array of objects.
+ * First row is treated as headers. Handles double-quoted fields (export_escape=1),
+ * including semicolons and escaped quotes inside quoted values.
+ * Headers are normalized to column codes via HEADER_TO_CODE map.
+ * @param {string} text - Raw CSV response body
+ * @returns {object[]} Array of row objects keyed by column codes
+ */
+export function parseCsvResponse(text) {
+  if (!text || typeof text !== 'string') return [];
+  const lines = text.trim().split('\n');
+  if (lines.length < 2) return [];
+  const headers = splitCsvLine(lines[0]).map((h) => normalizeHeader(h.trim()));
+  return lines.slice(1).map((line) => {
+    const values = splitCsvLine(line);
+    return Object.fromEntries(
+      headers.map((h, i) => [h, (values[i] ?? '').trim()]),
+    );
+  });
+}
+
+/**
+ * Coerces a string CSV value to the appropriate JS type.
+ * @param {string} value - Raw string from CSV
+ * @param {'int'|'float'|'string'|'bool'} type - Target type
+ * @returns {*} Coerced value
+ */
+export function coerceValue(value, type) {
+  if (value === '' || value === undefined || value === null) return null;
+  switch (type) {
+    case 'int': {
+      const parsed = parseInt(value, 10);
+      return Number.isNaN(parsed) ? null : parsed;
+    }
+    case 'float': {
+      const parsed = parseFloat(value);
+      return Number.isNaN(parsed) ? null : parsed;
+    }
+    case 'bool':
+      return value === 'true' || value === '1' || value === 'True';
+    default:
+      return value;
+  }
+}
+
+/**
+ * Enforces an upper bound on a limit value.
+ * @param {number} limit
+ * @param {number} upperLimit
+ * @returns {number}
+ */
+export const getLimit = (limit, upperLimit) => Math.min(limit, upperLimit);
+
+/**
+ * Converts YYYY-MM-DD to YYYYMM15 format used by the SEO API for monthly data.
+ * @param {string} date - ISO date string (YYYY-MM-DD)
+ * @returns {string} Date in YYYYMM15 format
+ */
+export function toApiDate(date) {
+  return `${date.slice(0, 4)}${date.slice(5, 7)}15`;
+}
+
+/**
+ * Returns today's date as YYYY-MM-DD.
+ * @returns {string}
+ */
+export function todayISO() {
+  return new Date().toISOString().split('T')[0];
+}
+
+/**
+ * Converts a YYYYMMDD date string from the API to YYYY-MM-DD.
+ * Returns null for invalid/missing inputs.
+ * @param {string} apiDate - Date in YYYYMMDD format
+ * @returns {string|null} Date in YYYY-MM-DD format, or null if invalid
+ */
+export function fromApiDate(apiDate) {
+  if (!apiDate || apiDate.length < 8 || !/^\d{8}$/.test(apiDate)) return null;
+  return `${apiDate.slice(0, 4)}-${apiDate.slice(4, 6)}-${apiDate.slice(6, 8)}`;
+}
+
+/**
+ * SEO data provider intent codes mapped to field names.
+ */
+export const INTENT_CODES = {
+  COMMERCIAL: 0,
+  INFORMATIONAL: 1,
+  NAVIGATIONAL: 2,
+  TRANSACTIONAL: 3,
+};
+
+/**
+ * Builds a SEO API display_filter string from an array of filter descriptors.
+ * Pipe characters in values are stripped to prevent filter injection.
+ * @param {Array<{sign: string, field: string, op: string, value: string}>} filters
+ * @returns {string} Pipe-delimited filter string
+ */
+export function buildFilter(filters) {
+  return filters
+    .map(({
+      sign, field, op, value,
+    }) => `${sign}|${field}|${op}|${String(value).replace(/\|/g, '')}`)
+    .join('|');
+}
+
+/**
+ * Extracts a brand name from a domain for client-side branded keyword detection.
+ * Uses URI.js to resolve the registrable domain, then takes the first label.
+ * E.g., "adobe.com" → "adobe", "blog.adobe.com" → "adobe", "example.co.uk" → "example"
+ * @param {string} domain
+ * @returns {string} Lowercase brand name
+ */
+export function extractBrand(domain) {
+  if (!domain) return '';
+  const normalized = domain.includes('://') ? domain : `https://${domain}`;
+  const registrable = new URI(normalized).domain();
+  return registrable.split('.')[0].toLowerCase();
+}
+
 /**
  * Merges default query parameters with caller-provided overrides.
  * @param {object} defaults - Default parameter values
@@ -19,13 +220,3 @@
 export function buildQueryParams(defaults, overrides) {
   return { ...defaults, ...overrides };
 }
-
-/**
- * Parses/normalizes an API response.
- * Stub - passes through unchanged. To be extended when implementing API calls.
- * @param {*} response - Raw API response
- * @returns {*} Parsed response
- */
-export function parseResponse(response) {
-  return response;
-}