rito 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 882b1dd78a0168c537a254240ff33562776b50a95ee04e17864229bde2cde2b0
+  data.tar.gz: ad4ec1b37559654409118de196adcdcb082f813a186e92688988adb8ebba3379
+SHA512:
+  metadata.gz: d0cef7acb7d9d98b2176dae271f24ccd23037c4d091be4e5896ff71a08682bd9657a072bf3ede3bb7ef5c328f55ff7826b2624e8305d6895746d99b0400338ed
+  data.tar.gz: 1f54d50efe21dc86999746be59cc29704610288b8cd595a2e09b97fe78831edef5ed6a1e81815f0afd60277733ce1cc8d3a2be22807302ebfaac6bb21d15b522

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.1.0 (2026-09-05)
+
+Initial release.
+
+- **HTTP layer**: Faraday 2.x with a per-host connection cache, JSON
+  request/response middleware, and transport retries (5xx, connection
+  failures) via faraday-retry.
+- **Routing**: platform vs regional routing values with automatic escalation
+  (`na1 → americas`), SEA→ASIA normalization for account-v1, and separate
+  VALORANT platform sets (`na1, eu, ap, kr, latam, br`; console: `na, eu, ap`).
+- **Rate limiting**: `AdaptiveLimiter` (default) learns limits from
+  `X-App-Rate-Limit` / `X-Method-Rate-Limit` headers, syncs counters from
+  `*-Count` headers, throttles pre-emptively, handles 429s by scope
+  (application / method / service) honoring `Retry-After` with exponential
+  backoff + jitter fallback. `NullLimiter` for reactive-only mode.
+  `RedisLimiter` for multi-process deployments (soft dependency on `redis`).
+- **Errors**: mapped hierarchy (400/401/403/404/405/415/429/5xx,
+  ConnectionError/TimeoutError/SSLError); `RateLimited` carries
+  `retry_after` and `limit_type`.
+- **Models**: frozen `Data` classes with liberal mapping; unknown fields
+  preserved in `.raw`.
+- **Coverage**: account-v1; LoL summoner-v4, match-v5, champion-mastery-v4,
+  champion-v3, league-v4, league-exp-v4, spectator-v5, lol-status-v4, clash-v1,
+  lol-challenges-v1, tournament-v5 (+ stub); TFT summoner/league/match/status/
+  spectator; VALORANT content/match/console-match/ranked/status; LoR
+  match/ranked/status/deck/inventory (RSO); riftbound-content-v1.
+- **Instrumentation**: `request.rito` ActiveSupport::Notifications events
+  (no-op without ActiveSupport).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kodbilenadam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# Rito
+
+A modern, production-ready Ruby client for the Riot Games API: League of
+Legends, TFT, VALORANT, Legends of Runeterra, Riftbound, and the Riot Account API.
+
+Full routing-value handling, header-driven adaptive rate limiting, frozen
+`Data` models, and a single runtime dependency (Faraday).
+
+## Installation
+
+```ruby
+gem "rito"
+```
+
+## Quick start
+
+```ruby
+require "rito"
+
+Rito.configure do |c|
+  c.api_key = ENV.fetch("RIOT_API_KEY")
+  c.region = :na1
+end
+
+client = Rito::Client.new
+
+account = client.account.by_riot_id("Hide on bush", "KR1", region: :asia)
+summoner = client.summoner.by_puuid(account.puuid, region: :kr)
+match_ids = client.matches.ids_by_puuid(account.puuid, region: :asia, count: 5)
+```
+
+## Configuration
+
+Class-level config with per-client overrides (later wins):
+
+```ruby
+Rito.api_key        # default: ENV["RIOT_API_KEY"]
+Rito.bearer_token   # default: ENV["RIOT_RSO_TOKEN"] (RSO endpoints)
+Rito.region         # default routing value, e.g. :na1
+Rito.max_retries    # 429 / transport retries (default: 3)
+Rito.rate_limiter   # rate limit strategy (default: AdaptiveLimiter)
+
+# per-client, for multi-key apps:
+client = Rito::Client.new(api_key: "RGAPI-...", region: :kr)
+```
+
+## Routing values
+
+Endpoints declare whether they are platform-routed (`na1`, `kr`, ...) or
+regionally routed (`americas`, `europe`, `asia`, `sea`). You pass whichever you
+have; the client escalates automatically:
+
+```ruby
+client.summoner.by_puuid(puuid, region: :kr)         # platform host: kr
+client.matches.ids_by_puuid(puuid, region: :kr)      # regional host: asia (escalated)
+client.account.by_puuid(puuid, region: :sea)         # account-v1 has no SEA host → asia
+```
+
+## Rate limiting
+
+The default `AdaptiveLimiter` learns your key's limits from
+`X-App-Rate-Limit` / `X-Method-Rate-Limit` headers, syncs counters from
+`*-Count` headers, throttles pre-emptively, and handles 429s:
+
+- `Retry-After` present → blocks that long (app-scope blocks the whole
+  key+region; method-scope blocks only the endpoint).
+- `Retry-After` missing → exponential backoff with jitter.
+- No `X-Rate-Limit-Type` header → service-level 429 → endpoint-only backoff.
+
+Exhausted retries raise `Rito::RateLimited` (with `.retry_after` and
+`.limit_type`). Opt out with `Rito::RateLimiting::NullLimiter`.
+
+### Multi-worker deployments
+
+Each process using the default `AdaptiveLimiter` tracks limits independently,
+so a multi-worker setup (Puma cluster, multiple hosts) can collectively exceed
+one key's limits. Use the Redis limiter for shared state:
+
+```ruby
+limiter = Rito::RateLimiting::RedisLimiter.new(redis: Redis.new)
+client = Rito::Client.new(rate_limiter: limiter)
+```
+
+Note: `acquire!` blocks the calling thread while throttled — fine in
+background jobs; in web requests prefer jobs or `max_retries: 0` with
+explicit `Rito::RateLimited` handling.
+
+### Multi-process (Redis)
+
+```ruby
+gem "redis" # soft dependency
+
+limiter = Rito::RateLimiting::RedisLimiter.new(redis: Redis.new)
+client = Rito::Client.new(rate_limiter: limiter)
+```
+
+## Errors
+
+```
+Rito::Error
+├── BadRequest (400)          ├── MethodNotAllowed (405)
+├── Unauthorized (401)        ├── UnsupportedMediaType (415)
+├── Forbidden (403)           ├── RateLimited (429)
+├── NotFound (404)            ├── ServerError / ServiceUnavailable (5xx)
+└── ConnectionError (TimeoutError, SSLError)
+```
+
+Every error carries `.status` and `.response`. Messages include the method,
+URL, and Riot's error detail.
+
+## Models
+
+Responses are frozen `Data` objects. Documented fields are typed accessors;
+unknown fields Riot adds later are preserved in `.raw`:
+
+```ruby
+entry = client.leagues.entries_by_summoner_id(summoner_id).first
+entry.tier      # => "DIAMOND"
+entry.winrate   # => 57.14
+entry.raw       # => full payload hash
+```
+
+## Coverage
+
+| Accessor | API |
+| --- | --- |
+| `client.account` | account-v1 |
+| `client.summoner` | summoner-v4 |
+| `client.matches` | match-v5 (matches, matchlist, timeline) |
+| `client.champion_masteries` | champion-mastery-v4 |
+| `client.champions` | champion-v3 (rotations) |
+| `client.leagues` / `client.league_exp` | league-v4 / league-exp-v4 |
+| `client.spectator` | spectator-v5 (`active_game` returns `nil` on 404) |
+| `client.lol_status` | lol-status-v4 |
+| `client.clash` | clash-v1 |
+| `client.challenges` | lol-challenges-v1 |
+| `client.tournaments` / `client.tournament_stub` | tournament-v5 / stub-v5 |
+| `client.tft.summoner` / `.leagues` / `.matches` / `.status` / `.spectator` | tft-summoner-v1, tft-league-v1, tft-match-v1, tft-status-v1, spectator-tft-v5 |
+| `client.val.content` / `.matches` / `.console_matches` / `.ranked` / `.status` | val-content-v1, val-match-v1, val-console-match-v1, val-ranked-v1, val-status-v1 |
+| `client.lor.matches` / `.ranked` / `.status` / `.decks` / `.inventory` | lor-match-v1, lor-ranked-v1, lor-status-v1, lor-deck-v1 / lor-inventory-v1 (RSO) |
+| `client.riftbound` | riftbound-content-v1 |
+
+Note: VALORANT uses its own platform routing values (`na1, eu, ap, kr, latam, br`;
+console: `na, eu, ap`) — the client validates against the right set per product.
+
+## Testing your own app
+
+`Rito` plays well with WebMock. Recorded fixtures via VCR:
+
+```
+bundle exec rake cassettes   # re-record (needs RIOT_API_KEY_TEST in .env)
+bundle exec rake test
+```
+
+## Instrumentation
+
+If ActiveSupport is present (e.g. in a Rails app), every request emits a
+`request.rito` notification:
+
+```ruby
+ActiveSupport::Notifications.subscribe("request.rito") do |*, payload|
+  Rails.logger.info(
+    "#{payload[:http_method]} #{payload[:url]} -> #{payload[:status]} " \
+    "in #{payload[:duration_ms]}ms (attempts: #{payload[:attempts]})"
+  )
+end
+```
+
+Without ActiveSupport, instrumentation is a no-op.
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+Ruby 3.2+ required (`Data.define`).
+
+## License
+
+MIT

