Metadata-Version: 2.4
Name: healthcloud-sdk
Version: 0.7.3
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 connector client on the SDK instance.

## Connectors

Connector methods are called through `sdk.connectors`; they are not raw HTTP helpers.
The package contains 33 connector clients.

### Architecture

Connector clients are created in three explicit steps:

1. Configure HealthCloud once through `HCSDK` (environment, tenant, access token).
2. Create an isolated connector client with that connector's vendor credentials via
   `sdk.connectors.<name>.create_client(...)`.
3. Call typed operation methods with operation-specific parameters only.

The connector gateway URL is resolved internally from the HealthCloud environment;
applications never pass connector base URLs or the HealthCloud bearer token again
when creating a connector client. Each client holds its vendor credentials only on
that instance and forwards them to the HealthCloud Connectors gateway
(`POST /connectors/<slug>/<operation>`) with every request. Connector-scoped
secrets cannot be overridden by operation input, and gateway errors are redacted
before being raised.

Create a credential-scoped connector client explicitly. The SDK never reads connector
credentials implicitly; applications can load them from their own secret manager or
the local `.env` used by integration tests. Do not hardcode credentials in source
code and do not create connector clients in client-side code.

### Usage

```python
import os

from healthcloud import HCSDK

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

athena = sdk.connectors.athena_health.create_client(
    secret_key=os.environ["HC_ATHENA_SECRET_KEY"],
    practice_id=os.environ["HC_ATHENA_PRACTICE_ID"],
    department_id=os.environ["HC_ATHENA_DEPARTMENT_ID"],
    provider_id=os.environ["HC_ATHENA_PROVIDER_ID"],
)
patients = athena.search_patients(
    last_name="Smith",
    limit=5,
)

stripe = sdk.connectors.stripe.create_client(api_key=os.environ["HC_STRIPE_API_KEY"])
stripe_status = stripe.verify_connection()

# Public connector — no vendor credentials required
nppes = sdk.connectors.nppes.create_client()
provider = nppes.verify_provider(npi="1234567890")

# OAuth-style connector
whoop = sdk.connectors.whoop.create_client(
    client_id=os.environ["HC_WHOOP_CLIENT_ID"],
    client_secret=os.environ["HC_WHOOP_CLIENT_SECRET"],
)
```

Pass `mode="live"` only when required; `mode="sandbox"` is the default for
mode-aware connectors. Calling `sdk.set_access_token(...)` propagates the new
HealthCloud token to every connector client already created.

### Available connectors

The table lists each connector's required credential keyword arguments and the
conventional `HC_*` environment variable names used by the live test suite
(names only — never commit values). Parameters marked `mode?` accept
`"sandbox"` (default) or `"live"`.

