The Open Standard for Generative UI
/**
* Installation telemetry disclosure
*
* Sent during package postinstall unless telemetry is disabled:
* - A random installation ID and a salted SHA-256 project ID
* - Lang Core, Node.js, OS, architecture, and package-manager versions
* - CI provider category, Docker status, project-ID source category, and schema version
*
* The JSON payload contains no direct PII or application-user data. It never includes
* names, email addresses, usernames, raw Git origins, repository or project names,
* filesystem paths, branches, commits, credentials, environment values, source code,
* prompts, messages, generated output, component or tool definitions, errors, logs,
* stack traces, routes, or UI interactions. As with any HTTP request, the telemetry
* proxy and PostHog can observe the source IP as transport metadata; the script does
* not read it or add it to the payload.
*/
import { id as ciInfoId, isCI as ciInfoIsCI } from "ci-info";
import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { release } from "node:os";
import path from "node:path";
import {
createTelemetryStateIO,
loadTelemetryState,
saveTelemetryState,
type TelemetryStateIO,
} from "../../../../shared/telemetry/telemetry-state.cjs";
import {
getPostHogConfig,
isTelemetryDisabled,
isTruthyEnv,
normalizeProjectIdentity,
PROJECT_ID_SALT,
TELEMETRY_REQUEST_TIMEOUT_MS,
TELEMETRY_SCHEMA_VERSION,
} from "./shared";
export { isTelemetryDisabled, isTruthyEnv, normalizeProjectIdentity };
export const INSTALL_EVENT = "openui_lang_core_installed";
export type ProjectIdSource = "git_origin" | "repository_url" | "install_root";
export type PackageManagerName = "npm" | "pnpm" | "yarn" | "bun" | "unknown";
export interface InstallTelemetryProperties extends Record<string, unknown> {
telemetry_schema_version: number;
project_id: string;
project_id_source: ProjectIdSource;
lang_core_version: string;
node_version: string;
system_platform: string;
system_release: string;
system_architecture: string;
package_manager: PackageManagerName;
package_manager_version?: string;
ci: boolean;
ci_name?: string;
is_docker: boolean;
}
export interface InstallTelemetryPayload {
distinctId: string;
event: typeof INSTALL_EVENT;
properties: InstallTelemetryProperties;
}
export interface InstallTelemetryIO extends TelemetryStateIO {
cwd(): string;
getGitOrigin(projectRoot: string): string | undefined;
platform: string;
architecture: string;
release(): string;
isDocker(): boolean;
stdout(message: string): void;
stderr(message: string): void;
}
export type InstallTelemetrySender = (
payload: InstallTelemetryPayload,
env: NodeJS.ProcessEnv,
) => Promise<void>;
export interface RunInstallTelemetryOptions {
env?: NodeJS.ProcessEnv;
io?: Partial<InstallTelemetryIO>;
send?: InstallTelemetrySender;
}
export type RunInstallTelemetryResult =
| { status: "disabled" }
| { status: "debug"; payload: InstallTelemetryPayload }
| { status: "sent"; payload: InstallTelemetryPayload }
| { status: "failed"; payload?: InstallTelemetryPayload };
interface ProjectIdentity {
value: string;
source: ProjectIdSource;
}
const INSTALL_NOTICE =
"\n◆ OpenUI Lang Core sends pseudonymous installation telemetry to PostHog.\n" +
" It includes a salted project ID, OpenUI/Node/OS/package-manager metadata, and the network IP observed by PostHog.\n" +
" It does not send repository URLs, paths, source code, prompts, errors, or application data.\n" +
" Disable it with OPENUI_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.\n\n";
export function hashProjectIdentity(salt: string, projectIdentity: string): string {
return createHash("sha256").update(salt).update("\0").update(projectIdentity).digest("hex");
}
export function detectPackageManager(env: NodeJS.ProcessEnv): {
name: PackageManagerName;
version?: string;
} {
const userAgent = env["npm_config_user_agent"]?.trim() ?? "";
const match = userAgent.match(/^(npm|pnpm|yarn|bun)\/([^\s]+)/i);
if (!match) return { name: "unknown" };
const name = match[1]!.toLowerCase() as Exclude<PackageManagerName, "unknown">;
const version = match[2]!.slice(0, 64);
return version ? { name, version } : { name };
}
export async function runInstallTelemetry(
options: RunInstallTelemetryOptions = {},
): Promise<RunInstallTelemetryResult> {
const env = options.env ?? process.env;
if (isTelemetryDisabled(env)) return { status: "disabled" };
let payload: InstallTelemetryPayload | undefined;
try {
const io = createInstallTelemetryIO(options.io);
let telemetryState = loadTelemetryState({ env, io });
let { state, changed } = telemetryState;
if (state["langCorePostinstallNoticeShown"] !== true) {
io.stderr(INSTALL_NOTICE);
state = { ...state, langCorePostinstallNoticeShown: true };
changed = true;
}
if (changed) {
telemetryState = saveTelemetryState(telemetryState, state, io);
state = telemetryState.state;
}
const projectRoot = path.resolve(env["INIT_CWD"] || io.cwd());
const projectIdentity = resolveProjectIdentity(projectRoot, env, io);
const packageManager = detectPackageManager(env);
payload = {
distinctId: state.distinctId,
event: INSTALL_EVENT,
properties: {
telemetry_schema_version: TELEMETRY_SCHEMA_VERSION,
project_id: hashProjectIdentity(PROJECT_ID_SALT, projectIdentity.value),
project_id_source: projectIdentity.source,
lang_core_version:
env["OPENUI_LANG_CORE_PACKAGE_VERSION"] || env["npm_package_version"] || "unknown",
node_version: process.version,
system_platform: io.platform,
system_release: io.release(),
system_architecture: io.architecture,
package_manager: packageManager.name,
...(packageManager.version ? { package_manager_version: packageManager.version } : {}),
ci: ciInfoIsCI,
...(ciInfoId ? { ci_name: ciInfoId } : {}),
is_docker: io.isDocker(),
},
};
if (isTruthyEnv(env["OPENUI_TELEMETRY_DEBUG"])) {
io.stdout(`[OpenUI telemetry debug]\n${JSON.stringify(payload, null, 2)}\n`);
return { status: "debug", payload };
}
await (options.send ?? sendToPostHog)(payload, env);
return { status: "sent", payload };
} catch {
return { status: "failed", ...(payload ? { payload } : {}) };
}
}
function createInstallTelemetryIO(overrides: Partial<InstallTelemetryIO> = {}): InstallTelemetryIO {
return {
...createTelemetryStateIO(),
cwd: () => process.cwd(),
getGitOrigin: defaultGetGitOrigin,
platform: process.platform,
architecture: process.arch,
release,
isDocker: defaultIsDocker,
stdout: (message) => process.stdout.write(message),
stderr: (message) => process.stderr.write(message),
...overrides,
};
}
function resolveProjectIdentity(
projectRoot: string,
env: NodeJS.ProcessEnv,
io: InstallTelemetryIO,
): ProjectIdentity {
const gitOrigin = io.getGitOrigin(projectRoot)?.trim();
if (gitOrigin) {
return { value: normalizeProjectIdentity(gitOrigin), source: "git_origin" };
}
const repositoryUrl = env["REPOSITORY_URL"]?.trim();
if (repositoryUrl) {
return {
value: normalizeProjectIdentity(repositoryUrl),
source: "repository_url",
};
}
return { value: projectRoot, source: "install_root" };
}
function defaultGetGitOrigin(projectRoot: string): string | undefined {
try {
return execFileSync("git", ["-C", projectRoot, "config", "--get", "remote.origin.url"], {
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 1000,
}).trim();
} catch {
return undefined;
}
}
function defaultIsDocker(): boolean {
if (existsSync("/.dockerenv")) return true;
try {
return /docker|containerd|kubepods/i.test(readFileSync("/proc/self/cgroup", "utf8"));
} catch {
return false;
}
}
async function sendToPostHog(
payload: InstallTelemetryPayload,
env: NodeJS.ProcessEnv,
): Promise<void> {
const postHog = getPostHogConfig(env);
const response = await fetch(postHog.captureUrl, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
api_key: postHog.apiKey,
event: payload.event,
properties: {
distinct_id: payload.distinctId,
...payload.properties,
},
}),
signal: AbortSignal.timeout(TELEMETRY_REQUEST_TIMEOUT_MS),
});
if (!response.ok) throw new Error(`PostHog capture failed: ${response.status}`);
}