feat(mail): return typed error envelopes across the mail domain

Replace every produced error path in shortcuts/mail with typed errs.* envelopes, so consumers get stable category, subtype, param/params, hint, retryable, and log_id metadata for classification and recovery instead of free-form message text.

- Locally constructed mail errors move from output.Err* / output.Errorf / final fmt.Errorf / common legacy helpers to errs.* builders, with structured params on multi-flag validation and failed-precondition states kept non-retryable.

- API-call failures move from runtime.CallAPI / DoAPIJSON legacy boundaries to runtime.CallAPITyped or runtime.ClassifyAPIResponse, and mail-specific enrichers read errs.ProblemOf so typed code, subtype, hint, and log_id metadata are preserved.

- Batch draft-send partial failures now use runtime.OutPartialFailure so successful and failed draft sends stay in stdout while the command exits through a typed multi-status signal.

- Add mail-domain typed helpers, mail API code metadata, and guard wiring to keep shortcuts/mail from reintroducing legacy envelopes or legacy API calls.

- Keep genuine intermediate fmt.Errorf wraps in parser/builder layers annotated with nolint comments; command-facing paths wrap them into typed validation, API, network, or internal errors.

Author: evandance

.golangci.yml

@@ -73,20 +73,20 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/)
+      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/|shortcuts/mail/)
         text: errs-typed-only
         linters:
           - forbidigo
       # errs-no-bare-wrap enforced on paths fully migrated to typed final
       # errors. Scoped separately from errs-typed-only because cmd/auth/,
       # cmd/config/ still have residual fmt.Errorf and must not be caught.
