@nexalink/carecompass-sdk 0.3.0-beta.15 → 0.4.0-beta.15

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { careCompassApiBaseUrlSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
@@ -32,13 +32,26 @@ planning, emergency triage, legal advice, and coverage guarantees. When a member
 needs clinical, emergency, plan-specific, or account-specific help that requires
 a human, route them to the customer's approved support resources.`;
 const CLI_COMMAND_ALLOWLIST = new Set([
+    "auth",
+    "completion",
+    "config",
+    "configure",
     "doctor",
+    "embed",
+    "health",
     "help",
     "init",
     "login",
+    "logout",
+    "query",
+    "setup",
     "snippet",
     "validate",
+    "version",
 ]);
+const UNAUTHENTICATED_AUTH_ATTEMPT_LIMIT = 2;
+const UNAUTHENTICATED_AUTH_RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+const UNAUTHENTICATED_AUTH_RATE_LIMIT_FILE = "auth-rate-limit.json";
 class CliTelemetryError extends Error {
     constructor(message, telemetry) {
         super(message);
@@ -47,6 +60,8 @@ class CliTelemetryError extends Error {
 }
 const sanitizeCommandName = (command) => {
     const normalized = command === "--help" || command === "-h" ? "help" : command;
+    if (command === "--version" || command === "-v")
+        return "version";
     return CLI_COMMAND_ALLOWLIST.has(normalized) ? normalized : "unknown_command";
 };
 const authTelemetryForSource = (source) => {
@@ -58,6 +73,96 @@ const authTelemetryForSource = (source) => {
     }
     return { authMethod: "api_key", keySource: "cli_flag" };
 };
+const unauthenticatedRateLimitPath = (io) => io.env.CARECOMPASS_AUTH_RATE_LIMIT_PATH ??
+    join(dirname(resolveCredentialsPath(io.env)), UNAUTHENTICATED_AUTH_RATE_LIMIT_FILE);
+const unauthenticatedRateLimitKey = (io) => {
+    const keyMaterial = io.env.CARECOMPASS_AUTH_RATE_LIMIT_KEY
+        ? `explicit:${io.env.CARECOMPASS_AUTH_RATE_LIMIT_KEY}`
+        : io.env.CARECOMPASS_CLIENT_IP
+            ? `ip:${io.env.CARECOMPASS_CLIENT_IP}`
+            : `credentials:${resolveCredentialsPath(io.env)}`;
+    return createHash("sha256")
+        .update("carecompass unauthenticated auth rate limit")
+        .update(keyMaterial)
+        .digest("hex");
+};
+const emptyUnauthenticatedAuthLedger = () => ({
+    version: 1,
+    entries: {},
+});
+const readUnauthenticatedAuthLedger = (path) => {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version !== 1 || typeof parsed.entries !== "object") {
+            return emptyUnauthenticatedAuthLedger();
+        }
+        const entries = {};
+        for (const [key, value] of Object.entries(parsed.entries)) {
+            if (typeof value === "object" &&
+                value !== null &&
+                typeof value.failures ===
+                    "number" &&
+                typeof value.firstAttemptAt ===
+                    "number" &&
+                typeof value.lastAttemptAt ===
+                    "number") {
+                entries[key] = value;
+            }
+        }
+        return { version: 1, entries };
+    }
+    catch {
+        return emptyUnauthenticatedAuthLedger();
+    }
+};
+const writeUnauthenticatedAuthLedger = (path, ledger) => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Some filesystems do not support chmod; the ledger contains only hashed
+        // limiter keys and counters.
+    }
+};
+const pruneUnauthenticatedAuthLedger = (ledger, now) => {
+    for (const [key, entry] of Object.entries(ledger.entries)) {
+        if (now - entry.firstAttemptAt >
+            UNAUTHENTICATED_AUTH_RATE_LIMIT_WINDOW_MS) {
+            delete ledger.entries[key];
+        }
+    }
+};
+const recordUnauthenticatedAuthFailure = (io) => {
+    const path = unauthenticatedRateLimitPath(io);
+    const key = unauthenticatedRateLimitKey(io);
+    const now = Date.now();
+    const ledger = readUnauthenticatedAuthLedger(path);
+    pruneUnauthenticatedAuthLedger(ledger, now);
+    const existing = ledger.entries[key];
+    const entry = existing &&
+        now - existing.firstAttemptAt <= UNAUTHENTICATED_AUTH_RATE_LIMIT_WINDOW_MS
+        ? existing
+        : { failures: 0, firstAttemptAt: now, lastAttemptAt: now };
+    entry.failures += 1;
+    entry.lastAttemptAt = now;
+    ledger.entries[key] = entry;
+    writeUnauthenticatedAuthLedger(path, ledger);
+    const failures = entry.failures;
+    if (failures < UNAUTHENTICATED_AUTH_ATTEMPT_LIMIT)
+        return null;
+    return new CliTelemetryError("Too many failed authentication attempts. Wait before trying again or verify the API key in the Nexalink console.", {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+        failureCategory: "rate_limit_error",
+    });
+};
+const resetUnauthenticatedAuthFailures = (io) => {
+    const path = unauthenticatedRateLimitPath(io);
+    const ledger = readUnauthenticatedAuthLedger(path);
+    delete ledger.entries[unauthenticatedRateLimitKey(io)];
+    writeUnauthenticatedAuthLedger(path, ledger);
+};
 const normalizeBaaStatus = (value) => {
     if (value === "signed" || value === "pending" || value === "not_required") {
         return value;
@@ -526,14 +631,11 @@ async function resolveInitApiKey(flags, io, apiBaseUrl, onAuthChecked = async ()
                 failureCategory: validation.failureCategory,
             });
             io.stdout.write(`${validation.message}\n`);
+            const rateLimitError = recordUnauthenticatedAuthFailure(io);
+            if (rateLimitError)
+                throw rateLimitError;
             continue;
         }
