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

package/dist/compliance.js

@@ -0,0 +1,121 @@
+export const CARECOMPASS_COMPLIANCE_PRESETS = {
+    // Standard is intentionally non-mutating for existing integrations. Detection
+    // can still drive a safety callback when the host opts into one.
+    standard: {
+        auditEnabled: false,
+        phiAction: "allow",
+        replacement: "[REDACTED]",
+    },
+    // Healthcare protects browser-visible requests and retains metadata-only audit
+    // records. It is the recommended starting point for PHI-oriented deployments.
+    healthcare: {
+        auditEnabled: true,
+        phiAction: "redact",
+        replacement: "[REDACTED]",
+    },
+    // Strict is appropriate when the host must stop detectable PHI before it leaves
+    // the browser. It may reject legitimate identifier-bearing workflow requests.
+    strict: {
+        auditEnabled: true,
+        phiAction: "block",
+        replacement: "[REDACTED]",
+    },
+};
+const PHI_PATTERNS = [
+    { category: "email", pattern: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi },
+    { category: "ssn", pattern: /\b\d{3}-\d{2}-\d{4}\b/g },
+    {
+        category: "phone",
+        pattern: /(?:\+1[ .-]?)?(?:\(?\d{3}\)?[ .-]?)\d{3}[ .-]\d{4}\b/g,
+    },
+    {
+        category: "date_of_birth",
+        pattern: /\b(?:dob|date of birth|birth date)\s*[:#-]?\s*(?:\d{1,2}[/-]\d{1,2}[/-]\d{2,4}|\d{4}[/-]\d{1,2}[/-]\d{1,2})\b/gi,
+    },
+    {
+        category: "medical_record_number",
+        pattern: /\b(?:mrn|medical record(?: number)?)\s*[:#-]?\s*[A-Z0-9-]{3,}\b/gi,
+    },
+    {
+        category: "member_id",
+        pattern: /\b(?:member|patient|policy|subscriber)(?:\s+(?:id|number))?\s*[:#-]?\s*[A-Z0-9-]{3,}\b/gi,
+    },
+];
+const PHI_CATEGORIES = new Set([
+    "date_of_birth",
+    "email",
+    "medical_record_number",
+    "member_id",
+    "phone",
+    "ssn",
+]);
+const validMatches = (value, matches) => matches
+    .filter((match) => PHI_CATEGORIES.has(match.category) &&
+    Number.isInteger(match.start) &&
+    Number.isInteger(match.end) &&
+    match.start >= 0 &&
+    match.end > match.start &&
+    match.end <= value.length)
+    .sort((a, b) => a.start - b.start || b.end - a.end)
+    .filter((match, index, sorted) => index === 0 || match.start >= sorted[index - 1].end);
+export const detectCareCompassPhi = (value) => {
+    const matches = [];
+    for (const { category, pattern } of PHI_PATTERNS) {
+        pattern.lastIndex = 0;
+        for (const match of value.matchAll(pattern)) {
+            const start = match.index;
+            if (start === undefined)
+                continue;
+            matches.push({ category, start, end: start + match[0].length });
+        }
+    }
+    return validMatches(value, matches);
+};
+export const redactCareCompassPhi = (value, matches, replacement) => {
+    let redacted = value;
+    for (const match of [...matches].sort((a, b) => b.start - a.start)) {
+        redacted = `${redacted.slice(0, match.start)}${replacement}${redacted.slice(match.end)}`;
+    }
+    return redacted;
+};
+export const resolveCareCompassCompliancePolicy = (config) => {
+    const preset = config?.preset ?? "standard";
+    const defaults = CARECOMPASS_COMPLIANCE_PRESETS[preset];
+    return {
+        preset,
+        auditEnabled: config?.audit?.enabled ?? defaults.auditEnabled,
+        phiAction: config?.phi?.action ?? defaults.phiAction,
+        replacement: config?.phi?.replacement ?? defaults.replacement,
+    };
+};
+export const phiSummary = (matches) => ({
+    categories: [...new Set(matches.map((match) => match.category))].sort(),
+    count: matches.length,
+});
+export const sanitizeCareCompassValue = (value, source, policy, hooks) => {
+    if (typeof value === "string") {
+        const matches = validMatches(value, (hooks?.detect ?? detectCareCompassPhi)(value, { source }));
+        if (policy.phiAction !== "redact" || matches.length === 0) {
+            return { matches, value };
+        }
+        return {
+            matches,
+            value: (hooks?.redact ?? redactCareCompassPhi)(value, matches, policy.replacement),
+        };
+    }
+    if (Array.isArray(value)) {
+        const entries = value.map((entry) => sanitizeCareCompassValue(entry, source, policy, hooks));
+        return {
+            matches: entries.flatMap((entry) => entry.matches),
+            value: entries.map((entry) => entry.value),
+        };
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).map(([key, entry]) => [key, sanitizeCareCompassValue(entry, source, policy, hooks)]);
+        return {
+            matches: entries.flatMap(([, entry]) => entry.matches),
+            value: Object.fromEntries(entries.map(([key, entry]) => [key, entry.value])),
+        };
+    }
+    return { matches: [], value };
+};

package/dist/component.d.ts

@@ -1,5 +1,35 @@
+import React from "react";
+import { type CareCompassContext, type CareCompassCore, type CareCompassCoreEvent, type CareCompassCoreOptions, type CareCompassCoreSnapshot, type CareCompassMessage, type CareCompassSendMessageOptions } from "./core.js";
+import type { CareCompassRuntimeTokenProvider } from "./client.js";
 import type { CareCompassConfig } from "./schema.js";
-export declare function CareCompassEmbed({ config, pollIntervalMs, }: {
+import type { CareCompassAuditListener, CareCompassSafetyListener } from "./compliance.js";
+export type CareCompassChatProps = {
     config: CareCompassConfig;
+    initialContext?: CareCompassContext;
+    onAuditEvent?: CareCompassAuditListener;
+    onEvent?: (event: CareCompassCoreEvent) => void;
+    onSafetyEvent?: CareCompassSafetyListener;
     pollIntervalMs?: number;
-}): import("react/jsx-runtime").JSX.Element;
+    renderMessage?: (message: CareCompassMessage) => React.ReactNode;
+    retryLabel?: string;
+    runtimeTokenProvider?: CareCompassRuntimeTokenProvider;
+};
+/** Options for the headless React hook. Keep object-valued options stable with
+ * `useMemo` when the calling component rerenders. */
+export type UseCareCompassOptions = CareCompassCoreOptions;
+export type CareCompassReactController = {
+    core: CareCompassCore;
+    snapshot: CareCompassCoreSnapshot;
+    sendMessage: (prompt: string, options?: CareCompassSendMessageOptions) => Promise<CareCompassCoreSnapshot>;
+    streamMessage: CareCompassCore["streamMessage"];
+    retryLast: CareCompassCore["retryLast"];
+    reset: CareCompassCore["reset"];
+    setContext: CareCompassCore["setContext"];
+};
+/**
+ * React adapter for the headless CareCompass core. It owns the core lifecycle
+ * and subscribes React to its snapshots, leaving hosts free to render any UI.
+ */
+export declare function useCareCompass(config: CareCompassConfig, options?: UseCareCompassOptions): CareCompassReactController;
+export declare function CareCompassChat({ config, initialContext, onAuditEvent, onEvent, onSafetyEvent, pollIntervalMs, renderMessage, retryLabel, runtimeTokenProvider, }: CareCompassChatProps): React.JSX.Element;
+export declare const CareCompassEmbed: typeof CareCompassChat;

package/dist/component.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
-import { createCareCompassClient } from "./client.js";
+import { createCareCompassCore, } from "./core.js";
+import { CareCompassMarkdown } from "./markdown.js";
 import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassTelemetry, } from "./telemetry.js";
 // The embed should fail closed inside the host page: show the configured
 // fallback text, capture sanitized telemetry, and avoid crashing the integrator.
@@ -25,71 +26,115 @@ class CareCompassErrorBoundary extends React.Component {
         return this.props.children;
     }
 }
