@nexalink/carecompass-sdk 0.3.0-beta.15 → 0.5.0

package/dist/rcm.d.ts

@@ -0,0 +1,93 @@
+import React from "react";
+import { type CareCompassCore, type CareCompassCoreOptions } from "./core.js";
+import type { CareCompassAuditListener, CareCompassSafetyListener } from "./compliance.js";
+import type { CareCompassConfig } from "./schema.js";
+/** A narrow, structured input for coding review. Do not include direct patient identifiers. */
+export type RcmCodingAssistanceInput = {
+    encounterId: string;
+    diagnosisNarrative: string;
+    procedureNarrative?: string;
+    serviceDate?: string;
+    placeOfService?: string;
+    claimContext?: {
+        payerName?: string;
+        submittedCodes?: string[];
+    };
+};
+export type RcmCodeSystem = "ICD-10-CM" | "CPT" | "HCPCS";
+export type RcmConfidence = "low" | "medium" | "high";
+export type RcmReviewDisposition = "review_required" | "abstain" | "escalate";
+export type RcmPolicyReference = {
+    corpusId: string;
+    id: string;
+    title: string;
+    excerpt: string;
+    version?: string;
+};
+export type RcmCodeRecommendation = {
+    code: string;
+    codeSystem: RcmCodeSystem;
+    confidence: RcmConfidence;
+    rationale: string;
+    policyReferenceIds: string[];
+};
+export type RcmCodingAssistanceResult = {
+    disposition: RcmReviewDisposition;
+    humanReviewRequired: true;
+    recommendations: RcmCodeRecommendation[];
+    documentationGaps: string[];
+    policyReferences: RcmPolicyReference[];
+    rationale: string;
+    /** A host-facing, measurable pilot hypothesis—not a claim of realized savings. */
+    operationalHypothesis: {
+        metric: "manual_research_minutes_per_case";
+        target: "Measure whether assisted review reduces manual research time by 25% or more.";
+    };
+    processingTimeMs: number;
+};
+export type RcmCustomerRules = {
+    allowedCodeSystems?: RcmCodeSystem[];
+    escalateOnLowConfidence?: boolean;
+    requirePolicySupport?: boolean;
+};
+export type RcmPolicyRetriever = {
+    /** Corpus IDs are allowlisted by the embed owner; retrieval stays in the host's trusted boundary. */
+    approvedCorpusIds: readonly string[];
+    search: (request: {
+        input: RcmCodingAssistanceInput;
+        query: string;
+    }) => Promise<RcmPolicyReference[]>;
+};
+export type RcmCodingWorkflowOptions = {
+    core?: CareCompassCore;
+    coreOptions?: CareCompassCoreOptions;
+    customerRules?: RcmCustomerRules;
+    now?: () => number;
+    onResult?: (result: RcmCodingAssistanceResult) => void;
+    /**
+     * `hosted` delegates retrieval to the tenant-authorized CareCompass runtime.
+     * The browser never supplies policy text or corpus identifiers in that mode.
+     */
+    retrieval?: RcmPolicyRetriever | "hosted";
+};
+export type RcmCodingWorkflow = {
+    core: CareCompassCore;
+    review: (input: RcmCodingAssistanceInput) => Promise<RcmCodingAssistanceResult>;
+};
+/**
+ * Creates a narrow RCM coding-review workflow on the shared CareCompass core.
+ * Retrieval can run in the CareCompass tenant boundary or be injected by a
+ * customer that maintains its own approved, server-side retrieval boundary.
+ */
+export declare function createRcmCodingWorkflow(config: CareCompassConfig, options?: RcmCodingWorkflowOptions): RcmCodingWorkflow;
+export declare const CARECOMPASS_RCM_SYNTHETIC_DEMO: RcmCodingAssistanceInput;
+export type RcmCodingAssistantProps = {
+    config: CareCompassConfig;
+    initialInput?: RcmCodingAssistanceInput;
+    onAuditEvent?: CareCompassAuditListener;
+    onResult?: (result: RcmCodingAssistanceResult) => void;
+    onSafetyEvent?: CareCompassSafetyListener;
+    workflowOptions?: Omit<RcmCodingWorkflowOptions, "core" | "coreOptions" | "onResult">;
+};
+/** A small branded form suitable for embedding the pilot workflow in a host app. */
+export declare function RcmCodingAssistant({ config, initialInput, onAuditEvent, onResult, onSafetyEvent, workflowOptions, }: RcmCodingAssistantProps): React.JSX.Element;

