@hubbleai/hubble-sdk

TypeScript client for the Hubble Patient Access API: create patient authorization links, exchange them for consent-scoped access tokens, and read FHIR R4 data.

import { Hubble } from "@hubbleai/hubble-sdk";

const hub = new Hubble({ clientId: "hbl_client_prod_...", clientSecret: "hbl_prod_..." });

// 1. Create a patient link and send the patient to it. Optionally prefill with
//    patient: { firstName, ... } demographics, providers: [{ name }], and the
//    optional organization your verified Hubble organization represents.
const link = await hub.createLink({ patientRef: "abc123", onBehalfOfOrganizationName: "Acme Health" });
console.log(link.verification_uri_complete);

// 2. Wait for the patient to authorize (polls the token endpoint for you).
const session = await hub.waitForAuthorization(link);

// 3. Read the patient's FHIR data (Bearer token + auto-refresh handled for you).
const bundle = await session.everything();
const observations = await session.fhir("Observation", { query: { category: "vital-signs" } });
const pdf = await session.exportPdf(); // pdf.data bytes; pdf.sourcesFailed counts failed sources

// Consent management
for (const consent of await hub.listConsents({ status: "active" })) {
  console.log(consent.id, consent.patient_ref);
}
await hub.revokeConsent(session.consentId!);

What the client handles for you

• Auth per plane — HTTP Basic (your app credentials) for consent management and the token endpoint; Bearer (the consent token) for FHIR reads.
• Default base URL — https://portal.hubble.ai. Override only with a trusted value; your access token is sent to it.
• Device-flow polling — waitForAuthorization honors the server's interval and slow_down.
• Correct FHIR paths — paths like Patient/$everything are sent unencoded.
• Transparent refresh — FHIR reads refresh and retry once on a 401.
• Typed FHIR responses — reads are typed against @types/fhir (R4): everything()/summary() return a Bundle, and fhir() returns the FhirResource union. Narrow with a type argument, e.g. session.fhir<Patient>("Patient/123").

Ships as ESM and CommonJS with type declarations.

Layout

Hubble / PatientSession are hand-written (src/hubble.ts). The low-level client generated from the OpenAPI contract with @hey-api/openapi-ts lives in src/client (regenerated on every spec change; never edited by hand) and is also re-exported for direct access. See the repo root README for how to regenerate.