Metadata-Version: 2.4
Name: healthcloud-sdk
Version: 0.6.0
Summary: Python SDK for HealthCloud APIs.
Author: Healthcheck Systems Inc
License-Expression: MIT
Keywords: api,health-cloud,healthcare,healthcloud,sdk
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# HealthCloud SDK for Python

Typed Python SDK for HealthCloud services and the HealthCloud Connectors gateway.

## Installation

```bash
pip install healthcloud-sdk
```

For local development:

```bash
pip install -e ./packages/pip
```

Python 3.9 or newer is required.

## Create and authenticate a client

The current API uses typed request objects. Authentication returns typed response
objects; after registration or login, explicitly share the access token with the
whole SDK by calling `set_access_token`.

```python
from healthcloud import HCSDK, LoginRequest, RegisterPatientRequest

sdk = HCSDK(environment="dev", tenant_id="your-tenant-id")

registration = sdk.auth.register(RegisterPatientRequest(
    first_name="Jane",
    last_name="Doe",
    email="patient@example.com",
    password="SecurePassword123!",
    date_of_birth="1990-06-15",
    sex_at_birth="female",
))

token = registration.access_token
if not token:
    login = sdk.auth.login(LoginRequest(
        email="patient@example.com",
        password="SecurePassword123!",
    ))
    token = login.access_token

sdk.set_access_token(token)
```

In UAT and production, complete email verification before login when the register
response reports that verification is required.

```python
from healthcloud import VerifyOtpRequest

sdk.auth.verify_email(VerifyOtpRequest(
    user_id=registration.cognito_sub,
    otp="123456",
))
```

## Service clients

One `HCSDK` instance exposes these clients:

```python
sdk.auth
sdk.patient
sdk.vitals
sdk.diagnostics
sdk.assistant
sdk.communications
sdk.fieldagent
sdk.mcp
sdk.connectivity

# Service clients whose public SDK surface is currently connect-only:
sdk.appointments
sdk.ehr
sdk.provider
sdk.rppg
sdk.session
sdk.telehealth
```

All typed methods accept the request model shown in their signature and return a
typed response model. Examples:

```python
from healthcloud import SubmitVitalsRequest, UpdatePhoneRequest

patient = sdk.patient.get_patient("patient-id")

phone = sdk.patient.set_phone(
    "patient-id",
    UpdatePhoneRequest(phone="+15550001234"),
)

vitals = sdk.vitals.submit(
    "patient-id",
    SubmitVitalsRequest(
        heart_rate=72,
        systolic=120,
        diastolic=80,
    ),
)

history = sdk.vitals.get_vitals("patient-id")
tools = sdk.mcp.list_tools("patient")
```

Use `sdk.set_access_token(new_token)` whenever a token changes. This updates every
authenticated service client and every vendor client on the SDK instance.

## Vendor connectors

Vendor methods are called through `sdk.vendors`; they are not raw HTTP helpers.
The package contains 32 vendor clients:

`anthropic`, `apple_auth`, `athena_health`, `cal`, `carequality`, `cms`,
`connecture`, `elevenlabs`, `fedex`, `google_ai`, `google_places`, `grok`,
`healthie`, `impilo`, `junction`, `nppes`, `openai`, `oura`, `plaid`, `quest`,
`salesforce`, `scrapfly`, `senaite`, `sendgrid`, `steadymd`, `stedi`, `stripe`,
`twilio`, `uber`, `whoop`, `zocdoc`, and `zus`.

Vendor credentials are read when `HCSDK` constructs its vendor clients. Set the
relevant environment variables before creating the SDK. Credentials are then sent
to the HealthCloud Connectors gateway so it can construct the vendor integration.

```powershell
$env:HC_ATHENA_SECRET_KEY="..."
$env:HC_ATHENA_PRACTICE_ID="..."
$env:HC_STRIPE_API_KEY="..."
$env:HC_TWILIO_ACCOUNT_SID="..."
$env:HC_TWILIO_AUTH_TOKEN="..."
$env:HC_STEDI_API_KEY="..."
$env:HC_WHOOP_CLIENT_ID="..."
$env:HC_WHOOP_CLIENT_SECRET="..."
$env:HC_OURA_CLIENT_ID="..."
$env:HC_OURA_CLIENT_SECRET="..."
```

Representative package-method calls:

```python
sdk = HCSDK(
    environment="dev",
    tenant_id="your-tenant-id",
    access_token="cognito-access-token",
)

patients = sdk.vendors.athena_health.search_patients(
    last_name="Smith",
    limit=5,
)

stripe_status = sdk.vendors.stripe.verify_connection()
messages = sdk.vendors.twilio.list_messages(page_size=10)
provider = sdk.vendors.stedi.verify_provider("1234567893")

whoop_url = sdk.vendors.whoop.build_authorization_url(
    redirect_uri="https://example.com/whoop/callback",
)
oura_url = sdk.vendors.oura.build_authorization_url(
    redirect_uri="https://example.com/oura/callback",
)
```

Set a vendor-specific mode variable such as `HC_ATHENA_MODE`, `HC_WHOOP_MODE`,
or `HC_OURA_MODE` to `sandbox` or `live` before constructing `HCSDK`. Sandbox is
the default where the connector supports it.

## Errors and cleanup

```python
from healthcloud import HealthCloudHTTPError, HealthCloudNetworkError

try:
    sdk.vendors.stripe.verify_connection()
except HealthCloudHTTPError as exc:
    print(exc.status_code, str(exc))
except HealthCloudNetworkError as exc:
    print(str(exc))
finally:
    sdk.close()
```

## Verification

From `packages/pip`:

```powershell
.\.venv\Scripts\python.exe -m pytest -q -m "not live"
```

Live integration tests are opt-in and use package methods:

```powershell
$env:HC_RUN_INTEGRATION="true"
$env:HC_ALLOW_REGISTER="true"
.\.venv\Scripts\python.exe -m pytest -q -m live
```

Do not commit `.env` files or vendor credentials.