data/lib/rito/client.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Rito
+  class Client
+    attr_reader :api_key, :bearer_token, :region, :limiter, :max_retries,
+                :open_timeout, :timeout, :adapter
+
+    def initialize(api_key: nil, bearer_token: nil, region: nil, rate_limiter: nil,
+                   max_retries: nil, open_timeout: nil, timeout: nil, adapter: nil)
+      @api_key = api_key || Rito.api_key
+      @bearer_token = bearer_token || Rito.bearer_token
+      @region = region || Rito.region
+      @limiter = rate_limiter || Rito.rate_limiter || RateLimiting::AdaptiveLimiter.new
+      @max_retries = max_retries || Rito.max_retries
+      @open_timeout = open_timeout || Rito.open_timeout
+      @timeout = timeout || Rito.timeout
+      @adapter = adapter || Rito.adapter
+      @connection = Connection.new(self)
+
+      validate!
+    end
+
+    def account
+      Endpoints::AccountV1.new(self)
+    end
+
+    def summoner
+      Endpoints::Lol::SummonerV4.new(self)
+    end
+
+    def matches
+      Endpoints::Lol::MatchV5.new(self)
+    end
+
+    def champion_masteries
+      Endpoints::Lol::ChampionMasteryV4.new(self)
+    end
+
+    def champions
+      Endpoints::Lol::ChampionV3.new(self)
+    end
+
+    def leagues
+      Endpoints::Lol::LeagueV4.new(self)
+    end
+
+    def league_exp
+      Endpoints::Lol::LeagueExpV4.new(self)
+    end
+
+    def spectator
+      Endpoints::Lol::SpectatorV5.new(self)
+    end
+
+    def lol_status
+      Endpoints::Lol::StatusV4.new(self)
+    end
+
+    def clash
+      Endpoints::Lol::ClashV1.new(self)
+    end
+
+    def challenges
+      Endpoints::Lol::ChallengesV1.new(self)
+    end
+
+    def tournaments
+      Endpoints::Lol::TournamentV5.new(self)
+    end
+
+    def tournament_stub
+      Endpoints::Lol::TournamentStubV5.new(self)
+    end
+
+    def tft
+      Rito::Tft::Api.new(self)
+    end
+
+    def val
+      Rito::Val::Api.new(self)
+    end
+
+    def lor
+      Rito::Lor::Api.new(self)
+    end
+
+    def riftbound
+      Endpoints::Riftbound.new(self)
+    end
+
+    def request(method, path, routing_kind:, routing_value: nil, params: {}, body: nil)
+      region = Routing.resolve(routing_kind, routing_value || @region)
+      connection = @connection.for_host(Routing.host_for(region))
+      response = connection.run_request(method, path, body, {}) do |req|
+        req.params.update(params) unless params.empty?
+      end
+      # 5xx responses reaching here are final: faraday-retry has exhausted
+      # its retries (or the status was not retryable).
+      raise_server_error!(response) if response.status >= 500
+      response
+    end
+
+    private
+
+    def raise_server_error!(response)
+      status = response.status
+      error_class = status == 503 ? ServiceUnavailable : ServerError
+      raise error_class.new("#{status} (after transport retries)", response: response)
+    end
+
+    def validate!
+      raise ConfigError, 'api_key or bearer_token is required' if @api_key.to_s.empty? && @bearer_token.to_s.empty?
+      return if Routing.platform?(@region) || Routing.regional?(@region)
+
+      raise ConfigError, "unknown region: #{@region.inspect}"
+    end
+  end
+end

