Struct etternaonline_api::v2::Session

pub struct Session { /* fields omitted */ }

EtternaOnline API session client, handles all requests to and from EtternaOnline.

This wrapper keeps care of expiring tokens by automatically logging back in when the login token expires.

This session has rate-limiting built-in. Please do make use of it - the EO server is brittle and funded entirely by donations.

Initialize a session using Session::new_from_login

Example

let mut session = Session::new_from_login(
	"<USERNAME>".into(),
	"<PASSWORD>".into(),
	"<CLIENT_DATA>".into(),
	std::time::Duration::from_millis(2000), // Wait 2s inbetween requests
	None, // No request timeout
)?;

println!("Details about kangalioo: {:?}", session.user_details("kangalioo")?);

let best_score = &session.user_top_10_scores("kangalioo")?[0];
println!(
	"kangalioo's best score has {} misses",
	session.score_data(&best_score.scorekey)?.judgements.misses
);

Implementations

impl Session

pub fn new_from_login(
    username: String,
    password: String,
    client_data: String,
    cooldown: Duration,
    timeout: Option<Duration>
) -> Result<Self, Error>

Initiate a new session by logging in using the specified credentials and API token.

Rate-limiting is done by waiting at least rate_limit inbetween requests

Errors

• Error::InvalidLogin if username or password are wrong

Example

let mut session = Session::new_from_login(
	"kangalioo".into(),
	"<PASSWORD>".into(),
	"<CLIENT_DATA>".into(),
	std::time::Duration::from_millis(2000), // wait 2s inbetween requests
	None, // no timeout
)?;

println!("Details about kangalioo: {:?}", session.user_details("kangalioo"));

pub fn user_details(&self, username: &str) -> Result<UserDetails, Error>

Retrieves details about the profile of the specified user.

Note: the aboutMe field may be an empty string

Errors

• Error::UserNotFound if the supplied username was not found

Example

// Retrieve details about user "kangalioo"
let details = session.user_details("kangalioo")?;

pub fn user_top_skillset_scores(
    &self,
    username: &str,
    skillset: Skillset7,
    limit: u32
) -> Result<Vec<TopScore>, Error>

Retrieve the user’s top scores by the given skillset. The number of scores returned is equal to limit

Errors

• Error::UserNotFound if the supplied username was not found

Example

// Retrieve the top 10 chordjack scores of user "kangalioo"
let scores = session.user_top_skillset_scores("kangalioo", Skillset7::Chordjack, 10)?;

pub fn user_top_10_scores(&self, username: &str) -> Result<Vec<TopScore>, Error>

Retrieve the user’s top 10 scores, sorted by the overall SSR. Due to a bug in the EO v2 API, it’s unfortunately not possible to control the number of scores returned.

Errors

• Error::UserNotFound if the supplied username was not found

Example

// Retrieve the top 10 scores of user "kangalioo"
let scores = session.user_top_10_scores("kangalioo")?;

pub fn user_latest_scores(
    &self,
    username: &str
) -> Result<Vec<LatestScore>, Error>

Retrieve the user’s latest 10 scores.

Errors

• Error::UserNotFound if the supplied username was not found

Example

// Retrieve the latest 10 scores of user "kangalioo"
let scores = session.user_latest_scores("kangalioo")?;

pub fn user_ranks_per_skillset(&self, username: &str) -> Result<UserRank, Error>

Retrieve the user’s rank for each skillset.

Errors

• Error::UserNotFound if the supplied username was not found

Example

// Retrieve "kangalioo"'s rank for each skillset
let scores = session.user_ranks_per_skillset("kangalioo")?;

pub fn user_top_scores_per_skillset(
    &self,
    username: &str
) -> Result<UserTopScoresPerSkillset, Error>

Retrieve the user’s best scores for each skillset. The number of scores yielded is not documented in the EO API, but according to my experiments it’s 25.

Errors

• Error::UserNotFound if the supplied username was not found

Example

let top_scores = session.user_top_scores_per_skillset("kangalioo")?;
println!("kangalioo's 5th best handstream score is {:?}", top_scores.handstream[4]);

pub fn score_data(&self, scorekey: impl AsRef<str>) -> Result<ScoreData, Error>

Retrieves detailed metadata and the replay data about the score with the given scorekey.

Errors

• Error::ScoreNotFound if the supplied scorekey was not found
• panics if the passed in scorekey is in an invalid format (only applies if passed in as a &str, since &Scorekey is guaranteed to be valid)

Example

let score_info = session.score_data("S65565b5bc377c6d78b60c0aecfd9e05955b4cf63")?;

