python-xbox 0.1.0__py3-none-any.whl

pythonxbox/api/provider/people/__init__.py

@@ -0,0 +1,193 @@
+"""
+People - Access friendlist from own profiles and others
+"""
+
+from pythonxbox.api.provider.people.models import (
+    PeopleDecoration,
+    PeopleResponse,
+    PeopleSummaryResponse,
+)
+from pythonxbox.api.provider.ratelimitedprovider import RateLimitedProvider
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pythonxbox.api.client import XboxLiveClient
+
+
+class PeopleProvider(RateLimitedProvider):
+    SOCIAL_URL = "https://social.xboxlive.com"
+    HEADERS_SOCIAL = {"x-xbl-contract-version": "2"}
+    PEOPLE_URL = "https://peoplehub.xboxlive.com"
+    HEADERS_PEOPLE = {
+        "x-xbl-contract-version": "7",
+        "Accept-Language": "overwrite in __init__",
+    }
+    SEPERATOR = ","
+
+    # NOTE: Rate Limits are noted for social.xboxlive.com ONLY
+    RATE_LIMITS = {"burst": 10, "sustain": 30}
+
+    client: "XboxLiveClient"
+
+    def __init__(self, client: "XboxLiveClient") -> None:
+        """
+        Initialize Baseclass, set 'Accept-Language' header from client instance
+
+        Args:
+            client (:class:`XboxLiveClient`): Instance of client
+        """
+        super().__init__(client)
+        self._headers = {**self.HEADERS_PEOPLE}
+        self._headers.update({"Accept-Language": self.client.language.locale})
+
+    async def get_friends_own(
+        self, decoration_fields: list[PeopleDecoration] | None = None, **kwargs
+    ) -> PeopleResponse:
+        """
+        Get friendlist of own profile
+
+        Returns:
+            :class:`PeopleResponse`: People Response
+        """
+        if not decoration_fields:
+            decoration_fields = [
+                PeopleDecoration.PREFERRED_COLOR,
+                PeopleDecoration.DETAIL,
+                PeopleDecoration.MULTIPLAYER_SUMMARY,
+                PeopleDecoration.PRESENCE_DETAIL,
+            ]
+        decoration = self.SEPERATOR.join(decoration_fields)
+
+        url = f"{self.PEOPLE_URL}/users/me/people/friends/decoration/{decoration}"
+        resp = await self.client.session.get(url, headers=self._headers, **kwargs)
+        resp.raise_for_status()
+        return PeopleResponse(**resp.json())
+
+    async def get_friends_by_xuid(
+        self,
+        xuid: str,
+        decoration_fields: list[PeopleDecoration] | None = None,
+        **kwargs,
+    ) -> PeopleResponse:
+        """
+        Get friendlist of own profile
+
+        Returns:
+            :class:`PeopleResponse`: People Response
+        """
+        if not decoration_fields:
+            decoration_fields = [
+                PeopleDecoration.PREFERRED_COLOR,
+                PeopleDecoration.DETAIL,
+                PeopleDecoration.MULTIPLAYER_SUMMARY,
+                PeopleDecoration.PRESENCE_DETAIL,
+            ]
+        decoration = self.SEPERATOR.join(decoration_fields)
+
+        url = f"{self.PEOPLE_URL}/users/me/people/xuids({xuid})/decoration/{decoration}"
+        resp = await self.client.session.get(url, headers=self._headers, **kwargs)
+        resp.raise_for_status()
+        return PeopleResponse(**resp.json())
+
+    async def get_friends_own_batch(
+        self,
+        xuids: list[str],
+        decoration_fields: list[PeopleDecoration] | None = None,
+        **kwargs,
+    ) -> PeopleResponse:
+        """
+        Get friends metadata by providing a list of XUIDs
+
+        Args:
+            xuids: List of XUIDs
+
+        Returns:
+            :class:`PeopleResponse`: People Response
+        """
+        if not decoration_fields:
+            decoration_fields = [
+                PeopleDecoration.PREFERRED_COLOR,
+                PeopleDecoration.DETAIL,
+                PeopleDecoration.MULTIPLAYER_SUMMARY,
+                PeopleDecoration.PRESENCE_DETAIL,
+            ]
+        decoration = self.SEPERATOR.join(decoration_fields)
+
+        url = f"{self.PEOPLE_URL}/users/me/people/batch/decoration/{decoration}"
+        resp = await self.client.session.post(
+            url, json={"xuids": xuids}, headers=self._headers, **kwargs
+        )
+        resp.raise_for_status()
+        return PeopleResponse(**resp.json())
+
+    async def get_friend_recommendations(
+        self, decoration_fields: list[PeopleDecoration] | None = None, **kwargs
+    ) -> PeopleResponse:
+        """
+        Get recommended friends
+
+        Returns:
+            :class:`PeopleResponse`: People Response
+        """
+        if not decoration_fields:
+            decoration_fields = [PeopleDecoration.DETAIL]
+        decoration = self.SEPERATOR.join(decoration_fields)
+
+        url = (
+            f"{self.PEOPLE_URL}/users/me/people/recommendations/decoration/{decoration}"
+        )
+        resp = await self.client.session.get(url, headers=self._headers, **kwargs)
+        resp.raise_for_status()
+        return PeopleResponse(**resp.json())
+
+    async def get_friends_summary_own(self, **kwargs) -> PeopleSummaryResponse:
+        """
+        Get friendlist summary of own profile
+
+        Returns:
+            :class:`PeopleSummaryResponse`: People Summary Response
+        """
+        url = self.SOCIAL_URL + "/users/me/summary"
+        resp = await self.client.session.get(
+            url, headers=self.HEADERS_SOCIAL, rate_limits=self.rate_limit_read, **kwargs
+        )
+        resp.raise_for_status()
+        return PeopleSummaryResponse(**resp.json())
+
+    async def get_friends_summary_by_xuid(
+        self, xuid: str, **kwargs
+    ) -> PeopleSummaryResponse:
+        """
+        Get friendlist summary of user by xuid
+
+        Args:
+            xuid: XUID to request summary from
+
+        Returns:
+            :class:`PeopleSummaryResponse`: People Summary Response
+        """
+        url = self.SOCIAL_URL + f"/users/xuid({xuid})/summary"
+        resp = await self.client.session.get(
+            url, headers=self.HEADERS_SOCIAL, rate_limits=self.rate_limit_read, **kwargs
+        )
+        resp.raise_for_status()
+        return PeopleSummaryResponse(**resp.json())
+
+    async def get_friends_summary_by_gamertag(
+        self, gamertag: str, **kwargs
+    ) -> PeopleSummaryResponse:
+        """
+        Get friendlist summary of user by gamertag
+
+        Args:
+            gamertag: Gamertag to request friendlist from
+
+        Returns:
+            :class:`PeopleSummaryResponse`: People Summary Response
+        """
+        url = self.SOCIAL_URL + f"/users/gt({gamertag})/summary"
+        resp = await self.client.session.get(
+            url, headers=self.HEADERS_SOCIAL, rate_limits=self.rate_limit_read, **kwargs
+        )
+        resp.raise_for_status()
+        return PeopleSummaryResponse(**resp.json())

