Add Streams endpoints to API

api/api.go

@@ -26,6 +26,7 @@ import (
 	"go.fifitido.net/twitch/api/raids"
 	"go.fifitido.net/twitch/api/schedule"
 	"go.fifitido.net/twitch/api/search"
+	"go.fifitido.net/twitch/api/streams"
 )
 
 const HelixBaseUrl = "https://api.twitch.tv/helix"
@@ -56,6 +57,7 @@ type API struct {
 	Raids         *raids.Raids
 	Schedule      *schedule.Schedule
 	Search        *search.Search
+	Streams       *streams.Streams
 }
 
 func New(client *http.Client, baseUrl *url.URL) *API {
@@ -85,6 +87,7 @@ func New(client *http.Client, baseUrl *url.URL) *API {
 		Raids:         raids.New(client, baseUrl),
 		Schedule:      schedule.New(client, baseUrl),
 		Search:        search.New(client, baseUrl),
+		Streams:       streams.New(client, baseUrl),
 	}
 }
 

api/streams/create_stream_marker.go

@@ -0,0 +1,70 @@
+package streams
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+)
+
+type CreateStreamMarkerRequest struct {
+	// The ID of the broadcaster that’s streaming content.
+	// This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster’s editors.
+	UserID string `json:"user_id"`
+
+	// A short description of the marker to help the user remember why they marked the location.
+	// The maximum length of the description is 140 characters.
+	Description string `json:"description"`
+}
+
+type CreateStreamMarkerResponse struct {
+	// A list that contains the single marker that you added.
+	Data []StreamMarker `json:"data"`
+}
+
+// Adds a marker to a live stream. A marker is an arbitrary point in a live stream that the broadcaster or editor wants to mark,
+// so they can return to that spot later to create video highlights (see Video Producer, Highlights in the Twitch UX).
+//
+// You may not add markers:
+//
+// - If the stream is not live
+//
+// - If the stream has not enabled video on demand (VOD)
+//
+// - If the stream is a premiere (a live, first-viewing event that combines uploaded videos with live chat)
+//
+// - If the stream is a rerun of a past broadcast, including past premieres.
+//
+// Requires a user access token that includes the channel:manage:broadcast scope.
+func (s *Streams) CreateStreamMarker(ctx context.Context, body *CreateStreamMarkerRequest) (*CreateStreamMarkerResponse, error) {
+	endpoint := s.baseUrl.ResolveReference(&url.URL{Path: "streams/markers"})
+
+	r, w := io.Pipe()
+
+	go func() {
+		if err := json.NewEncoder(w).Encode(body); err != nil {
+			w.CloseWithError(err)
+		} else {
+			w.Close()
+		}
+	}()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint.String(), r)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+
+	var data CreateStreamMarkerResponse
+	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
+		return nil, err
+	}
+
+	return &data, nil
+}

api/streams/get_followed_streams.go

@@ -0,0 +1,65 @@
+package streams
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+
+	"github.com/google/go-querystring/query"
+	"go.fifitido.net/twitch/api/types"
+)
+
+type GetFollowedStreamsParams struct {
+	// The ID of the user whose list of followed streams you want to get. This ID must match the user ID in the access token.
+	UserID string `url:"user_id"`
+
+	// 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 100.
+	First int `url:"first,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
+	After *types.Cursor `url:"after,omitempty"`
+}
+
+type GetFollowedStreamsResponse struct {
+	// The list of live streams of broadcasters that the specified user follows.
+	// The list is in descending order by the number of viewers watching the stream.
+	// Because viewers come and go during a stream, it’s possible to find duplicate or missing streams in the list as you page through the results.
+	// The list is empty if none of the followed broadcasters are streaming live.
+	Data []Stream `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"`
+}
+
+// Gets the list of broadcasters that the user follows and that are streaming live.
+//
+// Requires a user access token that includes the user:read:follows scope.
+func (s *Streams) GetFollowedStreams(ctx context.Context, params *GetFollowedStreamsParams) (*GetFollowedStreamsResponse, error) {
+	v, _ := query.Values(params)
+	endpoint := s.baseUrl.ResolveReference(&url.URL{Path: "streams/followed", RawQuery: v.Encode()})
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+
+	var data GetFollowedStreamsResponse
+	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
+		return nil, err
+	}
+
+	return &data, nil
+}

