@opendatalabs/connect 0.12.1 → 0.13.0

package/dist/cli/telemetry.js

@@ -3,13 +3,14 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { getTelemetryOutboxDir, readCliConfig, updateCliConfig, } from "../core/index.js";
-const TELEMETRY_ENDPOINT = "https://telemetry.opendatalabs.com/v1/cli/events";
+import { TELEMETRY_ENDPOINT, TELEMETRY_EVENT_VERSION, TELEMETRY_PRODUCER_NAME, } from "./telemetry-contract.js";
+// ── Config ──────────────────────────────────────────────────────────────────
 const MAX_EVENTS_PER_BATCH = 100;
 const MAX_BATCH_BYTES = 64 * 1024;
 const MAX_FILES_PER_FLUSH = 10;
 const FLUSH_TIMEOUT_MS = 1500;
-const EVENT_VERSION = 1;
 let activeSession = null;
+// ── Helpers ─────────────────────────────────────────────────────────────────
 function randomId(prefix) {
     return `${prefix}_${crypto.randomUUID()}`;
 }
@@ -19,127 +20,74 @@ function nowIso() {
 function getEndpoint() {
     return process.env.VANA_TELEMETRY_URL?.trim() || TELEMETRY_ENDPOINT;
 }
-function getInteractive(options) {
-    return Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.noInput);
+function detectOs() {
+    const platform = process.platform;
+    if (platform === "linux")
+        return "linux";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "win32")
+        return "windows";
+    return "linux"; // fallback
 }