pythonxbox/api/provider/people/models.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import Field
+
+from pythonxbox.common.models import CamelCaseModel, PascalCaseModel
+
+
+class PeopleDecoration(StrEnum):
+    SUGGESTION = "suggestion"
+    RECENT_PLAYER = "recentPlayer"
+    FOLLOWER = "follower"
+    PREFERRED_COLOR = "preferredColor"
+    DETAIL = "detail"
+    MULTIPLAYER_SUMMARY = "multiplayerSummary"
+    PRESENCE_DETAIL = "presenceDetail"
+    TITLE_PRESENCE = "titlePresence"
+    TITLE_SUMMARY = "titleSummary"
+    PRESENCE_TITLE_IDS = "presenceTitleIds"
+    COMMUNITY_MANAGER_TITLES = "communityManagerTitles"
+    SOCIAL_MANAGER = "socialManager"
+    BROADCAST = "broadcast"
+    TOURNAMENT_SUMMARY = "tournamentSummary"
+    AVATAR = "avatar"
+
+
+class PeopleSummaryResponse(CamelCaseModel):
+    target_following_count: int
+    target_follower_count: int
+    is_caller_following_target: bool
+    is_target_following_caller: bool
+    has_caller_marked_target_as_favorite: bool
+    has_caller_marked_target_as_identity_shared: bool
+    legacy_friend_status: str
+    available_people_slots: int | None = None
+    recent_change_count: int | None = None
+    watermark: str | None = None
+    is_friend: bool
+
+
+class Suggestion(PascalCaseModel):
+    type: str | None = None
+    priority: int
+    reasons: str | None = None
+    title_id: str | None = None
+
+
+class Recommendation(PascalCaseModel):
+    type: str
+    reasons: list[str]
+
+
+class SessionRef(CamelCaseModel):
+    scid: str
+    template_name: str
+    name: str
+
+
+class PartyDetails(CamelCaseModel):
+    session_ref: SessionRef
+    status: str
+    visibility: str
+    join_restriction: str
+    accepted: int
+
+
+class MultiplayerSummary(CamelCaseModel):
+    in_multiplayer_session: int | None = None
+    in_party: int
+    joinable_activities: list = Field(default_factory=list)
+    party_details: list[PartyDetails] = Field(default_factory=list)
+
+
+class RecentPlayer(CamelCaseModel):
+    titles: list[str]
+    text: str | None = None
+
+
+class Follower(CamelCaseModel):
+    text: str | None = None
+    followed_date_time_utc: datetime | None = None
+
+
+class PreferredColor(CamelCaseModel):
+    primary_color: str | None = None
+    secondary_color: str | None = None
+    tertiary_color: str | None = None
+
+
+class PresenceDetail(PascalCaseModel):
+    is_broadcasting: bool
+    device: str
+    device_sub_type: str | None = None
+    gameplay_type: str | None = None
+    presence_text: str
+    state: str
+    title_id: str
+    title_type: str | None = None
+    is_primary: bool
+    is_game: bool
+    rich_presence_text: str | None = None
+
+
+class TitlePresence(PascalCaseModel):
+    is_currently_playing: bool
+    presence_text: str | None = None
+    title_name: str | None = None
+    title_id: str | None = None
+
+
+class Detail(CamelCaseModel):
+    account_tier: str
+    bio: str | None = None
+    is_verified: bool
+    location: str | None = None
+    tenure: str | None = None
+    watermarks: list[str]
+    blocked: bool
+    mute: bool
+    follower_count: int
+    following_count: int
+    has_game_pass: bool
+    can_be_friended: bool
+    can_be_followed: bool
+    is_friend: bool
+    friend_count: int
+    is_friend_request_received: bool
+    is_friend_request_sent: bool
+    is_friend_list_shared: bool
+    is_following_caller: bool
+    is_followed_by_caller: bool
+    is_favorite: bool
+
+
+class SocialManager(CamelCaseModel):
+    title_ids: list[str]
+    pages: list[str]
+
+
+class Avatar(CamelCaseModel):
+    update_time_offset: datetime | None = None
+    spritesheet_metadata: Any | None = None
+
+
+class LinkedAccount(CamelCaseModel):
+    network_name: str
+    display_name: str | None = None
+    show_on_profile: bool
+    is_family_friendly: bool
+    deeplink: str | None = None
+
+
+class Person(CamelCaseModel):
+    xuid: str
+    is_favorite: bool
+    is_following_caller: bool
+    is_followed_by_caller: bool
+    is_identity_shared: bool
+    added_date_time_utc: datetime | None = None
+    display_name: str | None = None
+    real_name: str
+    display_pic_raw: str
+    show_user_as_avatar: str
+    gamertag: str
+    gamer_score: str
+    modern_gamertag: str
+    modern_gamertag_suffix: str
+    unique_modern_gamertag: str
+    xbox_one_rep: str
+    presence_state: str
+    presence_text: str
+    presence_devices: Any | None = None
+    is_broadcasting: bool
+    is_cloaked: bool | None = None
+    is_quarantined: bool
+    is_xbox_360_gamerpic: bool
+    last_seen_date_time_utc: datetime | None = None
+    suggestion: Suggestion | None = None
+    recommendation: Recommendation | None = None
+    search: Any | None = None
+    titleHistory: Any | None = None
+    multiplayer_summary: MultiplayerSummary | None = None
+    recent_player: RecentPlayer | None = None
+    follower: Follower | None = None
+    preferred_color: PreferredColor | None = None
+    presence_details: list[PresenceDetail] | None = None
+    title_presence: TitlePresence | None = None
+    title_summaries: Any | None = None
+    presence_title_ids: list[str] | None = None
+    detail: Detail | None = None
+    community_manager_titles: Any | None = None
+    social_manager: SocialManager | None = None
+    broadcast: list[Any] | None = None
+    tournament_summary: Any | None = None
+    avatar: Avatar | None = None
+    linked_accounts: list[LinkedAccount] | None = None
+    color_theme: str
+    preferred_flag: str
+    preferred_platforms: list[Any]
+    friended_date_time_utc: datetime | None = None
+    is_friend: bool
+    is_friend_request_received: bool
+    is_friend_request_sent: bool
+
+
+class RecommendationSummary(CamelCaseModel):
+    friend_of_friend: int | None = None
+    facebook_friend: int | None = None
+    phone_contact: int | None = None
+    follower: int | None = None
+    VIP: int | None = None
+    steam_friend: int
+    promote_suggestions: bool
+    community_suggestion: int
+
+
+class FriendFinderState(CamelCaseModel):
+    facebook_opt_in_status: str
+    facebook_token_status: str
+    phone_opt_in_status: str
+    phone_token_status: str
+    steam_opt_in_status: str
+    steam_token_status: str
+    discord_opt_in_status: str
+    discord_token_status: str
+    instagram_opt_in_status: str
+    instagram_token_status: str
+    mixer_opt_in_status: str
+    mixer_token_status: str
+    reddit_opt_in_status: str
+    reddit_token_status: str
+    twitch_opt_in_status: str
+    twitch_token_status: str
+    twitter_opt_in_status: str
+    twitter_token_status: str
+    you_tube_opt_in_status: str
+    you_tube_token_status: str
+
+
+class FriendRequestSummary(CamelCaseModel):
+    friend_requests_received_count: int
+
+
+class PeopleResponse(CamelCaseModel):
+    people: list[Person]
+    recommendation_summary: RecommendationSummary | None = None
+    friend_finder_state: FriendFinderState | None = None
+    account_link_details: list[LinkedAccount] | None = None
+    friend_request_summary: FriendRequestSummary | None = None

