twitchrb 1.9.0 → 1.10.0

data/README.md

@@ -26,6 +26,28 @@ An access token is required because the Helix API requires authentication.
 @client = Twitch::Client.new(client_id: "abc123", access_token: "xyz123")
 ```
 
+#### User vs. App Access Tokens
+
+Most endpoints accept a **user access token** — issued for a specific Twitch user via the
+[authorization code](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#authorization-code-grant-flow)
+or [device code](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#device-code-grant-flow) flows,
+and required for anything that acts on behalf of a user (sending chat, managing channels, etc.).
+
+Some endpoints require an **app access token** instead — issued to your application, not a user. These
+are the EventSub APIs (subscriptions over webhooks, conduits, and shards), plus a few others noted in
+each section below. App tokens are obtained with the `client_credentials` grant and need only your
+Client ID and Client Secret:
+
+```ruby
+oauth = Twitch::OAuth.new(client_id: "abc123", client_secret: "your-client-secret")
+token = oauth.create(grant_type: "client_credentials")
+
+@app_client = Twitch::Client.new(client_id: "abc123", access_token: token.access_token)
+```
+
+App tokens expire (typically after ~60 days). Use `oauth.validate(token: ...)` to check the remaining
+lifetime, and `oauth.create(grant_type: "client_credentials")` to mint a fresh one when needed.
+
 ### Resources
 
 The gem maps as closely as we can to the Twitch API so you can easily convert API examples to gem code.
@@ -296,7 +318,7 @@ attributes = {title: "My new title"}
 ```ruby
 # Retrieves a list of clips
 # Available parameters: broadcaster_id or game_id
-@client.clips.list(user_id: 12345)
+@client.clips.list(broadcaster_id: 12345)
 @client.clips.list(game_id: 12345)
 
 # Retrieves a clip by its ID.
@@ -305,7 +327,26 @@ attributes = {title: "My new title"}
 
 # Create a clip of a given Channel
 # Required scope: clips:edit
-@client.clips.create(broadcaster_id: 1234)
+# title is optional
+# duration is optional and can be from 5 to 60 seconds; defaults to 30 if not set
+@client.clips.create(broadcaster_id: 1234, title: "Best moment", duration: 12.5)
+
+# Create a clip from a VOD
+# Required scope: editor:manage:clips or channel:manage:clips
+# title is optional
+# duration is optional and can be from 5 to 60 seconds; defaults to 30 if not set
+@client.clips.create_from_vod(
+  editor_id: 1234,
+  broadcaster_id: 1234,
+  vod_id: 5678,
+  vod_offset: 45,
+  duration: 15.0,
+  title: "VOD highlight"
+)
+
+# Get download URLs for one or more clips
+# Required scope: editor:manage:clips or channel:manage:clips
+@client.clips.downloads(editor_id: 1234, broadcaster_id: 1234, clip_ids: ["clip-1", "clip-2"])
 ```
 
 ### Emotes
@@ -355,10 +396,11 @@ These require an application OAuth access token.
 
 ```ruby
 # Retrieves a list of EventSub Subscriptions
-# Available parameters: status, type, after
+# Available parameters: status, type, user_id, after, conduit_id, subscription_id
 @client.eventsub_subscriptions.list
 @client.eventsub_subscriptions.list(status: "enabled")
 @client.eventsub_subscriptions.list(type: "channel.follow")
+@client.eventsub_subscriptions.list(conduit_id: "conduit-id")
 
 # Create an EventSub Subscription
 @client.eventsub_subscriptions.create(
@@ -368,11 +410,45 @@ These require an application OAuth access token.
   transport: {method: "webhook", callback: "webhook_url", secret: "secret"}
 )
 
