feat: Add custom field (metadata) support

Adds support for reading and writing Flagsmith custom fields on features,
segments and environments, which terraform-provider-flagsmith#215 needs. Until
now the provider could not set a custom field at all, so an organisation with a
mandatory custom field could not create features through it.

The API takes a MetadataModelField ID, which is not the same as the custom
field's own ID: a single field bound to features, segments and environments has
three of them. Resolving a name to the right one is fiddly enough that it does
not belong in every caller, so this adds a MetadataFieldResolver that maps names
to model field IDs for one (project, entity) pair and back again.

Two API details drive the design:

- `GET /projects/{id}/metadata/fields/?entity=feature` filters which *fields*
  are returned but does NOT filter each field's nested `model_fields`, so the
  caller has to match on content type regardless. The entity param is therefore
  not used, which also lets one response serve all three entity types.
- Django content type IDs are specific to an installation, so they are resolved
  at runtime from the supported-content-types endpoint and never hardcoded.

`GET /features/get-by-uuid/` is served by CreateFeatureSerializer, which omits
metadata, so GetFeature hydrates it from the project scoped retrieve endpoint.
That costs one extra request per feature read. Segments and environments need no
workaround: their get-by-uuid responses already include metadata. See the TODO
for the upstream fix that would remove this.

Feature.UnmarshalJSON decodes into an explicit allowlist, so adding Metadata to
the struct alone would have silently dropped it on every read. The allowlist now
carries a warning, and a reflection based test fails if a future field is
missed.

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

Author: matthewelwell

client.go

@@ -132,9 +132,46 @@ func (c *Client) GetFeature(featureUUID string) (*Feature, error) {
 		return nil, err
 	}
 	feature.ProjectUUID = project.UUID
+
+	// `features/get-by-uuid/` is served by CreateFeatureSerializer, which omits
+	// metadata (see api/features/views.py::get_feature_by_uuid), so it has to be read
+	// from the project scoped retrieve endpoint instead.
+	// TODO: drop this once get_feature_by_uuid returns metadata.
+	if feature.ID != nil {
+		metadata, err := c.getFeatureMetadata(*feature.ProjectID, *feature.ID)
+		if err != nil {
+			return nil, err
+		}
+		feature.Metadata = metadata
+	}
+
 	return &feature, nil
 }
 
+// getFeatureMetadata reads just the metadata of a feature from the project scoped
+// retrieve endpoint.
+//
+// It decodes into an anonymous struct rather than a Feature so that the response cannot
+// overwrite fields the caller has already populated.
+func (c *Client) getFeatureMetadata(projectID, featureID int64) (*[]Metadata, error) {
+	url := fmt.Sprintf("%s/projects/%d/features/%d/", c.baseURL, projectID, featureID)
+	result := struct {
+		Metadata *[]Metadata `json:"metadata"`
+	}{}
+
+	resp, err := c.client.R().SetResult(&result).Get(url)
+
+	if err != nil {
+		return nil, err
+	}
+
+	if !resp.IsSuccess() {
+		return nil, fmt.Errorf("flagsmithapi: Error getting feature metadata: %s", resp)
+	}
+
+	return result.Metadata, nil
+}
+
 func (c *Client) CreateFeature(feature *Feature) error {
 	if feature.ProjectID == nil {
 		projectID, err := c.getProjectID(feature.ProjectUUID)

errors.go

@@ -2,6 +2,7 @@ package flagsmithapi
 
 import (
 	"fmt"
+	"strings"
 )
 
 type FeatureNotFoundError struct {
@@ -20,6 +21,45 @@ type UserNotFoundError struct {
 	email string
 }
 
+// MetadataFieldNotFoundError is returned when no custom field with the given name is
+// visible to the project. Fields are exported so that callers can build their own
+// messages without parsing this one.
+type MetadataFieldNotFoundError struct {
+	Name       string
+	Entity     string
+	KnownNames []string
+}
+
+// MetadataFieldNotBoundError is returned when a custom field exists in the project but
+// is not enabled for the entity being written to.
+type MetadataFieldNotBoundError struct {
+	Name   string
+	Entity string
+}
+
+// MetadataFieldInvalidValueError is returned when a value does not match its custom
+// field's configured type.
+type MetadataFieldInvalidValueError struct {
+	Name      string
+	FieldType string
+	Value     string
+	Reason    string
+}
+
+func (e MetadataFieldNotFoundError) Error() string {
+	return fmt.Sprintf("flagsmithapi: no custom field named '%s' is available for %ss in this project (available: %s)",
+		e.Name, e.Entity, strings.Join(e.KnownNames, ", "))
+}
+
+func (e MetadataFieldNotBoundError) Error() string {
+	return fmt.Sprintf("flagsmithapi: the custom field '%s' exists but is not enabled for %ss",
+		e.Name, e.Entity)
+}
+
+func (e MetadataFieldInvalidValueError) Error() string {
+	return fmt.Sprintf("flagsmithapi: invalid value for custom field '%s': %s", e.Name, e.Reason)
+}
+
 func (e FeatureNotFoundError) Error() string {
 	return fmt.Sprintf("flagsmithapi: feature '%s' not found", e.featureUUID)
 }