ACCT-4459: Support for domain scoped roles

.changelog/1095.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+account-member: add support for domain scoped roles
+```

account_members.go

@@ -3,17 +3,19 @@ package cloudflare
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 )
 
 // AccountMember is the definition of a member of an account.
 type AccountMember struct {
-	ID     string                   `json:"id"`
-	Code   string                   `json:"code"`
-	User   AccountMemberUserDetails `json:"user"`
-	Status string                   `json:"status"`
-	Roles  []AccountRole            `json:"roles"`
+	ID       string                   `json:"id"`
+	Code     string                   `json:"code"`
+	User     AccountMemberUserDetails `json:"user"`
+	Status   string                   `json:"status"`
+	Roles    []AccountRole            `json:"roles,omitempty"`
+	Policies []Policy                 `json:"policies,omitempty"`
 }
 
 // AccountMemberUserDetails outlines all the personal information about
@@ -46,9 +48,22 @@ type AccountMemberDetailResponse struct {
 // AccountMemberInvitation represents the invitation for a new member to
 // the account.
 type AccountMemberInvitation struct {
-	Email  string   `json:"email"`
-	Roles  []string `json:"roles"`
-	Status string   `json:"status,omitempty"`
+	Email    string   `json:"email"`
+	Roles    []string `json:"roles,omitempty"`
+	Policies []Policy `json:"policies,omitempty"`
+	Status   string   `json:"status,omitempty"`
+}
+
+const errMissingMemberRolesOrPolicies = "account member must be created with roles or policies (not both)"
+
+var ErrMissingMemberRolesOrPolicies = errors.New(errMissingMemberRolesOrPolicies)
+
+type CreateAccountMemberParams struct {
+	AccountId    string
+	EmailAddress string
+	Roles        []string
+	Policies     []Policy
+	Status       string
 }
 
 // AccountMembers returns all members of an account.
@@ -80,19 +95,56 @@ func (api *API) AccountMembers(ctx context.Context, accountID string, pageOpts P
 // Refer to the API reference for valid statuses.
 //
 // API reference: https://api.cloudflare.com/#account-members-add-member
-func (api *API) CreateAccountMemberWithStatus(ctx context.Context, accountID string, emailAddress string, roles []string, status string) (AccountMember, error) {
-	if accountID == "" {
-		return AccountMember{}, ErrMissingAccountID
+func (api *API) CreateAccountMemberWithStatus(ctx context.Context, rc *ResourceContainer, accountID string, emailAddress string, roles []string, status string) (AccountMember, error) {
+	return api.CreateAccountMember(ctx, rc, CreateAccountMemberParams{
+		AccountId:    accountID,
+		EmailAddress: emailAddress,
+		Roles:        roles,
+		Status:       status,
+	})
+}
+
+// CreateAccountMember invites a new member to join an account with roles.
+// The member will be placed into "pending" status and receive an email confirmation.
+// NOTE: If you are currently enrolled in Domain Scoped Roles, your roles will be converted to policies
+// upon member invitation. We recommend upgrading to CreateAccountMemberWithPolicies to use policies.
+//
+// API reference: https://api.cloudflare.com/#account-members-add-member
+func (api *API) CreateAccountMember(ctx context.Context, rc *ResourceContainer, params CreateAccountMemberParams) (AccountMember, error) {
+	if rc.Level != AccountRouteLevel {
+		return AccountMember{}, fmt.Errorf(errInvalidResourceContainerAccess, rc.Level)
+	}
+
+	if params.AccountId == "" {
+		if rc.Identifier == "" {
+			return AccountMember{}, ErrMissingAccountID
+		} else {
+			params.AccountId = rc.Identifier
+		}
+	}
+
+	invite := AccountMemberInvitation{
+		Email:  params.EmailAddress,
+		Status: params.Status,
 	}
 
-	uri := fmt.Sprintf("/accounts/%s/members", accountID)
+	roles := []AccountRole{}
+	for i := 0; i < len(params.Roles); i++ {
+		roles = append(roles, AccountRole{ID: params.Roles[i]})
+	}
+	err := validateRolesAndPolicies(roles, params.Policies)
+	if err != nil {
+		return AccountMember{}, err
+	}
 
-	newMember := AccountMemberInvitation{
-		Email:  emailAddress,
-		Roles:  roles,
-		Status: status,
+	if params.Roles != nil {
+		invite.Roles = params.Roles
+	} else if params.Policies != nil {
+		invite.Policies = params.Policies
 	}
-	res, err := api.makeRequestContext(ctx, http.MethodPost, uri, newMember)
+
+	uri := fmt.Sprintf("/accounts/%s/members", rc.Identifier)
+	res, err := api.makeRequestContext(ctx, http.MethodPost, uri, invite)
 	if err != nil {
 		return AccountMember{}, err
 	}
@@ -106,12 +158,28 @@ func (api *API) CreateAccountMemberWithStatus(ctx context.Context, accountID str
 	return accountMemberListResponse.Result, nil
 }
 
-// CreateAccountMember invites a new member to join an account.
-// The member will be placed into "pending" status and receive an email confirmation.
+// CreateAccountMemberWithRoles is a terse wrapper around the CreateAccountMember method
+// for clarity on what permissions you're granting an AccountMember.
 //
 // API reference: https://api.cloudflare.com/#account-members-add-member
-func (api *API) CreateAccountMember(ctx context.Context, accountID string, emailAddress string, roles []string) (AccountMember, error) {
-	return api.CreateAccountMemberWithStatus(ctx, accountID, emailAddress, roles, "")
+func (api *API) CreateAccountMemberWithRoles(ctx context.Context, rc *ResourceContainer, accountID string, emailAddress string, roles []string) (AccountMember, error) {
+	return api.CreateAccountMember(ctx, rc, CreateAccountMemberParams{
+		AccountId:    accountID,
+		EmailAddress: emailAddress,
+		Roles:        roles,
+	})
+}
+
+// CreateAccountMemberWithPolicies invites a new member to join your account with policies.
+// Policies are the replacement to legacy "roles", which enables the newest feature Domain Scoped Roles.
+//
+// API documentation will be coming shortly. Blog post: https://blog.cloudflare.com/domain-scoped-roles-ga/
+func (api *API) CreateAccountMemberWithPolicies(ctx context.Context, rc *ResourceContainer, accountID string, emailAddress string, policies []Policy) (AccountMember, error) {
+	return api.CreateAccountMember(ctx, rc, CreateAccountMemberParams{
+		AccountId:    accountID,
+		EmailAddress: emailAddress,
+		Policies:     policies,
+	})
 }
 
 // DeleteAccountMember removes a member from an account.
@@ -140,6 +208,11 @@ func (api *API) UpdateAccountMember(ctx context.Context, accountID string, userI
 		return AccountMember{}, ErrMissingAccountID
 	}
 
+	err := validateRolesAndPolicies(member.Roles, member.Policies)
+	if err != nil {
+		return AccountMember{}, err
+	}
+
 	uri := fmt.Sprintf("/accounts/%s/members/%s", accountID, userID)
 
 	res, err := api.makeRequestContext(ctx, http.MethodPut, uri, member)
@@ -183,3 +256,17 @@ func (api *API) AccountMember(ctx context.Context, accountID string, memberID st
 
 	return accountMemberResponse.Result, nil
 }
+
+// validateRolesAndPolicies ensures either roles or policies are provided in
+// CreateAccountMember requests, but not both.
+func validateRolesAndPolicies(roles []AccountRole, policies []Policy) error {
+	hasRoles := len(roles) > 0
+	hasPolicies := len(policies) > 0
+	hasRolesOrPolicies := hasRoles || hasPolicies
+	hasRolesAndPolicies := hasRoles && hasPolicies
+	hasCorrectPermissions := hasRolesOrPolicies && !hasRolesAndPolicies
+	if !hasCorrectPermissions {
+		return ErrMissingMemberRolesOrPolicies
+	}
+	return nil
+}