### Install Clash Royale API Wrapper

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Commands to install the package via yarn or npm.

```shell
yarn add @varandas/clash-royale-api
```

```shell
npm i --save @varandas/clash-royale-api
```

--------------------------------

### GET /leaderboards

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Methods for retrieving leaderboard information.

```APIDOC
## GET /leaderboards

### Description
List available leaderboards or retrieve specific player rankings from a leaderboard.

### Method
GET

### Parameters
#### Path Parameters
- **leaderboardId** (number) - Required - The ID of the leaderboard.

#### Query Parameters
- **params** (ILeaderboardRequestParams) - Optional - Request parameters for leaderboard data.
```

--------------------------------

### GET /players

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Methods for retrieving player profiles, upcoming chests, and battle logs.

```APIDOC
## GET /players

### Description
Retrieve information about a player, their upcoming reward chests, and their recent battle history.

### Method
GET

### Parameters
#### Path Parameters
- **tag** (string) - Required - The unique tag of the player.
```

--------------------------------

### GET /tournaments/{tag}

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Get detailed information about a specific tournament including participants and standings.

```APIDOC
## GET /tournaments/{tag}

### Description
Get detailed information about a specific tournament including participants and standings.

### Method
GET

### Endpoint
/tournaments/{tag}

### Parameters
#### Path Parameters
- **tag** (string) - Required - The tournament tag to retrieve details for.
```

--------------------------------

### GET /tournaments

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Methods for searching and retrieving tournament information.

```APIDOC
## GET /tournaments

### Description
Search for tournaments by name, get details for a specific tournament, or list all global tournaments.

### Method
GET

### Parameters
#### Path Parameters
- **tag** (string) - Required - The unique tag of the tournament.

#### Query Parameters
- **params** (ITournamentRequestParams) - Optional - Search parameters for tournaments.
```

--------------------------------

### GET /tournaments

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Search for tournaments by name with optional pagination parameters.

```APIDOC
## GET /tournaments

### Description
Search for tournaments by name with optional pagination parameters.

### Method
GET

### Endpoint
/tournaments

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the tournament to search for.
- **limit** (integer) - Optional - The maximum number of tournaments to return.
```

--------------------------------

### Get Leaderboards

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Lists all available leaderboards for different trophy roads.

```APIDOC
## GET /leaderboards

### Description
List all available leaderboards for different trophy roads.

### Method
GET

### Endpoint
/leaderboards

### Response
#### Success Response (200)
- **leaderboards** (array) - An array of leaderboard objects, each containing a name, ID, and optionally an icon URL.

#### Response Example
```json
[
  {
    "name": "Trophy Road Leaderboard",
    "id": 1,
    "iconUrl": "http://example.com/icon.png"
  }
]
```
```

--------------------------------

### GET /cards

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Method for retrieving the list of all available cards.

```APIDOC
## GET /cards

### Description
Get a list of all available cards in the game.

### Method
GET
```

--------------------------------

### GET /cards

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves the complete list of all available cards in Clash Royale, including support cards.

```APIDOC
## GET /cards

### Description
Retrieve the complete list of all available cards in Clash Royale, including support cards.

### Method
GET

### Endpoint
/cards

### Response
#### Success Response (200)
- **items** (array) - An array of card objects.
  - **name** (string) - The name of the card.
  - **elixirCost** (integer) - The elixir cost of the card.
  - **rarity** (string) - The rarity of the card (e.g., Common, Rare, Epic, Legendary).
  - **maxLevel** (integer) - The maximum level of the card.
  - **maxEvolutionLevel** (integer, optional) - The maximum evolution level of the card if applicable.
- **supportItems** (array) - An array of support card objects.
  - **name** (string) - The name of the support card.
  - **rarity** (string) - The rarity of the support card.

### Request Example
```javascript
api.getCards()
```

### Response Example
```json
{
  "items": [
    {
      "name": "Knight",
      "elixirCost": 3,
      "rarity": "Common",
      "maxLevel": 14,
      "maxEvolutionLevel": 1
    },
    {
      "name": "Archers",
      "elixirCost": 3,
      "rarity": "Common",
      "maxLevel": 14
    }
  ],
  "supportItems": [
    {
      "name": "Goblin Gang",
      "rarity": "Epic"
    }
  ]
}
```
```

--------------------------------

### GET /locations

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Methods for retrieving location data and rankings.

