@nexalink/carecompass-sdk 0.6.1 → 0.7.0

package/README.md

@@ -13,6 +13,25 @@ The SDK gives teams two integration paths:
 
 CareCompass is not a diagnosis tool, autonomous treatment product, replacement for clinicians, or general-purpose LLM SDK. It is healthcare AI infrastructure for building compliance-oriented, embedded AI workflows.
 
+## Customer Documentation
+
+Customer engineering and operations teams should start with the
+[customer quickstart](docs/quickstart.md), which walks through a
+complete synthetic (non-production) integration using the runnable files
+in [`examples/`](examples/). The examples are compiled and executed by
+this package's CI test suite, so the copy-paste code cannot drift from
+the SDK surface.
+
+- [Quickstart: synthetic integration end to end](docs/quickstart.md)
+- [CodingCase construction and field validation](docs/coding-case-guide.md)
+- [Coding packs: discovery, authorization, version pinning, and migration](docs/packs.md)
+- [Error handling: retries, timeouts, abstention, conflict, escalation](docs/error-handling.md)
+- [Configuration and policy: what you control, what Nexalink controls](docs/configuration-and-policy.md)
+- [Branding and accessibility guidance](docs/branding-and-accessibility.md)
+- [Production readiness checklist](docs/production-readiness.md)
+- [Version support and deprecation policy](docs/version-support.md)
+- [Migrating from the RCM coding-assistance API](docs/migration-rcm.md)
+
 ## Why Teams Choose CareCompass
 
 Healthcare teams can already access foundation models. The hard part is turning those models into production-ready healthcare software.
@@ -81,7 +100,7 @@ CareCompass AI runtime
 
 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.
+Secret API keys stay in CLI, server-side, or trusted setup workflows. The browser never receives model credentials or Nexalink API keys. Structured coding submissions additionally never carry prompt configuration, model preferences, feature flags, policy text, corpus identifiers, or runtime tokens; pack ids and cases are validated against the canonical contracts before they leave the SDK.
 
 ## Integration Options
 
@@ -180,10 +199,20 @@ 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.
 
