twitchrb 1.10.0 → 2.0.0

data/lib/twitch/resources/extensions.rb

@@ -0,0 +1,99 @@
+module Twitch
+  # Most of these endpoints require a signed JWT created by your Extension Backend Service,
+  # rather than an OAuth token. Pass the JWT as the client's access_token.
+  # See https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt
+  class ExtensionsResource < Resource
+    # Requires a signed JWT
+    def retrieve(extension_id:, extension_version: nil)
+      response = get_request("extensions", params: { extension_id: extension_id, extension_version: extension_version }.compact)
+      data = response.body.dig("data")
+
+      return nil if data.nil? || data.empty?
+
+      Extension.new(data[0])
+    end
+
+    def released(extension_id:, extension_version: nil)
+      response = get_request("extensions/released", params: { extension_id: extension_id, extension_version: extension_version }.compact)
+      data = response.body.dig("data")
+
+      return nil if data.nil? || data.empty?
+
+      Extension.new(data[0])
+    end
+
+    # Available parameters: first, after
+    def live_channels(extension_id:, **params)
+      response = get_request("extensions/live", params: params.merge(extension_id: extension_id))
+      collection(response, type: ExtensionLiveChannel)
+    end
+
+    # Requires a signed JWT
+    # segment: broadcaster, developer or global. Pass an array to get more than one.
+    def configuration(extension_id:, segment:, broadcaster_id: nil)
+      params = { extension_id: extension_id, segment: segment, broadcaster_id: broadcaster_id }.compact
+      response = get_request("extensions/configurations", params: params)
+      collection(response, type: ExtensionConfigurationSegment)
+    end
+
+    # Requires a signed JWT
+    # Available attributes: broadcaster_id, content, version
+    def set_configuration(extension_id:, segment:, **attributes)
+      put_request("extensions/configurations", body: attributes.merge(extension_id: extension_id, segment: segment))
+    end
+
+    # Requires a signed JWT
+    def set_required_configuration(broadcaster_id:, extension_id:, extension_version:, required_configuration:)
+      attrs = { extension_id: extension_id, extension_version: extension_version, required_configuration: required_configuration }
+      put_request(query_path("extensions/required_configuration", broadcaster_id: broadcaster_id), body: attrs)
+    end
+
+    # Requires a signed JWT
+    # target: an array containing broadcast, global, or whisper-<user-id>
+    def send_pubsub_message(broadcaster_id:, target:, message:, is_global_broadcast: nil)
+      attrs = { broadcaster_id: broadcaster_id, target: Array(target), message: message, is_global_broadcast: is_global_broadcast }.compact
+      post_request("extensions/pubsub", body: attrs)
+    end
+
+    # Requires a signed JWT
+    def send_chat_message(broadcaster_id:, text:, extension_id:, extension_version:)
+      attrs = { text: text, extension_id: extension_id, extension_version: extension_version }
+      post_request(query_path("extensions/chat", broadcaster_id: broadcaster_id), body: attrs)
+    end
+
+    # Requires a signed JWT
+    def secrets(extension_id:)
+      response = get_request("extensions/jwt/secrets", params: { extension_id: extension_id })
+      collection(response, type: ExtensionSecret)
+    end
+
+    # Requires a signed JWT
+    # delay: seconds before the new secret becomes active (minimum 300)
+    def create_secret(extension_id:, delay: nil)
+      response = post_request(query_path("extensions/jwt/secrets", extension_id: extension_id, delay: delay), body: {})
+      collection(response, type: ExtensionSecret)
+    end
+
+    # Requires an app access token whose Client ID matches the extension's
+    def bits_products(should_include_all: nil)
+      response = get_request("bits/extensions", params: { should_include_all: should_include_all }.compact)
+      collection(response, type: ExtensionBitsProduct)
+    end
+
+    # Requires an app access token whose Client ID matches the extension's
+    # cost: { amount: 100, type: "bits" }
+    # Available attributes: in_development, expiration, is_broadcast
+    def update_bits_product(sku:, cost:, display_name:, **attributes)
+      attrs = attributes.merge(sku: sku, cost: cost, display_name: display_name)
+      response = put_request("bits/extensions", body: attrs)
+      ExtensionBitsProduct.new(response.body.dig("data")[0])
+    end
+
+    # Requires an app access token
+    # Available parameters: id, first, after
+    def transactions(extension_id:, **params)
+      response = get_request("extensions/transactions", params: params.merge(extension_id: extension_id))
+      collection(response, type: ExtensionTransaction)
+    end
+  end
+end

data/lib/twitch/resources/games.rb

@@ -1,7 +1,7 @@
 module Twitch
   class GamesResource < Resource
     def retrieve(id: nil, ids: nil, name: nil, names: nil)
-      raise "Either id, ids, name or names is required" unless !id.nil? || !ids.nil? || !name.nil? || !names.nil?
+      raise ArgumentError, "Either id, ids, name or names is required" unless !id.nil? || !ids.nil? || !name.nil? || !names.nil?
 
       if id
         response = get_request("games", params: { id: id })
@@ -14,18 +14,16 @@ module Twitch
       end
 
       body = response.body.dig("data")
-      if id || name && body.count == 1
-        Game.new body[0]
-      elsif ids || names && body.count > 1
-        Collection.from_response(response, type: Game)
+      if id || name
+        body.empty? ? nil : Game.new(body[0])
       else
-        nil
+        collection(response, type: Game)
       end
     end
 
     def top(**params)
       response = get_request("games/top", params: params)
-      Collection.from_response(response, type: Game)
+      collection(response, type: Game)
     end
   end
 end

data/lib/twitch/resources/goals.rb

@@ -4,7 +4,7 @@ module Twitch
     # Broadcaster ID must match the user in the OAuth token
     def list(broadcaster_id:)
       response = get_request("goals", params: { broadcaster_id: broadcaster_id })
-      Collection.from_response(response, type: Goal)
+      collection(response, type: Goal)
     end
   end
 end

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,21 +3,21 @@ 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:)
-      delete_request("moderation/moderators?broadcaster_id=#{broadcaster_id}&user_id=#{user_id}")
+      delete_request("moderation/moderators", params: { broadcaster_id: broadcaster_id, user_id: user_id })
     end
   end
 end

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,16 +2,15 @@ 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
 
     # broadcaster_id must match the user in the OAuth token
     def delete(broadcaster_id:)
-      delete_request("raids?broadcaster_id=#{broadcaster_id}")
+      delete_request("raids", params: { broadcaster_id: broadcaster_id })
     end
   end
 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?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?broadcaster_id=#{broadcaster_id}&moderator_id=#{moderator_id}",
+        query_path("moderation/suspicious_users", broadcaster_id: broadcaster_id, moderator_id: moderator_id),
         body: attrs
       )
 
@@ -16,9 +16,13 @@ module Twitch
     # moderator_id must match the currently authenticated moderator
     def delete(broadcaster_id:, moderator_id:, user_id:)
       response = delete_request(
-        "moderation/suspicious_users?broadcaster_id=#{broadcaster_id}&moderator_id=#{moderator_id}&user_id=#{user_id}"
+        "moderation/suspicious_users",
+        params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id, user_id: user_id }
       )
 
+      # delete_request returns true for 204 No Content responses
+      return true unless response.respond_to?(:body)
+
       SuspiciousUser.new(response.body.dig("data")[0])
     end
   end

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