@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
@@ -0,0 +1,207 @@
1
+ # Semantic search over document chunks
2
+
3
+ Operation ID: `graph.vectorSearchDocuments`
4
+
5
+ Rank document chunks by semantic similarity to a natural-language query. The query is embedded server-side with the same model the collection was loaded with and matched by cosine similarity, so a question finds a document it shares no words with. Scope the search with collection (which corpus: consumer health topics or payer policies), then collection_group, source, language, network_id and tags within it. Searching the payer-policy collection requires payer_key: that corpus is partitioned by payer, so one search only ever returns one payer's policies.
6
+
7
+ ## Public method
8
+
9
+ `vectorSearchDocuments`
10
+
11
+ Signature: `graph.vectorSearchDocuments(request)`
12
+
13
+ Return type: `Promise<VectorSearchResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `POST /graph/vector/search`
28
+
29
+ ## Path parameters
30
+
31
+ None.
32
+
33
+ ## Query parameters
34
+
35
+ None.
36
+
37
+ ## Body parameters
38
+
39
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
40
+ |---|---|---:|---|---|---|---:|---|
41
+ | `body` | [`VectorSearchDocumentsRequest`](../models/VectorSearchDocumentsRequest.md) | Yes | | | | No | |
42
+
43
+ Request model: [`VectorSearchDocumentsRequest`](../models/VectorSearchDocumentsRequest.md)
44
+
45
+ ## Request example
46
+
47
+ ```json
48
+ {
49
+ "collection": "string",
50
+ "collection_group": "string",
51
+ "language": "string",
52
+ "network_id": "string",
53
+ "payer_key": "string",
54
+ "q": "string",
55
+ "source": "string",
56
+ "tags": [
57
+ "string"
58
+ ],
59
+ "top_k": 10
60
+ }
61
+ ```
62
+
63
+ ## Success responses
64
+
65
+ | Status | Shape | Content type | Description |
66
+ |---|---|---|---|
67
+ | `200` | [`VectorSearchResponse`](../models/VectorSearchResponse.md) | application/json | Ranked document chunks, closest first |
68
+
69
+ ## Success response examples
70
+
71
+ ### 200
72
+
73
+ ```json
74
+ {
75
+ "collection": "string",
76
+ "count": 0,
77
+ "embedding_model": "string",
78
+ "filter": "string",
79
+ "hits": [
80
+ {
81
+ "chunk_index": 0,
82
+ "collection_group": "string",
83
+ "doc_id": "string",
84
+ "id": "string",
85
+ "language": "string",
86
+ "metadata": {},
87
+ "network_id": "string",
88
+ "payer_key": "string",
89
+ "score": 0,
90
+ "source": "string",
91
+ "tags": [
92
+ "string"
93
+ ],
94
+ "text": "string",
95
+ "title": "string",
96
+ "url": "string"
97
+ }
98
+ ],
99
+ "query": "string"
100
+ }
101
+ ```
102
+
103
+ ## Common errors
104
+
105
+ | Status | Shape | Content type | Description |
106
+ |---|---|---|---|
107
+ | `400` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | The query was empty, the collection is not one this deployment serves, or a payer-partitioned collection was searched without a payer |
108
+ | `401` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
109
+ | `500` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Internal server error |
110
+ | `503` | [`graph.ErrorResponse`](../models/graph.ErrorResponse.md) | application/json | Vector search is not configured in this environment |
111
+
112
+ ## Error examples
113
+
114
+ ### 400 — The payer-policy collection was searched without naming a payer
115
+
116
+ ```json
117
+ {
118
+ "error": "payer_key is required when reading 'payer_policy_documents': it is partitioned by payer, so a read must name exactly one payer."
119
+ }
120
+ ```
121
+
122
+ ### 400 — The required 'q' field was empty
123
+
124
+ ```json
125
+ {
126
+ "error": "Field 'q' is required"
127
+ }
128
+ ```
129
+
130
+ ### 400 — The requested collection is not configured
131
+
132
+ ```json
133
+ {
134
+ "error": "Unknown collection 'nope'. Available: medical_documents, payer_policy_documents"
135
+ }
136
+ ```
137
+
138
+ ### 401 — Missing or invalid access token
139
+
140
+ ```json
141
+ {
142
+ "error": "Authorization required"
143
+ }
144
+ ```
145
+
146
+ ### 500 — Unexpected service failure (sanitized example)
147
+
148
+ ```json
149
+ {
150
+ "error": "Internal server error"
151
+ }
152
+ ```
153
+
154
+ ### 503 — No Milvus endpoint or embedding key is provisioned
155
+
156
+ ```json
157
+ {
158
+ "error": "Vector search is not configured"
159
+ }
160
+ ```
161
+
162
+ ## NodeJS / TypeScript implementation
163
+
164
+ ```ts
165
+ import { HCSDK } from "@healthcloudai/hc-sdk";
166
+ import type { VectorSearchRequest } from "@healthcloudai/hc-sdk";
167
+ ```
168
+
169
+ ```ts
170
+ const request = {
171
+ "collection": "string",
172
+ "collection_group": "string",
173
+ "language": "string",
174
+ "network_id": "string",
175
+ "payer_key": "string",
176
+ "q": "string",
177
+ "source": "string",
178
+ "tags": [
179
+ "string"
180
+ ],
181
+ "top_k": 10
182
+ };
183
+
184
+ const result = await graph.vectorSearchDocuments(request);
185
+ ```
186
+
187
+ ## cURL
188
+
189
+ ```bash
190
+ curl -X POST \
191
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
192
+ -H 'Content-Type: application/json' \
193
+ -d '{"collection":"string","collection_group":"string","language":"string","network_id":"string","payer_key":"string","q":"string","source":"string","tags":["string"],"top_k":10}' \
194
+ 'https://dev-api-graph.health.cloud/graph/vector/search'
195
+ ```
196
+
197
+ ## Notes
198
+
199
+ None.
200
+
201
+ ## Prepared Test Console scenario
202
+
203
+ No canonical scenario is currently associated.
204
+
205
+ ## Real response
206
+
207
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -46,11 +46,12 @@ Request model: [`AddInsuranceRequest`](../models/AddInsuranceRequest.md)
46
46
 
47
47
  ```json
