@nexalink/carecompass-sdk 0.6.0 → 0.7.0

package/dist/coding-element.js

@@ -0,0 +1,475 @@
+import { CARECOMPASS_CODING_DECISION_LABELS, createCodingFlow, decisionConflicts, decisionGaps, decisionPrimaryState, decisionRequiresHumanReview, } from "./coding.js";
+import { validateCareCompassConfig } from "./schema.js";
+export const CARECOMPASS_CODING_REVIEW_ELEMENT_TAG = "carecompass-coding-review";
+/**
+ * Register a framework-neutral coding-review embed backed by the headless
+ * coding flow. Deferring the HTMLElement subclass creation keeps this entry
+ * point safe to import during server rendering.
+ */
+export function defineCodingReviewElement(tagName = CARECOMPASS_CODING_REVIEW_ELEMENT_TAG) {
+    if (typeof customElements === "undefined" ||
+        typeof HTMLElement === "undefined") {
+        return undefined;
+    }
+    const existing = customElements.get(tagName);
+    if (existing)
+        return existing;
+    class CodingReviewElement extends HTMLElement {
+        constructor() {
+            super(...arguments);
+            this.draft = "";
+            this.hasPropertyConfig = false;
+            this.cancelledDispatched = false;
+        }
+        static get observedAttributes() {
+            return ["config"];
+        }
+        get config() {
+            return this.configValue;
+        }
+        set config(value) {
+            this.hasPropertyConfig = true;
+            this.configValue = value;
+            this.remount();
+        }
+        get initialCase() {
+            return this.initialCaseValue;
+        }
+        set initialCase(value) {
+            this.initialCaseValue = value;
+            this.remount();
+        }
+        get packId() {
+            return this.packIdValue;
+        }
+        set packId(value) {
+            this.packIdValue = value;
+            this.remount();
+        }
+        get reviewerId() {
+            return this.reviewerIdValue;
+        }
+        set reviewerId(value) {
+            this.reviewerIdValue = value;
+            this.remount();
+        }
+        get reviewerRole() {
+            return this.reviewerRoleValue;
+        }
+        set reviewerRole(value) {
+            this.reviewerRoleValue = value;
+            this.remount();
+        }
+        get runtimeTokenProvider() {
+            return this.runtimeTokenProviderValue;
+        }
+        get reviewerAuthProvider() {
+            return this.reviewerAuthProviderValue;
+        }
+        set reviewerAuthProvider(value) {
+            this.reviewerAuthProviderValue = value;
+            this.remount();
+        }
+        set runtimeTokenProvider(value) {
+            this.runtimeTokenProviderValue = value;
+            this.remount();
+        }
+        connectedCallback() {
+            this.remount();
+        }
+        disconnectedCallback() {
+            this.unmount();
+        }
+        attributeChangedCallback(name, _oldValue, value) {
+            if (name !== "config" || this.hasPropertyConfig)
+                return;
+            if (value === null) {
+                this.configValue = undefined;
+                this.remount();
+                return;
+            }
+            try {
+                this.configValue = JSON.parse(value);
+                this.remount();
+            }
+            catch {
+                this.reportConfigurationError();
+            }
+        }
+        unmount() {
+            this.unsubscribe?.();
+            this.unsubscribe = undefined;
+            this.core?.dispose();
+            this.core = undefined;
+            this.replaceChildren();
+        }
+        remount() {
+            this.unmount();
+            this.lastDecisionId = undefined;
+            this.lastErrorKey = undefined;
+            this.cancelledDispatched = false;
+            if (!this.isConnected || !this.configValue)
+                return;
+            const validation = validateCareCompassConfig(this.configValue);
+            if (!validation.ok) {
+                this.reportConfigurationError();
+                return;
+            }
+            this.core = createCodingFlow(validation.config, {
+                onAuditEvent: (event) => this.dispatchMetadataEvent("carecompass-audit", event),
+                onSafetyEvent: (event) => this.dispatchMetadataEvent("carecompass-safety", event),
+                runtimeTokenProvider: this.runtimeTokenProviderValue,
+                reviewerAuthProvider: this.reviewerAuthProviderValue,
+            });
+            this.unsubscribe = this.core.subscribe((snapshot) => this.renderSnapshot(validation.config, snapshot));
+            this.renderSnapshot(validation.config, this.core.getSnapshot());
+        }
+        dispatchMetadataEvent(name, event) {
+            // Core audit and safety records intentionally contain metadata only;
+            // never interpolate case content into DOM events.
+            this.dispatchEvent(new CustomEvent(name, {
+                bubbles: true,
+                detail: event,
+            }));
+        }
+        renderSnapshot(config, snapshot) {
+            const section = document.createElement("section");
+            section.setAttribute("aria-label", `${config.labels.title} coding review`);
+            Object.assign(section.style, {
+                background: config.theme.backgroundColor,
+                border: `1px solid ${config.theme.primaryColor}`,
+                borderRadius: config.theme.borderRadius,
+                color: config.theme.textColor,
+                fontFamily: config.theme.fontFamily,
+                maxWidth: "720px",
+                padding: "20px",
+            });
+            const header = document.createElement("header");
+            const brand = document.createElement("strong");
+            brand.textContent = config.branding.displayName;
+            header.append(brand);
+            if (snapshot.packId) {
+                const pack = document.createElement("span");
+                pack.textContent = ` · ${snapshot.packId}`;
+                pack.style.fontSize = "12px";
+                pack.style.opacity = "0.72";
+                header.append(pack);
+            }
+            section.append(header);
+            const showSubmission = this.initialCaseValue !== undefined &&
+                snapshot.phase !== "submitting" &&
+                snapshot.phase !== "polling";
+            if (showSubmission) {
+                const submit = document.createElement("button");
+                submit.textContent = CARECOMPASS_CODING_DECISION_LABELS.prepare;
+                submit.type = "button";
+                submit.disabled = snapshot.loading;
+                Object.assign(submit.style, {
+                    background: config.theme.primaryColor,
+                    color: "#ffffff",
+                    border: "0",
+                    borderRadius: "6px",
+                    padding: "8px 12px",
+                });
+                submit.addEventListener("click", () => void this.submit());
+                section.append(submit);
+            }
+            if (snapshot.loading) {
+                const status = document.createElement("p");
+                status.setAttribute("role", "status");
+                status.setAttribute("aria-live", "polite");
+                status.textContent = "Preparing coding review…";
+                if (snapshot.cancelable) {
+                    const cancel = document.createElement("button");
+                    cancel.textContent = CARECOMPASS_CODING_DECISION_LABELS.cancel;
+                    cancel.type = "button";
+                    cancel.style.marginLeft = "8px";
+                    cancel.style.fontSize = "12px";
+                    cancel.addEventListener("click", () => void this.cancel());
+                    status.append(cancel);
+                }
+                section.append(status);
+            }
+            if (snapshot.error) {
+                const error = document.createElement("p");
+                error.setAttribute("role", "alert");
+                error.textContent = snapshot.error.message;
+                error.style.color = "#b91c1c";
+                error.style.fontSize = "13px";
+                section.append(error);
+                if (snapshot.canRetry) {
+                    const retry = document.createElement("button");
+                    retry.textContent = CARECOMPASS_CODING_DECISION_LABELS.retry;
+                    retry.type = "button";
+                    retry.style.fontSize = "12px";
+                    retry.addEventListener("click", () => void this.retry());
+                    section.append(retry);
+                }
+            }
+            if (snapshot.phase === "cancelled") {
+                const cancelled = document.createElement("p");
+                cancelled.setAttribute("role", "status");
+                cancelled.textContent = CARECOMPASS_CODING_DECISION_LABELS.cancelled;
+                section.append(cancelled);
+            }
+            if (snapshot.decision) {
+                const decision = snapshot.decision;
+                const result = document.createElement("div");
+                result.setAttribute("aria-live", "polite");
+                result.setAttribute("role", "region");
+                result.setAttribute("aria-label", "Coding decision result");
+                const boundary = document.createElement("p");
+                boundary.setAttribute("role", "alert");
+                boundary.textContent = decisionRequiresHumanReview(decision)
+                    ? CARECOMPASS_CODING_DECISION_LABELS.humanReviewRequired
+                    : decisionPrimaryState(decision);
+                result.append(boundary);
+                const rationale = document.createElement("p");
+                rationale.textContent = decision.rationale;
+                result.append(rationale);
+                if (decision.lineDecisions.length > 0) {
+                    const lines = document.createElement("section");
+                    const heading = document.createElement("h3");
+                    heading.textContent = "Line decisions";
+                    const list = document.createElement("ul");
+                    for (const line of decision.lineDecisions) {
+                        const item = document.createElement("li");
+                        item.textContent = line.rationale;
+                        const strong = document.createElement("strong");
+                        strong.textContent = defaultLineLabel(line);
+                        item.prepend(strong, document.createTextNode(" — "));
+                        list.append(item);
+                    }
+                    lines.append(heading, list);
+                    result.append(lines);
+                }
+                const gaps = decisionGaps(decision);
+                if (gaps.length > 0) {
+                    const gapSection = document.createElement("section");
+                    const heading = document.createElement("h3");
+                    heading.textContent = "Gaps";
+                    const list = document.createElement("ul");
+                    for (const gap of gaps) {
+                        const item = document.createElement("li");
+                        const strong = document.createElement("strong");
+                        strong.textContent = gap.type;
+                        item.append(strong, document.createTextNode(` (${gap.severity}) — ${gap.description}`));
+                        list.append(item);
+                    }
+                    gapSection.append(heading, list);
+                    result.append(gapSection);
+                }
+                const conflicts = decisionConflicts(decision);
+                if (conflicts.length > 0) {
+                    const conflictSection = document.createElement("section");
+                    const heading = document.createElement("h3");
+                    heading.textContent = "Conflicts";
+                    const list = document.createElement("ul");
+                    for (const conflict of conflicts) {
+                        const item = document.createElement("li");
+                        const strong = document.createElement("strong");
+                        strong.textContent = conflict.type;
+                        item.append(strong, document.createTextNode(` — ${conflict.summary}`));
+                        list.append(item);
+                    }
+                    conflictSection.append(heading, list);
+                    result.append(conflictSection);
+                }
+                if (decision.evidenceItems?.length) {
+                    const evidenceSection = document.createElement("section");
+                    evidenceSection.setAttribute("aria-label", "Supporting evidence");
+                    const heading = document.createElement("h3");
+                    heading.textContent = "Supporting evidence";
+                    const list = document.createElement("ul");
+                    for (const evidence of decision.evidenceItems) {
+                        const item = document.createElement("li");
+                        const strong = document.createElement("strong");
+                        strong.textContent = `${evidence.source}${evidence.sourceVersion
+                            ? ` (version ${evidence.sourceVersion})`
+                            : ""}`;
+                        item.append(strong, document.createTextNode(` — ${evidence.excerpt}`));
+                        list.append(item);
+                    }
+                    evidenceSection.append(heading, list);
+                    result.append(evidenceSection);
+                }
+                const reviewerForm = document.createElement("form");
+                const fieldset = document.createElement("fieldset");
+                fieldset.disabled = !this.reviewerIdValue;
+                const legend = document.createElement("legend");
+                legend.textContent = "Record reviewer action";
+                const actionLabel = document.createElement("label");
+                actionLabel.textContent = "Action ";
+                const action = document.createElement("select");
+                action.setAttribute("aria-label", "Reviewer action");
+                for (const [value, label] of [
+                    ["", "Select…"],
+                    ["approved", "Approved"],
+                    ["rejected", "Rejected"],
+                    ["escalated", "Escalated"],
+                ]) {
+                    const option = document.createElement("option");
+                    option.value = value;
+                    option.textContent = label;
+                    option.disabled = value === "";
+                    option.selected = value === "";
+                    action.append(option);
+                }
+                actionLabel.append(action);
+                const notesLabel = document.createElement("label");
+                notesLabel.textContent = "Notes ";
+                const notes = document.createElement("textarea");
+                notes.setAttribute("aria-label", "Reviewer notes");
+                notes.rows = 2;
+                notesLabel.append(notes);
+                const record = document.createElement("button");
+                record.type = "submit";
+                record.disabled = true;
+                record.textContent = CARECOMPASS_CODING_DECISION_LABELS.recordAction;
+                const recordStatus = document.createElement("p");
+                recordStatus.setAttribute("aria-live", "polite");
+                recordStatus.style.fontSize = "12px";
+                action.addEventListener("change", () => {
+                    record.disabled = action.value === "";
+                });
+                reviewerForm.addEventListener("submit", (event) => {
+                    event.preventDefault();
+                    const reviewerId = this.reviewerIdValue;
+                    if (!action.value || !reviewerId)
+                        return;
+                    fieldset.disabled = true;
+                    record.textContent = "Recording…";
+                    const reviewerAction = {
+                        reviewerId,
+                        ...(this.reviewerRoleValue
+                            ? { reviewerRole: this.reviewerRoleValue }
+                            : {}),
+                        action: action.value,
+                        ...(notes.value.trim() ? { notes: notes.value.trim() } : {}),
+                        occurredAt: new Date().toISOString(),
+                    };
+                    void this.core
+                        ?.recordReviewerAction(decision.decisionId, reviewerAction)
+                        .then((recorded) => {
+                        recordStatus.setAttribute("role", "status");
+                        recordStatus.textContent = `${CARECOMPASS_CODING_DECISION_LABELS.actionRecorded} ${new Date().toISOString()}.`;
+                        this.dispatchMetadataEvent("carecompass-reviewer-action", recorded);
+                    })
+                        .catch((caught) => {
+                        const flowError = {
+                            code: "reviewer_action_failed",
+                            message: caught instanceof Error
+                                ? caught.message
+                                : "The reviewer action could not be recorded.",
+                        };
+                        recordStatus.setAttribute("role", "alert");
+                        recordStatus.textContent = flowError.message;
+                        this.dispatchMetadataEvent("carecompass-error", flowError);
+                    })
+                        .finally(() => {
+                        fieldset.disabled = !this.reviewerIdValue;
+                        record.textContent =
+                            CARECOMPASS_CODING_DECISION_LABELS.recordAction;
+                    });
+                });
+                fieldset.append(legend, actionLabel, notesLabel, record);
+                if (!this.reviewerIdValue) {
+                    const identityRequired = document.createElement("p");
+                    identityRequired.setAttribute("role", "note");
+                    identityRequired.textContent =
+                        "A reviewer ID is required to record an action.";
+                    reviewerForm.append(identityRequired);
+                }
+                reviewerForm.append(fieldset, recordStatus);
+                result.append(reviewerForm);
+                section.append(result);
+            }
+            this.replaceChildren(section);
+            this.dispatchTerminalEvents(snapshot);
+        }
+        dispatchTerminalEvents(snapshot) {
+            if (snapshot.error) {
+                const errorKey = `${snapshot.error.code}:${snapshot.error.message}`;
+                if (errorKey !== this.lastErrorKey) {
+                    this.lastErrorKey = errorKey;
+                    this.dispatchMetadataEvent("carecompass-error", snapshot.error);
+                }
+            }
+            else {
+                this.lastErrorKey = undefined;
+            }
+            if (snapshot.phase === "cancelled") {
+                if (!this.cancelledDispatched) {
+                    this.cancelledDispatched = true;
+                    this.dispatchMetadataEvent("carecompass-cancelled", {
+                        packId: snapshot.packId,
+                    });
+                }
+            }
+            else {
+                this.cancelledDispatched = false;
+            }
+            if (snapshot.decision) {
+                if (snapshot.decision.decisionId !== this.lastDecisionId) {
+                    this.lastDecisionId = snapshot.decision.decisionId;
+                    this.dispatchMetadataEvent("carecompass-decision", snapshot.decision);
+                }
+            }
+            else {
+                this.lastDecisionId = undefined;
+            }
+        }
+        async submit() {
+            if (!this.core || !this.packIdValue || !this.initialCaseValue)
+                return;
+            try {
+                await this.core.submit(this.packIdValue, this.initialCaseValue);
+            }
+            catch {
+                // The snapshot already carries the safe, user-visible error state.
+            }
+        }
+        async cancel() {
+            if (!this.core)
+                return;
+            try {
+                await this.core.cancel();
+            }
+            catch {
+                // The snapshot already carries the safe cancellation state.
+            }
+        }
+        async retry() {
+            if (!this.core)
+                return;
+            try {
+                await this.core.retryLast();
+            }
+            catch {
+                // The snapshot already carries the safe failure state.
+            }
+        }
+        reportConfigurationError() {
+            this.dispatchEvent(new CustomEvent("carecompass-error", {
+                bubbles: true,
+                detail: { code: "configuration_invalid" },
+            }));
+        }
+    }
+    customElements.define(tagName, CodingReviewElement);
+    return CodingReviewElement;
+}
+function defaultLineLabel(line) {
+    const unitPart = line.units?.count !== undefined
+        ? ` x${line.units.count}${line.units.unitOfMeasure ? ` ${line.units.unitOfMeasure}` : ""}`
+        : "";
+    return [
+        line.action,
+        line.code.codeSystem,
+        line.code.code,
+        line.modifiers?.length ? ` (${line.modifiers.join(", ")})` : "",
+        unitPart,
+    ]
+        .filter(Boolean)
+        .join(" ");
+}

