@healthcloudai/hc-sdk 0.1.2
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 +564 -0
- package/dist/index.cjs +768 -0
- package/dist/index.d.cts +1085 -0
- package/dist/index.d.ts +1085 -0
- package/dist/index.js +733 -0
- package/package.json +60 -0
package/README.md
ADDED
|
@@ -0,0 +1,564 @@
|
|
|
1
|
+
# @healthcloudai/hc-sdk
|
|
2
|
+
|
|
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
|
+
|
|
5
|
+
> **Swagger verification date:** 2026-06-17. All paths and operation counts below were confirmed against live swagger endpoints.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @healthcloudai/hc-sdk
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
No peer dependencies are required. `react-native` is an optional peer (the SDK works identically in Node and React Native).
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
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
|
+
## Quick start
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { HCSDK } from "@healthcloudai/hc-sdk";
|
|
29
|
+
|
|
30
|
+
const sdk = new HCSDK({
|
|
31
|
+
environment: "dev", // "dev" | "uat" | "prod"
|
|
32
|
+
tenantId: "eclinicapi",
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
// 1. Register
|
|
36
|
+
const registration = await sdk.auth.register({
|
|
37
|
+
email: "patient@example.com",
|
|
38
|
+
password: "SecurePassword123!",
|
|
39
|
+
first_name: "Jane",
|
|
40
|
+
last_name: "Doe",
|
|
41
|
+
date_of_birth: "1990-06-15",
|
|
42
|
+
sex_at_birth: "female",
|
|
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.
|
|
46
|
+
|
|
47
|
+
// 2. Verify email OTP (uat/prod only — dev auto-verifies and returns a token)
|
|
48
|
+
await sdk.auth.verifyEmail({
|
|
49
|
+
user_id: registration.cognito_sub,
|
|
50
|
+
otp: "123456",
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
// 3. Login — token is stored automatically on the SDK instance
|
|
54
|
+
await sdk.auth.login({
|
|
55
|
+
email: "patient@example.com",
|
|
56
|
+
password: "SecurePassword123!",
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
// 4. All subsequent calls use the token automatically
|
|
60
|
+
const patient = await sdk.patient.getProfile("patient-id");
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Configuration
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const sdk = new HCSDK({
|
|
69
|
+
environment: "dev", // required
|
|
70
|
+
tenantId: "eclinicapi", // optional — injected as X-Tenant-ID header and into auth request bodies
|
|
71
|
+
accessToken: "existing-token", // optional — skip login if you already have a token
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Base URLs are resolved from `environment` and the internal service name:
|
|
76
|
+
|
|
77
|
+
| Environment | Pattern | Example |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| `dev` | `https://dev-api-{service}.health.cloud` | `https://dev-api-patient.health.cloud` |
|
|
80
|
+
| `uat` | `https://uat-api-{service}.health.cloud` | `https://uat-api-vitals.health.cloud` |
|
|
81
|
+
| `prod` | `https://api-{service}.health.cloud` | `https://api-diagnostics.health.cloud` |
|
|
82
|
+
|
|
83
|
+
Token management:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
sdk.setAccessToken("my-token");
|
|
87
|
+
const token = sdk.getAccessToken(); // string | undefined
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Service groups
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
sdk.auth // register / login / verify-email
|
|
96
|
+
sdk.patient // connect, profile, address, phone, photo, medications, encounters, insurance,
|
|
97
|
+
// questionnaires, locations, vision face-compare, assistant (classify/ocr/chat/
|
|
98
|
+
// knowledge), CareConnect communications (presence/groups/conversations/messages/invites/rtc-token)
|
|
99
|
+
sdk.vitals // connect, record and list vitals
|
|
100
|
+
sdk.diagnostics // connect, rapid tests, list diagnostics
|
|
101
|
+
sdk.provider // connect + low-level request escape hatch
|
|
102
|
+
sdk.ehr // connect + low-level request escape hatch
|
|
103
|
+
sdk.appointments // connect + low-level request escape hatch
|
|
104
|
+
sdk.rppg // connect + low-level request escape hatch
|
|
105
|
+
sdk.session // connect + low-level request escape hatch
|
|
106
|
+
sdk.telehealth // connect + low-level request escape hatch
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
All groups share one HTTP client, one token store, one error handler, the same URL resolver, query serialiser, and path-param interpolator.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Auth
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
// Register a new patient
|
|
117
|
+
await sdk.auth.register({
|
|
118
|
+
email: "patient@example.com",
|
|
119
|
+
password: "SecurePassword123!",
|
|
120
|
+
tenant_id: "eclinicapi", // optional if tenantId passed to HCSDK constructor
|
|
121
|
+
first_name: "Jane",
|
|
122
|
+
last_name: "Doe",
|
|
123
|
+
date_of_birth: "1990-06-15",
|
|
124
|
+
sex_at_birth: "female", // 'male' | 'female' | 'unknown'
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
// Verify email OTP (uat/prod only — dev auto-verifies on register)
|
|
128
|
+
await sdk.auth.verifyEmail({
|
|
129
|
+
user_id: "cognito-sub-from-register-response",
|
|
130
|
+
otp: "123456",
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
// Login — access token is extracted from the response and stored on sdk.state
|
|
134
|
+
const authResponse = await sdk.auth.login({
|
|
135
|
+
email: "patient@example.com",
|
|
136
|
+
password: "SecurePassword123!",
|
|
137
|
+
});
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The token extractor looks for `token`, `access_token`, `accessToken`, `idToken` at the top level, and also inside a nested `data` or `result` object.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Patient
|
|
145
|
+
|
|
146
|
+
```ts
|
|
147
|
+
// Get profile
|
|
148
|
+
const profile = await sdk.patient.getProfile("patient-id");
|
|
149
|
+
|
|
150
|
+
// Update phone (triggers SMS OTP)
|
|
151
|
+
await sdk.patient.updatePhone("patient-id", { phone: "+15550001234" });
|
|
152
|
+
|
|
153
|
+
// Verify SMS OTP
|
|
154
|
+
await sdk.patient.verifySms("patient-id", { otp: "654321" });
|
|
155
|
+
|
|
156
|
+
// Update address
|
|
157
|
+
await sdk.patient.updateAddress("patient-id", {
|
|
158
|
+
street: "123 Main St",
|
|
159
|
+
city: "San Francisco",
|
|
160
|
+
state: "CA",
|
|
161
|
+
zip: "94102",
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
// Update race (valid values: white, black_or_african_american, asian,
|
|
165
|
+
// american_indian_or_alaska_native, native_hawaiian_or_other_pacific_islander,
|
|
166
|
+
// other, unknown, declined_to_specify)
|
|
167
|
+
await sdk.patient.updateRace("patient-id", { races: ["white", "asian"] });
|
|
168
|
+
|
|
169
|
+
// Update demographics — partial update, all fields optional
|
|
170
|
+
await sdk.patient.updateDemographics("patient-id", {
|
|
171
|
+
date_of_birth: "1990-06-15",
|
|
172
|
+
sex_at_birth: "female", // 'male' | 'female' | 'intersex' | 'unknown'
|
|
173
|
+
gender_identity: "woman",
|
|
174
|
+
ethnicity: "not_hispanic_or_latino",
|
|
175
|
+
marital_status: "married",
|
|
176
|
+
nationality: "ZA", // ISO 3166-1 alpha-2
|
|
177
|
+
preferred_language: "en", // BCP-47
|
|
178
|
+
communications: [{ language: "en", preferred: true }],
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
// Photo
|
|
182
|
+
const uploadUrl = await sdk.patient.getPhotoUploadUrl("patient-id");
|
|
183
|
+
await sdk.patient.uploadPhoto("patient-id", {
|
|
184
|
+
data: "base64-image-data",
|
|
185
|
+
content_type: "image/jpeg",
|
|
186
|
+
});
|
|
187
|
+
const photo = await sdk.patient.getPhoto("patient-id", { binary_id: "binary-id" });
|
|
188
|
+
|
|
189
|
+
// Face match (Rekognition CompareFaces against a stored FHIR Binary)
|
|
190
|
+
await sdk.patient.compareFaceMatch("patient-id", {
|
|
191
|
+
selfie_data: "base64-selfie-data",
|
|
192
|
+
reference_binary_id: "binary-id",
|
|
193
|
+
similarity_threshold: 80.0, // optional, defaults to 80.0
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
// OCR identity document (Textract AnalyzeID)
|
|
197
|
+
await sdk.patient.scanIdentityDocument("patient-id", {
|
|
198
|
+
document_data: "base64-document-data",
|
|
199
|
+
verify_against_demographics: true, // compares extracted name+DOB to the patient's FHIR record
|
|
200
|
+
});
|
|
201
|
+
|
|
202
|
+
// Insurance coverage
|
|
203
|
+
await sdk.patient.createInsurance("patient-id", {
|
|
204
|
+
priority: "primary", // 'primary' | 'secondary' | 'tertiary'
|
|
205
|
+
payer_name: "Blue Cross Blue Shield",
|
|
206
|
+
member_id: "M001",
|
|
207
|
+
relationship: "self",
|
|
208
|
+
});
|
|
209
|
+
await sdk.patient.checkInsuranceEligibility({
|
|
210
|
+
payer_id: "BCBSM",
|
|
211
|
+
member_id: "M001",
|
|
212
|
+
first_name: "Jane",
|
|
213
|
+
last_name: "Doe",
|
|
214
|
+
date_of_birth: "1990-06-15",
|
|
215
|
+
});
|
|
216
|
+
|
|
217
|
+
// Medications — required: name, route, dosage.value, dosage.unit, dosage.frequency
|
|
218
|
+
await sdk.patient.createMedication("patient-id", {
|
|
219
|
+
name: "Lisinopril",
|
|
220
|
+
rxnorm_code: "29046",
|
|
221
|
+
route: "oral",
|
|
222
|
+
dosage: { value: 10, unit: "mg", frequency: "once_daily", instructions: "Take in the morning" },
|
|
223
|
+
status: "active",
|
|
224
|
+
intent: "order",
|
|
225
|
+
prescriber_name: "Dr. Sarah Smith",
|
|
226
|
+
});
|
|
227
|
+
const meds = await sdk.patient.listMedications("patient-id");
|
|
228
|
+
const med = await sdk.patient.getMedication("patient-id", "med-id");
|
|
229
|
+
await sdk.patient.updateMedicationStatus("patient-id", "med-id", {
|
|
230
|
+
status: "stopped",
|
|
231
|
+
discontinued_reason: "Patient reported adverse reaction",
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
// Nearest locations — params are lat/lon/radius_km/type, NOT latitude/longitude
|
|
235
|
+
const locations = await sdk.patient.listNearestLocations({
|
|
236
|
+
lat: 33.4484,
|
|
237
|
+
lon: -112.0740,
|
|
238
|
+
radius_km: 10,
|
|
239
|
+
type: "hospital",
|
|
240
|
+
});
|
|
241
|
+
|
|
242
|
+
// Encounters
|
|
243
|
+
await sdk.patient.createEncounter({ patient_id: "patient-id", reason: "Annual checkup", encounter_type: "outpatient" });
|
|
244
|
+
const encounters = await sdk.patient.listEncounters({ patient_id: "patient-id" });
|
|
245
|
+
const encounter = await sdk.patient.getEncounter("encounter-id");
|
|
246
|
+
|
|
247
|
+
// Questionnaires
|
|
248
|
+
await sdk.patient.createQuestionnaire({
|
|
249
|
+
name: "PHQ-9",
|
|
250
|
+
title: "PHQ-9 Depression Screen",
|
|
251
|
+
items: [{ link_id: "q1", text: "Little interest?", type: "integer" }],
|
|
252
|
+
});
|
|
253
|
+
await sdk.patient.createQuestionnaireResponse("questionnaire-id", {
|
|
254
|
+
patient_id: "patient-id",
|
|
255
|
+
items: [{ link_id: "q1", answers: [{ value_integer: 2 }] }],
|
|
256
|
+
});
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## Assistant API (`/assistant/*`, public except knowledge/actions)
|
|
262
|
+
|
|
263
|
+
`classifyVoiceCommand`, `ocrIdentityDocument`, and `askAssistant` are called with
|
|
264
|
+
**no `Authorization` header** — they work for logged-out field workers. The 3
|
|
265
|
+
knowledge/action routes below them use the normal bearer-token auth.
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
// Voice command classification — options is optional; omit it to use the
|
|
269
|
+
// full action catalog from listAssistantActions() automatically
|
|
270
|
+
const { Action } = await sdk.patient.classifyVoiceCommand({
|
|
271
|
+
text: "start the test for this patient",
|
|
272
|
+
});
|
|
273
|
+
|
|
274
|
+
// ID document OCR via vision LLM — pass a full data: URI, not bare base64
|
|
275
|
+
const ocr = await sdk.patient.ocrIdentityDocument({
|
|
276
|
+
image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
|
|
277
|
+
});
|
|
278
|
+
// { type: 'ocr_result' | 'ocr_error', ok, fields?: { name, documentType, documentNumber, dateOfBirth, sex, nationality }, error? }
|
|
279
|
+
|
|
280
|
+
// Grounded RAG chat — answers only from the fixed internal knowledge base
|
|
281
|
+
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)
|
|
284
|
+
|
|
285
|
+
// Knowledge base + action catalog (bearer token required)
|
|
286
|
+
const kb = await sdk.patient.listKnowledge({ collection: "ppe" });
|
|
287
|
+
const results = await sdk.patient.searchKnowledge({ q: "swab collection", limit: 5 });
|
|
288
|
+
const actions = await sdk.patient.listAssistantActions();
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## Vision API (`/vision/face-compare`, bearer token required)
|
|
294
|
+
|
|
295
|
+
URL-based face comparison via Rekognition — unlike `compareFaceMatch`, this
|
|
296
|
+
takes two arbitrary HTTPS image URLs instead of a FHIR-stored binary.
|
|
297
|
+
|
|
298
|
+
```ts
|
|
299
|
+
const result = await sdk.patient.compareFacesByUrl({
|
|
300
|
+
imageUrl1: "https://example.com/photo-a.jpg",
|
|
301
|
+
imageUrl2: "https://example.com/photo-b.jpg",
|
|
302
|
+
similarityThreshold: 90.0, // optional, defaults to 80.0
|
|
303
|
+
});
|
|
304
|
+
// { samePerson, confidence, similarityThreshold, faceDetectedInImage1, faceDetectedInImage2 }
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## CareConnect Communications API (`/communications/*`)
|
|
310
|
+
|
|
311
|
+
Presence, groups, conversations, messages, and invites are Postgres-backed,
|
|
312
|
+
client-generated-`id` upserts (POST always means create-or-replace). Every
|
|
313
|
+
route except `mintRtcToken` requires a bearer token; `tenant_id` is always
|
|
314
|
+
resolved server-side from the JWT.
|
|
315
|
+
|
|
316
|
+
```ts
|
|
317
|
+
// Initial state snapshot — fetch once on app load instead of polling each list
|
|
318
|
+
const state = await sdk.patient.getCommunicationsState();
|
|
319
|
+
// { presence, groups, conversations, messages, invites } — all keys always present
|
|
320
|
+
|
|
321
|
+
// Presence (1 record per contactId; re-upserting overwrites the old state)
|
|
322
|
+
await sdk.patient.upsertPresence({ contactId: "c-self", presence: "online" });
|
|
323
|
+
const presence = await sdk.patient.listPresence();
|
|
324
|
+
|
|
325
|
+
// Groups
|
|
326
|
+
await sdk.patient.upsertGroup({
|
|
327
|
+
id: "grp-1",
|
|
328
|
+
name: "Field Team Alpha",
|
|
329
|
+
groupKind: "team", // 'team' | 'case' | 'broadcast'
|
|
330
|
+
memberIds: ["c-self", "c-2"],
|
|
331
|
+
callEnabled: true,
|
|
332
|
+
});
|
|
333
|
+
const groups = await sdk.patient.listGroups();
|
|
334
|
+
|
|
335
|
+
// Conversations (direct or group)
|
|
336
|
+
await sdk.patient.upsertConversation({ id: "conv-1", kind: "group", groupId: "grp-1", title: "Field Team Alpha" });
|
|
337
|
+
const conversations = await sdk.patient.listConversations();
|
|
338
|
+
|
|
339
|
+
// Messages — server always returns status: "sent" regardless of what you send
|
|
340
|
+
await sdk.patient.upsertMessage({
|
|
341
|
+
id: "msg-1",
|
|
342
|
+
conversationId: "conv-1",
|
|
343
|
+
senderId: "c-self",
|
|
344
|
+
kind: "text",
|
|
345
|
+
body: "On site, starting screening.",
|
|
346
|
+
});
|
|
347
|
+
const messages = await sdk.patient.listMessages({ conversationId: "conv-1" });
|
|
348
|
+
|
|
349
|
+
// Invites — dev returns a usable inviteCode without sending real SMS/email
|
|
350
|
+
await sdk.patient.upsertInvite({
|
|
351
|
+
id: "inv-1",
|
|
352
|
+
name: "Jordan Lee",
|
|
353
|
+
destination: "jordan@example.com",
|
|
354
|
+
channel: "email", // 'sms' | 'email' | 'link'
|
|
355
|
+
role: "field_worker",
|
|
356
|
+
});
|
|
357
|
+
const invites = await sdk.patient.listInvites();
|
|
358
|
+
|
|
359
|
+
// 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
|
+
await sdk.patient.mintRtcToken({ channelName: "case-123", uid: "c-self" });
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## Vitals
|
|
368
|
+
|
|
369
|
+
```ts
|
|
370
|
+
// Record vitals
|
|
371
|
+
await sdk.vitals.record("patient-id", {
|
|
372
|
+
heart_rate: 72,
|
|
373
|
+
temperature: 98.6,
|
|
374
|
+
systolic: 120,
|
|
375
|
+
diastolic: 80,
|
|
376
|
+
oxygen_saturation: 99,
|
|
377
|
+
weight_kg: 70,
|
|
378
|
+
height_cm: 175,
|
|
379
|
+
});
|
|
380
|
+
|
|
381
|
+
// List vitals with optional date range
|
|
382
|
+
const vitals = await sdk.vitals.list("patient-id", {
|
|
383
|
+
from: "2026-01-01",
|
|
384
|
+
to: "2026-06-16",
|
|
385
|
+
});
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
---
|
|
389
|
+
|
|
390
|
+
## Diagnostics
|
|
391
|
+
|
|
392
|
+
```ts
|
|
393
|
+
// Create rapid test result
|
|
394
|
+
// NOTE: three corrections vs the HealthCloud API reference doc, all confirmed
|
|
395
|
+
// against the live dev deployment:
|
|
396
|
+
// 1. path is /patients/{id}/diagnostics/rapid-tests (doc says /rapid-test, 404s)
|
|
397
|
+
// 2. field is `type`, not `test_type` (doc's name 400s with "KeyError: 'type'")
|
|
398
|
+
// 3. `type` is validated against a server-side RapidTestType enum — the doc's
|
|
399
|
+
// own example "COVID-19" 400s as invalid. `influenza_a` is confirmed valid;
|
|
400
|
+
// the full enum isn't published, so verify any other value against dev first.
|
|
401
|
+
await sdk.diagnostics.createRapidTest("patient-id", {
|
|
402
|
+
type: "influenza_a",
|
|
403
|
+
result: "negative",
|
|
404
|
+
lot_number: "LOT12345",
|
|
405
|
+
administered_date: "2026-06-16",
|
|
406
|
+
});
|
|
407
|
+
|
|
408
|
+
// List diagnostics
|
|
409
|
+
const tests = await sdk.diagnostics.list("patient-id", {
|
|
410
|
+
from: "2026-01-01",
|
|
411
|
+
to: "2026-06-16",
|
|
412
|
+
});
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
---
|
|
416
|
+
|
|
417
|
+
## Connectivity and service stubs
|
|
418
|
+
|
|
419
|
+
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:
|
|
420
|
+
|
|
421
|
+
```ts
|
|
422
|
+
await sdk.patient.connect();
|
|
423
|
+
await sdk.vitals.connect();
|
|
424
|
+
await sdk.diagnostics.connect();
|
|
425
|
+
await sdk.provider.connect();
|
|
426
|
+
await sdk.ehr.connect();
|
|
427
|
+
await sdk.appointments.connect();
|
|
428
|
+
await sdk.rppg.connect();
|
|
429
|
+
await sdk.session.connect();
|
|
430
|
+
await sdk.telehealth.connect();
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
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
|
+
|
|
435
|
+
```ts
|
|
436
|
+
// Low-level escape hatch - available on all service groups
|
|
437
|
+
await sdk.appointments.request("GET", "/appointments");
|
|
438
|
+
await sdk.ehr.request("GET", "/records");
|
|
439
|
+
await sdk.rppg.request("POST", "/sessions");
|
|
440
|
+
await sdk.session.request("POST", "/sessions");
|
|
441
|
+
await sdk.telehealth.request("POST", "/consultations");
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
Domain typed methods will be added once their swaggers publish domain paths.
|
|
445
|
+
|
|
446
|
+
---
|
|
447
|
+
|
|
448
|
+
## Error handling
|
|
449
|
+
|
|
450
|
+
All non-2xx responses and network failures are normalized into `SDKError`:
|
|
451
|
+
|
|
452
|
+
```ts
|
|
453
|
+
import { SDKError } from "@healthcloudai/hc-sdk";
|
|
454
|
+
|
|
455
|
+
try {
|
|
456
|
+
await sdk.patient.getProfile("patient-id");
|
|
457
|
+
} catch (error) {
|
|
458
|
+
if (error instanceof SDKError) {
|
|
459
|
+
console.log(error.statusCode); // HTTP status; 0 for network errors
|
|
460
|
+
console.log(error.message); // Backend message or HTTP status text
|
|
461
|
+
console.log(error.response); // Parsed response body (may be undefined)
|
|
462
|
+
console.log(error.cause); // Underlying Error for network failures
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
| Scenario | `statusCode` | `message` | `cause` |
|
|
468
|
+
|---|---|---|---|
|
|
469
|
+
| Network failure (no connection) | `0` | OS error message | `TypeError` |
|
|
470
|
+
| Missing path param | `0` | `"Path parameter "{x}" is required."` | — |
|
|
471
|
+
| No access token | `401` | SDK message | — |
|
|
472
|
+
| 4xx/5xx from backend | HTTP status | Backend `message`/`error`/`detail` field | — |
|
|
473
|
+
| 204 No Content | — | — | resolves to `undefined` |
|
|
474
|
+
|
|
475
|
+
`SDKError instanceof Error` holds after CJS transpilation (prototype chain restored via `Object.setPrototypeOf`).
|
|
476
|
+
|
|
477
|
+
---
|
|
478
|
+
|
|
479
|
+
## React Native integration
|
|
480
|
+
|
|
481
|
+
```tsx
|
|
482
|
+
import React, { useEffect, useState } from "react";
|
|
483
|
+
import { View, Text, ActivityIndicator } from "react-native";
|
|
484
|
+
import { HCSDK, SDKError } from "@healthcloudai/hc-sdk";
|
|
485
|
+
|
|
486
|
+
const sdk = new HCSDK({ environment: "dev", tenantId: "eclinicapi" });
|
|
487
|
+
|
|
488
|
+
export function usePatientProfile(patientId: string) {
|
|
489
|
+
const [data, setData] = useState<Record<string, unknown> | null>(null);
|
|
490
|
+
const [loading, setLoading] = useState(true);
|
|
491
|
+
const [error, setError] = useState<SDKError | null>(null);
|
|
492
|
+
|
|
493
|
+
useEffect(() => {
|
|
494
|
+
sdk.patient.getProfile(patientId)
|
|
495
|
+
.then((profile) => setData(profile as Record<string, unknown>))
|
|
496
|
+
.catch((err: unknown) => {
|
|
497
|
+
if (err instanceof SDKError) setError(err);
|
|
498
|
+
})
|
|
499
|
+
.finally(() => setLoading(false));
|
|
500
|
+
}, [patientId]);
|
|
501
|
+
|
|
502
|
+
return { data, loading, error };
|
|
503
|
+
}
|
|
504
|
+
|
|
505
|
+
export function PatientProfile({ patientId }: { patientId: string }) {
|
|
506
|
+
const { data, loading, error } = usePatientProfile(patientId);
|
|
507
|
+
if (loading) return <ActivityIndicator />;
|
|
508
|
+
if (error) return <Text>Error {error.statusCode}: {error.message}</Text>;
|
|
509
|
+
return <View><Text>{JSON.stringify(data)}</Text></View>;
|
|
510
|
+
}
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
---
|
|
514
|
+
|
|
515
|
+
## Swagger operation coverage matrix
|
|
516
|
+
|
|
517
|
+
Verified against live swagger specs on 2026-06-17.
|
|
518
|
+
|
|
519
|
+
| Service | Swagger host | Paths | Ops in swagger | Implemented | Missing | Extra | Status |
|
|
520
|
+
|---|---|---:|---:|---:|---|---|---|
|
|
521
|
+
| Patient (auth) | dev-api-patient.health.cloud | 51 | 46 | 46 | — | — | COMPLETE |
|
|
522
|
+
| Vitals | dev-api-vitals.health.cloud | 2 | 3 | 3 | — | — | COMPLETE |
|
|
523
|
+
| Diagnostics | dev-api-diagnostics.health.cloud | 3 | 3 | 3 | — | — | COMPLETE |
|
|
524
|
+
| Provider | dev-api-provider.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
525
|
+
| EHR | dev-api-ehr.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
526
|
+
| Appointments | dev-api-appointments.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
527
|
+
| rPPG | dev-api-rppg.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
528
|
+
| Session | dev-api-session.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
529
|
+
| Telehealth | dev-api-telehealth.health.cloud | 1 | 1 | 1 | — | — | CONNECT ONLY |
|
|
530
|
+
| **Total** | | **62** | **58** | **58** | | | |
|
|
531
|
+
|
|
532
|
+
> Swaggers do not publish request/response schemas. Request models are now aligned against
|
|
533
|
+
> `health_cloud_api.md` (the live API reference) rather than guessed from integration
|
|
534
|
+
> examples. Response models extend `Record<string, unknown>`.
|
|
535
|
+
|
|
536
|
+
---
|
|
537
|
+
|
|
538
|
+
## Running tests
|
|
539
|
+
|
|
540
|
+
```bash
|
|
541
|
+
npm test --workspace @healthcloudai/hc-sdk
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
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.
|
|
545
|
+
|
|
546
|
+
Live integration test from the repository root:
|
|
547
|
+
|
|
548
|
+
```powershell
|
|
549
|
+
$env:HC_TENANT_ID="elevancehealth"
|
|
550
|
+
$env:HC_PASSWORD="Secure@2025!"
|
|
551
|
+
npm run test:hc-sdk --prefix integration-tests
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
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.
|
|
555
|
+
|
|
556
|
+
---
|
|
557
|
+
|
|
558
|
+
## Build
|
|
559
|
+
|
|
560
|
+
```bash
|
|
561
|
+
npm run build # tsup → dist/index.js (ESM) + dist/index.cjs (CJS) + dist/index.d.ts
|
|
562
|
+
npm run typecheck # tsc --noEmit
|
|
563
|
+
npm run lint # eslint src --ext .ts
|
|
564
|
+
```
|