```APIDOC
## GET /locations

### Description
List locations and retrieve clan, player, or war rankings for specific locations.

### Method
GET

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique ID of the location.

#### Query Parameters
- **params** (ILocationFullRequestParams) - Optional - Request parameters for location details.
```

--------------------------------

### GET /global-tournaments

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves a list of all currently available global tournaments, including their rewards and settings.

```APIDOC
## GET /global-tournaments

### Description
List all currently available global tournaments with their rewards and settings.

### Method
GET

### Endpoint
/global-tournaments

### Response
#### Success Response (200)
- **tournaments** (array) - An array of tournament objects.
  - **title** (string) - The title of the tournament.
  - **tag** (string) - The unique tag of the tournament.
  - **startTime** (string) - The start time of the tournament.
  - **endTime** (string) - The end time of the tournament.
  - **maxLosses** (integer) - The maximum number of losses allowed.
  - **minExpLevel** (integer) - The minimum experience level required.
  - **tournamentLevel** (integer) - The level of the tournament.
  - **milestoneRewards** (array) - An array of milestone reward objects.
    - **wins** (integer) - The number of wins required for the reward.
    - **amount** (integer) - The amount of the reward resource.
    - **resource** (string) - The type of resource rewarded (e.g., Gold, Gems).
    - **chest** (string) - The type of chest rewarded.
  - **topRankReward** (object) - The reward for the top rank.
    - **amount** (integer) - The amount of the reward resource.
    - **resource** (string) - The type of resource rewarded.
    - **chest** (string) - The type of chest rewarded.

### Request Example
```javascript
api.getGlobalTournaments()
```

### Response Example
```json
[
  {
    "title": "Mega Draft Challenge",
    "tag": "#28Q8000",
    "startTime": "2023-10-27T14:00:00.000Z",
    "endTime": "2023-11-03T14:00:00.000Z",
    "maxLosses": 3,
    "minExpLevel": 8,
    "tournamentLevel": 8,
    "milestoneRewards": [
      { "wins": 0, "amount": 100, "resource": "Gold" },
      { "wins": 2, "amount": 50, "resource": "Gold" },
      { "wins": 4, "amount": 1, "chest": "Silver Chest" }
    ],
    "topRankReward": { "amount": 1000, "resource": "Gold" }
  }
]
```
```

--------------------------------