package/dist/rcm.js

@@ -0,0 +1,284 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+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 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) => {
+    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")
+            return null;
+        const documentationGaps = stringArray(body.documentationGaps);
+        if (!documentationGaps || !Array.isArray(body.recommendations))
+            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") {
+                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;
+        });
+        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,
+            rationale: body.rationale,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+const promptFor = (input, policyReferences, rules) => [
+    "You are a revenue-cycle coding-assistance workflow.",
+    "Return only JSON. This is a suggestion for a qualified human coder, never a final billing, coding, or clinical decision.",
+    'Use this shape: {"disposition":"review_required|abstain|escalate","humanReviewRequired":true,"recommendations":[{"code":"string","codeSystem":"ICD-10-CM|CPT|HCPCS","confidence":"low|medium|high","rationale":"string","evidenceIds":["reference-1"]}],"documentationGaps":["string"],"rationale":"string"}.',
+    "If documentation or policy support is insufficient, abstain or escalate with an empty recommendations array.",
+    `Customer rules: ${JSON.stringify(rules)}.`,
+    `Encounter context: ${JSON.stringify(input)}.`,
+    `Approved supporting references: ${JSON.stringify(policyReferences.map((reference, index) => ({
+        referenceId: `reference-${index + 1}`,
+        title: reference.title,
+        excerpt: reference.excerpt,
+        version: reference.version,
+    })))}.`,
+].join("\n");
+const fallback = (reason, policyReferences, processingTimeMs) => ({
+    disposition: "escalate",
+    humanReviewRequired: true,
+    recommendations: [],
+    documentationGaps: [],
+    policyReferences,
+    rationale: reason,
+    operationalHypothesis: OPERATIONAL_HYPOTHESIS,
+    processingTimeMs,
+});
+const enforceRules = (result, policyReferences, rules, processingTimeMs) => {
+    if (!result) {
+        return fallback("The response was not a valid review recommendation. Route this encounter to a qualified coder.", policyReferences, processingTimeMs);
+    }
+    const referenceIds = new Set(policyReferences.map((reference) => reference.id));
+    const missingRequiredPolicySupport = result.disposition === "review_required" &&
+        rules.requirePolicySupport === true &&
+        (policyReferences.length === 0 ||
+            result.recommendations.some((recommendation) => recommendation.policyReferenceIds.length === 0 ||
+                recommendation.policyReferenceIds.some((id) => !referenceIds.has(id))));
+    const violatesRules = missingRequiredPolicySupport ||
+        result.recommendations.some((recommendation) => (rules.allowedCodeSystems !== undefined &&
+            !rules.allowedCodeSystems.includes(recommendation.codeSystem)) ||
+            (rules.escalateOnLowConfidence === true &&
+                recommendation.confidence === "low"));
+    if (violatesRules) {
+        return fallback("Customer review rules require escalation before any coding recommendation can be used.", policyReferences, processingTimeMs);
+    }
+    return {
+        ...result,
+        policyReferences,
+        operationalHypothesis: OPERATIONAL_HYPOTHESIS,
+        processingTimeMs,
+    };
+};
+/**
+ * Creates a narrow RCM coding-review workflow on the shared CareCompass core.
+ * Retrieval can run in the CareCompass tenant boundary or be injected by a
+ * customer that maintains its own approved, server-side retrieval boundary.
+ */
+export function createRcmCodingWorkflow(config, options = {}) {
+    if (options.core && options.coreOptions) {
+        throw new Error("Provide either an existing core or coreOptions, not both.");
+    }
+    const core = options.core ?? createCareCompassCore(config, options.coreOptions);
+    const now = options.now ?? Date.now;
+    const rules = options.customerRules ?? {};
+    const hostedRetrieval = options.retrieval === "hosted";
+    return {
+        core,
+        review: async (input) => {
+            const startedAt = now();
+            const processingTime = () => Math.max(0, now() - startedAt);
+            let policyReferences = [];
+            try {
+                if (options.retrieval && options.retrieval !== "hosted") {
+                    policyReferences = await options.retrieval.search({
+                        input,
+                        query: [input.diagnosisNarrative, input.procedureNarrative]
+                            .filter(Boolean)
+                            .join(" "),
+                    });
+                    const approved = new Set(options.retrieval.approvedCorpusIds);
+                    if (policyReferences.some((reference) => !approved.has(reference.corpusId))) {
+                        throw new Error("Retrieval returned a reference outside the approved corpus.");
+                    }
+                    core.recordToolCall("completed");
+                }
+            }
+            catch {
+                core.recordToolCall("failed");
+                core.recordSafetyDecision("escalated", "tool_call");
+                const result = fallback("Approved policy retrieval was unavailable or returned an unapproved source. Route this encounter to a qualified coder.", policyReferences, processingTime());
+                options.onResult?.(result);
+                return result;
+            }
+            if (rules.requirePolicySupport &&
+                !hostedRetrieval &&
+                policyReferences.length === 0) {
+                core.recordSafetyDecision("escalated", "tool_call");
+                const result = fallback("No approved policy support was retrieved. Route this encounter to a qualified coder.", policyReferences, processingTime());
+                options.onResult?.(result);
+                return result;
+            }
+            core.recordWidgetAction("recorded");
+            try {
+                await core.sendMessage(promptFor(input, policyReferences, rules), {
+                    workflow: "rcm-coding-assistance",
+                    context: {
+                        rcmCodingInput: input,
+                        rcmSupportingReferences: policyReferences.map((reference, index) => ({
+                            referenceId: `reference-${index + 1}`,
+                            title: reference.title,
+                            excerpt: reference.excerpt,
+                            version: reference.version,
+                        })),
+                    },
+                });
+            }
+            catch {
+                core.recordSafetyDecision("escalated", "widget_action");
+                const result = fallback("The coding-assistance request could not be completed safely. Route this encounter to a qualified coder.", policyReferences, processingTime());
+                options.onResult?.(result);
+                return result;
+            }
+            const response = core
+                .getSnapshot()
+                .messages.slice()
+                .reverse()
+                .find((message) => message.role === "assistant" && message.id !== "welcome");
+            if (hostedRetrieval && response?.retrieval) {
+                policyReferences = response.retrieval.references.map((reference) => ({
+                    corpusId: response.retrieval?.corpusId ?? "",
+                    id: reference.referenceId,
+                    title: reference.title,
+                    excerpt: reference.excerpt,
+                    version: reference.version,
+                }));
+            }
+            const parsed = response ? parseResult(response.text) : null;
+            const evidenceIds = new Map(policyReferences.map((reference, index) => [
+                `reference-${index + 1}`,
+                reference.id,
+            ]));
+            const result = enforceRules(parsed && {
+                ...parsed,
+                recommendations: parsed.recommendations.map((recommendation) => ({
+                    ...recommendation,
+                    policyReferenceIds: recommendation.policyReferenceIds.map((id) => evidenceIds.get(id) ?? id),
+                })),
+            }, policyReferences, hostedRetrieval ? { ...rules, requirePolicySupport: true } : rules, processingTime());
+            if (result.disposition === "escalate" ||
+                result.disposition === "abstain") {
+                core.recordSafetyDecision("escalated", "widget_action");
+            }
+            options.onResult?.(result);
+            return result;
+        },
+    };
+}
+export const CARECOMPASS_RCM_SYNTHETIC_DEMO = {
+    encounterId: "DEMO-ENC-1042",
+    diagnosisNarrative: "Synthetic outpatient visit for persistent knee pain after activity.",
+    procedureNarrative: "Synthetic clinician documentation describes a focused musculoskeletal evaluation.",
+    serviceDate: "2026-07-01",
+    placeOfService: "11",
+    claimContext: { payerName: "Demo Health Plan", submittedCodes: [] },
+};
+/** 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, }) {
+    const workflow = React.useMemo(() => createRcmCodingWorkflow(config, {
+        ...workflowOptions,
+        coreOptions: {
+            onAuditEvent,
+            onSafetyEvent,
+        },
+        onResult,
+    }), [config, onAuditEvent, onResult, onSafetyEvent, workflowOptions]);
+    const [input, setInput] = React.useState(initialInput);
+    const [result, setResult] = React.useState(null);
+    const [submitting, setSubmitting] = React.useState(false);
+    React.useEffect(() => () => workflow.core.dispose(), [workflow]);
+    const submit = async (event) => {
+        event.preventDefault();
+        setSubmitting(true);
+        try {
+            setResult(await workflow.review(input));
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    const update = (field, value) => setInput((current) => ({ ...current, [field]: value }));
+    return (_jsxs("section", { "aria-label": `${config.labels.title} coding assistance`, style: {
+            background: config.theme.backgroundColor,
+            border: `1px solid ${config.theme.primaryColor}`,
+            borderRadius: config.theme.borderRadius,
+            color: config.theme.textColor,
+            fontFamily: config.theme.fontFamily,
+            maxWidth: 720,
+            padding: 20,
+        }, children: [_jsxs("header", { children: [_jsx("strong", { children: config.branding.displayName }), _jsx("h2", { style: { margin: "4px 0" }, children: "RCM Coding Assistance" }), _jsx("p", { children: "Suggestions require qualified human coding review before any billing action." })] }), _jsxs("form", { onSubmit: submit, children: [_jsxs("label", { children: ["Encounter reference", _jsx("input", { "aria-label": "Encounter reference", value: input.encounterId, onChange: (event) => update("encounterId", event.target.value) })] }), _jsxs("label", { children: ["Diagnosis context", _jsx("textarea", { "aria-label": "Diagnosis context", required: true, value: input.diagnosisNarrative, onChange: (event) => update("diagnosisNarrative", event.target.value) })] }), _jsxs("label", { children: ["Procedure context", _jsx("textarea", { "aria-label": "Procedure context", value: input.procedureNarrative ?? "", onChange: (event) => update("procedureNarrative", event.target.value) })] }), _jsx("button", { disabled: submitting, style: { background: config.theme.primaryColor, color: "#fff" }, type: "submit", children: submitting ? "Reviewing…" : "Prepare for coder review" })] }), result && (_jsxs("section", { "aria-live": "polite", children: [_jsx("p", { role: "alert", children: "Human review required \u2014 no billing or coding decision has been made." }), _jsx("p", { children: result.rationale }), result.recommendations.map((recommendation) => (_jsxs("article", { children: [_jsxs("strong", { children: [recommendation.codeSystem, " ", recommendation.code] }), _jsxs("span", { children: [" (", recommendation.confidence, " confidence)"] }), _jsx("p", { children: recommendation.rationale })] }, `${recommendation.codeSystem}-${recommendation.code}`))), result.policyReferences.length > 0 && (_jsxs("section", { "aria-label": "Supporting policy sources", children: [_jsx("h3", { children: "Supporting policy sources" }), result.policyReferences.map((reference) => (_jsxs("article", { children: [_jsx("strong", { children: reference.title }), reference.version && (_jsxs("span", { children: [" (version ", reference.version, ")"] })), _jsx("p", { children: reference.excerpt })] }, `${reference.corpusId}-${reference.id}`)))] }))] }))] }));
+}

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+export { CareCompassChat, CareCompassEmbed, useCareCompass, } from "./component.js";
+export type { CareCompassChatProps, CareCompassReactController, UseCareCompassOptions, } from "./component.js";

package/dist/react.js

@@ -0,0 +1 @@
+export { CareCompassChat, CareCompassEmbed, useCareCompass, } from "./component.js";

package/dist/schema.d.ts

@@ -34,6 +34,29 @@ export declare const careCompassPlacementSchema: z.ZodObject<{
     }>>;
     selector: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const careCompassComplianceConfigSchema: z.ZodObject<{
+    preset: z.ZodDefault<z.ZodEnum<{
+        standard: "standard";
+        healthcare: "healthcare";
+        strict: "strict";
+    }>>;
+    audit: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    phi: z.ZodDefault<z.ZodObject<{
+        action: z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            redact: "redact";
+            block: "block";
+        }>>;
+        replacement: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const careCompassModelConfigSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const careCompassFeatureFlagsSchema: z.ZodRecord<z.ZodString, z.ZodBoolean>;
 export declare const careCompassConfigSchema: z.ZodObject<{
     payerId: z.ZodString;
     environment: z.ZodEnum<{
@@ -69,6 +92,29 @@ export declare const careCompassConfigSchema: z.ZodObject<{
         welcomeMessage: z.ZodDefault<z.ZodString>;
         allowUserContext: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    compliance: z.ZodDefault<z.ZodObject<{
+        preset: z.ZodDefault<z.ZodEnum<{
+            standard: "standard";
+            healthcare: "healthcare";
+            strict: "strict";
+        }>>;
+        audit: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        phi: z.ZodDefault<z.ZodObject<{
+            action: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                redact: "redact";
+                block: "block";
+            }>>;
+            replacement: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    model: z.ZodDefault<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    featureFlags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     placement: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
             inline: "inline";
@@ -88,6 +134,9 @@ export declare const careCompassConfigSchema: z.ZodObject<{
 export type CareCompassTheme = z.infer<typeof careCompassThemeSchema>;
 export type CareCompassLabels = z.infer<typeof careCompassLabelsSchema>;
 export type CareCompassPromptConfig = z.infer<typeof careCompassPromptConfigSchema>;
+export type CareCompassComplianceConfig = z.infer<typeof careCompassComplianceConfigSchema>;
+export type CareCompassModelConfig = z.infer<typeof careCompassModelConfigSchema>;
+export type CareCompassFeatureFlags = z.infer<typeof careCompassFeatureFlagsSchema>;
 export type CareCompassConfig = z.infer<typeof careCompassConfigSchema>;
 export type CareCompassConfigInput = z.input<typeof careCompassConfigSchema>;
 export type CareCompassValidationResult = {

package/dist/schema.js

@@ -127,6 +127,33 @@ export const careCompassPlacementSchema = z.object({
     mode: z.enum(["inline", "floating", "sidebar"]).default("inline"),
     selector: z.string().min(1).max(120).optional(),
 });
+export const careCompassComplianceConfigSchema = z.object({
+    preset: z.enum(["standard", "healthcare", "strict"]).default("standard"),
+    audit: z
+        .object({
+        enabled: z.boolean().optional(),
+    })
+        .default({}),
+    phi: z
+        .object({
+        action: z.enum(["allow", "redact", "block"]).optional(),
+        replacement: z.string().min(1).max(80).optional(),
+    })
+        .default({}),
+});
+// Model selection is descriptive rather than credential-bearing. The hosted
+// runtime remains the authority for which models a tenant may use.
+export const careCompassModelConfigSchema = z.object({
+    id: z.string().min(1).max(120).optional(),
+    version: z.string().min(1).max(120).optional(),
+});
+// A portable public config can carry feature switches across every integration
+// option without requiring framework-specific configuration.
+export const careCompassFeatureFlagsSchema = z.record(z
+    .string()
+    .min(1)
+    .max(80)
+    .regex(/^[A-Za-z][A-Za-z0-9._-]*$/, "Feature flag keys must start with a letter and use letters, numbers, periods, underscores, or hyphens."), z.boolean());
 export const careCompassConfigSchema = z
     .object({
     payerId: z.string().regex(PAYER_ID_RE, "Invalid payer ID."),
@@ -149,6 +176,13 @@ export const careCompassConfigSchema = z
         welcomeMessage: "How can I help you navigate your care today?",
         allowUserContext: false,
     }),
+    compliance: careCompassComplianceConfigSchema.default({
+        preset: "standard",
+        audit: {},
+        phi: {},
+    }),
+    model: careCompassModelConfigSchema.default({}),
+    featureFlags: careCompassFeatureFlagsSchema.default({}),
     placement: careCompassPlacementSchema.default({ mode: "inline" }),
     deploymentTarget: z
         .enum(["react", "nextjs", "static", "web", "other"])
@@ -212,6 +246,8 @@ export function createDefaultCareCompassConfig(overrides = {}) {
         },
         labels: {},
         prompt: {},
+        model: {},
+        featureFlags: {},
         placement: {},
         deploymentTarget: "web",
         ...overrides,