@healthcloudai/hc-sdk 0.9.1 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -114,21 +114,32 @@ const token = sdk.getAccessToken(); // string | undefined
114
114
  ## Service groups
115
115
 
116
116
  ```ts
117
- sdk.auth // register / login / verify-email
118
- sdk.patient // connect, profile, address, phone, photo, medications, encounters, insurance,
119
- // questionnaires, locations, vision face-compare, assistant (classify/ocr/chat/
120
- // knowledge), CareConnect communications (presence/groups/conversations/messages/invites/rtc-token)
117
+ sdk.auth // register / login / verifyEmail / resetPassword / confirmPassword
118
+ // (login auto-stores the access_token on the SDK)
119
+ sdk.person // register / login / verifyEmail / resetPassword / confirmPassword,
120
+ // updatePhone / verifySms, get / update, photo
121
+ // (see Person section; login/register do NOT auto-store the token)
122
+ sdk.patient // connect, profile/dashboard, address/phone/sms, demographics, photo, vision
123
+ // face-compare, identity-document OCR, insurance-card OCR, medications, encounters,
124
+ // insurance (create/list/eligibility), questionnaires, nearest locations,
125
+ // assistant (classify/ocr/chat/knowledge), CareConnect communications
126
+ // (presence/groups/conversations/messages/invites/rtc-token),
127
+ // import (CCDA / health-record / vitals / activity), preferred pharmacy,
128
+ // dependents, notifications, agent configuration / current care session /
129
+ // check-in / sidebar, current screening symptoms
130
+ sdk.provider // register / login / verifyEmail / resetPassword / confirmPassword,
131
+ // updatePhone / verifySms, get / update, photo
132
+ // (see Provider section; login/register do NOT auto-store the token)
121
133
  sdk.vitals // connect, record and list vitals
122
- sdk.diagnostics // connect, rapid tests, list diagnostics
123
- sdk.provider // connect + low-level request escape hatch
134
+ sdk.diagnostics // connect, list, createRapidTest, lookupByGs1, getScanUploadUrl, getTestResult
124
135
  sdk.ehr // connect + low-level request escape hatch
125
- sdk.appointments // connect + low-level request escape hatch
136
+ sdk.appointments // connect, listSlots, createSlot, book, cancel, reschedule, listPatientAppointments
126
137
  sdk.rppg // connect + low-level request escape hatch
127
138
  sdk.session // connect + low-level request escape hatch
128
139
  sdk.telehealth // connect, createChannel, createPatientToken, createProviderToken, fetchRtcToken
129
- sdk.fieldAgent // connect, register/login/resetPassword/verifyEmail/verifySms,
140
+ sdk.fieldAgent // connect, register/login/resetPassword/confirmPassword/verifyEmail/verifySms,
130
141
  // getAgent/updateAgent, getDashboard, photo, listPatients, listEncounters
131
- sdk.mcp // connect + JSON-RPC proxy (patient/fieldAgent tool calls)
142
+ sdk.mcp // connect + JSON-RPC proxy (patient / fieldAgent / assistant / communications / person)
132
143
  sdk.graph // connect, provider search/cypher, health plan search/cypher,
133
144
  // document/medical-concept search/cypher, medical-concept
134
145
  // list/detail/hierarchy, policy document list/search/get
@@ -138,9 +149,10 @@ sdk.graph // connect, provider search/cypher, health plan search/cypher
138
149
  than `sdk.auth`/`sdk.patient` (`*-api-patient.health.cloud`) and has its own
139
150
  login. **A single `HCSDK` instance holds one bearer token** — calling
140
151
  `sdk.fieldAgent.login()` overwrites the token set by `sdk.auth.login()` (and
141
- vice versa). If your app needs an authenticated patient session and an
142
- authenticated field-agent session at the same time, create two `HCSDK`
143
- instances.
152
+ vice versa). The same single-token caveat applies to `sdk.person.login()` and
153
+ `sdk.provider.login()`. If your app needs multiple authenticated sessions at
154
+ the same time (patient + field agent, person + provider, etc.), create one
155
+ `HCSDK` instance per session.
144
156
 
145
157
  All groups share one HTTP client, one token store, one error handler, the same URL resolver, query serialiser, and path-param interpolator.
146
158
 
@@ -225,6 +237,115 @@ Authentication notes:
225
237
 
226
238
  ---
227
239
 
240
+ ## Person
241
+
242
+ `sdk.person` is the HC Person identity API (a separate host from the Patient
243
+ API — `*-api-person.health.cloud`). It mirrors the Auth client surface with
244
+ its own register/login/verify-email/reset-password flow, plus identity CRUD
245
+ and photo management. All routes are scoped to `/persons/{person_id}`.
246
+
247
+ **Important — token persistence:** unlike `sdk.auth.login()` and
248
+ `sdk.fieldAgent.login()`, **neither `sdk.person.login()` nor
249
+ `sdk.person.register()` call `sdk.setAccessToken(...)` internally.** The
250
+ response body contains `access_token`, but you must persist it yourself
251
+ before the next authenticated call:
252
+
253
+ ```ts
254
+ const data = await sdk.person.login({ email, password });
255
+ if (!data.access_token) throw new Error("no access_token");
256
+ sdk.setAccessToken(data.access_token); // ← required
257
+ const me = await sdk.person.get(data.fhir_person_id);
258
+ ```
259
+
260
+ `PersonLoginResponse` and `RegisterPersonResponse` include
261
+ `fhir_person_id: string`. Prefer this returned id over any cached id from a
262
+ prior session — on a fresh app launch the cache is `undefined`, which is the
263
+ most common source of downstream `4xx` errors.
264
+
265
+ Public methods (all auth routes are public; CRUD and photo require a bearer):
266
+
267
+ - Auth: `register`, `login`, `verifyEmail`, `resetPassword`, `confirmPassword`
268
+ - Identity CRUD: `updatePhone`, `verifySms`, `get`, `update`
269
+ - Photo: `getPhotoUploadUrl`, `uploadPhoto`, `getPhoto`
270
+
271
+ ```ts
272
+ const created = await sdk.person.register({
273
+ first_name: "Jane",
274
+ last_name: "Doe",
275
+ email: "jane@example.com",
276
+ password: "SecurePassword123!",
277
+ date_of_birth: "1990-06-15",
278
+ });
279
+ sdk.setAccessToken(created.access_token);
280
+
281
+ const person = await sdk.person.get(created.fhir_person_id);
282
+ await sdk.person.update(person.id, { phone: "+15551234567" });
283
+ ```
284
+
285
+ ---
286
+
287
+ ## Provider
288
+
289
+ `sdk.provider` is the HC Provider (Practitioner) identity API on
290
+ `*-api-provider.health.cloud`. It uses `/practitioners/{practitioner_id}` for
291
+ identity and photo routes, but the auth routes (`/auth/register`,
292
+ `/auth/login`, ...) are shared with the Person/Patient hosts.
293
+
294
+ **Same token-persistence caveat as Person:** `sdk.provider.login()` and
295
+ `sdk.provider.register()` do NOT call `sdk.setAccessToken(...)` — persist the
296
+ returned bearer yourself before any subsequent call.
297
+
298
+ `PractitionerLoginResponse` and `RegisterPractitionerResponse` include
299
+ `fhir_provider_id: string` (note: `fhir_provider_id`, **not**
300
+ `fhir_practitioner_id`). Use this as the path id for all
301
+ `/practitioners/{practitioner_id}/...` calls.
302
+
303
+ Public methods:
304
+
305
+ - Auth: `register`, `login`, `verifyEmail`, `resetPassword`, `confirmPassword`
306
+ - Practitioner CRUD: `updatePhone`, `verifySms`, `get`, `update`
307
+ - Photo: `getPhotoUploadUrl`, `uploadPhoto`, `getPhoto`
308
+
309
+ ```ts
310
+ const data = await sdk.provider.login({ email, password });
311
+ sdk.setAccessToken(data.access_token); // ← required
312
+
313
+ const provider = await sdk.provider.get(data.fhir_provider_id);
314
+ await sdk.provider.updatePhone(provider.id, { phone: "+15551234567" });
315
+ ```
316
+
317
+ ---
318
+
319
+ ## Appointments
320
+
321
+ `sdk.appointments` is the HC Appointments API on
322
+ `*-api-appointments.health.cloud`. It exposes a typed Slot + Booking surface
323
+ (no need to fall through to the low-level request escape hatch):
324
+
325
+ - Slots: `listSlots(query?)`, `createSlot(request)`
326
+ - Bookings: `book(request)`, `cancel(appointmentId)`, `reschedule(appointmentId, request)`
327
+ - Per-patient: `listPatientAppointments(patientId, query?)`
328
+
329
+ ```ts
330
+ const slots = await sdk.appointments.listSlots({ date_from, date_to });
331
+
332
+ const booked = await sdk.appointments.book({
333
+ slot_id: slots.slots[0].slot_id,
334
+ patient_id: fhirPatientId,
335
+ reason_code: "routine",
336
+ });
337
+
338
+ const upcoming = await sdk.appointments.listPatientAppointments(fhirPatientId, {
339
+ status: "scheduled",
340
+ });
341
+ ```
342
+
343
+ Patient insurance (the `BookAppointmentRequest` payload may carry payer
344
+ information) is covered on `sdk.patient` via `createInsurance`,
345
+ `listPatientInsurances`, and `checkInsuranceEligibility`.
346
+
347
+ ---
348
+
228
349
  ## Connectors (`sdk.connectors`)
229
350
 
230
351
  Connector clients are created in three explicit steps:
@@ -355,7 +476,7 @@ try {
355
476
 
356
477
  ### Available connectors
357
478
 
358
- All 33 connectors follow the same pattern: `sdk.connectors.<name>.createClient({ ...credentials })` returns an isolated, credential-scoped client whose methods call `POST /connectors/<slug>/<operation>` on the HealthCloud Connectors gateway. The table lists each connector's required credential fields and the conventional `HC_*` environment variable names used by the live test suite (names only — never commit values). Fields marked `mode?` accept `"sandbox"` (default) or `"live"`.
479
+ All 32 connectors follow the same pattern: `sdk.connectors.<name>.createClient({ ...credentials })` returns an isolated, credential-scoped client whose methods call `POST /connectors/<slug>/<operation>` on the HealthCloud Connectors gateway. The table lists each connector's required credential fields and the conventional `HC_*` environment variable names used by the live test suite (names only — never commit values). Fields marked `mode?` accept `"sandbox"` (default) or `"live"`.
359
480
 
360
481
  | Connector | Purpose | `createClient` credentials | Suggested env vars | Called via |
361
482
  |---|---|---|---|---|
@@ -560,6 +681,26 @@ await sdk.patient.updateRace("patient-id", { races: ["white"] });
560
681
  { "updated": true }
561
682
  ```
