[feat/serenity-init]: codebase alignment

Author: dmitriigulkin-semrush

docs/index.html

@@ -1,6 +1,6 @@
 # AI Visibility (Semrush gRPC proxy) – 22 GET endpoints
 # All endpoints live under /llmo/ai-visibility/* and proxy to Semrush gRPC.
-# Responses include an sr_filters block with available markets and models.
+# Responses include an srFilters block with available markets and models.
 
 # ── shared parameter fragments ──────────────────────────────────────────
 x-ai-vis-domain: &domainParam
@@ -34,10 +34,10 @@ x-ai-vis-engine: &engineParam
   name: engine
   in: query
   required: false
-  description: LLM engine slug (`chatgpt`, `gemini`, `google_ai_mode`, `google_ai_overview`). Omit or `all` for all models.
+  description: LLM engine slug (`chatgpt`, `gemini`, `googleAiMode`, `googleAiOverview`). Omit or `all` for all models.
   schema:
     type: string
-    enum: [chatgpt, gemini, google_ai_mode, google_ai_overview, all]
+    enum: [chatgpt, gemini, googleAiMode, googleAiOverview, all]
     example: chatgpt
 
 x-ai-vis-limit: &limitParam
@@ -71,7 +71,7 @@ x-ai-vis-month: &monthParam
     example: '2026-01'
 
 x-ai-vis-window-months: &windowMonthsParam
-  name: window_months
+  name: windowMonths
   in: query
   required: false
   description: Number of months to include in date-range aggregations
@@ -81,7 +81,7 @@ x-ai-vis-window-months: &windowMonthsParam
     example: 6
 
 x-ai-vis-search-query: &searchQueryParam
-  name: search_query
+  name: searchQuery
   in: query
   required: true
   description: Full-text search query for topic research
@@ -90,7 +90,7 @@ x-ai-vis-search-query: &searchQueryParam
     example: coffee
 
 x-ai-vis-topic-id: &topicIdParam
-  name: topic_id
+  name: topicId
   in: query
   required: true
   description: Topic identifier
@@ -384,14 +384,14 @@ ai-visibility-competitors-metrics:
       - *countryParam
       - *regionParam
       - *engineParam
-      - name: gap_snapshot_date
+      - name: gapSnapshotDate
         in: query
         required: false
         description: Pin to a specific snapshot date (`YYYY-MM-DD`)
         schema:
           type: string
           pattern: '^\d{4}-\d{2}-\d{2}$'
-      - name: metrics_snapshot_date
+      - name: metricsSnapshotDate
         in: query
         required: false
         description: Pin to a specific metrics snapshot date (`YYYY-MM-DD`)
@@ -425,7 +425,7 @@ ai-visibility-competitors-gap-topics:
       - *engineParam
       - *limitParam
       - *offsetParam
-      - name: gap_kinds
+      - name: gapKinds
         in: query
         required: false
         description: Comma-separated gap kinds (`ALL`, `MISSING`, `SHARED`, `UNIQUE`)
@@ -459,7 +459,7 @@ ai-visibility-competitors-gap-source-domains:
       - *engineParam
       - *limitParam
       - *offsetParam
-      - name: gap_kinds
+      - name: gapKinds
         in: query
         required: false
         description: Comma-separated gap kinds (`ALL`, `MISSING`, `SHARED`, `UNIQUE`)
@@ -495,14 +495,14 @@ ai-visibility-competitors-gap-prompts:
       - *engineParam
       - *limitParam
       - *offsetParam
-      - name: gap_kinds
+      - name: gapKinds
         in: query
         required: false
         description: Comma-separated gap kinds (`ALL`, `MISSING`, `SHARED`, `UNIQUE`)
         schema:
           type: string
           example: ALL
-      - name: prompt_tab
+      - name: promptTab
         in: query
         required: false
         description: Tab alias (`all-prompts`, `missing`, `shared`, `unique`)
@@ -512,7 +512,7 @@ ai-visibility-competitors-gap-prompts:
       - name: tab
         in: query
         required: false
-        description: Alternative tab parameter (same values as `prompt_tab`)
+        description: Alternative tab parameter (same values as `promptTab`)
         schema:
           type: string
     responses:
@@ -556,13 +556,13 @@ ai-visibility-prompts-responses-latest:
       Data from `PromptService/LastCrawledPromptByHash`.
     operationId: getAiVisibilityPromptsResponsesLatest
     parameters:
-      - name: prompt_hash
+      - name: promptHash
         in: query
         required: true
         description: Hash of the prompt to look up
         schema:
           type: string
-      - name: serp_id
+      - name: serpId
         in: query
         required: false
         description: SERP identifier for the prompt execution
@@ -671,7 +671,7 @@ ai-visibility-topics-stats:
     description: |
       Returns detailed statistics for a specific topic by ID,
       including brand mentions and visibility data.
-      Data from `TopicService/BrandTopics` filtered by `topic_id`.
+      Data from `TopicService/BrandTopics` filtered by `topicId`.
     operationId: getAiVisibilityTopicsStats
     parameters:
       - *domainParam
@@ -754,8 +754,8 @@ ai-visibility-topics-research-source-domains:
     description: |
       Returns source domains cited in LLM responses for a topic search query.
       Response is normalized to `{ data, total, offset, limit }` with rows
-      containing `source_domain`, `sources_count`, `mentions`, `organic_traffic`,
-      and optionally `prompt_example`.
+      containing `sourceDomain`, `sourcesCount`, `mentions`, `organicTraffic`,
+      and optionally `promptExample`.
       Data from `SourceService/SourceDomainsByTopicFTS` and `SourceDomainsByTopicFTSTotals`.
     operationId: getAiVisibilityTopicsResearchSourceDomains
     parameters:

docs/openapi/ai-visibility-api.yaml

