moderation.go

package reddit

import (
	"context"
	"fmt"
	"net/http"
	"net/url"
	"reflect"

	"github.com/google/go-querystring/query"
)

// ModerationService handles communication with the moderation
// related methods of the Reddit API.
//
// Reddit API docs: https://www.reddit.com/dev/api/#section_moderation
type ModerationService struct {
	client *Client
}

// ModAction is an action executed by a moderator of a subreddit, such
// as inviting another user to be a mod, or setting permissions.
type ModAction struct {
	ID      string     `json:"id,omitempty"`
	Action  string     `json:"action,omitempty"`
	Created *Timestamp `json:"created_utc,omitempty"`

	Moderator string `json:"mod,omitempty"`
	// Not the full ID, just the ID36.
	ModeratorID string `json:"mod_id36,omitempty"`

	// The author of whatever the action was produced on, e.g. a user, post, comment, etc.
	TargetAuthor string `json:"target_author,omitempty"`
	// This is the full ID of whatever the target was.
	TargetID        string `json:"target_fullname,omitempty"`
	TargetTitle     string `json:"target_title,omitempty"`
	TargetPermalink string `json:"target_permalink,omitempty"`
	TargetBody      string `json:"target_body,omitempty"`

	Subreddit string `json:"subreddit,omitempty"`
	// Not the full ID, just the ID36.
	SubredditID string `json:"sr_id36,omitempty"`
}

// ModPermissions are the different permissions moderators have or don't have on a subreddit.
// Read about them here: https://mods.reddithelp.com/hc/en-us/articles/360009381491-User-Management-moderators-and-permissions
type ModPermissions struct {
	All          bool `permission:"all"`
	Access       bool `permission:"access"`
	ChatConfig   bool `permission:"chat_config"`
	ChatOperator bool `permission:"chat_operator"`
	Config       bool `permission:"config"`
	Flair        bool `permission:"flair"`
	Mail         bool `permission:"mail"`
	Posts        bool `permission:"posts"`
	Wiki         bool `permission:"wiki"`
}

func (p *ModPermissions) String() (s string) {
	if p == nil {
		return "+all"
	}

	t := reflect.TypeOf(*p)
	v := reflect.ValueOf(*p)

	for i := 0; i < t.NumField(); i++ {
		if v.Field(i).Kind() != reflect.Bool {
			continue
		}

		permission := t.Field(i).Tag.Get("permission")
		permitted := v.Field(i).Bool()

		if permitted {
			s += "+"
		} else {
			s += "-"
		}

		s += permission

		if i != t.NumField()-1 {
			s += ","
		}
	}

	return
}

// BanConfig configures the ban of the user being banned.
type BanConfig struct {
	Reason string `url:"reason,omitempty"`
	// Not visible to the user being banned.
	ModNote string `url:"note,omitempty"`
	// How long the ban will last. 0-999. Leave nil for permanent.
	Days *int `url:"duration,omitempty"`
	// Note to include in the ban message to the user.
	Message string `url:"ban_message,omitempty"`
}

// Actions gets a list of moderator actions on a subreddit.
func (s *ModerationService) Actions(ctx context.Context, subreddit string, opts *ListModActionOptions) ([]*ModAction, *Response, error) {
	path := fmt.Sprintf("r/%s/about/log", subreddit)
	l, resp, err := s.client.getListing(ctx, path, opts)
	if err != nil {
		return nil, resp, err
	}
	return l.ModActions(), resp, nil
}