562
683
 
684
+ ```ts
685
+ // Get a patient's boolean feature/state flags — {} if none are set
686
+ const flags = await sdk.patient.getFlags("patient-id");
687
+ ```
688
+
689
+ ```json
690
+ { "imported_vitals": true }
691
+ ```
692
+
693
+ ```ts
694
+ // Update flags — a partial merge, not a replace: only the flags named here
695
+ // change, every other existing flag is left unchanged. Idempotent. Returns
696
+ // the complete flags dictionary after the merge.
697
+ await sdk.patient.updateFlags("patient-id", { onboarding_completed: true });
698
+ ```
699
+
700
+ ```json
701
+ { "imported_vitals": true, "onboarding_completed": true }
702
+ ```
703
+
563
704
  ```ts
564
705
  // Update demographics — partial update, all fields optional
565
706
  await sdk.patient.updateDemographics("patient-id", {
@@ -667,6 +808,36 @@ relays Stedi's response (or Stedi's own `400` for an unrecognized
667
808
  payer/member) verbatim. There's no fixed HealthCloud schema for this
668
809
  response, so it's typed as `InsuranceEligibilityResponse` (`JsonValue`).
669
810
 
811
+ ```ts
812
+ // List the patient's stored insurances
813
+ const insurances = await sdk.patient.listPatientInsurances("patient-id");
814
+ ```
815
+
816
+ ### Records, import, pharmacy, dependents, notifications
817
+
818
+ A growing set of patient routes are reachable via typed client methods but
819
+ return **untyped `JsonValue` payloads** — the contracts aren't fully
820
+ stabilized, so responses are not yet generated models. The methods are:
821
+
822
+ | Area | Methods | Routes |
823
+ |---|---|---|
824
+ | Health-record / CCDA import | `importHealthRecord`, `importCCDA` | `POST /patients/{id}/health-record/import` |
825
+ | Vitals / activity import | `importVitals`, `importActivity`, `listActivity`, `deleteActivity` | `/patients/{id}/vitals/import`, `/patients/{id}/activity*` |
826
+ | Preferred pharmacy | `getPreferredPharmacy`, `setPreferredPharmacy` | `GET|PUT /patients/{id}/preferred-pharmacy` |
827
+ | Dependents | `listDependents`, `saveDependent`, `deleteDependent` | `/patients/{id}/dependents*` |
828
+ | Notifications | `listNotifications`, `saveNotification`, `deleteNotification` | `/patients/{id}/notifications*` |
829
+ | Agent configuration | `getAgentConfiguration`, `getAgent` | `GET /agentconfiguration`, `GET /agent` |
830
+ | Care session / check-in / sidebar | `getCheckin`, `getCurrentCareSession`, `getPatientSidebar` | `GET /checkin`, `GET /care-sessions/current`, `GET /patient/sidebar` |
831
+ | Current screening symptoms | `createCurrentScreeningSymptoms` | `POST /screenings/current/symptoms` |
832
+
833
+ `importCCDA` accepts a CCDA XML document as a UTF-8 string and internally
834
+ base64-encodes it into a FHIR `Binary` payload before posting.
835
+ `importVitals`/`importActivity` take an opaque `source` vendor identifier and
836
+ an arbitrary JSON `payload`; `saveDependent`/`saveNotification` switch between
837
+ create (POST) and update (PUT) based on whether an id is passed.
838
+ `createCurrentScreeningSymptoms` POSTs an opaque `{ symptoms: string[] }` body.
839
+ These will be promoted to fully-typed models in a future release.
840
+
670
841
  ### Medications
671
842
 
672
843
  Required fields: `name`, `route`, `dosage.value`, `dosage.unit`, `dosage.frequency`, `status`.
@@ -890,6 +1061,20 @@ const ocr = await sdk.patient.ocrIdentityDocument({
890
1061
 
891
1062
  Soft failure: `{ "type": "ocr_error", "ok": false, "error": "" }`. Hard failure: `{ "type": "ocr_error", "ok": false, "error": "Couldn't read the document. Check the image and try again." }`.
892
1063
 
1064
+ `ocrInsuranceDocument` (added in 0.9.0) uses the exact same `OcrRequest`/`OcrResponse`
1065
+ envelope as `ocrIdentityDocument` but posts to the dedicated
1066
+ `POST /assistant/ocr-insurance` route with an insurance-card schema — `fields`
1067
+ includes `payerName`, `memberId`, `groupId`, `planName`, `planType`,
1068
+ `effectiveDate`, `subscriberName`, `subscriberDob`, `policyNumber`, and `bin`.
1069
+ It is also public (no bearer).
1070
+
1071
+ ```ts
1072
+ const card = await sdk.patient.ocrInsuranceDocument({
1073
+ image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
1074
+ });
1075
+ // card.fields.payerName, card.fields.memberId, card.fields.groupId, ...
1076
+ ```
1077
+
893
1078
  ```ts
