healthcloud-sdk 0.6.0

Python SDK for HealthCloud APIs.

HealthCloud SDK for Python

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

Installation

pip install healthcloud-sdk

For local development:

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.

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="[e-mail]",
    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="[e-mail]",
        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.

from healthcloud import VerifyOtpRequest

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

Service clients

One HCSDK instance exposes these clients:

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:

from healthcloud import SubmitVitalsRequest, UpdatePhoneRequest

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

phone = sdk.patient.set_phone(
    "patient-id",
    UpdatePhoneRequest(phone="[phone]"),
)

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.

$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:

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

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:

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

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

$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.