feat: brand-vs-competitors API endpoint with aggregate mode

[rainer-friederich]

Summary

• Adds GET /org/:spaceCatId/brands/{all,:brandId}/brand-presence/brand-vs-competitors endpoint
• Single PostgREST query against brand_vs_competitors_by_date VIEW with date-range filters (.gte()/.lte()) — PostgreSQL pushes WHERE clauses through the GROUP BY into partition-pruned, index-covered scans
• Accepts siteId (required) + optional startDate/endDate/model/categoryName/regionCode/aggregate, defaulting to a 28-day date range
• aggregate=true rolls up across categoryName/regionCode server-side, producing one row per (competitor, executionDate) — the shape the Market Tracking chart needs directly. Filters still apply before aggregation.
• Uses resolveModelFromRequest for model resolution (consistent with all other handlers)
• Uses WEEKS_QUERY_LIMIT (200K) to avoid silent data truncation for orgs with many competitors/categories/regions
• Response schema declares required fields so the frontend knows which properties are guaranteed

Depends on

• data-service PR #206 — brand_vs_competitors_by_date regular VIEW

CI will fail until #206 is merged, a new data-service image is published (e.g. v1.35.0), and the default image tag in test/it/postgres/docker-compose.yml is updated from v1.29.0 to the new version. The brand-vs-competitors IT tests require the view which only exists in the new image.

Response shape

Default (aggregate omitted or false): rows at (competitor, executionDate, categoryName, regionCode) granularity — includes categoryName and regionCode fields.

aggregate=true: rows at (competitor, executionDate) granularity — omits categoryName and regionCode, sums totalMentions/totalCitations across them.

Test plan

• 15 unit tests covering auth, validation, single-query flow, camelCase transform, date range defaults, optional filters, aggregate mode, aggregate+filters
• 10 integration tests against real PostgreSQL + PostgREST (validation, access control, date/category filtering, aggregate rollup, brandId scoping)
• Route registration tests updated (6806 tests passing)
• ESLint clean
• OpenAPI specs valid (npm run docs:lint)

Running IT tests locally

The IT tests require the brand_vs_competitors_by_date view from data-service PR #206. Build the image locally:

cd apps/mysticat-data-service
git fetch origin feat/brand-vs-competitors-view
git worktree add /tmp/ds-view-build FETCH_HEAD
docker build -f /tmp/ds-view-build/docker/Dockerfile -t mysticat-data-service:local-with-view /tmp/ds-view-build
git worktree remove /tmp/ds-view-build

cd ../spacecat-api-service
IT_DATA_SERVICE_IMAGE=mysticat-data-service:local-with-view \
  npx mocha --require test/it/postgres/harness.js --timeout 30000 test/it/postgres/brand-vs-competitors.test.js

Once PR #206 merges and a new ECR image is published, update the default image tag in test/it/postgres/docker-compose.yml.

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[rainer-friederich]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[rainer-friederich]

Code review

Found 1 issue:

1. createBrandVsCompetitorsHandler uses params.model || 'chatgpt' instead of resolveModelFromRequest(params.model). The literal 'chatgpt' is not a valid llm_model enum value -- the correct default is 'chatgpt-free'. All other handlers in this file use resolveModelFromRequest, which maps aliases (e.g. 'chatgpt' -> 'chatgpt-free') and defaults to DEFAULT_MODEL. When no model query param is provided, this handler will send the invalid value 'chatgpt' to PostgREST, likely returning zero rows or an error. (CLAUDE.md says "Follow existing patterns: Examine similar features")

spacecat-api-service/src/controllers/llmo/llmo-brand-presence.js

Lines 2590 to 2592 in d012cdb

	const filterByBrandId = brandId && brandId !== 'all' ? brandId : null;
	const model = params.model || 'chatgpt';
	const startDate = params.startDate || defaults.startDate;

Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}