@nexalink/carecompass-sdk 0.2.0-beta.14 → 0.2.0-beta.15

package/README.md

@@ -1,29 +1,84 @@
-# CareCompass Healthcare SDK
+# CareCompass Healthcare AI Infrastructure SDK
 
-CareCompass is a healthcare navigation AI for healthcare apps and portals. The SDK gives payers, providers, employers, and healthcare technology teams a branded member-facing chat experience backed by Nexalink-hosted AI infrastructure.
+CareCompass helps healthcare teams launch branded healthcare navigation assistants, member support assistants, and patient-facing AI experiences inside their own portals or applications. The SDK combines an embeddable chat experience with Nexalink-hosted healthcare AI infrastructure, reducing the implementation effort required to move from idea to deployable healthcare navigation workflow.
 
-CareCompass is not a general-purpose LLM SDK, medical diagnosis tool, replacement for clinical decision making, or system for autonomous treatment recommendations.
+The SDK is publicly installable for developer convenience, but live regulated use requires Nexalink onboarding, issued credentials, and BAA coverage where PHI may be involved. CareCompass is designed for healthcare navigation and support workflows. It is not a general-purpose LLM SDK, not a medical diagnosis tool, not autonomous treatment recommendation software, and not a replacement for clinicians or clinical judgment.
+
+## Who It's For
+
+- Healthcare startups building AI-powered patient experiences
+- Payer innovation and member engagement teams
+- Employer-benefits platforms
+- Provider organizations adding patient-facing support workflows
+- Digital health engineering teams
+- Healthcare product teams that need AI infrastructure quickly
+
+## Why Teams Use CareCompass
+
+- **Faster deployment**: add a healthcare-focused AI assistant to an existing healthcare product without months of infrastructure work.
+- **Reduced engineering effort**: avoid building and operating the supporting healthcare AI infrastructure around the assistant.
+- **Hosted healthcare AI runtime**: chat requests route through Nexalink-hosted APIs and the CareCompass AI runtime.
+- **Embedded branded experience**: use the React component, JavaScript mount helper, generated embed page, or iframe with your display name, labels, theme, logo, and support links.
+- **Prompt and configuration controls**: define approved prompt context, welcome copy, placement, allowed origins, and deployment environment.
+- **Deployment controls**: use key management, origin allowlists, hosted validation, and staging/production credential separation.
+- **Enterprise onboarding**: support BAA-gated onboarding where PHI may be involved.
+
+## Why Not Build It Yourself?
+
+Most healthcare teams can access foundation models through OpenAI, Anthropic, Bedrock, Azure OpenAI, or similar providers. The harder work is not obtaining an LLM. The harder work is building and operating the healthcare AI infrastructure around it:
+
+- Healthcare-focused prompts and guardrails
+- Hosted inference infrastructure
+- Tenant isolation
+- Key management
+- Deployment validation
+- Browser embedding
+- Usage tracking
+- Compliance-oriented onboarding
+
+CareCompass provides a managed healthcare AI infrastructure layer for these workflows, while keeping the embedded experience configurable for your application and brand.
+
+## What You Avoid Building
+
+- Model gateway
+- Chat embed
+- Prompt validation layer
+- Tenant and key management
+- Usage tracking
+- Hosted inference path
+- Staging and production credential separation
+- Deployment validation tooling
+- Compliance-oriented onboarding workflow
 
 ## What You Can Build
 
-- Member navigation assistants
-- Benefits guidance tools
-- Provider discovery experiences
-- Healthcare support chat interfaces
+- Member support assistants
+- Benefits navigation assistants
+- Provider discovery support flows
 - Employer healthcare navigation portals
 - Payer member engagement tools
+- Digital health support chat experiences
+
+## Example Questions CareCompass Can Help With
+
+CareCompass is intended for healthcare navigation and support, not diagnosis or treatment recommendations. Example navigation questions include:
 
-## Why CareCompass
+- "How do I find an in-network cardiologist?"
+- "What does my deductible mean?"
+- "How do I schedule a specialist appointment?"
+- "Where can I find behavioral health resources?"
+- "What support resources are available through my plan?"
 
-- **Healthcare-focused experience**: prompts, labels, guardrails, and defaults are oriented around healthcare navigation.
-- **Hosted AI infrastructure**: chat requests go through Nexalink-hosted APIs and the Nexalink-managed AI runtime.
-- **Branding and customization**: configure display name, logo, support links, theme, labels, placement, and approved prompt context.
-- **Usage tracking**: Nexalink tracks usage under issued keys for deployment monitoring and future metered billing.
-- **Enterprise deployment support**: use separate staging/production keys, origin allowlists, validation, BAA-gated onboarding where PHI may be involved, and security controls.
+## What CareCompass Is Not
+
+- Not a general-purpose LLM SDK
+- Not a diagnosis tool
+- Not a replacement for clinical judgment
+- Not autonomous treatment recommendation software
 
 ## Quick Start
 
-The package is publicly installable for developer convenience. Live regulated use requires Nexalink onboarding, BAA coverage where PHI may be involved, and Nexalink-issued credentials.
+Account creation and credentials are required because CareCompass is healthcare AI infrastructure for regulated deployment workflows, not an unauthenticated demo widget. The CLI requires Node.js 18 or newer.
 
 ```bash
 npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
@@ -39,7 +94,7 @@ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.jso
 - `carecompass/carecompass-iframe.html`
 - `carecompass/README.md`
 
-`npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package. The CLI requires Node.js 18 or newer.
+`npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package.
 
 ## How It Works
 
@@ -53,19 +108,22 @@ Nexalink Hosted APIs
 CareCompass AI Runtime
 ```
 
-Your application renders the React component, JavaScript mount helper, generated embed page, or iframe. The browser receives only public embed configuration: payer ID, environment, public embed key, branding, labels, theme, support links, approved prompt settings, and telemetry defaults. Chat goes to Nexalink-hosted CareCompass API routes.
+Your application renders the CareCompass UI through the SDK. The browser receives only public embed configuration: payer ID, environment, public embed key, branding, labels, theme, support links, approved prompt settings, placement, and telemetry defaults. The browser does not receive the secret API key, private model endpoint details, SageMaker credentials, AppSync signing roles, or Nexalink server-side allowlists.
+
+Chat requests go to Nexalink-hosted CareCompass API routes. Those hosted routes are responsible for authorization, origin validation, tenant isolation, prompt guardrails, rate limiting, request attribution, usage tracking, and routing to the CareCompass AI runtime.
+
+## Account, Credentials, and BAA Requirements
 
-## Account Requirements
+A Nexalink account with SDK access is required beyond package installation so Nexalink can validate payer identity, deployment environment, allowed origins, approved prompt configuration, credentials, and API usage.
 
-A Nexalink account with SDK access is required beyond package installation so Nexalink can validate payer identity, environment, secret API key, public embed key, allowed origins, approved prompt configuration, and API usage. API keys are issued in the Nexalink portal. When PHI may be involved, a tenant owner or admin executes the canonical BAA before generating the first key. The secret API key is shown once, stored locally, and must never be committed or placed in browser code.
+CareCompass uses two different keys:
 
-## Common Use Cases
+- **API key**: a secret credential for trusted setup and server-side or CLI workflows, including `init` sign-in and validation. 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 or proof of identity on its own.
 
-- Payers: branded member assistants for benefits, coverage navigation, support resources, and next steps.
-- Employers: healthcare navigation portals that route employees to plan resources and approved support channels.
-- Providers and digital health companies: support chat with model access, validation, and usage tracking behind Nexalink-hosted APIs.
+API keys are issued in the Nexalink portal. When PHI may be involved, a tenant owner or admin may need to execute the canonical BAA before generating the first key. The secret API key is shown once, stored locally by the developer, and should be handled as a server-side or CLI credential.
 
-## React Example
+## React Usage
 
 ```tsx
 import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
@@ -76,7 +134,7 @@ export function MemberSupport() {
 }
 ```
 
-## JavaScript Example
+## JavaScript Usage
 
 ```ts
 import { mountCareCompass } from "@nexalink/carecompass-sdk";
@@ -85,76 +143,6 @@ import config from "./carecompass/carecompass.config.json";
 mountCareCompass(document.getElementById("carecompass-root"), config);
 ```
 
