twitchrb 1.11.0 → 2.1.0

data/README.md

@@ -1,6 +1,6 @@
 # TwitchRB
 
-[![CI](https://github.com/deanpcmad/twitchrb/actions/workflows/ci.yml/badge.svg)](https://github.com/deanpcmad/twitchrb/actions/workflows/ci.yml)
+[![CI](https://github.com/d34ndev/twitchrb/actions/workflows/ci.yml/badge.svg)](https://github.com/d34ndev/twitchrb/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/twitchrb.svg)](https://badge.fury.io/rb/twitchrb)
 [![Downloads](https://img.shields.io/gem/dt/twitchrb.svg)](https://rubygems.org/gems/twitchrb)
 
@@ -14,6 +14,8 @@ Add this line to your application's Gemfile:
 gem "twitchrb"
 ```
 
+Upgrading from 1.x? Version 2.0 has breaking changes. See [Upgrading from 1.x](CHANGELOG.md#upgrading-from-1x) in the changelog.
+
 ## Usage
 
 ### Set Client Details
@@ -26,17 +28,46 @@ An access token is required because the Helix API requires authentication.
 @client = Twitch::Client.new(client_id: "abc123", access_token: "xyz123")
 ```
 
+Requests time out after 30 seconds (10 seconds to open the connection) by default, raising
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed`. Both can be changed on `Twitch::Client` and `Twitch::OAuth`:
+
+```ruby
+@client = Twitch::Client.new(client_id: "abc123", access_token: "xyz123", timeout: 10, open_timeout: 5)
+```
+
+#### Refreshing User Access Tokens
+
+User access tokens expire after a few hours. Pass the `refresh_token` and your `client_secret` and the client
+will refresh an expired token automatically, then retry the request. Twitch may issue a new refresh token each
+time, so use `on_token_refresh` to store the new tokens:
+
+```ruby
+@client = Twitch::Client.new(
+  client_id: "abc123",
+  client_secret: "your-client-secret", # omit for public clients
+  access_token: user.twitch_access_token,
+  refresh_token: user.twitch_refresh_token,
+  on_token_refresh: ->(token) {
+    user.update!(twitch_access_token: token.access_token, twitch_refresh_token: token.refresh_token)
+  }
+)
+
+# Or refresh manually
+@client.refresh_access_token!
+```
+
+The client refreshes once per expired token, even across threads. If the refresh token itself is invalid (e.g.
+the user disconnected your app), the error from Twitch is raised, e.g. `Twitch::Errors::BadRequestError`.
+
 #### 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.).
+and required for anything that acts on behalf of a user (managing channels, polls, rewards, 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:
+An **app access token** is issued to your application, not a user. 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")
@@ -48,12 +79,43 @@ token = oauth.create(grant_type: "client_credentials")
 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.
 
+**These require an app access token:**
+
+- EventSub over webhooks or conduits: `eventsub_subscriptions` and `eventsub_conduits` (including shards).
+  EventSub over WebSockets requires a user access token instead.
+- `users.authorization`
+- `extensions.transactions`, and `extensions.bits_products`/`update_bits_product` (the token's Client ID must be the extension's)
+
+**These also accept an app access token**, as long as the user in the request (e.g. `sender_id` or
+`moderator_id`) has previously authorized your app with the required scope through one of the user token flows.
+This is how chatbots can act without storing each user's token. Chat endpoints need the bot account to have
+granted `user:bot`, and the broadcaster to have granted `channel:bot` or made the bot a moderator — see
+[Chatbots](https://dev.twitch.tv/docs/chat/authenticating/) for details.
+
+- Chat: `chat_messages.create`, `chat_messages.delete`, `announcements.create`, `shoutouts.create`,
+  `pinned_chat_messages` (all methods), `chatters.list`, `chat_settings.update`
+- Moderation: `automod` (all methods), `banned_users` (all methods), `blocked_terms` (all methods),
+  `moderators.channels`, `shield_mode` (all methods), `warnings.create`, `suspicious_users` (all methods)
+- Ads: `channels.commercial`, `ads.schedule`, `ads.snooze`
+
 ### Resources
 
 The gem maps as closely as we can to the Twitch API so you can easily convert API examples to gem code.
 
 Responses are created as objects like `Twitch::Channel`. Having types like `Twitch::User` is handy for understanding what
-type of object you're working with. They're built using OpenStruct so you can easily access data in a Ruby-ish way.
+type of object you're working with. Attributes can be read with dot notation or like a hash, and nested data is wrapped too:
+
+```ruby
+user = @client.users.retrieve(username: "twitchdev")
+
+user.display_name                   #=> "TwitchDev"
+user[:display_name]                 #=> "TwitchDev"
+user.missing_attribute              #=> nil
+
+# Convert back to a hash or JSON, including nested data
+user.to_h
+user.to_json
+```
 
 ### Pagination
 
@@ -85,11 +147,38 @@ results.last
 results.cursor
 #=> "abc123"
 
-# Retrieve the next page
+# Retrieve the next page manually
 @client.clips.list(broadcaster_id: 123, after: results.cursor)
 #=> Twitch::Collection
 ```
 
+#### Automatic Pagination
+
+Collections from paginated endpoints can fetch their following pages for you. Each extra page is a separate
+API request (and counts towards your rate limit), so use `first:` to request up to 100 items per page.
+
+```ruby
+followers = @client.channels.followers(broadcaster_id: 123, first: 100)
+
+# Fetch the next page, or nil on the last page
+followers.next_page? #=> true
+followers.next_page  #=> Twitch::Collection
+
+# Iterate over every item across all pages. Pages are fetched lazily, only as needed.
+followers.auto_paginate.each { |follower| puts follower.user_name }
+
+# Stop after 250 items, without fetching any more pages than needed
+followers.auto_paginate.first(250)
+
+# Get every item as an array
+followers.auto_paginate.to_a
+
+# Iterate page by page
+followers.each_page do |page|
+  puts "#{page.data.size} followers on this page"
+end
+```
+
 ### Rate Limiting
 
 The Twitch API has rate limits to ensure fair usage. TwitchRB automatically tracks rate limit information from API responses and can warn you when approaching limits.
@@ -168,33 +257,59 @@ The `rate_limiter` object has several useful methods:
 
 ### OAuth
 
-This library includes the ability to create, refresh and revoke OAuth tokens.
+This library includes the ability to create, refresh, validate and revoke OAuth tokens.
+
+Failed token requests raise the same errors as API requests (e.g. `Twitch::Errors::BadRequestError`),
+with Twitch's message available as `error.twitch_error_message`.
 
 ```ruby
 # Firstly, set the client details
+# client_secret can be omitted for public clients using the device code flow
 @oauth = Twitch::OAuth.new(client_id: "", client_secret: "")
 
-# Create a Token
-# grant_type can be either "authorization_code" or "client_credentials"
-# scope is a space-delimited list of scopes. This is optional depending on the grant_type
-@oauth.create(grant_type: "", scope: "")
+# Create an app access token (client credentials grant flow)
+@oauth.create(grant_type: "client_credentials")
+
+# Exchange the code from the authorization code grant flow for a user access token
+# https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#authorization-code-grant-flow
+token = @oauth.exchange_code(code: params[:code], redirect_uri: "http://localhost:3000/callback")
+token.access_token
+token.refresh_token
 
 # Refresh a Token
 @oauth.refresh(refresh_token: "")
 
-# Device Code Grant Flow
-# scopes is required and is a space-delimited list of scopes
-# https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#device-code-grant-flow
-@oauth.device(scopes: "bits:read channel:read:subscriptions")
-
 # Validate an Access Token
 # Returns false if the token is invalid
 @oauth.validate(token: "")
 
 # Revoke a Token
+# Returns false if the token couldn't be revoked
 @oauth.revoke(token: "")
 ```
 
+#### Device Code Grant Flow
+
+For apps with limited input, such as CLIs, set-top boxes or games.
+See [the Twitch docs](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#device-code-grant-flow).
+
+```ruby
+# scopes can be an array or a space-delimited string
+scopes = ["user:read:email", "chat:read"]
+device = @oauth.device(scopes: scopes)
+
+puts "Go to #{device.verification_uri} and enter #{device.user_code}"
+
+# Poll until the user has authorized the app
+token = begin
+  sleep device.interval
+  @oauth.device_token(device_code: device.device_code, scopes: scopes)
+rescue Twitch::Errors::BadRequestError => e
+  retry if e.twitch_error_message == "authorization_pending"
+  raise
+end
+```
+
 ### Users
 
 ```ruby
@@ -254,6 +369,19 @@ This library includes the ability to create, refresh and revoke OAuth tokens.
 # #<Twitch::UserAuthorization user_id="72938118", user_name="deanpcmad", user_login="deanpcmad", scopes=["user:read:email"], has_authorized=true>
 @client.users.authorization(id: 123)
 @client.users.authorization(ids: [123, 321])
+
+# 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)
+@client.users.extensions
+
+# Gets the active extensions for a user, or the authenticated user if user_id is omitted
+@client.users.active_extensions(user_id: 123)
+
+# Updates the authenticated user's active extensions
+# Required scope: user:edit:broadcast
+@client.users.update_extensions(data: {
+  panel: { "1" => { active: true, id: "abc123", version: "1.0.0" } }
+})
 ```
 
 ### Channels
@@ -437,6 +565,54 @@ end
 @client.eventsub_subscriptions.delete(id: "abc12-abc12-abc12")
 ```
 
+### EventSub Webhooks
+
+When Twitch sends EventSub notifications to your webhook callback, you must verify each request came from Twitch
+before trusting it. `Twitch::EventsubWebhook` checks the HMAC signature using the `secret` you passed when creating
+the subscription, and rejects messages older than 10 minutes to guard against replay attacks.
+
+Pass the **raw** request body, as the signature covers the exact bytes Twitch sent. `headers` can be a Hash,
+a Rack env, or Rails' `request.headers`.
+
+```ruby
+# Rails example
+class TwitchWebhooksController < ApplicationController
+  skip_forgery_protection
+
+  def create
+    webhook = Twitch::EventsubWebhook.new(
+      secret: ENV["TWITCH_EVENTSUB_SECRET"],
+      headers: request.headers,
+      body: request.raw_post
+    )
+
+    return head :forbidden unless webhook.valid?
+
+    if webhook.verification?
+      # Twitch confirms you own the callback when you create a subscription
+      render plain: webhook.challenge
+    elsif webhook.notification?
+      # Twitch may send a message more than once, so skip message IDs you've already processed
+      # webhook.subscription_type  #=> "channel.follow"
+      # webhook.event              #=> #<Twitch::Object user_id="1234", user_login="cool_user", ...>
+      head :no_content
+    elsif webhook.revocation?
+      # webhook.subscription.status  #=> "authorization_revoked"
+      head :no_content
+    end
+  end
+end
+
+# Or just check the signature and timestamp
+Twitch::EventsubWebhook.verify(secret: "...", headers: request.headers, body: request.raw_post)
+
+# Allow a different maximum message age, in seconds (default 600)
+Twitch::EventsubWebhook.new(secret: "...", headers: request.headers, body: request.raw_post, max_age: 300)
+```
+
+Other readers: `message_id`, `message_type`, `timestamp`, `retry?`, `subscription_version`, `payload` (the parsed body),
+`signature_valid?`, and `expired?`.
+
 ### Custom Power-ups
 
 ```ruby
@@ -484,15 +660,13 @@ shards = [
     }
   }
 ]
-@client.eventsub_conduits.update_shards(id: "abc123-def456", shards: shards)
-```
+result = @client.eventsub_conduits.update_shards(id: "abc123-def456", shards: shards)
 
-### Banned Events
-
-```ruby
-# Retrieves all ban and un-ban events for a channel
-# Available parameters: user_id
-@client.banned_events.list(broadcaster_id: 123)
+# Twitch accepts up to 100 shards per request, so larger lists are sent in batches automatically.
+# Twitch applies the valid shards even if others fail, so check errors for any that didn't update:
+result.errors.each do |error|
+  puts "Shard #{error.id} failed: #{error.message} (#{error.code})"
+end
 ```
 
 ### Banned Users
@@ -735,6 +909,11 @@ messages = [{msg_id: "abc1", msg_text: "is this allowed?"}, {msg_id: "abc2", msg
 # Required scope: channel:read:charity
 # broadcaster_id must match the currently authenticated user
 @client.charity_campaigns.list broadcaster_id: 123
+
+# Gets the donations made to the broadcaster's active charity campaign
+# Required scope: channel:read:charity
+# broadcaster_id must match the currently authenticated user
+@client.charity_campaigns.donations(broadcaster_id: 123)
 ```
 
 ### Chatters
@@ -900,8 +1079,12 @@ outcomes = [
 # Check if a user is subscribed to a broadcaster
 # Required scope: user:read:subscriptions
 # user_id must match the currently authenticated user
+# Returns a collection with the subscription, or raises Twitch::Errors::EntityNotFoundError if not subscribed
 @client.subscriptions.is_subscribed(broadcaster_id: 123, user_id: 456)
 
+# Or get true/false
+@client.subscriptions.subscribed?(broadcaster_id: 123, user_id: 456)
+
 # Get subscription counts and points for a broadcaster
 # Required scope: channel:read:subscriptions
 # broadcaster_id must match the currently authenticated user
@@ -969,44 +1152,188 @@ outcomes = [
 @client.stream_markers.list(video_id: "video-id")
 ```
 
-### Tags
+### Hype Train Status
 
 ```ruby
-# Get all stream tags
-@client.tags.list
+# Get hype train status for a broadcaster
+# Required scope: channel:read:hype_train
+# broadcaster_id must match the currently authenticated user
+@client.hype_train_status.retrieve(broadcaster_id: 123)
+```
 
-# Get stream tags for a specific broadcaster
-@client.tags.stream(broadcaster_id: 123)
 
-# Replace stream tags for a broadcaster
-# Required scope: channel:manage:broadcast
+### Ads
+
+```ruby
+# Gets the broadcaster's ad schedule and snooze details
+# Required scope: channel:read:ads
+# broadcaster_id must match the currently authenticated user
+@client.ads.schedule(broadcaster_id: 123)
+
+# Pushes back the next scheduled ad by 5 minutes
+# Required scope: channel:manage:ads
 # broadcaster_id must match the currently authenticated user
-tag_ids = ["tag-id-1", "tag-id-2"]
-@client.tags.replace(broadcaster_id: 123, tag_ids: tag_ids)
+@client.ads.snooze(broadcaster_id: 123)
 ```
 
-### Hype Train Status
+### Analytics
 
 ```ruby
-# Get hype train status for a broadcaster
-# Required scope: channel:read:hype_train
-# broadcaster_id must match the currently authenticated user
-@client.hype_train_status.retrieve(broadcaster_id: 123)
+# Gets URLs for downloadable CSV reports about the authenticated user's extensions
+# Required scope: analytics:read:extensions
+# Available parameters: extension_id, type, started_at, ended_at, first, after
+@client.analytics.extensions(extension_id: "abc123")
+
+# Gets URLs for downloadable CSV reports about the authenticated user's games
+# Required scope: analytics:read:games
+# Available parameters: game_id, type, started_at, ended_at, first, after
+@client.analytics.games(game_id: 123)
 ```
 
-### Moderator Events
+### Bits
 
 ```ruby
-# Get moderator events for a broadcaster
-# Required scope: moderation:read
-# broadcaster_id must match the currently authenticated user
-@client.moderator_events.list(broadcaster_id: 123)
+# Gets the Bits leaderboard for the authenticated broadcaster
+# Required scope: bits:read
+# Available parameters: count, period, started_at, user_id
+@client.bits.leaderboard(count: 10, period: "week")
+
+# Gets the global Cheermotes, plus a broadcaster's custom Cheermotes if broadcaster_id is given
+@client.bits.cheermotes
+@client.bits.cheermotes(broadcaster_id: 123)
+```
+
+### Chat Settings
+
+```ruby
+# Gets a broadcaster's chat settings
+# Pass moderator_id (matching the authenticated user) to include non_moderator_chat_delay settings
+@client.chat_settings.retrieve(broadcaster_id: 123)
+@client.chat_settings.retrieve(broadcaster_id: 123, moderator_id: 321)
+
+# Updates a broadcaster's chat settings
+# Required scope: moderator:manage:chat_settings
+# moderator_id must match the currently authenticated user
+# Available attributes: emote_mode, follower_mode, follower_mode_duration, non_moderator_chat_delay,
+# non_moderator_chat_delay_duration, slow_mode, slow_mode_wait_time, subscriber_mode, unique_chat_mode
+@client.chat_settings.update(broadcaster_id: 123, moderator_id: 321, slow_mode: true, slow_mode_wait_time: 10)
+```
+
+### Shield Mode
+
+```ruby
+# Gets a broadcaster's Shield Mode status
+# Required scope: moderator:read:shield_mode or moderator:manage:shield_mode
+# moderator_id must match the currently authenticated user
+@client.shield_mode.retrieve(broadcaster_id: 123, moderator_id: 321)
+
+# Turns Shield Mode on or off
+# Required scope: moderator:manage:shield_mode
+# moderator_id must match the currently authenticated user
+@client.shield_mode.update(broadcaster_id: 123, moderator_id: 321, is_active: true)
+```
+
+### Content Classification Labels
+
+```ruby
+# Gets the content classification labels that can be applied to a channel with channels.update
+@client.content_classification_labels.list
+@client.content_classification_labels.list(locale: "en-US")
+```
+
+### Teams
+
+```ruby
+# Gets a team by ID or name
+@client.teams.retrieve(id: 123)
+@client.teams.retrieve(name: "staff")
+
+# Gets the teams a broadcaster is a member of
+@client.teams.channel(broadcaster_id: 123)
+```
+
+### Drops Entitlements
+
+```ruby
+# Gets Drops entitlements
+# The Client ID must be owned by a member of the organization that owns the game
+# Available parameters: id, user_id, game_id, fulfillment_status, first, after
+@client.drops_entitlements.list(user_id: 123)
+
+# Updates the fulfillment status of Drops entitlements (CLAIMED or FULFILLED)
+@client.drops_entitlements.update(entitlement_ids: ["abc", "def"], fulfillment_status: "FULFILLED")
+```
+
+### Extensions
+
+Most Extensions 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
+[Signing the JWT](https://dev.twitch.tv/docs/extensions/building/#signing-the-jwt).
+
+```ruby
+@ext_client = Twitch::Client.new(client_id: "extension-client-id", access_token: signed_jwt)
+
+# Gets an extension (requires a JWT), or a released extension (app or user token)
+@ext_client.extensions.retrieve(extension_id: "abc123")
+@client.extensions.released(extension_id: "abc123", extension_version: "1.0.0")
+
+# Gets live channels that have the extension installed or activated
+@client.extensions.live_channels(extension_id: "abc123")
+
+# Gets and sets configuration segments (requires a JWT)
+# segment: broadcaster, developer or global. Pass an array to get more than one.
+@ext_client.extensions.configuration(extension_id: "abc123", segment: "broadcaster", broadcaster_id: 123)
+@ext_client.extensions.set_configuration(extension_id: "abc123", segment: "broadcaster", broadcaster_id: 123, content: "{}", version: "1")
+@ext_client.extensions.set_required_configuration(broadcaster_id: 123, extension_id: "abc123", extension_version: "1.0.0", required_configuration: "RCS")
+
+# Sends a PubSub message or chat message (requires a JWT)
+@ext_client.extensions.send_pubsub_message(broadcaster_id: 123, target: ["broadcast"], message: "hello")
+@ext_client.extensions.send_chat_message(broadcaster_id: 123, text: "hello", extension_id: "abc123", extension_version: "1.0.0")
+
+# Gets or creates the extension's JWT secrets (requires a JWT)
+@ext_client.extensions.secrets(extension_id: "abc123")
+@ext_client.extensions.create_secret(extension_id: "abc123", delay: 300)
+
+# Gets and updates Bits products
+# Requires an app access token whose Client ID matches the extension's
+@app_client.extensions.bits_products(should_include_all: true)
+@app_client.extensions.update_bits_product(sku: "sku-1", cost: { amount: 100, type: "bits" }, display_name: "Thing")
+
+# Gets Bits transactions for the extension
+# Requires an app access token
+@app_client.extensions.transactions(extension_id: "abc123")
+```
+
+### Guest Star (Beta)
+
+```ruby
+# Gets and updates a channel's Guest Star settings
+@client.guest_star.settings(broadcaster_id: 123, moderator_id: 321)
+@client.guest_star.update_settings(broadcaster_id: 123, slot_count: 4)
+
+# Gets, creates and ends a Guest Star session
+@client.guest_star.session(broadcaster_id: 123, moderator_id: 321)
+@client.guest_star.create_session(broadcaster_id: 123)
+@client.guest_star.end_session(broadcaster_id: 123, session_id: "abc")
+
+# Gets, sends and deletes invites
+@client.guest_star.invites(broadcaster_id: 123, moderator_id: 321, session_id: "abc")
+@client.guest_star.send_invite(broadcaster_id: 123, moderator_id: 321, session_id: "abc", guest_id: 456)
+@client.guest_star.delete_invite(broadcaster_id: 123, moderator_id: 321, session_id: "abc", guest_id: 456)
+
+# Assigns, moves and removes guests in slots
+@client.guest_star.assign_slot(broadcaster_id: 123, moderator_id: 321, session_id: "abc", guest_id: 456, slot_id: "1")
+@client.guest_star.update_slot(broadcaster_id: 123, moderator_id: 321, session_id: "abc", source_slot_id: "1", destination_slot_id: "2")
+@client.guest_star.delete_slot(broadcaster_id: 123, moderator_id: 321, session_id: "abc", guest_id: 456, slot_id: "1")
+
+# Updates a slot's audio, video, live and volume settings
+@client.guest_star.update_slot_settings(broadcaster_id: 123, moderator_id: 321, session_id: "abc", slot_id: "1", volume: 50)
 ```
 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/deanpcmad/twitchrb.
+Bug reports and pull requests are welcome on GitHub at https://github.com/d34ndev/twitchrb.
 
 ## License