python-xbox 0.1.0__py3-none-any.whl

pythonxbox/api/provider/titlehub/__init__.py

@@ -0,0 +1,143 @@
+"""
+Titlehub - Get Title history and info
+"""
+
+from typing import TYPE_CHECKING
+from pythonxbox.api.provider.baseprovider import BaseProvider
+from pythonxbox.api.provider.titlehub.models import TitleFields, TitleHubResponse
+
+if TYPE_CHECKING:
+    from pythonxbox.api.client import XboxLiveClient
+
+
+class TitlehubProvider(BaseProvider):
+    TITLEHUB_URL = "https://titlehub.xboxlive.com"
+    SEPARATOR = ","
+
+    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 = {
+            "x-xbl-contract-version": "2",
+            "x-xbl-client-name": "XboxApp",
+            "x-xbl-client-type": "UWA",
+            "x-xbl-client-version": "39.39.22001.0",
+            "Accept-Language": self.client.language.locale,
+        }
+
+    async def get_title_history(
+        self,
+        xuid: str,
+        fields: list[TitleFields] | None = None,
+        max_items: int | None = 5,
+        **kwargs,
+    ) -> TitleHubResponse:
+        """
+        Get recently played titles
+
+        Args:
+            xuid: Xuid
+            fields: List of titlefield
+            max_items: Maximum items
+
+        Returns:
+            :class:`TitleHubResponse`: Title Hub Response
+        """
+        if not fields:
+            fields = [
+                TitleFields.ACHIEVEMENT,
+                TitleFields.IMAGE,
+                TitleFields.SERVICE_CONFIG_ID,
+            ]
+        fields = self.SEPARATOR.join(fields)
+
+        url = f"{self.TITLEHUB_URL}/users/xuid({xuid})/titles/titlehistory/decoration/{fields}"
+        params = {"maxItems": max_items}
+        resp = await self.client.session.get(
+            url, params=params, headers=self._headers, **kwargs
+        )
+        resp.raise_for_status()
+        return TitleHubResponse(**resp.json())
+
+    async def _get_title_info(
+        self, moniker: str, fields: list[TitleFields] | None = None, **kwargs
+    ) -> TitleHubResponse:
+        if not fields:
+            fields = [
+                TitleFields.ACHIEVEMENT,
+                TitleFields.ALTERNATE_TITLE_ID,
+                TitleFields.DETAIL,
+                TitleFields.IMAGE,
+                TitleFields.SERVICE_CONFIG_ID,
+            ]
+        fields = self.SEPARATOR.join(fields)
+
+        url = f"{self.TITLEHUB_URL}/users/xuid({self.client.xuid})/titles/{moniker}/decoration/{fields}"
+        resp = await self.client.session.get(url, headers=self._headers, **kwargs)
+        resp.raise_for_status()
+        return TitleHubResponse(**resp.json())
+
+    async def get_title_info(
+        self, title_id: str, fields: list[TitleFields] | None = None, **kwargs
+    ) -> TitleHubResponse:
+        """
+        Get info for specific title
+
+        Args:
+            title_id: Title Id
+            fields: List of title fields
+
+        Returns:
+            :class:`TitleHubResponse`: Title Hub Response
+        """
+        return await self._get_title_info(f"titleid({title_id})", fields, **kwargs)
+
+    async def get_title_info_by_pfn(
+        self, pfn: str, fields: list[TitleFields] | None = None, **kwargs
+    ) -> TitleHubResponse:
+        """
+        Get info for specific title by PFN
+
+        Args:
+            pfn: Package family name
+            fields: List of title fields
+
+        Returns:
+            :class:`TitleHubResponse`: Title Hub Response
+        """
+        return await self._get_title_info(f"pfn({pfn})", fields, **kwargs)
+
+    async def get_titles_batch(
+        self, pfns: list[str], fields: list[TitleFields] | None = None, **kwargs
+    ) -> TitleHubResponse:
+        """
+        Get Title info via PFN ids
+
+        Args:
+            pfns: List of Package family names (e.g. 'Microsoft.XboxApp_8wekyb3d8bbwe')
+            fields: List of title fields
+
+        Returns:
+            :class:`TitleHubResponse`: Title Hub Response
+        """
+        if not fields:
+            fields = [
+                TitleFields.ACHIEVEMENT,
+                TitleFields.DETAIL,
+                TitleFields.IMAGE,
+                TitleFields.SERVICE_CONFIG_ID,
+            ]
+        fields = self.SEPARATOR.join(fields)
+
+        url = self.TITLEHUB_URL + f"/titles/batch/decoration/{fields}"
+        post_data = {"pfns": pfns, "windowsPhoneProductIds": []}
+        resp = await self.client.session.post(
+            url, json=post_data, headers=self._headers, **kwargs
+        )
+        resp.raise_for_status()
+        return TitleHubResponse(**resp.json())