api/streams/get_stream_key.go

@@ -0,0 +1,43 @@
+package streams
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+)
+
+type GetStreamKeyResponse struct {
+	// A list that contains the channel’s stream key.
+	Data []struct {
+		// The channel’s stream key.
+		StreamKey string `json:"stream_key"`
+	} `json:"data"`
+}
+
+// Gets the channel’s stream key.
+//
+// Requires a user access token that includes the channel:read:stream_key scope.
+//
+// The broadcaster ID must match the user ID in the access token.
+func (s *Streams) GetStreamKey(ctx context.Context, broadcasterID string) (*GetStreamKeyResponse, error) {
+	endpoint := s.baseUrl.ResolveReference(&url.URL{Path: "streams/key", RawQuery: url.Values{"broadcaster_id": {broadcasterID}}.Encode()})
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+
+	var data GetStreamKeyResponse
+	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
+		return nil, err
+	}
+
+	return &data, nil
+}

api/streams/get_stream_markers.go

@@ -0,0 +1,78 @@
+package streams
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+
+	"github.com/google/go-querystring/query"
+	"go.fifitido.net/twitch/api/types"
+)
+
+type GetStreamMarkersParams struct {
+	// A user ID. The request returns the markers from this user’s most recent video.
+	// This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster’s editors.
+	//
+	// This parameter and the video_id query parameter are mutually exclusive.
+	UserID *string `url:"user_id,omitempty"`
+
+	// A video on demand (VOD)/video ID. The request returns the markers from this VOD/video.
+	// The user in the access token must own the video or the user must be one of the broadcaster’s editors.
+	//
+	// This parameter and the user_id query parameter are mutually exclusive.
+	VideoID *string `url:"video_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 previous page of results.
+	// 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"`
+
+	// 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
+	After *types.Cursor `url:"after,omitempty"`
+}
+
+type GetStreamMarkersResponse struct {
+	// The list of markers grouped by the user that created the marks.
+	Data []StreamMarkers `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"`
+}
+
+// Gets a list of markers from the user’s most recent stream or from the specified VOD/video.
+// A marker is an arbitrary point in a live stream that the broadcaster or editor marked,
+// so they can return to that spot later to create video highlights (see Video Producer, Highlights in the Twitch UX).
+//
+// Requires a user access token that includes the user:read:broadcast or channel:manage:broadcast scope.
+func (s *Streams) GetStreamMarkers(ctx context.Context, params *GetStreamMarkersParams) (*GetStreamMarkersResponse, error) {
+	v, _ := query.Values(params)
+	endpoint := s.baseUrl.ResolveReference(&url.URL{Path: "streams/markers", RawQuery: v.Encode()})
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+
+	var data GetStreamMarkersResponse
+	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
+		return nil, err
+	}
+
+	return &data, nil
+}

api/streams/get_streams.go

