From 041d1662db9f295d6820a31a296e4cdd94eb30d7 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 2 Apr 2026 14:29:39 +0200 Subject: [PATCH 01/16] feat: add URL Inspector PG API endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 4 new endpoints calling the URL Inspector RPCs in mysticat-data-service: - GET .../url-inspector/stats — aggregate stats + weekly sparklines - GET .../url-inspector/owned-urls — paginated owned URL citations - GET .../url-inspector/trending-urls — paginated non-owned URLs - GET .../url-inspector/cited-domains — domain-level aggregations Exports shared utilities from llmo-brand-presence.js for reuse. LLMO-4030 Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-03-31-url-inspector-pg-endpoints.md | 126 +++++ src/controllers/llmo/llmo-brand-presence.js | 11 +- .../llmo/llmo-mysticat-controller.js | 18 + src/controllers/llmo/llmo-url-inspector.js | 346 +++++++++++++ src/routes/index.js | 10 + src/routes/required-capabilities.js | 10 + .../llmo/llmo-url-inspector.test.js | 458 ++++++++++++++++++ 7 files changed, 974 insertions(+), 5 deletions(-) create mode 100644 docs/plans/2026-03-31-url-inspector-pg-endpoints.md create mode 100644 src/controllers/llmo/llmo-url-inspector.js create mode 100644 test/controllers/llmo/llmo-url-inspector.test.js diff --git a/docs/plans/2026-03-31-url-inspector-pg-endpoints.md b/docs/plans/2026-03-31-url-inspector-pg-endpoints.md new file mode 100644 index 000000000..8be402c16 --- /dev/null +++ b/docs/plans/2026-03-31-url-inspector-pg-endpoints.md @@ -0,0 +1,126 @@ +# URL Inspector PG Endpoints + +**Ticket:** [LLMO-4030](https://jira.corp.adobe.com/browse/LLMO-4030) +**Date:** 2026-03-31 +**Status:** Implementation complete, pending deployment + +## Problem + +The URL Inspector page in project-elmo-ui fetches ALL brand_presence data from spreadsheets (HLX Weekly API) and processes everything client-side. The `brand_presence_sources` table in PostgreSQL has ~2.1M rows and ~333K distinct URLs. Client-side aggregation is not viable at this scale. + +## Context + +PR #194 (`feat: url inspector rpcs`) already added 4 PostgreSQL RPCs to mysticat-data-service: + +| RPC | Purpose | +|-----|---------| +| `rpc_url_inspector_stats` | Aggregate citation stats + weekly sparkline trends | +| `rpc_url_inspector_owned_urls` | Paginated per-URL citation aggregates with JSONB weekly arrays | +| `rpc_url_inspector_trending_urls` | Paginated non-owned URL citations with per-prompt breakdown | +| `rpc_url_inspector_cited_domains` | Domain-level citation aggregations with dominant content type | + +These RPCs leverage covering indexes (`idx_bps_site_content_date`, `idx_bps_urlid_site_date`), monthly partitioning by `execution_date`, and server-side pagination — all the optimization work is already in the DB layer. + +**What was missing:** API endpoints in spacecat-api-service to expose these RPCs to the UI. + +## Changes + +### New file: `src/controllers/llmo/llmo-url-inspector.js` + +4 handler factories that call the existing RPCs via PostgREST: + +| Handler | Route sub-path | RPC | +|---------|---------------|-----| +| `createUrlInspectorStatsHandler` | `url-inspector/stats` | `rpc_url_inspector_stats` | +| `createUrlInspectorOwnedUrlsHandler` | `url-inspector/owned-urls` | `rpc_url_inspector_owned_urls` | +| `createUrlInspectorTrendingUrlsHandler` | `url-inspector/trending-urls` | `rpc_url_inspector_trending_urls` | +| `createUrlInspectorCitedDomainsHandler` | `url-inspector/cited-domains` | `rpc_url_inspector_cited_domains` | + +### Routes (8 total) + +``` +GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/stats +GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/stats +GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/owned-urls +GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/owned-urls +GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/trending-urls +GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls +GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains +GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains +``` + +### Modified files + +- `src/controllers/llmo/llmo-brand-presence.js` — exported 5 shared utilities for reuse +- `src/controllers/llmo/llmo-mysticat-controller.js` — instantiates and exports the 4 new handlers +- `src/routes/index.js` — registers 8 new routes +- `src/routes/required-capabilities.js` — adds routes to `INTERNAL_ROUTES` + +### Tests + +- `test/controllers/llmo/llmo-url-inspector.test.js` — covers all 4 handlers + +## Key Decisions + +### 1. Route prefix: `/brand-presence/url-inspector/` (not a top-level `/url-inspector/`) + +Reuses the existing `/org/:spaceCatId/brands/:brandId/brand-presence/` prefix. This keeps the endpoints within the established auth wrapper (`withBrandPresenceAuth`), capabilities framework, and PostgREST client injection pattern. No new middleware, no new access control logic needed. + +### 2. `siteId` as a required query parameter + +The URL Inspector RPCs are site-scoped (`p_site_id`), unlike brand-presence RPCs which are organization-scoped (`p_organization_id`). Rather than creating new org-less routes, we keep the org-scoped route for access control and pass `siteId` as a required query param — consistent with how existing brand-presence endpoints already accept `siteId` via `parseFilterDimensionsParams`. + +All handlers validate that the site belongs to the organization before calling the RPC. + +### 3. Platform filter is optional with no default + +Unlike brand-presence endpoints (which default to `chatgpt-free`), URL Inspector endpoints pass `null` for platform when not provided. This shows data across all models by default, matching the existing URL Inspector UI behavior. When provided, the platform is validated against the `llm_model` enum. + +### 4. Trending URLs: server-side row grouping + +The `rpc_url_inspector_trending_urls` RPC returns flat rows (one per URL+prompt combination). The handler groups these by URL and nests prompts, so the UI receives a clean nested structure: + +```json +{ + "urls": [ + { + "url": "https://example.com", + "contentType": "earned", + "totalCitations": 55, + "prompts": [ + { "prompt": "...", "category": "...", "citationCount": 30 } + ] + } + ], + "totalNonOwnedUrls": 12345 +} +``` + +This grouping happens in the API layer (not the DB or UI) because: +- The RPC intentionally returns flat rows for flexibility and to avoid JSONB aggregation overhead +- The UI should not need to do any data transformation +- The grouping is trivial in JS and bounded by `p_limit` (max 50 URLs per page) + +### 5. Cited domains: no pagination + +`rpc_url_inspector_cited_domains` returns all domains without pagination. Domain count per site is bounded (typically hundreds to low thousands of distinct hostnames), so the response size is manageable. Can be added later via a new migration if profiling shows issues. + +### 6. Exported shared utilities from `llmo-brand-presence.js` + +Rather than duplicating `withBrandPresenceAuth`, `shouldApplyFilter`, `parseFilterDimensionsParams`, `defaultDateRange`, and `parsePaginationParams`, these were exported from the existing file. This avoids code duplication while keeping the URL Inspector handlers in a separate, focused file. + +## Data Flow + +``` +UI (url-inspector-pg) + → GET /org/:orgId/brands/all/brand-presence/url-inspector/stats?siteId=... + → spacecat-api-service: createUrlInspectorStatsHandler + → PostgREST: client.rpc('rpc_url_inspector_stats', { p_site_id, ... }) + → PostgreSQL: CTE aggregation over brand_presence_sources + brand_presence_executions + → Uses idx_bps_site_content_date covering index + → Partition pruning on execution_date + ← Returns aggregate row (week=NULL) + weekly rows + ← Handler splits into { stats, weeklyTrends } + ← JSON response + ← useUrlInspectorPgStats hook → StatsCardV2 components +``` diff --git a/src/controllers/llmo/llmo-brand-presence.js b/src/controllers/llmo/llmo-brand-presence.js index f0d57fe98..ab46548b0 100644 --- a/src/controllers/llmo/llmo-brand-presence.js +++ b/src/controllers/llmo/llmo-brand-presence.js @@ -69,7 +69,8 @@ const ERR_NOT_FOUND = 'not found'; * @param {Function} handlerFn - Async (context, client) => response. Receives PostgREST client. * @returns {Promise} */ -async function withBrandPresenceAuth(context, getOrgAndValidateAccess, handlerName, handlerFn) { +// eslint-disable-next-line max-len +export async function withBrandPresenceAuth(context, getOrgAndValidateAccess, handlerName, handlerFn) { const { log, dataAccess } = context; const { Site } = dataAccess; @@ -97,7 +98,7 @@ async function withBrandPresenceAuth(context, getOrgAndValidateAccess, handlerNa /** @internal Exported for testing null/undefined fallbacks */ export const strCompare = (a, b) => (a || '').localeCompare(b || ''); -function shouldApplyFilter(value) { +export function shouldApplyFilter(value) { if (value == null) return false; if (typeof value === 'string' && SKIP_VALUES.has(value.trim())) return false; return hasText(String(value)); @@ -153,7 +154,7 @@ function parseTopicIds(q) { return arr.filter((id) => id != null && isValidUUID(String(id))); } -function parseFilterDimensionsParams(context) { +export function parseFilterDimensionsParams(context) { const q = context.data || {}; return { startDate: q.startDate || q.start_date, @@ -171,7 +172,7 @@ function parseFilterDimensionsParams(context) { }; } -function defaultDateRange() { +export function defaultDateRange() { const end = new Date(); const start = new Date(); start.setDate(start.getDate() - 28); @@ -1134,7 +1135,7 @@ export function buildPromptDetails(rows) { }); } -function parsePaginationParams(context, { defaultPageSize = 20 } = {}) { +export function parsePaginationParams(context, { defaultPageSize = 20 } = {}) { const q = context.data || {}; return { sortBy: q.sortBy || 'name', diff --git a/src/controllers/llmo/llmo-mysticat-controller.js b/src/controllers/llmo/llmo-mysticat-controller.js index b1dc64bb3..49b203173 100644 --- a/src/controllers/llmo/llmo-mysticat-controller.js +++ b/src/controllers/llmo/llmo-mysticat-controller.js @@ -23,6 +23,12 @@ import { createShareOfVoiceHandler, createBrandPresenceStatsHandler, } from './llmo-brand-presence.js'; +import { + createUrlInspectorStatsHandler, + createUrlInspectorOwnedUrlsHandler, + createUrlInspectorTrendingUrlsHandler, + createUrlInspectorCitedDomainsHandler, +} from './llmo-url-inspector.js'; /** * Controller for LLMO + Mysticat (mysticat-data-service / PostgreSQL) endpoints. @@ -58,6 +64,14 @@ function LlmoMysticatController(ctx) { const getSentimentMovers = createSentimentMoversHandler(getOrgAndValidateAccess); const getShareOfVoice = createShareOfVoiceHandler(getOrgAndValidateAccess); const getBrandPresenceStats = createBrandPresenceStatsHandler(getOrgAndValidateAccess); + const getUrlInspectorStats = createUrlInspectorStatsHandler(getOrgAndValidateAccess); + const getUrlInspectorOwnedUrls = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess); + const getUrlInspectorTrendingUrls = createUrlInspectorTrendingUrlsHandler( + getOrgAndValidateAccess, + ); + const getUrlInspectorCitedDomains = createUrlInspectorCitedDomainsHandler( + getOrgAndValidateAccess, + ); return { getFilterDimensions, @@ -72,6 +86,10 @@ function LlmoMysticatController(ctx) { getSentimentMovers, getShareOfVoice, getBrandPresenceStats, + getUrlInspectorStats, + getUrlInspectorOwnedUrls, + getUrlInspectorTrendingUrls, + getUrlInspectorCitedDomains, }; } diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js new file mode 100644 index 000000000..15b0ae139 --- /dev/null +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -0,0 +1,346 @@ +/* + * Copyright 2026 Adobe. All rights reserved. + * This file is licensed to you under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. You may obtain a copy + * of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under + * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS + * OF ANY KIND, either express or implied. See the License for the specific language + * governing permissions and limitations under the License. + */ + +import { ok, badRequest, forbidden } from '@adobe/spacecat-shared-http-utils'; + +import { + withBrandPresenceAuth, + shouldApplyFilter, + parseFilterDimensionsParams, + defaultDateRange, + parsePaginationParams, + validateSiteBelongsToOrg, + validateModel, +} from './llmo-brand-presence.js'; + +/** + * URL Inspector handlers for org-based routes. + * Queries mysticat-data-service PostgreSQL via PostgREST RPCs. + * + * All RPCs are site-scoped (p_site_id), so siteId is required. + * Platform is optional — when absent, no model filter is applied (unlike brand-presence + * endpoints which default to chatgpt-free). + */ + +/** + * Resolve platform/model from request. Returns null when absent (no default model). + * When provided, validates against the llm_model enum. + * @returns {{ model: string|null, error?: string }} + */ +function resolveUrlInspectorPlatform(params) { + if (!shouldApplyFilter(params.model)) return { model: null }; + const result = validateModel(params.model); + if (!result.valid) return { model: null, error: result.error }; + return { model: result.model }; +} + +/** + * Creates the getUrlInspectorStats handler. + * Aggregate citation statistics and weekly sparkline trends. + * Returns an aggregate stats object plus per-week breakdown rows. + * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } + */ +export function createUrlInspectorStatsHandler(getOrgAndValidateAccess) { + return (context) => withBrandPresenceAuth( + context, + getOrgAndValidateAccess, + 'url-inspector-stats', + async (ctx, client) => { + const { spaceCatId, brandId } = ctx.params; + const params = parseFilterDimensionsParams(ctx); + const defaults = defaultDateRange(); + + if (!shouldApplyFilter(params.siteId)) { + return badRequest('siteId is required for URL Inspector endpoints'); + } + + const siteBelongsToOrg = await validateSiteBelongsToOrg( + client, + spaceCatId, + params.siteId, + ); + if (!siteBelongsToOrg) { + return forbidden('Site does not belong to the organization'); + } + + const { model, error: modelError } = resolveUrlInspectorPlatform(params); + if (modelError) return badRequest(modelError); + + const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; + + const { data, error } = await client.rpc('rpc_url_inspector_stats', { + p_site_id: params.siteId, + p_start_date: params.startDate || defaults.startDate, + p_end_date: params.endDate || defaults.endDate, + p_category: shouldApplyFilter(params.categoryId) ? params.categoryId : null, + p_region: shouldApplyFilter(params.regionCode) ? params.regionCode : null, + p_platform: model, + p_brand_id: filterByBrandId, + }); + + if (error) { + ctx.log.error(`URL Inspector stats RPC error: ${error.message}`); + return badRequest(error.message); + } + + const rows = data || []; + const aggregateRow = rows.find((r) => r.week == null); + const weeklyRows = rows.filter((r) => r.week != null); + + const stats = { + totalPromptsCited: Number(aggregateRow?.total_prompts_cited ?? 0), + totalPrompts: Number(aggregateRow?.total_prompts ?? 0), + uniqueUrls: Number(aggregateRow?.unique_urls ?? 0), + totalCitations: Number(aggregateRow?.total_citations ?? 0), + }; + + const weeklyTrends = weeklyRows.map((r) => ({ + week: r.week, + totalPromptsCited: Number(r.total_prompts_cited ?? 0), + totalPrompts: Number(r.total_prompts ?? 0), + uniqueUrls: Number(r.unique_urls ?? 0), + totalCitations: Number(r.total_citations ?? 0), + })); + + return ok({ stats, weeklyTrends }); + }, + ); +} + +/** + * Creates the getUrlInspectorOwnedUrls handler. + * Paginated per-URL citation aggregates with JSONB weekly arrays for WoW trends. + * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } + */ +export function createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess) { + return (context) => withBrandPresenceAuth( + context, + getOrgAndValidateAccess, + 'url-inspector-owned-urls', + async (ctx, client) => { + const { spaceCatId, brandId } = ctx.params; + const params = parseFilterDimensionsParams(ctx); + const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); + const defaults = defaultDateRange(); + + if (!shouldApplyFilter(params.siteId)) { + return badRequest('siteId is required for URL Inspector endpoints'); + } + + const siteBelongsToOrg = await validateSiteBelongsToOrg( + client, + spaceCatId, + params.siteId, + ); + if (!siteBelongsToOrg) { + return forbidden('Site does not belong to the organization'); + } + + const { model, error: modelError } = resolveUrlInspectorPlatform(params); + if (modelError) return badRequest(modelError); + + const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; + const offset = pagination.page * pagination.pageSize; + + const { data, error } = await client.rpc('rpc_url_inspector_owned_urls', { + p_site_id: params.siteId, + p_start_date: params.startDate || defaults.startDate, + p_end_date: params.endDate || defaults.endDate, + p_category: shouldApplyFilter(params.categoryId) ? params.categoryId : null, + p_region: shouldApplyFilter(params.regionCode) ? params.regionCode : null, + p_platform: model, + p_brand_id: filterByBrandId, + p_limit: pagination.pageSize, + p_offset: offset, + }); + + if (error) { + ctx.log.error(`URL Inspector owned URLs RPC error: ${error.message}`); + return badRequest(error.message); + } + + const rows = data || []; + const totalCount = rows.length > 0 ? Number(rows[0].total_count ?? 0) : 0; + + const urls = rows.map((r) => ({ + url: r.url, + citations: Number(r.citations ?? 0), + promptsCited: Number(r.prompts_cited ?? 0), + products: r.products || [], + regions: r.regions || [], + weeklyCitations: r.weekly_citations || [], + weeklyPromptsCited: r.weekly_prompts_cited || [], + })); + + return ok({ urls, totalCount }); + }, + ); +} + +/** + * Creates the getUrlInspectorTrendingUrls handler. + * Paginated non-owned URL citations with per-prompt breakdown. + * The RPC returns flat rows (one per URL+prompt); this handler groups them by URL. + * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } + */ +export function createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess) { + return (context) => withBrandPresenceAuth( + context, + getOrgAndValidateAccess, + 'url-inspector-trending-urls', + async (ctx, client) => { + const { spaceCatId, brandId } = ctx.params; + const params = parseFilterDimensionsParams(ctx); + const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); + const defaults = defaultDateRange(); + const q = ctx.data || {}; + + if (!shouldApplyFilter(params.siteId)) { + return badRequest('siteId is required for URL Inspector endpoints'); + } + + const siteBelongsToOrg = await validateSiteBelongsToOrg( + client, + spaceCatId, + params.siteId, + ); + if (!siteBelongsToOrg) { + return forbidden('Site does not belong to the organization'); + } + + const { model, error: modelError } = resolveUrlInspectorPlatform(params); + if (modelError) return badRequest(modelError); + + const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; + const channel = q.channel || q.selectedChannel; + const offset = pagination.page * pagination.pageSize; + + const { data, error } = await client.rpc('rpc_url_inspector_trending_urls', { + p_site_id: params.siteId, + p_start_date: params.startDate || defaults.startDate, + p_end_date: params.endDate || defaults.endDate, + p_category: shouldApplyFilter(params.categoryId) ? params.categoryId : null, + p_region: shouldApplyFilter(params.regionCode) ? params.regionCode : null, + p_channel: shouldApplyFilter(channel) ? channel : null, + p_platform: model, + p_limit: pagination.pageSize, + p_brand_id: filterByBrandId, + p_offset: offset, + }); + + if (error) { + ctx.log.error(`URL Inspector trending URLs RPC error: ${error.message}`); + return badRequest(error.message); + } + + const rows = data || []; + const totalNonOwnedUrls = rows.length > 0 + ? Number(rows[0].total_non_owned_urls ?? 0) : 0; + + // Group flat rows by URL, nesting prompts under each URL + const urlMap = new Map(); + for (const row of rows) { + if (!urlMap.has(row.url)) { + urlMap.set(row.url, { + url: row.url, + contentType: row.content_type || '', + prompts: [], + }); + } + urlMap.get(row.url).prompts.push({ + prompt: row.prompt || '', + category: row.category || '', + region: row.region || '', + topics: row.topics || '', + citationCount: Number(row.citation_count ?? 0), + executionCount: Number(row.execution_count ?? 0), + }); + } + + // Calculate totalCitations per URL from its prompts + const urls = Array.from(urlMap.values()).map((entry) => ({ + ...entry, + totalCitations: entry.prompts.reduce((sum, p) => sum + p.citationCount, 0), + })); + + return ok({ urls, totalNonOwnedUrls }); + }, + ); +} + +/** + * Creates the getUrlInspectorCitedDomains handler. + * Domain-level citation aggregations with dominant content type. + * No pagination — domain count per site is bounded (hundreds to low thousands). + * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } + */ +export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { + return (context) => withBrandPresenceAuth( + context, + getOrgAndValidateAccess, + 'url-inspector-cited-domains', + async (ctx, client) => { + const { spaceCatId, brandId } = ctx.params; + const params = parseFilterDimensionsParams(ctx); + const defaults = defaultDateRange(); + const q = ctx.data || {}; + + if (!shouldApplyFilter(params.siteId)) { + return badRequest('siteId is required for URL Inspector endpoints'); + } + + const siteBelongsToOrg = await validateSiteBelongsToOrg( + client, + spaceCatId, + params.siteId, + ); + if (!siteBelongsToOrg) { + return forbidden('Site does not belong to the organization'); + } + + const { model, error: modelError } = resolveUrlInspectorPlatform(params); + if (modelError) return badRequest(modelError); + + const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; + const channel = q.channel || q.selectedChannel; + + const { data, error } = await client.rpc('rpc_url_inspector_cited_domains', { + p_site_id: params.siteId, + p_start_date: params.startDate || defaults.startDate, + p_end_date: params.endDate || defaults.endDate, + p_category: shouldApplyFilter(params.categoryId) ? params.categoryId : null, + p_region: shouldApplyFilter(params.regionCode) ? params.regionCode : null, + p_channel: shouldApplyFilter(channel) ? channel : null, + p_platform: model, + p_brand_id: filterByBrandId, + }); + + if (error) { + ctx.log.error(`URL Inspector cited domains RPC error: ${error.message}`); + return badRequest(error.message); + } + + const rows = data || []; + const domains = rows.map((r) => ({ + domain: r.domain || '', + totalCitations: Number(r.total_citations ?? 0), + totalUrls: Number(r.total_urls ?? 0), + promptsCited: Number(r.prompts_cited ?? 0), + contentType: r.content_type || '', + categories: r.categories || '', + regions: r.regions || '', + })); + + return ok({ domains }); + }, + ); +} diff --git a/src/routes/index.js b/src/routes/index.js index d33c29c5f..583063c2a 100644 --- a/src/routes/index.js +++ b/src/routes/index.js @@ -438,6 +438,16 @@ export default function getRouteHandlers( 'GET /org/:spaceCatId/brands/all/brand-presence/stats': llmoMysticatController.getBrandPresenceStats, 'GET /org/:spaceCatId/brands/:brandId/brand-presence/stats': llmoMysticatController.getBrandPresenceStats, + // URL Inspector (org-level, site-scoped via query param) + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/stats': llmoMysticatController.getUrlInspectorStats, + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/stats': llmoMysticatController.getUrlInspectorStats, + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/owned-urls': llmoMysticatController.getUrlInspectorOwnedUrls, + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/owned-urls': llmoMysticatController.getUrlInspectorOwnedUrls, + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/trending-urls': llmoMysticatController.getUrlInspectorTrendingUrls, + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls': llmoMysticatController.getUrlInspectorTrendingUrls, + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains': llmoMysticatController.getUrlInspectorCitedDomains, + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains': llmoMysticatController.getUrlInspectorCitedDomains, + // LLMO Opportunities (org-level) 'GET /org/:spaceCatId/opportunities/count': llmoOpportunitiesController.getOpportunityCount, 'GET /org/:spaceCatId/brands/all/opportunities': llmoOpportunitiesController.getBrandOpportunities, diff --git a/src/routes/required-capabilities.js b/src/routes/required-capabilities.js index 935cf2334..76d3455a9 100644 --- a/src/routes/required-capabilities.js +++ b/src/routes/required-capabilities.js @@ -51,6 +51,16 @@ export const INTERNAL_ROUTES = [ 'GET /org/:spaceCatId/brands/all/brand-presence/stats', 'GET /org/:spaceCatId/brands/:brandId/brand-presence/stats', + // URL Inspector - org-scoped, site-filtered; LLMO product, not yet required by S2S consumers + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/stats', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/stats', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/owned-urls', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/owned-urls', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/trending-urls', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains', + // LLMO Opportunities - org-scoped, LLMO product; not yet required by S2S consumers 'GET /org/:spaceCatId/opportunities/count', 'GET /org/:spaceCatId/brands/all/opportunities', diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js new file mode 100644 index 000000000..a75ed053d --- /dev/null +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -0,0 +1,458 @@ +/* + * Copyright 2026 Adobe. All rights reserved. + * This file is licensed to you under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. You may obtain a copy + * of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under + * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS + * OF ANY KIND, either express or implied. See the License for the specific language + * governing permissions and limitations under the License. + */ + +/* eslint-env mocha */ +import { expect, use } from 'chai'; +import sinon from 'sinon'; +import sinonChai from 'sinon-chai'; +import { + createUrlInspectorStatsHandler, + createUrlInspectorOwnedUrlsHandler, + createUrlInspectorTrendingUrlsHandler, + createUrlInspectorCitedDomainsHandler, +} from '../../../src/controllers/llmo/llmo-url-inspector.js'; + +use(sinonChai); + +const ORG_ID = '11111111-1111-1111-1111-111111111111'; +const SITE_ID = '22222222-2222-2222-2222-222222222222'; +const BRAND_ID = '33333333-3333-3333-3333-333333333333'; + +function createRpcMock(rpcResults = {}, defaultResult = { data: [], error: null }) { + const rpcStub = sinon.stub().callsFake((fnName, params) => { + const result = typeof rpcResults[fnName] === 'function' + ? rpcResults[fnName](params) + : (rpcResults[fnName] ?? defaultResult); + return Promise.resolve(result); + }); + + // validateSiteBelongsToOrg uses .from().select().eq().eq().limit() + const limitStub = sinon.stub().resolves({ data: [{ id: SITE_ID }], error: null }); + const client = { + rpc: rpcStub, + from: sinon.stub().returns({ + select: sinon.stub().returns({ + eq: sinon.stub().returns({ + eq: sinon.stub().returns({ + limit: limitStub, + }), + }), + }), + }), + }; + + return { client, rpcStub, limitStub }; +} + +function createContext(params = {}, data = {}, overrides = {}) { + const { client, rpcStub, limitStub } = createRpcMock(overrides.rpcResults); + return { + context: { + params: { spaceCatId: ORG_ID, brandId: 'all', ...params }, + data: { siteId: SITE_ID, ...data }, + log: { error: sinon.stub(), info: sinon.stub(), warn: sinon.stub() }, + dataAccess: { + Site: { postgrestService: client }, + Organization: { + findById: sinon.stub().resolves({ + getId: () => ORG_ID, + getImsOrgId: () => 'ims-org', + }), + }, + }, + }, + client, + rpcStub, + limitStub, + }; +} + +function getOrgAndValidateAccess() { + return async () => ({ organization: { getId: () => ORG_ID } }); +} + +describe('URL Inspector Handlers', () => { + afterEach(() => { + sinon.restore(); + }); + + describe('createUrlInspectorStatsHandler', () => { + it('returns stats and weekly trends on success', async () => { + const rpcData = [ + { + week: null, + total_prompts_cited: 10, + total_prompts: 50, + unique_urls: 5, + total_citations: 100, + }, + { + week: '2026-W10', total_prompts_cited: 4, total_prompts: 20, unique_urls: 3, total_citations: 40, + }, + { + week: '2026-W11', total_prompts_cited: 6, total_prompts: 30, unique_urls: 4, total_citations: 60, + }, + ]; + + const { context, rpcStub } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_stats: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = response.body ? JSON.parse(response.body) : response; + + expect(response.status).to.equal(200); + expect(body.stats.totalPromptsCited).to.equal(10); + expect(body.stats.totalPrompts).to.equal(50); + expect(body.stats.uniqueUrls).to.equal(5); + expect(body.stats.totalCitations).to.equal(100); + expect(body.weeklyTrends).to.have.length(2); + expect(body.weeklyTrends[0].week).to.equal('2026-W10'); + expect(rpcStub).to.have.been.calledWith('rpc_url_inspector_stats'); + }); + + it('returns badRequest when siteId is missing', async () => { + const { context } = createContext({}, { siteId: undefined }); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns forbidden when site does not belong to org', async () => { + const { context, limitStub } = createContext(); + limitStub.resolves({ data: [], error: null }); // site not found in org + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(403); + }); + + it('returns badRequest on RPC error', async () => { + const { context } = createContext({}, {}, { + rpcResults: { + rpc_url_inspector_stats: { data: null, error: { message: 'RPC failed' } }, + }, + }); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns empty stats when RPC returns empty data', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_stats: { data: [], error: null } }, + }); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(response.status).to.equal(200); + expect(body.stats.totalPromptsCited).to.equal(0); + expect(body.weeklyTrends).to.have.length(0); + }); + + it('passes brandId filter when brandId is not "all"', async () => { + const { context, rpcStub } = createContext( + { brandId: BRAND_ID }, + {}, + { rpcResults: { rpc_url_inspector_stats: { data: [], error: null } } }, + ); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + await handler(context); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); + }); + + it('passes null for platform when not provided', async () => { + const { context, rpcStub } = createContext( + {}, + {}, + { rpcResults: { rpc_url_inspector_stats: { data: [], error: null } } }, + ); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + await handler(context); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_platform).to.equal(null); + }); + }); + + describe('createUrlInspectorOwnedUrlsHandler', () => { + it('returns paginated owned URLs', async () => { + const rpcData = [ + { + url: 'https://example.com/page1', + citations: 42, + prompts_cited: 12, + products: ['Category A'], + regions: ['US', 'DE'], + weekly_citations: [{ week: '2026-W10', value: 20 }], + weekly_prompts_cited: [{ week: '2026-W10', value: 5 }], + total_count: 100, + }, + { + url: 'https://example.com/page2', + citations: 30, + prompts_cited: 8, + products: ['Category B'], + regions: ['US'], + weekly_citations: [{ week: '2026-W10', value: 15 }], + weekly_prompts_cited: [{ week: '2026-W10', value: 4 }], + total_count: 100, + }, + ]; + + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_owned_urls: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(2); + expect(body.totalCount).to.equal(100); + expect(body.urls[0].url).to.equal('https://example.com/page1'); + expect(body.urls[0].citations).to.equal(42); + expect(body.urls[0].weeklyCitations).to.deep.equal([{ week: '2026-W10', value: 20 }]); + }); + + it('returns empty result when no data', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_owned_urls: { data: [], error: null } }, + }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(0); + expect(body.totalCount).to.equal(0); + }); + + it('passes pagination params to RPC', async () => { + const { context, rpcStub } = createContext( + {}, + { page: '2', pageSize: '25' }, + { rpcResults: { rpc_url_inspector_owned_urls: { data: [], error: null } } }, + ); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + await handler(context); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_limit).to.equal(25); + expect(rpcCall.args[1].p_offset).to.equal(50); // page 2 * pageSize 25 + }); + }); + + describe('createUrlInspectorTrendingUrlsHandler', () => { + it('groups flat rows by URL with nested prompts', async () => { + const rpcData = [ + { + total_non_owned_urls: 500, + url: 'https://competitor.com/a', + content_type: 'earned', + prompt: 'What is X?', + category: 'Category A', + region: 'US', + topics: 'Topic 1', + citation_count: 30, + execution_count: 5, + }, + { + total_non_owned_urls: 500, + url: 'https://competitor.com/a', + content_type: 'earned', + prompt: 'How does Y work?', + category: 'Category A', + region: 'DE', + topics: 'Topic 2', + citation_count: 25, + execution_count: 3, + }, + { + total_non_owned_urls: 500, + url: 'https://other.com/b', + content_type: 'social', + prompt: 'What is Z?', + category: 'Category B', + region: 'US', + topics: 'Topic 1', + citation_count: 10, + execution_count: 2, + }, + ]; + + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_trending_urls: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(response.status).to.equal(200); + expect(body.totalNonOwnedUrls).to.equal(500); + expect(body.urls).to.have.length(2); + + // First URL: competitor.com/a has 2 prompts + const url1 = body.urls.find((u) => u.url === 'https://competitor.com/a'); + expect(url1.contentType).to.equal('earned'); + expect(url1.prompts).to.have.length(2); + expect(url1.totalCitations).to.equal(55); // 30 + 25 + expect(url1.prompts[0].prompt).to.equal('What is X?'); + expect(url1.prompts[1].prompt).to.equal('How does Y work?'); + + // Second URL: other.com/b has 1 prompt + const url2 = body.urls.find((u) => u.url === 'https://other.com/b'); + expect(url2.contentType).to.equal('social'); + expect(url2.prompts).to.have.length(1); + expect(url2.totalCitations).to.equal(10); + }); + + it('handles single URL with single prompt', async () => { + const rpcData = [ + { + total_non_owned_urls: 1, + url: 'https://example.com', + content_type: 'competitor', + prompt: 'Test prompt', + category: 'Cat', + region: 'US', + topics: 'Topic', + citation_count: 5, + execution_count: 1, + }, + ]; + + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_trending_urls: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(body.urls).to.have.length(1); + expect(body.urls[0].prompts).to.have.length(1); + expect(body.urls[0].totalCitations).to.equal(5); + }); + + it('returns empty when no data', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_trending_urls: { data: [], error: null } }, + }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(0); + expect(body.totalNonOwnedUrls).to.equal(0); + }); + + it('passes channel filter to RPC', async () => { + const { context, rpcStub } = createContext( + {}, + { channel: 'earned' }, + { rpcResults: { rpc_url_inspector_trending_urls: { data: [], error: null } } }, + ); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + await handler(context); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_channel).to.equal('earned'); + }); + }); + + describe('createUrlInspectorCitedDomainsHandler', () => { + it('returns cited domains', async () => { + const rpcData = [ + { + domain: 'example.com', + total_citations: 100, + total_urls: 25, + prompts_cited: 15, + content_type: 'earned', + categories: 'Cat A,Cat B', + regions: 'US,DE', + }, + { + domain: 'other.com', + total_citations: 50, + total_urls: 10, + prompts_cited: 8, + content_type: 'social', + categories: 'Cat A', + regions: 'US', + }, + ]; + + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_cited_domains: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = JSON.parse(response.body); + + expect(response.status).to.equal(200); + expect(body.domains).to.have.length(2); + expect(body.domains[0].domain).to.equal('example.com'); + expect(body.domains[0].totalCitations).to.equal(100); + expect(body.domains[0].contentType).to.equal('earned'); + }); + + it('returns badRequest when siteId is missing', async () => { + const { context } = createContext({}, { siteId: undefined }); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest when PostgREST is not available', async () => { + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + + const context = { + params: { spaceCatId: ORG_ID, brandId: 'all' }, + data: { siteId: SITE_ID }, + log: { error: sinon.stub() }, + dataAccess: { + Site: { postgrestService: null }, + Organization: { + findById: sinon.stub().resolves({ getId: () => ORG_ID }), + }, + }, + }; + + const response = await handler(context); + expect(response.status).to.equal(400); + }); + }); +}); From a2548dd14f3ceae1c593fa5e80e6a62789f9d149 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Wed, 15 Apr 2026 14:30:51 +0200 Subject: [PATCH 02/16] feat: add domain URL drilldown and URL prompt breakdown endpoints - LLMO-4030 --- .../llmo/llmo-mysticat-controller.js | 10 ++ src/controllers/llmo/llmo-url-inspector.js | 140 ++++++++++++++++++ src/routes/index.js | 4 + src/routes/required-capabilities.js | 4 + .../llmo/llmo-url-inspector.test.js | 22 ++- test/routes/index.test.js | 8 + 6 files changed, 180 insertions(+), 8 deletions(-) diff --git a/src/controllers/llmo/llmo-mysticat-controller.js b/src/controllers/llmo/llmo-mysticat-controller.js index 49b203173..6883f2efd 100644 --- a/src/controllers/llmo/llmo-mysticat-controller.js +++ b/src/controllers/llmo/llmo-mysticat-controller.js @@ -28,6 +28,8 @@ import { createUrlInspectorOwnedUrlsHandler, createUrlInspectorTrendingUrlsHandler, createUrlInspectorCitedDomainsHandler, + createUrlInspectorDomainUrlsHandler, + createUrlInspectorUrlPromptsHandler, } from './llmo-url-inspector.js'; /** @@ -72,6 +74,12 @@ function LlmoMysticatController(ctx) { const getUrlInspectorCitedDomains = createUrlInspectorCitedDomainsHandler( getOrgAndValidateAccess, ); + const getUrlInspectorDomainUrls = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess, + ); + const getUrlInspectorUrlPrompts = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess, + ); return { getFilterDimensions, @@ -90,6 +98,8 @@ function LlmoMysticatController(ctx) { getUrlInspectorOwnedUrls, getUrlInspectorTrendingUrls, getUrlInspectorCitedDomains, + getUrlInspectorDomainUrls, + getUrlInspectorUrlPrompts, }; } diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index 15b0ae139..de66bd37c 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -344,3 +344,143 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { }, ); } + +/** + * Creates the getUrlInspectorDomainUrls handler. + * Phase 2 drilldown: paginated URLs within a specific domain. + * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } + */ +export function createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess, +) { + return (context) => withBrandPresenceAuth( + context, + getOrgAndValidateAccess, + 'url-inspector-domain-urls', + async (ctx, client) => { + const { spaceCatId } = ctx.params; + const params = parseFilterDimensionsParams(ctx); + const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); + const defaults = defaultDateRange(); + const q = ctx.data || {}; + + if (!shouldApplyFilter(params.siteId)) { + return badRequest('siteId is required for URL Inspector endpoints'); + } + + const hostname = q.hostname || q.domain; + if (!hostname) { + return badRequest('hostname is required for domain URL drilldown'); + } + + const siteBelongsToOrg = await validateSiteBelongsToOrg( + client, + spaceCatId, + params.siteId, + ); + if (!siteBelongsToOrg) { + return forbidden('Site does not belong to the organization'); + } + + const { model, error: modelError } = resolveUrlInspectorPlatform(params); + if (modelError) return badRequest(modelError); + + const channel = q.channel || q.selectedChannel; + const offset = pagination.page * pagination.pageSize; + + const { data, error } = await client.rpc('rpc_url_inspector_domain_urls', { + p_site_id: params.siteId, + p_start_date: params.startDate || defaults.startDate, + p_end_date: params.endDate || defaults.endDate, + p_hostname: hostname, + p_channel: shouldApplyFilter(channel) ? channel : null, + p_platform: model, + p_limit: pagination.pageSize, + p_offset: offset, + }); + + if (error) { + ctx.log.error(`URL Inspector domain URLs RPC error: ${error.message}`); + return badRequest(error.message); + } + + const rows = data || []; + const totalCount = rows.length > 0 + ? Number(rows[0].total_count ?? 0) : 0; + + const urls = rows.map((r) => ({ + url: r.url || '', + contentType: r.content_type || '', + citations: Number(r.citations ?? 0), + })); + + return ok({ urls, totalCount }); + }, + ); +} + +/** + * Creates the getUrlInspectorUrlPrompts handler. + * Phase 3 drilldown: prompts that cited a specific URL. + * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } + */ +export function createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess, +) { + return (context) => withBrandPresenceAuth( + context, + getOrgAndValidateAccess, + 'url-inspector-url-prompts', + async (ctx, client) => { + const { spaceCatId } = ctx.params; + const params = parseFilterDimensionsParams(ctx); + const defaults = defaultDateRange(); + const q = ctx.data || {}; + + if (!shouldApplyFilter(params.siteId)) { + return badRequest('siteId is required for URL Inspector endpoints'); + } + + const urlId = q.urlId || q.url_id; + if (!urlId) { + return badRequest('urlId is required for URL prompt breakdown'); + } + + const siteBelongsToOrg = await validateSiteBelongsToOrg( + client, + spaceCatId, + params.siteId, + ); + if (!siteBelongsToOrg) { + return forbidden('Site does not belong to the organization'); + } + + const { model, error: modelError } = resolveUrlInspectorPlatform(params); + if (modelError) return badRequest(modelError); + + const { data, error } = await client.rpc('rpc_url_inspector_url_prompts', { + p_site_id: params.siteId, + p_start_date: params.startDate || defaults.startDate, + p_end_date: params.endDate || defaults.endDate, + p_url_id: urlId, + p_platform: model, + }); + + if (error) { + ctx.log.error(`URL Inspector URL prompts RPC error: ${error.message}`); + return badRequest(error.message); + } + + const rows = data || []; + const prompts = rows.map((r) => ({ + prompt: r.prompt || '', + category: r.category || '', + region: r.region || '', + topics: r.topics || '', + citations: Number(r.citations ?? 0), + })); + + return ok({ prompts }); + }, + ); +} diff --git a/src/routes/index.js b/src/routes/index.js index 583063c2a..39071434b 100644 --- a/src/routes/index.js +++ b/src/routes/index.js @@ -447,6 +447,10 @@ export default function getRouteHandlers( 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls': llmoMysticatController.getUrlInspectorTrendingUrls, 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains': llmoMysticatController.getUrlInspectorCitedDomains, 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains': llmoMysticatController.getUrlInspectorCitedDomains, + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/domain-urls': llmoMysticatController.getUrlInspectorDomainUrls, + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/domain-urls': llmoMysticatController.getUrlInspectorDomainUrls, + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/url-prompts': llmoMysticatController.getUrlInspectorUrlPrompts, + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/url-prompts': llmoMysticatController.getUrlInspectorUrlPrompts, // LLMO Opportunities (org-level) 'GET /org/:spaceCatId/opportunities/count': llmoOpportunitiesController.getOpportunityCount, diff --git a/src/routes/required-capabilities.js b/src/routes/required-capabilities.js index 76d3455a9..c947a4ac6 100644 --- a/src/routes/required-capabilities.js +++ b/src/routes/required-capabilities.js @@ -60,6 +60,10 @@ export const INTERNAL_ROUTES = [ 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls', 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains', 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/domain-urls', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/domain-urls', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/url-prompts', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/url-prompts', // LLMO Opportunities - org-scoped, LLMO product; not yet required by S2S consumers 'GET /org/:spaceCatId/opportunities/count', diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index a75ed053d..f68d4edd4 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -24,6 +24,12 @@ import { use(sinonChai); const ORG_ID = '11111111-1111-1111-1111-111111111111'; + +/** Parse response body whether it's a JSON string or already an object. */ +function parseBody(response) { + if (typeof response.body === 'string') return JSON.parse(response.body); + return response.body; +} const SITE_ID = '22222222-2222-2222-2222-222222222222'; const BRAND_ID = '33333333-3333-3333-3333-333333333333'; @@ -109,7 +115,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = response.body ? JSON.parse(response.body) : response; + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.stats.totalPromptsCited).to.equal(10); @@ -160,7 +166,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.stats.totalPromptsCited).to.equal(0); @@ -227,7 +233,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.urls).to.have.length(2); @@ -244,7 +250,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.urls).to.have.length(0); @@ -311,7 +317,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.totalNonOwnedUrls).to.equal(500); @@ -353,7 +359,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(body.urls).to.have.length(1); expect(body.urls[0].prompts).to.have.length(1); @@ -367,7 +373,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.urls).to.have.length(0); @@ -418,7 +424,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = JSON.parse(response.body); + const body = parseBody(response); expect(response.status).to.equal(200); expect(body.domains).to.have.length(2); diff --git a/test/routes/index.test.js b/test/routes/index.test.js index 8027117eb..b00bd8cad 100755 --- a/test/routes/index.test.js +++ b/test/routes/index.test.js @@ -558,6 +558,14 @@ describe('getRouteHandlers', () => { 'GET /org/:spaceCatId/brands/:brandId/brand-presence/share-of-voice', 'GET /org/:spaceCatId/brands/all/brand-presence/stats', 'GET /org/:spaceCatId/brands/:brandId/brand-presence/stats', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/stats', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/stats', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/owned-urls', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/owned-urls', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/trending-urls', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains', 'GET /org/:spaceCatId/opportunities/count', 'GET /org/:spaceCatId/brands/all/opportunities', 'GET /org/:spaceCatId/brands/:brandId/opportunities', From d1ab5e4d07025ff97b4535811f63915874eaf2c8 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Wed, 15 Apr 2026 15:29:32 +0200 Subject: [PATCH 03/16] feat: add pagination to cited-domains handler - LLMO-4030 --- src/controllers/llmo/llmo-url-inspector.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index de66bd37c..28f9a4c9d 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -291,6 +291,7 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { async (ctx, client) => { const { spaceCatId, brandId } = ctx.params; const params = parseFilterDimensionsParams(ctx); + const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); const defaults = defaultDateRange(); const q = ctx.data || {}; @@ -312,6 +313,7 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; const channel = q.channel || q.selectedChannel; + const offset = pagination.page * pagination.pageSize; const { data, error } = await client.rpc('rpc_url_inspector_cited_domains', { p_site_id: params.siteId, @@ -322,6 +324,8 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { p_channel: shouldApplyFilter(channel) ? channel : null, p_platform: model, p_brand_id: filterByBrandId, + p_limit: pagination.pageSize, + p_offset: offset, }); if (error) { @@ -330,6 +334,8 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { } const rows = data || []; + const totalCount = rows.length > 0 + ? Number(rows[0].total_count ?? 0) : 0; const domains = rows.map((r) => ({ domain: r.domain || '', totalCitations: Number(r.total_citations ?? 0), @@ -340,7 +346,7 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { regions: r.regions || '', })); - return ok({ domains }); + return ok({ domains, totalCount }); }, ); } From b2eaeed09d1d07939cd13da55e68b6a715759798 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Wed, 15 Apr 2026 16:13:06 +0200 Subject: [PATCH 04/16] fix: review --- .../llmo/llmo-url-inspector.test.js | 202 ++++++++++++++++++ test/routes/index.test.js | 4 + 2 files changed, 206 insertions(+) diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index f68d4edd4..410ee46a8 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -19,6 +19,8 @@ import { createUrlInspectorOwnedUrlsHandler, createUrlInspectorTrendingUrlsHandler, createUrlInspectorCitedDomainsHandler, + createUrlInspectorDomainUrlsHandler, + createUrlInspectorUrlPromptsHandler, } from '../../../src/controllers/llmo/llmo-url-inspector.js'; use(sinonChai); @@ -461,4 +463,204 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(400); }); }); + + describe('createUrlInspectorDomainUrlsHandler', () => { + it('returns paginated URLs for a domain', async () => { + const rpcData = [ + { + url: 'https://example.com/page1', + content_type: 'earned', + citations: 42, + total_count: 100, + }, + { + url: 'https://example.com/page2', + content_type: 'earned', + citations: 30, + total_count: 100, + }, + ]; + + const { context } = createContext( + {}, + { hostname: 'example.com' }, + { + rpcResults: { + rpc_url_inspector_domain_urls: { + data: rpcData, + error: null, + }, + }, + }, + ); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + const body = parseBody(response); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(2); + expect(body.totalCount).to.equal(100); + expect(body.urls[0].url).to.equal('https://example.com/page1'); + expect(body.urls[0].citations).to.equal(42); + }); + + it('returns badRequest when hostname is missing', async () => { + const { context } = createContext({}, { hostname: undefined }); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest when siteId is missing', async () => { + const { context } = createContext( + {}, + { siteId: undefined, hostname: 'example.com' }, + ); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns forbidden when site not in org', async () => { + const { context, limitStub } = createContext( + {}, + { hostname: 'example.com' }, + ); + limitStub.resolves({ data: [], error: null }); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(403); + }); + + it('returns badRequest on RPC error', async () => { + const { context } = createContext( + {}, + { hostname: 'example.com' }, + { + rpcResults: { + rpc_url_inspector_domain_urls: { + data: null, + error: { message: 'RPC failed' }, + }, + }, + }, + ); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + }); + + describe('createUrlInspectorUrlPromptsHandler', () => { + it('returns prompt breakdown for a URL', async () => { + const rpcData = [ + { + prompt: 'What is X?', + category: 'Cat A', + region: 'US', + topics: 'Topic 1', + citations: 15, + }, + { + prompt: 'How does Y work?', + category: 'Cat B', + region: 'DE', + topics: 'Topic 2', + citations: 8, + }, + ]; + + const urlId = '44444444-4444-4444-4444-444444444444'; + const { context } = createContext( + {}, + { urlId }, + { + rpcResults: { + rpc_url_inspector_url_prompts: { + data: rpcData, + error: null, + }, + }, + }, + ); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + const body = parseBody(response); + + expect(response.status).to.equal(200); + expect(body.prompts).to.have.length(2); + expect(body.prompts[0].prompt).to.equal('What is X?'); + expect(body.prompts[0].citations).to.equal(15); + }); + + it('returns badRequest when urlId is missing', async () => { + const { context } = createContext({}, { urlId: undefined }); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns forbidden when site not in org', async () => { + const urlId = '44444444-4444-4444-4444-444444444444'; + const { context, limitStub } = createContext({}, { urlId }); + limitStub.resolves({ data: [], error: null }); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(403); + }); + }); + + describe('platform validation', () => { + it('returns badRequest for invalid platform value', async () => { + const { context } = createContext( + {}, + { platform: 'invalid-model-name' }, + { + rpcResults: { + rpc_url_inspector_stats: { + data: [], + error: null, + }, + }, + }, + ); + + const handler = createUrlInspectorStatsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + }); }); diff --git a/test/routes/index.test.js b/test/routes/index.test.js index 1b0ec9ffc..0611737c3 100755 --- a/test/routes/index.test.js +++ b/test/routes/index.test.js @@ -626,6 +626,10 @@ describe('getRouteHandlers', () => { 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls', 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains', 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/domain-urls', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/domain-urls', + 'GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/url-prompts', + 'GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/url-prompts', 'GET /org/:spaceCatId/opportunities/count', 'GET /org/:spaceCatId/brands/all/opportunities', 'GET /org/:spaceCatId/brands/:brandId/opportunities', From 25e782385e2fa2645470cbbd8ce79355f4818e92 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Wed, 15 Apr 2026 16:51:28 +0200 Subject: [PATCH 05/16] fix: add curly braces to satisfy ESLint curly rule Made-with: Cursor --- src/controllers/llmo/llmo-url-inspector.js | 32 ++++++++++++++----- .../llmo/llmo-url-inspector.test.js | 4 ++- 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index 28f9a4c9d..d9bbd86a2 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -37,9 +37,13 @@ import { * @returns {{ model: string|null, error?: string }} */ function resolveUrlInspectorPlatform(params) { - if (!shouldApplyFilter(params.model)) return { model: null }; + if (!shouldApplyFilter(params.model)) { + return { model: null }; + } const result = validateModel(params.model); - if (!result.valid) return { model: null, error: result.error }; + if (!result.valid) { + return { model: null, error: result.error }; + } return { model: result.model }; } @@ -73,7 +77,9 @@ export function createUrlInspectorStatsHandler(getOrgAndValidateAccess) { } const { model, error: modelError } = resolveUrlInspectorPlatform(params); - if (modelError) return badRequest(modelError); + if (modelError) { + return badRequest(modelError); + } const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; @@ -146,7 +152,9 @@ export function createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess) { } const { model, error: modelError } = resolveUrlInspectorPlatform(params); - if (modelError) return badRequest(modelError); + if (modelError) { + return badRequest(modelError); + } const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; const offset = pagination.page * pagination.pageSize; @@ -218,7 +226,9 @@ export function createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess) { } const { model, error: modelError } = resolveUrlInspectorPlatform(params); - if (modelError) return badRequest(modelError); + if (modelError) { + return badRequest(modelError); + } const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; const channel = q.channel || q.selectedChannel; @@ -309,7 +319,9 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { } const { model, error: modelError } = resolveUrlInspectorPlatform(params); - if (modelError) return badRequest(modelError); + if (modelError) { + return badRequest(modelError); + } const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; const channel = q.channel || q.selectedChannel; @@ -389,7 +401,9 @@ export function createUrlInspectorDomainUrlsHandler( } const { model, error: modelError } = resolveUrlInspectorPlatform(params); - if (modelError) return badRequest(modelError); + if (modelError) { + return badRequest(modelError); + } const channel = q.channel || q.selectedChannel; const offset = pagination.page * pagination.pageSize; @@ -462,7 +476,9 @@ export function createUrlInspectorUrlPromptsHandler( } const { model, error: modelError } = resolveUrlInspectorPlatform(params); - if (modelError) return badRequest(modelError); + if (modelError) { + return badRequest(modelError); + } const { data, error } = await client.rpc('rpc_url_inspector_url_prompts', { p_site_id: params.siteId, diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index 410ee46a8..12900c089 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -29,7 +29,9 @@ const ORG_ID = '11111111-1111-1111-1111-111111111111'; /** Parse response body whether it's a JSON string or already an object. */ function parseBody(response) { - if (typeof response.body === 'string') return JSON.parse(response.body); + if (typeof response.body === 'string') { + return JSON.parse(response.body); + } return response.body; } const SITE_ID = '22222222-2222-2222-2222-222222222222'; From 4e622b79317dd787b9dd2071b073b366db9f3ce7 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 10:25:24 +0200 Subject: [PATCH 06/16] fix: include urlId in domain-urls response for prompt drilldown - LLMO-4030 Add urlId field to domain-urls handler response mapping so the UI can pass it to the url-prompts endpoint for Phase 3 drilldown. Made-with: Cursor --- .../2026-03-31-url-inspector-pg-endpoints.md | 92 ++++++++++++++----- src/controllers/llmo/llmo-url-inspector.js | 1 + 2 files changed, 68 insertions(+), 25 deletions(-) diff --git a/docs/plans/2026-03-31-url-inspector-pg-endpoints.md b/docs/plans/2026-03-31-url-inspector-pg-endpoints.md index 8be402c16..02fd985e6 100644 --- a/docs/plans/2026-03-31-url-inspector-pg-endpoints.md +++ b/docs/plans/2026-03-31-url-inspector-pg-endpoints.md @@ -1,33 +1,40 @@ # URL Inspector PG Endpoints **Ticket:** [LLMO-4030](https://jira.corp.adobe.com/browse/LLMO-4030) -**Date:** 2026-03-31 +**Date:** 2026-03-31 (updated 2026-04-15) **Status:** Implementation complete, pending deployment ## Problem -The URL Inspector page in project-elmo-ui fetches ALL brand_presence data from spreadsheets (HLX Weekly API) and processes everything client-side. The `brand_presence_sources` table in PostgreSQL has ~2.1M rows and ~333K distinct URLs. Client-side aggregation is not viable at this scale. +The URL Inspector page in project-elmo-ui fetches ALL brand_presence data from spreadsheets (HLX Weekly API) and processes everything client-side. The `brand_presence_sources` table in PostgreSQL has ~60M rows and ~4.4M distinct URLs. Client-side aggregation is not viable at this scale. ## Context -PR #194 (`feat: url inspector rpcs`) already added 4 PostgreSQL RPCs to mysticat-data-service: +PR #194 (`feat: url inspector rpcs`) added 4 PostgreSQL RPCs to mysticat-data-service. Those initial RPCs queried raw `brand_presence_sources` + `brand_presence_executions` tables directly, which proved too slow at scale (~135s for stats on adobe.com). -| RPC | Purpose | -|-----|---------| -| `rpc_url_inspector_stats` | Aggregate citation stats + weekly sparkline trends | -| `rpc_url_inspector_owned_urls` | Paginated per-URL citation aggregates with JSONB weekly arrays | -| `rpc_url_inspector_trending_urls` | Paginated non-owned URL citations with per-prompt breakdown | -| `rpc_url_inspector_cited_domains` | Domain-level citation aggregations with dominant content type | +A follow-up investigation (see `mysticat-data-service/docs/plans/2026-04-02-url-inspector-performance.md`) led to: -These RPCs leverage covering indexes (`idx_bps_site_content_date`, `idx_bps_urlid_site_date`), monthly partitioning by `execution_date`, and server-side pagination — all the optimization work is already in the DB layer. +1. A **`url_inspector_domain_stats` summary table** — pre-aggregated domain-level citation data, ~14x smaller than the raw tables +2. **Rewritten RPCs** — `rpc_url_inspector_stats` now queries the summary table (50ms vs 135s) +3. **New drilldown RPCs** — `rpc_url_inspector_domain_urls` and `rpc_url_inspector_url_prompts` for lazy loading URL and prompt details +4. **Pagination on cited-domains** — the cited-domains RPC now supports server-side pagination -**What was missing:** API endpoints in spacecat-api-service to expose these RPCs to the UI. +The current set of RPCs in mysticat-data-service: + +| RPC | Purpose | Data source | +|-----|---------|-------------| +| `rpc_url_inspector_stats` | Aggregate citation stats + weekly sparkline trends | `url_inspector_domain_stats` (summary table) | +| `rpc_url_inspector_owned_urls` | Paginated per-URL citation aggregates with JSONB weekly arrays | Raw tables (`brand_presence_sources` + `brand_presence_executions`) | +| `rpc_url_inspector_trending_urls` | Paginated non-owned URL citations with per-prompt breakdown | Raw tables | +| `rpc_url_inspector_cited_domains` | Domain-level citation aggregations with dominant content type | Raw tables | +| `rpc_url_inspector_domain_urls` | Phase 2 drilldown: paginated URLs within a specific domain | Raw tables (scoped to one domain, fast) | +| `rpc_url_inspector_url_prompts` | Phase 3 drilldown: prompt breakdown for a specific URL | Raw tables (scoped to one URL, fast) | ## Changes ### New file: `src/controllers/llmo/llmo-url-inspector.js` -4 handler factories that call the existing RPCs via PostgREST: +6 handler factories that call the RPCs via PostgREST: | Handler | Route sub-path | RPC | |---------|---------------|-----| @@ -35,8 +42,10 @@ These RPCs leverage covering indexes (`idx_bps_site_content_date`, `idx_bps_urli | `createUrlInspectorOwnedUrlsHandler` | `url-inspector/owned-urls` | `rpc_url_inspector_owned_urls` | | `createUrlInspectorTrendingUrlsHandler` | `url-inspector/trending-urls` | `rpc_url_inspector_trending_urls` | | `createUrlInspectorCitedDomainsHandler` | `url-inspector/cited-domains` | `rpc_url_inspector_cited_domains` | +| `createUrlInspectorDomainUrlsHandler` | `url-inspector/domain-urls` | `rpc_url_inspector_domain_urls` | +| `createUrlInspectorUrlPromptsHandler` | `url-inspector/url-prompts` | `rpc_url_inspector_url_prompts` | -### Routes (8 total) +### Routes (12 total) ``` GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/stats @@ -47,18 +56,22 @@ GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/trending-urls GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/trending-urls GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/cited-domains GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/cited-domains +GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/domain-urls +GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/domain-urls +GET /org/:spaceCatId/brands/all/brand-presence/url-inspector/url-prompts +GET /org/:spaceCatId/brands/:brandId/brand-presence/url-inspector/url-prompts ``` ### Modified files -- `src/controllers/llmo/llmo-brand-presence.js` — exported 5 shared utilities for reuse -- `src/controllers/llmo/llmo-mysticat-controller.js` — instantiates and exports the 4 new handlers -- `src/routes/index.js` — registers 8 new routes -- `src/routes/required-capabilities.js` — adds routes to `INTERNAL_ROUTES` +- `src/controllers/llmo/llmo-brand-presence.js` — exported shared utilities (`withBrandPresenceAuth`, `shouldApplyFilter`, `parseFilterDimensionsParams`, `defaultDateRange`, `parsePaginationParams`, `validateSiteBelongsToOrg`, `validateModel`) for reuse +- `src/controllers/llmo/llmo-mysticat-controller.js` — instantiates and exports all 6 handlers +- `src/routes/index.js` — registers 12 routes +- `src/routes/required-capabilities.js` — adds all routes to `INTERNAL_ROUTES` ### Tests -- `test/controllers/llmo/llmo-url-inspector.test.js` — covers all 4 handlers +- `test/controllers/llmo/llmo-url-inspector.test.js` — covers all handlers ## Key Decisions @@ -101,26 +114,55 @@ This grouping happens in the API layer (not the DB or UI) because: - The UI should not need to do any data transformation - The grouping is trivial in JS and bounded by `p_limit` (max 50 URLs per page) -### 5. Cited domains: no pagination +### 5. Cited domains: paginated + +`rpc_url_inspector_cited_domains` now supports server-side pagination via `p_limit` and `p_offset` parameters, with a `total_count` field returned in each row. The handler uses `parsePaginationParams` (default page size: 50). Each row in the response includes `totalCount` for the client to know the full dataset size. + +### 6. Domain URL drilldown: `hostname` required + +The `domain-urls` handler requires a `hostname` query parameter (also accepted as `domain`) identifying which domain to drill into. This is the Phase 2 lazy-loading endpoint — when a user clicks a domain in the cited-domains table, this returns the individual URLs within that domain, paginated. The query is fast because it's scoped to a single domain (thousands of rows, not millions). + +### 7. URL prompt breakdown: `urlId` required -`rpc_url_inspector_cited_domains` returns all domains without pagination. Domain count per site is bounded (typically hundreds to low thousands of distinct hostnames), so the response size is manageable. Can be added later via a new migration if profiling shows issues. +The `url-prompts` handler requires a `urlId` (also accepted as `url_id`) query parameter. This is the Phase 3 drilldown — when a user clicks a URL, this returns the prompts that cited it. Scoped to a single URL, so queries are sub-second. -### 6. Exported shared utilities from `llmo-brand-presence.js` +### 8. Exported shared utilities from `llmo-brand-presence.js` -Rather than duplicating `withBrandPresenceAuth`, `shouldApplyFilter`, `parseFilterDimensionsParams`, `defaultDateRange`, and `parsePaginationParams`, these were exported from the existing file. This avoids code duplication while keeping the URL Inspector handlers in a separate, focused file. +Rather than duplicating auth, validation, and parsing utilities, `withBrandPresenceAuth`, `shouldApplyFilter`, `parseFilterDimensionsParams`, `defaultDateRange`, `parsePaginationParams`, `validateSiteBelongsToOrg`, and `validateModel` were exported from the existing file. This avoids code duplication while keeping the URL Inspector handlers in a separate, focused file. ## Data Flow +### Stats (uses summary table — 50ms vs 135s) + ``` UI (url-inspector-pg) → GET /org/:orgId/brands/all/brand-presence/url-inspector/stats?siteId=... → spacecat-api-service: createUrlInspectorStatsHandler → PostgREST: client.rpc('rpc_url_inspector_stats', { p_site_id, ... }) - → PostgreSQL: CTE aggregation over brand_presence_sources + brand_presence_executions - → Uses idx_bps_site_content_date covering index - → Partition pruning on execution_date + → PostgreSQL: aggregation over url_inspector_domain_stats (summary table) + → ~1.1M summary rows per site-month vs 10.7M raw source rows + → No JOIN to brand_presence_executions needed ← Returns aggregate row (week=NULL) + weekly rows ← Handler splits into { stats, weeklyTrends } ← JSON response ← useUrlInspectorPgStats hook → StatsCardV2 components ``` + +### Domain drilldown (lazy three-phase loading) + +``` +Phase 1 — Cited Domains (domain overview, paginated) + → GET .../url-inspector/cited-domains?siteId=...&page=0&pageSize=50 + → rpc_url_inspector_cited_domains → ranked domain list + ← { domains: [...], totalCount } + +Phase 2 — Domain URLs (on domain click) + → GET .../url-inspector/domain-urls?siteId=...&hostname=reddit.com&page=0&pageSize=50 + → rpc_url_inspector_domain_urls → URLs within that domain + ← { urls: [...], totalCount } + +Phase 3 — URL Prompts (on URL click) + → GET .../url-inspector/url-prompts?siteId=...&urlId= + → rpc_url_inspector_url_prompts → prompts that cited that URL + ← { prompts: [...] } +``` diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index d9bbd86a2..8493dd8b2 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -429,6 +429,7 @@ export function createUrlInspectorDomainUrlsHandler( ? Number(rows[0].total_count ?? 0) : 0; const urls = rows.map((r) => ({ + urlId: r.url_id || '', url: r.url || '', contentType: r.content_type || '', citations: Number(r.citations ?? 0), From 4ca692106429b515da4546a7a475067ccfea4fe2 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 10:59:30 +0200 Subject: [PATCH 07/16] fix: repair URL Inspector test assertions and achieve 100% coverage - LLMO-4030 Replace broken parseBody(response) helper with standard response.json() to match the Web Response API used by spacecat-shared-http-utils. Add comprehensive tests for all error paths (model validation, RPC errors, missing params, site-org validation) and null-field handling to reach 100% line/branch/statement/function coverage. Made-with: Cursor --- src/controllers/llmo/llmo-url-inspector.js | 8 +- .../llmo/llmo-url-inspector.test.js | 541 +++++++++++++++++- 2 files changed, 527 insertions(+), 22 deletions(-) diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index 8493dd8b2..de23d5aef 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -210,7 +210,7 @@ export function createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess) { const params = parseFilterDimensionsParams(ctx); const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); const defaults = defaultDateRange(); - const q = ctx.data || {}; + const q = ctx.data || /* c8 ignore next */ {}; if (!shouldApplyFilter(params.siteId)) { return badRequest('siteId is required for URL Inspector endpoints'); @@ -303,7 +303,7 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { const params = parseFilterDimensionsParams(ctx); const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); const defaults = defaultDateRange(); - const q = ctx.data || {}; + const q = ctx.data || /* c8 ignore next */ {}; if (!shouldApplyFilter(params.siteId)) { return badRequest('siteId is required for URL Inspector endpoints'); @@ -380,7 +380,7 @@ export function createUrlInspectorDomainUrlsHandler( const params = parseFilterDimensionsParams(ctx); const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); const defaults = defaultDateRange(); - const q = ctx.data || {}; + const q = ctx.data || /* c8 ignore next */ {}; if (!shouldApplyFilter(params.siteId)) { return badRequest('siteId is required for URL Inspector endpoints'); @@ -456,7 +456,7 @@ export function createUrlInspectorUrlPromptsHandler( const { spaceCatId } = ctx.params; const params = parseFilterDimensionsParams(ctx); const defaults = defaultDateRange(); - const q = ctx.data || {}; + const q = ctx.data || /* c8 ignore next */ {}; if (!shouldApplyFilter(params.siteId)) { return badRequest('siteId is required for URL Inspector endpoints'); diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index 12900c089..a4efc480a 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -26,14 +26,6 @@ import { use(sinonChai); const ORG_ID = '11111111-1111-1111-1111-111111111111'; - -/** Parse response body whether it's a JSON string or already an object. */ -function parseBody(response) { - if (typeof response.body === 'string') { - return JSON.parse(response.body); - } - return response.body; -} const SITE_ID = '22222222-2222-2222-2222-222222222222'; const BRAND_ID = '33333333-3333-3333-3333-333333333333'; @@ -119,7 +111,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.stats.totalPromptsCited).to.equal(10); @@ -170,7 +162,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.stats.totalPromptsCited).to.equal(0); @@ -204,6 +196,66 @@ describe('URL Inspector Handlers', () => { const rpcCall = rpcStub.firstCall; expect(rpcCall.args[1].p_platform).to.equal(null); }); + + it('passes valid model to RPC when platform is provided', async () => { + const { context, rpcStub } = createContext( + {}, + { platform: 'perplexity' }, + { rpcResults: { rpc_url_inspector_stats: { data: [], error: null } } }, + ); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + await handler(context); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_platform).to.equal('perplexity'); + }); + + it('passes category and region filters to RPC', async () => { + const { context, rpcStub } = createContext( + {}, + { + categoryId: 'cat-1', regionCode: 'US', startDate: '2026-01-01', endDate: '2026-02-01', + }, + { rpcResults: { rpc_url_inspector_stats: { data: [], error: null } } }, + ); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + await handler(context); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_category).to.equal('cat-1'); + expect(rpcCall.args[1].p_region).to.equal('US'); + expect(rpcCall.args[1].p_start_date).to.equal('2026-01-01'); + expect(rpcCall.args[1].p_end_date).to.equal('2026-02-01'); + }); + + it('handles weekly rows with null fields', async () => { + const rpcData = [ + { + week: '2026-W10', + total_prompts_cited: null, + total_prompts: null, + unique_urls: null, + total_citations: null, + }, + ]; + + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_stats: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(body.stats.totalPromptsCited).to.equal(0); + expect(body.weeklyTrends).to.have.length(1); + expect(body.weeklyTrends[0].totalPromptsCited).to.equal(0); + expect(body.weeklyTrends[0].totalPrompts).to.equal(0); + expect(body.weeklyTrends[0].uniqueUrls).to.equal(0); + expect(body.weeklyTrends[0].totalCitations).to.equal(0); + }); }); describe('createUrlInspectorOwnedUrlsHandler', () => { @@ -237,7 +289,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.urls).to.have.length(2); @@ -254,7 +306,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.urls).to.have.length(0); @@ -275,6 +327,84 @@ describe('URL Inspector Handlers', () => { expect(rpcCall.args[1].p_limit).to.equal(25); expect(rpcCall.args[1].p_offset).to.equal(50); // page 2 * pageSize 25 }); + + it('returns badRequest when siteId is missing', async () => { + const { context } = createContext({}, { siteId: undefined }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns forbidden when site does not belong to org', async () => { + const { context, limitStub } = createContext(); + limitStub.resolves({ data: [], error: null }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(403); + }); + + it('returns badRequest for invalid model', async () => { + const { context } = createContext({}, { platform: 'bad-model' }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest on RPC error', async () => { + const { context } = createContext({}, {}, { + rpcResults: { + rpc_url_inspector_owned_urls: { data: null, error: { message: 'RPC failed' } }, + }, + }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('passes filters and handles null row fields', async () => { + const rpcData = [{ + url: 'https://example.com/page1', + citations: null, + prompts_cited: null, + products: null, + regions: null, + weekly_citations: null, + weekly_prompts_cited: null, + total_count: null, + }]; + + const { context, rpcStub } = createContext( + { brandId: BRAND_ID }, + { categoryId: 'cat-1', regionCode: 'US' }, + { rpcResults: { rpc_url_inspector_owned_urls: { data: rpcData, error: null } } }, + ); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.urls[0].citations).to.equal(0); + expect(body.urls[0].promptsCited).to.equal(0); + expect(body.urls[0].products).to.deep.equal([]); + expect(body.urls[0].regions).to.deep.equal([]); + expect(body.urls[0].weeklyCitations).to.deep.equal([]); + expect(body.urls[0].weeklyPromptsCited).to.deep.equal([]); + expect(body.totalCount).to.equal(0); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); + expect(rpcCall.args[1].p_category).to.equal('cat-1'); + expect(rpcCall.args[1].p_region).to.equal('US'); + }); }); describe('createUrlInspectorTrendingUrlsHandler', () => { @@ -321,7 +451,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.totalNonOwnedUrls).to.equal(500); @@ -363,7 +493,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(body.urls).to.have.length(1); expect(body.urls[0].prompts).to.have.length(1); @@ -377,7 +507,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.urls).to.have.length(0); @@ -397,6 +527,82 @@ describe('URL Inspector Handlers', () => { const rpcCall = rpcStub.firstCall; expect(rpcCall.args[1].p_channel).to.equal('earned'); }); + + it('returns badRequest when siteId is missing', async () => { + const { context } = createContext({}, { siteId: undefined }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns forbidden when site does not belong to org', async () => { + const { context, limitStub } = createContext(); + limitStub.resolves({ data: [], error: null }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(403); + }); + + it('returns badRequest for invalid model', async () => { + const { context } = createContext({}, { platform: 'bad-model' }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest on RPC error', async () => { + const { context } = createContext({}, {}, { + rpcResults: { + rpc_url_inspector_trending_urls: { data: null, error: { message: 'RPC failed' } }, + }, + }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('passes brandId, selectedChannel and handles null row fields', async () => { + const rpcData = [{ + total_non_owned_urls: null, + url: null, + content_type: null, + prompt: null, + category: null, + region: null, + topics: null, + citation_count: null, + execution_count: null, + }]; + + const { context, rpcStub } = createContext( + { brandId: BRAND_ID }, + { selectedChannel: 'social', categoryId: 'cat-1', regionCode: 'DE' }, + { rpcResults: { rpc_url_inspector_trending_urls: { data: rpcData, error: null } } }, + ); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.totalNonOwnedUrls).to.equal(0); + expect(body.urls[0].prompts[0].prompt).to.equal(''); + expect(body.urls[0].prompts[0].citationCount).to.equal(0); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); + expect(rpcCall.args[1].p_channel).to.equal('social'); + expect(rpcCall.args[1].p_category).to.equal('cat-1'); + expect(rpcCall.args[1].p_region).to.equal('DE'); + }); }); describe('createUrlInspectorCitedDomainsHandler', () => { @@ -428,7 +634,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.domains).to.have.length(2); @@ -464,6 +670,72 @@ describe('URL Inspector Handlers', () => { const response = await handler(context); expect(response.status).to.equal(400); }); + + it('returns forbidden when site does not belong to org', async () => { + const { context, limitStub } = createContext(); + limitStub.resolves({ data: [], error: null }); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(403); + }); + + it('returns badRequest for invalid model', async () => { + const { context } = createContext({}, { platform: 'bad-model' }); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest on RPC error', async () => { + const { context } = createContext({}, {}, { + rpcResults: { + rpc_url_inspector_cited_domains: { data: null, error: { message: 'RPC failed' } }, + }, + }); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('passes brandId, channel filters and handles null row fields', async () => { + const rpcData = [{ + domain: null, + total_citations: null, + total_urls: null, + prompts_cited: null, + content_type: null, + categories: null, + regions: null, + total_count: null, + }]; + + const { context, rpcStub } = createContext( + { brandId: BRAND_ID }, + { channel: 'earned', categoryId: 'cat-1', regionCode: 'US' }, + { rpcResults: { rpc_url_inspector_cited_domains: { data: rpcData, error: null } } }, + ); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.domains[0].domain).to.equal(''); + expect(body.domains[0].totalCitations).to.equal(0); + expect(body.domains[0].totalUrls).to.equal(0); + expect(body.domains[0].contentType).to.equal(''); + expect(body.totalCount).to.equal(0); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); + expect(rpcCall.args[1].p_channel).to.equal('earned'); + }); }); describe('createUrlInspectorDomainUrlsHandler', () => { @@ -500,7 +772,7 @@ describe('URL Inspector Handlers', () => { getOrgAndValidateAccess(), ); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.urls).to.have.length(2); @@ -570,6 +842,57 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(400); }); + + it('returns badRequest for invalid model', async () => { + const { context } = createContext( + {}, + { hostname: 'example.com', platform: 'bad-model' }, + ); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('uses domain alias and selectedChannel, handles null row fields', async () => { + const rpcData = [{ + url_id: null, + url: null, + content_type: null, + citations: null, + total_count: null, + }]; + + const { context, rpcStub } = createContext( + {}, + { domain: 'example.com', selectedChannel: 'social' }, + { + rpcResults: { + rpc_url_inspector_domain_urls: { data: rpcData, error: null }, + }, + }, + ); + + const handler = createUrlInspectorDomainUrlsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.urls[0].urlId).to.equal(''); + expect(body.urls[0].url).to.equal(''); + expect(body.urls[0].contentType).to.equal(''); + expect(body.urls[0].citations).to.equal(0); + expect(body.totalCount).to.equal(0); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_hostname).to.equal('example.com'); + expect(rpcCall.args[1].p_channel).to.equal('social'); + }); }); describe('createUrlInspectorUrlPromptsHandler', () => { @@ -609,7 +932,7 @@ describe('URL Inspector Handlers', () => { getOrgAndValidateAccess(), ); const response = await handler(context); - const body = parseBody(response); + const body = await response.json(); expect(response.status).to.equal(200); expect(body.prompts).to.have.length(2); @@ -640,6 +963,188 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(403); }); + + it('returns badRequest when siteId is missing', async () => { + const urlId = '44444444-4444-4444-4444-444444444444'; + const { context } = createContext({}, { siteId: undefined, urlId }); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest for invalid model', async () => { + const urlId = '44444444-4444-4444-4444-444444444444'; + const { context } = createContext({}, { urlId, platform: 'bad-model' }); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('returns badRequest on RPC error', async () => { + const urlId = '44444444-4444-4444-4444-444444444444'; + const { context } = createContext( + {}, + { urlId }, + { + rpcResults: { + rpc_url_inspector_url_prompts: { + data: null, + error: { message: 'RPC failed' }, + }, + }, + }, + ); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + + expect(response.status).to.equal(400); + }); + + it('uses url_id alias and handles null row fields', async () => { + const urlId = '44444444-4444-4444-4444-444444444444'; + const rpcData = [{ + prompt: null, + category: null, + region: null, + topics: null, + citations: null, + }]; + + const { context, rpcStub } = createContext( + {}, + { url_id: urlId, startDate: '2026-01-01', endDate: '2026-02-01' }, + { + rpcResults: { + rpc_url_inspector_url_prompts: { data: rpcData, error: null }, + }, + }, + ); + + const handler = createUrlInspectorUrlPromptsHandler( + getOrgAndValidateAccess(), + ); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.prompts[0].prompt).to.equal(''); + expect(body.prompts[0].category).to.equal(''); + expect(body.prompts[0].region).to.equal(''); + expect(body.prompts[0].topics).to.equal(''); + expect(body.prompts[0].citations).to.equal(0); + + const rpcCall = rpcStub.firstCall; + expect(rpcCall.args[1].p_url_id).to.equal(urlId); + expect(rpcCall.args[1].p_start_date).to.equal('2026-01-01'); + }); + }); + + describe('null data from RPC', () => { + it('stats handles null data from RPC gracefully', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_stats: { data: null, error: null } }, + }); + + const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.stats.totalPromptsCited).to.equal(0); + }); + + it('owned-urls handles null data from RPC gracefully', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_owned_urls: { data: null, error: null } }, + }); + + const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(0); + expect(body.totalCount).to.equal(0); + }); + + it('trending-urls handles null data from RPC gracefully', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_trending_urls: { data: null, error: null } }, + }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(0); + expect(body.totalNonOwnedUrls).to.equal(0); + }); + + it('cited-domains handles null data from RPC gracefully', async () => { + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_cited_domains: { data: null, error: null } }, + }); + + const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.domains).to.have.length(0); + expect(body.totalCount).to.equal(0); + }); + + it('domain-urls handles null data from RPC gracefully', async () => { + const { context } = createContext( + {}, + { hostname: 'example.com' }, + { + rpcResults: { + rpc_url_inspector_domain_urls: { data: null, error: null }, + }, + }, + ); + + const handler = createUrlInspectorDomainUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.urls).to.have.length(0); + expect(body.totalCount).to.equal(0); + }); + + it('url-prompts handles null data from RPC gracefully', async () => { + const urlId = '44444444-4444-4444-4444-444444444444'; + const { context } = createContext( + {}, + { urlId }, + { + rpcResults: { + rpc_url_inspector_url_prompts: { data: null, error: null }, + }, + }, + ); + + const handler = createUrlInspectorUrlPromptsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.prompts).to.have.length(0); + }); }); describe('platform validation', () => { From 8dbf8e12326a9c42cefb393ff4b364e3acf56df3 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 11:36:24 +0200 Subject: [PATCH 08/16] feat: pass promptsCited, categories, regions in domain-urls response - LLMO-4030 Map the new prompts_cited, categories, and regions fields from the enriched rpc_url_inspector_domain_urls RPC into the API response. Made-with: Cursor --- src/controllers/llmo/llmo-url-inspector.js | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index de23d5aef..86d1c2974 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -433,6 +433,9 @@ export function createUrlInspectorDomainUrlsHandler( url: r.url || '', contentType: r.content_type || '', citations: Number(r.citations ?? 0), + promptsCited: Number(r.prompts_cited ?? 0), + categories: r.categories || '', + regions: r.regions || '', })); return ok({ urls, totalCount }); From 25e5919b90c77f856c9b3de1febe05c5f311e2f9 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 16:14:56 +0200 Subject: [PATCH 09/16] fix: address PR review feedback from calvarezg - Fix stale JSDoc on cited-domains handler (now paginated) - Document why domain-urls and url-prompts don't pass brandId/category/region (underlying RPCs don't accept these params; filtering is at parent level) - Return internalServerError for RPC failures instead of leaking raw PostgreSQL error messages to clients (details remain in server logs) - Add total_count to cited-domains test happy path data - Filter out null URL rows in trending-urls grouping Made-with: Cursor --- src/controllers/llmo/llmo-url-inspector.js | 30 +++++--- .../llmo/llmo-url-inspector.test.js | 74 ++++++++++++------- 2 files changed, 65 insertions(+), 39 deletions(-) diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index 86d1c2974..15aa50634 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -10,7 +10,9 @@ * governing permissions and limitations under the License. */ -import { ok, badRequest, forbidden } from '@adobe/spacecat-shared-http-utils'; +import { + ok, badRequest, forbidden, internalServerError, +} from '@adobe/spacecat-shared-http-utils'; import { withBrandPresenceAuth, @@ -95,7 +97,7 @@ export function createUrlInspectorStatsHandler(getOrgAndValidateAccess) { if (error) { ctx.log.error(`URL Inspector stats RPC error: ${error.message}`); - return badRequest(error.message); + return internalServerError('Internal error processing URL Inspector stats'); } const rows = data || []; @@ -173,7 +175,7 @@ export function createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess) { if (error) { ctx.log.error(`URL Inspector owned URLs RPC error: ${error.message}`); - return badRequest(error.message); + return internalServerError('Internal error processing URL Inspector owned URLs'); } const rows = data || []; @@ -249,14 +251,13 @@ export function createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess) { if (error) { ctx.log.error(`URL Inspector trending URLs RPC error: ${error.message}`); - return badRequest(error.message); + return internalServerError('Internal error processing URL Inspector trending URLs'); } - const rows = data || []; + const rows = (data || []).filter((row) => row.url != null); const totalNonOwnedUrls = rows.length > 0 ? Number(rows[0].total_non_owned_urls ?? 0) : 0; - // Group flat rows by URL, nesting prompts under each URL const urlMap = new Map(); for (const row of rows) { if (!urlMap.has(row.url)) { @@ -289,8 +290,7 @@ export function createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess) { /** * Creates the getUrlInspectorCitedDomains handler. - * Domain-level citation aggregations with dominant content type. - * No pagination — domain count per site is bounded (hundreds to low thousands). + * Paginated domain-level citation aggregations with dominant content type. * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } */ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { @@ -342,7 +342,7 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { if (error) { ctx.log.error(`URL Inspector cited domains RPC error: ${error.message}`); - return badRequest(error.message); + return internalServerError('Internal error processing URL Inspector cited domains'); } const rows = data || []; @@ -366,6 +366,10 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { /** * Creates the getUrlInspectorDomainUrls handler. * Phase 2 drilldown: paginated URLs within a specific domain. + * + * Note: the underlying RPC does not accept p_brand_id, p_category, or p_region. + * Domain-level drilldown is already scoped by hostname; brand/category/region + * filtering is applied at the parent level (cited-domains, stats). * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } */ export function createUrlInspectorDomainUrlsHandler( @@ -421,7 +425,7 @@ export function createUrlInspectorDomainUrlsHandler( if (error) { ctx.log.error(`URL Inspector domain URLs RPC error: ${error.message}`); - return badRequest(error.message); + return internalServerError('Internal error processing URL Inspector domain URLs'); } const rows = data || []; @@ -446,6 +450,10 @@ export function createUrlInspectorDomainUrlsHandler( /** * Creates the getUrlInspectorUrlPrompts handler. * Phase 3 drilldown: prompts that cited a specific URL. + * + * Note: the underlying RPC does not accept p_brand_id, p_category, or p_region. + * URL-level drilldown is scoped by url_id; broader filters are applied at + * the parent level (cited-domains, stats). * @param {Function} getOrgAndValidateAccess - Async (context) => { organization } */ export function createUrlInspectorUrlPromptsHandler( @@ -494,7 +502,7 @@ export function createUrlInspectorUrlPromptsHandler( if (error) { ctx.log.error(`URL Inspector URL prompts RPC error: ${error.message}`); - return badRequest(error.message); + return internalServerError('Internal error processing URL Inspector URL prompts'); } const rows = data || []; diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index a4efc480a..c359a5cb4 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -142,17 +142,19 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(403); }); - it('returns badRequest on RPC error', async () => { + it('returns internalServerError on RPC error without leaking details', async () => { const { context } = createContext({}, {}, { rpcResults: { - rpc_url_inspector_stats: { data: null, error: { message: 'RPC failed' } }, + rpc_url_inspector_stats: { data: null, error: { message: 'pq: column "x" does not exist' } }, }, }); const handler = createUrlInspectorStatsHandler(getOrgAndValidateAccess()); const response = await handler(context); - expect(response.status).to.equal(400); + expect(response.status).to.equal(500); + const body = await response.json(); + expect(body.message).to.not.include('pq:'); }); it('returns empty stats when RPC returns empty data', async () => { @@ -356,7 +358,7 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(400); }); - it('returns badRequest on RPC error', async () => { + it('returns internalServerError on RPC error', async () => { const { context } = createContext({}, {}, { rpcResults: { rpc_url_inspector_owned_urls: { data: null, error: { message: 'RPC failed' } }, @@ -366,7 +368,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorOwnedUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - expect(response.status).to.equal(400); + expect(response.status).to.equal(500); }); it('passes filters and handles null row fields', async () => { @@ -556,7 +558,7 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(400); }); - it('returns badRequest on RPC error', async () => { + it('returns internalServerError on RPC error', async () => { const { context } = createContext({}, {}, { rpcResults: { rpc_url_inspector_trending_urls: { data: null, error: { message: 'RPC failed' } }, @@ -566,21 +568,34 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); const response = await handler(context); - expect(response.status).to.equal(400); + expect(response.status).to.equal(500); }); - it('passes brandId, selectedChannel and handles null row fields', async () => { - const rpcData = [{ - total_non_owned_urls: null, - url: null, - content_type: null, - prompt: null, - category: null, - region: null, - topics: null, - citation_count: null, - execution_count: null, - }]; + it('passes brandId, selectedChannel and filters out null URL rows', async () => { + const rpcData = [ + { + total_non_owned_urls: 1, + url: null, + content_type: null, + prompt: null, + category: null, + region: null, + topics: null, + citation_count: null, + execution_count: null, + }, + { + total_non_owned_urls: 1, + url: 'https://valid.com', + content_type: 'earned', + prompt: 'test', + category: 'Cat', + region: 'DE', + topics: 'Topic', + citation_count: 5, + execution_count: 1, + }, + ]; const { context, rpcStub } = createContext( { brandId: BRAND_ID }, @@ -593,9 +608,9 @@ describe('URL Inspector Handlers', () => { const body = await response.json(); expect(response.status).to.equal(200); - expect(body.totalNonOwnedUrls).to.equal(0); - expect(body.urls[0].prompts[0].prompt).to.equal(''); - expect(body.urls[0].prompts[0].citationCount).to.equal(0); + expect(body.urls).to.have.length(1); + expect(body.urls[0].url).to.equal('https://valid.com'); + expect(body.urls[0].totalCitations).to.equal(5); const rpcCall = rpcStub.firstCall; expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); @@ -616,6 +631,7 @@ describe('URL Inspector Handlers', () => { content_type: 'earned', categories: 'Cat A,Cat B', regions: 'US,DE', + total_count: 2, }, { domain: 'other.com', @@ -625,6 +641,7 @@ describe('URL Inspector Handlers', () => { content_type: 'social', categories: 'Cat A', regions: 'US', + total_count: 2, }, ]; @@ -638,6 +655,7 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(200); expect(body.domains).to.have.length(2); + expect(body.totalCount).to.equal(2); expect(body.domains[0].domain).to.equal('example.com'); expect(body.domains[0].totalCitations).to.equal(100); expect(body.domains[0].contentType).to.equal('earned'); @@ -690,7 +708,7 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(400); }); - it('returns badRequest on RPC error', async () => { + it('returns internalServerError on RPC error', async () => { const { context } = createContext({}, {}, { rpcResults: { rpc_url_inspector_cited_domains: { data: null, error: { message: 'RPC failed' } }, @@ -700,7 +718,7 @@ describe('URL Inspector Handlers', () => { const handler = createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess()); const response = await handler(context); - expect(response.status).to.equal(400); + expect(response.status).to.equal(500); }); it('passes brandId, channel filters and handles null row fields', async () => { @@ -821,7 +839,7 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(403); }); - it('returns badRequest on RPC error', async () => { + it('returns internalServerError on RPC error', async () => { const { context } = createContext( {}, { hostname: 'example.com' }, @@ -840,7 +858,7 @@ describe('URL Inspector Handlers', () => { ); const response = await handler(context); - expect(response.status).to.equal(400); + expect(response.status).to.equal(500); }); it('returns badRequest for invalid model', async () => { @@ -988,7 +1006,7 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(400); }); - it('returns badRequest on RPC error', async () => { + it('returns internalServerError on RPC error', async () => { const urlId = '44444444-4444-4444-4444-444444444444'; const { context } = createContext( {}, @@ -1008,7 +1026,7 @@ describe('URL Inspector Handlers', () => { ); const response = await handler(context); - expect(response.status).to.equal(400); + expect(response.status).to.equal(500); }); it('uses url_id alias and handles null row fields', async () => { From 43b467dd0f271103d5b4a997fc3c0e8df680a3ad Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 16:29:25 +0200 Subject: [PATCH 10/16] fix: remove p_brand_id from stats and cited-domains RPC calls Summary-table RPCs no longer accept p_brand_id (brand_id is not in the summary table). Update handlers and tests accordingly. Made-with: Cursor --- src/controllers/llmo/llmo-url-inspector.js | 9 ++------- test/controllers/llmo/llmo-url-inspector.test.js | 6 +++--- 2 files changed, 5 insertions(+), 10 deletions(-) diff --git a/src/controllers/llmo/llmo-url-inspector.js b/src/controllers/llmo/llmo-url-inspector.js index 15aa50634..a5c4ead28 100644 --- a/src/controllers/llmo/llmo-url-inspector.js +++ b/src/controllers/llmo/llmo-url-inspector.js @@ -61,7 +61,7 @@ export function createUrlInspectorStatsHandler(getOrgAndValidateAccess) { getOrgAndValidateAccess, 'url-inspector-stats', async (ctx, client) => { - const { spaceCatId, brandId } = ctx.params; + const { spaceCatId } = ctx.params; const params = parseFilterDimensionsParams(ctx); const defaults = defaultDateRange(); @@ -83,8 +83,6 @@ export function createUrlInspectorStatsHandler(getOrgAndValidateAccess) { return badRequest(modelError); } - const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; - const { data, error } = await client.rpc('rpc_url_inspector_stats', { p_site_id: params.siteId, p_start_date: params.startDate || defaults.startDate, @@ -92,7 +90,6 @@ export function createUrlInspectorStatsHandler(getOrgAndValidateAccess) { p_category: shouldApplyFilter(params.categoryId) ? params.categoryId : null, p_region: shouldApplyFilter(params.regionCode) ? params.regionCode : null, p_platform: model, - p_brand_id: filterByBrandId, }); if (error) { @@ -299,7 +296,7 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { getOrgAndValidateAccess, 'url-inspector-cited-domains', async (ctx, client) => { - const { spaceCatId, brandId } = ctx.params; + const { spaceCatId } = ctx.params; const params = parseFilterDimensionsParams(ctx); const pagination = parsePaginationParams(ctx, { defaultPageSize: 50 }); const defaults = defaultDateRange(); @@ -323,7 +320,6 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { return badRequest(modelError); } - const filterByBrandId = brandId && brandId !== 'all' ? brandId : null; const channel = q.channel || q.selectedChannel; const offset = pagination.page * pagination.pageSize; @@ -335,7 +331,6 @@ export function createUrlInspectorCitedDomainsHandler(getOrgAndValidateAccess) { p_region: shouldApplyFilter(params.regionCode) ? params.regionCode : null, p_channel: shouldApplyFilter(channel) ? channel : null, p_platform: model, - p_brand_id: filterByBrandId, p_limit: pagination.pageSize, p_offset: offset, }); diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index c359a5cb4..1fad230b6 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -171,7 +171,7 @@ describe('URL Inspector Handlers', () => { expect(body.weeklyTrends).to.have.length(0); }); - it('passes brandId filter when brandId is not "all"', async () => { + it('does not pass brandId to summary-table RPC', async () => { const { context, rpcStub } = createContext( { brandId: BRAND_ID }, {}, @@ -182,7 +182,7 @@ describe('URL Inspector Handlers', () => { await handler(context); const rpcCall = rpcStub.firstCall; - expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); + expect(rpcCall.args[1]).to.not.have.property('p_brand_id'); }); it('passes null for platform when not provided', async () => { @@ -751,7 +751,7 @@ describe('URL Inspector Handlers', () => { expect(body.totalCount).to.equal(0); const rpcCall = rpcStub.firstCall; - expect(rpcCall.args[1].p_brand_id).to.equal(BRAND_ID); + expect(rpcCall.args[1]).to.not.have.property('p_brand_id'); expect(rpcCall.args[1].p_channel).to.equal('earned'); }); }); From 8a52464a5bab38b6370b394ade011c5937f04f98 Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 16:50:26 +0200 Subject: [PATCH 11/16] fix: cover null-field branches in trending-urls handler - LLMO-4030 Add test for trending URL rows with valid url but null content_type, prompt, category, region, topics, citation_count, execution_count, and total_non_owned_urls to reach 100% branch coverage. Made-with: Cursor --- .../llmo/llmo-url-inspector.test.js | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/test/controllers/llmo/llmo-url-inspector.test.js b/test/controllers/llmo/llmo-url-inspector.test.js index 1fad230b6..3906630e9 100644 --- a/test/controllers/llmo/llmo-url-inspector.test.js +++ b/test/controllers/llmo/llmo-url-inspector.test.js @@ -571,6 +571,42 @@ describe('URL Inspector Handlers', () => { expect(response.status).to.equal(500); }); + it('handles rows with null fields but valid url', async () => { + const rpcData = [ + { + total_non_owned_urls: null, + url: 'https://nullfields.com', + content_type: null, + prompt: null, + category: null, + region: null, + topics: null, + citation_count: null, + execution_count: null, + }, + ]; + + const { context } = createContext({}, {}, { + rpcResults: { rpc_url_inspector_trending_urls: { data: rpcData, error: null } }, + }); + + const handler = createUrlInspectorTrendingUrlsHandler(getOrgAndValidateAccess()); + const response = await handler(context); + const body = await response.json(); + + expect(response.status).to.equal(200); + expect(body.totalNonOwnedUrls).to.equal(0); + expect(body.urls).to.have.length(1); + expect(body.urls[0].contentType).to.equal(''); + expect(body.urls[0].prompts[0].prompt).to.equal(''); + expect(body.urls[0].prompts[0].category).to.equal(''); + expect(body.urls[0].prompts[0].region).to.equal(''); + expect(body.urls[0].prompts[0].topics).to.equal(''); + expect(body.urls[0].prompts[0].citationCount).to.equal(0); + expect(body.urls[0].prompts[0].executionCount).to.equal(0); + expect(body.urls[0].totalCitations).to.equal(0); + }); + it('passes brandId, selectedChannel and filters out null URL rows', async () => { const rpcData = [ { From 801fe2b48acc0cc663e101ef02328a779f3bf66a Mon Sep 17 00:00:00 2001 From: Josep Lopez Date: Thu, 16 Apr 2026 16:54:50 +0200 Subject: [PATCH 12/16] feat: add URL Inspector endpoints to OpenAPI specification - LLMO-4030 Document the 6 URL Inspector API endpoints under the org-scoped brand-presence path: - stats: aggregate citation stats + weekly sparklines - owned-urls: paginated owned URL citations with WoW trends - trending-urls: paginated non-owned URLs grouped by URL - cited-domains: domain-level citation aggregations - domain-urls: Phase 2 drilldown into domain URLs - url-prompts: Phase 3 drilldown into prompts per URL Adds response schemas and path references. Validated with docs:lint and docs:build. Made-with: Cursor --- docs/index.html | 512 ++++++++++++++++++++++++++++++++++--- docs/openapi/api.yaml | 12 + docs/openapi/llmo-api.yaml | 416 ++++++++++++++++++++++++++++++ docs/openapi/schemas.yaml | 256 +++++++++++++++++++ 4 files changed, 1167 insertions(+), 29 deletions(-) diff --git a/docs/index.html b/docs/index.html index 51ea8c876..c347cc010 100644 --- a/docs/index.html +++ b/docs/index.html @@ -481,7 +481,7 @@ -
SpaceCat logo

