hebrah 0.8.1__py3-none-any.whl

SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.8.x   | Yes       |
+
+## Reporting a vulnerability
+
+Please report security issues privately to **security@hebrah.com**.
+
+Include:
+
+- A description of the issue and potential impact
+- Steps to reproduce
+- Affected SDK version(s)
+
+We aim to acknowledge reports within 2 business days. Do not open public GitHub issues for undisclosed vulnerabilities.
+
+## Scope
+
+This SDK is a thin HTTP client for the hebrah control plane API. It does not store credentials; callers supply API keys and webhook secrets at runtime.
+
+## Integrator guidance
+
+- Keep `HEBRAH_API_KEY`, `HEBRAH_WEBHOOK_SECRET`, and MCP PATs in server-side environment variables or a secrets manager — never in client-side code, browser bundles, or committed `.env` files.
+- Do not log API keys, webhook secrets, or raw webhook payloads containing PHI.
+- `HebrahApiError.detail` contains the raw control-plane response body for operator diagnostics. Do not return or log `detail` to end users or untrusted clients. Pass `include_error_detail=False` to `HebrahClient` to omit `detail` from thrown errors.
+- `base_url` must use `https://` or `http://localhost` / `http://127.0.0.1` for local development; other `http://` hosts are rejected at client construction.
+- The SDK holds credentials only in memory for the lifetime of a `HebrahClient` instance; it does not write them to disk or cache them.

hebrah/__init__.py

@@ -0,0 +1,15 @@
+from hebrah.client import HebrahClient
+from hebrah.errors import HebrahApiError
+from hebrah.harness import HebrahAgentHarness
+from hebrah.types import DEFAULT_BASE_URL
+from hebrah.webhooks import verify_webhook_signature
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "HebrahAgentHarness",
+    "HebrahApiError",
+    "HebrahClient",
+    "verify_webhook_signature",
+]
+
+__version__ = "0.8.1"

hebrah/client.py

