From 6333e966f24932dbb03bf0021e8776f8e0faf3ca Mon Sep 17 00:00:00 2001 From: Evan Fiordeliso Date: Sun, 3 Mar 2024 17:34:18 -0500 Subject: [PATCH] Add Streams endpoints to API --- api/api.go | 3 + api/streams/create_stream_marker.go | 70 ++++++++++++++++++++ api/streams/get_followed_streams.go | 65 +++++++++++++++++++ api/streams/get_stream_key.go | 43 +++++++++++++ api/streams/get_stream_markers.go | 78 +++++++++++++++++++++++ api/streams/get_streams.go | 99 +++++++++++++++++++++++++++++ api/streams/models.go | 87 +++++++++++++++++++++++++ api/streams/streams.go | 18 ++++++ 8 files changed, 463 insertions(+) create mode 100644 api/streams/create_stream_marker.go create mode 100644 api/streams/get_followed_streams.go create mode 100644 api/streams/get_stream_key.go create mode 100644 api/streams/get_stream_markers.go create mode 100644 api/streams/get_streams.go create mode 100644 api/streams/models.go create mode 100644 api/streams/streams.go diff --git a/api/api.go b/api/api.go index 06d3fd0..ac43adf 100644 --- a/api/api.go +++ b/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), } } diff --git a/api/streams/create_stream_marker.go b/api/streams/create_stream_marker.go new file mode 100644 index 0000000..ef83739 --- /dev/null +++ b/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 +} diff --git a/api/streams/get_followed_streams.go b/api/streams/get_followed_streams.go new file mode 100644 index 0000000..8a820c2 --- /dev/null +++ b/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 +} diff --git a/api/streams/get_stream_key.go b/api/streams/get_stream_key.go new file mode 100644 index 0000000..f296106 --- /dev/null +++ b/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 +} diff --git a/api/streams/get_stream_markers.go b/api/streams/get_stream_markers.go new file mode 100644 index 0000000..4d93cef --- /dev/null +++ b/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 +} diff --git a/api/streams/get_streams.go b/api/streams/get_streams.go new file mode 100644 index 0000000..c87b8f8 --- /dev/null +++ b/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 +} diff --git a/api/streams/models.go b/api/streams/models.go new file mode 100644 index 0000000..8e9d468 --- /dev/null +++ b/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"` +} diff --git a/api/streams/streams.go b/api/streams/streams.go new file mode 100644 index 0000000..2e8098c --- /dev/null +++ b/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, + } +}