@velum-labs/routekit-telemetry-core 0.16.4 → 0.16.6

package/dist/index.d.ts

@@ -1,11 +1,17 @@
+export declare const TELEMETRY_CATEGORIES: readonly ["usage", "reliability", "adoption"];
+export type TelemetryCategory = (typeof TELEMETRY_CATEGORIES)[number];
+export type TelemetryCategories = Record<TelemetryCategory, boolean>;
+export declare const DEFAULT_TELEMETRY_CATEGORIES: Readonly<TelemetryCategories>;
 export type ConsentFile = {
     enabled: boolean;
+    categories?: Partial<TelemetryCategories>;
     installId?: string;
     decidedAt?: string;
 };
 export type ConsentDecision = {
     enabled: boolean;
     source: "do-not-track" | "env" | "config" | "default";
+    categories: TelemetryCategories;
     installId?: string;
 };
 export type ConsentOptions = {
@@ -15,28 +21,373 @@ export type ConsentOptions = {
     now?: () => Date;
     randomId?: () => string;
 };
-/** Fields shared by every CLI's anonymous command event. */
+/** @deprecated Use the event schema inventory instead. */
 export declare const CLI_COMMAND_TELEMETRY_FIELDS: readonly ["command", "cli_version", "os", "arch", "node_major", "duration_bucket", "exit_kind", "is_ci"];
 export type TelemetryFieldMap = Readonly<Record<string, readonly string[]>>;
-/**
- * Shared machine-readable consent status. Products may add operational fields
- * and render this metadata differently, but consent semantics stay identical.
- */
-export declare function telemetryStatusMetadata(decision: ConsentDecision, fields: TelemetryFieldMap): {
+export type TelemetryDestination = {
+    provider: "posthog";
+    host: string;
+    configured: boolean;
+};
+export type TelemetryStatus = {
     enabled: boolean;
     source: ConsentDecision["source"];
-    installId: string | null;
-    fields: TelemetryFieldMap;
+    categories: TelemetryCategories;
+    installIdPresent: boolean;
+    destination: TelemetryDestination;
+    schema: TelemetrySchemaInventory;
 };
 export declare function createConsentManager(options: ConsentOptions): {
     path: () => string;
     read: () => ConsentFile | undefined;
     resolve: (env?: NodeJS.ProcessEnv) => ConsentDecision;
     enable(): ConsentFile;
-    disable(): void;
+    disable(): ConsentFile;
+    setCategory(category: TelemetryCategory, enabled: boolean): ConsentFile;
+    resetIdentity(env?: NodeJS.ProcessEnv): ConsentFile | undefined;
     clear(): void;
 };
-export declare function durationBucket(ms: number): string;
+export declare const DURATION_BUCKETS: readonly ["<1s", "1-10s", "10-60s", "1-5m", "5-30m", ">30m"];
+export declare function durationBucket(ms: number): (typeof DURATION_BUCKETS)[number];
+export declare const TELEMETRY_OUTCOMES: readonly ["success", "error", "cancelled"];
+declare const OUTCOMES: readonly ["success", "error", "cancelled"];
+export declare const COMMAND_PATHS: readonly ["start", "stop", "status", "doctor", "usage", "usage.redeem", "leaderboard", "accounts.login", "accounts.add", "accounts.rename", "accounts.remove", "accounts.list", "accounts.status", "calls.inspect", "config.path", "config.show", "config.init", "config.edit", "config.import", "config.migrate", "providers.add", "providers.remove", "providers.status", "models.list", "models.info", "remote.add", "remote.install", "remote.list", "remote.show", "remote.use", "remote.remove", "peer.add", "peer.show", "peer.remove", "token.issue", "token.list", "token.revoke", "codex", "claude", "cursor", "opencode", "codex.install", "codex.uninstall", "claude.install", "claude.uninstall", "daemon.reload", "daemon.status", "daemon.auth.show", "daemon.service.install", "daemon.service.uninstall", "daemon.service.status", "daemon.logs", "daemon.start", "daemon.stop", "daemon.restart", "daemon.upgrade"];
+export declare const COMMAND_EXIT_KINDS: readonly ["success", "usage_error", "command_error", "cancelled"];
+export declare const COMMAND_TARGET_KINDS: readonly ["local", "remote", "peer"];
+export declare const COMMAND_OS_VALUES: readonly ["darwin", "linux", "win32", "other"];
+export declare const COMMAND_ARCH_VALUES: readonly ["arm64", "x64", "other"];
+export declare const COMMAND_NODE_MAJOR_VALUES: readonly ["22", "23", "24", "25", "26", "other"];
+export declare const PRODUCT_OPERATIONS: readonly ["config_update", "config_import", "config_reload", "provider_enable", "provider_disable", "account_enroll", "account_enroll_activate", "account_remove", "account_sync", "launcher_prepare", "token_issue", "token_revoke"];
+declare const COUNT_BUCKETS: readonly ["0", "1", "2-5", "6-20", ">20"];
+declare const TOKEN_BUCKETS: readonly ["0", "1-1k", "1k-10k", "10k-100k", ">100k", "unknown"];
+declare const RETRY_BUCKETS: readonly ["0", "1", "2", "3+"];
+declare const BILLING_MODES: readonly ["metered-api", "subscription", "upstream-managed", "unknown"];
+declare const DIALECTS: readonly ["openai-chat", "openai-responses", "anthropic-messages", "openai-embeddings"];
+declare const REQUEST_KINDS: readonly ["chat", "responses", "messages", "embeddings"];
+declare const PREFERENCE_ACTIONS: readonly ["master", "category", "identity-reset"];
+declare const DAEMON_ACTIONS: readonly ["started", "stopped", "restarted", "reloaded"];
+export declare const TELEMETRY_EVENT_DEFINITIONS: {
+    readonly "routekit.command_completed": {
+        readonly category: "adoption";
+        readonly properties: {
+            readonly command: {
+                readonly type: "string";
+                readonly maxLength: 64;
+                readonly values: readonly ["start", "stop", "status", "doctor", "usage", "usage.redeem", "leaderboard", "accounts.login", "accounts.add", "accounts.rename", "accounts.remove", "accounts.list", "accounts.status", "calls.inspect", "config.path", "config.show", "config.init", "config.edit", "config.import", "config.migrate", "providers.add", "providers.remove", "providers.status", "models.list", "models.info", "remote.add", "remote.install", "remote.list", "remote.show", "remote.use", "remote.remove", "peer.add", "peer.show", "peer.remove", "token.issue", "token.list", "token.revoke", "codex", "claude", "cursor", "opencode", "codex.install", "codex.uninstall", "claude.install", "claude.uninstall", "daemon.reload", "daemon.status", "daemon.auth.show", "daemon.service.install", "daemon.service.uninstall", "daemon.service.status", "daemon.logs", "daemon.start", "daemon.stop", "daemon.restart", "daemon.upgrade"];
+            };
+            readonly cli_version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+            };
+            readonly os: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["darwin", "linux", "win32", "other"];
+            };
+            readonly arch: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["arm64", "x64", "other"];
+            };
+            readonly node_major: {
+                readonly type: "string";
+                readonly maxLength: 8;
+                readonly values: readonly ["22", "23", "24", "25", "26", "other"];
+            };
+            readonly duration_bucket: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["<1s", "1-10s", "10-60s", "1-5m", "5-30m", ">30m"];
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["success", "error", "cancelled"];
+            };
+            readonly exit_kind: {
+                readonly type: "string";
+                readonly maxLength: 24;
+                readonly values: readonly ["success", "usage_error", "command_error", "cancelled"];
+            };
+            readonly is_ci: {
+                readonly type: "boolean";
+            };
+            readonly target_kind: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["local", "remote", "peer"];
+            };
+        };
+    };
+    readonly "routekit.product_operation_completed": {
+        readonly category: "adoption";
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly maxLength: 64;
+                readonly values: readonly ["config_update", "config_import", "config_reload", "provider_enable", "provider_disable", "account_enroll", "account_enroll_activate", "account_remove", "account_sync", "launcher_prepare", "token_issue", "token_revoke"];
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["success", "error", "cancelled"];
+            };
+            readonly duration_bucket: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["<1s", "1-10s", "10-60s", "1-5m", "5-30m", ">30m"];
+            };
+            readonly version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+            };
+        };
+    };
+    readonly "routekit.daemon_lifecycle": {
+        readonly category: "reliability";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["started", "stopped", "restarted", "reloaded"];
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["success", "error", "cancelled"];
+            };
+            readonly supervisor: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["systemd", "launchd", "detached", "unknown"];
+            };
+            readonly version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+            };
+        };
+    };
+    readonly "routekit.gateway_usage_summary": {
+        readonly category: "usage";
+        readonly properties: {
+            readonly provider: {
+                readonly type: "string";
+                readonly maxLength: 100;
+                readonly canonical: true;
+            };
+            readonly model: {
+                readonly type: "string";
+                readonly maxLength: 200;
+                readonly canonical: true;
+            };
+            readonly dialect: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly values: readonly ["openai-chat", "openai-responses", "anthropic-messages", "openai-embeddings"];
+            };
+            readonly request_kind: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["chat", "responses", "messages", "embeddings"];
+            };
+            readonly stream: {
+                readonly type: "boolean";
+            };
+            readonly billing_mode: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly values: readonly ["metered-api", "subscription", "upstream-managed", "unknown"];
+            };
+            readonly input_token_bucket: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["0", "1-1k", "1k-10k", "10k-100k", ">100k", "unknown"];
+            };
+            readonly output_token_bucket: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["0", "1-1k", "1k-10k", "10k-100k", ">100k", "unknown"];
+            };
+            readonly request_count_bucket: {
+                readonly type: "string";
+                readonly maxLength: 8;
+                readonly values: readonly ["0", "1", "2-5", "6-20", ">20"];
+            };
+            readonly version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+            };
+        };
+    };
+    readonly "routekit.gateway_reliability_summary": {
+        readonly category: "reliability";
+        readonly properties: {
+            readonly provider: {
+                readonly type: "string";
+                readonly maxLength: 100;
+                readonly canonical: true;
+            };
+            readonly model: {
+                readonly type: "string";
+                readonly maxLength: 200;
+                readonly canonical: true;
+            };
+            readonly dialect: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly values: readonly ["openai-chat", "openai-responses", "anthropic-messages", "openai-embeddings"];
+            };
+            readonly request_kind: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["chat", "responses", "messages", "embeddings"];
+            };
+            readonly stream: {
+                readonly type: "boolean";
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["success", "error", "cancelled"];
+            };
+            readonly latency_bucket: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["<1s", "1-10s", "10-60s", "1-5m", "5-30m", ">30m"];
+            };
+            readonly retry_bucket: {
+                readonly type: "string";
+                readonly maxLength: 8;
+                readonly values: readonly ["0", "1", "2", "3+"];
+            };
+            readonly failover: {
+                readonly type: "boolean";
+            };
+            readonly request_count_bucket: {
+                readonly type: "string";
+                readonly maxLength: 8;
+                readonly values: readonly ["0", "1", "2-5", "6-20", ">20"];
+            };
+            readonly version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+            };
+        };
+    };
+    readonly "routekit.telemetry_preference_changed": {
+        readonly category: "adoption";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly values: readonly ["master", "category", "identity-reset"];
+            };
+            readonly category: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["usage", "reliability", "adoption"];
+                readonly required: false;
+            };
+            readonly enabled: {
+                readonly type: "boolean";
+            };
+            readonly source: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["do-not-track", "env", "config", "default"];
+            };
+            readonly version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+            };
+        };
+    };
+};
+export type TelemetryEventName = keyof typeof TELEMETRY_EVENT_DEFINITIONS;
+export type CommandCompletedProperties = {
+    command: (typeof COMMAND_PATHS)[number];
+    cli_version: string;
+    os: (typeof COMMAND_OS_VALUES)[number];
+    arch: (typeof COMMAND_ARCH_VALUES)[number];
+    node_major: (typeof COMMAND_NODE_MAJOR_VALUES)[number];
+    duration_bucket: (typeof DURATION_BUCKETS)[number];
+    outcome: (typeof OUTCOMES)[number];
+    exit_kind: (typeof COMMAND_EXIT_KINDS)[number];
+    is_ci: boolean;
+    target_kind: (typeof COMMAND_TARGET_KINDS)[number];
+};
+export type TelemetryEventProperties = {
+    "routekit.command_completed": CommandCompletedProperties;
+    "routekit.product_operation_completed": {
+        operation: (typeof PRODUCT_OPERATIONS)[number];
+        outcome: (typeof OUTCOMES)[number];
+        duration_bucket: (typeof DURATION_BUCKETS)[number];
+        version: string;
+    };
+    "routekit.daemon_lifecycle": {
+        action: (typeof DAEMON_ACTIONS)[number];
+        outcome: (typeof OUTCOMES)[number];
+        supervisor: "systemd" | "launchd" | "detached" | "unknown";
+        version: string;
+    };
+    /** Gateway summaries are the only families permitted to carry canonical provider/model identifiers. */
+    "routekit.gateway_usage_summary": {
+        provider: string;
+        model: string;
+        dialect: (typeof DIALECTS)[number];
+        request_kind: (typeof REQUEST_KINDS)[number];
+        stream: boolean;
+        billing_mode: (typeof BILLING_MODES)[number];
+        input_token_bucket: (typeof TOKEN_BUCKETS)[number];
+        output_token_bucket: (typeof TOKEN_BUCKETS)[number];
+        request_count_bucket: (typeof COUNT_BUCKETS)[number];
+        version: string;
+    };
+    "routekit.gateway_reliability_summary": {
+        provider: string;
+        model: string;
+        dialect: (typeof DIALECTS)[number];
+        request_kind: (typeof REQUEST_KINDS)[number];
+        stream: boolean;
+        outcome: (typeof OUTCOMES)[number];
+        latency_bucket: (typeof DURATION_BUCKETS)[number];
+        retry_bucket: (typeof RETRY_BUCKETS)[number];
+        failover: boolean;
+        request_count_bucket: (typeof COUNT_BUCKETS)[number];
+        version: string;
+    };
+    "routekit.telemetry_preference_changed": {
+        action: (typeof PREFERENCE_ACTIONS)[number];
+        category?: TelemetryCategory;
+        enabled: boolean;
+        source: ConsentDecision["source"];
+        version: string;
+    };
+};
+export type TelemetrySchemaInventory = Readonly<Record<TelemetryEventName, {
+    category: TelemetryCategory;
+    fields: readonly string[];
+}>>;
+export declare const TELEMETRY_SCHEMA_VERSION = 1;
+export declare const TELEMETRY_SCHEMA_INVENTORY: TelemetrySchemaInventory;
+export type BuiltTelemetryEvent = {
+    event: TelemetryEventName;
+    category: TelemetryCategory;
+    properties: Record<string, unknown> & {
+        schema_version: 1;
+        $process_person_profile: false;
+        $ip: null;
+    };
+};
+export declare function buildTelemetryEvent<N extends TelemetryEventName>(name: N, source: TelemetryEventProperties[N]): BuiltTelemetryEvent;
+export declare function telemetryStatusMetadata(decision: ConsentDecision, destinationOrFields: TelemetryDestination | TelemetryFieldMap, schema?: TelemetrySchemaInventory): TelemetryStatus | {
+    enabled: boolean;
+    source: ConsentDecision["source"];
+    installId: string | null;
+    fields: TelemetryFieldMap;
+};
+/** @deprecated Prefer buildTelemetryEvent, which rejects unknown properties. */
 export declare function allowlistedProperties(source: Record<string, unknown>, allow: readonly string[]): Record<string, unknown>;
 export declare function anonymousEventProperties(properties: Record<string, unknown>): Record<string, unknown>;
 export declare function boundedShutdown(shutdown: () => Promise<unknown>, timeoutMs?: number): Promise<void>;
