CareCompass Healthcare Embed SDK

@nexalink/carecompass-sdk helps healthcare organizations 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 healthcare teams offer member-facing navigation support while keeping LLM inference behind Nexalink-hosted APIs. The integrating organization 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 live regulated use requires Nexalink onboarding, BAA coverage where PHI may be involved, and Nexalink-issued API credentials.

Who This Is For

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

Typical users include:

• payer, provider, employer-benefits, care-navigation, and digital-health teams embedding CareCompass in a member or patient site
• implementation engineers configuring staging and production deployments
• technical operators validating origins, branding, and prompt policy
• non-technical customer admins issuing SDK keys from the Nexalink portal

Account Required

You need a Nexalink account with SDK access before using the SDK beyond package installation. For deployments that may involve PHI, a signed BAA and approved credentials are required before live use.

The account is required because Nexalink validates:

• the customer or 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 portal under the CareCompass SDK section. For first-time onboarding, a tenant owner or admin executes the canonical BAA from the portal BAA page before generating the first key. 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.

API Key Vs Embed Key

CareCompass uses two different keys with different security expectations:

• API key: a secret credential for trusted setup and server-side/CLI workflows. Use it to authenticate actions such as signing in during init and creating or managing SDK access. Never include it in browser code, generated embed HTML, frontend config, or source control.
• Embed key: a public browser-facing identifier for the CareCompass embed. It is safe to include in carecompass.config.json and generated snippets. It identifies the payer, environment, and embed client for runtime requests, but it is not a secret and should not be treated as proof of identity on its own.

Start onboarding with:

npx @nexalink/carecompass-sdk init

The CLI routes developers without accounts to the configured signup path, validates the API key with Nexalink, stores it locally only after successful sign-in, and generates the SDK config. BAA execution happens in the Nexalink web app before API key creation.

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 init --account-type developer --api-key <nexalink-api-key> --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. 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

init

Runs the complete first-time onboarding flow:

• routes users without accounts to the configured signup path
• validates the API key with Nexalink before continuing
• stores the secret Nexalink API key locally
• generates the SDK config, prompt starter, embed page, iframe, and setup guide with only public embed configuration

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

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

Credentials are stored at ~/.nexalink/carecompass/credentials.json by default. You can also set CARECOMPASS_API_KEY in your shell or CI environment. The generated config contains payer-facing configuration only. It does not contain the secret API key. The embed HTML and iframe are generated automatically during init; you do not need to run a separate snippet command for the first setup.

For scripted setup, pass --account-type developer. The developer signup route can be configured with --developer-signup-url or CARECOMPASS_DEVELOPER_SIGNUP_URL. By default, that route is https://www.nexalink.care/developer/signup.

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 --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
npx @nexalink/carecompass-sdk init --account-type developer --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, public embed key, payer ID, environment, and allowed origins are accepted by the server. The browser-side validation request uses public embed headers; it does not send the secret API key. 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.

The config is client-facing by design. It should contain the public embedKey, the payer ID, environment, allowed origins, branding, labels, theme, and prompt settings. Store the secret API key only in the local CLI credentials file or an approved server-side secret store.

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

Privacy-Safe Telemetry

Telemetry is enabled automatically with Nexalink-managed defaults. Integrators do not need to run an additional CLI command, add a runtime config block, or manage a PostHog token. The CLI also sends anonymous onboarding funnel events using an ephemeral per-process session ID that is never persisted.

The SDK sends only allowlisted anonymous deployment-health events directly to PostHog's public ingestion API. It does not bundle posthog-js, enable session replay or autocapture, identify users, set cookies, or persist analytics state. Prompts, model responses, chat history, user context, PHI/PII, credentials, raw errors, and stack traces are never included. CLI arguments, terminal input, and file paths are also excluded.

The SDK uses a Nexalink-owned public PostHog ingestion token. See TELEMETRY.md for the shared web, React Native, and Flutter event contract.

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.

Iframe Placement

