@healthcloudai/hc-sdk 3.22.0 → 3.24.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 (36) hide show
  1. package/dist/index.cjs +77 -0
  2. package/dist/index.d.cts +1312 -4
  3. package/dist/index.d.ts +1312 -4
  4. package/dist/index.js +77 -0
  5. package/docs/clients/PatientClient.md +1 -0
  6. package/docs/clients/ProviderClient.md +7 -0
  7. package/docs/docs-manifest.json +28 -3
  8. package/docs/examples/index.md +8 -0
  9. package/docs/index.md +8 -0
  10. package/docs/models/CreateProviderPatientRequest.md +22 -0
  11. package/docs/models/EncounterClinicalState.md +31 -0
  12. package/docs/models/LabOrder.md +35 -0
  13. package/docs/models/LabOrderDiagnosis.md +18 -0
  14. package/docs/models/LabOrderErrorResponse.md +21 -0
  15. package/docs/models/LabOrderItemRequest.md +17 -0
  16. package/docs/models/LabOrderProvider.md +20 -0
  17. package/docs/models/LabOrderRequisitionResponse.md +20 -0
  18. package/docs/models/LabOrderTest.md +19 -0
  19. package/docs/models/LabOrderUnsentItem.md +19 -0
  20. package/docs/models/ListLabOrdersResponse.md +18 -0
  21. package/docs/models/PlaceLabOrderRequest.md +27 -0
  22. package/docs/models/PlaceLabOrderResponse.md +20 -0
  23. package/docs/models/ProviderEncounterStatusCounts.md +21 -0
  24. package/docs/models/ProviderHomeSummaryResponse.md +19 -0
  25. package/docs/models/ProviderPatientListResponse.md +19 -0
  26. package/docs/models/ProviderPatientResponse.md +17 -0
  27. package/docs/models/index.md +17 -0
  28. package/docs/operations/patient.getPatientEncounterClinicalState.md +170 -0
  29. package/docs/operations/provider.createPatient.md +155 -0
  30. package/docs/operations/provider.getHomeSummary.md +115 -0
  31. package/docs/operations/provider.getLabOrder.md +179 -0
  32. package/docs/operations/provider.getLabOrderRequisition.md +148 -0
  33. package/docs/operations/provider.listLabOrders.md +198 -0
  34. package/docs/operations/provider.listPatients.md +154 -0
  35. package/docs/operations/provider.placeLabOrder.md +384 -0
  36. package/package.json +1 -1