-        await onAuthChecked({
-            authResult: "success",
-            baaStatus: validation.baaStatus,
-            keySource: authTelemetry.keySource,
-            failureCategory: null,
-        });
         if (validation.accountType !== accountType) {
             if (validation.accountType === "enterprise") {
                 io.stdout.write(`This API key belongs to an enterprise account. ${enterpriseUnavailableMessage(urls.developer)}\n`);
@@ -543,12 +645,14 @@ async function resolveInitApiKey(flags, io, apiBaseUrl, onAuthChecked = async ()
             continue;
         }
         writeStoredApiKey(normalizedApiKey, credentialsPath);
+        resetUnauthenticatedAuthFailures(io);
         io.stdout.write(`Stored CareCompass credentials at ${credentialsPath}\n`);
         io.stdout.write("Sign-in successful.\n");
         return {
             apiKey: normalizedApiKey,
             authMethod: authTelemetry.authMethod,
             baaStatus: validation.baaStatus,
+            keySource: authTelemetry.keySource,
             setup: validation.setup,
         };
     }
@@ -790,12 +894,14 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
     const sessionStartedAt = Date.now();
     const rawCommand = argv[0] ?? "help";
     const telemetryCommandName = sanitizeCommandName(rawCommand);
-    const commandStartedAt = Date.now();
+    let commandStartedAt = sessionStartedAt;
+    let commandStartedCaptured = false;
     let commandsAttempted = 0;
     let commandsSucceeded = 0;
     let commandsFailed = 0;
     let activeCommand = rawCommand;
     let authCheckedCaptured = false;
+    let initStartedCaptured = false;
     let sessionEndedCaptured = false;
     const captureAuthChecked = async (telemetry) => {
         if (authCheckedCaptured)
@@ -811,7 +917,19 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
             keySource: telemetry.keySource,
         });
     };
+    const captureCommandStarted = async () => {
+        if (commandStartedCaptured)
+            return;
+        commandStartedCaptured = true;
+        commandStartedAt = Date.now();
+        commandsAttempted += 1;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_STARTED, {
+            commandName: telemetryCommandName,
+            commandArgsCount: Math.max(argv.length - 1, 0),
+        });
+    };
     const captureCommandCompleted = async () => {
+        await captureCommandStarted();
         commandsSucceeded += 1;
         await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_COMPLETED, {
             commandName: telemetryCommandName,
@@ -820,6 +938,34 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
             modelId: null,
         });
     };