pythonxbox/api/provider/titlehub/models.py

@@ -0,0 +1,106 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pythonxbox.common.models import CamelCaseModel, PascalCaseModel
+
+
+class TitleFields(str, Enum):
+    SERVICE_CONFIG_ID = "scid"
+    ACHIEVEMENT = "achievement"
+    STATS = "stats"
+    GAME_PASS = "gamepass"  # noqa: S105
+    IMAGE = "image"
+    DETAIL = "detail"
+    FRIENDS_WHO_PLAYED = "friendswhoplayed"
+    ALTERNATE_TITLE_ID = "alternateTitleId"
+    PRODUCT_ID = "productId"
+    CONTENT_BOARD = "contentBoard"
+
+
+class Achievement(CamelCaseModel):
+    current_achievements: int
+    total_achievements: int
+    current_gamerscore: int
+    total_gamerscore: int
+    progress_percentage: float
+    source_version: int
+
+
+class Stats(CamelCaseModel):
+    source_version: int
+
+
+class GamePass(CamelCaseModel):
+    is_game_pass: bool
+
+
+class Image(CamelCaseModel):
+    url: str
+    type: str
+
+
+class TitleHistory(CamelCaseModel):
+    last_time_played: datetime
+    visible: bool
+    can_hide: bool
+
+
+class Attribute(CamelCaseModel):
+    applicable_platforms: list[str] | None = None
+    maximum: int | None = None
+    minimum: int | None = None
+    name: str
+
+
+class Availability(PascalCaseModel):
+    actions: list[str]
+    availability_id: str
+    platforms: list[str]
+    sku_id: str
+
+
+class Detail(CamelCaseModel):
+    attributes: list[Attribute]
+    availabilities: list[Availability]
+    capabilities: list[str]
+    description: str
+    developer_name: str | None = None
+    genres: list[str] | None = None
+    publisher_name: str
+    min_age: int | None = None
+    release_date: datetime | None = None
+    short_description: str | None = None
+    vui_display_name: str | None = None
+    xbox_live_gold_required: bool
+
+
+class Title(CamelCaseModel):
+    title_id: str
+    pfn: str | None = None
+    bing_id: str | None = None
+    service_config_id: str | None = None
+    windows_phone_product_id: str | None = None
+    name: str
+    type: str
+    devices: list[str]
+    display_image: str
+    media_item_type: str
+    modern_title_id: str | None = None
+    is_bundle: bool
+    achievement: Achievement | None = None
+    stats: Stats | None = None
+    game_pass: GamePass | None = None
+    images: list[Image] | None = None
+    title_history: TitleHistory | None = None
+    detail: Detail | None = None
+    friends_who_played: Any = None
+    alternate_title_ids: Any = None
+    content_boards: Any = None
+    xbox_live_tier: str | None = None
+    is_streamable: bool | None = None
+
+
+class TitleHubResponse(CamelCaseModel):
+    xuid: str | None = None
+    titles: list[Title]

pythonxbox/api/provider/usersearch/__init__.py

@@ -0,0 +1,29 @@
+"""
+Usersearch - Search for gamertags / userprofiles
+"""
+
+from pythonxbox.api.provider.baseprovider import BaseProvider
+from pythonxbox.api.provider.usersearch.models import UserSearchResponse
+
+
+class UserSearchProvider(BaseProvider):
+    USERSEARCH_URL = "https://usersearch.xboxlive.com"
+    HEADERS_USER_SEARCH = {"x-xbl-contract-version": "1"}
+
+    async def get_live_search(self, query: str, **kwargs) -> UserSearchResponse:
+        """
+        Get userprofiles for search query
+
+        Args:
+            query: Search query
+
+        Returns:
+            :class:`UserSearchResponse`: User Search Response
+        """
+        url = self.USERSEARCH_URL + "/suggest"
+        params = {"q": query}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_USER_SEARCH, **kwargs
+        )
+        resp.raise_for_status()
+        return UserSearchResponse(**resp.json())

