twitchrb 1.11.0 → 2.0.0

data/lib/twitch/resources/guest_star.rb

@@ -0,0 +1,102 @@
+module Twitch
+  # Guest Star is in beta, so Twitch may change these endpoints
+  class GuestStarResource < Resource
+    # Required scope: channel:read:guest_star, channel:manage:guest_star, moderator:read:guest_star or moderator:manage:guest_star
+    # moderator_id must match the user in the OAuth token
+    def settings(broadcaster_id:, moderator_id:)
+      response = get_request("guest_star/channel_settings", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id })
+      GuestStarSettings.new(response.body.dig("data")[0])
+    end
+
+    # Required scope: channel:manage:guest_star
+    # broadcaster_id must match the user in the OAuth token
+    # Available attributes: is_moderator_send_live_enabled, slot_count, is_browser_source_audio_enabled,
+    # group_layout, regenerate_browser_sources
+    def update_settings(broadcaster_id:, **attributes)
+      put_request(query_path("guest_star/channel_settings", broadcaster_id: broadcaster_id), body: attributes)
+    end
+
+    # Required scope: channel:read:guest_star, channel:manage:guest_star, moderator:read:guest_star or moderator:manage:guest_star
+    def session(broadcaster_id:, moderator_id:)
+      response = get_request("guest_star/session", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id })
+      data = response.body.dig("data")
+
+      return nil if data.nil? || data.empty?
+
+      GuestStarSession.new(data[0])
+    end
+
+    # Required scope: channel:manage:guest_star
+    # broadcaster_id must match the user in the OAuth token
+    def create_session(broadcaster_id:)
+      response = post_request(query_path("guest_star/session", broadcaster_id: broadcaster_id), body: {})
+      GuestStarSession.new(response.body.dig("data")[0])
+    end
+
+    # Required scope: channel:manage:guest_star
+    # broadcaster_id must match the user in the OAuth token
+    def end_session(broadcaster_id:, session_id:)
+      response = delete_request("guest_star/session", params: { broadcaster_id: broadcaster_id, session_id: session_id })
+      GuestStarSession.new(response.body.dig("data")[0])
+    end
+
+    # Required scope: channel:read:guest_star, channel:manage:guest_star, moderator:read:guest_star or moderator:manage:guest_star
+    def invites(broadcaster_id:, moderator_id:, session_id:)
+      response = get_request("guest_star/invites", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id, session_id: session_id })
+      collection(response, type: GuestStarInvite)
+    end
+
+    # Required scope: channel:manage:guest_star or moderator:manage:guest_star
+    # moderator_id must match the user in the OAuth token
+    def send_invite(broadcaster_id:, moderator_id:, session_id:, guest_id:)
+      params = { broadcaster_id: broadcaster_id, moderator_id: moderator_id, session_id: session_id, guest_id: guest_id }
+      post_request(query_path("guest_star/invites", params), body: {})
+    end
+
+    # Required scope: channel:manage:guest_star or moderator:manage:guest_star
+    # moderator_id must match the user in the OAuth token
+    def delete_invite(broadcaster_id:, moderator_id:, session_id:, guest_id:)
+      delete_request("guest_star/invites", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id, session_id: session_id, guest_id: guest_id })
+    end
+
+    # Required scope: channel:manage:guest_star or moderator:manage:guest_star
+    # moderator_id must match the user in the OAuth token
+    def assign_slot(broadcaster_id:, moderator_id:, session_id:, guest_id:, slot_id:)
+      params = { broadcaster_id: broadcaster_id, moderator_id: moderator_id, session_id: session_id, guest_id: guest_id, slot_id: slot_id }
+      post_request(query_path("guest_star/slot", params), body: {})
+    end
+
+    # Moves a guest to another slot, or swaps two guests when destination_slot_id is occupied
+    # Required scope: channel:manage:guest_star or moderator:manage:guest_star
+    def update_slot(broadcaster_id:, moderator_id:, session_id:, source_slot_id:, destination_slot_id: nil)
+      params = {
+        broadcaster_id: broadcaster_id,
+        moderator_id: moderator_id,
+        session_id: session_id,
+        source_slot_id: source_slot_id,
+        destination_slot_id: destination_slot_id
+      }
+      patch_request(query_path("guest_star/slot", params), body: {})
+    end
+
+    # Required scope: channel:manage:guest_star or moderator:manage:guest_star
+    def delete_slot(broadcaster_id:, moderator_id:, session_id:, guest_id:, slot_id:, should_reinvite_guest: nil)
+      params = {
+        broadcaster_id: broadcaster_id,
+        moderator_id: moderator_id,
+        session_id: session_id,
+        guest_id: guest_id,
+        slot_id: slot_id,
+        should_reinvite_guest: should_reinvite_guest
+      }.compact
+      delete_request("guest_star/slot", params: params)
+    end
+
+    # Required scope: channel:manage:guest_star or moderator:manage:guest_star
+    # Available attributes: is_audio_enabled, is_video_enabled, is_live, volume
+    def update_slot_settings(broadcaster_id:, moderator_id:, session_id:, slot_id:, **attributes)
+      params = attributes.merge(broadcaster_id: broadcaster_id, moderator_id: moderator_id, session_id: session_id, slot_id: slot_id)
+      patch_request(query_path("guest_star/slot_settings", params), body: {})
+    end
+  end
+end

