feat(analytics): unify install identity + structured auth telemetry (#212)

Author: miguel-heygen

README.md

@@ -190,7 +190,7 @@ heygen config list       # show all settings with sources
 
 ## Reporting bugs
 
-- **Quick signal (recommended for agents):** `heygen feedback --rating <1-5> --comment "..."`. Goes to private, anonymous analytics. Safe to run unattended.
+- **Quick signal (recommended for agents):** `heygen feedback --rating <1-5> --comment "..."`. Goes to private, anonymous analytics. Safe to run unattended. Usage telemetry is anonymous until you sign in: running `heygen auth login` links it to your account email or username. A one-time notice prints the first time analytics runs; opt out anytime with `HEYGEN_NO_ANALYTICS=1` (or `heygen config set analytics false`).
 - **Tracked bug a maintainer should see:** open a [GitHub issue](https://github.com/heygen-com/heygen-cli/issues). This repo is **public**, so review what you paste first and omit anything sensitive (API keys, prompts, internal URLs, personal data).
 
 **Agents:** do not open GitHub issues automatically. Use `heygen feedback` for bug signal; if something seems worth tracking, surface it to the user and let a human file the issue after reviewing it for sensitive content.

cmd/heygen/auth_login.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/heygen-com/heygen-cli/internal/analytics"
 	"github.com/heygen-com/heygen-cli/internal/auth"
 	"github.com/heygen-com/heygen-cli/internal/auth/oauth"
 	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
@@ -20,6 +21,38 @@ import (
 	"golang.org/x/term"
 )
 
+// loginAnalyticsClient is the subset of *analytics.Client this file calls,
+// factored out as an interface so tests can inject a spy without needing a
+// real PostHog capture client (internal/analytics's own stubCaptureClient
+// is the lower-level equivalent used in that package's tests).
+type loginAnalyticsClient interface {
+	IdentifyAccount(distinctId string)
+	AuthLoginStarted(method string)
+	AuthLoginCompleted(method string)
+	AuthLoginFailed(method, reason string)
+}
+
+// loginAnalytics is the process-wide analytics client login telemetry
+// calls into. main() sets it to the real client once at startup; left at
+// its inert zero value here so any test that builds the login commands
+// directly (bypassing main()) gets a no-op, matching analytics.New(_,
+// false)'s existing disabled-client contract.
+var loginAnalytics loginAnalyticsClient = &analytics.Client{}
+
+// identityKey picks the identity a successful login links analytics to:
+// email if present, otherwise username. Deliberately narrower than
+// UserInfo.DisplayName() (which also falls back to "first last") — this
+// links a PostHog person to a stable login handle, not a display string.
+// Lowercased so this joins with hyperframes-oss's own identify call
+// regardless of the account's stored casing — an uppercase-email user would
+// otherwise split across two PostHog profiles.
+func identityKey(userInfo auth.UserInfo) string {
+	if userInfo.Email != "" {
+		return strings.ToLower(userInfo.Email)
+	}
+	return strings.ToLower(userInfo.Username)
+}
+
 // oauthLoginConfig is overridable in tests so the login flow can be
 // driven against an httptest IdP without spawning a real browser.
 type oauthLoginConfig struct {
@@ -187,6 +220,8 @@ var runAuthLoginTestDeps *runAuthLoginDeps
 // override is in effect, else we default to the API-key flow.
 func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) error {
 	if flags.deviceCodeMode {
+		loginAnalytics.AuthLoginStarted("device_code")
+		loginAnalytics.AuthLoginFailed("device_code", "device_code_unsupported")
 		return clierrors.NewUsage(
 			"--device-code is not yet supported; use the default browser flow or --api-key",
 		)
@@ -219,8 +254,10 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 
 	switch {
 	case flags.oauthMode:
+		loginAnalytics.AuthLoginStarted("oauth")
 		return deps.runOAuth(cmd, ctx)
 	case flags.apiKeyMode:
+		loginAnalytics.AuthLoginStarted("api_key")
 		return deps.runAPIKey(cmd, ctx)
 	}
 
@@ -230,6 +267,8 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 	// keystrokes), and only when nothing in the environment has asked
 	// us to behave non-interactively.
 	if deps.stdinIsTerminal() && deps.stdoutIsTerminal() && !deps.nonInteractive() {
+		// No AuthLoginStarted here — the picker hasn't resolved a method
+		// yet. A cancel below must emit no started/failed pair at all.
 		choice, err := deps.runPicker(cmd.Context(), cmd.InOrStdin(), cmd.ErrOrStderr())
 		if err != nil {
 			if errors.Is(err, pickerCanceledError{}) || errorsAsPickerCanceled(err) {
@@ -239,8 +278,10 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 		}
 		switch choice {
 		case loginChoiceOAuth:
+			loginAnalytics.AuthLoginStarted("oauth")
 			return deps.runOAuth(cmd, ctx)
 		case loginChoiceAPIKey:
+			loginAnalytics.AuthLoginStarted("api_key")
 			return deps.runAPIKey(cmd, ctx)
 		default:
 			return clierrors.New(fmt.Sprintf("unknown login choice: %d", choice))
@@ -251,6 +292,7 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 	// decision: agents and CI runners feed keys on stdin, and the
 	// browser-OAuth dance has nowhere to land its loopback callback
 	// when there's no human to click "Allow".
+	loginAnalytics.AuthLoginStarted("api_key")
 	return deps.runAPIKey(cmd, ctx)
 }
 
@@ -270,12 +312,30 @@ func errorsAsPickerCanceled(err error) bool {
 // cleared so the file holds at most one of api_key / oauth (the
 // single-credential normalization invariant). Pre-this-change users
 // with both blocks self-heal on their next login.
-func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) error {
+func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) (err error) {
+	// reported tracks whether this attempt already emitted a terminal
+	// analytics event (AuthLoginCompleted/AuthLoginFailed) on one of the
+	// explicitly-instrumented paths below. The deferred check is a
+	// safety net for every OTHER error return in this function (e.g. a
+	// future early return nobody remembers to instrument): without it,
+	// the AuthLoginStarted event the caller already fired would never
+	// reconcile.
+	reported := false
+	defer func() {
+		if err != nil && !reported {
+			loginAnalytics.AuthLoginFailed("api_key", "internal_error")
+		}
+	}()
+
 	key, err := readAPIKey(cmd.InOrStdin(), cmd.ErrOrStderr())
 	if err != nil {
+		reported = true
+		loginAnalytics.AuthLoginFailed("api_key", "api_key_aborted")
 		return err
 	}
 	if key == "" {
+		reported = true
+		loginAnalytics.AuthLoginFailed("api_key", "api_key_invalid_input")
 		if stdinIsTerminalFunc() {
 			return clierrors.NewUsage(
 				"no API key entered — type your key after the prompt, or paste it.",
@@ -340,6 +400,9 @@ func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) error {
 		if saveErr := auth.SaveUserInfo(userInfo); saveErr != nil {
 			fmt.Fprintf(cmd.ErrOrStderr(), "(warning: could not persist user info: %v)\n", saveErr)
 		}
+		if id := identityKey(userInfo); id != "" {
+			loginAnalytics.IdentifyAccount(id)
+		}
 	} else if clearErr := auth.ClearUserInfo(); clearErr != nil {
 		// Probe failed but a stale user block from a prior login may
 		// still be on disk. Best-effort clear; a failure here is
@@ -375,12 +438,35 @@ func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) error {
 	if display := userInfo.DisplayName(); display != "" {
 		fmt.Fprintf(cmd.ErrOrStderr(), "Logged in as %s\n", display)
 	}
-	return ctx.formatter.Data(data, "", nil)
+	// Only report the login as completed once the response has actually
+	// been written out successfully: if the formatter fails (e.g. a
+	// broken pipe on stdout), the command still exits non-zero and the
+	// deferred check above reports AuthLoginFailed instead.
+	if err = ctx.formatter.Data(data, "", nil); err != nil {
+		return err
+	}
+	reported = true
+	loginAnalytics.AuthLoginCompleted("api_key")
+	return nil
 }
 
 // runOAuthLogin drives the browser + PKCE + loopback dance and persists
 // the resulting tokens.
-func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) error {
+func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) (err error) {
+	// reported tracks whether this attempt already emitted a terminal
+	// analytics event (AuthLoginCompleted/AuthLoginFailed) on one of the
+	// explicitly-instrumented paths below. The deferred check is a
+	// safety net for every OTHER error return in this function (e.g. a
+	// future early return nobody remembers to instrument): without it,
+	// the AuthLoginStarted event the caller already fired would never
+	// reconcile.
+	reported := false
+	defer func() {
+		if err != nil && !reported {
+			loginAnalytics.AuthLoginFailed("oauth", "internal_error")
+		}
+	}()
+
 	// Headless-shell fast-fail: when explicit --oauth lands in a shell
 	// with no TTY on stdin AND the environment opts out of opening a
 	// browser (BROWSER=none or HEYGEN_NO_BROWSER=1), the callback can
@@ -389,6 +475,8 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 	// guard when cfg.OpenBrowser is injected (test path drives the
 	// callback synthetically). (N1)
 	if cfg.OpenBrowser == nil && isHeadlessOAuthShell() {
+		reported = true
+		loginAnalytics.AuthLoginFailed("oauth", "headless_shell")
 		return clierrors.NewUsage(
 			"cannot complete browser OAuth flow in a headless shell " +
 				"(no TTY and BROWSER=none / HEYGEN_NO_BROWSER=1).\n" +
@@ -446,18 +534,26 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 	var loopbackResult oauth.LoopbackResult
 	select {
 	case <-cmdCtx.Done():
+		reported = true
+		loginAnalytics.AuthLoginFailed("oauth", "oauth_timeout")
 		return clierrors.New(fmt.Sprintf("oauth: timed out waiting for browser callback: %v", cmdCtx.Err()))
 	case loopbackResult = <-results:
 	}
 	if loopbackResult.Err != nil {
+		reported = true
+		loginAnalytics.AuthLoginFailed("oauth", "oauth_flow_error")
 		return clierrors.New(loopbackResult.Err.Error())
 	}
 
 	tok, err := oc.ExchangeAuthorizationCode(cmdCtx, loopbackResult.Code, verifier, loopbackResult.RedirectURI)
 	if err != nil {
+		reported = true
+		loginAnalytics.AuthLoginFailed("oauth", "token_exchange_failed")
 		return clierrors.New(fmt.Sprintf("oauth: token exchange failed: %v", err))
 	}
 	if tok.AccessToken == "" {
+		reported = true
+		loginAnalytics.AuthLoginFailed("oauth", "token_exchange_failed")
 		return clierrors.New("oauth: token endpoint returned no access_token")
 	}
 
@@ -508,6 +604,9 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 		if saveErr := auth.SaveUserInfo(userInfo); saveErr != nil {
 			fmt.Fprintf(cmd.ErrOrStderr(), "(warning: could not persist user info: %v)\n", saveErr)
 		}
+		if id := identityKey(userInfo); id != "" {
+			loginAnalytics.IdentifyAccount(id)
+		}
 	} else if clearErr := auth.ClearUserInfo(); clearErr != nil {
 		// Probe failed AND the file might still hold a stale user block
 		// from a prior login (different account). Best-effort clear; a
@@ -551,7 +650,16 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 	} else {
 		fmt.Fprintln(cmd.ErrOrStderr(), "Logged in.")
 	}
-	return ctx.formatter.Data(data, "", nil)
+	// Only report the login as completed once the response has actually
+	// been written out successfully: if the formatter fails (e.g. a
+	// broken pipe on stdout), the command still exits non-zero and the
+	// deferred check above reports AuthLoginFailed instead.
+	if err = ctx.formatter.Data(data, "", nil); err != nil {
+		return err
+	}
+	reported = true
+	loginAnalytics.AuthLoginCompleted("oauth")
+	return nil
 }
 
 // lookupCurrentUser GETs /v3/users/me with the freshly minted Bearer