+# If Twitch returns a 409 conflict for an already-existing subscription,
+# the raised error exposes the existing subscription ID
+begin
+  @client.eventsub_subscriptions.create(
+    type: "channel.follow",
+    version: 1,
+    condition: {broadcaster_user_id: 123},
+    transport: {method: "webhook", callback: "webhook_url", secret: "secret"}
+  )
+rescue Twitch::Errors::EventsubSubscriptionConflictError => e
+  e.existing_subscription_id
+end
+
+# The generic EventSub API also supports beta subscription types such as
+# channel.custom_power_up_redemption.add with version "beta"
+@client.eventsub_subscriptions.create(
+  type: "channel.custom_power_up_redemption.add",
+  version: "beta",
+  condition: {broadcaster_user_id: 123},
+  transport: {method: "webhook", callback: "webhook_url", secret: "secret"}
+)
+
 # Delete an EventSub Subscription
 # IDs are UUIDs
 @client.eventsub_subscriptions.delete(id: "abc12-abc12-abc12")
 ```
 
+### Custom Power-ups
+
+```ruby
+# Get all custom Power-ups for a broadcaster
+# Required scope: bits:read
+# broadcaster_id must match the currently authenticated user
+@client.custom_power_ups.list(broadcaster_id: 123)
+
+# Filter custom Power-ups by ID
+@client.custom_power_ups.list(broadcaster_id: 123, ids: ["power-up-1", "power-up-2"])
+```
+
 ### EventSub Conduits
 
 Conduits provide a way to receive events over multiple transports. These require an application OAuth access token.
@@ -449,6 +525,10 @@ shards = [
 # moderator_id can be either the currently authenticated moderator or the broadcaster
 # color can be either blue, green, orange, purple, primary. If left blank, primary is default
 @client.announcements.create broadcaster_id: 123, moderator_id: 123, message: "test message", color: "purple"
+
+# When using an App Access Token during a shared chat session, set for_source_only: false
+# to send the announcement to all channels in the session instead of only the source channel
+@client.announcements.create broadcaster_id: 123, moderator_id: 123, message: "shared announcement", for_source_only: false
 ```
 
 ### Create a Shoutout
