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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +137 -336
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,70 +1,84 @@
1
- # CareCompass Healthcare Embed SDK
1
+ # CareCompass Healthcare AI Infrastructure SDK
2
2
 
3
- `@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.
3
+ 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.
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
- 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.
7
+ ## Who It's For
8
8
 
9
- ## Who This Is For
9
+ - Healthcare startups building AI-powered patient experiences
10
+ - Payer innovation and member engagement teams
11
+ - Employer-benefits platforms
12
+ - Provider organizations adding patient-facing support workflows
13
+ - Digital health engineering teams
14
+ - Healthcare product teams that need AI infrastructure quickly
10
15
 
11
- 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.
16
+ ## Why Teams Use CareCompass
12
17
 
13
- Typical users include:
18
+ - **Faster deployment**: add a healthcare-focused AI assistant to an existing healthcare product without months of infrastructure work.
19
+ - **Reduced engineering effort**: avoid building and operating the supporting healthcare AI infrastructure around the assistant.
20
+ - **Hosted healthcare AI runtime**: chat requests route through Nexalink-hosted APIs and the CareCompass AI runtime.
21
+ - **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.
22
+ - **Prompt and configuration controls**: define approved prompt context, welcome copy, placement, allowed origins, and deployment environment.
23
+ - **Deployment controls**: use key management, origin allowlists, hosted validation, and staging/production credential separation.
24
+ - **Enterprise onboarding**: support BAA-gated onboarding where PHI may be involved.
14
25
 
15
- - payer, provider, employer-benefits, care-navigation, and digital-health teams embedding CareCompass in a member or patient site
16
- - implementation engineers configuring staging and production deployments
17
- - technical operators validating origins, branding, and prompt policy
18
- - non-technical customer admins issuing SDK keys from the Nexalink portal
26
+ ## Why Not Build It Yourself?
19
27
 
20
- ## Account Required
28
+ 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:
21
29
 
22
- 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.
30
+ - Healthcare-focused prompts and guardrails
31
+ - Hosted inference infrastructure
32
+ - Tenant isolation
33
+ - Key management
34
+ - Deployment validation
35
+ - Browser embedding
36
+ - Usage tracking
37
+ - Compliance-oriented onboarding
23
38
 
24
- The account is required because Nexalink validates:
39
+ CareCompass provides a managed healthcare AI infrastructure layer for these workflows, while keeping the embedded experience configurable for your application and brand.
25
40
 
26
- - the customer or payer ID
27
- - the secret SDK API key
28
- - the public browser embed key
29
- - the deployment environment
30
- - the allowed website origins
31
- - the approved prompt configuration
32
- - API usage and token counts for future metered billing
41
+ ## What You Avoid Building
33
42
 
34
- API keys are issued in the Nexalink portal under the CareCompass SDK section.
35
- For first-time onboarding, a tenant owner or admin executes the canonical BAA
36
- from the portal BAA page before generating the first key. The secret API key is
37
- shown once and should be stored locally by the developer. It should never be
38
- committed to source control or placed in browser code.
43
+ - Model gateway
44
+ - Chat embed
45
+ - Prompt validation layer
46
+ - Tenant and key management
47
+ - Usage tracking
48
+ - Hosted inference path
49
+ - Staging and production credential separation
50
+ - Deployment validation tooling
51
+ - Compliance-oriented onboarding workflow
39
52
 
40
- ### API Key Vs Embed Key
53
+ ## What You Can Build
41
54
 
42
- CareCompass uses two different keys with different security expectations:
55
+ - Member support assistants
56
+ - Benefits navigation assistants
57
+ - Provider discovery support flows
58
+ - Employer healthcare navigation portals
59
+ - Payer member engagement tools
60
+ - Digital health support chat experiences
43
61
 
44
- - **API key**: a secret credential for trusted setup and server-side/CLI
45
- workflows. Use it to authenticate actions such as signing in during `init` and
46
- creating or managing SDK access. Never include it in browser code, generated
47
- embed HTML, frontend config, or source control.
48
- - **Embed key**: a public browser-facing identifier for the CareCompass embed.
49
- It is safe to include in `carecompass.config.json` and generated snippets. It
50
- identifies the payer, environment, and embed client for runtime requests, but
51
- it is not a secret and should not be treated as proof of identity on its own.
62
+ ## Example Questions CareCompass Can Help With
52
63
 
53
- Start onboarding with:
64
+ CareCompass is intended for healthcare navigation and support, not diagnosis or treatment recommendations. Example navigation questions include:
54
65
 
55
- ```bash
56
- npx @nexalink/carecompass-sdk init
57
- ```
66
+ - "How do I find an in-network cardiologist?"
67
+ - "What does my deductible mean?"
68
+ - "How do I schedule a specialist appointment?"
69
+ - "Where can I find behavioral health resources?"
70
+ - "What support resources are available through my plan?"
58
71
 
59
- The CLI routes developers without accounts to the configured signup path,
60
- validates the API key with Nexalink, stores it locally only after successful
61
- sign-in, and generates the SDK config. BAA execution happens in the Nexalink web
62
- app before API key creation.
72
+ ## What CareCompass Is Not
63
73
 
64
- ## Install And Run
74
+ - Not a general-purpose LLM SDK
75
+ - Not a diagnosis tool
76
+ - Not a replacement for clinical judgment
77
+ - Not autonomous treatment recommendation software
65
78
 
66
- Use any common JavaScript package manager. For first-time testing, the simplest
67
- path is to run each command with `npx`.
79
+ ## Quick Start
80
+
81
+ 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.
68
82
 
69
83
  ```bash
