twitchrb 1.10.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fbfacc0abeb1677c2f16b79eefeaaaedb1b7ff4f3506fcf2f465ffb82735f78
-  data.tar.gz: 2a04bfacd176f1287cacfe55c939550a8b2b92f63b207aead8ae48dc47de0508
+  metadata.gz: 0641bf783f69ad1e15ce425ab0a04932376a98403eb996cae29e44cb04509869
+  data.tar.gz: c50b205b48bc9671724f848e81329ff980873f598fb278da24c344c753ff1768
 SHA512:
-  metadata.gz: d472b2b93b0aaacaf635079e4dd1a35d213026f0c517dd7c2f6b411f7a1caf8121fd652b46672c145730cd648f94aa5206c0655fd8d2bf08508f11b257facdb4
-  data.tar.gz: f175c566b480a93032f9fb19cfeb490f9834d5c8f58aa4f2141fd2488f3191047f556cd90518f166e00acd8ffb581e3b214161a90aee317d4621e49dbdfa3158
+  metadata.gz: f5f5d1850b6595dce58b11f9b2cd4756f3ae00043ce22c6643d20fd133232270abf6d24360b4d2a2ef7c3220b1b1cf888745ac418ce7582c3cf220c022bfca4a
+  data.tar.gz: 32e637838de8ea70e207655e3d870a7f7f80a021f4fb3afe4211f74293f6fcfce54e525d7f79ea859908bc2cf7f26277d3109812132610e7b48b4fe0659c0322

data/.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
     continue-on-error: true
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -28,7 +28,7 @@ jobs:
           - '3.4'
           - '4.0'
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby_version }}

data/.rubocop.yml

@@ -4,7 +4,7 @@ inherit_gem: { rubocop-rails-omakase: rubocop.yml }
 AllCops:
   Exclude:
     - 'test/**/*'
-  TargetRubyVersion: 4.0
+  TargetRubyVersion: 3.3
 
 # Overwrite or add rules to create your own house style
 #

data/CHANGELOG.md

@@ -4,7 +4,110 @@ All notable changes to `twitchrb` are documented in this file.
 
 Published release notes were sourced from GitHub releases where available. Older tag-only versions and the current unreleased work were reconstructed from local git history.
 