pub fn chart_leaderboard(
    &self,
    chartkey: impl AsRef<str>
) -> Result<Vec<ChartLeaderboardScore>, Error>

Retrieves the leaderboard for the specified chart. The return type is a vector of leaderboard entries.

Errors

• Error::ChartNotTracked if the chartkey provided is not tracked by EO

Example

let leaderboard = session.chart_leaderboard("X4a15f62b66a80b62ec64521704f98c6c03d98e03")?;

println!("The best Game Time score is being held by {}", leaderboard[0].user.username);

pub fn country_leaderboard(
    &self,
    country_code: &str
) -> Result<Vec<LeaderboardEntry>, Error>

Retrieves the player leaderboard for the given country.

Errors

• Error::NoUsersFound if there are no users registered in this country

Example

let leaderboard = session.country_leaderboard("DE")?;

println!(
	"The best German Etterna player is {} with a rating of {}",
	leaderboard[0].user.username,
	leaderboard[0].rating.overall,
);

pub fn world_leaderboard(&self) -> Result<Vec<LeaderboardEntry>, Error>

Retrieves the worldwide leaderboard of players.

Example

let leaderboard = session.world_leaderboard()?;

println!(
	"The world's best Etterna player is {} with a rating of {}",
	leaderboard[0].user.username,
	leaderboard[0].rating.overall,
);

pub fn user_favorites(&self, username: &str) -> Result<Vec<String>, Error>

Retrieves the user’s favorites. Returns a vector of chartkeys.

Errors

• Error::UserNotFound if the supplied username was not found

Example

let favorites = session.user_favorites("kangalioo")?;
println!("kangalioo has {} favorites", favorites.len());

pub fn add_user_favorite(
    &self,
    username: &str,
    chartkey: impl AsRef<str>
) -> Result<(), Error>

Add a chart to the user’s favorites.

Errors

• Error::ChartAlreadyFavorited if the chart is already in the user’s favorites
• Error::ChartNotTracked if the chartkey provided is not tracked by EO

Example

// Favorite Game Time
session.add_user_favorite("kangalioo", "X4a15f62b66a80b62ec64521704f98c6c03d98e03")?;

pub fn remove_user_favorite(
    &self,
    username: &str,
    chartkey: impl AsRef<str>
) -> Result<(), Error>

Remove a chart from the user’s favorites.

Example

// Unfavorite Game Time
session.remove_user_favorite("kangalioo", "X4a15f62b66a80b62ec64521704f98c6c03d98e03")?;

pub fn user_goals(&self, username: &str) -> Result<Vec<ScoreGoal>, Error>

Retrieves a user’s score goals.

Errors

• Error::UserNotFound if the specified user doesn’t exist or if the specified user has no goals

Example

let score_goals = session.user_goals("theropfather")?;

println!("theropfather has {} goals", score_goals.len());

pub fn add_user_goal(
    &self,
    username: &str,
    chartkey: impl AsRef<str>,
    rate: f64,
    wifescore: f64,
    time_assigned: &str
) -> Result<(), Error>

Add a new score goal.

Errors

• Error::GoalAlreadyExists when the goal already exists in the database
• Error::ChartNotTracked if the chartkey provided is not tracked by EO
• Error::DatabaseError if there was a problem with the database

Example

// Add a Game Time 1.0x AA score goal
session.add_user_goal(
	"kangalioo",
	"X4a15f62b66a80b62ec64521704f98c6c03d98e03",
	1.0,
	0.93,
	"2020-07-13 22:48:26",
)?;

pub fn remove_user_goal(
    &self,
    username: &str,
    chartkey: impl AsRef<str>,
    rate: Rate,
    wifescore: Wifescore
) -> Result<(), Error>

Remove the user goal with the specified chartkey, rate and wifescore.

Note: this API call doesn’t seem to do anything

Example

// Let's delete theropfather's first score goal

let score_goal = session.user_goals("theropfather")?[0];

session.remove_user_goal(
	"theropfather",
	score_goal.chartkey,
	score_goal.rate,
	score_goal.wifescore
)?;

pub fn update_user_goal(
    &self,
    username: &str,
    goal: &ScoreGoal
) -> Result<(), Error>

Update a score goal by replacing all its attributes with the given ones.

Example

// Let's up kangalioo's first score goal's rate by 0.05

let mut score_goal = &mut session.user_goals("kangalioo")?[0];

// Add 0.05 to the rate
score_goal.rate += Rate::from(0.05);

session.update_user_goal("kangalioo", score_goal)?;