pythonxbox/api/provider/presence/__init__.py

@@ -0,0 +1,110 @@
+"""
+Presence - Get online status of friends
+"""
+
+from pythonxbox.api.provider.baseprovider import BaseProvider
+from pythonxbox.api.provider.presence.models import (
+    PresenceBatchResponse,
+    PresenceItem,
+    PresenceLevel,
+    PresenceState,
+)
+
+
+class PresenceProvider(BaseProvider):
+    PRESENCE_URL = "https://userpresence.xboxlive.com"
+    HEADERS_PRESENCE = {"x-xbl-contract-version": "3", "Accept": "application/json"}
+
+    async def get_presence(
+        self,
+        xuid: str,
+        presence_level: PresenceLevel = PresenceLevel.USER,
+        **kwargs,
+    ) -> PresenceItem:
+        """
+        Get presence for given xuid
+
+        Args:
+            xuid: XUID
+            presence_level: Filter level
+
+        Returns:
+            :class:`PresenceItem`: Presence Response
+        """
+        url = self.PRESENCE_URL + "/users/xuid(" + xuid + ")?level=" + presence_level
+
+        resp = await self.client.session.get(
+            url, headers=self.HEADERS_PRESENCE, **kwargs
+        )
+        resp.raise_for_status()
+        return PresenceItem(**resp.json())
+
+    async def get_presence_batch(
+        self,
+        xuids: list[str],
+        online_only: bool = False,
+        presence_level: PresenceLevel = PresenceLevel.USER,
+        **kwargs,
+    ) -> list[PresenceItem]:
+        """
+        Get presence for list of xuids
+
+        Args:
+            xuids: List of XUIDs
+            online_only: Only get online profiles
+            presence_level: Filter level
+
+        Returns: List[:class:`PresenceItem`]: List of presence items
+        """
+        if len(xuids) > 1100:
+            raise Exception("Xuid list length is > 1100")
+
+        url = self.PRESENCE_URL + "/users/batch"
+        post_data = {
+            "users": [str(x) for x in xuids],
+            "onlineOnly": online_only,
+            "level": presence_level,
+        }
+        resp = await self.client.session.post(
+            url, json=post_data, headers=self.HEADERS_PRESENCE, **kwargs
+        )
+        resp.raise_for_status()
+        parsed = PresenceBatchResponse.model_validate(resp.json())
+        return parsed.root
+
+    async def get_presence_own(
+        self, presence_level: PresenceLevel = PresenceLevel.ALL, **kwargs
+    ) -> PresenceItem:
+        """
+        Get presence of own profile
+
+        Args:
+            presence_level: Filter level
+
+        Returns:
+            :class:`PresenceItem`: Presence Response
+        """
+        url = self.PRESENCE_URL + "/users/me"
+        params = {"level": presence_level}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_PRESENCE, **kwargs
+        )
+        resp.raise_for_status()
+        return PresenceItem(**resp.json())
+
+    async def set_presence_own(self, presence_state: PresenceState, **kwargs) -> bool:
+        """
+        Set presence of own profile
+
+        Args:
+            presence_state: State of presence
+
+        Returns:
+            `True` on success, `False` otherwise
+        """
+        url = self.PRESENCE_URL + f"/users/xuid({self.client.xuid})/state"
+        data = {"state": presence_state.value}
+        resp = await self.client.session.put(
+            url, json=data, headers=self.HEADERS_PRESENCE, **kwargs
+        )
+        return resp.status_code == 200

pythonxbox/api/provider/presence/models.py

@@ -0,0 +1,53 @@
+from enum import Enum
+from pydantic import RootModel
+
+from pythonxbox.common.models import CamelCaseModel
+
+
+class PresenceLevel(str, Enum):
+    USER = "user"
+    DEVICE = "device"
+    TITLE = "title"
+    ALL = "all"
+
+
+class PresenceState(str, Enum):
+    ACTIVE = "Active"
+    CLOAKED = "Cloaked"
+
+
+class LastSeen(CamelCaseModel):
+    device_type: str
+    title_id: str | None = None
+    title_name: str
+    timestamp: str
+
+
+class ActivityRecord(CamelCaseModel):
+    richPresence: str | None = None
+    media: str | None = None
+
+
+class TitleRecord(CamelCaseModel):
+    id: str | None = None
+    name: str | None = None
+    activity: list[ActivityRecord] | None = None
+    lastModified: str | None = None
+    placement: str | None = None
+    state: str | None = None
+
+
+class DeviceRecord(CamelCaseModel):
+    titles: list[TitleRecord] | None = None
+    type: str | None = None
+
+
+class PresenceItem(CamelCaseModel):
+    xuid: str
+    state: str
+    last_seen: LastSeen | None = None
+    devices: list[DeviceRecord] | None = None
+
+
+class PresenceBatchResponse(RootModel[list[PresenceItem]], CamelCaseModel):
+    root: list[PresenceItem]