70
84
  npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
@@ -72,47 +86,7 @@ npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.j
72
86
  npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
73
87
  ```
74
88
 
75
- `npx` does not permanently install a `carecompass` shell command. Keep using
76
- `npx @nexalink/carecompass-sdk <command>` for init, validate, snippet, and
77
- doctor.
78
-
79
- Package-manager equivalents:
80
-
81
- ```bash
82
- npm exec --package @nexalink/carecompass-sdk -- carecompass init
83
- pnpm dlx @nexalink/carecompass-sdk init
84
- yarn dlx @nexalink/carecompass-sdk init
85
- bunx @nexalink/carecompass-sdk init
86
- ```
87
-
88
- You can also install it in a project and run the binary through your package
89
- manager:
90
-
91
- ```bash
92
- npm install @nexalink/carecompass-sdk
93
- npm exec carecompass -- init --payer-id acme-health --origin https://members.acme-health.com
94
- ```
95
-
96
- Or install it globally if your organization permits global npm tools:
97
-
98
- ```bash
99
- npm install -g @nexalink/carecompass-sdk
100
- carecompass init --payer-id acme-health --origin https://members.acme-health.com
101
- ```
102
-
103
- ## CLI Commands
104
-
105
- ### `init`
106
-
107
- Runs the complete first-time onboarding flow:
108
-
109
- - routes users without accounts to the configured signup path
110
- - validates the API key with Nexalink before continuing
111
- - stores the secret Nexalink API key locally
112
- - generates the SDK config, prompt starter, embed page, iframe, and setup guide
113
- with only public embed configuration
114
-
115
- Creates a `carecompass` folder with all generated SDK files in one place:
89
+ `init` validates your Nexalink API key, stores it locally, and generates:
116
90
 
117
91
  - `carecompass/carecompass.config.json`
118
92
  - `carecompass/system-prompt.md`
@@ -120,68 +94,58 @@ Creates a `carecompass` folder with all generated SDK files in one place:
120
94
  - `carecompass/carecompass-iframe.html`
121
95
  - `carecompass/README.md`
122
96
 
123
- Credentials are stored at `~/.nexalink/carecompass/credentials.json` by
124
- default. You can also set `CARECOMPASS_API_KEY` in your shell or CI environment.
125
- The generated config contains payer-facing configuration only. It does not
126
- contain the secret API key. The embed HTML and iframe are generated
127
- automatically during `init`; you do not need to run a separate snippet command
128
- for the first setup.
129
-
130
- For scripted setup, pass `--account-type developer`. The developer signup route
131
- can be configured with `--developer-signup-url` or
132
- `CARECOMPASS_DEVELOPER_SIGNUP_URL`. By default, that route is
133
- `https://www.nexalink.care/developer/signup`.
97
+ `npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package.
134
98
 
135
- By default, generated HTML is bundler-friendly and imports the package as
136
- `@nexalink/carecompass-sdk`, which works with Parcel, Vite, Next.js, and similar
137
- tooling when the package is installed as a dependency. For a raw browser HTML
138
- demo that is not processed by Parcel or another bundler, add
139
- `--snippet-mode cdn`.
99
+ ## How It Works
140
100
 
141
- ```bash
142
- npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
143
- npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com
101
+ ```text
102
+ Your Application
103
+ ↓
104
+ CareCompass SDK
105
+ ↓
106
+ Nexalink Hosted APIs
107
+ ↓
108
+ CareCompass AI Runtime
144
109
  ```
