@nexalink/coding-contracts 0.2.0 → 0.4.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 (21) hide show
  1. package/README.md +48 -8
  2. package/dist/cjs/index.cjs +4756 -76
  3. package/dist/index.d.ts +1090 -3
  4. package/dist/index.js +4728 -75
  5. package/package.json +8 -2
  6. package/schemas/coding-batch.schema.json +63 -0
  7. package/schemas/coding-case-clinical.schema.json +428 -0
  8. package/schemas/coding-case-context.schema.json +128 -0
  9. package/schemas/coding-case-payer.schema.json +126 -0
  10. package/schemas/coding-case.schema.json +97 -0
  11. package/schemas/coding-decision-line.schema.json +172 -0
  12. package/schemas/coding-decision.schema.json +430 -0
  13. package/schemas/coding-evidence.schema.json +100 -0
  14. package/schemas/coding-extension.schema.json +36 -0
  15. package/schemas/coding-reviewer-action.schema.json +64 -0
  16. package/schemas/coding-rule-result.schema.json +90 -0
  17. package/schemas/coding-service-line.schema.json +120 -0
  18. package/schemas/rcm-reviewer-event.schema.json +160 -0
  19. package/schemas/rcm-workflow-catalog.schema.json +62 -5
  20. package/versions.json +67 -2
  21. package/workflow-constants.json +2 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nexalink/coding-contracts",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Versioned TypeScript types, validators, constants, and JSON Schemas for CareCompass coding workflows.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -32,8 +32,10 @@
32
32
  "contracts:check": "bun scripts/codegen.ts --check",
33
33
  "format": "bunx prettier --write --ignore-unknown .",
34
34
  "format:check": "bunx prettier --check --ignore-unknown .",
35
+ "lint": "bunx eslint .",
35
36
  "test": "bun test",
36
37
  "test:python": "PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=python .venv/bin/python -m pytest -p no:cacheprovider python/tests",
38
+ "tidy": "bun run format && bun run lint",
37
39
  "audit": "bun audit",
38
40
  "verify:package": "bun scripts/verify-package.mjs",
39
41
  "pack:dry-run": "bun run build && bun run verify:package && bun pm pack --dry-run --ignore-scripts",
@@ -43,8 +45,12 @@
43
45
  "zod": "^4.4.3"
44
46
  },
45
47
  "devDependencies": {
48
+ "@eslint/js": "^10.0.1",
49
+ "eslint": "^10.12.0",
50
+ "globals": "^17.13.0",
46
51
  "prettier": "3.8.1",
47
- "typescript": "^5.9.2"
52
+ "typescript": "^5.9.2",
53
+ "typescript-eslint": "^8.71.0"
48
54
  },
