@healthcloudai/hc-sdk 0.3.0 → 0.4.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
@@ -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
- > **Swagger verification date:** 2026-06-17. All paths and operation counts below were confirmed against live swagger endpoints.
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`: `registration.access_token` is already usable — no separate login call is needed. `uat`/`prod`: `email_otp_sent` is `true` and tokens are omitted; call `verifyEmail` then `login`.
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)
@@ -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
  ---
@@ -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 sdk.state
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
- The token extractor looks for `token`, `access_token`, `accessToken`, `idToken` at the top level, and also inside a nested `data` or `result` object.
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
- "resourceType": "Patient",
211
- "id": "patient-id",
212
- "name": [{ "given": ["Jane"], "family": "Doe" }],
213
- "birthDate": "1990-06-15",
214
- "gender": "female",
215
- "address": [],
216
- "telecom": []
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 (valid values: white, black_or_african_american, asian,
254
- // american_indian_or_alaska_native, native_hawaiian_or_other_pacific_islander,
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
- "expiry_date": "06/15/2030",
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 response — shape varies by payer.
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: "Lisinopril",
386
- rxnorm_code: "29046",
413
+ name: "Amoxicillin",
387
414
  route: "oral",
388
- dosage: { value: 10, unit: "mg", frequency: "once_daily", instructions: "Take in the morning" },
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
- { "fhir_id": "med-uuid", "resourceType": "MedicationRequest" }
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": ["...FHIR MedicationRequest resources..."], "total": 3 }
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 FHIR MedicationRequest resource
444
+ // → a single MedicationResponse
410
445
 
411
446
  await sdk.patient.updateMedicationStatus("patient-id", "med-id", {
412
- status: "stopped",
413
- discontinued_reason: "Patient reported adverse reaction",
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": "ChIJ...",
439
- "name": "Banner University Medical Center",
440
- "vicinity": "1111 E McDowell Rd, Phoenix",
441
- "types": ["hospital", "health", "point_of_interest"],
442
- "geometry": { "location": { "lat": 33.4826, "lng": -112.0624 } },
443
- "rating": 4.1,
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": 8,
448
- "radius_km": 10,
449
- "source": "google_places"
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"` when no Google Places API key is configured.
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({ patient_id: "patient-id", reason: "Annual checkup", encounter_type: "outpatient" });
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
- { "fhir_id": "encounter-uuid", "id": "...", "resourceType": "Encounter" }
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 `id`) as the `encounter-id` passed to `getEncounter`/`vitals.record`'s `encounter_id` — that's the actual FHIR resource identifier.
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: "PHQ-9",
477
- title: "PHQ-9 Depression Screen",
478
- items: [{ link_id: "q1", text: "Little interest?", type: "integer" }],
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
- items: [{ link_id: "q1", answers: [{ value_integer: 2 }] }],
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 — options is optional; omit it to use the
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**: confirmed live
517
- against `dev` — the identical image submitted as `data:image/png;base64,...` silently
518
- returns `{ "type": "ocr_error", "ok": false, "error": "" }` (the empty-`error` "soft
519
- failure" shape, not an HTTP error), while the same bytes re-encoded as JPEG return a
520
- real `ocr_result`. This PNG/JPEG distinction is not documented upstream.
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 documented outcome when `imageUrl1` has no detectable face (Rekognition `InvalidParameterException`).
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
- // dev (current) — 503, Agora credentials not provisioned
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
- // once Agora credentials are provisioned — 200
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: 99,
826
- weight_kg: 70,
827
- height_cm: 175,
894
+ oxygen_saturation: 98,
828
895
  });
829
896
  ```
830
897
 
831
- 200/201 — recorded vitals echoed back; exact shape varies by backend revision.
898
+ ```json
899
+ { "observations": 7, "patient_id": "patient-uuid" }
900
+ ```
832
901
 
833
902
  ```ts
834
- // List vitals with optional date range
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
- Array/list of recorded vitals entries for the date range.
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: "influenza_a",
928
+ type: "covid19",
858
929
  result: "negative",
859
- lot_number: "LOT12345",
860
- administered_date: "2026-06-16",
930
+ encounter_id: "encounter-id",
861
931
  });
862
932
  ```
863
933
 
864
- `201` — maps to a FHIR Observation (e.g. LOINC `80382-5` for `influenza_a`).
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
- // List diagnostics
868
- const tests = await sdk.diagnostics.list("patient-id", {
869
- from: "2026-01-01",
870
- to: "2026-06-16",
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
- Array/list of recorded diagnostic test results for the date range.
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 dev service swagger publishes `GET /connect` for Lambda warm-up / connectivity checks (confirmed 2026-06-17). The SDK exposes that as an unauthenticated `connect()` method:
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
- The `environment` field is present only on patient/vitals/diagnostics `connect()` responses — don't branch on its presence, just check `status: "connected"`.
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 publish only `GET /connect`, so each group also keeps the low-level escape hatch for early integration if backend domain routes are added before typed SDK methods:
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 once their swaggers publish domain paths.
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<Record<string, unknown> | null>(null);
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((profile) => setData(profile as Record<string, unknown>))
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