-      - path-except: (shortcuts/drive/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/drive/|shortcuts/mail/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
-      # errs-no-legacy-helper is drive-only: the shared helpers it bans are
-      # still used by other domains until their later migration phase.
-      - path-except: (shortcuts/drive/)
+      # errs-no-legacy-helper is scoped to migrated domains: the shared helpers
+      # it bans are still used by other domains until their later migration phase.
+      - path-except: (shortcuts/drive/|shortcuts/mail/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo
@@ -115,17 +115,17 @@ linters:
           msg: >-
             [errs-typed-only] use errs.NewXxxError(...) builder
             (see errs/types.go).
-        # ── legacy shared error helpers banned on drive ──
+        # ── legacy shared error helpers banned on migrated domains ──
         # These helpers internally produce legacy output.Err* shapes, so they
-        # are invisible to the errs-typed-only ban above. Drive has migrated its
-        # calls to typed errs.* (drive-local driveInputStatError / driveSaveError);
-        # this prevents reintroduction. Other domains still use the shared
-        # helpers (migrated globally in a later phase), so this is drive-scoped.
+        # are invisible to the errs-typed-only ban above. Migrated domains use
+        # typed errs.* builders or domain-local file-I/O helpers instead; this
+        # prevents reintroduction while unmigrated domains continue to use the
+        # shared helpers until their later migration phase.
         - pattern: (common\.FlagErrorf|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
           msg: >-
             [errs-no-legacy-helper] these shared helpers emit legacy output.Err*
-            shapes. Use the typed errs.NewXxxError builders or the drive-local
-            driveInputStatError / driveSaveError helpers (shortcuts/drive/drive_errors.go).
+            shapes. Use typed errs.NewXxxError builders or a domain-local
+            file-I/O helper.
         # ── bare error wraps banned on fully-typed paths ──
         - pattern: (fmt\.Errorf|errors\.New)\b
           msg: >-

internal/errclass/classify.go

@@ -244,6 +244,8 @@ func APIHint(subtype errs.Subtype) string {
 		return "operate on source and target within the same tenant and region/unit"
 	case errs.SubtypeCrossBrand:
 		return "operate on source and target within the same brand environment"
+	case errs.SubtypeQuotaExceeded:
+		return "reduce the request volume or free quota, then retry after the relevant quota resets"
 	}
 	return ""
 }

internal/errclass/codemeta_mail.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// mailCodeMeta holds mail-service Lark code -> CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes fall back to CategoryAPI via BuildAPIError.
+var mailCodeMeta = map[int]CodeMeta{
+	1234013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},      // mailbox not found or not active
+	1236007: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily send count exceeded
+	1236008: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily external recipient count exceeded
+	1236009: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant daily external recipient count exceeded
+	1236010: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // mail quota limit
+	1236013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant storage limit exceeded
+}
+
+func init() { mergeCodeMeta(mailCodeMeta, "mail") }

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -16,6 +16,7 @@ import (
 // common replacements or construct an errs.* typed error directly.
 var migratedCommonHelperPaths = []string{
 	"shortcuts/drive/",
+	"shortcuts/mail/",
 }
 
 const commonImportPath = "github.com/larksuite/cli/shortcuts/common"

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -17,6 +17,7 @@ import (
 // appending their path prefix here.
 var migratedEnvelopePaths = []string{
 	"shortcuts/drive/",
+	"shortcuts/mail/",
 }
 
 // legacyOutputImportPath is the import path of the package that declares the

lint/errscontract/rules_test.go

@@ -894,27 +894,33 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"ResolveOpenIDs",
 		"HandleApiResult",
 	}
-	for _, helper := range helpers {
-		t.Run(helper, func(t *testing.T) {
-			src := `package drive
+	paths := []string{
+		"shortcuts/drive/drive_search.go",
+		"shortcuts/mail/mail_send.go",
+	}
+	for _, path := range paths {
+		for _, helper := range helpers {
+			t.Run(path+"_"+helper, func(t *testing.T) {
+				src := `package migrated
 
 import "github.com/larksuite/cli/shortcuts/common"
 
 func boom() {
-	common.` + helper + `()
+common.` + helper + `()
 }
 `
-			v := CheckNoLegacyCommonHelperCall("shortcuts/drive/drive_search.go", src)
-			if len(v) != 1 {
-				t.Fatalf("expected 1 violation for %s, got %d: %+v", helper, len(v), v)
-			}
-			if v[0].Action != ActionReject {
-				t.Errorf("action = %q, want REJECT", v[0].Action)
-			}
-			if !strings.Contains(v[0].Message, "common."+helper) {
-				t.Errorf("message should name helper %s: %s", helper, v[0].Message)
-			}
-		})
+				v := CheckNoLegacyCommonHelperCall(path, src)
+				if len(v) != 1 {
+					t.Fatalf("expected 1 violation for %s on %s, got %d: %+v", helper, path, len(v), v)
+				}
+				if v[0].Action != ActionReject {
+					t.Errorf("action = %q, want REJECT", v[0].Action)
+				}
+				if !strings.Contains(v[0].Message, "common."+helper) {
+					t.Errorf("message should name helper %s: %s", helper, v[0].Message)
+				}
+			})
+		}
 	}
 }
 

shortcuts/mail/body_file.go

@@ -8,7 +8,6 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -51,11 +50,15 @@ const maxBodyFileSize = 32 * 1024 * 1024 // 32 MB
 func validateBodyFileMutex(bodyFlag, bodyFile string, validatePath func(string) error) error {
 	bodyEmpty := strings.TrimSpace(bodyFlag) == ""
 	if !bodyEmpty && bodyFile != "" {
-		return output.ErrValidation("--body and --body-file are mutually exclusive; pass exactly one")
+		return mailValidationError("--body and --body-file are mutually exclusive; pass exactly one").
+			WithParams(
+				mailInvalidParam("--body", "mutually exclusive with --body-file"),
+				mailInvalidParam("--body-file", "mutually exclusive with --body"),
+			)
 	}
 	if bodyFile != "" {
 		if err := validatePath(bodyFile); err != nil {
-			return output.ErrValidation("--body-file: %v", err)
+			return mailValidationParamError("--body-file", "--body-file: %v", err).WithCause(err)
 		}
 	}
 	return nil
@@ -79,7 +82,7 @@ func resolveBodyFromFlags(runtime *common.RuntimeContext) (string, error) {
 
 func validateRequiredResolvedBody(body string, hasTemplate bool, message string) error {
 	if !hasTemplate && strings.TrimSpace(body) == "" {
-		return output.ErrValidation(message)
+		return mailValidationError("%s", message)
 	}
 	return nil
 }
@@ -95,15 +98,15 @@ func validateRequiredResolvedBody(body string, hasTemplate bool, message string)
 func readBodyFile(fio fileio.FileIO, path string) (string, error) {
 	f, err := fio.Open(path)
 	if err != nil {
-		return "", output.ErrValidation("open --body-file %s: %v", path, err)
+		return "", mailValidationParamError("--body-file", "open --body-file %s: %v", path, err).WithCause(mailInputStatError(err))
 	}
 	defer f.Close()
 	buf, err := io.ReadAll(io.LimitReader(f, maxBodyFileSize+1))
 	if err != nil {
-		return "", output.ErrValidation("read --body-file %s: %v", path, err)
+		return "", mailValidationParamError("--body-file", "read --body-file %s: %v", path, err).WithCause(err)
 	}
 	if len(buf) > maxBodyFileSize {
-		return "", output.ErrValidation("--body-file: file exceeds %d MB limit", maxBodyFileSize/1024/1024)
+		return "", mailValidationParamError("--body-file", "--body-file: file exceeds %d MB limit", maxBodyFileSize/1024/1024)
 	}
 	return string(buf), nil
 }

shortcuts/mail/draft/charset.go

@@ -49,7 +49,7 @@ func encodeTextCharset(body []byte, label string) ([]byte, error) {
 	}
 	enc, _ := htmlcharset.Lookup(label)
 	if enc == nil {
-		return nil, fmt.Errorf("unsupported charset %q", label)
+		return nil, fmt.Errorf("unsupported charset %q", label) //nolint:forbidigo // intermediate draft charset error; mail command layer wraps into typed ValidationError.
 	}
 	var buf bytes.Buffer
 	writer := transform.NewWriter(&buf, enc.NewEncoder())

shortcuts/mail/draft/large_attachment_parse.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft large-attachment parser errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/limits.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft attachment limit errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (