@healthcloudai/hc-sdk 3.26.0 → 3.28.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 +78 -3
  2. package/dist/index.d.cts +869 -338
  3. package/dist/index.d.ts +869 -338
  4. package/dist/index.js +78 -3
  5. package/docs/clients/PatientClient.md +1 -0
  6. package/docs/docs-manifest.json +9 -3
  7. package/docs/examples/index.md +1 -0
  8. package/docs/index.md +1 -0
  9. package/docs/models/CheckInEncounterResponse.md +1 -1
  10. package/docs/models/CheckInsuranceBenefitsRequest.md +19 -0
  11. package/docs/models/CheckInsuranceBenefitsResponse.md +28 -0
  12. package/docs/models/GetEncounterResponse.md +1 -1
  13. package/docs/models/InsuranceBenefit.md +27 -0
  14. package/docs/models/ProviderEncounterRecord.md +3 -1
  15. package/docs/models/ProviderIntakeContent.md +25 -0
  16. package/docs/models/ProviderIntakeSubmission.md +29 -0
  17. package/docs/models/ProviderPatientRecordResources.md +1 -1
  18. package/docs/models/ProviderQueueEncounter.md +1 -0
  19. package/docs/models/UpdateEncounterClinicalNoteRequest.md +2 -1
  20. package/docs/models/fieldagent.Encounter.md +1 -1
  21. package/docs/models/index.md +5 -0
  22. package/docs/models/patient.Encounter.md +1 -1
  23. package/docs/models/provider.Encounter.md +1 -1
  24. package/docs/operations/patient.checkPatientInsuranceBenefits.md +209 -0
  25. package/docs/operations/patient.listPatientInsuranceClaims.md +3 -1
  26. package/docs/operations/provider.claimEncounter.md +2 -0
  27. package/docs/operations/provider.getEncounter.md +2 -0
  28. package/docs/operations/provider.getEncounterQueue.md +1 -0
  29. package/docs/operations/provider.getPatientRecord.md +54 -0
  30. package/docs/operations/provider.listEncounters.md +2 -0
  31. package/docs/operations/provider.signEncounter.md +2 -0
  32. package/docs/operations/provider.updateEncounterClinicalNote.md +2 -0
  33. package/docs/operations/provider.updateEncounterDiagnoses.md +2 -0
  34. package/docs/operations/provider.updateEncounterStatus.md +2 -0
  35. package/package.json +1 -1
