cli: reclassify parse/read failures + add source/http_status telemetry

Reclassify the remaining opaque `error` sites: a mid-response read failure ->
network_error; JSON-parse and poll field-extraction failures -> response_parse_error.
Capture the request id from x-amzn-request-id / x-amzn-trace-id (the app does not set
X-Request-Id; the ALB does), falling back to X-Request-Id.

Add telemetry-only origin signals to COMMAND_RUN_COMPLETE: source (api = from the API
envelope, cli = CLI-generated; defaults to cli) and http_status (upstream status when
known). Both are omitted on success and are NOT in the user-facing error envelope.
Dashboards can then group by (source, error_code) collision-safely and separate an
app 5xx from a no-envelope 5xx via source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: somanshreddy

cmd/heygen/main.go

@@ -26,25 +26,33 @@ func main() {
 
 	exitCode := 0
 	errorCode := ""
+	source := ""
+	httpStatus := 0
 	if err != nil {
 		var cliErr *clierrors.CLIError
 		if errors.As(err, &cliErr) {
 			enrichAuthHint(cliErr, credSourceFromCmd(executedCmd))
 			formatter.Error(cliErr)
 			exitCode = cliErr.ExitCode
 			errorCode = cliErr.Code
+			source = cliErr.Source
+			if source == "" {
+				source = "cli" // any error the CLI raised without an explicit origin
+			}
+			httpStatus = cliErr.HTTPStatus
 		} else {
 			// Cobra returns plain errors for unknown commands and arg validation.
 			// Detect these and wrap as usage errors (exit 2).
 			wrapped := classifyError(err)
 			formatter.Error(wrapped)
 			exitCode = wrapped.ExitCode
 			errorCode = wrapped.Code
+			source = "cli"
 		}
 	}
 
 	if analyticsClient.Started() && executedCmd != nil {
-		analyticsClient.CommandRunComplete(executedCmd.CommandPath(), exitCode, time.Since(start), errorCode)
+		analyticsClient.CommandRunComplete(executedCmd.CommandPath(), exitCode, time.Since(start), errorCode, source, httpStatus)
 	}
 	analyticsClient.Close()
 	os.Exit(exitCode)

internal/analytics/analytics.go

@@ -70,18 +70,28 @@ func (c *Client) CommandRun(command string) {
 	})
 }
 
