Merge pull request #165 from Flagsmith/feat/undeprecate-getidentityflags-getenvironmentflags

feat: Un-deprecate GetEnvironmentFlags and GetIdentityFlags, improve docs

Author: rolodato

Makefile

@@ -5,10 +5,11 @@ EVALUATION_CONTEXT_SCHEMA_URL ?= https://raw.githubusercontent.com/Flagsmith/fla
 
 .PHONY: generate-evaluation-context
 generate-evaluation-context:
-	npx quicktype ${EVALUATION_CONTEXT_SCHEMA_URL} \
+	curl ${EVALUATION_CONTEXT_SCHEMA_URL} | npx quicktype  \
 		--src-lang schema \
 		--lang go \
 		--package flagsmith \
 		--omit-empty \
 		--just-types-and-package \
-		> evaluationcontext.go
+		--top-level EvaluationContext \
+		-o evaluationcontext.go

client.go

@@ -171,19 +171,13 @@ func NewClient(apiKey string, options ...Option) *Client {
 	return c
 }
 
-// Returns `Flags` struct holding all the flags for the current environment.
+// GetFlags evaluates the feature flags within an EvaluationContext.
 //
-// Provide `EvaluationContext` to evaluate flags for a specific environment or identity.
+// When flag evaluation fails, the value of each Flag is determined by the default flag handler
+// from WithDefaultHandler, if one was provided.
 //
-// If local evaluation is enabled this function will not call the Flagsmith API
-// directly, but instead read the asynchronously updated local environment or
-// use the default flag handler in case it has not yet been updated.
-//
-// Notes:
-//
-// * `EvaluationContext.Environment` is ignored in local evaluation mode.
-//
-// * `EvaluationContext.Feature` is not yet supported.
+// Flags are evaluated remotely by the Flagsmith API by default.
+// To evaluate flags locally, instantiate a client using WithLocalEvaluation.
 func (c *Client) GetFlags(ctx context.Context, ec *EvaluationContext) (f Flags, err error) {
 	if ec != nil {
 		ctx = WithEvaluationContext(ctx, *ec)
@@ -194,13 +188,8 @@ func (c *Client) GetFlags(ctx context.Context, ec *EvaluationContext) (f Flags,
 	return c.GetEnvironmentFlags(ctx)
 }
 
-// Returns `Flags` struct holding all the flags for the current environment.
-//
-// If local evaluation is enabled this function will not call the Flagsmith API
-// directly, but instead read the asynchronously updated local environment or
-// use the default flag handler in case it has not yet been updated.
-//
-// Deprecated: Use `GetFlags` instead.
+// GetEnvironmentFlags calls GetFlags using the current environment as the EvaluationContext.
+// Equivalent to GetFlags(ctx, nil).
 func (c *Client) GetEnvironmentFlags(ctx context.Context) (f Flags, err error) {
 	if c.config.localEvaluation || c.config.offlineMode {
 		if f, err = c.getEnvironmentFlagsFromEnvironment(); err == nil {
@@ -219,18 +208,7 @@ func (c *Client) GetEnvironmentFlags(ctx context.Context) (f Flags, err error) {
 	return Flags{}, &FlagsmithClientError{msg: fmt.Sprintf("Failed to fetch flags with error: %s", err)}
 }
 
-// Returns `Flags` struct holding all the flags for the current environment for
-// a given identity.
-//
-// If local evaluation is disabled it will also upsert all traits to the
-// Flagsmith API for future evaluations. Providing a trait with a value of nil
-// will remove the trait from the identity if it exists.
-//
-// If local evaluation is enabled this function will not call the Flagsmith API
-// directly, but instead read the asynchronously updated local environment or
-// use the default flag handler in case it has not yet been updated.
-//
-// Deprecated: Use `GetFlags` providing `EvaluationContext.Identity` instead.
+// GetIdentityFlags calls GetFlags using this identifier and traits as the EvaluationContext.
 func (c *Client) GetIdentityFlags(ctx context.Context, identifier string, traits []*Trait) (f Flags, err error) {
 	if c.config.localEvaluation || c.config.offlineMode {
 		if f, err = c.getIdentityFlagsFromEnvironment(identifier, traits); err == nil {

evaluationcontext.go

@@ -1,26 +1,37 @@
 package flagsmith
 
+// EvaluationContext represents a context in which feature flags can be evaluated.
+// Flagsmith flags are always evaluated in an EnvironmentEvaluationContext, with an optional IdentityEvaluationContext.
 type EvaluationContext struct {
 	Environment *EnvironmentEvaluationContext `json:"environment,omitempty"`
-	Feature     *FeatureEvaluationContext     `json:"feature,omitempty"`
 	Identity    *IdentityEvaluationContext    `json:"identity,omitempty"`
+	Feature     *FeatureEvaluationContext     `json:"feature,omitempty"`
 }
 
+// EnvironmentEvaluationContext represents a Flagsmith environment used in an EvaluationContext.
+// It is ignored if the evaluating Client was created using WithLocalEvaluation.
 type EnvironmentEvaluationContext struct {
+	// APIKey is an identifier for this environment. It is also known as the environment ID or client-side SDK key.
 	APIKey string `json:"api_key"`
 }
 
-type FeatureEvaluationContext struct {
-	Name string `json:"name"`
-}
-
+// IdentityEvaluationContext represents a Flagsmith identity within a Flagsmith environment, used in an EvaluationContext.
+// Traits are application-defined key-value pairs which can be used as part of the flag evaluation context.
+// Flagsmith will not persist Transient identities when flags are remotely evaluated.
 type IdentityEvaluationContext struct {
 	Identifier *string                            `json:"identifier,omitempty"`
 	Traits     map[string]*TraitEvaluationContext `json:"traits,omitempty"`
 	Transient  *bool                              `json:"transient,omitempty"`
 }
 
+// TraitEvaluationContext represents a single trait value used within an IdentityEvaluationContext.
+// A Transient trait will not be persisted.
 type TraitEvaluationContext struct {
 	Transient *bool       `json:"transient,omitempty"`
 	Value     interface{} `json:"value"`
 }
+
+// FeatureEvaluationContext is not yet implemented.
+type FeatureEvaluationContext struct {
+	Name string `json:"name"`
+}