@nexalink/carecompass-sdk 0.6.0 → 0.7.0

package/dist/rcm.js

@@ -1,83 +1,78 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
+import { RCM_WORKFLOW_ID, rcmCodingInputValidationError, rcmCodingOutputValidationError, } from "@nexalink/coding-contracts";
 import { createCareCompassCore, } from "./core.js";
 const OPERATIONAL_HYPOTHESIS = {
     metric: "manual_research_minutes_per_case",
     target: "Measure whether assisted review reduces manual research time by 25% or more.",
 };
-const CODE_SYSTEMS = ["ICD-10-CM", "CPT", "HCPCS"];
-const CONFIDENCES = ["low", "medium", "high"];
-const DISPOSITIONS = [
-    "review_required",
-    "abstain",
-    "escalate",
-];
+const RCM_MIGRATION_NOTICE = "[carecompass-sdk] The RCM coding-assistance convenience API is deprecated. " +
+    "Migrate to the generic headless coding API: createCodingFlow at " +
+    "@nexalink/carecompass-sdk/coding and the CodingReview UI at " +
+    "@nexalink/carecompass-sdk/coding-ui. See the README section " +
+    "\u201cMigrating from the RCM coding-assistance API\u201d for the compatibility path.";
+let rcmMigrationWarned = false;
+const warnRcmMigration = () => {
+    if (rcmMigrationWarned || typeof console === "undefined")
+        return;
+    rcmMigrationWarned = true;
+    console.warn(RCM_MIGRATION_NOTICE);
+};
 const asRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
-const stringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string")
-    ? value
-    : null;
 const extractJson = (value) => {
     const trimmed = value.trim();
     const json = trimmed.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
     return JSON.parse(json);
 };