data/lib/rito/connection.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rito
+  class Connection
+    def initialize(client)
+      @client = client
+      @connections = {}
+      @mutex = Mutex.new
+    end
+
+    def for_host(host)
+      @mutex.synchronize do
+        @connections[host] ||= build(host)
+      end
+    end
+
+    private
+
+    def build(host)
+      Faraday.new("https://#{host}") do |f|
+        f.options.open_timeout = @client.open_timeout
+        f.options.timeout = @client.timeout
+        f.request :json
+        f.request :retry,
+                  max: @client.max_retries,
+                  retry_statuses: [500, 503, 504],
+                  interval: 0.5,
+                  backoff_factor: 2,
+                  exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::RetriableResponse]
+        f.use Middleware::RateLimitThrottle, client: @client
+        f.use Middleware::Authentication, client: @client
+        f.use Middleware::RiotErrors, client: @client
+        f.use Middleware::RateLimitObserve, client: @client
+        f.response :json, content_type: /\bjson$/
+        f.adapter @client.adapter
+      end
+    end
+  end
+end

data/lib/rito/endpoints/account_v1.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    class AccountV1 < Base
+      ROUTING = :regional
+
+      def by_riot_id(game_name, tag_line, region: nil)
+        Models::Account.from_api(
+          get("/riot/account/v1/accounts/by-riot-id/#{escape(game_name)}/#{escape(tag_line)}", region)
+        )
+      end
+
+      def by_puuid(puuid, region: nil)
+        Models::Account.from_api(
+          get("/riot/account/v1/accounts/by-puuid/#{escape(puuid)}", region)
+        )
+      end
+
+      def active_shard(game, puuid, region: nil)
+        Models::ActiveShard.from_api(
+          get("/riot/account/v1/active-shards/by-game/#{escape(game)}/by-puuid/#{escape(puuid)}", region)
+        )
+      end
+
+      def region_by_game(game, puuid, region: nil)
+        Models::AccountRegion.from_api(
+          get("/riot/account/v1/region/by-game/#{escape(game)}/by-puuid/#{escape(puuid)}", region)
+        )
+      end
+
+      # Requires the client to be configured with a bearer_token (RSO).
+      def me(region: nil)
+        Models::Account.from_api(get('/riot/account/v1/accounts/me', region))
+      end
+
+      private
+
+      def get(path, region)
+        # account-v1 has no SEA host; normalize it to ASIA.
+        super(path, Routing.regional_for_account(region || @client.region))
+      end
+    end
+  end
+end