data/lib/twitch/resources/moderators.rb

@@ -3,17 +3,17 @@ module Twitch
     # User ID must match the user in the OAuth token
     def channels(user_id:)
       response = get_request("moderation/channels", params: { user_id: user_id })
-      Collection.from_response(response, type: Channel)
+      collection(response, type: Channel)
     end
 
     # Broadcaster ID must match the user in the OAuth token
     def list(broadcaster_id:, **params)
       response = get_request("moderation/moderators", params: params.merge(broadcaster_id: broadcaster_id))
-      Collection.from_response(response, type: Moderator)
+      collection(response, type: Moderator)
     end
 
     def create(broadcaster_id:, user_id:)
-      post_request("moderation/moderators", body: { broadcaster_id: broadcaster_id, user_id: user_id })
+      post_request(query_path("moderation/moderators", broadcaster_id: broadcaster_id, user_id: user_id), body: {})
     end
 
     def delete(broadcaster_id:, user_id:)

data/lib/twitch/resources/pinned_chat_messages.rb

@@ -11,12 +11,12 @@ module Twitch
 
     # moderator_id must match the user in the OAuth token
     def create(broadcaster_id:, moderator_id:, message_id:, duration_seconds: nil)
-      put_request(query_path(broadcaster_id:, moderator_id:, message_id:, duration_seconds:), body: {})
+      put_request(pins_path(broadcaster_id:, moderator_id:, message_id:, duration_seconds:), body: {})
     end
 
     # moderator_id must match the user in the OAuth token
     def update(broadcaster_id:, moderator_id:, message_id:, duration_seconds: nil)
-      patch_request(query_path(broadcaster_id:, moderator_id:, message_id:, duration_seconds:), body: {})
+      patch_request(pins_path(broadcaster_id:, moderator_id:, message_id:, duration_seconds:), body: {})
     end
 
     # moderator_id must match the user in the OAuth token
@@ -26,15 +26,8 @@ module Twitch
 
     private
 
-    def query_path(broadcaster_id:, moderator_id:, message_id:, duration_seconds:)
-      params = {
-        broadcaster_id: broadcaster_id,
-        moderator_id: moderator_id,
-        message_id: message_id,
-        duration_seconds: duration_seconds
-      }.compact
-
-      "chat/pins?#{URI.encode_www_form(params)}"
+    def pins_path(broadcaster_id:, moderator_id:, message_id:, duration_seconds:)
+      query_path("chat/pins", broadcaster_id: broadcaster_id, moderator_id: moderator_id, message_id: message_id, duration_seconds: duration_seconds)
     end
   end
 end

data/lib/twitch/resources/polls.rb

@@ -3,7 +3,7 @@ module Twitch
     # Broadcaster ID must match the user in the OAuth token
     def list(broadcaster_id:, **params)
       response = get_request("polls", params: params.merge(broadcaster_id: broadcaster_id))
-      Collection.from_response(response, type: Poll)
+      collection(response, type: Poll)
     end
 
     # Broadcaster ID must match the user in the OAuth token

data/lib/twitch/resources/predictions.rb

