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

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
+import { careCompassApiBaseUrlSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
 import { normalizeApiKey, resolveApiKey, resolveCredentialsPath, writeStoredApiKey, } from "./credentials.js";
 import { generateCareCompassIframeSnippet, generateCareCompassSnippet, } from "./snippet.js";
 import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassCliTelemetry, } from "./telemetry.js";
@@ -31,6 +31,172 @@ support resources, and appropriate next steps. Stay out of diagnosis, treatment
 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([
+    "doctor",
+    "help",
+    "init",
+    "login",
+    "snippet",
+    "validate",
+]);
+class CliTelemetryError extends Error {
+    constructor(message, telemetry) {
+        super(message);
+        this.telemetry = telemetry;
+    }
+}
+const sanitizeCommandName = (command) => {
+    const normalized = command === "--help" || command === "-h" ? "help" : command;
+    return CLI_COMMAND_ALLOWLIST.has(normalized) ? normalized : "unknown_command";
+};
+const authTelemetryForSource = (source) => {
+    if (source === "environment") {
+        return { authMethod: "env_var", keySource: "env_var" };
+    }
+    if (source === "file") {
+        return { authMethod: "config_file", keySource: "config_file" };
+    }
+    return { authMethod: "api_key", keySource: "cli_flag" };
+};
+const normalizeBaaStatus = (value) => {
+    if (value === "signed" || value === "pending" || value === "not_required") {
+        return value;
+    }
+    return "signed";
+};
+const classifyAuthFailure = (status, message) => {
+    const normalized = message.toLowerCase();
+    if (status === 429 || normalized.includes("rate limit")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+            failureCategory: "rate_limit_error",
+            baaStatus: "signed",
+        };
+    }
+    if (status === 403 ||
+        normalized.includes("baa") ||
+        normalized.includes("business associate")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.BAA_REQUIRED,
+            failureCategory: "baa_not_signed",
+            baaStatus: "pending",
+        };
+    }
+    if (normalized.includes("expired")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_EXPIRED,
+            failureCategory: "auth_error",
+            baaStatus: "signed",
+        };
+    }
+    return {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_INVALID,
+        failureCategory: "auth_error",
+        baaStatus: "signed",
+    };
+};
+const classifyCliFailure = (error) => {
+    if (error instanceof CliTelemetryError)
+        return error.telemetry;
+    const code = error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : "";
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.toLowerCase();
+    if (code === "EACCES" || code === "EPERM") {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.PERMISSION_DENIED,
+            failureCategory: "permission_error",
+        };
+    }
+    if (code === "ENOENT" || normalized.includes("was not found")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIG_NOT_FOUND,
+            failureCategory: "config_error",
+        };
+    }
+    if (normalized.includes("invalid carecompass config") ||
+        normalized.includes("unexpected argument") ||
+        normalized.includes("must be either") ||
+        normalized.includes("api base url")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIG_INVALID,
+            failureCategory: "config_error",
+        };
+    }
+    if (normalized.includes("already exists")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIG_ALREADY_EXISTS,
+            failureCategory: "config_error",
+        };
+    }
+    if (normalized.includes("missing nexalink api key")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_MISSING,
+            failureCategory: "auth_error",
+        };
+    }
+    if (normalized.includes("api key format") ||
+        normalized.includes("invalid api key")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_INVALID,
+            failureCategory: "auth_error",
+        };
+    }
+    if (normalized.includes("baa execution") ||
+        normalized.includes("business associate")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.BAA_REQUIRED,
+            failureCategory: "baa_not_signed",
+        };
+    }
+    if (normalized.includes("rate limit") || normalized.includes("quota")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+            failureCategory: "rate_limit_error",
+        };
+    }
+    if (normalized.includes("timed out") || normalized.includes("timeout")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.NET_TIMEOUT,
+            failureCategory: "network_error",
+        };
+    }
+    if (normalized.includes("could not reach")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.NET_UNREACHABLE,
+            failureCategory: "network_error",
+        };
+    }
+    if (normalized.includes("model load")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.MODEL_LOAD_FAILED,
+            failureCategory: "model_error",
+        };
+    }
+    if (normalized.includes("model") || normalized.includes("inference")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.MODEL_INFERENCE_FAILED,
+            failureCategory: "model_error",
+        };
+    }
+    if (normalized.includes("unknown command")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_UNKNOWN,
+            failureCategory: "unknown",
+        };
+    }
+    if (normalized.includes("cancelled")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_CANCELLED,
+            failureCategory: "unknown",
+        };
+    }
+    return {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.UNKNOWN_ERROR,
+        failureCategory: "unknown",
+    };
+};
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const flags = {};
@@ -210,6 +376,12 @@ const signupUrls = (flags, io) => ({
         io.env.CARECOMPASS_DEVELOPER_SIGNUP_URL ??
         DEFAULT_DEVELOPER_SIGNUP_URL,
 });
