Client¶

def accept_friend_request(self, request_id: int) -> bool:
    """Accept a friend request. Requires authentication.

    Args:
        request_id: The friend request ID.

    Returns:
        True if accepted successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to accept friend request")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "requestID": str(request_id),
    }
    response = self._request("acceptGJFriendRequest20.php", data)
    return response == "1"

def block_user(self, user_id: int) -> bool:
    """Block a user. Requires authentication.

    Args:
        user_id: The user's account ID to block.

    Returns:
        True if blocked successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to block user")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "targetAccountID": str(user_id),
    }
    response = self._request("blockGJUser20.php", data)
    return response == "1"

def close(self) -> None:
    """Close the HTTP client."""
    if self._client:
        self._client.close()
        self._client = None

def delete_friend_request(self, request_id: int) -> bool:
    """Delete a friend request. Requires authentication.

    Args:
        request_id: The friend request ID.

    Returns:
        True if deleted successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to delete friend request")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "requestID": str(request_id),
    }
    response = self._request("deleteGJFriendRequests20.php", data)
    return response == "1"

def delete_level(self, level_id: int) -> bool:
    """Delete a level. Requires authentication.

    Args:
        level_id: The level ID to delete.

    Returns:
        True if deleted successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to delete level")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "levelID": str(level_id),
        "secret": "Wmfv2898gc9",
    }
    response = self._request("deleteGJLevelUser20.php", data)
    return response == "1"

def delete_level_comment(self, comment_id: int, level_id: int) -> bool:
    """Delete a level comment. Requires authentication.

    Args:
        comment_id: The comment ID to delete.
        level_id: The level ID the comment is on.

    Returns:
        True if deleted successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to delete comment")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "commentID": str(comment_id),
        "levelID": str(level_id),
    }
    response = self._request("deleteGJComment20.php", data)
    return response == "1"

def delete_message(self, message_id: int) -> bool:
    """Delete a message. Requires authentication.

    Args:
        message_id: The message ID to delete.

    Returns:
        True if deleted successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to delete message")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "messageID": str(message_id),
    }
    response = self._request("deleteGJMessages20.php", data)
    return response == "1"

def delete_profile_comment(self, comment_id: int) -> bool:
    """Delete a profile comment. Requires authentication.

    Args:
        comment_id: The comment ID to delete.

    Returns:
        True if deleted successfully.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to delete profile comment")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "commentID": str(comment_id),
    }
    response = self._request("deleteGJAccComment20.php", data)
    return response == "1"

def get_account_comments(
    self, account_id: int, limit: int = 10, page: int = 0
) -> list[Comment]:
    """Get comments on a user's profile.

    Args:
        account_id: The account ID of the user.
        limit: Maximum number of comments to return.
        page: Page number for pagination.

    Returns:
        List of Comment objects.
    """
    data = {
        "accountID": str(account_id),
        "total": str(limit),
        "page": str(page),
    }
    response = self._request("getGJAccountComments20.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    comments_data = parse_list_response(parts[0])
    return [Comment.model_validate(c) for c in comments_data]

def get_blocked_users(self) -> list[User]:
    """Get blocked users list. Requires authentication.

    Returns:
        List of User objects.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get blocked users")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "type": "1",
    }
    response = self._request("getGJUserList20.php", data)
    if response.startswith("-"):
        return []
    users_data = parse_list_response(response)
    return [User.model_validate(u) for u in users_data]

def get_challenges(self) -> DailyChallenges:
    """Get daily challenges/quests. Requires authentication."""

    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get challenges")
    udid = self._generate_udid()
    data = {
        "udid": udid,
        "secret": Secrets.COMMON,
        "chk": generate_rewards_chk("19847"),
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
    }
    response = self._request("getGJChallenges.php", data)
    if response.startswith("-") or "|" not in response:
        return DailyChallenges()
    return self._parse_challenges(response)

def get_chest_rewards(self, reward_type: int = 0) -> ChestInfo:
    """Get chest reward information. Requires authentication.

    Args:
        reward_type: 0 for info, 1 for small chest, 2 for large chest.
    """
    import random

    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get chest rewards")
    udid = self._generate_udid()
    data = {
        "udid": udid,
        "secret": Secrets.COMMON,
        "chk": generate_rewards_chk("59182"),
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "rewardType": str(reward_type),
        "r1": str(random.randint(100, 99999)),
        "r2": str(random.randint(100, 99999)),
    }
    response = self._request("getGJRewards.php", data)
    if response.startswith("-") or "|" not in response:
        return ChestInfo()
    return self._parse_chest_info(response)

