feat(event): emit typed error envelopes across the event domain

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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/)
+      - 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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/event/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/)
         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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/event/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
       # errs-no-legacy-helper enforced on domains whose shared validation/save
       # helpers have migrated to typed final errors.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/event/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -18,6 +18,7 @@ var migratedCommonHelperPaths = []string{
 	"shortcuts/base/",
 	"shortcuts/calendar/",
 	"shortcuts/drive/",
+	"shortcuts/event/",
 	"shortcuts/mail/",
 	"shortcuts/okr/",
 	"shortcuts/task/",

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -19,6 +19,7 @@ var migratedEnvelopePaths = []string{
 	"shortcuts/base/",
 	"shortcuts/calendar/",
 	"shortcuts/drive/",
+	"shortcuts/event/",
 	"shortcuts/mail/",
 	"shortcuts/okr/",
 	"shortcuts/task/",

shortcuts/event/errors.go

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package event
+
+import "github.com/larksuite/cli/errs"
+
+func eventValidationError(format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func eventValidationParamError(param, format string, args ...any) *errs.ValidationError {
+	return eventValidationError(format, args...).WithParam(param)
+}
+
+// eventValidationParamErrorWithCause appends ": <err>" to the formatted
+// message and preserves err as the unwrap cause.
+func eventValidationParamErrorWithCause(err error, param, format string, args ...any) *errs.ValidationError {
+	return eventValidationParamError(param, format+": %s", append(args, err)...).WithCause(err)
+}
+
+// eventFileIOError appends ": <err>" to the formatted message and preserves
+// err as the unwrap cause.
+func eventFileIOError(err error, format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeFileIO, format+": %s", append(args, err)...).WithCause(err)
+}
+
+// eventNetworkError appends ": <err>" to the formatted message and preserves
+// err as the unwrap cause.
+func eventNetworkError(err error, format string, args ...any) *errs.NetworkError {
+	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format+": %s", append(args, err)...).WithCause(err)
+}

shortcuts/event/pipeline.go