@@ -0,0 +1,99 @@
+package streams
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+
+	"github.com/google/go-querystring/query"
+	"go.fifitido.net/twitch/api/types"
+)
+
+type GetStreamsParams struct {
+	// A user ID used to filter the list of streams.
+	// Returns only the streams of those users that are broadcasting.
+	// To specify multiple IDs, include the user_id parameter for each user. For example, &user_id=1234&user_id=5678.
+	// You may specify a maximum of 100 IDs.
+	UserIDs []string `url:"user_id,omitempty"`
+
+	// A user login name used to filter the list of streams.
+	// Returns only the streams of those users that are broadcasting.
+	// To specify multiple names, include the user_login parameter for each user. For example, &user_login=foo&user_login=bar.
+	// You may specify a maximum of 100 login names.
+	UserLogins []string `url:"user_login,omitempty"`
+
+	// A game (category) ID used to filter the list of streams.
+	// Returns only the streams that are broadcasting the game (category).
+	// You may specify a maximum of 100 IDs.
+	// To specify multiple IDs, include the game_id parameter for each game. For example, &game_id=9876&game_id=5432.
+	GameIDs []string `url:"game_id,omitempty"`
+
+	// The type of stream to filter the list of streams by.
+	// Possible values are:
+	//
+	// all, live
+	//
+	// The default is all.
+	Type *string `url:"type,omitempty"`
+
+	// A language code used to filter the list of streams.
+	// Returns only streams that broadcast in the specified language.
+	// Specify the language using an ISO 639-1 two-letter language code or other if the broadcast uses a language not in the list of supported stream languages.
+	//
+	// You may specify a maximum of 100 language codes.
+	// To specify multiple languages, include the language parameter for each language. For example, &language=de&language=fr.
+	Languages []string `url:"language,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 previous page of results.
+	// 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"`
+
+	// 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
+	After *types.Cursor `url:"after,omitempty"`
+}
+
+type GetStreamsResponse struct {
+	// The list of streams.
+	Data []Stream `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"`
+}
+
+// Gets a list of all streams. The list is in descending order by the number of viewers watching the stream.
+// Because viewers come and go during a stream, it’s possible to find duplicate or missing streams in the list as you page through the results.
+//
+// Requires an app access token or user access token.
+func (s *Streams) GetStreams(ctx context.Context, params *GetStreamsParams) (*GetStreamsResponse, error) {
+	v, _ := query.Values(params)
+	endpoint := s.baseUrl.ResolveReference(&url.URL{Path: "streams", RawQuery: v.Encode()})
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+
+	var data GetStreamsResponse
+	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
+		return nil, err
+	}
+
+	return &data, nil
+}

api/streams/models.go

@@ -0,0 +1,87 @@
+package streams
+
+import "time"
+
+type Stream struct {
+	// An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
+	ID string `json:"id"`
+
+	// The ID of the user that’s broadcasting the stream.
+	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 ID of the category or game being played.
+	GameID string `json:"game_id"`
+
+	// The name of the category or game being played.
+	GameName string `json:"game_name"`
+
+	// The type of stream. Possible values are:
+	//
+	// live
+	//
+	// If an error occurs, this field is set to an empty string.
+	Type string `json:"type"`
+
+	// The stream’s title. Is an empty string if not set.
+	Title string `json:"title"`
+
+	// The tags applied to the stream.
+	Tags []string `json:"tags"`
+
+	// The number of users watching the stream.
+	ViewerCount int `json:"viewer_count"`
+
+	// The UTC date and time (in RFC3339 format) of when the broadcast began.
+	StartedAt time.Time `json:"started_at"`
+
+	// The language that the stream uses.
+	// This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages.
+	Language string `json:"language"`
+
+	// A URL to an image of a frame from the last 5 minutes of the stream.
+	// Replace the width and height placeholders in the URL ({width}x{height}) with the size of the image you want, in pixels.
+	ThumbnailURL string `json:"thumbnail_url"`
+
+	// A Boolean value that indicates whether the stream is meant for mature audiences.
+	IsMature bool `json:"is_mature"`
+}
+
+type StreamMarker struct {
+	// An ID that identifies this marker.
+	ID string `json:"id"`
+
+	// The UTC date and time (in RFC3339 format) of when the user created the marker.
+	CreatedAt time.Time `json:"created_at"`
+
+	// The relative offset (in seconds) of the marker from the beginning of the stream.
+	PositionSeconds int `json:"position_seconds"`
+
+	// A description that the user gave the marker to help them remember why they marked the location.
+	Description string `json:"description"`
+}
+
+type StreamMarkers struct {
+	// The ID of the user that created the marker.
+	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"`
+
+	// A list of videos that contain markers. The list contains a single video.
+	Videos []struct {
+		// An ID that identifies this video.
+		VideoID string `json:"video_id"`
+
+		// The list of markers in this video. The list in ascending order by when the marker was created.
+		Markers []StreamMarker `json:"markers"`
+	} `json:"videos"`
+}

api/streams/streams.go

@@ -0,0 +1,18 @@
+package streams
+
+import (
+	"net/http"
+	"net/url"
+)
+
+type Streams struct {
+	client  *http.Client
+	baseUrl *url.URL
+}
+
+func New(client *http.Client, baseUrl *url.URL) *Streams {
+	return &Streams{
+		client:  client,
+		baseUrl: baseUrl,
+	}
+}