145
110
 
146
- ### `validate`
111
+ 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.
147
112
 
148
- Checks that the config shape is valid and that credentials are available.
149
- By default this also calls the hosted Nexalink config-validation endpoint, which
150
- confirms the API base URL, public embed key, payer ID, environment, and allowed
151
- origins are accepted by the server. The browser-side validation request uses
152
- public embed headers; it does not send the secret API key. Use `--local-only`
153
- for schema-only checks.
113
+ 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.
154
114
 
155
- ```bash
156
- npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
157
- npx @nexalink/carecompass-sdk validate --local-only --config carecompass/carecompass.config.json
158
- ```
115
+ ## Account, Credentials, and BAA Requirements
159
116
 
160
- ### `snippet`
117
+ 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.
161
118
 
162
- Regenerates the HTML embed snippet after config, branding, origin, or prompt changes. `init` already runs this once.
119
+ CareCompass uses two different keys:
163
120
 
164
- ```bash
165
- npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json
166
- npx @nexalink/carecompass-sdk snippet --snippet-mode cdn --config carecompass/carecompass.config.json
167
- ```
121
+ - **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.
122
+ - **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.
168
123
 
169
- ### `doctor`
124
+ 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.
170
125
 
171
- Prints a deployment readiness summary for the selected config.
126
+ ## React Usage
172
127
 
173
- ```bash
174
- npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
128
+ ```tsx
129
+ import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
130
+ import config from "./carecompass/carecompass.config.json";
131
+
132
+ export function MemberSupport() {
133
+ return <CareCompassEmbed config={config} />;
134
+ }
175
135
  ```
176
136
 
177
- ## Configuration
137
+ ## JavaScript Usage
178
138
 
179
- `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.
139
+ ```ts
140
+ import { mountCareCompass } from "@nexalink/carecompass-sdk";
141
+ import config from "./carecompass/carecompass.config.json";
142
+
143
+ mountCareCompass(document.getElementById("carecompass-root"), config);
144
+ ```
180
145
 
181
- The config is client-facing by design. It should contain the public `embedKey`,
182
- the payer ID, environment, allowed origins, branding, labels, theme, and prompt
183
- settings. Store the secret API key only in the local CLI credentials file or an
184
- approved server-side secret store.
146
+ ## Configuration Reference
147
+
148
+ `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.
185
149
 
186
150
  ```json
187
151
  {
@@ -221,33 +185,9 @@ approved server-side secret store.
221
185
  }
