feat: add ultrahuman provider

[gudvin-byte]

Description

Adds support for Ultrahuman Ring Air wearable device, implementing OAuth authentication and 24/7 data synchronization including sleep sessions (with stages: awake, light, deep, REM), recovery metrics, and activity samples (heart rate, temperature, movement). The implementation follows the existing provider pattern used by Garmin, Whoop, and others.

Related Issue

N/A (new provider implementation)

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Checklist

General

• My code follows the project's code style
• I have performed a self-review of my code
• I have added tests that prove my fix/feature works (if applicable)
• New and existing tests pass locally

Backend Changes

• uv run ruff check passes
• uv run ruff format --check passes
• uv run ty check passes

Frontend Changes

• pnpm run lint passes
• pnpm run format:check passes
• pnpm run build succeeds

Testing Instructions

Steps to test:

1. Configure Ultrahuman OAuth credentials in backend/config/.env (add ULTRAHUMAN_CLIENT_ID, ULTRAHUMAN_CLIENT_SECRET, ULTRAHUMAN_REDIRECT_URI)
2. Important: Set ULTRAHUMAN_REDIRECT_URI to https:// URL (not http://), e.g., https://yourdomain.com/widget.connect
3. Run migrations: make migrate
4. Start services: docker compose up -d
5. Navigate to https://yourdomain.com and create/connect an Ultrahuman account
6. Trigger data sync for the Ultrahuman connection
7. Verify sleep sessions are saved: GET /api/v1/users/{user_id}/events/sleep?start_date={date}&end_date={date}
8. Verify timeseries data: GET /api/v1/users/{user_id}/timeseries?start_time={iso}&end_time={iso}&types=heart_rate,temperature

Expected behavior:

• OAuth flow redirects to Ultrahuman authorization and creates an active connection
• Data sync successfully fetches and stores sleep sessions with efficiency scores and stage breakdown
• Timeseries samples (heart rate, temperature, movement) are saved to the database
• Sleep API returns sessions with correct efficiency_percent and stages (awake_minutes, light_minutes, deep_minutes, rem_minutes)

Screenshots

N/A (backend-only changes)

Additional Notes

• Provider follows existing patterns from Garmin/Whoop implementations
• Uses Ultrahuman Partner API: https://partner.ultrahuman.com/api/partners/v1
• OAuth uses client_secret in request body (not PKCE)
• Comprehensive test suite includes 35 tests covering OAuth, data normalization, and full integration flows
• Includes verification script at backend/scripts/verify_ultrahuman_integration.py for end-to-end testing

Implementation Caveats

• HTTPS redirect URI required: Ultrahuman API only accepts HTTPS redirect URIs; http:// will be rejected
• Unique sample IDs: Timeseries samples don't have unique IDs from Ultrahuman API; we rely on database unique constraint (user_id, provider_name, series_type, recorded_at) to prevent duplicates
• Sleep efficiency fallback: If sleep efficiency is missing from quick_metrics["sleep_efic"], we fall back to the top-level sleep_efficiency field
• Data type compatibility: normalize_activity_samples method signature differs from the base template (expects dict instead of list) due to Ultrahuman's response structure; this is handled internally and doesn't affect the public API

[bartmichalak]

Hello @gudvin-byte, thanks for your contribution! Our team will do a review after the weekend.

PS Are you already on our Discord? If not, be sure to join!
https://discord.gg/qrcfFnNE6H

[bartmichalak]

And in the meantime you can fix code quality issues :)

[KaliszS]

And in the meantime you can fix code quality issues :)

The fastest method would be uv run pre-commit run --all-files from backend directory imo.

[gudvin-byte]

Hello guys! I've joined your discord channel. Code quality checks also passed ^^

[KaliszS]

Thanks for the contribution! Integration seems to be done correctly (well done), but could you provide some screenshoots of how it works? Our frontend would be the best, just to check if it integrates correctly. None of developers has an access to superhuman device, so right now we cannot check it on our own sadly.

[KaliszS]

I don't think that is required. I would removed that script.

[KaliszS]

That's am LLM artifact, also to remove :)

[KaliszS]

another file which shouldn't be generated here

[bartmichalak]

@gudvin-byte are you still working on this? PR is marked as a draft.

[gudvin-byte]

@gudvin-byte are you still working on this? PR is marked as a draft.

Yes, still in progress. Fine tuning small last small bits

[bartmichalak]

Sure, thanks for confirmation!

[bartmichalak]

@gudvin-byte hey, wanted to check how's this going?

We'd love to add support for this provider. I think there are just a few small things left to address here - any chance you could pick them up soon?

[gudvin-byte]

Hey @bartmichalak Had to make a break for another priorities, but will work on it this weekend. Need to polish the normalization layer

[KaliszS]

@gudvin-byte nobody likes conflicts, so I've resolved them for you (especially it happened because of our changes in main branch).

But now you need to fetch changes before you do the next commit in order to preserve that merge.

[bartmichalak]

@gudvin-byte are you still planning to finish this integration?
I'm currently waiting for a shipment from Ultrahuman, and once it arrives I'll be able to verify the integration and finish up whatever's left to implement, if you don't have the bandwidth.

We'd love to get this integration live :)