@healthcloudai/hc-sdk 3.3.0 → 3.5.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 (35) hide show
  1. package/dist/index.cjs +22 -0
  2. package/dist/index.d.cts +324 -164
  3. package/dist/index.d.ts +324 -164
  4. package/dist/index.js +22 -0
  5. package/docs/clients/GraphClient.md +3 -0
  6. package/docs/docs-manifest.json +16 -4
  7. package/docs/examples/index.md +3 -0
  8. package/docs/index.md +3 -0
  9. package/docs/models/AddInsuranceRequest.md +1 -0
  10. package/docs/models/CheckEncounterResponse.md +36 -0
  11. package/docs/models/CheckInEncounterResponse.md +51 -0
  12. package/docs/models/CreateRapidTestRequest.md +3 -0
  13. package/docs/models/{RapidTest.md → CreateRapidTestResponse.md} +8 -4
  14. package/docs/models/GetAppointmentTelehealthLinkResponse.md +17 -0
  15. package/docs/models/GetPreferredPharmacyResponse.md +2 -2
  16. package/docs/models/GetScanUploadUrlRequest.md +1 -0
  17. package/docs/models/GetVectorDocumentChunksResponse.md +30 -0
  18. package/docs/models/ListVectorCollectionsResponse.md +19 -0
  19. package/docs/models/VectorCollection.md +24 -0
  20. package/docs/models/VectorSearchDocumentsRequest.md +25 -0
  21. package/docs/models/VectorSearchHit.md +30 -0
  22. package/docs/models/VectorSearchResponse.md +22 -0
  23. package/docs/models/index.md +10 -1
  24. package/docs/operations/appointments.getTelehealthLink.md +4 -2
  25. package/docs/operations/diagnostics.createRapidTest.md +49 -37
  26. package/docs/operations/diagnostics.getScanUploadUrl.md +3 -1
  27. package/docs/operations/diagnostics.lookupTestByGs1.md +3 -1
  28. package/docs/operations/graph.getVectorDocumentChunks.md +189 -0
  29. package/docs/operations/graph.listVectorCollections.md +138 -0
  30. package/docs/operations/graph.vectorSearchDocuments.md +207 -0
  31. package/docs/operations/patient.addInsurance.md +11 -9
  32. package/docs/operations/patient.checkEncounter.md +93 -7
  33. package/docs/operations/patient.checkInEncounter.md +68 -2
  34. package/docs/operations/patient.getPreferredPharmacy.md +13 -1
  35. package/package.json +1 -1
@@ -2,7 +2,7 @@
2
2
 
3
3
  Operation ID: `diagnostics.createRapidTest`
4
4
 
5
- Create a rapid test Observation for a patient (COVID, flu, pregnancy, glucose, etc.). Returns the created test's test_id — use it with diagnostics.getScanUploadUrl to attach a photo of the test device, or with diagnostics.getTestResult to retrieve it later. administered_date is accepted as an alias for performed_date/performed_datetime; when none of the three date fields are supplied, the test is recorded as performed today.
5
+ Create a rapid test Observation for a patient (COVID, flu, pregnancy, glucose, etc.). Returns the created test's test_id — use it with diagnostics.getScanUploadUrl to attach a photo of the test device, or with diagnostics.getTestResult to retrieve it later. administered_date is accepted as an alias for performed_date/performed_datetime; when none of the three date fields are supplied, the test is recorded as performed today. When encounter_id (or athena_encounter_id directly) is supplied and the tenant has Athena with this patient linked, the result is also mirrored to the Athena chart as a lab order + lab result document (image attached when scan_storage_key resolves to one) — a best-effort, non-fatal step reported back via athena_status/athena_error/athena_order_id; the FHIR write always succeeds independently of the Athena outcome.
6
6
 
7
7
  ## Public method
8
8
 
@@ -48,16 +48,19 @@ Request model: [`CreateRapidTestRequest`](../models/CreateRapidTestRequest.md)
48
48
 
