@nexalink/carecompass-sdk 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -1,3 +1,276 @@
-# CareCompass SDK
+# CareCompass Payer Embed SDK
 
-See the repository documentation at `docs/carecompass-sdk.md`.
+`@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:
+
+```bash
+npx @nexalink/carecompass-sdk login
+```
+
+The CLI will direct you to the payer signup path.
+
+## Install And Run
+
+Use any common JavaScript package manager.
+
+```bash
+npx @nexalink/carecompass-sdk login --api-key <nexalink-api-key>
+npm exec @nexalink/carecompass-sdk -- 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:
+
+```bash
+npm install @nexalink/carecompass-sdk
+pnpm add @nexalink/carecompass-sdk
+yarn add @nexalink/carecompass-sdk
+bun add @nexalink/carecompass-sdk
+```
+
+## CLI Commands
+
+### `carecompass login`
+
+Stores your secret Nexalink API key locally so the other SDK commands can validate your payer configuration.
+
+```bash
+carecompass 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.
+
+### `carecompass init`
+
+Creates a starter `carecompass.config.json` file. This file contains payer-facing configuration only. It does not contain the secret API key.
+
+```bash
+carecompass init --payer-id acme-health --origin https://members.acme-health.com
+```
+
+### `carecompass validate`
+
+Checks that the config shape is valid and that credentials are available.
+
+```bash
+carecompass validate --config carecompass.config.json
+```
+
+### `carecompass snippet`
+
+Generates an HTML embed snippet that can be pasted into a payer-owned page or reviewed by non-technical stakeholders.
+
+```bash
+carecompass snippet --config carecompass.config.json --output carecompass-embed.html
+```
+
+### `carecompass doctor`
+
+Prints a deployment readiness summary for the selected config.
+
+```bash
+carecompass doctor --config carecompass.config.json
+```
+
+## Configuration
+
+`carecompass.config.json` is safe to commit when it only contains public embed configuration. Do not add the secret API key to this file.
+
+```json
+{
+  "payerId": "acme-health",
+  "environment": "staging",
+  "apiBaseUrl": "https://api.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": {
+    "systemInstruction": "Help members navigate benefits and care options within approved Acme Health support policies.",
+    "welcomeMessage": "How can I help you navigate your care today?",
+    "allowUserContext": false
+  },
+  "placement": {
+    "mode": "inline"
+  },
+  "deploymentTarget": "web"
+}
+```
+
+## React Usage
+
+```tsx
+import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
+import config from "./carecompass.config.json";
+
+export function MemberSupport() {
+  return <CareCompassEmbed config={config} />;
+}
+```
+
+## Vanilla JavaScript Usage
+
+```ts
+import { mountCareCompass } from "@nexalink/carecompass-sdk";
+import config from "./carecompass.config.json";
+
+mountCareCompass(document.getElementById("carecompass-root"), config);
+```
+
+## Package Exports
+
+```ts
+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:
+
+```json
+{
+  "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.
+
+```bash
+carecompass validate --config carecompass.staging.json
+carecompass snippet --config carecompass.staging.json --output staging-embed.html
+carecompass 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 `carecompass login --api-key <key>` or set `CARECOMPASS_API_KEY`.
+
+`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.

package/package.json

@@ -1,8 +1,29 @@
 {
   "name": "@nexalink/carecompass-sdk",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Embeddable CareCompass SDK and CLI for payer-whitelabeled deployments.",
   "type": "module",
+  "homepage": "https://nexalink.care",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nexalink-care/nexalink-webapp.git",
+    "directory": "packages/carecompass-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/nexalink-care/nexalink-webapp/issues"
+  },
+  "keywords": [
+    "carecompass",
+    "nexalink",
+    "payer",
+    "healthcare",
+    "embed",
+    "sdk",
+    "react",
+    "cli",
+    "llm"
+  ],
+  "sideEffects": false,
   "bin": {
     "carecompass": "dist/cli.js"
   },
@@ -24,8 +45,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json"
   },