@nexalink/carecompass-sdk 0.4.0-beta.15 → 0.6.0

package/README.md

@@ -79,7 +79,7 @@ Nexalink-hosted CareCompass APIs
 CareCompass AI runtime
 ```
 
-The browser receives only public embed configuration: tenant identifier, environment, public embed key, allowed origins, branding, labels, theme, placement, and approved prompt settings.
+The browser receives only public embed configuration: tenant identifier, environment, public embed key, allowed origins, endpoint, model preferences, feature flags, branding, labels, theme, placement, compliance, and approved prompt settings.
 
 Secret API keys stay in CLI, server-side, or trusted setup workflows. The browser never receives model credentials or Nexalink API keys.
 
@@ -97,6 +97,7 @@ The core manages:
 - loading, error, timeout, and retry state
 - context injection
 - subscriptions for custom renderers
+- PHI preflight, safety callbacks, and metadata-only audit trails
 - endpoint calls and telemetry integration
 
 ```ts
@@ -172,7 +173,177 @@ Custom message rendering:
 />
 ```
 
-### 3. Existing Embed Compatibility
+### RCM coding-assistance pilot workflow
+
+The RCM kit is a narrow, structured coding-review workflow built on the same
+headless core, compliance preflight, and metadata-only audit events. It returns
+candidate codes for qualified human review; it never makes a final coding,
+billing, claim-submission, diagnosis, or treatment decision.
+
+The SDK sends `workflow: "rcm-coding-assistance"` as an explicit top-level ask
+field. The hosted runtime authorizes the workflow from the issued embed key and
+server-side tenant entitlement. Values in user context do not authorize a
+workflow.
+
+Development and staging RCM requests must include `claimContext.stage` set to
+the configured SDK environment (`"development"` or `"staging"`). Production
+may omit the field. The hosted runtime validates any supplied value against the
+authenticated key environment; this marker never grants workflow access.
+
+For the hosted RCM path, configure the tenant's RCM policy corpus in the
+CareCompass tenant portal before embedding: an authorized administrator must
+have an executed BAA, enable the RCM entitlement, set up the corpus, upload a
+customer-owned policy version, explicitly approve it, and wait for ingestion to
+become active. The browser sends structured encounter context only; it never
+sends a corpus ID, policy text, or policy references.
+
+```tsx
+import {
+  CARECOMPASS_RCM_SYNTHETIC_DEMO,
+  RcmCodingAssistant,
+} from "@nexalink/carecompass-sdk/rcm";
+
+<RcmCodingAssistant
+  config={config}
+  initialInput={CARECOMPASS_RCM_SYNTHETIC_DEMO}
+  workflowOptions={{
+    customerRules: { requirePolicySupport: true },
+    retrieval: "hosted",
+  }}
+  onAuditEvent={(event) => hostAudit(event)}
+  onSafetyEvent={(event) => hostSafetyMonitor(event)}
+/>;
+```
+
+The included demo input is synthetic and contains no patient data. Its same-day
+observation scenario is designed to retrieve the official CMS E/M evidence for
+CPT 99236 from the Nexalink base corpus. Tenant policies may supplement the
+base, but the runtime still requires an approved, active corpus and grounded
+citations before returning a candidate.
+
+A production tenant must have an executed BAA, an RCM entitlement, and a
+healthy active corpus; otherwise the hosted workflow fails closed with a
+structured human-review escalation.
+
+In hosted mode, the result's `policyReferences` are the sanitized citations
+resolved by the runtime. Render those citations alongside a coder-review
+suggestion. A `review_required` result requires policy support; empty retrieval,
+invalid citations, guardrail intervention, or invalid JSON becomes an
+`abstain`/`escalate` result with no recommendations. Hosts receive the normal
+metadata-only audit and safety events, including authorization, retrieval,
+validation, and escalation outcomes.
+
+For a customer-managed trusted retrieval boundary, pass an `RcmPolicyRetriever`
+instead of `"hosted"`. Its `approvedCorpusIds` allowlist is enforced by the SDK;
+unapproved or missing references produce a human-review escalation.
+
+To evaluate the pilot, compare **manual research minutes per case** before and
+after assisted, human-reviewed use. The target is to measure a 25% or greater
+reduction, not to make or submit a coding decision.
+
+### 3. React Hook
+
+Use `useCareCompass` when your React app needs its own visual design but does
+not want to manage subscriptions, retries, or teardown by hand.
+
+```tsx
+import { useCareCompass } from "@nexalink/carecompass-sdk/react";
+import config from "./carecompass/carecompass.config.json";
+
+export function CareCompassPanel() {
+  const { snapshot, sendMessage, retryLast } = useCareCompass(config, {
+    initialContext: { workflow: "member-portal" },
+    onSafetyEvent: (event) => monitorSafety(event),
+  });
+
+  return (
+    <section>
+      {snapshot.messages.map((message) => (
+        <p key={message.id}>{message.text}</p>
+      ))}
+      <button
+        disabled={snapshot.loading}
+        onClick={() => void sendMessage("Find an in-network doctor")}
+      >
+        Find care
+      </button>
+      {snapshot.canRetry && (
+        <button onClick={() => void retryLast()}>Retry</button>
+      )}
+    </section>
+  );
+}
+```
+
+The hook returns the underlying `core` for audit export, safety/audit
+subscriptions, tool/widget events, and the lifecycle `streamMessage` API.
+
+### 4. Web Component (Vue-compatible)
+
+The Web Component is rendered directly from the headless core and exposes a
+standard custom-element property, making it a good fit for Vue, Angular, CMS
+shells, and mixed-framework pages without requiring a React runtime. Register
+it only in the browser.
+
+```ts
+import { defineCareCompassElement } from "@nexalink/carecompass-sdk/web-component";
+
+defineCareCompassElement();
+```
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from "vue";
+import { defineCareCompassElement } from "@nexalink/carecompass-sdk/web-component";
+import config from "./carecompass/carecompass.config.json";
+
+const chat = ref<HTMLElement & { config?: typeof config }>();
+onMounted(() => {
+  defineCareCompassElement();
+  if (chat.value) chat.value.config = config;
+});
+</script>
+
+<template><carecompass-chat ref="chat" /></template>
+```
+
+For static hosts, the element also accepts a JSON `config` attribute. Prefer the
+property assignment above in application code: it avoids HTML escaping and keeps
+the configuration in your typed build pipeline.
+
+### 5. Script-tag Quickstart
+
+The existing `mountCareCompass` path remains supported for quick static pages
+and CMS integrations. Generate a script snippet from the same config:
+
+```ts
+import { generateCareCompassSnippet } from "@nexalink/carecompass-sdk";
+
+const html = generateCareCompassSnippet(config, { mode: "cdn" });
+```
+
+The generated module calls `mountCareCompass` and does not require a React app.
+
+### 6. Iframe Fallback
+
+Use an iframe when the host page needs strong CSS/JavaScript isolation or cannot
+run a module script. The CLI `init` flow generates an iframe page, or you can
+create the host markup with `generateCareCompassIframeSnippet(config)`.
+
+```ts
+import { generateCareCompassIframeSnippet } from "@nexalink/carecompass-sdk";
+
+const html = generateCareCompassIframeSnippet(config, {
+  src: "/carecompass/carecompass-embed.html",
+});
+```
+
+An iframe isolates page styles and scripts, but it adds a separate document for
+focus management, analytics, responsive sizing, and host-to-widget context.
+Choose the React hook or Web Component when the assistant needs rich in-page
+coordination; choose the iframe for constrained or high-isolation environments.
+
+### 7. Existing Embed Compatibility
 
 Existing embed integrations can keep using the root package exports.
 
