feat: flag segment overrides — get, update, and delete

Slice 3 of 06-flags: segment overrides.

- `flag get <feature> --segment <id>` reads segment_feature_state from the
  features endpoint (environment + segment params) and shows the override,
  erroring when the feature has no override for that segment.
- `flag update <feature> --segment <id>` sets the override via update-flag-v2:
  the environment default is always carried forward unchanged, and a fresh
  override with no --value inherits the environment default value.
- `flag delete <feature> --segment <id>` removes an override via
  delete-segment-override; a bare `flag delete` exits 2 asking for --segment,
  and a missing override surfaces the endpoint's 404 as a clear message.

Identity overrides (--identifier) are deferred.

beep boop

Author: khvn26

README.md

@@ -19,8 +19,9 @@ flagsmith flag list    # list the flags in the current environment
 
 - `flagsmith init` — bind the current directory to a project (writes `flagsmith.json`).
 - `flagsmith flag list` — list feature flags in the current environment.
-- `flagsmith flag get <feature>` — show a single flag's state in the current environment.
-- `flagsmith flag update <feature>` — toggle (`--enable`/`--disable`) or set the value (`--value`, `--type`).
+- `flagsmith flag get <feature>` — show a single flag's state (`--segment <id>` for a segment override).
+- `flagsmith flag update <feature>` — toggle (`--enable`/`--disable`) or set the value (`--value`, `--type`); `--segment <id>` targets a segment override.
+- `flagsmith flag delete <feature> --segment <id>` — delete a segment override.
 - `flagsmith config` — show the resolved context and where each value comes from.
 - `flagsmith login` / `logout` — browser OAuth (PKCE, loopback); also `auth login`/`auth logout`.
 - `flagsmith auth status` — identity, organisations, credential source, token expiry.

internal/api/client.go

@@ -163,6 +163,7 @@ type Feature struct {
 	LifecycleStage       string               `json:"lifecycle_stage"`
 	CodeReferencesCounts []CodeReferenceCount `json:"code_references_counts"`
 	EnvironmentState     *FeatureState        `json:"environment_feature_state"`
+	SegmentState         *FeatureState        `json:"segment_feature_state"`
 
 	raw json.RawMessage
 }
@@ -196,10 +197,15 @@ func (f Feature) CodeReferences() int {
 }
 
 // Features lists a project's features with their state in one environment, via
-// the Admin API. The environment is identified by its numeric ID.
-func Features(ctx context.Context, apiURL string, auth Auth, projectID, environmentID int) ([]Feature, error) {
+// the Admin API. The environment is identified by its numeric ID. When
+// segmentID is non-zero, each feature also carries its segment_feature_state
+// for that segment.
+func Features(ctx context.Context, apiURL string, auth Auth, projectID, environmentID, segmentID int) ([]Feature, error) {
 	var features []Feature
 	path := fmt.Sprintf("/api/v1/projects/%d/features/?environment=%d", projectID, environmentID)
+	if segmentID != 0 {
+		path += fmt.Sprintf("&segment=%d", segmentID)
+	}
 	if err := getList(ctx, apiURL, path, auth, &features); err != nil {
 		return nil, err
 	}
@@ -226,11 +232,54 @@ type EnvironmentDefault struct {
 	Value   FeatureValue `json:"value"`
 }
 
-// UpdateFlagRequest is the update-flag-v2 body (environment default only; this
-// endpoint does not manage identity overrides).
+// SegmentOverride is one segment's state in the update-flag-v2 body.
+type SegmentOverride struct {
+	SegmentID int          `json:"segment_id"`
+	Enabled   bool         `json:"enabled"`
+	Value     FeatureValue `json:"value"`
+}
+
+// UpdateFlagRequest is the update-flag-v2 body. environment_default is always
+// required; segment_overrides only creates/updates the segments listed and
+// never removes others. This endpoint does not manage identity overrides.
 type UpdateFlagRequest struct {
 	Feature            FeatureRef         `json:"feature"`
 	EnvironmentDefault EnvironmentDefault `json:"environment_default"`
+	SegmentOverrides   []SegmentOverride  `json:"segment_overrides,omitempty"`
+}
+
+// DeleteSegmentOverride removes a feature's override for one segment, via the
+// experimental delete-segment-override endpoint keyed by the environment key.
+func DeleteSegmentOverride(ctx context.Context, apiURL string, auth Auth, environmentKey, featureName string, segmentID int) error {
+	body, err := json.Marshal(map[string]any{
+		"feature": FeatureRef{Name: featureName},
+		"segment": map[string]int{"id": segmentID},
+	})
+	if err != nil {
+		return err
+	}
+	u := strings.TrimRight(apiURL, "/") + "/api/experiments/environments/" + environmentKey + "/delete-segment-override/"
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, u, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	auth.Apply(req)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusForbidden {
+		return ErrWorkflowGated
+	}
+	if resp.StatusCode == http.StatusNotFound {
+		return fmt.Errorf("no override exists for segment %d", segmentID)
+	}
+	if resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("POST %s returned %s", u, resp.Status)
+	}
+	return nil
 }
 
 // ErrWorkflowGated is returned when update-flag-v2 refuses because the

internal/api/client_test.go

@@ -176,7 +176,7 @@ func TestFeatures(t *testing.T) {
 		defer srv.Close()
 
 		// When
-		features, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1)
+		features, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1, 0)
 
 		// Then
 		if err != nil {
@@ -206,7 +206,7 @@ func TestFeatures(t *testing.T) {
 		defer srv.Close()
 
 		// When
-		features, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1)
+		features, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1, 0)
 		if err != nil {
 			t.Fatal(err)
 		}