+function resolveTrustedApiBaseUrl(value) {
+    const result = careCompassApiBaseUrlSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw new Error(result.error.issues.map((issue) => issue.message).join("\n"));
+}
 function rejectLegacyBaaInitFlags(flags, io) {
     const legacyFlag = LEGACY_BAA_INIT_FLAGS.find((flag) => flag in flags);
     if (!legacyFlag)
@@ -267,7 +439,7 @@ async function validateInitApiKey(apiBaseUrl, apiKey, accountType) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Network request failed";
-        throw new Error(`Could not reach CareCompass authentication API at ${url}. ${message}`);
+        throw new CliTelemetryError(`Could not reach CareCompass authentication API at ${url}. ${message}`, classifyCliFailure(new Error(`Could not reach CareCompass authentication API. ${message}`)));
     }
     const text = await response.text();
     let payload = {};
@@ -278,27 +450,33 @@ async function validateInitApiKey(apiBaseUrl, apiKey, accountType) {
         payload = {};
     }
     if (!response.ok || payload.ok === false) {
+        const message = payload.error ?? "Invalid API key.";
+        const failure = classifyAuthFailure(response.status, message);
         return {
             ok: false,
-            message: payload.error ?? "Invalid API key.",
+            message,
+            ...failure,
         };
     }
     const validatedType = typeof payload.accountType === "string"
         ? normalizeAccountType(payload.accountType)
         : null;
     if (!validatedType) {
+        const message = "Credential validation succeeded but did not return a recognized account type. Contact support@nexalink.care.";
         return {
             ok: false,
-            message: "Credential validation succeeded but did not return a recognized account type. Contact support@nexalink.care.",
+            message,
+            ...classifyAuthFailure(401, message),
         };
     }
     return {
         ok: true,
         accountType: validatedType,
+        baaStatus: normalizeBaaStatus(payload.baaStatus),
         setup: normalizeAuthSetup(payload.setup),
     };
 }
