feat(minutes): add minutes edit shortcuts

shortcuts/minutes/minutes_speaker_replace.go

@@ -0,0 +1,139 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	minutesSpeakerReplaceSpeakerNotFoundCode = 2091001
+	minutesSpeakerReplaceNoEditPermission    = 2091005
+)
+
+// MinutesSpeakerReplace replaces a speaker in a minute's transcript.
+var MinutesSpeakerReplace = common.Shortcut{
+	Service:     "minutes",
+	Command:     "+speaker-replace",
+	Description: "Replace a speaker in a minute's transcript (rebind from one user to another)",
+	Risk:        "write",
+	Scopes:      []string{"minutes:minutes:update"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "minute-token", Desc: "minute token", Required: true},
+		{Name: "from-user-id", Desc: "speaker to replace, must be an open_id starting with 'ou_'", Required: true},
+		{Name: "to-user-id", Desc: "new speaker, must be an open_id starting with 'ou_'", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
+		if minuteToken == "" {
+			return output.ErrValidation("--minute-token is required")
+		}
+		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
+		if fromUserID == "" {
+			return output.ErrValidation("--from-user-id is required")
+		}
+		if _, err := common.ValidateUserID(fromUserID); err != nil {
+			return output.ErrValidation("--from-user-id: %s", err)
+		}
+		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
+		if toUserID == "" {
+			return output.ErrValidation("--to-user-id is required")
+		}
+		if _, err := common.ValidateUserID(toUserID); err != nil {
+			return output.ErrValidation("--to-user-id: %s", err)
+		}
+		if fromUserID == toUserID {
+			return output.ErrValidation("--from-user-id and --to-user-id must be different")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
+		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
+		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
+		return common.NewDryRunAPI().
+			PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
+			Body(map[string]interface{}{
+				"minute_token": minuteToken,
+				"from_user_id": fromUserID,
+				"to_user_id":   toUserID,
+			})
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
+		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
+		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
+
+		body := map[string]interface{}{
+			"minute_token": minuteToken,
+			"from_user_id": fromUserID,
+			"to_user_id":   toUserID,
+		}
+
+		_, err := runtime.CallAPI(http.MethodPut,
+			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
+			nil, body)
+		if err != nil {
+			return minutesSpeakerReplaceError(err, minuteToken, fromUserID)
+		}
+
+		outData := map[string]interface{}{
+			"minute_token": minuteToken,
+			"from_user_id": fromUserID,
+			"to_user_id":   toUserID,
+		}
+
+		runtime.OutFormat(outData, nil, nil)
+		return nil
+	},
+}
+
+func minutesSpeakerReplaceError(err error, minuteToken, fromUserID string) error {
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		return err
+	}
+
+	switch exitErr.Detail.Code {
+	case minutesSpeakerReplaceNoEditPermission:
+		return &output.ExitError{
+			Code: output.ExitAPI,
+			Detail: &output.ErrDetail{
+				Type:    "no_edit_permission",
+				Code:    minutesSpeakerReplaceNoEditPermission,
+				Message: fmt.Sprintf("No edit permission for minute %q: cannot replace the transcript speaker.", minuteToken),
+				Hint:    "Ask the minute owner for minute edit permission",
+				Detail:  exitErr.Detail.Detail,
+			},
+			Err: err,
+		}
+	case minutesSpeakerReplaceSpeakerNotFoundCode:
+		return &output.ExitError{
+			Code: output.ExitAPI,
+			Detail: &output.ErrDetail{
+				Type:    "speaker_not_found",
+				Code:    minutesSpeakerReplaceSpeakerNotFoundCode,
+				Message: fmt.Sprintf("Speaker not found in minute %q: --from-user-id %q does not match an existing speaker in the transcript.", minuteToken, fromUserID),
+				Hint:    "Check --minute-token and --from-user-id. Use an open_id for a speaker that appears in the minute transcript, then retry.",
+				Detail:  exitErr.Detail.Detail,
+			},
+			Err: err,
+		}
+	}
+
+	return err
+}

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -0,0 +1,247 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+const minutesSpeakerReplaceTestToken = "obcnexampleminute"
+
+func TestMinutesSpeakerReplace_Validate(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	tests := []struct {
+		name    string
+		args    []string
+		wantErr string
+	}{
+		{
+			name:    "missing minute token",
+			args:    []string{"+speaker-replace", "--from-user-id", "ou_a", "--to-user-id", "ou_b", "--as", "user"},
+			wantErr: "required flag(s) \"minute-token\" not set",
+		},
+		{
+			name:    "missing from",
+			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--to-user-id", "ou_b", "--as", "user"},
+			wantErr: "required flag(s) \"from-user-id\" not set",
+		},
+		{
+			name:    "missing to",
+			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_a", "--as", "user"},
+			wantErr: "required flag(s) \"to-user-id\" not set",
+		},
+		{
+			name:    "invalid from prefix",
+			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "u_a", "--to-user-id", "ou_b", "--as", "user"},
+			wantErr: "--from-user-id",
+		},
+		{
+			name:    "invalid to prefix",
+			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_a", "--to-user-id", "u_b", "--as", "user"},
+			wantErr: "--to-user-id",
+		},
+		{
+			name:    "from equals to",
+			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_same", "--to-user-id", "ou_same", "--as", "user"},
+			wantErr: "must be different",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "minutes"}
+			MinutesSpeakerReplace.Mount(parent, f)
+			parent.SetArgs(tt.args)
+			parent.SilenceErrors = true
+			parent.SilenceUsage = true
+			err := parent.Execute()
+			if err == nil {
+				t.Fatalf("expected error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error should contain %q, got: %s", tt.wantErr, err.Error())
+			}
+		})
+	}
+}
+
+func TestMinutesSpeakerReplace_DryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-user-id", "ou_old_speaker",
+		"--to-user-id", "ou_new_speaker",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "PUT") {
+		t.Errorf("expected PUT method, got:\n%s", out)
+	}
+	if !strings.Contains(out, "/open-apis/minutes/v1/minutes/"+minutesSpeakerReplaceTestToken+"/transcript/speaker") {
+		t.Errorf("expected speaker endpoint, got:\n%s", out)
+	}
+	if !strings.Contains(out, "ou_old_speaker") {
+		t.Errorf("expected from_user_id in body, got:\n%s", out)
+	}
+	if !strings.Contains(out, "ou_new_speaker") {
+		t.Errorf("expected to_user_id in body, got:\n%s", out)
+	}
+}
+
+func TestMinutesSpeakerReplace_Execute(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodPut,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-user-id", "ou_old_speaker",
+		"--to-user-id", "ou_new_speaker",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var envelope struct {
+		Data struct {
+			MinuteToken string `json:"minute_token"`
+			FromUserID  string `json:"from_user_id"`
+			ToUserID    string `json:"to_user_id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v", err)
+	}
+	if envelope.Data.MinuteToken != minutesSpeakerReplaceTestToken {
+		t.Errorf("data.minute_token = %q, want %q", envelope.Data.MinuteToken, minutesSpeakerReplaceTestToken)
+	}
+	if envelope.Data.FromUserID != "ou_old_speaker" {
+		t.Errorf("data.from_user_id = %q, want ou_old_speaker", envelope.Data.FromUserID)
+	}
+	if envelope.Data.ToUserID != "ou_new_speaker" {
+		t.Errorf("data.to_user_id = %q, want ou_new_speaker", envelope.Data.ToUserID)
+	}
+}
+
+func TestMinutesSpeakerReplace_SpeakerNotFound(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodPut,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
+		Body: map[string]interface{}{
+			"code": 2091001,
+			"msg":  "speaker not exist",
+		},
+	})
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-user-id", "ou_missing_speaker",
+		"--to-user-id", "ou_new_speaker",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected speaker-not-found error, got nil")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Detail == nil {
+		t.Fatalf("expected structured error detail, got nil")
+	}
+	if exitErr.Detail.Type != "speaker_not_found" {
+		t.Errorf("error type = %q, want speaker_not_found", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "Speaker not found") {
+		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "ou_missing_speaker") {
+		t.Errorf("message should include missing speaker id, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "--from-user-id") {
+		t.Errorf("hint should mention --from-user-id, got: %s", exitErr.Detail.Hint)
+	}
+}
+
+func TestMinutesSpeakerReplace_NoEditPermission(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodPut,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
+		Body: map[string]interface{}{
+			"code": 2091005,
+			"msg":  "no edit permission",
+		},
+	})
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-user-id", "ou_old_speaker",
+		"--to-user-id", "ou_new_speaker",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected no-edit-permission error, got nil")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Detail == nil {
+		t.Fatalf("expected structured error detail, got nil")
+	}
+	if exitErr.Detail.Type != "no_edit_permission" {
+		t.Errorf("error type = %q, want no_edit_permission", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "No edit permission") {
+		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Message, minutesSpeakerReplaceTestToken) {
+		t.Errorf("message should include minute token, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "edit permission") {
+		t.Errorf("hint should mention edit permission, got: %s", exitErr.Detail.Hint)
+	}
+}