@nexalink/carecompass-sdk 0.6.1 → 0.7.1

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { type CareCompassAdapterId } from "./adapters.js";
 import { type CareCompassConfig } from "./schema.js";
 export type CareCompassAskRequest = {
     prompt: string;
@@ -7,7 +8,17 @@ export type CareCompassAskRequest = {
     sessionId?: string;
     userContext?: Record<string, unknown>;
 };
-export type CareCompassWorkflowId = "rcm-coding-assistance";
+/**
+ * Workflow identifiers are server-authorized: any value is a client claim that
+ * the hosted runtime must validate against the tenant's authorized pack
+ * catalog before it is accepted. The SDK deliberately does not restrict this
+ * to a single TypeScript literal so new authorized packs do not require SDK
+ * releases. Prefer the canonical constants from @nexalink/coding-contracts
+ * (for example RCM_WORKFLOW_ID) and values returned by listAuthorizedPacks.
+ */
+export type CareCompassWorkflowId = string & {
+    readonly __careCompassWorkflowId?: unique symbol;
+};
 export type CareCompassAskResponse = {
     jobId: string;
 };
@@ -30,6 +41,79 @@ export type CareCompassStatusResponse = {
     result?: string;
     retrieval?: CareCompassRetrievalMetadata;
 };
+/** Authorized pack catalog entry returned by the hosted runtime. */
+export type CareCompassPackCatalogEntry = {
+    packId: CareCompassWorkflowId;
+    name: string;
+    description: string;
+    environments: ("development" | "staging" | "production")[];
+    inputSchemaVersion: string;
+    outputSchemaVersion: string;
+    requiresHumanReview: boolean;
+};
+/** Pack descriptor plus both JSON Schema documents the pack declares. */
+export type CareCompassPackSchema = {
+    packId: CareCompassWorkflowId;
+    name: string;
+    description: string;
+    environments: ("development" | "staging" | "production")[];
+    inputSchemaVersion: string;
+    outputSchemaVersion: string;
+    requiresHumanReview: boolean;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+};
+/**
+ * Structured coding-case submission. The browser payload intentionally carries
+ * only the server-authorized pack id, the canonical coding case, and routing
+ * metadata: no prompt configuration, model preferences, feature flags, or
+ * policy text is sent on this path.
+ */
+export type CareCompassSubmitCodingCaseRequest = {
+    packId: CareCompassWorkflowId;
+    caseSchemaVersion: string;
+    /** Stable client-generated id used to make a submit/retry idempotent. */
+    requestId?: string;
+    sessionId?: string;
+} & ({
+    /** Canonical coding case. Adapter fields are mutually exclusive. */
+    codingCase: Record<string, unknown>;
+    adapter?: never;
+    sourcePayload?: never;
+} | {
+    codingCase?: never;
+    /**
+     * Registered input adapter (fhir-r4-claim-v1, csv-row-v1, json-claim-v1,
+     * x12-837-claim-v1). The resolved pack authorizes the adapter; use a
+     * `CareCompassAdapterEnvelope` from `adapters.ts` to build it.
+     */
+    adapter: CareCompassAdapterId | (string & {});
+    /**
+     * Customer-native source payload normalized into the canonical CodingCase
+     * by the adapter. PHI-safe synthetic fixtures only in non-production.
+     */
+    sourcePayload: NonNullable<unknown>;
+});
+export type CareCompassSubmitCodingCaseResponse = {
+    jobId: string;
+    decisionId?: string;
+};
+/** Typed failure reasons for structured coding submissions. */
+export type CareCompassCodingErrorCode = "missing_data" | "unsupported_scope" | "policy_conflict" | "abstained" | "escalated" | "terminology_unavailable" | "request_timeout" | "cancelled" | "rate_limited" | "authentication_failed" | "network_error" | "backend_unavailable" | "invalid_decision" | "unknown";
+export type CareCompassCodingError = {
+    code: CareCompassCodingErrorCode;
+    message: string;
+};
+export type CareCompassCodingStatus = "queued" | "running" | "complete" | "failed" | "cancelled";
+export type CareCompassCodingStatusResponse = {
+    status: CareCompassCodingStatus;
+    decision?: Record<string, unknown>;
+    error?: CareCompassCodingError;
+};
+export type CareCompassReviewerActionResult = {
+    recorded: true;
+    reviewerAction: Record<string, unknown>;
+};
 type Fetcher = typeof fetch;
 export type CareCompassRuntimeTokenRequest = {
     payerId: string;
@@ -40,11 +124,26 @@ export type CareCompassRuntimeTokenRequest = {
 };
 /** Obtains a short-lived production token from the integrator's BFF. */
 export type CareCompassRuntimeTokenProvider = (request: CareCompassRuntimeTokenRequest) => Promise<string> | string;
+/** Supplies server-verified portal credentials for a human reviewer action. */
+export type CareCompassReviewerAuthProvider = () => Promise<{
+    accessToken: string;
+    idToken: string;
+}> | {
+    accessToken: string;
+    idToken: string;
+};
 export type CareCompassClientOptions = {
     fetcher?: Fetcher;
     now?: () => number;
     runtimeTokenProvider?: CareCompassRuntimeTokenProvider;
+    reviewerAuthProvider?: CareCompassReviewerAuthProvider;
+    signal?: AbortSignal;
 };
+/**
+ * Return the stable coding-flow error represented by an internal client
+ * failure without exposing transport or telemetry implementation details.
+ */
+export declare const careCompassCodingErrorCode: (error: unknown) => CareCompassCodingErrorCode | null;
 export declare function createCareCompassClient(inputConfig: CareCompassConfig, options?: CareCompassClientOptions): {
     validateConfig: () => Promise<{
         ok: true;
@@ -52,5 +151,22 @@ export declare function createCareCompassClient(inputConfig: CareCompassConfig,
     ask: (request: CareCompassAskRequest) => Promise<CareCompassAskResponse>;
     status: (jobId: string) => Promise<CareCompassStatusResponse>;
     recordInferenceTimeout: (jobId: string, durationMs: number) => void;
+    listAuthorizedPacks: () => Promise<CareCompassPackCatalogEntry[]>;
+    getPackSchema: (packId: CareCompassWorkflowId) => Promise<CareCompassPackSchema>;
+    submitCodingCase: (request: CareCompassSubmitCodingCaseRequest) => Promise<CareCompassSubmitCodingCaseResponse>;
+    codingStatus: (jobId: string) => Promise<CareCompassCodingStatusResponse>;
+    cancelCase: (jobId: string) => Promise<{
+        cancelled: true;
+    }>;
+    recordReviewerAction: (decisionId: string, reviewerAction: Record<string, unknown>) => Promise<CareCompassReviewerActionResult>;
+    /**
+     * Records one tenant-scoped reviewer engagement event (NEX-79) in the
+     * operational event plane. The event is validated and sanitized by the
+     * hosted API before storage; it never carries prompts, document contents,
+     * or direct identifiers.
+     */
+    reportReviewerEvent: (event: Record<string, unknown>) => Promise<{
+        accepted: boolean;
+    }>;
 };
 export {};

package/dist/client.js

@@ -11,6 +11,28 @@ class CareCompassClientError extends Error {
         this.name = "CareCompassClientError";
     }
 }
+/**
+ * Return the stable coding-flow error represented by an internal client
+ * failure without exposing transport or telemetry implementation details.
+ */
+export const careCompassCodingErrorCode = (error) => {
+    if (!(error instanceof CareCompassClientError))
+        return null;
+    switch (error.telemetryErrorCode) {
+        case CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED:
+            return "authentication_failed";
+        case CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMITED:
+            return "rate_limited";
+        case CARECOMPASS_TELEMETRY_ERROR_CODES.BACKEND_UNAVAILABLE:
+            return "backend_unavailable";
+        case CARECOMPASS_TELEMETRY_ERROR_CODES.NETWORK_ERROR:
+            return "network_error";
+        case CARECOMPASS_TELEMETRY_ERROR_CODES.INFERENCE_TIMEOUT:
+            return "request_timeout";
+        default:
+            return "unknown";
+    }
+};
 const joinUrl = (baseUrl, path) => `${baseUrl.replace(/\/+$/, "")}${path}`;
 const isLocalhostUrl = (value) => {
     try {
@@ -133,14 +155,17 @@ export function createCareCompassClient(inputConfig, options = {}) {
     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_INITIALIZED);
     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.THEME_LOADED);
     telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PROMPT_CONFIGURATION_LOADED);
-    async function send(input, init) {
+    async function send(input, init, inheritClientSignal = true) {
         // Hosted demos and sandboxes cannot call a developer's local API server, so
         // fail early with a setup hint instead of surfacing an opaque fetch error.
         if (isBrowserHostedAwayFromLocalhost(config.apiBaseUrl)) {
             throw new CareCompassClientError(`CareCompass apiBaseUrl is ${config.apiBaseUrl}, but this page is running at ${window.location.origin}. A hosted sandbox or remote site cannot reach your local Next.js server. Use a deployed Nexalink API base URL, or run both the integrating page and Nexalink web app locally on the same machine.`, CARECOMPASS_TELEMETRY_ERROR_CODES.NETWORK_ERROR, "network");
         }
         try {
-            return await fetcher(input, init);
+            return await fetcher(input, {
+                ...init,
+                signal: init?.signal ?? (inheritClientSignal ? options.signal : undefined),
+            });
         }
         catch (error) {
             if (error instanceof CareCompassClientError)
@@ -251,5 +276,196 @@ export function createCareCompassClient(inputConfig, options = {}) {
                 failureCategory: "timeout",
             });
         },
+        listAuthorizedPacks: async () => {
+            const startedAt = now();
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/packs"), { headers: await requestHeaders() });
+                const body = await parseJson(response);
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PACK_LIST_SUCCEEDED, {
+                    durationMs: now() - startedAt,
+                });
+                return body.packs;
+            }
+            catch (error) {
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PACK_LIST_FAILED, {
+                    ...telemetryFailure(error),
+                    durationMs: now() - startedAt,
+                });
+                throw error;
+            }
+        },
+        getPackSchema: async (packId) => {
+            const startedAt = now();
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/packs/${encodeURIComponent(packId)}`), { headers: await requestHeaders({ workflow: packId }) });
+                const body = await parseJson(response);
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PACK_SCHEMA_SUCCEEDED, {
+                    durationMs: now() - startedAt,
+                });
+                return body;
+            }
+            catch (error) {
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PACK_SCHEMA_FAILED, {
+                    ...telemetryFailure(error),
+                    durationMs: now() - startedAt,
+                });
+                throw error;
+            }
+        },
+        submitCodingCase: async (request) => {
+            const startedAt = now();
+            telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.CODING_CASE_SUBMITTED);
+            try {
+                const requestValue = request;
+                const hasCodingCase = requestValue.codingCase !== null &&
+                    typeof requestValue.codingCase === "object" &&
+                    !Array.isArray(requestValue.codingCase);
+                const hasAdapter = typeof requestValue.adapter === "string" &&
+                    requestValue.adapter.trim().length > 0;
+                const hasSourcePayload = requestValue.sourcePayload !== undefined &&
+                    requestValue.sourcePayload !== null;
+                const hasAnyAdapterField = requestValue.adapter !== undefined ||
+                    requestValue.sourcePayload !== undefined;
+                if ((hasCodingCase && hasAnyAdapterField) ||
+                    (!hasCodingCase && (!hasAdapter || !hasSourcePayload))) {
+                    throw new CareCompassClientError("CareCompass coding submissions require either codingCase or adapter with sourcePayload, but not both.", CARECOMPASS_TELEMETRY_ERROR_CODES.API_ERROR, "unknown");
+                }
+                const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/cases"), {
+                    method: "POST",
+                    headers: await requestHeaders({ workflow: request.packId }),
+                    body: JSON.stringify({
+                        packId: request.packId,
+                        ...(request.codingCase !== undefined
+                            ? { codingCase: request.codingCase }
+                            : {}),
+                        caseSchemaVersion: request.caseSchemaVersion,
+                        requestId: request.requestId,
+                        sessionId: request.sessionId,
+                        sdkVersion: CARECOMPASS_SDK_VERSION,
+                        applicationSurface: config.deploymentTarget,
+                        ...(request.adapter ? { adapter: request.adapter } : {}),
+                        ...(request.sourcePayload !== undefined
+                            ? { sourcePayload: request.sourcePayload }
+                            : {}),
+                    }),
+                });
+                const result = await parseJson(response);
+                jobStartedAt.set(result.jobId, startedAt);
+                jobWorkflows.set(result.jobId, request.packId);
+                return result;
+            }
+            catch (error) {
+                captureInferenceFailure(telemetry, error, now() - startedAt);
+                throw error;
+            }
+        },
+        codingStatus: async (jobId) => {
+            const startedAt = jobStartedAt.get(jobId) ?? now();
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/cases/${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" ||
+                    result.status === "cancelled") {
+                    jobStartedAt.delete(jobId);
+                    jobWorkflows.delete(jobId);
+                    telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_FAILED, {
+                        durationMs: now() - startedAt,
+                        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.INFERENCE_FAILED,
+                        failureCategory: "inference",
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                jobStartedAt.delete(jobId);
+                jobWorkflows.delete(jobId);
+                captureInferenceFailure(telemetry, error, now() - startedAt);
+                throw error;
+            }
+        },
+        cancelCase: async (jobId) => {
+            const startedAt = now();
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/cases/${encodeURIComponent(jobId)}/cancel`), {
+                    method: "POST",
+                    headers: await requestHeaders({
+                        jobId,
+                        workflow: jobWorkflows.get(jobId),
+                    }),
+                });
+                const result = await parseJson(response);
+                jobStartedAt.delete(jobId);
+                jobWorkflows.delete(jobId);
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.CODING_CASE_CANCELLED, {
+                    durationMs: now() - startedAt,
+                });
+                return result;
+            }
+            catch (error) {
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.CODING_CASE_CANCEL_FAILED, { ...telemetryFailure(error), durationMs: now() - startedAt });
+                throw error;
+            }
+        },
+        recordReviewerAction: async (decisionId, reviewerAction) => {
+            const startedAt = now();
+            try {
+                if (!options.reviewerAuthProvider) {
+                    throw new CareCompassClientError("Reviewer actions require a reviewerAuthProvider with portal credentials.", CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED, "authentication");
+                }
+                const reviewerAuth = await options.reviewerAuthProvider();
+                if (!reviewerAuth.accessToken || !reviewerAuth.idToken) {
+                    throw new CareCompassClientError("Reviewer portal credentials are missing.", CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED, "authentication");
+                }
+                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/decisions/${encodeURIComponent(decisionId)}/reviewer-action`), {
+                    method: "POST",
+                    headers: {
+                        ...(await requestHeaders()),
+                        authorization: `Bearer ${reviewerAuth.accessToken}`,
+                        "x-id-token": reviewerAuth.idToken,
+                    },
+                    body: JSON.stringify({ reviewerAction }),
+                });
+                const result = await parseJson(response);
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.REVIEWER_ACTION_RECORDED, { durationMs: now() - startedAt });
+                return result;
+            }
+            catch (error) {
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.REVIEWER_ACTION_FAILED, {
+                    ...telemetryFailure(error),
+                    durationMs: now() - startedAt,
+                });
+                throw error;
+            }
+        },
+        /**
+         * Records one tenant-scoped reviewer engagement event (NEX-79) in the
+         * operational event plane. The event is validated and sanitized by the
+         * hosted API before storage; it never carries prompts, document contents,
+         * or direct identifiers.
+         */
+        reportReviewerEvent: async (event) => {
+            const workflow = typeof event.workflowId === "string"
+                ? event.workflowId
+                : undefined;
+            const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/events"), {
+                method: "POST",
+                headers: await requestHeaders({ workflow }),
+                body: JSON.stringify({ events: [event] }),
+                keepalive: true,
+            }, false);
+            return await parseJson(response);
+        },
     };
 }

package/dist/coding-element.d.ts

@@ -0,0 +1,22 @@
+import type { CodingCase } from "@nexalink/coding-contracts";
+import type { CareCompassReviewerAuthProvider, CareCompassRuntimeTokenProvider } from "./client.js";
+import { type CareCompassConfig } from "./schema.js";
+export declare const CARECOMPASS_CODING_REVIEW_ELEMENT_TAG = "carecompass-coding-review";
+export type CareCompassCodingReviewElement = HTMLElement & {
+    config: CareCompassConfig | undefined;
+    initialCase: CodingCase | undefined;
+    packId: string | undefined;
+    reviewerId: string | undefined;
+    reviewerRole: string | undefined;
+    reviewerAuthProvider: CareCompassReviewerAuthProvider | undefined;
+    runtimeTokenProvider: CareCompassRuntimeTokenProvider | undefined;
+    submit: () => Promise<void>;
+    cancel: () => Promise<void>;
+    retry: () => Promise<void>;
+};
+/**
+ * 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 declare function defineCodingReviewElement(tagName?: string): CustomElementConstructor | undefined;