@@ -8560,7 +8560,7 @@ AiVisibilityServiceUnavailable:
   properties:
     error:
       type: string
-      example: ai_visibility_not_configured
+      example: aiVisibilityNotConfigured
     message:
       type: string
       example: Missing AI_SEO_CLIENT_ID
@@ -8576,9 +8576,9 @@ AiVisibilityEngineBreakdown:
       type: number
     gemini:
       type: number
-    google_ai_mode:
+    googleAiMode:
       type: number
-    google_ai_overview:
+    googleAiOverview:
       type: number
 
 AiVisibilityByDateEntry:
@@ -8589,12 +8589,20 @@ AiVisibilityByDateEntry:
       type: integer
     month:
       type: integer
+    day:
+      type: integer
+    aiVisibility:
+      type: number
     mentions:
       $ref: '#/AiVisibilityEngineBreakdown'
-    cited_pages:
+    citedPages:
       $ref: '#/AiVisibilityEngineBreakdown'
-    visibility_by_engine:
+    visibilityByEngine:
       $ref: '#/AiVisibilityEngineBreakdown'
+    ownedSources:
+      type: integer
+    audience:
+      type: integer
 
 AiVisibilityByCountryEntry:
   type: object
@@ -8606,7 +8614,7 @@ AiVisibilityByCountryEntry:
       type: integer
     audience:
       type: integer
-    cited_pages:
+    citedPages:
       type: integer
 
 AiVisibilitySrFilters:
@@ -8636,15 +8644,25 @@ AiVisibilityBrandStats:
   type: object
   description: Brand visibility statistics response
   properties:
-    by_date:
+    visibility:
+      type: number
+    visibilityByEngine:
+      $ref: '#/AiVisibilityEngineBreakdown'
+    audience:
+      type: integer
+    mentions:
+      $ref: '#/AiVisibilityEngineBreakdown'
+    citedPages:
+      $ref: '#/AiVisibilityEngineBreakdown'
+    byDate:
       type: array
       items:
         $ref: '#/AiVisibilityByDateEntry'
-    by_country:
+    byCountry:
       type: array
       items:
         $ref: '#/AiVisibilityByCountryEntry'
-    sr_filters:
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   additionalProperties: true
 
@@ -8664,15 +8682,15 @@ AiVisibilityPaginatedResponse:
       type: integer
     limit:
       type: integer
-    sr_filters:
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   additionalProperties: true
 
 AiVisibilityCompetitorsMetrics:
   type: object
   description: Competitor comparison time-series response
   properties:
-    by_brand:
+    byBrand:
       type: array
       items:
         type: object
@@ -8684,7 +8702,7 @@ AiVisibilityCompetitorsMetrics:
                 type: string
               name:
                 type: string
-          by_date:
+          byDate:
             type: array
             items:
               type: object
@@ -8704,9 +8722,9 @@ AiVisibilityCompetitorsMetrics:
                   type: number
                 audience:
                   type: number
-                owned_sources:
+                ownedSources:
                   type: number
-    sr_filters:
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   additionalProperties: true
 
@@ -8722,19 +8740,19 @@ AiVisibilityGapPromptRow:
       type: string
     topic:
       type: string
-    topic_id:
+    topicId:
       type: string
-    topic_volume:
+    topicVolume:
       type: integer
     mentioned:
       type: boolean
     brands:
       type: integer
     sources:
       type: integer
-    prompt_hash:
+    promptHash:
       type: string
-    serp_id:
+    serpId:
       type: string
 
 AiVisibilityGapPromptsResponse:
@@ -8751,7 +8769,7 @@ AiVisibilityGapPromptsResponse:
       type: integer
     limit:
       type: integer
-    sr_filters:
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   required: [data, total, offset, limit]
 
@@ -8764,34 +8782,37 @@ AiVisibilityMeta:
       items:
         type: object
         properties:
-          country_code:
+          countryCode:
             type: string
             description: ISO country code
-          name:
-            type: string
-          snapshots:
+          daily:
             type: array
             items:
-              type: string
-              description: Available snapshot dates
-    sr_filters:
+              type: object
+          monthly:
+            type: array
+            items:
+              type: object
+          isComingSoon:
+            type: boolean
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   additionalProperties: true
 
 AiVisibilityTopicsResearchStats:
   type: object
   description: Aggregate statistics for topic research
   properties:
-    topics_total:
+    topicsTotal:
       type: integer
       description: Total number of distinct topics matching the query
-    brands_total:
+    brandsTotal:
       type: integer
       description: Total number of brands across matching topics
-    source_domains_total:
+    sourceDomainsTotal:
       type: integer
       description: Total number of source domains across matching topics
-    intent_breakdown:
+    intentBreakdown:
       type: array
       items:
         type: object
@@ -8800,26 +8821,26 @@ AiVisibilityTopicsResearchStats:
             type: string
           count:
             type: integer
-    related_topics_ai_volume:
+    relatedTopicsAiVolume:
       type: integer
       description: Aggregated AI volume for related topics
-    sr_filters:
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   additionalProperties: true
 
 AiVisibilitySourceDomainRow:
   type: object
   description: A source domain row in topic research
   properties:
-    source_domain:
+    sourceDomain:
       type: string
-    sources_count:
+    sourcesCount:
       type: integer
     mentions:
       type: integer
-    organic_traffic:
+    organicTraffic:
       type: integer
-    prompt_example:
+    promptExample:
       type: string
 
 AiVisibilitySourceDomainsResponse:
@@ -8836,6 +8857,6 @@ AiVisibilitySourceDomainsResponse:
       type: integer
     limit:
       type: integer
-    sr_filters:
+    srFilters:
       $ref: '#/AiVisibilitySrFilters'
   required: [data, total, offset, limit]