@@ -0,0 +1,384 @@
1
+ # Place a Quest lab order for a tenant patient
2
+
3
+ Operation ID: `provider.placeLabOrder`
4
+
5
+ Place a Quest lab order for a patient in the authenticated provider's tenant. Catalog items (panels are expanded) are grouped into one Quest requisition, and one FHIR ServiceRequest, per collection modality: psc orders are held at a Quest Patient Service Center, home_kit orders need the tenant's home_kit_enabled flag. Rapid tests are not sent to Quest and come back under unsent_items. The ordering NPI (ORC-12/OBR-16) comes from the tenant's Quest roster in integration_attributes.QUEST, or from the tenant default provider for authorized orderers; it is never read from the Practitioner profile. Every active ask-at-order-entry question of every ordered Quest code must be answered, checked against the stored Quest compendium. 201: Quest accepted every requisition. 200: replay of the same idempotency_key and body. 202: Quest's answer is not known yet (timeout, 5xx, empty response); retry with the same idempotency_key and body, which re-sends the identical order, never a new one. 409 quest_rejected: Quest refused a requisition and the key is used up; the body lists every requisition so accepted ones are not ordered twice. Only Provider-pool tokens are accepted. Each call can place real orders: an agent must have the clinician's explicit confirmation.
6
+
7
+ ## Public method
8
+
9
+ `placeLabOrder`
10
+
11
+ Signature: `provider.placeLabOrder(patientId, request)`
12
+
13
+ Return type: `Promise<PlaceLabOrderResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `POST /patients/{patient_id}/lab-orders`
28
+
29
+ ## Path parameters
30
+
31
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
32
+ |---|---|---:|---|---|---|---:|---|
33
+ | `patient_id` | `string` | Yes | | | | No | |
34
+
35
+ ## Query parameters
36
+
37
+ None.
38
+
39
+ ## Body parameters
40
+
41
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
42
+ |---|---|---:|---|---|---|---:|---|
43
+ | `body` | [`PlaceLabOrderRequest`](../models/PlaceLabOrderRequest.md) | No | | | | Yes | |
44
+
45
+ Request model: [`PlaceLabOrderRequest`](../models/PlaceLabOrderRequest.md)
46
+
47
+ ## Request example
48
+
49
+ ```json
50
+ {
51
+ "aoe_answers": {
52
+ "395": {
53
+ "75400658": "CLEAN CATCH URINE"
54
+ }
55
+ },
56
+ "collection_timezone": "America/New_York",
57
+ "comments": [
58
+ "FASTING 8 HOURS"
59
+ ],
60
+ "diagnoses": [
61
+ {
62
+ "code": "R53.83",
63
+ "description": "Other fatigue"
64
+ }
65
+ ],
66
+ "encounter_id": "encounter-example-001",
67
+ "expected_collection_date": "2026-10-29",
68
+ "idempotency_key": "00000000-0000-4000-8000-000000000010",
69
+ "items": [
70
+ {
71
+ "catalog_item_id": "00000000-0000-4000-8000-000000000020"
72
+ }
73
+ ]
74
+ }
75
+ ```
76
+
77
+ ## Success responses
78
+
79
+ | Status | Shape | Content type | Description |
80
+ |---|---|---|---|
81
+ | `200` | [`PlaceLabOrderResponse`](../models/PlaceLabOrderResponse.md) | application/json | Replay: every requisition already existed with this idempotency_key and body |
82
+ | `201` | [`PlaceLabOrderResponse`](../models/PlaceLabOrderResponse.md) | application/json | Quest accepted every requisition |
83
+ | `202` | [`PlaceLabOrderResponse`](../models/PlaceLabOrderResponse.md) | application/json | At least one requisition is still being sent; retry with the same idempotency_key |
84
+
85
+ ## Success response examples
86
+
87
+ ### 200
88
+
89
+ ```json
90
+ {
91
+ "order_group_id": "00000000-0000-4000-8000-000000000030",
92
+ "orders": [
93
+ {
94
+ "abn_required": false,
95
+ "ack_code": "AA",
96
+ "authored_at": "2026-10-28T09:15:00-04:00",
97
+ "collection_modality": "psc",
98
+ "diagnoses": [
99
+ {
100
+ "code": "R53.83",
101
+ "description": "Other fatigue"
102
+ }
103
+ ],
104
+ "expected_collection_at": "2026-10-29T08:00:00-04:00",
105
+ "fhir_status": "active",
106
+ "lab": "MET",
107
+ "order_group_id": "00000000-0000-4000-8000-000000000030",
108
+ "order_id": "00000000-0000-4000-8000-000000000040",
109
+ "ordering_provider": {
110
+ "first_name": "Alex",
111
+ "last_name": "Smith",
112
+ "npi": "1234567893",
113
+ "source": "roster"
114
+ },
115
+ "patient_id": "patient-example-001",
116
+ "placer_order_number": "HC0123456789ABCDEF01",
117
+ "quest_http_status": null,
118
+ "requester": "Practitioner/practitioner-example-001",
119
+ "requisition_available": true,
120
+ "source": "provider_app",
121
+ "status": "accepted",
122
+ "tests": [
123
+ {
124
+ "catalog_item_id": "00000000-0000-4000-8000-000000000020",
125
+ "description": "URINALYSIS, COMPLETE",
126
+ "quest_code": "5463"
127
+ }
128
+ ]
129
+ }
130
+ ],
131
+ "replayed": true,
132
+ "unsent_items": [
133
+ {
134
+ "catalog_item_id": "00000000-0000-4000-8000-000000000060",
135
+ "name": "Visby CT/NG/TV",
136
+ "reason": "rapid_kit_flow"
137
+ }
138
+ ]
139
+ }
140
+ ```
141
+
142
+ ### 201
143
+
144
+ ```json
145
+ {
146
+ "order_group_id": "string",
147
+ "orders": [
148
+ {
149
+ "abn_required": true,
150
+ "ack_code": "string",
151
+ "authored_at": "string",
152
+ "collection_modality": "psc",
153
+ "diagnoses": [],
154
+ "expected_collection_at": "string",
155
+ "fhir_status": "string",
156
+ "lab": "string",
157
+ "order_group_id": "string",
158
+ "order_id": "string",
159
+ "ordering_provider": {
160
+ "first_name": "string",
161
+ "last_name": "string",
162
+ "npi": "string",
163
+ "source": "roster"
164
+ },
165
+ "patient_id": "string",
166
+ "placer_order_number": "string",
167
+ "quest_http_status": 0,
168
+ "requester": "string",
169
+ "requisition_available": true,
170
+ "source": "provider_app",
171
+ "status": "submitting",
172
+ "tests": [
173
+ {
174
+ "catalog_item_id": "string",
175
+ "description": "string",
176
+ "quest_code": "string"
177
+ }
178
+ ]
179
+ }
180
+ ],
181
+ "replayed": true,
182
+ "unsent_items": [
183
+ {
184
+ "catalog_item_id": "string",
185
+ "name": "string",
186
+ "reason": "rapid_kit_flow"
187
+ }
188
+ ]
189
+ }
190
+ ```
191
+
192
+ ### 202
193
+
194
+ ```json
195
+ {
196
+ "order_group_id": "string",
197
+ "orders": [
198
+ {
199
+ "abn_required": true,
200
+ "ack_code": "string",
201
+ "authored_at": "string",
202
+ "collection_modality": "psc",
203
+ "diagnoses": [],
204
+ "expected_collection_at": "string",
205
+ "fhir_status": "string",
206
+ "lab": "string",
207
+ "order_group_id": "string",
208
+ "order_id": "string",
209
+ "ordering_provider": {
210
+ "first_name": "string",
211
+ "last_name": "string",
212
+ "npi": "string",
213
+ "source": "roster"
214
+ },
215
+ "patient_id": "string",
216
+ "placer_order_number": "string",
217
+ "quest_http_status": 0,
218
+ "requester": "string",
219
+ "requisition_available": true,
220
+ "source": "provider_app",
221
+ "status": "submitting",
222
+ "tests": [
223
+ {
224
+ "catalog_item_id": "string",
225
+ "description": "string",
226
+ "quest_code": "string"
227
+ }
228
+ ]
229
+ }
230
+ ],
231
+ "replayed": true,
232
+ "unsent_items": [
233
+ {
234
+ "catalog_item_id": "string",
235
+ "name": "string",
236
+ "reason": "rapid_kit_flow"
237
+ }
238
+ ]
239
+ }
240
+ ```
241
+
242
+ ## Common errors
243
+
244
+ | Status | Shape | Content type | Description |
245
+ |---|---|---|---|
246
+ | `400` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The body is invalid or an AOE question is not answered |
247
+ | `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Provider Bearer authentication is required |
248
+ | `403` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | Not a Provider-pool token, or the caller is neither on the tenant's Quest roster nor authorized to order under the default provider |
249
+ | `404` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The patient or encounter does not exist in the caller's tenant |
250
+ | `409` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The tenant's account is not active, Quest ordering is not enabled, the key was used with another body, an item is unavailable, or Quest rejected the order |
251
+ | `500` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Unexpected failure; retry with the same idempotency_key |
252
+ | `503` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The order is saved but not sent, or no Quest compendium is stored; retry with the same key |
253
+
254
+ ## Error examples
255
+
256
+ ### 400 — Unanswered AOE question
257
+
258
+ ```json
259
+ {
260
+ "code": "aoe_answer_missing",
261
+ "error": "An ask-at-order-entry question is not answered",
262
+ "fields": [
263
+ "aoe_answers.395.75400658"
264
+ ]
265
+ }
266
+ ```
267
+
268
+ ### 401 — No provider JWT
269
+
270
+ ```json
271
+ {
272
+ "error": "Provider authorization required"
273
+ }
274
+ ```
275
+
276
+ ### 403 — Caller cannot order
277
+
278
+ ```json
279
+ {
280
+ "code": "not_an_ordering_provider",
281
+ "error": "Caller may not order Quest labs in this tenant",
282
+ "fields": []
283
+ }
284
+ ```
285
+
286
+ ### 404 — Unknown patient
287
+
288
+ ```json
289
+ {
290
+ "code": "patient_not_found",
291
+ "error": "Patient not found in this tenant",
292
+ "fields": []
293
+ }
294
+ ```
295
+
296
+ ### 409 — Same key, different body
297
+
298
+ ```json
299
+ {
300
+ "code": "idempotency_key_reused",
301
+ "error": "Idempotency key already used with a different order",
302
+ "fields": [
303
+ "idempotency_key"
304
+ ]
305
+ }
306
+ ```
307
+
308
+ ### 500 — Unexpected failure
309
+
310
+ ```json
311
+ {
312
+ "error": "Lab order service failed; retry the request"
313
+ }
314
+ ```
315
+
316
+ ### 503 — Saved, not sent
317
+
318
+ ```json
319
+ {
320
+ "code": "order_not_sent",
321
+ "error": "The order was saved but not sent; retry with the same key",
322
+ "fields": []
323
+ }
324
+ ```
325
+
326
+ ## NodeJS / TypeScript implementation
327
+
328
+ ```ts
329
+ import { HCSDK } from "@healthcloudai/hc-sdk";
330
+ ```
331
+
332
+ ```ts
333
+ const patientId = "<PATIENT_ID>";
334
+
335
+ const request = {
336
+ "aoe_answers": {
337
+ "395": {
338
+ "75400658": "CLEAN CATCH URINE"
339
+ }
340
+ },
341
+ "collection_timezone": "America/New_York",
342
+ "comments": [
343
+ "FASTING 8 HOURS"
344
+ ],
345
+ "diagnoses": [
346
+ {
347
+ "code": "R53.83",
348
+ "description": "Other fatigue"
349
+ }
350
+ ],
351
+ "encounter_id": "encounter-example-001",
352
+ "expected_collection_date": "2026-10-29",
353
+ "idempotency_key": "00000000-0000-4000-8000-000000000010",
354
+ "items": [
355
+ {
356
+ "catalog_item_id": "00000000-0000-4000-8000-000000000020"
357
+ }
358
+ ]
359
+ };
360
+
361
+ const result = await provider.placeLabOrder(patientId, request);
362
+ ```
363
+
364
+ ## cURL
365
+
366
+ ```bash
367
+ curl -X POST \
368
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
369
+ -H 'Content-Type: application/json' \
370
+ -d '{"aoe_answers":{"395":{"75400658":"CLEAN CATCH URINE"}},"collection_timezone":"America/New_York","comments":["FASTING 8 HOURS"],"diagnoses":[{"code":"R53.83","description":"Other fatigue"}],"encounter_id":"encounter-example-001","expected_collection_date":"2026-10-29","idempotency_key":"00000000-0000-4000-8000-000000000010","items":[{"catalog_item_id":"00000000-0000-4000-8000-000000000020"}]}' \
371
+ 'https://dev-api-provider.health.cloud/patients/%3CPATIENT_ID%3E/lab-orders'
372
+ ```
373
+
374
+ ## Notes
375
+
376
+ None.
377
+
378
+ ## Prepared Test Console scenario
379
+
380
+ No canonical scenario is currently associated.
381
+
382
+ ## Real response
383
+
384
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-sdk",
3
- "version": "3.22.0",
3
+ "version": "3.24.0",
4
4
  "description": "All-in-one HealthCloud SDK with typed platform APIs and secure connector clients.",
5
5
  "author": "Healthcheck Systems Inc",
6
6
  "license": "MIT",