feat: Serenity Data Insights topics + prompts endpoints | LLMO-6418

[calvarezg]

Summary

Adds two Serenity (Semrush-backed) brand-presence endpoints for the Data Insights table: a per-topic table and a per-prompt drill-down. Backend only — the SR UI wiring (project-elmo-ui) follows in a separate PR.

Both endpoints are built from the single PROMPTS_BY_TOPIC element (78864493) rather than the wiki's 3-element per-topic fan-out: 141adc88 (citations) currently returns 500, 0564b061 lacks a position field, and the live Brand Presence MFE also builds its view from 78864493 alone (verified via live probe + network capture, 2026-07-21).

Endpoints

• GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/topics — per-topic aggregates (promptCount, brand mentions/citations, avg visibility/position/sentiment) with each topic's prompts embedded, for the eager Data Insights table. Brand sub-workspace scoped; optional region/date; returns the full topic list.
• GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/brand-presence/topics/:topicId/prompts — per-prompt drill-down, scoped via CBF_topic (the topic NAME — Semrush topics have no UUID), with server-side pagination.

Notes / gaps (flagged, not silently guessed)

• sourceCount / share-of-voice aren't available from 78864493 (dedicated elements unusable) — left unset (optional in the UI contract).
• Averages exclude the element's sentinels: position: -1 (unranked) and sentiment: null are not averaged; a topic with no ranked/sentiment-bearing prompt yields null.
• New POC endpoint code is fenced with c8 ignore per the sibling convention; unit tests are still included.

Test plan

• topic-prompts + topics-insights definition unit tests (28 cases): payload shape, CBF_topic scoping, sentinel handling, aggregation, volume-sorted embedding.
• OpenAPI contract test extended (serenity-api.test.js): both new operations validate against their response schemas (24 passing).
• npm run docs:lint + docs:build clean; route/capability suites pass (3189).
• Transform + aggregation verified against a real 633-prompt element response (196 topics; drill-down counts match the live probe).
• End-to-end verification against a properly-provisioned Semrush brand — dev's only wired brand has a sub-workspace == org-parent collision, so this will be verified against prod data.

API spec checklist

• API specification updated (api.yaml, serenity-api.yaml, schemas.yaml); representative request/response shapes are exercised by the contract-test fixtures.
• Endpoints are implemented (no "Not implemented yet" / 501 stubs).

Related Issues

https://jira.corp.adobe.com/browse/LLMO-6418

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @calvarezg,

Verdict: Approve - clean, well-structured addition of two new read endpoints that follow all established patterns.
Complexity: HIGH - large diff (1300+ lines across 16 files); API surface + FACS classification touched.
Changes: Adds two Serenity brand-presence Data Insights endpoints (per-topic table and per-prompt drill-down) backed by the PROMPTS_BY_TOPIC element, with full OpenAPI specs, FACS/capability wiring, and definition-layer unit tests (16 files).

Note: CI integration test (it-postgres) is still pending - verify it passes before merge.

Non-blocking (4): minor issues and suggestions

• nit: The region-resolution block in listTopics and listTopicPrompts is identical (lines 646-661 and 729-744 of the controller diff) - consider extracting into a shared helper to reduce duplication as more brand-presence endpoints land. - src/controllers/elements.js
• suggestion: decodeURIComponent in listTopicPrompts (line 705) is defensive against double-encoding but enrichPathInfo already decodes. If it ever encounters a topic name containing a literal %2F (URL-encoded slash), the extra decode will corrupt it. Consider removing and trusting the middleware. - src/controllers/elements.js
• nit: The prompts array is embedded in every topic row in the listTopics response, which means the full per-prompt dataset is returned twice when a client fetches topics then drills down. For large workspaces this could be substantial payload. The OpenAPI spec already marks it optional in spirit (not in required), so a future ?embed=prompts query param could let the UI opt in. - docs/openapi/schemas.yaml
• nit: Number(row?.volume) || 0 in transformTopicPromptsResponse (line 967) coerces volume: 0 correctly (to 0), but would also coerce volume: NaN to 0 silently. The upstream element contract makes this unlikely but the sibling toNumberOrNull function handles the NaN case explicitly - consider consistency. - src/support/elements/definitions/topic-prompts.js

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 8m 42s | Cost: $2.67 | Commit: 4b00d8ca5675d425b927bc4389b0f34f69a75794
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[solaris007]

🎉 This PR is included in version 1.680.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