@@ -229,13 +229,77 @@ func TestFeatures(t *testing.T) {
 		defer srv.Close()
 
 		// When
-		_, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1)
+		_, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1, 0)
 
 		// Then
 		if err == nil || !strings.Contains(err.Error(), "403") {
 			t.Errorf("err = %v, want 403", err)
 		}
 	})
+
+	t.Run("segment param is sent when non-zero", func(t *testing.T) {
+		// Given
+		var gotSegment string
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			gotSegment = r.URL.Query().Get("segment")
+			fmt.Fprint(w, `{"count":0,"results":[]}`)
+		}))
+		defer srv.Close()
+
+		// When
+		if _, err := Features(context.Background(), srv.URL, APIKey("k.s"), 101, 1, 12); err != nil {
+			t.Fatal(err)
+		}
+
+		// Then
+		if gotSegment != "12" {
+			t.Errorf("segment = %q, want 12", gotSegment)
+		}
+	})
+}
+
+func TestDeleteSegmentOverride(t *testing.T) {
+	t.Run("posts the feature and segment, accepts 204", func(t *testing.T) {
+		// Given
+		var body map[string]any
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method != http.MethodPost ||
+				r.URL.Path != "/api/experiments/environments/envkey/delete-segment-override/" {
+				t.Errorf("request = %s %s", r.Method, r.URL.Path)
+			}
+			json.NewDecoder(r.Body).Decode(&body)
+			w.WriteHeader(http.StatusNoContent)
+		}))
+		defer srv.Close()
+
+		// When
+		err := DeleteSegmentOverride(context.Background(), srv.URL, APIKey("k.s"), "envkey", "max_items", 12)
+
+		// Then
+		if err != nil {
+			t.Fatal(err)
+		}
+		if body["feature"].(map[string]any)["name"] != "max_items" ||
+			body["segment"].(map[string]any)["id"] != float64(12) {
+			t.Errorf("body = %+v", body)
+		}
+	})
+
+	t.Run("404 becomes a no-override error", func(t *testing.T) {
+		// Given
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusNotFound)
+		}))
+		defer srv.Close()
+
+		// When
+		err := DeleteSegmentOverride(context.Background(), srv.URL, APIKey("k.s"), "envkey", "max_items", 12)
+
+		// Then
+		if err == nil || !strings.Contains(err.Error(), "segment 12") {
+			t.Errorf("err = %v, want a no-override error", err)
+		}
+	})
 }
 
 func TestCreateEnvironment(t *testing.T) {