feat(approval): support approval event consumption

cmd/event/list_test.go

@@ -17,6 +17,8 @@ import (
 
 func TestEventLookup_VCMeetingLifecycleKeys(t *testing.T) {
 	for _, key := range []string{
+		"approval.instance.status_changed_v4",
+		"approval.task.status_changed_v4",
 		"vc.meeting.participant_meeting_started_v1",
 		"vc.meeting.participant_meeting_joined_v1",
 	} {
@@ -36,6 +38,8 @@ func TestRunList_TextOutput(t *testing.T) {
 	out := stdout.String()
 	for _, want := range []string{
 		"KEY", "AUTH", "PARAMS", "DESCRIPTION",
+		"approval.instance.status_changed_v4",
+		"approval.task.status_changed_v4",
 		"im.message.receive_v1",
 		"im.message.message_read_v1",
 		"task.task.update_user_access_v2",
@@ -90,6 +94,8 @@ func TestRunList_JSONOutput(t *testing.T) {
 		t.Fatal("event list JSON missing task.task.update_user_access_v2")
 	}
 	for _, want := range []string{
+		"approval.instance.status_changed_v4",
+		"approval.task.status_changed_v4",
 		"vc.meeting.participant_meeting_started_v1",
 		"vc.meeting.participant_meeting_joined_v1",
 	} {

cmd/event/schema_test.go

@@ -19,6 +19,29 @@ import (
 	_ "github.com/larksuite/cli/events"
 )
 
+type approvalSchemaJSONPayload struct {
+	JQRootPath           string                           `json:"jq_root_path"`
+	AuthTypes            []string                         `json:"auth_types"`
+	Scopes               []string                         `json:"scopes"`
+	Params               []approvalSchemaJSONParam        `json:"params"`
+	ResolvedOutputSchema approvalSchemaJSONResolvedSchema `json:"resolved_output_schema"`
+}
+
+type approvalSchemaJSONParam struct {
+	Name            string `json:"name"`
+	Type            string `json:"type"`
+	Required        bool   `json:"required"`
+	SubscriptionKey bool   `json:"subscription_key"`
+}
+
+type approvalSchemaJSONResolvedSchema struct {
+	Properties map[string]approvalSchemaJSONProperty `json:"properties"`
+}
+
+type approvalSchemaJSONProperty struct {
+	Format string `json:"format"`
+}
+
 func TestRunSchema_ProcessedKey_Text(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
 
@@ -158,6 +181,60 @@ func TestRunSchema_TaskUpdateUserAccessJSON(t *testing.T) {
 	}
 }
 
+func TestRunSchema_ApprovalStatusChangedJSON(t *testing.T) {
+	tests := []struct {
+		key   string
+		scope string
+	}{
+		{"approval.instance.status_changed_v4", "approval:instance:read"},
+		{"approval.task.status_changed_v4", "approval:task:read"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.key, func(t *testing.T) {
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
+
+			if err := runSchema(f, tc.key, true); err != nil {
+				t.Fatalf("runSchema json: %v", err)
+			}
+
+			var payload approvalSchemaJSONPayload
+			if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+				t.Fatalf("output is not valid JSON: %v\n%s", err, stdout.String())
+			}
+			if payload.JQRootPath != "." {
+				t.Errorf("jq_root_path = %v, want .", payload.JQRootPath)
+			}
+			if got := payload.AuthTypes; !reflect.DeepEqual(got, []string{"user"}) {
+				t.Errorf("auth_types = %#v, want user", got)
+			}
+			if got := payload.Scopes; !reflect.DeepEqual(got, []string{tc.scope}) {
+				t.Errorf("scopes = %#v, want %s", got, tc.scope)
+			}
+			if len(payload.Params) != 1 {
+				t.Fatalf("params = %#v, want one subscription_type param", payload.Params)
+			}
+			param := payload.Params[0]
+			if param.Name != "subscription_type" || param.Type != "multi" || param.Required || param.SubscriptionKey {
+				t.Fatalf("subscription_type param = %#v, want optional multi non-subscription-key param", param)
+			}
+			props := payload.ResolvedOutputSchema.Properties
+			for _, field := range []string{"type", "event_id", "timestamp", "approval_code", "instance_code", "status", "operate_time"} {
+				if _, ok := props[field]; !ok {
+					t.Errorf("approval schema missing flat field %q: %+v", field, props)
+				}
+			}
+			if _, ok := props["event"]; ok {
+				t.Errorf("approval Custom schema should be flat, got envelope field event: %+v", props)
+			}
+			if got := props["operate_time"].Format; got != "timestamp_ms" {
+				t.Errorf("operate_time format = %v, want timestamp_ms", got)
+			}
+		})
+	}
+}
+
 func TestRunSchema_JSONOutput_VCMeetingLifecycleKeys(t *testing.T) {
 	for _, key := range []string{
 		"vc.meeting.participant_meeting_started_v1",

events/approval/preconsume.go

@@ -0,0 +1,155 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package approval
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/event"
+)
+
+type approvalEventType string
+type approvalSubscriptionPath string
+
+type approvalSubscriptionConfig struct {
+	eventType     approvalEventType
+	subscribePath approvalSubscriptionPath
+}
+
+func approvalSubscriptionPreConsume(cfg approvalSubscriptionConfig) func(context.Context, event.APIClient, map[string]string) (func() error, error) {
+	return func(ctx context.Context, rt event.APIClient, params map[string]string) (func() error, error) {
+		if rt == nil {
+			return nil, errs.NewInternalError(errs.SubtypeUnknown,
+				"runtime API client is required for pre-consume subscription")
+		}
+
+		eventType := string(cfg.eventType)
+		subscribePath := string(cfg.subscribePath)
+		subscriptionTypes, err := approvalSubscriptionTypes(eventType, params)
+		if err != nil {
+			return nil, err
+		}
+
+		registered := make([]string, 0, len(subscriptionTypes))
+		for _, subscriptionType := range subscriptionTypes {
+			body := map[string]string{"subscription_type": subscriptionType}
+			if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+				return nil, approvalSubscriptionRegistrationError(eventType, registered, subscriptionType, err)
+			}
+			registered = append(registered, subscriptionType)
+		}
+
+		// Approval subscriptions are durable user-auth relations. Consuming events
+		// should not cancel that relation when this local process exits.
+		return nil, nil
+	}
+}
+
+func approvalSubscriptionTypes(eventType string, params map[string]string) ([]string, error) {
+	raw := strings.TrimSpace(params["subscription_type"])
+	if raw == "" {
+		return append([]string(nil), approvalAllSubscriptionTypes...), nil
+	}
+
+	values, err := parseApprovalSubscriptionTypeValues(raw)
+	if err != nil {
+		return nil, invalidApprovalSubscriptionTypeError(eventType, raw)
+	}
+
+	selected := make(map[string]bool, len(values))
+	for _, value := range values {
+		value = strings.TrimSpace(value)
+		switch value {
+		case approvalSubscriptionTypeInvolved, approvalSubscriptionTypeManaged:
+			selected[value] = true
+		default:
+			return nil, invalidApprovalSubscriptionTypeError(eventType, value)
+		}
+	}
+
+	result := make([]string, 0, len(selected))
+	for _, value := range approvalAllSubscriptionTypes {
+		if selected[value] {
+			result = append(result, value)
+		}
+	}
+	if len(result) == 0 {
+		return nil, invalidApprovalSubscriptionTypeError(eventType, raw)
+	}
+	return result, nil
+}
+
+func parseApprovalSubscriptionTypeValues(raw string) ([]string, error) {
+	if strings.HasPrefix(raw, "[") {
+		var values []string
+		if err := json.Unmarshal([]byte(raw), &values); err != nil {
+			return nil, err
+		}
+		return values, nil
+	}
+	return strings.Split(raw, ","), nil
+}
+
+func approvalSubscriptionRegistrationError(eventType string, registered []string, failed string, err error) error {
+	if err == nil {
+		return nil
+	}
+
+	msg := fmt.Sprintf(
+		"approval subscription pre-consume failed for EventKey %s: failed subscription_type %s",
+		eventType,
+		failed,
+	)
+	hint := fmt.Sprintf(
+		"no approval subscription relation was registered for EventKey %s; fix the cause and retry",
+		eventType,
+	)
+	if len(registered) > 0 {
+		msg = fmt.Sprintf(
+			"approval subscription pre-consume partially completed for EventKey %s: registered subscription_type(s) [%s], failed subscription_type %s",
+			eventType,
+			strings.Join(registered, ", "),
+			failed,
+		)
+		hint = fmt.Sprintf(
+			"server-side approval subscription relation(s) already registered for EventKey %s: %s; after fixing the cause, retry with --param subscription_type=%s to register the failed relation",
+			eventType,
+			strings.Join(registered, ", "),
+			failed,
+		)
+	}
+
+	if p, ok := errs.ProblemOf(err); ok {
+		if upstream := strings.TrimSpace(p.Message); upstream != "" {
+			p.Message = msg + ": " + upstream
+		} else {
+			p.Message = msg
+		}
+		if upstreamHint := strings.TrimSpace(p.Hint); upstreamHint != "" {
+			p.Hint = upstreamHint + "\n" + hint
+		} else {
+			p.Hint = hint
+		}
+		return err
+	}
+	return errs.NewInternalError(errs.SubtypeSDKError, "%s: %v", msg, err).
+		WithHint("%s", hint).
+		WithCause(err)
+}
+
+func invalidApprovalSubscriptionTypeError(eventType, value string) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument,
+		"invalid subscription_type for EventKey %s: %q", eventType, value).
+		WithParam("--param").
+		WithHint("omit subscription_type to register both approval subscription relations, or pass --param subscription_type=%s, --param subscription_type=%s, or --param subscription_type=%s,%s; run `lark-cli event schema %s` for details",
+			approvalSubscriptionTypeInvolved,
+			approvalSubscriptionTypeManaged,
+			approvalSubscriptionTypeInvolved,
+			approvalSubscriptionTypeManaged,
+			eventType)
+}