def get_comment_history(
    self, user_id: int, limit: int = 10, page: int = 0, mode: str = "recent"
) -> list[Comment]:
    """Get a user's comment history (comments they've posted on levels).

    Args:
        user_id: The user's ID (not account ID).
        limit: Maximum number of comments to return.
        page: Page number for pagination.
        mode: "recent" or "liked".

    Returns:
        List of Comment objects.
    """
    mode_value = "1" if mode == "liked" else "0"
    data = {
        "userID": str(user_id),
        "total": str(limit),
        "page": str(page),
        "mode": mode_value,
    }
    response = self._request("getGJCommentHistory.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    comments = []
    for comment_str in parts[0].split("|"):
        if not comment_str:
            continue
        comment_parts = comment_str.split(":")
        comment_data = parse_response(comment_parts[0])
        if len(comment_parts) > 1:
            user_data = parse_response(comment_parts[1])
            comment_data["username"] = user_data.get("1", "")
        comments.append(Comment.model_validate(comment_data))
    return comments

def get_daily_level(self, type: str = "daily") -> DailyLevel:
    """Get the current daily/weekly level info.

    Args:
        type: "daily", "weekly", or "event".

    Returns:
        DailyLevel object with index and time_left.
    """
    type_map = {"daily": "0", "weekly": "1", "event": "2"}
    data = {"type": type_map.get(type, "0")}
    response = self._request("getGJDailyLevel.php", data)
    if response.startswith("-"):
        return DailyLevel()
    parts = response.split("|")
    if len(parts) >= 2:
        return DailyLevel(index=int(parts[0]), time_left=int(parts[1]))
    return DailyLevel()

def get_friend_requests(
    self, limit: int = 10, page: int = 0, sent: bool = False
) -> list[FriendRequest]:
    """Get friend requests. Requires authentication.

    Args:
        limit: Maximum number of requests to return.
        page: Page number for pagination.
        sent: If True, get sent requests instead of received.

    Returns:
        List of FriendRequest objects.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get friend requests")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "page": str(page),
        "total": str(limit),
        "getSent": "1" if sent else "0",
    }
    response = self._request("getGJFriendRequests20.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    requests_data = parse_list_response(parts[0])
    return [FriendRequest.model_validate(r) for r in requests_data]

def get_friends(self) -> list[User]:
    """Get friends list. Requires authentication.

    Returns:
        List of User objects.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get friends")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "type": "0",
    }
    response = self._request("getGJUserList20.php", data)
    if response.startswith("-"):
        return []
    users_data = parse_list_response(response)
    return [User.model_validate(u) for u in users_data]

