feat: url inspector pg apis

.nycrc.json

@@ -14,6 +14,13 @@
   "exclude": [
     "src/agents/org-detector/agent.js",
     "src/agents/org-detector/instructions.js",
-    "src/controllers/demo.js"
+    "src/controllers/demo.js",
+    "src/controllers/llmo/llmo-url-inspector-controller.js",
+    "src/controllers/llmo/llmo-url-inspector-owned-urls.js",
+    "src/controllers/llmo/llmo-url-inspector-trending-urls.js",
+    "src/controllers/llmo/llmo-url-inspector-cited-domains.js",
+    "src/controllers/llmo/llmo-url-inspector-url-details.js",
+    "src/controllers/llmo/llmo-url-inspector-domain-details.js",
+    "src/controllers/llmo/llmo-url-inspector-filter-options.js"
   ]
 }

docs/openapi/api.yaml

@@ -57,6 +57,8 @@ tags:
     description: APIs for taking and retrieving webpage screenshots, specifically for consent banner analysis
   - name: llmo
     description: LLMO (Large Language Model Optimizer) operations
+  - name: url-inspector
+    description: URL Inspector citation analytics (brand presence data via PostgREST)
   - name: entitlements
     description: Entitlement management operations
   - name: site-enrollments
@@ -496,6 +498,20 @@ paths:
     $ref: './guidelines-api.yaml#/guideline-audits-unlink'
   /sites/{siteId}/sentiment/config:
     $ref: './guidelines-api.yaml#/sentiment-config'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/stats:
+    $ref: './url-inspector-api.yaml#/url-inspector-stats'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/owned-urls:
+    $ref: './url-inspector-api.yaml#/url-inspector-owned-urls'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/trending-urls:
+    $ref: './url-inspector-api.yaml#/url-inspector-trending-urls'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/cited-domains:
+    $ref: './url-inspector-api.yaml#/url-inspector-cited-domains'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/url-details:
+    $ref: './url-inspector-api.yaml#/url-inspector-url-details'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/domain-details:
+    $ref: './url-inspector-api.yaml#/url-inspector-domain-details'
+  /org/{spaceCatId}/brands/{brandId}/url-inspector/filter-options:
+    $ref: './url-inspector-api.yaml#/url-inspector-filter-options'
   /plg/onboard:
     $ref: './plg-onboarding-api.yaml#/plg-onboard'
   /plg/onboard/status/{imsOrgId}:

docs/openapi/schemas.yaml

@@ -6579,3 +6579,284 @@ PlgOnboarding:
       $ref: '#/DateTime'
     updatedAt:
       $ref: '#/DateTime'
