hubble-sdk-python 0.0.3__tar.gz → 0.2.0__tar.gz

{hubble_sdk_python-0.0.3 → hubble_sdk_python-0.2.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.2.0](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.1.0...hubble-sdk-python-v0.2.0) (2026-09-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* the `authorization_code` value is removed from the token `grant_type` enum (it was never available), and `ConsentList.next_cursor` / `ConsentSource.id` are now required response fields.
+
+### Features
+
+* add revoked consent source status ([#51](https://github.com/hubble-dot-ai/hubble-sdks/issues/51)) ([b2dc24d](https://github.com/hubble-dot-ai/hubble-sdks/commit/b2dc24d3359ce1ea245bd881303ada2c425e3132))
+* async record exports, consent pagination, and per-source ids ([#47](https://github.com/hubble-dot-ai/hubble-sdks/issues/47)) ([ddf8e5b](https://github.com/hubble-dot-ai/hubble-sdks/commit/ddf8e5b02436d6ae69d0ca20e723752ee21349a9))
+* verify and parse webhook events ([#50](https://github.com/hubble-dot-ai/hubble-sdks/issues/50)) ([e71b0bc](https://github.com/hubble-dot-ai/hubble-sdks/commit/e71b0bc80b38fbd070a4b6fd5ddfcbada1e8e311))
+
+## [0.1.0](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.0.3...hubble-sdk-python-v0.1.0) (2026-09-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* `Consent.granted_at` is removed. Callers reading it must derive authorization time another way (e.g. status transitions).
+
+### Features
+
+* add attach_authorization for BYO HIPAA authorization ([#41](https://github.com/hubble-dot-ai/hubble-sdks/issues/41)) ([66baf11](https://github.com/hubble-dot-ai/hubble-sdks/commit/66baf1192291b31cb03e325be44f1e6c5e4371f3))
+* drop granted_at from Consent ([#44](https://github.com/hubble-dot-ai/hubble-sdks/issues/44)) ([cb61be8](https://github.com/hubble-dot-ai/hubble-sdks/commit/cb61be8dc6e8c4784e30332cb4e31317f773ec3b))
+* support represented organizations in SDK links ([#45](https://github.com/hubble-dot-ai/hubble-sdks/issues/45)) ([430a1d0](https://github.com/hubble-dot-ai/hubble-sdks/commit/430a1d022f75ea645d27b0b7ebf87b910f1c51a9))
+
 ## [0.0.3](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.0.2...hubble-sdk-python-v0.0.3) (2026-08-23)
 
 

{hubble_sdk_python-0.0.3 → hubble_sdk_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hubble-sdk-python
-Version: 0.0.3
+Version: 0.2.0
 Summary: Python client for the Hubble Patient Access API.
 Project-URL: Homepage, https://github.com/hubble-dot-ai/hubble-sdks
 Project-URL: Repository, https://github.com/hubble-dot-ai/hubble-sdks
@@ -45,8 +45,9 @@ from hubble_sdk import Hubble
 hub = Hubble(client_id="hbl_client_prod_...", client_secret="hbl_prod_...")
 
 # 1. Create a patient link and send the patient to it. Optionally prefill with
-#    patient={"first_name": ...} demographics and providers=[{"name": ...}].
-link = hub.create_link(patient_ref="abc123")
+#    patient={"first_name": ...} demographics, providers=[{"name": ...}], and
+#    the optional organization your verified Hubble organization represents.
+link = hub.create_link(patient_ref="abc123", on_behalf_of_organization_name="Acme Health")
 print(link.verification_uri_complete)
 
 # 2. Wait for the patient to authorize (polls the token endpoint for you).
@@ -63,6 +64,35 @@ for consent in hub.list_consents(status="active"):
 hub.revoke_consent(session.consent_id)
 ```
 
+## Receiving webhooks
+
+Verify each delivery against your endpoint's signing secret (from the portal's
+Webhooks page) and get the event back. Pass the **raw** body: a body that was
+parsed and re-serialized will not verify.
+
+```python
+from hubble_sdk import WebhookSignatureError, construct_webhook_event
+
+# e.g. Flask
+@app.post("/hubble/webhooks")
+def hubble_webhook():
+    try:
+        event = construct_webhook_event(
+            request.get_data(), request.headers.get("Hubble-Signature"), WEBHOOK_SECRET
+        )
+    except WebhookSignatureError:
+        return "bad signature", 400
+    if event.type == "consent.source.available":
+        print(event.consent_id, event.source.id)
+    # newer event types may arrive; ignore what you don't handle
+    return "", 204
+```
+
+In FastAPI, read the body with `await request.body()`. Deliveries are
+at-least-once, so dedupe on `event.id`. Pass `secret` as a list to accept the old
+and new secret during a rotation, and `tolerance` to change the default 5-minute
+replay window.
+
 ## What the client handles for you
 
 - **Auth per plane** — HTTP Basic (your app credentials) for consent management
@@ -81,7 +111,7 @@ hub.revoke_consent(session.consent_id)
 
 ## Layout
 
-`Hubble` / `PatientSession` are hand-written. The low-level client generated
+`Hubble` / `PatientSession` and the webhook helpers are hand-written. The low-level client generated
 from the OpenAPI contract with
 [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
 lives under `hubble_sdk._generated` (regenerated on every spec change;

{hubble_sdk_python-0.0.3 → hubble_sdk_python-0.2.0}/README.md

@@ -13,8 +13,9 @@ from hubble_sdk import Hubble
 hub = Hubble(client_id="hbl_client_prod_...", client_secret="hbl_prod_...")
 
 # 1. Create a patient link and send the patient to it. Optionally prefill with
-#    patient={"first_name": ...} demographics and providers=[{"name": ...}].
-link = hub.create_link(patient_ref="abc123")
+#    patient={"first_name": ...} demographics, providers=[{"name": ...}], and
+#    the optional organization your verified Hubble organization represents.
+link = hub.create_link(patient_ref="abc123", on_behalf_of_organization_name="Acme Health")
 print(link.verification_uri_complete)
 
 # 2. Wait for the patient to authorize (polls the token endpoint for you).
@@ -31,6 +32,35 @@ for consent in hub.list_consents(status="active"):
 hub.revoke_consent(session.consent_id)
 ```
 
+## Receiving webhooks
+
+Verify each delivery against your endpoint's signing secret (from the portal's
+Webhooks page) and get the event back. Pass the **raw** body: a body that was
+parsed and re-serialized will not verify.
+
+```python
+from hubble_sdk import WebhookSignatureError, construct_webhook_event
+
+# e.g. Flask
+@app.post("/hubble/webhooks")
+def hubble_webhook():
+    try:
+        event = construct_webhook_event(
+            request.get_data(), request.headers.get("Hubble-Signature"), WEBHOOK_SECRET
+        )
+    except WebhookSignatureError:
+        return "bad signature", 400
+    if event.type == "consent.source.available":
+        print(event.consent_id, event.source.id)
+    # newer event types may arrive; ignore what you don't handle
+    return "", 204
+```
+
+In FastAPI, read the body with `await request.body()`. Deliveries are
+at-least-once, so dedupe on `event.id`. Pass `secret` as a list to accept the old
+and new secret during a rotation, and `tolerance` to change the default 5-minute
+replay window.
+
 ## What the client handles for you
 
 - **Auth per plane** — HTTP Basic (your app credentials) for consent management
@@ -49,7 +79,7 @@ hub.revoke_consent(session.consent_id)
 
 ## Layout
 
-`Hubble` / `PatientSession` are hand-written. The low-level client generated
+`Hubble` / `PatientSession` and the webhook helpers are hand-written. The low-level client generated
 from the OpenAPI contract with
 [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
 lives under `hubble_sdk._generated` (regenerated on every spec change;

{hubble_sdk_python-0.0.3 → hubble_sdk_python-0.2.0}/hubble_sdk/__init__.py

@@ -28,6 +28,13 @@ from ._hubble import (
     PdfExport,
     TokenSet,
 )
+from ._webhooks import (
+    WEBHOOK_SIGNATURE_HEADER,
+    WebhookEvent,
+    WebhookEventSource,
+    WebhookSignatureError,
+    construct_webhook_event,
+)
 
 __all__ = [
     "Hubble",
@@ -36,6 +43,11 @@ __all__ = [
     "ConsentTimeout",
     "TokenSet",
     "PdfExport",
+    "construct_webhook_event",
+    "WebhookEvent",
+    "WebhookEventSource",
+    "WebhookSignatureError",
+    "WEBHOOK_SIGNATURE_HEADER",
     "Consent",
     "ConsentStatus",
     "DeviceAuthorizationResponse",

{hubble_sdk_python-0.0.3 → hubble_sdk_python-0.2.0}/hubble_sdk/_generated/api/default/attach_client_authorization.py

@@ -8,9 +8,7 @@ from ... import errors
 from ...client import AuthenticatedClient, Client
 from ...models.api_error import ApiError
 from ...models.attach_client_authorization_body import AttachClientAuthorizationBody
-from ...models.attach_client_authorization_response_201 import (
-    AttachClientAuthorizationResponse201,
-)
+from ...models.consent import Consent
 from ...types import Response
 
 
@@ -38,11 +36,11 @@ def _get_kwargs(
 
 def _parse_response(
     *, client: AuthenticatedClient | Client, response: httpx.Response
-) -> ApiError | AttachClientAuthorizationResponse201 | None:
-    if response.status_code == 201:
-        response_201 = AttachClientAuthorizationResponse201.from_dict(response.json())
+) -> ApiError | Consent | None:
+    if response.status_code == 200:
+        response_200 = Consent.from_dict(response.json())
 
-        return response_201
+        return response_200
 
     if response.status_code == 400:
         response_400 = ApiError.from_dict(response.json())
@@ -64,6 +62,11 @@ def _parse_response(
 
         return response_404
 
+    if response.status_code == 409:
+        response_409 = ApiError.from_dict(response.json())
+
+        return response_409
+
     if response.status_code == 413:
         response_413 = ApiError.from_dict(response.json())
 
@@ -77,7 +80,7 @@ def _parse_response(
 
 def _build_response(
     *, client: AuthenticatedClient | Client, response: httpx.Response
-) -> Response[ApiError | AttachClientAuthorizationResponse201]:
+) -> Response[ApiError | Consent]:
     return Response(
         status_code=HTTPStatus(response.status_code),
         content=response.content,
@@ -91,7 +94,7 @@ def sync_detailed(
     *,
     client: AuthenticatedClient,
     body: AttachClientAuthorizationBody,
-) -> Response[ApiError | AttachClientAuthorizationResponse201]:
+) -> Response[ApiError | Consent]:
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
@@ -107,7 +110,7 @@ def sync_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[ApiError | AttachClientAuthorizationResponse201]
+        Response[ApiError | Consent]
     """
 
     kwargs = _get_kwargs(
@@ -127,7 +130,7 @@ def sync(
     *,
     client: AuthenticatedClient,
     body: AttachClientAuthorizationBody,
-) -> ApiError | AttachClientAuthorizationResponse201 | None:
+) -> ApiError | Consent | None:
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
@@ -143,7 +146,7 @@ def sync(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        ApiError | AttachClientAuthorizationResponse201
+        ApiError | Consent
     """
 
     return sync_detailed(
@@ -158,7 +161,7 @@ async def asyncio_detailed(
     *,
     client: AuthenticatedClient,
     body: AttachClientAuthorizationBody,
-) -> Response[ApiError | AttachClientAuthorizationResponse201]:
+) -> Response[ApiError | Consent]:
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
@@ -174,7 +177,7 @@ async def asyncio_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[ApiError | AttachClientAuthorizationResponse201]
+        Response[ApiError | Consent]
     """
 
     kwargs = _get_kwargs(
@@ -192,7 +195,7 @@ async def asyncio(
     *,
     client: AuthenticatedClient,
     body: AttachClientAuthorizationBody,
-) -> ApiError | AttachClientAuthorizationResponse201 | None:
+) -> ApiError | Consent | None:
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
@@ -208,7 +211,7 @@ async def asyncio(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        ApiError | AttachClientAuthorizationResponse201
+        ApiError | Consent
     """
 
     return (

hubble_sdk_python-0.2.0/hubble_sdk/_generated/api/default/export_patient_fhir.py

@@ -0,0 +1,262 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.export_patient_fhir_prefer import ExportPatientFhirPrefer
+from ...models.export_patient_fhir_response_202 import ExportPatientFhirResponse202
+from ...models.fhir_resource import FhirResource
+from ...models.operation_outcome import OperationOutcome
+from ...types import UNSET, Response, Unset
+
+
+def _get_kwargs(
+    *,
+    field_count: int | Unset = UNSET,
+    field_offset: int | Unset = UNSET,
+    prefer: ExportPatientFhirPrefer | Unset = UNSET,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+    if not isinstance(prefer, Unset):
+        headers["Prefer"] = str(prefer)
+
+    params: dict[str, Any] = {}
+
+    params["_count"] = field_count
+
+    params["_offset"] = field_offset
+
+    params = {k: v for k, v in params.items() if v is not UNSET and v is not None}
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/api/v1/fhir/Patient/$everything",
+        "params": params,
+    }
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> ExportPatientFhirResponse202 | FhirResource | OperationOutcome | None:
+    if response.status_code == 200:
+        response_200 = FhirResource.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 202:
+        response_202 = ExportPatientFhirResponse202.from_dict(response.json())
+
+        return response_202
+
+    if response.status_code == 400:
+        response_400 = OperationOutcome.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = OperationOutcome.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = OperationOutcome.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = OperationOutcome.from_dict(response.json())
+
+        return response_404
+
+    if response.status_code == 429:
+        response_429 = OperationOutcome.from_dict(response.json())
+
+        return response_429
+
+    if response.status_code == 503:
+        response_503 = OperationOutcome.from_dict(response.json())
+
+        return response_503
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[ExportPatientFhirResponse202 | FhirResource | OperationOutcome]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+    field_count: int | Unset = UNSET,
+    field_offset: int | Unset = UNSET,
+    prefer: ExportPatientFhirPrefer | Unset = UNSET,
+) -> Response[ExportPatientFhirResponse202 | FhirResource | OperationOutcome]:
+    """Read or asynchronously export the patient's FHIR record
+
+     Without Prefer, returns the existing paginated FHIR searchset. Send Prefer: respond-async without
+    query parameters to prepare health-records.json in the background. The file is a FHIR collection
+    Bundle containing the captured provider sources, including each source's Patient and warnings for
+    incomplete sources. It has no paging links, search metadata or total field, and is not a Bulk Data
+    $export/NDJSON response. Poll Content-Location with the same consent token no sooner than Retry-
+    After for a 303 download redirect. An organization can hold 20 exports in flight at once; a repeat
+    request for one already running reuses it. Payer records are not included.
+
+    Args:
+        field_count (int | Unset):
+        field_offset (int | Unset):
+        prefer (ExportPatientFhirPrefer | Unset):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ExportPatientFhirResponse202 | FhirResource | OperationOutcome]
+    """
+
+    kwargs = _get_kwargs(
+        field_count=field_count,
+        field_offset=field_offset,
+        prefer=prefer,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+    field_count: int | Unset = UNSET,
+    field_offset: int | Unset = UNSET,
+    prefer: ExportPatientFhirPrefer | Unset = UNSET,
+) -> ExportPatientFhirResponse202 | FhirResource | OperationOutcome | None:
+    """Read or asynchronously export the patient's FHIR record
+
+     Without Prefer, returns the existing paginated FHIR searchset. Send Prefer: respond-async without
+    query parameters to prepare health-records.json in the background. The file is a FHIR collection
+    Bundle containing the captured provider sources, including each source's Patient and warnings for
+    incomplete sources. It has no paging links, search metadata or total field, and is not a Bulk Data
+    $export/NDJSON response. Poll Content-Location with the same consent token no sooner than Retry-
+    After for a 303 download redirect. An organization can hold 20 exports in flight at once; a repeat
+    request for one already running reuses it. Payer records are not included.
+
+    Args:
+        field_count (int | Unset):
+        field_offset (int | Unset):
+        prefer (ExportPatientFhirPrefer | Unset):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ExportPatientFhirResponse202 | FhirResource | OperationOutcome
+    """
+
+    return sync_detailed(
+        client=client,
+        field_count=field_count,
+        field_offset=field_offset,
+        prefer=prefer,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+    field_count: int | Unset = UNSET,
+    field_offset: int | Unset = UNSET,
+    prefer: ExportPatientFhirPrefer | Unset = UNSET,
+) -> Response[ExportPatientFhirResponse202 | FhirResource | OperationOutcome]:
+    """Read or asynchronously export the patient's FHIR record
+
+     Without Prefer, returns the existing paginated FHIR searchset. Send Prefer: respond-async without
+    query parameters to prepare health-records.json in the background. The file is a FHIR collection
+    Bundle containing the captured provider sources, including each source's Patient and warnings for
+    incomplete sources. It has no paging links, search metadata or total field, and is not a Bulk Data
+    $export/NDJSON response. Poll Content-Location with the same consent token no sooner than Retry-
+    After for a 303 download redirect. An organization can hold 20 exports in flight at once; a repeat
+    request for one already running reuses it. Payer records are not included.
+
+    Args:
+        field_count (int | Unset):
+        field_offset (int | Unset):
+        prefer (ExportPatientFhirPrefer | Unset):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ExportPatientFhirResponse202 | FhirResource | OperationOutcome]
+    """
+
+    kwargs = _get_kwargs(
+        field_count=field_count,
+        field_offset=field_offset,
+        prefer=prefer,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+    field_count: int | Unset = UNSET,
+    field_offset: int | Unset = UNSET,
+    prefer: ExportPatientFhirPrefer | Unset = UNSET,
+) -> ExportPatientFhirResponse202 | FhirResource | OperationOutcome | None:
+    """Read or asynchronously export the patient's FHIR record
+
+     Without Prefer, returns the existing paginated FHIR searchset. Send Prefer: respond-async without
+    query parameters to prepare health-records.json in the background. The file is a FHIR collection
+    Bundle containing the captured provider sources, including each source's Patient and warnings for
+    incomplete sources. It has no paging links, search metadata or total field, and is not a Bulk Data
+    $export/NDJSON response. Poll Content-Location with the same consent token no sooner than Retry-
+    After for a 303 download redirect. An organization can hold 20 exports in flight at once; a repeat
+    request for one already running reuses it. Payer records are not included.
+
+    Args:
+        field_count (int | Unset):
+        field_offset (int | Unset):
+        prefer (ExportPatientFhirPrefer | Unset):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ExportPatientFhirResponse202 | FhirResource | OperationOutcome
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            field_count=field_count,
+            field_offset=field_offset,
+            prefer=prefer,
+        )
+    ).parsed