+> **Deprecated.** The `./rcm` convenience API (createRcmCodingWorkflow and
+> RcmCodingAssistant) remains fully supported and tested for existing
+> integrations, but new integrations should use the generic headless coding
+> API and review UI described below. A one-time console warning is emitted
+> when the RCM wrappers are used. See [Migrating from the RCM coding-assistance
+> API](#migrating-from-the-rcm-coding-assistance-api).
+
 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.
+field. The workflow identifier, request/result payload contracts, and validation
+rules come from the canonical `@nexalink/coding-contracts` package, which is
+generated from one JSON Schema source shared with the portal and the hosted
+runtime. The SDK validates every review response against the canonical
+`rcm-coding-output` contract and fails closed with an escalation when the
+response violates it.
 
 Development and staging RCM requests must include `claimContext.stage` set to
 the configured SDK environment (`"development"` or `"staging"`). Production
@@ -247,6 +276,314 @@ 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.
 
+### Generic headless coding API
+
+The generic coding API is a stable delivery layer for any authorized coding
+pack. It is intentionally free of payer- or specialty-specific rules: pack
+identity and required schemas come from the server-authorized pack catalog, and
+the canonical CodingCase/CodingDecision contracts come from
+`@nexalink/coding-contracts`.
+
+The SDK can integrate headlessly without importing any bundled UI. Import from
+the `./coding` subpath:
+
+```ts
+import { createCodingFlow } from "@nexalink/carecompass-sdk/coding";
+import config from "./carecompass/carecompass.config.json";
+
+const flow = createCodingFlow(config, {
+  reviewerAuthProvider: () => getReviewerPortalTokens(),
+});
+
+// 1. Discover the packs the runtime authorizes for this tenant.
+const packs = await flow.listAuthorizedPacks();
+
+// 2. Obtain the pack descriptor and required JSON Schemas.
+const packSchema = await flow.getPackSchema("rcm-coding-assistance");
+
+// 3. Submit a structured coding case and poll/stream the job to a decision.
+const snapshot = await flow.submit("rcm-coding-assistance", {
+  caseId: "ENC-1042",
+  codingIntent: "encounter_review",
+  servicePeriod: { startDate: "2026-07-01" },
+  context: { setting: "professional", placeOfService: "22" },
+  payer: { payerName: "Example Payer" },
+  clinical: {
+    diagnoses: [
+      {
+        diagnosisId: "dx-1",
+        code: "R05",
+        codeSystem: "ICD-10-CM",
+        description: "Documented cough",
+        diagnosisType: "principal",
+      },
+    ],
+    notes: [{ noteId: "n1", noteType: "clinical_narrative", note: "…" }],
+  },
+});
+
+// 4. Render or persist the canonical decision.
+if (snapshot.phase === "complete" && snapshot.decision) {
+  const { disposition, lineDecisions, gaps, conflicts, provenance } =
+    snapshot.decision;
+}
+
+// 5. Record a reviewer disposition against the immutable decision.
+await flow.recordReviewerAction(snapshot.decision.decisionId, {
+  reviewerId: authenticatedReviewerSub,
+  reviewerRole: "qualified_coder",
+  action: "approved",
+  occurredAt: new Date().toISOString(),
+});
+```
+
+Reviewer actions require a portal-authenticated owner, admin, or reviewer whose
+verified user ID matches `reviewerId` and who has claimed the review in the
+portal. `reviewerAuthProvider` returns that user's `{ accessToken, idToken }`;
+embed credentials and runtime tokens alone cannot approve coding decisions.
+Edits to recommendations must use the portal review disposition flow, which
+validates per-code feedback and the edited evidence set.
+
+### Reviewer engagement events (RCM analytics)
+
+`flow.reportReviewerEvent` records tenant-scoped, PHI-free reviewer engagement
+facts (`decision_shown`, `evidence_opened`, `evidence_copied`,
+`review_active_time`) in the operational event plane that powers tenant RCM
+analytics. The built-in `CodingReview` surface reports `decision_shown`,
+evidence engagement, and active review time automatically with a documented
+120-second idle pause. Delivery is best-effort: it returns `false` instead of
+throwing and never blocks a review.
+
+```ts
+// Hosts rendering a custom review UI report the same contract themselves.
+await flow.reportReviewerEvent({
+  eventName: "decision_shown",
+  caseRef: decision.caseRef, // opaque case reference, never a patient id
+  workflowId: snapshot.packId ?? "rcm-coding-assistance",
+});
+```
+
+Hosts with custom UIs must supply the event name, the opaque `caseRef`, the
+workflow id; the SDK supplies `occurredAt` when omitted. `evidenceId` and
+`activeSeconds` are optional.
+Never send prompts, document contents, patient or member identifiers, claim
+identifiers, or free text. Events are accepted only for jobs owned by the
+embed key's tenant and are validated against the published
+`rcm-reviewer-event-v1` contract. See `TELEMETRY.md` for the boundary between
+aggregate deployment telemetry and this tenant-scoped event plane.
+
+### Monthly PIN time aggregation pack
+
+The `monthly-pin-time-aggregation` workflow runs through the exact same
+methods with a structurally different case: structured monthly activity time
+instead of a narrative encounter. The hosted runtime derives the time-based
+codes deterministically from the pack's rule set (the model never computes
+time); the SDK renders the same `CodingReview` surface and requires the same
+qualified human review.
+
+```ts
+import {
+  createCodingFlow,
+  PIN_TIME_WORKFLOW_ID,
+} from "@nexalink/carecompass-sdk";
+
+const flow = createCodingFlow(config);
+
+// Discover the pack the runtime authorizes for this tenant.
+const packs = await flow.listAuthorizedPacks();
+const pinPack = packs.find((pack) => pack.packId === PIN_TIME_WORKFLOW_ID);
+if (!pinPack) throw new Error("monthly-pin-time-aggregation is not authorized");
+
+// Submit a monthly multi-activity time case.
+const snapshot = await flow.submit(PIN_TIME_WORKFLOW_ID, {
+  caseId: "CCM-2026-07",
+  analyticsId: "anl-ccm-2026-07",
+  codingIntent: "monthly_time_aggregation",
+  servicePeriod: { startDate: "2026-07-01", endDate: "2026-07-31" },
+  context: {
+    setting: "professional",
+    placeOfService: "11",
+    jurisdiction: "Synthetic MAC-J15",
+    specialty: "internal_medicine",
+  },
+  clinical: {
+    timeUnits: [
+      {
+        timeId: "tu-1",
+        date: "2026-07-02",
+        durationMinutes: 45,
+        activityCode: "EM-MGMT",
+      },
+      {
+        timeId: "tu-2",
+        date: "2026-07-09",
+        durationMinutes: 50,
+        activityCode: "EM-MGMT",
+      },
+    ],
+  },
+});
+
+if (snapshot.phase === "complete" && snapshot.decision) {
+  // Deterministic code candidates appear as line decisions with rule provenance.
+  const { lineDecisions, provenance } = snapshot.decision;
+  if (
+    provenance.rules.some(
+      (rule) => rule.ruleId === "rcm.monthly-time-aggregation",
+    )
+  ) {
+    // The codes were derived by the pack's deterministic time-aggregation rule.
+  }
+}
+```
+
+Both packs share the same `createCodingFlow`, `CodingReview`, reviewer-action,
+tenant isolation, evidence grounding, abstention/escalation, and audit
+guarantees; pack-specific behavior lives in the manifests, rule sets, prompts,
+and fixtures only.
+
+For live progress, use the lifecycle generator instead of `submit`:
+
+```ts
+for await (const event of flow.stream("rcm-coding-assistance", codingCase)) {
+  switch (event.type) {
+    case "case_submitted":
+    case "status":
+      // jobId + queued/running/complete/failed/cancelled
+      break;
+    case "decision_completed":
+      renderDecision(event.decision);
+      break;
+    case "error":
+      retryState(event.snapshot);
+      break;
+    case "cancelled":
+      break;
+  }
+}
+```
+
+Workflow/pack identifiers are **server-authorized**. `submit` sends only the
+pack id, the canonical coding case, and routing metadata — never prompt
+configuration, model preferences, feature flags, or policy text. The runtime
+validates the pack against the tenant catalog before accepting work; an
+unauthorized pack fails closed with an `unsupported_scope` error. Responses are
+validated against the canonical `coding-decision` contract and fail closed with
+an `invalid_decision` error instead of surfacing a malformed result.
+
+Structured failure states are explicit: `missing_data` (schema validation),
+`unsupported_scope` (pack/date/setting not applicable), `policy_conflict`,
+`terminology_unavailable`, `abstained`, `escalated`, `request_timeout`, and
+`cancelled`. Every failure keeps an error snapshot with `canRetry` metadata;
+`retryLast()` reuses the original request identifier only when the submission
+outcome was ambiguous, and issues a fresh one otherwise. `cancel()` stops
+polling and requests server-side cancellation; after dispose, all in-flight
+operations reject with a disposed error.
+
+Browser payloads on this path never contain secret credentials or unrestricted
+policy configuration. Production embeds still require a BFF
+`runtimeTokenProvider`, exactly like the chat and RCM paths.
+
+### Coding review UI
+
+For an approved default review experience with minimal configuration, use the
+React `CodingReview` component or the framework-neutral web component. Both are
+optional: headless integrations never import them.
+
+```tsx
+import { CodingReview } from "@nexalink/carecompass-sdk/coding-ui";
+import config from "./carecompass/carecompass.config.json";
+
+<CodingReview
+  config={config}
+  packId="rcm-coding-assistance"
+  initialCase={codingCase}
+  reviewerId={authenticatedReviewerSub}
+  reviewerAuthProvider={() => getReviewerPortalTokens()}
+  onCodingDecision={(decision) => persistDecision(decision)}
+  renderGap={(gap) => <CustomGap gap={gap} />}
+/>;
+```
+
+The default experience renders the human-review boundary (`role="alert"`),
+disposition, line decisions (actions, codes, modifiers, units, linked
+diagnoses), typed gaps (missing documentation, unsupported scope, insufficient
+evidence, policy conflict, terminology unavailable), conflicts, and supporting
+evidence, with retry and cancel controls and a reviewer-action recording form.
+It is driven by `config.theme`, `config.branding`, and `config.labels`; label
+overrides for the review copy are passed with the `labels` prop. UI
+configuration can change presentation only — it can never redefine an
+authorized workflow.
+
+For a headless React controller, use `useCodingReview(config, options)`, which
+returns `{ flow, snapshot, submit, retryLast, cancel, recordReviewerAction }`
+and owns teardown. For framework-neutral pages:
+
+```ts
+import { defineCodingReviewElement } from "@nexalink/carecompass-sdk/coding-element";
+
+defineCodingReviewElement();
+```
+
+```html
+<carecompass-coding-review></carecompass-coding-review>
+<script>
+  const element = document.querySelector("carecompass-coding-review");
+  element.config = config;
+  element.packId = "rcm-coding-assistance";
+  element.initialCase = codingCase;
+  element.reviewerId = "user-coder-42";
+  element.reviewerRole = "qualified_coder";
+  element.reviewerAuthProvider = () => getReviewerPortalTokens();
+  element.addEventListener("carecompass-decision", (event) =>
+    console.log(event.detail),
+  );
+  element.addEventListener("carecompass-error", (event) =>
+    console.error(event.detail),
+  );
+  element.addEventListener("carecompass-cancelled", (event) =>
+    console.log("Cancelled", event.detail),
+  );
+</script>
+```
+
+Terminal `carecompass-decision`, `carecompass-error`, and
+`carecompass-cancelled` events fire once per state transition. Successful
+reviewer submissions emit `carecompass-reviewer-action`. Audit and safety
+metadata continue to use `carecompass-audit` and `carecompass-safety`.
+
+Schema-driven primitives (`createCodingDraft`, `decisionGaps`,
+`decisionBlockingGaps`, `decisionConflicts`, `decisionPrimaryState`) are
+exported from both the root package and the `./coding` subpath so forms and
+result renderers stay contract-driven without embedding specialty logic.
+
+### Migrating from the RCM coding-assistance API
+
+The RCM wrappers (`createRcmCodingWorkflow`, `RcmCodingAssistant`,
+`CARECOMPASS_RCM_SYNTHETIC_DEMO`) remain available at `@nexalink/carecompass-sdk/rcm`
+and keep their existing transport and result shapes, so existing integrations
+do not need changes. They now emit a one-time deprecation warning.
+
+To migrate:
+
+1. Replace the review call with `createCodingFlow(config, options).submit(packId, codingCase)`.
+2. Convert your `RcmCodingAssistanceInput` into the canonical `CodingCase`
+   envelope (encounter id, coding intent, service period, context, payer,
+   clinical narratives, and supporting references).
+3. Read the result from `snapshot.decision` (CodingDecision) instead of
+   `RcmCodingAssistanceResult`; map dispositions `review_required` /
+   `abstain` / `escalate` and render gaps and conflicts from the decision
+   primitives.
+4. Optionally replace the `RcmCodingAssistant` component with `CodingReview`.
+5. Record reviewer dispositions with `recordReviewerAction` instead of
+   host-side tracking.
+
+The RCM and generic paths are equally auditable and safety-checked; both
+forward structured context only and keep policy text out of the browser.
+The full migration guide — field-by-field input mapping, result-shape
+mapping, and a runnable before/after example — is in
+[Migrating from the RCM coding-assistance API](docs/migration-rcm.md).
+
 ### 3. React Hook
 
 Use `useCareCompass` when your React app needs its own visual design but does
