core types + interfaces: CLIError, RequestSpec, Formatter, CredentialResolver, Provider

Stable types and interfaces that codegen and framework features build against:

- CLIError with exit codes (0/1/2/3), ToErrorEnvelope for JSON output
- APIError matching HeyGen's standard error envelope
- FromAPIError mapping HTTP status → exit code
- RequestSpec: []QueryParam, []FieldSpec, BodyEncoding, FilePath, *PollConfig
- output.Formatter interface (Data + Error)
- auth.CredentialResolver interface (priority chain for API keys)
- config.Provider interface (non-secret settings, BaseURL only)

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

Author: somanshreddy

internal/auth/resolver.go

@@ -0,0 +1,10 @@
+package auth
+
+// CredentialResolver locates an API key by searching a priority chain of
+// credential sources (environment variable, OS keychain, credentials file).
+// The first source that returns a key wins.
+//
+// Currently only EnvCredentialResolver is implemented (reads HEYGEN_API_KEY).
+type CredentialResolver interface {
+	Resolve() (string, error)
+}

internal/client/request_spec.go

@@ -0,0 +1,58 @@
+package client
+
+// RequestSpec is the contract between commands and the HTTP executor.
+// A command (hand-written or auto-generated) populates a RequestSpec;
+// the executor converts it to an HTTP request, handles the response,
+// and returns raw JSON.
+//
+// The full struct is defined upfront so that codegen, pagination, polling,
+// and multipart upload can rely on a stable shape.
+type RequestSpec struct {
+	Endpoint     string            // "/v3/videos"
+	Method       string            // GET, POST, DELETE, PATCH
+	PathParams   map[string]string // {video_id: "abc123"}
+	QueryParams  []QueryParam      // typed query params (supports repeated keys)
+	Body         []FieldSpec       // typed body fields (supports nested objects)
+	BodyEncoding string            // "json" (default) or "multipart"
+	FilePath     string            // local file path for multipart upload
+	Paginated    bool              // enables --all accumulation
+	TokenField   string            // pagination cursor field in response
+	DataField    string            // response array field name
+	Pollable     bool              // enables --wait
+	PollConfig   *PollConfig       // status field, terminal states
+	Destructive  bool              // triggers confirmation prompt (--force skips)
+	Columns      []Column          // TUI table column definitions
+}
+
+// QueryParam represents a single query parameter. Repeated allows
+// multiple values for the same key (e.g., ?status=a&status=b).
+type QueryParam struct {
+	Key      string
+	Value    string
+	Repeated bool
+}
+
+// FieldSpec represents a typed body field for JSON request bodies.
+// The codegen pipeline emits these from OpenAPI request body schemas.
+type FieldSpec struct {
+	Name     string // JSON field name
+	Type     string // "string", "int", "bool", "object", "array"
+	Value    any    // typed value from flag
+	Required bool
+}
+
+// PollConfig defines how --wait polling works for async commands.
+type PollConfig struct {
+	StatusEndpoint string   // GET endpoint to check status
+	StatusField    string   // JSON field containing status (e.g., "status")
+	TerminalOK     []string // Success states: ["completed"]
+	TerminalFail   []string // Failure states: ["failed", "error"]
+	IDField        string   // Field in create response with resource ID
+}
+
+// Column defines a TUI table column for --human output.
+type Column struct {
+	Header string // Table column header ("Status")
+	Field  string // JSON field path, supports dot notation ("avatar.name")
+	Width  int    // Optional fixed width (0 = auto-size)
+}

internal/config/config.go

@@ -0,0 +1,10 @@
+package config
+
+// Provider supplies non-secret configuration values using a precedence chain:
+// CLI flag > environment variable > config file > built-in default.
+//
+// Credentials are not part of config — see auth.CredentialResolver.
+// Currently only EnvProvider is implemented (reads HEYGEN_API_BASE env var).
+type Provider interface {
+	BaseURL() string
+}

internal/errors/api_error.go

@@ -0,0 +1,10 @@
+package errors
+
+// APIError represents the HeyGen standard error envelope.
+// Maps to: {"error": {"code": ..., "message": ..., "param": ..., "doc_url": ...}}
+type APIError struct {
+	Code    string  `json:"code"`
+	Message string  `json:"message"`
+	Param   *string `json:"param,omitempty"`
+	DocURL  *string `json:"doc_url,omitempty"`
+}

internal/errors/errors.go