222
186
  ```
223
187
 
224
- ## Privacy-Safe Telemetry
225
-
226
- Telemetry is enabled automatically with Nexalink-managed defaults. Integrators
227
- do not need to run an additional CLI command, add a runtime config block, or
228
- manage a PostHog token. The CLI also sends anonymous onboarding funnel events
229
- using an ephemeral per-process session ID that is never persisted.
188
+ `carecompass/system-prompt.md` defines approved context before a member message reaches the AI runtime: plan terminology, support boundaries, escalation rules, and navigation context. The CLI resolves the prompt file into `carecompass/carecompass-embed.html`; the browser receives prompt text, not a local file path. Nexalink guardrails still validate prompt content.
230
189
 
231
- The SDK sends only allowlisted anonymous deployment-health events directly to
232
- PostHog's public ingestion API. It does not bundle `posthog-js`, enable session
233
- replay or autocapture, identify users, set cookies, or persist analytics state.
234
- Prompts, model responses, chat history, user context, PHI/PII, credentials, raw
235
- errors, and stack traces are never included. CLI arguments, terminal input, and
236
- file paths are also excluded.
237
-
238
- The SDK uses a Nexalink-owned public PostHog ingestion token. See
239
- [`TELEMETRY.md`](./TELEMETRY.md) for the shared web, React Native, and Flutter
240
- event contract.
241
-
242
- ## System Prompt File
243
-
244
- `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.
245
-
246
- 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.
247
-
248
- ## Iframe Placement
249
-
250
- `carecompass/carecompass-iframe.html` contains the iframe to place on the integrating page where the CareCompass LLM should appear.
190
+ `carecompass/carecompass-iframe.html` contains the iframe to place on the integrating page:
251
191
 
252
192
  ```html
253
193
  <iframe
@@ -258,212 +198,73 @@ The prompt file is resolved by the CLI when it generates `carecompass/carecompas
258
198
  ></iframe>
259
199
  ```
260
200
 
261
- 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.
262
-
263
- ## React Usage
264
-
265
- ```tsx
266
- import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
267
- import config from "./carecompass/carecompass.config.json";
201
+ Serve `carecompass/carecompass-embed.html` at the iframe `src`, often by copying the generated `carecompass` folder into public/static assets.
268
202
 
269
- export function MemberSupport() {
270
- return <CareCompassEmbed config={config} />;
271
- }
272
- ```
203
+ ## CLI Reference
273
204
 
274
- ## Vanilla JavaScript Usage
205
+ ### `init`
275
206
 
276
- ```ts
277
- import { mountCareCompass } from "@nexalink/carecompass-sdk";
278
- import config from "./carecompass/carecompass.config.json";
207
+ 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.
279
208
 
280
- mountCareCompass(document.getElementById("carecompass-root"), config);
281
- ```
209
+ 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`.
282
210
 
283
- ## Package Exports
211
+ 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`.
284
212
 
285
- ```ts
286
- import {
287
- CareCompassEmbed,
288
- mountCareCompass,
289
- validateCareCompassConfig,
290
- createCareCompassClient,
291
- } from "@nexalink/carecompass-sdk";
292
-
293
- import type {
294
- CareCompassConfig,
295
- CareCompassTheme,
296
- CareCompassLabels,
297
- CareCompassPromptConfig,
298
- } from "@nexalink/carecompass-sdk";
213
+ ```bash
214
+ npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
215
+ npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com
299
216
  ```
300
217
 
301
- ## Runtime Dependencies
302
-
303
- The package has a small runtime surface:
304
-
305
- - `zod` for shared config validation
306
- - `react` as a peer dependency for the embed component
307
- - `react-dom` as a peer dependency for mounting
218
+ ### `validate`
308
219
 
309
- Peer dependency range:
220
+ 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.
310
221
 
311
- ```json
312
- {
313
- "react": "^18.3.0 || ^19.0.0",
314
- "react-dom": "^18.3.0 || ^19.0.0"
315
- }
222
+ ```bash
223
+ npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
224
+ npx @nexalink/carecompass-sdk validate --local-only --config carecompass/carecompass.config.json
316
225
  ```
317
226
 
318
- The CLI requires Node.js 18 or newer.
319
-
320
- ## Development
227
+ ### `snippet`
321
228
 
322
- This repository uses Bun for local development.
229
+ Regenerates the HTML embed snippet after config, branding, origin, or prompt changes. `init` already runs this once.
323
230
 
324
231
  ```bash