@@ -407,6 +744,36 @@ fail closed when the provider is absent, fails, or returns an empty token.
 
 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.
 
+### Input adapters (FHIR, CSV, JSON, X12)
+
+Customers who already carry claims in their own formats can submit them
+through the same coding packs without building a CodingCase by hand. SDK
+helpers build the versioned `{adapter, sourcePayload}` envelope; the
+hosted runtime normalizes it into the canonical CodingCase:
+
+```ts
+import {
+  fhirR4ClaimPayload,
+  csvRowPayload,
+  jsonClaimPayload,
+  x12837Payload,
+} from "@nexalink/carecompass-sdk/adapters";
+import { createCareCompassClient } from "@nexalink/carecompass-sdk/client";
+
+const client = createCareCompassClient(config, { runtimeTokenProvider });
+
+await client.submitCodingCase({
+  packId: "rcm-coding-assistance",
+  caseSchemaVersion: "coding-case-v1",
+  ...fhirR4ClaimPayload(fhirClaimBundleOrResource), // or csvRowPayload / jsonClaimPayload / x12837Payload
+});
+```
+
+Supported adapters: `fhir-r4-claim-v1`, `csv-row-v1`, `json-claim-v1`,
+`x12-837-claim-v1`. The resolved pack authorizes adapters; unknown or
+undeclared adapters fail closed. The SDK never parses claims, fabricates
+data, or bypasses tenant authorization — it only builds the envelope.
+
 ```bash
 npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://app.acme-health.com
 npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
@@ -605,6 +972,7 @@ The SDK is designed to keep sensitive operational details out of the browser:
 - no model endpoint credentials in browser code
 - no customer-managed telemetry switches in runtime config
 - 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
+- structured coding submissions carry the pack id and canonical CodingCase only: no prompt configuration, model preferences, feature flags, policy text, corpus ids, or credentials
 - generated snippets escape serialized config
 - default React rendering escapes raw HTML
 
@@ -625,6 +993,8 @@ Requests still route through Nexalink-hosted APIs. The browser embed does not re
 - `Origin is not authorized`: add the exact website origin to the Nexalink SDK configuration.
 - `Prompt configuration violates CareCompass guardrails`: remove unsafe or unsupported instructions and re-run validation.
 - `CareCompass embed client is not authorized`: confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued for the deployment.
+- `Unsupported scope` on a coding submission: the pack, service date, setting, or jurisdiction is not authorized for this tenant on this runtime; authorize the pack in the tenant portal or submit an in-scope case.
+- `Invalid decision` on a coding submission: the runtime returned a result that violated the canonical CodingDecision contract; the SDK failed closed and the case must go to a qualified coder.
 
 ## License
 

package/dist/adapters.d.ts

@@ -0,0 +1,54 @@
+/**
+ * CareCompass coding input adapters (NEX-115).
+ *
+ * Adapters let customers submit their existing healthcare and operational
+ * formats through the hosted runtime without coupling the SDK to one
+ * transport or EHR. These helpers build the `{adapter, sourcePayload}`
+ * envelope the server-side registry normalizes into the canonical CodingCase.
+ *
+ * Client-side envelope construction only: the SDK never parses claim
+ * semantics itself, never fabricates data, and keeps the same validation and
+ * tenant-authorization guarantees as every other coding submission. Mapping
+ * versions are declared explicitly so a server that has not adopted a mapping
+ * can fail closed instead of guessing.
+ */
+export declare const ADAPTER_IDS: {
+    readonly FHIR_R4_CLAIM: "fhir-r4-claim-v1";
+    readonly CSV_ROW: "csv-row-v1";
+    readonly JSON_CLAIM: "json-claim-v1";
+    readonly X12_837_CLAIM: "x12-837-claim-v1";
+};
+export type CareCompassAdapterId = (typeof ADAPTER_IDS)[keyof typeof ADAPTER_IDS];
+export type CareCompassAdapterEnvelope = {
+    adapter: CareCompassAdapterId;
+    sourcePayload: NonNullable<unknown>;
+};
+/**
+ * Build a FHIR R4/R4B claim envelope from a Claim resource or a
+ * self-contained Bundle containing the Claim and its referenced resources.
+ */
+export declare const fhirR4ClaimPayload: (source: Record<string, unknown>) => CareCompassAdapterEnvelope;
+/**
+ * Build a validated CSV template envelope. Pass the single-row CSV text
+ * (header + one data row) directly, or a one-row JSON batch template as
+ * `{ rows: [{ ... }] }`.
+ */
+export declare const csvRowPayload: (source: string | {
+    csv?: string;
+    rows?: Array<Record<string, unknown>>;
+}) => CareCompassAdapterEnvelope;
+/**
+ * Build a customer-native JSON claim template envelope.
+ */
+export declare const jsonClaimPayload: (source: Record<string, unknown> | {
+    claims: Array<Record<string, unknown>>;
+}) => CareCompassAdapterEnvelope;
+/**
+ * Build a bounded X12 837 claim envelope from raw EDI text or a segment
+ * array. Import subset only: 835 export remains a documented boundary.
+ */
+export declare const x12837Payload: (source: string | {
+    edi?: string;
+    segments?: string[][];
+}) => CareCompassAdapterEnvelope;
+export declare const careCompassAdapterIds: () => CareCompassAdapterId[];

package/dist/adapters.js

@@ -0,0 +1,53 @@
+/**
+ * CareCompass coding input adapters (NEX-115).
+ *
+ * Adapters let customers submit their existing healthcare and operational
+ * formats through the hosted runtime without coupling the SDK to one
+ * transport or EHR. These helpers build the `{adapter, sourcePayload}`
+ * envelope the server-side registry normalizes into the canonical CodingCase.
+ *
+ * Client-side envelope construction only: the SDK never parses claim
+ * semantics itself, never fabricates data, and keeps the same validation and
+ * tenant-authorization guarantees as every other coding submission. Mapping
+ * versions are declared explicitly so a server that has not adopted a mapping
+ * can fail closed instead of guessing.
+ */
+export const ADAPTER_IDS = {
+    FHIR_R4_CLAIM: "fhir-r4-claim-v1",
+    CSV_ROW: "csv-row-v1",
+    JSON_CLAIM: "json-claim-v1",
+    X12_837_CLAIM: "x12-837-claim-v1",
+};
+/**
+ * Build a FHIR R4/R4B claim envelope from a Claim resource or a
+ * self-contained Bundle containing the Claim and its referenced resources.
+ */
+export const fhirR4ClaimPayload = (source) => ({
+    adapter: ADAPTER_IDS.FHIR_R4_CLAIM,
+    sourcePayload: source,
+});
+/**
+ * Build a validated CSV template envelope. Pass the single-row CSV text
+ * (header + one data row) directly, or a one-row JSON batch template as
+ * `{ rows: [{ ... }] }`.
+ */
+export const csvRowPayload = (source) => ({
+    adapter: ADAPTER_IDS.CSV_ROW,
+    sourcePayload: typeof source === "string" ? { csv: source } : source,
+});
+/**
+ * Build a customer-native JSON claim template envelope.
+ */
+export const jsonClaimPayload = (source) => ({
+    adapter: ADAPTER_IDS.JSON_CLAIM,
+    sourcePayload: source,
+});
+/**
+ * Build a bounded X12 837 claim envelope from raw EDI text or a segment
+ * array. Import subset only: 835 export remains a documented boundary.
+ */
+export const x12837Payload = (source) => ({
+    adapter: ADAPTER_IDS.X12_837_CLAIM,
+    sourcePayload: source,
+});
+export const careCompassAdapterIds = () => Object.values(ADAPTER_IDS);

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 {};