49
55
  "publishConfig": {
50
56
  "access": "public",
package/schemas/coding-batch.schema.json ADDED
@@ -0,0 +1,63 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://nexalink.care/contracts/coding-batch.schema.json",
4
+ "title": "CodingBatch",
5
+ "description": "A bounded batch envelope carrying CodingCase instances for batch review. Batch size is capped so one execution remains within runtime limits; unbounded or streaming workloads are out of scope for this envelope.",
6
+ "version": "1.0.0",
7
+ "x-wire-version": "coding-batch-v1",
8
+ "x-wire-constant": "CODING_BATCH_SCHEMA_VERSION",
9
+ "x-code": "coding_batch",
10
+ "x-keys-code": "coding_batch_keys",
11
+ "type": "object",
12
+ "additionalProperties": false,
13
+ "required": ["batchId", "intent", "cases", "createdAt"],
14
+ "properties": {
15
+ "batchId": {
16
+ "type": "string",
17
+ "minLength": 1,
18
+ "maxLength": 128,
19
+ "x-code": "batch_id"
20
+ },
21
+ "tenantReference": {
22
+ "type": "string",
23
+ "minLength": 1,
24
+ "maxLength": 128,
25
+ "x-code": "batch_tenant_reference"
26
+ },
27
+ "intent": {
28
+ "type": "string",
29
+ "const": "batch_review",
30
+ "x-code": "batch_intent"
31
+ },
32
+ "cases": {
33
+ "type": "array",
34
+ "minItems": 1,
35
+ "maxItems": 100,
36
+ "x-code": "batch_cases",
37
+ "items": {
38
+ "$ref": "coding-case.schema.json"
39
+ }
40
+ },
41
+ "createdBy": {
42
+ "type": "string",
43
+ "minLength": 1,
44
+ "maxLength": 128,
45
+ "x-code": "batch_created_by"
46
+ },
47
+ "createdAt": {
48
+ "type": "string",
49
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
50
+ "format": "date-time",
51
+ "maxLength": 64,
52
+ "x-code": "batch_created_at"
53
+ },
54
+ "extensions": {
55
+ "type": "array",
56
+ "maxItems": 25,
57
+ "x-code": "batch_extensions",
58
+ "items": {
59
+ "$ref": "coding-extension.schema.json"
60
+ }
61
+ }
62
+ }
63
+ }
package/schemas/coding-case-clinical.schema.json ADDED
@@ -0,0 +1,428 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://nexalink.care/contracts/coding-case-clinical.schema.json",
4
+ "title": "CodingCaseClinical",
5
+ "description": "Structured clinical and operational facts: diagnoses, procedures, medications, supplies, time entries, notes, and source references. Time entries keep duration and activity structured so workflows such as monthly multi-activity time aggregation never depend on free text for calculations.",
6
+ "version": "1.0.0",
7
+ "x-wire-version": "coding-case-clinical-v1",
8
+ "x-wire-constant": "CODING_CASE_CLINICAL_SCHEMA_VERSION",
9
+ "x-code": "clinical",
10
+ "x-keys-code": "clinical_keys",
11
+ "type": "object",
12
+ "additionalProperties": false,
13
+ "properties": {
14
+ "diagnoses": {
15
+ "type": "array",
16
+ "maxItems": 100,
17
+ "x-code": "clinical_diagnoses",
18
+ "items": {
19
+ "type": "object",
20
+ "additionalProperties": false,
21
+ "required": ["diagnosisId"],
22
+ "x-code": "clinical_diagnosis",
23
+ "x-keys-code": "clinical_diagnosis_keys",
24
+ "properties": {
25
+ "diagnosisId": {
26
+ "type": "string",
27
+ "minLength": 1,
28
+ "maxLength": 60,
29
+ "x-code": "clinical_diagnosis_id"
30
+ },
31
+ "code": {
32
+ "type": "string",
33
+ "minLength": 1,
34
+ "maxLength": 32,
35
+ "x-code": "clinical_diagnosis_code"
36
+ },
37
+ "codeSystem": {
38
+ "type": "string",
39
+ "enum": ["ICD-10-CM", "ICD-9-CM", "OTHER"],
40
+ "x-code": "clinical_diagnosis_code_system"
41
+ },
42
+ "codeVersion": {
43
+ "type": "string",
44
+ "minLength": 1,
45
+ "maxLength": 40,
46
+ "x-code": "clinical_diagnosis_code_version"
47
+ },
48
+ "description": {
49
+ "type": "string",
50
+ "minLength": 1,
51
+ "maxLength": 240,
52
+ "x-code": "clinical_diagnosis_description"
53
+ },
54
+ "diagnosisType": {
55
+ "type": "string",
56
+ "enum": ["principal", "secondary", "complication", "other"],
57
+ "x-code": "clinical_diagnosis_type"
58
+ },
59
+ "onsetDate": {
60
+ "type": "string",
61
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
62
+ "format": "date",
63
+ "x-code": "clinical_diagnosis_onset_date"
64
+ },
65
+ "presentOnAdmission": {
66
+ "type": "boolean",
67
+ "x-code": "clinical_diagnosis_present_on_admission"
68
+ }
69
+ }
70
+ }
71
+ },
72
+ "procedures": {
73
+ "type": "array",
74
+ "maxItems": 100,
75
+ "x-code": "clinical_procedures",
76
+ "items": {
77
+ "type": "object",
78
+ "additionalProperties": false,
79
+ "required": ["procedureId"],
80
+ "x-code": "clinical_procedure",
81
+ "x-keys-code": "clinical_procedure_keys",
82
+ "properties": {
83
+ "procedureId": {
84
+ "type": "string",
85
+ "minLength": 1,
86
+ "maxLength": 60,
87
+ "x-code": "clinical_procedure_id"
88
+ },
89
+ "code": {
90
+ "type": "string",
91
+ "minLength": 1,
92
+ "maxLength": 64,
93
+ "x-code": "clinical_procedure_code"
94
+ },
95
+ "codeSystem": {
96
+ "type": "string",
97
+ "enum": ["CPT", "HCPCS", "ICD-10-PCS", "OTHER"],
98
+ "x-code": "clinical_procedure_code_system"
99
+ },
100
+ "codeVersion": {
101
+ "type": "string",
102
+ "minLength": 1,
103
+ "maxLength": 40,
104
+ "x-code": "clinical_procedure_code_version"
105
+ },
106
+ "description": {
107
+ "type": "string",
108
+ "minLength": 1,
109
+ "maxLength": 240,
110
+ "x-code": "clinical_procedure_description"
111
+ },
112
+ "performedDate": {
113
+ "type": "string",
114
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
115
+ "format": "date",
116
+ "x-code": "clinical_procedure_performed_date"
117
+ }
118
+ }
119
+ }
120
+ },
121
+ "medications": {
122
+ "type": "array",
123
+ "maxItems": 100,
124
+ "x-code": "clinical_medications",
125
+ "items": {
126
+ "type": "object",
127
+ "additionalProperties": false,
128
+ "required": ["medicationId"],
129
+ "x-code": "clinical_medication",
130
+ "x-keys-code": "clinical_medication_keys",
131
+ "properties": {
132
+ "medicationId": {
133
+ "type": "string",
134
+ "minLength": 1,
135
+ "maxLength": 60,
136
+ "x-code": "clinical_medication_id"
137
+ },
138
+ "code": {
139
+ "type": "string",
140
+ "minLength": 1,
141
+ "maxLength": 64,
142
+ "x-code": "clinical_medication_code"
143
+ },
144
+ "codeSystem": {
145
+ "type": "string",
146
+ "enum": ["NDC", "RxNorm", "OTHER"],
147
+ "x-code": "clinical_medication_code_system"
148
+ },
149
+ "name": {
150
+ "type": "string",
151
+ "minLength": 1,
152
+ "maxLength": 240,
153
+ "x-code": "clinical_medication_name"
154
+ },
155
+ "dosage": {
156
+ "type": "string",
157
+ "minLength": 1,
158
+ "maxLength": 120,
159
+ "x-code": "clinical_medication_dosage"
160
+ },
161
+ "route": {
162
+ "type": "string",
163
+ "minLength": 1,
164
+ "maxLength": 80,
165
+ "x-code": "clinical_medication_route"
166
+ },
167
+ "administrationDate": {
168
+ "type": "string",
169
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
170
+ "format": "date",
171
+ "x-code": "clinical_medication_administration_date"
172
+ }
173
+ }
174
+ }
175
+ },
176
+ "supplies": {
177
+ "type": "array",
178
+ "maxItems": 100,
179
+ "x-code": "clinical_supplies",
180
+ "items": {
181
+ "type": "object",
182
+ "additionalProperties": false,
183
+ "required": ["supplyId"],
184
+ "x-code": "clinical_supply",
185
+ "x-keys-code": "clinical_supply_keys",
186
+ "properties": {
187
+ "supplyId": {
188
+ "type": "string",
189
+ "minLength": 1,
190
+ "maxLength": 60,
191
+ "x-code": "clinical_supply_id"
192
+ },
193
+ "code": {
194
+ "type": "string",
195
+ "minLength": 1,
196
+ "maxLength": 64,
197
+ "x-code": "clinical_supply_code"
198
+ },
199
+ "codeSystem": {
200
+ "type": "string",
201
+ "enum": ["HCPCS", "NDC", "OTHER"],
202
+ "x-code": "clinical_supply_code_system"
203
+ },
204
+ "name": {
205
+ "type": "string",
206
+ "minLength": 1,
207
+ "maxLength": 240,
208
+ "x-code": "clinical_supply_name"
209
+ },
210
+ "quantity": {
211
+ "type": "integer",
212
+ "minimum": 0,
213
+ "maximum": 999999,
214
+ "x-code": "clinical_supply_quantity"
215
+ },
216
+ "unitOfMeasure": {
217
+ "type": "string",
218
+ "minLength": 1,
219
+ "maxLength": 20,
220
+ "x-code": "clinical_supply_unit_of_measure"
221
+ },
222
+ "supplyDate": {
223
+ "type": "string",
224
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
225
+ "format": "date",
226
+ "x-code": "clinical_supply_date"
227
+ }
228
+ }
229
+ }
230
+ },
231
+ "timeUnits": {
232
+ "type": "array",
233
+ "maxItems": 200,
234
+ "x-code": "clinical_time_units",
235
+ "items": {
236
+ "type": "object",
237
+ "additionalProperties": false,
238
+ "required": ["timeId", "date", "durationMinutes"],
239
+ "x-code": "clinical_time_unit",
240
+ "x-keys-code": "clinical_time_unit_keys",
241
+ "properties": {
242
+ "timeId": {
243
+ "type": "string",
244
+ "minLength": 1,
245
+ "maxLength": 60,
246
+ "x-code": "clinical_time_unit_id"
247
+ },
248
+ "date": {
249
+ "type": "string",
250
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
251
+ "format": "date",
252
+ "x-code": "clinical_time_unit_date"
253
+ },
254
+ "durationMinutes": {
255
+ "type": "integer",
256
+ "minimum": 1,
257
+ "maximum": 1440,
258
+ "x-code": "clinical_time_unit_duration"
259
+ },
260
+ "activityCode": {
261
+ "type": "string",
262
+ "minLength": 1,
263
+ "maxLength": 80,
264
+ "x-code": "clinical_time_unit_activity_code"
265
+ },
266
+ "activityDescription": {
267
+ "type": "string",
268
+ "minLength": 1,
269
+ "maxLength": 240,
270
+ "x-code": "clinical_time_unit_activity_description"
271
+ },
272
+ "clinicianRole": {
273
+ "type": "string",
274
+ "enum": [
275
+ "attending",
276
+ "physician",
277
+ "nurse_practitioner",
278
+ "physician_assistant",
279
+ "resident",
280
+ "other"
281
+ ],
282
+ "x-code": "clinical_time_unit_clinician_role"
283
+ },
284
+ "placeOfService": {
285
+ "type": "string",
286
+ "pattern": "^[0-9]{2}$",
287
+ "x-code": "clinical_time_unit_place_of_service"
288
+ }
289
+ }
290
+ }
291
+ },
292
+ "notes": {
293
+ "type": "array",
294
+ "maxItems": 50,
295
+ "x-code": "clinical_notes",
296
+ "items": {
297
+ "type": "object",
298
+ "additionalProperties": false,
299
+ "required": ["noteId", "noteType", "note"],
300
+ "x-code": "clinical_note",
301
+ "x-keys-code": "clinical_note_keys",
302
+ "properties": {
303
+ "noteId": {
304
+ "type": "string",
305
+ "minLength": 1,
306
+ "maxLength": 60,
307
+ "x-code": "clinical_note_id"
308
+ },
309
+ "noteType": {
310
+ "type": "string",
311
+ "enum": [
312
+ "clinical_narrative",
313
+ "procedure_narrative",
314
+ "authorization",
315
+ "correspondence",
316
+ "other"
317
+ ],
318
+ "x-code": "clinical_note_type"
319
+ },
320
+ "note": {
321
+ "type": "string",
322
+ "minLength": 1,
323
+ "maxLength": 10000,
324
+ "x-strip-nonempty": true,
325
+ "x-code": "clinical_note_text"
326
+ }
327
+ }
328
+ }
329
+ },
330
+ "sourceReferences": {
331
+ "type": "array",
332
+ "maxItems": 50,
333
+ "x-code": "clinical_source_references",
334
+ "items": {
335
+ "type": "object",
336
+ "additionalProperties": false,
337
+ "required": ["sourceId", "sourceLabel"],
338
+ "x-code": "clinical_source_reference",
339
+ "x-keys-code": "clinical_source_reference_keys",
340
+ "properties": {
341
+ "sourceId": {
342
+ "type": "string",
343
+ "minLength": 1,
344
+ "maxLength": 60,
345
+ "x-code": "clinical_source_reference_id"
346
+ },
347
+ "sourceLabel": {
348
+ "type": "string",
349
+ "minLength": 1,
350
+ "maxLength": 120,
351
+ "x-code": "clinical_source_reference_label"
352
+ },
353
+ "documentId": {
354
+ "type": "string",
355
+ "minLength": 1,
356
+ "maxLength": 240,
357
+ "x-code": "clinical_source_reference_document_id"
358
+ },
359
+ "excerpt": {
360
+ "type": "string",
361
+ "minLength": 1,
362
+ "maxLength": 2000,
363
+ "x-strip-nonempty": true,
364
+ "x-code": "clinical_source_reference_excerpt"
365
+ },
366
+ "sourceVersion": {
367
+ "type": "string",
368
+ "minLength": 1,
369
+ "maxLength": 80,
370
+ "x-code": "clinical_source_reference_version"
371
+ },
372
+ "corpusScope": {
373
+ "type": "string",
374
+ "enum": ["base", "tenant"],
375
+ "x-code": "clinical_source_reference_corpus_scope"
376
+ },
377
+ "publisher": {
378
+ "type": "string",
379
+ "minLength": 1,
380
+ "maxLength": 240,
381
+ "x-code": "clinical_source_reference_publisher"
382
+ },
383
+ "effectiveDate": {
384
+ "type": "string",
385
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
386
+ "format": "date",
387
+ "x-code": "clinical_source_reference_effective_date"
388
+ },
389
+ "retrievalDate": {
390
+ "type": "string",
391
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
392
+ "format": "date",
393
+ "x-code": "clinical_source_reference_retrieval_date"
394
+ },
395
+ "coveredPayerProgram": {
396
+ "type": "string",
397
+ "minLength": 1,
398
+ "maxLength": 240,
399
+ "x-code": "clinical_source_reference_covered_payer_program"
400
+ },
401
+ "sourceUrl": {
402
+ "type": "string",
403
+ "minLength": 1,
404
+ "maxLength": 2048,
405
+ "x-code": "clinical_source_reference_url"
406
+ },
407
+ "documentHash": {
408
+ "type": "string",
409
+ "minLength": 1,
410
+ "maxLength": 64,
411
+ "x-code": "clinical_source_reference_hash"
412
+ },
413
+ "capturedAt": {
414
+ "type": "string",
415
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
416
+ "format": "date",
417
+ "x-code": "clinical_source_reference_captured_at"
418
+ },
419
+ "humanReviewRequired": {
420
+ "type": "boolean",
421
+ "const": true,
422
+ "x-code": "clinical_source_reference_human_review_required"
423
+ }
424
+ }
425
+ }
426
+ }
427
+ }
428
+ }
package/schemas/coding-case-context.schema.json ADDED
@@ -0,0 +1,128 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://nexalink.care/contracts/coding-case-context.schema.json",
4
+ "title": "CodingCaseContext",
5
+ "description": "Where and by whom the services were rendered: setting, place of service, jurisdiction, specialty, provider, and facility. Provider identifiers are direct identifiers and must never be promoted to analytics surfaces.",
6
+ "version": "1.0.0",
7
+ "x-wire-version": "coding-case-context-v1",
8
+ "x-wire-constant": "CODING_CASE_CONTEXT_SCHEMA_VERSION",
9
+ "x-code": "context",
10
+ "x-keys-code": "context_keys",
11
+ "type": "object",
12
+ "additionalProperties": false,
13
+ "required": ["setting"],
14
+ "properties": {
15
+ "setting": {
16
+ "type": "string",
17
+ "enum": [
18
+ "professional",
19
+ "facility",
20
+ "pharmacy",
21
+ "dental",
22
+ "risk_adjustment",
23
+ "other"
24
+ ],
25
+ "x-code": "context_setting"
26
+ },
27
+ "otherSettingDescription": {
28
+ "type": "string",
29
+ "minLength": 1,
30
+ "maxLength": 120,
31
+ "x-strip-nonempty": true,
32
+ "x-code": "context_other_setting"
33
+ },
34
+ "placeOfService": {
35
+ "type": "string",
36
+ "pattern": "^[0-9]{2}$",
37
+ "x-code": "context_place_of_service"
38
+ },
39
+ "jurisdiction": {
40
+ "type": "string",
41
+ "minLength": 1,
42
+ "maxLength": 80,
43
+ "x-code": "context_jurisdiction"
44
+ },
45
+ "specialty": {
46
+ "type": "string",
47
+ "minLength": 1,
48
+ "maxLength": 120,
49
+ "x-code": "context_specialty"
50
+ },
51
+ "provider": {
52
+ "type": "object",
53
+ "additionalProperties": false,
54
+ "x-code": "context_provider",
55
+ "x-keys-code": "context_provider_keys",
56
+ "properties": {
57
+ "providerId": {
58
+ "type": "string",
59
+ "minLength": 1,
60
+ "maxLength": 64,
61
+ "x-code": "context_provider_id"
62
+ },
63
+ "npi": {
64
+ "type": "string",
65
+ "pattern": "^[0-9]{10}$",
66
+ "x-code": "context_provider_npi"
67
+ },
68
+ "name": {
69
+ "type": "string",
70
+ "minLength": 1,
71
+ "maxLength": 160,
72
+ "x-code": "context_provider_name"
73
+ },
74
+ "role": {
75
+ "type": "string",
76
+ "enum": [
77
+ "rendering",
78
+ "billing",
79
+ "attending",
80
+ "supervising",
81
+ "ordering",
82
+ "referring",
83
+ "other"
84
+ ],
85
+ "x-code": "context_provider_role"
86
+ },
87
+ "taxonomy": {
88
+ "type": "string",
89
+ "minLength": 1,
90
+ "maxLength": 40,
91
+ "x-code": "context_provider_taxonomy"
92
+ }
93
+ }
94
+ },
95
+ "facility": {
96
+ "type": "object",
97
+ "additionalProperties": false,
98
+ "x-code": "context_facility",
99
+ "x-keys-code": "context_facility_keys",
100
+ "properties": {
101
+ "facilityId": {
102
+ "type": "string",
103
+ "minLength": 1,
104
+ "maxLength": 64,
105
+ "x-code": "context_facility_id"
106
+ },
107
+ "name": {
108
+ "type": "string",
109
+ "minLength": 1,
110
+ "maxLength": 160,
111
+ "x-code": "context_facility_name"
112
+ },
113
+ "facilityType": {
114
+ "type": "string",
115
+ "enum": [
116
+ "hospital_inpatient",
117
+ "hospital_outpatient",
118
+ "clinic",
119
+ "ambulatory_surgery_center",
120
+ "nursing_facility",
121
+ "other"
122
+ ],
123
+ "x-code": "context_facility_type"
124
+ }
125
+ }
126
+ }
127
+ }
128
+ }