@@ -5,7 +5,7 @@ module Twitch
       response = get_request("predictions", params: params.merge(broadcaster_id: broadcaster_id))
 
       if response.body["data"]
-        Collection.from_response(response, type: Prediction)
+        collection(response, type: Prediction)
       else
         nil
       end

data/lib/twitch/resources/raids.rb

@@ -2,9 +2,8 @@ module Twitch
   class RaidsResource < Resource
     # from_broadcaster_id must match the user in the OAuth token
     def create(from_broadcaster_id:, to_broadcaster_id:)
-      attrs = { from_broadcaster_id: from_broadcaster_id, to_broadcaster_id: to_broadcaster_id }
-
-      response = post_request("raids", body: attrs)
+      path = query_path("raids", from_broadcaster_id: from_broadcaster_id, to_broadcaster_id: to_broadcaster_id)
+      response = post_request(path, body: {})
 
       Raid.new(response.body.dig("data")[0]) if response.success?
     end

data/lib/twitch/resources/search.rb

@@ -3,13 +3,13 @@ module Twitch
     def categories(query:, **params)
       response = get_request("search/categories", params: params.merge(query: query))
 
-      Collection.from_response(response, type: SearchResult)
+      collection(response, type: SearchResult)
     end
 
     def channels(query:, **params)
       response = get_request("search/channels", params: params.merge(query: query))
 
-      Collection.from_response(response, type: SearchResult)
+      collection(response, type: SearchResult)
     end
   end
 end

data/lib/twitch/resources/shield_mode.rb

@@ -0,0 +1,18 @@
+module Twitch
+  class ShieldModeResource < Resource
+    # Required scope: moderator:read:shield_mode or moderator:manage:shield_mode
+    # moderator_id must match the user in the OAuth token
+    def retrieve(broadcaster_id:, moderator_id:)
+      response = get_request("moderation/shield_mode", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id })
+      ShieldModeStatus.new(response.body.dig("data")[0])
+    end
+
+    # Required scope: moderator:manage:shield_mode
+    # moderator_id must match the user in the OAuth token
+    def update(broadcaster_id:, moderator_id:, is_active:)
+      path = query_path("moderation/shield_mode", broadcaster_id: broadcaster_id, moderator_id: moderator_id)
+      response = put_request(path, body: { is_active: is_active })
+      ShieldModeStatus.new(response.body.dig("data")[0])
+    end
+  end
+end

data/lib/twitch/resources/shoutouts.rb

@@ -5,7 +5,7 @@ module Twitch
     # To: the ID of the Broadcaster the Shoutout will be for
     # Required scope: moderator:manage:shoutouts
     def create(from:, to:, moderator_id:)
-      post_request("chat/shoutouts?#{URI.encode_www_form(from_broadcaster_id: from, to_broadcaster_id: to, moderator_id: moderator_id)}", body: nil)
+      post_request(query_path("chat/shoutouts", from_broadcaster_id: from, to_broadcaster_id: to, moderator_id: moderator_id), body: nil)
     end
   end
 end

data/lib/twitch/resources/stream_markers.rb

@@ -4,7 +4,7 @@ module Twitch
     def list(**params)
       response = get_request("streams/markers", params: params)
 
-      Collection.from_response(response, type: StreamMarker)
+      collection(response, type: StreamMarker)
     end
 
     # Required scope: channel:manage:broadcast

data/lib/twitch/resources/stream_schedule.rb

@@ -17,21 +17,20 @@ module Twitch
     # Broadcaster ID must match the user in the OAuth token
     # TODO: Allow the user to put any date format and then convert it to RFC3339
     def update(broadcaster_id:, **params)
-      patch_request("schedule/settings", body: params.merge(broadcaster_id: broadcaster_id))
+      patch_request(query_path("schedule/settings", params.merge(broadcaster_id: broadcaster_id)), body: {})
     end
 
     # Broadcaster ID must match the user in the OAuth token
     def create_segment(broadcaster_id:, start_time:, timezone:, duration:, is_recurring:, **params)