-## Enterprise Features
-
-CareCompass uses separate credentials for trusted setup and browser runtime:
-
-- **API key**: a secret credential for trusted setup and server-side/CLI workflows, including `init` sign-in and validation. 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 or proof of identity on its own.
-
-Enterprise concepts include API keys, embed keys, origin allowlists, BAA requirements where PHI may be involved, usage tracking, future Stripe metered billing support, hosted validation, prompt guardrails, rate limiting, request attribution, tenant isolation, and staging/production separation. Enterprise signup and BAA execution happen in the Nexalink web app before API key creation.
-
-Use separate keys and config files for staging and production:
-
-```bash
-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 the exact origin allowlist, a production-specific `embedKey`, approved Nexalink-hosted `apiBaseUrl`, support links, prompt instructions, and no secret API key in generated source code.
-
-## Security & Compliance
-
-CareCompass keeps secret SDK API keys out of the browser. The browser uses public `embedKey`, payer ID, environment, and allowed origin metadata to call Nexalink-hosted embed API routes. Staging and production `apiBaseUrl` values must be Nexalink-hosted HTTPS URLs; `localhost` is accepted only for `development`.
-
-The browser does not receive SageMaker credentials, AppSync signing roles, private model endpoint details, Nexalink server-side allowlists, or the secret SDK API key. Generated snippets escape serialized config, and React renders chat messages and labels as text.
-
-Telemetry is enabled automatically with Nexalink-managed defaults. The SDK sends only allowlisted anonymous deployment-health events 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, responses, chat history, user context, PHI/PII, credentials, raw errors, stack traces, CLI arguments, terminal input, and file paths are excluded.
-
-Some MVP and development model endpoints may use scale-to-zero capacity; first request after an idle period can take several minutes while the endpoint warms through Nexalink-hosted APIs.
-
-## CLI Reference
-
-### `init`
-
-Runs first-time setup: routes users to signup, validates the API key, stores it locally, and generates the config, prompt starter, embed page, iframe, and setup guide with only public embed configuration.
-
-Credentials are stored at `~/.nexalink/carecompass/credentials.json` by default. You can also set `CARECOMPASS_API_KEY`. For scripted setup, pass `--account-type developer`. Configure signup with `--developer-signup-url` or `CARECOMPASS_DEVELOPER_SIGNUP_URL`; default: `https://www.nexalink.care/developer/signup`.
-
-Generated HTML defaults to bundler-friendly imports from `@nexalink/carecompass-sdk`. For a raw browser HTML demo that is not processed by a bundler, add `--snippet-mode cdn`.
-
-```bash
-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 local config shape and credentials, then hosted validation for `apiBaseUrl`, `embedKey`, `payerId`, `environment`, and `allowedOrigins` unless `--local-only` is passed. Browser-side validation uses public embed headers and does not send the secret API key.
-
-```bash
-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.
-
-```bash
-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.
-
-```bash
-npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
-```
-
 ## Configuration Reference
 
 `carecompass/carecompass.config.json` is safe to commit when it contains only public embed configuration. Store the secret API key only in local CLI credentials or an approved server-side secret store.
@@ -212,6 +200,61 @@ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.jso
 
 Serve `carecompass/carecompass-embed.html` at the iframe `src`, often by copying the generated `carecompass` folder into public/static assets.
 
+## CLI Reference
+
+### `init`
+
+Runs first-time setup: routes users to signup, validates the API key, stores it locally, and generates the config, prompt starter, embed page, iframe, and setup guide with only public embed configuration.
+
+Credentials are stored at `~/.nexalink/carecompass/credentials.json` by default. You can also set `CARECOMPASS_API_KEY`. For scripted setup, pass `--account-type developer`. Configure signup with `--developer-signup-url` or `CARECOMPASS_DEVELOPER_SIGNUP_URL`; default: `https://www.nexalink.care/developer/signup`.
+
+Generated HTML defaults to bundler-friendly imports from `@nexalink/carecompass-sdk`. For a raw browser HTML demo that is not processed by a bundler, add `--snippet-mode cdn`.
+
+```bash
+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 local config shape and credentials, then hosted validation for `apiBaseUrl`, `embedKey`, `payerId`, `environment`, and `allowedOrigins` unless `--local-only` is passed. Browser-side validation uses public embed headers and does not send the secret API key.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
+```
+
+## Security and Compliance Model
+
+CareCompass is BAA-gated where PHI may be involved and HIPAA-oriented for regulated healthcare deployment workflows, but this README does not claim blanket HIPAA compliance for every implementation or deployment.
+
+The SDK keeps secret keys out of the browser. Browser code receives public embed configuration only. Staging and production `apiBaseUrl` values must be Nexalink-hosted HTTPS URLs; `localhost` is accepted only for `development`.
+
+Nexalink-hosted API routes are responsible for authorization, origin allowlists, tenant isolation, prompt guardrails, rate limiting, request attribution, and usage tracking. Generated snippets escape serialized config, and React renders chat messages and labels as text.
+
+Telemetry is enabled automatically with Nexalink-managed defaults. The SDK sends only allowlisted anonymous deployment-health events 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, responses, chat history, user context, PHI/PII, credentials, raw errors, stack traces, CLI arguments, terminal input, and file paths are excluded from telemetry.
+
+## Runtime Notes
+
+Some development and MVP environments may use scale-to-zero infrastructure, which can add cold-start latency to the first request after an idle period. The request still routes through Nexalink-hosted APIs; the browser embed does not receive infrastructure credentials or call the model endpoint directly.
+
 ## Troubleshooting
 
 - `Missing Nexalink API key`: run `init`, choose Developer, and sign in. For scripts, pass `--account-type developer` with `--api-key <key>`, or set `CARECOMPASS_API_KEY` with `CARECOMPASS_ACCOUNT_TYPE=developer`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexalink/carecompass-sdk",
-  "version": "0.2.0-beta.14",
+  "version": "0.2.0-beta.15",
   "description": "Embeddable CareCompass SDK and CLI for healthcare ecosystem integrations with Nexalink onboarding, BAA coverage, and API keys.",
   "type": "module",
   "packageManager": "bun@1.3.9",