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

package/dist/telemetry.js

@@ -1,3 +1,4 @@
+import { careCompassApiBaseUrlSchema, } from "./schema.js";
 import { CARECOMPASS_COMPONENT_VERSION, CARECOMPASS_SDK_VERSION, CARECOMPASS_TELEMETRY_CONTRACT_VERSION, } from "./version.js";
 export const CARECOMPASS_TELEMETRY_EVENTS = {
     SDK_INITIALIZED: "carecompass_sdk_initialized",
@@ -62,39 +63,71 @@ export const CARECOMPASS_TELEMETRY_ERROR_CODES = {
     CLI_COMMAND_UNKNOWN: "CLI_COMMAND_UNKNOWN",
     UNKNOWN_ERROR: "UNKNOWN_ERROR",
 };
-const DEPLOYMENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$/;
-const POSTHOG_PROJECT_TOKEN_RE = /^phc_[A-Za-z0-9_-]{8,}$/;
-const POSTHOG_HOSTNAMES = new Set(["us.i.posthog.com", "eu.i.posthog.com"]);
-const CARECOMPASS_DEFAULT_POSTHOG_API_HOST = "https://us.i.posthog.com";
-const CARECOMPASS_DEFAULT_POSTHOG_PROJECT_TOKEN = "phc_vYl3rpIu6Iz5vCeJUG62BBA3nlPCeF4RSYpCb8FjnOl";
+const CARECOMPASS_DEFAULT_API_BASE_URL = "https://www.nexalink.care";
+const CARECOMPASS_TELEMETRY_PATH = "/api/carecompass/telemetry";
 const TELEMETRY_CAPTURE_TIMEOUT_MS = 1_000;
+const TELEMETRY_EVENTS = new Set(Object.values(CARECOMPASS_TELEMETRY_EVENTS));
+const TELEMETRY_ERROR_CODES = new Set(Object.values(CARECOMPASS_TELEMETRY_ERROR_CODES));
+const FAILURE_CATEGORIES = new Set([
+    "authentication",
+    "auth_error",
+    "baa_not_signed",
+    "configuration",
+    "config_error",
+    "inference",
+    "model_error",
+    "network",
+    "network_error",
+    "permission_error",
+    "rate_limit",
+    "rate_limit_error",
+    "rendering",
+    "timeout",
+    "unknown",
+]);
+const AUTH_METHODS = new Set(["api_key", "env_var", "config_file"]);
+const BAA_STATUSES = new Set(["signed", "pending", "not_required"]);
+const COMMAND_NAMES = new Set([
+    "auth",
+    "completion",
+    "config",
+    "configure",
+    "doctor",
+    "embed",
+    "health",
+    "help",
+    "init",
+    "login",
+    "logout",
+    "query",
+    "setup",
+    "snippet",
+    "unknown_command",
+    "validate",
+    "version",
+]);
+const EXIT_REASONS = new Set([
+    "user_exit",
+    "error",
+    "timeout",
+    "signal",
+]);
+const AUTH_RESULTS = new Set(["success", "failure"]);
+const KEY_SOURCES = new Set(["env_var", "config_file", "cli_flag"]);
 const disabledTelemetry = {
     enabled: false,
     capture: () => undefined,
     captureAsync: async () => undefined,
 };
-const approvedApiHost = (value, environment) => {
-    // Telemetry is restricted to known PostHog ingestion hosts; localhost is only
-    // accepted in development so tests and local captures can be isolated.
-    if (typeof value !== "string")
+const approvedRelayBaseUrl = (value, environment) => {
+    const parsed = careCompassApiBaseUrlSchema.safeParse(value);
+    if (!parsed.success)
         return null;
-    try {
-        const url = new URL(value);
-        if (url.pathname !== "/" || url.search || url.hash)
-            return null;
-        const isLocalhost = url.hostname === "localhost" ||
-            url.hostname === "127.0.0.1" ||
-            url.hostname === "[::1]";
-        if (isLocalhost) {
-            return environment === "development" ? value.replace(/\/+$/, "") : null;
-        }
-        return url.protocol === "https:" && POSTHOG_HOSTNAMES.has(url.hostname)
-            ? value.replace(/\/+$/, "")
-            : null;
-    }
-    catch {
-        return null;
-    }
+    const url = new URL(parsed.data);
+    const isLocalhost = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "[::1]";
+    return isLocalhost && environment !== "development" ? null : parsed.data;
 };
 export const careCompassTelemetryDurationBucket = (durationMs) => {
     if (durationMs < 250)
@@ -107,117 +140,102 @@ export const careCompassTelemetryDurationBucket = (durationMs) => {
         return "5_to_29_999_ms";
     return "30_s_or_more";
 };
-const integerMs = (value) => Math.max(0, Math.round(value));
-const integerCount = (value) => Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+const integerMs = (value) => typeof value === "number" && Number.isFinite(value)
+    ? Math.max(0, Math.round(value))
+    : undefined;
+const integerCount = (value) => typeof value === "number" && Number.isFinite(value)
+    ? Math.max(0, Math.trunc(value))
+    : undefined;
+const allowedValue = (value, values) => typeof value === "string" && values.has(value) ? value : undefined;
+const allowedEnvironment = (value) => value === "development" || value === "staging" || value === "production"
+    ? value
+    : "unknown";
 function createTelemetry(context, options = {}) {
-    const projectToken = CARECOMPASS_DEFAULT_POSTHOG_PROJECT_TOKEN;
-    // Invalid identifiers disable telemetry instead of producing malformed events
-    // or sending data under an ambiguous deployment identity.
-    if (!DEPLOYMENT_ID_RE.test(context.deploymentId) ||
-        !DEPLOYMENT_ID_RE.test(context.distinctId) ||
-        !POSTHOG_PROJECT_TOKEN_RE.test(projectToken)) {
-        return disabledTelemetry;
-    }
     const fetcher = options.fetcher ?? fetch;
     const now = options.now ?? (() => new Date());
-    const apiHost = approvedApiHost(CARECOMPASS_DEFAULT_POSTHOG_API_HOST, context.environment);
-    if (!apiHost)
+    const relayBaseUrl = approvedRelayBaseUrl(context.apiBaseUrl, context.environment);
+    if (!relayBaseUrl)
         return disabledTelemetry;
     const captureAsync = async (event, captureOptions = {}) => {
+        if (!TELEMETRY_EVENTS.has(event))
+            return;
         const eventTimestamp = now().toISOString();
+        const durationMs = integerMs(captureOptions.durationMs);
+        const failureCategory = captureOptions.failureCategory === null
+            ? null
+            : allowedValue(captureOptions.failureCategory, FAILURE_CATEGORIES);
+        const errorCode = allowedValue(captureOptions.errorCode, TELEMETRY_ERROR_CODES);
+        const initDurationMs = integerMs(captureOptions.initDurationMs);
+        const authMethod = allowedValue(captureOptions.authMethod, AUTH_METHODS);
+        const baaStatus = allowedValue(captureOptions.baaStatus, BAA_STATUSES);
+        const commandName = allowedValue(captureOptions.commandName, COMMAND_NAMES);
+        const commandArgsCount = integerCount(captureOptions.commandArgsCount);
+        const commandDurationMs = integerMs(captureOptions.commandDurationMs);
+        const tokensUsed = captureOptions.tokensUsed === null
+            ? null
+            : integerCount(captureOptions.tokensUsed);
+        const sessionDurationMs = integerMs(captureOptions.sessionDurationMs);
+        const commandsAttempted = integerCount(captureOptions.commandsAttempted);
+        const commandsSucceeded = integerCount(captureOptions.commandsSucceeded);
+        const commandsFailed = integerCount(captureOptions.commandsFailed);
+        const exitReason = allowedValue(captureOptions.exitReason, EXIT_REASONS);
+        const authResult = allowedValue(captureOptions.authResult, AUTH_RESULTS);
+        const keySource = allowedValue(captureOptions.keySource, KEY_SOURCES);
         // Properties are allowlisted here by design. Do not add prompts, responses,
-        // user context, credentials, or raw exception messages to this payload.
+        // user context, credentials, raw exception messages, or stable identifiers.
         const properties = {
             $process_person_profile: false,
             contract_version: CARECOMPASS_TELEMETRY_CONTRACT_VERSION,
             sdk_version: CARECOMPASS_SDK_VERSION,
             component_version: CARECOMPASS_COMPONENT_VERSION,
             platform: context.platform,
-            environment: context.environment,
-            payer_id: context.payerId,
-            deployment_id: context.deploymentId,
+            environment: allowedEnvironment(context.environment),
             event_timestamp: eventTimestamp,
-            ...(context.cliSessionId ? { cli_session_id: context.cliSessionId } : {}),
-            ...(captureOptions.durationMs === undefined
+            ...(durationMs === undefined
                 ? {}
                 : {
-                    duration_bucket: careCompassTelemetryDurationBucket(captureOptions.durationMs),
+                    duration_bucket: careCompassTelemetryDurationBucket(durationMs),
                 }),
-            ...(captureOptions.failureCategory === undefined
+            ...(failureCategory === undefined
                 ? {}
-                : { failure_category: captureOptions.failureCategory }),
-            ...(captureOptions.errorCode
-                ? { error_code: captureOptions.errorCode }
-                : {}),
-            ...(captureOptions.initDurationMs === undefined
+                : { failure_category: failureCategory }),
+            ...(errorCode ? { error_code: errorCode } : {}),
+            ...(initDurationMs === undefined
                 ? {}
-                : { init_duration_ms: integerMs(captureOptions.initDurationMs) }),
-            ...(captureOptions.authMethod
-                ? { auth_method: captureOptions.authMethod }
-                : {}),
-            ...(captureOptions.baaStatus
-                ? { baa_status: captureOptions.baaStatus }
-                : {}),
-            ...(captureOptions.commandName
-                ? { command_name: captureOptions.commandName }
-                : {}),
-            ...(captureOptions.commandArgsCount === undefined
+                : { init_duration_ms: initDurationMs }),
+            ...(authMethod ? { auth_method: authMethod } : {}),
+            ...(baaStatus ? { baa_status: baaStatus } : {}),
+            ...(commandName ? { command_name: commandName } : {}),
+            ...(commandArgsCount === undefined
                 ? {}
-                : {
-                    command_args_count: integerCount(captureOptions.commandArgsCount),
-                }),
-            ...(captureOptions.commandDurationMs === undefined
+                : { command_args_count: commandArgsCount }),
+            ...(commandDurationMs === undefined
                 ? {}
-                : {
-                    command_duration_ms: integerMs(captureOptions.commandDurationMs),
-                }),
-            ...(captureOptions.tokensUsed === undefined
+                : { command_duration_ms: commandDurationMs }),
+            ...(tokensUsed === undefined ? {} : { tokens_used: tokensUsed }),
+            ...(sessionDurationMs === undefined
                 ? {}
-                : {
-                    tokens_used: captureOptions.tokensUsed === null
-                        ? null
-                        : integerCount(captureOptions.tokensUsed),
-                }),
-            ...(captureOptions.modelId === undefined
+                : { session_duration_ms: sessionDurationMs }),
+            ...(commandsAttempted === undefined
                 ? {}
-                : { model_id: captureOptions.modelId }),
-            ...(captureOptions.sessionDurationMs === undefined
+                : { commands_attempted: commandsAttempted }),
+            ...(commandsSucceeded === undefined
                 ? {}
-                : {
-                    session_duration_ms: integerMs(captureOptions.sessionDurationMs),
-                }),
-            ...(captureOptions.commandsAttempted === undefined
-                ? {}
-                : {
-                    commands_attempted: integerCount(captureOptions.commandsAttempted),
-                }),
-            ...(captureOptions.commandsSucceeded === undefined
-                ? {}
-                : {
-                    commands_succeeded: integerCount(captureOptions.commandsSucceeded),
-                }),
-            ...(captureOptions.commandsFailed === undefined
+                : { commands_succeeded: commandsSucceeded }),
+            ...(commandsFailed === undefined
                 ? {}
-                : { commands_failed: integerCount(captureOptions.commandsFailed) }),
-            ...(captureOptions.exitReason
-                ? { exit_reason: captureOptions.exitReason }
-                : {}),
-            ...(captureOptions.authResult
-                ? { auth_result: captureOptions.authResult }
-                : {}),
-            ...(captureOptions.keySource
-                ? { key_source: captureOptions.keySource }
-                : {}),
+                : { commands_failed: commandsFailed }),
+            ...(exitReason ? { exit_reason: exitReason } : {}),
+            ...(authResult ? { auth_result: authResult } : {}),
+            ...(keySource ? { key_source: keySource } : {}),
         };
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), TELEMETRY_CAPTURE_TIMEOUT_MS);
         try {
-            await fetcher(`${apiHost}/i/v0/e/`, {
+            await fetcher(`${relayBaseUrl}${CARECOMPASS_TELEMETRY_PATH}`, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({
-                    api_key: projectToken,
-                    distinct_id: context.distinctId,
                     event,
                     properties,
                     timestamp: eventTimestamp,
@@ -239,24 +257,19 @@ function createTelemetry(context, options = {}) {
     };
 }
 export function createCareCompassTelemetry(config, options = {}) {
-    const deploymentId = `${config.payerId}-${config.environment}-web`;
     return createTelemetry({
-        deploymentId,
-        distinctId: deploymentId,
+        apiBaseUrl: config.apiBaseUrl,
         environment: config.environment,
-        payerId: config.payerId,
         platform: "web",
     }, options);
 }
 export function createCareCompassCliTelemetry(sessionId, context = {}, options = {}) {
+    // Keep the public signature stable, but session IDs must never reach telemetry.
+    void sessionId;
     const environment = context.environment ?? "unknown";
-    const payerId = context.payerId ?? "anonymous";
     return createTelemetry({
-        cliSessionId: sessionId,
-        deploymentId: `${payerId}-${environment}-cli`,
-        distinctId: sessionId,
+        apiBaseUrl: context.apiBaseUrl ?? CARECOMPASS_DEFAULT_API_BASE_URL,
         environment,
-        payerId,
         platform: "cli",
     }, options);
 }

package/dist/ui.d.ts

@@ -1,3 +1,3 @@
-export { CareCompassChat, CareCompassEmbed } from "./component.js";
-export type { CareCompassChatProps } from "./component.js";
+export { CareCompassChat, CareCompassEmbed, useCareCompass, } from "./component.js";
+export type { CareCompassChatProps, CareCompassReactController, UseCareCompassOptions, } from "./component.js";
 export { mountCareCompass } from "./mount.js";

package/dist/ui.js

@@ -1,2 +1,2 @@
-export { CareCompassChat, CareCompassEmbed } from "./component.js";
+export { CareCompassChat, CareCompassEmbed, useCareCompass, } from "./component.js";
 export { mountCareCompass } from "./mount.js";

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const CARECOMPASS_SDK_VERSION: string;
 export declare const CARECOMPASS_COMPONENT_VERSION = "1.0.0";
-export declare const CARECOMPASS_TELEMETRY_CONTRACT_VERSION = "1.0.0";
+export declare const CARECOMPASS_TELEMETRY_CONTRACT_VERSION = "1.1.0";

package/dist/version.js

@@ -1,3 +1,3 @@
-export const CARECOMPASS_SDK_VERSION = "0.4.0-beta.15"; // x-release-please-version
+export const CARECOMPASS_SDK_VERSION = "0.6.0"; // x-release-please-version
 export const CARECOMPASS_COMPONENT_VERSION = "1.0.0";
-export const CARECOMPASS_TELEMETRY_CONTRACT_VERSION = "1.0.0";
+export const CARECOMPASS_TELEMETRY_CONTRACT_VERSION = "1.1.0";

package/dist/web-component.d.ts

@@ -0,0 +1,13 @@
+import type { CareCompassRuntimeTokenProvider } from "./client.js";
+import { type CareCompassConfig } from "./schema.js";
+export declare const CARECOMPASS_ELEMENT_TAG = "carecompass-chat";
+export type CareCompassWebComponentElement = HTMLElement & {
+    config: CareCompassConfig | undefined;
+    runtimeTokenProvider: CareCompassRuntimeTokenProvider | undefined;
+};
+/**
+ * Register a framework-neutral embed backed directly by the headless core.
+ * Deferring the HTMLElement subclass creation keeps this entry point safe to
+ * import during server rendering.
+ */
+export declare function defineCareCompassElement(tagName?: string): CustomElementConstructor | undefined;

package/dist/web-component.js

@@ -0,0 +1,236 @@
+import { createCareCompassCore, } from "./core.js";
+import { validateCareCompassConfig } from "./schema.js";
+export const CARECOMPASS_ELEMENT_TAG = "carecompass-chat";
+/**
+ * Register a framework-neutral embed backed directly by the headless core.
+ * Deferring the HTMLElement subclass creation keeps this entry point safe to
+ * import during server rendering.
+ */
+export function defineCareCompassElement(tagName = CARECOMPASS_ELEMENT_TAG) {
+    if (typeof customElements === "undefined" ||
+        typeof HTMLElement === "undefined") {
+        return undefined;
+    }
+    const existing = customElements.get(tagName);
+    if (existing)
+        return existing;
+    class CareCompassElement extends HTMLElement {
+        constructor() {
+            super(...arguments);
+            this.draft = "";
+            this.hasPropertyConfig = false;
+        }
+        static get observedAttributes() {
+            return ["config"];
+        }
+        get config() {
+            return this.configuredValue;
+        }
+        set config(value) {
+            this.hasPropertyConfig = true;
+            this.configuredValue = value;
+            this.remount();
+        }
+        get runtimeTokenProvider() {
+            return this.runtimeTokenProviderValue;
+        }
+        set runtimeTokenProvider(value) {
+            this.runtimeTokenProviderValue = value;
+            this.remount();
+        }
+        connectedCallback() {
+            this.remount();
+        }
+        disconnectedCallback() {
+            this.unmount();
+        }
+        attributeChangedCallback(name, _oldValue, value) {
+            if (name !== "config" || this.hasPropertyConfig)
+                return;
+            if (value === null) {
+                this.configuredValue = undefined;
+                this.remount();
+                return;
+            }
+            try {
+                this.configuredValue = JSON.parse(value);
+                this.remount();
+            }
+            catch {
+                this.reportConfigurationError();
+            }
+        }
+        unmount() {
+            this.unsubscribe?.();
+            this.unsubscribe = undefined;
+            this.core?.dispose();
+            this.core = undefined;
+            this.replaceChildren();
+        }
+        remount() {
+            this.unmount();
+            if (!this.isConnected || !this.configuredValue)
+                return;
+            const validation = validateCareCompassConfig(this.configuredValue);
+            if (!validation.ok) {
+                this.reportConfigurationError();
+                return;
+            }
+            this.core = createCareCompassCore(validation.config, {
+                onAuditEvent: (event) => this.dispatchMetadataEvent("carecompass-audit", event),
+                onSafetyEvent: (event) => this.dispatchMetadataEvent("carecompass-safety", event),
+                runtimeTokenProvider: this.runtimeTokenProviderValue,
+            });
+            this.unsubscribe = this.core.subscribe((snapshot) => this.renderSnapshot(validation.config, snapshot));
+            this.renderSnapshot(validation.config, this.core.getSnapshot());
+        }
+        dispatchMetadataEvent(name, event) {
+            // Core audit and safety records intentionally contain metadata and PHI
+            // summaries only; never interpolate message text into DOM events.
+            this.dispatchEvent(new CustomEvent(name, {
+                bubbles: true,
+                detail: event,
+            }));
+        }
+        renderSnapshot(config, snapshot) {
+            const section = document.createElement("section");
+            section.setAttribute("aria-label", config.labels.title);
+            Object.assign(section.style, {
+                background: config.theme.backgroundColor,
+                border: `1px solid ${config.theme.textColor}22`,
+                borderRadius: config.theme.borderRadius,
+                color: config.theme.textColor,
+                display: "flex",
+                flexDirection: "column",
+                fontFamily: config.theme.fontFamily,
+                maxWidth: config.placement.mode === "sidebar" ? "420px" : "720px",
+                minHeight: "420px",
+                overflow: "hidden",
+            });
+            const header = document.createElement("header");
+            Object.assign(header.style, {
+                borderBottom: `1px solid ${config.theme.textColor}22`,
+                padding: "16px",
+            });
+            const title = document.createElement("strong");
+            title.textContent = config.labels.title;
+            const brand = document.createElement("div");
+            brand.textContent = config.branding.displayName;
+            brand.style.fontSize = "12px";
+            brand.style.opacity = "0.72";
+            header.append(title, brand);
+            const messages = document.createElement("div");
+            messages.setAttribute("aria-live", "polite");
+            Object.assign(messages.style, {
+                display: "flex",
+                flex: "1",
+                flexDirection: "column",
+                gap: "12px",
+                overflowY: "auto",
+                padding: "16px",
+            });
+            for (const message of snapshot.messages) {
+                const bubble = document.createElement("div");
+                bubble.textContent = message.text;
+                Object.assign(bubble.style, {
+                    alignSelf: message.role === "user" ? "flex-end" : "flex-start",
+                    background: message.role === "user"
+                        ? config.theme.primaryColor
+                        : `${config.theme.textColor}12`,
+                    borderRadius: "12px",
+                    color: message.role === "user" ? "#ffffff" : "inherit",
+                    maxWidth: "82%",
+                    padding: "10px 12px",
+                    whiteSpace: "pre-wrap",
+                });
+                messages.append(bubble);
+            }
+            if (snapshot.loading) {
+                const thinking = document.createElement("div");
+                thinking.textContent = "Thinking...";
+                thinking.style.fontSize = "13px";
+                thinking.style.opacity = "0.72";
+                messages.append(thinking);
+            }
+            const form = document.createElement("form");
+            Object.assign(form.style, {
+                borderTop: `1px solid ${config.theme.textColor}22`,
+                display: "flex",
+                flexDirection: "column",
+                gap: "8px",
+                padding: "12px",
+            });
+            form.addEventListener("submit", (event) => {
+                event.preventDefault();
+                void this.sendMessage(snapshot);
+            });
+            const controls = document.createElement("div");
+            controls.style.display = "flex";
+            controls.style.gap = "8px";
+            const input = document.createElement("input");
+            input.setAttribute("aria-label", config.labels.placeholder);
+            input.disabled = snapshot.loading;
+            input.placeholder = config.labels.placeholder;
+            input.value = this.draft;
+            input.style.flex = "1";
+            input.style.minWidth = "0";
+            input.style.padding = "10px 12px";
+            input.addEventListener("input", () => {
+                this.draft = input.value;
+                send.disabled = snapshot.loading || !this.draft.trim();
+            });
+            const send = document.createElement("button");
+            send.disabled = snapshot.loading || !this.draft.trim();
+            send.textContent = config.labels.sendButton;
+            send.type = "submit";
+            Object.assign(send.style, {
+                background: config.theme.primaryColor,
+                border: "0",
+                borderRadius: "8px",
+                color: "#ffffff",
+                fontWeight: "700",
+                padding: "0 14px",
+            });
+            controls.append(input, send);
+            form.append(controls);
+            if (snapshot.error) {
+                const error = document.createElement("div");
+                error.setAttribute("role", "alert");
+                error.textContent = snapshot.error.message;
+                error.style.color = "#b91c1c";
+                error.style.fontSize = "12px";
+                form.append(error);
+            }
+            const disclaimer = document.createElement("div");
+            disclaimer.textContent = config.labels.disclaimer;
+            disclaimer.style.fontSize = "11px";
+            disclaimer.style.opacity = "0.7";
+            form.append(disclaimer);
+            section.append(header, messages, form);
+            this.replaceChildren(section);
+        }
+        async sendMessage(snapshot) {
+            const prompt = this.draft.trim();
+            if (!prompt || snapshot.loading || !this.core)
+                return;
+            this.draft = "";
+            try {
+                this.core.recordWidgetAction();
+                await this.core.sendMessage(prompt);
+            }
+            catch {
+                // The snapshot already carries the safe, user-visible error state.
+            }
+        }
+        reportConfigurationError() {
+            // Do not include raw config or validation detail in DOM events; a config
+            // can contain user-controlled branding and labels.
+            this.dispatchEvent(new CustomEvent("carecompass-error", {
+                bubbles: true,
+                detail: { code: "configuration_invalid" },
+            }));
+        }
+    }
+    customElements.define(tagName, CareCompassElement);
+    return CareCompassElement;
+}