go-twitch/api/goals/get_creator_goals.go

package goals

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

type GetCreatorGoalsResponse struct {
	Data []Goal `json:"data"`
}

type Goal struct {
	// An ID that identifies this goal.
	Id string `json:"id"`

	// An ID that identifies the broadcaster that created the goal.
	BroadcasterId string `json:"broadcaster_id"`

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

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

	// The type of goal. Possible values are:
	//
	// follower — The goal is to increase followers.
	//
	// subscription — The goal is to increase subscriptions.
	// This type shows the net increase or decrease in tier points associated with the subscriptions.
	//
	// subscription_count — The goal is to increase subscriptions.
	// This type shows the net increase or decrease in the number of subscriptions.
	//
	// new_subscription — The goal is to increase subscriptions.
	// This type shows only the net increase in tier points associated with the subscriptions
	// (it does not account for users that unsubscribed since the goal started).
	//
	// new_subscription_count — The goal is to increase subscriptions.
	// This type shows only the net increase in the number of subscriptions
	// (it does not account for users that unsubscribed since the goal started).
	Type string `json:"type"`

	// A description of the goal. Is an empty string if not specified.
	Description string `json:"description"`

	// The goal’s current value.
	//
	// The goal’s type determines how this value is increased or decreased.
	//
	// If type is follower, this field is set to the broadcasters current number of followers.
	// This number increases with new followers and decreases when users unfollow the broadcaster.
	//
	// If type is subscription, this field is increased and decreased by the points value associated with the subscription tier.
	// For example, if a tier-two subscription is worth 2 points, this field is increased or decreased by 2, not 1.
	//
	// If type is subscription_count, this field is increased by 1 for each new subscription and decreased by 1 for each user that unsubscribes.
	//
	// If type is new_subscription, this field is increased by the points value associated with the subscription tier.
	// For example, if a tier-two subscription is worth 2 points, this field is increased by 2, not 1.
	//
	// If type is new_subscription_count, this field is increased by 1 for each new subscription.
	CurrentAmount int `json:"current_amount"`

	// The goal’s target value.
	//
	// For example, if the broadcaster has 200 followers before creating the goal,
	// and their goal is to double that number, this field is set to 400.
	TargetAmount int `json:"target_amount"`

	// The UTC date and time (in RFC3339 format) that the broadcaster created the goal.
	CreatedAt time.Time `json:"created_at"`
}

// Gets the broadcaster’s list of active goals. Use this endpoint to get the current progress of each goal.
//
// Instead of polling for the progress of a goal, consider subscribing to receive notifications when a goal makes progress
// using the channel.goal.progress subscription type. Read More: https://dev.twitch.tv/docs/api/goals#requesting-event-notifications
//
// Requires a user access token that includes the channel:read:goals scope.
func (c *Goals) GetCreatorGoals(ctx context.Context, broadcasterID string) (*GetCreatorGoalsResponse, error) {
	endpoint := c.baseUrl.ResolveReference(&url.URL{Path: "goals", RawQuery: "broadcaster_id=" + broadcasterID})

	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 creator goals (%d)", res.StatusCode)
	}

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

	return &data, nil
}