48
48
  {
49
- "member_id": "MEM-example-001",
50
- "payer_id": "60054",
51
- "payer_name": "Example Health Plan",
49
+ "member_id": "string",
50
+ "payer_id": "string",
51
+ "payer_name": "string",
52
52
  "priority": "primary",
53
- "relationship": "self"
53
+ "relationship": "self",
54
+ "state": "string"
54
55
  }
55
56
  ```
56
57
 
@@ -121,11 +122,12 @@ import type { CreateInsuranceRequest } from "@healthcloudai/hc-sdk";
121
122
 
122
123
  ```ts
123
124
  const request = {
124
- "member_id": "MEM-example-001",
125
- "payer_id": "60054",
126
- "payer_name": "Example Health Plan",
125
+ "member_id": "string",
126
+ "payer_id": "string",
127
+ "payer_name": "string",
127
128
  "priority": "primary",
128
- "relationship": "self"
129
+ "relationship": "self",
130
+ "state": "string"
129
131
  };
130
132
 
131
133
  const result = await patient.createInsurance(request);
@@ -137,7 +139,7 @@ const result = await patient.createInsurance(request);
137
139
  curl -X POST \
138
140
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
139
141
  -H 'Content-Type: application/json' \
140
- -d '{"member_id":"MEM-example-001","payer_id":"60054","payer_name":"Example Health Plan","priority":"primary","relationship":"self"}' \
142
+ -d '{"member_id":"string","payer_id":"string","payer_name":"string","priority":"primary","relationship":"self","state":"string"}' \
141
143
  'https://dev-api-patient.health.cloud/patients/insurance'
142
144
  ```
143
145
 
@@ -46,8 +46,8 @@ Request model: [`CheckEncounterRequest`](../models/CheckEncounterRequest.md)
46
46
 
47
47
  ```json
48
48
  {
49
- "notes": "string",
50
- "patient_id": "string"
49
+ "notes": "Synthetic visit note",
50
+ "patient_id": "patient-example-001"
51
51
  }
52
52
  ```
53
53
 
@@ -55,14 +55,100 @@ Request model: [`CheckEncounterRequest`](../models/CheckEncounterRequest.md)
55
55
 
56
56
  | Status | Shape | Content type | Description |
57
57
  |---|---|---|---|
58
- | `200` | `object` | application/json | Current or newly created encounter, with Athena walk-in status |
58
+ | `200` | [`CheckEncounterResponse`](../models/CheckEncounterResponse.md) | application/json | Current or newly created encounter, with Athena walk-in status |
59
59
 
60
60
  ## Success response examples
61
61
 
62
62
  ### 200
63
63
 
64
64
  ```json
