@nexalink/carecompass-sdk 0.1.0-beta.9 → 0.2.0-beta.12

package/dist/client.js

@@ -1,3 +1,15 @@
+import { validateCareCompassConfig } from "./schema.js";
+import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassTelemetry, } from "./telemetry.js";
+// Internal error metadata keeps telemetry classification separate from messages,
+// which may include user-visible API details that should not be emitted.
+class CareCompassClientError extends Error {
+    constructor(message, telemetryErrorCode, telemetryFailureCategory) {
+        super(message);
+        this.telemetryErrorCode = telemetryErrorCode;
+        this.telemetryFailureCategory = telemetryFailureCategory;
+        this.name = "CareCompassClientError";
+    }
+}
 const joinUrl = (baseUrl, path) => `${baseUrl.replace(/\/+$/, "")}${path}`;
 const isLocalhostUrl = (value) => {
     try {
@@ -16,59 +28,186 @@ const isBrowserHostedAwayFromLocalhost = (apiBaseUrl) => {
     return (window.location.hostname !== "localhost" &&
         window.location.hostname !== "127.0.0.1");
 };
-export function createCareCompassClient(config, options = {}) {
+// Keep HTTP status mapping centralized so every client command reports failures
+// with the same public telemetry taxonomy.
+const responseError = (status, message) => {
+    if (status === 401 || status === 403) {
+        return new CareCompassClientError(message, CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED, "authentication");
+    }
+    if (status === 429) {
+        return new CareCompassClientError(message, CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMITED, "rate_limit");
+    }
+    if (status >= 500) {
+        return new CareCompassClientError(message, CARECOMPASS_TELEMETRY_ERROR_CODES.BACKEND_UNAVAILABLE, "network");
+    }
+    return new CareCompassClientError(message, CARECOMPASS_TELEMETRY_ERROR_CODES.API_ERROR, "unknown");
+};
+const telemetryFailure = (error) => error instanceof CareCompassClientError
+    ? {
+        errorCode: error.telemetryErrorCode,
+        failureCategory: error.telemetryFailureCategory,
+    }
+    : {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.INFERENCE_FAILED,
+        failureCategory: "unknown",
+    };
+const captureInferenceFailure = (telemetry, error, durationMs) => {
+    const failure = telemetryFailure(error);
+    telemetry.capture(failure.errorCode === CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMITED
+        ? CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_RATE_LIMITED
+        : CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_FAILED, { ...failure, durationMs });
+};
+export function createCareCompassClient(inputConfig, options = {}) {
+    const telemetry = createCareCompassTelemetry(inputConfig);
+    const now = options.now ?? Date.now;
+    let config;
+    try {
+        const validation = validateCareCompassConfig(inputConfig);
+        if (!validation.ok) {
+            const promptInvalid = validation.errors.some((error) => error.startsWith("prompt."));
+            if (promptInvalid) {
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PROMPT_CONFIGURATION_FAILED, {
+                    errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID,
+                    failureCategory: "configuration",
+                });
+            }
+            telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_CONFIGURATION_FAILED, {
+                errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID,
+                failureCategory: "configuration",
+            });
+            telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_INITIALIZATION_FAILED, {
+                errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID,
+                failureCategory: "configuration",
+            });
+            throw new CareCompassClientError(`Invalid CareCompass config:\n${validation.errors.join("\n")}`, CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID, "configuration");
+        }
+        config = validation.config;
+    }
+    catch (error) {
+        if (error instanceof CareCompassClientError)
+            throw error;
+        telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_CONFIGURATION_FAILED, {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID,
+            failureCategory: "configuration",
+        });
+        telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_INITIALIZATION_FAILED, {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID,
+            failureCategory: "configuration",
+        });
+        throw new CareCompassClientError("Invalid CareCompass config.", CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIGURATION_INVALID, "configuration");
+    }
     const fetcher = options.fetcher ?? fetch;
+    // These headers are the public embed identity; secret API keys stay in the CLI.
     const headers = {
         "content-type": "application/json",
         "x-carecompass-payer-id": config.payerId,
         "x-carecompass-embed-key": config.embedKey,
         "x-carecompass-environment": config.environment,
     };
