@healthcloudai/hc-sdk 0.3.0 → 0.5.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 +345 -156
- package/dist/index.cjs +154 -53
- package/dist/index.d.cts +823 -406
- package/dist/index.d.ts +823 -406
- package/dist/index.js +152 -52
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
All-in-one TypeScript SDK for the `*.health.cloud` APIs. Zero runtime dependencies — uses the platform `fetch` that ships in Node 18+ and React Native.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
HealthCloud endpoints don't wrap responses in a generic envelope: each
|
|
6
|
+
endpoint returns its own JSON body directly, and each one has its own
|
|
7
|
+
concrete request/response type. The one shape that's genuinely universal
|
|
8
|
+
across the SDK is connectivity — every service's `GET /connect` returns the
|
|
9
|
+
same `ConnectResponse` (see [Connectivity and service stubs](#connectivity-and-service-stubs)).
|
|
10
|
+
|
|
11
|
+
The one endpoint with no fixed shape is `checkInsuranceEligibility` —
|
|
12
|
+
HealthCloud forwards the call to Stedi and relays whatever Stedi returns, so
|
|
13
|
+
it's typed as `JsonValue`.
|
|
6
14
|
|
|
7
15
|
---
|
|
8
16
|
|
|
@@ -16,12 +24,6 @@ No peer dependencies are required. `react-native` is an optional peer (the SDK w
|
|
|
16
24
|
|
|
17
25
|
---
|
|
18
26
|
|
|
19
|
-
## Zero runtime dependencies
|
|
20
|
-
|
|
21
|
-
`package.json` contains no `dependencies` field. Everything at runtime is TypeScript types (erased) and the platform `fetch` global.
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
27
|
## Quick start
|
|
26
28
|
|
|
27
29
|
```ts
|
|
@@ -55,7 +57,7 @@ const registration = await sdk.auth.register({
|
|
|
55
57
|
}
|
|
56
58
|
```
|
|
57
59
|
|
|
58
|
-
`dev
|
|
60
|
+
In `dev`, `registration.access_token` is already usable — no separate login call is needed. In `uat`/`prod`, `email_otp_sent` is `true` and tokens are omitted; call `verifyEmail` then `login`.
|
|
59
61
|
|
|
60
62
|
```ts
|
|
61
63
|
// 2. Verify email OTP (uat/prod only — dev auto-verifies and returns a token)
|
|
@@ -87,7 +89,7 @@ const patient = await sdk.patient.getProfile("patient-id");
|
|
|
87
89
|
```ts
|
|
88
90
|
const sdk = new HCSDK({
|
|
89
91
|
environment: "dev", // required
|
|
90
|
-
tenantId: "eclinicapi", // optional — injected
|
|
92
|
+
tenantId: "eclinicapi", // optional — injected into /auth/* request bodies only; never sent as a header
|
|
91
93
|
accessToken: "existing-token", // optional — skip login if you already have a token
|
|
92
94
|
});
|
|
93
95
|
```
|
|
@@ -124,8 +126,19 @@ sdk.appointments // connect + low-level request escape hatch
|
|
|
124
126
|
sdk.rppg // connect + low-level request escape hatch
|
|
125
127
|
sdk.session // connect + low-level request escape hatch
|
|
126
128
|
sdk.telehealth // connect + low-level request escape hatch
|
|
129
|
+
sdk.fieldAgent // connect, register/login/resetPassword/verifyEmail/verifySms,
|
|
130
|
+
// getAgent/updateAgent, getDashboard, photo, listPatients, listEncounters
|
|
131
|
+
sdk.mcp // connect + JSON-RPC proxy (patient/fieldAgent tool calls)
|
|
127
132
|
```
|
|
128
133
|
|
|
134
|
+
`sdk.fieldAgent` talks to a different host (`*-api-fieldagent.health.cloud`)
|
|
135
|
+
than `sdk.auth`/`sdk.patient` (`*-api-patient.health.cloud`) and has its own
|
|
136
|
+
login. **A single `HCSDK` instance holds one bearer token** — calling
|
|
137
|
+
`sdk.fieldAgent.login()` overwrites the token set by `sdk.auth.login()` (and
|
|
138
|
+
vice versa). If your app needs an authenticated patient session and an
|
|
139
|
+
authenticated field-agent session at the same time, create two `HCSDK`
|
|
140
|
+
instances.
|
|
141
|
+
|
|
129
142
|
All groups share one HTTP client, one token store, one error handler, the same URL resolver, query serialiser, and path-param interpolator.
|
|
130
143
|
|
|
131
144
|
---
|
|
@@ -137,7 +150,7 @@ All groups share one HTTP client, one token store, one error handler, the same U
|
|
|
137
150
|
await sdk.auth.register({
|
|
138
151
|
email: "patient@example.com",
|
|
139
152
|
password: "SecurePassword123!",
|
|
140
|
-
tenant_id
|
|
153
|
+
// no tenant_id here — the SDK injects it from the `tenantId` passed to the HCSDK constructor
|
|
141
154
|
first_name: "Jane",
|
|
142
155
|
last_name: "Doe",
|
|
143
156
|
date_of_birth: "1990-06-15",
|
|
@@ -181,7 +194,7 @@ await sdk.auth.verifyEmail({
|
|
|
181
194
|
```
|
|
182
195
|
|
|
183
196
|
```ts
|
|
184
|
-
// Login — access token is extracted from the response and stored on
|
|
197
|
+
// Login — access token is extracted from the response and stored on the SDK instance
|
|
185
198
|
const authResponse = await sdk.auth.login({
|
|
186
199
|
email: "patient@example.com",
|
|
187
200
|
password: "SecurePassword123!",
|
|
@@ -192,7 +205,7 @@ const authResponse = await sdk.auth.login({
|
|
|
192
205
|
{ "access_token": "eyJhbGci...", "id_token": "eyJhbGci...", "expires_in": 3600 }
|
|
193
206
|
```
|
|
194
207
|
|
|
195
|
-
|
|
208
|
+
`login()` reads `access_token` off the response body and throws `SDKError` if it's missing.
|
|
196
209
|
|
|
197
210
|
---
|
|
198
211
|
|
|
@@ -201,19 +214,41 @@ The token extractor looks for `token`, `access_token`, `accessToken`, `idToken`
|
|
|
201
214
|
### Profile, phone, address, race, demographics
|
|
202
215
|
|
|
203
216
|
```ts
|
|
204
|
-
// Get profile — full FHIR R4 Patient resource
|
|
205
217
|
const profile = await sdk.patient.getProfile("patient-id");
|
|
206
218
|
```
|
|
207
219
|
|
|
208
220
|
```json
|
|
209
221
|
{
|
|
210
|
-
"
|
|
211
|
-
"
|
|
212
|
-
"
|
|
213
|
-
"
|
|
214
|
-
"
|
|
215
|
-
"
|
|
216
|
-
"
|
|
222
|
+
"patient_id": "patient-id",
|
|
223
|
+
"fhir_id": "uuid",
|
|
224
|
+
"mrn": "MRN-XXXXXXXX",
|
|
225
|
+
"name": { "use": "official", "first_name": "Jane", "last_name": "Doe" },
|
|
226
|
+
"date_of_birth": "1990-06-15",
|
|
227
|
+
"gender": "unknown",
|
|
228
|
+
"sex_at_birth": "female",
|
|
229
|
+
"preferred_language": "en",
|
|
230
|
+
"communications": [{ "language": "en", "preferred": true }],
|
|
231
|
+
"email": "patient@example.com",
|
|
232
|
+
"active": true,
|
|
233
|
+
"created_by": "field-agent-fhir-id",
|
|
234
|
+
"created_date": "2026-06-24T04:54:17Z"
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
// Dashboard snapshot
|
|
240
|
+
const dashboard = await sdk.patient.getDashboard("patient-id");
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"patient_id": "uuid",
|
|
246
|
+
"summary": {},
|
|
247
|
+
"recent_encounters": [],
|
|
248
|
+
"active_medications": [],
|
|
249
|
+
"upcoming_appointments": [],
|
|
250
|
+
"latest_vitals": null,
|
|
251
|
+
"alerts": []
|
|
217
252
|
}
|
|
218
253
|
```
|
|
219
254
|
|
|
@@ -250,10 +285,8 @@ await sdk.patient.updateAddress("patient-id", {
|
|
|
250
285
|
```
|
|
251
286
|
|
|
252
287
|
```ts
|
|
253
|
-
// Update race
|
|
254
|
-
|
|
255
|
-
// other, unknown, declined_to_specify)
|
|
256
|
-
await sdk.patient.updateRace("patient-id", { races: ["white", "asian"] });
|
|
288
|
+
// Update race
|
|
289
|
+
await sdk.patient.updateRace("patient-id", { races: ["white"] });
|
|
257
290
|
```
|
|
258
291
|
|
|
259
292
|
```json
|
|
@@ -333,19 +366,7 @@ await sdk.patient.scanIdentityDocument("patient-id", {
|
|
|
333
366
|
"last_name": "DOE",
|
|
334
367
|
"date_of_birth": "06/15/1990",
|
|
335
368
|
"document_number": "D1234567",
|
|
336
|
-
"
|
|
337
|
-
"issuing_country": "UNITED STATES",
|
|
338
|
-
"document_type": "DRIVER LICENSE",
|
|
339
|
-
"verified": true,
|
|
340
|
-
"demographics_match": { "name": true, "date_of_birth": true },
|
|
341
|
-
"raw_fields": {
|
|
342
|
-
"FIRST_NAME": "JANE",
|
|
343
|
-
"LAST_NAME": "DOE",
|
|
344
|
-
"DATE_OF_BIRTH": "06/15/1990",
|
|
345
|
-
"DOCUMENT_NUMBER": "D1234567",
|
|
346
|
-
"EXPIRATION_DATE": "06/15/2030",
|
|
347
|
-
"ID_TYPE": "DRIVER LICENSE"
|
|
348
|
-
}
|
|
369
|
+
"verified": true
|
|
349
370
|
}
|
|
350
371
|
```
|
|
351
372
|
|
|
@@ -374,43 +395,57 @@ await sdk.patient.checkInsuranceEligibility({
|
|
|
374
395
|
});
|
|
375
396
|
```
|
|
376
397
|
|
|
377
|
-
Stedi EDI 270/271 eligibility
|
|
398
|
+
Pure passthrough to Stedi's EDI 270/271 eligibility service — HealthCloud
|
|
399
|
+
relays Stedi's response (or Stedi's own `400` for an unrecognized
|
|
400
|
+
payer/member) verbatim. There's no fixed HealthCloud schema for this
|
|
401
|
+
response, so it's typed as `InsuranceEligibilityResponse` (`JsonValue`).
|
|
378
402
|
|
|
379
403
|
### Medications
|
|
380
404
|
|
|
381
|
-
Required fields: `name`, `route`, `dosage.value`, `dosage.unit`, `dosage.frequency`.
|
|
405
|
+
Required fields: `name`, `route`, `dosage.value`, `dosage.unit`, `dosage.frequency`, `status`.
|
|
406
|
+
`dosage.frequency` (`MedicationFrequency`): `once, once_daily, twice_daily,
|
|
407
|
+
three_times_daily, four_times_daily, every_4_hours, every_6_hours,
|
|
408
|
+
every_8_hours, every_12_hours, every_48_hours, weekly, biweekly, monthly,
|
|
409
|
+
as_needed, other`.
|
|
382
410
|
|
|
383
411
|
```ts
|
|
384
412
|
await sdk.patient.createMedication("patient-id", {
|
|
385
|
-
name: "
|
|
386
|
-
rxnorm_code: "29046",
|
|
413
|
+
name: "Amoxicillin",
|
|
387
414
|
route: "oral",
|
|
388
|
-
dosage: { value:
|
|
415
|
+
dosage: { value: 500, unit: "mg", frequency: "twice_daily" },
|
|
389
416
|
status: "active",
|
|
390
|
-
intent: "order",
|
|
391
|
-
prescriber_name: "Dr. Sarah Smith",
|
|
392
417
|
});
|
|
393
418
|
```
|
|
394
419
|
|
|
395
420
|
```json
|
|
396
|
-
{
|
|
421
|
+
{
|
|
422
|
+
"medication_id": "med-id",
|
|
423
|
+
"fhir_id": "med-uuid",
|
|
424
|
+
"resource_type": "MedicationRequest",
|
|
425
|
+
"name": "Amoxicillin",
|
|
426
|
+
"route": "oral",
|
|
427
|
+
"dosage": { "value": 500.0, "unit": "mg", "frequency": "twice_daily" },
|
|
428
|
+
"status": "active",
|
|
429
|
+
"intent": "order"
|
|
430
|
+
}
|
|
397
431
|
```
|
|
398
432
|
|
|
399
433
|
```ts
|
|
400
434
|
const meds = await sdk.patient.listMedications("patient-id");
|
|
435
|
+
// optional: { resource_type: "MedicationRequest" | "MedicationStatement" }
|
|
401
436
|
```
|
|
402
437
|
|
|
403
438
|
```json
|
|
404
|
-
{ "medications": [
|
|
439
|
+
{ "medications": [ /* MedicationResponse[] */ ], "total": 3 }
|
|
405
440
|
```
|
|
406
441
|
|
|
407
442
|
```ts
|
|
408
443
|
const med = await sdk.patient.getMedication("patient-id", "med-id");
|
|
409
|
-
// → a single
|
|
444
|
+
// → a single MedicationResponse
|
|
410
445
|
|
|
411
446
|
await sdk.patient.updateMedicationStatus("patient-id", "med-id", {
|
|
412
|
-
status: "
|
|
413
|
-
|
|
447
|
+
status: "completed",
|
|
448
|
+
notes: "course finished",
|
|
414
449
|
});
|
|
415
450
|
```
|
|
416
451
|
|
|
@@ -435,31 +470,49 @@ const locations = await sdk.patient.listNearestLocations({
|
|
|
435
470
|
{
|
|
436
471
|
"locations": [
|
|
437
472
|
{
|
|
438
|
-
"place_id": "
|
|
439
|
-
"name": "
|
|
440
|
-
"vicinity": "
|
|
441
|
-
"types": ["
|
|
442
|
-
"geometry": { "location": { "lat":
|
|
443
|
-
"rating": 4.
|
|
444
|
-
"open_now": true
|
|
473
|
+
"place_id": "hc_static_001",
|
|
474
|
+
"name": "HealthCloud Primary Care Clinic",
|
|
475
|
+
"vicinity": "123 Medical Center Drive",
|
|
476
|
+
"types": ["health", "point_of_interest"],
|
|
477
|
+
"geometry": { "location": { "lat": 30.27, "lng": -97.74 } },
|
|
478
|
+
"rating": 4.5,
|
|
479
|
+
"open_now": true,
|
|
480
|
+
"phone": "+1-800-555-0100",
|
|
481
|
+
"distance_km": 1.2
|
|
445
482
|
}
|
|
446
483
|
],
|
|
447
|
-
"total":
|
|
448
|
-
"radius_km": 10,
|
|
449
|
-
"source": "
|
|
484
|
+
"total": 3,
|
|
485
|
+
"radius_km": 10.0,
|
|
486
|
+
"source": "hardcoded",
|
|
487
|
+
"note": "Set GOOGLE_PLACES_API_KEY to enable live results"
|
|
450
488
|
}
|
|
451
489
|
```
|
|
452
490
|
|
|
453
|
-
`source` is `"hardcoded"`
|
|
491
|
+
`source` is `"hardcoded"` (curated fallback data) until `GOOGLE_PLACES_API_KEY` is configured; once it is, `source` becomes `"google_places"`.
|
|
454
492
|
|
|
455
493
|
### Encounters
|
|
456
494
|
|
|
457
495
|
```ts
|
|
458
|
-
await sdk.patient.createEncounter({
|
|
496
|
+
await sdk.patient.createEncounter({
|
|
497
|
+
patient_id: "patient-id",
|
|
498
|
+
status: "in-progress",
|
|
499
|
+
encounter_class: "AMB",
|
|
500
|
+
});
|
|
459
501
|
```
|
|
460
502
|
|
|
461
503
|
```json
|
|
462
|
-
{
|
|
504
|
+
{
|
|
505
|
+
"encounter_id": "id",
|
|
506
|
+
"fhir_id": "encounter-uuid",
|
|
507
|
+
"status": "in-progress",
|
|
508
|
+
"encounter_class": "AMB",
|
|
509
|
+
"patient_id": "patient-uuid",
|
|
510
|
+
"participants": [],
|
|
511
|
+
"diagnoses": [],
|
|
512
|
+
"locations": [],
|
|
513
|
+
"created_by": "self",
|
|
514
|
+
"created_date": "2026-06-24T04:54:27Z"
|
|
515
|
+
}
|
|
463
516
|
```
|
|
464
517
|
|
|
465
518
|
```ts
|
|
@@ -467,15 +520,19 @@ const encounters = await sdk.patient.listEncounters({ patient_id: "patient-id" }
|
|
|
467
520
|
const encounter = await sdk.patient.getEncounter("encounter-id");
|
|
468
521
|
```
|
|
469
522
|
|
|
470
|
-
> Use `fhir_id` from the create response (not `
|
|
523
|
+
> Use `fhir_id` from the create response (not `encounter_id`) as the `encounter-id` passed to `getEncounter`/`vitals.record`'s `encounter_id` — that's the actual FHIR resource identifier. `status` and `encounter_class` are typed as plain `string` rather than a fixed enum.
|
|
471
524
|
|
|
472
525
|
### Questionnaires
|
|
473
526
|
|
|
474
527
|
```ts
|
|
475
528
|
await sdk.patient.createQuestionnaire({
|
|
476
|
-
name: "
|
|
477
|
-
title: "
|
|
478
|
-
|
|
529
|
+
name: "health-intake",
|
|
530
|
+
title: "Health Intake",
|
|
531
|
+
status: "active",
|
|
532
|
+
items: [
|
|
533
|
+
{ link_id: "q1", text: "Allergies?", type: "boolean" },
|
|
534
|
+
{ link_id: "q2", text: "Meds?", type: "string" },
|
|
535
|
+
],
|
|
479
536
|
});
|
|
480
537
|
```
|
|
481
538
|
|
|
@@ -486,10 +543,19 @@ await sdk.patient.createQuestionnaire({
|
|
|
486
543
|
```ts
|
|
487
544
|
await sdk.patient.createQuestionnaireResponse("questionnaire-id", {
|
|
488
545
|
patient_id: "patient-id",
|
|
489
|
-
|
|
546
|
+
encounter_id: "encounter-id",
|
|
547
|
+
status: "completed",
|
|
548
|
+
items: [
|
|
549
|
+
{ link_id: "q1", answers: [{ value_boolean: false }] },
|
|
550
|
+
{ link_id: "q2", answers: [{ value_string: "None" }] },
|
|
551
|
+
],
|
|
490
552
|
});
|
|
491
553
|
```
|
|
492
554
|
|
|
555
|
+
```json
|
|
556
|
+
{ "fhir_id": "questionnaire-response-uuid" }
|
|
557
|
+
```
|
|
558
|
+
|
|
493
559
|
---
|
|
494
560
|
|
|
495
561
|
## Assistant API (`/assistant/*`, public except knowledge/actions)
|
|
@@ -499,8 +565,7 @@ await sdk.patient.createQuestionnaireResponse("questionnaire-id", {
|
|
|
499
565
|
knowledge/action routes below them use the normal bearer-token auth.
|
|
500
566
|
|
|
501
567
|
```ts
|
|
502
|
-
// Voice command classification
|
|
503
|
-
// full action catalog from listAssistantActions() automatically
|
|
568
|
+
// Voice command classification
|
|
504
569
|
const { Action } = await sdk.patient.classifyVoiceCommand({
|
|
505
570
|
text: "start the test for this patient",
|
|
506
571
|
});
|
|
@@ -513,11 +578,11 @@ const { Action } = await sdk.patient.classifyVoiceCommand({
|
|
|
513
578
|
When nothing in the catalog matches: `{ "Action": "" }` — there is no HTTP error case for this route.
|
|
514
579
|
|
|
515
580
|
`image` must be a **full data URI** (`data:image/jpeg;base64,...`), 1–16,000,000 chars
|
|
516
|
-
— a bare base64 string is rejected. **Use a JPEG data URI, not PNG**:
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
failure"
|
|
520
|
-
real `ocr_result`.
|
|
581
|
+
— a bare base64 string is rejected. **Use a JPEG data URI, not PNG**: the
|
|
582
|
+
identical image submitted as `data:image/png;base64,...` silently returns
|
|
583
|
+
`{ "type": "ocr_error", "ok": false, "error": "" }` (an empty-`error` "soft
|
|
584
|
+
failure", not an HTTP error), while the same bytes re-encoded as JPEG return a
|
|
585
|
+
real `ocr_result`.
|
|
521
586
|
|
|
522
587
|
```ts
|
|
523
588
|
// ID document OCR via vision LLM — pass a full data: URI, not bare base64
|
|
@@ -650,7 +715,7 @@ const result = await sdk.patient.compareFacesByUrl({
|
|
|
650
715
|
}
|
|
651
716
|
```
|
|
652
717
|
|
|
653
|
-
A `500` with `{"error": "<detail>"}` is the
|
|
718
|
+
A `500` with `{"error": "<detail>"}` is the expected outcome when `imageUrl1` has no detectable face (Rekognition `InvalidParameterException`).
|
|
654
719
|
|
|
655
720
|
---
|
|
656
721
|
|
|
@@ -792,12 +857,12 @@ await sdk.patient.mintRtcToken({ channelName: "case-123", uid: "c-self" });
|
|
|
792
857
|
```
|
|
793
858
|
|
|
794
859
|
```json
|
|
795
|
-
//
|
|
860
|
+
// While Agora credentials aren't provisioned — 503
|
|
796
861
|
{ "error": "Live calling is not configured", "configured": false }
|
|
797
862
|
```
|
|
798
863
|
|
|
799
864
|
```json
|
|
800
|
-
//
|
|
865
|
+
// Once Agora credentials are provisioned — 200
|
|
801
866
|
{
|
|
802
867
|
"appId": "...",
|
|
803
868
|
"channelName": "case-123",
|
|
@@ -809,36 +874,49 @@ await sdk.patient.mintRtcToken({ channelName: "case-123", uid: "c-self" });
|
|
|
809
874
|
}
|
|
810
875
|
```
|
|
811
876
|
|
|
812
|
-
Treat the `503` as expected, not a bug, and fall back to a mock/offline call UI.
|
|
877
|
+
Treat the `503` as expected, not a bug, and fall back to a mock/offline call UI until Agora is configured for the tenant.
|
|
813
878
|
|
|
814
879
|
---
|
|
815
880
|
|
|
816
881
|
## Vitals
|
|
817
882
|
|
|
818
883
|
```ts
|
|
819
|
-
// Record vitals
|
|
884
|
+
// Record vitals — all fields optional; blood pressure requires both
|
|
885
|
+
// systolic and diastolic together (or neither). BMI is auto-derived from
|
|
886
|
+
// weight + height.
|
|
820
887
|
await sdk.vitals.record("patient-id", {
|
|
888
|
+
temperature: 36.6,
|
|
889
|
+
weight_kg: 70.5,
|
|
890
|
+
height_cm: 175.0,
|
|
821
891
|
heart_rate: 72,
|
|
822
|
-
temperature: 98.6,
|
|
823
892
|
systolic: 120,
|
|
824
893
|
diastolic: 80,
|
|
825
|
-
oxygen_saturation:
|
|
826
|
-
weight_kg: 70,
|
|
827
|
-
height_cm: 175,
|
|
894
|
+
oxygen_saturation: 98,
|
|
828
895
|
});
|
|
829
896
|
```
|
|
830
897
|
|
|
831
|
-
|
|
898
|
+
```json
|
|
899
|
+
{ "observations": 7, "patient_id": "patient-uuid" }
|
|
900
|
+
```
|
|
832
901
|
|
|
833
902
|
```ts
|
|
834
|
-
// List vitals
|
|
835
|
-
const vitals = await sdk.vitals.list("patient-id"
|
|
836
|
-
from: "2026-01-01",
|
|
837
|
-
to: "2026-06-16",
|
|
838
|
-
});
|
|
903
|
+
// List vitals — optional ?type=<LOINC code> to filter to one vital sign
|
|
904
|
+
const vitals = await sdk.vitals.list("patient-id");
|
|
839
905
|
```
|
|
840
906
|
|
|
841
|
-
|
|
907
|
+
```json
|
|
908
|
+
{
|
|
909
|
+
"vitals_id": "vitals-uuid",
|
|
910
|
+
"patient_id": "patient-uuid",
|
|
911
|
+
"blood_pressure": { "systolic": 120.0, "diastolic": 80.0 },
|
|
912
|
+
"heart_rate": { "rate": 72.0 },
|
|
913
|
+
"temperature": { "value": 36.6, "route": "oral" },
|
|
914
|
+
"weight": { "value": 70.5, "clothed": false },
|
|
915
|
+
"height": { "value": 175.0 },
|
|
916
|
+
"pulse_oximetry": { "spo2": 98.0, "on_supplemental_oxygen": false },
|
|
917
|
+
"status": "final"
|
|
918
|
+
}
|
|
919
|
+
```
|
|
842
920
|
|
|
843
921
|
---
|
|
844
922
|
|
|
@@ -846,38 +924,186 @@ Array/list of recorded vitals entries for the date range.
|
|
|
846
924
|
|
|
847
925
|
```ts
|
|
848
926
|
// Create rapid test result
|
|
849
|
-
// NOTE: three corrections vs the HealthCloud API reference doc, all confirmed
|
|
850
|
-
// against the live dev deployment:
|
|
851
|
-
// 1. path is /patients/{id}/diagnostics/rapid-tests (doc says /rapid-test, 404s)
|
|
852
|
-
// 2. field is `type`, not `test_type` (doc's name 400s with "KeyError: 'type'")
|
|
853
|
-
// 3. `type` is validated against a server-side RapidTestType enum — the doc's
|
|
854
|
-
// own example "COVID-19" 400s as invalid. `influenza_a` is confirmed valid;
|
|
855
|
-
// the full enum isn't published, so verify any other value against dev first.
|
|
856
927
|
await sdk.diagnostics.createRapidTest("patient-id", {
|
|
857
|
-
type: "
|
|
928
|
+
type: "covid19",
|
|
858
929
|
result: "negative",
|
|
859
|
-
|
|
860
|
-
administered_date: "2026-06-16",
|
|
930
|
+
encounter_id: "encounter-id",
|
|
861
931
|
});
|
|
862
932
|
```
|
|
863
933
|
|
|
864
|
-
|
|
934
|
+
```json
|
|
935
|
+
{
|
|
936
|
+
"test_id": "id",
|
|
937
|
+
"fhir_id": "test-uuid",
|
|
938
|
+
"type": "covid19",
|
|
939
|
+
"result": "negative",
|
|
940
|
+
"status": "final",
|
|
941
|
+
"specimen_type": "nasopharyngeal_swab",
|
|
942
|
+
"encounter_id": "encounter-uuid"
|
|
943
|
+
}
|
|
944
|
+
```
|
|
945
|
+
|
|
946
|
+
`type` (`RapidTestType`): `covid19, influenza_a, influenza_b, rsv, strep, hiv,
|
|
947
|
+
pregnancy, mono, uti_dipstick, blood_glucose, other`.
|
|
948
|
+
`result` (`RapidTestResult`): `positive, negative, invalid, inconclusive,
|
|
949
|
+
not_detected, detected`.
|
|
950
|
+
|
|
951
|
+
```ts
|
|
952
|
+
const tests = await sdk.diagnostics.list("patient-id");
|
|
953
|
+
```
|
|
954
|
+
|
|
955
|
+
```json
|
|
956
|
+
{
|
|
957
|
+
"observations": [
|
|
958
|
+
{ "observation_id": "uuid", "loinc_code": "97097-0", "display": "SARS-CoV-2 (COVID-19) Ag [Presence] ...", "status": "final" }
|
|
959
|
+
],
|
|
960
|
+
"total": 1
|
|
961
|
+
}
|
|
962
|
+
```
|
|
963
|
+
|
|
964
|
+
---
|
|
965
|
+
|
|
966
|
+
## Field Agent API (`sdk.fieldAgent`, host: `*-api-fieldagent.health.cloud`)
|
|
967
|
+
|
|
968
|
+
A separate identity/host from the Patient API — field agents register, log
|
|
969
|
+
in, and act on a different bearer token than patients.
|
|
865
970
|
|
|
866
971
|
```ts
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
972
|
+
const registration = await sdk.fieldAgent.register({
|
|
973
|
+
first_name: "Field",
|
|
974
|
+
last_name: "Agent",
|
|
975
|
+
email: "agent@example.com",
|
|
976
|
+
password: "Agent@2025!",
|
|
977
|
+
badge_number: "FA-001",
|
|
978
|
+
department: "QA",
|
|
871
979
|
});
|
|
872
980
|
```
|
|
873
981
|
|
|
874
|
-
|
|
982
|
+
```json
|
|
983
|
+
{
|
|
984
|
+
"cognito_sub": "uuid",
|
|
985
|
+
"email_otp_sent": false,
|
|
986
|
+
"email_verified": true,
|
|
987
|
+
"access_token": "eyJ...",
|
|
988
|
+
"id_token": "eyJ...",
|
|
989
|
+
"expires_in": 3600
|
|
990
|
+
}
|
|
991
|
+
```
|
|
992
|
+
|
|
993
|
+
```ts
|
|
994
|
+
// Login — stores the token on this SDK instance (overwrites sdk.auth's token
|
|
995
|
+
// if both were used; see the note in Service groups above)
|
|
996
|
+
await sdk.fieldAgent.login({ email: "agent@example.com", password: "Agent@2025!" });
|
|
997
|
+
|
|
998
|
+
// Reset password
|
|
999
|
+
await sdk.fieldAgent.resetPassword({ email: "agent@example.com" });
|
|
1000
|
+
```
|
|
1001
|
+
|
|
1002
|
+
```json
|
|
1003
|
+
{ "reset_initiated": true, "message": "A reset code has been sent to your email." }
|
|
1004
|
+
```
|
|
1005
|
+
|
|
1006
|
+
```ts
|
|
1007
|
+
// Profile (self) — fhir_person_id is what you pass as `created_by` when this
|
|
1008
|
+
// agent registers a patient via sdk.auth.register()
|
|
1009
|
+
const agent = await sdk.fieldAgent.getAgent(cognitoSub);
|
|
1010
|
+
```
|
|
1011
|
+
|
|
1012
|
+
```json
|
|
1013
|
+
{
|
|
1014
|
+
"agent_id": "sub", "fhir_person_id": "uuid", "cognito_sub": "sub",
|
|
1015
|
+
"tenant_id": "cdcprotect", "email": "agent@example.com",
|
|
1016
|
+
"first_name": "Field", "last_name": "Agent", "title": null, "phone": null,
|
|
1017
|
+
"badge_number": "FA-001", "license_number": null, "department": "QA",
|
|
1018
|
+
"organization": null, "address_street1": null, "address_state": null,
|
|
1019
|
+
"status": "active"
|
|
1020
|
+
}
|
|
1021
|
+
```
|
|
1022
|
+
|
|
1023
|
+
```ts
|
|
1024
|
+
await sdk.fieldAgent.updateAgent(cognitoSub, { title: "Senior Agent", phone: "+15551230000" });
|
|
1025
|
+
|
|
1026
|
+
const dashboard = await sdk.fieldAgent.getDashboard(cognitoSub); // optional ?date=YYYY-MM-DD
|
|
1027
|
+
```
|
|
1028
|
+
|
|
1029
|
+
```json
|
|
1030
|
+
{
|
|
1031
|
+
"agent_id": "sub", "date": "2026-06-24",
|
|
1032
|
+
"counts": { "patients": 18, "tests": 17, "test_results": 0 },
|
|
1033
|
+
"assigned_patients": [], "recent_encounters": [], "pending_tasks": [], "alerts": [],
|
|
1034
|
+
"summary": { "patients": 18, "tests": 17, "test_results": 0 }
|
|
1035
|
+
}
|
|
1036
|
+
```
|
|
1037
|
+
|
|
1038
|
+
```ts
|
|
1039
|
+
// Photo — same upload-url / upload / fetch flow as patient.uploadPhoto
|
|
1040
|
+
const uploadUrl = await sdk.fieldAgent.getPhotoUploadUrl(cognitoSub);
|
|
1041
|
+
await sdk.fieldAgent.uploadPhoto(cognitoSub, { data: "base64-png", content_type: "image/png" });
|
|
1042
|
+
const photo = await sdk.fieldAgent.getPhoto(cognitoSub, { binary_id: "uuid" });
|
|
1043
|
+
|
|
1044
|
+
// Patients/encounters created by this agent
|
|
1045
|
+
const patients = await sdk.fieldAgent.listPatients({ created_by: agent.fhir_person_id, limit: 20 });
|
|
1046
|
+
const encounters = await sdk.fieldAgent.listEncounters({ limit: 20 });
|
|
1047
|
+
```
|
|
1048
|
+
|
|
1049
|
+
---
|
|
1050
|
+
|
|
1051
|
+
## MCP API (`sdk.mcp`, host: `*-api-mcp.health.cloud`)
|
|
1052
|
+
|
|
1053
|
+
JSON-RPC 2.0 proxy. `sdk.mcp.patient(...)` forwards to the 14 Patient API
|
|
1054
|
+
tools, `sdk.mcp.fieldAgent(...)` forwards to the 8 Field Agent API tools —
|
|
1055
|
+
both using whichever bearer token is currently set on this SDK instance.
|
|
1056
|
+
There's no per-tool wrapper method: you build the JSON-RPC envelope yourself
|
|
1057
|
+
and pick the result type per call, since one envelope shape carries different
|
|
1058
|
+
results depending on `method`.
|
|
1059
|
+
|
|
1060
|
+
```ts
|
|
1061
|
+
import type { McpInitializeResult, McpToolCallResult } from "@healthcloudai/hc-sdk";
|
|
1062
|
+
|
|
1063
|
+
const handshake = await sdk.mcp.patient<Record<string, never>, McpInitializeResult>({
|
|
1064
|
+
jsonrpc: "2.0",
|
|
1065
|
+
id: 1,
|
|
1066
|
+
method: "initialize",
|
|
1067
|
+
params: {},
|
|
1068
|
+
});
|
|
1069
|
+
```
|
|
1070
|
+
|
|
1071
|
+
```json
|
|
1072
|
+
{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2024-11-05", "serverInfo": { "name": "HC Patient MCP", "version": "1.0.0" } } }
|
|
1073
|
+
```
|
|
1074
|
+
|
|
1075
|
+
```ts
|
|
1076
|
+
const result = await sdk.mcp.patient<{ name: string; arguments: Record<string, unknown> }, McpToolCallResult>({
|
|
1077
|
+
jsonrpc: "2.0",
|
|
1078
|
+
id: 3,
|
|
1079
|
+
method: "tools/call",
|
|
1080
|
+
params: { name: "get_patient", arguments: { patient_id: fhirPatientId } },
|
|
1081
|
+
});
|
|
1082
|
+
```
|
|
1083
|
+
|
|
1084
|
+
```json
|
|
1085
|
+
{ "jsonrpc": "2.0", "id": 3, "result": { "content": [{ "type": "text", "text": "..." }], "isError": false } }
|
|
1086
|
+
```
|
|
1087
|
+
|
|
1088
|
+
Patient tools: `get_patient, get_patient_dashboard, update_demographics,
|
|
1089
|
+
update_address, list_encounters, create_encounter, get_encounter,
|
|
1090
|
+
list_medications, create_medication, add_insurance,
|
|
1091
|
+
check_insurance_eligibility, find_nearest_locations, ask_assistant,
|
|
1092
|
+
classify_voice_command` (`McpPatientToolName`).
|
|
1093
|
+
|
|
1094
|
+
Field-agent tools (via `sdk.mcp.fieldAgent(...)`): `get_agent,
|
|
1095
|
+
get_agent_dashboard, update_agent, list_patients, list_encounters,
|
|
1096
|
+
get_agent_photo_upload_url, upload_agent_photo, get_agent_photo`
|
|
1097
|
+
(`McpFieldAgentToolName`).
|
|
1098
|
+
|
|
1099
|
+
There's no published `tools/list` result schema, so `McpListToolsResult` is
|
|
1100
|
+
`JsonValue`.
|
|
875
1101
|
|
|
876
1102
|
---
|
|
877
1103
|
|
|
878
1104
|
## Connectivity and service stubs
|
|
879
1105
|
|
|
880
|
-
Every
|
|
1106
|
+
Every service exposes `GET /connect` for Lambda warm-up / connectivity checks. The SDK exposes that as an unauthenticated `connect()` method:
|
|
881
1107
|
|
|
882
1108
|
```ts
|
|
883
1109
|
await sdk.patient.connect();
|
|
@@ -889,6 +1115,8 @@ await sdk.appointments.connect();
|
|
|
889
1115
|
await sdk.rppg.connect();
|
|
890
1116
|
await sdk.session.connect();
|
|
891
1117
|
await sdk.telehealth.connect();
|
|
1118
|
+
await sdk.fieldAgent.connect();
|
|
1119
|
+
await sdk.mcp.connect();
|
|
892
1120
|
```
|
|
893
1121
|
|
|
894
1122
|
```json
|
|
@@ -899,9 +1127,13 @@ await sdk.telehealth.connect();
|
|
|
899
1127
|
{ "status": "connected", "service": "provider-api" }
|
|
900
1128
|
```
|
|
901
1129
|
|
|
902
|
-
|
|
1130
|
+
Every `connect()` method returns the same `ConnectResponse` type
|
|
1131
|
+
(`{ status: "connected"; service: string; environment?: Environment }`) — the
|
|
1132
|
+
one truly universal response shape across the whole SDK. `environment` is
|
|
1133
|
+
present only on patient/vitals/diagnostics `connect()` responses — don't
|
|
1134
|
+
branch on its presence, just check `status: "connected"`.
|
|
903
1135
|
|
|
904
|
-
Provider, EHR, Appointments, rPPG, Session, and Telehealth currently
|
|
1136
|
+
Provider, EHR, Appointments, rPPG, Session, and Telehealth currently only have `GET /connect` implemented, so each group also keeps a low-level escape hatch for early integration ahead of typed SDK methods:
|
|
905
1137
|
|
|
906
1138
|
```ts
|
|
907
1139
|
// Low-level escape hatch - available on all service groups
|
|
@@ -912,7 +1144,7 @@ await sdk.session.request("POST", "/sessions");
|
|
|
912
1144
|
await sdk.telehealth.request("POST", "/consultations");
|
|
913
1145
|
```
|
|
914
1146
|
|
|
915
|
-
Domain typed methods will be added
|
|
1147
|
+
Domain typed methods will be added as those services grow domain paths.
|
|
916
1148
|
|
|
917
1149
|
---
|
|
918
1150
|
|
|
@@ -952,18 +1184,18 @@ try {
|
|
|
952
1184
|
```tsx
|
|
953
1185
|
import React, { useEffect, useState } from "react";
|
|
954
1186
|
import { View, Text, ActivityIndicator } from "react-native";
|
|
955
|
-
import { HCSDK, SDKError } from "@healthcloudai/hc-sdk";
|
|
1187
|
+
import { HCSDK, SDKError, type PatientResponse } from "@healthcloudai/hc-sdk";
|
|
956
1188
|
|
|
957
1189
|
const sdk = new HCSDK({ environment: "dev", tenantId: "eclinicapi" });
|
|
958
1190
|
|
|
959
1191
|
export function usePatientProfile(patientId: string) {
|
|
960
|
-
const [data, setData] = useState<
|
|
1192
|
+
const [data, setData] = useState<PatientResponse | null>(null);
|
|
961
1193
|
const [loading, setLoading] = useState(true);
|
|
962
1194
|
const [error, setError] = useState<SDKError | null>(null);
|
|
963
1195
|
|
|
964
1196
|
useEffect(() => {
|
|
965
1197
|
sdk.patient.getProfile(patientId)
|
|
966
|
-
.then(
|
|
1198
|
+
.then(setData)
|
|
967
1199
|
.catch((err: unknown) => {
|
|
968
1200
|
if (err instanceof SDKError) setError(err);
|
|
969
1201
|
})
|
|
@@ -983,49 +1215,6 @@ export function PatientProfile({ patientId }: { patientId: string }) {
|
|
|
983
1215
|
|
|
984
1216
|
---
|
|
985
1217
|
|
|
986
|
-
## Swagger operation coverage matrix
|
|
987
|
-
|
|
988
|
-
Verified against live swagger specs on 2026-06-17.
|
|
989
|
-
|
|
990
|
-
| Service | Swagger host | Paths | Ops in swagger | Implemented | Missing | Extra | Status |
|
|
991
|
-
|---|---|---:|---:|---:|---|---|---|
|
|
992
|
-
| Patient (auth) | dev-api-patient.health.cloud | 51 | 46 | 46 | — | — | COMPLETE |
|
|
993
|
-
| Vitals | dev-api-vitals.health.cloud | 2 | 3 | 3 | — | — | COMPLETE |
|
|
994
|
-
| Diagnostics | dev-api-diagnostics.health.cloud | 3 | 3 | 3 | — | — | COMPLETE |
|
|
995
|
-
| Provider | dev-api-provider.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
996
|
-
| EHR | dev-api-ehr.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
997
|
-
| Appointments | dev-api-appointments.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
998
|
-
| rPPG | dev-api-rppg.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
999
|
-
| Session | dev-api-session.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
1000
|
-
| Telehealth | dev-api-telehealth.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
1001
|
-
| **Total** | | **62** | **58** | **58** | | | |
|
|
1002
|
-
|
|
1003
|
-
> Swaggers do not publish request/response schemas. Request models are now aligned against
|
|
1004
|
-
> `health_cloud_api.md` (the live API reference) rather than guessed from integration
|
|
1005
|
-
> examples. Response models extend `Record<string, unknown>`.
|
|
1006
|
-
|
|
1007
|
-
---
|
|
1008
|
-
|
|
1009
|
-
## Running tests
|
|
1010
|
-
|
|
1011
|
-
```bash
|
|
1012
|
-
npm test --workspace @healthcloudai/hc-sdk
|
|
1013
|
-
```
|
|
1014
|
-
|
|
1015
|
-
Package tests use injected fake `fetch`; no real network connections are made. They assert on concrete URLs, HTTP methods, headers, request bodies, error shapes, and `SDKError` prototype correctness.
|
|
1016
|
-
|
|
1017
|
-
Live integration test from the repository root:
|
|
1018
|
-
|
|
1019
|
-
```powershell
|
|
1020
|
-
$env:HC_TENANT_ID="elevancehealth"
|
|
1021
|
-
$env:HC_PASSWORD="Secure@2025!"
|
|
1022
|
-
npm run test:hc-sdk --prefix integration-tests
|
|
1023
|
-
```
|
|
1024
|
-
|
|
1025
|
-
The live integration test has no framework-level skips. It registers a fresh user first, then logs in with that same user. Set `HC_REGISTER_EMAIL` only if you need a fixed registration email; otherwise a unique `@yopmail.com` address is generated for each run. Set `HC_PATIENT_ID`, `HC_FHIR_PATIENT_ID`, or `HC_BINARY_ID` only when the backend does not return those identifiers during the flow.
|
|
1026
|
-
|
|
1027
|
-
---
|
|
1028
|
-
|
|
1029
1218
|
## Build
|
|
1030
1219
|
|
|
1031
1220
|
```bash
|