-function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, }) {
-    const client = React.useMemo(() => createCareCompassClient(config), [config]);
-    const [messages, setMessages] = React.useState([
-        {
-            id: "welcome",
-            role: "assistant",
-            text: config.prompt.welcomeMessage,
-        },
+/**
+ * React adapter for the headless CareCompass core. It owns the core lifecycle
+ * and subscribes React to its snapshots, leaving hosts free to render any UI.
+ */
+export function useCareCompass(config, options = {}) {
+    const { compliance, fetcher, initialContext, now, onAuditEvent, onSafetyEvent, pollIntervalMs, runtimeTokenProvider, timeoutMs, } = options;
+    const core = React.useMemo(() => createCareCompassCore(config, {
+        compliance,
+        fetcher,
+        initialContext,
+        now,
+        onAuditEvent,
+        onSafetyEvent,
+        pollIntervalMs,
+        runtimeTokenProvider,
+        timeoutMs,
+    }), [
+        compliance,
+        config,
+        fetcher,
+        initialContext,
+        now,
+        onAuditEvent,
+        onSafetyEvent,
+        pollIntervalMs,
+        runtimeTokenProvider,
+        timeoutMs,
     ]);
+    const [snapshot, setSnapshot] = React.useState(() => core.getSnapshot());
+    React.useEffect(() => {
+        const unsubscribe = core.subscribe(setSnapshot);
+        setSnapshot(core.getSnapshot());
+        return () => {
+            unsubscribe();
+            core.dispose();
+        };
+    }, [core]);
+    return React.useMemo(() => ({
+        core,
+        snapshot,
+        sendMessage: core.sendMessage,
+        streamMessage: core.streamMessage,
+        retryLast: core.retryLast,
+        reset: core.reset,
+        setContext: core.setContext,
+    }), [core, snapshot]);
+}
+function CareCompassChatContent({ config, initialContext, onAuditEvent, onEvent, onSafetyEvent, telemetry, pollIntervalMs = 1500, renderMessage, retryLabel = "Retry", runtimeTokenProvider, }) {
+    const core = React.useMemo(() => createCareCompassCore(config, {
+        initialContext,
+        onAuditEvent,
+        onSafetyEvent,
+        pollIntervalMs,
+        runtimeTokenProvider,
+    }), [
+        config,
+        initialContext,
+        onAuditEvent,
+        onSafetyEvent,
+        pollIntervalMs,
+        runtimeTokenProvider,
+    ]);
+    const [snapshot, setSnapshot] = React.useState(() => core.getSnapshot());
     const [input, setInput] = React.useState("");
-    const [loading, setLoading] = React.useState(false);
-    const [error, setError] = React.useState(null);
     React.useEffect(() => {
         telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_RENDERED);
         telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_OPENED);
+        const unsubscribe = core.subscribe(setSnapshot);
+        setSnapshot(core.getSnapshot());
         return () => {
+            unsubscribe();
+            core.dispose();
             telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_CLOSED);
         };
-    }, [telemetry]);
+    }, [core, telemetry]);
     async function sendMessage(event) {
         event.preventDefault();
         const prompt = input.trim();
-        if (!prompt || loading)
+        if (!prompt || snapshot.loading)
             return;
         setInput("");
-        setError(null);
-        setLoading(true);
-        setMessages((current) => [
-            ...current,
-            { id: `user-${Date.now()}`, role: "user", text: prompt },
-        ]);
         try {
-            const { jobId } = await client.ask({ prompt });
-            const startedAt = Date.now();
-            // The backend returns a job immediately, so the component polls until it
-            // sees a terminal state or reaches the same timeout tracked by telemetry.
-            while (Date.now() - startedAt < 120_000) {
-                const status = await client.status(jobId);
-                if (status.status === "complete" && status.result) {
-                    setMessages((current) => [
-                        ...current,
-                        {
-                            id: `assistant-${Date.now()}`,
-                            role: "assistant",
-                            text: status.result ?? "",
-                        },
-                    ]);
-                    return;
-                }
-                if (status.status === "failed") {
-                    throw new Error(status.result ?? config.labels.errorMessage);
-                }
-                await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            core.recordWidgetAction();
+            for await (const coreEvent of core.streamMessage(prompt)) {
+                onEvent?.(coreEvent);
             }
-            client.recordInferenceTimeout(jobId, Date.now() - startedAt);
-            throw new Error("CareCompass request timed out.");
         }
-        catch (err) {
-            setError(err?.message ??
-                config.labels.errorMessage);
+        catch {
+            // The core snapshot already carries the user-visible error and retry
+            // state. Swallow here so host pages do not see unhandled form errors.
         }
-        finally {
-            setLoading(false);
+    }
+    async function retryMessage() {
+        try {
+            core.recordWidgetAction();
+            await core.retryLast();
+        }
+        catch {
+            // The core owns the visible retry failure state.
         }
     }
+    const messageContent = (message) => {
+        if (renderMessage)
+            return renderMessage(message);
+        if (message.role === "assistant") {
+            return _jsx(CareCompassMarkdown, { text: message.text });
+        }
+        return message.text;
+    };
     return (_jsxs("section", { "aria-label": config.labels.title, style: {
             "--carecompass-primary": config.theme.primaryColor,
             "--carecompass-bg": config.theme.backgroundColor,
@@ -118,7 +163,7 @@ function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, })
                     gap: 12,
                     overflowY: "auto",
                     padding: 16,
-                }, children: [messages.map((message) => (_jsx("div", { style: {
+                }, children: [snapshot.messages.map((message) => (_jsx("div", { style: {
                             alignSelf: message.role === "user" ? "flex-end" : "flex-start",
                             background: message.role === "user"
                                 ? "var(--carecompass-primary)"
@@ -127,14 +172,14 @@ function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, })
                             color: message.role === "user" ? "#ffffff" : "inherit",
                             maxInlineSize: "82%",
                             padding: "10px 12px",
-                            whiteSpace: "pre-wrap",
-                        }, children: message.text }, message.id))), loading ? (_jsx("div", { style: { fontSize: 13, opacity: 0.72 }, children: "Thinking..." })) : null] }), _jsxs("form", { onSubmit: sendMessage, style: {
+                            whiteSpace: message.role === "user" ? "pre-wrap" : "normal",
+                        }, children: messageContent(message) }, message.id))), snapshot.loading ? (_jsx("div", { style: { fontSize: 13, opacity: 0.72 }, children: "Thinking..." })) : null] }), _jsxs("form", { onSubmit: sendMessage, style: {
                     borderTop: "1px solid color-mix(in srgb, var(--carecompass-text) 12%, transparent)",
                     display: "flex",
                     flexDirection: "column",
                     gap: 8,
                     padding: 12,
-                }, children: [_jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsx("input", { "aria-label": config.labels.placeholder, disabled: loading, onChange: (event) => setInput(event.currentTarget.value), placeholder: config.labels.placeholder, style: {
+                }, children: [_jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsx("input", { "aria-label": config.labels.placeholder, disabled: snapshot.loading, onChange: (event) => setInput(event.currentTarget.value), placeholder: config.labels.placeholder, style: {
                                     border: "1px solid color-mix(in srgb, var(--carecompass-text) 16%, transparent)",
                                     borderRadius: 8,
                                     color: "inherit",
@@ -142,20 +187,36 @@ function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, })
                                     font: "inherit",
                                     minInlineSize: 0,
                                     padding: "10px 12px",
-                                }, value: input }), _jsx("button", { disabled: loading || !input.trim(), style: {
+                                }, value: input }), _jsx("button", { disabled: snapshot.loading || !input.trim(), style: {
                                     background: "var(--carecompass-primary)",
                                     border: 0,
                                     borderRadius: 8,
                                     color: "#ffffff",
-                                    cursor: loading ? "not-allowed" : "pointer",
+                                    cursor: snapshot.loading ? "not-allowed" : "pointer",
                                     font: "inherit",
                                     fontWeight: 700,
                                     padding: "0 14px",
-                                }, type: "submit", children: config.labels.sendButton })] }), error ? (_jsx("div", { role: "alert", style: { color: "#b91c1c", fontSize: 12 }, children: error })) : null, _jsx("div", { style: { fontSize: 11, opacity: 0.7 }, children: config.labels.disclaimer })] })] }));
+                                }, type: "submit", children: config.labels.sendButton })] }), snapshot.error ? (_jsxs("div", { role: "alert", style: {
+                            alignItems: "center",
+                            color: "#b91c1c",
+                            display: "flex",
+                            flexWrap: "wrap",
+                            fontSize: 12,
+                            gap: 8,
+                        }, children: [_jsx("span", { children: snapshot.error.message }), snapshot.canRetry ? (_jsx("button", { onClick: retryMessage, style: {
+                                    background: "transparent",
+                                    border: "1px solid color-mix(in srgb, #b91c1c 40%, transparent)",
+                                    borderRadius: 6,
+                                    color: "#b91c1c",
+                                    cursor: "pointer",
+                                    font: "inherit",
+                                    padding: "4px 8px",
+                                }, type: "button", children: retryLabel })) : null] })) : null, _jsx("div", { style: { fontSize: 11, opacity: 0.7 }, children: config.labels.disclaimer })] })] }));
 }