-async function resolveInitApiKey(flags, io, apiBaseUrl) {
+async function resolveInitApiKey(flags, io, apiBaseUrl, onAuthChecked = async () => undefined) {
     const credentialsPath = resolveCredentialsPath(io.env);
     let credentials = resolveApiKey(flagString(flags, "api-key"), io.env, credentialsPath);
     const urls = signupUrls(flags, io);
@@ -316,6 +494,7 @@ async function resolveInitApiKey(flags, io, apiBaseUrl) {
         const apiKey = useResolvedCredential
             ? credentials.apiKey
             : await promptForSecret(io, "Enter API key: ");
+        const authTelemetry = authTelemetryForSource(credentials.source);
         useResolvedCredential = false;
         credentials = { apiKey: null, source: "missing" };
         const normalizedApiKey = normalizeApiKey(apiKey);
@@ -324,11 +503,37 @@ async function resolveInitApiKey(flags, io, apiBaseUrl) {
             continue;
         }
         io.stdout.write("Validating credentials...\n");
-        const validation = await validateInitApiKey(apiBaseUrl, normalizedApiKey, accountType);
+        let validation;
+        try {
+            validation = await validateInitApiKey(apiBaseUrl, normalizedApiKey, accountType);
+        }
+        catch (error) {
+            const failure = classifyCliFailure(error);
+            await onAuthChecked({
+                authResult: "failure",
+                baaStatus: "signed",
+                keySource: authTelemetry.keySource,
+                ...failure,
+            });
+            throw error;
+        }
         if (!validation.ok) {
+            await onAuthChecked({
+                authResult: "failure",
+                baaStatus: validation.baaStatus,
+                keySource: authTelemetry.keySource,
+                errorCode: validation.errorCode,
+                failureCategory: validation.failureCategory,
+            });
             io.stdout.write(`${validation.message}\n`);
             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`);
@@ -340,7 +545,12 @@ async function resolveInitApiKey(flags, io, apiBaseUrl) {
         writeStoredApiKey(normalizedApiKey, credentialsPath);
         io.stdout.write(`Stored CareCompass credentials at ${credentialsPath}\n`);
         io.stdout.write("Sign-in successful.\n");
-        return { apiKey: normalizedApiKey, setup: validation.setup };
+        return {
+            apiKey: normalizedApiKey,
+            authMethod: authTelemetry.authMethod,
+            baaStatus: validation.baaStatus,
+            setup: validation.setup,
+        };
     }
 }
 function resolvePromptFile(config, configPath) {
@@ -349,8 +559,23 @@ function resolvePromptFile(config, configPath) {
         return config;
     // Prompt files are resolved relative to the config file so generated kits work
     // after the caller changes directories.
-    const resolvedPath = resolve(dirname(configPath), promptFile);
-    const systemInstruction = readFileSync(resolvedPath, "utf8").trim();
+    if (isAbsolute(promptFile)) {
+        throw new Error("Prompt file must stay inside the config directory.");
+    }
+    const configDir = realpathSync(resolve(dirname(configPath)));
+    const resolvedPath = resolve(configDir, promptFile);
+    let realPromptPath;
+    try {
+        realPromptPath = realpathSync(resolvedPath);
+    }
+    catch {
+        throw new Error(`CareCompass prompt file was not found: ${promptFile}`);
+    }
+    const relativePromptPath = relative(configDir, realPromptPath);
+    if (relativePromptPath.startsWith("..") || isAbsolute(relativePromptPath)) {
+        throw new Error("Prompt file must stay inside the config directory.");
+    }
+    const systemInstruction = readFileSync(realPromptPath, "utf8").trim();
     const validation = validateCareCompassConfig({
         ...config,
         prompt: {
@@ -562,13 +787,63 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
     // Start with anonymous CLI telemetry, then rebuild it with payer context after
     // a config has been generated or read.
     let cliTelemetry = createCareCompassCliTelemetry(cliSessionId);
-    let activeCommand = "unknown";
+    const sessionStartedAt = Date.now();
+    const rawCommand = argv[0] ?? "help";
+    const telemetryCommandName = sanitizeCommandName(rawCommand);
+    const commandStartedAt = Date.now();
+    let commandsAttempted = 0;
+    let commandsSucceeded = 0;
+    let commandsFailed = 0;
+    let activeCommand = rawCommand;
+    let authCheckedCaptured = false;
+    let sessionEndedCaptured = false;
+    const captureAuthChecked = async (telemetry) => {
+        if (authCheckedCaptured)
+            return;
+        authCheckedCaptured = true;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_AUTH_CHECKED, {
+            authResult: telemetry.authResult,
+            failureCategory: telemetry.authResult === "success"
+                ? null
+                : (telemetry.failureCategory ?? "unknown"),
+            ...(telemetry.errorCode ? { errorCode: telemetry.errorCode } : {}),
+            baaStatus: telemetry.baaStatus,
+            keySource: telemetry.keySource,
+        });
+    };
+    const captureCommandCompleted = async () => {
+        commandsSucceeded += 1;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_COMPLETED, {
+            commandName: telemetryCommandName,
+            commandDurationMs: Date.now() - commandStartedAt,
+            tokensUsed: null,
+            modelId: null,
+        });
+    };
+    const captureSessionEnded = async (exitReason) => {
+        if (sessionEndedCaptured)
+            return;
+        sessionEndedCaptured = true;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_SESSION_ENDED, {
+            sessionDurationMs: Date.now() - sessionStartedAt,
+            commandsAttempted,
+            commandsSucceeded,
+            commandsFailed,
+            exitReason,
+        });
+    };
     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;
         if (command === "help" || command === "--help" || command === "-h") {
             printHelp(io);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "login") {
@@ -581,20 +856,23 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
                     errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED,
                     failureCategory: "authentication",
                 });
+                commandsFailed += 1;
                 return 1;
             }
             const credentialsPath = resolveCredentialsPath(io.env);
             writeStoredApiKey(apiKey, credentialsPath);
             io.stdout.write(`Stored CareCompass credentials at ${credentialsPath}\n`);
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_LOGIN_SUCCEEDED);
+            await captureCommandCompleted();
             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 = flagString(flags, "api-base-url") ?? DEFAULT_API_BASE_URL;
-            const initAuth = await resolveInitApiKey(flags, io, apiBaseUrl);
+            const apiBaseUrl = resolveTrustedApiBaseUrl(flagString(flags, "api-base-url") ?? DEFAULT_API_BASE_URL);
+            const initAuth = await resolveInitApiKey(flags, io, apiBaseUrl, captureAuthChecked);
             const output = flagString(flags, "output") ??
                 join(outputDir, "carecompass.config.json");
             const snippetOutput = flagString(flags, "snippet-output") ??
@@ -657,7 +935,13 @@ Step 5: Follow the generated setup guide
 Next command:
   npx @nexalink/carecompass-sdk validate --config ${output}
 `);
+            await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_COMPLETED, {
+                initDurationMs: Date.now() - initStartedAt,
+                authMethod: initAuth.authMethod,
+                baaStatus: initAuth.baaStatus,
+            });
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_SETUP_KIT_GENERATED);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "validate") {
@@ -670,12 +954,14 @@ Next command:
                 }
                 io.stdout.write(`CareCompass config is valid for ${config.payerId}. Credentials loaded from ${credentials.source}.\n`);
                 await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_SUCCEEDED);