@@ -0,0 +1,209 @@
1
+ # Check reported insurance benefits
2
+
3
+ Operation ID: `patient.checkPatientInsuranceBenefits`
4
+
5
+ Check reported copay, coinsurance, deductible and out-of-pocket benefits for one X12 STC. Requires a PATIENT-pool Bearer JWT; identity and tenant come from the token. Uses saved name/DOB and exactly one active primary self Coverage. The Stedi key and requesting NPI are resolved server-side. Calls Stedi POST /2026-06-01/eligibility-check once with a 12-second timeout and no redirects. Omit service_date for the payer current date. No STC 30 fallback or inferred amounts. Entries retain plan, coverage level, network, period and benefit dates; null amounts remain unknown. coinsurance_fraction is a decimal fraction (0.2 means 20%). additional_conditions flags payer restrictions that require review; free-form payer messages are not exposed. Reported network applicability does not verify clinician participation, and benefits are not a final price. Persist request_id and the exact request body. A FHIR Task is conditionally created before Stedi I/O. Replay returns the saved result without another Stedi call; a changed body returns 409. An uncertain write remains pending and needs reconciliation; never automatically generate a new ID after a timeout or pending result, since that could cause another billable vendor check.
6
+
7
+ ## Public method
8
+
9
+ `checkInsuranceBenefits`
10
+
11
+ Signature: `patient.checkInsuranceBenefits(request)`
12
+
13
+ Return type: `Promise<CheckInsuranceBenefitsResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ - A PATIENT-pool access token and exactly one saved active primary self Coverage with complete saved demographics.
24
+ - The server's Stedi key and tenant-specific requesting NPI are configured; neither is a request parameter.
25
+
26
+ ## HTTP
27
+
28
+ `POST /insurance/benefits/check`
29
+
30
+ ## Path parameters
31
+
32
+ None.
33
+
34
+ ## Query parameters
35
+
36
+ None.
37
+
38
+ ## Body parameters
39
+
40
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
41
+ |---|---|---:|---|---|---|---:|---|
42
+ | `body` | [`CheckInsuranceBenefitsRequest`](../models/CheckInsuranceBenefitsRequest.md) | Yes | | | | No | |
43
+
44
+ Request model: [`CheckInsuranceBenefitsRequest`](../models/CheckInsuranceBenefitsRequest.md)
45
+
46
+ ## Request example
47
+
48
+ None declared in canonical OpenAPI.
49
+
50
+ ## Success responses
51
+
52
+ | Status | Shape | Content type | Description |
53
+ |---|---|---|---|
54
+ | `200` | [`CheckInsuranceBenefitsResponse`](../models/CheckInsuranceBenefitsResponse.md) | application/json | Persisted result. Inspect status/reason: completed is a reported result, unavailable is not ineligible coverage. |
55
+ | `202` | [`CheckInsuranceBenefitsResponse`](../models/CheckInsuranceBenefitsResponse.md) | application/json | Outcome pending. Replay the same request ID/body; no automatic vendor re-dispatch. |
56
+
57
+ ## Success response examples
58
+
59
+ ### 200
60
+
61
+ ```json
62
+ {
63
+ "benefits": [
64
+ {
65
+ "additional_conditions": false,
66
+ "benefit_end": "2026-01-01",
67
+ "benefit_start": "2026-01-01",
68
+ "benefit_type": "copay",
69
+ "coverage_level": "CHILDREN_ONLY",
70
+ "network": "IN_NETWORK",
71
+ "plan_index": 0,
72
+ "service_type_code": "string",
73
+ "time_period": "HOUR"
74
+ }
75
+ ],
76
+ "check_id": "00000000-0000-0000-0000-000000000000",
77
+ "checked_at": "2026-01-01T09:00:00Z",
78
+ "coverage_id": "string",
79
+ "endpoint_version": "2026-06-01",
80
+ "interpretation": "reported_benefits_not_final_price",
81
+ "network_determination": "unknown",
82
+ "reason": "active_coverage",
83
+ "service_date": "2026-01-01",
84
+ "service_type_code": "string",
85
+ "source": "stedi",
86
+ "status": "completed"
87
+ }
88
+ ```
89
+
90
+ ### 202
91
+
92
+ ```json
93
+ {
94
+ "benefits": [
95
+ {
96
+ "additional_conditions": false,
97
+ "benefit_end": "2026-01-01",
98
+ "benefit_start": "2026-01-01",
99
+ "benefit_type": "copay",
100
+ "coverage_level": "CHILDREN_ONLY",
101
+ "network": "IN_NETWORK",
102
+ "plan_index": 0,
103
+ "service_type_code": "string",
104
+ "time_period": "HOUR"
105
+ }
106
+ ],
107
+ "check_id": "00000000-0000-0000-0000-000000000000",
108
+ "checked_at": "2026-01-01T09:00:00Z",
109
+ "coverage_id": "string",
110
+ "endpoint_version": "2026-06-01",
111
+ "interpretation": "reported_benefits_not_final_price",
112
+ "network_determination": "unknown",
113
+ "reason": "active_coverage",
114
+ "service_date": "2026-01-01",
115
+ "service_type_code": "string",
116
+ "source": "stedi",
117
+ "status": "completed"
118
+ }
119
+ ```
120
+
121
+ ## Common errors
122
+
123
+ | Status | Shape | Content type | Description |
124
+ |---|---|---|---|
125
+ | `401` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Authorization required — missing, invalid, expired, or non-patient Bearer JWT |
126
+ | `404` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The authenticated patient has no FHIR Patient record |
127
+ | `409` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The request ID already belongs to a different body |
128
+ | `422` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Invalid UUID, STC or ISO date, missing required fields, non-object body or extra fields |
129
+ | `503` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The durable check journal is unavailable. Replay the same request ID/body. |
130
+
131
+ ## Error examples
132
+
133
+ ### 401 — Missing or invalid access token
134
+
135
+ ```json
136
+ {
137
+ "error": "Authorization required"
138
+ }
139
+ ```
140
+
141
+ ### 404 — Patient not found
142
+
143
+ ```json
144
+ {
145
+ "error": "Patient not found"
146
+ }
147
+ ```
148
+
149
+ ### 409 — Changed request body
150
+
151
+ ```json
152
+ {
153
+ "error": "request_id was already used for a different check"
154
+ }
155
+ ```
156
+
157
+ ### 422 — Invalid request
158
+
159
+ ```json
160
+ {
161
+ "error": "Invalid insurance benefits request"
162
+ }
163
+ ```
164
+
165
+ ### 503 — Storage unavailable
166
+
167
+ ```json
168
+ {
169
+ "error": "Insurance benefits service is unavailable"
170
+ }
171
+ ```
172
+
173
+ ## NodeJS / TypeScript implementation
174
+
175
+ ```ts
176
+ import { HCSDK } from "@healthcloudai/hc-sdk";
177
+ ```
178
+
179
+ ```ts
180
+ const request = "<REQUEST>";
181
+
182
+ const result = await patient.checkInsuranceBenefits(request);
183
+ ```
184
+
185
+ ## cURL
186
+
187
+ ```bash
188
+ curl -X POST \
189
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
190
+ -H 'Content-Type: application/json' \
191
+ -d '<REQUEST_BODY_JSON>' \
192
+ 'https://dev-api-patient.health.cloud/insurance/benefits/check'
193
+ ```
194
+
195
+ ## Notes
196
+
197
+ - npm: patient.checkInsuranceBenefits(request). Python: patient.check_insurance_benefits(request). Persist the request_id and exact body before sending.
198
+ - HTTP 202 is a typed pending outcome. Replay the original ID/body to read the saved result. Never automatically generate another ID after a timeout, pending result or uncertain storage failure.
199
+ - Entries preserve individual/family, network applicability, annual/remaining period and plan separately. Missing amounts are unknown, not zero. coinsurance_fraction of 0.20 means 20%.
200
+ - Reported benefits do not establish a final patient charge or clinician network participation. additional_conditions flags payer restrictions that require review.
201
+ - Omit service_date for the payer's current date. Standard Stedi medical mock requests support only service_type_code 30 and require the published exact test subscriber values and a test-mode key.
202
+
203
+ ## Prepared Test Console scenario
204
+
205
+ No canonical scenario is currently associated.
206
+
207
+ ## Real response
208
+
209
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -173,7 +173,9 @@ curl -X GET \
173
173
 
174
174
  ## Notes
175
175
 
176
- None.
176
+ - npm: patient.listInsuranceClaims(query). Python: patient.list_insurance_claims(page_size=..., page_token=...). Existing Patient SDK methods and patient-owned FHIR Claim linkage are reused.
177
+ - Stedi statuses pass through unchanged: SUBMITTED, RECEIVED, ACCEPTED, REJECTED, PROCESSED, DENIED and UNKNOWN. PROCESSED means adjudicated and does not establish payment.
178
+ - No paid amount or patient responsibility is inferred from missing claim data. An empty owned collection is a successful response and does not establish a live Stedi claim-status readback.
177
179
 
178
180
  ## Prepared Test Console scenario
179
181
 
@@ -132,8 +132,10 @@ None declared in canonical OpenAPI.
132
132
  "period_start": "2026-01-01T09:00:00Z",
133
133
  "priority_code": "string",
134
134
  "priority_display": "string",
135
+ "provider_notes": "string",
135
136
  "reason_code": "string",
136
137
  "reason_display": "string",
138
+ "reported_symptoms": "string",
137
139
  "service_provider_display": "string",
138
140
  "service_provider_id": "string",
139
141
  "service_type_code": "string",
@@ -130,8 +130,10 @@ None declared in canonical OpenAPI.
130
130
  "period_start": "2026-01-01T09:00:00Z",
131
131
  "priority_code": "string",
132
132
  "priority_display": "string",
133
+ "provider_notes": "string",
133
134
  "reason_code": "string",
134
135
  "reason_display": "string",
136
+ "reported_symptoms": "string",
135
137
  "service_provider_display": "string",
136
138
  "service_provider_id": "string",
137
139
  "service_type_code": "string",
@@ -73,6 +73,7 @@ None declared in canonical OpenAPI.
73
73
  "priority_display": "string",
74
74
  "reason_code": "string",
75
75
  "reason_display": "string",
76
+ "reported_symptoms": "string",
76
77
  "status": "string",
77
78
  "type_code": "string",
78
79
  "type_display": "string"
@@ -339,8 +339,62 @@ None declared in canonical OpenAPI.
339
339
  ],
340
340
  "intake_submissions": [
341
341
  {
342
+ "content": {
343
+ "allergies": [],
344
+ "conditions": [
345
+ {
346
+ "categories": [],
347
+ "clinical_status": "active",
348
+ "description": "string",
349
+ "problem_id": "00000000-0000-0000-0000-000000000000",
350
+ "verification_status": "confirmed"
351
+ }
352
+ ],
353
+ "family_history": [],
354
+ "gyn_history": [
355
+ {
356
+ "history_id": "00000000-0000-0000-0000-000000000000"
357
+ }
358
+ ],
359
+ "immunizations": [
360
+ {
361
+ "immunization_id": "00000000-0000-0000-0000-000000000000",
362
+ "reactions": [],
363
+ "reason_codes": [],
364
+ "status": "completed",
365
+ "vaccine_name": "string"
366
+ }
367
+ ],
368
+ "medications": [],
369
+ "perinatal_history": [
370
+ {
371
+ "history_id": "00000000-0000-0000-0000-000000000000"
372
+ }
373
+ ],
374
+ "procedures": [
375
+ {
376
+ "body_sites": [],
377
+ "complications": [],
378
+ "description": "string",
379
+ "procedure_id": "00000000-0000-0000-0000-000000000000",
380
+ "reported": false,
381
+ "status": "completed"
382
+ }
383
+ ],
384
+ "social_history": [
385
+ {
386
+ "occupational_exposures": [],
387
+ "substances": [],
388
+ "travel_history": []
389
+ }
390
+ ]
391
+ },
392
+ "content_complete": true,
342
393
  "created_at": "2026-01-01T09:00:00Z",
343
394
  "invalid_entries": {},
395
+ "sections": [
396
+ "string"
397
+ ],
344
398
  "storage_status": "pending",
345
399
  "submission_id": "00000000-0000-0000-0000-000000000000",
346
400
  "unknown_fields": [
@@ -132,8 +132,10 @@ None declared in canonical OpenAPI.
132
132
  "period_start": "2026-01-01T09:00:00Z",
133
133
  "priority_code": "string",
134
134
  "priority_display": "string",
135
+ "provider_notes": "string",
135
136
  "reason_code": "string",
136
137
  "reason_display": "string",
138
+ "reported_symptoms": "string",
137
139
  "service_provider_display": "string",
138
140
  "service_provider_id": "string",
139
141
  "service_type_code": "string",
@@ -131,8 +131,10 @@ None declared in canonical OpenAPI.
131
131
  "period_start": "2026-01-01T09:00:00Z",
132
132
  "priority_code": "string",
133
133
  "priority_display": "string",
134
+ "provider_notes": "string",
134
135
  "reason_code": "string",
135
136
  "reason_display": "string",
137
+ "reported_symptoms": "string",
136
138
  "service_provider_display": "string",
137
139
  "service_provider_id": "string",
138
140
  "service_type_code": "string",
@@ -138,8 +138,10 @@ Request model: [`UpdateEncounterClinicalNoteRequest`](../models/UpdateEncounterC
138
138
  "period_start": "2026-01-01T09:00:00Z",
139
139
  "priority_code": "string",
140
140
  "priority_display": "string",
141
+ "provider_notes": "string",
141
142
  "reason_code": "string",
142
143
  "reason_display": "string",
144
+ "reported_symptoms": "string",
143
145
  "service_provider_display": "string",
144
146
  "service_provider_id": "string",
145
147
  "service_type_code": "string",
@@ -143,8 +143,10 @@ Request model: [`UpdateEncounterDiagnosesRequest`](../models/UpdateEncounterDiag
143
143
  "period_start": "2026-01-01T09:00:00Z",
144
144
  "priority_code": "string",
145
145
  "priority_display": "string",
146
+ "provider_notes": "string",
146
147
  "reason_code": "string",
147
148
  "reason_display": "string",
149
+ "reported_symptoms": "string",
148
150
  "service_provider_display": "string",
149
151
  "service_provider_id": "string",
150
152
  "service_type_code": "string",
@@ -137,8 +137,10 @@ Request model: [`UpdateEncounterStatusRequest`](../models/UpdateEncounterStatusR
137
137
  "period_start": "2026-01-01T09:00:00Z",
138
138
  "priority_code": "string",
139
139
  "priority_display": "string",
140
+ "provider_notes": "string",
140
141
  "reason_code": "string",
141
142
  "reason_display": "string",
143
+ "reported_symptoms": "string",
142
144
  "service_provider_display": "string",
143
145
  "service_provider_id": "string",
144
146
  "service_type_code": "string",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-sdk",
3
- "version": "3.26.0",
3
+ "version": "3.28.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",