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

### New endpoint: `GET
/v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/market-tracking-trends`

## Summary

Adds a Semrush **Elements**-backed endpoint returning **weekly
per-competitor mentions + citations** for the tracked brand and its
competitors — the data behind the **Competitor Comparison** chart
(`CitationsMentionsTrendChart`) on the `brand-presence-sr-ui` dashboard.

Full design notes, the confirmed Semrush payload/response shapes, and
resolved decisions are in `docs/elements/market-tracking-trends-plan.md`
(modeled on `brand-presence-stats-plan.md` from #2823). All brand names
and metrics in the docs/tests are synthetic.

> The element mapping was verified by observing the Brand Presence MFE's
"Market Tracking" chart request/response shapes (Mentions and Citations
tabs) — not inferred from the migration wiki, whose documented citations
trend element (`b81af644`, domain-level) is *not* what this chart uses.

## Element mapping

Both are `type: "line"`, `auto_bucketing: "week"`, **no brand filter**
(so competitors come back natively as tracked-benchmark `legend`s):

| Chart metric | Element | Constant | Project filter col | Value field |
|---|---|---|---|---|
| Mentions | `b5281393` | `TRENDS_MV` (existing) | `CBF_project`
(singular) | `y__mentions` |
| Citations | `2e5a6f4e` | `MARKET_CITATIONS_TREND` (**new**) |
`CBF_projects` (**plural**) | `y__mentions` |

⚠️ Both elements expose the value under the key `y__mentions`; in the
citations element that number is the **citation** count (Semrush reuses
the generic key). The transform maps each to the right metric.

## What changed

- **Route + auth scaffold** (`routes/index.js`,
`routes/facs-capabilities.js` → `llmo/can_view`,
`routes/required-capabilities.js` → `brand:read`): registers the route
under the existing brand-scoped `authorizeOrg` pattern; `brandId` reuses
the existing LLMO FACS brand alias.
- **Controller** `getMarketTrackingTrends` (`controllers/elements.js`):
mirrors the URL-inspector handlers — `authorizeOrg`, `siteId`
cross-check, optional dates with a 28-day trailing default + validation,
region→`projectId` resolution (else aggregate across all the brand's
projects), `cachedOk`.
- **Definitions**
(`support/elements/definitions/market-tracking-trends.js`, new): weekly
payload builders (`CBF_project` vs `CBF_projects`, no brand filter, no
`comparison_data_formatting`) + `transformMarketTrackingTrends` — groups
both `blocks.lines[]` by ISO week, splits the brand line from competitor
lines, defaults a missing metric to 0.
- **Service** `getMarketTrackingTrends`
(`support/elements/elements-service.js`): fetches the two elements in
parallel; no per-week fan-out (elements are pre-bucketed) and no
per-competitor fan-out (`legend` carries them). `projectId` (single
region) takes precedence over `projectIds` (aggregate).
- **Element id** (`support/elements/element-ids.js`): new
`MARKET_CITATIONS_TREND`.
- **Design doc** (`docs/elements/market-tracking-trends-plan.md`, new).

## Response shape

```json
{
  "weeklyTrends": [
    {
      "week": "2026-07-05", "weekNumber": 27, "year": 2026,
      "mentions": 900, "citations": 5000,
      "competitors": [ { "name": "Rival One", "mentions": 150, "citations": 300 } ]
    }
  ]
}
```

## Testing

- New/added unit suites: definitions (payload builders + transform),
service (`getMarketTrackingTrends`), controller (auth, date
defaulting/validation, region resolution + 404, `siteId` cross-check,
error mapping), and route registration.
- Route-param FACS classification + required-capabilities drift suites
pass.
- Weekly-only bucketing for now; visibility intentionally excluded (out
of scope for this chart).

## Out of scope

UI wiring (DAL service + hook + `SRCompetitorComparisonSection`);
Competitor Summary / Share of Voice / Sentiment endpoints; day/month
bucketing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: hjen_adobe <hjen@adobe.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

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

@@ -0,0 +1,166 @@
+# 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. |
+
+**Both or neither** (mirrors the URL-inspector handlers): if only one of `startDate`/`endDate`
+is supplied, both are ignored and the full 28-day default range is used as a unit — a
+half-supplied bound never pairs with the default's other half. The resolved span is capped at
+**`MAX_RANGE_DAYS = 366`** (400 otherwise) to bound upstream fan-out.
+
+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.

docs/openapi/api.yaml

@@ -176,6 +176,8 @@ paths:
     $ref: './serenity-api.yaml#/v2-serenity-deactivate'
   /v2/orgs/{spaceCatId}/brands/{brandId}/serenity/brand-presence/url-inspector/filter-dimensions:
     $ref: './serenity-api.yaml#/v2-serenity-url-inspector-filter-dimensions'
+  /v2/orgs/{spaceCatId}/brands/{brandId}/serenity/brand-presence/market-tracking-trends:
+    $ref: './serenity-api.yaml#/v2-serenity-market-tracking-trends'
   /v2/orgs/{spaceCatId}/brands/{brandId}/serenity/brand-presence/sentiment-overview:
     $ref: './serenity-api.yaml#/v2-serenity-brand-presence-sentiment-overview'
   /v2/orgs/{spaceCatId}/brands/{brandId}/serenity/brand-presence/stats:

docs/openapi/schemas.yaml

@@ -11717,6 +11717,50 @@ SerenityUrlInspectorFilterDimensions:
     description: Tags grouped by a Semrush tag prefix not covered by the fixed dimensions above.
     items: { $ref: '#/SerenityFilterDimensionItem' }
 
+SerenityMarketTrackingTrends:
+  type: object
+  description: |
+    Weekly Market Tracking Trends for the Serenity (Semrush Elements-backed)
+    Brand Presence Competitor Comparison chart. Each entry is one ISO week; the
+    tracked brand's own totals are at the top level and every tracked competitor
+    (a Semrush benchmark) is an entry in `competitors`. Mentions come from the
+    Trends Mentions/Visibility element and citations from the Market Tracking
+    citations element; both are already weekly-bucketed by Semrush.
+  required: [weeklyTrends]
+  properties:
+    weeklyTrends:
+      type: array
+      description: One entry per ISO week, sorted ascending by `week`.
+      items:
+        type: object
+        required: [week, weekNumber, year, mentions, citations, competitors]
+        properties:
+          week:
+            type: string
+            format: date
+            description: ISO week-start date (`YYYY-MM-DD`), from the Semrush bucket's `x`.
+          weekNumber:
+            type: integer
+            description: ISO week number (1–53).
+          year:
+            type: integer
+            description: ISO week-numbering year.
+          mentions:
+            type: integer
+            description: The tracked brand's own mentions in this week.
+          citations:
+            type: integer
+            description: The tracked brand's own citations in this week.
+          competitors:
+            type: array
+            description: Per-competitor mentions + citations for this week, sorted by mentions desc.
+            items:
+              type: object
+              required: [name, mentions, citations]
+              properties:
+                name: { type: string }
+                mentions: { type: integer }
+                citations: { type: integer }
 SerenityBrandPresenceStatsValues:
   type: object
   description: The four aggregated Brand Presence KPI values, shared by the top-level `stats` and each `trends[].data.stats` entry.

docs/openapi/serenity-api.yaml

@@ -1404,3 +1404,121 @@ v2-serenity-brand-presence-stats:
           application/json:
             schema: { $ref: './schemas.yaml#/SerenityErrorResponse' }
       '500': { $ref: './responses.yaml#/500' }
+
+v2-serenity-market-tracking-trends:
+  parameters:
+    - name: spaceCatId
+      in: path
+      required: true
+      description: SpaceCat Organization ID (UUID)
+      schema:
+        type: string
+        format: uuid
+    - name: brandId
+      in: path
+      required: true
+      description: Brand ID (UUID-only on the /serenity/* surface)
+      schema:
+        type: string
+        format: uuid
+  get:
+    tags: [serenity]
+    summary: Weekly Market Tracking Trends for the Brand Presence Competitor Comparison chart
+    description: |
+      Returns a weekly time series of mentions and citations for the tracked
+      brand and each of its competitors, sourced from two Semrush Elements
+      (Trends Mentions/Visibility + Market Tracking citations) — not from Adobe
+      Postgres. Competitors are the brand's tracked Semrush benchmarks; they are
+      returned automatically (no competitor list input). Each entry is one ISO
+      week; the brand's own totals are at the top level and each competitor is an
+      entry in `competitors`. See `SerenityMarketTrackingTrends`.
+
+      Date range is optional and defaults to a 28-day trailing window. Both
+      `startDate` and `endDate` must be supplied together or not at all — a
+      half-supplied range falls back to the full default as a unit. The resolved
+      span is capped at 366 days (400 otherwise).
+    operationId: listSerenityMarketTrackingTrends
+    security:
+      - ims_key: []
+    parameters:
+      - name: startDate
+        in: query
+        required: false
+        description: |
+          Range start (`YYYY-MM-DD`). Alias `start_date`. Defaults to 28 days
+          before today. Must be supplied together with `endDate` (else both are
+          ignored and the default range is used).
+        schema: { type: string, format: date }
+      - name: endDate
+        in: query
+        required: false
+        description: Range end (`YYYY-MM-DD`). Alias `end_date`. Defaults to today.
+        schema: { type: string, format: date }
+      - name: model
+        in: query
+        required: false
+        description: |
+          AI model to scope the trends to. Accepts a Semrush Elements model name
+          directly, or a SpaceCat/UI platform code (translated server-side).
+          Defaults to `search-gpt` when omitted or unrecognized.
+        schema:
+          type: string
+          x-canonical-values:
+            - google-ai-mode
+            - grok-3
+            - google-ai-overview
+            - microsoft-copilot
+            - open-evidence
+            - gemini-2.5-flash
+            - claude-sonnet-4
+            - gpt-5
+            - deepseek
+            - search-gpt
+            - perplexity
+          x-known-aliases:
+            copilot: microsoft-copilot
+            gemini: gemini-2.5-flash
+            openai: gpt-5
+            chatgpt: search-gpt
+      - name: platform
+        in: query
+        required: false
+        description: Legacy alias for `model`; `model` takes precedence when both are given.
+        schema: { type: string }
+      - name: regionCode
+        in: query
+        required: false
+        description: |
+          One region+language code (e.g. `US`), resolved to a single Semrush
+          project. Aliases `region_code`, `region`. `all` or absent aggregates
+          across every project the brand owns.
+        schema: { type: string }
+      - name: siteId
+        in: query
+        required: false
+        description: |
+          Optional cross-check: must resolve to the same brand as `:brandId`
+          (400 otherwise). Alias `site_id`. Does not itself narrow the query.
+        schema: { type: string }
+    responses:
+      '200':
+        description: Weekly market tracking trends retrieved.
+        content:
+          application/json:
+            schema: { $ref: './schemas.yaml#/SerenityMarketTrackingTrends' }
+      '400': { $ref: './responses.yaml#/400' }
+      '403':
+        description: Caller lacks access to the organization.
+      '404':
+        description: Organization not found, brand not found for this organization, the brand has no resolvable Semrush workspace, or the requested region matches no market.
+      '502':
+        description: Upstream returned a non-2xx response.
+        content:
+          application/json:
+            schema: { $ref: './schemas.yaml#/SerenityErrorResponse' }
+      '503':
+        description: PostgREST client not configured for this deployment.
+        content:
+          application/json:
+            schema: { $ref: './schemas.yaml#/SerenityErrorResponse' }
+      '500': { $ref: './responses.yaml#/500' }