@healthcloudai/hc-sdk 0.1.2 → 0.2.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.
Files changed (2) hide show
  1. package/README.md +487 -16
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -41,9 +41,23 @@ const registration = await sdk.auth.register({
41
41
  date_of_birth: "1990-06-15",
42
42
  sex_at_birth: "female",
43
43
  });
44
- // dev: registration.access_token is already set on the SDK login flow below;
45
- // uat/prod: registration.email_otp_sent is true and verify-email is required first.
44
+ ```
45
+
46
+ ```json
47
+ {
48
+ "cognito_sub": "xxxxxxxx-...",
49
+ "fhir_patient_id": "yyyyyyyy-...",
50
+ "email_otp_sent": false,
51
+ "email_verified": true,
52
+ "access_token": "eyJhbGci...",
53
+ "id_token": "eyJhbGci...",
54
+ "expires_in": 3600
55
+ }
56
+ ```
46
57
 
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`.
59
+
60
+ ```ts
47
61
  // 2. Verify email OTP (uat/prod only — dev auto-verifies and returns a token)
48
62
  await sdk.auth.verifyEmail({
49
63
  user_id: registration.cognito_sub,
@@ -55,7 +69,13 @@ await sdk.auth.login({
55
69
  email: "patient@example.com",
56
70
  password: "SecurePassword123!",
57
71
  });
72
+ ```
58
73
 
74
+ ```json
75
+ { "access_token": "eyJhbGci...", "id_token": "eyJhbGci...", "expires_in": 3600 }
76
+ ```
77
+
78
+ ```ts
59
79
  // 4. All subsequent calls use the token automatically
60
80
  const patient = await sdk.patient.getProfile("patient-id");
61
81
  ```
@@ -123,13 +143,44 @@ await sdk.auth.register({
123
143
  date_of_birth: "1990-06-15",
124
144
  sex_at_birth: "female", // 'male' | 'female' | 'unknown'
125
145
  });
146
+ ```
126
147
 
148
+ ```json
149
+ // dev — 201
150
+ {
151
+ "cognito_sub": "xxxxxxxx-...",
152
+ "fhir_patient_id": "yyyyyyyy-...",
153
+ "email_otp_sent": false,
154
+ "email_verified": true,
155
+ "access_token": "eyJhbGci...",
156
+ "id_token": "eyJhbGci...",
157
+ "expires_in": 3600
158
+ }
159
+ ```
160
+
161
+ ```json
162
+ // uat/prod — 201, no token yet; call verifyEmail then login
163
+ {
164
+ "cognito_sub": "xxxxxxxx-...",
165
+ "fhir_patient_id": "yyyyyyyy-...",
166
+ "email_otp_sent": true,
167
+ "email_verified": false
168
+ }
169
+ ```
170
+
171
+ ```ts
127
172
  // Verify email OTP (uat/prod only — dev auto-verifies on register)
128
173
  await sdk.auth.verifyEmail({
129
174
  user_id: "cognito-sub-from-register-response",
130
175
  otp: "123456",
131
176
  });
177
+ ```
132
178
 
179
+ ```json
180
+ { "verified": true }
181
+ ```
182
+
183
+ ```ts
133
184
  // Login — access token is extracted from the response and stored on sdk.state