data/lib/rito/endpoints/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def get(path, region = nil, params: {})
+        @client.request(:get, path, routing_kind: routing_kind, routing_value: region, params: params).body
+      end
+
+      def post(path, region = nil, params: {}, body: nil)
+        @client.request(:post, path, routing_kind: routing_kind, routing_value: region,
+                                     params: params, body: body).body
+      end
+
+      def put(path, region = nil, params: {}, body: nil)
+        @client.request(:put, path, routing_kind: routing_kind, routing_value: region,
+                                    params: params, body: body).body
+      end
+
+      def routing_kind
+        self.class::ROUTING
+      end
+
+      def escape(segment)
+        ERB::Util.url_encode(segment.to_s)
+      end
+    end
+  end
+end

data/lib/rito/endpoints/lol/challenges_v1.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    module Lol
+      class ChallengesV1 < Base
+        ROUTING = :platform
+
+        def config(region: nil)
+          get('/lol/challenges/v1/challenges/config', region)
+        end
+
+        def percentiles(region: nil)
+          get('/lol/challenges/v1/challenges/percentiles', region)
+        end
+
+        def leaderboard(challenge_id, level, top: nil, page: nil, region: nil)
+          params = {}
+          params['top'] = top if top
+          params['page'] = page if page
+          get("/lol/challenges/v1/challenges/#{escape(challenge_id)}/leaderboards/by-level/#{escape(level)}", region,
+              params: params)
+        end
+
+        def player_data(puuid, region: nil)
+          get("/lol/challenges/v1/player-data/#{escape(puuid)}", region)
+        end
+      end
+    end
+  end
+end

data/lib/rito/endpoints/lol/champion_mastery_v4.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    module Lol
+      class ChampionMasteryV4 < Base
+        ROUTING = :platform
+
+        def for_puuid(puuid, region: nil)
+          get("/lol/champion-mastery/v4/champion-masteries/by-puuid/#{escape(puuid)}", region)
+            .map { |hash| Models::ChampionMastery.from_api(hash) }
+        end
+
+        def for_puuid_and_champion(puuid, champion_id, region: nil)
+          path = "/lol/champion-mastery/v4/champion-masteries/by-puuid/#{escape(puuid)}" \
+                 "/by-champion/#{escape(champion_id)}"
+          Models::ChampionMastery.from_api(get(path, region))
+        end
+
+        def top_for_puuid(puuid, count: nil, region: nil)
+          params = {}
+          params['count'] = count if count
+          get("/lol/champion-mastery/v4/champion-masteries/by-puuid/#{escape(puuid)}/top", region, params: params)
+            .map { |hash| Models::ChampionMastery.from_api(hash) }
+        end
+
+        def score(puuid, region: nil)
+          get("/lol/champion-mastery/v4/scores/by-puuid/#{escape(puuid)}", region)
+        end
+      end
+    end
+  end
+end

