e621-sdk-go/pkg/e621/builder/basic/users.go

package basic

import (
	"context"
	"git.dragse.it/anthrove/e621-sdk-go/pkg/e621/endpoints"
	"git.dragse.it/anthrove/e621-sdk-go/pkg/e621/model"
	"strconv"
)

// UsersBuilder represents a builder for constructing queries to retrieve user information.
type UsersBuilder interface {
	// SetPage sets the page number for paginated results.
	SetPage(pageNumber int) UsersBuilder
	// SetLimit sets the maximum number of users to retrieve.
	SetLimit(limitUser int) UsersBuilder
	// SearchByName specifies a username to search for.
	SearchByName(userName string) UsersBuilder
	// SearchByAbout specifies a text to search in the 'about' field of user profiles.
	SearchByAbout(about string) UsersBuilder
	// SearchByAvatarID specifies an avatar ID to search for.
	SearchByAvatarID(avatarID model.PostID) UsersBuilder
	// SearchByLevel specifies a user level to filter by.
	SearchByLevel(level model.UserLevel) UsersBuilder
	// SearchByMinLevel specifies the minimum user level to filter by.
	SearchByMinLevel(minLevel model.UserLevel) UsersBuilder
	// SearchByMaxLevel specifies the maximum user level to filter by.
	SearchByMaxLevel(maxLevel model.UserLevel) UsersBuilder
	// SearchByCanUpload specifies whether users can upload free content.
	SearchByCanUpload(canUpload bool) UsersBuilder
	// SearchByIsApprover specifies whether users can approve posts.
	SearchByIsApprover(isApprover bool) UsersBuilder
	// SearchByOrder specifies the order in which users are retrieved.
	SearchByOrder(order model.Order) UsersBuilder
	// Execute sends the constructed query and returns the requested user information and an error, if any.
	Execute() ([]model.User, error)
}

// NewGetUsersBuilder creates a new UsersBuilder with the provided RequestContext.
//
// Parameters:
//   - requestContext: The context for the API request, including the host, user agent, username, and API key.
//
// Returns:
//   - UsersBuilder: An instance of the UsersBuilder interface.
func NewGetUsersBuilder(requestContext model.RequestContext) UsersBuilder {
	return &getUsers{requestContext: requestContext, query: make(map[string]string)}
}

// getUsers is an implementation of the UsersBuilder interface.
type getUsers struct {
	requestContext model.RequestContext
	query          map[string]string
}

// SearchByName specifies a username to search for.
//
// Parameters:
//   - userName: The username to search for.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByName(userName string) UsersBuilder {
	g.query["search[name_matches]"] = userName
	return g
}

// SearchByAbout specifies a text to search in the 'about' field of user profiles.
//
// Parameters:
//   - about: The text to search for in the 'about' field of user profiles.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByAbout(about string) UsersBuilder {
	g.query["search[about_me]"] = about
	return g
}

// SearchByAvatarID specifies an avatar ID to search for.
//
// Parameters:
//   - avatarID: The avatar ID to search for.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByAvatarID(avatarID model.PostID) UsersBuilder {
	g.query["search[avatar_id]"] = strconv.FormatInt(int64(avatarID), 10)
	return g
}

// SearchByLevel specifies a user level to filter by.
//
// Parameters:
//   - level: The user level to filter by.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByLevel(level model.UserLevel) UsersBuilder {
	g.query["search[level]"] = strconv.Itoa(int(level))
	return g
}

// SearchByMinLevel specifies the minimum user level to filter by.
//
// Parameters:
//   - minLevel: The minimum user level to filter by.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByMinLevel(minLevel model.UserLevel) UsersBuilder {
	g.query["search[min_level]"] = strconv.Itoa(int(minLevel))
	return g
}

// SearchByMaxLevel specifies the maximum user level to filter by.
//
// Parameters:
//   - maxLevel: The maximum user level to filter by.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByMaxLevel(maxLevel model.UserLevel) UsersBuilder {
	g.query["search[max_level]"] = strconv.Itoa(int(maxLevel))
	return g
}

// SearchByCanUpload specifies whether users can upload free content.
//
// Parameters:
//   - canUpload: Whether users can upload free content.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByCanUpload(canUpload bool) UsersBuilder {
	g.query["search[can_upload_free]"] = strconv.FormatBool(canUpload)
	return g
}

// SearchByIsApprover specifies whether users can approve posts.
//
// Parameters:
//   - isApprover: Whether users can approve posts.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByIsApprover(isApprover bool) UsersBuilder {
	g.query["search[can_approve_posts]"] = strconv.FormatBool(isApprover)
	return g
}

// SearchByOrder specifies the order in which users are retrieved.
//
// Parameters:
//   - order: The order in which users are retrieved.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SearchByOrder(order model.Order) UsersBuilder {
	g.query["search[order]"] = string(order)
	return g
}

// SetPage sets the page number for paginated results.
//
// Parameters:
//   - pageNumber: The page number for paginated results.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SetPage(pageNumber int) UsersBuilder {
	g.query["page"] = strconv.Itoa(pageNumber)
	return g
}

// SetLimit sets the maximum number of users to retrieve.
//
// Parameters:
//   - limitUser: The maximum number of users to retrieve.
//
// Returns:
//   - UsersBuilder: The instance of the UsersBuilder for method chaining.
func (g *getUsers) SetLimit(limitUser int) UsersBuilder {
	g.query["limit"] = strconv.Itoa(limitUser)
	return g
}

// Execute sends the constructed query and returns the requested user information and an error, if any.
//
// Returns:
//   - []model.User: A slice of user information.
//   - error: An error, if any, encountered during the API request or response handling.
func (g *getUsers) Execute() ([]model.User, error) {
	if g.requestContext.RateLimiter != nil {
		err := g.requestContext.RateLimiter.Wait(context.Background())
		if err != nil {
			return nil, err
		}
	}
	users, err := endpoints.GetUsers(g.requestContext, g.query)
	if err != nil {
		return nil, err
	}
	return users, nil
}