carecompass/carecompass-iframe.html contains the iframe to place on the integrating page where the CareCompass LLM should appear.

<iframe
  title="Acme Health CareCompass"
  src="/carecompass/carecompass-embed.html"
  style="width: 100%; min-height: 640px; border: 0; border-radius: 8px;"
  loading="lazy"
></iframe>

Serve carecompass/carecompass-embed.html from the integrating site at the iframe src. For many apps, that means copying the generated carecompass folder into the app's public/static assets folder before deployment.

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.

Development

This repository uses Bun for local development.

bun install
bun run build
bun run test
bun run pack:dry-run

Do not publish a new package version unless the SDK version is intentionally changed and release approval is complete.

What Runs In The Browser

The browser receives only public embed configuration:

• customer or payer ID
• environment
• public embedKey
• branding and theme values
• labels and support links
• approved prompt settings
• Nexalink-managed telemetry defaults compiled into the SDK

The browser does not receive:

• the secret SDK API key
• SageMaker credentials
• the AppSync signing role
• 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.

Hosted LLM Warm-Up

Nexalink hosts the proprietary CareCompass LLM runtime behind Nexalink-managed API routes. To control infrastructure costs for early deployments, Nexalink may run some hosted model endpoints with scale-to-zero capacity. When an endpoint has scaled to zero, the first chat request after an idle period can take several minutes while cloud GPU capacity is allocated and the model endpoint warms up.

This warm-up delay is expected for some MVP and development environments. It does not mean the browser embed needs a secret API key, and it does not mean the SDK is calling SageMaker directly. The request is queued through Nexalink-hosted APIs while the model endpoint starts. Nexalink is actively working on improvements to reduce or avoid first-request warm-up delays.

Runtime Security Model

The SDK component uses the public browser embedKey, payer ID, environment, and allowed origin metadata to call Nexalink-hosted embed API routes. The secret SDK API key is used only by trusted setup and server-side/CLI workflows and must never be placed in browser config or generated snippets.

For staging and production, apiBaseUrl must be a Nexalink-hosted HTTPS URL. localhost API and origin values are accepted only for development configurations. Hosted validation still remains authoritative: Nexalink API routes must enforce payer ID, embed key, environment, allowed origin, prompt guardrails, rate limiting, request attribution, and tenant isolation for config, analytics, logs, prompts, and model requests.

Generated snippets escape serialized config before embedding it in a module script. React renders chat messages and labels as text rather than raw HTML. Do not add dangerouslySetInnerHTML, raw HTML snippets, unreviewed third-party scripts, or payer-provided secret values to an embed page.

API Keys And Usage Tracking

SDK API keys are issued in the Nexalink portal and stored server-side as hashes. Each secret API key is associated with a customer or payer ID, environment, public embed key, and allowed origins. The API key authenticates trusted setup and management flows; the public embed key is what the browser uses for client-facing runtime requests.

CareCompass usage under a key is tracked so Nexalink can support future Stripe metered billing. The backend records prompt tokens, completion tokens, total tokens, and last-used timestamps per payer/API key. Hosted routes use MedGemma token counts when they are available and fall back to estimates only when needed.

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
• production apiBaseUrl points at the approved Nexalink-hosted environment
• 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
• diagnostics, logs, and analytics are configured to avoid raw PHI/PII, raw prompts, raw model responses, credentials, or privileged backend tokens unless Nexalink has approved a secure diagnostic path

Troubleshooting

Missing Nexalink API key

Run npx @nexalink/carecompass-sdk init, choose Developer, and sign in with an API key. For non-interactive setup, pass --account-type developer with --api-key <key>, or set CARECOMPASS_API_KEY with CARECOMPASS_ACCOUNT_TYPE=developer.

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 Nexalink 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 Nexalink portal.

CareCompass AppSync inference service is not configured

Nexalink server operators should confirm the hosted web environment has NEXT_PUBLIC_API_URL or CARECOMPASS_APPSYNC_URL configured. The SDK browser embed does not require a payer-provided LLM URL.

License

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