pythonxbox/api/provider/usersearch/models.py

@@ -0,0 +1,17 @@
+from pythonxbox.common.models import CamelCaseModel
+
+
+class UserDetail(CamelCaseModel):
+    id: str
+    gamertag: str
+    display_pic_uri: str
+    score: float
+
+
+class UserResult(CamelCaseModel):
+    text: str
+    result: UserDetail
+
+
+class UserSearchResponse(CamelCaseModel):
+    results: list[UserResult]

pythonxbox/api/provider/userstats/__init__.py

@@ -0,0 +1,164 @@
+"""
+Userstats - Get game statistics
+"""
+
+from pythonxbox.api.provider.ratelimitedprovider import RateLimitedProvider
+from pythonxbox.api.provider.userstats.models import (
+    GeneralStatsField,
+    UserStatsResponse,
+)
+
+
+class UserStatsProvider(RateLimitedProvider):
+    USERSTATS_URL = "https://userstats.xboxlive.com"
+    HEADERS_USERSTATS = {"x-xbl-contract-version": "2"}
+    HEADERS_USERSTATS_WITH_METADATA = {"x-xbl-contract-version": "3"}
+    SEPERATOR = ","
+
+    # NOTE: Stats Read (userstats.xboxlive.com) and Stats Write (statswrite.xboxlive.com)
+    # Are mentioned as their own objects but their rate limits are the same and do not collide
+    # (Stats Read -> read rate limit, Stats Write -> write rate limit)
+    RATE_LIMITS = {"burst": 100, "sustain": 300}
+
+    async def get_stats(
+        self,
+        xuid: str,
+        service_config_id: str,
+        stats_fields: list[GeneralStatsField] | None = None,
+        **kwargs,
+    ) -> UserStatsResponse:
+        """
+        Get userstats
+
+        Args:
+            xuid: Xbox User Id
+            service_config_id: Service Config Id of Game (scid)
+            stats_fields: List of stats fields to acquire
+
+        Returns:
+            :class:`UserStatsResponse`: User Stats Response
+        """
+        if not stats_fields:
+            stats_fields = [GeneralStatsField.MINUTES_PLAYED]
+        stats = self.SEPERATOR.join(stats_fields)
+
+        url = f"{self.USERSTATS_URL}/users/xuid({xuid})/scids/{service_config_id}/stats/{stats}"
+        resp = await self.client.session.get(
+            url,
+            headers=self.HEADERS_USERSTATS,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return UserStatsResponse(**resp.json())
+
+    async def get_stats_with_metadata(
+        self,
+        xuid: str,
+        service_config_id: str,
+        stats_fields: list[GeneralStatsField] | None = None,
+        **kwargs,
+    ) -> UserStatsResponse:
+        """
+        Get userstats including metadata for each stat (if available)
+
+        Args:
+            xuid: Xbox User Id
+            service_config_id: Service Config Id of Game (scid)
+            stats_fields: List of stats fields to acquire
+
+        Returns:
+            :class:`UserStatsResponse`: User Stats Response
+        """
+        if not stats_fields:
+            stats_fields = [GeneralStatsField.MINUTES_PLAYED]
+        stats = self.SEPERATOR.join(stats_fields)
+
+        url = f"{self.USERSTATS_URL}/users/xuid({xuid})/scids/{service_config_id}/stats/{stats}"
+        params = {"include": "valuemetadata"}
+        resp = await self.client.session.get(
+            url,
+            params=params,
+            headers=self.HEADERS_USERSTATS_WITH_METADATA,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return UserStatsResponse(**resp.json())
+
+    async def get_stats_batch(
+        self,
+        xuids: list[str],
+        title_id: str,
+        stats_fields: list[GeneralStatsField] | None = None,
+        **kwargs,
+    ) -> UserStatsResponse:
+        """
+        Get userstats in batch mode
+
+        Args:
+            xuids: List of XUIDs to get stats for
+            title_id: Game Title Id
+            stats_fields: List of stats fields to acquire
+
+        Returns:
+            :class:`UserStatsResponse`: User Stats Response
+        """
+        if not stats_fields:
+            stats_fields = [GeneralStatsField.MINUTES_PLAYED]
+
+        url = self.USERSTATS_URL + "/batch"
+        post_data = {
+            "arrangebyfield": "xuid",
+            "groups": [{"name": "Hero", "titleId": title_id}],
+            "stats": [dict(name=stat, titleId=title_id) for stat in stats_fields],
+            "xuids": xuids,
+        }
+        resp = await self.client.session.post(
+            url,
+            json=post_data,
+            headers=self.HEADERS_USERSTATS,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return UserStatsResponse(**resp.json())
+
+    async def get_stats_batch_by_scid(
+        self,
+        xuids: list[str],
+        service_config_id: str,
+        stats_fields: list[GeneralStatsField] | None = None,
+        **kwargs,
+    ) -> UserStatsResponse:
+        """
+        Get userstats in batch mode, via scid
+
+        Args:
+            xuids: List of XUIDs to get stats for
+            service_config_id: Service Config Id of Game (scid)
+            stats_fields: List of stats fields to acquire
+
+        Returns:
+            :class:`UserStatsResponse`: User Stats Response
+        """
+        if not stats_fields:
+            stats_fields = [GeneralStatsField.MINUTES_PLAYED]
+
+        url = self.USERSTATS_URL + "/batch"
+
+        post_data = {
+            "arrangebyfield": "xuid",
+            "groups": [{"name": "Hero", "scid": service_config_id}],
+            "stats": [dict(name=stat, scid=service_config_id) for stat in stats_fields],
+            "xuids": xuids,
+        }
+        resp = await self.client.session.post(
+            url,
+            json=post_data,
+            headers=self.HEADERS_USERSTATS,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return UserStatsResponse(**resp.json())

pythonxbox/api/provider/userstats/models.py

@@ -0,0 +1,44 @@
+from pythonxbox.common.models import LowerCaseModel, PascalCaseModel
+
+
+class GeneralStatsField:
+    MINUTES_PLAYED = "MinutesPlayed"
+
+
+class GroupProperties(PascalCaseModel):
+    ordinal: str | None = None
+    sort_order: str | None = None
+    display_name: str | None = None
+    display_format: str | None = None
+    display_semantic: str | None = None
+
+
+class Properties(PascalCaseModel):
+    display_name: str | None = None
+
+
+class Stat(LowerCaseModel):
+    group_properties: GroupProperties | None = None
+    xuid: str
+    scid: str
+    name: str
+    type: str
+    value: str
+    properties: Properties
+
+
+class StatListsCollectionItem(LowerCaseModel):
+    arrange_by_field: str
+    arrange_by_field_id: str
+    stats: list[Stat]
+
+
+class Group(LowerCaseModel):
+    name: str
+    title_id: str | None = None
+    statlistscollection: list[StatListsCollectionItem]
+
+
+class UserStatsResponse(LowerCaseModel):
+    groups: list[Group] | None = None
+    statlistscollection: list[StatListsCollectionItem]

pythonxbox/authentication/manager.py

@@ -0,0 +1,161 @@
+"""
+Authentication Manager
+
+Authenticate with Windows Live Server and Xbox Live.
+"""
+
+import logging
+
+import httpx
+
+from pythonxbox.authentication.models import (
+    OAuth2TokenResponse,
+    XAUResponse,
+    XSTSResponse,
+)
+from pythonxbox.common.exceptions import AuthenticationException
+from pythonxbox.common.signed_session import SignedSession
+
+log = logging.getLogger("authentication")
+
+DEFAULT_SCOPES = ["Xboxlive.signin", "Xboxlive.offline_access"]
+
+
+class AuthenticationManager:
+    def __init__(
+        self,
+        client_session: SignedSession,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        scopes: list[str] | None = None,
+    ) -> None:
+        if not isinstance(client_session, (SignedSession, httpx.AsyncClient)):
+            raise DeprecationWarning(
+                """Xbox WebAPI changed to use SignedSession (wrapped httpx.AsyncClient).
+                Please check the documentation"""
+            )
+
+        self.session: SignedSession = client_session
+        self._client_id: str = client_id
+        self._client_secret: str = client_secret
+        self._redirect_uri: str = redirect_uri
+        self._scopes: list[str] = scopes or DEFAULT_SCOPES
+
+        self.oauth: OAuth2TokenResponse = None
+        self.user_token: XAUResponse = None
+        self.xsts_token: XSTSResponse = None
+
+    def generate_authorization_url(self, state: str | None = None) -> str:
+        """Generate Windows Live Authorization URL."""
+        query_params = {
+            "client_id": self._client_id,
+            "response_type": "code",
+            "approval_prompt": "auto",
+            "scope": " ".join(self._scopes),
+            "redirect_uri": self._redirect_uri,
+        }
+
+        if state:
+            query_params["state"] = state
+
+        return str(
+            httpx.URL(
+                "https://login.live.com/oauth20_authorize.srf", params=query_params
+            )
+        )
+
+    async def request_tokens(self, authorization_code: str) -> None:
+        """Request all tokens."""
+        self.oauth = await self.request_oauth_token(authorization_code)
+        self.user_token = await self.request_user_token()
+        self.xsts_token = await self.request_xsts_token()
+
+    async def refresh_tokens(self) -> None:
+        """Refresh all tokens."""
+        if not (self.oauth and self.oauth.is_valid()):
+            self.oauth = await self.refresh_oauth_token()
+        if not (self.user_token and self.user_token.is_valid()):
+            self.user_token = await self.request_user_token()
+        if not (self.xsts_token and self.xsts_token.is_valid()):
+            self.xsts_token = await self.request_xsts_token()
+
+    async def request_oauth_token(self, authorization_code: str) -> OAuth2TokenResponse:
+        """Request OAuth2 token."""
+        return await self._oauth2_token_request(
+            {
+                "grant_type": "authorization_code",
+                "code": authorization_code,
+                "scope": " ".join(self._scopes),
+                "redirect_uri": self._redirect_uri,
+            }
+        )
+
+    async def refresh_oauth_token(self) -> OAuth2TokenResponse:
+        """Refresh OAuth2 token."""
+        return await self._oauth2_token_request(
+            {
+                "grant_type": "refresh_token",
+                "scope": " ".join(self._scopes),
+                "refresh_token": self.oauth.refresh_token,
+            }
+        )
+
+    async def _oauth2_token_request(self, data: dict) -> OAuth2TokenResponse:
+        """Execute token requests."""
+        data["client_id"] = self._client_id
+        if self._client_secret:
+            data["client_secret"] = self._client_secret
+        resp = await self.session.post(
+            "https://login.live.com/oauth20_token.srf", data=data
+        )
+        resp.raise_for_status()
+        return OAuth2TokenResponse(**resp.json())
+
+    async def request_user_token(
+        self,
+        relying_party: str = "http://auth.xboxlive.com",
+        use_compact_ticket: bool = False,
+    ) -> XAUResponse:
+        """Authenticate via access token and receive user token."""
+        url = "https://user.auth.xboxlive.com/user/authenticate"
+        headers = {"x-xbl-contract-version": "1"}
+        data = {
+            "RelyingParty": relying_party,
+            "TokenType": "JWT",
+            "Properties": {
+                "AuthMethod": "RPS",
+                "SiteName": "user.auth.xboxlive.com",
+                "RpsTicket": self.oauth.access_token
+                if use_compact_ticket
+                else f"d={self.oauth.access_token}",
+            },
+        }
+
+        resp = await self.session.post(url, json=data, headers=headers)
+        resp.raise_for_status()
+        return XAUResponse(**resp.json())
+
+    async def request_xsts_token(
+        self, relying_party: str = "http://xboxlive.com"
+    ) -> XSTSResponse:
+        """Authorize via user token and receive final X token."""
+        url = "https://xsts.auth.xboxlive.com/xsts/authorize"
+        headers = {"x-xbl-contract-version": "1"}
+        data = {
+            "RelyingParty": relying_party,
+            "TokenType": "JWT",
+            "Properties": {
+                "UserTokens": [self.user_token.token],
+                "SandboxId": "RETAIL",
+            },
+        }
+
+        resp = await self.session.post(url, json=data, headers=headers)
+        if resp.status_code == 401:  # if unauthorized
+            print(
+                "Failed to authorize you! Your password or username may be wrong or you are trying to use child account (< 18 years old)"
+            )
+            raise AuthenticationException()
+        resp.raise_for_status()
+        return XSTSResponse(**resp.json())