@nexalink/coding-contracts 0.1.0 → 0.2.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.
- package/LICENSE +23 -0
- package/README.md +160 -0
- package/dist/cjs/index.cjs +3 -3
- package/dist/index.js +3 -3
- package/package.json +24 -5
- package/versions.json +2 -2
- package/workflow-constants.json +1 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
Nexalink Proprietary Software License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nexalink Health, Inc. All rights reserved.
|
|
4
|
+
|
|
5
|
+
This package and its source code are proprietary to Nexalink Health, Inc.
|
|
6
|
+
Access to this package does not grant any ownership interest, sublicensing
|
|
7
|
+
right, or right to redistribute the software except as expressly authorized in a
|
|
8
|
+
written agreement with Nexalink Health, Inc.
|
|
9
|
+
|
|
10
|
+
Authorized Nexalink customers and implementation partners may install and use
|
|
11
|
+
this package solely to evaluate, integrate, test, and operate CareCompass coding
|
|
12
|
+
workflow integrations for customer-approved healthcare deployments.
|
|
13
|
+
|
|
14
|
+
You may not copy, modify, publish, distribute, sell, sublicense, reverse
|
|
15
|
+
engineer, or use this software to provide a competing service except where
|
|
16
|
+
expressly permitted by a written agreement with Nexalink or by applicable law.
|
|
17
|
+
|
|
18
|
+
This software is provided "as is" without warranties of any kind, whether
|
|
19
|
+
express, implied, statutory, or otherwise, including warranties of
|
|
20
|
+
merchantability, fitness for a particular purpose, title, and non-infringement.
|
|
21
|
+
Nexalink is not liable for any claim, damages, or other liability arising from
|
|
22
|
+
use of this software except as required by applicable law or an executed written
|
|
23
|
+
agreement with Nexalink.
|
package/README.md
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# `@nexalink/coding-contracts`
|
|
2
|
+
|
|
3
|
+
Canonical TypeScript contracts for Nexalink CareCompass coding workflows.
|
|
4
|
+
|
|
5
|
+
The package provides:
|
|
6
|
+
|
|
7
|
+
- TypeScript types for coding inputs, grounded outputs, supporting references,
|
|
8
|
+
retrieval metadata, runtime events, model prompts, and workflow policy.
|
|
9
|
+
- Strict [Zod](https://zod.dev/) schemas for parsing untrusted values.
|
|
10
|
+
- Validation helpers that return stable, machine-readable error codes.
|
|
11
|
+
- Canonical workflow identifiers and schema wire-version constants.
|
|
12
|
+
- The underlying JSON Schema documents for non-TypeScript consumers and
|
|
13
|
+
tooling.
|
|
14
|
+
|
|
15
|
+
This package defines data contracts only. It does not make network requests,
|
|
16
|
+
persist data, submit claims, or replace review by a qualified human coder.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
Pin an exact version so contract upgrades are deliberate:
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
bun add @nexalink/coding-contracts@0.2.0 --exact
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The package supports both ES modules and CommonJS.
|
|
27
|
+
|
|
28
|
+
## Validate a coding input
|
|
29
|
+
|
|
30
|
+
Use the Zod schema when you want parsed, typed data and detailed issues:
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import {
|
|
34
|
+
RCM_INPUT_SCHEMA_VERSION,
|
|
35
|
+
rcmCodingInputSchema,
|
|
36
|
+
type RcmCodingInput,
|
|
37
|
+
} from "@nexalink/coding-contracts";
|
|
38
|
+
|
|
39
|
+
const candidate: unknown = {
|
|
40
|
+
encounterId: "DEMO-ENC-1042",
|
|
41
|
+
diagnosisNarrative: "Synthetic example for integration testing.",
|
|
42
|
+
serviceDate: "2026-07-01",
|
|
43
|
+
claimContext: {
|
|
44
|
+
stage: "development",
|
|
45
|
+
},
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
const input: RcmCodingInput = rcmCodingInputSchema.parse(candidate);
|
|
49
|
+
|
|
50
|
+
console.log(RCM_INPUT_SCHEMA_VERSION, input.encounterId);
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Use the validation helper when a compact error code is more useful than a Zod
|
|
54
|
+
error:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { rcmCodingInputValidationError } from "@nexalink/coding-contracts";
|
|
58
|
+
|
|
59
|
+
const errorCode = rcmCodingInputValidationError(candidate);
|
|
60
|
+
if (errorCode !== null) {
|
|
61
|
+
throw new Error(`Invalid coding input: ${errorCode}`);
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Validate a grounded coding output
|
|
66
|
+
|
|
67
|
+
Output validation can enforce both the structural contract and evidence
|
|
68
|
+
grounding. Pass the approved reference IDs and the corresponding evidence text
|
|
69
|
+
when validating recommendations:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { rcmCodingOutputValidationError } from "@nexalink/coding-contracts";
|
|
73
|
+
|
|
74
|
+
const candidate: unknown = {
|
|
75
|
+
disposition: "review_required",
|
|
76
|
+
humanReviewRequired: true,
|
|
77
|
+
recommendations: [
|
|
78
|
+
{
|
|
79
|
+
code: "99236",
|
|
80
|
+
codeSystem: "CPT",
|
|
81
|
+
confidence: "medium",
|
|
82
|
+
rationale: "Synthetic example for qualified coder review.",
|
|
83
|
+
evidenceIds: ["reference-1"],
|
|
84
|
+
},
|
|
85
|
+
],
|
|
86
|
+
documentationGaps: [],
|
|
87
|
+
rationale: "Synthetic grounded recommendation requiring human review.",
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
const errorCode = rcmCodingOutputValidationError(candidate, {
|
|
91
|
+
allowedReferenceIds: new Set(["reference-1"]),
|
|
92
|
+
referenceTextById: {
|
|
93
|
+
"reference-1": "Synthetic policy excerpt supporting CPT 99236.",
|
|
94
|
+
},
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
if (errorCode !== null) {
|
|
98
|
+
// Fail closed: do not present or act on an invalid recommendation.
|
|
99
|
+
throw new Error(`Invalid coding output: ${errorCode}`);
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
When grounding options are supplied, each recommendation must cite an approved
|
|
104
|
+
reference and its code must appear in at least one cited evidence text. Use both
|
|
105
|
+
options at trust boundaries. Calling the Zod schema or boolean helper alone
|
|
106
|
+
validates the structural and semantic contract, but not the caller-specific
|
|
107
|
+
approved evidence set.
|
|
108
|
+
|
|
109
|
+
## Main exports
|
|
110
|
+
|
|
111
|
+
| Category | Exports |
|
|
112
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
113
|
+
| Types | `RcmCodingInput`, `RcmCodingOutput`, `RcmSupportingReference`, `RcmModelPrompt`, `RcmRetrievalMetadata`, `RcmRuntimeEvent`, `RcmWorkflowCatalog` |
|
|
114
|
+
| Zod schemas | `rcmCodingInputSchema`, `rcmCodingOutputSchema`, and one schema for each additional contract type |
|
|
115
|
+
| Validation | `rcm*ValidationError` functions and `validRcm*` boolean helpers |
|
|
116
|
+
| Workflow policy | `RCM_WORKFLOW_ID`, `RCM_MODEL_POLICY_ID`, `RCM_HUMAN_REVIEW_POLICY_ID`, `RCM_HUMAN_REVIEW_INSTRUCTION`, `RCM_OUTPUT_SCHEMA_NAME` |
|
|
117
|
+
| Schema versions | `RCM_INPUT_SCHEMA_VERSION`, `RCM_OUTPUT_SCHEMA_VERSION`, `RCM_REFERENCE_SCHEMA_VERSION`, and the other contract wire-version constants |
|
|
118
|
+
| Schema documents | `Rcm*SchemaJson` values, JSON Schema package subpaths, `versions.json`, and `workflow-constants.json` |
|
|
119
|
+
|
|
120
|
+
## Use the raw JSON Schemas
|
|
121
|
+
|
|
122
|
+
The schemas are available as package subpaths. For example, in CommonJS:
|
|
123
|
+
|
|
124
|
+
```js
|
|
125
|
+
const inputSchema = require("@nexalink/coding-contracts/schemas/rcm-coding-input.schema");
|
|
126
|
+
const versions = require("@nexalink/coding-contracts/versions.json");
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The same documents are also exported as JavaScript values from the package
|
|
130
|
+
root, such as `RcmCodingInputSchemaJson`.
|
|
131
|
+
|
|
132
|
+
## Versioning
|
|
133
|
+
|
|
134
|
+
Package versions and wire-schema versions serve different purposes:
|
|
135
|
+
|
|
136
|
+
- The npm package follows semantic versioning. Consumers should pin an exact
|
|
137
|
+
version and evaluate contract changes before upgrading.
|
|
138
|
+
- Each schema also has a wire-version constant used in requests, results, and
|
|
139
|
+
runtime events. A package release can update implementation details without
|
|
140
|
+
changing every wire version.
|
|
141
|
+
- Additive contract changes may ship in a minor package release. Breaking
|
|
142
|
+
contract changes require a major package release and a new wire version.
|
|
143
|
+
|
|
144
|
+
The complete package-to-schema mapping is available from
|
|
145
|
+
`@nexalink/coding-contracts/versions.json`.
|
|
146
|
+
|
|
147
|
+
## Safety and licensing
|
|
148
|
+
|
|
149
|
+
- `humanReviewRequired` is always `true` for coding outputs. Recommendations
|
|
150
|
+
must be reviewed by a qualified human coder before billing, coding, or claim
|
|
151
|
+
submission.
|
|
152
|
+
- Treat validation failures as fail-closed conditions. Do not silently coerce
|
|
153
|
+
invalid input or continue with ungrounded output.
|
|
154
|
+
- Examples in this README are synthetic and must not be interpreted as coding
|
|
155
|
+
guidance.
|
|
156
|
+
- The package does not include licensed terminology descriptions and does not
|
|
157
|
+
grant rights to use licensed code-set content.
|
|
158
|
+
|
|
159
|
+
Use of this package is governed by the included Nexalink Proprietary Software
|
|
160
|
+
License.
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
// GENERATED FILE. DO NOT EDIT.
|
|
3
|
-
// Source:
|
|
3
|
+
// Source: coding-contracts schemas/ (run: bun run contracts:gen)
|
|
4
4
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
5
5
|
exports.RcmWorkflowCatalogSchemaJson = exports.validRcmWorkflowCatalog = exports.rcmWorkflowCatalogSchema = exports.RcmRuntimeEventSchemaJson = exports.validRcmRuntimeEvent = exports.rcmRuntimeEventSchema = exports.RcmRetrievalMetadataSchemaJson = exports.validRcmRetrievalMetadata = exports.rcmRetrievalMetadataSchema = exports.RcmModelPromptSchemaJson = exports.validRcmModelPrompt = exports.rcmModelPromptSchema = exports.RcmCodingOutputSchemaJson = exports.validRcmCodingOutput = exports.rcmCodingOutputSchema = exports.RcmCodingInputSchemaJson = exports.validRcmCodingInput = exports.rcmCodingInputSchema = exports.RcmSupportingReferenceSchemaJson = exports.validRcmSupportingReference = exports.rcmSupportingReferenceSchema = exports.RCM_WORKFLOW_CATALOG_SCHEMA_VERSION = exports.RCM_RUNTIME_EVENT_SCHEMA_VERSION = exports.RCM_RETRIEVAL_SCHEMA_VERSION = exports.RCM_MODEL_PROMPT_SCHEMA_VERSION = exports.RCM_OUTPUT_SCHEMA_VERSION = exports.RCM_INPUT_SCHEMA_VERSION = exports.RCM_REFERENCE_SCHEMA_VERSION = exports.RCM_HUMAN_REVIEW_INSTRUCTION = exports.RCM_OUTPUT_SCHEMA_NAME = exports.RCM_HUMAN_REVIEW_POLICY_ID = exports.RCM_MODEL_POLICY_ID = exports.RCM_WORKFLOW_ID = void 0;
|
|
6
6
|
exports.rcmSupportingReferenceValidationError = rcmSupportingReferenceValidationError;
|
|
@@ -13,13 +13,13 @@ exports.rcmWorkflowCatalogValidationError = rcmWorkflowCatalogValidationError;
|
|
|
13
13
|
const zod_1 = require("zod");
|
|
14
14
|
const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
15
15
|
const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
16
|
-
// Canonical workflow constants (source:
|
|
16
|
+
// Canonical workflow constants (source: workflow-constants.json).
|
|
17
17
|
exports.RCM_WORKFLOW_ID = "rcm-coding-assistance";
|
|
18
18
|
exports.RCM_MODEL_POLICY_ID = "carecompass-rcm-review-v1";
|
|
19
19
|
exports.RCM_HUMAN_REVIEW_POLICY_ID = "qualified-coder-review-v1";
|
|
20
20
|
exports.RCM_OUTPUT_SCHEMA_NAME = "carecompass_rcm_grounded_review";
|
|
21
21
|
exports.RCM_HUMAN_REVIEW_INSTRUCTION = "Qualified human coder review is required before billing, coding, or claim submission.";
|
|
22
|
-
// Schema wire versions (source:
|
|
22
|
+
// Schema wire versions (source: schemas/*.schema.json).
|
|
23
23
|
exports.RCM_REFERENCE_SCHEMA_VERSION = "rcm-supporting-reference-v1";
|
|
24
24
|
exports.RCM_INPUT_SCHEMA_VERSION = "rcm-coding-input-v1";
|
|
25
25
|
exports.RCM_OUTPUT_SCHEMA_VERSION = "rcm-grounded-human-review-v2";
|
package/dist/index.js
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
// GENERATED FILE. DO NOT EDIT.
|
|
2
|
-
// Source:
|
|
2
|
+
// Source: coding-contracts schemas/ (run: bun run contracts:gen)
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
5
5
|
const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
6
|
-
// Canonical workflow constants (source:
|
|
6
|
+
// Canonical workflow constants (source: workflow-constants.json).
|
|
7
7
|
export const RCM_WORKFLOW_ID = "rcm-coding-assistance";
|
|
8
8
|
export const RCM_MODEL_POLICY_ID = "carecompass-rcm-review-v1";
|
|
9
9
|
export const RCM_HUMAN_REVIEW_POLICY_ID = "qualified-coder-review-v1";
|
|
10
10
|
export const RCM_OUTPUT_SCHEMA_NAME = "carecompass_rcm_grounded_review";
|
|
11
11
|
export const RCM_HUMAN_REVIEW_INSTRUCTION = "Qualified human coder review is required before billing, coding, or claim submission.";
|
|
12
|
-
// Schema wire versions (source:
|
|
12
|
+
// Schema wire versions (source: schemas/*.schema.json).
|
|
13
13
|
export const RCM_REFERENCE_SCHEMA_VERSION = "rcm-supporting-reference-v1";
|
|
14
14
|
export const RCM_INPUT_SCHEMA_VERSION = "rcm-coding-input-v1";
|
|
15
15
|
export const RCM_OUTPUT_SCHEMA_VERSION = "rcm-grounded-human-review-v2";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nexalink/coding-contracts",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Versioned
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Versioned TypeScript types, validators, constants, and JSON Schemas for CareCompass coding workflows.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"types": "./dist/index.d.ts",
|
|
@@ -19,17 +19,36 @@
|
|
|
19
19
|
"files": [
|
|
20
20
|
"dist",
|
|
21
21
|
"schemas",
|
|
22
|
+
"README.md",
|
|
23
|
+
"LICENSE",
|
|
22
24
|
"versions.json",
|
|
23
25
|
"workflow-constants.json"
|
|
24
26
|
],
|
|
25
27
|
"sideEffects": false,
|
|
28
|
+
"scripts": {
|
|
29
|
+
"build": "bun run clean && bunx tsc -p tsconfig.json && bunx tsc -p tsconfig.cjs.json && bun scripts/rename-cjs.mjs",
|
|
30
|
+
"clean": "bun scripts/clean.mjs",
|
|
31
|
+
"contracts:gen": "bun scripts/codegen.ts",
|
|
32
|
+
"contracts:check": "bun scripts/codegen.ts --check",
|
|
33
|
+
"format": "bunx prettier --write --ignore-unknown .",
|
|
34
|
+
"format:check": "bunx prettier --check --ignore-unknown .",
|
|
35
|
+
"test": "bun test",
|
|
36
|
+
"test:python": "PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=python .venv/bin/python -m pytest -p no:cacheprovider python/tests",
|
|
37
|
+
"audit": "bun audit",
|
|
38
|
+
"verify:package": "bun scripts/verify-package.mjs",
|
|
39
|
+
"pack:dry-run": "bun run build && bun run verify:package && bun pm pack --dry-run --ignore-scripts",
|
|
40
|
+
"publish:beta": "bash scripts/publish.sh"
|
|
41
|
+
},
|
|
26
42
|
"dependencies": {
|
|
27
43
|
"zod": "^4.4.3"
|
|
28
44
|
},
|
|
45
|
+
"devDependencies": {
|
|
46
|
+
"prettier": "3.8.1",
|
|
47
|
+
"typescript": "^5.9.2"
|
|
48
|
+
},
|
|
29
49
|
"publishConfig": {
|
|
30
50
|
"access": "public",
|
|
31
|
-
"registry": "https://registry.npmjs.org/"
|
|
32
|
-
"tag": "beta"
|
|
51
|
+
"registry": "https://registry.npmjs.org/"
|
|
33
52
|
},
|
|
34
|
-
"license": "
|
|
53
|
+
"license": "SEE LICENSE IN LICENSE"
|
|
35
54
|
}
|
package/versions.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
|
-
"$comment": "GENERATED FILE. Schema registry derived from
|
|
2
|
+
"$comment": "GENERATED FILE. Schema registry derived from schemas/*.schema.json.",
|
|
3
3
|
"packageName": "@nexalink/coding-contracts",
|
|
4
|
-
"packageVersion": "0.
|
|
4
|
+
"packageVersion": "0.2.0",
|
|
5
5
|
"schemas": {
|
|
6
6
|
"rcm-supporting-reference": {
|
|
7
7
|
"file": "rcm-supporting-reference.schema.json",
|
package/workflow-constants.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"$comment": "Single source for workflow identity and policy identifiers
|
|
2
|
+
"$comment": "Single source for workflow identity and policy identifiers. Values are immutable server-side; changes require a breaking major release and a documented compatibility migration.",
|
|
3
3
|
"workflowConstants": {
|
|
4
4
|
"rcmWorkflowId": "rcm-coding-assistance",
|
|
5
5
|
"rcmModelPolicyId": "carecompass-rcm-review-v1",
|