package/dist/coding-ui.d.ts

@@ -0,0 +1,62 @@
+import React from "react";
+import type { CodingCase, CodingDecision, CodingReviewerAction } from "@nexalink/coding-contracts";
+import { type CodingDecisionLabels, type CodingFlow, type CodingFlowOptions, type CodingFlowSnapshot, type TypedCodingGap } from "./coding.js";
+import type { CareCompassAuditListener, CareCompassSafetyListener } from "./compliance.js";
+import type { CareCompassReviewerAuthProvider, CareCompassRuntimeTokenProvider } from "./client.js";
+import type { CareCompassConfig } from "./schema.js";
+export type CodingDecisionLine = NonNullable<CodingDecision["lineDecisions"]>[number];
+export type CodingReviewRenderProps = {
+    renderDecision?: (decision: CodingDecision, content: React.ReactNode) => React.ReactNode;
+    renderLineDecision?: (line: CodingDecisionLine) => React.ReactNode;
+    renderGap?: (gap: TypedCodingGap) => React.ReactNode;
+};
+export type EvidenceEngagementAction = "opened" | "copied";
+export type CodingReviewProps = {
+    config: CareCompassConfig;
+    flow?: CodingFlow;
+    initialCase?: CodingCase;
+    labels?: Partial<CodingDecisionLabels>;
+    onAuditEvent?: CareCompassAuditListener;
+    onCodingDecision?: (decision: CodingDecision) => void;
+    onSafetyEvent?: CareCompassSafetyListener;
+    packId?: string;
+    pollIntervalMs?: number;
+    reviewerId?: string;
+    reviewerRole?: string;
+    reviewerAuthProvider?: CareCompassReviewerAuthProvider;
+    runtimeTokenProvider?: CareCompassRuntimeTokenProvider;
+} & CodingReviewRenderProps;
+export declare function CareCompassCodingReviewContent({ config, flow, initialCase, labels: labelsOverride, onCodingDecision, packId, renderDecision, renderGap, renderLineDecision, reviewerId, reviewerRole, snapshot, }: {
+    config: CareCompassConfig;
+    flow: CodingFlow;
+    initialCase?: CodingCase;
+    labels?: Partial<CodingDecisionLabels>;
+    onCodingDecision?: (decision: CodingDecision) => void;
+    packId?: string;
+    reviewerId?: string;
+    reviewerRole?: string;
+    snapshot: CodingFlowSnapshot;
+} & CodingReviewRenderProps): React.JSX.Element;
+export declare function CodingReview({ config, flow: flowProp, initialCase, labels, onAuditEvent, onCodingDecision, onSafetyEvent, packId, pollIntervalMs, renderDecision, renderGap, renderLineDecision, reviewerId, reviewerRole, reviewerAuthProvider, runtimeTokenProvider, }: CodingReviewProps): React.JSX.Element | null;
+export type UseCodingReviewResult = {
+    cancel: () => Promise<CodingFlowSnapshot>;
+    flow: CodingFlow;
+    recordReviewerAction: (decisionId: string, action: CodingReviewerAction) => Promise<{
+        recorded: true;
+        reviewerAction: Record<string, unknown>;
+    }>;
+    retryLast: () => Promise<CodingFlowSnapshot>;
+    snapshot: CodingFlowSnapshot;
+    submit: (packId: string, codingCase: CodingCase) => Promise<CodingFlowSnapshot>;
+};
+/** React adapter for the headless coding flow. Renders nothing itself. */
+export declare function useCodingReview(config: CareCompassConfig, options?: CodingFlowOptions): UseCodingReviewResult;
+export declare function mountCodingReview(element: Element | null, config: CareCompassConfig, options?: {
+    initialCase?: CodingCase;
+    onCodingDecision?: (decision: CodingDecision) => void;
+    packId?: string;
+    reviewerAuthProvider?: CareCompassReviewerAuthProvider;
+    runtimeTokenProvider?: CareCompassRuntimeTokenProvider;
+}): {
+    unmount: () => void;
+};