49
49
  ```json
50
50
  {
51
- "administered_date": "2026-08-10",
52
- "device_name": "Synthetic Rapid Test",
53
- "lot_number": "LOT-EXAMPLE-001",
54
- "notes": "Synthetic diagnostic example",
55
- "performed_date": "2026-08-10",
56
- "performed_datetime": "2026-08-10T12:00:00Z",
57
- "quantitative_unit": "index",
58
- "quantitative_value": 0.12,
59
- "result": "negative",
60
- "specimen_type": "nasal_swab",
51
+ "administered_date": "string",
52
+ "athena_encounter_id": "string",
53
+ "device_name": "string",
54
+ "encounter_id": "string",
55
+ "lot_number": "string",
56
+ "notes": "string",
57
+ "performed_date": "2026-01-01",
58
+ "performed_datetime": "2026-01-01T09:00:00Z",
59
+ "quantitative_unit": "string",
60
+ "quantitative_value": 0,
61
+ "result": "positive",
62
+ "scan_storage_key": "string",
63
+ "specimen_type": "blood",
61
64
  "type": "covid19"
62
65
  }
63
66
  ```
@@ -66,7 +69,7 @@ Request model: [`CreateRapidTestRequest`](../models/CreateRapidTestRequest.md)
66
69
 
67
70
  | Status | Shape | Content type | Description |
68
71
  |---|---|---|---|
69
- | `201` | [`RapidTest`](../models/RapidTest.md) | application/json | Rapid point-of-care test result created |
72
+ | `201` | [`CreateRapidTestResponse`](../models/CreateRapidTestResponse.md) | application/json | Rapid point-of-care test result created |
70
73
 
71
74
  ## Success response examples
72
75
 
@@ -74,21 +77,27 @@ Request model: [`CreateRapidTestRequest`](../models/CreateRapidTestRequest.md)
74
77
 
75
78
  ```json
76
79
  {
77
- "collected_by": "agent-example-001",
78
- "device_name": "Synthetic Rapid Test",
79
- "encounter_id": "encounter-example-001",
80
- "fhir_id": "diagnostic-example-001",
81
- "lot_number": "LOT-EXAMPLE-001",
82
- "notes": "Synthetic diagnostic example",
83
- "performed_by": "provider-example-001",
84
- "performed_date": "2026-08-10",
85
- "performed_datetime": "2026-08-10T12:00:00Z",
86
- "quantitative_unit": "index",
87
- "quantitative_value": 0.12,
88
- "result": "negative",
89
- "specimen_type": "nasal_swab",
80
+ "athena_error": "string",
81
+ "athena_order_id": "string",
82
+ "athena_status": "linked",
83
+ "collected_by": "string",
84
+ "derived_from": [
85
+ "string"
86
+ ],
87
+ "device_name": "string",
88
+ "encounter_id": "string",
89
+ "fhir_id": "string",
90
+ "lot_number": "string",
91
+ "notes": "string",
92
+ "performed_by": "string",
93
+ "performed_date": "2026-01-01",
94
+ "performed_datetime": "2026-01-01T09:00:00Z",
95
+ "quantitative_unit": "string",
96
+ "quantitative_value": 0,
97
+ "result": "positive",
98
+ "specimen_type": "nasopharyngeal_swab",
90
99
  "status": "final",
91
- "test_id": "00000000-0000-4000-8000-000000000001",
100
+ "test_id": "00000000-0000-0000-0000-000000000000",
92
101
  "type": "covid19"
93
102
  }
94
103
  ```
@@ -163,16 +172,19 @@ import { HCSDK } from "@healthcloudai/hc-sdk";
163
172
  const patientId = "<PATIENT_ID>";
164
173
 
165
174
  const request = {
166
- "administered_date": "2026-08-10",
167
- "device_name": "Synthetic Rapid Test",
168
- "lot_number": "LOT-EXAMPLE-001",
169
- "notes": "Synthetic diagnostic example",
170
- "performed_date": "2026-08-10",
171
- "performed_datetime": "2026-08-10T12:00:00Z",
172
- "quantitative_unit": "index",
173
- "quantitative_value": 0.12,
174
- "result": "negative",
175
- "specimen_type": "nasal_swab",
175
+ "administered_date": "string",
176
+ "athena_encounter_id": "string",
177
+ "device_name": "string",
178
+ "encounter_id": "string",
179
+ "lot_number": "string",
180
+ "notes": "string",
181
+ "performed_date": "2026-01-01",
182
+ "performed_datetime": "2026-01-01T09:00:00Z",
183
+ "quantitative_unit": "string",
184
+ "quantitative_value": 0,
185
+ "result": "positive",
186
+ "scan_storage_key": "string",
187
+ "specimen_type": "blood",
176
188
  "type": "covid19"
177
189
  };