-func (c *Client) CommandRunComplete(command string, exitCode int, duration time.Duration, errorCode string) {
+// CommandRunComplete records a completed command. On error, source is "api" (the
+// error came from an API response envelope) or "cli" (CLI-generated), and httpStatus
+// is the upstream status when known (0 otherwise); both are omitted on success.
+func (c *Client) CommandRunComplete(command string, exitCode int, duration time.Duration, errorCode, source string, httpStatus int) {
 	if !c.enabled || c.ph == nil {
 		return
 	}
+	props := c.baseProperties(command).
+		Set("exit_code", exitCode).
+		Set("duration_ms", duration.Milliseconds()).
+		Set("success", exitCode == 0).
+		Set("error_code", errorCode)
+	if source != "" {
+		props = props.Set("source", source)
+	}
+	if httpStatus > 0 {
+		props = props.Set("http_status", httpStatus)
+	}
 	_ = c.ph.Enqueue(posthog.Capture{
 		DistinctId: c.distinctID,
 		Event:      "COMMAND_RUN_COMPLETE",
-		Properties: c.baseProperties(command).
-			Set("exit_code", exitCode).
-			Set("duration_ms", duration.Milliseconds()).
-			Set("success", exitCode == 0).
-			Set("error_code", errorCode),
+		Properties: props,
 	})
 }
 

internal/analytics/analytics_test.go

@@ -59,7 +59,7 @@ func TestCommandRunComplete_Properties(t *testing.T) {
 	client := newWithCapture("v1.2.3", stub)
 	client.distinctID = "anon-id"
 
-	client.CommandRunComplete("heygen video create", 4, 1500*time.Millisecond, "timeout")
+	client.CommandRunComplete("heygen video create", 4, 1500*time.Millisecond, "timeout", "cli", 0)
 
 	if len(stub.messages) != 1 {
 		t.Fatalf("messages = %d, want 1", len(stub.messages))
@@ -107,7 +107,7 @@ func TestCommandRunComplete_IncludesClientOrigin(t *testing.T) {
 	client := newWithCapture("v1.2.3", stub)
 	client.clientOrigin = "claude_code"
 
-	client.CommandRunComplete("heygen video create", 0, time.Second, "")
+	client.CommandRunComplete("heygen video create", 0, time.Second, "", "", 0)
 
 	msg := stub.messages[0].(posthog.Capture)
 	if got := msg.Properties["client_origin"]; got != "claude_code" {
@@ -225,3 +225,39 @@ func TestDistinctID_Persists(t *testing.T) {
 		t.Fatalf("second distinct ID = %q, want %q", second, first)
 	}
 }
+
+func TestCommandRunComplete_SourceAndHTTPStatus(t *testing.T) {
+	t.Run("api source carries http_status", func(t *testing.T) {
+		stub := &stubCaptureClient{}
+		client := newWithCapture("v1.2.3", stub)
+		client.CommandRunComplete("heygen video create", 1, time.Second, "insufficient_credit", "api", 402)
+		msg := stub.messages[0].(posthog.Capture)
+		if got := msg.Properties["source"]; got != "api" {
+			t.Fatalf("source = %v, want api", got)
+		}
+		if got := msg.Properties["http_status"]; got != 402 {
+			t.Fatalf("http_status = %v, want 402", got)
+		}
+	})
+	t.Run("cli source omits http_status when 0", func(t *testing.T) {
+		stub := &stubCaptureClient{}
+		client := newWithCapture("v1.2.3", stub)
+		client.CommandRunComplete("heygen video create", 1, time.Second, "file_io_error", "cli", 0)
+		msg := stub.messages[0].(posthog.Capture)
+		if got := msg.Properties["source"]; got != "cli" {
+			t.Fatalf("source = %v, want cli", got)
+		}
+		if _, ok := msg.Properties["http_status"]; ok {
+			t.Fatalf("http_status should be omitted when 0")
+		}
+	})
+	t.Run("success omits source", func(t *testing.T) {
+		stub := &stubCaptureClient{}
+		client := newWithCapture("v1.2.3", stub)
+		client.CommandRunComplete("heygen video list", 0, time.Second, "", "", 0)
+		msg := stub.messages[0].(posthog.Capture)
+		if _, ok := msg.Properties["source"]; ok {
+			t.Fatalf("source should be omitted on success")
+		}
+	})
+}

internal/client/executor.go

@@ -81,10 +81,13 @@ func (c *Client) ExecuteAndPoll(
 
 	resourceID, err := extractJSONPath(createResp, spec.PollConfig.IDField)
 	if err != nil {
-		return nil, clierrors.New(fmt.Sprintf(
-			"failed to extract resource ID from %q: %v. This command may require manual polling for batch responses",
-			spec.PollConfig.IDField, err,
-		))
+		return nil, &clierrors.CLIError{
+			Code: "response_parse_error",
+			Message: fmt.Sprintf(
+				"failed to extract resource ID from %q: %v", spec.PollConfig.IDField, err),
+			Hint:     "The create response did not have the expected shape. This command may require manual polling for batch responses.",
+			ExitCode: clierrors.ExitGeneral,
+		}
 	}
 
 	// If IDField uses an array index (e.g., "data.ids.0"), reject batch
@@ -131,10 +134,13 @@ func (c *Client) ExecuteAndPoll(
 
 		status, err := extractJSONPath(statusResp, spec.PollConfig.StatusField)
 		if err != nil {
-			return nil, clierrors.New(fmt.Sprintf(
-				"failed to extract status from %q: %v",
-				spec.PollConfig.StatusField, err,
-			))
+			return nil, &clierrors.CLIError{
+				Code: "response_parse_error",
+				Message: fmt.Sprintf(
+					"failed to extract status from %q: %v", spec.PollConfig.StatusField, err),
+				Hint:     "The status response did not have the expected shape. Retry; if it persists, report it.",
+				ExitCode: clierrors.ExitGeneral,
+			}
 		}
 
 		if slices.Contains(spec.PollConfig.TerminalOK, status) {
@@ -212,11 +218,17 @@ func (c *Client) executeWithContext(ctx context.Context, spec *command.Spec, inv
 
 	respBody, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return nil, clierrors.New(fmt.Sprintf("failed to read response body: %v", err))
+		// Mid-response read failure is a dropped connection, not a parse issue.
+		return nil, &clierrors.CLIError{
+			Code:     "network_error",
+			Message:  fmt.Sprintf("failed to read response body: %v", err),
+			Hint:     "This is usually a temporary network issue. Check your connection and retry.",
+			ExitCode: clierrors.ExitGeneral,
+		}
 	}
 
 	if resp.StatusCode >= 400 {
-		return nil, parseErrorResponse(resp.StatusCode, respBody, resp.Header.Get("X-Request-Id"))
+		return nil, parseErrorResponse(resp.StatusCode, respBody, requestIDFromHeaders(resp.Header))
 	}
 
 	return json.RawMessage(respBody), nil
@@ -394,7 +406,12 @@ func extractJSONPath(raw json.RawMessage, path string) (string, error) {
 
 	var current any
 	if err := json.Unmarshal(raw, &current); err != nil {
-		return "", clierrors.New(fmt.Sprintf("failed to parse JSON response: %v", err))
+		return "", &clierrors.CLIError{
+			Code:     "response_parse_error",
+			Message:  fmt.Sprintf("failed to parse JSON response: %v", err),
+			Hint:     "The API response could not be parsed. Retry; if it persists, report it (possible CLI/API mismatch).",
+			ExitCode: clierrors.ExitGeneral,
+		}
 	}
 
 	for _, part := range strings.Split(path, ".") {
@@ -515,3 +532,15 @@ func parseErrorResponse(statusCode int, body []byte, requestID string) *clierror
 
 	return clierrors.FromAPIError(statusCode, &clierrors.APIError{}, requestID)
 }
+
+// requestIDFromHeaders returns the best available request/trace id for support
+// correlation. The v3 app does not set X-Request-Id; the AWS ALB sets x-amzn-*, so
+// prefer the app header when present, then fall back to the ALB's.
+func requestIDFromHeaders(h http.Header) string {
+	for _, k := range []string{"X-Request-Id", "X-Amzn-Request-Id", "X-Amzn-Trace-Id"} {
+		if v := h.Get(k); v != "" {
+			return v
+		}
+	}
+	return ""
+}

internal/client/executor_test.go

@@ -997,3 +997,61 @@ func TestParseErrorResponse_SurfacesParamAndDocURL(t *testing.T) {
 		t.Errorf("DocURL = %q, want the doc URL", err.DocURL)
 	}
 }
+
+func TestRequestIDFromHeaders(t *testing.T) {
+	tests := []struct {
+		name string
+		h    http.Header
+		want string
+	}{
+		{"app X-Request-Id preferred", http.Header{"X-Request-Id": {"app-1"}, "X-Amzn-Request-Id": {"amzn-1"}}, "app-1"},
+		{"falls back to x-amzn-request-id", http.Header{"X-Amzn-Request-Id": {"amzn-1"}}, "amzn-1"},
+		{"falls back to x-amzn-trace-id", http.Header{"X-Amzn-Trace-Id": {"trace-1"}}, "trace-1"},
+		{"none present", http.Header{}, ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := requestIDFromHeaders(tt.h); got != tt.want {
+				t.Errorf("requestIDFromHeaders = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractJSONPath_ParseError(t *testing.T) {
+	_, err := extractJSONPath([]byte("{not valid json"), "data.id")
+	var cliErr *clierrors.CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != "response_parse_error" {
+		t.Fatalf("err = %v, want a response_parse_error CLIError", err)
+	}
+}
+
+// errReadCloser fails on Read, simulating a connection dropped mid-response.
+type errReadCloser struct{}
+
+func (errReadCloser) Read([]byte) (int, error) { return 0, errors.New("connection reset mid-body") }
+func (errReadCloser) Close() error             { return nil }
+
+type errBodyTransport struct{}
+
+func (errBodyTransport) RoundTrip(*http.Request) (*http.Response, error) {
+	return &http.Response{StatusCode: 200, Body: errReadCloser{}, Header: make(http.Header)}, nil
+}
+
+func TestExecute_ResponseBodyReadError_NetworkError(t *testing.T) {
+	c := New("key", WithBaseURL("http://example.invalid"), WithHTTPClient(&http.Client{Transport: errBodyTransport{}}))
+	_, err := c.Execute(&command.Spec{Endpoint: "/v3/videos", Method: "GET"}, &command.Invocation{PathParams: map[string]string{}})
+	var cliErr *clierrors.CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != "network_error" {
+		t.Fatalf("err = %v, want a network_error CLIError", err)
+	}
+}
+
+func TestRequestIDFromHeaders_CaseInsensitive(t *testing.T) {
+	// A lowercase ALB header (as parsed/canonicalized by net/http) is still found.
+	h := http.Header{}
+	h.Set("x-amzn-request-id", "amzn-lower")
+	if got := requestIDFromHeaders(h); got != "amzn-lower" {
+		t.Errorf("requestIDFromHeaders = %q, want amzn-lower", got)
+	}
+}

internal/errors/errors.go

@@ -23,6 +23,10 @@ type CLIError struct {
 	DocURL    string // API: link to this error code's documentation
 	RequestID string // from API X-Request-Id header (if applicable)
 	ExitCode  int    // process exit code (0/1/2/3/4)
+
+	// Telemetry-only (NOT serialized in ToErrorEnvelope — internal origin signal):
+	Source     string // "api" (from the API envelope) or "cli" (CLI-generated). Empty defaults to "cli".
+	HTTPStatus int    // upstream HTTP status when the error came from an API response (0 otherwise)
 }
 
 // Error implements the error interface.
@@ -184,14 +188,23 @@ func FromAPIError(statusCode int, apiErr *APIError, requestID string) *CLIError
 		docURL = *apiErr.DocURL
 	}
 
+	// Origin for telemetry: a preserved (specific) API code came from the API
+	// envelope; a status-derived code was generated by the CLI (non-envelope / edge).
+	source := "cli"
+	if !isNonSpecific(apiErr.Code) {
+		source = "api"
+	}
+
 	return &CLIError{
-		Code:      code,
-		Message:   message,
-		Hint:      hint,
-		Param:     param,
-		DocURL:    docURL,
-		RequestID: requestID,
-		ExitCode:  exitCode,
+		Code:       code,
+		Message:    message,
+		Hint:       hint,
+		Param:      param,
+		DocURL:     docURL,
+		RequestID:  requestID,
+		ExitCode:   exitCode,
+		Source:     source,
+		HTTPStatus: statusCode,
 	}
 }
 

internal/errors/errors_test.go

@@ -362,3 +362,24 @@ func TestToErrorEnvelope_OmitsDocURLAndParamWhenEmpty(t *testing.T) {
 		t.Error("doc_url should be omitted when empty")
 	}
 }
+
+func TestFromAPIError_SourceAndHTTPStatus(t *testing.T) {
+	// A preserved (specific) API code originates from the API envelope.
+	got := FromAPIError(402, &APIError{Code: "insufficient_credit", Message: "x"}, "")
+	if got.Source != "api" || got.HTTPStatus != 402 {
+		t.Errorf("Source/HTTPStatus = %q/%d, want api/402", got.Source, got.HTTPStatus)
+	}
+	// A status-derived (non-specific) code is CLI-generated.
+	derived := FromAPIError(500, &APIError{Message: "x"}, "")
+	if derived.Source != "cli" || derived.HTTPStatus != 500 {
+		t.Errorf("Source/HTTPStatus = %q/%d, want cli/500", derived.Source, derived.HTTPStatus)
+	}
+	// Source/HTTPStatus are telemetry-only — never serialized in the envelope.
+	inner := got.ToErrorEnvelope()["error"].(map[string]any)
+	if _, ok := inner["source"]; ok {
+		t.Error("source must not appear in the error envelope")
+	}
+	if _, ok := inner["http_status"]; ok {
+		t.Error("http_status must not appear in the error envelope")
+	}
+}