+    const authenticateConfigCommand = async (flags) => {
+        let credentials;
+        try {
+            credentials = requireApiKey(flags, io);
+        }
+        catch (error) {
+            const failure = classifyCliFailure(error);
+            await captureAuthChecked({
+                authResult: "failure",
+                baaStatus: "signed",
+                keySource: "cli_flag",
+                errorCode: failure.errorCode,
+                failureCategory: failure.failureCategory,
+            });
+            const rateLimitError = recordUnauthenticatedAuthFailure(io);
+            throw rateLimitError ?? error;
+        }
+        const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
+        resetUnauthenticatedAuthFailures(io);
+        cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+        await captureAuthChecked({
+            authResult: "success",
+            baaStatus: "not_required",
+            keySource: authTelemetryForSource(credentials.source).keySource,
+            failureCategory: null,
+        });
+        return { config, credentials };
+    };
     const captureSessionEnded = async (exitReason) => {
         if (sessionEndedCaptured)
             return;
@@ -833,11 +979,6 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
         });
     };
     await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_STARTED);
-    await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_STARTED, {
-        commandName: telemetryCommandName,
-        commandArgsCount: Math.max(argv.length - 1, 0),
-    });
-    commandsAttempted += 1;
     try {
         const { command, flags, positionals } = parseArgs(argv);
         activeCommand = command;
@@ -847,6 +988,7 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
             return 0;
         }
         if (command === "login") {
+            await captureCommandStarted();
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_LOGIN_STARTED);
             const apiKey = flagString(flags, "api-key") ?? positionals[0];
             if (!apiKey) {
@@ -867,12 +1009,22 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
             return 0;
         }
         if (command === "init") {
-            const initStartedAt = Date.now();
-            await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_STARTED);
             rejectLegacyBaaInitFlags(flags, io);
             const outputDir = flagString(flags, "output-dir") ?? DEFAULT_OUTPUT_DIR;
             const apiBaseUrl = resolveTrustedApiBaseUrl(flagString(flags, "api-base-url") ?? DEFAULT_API_BASE_URL);
             const initAuth = await resolveInitApiKey(flags, io, apiBaseUrl, captureAuthChecked);
+            const config = buildInitConfig(flags, initAuth.setup);
+            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+            await captureAuthChecked({
+                authResult: "success",
+                baaStatus: initAuth.baaStatus,
+                keySource: initAuth.keySource,
+                failureCategory: null,
+            });
+            await captureCommandStarted();
+            const initStartedAt = Date.now();
+            await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_STARTED);
+            initStartedCaptured = true;
             const output = flagString(flags, "output") ??
                 join(outputDir, "carecompass.config.json");
             const snippetOutput = flagString(flags, "snippet-output") ??
@@ -895,8 +1047,6 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
                 }
             }
             mkdirSync(outputDir, { recursive: true });
-            const config = buildInitConfig(flags, initAuth.setup);
-            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
             writeFileSync(output, `${JSON.stringify(config, null, 2)}\n`);
             writeFileSync(promptOutput, `${DEFAULT_SYSTEM_PROMPT}\n`);
             const resolvedConfig = readConfig(output);