### Get Tournament Details

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves comprehensive information about a specific tournament, including participant standings.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getTournamentByTag('#TOURNEYTAG')
  .then(tournament => {
    console.log(`Tournament started: ${tournament.startedTime}`)
    console.log(`Participants: ${tournament.membersList.length}`)

    console.log('\nTop 10 Standings:')
    tournament.membersList
      .sort((a, b) => a.rank - b.rank)
      .slice(0, 10)
      .forEach(member => {
        console.log(`  ${member.rank}. ${member.name} - Score: ${member.score}`)
        if (member.clan) {
          console.log(`     Clan: ${member.clan.name}`)
        }
      })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Clan Methods

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Methods for retrieving clan information, including searching for clans, getting details of a specific clan, and listing clan members.

```APIDOC
## GET /clans

### Description
Search for clans by name and filter results using various criteria. The name parameter must be at least 3 characters long and performs wildcard matching.

### Method
GET

### Endpoint
`/clans`

### Parameters
#### Query Parameters
- **name** (string) - Required - Clan name (at least 3 characters).
- **locationId** (integer) - Optional - Filter by location ID.
- **minMembers** (integer) - Optional - Minimum number of members.
- **maxMembers** (integer) - Optional - Maximum number of members.
- **minScore** (integer) - Optional - Minimum clan score.
- **limit** (integer) - Optional - Limit the number of results.

### Request Example
```javascript
api.getClans({
  name: 'Warriors',
  locationId: 57000249,
  minMembers: 40,
  maxMembers: 50,
  minScore: 50000,
  limit: 10
})
```

### Response
#### Success Response (200)
An array of clan objects matching the search criteria.

#### Response Example
```json
[
  {
    "name": "Warriors Elite",
    "tag": "#2ABC123",
    "clanScore": 58234,
    "members": 47
  },
  {
    "name": "Warriors United",
    "tag": "#9XYZ789",
    "clanScore": 52100,
    "members": 45
  }
]
```
```

```APIDOC
## GET /clans/{tag}

### Description
Retrieve detailed information about a specific clan using its tag. The library automatically URL-encodes the tag (e.g., #2ABC becomes %232ABC).

### Method
GET

### Endpoint
`/clans/{tag}`

### Parameters
#### Path Parameters
- **tag** (string) - Required - The unique tag of the clan (e.g., '#2ABC123').

### Request Example
```javascript
api.getClanByTag('#2ABC123')
```

### Response
#### Success Response (200)
A clan object with detailed information.

#### Response Example
```json
{
  "name": "Warriors Elite",
  "tag": "#2ABC123",
  "description": "A clan of skilled warriors.",
  "clanScore": 58234,
  "clanWarTrophies": 4500,
  "members": 47,
  "memberList": [
    {
      "name": "Player One",
      "tag": "#P1TAG",
      "role": "Leader",
      "donations": 1000,
      "donationsReceived": 500
    }
    // ... other members
  ]
}
```
```

```APIDOC
## GET /clans/{tag}/members

### Description
Retrieve the list of all members in a clan with their stats, roles, and activity information.

### Method
GET

### Endpoint
`/clans/{tag}/members`

### Parameters
#### Path Parameters
- **tag** (string) - Required - The unique tag of the clan (e.g., '#2ABC123').

### Request Example
```javascript
api.getClanMembers('#2ABC123')
```

### Response
#### Success Response (200)
An array of member objects belonging to the clan.

#### Response Example
```json
[
  {
    "name": "Player One",
    "tag": "#P1TAG",
    "role": "Leader",
    "trophies": 5000,
    "arena": {"name": "Legendary Arena"},
    "donations": 1000,
    "donationsReceived": 500,
    "lastSeen": "2023-10-27T10:00:00.000Z",
    "clanRank": 1,
    "previousClanRank": 1
  }
  // ... other members
]
```
```

--------------------------------

### GET /players/{tag}/battlelog

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves a player's recent battle history with detailed match information.

```APIDOC
## GET /players/{tag}/battlelog

### Description
Retrieve a player's recent battle history with detailed match information.

### Method
GET

### Endpoint
/players/{tag}/battlelog

### Parameters
#### Path Parameters
- **tag** (string) - Required - The player tag to retrieve battle logs for.
```

--------------------------------

### GET /clans

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Methods for retrieving clan information, members, war logs, and current river race status.

```APIDOC
## GET /clans

### Description
Retrieve clan data including lists, specific clan details, members, war logs, and current river race information.

### Method
GET

### Parameters
#### Path Parameters
- **tag** (string) - Required - The unique tag of the clan.

#### Query Parameters
- **params** (IClanRequestParams) - Optional - Filtering parameters for clan lists.
```

--------------------------------

### Get Leaderboard by ID

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves the list of players on a specific leaderboard with optional pagination.

```APIDOC
## GET /leaderboards/{leaderboardId}

### Description
Get the list of players on a specific leaderboard with optional pagination.

### Method
GET

### Endpoint
/leaderboards/{leaderboardId}

### Parameters
#### Path Parameters
- **leaderboardId** (integer) - Required - The ID of the leaderboard.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of players to return.

### Request Example
```javascript
api.getLeaderboardById(1, { limit: 10 })
```

### Response
#### Success Response (200)
- **players** (array) - An array of player objects, each containing rank, name, tag, trophies, level, and optional clan information.

#### Response Example
```json
[
  {
    "rank": 1,
    "name": "Player Name",
    "tag": "#TAG",
    "trophies": 12000,
    "expLevel": 14,
    "clan": {
      "name": "Clan Name",
      "tag": "#CLANTAG"
    }
  }
]
```
```

--------------------------------

### GET /players/{tag}/upcomingchests

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves the list of reward chests that a player will receive next in the game.

```APIDOC
## GET /players/{tag}/upcomingchests

### Description
Get the list of reward chests that a player will receive next in the game.

### Method
GET

### Endpoint
/players/{tag}/upcomingchests

### Parameters
#### Path Parameters
- **tag** (string) - Required - The player tag to retrieve chests for.
```

--------------------------------

### Retrieve Clan Members List

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Get a list of all members in a clan, including their roles, stats, and activity status.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getClanMembers('#2ABC123')
  .then(members => {
    console.log(`Total members: ${members.length}`)

    members.forEach(member => {
      console.log(`${member.name} (${member.tag})`)
      console.log(`  Role: ${member.role}`)
      console.log(`  Trophies: ${member.trophies}`)
      console.log(`  Arena: ${member.arena.name}`)
      console.log(`  Donations: ${member.donations} given, ${member.donationsReceived} received`)
      console.log(`  Last seen: ${member.lastSeen}`)
      console.log(`  Rank: ${member.clanRank} (previous: ${member.previousClanRank})`)
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Location by ID

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves detailed information for a specific location using its unique ID.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getLocationById('57000249')  // United States
  .then(location => {
    console.log(`Location: ${location.name}`)
    console.log(`ID: ${location.id}`)
    console.log(`Is Country: ${location.isCountry}`)
    if (location.countryCode) {
      console.log(`Country Code: ${location.countryCode}`)
    }
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Player Rankings for Location

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves the top player rankings for a specified geographical location.

```APIDOC
## GET /players/rankings/{locationId}

### Description
Get the top player rankings for a specific location.

### Method
GET

### Endpoint
/players/rankings/{locationId}

### Parameters
#### Path Parameters
- **locationId** (string) - Required - The ID of the location for which to retrieve rankings.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of players to return.

### Request Example
```javascript
api.getPlayerRankingsForLocation('57000249', {
  locationId: '57000249',
  limit: 10
})
```

### Response
#### Success Response (200)
- **players** (array) - An array of player objects, each containing details like name, tag, trophies, and level.

#### Response Example
```json
[
  {
    "name": "Player Name",
    "tag": "#TAG",
    "trophies": 10000,
    "expLevel": 14
  }
]
```
```

--------------------------------

### Get Player Profile by Tag

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches comprehensive player data, including battle stats, challenge performance, league statistics, and card collection details. Requires a player's unique tag.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getPlayerByTag('#PLAYERTAG')
  .then(player => {
    console.log(`Player: ${player.name} (${player.tag})`)
    console.log(`Level: ${player.expLevel}`)
    console.log(`Trophies: ${player.trophies} (Best: ${player.bestTrophies})`)
    console.log(`Arena: ${player.arena.name}`)
    console.log(`Clan: ${player.clan.name}`)

    console.log(`\nBattle Stats: `)
    console.log(`  Total Battles: ${player.battleCount}`)
    console.log(`  Wins: ${player.wins}`)
    console.log(`  Losses: ${player.losses}`)
    console.log(`  Three Crown Wins: ${player.threeCrownWins}`)
    console.log(`  War Day Wins: ${player.warDayWins}`)

    console.log(`\nChallenge Stats: `)
    console.log(`  Cards Won: ${player.challengeCardsWon}`)
    console.log(`  Max Wins: ${player.challengeMaxWins}`)

    console.log(`\nLeague Statistics: `)
    console.log(`  Current Season: ${player.leagueStatistics.currentSeason.trophies} trophies`)
    console.log(`  Best Season: ${player.leagueStatistics.bestSeason.trophies} trophies`)

    console.log(`\nFavorite Card: ${player.currentFavouriteCard.name}`)
    console.log(`Total Cards Collected: ${player.cards.length}`)
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Clan War Rankings for Location

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves clan war rankings for a specified geographical location.

```APIDOC
## GET /clans/wars/rankings/{locationId}

### Description
Get clan war rankings for a specific location.

### Method
GET

### Endpoint
/clans/wars/rankings/{locationId}

### Parameters
#### Path Parameters
- **locationId** (string) - Required - The ID of the location for which to retrieve clan war rankings.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of clans to return.

### Request Example
```javascript
api.getClanWarRankingsForLocation('57000249', {
  locationId: '57000249',
  limit: 10
})
```

### Response
#### Success Response (200)
- **clans** (array) - An array of clan objects, each containing details like name, tag, clan score, and number of members.

#### Response Example
```json
[
  {
    "name": "Clan Name",
    "tag": "#CLANTAG",
    "clanScore": 50000,
    "members": 50
  }
]
```
```

--------------------------------

### Clan Current War API

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Get information about a clan's current clan war status.

```APIDOC
## GET /api/clans/{clanTag}/currentwar

### Description
Get information about a clan's current clan war status. When warEndTime is undefined, the war is still in collection phase - use collectionEndTime instead.

### Method
GET

### Endpoint
/api/clans/{clanTag}/currentwar

### Parameters
#### Path Parameters
- **clanTag** (string) - Required - The unique tag of the clan.

### Response
#### Success Response (200)
- **state** (string) - The current state of the war (e.g., 'WarDay', 'Collection').
- **warEndTime** (string) - The end time of the war if in war phase.
- **collectionEndTime** (string) - The end time of the collection phase if in collection phase.
- **clans** (array) - An array of participating clans.
  - **name** (string) - The name of the clan.
  - **wins** (integer) - The number of wins for the clan.
  - **crowns** (integer) - The number of crowns for the clan.
- **participants** (array) - An array of participants in the war.
  - **name** (string) - The name of the participant.
  - **battlesPlayed** (integer) - The number of battles played by the participant.
  - **wins** (integer) - The number of wins by the participant.

### Response Example
```json
{
  "state": "WarDay",
  "warEndTime": "2023-10-28T14:00:00.000Z",
  "clans": [
    {
      "name": "Clan A",
      "wins": 10,
      "crowns": 5
    },
    {
      "name": "Clan B",
      "wins": 8,
      "crowns": 4
    }
  ],
  "participants": [
    {
      "name": "Player1",
      "battlesPlayed": 3,
      "wins": 3
    },
    {
      "name": "Player2",
      "battlesPlayed": 3,
      "wins": 2
    }
  ]
}
```
```

--------------------------------

### Get Leaderboard by ID

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves players on a specific leaderboard, supporting pagination with a limit parameter. Requires a leaderboard ID and API token.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getLeaderboardById(1, { limit: 10 })
  .then(players => {
    console.log('Top 10 Players on Leaderboard:')

    players.forEach(player => {
      const rankChange = player.previousRank
        ? player.previousRank - player.rank
        : 0
      const changeStr = rankChange > 0 ? `(+${rankChange})` :
                        rankChange < 0 ? `(${rankChange})` : ''

      console.log(`
${player.rank}. ${player.name} ${changeStr}`)
      console.log(`   Tag: ${player.tag}`)
      console.log(`   Trophies: ${player.trophies}`)
      console.log(`   Level: ${player.expLevel}`)
      if (player.clan) {
        console.log(`   Clan: ${player.clan.name}`)
      }
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Player Rankings for Location

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches the top player rankings for a specified location. Requires a valid API token and location ID.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getPlayerRankingsForLocation('57000249', {
  locationId: '57000249',
  limit: 10
})
.then(players => {
  console.log('Top 10 Players in United States:')

  players.forEach((player, index) => {
    console.log(`
${index + 1}. ${player.name} (${player.tag})`)
    console.log(`   Trophies: ${player.trophies}`)
    console.log(`   Level: ${player.expLevel}`)
  })
})
.catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Clan Rankings for Location

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches top clan rankings for a specific location ID. Requires location ID and optional parameters.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getClanRankinsForLocation('57000249', {
  locationId: '57000249',
  limit: 10
})
.then(clans => {
  console.log('Top 10 Clans in United States:')

  clans.forEach((clan, index) => {
    console.log(`\n${index + 1}. ${clan.name} (${clan.tag})`)
    console.log(`   Score: ${clan.clanScore}`)
    console.log(`   War Trophies: ${clan.clanWarTrophies}`)
    console.log(`   Members: ${clan.members}`)
  })
})
.catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Clan War Log History

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves the war log history for a specified clan. Useful for analyzing past clan performance and participation.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getClanWarlog('#2ABC123')
  .then(warlog => {
    console.log(`War history entries: ${warlog.length}`)

    warlog.forEach(war => {
      console.log(`\nSeason ${war.seasonId} - ${war.createdDate}`)
      console.log(`Participants: ${war.participants.length}`)

      const topPerformers = war.participants
        .sort((a, b) => b.cardsEarned - a.cardsEarned)
        .slice(0, 3)

      console.log('Top performers:')
      topPerformers.forEach(p => {
        console.log(`  ${p.name}: ${p.wins} wins, ${p.cardsEarned} cards earned`)
      })
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Clan Current War Status

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches the current clan war status for a clan. Provides information on the war state, end times, participating clans, and individual participant stats.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getClanCurrentWar('#2ABC123')
  .then(war => {
    console.log(`War State: ${war.state}`)

    if (war.warEndTime) {
      console.log(`War ends: ${war.warEndTime}`)
    } else if (war.collectionEndTime) {
      console.log(`Collection ends: ${war.collectionEndTime}`)
    }

    console.log('\nParticipating Clans:')
    war.clans.forEach(clan => {
      console.log(`  ${clan.name}: ${clan.wins} wins, ${clan.crowns} crowns`)
    })

    console.log('\nParticipants:')
    war.participants.forEach(p => {
      console.log(`  ${p.name}: ${p.battlesPlayed} battles, ${p.wins} wins`)
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Clan War Rankings for Location

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves clan war rankings for a specific geographical location. Ensure you have an API token and the correct location ID.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getClanWarRankingsForLocation('57000249', {
  locationId: '57000249',
  limit: 10
})
.then(clans => {
  console.log('Top 10 War Clans in United States:')

  clans.forEach((clan, index) => {
    console.log(`
${index + 1}. ${clan.name} (${clan.tag})`)
    console.log(`   Clan Score: ${clan.clanScore}`)
    console.log(`   Members: ${clan.members}`)
  })
})
.catch(err => console.error('Error:', err.message))
```

--------------------------------

### Get Clan Current River Race Progress

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Retrieves details about a clan's current river race, including fame, repair points, and participant performance. Useful for tracking progress during river race events.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getClanCurrentRiverRace('#2ABC123')
  .then(race => {
    console.log(`River Race State: ${race.state}`)
    console.log(`Section Index: ${race.sectionIndex}`)

    console.log(`\nYour Clan: ${race.clan.name}`)
    console.log(`  Fame: ${race.clan.fame}`)
    console.log(`  Repair Points: ${race.clan.repairPoints}`)

    console.log('\nCompeting Clans:')
    race.clans
      .sort((a, b) => b.fame - a.fame)
      .forEach((clan, index) => {
        console.log(`  ${index + 1}. ${clan.name} - Fame: ${clan.fame}`)
      })

    console.log('\nTop Participants:')
    race.clan.participants
      .sort((a, b) => b.fame - a.fame)
      .slice(0, 5)
      .forEach(p => {
        console.log(`  ${p.name}: ${p.fame} fame, ${p.repairPoints} repair points`)
      })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Initialize and Use Clash Royale API

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Demonstrates initializing the API client and fetching data, including an optional configuration for using a proxy server.

```javascript
// Import the package
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

// Initialize the api
const api = new ClashRoyaleAPI('the token you got from the api')

// Use the api to get cards
api
  .getCards()
  .then(cards => {
    // Do something with the cards
  })
  .catch(err => {
    // handle errors
  })

// Using the proxy server (https://proxy.royaleapi.dev/v1)
// Create a key on the the official API and whitelist (include) this IP: 45.79.218.79
// Use https://proxy.royaleapi.dev/v1
const api = new ClashRoyaleAPI(
  'the token you got from the api',
  'https://proxy.royaleapi.dev/v1',
)

// Use the api to get cards
...
```

--------------------------------

### Initialization

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Initialize the ClashRoyaleAPI class with your API token. Optionally, provide a custom base URL to use a proxy server.

```APIDOC
## Initialization

Initialize the ClashRoyaleAPI class with your API token obtained from the official Clash Royale developer portal. Optionally provide a custom base URL to use a proxy server.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

// Basic initialization with API token
const api = new ClashRoyaleAPI('your-api-token-here')

// Using a proxy server (whitelist IP: 45.79.218.79 in your API key)
const apiWithProxy = new ClashRoyaleAPI(
  'your-api-token-here',
  'https://proxy.royaleapi.dev/v1'
)
```
```

--------------------------------

### Initialize ClashRoyaleAPI Client

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Initialize the API client with an authentication token. Optionally specify a custom base URL for proxy server support.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

// Basic initialization with API token
const api = new ClashRoyaleAPI('your-api-token-here')

// Using a proxy server (whitelist IP: 45.79.218.79 in your API key)
const apiWithProxy = new ClashRoyaleAPI(
  'your-api-token-here',
  'https://proxy.royaleapi.dev/v1'
)
```

--------------------------------

### List Available Leaderboards

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches a list of all available leaderboards, useful for identifying which leaderboards can be queried. Requires an API token.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getLeaderboards()
  .then(leaderboards => {
    console.log(`Available Leaderboards: ${leaderboards.length}`)

    leaderboards.forEach(board => {
      console.log(`
${board.name}`)
      console.log(`  ID: ${board.id}`)
      if (board.iconUrl) {
        console.log(`  Icon: ${board.iconUrl}`)
      }
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Handle API Errors with Async/Await

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Demonstrates robust error handling for API requests using async/await and try-catch blocks. It differentiates between network errors and API-specific error responses.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

async function fetchPlayerData(playerTag) {
  try {
    const player = await api.getPlayerByTag(playerTag)
    console.log(`Successfully fetched: ${player.name}`)
    return player
  } catch (error) {
    if (error.response) {
      // API responded with an error
      console.error(`API Error: ${error.response.status}`)
      switch (error.response.status) {
        case 400:
          console.error('Bad request - check your parameters')
          break
        case 403:
          console.error('Access denied - check your API token and IP whitelist')
          break
        case 404:
          console.error('Player not found')
          break
        case 429:
          console.error('Rate limit exceeded - slow down requests')
          break
        case 503:
          console.error('API temporarily unavailable')
          break
      }
    } else if (error.request) {
      console.error('Network error - no response received')
    } else {
      console.error('Error:', error.message)
    }
    throw error
  }
}

// Usage with async/await
(async () => {
  try {
    const player = await fetchPlayerData('#PLAYERTAG')
    console.log(player)
  } catch (error) {
    // Handle or ignore error
  }
})()
```

--------------------------------

### Retrieve All Cards

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches the complete list of cards and support items. Useful for categorizing cards by rarity or checking evolution levels.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getCards()
  .then(response => {
    const { items: cards, supportItems } = response

    console.log(`Total Cards: ${cards.length}`)
    console.log(`Support Cards: ${supportItems.length}`)

    // Group cards by rarity
    const byRarity = cards.reduce((acc, card) => {
      acc[card.rarity] = acc[card.rarity] || []
      acc[card.rarity].push(card)
      return acc
    }, {})

    Object.entries(byRarity).forEach(([rarity, rarityCards]) => {
      console.log(`\n${rarity} Cards (${rarityCards.length}):`)
      rarityCards.forEach(card => {
        console.log(`  ${card.name} - ${card.elixirCost} elixir (Max Level: ${card.maxLevel})`)
        if (card.maxEvolutionLevel) {
          console.log(`    Evolution available (Max: ${card.maxEvolutionLevel})`)
        }
      })
    })

    console.log('\nSupport Cards:')
    supportItems.forEach(card => {
      console.log(`  ${card.name} (${card.rarity})`)
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Leaderboard List Parameters (ILeaderboardRequestParams)

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Parameters for retrieving leaderboard data. Supports limiting the number of results and pagination using 'after' or 'before' markers.

```APIDOC
## Leaderboard List Parameters

### Description
Parameters for retrieving leaderboard data. Supports limiting the number of results and pagination using 'after' or 'before' markers.

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Limit the number of items returned in the response.
- **after** (string) - Optional - Return only items that occur after this marker. Marker can be found in the 'paging' property of the response. Only 'after' or 'before' can be specified.
- **before** (string) - Optional - Return only items that occur before this marker. Marker can be found in the 'paging' property of the response. Only 'after' or 'before' can be specified.
```

--------------------------------

### Error Handling

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Demonstrates how to handle potential errors when making API requests.

```APIDOC
## Error Handling

All API methods return promises and should include proper error handling for network issues and API errors.

### Common Error Codes
- **400 Bad Request**: Check your parameters.
- **403 Forbidden**: Check your API token and IP whitelist.
- **404 Not Found**: Resource not found (e.g., player tag is invalid).
- **429 Too Many Requests**: Rate limit exceeded, slow down requests.
- **503 Service Unavailable**: The API is temporarily unavailable.

### Request Example (JavaScript with async/await)
```javascript
async function fetchPlayerData(playerTag) {
  try {
    const player = await api.getPlayerByTag(playerTag)
    console.log(`Successfully fetched: ${player.name}`)
    return player
  } catch (error) {
    if (error.response) {
      // API responded with an error
      console.error(`API Error: ${error.response.status}`)
      switch (error.response.status) {
        case 400:
          console.error('Bad request - check your parameters')
          break
        case 403:
          console.error('Access denied - check your API token and IP whitelist')
          break
        case 404:
          console.error('Player not found')
          break
        case 429:
          console.error('Rate limit exceeded - slow down requests')
          break
        case 503:
          console.error('API temporarily unavailable')
          break
      }
    } else if (error.request) {
      console.error('Network error - no response received')
    } else {
      console.error('Error:', error.message)
    }
    throw error
  }
}

// Usage with async/await
(async () => {
  try {
    const player = await fetchPlayerData('#PLAYERTAG')
    console.log(player)
  } catch (error) {
    // Handle or ignore error
  }
})()
```
```

--------------------------------

### Tournament Search Parameters (ITournamentRequestParams)

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Defines parameters for searching tournaments. The 'name' parameter is required. Pagination parameters 'limit', 'after', and 'before' are also available.

```APIDOC
## Tournament Search Parameters

### Description
Parameters for searching tournaments. The 'name' property is required. Pagination parameters 'limit', 'after', and 'before' are also available.

### Parameters
#### Query Parameters
- **name** (string) - Required - Search tournaments by name.
- **limit** (number) - Optional - Limit the number of items returned in the response.
- **after** (number) - Optional - Return only items that occur after this marker. Marker can be found in the 'paging' property of the response. Only 'after' or 'before' can be specified.
- **before** (number) - Optional - Return only items that occur before this marker. Marker can be found in the 'paging' property of the response. Only 'after' or 'before' can be specified.
```

--------------------------------

### Retrieve Locations

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Lists available countries and regions. Supports pagination via the params object.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getLocations({ limit: 50 })
  .then(locations => {
    console.log(`Available Locations: ${locations.length}`)

    // Filter countries only
    const countries = locations.filter(loc => loc.isCountry)
    const regions = locations.filter(loc => !loc.isCountry)

    console.log(`\nCountries (${countries.length}):`)
    countries.forEach(location => {
      console.log(`  ${location.name} (${location.countryCode}) - ID: ${location.id}`)
    })

    console.log(`\nRegions (${regions.length}):`)
    regions.forEach(location => {
      console.log(`  ${location.name} - ID: ${location.id}`)
    })
  })
  .catch(err => console.error('Error:', err.message))
```

--------------------------------

### Clan Search Parameters (IClanRequestParams)

Source: https://github.com/andrevarandas/clash-royale-api/blob/master/README.md

Defines the parameters for searching clans. The 'name' parameter is required and supports wildcard searches. Other parameters allow filtering by location, member count, score, and pagination.

```APIDOC
## Clan Search Parameters

### Description
Parameters for searching clans. The 'name' property is required and supports wildcard searches. Other parameters allow filtering by location, member count, score, and pagination.

### Parameters
#### Query Parameters
- **name** (string) - Required - Search clans by name. Must be at least three characters long and can appear anywhere in the clan name.
- **locationId** (number) - Optional - Filter by clan location identifier. Refer to `getLocations` operation for a list of available locations.
- **minMembers** (number) - Optional - Filter by minimum amount of clan members.
- **maxMembers** (number) - Optional - Filter by maximum amount of clan members.
- **minScore** (number) - Optional - Filter by minimum amount of clan score.
- **limit** (number) - Optional - Limit the number of items returned in the response.
- **after** (number) - Optional - Return only items that occur after this marker. Marker can be found in the 'paging' property of the response. Only 'after' or 'before' can be specified.
- **before** (number) - Optional - Return only items that occur before this marker. Marker can be found in the 'paging' property of the response. Only 'after' or 'before' can be specified.
```

--------------------------------

### Retrieve Player Battle Log

Source: https://context7.com/andrevarandas/clash-royale-api/llms.txt

Fetches recent match history for a player, including deck information and match results.

```javascript
const { ClashRoyaleAPI } = require('@varandas/clash-royale-api')

const api = new ClashRoyaleAPI('your-api-token')

api.getPlayerBattleLog('#PLAYERTAG')
  .then(battles => {
    console.log(`Recent Battles: ${battles.length}`)

    battles.slice(0, 5).forEach(battle => {
      const player = battle.team[0]
      const opponent = battle.opponent[0]
      const result = player.crowns > opponent.crowns ? 'WIN' :
                     player.crowns < opponent.crowns ? 'LOSS' : 'DRAW'

      console.log(`\n${battle.type} - ${battle.gameMode.name}`)
      console.log(`  Result: ${result}`)
      console.log(`  Score: ${player.crowns} - ${opponent.crowns}`)
      console.log(`  Trophy Change: ${player.trophyChange > 0 ? '+' : ''}${player.trophyChange}`)
      console.log(`  Arena: ${battle.arena.name}`)
      console.log(`  Time: ${battle.battleTime}`)
      console.log(`  Opponent: ${opponent.name} (${opponent.clan?.name || 'No Clan'})`)

      console.log(`  Your Deck:`)
      player.cards.forEach(card => {
        console.log(`    - ${card.name} (Level ${card.level})`)
      })
    })
  })
  .catch(err => console.error('Error:', err.message))
```