-const isOneOf = (value, options) => typeof value === "string" && options.includes(value);
-const parseResult = (value) => {
+const parseResult = (value, policyReferences) => {
     try {
         const body = asRecord(extractJson(value));
-        if (!body || body.humanReviewRequired !== true)
-            return null;
-        if (!isOneOf(body.disposition, DISPOSITIONS))
-            return null;
-        if (typeof body.rationale !== "string")
+        if (!body)
             return null;
-        const documentationGaps = stringArray(body.documentationGaps);
-        if (!documentationGaps || !Array.isArray(body.recommendations))
+        const allowedReferenceIds = new Set();
+        const referenceTextById = {};
+        policyReferences.forEach((reference, index) => {
+            const alias = `reference-${index + 1}`;
+            const referenceText = `${reference.title}\n${reference.excerpt}`;
+            allowedReferenceIds.add(alias);
+            allowedReferenceIds.add(reference.id);
+            referenceTextById[alias] = referenceText;
+            referenceTextById[reference.id] = referenceText;
+        });
+        if (rcmCodingOutputValidationError(body, {
+            allowedReferenceIds,
+            referenceTextById,
+        }) !== null) {
             return null;
+        }
         const recommendations = body.recommendations.map((candidate) => {
             const entry = asRecord(candidate);
-            if (!entry ||
-                typeof entry.code !== "string" ||
-                !/^[A-Za-z0-9.]{2,12}$/.test(entry.code) ||
-                !isOneOf(entry.codeSystem, CODE_SYSTEMS) ||
-                !isOneOf(entry.confidence, CONFIDENCES) ||
-                typeof entry.rationale !== "string") {
+            if (!entry)
                 return null;
-            }
-            const policyReferenceIds = stringArray(entry.policyReferenceIds);
-            const evidenceIds = stringArray(entry.evidenceIds);
-            return policyReferenceIds
-                ? {
-                    code: entry.code,
-                    codeSystem: entry.codeSystem,
-                    confidence: entry.confidence,
-                    rationale: entry.rationale,
-                    policyReferenceIds,
-                }
-                : evidenceIds
-                    ? {
-                        code: entry.code,
-                        codeSystem: entry.codeSystem,
-                        confidence: entry.confidence,
-                        rationale: entry.rationale,
-                        policyReferenceIds: evidenceIds,
-                    }
-                    : null;
+            const idValue = entry["policyReferenceIds"] ?? entry["evidenceIds"];
+            const policyReferenceIds = Array.isArray(idValue) &&
+                idValue.every((id) => typeof id === "string")
+                ? idValue
+                : null;
+            if (!policyReferenceIds)
+                return null;
+            return {
+                code: entry["code"],
+                codeSystem: entry["codeSystem"],
+                confidence: entry["confidence"],
+                rationale: entry["rationale"],
+                policyReferenceIds,
+            };
         });
         if (recommendations.some((candidate) => candidate === null))
             return null;
-        if ((body.disposition === "review_required" &&
-            recommendations.length === 0) ||
-            (body.disposition !== "review_required" && recommendations.length > 0)) {
-            return null;
-        }
         return {
             disposition: body.disposition,
             humanReviewRequired: true,
             recommendations: recommendations,
-            documentationGaps,
+            documentationGaps: body.documentationGaps,
             rationale: body.rationale,
         };
     }
@@ -140,6 +135,7 @@ const enforceRules = (result, policyReferences, rules, processingTimeMs) => {
  * customer that maintains its own approved, server-side retrieval boundary.
  */
 export function createRcmCodingWorkflow(config, options = {}) {
+    warnRcmMigration();
     if (options.core && options.coreOptions) {
         throw new Error("Provide either an existing core or coreOptions, not both.");
     }
@@ -153,6 +149,12 @@ export function createRcmCodingWorkflow(config, options = {}) {
             const startedAt = now();
             const processingTime = () => Math.max(0, now() - startedAt);
             let policyReferences = [];
+            if (rcmCodingInputValidationError(input) !== null) {
+                core.recordSafetyDecision("escalated", "widget_action");
+                const result = fallback("The coding-assistance input did not satisfy the canonical workflow contract. Route this encounter to a qualified coder.", policyReferences, processingTime());
+                options.onResult?.(result);
+                return result;
+            }
             try {
                 if (options.retrieval && options.retrieval !== "hosted") {
                     policyReferences = await options.retrieval.search({
@@ -186,7 +188,7 @@ export function createRcmCodingWorkflow(config, options = {}) {
             core.recordWidgetAction("recorded");
             try {
                 await core.sendMessage(promptFor(input, policyReferences, rules), {
-                    workflow: "rcm-coding-assistance",
+                    workflow: RCM_WORKFLOW_ID,
                     context: {
                         rcmCodingInput: input,
                         rcmSupportingReferences: policyReferences.map((reference, index) => ({
@@ -218,7 +220,9 @@ export function createRcmCodingWorkflow(config, options = {}) {
                     version: reference.version,
                 }));
             }
-            const parsed = response ? parseResult(response.text) : null;
+            const parsed = response
+                ? parseResult(response.text, policyReferences)
+                : null;
             const evidenceIds = new Map(policyReferences.map((reference, index) => [
                 `reference-${index + 1}`,
                 reference.id,
@@ -253,6 +257,7 @@ export const CARECOMPASS_RCM_SYNTHETIC_DEMO = {
 };
 /** A small branded form suitable for embedding the pilot workflow in a host app. */
 export function RcmCodingAssistant({ config, initialInput = CARECOMPASS_RCM_SYNTHETIC_DEMO, onAuditEvent, onResult, onSafetyEvent, workflowOptions, }) {
+    warnRcmMigration();
     const workflow = React.useMemo(() => createRcmCodingWorkflow(config, {
         ...workflowOptions,
         coreOptions: {

package/dist/telemetry.d.ts

@@ -32,6 +32,17 @@ export declare const CARECOMPASS_TELEMETRY_EVENTS: {
     readonly CLI_SNIPPET_GENERATED: "carecompass_cli_snippet_generated";
     readonly CLI_DOCTOR_COMPLETED: "carecompass_cli_doctor_completed";
     readonly CLI_COMMAND_FAILED: "carecompass_cli_command_failed";
+    readonly PACK_LIST_SUCCEEDED: "carecompass_pack_list_succeeded";
+    readonly PACK_LIST_FAILED: "carecompass_pack_list_failed";
+    readonly PACK_SCHEMA_SUCCEEDED: "carecompass_pack_schema_succeeded";
+    readonly PACK_SCHEMA_FAILED: "carecompass_pack_schema_failed";
+    readonly CODING_CASE_SUBMITTED: "carecompass_coding_case_submitted";
+    readonly CODING_DECISION_RECEIVED: "carecompass_coding_decision_received";
+    readonly CODING_DECISION_INVALID: "carecompass_coding_decision_invalid";
+    readonly CODING_CASE_CANCELLED: "carecompass_coding_case_cancelled";
+    readonly CODING_CASE_CANCEL_FAILED: "carecompass_coding_case_cancel_failed";
+    readonly REVIEWER_ACTION_RECORDED: "carecompass_reviewer_action_recorded";
+    readonly REVIEWER_ACTION_FAILED: "carecompass_reviewer_action_failed";
 };
 export type CareCompassTelemetryEvent = (typeof CARECOMPASS_TELEMETRY_EVENTS)[keyof typeof CARECOMPASS_TELEMETRY_EVENTS];
 export declare const CARECOMPASS_TELEMETRY_ERROR_CODES: {

package/dist/telemetry.js

@@ -33,6 +33,17 @@ export const CARECOMPASS_TELEMETRY_EVENTS = {
     CLI_SNIPPET_GENERATED: "carecompass_cli_snippet_generated",
     CLI_DOCTOR_COMPLETED: "carecompass_cli_doctor_completed",
     CLI_COMMAND_FAILED: "carecompass_cli_command_failed",
+    PACK_LIST_SUCCEEDED: "carecompass_pack_list_succeeded",
+    PACK_LIST_FAILED: "carecompass_pack_list_failed",
+    PACK_SCHEMA_SUCCEEDED: "carecompass_pack_schema_succeeded",
+    PACK_SCHEMA_FAILED: "carecompass_pack_schema_failed",
+    CODING_CASE_SUBMITTED: "carecompass_coding_case_submitted",
+    CODING_DECISION_RECEIVED: "carecompass_coding_decision_received",
+    CODING_DECISION_INVALID: "carecompass_coding_decision_invalid",
+    CODING_CASE_CANCELLED: "carecompass_coding_case_cancelled",
+    CODING_CASE_CANCEL_FAILED: "carecompass_coding_case_cancel_failed",
+    REVIEWER_ACTION_RECORDED: "carecompass_reviewer_action_recorded",
+    REVIEWER_ACTION_FAILED: "carecompass_reviewer_action_failed",
 };
 export const CARECOMPASS_TELEMETRY_ERROR_CODES = {
     API_ERROR: "api_error",
@@ -151,11 +162,17 @@ const allowedEnvironment = (value) => value === "development" || value === "stag
     ? value
     : "unknown";
 function createTelemetry(context, options = {}) {
-    const fetcher = options.fetcher ?? fetch;
     const now = options.now ?? (() => new Date());
     const relayBaseUrl = approvedRelayBaseUrl(context.apiBaseUrl, context.environment);
-    if (!relayBaseUrl)
+    // Some test and embedded environments do not define fetch at all; telemetry
+    // must never crash SDK construction in those runtimes.
+    const resolvedFetcher = options.fetcher ??
+        (typeof globalThis.fetch === "function"
+            ? globalThis.fetch
+            : undefined);
+    if (!relayBaseUrl || !resolvedFetcher)
         return disabledTelemetry;
+    const fetcher = resolvedFetcher;
     const captureAsync = async (event, captureOptions = {}) => {
         if (!TELEMETRY_EVENTS.has(event))
             return;

package/dist/ui.d.ts

@@ -1,3 +1,7 @@
 export { CareCompassChat, CareCompassEmbed, useCareCompass, } from "./component.js";
 export type { CareCompassChatProps, CareCompassReactController, UseCareCompassOptions, } from "./component.js";
+export { CareCompassCodingReviewContent, CodingReview, mountCodingReview, useCodingReview, } from "./coding-ui.js";
+export type { CodingDecisionLine, CodingReviewProps, CodingReviewRenderProps, UseCodingReviewResult, } from "./coding-ui.js";
+export { CARECOMPASS_CODING_REVIEW_ELEMENT_TAG, defineCodingReviewElement, } from "./coding-element.js";
+export type { CareCompassCodingReviewElement } from "./coding-element.js";
 export { mountCareCompass } from "./mount.js";

package/dist/ui.js

@@ -1,2 +1,4 @@
 export { CareCompassChat, CareCompassEmbed, useCareCompass, } from "./component.js";
+export { CareCompassCodingReviewContent, CodingReview, mountCodingReview, useCodingReview, } from "./coding-ui.js";
+export { CARECOMPASS_CODING_REVIEW_ELEMENT_TAG, defineCodingReviewElement, } from "./coding-element.js";
 export { mountCareCompass } from "./mount.js";

package/dist/version.js

@@ -1,3 +1,3 @@
-export const CARECOMPASS_SDK_VERSION = "0.6.0"; // x-release-please-version
+export const CARECOMPASS_SDK_VERSION = "0.7.0"; // x-release-please-version
 export const CARECOMPASS_COMPONENT_VERSION = "1.0.0";
 export const CARECOMPASS_TELEMETRY_CONTRACT_VERSION = "1.1.0";

package/node_modules/@nexalink/coding-contracts/LICENSE

@@ -0,0 +1,23 @@
+Nexalink Proprietary Software License
+
+Copyright (c) 2026 Nexalink Health, Inc. All rights reserved.
+
+This package and its source code are proprietary to Nexalink Health, Inc.
+Access to this package does not grant any ownership interest, sublicensing
+right, or right to redistribute the software except as expressly authorized in a
+written agreement with Nexalink Health, Inc.
+
+Authorized Nexalink customers and implementation partners may install and use
+this package solely to evaluate, integrate, test, and operate CareCompass coding
+workflow integrations for customer-approved healthcare deployments.
+
+You may not copy, modify, publish, distribute, sell, sublicense, reverse
+engineer, or use this software to provide a competing service except where
+expressly permitted by a written agreement with Nexalink or by applicable law.
+
+This software is provided "as is" without warranties of any kind, whether
+express, implied, statutory, or otherwise, including warranties of
+merchantability, fitness for a particular purpose, title, and non-infringement.
+Nexalink is not liable for any claim, damages, or other liability arising from
+use of this software except as required by applicable law or an executed written
+agreement with Nexalink.

package/node_modules/@nexalink/coding-contracts/README.md

@@ -0,0 +1,200 @@
+# `@nexalink/coding-contracts`
+
+Canonical TypeScript contracts for Nexalink CareCompass coding workflows.
+
+The package provides:
+
+- TypeScript types for coding inputs, grounded outputs, supporting references,
+  retrieval metadata, runtime events, model prompts, and workflow policy.
+- Strict [Zod](https://zod.dev/) schemas for parsing untrusted values.
+- Validation helpers that return stable, machine-readable error codes.
+- Canonical workflow identifiers and schema wire-version constants.
+- The underlying JSON Schema documents for non-TypeScript consumers and
+  tooling.
+
+This package defines data contracts only. It does not make network requests,
+persist data, submit claims, or replace review by a qualified human coder.
+
+## Install
+
+Pin an exact version so contract upgrades are deliberate:
+
+```sh
+bun add @nexalink/coding-contracts@0.2.0 --exact
+```
+
+The package supports both ES modules and CommonJS.
+
+## Validate a coding input
+
+Use the Zod schema when you want parsed, typed data and detailed issues:
+
+```ts
+import {
+  RCM_INPUT_SCHEMA_VERSION,
+  rcmCodingInputSchema,
+  type RcmCodingInput,
+} from "@nexalink/coding-contracts";
+
+const candidate: unknown = {
+  encounterId: "DEMO-ENC-1042",
+  diagnosisNarrative: "Synthetic example for integration testing.",
+  serviceDate: "2026-07-01",
+  claimContext: {
+    stage: "development",
+  },
+};
+
+const input: RcmCodingInput = rcmCodingInputSchema.parse(candidate);
+
+console.log(RCM_INPUT_SCHEMA_VERSION, input.encounterId);
+```
+
+Use the validation helper when a compact error code is more useful than a Zod
+error:
+
+```ts
+import { rcmCodingInputValidationError } from "@nexalink/coding-contracts";
+
+const errorCode = rcmCodingInputValidationError(candidate);
+if (errorCode !== null) {
+  throw new Error(`Invalid coding input: ${errorCode}`);
+}
+```
+
+## Validate a grounded coding output
+
+Output validation can enforce both the structural contract and evidence
+grounding. Pass the approved reference IDs and the corresponding evidence text
+when validating recommendations:
+
+```ts
+import { rcmCodingOutputValidationError } from "@nexalink/coding-contracts";
+
+const candidate: unknown = {
+  disposition: "review_required",
+  humanReviewRequired: true,
+  recommendations: [
+    {
+      code: "99236",
+      codeSystem: "CPT",
+      confidence: "medium",
+      rationale: "Synthetic example for qualified coder review.",
+      evidenceIds: ["reference-1"],
+    },
+  ],
+  documentationGaps: [],
+  rationale: "Synthetic grounded recommendation requiring human review.",
+};
+
+const errorCode = rcmCodingOutputValidationError(candidate, {
+  allowedReferenceIds: new Set(["reference-1"]),
+  referenceTextById: {
+    "reference-1": "Synthetic policy excerpt supporting CPT 99236.",
+  },
+});
+
+if (errorCode !== null) {
+  // Fail closed: do not present or act on an invalid recommendation.
+  throw new Error(`Invalid coding output: ${errorCode}`);
+}
+```
+
+When grounding options are supplied, each recommendation must cite an approved
+reference and its code must appear in at least one cited evidence text. Use both
+options at trust boundaries. Calling the Zod schema or boolean helper alone
+validates the structural and semantic contract, but not the caller-specific
+approved evidence set.
+
+## Main exports
+
+| Category         | Exports                                                                                                                                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Types            | `RcmCodingInput`, `RcmCodingOutput`, `RcmSupportingReference`, `RcmModelPrompt`, `RcmRetrievalMetadata`, `RcmRuntimeEvent`, `RcmWorkflowCatalog`                                                       |
+| Case models      | `CodingCase`, `CodingCaseContext`, `CodingCasePayer`, `CodingCaseClinical`, `CodingServiceLine`, `CodingExtension`, `CodingBatch`                                                                      |
+| Decision models  | `CodingDecision`, `CodingDecisionLine`, `CodingEvidence`, `CodingRuleResult`, `CodingReviewerAction`                                                                                                   |
+| Zod schemas      | `rcmCodingInputSchema`, `rcmCodingOutputSchema`, `codingCaseSchema`, `codingDecisionSchema`, and one schema for each additional contract type                                                          |
+| Validation       | `rcm*ValidationError` functions, `coding*ValidationError` functions, and `valid*` boolean helpers                                                                                                      |
+| Workflow policy  | `RCM_WORKFLOW_ID`, `PIN_TIME_WORKFLOW_ID`, `RCM_MODEL_POLICY_ID`, `RCM_HUMAN_REVIEW_POLICY_ID`, `RCM_HUMAN_REVIEW_INSTRUCTION`, `RCM_OUTPUT_SCHEMA_NAME`                                               |
+| Schema versions  | `RCM_INPUT_SCHEMA_VERSION`, `RCM_OUTPUT_SCHEMA_VERSION`, `RCM_REFERENCE_SCHEMA_VERSION`, `CODING_CASE_SCHEMA_VERSION`, `CODING_DECISION_SCHEMA_VERSION`, and the other contract wire-version constants |
+| Schema documents | `Rcm*SchemaJson`, `Coding*SchemaJson` values, JSON Schema package subpaths, `versions.json`, and `workflow-constants.json`                                                                             |
+
+## Canonical CodingCase and CodingDecision
+
+`CodingCase` is the canonical case envelope for encounter review, claim review,
+longitudinal review, monthly multi-activity time aggregation, and bounded batch
+review. `CodingDecision` is the corresponding reconstructable decision.
+
+- **CodingCase** carries case identity (`caseId` is client-supplied and may be
+  a direct reference; `analyticsId` is the separate analytics-safe identifier),
+  coding intent, the service period, setting/jurisdiction/provider context,
+  payer/plan/program/contract context, structured clinical facts (diagnoses,
+  procedures, medications, supplies, `timeUnits` with `durationMinutes` and
+  `activityCode`, notes, source references), existing claim lines, and
+  namespaced `extensions`.
+- **CodingDecision** references the case by the analytics-safe `caseRef` only,
+  proposes claim-line actions (`add`, `retain`, `replace`, `remove`, `review`)
+  with code identity, modifiers, units, linked diagnoses, and sequencing, and
+  records typed evidence, documentation gaps, conflicts, extracted facts, rule
+  traces, confidence, and the qualified-human-review disposition.
+- **Provenance** (`decisionSchemaVersion`, `caseSchemaVersion`, pack, model,
+  terminology editions with license status, rule versions, retrieval corpus,
+  and generation time) lets every recommendation be reconstructed.
+- **ReviewerAction** is appended immutably: the original decision and the
+  attributable reviewer disposition are both preserved.
+- **Extensions** are `{ namespace, schemaVersion, payload }` objects. Payloads
+  are bounded (at most 50 properties) but otherwise opaque; Nexalink reserves
+  `com.nexalink` and `org.nexalink` namespaces. Extensions keep pack-specific
+  data out of the shared envelope without making every field optional.
+- **Identifiers**: direct identifiers (`caseId`, provider NPIs/names, `memberId`)
+  are documented as such in the schemas and must never be promoted to analytics
+  surfaces. Decisions and metrics reference the analytics-safe `analyticsId` /
+  `caseRef` only.
+- **Batching**: `CodingBatch` wraps 1–100 cases for bounded batch review; one
+  execution stays within runtime limits.
+
+The current RCM example (`DEMO-ENC-1042`) and a monthly multi-activity
+time-aggregation workflow both have lossless, round-trip fixtures under
+`fixtures/coding-case/` and `fixtures/coding-decision/`.
+
+## Use the raw JSON Schemas
+
+The schemas are available as package subpaths. For example, in CommonJS:
+
+```js
+const inputSchema = require("@nexalink/coding-contracts/schemas/rcm-coding-input.schema");
+const versions = require("@nexalink/coding-contracts/versions.json");
+```
+
+The same documents are also exported as JavaScript values from the package
+root, such as `RcmCodingInputSchemaJson`.
+
+## Versioning
+
+Package versions and wire-schema versions serve different purposes:
+
+- The npm package follows semantic versioning. Consumers should pin an exact
+  version and evaluate contract changes before upgrading.
+- Each schema also has a wire-version constant used in requests, results, and
+  runtime events. A package release can update implementation details without
+  changing every wire version.
+- Additive contract changes may ship in a minor package release. Breaking
+  contract changes require a major package release and a new wire version.
+
+The complete package-to-schema mapping is available from
+`@nexalink/coding-contracts/versions.json`.
+
+## Safety and licensing
+
+- `humanReviewRequired` is always `true` for coding outputs. Recommendations
+  must be reviewed by a qualified human coder before billing, coding, or claim
+  submission.
+- Treat validation failures as fail-closed conditions. Do not silently coerce
+  invalid input or continue with ungrounded output.
+- Examples in this README are synthetic and must not be interpreted as coding
+  guidance.
+- The package does not include licensed terminology descriptions and does not
+  grant rights to use licensed code-set content.
+
+Use of this package is governed by the included Nexalink Proprietary Software
+License.