134
185
  const authResponse = await sdk.auth.login({
135
186
  email: "patient@example.com",
@@ -137,22 +188,54 @@ const authResponse = await sdk.auth.login({
137
188
  });
138
189
  ```
139
190
 
191
+ ```json
192
+ { "access_token": "eyJhbGci...", "id_token": "eyJhbGci...", "expires_in": 3600 }
193
+ ```
194
+
140
195
  The token extractor looks for `token`, `access_token`, `accessToken`, `idToken` at the top level, and also inside a nested `data` or `result` object.
141
196
 
142
197
  ---
143
198
 
144
199
  ## Patient
145
200
 
201
+ ### Profile, phone, address, race, demographics
202
+
146
203
  ```ts
147
- // Get profile
204
+ // Get profile — full FHIR R4 Patient resource
148
205
  const profile = await sdk.patient.getProfile("patient-id");
206
+ ```
207
+
208
+ ```json
209
+ {
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": []
217
+ }
218
+ ```
149
219
 
220
+ ```ts
150
221
  // Update phone (triggers SMS OTP)
151
222
  await sdk.patient.updatePhone("patient-id", { phone: "+15550001234" });
223
+ ```
224
+
225
+ ```json
226
+ { "sms_otp_sent": true }
227
+ ```
152
228
 
229
+ ```ts
153
230
  // Verify SMS OTP
154
231
  await sdk.patient.verifySms("patient-id", { otp: "654321" });
232
+ ```
233
+
234
+ ```json
235
+ { "verified": true }
236
+ ```
155
237
 
238
+ ```ts
156
239
  // Update address
157
240
  await sdk.patient.updateAddress("patient-id", {
158
241
  street: "123 Main St",
@@ -160,12 +243,24 @@ await sdk.patient.updateAddress("patient-id", {
160
243
  state: "CA",
161
244
  zip: "94102",
162
245
  });
246
+ ```
247
+
248
+ ```json
249
+ { "updated": true }
250
+ ```
163
251
 
252
+ ```ts
164
253
  // Update race (valid values: white, black_or_african_american, asian,
165
254
  // american_indian_or_alaska_native, native_hawaiian_or_other_pacific_islander,
166
255
  // other, unknown, declined_to_specify)
167
256
  await sdk.patient.updateRace("patient-id", { races: ["white", "asian"] });
257
+ ```
168
258
 
259
+ ```json
260
+ { "updated": true }
261
+ ```
262
+
263
+ ```ts
169
264
  // Update demographics — partial update, all fields optional
170
265
  await sdk.patient.updateDemographics("patient-id", {
171
266
  date_of_birth: "1990-06-15",
@@ -177,13 +272,34 @@ await sdk.patient.updateDemographics("patient-id", {
177
272
  preferred_language: "en", // BCP-47
178
273
  communications: [{ language: "en", preferred: true }],
179
274
  });
275
+ ```
180
276
 
181
- // Photo
277
+ ```json
278
+ { "updated": true }
279
+ ```
280
+
281
+ ### Photo, face match, ID document OCR
282
+
283
+ ```ts
182
284
  const uploadUrl = await sdk.patient.getPhotoUploadUrl("patient-id");
285
+ ```
286
+
287
+ ```json
288
+ { "url": "https://s3.wasabisys.com/...", "key": "patients/{id}/photo.png" }
289
+ ```
290
+
291
+ ```ts
183
292
  await sdk.patient.uploadPhoto("patient-id", {
184
293
  data: "base64-image-data",
185
294
  content_type: "image/jpeg",
186
295
  });
296
+ ```
297
+
298
+ ```json
299
+ { "binary_id": "fhir-binary-uuid" }
300
+ ```
301
+
302
+ ```ts
187
303
  const photo = await sdk.patient.getPhoto("patient-id", { binary_id: "binary-id" });
188
304
 
189
305
  // Face match (Rekognition CompareFaces against a stored FHIR Binary)
@@ -192,20 +308,63 @@ await sdk.patient.compareFaceMatch("patient-id", {
192
308
  reference_binary_id: "binary-id",
193
309
  similarity_threshold: 80.0, // optional, defaults to 80.0
194
310
  });
311
+ ```
195
312
 
313
+ ```json
314
+ {
315
+ "match": true,
316
+ "confidence": 96.42,
317
+ "similarity_threshold": 80.0,
318
+ "face_detected_in_selfie": true
319
+ }
320
+ ```
321
+
322
+ ```ts
196
323
  // OCR identity document (Textract AnalyzeID)
197
324
  await sdk.patient.scanIdentityDocument("patient-id", {
198
325
  document_data: "base64-document-data",
199
326
  verify_against_demographics: true, // compares extracted name+DOB to the patient's FHIR record
200
327
  });
328
+ ```
201
329
 
202
- // Insurance coverage
330
+ ```json
331
+ {
332
+ "first_name": "JANE",
333
+ "last_name": "DOE",
334
+ "date_of_birth": "06/15/1990",
335
+ "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
+ }
349
+ }
350
+ ```
351
+
352
+ ### Insurance
353
+
354
+ ```ts
203
355
  await sdk.patient.createInsurance("patient-id", {
204
356
  priority: "primary", // 'primary' | 'secondary' | 'tertiary'
205
357
  payer_name: "Blue Cross Blue Shield",
206
358
  member_id: "M001",
207
359
  relationship: "self",
208
360
  });
361
+ ```
362
+
363
+ ```json
364
+ { "coverages_created": 1, "patient_id": "patient-id" }
365
+ ```
366
+
367
+ ```ts
209
368
  await sdk.patient.checkInsuranceEligibility({
210
369
  payer_id: "BCBSM",
211
370
  member_id: "M001",
@@ -213,8 +372,15 @@ await sdk.patient.checkInsuranceEligibility({
213
372
  last_name: "Doe",
214
373
  date_of_birth: "1990-06-15",
215
374
  });
375
+ ```
376
+
377
+ Stedi EDI 270/271 eligibility response — shape varies by payer.
216
378
 
217
- // Medications — required: name, route, dosage.value, dosage.unit, dosage.frequency
379
+ ### Medications
380
+
381
+ Required fields: `name`, `route`, `dosage.value`, `dosage.unit`, `dosage.frequency`.
382
+
383
+ ```ts
218
384
  await sdk.patient.createMedication("patient-id", {
219
385
  name: "Lisinopril",
220
386
  rxnorm_code: "29046",
@@ -224,32 +390,100 @@ await sdk.patient.createMedication("patient-id", {
224
390
  intent: "order",
225
391
  prescriber_name: "Dr. Sarah Smith",
226
392
  });
393
+ ```
394
+
395
+ ```json
396
+ { "fhir_id": "med-uuid", "resourceType": "MedicationRequest" }
397
+ ```
398
+
399
+ ```ts
227
400
  const meds = await sdk.patient.listMedications("patient-id");
401
+ ```
402
+
403
+ ```json
404
+ { "medications": ["...FHIR MedicationRequest resources..."], "total": 3 }
405
+ ```
406
+
407
+ ```ts
228
408
  const med = await sdk.patient.getMedication("patient-id", "med-id");
409
+ // → a single FHIR MedicationRequest resource
410
+
229
411
  await sdk.patient.updateMedicationStatus("patient-id", "med-id", {
230
412
  status: "stopped",
231
413
  discontinued_reason: "Patient reported adverse reaction",
232
414
  });
415
+ ```
416
+
417
+ ```json
418
+ { "updated": true, "fhir_id": "med-uuid" }
419
+ ```
420
+
421
+ ### Nearest locations
233
422
 
234
- // Nearest locations — params are lat/lon/radius_km/type, NOT latitude/longitude
423
+ Params are `lat`/`lon`/`radius_km`/`type` — not `latitude`/`longitude`.
424
+
425
+ ```ts
235
426
  const locations = await sdk.patient.listNearestLocations({
236
427
  lat: 33.4484,
237
428
  lon: -112.0740,
238
429
  radius_km: 10,
239
430
  type: "hospital",
240
431
  });
432
+ ```
241
433
 
242
- // Encounters
434
+ ```json
435
+ {
436
+ "locations": [
437
+ {
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
445
+ }
446
+ ],
447
+ "total": 8,
448
+ "radius_km": 10,
449
+ "source": "google_places"
450
+ }
451
+ ```
452
+
453
+ `source` is `"hardcoded"` when no Google Places API key is configured.
454
+
455
+ ### Encounters
456
+
457
+ ```ts
243
458
  await sdk.patient.createEncounter({ patient_id: "patient-id", reason: "Annual checkup", encounter_type: "outpatient" });
459
+ ```
460
+
461
+ ```json
462
+ { "fhir_id": "encounter-uuid", "id": "...", "resourceType": "Encounter" }
463
+ ```
464
+
465
+ ```ts
244
466
  const encounters = await sdk.patient.listEncounters({ patient_id: "patient-id" });
245
467
  const encounter = await sdk.patient.getEncounter("encounter-id");
468
+ ```
469
+
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.
471
+
472
+ ### Questionnaires
246
473
 
247
- // Questionnaires
474
+ ```ts
248
475
  await sdk.patient.createQuestionnaire({
249
476
  name: "PHQ-9",
250
477
  title: "PHQ-9 Depression Screen",
251
478
  items: [{ link_id: "q1", text: "Little interest?", type: "integer" }],
252
479
  });
480
+ ```
481
+
482
+ ```json
483
+ { "fhir_id": "questionnaire-uuid" }
484
+ ```
485
+
486
+ ```ts
253
487
  await sdk.patient.createQuestionnaireResponse("questionnaire-id", {
254
488
  patient_id: "patient-id",
255
489
  items: [{ link_id: "q1", answers: [{ value_integer: 2 }] }],
@@ -270,24 +504,127 @@ knowledge/action routes below them use the normal bearer-token auth.
270
504
  const { Action } = await sdk.patient.classifyVoiceCommand({
271
505
  text: "start the test for this patient",
272
506
  });
507
+ ```
273
508
 
509
+ ```json
510
+ { "Action": "start_test" }
511
+ ```
512
+
513
+ When nothing in the catalog matches: `{ "Action": "" }` — there is no HTTP error case for this route.
514
+
515
+ `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.
521
+
522
+ ```ts
274
523
  // ID document OCR via vision LLM — pass a full data: URI, not bare base64
275
524
  const ocr = await sdk.patient.ocrIdentityDocument({
276
525
  image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
277
526
  });
278
- // { type: 'ocr_result' | 'ocr_error', ok, fields?: { name, documentType, documentNumber, dateOfBirth, sex, nationality }, error? }
527
+ ```
279
528
 
529
+ ```json
530
+ {
531
+ "type": "ocr_result",
532
+ "ok": true,
533
+ "fields": {
534
+ "name": "JANE DOE",
535
+ "documentType": "PASSPORT",
536
+ "documentNumber": "X1234567",
537
+ "dateOfBirth": "1990-06-15",
538
+ "sex": "F",
539
+ "nationality": "US"
540
+ }
541
+ }
542
+ ```
543
+
544
+ 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." }`.
545
+
546
+ ```ts
280
547
  // Grounded RAG chat — answers only from the fixed internal knowledge base
281
548
  const chat = await sdk.patient.askAssistant({ message: "What PPE should I wear for screening?" });
282
- // { answer, citations, suggestedActions, disclaimer, error? } — treat 502/503 as
283
- // "show fallback citations", not a hard error (askAssistant resolves the body either way)
549
+ ```
550
+
551
+ ```json
552
+ {
553
+ "answer": "For field screening, you should wear gloves, a surgical mask or N95 respirator, eye protection, and a disposable gown for close-contact screening...",
554
+ "citations": [
555
+ { "id": "kb_004", "title": "Standard PPE for field screening", "collection": "ppe" }
556
+ ],
557
+ "suggestedActions": [
558
+ { "id": "open_symptom_checker", "label": "Open symptom checker" }
559
+ ],
560
+ "disclaimer": "Informational and screening support only. This is not a diagnosis and not a substitute for a clinician or public-health authority."
561
+ }
562
+ ```
563
+
564
+ Treat `502`/`503` as "show fallback citations", not a hard error — `askAssistant` resolves the body either way.
284
565
 
566
+ ```ts
285
567
  // Knowledge base + action catalog (bearer token required)
286
568
  const kb = await sdk.patient.listKnowledge({ collection: "ppe" });
569
+ ```
570
+
571
+ ```json
572
+ {
573
+ "collections": [
574
+ { "id": "screening", "name": "Screening & Triage" },
575
+ { "id": "ppe", "name": "PPE & Safety" },
576
+ { "id": "sample_collection", "name": "Sample Collection" },
577
+ { "id": "field_ops", "name": "Field Operations" }
578
+ ],
579
+ "entries": [
580
+ { "id": "kb_004", "collection": "ppe", "title": "Standard PPE for field screening", "tags": ["ppe", "gloves", "mask", "gown", "safety"] }
581
+ ],
582
+ "total": 3
583
+ }
584
+ ```
585
+
586
+ ```ts
287
587
  const results = await sdk.patient.searchKnowledge({ q: "swab collection", limit: 5 });
588
+ ```
589
+
590
+ ```json
591
+ {
592
+ "query": "swab collection",
593
+ "results": [
594
+ {
595
+ "id": "kb_007",
596
+ "collection": "sample_collection",
597
+ "title": "Nasal swab collection steps",
598
+ "body": "Use the swab provided in the kit...",
599
+ "tags": ["sample", "swab", "nasal", "collection", "test"]
600
+ }
601
+ ],
602
+ "total": 1
603
+ }
604
+ ```
605
+
606
+ ```ts
288
607
  const actions = await sdk.patient.listAssistantActions();
289
608
  ```
290
609
 
610
+ ```json
611
+ {
612
+ "actions": [
613
+ { "id": "start_assessment", "label": "Start assessment" },
614
+ { "id": "start_test", "label": "Start test" },
615
+ { "id": "capture_result", "label": "Capture result" },
616
+ { "id": "onboard_patient", "label": "Onboard patient" },
617
+ { "id": "medication_order", "label": "Medication order" },
618
+ { "id": "view_records", "label": "View records" },
619
+ { "id": "view_alerts", "label": "View alerts" },
620
+ { "id": "open_symptom_checker", "label": "Open symptom checker" },
621
+ { "id": "view_case", "label": "View case" },
622
+ { "id": "connect_clinician", "label": "Connect with a clinician" }
623
+ ],
624
+ "total": 10
625
+ }
626
+ ```
627
+
291
628
  ---
292
629
 
293
630
  ## Vision API (`/vision/face-compare`, bearer token required)
@@ -301,9 +638,20 @@ const result = await sdk.patient.compareFacesByUrl({
301
638
  imageUrl2: "https://example.com/photo-b.jpg",
302
639
  similarityThreshold: 90.0, // optional, defaults to 80.0
303
640
  });
304
- // { samePerson, confidence, similarityThreshold, faceDetectedInImage1, faceDetectedInImage2 }
305
641
  ```
306
642
 
643
+ ```json
644
+ {
645
+ "samePerson": true,
646
+ "confidence": 99.21,
647
+ "similarityThreshold": 90.0,
648
+ "faceDetectedInImage1": true,
649
+ "faceDetectedInImage2": true
650
+ }
651
+ ```
652
+
653
+ A `500` with `{"error": "<detail>"}` is the documented outcome when `imageUrl1` has no detectable face (Rekognition `InvalidParameterException`).
654
+
307
655
  ---
308
656
 
309
657
  ## CareConnect Communications API (`/communications/*`)
@@ -316,12 +664,39 @@ resolved server-side from the JWT.
316
664
  ```ts
317
665
  // Initial state snapshot — fetch once on app load instead of polling each list
318
666
  const state = await sdk.patient.getCommunicationsState();
319
- // { presence, groups, conversations, messages, invites } — all keys always present
667
+ ```
320
668
 
669
+ ```json
670
+ {
671
+ "presence": [{ "id": "c-self", "contactId": "c-self", "presence": "online", "lastActiveAt": "2026-06-16T09:12:00" }],
672
+ "groups": [{ "id": "grp-1", "name": "Field Team Alpha", "groupKind": "team", "memberIds": ["c-self", "c-2"], "createdBy": "c-self", "callEnabled": true, "createdAt": "...", "updatedAt": "..." }],
673
+ "conversations": [{ "id": "conv-1", "kind": "group", "groupId": "grp-1", "title": "Field Team Alpha", "unreadCount": 0, "createdAt": "...", "updatedAt": "..." }],
674
+ "messages": [{ "id": "msg-1", "conversationId": "conv-1", "senderId": "c-self", "kind": "text", "body": "On site, starting screening.", "status": "sent", "createdAt": "..." }],
675
+ "invites": [{ "id": "inv-1", "name": "Jordan Lee", "destination": "jordan@example.com", "channel": "email", "role": "field_worker", "status": "queued", "inviteCode": "9F3KQ7XZ", "createdAt": "..." }]
676
+ }
677
+ ```
678
+
679
+ A brand-new tenant gets all five keys present with empty arrays — never a missing key.
680
+
681
+ ```ts
321
682
  // Presence (1 record per contactId; re-upserting overwrites the old state)
322
683
  await sdk.patient.upsertPresence({ contactId: "c-self", presence: "online" });
684
+ ```
685
+
686
+ ```json
687
+ // 201
688
+ { "id": "c-self", "contactId": "c-self", "presence": "online", "lastActiveAt": "2026-06-16T09:12:00Z" }
689
+ ```
690
+
691
+ ```ts
323
692
  const presence = await sdk.patient.listPresence();
693
+ ```
694
+
695
+ ```json
696
+ { "presence": ["..."], "total": 1 }
697
+ ```
324
698
 
699
+ ```ts
325
700
  // Groups
326
701
  await sdk.patient.upsertGroup({
327
702
  id: "grp-1",
@@ -330,12 +705,40 @@ await sdk.patient.upsertGroup({
330
705
  memberIds: ["c-self", "c-2"],
331
706
  callEnabled: true,
332
707
  });
708
+ ```
709
+
710
+ ```json
711
+ // 201
712
+ { "id": "grp-1", "name": "Field Team Alpha", "groupKind": "team", "memberIds": ["c-self", "c-2"], "callEnabled": true }
713
+ ```
714
+
715
+ ```ts
333
716
  const groups = await sdk.patient.listGroups();
717
+ ```
334
718
 
719
+ ```json
720
+ { "groups": ["..."], "total": 1 }
721
+ ```
722
+
723
+ ```ts
335
724
  // Conversations (direct or group)
336
725
  await sdk.patient.upsertConversation({ id: "conv-1", kind: "group", groupId: "grp-1", title: "Field Team Alpha" });
726
+ ```
727
+
728
+ ```json
729
+ // 201
730
+ { "id": "conv-1", "kind": "group", "groupId": "grp-1", "title": "Field Team Alpha" }
731
+ ```
732
+
733
+ ```ts
337
734
  const conversations = await sdk.patient.listConversations();
735
+ ```
736
+
737
+ ```json
738
+ { "conversations": ["..."], "total": 1 }
739
+ ```
338
740
 
741
+ ```ts
339
742
  // Messages — server always returns status: "sent" regardless of what you send
340
743
  await sdk.patient.upsertMessage({
341
744
  id: "msg-1",
@@ -344,8 +747,22 @@ await sdk.patient.upsertMessage({
344
747
  kind: "text",
345
748
  body: "On site, starting screening.",
346
749
  });
750
+ ```
751
+
752
+ ```json
753
+ // 201
754
+ { "id": "msg-1", "conversationId": "conv-1", "senderId": "c-self", "kind": "text", "body": "On site, starting screening.", "status": "sent" }
755
+ ```
756
+
757
+ ```ts
347
758
  const messages = await sdk.patient.listMessages({ conversationId: "conv-1" });
759
+ ```
348
760
 
761
+ ```json
762
+ { "messages": ["..."], "total": 1 }
763
+ ```
764
+
765
+ ```ts
349
766
  // Invites — dev returns a usable inviteCode without sending real SMS/email
350
767
  await sdk.patient.upsertInvite({
351
768
  id: "inv-1",
@@ -354,14 +771,46 @@ await sdk.patient.upsertInvite({
354
771
  channel: "email", // 'sms' | 'email' | 'link'
355
772
  role: "field_worker",
356
773
  });
774
+ ```
775
+
776
+ ```json
777
+ // 201
778
+ { "id": "inv-1", "name": "Jordan Lee", "destination": "jordan@example.com", "channel": "email", "inviteCode": "9F3KQ7XZ", "status": "queued" }
779
+ ```
780
+
781
+ ```ts
357
782
  const invites = await sdk.patient.listInvites();
783
+ ```
784
+
785
+ ```json
786
+ { "invites": ["..."], "total": 1 }
787
+ ```
358
788
 
789
+ ```ts
359
790
  // Live-call token minting — no Authorization header; the channel name is the gate.
360
- // Currently returns 503 in dev (Agora credentials not provisioned) — treat that
361
- // as expected and fall back to a mock/offline call UI.
362
791
  await sdk.patient.mintRtcToken({ channelName: "case-123", uid: "c-self" });
363
792
  ```
364
793
 
794
+ ```json
795
+ // dev (current) — 503, Agora credentials not provisioned
796
+ { "error": "Live calling is not configured", "configured": false }
797
+ ```
798
+
799
+ ```json
800
+ // once Agora credentials are provisioned — 200
801
+ {
802
+ "appId": "...",
803
+ "channelName": "case-123",
804
+ "uid": "c-self",
805
+ "rtcToken": "006...",
806
+ "role": "publisher",
807
+ "ttlSeconds": 3600,
808
+ "expiresAt": "2026-06-16T10:12:00Z"
809
+ }
810
+ ```
811
+
812
+ Treat the `503` as expected, not a bug, and fall back to a mock/offline call UI.
813
+
365
814
  ---
366
815
 
367
816
  ## Vitals
@@ -377,7 +826,11 @@ await sdk.vitals.record("patient-id", {
377
826
  weight_kg: 70,
378
827
  height_cm: 175,
379
828
  });
829
+ ```
380
830
 
831
+ 200/201 — recorded vitals echoed back; exact shape varies by backend revision.
832
+
833
+ ```ts
381
834
  // List vitals with optional date range
382
835
  const vitals = await sdk.vitals.list("patient-id", {
383
836
  from: "2026-01-01",
@@ -385,6 +838,8 @@ const vitals = await sdk.vitals.list("patient-id", {
385
838
  });
386
839
  ```
387
840
 
841
+ Array/list of recorded vitals entries for the date range.
842
+
388
843
  ---
389
844
 
390
845
  ## Diagnostics
@@ -404,7 +859,11 @@ await sdk.diagnostics.createRapidTest("patient-id", {
404
859
  lot_number: "LOT12345",
405
860
  administered_date: "2026-06-16",
406
861
  });
862
+ ```
863
+
864
+ `201` — maps to a FHIR Observation (e.g. LOINC `80382-5` for `influenza_a`).
407
865
 
866
+ ```ts
408
867
  // List diagnostics
409
868
  const tests = await sdk.diagnostics.list("patient-id", {
410
869
  from: "2026-01-01",
@@ -412,6 +871,8 @@ const tests = await sdk.diagnostics.list("patient-id", {
412
871
  });
413
872
  ```
414
873
 
874
+ Array/list of recorded diagnostic test results for the date range.
875
+
415
876
  ---
416
877
 
417
878
  ## Connectivity and service stubs
@@ -430,6 +891,16 @@ await sdk.session.connect();
430
891
  await sdk.telehealth.connect();
431
892
  ```
432
893
 
894
+ ```json
895
+ { "status": "connected", "service": "patient-api", "environment": "dev" }
896
+ ```
897
+
898
+ ```json
899
+ { "status": "connected", "service": "provider-api" }
900
+ ```
901
+
902
+ The `environment` field is present only on patient/vitals/diagnostics `connect()` responses — don't branch on its presence, just check `status: "connected"`.
903
+
433
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:
434
905
 
435
906
  ```ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-sdk",
3
- "version": "0.1.2",
3
+ "version": "0.2.0",
4
4
  "description": "All-in-one HealthCloud SDK for the new HealthCloud APIs.",
5
5
  "author": "Healthcheck Systems Inc",
6
6
  "license": "MIT",