325
- bun install
326
- bun run build
327
- bun run test
328
- bun run pack:dry-run
232
+ npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json
233
+ npx @nexalink/carecompass-sdk snippet --snippet-mode cdn --config carecompass/carecompass.config.json
329
234
  ```
330
235
 
331
- Do not publish a new package version unless the SDK version is intentionally
332
- changed and release approval is complete.
333
-
334
- ## What Runs In The Browser
335
-
336
- The browser receives only public embed configuration:
337
-
338
- - customer or payer ID
339
- - environment
340
- - public `embedKey`
341
- - branding and theme values
342
- - labels and support links
343
- - approved prompt settings
344
- - Nexalink-managed telemetry defaults compiled into the SDK
345
-
346
- The browser does not receive:
347
-
348
- - the secret SDK API key
349
- - SageMaker credentials
350
- - the AppSync signing role
351
- - private model endpoint details
352
- - Nexalink server-side allowlists
353
-
354
- Chat requests are sent to Nexalink-hosted CareCompass API routes. The component does not call the model endpoint directly.
355
-
356
- ## Hosted LLM Warm-Up
357
-
358
- Nexalink hosts the proprietary CareCompass LLM runtime behind Nexalink-managed
359
- API routes. To control infrastructure costs for early deployments, Nexalink may
360
- run some hosted model endpoints with scale-to-zero capacity. When an endpoint
361
- has scaled to zero, the first chat request after an idle period can take several
362
- minutes while cloud GPU capacity is allocated and the model endpoint warms up.
363
-
364
- This warm-up delay is expected for some MVP and development environments. It
365
- does not mean the browser embed needs a secret API key, and it does not mean the
366
- SDK is calling SageMaker directly. The request is queued through Nexalink-hosted
367
- APIs while the model endpoint starts. Nexalink is actively working on
368
- improvements to reduce or avoid first-request warm-up delays.
369
-
370
- ## Runtime Security Model
371
-
372
- The SDK component uses the public browser `embedKey`, payer ID, environment, and
373
- allowed origin metadata to call Nexalink-hosted embed API routes. The secret SDK
374
- API key is used only by trusted setup and server-side/CLI workflows and must
375
- never be placed in browser config or generated snippets.
376
-
377
- For staging and production, `apiBaseUrl` must be a Nexalink-hosted HTTPS URL.
378
- `localhost` API and origin values are accepted only for `development`
379
- configurations. Hosted validation still remains authoritative: Nexalink API
380
- routes must enforce payer ID, embed key, environment, allowed origin, prompt
381
- guardrails, rate limiting, request attribution, and tenant isolation for config,
382
- analytics, logs, prompts, and model requests.
383
-
384
- Generated snippets escape serialized config before embedding it in a module
385
- script. React renders chat messages and labels as text rather than raw HTML.
386
- Do not add `dangerouslySetInnerHTML`, raw HTML snippets, unreviewed third-party
387
- scripts, or payer-provided secret values to an embed page.
388
-
389
- ## API Keys And Usage Tracking
390
-
391
- SDK API keys are issued in the Nexalink portal and stored server-side as hashes.
392
- Each secret API key is associated with a customer or payer ID, environment,
393
- public embed key, and allowed origins. The API key authenticates trusted setup
394
- and management flows; the public embed key is what the browser uses for
395
- client-facing runtime requests.
396
-
397
- 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.
398
-
399
- ## Staging And Production
236
+ ### `doctor`
400
237
 
401
- Use separate keys and config files for staging and production.
238
+ Prints a deployment readiness summary for the selected config.
402
239
 
403
240
  ```bash
