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

package/TELEMETRY.md

@@ -0,0 +1,129 @@
+# CareCompass SDK Telemetry Contract
+
+Contract version: `1.0.0`
+
+CareCompass SDK telemetry measures deployment health without collecting PHI,
+PII, chat content, or credentials. The web SDK sends allowlisted anonymous
+events directly to PostHog's public ingestion API. The CLI uses the same narrow
+transport for onboarding funnel events. React Native and Flutter SDKs should
+adopt the same event names and property contract.
+
+## Configuration
+
+Telemetry is enabled automatically for every web SDK deployment. Integrators do
+not need to run an additional CLI command, add a runtime config block, or manage
+a PostHog token.
+
+The web SDK sends events to Nexalink's PostHog project through the public US
+ingestion endpoint. It uses a Nexalink-owned public PostHog project token
+compiled into the SDK. The token permits event ingestion only; it is never a
+PostHog personal or admin API key.
+
+The anonymous deployment ID is derived from the public payer ID, environment,
+and web platform. For example, payer `acme-health` in staging is reported as
+`acme-health-staging-web`.
+
+CLI invocations use an ephemeral random `cli_session_id` as their anonymous
+PostHog `distinct_id`. It is created in memory for one process invocation and is
+not persisted. Before the CLI has public payer context, events use
+`anonymous-unknown-cli`; later events use the public payer ID and environment.
+
+## Event Taxonomy
+
+Initialization and configuration:
+
+- `carecompass_sdk_initialized`
+- `carecompass_sdk_initialization_failed`
+- `carecompass_sdk_configuration_validated`
+- `carecompass_sdk_configuration_failed`
+
+Component lifecycle:
+
+- `carecompass_component_rendered`
+- `carecompass_component_opened`
+- `carecompass_component_closed`
+- `carecompass_component_error`
+
+Inference lifecycle:
+
+- `carecompass_prompt_submitted`
+- `carecompass_inference_succeeded`
+- `carecompass_inference_failed`
+- `carecompass_inference_rate_limited`
+
+Customization and deployment health:
+
+- `carecompass_theme_loaded`
+- `carecompass_prompt_configuration_loaded`
+- `carecompass_prompt_configuration_failed`
+
+CLI onboarding:
+
+- `carecompass_cli_started`
+- `carecompass_cli_login_started`
+- `carecompass_cli_login_succeeded`
+- `carecompass_cli_login_failed`
+- `carecompass_cli_init_started`
+- `carecompass_cli_init_failed`
+- `carecompass_cli_setup_kit_generated`
+- `carecompass_cli_validation_succeeded`
+- `carecompass_cli_validation_failed`
+- `carecompass_cli_snippet_generated`
+- `carecompass_cli_doctor_completed`
+- `carecompass_cli_command_failed`
+
+For the always-visible web embed, opened and closed map to mount and unmount.
+Future mobile components should map these events to their equivalent visible
+screen lifecycle.
+
+## Allowed Properties
+
+Events contain only:
+
+- `contract_version`
+- `sdk_version`
+- `component_version`
+- `platform`
+- `environment`
+- `payer_id`
+- `deployment_id`
+- `event_timestamp`
+- `duration_bucket`, when applicable
+- `failure_category`, when applicable
+- `error_code`, when applicable
+- `cli_session_id`, for CLI events only
+- `$process_person_profile: false`
+
+The transport also sends the public PostHog project token, event name, anonymous
+`distinct_id`, and timestamp required by the PostHog ingestion API. Web events
+use the deployment ID as `distinct_id`; CLI events use the ephemeral
+`cli_session_id`. It does not identify individual users or create person
+profiles.
+
+## Prohibited Data
+
+Never send:
+
+- raw user prompts, model responses, chat history, or optional user context
+- PHI, PII, member IDs, policy IDs, names, emails, or phone numbers
+- API keys, access tokens, cookies, credentials, or session secrets
+- CLI arguments, terminal input, or file paths
+- SageMaker credentials, internal infrastructure details, or privileged tokens
+- raw error objects, stack traces, request payloads, or response bodies
+- payer prompt text; use an approved non-sensitive configuration ID in a future
+  contract version if needed
+
+The web SDK intentionally does not bundle `posthog-js`. It does not enable
+session replay, autocapture, DOM capture, form capture, cookies, persistence,
+surveys, feature flags, or user identification.
+
+Package download counts remain registry-owned metrics. CLI telemetry begins when
+the user invokes the installed package.
+
+## Verification
+
+1. Mount a development component, submit a non-PHI prompt, and complete an
+   inference.
+2. Confirm the expected lifecycle events arrive in Nexalink's PostHog project.
+3. Inspect event payloads and verify they contain only the allowlisted
+   properties above.

package/dist/cli.d.ts

@@ -3,6 +3,8 @@ type CliIO = {
     stdout: Pick<NodeJS.WriteStream, "write">;
     stderr: Pick<NodeJS.WriteStream, "write">;
     env: NodeJS.ProcessEnv;
+    stdin?: NodeJS.ReadStream;
+    prompt?: (question: string) => Promise<string>;
 };
 export declare function runCareCompassCli(argv?: string[], io?: CliIO): Promise<1 | 0>;
 export {};