Metadata-Version: 2.4
Name: whoop-py
Version: 0.1.0
Summary: Python client for the WHOOP API with OAuth 2.0 support
Project-URL: Homepage, https://github.com/kartheekpnsn/whoop-api
Project-URL: Repository, https://github.com/kartheekpnsn/whoop-api
Project-URL: Issues, https://github.com/kartheekpnsn/whoop-api/issues
Author-email: Kartheek Palepu <kartheekpnsn@gmail.com>
License: MIT
Keywords: api,fitness,health,oauth,wearable,whoop
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: authlib>=1.3.0
Requires-Dist: requests>=2.32.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: ipykernel>=6.29.0; extra == 'dev'
Requires-Dist: pandas>=2.2.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# whoop-api

Personal WHOOP data explorer using the [WHOOP API](https://developer.whoop.com/api).

## Structure

```
whoop.py      # WhoopClient (OAuth2 + API) and WhoopAPI (token persistence)
main.py       # CLI entry point
main.ipynb    # Interactive data exploration
```

## Auth Flow

```mermaid
sequenceDiagram
    participant U as User
    participant A as WhoopAPI
    participant W as WHOOP OAuth

    U->>A: WhoopAPI()
    A->>A: load token from disk
    alt no token / missing scopes
        A->>W: create_authorization_url()
        W-->>U: redirect URL
        U->>W: approve access
        W-->>U: redirect with code
        U->>A: paste redirect URL
        A->>W: fetch_token(code)
        W-->>A: access + refresh token
        A->>A: save token to disk
    else token expired
        A->>W: refresh_access_token()
        W-->>A: new token
        A->>A: save token to disk
    end
    A-->>U: authenticated WhoopClient
```

## Data Flow

```mermaid
flowchart LR
    E[.env\nCLIENT_ID\nCLIENT_SECRET\nREDIRECT_URI] --> API[WhoopAPI]
    T[.whoop_token.json] <-->|load / save| API
    API --> C[WhoopClient]
    C -->|GET| S[/sleep]
    C -->|GET| R[/recovery]
    C -->|GET| W[/workout]
    C -->|GET| CY[/cycle]
```

## Setup

```bash
pip install -r requirements.txt
```

**.env**
```
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
REDIRECT_URI=your_redirect_uri
```

Register your app at [developer.whoop.com](https://developer.whoop.com) to get credentials.

## Usage

**Script**
```bash
python main.py
```

**Notebook**
```bash
jupyter notebook main.ipynb
```

**Library**
```python
from dotenv import load_dotenv
from whoop import WhoopAPI

load_dotenv()

with WhoopAPI() as api:
    sleep = api.get_sleep_collection(start_date="2026-06-01")
    recovery = api.get_recovery_collection()
    workouts = api.get_workout_collection()
```

The first run opens an interactive auth flow and saves the token to `.whoop_token.json`. Subsequent runs reuse or auto-refresh it.

## API Reference

| Method | Description |
|---|---|
| `get_profile()` | User profile |
| `get_body_measurement()` | Height, weight, max HR |
| `get_sleep_collection(start, end)` | All sleep records |
| `get_sleep_by_id(id)` | Single sleep record |
| `get_sleep_stream(id)` | Raw HR/temp signal stream |
| `get_recovery_collection(start, end)` | All recovery scores |
| `get_recovery_for_cycle(cycle_id)` | Recovery for a cycle |
| `get_cycle_collection(start, end)` | All physiological cycles |
| `get_cycle_by_id(id)` | Single cycle |
| `get_workout_collection(start, end)` | All workouts |
| `get_workout_by_id(id)` | Single workout |

`start` / `end` are ISO date strings (e.g. `"2026-06-01"`). Defaults to the last 7 days.