// AcceptInvite accepts a pending invite to moderate the specified subreddit.
func (s *ModerationService) AcceptInvite(ctx context.Context, subreddit string) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/accept_moderator_invite", subreddit)

	form := url.Values{}
	form.Set("api_type", "json")

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Approve a post or comment via its full ID.
func (s *ModerationService) Approve(ctx context.Context, id string) (*Response, error) {
	path := "api/approve"

	form := url.Values{}
	form.Set("id", id)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Remove a post, comment or modmail message via its full ID.
func (s *ModerationService) Remove(ctx context.Context, id string) (*Response, error) {
	path := "api/remove"

	form := url.Values{}
	form.Set("id", id)
	form.Set("spam", "false")

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// RemoveSpam removes a post, comment or modmail message via its full ID and marks it as spam.
func (s *ModerationService) RemoveSpam(ctx context.Context, id string) (*Response, error) {
	path := "api/remove"

	form := url.Values{}
	form.Set("id", id)
	form.Set("spam", "true")

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Leave abdicates your moderator status in a subreddit via its full ID.
func (s *ModerationService) Leave(ctx context.Context, subredditID string) (*Response, error) {
	path := "api/leavemoderator"

	form := url.Values{}
	form.Set("id", subredditID)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// LeaveContributor abdicates your approved user status in a subreddit via its full ID.
func (s *ModerationService) LeaveContributor(ctx context.Context, subredditID string) (*Response, error) {
	path := "api/leavecontributor"

	form := url.Values{}
	form.Set("id", subredditID)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Reported returns posts and comments that have been reported.
func (s *ModerationService) Reported(ctx context.Context, subreddit string, opts *ListOptions) ([]*Post, []*Comment, *Response, error) {
	path := fmt.Sprintf("r/%s/about/reports", subreddit)
	l, resp, err := s.client.getListing(ctx, path, opts)
	if err != nil {
		return nil, nil, resp, err
	}
	return l.Posts(), l.Comments(), resp, nil
}

// Spam returns posts and comments marked as spam.
func (s *ModerationService) Spam(ctx context.Context, subreddit string, opts *ListOptions) ([]*Post, []*Comment, *Response, error) {
	path := fmt.Sprintf("r/%s/about/spam", subreddit)
	l, resp, err := s.client.getListing(ctx, path, opts)
	if err != nil {
		return nil, nil, resp, err
	}
	return l.Posts(), l.Comments(), resp, nil
}

// Queue returns posts and comments requiring moderator reviews, such as one that have been
// reported or caught in the spam filter.
func (s *ModerationService) Queue(ctx context.Context, subreddit string, opts *ListOptions) ([]*Post, []*Comment, *Response, error) {
	path := fmt.Sprintf("r/%s/about/modqueue", subreddit)
	l, resp, err := s.client.getListing(ctx, path, opts)
	if err != nil {
		return nil, nil, resp, err
	}
	return l.Posts(), l.Comments(), resp, nil
}

// Unmoderated returns posts that have yet to be approved/removed by a mod.
func (s *ModerationService) Unmoderated(ctx context.Context, subreddit string, opts *ListOptions) ([]*Post, *Response, error) {
	path := fmt.Sprintf("r/%s/about/unmoderated", subreddit)
	l, resp, err := s.client.getListing(ctx, path, opts)
	if err != nil {
		return nil, resp, err
	}
	return l.Posts(), resp, nil
}

// Edited gets posts and comments that have been edited recently.
func (s *ModerationService) Edited(ctx context.Context, subreddit string, opts *ListOptions) ([]*Post, []*Comment, *Response, error) {
	path := fmt.Sprintf("r/%s/about/edited", subreddit)
	l, resp, err := s.client.getListing(ctx, path, opts)
	if err != nil {
		return nil, nil, resp, err
	}
	return l.Posts(), l.Comments(), resp, nil
}

// IgnoreReports prevents reports on a post or comment from causing notifications.
func (s *ModerationService) IgnoreReports(ctx context.Context, id string) (*Response, error) {
	path := "api/ignore_reports"

	form := url.Values{}
	form.Set("id", id)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// UnignoreReports allows reports on a post or comment to cause notifications.
func (s *ModerationService) UnignoreReports(ctx context.Context, id string) (*Response, error) {
	path := "api/unignore_reports"

	form := url.Values{}
	form.Set("id", id)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Invite a user to become a moderator of the subreddit.
// If permissions is nil, all permissions will be granted.
func (s *ModerationService) Invite(ctx context.Context, subreddit string, username string, permissions *ModPermissions) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/friend", subreddit)

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("name", username)
	form.Set("type", "moderator_invite")
	form.Set("permissions", permissions.String())

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Uninvite a user from becoming a moderator of the subreddit.
func (s *ModerationService) Uninvite(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.deleteRelationship(ctx, subreddit, username, "moderator_invite")
}

// SetPermissions sets the mod permissions for the user in the subreddit.
// If permissions is nil, all permissions will be granted.
func (s *ModerationService) SetPermissions(ctx context.Context, subreddit string, username string, permissions *ModPermissions) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/setpermissions", subreddit)

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("name", username)
	form.Set("type", "moderator_invite")
	form.Set("permissions", permissions.String())

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Ban a user from the subreddit.
func (s *ModerationService) Ban(ctx context.Context, subreddit string, username string, config *BanConfig) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/friend", subreddit)

	form, err := query.Values(config)
	if err != nil {
		return nil, err
	}

	form.Set("api_type", "json")
	form.Set("name", username)
	form.Set("type", "banned")

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Unban a user from the subreddit.
func (s *ModerationService) Unban(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.deleteRelationship(ctx, subreddit, username, "banned")
}

// BanWiki bans a user from contributing to the subreddit wiki.
func (s *ModerationService) BanWiki(ctx context.Context, subreddit string, username string, config *BanConfig) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/friend", subreddit)

	form, err := query.Values(config)
	if err != nil {
		return nil, err
	}

	form.Set("api_type", "json")
	form.Set("name", username)
	form.Set("type", "wikibanned")

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// UnbanWiki unbans a user from contributing to the subreddit wiki.
func (s *ModerationService) UnbanWiki(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.deleteRelationship(ctx, subreddit, username, "wikibanned")
}

// Mute a user in the subreddit.
func (s *ModerationService) Mute(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.createRelationship(ctx, subreddit, username, "muted")
}

// Unmute a user in the subreddit.
func (s *ModerationService) Unmute(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.deleteRelationship(ctx, subreddit, username, "muted")
}

// ApproveUser adds a user as an approved user to the subreddit.
func (s *ModerationService) ApproveUser(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.createRelationship(ctx, subreddit, username, "contributor")
}

// UnapproveUser removes a user as an approved user to the subreddit.
func (s *ModerationService) UnapproveUser(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.deleteRelationship(ctx, subreddit, username, "contributor")
}

// ApproveUserWiki adds a user as an approved wiki contributor in the subreddit.
func (s *ModerationService) ApproveUserWiki(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.createRelationship(ctx, subreddit, username, "wikicontributor")
}

// UnapproveUserWiki removes a user as an approved wiki contributor in the subreddit.
func (s *ModerationService) UnapproveUserWiki(ctx context.Context, subreddit string, username string) (*Response, error) {
	return s.deleteRelationship(ctx, subreddit, username, "wikicontributor")
}

func (s *ModerationService) createRelationship(ctx context.Context, subreddit, username, relationship string) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/friend", subreddit)

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("name", username)
	form.Set("type", relationship)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

func (s *ModerationService) deleteRelationship(ctx context.Context, subreddit, username, relationship string) (*Response, error) {
	path := fmt.Sprintf("r/%s/api/unfriend", subreddit)

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("name", username)
	form.Set("type", relationship)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Distinguish your post or comment via its full ID, adding a moderator tag to it.
// todo: add how=admin and how=special? They require special privileges.
func (s *ModerationService) Distinguish(ctx context.Context, id string) (*Response, error) {
	path := "api/distinguish"

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("how", "yes")
	form.Set("id", id)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// DistinguishAndSticky your comment via its full ID, adding a moderator tag to it
// and stickying the comment at the top of the thread.
func (s *ModerationService) DistinguishAndSticky(ctx context.Context, id string) (*Response, error) {
	path := "api/distinguish"

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("how", "yes")
	form.Set("sticky", "true")
	form.Set("id", id)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}

// Undistinguish your post or comment via its full ID, removing the moderator tag from it.
func (s *ModerationService) Undistinguish(ctx context.Context, id string) (*Response, error) {
	path := "api/distinguish"

	form := url.Values{}
	form.Set("api_type", "json")
	form.Set("how", "no")
	form.Set("id", id)

	req, err := s.client.NewRequest(http.MethodPost, path, form)
	if err != nil {
		return nil, err
	}

	return s.client.Do(ctx, req, nil)
}