@@ -0,0 +1,515 @@
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import httpx
+
+from hebrah.errors import HebrahApiError
+from hebrah.types import (
+    PatientListResponse,
+    PayerRules,
+    RunScenarioResponse,
+    SandboxCatalog,
+    SandboxDomainSummary,
+    SandboxResourceListResponse,
+    TriggerMockEventResponse,
+    resolve_base_url,
+)
+
+
+class _SandboxResource:
+    def __init__(self, client: HebrahClient) -> None:
+        self._client = client
+
+    def catalog(self, connection_id: str | None = None) -> SandboxCatalog:
+        return self._client._request(
+            "GET",
+            "/v1/sandbox/catalog",
+            params=self._client._connection_params(connection_id),
+        )
+
+    def domains(self) -> list[SandboxDomainSummary]:
+        return self._client._request("GET", "/v1/sandbox/domains")
+
+    def domain(self, domain_id: str) -> SandboxDomainSummary:
+        from urllib.parse import quote
+
+        return self._client._request(
+            "GET",
+            f"/v1/sandbox/domains/{quote(domain_id, safe='')}",
+        )
+
+    def resource(
+        self,
+        resource_type: str,
+        resource_id: str,
+        *,
+        patient_id: str | None = None,
+    ) -> dict[str, Any]:
+        from urllib.parse import quote
+
+        params = {"patient_id": patient_id} if patient_id else None
+        return self._client._request(
+            "GET",
+            f"/v1/sandbox/resources/{quote(resource_type, safe='')}/{quote(resource_id, safe='')}",
+            params=params,
+        )
+
+    def list_synthetic_resources(
+        self,
+        resource_type: str,
+        *,
+        connection_id: str | None = None,
+    ) -> SandboxResourceListResponse:
+        from urllib.parse import quote
+
+        params = self._client._connection_params(connection_id)
+        return self._client._request(
+            "GET",
+            f"/v1/sandbox/resources/{quote(resource_type, safe='')}",
+            params=params,
+        )
+
+    def run_scenario(
+        self,
+        scenario_id: str,
+        *,
+        patient_id: str | None = None,
+        connection_id: str | None = None,
+        delay_seconds: float | None = None,
+    ) -> RunScenarioResponse:
+        from urllib.parse import quote
+
+        body: dict[str, str | float] = {}
+        if patient_id:
+            body["patient_id"] = patient_id
+        resolved_connection = self._client._resolve_connection_id(connection_id)
+        if resolved_connection:
+            body["connection_id"] = resolved_connection
+        if delay_seconds is not None:
+            body["delay_seconds"] = delay_seconds
+        return self._client._request(
+            "POST",
+            f"/v1/sandbox/scenarios/{quote(scenario_id, safe='')}/run",
+            json=body,
+        )
+
+    def payer_rules(self, payer_id: str) -> PayerRules:
+        from urllib.parse import quote
+
+        return self._client._request(
+            "GET",
+            f"/v1/sandbox/payer-rules/{quote(payer_id, safe='')}",
+        )
+
+    def hl7_templates(self) -> list[dict[str, Any]]:
+        return self._client._request("GET", "/v1/sandbox/hl7/templates")
+
+    def inject_hl7(
+        self,
+        *,
+        message: str | None = None,
+        template_id: str | None = None,
+        patient_id: str | None = None,
+        connection_id: str | None = None,
+        event: str | None = None,
+        deliver: bool | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, str | bool] = {}
+        if message:
+            body["message"] = message
+        if template_id:
+            body["template_id"] = template_id
+        if patient_id:
+            body["patient_id"] = patient_id
+        resolved_connection = self._client._resolve_connection_id(connection_id)
+        if resolved_connection:
+            body["connection_id"] = resolved_connection
+        if event:
+            body["event"] = event
+        if deliver is not None:
+            body["deliver"] = deliver
+        return self._client._request("POST", "/v1/sandbox/hl7/inject", json=body)
+
+    def configure_webhook_reliability(self, **profile: Any) -> dict[str, Any]:
+        return self._client._request(
+            "PATCH",
+            "/v1/sandbox/webhook-reliability",
+            json=profile,
+        )
+
+    def run_webhook_reliability_scenario(
+        self,
+        scenario_id: str,
+        *,
+        patient_id: str | None = None,
+        connection_id: str | None = None,
+    ) -> RunScenarioResponse:
+        return self.run_scenario(
+            scenario_id,
+            patient_id=patient_id,
+            connection_id=connection_id,
+        )
+
+    def run_mpi_match(
+        self,
+        *,
+        first_name: str | None = None,
+        last_name: str | None = None,
+        birth_date: str | None = None,
+        identifier: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, str] = {}
+        if first_name:
+            body["first_name"] = first_name
+        if last_name:
+            body["last_name"] = last_name
+        if birth_date:
+            body["birth_date"] = birth_date
+        if identifier:
+            body["identifier"] = identifier
+        return self._client._request("POST", "/v1/sandbox/mpi/match", json=body)
+
+    def run_aggregator_query(
+        self,
+        *,
+        patient_id: str,
+        include_consent: bool = True,
+        include_provenance: bool = True,
+    ) -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            "/v1/sandbox/aggregator/query",
+            json={
+                "patient_id": patient_id,
+                "include_consent": include_consent,
+                "include_provenance": include_provenance,
+            },
+        )
+
+    def get_practitioner_credentialing(self, practitioner_id: str) -> dict[str, Any]:
+        from urllib.parse import quote
+
+        return self._client._request(
+            "GET",
+            f"/v1/sandbox/credentialing/practitioners/{quote(practitioner_id, safe='')}",
+        )
+
+    def synthetic_ehr_profile(self, *, connection_id: str | None = None) -> dict[str, Any]:
+        return self._client._request(
+            "GET",
+            "/v1/sandbox/synthetic-ehr/profile",
+            params=self._client._connection_params(connection_id),
+        )
+
+    def list_ehr_models(self) -> list[dict[str, Any]]:
+        return self._client._request("GET", "/v1/sandbox/ehr-models")
+
+    def reset_synthetic_ehr(self, *, connection_id: str | None = None) -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            "/v1/sandbox/synthetic-ehr/reset",
+            params=self._client._connection_params(connection_id),
+        )
+
+
+class _SmartResource:
+    def __init__(self, client: HebrahClient) -> None:
+        self._client = client
+
+    def launch(
+        self,
+        *,
+        patient_id: str,
+        encounter_id: str | None = None,
+        smart_app_url: str | None = None,
+    ) -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            "/v1/smart/launch",
+            json={
+                "patient_id": patient_id,
+                "encounter_id": encounter_id,
+                "smart_app_url": smart_app_url,
+            },
+        )
+
+    def register_client(
+        self,
+        *,
+        client_id: str,
+        redirect_uris: list[str],
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            "/v1/smart/clients",
+            json={
+                "client_id": client_id,
+                "name": name or "Python SDK SMART client",
+                "redirect_uris": redirect_uris,
+            },
+        )
+
+    def exchange_token(
+        self,
+        *,
+        code: str,
+        redirect_uri: str,
+        client_id: str,
+        code_verifier: str,
+    ) -> dict[str, Any]:
+        try:
+            response = httpx.post(
+                f"{self._client._base_url}/oauth/token",
+                data={
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "redirect_uri": redirect_uri,
+                    "client_id": client_id,
+                    "code_verifier": code_verifier,
+                },
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=30.0,
+            )
+        except httpx.TimeoutException as exc:
+            raise HebrahApiError("SMART token exchange timed out", 504) from exc
+        except httpx.RequestError as exc:
+            raise HebrahApiError(
+                "SMART token exchange failed: control plane unreachable",
+                503,
+            ) from exc
+        if not response.is_success:
+            raise HebrahApiError(
+                f"SMART token exchange failed ({response.status_code})",
+                response.status_code,
+                self._client._error_detail(response.text),
+            )
+        return response.json()
+
+
+class _FhirResource:
+    def __init__(self, client: HebrahClient) -> None:
+        self._client = client
+
+    def read_patient(self, patient_id: str, access_token: str) -> dict[str, Any]:
+        from urllib.parse import quote
+
+        try:
+            response = httpx.get(
+                f"{self._client._base_url}/fhir/R4/Patient/{quote(patient_id, safe='')}",
+                headers={
+                    "Authorization": f"Bearer {access_token}",
+                    "Accept": "application/fhir+json",
+                },
+                timeout=30.0,
+            )
+        except httpx.TimeoutException as exc:
+            raise HebrahApiError("FHIR Patient read timed out", 504) from exc
+        except httpx.RequestError as exc:
+            raise HebrahApiError(
+                "FHIR Patient read failed: control plane unreachable",
+                503,
+            ) from exc
+        if not response.is_success:
+            raise HebrahApiError(
+                f"FHIR Patient read failed ({response.status_code})",
+                response.status_code,
+                self._client._error_detail(response.text),
+            )
+        return response.json()
+
+
+class _PatientsResource:
+    def __init__(self, client: HebrahClient) -> None:
+        self._client = client
+
+    def list(self, *, connection_id: str | None = None) -> PatientListResponse:
+        warnings.warn(
+            "patients.list() is deprecated; use "
+            "sandbox.list_synthetic_resources('Patient', connection_id=...).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._client._request(
+            "GET",
+            "/v1/patients",
+            params=self._client._connection_params(connection_id),
+        )
+
+    def get(self, patient_id: str, *, connection_id: str | None = None) -> dict[str, Any]:
+        warnings.warn(
+            "patients.get() is deprecated; use sandbox.resource('Patient', patient_id) "
+            "for connection-scoped reads.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from urllib.parse import quote
+
+        return self._client._request(
+            "GET",
+            f"/v1/patients/{quote(patient_id, safe='')}",
+            params=self._client._connection_params(connection_id),
+        )
+
+
+class _WebhooksResource:
+    def __init__(self, client: HebrahClient) -> None:
+        self._client = client
+
+    def trigger_mock_event(
+        self,
+        *,
+        event: str | None = None,
+        patient_id: str | None = None,
+        connection_id: str | None = None,
+        domain_id: str | None = None,
+        scenario_id: str | None = None,
+    ) -> TriggerMockEventResponse:
+        body: dict[str, str] = {}
+        if event:
+            body["event"] = event
+        if patient_id:
+            body["patient_id"] = patient_id
+        resolved_connection = self._client._resolve_connection_id(connection_id)
+        if resolved_connection:
+            body["connection_id"] = resolved_connection
+        if domain_id:
+            body["domain_id"] = domain_id
+        if scenario_id:
+            body["scenario_id"] = scenario_id
+        return self._client._request(
+            "POST",
+            "/v1/webhooks/trigger-mock-event",
+            json=body,
+        )
+
+    def list_deliveries(
+        self,
+        *,
+        connection_id: str | None = None,
+        status: str | None = None,
+        event: str | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, str] = {}
+        resolved_connection = self._client._resolve_connection_id(connection_id)
+        if resolved_connection:
+            params["connection_id"] = resolved_connection
+        if status:
+            params["status"] = status
+        if event:
+            params["event"] = event
+        if limit is not None:
+            params["limit"] = str(limit)
+        return self._client._request("GET", "/v1/webhooks/deliveries", params=params or None)
+
+    def replay_delivery(self, delivery_id: str) -> dict[str, Any]:
+        from urllib.parse import quote
+
+        return self._client._request(
+            "POST",
+            f"/v1/webhooks/deliveries/{quote(delivery_id, safe='')}/replay",
+        )
+
+
+class HebrahClient:
+    """Sync client for the hebrah control plane API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        default_connection_id: str | None = None,
+        include_error_detail: bool = True,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+        self._api_key = api_key.strip()
+        self._base_url = resolve_base_url(base_url)
+        self._default_connection_id = (
+            default_connection_id.strip() if default_connection_id else None
+        )
+        self._include_error_detail = include_error_detail
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {self._api_key}"},
+            timeout=30.0,
+        )
+        self.sandbox = _SandboxResource(self)
+        self.patients = _PatientsResource(self)
+        self.webhooks = _WebhooksResource(self)
+        self.smart = _SmartResource(self)
+        self.fhir = _FhirResource(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def _resolve_connection_id(self, connection_id: str | None) -> str | None:
+        return connection_id or self._default_connection_id
+
+    def _connection_params(self, connection_id: str | None = None) -> dict[str, str] | None:
+        resolved = self._resolve_connection_id(connection_id)
+        return {"connection_id": resolved} if resolved else None
+
+    def _error_detail(self, raw: str | None) -> str | None:
+        return raw if self._include_error_detail else None
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> HebrahClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def health(self) -> dict[str, str]:
+        try:
+            response = httpx.get(f"{self._base_url}/health", timeout=30.0)
+        except httpx.TimeoutException as exc:
+            raise HebrahApiError("Health check timed out", 504) from exc
+        except httpx.RequestError as exc:
+            raise HebrahApiError(
+                f"Control plane unreachable at {self._base_url}. Is hebrah-api running?",
+                503,
+            ) from exc
+        if not response.is_success:
+            raise HebrahApiError(
+                f"Health check failed ({response.status_code})",
+                response.status_code,
+                self._error_detail(response.text),
+            )
+        return response.json()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: dict[str, str | float | bool] | None = None,
+    ) -> Any:
+        try:
+            response = self._http.request(method, path, params=params, json=json)
+        except httpx.TimeoutException as exc:
+            raise HebrahApiError("Control plane request timed out", 504) from exc
+        except httpx.RequestError as exc:
+            raise HebrahApiError(
+                f"Control plane unreachable at {self._base_url}. Is hebrah-api running?",
+                503,
+            ) from exc
+
+        if not response.is_success:
+            raise HebrahApiError(
+                f"Control plane request failed ({response.status_code})",
+                response.status_code,
+                self._error_detail(response.text),
+            )
+
+        if not response.content:
+            return None
+        return response.json()

hebrah/errors.py

@@ -0,0 +1,7 @@
+class HebrahApiError(Exception):
+    """Raised when the control plane returns a non-success HTTP status."""
+
+    def __init__(self, message: str, status: int, detail: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.detail = detail

hebrah/harness.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+
+class HebrahAgentHarness:
+    """Thin orchestration layer: MCP tools + integration-agent for BYOM EHR modeling."""
+
+    def __init__(
+        self,
+        *,
+        mcp_url: str,
+        pat: str,
+        integration_agent_url: str = "http://localhost:3050",
+    ) -> None:
+        self.mcp_url = mcp_url.rstrip("/")
+        self.pat = pat
+        self.integration_agent_url = integration_agent_url.rstrip("/")
+
+    def _mcp_call(self, tool: str, args: dict[str, Any] | None = None) -> Any:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {"name": tool, "arguments": args or {}},
+        }
+        with httpx.Client(timeout=60.0) as client:
+            res = client.post(
+                f"{self.mcp_url}/mcp",
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.pat}",
+                },
+                json=payload,
+            )
+            res.raise_for_status()
+            body = res.json()
+        if body.get("error"):
+            raise RuntimeError(body["error"].get("message", "MCP tool error"))
+        content = (body.get("result") or {}).get("content") or []
+        if content and content[0].get("text"):
+            return json.loads(content[0]["text"])
+        return body.get("result")
+
+    def get_developer_doc(self, connection_id: str | None = None) -> Any:
+        return self._mcp_call(
+            "get_connection_developer_doc",
+            {"connectionId": connection_id} if connection_id else {},
+        )
+
+    def get_synthetic_ehr_profile(self, connection_id: str | None = None) -> Any:
+        return self._mcp_call(
+            "get_synthetic_ehr_profile",
+            {"connectionId": connection_id} if connection_id else {},
+        )
+
+    def list_base_ehr_models(self) -> Any:
+        return self._mcp_call("list_ehr_base_models")
+
+    def research_and_model_ehr(
+        self,
+        *,
+        vendor: str,
+        connection_id: str,
+        doc_urls: list[str] | None = None,
+        doc_text: str | None = None,
+    ) -> Any:
+        chunk_ids: list[str] = []
+        with httpx.Client(timeout=60.0) as client:
+            for url in doc_urls or []:
+                res = client.post(
+                    f"{self.integration_agent_url}/v1/ingest",
+                    json={"connection_id": connection_id, "url": url},
+                )
+                if res.is_success:
+                    chunk_ids.append(res.json()["chunk_id"])
+            if doc_text:
+                res = client.post(
+                    f"{self.integration_agent_url}/v1/ingest",
+                    json={"connection_id": connection_id, "text": doc_text},
+                )
+                if res.is_success:
+                    chunk_ids.append(res.json()["chunk_id"])
+            gen = client.post(
+                f"{self.integration_agent_url}/v1/generate",
+                json={
+                    "connection_id": connection_id,
+                    "vendor": vendor,
+                    "doc_chunk_ids": chunk_ids,
+                },
+            )
+            gen.raise_for_status()
+            return gen.json()
+
+    def validate_sandbox(self, connection_id: str | None = None) -> dict[str, Any]:
+        profile = self.get_synthetic_ehr_profile(connection_id)
+        doc = self.get_developer_doc(connection_id)
+        return {"profile": profile, "doc": doc, "ok": bool(profile and doc)}
+
+    def apply_custom_ehr_model(
+        self,
+        *,
+        connection_id: str,
+        model_pack: dict[str, Any],
+        dashboard_url: str = "http://localhost:3000",
+        confirm_token: str | None = None,
+    ) -> Any:
+        token = confirm_token or f"confirm_{connection_id}"
+        with httpx.Client(timeout=60.0) as client:
+            res = client.post(
+                f"{dashboard_url.rstrip('/')}/api/connections/{connection_id}/byom/apply",
+                headers={
+                    "Authorization": f"Bearer {self.pat}",
+                    "Content-Type": "application/json",
+                },
+                json={"modelPack": model_pack, "confirmToken": token},
+            )
+            if not res.is_success:
+                raise RuntimeError(
+                    f"BYOM apply failed ({res.status_code}): {res.text}"
+                )
+            return res.json()

hebrah/types.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import os
+from typing import Any, TypedDict
+
+DEFAULT_BASE_URL = "https://api.hebrah.com"
+
+
+class SandboxScenarioSummary(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    events: list[str]
+    delay_seconds: float | int
+
+
+class SandboxDomainSummary(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    events: list[str]
+    resource_types: list[str]
+    hl7_message_types: dict[str, str]
+    scenarios: list[SandboxScenarioSummary]
+
+
+class SandboxCatalog(TypedDict, total=False):
+    org_id: str
+    org_name: str
+    connection_id: str
+    environment: str
+    sample_patient_ids: list[str]
+    supported_events: list[str]
+    example_patient_response: dict[str, Any]
+    example_webhook_envelope: dict[str, Any]
+    sandbox_domains: list[SandboxDomainSummary]
+    event_groups: dict[str, list[str]]
+    example_envelopes: dict[str, dict[str, Any]]
+    ehr_vendor: str | None
+    data_format: str | None
+    resource_types: list[str] | None
+    field_mappings: list[dict[str, Any]] | None
+
+
+class SandboxResourceListResponse(TypedDict):
+    resource_type: str
+    ids: list[str]
+
+
+class PayerRules(TypedDict):
+    id: str
+    name: str
+    required_documents: list[str]
+    typical_pend_reasons: list[str]
+    typical_denial_reasons: list[str]
+
+
+class RunScenarioResponse(TypedDict):
+    status: str
+    scenario_id: str
+    connection_id: str
+    events: list[str]
+    envelope_previews: list[dict[str, Any]]
+
+
+class PatientSummary(TypedDict):
+    id: str
+
+
+class PatientListResponse(TypedDict):
+    patients: list[PatientSummary]
+
+
+class TriggerMockEventResponse(TypedDict, total=False):
+    status: str
+    event: str
+    patient_id: str
+    connection_id: str
+    envelope_preview: dict[str, Any]
+    scenario_id: str
+
+
+class WebhookEventEnvelope(TypedDict, total=False):
+    event: str
+    resource: dict[str, Any]
+    connection_id: str
+    environment: str
+    timestamp: str
+    org_id: str
+    method: str
+    path: str
+    status_code: int
+    latency_ms: int
+
+
+LOCAL_HTTP_HOSTS = frozenset({"localhost", "127.0.0.1", "[::1]"})
+
+
+def assert_safe_base_url(url: str) -> None:
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    if not parsed.scheme or not parsed.netloc:
+        raise ValueError(f"Invalid base_url: {url}")
+
+    if parsed.scheme == "https":
+        return
+
+    if parsed.scheme == "http" and parsed.hostname in LOCAL_HTTP_HOSTS:
+        return
+
+    raise ValueError(
+        "base_url must use https:// or http://localhost/127.0.0.1 for local development "
+        f"(got {parsed.scheme}://{parsed.hostname})"
+    )
+
+
+def resolve_base_url(base_url: str | None = None) -> str:
+    url = (base_url or os.environ.get("HEBRAH_API_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+    assert_safe_base_url(url)
+    return url

hebrah/webhooks.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+
+from hebrah.types import WebhookEventEnvelope
+
+
+def verify_webhook_signature(
+    raw_body: bytes | str,
+    signature_header: str | None,
+    webhook_secret: str,
+) -> WebhookEventEnvelope:
+    """Verify X-Hebrah-Signature (HMAC-SHA256 hex) and return the parsed payload."""
+    if not signature_header:
+        raise ValueError("Missing X-Hebrah-Signature header")
+
+    raw = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+
+    expected = hmac.new(
+        webhook_secret.encode("utf-8"),
+        raw,
+        hashlib.sha256,
+    ).hexdigest()
+
+    if len(signature_header) != len(expected):
+        raise ValueError("Invalid webhook signature")
+
+    if not hmac.compare_digest(expected, signature_header):
+        raise ValueError("Invalid webhook signature")
+
+    return json.loads(raw.decode("utf-8"))

hebrah-0.8.1.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: hebrah
+Version: 0.8.1
+Summary: Official Python SDK for the hebrah control plane API
+Project-URL: Homepage, https://hebrah.com
+Project-URL: Documentation, https://app.hebrah.com/docs/sdk
+Project-URL: Repository, https://github.com/Hebrah-inc/hebrah-sdk-python
+Author: hebrah
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fhir,healthcare,hebrah,sdk,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hebrah
+
+Official Python SDK for the [hebrah](https://hebrah.com) control plane API (hebrah-api).
+
+## Install
+
+```bash
+pip install hebrah
+```
+
+Requires **Python 3.10+**.
+
+## Quick start
+
+```python
+import os
+from hebrah import HebrahClient, verify_webhook_signature
+
+with HebrahClient(
+    api_key=os.environ["HEBRAH_API_KEY"],
+    default_connection_id=os.environ.get("HEBRAH_CONNECTION_ID"),
+) as client:
+    catalog = client.sandbox.catalog()
+    patient_id = catalog["sample_patient_ids"][0]
+    patient = client.sandbox.resource("Patient", patient_id)
+
+    client.webhooks.trigger_mock_event(
+        event="patient.admitted",
+        patient_id=patient_id,
+    )
+```
+
+> **v0.8:** `default_connection_id` is applied when sandbox methods omit `connection_id`. `client.patients.list()` / `get()` emit `DeprecationWarning` — use `sandbox.list_synthetic_resources("Patient")` instead.
+
+### Webhook verification
+
+```python
+from hebrah import verify_webhook_signature
+
+payload = verify_webhook_signature(
+    request.get_data(),
+    request.headers.get("X-Hebrah-Signature"),
+    webhook_secret,
+)
+```
+
+## Security
+
+- Store `HEBRAH_API_KEY` and `HEBRAH_WEBHOOK_SECRET` in server-side environment variables or a secrets manager only — never expose them to browsers or commit `.env` files.
+- The SDK does not persist credentials; they live in memory for the lifetime of each `HebrahClient` instance.
+- `base_url` must be `https://` in production, or `http://localhost` / `http://127.0.0.1` for local dev — other `http://` hosts are rejected at construction to reduce API-key exfiltration risk.
+- Treat `HebrahApiError.detail` as operator-only diagnostics. Do not log or return it to end users — it may contain internal paths or sensitive API error payloads. Set `include_error_detail=False` on `HebrahClient` to omit `detail` from errors.
+
+See [SECURITY.md](./SECURITY.md) for supported versions and vulnerability reporting.
+
+## API surface (v0.8)
+
+### Sandbox & resources
+
+| Method | Description |
+|--------|-------------|
+| `client.health()` | `GET /health` (no API key on separate httpx call) |
+| `client.sandbox.catalog(connection_id=None)` | `GET /v1/sandbox/catalog` — uses `default_connection_id` when omitted |
+| `client.sandbox.domains()` | `GET /v1/sandbox/domains` |
+| `client.sandbox.domain(domain_id)` | `GET /v1/sandbox/domains/{id}` |
+| `client.sandbox.list_synthetic_resources(resource_type, connection_id=None)` | `GET /v1/sandbox/resources/{type}` |
+| `client.sandbox.resource(resource_type, resource_id, patient_id=None)` | `GET /v1/sandbox/resources/{type}/{id}` |
+| `client.sandbox.run_scenario(scenario_id, ...)` | `POST /v1/sandbox/scenarios/{id}/run` |
+| `client.sandbox.synthetic_ehr_profile(connection_id=...)` | `GET /v1/sandbox/synthetic-ehr/profile` |
+| `client.sandbox.list_ehr_models()` | `GET /v1/sandbox/ehr-models` |
+| `client.sandbox.reset_synthetic_ehr(connection_id=...)` | `POST /v1/sandbox/synthetic-ehr/reset` |
+| `client.sandbox.payer_rules(payer_id)` | `GET /v1/sandbox/payer-rules/{id}` |
+| `client.patients.list(connection_id=None)` | **Deprecated** — `GET /v1/patients` |
+| `client.patients.get(id, connection_id=None)` | **Deprecated** — `GET /v1/patients/{id}` |
+
+### HL7, webhooks, interop
+
+| Method | Description |
+|--------|-------------|
+| `client.sandbox.hl7_templates()` | `GET /v1/sandbox/hl7/templates` |
+| `client.sandbox.inject_hl7(...)` | `POST /v1/sandbox/hl7/inject` |
+| `client.sandbox.configure_webhook_reliability(**profile)` | `PATCH /v1/sandbox/webhook-reliability` |
+| `client.sandbox.run_webhook_reliability_scenario(scenario_id, ...)` | `POST /v1/sandbox/scenarios/{id}/run` (alias) |
+| `client.sandbox.run_mpi_match(...)` | `POST /v1/sandbox/mpi/match` |
+| `client.sandbox.run_aggregator_query(...)` | `POST /v1/sandbox/aggregator/query` |
+| `client.sandbox.get_practitioner_credentialing(practitioner_id)` | `GET /v1/sandbox/credentialing/practitioners/{id}` |
+| `client.webhooks.trigger_mock_event(...)` | `POST /v1/webhooks/trigger-mock-event` |
+| `client.webhooks.list_deliveries(...)` | `GET /v1/webhooks/deliveries` |
+| `client.webhooks.replay_delivery(delivery_id)` | `POST /v1/webhooks/deliveries/{id}/replay` |
+| `verify_webhook_signature(raw_body, signature, secret)` | Local HMAC-SHA256 verify |
+
+### SMART & FHIR
+
+| Method | Description |
+|--------|-------------|
+| `client.smart.launch(...)` | `POST /v1/smart/launch` |
+| `client.smart.register_client(...)` | `POST /v1/smart/clients` |
+| `client.smart.exchange_token(...)` | `POST /oauth/token` (form-encoded; no API key) |
+| `client.fhir.read_patient(patient_id, access_token)` | `GET /fhir/R4/Patient/{id}` (SMART access token) |
+
+### Advanced: BYOM agent harness
+
+`HebrahAgentHarness` is exported for bring-your-own-model EHR workflows (MCP + integration-agent). It is **not** part of the core integrator quick start — harness improvements are tracked separately from the core client.
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `HEBRAH_API_KEY` | Pass to `HebrahClient(api_key=...)` |
+| `HEBRAH_API_BASE_URL` | Optional; default `https://api.hebrah.com` |
+| `HEBRAH_CONNECTION_ID` | Optional; pass to `default_connection_id` for sandbox reads |
+| `HEBRAH_WEBHOOK_SECRET` | For `verify_webhook_signature` |
+
+## Docs
+
+Full integrator reference: [hebrah-app `/docs/sdk`](https://app.hebrah.com/docs/sdk).
+
+## License
+
+MIT

hebrah-0.8.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+hebrah/__init__.py,sha256=qcOEZDBw9CWPTmW9hF4FDlD4DZa_kQu_yi228SVTavE,383
+hebrah/client.py,sha256=GO8VWylmeA1CAaYo0Nr9aOpZRjrjqLZLqHrmkwYPAKg,16686
+hebrah/errors.py,sha256=VuNSyhZyr72K3WjeFLc4YsZ8MzjWw8wBOFhcjrpocV4,287
+hebrah/harness.py,sha256=zgVxBbVrTSZmXeYxQY64jrCn6kgLukGi9zoEbVJfsQo,4472
+hebrah/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hebrah/types.py,sha256=ub1hs2qGLD76OZ_--Yi_JkW2PJg7WM-K7x6qMy4uFxs,2843
+hebrah/webhooks.py,sha256=KobTpOmJP648YN9fCkpqh177FgN0ZgM8kbdBE6FAWCA,903
+SECURITY.md,sha256=UetLWOPGRi6hLKSkkv-CdMQTpQUntzbAk3sCa8zwlUM,1451
+hebrah-0.8.1.dist-info/METADATA,sha256=drC-L1GjpztFRi-SgazUc7yjU8T-l1xfGW3K-Fx1I0k,6408
+hebrah-0.8.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+hebrah-0.8.1.dist-info/licenses/LICENSE,sha256=HElH-jMejKWrn_uksovpqgADmPChn2mGdADHDmJ0IOg,1069
+hebrah-0.8.1.dist-info/RECORD,,

hebrah-0.8.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hebrah-0.8.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hebrah, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.