go-twitch/api/bits/get_bits_leaderboard.go

package bits

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"time"

	"github.com/google/go-querystring/query"
	"go.fifitido.net/twitch/api/types"
)

type GetBitsLeaderboardParams struct {
	// The number of results to return. The minimum count is 1 and the maximum is 100. The default is 10.
	Count *int `url:"count,omitempty"`

	// The time period over which data is aggregated (uses the PST time zone).
	Period *Period `url:"period,omitempty"`

	// The start date, in RFC3339 format, used for determining the aggregation period. Specify this parameter only if you specify the period query parameter.
	// The start date is ignored if period is all.
	//
	// Note that the date is converted to PST before being used, so if you set the start time to 2022-01-01T00:00:00.0Z and period to month,
	// the actual reporting period is December 2021, not January 2022. If you want the reporting period to be January 2022,
	// you must set the start time to 2022-01-01T08:00:00.0Z or 2022-01-01T00:00:00.0-08:00.
	//
	// If your start date uses the ‘+’ offset operator (for example, 2022-01-01T00:00:00.0+05:00), you must URL encode the start date.
	StartedAt *time.Time `url:"started_at,omitempty"`

	// An ID that identifies a user that cheered bits in the channel.
	// If count is greater than 1, the response may include users ranked above and below the specified user.
	// To get the leaderboard’s top leaders, don’t specify a user ID.
	UserID *string `url:"user_id,omitempty"`
}

type GetBitsLeaderboardResponse struct {
	// A list of leaderboard leaders. The leaders are returned in rank order by how much they’ve cheered.
	// The array is empty if nobody has cheered bits.
	Data []LeaderboardEntry `json:"data"`

	// The reporting window’s start and end dates, in RFC3339 format. The dates are calculated by using the started_at and period query parameters.
	// If you don’t specify the started_at query parameter, the fields contain empty strings.
	DateRange types.DateRange `json:"date_range"`

	// The number of ranked users in data.
	// This is the value in the count query parameter or the total number of entries on the leaderboard, whichever is less.
	Total int `json:"total"`
}

type LeaderboardEntry struct {
	// An ID that identifies a user on the leaderboard.
	UserID string `json:"user_id"`

	// The user’s login name.
	UserLogin string `json:"user_login"`

	// The user’s display name.
	UserName string `json:"user_name"`

	// The user’s position on the leaderboard.
	Rank int `json:"rank"`

	// The number of Bits the user has cheered.
	Score int `json:"score"`
}

// Gets the Bits leaderboard for the authenticated broadcaster.
//
// Requires a user access token that includes the bits:read scope.
func (b *Bits) GetBitsLeaderboard(ctx context.Context, params *GetBitsLeaderboardParams) (*GetBitsLeaderboardResponse, error) {
	v, _ := query.Values(params)
	endpoint := b.baseUrl.ResolveReference(&url.URL{Path: "bits/leaderboard", RawQuery: v.Encode()})

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.String(), nil)
	if err != nil {
		return nil, err
	}

	res, err := b.client.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	statusOK := res.StatusCode >= 200 && res.StatusCode < 300
	if !statusOK {
		return nil, fmt.Errorf("failed to get bits leaderboard (%d)", res.StatusCode)
	}

	var data GetBitsLeaderboardResponse
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		return nil, err
	}

	return &data, nil
}