-export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
+export function CareCompassChat({ config, initialContext, onAuditEvent, onEvent, onSafetyEvent, pollIntervalMs = 1500, renderMessage, retryLabel, runtimeTokenProvider, }) {
     // Telemetry is scoped to the validated public config; no per-message content
     // is passed through this component-level telemetry object.
     const telemetry = React.useMemo(() => createCareCompassTelemetry(config), [config]);
-    return (_jsx(CareCompassErrorBoundary, { config: config, telemetry: telemetry, children: _jsx(CareCompassEmbedContent, { config: config, pollIntervalMs: pollIntervalMs, telemetry: telemetry }) }));
+    return (_jsx(CareCompassErrorBoundary, { config: config, telemetry: telemetry, children: _jsx(CareCompassChatContent, { config: config, initialContext: initialContext, onAuditEvent: onAuditEvent, onEvent: onEvent, onSafetyEvent: onSafetyEvent, pollIntervalMs: pollIntervalMs, renderMessage: renderMessage, retryLabel: retryLabel, runtimeTokenProvider: runtimeTokenProvider, telemetry: telemetry }) }));
 }
+export const CareCompassEmbed = CareCompassChat;

package/dist/core.d.ts

@@ -0,0 +1,95 @@
+import { type CareCompassRuntimeTokenProvider, type CareCompassStatusResponse, type CareCompassWorkflowId } from "./client.js";
+import { type CareCompassAuditEvent, type CareCompassAuditListener, type CareCompassComplianceRuntimeOptions, type CareCompassSafetyDecision, type CareCompassSafetyListener } from "./compliance.js";
+import type { CareCompassConfig } from "./schema.js";
+type Fetcher = typeof fetch;
+export type CareCompassContext = Record<string, unknown>;
+export type CareCompassMessage = {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    createdAt: number;
+    status: "complete" | "failed" | "pending";
+    retrieval?: CareCompassStatusResponse["retrieval"];
+};
+export type CareCompassLifecyclePhase = "idle" | "submitting" | "streaming" | "complete" | "error" | "disposed";
+export type CareCompassCoreErrorCode = "request_failed" | "safety_blocked" | "timeout" | "disposed";
+export type CareCompassCoreError = {
+    code: CareCompassCoreErrorCode;
+    message: string;
+};
+export type CareCompassRetryMetadata = {
+    prompt: string;
+    requestId?: string;
+    workflow?: CareCompassWorkflowId;
+    context: CareCompassContext;
+    attempts: number;
+};
+export type CareCompassCoreSnapshot = {
+    messages: CareCompassMessage[];
+    phase: CareCompassLifecyclePhase;
+    loading: boolean;
+    error: CareCompassCoreError | null;
+    context: CareCompassContext;
+    canRetry: boolean;
+    retry: CareCompassRetryMetadata | null;
+    activeJobId: string | null;
+};
+export type CareCompassCoreEvent = {
+    type: "message_submitted";
+    message: CareCompassMessage;
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "status";
+    jobId: string;
+    status: CareCompassStatusResponse["status"];
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "message_completed";
+    message: CareCompassMessage;
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "error";
+    error: CareCompassCoreError;
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "context_updated";
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "reset";
+    snapshot: CareCompassCoreSnapshot;
+};
+export type CareCompassCoreOptions = {
+    compliance?: CareCompassComplianceRuntimeOptions;
+    fetcher?: Fetcher;
+    initialContext?: CareCompassContext;
+    now?: () => number;
+    onAuditEvent?: CareCompassAuditListener;
+    onSafetyEvent?: CareCompassSafetyListener;
+    pollIntervalMs?: number;
+    runtimeTokenProvider?: CareCompassRuntimeTokenProvider;
+    timeoutMs?: number;
+};
+export type CareCompassSendMessageOptions = {
+    /** Reuse this value only when retrying the same hosted submission. */
+    requestId?: string;
+    workflow?: CareCompassWorkflowId;
+    context?: CareCompassContext;
+};
+export type CareCompassCore = {
+    exportAuditTrail: () => CareCompassAuditEvent[];
+    getSnapshot: () => CareCompassCoreSnapshot;
+    recordSafetyDecision: (decision: Exclude<CareCompassSafetyDecision, "redacted" | "blocked">, source?: "tool_call" | "widget_action") => void;
+    recordToolCall: (outcome?: "completed" | "failed") => void;
+    recordWidgetAction: (outcome?: "recorded" | "completed") => void;
+    subscribe: (listener: (snapshot: CareCompassCoreSnapshot) => void) => () => void;
+    subscribeAudit: (listener: CareCompassAuditListener) => () => void;
+    subscribeSafety: (listener: CareCompassSafetyListener) => () => void;
+    setContext: (context: CareCompassContext | ((current: CareCompassContext) => CareCompassContext)) => void;
+    sendMessage: (prompt: string, options?: CareCompassSendMessageOptions) => Promise<CareCompassCoreSnapshot>;
+    streamMessage: (prompt: string, options?: CareCompassSendMessageOptions) => AsyncIterable<CareCompassCoreEvent>;
+    retryLast: () => Promise<CareCompassCoreSnapshot>;
+    reset: () => void;
+    dispose: () => void;
+};
+export declare function createCareCompassCore(config: CareCompassConfig, options?: CareCompassCoreOptions): CareCompassCore;
+export {};