feat: surface search API notices

shortcuts/contact/contact_search_user.go

@@ -85,6 +85,7 @@ type searchUserAPIData struct {
 	Items     []searchUserAPIItem `json:"items"`
 	HasMore   bool                `json:"has_more"`
 	PageToken string              `json:"page_token"`
+	Notice    string              `json:"notice"`
 }
 
 type searchUserAPIItem struct {
@@ -126,6 +127,7 @@ type searchUser struct {
 type searchUserResponse struct {
 	Users   []searchUser `json:"users"`
 	HasMore bool         `json:"has_more"`
+	Notice  string       `json:"notice,omitempty"`
 }
 
 var ContactSearchUser = common.Shortcut{
@@ -189,13 +191,15 @@ var ContactSearchUser = common.Shortcut{
 	Execute: executeSearchUser,
 }
 
+// executeSearchUser dispatches contact search to single-query or fanout mode.
 func executeSearchUser(ctx context.Context, runtime *common.RuntimeContext) error {
 	if strings.TrimSpace(runtime.Str("queries")) != "" {
 		return executeSearchUserFanout(ctx, runtime)
 	}
 	return executeSearchUserSingle(ctx, runtime)
 }
 
+// executeSearchUserSingle performs one contact search and preserves server notices.
 func executeSearchUserSingle(ctx context.Context, runtime *common.RuntimeContext) error {
 	body, err := buildSearchUserBody(runtime)
 	if err != nil {
@@ -222,7 +226,7 @@ func executeSearchUserSingle(ctx context.Context, runtime *common.RuntimeContext
 	}
 
 	users, hasMore := projectUsers(respData, runtime.Str("lang"), runtime.Config.Brand)
-	out := searchUserResponse{Users: users, HasMore: hasMore}
+	out := searchUserResponse{Users: users, HasMore: hasMore, Notice: respData.Notice}
 
 	runtime.OutFormat(out, &output.Meta{Count: len(users)}, func(w io.Writer) {
 		if len(users) == 0 {

shortcuts/contact/contact_search_user_fanout.go

@@ -45,22 +45,17 @@ type fanoutResult struct {
 	Query   string
 	Users   []searchUser
 	HasMore bool
+	Notice  string
 	ErrMsg  string // empty = success
 	Err     error  // original failure, kept for typed all-failed propagation
 }
 
-// isFanoutSummaryFormat gates the per-fanout stderr summary line. Includes csv
-// because that summary lives on stderr and never corrupts the csv stream on
-// stdout — single-query mode keeps the narrower isHumanReadableFormat predicate
-// for its refine hint, so adding csv here doesn't regress that path.
+// isFanoutSummaryFormat gates the per-fanout stderr summary line.
 func isFanoutSummaryFormat(format string) bool {
 	return format == "pretty" || format == "table" || format == "csv"
 }
 
-// runOneQuery converts every failure mode (transport, HTTP status, parse,
-// API code) into an ErrMsg string instead of returning a Go error. The
-// fanout dispatcher (Task 6) relies on this so a single failed query never
-// short-circuits the remaining workers.
+// runOneQuery converts one fanout request into either users or an error summary.
 func runOneQuery(ctx context.Context, runtime *common.RuntimeContext, index int, query string,
 	filter *searchUserAPIFilter) fanoutResult {
 	// Pre-check ctx so queued workers see cancellation before issuing a
@@ -94,9 +89,10 @@ func runOneQuery(ctx context.Context, runtime *common.RuntimeContext, index int,
 	}
 
 	users, hasMore := projectUsers(respData, runtime.Str("lang"), runtime.Config.Brand)
-	return fanoutResult{Index: index, Query: query, Users: users, HasMore: hasMore}
+	return fanoutResult{Index: index, Query: query, Users: users, HasMore: hasMore, Notice: respData.Notice}
 }
 
+// fanoutErrorResult records a failed fanout query without stopping other workers.
 func fanoutErrorResult(index int, query string, err error) fanoutResult {
 	if err == nil {
 		return fanoutResult{Index: index, Query: query}
@@ -113,17 +109,16 @@ type querySummary struct {
 	Query   string `json:"query"`
 	Error   string `json:"error,omitempty"`
 	HasMore bool   `json:"has_more"`
+	Notice  string `json:"notice,omitempty"`
 }
 
 type fanoutResponse struct {
 	Users   []fanoutUser   `json:"users"`
 	Queries []querySummary `json:"queries"`
+	Notice  string         `json:"notice,omitempty"`
 }
 
-// buildFanoutResponse walks results by Index (input order), flattens users[]
-// with matched_query, lists every input in queries[] (including successes),
-// and returns an error only when every query failed. The error wraps the
-// first failing query's ErrMsg so the CLI exits non-zero on full failure.
+// buildFanoutResponse flattens ordered fanout results and fails only when all queries fail.
 func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutResponse, error) {
 	indexed := make([]fanoutResult, len(queries))
 	for _, r := range results {
@@ -142,6 +137,7 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 			Query:   queries[i],
 			Error:   r.ErrMsg,
 			HasMore: r.HasMore,
+			Notice:  r.Notice,
 		})
 		if r.ErrMsg != "" {
 			failed++
@@ -152,6 +148,9 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 			}
 			continue
 		}
+		if out.Notice == "" {
+			out.Notice = r.Notice
+		}
 		for _, u := range r.Users {
 			out.Users = append(out.Users, fanoutUser{searchUser: u, MatchedQuery: queries[i]})
 		}

shortcuts/contact/contact_search_user_test.go

@@ -562,13 +562,15 @@ func mountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Fact
 	return parent.Execute()
 }
 
+// searchUserStub returns a representative user search response with a notice.
 func searchUserStub() *httpmock.Stub {
 	return &httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/contact/v3/users/search",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "ok",
 			"data": map[string]interface{}{
+				"notice": "The query is too long and has been truncated to the first 50 characters for search.",
 				"items": []interface{}{
 					map[string]interface{}{
 						"id": "ou_a",
@@ -590,6 +592,7 @@ func searchUserStub() *httpmock.Stub {
 	}
 }
 
+// TestSearchUser_Integration_PrettyRendersExpectedColumns verifies human output columns.
 func TestSearchUser_Integration_PrettyRendersExpectedColumns(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
 	reg.Register(searchUserStub())
@@ -614,6 +617,7 @@ func TestSearchUser_Integration_PrettyRendersExpectedColumns(t *testing.T) {
 	}
 }
 
+// TestSearchUser_Integration_JSONStructuredFields verifies normalized JSON and notices.
 func TestSearchUser_Integration_JSONStructuredFields(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
 	reg.Register(searchUserStub())
@@ -631,6 +635,9 @@ func TestSearchUser_Integration_JSONStructuredFields(t *testing.T) {
 	if !ok {
 		t.Fatalf("envelope.data: expected object, got %v\nraw=%s", got["data"], stdout.String())
 	}
+	if data["notice"] != "The query is too long and has been truncated to the first 50 characters for search." {
+		t.Fatalf("data.notice = %v", data["notice"])
+	}
 	users, _ := data["users"].([]interface{})
 	if len(users) != 1 {
 		t.Fatalf("users: expected 1, got %d (output=%s)", len(users), stdout.String())
@@ -1358,6 +1365,7 @@ func TestSearchUser_Integration_NoAutoPaginationFlags(t *testing.T) {
 	}
 }
 
+// TestFanout_FilterAppliedToEachQuery verifies shared fanout filters reach every request.
 func TestFanout_FilterAppliedToEachQuery(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
 	stub := &httpmock.Stub{
@@ -1399,13 +1407,15 @@ func TestFanout_FilterAppliedToEachQuery(t *testing.T) {
 	}
 }
 
+// TestFanout_PartialFailure_ExitZero verifies partial fanout failures keep notices.
 func TestFanout_PartialFailure_ExitZero(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
 	reg.Register(&httpmock.Stub{
 		Method: "POST", URL: "/open-apis/contact/v3/users/search",
 		BodyFilter: func(b []byte) bool { return strings.Contains(string(b), `"alice"`) },
 		Body: map[string]interface{}{"code": 0, "msg": "ok",
 			"data": map[string]interface{}{
+				"notice":   "The query is too long and has been truncated to the first 50 characters for search.",
 				"items":    []interface{}{map[string]interface{}{"id": "ou_a"}},
 				"has_more": false,
 			}},
@@ -1432,10 +1442,17 @@ func TestFanout_PartialFailure_ExitZero(t *testing.T) {
 	if len(users) != 1 {
 		t.Errorf("users: expected 1 (alice), got %d; stdout=%s", len(users), stdout.String())
 	}
+	if data["notice"] != "The query is too long and has been truncated to the first 50 characters for search." {
+		t.Fatalf("data.notice = %v", data["notice"])
+	}
 	queries := data["queries"].([]interface{})
 	if len(queries) != 2 {
 		t.Fatalf("queries: expected 2, got %d", len(queries))
 	}
+	q0 := queries[0].(map[string]interface{})
+	if q0["notice"] != "The query is too long and has been truncated to the first 50 characters for search." {
+		t.Fatalf("queries[0].notice = %v", q0["notice"])
+	}
 	q1 := queries[1].(map[string]interface{})
 	if !strings.HasPrefix(q1["error"].(string), "HTTP 500") {
 		t.Errorf("queries[1].error: got %q", q1["error"])

shortcuts/doc/docs_search.go

@@ -74,6 +74,9 @@ var DocsSearch = common.Shortcut{
 			"page_token": data["page_token"],
 			"results":    normalizedItems,
 		}
+		if notice, _ := data["notice"].(string); notice != "" {
+			resultData["notice"] = notice
+		}
 
 		runtime.OutFormat(resultData, &output.Meta{Count: len(normalizedItems)}, func(w io.Writer) {
 			if len(normalizedItems) == 0 {

shortcuts/doc/docs_search_test.go

@@ -7,8 +7,48 @@ import (
 	"encoding/json"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
 )
 
+// TestDocsSearchExecutePassesThroughNotice verifies docs +search preserves notices.
+func TestDocsSearchExecutePassesThroughNotice(t *testing.T) {
+	const notice = "The query is too long and has been truncated to the first 50 characters for search."
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-search-notice"))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/search/v2/doc_wiki/search",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"notice":     notice,
+				"res_units":  []interface{}{},
+				"total":      0,
+				"has_more":   false,
+				"page_token": "",
+			},
+		},
+	})
+
+	if err := mountAndRunDocs(t, DocsSearch, []string{"+search", "--query", "incident", "--format", "json", "--as", "user"}, f, stdout); err != nil {
+		t.Fatalf("DocsSearch.Execute() error = %v", err)
+	}
+	reg.Verify(t)
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal(stdout) error = %v\nstdout=%s", err, stdout.String())
+	}
+	data, _ := env["data"].(map[string]interface{})
+	if got, _ := data["notice"].(string); got != notice {
+		t.Fatalf("data.notice = %q, want %q; data=%#v", got, notice, data)
+	}
+}
+
+// TestAddIsoTimeFieldsSupportsJSONNumber verifies JSON numbers get ISO fields.
 func TestAddIsoTimeFieldsSupportsJSONNumber(t *testing.T) {
 	t.Parallel()
 

shortcuts/drive/drive_search.go

@@ -149,6 +149,9 @@ var DriveSearch = common.Shortcut{
 			"page_token": data["page_token"],
 			"results":    normalizedItems,
 		}
+		if notice, _ := data["notice"].(string); notice != "" {
+			resultData["notice"] = notice
+		}
 
 		runtime.OutFormat(resultData, &output.Meta{Count: len(normalizedItems)}, func(w io.Writer) {
 			renderDriveSearchTable(w, data, normalizedItems)

shortcuts/drive/drive_search_test.go

@@ -14,12 +14,49 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/errclass"
+	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
 )
 
-// TestClampOpenedTimeWindow covers the 3-month / 1-year boundary logic that
-// narrows --opened-since / --opened-until and generates the multi-slice notice.
+// TestDriveSearchExecutePassesThroughNotice verifies drive +search preserves notices.
+func TestDriveSearchExecutePassesThroughNotice(t *testing.T) {
+	const notice = "The query is too long and has been truncated to the first 50 characters for search."
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/search/v2/doc_wiki/search",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"notice":     notice,
+				"res_units":  []interface{}{},
+				"total":      0,
+				"has_more":   false,
+				"page_token": "",
+			},
+		},
+	})
+
+	if err := mountAndRunDrive(t, DriveSearch, []string{"+search", "--query", "incident", "--format", "json", "--as", "user"}, f, stdout); err != nil {
+		t.Fatalf("DriveSearch.Execute() error = %v", err)
+	}
+	reg.Verify(t)
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal(stdout) error = %v\nstdout=%s", err, stdout.String())
+	}
+	data, _ := env["data"].(map[string]interface{})
+	if got, _ := data["notice"].(string); got != notice {
+		t.Fatalf("data.notice = %q, want %q; data=%#v", got, notice, data)
+	}
+}
+
+// TestClampOpenedTimeWindow covers opened-time clamping and slice notices.
 func TestClampOpenedTimeWindow(t *testing.T) {
 	t.Parallel()