feat(elements): add brand-presence market-tracking-trends endpoint

Add GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends,
a Semrush Elements wrapper returning weekly per-competitor mentions + citations for the
brand-presence-sr-ui Competitor Comparison chart (CitationsMentionsTrendChart).

Mentions come from TRENDS_MV (b5281393); citations from the market-tracking citations
element (2e5a6f4e, new MARKET_CITATIONS_TREND constant). Both are weekly line elements
that return one series per market participant keyed by legend=name, so competitors arrive
natively as tracked benchmarks with no fan-out. The contract was ground-truthed against
the live Brand Presence MFE. See docs/elements/market-tracking-trends-plan.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hjen_adobe

docs/elements/market-tracking-trends-plan.md

@@ -0,0 +1,161 @@
+# Implementation Plan — `GET .../brand-presence/market-tracking-trends`
+
+> Status: **Implemented.**
+> Endpoint: `GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends`
+>
+> Companion reference: [`semrush-elements-api-reference.md`](./semrush-elements-api-reference.md)
+> — read that first for the shared conventions (transport, definitions, service layer)
+> this plan builds on.
+
+Powers the **Competitor Comparison** chart (`CitationsMentionsTrendChart`) on the
+`brand-presence-sr-ui` dashboard: a weekly time series of mentions and citations for the
+tracked brand and each of its competitors.
+
+> **Verified against the Brand Presence MFE.** The element mapping below was derived by
+> observing the request/response shapes of the Semrush micro-frontend's "Market Tracking"
+> chart (Mentions and Citations tabs) — not inferred from the migration wiki. The wiki's
+> documented citations trend element (`b81af644`, domain-level) is **not** what this chart
+> uses. All brand names and metrics in the examples below are synthetic.
+
+---
+
+## 0. API Reference
+
+`GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends`
+
+Auth: same as every other Elements-wrapper route (`authorizeOrg` — IMS/promise-token, org +
+brand access, resolves the brand's Semrush workspace). FACS `llmo/can_view`; S2S `brand:read`.
+
+### Query parameters (all optional)
+
+| Param | Aliases | Default | Description |
+|---|---|---|---|
+| `startDate` | `start_date` | 28 days before today | Range start, `YYYY-MM-DD`. 400 if not a valid calendar date. |
+| `endDate` | `end_date` | today | Range end, `YYYY-MM-DD`. 400 if invalid, or before `startDate`. |
+| `model` | `platform` | `search-gpt` (via `resolveElementModel`) | AI model/platform filter. Unrecognized values fall back to the default. |
+| `regionCode` | `region_code`, `region` | — | One region+language code (e.g. `US`) → a single Semrush `projectId` via `resolveRegionProjectId`; 404 if it matches no market. `all`/absent → aggregate across **every** project the brand owns. |
+| `siteId` | `site_id` | — | Cross-check only: must resolve (via `getBrandBySite`) to the same brand as `:brandId`; 400 otherwise. Does not itself narrow the query. |
+
+Bucketing is **weekly only** for now (`auto_bucketing: "week"` is hardcoded). Day/month is a
+trivial future extension via a `granularity` param.
+
+### Response shape
+
+```json
+{
+  "weeklyTrends": [
+    {
+      "week": "2026-07-05",
+      "weekNumber": 27,
+      "year": 2026,
+      "mentions": 900,
+      "citations": 5000,
+      "competitors": [
+        { "name": "Rival One", "mentions": 150, "citations": 300 },
+        { "name": "Rival Two", "mentions": 120, "citations": 250 }
+      ]
+    }
+  ]
+}
+```
+
+- One entry per ISO week (`week` = the element's week-start `x`, `YYYY-MM-DD`), sorted ascending.
+- `mentions`/`citations` are the **tracked brand's** own totals that week; each competitor's
+  totals sit in `competitors[]` (sorted by mentions desc).
+- Visibility is intentionally **not** included (out of scope for this chart).
+
+### Error responses
+
+| Status | `error` token | Cause |
+|---|---|---|
+| 400 | `invalidRequest` | `brandId` not a UUID; malformed/out-of-order dates; `siteId` doesn't belong to `:brandId` |
+| 401 | `authenticationRequired` | Missing/invalid bearer (non-IMS caller with no `x-promise-token`) |
+| 403 | `forbidden` | Caller lacks org access |
+| 404 | `notFound` | Org/brand not found; brand has no Semrush workspace; `regionCode` matches no market |
+| 502 | `elementsUpstreamError` | Non-auth Semrush upstream failure |
+| 500 | `internalServerError` | Unexpected error |
+
+---
+
+## 1. Element mapping (confirmed against live payloads)
+
+Both elements are `type: "line"`, `auto_bucketing: "week"`, with **no brand filter** — that is
+what makes the response include one series per tracked competitor (competitors are tracked as
+Semrush benchmarks). Each `blocks.lines[]` row is `{ legend, x, y__mentions, … }` where
+`legend` is the brand/competitor **name** and `x` is the ISO week-start date.
+
+| Chart metric | Element | Constant | Project filter col | Value field |
+|---|---|---|---|---|
+| Mentions | `b5281393-ee98-4c38-9ed5-3437b0c450c3` | `TRENDS_MV` (pre-existing) | `CBF_project` (singular) | `y__mentions` |
+| Citations | `2e5a6f4e-f287-4951-a7e2-7e29981c86d8` | `MARKET_CITATIONS_TREND` (new) | `CBF_projects` (**plural**) | `y__mentions` |
+
+> ⚠️ **`y__mentions` means different things per element.** In `TRENDS_MV` it is the mention
+> count; in `MARKET_CITATIONS_TREND` the *same key* carries the **citation** count (Semrush
+> reuses the generic field name). The transform maps `TRENDS_MV.y__mentions → mentions` and
+> `MARKET_CITATIONS_TREND.y__mentions → citations`. (The citations element also returns
+> `y__prompts_with_mentions` and `y__visibility`, which power the MFE's sibling "Responses with
+> Citations" / "Source Visibility" sub-tabs — unused here.)
+
+### Confirmed request payload (both elements)
+
+```json
+{
+  "auto_bucketing": "week",
+  "filters": {
+    "simple": { "start_date": "2026-06-16", "end_date": "2026-07-15" },
+    "advanced": { "op": "and", "filters": [
+      { "op": "or", "filters": [{ "op": "eq", "val": "search-gpt", "col": "CBF_model" }] },
+      { "op": "or", "filters": [
+        { "op": "eq", "val": "<projectId1>", "col": "CBF_project" },
+        { "op": "eq", "val": "<projectId2>", "col": "CBF_project" }
+      ] }
+    ] }
+  }
+}
+```
+
+Citations differs only in the project column name (`CBF_projects`). Note: unlike the KPI/URL
+elements, these trend elements take plain `start_date`/`end_date` in `simple` (not
+`CBF_date__start`/`end`) and send **no** `comparison_data_formatting`.
+
+---
+
+## 2. Codebase changes
+
+- **`src/support/elements/element-ids.js`** — new `MARKET_CITATIONS_TREND` constant.
+- **`src/support/elements/definitions/market-tracking-trends.js`** (new) —
+  `buildMarketMentionsTrendPayload` (`CBF_project`), `buildMarketCitationsTrendPayload`
+  (`CBF_projects`), and `transformMarketTrackingTrends(mentionsRaw, citationsRaw, brandName)`
+  which groups both `blocks.lines[]` by ISO week, splits the brand line
+  (`legend === brandName`, case-insensitive) from competitor lines, and defaults a missing
+  metric to 0. Exported from `definitions/index.js`.
+- **`src/support/elements/elements-service.js`** — `getMarketTrackingTrends(workspaceId, {...})`
+  fetches the two elements in parallel and returns `{ weeklyTrends }`. No per-week fan-out (the
+  elements are already weekly-bucketed) and no per-competitor fan-out (`legend` carries them).
+  `projectId` (single region) takes precedence over `projectIds` (aggregate all projects).
+- **`src/controllers/elements.js`** — `getMarketTrackingTrends` handler (mirrors the URL
+  Inspector handlers: `authorizeOrg`, `siteId` cross-check, optional-date validation with a
+  28-day default via `defaultTrailingDateRange`, region→`projectId` resolution else all projects,
+  `cachedOk`).
+- **`src/routes/index.js`**, **`src/routes/facs-capabilities.js`** (`llmo/can_view`),
+  **`src/routes/required-capabilities.js`** (`brand:read`) — route registration + classification.
+
+No new element UUIDs beyond `MARKET_CITATIONS_TREND`; `brandId` is already a classified LLMO
+FACS brand resource.
+
+## 3. Tests
+
+- `test/support/elements/definitions/market-tracking-trends.test.js` — payload builders
+  (singular vs plural project col, no-projectIds branch, model fallback) + transform
+  (brand/competitor split, week grouping, missing-metric → 0, case-insensitive brand match,
+  malformed-line skipping).
+- `test/support/elements/elements-service.test.js` — `getMarketTrackingTrends` (both element
+  calls, merge, `projectId` precedence, error propagation).
+- `test/controllers/elements.test.js` — auth reuse, date defaulting/validation, region
+  resolution + 404, `siteId` cross-check, error mapping.
+- `test/routes/index.test.js` — route registration.
+
+## 4. Out of scope
+
+UI wiring; Competitor Summary / Share of Voice / Sentiment endpoints; visibility; day/month
+bucketing.

src/controllers/elements.js

@@ -144,6 +144,20 @@ function splitCsv(value) {
   return value.split(',').map((v) => v.trim()).filter((v) => v.length > 0);
 }
 
+/**
+ * Default 28-day trailing `{ startDate, endDate }` (YYYY-MM-DD), used by endpoints
+ * whose date range is optional (e.g. market-tracking-trends) when the caller omits it.
+ */
+function defaultTrailingDateRange() {
+  const end = new Date();
+  const start = new Date();
+  start.setDate(start.getDate() - 28);
+  return {
+    startDate: start.toISOString().slice(0, 10),
+    endDate: end.toISOString().slice(0, 10),
+  };
+}
+
 /**
  * Extracts and validates the IMS bearer token from the inbound Authorization header.
  * Throws 401 if missing or if the caller authenticated via a non-IMS mechanism.
@@ -739,12 +753,101 @@ export default function ElementsController(context, log, env) {
   };
   /* c8 ignore stop */
 
+  /**
+   * GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends
+   * Weekly per-competitor mentions + citations for the Competitor Comparison chart on
+   * the brand-presence-sr-ui dashboard. Backed by two weekly `line` elements (TRENDS_MV
+   * for mentions, MARKET_CITATIONS_TREND for citations); competitors come back natively
+   * as tracked-benchmark legends, so no competitor list is needed as input. See
+   * docs/elements/market-tracking-trends-plan.md.
+   *
+   * Query params (all optional): `startDate`/`start_date` + `endDate`/`end_date`
+   * (default: 28-day trailing window), `model`/`platform` (default search-gpt),
+   * `regionCode`/`region_code`/`region` (a single region → its one Semrush project;
+   * `all`/absent → aggregate across every project the brand owns), `siteId`/`site_id`
+   * (cross-check only — must belong to `:brandId`).
+   */
+  const getMarketTrackingTrends = async (ctx) => {
+    try {
+      const auth = await authorizeOrg(ctx);
+      if (auth.error) {
+        return auth.error;
+      }
+      const { spaceCatId, brandId } = ctx?.params ?? {};
+      const { workspaceId, brand } = auth;
+      const query = extractQuery(ctx);
+
+      // The path already names the brand; a siteId filter is only honored when it
+      // belongs to that brand (mirrors listWeeks / listCitedDomains).
+      const siteId = query.siteId || query.site_id;
+      if (hasText(siteId)) {
+        const postgrestClient = ctx?.dataAccess?.services?.postgrestClient;
+        const resolved = await getBrandBySite(spaceCatId, siteId, postgrestClient, log);
+        if (!resolved || resolved.id !== brand.id) {
+          return badRequest('siteId does not belong to the specified brand');
+        }
+      }
+
+      // Date range is optional (defaults to a 28-day trailing window); when a value is
+      // sent it must be a valid YYYY-MM-DD and correctly ordered.
+      const startDate = query.startDate || query.start_date;
+      const endDate = query.endDate || query.end_date;
+      if (hasText(startDate) && !isYmdDate(startDate)) {
+        return badRequest('startDate must be a valid YYYY-MM-DD date');
+      }
+      if (hasText(endDate) && !isYmdDate(endDate)) {
+        return badRequest('endDate must be a valid YYYY-MM-DD date');
+      }
+      if (hasText(startDate) && hasText(endDate) && startDate > endDate) {
+        return badRequest('startDate must not be after endDate');
+      }
+      const defaultRange = defaultTrailingDateRange();
+
+      const service = await buildService(ctx);
+      const { BrandSemrushProject } = ctx?.dataAccess ?? {};
+      const brandSemrushProjects = await fetchBrandSemrushProjects(BrandSemrushProject, [brand]);
+
+      // A single selected region+language → its one Semrush projectId. region=all/absent
+      // → every project the brand owns (the payload builder ORs them into one call, so
+      // neither path fans out).
+      let projectId;
+      let projectIds;
+      const region = query.regionCode || query.region_code || query.region;
+      if (hasText(region) && region.toLowerCase() !== 'all') {
+        projectId = await service.resolveRegionProjectId(workspaceId, {
+          brandId, region, brandSemrushProjects,
+        });
+        if (!hasText(projectId)) {
+          return notFound(`No Semrush market found for region: ${region}`);
+        }
+      } else {
+        projectIds = brandSemrushProjects
+          .map((p) => p.semrushProjectId)
+          .filter(hasText);
+      }
+
+      const result = await service.getMarketTrackingTrends(workspaceId, {
+        model: query.model,
+        platform: query.platform,
+        startDate: startDate || defaultRange.startDate,
+        endDate: endDate || defaultRange.endDate,
+        projectId,
+        projectIds,
+        brandName: brand.name,
+      });
+      return cachedOk(result);
+    } catch (e) {
+      return mapError(e, log);
+    }
+  };
+
   return {
     listUrlInspectorFilterDimensions,
     listWeeks,
     listPrompts,
     listCitedDomains,
     listOwnedUrls,
     listDomainUrls,
+    getMarketTrackingTrends,
   };
 }

src/routes/facs-capabilities.js

@@ -814,6 +814,7 @@ const routeFacsCapabilities = {
       'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/cited-domains': 'llmo/can_view',
       'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/owned-urls': 'llmo/can_view',
       'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/domain-urls': 'llmo/can_view',
+      'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends': 'llmo/can_view',
       'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/stats': 'llmo/can_view',
       // Preflight (site-scoped reads)
       'GET /sites/:siteId/preflights': 'llmo/can_view',

src/routes/index.js

@@ -254,6 +254,7 @@ export default function getRouteHandlers(
     'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/cited-domains': elementsController.listCitedDomains,
     'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/owned-urls': elementsController.listOwnedUrls,
     'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/domain-urls': elementsController.listDomainUrls,
+    'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends': elementsController.getMarketTrackingTrends,
     // Brand-independent Semrush language catalog (add-brand wizard language picker).
     'GET /v2/orgs/:spaceCatId/serenity/languages': serenityController.listOrgLanguages,
     'POST /v2/orgs/:spaceCatId/brands/:brandId/serenity/activate': serenityController.activate,

src/routes/required-capabilities.js

@@ -310,6 +310,7 @@ const routeRequiredCapabilities = {
   'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/cited-domains': 'brand:read',
   'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/owned-urls': 'brand:read',
   'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/url-inspector/domain-urls': 'brand:read',
+  'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends': 'brand:read',
   'POST /v2/orgs/:spaceCatId/brands/:brandId/serenity/activate': 'organization:write',
   'POST /v2/orgs/:spaceCatId/brands/:brandId/serenity/deactivate': 'organization:write',
   'GET /v2/orgs/:spaceCatId/sites/:siteId/brand': 'organization:read',

src/support/elements/definitions/index.js

@@ -29,3 +29,8 @@ export {
   transformOwnedUrlsResponse,
 } from './owned-urls.js';
 export { buildDomainUrlsPayload, transformDomainUrlsResponse } from './domain-urls.js';
+export {
+  buildMarketMentionsTrendPayload,
+  buildMarketCitationsTrendPayload,
+  transformMarketTrackingTrends,
+} from './market-tracking-trends.js';