@@ -946,9 +1096,8 @@ Next command:
         }
         if (command === "validate") {
             try {
-                const credentials = requireApiKey(flags, io);
-                const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
-                cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+                const { config, credentials } = await authenticateConfigCommand(flags);
+                await captureCommandStarted();
                 if (flags["local-only"] !== true) {
                     await assertHostedConfig(config, credentials.apiKey);
                 }
@@ -959,17 +1108,18 @@ Next command:
             }
             catch (error) {
                 const failure = classifyCliFailure(error);
-                await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_FAILED, {
-                    errorCode: failure.errorCode,
-                    failureCategory: failure.failureCategory,
-                });
+                if (commandStartedCaptured) {
+                    await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_FAILED, {
+                        errorCode: failure.errorCode,
+                        failureCategory: failure.failureCategory,
+                    });
+                }
                 throw error;
             }
         }
         if (command === "snippet") {
-            requireApiKey(flags, io);
-            const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
-            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+            const { config } = await authenticateConfigCommand(flags);
+            await captureCommandStarted();
             const snippet = generateCareCompassSnippet(runtimeConfig(config), {
                 mode: snippetMode(flags),
             });
@@ -987,9 +1137,8 @@ Next command:
             return 0;
         }
         if (command === "doctor") {
-            const credentials = requireApiKey(flags, io);
-            const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
-            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+            const { config, credentials } = await authenticateConfigCommand(flags);
+            await captureCommandStarted();
             let hostedStatus = "not checked";
             try {
                 await assertHostedConfig(config, credentials.apiKey);
@@ -1013,12 +1162,16 @@ Status: ready for staging verification
             await captureCommandCompleted();
             return 0;
         }
+        await captureCommandStarted();
         throw new Error(`Unknown command: ${command}`);
     }
     catch (error) {
         commandsFailed += 1;
+        if (!commandStartedCaptured && commandsAttempted === 0) {
+            commandsAttempted = 1;
+        }
         const failure = classifyCliFailure(error);
-        if (activeCommand === "init") {
+        if (activeCommand === "init" && initStartedCaptured) {
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_FAILED, {
                 errorCode: failure.errorCode,
                 failureCategory: failure.failureCategory,

package/dist/component.d.ts

@@ -1,5 +1,13 @@
+import React from "react";
+import { type CareCompassContext, type CareCompassCoreEvent, type CareCompassMessage } from "./core.js";
 import type { CareCompassConfig } from "./schema.js";
-export declare function CareCompassEmbed({ config, pollIntervalMs, }: {
+export type CareCompassChatProps = {
     config: CareCompassConfig;
+    initialContext?: CareCompassContext;
+    onEvent?: (event: CareCompassCoreEvent) => void;
     pollIntervalMs?: number;
-}): import("react/jsx-runtime").JSX.Element;
+    renderMessage?: (message: CareCompassMessage) => React.ReactNode;
+    retryLabel?: string;
+};
+export declare function CareCompassChat({ config, initialContext, onEvent, pollIntervalMs, renderMessage, retryLabel, }: CareCompassChatProps): import("react/jsx-runtime").JSX.Element;
+export declare const CareCompassEmbed: typeof CareCompassChat;

package/dist/component.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
-import { createCareCompassClient } from "./client.js";
+import { createCareCompassCore, } from "./core.js";
+import { CareCompassMarkdown } from "./markdown.js";
 import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassTelemetry, } from "./telemetry.js";
 // The embed should fail closed inside the host page: show the configured
 // fallback text, capture sanitized telemetry, and avoid crashing the integrator.
@@ -25,71 +26,56 @@ class CareCompassErrorBoundary extends React.Component {
         return this.props.children;
     }
 }
-function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, }) {
-    const client = React.useMemo(() => createCareCompassClient(config), [config]);
-    const [messages, setMessages] = React.useState([
-        {
-            id: "welcome",
-            role: "assistant",
-            text: config.prompt.welcomeMessage,
-        },
-    ]);
+function CareCompassChatContent({ config, initialContext, onEvent, telemetry, pollIntervalMs = 1500, renderMessage, retryLabel = "Retry", }) {
+    const core = React.useMemo(() => createCareCompassCore(config, {
+        initialContext,
+        pollIntervalMs,
+    }), [config, initialContext, pollIntervalMs]);
+    const [snapshot, setSnapshot] = React.useState(() => core.getSnapshot());
     const [input, setInput] = React.useState("");
-    const [loading, setLoading] = React.useState(false);
-    const [error, setError] = React.useState(null);
     React.useEffect(() => {
         telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_RENDERED);
         telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_OPENED);
+        const unsubscribe = core.subscribe(setSnapshot);
+        setSnapshot(core.getSnapshot());
         return () => {
+            unsubscribe();
+            core.dispose();
             telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_CLOSED);
         };
-    }, [telemetry]);
+    }, [core, telemetry]);
     async function sendMessage(event) {
         event.preventDefault();
         const prompt = input.trim();
-        if (!prompt || loading)
+        if (!prompt || snapshot.loading)
             return;
         setInput("");
-        setError(null);
-        setLoading(true);
-        setMessages((current) => [
-            ...current,
-            { id: `user-${Date.now()}`, role: "user", text: prompt },
-        ]);
         try {
-            const { jobId } = await client.ask({ prompt });
-            const startedAt = Date.now();
-            // The backend returns a job immediately, so the component polls until it
-            // sees a terminal state or reaches the same timeout tracked by telemetry.
-            while (Date.now() - startedAt < 120_000) {
-                const status = await client.status(jobId);
-                if (status.status === "complete" && status.result) {
-                    setMessages((current) => [
-                        ...current,
-                        {
-                            id: `assistant-${Date.now()}`,
-                            role: "assistant",
-                            text: status.result ?? "",
-                        },
-                    ]);
-                    return;
-                }
-                if (status.status === "failed") {
-                    throw new Error(status.result ?? config.labels.errorMessage);
-                }
-                await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            for await (const coreEvent of core.streamMessage(prompt)) {
+                onEvent?.(coreEvent);
             }
-            client.recordInferenceTimeout(jobId, Date.now() - startedAt);
-            throw new Error("CareCompass request timed out.");
         }
-        catch (err) {
-            setError(err?.message ??
-                config.labels.errorMessage);
+        catch {
+            // The core snapshot already carries the user-visible error and retry
+            // state. Swallow here so host pages do not see unhandled form errors.
         }
-        finally {
-            setLoading(false);
+    }
+    async function retryMessage() {
+        try {
+            await core.retryLast();
+        }
+        catch {
+            // The core owns the visible retry failure state.
         }
     }
+    const messageContent = (message) => {
+        if (renderMessage)
+            return renderMessage(message);
+        if (message.role === "assistant") {
+            return _jsx(CareCompassMarkdown, { text: message.text });
+        }
+        return message.text;
+    };
     return (_jsxs("section", { "aria-label": config.labels.title, style: {
             "--carecompass-primary": config.theme.primaryColor,
             "--carecompass-bg": config.theme.backgroundColor,
@@ -118,7 +104,7 @@ function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, })
                     gap: 12,
                     overflowY: "auto",
                     padding: 16,
-                }, children: [messages.map((message) => (_jsx("div", { style: {
+                }, children: [snapshot.messages.map((message) => (_jsx("div", { style: {
                             alignSelf: message.role === "user" ? "flex-end" : "flex-start",
                             background: message.role === "user"
                                 ? "var(--carecompass-primary)"
@@ -127,14 +113,14 @@ function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, })
                             color: message.role === "user" ? "#ffffff" : "inherit",
                             maxInlineSize: "82%",
                             padding: "10px 12px",
-                            whiteSpace: "pre-wrap",
-                        }, children: message.text }, message.id))), loading ? (_jsx("div", { style: { fontSize: 13, opacity: 0.72 }, children: "Thinking..." })) : null] }), _jsxs("form", { onSubmit: sendMessage, style: {
+                            whiteSpace: message.role === "user" ? "pre-wrap" : "normal",
+                        }, children: messageContent(message) }, message.id))), snapshot.loading ? (_jsx("div", { style: { fontSize: 13, opacity: 0.72 }, children: "Thinking..." })) : null] }), _jsxs("form", { onSubmit: sendMessage, style: {
                     borderTop: "1px solid color-mix(in srgb, var(--carecompass-text) 12%, transparent)",
                     display: "flex",
                     flexDirection: "column",
                     gap: 8,
                     padding: 12,
-                }, children: [_jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsx("input", { "aria-label": config.labels.placeholder, disabled: loading, onChange: (event) => setInput(event.currentTarget.value), placeholder: config.labels.placeholder, style: {
+                }, children: [_jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsx("input", { "aria-label": config.labels.placeholder, disabled: snapshot.loading, onChange: (event) => setInput(event.currentTarget.value), placeholder: config.labels.placeholder, style: {
                                     border: "1px solid color-mix(in srgb, var(--carecompass-text) 16%, transparent)",
                                     borderRadius: 8,
                                     color: "inherit",
@@ -142,20 +128,36 @@ function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, })
                                     font: "inherit",
                                     minInlineSize: 0,
                                     padding: "10px 12px",
-                                }, value: input }), _jsx("button", { disabled: loading || !input.trim(), style: {
+                                }, value: input }), _jsx("button", { disabled: snapshot.loading || !input.trim(), style: {
                                     background: "var(--carecompass-primary)",
                                     border: 0,
                                     borderRadius: 8,
                                     color: "#ffffff",
-                                    cursor: loading ? "not-allowed" : "pointer",
+                                    cursor: snapshot.loading ? "not-allowed" : "pointer",
                                     font: "inherit",
                                     fontWeight: 700,
                                     padding: "0 14px",
-                                }, type: "submit", children: config.labels.sendButton })] }), error ? (_jsx("div", { role: "alert", style: { color: "#b91c1c", fontSize: 12 }, children: error })) : null, _jsx("div", { style: { fontSize: 11, opacity: 0.7 }, children: config.labels.disclaimer })] })] }));
+                                }, type: "submit", children: config.labels.sendButton })] }), snapshot.error ? (_jsxs("div", { role: "alert", style: {
+                            alignItems: "center",
+                            color: "#b91c1c",
+                            display: "flex",
+                            flexWrap: "wrap",
+                            fontSize: 12,
+                            gap: 8,
+                        }, children: [_jsx("span", { children: snapshot.error.message }), snapshot.canRetry ? (_jsx("button", { onClick: retryMessage, style: {
+                                    background: "transparent",
+                                    border: "1px solid color-mix(in srgb, #b91c1c 40%, transparent)",
+                                    borderRadius: 6,
+                                    color: "#b91c1c",
+                                    cursor: "pointer",
+                                    font: "inherit",
+                                    padding: "4px 8px",
+                                }, type: "button", children: retryLabel })) : null] })) : null, _jsx("div", { style: { fontSize: 11, opacity: 0.7 }, children: config.labels.disclaimer })] })] }));
 }