65
- {}
65
+ {
66
+ "athena_appointment_id": "athena-appointment-example-001",
67
+ "athena_encounter_error": null,
68
+ "athena_encounter_id": "athena-encounter-example-001",
69
+ "athena_encounter_status": "linked",
70
+ "athena_insurance_error": null,
71
+ "athena_insurance_status": "linked",
72
+ "athena_patient_id": "athena-patient-example-001",
73
+ "created": true,
74
+ "encounter": {
75
+ "appointment_id": "appointment-example-001",
76
+ "athena_appointment_id": null,
77
+ "athena_encounter_id": null,
78
+ "created_by": "self",
79
+ "created_date": "2026-08-10T23:36:57Z",
80
+ "diagnoses": [
81
+ {
82
+ "condition_display": "Acute upper respiratory infection",
83
+ "condition_id": "condition-example-001",
84
+ "rank": 1,
85
+ "use_code": "AD"
86
+ }
87
+ ],
88
+ "encounter_class": "AMB",
89
+ "encounter_id": "167dd34e-1833-4260-a8b1-ea0b38229a1b",
90
+ "fhir_id": "6e0d484f-4f8b-4025-b6ef-abedf69f0f91",
91
+ "hospitalization": {
92
+ "admit_source_code": "physician-referral",
93
+ "destination_id": "location-example-002",
94
+ "discharge_disposition": "home",
95
+ "origin_id": "location-example-001",
96
+ "pre_admission_id": "encounter-example-prior",
97
+ "re_admission_code": "N"
98
+ },
99
+ "length_minutes": 30,
100
+ "locations": [
101
+ {
102
+ "location_display": "Example Clinic, Room 101",
103
+ "location_id": "location-example-001",
104
+ "period_end": "2026-08-10T10:30:00Z",
105
+ "period_start": "2026-08-10T10:00:00Z",
106
+ "status": "completed"
107
+ }
108
+ ],
109
+ "notes": null,
110
+ "openloop_appointment_id": null,
111
+ "openloop_encounter_id": null,
112
+ "participants": [
113
+ {
114
+ "participant_type": "ATND",
115
+ "period_end": "2026-08-10T10:30:00Z",
116
+ "period_start": "2026-08-10T10:00:00Z",
117
+ "practitioner_display": "Dr. Alex Smith",
118
+ "practitioner_id": "provider-example-001"
119
+ }
120
+ ],
121
+ "patient_id": "patient-example-001",
122
+ "period_end": "2026-08-10T10:30:00Z",
123
+ "period_start": "2026-08-10T10:00:00Z",
124
+ "priority_code": "R",
125
+ "priority_display": "Routine",
126
+ "reason_code": "386661006",
127
+ "reason_display": "Fever",
128
+ "service_provider_display": "Example Health Clinic",
129
+ "service_provider_id": "organization-example-001",
130
+ "service_type_code": "124",
131
+ "service_type_display": "General practice",
132
+ "status": "finished",
133
+ "steadymd_consult_guid": null,
134
+ "steadymd_episode_guid": null,
135
+ "type_code": "99213",
136
+ "type_display": "Office outpatient visit"
137
+ },
138
+ "notes_athena_sections": {
139
+ "status": "linked"
140
+ },
141
+ "notes_fhir_error": null,
142
+ "notes_fhir_status": "linked",
143
+ "openloop_appointment_id": null,
144
+ "openloop_encounter_error": null,
145
+ "openloop_encounter_id": null,
146
+ "openloop_encounter_status": "skipped_no_openloop",
147
+ "steadymd_consult_guid": null,
148
+ "steadymd_encounter_error": null,
149
+ "steadymd_encounter_status": "skipped_no_steadymd",
150
+ "steadymd_episode_guid": null
151
+ }
66
152
  ```
67
153
 
68
154
  ## Common errors
@@ -82,8 +168,8 @@ import type { CheckEncounterRequest } from "@healthcloudai/hc-sdk";
82
168
 
83
169
  ```ts
84
170
  const request = {
85
- "notes": "string",
86
- "patient_id": "string"
171
+ "notes": "Synthetic visit note",
172
+ "patient_id": "patient-example-001"
87
173
  };
88
174
 
