hubble-sdk-python 0.1.0__tar.gz → 0.2.1__tar.gz

{hubble_sdk_python-0.1.0 → hubble_sdk_python-0.2.1}/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.2.1](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.2.0...hubble-sdk-python-v0.2.1) (2026-10-14)
+
+
+### Features
+
+* echo provider_ref on sources from a seeded provider ([#57](https://github.com/hubble-dot-ai/hubble-sdks/issues/57)) ([dbfc576](https://github.com/hubble-dot-ai/hubble-sdks/commit/dbfc5763b2514aecbc520bd0406eeefedae1f6ac))
+* mark Consent.error deprecated and optional ([#58](https://github.com/hubble-dot-ai/hubble-sdks/issues/58)) ([dacf748](https://github.com/hubble-dot-ai/hubble-sdks/commit/dacf7488d5d4b073b9781914d20bdd6897075c50))
+
+
+### Bug Fixes
+
+* accept enum values this SDK version does not know ([#56](https://github.com/hubble-dot-ai/hubble-sdks/issues/56)) ([45d69ad](https://github.com/hubble-dot-ai/hubble-sdks/commit/45d69ad44d67de470f122803e842a914b9342915))
+
+
+### Documentation
+
+* state the BYO attestation and who checks the authorization ([#54](https://github.com/hubble-dot-ai/hubble-sdks/issues/54)) ([7ddecdd](https://github.com/hubble-dot-ai/hubble-sdks/commit/7ddecddf1d1ffc61e92825aa202d5105c7647092))
+
+## [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)
 
 

{hubble_sdk_python-0.1.0 → hubble_sdk_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hubble-sdk-python
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -64,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
@@ -82,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.1.0 → hubble_sdk_python-0.2.1}/README.md

@@ -32,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
@@ -50,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.1.0 → hubble_sdk_python-0.2.1}/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.1.0 → hubble_sdk_python-0.2.1}/hubble_sdk/_generated/api/default/attach_client_authorization.py

@@ -98,8 +98,14 @@ def sync_detailed(
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
-    providers it names. The artifact IS the evidence, so the consent is granted at once with no patient
-    step. Requires the `byo_hipaa_authorization` entitlement on your organization.
+    providers it names. Hubble keeps a copy of the signed authorization on file and, based on your
+    attestation, makes the consent `active` right away with no patient step. If your organization also
+    uses EHR sign-in, health plans, or the health information network, the consent stays `pending` until
+    the patient finishes the link. Requires the `byo_hipaa_authorization` entitlement on your
+    organization. Attaching an authorization is your organization's attestation that it holds a valid
+    HIPAA authorization signed by the patient, and that it covers the providers you name. Hubble does
+    not review the document or ask the patient to confirm it, so your organization is responsible for
+    checking that the authorization is correct before you attach it.
 
     Args:
         id (str):
@@ -134,8 +140,14 @@ def sync(
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
-    providers it names. The artifact IS the evidence, so the consent is granted at once with no patient
-    step. Requires the `byo_hipaa_authorization` entitlement on your organization.
+    providers it names. Hubble keeps a copy of the signed authorization on file and, based on your
+    attestation, makes the consent `active` right away with no patient step. If your organization also
+    uses EHR sign-in, health plans, or the health information network, the consent stays `pending` until
+    the patient finishes the link. Requires the `byo_hipaa_authorization` entitlement on your
+    organization. Attaching an authorization is your organization's attestation that it holds a valid
+    HIPAA authorization signed by the patient, and that it covers the providers you name. Hubble does
+    not review the document or ask the patient to confirm it, so your organization is responsible for
+    checking that the authorization is correct before you attach it.
 
     Args:
         id (str):
@@ -165,8 +177,14 @@ async def asyncio_detailed(
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
-    providers it names. The artifact IS the evidence, so the consent is granted at once with no patient
-    step. Requires the `byo_hipaa_authorization` entitlement on your organization.
+    providers it names. Hubble keeps a copy of the signed authorization on file and, based on your
+    attestation, makes the consent `active` right away with no patient step. If your organization also
+    uses EHR sign-in, health plans, or the health information network, the consent stays `pending` until
+    the patient finishes the link. Requires the `byo_hipaa_authorization` entitlement on your
+    organization. Attaching an authorization is your organization's attestation that it holds a valid
+    HIPAA authorization signed by the patient, and that it covers the providers you name. Hubble does
+    not review the document or ask the patient to confirm it, so your organization is responsible for
+    checking that the authorization is correct before you attach it.
 
     Args:
         id (str):
@@ -199,8 +217,14 @@ async def asyncio(
     """Attach a customer-supplied HIPAA authorization
 
      Upload an already-signed HIPAA authorization for a consent and grant delegated retrieval from the
-    providers it names. The artifact IS the evidence, so the consent is granted at once with no patient
-    step. Requires the `byo_hipaa_authorization` entitlement on your organization.
+    providers it names. Hubble keeps a copy of the signed authorization on file and, based on your
+    attestation, makes the consent `active` right away with no patient step. If your organization also
+    uses EHR sign-in, health plans, or the health information network, the consent stays `pending` until
+    the patient finishes the link. Requires the `byo_hipaa_authorization` entitlement on your
+    organization. Attaching an authorization is your organization's attestation that it holds a valid
+    HIPAA authorization signed by the patient, and that it covers the providers you name. Hubble does
+    not review the document or ask the patient to confirm it, so your organization is responsible for
+    checking that the authorization is correct before you attach it.
 
     Args:
         id (str):

hubble_sdk_python-0.2.1/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