feat(people): publish people search in the API specification (#2094)

Stainless-Generated-From: f926e2e509baf334f272aa099fc4de6fb8f0f389

Author: stlc-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 39
+configured_endpoints: 40

pkg/cmd/cmd.go

@@ -181,6 +181,7 @@ func init() {
 				Suggest:  true,
 				Commands: []*cli.Command{
 					&peopleEnrich,
+					&peopleSearch,
 				},
 			},
 			{

pkg/cmd/person.go

@@ -145,6 +145,55 @@ var peopleEnrich = requestflag.WithInnerFlags(cli.Command{
 	},
 })
 
+var peopleSearch = requestflag.WithInnerFlags(cli.Command{
+	Name:    "search",
+	Usage:   "Find people with a natural-language query.",
+	Suggest: true,
+	Flags: []cli.Flag{
+		&requestflag.Flag[string]{
+			Name:     "query",
+			Usage:    "Describe the people to find.",
+			Required: true,
+			BodyPath: "query",
+		},
+		&requestflag.Flag[string]{
+			Name:     "cursor",
+			Usage:    "Use next_cursor with the same query and filters to fetch the next page.",
+			BodyPath: "cursor",
+		},
+		&requestflag.Flag[map[string]any]{
+			Name:     "filters",
+			Usage:    "Additional constraints every result must match.",
+			BodyPath: "filters",
+		},
+		&requestflag.Flag[[]string]{
+			Name:     "tag",
+			Usage:    "Labels for filtering usage in the dashboard.",
+			BodyPath: "tags",
+		},
+	},
+	Action:          handlePeopleSearch,
+	HideHelpCommand: true,
+}, map[string][]requestflag.HasOuterFlag{
+	"filters": {
+		&requestflag.InnerFlag[[]string]{
+			Name:       "filters.countries",
+			Usage:      "Countries people live in as two-letter codes, such as US or GB.",
+			InnerField: "countries",
+		},
+		&requestflag.InnerFlag[int64]{
+			Name:       "filters.years-of-experience-max",
+			Usage:      "Maximum years of professional experience.",
+			InnerField: "years_of_experience_max",
+		},
+		&requestflag.InnerFlag[int64]{
+			Name:       "filters.years-of-experience-min",
+			Usage:      "Minimum years of professional experience.",
+			InnerField: "years_of_experience_min",
+		},
+	},
+})
+
 func handlePeopleEnrich(ctx context.Context, cmd *cli.Command) error {
 	client := contextdev.NewClient(getDefaultRequestOptions(cmd)...)
 	unusedArgs := cmd.Args().Slice()
@@ -185,3 +234,44 @@ func handlePeopleEnrich(ctx context.Context, cmd *cli.Command) error {
 		Transform:      transform,
 	})
 }
+
+func handlePeopleSearch(ctx context.Context, cmd *cli.Command) error {
+	client := contextdev.NewClient(getDefaultRequestOptions(cmd)...)
+	unusedArgs := cmd.Args().Slice()
+
+	if len(unusedArgs) > 0 {
+		return fmt.Errorf("Unexpected extra arguments: %v", unusedArgs)
+	}
+
+	options, err := flagOptions(
+		cmd,
+		apiquery.NestedQueryFormatBrackets,
+		apiquery.ArrayQueryFormatComma,
+		ApplicationJSON,
+		false,
+	)
+	if err != nil {
+		return err
+	}
+
+	params := contextdev.PersonSearchParams{}
+
+	var res []byte
+	options = append(options, option.WithResponseBodyInto(&res))
+	_, err = client.People.Search(ctx, params, options...)
+	if err != nil {
+		return err
+	}
+
+	obj := gjson.ParseBytes(res)
+	format := cmd.Root().String("format")
+	explicitFormat := cmd.Root().IsSet("format")
+	transform := cmd.Root().String("transform")
+	return ShowJSON(obj, ShowJSONOpts{
+		ExplicitFormat: explicitFormat,
+		Format:         format,
+		RawOutput:      cmd.Root().Bool("raw-output"),
+		Title:          "people search",
+		Transform:      transform,
+	})
+}

pkg/cmd/person_test.go

@@ -96,3 +96,58 @@ func TestPeopleEnrich(t *testing.T) {
 		)
 	})
 }
+
+func TestPeopleSearch(t *testing.T) {
+	t.Skip("Mock server tests are disabled")
+	t.Run("regular flags", func(t *testing.T) {
+		mocktest.TestRunMockTestWithFlags(
+			t,
+			"--api-key", "string",
+			"people", "search",
+			"--query", "VPs of sales at solar companies in California",
+			"--cursor", "cursor",
+			"--filters", "{countries: [SE], years_of_experience_max: 0, years_of_experience_min: 0}",
+			"--tag", "production",
+			"--tag", "team-alpha",
+		)
+	})
+
+	t.Run("inner flags", func(t *testing.T) {
+		// Check that inner flags have been set up correctly
+		requestflag.CheckInnerFlags(peopleSearch)
+
+		// Alternative argument passing style using inner flags
+		mocktest.TestRunMockTestWithFlags(
+			t,
+			"--api-key", "string",
+			"people", "search",
+			"--query", "VPs of sales at solar companies in California",
+			"--cursor", "cursor",
+			"--filters.countries", "[SE]",
+			"--filters.years-of-experience-max", "0",
+			"--filters.years-of-experience-min", "0",
+			"--tag", "production",
+			"--tag", "team-alpha",
+		)
+	})
+
+	t.Run("piping data", func(t *testing.T) {
+		// Test piping YAML data over stdin
+		pipeData := []byte("" +
+			"query: VPs of sales at solar companies in California\n" +
+			"cursor: cursor\n" +
+			"filters:\n" +
+			"  countries:\n" +
+			"    - SE\n" +
+			"  years_of_experience_max: 0\n" +
+			"  years_of_experience_min: 0\n" +
+			"tags:\n" +
+			"  - production\n" +
+			"  - team-alpha\n")
+		mocktest.TestRunMockTestWithPipeAndFlags(
+			t, pipeData,
+			"--api-key", "string",
+			"people", "search",
+		)
+	})
+}