[PR #429] Unify GSC analytics response contract and status-driven consumers #733

New issue

Open

opened 2026-03-13 21:06:25 +03:00 by kerem · 0 comments

kerem commented

2026-03-13 21:06:25 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/AJaySi/ALwrity/pull/429
Author: @AJaySi
Created: 3/12/2026
Status: 🔄 Open

Base: main ← Head: codex/define-consistent-response-contract-for-get_search_analytics-ren1d4

📝 Commits (1)

fa05388 Unify GSC analytics response contract and status-based consumers

📊 Changes

4 files changed (+127 additions, -82 deletions)

View changed files

📝 backend/api/content_planning/services/content_strategy/autofill/normalizers/analytics_normalizer.py (+7 -2)
📝 backend/services/analytics/handlers/gsc_handler.py (+30 -61)
📝 backend/services/gsc_service.py (+85 -14)
📝 backend/services/scheduler/executors/gsc_insights_executor.py (+5 -5)

📄 Description

Motivation

Ensure get_search_analytics always returns a single, predictable shape so downstream code can rely on keys rather than presence checks.
Replace ad-hoc early returns (auth failure, not connected, no data, verification/API errors, exceptions) with structured responses that include a status marker and empty collections.
Normalize cached/legacy payloads so previously cached responses conform to the new contract.
Simplify and harden consumers (handler, scheduler, onboarding normalizers) to use status + guaranteed keys instead of brittle key-existence logic.

Description

Added helper builders inside GSCService.get_search_analytics: _base_payload(status, error) and _normalize_payload(payload) that guarantee the unified contract with keys: overall_metrics.rows, query_data.rows, page_data.rows, query_page_data.rows, verification_data.rows, date_range (start/end), site_url, startDate/endDate/siteUrl aliases, status, and optional error/warning.
Refactored all early-return branches in get_search_analytics to return the canonical payload with appropriate status values (examples: not_connected, auth_failed, no_data, verification_failed, api_error, partial_success, success, error) and empty arrays instead of ad-hoc dict shapes.
Normalized successful and partial-success responses to include canonical date_range, site_url, and status and ensure cached responses are converted via _normalize_payload before being returned.
Updated consumers to rely on status and guaranteed keys: backend/services/analytics/handlers/gsc_handler.py now derives metrics from overall_metrics/query_data and computes connection status from status; backend/services/scheduler/executors/gsc_insights_executor.py checks status rather than presence of 'error'; onboarding normalizer normalize_gsc_analytics gates processing based on status.

Testing

Ran python -m compileall backend/services/gsc_service.py backend/services/analytics/handlers/gsc_handler.py backend/services/scheduler/executors/gsc_insights_executor.py backend/api/content_planning/services/content_strategy/autofill/normalizers/analytics_normalizer.py and all modified modules compiled without syntax errors.
No automated unit tests were added or modified as part of this change.

Codex Task

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/AJaySi/ALwrity/pull/429 **Author:** [@AJaySi](https://github.com/AJaySi) **Created:** 3/12/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/define-consistent-response-contract-for-get_search_analytics-ren1d4` --- ### 📝 Commits (1) - [`fa05388`](https://github.com/AJaySi/ALwrity/commit/fa05388b02df95dd7e73260faad0fecd7e4419ff) Unify GSC analytics response contract and status-based consumers ### 📊 Changes **4 files changed** (+127 additions, -82 deletions) <details> <summary>View changed files</summary> 📝 `backend/api/content_planning/services/content_strategy/autofill/normalizers/analytics_normalizer.py` (+7 -2) 📝 `backend/services/analytics/handlers/gsc_handler.py` (+30 -61) 📝 `backend/services/gsc_service.py` (+85 -14) 📝 `backend/services/scheduler/executors/gsc_insights_executor.py` (+5 -5) </details> ### 📄 Description ### Motivation - Ensure `get_search_analytics` always returns a single, predictable shape so downstream code can rely on keys rather than presence checks. - Replace ad-hoc early returns (auth failure, not connected, no data, verification/API errors, exceptions) with structured responses that include a `status` marker and empty collections. - Normalize cached/legacy payloads so previously cached responses conform to the new contract. - Simplify and harden consumers (handler, scheduler, onboarding normalizers) to use `status` + guaranteed keys instead of brittle key-existence logic. ### Description - Added helper builders inside `GSCService.get_search_analytics`: `_base_payload(status, error)` and `_normalize_payload(payload)` that guarantee the unified contract with keys: `overall_metrics.rows`, `query_data.rows`, `page_data.rows`, `query_page_data.rows`, `verification_data.rows`, `date_range` (`start`/`end`), `site_url`, `startDate`/`endDate`/`siteUrl` aliases, `status`, and optional `error`/`warning`. - Refactored all early-return branches in `get_search_analytics` to return the canonical payload with appropriate `status` values (examples: `not_connected`, `auth_failed`, `no_data`, `verification_failed`, `api_error`, `partial_success`, `success`, `error`) and empty arrays instead of ad-hoc dict shapes. - Normalized successful and partial-success responses to include canonical `date_range`, `site_url`, and `status` and ensure cached responses are converted via `_normalize_payload` before being returned. - Updated consumers to rely on `status` and guaranteed keys: `backend/services/analytics/handlers/gsc_handler.py` now derives metrics from `overall_metrics/query_data` and computes connection status from `status`; `backend/services/scheduler/executors/gsc_insights_executor.py` checks `status` rather than presence of `'error'`; onboarding normalizer `normalize_gsc_analytics` gates processing based on `status`. ### Testing - Ran `python -m compileall backend/services/gsc_service.py backend/services/analytics/handlers/gsc_handler.py backend/services/scheduler/executors/gsc_insights_executor.py backend/api/content_planning/services/content_strategy/autofill/normalizers/analytics_normalizer.py` and all modified modules compiled without syntax errors. - No automated unit tests were added or modified as part of this change. ------ [Codex Task](https://chatgpt.com/codex/tasks/task_e_69b26cbb23008328b77f91ae995377e9) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem added the

pull-request

label

2026-03-13 21:06:25 +03:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/ALwrity#733

No description provided.

Rows
Columns