@@ -0,0 +1,114 @@
+package errors
+
+import "fmt"
+
+// Exit codes. Kept minimal — the primary consumer is an LLM agent that reads
+// the error JSON for details; exit codes just provide coarse routing.
+const (
+	ExitSuccess = 0
+	ExitGeneral = 1
+	ExitUsage   = 2
+	ExitAuth    = 3
+)
+
+// CLIError is the canonical error type for all CLI operations.
+type CLIError struct {
+	Code      string // machine-readable: "auth_error", "not_found", "network_error"
+	Message   string // human-readable description
+	Hint      string // actionable fix: "Run heygen auth login"
+	RequestID string // from API X-Request-Id header (if applicable)
+	ExitCode  int    // process exit code (0/1/2/3)
+}
+
+// Error implements the error interface.
+func (e *CLIError) Error() string {
+	if e.Hint != "" {
+		return fmt.Sprintf("%s (hint: %s)", e.Message, e.Hint)
+	}
+	return e.Message
+}
+
+// ToErrorEnvelope returns the canonical JSON error envelope shape:
+// {"error": {"code": ..., "message": ..., "hint": ..., "request_id": ...}}
+func (e *CLIError) ToErrorEnvelope() map[string]any {
+	inner := map[string]any{
+		"code":    e.Code,
+		"message": e.Message,
+	}
+	if e.Hint != "" {
+		inner["hint"] = e.Hint
+	}
+	if e.RequestID != "" {
+		inner["request_id"] = e.RequestID
+	}
+	return map[string]any{"error": inner}
+}
+
+// New creates a CLIError with ExitGeneral.
+func New(message string) *CLIError {
+	return &CLIError{
+		Code:     "error",
+		Message:  message,
+		ExitCode: ExitGeneral,
+	}
+}
+
+// NewAuth creates a CLIError with ExitAuth.
+func NewAuth(message, hint string) *CLIError {
+	return &CLIError{
+		Code:     "auth_error",
+		Message:  message,
+		Hint:     hint,
+		ExitCode: ExitAuth,
+	}
+}
+
+// NewUsage creates a CLIError with ExitUsage.
+func NewUsage(message string) *CLIError {
+	return &CLIError{
+		Code:     "usage_error",
+		Message:  message,
+		ExitCode: ExitUsage,
+	}
+}
+
+// FromAPIError converts an API error envelope and HTTP status code into a CLIError.
+func FromAPIError(statusCode int, apiErr *APIError, requestID string) *CLIError {
+	exitCode := ExitGeneral
+	code := apiErr.Code
+
+	switch {
+	case statusCode == 401 || statusCode == 403:
+		exitCode = ExitAuth
+		if code == "" {
+			code = "auth_error"
+		}
+	case statusCode == 400:
+		if code == "" {
+			code = "validation_error"
+		}
+	case statusCode == 404:
+		if code == "" {
+			code = "not_found"
+		}
+	case statusCode == 429:
+		if code == "" {
+			code = "rate_limited"
+		}
+	case statusCode >= 500:
+		if code == "" {
+			code = "server_error"
+		}
+	default:
+		if code == "" {
+			code = "error"
+		}
+	}
+
+	return &CLIError{
+		Code:      code,
+		Message:   apiErr.Message,
+		RequestID: requestID,
+		ExitCode:  exitCode,
+	}
+}

internal/errors/errors_test.go