+export {};

package/dist/index.js

@@ -2,7 +2,13 @@ import { randomUUID } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { dirname } from "node:path";
 import { writeFileAtomic } from "@velum-labs/routekit-runtime";
-/** Fields shared by every CLI's anonymous command event. */
+export const TELEMETRY_CATEGORIES = ["usage", "reliability", "adoption"];
+export const DEFAULT_TELEMETRY_CATEGORIES = Object.freeze({
+    usage: true,
+    reliability: true,
+    adoption: true
+});
+/** @deprecated Use the event schema inventory instead. */
 export const CLI_COMMAND_TELEMETRY_FIELDS = [
     "command",
     "cli_version",
@@ -13,68 +19,94 @@ export const CLI_COMMAND_TELEMETRY_FIELDS = [
     "exit_kind",
     "is_ci"
 ];
-/**
- * Shared machine-readable consent status. Products may add operational fields
- * and render this metadata differently, but consent semantics stay identical.
- */
-export function telemetryStatusMetadata(decision, fields) {
+const truthy = (value) => value !== undefined && ["1", "true", "on", "yes"].includes(value.toLowerCase());
+const falsy = (value) => value !== undefined && ["0", "false", "off", "no"].includes(value.toLowerCase());
+function categories(value) {
     return {
-        enabled: decision.enabled,
-        source: decision.source,
-        installId: decision.installId ?? null,
-        fields
+        usage: value?.usage ?? DEFAULT_TELEMETRY_CATEGORIES.usage,
+        reliability: value?.reliability ?? DEFAULT_TELEMETRY_CATEGORIES.reliability,
+        adoption: value?.adoption ?? DEFAULT_TELEMETRY_CATEGORIES.adoption
     };
 }
-const truthy = (value) => value !== undefined && ["1", "true", "on", "yes"].includes(value.toLowerCase());
-const falsy = (value) => value !== undefined && ["0", "false", "off", "no"].includes(value.toLowerCase());
 export function createConsentManager(options) {
+    let ephemeralInstallId;
+    const nextId = () => (options.randomId ?? randomUUID)();
+    const decidedAt = () => (options.now ?? (() => new Date()))().toISOString();
     const read = () => {
         const path = options.path();
         if (!existsSync(path))
             return undefined;
         try {
             const parsed = JSON.parse(readFileSync(path, "utf8"));
-            if (typeof parsed === "object" &&
-                parsed !== null &&
-                typeof parsed.enabled === "boolean") {
-                return parsed;
+            if (typeof parsed !== "object" || parsed === null)
+                return undefined;
+            const candidate = parsed;
+            if (typeof candidate.enabled !== "boolean")
+                return undefined;
+            const normalized = {
+                enabled: candidate.enabled,
+                categories: categories(candidate.categories),
+                ...(candidate.decidedAt !== undefined ? { decidedAt: candidate.decidedAt } : {})
+            };
+            if (candidate.enabled &&
+                typeof candidate.installId === "string" &&
+                candidate.installId.length > 0) {
+                normalized.installId = candidate.installId;
             }
+            return normalized;
         }
         catch {
-            // Corrupt consent is undecided and therefore disabled.
+            return undefined;
         }
-        return undefined;
     };
     const write = (value) => {
         const path = options.path();
+        const normalized = {
+            enabled: value.enabled,
+            categories: categories(value.categories),
+            ...(value.enabled && value.installId !== undefined ? { installId: value.installId } : {}),
+            ...(value.decidedAt !== undefined ? { decidedAt: value.decidedAt } : {})
+        };
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         chmodSync(dirname(path), 0o700);
-        writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+        writeFileAtomic(path, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
         chmodSync(path, 0o600);
     };
+    const stableId = (file) => {
+        if (file?.enabled && file.installId !== undefined)
+            return file.installId;
+        ephemeralInstallId ??= nextId();
+        return ephemeralInstallId;
+    };
     const resolve = (env = process.env) => {
+        const file = read();
+        const selectedCategories = categories(file?.categories);
         if (truthy(env[options.doNotTrackVariable ?? "DO_NOT_TRACK"])) {
-            return { enabled: false, source: "do-not-track" };
+            return { enabled: false, source: "do-not-track", categories: selectedCategories };
         }
         const override = env[options.environmentVariable];
-        if (falsy(override))
-            return { enabled: false, source: "env" };
-        const file = read();
+        if (falsy(override)) {
+            return { enabled: false, source: "env", categories: selectedCategories };
+        }
         if (truthy(override)) {
             return {
                 enabled: true,
                 source: "env",
-                installId: file?.installId ?? (options.randomId ?? randomUUID)()
+                categories: selectedCategories,
+                installId: stableId(file)
             };
         }
         if (file !== undefined) {
+            if (!file.enabled)
+                return { enabled: false, source: "config", categories: selectedCategories };
             return {
-                enabled: file.enabled,
+                enabled: true,
                 source: "config",
-                ...(file.installId !== undefined ? { installId: file.installId } : {})
+                categories: selectedCategories,
+                installId: stableId(file)
             };
         }
-        return { enabled: false, source: "default" };
+        return { enabled: false, source: "default", categories: selectedCategories };
     };
     return {
         path: options.path,
@@ -84,23 +116,75 @@ export function createConsentManager(options) {
             const existing = read();
             const file = {
                 enabled: true,
-                installId: existing?.installId ?? (options.randomId ?? randomUUID)(),
-                decidedAt: (options.now ?? (() => new Date()))().toISOString()
+                categories: categories(existing?.categories),
+                installId: existing?.enabled ? (existing.installId ?? nextId()) : nextId(),
+                decidedAt: decidedAt()
             };
+            ephemeralInstallId = file.installId;
             write(file);
             return file;
         },
         disable() {
-            write({
+            ephemeralInstallId = undefined;
+            const file = {
                 enabled: false,
-                decidedAt: (options.now ?? (() => new Date()))().toISOString()
-            });
+                categories: categories(read()?.categories),
+                decidedAt: decidedAt()
+            };
+            write(file);
+            return file;
+        },
+        setCategory(category, enabled) {
+            const existing = read();
+            const file = {
+                enabled: existing?.enabled ?? false,
+                categories: { ...categories(existing?.categories), [category]: enabled },
+                ...(existing?.enabled && existing.installId !== undefined
+                    ? { installId: existing.installId }
+                    : {}),
+                decidedAt: decidedAt()
+            };
+            write(file);
+            return file;
+        },
+        resetIdentity(env = process.env) {
+            const decision = resolve(env);
+            if (!decision.enabled) {
+                ephemeralInstallId = undefined;
+                const existing = read();
+                if (existing?.enabled) {
+                    const disabled = {
+                        enabled: false,
+                        categories: categories(existing.categories),
+                        decidedAt: decidedAt()
+                    };
+                    write(disabled);
+                    return disabled;
+                }
+                return existing;
+            }
+            const installId = nextId();
+            ephemeralInstallId = installId;
+            const existing = read();
+            if (existing?.enabled) {
+                const file = {
+                    enabled: true,
+                    categories: categories(existing.categories),
+                    installId,
+                    decidedAt: decidedAt()
+                };
+                write(file);
+                return file;
+            }
+            return undefined;
         },
         clear() {
+            ephemeralInstallId = undefined;
             rmSync(options.path(), { force: true });
         }
     };
 }
+export const DURATION_BUCKETS = ["<1s", "1-10s", "10-60s", "1-5m", "5-30m", ">30m"];
 export function durationBucket(ms) {
     if (ms < 1_000)
         return "<1s";
@@ -114,12 +198,269 @@ export function durationBucket(ms) {
         return "5-30m";
     return ">30m";
 }
+export const TELEMETRY_OUTCOMES = ["success", "error", "cancelled"];
+const OUTCOMES = TELEMETRY_OUTCOMES;
+export const COMMAND_PATHS = [
+    "start",
+    "stop",
+    "status",
+    "doctor",
+    "usage",
+    "usage.redeem",
+    "leaderboard",
+    "accounts.login",
+    "accounts.add",
+    "accounts.rename",
+    "accounts.remove",
+    "accounts.list",
+    "accounts.status",
+    "calls.inspect",
+    "config.path",
+    "config.show",
+    "config.init",
+    "config.edit",
+    "config.import",
+    "config.migrate",
+    "providers.add",
+    "providers.remove",
+    "providers.status",
+    "models.list",
+    "models.info",
+    "remote.add",
+    "remote.install",
+    "remote.list",
+    "remote.show",
+    "remote.use",
+    "remote.remove",
+    "peer.add",
+    "peer.show",
+    "peer.remove",
+    "token.issue",
+    "token.list",
+    "token.revoke",
+    "codex",
+    "claude",
+    "cursor",
+    "opencode",
+    "codex.install",
+    "codex.uninstall",
+    "claude.install",
+    "claude.uninstall",
+    "daemon.reload",
+    "daemon.status",
+    "daemon.auth.show",
+    "daemon.service.install",
+    "daemon.service.uninstall",
+    "daemon.service.status",
+    "daemon.logs",
+    "daemon.start",
+    "daemon.stop",
+    "daemon.restart",
+    "daemon.upgrade"
+];
+export const COMMAND_EXIT_KINDS = ["success", "usage_error", "command_error", "cancelled"];
+export const COMMAND_TARGET_KINDS = ["local", "remote", "peer"];
+export const COMMAND_OS_VALUES = ["darwin", "linux", "win32", "other"];
+export const COMMAND_ARCH_VALUES = ["arm64", "x64", "other"];
+export const COMMAND_NODE_MAJOR_VALUES = ["22", "23", "24", "25", "26", "other"];
+export const PRODUCT_OPERATIONS = [
+    "config_update",
+    "config_import",
+    "config_reload",
+    "provider_enable",
+    "provider_disable",
+    "account_enroll",
+    "account_enroll_activate",
+    "account_remove",
+    "account_sync",
+    "launcher_prepare",
+    "token_issue",
+    "token_revoke"
+];
+const COUNT_BUCKETS = ["0", "1", "2-5", "6-20", ">20"];
+const TOKEN_BUCKETS = ["0", "1-1k", "1k-10k", "10k-100k", ">100k", "unknown"];
+const RETRY_BUCKETS = ["0", "1", "2", "3+"];
+const BILLING_MODES = ["metered-api", "subscription", "upstream-managed", "unknown"];
+const DIALECTS = [
+    "openai-chat",
+    "openai-responses",
+    "anthropic-messages",
+    "openai-embeddings"
+];
+const REQUEST_KINDS = ["chat", "responses", "messages", "embeddings"];
+const PREFERENCE_ACTIONS = ["master", "category", "identity-reset"];
+const DAEMON_ACTIONS = ["started", "stopped", "restarted", "reloaded"];
+export const TELEMETRY_EVENT_DEFINITIONS = {
+    "routekit.command_completed": {
+        category: "adoption",
+        properties: {
+            command: { type: "string", maxLength: 64, values: COMMAND_PATHS },
+            cli_version: { type: "string", maxLength: 32 },
+            os: { type: "string", maxLength: 16, values: COMMAND_OS_VALUES },
+            arch: { type: "string", maxLength: 16, values: COMMAND_ARCH_VALUES },
+            node_major: { type: "string", maxLength: 8, values: COMMAND_NODE_MAJOR_VALUES },
+            duration_bucket: { type: "string", maxLength: 16, values: DURATION_BUCKETS },
+            outcome: { type: "string", maxLength: 16, values: OUTCOMES },
+            exit_kind: { type: "string", maxLength: 24, values: COMMAND_EXIT_KINDS },
+            is_ci: { type: "boolean" },
+            target_kind: { type: "string", maxLength: 16, values: COMMAND_TARGET_KINDS }
+        }
+    },
+    "routekit.product_operation_completed": {
+        category: "adoption",
+        properties: {
+            operation: { type: "string", maxLength: 64, values: PRODUCT_OPERATIONS },
+            outcome: { type: "string", maxLength: 16, values: OUTCOMES },
+            duration_bucket: { type: "string", maxLength: 16, values: DURATION_BUCKETS },
+            version: { type: "string", maxLength: 32 }
+        }
+    },
+    "routekit.daemon_lifecycle": {
+        category: "reliability",
+        properties: {
+            action: { type: "string", maxLength: 16, values: DAEMON_ACTIONS },
+            outcome: { type: "string", maxLength: 16, values: OUTCOMES },
+            supervisor: {
+                type: "string",
+                maxLength: 16,
+                values: ["systemd", "launchd", "detached", "unknown"]
+            },
+            version: { type: "string", maxLength: 32 }
+        }
+    },
+    "routekit.gateway_usage_summary": {
+        category: "usage",
+        properties: {
+            provider: { type: "string", maxLength: 100, canonical: true },
+            model: { type: "string", maxLength: 200, canonical: true },
+            dialect: { type: "string", maxLength: 32, values: DIALECTS },
+            request_kind: { type: "string", maxLength: 16, values: REQUEST_KINDS },
+            stream: { type: "boolean" },
+            billing_mode: { type: "string", maxLength: 32, values: BILLING_MODES },
+            input_token_bucket: { type: "string", maxLength: 16, values: TOKEN_BUCKETS },
+            output_token_bucket: { type: "string", maxLength: 16, values: TOKEN_BUCKETS },
+            request_count_bucket: { type: "string", maxLength: 8, values: COUNT_BUCKETS },
+            version: { type: "string", maxLength: 32 }
+        }
+    },
+    "routekit.gateway_reliability_summary": {
+        category: "reliability",
+        properties: {
+            provider: { type: "string", maxLength: 100, canonical: true },
+            model: { type: "string", maxLength: 200, canonical: true },
+            dialect: { type: "string", maxLength: 32, values: DIALECTS },
+            request_kind: { type: "string", maxLength: 16, values: REQUEST_KINDS },
+            stream: { type: "boolean" },
+            outcome: { type: "string", maxLength: 16, values: OUTCOMES },
+            latency_bucket: { type: "string", maxLength: 16, values: DURATION_BUCKETS },
+            retry_bucket: { type: "string", maxLength: 8, values: RETRY_BUCKETS },
+            failover: { type: "boolean" },
+            request_count_bucket: { type: "string", maxLength: 8, values: COUNT_BUCKETS },
+            version: { type: "string", maxLength: 32 }
+        }
+    },
+    "routekit.telemetry_preference_changed": {
+        category: "adoption",
+        properties: {
+            action: { type: "string", maxLength: 32, values: PREFERENCE_ACTIONS },
+            category: { type: "string", maxLength: 16, values: TELEMETRY_CATEGORIES, required: false },
+            enabled: { type: "boolean" },
+            source: {
+                type: "string",
+                maxLength: 16,
+                values: ["do-not-track", "env", "config", "default"]
+            },
+            version: { type: "string", maxLength: 32 }
+        }
+    }
+};
+export const TELEMETRY_SCHEMA_VERSION = 1;
+export const TELEMETRY_SCHEMA_INVENTORY = Object.freeze(Object.fromEntries(Object.entries(TELEMETRY_EVENT_DEFINITIONS).map(([name, definition]) => [
+    name,
+    { category: definition.category, fields: Object.keys(definition.properties) }
+])));
+const FORBIDDEN_KEYS = /(?:^|_)(?:id|label|path|body|prompt|response|error|cost|usage|timing|token|secret|key)(?:$|_)/i;
+const FORBIDDEN_VALUE = /(?:bearer\s+|sk-[a-z0-9]|-----begin [a-z ]+private key-----|(?:^|\s)\/(?:users|home|var|tmp)\/)/i;
+const CANONICAL_ID = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/;
+export function buildTelemetryEvent(name, source) {
+    if (!Object.hasOwn(TELEMETRY_EVENT_DEFINITIONS, name)) {
+        throw new TypeError(`unknown telemetry event: ${name}`);
+    }
+    const eventName = name;
+    const definition = TELEMETRY_EVENT_DEFINITIONS[eventName];
+    const input = source;
+    for (const key of Object.keys(input)) {
+        if (definition.properties[key] === undefined) {
+            const sensitive = FORBIDDEN_KEYS.test(key) ? " sensitive" : "";
+            throw new TypeError(`unknown${sensitive} telemetry property ${key} for ${name}`);
+        }
+    }
+    for (const [key, validator] of Object.entries(definition.properties)) {
+        if (validator.required !== false && input[key] === undefined) {
+            throw new TypeError(`missing telemetry property ${key} for ${name}`);
+        }
+    }
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        const validator = definition.properties[key];
+        if (validator === undefined) {
+            const sensitive = FORBIDDEN_KEYS.test(key) ? " sensitive" : "";
+            throw new TypeError(`unknown${sensitive} telemetry property ${key} for ${name}`);
+        }
+        if (validator.type === "boolean") {
+            if (typeof value !== "boolean")
+                throw new TypeError(`invalid telemetry property ${key}`);
+        }
+        else {
+            if (typeof value !== "string" || value.length === 0 || value.length > validator.maxLength) {
+                throw new TypeError(`invalid telemetry property ${key}`);
+            }
+            if (validator.values !== undefined && !validator.values.includes(value)) {
+                throw new TypeError(`invalid telemetry property ${key}`);
+            }
+            if (validator.canonical && !CANONICAL_ID.test(value)) {
+                throw new TypeError(`invalid telemetry property ${key}`);
+            }
+            if (FORBIDDEN_VALUE.test(value))
+                throw new TypeError(`forbidden telemetry value for ${key}`);
+        }
+        output[key] = value;
+    }
+    return {
+        event: eventName,
+        category: definition.category,
+        properties: anonymousEventProperties({
+            ...output,
+            schema_version: TELEMETRY_SCHEMA_VERSION
+        })
+    };
+}
+export function telemetryStatusMetadata(decision, destinationOrFields, schema = TELEMETRY_SCHEMA_INVENTORY) {
+    if (!("provider" in destinationOrFields) ||
+        !("host" in destinationOrFields) ||
+        !("configured" in destinationOrFields)) {
+        return {
+            enabled: decision.enabled,
+            source: decision.source,
+            installId: decision.installId ?? null,
+            fields: destinationOrFields
+        };
+    }
+    return {
+        enabled: decision.enabled,
+        source: decision.source,
+        categories: decision.categories,
+        installIdPresent: decision.installId !== undefined,
+        destination: destinationOrFields,
+        schema
+    };
+}
+/** @deprecated Prefer buildTelemetryEvent, which rejects unknown properties. */
 export function allowlistedProperties(source, allow) {
     const properties = {};
-    for (const key of allow) {
+    for (const key of allow)
         if (source[key] !== undefined)
             properties[key] = source[key];
-    }
     return properties;
 }
 export function anonymousEventProperties(properties) {

package/dist/test/telemetry-core.test.js

@@ -1,50 +1,196 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { anonymousEventProperties, CLI_COMMAND_TELEMETRY_FIELDS, createConsentManager, telemetryStatusMetadata } from "../index.js";
-test("consent is parameterized and anonymous events redact network identity", () => {
+import { buildTelemetryEvent, createConsentManager, DEFAULT_TELEMETRY_CATEGORIES, TELEMETRY_SCHEMA_INVENTORY, telemetryStatusMetadata } from "../index.js";
+function fixture(ids = ["id-1", "id-2", "id-3"]) {
     const root = mkdtempSync(join(tmpdir(), "routekit-telemetry-"));
+    let index = 0;
+    const manager = createConsentManager({
+        path: () => join(root, "consent.json"),
+        environmentVariable: "ROUTEKIT_TELEMETRY",
+        randomId: () => ids[index++] ?? `id-${index}`,
+        now: () => new Date("2026-01-01T00:00:00.000Z")
+    });
+    return { root, path: join(root, "consent.json"), manager };
+}
+test("consent defaults off and migrates old files logically", () => {
+    const { root, path, manager } = fixture();
     try {
-        const manager = createConsentManager({
-            path: () => join(root, "consent.json"),
-            environmentVariable: "EXAMPLE_TELEMETRY",
-            randomId: () => "install-id",
-            now: () => new Date("2026-01-01T00:00:00.000Z")
+        assert.deepEqual(manager.resolve({}), {
+            enabled: false,
+            source: "default",
+            categories: DEFAULT_TELEMETRY_CATEGORIES
         });
-        assert.equal(manager.resolve({}).enabled, false);
-        assert.equal(manager.enable().installId, "install-id");
-        assert.equal(manager.resolve({}).enabled, true);
-        assert.deepEqual(anonymousEventProperties({ command: "test" }), {
-            command: "test",
-            $process_person_profile: false,
-            $ip: null
+        writeFileSync(path, JSON.stringify({ enabled: true, installId: "legacy" }));
+        assert.deepEqual(manager.resolve({}), {
+            enabled: true,
+            source: "config",
+            categories: DEFAULT_TELEMETRY_CATEGORIES,
+            installId: "legacy"
         });
+        writeFileSync(path, JSON.stringify({ enabled: false, installId: "must-disappear" }));
+        assert.equal(manager.read()?.installId, undefined);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("consent truthy/falsy matrix, DNT precedence, corruption, and identity stability", () => {
+    const { root, path, manager } = fixture();
+    try {
+        manager.enable();
+        for (const value of ["1", "true", "TRUE", "on", "yes"]) {
+            assert.equal(manager.resolve({ ROUTEKIT_TELEMETRY: value }).enabled, true, value);
+        }
+        for (const value of ["0", "false", "FALSE", "off", "no"]) {
+            const decision = manager.resolve({ ROUTEKIT_TELEMETRY: value });
+            assert.equal(decision.enabled, false, value);
+            assert.equal(decision.source, "env");
+        }
+        for (const value of ["1", "true", "on", "yes"]) {
+            const decision = manager.resolve({ ROUTEKIT_TELEMETRY: "1", DO_NOT_TRACK: value });
+            assert.equal(decision.enabled, false, value);
+            assert.equal(decision.source, "do-not-track");
+        }
+        manager.disable();
+        const first = manager.resolve({ ROUTEKIT_TELEMETRY: "yes" });
+        const second = manager.resolve({ ROUTEKIT_TELEMETRY: "yes" });
+        assert.equal(first.installId, second.installId);
+        writeFileSync(path, "{broken json");
+        assert.equal(manager.resolve({}).source, "default");
+        assert.equal(manager.resolve({}).enabled, false);
     }
     finally {
         rmSync(root, { recursive: true, force: true });
     }
 });
-test("shared CLI telemetry metadata supports product-specific fields and presentation", () => {
-    const fields = {
-        "cli.command": [...CLI_COMMAND_TELEMETRY_FIELDS, "product_mode"]
-    };
-    assert.deepEqual(fields["cli.command"], [
-        "command",
-        "cli_version",
-        "os",
-        "arch",
-        "node_major",
-        "duration_bucket",
-        "exit_kind",
-        "is_ci",
-        "product_mode"
-    ]);
-    assert.deepEqual(telemetryStatusMetadata({ enabled: false, source: "do-not-track" }, fields), {
-        enabled: false,
-        source: "do-not-track",
-        installId: null,
-        fields
+test("category changes, disable, re-enable, and identity reset preserve invariants", () => {
+    const { root, path, manager } = fixture();
+    try {
+        assert.equal(manager.enable().installId, "id-1");
+        manager.setCategory("usage", false);
+        assert.equal(manager.resolve({}).categories.usage, false);
+        assert.equal(manager.resetIdentity({})?.installId, "id-2");
+        manager.disable();
+        assert.equal(manager.resolve({}).installId, undefined);
+        assert.equal(JSON.parse(readFileSync(path, "utf8")).installId, undefined);
+        assert.deepEqual(manager.resetIdentity({}), manager.read());
+        assert.equal(manager.enable().installId, "id-3");
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("event builder validates exact schemas and privacy canaries", () => {
+    assert.deepEqual(buildTelemetryEvent("routekit.gateway_usage_summary", {
+        provider: "openai",
+        model: "openai/gpt-5.2",
+        dialect: "openai-responses",
+        request_kind: "responses",
+        stream: true,
+        billing_mode: "metered-api",
+        input_token_bucket: "1k-10k",
+        output_token_bucket: "1-1k",
+        request_count_bucket: "1",
+        version: "0.17.0"
+    }).properties.$ip, null);
+    assert.equal(buildTelemetryEvent("routekit.gateway_reliability_summary", {
+        provider: "openai",
+        model: "openai/gpt-5.2",
+        dialect: "openai-responses",
+        request_kind: "responses",
+        stream: true,
+        outcome: "success",
+        latency_bucket: "1-10s",
+        retry_bucket: "1",
+        failover: false,
+        request_count_bucket: "1",
+        version: "0.17.0"
+    }).category, "reliability");
+    assert.throws(() => buildTelemetryEvent("routekit.unknown", {}), /unknown telemetry event/);
+    assert.throws(() => buildTelemetryEvent("routekit.command_completed", { path: "/tmp/a" }), /sensitive/);
+    assert.throws(() => buildTelemetryEvent("routekit.command_completed", { command: "Bearer secret" }), /forbidden|missing/);
+    assert.throws(() => buildTelemetryEvent("routekit.gateway_usage_summary", { provider: "open ai" }), /invalid|missing/);
+    assert.throws(() => buildTelemetryEvent("routekit.gateway_usage_summary", { latency_ms: 12 }), /unknown/);
+});
+test("schema inventory exposes exact category-truthful event families and fields", () => {
+    assert.deepEqual(TELEMETRY_SCHEMA_INVENTORY, {
+        "routekit.command_completed": {
+            category: "adoption",
+            fields: [
+                "command",
+                "cli_version",
+                "os",
+                "arch",
+                "node_major",
+                "duration_bucket",
+                "outcome",
+                "exit_kind",
+                "is_ci",
+                "target_kind"
+            ]
+        },
+        "routekit.product_operation_completed": {
+            category: "adoption",
+            fields: ["operation", "outcome", "duration_bucket", "version"]
+        },
+        "routekit.daemon_lifecycle": {
+            category: "reliability",
+            fields: ["action", "outcome", "supervisor", "version"]
+        },
+        "routekit.gateway_usage_summary": {
+            category: "usage",
+            fields: [
+                "provider",
+                "model",
+                "dialect",
+                "request_kind",
+                "stream",
+                "billing_mode",
+                "input_token_bucket",
+                "output_token_bucket",
+                "request_count_bucket",
+                "version"
+            ]
+        },
+        "routekit.gateway_reliability_summary": {
+            category: "reliability",
+            fields: [
+                "provider",
+                "model",
+                "dialect",
+                "request_kind",
+                "stream",
+                "outcome",
+                "latency_bucket",
+                "retry_bucket",
+                "failover",
+                "request_count_bucket",
+                "version"
+            ]
+        },
+        "routekit.telemetry_preference_changed": {
+            category: "adoption",
+            fields: ["action", "category", "enabled", "source", "version"]
+        }
+    });
+});
+test("status exposes presence and exact schema without identity", () => {
+    const status = telemetryStatusMetadata({
+        enabled: true,
+        source: "config",
+        categories: { usage: true, reliability: false, adoption: true },
+        installId: "private"
+    }, { provider: "posthog", host: "https://us.i.posthog.com", configured: false });
+    assert.deepEqual(status, {
+        enabled: true,
+        source: "config",
+        categories: { usage: true, reliability: false, adoption: true },
+        installIdPresent: true,
+        destination: { provider: "posthog", host: "https://us.i.posthog.com", configured: false },
+        schema: TELEMETRY_SCHEMA_INVENTORY
     });
+    assert.equal("installId" in status, false);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-telemetry-core",
   "private": false,
-  "version": "0.16.4",
+  "version": "0.16.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -26,7 +26,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@velum-labs/routekit-runtime": "0.16.4"
+    "@velum-labs/routekit-runtime": "0.16.6"
   },
   "keywords": [
     "routekit",