-function sanitizeMetadata(metadata) {
-    if (!metadata) {
-        return null;
-    }
-    return Object.fromEntries(Object.entries(metadata).slice(0, 16));
+function detectArch() {
+    const arch = os.arch();
+    if (arch === "arm64")
+        return "arm64";
+    return "x86_64";
 }
-function countScopeResults(scopeResults) {
-    return {
-        storedScopeCount: scopeResults?.filter((item) => item.status === "stored").length ?? null,
-        failedScopeCount: scopeResults?.filter((item) => item.status === "failed").length ?? null,
-    };
+function makeHostPlatform(osName, arch) {
+    return `${osName}-${arch}`;
 }
-function classifyError(reason) {
-    const value = (reason ?? "").toLowerCase();
-    if (!value)
-        return null;
-    if (value.includes("setup_declined"))
-        return "setup_declined";
-    if (value.includes("setup_required"))
-        return "setup_required";
-    if (value.includes("source_required"))
-        return "source_required";
-    if (value.includes("prompt_cancelled"))
-        return "prompt_cancelled";
-    if (value.includes("auth"))
-        return "auth_failed";
-    if (value.includes("needs input"))
-        return "needs_input";
-    if (value.includes("legacy"))
-        return "legacy_auth";
-    if (value.includes("personal_server_unavailable"))
+// Classify a free-form CLI error/reason string into a canonical error class.
+// The CLI's own classification produced richer values (e.g. setup_required,
+// legacy_auth); we collapse these into the canonical whitelist here.
+function classifyCanonicalError(value) {
+    const normalized = (value ?? "").toLowerCase();
+    if (!normalized)
+        return "unknown";
+    if (normalized.includes("personal_server_unavailable") ||
+        normalized.includes("personal server")) {
         return "personal_server_unavailable";
-    if (value.includes("ingest"))
-        return "ingest_failed";
-    if (value.includes("connector"))
-        return "connector_unavailable";
-    if (value.includes("runtime"))
+    }
+    if (normalized.includes("auth") || normalized.includes("legacy")) {
+        return "auth_failed";
+    }
+    if (normalized.includes("timeout") || normalized.includes("timed out")) {
+        return "timeout";
+    }
+    if (normalized.includes("network")) {
+        return "network_error";
+    }
+    if (normalized.includes("runtime") ||
+        normalized.includes("connector") ||
+        normalized.includes("unexpected") ||
+        normalized.includes("ingest_failed") ||
+        normalized.includes("setup_required") ||
+        normalized.includes("invalid_connector")) {
         return "runtime_error";
+    }
     return "unknown";
 }
-function mapCliEventToTelemetry(event) {
-    switch (event.type) {
-        case "setup-check":
-            return {
-                eventName: "runtime_check_completed",
-                patch: {
-                    metadata: sanitizeMetadata({ runtime: event.runtime ?? null }),
-                },
-            };
-        case "setup-complete":
-            return {
-                eventName: "runtime_install_completed",
-                patch: {
-                    metadata: sanitizeMetadata({ runtime: event.runtime ?? null }),
-                },
-            };
-        case "connector-resolved":
-            return { eventName: "connector_resolved" };
-        case "needs-input":
-            return {
-                eventName: "input_required",
-                patch: {
-                    errorClass: "needs_input",
-                    metadata: sanitizeMetadata({ fieldCount: event.fields?.length ?? 0 }),
-                },
-            };
-        case "legacy-auth":
-            return {
-                eventName: "legacy_auth_required",
-                patch: { errorClass: "legacy_auth" },
-            };
-        case "collection-complete":
-            return { eventName: "collection_completed" };
-        case "runtime-error":
-            return {
-                eventName: "collection_failed",
-                patch: { errorClass: classifyError(event.message) ?? "runtime_error" },
-            };
-        case "ingest-started":
-            return { eventName: "ingest_started" };
-        case "ingest-complete":
-            return {
-                eventName: "ingest_completed",
-                patch: countScopeResults(event.scopeResults),
-            };
-        case "ingest-partial":
-            return {
-                eventName: "ingest_partial",
-                patch: {
-                    ...countScopeResults(event.scopeResults),
-                    errorClass: "ingest_failed",
-                },
-            };
-        case "ingest-failed":
-            return {
-                eventName: "ingest_failed",
-                patch: {
-                    ...countScopeResults(event.scopeResults),
-                    errorClass: "ingest_failed",
-                },
-            };
-        case "ingest-skipped":
-            return {
-                eventName: "ingest_skipped",
-                patch: {
-                    errorClass: classifyError(event.reason) ?? null,
-                    metadata: sanitizeMetadata({ reason: event.reason ?? null }),
-                },
-            };
-        case "outcome":
-        case "progress-update":
-        case "status-update":
-        case "headed-required":
-        case "jpeg":
-            return null;
-    }
-    return null;
+// Map a CLI interaction indicator to a canonical InteractionKind.
+function mapInteractionKind(value) {
+    const normalized = (value ?? "").toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (normalized.includes("otp"))
+        return "otp";
+    if (normalized.includes("captcha"))
+        return "captcha";
+    if (normalized.includes("login") || normalized.includes("credential"))
+        return "login";
+    return "manual_action";
 }
+// ── Outbox (file-backed) ────────────────────────────────────────────────────
+//
+// Events are batched into TelemetryBatch envelopes, written to individual
+// JSON files in getTelemetryOutboxDir(), and flushed on command exit and on
+// subsequent runs (retry across restarts). This survives crashes — the
+// pattern is worth preserving for the desktop app too.
 async function ensureOutboxDir() {
     await fs.mkdir(getTelemetryOutboxDir(), { recursive: true });
 }
@@ -222,52 +170,64 @@ async function resolveTelemetryState(localOnly = false) {
         queuedBatches,
     };
 }
+// ── Event factory ───────────────────────────────────────────────────────────
+//
+// Builds canonical TelemetryEvent values with identity + time + attribution +
+// context auto-populated. The caller supplies correlation + kind.
 function createEventFactory(context, state) {
-    const runId = randomId("run");
-    const base = {
-        installId: state.installId,
-        runId,
-        command: context.command,
-        subcommand: context.subcommand ?? null,
-        source: context.source ?? null,
-        connectorVersion: null,
-        authMode: null,
-        platform: `${process.platform}-${os.arch()}`,
-        os: process.platform,
-        arch: os.arch(),
-        cliVersion: context.cliVersion,
-        channel: context.channel,
-        installMethod: context.installMethod,
-        ci: Boolean(process.env.CI),
-        agent: Boolean(process.env.AGENT),
-        interactive: getInteractive(context.options),
+    const hostRunId = randomId("host");
+    const osName = detectOs();
+    const arch = detectArch();
+    const hostPlatform = makeHostPlatform(osName, arch);
+    const baseContext = {
+        hostPlatform,
+        os: osName,
+        arch,
+        producerVersion: context.cliVersion,
+    };
+    return {
+        hostRunId,
+        build(args) {
+            return {
+                identity: {
+                    eventId: randomId("evt"),
+                    eventVersion: TELEMETRY_EVENT_VERSION,
+                },
+                time: {
+                    occurredAt: nowIso(),
+                    ...(args.durationMs !== undefined
+                        ? { durationMs: args.durationMs }
+                        : {}),
+                },
+                attribution: {
+                    producer: TELEMETRY_PRODUCER_NAME,
+                    installId: state.installId,
+                },
+                context: {
+                    ...baseContext,
+                    ...(args.connectorVersion
+                        ? { connectorVersion: args.connectorVersion }
+                        : {}),
+                    ...(args.authMode ? { authMode: args.authMode } : {}),
+                },
+                correlation: args.correlation,
+                kind: args.kind,
+                ...(args.debug ? { debug: args.debug } : {}),
+                ...(args.extensions ? { extensions: args.extensions } : {}),
+            };
+        },
     };
-    return (eventName, patch = {}) => ({
-        eventId: randomId("evt"),
-        eventVersion: EVENT_VERSION,
-        timestamp: nowIso(),
-        eventName,
-        ...base,
-        ...patch,
-        outcome: patch.outcome ?? null,
-        errorClass: patch.errorClass ?? null,
-        durationMs: patch.durationMs ?? null,
-        storedScopeCount: patch.storedScopeCount ?? null,
-        failedScopeCount: patch.failedScopeCount ?? null,
-        metadata: sanitizeMetadata(patch.metadata),
-    });
 }
-function splitIntoEnvelopes(events, cliVersion) {
+// ── Batch serialization ─────────────────────────────────────────────────────
+function splitIntoEnvelopes(events) {
     const envelopes = [];
     let current = [];
     const flushCurrent = () => {
-        if (current.length === 0) {
+        if (current.length === 0)
             return;
-        }
         envelopes.push({
             batchId: randomId("batch"),
             sentAt: nowIso(),
-            client: { name: "vana-cli", version: cliVersion },
             events: current,
         });
         current = [];
@@ -277,7 +237,6 @@ function splitIntoEnvelopes(events, cliVersion) {
         const candidate = {
             batchId: "batch_candidate",
             sentAt: nowIso(),
-            client: { name: "vana-cli", version: cliVersion },
             events: current,
         };
         const tooManyEvents = current.length > MAX_EVENTS_PER_BATCH;
@@ -285,25 +244,23 @@ function splitIntoEnvelopes(events, cliVersion) {
         if (tooManyEvents || tooLarge) {
             const overflow = current.pop();
             flushCurrent();
-            if (overflow) {
+            if (overflow)
                 current.push(overflow);
-            }
         }
     }
     flushCurrent();
     return envelopes;
 }
-async function writeEnvelope(envelope, runId) {
+async function writeEnvelope(envelope, hostRunId) {
     await ensureOutboxDir();
-    const filename = `${Date.now()}-${process.pid}-${runId}-${crypto.randomUUID()}.json`;
+    const filename = `${Date.now()}-${process.pid}-${hostRunId}-${crypto.randomUUID()}.json`;
     const outboxPath = path.join(getTelemetryOutboxDir(), filename);
     await fs.writeFile(outboxPath, `${JSON.stringify(envelope)}\n`, "utf8");
 }
 export async function flushTelemetryOutbox() {
     const state = await resolveTelemetryState();
-    if (!state.enabled || state.mode !== "normal") {
+    if (!state.enabled || state.mode !== "normal")
         return;
-    }
     const files = (await listOutboxFiles()).slice(0, MAX_FILES_PER_FLUSH);
     for (const filePath of files) {
         let contents;
@@ -318,7 +275,7 @@ export async function flushTelemetryOutbox() {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
-                    "User-Agent": `vana-cli/${JSON.parse(contents).client?.version ?? "unknown"}`,
+                    "User-Agent": `vana-cli/unknown`,
                 },
                 body: contents,
                 signal: AbortSignal.timeout(FLUSH_TIMEOUT_MS),
@@ -332,6 +289,7 @@ export async function flushTelemetryOutbox() {
         }
     }
 }
+// ── Public helpers ──────────────────────────────────────────────────────────
 export async function getTelemetryStatus() {
     const state = await resolveTelemetryState();
     return {
@@ -352,93 +310,312 @@ export function setActiveTelemetrySession(session) {
 export function getActiveTelemetrySession() {
     return activeSession;
 }
-export function trackActiveTelemetryEvent(eventName, patch) {
-    activeSession?.trackCustomEvent(eventName, patch);
-}
+// ── Session ─────────────────────────────────────────────────────────────────
 export async function createCliTelemetrySession(context) {
     const state = await resolveTelemetryState(Boolean(context.localOnly));
-    const buildEvent = createEventFactory(context, state);
+    const factory = createEventFactory(context, state);
     const startedAt = Date.now();
     const events = [];
-    let latestOutcome = null;
-    let latestErrorClass = null;
+    // Per-session state. A single CLI invocation is ONE host run, with zero
+    // or more collection runs and sync attempts nested within.
+    const hostRunId = factory.hostRunId;
+    let collectionRunId = null;
+    let collectionSource = context.source ?? null;
+    let connectorVersion;
+    let authMode;
+    let syncRunId = null;
+    let latestOutcomeRaw = null;
     let persisted = false;
-    const push = (eventName, patch = {}) => {
-        if (!state.enabled && state.mode !== "debug") {
+    // Host-level extensions captured from the command context. These are
+    // producer-specific details that don't belong in the canonical Kind.
+    const hostExtensions = {
+        command: context.command,
+        subcommand: context.subcommand ?? null,
+        channel: context.channel,
+        installMethod: context.installMethod,
+        isCi: Boolean(process.env.CI),
+        isAgent: Boolean(process.env.AGENT),
+        isInteractive: Boolean(process.stdin.isTTY && process.stdout.isTTY && !context.options.noInput),
+    };
+    const push = (event) => {
+        if (!state.enabled && state.mode !== "debug")
             return;
-        }
-        const next = buildEvent(eventName, patch);
-        events.push(next);
+        events.push(event);
+    };
+    // Emit host/started immediately.
+    push(factory.build({
+        correlation: { scope: "host", hostRunId },
+        kind: { lifecycle: "host", phase: "started" },
+        extensions: hostExtensions,
+    }));
+    // Helper to lazily start a collection run the first time we see collection activity.
+    const ensureCollectionStarted = () => {
+        if (collectionRunId)
+            return;
+        if (!collectionSource)
+            return;
+        collectionRunId = randomId("col");
+        push(factory.build({
+            correlation: {
+                scope: "collection",
+                hostRunId,
+                collectionRunId,
+                source: collectionSource,
+            },
+            kind: { lifecycle: "collection", phase: "started" },
+            connectorVersion,
+            authMode,
+        }));
+    };
+    const emitCollectionEvent = (kind) => {
+        ensureCollectionStarted();
+        if (!collectionRunId || !collectionSource)
+            return;
+        push(factory.build({
+            correlation: {
+                scope: "collection",
+                hostRunId,
+                collectionRunId,
+                source: collectionSource,
+            },
+            kind,
+            connectorVersion,
+        }));
+    };
+    const ensureSyncRunId = () => {
+        if (!syncRunId)
+            syncRunId = randomId("sync");
+        return syncRunId;
+    };
+    const emitSyncEvent = (kind) => {
+        if (!collectionSource)
+            return;
+        push(factory.build({
+            correlation: {
+                scope: "sync",
+                hostRunId,
+                syncRunId: ensureSyncRunId(),
+                source: collectionSource,
+                ...(collectionRunId ? { collectionRunId } : {}),
+            },
+            kind,
+        }));
+    };
+    const countScopeResults = (scopeResults) => {
+        const stored = scopeResults?.filter((s) => s.status === "stored").length ?? 0;
+        const failed = scopeResults?.filter((s) => s.status === "failed").length ?? 0;
+        return { stored, failed };
     };
-    push("command_started", {
-        metadata: sanitizeMetadata({
-            launchMode: context.options.detach ? "detached" : "direct",
-            inputMode: context.options.ipc
-                ? "ipc"
-                : context.options.noInput
-                    ? "no_input"
-                    : "interactive",
-        }),
-    });
     return {
         trackCliEvent(event) {
-            const mapped = mapCliEventToTelemetry(event);
-            if (!mapped) {
-                if (event.type === "outcome") {
-                    latestOutcome = event.status ?? null;
-                    latestErrorClass = classifyError(event.reason) ?? latestErrorClass;
+            // Capture connector version / source / auth mode from any event that carries them.
+            if ("source" in event && event.source)
+                collectionSource = event.source;
+            switch (event.type) {
+                case "setup-check":
+                    // Setup-phase events are producer-specific and don't fit the shared
+                    // lifecycle. Attach them to the host extensions instead.
+                    hostExtensions.runtimeCheckCompleted = true;
+                    break;
+                case "setup-complete":
+                    hostExtensions.runtimeInstallCompleted = true;
+                    break;
+                case "connector-resolved":
+                    hostExtensions.connectorResolved = true;
+                    break;
+                case "needs-input":
+                    emitCollectionEvent({
+                        lifecycle: "collection",
+                        phase: "needs_input",
+                        ...(mapInteractionKind(event.fields?.join(",") ?? null)
+                            ? {
+                                interactionKind: mapInteractionKind(event.fields?.join(",") ?? null),
+                            }
+                            : {}),
+                    });
+                    break;
+                case "legacy-auth":
+                    // Legacy auth is effectively a "needs manual action" interaction.
+                    emitCollectionEvent({
+                        lifecycle: "collection",
+                        phase: "needs_input",
+                        interactionKind: "manual_action",
+                    });
+                    break;
+                case "collection-complete":
+                    emitCollectionEvent({
+                        lifecycle: "collection",
+                        phase: "terminal",
+                        outcome: "success",
+                    });
+                    break;
+                case "runtime-error":
+                    emitCollectionEvent({
+                        lifecycle: "collection",
+                        phase: "terminal",
+                        outcome: "failure",
+                        errorClass: classifyCanonicalError(event.message),
+                    });
+                    break;
+                case "ingest-started":
+                    emitSyncEvent({ lifecycle: "sync", phase: "started" });
+                    break;
+                case "ingest-complete": {
+                    const { stored, failed } = countScopeResults(event.scopeResults);
+                    emitSyncEvent({
+                        lifecycle: "sync",
+                        phase: "terminal",
+                        outcome: "success",
+                        storedScopeCount: stored,
+                        failedScopeCount: failed,
+                    });
+                    syncRunId = null;
+                    break;
                 }
-                return;
+                case "ingest-partial": {
+                    // Partial in the CLI means "some scopes stored, some failed" — in
+                    // the canonical contract that is `outcome: success` with
+                    // failedScopeCount > 0. The UI derives the "partial" label.
+                    const { stored, failed } = countScopeResults(event.scopeResults);
+                    emitSyncEvent({
+                        lifecycle: "sync",
+                        phase: "terminal",
+                        outcome: "success",
+                        storedScopeCount: stored,
+                        failedScopeCount: failed,
+                    });
+                    syncRunId = null;
+                    break;
+                }
+                case "ingest-failed":
+                    emitSyncEvent({
+                        lifecycle: "sync",
+                        phase: "terminal",
+                        outcome: "failure",
+                        errorClass: classifyCanonicalError("ingest_failed"),
+                    });
+                    syncRunId = null;
+                    break;
+                case "ingest-skipped":
+                    // Skip is standalone — no preceding `started` event.
+                    syncRunId = randomId("sync"); // fresh ID for the standalone skip
+                    emitSyncEvent({
+                        lifecycle: "sync",
+                        phase: "skipped",
+                        reason: classifyCanonicalError(event.reason) ===
+                            "personal_server_unavailable"
+                            ? "server_unavailable"
+                            : "not_requested",
+                    });
+                    syncRunId = null;
+                    break;
+                case "outcome":
+                    latestOutcomeRaw = event.status ?? null;
+                    break;
+                case "progress-update":
+                case "status-update":
+                case "headed-required":
+                case "jpeg":
+                    // Not modeled in canonical telemetry.
+                    break;
             }
-            push(mapped.eventName, {
-                ...mapped.patch,
-                source: event.source ?? context.source ?? null,
-            });
-        },
-        trackCustomEvent(eventName, patch = {}) {
-            push(eventName, patch);
         },
         markCommandResult(result) {
-            latestOutcome = result.outcome ?? latestOutcome;
-            latestErrorClass = result.errorClass ?? latestErrorClass;
             const durationMs = Date.now() - startedAt;
+            latestOutcomeRaw = result.outcome ?? latestOutcomeRaw;
+            // If a collection run was started but never terminated, close it here.
+            // If the CLI exited with a non-zero code, record collection_failed;
+            // otherwise let the lifecycle's own terminal stand.
+            if (collectionRunId && collectionSource) {
+                const hasCollectionTerminal = events.some((e) => e.correlation.scope === "collection" &&
+                    e.correlation.collectionRunId === collectionRunId &&
+                    e.kind.lifecycle === "collection" &&
+                    e.kind.phase === "terminal");
+                if (!hasCollectionTerminal) {
+                    if (result.exitCode === 0) {
+                        push(factory.build({
+                            correlation: {
+                                scope: "collection",
+                                hostRunId,
+                                collectionRunId,
+                                source: collectionSource,
+                            },
+                            kind: {
+                                lifecycle: "collection",
+                                phase: "terminal",
+                                outcome: "success",
+                            },
+                        }));
+                    }
+                    else {
+                        push(factory.build({
+                            correlation: {
+                                scope: "collection",
+                                hostRunId,
+                                collectionRunId,
+                                source: collectionSource,
+                            },
+                            kind: {
+                                lifecycle: "collection",
+                                phase: "terminal",
+                                outcome: "failure",
+                                errorClass: classifyCanonicalError(result.errorClass ?? latestOutcomeRaw),
+                            },
+                        }));
+                    }
+                }
+            }
+            // Host terminal.
             if (result.exitCode === 0) {
-                push("command_completed", {
+                push(factory.build({
+                    correlation: { scope: "host", hostRunId },
+                    kind: { lifecycle: "host", phase: "terminal", outcome: "success" },
                     durationMs,
-                    outcome: latestOutcome,
-                    errorClass: null,
-                });
-                return;
+                }));
+            }
+            else {
+                push(factory.build({
+                    correlation: { scope: "host", hostRunId },
+                    kind: {
+                        lifecycle: "host",
+                        phase: "terminal",
+                        outcome: "failure",
+                        errorClass: classifyCanonicalError(result.errorClass ?? latestOutcomeRaw),
+                    },
+                    durationMs,
+                }));
             }
-            push("command_failed", {
-                durationMs,
-                outcome: latestOutcome,
-                errorClass: latestErrorClass ?? "unknown",
-            });
         },
         async persist() {
-            if (persisted) {
+            if (persisted)
                 return;
-            }
             persisted = true;
             if (state.mode === "debug") {
-                for (const envelope of splitIntoEnvelopes(events, context.cliVersion)) {
+                for (const envelope of splitIntoEnvelopes(events)) {
                     process.stderr.write(`${JSON.stringify(envelope)}\n`);
                 }
                 return;
             }
-            if (!state.enabled) {
+            if (!state.enabled)
                 return;
-            }
-            const envelopes = splitIntoEnvelopes(events, context.cliVersion);
-            const runId = events[0]?.runId ?? randomId("run");
+            const envelopes = splitIntoEnvelopes(events);
             for (const envelope of envelopes) {
-                await writeEnvelope(envelope, runId);
+                await writeEnvelope(envelope, hostRunId);
             }
         },
+        trackCustomEvent() {
+            // No-op. See the CliTelemetrySession interface doc.
+        },
         async flush() {
             await flushTelemetryOutbox();
         },
     };
 }
+// ── Deprecated ──────────────────────────────────────────────────────────────
+/** @deprecated trackCustomEvent on the session is a no-op in the canonical
+ *  model. This top-level helper is also a no-op — kept only to satisfy
+ *  existing call sites. */
+export function trackActiveTelemetryEvent(_eventName, _patch) {
+    /* intentionally blank */
+}
 //# sourceMappingURL=telemetry.js.map