@nexalink/carecompass-sdk 0.6.1 → 0.7.1

package/README.md

@@ -1,23 +1,44 @@
 # CareCompass SDK
 
-CareCompass is embeddable healthcare AI infrastructure for teams building AI-powered healthcare products.
+CareCompass by Nexalink is an embeddable SDK for AI-assisted medical-coding review, built for behavioral-health EHR and RCM platforms.
 
-It gives healthcare companies a secure SDK and hosted runtime for adding LLM-powered experiences to their own applications without building the regulated AI stack from scratch: model routing, tenant-aware runtime APIs, browser-safe authentication, prompt controls, guardrails, origin validation, deployment checks, and healthcare-specific onboarding.
+It brings coding suggestions, references from the payer policies your team supplies and approves, and missing-documentation flags into your existing product. A qualified human reviewer makes the final coding decision, and that decision is recorded.
 
-CareCompass is for teams that want to ship their own AI product experience while relying on Nexalink to operate the healthcare AI infrastructure layer underneath.
+Your team can add coding review without building and maintaining the supporting AI runtime and policy-research tools itself. Your team remains responsible for approved policies, its integration, and qualified review. Pilot scope, goals, and pricing are agreed with your team before starting; real patient data requires security review and a signed BAA.
 
 The SDK gives teams two integration paths:
 
 - **Headless core** for product teams that want full control over their own UI, workflow, state management, and rendering.
-- **Optional UI kit** for teams that want a fast, branded AI chat experience they can drop into a web app and customize over time.
+- **Optional UI kit** for teams that want embedded review components and a branded experience they can customize over time.
 
-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.
+CareCompass supports coding review; it does not submit claims, bill payers, diagnose, or replace qualified reviewers. Prior authorization and patient navigation are future directions, not the current product. Generic chat APIs described below are integration primitives, not a promise of those workflows.
+
+See the [CareCompass product overview](https://www.nexalink.care/carecompass), [public developer documentation](https://www.nexalink.care/developer/documentation), and [pilot contact page](https://www.nexalink.care/enterprise/signup).
+
+## 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.
+Getting an AI prototype working is only the beginning. A coding-review feature also needs approved policy evidence, data handling, and a reliable human review process.
 
-CareCompass packages the healthcare-specific infrastructure layer that most teams would otherwise need to build themselves:
+CareCompass supplies supporting components your team would otherwise need to build and maintain:
 
 - secure hosted runtime APIs
 - tenant and environment routing
@@ -29,22 +50,18 @@ CareCompass packages the healthcare-specific infrastructure layer that most team
 - white-label UI support
 - operational onboarding for healthcare use cases
 
-Instead of spending months building LLM infrastructure, product teams can use CareCompass to embed AI into their own application and focus on the workflow, customer experience, and clinical or operational use case they are trying to ship.
+Product teams can focus on their own product while qualified reviewers assess suggestions alongside the approved evidence.
 
 ## What You Can Build
 
-CareCompass can power healthcare AI features inside products such as:
+The current product supports a defined medical-coding review workflow inside your existing healthcare software:
 
-- clinical workflow copilots
-- patient engagement assistants
-- care navigation and resource guidance flows
-- benefits or plan guidance experiences
-- RCM and prior authorization support tools
-- onboarding and support flows for digital health products
-- internal operations copilots for healthcare teams
-- white-labeled AI assistants inside existing healthcare applications
+- Submit structured encounter information for an authorized coding workflow.
+- Show suggested codes with supporting policy references and documentation gaps.
+- Route unsupported or uncertain cases for qualified review.
+- Record a qualified reviewer's approval, edits, rejection, or escalation.
 
-CareCompass is intentionally workflow-agnostic at the infrastructure layer. The customer owns the product experience; CareCompass provides the SDK, runtime, guardrails, and deployment model needed to make healthcare AI usable in production.
+Your team owns the product experience, supplies and approves the policies, and keeps the final coding decision with a qualified reviewer.
 
 ## What You Avoid Building
 
@@ -81,7 +98,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 +197,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 +274,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 +742,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 +970,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 +991,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);