178
190
 
@@ -185,7 +197,7 @@ const result = await diagnostics.createRapidTest(patientId, request);
185
197
  curl -X POST \
186
198
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
187
199
  -H 'Content-Type: application/json' \
188
- -d '{"administered_date":"2026-08-10","device_name":"Synthetic Rapid Test","lot_number":"LOT-EXAMPLE-001","notes":"Synthetic diagnostic example","performed_date":"2026-08-10","performed_datetime":"2026-08-10T12:00:00Z","quantitative_unit":"index","quantitative_value":0.12,"result":"negative","specimen_type":"nasal_swab","type":"covid19"}' \
200
+ -d '{"administered_date":"string","athena_encounter_id":"string","device_name":"string","encounter_id":"string","lot_number":"string","notes":"string","performed_date":"2026-01-01","performed_datetime":"2026-01-01T09:00:00Z","quantitative_unit":"string","quantitative_value":0,"result":"positive","scan_storage_key":"string","specimen_type":"blood","type":"covid19"}' \
189
201
  'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics/rapid-tests'
190
202
  ```
191
203
 
@@ -49,6 +49,7 @@ Request model: [`GetScanUploadUrlRequest`](../models/GetScanUploadUrlRequest.md)
49
49
  ```json
50
50
  {
51
51
  "content_type": "image/jpeg",
52
+ "encounter_id": "string",
52
53
  "filename": "scan.jpg",
53
54
  "gtin": "string",
54
55
  "test_id": "00000000-0000-0000-0000-000000000000"
@@ -137,6 +138,7 @@ const patientId = "<PATIENT_ID>";
137
138
 
138
139
  const request = {
139
140
  "content_type": "image/jpeg",
141
+ "encounter_id": "string",
140
142
  "filename": "scan.jpg",
141
143
  "gtin": "string",
142
144
  "test_id": "00000000-0000-0000-0000-000000000000"
@@ -151,7 +153,7 @@ const result = await diagnostics.getScanUploadUrl(patientId, request);
151
153
  curl -X POST \
152
154
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
153
155
  -H 'Content-Type: application/json' \
154
- -d '{"content_type":"image/jpeg","filename":"scan.jpg","gtin":"string","test_id":"00000000-0000-0000-0000-000000000000"}' \
156
+ -d '{"content_type":"image/jpeg","encounter_id":"string","filename":"scan.jpg","gtin":"string","test_id":"00000000-0000-0000-0000-000000000000"}' \
155
157
  'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics/scan-upload-url'
156
158
  ```
157
159
 
@@ -36,6 +36,7 @@ None documented.
36
36
 
37
37
  | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
38
38
  |---|---|---:|---|---|---|---:|---|
39
+ | `encounter_id` | `string` | No | | | | No | |
39
40
  | `gs1` | `string` | Yes | | | | No | GS1 barcode value (e.g. 01095577222334451721053110ABC123) |
40
41
 
41
42
  ## Body parameters
@@ -139,6 +140,7 @@ import { HCSDK } from "@healthcloudai/hc-sdk";
139
140
  const patientId = "<PATIENT_ID>";
140
141
 
141
142
  const query = {
143
+ "encounter_id": "<ENCOUNTER_ID>",
142
144
  "gs1": "<GS1>"
143
145
  };
144
146
 
@@ -150,7 +152,7 @@ const result = await diagnostics.lookupByGs1(patientId, query);
150
152
  ```bash
151
153
  curl -X GET \
152
154
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
153
- 'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics/lookup?gs1=%3CGS1%3E'
155
+ 'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics/lookup?encounter_id=%3CENCOUNTER_ID%3E&gs1=%3CGS1%3E'
154
156
  ```
155
157
 
156
158
  ## Notes
@@ -0,0 +1,189 @@
1
+ # Get one document's chunks
2
+
3
+ Operation ID: `graph.getVectorDocumentChunks`
4
+
5
+ Return every stored chunk of one document, ordered by chunk_index. Concatenating them reconstructs the text that was embedded. The doc_id is the identifier carried on each search hit. Reading a document from the payer-policy collection requires payer_key, the same rule the search follows: knowing a document id is not on its own enough to read another payer's policy.
6
+
7
+ ## Public method
8
+
9
+ `getVectorDocumentChunks`
10
+
11
+ Signature: `graph.getVectorDocumentChunks(docId, query)`
12
+
13
+ Return type: `Promise<GetVectorDocumentChunksResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /graph/vector/documents/{doc_id}`
28
+
29
+ ## Path parameters
30
+
31
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
32
+ |---|---|---:|---|---|---|---:|---|
33
+ | `doc_id` | `string` | Yes | | | | No | |
34
+
35
+ ## Query parameters
36
+
37
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
38
+ |---|---|---:|---|---|---|---:|---|
39
+ | `collection` | `string` | No | | | | No | Collection to read from; defaults to the documents corpus |
40
+ | `limit` | `integer` | No | | | `100` | No | |
41
+ | `payer_key` | `string` | No | | | | No | Payer slug; REQUIRED when reading from the payer-policy collection |
42
+
43
+ ## Body parameters
44
+
45
+ None.
46
+
47
+ Request model: None.
48
+
49
+ ## Request example
50
+
51
+ None declared in canonical OpenAPI.
52
+
53
+ ## Success responses
54
+
55
+ | Status | Shape | Content type | Description |
56
+ |---|---|---|---|
57
+ | `200` | [`GetVectorDocumentChunksResponse`](../models/GetVectorDocumentChunksResponse.md) | application/json | The document's chunks, ordered by chunk_index |
58
+
59
+ ## Success response examples
60
+
61
+ ### 200
62
+
63
+ ```json
64
+ {
65
+ "chunk_count": 0,
66
+ "chunks": [
67
+ {
68
+ "chunk_index": 0,
69
+ "collection_group": "string",
70
+ "doc_id": "string",
71
+ "id": "string",
72
+ "language": "string",
73
+ "metadata": {},
74
+ "network_id": "string",
75
+ "payer_key": "string",
76
+ "score": 0,
77
+ "source": "string",
78
+ "tags": [
79
+ "string"
80
+ ],
81
+ "text": "string",
82
+ "title": "string",
83
+ "url": "string"
84
+ }
85
+ ],
86
+ "collection": "string",
87
+ "collection_group": "string",
88
+ "doc_id": "string",
89
+ "language": "string",
90
+ "metadata": {},
91
+ "payer_key": "string",
92
+ "source": "string",
93
+ "tags": [
94
+ "string"
95
+ ],
96
+ "title": "string",
97
+ "url": "string"
98
+ }
99
+ ```
100
+
101
+ ## Common errors
102
+
103
+ | Status | Shape | Content type | Description |
104
+ |---|---|---|---|
105
+ | `400` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | The request was invalid — a required parameter was missing or a filter value was not recognized |
106
+ | `401` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
107
+ | `404` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | No chunks exist for doc_id in the collection |
108
+ | `500` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Internal server error |
109
+ | `503` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Vector search is not configured in this environment |
110
+
111
+ ## Error examples
112
+
113
+ ### 400 — A required query parameter was missing or a filter value was not recognized (sanitized example)
114
+
115
+ ```json
116
+ {
117
+ "error": "Bad request"
118
+ }
119
+ ```
120
+
121
+ ### 401 — Missing or invalid access token
122
+
123
+ ```json
124
+ {
125
+ "error": "Authorization required"
126
+ }
127
+ ```
128
+
129
+ ### 404 — The document is not loaded in this collection
130
+
131
+ ```json
132
+ {
133
+ "error": "Document not found in the vector store"
134
+ }
135
+ ```
136
+
137
+ ### 500 — Unexpected service failure (sanitized example)
138
+
139
+ ```json
140
+ {
141
+ "error": "Internal server error"
142
+ }
143
+ ```
144
+
145
+ ### 503 — No Milvus endpoint or embedding key is provisioned
146
+
147
+ ```json
148
+ {
149
+ "error": "Vector search is not configured"
150
+ }
151
+ ```
152
+
153
+ ## NodeJS / TypeScript implementation
154
+
155
+ ```ts
156
+ import { HCSDK } from "@healthcloudai/hc-sdk";
157
+ ```
158
+
159
+ ```ts
160
+ const docId = "<DOC_ID>";
161
+
162
+ const query = {
163
+ "collection": "<COLLECTION>",
164
+ "limit": 100,
165
+ "payer_key": "<PAYER_KEY>"
166
+ };
167
+
168
+ const result = await graph.getVectorDocumentChunks(docId, query);
169
+ ```
170
+
171
+ ## cURL
172
+
173
+ ```bash
174
+ curl -X GET \
175
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
176
+ 'https://dev-api-graph.health.cloud/graph/vector/documents/%3CDOC_ID%3E?collection=%3CCOLLECTION%3E&limit=100&payer_key=%3CPAYER_KEY%3E'
177
+ ```
178
+
179
+ ## Notes
180
+
181
+ None.
182
+
183
+ ## Prepared Test Console scenario
184
+
185
+ No canonical scenario is currently associated.
186
+
187
+ ## Real response
188
+
189
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -0,0 +1,138 @@
1
+ # List searchable vector collections
2
+
3
+ Operation ID: `graph.listVectorCollections`
4
+
5
+ List the vector collections this deployment can search, with each one's chunk count, vector width, similarity metric, and whether it is partitioned by payer (which makes payer_key mandatory when reading it). The width is the operationally important field: the collections are loaded by a separate pipeline, so a corpus embedded with a different model has a different width and cannot be searched with this deployment's query vectors at all.
6
+
7
+ ## Public method
8
+
9
+ `listVectorCollections`
10
+
11
+ Signature: `graph.listVectorCollections()`
12
+
13
+ Return type: `Promise<ListVectorCollectionsResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /graph/vector/collections`
28
+
29
+ ## Path parameters
30
+
31
+ None.
32
+
33
+ ## Query parameters
34
+
35
+ None.
36
+
37
+ ## Body parameters
38
+
39
+ None.
40
+
41
+ Request model: None.
42
+
43
+ ## Request example
44
+
45
+ None declared in canonical OpenAPI.
46
+
47
+ ## Success responses
48
+
49
+ | Status | Shape | Content type | Description |
50
+ |---|---|---|---|
51
+ | `200` | [`ListVectorCollectionsResponse`](../models/ListVectorCollectionsResponse.md) | application/json | Configured collections with chunk count, vector width and metric |
52
+
53
+ ## Success response examples
54
+
55
+ ### 200
56
+
57
+ ```json
58
+ {
59
+ "collections": [
60
+ {
61
+ "available": true,
62
+ "chunk_count": 4211,
63
+ "collection": "medical_documents",
64
+ "detail": null,
65
+ "dimension": 384,
66
+ "metric_type": "COSINE",
67
+ "partitioned_by_payer": false,
68
+ "role": "documents"
69
+ }
70
+ ],
71
+ "embedding_model": "BAAI/bge-small-en-v1.5",
72
+ "total": 1
73
+ }
74
+ ```
75
+
76
+ ## Common errors
77
+
78
+ | Status | Shape | Content type | Description |
79
+ |---|---|---|---|
80
+ | `401` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
81
+ | `500` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Internal server error |
82
+ | `503` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Vector search is not configured in this environment |
83
+
84
+ ## Error examples
85
+
86
+ ### 401 — Missing or invalid access token
87
+
88
+ ```json
89
+ {
90
+ "error": "Authorization required"
91
+ }
92
+ ```
93
+
94
+ ### 500 — Unexpected service failure (sanitized example)
95
+
96
+ ```json
97
+ {
98
+ "error": "Internal server error"
99
+ }
100
+ ```
101
+
102
+ ### 503 — No Milvus endpoint or embedding key is provisioned
103
+
104
+ ```json
105
+ {
106
+ "error": "Vector search is not configured"
107
+ }
108
+ ```
109
+
110
+ ## NodeJS / TypeScript implementation
111
+
112
+ ```ts
113
+ import { HCSDK } from "@healthcloudai/hc-sdk";
114
+ ```
115
+
116
+ ```ts
117
+ const result = await graph.listVectorCollections();
118
+ ```
119
+
120
+ ## cURL
121
+
122
+ ```bash
123
+ curl -X GET \
124
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
125
+ 'https://dev-api-graph.health.cloud/graph/vector/collections'
126
+ ```
127
+
128
+ ## Notes
129
+
130
+ None.
131
+
132
+ ## Prepared Test Console scenario
133
+
134
+ No canonical scenario is currently associated.
135
+
136
+ ## Real response
137
+
138
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.