@@ -192,6 +363,40 @@ import config from "./carecompass/carecompass.config.json";
 mountCareCompass(document.getElementById("carecompass-root"), config);
 ```
 
+### Production runtime tokens
+
+Production embeds require a fresh runtime token from an integrator-controlled
+backend-for-frontend (BFF). Do not place a Nexalink API key, runtime-token
+secret, or a reusable token in `carecompass.config.json` or browser code.
+
+Provide `runtimeTokenProvider`; the SDK calls it before validation, every
+inference request, and every status poll. The provider should call your BFF,
+which holds the Nexalink API key and obtains a short-lived token for the
+current browser origin and workflow.
+
+```tsx
+const runtimeTokenProvider = async ({ workflow }: { workflow?: string }) => {
+  const response = await fetch("/api/carecompass/runtime-token", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ workflow }),
+  });
+  if (!response.ok) throw new Error("Could not authorize CareCompass.");
+  return ((await response.json()) as { token: string }).token;
+};
+
+<CareCompassEmbed
+  config={config}
+  runtimeTokenProvider={runtimeTokenProvider}
+/>;
+```
+
+For static hosts, pass the provider as the third argument to
+`mountCareCompass`. For Web Components, assign it to the
+`runtimeTokenProvider` property before setting `config`. Production requests
+fail closed when the provider is absent, fails, or returns an empty token.
+
 ## Quick Start
 
 Live regulated use requires Nexalink onboarding, issued credentials, and BAA coverage where PHI may be involved. The package is publicly installable for developer convenience, but runtime access is credentialed.
@@ -249,6 +454,17 @@ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.jso
     "welcomeMessage": "How can I help?",
     "allowUserContext": false
   },
+  "compliance": {
+    "preset": "healthcare"
+  },
+  "model": {
+    "id": "care-navigation-v2",
+    "version": "2026-07"
+  },
+  "featureFlags": {
+    "care-plan-summary": true,
+    "provider-search": true
+  },
   "placement": {
     "mode": "inline"
   },
@@ -256,6 +472,72 @@ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.jso
 }
 ```
 
