go-twitch/api/subscriptions/get_broadcaster_subscriptions.go

package subscriptions

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

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

type GetBroadcasterSubscriptionsParams struct {
	// The broadcaster’s ID. This ID must match the user ID in the access token.
	BroadcasterID string `url:"broadcaster_id"`

	// Filters the list to include only the specified subscribers.
	// To specify more than one subscriber, include this parameter for each subscriber. For example, &user_id=1234&user_id=5678.
	// You may specify a maximum of 100 subscribers.
	UserIDs []string `url:"user_id,omitempty"`

	// The maximum number of items to return per page in the response.
	// The minimum page size is 1 item per page and the maximum is 100 items per page.
	// The default is 20.
	First *int `url:"first,omitempty"`

	// The cursor used to get the next page of results. Do not specify if you set the user_id query parameter.
	// The Pagination object in the response contains the cursor’s value.
	// Read More: https://dev.twitch.tv/docs/api/guide#pagination
	After *types.Cursor `url:"after,omitempty"`

	// The cursor used to get the previous page of results. Do not specify if you set the user_id query parameter.
	// The Pagination object in the response contains the cursor’s value.
	// Read More: https://dev.twitch.tv/docs/api/guide#pagination
	Before *types.Cursor `url:"before,omitempty"`
}

type GetBroadcasterSubscriptionsResponse struct {
	// The list of users that subscribe to the broadcaster. The list is empty if the broadcaster has no subscribers.
	Data []BroadcasterSubscription `json:"data"`

	// Contains the information used to page through the list of results.
	// The object is empty if there are no more pages left to page through.
	// Read More: https://dev.twitch.tv/docs/api/guide#pagination
	Pagination types.Pagination `json:"pagination"`

	// The current number of subscriber points earned by this broadcaster.
	// Points are based on the subscription tier of each user that subscribes to this broadcaster.
	// For example, a Tier 1 subscription is worth 1 point, Tier 2 is worth 2 points, and Tier 3 is worth 6 points.
	// The number of points determines the number of emote slots that are unlocked for the broadcaster (see Subscriber Emote Slots).
	Points int `json:"points"`

	// The total number of users that subscribe to this broadcaster.
	Total int `json:"total"`
}

type BroadcasterSubscription struct {
	// An ID that identifies the broadcaster.
	BroadcasterID string `json:"broadcaster_id"`

	// The broadcaster’s login name.
	BroadcasterLogin string `json:"broadcaster_login"`

	// The broadcaster’s display name.
	BroadcasterName string `json:"broadcaster_name"`

	// The ID of the user that gifted the subscription to the user. Is an empty string if is_gift is false.
	GifterID string `json:"gifter_id"`

	// The gifter’s login name. Is an empty string if is_gift is false.
	GifterLogin string `json:"gifter_login"`

	// The gifter’s display name. Is an empty string if is_gift is false.
	GifterName string `json:"gifter_name"`

	// A Boolean value that determines whether the subscription is a gift subscription. Is true if the subscription was gifted.
	IsGift bool `json:"is_gift"`

	// The name of the subscription.
	PlanName string `json:"plan_name"`

	// The type of subscription. Possible values are:
	//
	// 1000 — Tier 1
	//
	// 2000 — Tier 2
	//
	// 3000 — Tier 3
	Tier string `json:"tier"`

	// An ID that identifies the subscribing user.
	UserID string `json:"user_id"`

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

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

// Gets a list of users that subscribe to the specified broadcaster.
//
// Requires a user access token that includes the channel:read:subscriptions scope.
//
// A Twitch extensions may use an app access token if the broadcaster has granted the channel:read:subscriptions scope from within the Twitch Extensions manager.
func (c *Subscriptions) GetBroadcasterSubscriptions(ctx context.Context, params *GetBroadcasterSubscriptionsParams) (*GetBroadcasterSubscriptionsResponse, error) {
	v, _ := query.Values(params)
	endpoint := c.baseUrl.ResolveReference(&url.URL{Path: "subscriptions", RawQuery: v.Encode()})

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

	res, err := c.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 broadcaster subscriptions (%d)", res.StatusCode)
	}

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

	return &data, nil
}