Add typed error codes for better downstream client usage of error handling (#525)

* Add typed error codes for better downstream client usage of error handling

* fix go vet

* fix govet

Author: rocktavious

.changes/unreleased/Feature-20250327-125544.yaml

@@ -0,0 +1,3 @@
+kind: Feature
+body: Add error codes for different types of error to support better client error handling
+time: 2025-03-27T12:55:44.683709-05:00

actions.go

@@ -1,6 +1,7 @@
 package opslevel
 
 import (
+	"errors"
 	"fmt"
 )
 
@@ -51,7 +52,7 @@ type CustomActionsExternalActionsConnection struct {
 type CustomActionsTriggerDefinitionsConnection struct {
 	Nodes      []CustomActionsTriggerDefinition
 	PageInfo   PageInfo
-	TotalCount int
+	TotalCount int `graphql:"-"`
 }
 
 func (client *Client) CreateWebhookAction(input CustomActionsWebhookActionCreateInput) (*CustomActionsExternalAction, error) {
@@ -65,7 +66,7 @@ func (client *Client) CreateWebhookAction(input CustomActionsWebhookActionCreate
 		"input": input,
 	}
 	err := client.Mutate(&m, v, WithName("WebhookActionCreate"))
-	return &m.Payload.WebhookAction, HandleErrors(err, m.Payload.Errors)
+	return &m.Payload.WebhookAction, errors.Join(err, HasAPIErrors(m.Payload.Errors))
 }
 
 func (client *Client) GetCustomAction(input string) (*CustomActionsExternalAction, error) {
@@ -78,10 +79,7 @@ func (client *Client) GetCustomAction(input string) (*CustomActionsExternalActio
 		"input": *NewIdentifier(input),
 	}
 	err := client.Query(&q, v, WithName("ExternalActionGet"))
-	if q.Account.Action.CustomActionsId.Id == "" {
-		err = fmt.Errorf("CustomActionsExternalAction with ID or Alias matching '%s' not found", input)
-	}
-	return &q.Account.Action, HandleErrors(err, nil)
+	return &q.Account.Action, HandleErrors(err, IsResourceFound(&q.Account.Action.CustomActionsId))
 }
 
 func (client *Client) ListCustomActions(variables *PayloadVariables) (*CustomActionsExternalActionsConnection, error) {
@@ -160,10 +158,7 @@ func (client *Client) GetTriggerDefinition(input string) (*CustomActionsTriggerD
 		"input": *NewIdentifier(input),
 	}
 	err := client.Query(&q, v, WithName("TriggerDefinitionGet"))
-	if q.Account.Definition.Id == "" {
-		err = fmt.Errorf("CustomActionsTriggerDefinition with ID or Alias matching '%s' not found", input)
-	}
-	return &q.Account.Definition, HandleErrors(err, nil)
+	return &q.Account.Definition, errors.Join(err, IsResourceFound(&q.Account.Definition))
 }
 
 func (client *Client) ListTriggerDefinitions(variables *PayloadVariables) (*CustomActionsTriggerDefinitionsConnection, error) {
@@ -176,19 +171,20 @@ func (client *Client) ListTriggerDefinitions(variables *PayloadVariables) (*Cust
 		variables = client.InitialPageVariablesPointer()
 	}
 	if err := client.Query(&q, *variables, WithName("TriggerDefinitionList")); err != nil {
-		return nil, err
+		return nil, HandleErrors(err)
 	}
+	q.Account.Definitions.TotalCount = len(q.Account.Definitions.Nodes)
 	for q.Account.Definitions.PageInfo.HasNextPage {
 		(*variables)["after"] = q.Account.Definitions.PageInfo.End
 		resp, err := client.ListTriggerDefinitions(variables)
 		if err != nil {
-			return nil, err
+			return &q.Account.Definitions, HandleErrors(err)
 		}
 		q.Account.Definitions.Nodes = append(q.Account.Definitions.Nodes, resp.Nodes...)
 		q.Account.Definitions.PageInfo = resp.PageInfo
 		q.Account.Definitions.TotalCount += resp.TotalCount
 	}
-	return &q.Account.Definitions, nil
+	return &q.Account.Definitions, HandleErrors(IsResourceFound(&q.Account.Definitions))
 }
 
 func (client *Client) UpdateTriggerDefinition(input CustomActionsTriggerDefinitionUpdateInput) (*CustomActionsTriggerDefinition, error) {

actions_test.go

@@ -225,14 +225,14 @@ func TestGetTriggerDefinition(t *testing.T) {
 func TestListTriggerDefinitions(t *testing.T) {
 	// Arrange
 	testRequestOne := autopilot.NewTestRequest(
-		`query TriggerDefinitionList($after:String!$first:Int!){account{customActionsTriggerDefinitions(after: $after, first: $first){nodes{{ template "custom_actions_trigger_request" }},{{ template "pagination_request" }},totalCount}}}`,
+		`query TriggerDefinitionList($after:String!$first:Int!){account{customActionsTriggerDefinitions(after: $after, first: $first){nodes{{ template "custom_actions_trigger_request" }},{{ template "pagination_request" }}}}}`,
 		`{{ template "pagination_initial_query_variables" }}`,
-		`{ "data": { "account": { "customActionsTriggerDefinitions": { "nodes": [ { {{ template "custom_action_trigger1_response" }} }, { {{ template "custom_action_trigger2_response" }} } ], {{ template "pagination_initial_pageInfo_response" }}, "totalCount": 2 }}}}`,
+		`{ "data": { "account": { "customActionsTriggerDefinitions": { "nodes": [ { {{ template "custom_action_trigger1_response" }} }, { {{ template "custom_action_trigger2_response" }} } ], {{ template "pagination_initial_pageInfo_response" }} }}}}`,
 	)
 	testRequestTwo := autopilot.NewTestRequest(
-		`query TriggerDefinitionList($after:String!$first:Int!){account{customActionsTriggerDefinitions(after: $after, first: $first){nodes{{ template "custom_actions_trigger_request" }},{{ template "pagination_request" }},totalCount}}}`,
+		`query TriggerDefinitionList($after:String!$first:Int!){account{customActionsTriggerDefinitions(after: $after, first: $first){nodes{{ template "custom_actions_trigger_request" }},{{ template "pagination_request" }}}}}`,
 		`{{ template "pagination_second_query_variables" }}`,
-		`{ "data": { "account": { "customActionsTriggerDefinitions": { "nodes": [ { {{ template "custom_action_trigger3_response" }} } ], {{ template "pagination_second_pageInfo_response" }}, "totalCount": 1 }}}}`,
+		`{ "data": { "account": { "customActionsTriggerDefinitions": { "nodes": [ { {{ template "custom_action_trigger3_response" }} } ], {{ template "pagination_second_pageInfo_response" }} }}}}`,
 	)
 	requests := []autopilot.TestRequest{testRequestOne, testRequestTwo}
 

common.go

@@ -1,13 +1,9 @@
 package opslevel
 
 import (
-	"errors"
-	"fmt"
 	"slices"
-	"strings"
 	"time"
 
-	"github.com/hasura/go-graphql-client"
 	"github.com/relvacode/iso8601"
 )
 
@@ -52,43 +48,6 @@ func RefTo[T NullableConstraint](value T) *Nullable[T] {
 	return NewNullableFrom(value)
 }
 
-func HandleErrors(err error, errs []Error) error {
-	if err != nil {
-		return err
-	}
-	return FormatErrors(errs)
-}
-
-func FormatErrors(errs []Error) error {
-	if len(errs) == 0 {
-		return nil
-	}
-
-	allErrors := fmt.Errorf("OpsLevel API Errors:")
-	for _, err := range errs {
-		if len(err.Path) == 1 && err.Path[0] == "base" {
-			err.Path[0] = ""
-		}
-		newErr := fmt.Errorf("\t- '%s' %s", strings.Join(err.Path, "."), err.Message)
-		allErrors = errors.Join(allErrors, newErr)
-	}
-
-	return allErrors
-}
-
-// IsOpsLevelApiError checks if the error is returned by OpsLevel's API
-func IsOpsLevelApiError(err error) bool {
-	if _, ok := err.(graphql.Errors); !ok {
-		return false
-	}
-	for _, hasuraErr := range err.(graphql.Errors) {
-		if len(hasuraErr.Path) > 0 {
-			return true
-		}
-	}
-	return false
-}
-
 func NewISO8601Date(datetime string) iso8601.Time {
 	date, _ := iso8601.ParseString(datetime)
 	return iso8601.Time{Time: date}

errors.go

@@ -0,0 +1,97 @@
+package opslevel
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/hasura/go-graphql-client"
+)
+
+type ErrorCode int
+
+const (
+	ErrorUnknown ErrorCode = iota
+	ErrorRequestError
+	ErrorAPIError
+	ErrorResourceNotFound
+)
+
+type ClientError struct {
+	error
+	ErrorCode ErrorCode
+}
+
+func NewClientError(code ErrorCode, err error) error {
+	return &ClientError{
+		error:     err,
+		ErrorCode: code,
+	}
+}
+
+func HandleErrors(opts ...any) error {
+	output := (error)(nil)
+	for _, opt := range opts {
+		switch v := opt.(type) {
+		case error:
+			if !IsOpsLevelApiError(v) {
+				output = errors.Join(output, NewClientError(ErrorRequestError, v))
+			} else {
+				output = errors.Join(output, v)
+			}
+		case []Error:
+			output = errors.Join(output, HasAPIErrors(v))
+		}
+	}
+	return output
+}
+
+func HasAPIErrors(errs []Error) error {
+	if len(errs) == 0 {
+		return nil
+	}
+
+	message := "OpsLevel API Errors:"
+	for _, e := range errs {
+		if len(e.Path) == 1 && e.Path[0] == "base" {
+			e.Path[0] = ""
+		}
+		message += fmt.Sprintf("\n\t- '%s' %s", strings.Join(e.Path, "."), e.Message)
+	}
+
+	return NewClientError(ErrorAPIError, errors.New(message))
+}
+
+func IsResourceFound(resource any) error {
+	// TODO: Also Check if ID is valid somehow `.Id == ""`
+	if resource == nil {
+		return NewClientError(ErrorResourceNotFound, fmt.Errorf("resource '%T' not found", resource))
+	}
+	if casted, ok := resource.(Identifiable); ok && casted.GetID() == "" {
+		return NewClientError(ErrorResourceNotFound, fmt.Errorf("resource '%T' not found", resource))
+	}
+	return nil
+}
+
+func ErrIs(err error, code ErrorCode) bool {
+	var clientErr *ClientError
+	if errors.As(err, &clientErr) {
+		if clientErr.ErrorCode == code {
+			return true
+		}
+	}
+	return false
+}
+
+// IsOpsLevelApiError checks if the error is returned by OpsLevel's API
+func IsOpsLevelApiError(err error) bool {
+	if _, ok := err.(graphql.Errors); !ok {
+		return false
+	}
+	for _, hasuraErr := range err.(graphql.Errors) {
+		if len(hasuraErr.Path) > 0 {
+			return true
+		}
+	}
+	return false
+}

common_test.go errors_test.go

@@ -1,38 +1,51 @@
 package opslevel_test
 
 import (
+	"fmt"
 	"testing"
 
 	ol "github.com/opslevel/opslevel-go/v2025"
 	"github.com/rocktavious/autopilot/v2023"
 )
 
-func TestFormatErrorsWorks(t *testing.T) {
+func TestHasAPIErrorsWorks(t *testing.T) {
 	// Arrange
 	errs := []ol.Error{
 		{Message: "can't be blank", Path: []string{"resource", "id"}},
 		{Message: "is not a valid input", Path: []string{"id"}},
 	}
 	// Act
-	output := ol.FormatErrors(errs)
+	output := ol.HasAPIErrors(errs)
 	// Assert
+	autopilot.Equals(t, true, ol.ErrIs(output, ol.ErrorAPIError))
 	autopilot.Equals(t, `OpsLevel API Errors:
 	- 'resource.id' can't be blank
 	- 'id' is not a valid input`,
 		output.Error())
 }
 
-func TestFormatErrorsNoPath(t *testing.T) {
+func TestHasAPIErrorsNoPath(t *testing.T) {
 	// Arrange
 	errs := []ol.Error{
 		{Message: "can't be blank", Path: []string{"base"}},
 		{Message: "is not a valid input", Path: []string{""}},
 	}
 	// Act
-	output := ol.FormatErrors(errs)
+	output := ol.HasAPIErrors(errs)
 	// Assert
+	autopilot.Equals(t, true, ol.ErrIs(output, ol.ErrorAPIError))
 	autopilot.Equals(t, `OpsLevel API Errors:
 	- '' can't be blank
 	- '' is not a valid input`,
 		output.Error())
 }
+
+func TestIsResourceFoundError(t *testing.T) {
+	// Arrange
+	err1 := ol.NewClientError(ol.ErrorResourceNotFound, fmt.Errorf("resource 'Example' not found"))
+	err2 := ol.NewClientError(ol.ErrorAPIError, fmt.Errorf("resource 'Example' not found"))
+	// Act
+	// Assert
+	autopilot.Equals(t, true, ol.ErrIs(err1, ol.ErrorResourceNotFound))
+	autopilot.Equals(t, false, ol.ErrIs(err2, ol.ErrorResourceNotFound))
+}

scalar.go

@@ -8,6 +8,10 @@ import (
 	"strings"
 )
 
+type Identifiable interface {
+	GetID() ID
+}
+
 type ID string
 
 func NewID(id ...string) *ID {
@@ -32,6 +36,10 @@ type Identifier struct {
 	Aliases []string `graphql:"aliases" json:"aliases"`
 }
 
+func (s Identifier) GetID() ID {
+	return s.Id
+}
+
 func (identifierInput IdentifierInput) MarshalJSON() ([]byte, error) {
 	if identifierInput.Id == nil && identifierInput.Alias == nil {
 		return []byte("null"), nil

service.go

@@ -321,7 +321,7 @@ func (client *Client) CreateService(input ServiceCreateInput) (*Service, error)
 	if err := m.Payload.Service.Hydrate(client); err != nil {
 		return &m.Payload.Service, err
 	}
-	return &m.Payload.Service, FormatErrors(m.Payload.Errors)
+	return &m.Payload.Service, HandleErrors(m.Payload.Errors)
 }
 
 func (client *Client) GetServiceIdWithAlias(alias string) (*ServiceId, error) {
@@ -723,7 +723,7 @@ func (client *Client) UpdateService(input ServiceUpdateInput) (*Service, error)
 	if err := m.Payload.Service.Hydrate(client); err != nil {
 		return &m.Payload.Service, err
 	}
-	return &m.Payload.Service, FormatErrors(m.Payload.Errors)
+	return &m.Payload.Service, HandleErrors(m.Payload.Errors)
 }
 
 func (client *Client) UpdateServiceNote(input ServiceNoteUpdateInput) (*Service, error) {
@@ -738,7 +738,7 @@ func (client *Client) UpdateServiceNote(input ServiceNoteUpdateInput) (*Service,
 		return nil, err
 	}
 
-	return &m.Payload.Service, FormatErrors(m.Payload.Errors)
+	return &m.Payload.Service, HandleErrors(m.Payload.Errors)
 }
 
 func (client *Client) DeleteService(identifier string) error {

team.go

@@ -253,7 +253,7 @@ func (client *Client) CreateTeam(input TeamCreateInput) (*Team, error) {
 	if err := m.Payload.Team.Hydrate(client); err != nil {
 		return &m.Payload.Team, err
 	}
-	return &m.Payload.Team, FormatErrors(m.Payload.Errors)
+	return &m.Payload.Team, HandleErrors(m.Payload.Errors)
 }
 
 func (client *Client) AddMemberships(team *TeamId, memberships ...TeamMembershipUserInput) ([]TeamMembership, error) {
@@ -421,7 +421,7 @@ func (client *Client) UpdateTeam(input TeamUpdateInput) (*Team, error) {
 	if err := m.Payload.Team.Hydrate(client); err != nil {
 		return &m.Payload.Team, err
 	}
-	return &m.Payload.Team, FormatErrors(m.Payload.Errors)
+	return &m.Payload.Team, HandleErrors(m.Payload.Errors)
 }
 
 func (client *Client) UpdateContact(id ID, contact ContactInput) (*Contact, error) {