def get_gauntlets(self) -> list[Gauntlet]:
    """Get all gauntlets.

    Returns:
        List of Gauntlet objects.
    """
    data = {"special": "1"}
    response = self._request("getGJGauntlets21.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    gauntlets_data = parse_list_response(parts[0])
    return [Gauntlet.model_validate(g) for g in gauntlets_data]

def get_leaderboard(self, limit: int = 100, type: str = "top") -> list[LeaderboardScore]:
    """Get the leaderboard.

    Args:
        limit: Maximum number of results (max 100).
        type: Leaderboard type - "top" or "creators".

    Returns:
        List of LeaderboardScore objects.
    """
    type_value = "creators" if type == "creators" else "top"
    data = {"type": type_value, "count": str(min(limit, 100))}
    response = self._request("getGJScores20.php", data)
    if response.startswith("-"):
        return []
    entries_data = parse_list_response(response)
    return [LeaderboardScore.model_validate(e) for e in entries_data]

def get_level(self, level_id: int) -> Level:
    """Get a level by its ID.

    Args:
        level_id: The ID of the level.

    Returns:
        Level object with level information.

    Raises:
        NotFoundError: If level is not found.
        InvalidRequestError: If rate limited.
    """
    data = {"levelID": str(level_id)}
    response = self._request("downloadGJLevel22.php", data)
    if response.startswith("-"):
        self._handle_error(response)
    parsed = parse_response(response.split("#")[0])
    return Level.model_validate(parsed)

def get_level_comments(self, level_id: int, limit: int = 10, page: int = 0) -> list[Comment]:
    """Get comments for a level.

    Args:
        level_id: The ID of the level.
        limit: Maximum number of comments to return.
        page: Page number for pagination.

    Returns:
        List of Comment objects.
    """
    data = {
        "levelID": str(level_id),
        "total": str(limit),
        "page": str(page),
        "mode": "0",
    }
    response = self._request("getGJComments21.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    comments = []
    for comment_str in parts[0].split("|"):
        if not comment_str:
            continue
        comment_parts = comment_str.split(":")
        comment_data = parse_response(comment_parts[0])
        if len(comment_parts) > 1:
            user_data = parse_response(comment_parts[1])
            comment_data["username"] = user_data.get("1", "")
        comments.append(Comment.model_validate(comment_data))
    return comments

def get_level_lists(self, limit: int = 10, page: int = 0) -> list[dict[str, str]]:
    """Get level lists (user-created lists of levels).

    Args:
        limit: Maximum number of lists to return.
        page: Page number for pagination.

    Returns:
        List of level list dictionaries.
    """
    data = {"type": "0", "str": "", "total": str(limit), "page": str(page)}
    response = self._request("getGJLevelLists.php", data)
    if response.startswith("-"):
        return []
    return parse_list_response(response)

def get_map_packs(self, page: int = 0) -> list[MapPack]:
    """Get map packs.

    Args:
        page: Page number for pagination.

    Returns:
        List of MapPack objects.
    """
    data = {"page": str(page)}
    response = self._request("getGJMapPacks21.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    packs_data = parse_list_response(parts[0])
    return [MapPack.model_validate(p) for p in packs_data]

def get_message(self, message_id: int) -> Message:
    """Download full message content. Requires authentication.

    Args:
        message_id: The message ID to download.

    Returns:
        Message object with full content.

    Raises:
        RuntimeError: If not authenticated.
        NotFoundError: If message not found.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get message")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "messageID": str(message_id),
    }
    response = self._request("downloadGJMessage20.php", data)
    if response.startswith("-"):
        self._handle_error(response)
    parsed = parse_response(response)
    return Message.model_validate(parsed)

def get_messages(self, limit: int = 10, page: int = 0, sent: bool = False) -> list[Message]:
    """Get inbox or sent messages. Requires authentication.

    Args:
        limit: Maximum number of messages to return.
        page: Page number for pagination.
        sent: If True, get sent messages instead of inbox.

    Returns:
        List of Message objects.

    Raises:
        RuntimeError: If not authenticated.
    """
    if not self.is_authenticated:
        raise RuntimeError("Must be authenticated to get messages")
    data = {
        "accountID": str(self._account_id),
        "gjp2": self._get_gjp2(),
        "page": str(page),
        "total": str(limit),
        "getSent": "1" if sent else "0",
    }
    response = self._request("getGJMessages20.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    messages_data = parse_list_response(parts[0])
    return [Message.model_validate(m) for m in messages_data]

def get_song(self, song_id: int) -> Song:
    """Get a custom song by its ID.

    Args:
        song_id: The ID of the song.

    Returns:
        Song object with song information.

    Raises:
        NotFoundError: If song is not found.
        InvalidRequestError: If rate limited.
    """
    data = {"songID": str(song_id)}
    response = self._request("getGJSongInfo.php", data)
    if response.startswith("-"):
        self._handle_error(response)
    parsed = parse_response(response)
    return Song.model_validate(parsed)

def get_top_1000(self, limit: int = 100, page: int = 0) -> list[User]:
    """Get top 1000 users by stars.

    Args:
        limit: Maximum number of users to return.
        page: Page number for pagination.

    Returns:
        List of User objects.
    """
    data = {"type": "top", "count": str(limit), "page": str(page)}
    response = self._request("getTop1000.php", data)
    if response.startswith("-"):
        return []
    users_data = parse_list_response(response)
    return [User.model_validate(u) for u in users_data]

def get_top_artists(self, page: int = 0) -> list[TopArtist]:
    """Get RobTop's handpicked top artists.

    Args:
        page: Page number for pagination.

    Returns:
        List of TopArtist objects.
    """
    data = {"page": str(page)}
    response = self._request("getGJTopArtists.php", data)
    if response.startswith("-"):
        return []
    parts = response.split("#")
    if not parts:
        return []
    artists_data = parse_list_response(parts[0])
    return [TopArtist.model_validate(a) for a in artists_data]

def get_user(self, account_id: int) -> User:
    """Get a user by their account ID.

    Args:
        account_id: The account ID of the user.

    Returns:
        User object with profile information.

    Raises:
        NotFoundError: If user is not found.
        InvalidRequestError: If rate limited.
    """
    data = {"targetAccountID": str(account_id)}
    response = self._request("getGJUserInfo20.php", data)
    if response.startswith("-"):
        self._handle_error(response)
    parsed = parse_response(response)
    return User.model_validate(parsed)