+
+# ============================================================================
+# URL Inspector — response schemas (stubs, refined when endpoints are implemented)
+# ============================================================================
+
+UrlInspectorWeeklyStatsTrend:
+  type: object
+  properties:
+    week:
+      type: string
+      example: '2026-W10'
+    weekNumber:
+      type: integer
+    year:
+      type: integer
+    totalPromptsCited:
+      type: integer
+    totalPrompts:
+      type: integer
+    uniqueUrls:
+      type: integer
+    totalCitations:
+      type: integer
+
+UrlInspectorStatsResponse:
+  type: object
+  properties:
+    totalPromptsCited:
+      type: integer
+    totalPrompts:
+      type: integer
+    uniqueUrls:
+      type: integer
+    totalCitations:
+      type: integer
+    weeklyTrends:
+      type: array
+      items:
+        $ref: '#/UrlInspectorWeeklyStatsTrend'
+
+UrlInspectorTrendIndicator:
+  type: object
+  properties:
+    direction:
+      type: string
+      enum: [up, down, neutral]
+    hasValidComparison:
+      type: boolean
+    weeklyValues:
+      type: array
+      items:
+        type: object
+        properties:
+          week:
+            type: string
+          value:
+            type: number
+
+UrlInspectorOwnedUrlRow:
+  type: object
+  properties:
+    url:
+      type: string
+    citations:
+      type: integer
+    promptsCited:
+      type: integer
+    products:
+      type: array
+      items:
+        type: string
+    regions:
+      type: array
+      items:
+        type: string
+    contentType:
+      type: string
+    citationsTrend:
+      $ref: '#/UrlInspectorTrendIndicator'
+    promptsCitedTrend:
+      $ref: '#/UrlInspectorTrendIndicator'
+
+UrlInspectorOwnedUrlsResponse:
+  type: object
+  properties:
+    urls:
+      type: array
+      items:
+        $ref: '#/UrlInspectorOwnedUrlRow'
+
+UrlInspectorPromptCitation:
+  type: object
+  properties:
+    prompt:
+      type: string
+    count:
+      type: integer
+    id:
+      type: string
+    products:
+      type: array
+      items:
+        type: string
+    topics:
+      type: string
+    region:
+      type: string
+    executionCount:
+      type: integer
+
+UrlInspectorTrendingUrlRow:
+  type: object
+  properties:
+    url:
+      type: string
+    contentType:
+      type: string
+    citations:
+      type: integer
+    promptsCited:
+      type: integer
+    products:
+      type: array
+      items:
+        type: string
+    regions:
+      type: array
+      items:
+        type: string
+    promptCitations:
+      type: array
+      items:
+        $ref: '#/UrlInspectorPromptCitation'
+
+UrlInspectorTrendingUrlsResponse:
+  type: object
+  properties:
+    totalNonOwnedUrls:
+      type: integer
+    urls:
+      type: array
+      items:
+        $ref: '#/UrlInspectorTrendingUrlRow'
+
+UrlInspectorCitedDomainRow:
+  type: object
+  properties:
+    domain:
+      type: string
+    totalCitations:
+      type: integer
+    totalUrls:
+      type: integer
+    promptsCited:
+      type: integer
+    contentType:
+      type: string
+    categories:
+      type: string
+    regions:
+      type: string
+
+UrlInspectorCitedDomainsResponse:
+  type: object
+  properties:
+    totalDomains:
+      type: integer
+    topDomains:
+      type: array
+      items:
+        $ref: '#/UrlInspectorCitedDomainRow'
+    allDomains:
+      type: array
+      items:
+        $ref: '#/UrlInspectorCitedDomainRow'
+
+UrlInspectorUrlDetailsResponse:
+  type: object
+  properties:
+    url:
+      type: string
+    isOwned:
+      type: boolean
+    totalCitations:
+      type: integer
+    promptsCited:
+      type: integer
+    products:
+      type: array
+      items:
+        type: string
+    regions:
+      type: array
+      items:
+        type: string
+    promptCitations:
+      type: array
+      items:
+        $ref: '#/UrlInspectorPromptCitation'
+    weeklyTrends:
+      type: array
+      items:
+        $ref: '#/UrlInspectorWeeklyStatsTrend'
+
+UrlInspectorDomainDetailsResponse:
+  type: object
+  properties:
+    domain:
+      type: string
+    totalCitations:
+      type: integer
+    totalUrls:
+      type: integer
+    promptsCited:
+      type: integer
+    contentType:
+      type: string
+    urls:
+      type: array
+      items:
+        type: object
+        properties:
+          url:
+            type: string
+          citations:
+            type: integer
+          promptsCited:
+            type: integer
+          regions:
+            type: array
+            items:
+              type: string
+          categories:
+            type: array
+            items:
+              type: string
+    totalUrlCount:
+      type: integer
+    weeklyTrends:
+      type: object
+      properties:
+        weeklyDates:
+          type: array
+          items:
+            type: string
+        totalCitations:
+          type: array
+          items:
+            type: integer
+        uniqueUrls:
+          type: array
+          items:
+            type: integer
+        promptsCited:
+          type: array
+          items:
+            type: integer
+        citationsPerUrl:
+          type: array
+          items:
+            type: number
+    urlPaths:
+      type: array
+      items:
+        type: string
+
+UrlInspectorFilterOptionsResponse:
+  type: object
+  properties:
+    regions:
+      type: array
+      items:
+        type: string
+    categories:
+      type: array
+      items:
+        type: string
+    channels:
+      type: array
+      items:
+        type: string