894
1079
  // Grounded RAG chat — answers only from the fixed internal knowledge base
895
1080
  const chat = await sdk.patient.askAssistant({ message: "What PPE should I wear for screening?" });
package/dist/index.cjs CHANGED
@@ -63,6 +63,7 @@ __export(index_exports, {
63
63
  ZocdocClient: () => ZocdocClient,
64
64
  ZusClient: () => ZusClient,
65
65
  assertEnvironment: () => assertEnvironment,
66
+ isJsonRpcError: () => isJsonRpcError,
66
67
  isServiceName: () => isServiceName,
67
68
  resolveBaseUrl: () => resolveBaseUrl,
68
69
  withTenantId: () => withTenantId
@@ -169,9 +170,10 @@ var HttpClient = class {
169
170
  return headers;
170
171
  }
171
172
  buildUrl(service, path, options) {
172
- var _a;
173
+ var _a, _b, _c;
173
174
  const normalizedPath = this.resolvePath(path, (_a = options.pathParams) != null ? _a : {});
174
- const url = new URL(`${resolveBaseUrl(this.state.environment, service)}${normalizedPath}`);
175
+ const base = (_c = (_b = this.state.baseUrlOverrides) == null ? void 0 : _b[service]) != null ? _c : resolveBaseUrl(this.state.environment, service);
176
+ const url = new URL(`${base}${normalizedPath}`);
175
177
  if (options.query) {
176
178
  for (const [key, value] of Object.entries(options.query)) {
177
179
  this.appendQuery(url, key, value);
@@ -406,6 +408,12 @@ var AuthClient = class extends BaseServiceClient {
406
408
  auth: false
407
409
  });
408
410
  }
411
+ async resendEmailVerification(request) {
412
+ return this.send("POST", "/auth/resend-verification-code", {
413
+ body: withTenantId(request, this.getTenantId()),
414
+ auth: false
415
+ });
416
+ }
409
417
  };
410
418
 
411
419
  // src/clients/DiagnosticsClient.ts
@@ -585,6 +593,7 @@ var FieldAgentClient = class extends BaseServiceClient {
585
593
  };
586
594
 
587
595
  // src/clients/MCPClient.ts
596
+ var nextRequestId = 1;
588
597
  var MCPClient = class extends BaseServiceClient {
589
598
  constructor(http) {
590
599
  super(http, "mcp");
@@ -592,28 +601,75 @@ var MCPClient = class extends BaseServiceClient {
592
601
  connect() {
593
602
  return this.connectService();
594
603
  }
595
- sendToAudience(audience, request) {
604
+ /**
605
+ * Low-level JSON-RPC 2.0 transport: send any request to one audience.
606
+ * Named `rpc` (not `request`) because `BaseServiceClient.request` is
607
+ * already the generic per-path REST escape hatch with an incompatible
608
+ * signature; this also matches the Python SDK's `MCPClient.rpc(...)`.
609
+ * Prefer `initialize`/`listTools`/`callTool` for the three standard MCP
610
+ * methods — this exists so a newly deployed tool or method can be reached
611
+ * before a generated convenience method catches up.
612
+ */
613
+ rpc(audience, request) {
596
614
  return this.send("POST", `/${audience}`, { body: request });
597
615
  }
598
- /** Calls one of the 14 Patient API tools via `POST /patient`. */
599
- patient(request) {
600
- return this.sendToAudience("patient", request);
616
+ /** `initialize` — negotiates the MCP protocol version and capabilities. */
617
+ initialize(audience) {
618
+ return this.rpc(audience, {
619
+ jsonrpc: "2.0",
620
+ id: nextRequestId++,
621
+ method: "initialize",
622
+ params: {}
623
+ });
601
624
  }
602
- /** Calls one of the 8 Field Agent API tools via `POST /fieldagent`. */
603
- fieldAgent(request) {
604
- return this.sendToAudience("fieldagent", request);
625
+ /**
626
+ * `notifications/initialized` — the gateway replies with HTTP 204 (no
627
+ * body) per the JSON-RPC notification convention; `HttpClient` already
628
+ * surfaces a 204 as `undefined`, so this resolves with `void`.
629
+ */
630
+ async notifyInitialized(audience) {
631
+ await this.send("POST", `/${audience}`, {
632
+ body: { jsonrpc: "2.0", method: "notifications/initialized", params: {} }
633
+ });
605
634
  }
606
- /** Calls one of the Assistant API tools via `POST /assistant`. */
607
- assistant(request) {
608
- return this.sendToAudience("assistant", request);
635
+ /** `tools/list` — every tool the gateway serves for this audience. */
636
+ listTools(audience) {
637
+ return this.rpc(audience, {
638
+ jsonrpc: "2.0",
639
+ id: nextRequestId++,
640
+ method: "tools/list",
641
+ params: {}
642
+ });
609
643
  }
610
- /** Calls one of the Communications API tools via `POST /communications`. */
611
- communications(request) {
612
- return this.sendToAudience("communications", request);
644
+ /** `tools/call` — invoke one tool by its exact MCP tool name. */
645
+ callTool(audience, name, args = {}, id = nextRequestId++) {
646
+ return this.rpc(audience, {
647
+ jsonrpc: "2.0",
648
+ id,
649
+ method: "tools/call",
650
+ params: { name, arguments: args }
651
+ });
613
652
  }
614
- /** Calls one of the Person API tools via `POST /person`. */
653
+ /**
654
+ * @deprecated Prefer `rpc("patient", ...)` or `callTool("patient", ...)`.
655
+ * Kept for backward compatibility; delegates to the generic transport.
656
+ */
657
+ patient(request) {
658
+ return this.rpc("patient", request);
659
+ }
660
+ /**
661
+ * @deprecated Prefer `rpc("fieldagent", ...)` or `callTool("fieldagent", ...)`.
662
+ * Kept for backward compatibility; delegates to the generic transport.
663
+ */
664
+ fieldAgent(request) {
665
+ return this.rpc("fieldagent", request);
666
+ }
667
+ /**
668
+ * @deprecated Prefer `rpc("person", ...)` or `callTool("person", ...)`.
669
+ * Kept for backward compatibility; delegates to the generic transport.
670
+ */
615
671
  person(request) {
616
- return this.sendToAudience("person", request);
672
+ return this.rpc("person", request);
617
673
  }
618
674
  };
619
675
 
@@ -649,6 +705,36 @@ var PatientClient = class extends BaseServiceClient {
649
705
  body: request
650
706
  });
651
707
  }
708
+ /**
709
+ * Get a patient's complete boolean flags dictionary, e.g. `{ imported_vitals: true }`.
710
+ * GET /patients/{id}/flags
711
+ *
712
+ * @param fhirPatientId - The FHIR Patient ID
713
+ * @returns The complete flags dictionary; `{}` if the patient has no flags set.
714
+ */
715
+ getFlags(fhirPatientId) {
716
+ return this.send("GET", "/patients/{id}/flags", {
717
+ pathParams: { id: fhirPatientId }
718
+ });
719
+ }
720
+ /**
721
+ * Partially update a patient's boolean flags dictionary.
722
+ * PATCH /patients/{id}/flags
723
+ *
724
+ * This is a merge, not a replace: only the flag names present in `request`
725
+ * are changed, every other existing flag is left unchanged. Setting the
726
+ * same value again is idempotent. Returns the complete flags dictionary
727
+ * after the merge.
728
+ *
729
+ * @param fhirPatientId - The FHIR Patient ID
730
+ * @param request - One or more `{ flagName: boolean }` entries to merge in
731
+ */
732
+ updateFlags(fhirPatientId, request) {
733
+ return this.send("PATCH", "/patients/{id}/flags", {
734
+ pathParams: { id: fhirPatientId },
735
+ body: request
736
+ });
737
+ }
652
738
  getProfile(fhirPatientId) {
653
739
  return this.send("GET", "/patients/{id}", {
654
740
  pathParams: { id: fhirPatientId }
@@ -4290,7 +4376,8 @@ var HCSDK = class {
4290
4376
  this.state = {
4291
4377
  environment: config.environment,
4292
4378
  tenantId: config.tenantId,
4293
- accessToken: config.accessToken
4379
+ accessToken: config.accessToken,
4380
+ baseUrlOverrides: config.baseUrlOverrides
4294
4381
  };
4295
4382
  this.http = new HttpClient(this.state);
4296
4383
  this.auth = new AuthClient(
@@ -4325,6 +4412,11 @@ var HCSDK = class {
4325
4412
  }
4326
4413
  };
4327
4414
 
4415
+ // src/models/generated/mcp.ts
4416
+ function isJsonRpcError(response) {
4417
+ return "error" in response && response.error !== void 0;
4418
+ }
4419
+
4328
4420
  // src/models/generated/operations.ts
4329
4421
  var HCSDK_OPERATION_SUMMARY = [
4330
4422
  { service: "patient", method: "GET", path: "/connect", sdkMethod: "patient.connect", summary: "Lambda warm-up / connectivity check" },
@@ -4453,6 +4545,7 @@ var HCSDK_SWAGGER_OPERATION_COUNTS = {
4453
4545
  ZocdocClient,
4454
4546
  ZusClient,
4455
4547
  assertEnvironment,
4548
+ isJsonRpcError,
4456
4549
  isServiceName,
4457
4550
  resolveBaseUrl,
4458
4551
  withTenantId