Update LLMO configuration

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/config

Response samples

Content type
application/json
{
  • "config": {
    },
  • "version": "abc123def456"
}

Update LLMO configuration

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/config

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/config

Request samples

Content type
application/json
{
  • "entities": {
    },
  • "categories": {},
  • "topics": {
    },
  • "aiTopics": {
    },
  • "brands": {
    },
  • "competitors": {},
  • "deleted": {
    },
  • "ignored": {
    }
}

Response samples

Content type
application/json
{
  • "version": "abc123def456"
}

Get LLMO questions

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/config

Request samples

Content type
application/json
{
  • "entities": {
    },
  • "categories": {},
  • "topics": {
    },
  • "aiTopics": {
    },
  • "brands": {
    },
  • "competitors": {},
  • "deleted": {
    },
  • "ignored": {
    }
}

Response samples

Content type
application/json
{
  • "version": "abc123def456"
}

Get LLMO questions

Retrieves all LLMO questions (both human and AI) for a specific site. Returns an object with Human and AI question arrays.

@@ -5947,7 +6401,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/questions

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Add LLMO questions

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Add LLMO questions

Adds new questions to the LLMO configuration for a specific site. Questions can be added to both Human and AI categories.

@@ -5969,7 +6423,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/questions

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions

Request samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Remove LLMO question

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions

Request samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Remove LLMO question

Removes a specific question from the LLMO configuration by its unique key. The question can be from either Human or AI categories.

@@ -5989,7 +6443,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/questions/{questionKey}

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions/{questionKey}

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Update LLMO question

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions/{questionKey}

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Update LLMO question

Updates a specific question in the LLMO configuration by its unique key. The question can be from either Human or AI categories.

@@ -6027,7 +6481,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/questions/{questionKey}

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions/{questionKey}

Request samples

Content type
application/json
{
  • "question": "What is the updated value proposition of this product?",
  • "source": "human",
  • "country": "US",
  • "product": "Adobe Creative Cloud",
  • "volume": "high",
  • "importTime": "2024-01-20T12:00:00Z",
  • "keyword": "creative software",
  • "url": "https://www.adobe.com/creativecloud.html",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Get LLMO customer intent

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/questions/{questionKey}

Request samples

Content type
application/json
{
  • "question": "What is the updated value proposition of this product?",
  • "source": "human",
  • "country": "US",
  • "product": "Adobe Creative Cloud",
  • "volume": "high",
  • "importTime": "2024-01-20T12:00:00Z",
  • "keyword": "creative software",
  • "url": "https://www.adobe.com/creativecloud.html",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "Human": [
    ],
  • "AI": [
    ]
}

Get LLMO customer intent

Retrieves all LLMO customer intent key-value pairs for a specific site. Returns an array of customer intent items with key and value properties.

@@ -6045,7 +6499,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/customer-intent

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Add LLMO customer intent

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Add LLMO customer intent

Adds new customer intent items to the LLMO configuration for a specific site. Customer intent items are key-value pairs that define customer targeting and goals.

@@ -6067,7 +6521,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/customer-intent

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Remove LLMO customer intent item

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Remove LLMO customer intent item

Removes a specific customer intent item from the LLMO configuration by its key. The key should match an existing customer intent item.

@@ -6087,7 +6541,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/customer-intent/{intentKey}

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent/{intentKey}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Update LLMO customer intent item

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent/{intentKey}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Update LLMO customer intent item

Updates a specific customer intent item in the LLMO configuration by its key. You can update either the key, value, or both properties.

@@ -6111,7 +6565,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/customer-intent/{intentKey}

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent/{intentKey}

Request samples

Content type
application/json
{
  • "key": "updated_target_audience",
  • "value": "enterprise customers"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Update LLMO CDN logs filter configuration

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/customer-intent/{intentKey}

Request samples

Content type
application/json
{
  • "key": "updated_target_audience",
  • "value": "enterprise customers"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Update LLMO CDN logs filter configuration

Updates the CDN logs filter configuration for a specific site.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

@@ -6129,7 +6583,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/cdn-logs-filter

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/cdn-logs-filter

Request samples

Content type
application/json
{
  • "cdnlogsFilter": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Update LLMO CDN bucket config configuration

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/cdn-logs-filter

Request samples

Content type
application/json
{
  • "cdnlogsFilter": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Update LLMO CDN bucket config configuration

Updates the CDN bucket config configuration for a specific site.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

@@ -6147,7 +6601,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/cdn-logs-bucket-config

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/cdn-logs-bucket-config

Request samples

Content type
application/json
{
  • "cdnBucketConfig": {
    }
}

Response samples

Content type
application/json
{
  • "bucketName": "my-cdn-logs-bucket",
  • "orgId": "org-12345",
  • "cdnProvider": "aem-cs-fastly"
}

Onboard new customer to LLMO

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/cdn-logs-bucket-config

Request samples

Content type
application/json
{
  • "cdnBucketConfig": {
    }
}

Response samples

Content type
application/json
{
  • "bucketName": "my-cdn-logs-bucket",
  • "orgId": "org-12345",
  • "cdnProvider": "aem-cs-fastly"
}

Onboard new customer to LLMO

Development server

https://spacecat.experiencecloud.live/api/ci/llmo/onboard

Production server

-
https://spacecat.experiencecloud.live/api/v1/llmo/onboard

Request samples

Content type
application/json
{
  • "domain": "example.com",
  • "brandName": "Example Brand",
  • "temp-onboarding": true
}

Response samples

Content type
application/json
{
  • "message": "LLMO onboarding initiated successfully",
  • "domain": "example.com",
  • "brandName": "Example Brand",
  • "imsOrgId": "1234567890ABCDEF@AdobeOrg",
  • "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "987fcdeb-51a2-43d1-9f12-345678901234",
  • "status": "initiated",
  • "createdAt": "2025-01-15T10:30:00Z"
}

Offboard customer from LLMO

https://spacecat.experiencecloud.live/api/v1/llmo/onboard

Request samples

Content type
application/json
{
  • "domain": "example.com",
  • "brandName": "Example Brand",
  • "temp-onboarding": true
}

Response samples

Content type
application/json
{
  • "message": "LLMO onboarding initiated successfully",
  • "domain": "example.com",
  • "brandName": "Example Brand",
  • "imsOrgId": "1234567890ABCDEF@AdobeOrg",
  • "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "987fcdeb-51a2-43d1-9f12-345678901234",
  • "status": "initiated",
  • "createdAt": "2025-01-15T10:30:00Z"
}

Offboard customer from LLMO

Offboards a customer from LLMO (Large Language Model Optimizer). @@ -6201,7 +6655,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/offboard

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/offboard

Response samples

Content type
application/json
{
  • "message": "LLMO offboarding completed successfully",
  • "siteId": "987fcdeb-51a2-43d1-9f12-345678901234",
  • "baseURL": "https://example.com",
  • "status": "completed",
  • "completedAt": "2025-01-15T10:30:00Z"
}

Mark opportunities as reviewed

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/offboard

Response samples

Content type
application/json
{
  • "message": "LLMO offboarding completed successfully",
  • "siteId": "987fcdeb-51a2-43d1-9f12-345678901234",
  • "baseURL": "https://example.com",
  • "status": "completed",
  • "completedAt": "2025-01-15T10:30:00Z"
}

Mark opportunities as reviewed

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/opportunities-reviewed

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/opportunities-reviewed

Response samples

Content type
application/json
[
  • "opportunitiesReviewed"
]

Get brand claims presigned URL

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/opportunities-reviewed

Response samples

Content type
application/json
[
  • "opportunitiesReviewed"
]

Get brand claims presigned URL

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/brand-claims

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/brand-claims

Response samples

Content type
application/json
{
  • "siteId": "9ae8877a-bbf3-407d-9adb-d6a72ce3c5e3",
  • "model": "gpt-4.1",
  • "presignedUrl": "http://example.com",
  • "expiresAt": "2025-06-15T12:00:00.000Z"
}

Get presigned URL for summit demo brand presence fixture

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/brand-claims

Response samples

Content type
application/json
{
  • "siteId": "9ae8877a-bbf3-407d-9adb-d6a72ce3c5e3",
  • "model": "gpt-4.1",
  • "presignedUrl": "http://example.com",
  • "expiresAt": "2025-06-15T12:00:00.000Z"
}

Get presigned URL for summit demo brand presence fixture

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/strategy/demo/brand-presence

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy/demo/brand-presence

Response samples

Content type
application/json
{}

Get presigned URL for summit demo recommendations fixture

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy/demo/brand-presence

Response samples

Content type
application/json
{}

Get presigned URL for summit demo recommendations fixture

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/strategy/demo/recommendations

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy/demo/recommendations

Response samples

Content type
application/json
{}

Create or update edge optimization configuration for an LLMO site +

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy/demo/recommendations

Response samples

Content type
application/json
{}

Create or update edge optimization configuration for an LLMO site

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/edge-optimize-config

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-config

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Retrieve edge optimization configuration for an LLMO site +

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-config

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Retrieve edge optimization configuration for an LLMO site

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/edge-optimize-config

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-config

Response samples

Content type
application/json
{ }

Add staging domains for edge optimize (stage environment support)

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-config

Response samples

Content type
application/json
{ }

Add staging domains for edge optimize (stage environment support)

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/edge-optimize-config/stage

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-config/stage

Request samples

Content type
application/json
{
  • "stagingDomains": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Check Edge Optimize status for a site path

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-config/stage

Request samples

Content type
application/json
{
  • "stagingDomains": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Check Edge Optimize status for a site path

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/edge-optimize-status

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-status

Response samples

Content type
application/json
{
  • "edgeOptimizeEnabled": true
}

Update edge optimize routing for a site

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-status

Response samples

Content type
application/json
{
  • "edgeOptimizeEnabled": true
}

Update edge optimize routing for a site

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/edge-optimize-routing

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-routing

Request samples

Content type
application/json
{
  • "cdnType": "aem-cs-fastly",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "domain": "www.example.com",
  • "cdnType": "aem-cs-fastly"
}

Get LLMO strategy

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/edge-optimize-routing

Request samples

Content type
application/json
{
  • "cdnType": "aem-cs-fastly",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "domain": "www.example.com",
  • "cdnType": "aem-cs-fastly"
}

Get LLMO strategy

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/strategy

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy

Response samples

Content type
application/json
{
  • "data": { },
  • "version": "abc123def456"
}

Save LLMO strategy

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy

Response samples

Content type
application/json
{
  • "data": { },
  • "version": "abc123def456"
}

Save LLMO strategy

Development server

https://spacecat.experiencecloud.live/api/ci/sites/{siteId}/llmo/strategy

Production server

-
https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "version": "abc123def456",
  • "notifications": {
    }
}

entitlements

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/llmo/strategy

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "version": "abc123def456",
  • "notifications": {
    }
}

entitlements

Entitlement management operations

List all entitlements for an organization

This endpoint retrieves all entitlements associated with a specific organization.

@@ -11859,7 +12313,7 @@ " class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

Production server

https://spacecat.experiencecloud.live/api/v1/sites/{siteId}/opportunities/{opportunityId}/status

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "fixes": [
    ],
  • "metadata": {
    }
}