CareCompass Payer Embed SDK

@nexalink/carecompass-sdk helps payer teams embed a branded CareCompass chat experience in their own websites and applications. It includes a React component, a vanilla JavaScript mount helper, shared configuration validation, and a CLI for setup, validation, snippet generation, and local diagnostics.

CareCompass lets a payer offer member-facing navigation support while keeping LLM inference behind Nexalink-hosted APIs. The payer controls the placement, branding, theme, labels, support links, allowed origins, and approved prompt configuration. Nexalink controls account validation, API-key enforcement, embed-key authorization, usage tracking, and the hosted model path.

This package is publicly installable for developer convenience, but meaningful use requires a Nexalink payer account and a Nexalink-issued API key.

Who This Is For

This SDK is for enterprise healthcare teams that want to add CareCompass to a payer-owned frontend without building their own model gateway, prompt validation layer, key-management flow, or token-metering pipeline.

Typical users include:

• payer portal developers embedding CareCompass in a member site
• implementation engineers configuring staging and production deployments
• technical operators validating origins, branding, and prompt policy
• non-technical payer admins issuing SDK keys from the payer portal

Account Required

You need a Nexalink payer account before using the SDK beyond package installation.

The account is required because Nexalink validates:

• the payer ID
• the secret SDK API key
• the public browser embed key
• the deployment environment
• the allowed website origins
• the approved prompt configuration
• API usage and token counts for future metered billing

API keys are issued in the Nexalink payer portal under the CareCompass SDK section. The secret API key is shown once and should be stored locally by the developer. It should never be committed to source control or placed in browser code.

If you do not have an API key, run:

npx @nexalink/carecompass-sdk login

The CLI will direct you to the payer signup path.

Install And Run

Use any common JavaScript package manager. For first-time testing, the simplest path is to run each command with npx.

npx @nexalink/carecompass-sdk login --api-key <nexalink-api-key>
npx @nexalink/carecompass-sdk init --payer-id acme-health --origin https://members.acme-health.com
npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json

npx does not permanently install a carecompass shell command. If you use npx for login, keep using npx @nexalink/carecompass-sdk <command> for init, validate, snippet, and doctor.

Package-manager equivalents:

npm exec --package @nexalink/carecompass-sdk -- carecompass init
pnpm dlx @nexalink/carecompass-sdk init
yarn dlx @nexalink/carecompass-sdk init
bunx @nexalink/carecompass-sdk init

You can also install it in a project and run the binary through your package manager:

npm install @nexalink/carecompass-sdk
npm exec carecompass -- init --payer-id acme-health --origin https://members.acme-health.com

Or install it globally if your organization permits global npm tools:

npm install -g @nexalink/carecompass-sdk
carecompass init --payer-id acme-health --origin https://members.acme-health.com

CLI Commands

login

Stores your secret Nexalink API key locally so the other SDK commands can validate your payer configuration.

npx @nexalink/carecompass-sdk login --api-key <nexalink-api-key>

Credentials are stored at ~/.nexalink/carecompass/credentials.json by default. You can also set CARECOMPASS_API_KEY in your shell or CI environment.

init

Creates a carecompass folder with all generated SDK files in one place:

• carecompass/carecompass.config.json
• carecompass/system-prompt.md
• carecompass/carecompass-embed.html

The config file contains payer-facing configuration only. It does not contain the secret API key. The embed HTML is generated automatically during init; you do not need to run a separate snippet command for the first setup.

By default, generated HTML is bundler-friendly and imports the package as @nexalink/carecompass-sdk, which works with Parcel, Vite, Next.js, and similar tooling when the package is installed as a dependency. For a raw browser HTML demo that is not processed by Parcel or another bundler, add --snippet-mode cdn.

npx @nexalink/carecompass-sdk init --payer-id acme-health --origin https://members.acme-health.com
npx @nexalink/carecompass-sdk init --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com

validate

Checks that the config shape is valid and that credentials are available. By default this also calls the hosted Nexalink config-validation endpoint, which confirms the API base URL, API key, embed key, environment, and first allowed origin are accepted by the server. Use --local-only for schema-only checks.

npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
npx @nexalink/carecompass-sdk validate --local-only --config carecompass/carecompass.config.json

snippet

Regenerates the HTML embed snippet after config, branding, origin, or prompt changes. init already runs this once.

npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json
npx @nexalink/carecompass-sdk snippet --snippet-mode cdn --config carecompass/carecompass.config.json

doctor

Prints a deployment readiness summary for the selected config.

npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json

Configuration

carecompass/carecompass.config.json is safe to commit when it only contains public embed configuration. Do not add the secret API key to this file.

