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

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

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.3.1](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.3.0...hubble-sdk-python-v0.3.1) (2026-11-05)
+
+
+### Features
+
+* Support `Hubble-Version` through the `version` option on `export_pdf`, including waiting for background generation and downloading the completed records archive. ([#82](https://github.com/hubble-dot-ai/hubble-sdks/issues/82)) ([8f295db](https://github.com/hubble-dot-ai/hubble-sdks/commit/8f295db3f67c8606a29db0f7dfd99752e963c99e))
+* Request a single PDF containing a source's summary and documents with `combined=true` in the generated client. ([#84](https://github.com/hubble-dot-ai/hubble-sdks/issues/84)) ([3a70d41](https://github.com/hubble-dot-ai/hubble-sdks/commit/3a70d417c9cc27700679b3e957a748dd251fcd71))
+* Limit FHIR reads and exports to one connected source with the generated client's `connection` parameter. ([#81](https://github.com/hubble-dot-ai/hubble-sdks/issues/81)) ([0f812d0](https://github.com/hubble-dot-ai/hubble-sdks/commit/0f812d06ac59e23285fd72238529eb21afcbc80a))
+
+
+### Documentation
+
+* Document records archives and 30-day export availability after completion, with download links valid for at most 60 seconds. ([#81](https://github.com/hubble-dot-ai/hubble-sdks/issues/81)) ([0f812d0](https://github.com/hubble-dot-ai/hubble-sdks/commit/0f812d06ac59e23285fd72238529eb21afcbc80a))
+* Clarify that `consent.completed` means the patient finished adding sources; their records may still be processing. ([#78](https://github.com/hubble-dot-ai/hubble-sdks/issues/78)) ([b16e458](https://github.com/hubble-dot-ai/hubble-sdks/commit/b16e45869dd7a5f531318e58c182022b12e3139b))
+
+## [0.3.0](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.2.1...hubble-sdk-python-v0.3.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* type the consent status filter as a literal ([#70](https://github.com/hubble-dot-ai/hubble-sdks/issues/70))
+* each discloser needs an address (line1, city, state, postal_code) next to its name. The API now refuses a name-only discloser with a 400, and the TypeScript type no longer accepts one.
+
+### Features
+
+* create consents without the device flow ([#66](https://github.com/hubble-dot-ai/hubble-sdks/issues/66)) ([f82bed9](https://github.com/hubble-dot-ai/hubble-sdks/commit/f82bed9d31192144cd592c25890639b1576bf2bd))
+* read consents with an application access token ([#65](https://github.com/hubble-dot-ai/hubble-sdks/issues/65)) ([66f9703](https://github.com/hubble-dot-ai/hubble-sdks/commit/66f97031f9eef15bc39c2e5a8f6059c11c4bbf93))
+* send facility details with each discloser when attaching an authorization ([#69](https://github.com/hubble-dot-ai/hubble-sdks/issues/69)) ([6d49b68](https://github.com/hubble-dot-ai/hubble-sdks/commit/6d49b68b49768efb5715cc7a3379ee0123ddd466))
+* ship a py.typed marker so type checkers read the SDK's types ([#72](https://github.com/hubble-dot-ai/hubble-sdks/issues/72)) ([bf1f4b0](https://github.com/hubble-dot-ai/hubble-sdks/commit/bf1f4b0a0ecadc17d89e0eb477cbda98f9648aec))
+* sync the spec for application tokens and POST /consents ([#64](https://github.com/hubble-dot-ai/hubble-sdks/issues/64)) ([8981d57](https://github.com/hubble-dot-ai/hubble-sdks/commit/8981d57c7dee236a1668effc477adbd77ef38ba3))
+* type the consent status filter as a literal ([#70](https://github.com/hubble-dot-ai/hubble-sdks/issues/70)) ([fb7fd4b](https://github.com/hubble-dot-ai/hubble-sdks/commit/fb7fd4b26ba0e05874a01a307ca8e16a02000979))
+
+
+### Bug Fixes
+
+* harden application-token reads (dot ids, relative next links, shared token) ([#68](https://github.com/hubble-dot-ai/hubble-sdks/issues/68)) ([0d9d41e](https://github.com/hubble-dot-ai/hubble-sdks/commit/0d9d41e85f5d45f98a7cc08d7efb1ede6a1aabbd))
+* send create_consent's body as given so a misspelt field is refused ([#73](https://github.com/hubble-dot-ai/hubble-sdks/issues/73)) ([559cf0f](https://github.com/hubble-dot-ai/hubble-sdks/commit/559cf0f7471f277f77d874f4454d5202d3a16e62))
+* sync the consent status and error descriptions from the portal ([#62](https://github.com/hubble-dot-ai/hubble-sdks/issues/62)) ([2bd1606](https://github.com/hubble-dot-ai/hubble-sdks/commit/2bd160636fa5ccd8d5f324d0d69f29ab19ff57fc))
+
+
+### Documentation
+
+* keep the disclosers description in one argument entry ([#74](https://github.com/hubble-dot-ai/hubble-sdks/issues/74)) ([53e5163](https://github.com/hubble-dot-ai/hubble-sdks/commit/53e51634c5a29c0b3bd96dab06b8965f7b6cfdda))
+
 ## [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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hubble-sdk-python
-Version: 0.2.1
+Version: 0.3.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
@@ -32,8 +32,8 @@ Description-Content-Type: text/markdown
 
 # hubble-sdk-python
 
-Python client for the Hubble Patient Access API: create patient authorization
-links, exchange them for consent-scoped access tokens, and read FHIR R4 data.
+Python client for the Hubble Patient Access API: create consents and patient
+links, and read FHIR R4 data with your application's access token.
 
 ```bash
 pip install hubble-sdk-python
@@ -44,24 +44,53 @@ 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
+# 1. Create a consent and send the patient its link. Optionally prefill with
 #    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).
-session = hub.wait_for_authorization(link)
+consent = hub.create_consent(patient_ref="abc123", on_behalf_of_organization_name="Acme Health")
+print(consent.link_url)   # returned only here; store it if you may resend it
 
-# 3. Read the patient's FHIR data (Bearer token + auto-refresh handled for you).
-bundle = session.everything()
-observations = session.fhir("Observation", params={"category": "vital-signs"})
-export = session.export_pdf()   # export.content bytes; export.sources_failed counts failed sources
+# 2. Read the patient's FHIR data whenever you like (see below for every read).
+summary = hub.summary(consent.id)
+labs = hub.search(consent.id, "Observation", {"category": "laboratory"})
 
 # Consent management
-for consent in hub.list_consents(status="active"):
-    print(consent.id, consent.patient_ref)
-hub.revoke_consent(session.consent_id)
+for c in hub.list_consents(status="active"):
+    print(c.id, c.patient_ref)
+hub.revoke_consent(consent.id)
+```
+
+## Reading with an application token
+
+Read any consent in your environment by its id, without the device flow: while
+the patient is still adding sources, after they finish, or after the link
+expires. The client gets the application access token from `POST /api/v1/token`,
+caches it and renews it for you, and names the consent on every request. One
+`Hubble` client is safe to share across threads: they share the one token, and
+only one thread fetches or renews it at a time.
+
+```python
+obs = hub.read(consent_id, "Observation", "abc-123")                  # one resource
+page = hub.search(consent_id, "Observation", {"category": "laboratory"})  # first page (a Bundle)
+for resource in hub.iter_search(consent_id, "Observation", {"category": "laboratory"}):
+    ...                                                                # every page, lazily
+summary = hub.summary(consent_id)
+record = hub.everything(consent_id, {"_count": 100})
+export = hub.export_pdf(consent_id, connection=connection_id)         # one source's PDF
+```
+
+Reuse one `Hubble` client so its token is reused too.
+
+### The device flow
+
+Existing integrations can keep using the device flow, which waits for the
+patient to finish and reads with a consent-scoped token:
+
+```python
+link = hub.create_link(patient_ref="abc123")
+print(link.verification_uri_complete)
+session = hub.wait_for_authorization(link)   # polls until the patient finishes
+bundle = session.everything()                # refreshes the consent token for you
 ```
 
 ## Receiving webhooks

{hubble_sdk_python-0.2.1 → hubble_sdk_python-0.3.1}/README.md

@@ -1,7 +1,7 @@
 # hubble-sdk-python
 
-Python client for the Hubble Patient Access API: create patient authorization
-links, exchange them for consent-scoped access tokens, and read FHIR R4 data.
+Python client for the Hubble Patient Access API: create consents and patient
+links, and read FHIR R4 data with your application's access token.
 
 ```bash
 pip install hubble-sdk-python
@@ -12,24 +12,53 @@ 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
+# 1. Create a consent and send the patient its link. Optionally prefill with
 #    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).
-session = hub.wait_for_authorization(link)
+consent = hub.create_consent(patient_ref="abc123", on_behalf_of_organization_name="Acme Health")
+print(consent.link_url)   # returned only here; store it if you may resend it
 
-# 3. Read the patient's FHIR data (Bearer token + auto-refresh handled for you).
-bundle = session.everything()
-observations = session.fhir("Observation", params={"category": "vital-signs"})
-export = session.export_pdf()   # export.content bytes; export.sources_failed counts failed sources
+# 2. Read the patient's FHIR data whenever you like (see below for every read).
+summary = hub.summary(consent.id)
+labs = hub.search(consent.id, "Observation", {"category": "laboratory"})
 
 # Consent management
-for consent in hub.list_consents(status="active"):
-    print(consent.id, consent.patient_ref)
-hub.revoke_consent(session.consent_id)
+for c in hub.list_consents(status="active"):
+    print(c.id, c.patient_ref)
+hub.revoke_consent(consent.id)
+```
+
+## Reading with an application token
+
+Read any consent in your environment by its id, without the device flow: while
+the patient is still adding sources, after they finish, or after the link
+expires. The client gets the application access token from `POST /api/v1/token`,
+caches it and renews it for you, and names the consent on every request. One
+`Hubble` client is safe to share across threads: they share the one token, and
+only one thread fetches or renews it at a time.
+
+```python
+obs = hub.read(consent_id, "Observation", "abc-123")                  # one resource
+page = hub.search(consent_id, "Observation", {"category": "laboratory"})  # first page (a Bundle)
+for resource in hub.iter_search(consent_id, "Observation", {"category": "laboratory"}):
+    ...                                                                # every page, lazily
+summary = hub.summary(consent_id)
+record = hub.everything(consent_id, {"_count": 100})
+export = hub.export_pdf(consent_id, connection=connection_id)         # one source's PDF
+```
+
+Reuse one `Hubble` client so its token is reused too.
+
+### The device flow
+
+Existing integrations can keep using the device flow, which waits for the
+patient to finish and reads with a consent-scoped token:
+
+```python
+link = hub.create_link(patient_ref="abc123")
+print(link.verification_uri_complete)
+session = hub.wait_for_authorization(link)   # polls until the patient finishes
+bundle = session.everything()                # refreshes the consent token for you
 ```
 
 ## Receiving webhooks

{hubble_sdk_python-0.2.1 → hubble_sdk_python-0.3.1}/hubble_sdk/__init__.py

@@ -5,10 +5,12 @@ Import the high-level client from here:
     from hubble_sdk import Hubble
 
     hub = Hubble(client_id="hbl_client_...", client_secret="hbl_prod_...")
-    link = hub.create_link(patient_ref="abc123")
-    print(link.verification_uri_complete)     # send the patient here
-    session = hub.wait_for_authorization(link)
-    bundle = session.everything()             # reads FHIR with the consent token
+    consent = hub.create_consent(patient_ref="abc123")
+    print(consent.link_url)                     # send the patient here
+    bundle = hub.everything(consent.id)         # read whenever you like
+
+The device flow (``create_link`` / ``wait_for_authorization``) still works for
+existing integrations.
 
 The generated low-level client lives under ``hubble_sdk._generated``
 if you need direct access to raw operations and models.
@@ -17,6 +19,7 @@ if you need direct access to raw operations and models.
 from ._generated.models import (
     Consent,
     ConsentStatus,
+    CreatedConsent,
     DeviceAuthorizationResponse,
     TokenResponse,
 )
@@ -28,6 +31,15 @@ from ._hubble import (
     PdfExport,
     TokenSet,
 )
+from ._params import (
+    ConsentStatusFilter,
+    DiscloserParams,
+    FacilityAddressParams,
+    PatientAddressParams,
+    PatientParams,
+    ProviderSeedParams,
+    UsStateCode,
+)
 from ._webhooks import (
     WEBHOOK_SIGNATURE_HEADER,
     WebhookEvent,
@@ -43,6 +55,13 @@ __all__ = [
     "ConsentTimeout",
     "TokenSet",
     "PdfExport",
+    "ConsentStatusFilter",
+    "PatientParams",
+    "PatientAddressParams",
+    "ProviderSeedParams",
+    "DiscloserParams",
+    "FacilityAddressParams",
+    "UsStateCode",
     "construct_webhook_event",
     "WebhookEvent",
     "WebhookEventSource",
@@ -50,6 +69,7 @@ __all__ = [
     "WEBHOOK_SIGNATURE_HEADER",
     "Consent",
     "ConsentStatus",
+    "CreatedConsent",
     "DeviceAuthorizationResponse",
     "TokenResponse",
 ]

hubble_sdk_python-0.3.1/hubble_sdk/_generated/api/default/create_consent.py

@@ -0,0 +1,193 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.api_error import ApiError
+from ...models.consent_link_request import ConsentLinkRequest
+from ...models.created_consent import CreatedConsent
+from ...types import UNSET, Response, Unset
+
+
+def _get_kwargs(
+    *,
+    body: ConsentLinkRequest | Unset = UNSET,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/api/v1/consents",
+    }
+
+    if not isinstance(body, Unset):
+        _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> ApiError | CreatedConsent | None:
+    if response.status_code == 201:
+        response_201 = CreatedConsent.from_dict(response.json())
+
+        return response_201
+
+    if response.status_code == 400:
+        response_400 = ApiError.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ApiError.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = ApiError.from_dict(response.json())
+
+        return response_403
+
+    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[ApiError | CreatedConsent]:
+    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,
+    body: ConsentLinkRequest | Unset = UNSET,
+) -> Response[ApiError | CreatedConsent]:
+    """Create a consent
+
+     Creates a pending consent and its patient link, and returns the consent with `link_url`. Deliver the
+    link to the patient, then read the consent with an application access token from POST /api/v1/token
+    and `consent=<id>` on /api/v1/fhir. Every field is optional.
+
+    Args:
+        body (ConsentLinkRequest | 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[ApiError | CreatedConsent]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+    body: ConsentLinkRequest | Unset = UNSET,
+) -> ApiError | CreatedConsent | None:
+    """Create a consent
+
+     Creates a pending consent and its patient link, and returns the consent with `link_url`. Deliver the
+    link to the patient, then read the consent with an application access token from POST /api/v1/token
+    and `consent=<id>` on /api/v1/fhir. Every field is optional.
+
+    Args:
+        body (ConsentLinkRequest | 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:
+        ApiError | CreatedConsent
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: ConsentLinkRequest | Unset = UNSET,
+) -> Response[ApiError | CreatedConsent]:
+    """Create a consent
+
+     Creates a pending consent and its patient link, and returns the consent with `link_url`. Deliver the
+    link to the patient, then read the consent with an application access token from POST /api/v1/token
+    and `consent=<id>` on /api/v1/fhir. Every field is optional.
+
+    Args:
+        body (ConsentLinkRequest | 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[ApiError | CreatedConsent]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+    body: ConsentLinkRequest | Unset = UNSET,
+) -> ApiError | CreatedConsent | None:
+    """Create a consent
+
+     Creates a pending consent and its patient link, and returns the consent with `link_url`. Deliver the
+    link to the patient, then read the consent with an application access token from POST /api/v1/token
+    and `consent=<id>` on /api/v1/fhir. Every field is optional.
+
+    Args:
+        body (ConsentLinkRequest | 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:
+        ApiError | CreatedConsent
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+        )
+    ).parsed

{hubble_sdk_python-0.2.1 → hubble_sdk_python-0.3.1}/hubble_sdk/_generated/api/default/create_consent_link.py

@@ -77,7 +77,8 @@ def sync_detailed(
      Mints a pending consent and a one-time patient link. Send the patient to
     `verification_uri_complete`, then poll the token endpoint with `device_code` until they authorize.
     Accepts a nested JSON body (recommended) or the flat RFC 8628 form encoding; both prefill the same
-    consent.
+    consent. To read with an application access token instead, create the consent with POST
+    /api/v1/consents, which has no device code.
 
     Args:
         body (ConsentLinkRequest | Unset):
@@ -112,7 +113,8 @@ def sync(
      Mints a pending consent and a one-time patient link. Send the patient to
     `verification_uri_complete`, then poll the token endpoint with `device_code` until they authorize.
     Accepts a nested JSON body (recommended) or the flat RFC 8628 form encoding; both prefill the same
-    consent.
+    consent. To read with an application access token instead, create the consent with POST
+    /api/v1/consents, which has no device code.
 
     Args:
         body (ConsentLinkRequest | Unset):
@@ -142,7 +144,8 @@ async def asyncio_detailed(
      Mints a pending consent and a one-time patient link. Send the patient to
     `verification_uri_complete`, then poll the token endpoint with `device_code` until they authorize.
     Accepts a nested JSON body (recommended) or the flat RFC 8628 form encoding; both prefill the same
-    consent.
+    consent. To read with an application access token instead, create the consent with POST
+    /api/v1/consents, which has no device code.
 
     Args:
         body (ConsentLinkRequest | Unset):
@@ -175,7 +178,8 @@ async def asyncio(
      Mints a pending consent and a one-time patient link. Send the patient to
     `verification_uri_complete`, then poll the token endpoint with `device_code` until they authorize.
     Accepts a nested JSON body (recommended) or the flat RFC 8628 form encoding; both prefill the same
-    consent.
+    consent. To read with an application access token instead, create the consent with POST
+    /api/v1/consents, which has no device code.
 
     Args:
         body (ConsentLinkRequest | Unset):