go-twitch/api/entitlements/get_drops_entitlements.go

package entitlements

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

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

type GetDropsEntitlementsParams struct {
	// An ID that identifies the entitlement to get.
	// Include this parameter for each entitlement you want to get.
	// For example, id=1234&id=5678.
	// You may specify a maximum of 100 IDs.
	IDs []string `url:"id,omitempty"`

	// An ID that identifies a user that was granted entitlements.
	UserID *string `url:"user_id,omitempty"`

	// An ID that identifies a game that offered entitlements.
	GameID *string `url:"game_id,omitempty"`

	// The entitlement’s fulfillment status. Used to filter the list to only those with the specified status.
	FulfillmentStatus *FulfillmentStatus `url:"fulfillment_status,omitempty"`

	// The cursor used to get the next page of results.
	// The Pagination object in the response contains the cursor’s value.
	// Read More: https://dev.twitch.tv/docs/api/guide#pagination
	Cursor *string `url:"cursor,omitempty"`

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

type GetDropsEntitlementsResponse struct {
	// The list of entitlements.
	Data []Entitlement `json:"data"`

	// 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"`
}

type Entitlement struct {
	// An ID that identifies the entitlement.
	ID string `json:"id"`

	// An ID that identifies the benefit (reward).
	BenefitID string `json:"benefit_id"`

	// The UTC date and time (in RFC3339 format) of when the entitlement was granted.
	Timestamp time.Time `json:"timestamp"`

	// An ID that identifies the user who was granted the entitlement.
	UserID string `json:"user_id"`

	// An ID that identifies the game the user was playing when the reward was entitled.
	GameID string `json:"game_id"`

	// The entitlement’s fulfillment status.
	FulfillmentStatus FulfillmentStatus `json:"fulfillment_status"`

	// The UTC date and time (in RFC3339 format) of when the entitlement was last updated.
	LastUpdated time.Time `json:"last_updated"`
}

// Gets an organization’s list of entitlements that have been granted to a game, a user, or both.
//
// NOTE: Entitlements returned in the response body data are not guaranteed to be sorted by any field returned by the API. To retrieve CLAIMED or FULFILLED entitlements, use the fulfillment_status query parameter to filter results. To retrieve entitlements for a specific game, use the game_id query parameter to filter results.
//
// The following table identifies the request parameters that you may specify based on the type of access token used.
// Access token type |	Parameter       | Description
// ------------------|------------------|---------------------------------------------------------------------------------------------------------------------
// App               | None             | If you don’t specify request parameters, the request returns all entitlements that your organization owns.
// App               | user_id          | The request returns all entitlements for any game that the organization granted to the specified user.
// App               | user_id, game_id | The request returns all entitlements that the specified game granted to the specified user.
// App               | game_id          | The request returns all entitlements that the specified game granted to all entitled users.
// User              | None             | If you don’t specify request parameters, the request returns all entitlements for any game that the organization granted to the user identified in the access token.
// User              | user_id          | Invalid.
// User              | user_id, game_id | Invalid.
// User              | game_id          | The request returns all entitlements that the specified game granted to the user identified in the access token.
//
// Requires an app access token or user access token. The client ID in the access token must own the game.
func (c *Entitlements) GetDropsEntitlements(ctx context.Context, params *GetDropsEntitlementsParams) (*GetDropsEntitlementsResponse, error) {
	v, _ := query.Values(params)
	endpoint := c.baseUrl.ResolveReference(&url.URL{Path: "entitlements/drops", 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 drops entitlements (%d)", res.StatusCode)
	}

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

	return &data, nil
}