| Connector | Purpose | `create_client` credentials | Suggested env vars | Called via |
|---|---|---|---|---|
| `anthropic` | Anthropic (Claude) LLM completions | `api_key`, `mode?` | `HC_ANTHROPIC_API_KEY` | `sdk.connectors.anthropic.create_client(...)` |
| `apple_auth` | Sign in with Apple token exchange | `team_id`, `client_id`, `key_id`, `redirect_uri`, `private_key` | `HC_APPLE_AUTH_TEAM_ID`, `HC_APPLE_AUTH_CLIENT_ID`, `HC_APPLE_AUTH_KEY_ID`, `HC_APPLE_AUTH_REDIRECT_URI`, `HC_APPLE_AUTH_PRIVATE_KEY` | `sdk.connectors.apple_auth.create_client(...)` |
| `athena_health` | athenahealth EHR (patients, appointments) | `secret_key`, `practice_id`, `department_id`, `provider_id`, `mode?` | `HC_ATHENA_SECRET_KEY`, `HC_ATHENA_PRACTICE_ID`, `HC_ATHENA_DEPARTMENT_ID`, `HC_ATHENA_PROVIDER_ID` | `sdk.connectors.athena_health.create_client(...)` |
| `cal` | Cal.com scheduling and bookings | `api_key` | `HC_CAL_API_KEY` | `sdk.connectors.cal.create_client(...)` |
| `carequality` | Carequality health information exchange | `api_key`, `initiator_url` | `HC_CAREQUALITY_API_KEY`, `HC_CAREQUALITY_INITIATOR_URL` | `sdk.connectors.carequality.create_client(...)` |
| `cms` | CMS (Centers for Medicare & Medicaid) data | `api_key` | `HC_CMS_API_KEY` | `sdk.connectors.cms.create_client(...)` |
| `connecture` | ConnectureDRX Medicare plan shopping | `basic_token`, `client_key`, `client_secret` | `HC_CONNECTURE_BASIC_TOKEN`, `HC_CONNECTURE_CLIENT_KEY`, `HC_CONNECTURE_CLIENT_SECRET` | `sdk.connectors.connecture.create_client(...)` |
| `elevenlabs` | ElevenLabs text-to-speech | `api_key` | `HC_ELEVENLABS_API_KEY` | `sdk.connectors.elevenlabs.create_client(...)` |
| `fedex` | FedEx shipping and tracking | `client_id`, `client_secret`, `account_number`, `mode?` | `HC_FEDEX_CLIENT_ID`, `HC_FEDEX_CLIENT_SECRET`, `HC_FEDEX_ACCOUNT_NUMBER` | `sdk.connectors.fedex.create_client(...)` |
| `google_ai` | Google AI (Gemini) LLM | `api_key` | `HC_GOOGLE_AI_API_KEY` | `sdk.connectors.google_ai.create_client(...)` |
| `google_places` | Google Places search/geocoding | `api_key`, `mode?` | `HC_GOOGLE_PLACES_API_KEY` | `sdk.connectors.google_places.create_client(...)` |
| `grok` | xAI Grok LLM | `api_key` | `HC_GROK_API_KEY` | `sdk.connectors.grok.create_client(...)` |
| `healthie` | Healthie EHR / practice management | `secret_key`, `mode?`, `shard_id?` | `HC_HEALTHIE_SECRET_KEY`, `HC_HEALTHIE_AUTHORIZATION_SHARD` | `sdk.connectors.healthie.create_client(...)` |
| `impilo` | Impilo remote patient monitoring logistics | `api_key` | `HC_IMPILO_API_KEY` | `sdk.connectors.impilo.create_client(...)` |
| `junction` | Junction (Vital) lab testing and wearables | `api_key` | `HC_JUNCTION_API_KEY` | `sdk.connectors.junction.create_client(...)` |
| `nppes` | NPPES NPI registry lookup (public, no credentials) | — | — | `sdk.connectors.nppes.create_client()` |
| `openai` | OpenAI LLM completions | `api_key` | `HC_OPENAI_API_KEY` | `sdk.connectors.openai.create_client(...)` |
| `oura` | Oura ring wearable data (OAuth) | `client_id`, `client_secret`, `mode?` | `HC_OURA_CLIENT_ID`, `HC_OURA_CLIENT_SECRET` | `sdk.connectors.oura.create_client(...)` |
| `plaid` | Plaid identity / financial verification | `client_id`, `secret`, `template_id`, `mode?` | `HC_PLAID_CLIENT_ID`, `HC_PLAID_SECRET`, `HC_PLAID_TEMPLATE_ID` | `sdk.connectors.plaid.create_client(...)` |
| `quest` | Quest Diagnostics — REST-style orders/results/catalog **and** HL7 orders, results, compendium | `client_id`, `client_secret`, `mode?` | `HC_QUEST_CLIENT_ID`, `HC_QUEST_CLIENT_SECRET` | `sdk.connectors.quest.create_client(...)` |
| `salesforce` | Salesforce CRM records and queries | `client_id`, `client_secret`, `username`, `password`, `mode?` | `HC_SALESFORCE_CLIENT_ID`, `HC_SALESFORCE_CLIENT_SECRET`, `HC_SALESFORCE_USERNAME`, `HC_SALESFORCE_PASSWORD` | `sdk.connectors.salesforce.create_client(...)` |
| `scrapfly` | Scrapfly web scraping | `api_key` | `HC_SCRAPFLY_API_KEY` | `sdk.connectors.scrapfly.create_client(...)` |
| `senaite` | SENAITE LIMS (lab information management) | `base_url`, `username`, `password` | `HC_SENAITE_BASE_URL`, `HC_SENAITE_USERNAME`, `HC_SENAITE_PASSWORD` | `sdk.connectors.senaite.create_client(...)` |
| `sendgrid` | SendGrid transactional email | `api_key`, `mode?` | `HC_SENDGRID_API_KEY` | `sdk.connectors.sendgrid.create_client(...)` |
| `steadymd` | SteadyMD telehealth clinician network | `api_key` **or** `token` (exactly one), `mode?`, `api_url?` | `HC_STEADYMD_API_KEY` or `HC_STEADYMD_TOKEN`, `HC_STEADYMD_API_URL` | `sdk.connectors.steadymd.create_client(...)` |
| `stedi` | Stedi insurance eligibility (X12/EDI) | `api_key` | `HC_STEDI_API_KEY` | `sdk.connectors.stedi.create_client(...)` |
| `stripe` | Stripe payments and subscriptions | `api_key` | `HC_STRIPE_API_KEY` | `sdk.connectors.stripe.create_client(...)` |
| `twilio` | Twilio SMS / voice messaging | `account_sid`, `auth_token`, `from_number`, `mode?` | `HC_TWILIO_ACCOUNT_SID`, `HC_TWILIO_AUTH_TOKEN`, `HC_TWILIO_FROM_NUMBER` | `sdk.connectors.twilio.create_client(...)` |
| `uber` | Uber Direct / Health rides and deliveries | `client_id`, `client_secret`, `customer_id`, `mode?` | `HC_UBER_CLIENT_ID`, `HC_UBER_CLIENT_SECRET`, `HC_UBER_CUSTOMER_ID` | `sdk.connectors.uber.create_client(...)` |
| `whoop` | WHOOP wearable data (OAuth) | `client_id`, `client_secret`, `mode?` | `HC_WHOOP_CLIENT_ID`, `HC_WHOOP_CLIENT_SECRET` | `sdk.connectors.whoop.create_client(...)` |
| `zocdoc` | Zocdoc provider search and booking | `api_key` | `HC_ZOCDOC_API_KEY` | `sdk.connectors.zocdoc.create_client(...)` |
| `zus` | Zus Health aggregated patient data | `client_id`, `client_secret`, `mode?` | `HC_ZUS_CLIENT_ID`, `HC_ZUS_CLIENT_SECRET` | `sdk.connectors.zus.create_client(...)` |

> Note: the single `quest` connector covers both the REST-style
> order/results/catalog operations and the HL7 message-based operations,
> all routing to the gateway's `quest` slug with the same credentials.

## Errors and cleanup

```python
from healthcloud import HealthCloudHTTPError, HealthCloudNetworkError

try:
    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 connector credentials.