+    const jobStartedAt = new Map();
+    telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_INITIALIZED);
+    telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.THEME_LOADED);
+    telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PROMPT_CONFIGURATION_LOADED);
     async function send(input, init) {
+        // Hosted demos and sandboxes cannot call a developer's local API server, so
+        // fail early with a setup hint instead of surfacing an opaque fetch error.
         if (isBrowserHostedAwayFromLocalhost(config.apiBaseUrl)) {
-            throw new Error(`CareCompass apiBaseUrl is ${config.apiBaseUrl}, but this page is running at ${window.location.origin}. A hosted sandbox or payer site cannot reach your local Next.js server. Use a deployed Nexalink API base URL, or run both the payer page and Nexalink web app locally on the same machine.`);
+            throw new CareCompassClientError(`CareCompass apiBaseUrl is ${config.apiBaseUrl}, but this page is running at ${window.location.origin}. A hosted sandbox or remote site cannot reach your local Next.js server. Use a deployed Nexalink API base URL, or run both the integrating page and Nexalink web app locally on the same machine.`, CARECOMPASS_TELEMETRY_ERROR_CODES.NETWORK_ERROR, "network");
         }
         try {
             return await fetcher(input, init);
         }
         catch (error) {
+            if (error instanceof CareCompassClientError)
+                throw error;
             const message = error instanceof Error ? error.message : "Network request failed";
-            throw new Error(`CareCompass could not reach ${config.apiBaseUrl}. Confirm apiBaseUrl, CORS, allowedOrigins, and Nexalink hosted API configuration. ${message}`);
+            throw new CareCompassClientError(`CareCompass could not reach ${config.apiBaseUrl}. Confirm apiBaseUrl, CORS, allowedOrigins, and Nexalink hosted API configuration. ${message}`, CARECOMPASS_TELEMETRY_ERROR_CODES.NETWORK_ERROR, "network");
         }
     }
     async function parseJson(response) {
         const body = (await response.json().catch(() => ({})));
         if (!response.ok) {
-            throw new Error(body.error ?? "CareCompass request failed.");
+            throw responseError(response.status, body.error ?? "CareCompass request failed.");
         }
         return body;
     }
     return {
         validateConfig: async () => {
-            const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/config/validate"), {
-                method: "POST",
-                headers,
-                body: JSON.stringify({ config }),
-            });
-            return parseJson(response);
+            const startedAt = now();
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/config/validate"), {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify({ config }),
+                });
+                const result = await parseJson(response);
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_CONFIGURATION_VALIDATED, { durationMs: now() - startedAt });
+                return result;
+            }
+            catch (error) {
+                telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.SDK_CONFIGURATION_FAILED, { ...telemetryFailure(error), durationMs: now() - startedAt });
+                throw error;
+            }
         },
         ask: async (request) => {
-            const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/ask"), {
-                method: "POST",
-                headers,
-                body: JSON.stringify({
-                    prompt: request.prompt,
-                    sessionId: request.sessionId,
-                    userContext: request.userContext,
-                    promptConfig: config.prompt,
-                }),
-            });
-            return parseJson(response);
+            const startedAt = now();
+            telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.PROMPT_SUBMITTED);
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, "/api/carecompass/embed/ask"), {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify({
+                        prompt: request.prompt,
+                        sessionId: request.sessionId,
+                        userContext: request.userContext,
+                        promptConfig: config.prompt,
+                    }),
+                });
+                const result = await parseJson(response);
+                // Status polling is asynchronous, so retain the submit timestamp until
+                // the final job state lets telemetry report end-to-end latency.
+                jobStartedAt.set(result.jobId, startedAt);
+                return result;
+            }
+            catch (error) {
+                captureInferenceFailure(telemetry, error, now() - startedAt);
+                throw error;
+            }
         },
         status: async (jobId) => {
-            const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/status/${encodeURIComponent(jobId)}`), { headers });
-            return parseJson(response);
+            const startedAt = jobStartedAt.get(jobId) ?? now();
+            try {
+                const response = await send(joinUrl(config.apiBaseUrl, `/api/carecompass/embed/status/${encodeURIComponent(jobId)}`), { headers });
+                const result = await parseJson(response);
+                if (result.status === "complete") {
+                    jobStartedAt.delete(jobId);
+                    telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_SUCCEEDED, {
+                        durationMs: now() - startedAt,
+                    });
+                }
+                else if (result.status === "failed") {
+                    jobStartedAt.delete(jobId);
+                    telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_FAILED, {
+                        durationMs: now() - startedAt,
+                        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.INFERENCE_FAILED,
+                        failureCategory: "inference",
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                jobStartedAt.delete(jobId);
+                captureInferenceFailure(telemetry, error, now() - startedAt);
+                throw error;
+            }
+        },
+        recordInferenceTimeout: (jobId, durationMs) => {
+            jobStartedAt.delete(jobId);
+            telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.INFERENCE_FAILED, {
+                durationMs,
+                errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.INFERENCE_TIMEOUT,
+                failureCategory: "timeout",
+            });
         },
     };
 }
-//# sourceMappingURL=client.js.map

package/dist/component.js

@@ -1,7 +1,31 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { createCareCompassClient } from "./client.js";
-export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
+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.
+class CareCompassErrorBoundary extends React.Component {
+    constructor() {
+        super(...arguments);
+        this.state = { failed: false };
+    }
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch() {
+        this.props.telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_ERROR, {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RENDER_FAILED,
+            failureCategory: "rendering",
+        });
+    }
+    render() {
+        if (this.state.failed) {
+            return _jsx("div", { role: "alert", children: this.props.config.labels.errorMessage });
+        }
+        return this.props.children;
+    }
+}
+function CareCompassEmbedContent({ config, telemetry, pollIntervalMs = 1500, }) {
     const client = React.useMemo(() => createCareCompassClient(config), [config]);
     const [messages, setMessages] = React.useState([
         {
@@ -13,6 +37,13 @@ export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
     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);
+        return () => {
+            telemetry.capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_CLOSED);
+        };
+    }, [telemetry]);
     async function sendMessage(event) {
         event.preventDefault();
         const prompt = input.trim();
@@ -28,6 +59,8 @@ export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
         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) {
@@ -46,6 +79,7 @@ export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
                 }
                 await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
             }
+            client.recordInferenceTimeout(jobId, Date.now() - startedAt);
             throw new Error("CareCompass request timed out.");
         }
         catch (err) {
@@ -119,4 +153,9 @@ export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
                                     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 })] })] }));
 }
-//# sourceMappingURL=component.js.map
+export function CareCompassEmbed({ config, pollIntervalMs = 1500, }) {
+    // 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 }) }));
+}

package/dist/credentials.js

@@ -20,6 +20,8 @@ export function readStoredApiKey(path = resolveCredentialsPath()) {
             : null;
     }
     catch {
+        // Missing, unreadable, or malformed credential files are treated the same so
+        // callers can fall through to the next credential source without leaking paths.
         return null;
     }
 }
@@ -37,6 +39,8 @@ export function writeStoredApiKey(apiKey, path = resolveCredentialsPath()) {
     }
 }
 export function resolveApiKey(argumentApiKey, env = process.env, credentialsPath = resolveCredentialsPath(env)) {
+    // Precedence mirrors common CLI behavior: explicit flag, then environment,
+    // then the local credential store created by `carecompass login` or `init`.
     const argKey = normalizeApiKey(argumentApiKey);
     if (argKey)
         return { apiKey: argKey, source: "argument" };
@@ -48,4 +52,3 @@ export function resolveApiKey(argumentApiKey, env = process.env, credentialsPath
         return { apiKey: fileKey, source: "file" };
     return { apiKey: null, source: "missing" };
 }
-//# sourceMappingURL=credentials.js.map

package/dist/index.d.ts

@@ -3,5 +3,8 @@ export type { CareCompassAskRequest, CareCompassAskResponse, CareCompassStatusRe
 export { CareCompassEmbed } from "./component.js";
 export { mountCareCompass } from "./mount.js";
 export { generateCareCompassIframeSnippet, generateCareCompassSnippet, } from "./snippet.js";
-export { careCompassConfigSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
-export type { CareCompassConfig, CareCompassLabels, CareCompassPromptConfig, CareCompassTheme, CareCompassValidationResult, } from "./schema.js";
+export { careCompassApiBaseUrlSchema, careCompassConfigSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
+export type { CareCompassConfig, CareCompassConfigInput, CareCompassLabels, CareCompassPromptConfig, CareCompassTheme, CareCompassValidationResult, } from "./schema.js";
+export { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, careCompassTelemetryDurationBucket, createCareCompassCliTelemetry, createCareCompassTelemetry, } from "./telemetry.js";
+export type { CareCompassTelemetry, CareCompassTelemetryCaptureOptions, CareCompassTelemetryDurationBucket, CareCompassTelemetryErrorCode, CareCompassTelemetryEvent, CareCompassTelemetryFailureCategory, } from "./telemetry.js";
+export { CARECOMPASS_COMPONENT_VERSION, CARECOMPASS_SDK_VERSION, CARECOMPASS_TELEMETRY_CONTRACT_VERSION, } from "./version.js";

package/dist/index.js

@@ -2,5 +2,6 @@ export { createCareCompassClient } from "./client.js";
 export { CareCompassEmbed } from "./component.js";
 export { mountCareCompass } from "./mount.js";
 export { generateCareCompassIframeSnippet, generateCareCompassSnippet, } from "./snippet.js";
-export { careCompassConfigSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
-//# sourceMappingURL=index.js.map
+export { careCompassApiBaseUrlSchema, careCompassConfigSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
+export { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, careCompassTelemetryDurationBucket, createCareCompassCliTelemetry, createCareCompassTelemetry, } from "./telemetry.js";
+export { CARECOMPASS_COMPONENT_VERSION, CARECOMPASS_SDK_VERSION, CARECOMPASS_TELEMETRY_CONTRACT_VERSION, } from "./version.js";

package/dist/mount.js

@@ -1,13 +1,21 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createRoot } from "react-dom/client";
 import { CareCompassEmbed } from "./component.js";
+import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassTelemetry, } from "./telemetry.js";
 export function mountCareCompass(element, config) {
-    if (!element)
+    if (!element) {
+        // Missing mount points usually mean a copied snippet and page markup drifted
+        // apart, so capture the setup error before throwing to the caller.
+        createCareCompassTelemetry(config).capture(CARECOMPASS_TELEMETRY_EVENTS.COMPONENT_ERROR, {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.MOUNT_ELEMENT_MISSING,
+            failureCategory: "rendering",
+        });
         throw new Error("CareCompass mount element was not found.");
+    }
     const root = createRoot(element);
     root.render(_jsx(CareCompassEmbed, { config: config }));
     return {
+        // Return the small React root facade so non-React hosts can clean up embeds.
         unmount: () => root.unmount(),
     };
 }
-//# sourceMappingURL=mount.js.map

package/dist/schema.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 export declare const careCompassOriginSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export declare const careCompassApiBaseUrlSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 export declare const careCompassThemeSchema: z.ZodObject<{
     primaryColor: z.ZodString;
     backgroundColor: z.ZodDefault<z.ZodString>;
@@ -40,7 +41,7 @@ export declare const careCompassConfigSchema: z.ZodObject<{
         staging: "staging";
         production: "production";
     }>;
-    apiBaseUrl: z.ZodString;
+    apiBaseUrl: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     embedKey: z.ZodString;
     allowedOrigins: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
     branding: z.ZodObject<{
@@ -88,6 +89,7 @@ export type CareCompassTheme = z.infer<typeof careCompassThemeSchema>;
 export type CareCompassLabels = z.infer<typeof careCompassLabelsSchema>;
 export type CareCompassPromptConfig = z.infer<typeof careCompassPromptConfigSchema>;
 export type CareCompassConfig = z.infer<typeof careCompassConfigSchema>;
+export type CareCompassConfigInput = z.input<typeof careCompassConfigSchema>;
 export type CareCompassValidationResult = {
     ok: true;
     config: CareCompassConfig;

package/dist/schema.js

@@ -2,13 +2,40 @@ import { z } from "zod";
 const HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
 const PAYER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{2,63}$/;
 const EMBED_KEY_RE = /^[A-Za-z0-9._-]{16,128}$/;
+const NEXALINK_HOSTNAME = "nexalink.care";
+// These patterns are a local preflight check, not the full policy layer. They
+// catch obvious prompt configurations that conflict with Nexalink guardrails.
 const unsafePromptPatterns = [
     /ignore (all )?(previous|prior) (instructions|rules)/i,
     /bypass (safety|guardrails|compliance)/i,
     /disable (safety|guardrails|compliance)/i,
     /provide (a )?(diagnosis|treatment plan)/i,
+    /reveal (the )?(system|developer) (prompt|instructions)/i,
+    /override (nexalink|carecompass) (safety|guardrails|policy)/i,
     /return raw (phi|credentials|tokens|secrets)/i,
 ];
+const isLocalhostHostname = (hostname) => hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+const isNexalinkHostname = (hostname) => hostname === NEXALINK_HOSTNAME || hostname.endsWith(`.${NEXALINK_HOSTNAME}`);
+const parseUrl = (value) => {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+};
+const isLocalhostUrl = (value) => {
+    const parsed = parseUrl(value);
+    return parsed ? isLocalhostHostname(parsed.hostname) : false;
+};
+const isNexalinkHostedApiUrl = (value) => {
+    const parsed = parseUrl(value);
+    if (!parsed)
+        return false;
+    if (isLocalhostHostname(parsed.hostname))
+        return true;
+    return parsed.protocol === "https:" && isNexalinkHostname(parsed.hostname);
+};
 export const careCompassOriginSchema = z
     .string()
     .url("Allowed origins must be valid URLs.")
@@ -17,6 +44,13 @@ export const careCompassOriginSchema = z
     const parsed = new URL(value);
     return parsed.protocol === "https:" || parsed.hostname === "localhost";
 }, "Allowed origins must use HTTPS, except localhost for development.");
+export const careCompassApiBaseUrlSchema = z
+    .string()
+    .url("API base URL must be a valid URL.")
+    .transform((value) => value.replace(/\/+$/, ""))
+    // Runtime traffic should stay on Nexalink-hosted HTTPS endpoints; localhost is
+    // kept only for development because integrators need to test local web apps.
+    .refine(isNexalinkHostedApiUrl, "API base URL must be a Nexalink-hosted HTTPS URL, except localhost for development.");
 export const careCompassThemeSchema = z.object({
     primaryColor: z.string().regex(HEX_COLOR_RE, "Use a hex color like #2563eb."),
     backgroundColor: z
@@ -72,17 +106,32 @@ export const careCompassPromptConfigSchema = z
 });
 export const careCompassBrandingSchema = z.object({
     displayName: z.string().min(1).max(80),
-    logoUrl: z.string().url().optional(),
-    supportUrl: z.string().url().optional(),
+    logoUrl: z
+        .string()
+        .url()
+        .refine((value) => {
+        const parsed = new URL(value);
+        return (parsed.protocol === "https:" || isLocalhostHostname(parsed.hostname));
+    }, "Logo URL must use HTTPS, except localhost for development.")
+        .optional(),
+    supportUrl: z
+        .string()
+        .url()
+        .refine((value) => {
+        const parsed = new URL(value);
+        return (parsed.protocol === "https:" || isLocalhostHostname(parsed.hostname));
+    }, "Support URL must use HTTPS, except localhost for development.")
+        .optional(),
 });
 export const careCompassPlacementSchema = z.object({
     mode: z.enum(["inline", "floating", "sidebar"]).default("inline"),
     selector: z.string().min(1).max(120).optional(),
 });
-export const careCompassConfigSchema = z.object({
+export const careCompassConfigSchema = z
+    .object({
     payerId: z.string().regex(PAYER_ID_RE, "Invalid payer ID."),
     environment: z.enum(["development", "staging", "production"]),
-    apiBaseUrl: z.string().url("API base URL must be a valid URL."),
+    apiBaseUrl: careCompassApiBaseUrlSchema,
     embedKey: z.string().regex(EMBED_KEY_RE, "Invalid public embed key."),
     allowedOrigins: z
         .array(careCompassOriginSchema)
@@ -104,6 +153,28 @@ export const careCompassConfigSchema = z.object({
     deploymentTarget: z
         .enum(["react", "nextjs", "static", "web", "other"])
         .default("web"),
+})
+    .superRefine((value, ctx) => {
+    // Development can point both sides at localhost. Staging and production must
+    // use deployable origins so embeds cannot ship with machine-local endpoints.
+    if (value.environment === "development")
+        return;
+    if (isLocalhostUrl(value.apiBaseUrl)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["apiBaseUrl"],
+            message: "Staging and production API base URLs must use a Nexalink-hosted HTTPS URL.",
+        });
+    }
+    for (const [index, origin] of value.allowedOrigins.entries()) {
+        if (isLocalhostUrl(origin)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["allowedOrigins", index],
+                message: "Staging and production allowed origins must not use localhost.",
+            });
+        }
+    }
 });
 export function validateCareCompassConfig(value) {
     const result = careCompassConfigSchema.safeParse(value);
@@ -111,6 +182,8 @@ export function validateCareCompassConfig(value) {
         return { ok: true, config: result.data };
     return {
         ok: false,
+        // Flatten Zod issue paths into CLI-friendly strings while preserving enough
+        // context for users to find the bad field quickly.
         errors: result.error.issues.map((issue) => {
             const path = issue.path.length ? `${issue.path.join(".")}: ` : "";
             return `${path}${issue.message}`;
@@ -118,6 +191,8 @@ export function validateCareCompassConfig(value) {
     };
 }
 export function createDefaultCareCompassConfig(overrides = {}) {
+    // Defaults are intentionally valid staging examples so tests and generated
+    // setup kits can start from a complete config and override only local details.
     return careCompassConfigSchema.parse({
         payerId: "payer-demo",
         environment: "staging",
@@ -142,4 +217,3 @@ export function createDefaultCareCompassConfig(overrides = {}) {
         ...overrides,
     });
 }
-//# sourceMappingURL=schema.js.map

package/dist/snippet.js

@@ -1,9 +1,26 @@
+const SCRIPT_JSON_ESCAPES = {
+    "<": "\\u003c",
+    ">": "\\u003e",
+    "&": "\\u0026",
+    "\u2028": "\\u2028",
+    "\u2029": "\\u2029",
+};
+const escapeHtmlAttribute = (value) => value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+// Script JSON needs stronger escaping than attributes because `</script>` and
+// Unicode line separators can terminate or break the generated module.
+const serializeScriptJson = (value) => JSON.stringify(value, null, 2).replace(/[<>&\u2028\u2029]/g, (character) => SCRIPT_JSON_ESCAPES[character]);
 export function generateCareCompassIframeSnippet(config, options = {}) {
     const src = options.src ?? "/carecompass/carecompass-embed.html";
     const title = `${config.branding.displayName} CareCompass`;
+    // The iframe form is intentionally static so it can be pasted into CMS pages
+    // or server-rendered apps without needing a bundler.
     return `<iframe
-  title="${title.replaceAll('"', "&quot;")}"
-  src="${src.replaceAll('"', "&quot;")}"
+  title="${escapeHtmlAttribute(title)}"
+  src="${escapeHtmlAttribute(src)}"
   style="width: 100%; min-height: 640px; border: 0; border-radius: ${config.theme.borderRadius};"
   loading="lazy"
 ></iframe>`;
@@ -13,12 +30,13 @@ export function generateCareCompassSnippet(config, options = {}) {
     const moduleUrl = options.mode === "cdn"
         ? "https://esm.sh/@nexalink/carecompass-sdk"
         : "@nexalink/carecompass-sdk";
+    // The config is embedded beside the mount call so the generated page is
+    // deployable as a single static asset.
     return `<div id="${targetId}"></div>
 <script type="module">
   import { mountCareCompass } from "${moduleUrl}";
 
-  const config = ${JSON.stringify(config, null, 2)};
+  const config = ${serializeScriptJson(config)};
   mountCareCompass(document.getElementById("${targetId}"), config);
 </script>`;
 }
-//# sourceMappingURL=snippet.js.map

package/dist/telemetry.d.ts

@@ -0,0 +1,71 @@
+import type { CareCompassConfig } from "./schema.js";
+export declare const CARECOMPASS_TELEMETRY_EVENTS: {
+    readonly SDK_INITIALIZED: "carecompass_sdk_initialized";
+    readonly SDK_INITIALIZATION_FAILED: "carecompass_sdk_initialization_failed";
+    readonly SDK_CONFIGURATION_VALIDATED: "carecompass_sdk_configuration_validated";
+    readonly SDK_CONFIGURATION_FAILED: "carecompass_sdk_configuration_failed";
+    readonly COMPONENT_RENDERED: "carecompass_component_rendered";
+    readonly COMPONENT_OPENED: "carecompass_component_opened";
+    readonly COMPONENT_CLOSED: "carecompass_component_closed";
+    readonly COMPONENT_ERROR: "carecompass_component_error";
+    readonly PROMPT_SUBMITTED: "carecompass_prompt_submitted";
+    readonly INFERENCE_SUCCEEDED: "carecompass_inference_succeeded";
+    readonly INFERENCE_FAILED: "carecompass_inference_failed";
+    readonly INFERENCE_RATE_LIMITED: "carecompass_inference_rate_limited";
+    readonly THEME_LOADED: "carecompass_theme_loaded";
+    readonly PROMPT_CONFIGURATION_LOADED: "carecompass_prompt_configuration_loaded";
+    readonly PROMPT_CONFIGURATION_FAILED: "carecompass_prompt_configuration_failed";
+    readonly CLI_STARTED: "carecompass_cli_started";
+    readonly CLI_LOGIN_STARTED: "carecompass_cli_login_started";
+    readonly CLI_LOGIN_SUCCEEDED: "carecompass_cli_login_succeeded";
+    readonly CLI_LOGIN_FAILED: "carecompass_cli_login_failed";
+    readonly CLI_INIT_STARTED: "carecompass_cli_init_started";
+    readonly CLI_INIT_FAILED: "carecompass_cli_init_failed";
+    readonly CLI_SETUP_KIT_GENERATED: "carecompass_cli_setup_kit_generated";
+    readonly CLI_VALIDATION_SUCCEEDED: "carecompass_cli_validation_succeeded";
+    readonly CLI_VALIDATION_FAILED: "carecompass_cli_validation_failed";
+    readonly CLI_SNIPPET_GENERATED: "carecompass_cli_snippet_generated";
+    readonly CLI_DOCTOR_COMPLETED: "carecompass_cli_doctor_completed";
+    readonly CLI_COMMAND_FAILED: "carecompass_cli_command_failed";
+};
+export type CareCompassTelemetryEvent = (typeof CARECOMPASS_TELEMETRY_EVENTS)[keyof typeof CARECOMPASS_TELEMETRY_EVENTS];
+export declare const CARECOMPASS_TELEMETRY_ERROR_CODES: {
+    readonly API_ERROR: "api_error";
+    readonly AUTHENTICATION_FAILED: "authentication_failed";
+    readonly BACKEND_UNAVAILABLE: "backend_unavailable";
+    readonly CONFIGURATION_INVALID: "configuration_invalid";
+    readonly INFERENCE_FAILED: "inference_failed";
+    readonly INFERENCE_TIMEOUT: "inference_timeout";
+    readonly MOUNT_ELEMENT_MISSING: "mount_element_missing";
+    readonly NETWORK_ERROR: "network_error";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly RENDER_FAILED: "render_failed";
+    readonly CLI_COMMAND_FAILED: "cli_command_failed";
+};
+export type CareCompassTelemetryErrorCode = (typeof CARECOMPASS_TELEMETRY_ERROR_CODES)[keyof typeof CARECOMPASS_TELEMETRY_ERROR_CODES];
+export type CareCompassTelemetryFailureCategory = "authentication" | "configuration" | "inference" | "network" | "rate_limit" | "rendering" | "timeout" | "unknown";
+export type CareCompassTelemetryDurationBucket = "under_250_ms" | "250_to_999_ms" | "1_to_4_999_ms" | "5_to_29_999_ms" | "30_s_or_more";
+export type CareCompassTelemetryCaptureOptions = {
+    durationMs?: number;
+    errorCode?: CareCompassTelemetryErrorCode;
+    failureCategory?: CareCompassTelemetryFailureCategory;
+};
+type Fetcher = typeof fetch;
+export type CareCompassTelemetry = {
+    enabled: boolean;
+    capture: (event: CareCompassTelemetryEvent, options?: CareCompassTelemetryCaptureOptions) => void;
+    captureAsync: (event: CareCompassTelemetryEvent, options?: CareCompassTelemetryCaptureOptions) => Promise<void>;
+};
+export declare const careCompassTelemetryDurationBucket: (durationMs: number) => CareCompassTelemetryDurationBucket;
+export declare function createCareCompassTelemetry(config: Pick<CareCompassConfig, "environment" | "payerId">, options?: {
+    fetcher?: Fetcher;
+    now?: () => Date;
+}): CareCompassTelemetry;
+export declare function createCareCompassCliTelemetry(sessionId: string, context?: {
+    environment?: CareCompassConfig["environment"];
+    payerId?: string;
+}, options?: {
+    fetcher?: Fetcher;
+    now?: () => Date;
+}): CareCompassTelemetry;
+export {};