@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.
- package/README.md +487 -16
- 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
|
-
|
|
45
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
283
|
-
|
|
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
|
-
|
|
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
|