feat: emit typed error envelopes for minutes and vc commands

Failures from the minutes and video-conference commands now carry a stable
error category and subtype instead of free-form text, so callers can tell
apart invalid input, missing permissions, and network or service failures
without scraping messages. Errors raised at the remote API boundary keep
their current form until the typed request path is in place.

Author: evandance

shortcuts/minutes/minutes_download.go

@@ -17,6 +17,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -54,21 +55,21 @@ var MinutesDownload = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
 		if len(tokens) == 0 {
-			return output.ErrValidation("--minute-tokens is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens is required").WithParam("--minute-tokens")
 		}
 		if len(tokens) > maxBatchSize {
-			return output.ErrValidation("--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize).WithParam("--minute-tokens")
 		}
 		for _, token := range tokens {
 			if !validMinuteToken.MatchString(token) {
-				return output.ErrValidation("invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token).WithParam("--minute-tokens")
 			}
 		}
 		// Cheap checks first, then path-safety resolution.
 		out := runtime.Str("output")
 		outDir := runtime.Str("output-dir")
 		if out != "" && outDir != "" {
-			return output.ErrValidation("--output and --output-dir cannot both be set")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output and --output-dir cannot both be set").WithParam("--output")
 		}
 		if out != "" {
 			if err := common.ValidateSafePath(runtime.FileIO(), out); err != nil {
@@ -112,15 +113,15 @@ var MinutesDownload = common.Shortcut{
 				explicitOutputPath = ""
 			case statErr == nil && !fi.IsDir():
 				if !single {
-					return output.ErrValidation("--output %q is a file; batch mode expects a directory (use --output-dir)", explicitOutputPath)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output %q is a file; batch mode expects a directory (use --output-dir)", explicitOutputPath).WithParam("--output")
 				}
 			case errors.Is(statErr, fs.ErrNotExist):
 				if !single {
 					explicitOutputDir = explicitOutputPath
 					explicitOutputPath = ""
 				}
 			default:
-				return output.Errorf(output.ExitAPI, "io_error", "cannot access --output %q: %s", explicitOutputPath, statErr)
+				return errs.NewInternalError(errs.SubtypeFileIO, "cannot access --output %q: %s", explicitOutputPath, statErr).WithCause(statErr)
 			}
 		}
 
@@ -151,7 +152,7 @@ var MinutesDownload = common.Shortcut{
 		// download URLs originate from the trusted Lark API, not user input.
 		baseClient, err := runtime.Factory.HttpClient()
 		if err != nil {
-			return output.ErrNetwork("failed to get HTTP client: %s", err)
+			return errs.NewNetworkError(errs.SubtypeNetworkTransport, "failed to get HTTP client: %s", err).WithCause(err)
 		}
 		clonedClient := *baseClient
 		clonedClient.Timeout = disableClientTimeout
@@ -235,6 +236,7 @@ var MinutesDownload = common.Shortcut{
 		if single {
 			r := results[0]
 			if r.Error != "" {
+				// TODO(errs-migrate): surface batch partial failures via runtime.OutPartialFailure
 				return output.ErrAPI(0, r.Error, nil)
 			}
 			if urlOnly {
@@ -264,6 +266,7 @@ var MinutesDownload = common.Shortcut{
 
 		runtime.OutFormat(map[string]interface{}{"downloads": results}, &output.Meta{Count: len(results)}, nil)
 		if successCount == 0 && len(results) > 0 {
+			// TODO(errs-migrate): surface batch partial failures via runtime.OutPartialFailure
 			return output.ErrAPI(0, fmt.Sprintf("all %d downloads failed", len(results)), nil)
 		}
 		return nil
@@ -272,6 +275,7 @@ var MinutesDownload = common.Shortcut{
 
 // fetchDownloadURL retrieves the pre-signed download URL for a minute token.
 func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) (string, error) {
+	// TODO(errs-migrate): route through runtime.CallAPITyped once the typed API boundary is available
 	data, err := runtime.DoAPIJSON(http.MethodGet,
 		fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/media", validate.EncodePathSegment(minuteToken)),
 		nil, nil)
@@ -280,7 +284,7 @@ func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minut
 	}
 	downloadURL := common.GetString(data, "download_url")
 	if downloadURL == "" {
-		return "", output.Errorf(output.ExitAPI, "api_error", "API returned empty download_url for %s", minuteToken)
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "API returned empty download_url for %s", minuteToken)
 	}
 	return downloadURL, nil
 }
@@ -302,26 +306,26 @@ type downloadOpts struct {
 // Filename resolution: opts.outputPath > Content-Disposition filename > Content-Type ext > <token>.media.
 func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, minuteToken string, opts downloadOpts) (*downloadResult, error) {
 	if err := validate.ValidateDownloadSourceURL(ctx, downloadURL); err != nil {
-		return nil, output.ErrValidation("blocked download URL: %s", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "blocked download URL: %s", err).WithCause(err)
 	}
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
 	if err != nil {
-		return nil, output.ErrNetwork("invalid download URL: %s", err)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "invalid download URL: %s", err).WithCause(err)
 	}
 
 	resp, err := client.Do(req)
 	if err != nil {
-		return nil, output.ErrNetwork("download failed: %s", err)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: %s", err).WithCause(err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
 		if len(body) > 0 {
-			return nil, output.ErrNetwork("download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
 		}
-		return nil, output.ErrNetwork("download failed: HTTP %d", resp.StatusCode)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d", resp.StatusCode)
 	}
 
 	// resolve output path
@@ -340,7 +344,8 @@ func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, mi
 
 	if !opts.overwrite {
 		if _, statErr := opts.fio.Stat(outputPath); statErr == nil {
-			return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", outputPath)
+			// TODO(errs-migrate): use errs.SubtypeFailedPrecondition once that subtype is available
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "output file already exists: %s (use --overwrite to replace)", outputPath)
 		}
 	}
 
@@ -349,7 +354,7 @@ func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, mi
 		ContentLength: resp.ContentLength,
 	}, resp.Body)
 	if err != nil {
-		return nil, common.WrapSaveErrorByCategory(err, "io")
+		return nil, minutesSaveError(err)
 	}
 	resolvedPath, err := opts.fio.ResolvePath(outputPath)
 	if err != nil || resolvedPath == "" {
@@ -417,3 +422,21 @@ func extFromContentType(contentType string) string {
 	}
 	return ""
 }
+
+// minutesSaveError maps a FileIO.Save error to a typed error: path
+// validation failures are validation errors; mkdir/write failures are
+// internal file-I/O errors.
+func minutesSaveError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var me *fileio.MkdirError
+	switch {
+	case errors.Is(err, fileio.ErrPathValidation):
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithCause(err)
+	case errors.As(err, &me):
+		return errs.NewInternalError(errs.SubtypeFileIO, "cannot create parent directory: %s", err).WithCause(err)
+	default:
+		return errs.NewInternalError(errs.SubtypeFileIO, "cannot create file: %s", err).WithCause(err)
+	}
+}

shortcuts/minutes/minutes_download_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"os"
 	"strings"
@@ -15,6 +16,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -694,3 +696,186 @@ func TestDownload_Batch_DryRun(t *testing.T) {
 		t.Errorf("dry-run should show tokens, got: %s", out)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// Typed-error lock tests
+// ---------------------------------------------------------------------------
+
+// TestDownload_TypedErr_ValidationInvalidArgument verifies that an invalid
+// minute token format (passing cobra's required check but failing our regex)
+// returns a *errs.ValidationError with SubtypeInvalidArgument and the expected
+// Param.  This locks site :64 (invalid minute token %q).
+func TestDownload_TypedErr_ValidationInvalidArgument(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, MinutesDownload, []string{
+		"+download", "--minute-tokens", "INVALID***TOKEN", "--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if ve.Param != "--minute-tokens" {
+		t.Errorf("Param = %q, want %q", ve.Param, "--minute-tokens")
+	}
+}
+
+// TestDownload_TypedErr_NetworkTransport_HttpError verifies that a non-2xx
+// download response from downloadMediaFile returns a *errs.NetworkError with
+// SubtypeNetworkTransport.
+//
+// Note: in the end-to-end single-token Execute path the error is captured into
+// results[i].Error (string) and re-surfaced as an aggregate error that is not
+// yet typed.  We therefore call downloadMediaFile directly via a probe shortcut
+// to assert the typed shape at the source.
+func TestDownload_TypedErr_NetworkTransport_HttpError(t *testing.T) {
+	chdir(t, t.TempDir())
+
+	var capturedErr error
+	probe := common.Shortcut{
+		Service:   "minutes",
+		Command:   "+probe-dl",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+			client, err := rctx.Factory.HttpClient()
+			if err != nil {
+				return err
+			}
+			_, capturedErr = downloadMediaFile(ctx, client,
+				"https://example.com/presigned/download", "tok001",
+				downloadOpts{fio: rctx.FileIO(), outputPath: "out.mp4"})
+			return nil
+		},
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		URL:     "example.com/presigned/download",
+		Status:  503,
+		RawBody: []byte("Service Unavailable"),
+	})
+
+	if err := mountAndRun(t, probe, []string{"+probe-dl", "--as", "bot"}, f, nil); err != nil {
+		t.Fatalf("probe shortcut should not error: %v", err)
+	}
+	if capturedErr == nil {
+		t.Fatal("expected downloadMediaFile to return an error for HTTP 503, got nil")
+	}
+	var ne *errs.NetworkError
+	if !errors.As(capturedErr, &ne) {
+		t.Fatalf("expected *errs.NetworkError, got %T: %v", capturedErr, capturedErr)
+	}
+	if ne.Subtype != errs.SubtypeNetworkTransport {
+		t.Errorf("Subtype = %q, want %q", ne.Subtype, errs.SubtypeNetworkTransport)
+	}
+	if !strings.Contains(ne.Error(), "503") {
+		t.Errorf("error message should contain status code 503, got: %v", ne)
+	}
+}
+
+// TestDownload_TypedErr_InternalInvalidResponse verifies that fetchDownloadURL
+// returns *errs.InternalError with SubtypeInvalidResponse when the API
+// response contains an empty download_url field.
+//
+// Note: the end-to-end Execute path wraps this error in an aggregate error at
+// the single-token result aggregation step, which is not yet typed.  The
+// typed assertion is therefore made at the fetchDownloadURL call site directly,
+// using a thin custom shortcut that returns the raw error.
+func TestDownload_TypedErr_InternalInvalidResponse(t *testing.T) {
+	var capturedErr error
+	probe := common.Shortcut{
+		Service:   "minutes",
+		Command:   "+probe-download-url",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+			_, capturedErr = fetchDownloadURL(ctx, rctx, "tok001")
+			// Always return nil so mountAndRun doesn't swallow the error type.
+			return nil
+		},
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/tok001/media",
+		Status: 200,
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"download_url": ""},
+		},
+	})
+
+	if err := mountAndRun(t, probe, []string{"+probe-download-url", "--as", "bot"}, f, nil); err != nil {
+		t.Fatalf("probe shortcut should not error: %v", err)
+	}
+	if capturedErr == nil {
+		t.Fatal("expected fetchDownloadURL to return an error for empty download_url, got nil")
+	}
+	var ie *errs.InternalError
+	if !errors.As(capturedErr, &ie) {
+		t.Fatalf("expected *errs.InternalError, got %T: %v", capturedErr, capturedErr)
+	}
+	if ie.Subtype != errs.SubtypeInvalidResponse {
+		t.Errorf("Subtype = %q, want %q", ie.Subtype, errs.SubtypeInvalidResponse)
+	}
+	if !strings.Contains(ie.Error(), "download_url") {
+		t.Errorf("error message should mention download_url, got: %v", ie)
+	}
+}
+
+// TestDownload_TypedErr_OverwriteProtection verifies that the overwrite guard
+// in downloadMediaFile returns *errs.ValidationError with SubtypeInvalidArgument
+// (it will move to a failed-precondition subtype once that subtype is available).
+//
+// Note: in the end-to-end single-token Execute path this error is captured into
+// results[i].Error (string) and re-surfaced as an aggregate error that is not
+// yet typed. We call downloadMediaFile directly via a probe shortcut so the typed
+// shape is asserted at the source.
+func TestDownload_TypedErr_OverwriteProtection(t *testing.T) {
+	chdir(t, t.TempDir())
+	if err := os.WriteFile("existing.mp4", []byte("old"), 0644); err != nil {
+		t.Fatalf("setup failed: %v", err)
+	}
+
+	var capturedErr error
+	probe := common.Shortcut{
+		Service:   "minutes",
+		Command:   "+probe-overwrite",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+			client, err := rctx.Factory.HttpClient()
+			if err != nil {
+				return err
+			}
+			_, capturedErr = downloadMediaFile(ctx, client,
+				"https://example.com/presigned/download", "tok001",
+				downloadOpts{fio: rctx.FileIO(), outputPath: "existing.mp4", overwrite: false})
+			return nil
+		},
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(downloadStub("example.com/presigned/download", []byte("new-content"), "video/mp4"))
+
+	if err := mountAndRun(t, probe, []string{"+probe-overwrite", "--as", "bot"}, f, nil); err != nil {
+		t.Fatalf("probe shortcut should not error: %v", err)
+	}
+	if capturedErr == nil {
+		t.Fatal("expected downloadMediaFile to return an error for existing file without overwrite, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(capturedErr, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", capturedErr, capturedErr)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if !strings.Contains(ve.Error(), "exists") {
+		t.Errorf("error message should mention exists, got: %v", ve)
+	}
+}