+                await captureCommandCompleted();
                 return 0;
             }
             catch (error) {
+                const failure = classifyCliFailure(error);
                 await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_FAILED, {
-                    errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_FAILED,
-                    failureCategory: "configuration",
+                    errorCode: failure.errorCode,
+                    failureCategory: failure.failureCategory,
                 });
                 throw error;
             }
@@ -697,6 +983,7 @@ Next command:
                 io.stdout.write(`${snippet}\n`);
             }
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_SNIPPET_GENERATED);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "doctor") {
@@ -723,24 +1010,31 @@ Hosted API: ${hostedStatus}
 Status: ready for staging verification
 `);
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_DOCTOR_COMPLETED);
+            await captureCommandCompleted();
             return 0;
         }
         throw new Error(`Unknown command: ${command}`);
     }
     catch (error) {
+        commandsFailed += 1;
+        const failure = classifyCliFailure(error);
         if (activeCommand === "init") {
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_FAILED, {
-                errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_FAILED,
-                failureCategory: "unknown",
+                errorCode: failure.errorCode,
+                failureCategory: failure.failureCategory,
             });
         }
         await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_FAILED, {
-            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_FAILED,
-            failureCategory: "unknown",
+            errorCode: failure.errorCode,
+            failureCategory: failure.failureCategory,
+            commandName: telemetryCommandName,
         });
         io.stderr.write(`${error.message}\n`);
         return 1;
     }
+    finally {
+        await captureSessionEnded(commandsFailed > 0 ? "error" : "user_exit");
+    }
 }
 const isMainModule = () => Boolean(process.argv[1]) &&
     realpathSync(fileURLToPath(import.meta.url)) ===

package/dist/snippet.d.ts

@@ -1,4 +1,4 @@
-import type { CareCompassConfig } from "./schema.js";
+import { type CareCompassConfig } from "./schema.js";
 export type CareCompassSnippetMode = "bundler" | "cdn";
 export declare function generateCareCompassIframeSnippet(config: CareCompassConfig, options?: {
     src?: string;

package/dist/snippet.js

@@ -1,3 +1,4 @@
+import { careCompassThemeSchema } from "./schema.js";
 const SCRIPT_JSON_ESCAPES = {
     "<": "\\u003c",
     ">": "\\u003e",
@@ -16,12 +17,14 @@ const serializeScriptJson = (value) => JSON.stringify(value, null, 2).replace(/[
 export function generateCareCompassIframeSnippet(config, options = {}) {
     const src = options.src ?? "/carecompass/carecompass-embed.html";
     const title = `${config.branding.displayName} CareCompass`;
+    const theme = careCompassThemeSchema.safeParse(config.theme);
+    const borderRadius = theme.success ? theme.data.borderRadius : "8px";
     // 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="${escapeHtmlAttribute(title)}"
   src="${escapeHtmlAttribute(src)}"
-  style="width: 100%; min-height: 640px; border: 0; border-radius: ${config.theme.borderRadius};"
+  style="width: 100%; min-height: 640px; border: 0; border-radius: ${borderRadius};"
   loading="lazy"
 ></iframe>`;
 }

package/dist/telemetry.d.ts

