feat: Add GetFeatureByName and GetSegmentByName

Adds lookups by name for features and segments, so that callers which know a
project UUID and a name -- but not a UUID -- can resolve an entity. This is
what the Terraform provider needs to offer `flagsmith_feature` and
`flagsmith_segment` data sources.

Both are built on a shared `searchProjectResources` helper. Two things about
the API are worth knowing:

- Features filter on `search`, segments filter on `q`. Passing the wrong one is
  silently ignored and returns every result in the project.
- Both filters are case insensitive "contains" matches, so results have to be
  filtered client side for an exact match. Without that, asking for `flag`
  could return `flagship`.

Pages are requested as `page=N` against the client's configured base URL rather
than by following DRF's `next` link, which is built from the incoming request
host and so can be unreachable behind a self hosted reverse proxy.

Segment names are not unique within a project, so a name that matches more than
one segment returns MultipleSegmentsFoundError rather than picking arbitrarily.
Feature names are uniquely indexed, so the equivalent feature error is
defensive only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: matthewelwell

client.go

@@ -135,6 +135,39 @@ func (c *Client) GetFeature(featureUUID string) (*Feature, error) {
 	return &feature, nil
 }
 
+// GetFeatureByName returns the feature in the given project whose name is an exact
+// match for featureName.
+//
+// The match is case sensitive. The API's `search` filter is a case insensitive
+// "contains" match, so results are filtered client side.
+func (c *Client) GetFeatureByName(projectUUID string, featureName string) (*Feature, error) {
+	projectID, err := c.getProjectID(projectUUID)
+	if err != nil {
+		return nil, err
+	}
+
+	url := fmt.Sprintf("%s/projects/%d/features/", c.baseURL, projectID)
+	matches, err := searchProjectResources(c, url, "search", featureName, "features",
+		func(feature *Feature) string { return feature.Name })
+
+	if err != nil {
+		return nil, err
+	}
+
+	switch len(matches) {
+	case 0:
+		return nil, FeatureNotFoundError{featureName: featureName, projectUUID: projectUUID}
+	case 1:
+		feature := matches[0]
+		// The API never returns the project UUID, and unlike GetFeature we already
+		// know it, so there is no need to look the project up again.
+		feature.ProjectUUID = projectUUID
+		return feature, nil
+	default:
+		return nil, MultipleFeaturesFoundError{featureName: featureName, projectUUID: projectUUID, count: len(matches)}
+	}
+}
+
 func (c *Client) CreateFeature(feature *Feature) error {
 	if feature.ProjectID == nil {
 		projectID, err := c.getProjectID(feature.ProjectUUID)
@@ -189,6 +222,61 @@ func (c *Client) UpdateFeature(feature *Feature) error {
 	return nil
 }
 
+// searchPageLimit caps the number of pages walked while searching, as a guard
+// against a server that always reports a further page.
+const searchPageLimit = 100
+
+// searchProjectResources walks a paginated project list endpoint, passing searchTerm
+// as queryParam, and returns every result whose name is an exact match.
+//
+// The Flagsmith API's search filters are case insensitive "contains" matches, so
+// callers cannot rely on the server to return exactly one result.
+//
+// Pages are requested as `page=N` against the client's own base URL rather than by
+// following the `next` link, which DRF builds from the incoming request host and so
+// may be unreachable behind a self hosted reverse proxy. `next` is used only to
+// decide whether a further page exists.
+func searchProjectResources[T any](c *Client, url, queryParam, searchTerm, resourceName string,
+	nameOf func(*T) string) ([]*T, error) {
+	matches := []*T{}
+
+	for page := 1; page <= searchPageLimit; page++ {
+		result := struct {
+			Next    *string `json:"next"`
+			Results []*T    `json:"results"`
+		}{}
+
+		resp, err := c.client.R().
+			SetQueryParams(map[string]string{
+				queryParam: searchTerm,
+				"page":     strconv.Itoa(page),
+			}).
+			SetResult(&result).
+			Get(url)
+
+		if err != nil {
+			return nil, err
+		}
+
+		if !resp.IsSuccess() {
+			return nil, fmt.Errorf("flagsmithapi: Error searching %s: %s", resourceName, resp)
+		}
+
+		for _, item := range result.Results {
+			if nameOf(item) == searchTerm {
+				matches = append(matches, item)
+			}
+		}
+
+		if result.Next == nil || *result.Next == "" {
+			return matches, nil
+		}
+	}
+
+	return nil, fmt.Errorf("flagsmithapi: Error searching %s: more than %d pages of results",
+		resourceName, searchPageLimit)
+}
+
 func (c *Client) getProjectID(projectUUID string) (int64, error) {
 	project, err := c.GetProject(projectUUID)
 
@@ -376,6 +464,46 @@ func (c *Client) GetSegment(segmentUUID string) (*Segment, error) {
 	segment.ProjectUUID = project.UUID
 	return &segment, nil
 }
+
+// GetSegmentByName returns the segment in the given project whose name is an exact
+// match for segmentName.
+//
+// The match is case sensitive. The API's `q` filter is a case insensitive
+// "contains" match, so results are filtered client side.
+//
+// Note that segment names are not unique within a project: if more than one segment
+// matches, a MultipleSegmentsFoundError is returned. System segments are excluded by
+// the list endpoint, so they can only be looked up by UUID.
+func (c *Client) GetSegmentByName(projectUUID string, segmentName string) (*Segment, error) {
+	projectID, err := c.getProjectID(projectUUID)
+	if err != nil {
+		return nil, err
+	}
+
+	url := fmt.Sprintf("%s/projects/%d/segments/", c.baseURL, projectID)
+	// NOTE: segments filter on `q`, features filter on `search`. Passing `search`
+	// here is silently ignored and returns every segment in the project.
+	matches, err := searchProjectResources(c, url, "q", segmentName, "segments",
+		func(segment *Segment) string { return segment.Name })
+
+	if err != nil {
+		return nil, err
+	}
+
+	switch len(matches) {
+	case 0:
+		return nil, SegmentNotFoundError{segmentName: segmentName, projectUUID: projectUUID}
+	case 1:
+		segment := matches[0]
+		// The API never returns the project UUID, and unlike GetSegment we already
+		// know it, so there is no need to look the project up again.
+		segment.ProjectUUID = projectUUID
+		return segment, nil
+	default:
+		return nil, MultipleSegmentsFoundError{segmentName: segmentName, projectUUID: projectUUID, count: len(matches)}
+	}
+}
+
 func (c *Client) DeleteSegment(projectID, segmentID int64) error {
 	url := fmt.Sprintf("%s/projects/%d/segments/%d/", c.baseURL, projectID, segmentID)
 

errors.go

@@ -6,12 +6,16 @@ import (
 
 type FeatureNotFoundError struct {
 	featureUUID string
+	featureName string
+	projectUUID string
 }
 type FeatureStateNotFoundError struct {
 	featureStateUUID string
 }
 type SegmentNotFoundError struct {
 	segmentUUID string
+	segmentName string
+	projectUUID string
 }
 type FeatureMVOptionNotFoundError struct {
 	featureMVOptionUUID string
@@ -20,14 +24,46 @@ type UserNotFoundError struct {
 	email string
 }
 
+// MultipleFeaturesFoundError is returned when a lookup by name matches more than
+// one feature. Feature names are unique within a project, so this is defensive.
+type MultipleFeaturesFoundError struct {
+	featureName string
+	projectUUID string
+	count       int
+}
+
+// MultipleSegmentsFoundError is returned when a lookup by name matches more than
+// one segment. Unlike features, segment names are not unique within a project.
+type MultipleSegmentsFoundError struct {
+	segmentName string
+	projectUUID string
+	count       int
+}
+
 func (e FeatureNotFoundError) Error() string {
+	if e.featureName != "" {
+		return fmt.Sprintf("flagsmithapi: feature named '%s' not found in project '%s'", e.featureName, e.projectUUID)
+	}
 	return fmt.Sprintf("flagsmithapi: feature '%s' not found", e.featureUUID)
 }
 
 func (e SegmentNotFoundError) Error() string {
+	if e.segmentName != "" {
+		return fmt.Sprintf("flagsmithapi: segment named '%s' not found in project '%s'", e.segmentName, e.projectUUID)
+	}
 	return fmt.Sprintf("flagsmithapi: segment '%s' not found", e.segmentUUID)
 }
 
+func (e MultipleFeaturesFoundError) Error() string {
+	return fmt.Sprintf("flagsmithapi: found %d features named '%s' in project '%s', expected exactly one",
+		e.count, e.featureName, e.projectUUID)
+}
+
+func (e MultipleSegmentsFoundError) Error() string {
+	return fmt.Sprintf("flagsmithapi: found %d segments named '%s' in project '%s', expected exactly one",
+		e.count, e.segmentName, e.projectUUID)
+}
+
 func (e FeatureStateNotFoundError) Error() string {
 	return fmt.Sprintf("flagsmithapi: feature state '%s' not found", e.featureStateUUID)
 }