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

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/mysticat-shared-seo-client-v1.2.1](https://github.com/adobe/spacecat-shared/compare/@adobe/mysticat-shared-seo-client-v1.2.0...@adobe/mysticat-shared-seo-client-v1.2.1) (2026-04-10)
+
+### Bug Fixes
+
+* **seo-client:** add prefix URL filter to getTopPages ([#1528](https://github.com/adobe/spacecat-shared/issues/1528)) ([60e0a31](https://github.com/adobe/spacecat-shared/commit/60e0a31cb2948282c61498baaa0442791ed210b2))
+
 ## [@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

package/README.md

@@ -29,6 +29,43 @@ const config = {
 const client = new SeoClient(config, fetch);
 ```
 
+## API Methods
+
+### `getTopPages(url, opts)`
+
+Returns the top organic pages for a given URL prefix, sorted by traffic. Fans out across multiple databases to aggregate traffic globally.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `string` | *(required)* | A **prefix URL** scoping which pages to return. Can include protocol (e.g., `https://www.example.com`) or omit it (e.g., `www.example.com`, `example.com/us`). |
+| `opts.limit` | `number` | `200` | Maximum number of pages to return (capped at 2000). |
+| `opts.region` | `string` | *(optional)* | ISO 3166-1 alpha-2 region code (e.g., `CZ`). Added to the default database list if not already present. |
+
+**Prefix URL filtering:**
+
+The `url` parameter acts as a prefix filter, not just a plain domain. This ensures that only pages belonging to the intended hostname (and optional path prefix) are returned. For example, passing `https://www.example.com` excludes pages from subdomains like `blog.example.com` or `shop.example.com`.
+
+- **www prefixes** (e.g., `https://www.example.com`): The method applies a server-side `Bw` (begins with) display filter on the SEO API call. This reliably scopes results to the correct hostname.
+- **Non-www prefixes** (e.g., `https://example.com`, `example.com/us`): The `Bw` API filter is unreliable for non-www domains because it can match subdomains (e.g., a filter for `https://example.com` also matches `https://example.com.au`). To handle this, the method over-fetches (2x the requested limit) and applies client-side filtering, keeping only pages whose URL equals the prefix or starts with `{prefix}/`.
+- If client-side filtering for non-www prefixes cannot meet the requested `limit`, a warning is logged (when the API returned a full result set, suggesting more pages exist but were filtered out) or a debug message is logged (when the provider simply has fewer matching pages).
+
+**Returns:** `{ result: { pages: Array<{ url, sum_traffic, top_keyword }> }, fullAuditRef }`
+
+**Example:**
+
+```js
+// Fetch top 100 pages for www.example.com (API-level filtering)
+const { result } = await client.getTopPages('https://www.example.com', { limit: 100 });
+
+// Fetch top 50 pages for a subfolder prefix (client-side filtering)
+const { result: subResult } = await client.getTopPages('example.com/us', { limit: 50 });
+
+// Fetch with a specific region database
+const { result: czResult } = await client.getTopPages('https://www.example.cz', { limit: 100, region: 'CZ' });
+```
+
 ## Testing
 
 ```bash

package/package.json

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

package/src/client.js

@@ -222,28 +222,55 @@ export default class SeoClient {
       throw new Error(`Invalid URL: ${url}`);
     }
 
+    // Ensure url has protocol for the Bw filter and extract hostname for the API.
+    // Input is a prefix URL, either full (https://www.example.com) or protocol-stripped
+    // (www.example.com, example.com/us).
+    const prefixUrl = (url.includes('://') ? url : `https://${url}`).replace(/\/+$/, '');
+    let domain;
+    try {
+      domain = new URL(prefixUrl).hostname;
+    } catch {
+      this.log.warn(`[SEO] Could not parse URL "${url}", using raw value as domain`);
+      domain = url;
+    }
+
+    const isWww = domain.startsWith('www.');
     const ep = ENDPOINTS.topPages;
     const epKw = ENDPOINTS.topPagesKeywords;
-    const effectiveLimit = getLimit(limit, 2000);
+
+    // For non-www prefixes, the Bw filter is unreliable (matches subdomains),
+    // so we over-fetch and filter client-side. Note: at limit >= 1000 the 2000
+    // cap leaves no over-fetch headroom.
+    const requestLimit = !isWww
+      ? getLimit(limit * 2, 2000)
+      : getLimit(limit, 2000);
     const databases = getDatabases(region);
 
+    // Build display_filter: traffic > 0, plus Bw prefix filter
+    const filters = [
+      {
+        sign: '+', field: 'Tg', op: 'Gt', value: '0',
+      },
+      {
+        sign: '+', field: 'Ur', op: 'Bw', value: prefixUrl,
+      },
+    ];
+
     const dbResults = await this.fanOut(databases, async (db) => {
-      const commonParams = { domain: url, database: db };
-      const [{ body: pagesBody, fullAuditRef }, { body: kwBody }] = await Promise.all([
+      const commonParams = { domain, database: db };
+      const [{ body: pagesBody, fullAuditRef: ref }, { body: kwBody }] = await Promise.all([
         this.sendRawRequest({
           type: ep.type,
           ...commonParams,
-          display_limit: effectiveLimit,
+          display_limit: requestLimit,
           export_columns: ep.columns,
-          display_filter: buildFilter([{
-            sign: '+', field: 'Tg', op: 'Gt', value: '0',
-          }]),
+          display_filter: buildFilter(filters),
           ...ep.defaultParams,
         }, ep.path),
         this.sendRawRequest({
           type: epKw.type,
           ...commonParams,
-          display_limit: effectiveLimit * 3,
+          display_limit: requestLimit * 3,
           export_columns: epKw.columns,
           ...epKw.defaultParams,
         }, epKw.path),
@@ -251,7 +278,7 @@ export default class SeoClient {
       return {
         pageRows: parseCsvResponse(pagesBody),
         kwRows: parseCsvResponse(kwBody),
-        fullAuditRef,
+        fullAuditRef: ref,
       };
     }, 'getTopPages');
 
@@ -282,13 +309,30 @@ export default class SeoClient {
       }
     }
 
-    const pages = [...pageMap.values()]
+    let 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);
+      .sort((a, b) => b.sum_traffic - a.sum_traffic);
+
+    // For non-www prefixes, apply client-side filtering since Bw is unreliable
+    if (!isWww) {
+      const filteredPages = pages.filter(
+        (page) => page.url === prefixUrl
+          || page.url.startsWith(`${prefixUrl}/`),
+      );
+
+      if (filteredPages.length < limit && pages.length >= requestLimit) {
+        this.log.warn(`[SEO] Could not meet ${limit} top pages for ${prefixUrl} after requesting ${requestLimit} (got ${filteredPages.length} matching)`);
+      } else if (filteredPages.length < limit) {
+        this.log.debug(`[SEO] Provider has only ${filteredPages.length} pages matching prefix ${prefixUrl}`);
+      }
+
+      pages = filteredPages;
+    }
+
+    pages = pages.slice(0, limit);
 
     return {
       result: { pages },