fix: Handle partial sync failures gracefully (issue #19) (#20)

* fix: Handle partial sync failures gracefully (issue #19)

Previously, if one Polar API endpoint returned an error (e.g., 403 on
sleep due to missing consents), the entire sync would fail and no data
would be synced.

Now:
- Each endpoint is wrapped in try/except - failures don't stop other syncs
- SyncResult dataclass tracks both successful records and errors
- 403 errors include actionable guidance about Polar consent settings
- Admin UI shows partial success with both synced data and error details
- SyncOrchestrator properly logs partial success status

Also bumps version to 1.3.3 with updated CHANGELOG.

Closes #19

* feat: Manual sync now creates SyncLog entries for audit trail

- Admin "Sync Now" button now uses SyncOrchestrator instead of SyncService directly
- This ensures all manual syncs are properly logged in sync_logs table
- SyncOrchestrator now stores error_details for partial success (not just total failure)
- Updated CHANGELOG with manual sync audit logging fix

* feat: Add expandable sync log details in admin dashboard

- Click any sync log row to expand/collapse detailed view
- Shows breakdown of records synced per endpoint
- Shows error type and message for failed/partial syncs
- Shows analytics status (baselines, patterns, insights)
- Shows metadata (job ID, API calls, priority)
- Updated Records column to show total count instead of "X types"

* style: Fix ruff formatting

Author: StuMason

.github/workflows/claude-code-review.yml

@@ -2,7 +2,7 @@ name: Claude Code Review
 
 on:
   pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
+    types: [opened, ready_for_review, reopened]
 
 jobs:
   claude-review:

CHANGELOG.md

@@ -9,6 +9,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.3] - 2026-01-21
+
+### Fixed
+
+**Partial Sync Failure Handling (Issue #19)**
+- Sync now continues when individual Polar API endpoints fail (e.g., 403 on sleep)
+- Previously, a single endpoint failure would stop the entire sync with no data saved
+- Now syncs each endpoint independently - failures are captured but don't block other data
+
+**Manual Sync Audit Logging**
+- Admin "Sync Now" button now creates `SyncLog` entries for proper audit trail
+- Previously, manual syncs bypassed `SyncOrchestrator` and weren't logged
+
+### Added
+
+- `SyncResult` dataclass to track both successful records and per-endpoint errors
+- Actionable error messages for common HTTP errors:
+  - 403: Guidance about Polar data sharing consent settings
+  - 401: Token expiration/re-authentication needed
+  - 429: Rate limit information
+- Partial success UI template showing both synced data and errors
+- Dynamic endpoint display in templates (all 13 data types now shown)
+- API sync endpoint now returns `status: "partial"` with error details when some endpoints fail
+- Expandable sync log rows in admin dashboard showing full details (records, errors, analytics, metadata)
+
+### Changed
+
+- `SyncService.sync_user()` now returns `SyncResult` instead of `dict[str, int]`
+- `SyncOrchestrator` properly tracks partial success status in `SyncLog`
+- Admin sync templates dynamically iterate over all endpoints instead of hardcoding
+
+---
+
+## [1.3.2] - 2026-01-20
+
+### Fixed
+
+- CSRF cookie configuration for proxy deployments
+- Admin route CSRF exclusions
+
+---
+
+## [1.3.1] - 2026-01-20
+
+### Fixed
+
+- Version mismatch between pyproject.toml and __init__.py
+
+---
+
+## [1.3.0] - 2026-01-20
+
+### Added
+
+- MCP server integration for Claude Desktop
+- Additional Polar SDK endpoints (cardio load, sleepwise, biosensing)
+
+---
+
 ## [1.2.0] - 2026-01-13
 
 ### Added

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polar-flow-server"
-version = "1.3.2"
+version = "1.3.3"
 description = "Self-hosted health analytics server for Polar devices"
 readme = "README.md"
 authors = [

src/polar_flow_server/__init__.py

@@ -1,5 +1,5 @@
 """polar-flow-server - Self-hosted health analytics server for Polar devices."""
 
-__version__ = "1.3.2"
+__version__ = "1.3.3"
 
 __all__ = ["__version__"]

src/polar_flow_server/admin/routes.py

@@ -49,11 +49,11 @@
 from polar_flow_server.models.sleepwise_alertness import SleepWiseAlertness
 from polar_flow_server.models.sleepwise_bedtime import SleepWiseBedtime
 from polar_flow_server.models.spo2 import SpO2
-from polar_flow_server.models.sync_log import SyncLog
+from polar_flow_server.models.sync_log import SyncLog, SyncTrigger
 from polar_flow_server.models.temperature import BodyTemperature, SkinTemperature
 from polar_flow_server.models.user import User
 from polar_flow_server.services.scheduler import get_scheduler
-from polar_flow_server.services.sync import SyncService
+from polar_flow_server.services.sync_orchestrator import SyncOrchestrator
 
 logger = logging.getLogger(__name__)
 
@@ -918,24 +918,55 @@ async def trigger_manual_sync(request: Request[Any, Any, Any], session: AsyncSes
         polar_token = env_token
         user_id = "self"
 
-    # Run sync
-    sync_service = SyncService(session)
+    # Run sync via orchestrator (creates SyncLog entry for audit trail)
+    orchestrator = SyncOrchestrator(session)
     try:
-        results = await sync_service.sync_user(
+        sync_log = await orchestrator.sync_user(
             user_id=user_id,
             polar_token=polar_token,
-            days=settings.sync_days_lookback,
+            trigger=SyncTrigger.MANUAL,
         )
 
         # Get updated counts
         sleep_count = (await session.execute(select(func.count(Sleep.id)))).scalar() or 0
         exercise_count = (await session.execute(select(func.count(Exercise.id)))).scalar() or 0
         activity_count = (await session.execute(select(func.count(Activity.id)))).scalar() or 0
 
+        # Check sync status
+        if sync_log.status == "partial":
+            # Partial success - some endpoints worked, some failed
+            errors = sync_log.error_details.get("errors", {}) if sync_log.error_details else {}
+            return Template(
+                template_name="admin/partials/sync_partial.html",
+                context={
+                    "results": sync_log.records_synced or {},
+                    "errors": errors,
+                    "sleep_count": sleep_count,
+                    "exercise_count": exercise_count,
+                    "activity_count": activity_count,
+                },
+            )
+        elif sync_log.status == "failed":
+            # Total failure - all endpoints failed
+            errors_raw = sync_log.error_details.get("errors", {}) if sync_log.error_details else {}
+            # errors_raw is dict[str, str] but typed as object, cast for iteration
+            errors = errors_raw if isinstance(errors_raw, dict) else {}
+            if errors:
+                error_messages = "\n".join(
+                    f"• {endpoint}: {msg}" for endpoint, msg in errors.items()
+                )
+            else:
+                error_messages = sync_log.error_message or "Sync failed"
+            return Template(
+                template_name="admin/partials/sync_error.html",
+                context={"error": error_messages},
+            )
+
+        # Full success - no errors
         return Template(
             template_name="admin/partials/sync_success.html",
             context={
-                "results": results,
+                "results": sync_log.records_synced or {},
                 "sleep_count": sleep_count,
                 "exercise_count": exercise_count,
                 "activity_count": activity_count,

src/polar_flow_server/api/sync.py

@@ -1,6 +1,6 @@
 """Sync API endpoints."""
 
-from typing import Annotated
+from typing import Annotated, Any
 
 from litestar import Router, post
 from litestar.params import Parameter
@@ -20,7 +20,7 @@ async def trigger_sync(
     session: AsyncSession,
     polar_token: Annotated[str, Parameter(header="X-Polar-Token")],
     days: Annotated[int | None, Parameter(query="days", ge=1, le=365)] = None,
-) -> dict[str, str | dict[str, int]]:
+) -> dict[str, Any]:
     """Trigger data sync for a user.
 
     Args:
@@ -30,24 +30,26 @@ async def trigger_sync(
         days: Number of days to sync (optional, uses config default)
 
     Returns:
-        Sync results with counts per data type
+        Sync results with counts per data type and any errors
 
     Example:
         POST /api/v1/users/12345/sync/trigger?days=30
         Headers: X-Polar-Token: <access_token>
     """
     sync_service = SyncService(session)
 
-    results = await sync_service.sync_user(
+    sync_result = await sync_service.sync_user(
         user_id=user_id,
         polar_token=polar_token,
         days=days,
     )
 
     return {
-        "status": "success",
+        "status": "partial" if sync_result.has_errors else "success",
         "user_id": user_id,
-        "results": results,
+        "records": sync_result.records,
+        "errors": sync_result.errors if sync_result.has_errors else None,
+        "total_records": sync_result.total_records,
     }
 
 

src/polar_flow_server/services/__init__.py

@@ -4,13 +4,14 @@
 from polar_flow_server.services.insights import InsightsService
 from polar_flow_server.services.observations import ObservationGenerator
 from polar_flow_server.services.pattern import AnomalyService, PatternService
-from polar_flow_server.services.sync import SyncService
+from polar_flow_server.services.sync import SyncResult, SyncService
 
 __all__ = [
     "AnomalyService",
     "BaselineService",
     "InsightsService",
     "ObservationGenerator",
     "PatternService",
+    "SyncResult",
     "SyncService",
 ]