feat(backend): add recovery summary endpoint

[KaliszS]

Resolves #198

Summary by CodeRabbit

• New Features

  • Recovery summaries endpoint now returns daily recovery scores and related metrics (HRV, resting heart rate, SpO2) for a user within a date range, with cursor-based pagination.

• Documentation

  • Added recovery summary response examples and updated client integration guidance.

• Tests

  • New test suite validating payloads, metric mapping, ordering, range exclusion, null-component behavior, and pagination.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 937c1549-9eca-43eb-a6f6-e43e27cebf7f

📥 Commits

Reviewing files that changed from the base of the PR and between 2e7a243 and 1a6909d.

📒 Files selected for processing (1)

• backend/app/repositories/health_score_repository.py

🚧 Files skipped from review as they are similar to previous changes (1)

• backend/app/repositories/health_score_repository.py

---

📝 Walkthrough

Walkthrough

Implements the recovery summaries endpoint end-to-end: repository cursor-query for RECOVERY HealthScore rows, service filtering/mapping to RecoverySummary objects with pagination, API route wiring to parse dates and forward params, tests covering behavior and pagination, and docs + client example.

Changes

Recovery Summaries Feature

Layer / File(s)	Summary
Repository Query Layer for Recovery Records backend/app/repositories/health_score_repository.py	Adds cursor-pagination imports and get_recovery_summaries method that queries recovery-category HealthScore rows within a date range, applies tuple-based pagination, and returns dictionaries with parsed dates, provider/source, record ID, recovery_score, and safe-extracted component metrics.
Service Business Logic and Wiring backend/app/services/summaries_service.py	Adds HealthScore model and HealthScoreRepository imports, initializes repository instance, and introduces get_recovery_summaries method that queries the repository, filters by highest-priority source per recovery date, computes pagination cursors, and transforms component fields (resting heart rate, HRV RMSSD, SpO2) into RecoverySummary objects returned in a PaginatedResponse.
API Route Implementation backend/app/api/routes/v1/summaries.py	Removes unused HTTPException import and implements the recovery endpoint handler to parse start_date/end_date query parameters into datetimes and forward them with cursor and limit to the service.
Comprehensive Endpoint Tests backend/tests/api/v1/test_summaries.py	Adds HealthScoreCategory and HealthScoreFactory imports and introduces TestRecoverySummaryEndpoint with tests covering basic recovery response, component-metric mapping, empty ranges, date ordering, boundary exclusion, null-component handling, and pagination.
Response Documentation and Client Example docs/dev-guides/integration-guide.mdx	Adds RecoverySummary response example and extends the Python OpenWearablesClient example with get_recovery_summary that calls the new endpoint and returns paginated items.

Sequence Diagram

sequenceDiagram
  participant Client
  participant Route
  participant Service
  participant Repository
  participant Database
  Client->>Route: GET /users/{user_id}/summaries/recovery?start_date&end_date&cursor&limit
  Route->>Service: get_recovery_summaries(user_id, start, end, cursor, limit)
  Service->>Repository: get_recovery_summaries(db_session, user_id, start, end, cursor, limit)
  Repository->>Database: Execute RECOVERY query (date window, cursor tuple)
  Database-->>Repository: rows
  Repository-->>Service: list[dict(metrics, recorded_at, id, provider)]
  Service->>Service: filter by priority, map to RecoverySummary, build cursors
  Service-->>Route: PaginatedResponse[RecoverySummary]
  Route-->>Client: 200 JSON response

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• the-momentum/open-wearables#818: Both PRs touch the same HealthScore RECOVERY data path: #818 adds writing Whoop recovery (HealthScore.category=RECOVERY and component fields) into the health_scores model, while the main PR implements repository/service/endpoint logic to read/query those RECOVERY rows (including the same component fields) for recovery summaries.
• the-momentum/open-wearables#804: Both PRs modify the HealthScore repository/service layer and add endpoints for health-score-related data (the retrieved PR introduces HealthScoreRepository/service and endpoints while the main PR extends the same repository with get_recovery_summaries and wires a corresponding service/route).
• the-momentum/open-wearables#950: The changes are related: both PRs operate on RECOVERY health-score data—this main PR implements recovery-summary endpoints and queries HealthScore RECOVERY records while the retrieved PR migrates recovery_score from timeseries into the HealthScore model.

Suggested labels

health scores

Suggested reviewers

• bartmichalak
• czajkub

Poem

🐰 A little rabbit nods with glee,
From DB rows to JSON key,
HRV, SpO2 in tow,
Cursors stitch the stream’s flow,
Paginated metrics, off they go!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: implementing a new recovery summary endpoint in the backend API.
Linked Issues check	✅ Passed	The PR implements the recovery summary endpoint as required by issue #198. It uses parse_query_datetime for date parsing and creates the necessary service layer.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the /users/{user_id}/summaries/recovery endpoint and supporting infrastructure with no out-of-scope modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch recovery_summary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[railway-app]

🚅 Deployed to the open-wearables-pr-1027 environment in Open Wearables

Service	Status	Web	Updated (UTC)
celery-beat	✅ Success (View Logs)		May 12, 2026 at 11:06 am
celery-flower	✅ Success (View Logs)	Web	May 12, 2026 at 11:06 am
backend	✅ Success (View Logs)	Web	May 12, 2026 at 11:06 am
celery-worker	✅ Success (View Logs)		May 12, 2026 at 11:06 am
frontend	✅ Success (View Logs)	Web	May 12, 2026 at 11:06 am