-      attrs = { broadcaster_id: broadcaster_id, start_time: start_time, duration: duration, timezone: timezone, is_recurring: is_recurring }
-      response = post_request("schedule/segment", body: attrs.merge(params))
+      attrs = { start_time: start_time, duration: duration, timezone: timezone, is_recurring: is_recurring }
+      response = post_request(query_path("schedule/segment", broadcaster_id: broadcaster_id), body: attrs.merge(params))
 
       StreamSchedule.new(response.body) if response.success?
     end
 
     # Broadcaster ID must match the user in the OAuth token
     def update_segment(broadcaster_id:, id:, **params)
-      attrs = { broadcaster_id: broadcaster_id, id: id }
-      response = patch_request("schedule/segment", body: attrs.merge(params))
+      response = patch_request(query_path("schedule/segment", broadcaster_id: broadcaster_id, id: id), body: params)
 
       StreamSchedule.new(response.body) if response.success?
     end

data/lib/twitch/resources/streams.rb

@@ -3,7 +3,7 @@ module Twitch
     def list(**params)
       response = get_request("streams", params: params)
 
-      Collection.from_response(response, type: Stream)
+      collection(response, type: Stream)
     end
 
     # Required scope: user:read:follows
@@ -11,7 +11,7 @@ module Twitch
     def followed(user_id:, **params)
       response = get_request("streams/followed", params: params.merge(user_id: user_id))
 
-      Collection.from_response(response, type: Stream)
+      collection(response, type: Stream)
     end
   end
 end

data/lib/twitch/resources/subscriptions.rb

@@ -5,7 +5,7 @@ module Twitch
     # Required scope: channel:read:subscriptions
     def list(broadcaster_id:, **params)
       response = get_request("subscriptions", params: params.merge(broadcaster_id: broadcaster_id))
-      Collection.from_response(response, type: Subscription)
+      collection(response, type: Subscription)
     end
 
     # Checks if a User is subscribed to a Broadcaster
@@ -15,7 +15,18 @@ module Twitch
     def is_subscribed(broadcaster_id:, user_id:, **params)
       attrs = { broadcaster_id: broadcaster_id, user_id: user_id }
       response = get_request("subscriptions/user", params: attrs.merge(params))
-      Collection.from_response(response, type: Subscription)
+      collection(response, type: Subscription)
+    end
+
+    # Returns true if the user subscribes to the broadcaster, false if not
+    # User ID must match the user in the OAuth token
+    # Required scope: user:read:subscriptions
+    def subscribed?(broadcaster_id:, user_id:)
+      get_request("subscriptions/user", params: { broadcaster_id: broadcaster_id, user_id: user_id })
+      true
+    rescue Errors::EntityNotFoundError
+      # Twitch responds with 404 when the user doesn't subscribe
+      false
     end
 
     # Grabs the number of Subscribers and Subscriber Points a broadcaster has

data/lib/twitch/resources/suspicious_users.rb

@@ -5,7 +5,7 @@ module Twitch
     def create(broadcaster_id:, moderator_id:, user_id:, status:)
       attrs = { user_id: user_id, status: status }
       response = post_request(
-        "moderation/suspicious_users?#{URI.encode_www_form(broadcaster_id: broadcaster_id, moderator_id: moderator_id)}",
+        query_path("moderation/suspicious_users", broadcaster_id: broadcaster_id, moderator_id: moderator_id),
         body: attrs
       )
 

data/lib/twitch/resources/teams.rb

@@ -0,0 +1,20 @@
+module Twitch
+  class TeamsResource < Resource
+    def retrieve(id: nil, name: nil)
+      raise ArgumentError, "Either id or name is required" if id.nil? && name.nil?
+
+      response = get_request("teams", params: { id: id, name: name }.compact)
+      data = response.body.dig("data")
+
+      return nil if data.nil? || data.empty?
+
+      Team.new(data[0])
+    end
+
+    # Gets the teams that a broadcaster is a member of
+    def channel(broadcaster_id:)
+      response = get_request("teams/channel", params: { broadcaster_id: broadcaster_id })
+      collection(response, type: Team)
+    end
+  end
+end

data/lib/twitch/resources/unban_requests.rb

@@ -3,12 +3,12 @@ module Twitch
     def list(broadcaster_id:, moderator_id:, status:, **params)
       attrs = { broadcaster_id: broadcaster_id, moderator_id: moderator_id, status: status }
       response = get_request("moderation/unban_requests", params: attrs.merge(params))