-## [1.10.0] - Unreleased
+## [2.0.0] - 2026-09-23
+
+This release adds every remaining Helix endpoint, automatic pagination, automatic token refresh, and EventSub
+webhook verification, and fixes many requests that didn't match the Twitch API reference. It contains breaking
+changes, listed below.
+
+### Upgrading from 1.x
+
+- **Ruby 3.3 or newer is required.**
+- **Methods for endpoints Twitch has shut down were removed:**
+  - `hype_train_events.list` → use `hype_train_status.retrieve(broadcaster_id:)`.
+  - `users.follows` and `users.following?` → use `channels.followers(broadcaster_id:, user_id:)` to check whether a
+    user follows a channel, or `channels.followed(user_id:)` to list the channels a user follows.
+  - `tags.list`, `tags.stream`, and `tags.replace` → channel tags are returned by `channels.retrieve` and set with
+    `channels.update(broadcaster_id:, tags: [...])`.
+  - `banned_events.list` and `moderator_events.list` → no API replacement; use the `channel.ban`, `channel.unban`,
+    and `channel.moderate` EventSub subscriptions.
+- **`oauth.create`, `oauth.refresh`, and `oauth.device` raise errors instead of returning `false`.** Replace checks
+  like `if token = oauth.refresh(...)` with a `rescue`:
+
+  ```ruby
+  begin
+    token = oauth.refresh(refresh_token: refresh_token)
+  rescue Twitch::Error => e
+    e.twitch_error_message #=> "Invalid refresh token"
+  end
+  ```
+
+  `oauth.validate` and `oauth.revoke` still return `false`.
+- **Missing required arguments raise `ArgumentError`** instead of `RuntimeError`. Update any `rescue RuntimeError`.
+- **`to_h` on response objects now converts nested objects to hashes too.** If you called methods on nested values
+  from `to_h` (e.g. `object.to_h[:current].id`), use hash access instead (`object.to_h[:current][:id]`), or call the
+  method on the object itself (`object.current.id`).
+
+### Changed
+- Missing required arguments (e.g. calling `clips.list` without `broadcaster_id`, `game_id` or `id`) now raise `ArgumentError` instead of `RuntimeError`.
+- **Breaking:** `oauth.create`, `oauth.refresh`, and `oauth.device` now raise errors (e.g. `Twitch::Errors::BadRequestError`, with Twitch's message in `twitch_error_message`) instead of returning `false`. `oauth.validate` and `oauth.revoke` still return `false`.
+- The minimum supported Ruby version is now 3.3 (previously declared as 2.3, though the gem already required 3.1+). This matches the versions tested in CI.
+
+### Added
+- `subscriptions.subscribed?(broadcaster_id:, user_id:)`, which returns `true` or `false` instead of raising when the user isn't subscribed.
+- Automatic token refresh: pass `refresh_token:` (and `client_secret:`, unless your app is a public client) to `Twitch::Client.new`, and requests that fail because the access token expired are retried once with a refreshed token. `on_token_refresh:` is called with the new token so you can store it, and `client.refresh_access_token!` refreshes manually.
+- Automatic pagination: collections from paginated endpoints now have `next_page?`, `next_page`, `each_page`, and `auto_paginate`, which lazily iterates over every item across pages (e.g. `auto_paginate.first(250)` only fetches the pages it needs).
+- `Twitch::EventsubWebhook` to verify and parse EventSub webhook requests. It checks the HMAC signature in constant time, rejects messages older than 10 minutes, and gives access to the message type, challenge, subscription, and event.
+- `oauth.exchange_code(code:, redirect_uri:)` for the authorization code grant flow, and `oauth.device_token(device_code:, scopes:)` to finish the device code grant flow. Previously neither flow could be completed.
+- `oauth.create` sends extra keyword arguments (such as `code` and `redirect_uri`) with the request, and `scope`/`scopes` accept arrays.
+- `Twitch::OAuth.new` no longer requires a `client_secret`, for public clients using the device code flow.
+- `ads.schedule` and `ads.snooze` (Get Ad Schedule, Snooze Next Ad).
+- `analytics.extensions` and `analytics.games`.
+- `bits.leaderboard` and `bits.cheermotes`.
+- `charity_campaigns.donations`.
+- `chat_settings.retrieve` and `chat_settings.update`.
+- `shield_mode.retrieve` and `shield_mode.update`.
+- `content_classification_labels.list`.
+- `teams.retrieve` and `teams.channel`.
+- `drops_entitlements.list` and `drops_entitlements.update`.
+- `users.extensions`, `users.active_extensions`, and `users.update_extensions`.
+- An `extensions` resource covering the Extensions API: `retrieve`, `released`, `live_channels`, `configuration`, `set_configuration`, `set_required_configuration`, `send_pubsub_message`, `send_chat_message`, `secrets`, `create_secret`, `bits_products`, `update_bits_product`, and `transactions`.
+- A `guest_star` resource covering the Guest Star beta API.
+
+### Removed
+- Removed methods for endpoints Twitch has shut down, which could only return errors:
+  - `hype_train_events.list`, which forwarded to `hype_train_status.retrieve` with a deprecation warning since 1.10.0.
+  - `banned_events.list` and `moderator_events.list` (Get Banned Events / Get Moderator Events).
+  - `users.follows` and `users.following?` (`GET /users/follows`). Use `channels.followers` or `channels.followed` instead.
+  - `tags.list`, `tags.stream`, and `tags.replace` (the old Twitch-defined stream tags). Channel tags are now read with `channels.retrieve` and set with `channels.update(tags: [...])`.
+- Removed the now-unused `Twitch::BannedEvent`, `Twitch::ModeratorEvent`, `Twitch::FollowedUser`, `Twitch::HypeTrainEvent`, and `Twitch::Tag` classes.
+
+### Fixed
+- Fixed multi-value query params (e.g. `users.retrieve(ids:)`, `games.retrieve(names:)`, `streams.list(user_id: [...])`, `clips.downloads(clip_ids:)`) being sent as `id[]=1&id[]=2`. They are now sent as repeated keys (`id=1&id=2`), which is the format Helix expects.
+- Fixed write endpoints sending query string parameters in the JSON body instead of the query string, contrary to the Twitch API reference. Affects `channels.update`, `custom_rewards.create`/`update`, `automod.check_status`/`check_status_multiple`/`update_settings`, `banned_users.create`, `blocked_terms.create`, `unban_requests.resolve`, `moderators.create`, `vips.create`, `raids.create`, `whispers.create`, `stream_schedule.update`/`create_segment`/`update_segment`, `users.update`, and `users.block_user` (whose `source_context` and `reason` options were being sent in the body).
+- Fixed `clips.list` and `videos.list` rejecting calls that only pass `id`, which both endpoints accept.
+- Fixed `eventsub_conduits.update_shards` discarding the `errors` Twitch returns for shards that failed to update. They are now available as `result.errors`, and `Collection#errors` is available for any endpoint that reports partial failures.
+- `eventsub_conduits.update_shards` now sends lists of more than 100 shards in batches of 100, the most Twitch accepts per request.
+- Fixed `oauth.device` sending `scope` instead of `scopes`, which Twitch requires.
+- Fixed `to_h` and `to_json` on response objects leaving nested objects as `OpenStruct`s, which serialized as strings like `"#<OpenStruct ...>"`. Nested objects and arrays are now converted to plain hashes, and `as_json` is defined for Rails.
+- `Collection#cursor` now works for endpoints that return `pagination` as a bare string (such as Get Extension Live Channels) instead of raising.
+- `banned_users.create` no longer sends `"duration": null` for permanent bans.
+- Helix and OAuth requests now have default timeouts (30s read, 10s open) instead of waiting indefinitely. Configure with the `timeout:` and `open_timeout:` options on `Twitch::Client.new` and `Twitch::OAuth.new`.
+
+## [1.11.0] - 2026-08-11
+
+### Fixed
+- Fixed a `NoMethodError` crash when API responses have non-JSON bodies, such as `stream_schedule.icalendar` (which was completely broken) and HTML error pages from proxies.
+- Fixed `users.retrieve` and `games.retrieve` returning `nil` when a plural lookup (`ids`, `usernames`, `names`) matched exactly one item; plural lookups now always return a `Collection`. Singular lookups with no match now return `nil` instead of an empty object.
+- Fixed `oauth.revoke` always returning `true`; it now returns `false` when revocation fails, matching `validate`, `create`, and `refresh`.
+- Fixed `blocked_terms.create` returning a `BannedUser` instead of a `BlockedTerm`.
+- Fixed `suspicious_users.delete` crashing on 204 No Content responses; it now returns `true`.
+- Fixed query string values not being escaped in request paths. Notably, `users.update_color` silently dropped hex colors like `#9146FF`.
+- Errors are now raised for any 4xx/5xx response; previously 422, 502, and 504 slipped through unraised.
+- `Collection#total` now reports the `total` field from the API for paginated endpoints instead of the page size, and responses without a `data` key return an empty collection instead of raising.
+- Removed a leftover debug `puts` in `users.get_color`.
+- Error messages for unmapped statuses no longer duplicate the Twitch message.
+- Updated the minimum Faraday version to 2.14.3 to fix the uncontrolled recursion denial-of-service vulnerability in `NestedParamsEncoder` (CVE-2026-54297).
+
+### Changed
+- The `auto_retry_rate_limit` client option (default `true`) now works: requests that hit a 429 wait until the rate limit window resets and retry once. Previously the option was accepted but ignored.
+- All API errors now inherit from `Twitch::Error`, so they can be rescued with a single base class.
+- `eventsub_subscriptions.create` now goes through the shared request helpers, gaining request path validation and rate limit auto-retry.
+
+### Added
+- `users.get_color` accepts an array for `user_ids`, in line with other multi-id endpoints. Comma-separated strings still work.
+
+## [1.10.0] - 2026-05-16
 
 ### Added
 - Added custom power-up API support.

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    twitchrb (1.10.0)
-      faraday (>= 2.14.1, < 3)
+    twitchrb (2.0.0)
+      faraday (>= 2.14.3, < 3)
       ostruct (~> 0.6.0)
 
 GEM
@@ -27,7 +27,7 @@ GEM
     benchmark (0.5.0)
     bigdecimal (4.1.2)
     cgi (0.5.1)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.8)
     connection_pool (3.0.2)
     crack (1.0.1)
       bigdecimal
@@ -36,7 +36,7 @@ GEM
     dotenv (3.2.0)
     drb (2.2.3)
     erb (6.0.4)
-    faraday (2.14.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -51,7 +51,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.5)
+    json (2.21.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)