@@ -63,13 +63,13 @@ func NewEventPipeline(
 func (p *EventPipeline) EnsureDirs() error {
 	if p.config.OutputDir != "" {
 		if err := vfs.MkdirAll(p.config.OutputDir, 0700); err != nil {
-			return fmt.Errorf("create output dir: %w", err)
+			return eventFileIOError(err, "create output dir")
 		}
 	}
 	if p.config.Router != nil {
 		for _, route := range p.config.Router.routes {
 			if err := vfs.MkdirAll(route.dir, 0700); err != nil {
-				return fmt.Errorf("create route dir %s: %w", route.dir, err)
+				return eventFileIOError(err, "create route dir %s", route.dir)
 			}
 		}
 	}

shortcuts/event/processor_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
 	"os"
 	"path/filepath"
@@ -15,7 +16,12 @@ import (
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/shortcuts/common"
 	larkevent "github.com/larksuite/oapi-sdk-go/v3/event"
+	"github.com/spf13/cobra"
 )
 
 // chdirTemp changes cwd to a fresh temp dir for the test duration.
@@ -44,6 +50,87 @@ func makeRawEvent(eventType string, eventJSON string) *RawEvent {
 	}
 }
 
+func requireProblem(t *testing.T, err error, category errs.Category, subtype errs.Subtype, param string) {
+	t.Helper()
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf(%T) = false, error: %v", err, err)
+	}
+	if p.Category != category || p.Subtype != subtype {
+		t.Fatalf("problem = %s/%s, want %s/%s", p.Category, p.Subtype, category, subtype)
+	}
+	if param != "" {
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) {
+			t.Fatalf("error %T is not *errs.ValidationError", err)
+		}
+		if ve.Param != param {
+			t.Fatalf("Param = %q, want %q", ve.Param, param)
+		}
+	}
+}
+
+func TestEventTypedErrorHelpers(t *testing.T) {
+	cause := errors.New("cause")
+
+	validation := eventValidationError("bad input")
+	requireProblem(t, validation, errs.CategoryValidation, errs.SubtypeInvalidArgument, "")
+
+	paramErr := eventValidationParamErrorWithCause(cause, "--flag", "bad %s value", "flag")
+	requireProblem(t, paramErr, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--flag")
+	if got := paramErr.Error(); got != "bad flag value: cause" {
+		t.Fatalf("message = %q, want %q", got, "bad flag value: cause")
+	}
+	if !errors.Is(paramErr, cause) {
+		t.Fatal("validation error should preserve its cause")
+	}
+
+	fileErr := eventFileIOError(cause, "write failed")
+	requireProblem(t, fileErr, errs.CategoryInternal, errs.SubtypeFileIO, "")
+	if got := fileErr.Error(); got != "write failed: cause" {
+		t.Fatalf("message = %q, want %q", got, "write failed: cause")
+	}
+	if !errors.Is(fileErr, cause) {
+		t.Fatal("file_io error should preserve its cause")
+	}
+
+	networkErr := eventNetworkError(cause, "websocket failed")
+	requireProblem(t, networkErr, errs.CategoryNetwork, errs.SubtypeNetworkTransport, "")
+	if got := networkErr.Error(); got != "websocket failed: cause" {
+		t.Fatalf("message = %q, want %q", got, "websocket failed: cause")
+	}
+	if !errors.Is(networkErr, cause) {
+		t.Fatal("network error should preserve its cause")
+	}
+}
+
+func newSubscribeTestRuntime(t *testing.T) *common.RuntimeContext {
+	t.Helper()
+
+	var out, errOut bytes.Buffer
+	cmd := &cobra.Command{Use: "+subscribe"}
+	cmd.Flags().String("event-types", "", "")
+	cmd.Flags().String("filter", "", "")
+	cmd.Flags().Bool("json", false, "")
+	cmd.Flags().Bool("compact", false, "")
+	cmd.Flags().String("output-dir", "", "")
+	cmd.Flags().Bool("quiet", false, "")
+	cmd.Flags().StringArray("route", nil, "")
+	cmd.Flags().Bool("force", false, "")
+
+	return &common.RuntimeContext{
+		Cmd: cmd,
+		Config: &core.CliConfig{
+			AppID:     "cli_event_test",
+			AppSecret: "secret",
+			Brand:     core.BrandFeishu,
+		},
+		Factory: &cmdutil.Factory{
+			IOStreams: cmdutil.NewIOStreams(strings.NewReader(""), &out, &errOut),
+		},
+	}
+}
+
 // --- Registry ---
 
 func TestRegistryLookup(t *testing.T) {
@@ -63,9 +150,11 @@ func TestRegistryDuplicateReturnsError(t *testing.T) {
 	if err := r.Register(&ImMessageProcessor{}); err != nil {
 		t.Fatalf("first register should succeed: %v", err)
 	}
-	if err := r.Register(&ImMessageProcessor{}); err == nil {
+	err := r.Register(&ImMessageProcessor{})
+	if err == nil {
 		t.Error("expected error on duplicate registration")
 	}
+	requireProblem(t, err, errs.CategoryInternal, errs.SubtypeUnknown, "")
 }
 
 // --- Filters ---
@@ -106,6 +195,54 @@ func TestRegexFilter_Invalid(t *testing.T) {
 	}
 }
 
+func TestEventSubscribeExecuteRejectsUnsafeOutputDir(t *testing.T) {
+	rt := newSubscribeTestRuntime(t)
+	if err := rt.Cmd.Flags().Set("output-dir", "/tmp/events"); err != nil {
+		t.Fatal(err)
+	}
+	err := EventSubscribe.Execute(context.Background(), rt)
+	if err == nil {
+		t.Fatal("expected unsafe output-dir error")
+	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--output-dir")
+	if errors.Unwrap(err) == nil {
+		t.Fatal("unsafe output-dir error should preserve its cause")
+	}
+}
+
+func TestEventSubscribeExecuteRejectsInvalidFilter(t *testing.T) {
+	rt := newSubscribeTestRuntime(t)
+	if err := rt.Cmd.Flags().Set("force", "true"); err != nil {
+		t.Fatal(err)
+	}
+	if err := rt.Cmd.Flags().Set("filter", "[invalid"); err != nil {
+		t.Fatal(err)
+	}
+	err := EventSubscribe.Execute(context.Background(), rt)
+	if err == nil {
+		t.Fatal("expected invalid filter error")
+	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--filter")
+	if errors.Unwrap(err) == nil {
+		t.Fatal("invalid filter error should preserve its cause")
+	}
+}
+
+func TestEventSubscribeExecuteRejectsInvalidRoute(t *testing.T) {
+	rt := newSubscribeTestRuntime(t)
+	if err := rt.Cmd.Flags().Set("force", "true"); err != nil {
+		t.Fatal(err)
+	}
+	if err := rt.Cmd.Flags().Set("route", "no-equals-sign"); err != nil {
+		t.Fatal(err)
+	}
+	err := EventSubscribe.Execute(context.Background(), rt)
+	if err == nil {
+		t.Fatal("expected invalid route error")
+	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
+}
+
 func TestFilterChain(t *testing.T) {
 	etf := NewEventTypeFilter("im.message.receive_v1, drive.file.edit_v1")
 	rf, _ := NewRegexFilter("im\\..*")
@@ -339,6 +476,23 @@ func TestPipeline_OutputDir(t *testing.T) {
 	}
 }
 
+func TestPipeline_EnsureDirsFileIOError(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "not-a-dir")
+	if err := os.WriteFile(path, []byte("x"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	p := NewEventPipeline(DefaultRegistry(), NewFilterChain(),
+		PipelineConfig{Mode: TransformCompact, OutputDir: filepath.Join(path, "child")}, io.Discard, io.Discard)
+	err := p.EnsureDirs()
+	if err == nil {
+		t.Fatal("expected file_io error")
+	}
+	requireProblem(t, err, errs.CategoryInternal, errs.SubtypeFileIO, "")
+	if errors.Unwrap(err) == nil {
+		t.Fatal("file_io error should preserve its cause")
+	}
+}
+
 // --- Pipeline: JsonFlag ---
 
 func TestPipeline_JsonFlag(t *testing.T) {
@@ -608,20 +762,26 @@ func TestParseRoutes_MissingEquals(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for missing =")
 	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_InvalidRegex(t *testing.T) {
 	_, err := ParseRoutes([]string{"[invalid=dir:./foo/"})
 	if err == nil {
 		t.Error("expected error for invalid regex")
 	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
+	if errors.Unwrap(err) == nil {
+		t.Fatal("invalid regex error should preserve its cause")
+	}
 }
 
 func TestParseRoutes_MissingPrefix(t *testing.T) {
 	_, err := ParseRoutes([]string{`^im\.message=./messages/`})
 	if err == nil {
 		t.Error("expected error for missing dir: prefix")
 	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 	if !strings.Contains(err.Error(), "dir:") {
 		t.Errorf("error should mention dir: prefix, got: %v", err)
 	}
@@ -632,20 +792,23 @@ func TestParseRoutes_EmptyPath(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for empty path")
 	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_RejectsAbsolutePath(t *testing.T) {
 	_, err := ParseRoutes([]string{`^test=dir:/tmp/evil`})
 	if err == nil {
 		t.Error("expected error for absolute path in route")
 	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_RejectsTraversal(t *testing.T) {
 	_, err := ParseRoutes([]string{`^test=dir:../../etc/evil`})
 	if err == nil {
 		t.Error("expected error for path traversal in route")
 	}
+	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_PathSafety(t *testing.T) {

shortcuts/event/registry.go

@@ -3,7 +3,7 @@
 
 package event
 
-import "fmt"
+import "github.com/larksuite/cli/errs"
 
 // ProcessorRegistry manages event_type → EventProcessor mappings.
 type ProcessorRegistry struct {
@@ -23,7 +23,7 @@ func NewProcessorRegistry(fallback EventProcessor) *ProcessorRegistry {
 func (r *ProcessorRegistry) Register(p EventProcessor) error {
 	et := p.EventType()
 	if _, exists := r.processors[et]; exists {
-		return fmt.Errorf("duplicate event processor for: %s", et)
+		return errs.NewInternalError(errs.SubtypeUnknown, "duplicate event processor for: %s", et)
 	}
 	r.processors[et] = p
 	return nil

shortcuts/event/router.go

@@ -4,7 +4,6 @@
 package event
 
 import (
-	"fmt"
 	"regexp"
 	"strings"
 
@@ -34,27 +33,27 @@ func ParseRoutes(specs []string) (*EventRouter, error) {
 	for _, spec := range specs {
 		parts := strings.SplitN(spec, "=", 2)
 		if len(parts) != 2 {
-			return nil, fmt.Errorf("invalid route %q: expected format regex=dir:./path", spec)
+			return nil, eventValidationParamError("--route", "invalid --route %q: expected format regex=dir:./path", spec)
 		}
 		pattern := parts[0]
 		target := parts[1]
 
 		re, err := regexp.Compile(pattern)
 		if err != nil {
-			return nil, fmt.Errorf("invalid regex in route %q: %w", spec, err)
+			return nil, eventValidationParamErrorWithCause(err, "--route", "invalid regex in --route %q", spec)
 		}
 
 		if !strings.HasPrefix(target, "dir:") {
-			return nil, fmt.Errorf("invalid route target %q: must start with \"dir:\" prefix (format: regex=dir:./path)", target)
+			return nil, eventValidationParamError("--route", "invalid --route target %q: must start with \"dir:\" prefix (format: regex=dir:./path)", target)
 		}
 		dir := strings.TrimPrefix(target, "dir:")
 		if dir == "" {
-			return nil, fmt.Errorf("invalid route %q: directory path is empty", spec)
+			return nil, eventValidationParamError("--route", "invalid --route %q: directory path is empty", spec)
 		}
 
 		safeDir, err := validate.SafeOutputPath(dir)
 		if err != nil {
-			return nil, fmt.Errorf("invalid route %q: %w", spec, err)
+			return nil, eventValidationParamErrorWithCause(err, "--route", "invalid --route %q", spec)
 		}
 
 		routes = append(routes, Route{pattern: re, dir: safeDir})