+## Compliance Controls And Audit Trails
+
+Compliance controls are local SDK preflight checks, not a substitute for Nexalink runtime guardrails, a BAA, or the host application's own HIPAA program. They detect common direct identifiers (email addresses, US phone numbers, SSNs, DOBs, member/policy IDs, and MRNs) in messages, responses, and string-valued context before the SDK stores or sends them.
+
+Choose a preset in public SDK configuration, then override only the behavior you need:
+
+| Preset       | PHI behavior                                                                      | Audit retention | Tradeoff                                                                                                      |
+| ------------ | --------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
+| `standard`   | Detects and emits a `policy_sensitive` safety callback; does not modify requests. | Off             | Preserves existing SDK behavior; the host must opt into audit retention.                                      |
+| `healthcare` | Replaces detected values with `[REDACTED]` before requests and UI state.          | On              | Recommended default for PHI-oriented browser integrations; local detection cannot identify every form of PHI. |
+| `strict`     | Blocks a request or response with detectable PHI.                                 | On              | Stronger browser-side control, but legitimate identifier-bearing workflows need a host-approved alternative.  |
+
+```ts
+import { createCareCompassCore } from "@nexalink/carecompass-sdk/core";
+
+const core = createCareCompassCore({
+  ...config,
+  compliance: {
+    preset: "healthcare",
+    phi: { replacement: "[PHI REMOVED]" },
+  },
+});
+
+const unsubscribeAudit = core.subscribeAudit((event) => {
+  // Persist to your audit system. Events contain type, outcome, timestamp,
+  // source, PHI category/count, and a generated ID—never message text,
+  // context values, identifiers, or raw errors.
+  persistAuditEvent(event);
+});
+
+const unsubscribeSafety = core.subscribeSafety((event) => {
+  // `blocked`, `redacted`, `escalated`, or `policy_sensitive` with only
+  // source plus PHI category/count for safe monitoring.
+  monitorSafetyEvent(event);
+});
+
+// Export a copy of the in-memory, metadata-only audit trail on demand.
+const auditTrail = core.exportAuditTrail();
+
+unsubscribeAudit();
+unsubscribeSafety();
+```
+
+For host-owned tools and UI actions that happen outside the core request lifecycle, add their metadata-only events explicitly:
+
+```ts
+core.recordToolCall("completed");
+core.recordWidgetAction();
+core.recordSafetyDecision("escalated");
+```
+
+If your organization has an approved detector or redaction format, pass it through `createCareCompassCore` options. These hooks receive the raw value only inside your host application; the SDK still emits only PHI categories and counts in audit and safety events.
+
+```ts
+const core = createCareCompassCore(config, {
+  compliance: {
+    phi: {
+      detect: (value) => approvedPhiDetector(value),
+      redact: (value, matches) => approvedRedactor(value, matches),
+    },
+  },
+});
+```
+
+The React UI kit accepts `onAuditEvent` and `onSafetyEvent` with the same safe payloads. Its submit and retry actions are automatically represented as widget audit events when auditing is enabled.
+
 ## Credential Model
 
 CareCompass uses two key types:
@@ -316,7 +598,7 @@ The SDK is designed to keep sensitive operational details out of the browser:
 - no secret API keys in frontend config
 - no model endpoint credentials in browser code
 - no customer-managed telemetry switches in runtime config
-- no prompt, response, chat history, user context, PHI/PII, credentials, raw errors, stack traces, CLI arguments, terminal input, or file paths in SDK telemetry
+- no prompt, response, chat history, user context, PHI/PII, payer, tenant, deployment, session, or user identifiers, credentials, raw errors, stack traces, CLI arguments, terminal input, or file paths in SDK telemetry
 - generated snippets escape serialized config
 - default React rendering escapes raw HTML
 

package/dist/client.d.ts

@@ -1,21 +1,51 @@
 import { type CareCompassConfig } from "./schema.js";
 export type CareCompassAskRequest = {
     prompt: string;
+    /** Stable client-generated id used to make a submit/retry idempotent. */
+    requestId?: string;
+    workflow?: CareCompassWorkflowId;
     sessionId?: string;
     userContext?: Record<string, unknown>;
 };
+export type CareCompassWorkflowId = "rcm-coding-assistance";
 export type CareCompassAskResponse = {
     jobId: string;
 };
+export type CareCompassRetrievalReference = {
+    referenceId: string;
+    documentId: string;
+    title: string;
+    version: string;
+    excerpt: string;
+};
+export type CareCompassRetrievalMetadata = {
+    corpusId: string;
+    corpusVersion: string;
+    outcome: string;
+    latencyMs: number;
+    references: CareCompassRetrievalReference[];
+};
 export type CareCompassStatusResponse = {
     status: "queued" | "running" | "complete" | "failed";
     result?: string;
+    retrieval?: CareCompassRetrievalMetadata;
 };
 type Fetcher = typeof fetch;
-export declare function createCareCompassClient(inputConfig: CareCompassConfig, options?: {
+export type CareCompassRuntimeTokenRequest = {
+    payerId: string;
+    environment: CareCompassConfig["environment"];
+    embedKey: string;
+    workflow?: CareCompassWorkflowId;
+    jobId?: string;
+};
+/** Obtains a short-lived production token from the integrator's BFF. */
+export type CareCompassRuntimeTokenProvider = (request: CareCompassRuntimeTokenRequest) => Promise<string> | string;
+export type CareCompassClientOptions = {
     fetcher?: Fetcher;
     now?: () => number;
-}): {
+    runtimeTokenProvider?: CareCompassRuntimeTokenProvider;
+};
+export declare function createCareCompassClient(inputConfig: CareCompassConfig, options?: CareCompassClientOptions): {
     validateConfig: () => Promise<{
         ok: true;
     }>;

package/dist/client.js

@@ -1,5 +1,6 @@
 import { validateCareCompassConfig } from "./schema.js";
 import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassTelemetry, } from "./telemetry.js";
+import { CARECOMPASS_SDK_VERSION } from "./version.js";
 // Internal error metadata keeps telemetry classification separate from messages,
 // which may include user-visible API details that should not be emitted.
 class CareCompassClientError extends Error {
@@ -105,6 +106,30 @@ export function createCareCompassClient(inputConfig, options = {}) {
         "x-carecompass-environment": config.environment,
     };
     const jobStartedAt = new Map();
+    const jobWorkflows = new Map();
+    async function requestHeaders(request = {}) {
+        if (config.environment !== "production")
+            return headers;
+        if (!options.runtimeTokenProvider) {
+            throw new CareCompassClientError("Production CareCompass embeds require a runtimeTokenProvider backed by your server.", CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED, "authentication");
+        }
+        let token;
+        try {
+            token = await options.runtimeTokenProvider({
+                payerId: config.payerId,
+                environment: config.environment,
+                embedKey: config.embedKey,
+                ...request,
+            });
+        }
+        catch {
+            throw new CareCompassClientError("CareCompass runtime authorization could not be obtained.", CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED, "authentication");
+        }
+        if (typeof token !== "string" || !token.trim()) {
+            throw new CareCompassClientError("CareCompass runtime authorization could not be obtained.", CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED, "authentication");
+        }
+        return { ...headers, "x-carecompass-runtime-token": token.trim() };
+    }
     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_INITIALIZED);
     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.THEME_LOADED);
     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PROMPT_CONFIGURATION_LOADED);
@@ -137,7 +162,7 @@ export function createCareCompassClient(inputConfig, options = {}) {
             try {
                 const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/config/validate"), {
                     method: "POST",
-                    headers,
+                    headers: await requestHeaders(),
                     body: JSON.stringify({ config }),
                 });
                 const result = await parseJson(response);
@@ -155,18 +180,27 @@ export function createCareCompassClient(inputConfig, options = {}) {
             try {
                 const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/ask"), {
                     method: "POST",
-                    headers,
+                    headers: await requestHeaders({ workflow: request.workflow }),
                     body: JSON.stringify({
                         prompt: request.prompt,
+                        requestId: request.requestId,
+                        workflow: request.workflow,
                         sessionId: request.sessionId,
+                        sdkVersion: CARECOMPASS_SDK_VERSION,
+                        applicationSurface: config.deploymentTarget,
                         userContext: request.userContext,
                         promptConfig: config.prompt,
+                        // Public routing preferences; the hosted runtime validates model
+                        // availability and may ignore disabled feature flags.
+                        model: config.model,
+                        featureFlags: config.featureFlags,
                     }),
                 });
                 const result = await parseJson(response);
                 // Status polling is asynchronous, so retain the submit timestamp until
                 // the final job state lets telemetry report end-to-end latency.
                 jobStartedAt.set(result.jobId, startedAt);
+                jobWorkflows.set(result.jobId, request.workflow);
                 return result;
             }
             catch (error) {
@@ -177,16 +211,23 @@ export function createCareCompassClient(inputConfig, options = {}) {
         status: async (jobId) => {
             const startedAt = jobStartedAt.get(jobId) ?? now();
             try {
-                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/status/${encodeURIComponent(jobId)}`), { headers });
+                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/status/${encodeURIComponent(jobId)}`), {
+                    headers: await requestHeaders({
+                        jobId,
+                        workflow: jobWorkflows.get(jobId),
+                    }),
+                });
                 const result = await parseJson(response);
                 if (result.status === "complete") {
                     jobStartedAt.delete(jobId);
+                    jobWorkflows.delete(jobId);
                     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_SUCCEEDED, {
                         durationMs: now() - startedAt,
                     });
                 }
                 else if (result.status === "failed") {
                     jobStartedAt.delete(jobId);
+                    jobWorkflows.delete(jobId);
                     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_FAILED, {
                         durationMs: now() - startedAt,
                         errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.INFERENCE_FAILED,
@@ -197,6 +238,7 @@ export function createCareCompassClient(inputConfig, options = {}) {
             }
             catch (error) {
                 jobStartedAt.delete(jobId);
+                jobWorkflows.delete(jobId);
                 captureInferenceFailure(telemetry, error, now() - startedAt);
                 throw error;
             }

package/dist/compliance.d.ts

@@ -0,0 +1,69 @@
+import type { CareCompassComplianceConfig } from "./schema.js";
+/** The identifier categories detected by the SDK's local PHI preflight. */
+export type CareCompassPhiCategory = "date_of_birth" | "email" | "medical_record_number" | "member_id" | "phone" | "ssn";
+export type CareCompassPhiMatch = {
+    category: CareCompassPhiCategory;
+    start: number;
+    end: number;
+};
+export type CareCompassPhiSource = "message" | "response" | "context";
+export type CareCompassPhiDetectionContext = {
+    source: CareCompassPhiSource;
+};
+export type CareCompassPhiDetector = (value: string, context: CareCompassPhiDetectionContext) => CareCompassPhiMatch[];
+export type CareCompassPhiRedactor = (value: string, matches: CareCompassPhiMatch[], replacement: string) => string;
+export type CareCompassPhiHooks = {
+    /** Replaces the built-in detector. The hook receives raw content; never emit it. */
+    detect?: CareCompassPhiDetector;
+    /** Replaces the built-in redactor. The hook receives raw content; never emit it. */
+    redact?: CareCompassPhiRedactor;
+};
+export type CareCompassComplianceRuntimeOptions = {
+    phi?: CareCompassPhiHooks;
+};
+export type CareCompassCompliancePreset = "standard" | "healthcare" | "strict";
+export type CareCompassPhiAction = "allow" | "redact" | "block";
+export type CareCompassCompliancePolicy = {
+    auditEnabled: boolean;
+    phiAction: CareCompassPhiAction;
+    preset: CareCompassCompliancePreset;
+    replacement: string;
+};
+export declare const CARECOMPASS_COMPLIANCE_PRESETS: Readonly<Record<CareCompassCompliancePreset, Omit<CareCompassCompliancePolicy, "preset">>>;
+export type CareCompassAuditEventType = "message" | "tool_call" | "widget_action" | "error" | "safety_decision";
+export type CareCompassAuditOutcome = "submitted" | "completed" | "failed" | "blocked" | "redacted" | "escalated" | "recorded";
+export type CareCompassAuditSource = CareCompassPhiSource | "tool_call" | "widget_action";
+export type CareCompassAuditEvent = {
+    id: string;
+    occurredAt: number;
+    outcome: CareCompassAuditOutcome;
+    phi: {
+        categories: CareCompassPhiCategory[];
+        count: number;
+    };
+    source?: CareCompassAuditSource;
+    type: CareCompassAuditEventType;
+};
+export type CareCompassSafetyDecision = "blocked" | "escalated" | "redacted" | "policy_sensitive";
+export type CareCompassSafetyEvent = {
+    decision: CareCompassSafetyDecision;
+    occurredAt: number;
+    phi: {
+        categories: CareCompassPhiCategory[];
+        count: number;
+    };
+    source: CareCompassPhiSource | "tool_call" | "widget_action";
+};
+export type CareCompassAuditListener = (event: CareCompassAuditEvent) => void;
+export type CareCompassSafetyListener = (event: CareCompassSafetyEvent) => void;
+export declare const detectCareCompassPhi: CareCompassPhiDetector;
+export declare const redactCareCompassPhi: CareCompassPhiRedactor;
+export declare const resolveCareCompassCompliancePolicy: (config: CareCompassComplianceConfig | undefined) => CareCompassCompliancePolicy;
+export declare const phiSummary: (matches: CareCompassPhiMatch[]) => {
+    categories: CareCompassPhiCategory[];
+    count: number;
+};
+export declare const sanitizeCareCompassValue: (value: unknown, source: CareCompassPhiSource, policy: CareCompassCompliancePolicy, hooks: CareCompassPhiHooks | undefined) => {
+    matches: CareCompassPhiMatch[];
+    value: unknown;
+};