@@ -539,12 +619,40 @@ shards = [
 # reply_to is optional and is the UUID of the message to reply to
 @client.chat_messages.create broadcaster_id: 123, sender_id: 321, message: "A test message", reply_to: "aabbcc"
 
+# When using an App Access Token during a shared chat session, control whether the message
+# is only sent to the source channel or shared to all channels in the session
+@client.chat_messages.create broadcaster_id: 123, sender_id: 321, message: "Shared chat message", for_source_only: false
+
+# Optionally pin the message immediately after sending it
+# Requires moderator:manage:chat_messages and the sender must be the broadcaster or a moderator
+@client.chat_messages.create broadcaster_id: 123, sender_id: 321, message: "Read the rules", pin: true
+
 # Removes a single chat message from the broadcaster's chat room
 # Requires moderator:manage:chat_messages
 # moderator_id can be either the currently authenticated moderator or the broadcaster
 @client.chat_messages.delete broadcaster_id: 123, moderator_id: 123, message_id: "abc123-abc123"
 ```
 
+### Pinned Chat Messages
+
+```ruby
+# Get the currently pinned chat message
+# Requires moderator:read:chat_messages or moderator:manage:chat_messages
+@client.pinned_chat_messages.retrieve broadcaster_id: 123, moderator_id: 321
+
+# Pin a message
+# Requires moderator:manage:chat_messages
+@client.pinned_chat_messages.create broadcaster_id: 123, moderator_id: 321, message_id: "abc123-abc123", duration_seconds: 300
+
+# Update a pinned message's duration
+# Requires moderator:manage:chat_messages
+@client.pinned_chat_messages.update broadcaster_id: 123, moderator_id: 321, message_id: "abc123-abc123", duration_seconds: 120
+
+# Unpin a message
+# Requires moderator:manage:chat_messages
+@client.pinned_chat_messages.delete broadcaster_id: 123, moderator_id: 321, message_id: "abc123-abc123"
+```
+
 ### Whispers
 
 ```ruby
@@ -638,6 +746,13 @@ messages = [{msg_id: "abc1", msg_text: "is this allowed?"}, {msg_id: "abc2", msg
 @client.chatters.list broadcaster_id: 123, moderator_id: 123
 ```
 
+### Shared Chat Sessions
+
+```ruby
+# Get the active shared chat session for a broadcaster
+@client.shared_chat_sessions.retrieve broadcaster_id: 123
+```
+
 ### Channel Points Custom Rewards
 
 ```ruby
@@ -700,6 +815,20 @@ messages = [{msg_id: "abc1", msg_text: "is this allowed?"}, {msg_id: "abc2", msg
 @client.warnings.create broadcaster_id: 123, moderator_id: 123, user_id: 321, reason: "dont do that"
 ```
 
+### Suspicious Users
+
+```ruby
+# Add suspicious status to a chat user
+# Required scope: moderator:manage:suspicious_users
+# moderator_id must match the currently authenticated moderator
+@client.suspicious_users.create broadcaster_id: 123, moderator_id: 321, user_id: 456, status: "RESTRICTED"
+
+# Remove suspicious status from a chat user
+# Required scope: moderator:manage:suspicious_users
+# moderator_id must match the currently authenticated moderator
+@client.suspicious_users.delete broadcaster_id: 123, moderator_id: 321, user_id: 456
+```
+
 ### Streams
 
 ```ruby
@@ -856,13 +985,13 @@ tag_ids = ["tag-id-1", "tag-id-2"]
 @client.tags.replace(broadcaster_id: 123, tag_ids: tag_ids)
 ```
 
-### Hype Train Events
+### Hype Train Status
 
 ```ruby
-# Get hype train events for a broadcaster
+# Get hype train status for a broadcaster
 # Required scope: channel:read:hype_train
 # broadcaster_id must match the currently authenticated user
-@client.hype_train_events.list(broadcaster_id: 123)
+@client.hype_train_status.retrieve(broadcaster_id: 123)
 ```
 
 ### Moderator Events

data/bin/smoke

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# Hits the real Twitch API to verify the gem still matches what Twitch returns.
+# Run before releases, or on a schedule. Unit tests use WebMock and won't catch
+# Twitch-side schema drift; this will.
+#
+# Required env (load via .env):
+#   TWITCH_CLIENT_ID
+#   TWITCH_ACCESS_TOKEN          # user token
+#   TWITCH_CLIENT_SECRET         # only needed for app-token checks
+#
+# Optional env — enables write checks that actually send messages:
+#   TWITCH_SMOKE_BROADCASTER_ID  # channel to post into
+#   TWITCH_SMOKE_MODERATOR_ID    # must match the user/bot in the token
+#                                # (also used as sender_id for chat messages)
+#
+# Usage:
+#   bin/smoke               # run all checks
+#   bin/smoke users games   # run only the named checks
+
+require "bundler/setup"
+require "twitch"
+require "dotenv/load"
+
+unless ENV["TWITCH_CLIENT_ID"] && ENV["TWITCH_ACCESS_TOKEN"]
+  abort "Missing TWITCH_CLIENT_ID / TWITCH_ACCESS_TOKEN — set them in .env"
+end
+
+client = Twitch::Client.new(
+  client_id: ENV["TWITCH_CLIENT_ID"],
+  access_token: ENV["TWITCH_ACCESS_TOKEN"]
+)
+
+app_client = nil
+if ENV["TWITCH_CLIENT_SECRET"]
+  oauth = Twitch::OAuth.new(
+    client_id: ENV["TWITCH_CLIENT_ID"],
+    client_secret: ENV["TWITCH_CLIENT_SECRET"]
+  )
+  token = oauth.create(grant_type: "client_credentials")
+  app_client = Twitch::Client.new(client_id: ENV["TWITCH_CLIENT_ID"], access_token: token.access_token) if token
+end
+
+broadcaster_id = ENV["TWITCH_SMOKE_BROADCASTER_ID"]
+moderator_id   = ENV["TWITCH_SMOKE_MODERATOR_ID"]
+timestamp      = Time.now.strftime("%Y-%m-%d %H:%M:%S")
+
+CHECKS = {
+  "users"            => -> { client.users.retrieve(username: "twitchdev") },
+  "users_many"       => -> { client.users.retrieve(usernames: [ "twitchdev", "twitch" ]) },
+  "channels"         => -> { client.channels.retrieve(id: 141981764) },
+  "games"            => -> { client.games.retrieve(name: "Just Chatting") },
+  "games_top"        => -> { client.games.top(first: 5) },
+  "streams"          => -> { client.streams.list(first: 5) },
+  "clips"            => -> { client.clips.list(broadcaster_id: "141981764", first: 3) },
+  "videos"           => -> { client.videos.list(user_id: "141981764", first: 3) },
+  "badges_global"    => -> { client.badges.global },
+  "badges_channel"   => -> { client.badges.channel(broadcaster_id: "141981764") },
+  "emotes_global"    => -> { client.emotes.global },
+  "emotes_channel"   => -> { client.emotes.channel(broadcaster_id: "141981764") },
+  "eventsub_list"    => -> { client.eventsub_subscriptions.list },
+
+  # app-token only
+  "conduits_list"    => -> { app_client && app_client.eventsub_conduits.list },
+  "app_subs_list"    => -> { app_client && app_client.eventsub_subscriptions.list },
+
+  # write checks — only run when broadcaster + moderator ids are set
+  "chat_message"     => -> {
+    client.chat_messages.create(
+      broadcaster_id: broadcaster_id,
+      sender_id: moderator_id,
+      message: "twitchrb smoke test #{timestamp}"
+    )
+  },
+  "announcement"     => -> {
+    client.announcements.create(
+      broadcaster_id: broadcaster_id,
+      moderator_id: moderator_id,
+      message: "twitchrb smoke test announcement #{timestamp}",
+      color: "primary"
+    )
+  }
+}.freeze
+
+requested = ARGV.empty? ? CHECKS.keys : ARGV
+unknown = requested - CHECKS.keys
+abort "Unknown check(s): #{unknown.join(", ")}\nAvailable: #{CHECKS.keys.join(", ")}" if unknown.any?
+
+failures = 0
+write_checks = %w[chat_message announcement]
+
+requested.each do |name|
+  if name.start_with?("conduits", "app_subs") && app_client.nil?
+    puts "- #{name.ljust(18)} skipped (no TWITCH_CLIENT_SECRET)"
+    next
+  end
+
+  if write_checks.include?(name) && (broadcaster_id.nil? || moderator_id.nil?)
+    puts "- #{name.ljust(18)} skipped (set TWITCH_SMOKE_BROADCASTER_ID + TWITCH_SMOKE_MODERATOR_ID)"
+    next
+  end
+
+  begin
+    result = CHECKS[name].call
+    count = result.respond_to?(:data) ? result.data.size : 1
+    puts "✓ #{name.ljust(18)} (#{count} record#{"s" unless count == 1})"
+  rescue => e
+    failures += 1
+    puts "✗ #{name.ljust(18)} #{e.class}: #{e.message}"
+  end
+end
+
+puts
+if failures.zero?
+  puts "All checks passed."
+else
+  puts "#{failures} check(s) failed."
+  exit 1
+end

data/lib/twitch/client.rb

@@ -114,6 +114,10 @@ module Twitch
       CustomRewardRedemptionsResource.new(self)
     end
 
+    def custom_power_ups
+      CustomPowerUpsResource.new(self)
+    end
+
     def goals
       GoalsResource.new(self)
     end
@@ -122,6 +126,10 @@ module Twitch
       HypeTrainEventsResource.new(self)
     end
 
+    def hype_train_status
+      HypeTrainStatusResource.new(self)
+    end
+
     def announcements
       AnnouncementsResource.new(self)
     end
@@ -134,6 +142,10 @@ module Twitch
       ChatMessagesResource.new(self)
     end
 
+    def pinned_chat_messages
+      PinnedChatMessagesResource.new(self)
+    end
+
     def vips
       VipsResource.new(self)
     end
@@ -162,6 +174,10 @@ module Twitch
       ShoutoutsResource.new(self)
     end
 
+    def shared_chat_sessions
+      SharedChatSessionsResource.new(self)
+    end
+
     def unban_requests
       UnbanRequestsResource.new(self)
     end
@@ -170,6 +186,10 @@ module Twitch
       WarningsResource.new(self)
     end
 
+    def suspicious_users
+      SuspiciousUsersResource.new(self)
+    end
+
     def connection
       @connection ||= Faraday.new(BASE_URL) do |conn|
         conn.request :authorization, :Bearer, access_token

data/lib/twitch/error.rb

@@ -1,4 +1,7 @@
 module Twitch
   class Error < StandardError
   end
+
+  class UnsafeRequestPathError < ArgumentError
+  end
 end

data/lib/twitch/error_generator.rb

@@ -88,6 +88,15 @@ module Twitch
       end
     end
 
+    class EventsubSubscriptionConflictError < ConflictError
+      attr_reader :existing_subscription_id
+
+      def initialize(response_body, http_status_code, existing_subscription_id: nil)
+        @existing_subscription_id = existing_subscription_id
+        super(response_body, http_status_code)
+      end
+    end
+
     class TooManyRequestsError < ErrorGenerator
       private
 

data/lib/twitch/objects/clip_download.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ClipDownload < Object
+  end
+end

data/lib/twitch/objects/custom_power_up.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class CustomPowerUp < Object
+  end
+end

data/lib/twitch/objects/hype_train_status.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class HypeTrainStatus < Object
+  end
+end

data/lib/twitch/objects/pinned_chat_message.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class PinnedChatMessage < Object
+  end
+end

data/lib/twitch/objects/shared_chat_session.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class SharedChatSession < Object
+  end
+end

data/lib/twitch/objects/suspicious_user.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class SuspiciousUser < Object
+  end
+end

data/lib/twitch/resource.rb

@@ -9,22 +9,27 @@ module Twitch
     private
 
     def get_request(url, params: {}, headers: {})
+      validate_request_path!(url)
       handle_response client.connection.get(url, params, headers)
     end
 
     def post_request(url, body:, headers: {})
+      validate_request_path!(url)
       handle_response client.connection.post(url, body, headers)
     end
 
     def patch_request(url, body:, headers: {})
+      validate_request_path!(url)
       handle_response client.connection.patch(url, body, headers)
     end
 
     def put_request(url, body:, headers: {})
+      validate_request_path!(url)
       handle_response client.connection.put(url, body, headers)
     end
 
     def delete_request(url, params: {}, headers: {})
+      validate_request_path!(url)
       handle_response client.connection.delete(url, params, headers)
     end
 
@@ -71,5 +76,13 @@ module Twitch
       )
       raise error
     end
+
+    def validate_request_path!(url)
+      return unless url.start_with?("//") || URI(url).absolute?
+
+      raise Twitch::UnsafeRequestPathError, "request path must be relative to the Twitch API base URL"
+    rescue URI::InvalidURIError
+      nil
+    end
   end
 end

data/lib/twitch/resources/announcements.rb

@@ -2,8 +2,8 @@ module Twitch
   class AnnouncementsResource < Resource
     # Moderator ID must match the user in the OAuth token
     # Required scope: moderator:manage:announcements
-    def create(broadcaster_id:, moderator_id:, message:, color: nil)
-      attrs = { message: message, color: color }
+    def create(broadcaster_id:, moderator_id:, message:, color: nil, for_source_only: nil)
+      attrs = { message: message, color: color, for_source_only: for_source_only }
 
       post_request("chat/announcements?broadcaster_id=#{broadcaster_id}&moderator_id=#{moderator_id}", body: attrs)
     end

data/lib/twitch/resources/chat_messages.rb

@@ -1,7 +1,14 @@
 module Twitch
   class ChatMessagesResource < Resource
-    def create(broadcaster_id:, sender_id:, message:, reply_to: nil)
-      attrs = { broadcaster_id: broadcaster_id, sender_id: sender_id, message: message, reply_parent_message_id: reply_to }
+    def create(broadcaster_id:, sender_id:, message:, reply_to: nil, pin: nil, for_source_only: nil)
+      attrs = {
+        broadcaster_id: broadcaster_id,
+        sender_id: sender_id,
+        message: message,
+        reply_parent_message_id: reply_to,
+        pin: pin,
+        for_source_only: for_source_only
+      }.compact
 
       response = post_request("chat/messages", body: attrs)
       ChatMessage.new(response.body.dig("data")[0])

data/lib/twitch/resources/clips.rb

@@ -13,9 +13,37 @@ module Twitch
 
     # Required scope: clips:edit
     def create(broadcaster_id:, **attributes)
-      response = post_request("clips", body: attributes.merge(broadcaster_id: broadcaster_id))
+      response = post_request(query_path("clips", attributes.merge(broadcaster_id: broadcaster_id)), body: {})
 
       Clip.new(response.body.dig("data")[0]) if response.success?
     end
+
+    # Required scope: editor:manage:clips or channel:manage:clips
+    def create_from_vod(editor_id:, broadcaster_id:, vod_id:, vod_offset:, **attributes)
+      params = attributes.merge(
+        editor_id: editor_id,
+        broadcaster_id: broadcaster_id,
+        vod_id: vod_id,
+        vod_offset: vod_offset
+      )
+
+      response = post_request(query_path("videos/clips", params), body: {})
+
+      Clip.new(response.body.dig("data")[0]) if response.success?
+    end
+
+    # Required scope: editor:manage:clips or channel:manage:clips
+    def downloads(editor_id:, broadcaster_id:, clip_id: nil, clip_ids: nil)
+      ids = clip_ids || Array(clip_id)
+      response = get_request("clips/downloads", params: { editor_id: editor_id, broadcaster_id: broadcaster_id, clip_id: ids })
+
+      Collection.from_response(response, type: ClipDownload)
+    end
+
+    private
+
+    def query_path(path, params)
+      "#{path}?#{URI.encode_www_form(params)}"
+    end
   end
 end

data/lib/twitch/resources/custom_power_ups.rb

@@ -0,0 +1,13 @@
+module Twitch
+  class CustomPowerUpsResource < Resource
+    # Required scope: bits:read
+    # broadcaster_id must match the currently authenticated user
+    def list(broadcaster_id:, ids: nil)
+      params = { broadcaster_id: broadcaster_id }
+      params[:id] = ids if ids
+
+      response = get_request("bits/custom_power_ups", params: params)
+      Collection.from_response(response, type: CustomPowerUp)
+    end
+  end
+end

data/lib/twitch/resources/eventsub_subscriptions.rb

@@ -7,7 +7,18 @@ module Twitch
 
     def create(type:, version:, condition:, transport:, **params)
       attributes = { type: type, version: version, condition: condition, transport: transport }.merge(params)
-      response = post_request("eventsub/subscriptions", body: attributes)
+      response = client.connection.post("eventsub/subscriptions", attributes)
+      update_rate_limit(response)
+
+      if response.status == 409
+        raise Twitch::Errors::EventsubSubscriptionConflictError.new(
+          response.body,
+          response.status,
+          existing_subscription_id: response.body.dig("data", 0, "id")
+        )
+      end
+
+      return raise_error(response) if error?(response)
 
       EventsubSubscription.new(response.body.dig("data")[0]) if response.success?
     end

data/lib/twitch/resources/hype_train_events.rb

@@ -3,8 +3,8 @@ module Twitch
     # Required scope: channel:read:hype_train
     # Broadcaster ID must match the user in the OAuth token
     def list(broadcaster_id:)
-      response = get_request("hypetrain/events", params: { broadcaster_id: broadcaster_id })
-      Collection.from_response(response, type: HypeTrainEvent)
+      warn "`hype_train_events.list` is deprecated because Twitch removed GET /helix/hypetrain/events. Use `hype_train_status.retrieve` instead."
+      HypeTrainStatusResource.new(client).retrieve(broadcaster_id: broadcaster_id)
     end
   end
 end

data/lib/twitch/resources/hype_train_status.rb

@@ -0,0 +1,14 @@
+module Twitch
+  class HypeTrainStatusResource < Resource
+    # Required scope: channel:read:hype_train
+    # Broadcaster ID must match the user in the OAuth token
+    def retrieve(broadcaster_id:)
+      response = get_request("hypetrain/status", params: { broadcaster_id: broadcaster_id })
+      data = response.body.dig("data")
+
+      return nil if data.nil? || data.empty?
+
+      HypeTrainStatus.new(data[0])
+    end
+  end
+end

data/lib/twitch/resources/pinned_chat_messages.rb

@@ -0,0 +1,40 @@
+module Twitch
+  class PinnedChatMessagesResource < Resource
+    def retrieve(broadcaster_id:, moderator_id:)
+      response = get_request("chat/pins", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id })
+      data = response.body.dig("data")
+
+      return nil if data.nil? || data.empty?
+
+      PinnedChatMessage.new(data[0])
+    end
+
+    # 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: {})
+    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: {})
+    end
+
+    # moderator_id must match the user in the OAuth token
+    def delete(broadcaster_id:, moderator_id:, message_id:)
+      delete_request("chat/pins", params: { broadcaster_id: broadcaster_id, moderator_id: moderator_id, message_id: message_id })
+    end
+
+    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)}"
+    end
+  end
+end