-      Collection.from_response(response, type: UnbanRequest)
+      collection(response, type: UnbanRequest)
     end
 
     def resolve(broadcaster_id:, moderator_id:, id:, status:, **params)
       attrs = { broadcaster_id: broadcaster_id, moderator_id: moderator_id, unban_request_id: id, status: status }
-      response = patch_request("moderation/unban_requests", body: attrs.merge(params))
+      response = patch_request(query_path("moderation/unban_requests", attrs.merge(params)), body: {})
       UnbanRequest.new(response.body.dig("data")[0])
     end
   end

data/lib/twitch/resources/users.rb

@@ -1,7 +1,7 @@
 module Twitch
   class UsersResource < Resource
     def retrieve(id: nil, ids: nil, username: nil, usernames: nil)
-      raise "Either id, ids, username or usernames is required" unless !id.nil? || !ids.nil? || !username.nil? || !usernames.nil?
+      raise ArgumentError, "Either id, ids, username or usernames is required" unless !id.nil? || !ids.nil? || !username.nil? || !usernames.nil?
 
       if id
         response = get_request("users", params: { id: id })
@@ -17,23 +17,22 @@ module Twitch
       if id || username
         body.empty? ? nil : User.new(body[0])
       else
-        Collection.from_response(response, type: User)
+        collection(response, type: User)
       end
     end
 
     # Updates the current users description
     # Required scope: user:edit
     def update(description:)
-      response = put_request("users", body: { description: description })
+      response = put_request(query_path("users", description: description), body: {})
       User.new response.body.dig("data")[0]
     end
 
     def get_color(user_id: nil, user_ids: nil)
       if user_ids
         ids = user_ids.is_a?(Array) ? user_ids : user_ids.split(",")
-        query = URI.encode_www_form(ids.map { |i| [ "user_id", i.to_s.strip ] })
-        response = get_request("chat/color?#{query}")
-        Collection.from_response(response, type: UserColor)
+        response = get_request("chat/color", params: { user_id: ids.map { |i| i.to_s.strip } })
+        collection(response, type: UserColor)
       else
         response = get_request("chat/color", params: { user_id: user_id })
         UserColor.new response.body.dig("data")[0]
@@ -44,28 +43,18 @@ module Twitch
     # Required scope: user:manage:chat_color
     # user_id must be the currently authenticated user
     def update_color(user_id:, color:)
-      put_request("chat/color?#{URI.encode_www_form(user_id: user_id, color: color)}", body: {})
-    end
-
-    # Deprecated.
-    def follows(**params)
-      warn "`users.follows` is deprecated. Use `channels.followers` or `channels.following` instead."
-
-      raise "from_id or to_id is required" unless !params[:from_id].nil? || !params[:to_id].nil?
-
-      response = get_request("users/follows", params: params)
-      Collection.from_response(response, type: FollowedUser)
+      put_request(query_path("chat/color", user_id: user_id, color: color), body: {})
     end
 
     # Required scope: user:read:blocked_users
     def blocks(broadcaster_id:, **params)
       response = get_request("users/blocks", params: params.merge(broadcaster_id: broadcaster_id))
-      Collection.from_response(response, type: BlockedUser)
+      collection(response, type: BlockedUser)
     end
 
     # Required scope: user:manage:blocked_users
     def block_user(target_user_id:, **attributes)
-      put_request("users/blocks?#{URI.encode_www_form(target_user_id: target_user_id)}", body: attributes)
+      put_request(query_path("users/blocks", attributes.merge(target_user_id: target_user_id)), body: {})
     end
 
     # Required scope: user:manage:blocked_users
@@ -73,27 +62,34 @@ module Twitch
       delete_request("users/blocks", params: { target_user_id: target_user_id })
     end
 
-    # A quick method to see if a user is following a channel
-    def following?(from_id:, to_id:)
-      warn "`users.following?` is deprecated. Use `channels.followers` or `channels.following` instead."
+    def emotes(user_id:, **params)
+      attrs = { user_id: user_id }
+      response = get_request("chat/emotes/user", params: attrs.merge(params))
+      collection(response, type: Emote)
+    end
 
