riotskillissue 1.1.4__tar.gz → 1.2.0__tar.gz

{riotskillissue-1.1.4 → riotskillissue-1.2.0}/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-10-26
+
+### Added
+
+- Replay listing and downloads through `riotskillissue-cli replays`. Use
+  `--player "GameName#TagLine"` with a running League Client to select another
+  player's replay, or an RSO token for the authenticated player's public API
+  replay list. Supports interactive selection, explicit output paths, and
+  opt-in replacement of existing files.
+- `LeagueReplayClient` for local player lookup, recent matches, and replay
+  downloads. Uses the client's replay folder and follows its download limits
+  without retrying rejected download requests.
+- Async and sync `lol.replays()` and `lol.download_replay()` helpers with streamed
+  downloads, temporary-file cleanup, and credential-free file requests.
+- Replay documentation covering League Client and RSO setup, CLI and Python
+  usage, and download limits.
+
+### Upgrade
+
+```bash
+python -m pip install --upgrade riotskillissue
+riotskillissue-cli replays download --player "GameName#TagLine"
+```
+
+### Compatibility
+
+- Player mode requires a signed-in League Client on the same Windows or macOS
+  machine, with the target match accessible on the client's current region.
+  Riot enforces the current [10-downloads-per-hour limit](https://www.leagueoflegends.com/en-ph/news/game-updates/league-of-legends-patch-26-21-notes/).
+  The [League Client API](https://developer.riotgames.com/docs/lol#league-client-api)
+  is unsupported by Riot and may change between patches.
+- Public API replay requests require an RSO token from an approved integration
+  and return replays for the player identified by that token. They do not
+  provide arbitrary player-name or match-ID lookup.
+- Automated tests cover the client workflow with mocked API responses. A replay
+  download from a live League 26.21 client has not been verified.
+
+## [1.1.5] - 2026-10-26
+
+### Changed
+
+## Added Endpoints
+- /lol/match/v5/matches/replays
+
+## Removed Endpoints
+- /lol/match/v5/matches/by-puuid/{puuid}/replays
+
+## Other Changes
+- info.version: "bca08c6737245decb570e82447491f77fee83d38" -> "f11a6ec7a4e117eac0a1997e9bda89bd6a5d52bf"
+- info.x-hash: "bca08c6737245decb570e82447491f77fee83d38a2591954004b70b6d1909828f157d9a4acf6cff8" -> "f11a6ec7a4e117eac0a1997e9bda89bd6a5d52bfa2591954004b70b6d1909828f157d9a4acf6cff8"
+
+
 ## [1.1.4] - 2026-10-06
 
 ### Changed
@@ -343,6 +395,7 @@ natural-language game analysis instead of returning disconnected API payloads.
 - **Pagination**: Async iterator `paginate()` for paginated endpoints.
 - **Static**: `DataDragonClient` for fetching versions and assets.
 
+[1.2.0]: https://github.com/Demoen/riotskillissue/compare/v1.1.5...v1.2.0
 [1.1.2]: https://github.com/Demoen/riotskillissue/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/Demoen/riotskillissue/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/Demoen/riotskillissue/compare/v1.0.0...v1.1.0

{riotskillissue-1.1.4 → riotskillissue-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: riotskillissue
-Version: 1.1.4
+Version: 1.2.0
 Summary: Typed Python client and local MCP server for Riot Games APIs.
 Project-URL: Homepage, https://github.com/Demoen/riotskillissue
 Project-URL: Repository, https://github.com/Demoen/riotskillissue
@@ -70,10 +70,11 @@ Description-Content-Type: text/markdown
 
 ## Install
 
-RiotSkillIssue 1.x requires Python `>=3.14,<3.17`, covering Python 3.14,
-3.15, and 3.16. As of July 2026, CI gates releases on Python 3.14 and the
-current Python 3.15 prerelease. Python 3.16 is still in development, so it is
-covered by a non-blocking nightly compatibility probe until its stable release.
+RiotSkillIssue 1.x requires Python `>=3.14,<3.17`. CI tests Python 3.14 and
+3.15 on Linux and Windows, and release verification checks both versions.
+A separate Python 3.16-dev compatibility probe runs when its dependencies can
+be installed; unavailable upstream dependencies are reported without failing
+that probe.
 
 ```bash
 pip install riotskillissue
@@ -111,6 +112,35 @@ with SyncRiotClient(default_route=PlatformRoute.EUW1) as riot:
     print(riot.lol.player_profile("Player#EUW"))
 ```
 
+## Replay downloads
+
+Open the League Client and sign in, then choose a replay from another player's
+recent matches using their full Riot ID:
+
+```bash
+riotskillissue-cli replays list --player "GameName#TagLine"
+riotskillissue-cli replays download --player "GameName#TagLine"
+```
+
+For a direct selection and an explicit destination:
+
+```bash
+riotskillissue-cli replays download 1 --player "GameName#TagLine" --output ./replays/my-game.rofl
+```
+
+This requires League running on the same Windows or macOS machine, with the
+target match accessible on the client's region. No API key or RSO token is
+needed. Riot's limit of 10 downloads per hour applies through the client. The
+League Client API is not officially supported by Riot and may change between
+patches.
+
+The public API workflow remains available by omitting `--player` and setting
+`RIOT_RSO_ACCESS_TOKEN`. It returns replays for that token's player. Python
+applications can use `LeagueReplayClient` for player lookups or the async/sync
+`lol.replays()` and `lol.download_replay()` RSO helpers. See the
+[replay guide](https://demoen.github.io/riotskillissue/replays/) for client setup,
+RSO authentication, limits, and examples.
+
 ## Local MCP server
 
 Install the optional server and run it over stdio:

{riotskillissue-1.1.4 → riotskillissue-1.2.0}/README.md

@@ -18,10 +18,11 @@
 
 ## Install
 
-RiotSkillIssue 1.x requires Python `>=3.14,<3.17`, covering Python 3.14,
-3.15, and 3.16. As of July 2026, CI gates releases on Python 3.14 and the
-current Python 3.15 prerelease. Python 3.16 is still in development, so it is
-covered by a non-blocking nightly compatibility probe until its stable release.
+RiotSkillIssue 1.x requires Python `>=3.14,<3.17`. CI tests Python 3.14 and
+3.15 on Linux and Windows, and release verification checks both versions.
+A separate Python 3.16-dev compatibility probe runs when its dependencies can
+be installed; unavailable upstream dependencies are reported without failing
+that probe.
 
 ```bash
 pip install riotskillissue
@@ -59,6 +60,35 @@ with SyncRiotClient(default_route=PlatformRoute.EUW1) as riot:
     print(riot.lol.player_profile("Player#EUW"))
 ```
 
+## Replay downloads
+
+Open the League Client and sign in, then choose a replay from another player's
+recent matches using their full Riot ID:
+
+```bash
+riotskillissue-cli replays list --player "GameName#TagLine"
+riotskillissue-cli replays download --player "GameName#TagLine"
+```
+
+For a direct selection and an explicit destination:
+
+```bash
+riotskillissue-cli replays download 1 --player "GameName#TagLine" --output ./replays/my-game.rofl
+```
+
+This requires League running on the same Windows or macOS machine, with the
+target match accessible on the client's region. No API key or RSO token is
+needed. Riot's limit of 10 downloads per hour applies through the client. The
+League Client API is not officially supported by Riot and may change between
+patches.
+
+The public API workflow remains available by omitting `--player` and setting
+`RIOT_RSO_ACCESS_TOKEN`. It returns replays for that token's player. Python
+applications can use `LeagueReplayClient` for player lookups or the async/sync
+`lol.replays()` and `lol.download_replay()` RSO helpers. See the
+[replay guide](https://demoen.github.io/riotskillissue/replays/) for client setup,
+RSO authentication, limits, and examples.
+
 ## Local MCP server
 
 Install the optional server and run it over stdio:

{riotskillissue-1.1.4 → riotskillissue-1.2.0}/docs/CONTRIBUTING.md

@@ -123,16 +123,16 @@ Generated files:
 1. Bump the version in `pyproject.toml` and move the completed changes from
    `Unreleased` into a dated `CHANGELOG.md` release section. Remove an empty
    `Unreleased` section and update the comparison links at the end of the file.
-2. Run the quality checks from CI and validate the release metadata. For 1.1.2:
+2. Run the quality checks from CI and validate the release metadata. For 1.2.0:
 
    ```bash
-   python tools/release.py --tag v1.1.2
-   hatch build dist/1.1.2
-   python tools/release.py --tag v1.1.2 --notes-output dist/1.1.2/RELEASE_NOTES.md
+   python tools/release.py --tag v1.2.0
+   hatch build dist/1.2.0
+   python tools/release.py --tag v1.2.0 --notes-output dist/1.2.0/RELEASE_NOTES.md
    ```
 
 3. Review and commit the prepared changes, then tag that commit with the exact
-   version (`v1.1.2`). Pushing the tag starts `.github/workflows/publish.yml`.
+   version (`v1.2.0`). Pushing the tag starts `.github/workflows/publish.yml`.
 4. The workflow checks the tag/version match, requires release notes, and verifies
    Python 3.14 and 3.15 before publishing to PyPI using Trusted Publishing. The
    GitHub release uses the reviewed changelog entry and contains the built

{riotskillissue-1.1.4 → riotskillissue-1.2.0}/docs/api-reference.md

@@ -115,7 +115,7 @@ as the raw clients and registry.
 | Operation ID | Python accessor | Method | Route | Auth | Result |
 | --- | --- | --- | --- | --- | --- |
 | `match-v5.getMatchIdsByPUUID` | `riot.raw.lol.match.get_match_ids_by_puuid` | GET | regional | api_key | `List[str]` |
-| `match-v5.getReplay` | `riot.raw.lol.match.get_replay` | GET | regional | api_key | `Replay` |
+| `match-v5.getReplayByAccessToken` | `riot.raw.lol.match.get_replay_by_access_token` | GET | regional | rso | `Replay` |
 | `match-v5.getMatch` | `riot.raw.lol.match.get_match` | GET | regional | api_key | `Match` |
 | `match-v5.getTimeline` | `riot.raw.lol.match.get_timeline` | GET | regional | api_key | `Timeline` |
 

{riotskillissue-1.1.4 → riotskillissue-1.2.0}/docs/cli.md

@@ -1,6 +1,6 @@
 # Command Line Interface
 
-Look up a League player, inspect a match, or open the live-game dashboard from your terminal. The CLI prints a focused summary; use the [Python client](getting-started.md) or [MCP server](mcp.md) for richer results.
+Look up a League player, inspect a match, download an available replay, or open the live-game dashboard from your terminal. Use the [Python client](getting-started.md) or [MCP server](mcp.md) to process richer results.
 
 ## Installation
 
@@ -20,7 +20,7 @@ See [getting started](getting-started.md) for supported Python versions.
 
 ## Configuration
 
-Set `RIOT_API_KEY` in the terminal where you will run the command:
+For `summoner`, `match`, and `live`, set `RIOT_API_KEY` in the terminal where you will run the command:
 
 === "macOS / Linux"
 
@@ -40,10 +40,12 @@ Set `RIOT_API_KEY` in the terminal where you will run the command:
     set RIOT_API_KEY=RGAPI-your-key-here
     ```
 
-Every command also accepts `--api-key`. The environment variable keeps the key out of the command itself.
+These commands also accept `--api-key`. The environment variable keeps the key out of the command itself.
+
+With `--player "GameName#TagLine"`, the `replays` commands connect to your running, logged-in League Client on Windows or macOS. No API key or RSO token is needed. Without `--player`, they use `RIOT_RSO_ACCESS_TOKEN` or `--access-token` from an approved Riot Sign On integration. See the [replay guide](replays.md) for both workflows.
 
 !!! tip "Choose the right route"
-    `summoner` and `live` use a **platform route**, such as `euw1`. `match` uses a **regional route**, such as `europe`. See [routing](routing.md) for how the families relate.
+    `summoner` and `live` use a **platform route**, such as `euw1`. `match` and RSO replay requests use a **regional route**, such as `europe`. Replay requests with `--player` use the League Client's current region. See [routing](routing.md) for how the families relate.
 
 ## Commands
 
@@ -52,6 +54,8 @@ Every command also accepts `--api-key`. The environment variable keeps the key o
 | [`summoner`](#summoner) | Player level and PUUID | `euw1` |
 | [`match`](#match) | Game mode and duration | `europe` |
 | [`live`](#live) | Interactive live-game dashboard | `euw1` |
+| [`replays list`](#replays) | A player's recent matches or the RSO replay list | Client region with `--player`; otherwise `europe` |
+| [`replays download`](#replays) | A selected replay saved to a local `.rofl` file | Client region with `--player`; otherwise `europe` |
 
 Run `riotskillissue-cli --help` to list commands, or append `--help` to a command to inspect its options.
 
@@ -106,6 +110,42 @@ The dashboard shows teams, champions, summoner spells, ranked records, and bans.
 
 Press `r` to refresh, or `q` / `Esc` to quit. The [`tui` extra](#installation) is required. See the [TUI guide](live-game-tui.md) for previews, controls, and refresh behavior.
 
+### replays
+
+Open League, sign in, and look up another player's recent matches by full Riot
+ID:
+
+```bash
+riotskillissue-cli replays list --player "GameName#TagLine"
+riotskillissue-cli replays download --player "GameName#TagLine"
+```
+
+`download` prompts for a one-based selection from the list it just fetched. To
+select an entry directly and set the destination:
+
+```bash
+riotskillissue-cli replays download 1 --player "GameName#TagLine" --output ./replays/my-game.rofl
+```
+
+Player mode needs the League Client running on the same Windows or macOS
+machine. It uses the client's replay folder by default; `--output` copies the
+completed file elsewhere. Riot's download limit applies, including downloads
+started through the client UI. Use `--lockfile` for a custom installation and
+`--count` to show between 1 and 20 recent matches.
+
+For the public API workflow, set `RIOT_RSO_ACCESS_TOKEN` and omit `--player`:
+
+```bash
+riotskillissue-cli replays list --route europe
+riotskillissue-cli replays download --route europe
+```
+
+That endpoint returns replays for the token's player and has no player-name or
+match-ID lookup. Neither workflow needs a Riot API key. Existing `--output`
+files are preserved unless you pass `--overwrite`. See the [replay guide](replays.md)
+for client requirements, RSO authentication, selection behavior, options, and
+Python examples.
+
 ## Error Handling
 
 | Symptom | What to check |
@@ -116,5 +156,6 @@ Press `r` to refresh, or `q` / `Esc` to quit. The [`tui` extra](#installation) i
 | Player or match not found | Check the identifier and the command's route family. |
 | Live command cannot import Textual | Install `"riotskillissue[tui]"` in the same environment as the CLI. |
 | Live dashboard shows previous or partial data | Read the status bar and the [TUI troubleshooting guide](live-game-tui.md#troubleshooting). |
+| Replay token, selection, or download error | Follow the [replay troubleshooting guide](replays.md#troubleshooting). |
 
 To process results in your own application, start with the [Python client](getting-started.md) and [game examples](examples/index.md).

riotskillissue-1.2.0/docs/replays.md

@@ -0,0 +1,341 @@
+# Replay downloads
+
+Download a League of Legends replay by player name through your running League
+Client, or use Riot Sign On to download replays returned by the public API.
+Both workflows are included in the base package.
+
+To choose one of another player's recent matches, open League, sign in, and run:
+
+```bash
+riotskillissue-cli replays download --player "GameName#TagLine"
+```
+
+Use the full Riot ID, including the tag. The command shows recent matches and
+asks which replay to download. This mode needs neither a Riot API key nor an
+RSO token.
+
+| Mode | Requirements | Replay source |
+| --- | --- | --- |
+| `--player "GameName#TagLine"` | Logged-in League Client on the same Windows or macOS machine | The named player's matches accessible to that client |
+| Without `--player` | An access token from an approved RSO integration | Replays returned for the player identified by the token |
+
+## Download by player name
+
+Keep the League Client running while using these commands. The target player
+and match must be accessible on the client's current region. `--route` is an
+RSO-only option and cannot be combined with `--player`.
+
+To inspect up to 20 recent matches:
+
+```bash
+riotskillissue-cli replays list --player "GameName#TagLine"
+```
+
+The table shows the selection number, match ID, queue, and patch. Recent matches
+can include unavailable replays; the client checks the selected replay when you
+request a download.
+
+For interactive selection from a smaller list:
+
+```bash
+riotskillissue-cli replays download --player "GameName#TagLine" --count 5
+```
+
+Or select a one-based entry directly:
+
+```bash
+riotskillissue-cli replays download 1 --player "GameName#TagLine"
+```
+
+The League Client downloads the selected replay into its configured replay
+folder. The CLI waits for completion and prints the resulting path. To keep a
+copy somewhere else:
+
+```bash
+riotskillissue-cli replays download 1 --player "GameName#TagLine" --output ./replays/game.rofl
+```
+
+`--output` copies the completed replay to that file without changing the League
+Client's settings. Missing parent directories are created. An existing output
+file is preserved unless you pass `--overwrite`, and a failed copy leaves no
+partially written destination.
+
+| Argument or option | Default | Meaning |
+| --- | --- | --- |
+| `--player` | Not set | Full `GameName#TagLine` Riot ID; enables the League Client workflow |
+| `INDEX` | Interactive selection | One-based row to download; `download` only |
+| `--count` | `20` | Recent matches to list, from `1` to `20`; player mode only |
+| `--lockfile` | `RIOT_LCU_LOCKFILE`, then automatic discovery | Path to the running League Client's lockfile |
+| `--timeout` | `120` | Seconds to wait for local download completion, from `1` to `600`; `download` only |
+| `--output` | League Client's replay folder | Copy the completed replay to this file; `download` only |
+| `--overwrite` | Off | Replace an existing `--output` file after a successful copy |
+
+`--lockfile`, `--count`, and `--timeout` apply only when `--player` is set.
+
+The list is fetched anew for each invocation. Its order may change between
+`list` and `download 1`. Omit the index to choose from the exact list that the
+download command will use. The number is a row selection, not a match ID.
+
+!!! note "League Client API compatibility"
+    This workflow uses the local
+    [League Client API](https://developer.riotgames.com/docs/lol#league-client-api).
+    Riot does not officially support it for third-party applications or
+    guarantee compatibility between patches. Replay access remains subject to
+    the current client's availability checks and server responses.
+
+## Find your League client
+
+The CLI checks these standard lockfile locations:
+
+| Platform | Location |
+| --- | --- |
+| Windows | `C:/Riot Games/League of Legends/lockfile` |
+| macOS | `/Applications/League of Legends.app/Contents/LoL/lockfile` |
+| macOS, per-user installation | `~/Applications/League of Legends.app/Contents/LoL/lockfile` |
+
+On Windows, the drive comes from `SYSTEMDRIVE`, normally `C:`.
+
+For a custom installation, pass the exact path or set `RIOT_LCU_LOCKFILE`:
+
+```powershell
+riotskillissue-cli replays list --player "GameName#TagLine" --lockfile "D:/Riot Games/League of Legends/lockfile"
+```
+
+The lockfile is created by the running League Client and contains local
+connection credentials. Use the file on your own machine; do not copy it from
+another player or commit it to a repository. Run the command in the same Windows
+or macOS environment as League, rather than a remote server, container, or WSL.
+
+## Download limits
+
+Riot's
+[Patch 26.21 notes](https://www.leagueoflegends.com/en-ph/news/game-updates/league-of-legends-patch-26-21-notes/),
+published on October 20, 2026, retain downloads of your own, friends', and other
+players' replays with a limit of **10 downloads per hour**.
+
+Player mode asks your League Client to download the replay and follows its
+server-enforced limit, including downloads started through the client UI. The
+CLI downloads one selected replay per invocation. It does not retry rejected
+download requests or invent a local count of remaining downloads. If Riot
+rejects a download, wait for the reported interval where available before trying
+again.
+
+That client announcement does not specify the public API's replay quota. The
+RSO workflow below also respects rate-limit responses.
+
+## What the endpoint supports
+
+Without `--player`, RiotSkillIssue uses the public endpoint
+[`match-v5.getReplayByAccessToken`](https://developer.riotgames.com/apis#match-v5/GET_getReplayByAccessToken):
+
+```text
+GET https://{route}.api.riotgames.com/lol/match/v5/matches/replays
+Authorization: Bearer <RSO access token>
+```
+
+The response contains `total` and `matchFileURLs`. It lists replays for the
+player identified by the access token. The endpoint has no Riot ID, PUUID,
+match-ID, or pagination parameter. The CLI can download files from that list;
+this RSO mode cannot look up another player's replay by name or match ID.
+Use [player mode](#download-by-player-name) for a lookup through your local
+League Client.
+
+## Authentication
+
+These requirements apply to the public API workflow, without `--player`.
+Player mode uses the running League Client instead.
+
+[Riot's RSO integration guide](https://developer.riotgames.com/docs/lol#rso-integration)
+requires an approved production-key application and RSO onboarding. The player
+then signs in through Riot's authorization flow. The replay operation requires
+the `openid` scope.
+
+RiotSkillIssue provides [RSO helpers](rso.md) for applications that already have
+that integration. The CLI accepts an existing access token; it does not register
+an application, run a browser login, or extract tokens from the League client.
+
+Set the token in the terminal where you will run the replay commands:
+
+=== "macOS / Linux"
+
+    ```bash
+    export RIOT_RSO_ACCESS_TOKEN="your-rso-access-token"
+    ```
+
+=== "Windows PowerShell"
+
+    ```powershell
+    $env:RIOT_RSO_ACCESS_TOKEN = "your-rso-access-token"
+    ```
+
+Both commands also accept `--access-token`. Using the environment variable keeps
+the token out of the replay command's arguments. Treat access tokens and signed
+download URLs as credentials. No `RIOT_API_KEY` is needed for these commands.
+
+## List available replays
+
+With an RSO token configured, list the authenticated player's public API replays:
+
+```bash
+riotskillissue-cli replays list --route europe
+```
+
+The table shows a one-based selection number and a suggested filename. The CLI
+does not print the signed download URLs. Choose the regional route that holds
+the player's replays: `americas`, `asia`, `europe`, or `sea`. The default is
+`europe`; platform routes such as `euw1` are not accepted here.
+
+Riot returns URLs without separate match metadata. A filename is inferred when
+the URL contains a usable name; otherwise the command supplies a fallback.
+Do not assume every row includes a match ID, date, champion, or game mode.
+
+## Download a replay
+
+For an interactive selection from the RSO replay list, run:
+
+```bash
+riotskillissue-cli replays download --route europe
+```
+
+The command fetches the list and asks which entry to download. It downloads
+from that same list, so the selected number refers to the row you just saw.
+
+To select a number directly and choose a destination:
+
+```bash
+riotskillissue-cli replays download 1 --route europe --output ./replays/my-game.rofl
+```
+
+Each command fetches the current list. Its order and contents may change between
+a separate `list` call and `download 1`; use interactive selection when you want
+to inspect the exact list being used. Numbers start at **1** and are not match
+IDs.
+
+| Argument or option | Default | Meaning |
+| --- | --- | --- |
+| `INDEX` | Interactive selection | One-based entry in the current list; `download` only |
+| `--route` | `europe` | `americas`, `asia`, `europe`, or `sea` |
+| `--access-token` | `RIOT_RSO_ACCESS_TOKEN` | RSO access token |
+| `--output` | Suggested filename in the current directory | Destination file; `download` only |
+| `--overwrite` | Off | Replace an existing destination after a successful download |
+
+Files are streamed to disk, and missing parent directories are created. The
+destination is published only after the transfer completes; a failed transfer
+cleans up its temporary file and preserves any existing destination. To replace
+a file deliberately:
+
+```bash
+riotskillissue-cli replays download 1 --output ./replays/my-game.rofl --overwrite
+```
+
+The command downloads one file per invocation and does not retry file downloads
+automatically. If the server limits requests, wait before trying again. Run
+`riotskillissue-cli replays download --help` for the installed version's options.
+
+## Use from Python
+
+### League Client
+
+Use `LeagueReplayClient` as an async context manager while League is running:
+
+```python
+import asyncio
+
+from riotskillissue import LeagueReplayClient
+
+
+async def main() -> None:
+    async with LeagueReplayClient() as league:
+        replays = await league.player_replays("GameName#TagLine", count=5)
+        if replays:
+            path = await league.download_replay(replays[0], timeout=120)
+            print(path)
+
+
+asyncio.run(main())
+```
+
+`player_replays()` returns `list[ClientReplay]` for the named player's recent
+matches. Pass a `destination` to `download_replay()` to copy the completed replay
+to another file; omit it to use the League Client's replay folder. The method
+returns a `pathlib.Path` and accepts `overwrite=True` for replacing an explicit
+destination. This client does not use `RiotClient`, an API key, or an RSO token.
+
+### Public API with RSO
+
+The async and sync Riot clients expose the same RSO workflow. Both examples read
+`RIOT_RSO_ACCESS_TOKEN` from the environment.
+
+=== "Async"
+
+    ```python
+    import asyncio
+
+    from riotskillissue import RegionalRoute, RiotClient
+
+
+    async def main() -> None:
+        async with RiotClient() as riot:
+            replays = await riot.lol.replays(route=RegionalRoute.EUROPE)
+            for replay in replays:
+                print(replay.index, replay.filename)
+            if replays:
+                path = await riot.lol.download_replay(
+                    replays[0], "replays/my-game.rofl"
+                )
+                print(path)
+
+
+    asyncio.run(main())
+    ```
+
+=== "Sync"
+
+    ```python
+    from riotskillissue import RegionalRoute, SyncRiotClient
+
+    with SyncRiotClient() as riot:
+        replays = riot.lol.replays(route=RegionalRoute.EUROPE)
+        if replays:
+            path = riot.lol.download_replay(replays[0], "replays/my-game.rofl")
+            print(path)
+    ```
+
+`replays()` returns `list[ReplayFile]`. Each entry has `index`, `filename`, and
+`url`; the URL is omitted from the object's representation. `download_replay()`
+returns a `pathlib.Path` and accepts `overwrite=True` for explicit replacement.
+Keep returned entries only as long as needed to download them, since signed
+URLs may expire.
+
+When embedding the client in an application, keep HTTP request logging disabled
+for replay downloads: `httpx` INFO logs and `httpcore` debug logs can include
+signed URLs. The CLI does not enable that logging.
+
+For applications that need the unmodified response, the generated method remains
+available:
+
+```python
+replay_data = await riot.raw.lol.match.get_replay_by_access_token(
+    route=RegionalRoute.EUROPE,
+)
+```
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| League Client not found | Open League and sign in. For a custom installation, pass `--lockfile` or set `RIOT_LCU_LOCKFILE`. |
+| Player not found | Supply the full Riot ID, including `#TagLine`, and check that the player is accessible from the League Client's current region. |
+| Match listed but replay unavailable | A match-history entry does not guarantee that Riot still offers its replay. The client may reject older or otherwise unavailable replays. |
+| Local download timed out | Keep League open and check its download status. Increase `--timeout` if the transfer is slow; the timeout does not cancel the client's download. |
+| Missing RSO access token | For commands without `--player`, set `RIOT_RSO_ACCESS_TOKEN`; an `RGAPI-...` API key cannot replace it. |
+| RSO unauthorized or forbidden | Obtain a current token through your approved RSO integration and verify the player's authorization. |
+| No RSO replays returned | Check the regional route and the replays available to the authenticated player. |
+| Invalid selection | Select a number from the current list, starting at `1`, or omit it to choose interactively. |
+| Destination already exists | Choose another `--output` path or use `--overwrite`. |
+| Download expired or unavailable | Fetch a fresh list and retry the selection. A replay may no longer be available. |
+| Rate limited | Wait for the reported retry interval where available; do not repeatedly request the same download. |
+| RSO transfer interrupted | Retry once the connection is stable. Incomplete downloads are not kept as completed replay files. |
+
+Downloaded `.rofl` files are game replays, not video exports. Downloading a file
+does not launch League or convert it to another format.