data/lib/rito/endpoints/lol/champion_v3.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    module Lol
+      class ChampionV3 < Base
+        ROUTING = :platform
+
+        def rotations(region: nil)
+          Models::ChampionInfo.from_api(
+            get('/lol/platform/v3/champion-rotations', region)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rito/endpoints/lol/clash_v1.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    module Lol
+      class ClashV1 < Base
+        ROUTING = :platform
+
+        def players_by_summoner_id(summoner_id, region: nil)
+          get("/lol/clash/v1/players/by-summoner/#{escape(summoner_id)}", region)
+        end
+
+        def team(team_id, region: nil)
+          get("/lol/clash/v1/teams/#{escape(team_id)}", region)
+        end
+
+        def tournaments(region: nil)
+          get('/lol/clash/v1/tournaments', region)
+        end
+
+        def tournament_by_team(team_id, region: nil)
+          get("/lol/clash/v1/tournaments/by-team/#{escape(team_id)}", region)
+        end
+      end
+    end
+  end
+end

data/lib/rito/endpoints/lol/league_v4.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    module Lol
+      class LeagueV4 < Base
+        ROUTING = :platform
+
+        def challenger(queue, region: nil)
+          Models::LeagueList.from_api(
+            get("/lol/league/v4/challengerleagues/by-queue/#{escape(queue)}", region)
+          )
+        end
+
+        def grandmaster(queue, region: nil)
+          Models::LeagueList.from_api(
+            get("/lol/league/v4/grandmasterleagues/by-queue/#{escape(queue)}", region)
+          )
+        end
+
+        def master(queue, region: nil)
+          Models::LeagueList.from_api(
+            get("/lol/league/v4/masterleagues/by-queue/#{escape(queue)}", region)
+          )
+        end
+
+        def entries_by_summoner_id(summoner_id, region: nil)
+          get("/lol/league/v4/entries/by-summoner/#{escape(summoner_id)}", region)
+            .map { |hash| Models::LeagueEntry.from_api(hash) }
+        end
+
+        def entries(tier, division, page: nil, region: nil)
+          params = {}
+          params['page'] = page if page
+          get("/lol/league/v4/entries/#{escape(tier)}/#{escape(division)}", region, params: params)
+            .map { |hash| Models::LeagueEntry.from_api(hash) }
+        end
+
+        def league(league_id, region: nil)
+          Models::LeagueList.from_api(
+            get("/lol/league/v4/leagues/#{escape(league_id)}", region)
+          )
+        end
+      end
+
+      class LeagueExpV4 < Base
+        ROUTING = :platform
+
+        def entries(queue, tier, division, page: nil, region: nil)
+          params = {}
+          params['page'] = page if page
+          get("/lol/league-exp/v4/entries/#{escape(queue)}/#{escape(tier)}/#{escape(division)}", region, params: params)
+            .map { |hash| Models::LeagueEntry.from_api(hash) }
+        end
+      end
+    end
+  end
+end

data/lib/rito/endpoints/lol/match_v5.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Rito
+  module Endpoints
+    module Lol
+      class MatchV5 < Base
+        ROUTING = :regional
+
+        def by_id(match_id, region: nil)
+          Models::Match.from_api(
+            get("/lol/match/v5/matches/#{escape(match_id)}", region)
+          )
+        end
+
+        def ids_by_puuid(puuid, region: nil, start: nil, count: nil, queue: nil,
+                         type: nil, start_time: nil, end_time: nil)
+          params = {}
+          params['start'] = start if start
+          params['count'] = count if count
+          params['queue'] = queue if queue
+          params['type'] = type if type
+          params['startTime'] = start_time if start_time
+          params['endTime'] = end_time if end_time
+
+          get("/lol/match/v5/matches/by-puuid/#{escape(puuid)}/ids", region, params: params)
+        end
+
+        def timeline_by_id(match_id, region: nil)
+          get("/lol/match/v5/matches/#{escape(match_id)}/timeline", region)
+        end
+      end
+    end
+  end
+end