89
175
  const result = await patient.checkEncounter(request);
@@ -95,7 +181,7 @@ const result = await patient.checkEncounter(request);
95
181
  curl -X POST \
96
182
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
97
183
  -H 'Content-Type: application/json' \
98
- -d '{"notes":"string","patient_id":"string"}' \
184
+ -d '{"notes":"Synthetic visit note","patient_id":"patient-example-001"}' \
99
185
  'https://dev-api-patient.health.cloud/encounters/check'
100
186
  ```
101
187
 
@@ -56,14 +56,80 @@ Request model: [`CheckInEncounterRequest`](../models/CheckInEncounterRequest.md)
56
56
 
57
57
  | Status | Shape | Content type | Description |
58
58
  |---|---|---|---|
59
- | `200` | `object` | application/json | Encounter checked in and linked to the EHR encounter, plus athena_patient_id |
59
+ | `200` | [`CheckInEncounterResponse`](../models/CheckInEncounterResponse.md) | application/json | Encounter checked in and linked to the EHR encounter, plus athena_patient_id |
60
60
 
61
61
  ## Success response examples
62
62
 
63
63
  ### 200
64
64
 
65
65
  ```json
66
- {}
66
+ {
67
+ "appointment_id": "string",
68
+ "athena_appointment_id": "string",
69
+ "athena_encounter_id": "string",
70
+ "athena_patient_id": "string",
71
+ "created_by": "self",
72
+ "created_date": "2026-01-01T09:00:00Z",
73
+ "diagnoses": [
74
+ {
75
+ "condition_display": "string",
76
+ "condition_id": "string",
77
+ "rank": 1,
78
+ "use_code": "CC"
79
+ }
80
+ ],
81
+ "encounter_class": "AMB",
82
+ "encounter_id": "00000000-0000-0000-0000-000000000000",
83
+ "fhir_id": "string",
84
+ "hospitalization": {
85
+ "admit_source_code": "string",
86
+ "destination_id": "string",
87
+ "discharge_disposition": "home",
88
+ "origin_id": "string",
89
+ "pre_admission_id": "string",
90
+ "re_admission_code": "string"
91
+ },
92
+ "length_minutes": 0,
93
+ "locations": [
94
+ {
95
+ "location_display": "string",
96
+ "location_id": "string",
97
+ "period_end": "2026-01-01T09:00:00Z",
98
+ "period_start": "2026-01-01T09:00:00Z",
99
+ "status": "active"
100
+ }
101
+ ],
102
+ "notes": "string",
103
+ "openloop_appointment_id": "string",
104
+ "openloop_encounter_id": "string",
105
+ "openloop_encounter_status": "linked",
106
+ "openloop_patient_id": "string",
107
+ "participants": [
108
+ {
109
+ "participant_type": "PPRF",
110
+ "period_end": "2026-01-01T09:00:00Z",
111
+ "period_start": "2026-01-01T09:00:00Z",
112
+ "practitioner_display": "string",
113
+ "practitioner_id": "string"
114
+ }
115
+ ],
116
+ "patient_id": "string",
117
+ "period_end": "2026-01-01T09:00:00Z",
118
+ "period_start": "2026-01-01T09:00:00Z",
119
+ "priority_code": "string",
120
+ "priority_display": "string",
121
+ "reason_code": "string",
122
+ "reason_display": "string",
123
+ "service_provider_display": "string",
124
+ "service_provider_id": "string",
125
+ "service_type_code": "string",
126
+ "service_type_display": "string",
127
+ "status": "planned",
128
+ "steadymd_consult_guid": "string",
129
+ "steadymd_episode_guid": "string",
130
+ "type_code": "string",
131
+ "type_display": "string"
132
+ }
67
133
  ```
68
134
 
69
135
  ## Common errors
@@ -56,7 +56,19 @@ None declared in canonical OpenAPI.
56
56
 
57
57
  ```json
58
58
  {
59
- "preferred_pharmacy": null
59
+ "active": true,
60
+ "address": [
61
+ {}
62
+ ],
63
+ "id": "string",
64
+ "identifier": [
65
+ {}
66
+ ],
67
+ "name": "string",
68
+ "resourceType": "Organization",
69
+ "telecom": [
70
+ {}
71
+ ]
60
72
  }
61
73
  ```
62
74
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-sdk",
3
- "version": "3.3.0",
3
+ "version": "3.5.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",