client: reject batch --wait with clear error

When IDField uses an array index (e.g., data.video_translation_ids.0)
and the array has >1 element, return a batch_not_supported error
instead of silently polling only the first resource.

Single-element arrays (single-language translation) work normally.

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

Author: somanshreddy

cmd/heygen/builder.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -103,7 +104,7 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 						if errors.As(err, &failErr) {
 							// Output the failure response (contains error details),
 							// then signal failure via CLIError for exit code 1.
-							if fmtErr := ctx.formatter.Data(failErr.Data, spec.DataField, nil); fmtErr != nil {
+							if fmtErr := ctx.formatter.Data(failErr.Data, "data", nil); fmtErr != nil {
 								return fmtErr
 							}
 							return clierrors.New(failErr.Error())
@@ -114,7 +115,7 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 					// --wait result is a single resource from the GET endpoint.
 					// Columns are nil — HumanFormatter renders single objects as
 					// key-value pairs, not tables. This matches `heygen video get`.
-					return ctx.formatter.Data(result, spec.DataField, nil)
+					return ctx.formatter.Data(result, "data", nil)
 				}
 			}
 

cmd/heygen/builder_test.go

@@ -40,7 +40,6 @@ var videoCreateWaitSpec = &command.Spec{
 	Endpoint:     "/v3/videos",
 	Method:       "POST",
 	BodyEncoding: "json",
-	DataField:    "data",
 	Examples:     []string{"heygen video create --wait"},
 }
 

internal/client/executor.go

@@ -79,6 +79,17 @@ func (c *Client) ExecuteAndPoll(
 		))
 	}
 
+	// If IDField uses an array index (e.g., "data.ids.0"), reject batch
+	// responses with multiple IDs. --wait only supports single-resource polling.
+	if arrayLen, ok := extractArrayLen(createResp, spec.PollConfig.IDField); ok && arrayLen > 1 {
+		return nil, &clierrors.CLIError{
+			Code:     "batch_not_supported",
+			Message:  fmt.Sprintf("--wait does not support batch operations (got %d resources)", arrayLen),
+			Hint:     "Poll each resource individually with the corresponding get command",
+			ExitCode: clierrors.ExitGeneral,
+		}
+	}
+
 	pathParams, err := statusPathParams(spec.PollConfig.StatusEndpoint, resourceID)
 	if err != nil {
 		return nil, err
@@ -409,6 +420,43 @@ func statusPathParams(endpoint, resourceID string) (map[string]string, error) {
 	return params, nil
 }
 
+// extractArrayLen checks if a dot-notation path ends with a numeric index
+// (e.g., "data.ids.0"), and if so, returns the length of that array.
+// Returns (0, false) if the path doesn't end with an array index.
+func extractArrayLen(raw json.RawMessage, path string) (int, bool) {
+	parts := strings.Split(path, ".")
+	if len(parts) < 2 {
+		return 0, false
+	}
+	// Check if the last segment is a numeric index
+	if _, err := strconv.Atoi(parts[len(parts)-1]); err != nil {
+		return 0, false
+	}
+	// Walk to the parent array
+	arrayPath := strings.Join(parts[:len(parts)-1], ".")
+
+	var current any
+	if err := json.Unmarshal(raw, &current); err != nil {
+		return 0, false
+	}
+	for _, part := range strings.Split(arrayPath, ".") {
+		obj, ok := current.(map[string]any)
+		if !ok {
+			return 0, false
+		}
+		next, ok := obj[part]
+		if !ok {
+			return 0, false
+		}
+		current = next
+	}
+	arr, ok := current.([]any)
+	if !ok {
+		return 0, false
+	}
+	return len(arr), true
+}
+
 // extractJSONPath extracts a string value from JSON using dot-notation.
 // Supports object fields ("data.status") and array indices ("data.ids.0").
 func extractJSONPath(raw json.RawMessage, path string) (string, error) {

internal/client/executor_test.go

@@ -877,6 +877,97 @@ func TestExtractJSONPath_ArrayOnNonArray(t *testing.T) {
 	}
 }
 
+func TestExecuteAndPoll_RejectsBatch(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		// Create response returns multiple IDs (batch translation)
+		_, _ = w.Write([]byte(`{"data":{"video_translation_ids":["id_1","id_2","id_3"]}}`))
+	}))
+	defer srv.Close()
+
+	c := New("key", WithBaseURL(srv.URL), WithHTTPClient(srv.Client()), WithMaxRetries(0))
+
+	spec := &command.Spec{
+		Endpoint:     "/v3/video-translations",
+		Method:       http.MethodPost,
+		BodyEncoding: "json",
+		PollConfig: &command.PollConfig{
+			StatusEndpoint: "/v3/video-translations/{video_translation_id}",
+			StatusField:    "data.status",
+			TerminalOK:     []string{"completed"},
+			TerminalFail:   []string{"failed"},
+			IDField:        "data.video_translation_ids.0",
+		},
+	}
+
+	_, err := c.ExecuteAndPoll(context.Background(), spec, emptyInvocation(), PollOptions{
+		BaseDelay: time.Millisecond,
+		MaxDelay:  time.Millisecond,
+	})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+
+	var cliErr *clierrors.CLIError
+	if !errors.As(err, &cliErr) {
+		t.Fatalf("expected *CLIError, got %T: %v", err, err)
+	}
+	if cliErr.Code != "batch_not_supported" {
+		t.Fatalf("code = %q, want %q", cliErr.Code, "batch_not_supported")
+	}
+	if !strings.Contains(cliErr.Message, "3 resources") {
+		t.Fatalf("message = %q, want mention of 3 resources", cliErr.Message)
+	}
+}
+
+func TestExecuteAndPoll_SingleArrayElement_OK(t *testing.T) {
+	var statusCalls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v3/video-translations":
+			w.WriteHeader(http.StatusOK)
+			// Single-language: array with 1 element
+			_, _ = w.Write([]byte(`{"data":{"video_translation_ids":["trans_123"]}}`))
+		case "/v3/video-translations/trans_123":
+			statusCalls++
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(`{"data":{"id":"trans_123","status":"completed"}}`))
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer srv.Close()
+
+	c := New("key", WithBaseURL(srv.URL), WithHTTPClient(srv.Client()), WithMaxRetries(0))
+
+	spec := &command.Spec{
+		Endpoint:     "/v3/video-translations",
+		Method:       http.MethodPost,
+		BodyEncoding: "json",
+		PollConfig: &command.PollConfig{
+			StatusEndpoint: "/v3/video-translations/{video_translation_id}",
+			StatusField:    "data.status",
+			TerminalOK:     []string{"completed"},
+			TerminalFail:   []string{"failed"},
+			IDField:        "data.video_translation_ids.0",
+		},
+	}
+
+	result, err := c.ExecuteAndPoll(context.Background(), spec, emptyInvocation(), PollOptions{
+		BaseDelay: time.Millisecond,
+		MaxDelay:  time.Millisecond,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if statusCalls != 1 {
+		t.Fatalf("statusCalls = %d, want 1", statusCalls)
+	}
+	if !strings.Contains(string(result), "completed") {
+		t.Fatalf("result = %s, want completed", result)
+	}
+}
+
 func pollableVideoCreateSpec() *command.Spec {
 	return &command.Spec{
 		Endpoint:     "/v3/videos",