-      response = get_request("users/follows", params: { from_id: from_id, to_id: to_id })
+    # Gets all extensions the authenticated user has installed, active or not
+    # Required scope: user:read:broadcast or user:edit:broadcast (needed to include inactive extensions)
+    def extensions
+      response = get_request("users/extensions/list")
+      collection(response, type: UserExtension)
+    end
 
-      if response.body["data"].empty?
-        false
-      else
-        true
-      end
+    # Gets the active extensions installed for a user, or the authenticated user if user_id is omitted
+    def active_extensions(user_id: nil)
+      response = get_request("users/extensions", params: { user_id: user_id }.compact)
+      UserActiveExtensions.new(response.body.dig("data"))
     end
 
-    def emotes(user_id:, **params)
-      attrs = { user_id: user_id }
-      response = get_request("chat/emotes/user", params: attrs.merge(params))
-      Collection.from_response(response, type: Emote)
+    # Required scope: user:edit:broadcast
+    # data: { panel: { "1" => { active: true, id: "abc", version: "1.0.0" } }, overlay: {...}, component: {...} }
+    def update_extensions(data:)
+      response = put_request("users/extensions", body: { data: data })
+      UserActiveExtensions.new(response.body.dig("data"))
     end
 
     def authorization(id: nil, ids: nil)
-      raise "Either id or ids is required" unless !id.nil? || !ids.nil?
+      raise ArgumentError, "Either id or ids is required" unless !id.nil? || !ids.nil?
 
       if id
         response = get_request("authorization/users", params: { user_id: id })
@@ -101,7 +97,7 @@ module Twitch
         response = get_request("authorization/users", params: { user_id: ids })
       end
 
-      Collection.from_response(response, type: UserAuthorization)
+      collection(response, type: UserAuthorization)
     end
   end
 end

data/lib/twitch/resources/videos.rb

@@ -1,10 +1,10 @@
 module Twitch
   class VideosResource < Resource
     def list(**params)
-      raise "user_id or game_id is required" unless !params[:user_id].nil? || !params[:game_id].nil?
+      raise ArgumentError, "user_id, game_id or id is required" if params.values_at(:user_id, :game_id, :id).all?(&:nil?)
 
       response = get_request("videos", params: params)
-      Collection.from_response(response, type: Video)
+      collection(response, type: Video)
     end
 
     def retrieve(id:)

data/lib/twitch/resources/vips.rb

@@ -3,11 +3,11 @@ module Twitch
     # Broadcaster ID must match the user in the OAuth token
     def list(broadcaster_id:, **params)
       response = get_request("channels/vips", params: params.merge(broadcaster_id: broadcaster_id))
-      Collection.from_response(response, type: Vip)
+      collection(response, type: Vip)
     end
 
     def create(broadcaster_id:, user_id:)
-      post_request("channels/vips", body: { broadcaster_id: broadcaster_id, user_id: user_id })
+      post_request(query_path("channels/vips", broadcaster_id: broadcaster_id, user_id: user_id), body: {})
     end
 
     def delete(broadcaster_id:, user_id:)

data/lib/twitch/resources/warnings.rb

@@ -5,8 +5,8 @@ module Twitch
     def create(broadcaster_id:, moderator_id:, user_id:, reason:)
       attrs = { user_id: user_id, reason: reason }
 
-      response = post_request("moderation/warnings?#{URI.encode_www_form(broadcaster_id: broadcaster_id, moderator_id: moderator_id)}", body: { data: attrs })
-      Collection.from_response(response, type: Warning)
+      response = post_request(query_path("moderation/warnings", broadcaster_id: broadcaster_id, moderator_id: moderator_id), body: { data: attrs })
+      collection(response, type: Warning)
     end
   end
 end

data/lib/twitch/resources/whispers.rb

@@ -1,7 +1,7 @@
 module Twitch
   class WhispersResource < Resource
     def create(from_user_id:, to_user_id:, message:)
-      post_request("whispers", body: { from_user_id: from_user_id, to_user_id: to_user_id, message: message })
+      post_request(query_path("whispers", from_user_id: from_user_id, to_user_id: to_user_id), body: { message: message })
     end
   end
 end

data/lib/twitch/version.rb

@@ -1,3 +1,3 @@
 module Twitch
-  VERSION = "1.11.0"
+  VERSION = "2.0.0"
 end