@@ -0,0 +1,150 @@
+package errors
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestCLIError_Error(t *testing.T) {
+	tests := []struct {
+		name string
+		err  *CLIError
+		want string
+	}{
+		{
+			name: "message only",
+			err:  &CLIError{Message: "something failed"},
+			want: "something failed",
+		},
+		{
+			name: "message with hint",
+			err:  &CLIError{Message: "auth failed", Hint: "run heygen auth login"},
+			want: "auth failed (hint: run heygen auth login)",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.err.Error(); got != tt.want {
+				t.Errorf("Error() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCLIError_ToErrorEnvelope(t *testing.T) {
+	err := &CLIError{
+		Code:      "not_found",
+		Message:   "Video abc123 not found",
+		Hint:      "Check the video ID with: heygen video list",
+		RequestID: "req_xyz",
+	}
+
+	envelope := err.ToErrorEnvelope()
+
+	// Marshal and re-parse to verify JSON shape
+	data, marshalErr := json.Marshal(envelope)
+	if marshalErr != nil {
+		t.Fatalf("failed to marshal envelope: %v", marshalErr)
+	}
+
+	var parsed map[string]map[string]string
+	if jsonErr := json.Unmarshal(data, &parsed); jsonErr != nil {
+		t.Fatalf("failed to unmarshal envelope: %v", jsonErr)
+	}
+
+	inner := parsed["error"]
+	if inner["code"] != "not_found" {
+		t.Errorf("code = %q, want %q", inner["code"], "not_found")
+	}
+	if inner["message"] != "Video abc123 not found" {
+		t.Errorf("message = %q, want %q", inner["message"], "Video abc123 not found")
+	}
+	if inner["hint"] != "Check the video ID with: heygen video list" {
+		t.Errorf("hint = %q, want expected value", inner["hint"])
+	}
+	if inner["request_id"] != "req_xyz" {
+		t.Errorf("request_id = %q, want %q", inner["request_id"], "req_xyz")
+	}
+}
+
+func TestCLIError_ToErrorEnvelope_OmitsEmpty(t *testing.T) {
+	err := &CLIError{Code: "error", Message: "fail"}
+	envelope := err.ToErrorEnvelope()
+	inner := envelope["error"].(map[string]any)
+
+	if _, ok := inner["hint"]; ok {
+		t.Error("hint should be omitted when empty")
+	}
+	if _, ok := inner["request_id"]; ok {
+		t.Error("request_id should be omitted when empty")
+	}
+}
+
+func TestFromAPIError_ExitCodes(t *testing.T) {
+	tests := []struct {
+		name       string
+		statusCode int
+		wantExit   int
+		wantCode   string
+	}{
+		{"401 → auth", 401, ExitAuth, "auth_error"},
+		{"403 → auth", 403, ExitAuth, "auth_error"},
+		{"400 → general", 400, ExitGeneral, "validation_error"},
+		{"404 → general", 404, ExitGeneral, "not_found"},
+		{"429 → general", 429, ExitGeneral, "rate_limited"},
+		{"500 → general", 500, ExitGeneral, "server_error"},
+		{"502 → general", 502, ExitGeneral, "server_error"},
+		{"503 → general", 503, ExitGeneral, "server_error"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			apiErr := &APIError{Message: "test error"}
+			cliErr := FromAPIError(tt.statusCode, apiErr, "req_123")
+
+			if cliErr.ExitCode != tt.wantExit {
+				t.Errorf("ExitCode = %d, want %d", cliErr.ExitCode, tt.wantExit)
+			}
+			if cliErr.Code != tt.wantCode {
+				t.Errorf("Code = %q, want %q", cliErr.Code, tt.wantCode)
+			}
+			if cliErr.RequestID != "req_123" {
+				t.Errorf("RequestID = %q, want %q", cliErr.RequestID, "req_123")
+			}
+		})
+	}
+}
+
+func TestFromAPIError_PreservesAPICode(t *testing.T) {
+	apiErr := &APIError{Code: "custom_code", Message: "custom error"}
+	cliErr := FromAPIError(400, apiErr, "")
+
+	if cliErr.Code != "custom_code" {
+		t.Errorf("Code = %q, want %q (should preserve API code)", cliErr.Code, "custom_code")
+	}
+}
+
+func TestConstructors(t *testing.T) {
+	t.Run("New", func(t *testing.T) {
+		err := New("something broke")
+		if err.ExitCode != ExitGeneral {
+			t.Errorf("ExitCode = %d, want %d", err.ExitCode, ExitGeneral)
+		}
+	})
+
+	t.Run("NewAuth", func(t *testing.T) {
+		err := NewAuth("no key", "set HEYGEN_API_KEY")
+		if err.ExitCode != ExitAuth {
+			t.Errorf("ExitCode = %d, want %d", err.ExitCode, ExitAuth)
+		}
+		if err.Hint != "set HEYGEN_API_KEY" {
+			t.Errorf("Hint = %q, want expected value", err.Hint)
+		}
+	})
+
+	t.Run("NewUsage", func(t *testing.T) {
+		err := NewUsage("bad flag")
+		if err.ExitCode != ExitUsage {
+			t.Errorf("ExitCode = %d, want %d", err.ExitCode, ExitUsage)
+		}
+	})
+}

internal/output/formatter.go

@@ -0,0 +1,19 @@
+package output
+
+import (
+	"encoding/json"
+
+	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
+)
+
+// Formatter controls how the CLI renders output. Successful data goes to
+// stdout; errors go to stderr as structured JSON envelopes.
+//
+// JSONFormatter is the default (machine-readable). A TUIFormatter can be
+// added behind the same interface to support --human tables and spinners.
+type Formatter interface {
+	// Data writes a successful API response to stdout.
+	Data(v json.RawMessage) error
+	// Error writes a CLIError as a JSON envelope to stderr.
+	Error(err *clierrors.CLIError)
+}