@@ -21,6 +21,11 @@ export declare const CARECOMPASS_TELEMETRY_EVENTS: {
     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_INIT_COMPLETED: "carecompass_cli_init_completed";
+    readonly CLI_COMMAND_STARTED: "carecompass_cli_command_started";
+    readonly CLI_COMMAND_COMPLETED: "carecompass_cli_command_completed";
+    readonly CLI_SESSION_ENDED: "carecompass_cli_session_ended";
+    readonly CLI_AUTH_CHECKED: "carecompass_cli_auth_checked";
     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";
@@ -41,14 +46,50 @@ export declare const CARECOMPASS_TELEMETRY_ERROR_CODES: {
     readonly RATE_LIMITED: "rate_limited";
     readonly RENDER_FAILED: "render_failed";
     readonly CLI_COMMAND_FAILED: "cli_command_failed";
+    readonly AUTH_KEY_MISSING: "AUTH_KEY_MISSING";
+    readonly AUTH_KEY_INVALID: "AUTH_KEY_INVALID";
+    readonly AUTH_KEY_EXPIRED: "AUTH_KEY_EXPIRED";
+    readonly BAA_REQUIRED: "BAA_REQUIRED";
+    readonly NET_TIMEOUT: "NET_TIMEOUT";
+    readonly NET_UNREACHABLE: "NET_UNREACHABLE";
+    readonly CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly CONFIG_ALREADY_EXISTS: "CONFIG_ALREADY_EXISTS";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly MODEL_LOAD_FAILED: "MODEL_LOAD_FAILED";
+    readonly MODEL_INFERENCE_FAILED: "MODEL_INFERENCE_FAILED";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly CLI_COMMAND_CANCELLED: "CLI_COMMAND_CANCELLED";
+    readonly CLI_COMMAND_UNKNOWN: "CLI_COMMAND_UNKNOWN";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
 };
 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 CareCompassTelemetryFailureCategory = "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";
+export type CareCompassTelemetryBaaStatus = "signed" | "pending" | "not_required";
+export type CareCompassTelemetryAuthMethod = "api_key" | "env_var" | "config_file";
+export type CareCompassTelemetryKeySource = "env_var" | "config_file" | "cli_flag";
+export type CareCompassTelemetryExitReason = "user_exit" | "error" | "timeout" | "signal";
+export type CareCompassTelemetryAuthResult = "success" | "failure";
 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;
+    failureCategory?: CareCompassTelemetryFailureCategory | null;
+    initDurationMs?: number;
+    authMethod?: CareCompassTelemetryAuthMethod;
+    baaStatus?: CareCompassTelemetryBaaStatus;
+    commandName?: string;
+    commandArgsCount?: number;
+    commandDurationMs?: number;
+    tokensUsed?: number | null;
+    modelId?: string | null;
+    sessionDurationMs?: number;
+    commandsAttempted?: number;
+    commandsSucceeded?: number;
+    commandsFailed?: number;
+    exitReason?: CareCompassTelemetryExitReason;
+    authResult?: CareCompassTelemetryAuthResult;
+    keySource?: CareCompassTelemetryKeySource;
 };
 type Fetcher = typeof fetch;
 export type CareCompassTelemetry = {

package/dist/telemetry.js

@@ -21,6 +21,11 @@ export const CARECOMPASS_TELEMETRY_EVENTS = {
     CLI_LOGIN_FAILED: "carecompass_cli_login_failed",
     CLI_INIT_STARTED: "carecompass_cli_init_started",
     CLI_INIT_FAILED: "carecompass_cli_init_failed",
+    CLI_INIT_COMPLETED: "carecompass_cli_init_completed",
+    CLI_COMMAND_STARTED: "carecompass_cli_command_started",
+    CLI_COMMAND_COMPLETED: "carecompass_cli_command_completed",
+    CLI_SESSION_ENDED: "carecompass_cli_session_ended",
+    CLI_AUTH_CHECKED: "carecompass_cli_auth_checked",
     CLI_SETUP_KIT_GENERATED: "carecompass_cli_setup_kit_generated",
     CLI_VALIDATION_SUCCEEDED: "carecompass_cli_validation_succeeded",
     CLI_VALIDATION_FAILED: "carecompass_cli_validation_failed",
@@ -40,6 +45,22 @@ export const CARECOMPASS_TELEMETRY_ERROR_CODES = {
     RATE_LIMITED: "rate_limited",
     RENDER_FAILED: "render_failed",
     CLI_COMMAND_FAILED: "cli_command_failed",
+    AUTH_KEY_MISSING: "AUTH_KEY_MISSING",
+    AUTH_KEY_INVALID: "AUTH_KEY_INVALID",
+    AUTH_KEY_EXPIRED: "AUTH_KEY_EXPIRED",
+    BAA_REQUIRED: "BAA_REQUIRED",
+    NET_TIMEOUT: "NET_TIMEOUT",
+    NET_UNREACHABLE: "NET_UNREACHABLE",
+    CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+    CONFIG_INVALID: "CONFIG_INVALID",
+    CONFIG_ALREADY_EXISTS: "CONFIG_ALREADY_EXISTS",
+    PERMISSION_DENIED: "PERMISSION_DENIED",
+    MODEL_LOAD_FAILED: "MODEL_LOAD_FAILED",
+    MODEL_INFERENCE_FAILED: "MODEL_INFERENCE_FAILED",
+    RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED",
+    CLI_COMMAND_CANCELLED: "CLI_COMMAND_CANCELLED",
+    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,}$/;
@@ -86,6 +107,8 @@ 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;
 function createTelemetry(context, options = {}) {
     const projectToken = CARECOMPASS_DEFAULT_POSTHOG_PROJECT_TOKEN;
     // Invalid identifiers disable telemetry instead of producing malformed events
@@ -120,12 +143,71 @@ function createTelemetry(context, options = {}) {
                 : {
                     duration_bucket: careCompassTelemetryDurationBucket(captureOptions.durationMs),
                 }),
-            ...(captureOptions.failureCategory
-                ? { failure_category: captureOptions.failureCategory }
-                : {}),
+            ...(captureOptions.failureCategory === undefined
+                ? {}
+                : { failure_category: captureOptions.failureCategory }),
             ...(captureOptions.errorCode
                 ? { error_code: captureOptions.errorCode }
                 : {}),
+            ...(captureOptions.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
+                ? {}
+                : {
+                    command_args_count: integerCount(captureOptions.commandArgsCount),
+                }),
+            ...(captureOptions.commandDurationMs === undefined
+                ? {}
+                : {
+                    command_duration_ms: integerMs(captureOptions.commandDurationMs),
+                }),
+            ...(captureOptions.tokensUsed === undefined
+                ? {}
+                : {
+                    tokens_used: captureOptions.tokensUsed === null
+                        ? null
+                        : integerCount(captureOptions.tokensUsed),
+                }),
+            ...(captureOptions.modelId === undefined
+                ? {}
+                : { model_id: captureOptions.modelId }),
+            ...(captureOptions.sessionDurationMs === 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_failed: integerCount(captureOptions.commandsFailed) }),
+            ...(captureOptions.exitReason
+                ? { exit_reason: captureOptions.exitReason }
+                : {}),
+            ...(captureOptions.authResult
+                ? { auth_result: captureOptions.authResult }
+                : {}),
+            ...(captureOptions.keySource
+                ? { key_source: captureOptions.keySource }
+                : {}),
         };
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), TELEMETRY_CAPTURE_TIMEOUT_MS);

package/dist/version.js

@@ -1,3 +1,3 @@
-export const CARECOMPASS_SDK_VERSION = "0.2.0-beta.13"; // x-release-please-version
+export const CARECOMPASS_SDK_VERSION = "0.3.0-beta.15"; // x-release-please-version
 export const CARECOMPASS_COMPONENT_VERSION = "1.0.0";
 export const CARECOMPASS_TELEMETRY_CONTRACT_VERSION = "1.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexalink/carecompass-sdk",
-  "version": "0.2.0-beta.15",
+  "version": "0.3.0-beta.15",
   "description": "Embeddable CareCompass SDK and CLI for healthcare ecosystem integrations with Nexalink onboarding, BAA coverage, and API keys.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -64,13 +64,13 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.12.4",
+    "@types/node": "^25.9.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "@eslint/js": "^9.39.4",
     "eslint": "^9.39.4",
     "globals": "^16.5.0",
     "jest": "^30.4.2",
@@ -79,8 +79,11 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "ts-jest": "^29.4.1",
-    "typescript-eslint": "^8.48.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1"
+  },
+  "overrides": {
+    "js-yaml": "4.2.0"
   },
   "publishConfig": {
     "access": "public",