404
- npx @nexalink/carecompass-sdk validate --config carecompass.staging.json
405
- npx @nexalink/carecompass-sdk snippet --config carecompass.staging.json --output carecompass/staging-embed.html
406
- npx @nexalink/carecompass-sdk doctor --config carecompass.staging.json
241
+ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
407
242
  ```
408
243
 
409
- Before production, confirm:
410
-
411
- - production origin is allowlisted exactly
412
- - production `embedKey` is separate from staging
413
- - production `apiBaseUrl` points at the approved Nexalink-hosted environment
414
- - support links route to the payer's approved support surface
415
- - prompt instructions are approved by Nexalink and the payer
416
- - no secret API key appears in generated source code
417
- - diagnostics, logs, and analytics are configured to avoid raw PHI/PII, raw
418
- prompts, raw model responses, credentials, or privileged backend tokens unless
419
- Nexalink has approved a secure diagnostic path
420
-
421
- ## Troubleshooting
422
-
423
- `Missing Nexalink API key`
244
+ ## Security and Compliance Model
424
245
 
425
- Run `npx @nexalink/carecompass-sdk init`, choose Developer, and sign in with an
426
- API key. For non-interactive setup, pass `--account-type developer` with
427
- `--api-key <key>`, or set `CARECOMPASS_API_KEY` with
428
- `CARECOMPASS_ACCOUNT_TYPE=developer`.
246
+ 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.
429
247
 
430
- `zsh: command not found: carecompass`
248
+ 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`.
431
249
 
432
- You ran the SDK with `npx`, which does not install a permanent global command.
433
- Run the next command with `npx @nexalink/carecompass-sdk <command>`, install the
434
- package in your project, or install it globally.
250
+ 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.
435
251
 
436
- `@parcel/core: Failed to resolve 'https://esm.sh/...'`
252
+ 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.
437
253
 
438
- Regenerate the snippet with the default bundler mode instead of CDN mode:
439
- `npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json`.
440
- Parcel does not allow `https:` imports in HTML. CDN mode is only for raw browser
441
- HTML that is not bundled.
254
+ ## Runtime Notes
442
255
 
443
- `CareCompass could not reach http://localhost:3000`
256
+ 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.
444
257
 
445
- The browser cannot reach the configured API base URL. If the embed is running in
446
- a hosted sandbox, `localhost` points at the sandbox/browser environment, not the
447
- Nexalink server on your machine. Run the Nexalink web app locally and test from
448
- a local page, or point `apiBaseUrl` at a deployed Nexalink environment that has
449
- the CareCompass embed API routes deployed. Run `validate` to check this before
450
- typing into the embed.
451
-
452
- `Origin is not authorized`
453
-
454
- Add the exact website origin to the Nexalink portal SDK configuration.
455
-
456
- `Prompt configuration violates CareCompass guardrails`
457
-
458
- Remove unsafe or unsupported instructions and re-run validation.
459
-
460
- `CareCompass embed client is not authorized`
461
-
462
- Confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued in the Nexalink portal.
463
-
464
- `CareCompass AppSync inference service is not configured`
258
+ ## Troubleshooting
465
259
 
466
- 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.
260
+ - `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`.
261
+ - `zsh: command not found: carecompass`: `npx` does not install a permanent command. Run `npx @nexalink/carecompass-sdk <command>` or install the package.
262
+ - `@parcel/core: Failed to resolve 'https://esm.sh/...'`: regenerate with bundler mode: `npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json`. CDN mode is for raw browser HTML.
263
+ - `CareCompass could not reach http://localhost:3000`: hosted sandboxes cannot reach your machine's `localhost`. Test locally or use a deployed Nexalink `apiBaseUrl`. Run `validate` before typing into the embed.
264
+ - `Origin is not authorized`: add the exact website origin to the Nexalink portal SDK configuration.
265
+ - `Prompt configuration violates CareCompass guardrails`: remove unsafe or unsupported instructions and re-run validation.
266
+ - `CareCompass embed client is not authorized`: confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued in the Nexalink portal.
267
+ - `CareCompass AppSync inference service is not configured`: Nexalink server operators should confirm `NEXT_PUBLIC_API_URL` or `CARECOMPASS_APPSYNC_URL`. The embed does not require a payer-provided LLM URL.
467
268
 
468
269
  ## License
469
270
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nexalink/carecompass-sdk",
3
- "version": "0.2.0-beta.13",
3
+ "version": "0.2.0-beta.15",
4
4
  "description": "Embeddable CareCompass SDK and CLI for healthcare ecosystem integrations with Nexalink onboarding, BAA coverage, and API keys.",
5
5
  "type": "module",
6
6
  "packageManager": "bun@1.3.9",