-export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
+export function CareCompassChat({ config, initialContext, onEvent, pollIntervalMs = 1500, renderMessage, retryLabel, }) {
     // Telemetry is scoped to the validated public config; no per-message content
     // is passed through this component-level telemetry object.
     const telemetry = React.useMemo(() => createCareCompassTelemetry(config), [config]);
-    return (_jsx(CareCompassErrorBoundary, { config: config, telemetry: telemetry, children: _jsx(CareCompassEmbedContent, { config: config, pollIntervalMs: pollIntervalMs, telemetry: telemetry }) }));
+    return (_jsx(CareCompassErrorBoundary, { config: config, telemetry: telemetry, children: _jsx(CareCompassChatContent, { config: config, initialContext: initialContext, onEvent: onEvent, pollIntervalMs: pollIntervalMs, renderMessage: renderMessage, retryLabel: retryLabel, telemetry: telemetry }) }));
 }
+export const CareCompassEmbed = CareCompassChat;

package/dist/core.d.ts

@@ -0,0 +1,78 @@
+import { type CareCompassStatusResponse } from "./client.js";
+import type { CareCompassConfig } from "./schema.js";
+type Fetcher = typeof fetch;
+export type CareCompassContext = Record<string, unknown>;
+export type CareCompassMessage = {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    createdAt: number;
+    status: "complete" | "failed" | "pending";
+};
+export type CareCompassLifecyclePhase = "idle" | "submitting" | "streaming" | "complete" | "error" | "disposed";
+export type CareCompassCoreErrorCode = "request_failed" | "timeout" | "disposed";
+export type CareCompassCoreError = {
+    code: CareCompassCoreErrorCode;
+    message: string;
+};
+export type CareCompassRetryMetadata = {
+    prompt: string;
+    context: CareCompassContext;
+    attempts: number;
+};
+export type CareCompassCoreSnapshot = {
+    messages: CareCompassMessage[];
+    phase: CareCompassLifecyclePhase;
+    loading: boolean;
+    error: CareCompassCoreError | null;
+    context: CareCompassContext;
+    canRetry: boolean;
+    retry: CareCompassRetryMetadata | null;
+    activeJobId: string | null;
+};
+export type CareCompassCoreEvent = {
+    type: "message_submitted";
+    message: CareCompassMessage;
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "status";
+    jobId: string;
+    status: CareCompassStatusResponse["status"];
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "message_completed";
+    message: CareCompassMessage;
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "error";
+    error: CareCompassCoreError;
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "context_updated";
+    snapshot: CareCompassCoreSnapshot;
+} | {
+    type: "reset";
+    snapshot: CareCompassCoreSnapshot;
+};
+export type CareCompassCoreOptions = {
+    fetcher?: Fetcher;
+    initialContext?: CareCompassContext;
+    now?: () => number;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+};
+export type CareCompassSendMessageOptions = {
+    context?: CareCompassContext;
+};
+export type CareCompassCore = {
+    getSnapshot: () => CareCompassCoreSnapshot;
+    subscribe: (listener: (snapshot: CareCompassCoreSnapshot) => void) => () => void;
+    setContext: (context: CareCompassContext | ((current: CareCompassContext) => CareCompassContext)) => void;
+    sendMessage: (prompt: string, options?: CareCompassSendMessageOptions) => Promise<CareCompassCoreSnapshot>;
+    streamMessage: (prompt: string, options?: CareCompassSendMessageOptions) => AsyncIterable<CareCompassCoreEvent>;
+    retryLast: () => Promise<CareCompassCoreSnapshot>;
+    reset: () => void;
+    dispose: () => void;
+};
+export declare function createCareCompassCore(config: CareCompassConfig, options?: CareCompassCoreOptions): CareCompassCore;
+export {};