{
  "payerId": "acme-health",
  "environment": "staging",
  "apiBaseUrl": "https://www.nexalink.care",
  "embedKey": "embed_public_key_from_nexalink",
  "allowedOrigins": ["https://members.acme-health.com"],
  "branding": {
    "displayName": "Acme Health",
    "logoUrl": "https://members.acme-health.com/logo.svg",
    "supportUrl": "https://members.acme-health.com/support"
  },
  "theme": {
    "primaryColor": "#2563eb",
    "backgroundColor": "#ffffff",
    "textColor": "#111827",
    "borderRadius": "8px",
    "fontFamily": "system-ui, sans-serif"
  },
  "labels": {
    "title": "Acme Care Guide",
    "placeholder": "Ask about benefits, care options, or next steps...",
    "sendButton": "Send",
    "disclaimer": "CareCompass provides navigation support, not medical advice.",
    "errorMessage": "CareCompass is unavailable right now."
  },
  "prompt": {
    "systemInstructionFile": "./system-prompt.md",
    "welcomeMessage": "How can I help you navigate your care today?",
    "allowUserContext": false
  },
  "placement": {
    "mode": "inline"
  },
  "deploymentTarget": "web"
}

System Prompt File

carecompass/system-prompt.md lets the payer define approved context before a member message reaches the LLM. Use it to steer CareCompass toward plan-specific terminology, support boundaries, escalation rules, and benefit-navigation context.

The prompt file is resolved by the CLI when it generates carecompass/carecompass-embed.html. The browser receives the resolved prompt text, not a local file path. Prompt content is still validated against Nexalink guardrails.

React Usage

import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
import config from "./carecompass/carecompass.config.json";

export function MemberSupport() {
  return <CareCompassEmbed config={config} />;
}

Vanilla JavaScript Usage

import { mountCareCompass } from "@nexalink/carecompass-sdk";
import config from "./carecompass/carecompass.config.json";

mountCareCompass(document.getElementById("carecompass-root"), config);

Package Exports

import {
  CareCompassEmbed,
  mountCareCompass,
  validateCareCompassConfig,
  createCareCompassClient,
} from "@nexalink/carecompass-sdk";

import type {
  CareCompassConfig,
  CareCompassTheme,
  CareCompassLabels,
  CareCompassPromptConfig,
} from "@nexalink/carecompass-sdk";

Runtime Dependencies

The package has a small runtime surface:

• zod for shared config validation
• react as a peer dependency for the embed component
• react-dom as a peer dependency for mounting

Peer dependency range:

{
  "react": "^18.3.0 || ^19.0.0",
  "react-dom": "^18.3.0 || ^19.0.0"
}

The CLI requires Node.js 18 or newer.

What Runs In The Browser

The browser receives only public embed configuration:

• payer ID
• environment
• public embedKey
• branding and theme values
• labels and support links
• approved prompt settings

The browser does not receive:

• the secret SDK API key
• SageMaker credentials
• private model endpoint details
• Nexalink server-side allowlists

Chat requests are sent to Nexalink-hosted CareCompass API routes. The component does not call the model endpoint directly.

API Keys And Usage Tracking

SDK API keys are issued in the payer portal and stored server-side as hashes. Each key is associated with a payer, environment, public embed key, and allowed origins.

CareCompass usage under a key is tracked so Nexalink can support future Stripe metered billing. The backend records estimated prompt tokens, completion tokens, total tokens, and last-used timestamps per payer/API key.

Staging And Production

Use separate keys and config files for staging and production.

npx @nexalink/carecompass-sdk validate --config carecompass.staging.json
npx @nexalink/carecompass-sdk snippet --config carecompass.staging.json --output carecompass/staging-embed.html
npx @nexalink/carecompass-sdk doctor --config carecompass.staging.json

Before production, confirm:

• production origin is allowlisted exactly
• production embedKey is separate from staging
• support links route to the payer's approved support surface
• prompt instructions are approved by Nexalink and the payer
• no secret API key appears in generated source code

Troubleshooting

Missing Nexalink API key

Run npx @nexalink/carecompass-sdk login --api-key <key> or set CARECOMPASS_API_KEY.

zsh: command not found: carecompass

You ran the SDK with npx, which does not install a permanent global command. Run the next command with npx @nexalink/carecompass-sdk <command>, install the package in your project, or install it globally.

@parcel/core: Failed to resolve 'https://esm.sh/...'

Regenerate the snippet with the default bundler mode instead of CDN mode: npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json. Parcel does not allow https: imports in HTML. CDN mode is only for raw browser HTML that is not bundled.

CareCompass could not reach http://localhost:3000

The browser cannot reach the configured API base URL. If the embed is running in a hosted sandbox, localhost points at the sandbox/browser environment, not the Nexalink server on your machine. Run the Nexalink web app locally and test from a local page, or point apiBaseUrl at a deployed Nexalink environment that has the CareCompass embed API routes deployed. Run validate to check this before typing into the embed.

Origin is not authorized

Add the exact website origin to the payer portal 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 in the payer portal.

CareCompass inference service is not configured

Nexalink server operators should confirm the hosted environment has CARECOMPASS_LLM_URL configured.

License

This SDK is proprietary software owned by Nexalink Health, Inc. See the included LICENSE file.